@botbotgo/agent-harness 0.0.270 → 0.0.272

package/README.md

@@ -1059,8 +1059,9 @@ ACP transport notes:
 - `serveAcpStdio(runtime)` exposes newline-delimited JSON-RPC over stdio for local IDE, CLI, or subprocess clients.
 - `serveAcpHttp(runtime)` exposes JSON-RPC over HTTP plus SSE runtime events so remote operator surfaces can connect without importing the runtime in-process.
 - ACP transport validation now covers the reference-client core flow: capability discovery, request submit, session lookup, request lookup, invalid-JSON handling, notification calls without response ids, stdio JSON-RPC, and HTTP plus SSE runtime notifications.
+- Cross-protocol conformance now has an explicit regression gate as well: ACP submission, A2A task lookup and continuation, and runtime MCP inspection must all project the same persisted `sessionId` / `requestId` runtime records instead of drifting into surface-specific identifiers or side stores.
 - For the thinnest editor or CLI starter, begin with `agent-harness acp serve --workspace . --transport stdio` and mirror the `examples/protocol-hello-world/app/acp-stdio-hello-world.mjs` wire shape. Applications that want an in-process reference client can use `createAcpStdioClient(...)` to issue JSON-RPC requests and route runtime notifications without hand-rolling line parsing.
-- `serveA2aHttp(runtime)` exposes an A2A-compatible HTTP JSON-RPC bridge plus agent card discovery, mapping both existing methods such as `message/send` and A2A v1.0 PascalCase methods such as `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, `GetAgentCard`, `GetExtendedAgentCard`, and task push-notification config methods onto the existing session/request runtime surface. The bridge now advertises both `1.0` and `0.3` JSON-RPC interfaces, answers `HEAD` / `OPTIONS` discovery on the agent-card path, sets supported-version discovery headers, validates `A2A-Version`, records `A2A-Extensions` into runtime invocation metadata, publishes `TASK_STATE_*` statuses plus the `{ task }` `SendMessage` wrapper, streams an initial `{ task }` snapshot plus later `{ statusUpdate }` payloads over SSE for v1 streaming methods, and can send best-effort webhook task snapshots for configured push notification receivers.
+- `serveA2aHttp(runtime)` exposes an A2A-compatible HTTP JSON-RPC bridge plus agent card discovery, mapping both existing methods such as `message/send` and A2A v1.0 PascalCase methods such as `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, `GetAgentCard`, `GetExtendedAgentCard`, and task push-notification config methods onto the existing session/request runtime surface. The bridge now advertises both `1.0` and `0.3` JSON-RPC interfaces, answers `HEAD` / `OPTIONS` discovery on the agent-card path, sets supported-version discovery headers, can optionally expose registry URLs plus detached signed-card metadata for surrounding discovery systems, validates `A2A-Version`, records `A2A-Extensions` into runtime invocation metadata, publishes `TASK_STATE_*` statuses plus the `{ task }` `SendMessage` wrapper, streams an initial `{ task }` snapshot plus later `{ statusUpdate }` payloads over SSE for v1 streaming methods, and can send best-effort webhook task snapshots for configured push notification receivers.
 - `serveAgUiHttp(runtime)` exposes an AG-UI-compatible HTTP SSE bridge that projects runtime lifecycle, text output, upstream thinking, step progress, and tool calls onto `RUN_*`, `TEXT_MESSAGE_*`, `THINKING_TEXT_MESSAGE_*`, `STEP_*`, and `TOOL_CALL_*` events for UI clients.
 - `createRuntimeMcpServer(runtime)` and `serveRuntimeMcpOverStdio(runtime)` expose the persisted runtime control surface itself as MCP tools, including sessions, requests, approvals, artifacts, events, and package export helpers.
 - `listRequestEvents(...)`, `listRequestTraceItems(...)`, and `exportRequestPackage(...)` are the request-first inspection helpers.

package/README.zh.md

@@ -1016,8 +1016,9 @@ ACP transport 说明：
 - `serveAcpStdio(runtime)` 提供基于 stdio 的 newline-delimited JSON-RPC，适合本地 IDE、CLI 或子进程客户端。
 - `serveAcpHttp(runtime)` 提供基于 HTTP 的 JSON-RPC 与 SSE runtime events，适合远程界面或独立控制面接入。
 - ACP transport 现已覆盖核心参考客户端流程验证：capability discovery、request submit、session lookup、request lookup、invalid JSON 处理、无 id notification 不返回响应，以及 stdio JSON-RPC 与 HTTP + SSE runtime notifications。
+- 现在还额外有一条跨协议一致性回归门：ACP 发起的 request、A2A 读取或继续的 task，以及 runtime MCP 暴露的检查结果，必须始终指向同一组持久化 `sessionId` / `requestId` 运行时记录，不能漂移成各协议各自维护的标识体系。
 - 如果要从最薄的一层 editor / CLI starter 开始，优先用 `agent-harness acp serve --workspace . --transport stdio`，并直接参考 `examples/protocol-hello-world/app/acp-stdio-hello-world.mjs` 的 wire shape。需要在应用内使用 reference client 时，可直接用 `createAcpStdioClient(...)` 发起 JSON-RPC 请求并分流 runtime notifications，避免每个 sidecar 自己重写 line parsing。
-- `serveA2aHttp(runtime)` 提供 A2A HTTP JSON-RPC bridge 与 agent card discovery，同时兼容 `message/send` 这类旧方法，以及 `SendMessage`、`SendStreamingMessage`、`GetTask`、`ListTasks`、`CancelTask`、`SubscribeToTask`、`GetAgentCard`、`GetExtendedAgentCard` 与 task push-notification config 这类 A2A v1.0 方法，并统一映射到现有 session/request 运行记录。bridge 现在会同时声明 `1.0` 与 `0.3` 两个 JSON-RPC interface、在 agent card 路径上响应 `HEAD` / `OPTIONS` discovery、写出支持版本的 discovery headers、校验 `A2A-Version`、把 `A2A-Extensions` 记录进 runtime invocation metadata、发布 `TASK_STATE_*` 状态与 `SendMessage` 的 `{ task }` wrapper、在 v1 streaming 方法上先通过 SSE 输出 `{ task }` 初始快照，再输出 `{ statusUpdate }` 增量状态，并可向已配置的 webhook receiver 发送 best-effort task push notifications。
+- `serveA2aHttp(runtime)` 提供 A2A HTTP JSON-RPC bridge 与 agent card discovery，同时兼容 `message/send` 这类旧方法，以及 `SendMessage`、`SendStreamingMessage`、`GetTask`、`ListTasks`、`CancelTask`、`SubscribeToTask`、`GetAgentCard`、`GetExtendedAgentCard` 与 task push-notification config 这类 A2A v1.0 方法，并统一映射到现有 session/request 运行记录。bridge 现在会同时声明 `1.0` 与 `0.3` 两个 JSON-RPC interface、在 agent card 路径上响应 `HEAD` / `OPTIONS` discovery、写出支持版本的 discovery headers、可选暴露 registry URL 与 detached signed-card metadata 供外围发现系统使用、校验 `A2A-Version`、把 `A2A-Extensions` 记录进 runtime invocation metadata、发布 `TASK_STATE_*` 状态与 `SendMessage` 的 `{ task }` wrapper、在 v1 streaming 方法上先通过 SSE 输出 `{ task }` 初始快照，再输出 `{ statusUpdate }` 增量状态，并可向已配置的 webhook receiver 发送 best-effort task push notifications。
 - `serveAgUiHttp(runtime)` 提供 AG-UI HTTP SSE bridge，把 runtime 生命周期、文本输出、upstream thinking、step 进度与 tool call 投影成 `RUN_*`、`TEXT_MESSAGE_*`、`THINKING_TEXT_MESSAGE_*`、`STEP_*` 与 `TOOL_CALL_*` 事件，便于 UI 客户端直接接入。
 - `createRuntimeMcpServer(runtime)` 与 `serveRuntimeMcpOverStdio(runtime)` 会把持久化 runtime 控制面本身暴露成 MCP tools，包括 sessions、requests、approvals、artifacts、events 与 package export helpers。
 - `listRequestEvents(...)`、`listRequestTraceItems(...)` 与 `exportRequestPackage(...)` 是 request-first 的检查 helper。

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.269";
+export declare const AGENT_HARNESS_VERSION = "0.0.271";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.269";
+export const AGENT_HARNESS_VERSION = "0.0.271";

package/dist/protocol/a2a/http.d.ts

@@ -12,6 +12,20 @@ export type A2aHttpServerOptions = {
         url?: string;
     };
     defaultAgentId?: string;
+    registryUrls?: string[];
+    agentCardSignature?: {
+        algorithm: string;
+        signature: string;
+        keyId?: string;
+    };
+};
+type A2aAgentCardDiscoveryMetadata = {
+    registryUrls?: string[];
+    signedAgentCard?: {
+        algorithm: string;
+        signature: string;
+        keyId?: string;
+    };
 };
 export type A2aAgentCard = {
     name: string;
@@ -45,6 +59,11 @@ export type A2aAgentCard = {
         tags: string[];
         examples: string[];
     }>;
+    metadata?: {
+        agentHarness?: {
+            discovery?: A2aAgentCardDiscoveryMetadata;
+        };
+    };
 };
 export type A2aExtendedAgentCard = A2aAgentCard & {
     metadata: {
@@ -59,6 +78,7 @@ export type A2aExtendedAgentCard = A2aAgentCard & {
                 agentCount: number;
                 subagentCount: number;
             };
+            discovery?: A2aAgentCardDiscoveryMetadata;
             agents: Array<{
                 id: string;
                 name: string;

package/dist/protocol/a2a/http.js

@@ -15,6 +15,50 @@ function writeA2aDiscoveryHeaders(response) {
     response.setHeader("A2A-Version", "1.0");
     response.setHeader("A2A-Supported-Versions", SUPPORTED_A2A_VERSIONS.join(", "));
 }
+function normalizeNonEmptyStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const items = value.map((item) => item.trim()).filter((item) => item.length > 0);
+    return items.length > 0 ? items : undefined;
+}
+function buildDiscoveryMetadata(options) {
+    const registryUrls = normalizeNonEmptyStringArray(options.registryUrls);
+    const signature = options.agentCardSignature?.signature?.trim();
+    const algorithm = options.agentCardSignature?.algorithm?.trim();
+    const keyId = options.agentCardSignature?.keyId?.trim();
+    if (!registryUrls && (!signature || !algorithm)) {
+        return undefined;
+    }
+    return {
+        ...(registryUrls ? { registryUrls } : {}),
+        ...(signature && algorithm
+            ? {
+                signedAgentCard: {
+                    algorithm,
+                    signature,
+                    ...(keyId ? { keyId } : {}),
+                },
+            }
+            : {}),
+    };
+}
+function writeOptionalAgentCardIntegrityHeaders(response, options) {
+    const registryUrls = normalizeNonEmptyStringArray(options.registryUrls);
+    if (registryUrls) {
+        response.setHeader("X-A2A-Registry-Urls", registryUrls.join(", "));
+    }
+    const signature = options.agentCardSignature?.signature?.trim();
+    const algorithm = options.agentCardSignature?.algorithm?.trim();
+    const keyId = options.agentCardSignature?.keyId?.trim();
+    if (signature && algorithm) {
+        response.setHeader("X-A2A-Agent-Card-Signature", signature);
+        response.setHeader("X-A2A-Agent-Card-Alg", algorithm);
+        if (keyId) {
+            response.setHeader("X-A2A-Agent-Card-Key-Id", keyId);
+        }
+    }
+}
 function writeSseHeaders(response) {
     response.statusCode = 200;
     response.setHeader("content-type", "text/event-stream; charset=utf-8");
@@ -562,6 +606,21 @@ function buildAgentCard(runtime, options) {
         defaultInputModes: ["text/plain"],
         defaultOutputModes: ["text/plain"],
         skills,
+        ...(buildDiscoveryMetadata({
+            registryUrls: options.registryUrls,
+            agentCardSignature: options.agentCardSignature,
+        })
+            ? {
+                metadata: {
+                    agentHarness: {
+                        discovery: buildDiscoveryMetadata({
+                            registryUrls: options.registryUrls,
+                            agentCardSignature: options.agentCardSignature,
+                        }),
+                    },
+                },
+            }
+            : {}),
         ...(options.documentationUrl ? { documentationUrl: options.documentationUrl } : {}),
         ...(options.provider ? { provider: options.provider } : {}),
         ...(options.defaultAgentId ? { defaultAgentId: options.defaultAgentId } : {}),
@@ -584,6 +643,17 @@ function buildExtendedAgentCard(runtime, options) {
                     agentCount: inventory.agents.length,
                     subagentCount: inventory.agents.filter((agent) => Boolean(agent.parentAgentId)).length,
                 },
+                ...(buildDiscoveryMetadata({
+                    registryUrls: options.registryUrls,
+                    agentCardSignature: options.agentCardSignature,
+                })
+                    ? {
+                        discovery: buildDiscoveryMetadata({
+                            registryUrls: options.registryUrls,
+                            agentCardSignature: options.agentCardSignature,
+                        }),
+                    }
+                    : {}),
                 agents: inventory.agents.map((agent) => ({
                     id: agent.id,
                     name: agent.id,
@@ -846,6 +916,8 @@ export async function serveA2aOverHttp(runtime, options = {}) {
         ...(options.documentationUrl ? { documentationUrl: options.documentationUrl } : {}),
         ...(options.provider ? { provider: options.provider } : {}),
         ...(options.defaultAgentId ? { defaultAgentId: options.defaultAgentId } : {}),
+        ...(options.registryUrls ? { registryUrls: options.registryUrls } : {}),
+        ...(options.agentCardSignature ? { agentCardSignature: options.agentCardSignature } : {}),
     });
     const pushConfigsByTask = new Map();
     const registerPushNotificationConfig = (taskId, config) => {
@@ -919,18 +991,32 @@ export async function serveA2aOverHttp(runtime, options = {}) {
             }
             writeA2aDiscoveryHeaders(response);
             if (request.method === "OPTIONS" && (requestUrl.pathname === rpcPath || requestUrl.pathname === agentCardPath || requestUrl.pathname === "/.well-known/agent.json")) {
+                if (requestUrl.pathname === agentCardPath || requestUrl.pathname === "/.well-known/agent.json") {
+                    writeOptionalAgentCardIntegrityHeaders(response, {
+                        registryUrls: options.registryUrls,
+                        agentCardSignature: options.agentCardSignature,
+                    });
+                }
                 response.statusCode = 204;
                 response.setHeader("Allow", "GET,HEAD,POST,OPTIONS");
                 response.end();
                 return;
             }
             if (request.method === "HEAD" && (requestUrl.pathname === agentCardPath || requestUrl.pathname === "/.well-known/agent.json")) {
+                writeOptionalAgentCardIntegrityHeaders(response, {
+                    registryUrls: options.registryUrls,
+                    agentCardSignature: options.agentCardSignature,
+                });
                 response.statusCode = 200;
                 response.setHeader("content-type", "application/json; charset=utf-8");
                 response.end();
                 return;
             }
             if (request.method === "GET" && (requestUrl.pathname === agentCardPath || requestUrl.pathname === "/.well-known/agent.json")) {
+                writeOptionalAgentCardIntegrityHeaders(response, {
+                    registryUrls: options.registryUrls,
+                    agentCardSignature: options.agentCardSignature,
+                });
                 writeJson(response, 200, buildAgentCard(runtime, buildCardOptions()));
                 return;
             }
@@ -968,6 +1054,10 @@ export async function serveA2aOverHttp(runtime, options = {}) {
                         return;
                     }
                     if (payload.method === "GetAgentCard") {
+                        writeOptionalAgentCardIntegrityHeaders(response, {
+                            registryUrls: options.registryUrls,
+                            agentCardSignature: options.agentCardSignature,
+                        });
                         writeJson(response, 200, toSuccess(payload.id ?? null, buildAgentCard(runtime, buildCardOptions())));
                         return;
                     }
@@ -1093,6 +1183,10 @@ export async function serveA2aOverHttp(runtime, options = {}) {
                         return;
                     }
                     if (payload.method === "GetExtendedAgentCard") {
+                        writeOptionalAgentCardIntegrityHeaders(response, {
+                            registryUrls: options.registryUrls,
+                            agentCardSignature: options.agentCardSignature,
+                        });
                         writeJson(response, 200, toSuccess(payload.id ?? null, buildExtendedAgentCard(runtime, buildCardOptions())));
                         return;
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.270",
+  "version": "0.0.272",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",