Network - AI

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— atomicpropose → validate → commitprevents 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)—ContextComposerassembles token-budgeted, relevance-ranked context packs (semantic/lexical × recency decay × scope affinity, position-aware layout);context_pack+blackboard_searchMCP 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.pyinjects 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)—GovernedModelGatewayabsorbs 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'spropose → validate → commitmutex prevents this at the coordination layer, before any write reaches shared state.

- ATypeScript/Node.js library—import { createSwarmOrchestrator } from 'network-ai'
- AnMCP server—npx network-ai-server --port 3001
- ACLI—network-ai bb get status/network-ai audit tail
- AClaude Code plugin—/plugin install network-ai@network-ai
- AGemini CLI extension—gemini extensions install https://github.com/Jovancoding/Network-AI
- AnOpenClaw skill—clawhub install network-ai

🛡️ Model-Interaction Lifecycle Governance

Most governance tools stop at the agent boundary — they police which tools an agent may callbeforeit 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— detectstop_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 anunservedRefusalCountgap to alert on.
- EffortPolicy— turn theeffortcost dial into a policy object: cap sub-agents atlow, require justification forxhigh/max.
- ThinkingBlockManager— keep thinking blocks unchanged on the same model; strip them on a cross-model fallback; guard prompts againstreasoning_extractionrefusals.
- Per-sub-agent fallback—FanOutFanInsteps andTeamRunnertasks 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.

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

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" } } }

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

- 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 anagent_idparameter — 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>.

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 runsnpx -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:

Validate the manifests locally withclaude 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:

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/mcpto confirmnetwork-aiis connected.

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/mcpinside Gemini CLI to confirm thenetwork-aitools are loaded. For building Gemini-powered swarm agents, use theGeminiAdapter(Gemini Developer API / AI Studio) orVertexAIAdapter(Vertex AI on GCP) — and for Google's Agent2Agent ecosystem,A2AServerexposes 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

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

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)

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.

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

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

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), andFederatedBudgettracking — all without a single API call.

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

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

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

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

Works with LangGraph, CrewAI, and AutoGen

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

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):