Network-AI
TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination
If Network-AI is useful to you, consider giving it a star ⭐ — it helps others find the project.
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 → 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'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
🛡️ 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— 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.```typescript
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 |
### 🔒 ASI Strict Mode (opt-in)
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 / `false` | Off — today's behaviour |
| `audit` | Every check runs and reports would-be denials (`outcome: 'would-deny'`) without blocking — measure before you enforce |
| `enforce` (or any other value — fails closed) | 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** (`ProofGate`) | Gated tools (`shell_exec`, `file_write`, MCP tools marked `requires_formal_proof`) run only with a proof bound to the exact tool, canonical arguments, agent, single-use nonce, and expiry. BYO verifiers (zkVM receipts, formal-verification certificates); built-in short-lived HMAC/Ed25519 capability tokens (`CapabilityIssuer`) for deployments without a prover; optional out-of-process co-signer (`ExternalAuthority.authorize`). |
| **BFT consensus** (`ConsensusEngine`) | High-stakes `GovernedModelGateway` turns are judged by ≥ 3f+1 independent evaluators; robust geometric median (Weiszfeld) with CP-WBFT confidence weighting, outlier detection, signed ballots, and a minimum number of distinct **model families** (correlated models fail together). |
| **Auditor receipts** (`LockedBlackboard`) | 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. `claimVerifierCheck` lets `ClaimVerifier` be the auditor's check. |
| **Kill switch** (`HaltCoordinator`) | 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** (`ContextComposer`) | Per-tier context policies: smaller budgets, higher score floors, allowed scopes, excluded producers. AUDITOR is never derived from a score. |
| **Cognitive caps** (`EffortPolicy`, `ThinkingBlockManager`) | Per-tier effort ceiling, thinking-token budget, output cap, and sub-agent depth limit. |
| **Canaries & export** (`CanaryRegistry`, `HashChainSink`) | 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.```typescript
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.
♾️ Perpetual Runtime (opt-in)
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 LeaseAuthority; short-lived Ed25519 leases; LeaseGuard halts the run when a lease is revoked, paused, expired, or cannot be renewed (dead-man switch); the egress proxy refuses traffic without a live lease |
| I2 | Agents can modify themselves, never their limits | GuardedPaths: governance files and blackboard keys are writable only with a single-use, operator-signed approval of the exact content |
| 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 |
| Component | What it does |
|---|---|
LeaseAuthority (own process) |
Issues and renews leases under an operator-signed RenewalPolicy: TTL, end date, scope (tools, paths, egress routes), budget ceilings, stop conditions (canary failure, failing health, sentry alerts). Operator: revoke, pause, resume, tighten, install policy. Sentries: alert and tighten only. |
LeaseGuard (in the agent) |
Holds the current lease, renews it with spend and health heartbeats, polls for revocation, and vetoes AgentRuntime.exec/writeFile, GovernedModelGateway.send, and LockedBlackboard writes without a valid, in-scope lease. |
EgressProxy (own process) |
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. |
ISandboxRunner |
Disposable sandbox per command; ContainerSandboxRunner defaults to gVisor (runsc), read-only root, no capabilities, no network or egress-proxy only. |
| 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 sentryQuorum set, renewal stops only when enough of them agree. |
ImprovementPipeline |
Self-modification with evidence: static checks, sandbox tests on a copy, multi-family consensus, then a signed receipt bound to the patch hash. Tiers: auto (agent task code), human, operator (guarded paths, always). |
StateSnapshotter / SelfHealer |
HMAC-signed, hash-chained blackboard snapshots; canary failure ⇒ failing health (renewal stops), rollback to the last verified snapshot, session purge. |
BudgetBalancer |
Picks the cheapest approved source with headroom, throttles effort (full → reduced → minimal → stopped), feeds spend into lease heartbeats. |
network-ai perpetual keygen operator && network-ai perpetual keygen authority
network-ai perpetual sign-policy policy.json --key data/perpetual/keys/operator.key --out policy.signed.json
# Role secrets come from the environment (each ≥ 32 chars, 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 data/perpetual/keys/operator.pub \
--authority-key data/perpetual/keys/authority.key --policy policy.signed.json
network-ai perpetual status # the human controls
network-ai perpetual pause | resume | revoke <runId> | revoke --all
``````typescript
import { 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.
⚡ Try in 60 Seconds```bash
npm install network-ai
``````typescript
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:**```bash
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 metadata + audit trail
✅ Minimal mode · --minimal / NETWORK_AI_MINIMAL=1 — skips WAL replay and sweep for fast CI/test startup
✅ 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
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 |
| 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 |
Architecture```mermaid
%%{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```bash
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):```bash
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):```json
{
"mcpServers": {
"network-ai": {
"url": "http://localhost:3001/sse"
}
}
}
Cursor / Cline / any SSE-based MCP client — point to the same URL:```json
{
"mcpServers": {
"network-ai": {
"url": "http://localhost:3001/sse"
}
}
}
Verify it's running:```bash
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, 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, --board, --audit-log.
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):```bash
/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:```jsonc
// .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 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.
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):```bash
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`:```toml
[mcp_servers.network-ai]
command = "npx"
args = ["-y", "-p", "network-ai", "network-ai-server", "--stdio"]
…(正文过长,页面只展示前面部分,完整内容见仓库)
