@mono-agent/a2a-adapter 0.12.0 → 0.14.0

package/README.md

@@ -1,14 +1,23 @@
 # @mono-agent/a2a-adapter
 
-Category: `communication`
+Expose a mono-agent as an A2A provider, or call a remote A2A provider from
+programmatic host code.
 
 ## Category
 
-Communication adapter.
+<!-- package-metadata:start -->
+<!-- Generated by scripts/generate-package-docs.mjs. Do not edit by hand. -->
+
+Category: `communication`
+Tier: `plugin`
+Catalog responsibility: Exposes agent responders over A2A and consumes remote A2A agents through direct discovery.
+
+<!-- package-metadata:end -->
 
 ## Responsibility
 
-Expose a agent responder as an A2A provider and call remote A2A agents through direct Agent Card discovery.
+Expose an agent responder through an A2A Agent Card plus JSON-RPC/REST message
+routes, and provide direct-discovery consumer clients for text/task calls.
 
 This is a **plugin-tier** package: it publishes to npm in the mono-agent lockstep at the same version as the core packages, but it is not part of the core `@mono-agent/agent-app` dependency closure. `@mono-agent/agent-app` loads its provider channel only when a host declares it under `channels.plugins[]`.
 
@@ -16,11 +25,58 @@ This is a **plugin-tier** package: it publishes to npm in the mono-agent lockste
 
 ## Install / Usage
 
+The A2A package is outside the core `@mono-agent/agent-app` closure. Install the
+same lockstep version as the rest of the framework, then declare the provider
+plugin in `mono-agent.config.json`:
+
 ```bash
-pnpm --filter @mono-agent/a2a-adapter run build
+pnpm add @mono-agent/agent-app@latest @mono-agent/a2a-adapter@latest
 ```
 
-Provider usage starts a loopback HTTP server by default and serves the Agent Card at `/.well-known/agent-card.json`. Message/task endpoints are available under `/a2a/json-rpc` and `/a2a/rest`.
+The lockstep `latest` tags resolve to the same framework version. If the host
+pins an older release, replace both `latest` tags with that same version.
+
+```json
+{
+  "agent": { "name": "Agent A" },
+  "channels": {
+    "plugins": [
+      {
+        "package": "@mono-agent/a2a-adapter",
+        "id": "a2a",
+        "config": {
+          "enabled": true,
+          "provider": { "host": "127.0.0.1", "port": 4300 },
+          "agent": {
+            "description": "Local A2A provider.",
+            "version": "0.1.0"
+          },
+          "skill": {
+            "id": "main",
+            "name": "Main",
+            "description": "Answers text prompts.",
+            "tags": ["mono-agent", "a2a"]
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+```bash
+mono-agent validate
+mono-agent start --foreground
+```
+
+The provider starts on loopback by default. It serves the Agent Card at
+`/.well-known/agent-card.json` and message/task endpoints at `/a2a/json-rpc`
+and `/a2a/rest`. Set `MONO_AGENT_A2A_BEARER_TOKEN` in `.env` when
+`config.provider.requireBearer` is enabled. Non-loopback binding or a public
+base URL also requires `allowNonLoopback: true`; terminate HTTPS in front of
+the plaintext server.
+
+Custom hosts can start a provider directly:
 
 ```ts
 import { startA2AProvider } from "@mono-agent/a2a-adapter";
@@ -119,8 +175,54 @@ migration; startup refuses to reinterpret an existing manifest.
 Config-loaded providers reject any partial `provider.idempotency` block that
 omits the namespace; they never silently start without the advertised guard.
 
+Provider config makes this agent callable. It does not automatically give the
+agent a tool for calling peers. The consumer API remains programmatic: compose
+`createA2AConsumerResponder`, `sendA2AMessage`, or `dispatchA2AMessage` in host
+code. Plugin `config.consumer` supplies defaults to code that chooses to use
+them; it does not create autonomous delegation by itself.
+
+## Architecture
+
+### Data flow
+
+1. The channel driver layers plugin config and environment overrides, validates
+   the public Agent Card identity and network guard, then starts the provider
+   with the host's structural responder.
+2. Provider routes authenticate before parsing the bounded body, translate A2A
+   text/task input into an `A2AAgentRequest`, and stream the responder's result
+   back through the SDK transport.
+3. When enabled, the durable idempotency store binds a caller-supplied key to a
+   canonical execution fingerprint, replays the same task, and fails closed on
+   conflict, capacity, expired results, or in-doubt admissions.
+4. Separately, consumer helpers discover a remote Agent Card, validate the
+   advertised capability, and send/observe/cancel requests. Observer timeout or
+   cancellation does not cancel the remote task; `dispatch.cancel()` is explicit.
+
+### Package structure
+
+| Source module | Responsibility |
+| --- | --- |
+| [`channel-driver.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/a2a-adapter/src/channel-driver.ts) | Plugin-tier config-first provider lifecycle. |
+| [`config.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/a2a-adapter/src/config.ts) | Provider, card, skill, consumer, bearer, and idempotency config validation/redaction. |
+| [`card.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/a2a-adapter/src/card.ts) | Agent Card construction and extension advertisement. |
+| [`provider.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/a2a-adapter/src/provider.ts) | HTTP/SDK provider routes and responder translation. |
+| [`consumer.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/a2a-adapter/src/consumer.ts) | Discovery, send, dispatch, observation, cancellation, and responder facade. |
+| [`idempotency.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/a2a-adapter/src/idempotency.ts) | Durable admission records, result replay, permanent tombstones, and capacity checks. |
+
 ## Public API
 
+### Start here
+
+| API | Use it for |
+| --- | --- |
+| `createChannelDriver` / `createA2AChannelDriver` | Load the provider as a config-first `channels.plugins[]` entry. |
+| `startA2AProvider` | Expose a responder from a custom host. |
+| `createA2AAgentCard` | Build the exact card advertised by a custom provider. |
+| `sendA2AMessage` | Send and await one direct remote text/task request. |
+| `dispatchA2AMessage` | Admit long work, then observe or cancel the durable remote task separately. |
+| `createA2AConsumer` / `createA2AConsumerResponder` | Reuse discovery and A2A calls inside a programmatic composition. |
+| `loadA2AAdapterConfig` | Validate plugin/env settings without starting a server. |
+
 <!-- public-api-inventory:start -->
 <!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
 
@@ -188,90 +290,6 @@ startA2AProvider
 
 <!-- public-api-inventory:end -->
 
-Config can be loaded from a `channels.plugins[]` entry or explicit environment variables:
-
-Set `MONO_AGENT_A2A_BEARER_TOKEN` in `.env` when `requireBearer` is enabled;
-the source-config example omits the credential.
-
-```json
-{
-  "agent": {
-    "name": "Agent A"
-  },
-  "channels": {
-    "plugins": [
-      {
-        "package": "@mono-agent/a2a-adapter",
-        "id": "a2a",
-        "config": {
-          "enabled": true,
-          "provider": {
-            "host": "127.0.0.1",
-            "port": 4300,
-            "requireBearer": true,
-            "maxRequestBytes": 50000000,
-            "idempotency": {
-              "namespace": "agent-a-production",
-              "stateDir": ".mono-agent/a2a-agent-a",
-              "retentionMs": 2592000000,
-              "maxRecords": 10000
-            }
-          },
-          "agent": {
-            "description": "Local A2A provider.",
-            "version": "0.1.0"
-          },
-          "skill": {
-            "id": "agent-a",
-            "name": "Agent A",
-            "description": "Answers text prompts.",
-            "tags": ["mono-agent", "a2a"]
-          },
-          "consumer": {
-            "remoteAgentUrls": ["http://127.0.0.1:4300/.well-known/agent-card.json"],
-            "timeoutMs": 30000
-          }
-        }
-      }
-    ]
-  }
-}
-```
-
-Root `agent.name` is the default Agent Card name when the plugin's
-`config.agent.name` is omitted. An A2A-specific `config.agent.name` or
-`MONO_AGENT_A2A_AGENT_NAME` overrides that public default without changing the
-root agent identity; `MONO_AGENT_NAME` is the environment override for the root
-name.
-
-Important env names:
-
-- `MONO_AGENT_A2A_ENABLED`
-- `MONO_AGENT_A2A_PROVIDER_ENABLED`
-- `MONO_AGENT_A2A_HOST`
-- `MONO_AGENT_A2A_PORT`
-- `MONO_AGENT_A2A_PUBLIC_BASE_URL`
-- `MONO_AGENT_A2A_ALLOW_NON_LOOPBACK`
-- `MONO_AGENT_A2A_REQUIRE_BEARER`
-- `MONO_AGENT_A2A_BEARER_TOKEN`
-- `MONO_AGENT_A2A_MAX_REQUEST_BYTES`
-- `MONO_AGENT_A2A_IDEMPOTENCY_NAMESPACE`
-- `MONO_AGENT_A2A_IDEMPOTENCY_STATE_DIR`
-- `MONO_AGENT_A2A_IDEMPOTENCY_RETENTION_MS`
-- `MONO_AGENT_A2A_IDEMPOTENCY_MAX_RECORDS`
-- `MONO_AGENT_NAME`
-- `MONO_AGENT_A2A_AGENT_NAME`
-- `MONO_AGENT_A2A_AGENT_DESCRIPTION`
-- `MONO_AGENT_A2A_AGENT_VERSION`
-- `MONO_AGENT_A2A_SKILL_ID`
-- `MONO_AGENT_A2A_SKILL_NAME`
-- `MONO_AGENT_A2A_SKILL_DESCRIPTION`
-- `MONO_AGENT_A2A_SKILL_TAGS`
-- `MONO_AGENT_A2A_REMOTE_AGENT_URLS`
-- `MONO_AGENT_A2A_DEFAULT_REMOTE_AGENT_URL`
-- `MONO_AGENT_A2A_CONSUMER_BEARER_TOKEN`
-- `MONO_AGENT_A2A_TIMEOUT_MS`
-
 ## Dependency Boundary
 
 This package depends only on `@mono-agent/agent-contracts` plus the pinned A2A SDK and Express transport surface. It does not depend on the agent harness, config package, operator surfaces, or other communication adapters.
@@ -280,6 +298,13 @@ This package depends only on `@mono-agent/agent-contracts` plus the pinned A2A S
 
 It does not own runtime execution, memory, tool policy, central registries, signed cards, push notifications, file exchange, gRPC hosting, or autonomous LLM-selected remote-agent delegation. This pass supports direct discovery and text/task communication only.
 
+## Related Documentation
+
+- [A2A provider channel](https://mono-agent-docs.vercel.app/channels/a2a/)
+- [Programmatic A2A consumer](https://mono-agent-docs.vercel.app/programmatic/a2a-consumer/)
+- [A2A provider and consumer playbook](https://mono-agent-docs.vercel.app/playbooks/a2a-provider-and-consumer/)
+- [Multi-agent composition](https://mono-agent-docs.vercel.app/programmatic/multi-agent/)
+
 ## Verification
 
 Run:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/a2a-adapter",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "A2A provider and consumer adapter for host-compatible runtimes.",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -27,7 +27,7 @@
   ],
   "dependencies": {
     "@a2a-js/sdk": "1.0.0-alpha.0",
-    "@mono-agent/agent-contracts": "0.12.0",
+    "@mono-agent/agent-contracts": "0.14.0",
     "express": "^5.1.0"
   },
   "devDependencies": {