AutoSwarm-Shadow-Adapter

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

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

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

What is AutoSwarm-Shadow-Adapter?

AutoSwarm-shadow-adapter is a high-concurrency Temporal Bridge for AutoSwarm. It allows AutoSwarm 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.

1. Non-Blocking Intercept: Intercepts AutoSwarm 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 ["AutoSwarm 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[("AutoSwarm 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

1. Task Decomposing & Assignment: When a user launches an AutoSwarm session (e.g. opc chat --mode company "Build feature X"), AutoSwarm's Manager AI creates work items and assigns them to configured role seats (e.g., senior_developer, legal_counsel).
2. **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. AutoSwarm-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 AutoSwarm 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:

• Architecture Specification & Implementation Contracts
• Technical Lifecycle & Sequence Diagram
• State Machine Integration Diagram
• Database Schemas & Tables (shadow_tasks.db)

Configuration Reference

Development & Testing

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

# Run engine simulator demo
python tests/mock_AutoSwarm_engine.py

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

GitHub Repository | PyPI Package | Issue Tracker | Architecture Spec

Thanks for visiting 🖤 Build for AutoSwarm Community