![\"Network-AI](\"assets/demo.svg\")
\n\n \n
\n If Network-AI is useful to you, consider giving it a star ⭐ — it helps others find the project.\n
\n\nNetwork-AI is a TypeScript/Node.js multi-agent orchestrator that adds coordination, guardrails, and governance to any AI agent stack.\n\n- **Shared blackboard with locking** — atomic `propose → validate → commit` prevents race conditions and split-brain failures across parallel agents\n- **Guardrails and budgets** — FSM governance, per-agent token ceilings, HMAC / Ed25519 audit trails, and permission gating\n- **Context signal-over-noise (v5.15)** — `ContextComposer` assembles token-budgeted, relevance-ranked context packs (semantic/lexical × recency decay × scope affinity, position-aware layout); `context_pack` + `blackboard_search` MCP tools let agents pull curated state instead of dumping the whole board into their window\n- **32 adapters** — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, OpenAI Responses (Assistants successor), LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Custom (+ streaming), OpenClaw, A2A, Codex, MiniMax, NemoClaw, APS, Copilot, LangGraph, Anthropic Computer Use, Claude Agent SDK (agentic loops), OpenAI Agents SDK, Vertex AI, Gemini (Developer API), Pydantic AI, Browser Agent, Hermes (NousResearch Hermes / any OpenAI-compatible endpoint), Orchestrator (hierarchical multi-orchestrator), and RLM (Recursive Language Model / any RLM-compatible HTTP endpoint) — no glue code, no lock-in\n- **Persistent project memory (Layer 3)** — `context_manager.py` injects decisions, goals, stack, milestones, and banned patterns into every system prompt so agents always have full project context\n- **v5.0 modules** — Agent VCR (record/replay), comparison runner, coverage reporter, goal DSL, approval inbox, job queue, gRPC/HTTP transport, playground REPL, adapter test harness, and more\n- **Model-interaction lifecycle governance (v5.13)** — `GovernedModelGateway` absorbs the model refusal → fallback → billing chain (cross-model fallback, fallback-credit repricing, effort governance, thinking-block handoff) behind one governed, budgeted, audited call\n\n> **The silent failure mode in multi-agent systems:** parallel agents writing to the same key\n> use last-write-wins by default — one agent's result silently overwrites another's mid-flight.\n> The outcome is split-brain state: double-spends, contradictory decisions, corrupted context,\n> no error thrown. Network-AI's `propose → validate → commit` mutex prevents this at the\n> coordination layer, before any write reaches shared state.\n\n**Use Network-AI as:**\n- A **TypeScript/Node.js library** — `import { createSwarmOrchestrator } from 'network-ai'`\n- An **MCP server** — `npx network-ai-server --port 3001`\n- A **CLI** — `network-ai bb get status` / `network-ai audit tail`\n- A **Claude Code plugin** — `/plugin install network-ai@network-ai`\n- A **Gemini CLI extension** — `gemini extensions install https://github.com/Jovancoding/Network-AI`\n- An **OpenClaw skill** — `clawhub install network-ai`\n\n[**5-minute quickstart →**](QUICKSTART.md) | [**Architecture →**](ARCHITECTURE.md) | [**All adapters →**](#adapter-system) | [**Benchmarks →**](BENCHMARKS.md)\n\n---\n\n## 🛡️ Model-Interaction Lifecycle Governance\n\nMost governance tools stop at the agent boundary — they police which tools an agent may call *before* it acts. Network-AI also governs the layer underneath: **how an agent talks to the model.** When a frontier model declines a request with a classifier refusal, Network-AI absorbs the refusal → fallback → billing chain and presents one governed, budgeted, audited call.\n\n- **`GovernedModelGateway`** — detect `stop_reason:\"refusal\"`, audit which classifier fired, route to a fallback model, and redeem the fallback-credit token so the retry is repriced as a cache read.\n- **`ModelBudget`** — per-model USD accounting with fallback-credit repricing; never sums tokens across models.\n- **`RefusalTelemetry`** — a refusal is an HTTP 200, invisible to error-rate monitoring; emitted as a discrete non-error signal with an `unservedRefusalCount` gap to alert on.\n- **`EffortPolicy`** — turn the `effort` cost dial into a policy object: cap sub-agents at `low`, require justification for `xhigh`/`max`.\n- **`ThinkingBlockManager`** — keep thinking blocks unchanged on the same model; strip them on a cross-model fallback; guard prompts against `reasoning_extraction` refusals.\n- **Per-sub-agent fallback** — `FanOutFanIn` steps and `TeamRunner` tasks each carry their own fallback agent and per-request retry budget (`RetryBudget`), because a turn can refuse independently across an agent and its sub-agents.\n\n```typescript\nimport { AnthropicMessagesAdapter, ModelBudget, RefusalTelemetry } from 'network-ai';\n\nconst adapter = new AnthropicMessagesAdapter();\nawait adapter.initialize({});\nadapter.registerModelAgent('analyst', {\n client, // bring your own Anthropic client\n model: 'claude-fable-5',\n fallbackModels: ['claude-opus-4-8'], // classifier refusals fall through here\n budget: new ModelBudget({\n ceilingUsd: 5,\n pricing: {\n 'claude-fable-5': { inputPerMTok: 10, outputPerMTok: 50 },\n 'claude-opus-4-8': { inputPerMTok: 5, outputPerMTok: 25 },\n },\n }),\n telemetry: new RefusalTelemetry(),\n});\nconst result = await adapter.executeAgent('analyst', { action: 'Summarize Q3 results', params: {} }, { agentId: 'cli' });\n// result.data: { servedModel, servedByFallback, refused, refusalCategories, attempts, totalCostUsd }\n```\n\n### OWASP Agentic AI Top 10 (2026) — engine coverage\n\nVerify programmatically with `verifyOwaspCoverage()` (exported from `network-ai`):\n\n| Risk | Status | Primary control |\n|---|---|---|\n| ASI-01 Agent Goal Hijack | ✅ Covered | AuthGuardian gating + JourneyFSM control plane |\n| ASI-02 Tool Misuse & Exploitation | ✅ Covered | AgentRuntime SandboxPolicy + ApprovalGate |\n| ASI-03 Identity & Privilege Abuse | ✅ Covered | HMAC / Ed25519 signed tokens + trust scoring |\n| ASI-04 Supply Chain Risks | ✅ Covered | 1 runtime dep + socket / clawhub / codeql gates |\n| ASI-05 Unsafe Code Execution | ✅ Covered | ShellExecutor `shell:false` argv + path guards |\n| ASI-06 Memory & Context Poisoning | ✅ Covered | LockedBlackboard + injection detection |\n| ASI-07 Insecure Inter-Agent Comms | 🟡 Partial | FS-mutex + signed handoffs (local-trust boundary) |\n| ASI-08 Cascading Failures | ✅ Covered | CircuitBreaker + budgets + RetryBudget |\n| ASI-09 Human-Agent Trust Exploitation | ✅ Covered | ApprovalGate + tamper-evident audit trail |\n| ASI-10 Rogue Agents | ✅ Covered | ComplianceMonitor + circuit-breaker kill switch |\n\n---\n\n## ⚡ Try in 60 Seconds\n\n```bash\nnpm install network-ai\n```\n\n```typescript\nimport { LockedBlackboard } from 'network-ai';\n\nconst board = new LockedBlackboard('.');\nconst id = board.propose('status', { ready: true }, 'agent-1');\nboard.validate(id, 'agent-1');\nboard.commit(id);\n\nconsole.log(board.read('status')); // { ready: true }\n```\n\nTwo agents, atomic writes, no race conditions. That's it.\n\nWant the full stress test? **No API key, ~3 seconds:**\n\n```bash\nnpx ts-node examples/08-control-plane-stress-demo.ts\n```\n\nRuns priority preemption, AuthGuardian permission gating, FSM governance, and compliance monitoring — all without a single LLM call.\n\n> If it saves you from a race condition, a ⭐ helps others find it.\n\n---\n\n## What's Included\n\n| | |\n|---|---|\n| ✅ Atomic shared state | `propose → validate → commit` with filesystem mutex — no split-brain |\n| ✅ Token budgets | Hard per-agent ceilings with live spend tracking |\n| ✅ Permission gating | HMAC / Ed25519-signed tokens, scoped per agent and resource |\n| ✅ Append-only audit log | Every write, grant, and transition signed and logged |\n| ✅ 32 framework adapters | LangChain, CrewAI, AutoGen, MCP, Codex, Gemini, APS, RLM, and 24 more — zero lock-in |\n| ✅ FSM governance | Hard-stop agents at state boundaries, timeout enforcement |\n| ✅ Compliance monitoring | Real-time violation detection (tool abuse, turn-taking, timeouts) |\n| ✅ Claim verification | Tier 1 agent honesty — outcome-bound signed receipts, manifest reconciliation, trust decay for liars |\n| ✅ QA orchestration | Scenario replay, feedback loops, regression tracking, contradiction detection |\n| ✅ Deferred adapter init | Lazy-load adapters on first use — zero startup cost for unused frameworks |\n| ✅ Hook middleware | `beforeExecute` / `afterExecute` / `onError` hooks on any adapter call |\n| ✅ Flow control | Pause / resume / throttle writes on the blackboard |\n| ✅ Skill composition | `chain()` / `batch()` / `loop()` / `verify()` meta-operations over agent calls |\n| ✅ Semantic memory search | BYOE vector store with cosine similarity over blackboard data |\n| ✅ Phase pipeline | Multi-phase workflows with human-in-the-loop approval gates; `approvalTimeoutMs` fail-closed timeout prevents indefinite hangs |\n| ✅ Confidence filtering | Multi-agent result scoring, threshold validation, and consensus aggregation |\n| ✅ Matcher-based hooks | Glob patterns on agent/action/tool for targeted hook filtering |\n| ✅ Fan-out / fan-in | Parallel agent spawning with pluggable aggregation strategies |\n| ✅ Agent runtime sandbox | Sandboxed shell execution with policy enforcement and approval gates |\n| ✅ Interactive console | TUI dashboard for live monitoring, agent control, blackboard/budget/FSM management |\n| ✅ Pipe mode | JSON stdin/stdout protocol for programmatic AI-to-orchestrator control |\n| ✅ Strategy agent | Meta-orchestrator with elastic agent pools, workload partitioning, and adaptive scaling |\n| ✅ Goal decomposer | LLM-powered goal → task DAG → parallel execution with `runTeam()` one-liner |\n| ✅ Context Throttler | Prune blackboard keys per agent scope before LLM calls — prevent context pollution |\n| ✅ Partition Planner | Assign non-overlapping focus areas to agents before DAG execution — no redundant research |\n| ✅ Coverage Gate | Recursive refinement loop — re-run decomposer for gaps until coverage score ≥ threshold |\n| ✅ Route Classifier | Short-circuit routing — classify goals as factual lookup vs. complex synthesis before planning |\n| ✅ Goal DSL | YAML/JSON goal definitions with cycle detection and topological compilation |\n| ✅ Agent VCR | Record and replay LLM/agent interactions for deterministic tests |\n| ✅ Comparison runner | Side-by-side adapter comparison with scoring, timing, cost analysis |\n| ✅ Coverage reporter | V8 coverage collection with threshold enforcement |\n| ✅ Job queue | Persistent priority FIFO with retries, crash recovery, pluggable backends |\n| ✅ Approval inbox | Web-accessible approval queue with REST API and SSE streaming |\n| ✅ TTL auto-eviction | `purgeExpired()` on-demand eviction; `startSweep(intervalMs)` / `stopSweep()` background timer (unref'd, default 60 s) |\n| ✅ WAL crash recovery | `LockedBlackboard` Write-Ahead Log survives process crashes; `replayWAL()` replays uncommitted ops on restart; `compactWAL()` for manual truncation |\n| ✅ Circuit Breaker | `AdapterRegistry` per-adapter CLOSED/OPEN/HALF_OPEN state machine; `fallbackChain` for automatic failover; `CircuitOpenError`; zero added dependencies |\n| ✅ OTel telemetry hooks | `ITelemetryProvider` BYOT abstraction — `NullTelemetryProvider`, `CapturingTelemetryProvider`, `createOtelHooks()` factory; plug in any OTel SDK without modifying adapters |\n| ✅ Transport layer | JSON-RPC 2.0 over HTTP with HMAC auth, TTL, node allowlisting |\n| ✅ Playground REPL | Interactive sandbox with mock agents for rapid prototyping |\n| ✅ Adapter test harness | Parameterized test battery for any adapter implementation |\n| ✅ IAuthValidator | Interface to decouple authorization from concrete AuthGuardian |\n| ✅ Kill switch | `network-ai pause` / `resume` — `SYSTEM_PAUSED` sentinel; `doctor` self-diagnostics; `inspect