What is OpenOPC-Shadow-Adapter?

openopc-shadow-adapter is a high-concurrency Temporal Bridge for OpenOPC. It allows OpenOPC agentic DAGs to pause non-blockingly when a role requires human sign-off (Carbon) or remote GPU execution (Silicon BYOC), without causing engine timeouts or stalling parallel branches.

• Non-Blocking Intercept: Intercepts OpenOPC task execution in <50ms, parks the task in an isolated SQLite WAL database, and releases execution threads immediately with AWAITING_HUMAN.
• Contractor & Silicon Worker Portal: Provides a dedicated, secure React 19 UI and REST API (shadow-serve) for human reviewers and remote workers (shadow-worker).
• Consolidated Corporate Brain: Automatically packages ancestor deliverables, structured markdown briefs (brief_md), and uploaded file artifacts (CorporateArtifacts) for downstream context inheritance.
• Canonical State Subordination: Resumes OpenOPC's native store.db state machine (delegationworkitems.phase) instantly when deliverables are submitted.
• Symbiotic Architecture: Functions as an independent, non-invasive extension that plugs into OpenOPC's external agent registry (ADAPTER_CLASSES["shadow"]) with zero core repository modifications.

Appoint AI Agents & Hybrid Employees to

Automate Freelance & Multiple Jobs (Overemployment Engine)

Augment Vacant or Overloaded Roles

Run Your Entire Business on AI Autopilot

Ensure Enterprise Regulatory Compliance

Feature Comparison

| Capability | Standard OpenOPC | OpenOPC + Shadow Adapter | |:---|:---|:---| | Human response time > 900s | Engine crash (timeout failure) | Zero timeouts (unlimited duration) | | System restart resilience | State lost | Persisted in isolated SQLite WAL DB | | Multi-user access control | Local user only | Multi-user queue with JWT auth | | File attachments | Text only | Up to 5 files, 50MB payload | | Audit log compliance | Basic engine log | Immutable timeline with user attribution | | Iterative rework loop | Manual intervention | Built-in rework_requested state transition |

How It Works

flowchart LR
    subgraph Engine ["OpenOPC Agentic DAG Engine"]
        DAG["Multi-Agent DAG Execution\n(Parallel AI Tasks)"]
    end
subgraph Adapter ["Shadow Mode Plugin"]         SA["ShadowModeAdapter\n(Non-blocking Intercept < 50ms)"]     end
subgraph Store ["Isolated Persistence"]         DB[("SQLite WAL Store\nshadow_tasks.db")]     end
subgraph Portal ["Human Operations"]         ReactApp["React 19 Human Portal\n(JWT Authenticated)"]         HumanReviewer["Human Contractor / Reviewer"]     end
subgraph ResumeLayer ["DAG Unblock & Resume"]         OPCStore[("OpenOPC Engine Store\nstore.db (WAL Mode)")]         UnblockNode(["Downstream DAG Nodes\nResume Automatically"])     end
DAG -->|1. Intercept human-backed task| SA     SA -->|2. Park task record| DB     SA -->|3. Return AWAITING_HUMAN and release thread| DAG     DB <-->|4. Query pending queue & Submit deliverable| ReactApp     HumanReviewer <-->|5. Review brief & attach files| ReactApp     ReactApp -->|6. Submit deliverable via REST API| SA     SA -->|7. Write Phase.APPROVED to store| OPCStore     OPCStore -->|8. Native Phase Hooks Trigger| UnblockNode

User Workflow & Execution Pipeline

• Task Decomposing & Assignment: When a user launches an OpenOPC session (e.g. opc chat --mode company "Build feature X"), OpenOPC's Manager AI creates work items and assigns them to configured role seats (e.g., seniordeveloper, legalcounsel).
• Shadow Intercept (<50ms): Any role assigned preferredexternalagent: shadow is intercepted by ShadowModeAdapter. The adapter parses project goals, compiles a markdown task brief (TaskBriefBuilder), parks a record in shadowtasks.db, and returns AWAITINGHUMAN to OpenOPC. Execution threads release immediately so parallel DAG tasks continue without timing out.
• Task Claiming:

• Deliverable Submission: The worker reviews upstream subagent context, writes solution notes, and attaches deliverable files (up to 5 files / 50MB payload cap). Files are indexed into CorporateArtifacts with SHA-256 integrity hashes.
• DAG Resumption: OpcResumeRepository updates delegationworkitems.phase in OpenOPC's host store.db. OpenOPC wakes downstream DAG nodes, passing the uploaded artifacts forward.

• 📖 Step-by-Step Execution Flow Walkthrough
• 🛠️ Detailed Implementation & Setup Guide
• 📜 Changelog & Compatibility Matrix

Symbiotic Integration & Quick Start

openopc-shadow-adapter is built to run as a true symbiont with OpenOPC. You can run the portal server embedded in your main Python process or as a standalone CLI sidecar.

Step 1: Install Package

pip install openopc-shadow-adapter

Step 2: Register & Launch Embedded (Zero Extra Commands)

In your main OpenOPC application entry point (e.g., main.py), register the adapter and launch the Human Portal server concurrently in a background thread:

# main.py (Your OpenOPC application entry point)
from opc.layer3agent.adapters.registry import ADAPTERCLASSES
from shadowadapter import ShadowModeAdapter, startserverinthread
1. Register "shadow" mode into OpenOPC's adapter registry
ADAPTER_CLASSES["shadow"] = ShadowModeAdapter
2. Launch Human Web Portal concurrently on port 8800 (single process)
startserverin_thread(port=8800)
3. Launch your OpenOPC DAG pipeline as normal!

Step 3: Configure Target Roles

In your OpenOPC organization config (.opc/config/companyorgs/companyconfig.yaml), set preferredexternalagent: shadow for human-backed roles:

# .opc/config/companyorgs/companyconfig.yaml
roles:
  legal_counsel:
    title: "Human Legal Counsel"
    execution_strategy: external
    preferredexternalagent: shadow  # <-- Intercepted by Shadow Adapter
senior_architect:     title: "Human Senior Architect"     execution_strategy: external     preferredexternalagent: shadow  # <-- Intercepted by Shadow Adapter

Alternative: Launch via CLI Sidecar

If you prefer running the Web Portal in a separate terminal or Docker container:

shadow-serve --port 8800

• React Human Web Portal: http://localhost:8800
• REST API Base: http://localhost:8800/api/v1

Distributed Silicon Workforce (Bring Your Own Compute - BYOC)

The shadow-worker daemon allows remote PCs, GPU workstations, and dedicated cloud nodes to act as specialized silicon employees. Each remote node runs its assigned role on its own local model or API key without modifying the central OpenOPC engine.

Launch Remote Compute Nodes (3-PC Distributed Example)

1. Remote GPU Workstation (Role: Senior Developer -> Local Ollama)

export OLLAMA_HOST="http://localhost:11434"
shadow-worker \
  --server-url "http://192.168.1.100:8800" \
  --username "devnode1" \
  --password "securepass1" \
  --role "senior_developer" \
  --provider "ollama" \
  --model "llama3.3:70b"

2. Remote Enterprise Server (Role: Legal Counsel -> Enterprise Claude API)

export LOCALANTHROPICKEY="sk-ant-api03-enterprise-key..."
shadow-worker \
  --server-url "http://192.168.1.100:8800" \
  --username "legalnode2" \
  --password "securepass2" \
  --role "legal_counsel" \
  --provider "anthropic" \
  --model "claude-3-5-sonnet-20241022"

3. Remote Tester Machine (Role: QA Tester -> OpenAI GPT-4o)

export LOCALOPENAIAPI_KEY="sk-proj-openai-key..."
shadow-worker \
  --server-url "http://192.168.1.100:8800" \
  --username "qanode3" \
  --password "securepass3" \
  --role "qa_tester" \
  --provider "openai" \
  --model "gpt-4o"

Programmatic Python SDK Usage

You can also embed ShadowWorker into custom Python pipelines on remote nodes:

import asyncio
from shadow_adapter import ShadowWorker
Custom task handler executing local agent pipeline
async def mylocalagent(task: dict) -> str:
    # Query your local GPU, private database, or custom agent model
    return f"Processed task '{task['title']}' on local node."
worker = ShadowWorker(     serverurl="http://192.168.1.100:8800",     username="customnode01",     password="password123",     role="legal_counsel",     customhandler=mylocal_agent, )

asyncio.run(worker.run_forever())

# Run full anti-fragility & host integration test suite (55 tests)
Enforces Concurrency, Property-Based Fuzzing, Black Hole Exception Trapping, and OpenOPC Host Mutation Survival
pytest tests/ -v --cov=shadow_adapter --cov-report=term-missing
Run engine simulator demo
python tests/mockopenopcengine.py