network-ai 4.15.3 → 5.1.0

package/INTEGRATION_GUIDE.md

@@ -64,14 +64,16 @@ Answers drive `AuthGuardian` configuration and audit log retention policy.
 
 ## 2. Framework Mapping
 
-Network-AI ships 17 adapters. Map your existing agents to the right one:
+Network-AI ships 27 adapters. Map your existing agents to the right one:
 
 | Your Stack | Network-AI Adapter | Notes |
 |-----------|-------------------|-------|
 | LangChain (JS/TS) | `LangChainAdapter` | Supports Runnables, chains, agents |
+| LangGraph | `LangGraphAdapter` | Compiled StateGraph execution |
 | AutoGen / AG2 | `AutoGenAdapter` | Supports `.run()` and `.generateReply()` |
 | CrewAI | `CrewAIAdapter` | Individual agents and full crew objects |
 | OpenAI Assistants | `OpenAIAssistantsAdapter` | Thread management included |
+| OpenAI Agents SDK | `OpenAIAgentsAdapter` | Tool use, handoffs, guardrails |
 | LlamaIndex | `LlamaIndexAdapter` | Query engines, chat engines, agent runners |
 | Semantic Kernel | `SemanticKernelAdapter` | Microsoft SK kernels, functions, planners |
 | Haystack | `HaystackAdapter` | Pipelines, agents, components |
@@ -84,6 +86,11 @@ Network-AI ships 17 adapters. Map your existing agents to the right one:
 | MiniMax | `MiniMaxAdapter` | MiniMax chat completions (M2.5) |
 | NVIDIA NemoClaw | `NemoClawAdapter` | Sandboxed agent execution via OpenShell |
 | APS delegation chains | `APSAdapter` | Delegation-chain trust mapping for AuthGuardian |
+| GitHub Copilot | `CopilotAdapter` | Code generate/review/explain/fix/test/refactor/chat |
+| Anthropic Computer Use | `AnthropicComputerUseAdapter` | Screenshot/click/type/scroll browser automation |
+| Google Vertex AI / Gemini | `VertexAIAdapter` | Function calling, multi-modal (text+image) |
+| Pydantic AI | `PydanticAIAdapter` | Structured output with validation, deps injection |
+| Browser automation | `BrowserAgentAdapter` | Playwright/Puppeteer/CDP browser control |
 | **Anything else** | `CustomAdapter` | Wrap any async function or HTTP endpoint |
 
 ### No matching framework?
@@ -405,11 +412,11 @@ Run these before declaring the integration production-ready:
 - [ ] All agents execute via the adapter registry without errors
 - [ ] `npx ts-node test-standalone.ts` — 88 core tests pass
 - [ ] `npx ts-node test-security.ts` — 34 security tests pass
-- [ ] `npx ts-node test-adapters.ts` — 176 adapter tests pass
+- [ ] `npx ts-node test-adapters.ts` — 206 adapter tests pass
 - [ ] `npx ts-node test-phase4.ts` — 147 behavioral tests pass
 - [ ] `npx ts-node test-qa.ts` — 67 QA orchestrator tests pass
 - [ ] `npx ts-node test-phase7.ts` — 94 Phase 7 tests pass (hooks, flow control, composer, semantic search)
-- [ ] `npm run test:all` — all 2,357 tests pass across 25 suites
+- [ ] `npm run test:all` — all 2,691 tests pass across 26 suites
 - [ ] `npm run demo -- --08` runs to completion in < 10 seconds
 
 ### Race Condition Safety
@@ -467,7 +474,7 @@ Run these before declaring the integration production-ready:
 |----------|---------------|
 | [QUICKSTART.md](QUICKSTART.md) | Get running in 5 minutes |
 | [QUICKSTART.md § CLI](QUICKSTART.md) | CLI reference — bb, auth, budget, audit commands |
-| [references/adapter-system.md](references/adapter-system.md) | All 17 adapters with code examples |
+| [references/adapter-system.md](references/adapter-system.md) | All 27 adapters with code examples |
 | [references/trust-levels.md](references/trust-levels.md) | Trust scoring formula and agent roles |
 | [references/auth-guardian.md](references/auth-guardian.md) | Permission system, justification scoring, token lifecycle |
 | [references/blackboard-schema.md](references/blackboard-schema.md) | Blackboard key conventions and namespacing |
@@ -477,4 +484,4 @@ Run these before declaring the integration production-ready:
 
 ---
 
-*Network-AI v4.15.3 · MIT License · https://github.com/Jovancoding/Network-AI*
+*Network-AI v5.0.0 · MIT License · https://github.com/Jovancoding/Network-AI*

package/QUICKSTART.md

@@ -18,7 +18,7 @@ npm install
 npx ts-node setup.ts --check
 ```
 
-**Zero external AI dependencies.** All 17 adapters are self-contained — add framework SDKs only when you need them.
+**Zero external AI dependencies.** All 27 adapters are self-contained — add framework SDKs only when you need them.
 
 ---
 
@@ -43,6 +43,13 @@ npx ts-node setup.ts --check
 | `codex` | Codex | `openai` | OpenAI Codex CLI |
 | `minimax` | MiniMax | none | MiniMax chat completions |
 | `nemoclaw` | NemoClaw | none | NVIDIA sandboxed agent execution |\n| `aps` | APS | none | Delegation-chain trust mapping |
+| `copilot` | GitHub Copilot | none | Code generate/review/explain/fix/test/refactor |
+| `langgraph` | LangGraph | `@langchain/langgraph` | Compiled StateGraph execution |
+| `anthropic-computer-use` | Anthropic Computer Use | `@anthropic-ai/sdk` | Screenshot/click/type/scroll automation |
+| `openai-agents` | OpenAI Agents SDK | `openai` | Tool use, handoffs, guardrails |
+| `vertex-ai` | Vertex AI / Gemini | `@google-cloud/vertexai` | Function calling, multi-modal |
+| `pydantic-ai` | Pydantic AI | none | Structured output with validation |
+| `browser-agent` | Browser Automation | none | Playwright/Puppeteer/CDP browser control |
 
 ---
 
@@ -244,7 +251,7 @@ export class MyFrameworkAdapter extends BaseAdapter {
 ```bash
 npx ts-node test-standalone.ts    # 88 core tests
 npx ts-node test-security.ts      # 34 security tests
-npx ts-node test-adapters.ts      # 176 adapter tests (all 17 frameworks)
+npx ts-node test-adapters.ts      # 206 adapter tests (all 27 frameworks)
  npx ts-node test-cli.ts           # 65 CLI tests
 npx ts-node test-qa.ts             # 67 QA orchestrator tests
 ```
@@ -255,7 +262,7 @@ npx ts-node test-qa.ts             # 67 QA orchestrator tests
 
 ```bash
 npx ts-node setup.ts --check      # Verify installation
-npx ts-node setup.ts --list       # List all 17 adapters
+npx ts-node setup.ts --list       # List all 27 adapters
 npx ts-node setup.ts --example    # Generate example.ts
 ```
 
@@ -374,7 +381,15 @@ Your App
             ├── HaystackAdapter     ─── Haystack pipelines
             ├── DSPyAdapter         ─── DSPy modules
             ├── AgnoAdapter         ─── Agno agents/teams
-            └── APSAdapter          ─── APS delegation-chain trust
+            ├── AgnoAdapter         ─── Agno agents/teams
+            ├── APSAdapter          ─── APS delegation-chain trust
+            ├── CopilotAdapter      ─── GitHub Copilot
+            ├── LangGraphAdapter    ─── LangGraph state graphs
+            ├── VertexAIAdapter     ─── Vertex AI / Gemini
+            ├── PydanticAIAdapter   ─── Pydantic AI structured output
+            ├── OpenAIAgentsAdapter ─── OpenAI Agents SDK
+            ├── AnthropicComputerUseAdapter ─── Computer Use
+            └── BrowserAgentAdapter ─── Browser automation
 ```
 
 ---
@@ -604,13 +619,25 @@ import SwarmOrchestrator, {
 // Factory
 import { createSwarmOrchestrator } from 'network-ai';
 
-// All 17 adapters
+// All 27 adapters
 import {
   AdapterRegistry, BaseAdapter,
   OpenClawAdapter, LangChainAdapter, AutoGenAdapter,
   CrewAIAdapter, MCPAdapter, CustomAdapter,
   LlamaIndexAdapter, SemanticKernelAdapter, OpenAIAssistantsAdapter,
   HaystackAdapter, DSPyAdapter, AgnoAdapter,
+  CopilotAdapter, LangGraphAdapter, AnthropicComputerUseAdapter,
+  OpenAIAgentsAdapter, VertexAIAdapter, PydanticAIAdapter, BrowserAgentAdapter,
+} from 'network-ai';
+
+// v5.0 modules
+import {
+  AgentVCR, ComparisonRunner, CoverageReporter,
+  JobQueue, FileJobStore, ApprovalInbox,
+  SwarmTransportServer, SwarmTransportClient,
+  startPlayground, createAdapterTestSuite,
+  parseGoal, validateGoal, compileGoal,
+  NoOpAuthValidator,
 } from 'network-ai';
 
 // Types

package/README.md

@@ -5,10 +5,10 @@
 [![Website](https://img.shields.io/badge/website-network--ai.org-4b9df2?style=flat&logo=web&logoColor=white)](https://network-ai.org/)
 [![CI](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml/badge.svg)](https://github.com/Jovancoding/Network-AI/actions/workflows/codeql.yml)
-[![Release](https://img.shields.io/badge/release-v4.15.3-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v5.1.0-blue.svg)](https://github.com/Jovancoding/Network-AI/releases)
 [![npm](https://img.shields.io/npm/dw/network-ai.svg?label=npm%20downloads)](https://www.npmjs.com/package/network-ai)
-[![Tests](https://img.shields.io/badge/tests-2357%20passing-brightgreen.svg)](#testing)
-[![Adapters](https://img.shields.io/badge/frameworks-17%20supported-blueviolet.svg)](#adapter-system)
+[![Tests](https://img.shields.io/badge/tests-2691%20passing-brightgreen.svg)](#testing)
+[![Adapters](https://img.shields.io/badge/frameworks-27%20supported-blueviolet.svg)](#adapter-system)
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
 [![Socket](https://socket.dev/api/badge/npm/package/network-ai)](https://socket.dev/npm/package/network-ai/overview)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
@@ -23,12 +23,17 @@
   <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
-- **17 adapters** — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Custom (+ streaming), OpenClaw, A2A, Codex, MiniMax, NemoClaw, and APS — no glue code, no lock-in
+- **27 adapters** — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Custom (+ streaming), OpenClaw, A2A, Codex, MiniMax, NemoClaw, APS, Copilot, LangGraph, Anthropic Computer Use, OpenAI Agents SDK, Vertex AI, Pydantic AI, Browser Agent, and Orchestrator (hierarchical multi-orchestrator) — 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
 
 > **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.
@@ -85,7 +90,7 @@ Runs priority preemption, AuthGuardian permission gating, FSM governance, and co
 | ✅ 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 |
-| ✅ 17 framework adapters | LangChain, CrewAI, AutoGen, MCP, Codex, APS, and 11 more — zero lock-in |
+| ✅ 27 framework adapters | LangChain, CrewAI, AutoGen, MCP, Codex, APS, and 21 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) |
 | ✅ QA orchestration | Scenario replay, feedback loops, regression tracking, contradiction detection |
@@ -103,6 +108,16 @@ Runs priority preemption, AuthGuardian permission gating, FSM governance, and co
 | ✅ 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 |
+| ✅ 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 |
+| ✅ 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 |
 | ✅ TypeScript native | ES2022 strict mode, zero native dependencies |
 
 ---
@@ -114,7 +129,7 @@ Runs priority preemption, AuthGuardian permission gating, FSM governance, and co
 | 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 | 17 adapters — mix LangChain + AutoGen + CrewAI + Codex + MiniMax + NemoClaw + APS + custom in one swarm |
+| Locked into one AI framework | 27 adapters — mix LangChain + AutoGen + CrewAI + Codex + MiniMax + NemoClaw + APS + LangGraph + Vertex AI + 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 |
@@ -335,7 +350,7 @@ npx ts-node examples/10-nemoclaw-sandbox-swarm.ts
 
 ## Adapter System
 
-17 adapters, zero adapter dependencies. You bring your own SDK objects.
+27 adapters, zero adapter dependencies. You bring your own SDK objects.
 
 | Adapter | Framework / Protocol | Register method |
 |---|---|---|
@@ -356,6 +371,14 @@ npx ts-node examples/10-nemoclaw-sandbox-swarm.ts
 | `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)` |
+| `OrchestratorAdapter` | Hierarchical multi-orchestrator coordination | `registerOrchestrator(id, orchestrator)` |
 
 **Streaming variants** (drop-in replacements with `.stream()` support):
 
@@ -374,7 +397,7 @@ Extend `BaseAdapter` (or `StreamingBaseAdapter` for streaming) to add your own i
 
 | Capability | Network-AI | LangGraph | CrewAI | AutoGen |
 |---|---|---|---|---|
-| Cross-framework agents in one swarm | ✅ 17 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 |
+| Cross-framework agents in one swarm | ✅ 27 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 |
@@ -390,7 +413,7 @@ Extend `BaseAdapter` (or `StreamingBaseAdapter` for streaming) to add your own i
 npm run test:all          # All suites in sequence
 npm test                  # Core orchestrator
 npm run test:security     # Security module
-npm run test:adapters     # All 17 adapters
+npm run test:adapters     # All 27 adapters
 npm run test:streaming    # Streaming adapters
 npm run test:a2a          # A2A protocol adapter
 npm run test:codex        # Codex adapter
@@ -400,7 +423,7 @@ npm run test:phase9       # Agent runtime, console, strategy agent
 npm run test:phase10      # Goal decomposer, task DAG, runTeam
 ```
 
-**2,357 passing assertions across 25 test suites** (`npm run test:all`):
+**2,691 passing assertions across 26 test suites** (`npm run test:all`):
 
 | Suite | Assertions | Covers |
 |---|---|---|
@@ -408,7 +431,7 @@ npm run test:phase10      # Goal decomposer, task DAG, runTeam
 | `test-phase5f.ts` | 127 | SSE transport, `McpCombinedBridge`, extended MCP tools |
 | `test-phase5g.ts` | 121 | CRDT backend, vector clocks, bidirectional sync |
 | `test-phase6.ts` | 121 | MCP server, control-plane tools, audit tools |
-| `test-adapters.ts` | 176 | All 17 adapters, registry routing, integration, edge cases |
+| `test-adapters.ts` | 206 | All 27 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 |
@@ -428,6 +451,8 @@ npm run test:phase10      # Goal decomposer, task DAG, runTeam
 | `test-phase8.ts` | 146 | Phase pipeline, confidence filter, matcher-based hooks, fan-out/fan-in |
 | `test-phase9.ts` | 280 | 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-topology.ts` | 304 | WorkTree, ControlPlane, dashboard server, topology visualization, WebSocket protocol |
+| `test.ts` | 39 | Core orchestrator smoke tests |
 
 ---
 
@@ -436,16 +461,16 @@ npm run test:phase10      # Goal decomposer, task DAG, runTeam
 | 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, project structure |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | Race condition problem, FSM design, handoff protocol, 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 |
+| [SECURITY.md](SECURITY.md) | Security module, permission system, trust levels, audit trail, v5.0 security additions |
 | [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, 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 |
-| [references/adapter-system.md](references/adapter-system.md) | Adapter architecture, writing custom adapters |
-| [references/auth-guardian.md](references/auth-guardian.md) | Permission scoring, resource types |
-| [references/trust-levels.md](references/trust-levels.md) | Trust level configuration |
+| [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) | End-to-end integration walkthrough with v5.0 modules |
+| [references/adapter-system.md](references/adapter-system.md) | Adapter architecture, all 27 adapters, writing custom adapters |
+| [references/auth-guardian.md](references/auth-guardian.md) | Permission scoring, resource types, IAuthValidator interface |
+| [references/trust-levels.md](references/trust-levels.md) | Trust level configuration, APS delegation-chain mapping |
 
 ---
 

package/bin/dashboard.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Dashboard CLI entry point
+ *
+ * Launches the live agent topology dashboard on localhost.
+ * Usage: npx network-ai-dashboard [--port 4820]
+ *
+ * @module DashboardCLI
+ */
+
+import { TopologyTracker } from '../lib/topology';
+import { DashboardServer } from '../lib/dashboard-server';
+
+const args = process.argv.slice(2);
+let port = 4820;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--port' && args[i + 1]) {
+    const p = parseInt(args[i + 1], 10);
+    if (!isNaN(p) && p > 0 && p < 65536) {
+      port = p;
+    }
+    i++;
+  }
+}
+
+const tracker = new TopologyTracker();
+const dashboard = new DashboardServer(tracker, { port });
+
+async function main(): Promise<void> {
+  await dashboard.start();
+
+  console.log(`
+  ╔══════════════════════════════════════════════════════╗
+  ║  Network-AI Live Agent Topology Dashboard            ║
+  ║                                                      ║
+  ║  Dashboard: http://127.0.0.1:${String(port).padEnd(5)}                  ║
+  ║  WebSocket: ws://127.0.0.1:${String(port).padEnd(5)}                   ║
+  ║                                                      ║
+  ║  Press Ctrl+C to stop                                ║
+  ╚══════════════════════════════════════════════════════╝
+  `);
+
+  // Demo: spawn some agents to show the dashboard working
+  // In real usage, the orchestrator feeds real events
+  if (args.includes('--demo')) {
+    runDemo(tracker);
+  }
+}
+
+/**
+ * Runs a demo simulation with fake agents for demonstration purposes.
+ */
+function runDemo(topo: TopologyTracker): void {
+  console.log('  Running demo simulation...\n');
+
+  topo.addAgent({ id: 'orchestrator', label: 'Orchestrator', role: 'orchestrator' });
+  topo.addAgent({ id: 'planner', label: 'Planner', role: 'planner', adapter: 'custom' });
+  topo.addAgent({ id: 'lc:researcher', label: 'Researcher', role: 'worker', adapter: 'langchain', tokenBudget: 5000 });
+  topo.addAgent({ id: 'lc:writer', label: 'Writer', role: 'worker', adapter: 'langchain', tokenBudget: 8000 });
+  topo.addAgent({ id: 'crew:reviewer', label: 'Reviewer', role: 'validator', adapter: 'crewai', tokenBudget: 3000 });
+  topo.addAgent({ id: 'aggregator', label: 'Aggregator', role: 'aggregator', adapter: 'custom' });
+
+  topo.setStatus('orchestrator', 'running');
+
+  let step = 0;
+  const interval = setInterval(() => {
+    step++;
+
+    switch (step) {
+      case 1:
+        topo.setStatus('planner', 'running');
+        topo.setTask('planner', 'Decomposing goal into tasks');
+        topo.addEdge('orchestrator', 'planner', 'delegation', 'plan');
+        break;
+      case 3:
+        topo.setStatus('planner', 'completed');
+        topo.addEdge('planner', 'orchestrator', 'result', 'task DAG');
+        topo.setStatus('lc:researcher', 'running');
+        topo.setStatus('lc:writer', 'running');
+        topo.setTask('lc:researcher', 'Analyzing codebase');
+        topo.setTask('lc:writer', 'Drafting documentation');
+        topo.addEdge('orchestrator', 'lc:researcher', 'delegation', 'research');
+        topo.addEdge('orchestrator', 'lc:writer', 'delegation', 'write');
+        break;
+      case 5:
+        topo.addTokens('lc:researcher', 1200);
+        topo.addTokens('lc:writer', 800);
+        topo.addEdge('lc:researcher', '_blackboard', 'blackboard_write', 'analysis:result');
+        break;
+      case 7:
+        topo.addTokens('lc:researcher', 2100);
+        topo.addTokens('lc:writer', 2500);
+        topo.addEdge('lc:writer', '_blackboard', 'blackboard_write', 'draft:v1');
+        topo.setStatus('lc:researcher', 'completed');
+        topo.setTask('lc:researcher', undefined);
+        break;
+      case 9:
+        topo.addTokens('lc:writer', 4200);
+        topo.setStatus('lc:writer', 'completed');
+        topo.setTask('lc:writer', undefined);
+        topo.setStatus('crew:reviewer', 'running');
+        topo.setTask('crew:reviewer', 'Reviewing draft');
+        topo.addEdge('crew:reviewer', '_blackboard', 'blackboard_read', 'draft:v1');
+        topo.addEdge('orchestrator', 'crew:reviewer', 'delegation', 'review');
+        break;
+      case 11:
+        topo.addTokens('crew:reviewer', 1500);
+        topo.setStatus('crew:reviewer', 'completed');
+        topo.addEdge('crew:reviewer', '_blackboard', 'blackboard_write', 'review:feedback');
+        topo.setStatus('aggregator', 'running');
+        topo.setTask('aggregator', 'Merging results');
+        topo.addEdge('aggregator', '_blackboard', 'blackboard_read', 'analysis:result');
+        topo.addEdge('orchestrator', 'aggregator', 'delegation', 'aggregate');
+        break;
+      case 13:
+        topo.setStatus('aggregator', 'completed');
+        topo.addEdge('aggregator', 'orchestrator', 'result', 'final output');
+        topo.setStatus('orchestrator', 'completed');
+        topo.setTask('orchestrator', 'Done');
+        break;
+      case 16:
+        // Reset for loop
+        step = 0;
+        topo.clear();
+        topo.addAgent({ id: 'orchestrator', label: 'Orchestrator', role: 'orchestrator' });
+        topo.addAgent({ id: 'planner', label: 'Planner', role: 'planner', adapter: 'custom' });
+        topo.addAgent({ id: 'lc:researcher', label: 'Researcher', role: 'worker', adapter: 'langchain', tokenBudget: 5000 });
+        topo.addAgent({ id: 'lc:writer', label: 'Writer', role: 'worker', adapter: 'langchain', tokenBudget: 8000 });
+        topo.addAgent({ id: 'crew:reviewer', label: 'Reviewer', role: 'validator', adapter: 'crewai', tokenBudget: 3000 });
+        topo.addAgent({ id: 'aggregator', label: 'Aggregator', role: 'aggregator', adapter: 'custom' });
+        topo.setStatus('orchestrator', 'running');
+        break;
+    }
+  }, 1500);
+
+  process.on('SIGINT', () => {
+    clearInterval(interval);
+    dashboard.stop().then(() => process.exit(0));
+  });
+}
+
+main().catch((err) => {
+  console.error('Failed to start dashboard:', err);
+  process.exit(1);
+});

package/bin/mcp-server.ts

@@ -162,11 +162,12 @@ async function runStdio(combined: McpCombinedBridge): Promise<void> {
     let request: McpJsonRpcRequest;
     try {
       request = JSON.parse(trimmed);
-    } catch {
+    } catch (parseErr) {
+      const detail = parseErr instanceof Error ? parseErr.message : String(parseErr);
       const err = {
         jsonrpc: '2.0' as const,
         id: null,
-        error: { code: -32700, message: 'Parse error' },
+        error: { code: -32700, message: `Parse error: ${detail}` },
       };
       process.stdout.write(JSON.stringify(err) + '\n');
       return;

package/dist/adapters/adapter-registry.d.ts

@@ -14,6 +14,22 @@ import type { IAgentAdapter, AdapterConfig, AdapterRoute, RegistryConfig, AgentP
  * Used with registerDeferred() for lazy initialization.
  */
 export type AdapterFactory = () => IAgentAdapter;
+/**
+ * Configurable retry behaviour for adapter execution.
+ *
+ * The policy uses exponential backoff with optional jitter.
+ * Only errors marked `recoverable` in the {@link AgentResult} trigger a retry.
+ */
+export interface RetryPolicy {
+    /** Maximum number of retry attempts (0 = no retries, default). */
+    maxRetries: number;
+    /** Base delay in ms before the first retry (doubled each attempt). */
+    baseDelayMs: number;
+    /** Maximum delay cap in ms. */
+    maxDelayMs: number;
+    /** Optional fallback adapter name to try when all retries are exhausted. */
+    fallbackAdapter?: string;
+}
 /**
  * Central registry that manages multiple agent framework adapters and
  * routes execution requests to the correct one.
@@ -42,7 +58,15 @@ export declare class AdapterRegistry {
     private eventHandlers;
     private agentCache;
     private deferredFactories;
-    constructor(config?: RegistryConfig);
+    /** Opt-in retry policy for adapter execution. */
+    private retryPolicy;
+    constructor(config?: RegistryConfig & {
+        retryPolicy?: Partial<RetryPolicy>;
+    });
+    /**
+     * Update the retry policy at runtime.
+     */
+    setRetryPolicy(policy: Partial<RetryPolicy>): void;
     /**
      * Register an adapter with the registry.
      * Call this for each agent framework you want to support.
@@ -120,6 +144,14 @@ export declare class AdapterRegistry {
      * This is the primary method the SwarmOrchestrator calls.
      */
     executeAgent(agentId: string, payload: AgentPayload, context: AgentContext): Promise<AgentResult>;
+    /**
+     * Execute with exponential-backoff retries for recoverable errors.
+     */
+    private executeWithRetry;
+    /**
+     * Single adapter execution attempt with event emission.
+     */
+    private executeOnce;
     /**
      * Discover all agents across all registered adapters
      */

package/dist/adapters/adapter-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter-registry.d.ts","sourceRoot":"","sources":["../../adapters/adapter-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter-registry.d.ts","sourceRoot":"","sources":["../../adapters/adapter-registry.ts"],"names":[],"mappings":"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"}

package/dist/adapters/adapter-registry.js

@@ -13,6 +13,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdapterRegistry = void 0;
 exports.getRegistry = getRegistry;
 const errors_1 = require("../lib/errors");
+const DEFAULT_RETRY_POLICY = {
+    maxRetries: 0,
+    baseDelayMs: 200,
+    maxDelayMs: 5000,
+};
 /**
  * Central registry that manages multiple agent framework adapters and
  * routes execution requests to the correct one.
@@ -41,11 +46,20 @@ class AdapterRegistry {
     eventHandlers = new Map();
     agentCache = new Map(); // agentId -> adapterName
     deferredFactories = new Map();
+    /** Opt-in retry policy for adapter execution. */
+    retryPolicy;
     constructor(config) {
         if (config) {
             this.defaultAdapterName = config.defaultAdapter ?? null;
             this.routes = config.routes ?? [];
         }
+        this.retryPolicy = { ...DEFAULT_RETRY_POLICY, ...config?.retryPolicy };
+    }
+    /**
+     * Update the retry policy at runtime.
+     */
+    setRetryPolicy(policy) {
+        this.retryPolicy = { ...this.retryPolicy, ...policy };
     }
     // =========================================================================
     // ADAPTER MANAGEMENT
@@ -325,6 +339,41 @@ class AdapterRegistry {
                 },
             };
         }
+        const result = await this.executeWithRetry(adapter, agentId, payload, context);
+        // If all retries exhausted and a fallback adapter is configured, try it
+        if (!result.success && result.error?.recoverable && this.retryPolicy.fallbackAdapter) {
+            const fallback = this.adapters.get(this.retryPolicy.fallbackAdapter);
+            if (fallback && fallback !== adapter) {
+                this.emit('agent:execution:fallback', this.retryPolicy.fallbackAdapter, { agentId, originalAdapter: adapter.name });
+                return this.executeOnce(fallback, agentId, payload, context);
+            }
+        }
+        return result;
+    }
+    /**
+     * Execute with exponential-backoff retries for recoverable errors.
+     */
+    async executeWithRetry(adapter, agentId, payload, context) {
+        let lastResult = await this.executeOnce(adapter, agentId, payload, context);
+        let attempt = 0;
+        while (attempt < this.retryPolicy.maxRetries &&
+            !lastResult.success &&
+            lastResult.error?.recoverable) {
+            attempt++;
+            const delay = Math.min(this.retryPolicy.baseDelayMs * Math.pow(2, attempt - 1), this.retryPolicy.maxDelayMs);
+            await new Promise(r => setTimeout(r, delay));
+            this.emit('agent:execution:retry', adapter.name, { agentId, attempt, delayMs: delay });
+            lastResult = await this.executeOnce(adapter, agentId, payload, context);
+        }
+        if (lastResult.metadata) {
+            lastResult.metadata.retryAttempts = attempt;
+        }
+        return lastResult;
+    }
+    /**
+     * Single adapter execution attempt with event emission.
+     */
+    async executeOnce(adapter, agentId, payload, context) {
         this.emit('agent:execution:start', adapter.name, { agentId, payload });
         const startTime = Date.now();
         try {