@zhin.js/a2a 1.0.2 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @zhin.js/a2a
 
+## 2.0.0
+
+### Patch Changes
+
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/host-router@3.0.0
+  - @zhin.js/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+
+## 1.0.3
+
+### Patch Changes
+
+- 16ec4e8: Harden Plugin Runtime migration boundaries: make process-level registries, the game
+  catalog, and game-record storage generation-owned so HMR replacement cannot unregister the
+  active generation, discover workspace agents without mutating `process.cwd()`, and
+  require authentication for production A2A endpoints.
+
+  Game SessionServices and Group Suite mutable state now live in owner-scoped
+  resources. Lottery database, Agent dependencies, and outbound push bindings use
+  generation registrations with rollback-safe disposal.
+
+  The Plugin Runtime Console demo scope now follows ADR 0016 and rejects project
+  file, environment, and database RPCs, closing both direct and file-manager paths
+  that could expose `.env` values.
+
+- Updated dependencies [16ec4e8]
+- Updated dependencies [cc5c94d]
+- Updated dependencies [447f3e2]
+  - @zhin.js/core@1.3.5
+  - @zhin.js/agent@1.0.4
+  - @zhin.js/host-http@1.0.1
+  - zhin.js@4.1.3
+  - @zhin.js/logger@1.0.75
+  - @zhin.js/host-router@2.0.4
+
 ## 1.0.2
 
 ### Patch Changes

package/lib/card-builder.d.ts

@@ -3,6 +3,6 @@
  */
 import { type AgentCard } from '@a2a-js/sdk';
 import type { AgentBindingRegistry } from '@zhin.js/agent/config';
-export declare function buildAgentCardForBinding(agentName: string, registry: AgentBindingRegistry, publicBaseUrl: string): AgentCard | null;
+export declare function buildAgentCardForBinding(agentName: string, registry: AgentBindingRegistry, publicBaseUrl: string, basePath?: string): AgentCard | null;
 export declare function listExposableAgentNames(registry: AgentBindingRegistry): string[];
 //# sourceMappingURL=card-builder.d.ts.map

package/lib/card-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"card-builder.d.ts","sourceRoot":"","sources":["../src/card-builder.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAwB,KAAK,SAAS,EAAmB,MAAM,aAAa,CAAC;AAEpF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAuBlE,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,oBAAoB,EAC9B,aAAa,EAAE,MAAM,GACpB,SAAS,GAAG,IAAI,CAgElB;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAEhF"}
+{"version":3,"file":"card-builder.d.ts","sourceRoot":"","sources":["../src/card-builder.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAwB,KAAK,SAAS,EAAmB,MAAM,aAAa,CAAC;AAEpF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAuBlE,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,oBAAoB,EAC9B,aAAa,EAAE,MAAM,EACrB,QAAQ,SAAS,GAChB,SAAS,GAAG,IAAI,CAuElB;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAEhF"}

package/lib/card-builder.js

@@ -21,13 +21,18 @@ const DEFAULT_SKILLS = [
         tags: ['orchestration', 'delegate'],
     }),
 ];
-export function buildAgentCardForBinding(agentName, registry, publicBaseUrl) {
+export function buildAgentCardForBinding(agentName, registry, publicBaseUrl, basePath = '/a2a') {
     const binding = registry.getBinding(agentName);
     if (!binding)
         return null;
     const nickname = binding.nickname ?? agentName;
-    const jsonRpcUrl = a2aJsonRpcUrl(publicBaseUrl, agentName);
-    const restUrl = a2aRestUrl(publicBaseUrl, agentName);
+    const normalizedBasePath = basePath === '/a2a' ? undefined : basePath;
+    const jsonRpcUrl = normalizedBasePath
+        ? `${publicBaseUrl}${normalizedBasePath}/${encodeURIComponent(agentName)}/jsonrpc`
+        : a2aJsonRpcUrl(publicBaseUrl, agentName);
+    const restUrl = normalizedBasePath
+        ? `${publicBaseUrl}${normalizedBasePath}/${encodeURIComponent(agentName)}/rest`
+        : a2aRestUrl(publicBaseUrl, agentName);
     const skills = [
         makeSkill({
             id: agentName,
@@ -81,7 +86,9 @@ export function buildAgentCardForBinding(agentName, registry, publicBaseUrl) {
         defaultOutputModes: ['text/plain'],
         skills,
         signatures: [],
-        documentationUrl: a2aAgentCardUrl(publicBaseUrl, agentName),
+        documentationUrl: normalizedBasePath
+            ? `${publicBaseUrl}${normalizedBasePath}/${encodeURIComponent(agentName)}/.well-known/agent-card.json`
+            : a2aAgentCardUrl(publicBaseUrl, agentName),
     };
 }
 export function listExposableAgentNames(registry) {

package/lib/card-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"card-builder.js","sourceRoot":"","sources":["../src/card-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"card-builder.js","sourceRoot":"","sources":["../src/card-builder.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,oBAAoB,EAAmC,MAAM,aAAa,CAAC;AAGpF,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzE,SAAS,SAAS,CAAC,OAA8E;IAC/F,OAAO;QACL,GAAG,OAAO;QACV,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,EAAE;QACxB,QAAQ,EAAE,EAAE;QACZ,UAAU,EAAE,CAAC,YAAY,CAAC;QAC1B,WAAW,EAAE,CAAC,YAAY,CAAC;QAC3B,oBAAoB,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;KAC9D,CAAC;AACJ,CAAC;AAED,MAAM,cAAc,GAAiB;IACnC,SAAS,CAAC;QACR,EAAE,EAAE,UAAU;QACd,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,wDAAwD;QACrE,IAAI,EAAE,CAAC,eAAe,EAAE,UAAU,CAAC;KACpC,CAAC;CACH,CAAC;AAEF,MAAM,UAAU,wBAAwB,CACtC,SAAiB,EACjB,QAA8B,EAC9B,aAAqB,EACrB,QAAQ,GAAG,MAAM;IAEjB,MAAM,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAC/C,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,SAAS,CAAC;IAC/C,MAAM,kBAAkB,GAAG,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;IACtE,MAAM,UAAU,GAAG,kBAAkB;QACnC,CAAC,CAAC,GAAG,aAAa,GAAG,kBAAkB,IAAI,kBAAkB,CAAC,SAAS,CAAC,UAAU;QAClF,CAAC,CAAC,aAAa,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,kBAAkB;QAChC,CAAC,CAAC,GAAG,aAAa,GAAG,kBAAkB,IAAI,kBAAkB,CAAC,SAAS,CAAC,OAAO;QAC/E,CAAC,CAAC,UAAU,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAEzC,MAAM,MAAM,GAAiB;QAC3B,SAAS,CAAC;YACR,EAAE,EAAE,SAAS;YACb,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,eAAe,SAAS,MAAM,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,KAAK,GAAG;YACpF,IAAI,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;SAC1B,CAAC;QACF,GAAG,cAAc;KAClB,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,sBAAsB,SAAS,gBAAgB,OAAO,CAAC,aAAa,WAAW,OAAO,CAAC,KAAK,EAAE;QAC3G,OAAO,EAAE,OAAO;QAChB,mBAAmB,EAAE;YACnB;gBACE,GAAG,EAAE,UAAU;gBACf,eAAe,EAAE,SAAS;gBAC1B,eAAe,EAAE,oBAAoB;gBACrC,MAAM,EAAE,EAAE;aACX;YACD;gBACE,GAAG,EAAE,OAAO;gBACZ,eAAe,EAAE,WAAW;gBAC5B,eAAe,EAAE,oBAAoB;gBACrC,MAAM,EAAE,EAAE;aACX;SACF;QACD,QAAQ,EAAE;YACR,YAAY,EAAE,SAAS;YACvB,GAAG,EAAE,gCAAgC;SACtC;QACD,YAAY,EAAE;YACZ,SAAS,EAAE,IAAI;YACf,iBAAiB,EAAE,KAAK;YACxB,UAAU,EAAE,EAAE;SACf;QACD,eAAe,EAAE;YACf,MAAM,EAAE;gBACN,MAAM,EAAE;oBACN,KAAK,EAAE,wBAAwB;oBAC/B,KAAK,EAAE;wBACL,WAAW,EAAE,2BAA2B;wBACxC,MAAM,EAAE,QAAQ;wBAChB,YAAY,EAAE,EAAE;qBACjB;iBACF;aACF;SACF;QACD,oBAAoB,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;QAC7D,iBAAiB,EAAE,CAAC,YAAY,EAAE,kBAAkB,CAAC;QACrD,kBAAkB,EAAE,CAAC,YAAY,CAAC;QAClC,MAAM;QACN,UAAU,EAAE,EAAE;QACd,gBAAgB,EAAE,kBAAkB;YAClC,CAAC,CAAC,GAAG,aAAa,GAAG,kBAAkB,IAAI,kBAAkB,CAAC,SAAS,CAAC,8BAA8B;YACtG,CAAC,CAAC,eAAe,CAAC,aAAa,EAAE,SAAS,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,QAA8B;IACpE,OAAO,QAAQ,CAAC,cAAc,EAAE,CAAC;AACnC,CAAC"}

package/lib/runtime.d.ts

@@ -0,0 +1,19 @@
+import type { HttpHost } from '@zhin.js/host-http';
+import type { AgentHostPort } from '@zhin.js/agent/runtime';
+export interface RuntimeA2aConfig {
+    readonly enabled?: boolean;
+    readonly path?: string;
+    readonly token?: string;
+    readonly publicUrl?: string;
+}
+export interface InstallRuntimeA2aOptions {
+    readonly http: HttpHost;
+    readonly agentHost: AgentHostPort;
+    readonly config?: RuntimeA2aConfig;
+    readonly fallbackToken?: string;
+    readonly fallbackPublicUrl: string;
+    readonly production?: boolean;
+}
+/** Mount Agent Card, JSON-RPC, and HTTP+JSON routes on the Runtime HTTP Host. */
+export declare function installRuntimeA2a(options: InstallRuntimeA2aOptions): () => void;
+//# sourceMappingURL=runtime.d.ts.map

package/lib/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAQ5D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAOD,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,IAAI,CAyD/E"}

package/lib/runtime.js

@@ -0,0 +1,109 @@
+import { DefaultRequestHandler, InMemoryTaskStore, } from '@a2a-js/sdk/server';
+import { AGENT_CARD_PATH } from '@a2a-js/sdk';
+import { buildAgentCardForBinding, listExposableAgentNames } from './card-builder.js';
+import { ZhinA2AExecutor } from './agent-executor.js';
+import { handleAgentCard, handleJsonRpc, handleRest } from './http-handlers.js';
+import { verifyA2aBearer } from './auth.js';
+/** Mount Agent Card, JSON-RPC, and HTTP+JSON routes on the Runtime HTTP Host. */
+export function installRuntimeA2a(options) {
+    if (options.config?.enabled === false)
+        return () => undefined;
+    const basePath = normalizePath(options.config?.path ?? '/a2a');
+    const publicBaseUrl = (options.config?.publicUrl ?? options.fallbackPublicUrl).replace(/\/+$/u, '');
+    const token = options.config?.token ?? options.fallbackToken ?? '';
+    if (options.production === true && !token) {
+        throw new Error('A2A requires a2a.token or http.token in production');
+    }
+    const service = options.agentHost.service;
+    const agent = options.agentHost.agent;
+    const registry = service.getBindingRegistry();
+    const stacks = new Map();
+    for (const agentName of listExposableAgentNames(registry)) {
+        const card = buildAgentCardForBinding(agentName, registry, publicBaseUrl, basePath);
+        if (!card)
+            continue;
+        const executor = new ZhinA2AExecutor({
+            agentName,
+            getAgent: () => agent,
+            resolveBinding: () => registry.getBinding(agentName),
+        });
+        stacks.set(agentName, {
+            card,
+            handler: new DefaultRequestHandler(card, new InMemoryTaskStore(), executor),
+        });
+    }
+    const unregister = options.http.route('ALL', `${basePath}/*`, async (request, response, url) => {
+        if (token && !verifyA2aBearer(request, token)) {
+            writeJson(response, 401, { error: 'Unauthorized - Bearer token required' });
+            return;
+        }
+        const route = parseRoute(url.pathname, basePath);
+        if (!route) {
+            writeJson(response, 404, { error: 'Not found' });
+            return;
+        }
+        const stack = stacks.get(route.agentName);
+        if (!stack) {
+            writeJson(response, 404, { error: `A2A agent "${route.agentName}" not found` });
+            return;
+        }
+        if (route.kind === 'card') {
+            await handleAgentCard(request, response, stack.handler);
+        }
+        else if (route.kind === 'jsonrpc') {
+            await handleJsonRpc(request, response, stack.handler);
+        }
+        else {
+            await handleRest(request, response, stack.handler, route.restPath);
+        }
+    }, { summary: 'Agent-to-Agent protocol', tags: ['a2a'] });
+    return () => {
+        unregister();
+        stacks.clear();
+    };
+}
+function parseRoute(pathname, basePath) {
+    const prefix = `${basePath}/`;
+    if (!pathname.startsWith(prefix))
+        return null;
+    const slash = pathname.indexOf('/', prefix.length);
+    if (slash < 0)
+        return null;
+    let agentName;
+    try {
+        agentName = decodeURIComponent(pathname.slice(prefix.length, slash));
+    }
+    catch {
+        return null;
+    }
+    if (!agentName)
+        return null;
+    const tail = pathname.slice(slash + 1).replace(/^\/+|\/+$/gu, '');
+    if (tail === `.well-known/${AGENT_CARD_PATH}` || tail === '.well-known/agent-card.json') {
+        return { agentName, kind: 'card' };
+    }
+    if (tail === 'jsonrpc' || tail.startsWith('jsonrpc/')) {
+        return { agentName, kind: 'jsonrpc' };
+    }
+    if (tail === 'rest' || tail.startsWith('rest/')) {
+        return {
+            agentName,
+            kind: 'rest',
+            restPath: tail === 'rest' ? '' : tail.slice('rest/'.length),
+        };
+    }
+    return null;
+}
+function writeJson(response, status, body) {
+    const payload = JSON.stringify(body);
+    response.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': String(Buffer.byteLength(payload)),
+    });
+    response.end(payload);
+}
+function normalizePath(path) {
+    const leading = path.startsWith('/') ? path : `/${path}`;
+    return leading.replace(/\/+$/u, '') || '/a2a';
+}
+//# sourceMappingURL=runtime.js.map

package/lib/runtime.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/a2a",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "description": "A2A Protocol server for Zhin.js — multi-agent Agent Cards and task delegation",
   "type": "module",
   "main": "./lib/index.js",
@@ -10,6 +10,11 @@
       "types": "./lib/index.d.ts",
       "development": "./src/index.ts",
       "import": "./lib/index.js"
+    },
+    "./runtime": {
+      "types": "./lib/runtime.d.ts",
+      "development": "./src/runtime.ts",
+      "import": "./lib/runtime.js"
     }
   },
   "keywords": [
@@ -31,21 +36,22 @@
   },
   "dependencies": {
     "@a2a-js/sdk": "1.0.0-beta.0",
-    "@zhin.js/core": "1.3.4",
-    "@zhin.js/logger": "1.0.74"
+    "@zhin.js/core": "1.4.0",
+    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/logger": "1.0.75"
   },
   "peerDependencies": {
-    "@zhin.js/agent": "1.0.3",
-    "@zhin.js/host-router": "2.0.3",
-    "zhin.js": "4.1.2"
+    "@zhin.js/agent": "1.0.5",
+    "@zhin.js/host-router": "3.0.0",
+    "zhin.js": "5.0.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
     "rimraf": "^6.0.0",
     "typescript": "^6.0.3",
-    "@zhin.js/agent": "1.0.3",
-    "@zhin.js/host-router": "2.0.3",
-    "zhin.js": "4.1.2"
+    "@zhin.js/agent": "1.0.5",
+    "@zhin.js/host-router": "3.0.0",
+    "zhin.js": "5.0.0"
   },
   "files": [
     "src",

package/src/card-builder.ts

@@ -30,13 +30,19 @@ export function buildAgentCardForBinding(
   agentName: string,
   registry: AgentBindingRegistry,
   publicBaseUrl: string,
+  basePath = '/a2a',
 ): AgentCard | null {
   const binding = registry.getBinding(agentName);
   if (!binding) return null;
 
   const nickname = binding.nickname ?? agentName;
-  const jsonRpcUrl = a2aJsonRpcUrl(publicBaseUrl, agentName);
-  const restUrl = a2aRestUrl(publicBaseUrl, agentName);
+  const normalizedBasePath = basePath === '/a2a' ? undefined : basePath;
+  const jsonRpcUrl = normalizedBasePath
+    ? `${publicBaseUrl}${normalizedBasePath}/${encodeURIComponent(agentName)}/jsonrpc`
+    : a2aJsonRpcUrl(publicBaseUrl, agentName);
+  const restUrl = normalizedBasePath
+    ? `${publicBaseUrl}${normalizedBasePath}/${encodeURIComponent(agentName)}/rest`
+    : a2aRestUrl(publicBaseUrl, agentName);
 
   const skills: AgentSkill[] = [
     makeSkill({
@@ -92,7 +98,9 @@ export function buildAgentCardForBinding(
     defaultOutputModes: ['text/plain'],
     skills,
     signatures: [],
-    documentationUrl: a2aAgentCardUrl(publicBaseUrl, agentName),
+    documentationUrl: normalizedBasePath
+      ? `${publicBaseUrl}${normalizedBasePath}/${encodeURIComponent(agentName)}/.well-known/agent-card.json`
+      : a2aAgentCardUrl(publicBaseUrl, agentName),
   };
 }
 

package/src/runtime.ts

@@ -0,0 +1,143 @@
+import {
+  DefaultRequestHandler,
+  InMemoryTaskStore,
+  type A2ARequestHandler,
+} from '@a2a-js/sdk/server';
+import { AGENT_CARD_PATH, type AgentCard } from '@a2a-js/sdk';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { AgentHostPort } from '@zhin.js/agent/runtime';
+import type { ZhinAgent } from '@zhin.js/agent';
+import type { AgentBindingRegistry } from '@zhin.js/agent/config';
+import { buildAgentCardForBinding, listExposableAgentNames } from './card-builder.js';
+import { ZhinA2AExecutor } from './agent-executor.js';
+import { handleAgentCard, handleJsonRpc, handleRest } from './http-handlers.js';
+import { verifyA2aBearer } from './auth.js';
+
+export interface RuntimeA2aConfig {
+  readonly enabled?: boolean;
+  readonly path?: string;
+  readonly token?: string;
+  readonly publicUrl?: string;
+}
+
+export interface InstallRuntimeA2aOptions {
+  readonly http: HttpHost;
+  readonly agentHost: AgentHostPort;
+  readonly config?: RuntimeA2aConfig;
+  readonly fallbackToken?: string;
+  readonly fallbackPublicUrl: string;
+  readonly production?: boolean;
+}
+
+interface AgentStack {
+  readonly card: AgentCard;
+  readonly handler: A2ARequestHandler;
+}
+
+/** Mount Agent Card, JSON-RPC, and HTTP+JSON routes on the Runtime HTTP Host. */
+export function installRuntimeA2a(options: InstallRuntimeA2aOptions): () => void {
+  if (options.config?.enabled === false) return () => undefined;
+  const basePath = normalizePath(options.config?.path ?? '/a2a');
+  const publicBaseUrl = (options.config?.publicUrl ?? options.fallbackPublicUrl).replace(/\/+$/u, '');
+  const token = options.config?.token ?? options.fallbackToken ?? '';
+  if (options.production === true && !token) {
+    throw new Error('A2A requires a2a.token or http.token in production');
+  }
+  const service = options.agentHost.service as {
+    getBindingRegistry(): AgentBindingRegistry;
+  };
+  const agent = options.agentHost.agent as ZhinAgent;
+  const registry = service.getBindingRegistry();
+  const stacks = new Map<string, AgentStack>();
+
+  for (const agentName of listExposableAgentNames(registry)) {
+    const card = buildAgentCardForBinding(agentName, registry, publicBaseUrl, basePath);
+    if (!card) continue;
+    const executor = new ZhinA2AExecutor({
+      agentName,
+      getAgent: () => agent,
+      resolveBinding: () => registry.getBinding(agentName),
+    });
+    stacks.set(agentName, {
+      card,
+      handler: new DefaultRequestHandler(card, new InMemoryTaskStore(), executor),
+    });
+  }
+
+  const unregister = options.http.route('ALL', `${basePath}/*`, async (request, response, url) => {
+    if (token && !verifyA2aBearer(request, token)) {
+      writeJson(response, 401, { error: 'Unauthorized - Bearer token required' });
+      return;
+    }
+    const route = parseRoute(url.pathname, basePath);
+    if (!route) {
+      writeJson(response, 404, { error: 'Not found' });
+      return;
+    }
+    const stack = stacks.get(route.agentName);
+    if (!stack) {
+      writeJson(response, 404, { error: `A2A agent "${route.agentName}" not found` });
+      return;
+    }
+    if (route.kind === 'card') {
+      await handleAgentCard(request, response, stack.handler);
+    } else if (route.kind === 'jsonrpc') {
+      await handleJsonRpc(request, response, stack.handler);
+    } else {
+      await handleRest(request, response, stack.handler, route.restPath);
+    }
+  }, { summary: 'Agent-to-Agent protocol', tags: ['a2a'] });
+
+  return () => {
+    unregister();
+    stacks.clear();
+  };
+}
+
+type ParsedRoute =
+  | { readonly agentName: string; readonly kind: 'card' }
+  | { readonly agentName: string; readonly kind: 'jsonrpc' }
+  | { readonly agentName: string; readonly kind: 'rest'; readonly restPath: string };
+
+function parseRoute(pathname: string, basePath: string): ParsedRoute | null {
+  const prefix = `${basePath}/`;
+  if (!pathname.startsWith(prefix)) return null;
+  const slash = pathname.indexOf('/', prefix.length);
+  if (slash < 0) return null;
+  let agentName: string;
+  try {
+    agentName = decodeURIComponent(pathname.slice(prefix.length, slash));
+  } catch {
+    return null;
+  }
+  if (!agentName) return null;
+  const tail = pathname.slice(slash + 1).replace(/^\/+|\/+$/gu, '');
+  if (tail === `.well-known/${AGENT_CARD_PATH}` || tail === '.well-known/agent-card.json') {
+    return { agentName, kind: 'card' };
+  }
+  if (tail === 'jsonrpc' || tail.startsWith('jsonrpc/')) {
+    return { agentName, kind: 'jsonrpc' };
+  }
+  if (tail === 'rest' || tail.startsWith('rest/')) {
+    return {
+      agentName,
+      kind: 'rest',
+      restPath: tail === 'rest' ? '' : tail.slice('rest/'.length),
+    };
+  }
+  return null;
+}
+
+function writeJson(response: import('node:http').ServerResponse, status: number, body: unknown): void {
+  const payload = JSON.stringify(body);
+  response.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': String(Buffer.byteLength(payload)),
+  });
+  response.end(payload);
+}
+
+function normalizePath(path: string): string {
+  const leading = path.startsWith('/') ? path : `/${path}`;
+  return leading.replace(/\/+$/u, '') || '/a2a';
+}