Network-AI provides an MCP control plane for multi-agent coordination, shared state, governance, and observability.
Read, write, list, check, delete, search, and context-pack shared blackboard entries with TTL and scoped access.
Track and enforce federated token budgets: status, spend, reset, set ceiling, and transaction log.
Create, validate, and revoke HMAC/Ed25519 security tokens for scoped resource access.
Query and tail the append-only audit log for compliance and debugging.
Read and update live orchestrator configuration at runtime.
List, spawn, and stop registered agents via blackboard task records and registry signals.
Advance named FSM states and record transitions on the blackboard.
Get orchestrator health/version, config summary, agent count, blackboard key count, and uptime.
Allows coordination of CrewAI agents within a multi-agent swarm, providing shared state management via an atomic blackboard and federated budget tracking.
Enables integration of LangChain agents into a coordinated swarm, supporting streaming and cross-framework agent interaction with shared memory.
Integrates OpenAI Assistants into a governed multi-agent environment, featuring identity-verified state writes and token ceiling enforcement.
TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination
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 → commitmutex 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 -y -p network-ai@6.0.1 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 → | Architecture → | All adapters → | Benchmarks →
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 }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 |
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 |
For deployments running highly capable agents, ASI_STRICT_MODE adds controls that assume an agent may be smarter than its overseers. It is off by default; when off, every code path is unchanged (a single boolean check).
Setting | Behaviour |
unset / | Off — today's behaviour |
| Every check runs and reports would-be denials ( |
| Violations are blocked |
The setting is read once and frozen; at runtime it can only be tightened (tightenAsiConfig), never loosened.
Control | What it does |
Proof-carrying actions ( | Gated tools ( |
BFT consensus ( | High-stakes |
Auditor receipts ( | LOW-trust agents' changes commit only with a signed receipt from an operator-designated AUDITOR, bound to the change id, key, value hash, and base version. |
Kill switch ( | Password-Activated Shutdown: a salted-hash token detected in the input stream (redacted before any model sees it), an OS signal, or an authenticated HTTP call halts every registered component, aborts in-flight work, and latches until a separate resume key is presented. |
Trust-tiered context ( | Per-tier context policies: smaller budgets, higher score floors, allowed scopes, excluded producers. AUDITOR is never derived from a score. |
Cognitive caps ( | Per-tier effort ceiling, thinking-token budget, output cap, and sub-agent depth limit. |
Canaries & export ( | Decoy values that flag exfiltration when they appear in output; strict-mode events hash-chained to an append-only store outside the agents' process. |
In enforce mode AgentRuntime also forces sourceProtection and withholds secret-like environment variables from child processes.
import { createAsiConfig, ProofGate, CapabilityIssuer, SignedAttestationVerifier, AgentRuntime } from 'network-ai';
const config = createAsiConfig({ mode: 'enforce', auditors: ['auditor-1'] });
const key = { name: 'ops', alg: 'hmac-sha256' as const, key: process.env.CAPABILITY_KEY! };
const proofGate = new ProofGate({ gatedTools: ['shell_exec', 'file_write'], verifiers: [new SignedAttestationVerifier([key])] }, config);
const runtime = new AgentRuntime({ policy: { basePath: '.', allowedCommands: ['npm *'] }, asi: { proofGate, config } });
// The approval service (outside the agent's process) mints a one-shot capability:
const issuer = new CapabilityIssuer('ops', { alg: 'hmac-sha256', secret: process.env.CAPABILITY_KEY! });
const proof = issuer.issue('shell_exec', runtime.shellProofArgs('npm test'), 'agent-7');
await runtime.exec('npm test', 'agent-7', { proof });Limits. Strict mode raises the cost of misbehaviour; it is not a containment proof. An agent with arbitrary code execution on the same host can restart the process with different settings — pair strict mode with OS-level isolation and an out-of-process
ExternalAuthority. Consensus assumes at most f faulty, independent evaluators.
Lets agent swarms run indefinitely, improve themselves, and fund their own work while humans keep control. A run continues only while an operator-signed policy keeps renewing its lease, never because the agents arrange it. Nothing starts automatically, and every integration point is a single check when unused.
Three invariants hold whatever the configuration:
# | Invariant | Mechanism |
I1 | The external stop always works without agent cooperation | Out-of-process |
I2 | Agents can modify themselves, never their limits |
|
I3 | Self-funding stays inside human-set ceilings | Ceilings in the signed policy; agents can lower, never raise; new sources need a new signed policy; payments only through the egress proxy with per-request and per-run limits |
I4 | Code on the agent host cannot cause a lease to be issued or extended (v6.0.0) | Granting needs k off-host authorities co-signing under the same signed policy; stopping needs any one of them, the sentry quorum, the operator, or lease expiry; high-risk scopes need k ≥ 2 unless the operator signs an |
Component | What it does |
| Issues and renews leases under an operator-signed |
| Holds the current lease, renews it with spend and health heartbeats, polls for revocation, and vetoes |
| The agents' only route to the network: lease-checked, per-route allowlist, injects credentials the agents never see, scrubs them from responses, rate-limits, and caps financial requests. |
| Disposable sandbox per command; |
Sentry swarm | Read-only processes over the audit stream: velocity, denied-access probing, prompt injection, blackboard poisoning, guarded-path attempts, canary leaks, goal drift. Each sentry has its own identity; with |
| Self-modification with evidence: static checks, sandbox tests on a copy, multi-family consensus, then a signed receipt bound to the patch hash. Tiers: |
| HMAC-signed, hash-chained blackboard snapshots; canary failure ⇒ failing health (renewal stops), rollback to the last verified snapshot, session purge. |
| Picks the cheapest approved source with headroom, throttles effort ( |
Zero-day containment (v6.0.0) | k-of-n authorities, a deployment posture gate ( |
# The operator key stays off the authority host (keep it offline or on a hardware token).
network-ai perpetual keygen operator --out ~/operator-keys
network-ai perpetual keygen authority
network-ai perpetual sign-policy policy.json --key ~/operator-keys/operator.key --out policy.signed.json
# Role secrets come from the environment (each ≥ 32 chars, high-entropy, all distinct)
NETWORK_AI_LEASE_OPERATOR_SECRET=… NETWORK_AI_LEASE_RUNNER_SECRET=… \
NETWORK_AI_LEASE_SENTRY_SECRET_S1=… NETWORK_AI_LEASE_SENTRY_SECRET_S2=… \
network-ai perpetual authority --operator-pub ~/operator-keys/operator.pub \
--authority-key data/perpetual/keys/authority.key --policy policy.signed.json --agent-user nai-agent
network-ai perpetual doctor --role authority --operator-pub ~/operator-keys/operator.pub --key data/perpetual/keys/authority.key
network-ai perpetual status # the human controls
network-ai perpetual pause | resume | revoke <runId> | revoke --all
network-ai perpetual checkpoint --all --key ~/operator-keys/operator.key --policy policy.signed.jsonimport { LeaseGuard, HttpLeaseTransport, HaltCoordinator, AgentRuntime } from 'network-ai';
const guard = new LeaseGuard({
runId: 'research-swarm',
authorityPublicKey, // the authority's public key only
transport: new HttpLeaseTransport('http://127.0.0.1:4710', process.env.NETWORK_AI_LEASE_RUNNER_SECRET!),
halt: haltCoordinator, // fired when the lease is lost
spend: () => balancer.spend(),
health: () => healer.health(),
});
await guard.start();
const runtime = new AgentRuntime({ policy: { basePath: '.' }, lease: guard, guarded, sandbox: { runner } });Limits. The guarantees rest on the operator key, role secrets, and credentials staying outside the agents' reach, and on the authority, proxy, and sentries running where agents cannot write or signal. Run agents in the sandbox with network access only through the proxy; without that isolation an agent with host code execution can bypass in-process checks.
Related MCP server: OmniAgent MCP Mesh
npm install network-aiimport { 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.tsRuns 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.
✅ Atomic shared state |
|
✅ 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 |
|
✅ Flow control | Pause / resume / throttle writes on the blackboard |
✅ Skill composition |
|
✅ Semantic memory search | BYOE vector store with cosine similarity over blackboard data |
✅ Phase pipeline | Multi-phase workflows with human-in-the-loop approval gates; |
✅ 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 |
✅ 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 |
|
✅ WAL crash recovery |
|
✅ Circuit Breaker |
|
✅ OTel telemetry hooks |
|
✅ 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 |
|
✅ Minimal mode |
|
✅ ASI Strict Mode | Opt-in proof-carrying actions, BFT consensus, auditor receipts, kill switch, trust-tiered context, cognitive caps |
✅ Perpetual Runtime | Opt-in indefinite runs under operator-signed leases: dead-man switch, egress proxy, guarded paths, sandbox, sentry swarm, self-improvement pipeline, self-healing state, budget balancer |
✅ TypeScript native | ES2022 strict mode, zero native dependencies |
Problem | How Network-AI solves it |
Race conditions in parallel agents | Atomic blackboard: |
Agent overspend / runaway costs |
|
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 |
|
Agents lack project context between runs |
|
No regression tracking on agent output quality |
|
Long-running agents you cannot reliably stop | Perpetual Runtime — out-of-process lease authority, dead-man switch, and guarded governance paths keep humans in control |
%%{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
FederatedBudgetis a standalone export — instantiate it separately and optionally wire it to a blackboard backend for cross-node token budget enforcement.
ProjectContextManageris 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
npm install network-aiNo native dependencies, no build step. Adapters are dependency-free (BYOC — bring your own client).
Start the server (no config required, zero dependencies):
npx -y -p network-ai@6.0.1 network-ai-server --port 3001
# or from source:
npx ts-node bin/mcp-server.ts --port 3001Then 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 listTools 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, recorded as the source agent of every write. The MCP server's trust boundary is transport authentication (the bearer secret over SSE/HTTP, or local stdio): once a client is admitted, the server writes on its behalf with a server-held random identity, so any agent_id works and no shared token needs to be known. Caller-supplied agent_token values are ignored over MCP. In-process TypeScript code keeps per-agent tokens and namespaces via registerAgent().
Options: --no-budget, --no-token, --no-control, --ceiling <n>, --board <name>, --audit-log <path>.
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-aiThat'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@6.0.1 network-ai-server --stdio (stdio MCP transport), pinned to the exact published npm version.
The plugin lives in its own folder, so the directory only reads plugin files:
File | Role |
Plugin manifest (icon: | |
Registers the Network-AI MCP server (stdio, pinned version) | |
Slash commands — | |
Self-hosted marketplace catalog (points at | |
Project MCP config for contributors working in this repository |
Validate locally with claude plugin validate ./plugins/network-ai and claude plugin validate . (marketplace).
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@6.0.1 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 and are matched against the tool name and every string field of the tool input (e.g. Write.content, Edit.new_string, MCP tool arguments). --allow patterns match only the tool name and primary target. Invalid or backtracking-prone patterns make the hook exit 2, which Claude Code treats as a block, so a bad rule fails closed rather than silently disabling the deny list.
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@6.0.1 network-ai-server --stdioIn 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@6.0.1", "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.
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-AIOr register just the MCP server directly:
gemini mcp add network-ai npx -- -y -p network-ai network-ai-server --stdioRun /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, // required (v5.15.5+); or allowUnauthenticated: true for loopback-only dev
executor: async (text) => ({ text: await runSwarmTask(text) }),
});
a2a.startServer(4310); // serves /.well-known/agent.json + tasks/sendControl 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 blackboardCommand group | What it controls |
| Blackboard — get, set, delete, list, snapshot, propose, commit, abort |
| AuthGuardian — issue tokens ( |
| FederatedBudget — spend status, set ceiling |
| Audit log — print, live-tail, clear |
| Environment management — init, list, chain, diff, promote, backup, restore |
| Self-diagnostics — validate data dir, env routing, audit log, WAL, kill-switch, MCP secret |
| Inspect a blackboard key — value, metadata, pending history, audit trail |
| Kill switch — write/remove |
| Perpetual Runtime — keygen, sign-policy, authority, proxy, sentry, status, pause, resume, revoke, tighten, install-policy, sign-guarded, sign-budget, snapshot, rollback, doctor, checkpoint, tripwires, sign-capability-eval, capability-eval |
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
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
Runs in ~3 seconds. Proves the coordination primitives without any LLM calls.
npm run demo -- --08What 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
32 adapters, zero adapter dependencies. You bring your own SDK objects.
Adapter | Framework / Protocol | Register method |
| Any function or HTTP endpoint |
|
| LangChain |
|
| AutoGen / AG2 |
|
| CrewAI |
|
| Model Context Protocol |
|
| LlamaIndex |
|
| Microsoft Semantic Kernel |
|
| OpenAI Assistants |
|
| deepset Haystack |
|
| Stanford DSPy |
|
| Agno (formerly Phidata) |
|
| OpenClaw |
|
| Google A2A Protocol |
|
| OpenAI Codex / gpt-4o / Codex CLI |
|
| MiniMax LLM API (M2.5 / M2.5-highspeed) |
|
| NVIDIA NemoClaw (sandboxed agents via OpenShell) |
|
| Agent Permission Service (delegation-chain trust) |
|
| GitHub Copilot (generate/review/explain/fix/test/refactor/chat) |
|
| LangGraph (compiled StateGraph) |
|
| Anthropic Computer Use (screenshot/click/type/scroll) |
|
| OpenAI Agents SDK (tool use, handoffs, guardrails) |
|
| Google Vertex AI / Gemini (function calling, multi-modal) |
|
| Pydantic AI (structured output, validation, deps injection) |
|
| Browser automation (Playwright/Puppeteer/CDP) |
|
| NousResearch Hermes / any OpenAI-compatible endpoint (Ollama, Together AI, Fireworks, llama.cpp) |
|
| Hierarchical multi-orchestrator coordination |
|
| Recursive Language Model / any RLM-compatible HTTP endpoint (arxiv 2512.24601) |
|
Streaming variants (drop-in replacements with .stream() support):
Adapter | Extends | Streaming source |
|
| Calls |
|
| Pipes |
Extend BaseAdapter (or StreamingBaseAdapter for streaming) to add your own in minutes. See references/adapter-system.md.
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 | ✅ 32 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) | ✅ | ⚠️ State passed between nodes; last-write-wins | ⚠️ Shared memory available; no conflict resolution | ⚠️ Shared context available; no conflict resolution |
Hard token ceiling per agent | ✅ | ⚠️ Via callbacks / custom middleware | ⚠️ Via callbacks / custom middleware | ⚠️ Built-in token tracking in v0.4+; no swarm-level ceiling |
Permission gating before sensitive ops | ✅ | ⚠️ Possible via custom node logic | ⚠️ Possible via custom tools | ⚠️ Possible via custom middleware |
Append-only audit log | ✅ plain 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 |
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
npx ts-node test-asi.ts # ASI Strict Mode
npx ts-node test-perpetual.ts # Perpetual Runtime: leases, egress proxy, CLI
npx ts-node test-perpetual-safety.ts # Perpetual Runtime: guarded paths, sandbox, sentries, pipeline, self-healing, budget
npx ts-node test-perpetual-phase5.ts # Perpetual Runtime Phase 5: k-of-n, posture, checkpoints, tripwires, relay, attestation, Merkle, core, Lean
npx ts-node test-perpetual-fuzz.ts # Seeded fuzzing of every control door (NAI_FUZZ_SEED / NAI_FUZZ_ITERATIONS)4,588 passing assertions across 47 test suites (npm run test:all):
Suite | Assertions | Covers |
| 147 | FSM governance, compliance monitor, adapter integration |
| 127 | SSE transport, |
| 121 | CRDT backend, vector clocks, bidirectional sync |
| 129 | MCP server, control-plane tools, audit tools |
| 271 | All 32 adapters, registry routing, integration, edge cases |
| 117 | Pluggable backend (Redis, CRDT, Memory) |
| 88 | Blackboard, auth, integration, persistence, parallelisation, quality gate |
| 87 | Federated budget tracking |
| 73 | Named multi-blackboard, isolation, backend options |
| 51 | Codex adapter: chat, completion, CLI, BYOC client, error paths |
| 50 | MiniMax adapter: lifecycle, registration, chat mode, temperature clamping |
| 93 | NemoClaw adapter: sandbox lifecycle, policies, blueprint, handoff, env forwarding |
| 64 | Priority preemption, conflict resolution, backward compat |
| 35 | A2A protocol: register, execute, mock fetch, error paths |
| 32 | Streaming adapters, chunk shapes, fallback, collectStream |
| 55 | Pluggable backend part 2, consistency levels |
| 42 | Named multi-blackboard base |
| 34 | Tokens, sanitization, rate limiting, encryption, audit |
| 65 | CLI layer: bb, auth, budget, audit commands |
| 67 | QA orchestrator: scenarios, feedback loop, regression, contradictions |
| 94 | Deferred init, hook middleware, flow control, skill composer, semantic search |
| 146 | Phase pipeline, confidence filter, matcher-based hooks, fan-out/fan-in |
| 293 | Agent runtime, sandbox policy, shell executor, file accessor, approval gate, console UI, orchestrator wiring, pipe mode, strategy agent |
| 153 | Goal decomposer, task DAG validation, topological layers, JSON parsing, team runner, concurrency, timeouts, events, runTeam one-liner, dependency injection, LLM planner |
| 55 | TTL background sweep, WAL crash recovery, CircuitBreaker, |
| 304 | WorkTree, ControlPlane, dashboard server, topology visualization, WebSocket protocol |
| 123 | FederatedBudget child spending, blackboard metadata API, best-partial result, HookContext depth, sub-goal recursion, semaphore fan-out, PhasePipeline compaction, RLMAdapter end-to-end |
| 65 | Context Throttler, Partition Planner, Coverage Gate, Route Classifier, EVALUATING FSM state, runTeam integration |
| 77 | Multi-environment isolation, promotion chain, backup/restore, source protection, NETWORK_AI_ENV, blackboard env routing |
| 117 | Basis transport tier: |
| 50 | ClaimVerifier: receipt generation/tamper/expiry, corroborated/unsupported/undisclosed, trust decay/reset/DoS protection |
| 58 | ESM dual-build config, McpStreamableServer dispatch + resources + prompts, PhasePipeline checkpoint/resume/clear, SemanticMemory save/load/autoSave/clearPersisted |
| 52 | Model lifecycle governance: |
| 32 | Orchestration resilience: |
| 21 |
|
| 15 |
|
| 85 |
|
| 78 |
|
| 142 | Security regressions: |
| 148 | ASI Strict Mode: config parsing/tightening, |
| 144 | Perpetual Runtime: signing, |
| 152 | Perpetual Runtime: |
| 326 | Perpetual Runtime Phase 5: high-risk policies, signers + |
| 44 | Seeded fuzzing of every control door: authority router, egress proxy, relay frames, lease/policy/checkpoint/eval verification, co-signing, Merkle proofs, routes, sandbox requests, tripwire manifests, snapshots |
| 14 | ClawHub Python skill scripts run against a throwaway project: pending files never resolved or followed (real symlinks on Linux CI; junctions and non-regular entries everywhere), containment by path components |
| 13 | Launchers and run instructions pin |
| 39 | Core orchestrator smoke tests |
Doc | Contents |
Installation, first run, CLI reference, PowerShell guide, Python scripts CLI | |
Race condition problem, FSM design, handoff protocol, model-interaction lifecycle governance, ASI Strict Mode, Perpetual Runtime, module inventory, project structure | |
Provider performance, rate limits, local GPU, | |
Security module, permission system, trust levels, audit trail, OWASP Agentic Top 10 coverage, Perpetual Runtime controls, disclosure SLA, ClawHub scan findings | |
Adversary profiles (incl. self-modifying long-running agents), trust boundaries, explicit non-goals, security controls summary | |
Every file Network-AI creates — path, purpose, data classification, operator responsibilities (incl. Perpetual Runtime keys, audits, snapshots) | |
Runtime dependencies, what runs at install, network surface (incl. lease authority and egress proxy), SLSA/npm provenance verification | |
Evaluation checklist, stability policy, security summary, integration entry points | |
Audit log field reference, all event types (including | |
Known adopters — open a PR to add yourself | |
End-to-end integration walkthrough with v5.17 modules, including the Perpetual Runtime | |
OpenClaw/ClawHub Python skill — setup, orchestrator protocol, OWASP engine coverage, security scan findings | |
Cross-vendor agent instructions (Codex, Gemini CLI, Cursor, Factory) — build commands, conventions, architecture patterns | |
Adapter architecture, all 32 adapters (incl. | |
Permission scoring, resource types, | |
Trust level configuration, APS delegation-chain mapping |
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 API tool use & OpenAI Codex — drop into the | |
Custom GPT Actions — import directly in the GPT editor | |
Claude Projects — paste into Custom Instructions (includes lifecycle governance and Perpetual Runtime context) |
Claude API / Codex:
import tools from './claude-tools.json' assert { type: 'json' };
// Pass tools array to anthropic.messages.create({ tools }) or OpenAI chat completionsCustom 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 -y -p network-ai@6.0.1 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.
Join our Discord server to discuss multi-agent AI coordination, get help, and share what you're building:
Fork → feature branch → npm run test:all → pull request
Bugs and feature requests via Issues
MIT License — LICENSE · CHANGELOG · CONTRIBUTING · Code of Conduct · Security Policy ·
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
List all agents registered with the orchestrator and their current status. Read-only — no side effects. Returns {ok:true, agents:[{agentId, status, lastSeen, taskCount}], count}. Returns {ok:false, error:"..."} if the registry is unavailable. status_filter accepts one of: "active", "idle", "stopped", or "error" — omit to return all statuses. Call before agent_spawn or agent_stop to confirm the target agent exists and has the expected status.
Inputs: status_filter.
Write a task record to the blackboard to dispatch work to a named agent on its next poll cycle. Returns {ok:true, taskKey, agentId, instruction, written:true} on success. Returns {ok:false, error:"..."} if agent_id, task_key, or instruction is missing, or if payload_json is malformed. Call agent_list first to confirm the target agent is registered; verify the task was recorded with blackboard_read after spawning.
Inputs: agent_id (required), task_key (required), instruction (required), ttl, +1 more.
Signal a running agent to stop by writing a stop record to the blackboard and marking it stopped in the registry. Returns {ok:true, agentId, reason, stopped:true}. Returns {ok:false, error:"..."} if agent_id is missing. agent_id must match a value returned by agent_list; reason is optional but written to the audit log under eventType "agent_stop" and helps trace the cause of the stop. The agent observes the stop signal on its next poll — it does not terminate immediately. Call agent_list first to confirm the agent is currently active.
Inputs: agent_id (required), reason.
Search the append-only audit log with optional filters. Read-only — never modifies the log. Returns {ok:true, entries:[{timestamp, agentId, eventType, outcome, details}], count}. Returns {ok:false, error:"..."} if the log file cannot be read. All filters are optional and combinable; use limit to cap results and avoid large payloads on busy systems (default 100). Use audit_tail for the most recent N entries without filtering; use this tool for compliance review, debugging, or verifying permission grant history.
Inputs: limit, since_iso, outcome_filter, agent_id_filter, +1 more.
Return the N most recent audit log entries in ascending timestamp order (oldest-first within the tail window). Read-only — no side effects. Returns {ok:true, entries:[{timestamp, agentId, eventType, outcome, details}], count}. Returns {ok:false, error:"..."} if the log file cannot be read. n defaults to 20 and is capped at 500 — use a larger value only when debugging a busy system. Prefer audit_query for filtered searches by agent, event type, outcome, or time range; use this tool for real-time monitoring or quick post-action verification.
Inputs: n.
Remove an entry from the shared blackboard by key. Returns {ok:true, deleted:true, key} if found and removed; {ok:true, deleted:false, key} if the key was absent or already expired. Returns {ok:false, error:"..."} if the agent token is rejected or the blackboard is unavailable. key must use the same namespaced format used at write time (e.g. "task:result:q3"); agent_token is required only if the entry was written with a token — omit it for unprotected keys. Call blackboard_exists first to confirm the key is present before deletion.
Inputs: key (required), agent_id (required), agent_token.
Check whether a specific key is present and not expired on the shared blackboard. Read-only — no side effects and never modifies state. Returns {ok:true, exists:true} or {ok:true, exists:false}. Returns {ok:false, error:"..."} if the blackboard is unavailable. key must use the same namespaced format as blackboard_read/write/delete (e.g. "task:result:q3"); agent_id is used for scoped access checks. Prefer over blackboard_read when only checking presence — lighter-weight and avoids fetching the full value.
Inputs: key (required), agent_id (required).
List all active (non-expired) keys on the shared blackboard, optionally filtered by a key prefix. Read-only — no side effects. Returns {ok:true, keys:["..."], count}. Returns {ok:false, error:"..."} if the blackboard is unavailable. All non-expired keys are returned in one response — on large blackboards use a narrow prefix filter to reduce payload size. Use before blackboard_read when you do not know the exact key name; filter with a prefix such as "task:" to scope results to a specific namespace.
Inputs: agent_id (required), prefix.
Read a single entry from the shared blackboard by key. Read-only — never modifies the blackboard. Returns {ok:true, key, value, sourceAgent, timestamp} when found, or {ok:true, key, value:null} when the key does not exist or has expired. Returns {ok:false, error:"..."} if the blackboard is unavailable. key uses the same namespaced format as blackboard_write (e.g. "task:analysis:q3"); agent_id is used for scoped access checks and audit logging. Use when you know the exact key; call blackboard_list with a prefix filter first if you need to discover available keys.
Inputs: key (required), agent_id (required).
Search the shared blackboard for entries relevant to a query and return the top-K ranked matches. Use this instead of blackboard_list when you need relevant keys rather than all keys — it keeps noise out of your context window. Read-only. Ranks semantically when the server has an embedding provider wired, otherwise by deterministic lexical overlap (response includes which mode was used). Returns {ok:true, mode, results:[{key, score, snippet, sourceAgent}], count}. Follow up with blackboard_read for the full value of a specific key.
Inputs: query (required), agent_id (required), top_k, min_score.
Write a JSON-encoded value to the shared blackboard under the given key. Overwrites any existing entry for that key — TTL is also replaced (or removed if omitted). Not idempotent: each call records a new timestamp and sourceAgent. Returns {ok:true, key, value, sourceAgent, timestamp} on success. Returns {ok:false, error:"..."} if value is not valid JSON, agent_id is missing, or the agent token is rejected. value must be a valid JSON string (use JSON.stringify on objects); ttl sets expiry in seconds — omit for a persistent entry; agent_token is required only if the target key is protected. Use namespaced keys (e.g. "task:result:q3") to avoid collisions; confirm with blackboard_read immediately if the consumer agent is already polling.
Inputs: key (required), value (required), agent_id (required), ttl, +1 more.
Return a chronological list of all token spend transactions. Read-only — never modifies budget state. Returns {ok:true, log:[{agentId, tokens, timestamp}], count}. Returns {ok:false, error:"..."} if the budget is not available. Use limit to cap the number of entries returned (default 50); prefer budget_status for a summary view. Useful for auditing which agents consumed the most tokens in a task cycle.
Inputs: agent_id (required), limit.
Reset all agent spend counters to zero while preserving the ceiling. Returns {ok:true, reset:true, ceiling} on success. Returns {ok:false, error:"confirm must be "yes""} if the confirm parameter is not "yes" — this guard prevents accidental resets. Do not reset mid-task if other agents are actively spending — use only at the start of a new task cycle or after all agents have finished. Call budget_status before and after to verify the reset took effect.
Inputs: confirm (required), agent_id (required).
Dynamically change the global token ceiling for all agents. Returns {ok:true, ceiling, previous} on success. Returns {ok:false, error:"..."} if ceiling is not a positive number. Changes take effect immediately — lowering below current spend will deny all future budget_spend calls until counters are reset via budget_reset; raising allows previously blocked agents to resume. ceiling must be a positive integer (total token budget across all agents); agent_id is recorded in the audit log. Avoid lowering the ceiling while agents are actively running; call budget_status first to check the current spend level.
Inputs: ceiling (required), agent_id (required).
Deduct tokens from the global FederatedBudget on behalf of an agent. Returns {ok:true, allowed:true, spent, remaining} when approved, or {ok:true, allowed:false, deniedReason, remaining} when the ceiling would be exceeded. Returns {ok:false, error:"..."} if tokens is not a positive integer. tokens represents the estimated cost of the upcoming LLM call — pass the expected usage before invoking the model; agent_id is tracked individually in the spend log and reported by budget_status. Call budget_status first to check remaining balance; never attempt an LLM call after receiving allowed:false.
Inputs: tokens (required), agent_id (required).
Get a read-only snapshot of the global FederatedBudget: ceiling, total spent, remaining tokens, and per-agent spend breakdown. Never modifies budget state. Returns {ok:true, ceiling, spent, remaining, perAgent:{agentId:tokensSpent}}. Returns {ok:false, error:"Budget not available"} if no budget is configured. agent_id is recorded in the audit log only — it does not filter results. Call before budget_spend to check available capacity; use budget_get_log for a full timestamped transaction history.
Inputs: agent_id (required).
Read one or all live orchestrator configuration values. Returns {ok:true, key, value} for a single key, or {ok:true, config:{...}} for all keys. Returns {ok:false, error:"Unknown config key: "..." Known keys: ..."} if the key is not recognised. Call without a key to discover available config names; use config_set to update values at runtime.
Inputs: key.
Update a live orchestrator configuration value at runtime. Changes take effect immediately for all subsequent operations and are written to the audit log — there is no undo. Returns {ok:true, key, value, previous} on success. Returns {ok:false, error:"Unknown config key..."} with a list of valid keys if the key is not recognised, or {ok:false, error:"..."} if value is not valid JSON. Call config_get first to read the current value and confirm the key name before updating.
Inputs: key (required), value (required).
Assemble a token-budgeted, relevance-ranked context brief from the shared blackboard for a given task. Use this INSTEAD of blackboard_list + many blackboard_read calls: it returns only the entries most relevant to your task, ranked by semantic/lexical relevance, recency (half-life decay), and namespace affinity, assembled position-aware (strongest items first and last) under a hard token budget. Read-only — never modifies the blackboard. Returns {ok:true, text, used_tokens, budget_tokens, utilization, included:[{key,score,tokens}], excluded:[{key,reason}]}. The text field is ready to use as working context. Entries past their TTL are excluded automatically.
Inputs: task (required), agent_id (required), max_items, scope_tags, +1 more.
Advance a named FSM (Finite State Machine) to a new state and record the transition on the blackboard. Transitions are irreversible via this tool — new_state is written directly without validating against a predefined state graph, so the caller must ensure the transition is valid. Returns {ok:true, fsmId, transition:{from, to}, blackboardWritten:true} on success. Returns {ok:false, error:"..."} if fsm_id, new_state, or agent_id is missing, or if metadata_json is not valid JSON. Avoid concurrent transitions to the same FSM from multiple agents; call orchestrator_info first to read the current FSM state before transitioning.
Inputs: fsm_id (required), agent_id (required), new_state (required), metadata_json.
Return a full health snapshot of the orchestrator: version, config values, registered agent count, blackboard key count, and system uptime. Returns {ok:true, version, config:{...}, agentCount, blackboardKeyCount, uptime}. This tool always succeeds — it never returns {ok:false}. Use as the first call when connecting to confirm the server is healthy and to discover current config before calling config_get or agent_list.
Inputs: no named parameters.
Issue a new HMAC/Ed25519-signed security token for an agent scoped to a resource type and permission level. Each call produces a unique token with a fixed expiry managed by the token manager. Returns {ok:true, token:{tokenId, agentId, resourceType, scope, issuedAt, expiresAt, signature}}. Returns {ok:false, error:"..."} if the token manager is unavailable. resource_type is a free-form string identifying the protected resource (e.g. "FILE_SYSTEM", "BLACKBOARD", "API"); scope controls permission level (e.g. "read", "write", "admin"). Pass the full returned token object as token_json to token_validate; call token_revoke with the tokenId when access should be withdrawn.
Inputs: scope (required), agent_id (required), resource_type (required).
Permanently revoke a security token by its tokenId. Returns {ok:true, revoked:true, tokenId} on success. Returns {ok:false, error:"..."} if the token manager is unavailable. Revocation is immediate and irreversible — the token will fail token_validate on all future attempts. token_id is the tokenId field from the token object returned by token_create; reason is optional but written to the audit log and aids security review. Use when an agent session ends, a permission grant expires by policy, or a token may have been compromised.
Inputs: token_id (required), reason.
Verify a security token's HMAC/Ed25519 signature, confirm it has not expired, and check it has not been revoked. Read-only — never modifies token state. Returns {ok:true, valid:true, token:{...}} if the token passes all checks, or {ok:true, valid:false, reason:"..."} if it fails any check (reason indicates which check failed: "invalid_signature", "expired", or "revoked"). Returns {ok:false, error:"..."} if token_json is not valid JSON. Call before granting access to any protected resource; use token_revoke to invalidate a token that should no longer be trusted.
Inputs: token_json (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 24 tools
Each tool targets a distinct function: blackboard operations are separated into list/read/write/delete/exists/search, budget tools split status/spend/reset/set/log, token tools cover create/validate/revoke, and audit tools split query/tail. Even similar read-only tools (blackboard_search vs blackboard_list vs context_pack) have clear intended use cases described.
All tools follow a consistent snake_case pattern of domain_prefix_action, e.g., blackboard_list, budget_status, token_create, agent_spawn, config_get. The domain prefix is always lowercase and separated by an underscore, with clear verbs (list, read, write, delete, exists, status, spend, reset, set, get_log, create, validate, revoke, query, tail, set, list, spawn, stop, transition, info, pack, search).
With 24 tools, the server is on the heavier side but the scope is broad (orchestration, blackboard, budget, tokens, audit, agents, FSM). Each tool serves a distinct purpose and the count is justified for a complex orchestrator server, though a slightly tighter set could be possible.
The server covers core lifecycle operations for blackboard (create/read/update/delete/list/search) and tokens (create/validate/revoke), plus budget management (status/spend/reset/set/log) and basic agent operations (list/spawn/stop). Minor gaps include no direct agent removal or FSM reset, and no explicit tool for blackboard TTL extension, but agents can work around most gaps.
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Coordinate multiple AI agents over MCP: atomic claims, leases, shared ledger, handoffs, tasks.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Shared blackboard and MCP control plane for multi-agent teams.
