OpenOPC-Shadow-Adapter: Open Source Orchestration & Scheduling

What is OpenOPC-Shadow-Adapter?

OpenOPC-Shadow-Adapter is a zero-modification, MIT-licensed Python adapter that gives OpenOPC's agentic DAG runtime non-blocking human-in-the-loop sign-off and bring-your-own-compute execution, built for teams whose agent workflows need real people or remote machines in the loop without stalling the engine.

What it is

OpenOPC-Shadow-Adapter is a "temporal bridge" plugin for OpenOPC, the agentic DAG runtime in which a Manager AI decomposes a request into work items and assigns them to configured role seats such as senior_developer or legal_counsel. The adapter attaches to that runtime without modifying its core, presenting itself as a ShadowModeAdapter that sits between the DAG engine and the delivery of a task. Its FastAPI backend, SQLite WAL store, React 19 + Tailwind review portal and shadow-worker client together form a small service layer around an engine that otherwise has no notion of a pending human reviewer or a borrowed GPU.

The concrete problem it solves is the wait itself. In the default path shown in the project's comparison table, a task that needs a person ends in an engine timeout failure at the 900-second mark, in-flight state is lost on restart, only the local user can act, review is text-only, and rework requires manual intervention. The adapter intercepts the task, parks the record in an isolated database, returns AWAITING_HUMAN and releases the engine thread, so parallel DAG branches continue running while a reviewer or a remote worker takes as long as it takes.

Key capabilities

Non-blocking intercept through ShadowModeAdapter, which parks the task record and returns AWAITING_HUMAN instead of holding the engine thread.
Native phase hooks: on submission the adapter writes Phase.APPROVED to the OPCStore, which triggers OpenOPC's own hooks to fire UnblockNode and resume the DAG.
Restart resilience, with parked review state persisted in an isolated SQLite WAL database rather than held in memory.
A multi-user review queue with JWT authentication and bcrypt password hashing, replacing local-user-only access.
File attachments on deliverables, up to 5 files and a 50MB payload, instead of text-only review submissions.
An immutable audit timeline with user attribution, plus a built-in rework_requested state transition for iterative rework loops.
A shadow-worker CLI that enrolls a remote machine as a role seat using --server-url, --username, --role, --provider and --model, demonstrated with local Ollama (llama3.3:70b) and the enterprise Anthropic API.

Who uses it and how

Teams launching company-mode sessions such as opc chat --mode company "Build feature X", where the resulting work items land on role seats like legal_counsel and wait for a human sign-off rather than blocking the session.
Organisations that need documented human oversight of agent output, reviewed through the React 19 portal with per-user attribution in the audit timeline.
Groups with data-residency or compute constraints, who run shadow-worker on a remote node against a server on the local network (the README uses http://192.168.1.100:8800) with either a local Ollama model or an enterprise Claude key kept on that machine.
Operations with several reviewers, who rely on the multi-user queue and JWT authentication so that more than one person can pick up pending work.

Getting started

The package is published on PyPI as openopc-shadow-adapter for Python 3.10 and newer; after installing it, each human-backed or remote machine is enrolled by running the bundled shadow-worker CLI with its server URL, credentials, role, provider and model.

How it compares

The supplied facts name no rival adapter, bridge or alternative HITL product, so this entry stands alone in this registry rather than displacing a named commercial tool. The only comparison the material supports is internal to the ecosystem: the adapter against OpenOPC's own default wait path, where the adapter trades a 900-second timeout and lost state for unlimited-duration, persisted review.

When to use it — and when not

Choose it if you already run OpenOPC and need durable, multi-user sign-off or remote compute, and accept that you will operate a FastAPI service, a SQLite WAL database, a React portal, JWT account management and one shadow-worker process per borrowed machine. Do not pick it as a standalone orchestrator, since it is explicitly an adapter for OpenOPC and requires zero core modifications only because it depends on that core. Note also that this is a v0.1.0 production release whose 1,844 stars sit against a single fork, which suggests limited independent contribution or external validation so far, and the README is dense with badges and tables, making it slower to read than the workflow it describes.

project readme (upstream, from github) — read inline

OpenOPC-Shadow-Adapter

Non-Blocking Human-in-the-Loop (HITL) & BYOC Infrastructure for OpenOPC

AI Agent Employees For Your Compan -- The Carbon-Silicon Continuum: Real Humans & Remote PCs as First-Class OpenOPC Employees

Built for OpenOPC | Zero Core Modifications | Production Release v0.1.0

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 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-inrework_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., senior_developer, legal_counsel).
**Shadow Intercept ( Local Ollama)

export OLLAMA_HOST="http://localhost:11434"
shadow-worker \
  --server-url "[http://192.168.1.100:8800](http://192.168.1.100:8800)" \
  --username "dev_node_1" \
  --password "secure_pass_1" \
  --role "senior_developer" \
  --provider "ollama" \
  --model "llama3.3:70b"

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

export LOCAL_ANTHROPIC_KEY="sk-ant-api03-enterprise-key..."
shadow-worker \
  --server-url "[http://192.168.1.100:8800](http://192.168.1.100:8800)" \
  --username "legal_node_2" \
  --password "secure_pass_2" \
  --role "legal_counsel" \
  --provider "anthropic" \
  --model "claude-3-5-sonnet-20241022"

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

export LOCAL_OPENAI_API_KEY="sk-proj-openai-key..."
shadow-worker \
  --server-url "[http://192.168.1.100:8800](http://192.168.1.100:8800)" \
  --username "qa_node_3" \
  --password "secure_pass_3" \
  --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 my_local_agent(task: dict) -> str:
    # Query your local GPU, private database, or custom agent model
    return f"Processed task '{task['title']}' on local node."

worker = ShadowWorker(
    server_url="[http://192.168.1.100:8800](http://192.168.1.100:8800)",
    username="custom_node_01",
    password="password123",
    role="legal_counsel",
    custom_handler=my_local_agent,
)

asyncio.run(worker.run_forever())

The Consolidated Corporate Brain (Knowledge Graph)

A real company doesn't just pass text strings—employees share documents, reports, and data. openopc-shadow-adapter acts as the Central Nervous System for your AI and Human workforce by maintaining a centralized artifact registry.

1. The Shared Artifact Registry

When a Silicon or Carbon employee finishes a task, their deliverables (PDFs, CSVs, code files) are saved to the centralized CorporateArtifacts registry. This creates an indexed, searchable corporate memory for your entire DAG.

2. Hierarchical Context Injection

The adapter dynamically parses your OpenOPC company_config.yaml to understand your corporate hierarchy. When a downstream Manager receives a task to "Review the Analyst's work," the adapter automatically packages and injects the Analyst's upstream artifacts directly into the Manager's workspace (via the React Portal or the ShadowWorker API payload).

3. Role-Based Inheritance

Employees natively inherit the context of the workers below them. A Human Legal Director reviewing a contract doesn't just get a text summary—they are handed the exact .docx file the remote AI Drafter uploaded 5 minutes prior.

Architecture Deep-Dive

All detailed technical specifications are decoupled from this overview:

Configuration Reference

Variable	Default Value	Required	Description
`SHADOW_JWT_SECRET`	None	Yes	Secret key for signing JWT tokens (min 32 chars).
`SHADOW_DB_PATH`	`./shadow_tasks.db`	No	Path for the isolated Shadow SQLite database.
`SHADOW_OPC_STORE_PATH`	`.opc/projects/default/store.db`	No	Path to OpenOPC's `store.db` for WAL resume writes.
`SHADOW_UPLOAD_DIR`	`./shadow_uploads`	No	Directory for storing deliverable attachments.
`SHADOW_MAX_FILES_PER_SUBMISSION`	`5`	No	Max files permitted per submission.
`SHADOW_MAX_FILE_SIZE_MB`	`10`	No	Max allowed size per file in MB.
`SHADOW_MAX_TOTAL_UPLOAD_SIZE_MB`	`50`	No	Max total upload payload per submission in MB.
`SHADOW_API_PORT`	`8800`	No	Network port for FastAPI server and React SPA.

Development & Testing

# 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/mock_openopc_engine.py

OpenOPC-Shadow-Adapter | Non-Blocking Human-in-the-Loop Layer for OpenOPC

GitHub Repository | PyPI Package | Issue Tracker | Architecture Spec

Thanks for visiting 🖤 Build for OpenOPC Community

Frequently asked questions

Is OpenOPC-Shadow-Adapter free to use?

OpenOPC-Shadow-Adapter is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does OpenOPC-Shadow-Adapter do?

Zero-modification Human-in-the-Loop adapter for OpenOPC's agentic DAG runtime.

What is OpenOPC-Shadow-Adapter written in?

OpenOPC-Shadow-Adapter is primarily written in Python. Its source is publicly available at https://github.com/AhmadHassan-BTed/OpenOPC-Shadow-Adapter, and it has 1,844 GitHub stars.