network-ai 4.0.16 → 4.1.0

package/README.md

@@ -1,13 +1,13 @@
-# Network-AI
+# Network-AI
 
 **TypeScript/Node.js multi-agent orchestrator — shared state, guardrails, budgets, and cross-framework coordination**
 
 [![CI](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/ci.yml/badge.svg)](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/codeql.yml/badge.svg)](https://github.com/jovanSAPFIONEER/Network-AI/actions/workflows/codeql.yml)
-[![Release](https://img.shields.io/badge/release-v4.0.16-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v4.1.0-blue.svg)](https://github.com/jovanSAPFIONEER/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-1184%20passing-brightgreen.svg)](#testing)
-[![Adapters](https://img.shields.io/badge/frameworks-12%20supported-blueviolet.svg)](#adapter-system)
+[![Tests](https://img.shields.io/badge/tests-1283%20passing-brightgreen.svg)](#testing)
+[![Adapters](https://img.shields.io/badge/frameworks-13%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)
@@ -19,7 +19,13 @@ Network-AI is a TypeScript/Node.js multi-agent orchestrator that adds coordinati
 
 - **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 audit trails, and permission gating
-- **12 framework adapters** — LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, and more in one orchestrator — no glue code, no lock-in
+- **13 adapters** — LangChain (+ streaming), AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, Custom (+ streaming), OpenClaw, and A2A — no glue code, no lock-in
+
+> **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'`
@@ -28,6 +34,15 @@ Network-AI is a TypeScript/Node.js multi-agent orchestrator that adds coordinati
 
 [**5-minute quickstart →**](QUICKSTART.md)  |  [**Architecture →**](ARCHITECTURE.md)  |  [**All adapters →**](#adapter-system)  |  [**Benchmarks →**](BENCHMARKS.md)
 
+> **Try the control-plane 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 against a live swarm. No external services required.
+>
+> If it saves you from a race condition, a ⭐ helps others find it.
+
 ---
 
 ## Why teams use Network-AI
@@ -37,38 +52,44 @@ Network-AI is a TypeScript/Node.js multi-agent orchestrator that adds coordinati
 | 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-signed audit log on every write, permission grant, and FSM transition |
-| Locked into one AI framework | 12 adapters — mix LangChain + AutoGen + CrewAI + custom in one swarm |
+| Locked into one AI framework | 13 adapters — mix LangChain + AutoGen + CrewAI + A2A + custom in one swarm |
 | Agents escalating beyond their scope | `AuthGuardian` — scoped permission tokens required before sensitive operations |
 
 ---
 
 ## 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(permission gating)"]:::security
+        AR["AdapterRegistry\n(route tasks to frameworks)"]:::routing
+        QG["QualityGateAgent\n(validate blackboard writes)"]:::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
+    end
+
+    SO --> AUDIT["data/audit_log.jsonl"]:::audit
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                     Your Application                        │
-└──────────────────────────┬──────────────────────────────────┘
-                           │  createSwarmOrchestrator()
-┌──────────────────────────▼──────────────────────────────────┐
-│                  SwarmOrchestrator                          │
-│  ┌──────────────┐  ┌───────────────┐  ┌─────────────────┐  │
-│  │ AdapterRegistry│  │ AuthGuardian  │  │ FederatedBudget │  │
-│  │ (route tasks) │  │ (permissions) │  │ (token ceilings)│  │
-│  └──────┬───────┘  └───────────────┘  └─────────────────┘  │
-│         │                                                    │
-│  ┌──────▼──────────────────────────────────────────────┐   │
-│  │            LockedBlackboard (shared state)           │   │
-│  │   propose → validate → commit  (file-system mutex)  │   │
-│  └──────────────────────────────────────────────────────┘   │
-│         │                                                    │
-│  ┌──────▼───────────────────────────────────────────────┐  │
-│  │  Adapters (plug any framework in, swap out freely)   │  │
-│  │  LangChain │ AutoGen │ CrewAI │ MCP │ LlamaIndex │…  │  │
-│  └──────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-                           │
-              HMAC-signed audit log
-```
+
+> `FederatedBudget` is a standalone export — instantiate it separately and optionally wire it to a blackboard backend for cross-node token budget enforcement.
 
 → [Full architecture, FSM journey, and handoff protocol](ARCHITECTURE.md)
 
@@ -84,6 +105,64 @@ No native dependencies, no build step. Adapters are dependency-free (BYOC — br
 
 ---
 
+## 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`
+- `budget_status` / `budget_spend` / `budget_reset` — federated token tracking
+- `token_create` / `token_validate` / `token_revoke` — HMAC-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>`.
+
+---
+
 ## 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.
@@ -129,13 +208,15 @@ Add budgets, permissions, and cross-framework agents with the same pattern. →
 
 ## Demo — Control-Plane Stress Test *(no API key)*
 
-Runs in ~2 seconds. Proves the coordination primitives without any LLM calls.
+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), 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.
+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.
+
+[![Control Plane Demo](https://img.youtube.com/vi/niVRZJu1MEo/0.jpg)](https://www.youtube.com/watch?v=niVRZJu1MEo)
 
 **8-agent AI pipeline** (requires `OPENAI_API_KEY` — builds a Payment Processing Service end-to-end):
 
@@ -149,12 +230,12 @@ npm run demo -- --07
 
 ## Adapter System
 
-12 frameworks, zero adapter dependencies. You bring your own SDK objects.
+13 adapters, zero adapter dependencies. You bring your own SDK objects.
 
-| Adapter | Framework | Register method |
+| Adapter | Framework / Protocol | Register method |
 |---|---|---|
 | `CustomAdapter` | Any function or HTTP endpoint | `registerHandler(name, fn)` |
-| `LangChainAdapter` | LangChain | `registerRunnable(name, runnable)` |
+| `LangChainAdapter` | LangChain | `registerAgent(name, runnable)` |
 | `AutoGenAdapter` | AutoGen / AG2 | `registerAgent(name, agent)` |
 | `CrewAIAdapter` | CrewAI | `registerAgent` or `registerCrew` |
 | `MCPAdapter` | Model Context Protocol | `registerTool(name, handler)` |
@@ -165,8 +246,16 @@ npm run demo -- --07
 | `DSPyAdapter` | Stanford DSPy | `registerModule()`, `registerProgram()` |
 | `AgnoAdapter` | Agno (formerly Phidata) | `registerAgent()`, `registerTeam()` |
 | `OpenClawAdapter` | OpenClaw | `registerSkill(name, skillRef)` |
+| `A2AAdapter` | Google A2A Protocol | `registerRemoteAgent(name, url)` |
 
-Extend `BaseAdapter` to add your own in minutes. See [references/adapter-system.md](references/adapter-system.md).
+**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).
 
 ---
 
@@ -176,12 +265,12 @@ Extend `BaseAdapter` to add your own in minutes. See [references/adapter-system.
 
 | Capability | Network-AI | LangGraph | CrewAI | AutoGen |
 |---|---|---|---|---|
-| Cross-framework agents in one swarm | ✅ 12 adapters | ❌ LangChain only | ❌ CrewAI only | ❌ AutoGen only |
-| Atomic shared state (conflict-safe) | ✅ `propose → validate → commit` | ⚠️ Last-write-wins | ⚠️ Last-write-wins | ⚠️ Last-write-wins |
-| Hard budget ceiling per agent | ✅ `FederatedBudget` | ⚠️ Callbacks only | ❌ | ❌ |
-| Permission gating before sensitive ops | ✅ `AuthGuardian` | ❌ | ❌ | ❌ |
-| Tamper-evident audit trail | ✅ HMAC-signed | ❌ | ❌ | ❌ |
-| Encryption at rest | ✅ AES-256-GCM | ❌ | ❌ | ❌ |
+| Cross-framework agents in one swarm | ✅ 13 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 |
 
 ---
@@ -192,29 +281,31 @@ Extend `BaseAdapter` to add your own in minutes. See [references/adapter-system.
 npm run test:all          # All suites in sequence
 npm test                  # Core orchestrator
 npm run test:security     # Security module
-npm run test:adapters     # All 12 adapters
+npm run test:adapters     # All 13 adapters
+npm run test:streaming    # Streaming adapters
+npm run test:a2a          # A2A protocol adapter
 npm run test:priority     # Priority & preemption
 ```
 
-**1,184 passing assertions across 15 test suites** (verified by counting `assert()` / `pass()` calls in each file):
+**1,283 passing assertions across 15 test suites** (`npm run test:all`):
 
 | Suite | Assertions | Covers |
 |---|---|---|
-| `test-standalone.ts` | 83 | Blackboard, auth, integration, persistence, parallelisation, quality gate |
-| `test-adapters.ts` | 142 | All 12 adapters, registry routing, integration, edge cases |
-| `test-phase4.ts` | 133 | FSM, compliance monitor, adapter integration |
-| `test-phase5d.ts` | 119 | Pluggable backend |
-| `test-phase5f.ts` | 113 | Phase 5f extended |
-| `test-phase5g.ts` | 106 | Phase 5g extended |
-| `test-phase6.ts` | 122 | Latest feature coverage |
-| `test-phase5c.ts` | 74 | Named multi-blackboard |
-| `test-phase5e.ts` | 88 | Phase 5e |
-| `test-phase5b.ts` | 56 | Pluggable backend part 2 |
-| `test-priority.ts` | 65 | Priority preemption, conflict resolution, backward compat |
-| `test-security.ts` | 35 | Tokens, sanitization, rate limiting, encryption, audit |
-| `test-phase5.ts` | 24 | Named multi-blackboard base |
-| `test.ts` | 24 | Full integration |
-| `test-phase4.ts` (stubs) | 4 | FSM stub coverage |
+| `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` | 121 | MCP server, control-plane tools, audit tools |
+| `test-phase5d.ts` | 117 | Pluggable backend (Redis, CRDT, Memory) |
+| `test-adapters.ts` | 139 | All 13 adapters, registry routing, integration, edge cases |
+| `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-priority.ts` | 64 | Priority preemption, conflict resolution, backward compat |
+| `test-a2a.ts` | 34 | A2A protocol: register, execute, mock fetch, error paths |
+| `test-streaming.ts` | 31 | 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 |
 
 ---
 
@@ -240,17 +331,14 @@ npm run test:priority     # Priority & preemption
 
 1. Fork → feature branch → `npm run test:all` → pull request
 2. Bugs and feature requests via [Issues](https://github.com/jovanSAPFIONEER/Network-AI/issues)
-3. If Network-AI saves you time, a ⭐ helps others find it
-
-[![Star on GitHub](https://img.shields.io/github/stars/jovanSAPFIONEER/Network-AI?style=social)](https://github.com/jovanSAPFIONEER/Network-AI)
 
 ---
 
 MIT License — [LICENSE](LICENSE) &nbsp;·&nbsp; [CHANGELOG](CHANGELOG.md) &nbsp;·&nbsp; [CONTRIBUTING](CONTRIBUTING.md) &nbsp;·&nbsp; [![RSS](https://img.shields.io/badge/RSS-releases-orange?logo=rss)](https://github.com/jovanSAPFIONEER/Network-AI/releases.atom)
 
 <details>
-<summary>Keywords (for search)</summary>
+<summary>Keywords</summary>
 
-ai-agents, agentic-ai, multi-agent, multi-agent-systems, multi-agent-system, agent-framework, ai-agent-framework, agentic-framework, agentic-workflow, llm, llm-agents, llm-agent, large-language-models, generative-ai, genai, orchestration, ai-orchestration, swarm, swarm-intelligence, autonomous-agents, agents, ai, typescript, nodejs, mcp, model-context-protocol, a2a, agent-to-agent, function-calling, tool-integration, context-engineering, rag, ai-safety, multi-agents-collaboration, multi-agents, aiagents, aiagentframework, plug-and-play, adapter-registry, blackboard-pattern, agent-coordination, agent-handoffs, token-permissions, budget-tracking, cost-awareness, atomic-commits, hallucination-detection, content-quality-gate, behavioral-control-plane, governance-layer, compliance-enforcement, fan-out-fan-in, agent-observability, permission-gating, audit-trail, OpenClaw, ClawHub, clawhub, AgentSkills, LangChain adapter, LangGraph, AutoGen adapter, AG2, CrewAI adapter, MCP adapter, LlamaIndex adapter, Semantic Kernel adapter, OpenAI Assistants adapter, Haystack adapter, DSPy adapter, Agno adapter, custom-adapter, AES-256 encryption, HMAC tokens, rate limiting, input sanitization, privilege escalation prevention, agentic-rag, deep-research, workflow-orchestration, ai-assistant, ai-tools, developer-tools, open-source
+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
 
 </details>

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

@@ -0,0 +1,152 @@
+/**
+ * A2AAdapter — Agent-to-Agent (A2A) protocol adapter.
+ *
+ * Implements the Google A2A (Agent-to-Agent) open protocol that lets
+ * independently hosted agents discover each other through a standard
+ * Agent Card (/.well-known/agent.json) and exchange tasks via a
+ * JSON-RPC envelope posted to the agent's task endpoint.
+ *
+ * References:
+ *   https://google.github.io/A2A/
+ *   https://github.com/google/A2A
+ *
+ * Usage:
+ *
+ *   const adapter = new A2AAdapter();
+ *   await adapter.initialize({});
+ *
+ *   // Register a remote agent by its Agent Card URL
+ *   await adapter.registerRemoteAgent('remote-analyst', 'https://agent.example.com');
+ *
+ *   // Or register a local agent that serves an A2A-compliant card
+ *   adapter.registerLocalA2AAgent('local-writer', {
+ *     name: 'Writing Agent',
+ *     description: 'Draft documents given a topic',
+ *     version: '1.0',
+ *     capabilities: { streaming: false },
+ *     taskEndpoint: 'https://writer.internal/tasks',
+ *   });
+ *
+ *   await registry.addAdapter(adapter);
+ *
+ *   // In the orchestrator:
+ *   delegateTask({ targetAgent: 'a2a:remote-analyst', ... })
+ *
+ * @module A2AAdapter
+ * @version 1.0.0
+ */
+import { BaseAdapter } from './base-adapter';
+import type { AdapterConfig, AdapterCapabilities, AgentPayload, AgentContext, AgentResult } from '../types/agent-adapter';
+/** Agent Card served at /.well-known/agent.json (A2A spec §3.1) */
+export interface A2AAgentCard {
+    /** Human-readable agent name */
+    name: string;
+    /** Purpose / capabilities in plain English */
+    description?: string;
+    /** SemVer */
+    version?: string;
+    /** Protocol capabilities declared by the agent */
+    capabilities?: {
+        streaming?: boolean;
+        pushNotifications?: boolean;
+        stateTransitionHistory?: boolean;
+    };
+    /** URL that accepts A2A task envelopes (defaults to <baseUrl>/tasks) */
+    taskEndpoint?: string;
+    /** Agent homepage or further docs */
+    url?: string;
+}
+/** JSON-RPC 2.0 task request envelope sent to the task endpoint (A2A spec §4) */
+export interface A2ATask {
+    jsonrpc: '2.0';
+    id: string;
+    method: 'tasks/send';
+    params: {
+        id: string;
+        message: {
+            role: 'user';
+            parts: Array<{
+                type: 'text';
+                text: string;
+            }>;
+        };
+        metadata?: Record<string, unknown>;
+    };
+}
+/** State of a running A2A task */
+export type A2ATaskState = 'submitted' | 'working' | 'input-required' | 'completed' | 'canceled' | 'failed' | 'unknown';
+/** Artifact produced by the agent (A2A spec §4.3) */
+export interface A2AArtifact {
+    name?: string;
+    description?: string;
+    parts: Array<{
+        type: string;
+        text?: string;
+        data?: unknown;
+    }>;
+}
+/** JSON-RPC 2.0 task response (A2A spec §4) */
+export interface A2ATaskResponse {
+    jsonrpc: '2.0';
+    id: string;
+    result?: {
+        id: string;
+        status: {
+            state: A2ATaskState;
+            message?: string;
+        };
+        artifacts?: A2AArtifact[];
+        metadata?: Record<string, unknown>;
+    };
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** Adapter configuration specific to A2A */
+export interface A2AAdapterConfig extends AdapterConfig {
+    /** Default bearer token applied to all agents unless overridden at agent level */
+    defaultBearerToken?: string;
+    /** Default timeout for all agents in ms (default: 30 000) */
+    defaultTimeoutMs?: number;
+    /** Custom fetch implementation (for testing / node compat) */
+    fetchImpl?: typeof fetch;
+}
+export declare class A2AAdapter extends BaseAdapter {
+    readonly name = "a2a";
+    readonly version = "1.0.0";
+    private a2aAgents;
+    private defaultBearerToken?;
+    private defaultTimeoutMs;
+    private fetchImpl;
+    get capabilities(): AdapterCapabilities;
+    initialize(config: A2AAdapterConfig): Promise<void>;
+    /**
+     * Fetch the Agent Card from `<baseUrl>/.well-known/agent.json` and register
+     * the remote agent for use in the orchestrator.
+     *
+     * @param agentId  - Local identifier (used in `delegate_task` calls)
+     * @param baseUrl  - Root URL of the remote A2A-compliant agent server
+     * @param options  - Optional bearer token / timeout override
+     */
+    registerRemoteAgent(agentId: string, baseUrl: string, options?: {
+        bearerToken?: string;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Register a local A2A agent whose card you already have (no network fetch).
+     * Useful when the card is embedded in config or returned from another service.
+     */
+    registerLocalA2AAgent(agentId: string, card: A2AAgentCard & {
+        taskEndpoint: string;
+    }, options?: {
+        bearerToken?: string;
+        timeoutMs?: number;
+    }): void;
+    executeAgent(agentId: string, payload: AgentPayload, context: AgentContext): Promise<AgentResult>;
+    private fetchAgentCard;
+    private sendTask;
+    private extractOutput;
+}
+//# sourceMappingURL=a2a-adapter.d.ts.map

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

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