network-ai
Multi-agent coordination layer for Gemini CLI — atomic shared blackboard (propose/validate/commit), permission gating with HMAC/Ed25519-sign
Open source Open in the app JSON README (API)
About
Multi-agent coordination layer for Gemini CLI — atomic shared blackboard (propose/validate/commit), permission gating with HMAC/Ed25519-signed tokens, federated token-budget tracking, and append-only audit-log queries over MCP.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- jovancoding
- Origin
- gemini
- Category
- ferramentas
- Version
- 5.15.1
- Stars
- 74
- Forks
- 12
- Open pull requests
- 1
- Last push
- 2026-08-31T23:10:44Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
jovancoding/network-ai
README
# Network-AI
**TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination**
[](https://network-ai.org/)
[](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml)
[](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml)
[](https://github.com/Jovancoding/Network-AI/releases)
[](https://www.npmjs.com/package/network-ai)
[](#testing)
[](#adapter-system)
[](LICENSE)
[](https://socket.dev/npm/package/network-ai/overview)
[](https://nodejs.org)
[](https://typescriptlang.org)
[](https://clawhub.ai/jovancoding/network-ai)
[](INTEGRATION_GUIDE.md)
[](https://github.com/sponsors/Jovancoding)
[](https://discord.gg/Cab5vAxc86)
[](https://glama.ai/mcp/servers/Jovancoding/network-ai)
<p align="center">
<img src="assets/demo.svg" alt="Network-AI control-plane demo — atomic blackboard, priority preemption, AuthGuardian, FSM governance" width="720">
</p>
<p align="center">
<b>If Network-AI is useful to you, consider <a href="https://github.com/Jovancoding/Network-AI">giving it a star ⭐</a> — it helps others find the project.</b>
</p>
Network-AI is a TypeScript/Node.js multi-agent orchestrator that adds coordination, guardrails, and governance to any AI agent stack.
- **Shared blackboard with locking** — atomic `propose → validate → commit` prevents race conditions and split-brain failures across parallel agents
- **Guardrails and budgets** — FSM governance, per-agent token ceilings, HMAC / Ed25519 audit trails, and permission gating
- **Context signal-over-noise (v5.15)** — `ContextComposer` assembles token-budgeted, relevance-ranked context packs (semantic/lexical × recency decay × scope affinity, position-aware layout); `context_pack` + `blackboard_search` MCP tools let agents pull curated state instead of dumping the whole board into their window
- **32 adapters** — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, OpenAI Responses (Assistants successor), LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Custom (+ streaming), OpenClaw, A2A, Codex, MiniMax, NemoClaw, APS, Copilot, LangGraph, Anthropic Computer Use, Claude Agent SDK (agentic loops), OpenAI Agents SDK, Vertex AI, Gemini (Developer API), Pydantic AI, Browser Agent, Hermes (NousResearch Hermes / any OpenAI-compatible endpoint), Orchestrator (hierarchical multi-orchestrator), and RLM (Recursive Language Model / any RLM-compatible HTTP endpoint) — no glue code, no lock-in
- **Persistent project memory (Layer 3)** — `context_manager.py` injects decisions, goals, stack, milestones, and banned patterns into every system prompt so agents always have full project context
- **v5.0 modules** — Agent VCR (record/replay), comparison runner, coverage reporter, goal DSL, approval inbox, job queue, gRPC/HTTP transport, playground REPL, adapter test harness, and more
- **Model-interaction lifecycle governance (v5.13)** — `GovernedModelGateway` absorbs the model refusal → fallback → billing chain (cross-model fallback, fallback-credit repricing, effort governance, thinking-block handoff) behind one governed, budgeted, audited call
> **The silent failure mode in multi-agent systems:** parallel agents writing to the same key
> use last-write-wins by default — one agent's result silently overwrites another's mid-flight.
> The outcome is split-brain state: double-spends, contradictory decisions, corrupted context,
> no error thrown. Network-AI's `propose → validate → commit` mutex prevents this at the
> coordination layer, before any write reaches shared state.
**Use Network-AI as:**
- A **TypeScript/Node.js library** — `import { createSwarmOrchestrator } from 'network-ai'`
- An **MCP server** — `npx network-ai-server --port 3001`
- A **CLI** — `network-ai bb get status` / `network-ai audit tail`
- A **Claude Code plugin** — `/plugin install network-ai@network-ai`
- A **Gemini CLI extension** — `gemini extensions install https://github.com/Jovancoding/Network-AI`
- An **OpenClaw skill** — `clawhub install network-ai`
[**5-minute quickstart →**](QUICKSTART.md) | [**Architecture →**](ARCHITECTURE.md) | [**All adapters →**](#adapter-system) | [**Benchmarks →**](BENCHMARKS.md)
---
## 🛡️ Model-Interaction Lifecycle Governance
Most governance tools stop at the agent boundary — they police which tools an agent may call *before* it acts. Network-AI also governs the layer underneath: **how an agent talks to the model.** When a frontier model declines a request with a classifier refusal, Network-AI absorbs the refusal → fallback → billing chain and presents one governed, budgeted, audited call.
- **`GovernedModelGateway`** — detect `stop_reason:"refusal"`, audit which classifier fired, route to a fallback model, and redeem the fallback-credit token so the retry is repriced as a cache read.
- **`ModelBudget`** — per-model USD accounting with fallback-credit repricing; never sums tokens across models.
- **`RefusalTelemetry`** — a refusal is an HTTP 200, invisible to error-rate monitoring; emitted as a discrete non-error signal with an `unservedRefusalCount` gap to alert on.
- **`EffortPolicy`** — turn the `effort` cost dial into a policy object: cap sub-agents at `low`, require justification for `xhigh`/`max`.
- **`ThinkingBlockManager`** — keep thinking blocks unchanged on the same model; strip them on a cross-model fallback; guard prompts against `reasoning_extraction` refusals.
- **Per-sub-agent fallback** — `FanOutFanIn` steps and `TeamRunner` tasks each carry their own fallback agent and per-request retry budget (`RetryBudget`), because a turn can refuse independently across an agent and its sub-agents.
```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 |
---
## ⚡ 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 <key>` metadata + audit trail |
| ✅ Minimal mode | `--minimal` / `NETWORK_AI_MINIMAL=1` — skips WAL replay and sweep for fast CI/test startup |
| ✅ TypeScript native | ES2022 strict mode, zero native dependencies |
---
## Why teams use Network-AI
| Problem | How Network-AI solves it |
|---|---|
| Race conditions in parallel agents | Atomic blackboard: `propose → validate → commit` with file-system mutex |
| Agent overspend / runaway costs | `FederatedBudget` — hard per-agent token ceilings with live spend tracking |
| No visibility into what agents did | HMAC / Ed25519-signed audit log on every write, permission grant, and FSM transition |
| Locked into one AI framework | 32 adapters — mix LangChain + AutoGen + CrewAI + Codex + Gemini + MiniMax + NemoClaw + APS + LangGraph + Vertex AI + Hermes + RLM + custom in one swarm |
| Agents escalating beyond their scope | `AuthGuardian` — scoped permission tokens required before sensitive operations |
| Agents lack project context between runs | `ProjectContextManager` (Layer 3) — inject decisions, goals, stack, and milestones into every system prompt |
| No regression tracking on agent output quality | `QAOrchestratorAgent` — scenario replay, feedback loops, cross-agent contradiction detection, historical trend tracking |
---
## Architecture
```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](ARCHITECTURE.md#layer-3--projectcontextmanager).
→ [Full architecture, FSM journey, and handoff protocol](ARCHITECTURE.md)
---
## 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 — all writes are identity-verified and namespace-scoped, exactly as they are in the TypeScript API.
Options: `--no-budget`, `--no-token`, `--no-control`, `--ceiling <n>`, `--board <name>`, `--audit-log <path>`.
---
## Use as a Claude Code Plugin
Network-AI ships as a [Claude Code](https://code.claude.com) 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`](.claude-plugin/plugin.json) | Plugin manifest |
| [`.mcp.json`](.mcp.json) | Registers the Network-AI MCP server (stdio) |
| [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) | Self-hosted marketplace catalog |
| [`commands/`](commands/status.md) | 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.
---
## Use with OpenAI Codex
Network-AI also runs as an [OpenAI Codex](https://developers.openai.com/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`](.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"]
```
Either route exposes the full tool set (`blackboard_read`, `budget_status`, `audit_query`, `token_create`, …) over stdio MCP — no API keys, no running server to manage.
---
## Use with Gemini CLI
Network-AI ships as a [Gemini CLI](https://github.com/google-gemini/gemini-cli) extension — the repo root carries [`gemini-extension.json`](gemini-extension.json), which wires in the stdio MCP server and a [`GEMINI.md`](GEMINI.md) context file automatically:
```bash
gemini extensions install https://github.com/Jovancoding/Network-AI
```
Or register just the MCP server directly:
```bash
gemini mcp add network-ai npx -- -y -p network-ai network-ai-server --stdio
```
Run `/mcp` inside Gemini CLI to confirm the `network-ai` tools are loaded. For building Gemini-powered swarm agents, use the `GeminiAdapter` (Gemini Developer API / AI Studio) or `VertexAIAdapter` (Vertex AI on GCP) — and for Google's Agent2Agent ecosystem, `A2AServer` exposes this orchestrator as a discoverable A2A agent:
```typescript
import { A2AServer } from 'network-ai';
const a2a = new A2AServer({
name: 'Network-AI Orchestrator',
secret: process.env.A2A_SECRET,
executor: async (text) => ({ text: await runSwarmTask(text) }),
});
a2a.startServer(4310); // serves /.well-known/agent.json + tasks/send
```
---
## CLI
Control Network-AI directly from the terminal — no server required. The CLI imports the same core engine used by the MCP server.
```bash
# One-off commands (no server needed)
npx ts-node bin/cli.ts bb set status running --agent cli
npx ts-node bin/cli.ts bb get status
npx ts-node bin/cli.ts bb snapshot
# After npm install -g network-ai:
network-ai bb list
network-ai audit tail # live-stream the audit log
network-ai auth token my-bot --resource blackboard
```
| Command group | What it controls |
|---|---|
| `network-ai bb` | Blackboard — get, set, delete, list, snapshot, propose, commit, abort |
| `network-ai auth` | AuthGuardian — issue tokens (`--why` for scoring breakdown), revoke, check permissions |
| `network-ai budget` | FederatedBudget — spend status, set ceiling |
| `network-ai audit` | Audit log — print, live-tail, clear |
| `network-ai env` | Environment management — init, list, chain, diff, promote, backup, restore |
| `network-ai doctor` | Self-diagnostics — validate data dir, env routing, audit log, WAL, kill-switch, MCP secret |
| `network-ai inspect <key>` | Inspect a blackboard key — value, metadata, pending history, audit trail |
| `network-ai pause` / `resume` | Kill switch — write/remove `SYSTEM_PAUSED` sentinel |
Global flags on every command: `--data <path>` (data directory, default `./data`) · `--env <name>` (environment) · `--json` (machine-readable output) · `--minimal` (skip WAL replay + sweep — CI/test fast startup)
→ Full reference in [QUICKSTART.md § CLI](QUICKSTART.md)
---
## 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.
```typescript
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](QUICKSTART.md)
---
## Demo — Control-Plane Stress Test *(no API key)*
Runs in ~3 seconds. Proves the coordination primitives without any LLM calls.
```bash
npm run demo -- --08
```
What it shows: atomic blackboard locking, priority preemption (priority-3 wins over priority-0 on same key), **AuthGuardian permission gate** (blocked → justified → granted with token), FSM hard-stop at 700 ms, live compliance violation capture (TOOL_ABUSE, TURN_TAKING, RESPONSE_TIMEOUT, JOURNEY_TIMEOUT), and `FederatedBudget` tracking — all without a single API call.
[](https://www.youtube.com/watch?v=niVRZJu1MEo)
**8-agent AI pipeline** (requires `OPENAI_API_KEY` — builds a Payment Processing Service end-to-end):
```bash
npm run demo -- --07
```
[](https://youtu.be/UyMsNhaw9lU)
**NemoClaw sandbox swarm** *(no API key)* — 3 agents in isolated NVIDIA NemoClaw sandboxes with deny-by-default network policies:
```bash
npx ts-node examples/10-nemoclaw-sandbox-swarm.ts
```
[](https://www.youtube.com/watch?v=c-UWDrdP4ZE)
---
## Adapter System
32 adapters, zero adapter dependencies. You bring your own SDK objects.
| Adapter | Framework / Protocol | Register method |
|---|---|---|
| `CustomAdapter` | Any function or HTTP endpoint | `registerHandler(name, fn)` |
| `LangChainAdapter` | LangChain | `registerAgent(name, runnable)` |
| `AutoGenAdapter` | AutoGen / AG2 | `registerAgent(name, agent)` |
| `CrewAIAdapter` | CrewAI | `registerAgent` or `registerCrew` |
| `MCPAdapter` | Model Context Protocol | `registerTool(name, handler)` |
| `LlamaIndexAdapter` | LlamaIndex | `registerQueryEngine()`, `registerChatEngine()` |
| `SemanticKernelAdapter` | Microsoft Semantic Kernel | `registerKernel()`, `registerFunction()` |
| `OpenAIAssistantsAdapter` | OpenAI Assistants | `registerAssistant(name, config)` |
| `HaystackAdapter` | deepset Haystack | `registerPipeline()`, `registerAgent()` |
| `DSPyAdapter` | Stanford DSPy | `registerModule()`, `registerProgram()` |
| `AgnoAdapter` | Agno (formerly Phidata) | `registerAgent()`, `registerTeam()` |
| `OpenClawAdapter` | OpenClaw | `registerSkill(name, skillRef)` |
| `A2AAdapter` | Google A2A Protocol | `registerRemoteAgent(name, url)` |
| `CodexAdapter` | OpenAI Codex / gpt-4o / Codex CLI | `registerCodexAgent(name, config)` |
| `MiniMaxAdapter` | MiniMax LLM API (M2.5 / M2.5-highspeed) | `registerAgent(name, config)` |
| `NemoClawAdapter` | NVIDIA NemoClaw (sandboxed agents via OpenShell) | `registerSandboxAgent(name, config)` |
| `APSAdapter` | Agent Permission Service (delegation-chain trust) | `apsDelegationToTrust(delegation)` |
| `CopilotAdapter` | GitHub Copilot (generate/review/explain/fix/test/refactor/chat) | `registerAgent(name, config)` |
| `LangGraphAdapter` | LangGraph (compiled StateGraph) | `registerGraph(name, graph)` |
| `AnthropicComputerUseAdapter` | Anthropic Computer Use (screenshot/click/type/scroll) | `registerAgent(name, config)` |
| `OpenAIAgentsAdapter` | OpenAI Agents SDK (tool use, handoffs, guardrails) | `registerAgent(name, runner)` |
| `VertexAIAdapter` | Google Vertex AI / Gemini (function calling, multi-modal) | `registerAgent(name, config)` |
| `PydanticAIAdapter` | Pydantic AI (structured output, validation, deps injection) | `registerAgent(name, config)` |
| `BrowserAgentAdapter` | Browser automation (Playwright/Puppeteer/CDP) | `registerAgent(name, driver)` |
| `HermesAdapter` | NousResearch Hermes / any OpenAI-compatible endpoint (Ollama, Together AI, Fireworks, llama.cpp) | `registerAgent(name, config)` |
| `OrchestratorAdapter` | Hierarchical multi-orchestrator coordination | `registerOrchestrator(id, orchestrator)` |
| `RLMAdapter` | Recursive Language Model / any RLM-compatible HTTP endpoint (arxiv 2512.24601) | `registerAgent(name, config)` |
**Streaming variants** (drop-in replacements with `.stream()` support):
| Adapter | Extends | Streaming source |
|---|---|---|
| `LangChainStreamingAdapter` | `LangChainAdapter` | Calls `.stream()` on the Runnable if available; falls back to `.invoke()` |
| `CustomStreamingAdapter` | `CustomAdapter` | Pipes `AsyncIterable<string>` handlers; falls back to single-chunk for plain Promises |
Extend `BaseAdapter` (or `StreamingBaseAdapter` for streaming) to add your own in minutes. See [references/adapter-system.md](references/adapter-system.md).
---
## Works with LangGraph, CrewAI, and AutoGen
> Network-AI is the coordination layer you add **on top of** your existing stack. Keep your LangChain chains, CrewAI crews, and AutoGen agents — and add shared state, governance, and budgets around them.
| Capability | Network-AI | LangGraph | CrewAI | AutoGen |
|---|---|---|---|---|
| Cross-framework agents in one swarm | ✅ 29 built-in adapters | ⚠️ Nodes can call any code; no adapter abstraction | ⚠️ Extensible via tools; CrewAI-native agents only | ⚠️ Extensible via plugins; AutoGen-native agents only |
| Atomic shared state (conflict-safe) | ✅ `propose → validate → commit` mutex | ⚠️ State passed between nodes; last-write-wins | ⚠️ Shared memory available; no conflict resolution | ⚠️ Shared context available; no conflict resolution |
| Hard token ceiling per agent | ✅ `FederatedBudget` (first-class API) | ⚠️ Via callbacks / custom middleware | ⚠️ Via callbacks / custom middleware | ⚠️ Built-in token tracking in v0.4+; no swarm-level ceiling |
| Permission gating before sensitive ops | ✅ `AuthGuardian` (built-in) | ⚠️ Possible via custom node logic | ⚠️ Possible via custom tools | ⚠️ Possible via custom middleware |
| Append-only audit log | ✅ plain JSONL (`data/audit_log.jsonl`) | ⚠️ Not built-in | ⚠️ Not built-in | ⚠️ Not built-in |
| Encryption at rest | ✅ AES-256-GCM (TypeScript layer) | ⚠️ Not built-in | ⚠️ Not built-in | ⚠️ Not built-in |
| Language | TypeScript / Node.js | Python | Python | Python |
---
## Testing
```bash
npm run test:all # All suites in sequence
npm test # Core orchestrator
npm run test:security # Security module
npm run test:adapters # All 32 adapters
npm run test:streaming # Streaming adapters
npm run test:a2a # A2A protocol adapter
npm run test:codex # Codex adapter
npm run test:priority # Priority & preemption
npm run test:cli # CLI layer
npm run test:phase9 # Agent runtime, console, strategy agent
npm run test:phase12 # Context Throttler, Partition Planner, Coverage Gate, Route Classifier
```
**3,638 passing assertions across 41 test suites** (`npm run test:all`):
| Suite | Assertions | Covers |
|---|---|---|
| `test-phase4.ts` | 147 | FSM governance, compliance monitor, adapter integration |
| `test-phase5f.ts` | 127 | SSE transport, `McpCombinedBridge`, extended MCP tools |
| `test-phase5g.ts` | 121 | CRDT backend, vector clocks, bidirectional sync |
| `test-phase6.ts` | 129 | MCP server, control-plane tools, audit tools |
| `test-adapters.ts` | 271 | All 32 adapters, registry routing, integration, edge cases |
| `test-phase5d.ts` | 117 | Pluggable backend (Redis, CRDT, Memory) |
| `test-standalone.ts` | 88 | Blackboard, auth, integration, persistence, parallelisation, quality gate |
| `test-phase5e.ts` | 87 | Federated budget tracking |
| `test-phase5c.ts` | 73 | Named multi-blackboard, isolation, backend options |
| `test-codex.ts` | 51 | Codex adapter: chat, completion, CLI, BYOC client, error paths |
| `test-minimax.ts` | 50 | MiniMax adapter: lifecycle, registration, chat mode, temperature clamping |
| `test-nemoclaw.ts` | 93 | NemoClaw adapter: sandbox lifecycle, policies, blueprint, handoff, env forwarding |
| `test-priority.ts` | 64 | Priority preemption, conflict resolution, backward compat |
| `test-a2a.ts` | 35 | A2A protocol: register, execute, mock fetch, error paths |
| `test-streaming.ts` | 32 | Streaming adapters, chunk shapes, fallback, collectStream |
| `test-phase5b.ts` | 55 | Pluggable backend part 2, consistency levels |
| `test-phase5.ts` | 42 | Named multi-blackboard base |
| `test-security.ts` | 34 | Tokens, sanitization, rate limiting, encryption, audit |
| `test-cli.ts` | 65 | CLI layer: bb, auth, budget, audit commands |
| `test-qa.ts` | 67 | QA orchestrator: scenarios, feedback loop, regression, contradictions |
| `test-phase7.ts` | 94 | Deferred init, hook middleware, flow control, skill composer, semantic search |
| `test-phase8.ts` | 146 | Phase pipeline, confidence filter, matcher-based hooks, fan-out/fan-in |
| `test-phase9.ts` | 293 | Agent runtime, sandbox policy, shell executor, file accessor, approval gate, console UI, orchestrator wiring, pipe mode, strategy agent |
| `test-phase10.ts` | 153 | Goal decomposer, task DAG validation, topological layers, JSON parsing, team runner, concurrency, timeouts, events, runTeam one-liner, dependency injection, LLM planner |
| `test-phase11.ts` | 55 | TTL background sweep, WAL crash recovery, CircuitBreaker, `ITelemetryProvider` / OTel hooks |
| `test-topology.ts` | 304 | WorkTree, ControlPlane, dashboard server, topology visualization, WebSocket protocol |
| `test-rlm-phases.ts` | 123 | FederatedBudget child spending, blackboard metadata API, best-partial result, HookContext depth, sub-goal recursion, semaphore fan-out, PhasePipeline compaction, RLMAdapter end-to-end |
| `test-phase12.ts` | 65 | Context Throttler, Partition Planner, Coverage Gate, Route Classifier, EVALUATING FSM state, runTeam integration |
| `test-env-manager.ts` | 77 | Multi-environment isolation, promotion chain, backup/restore, source protection, NETWORK_AI_ENV, blackboard env routing |
| `test-transport.ts` | 117 | Basis transport tier: `TransportAgent` state machine, `LandscapeAgent` health tracking, `AgentPool` drain/pause, fleet coordination, canary, rollback |
| `test-claim-verifier.ts` | 50 | ClaimVerifier: receipt generation/tamper/expiry, corroborated/unsupported/undisclosed, trust decay/reset/DoS protection |
| `test-phase13.ts` | 58 | ESM dual-build config, McpStreamableServer dispatch + resources + prompts, PhasePipeline checkpoint/resume/clear, SemanticMemory save/load/autoSave/clearPersisted |
| `test-phase14.ts` | 52 | Model lifecycle governance: `GovernedModelGateway` refusal→fallback, `ModelBudget` credit repricing, `RefusalTelemetry`, Anthropic Messages adapter |
| `test-phase15.ts` | 32 | Orchestration resilience: `RetryBudget`, per-sub-agent fallback in `FanOutFanIn` + `TeamRunner`, `EffortPolicy` |
| `test-phase16.ts` | 21 | `ThinkingBlockManager` lifecycle + reasoning-extraction guard, OWASP Agentic Top 10 coverage matrix |
| `test-phase17.ts` | 13 | `ApprovalInbox` GHSA-m4jg-6w3q-gm86 fix: read-route auth gating, token validation, backward compatibility, CORS allowlist |
| `test-phase18.ts` | 85 | `ClaudeHookBridge` observe/enforce gating, MCP elicitation channel + fail-closed approval callback, `A2AServer` agent card / tasks / auth / eviction |
| `test-phase19.ts` | 78 | `ContextComposer` ranking/budget/pinning/staleness/layout, `estimateTokens`, `context_pack` + `blackboard_search` MCP tools (lexical + semantic modes) |
| `test-phase20.ts` | 35 | Security regressions: `ClaudeHookBridge` full-target deny/allow matching (GHSA-743h-jr5x-mpcr), `SandboxPolicy` canonicalized command matching (GHSA-9v4f-j8cv-fhxw) |
| `test.ts` | 39 | Core orchestrator smoke tests |
---
## Documentation
| Doc | Contents |
|---|---|
| [QUICKSTART.md](QUICKSTART.md) | Installation, first run, CLI reference, PowerShell guide, Python scripts CLI |
| [ARCHITECTURE.md](ARCHITECTURE.md) | Race condition problem, FSM design, handoff protocol, model-interaction lifecycle governance, module inventory, project structure |
| [BENCHMARKS.md](BENCHMARKS.md) | Provider performance, rate limits, local GPU, `max_completion_tokens` guide |
| [SECURITY.md](SECURITY.md) | Security module, permission system, trust levels, audit trail, OWASP Agentic Top 10 coverage, disclosure SLA, ClawHub scan findings |
| [THREAT_MODEL.md](THREAT_MODEL.md) | Adversary profiles, trust boundaries, explicit non-goals, security controls summary |
| [DATA_LOCATIONS.md](DATA_LOCATIONS.md) | Every file Network-AI creates — path, purpose, data classification, operator responsibilities |
| [SUPPLY_CHAIN.md](SUPPLY_CHAIN.md) | Runtime dependencies, what runs at install, network surface, SLSA/npm provenance verification |
| [ENTERPRISE.md](ENTERPRISE.md) | Evaluation checklist, stability policy, security summary, integration entry points |
| [AUDIT_LOG_SCHEMA.md](AUDIT_LOG_SCHEMA.md) | Audit log field reference, all event types (including `model.refusal` / `model.attempt`), scoring formula |
| [ADOPTERS.md](ADOPTERS.md) | Known adopters — open a PR to add yourself |
| [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) | End-to-end integration walkthrough with v5.15 modules |
| [SKILL.md](SKILL.md) | OpenClaw/ClawHub Python skill — setup, orchestrator protocol, OWASP engine coverage, security scan findings |
| [AGENTS.md](AGENTS.md) | Cross-vendor agent instructions (Codex, Gemini CLI, Cursor, Factory) — build commands, conventions, architecture patterns |
| [references/adapter-system.md](references/adapter-system.md) | Adapter architecture, all 32 adapters (incl. `AnthropicMessagesAdapter`), writing custom adapters |
| [references/auth-guardian.md](references/auth-guardian.md) | Permission scoring, resource types, `scoreRequest()`, IAuthValidator interface |
| [references/trust-levels.md](references/trust-levels.md) | Trust level configuration, APS delegation-chain mapping |
---
## Use with Claude, ChatGPT & Codex
> Using **Claude Code** (the CLI)? See [Use as a Claude Code Plugin](#use-as-a-claude-code-plugin) — one command installs every tool.
>
> Using **OpenAI Codex** (CLI or IDE)? See [Use with OpenAI Codex](#use-with-openai-codex) — add the MCP server with a single `codex mcp add`.
>
> Using **Gemini CLI**? See [Use with Gemini CLI](#use-with-gemini-cli) — install the extension with a single `gemini extensions install`.
Three integration files are included in the repo root:
| File | Use |
|---|---|
| [`claude-tools.json`](claude-tools.json) | Claude API tool use & OpenAI Codex — drop into the `tools` array |
| [`openapi.yaml`](openapi.yaml) | Custom GPT Actions — import directly in the GPT editor |
| [`claude-project-prompt.md`](claude-project-prompt.md) | Claude Projects — paste into Custom Instructions (includes lifecycle governance context) |
**Claude API / Codex:**
```js
import tools from './claude-tools.json' assert { type: 'json' };
// Pass tools array to anthropic.messages.create({ tools }) or OpenAI chat completions
```
**Custom GPT Actions:**
In the GPT editor → Actions → Import from URL, or paste the contents of `openapi.yaml`.
Set the server URL to your running `npx network-ai-server --port 3001` instance.
**Claude Projects:**
Copy the contents of `claude-project-prompt.md` (below the horizontal rule) into a Claude Project's Custom Instructions field. No server required for instruction-only mode.
---
## Community
Join our Discord server to discuss multi-agent AI coordination, get help, and share what you're building:
[](https://discord.gg/Cab5vAxc86)
---
## Contributing
1. Fork → feature branch → `npm run test:all` → pull request
2. Bugs and feature requests via [Issues](https://github.com/Jovancoding/Network-AI/issues)
---
MIT License — [LICENSE](LICENSE) · [CHANGELOG](CHANGELOG.md) · [CONTRIBUTING](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security Policy](SECURITY.md) · [](https://github.com/Jovancoding/Network-AI/releases.atom)
<details>
<summary>Keywords</summary>
multi-agent · agent orchestration · AI agents · agentic AI · agentic workflow · TypeScript · Node.js · LangGraph · CrewAI · AutoGen · MCP · model-context-protocol · LlamaIndex · Semantic Kernel · OpenAI Assistants · Haystack · DSPy · Agno · OpenClaw · ClawHub · shared state · blackboard pattern · atomic commits · guardrails · token budgets · permission gating · audit trail · agent coordination · agent handoffs · governance · cost-awareness · refusal handling · fallback routing · model lifecycle · OWASP agentic AI · effort policy · thinking blocks
</details>
## Download History
[](https://skill-history.com/jovancoding/network-ai)