@botbotgo/agent-harness 0.0.223 → 0.0.225

package/README.md

@@ -1024,7 +1024,7 @@ ACP transport notes:
 - `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.
 - 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`, and `GetExtendedAgentCard` onto the existing session/request runtime surface. The bridge now advertises both `1.0` and `0.3` JSON-RPC interfaces, sets `capabilities.streaming = true`, validates `A2A-Version`, records `A2A-Extensions` into runtime invocation metadata, publishes `TASK_STATE_*` statuses plus the `{ task }` `SendMessage` wrapper, streams task snapshots over SSE for streaming methods, and still returns explicit unsupported errors for push notifications.
+- `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`, `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, sets `capabilities.streaming = true` plus `capabilities.pushNotifications = true`, validates `A2A-Version`, records `A2A-Extensions` into runtime invocation metadata, publishes `TASK_STATE_*` statuses plus the `{ task }` `SendMessage` wrapper, streams task snapshots over SSE for 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(...)` and `exportRequestPackage(...)` are the request-first inspection helpers.

package/README.zh.md

@@ -982,7 +982,7 @@ ACP transport 说明：
 - `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。
 - 如果要从最薄的一层 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`、`GetExtendedAgentCard` 这类 A2A v1.0 PascalCase 方法，并统一映射到现有 session/request 运行记录。bridge 现在会同时声明 `1.0` 与 `0.3` 两个 JSON-RPC interface、把 `capabilities.streaming` 设为 `true`、校验 `A2A-Version`、把 `A2A-Extensions` 记录进 runtime invocation metadata、发布 `TASK_STATE_*` 状态与 `SendMessage` 的 `{ task }` wrapper，并在 streaming 方法上通过 SSE 输出 task snapshots；push notification 仍返回明确 unsupported error。
+- `serveA2aHttp(runtime)` 提供 A2A HTTP JSON-RPC bridge 与 agent card discovery，同时兼容 `message/send` 这类旧方法，以及 `SendMessage`、`SendStreamingMessage`、`GetTask`、`ListTasks`、`CancelTask`、`SubscribeToTask`、`GetExtendedAgentCard` 与 task push-notification config 这类 A2A v1.0 方法，并统一映射到现有 session/request 运行记录。bridge 现在会同时声明 `1.0` 与 `0.3` 两个 JSON-RPC interface、把 `capabilities.streaming` 和 `capabilities.pushNotifications` 都设为 `true`、校验 `A2A-Version`、把 `A2A-Extensions` 记录进 runtime invocation metadata、发布 `TASK_STATE_*` 状态与 `SendMessage` 的 `{ task }` wrapper、在 streaming 方法上通过 SSE 输出 task snapshots，并可向已配置的 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(...)` 与 `exportRequestPackage(...)` 是 request-first 的检查 helper。

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.222";
+export declare const AGENT_HARNESS_VERSION = "0.0.224";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.222";
+export const AGENT_HARNESS_VERSION = "0.0.224";

package/dist/protocol/a2a/http.js

@@ -1,5 +1,6 @@
 import { createServer } from "node:http";
 import { AGENT_HARNESS_VERSION } from "../../package-version.js";
+import { createPersistentId } from "../../utils/id.js";
 const SUPPORTED_A2A_VERSIONS = ["1.0", "0.3"];
 function normalizePath(value, fallback) {
     const source = typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
@@ -134,11 +135,59 @@ function parseMessageSendParams(params) {
     const invocation = metadata && typeof metadata === "object" && !Array.isArray(metadata)
         ? metadata
         : undefined;
+    const configuration = typed.configuration;
+    const nestedPushNotificationConfig = configuration && typeof configuration === "object" && !Array.isArray(configuration)
+        ? configuration.pushNotificationConfig
+            ?? configuration.taskPushNotificationConfig
+        : undefined;
+    const pushNotificationConfig = parsePendingPushNotificationConfig(typed.pushNotificationConfig ?? nestedPushNotificationConfig);
     return {
         input: textParts.join("\n\n"),
         ...(agentId ? { agentId } : {}),
         ...(sessionId ? { sessionId } : {}),
         ...(invocation ? { invocation } : {}),
+        ...(pushNotificationConfig ? { pushNotificationConfig } : {}),
+    };
+}
+function parsePushNotificationAuthenticationInfo(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const typed = value;
+    const schemes = Array.isArray(typed.schemes)
+        ? typed.schemes
+            .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+            .map((entry) => entry.trim())
+        : [];
+    if (schemes.length === 0) {
+        return undefined;
+    }
+    return {
+        schemes,
+        ...(typeof typed.credentials === "string" && typed.credentials.trim().length > 0
+            ? { credentials: typed.credentials.trim() }
+            : {}),
+    };
+}
+function parsePendingPushNotificationConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const typed = value;
+    const rawUrl = typeof typed.url === "string" ? typed.url.trim() : "";
+    if (rawUrl.length === 0) {
+        throw new Error("A2A push notification config requires `url`.");
+    }
+    const parsedUrl = new URL(rawUrl);
+    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+        throw new Error("A2A push notification config requires an http or https URL.");
+    }
+    const authentication = parsePushNotificationAuthenticationInfo(typed.authentication);
+    return {
+        url: parsedUrl.toString(),
+        ...(typeof typed.id === "string" && typed.id.trim().length > 0 ? { id: typed.id.trim() } : {}),
+        ...(typeof typed.token === "string" && typed.token.trim().length > 0 ? { token: typed.token.trim() } : {}),
+        ...(authentication ? { authentication } : {}),
     };
 }
 function attachServiceParameters(invocation, serviceParameters) {
@@ -199,6 +248,54 @@ function parseTaskListParams(params) {
         limit: limitValue,
     };
 }
+function parsePushNotificationLocatorParams(params) {
+    if (!params || typeof params !== "object" || Array.isArray(params)) {
+        throw new Error("A2A push notification lookup requires params object.");
+    }
+    const typed = params;
+    const taskId = typeof typed.taskId === "string" && typed.taskId.trim().length > 0 ? typed.taskId.trim() : "";
+    const configId = typeof typed.id === "string" && typed.id.trim().length > 0 ? typed.id.trim() : "";
+    if (!taskId) {
+        throw new Error("A2A push notification lookup requires `taskId`.");
+    }
+    if (!configId) {
+        throw new Error("A2A push notification lookup requires `id`.");
+    }
+    return { taskId, configId };
+}
+function parsePushNotificationListParams(params) {
+    if (!params || typeof params !== "object" || Array.isArray(params)) {
+        throw new Error("A2A push notification list requires params object.");
+    }
+    const typed = params;
+    const taskId = typeof typed.taskId === "string" && typed.taskId.trim().length > 0 ? typed.taskId.trim() : "";
+    if (!taskId) {
+        throw new Error("A2A push notification list requires `taskId`.");
+    }
+    const pageSize = typeof typed.pageSize === "number" && Number.isFinite(typed.pageSize)
+        ? Math.max(1, Math.min(100, Math.trunc(typed.pageSize)))
+        : 20;
+    return {
+        taskId,
+        pageSize,
+        ...(typeof typed.pageToken === "string" && typed.pageToken.trim().length > 0 ? { pageToken: typed.pageToken.trim() } : {}),
+    };
+}
+function parseCreatePushNotificationConfigParams(params) {
+    if (!params || typeof params !== "object" || Array.isArray(params)) {
+        throw new Error("A2A push notification create requires params object.");
+    }
+    const typed = params;
+    const taskId = typeof typed.taskId === "string" && typed.taskId.trim().length > 0 ? typed.taskId.trim() : "";
+    if (!taskId) {
+        throw new Error("A2A push notification create requires `taskId`.");
+    }
+    const config = parsePendingPushNotificationConfig(typed.pushNotificationConfig ?? typed.config ?? typed);
+    if (!config) {
+        throw new Error("A2A push notification create requires a config object.");
+    }
+    return { taskId, config };
+}
 function mapRunState(state) {
     switch (state) {
         case "queued":
@@ -449,7 +546,7 @@ function buildAgentCard(runtime, options) {
         ],
         capabilities: {
             streaming: true,
-            pushNotifications: false,
+            pushNotifications: true,
             extendedAgentCard: true,
         },
         defaultInputModes: ["text/plain"],
@@ -541,6 +638,42 @@ function withRunResult(task, result, streamedText) {
 function isTerminalTaskState(state) {
     return state === "TASK_STATE_COMPLETED" || state === "TASK_STATE_FAILED" || state === "TASK_STATE_CANCELED";
 }
+function clonePushNotificationConfig(config) {
+    return {
+        id: config.id,
+        taskId: config.taskId,
+        url: config.url,
+        ...(config.token ? { token: config.token } : {}),
+        ...(config.authentication ? { authentication: config.authentication } : {}),
+    };
+}
+function fingerprintTaskForPush(task) {
+    return JSON.stringify({
+        state: task.status.state,
+        timestamp: task.status.timestamp,
+        message: task.status.message,
+    });
+}
+async function sendPushNotification(config, task) {
+    const headers = {
+        "content-type": "application/json",
+    };
+    if (config.token) {
+        headers["x-a2a-notification-token"] = config.token;
+    }
+    const scheme = config.authentication?.schemes[0]?.toLowerCase();
+    if (scheme === "bearer" && config.authentication?.credentials) {
+        headers.authorization = `Bearer ${config.authentication.credentials}`;
+    }
+    else if (scheme === "basic" && config.authentication?.credentials) {
+        headers.authorization = `Basic ${config.authentication.credentials}`;
+    }
+    await fetch(config.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ task }),
+    });
+}
 async function streamTaskUpdates(response, id, method, iterator) {
     writeSseHeaders(response);
     for await (const item of iterator) {
@@ -677,6 +810,63 @@ export async function serveA2aOverHttp(runtime, options = {}) {
         ...(options.provider ? { provider: options.provider } : {}),
         ...(options.defaultAgentId ? { defaultAgentId: options.defaultAgentId } : {}),
     });
+    const pushConfigsByTask = new Map();
+    const registerPushNotificationConfig = (taskId, config) => {
+        const entry = {
+            id: config.id ?? `push-${createPersistentId()}`,
+            taskId,
+            url: config.url,
+            ...(config.token ? { token: config.token } : {}),
+            ...(config.authentication ? { authentication: config.authentication } : {}),
+        };
+        let taskConfigs = pushConfigsByTask.get(taskId);
+        if (!taskConfigs) {
+            taskConfigs = new Map();
+            pushConfigsByTask.set(taskId, taskConfigs);
+        }
+        taskConfigs.set(entry.id, entry);
+        return entry;
+    };
+    const listPushNotificationConfigs = (taskId) => [...(pushConfigsByTask.get(taskId)?.values() ?? [])].sort((left, right) => left.id.localeCompare(right.id));
+    const getPushNotificationConfig = (taskId, configId) => pushConfigsByTask.get(taskId)?.get(configId);
+    const deletePushNotificationConfig = (taskId, configId) => {
+        const taskConfigs = pushConfigsByTask.get(taskId);
+        if (!taskConfigs) {
+            return false;
+        }
+        const deleted = taskConfigs.delete(configId);
+        if (taskConfigs.size === 0) {
+            pushConfigsByTask.delete(taskId);
+        }
+        return deleted;
+    };
+    const dispatchPushNotificationsForTask = async (taskId) => {
+        const task = await hydrateTaskStateFromEvents(runtime, await buildTaskFromRuntime(runtime, taskId));
+        if (!task) {
+            return;
+        }
+        const fingerprint = fingerprintTaskForPush(task);
+        const configs = listPushNotificationConfigs(taskId);
+        await Promise.all(configs.map(async (config) => {
+            if (config.lastFingerprint === fingerprint) {
+                return;
+            }
+            try {
+                await sendPushNotification(config, task);
+                config.lastFingerprint = fingerprint;
+            }
+            catch {
+                // Push delivery is best-effort and should not fail the transport request.
+            }
+        }));
+    };
+    const pushRelevantEventTypes = new Set(["run.state.changed", "approval.requested", "approval.resolved"]);
+    const unsubscribePushNotifications = runtime.subscribe((event) => {
+        if (!pushRelevantEventTypes.has(event.eventType) || !pushConfigsByTask.has(event.runId)) {
+            return;
+        }
+        void dispatchPushNotificationsForTask(event.runId);
+    });
     const httpServer = createServer(async (request, response) => {
         try {
             const requestUrl = new URL(request.url ?? "/", `http://${hostname}`);
@@ -720,6 +910,10 @@ export async function serveA2aOverHttp(runtime, options = {}) {
                         const requestRecord = await runtime.getRun(result.runId);
                         const approvals = await runtime.listApprovals({ threadId: result.threadId, runId: result.runId });
                         const task = buildTaskFromSessionAndRequest(toSessionRecord(session), toRequestRecord(requestRecord), approvals, result.output);
+                        if (task && parsed.pushNotificationConfig) {
+                            registerPushNotificationConfig(task.id, parsed.pushNotificationConfig);
+                            await dispatchPushNotificationsForTask(task.id);
+                        }
                         writeJson(response, 200, toSuccess(payload.id ?? null, toSendMessageResult(payload.method, task)));
                         return;
                     }
@@ -729,12 +923,24 @@ export async function serveA2aOverHttp(runtime, options = {}) {
                             return;
                         }
                         const parsed = parseMessageSendParams(payload.params);
-                        await streamTaskUpdates(response, payload.id ?? null, payload.method, streamSendMessageTaskUpdates(runtime, {
+                        let registeredPushTaskId;
+                        const sourceIterator = streamSendMessageTaskUpdates(runtime, {
                             agentId: parsed.agentId ?? options.defaultAgentId,
                             input: parsed.input,
                             ...(parsed.sessionId ? { threadId: parsed.sessionId } : {}),
                             invocation: attachServiceParameters(parsed.invocation, serviceParameters),
-                        }, payload.method));
+                        }, payload.method);
+                        const iterator = (async function* () {
+                            for await (const item of sourceIterator) {
+                                if (item.task && parsed.pushNotificationConfig && !registeredPushTaskId) {
+                                    registeredPushTaskId = item.task.id;
+                                    registerPushNotificationConfig(item.task.id, parsed.pushNotificationConfig);
+                                    await dispatchPushNotificationsForTask(item.task.id);
+                                }
+                                yield item;
+                            }
+                        }());
+                        await streamTaskUpdates(response, payload.id ?? null, payload.method, iterator);
                         return;
                     }
                     if (payload.method === "tasks/get" || payload.method === "GetTask") {
@@ -767,6 +973,10 @@ export async function serveA2aOverHttp(runtime, options = {}) {
                             return;
                         }
                         if (payload.method === "SubscribeToTask") {
+                            if (isTerminalTaskState(task.status.state)) {
+                                writeJson(response, 200, toError(payload.id ?? null, -32004, "SubscribeToTask is not supported for tasks in terminal state."));
+                                return;
+                            }
                             if (!acceptsSse(request)) {
                                 writeJson(response, 406, toError(payload.id ?? null, -32004, "A2A streaming subscriptions require `Accept: text/event-stream`."));
                                 return;
@@ -777,18 +987,55 @@ export async function serveA2aOverHttp(runtime, options = {}) {
                         writeJson(response, 200, toSuccess(payload.id ?? null, {
                             task,
                             streamable: false,
-                            pushNotifications: false,
+                            pushNotifications: true,
                             nextPollAfterMs: task.status.state === "TASK_STATE_COMPLETED" || task.status.state === "TASK_STATE_FAILED" || task.status.state === "TASK_STATE_CANCELED"
                                 ? 0
                                 : 1_000,
                         }));
                         return;
                     }
-                    if (payload.method === "CreateTaskPushNotificationConfig"
-                        || payload.method === "GetTaskPushNotificationConfig"
-                        || payload.method === "ListTaskPushNotificationConfigs"
-                        || payload.method === "DeleteTaskPushNotificationConfig") {
-                        writeJson(response, 200, toError(payload.id ?? null, -32003, "A2A push notifications are not supported by this bridge."));
+                    if (payload.method === "CreateTaskPushNotificationConfig") {
+                        const { taskId, config } = parseCreatePushNotificationConfigParams(payload.params);
+                        if (!await buildTaskFromRuntime(runtime, taskId)) {
+                            writeJson(response, 200, toError(payload.id ?? null, -32001, "Task not found."));
+                            return;
+                        }
+                        const created = registerPushNotificationConfig(taskId, config);
+                        await dispatchPushNotificationsForTask(taskId);
+                        writeJson(response, 200, toSuccess(payload.id ?? null, clonePushNotificationConfig(created)));
+                        return;
+                    }
+                    if (payload.method === "GetTaskPushNotificationConfig") {
+                        const { taskId, configId } = parsePushNotificationLocatorParams(payload.params);
+                        const config = getPushNotificationConfig(taskId, configId);
+                        if (!config) {
+                            writeJson(response, 200, toError(payload.id ?? null, -32001, "Push notification config not found."));
+                            return;
+                        }
+                        writeJson(response, 200, toSuccess(payload.id ?? null, clonePushNotificationConfig(config)));
+                        return;
+                    }
+                    if (payload.method === "ListTaskPushNotificationConfigs") {
+                        const { taskId, pageSize, pageToken } = parsePushNotificationListParams(payload.params);
+                        const configs = listPushNotificationConfigs(taskId);
+                        const startIndex = pageToken ? Number.parseInt(Buffer.from(pageToken, "base64url").toString("utf8"), 10) || 0 : 0;
+                        const page = configs.slice(startIndex, startIndex + pageSize).map(clonePushNotificationConfig);
+                        const nextIndex = startIndex + page.length;
+                        const nextPageToken = nextIndex < configs.length ? Buffer.from(String(nextIndex), "utf8").toString("base64url") : "";
+                        const result = {
+                            configs: page,
+                            nextPageToken,
+                        };
+                        writeJson(response, 200, toSuccess(payload.id ?? null, result));
+                        return;
+                    }
+                    if (payload.method === "DeleteTaskPushNotificationConfig") {
+                        const { taskId, configId } = parsePushNotificationLocatorParams(payload.params);
+                        if (!deletePushNotificationConfig(taskId, configId)) {
+                            writeJson(response, 200, toError(payload.id ?? null, -32001, "Push notification config not found."));
+                            return;
+                        }
+                        writeJson(response, 200, toSuccess(payload.id ?? null, { deleted: true, id: configId, taskId }));
                         return;
                     }
                     if (payload.method === "GetExtendedAgentCard") {
@@ -833,6 +1080,7 @@ export async function serveA2aOverHttp(runtime, options = {}) {
         agentCardUrl: `http://${hostname}:${resolvedPort}${agentCardPath}`,
         completed,
         close: async () => {
+            unsubscribePushNotifications();
             await new Promise((resolve, reject) => {
                 httpServer.close((error) => {
                     if (error) {

package/package.json

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