Network-AI

Network-AI

TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination

               

<p align="center"> <img src="assets/demo.svg" alt="Network-AI control-plane demo — atomic blackboard, priority preemption, AuthGuardian, FSM governance" width="720"> </p>

<p align="center"> <b>If Network-AI is useful to you, consider <a href="https://github.com/Jovancoding/Network-AI">giving it a star ⭐</a> — it helps others find the project.</b> </p>

Network-AI is a TypeScript/Node.js multi-agent orchestrator that adds coordination, guardrails, and governance to any AI agent stack.

• Shared blackboard with locking — atomic propose → validate → commit prevents race conditions and split-brain failures across parallel agents
• Guardrails and budgets — FSM governance, per-agent token ceilings, HMAC / Ed25519 audit trails, and permission gating
• 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
• 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
• 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
• 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
• 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

The silent failure mode in multi-agent systems: parallel agents writing to the same key use last-write-wins by default — one agent's result silently overwrites another's mid-flight. The outcome is split-brain state: double-spends, contradictory decisions, corrupted context, no error thrown. Network-AI's propose → validate → commit mutex prevents this at the coordination layer, before any write reaches shared state.

Use Network-AI as:

• A TypeScript/Node.js library — import { createSwarmOrchestrator } from 'network-ai'
• An MCP server — npx network-ai-server --port 3001
• A CLI — network-ai bb get status / network-ai audit tail
• A Claude Code plugin — /plugin install network-ai@network-ai
• A Gemini CLI extension — gemini extensions install https://github.com/Jovancoding/Network-AI
• An OpenClaw skill — clawhub install network-ai

5-minute quickstart → &nbsp;|&nbsp; Architecture → &nbsp;|&nbsp; All adapters → &nbsp;|&nbsp; Benchmarks →

---

🛡️ Model-Interaction Lifecycle Governance

Most 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.

• 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.
• ModelBudget — per-model USD accounting with fallback-credit repricing; never sums tokens across models.
• 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.
• EffortPolicy — turn the effort cost dial into a policy object: cap sub-agents at low, require justification for xhigh/max.
• ThinkingBlockManager — keep thinking blocks unchanged on the same model; strip them on a cross-model fallback; guard prompts against reasoning_extraction refusals.
• 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.

import { AnthropicMessagesAdapter, ModelBudget, RefusalTelemetry } from 'network-ai';

const adapter = new AnthropicMessagesAdapter();
await adapter.initialize({});
adapter.registerModelAgent('analyst', {
  client,                              // bring your own Anthropic client
  model: 'claude-fable-5',
  fallbackModels: ['claude-opus-4-8'], // classifier refusals fall through here
  budget: new ModelBudget({
    ceilingUsd: 5,
    pricing: {
      'claude-fable-5': { inputPerMTok: 10, outputPerMTok: 50 },
      'claude-opus-4-8': { inputPerMTok: 5, outputPerMTok: 25 },
    },
  }),
  telemetry: new RefusalTelemetry(),
});
const result = await adapter.executeAgent('analyst', { action: 'Summarize Q3 results', params: {} }, { agentId: 'cli' });
// result.data: { servedModel, servedByFallback, refused, refusalCategories, attempts, totalCostUsd }

OWASP Agentic AI Top 10 (2026) — engine coverage

Verify programmatically with verifyOwaspCoverage() (exported from network-ai):

| Risk | Status | Primary control | |---|---|---| | ASI-01 Agent Goal Hijack | ✅ Covered | AuthGuardian gating + JourneyFSM control plane | | ASI-02 Tool Misuse & Exploitation | ✅ Covered | AgentRuntime SandboxPolicy + ApprovalGate | | ASI-03 Identity & Privilege Abuse | ✅ Covered | HMAC / Ed25519 signed tokens + trust scoring | | ASI-04 Supply Chain Risks | ✅ Covered | 1 runtime dep + socket / clawhub / codeql gates | | ASI-05 Unsafe Code Execution | ✅ Covered | ShellExecutor shell:false argv + path guards | | ASI-06 Memory & Context Poisoning | ✅ Covered | LockedBlackboard + injection detection | | ASI-07 Insecure Inter-Agent Comms | 🟡 Partial | FS-mutex + signed handoffs (local-trust boundary) | | ASI-08 Cascading Failures | ✅ Covered | CircuitBreaker + budgets + RetryBudget | | ASI-09 Human-Agent Trust Exploitation | ✅ Covered | ApprovalGate + tamper-evident audit trail | | ASI-10 Rogue Agents | ✅ Covered | ComplianceMonitor + circuit-breaker kill switch |

---

⚡ Try in 60 Seconds

npm install network-ai

import { LockedBlackboard } from 'network-ai';

const board = new LockedBlackboard('.');
const id    = board.propose('status', { ready: true }, 'agent-1');
board.validate(id, 'agent-1');
board.commit(id);

console.log(board.read('status'));  // { ready: true }

Two agents, atomic writes, no race conditions. That's it.

Want the full stress test? No API key, ~3 seconds:

npx ts-node examples/08-control-plane-stress-demo.ts

Runs priority preemption, AuthGuardian permission gating, FSM governance, and compliance monitoring — all without a single LLM call.

If it saves you from a race condition, a ⭐ helps others find it.

---

What's Included

| | | |---|---| | ✅ Atomic shared state | propose → validate → commit with filesystem mutex — no split-brain | | ✅ Token budgets | Hard per-agent ceilings with live spend tracking | | ✅ Permission gating | HMAC / Ed25519-signed tokens, scoped per agent and resource | | ✅ Append-only audit log | Every write, grant, and transition signed and logged | | ✅ 32 framework adapters | LangChain, CrewAI, AutoGen, MCP, Codex, Gemini, APS, RLM, and 24 more — zero lock-in | | ✅ FSM governance | Hard-stop agents at state boundaries, timeout enforcement | | ✅ Compliance monitoring | Real-time violation detection (tool abuse, turn-taking, timeouts) | | ✅ Claim verification | Tier 1 agent honesty — outcome-bound signed receipts, manifest reconciliation, trust decay for liars | | ✅ QA orchestration | Scenario replay, feedback loops, regression tracking, contradiction detection | | ✅ Deferred adapter init | Lazy-load adapters on first use — zero startup cost for unused frameworks | | ✅ Hook middleware | beforeExecute / afterExecute / onError hooks on any adapter call | | ✅ Flow control | Pause / resume / throttle writes on the blackboard | | ✅ Skill composition | chain() / batch() / loop() / verify() meta-operations over agent calls | | ✅ Semantic memory search | BYOE vector store with cosine similarity over blackboard data | | ✅ Phase pipeline | Multi-phase workflows with human-in-the-loop approval gates; approvalTimeoutMs fail-closed timeout prevents indefinite hangs | | ✅ Confidence filtering | Multi-agent result scoring, threshold validation, and consensus aggregation | | ✅ Matcher-based hooks | Glob patterns on agent/action/tool for targeted hook filtering | | ✅ Fan-out / fan-in | Parallel agent spawning with pluggable aggregation strategies | | ✅ Agent runtime sandbox | Sandboxed shell execution with policy enforcement and approval gates | | ✅ Interactive console | TUI dashboard for live monitoring, agent control, blackboard/budget/FSM management | | ✅ Pipe mode | JSON stdin/stdout protocol for programmatic AI-to-orchestrator control | | ✅ Strategy agent | Meta-orchestrator with elastic agent pools, workload partitioning, and adaptive scaling | | ✅ Goal decomposer | LLM-powered goal → task DAG → parallel execution with runTeam() one-liner | | ✅ Context Throttler | Prune blackboard keys per agent scope before LLM calls — prevent context pollution | | ✅ Partition Planner | Assign non-overlapping focus areas to agents before DAG execution — no redundant research | | ✅ Coverage Gate | Recursive refinement loop — re-run decomposer for gaps until coverage score ≥ threshold | | ✅ Route Classifier | Short-circuit routing — classify goals as factual lookup vs. complex synthesis before planning | | ✅ Goal DSL | YAML/JSON goal definitions with cycle detection and topological compilation | | ✅ Agent VCR | Record and replay LLM/agent interactions for deterministic tests | | ✅ Comparison runner | Side-by-side adapter comparison with scoring, timing, cost analysis | | ✅ Coverage reporter | V8 coverage collection with threshold enforcement | | ✅ Job queue | Persistent priority FIFO with retries, crash recovery, pluggable backends | | ✅ Approval inbox | Web-accessible approval queue with REST API and SSE streaming | | ✅ TTL auto-eviction | purgeExpired() on-demand eviction; startSweep(intervalMs) / stopSweep() background timer (unref'd, default 60 s) | | ✅ WAL crash recovery | LockedBlackboard Write-Ahead Log survives process crashes; replayWAL() replays uncommitted ops on restart; compactWAL() for manual truncation | | ✅ Circuit Breaker | AdapterRegistry per-adapter CLOSED/OPEN/HALF_OPEN state machine; fallbackChain for automatic failover; CircuitOpenError; zero added dependencies | | ✅ OTel telemetry hooks | ITelemetryProvider BYOT abstraction — NullTelemetryProvider, CapturingTelemetryProvider, createOtelHooks() factory; plug in any OTel SDK without modifying adapters | | ✅ Transport layer | JSON-RPC 2.0 over HTTP with HMAC auth, TTL, node allowlisting | | ✅ Playground REPL | Interactive sandbox with mock agents for rapid prototyping | | ✅ Adapter test harness | Parameterized test battery for any adapter implementation | | ✅ IAuthValidator | Interface to decouple authorization from concrete AuthGuardian | | ✅ Kill switch | network-ai pause / resume — SYSTEM_PAUSED sentinel; doctor self-diagnostics; inspect <key> metadata + audit trail | | ✅ Minimal mode | --minimal / NETWORK_AI_MINIMAL=1 — skips WAL replay and sweep for fast CI/test startup | | ✅ TypeScript native | ES2022 strict mode, zero native dependencies |

---

Why teams use Network-AI

| Problem | How Network-AI solves it | |---|---| | Race conditions in parallel agents | Atomic blackboard: propose → validate → commit with file-system mutex | | Agent overspend / runaway costs | FederatedBudget — hard per-agent token ceilings with live spend tracking | | No visibility into what agents did | HMAC / Ed25519-signed audit log on every write, permission grant, and FSM transition | | Locked into one AI framework | 32 adapters — mix LangChain + AutoGen + CrewAI + Codex + Gemini + MiniMax + NemoClaw + APS + LangGraph + Vertex AI + Hermes + RLM + custom in one swarm | | Agents escalating beyond their scope | AuthGuardian — scoped permission tokens required before sensitive operations | | Agents lack project context between runs | ProjectContextManager (Layer 3) — inject decisions, goals, stack, and milestones into every system prompt | | No regression tracking on agent output quality | QAOrchestratorAgent — scenario replay, feedback loops, cross-agent contradiction detection, historical trend tracking |

---

Architecture

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#1e293b', 'primaryTextColor': '#e2e8f0', 'primaryBorderColor': '#475569', 'lineColor': '#94a3b8', 'clusterBkg': '#0f172a', 'clusterBorder': '#334155', 'edgeLabelBackground': '#1e293b', 'edgeLabelColor': '#cbd5e1', 'titleColor': '#e2e8f0'}}}%%
flowchart TD
    classDef app        fill:#1e3a5f,stroke:#3b82f6,color:#bfdbfe,font-weight:bold
    classDef security   fill:#451a03,stroke:#d97706,color:#fde68a
    classDef routing    fill:#14532d,stroke:#16a34a,color:#bbf7d0
    classDef quality    fill:#3b0764,stroke:#9333ea,color:#e9d5ff
    classDef blackboard fill:#0c4a6e,stroke:#0284c7,color:#bae6fd
    classDef adapters   fill:#064e3b,stroke:#059669,color:#a7f3d0
    classDef audit      fill:#1e293b,stroke:#475569,color:#94a3b8

    App["Your Application"]:::app
    App -->|"createSwarmOrchestrator()"| SO

    subgraph SO["SwarmOrchestrator"]
        AG["AuthGuardian\n(HMAC / Ed25519 permission tokens)"]:::security
        AR["AdapterRegistry\n(route tasks to frameworks)"]:::routing
        QG["QualityGateAgent\n(validate blackboard writes)"]:::quality
        QA["QAOrchestratorAgent\n(scenario replay, regression tracking)"]:::quality
        BB["SharedBlackboard\n(shared agent state)\npropose → validate → commit\nfilesystem mutex"]:::blackboard
        AD["Adapters — plug any framework in, swap freely\nLangChain · AutoGen · CrewAI · MCP · LlamaIndex · …"]:::adapters

        AG -->|"grant / deny"| AR
        AR -->|"tasks dispatched"| AD
        AD -->|"writes results"| BB
        QG -->|"validates"| BB
        QA -->|"orchestrates"| QG
    end

    SO --> AUDIT["data/audit_log.jsonl\n(HMAC / Ed25519-signed)"]:::audit

FederatedBudget is a standalone export — instantiate it separately and optionally wire it to a blackboard backend for cross-node token budget enforcement. ProjectContextManager is a Layer-3 Python helper (scripts/context_manager.py) that injects persistent project goals, decisions, and milestones into agent system prompts — see ARCHITECTURE.md § Layer 3.

→ Full architecture, FSM journey, and handoff protocol

---

Install

npm install network-ai

No native dependencies, no build step. Adapters are dependency-free (BYOC — bring your own client).

---

Use as MCP Server

Start the server (no config required, zero dependencies):

npx network-ai-server --port 3001
# or from source:
npx ts-node bin/mcp-server.ts --port 3001

Then wire any MCP-compatible client to it.

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "network-ai": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Cursor / Cline / any SSE-based MCP client — point to the same URL:

{
  "mcpServers": {
    "network-ai": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Verify it's running:

curl http://localhost:3001/health   # { "status": "ok", "tools": <n>, "uptime": <ms> }
curl http://localhost:3001/tools    # full tool list

Tools exposed over MCP:

• blackboard_read / blackboard_write / blackboard_list / blackboard_delete / blackboard_exists
• context_pack — token-budgeted, relevance-ranked context brief for a task (use instead of dumping the whole board into your window)
• blackboard_search — ranked top-K search over blackboard entries (semantic when an embedder is wired, lexical otherwise)
• budget_status / budget_spend / budget_reset — federated token tracking
• token_create / token_validate / token_revoke — HMAC / Ed25519-signed permission tokens
• audit_query — query the append-only audit log
• config_get / config_set — live orchestrator configuration
• agent_list / agent_spawn / agent_stop — agent lifecycle
• fsm_transition — write FSM state transitions to the blackboard

Each tool takes an agent_id parameter — all writes are identity-verified and namespace-scoped, exactly as they are in the TypeScript API.

Options: --no-budget, --no-token, --no-control, --ceiling <n>, --board <name>, --audit-log <path>.

---

Use as a Claude Code Plugin

Network-AI ships as a Claude Code plugin — the MCP server wires in automatically, so every tool listed above becomes available inside Claude Code with no manual config.

Install from the self-hosted marketplace (zero approval needed):

/plugin marketplace add Jovancoding/Network-AI
/plugin install network-ai@network-ai

That's it — blackboard_read, budget_status, audit_query, token_create, and the rest load as native Claude Code tools. Under the hood the plugin runs npx -y -p network-ai network-ai-server --stdio (stdio MCP transport), so it always uses the published npm package.

The repo root carries the standard plugin layout:

| File | Role | |---|---| | .claude-plugin/plugin.json | Plugin manifest | | .mcp.json | Registers the Network-AI MCP server (stdio) | | .claude-plugin/marketplace.json | Self-hosted marketplace catalog | | commands/ | Slash commands — /network-ai:status, /network-ai:budget, /network-ai:audit, /network-ai:blackboard |

Validate the manifests locally with claude plugin validate ..

Gate Claude Code itself with AuthGuardian (hooks). Every tool call Claude Code makes — shell commands, file edits, web fetches — can be audited and permission-gated through the same weighted scoring (justification 40%, trust 30%, risk 30%) Network-AI applies to swarm agents:

// .claude/settings.json — see examples/claude-code-hooks.json for the full config
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash|Write|Edit|WebFetch",
      "hooks": [{ "type": "command",
                  "command": "npx -y -p network-ai network-ai hook pre-tool-use --mode enforce" }]
    }]
  }
}

--mode observe (default) audits every call to data/hooks_audit.jsonl without blocking; --mode enforce maps tools to resource types (Bash → SHELL_EXEC, Write/Edit → FILE_SYSTEM, WebFetch → EXTERNAL_SERVICE) and requires an AuthGuardian grant — denied calls escalate to you as an interactive prompt. --deny "rm -rf" patterns hard-block regardless of mode.

---

Use with OpenAI Codex

Network-AI also runs as an OpenAI Codex MCP server — in both the Codex CLI and the IDE extension. The same tools that load in Claude Code become available in Codex.

Add it with one command (uses the published npm package):

codex mcp add network-ai -- npx -y -p network-ai network-ai-server --stdio

In the Codex TUI, run /mcp to confirm network-ai is connected.

Or scope it to a project — the repo root ships a .codex/config.toml so any trusted checkout picks the server up automatically. To register it globally instead, drop the same block into ~/.codex/config.toml:

[mcp_servers.network-ai]
command = "npx"
args = ["-y", "-p", "network-ai", "network-ai-server", "--stdio"]

Either route exposes the full tool set (blackboard_read, budget_status, audit_query, token_create, …) over stdio MCP — no API keys, no running server to manage.

---

Use with Gemini CLI

Network-AI ships as a Gemini CLI extension — the repo root carries gemini-extension.json, which wires in the stdio MCP server and a GEMINI.md context file automatically:

gemini extensions install https://github.com/Jovancoding/Network-AI

Or register just the MCP server directly:

gemini mcp add network-ai npx -- -y -p network-ai network-ai-server --stdio

Run /mcp inside Gemini CLI to confirm the network-ai tools are loaded. For building Gemini-powered swarm agents, use the GeminiAdapter (Gemini Developer API / AI Studio) or VertexAIAdapter (Vertex AI on GCP) — and for Google's Agent2Agent ecosystem, A2AServer exposes this orchestrator as a discoverable A2A agent:

import { A2AServer } from 'network-ai';

const a2a = new A2AServer({
  name: 'Network-AI Orchestrator',
  secret: process.env.A2A_SECRET,
  executor: async (text) => ({ text: await runSwarmTask(text) }),
});
a2a.startServer(4310); // serves /.well-known/agent.json + tasks/send

---

CLI

Control Network-AI directly from the terminal — no server required. The CLI imports the same core engine used by the MCP server.

# One-off commands (no server needed)
npx ts-node bin/cli.ts bb set status running --agent cli
npx ts-node bin/cli.ts bb get status
npx ts-node bin/cli.ts bb snapshot

# After npm install -g network-ai:
network-ai bb list
network-ai audit tail          # live-stream the audit log
network-ai auth token my-bot --resource blackboard

| Command group | What it controls | |---|---| | network-ai bb | Blackboard — get, set, delete, list, snapshot, propose, commit, abort | | network-ai auth | AuthGuardian — issue tokens (--why for scoring breakdown), revoke, check permissions | | network-ai budget | FederatedBudget — spend status, set ceiling | | network-ai audit | Audit log — print, live-tail, clear | | network-ai env | Environment management — init, list, chain, diff, promote, backup, restore | | network-ai doctor | Self-diagnostics — validate data dir, env routing, audit log, WAL, kill-switch, MCP secret | | network-ai inspect <key> | Inspect a blackboard key — value, metadata, pending history, audit trail | | network-ai pause / resume | Kill switch — write/remove SYSTEM_PAUSED sentinel |

Global flags on every command: --data <path> (data directory, default ./data) · --env <name> (environment) · --json (machine-readable output) · --minimal (skip WAL replay + sweep — CI/test fast startup)

→ Full reference in QUICKSTART.md § CLI

---

Two agents, one shared state — without race conditions

The real differentiator is coordination. Here is what no single-framework solution handles: two agents writing to the same resource concurrently, atomically, without corrupting each other.

import { LockedBlackboard, CustomAdapter, createSwarmOrchestrator } from 'network-ai';

const board   = new LockedBlackboard('.');
const adapter = new CustomAdapter();

// Agent 1: writes its analysis result atomically
adapter.registerHandler('analyst', async () => {
  const id = board.propose('report:status', { phase: 'analysis', complete: true }, 'analyst');
  board.validate(id, 'analyst');
  board.commit(id);                           // file-system mutex — no race condition possible
  return { result: 'analysis written' };
});

// Agent 2: runs concurrently, writes to its own key safely
adapter.registerHandler('reviewer', async () => {
  const id = board.propose('report:review', { approved: true }, 'reviewer');
  board.validate(id, 'reviewer');
  board.commit(id);
  const analysis = board.read('report:status');
  return { result: `reviewed phase=${analysis?.phase}` };
});

createSwarmOrchestrator({ adapters: [{ adapter }] });

// Both fire concurrently — mutex guarantees no write is ever lost
const [, ] = await Promise.all([
  adapter.executeAgent('analyst',  { action: 'run', params: {} }, { agentId: 'analyst' }),
  adapter.executeAgent('reviewer', { action: 'run', params: {} }, { agentId: 'reviewer' }),
]);

console.log(board.read('report:status'));   // { phase: 'analysis', complete: true }
console.log(board.read('report:review'));   // { approved: true }

Add budgets, permissions, and cross-framework agents with the same pattern. → QUICKSTART.md

---

Demo — Control-Plane Stress Test (no API key)

Runs in ~3 seconds. Proves the coordination primitives without any LLM calls.

npm run demo -- --08

What it shows: atomic blackboard locking, priority preemption (priority-3 wins over priority-0 on same key), AuthGuardian permission gate (blocked → justified → granted with token), FSM hard-stop at 700 ms, live compliance violation capture (TOOL_ABUSE, TURN_TAKING, RESPONSE_TIMEOUT, JOURNEY_TIMEOUT), and FederatedBudget tracking — all without a single API call.


8-agent AI pipeline (requires OPENAI_API_KEY — builds a Payment Processing Service end-to-end):

npm run demo -- --07


NemoClaw sandbox swarm (no API key) — 3 agents in isolated NVIDIA NemoClaw sandboxes with deny-by-default network policies:

npx ts-node examples/10-nemoclaw-sandbox-swarm.ts


---

Adapter System

32 adapters, zero adapter dependencies. You bring your own SDK objects.

| Adapter | Framework / Protocol | Register method | |---|---|---| | CustomAdapter | Any function or HTTP endpoint | registerHandler(name, fn) | | LangChainAdapter | LangChain | registerAgent(name, runnable) | | AutoGenAdapter | AutoGen / AG2 | registerAgent(name, agent) | | CrewAIAdapter | CrewAI | registerAgent or registerCrew | | MCPAdapter | Model Context Protocol | registerTool(name, handler) | | LlamaIndexAdapter | LlamaIndex | registerQueryEngine(), registerChatEngine() | | SemanticKernelAdapter | Microsoft Semantic Kernel | registerKernel(), registerFunction() | | OpenAIAssistantsAdapter | OpenAI Assistants | registerAssistant(name, config) | | HaystackAdapter | deepset Haystack | registerPipeline(), registerAgent() | | DSPyAdapter | Stanford DSPy | registerModule(), registerProgram() | | AgnoAdapter | Agno (formerly Phidata) | registerAgent(), registerTeam() | | OpenClawAdapter | OpenClaw | registerSkill(name, skillRef) | | A2AAdapter | Google A2A Protocol | registerRemoteAgent(name, url) | | CodexAdapter | OpenAI Codex / gpt-4o / Codex CLI | registerCodexAgent(name, config) | | MiniMaxAdapter | MiniMax LLM API (M2.5 / M2.5-highspeed) | registerAgent(name, config) | | NemoClawAdapter | NVIDIA NemoClaw (sandboxed agents via OpenShell) | registerSandboxAgent(name, config) | | APSAdapter | Agent Permission Service (delegation-chain trust) | apsDelegationToTrust(delegation) | | CopilotAdapter | GitHub Copilot (generate/review/explain/fix/test/refactor/chat) | registerAgent(name, config) | | LangGraphAdapter | LangGraph (compiled StateGraph) | registerGraph(name, graph) | | AnthropicComputerUseAdapter | Anthropic Computer Use (screenshot/click/type/scroll) | registerAgent(name, config) | | OpenAIAgentsAdapter | OpenAI Agents SDK (tool use, handoffs, guardrails) | registerAgent(name, runner) | | VertexAIAdapter | Google Vertex AI / Gemini (function calling, multi-modal) | registerAgent(name, config) | | PydanticAIAdapter | Pydantic AI (structured output, validation, deps injection) | registerAgent(name, config) | | BrowserAgentAdapter | Browser automation (Playwright/Puppeteer/CDP) | registerAgent(name, driver) | | HermesAdapter | NousResearch Hermes / any OpenAI-compatible endpoint (Ollama, Together AI, Fireworks, llama.cpp) | registerAgent(name, config) | | OrchestratorAdapter | Hierarchical multi-orchestrator coordination | registerOrchestrator(id, orchestrator) | | RLMAdapter | Recursive Language Model / any RLM-compatible HTTP endpoint (arxiv 2512.24601) | registerAgent(name, config) |

Streaming variants (drop-in replacements with .stream() support):

| Adapter | Extends | Streaming source | |---|---|---| | LangChainStreamingAdapter | LangChainAdapter | Calls .stream() on the Runnable if available; falls back to .invoke() | | CustomStreamingAdapter | CustomAdapter | Pipes AsyncIterable<string> handlers; falls back to single-chunk for plain Promises |

Extend BaseAdapter (or StreamingBaseAdapter for streaming) to add your own in minutes. See references/adapter-system.md.

---

Works with LangGraph, CrewAI, and AutoGen

Network-AI is the coordination layer you add on top of your existing stack. Keep your LangChain chains, CrewAI crews, and AutoGen agents — and add shared state, governance, and budgets around them.

| Capability | Network-AI | LangGraph | CrewAI | AutoGen | |---|---|---|---|---| | Cross-framework agents in one swarm | ✅ 29 built-in adapters | ⚠️ Nodes can call any code; no adapter abstraction | ⚠️ Extensible via tools; CrewAI-native agents only | ⚠️ Extensible via plugins; AutoGen-native agents only | | Atomic shared state (conflict-safe) | ✅ propose → validate → commit mutex | ⚠️ State passed between nodes; last-write-wins | ⚠️ Shared memory available; no conflict resolution | ⚠️ Shared context available; no conflict resolution | | Hard token ceiling per agent | ✅ FederatedBudget (first-class API) | ⚠️ Via callbacks / custom middleware | ⚠️ Via callbacks / custom middleware | ⚠️ Built-in token tracking in v0.4+; no swarm-level ceiling | | Permission gating before sensitive ops | ✅ AuthGuardian (built-in) | ⚠️ Possible via custom node logic | ⚠️ Possible via custom tools | ⚠️ Possible via custom middleware | | Append-only audit log | ✅ plain JSONL (data/audit_log.jsonl) | ⚠️ Not built-in | ⚠️ Not built-in | ⚠️ Not built-in | | Encryption at rest | ✅ AES-256-GCM (TypeScript layer) | ⚠️ Not built-in | ⚠️ Not built-in | ⚠️ Not built-in | | Language | TypeScript / Node.js | Python | Python | Python |

---

Testing

npm run test:all          # All suites in sequence
npm test                  # Core orchestrator
npm run test:security     # Security module
npm run test:adapters     # All 32 adapters
npm run test:streaming    # Streaming adapters
npm run test:a2a          # A2A protocol adapter
npm run test:codex        # Codex adapter
npm run test:priority     # Priority & preemption
npm run test:cli          # CLI layer
npm run test:phase9       # Agent runtime, console, strategy agent
npm run test:phase12      # Context Throttler, Partition Planner, Coverage Gate, Route Classifier

3,638 passing assertions across 41 test suites (npm run test:all):

| Suite | Assertions | Covers | |---|---|---| | test-phase4.ts | 147 | FSM governance, compliance monitor, adapter integration | | test-phase5f.ts | 127 | SSE transport, McpCombinedBridge, extended MCP tools | | test-phase5g.ts | 121 | CRDT backend, vector clocks, bidirectional sync | | test-phase6.ts | 129 | MCP server, control-plane tools, audit tools | | test-adapters.ts | 271 | All 32 adapters, registry routing, integration, edge cases | | test-phase5d.ts | 117 | Pluggable backend (Redis, CRDT, Memory) | | test-standalone.ts | 88 | Blackboard, auth, integration, persistence, parallelisation, quality gate | | test-phase5e.ts | 87 | Federated budget tracking | | test-phase5c.ts | 73 | Named multi-blackboard, isolation, backend options | | test-codex.ts | 51 | Codex adapter: chat, completion, CLI, BYOC client, error paths | | test-minimax.ts | 50 | MiniMax adapter: lifecycle, registration, chat mode, temperature clamping | | test-nemoclaw.ts | 93 | NemoClaw adapter: sandbox lifecycle, policies, blueprint, handoff, env forwarding | | test-priority.ts | 64 | Priority preemption, conflict resolution, backward compat | | test-a2a.ts | 35 | A2A protocol: register, execute, mock fetch, error paths | | test-streaming.ts | 32 | Streaming adapters, chunk shapes, fallback, collectStream | | test-phase5b.ts | 55 | Pluggable backend part 2, consistency levels | | test-phase5.ts | 42 | Named multi-blackboard base | | test-security.ts | 34 | Tokens, sanitization, rate limiting, encryption, audit | | test-cli.ts | 65 | CLI layer: bb, auth, budget, audit commands | | test-qa.ts | 67 | QA orchestrator: scenarios, feedback loop, regression, contradictions | | test-phase7.ts | 94 | Deferred init, hook middleware, flow control, skill composer, semantic search | | test-phase8.ts | 146 | Phase pipeline, confidence filter, matcher-based hooks, fan-out/fan-in | | test-phase9.ts | 293 | Agent runtime, sandbox policy, shell executor, file accessor, approval gate, console UI, orchestrator wiring, pipe mode, strategy agent | | test-phase10.ts | 153 | Goal decomposer, task DAG validation, topological layers, JSON parsing, team runner, concurrency, timeouts, events, runTeam one-liner, dependency injection, LLM planner | | test-phase11.ts | 55 | TTL background sweep, WAL crash recovery, CircuitBreaker, ITelemetryProvider / OTel hooks | | test-topology.ts | 304 | WorkTree, ControlPlane, dashboard server, topology visualization, WebSocket protocol | | test-rlm-phases.ts | 123 | FederatedBudget child spending, blackboard metadata API, best-partial result, HookContext depth, sub-goal recursion, semaphore fan-out, PhasePipeline compaction, RLMAdapter end-to-end | | test-phase12.ts | 65 | Context Throttler, Partition Planner, Coverage Gate, Route Classifier, EVALUATING FSM state, runTeam integration | | test-env-manager.ts | 77 | Multi-environment isolation, promotion chain, backup/restore, source protection, NETWORK_AI_ENV, blackboard env routing | | test-transport.ts | 117 | Basis transport tier: TransportAgent state machine, LandscapeAgent health tracking, AgentPool drain/pause, fleet coordination, canary, rollback | | test-claim-verifier.ts | 50 | ClaimVerifier: receipt generation/tamper/expiry, corroborated/unsupported/undisclosed, trust decay/reset/DoS protection | | test-phase13.ts | 58 | ESM dual-build config, McpStreamableServer dispatch + resources + prompts, PhasePipeline checkpoint/resume/clear, SemanticMemory save/load/autoSave/clearPersisted | | test-phase14.ts | 52 | Model lifecycle governance: GovernedModelGateway refusal→fallback, ModelBudget credit repricing, RefusalTelemetry, Anthropic Messages adapter | | test-phase15.ts | 32 | Orchestration resilience: RetryBudget, per-sub-agent fallback in FanOutFanIn + TeamRunner, EffortPolicy | | test-phase16.ts | 21 | ThinkingBlockManager lifecycle + reasoning-extraction guard, OWASP Agentic Top 10 coverage matrix | | test-phase17.ts | 13 | ApprovalInbox GHSA-m4jg-6w3q-gm86 fix: read-route auth gating, token validation, backward compatibility, CORS allowlist | | test-phase18.ts | 85 | ClaudeHookBridge observe/enforce gating, MCP elicitation channel + fail-closed approval callback, A2AServer agent card / tasks / auth / eviction | | test-phase19.ts | 78 | ContextComposer ranking/budget/pinning/staleness/layout, estimateTokens, context_pack + blackboard_search MCP tools (lexical + semantic modes) | | test-phase20.ts | 35 | Security regressions: ClaudeHookBridge full-target deny/allow matching (GHSA-743h-jr5x-mpcr), SandboxPolicy canonicalized command matching (GHSA-9v4f-j8cv-fhxw) | | test.ts | 39 | Core orchestrator smoke tests |

---

Documentation

| Doc | Contents | |---|---| | QUICKSTART.md | Installation, first run, CLI reference, PowerShell guide, Python scripts CLI | | ARCHITECTURE.md | Race condition problem, FSM design, handoff protocol, model-interaction lifecycle governance, module inventory, project structure | | BENCHMARKS.md | Provider performance, rate limits, local GPU, max_completion_tokens guide | | SECURITY.md | Security module, permission system, trust levels, audit trail, OWASP Agentic Top 10 coverage, disclosure SLA, ClawHub scan findings | | THREAT_MODEL.md | Adversary profiles, trust boundaries, explicit non-goals, security controls summary | | DATA_LOCATIONS.md | Every file Network-AI creates — path, purpose, data classification, operator responsibilities | | SUPPLY_CHAIN.md | Runtime dependencies, what runs at install, network surface, SLSA/npm provenance verification | | ENTERPRISE.md | Evaluation checklist, stability policy, security summary, integration entry points | | AUDIT_LOG_SCHEMA.md | Audit log field reference, all event types (including model.refusal / model.attempt), scoring formula | | ADOPTERS.md | Known adopters — open a PR to add yourself | | INTEGRATION_GUIDE.md | End-to-end integration walkthrough with v5.15 modules | | SKILL.md | OpenClaw/ClawHub Python skill — setup, orchestrator protocol, OWASP engine coverage, security scan findings | | AGENTS.md | Cross-vendor agent instructions (Codex, Gemini CLI, Cursor, Factory) — build commands, conventions, architecture patterns | | references/adapter-system.md | Adapter architecture, all 32 adapters (incl. AnthropicMessagesAdapter), writing custom adapters | | references/auth-guardian.md | Permission scoring, resource types, scoreRequest(), IAuthValidator interface | | references/trust-levels.md | Trust level configuration, APS delegation-chain mapping |

---

Use with Claude, ChatGPT & Codex

Using Claude Code (the CLI)? See Use as a Claude Code Plugin — one command installs every tool. Using OpenAI Codex (CLI or IDE)? See Use with OpenAI Codex — add the MCP server with a single codex mcp add. Using Gemini CLI? See Use with Gemini CLI — install the extension with a single gemini extensions install.

Three integration files are included in the repo root:

| File | Use | |---|---| | claude-tools.json | Claude API tool use & OpenAI Codex — drop into the tools array | | openapi.yaml | Custom GPT Actions — import directly in the GPT editor | | claude-project-prompt.md | Claude Projects — paste into Custom Instructions (includes lifecycle governance context) |

Claude API / Codex: ``js import tools from './claude-tools.json' assert { type: 'json' }; // Pass tools array to anthropic.messages.create({ tools }) or OpenAI chat completions ``

Custom GPT Actions: In the GPT editor → Actions → Import from URL, or paste the contents of openapi.yaml. Set the server URL to your running npx network-ai-server --port 3001 instance.

Claude Projects: Copy the contents of claude-project-prompt.md (below the horizontal rule) into a Claude Project's Custom Instructions field. No server required for instruction-only mode.

---

Community

Join our Discord server to discuss multi-agent AI coordination, get help, and share what you're building:


---

Contributing

1. Fork → feature branch → npm run test:all → pull request
2. Bugs and feature requests via Issues

---

MIT License — LICENSE &nbsp;·&nbsp; CHANGELOG &nbsp;·&nbsp; CONTRIBUTING &nbsp;·&nbsp; Code of Conduct &nbsp;·&nbsp; Security Policy &nbsp;·&nbsp; 

<details> <summary>Keywords</summary>

multi-agent · agent orchestration · AI agents · agentic AI · agentic workflow · TypeScript · Node.js · LangGraph · CrewAI · AutoGen · MCP · model-context-protocol · LlamaIndex · Semantic Kernel · OpenAI Assistants · Haystack · DSPy · Agno · OpenClaw · ClawHub · shared state · blackboard pattern · atomic commits · guardrails · token budgets · permission gating · audit trail · agent coordination · agent handoffs · governance · cost-awareness · refusal handling · fallback routing · model lifecycle · OWASP agentic AI · effort policy · thinking blocks

</details>

Download History