@botbotgo/agent-harness 0.0.168 → 0.0.170

package/README.md

@@ -154,6 +154,8 @@ Boundary documents live in:
 - `docs/development/extensions.html`
 - `docs/development/runtime-operations.html`
 - `docs/development/testing-and-release.html`
+- `docs/development/api-reference.html`
+- `docs/development/cookbook.html`
 - `docs/upstream-feature-matrix.md`
 - `docs/product-boundary.md`
 - `docs/runtime-blueprint-assessment.md`
@@ -902,6 +904,7 @@ Primary exports:
 - `createAcpServer`
 - `serveAcpHttp`
 - `serveAcpStdio`
+- `serveA2aHttp`
 - `serveAgUiHttp`
 - `createRuntimeMcpServer`
 - `serveRuntimeMcpOverStdio`
@@ -926,7 +929,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.
+- `serveA2aHttp(runtime)` exposes a minimal A2A-compatible HTTP JSON-RPC bridge plus agent card discovery, mapping `message/send`, `tasks/get`, and `tasks/cancel` onto the existing session/request runtime surface.
 - `serveAgUiHttp(runtime)` exposes a minimal AG-UI-compatible HTTP SSE bridge that projects `run + output.delta + final result` onto `RUN_STARTED`, `TEXT_MESSAGE_*`, and `RUN_FINISHED` 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.
 - `exportRunPackage(...)` and `exportSessionPackage(...)` package stable runtime records, transcript, approvals, events, and artifacts for operator tooling without reaching into persistence internals.
 - `runtime/default.governance.remoteMcp` can now deny or allow specific MCP servers, raise approval requirements by transport, and stamp transport-based risk tiers into runtime governance bundles.
+- detailed A2A adapter guidance lives in [`docs/a2a-bridge.md`](docs/a2a-bridge.md)

package/README.zh.md

@@ -154,6 +154,8 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 - `docs/development/extensions.html`
 - `docs/development/runtime-operations.html`
 - `docs/development/testing-and-release.html`
+- `docs/development/api-reference.html`
+- `docs/development/cookbook.html`
 - `docs/upstream-feature-matrix.md`
 - `docs/product-boundary.md`
 - `docs/runtime-blueprint-assessment.md`
@@ -861,6 +863,7 @@ spec:
 - `createAcpServer`
 - `serveAcpHttp`
 - `serveAcpStdio`
+- `serveA2aHttp`
 - `serveAgUiHttp`
 - `createRuntimeMcpServer`
 - `serveRuntimeMcpOverStdio`
@@ -885,7 +888,9 @@ ACP transport 说明：
 
 - `serveAcpStdio(runtime)` 提供基于 stdio 的 newline-delimited JSON-RPC，适合本地 IDE、CLI 或子进程客户端。
 - `serveAcpHttp(runtime)` 提供基于 HTTP 的 JSON-RPC 与 SSE runtime events，适合远程 operator surface 或独立控制面接入。
+- `serveA2aHttp(runtime)` 提供最小可用的 A2A HTTP JSON-RPC bridge 与 agent card discovery，把 `message/send`、`tasks/get`、`tasks/cancel` 映射到现有 session/request runtime surface。
 - `serveAgUiHttp(runtime)` 提供最小可用的 AG-UI HTTP SSE bridge，把现有 `run + output.delta + final result` 投影成 `RUN_STARTED`、`TEXT_MESSAGE_*` 与 `RUN_FINISHED` 事件，便于 UI 客户端直接接入。
 - `createRuntimeMcpServer(runtime)` 与 `serveRuntimeMcpOverStdio(runtime)` 会把持久化 runtime 控制面本身暴露成 MCP tools，包括 sessions、requests、approvals、artifacts、events 与 package export helpers。
 - `exportRunPackage(...)` 与 `exportSessionPackage(...)` 可把稳定 runtime 记录、transcript、approvals、events 和 artifacts 打包给 operator tooling，而不必直接访问 persistence 内部实现。
 - `runtime/default.governance.remoteMcp` 现在可以按 MCP server 或 transport 做 allow/deny、审批升级，并把 transport 风险等级写进 runtime governance bundles。
+- 更详细的 A2A 适配层开发说明见 [`docs/a2a-bridge.md`](docs/a2a-bridge.md)

package/dist/api.d.ts

@@ -10,6 +10,7 @@ export { buildFlowGraph, exportFlowGraphToMermaid, exportFlowGraphToSequenceMerm
 export { createUpstreamTimelineReducer } from "./upstream-events.js";
 export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, RuntimeRunPackage, RuntimeRunPackageInput, RuntimeSessionPackage, RuntimeSessionPackageInput, UpdateMemoryInput, } from "./contracts/types.js";
 export type { AcpHttpServer, AcpHttpServerOptions } from "./protocol/acp/http.js";
+export type { A2aAgentCard, A2aHttpServer, A2aHttpServerOptions, A2aTask, A2aTaskState } from "./protocol/a2a/http.js";
 export type { AcpStdioServer, AcpStdioServerOptions } from "./protocol/acp/stdio.js";
 export type { AgUiEvent, AgUiHttpServer, AgUiHttpServerOptions, AgUiRunAgentInput } from "./protocol/ag-ui/http.js";
 type PublicApprovalRecord = {
@@ -99,6 +100,7 @@ export declare function replayEvaluationBundle(runtime: AgentHarnessRuntime, inp
 export declare function serveAcpStdio(runtime: AgentHarnessRuntime, options?: import("./protocol/acp/stdio.js").AcpStdioServerOptions): import("./protocol/acp/stdio.js").AcpStdioServer;
 export declare function serveAcpHttp(runtime: AgentHarnessRuntime, options?: import("./protocol/acp/http.js").AcpHttpServerOptions): Promise<import("./protocol/acp/http.js").AcpHttpServer>;
 export declare function serveAgUiHttp(runtime: AgentHarnessRuntime, options?: import("./protocol/ag-ui/http.js").AgUiHttpServerOptions): Promise<import("./protocol/ag-ui/http.js").AgUiHttpServer>;
+export declare function serveA2aHttp(runtime: AgentHarnessRuntime, options?: import("./protocol/a2a/http.js").A2aHttpServerOptions): Promise<import("./protocol/a2a/http.js").A2aHttpServer>;
 export declare function listAgentSkills(runtime: AgentHarnessRuntime, agentId: string, options?: RequirementAssessmentOptions): InventorySkillRecord[];
 export declare function getAgent(runtime: AgentHarnessRuntime, agentId: string, options?: RequirementAssessmentOptions): InventoryAgentRecord | null;
 export declare function describeInventory(runtime: AgentHarnessRuntime, options?: RequirementAssessmentOptions): {

package/dist/api.js

@@ -1,4 +1,5 @@
 import { AgentHarnessRuntime } from "./runtime/harness.js";
+import { serveA2aOverHttp } from "./protocol/a2a/http.js";
 import { serveAgUiOverHttp } from "./protocol/ag-ui/http.js";
 import { serveAcpOverHttp } from "./protocol/acp/http.js";
 import { serveAcpOverStdio } from "./protocol/acp/stdio.js";
@@ -216,6 +217,9 @@ export async function serveAcpHttp(runtime, options) {
 export async function serveAgUiHttp(runtime, options) {
     return serveAgUiOverHttp(runtime, options);
 }
+export async function serveA2aHttp(runtime, options) {
+    return serveA2aOverHttp(runtime, options);
+}
 export function listAgentSkills(runtime, agentId, options) {
     return runtime.listAgentSkills(agentId, options);
 }

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { createAgentHarness } from "./api.js";
+import { serveA2aOverHttp } from "./protocol/a2a/http.js";
 import { serveAgUiOverHttp } from "./protocol/ag-ui/http.js";
 import { serveAcpOverHttp } from "./protocol/acp/http.js";
 import { serveAcpOverStdio } from "./protocol/acp/stdio.js";
@@ -11,6 +12,7 @@ type CliIo = {
 };
 type CliDeps = {
     createAgentHarness?: typeof createAgentHarness;
+    serveA2aOverHttp?: typeof serveA2aOverHttp;
     serveAgUiOverHttp?: typeof serveAgUiOverHttp;
     serveAcpOverHttp?: typeof serveAcpOverHttp;
     serveAcpOverStdio?: typeof serveAcpOverStdio;

package/dist/cli.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { createAgentHarness } from "./api.js";
 import { initProject } from "./init-project.js";
+import { serveA2aOverHttp } from "./protocol/a2a/http.js";
 import { serveAgUiOverHttp } from "./protocol/ag-ui/http.js";
 import { serveAcpOverHttp } from "./protocol/acp/http.js";
 import { serveAcpOverStdio } from "./protocol/acp/stdio.js";
@@ -11,6 +12,7 @@ function renderUsage() {
     return `Usage:
   agent-harness init <project-name> [--template deep-research|single-agent] [--provider <provider>] [--model <model>] [--with-web-search|--no-web-search]
   agent-harness acp serve [--workspace <path>] [--transport stdio|http] [--host <hostname>] [--port <port>]
+  agent-harness a2a serve [--workspace <path>] [--host <hostname>] [--port <port>]
   agent-harness ag-ui serve [--workspace <path>] [--host <hostname>] [--port <port>]
   agent-harness runtime-mcp serve [--workspace <path>]
 `;
@@ -108,7 +110,7 @@ function parseAcpServeOptions(args) {
     }
     return { workspaceRoot, transport, hostname, port };
 }
-function parseHttpServeOptions(args) {
+function parseHttpServeOptions(args, serviceLabel = "HTTP") {
     let workspaceRoot;
     let hostname;
     let port;
@@ -139,7 +141,7 @@ function parseHttpServeOptions(args) {
             }
             const parsedPort = Number.parseInt(value, 10);
             if (!Number.isFinite(parsedPort) || parsedPort < 0) {
-                return { workspaceRoot, hostname, error: `Invalid AG-UI port: ${value}` };
+                return { workspaceRoot, hostname, error: `Invalid ${serviceLabel} port: ${value}` };
             }
             port = parsedPort;
             index += 1;
@@ -155,6 +157,7 @@ export async function runCli(argv, io = {}, deps = {}) {
     const stderr = io.stderr ?? ((message) => process.stderr.write(message));
     const [command, projectName, ...rest] = argv;
     const createHarness = deps.createAgentHarness ?? createAgentHarness;
+    const serveA2a = deps.serveA2aOverHttp ?? serveA2aOverHttp;
     const serveAgUi = deps.serveAgUiOverHttp ?? serveAgUiOverHttp;
     const serveAcpHttp = deps.serveAcpOverHttp ?? serveAcpOverHttp;
     const serveAcp = deps.serveAcpOverStdio ?? serveAcpOverStdio;
@@ -232,7 +235,7 @@ export async function runCli(argv, io = {}, deps = {}) {
             stderr(renderUsage());
             return 1;
         }
-        const parsed = parseHttpServeOptions(subcommandArgs);
+        const parsed = parseHttpServeOptions(subcommandArgs, "AG-UI");
         if (parsed.error) {
             stderr(`${parsed.error}\n`);
             stderr(renderUsage());
@@ -256,13 +259,43 @@ export async function runCli(argv, io = {}, deps = {}) {
             return 1;
         }
     }
+    if (command === "a2a") {
+        const [subcommand, ...subcommandArgs] = [projectName, ...rest];
+        if (subcommand !== "serve") {
+            stderr(renderUsage());
+            return 1;
+        }
+        const parsed = parseHttpServeOptions(subcommandArgs, "A2A");
+        if (parsed.error) {
+            stderr(`${parsed.error}\n`);
+            stderr(renderUsage());
+            return 1;
+        }
+        try {
+            const runtime = await createHarness(path.resolve(cwd, parsed.workspaceRoot ?? "."));
+            const workspacePath = path.resolve(cwd, parsed.workspaceRoot ?? ".");
+            const server = await serveA2a(runtime, {
+                hostname: parsed.hostname,
+                port: parsed.port,
+            });
+            stderr(`Serving A2A over http from ${workspacePath} at ${server.rpcUrl} (card ${server.agentCardUrl})\n`);
+            await server.completed;
+            await runtime.stop();
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            stderr(`${message}\n`);
+            return 1;
+        }
+    }
     if (command === "runtime-mcp") {
         const [subcommand, ...subcommandArgs] = [projectName, ...rest];
         if (subcommand !== "serve") {
             stderr(renderUsage());
             return 1;
         }
-        const parsed = parseHttpServeOptions(subcommandArgs);
+        const parsed = parseHttpServeOptions(subcommandArgs, "runtime MCP");
         if (parsed.error) {
             stderr(`${parsed.error}\n`);
             stderr(renderUsage());

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRunPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, listRunEvents, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRunPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, listRunEvents, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
 export type { AcpApproval, AcpArtifact, AcpEventNotification, AcpJsonRpcError, AcpJsonRpcRequest, AcpJsonRpcResponse, AcpJsonRpcSuccess, AcpRequestRecord, AcpRunRequestParams, AcpServerCapabilities, AcpSessionRecord, } from "./acp.js";
 export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, RuntimeRunPackage, RuntimeRunPackageInput, RuntimeSessionPackage, RuntimeSessionPackageInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
 export type { BuildFlowGraphInput, FlowEdge, FlowEdgeKind, FlowGraph, FlowGraphMermaidOptions, FlowGraphSequenceMermaidOptions, FlowGroup, FlowGroupKind, FlowNode, FlowNodeKind, FlowNodeLayer, FlowNodeStatus, } from "./flow/index.js";
-export type { AcpHttpServer, AcpHttpServerOptions, AcpStdioServer, AcpStdioServerOptions, AgUiEvent, AgUiHttpServer, AgUiHttpServerOptions, AgUiRunAgentInput, } from "./api.js";
+export type { A2aAgentCard, A2aHttpServer, A2aHttpServerOptions, A2aTask, A2aTaskState, AcpHttpServer, AcpHttpServerOptions, AcpStdioServer, AcpStdioServerOptions, AgUiEvent, AgUiHttpServer, AgUiHttpServerOptions, AgUiRunAgentInput, } from "./api.js";
 export type { RuntimeMcpServerOptions, ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";
 export type { UpstreamTimelineProjection, UpstreamTimelineReducer } from "./upstream-events.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRunPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, listRunEvents, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, buildFlowGraph, cancelRun, createAgentHarness, createAcpServer, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportRunPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getRequest, getHealth, listMemories, listRunEvents, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, exportFlowGraphToMermaid, exportFlowGraphToSequenceMermaid, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.167";
+export declare const AGENT_HARNESS_VERSION = "0.0.169";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.167";
+export const AGENT_HARNESS_VERSION = "0.0.169";

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

@@ -0,0 +1,86 @@
+import type { AgentHarnessRuntime } from "../../runtime/harness.js";
+export type A2aHttpServerOptions = {
+    hostname?: string;
+    port?: number;
+    rpcPath?: string;
+    agentCardPath?: string;
+    agentName?: string;
+    agentDescription?: string;
+    documentationUrl?: string;
+    provider?: {
+        organization?: string;
+        url?: string;
+    };
+    defaultAgentId?: string;
+};
+export type A2aAgentCard = {
+    name: string;
+    description: string;
+    version: string;
+    url: string;
+    preferredTransport: "JSONRPC";
+    provider?: {
+        organization?: string;
+        url?: string;
+    };
+    documentationUrl?: string;
+    capabilities: {
+        streaming: boolean;
+        pushNotifications: boolean;
+        stateTransitionHistory: boolean;
+    };
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    skills: Array<{
+        id: string;
+        name: string;
+        description: string;
+        tags: string[];
+        examples: string[];
+    }>;
+};
+export type A2aTaskState = "submitted" | "working" | "input-required" | "completed" | "failed" | "canceled";
+type A2aTaskStatus = {
+    state: A2aTaskState;
+    timestamp: string;
+    message?: {
+        role: "agent";
+        parts: Array<{
+            type: "text";
+            text: string;
+        }>;
+    };
+};
+export type A2aTask = {
+    id: string;
+    contextId: string;
+    kind: "task";
+    status: A2aTaskStatus;
+    history: Array<{
+        role: "user" | "agent";
+        parts: Array<{
+            type: "text";
+            text: string;
+        }>;
+    }>;
+    artifacts: Array<{
+        name: string;
+        parts: Array<{
+            type: "text";
+            text: string;
+        }>;
+    }>;
+    metadata: Record<string, unknown>;
+};
+export type A2aHttpServer = {
+    hostname: string;
+    port: number;
+    rpcPath: string;
+    agentCardPath: string;
+    rpcUrl: string;
+    agentCardUrl: string;
+    completed: Promise<void>;
+    close: () => Promise<void>;
+};
+export declare function serveA2aOverHttp(runtime: AgentHarnessRuntime, options?: A2aHttpServerOptions): Promise<A2aHttpServer>;
+export {};

package/dist/protocol/a2a/http.js

@@ -0,0 +1,431 @@
+import { createServer } from "node:http";
+function normalizePath(value, fallback) {
+    const source = typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+    return source.startsWith("/") ? source : `/${source}`;
+}
+function writeJson(response, statusCode, payload) {
+    response.statusCode = statusCode;
+    response.setHeader("content-type", "application/json; charset=utf-8");
+    response.end(JSON.stringify(payload));
+}
+function readRequestBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        request.on("data", (chunk) => {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        request.on("error", reject);
+    });
+}
+function toError(id, code, message, data) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code,
+            message,
+            ...(data === undefined ? {} : { data }),
+        },
+    };
+}
+function toSuccess(id, result) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        result,
+    };
+}
+function parseTextPart(part) {
+    if (!part || typeof part !== "object" || Array.isArray(part)) {
+        return null;
+    }
+    const typed = part;
+    if (typed.type !== "text" || typeof typed.text !== "string" || typed.text.trim().length === 0) {
+        return null;
+    }
+    return typed.text;
+}
+function parseMessageSendParams(params) {
+    if (!params || typeof params !== "object" || Array.isArray(params)) {
+        throw new Error("A2A message/send requires params object.");
+    }
+    const typed = params;
+    const message = typed.message;
+    if (!message || typeof message !== "object" || Array.isArray(message)) {
+        throw new Error("A2A message/send requires `message`.");
+    }
+    const typedMessage = message;
+    const role = typeof typedMessage.role === "string" ? typedMessage.role : "";
+    if (role !== "user") {
+        throw new Error("A2A message/send currently supports only `user` role messages.");
+    }
+    const parts = Array.isArray(typedMessage.parts) ? typedMessage.parts : [];
+    const textParts = parts.map(parseTextPart).filter((item) => Boolean(item));
+    if (textParts.length === 0) {
+        throw new Error("A2A message/send requires at least one text part.");
+    }
+    const sessionId = typeof typed.contextId === "string" && typed.contextId.trim().length > 0
+        ? typed.contextId.trim()
+        : undefined;
+    const agentId = typeof typed.agentId === "string" && typed.agentId.trim().length > 0
+        ? typed.agentId.trim()
+        : undefined;
+    const metadata = typed.metadata;
+    const invocation = metadata && typeof metadata === "object" && !Array.isArray(metadata)
+        ? metadata
+        : undefined;
+    return {
+        input: textParts.join("\n\n"),
+        ...(agentId ? { agentId } : {}),
+        ...(sessionId ? { sessionId } : {}),
+        ...(invocation ? { invocation } : {}),
+    };
+}
+function parseTaskLocatorParams(params) {
+    if (!params || typeof params !== "object" || Array.isArray(params)) {
+        throw new Error("A2A task lookup requires params object.");
+    }
+    const typed = params;
+    const taskId = typeof typed.id === "string" && typed.id.trim().length > 0
+        ? typed.id.trim()
+        : typeof typed.taskId === "string" && typed.taskId.trim().length > 0
+            ? typed.taskId.trim()
+            : "";
+    if (!taskId) {
+        throw new Error("A2A task lookup requires `id`.");
+    }
+    return { taskId };
+}
+function mapRunState(state) {
+    switch (state) {
+        case "queued":
+            return "submitted";
+        case "running":
+            return "working";
+        case "waiting_for_approval":
+            return "input-required";
+        case "completed":
+            return "completed";
+        case "cancelled":
+            return "canceled";
+        case "failed":
+        default:
+            return "failed";
+    }
+}
+function toTextParts(text) {
+    if (typeof text !== "string" || text.length === 0) {
+        return [];
+    }
+    return [{ type: "text", text }];
+}
+function contentToText(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (!Array.isArray(content)) {
+        return undefined;
+    }
+    const text = content
+        .filter((part) => part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("\n\n")
+        .trim();
+    return text.length > 0 ? text : undefined;
+}
+function buildTaskFromSessionAndRequest(session, request, approvals, output, failureMessage) {
+    if (!session || !request) {
+        return null;
+    }
+    const latestUserMessage = [...session.messages].reverse().find((message) => message.role === "user");
+    const latestAgentMessage = [...session.messages].reverse().find((message) => message.role === "assistant");
+    const approval = approvals.find((item) => item.status === "pending");
+    const latestAgentText = contentToText(latestAgentMessage?.content);
+    const latestUserText = contentToText(latestUserMessage?.content);
+    const statusText = request.state === "waiting_for_approval"
+        ? approval
+            ? `Approval required for tool ${approval.toolName}.`
+            : "Approval required."
+        : output ?? latestAgentText ?? failureMessage;
+    return {
+        id: request.requestId,
+        contextId: session.sessionId,
+        kind: "task",
+        status: {
+            state: mapRunState(request.state),
+            timestamp: request.updatedAt,
+            ...(statusText ? {
+                message: {
+                    role: "agent",
+                    parts: toTextParts(statusText),
+                },
+            } : {}),
+        },
+        history: [
+            ...(latestUserText
+                ? [{
+                        role: "user",
+                        parts: toTextParts(latestUserText),
+                    }]
+                : []),
+            ...(latestAgentText
+                ? [{
+                        role: "agent",
+                        parts: toTextParts(latestAgentText),
+                    }]
+                : []),
+        ],
+        artifacts: [],
+        metadata: {
+            agentId: request.agentId,
+            sessionId: session.sessionId,
+            requestId: request.requestId,
+            state: request.state,
+            approvalIds: approvals.map((item) => item.approvalId),
+        },
+    };
+}
+async function buildTaskFromRuntime(runtime, requestId) {
+    const request = await runtime.getRun(requestId);
+    if (!request) {
+        return null;
+    }
+    const session = await runtime.getThread(request.threadId);
+    const approvals = await runtime.listApprovals({ threadId: request.threadId, runId: request.runId });
+    return buildTaskFromSessionAndRequest(session ? {
+        sessionId: session.threadId,
+        entryAgentId: session.entryAgentId,
+        currentAgentId: session.currentAgentId,
+        currentState: session.currentState,
+        latestRequestId: session.latestRunId,
+        createdAt: session.createdAt,
+        updatedAt: session.updatedAt,
+        messages: session.messages,
+        requests: session.runs.map((run) => ({
+            requestId: run.runId,
+            sessionId: run.threadId,
+            agentId: run.agentId,
+            executionMode: run.executionMode,
+            adapterKind: run.adapterKind,
+            createdAt: run.createdAt,
+            updatedAt: run.updatedAt,
+            state: run.state,
+            checkpointRef: run.checkpointRef,
+            resumable: run.resumable,
+            startedAt: run.startedAt,
+            endedAt: run.endedAt,
+            lastActivityAt: run.lastActivityAt,
+            currentAgentId: run.currentAgentId,
+            delegationChain: run.delegationChain,
+            runtimeSnapshot: run.runtimeSnapshot,
+        })),
+        pendingDecision: session.pendingDecision,
+    } : null, {
+        requestId: request.runId,
+        sessionId: request.threadId,
+        agentId: request.agentId,
+        executionMode: request.executionMode,
+        adapterKind: request.adapterKind,
+        createdAt: request.createdAt,
+        updatedAt: request.updatedAt,
+        state: request.state,
+        checkpointRef: request.checkpointRef,
+        resumable: request.resumable,
+        startedAt: request.startedAt,
+        endedAt: request.endedAt,
+        lastActivityAt: request.lastActivityAt,
+        currentAgentId: request.currentAgentId,
+        delegationChain: request.delegationChain,
+        runtimeSnapshot: request.runtimeSnapshot,
+    }, approvals);
+}
+function buildAgentCard(runtime, options) {
+    const inventory = runtime.describeWorkspaceInventory();
+    const skills = inventory.agents.map((agent) => ({
+        id: agent.id,
+        name: agent.id,
+        description: agent.description || `Agent ${agent.id}`,
+        tags: ["agent-harness", agent.parentAgentId ? "subagent" : "agent"],
+        examples: [`Send a task to ${agent.id}.`],
+    }));
+    return {
+        name: options.agentName,
+        description: options.agentDescription,
+        version: "0.1.0",
+        url: options.rpcUrl,
+        preferredTransport: "JSONRPC",
+        capabilities: {
+            streaming: false,
+            pushNotifications: false,
+            stateTransitionHistory: true,
+        },
+        defaultInputModes: ["text"],
+        defaultOutputModes: ["text"],
+        skills,
+    };
+}
+export async function serveA2aOverHttp(runtime, options = {}) {
+    const hostname = options.hostname?.trim() || "127.0.0.1";
+    const port = typeof options.port === "number" && Number.isFinite(options.port) ? options.port : 0;
+    const rpcPath = normalizePath(options.rpcPath, "/a2a");
+    const agentCardPath = normalizePath(options.agentCardPath, "/.well-known/agent-card.json");
+    const httpServer = createServer(async (request, response) => {
+        try {
+            const requestUrl = new URL(request.url ?? "/", `http://${hostname}`);
+            if (request.method === "GET" && (requestUrl.pathname === agentCardPath || requestUrl.pathname === "/.well-known/agent.json")) {
+                const card = buildAgentCard(runtime, {
+                    agentName: options.agentName ?? "agent-harness-runtime",
+                    agentDescription: options.agentDescription ?? "Agent-harness A2A bridge over the persisted runtime surface.",
+                    cardUrl: `http://${hostname}:${resolvedPort}${agentCardPath}`,
+                    rpcUrl: `http://${hostname}:${resolvedPort}${rpcPath}`,
+                });
+                writeJson(response, 200, {
+                    ...card,
+                    ...(options.documentationUrl ? { documentationUrl: options.documentationUrl } : {}),
+                    ...(options.provider ? { provider: options.provider } : {}),
+                    ...(options.defaultAgentId ? { defaultAgentId: options.defaultAgentId } : {}),
+                });
+                return;
+            }
+            if (request.method === "POST" && (requestUrl.pathname === rpcPath || requestUrl.pathname === agentCardPath)) {
+                let payload;
+                try {
+                    payload = JSON.parse(await readRequestBody(request));
+                }
+                catch {
+                    writeJson(response, 400, toError(null, -32700, "Invalid JSON payload."));
+                    return;
+                }
+                if (payload.jsonrpc !== "2.0" || typeof payload.method !== "string") {
+                    writeJson(response, 400, toError(payload.id ?? null, -32600, "Invalid JSON-RPC request."));
+                    return;
+                }
+                try {
+                    if (payload.method === "message/send" || payload.method === "tasks/send") {
+                        const parsed = parseMessageSendParams(payload.params);
+                        const result = await runtime.run({
+                            agentId: parsed.agentId ?? options.defaultAgentId,
+                            input: parsed.input,
+                            ...(parsed.sessionId ? { threadId: parsed.sessionId } : {}),
+                            ...(parsed.invocation ? { invocation: parsed.invocation } : {}),
+                        });
+                        const session = await runtime.getThread(result.threadId);
+                        const requestRecord = await runtime.getRun(result.runId);
+                        const approvals = await runtime.listApprovals({ threadId: result.threadId, runId: result.runId });
+                        const task = buildTaskFromSessionAndRequest(session ? {
+                            sessionId: session.threadId,
+                            entryAgentId: session.entryAgentId,
+                            currentAgentId: session.currentAgentId,
+                            currentState: session.currentState,
+                            latestRequestId: session.latestRunId,
+                            createdAt: session.createdAt,
+                            updatedAt: session.updatedAt,
+                            messages: session.messages,
+                            requests: session.runs.map((run) => ({
+                                requestId: run.runId,
+                                sessionId: run.threadId,
+                                agentId: run.agentId,
+                                executionMode: run.executionMode,
+                                adapterKind: run.adapterKind,
+                                createdAt: run.createdAt,
+                                updatedAt: run.updatedAt,
+                                state: run.state,
+                                checkpointRef: run.checkpointRef,
+                                resumable: run.resumable,
+                                startedAt: run.startedAt,
+                                endedAt: run.endedAt,
+                                lastActivityAt: run.lastActivityAt,
+                                currentAgentId: run.currentAgentId,
+                                delegationChain: run.delegationChain,
+                                runtimeSnapshot: run.runtimeSnapshot,
+                            })),
+                            pendingDecision: session.pendingDecision,
+                        } : null, requestRecord ? {
+                            requestId: requestRecord.runId,
+                            sessionId: requestRecord.threadId,
+                            agentId: requestRecord.agentId,
+                            executionMode: requestRecord.executionMode,
+                            adapterKind: requestRecord.adapterKind,
+                            createdAt: requestRecord.createdAt,
+                            updatedAt: requestRecord.updatedAt,
+                            state: requestRecord.state,
+                            checkpointRef: requestRecord.checkpointRef,
+                            resumable: requestRecord.resumable,
+                            startedAt: requestRecord.startedAt,
+                            endedAt: requestRecord.endedAt,
+                            lastActivityAt: requestRecord.lastActivityAt,
+                            currentAgentId: requestRecord.currentAgentId,
+                            delegationChain: requestRecord.delegationChain,
+                            runtimeSnapshot: requestRecord.runtimeSnapshot,
+                        } : null, approvals, result.output);
+                        writeJson(response, 200, toSuccess(payload.id ?? null, task));
+                        return;
+                    }
+                    if (payload.method === "tasks/get") {
+                        const { taskId } = parseTaskLocatorParams(payload.params);
+                        const task = await buildTaskFromRuntime(runtime, taskId);
+                        if (!task) {
+                            writeJson(response, 200, toError(payload.id ?? null, -32004, "Task not found."));
+                            return;
+                        }
+                        writeJson(response, 200, toSuccess(payload.id ?? null, task));
+                        return;
+                    }
+                    if (payload.method === "tasks/cancel") {
+                        const { taskId } = parseTaskLocatorParams(payload.params);
+                        const result = await runtime.cancelRun({ runId: taskId, reason: "Cancelled via A2A bridge." });
+                        const task = await buildTaskFromRuntime(runtime, result.runId);
+                        writeJson(response, 200, toSuccess(payload.id ?? null, task));
+                        return;
+                    }
+                    writeJson(response, 200, toError(payload.id ?? null, -32601, `Unknown A2A method: ${payload.method}`));
+                }
+                catch (error) {
+                    writeJson(response, 200, toError(payload.id ?? null, -32000, error instanceof Error ? error.message : String(error)));
+                }
+                return;
+            }
+            writeJson(response, 404, {
+                error: "Not Found",
+                rpcPath,
+                agentCardPath,
+            });
+        }
+        catch (error) {
+            writeJson(response, 500, {
+                error: error instanceof Error ? error.message : "A2A HTTP transport failed.",
+            });
+        }
+    });
+    const completed = new Promise((resolve, reject) => {
+        httpServer.once("close", resolve);
+        httpServer.once("error", reject);
+    });
+    await new Promise((resolve, reject) => {
+        httpServer.listen(port, hostname, () => resolve());
+        httpServer.once("error", reject);
+    });
+    const address = httpServer.address();
+    const resolvedPort = typeof address === "object" && address ? address.port : port;
+    return {
+        hostname,
+        port: resolvedPort,
+        rpcPath,
+        agentCardPath,
+        rpcUrl: `http://${hostname}:${resolvedPort}${rpcPath}`,
+        agentCardUrl: `http://${hostname}:${resolvedPort}${agentCardPath}`,
+        completed,
+        close: async () => {
+            await new Promise((resolve, reject) => {
+                httpServer.close((error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.168",
+  "version": "0.0.170",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",