@zhin.js/a2a 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @zhin.js/a2a
+
+## 1.0.0
+
+### Major Changes
+
+- Initial A2A v1.0 server plugin (`@a2a-js/sdk@1.0.0-beta.0`)
+- Multi Agent Card per `ai.agents[]`
+- Replaces MCP Agent Mesh v1 inbound delegation

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @zhin.js/a2a
+
+A2A v1.0 server plugin for Zhin.js — exposes one [Agent Card](https://a2a-protocol.org/v1.0.0/specification) per `ai.agents[]` entry.
+
+## Routes
+
+| Method | Path |
+|--------|------|
+| GET | `/a2a/{agentName}/.well-known/agent-card.json` |
+| POST | `/a2a/{agentName}/jsonrpc` |
+| * | `/a2a/{agentName}/rest/*` |
+
+## Setup
+
+```yaml
+plugins:
+  - "@zhin.js/a2a"
+
+http:
+  token: ${HTTP_TOKEN}
+  publicUrl: https://bot.example.com   # recommended behind reverse proxy
+
+ai:
+  agents:
+    zhin:
+      provider: ollama
+      model: qwen3:8b
+```
+
+Bearer `http.token` is required for inbound A2A calls (except when token is empty in dev).
+
+## Related
+
+- [Agent Mesh](../../../docs/advanced/agent-mesh.md)
+- [ADR 0035](../../../docs/adr/0035-a2a-agent-mesh.md)

package/lib/a2a-parts.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A2A v1.0 proto-shaped Part/Message helpers.
+ */
+import type { Part } from '@a2a-js/sdk';
+export declare function textPart(text: string, mediaType?: string): Part;
+export declare function dataPart(data: unknown): Part;
+export declare function partsToPromptText(parts: Part[]): string;
+export declare function agentTextMessage(messageId: string, contextId: string, text: string, taskId?: string): import('@a2a-js/sdk').Message;
+export declare function userTextMessage(messageId: string, contextId: string, parts: Part[], metadata?: Record<string, unknown>): import('@a2a-js/sdk').Message;
+//# sourceMappingURL=a2a-parts.d.ts.map

package/lib/a2a-parts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-parts.d.ts","sourceRoot":"","sources":["../src/a2a-parts.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAGxC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAe,GAAG,IAAI,CAOrE;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAO5C;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAYvD;AAED,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,SAAK,GACV,OAAO,aAAa,EAAE,OAAO,CAW/B;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,IAAI,EAAE,EACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,aAAa,EAAE,OAAO,CAW/B"}

package/lib/a2a-parts.js

@@ -0,0 +1,57 @@
+import { Role } from '@a2a-js/sdk';
+export function textPart(text, mediaType = 'text/plain') {
+    return {
+        content: { $case: 'text', value: text },
+        metadata: undefined,
+        filename: '',
+        mediaType,
+    };
+}
+export function dataPart(data) {
+    return {
+        content: { $case: 'data', value: data },
+        metadata: undefined,
+        filename: '',
+        mediaType: 'application/json',
+    };
+}
+export function partsToPromptText(parts) {
+    const lines = [];
+    for (const part of parts) {
+        if (part.content?.$case === 'text') {
+            lines.push(part.content.value);
+        }
+        else if (part.content?.$case === 'data') {
+            lines.push('```json', JSON.stringify(part.content.value, null, 2), '```');
+        }
+        else if (part.content?.$case === 'url') {
+            lines.push(`[file: ${part.content.value}]`);
+        }
+    }
+    return lines.join('\n').trim();
+}
+export function agentTextMessage(messageId, contextId, text, taskId = '') {
+    return {
+        messageId,
+        contextId,
+        taskId,
+        role: Role.ROLE_AGENT,
+        parts: [textPart(text)],
+        metadata: undefined,
+        extensions: [],
+        referenceTaskIds: [],
+    };
+}
+export function userTextMessage(messageId, contextId, parts, metadata) {
+    return {
+        messageId,
+        contextId,
+        taskId: '',
+        role: Role.ROLE_USER,
+        parts,
+        metadata,
+        extensions: [],
+        referenceTaskIds: [],
+    };
+}
+//# sourceMappingURL=a2a-parts.js.map

package/lib/a2a-parts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-parts.js","sourceRoot":"","sources":["../src/a2a-parts.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,SAAS,GAAG,YAAY;IAC7D,OAAO;QACL,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE;QACvC,QAAQ,EAAE,SAAS;QACnB,QAAQ,EAAE,EAAE;QACZ,SAAS;KACV,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAa;IACpC,OAAO;QACL,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE;QACvC,QAAQ,EAAE,SAAS;QACnB,QAAQ,EAAE,EAAE;QACZ,SAAS,EAAE,kBAAkB;KAC9B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,KAAK,MAAM,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;aAAM,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1C,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5E,CAAC;aAAM,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,KAAK,KAAK,EAAE,CAAC;YACzC,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,SAAiB,EACjB,IAAY,EACZ,MAAM,GAAG,EAAE;IAEX,OAAO;QACL,SAAS;QACT,SAAS;QACT,MAAM;QACN,IAAI,EAAE,IAAI,CAAC,UAAU;QACrB,KAAK,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACvB,QAAQ,EAAE,SAAS;QACnB,UAAU,EAAE,EAAE;QACd,gBAAgB,EAAE,EAAE;KACrB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,SAAiB,EACjB,SAAiB,EACjB,KAAa,EACb,QAAkC;IAElC,OAAO;QACL,SAAS;QACT,SAAS;QACT,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,IAAI,CAAC,SAAS;QACpB,KAAK;QACL,QAAQ;QACR,UAAU,EAAE,EAAE;QACd,gBAAgB,EAAE,EAAE;KACrB,CAAC;AACJ,CAAC"}

package/lib/agent-executor.d.ts

@@ -0,0 +1,16 @@
+import { type AgentExecutor, type ExecutionEventBus, type RequestContext } from '@a2a-js/sdk/server';
+import type { ZhinAgent } from '@zhin.js/agent';
+import type { ResolvedAgentBinding } from '@zhin.js/agent/config';
+export interface ZhinA2AExecutorOptions {
+    agentName: string;
+    getAgent: () => ZhinAgent | null;
+    resolveBinding: () => ResolvedAgentBinding | null;
+}
+export declare class ZhinA2AExecutor implements AgentExecutor {
+    private readonly options;
+    private readonly running;
+    constructor(options: ZhinA2AExecutorOptions);
+    execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void>;
+    cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void>;
+}
+//# sourceMappingURL=agent-executor.d.ts.map

package/lib/agent-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-executor.d.ts","sourceRoot":"","sources":["../src/agent-executor.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGlE,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,SAAS,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,MAAM,oBAAoB,GAAG,IAAI,CAAC;CACnD;AAwBD,qBAAa,eAAgB,YAAW,aAAa;IAGvC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEhB,OAAO,EAAE,sBAAsB;IAEtD,OAAO,CAAC,cAAc,EAAE,cAAc,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IA+FnF,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAc7E"}

package/lib/agent-executor.js

@@ -0,0 +1,125 @@
+/**
+ * ZhinA2AExecutor — runs inbound A2A tasks via bound ZhinAgent.
+ */
+import { randomUUID } from 'node:crypto';
+import { TaskState } from '@a2a-js/sdk';
+import { AgentEvent, } from '@a2a-js/sdk/server';
+import { createSyntheticMessage } from '@zhin.js/core';
+import { agentTextMessage, partsToPromptText, textPart } from './a2a-parts.js';
+function outputElementsToText(elements) {
+    return elements
+        .map((el) => (el.type === 'text' ? el.content || '' : ''))
+        .join('\n')
+        .trim();
+}
+function initialTask(requestContext, agentName) {
+    return {
+        id: requestContext.taskId,
+        contextId: requestContext.contextId,
+        status: {
+            state: TaskState.TASK_STATE_WORKING,
+            message: undefined,
+            timestamp: new Date().toISOString(),
+        },
+        artifacts: [],
+        history: [requestContext.userMessage],
+        metadata: { zhinAgent: agentName },
+    };
+}
+export class ZhinA2AExecutor {
+    options;
+    running = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    async execute(requestContext, eventBus) {
+        const agent = this.options.getAgent();
+        const binding = this.options.resolveBinding();
+        if (!agent || !binding) {
+            const failed = {
+                ...initialTask(requestContext, this.options.agentName),
+                status: {
+                    state: TaskState.TASK_STATE_FAILED,
+                    message: agentTextMessage(randomUUID(), requestContext.contextId, `Agent "${this.options.agentName}" not ready`, requestContext.taskId),
+                    timestamp: new Date().toISOString(),
+                },
+            };
+            eventBus.publish(AgentEvent.task(failed));
+            eventBus.finished();
+            return;
+        }
+        const task = initialTask(requestContext, this.options.agentName);
+        eventBus.publish(AgentEvent.task(task));
+        this.running.add(requestContext.taskId);
+        const prompt = partsToPromptText(requestContext.userMessage.parts);
+        agent.configure({ activeBinding: binding });
+        const commMessage = createSyntheticMessage({
+            adapter: 'a2a',
+            endpoint: this.options.agentName,
+            sender: { id: 'a2a-client', isMaster: true },
+            channel: { type: 'private', id: requestContext.contextId },
+        });
+        try {
+            const output = await agent.prompt(prompt, commMessage);
+            const resultText = outputElementsToText(output)
+                || '（A2A 任务已完成，Agent 未返回文本）';
+            eventBus.publish(AgentEvent.artifactUpdate({
+                taskId: task.id,
+                contextId: task.contextId,
+                artifact: {
+                    artifactId: randomUUID(),
+                    name: 'result',
+                    description: '',
+                    parts: [textPart(resultText)],
+                    metadata: undefined,
+                    extensions: [],
+                },
+                append: false,
+                lastChunk: true,
+                metadata: undefined,
+            }));
+            eventBus.publish(AgentEvent.statusUpdate({
+                taskId: task.id,
+                contextId: task.contextId,
+                status: {
+                    state: TaskState.TASK_STATE_COMPLETED,
+                    message: agentTextMessage(randomUUID(), requestContext.contextId, resultText, task.id),
+                    timestamp: new Date().toISOString(),
+                },
+                metadata: undefined,
+            }));
+        }
+        catch (err) {
+            const errorText = err instanceof Error ? err.message : String(err);
+            eventBus.publish(AgentEvent.statusUpdate({
+                taskId: task.id,
+                contextId: task.contextId,
+                status: {
+                    state: TaskState.TASK_STATE_FAILED,
+                    message: agentTextMessage(randomUUID(), requestContext.contextId, errorText, task.id),
+                    timestamp: new Date().toISOString(),
+                },
+                metadata: undefined,
+            }));
+        }
+        finally {
+            this.running.delete(requestContext.taskId);
+            eventBus.finished();
+        }
+    }
+    async cancelTask(taskId, eventBus) {
+        this.running.delete(taskId);
+        eventBus.publish(AgentEvent.statusUpdate({
+            taskId,
+            contextId: '',
+            status: {
+                state: TaskState.TASK_STATE_CANCELED,
+                message: undefined,
+                timestamp: new Date().toISOString(),
+            },
+            metadata: undefined,
+        }));
+        eventBus.finished();
+    }
+}
+//# sourceMappingURL=agent-executor.js.map

package/lib/agent-executor.js.map

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

package/lib/auth.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Bearer auth for A2A HTTP endpoints (reuses MCP mesh-auth timing-safe compare).
+ */
+import type { IncomingMessage } from 'node:http';
+export declare function timingSafeEqualString(a: string, b: string): boolean;
+export declare function extractBearerToken(req: IncomingMessage): string;
+export declare function verifyA2aBearer(req: IncomingMessage, expectedToken: string): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/lib/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAGjD,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAMnE;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAG/D;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAGpF"}

package/lib/auth.js

@@ -0,0 +1,20 @@
+import { timingSafeEqual } from 'node:crypto';
+export function timingSafeEqualString(a, b) {
+    if (!a || !b)
+        return false;
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+export function extractBearerToken(req) {
+    const auth = req.headers.authorization ?? '';
+    return auth.startsWith('Bearer ') ? auth.slice(7) : '';
+}
+export function verifyA2aBearer(req, expectedToken) {
+    if (!expectedToken)
+        return false;
+    return timingSafeEqualString(expectedToken, extractBearerToken(req));
+}
+//# sourceMappingURL=auth.js.map

package/lib/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,UAAU,qBAAqB,CAAC,CAAS,EAAE,CAAS;IACxD,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC9C,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAoB;IACrD,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC;IAC7C,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAoB,EAAE,aAAqB;IACzE,IAAI,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC;IACjC,OAAO,qBAAqB,CAAC,aAAa,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;AACvE,CAAC"}

package/lib/card-builder.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Build A2A AgentCard per ai.agents binding.
+ */
+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 listExposableAgentNames(registry: AgentBindingRegistry): string[];
+//# sourceMappingURL=card-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"card-builder.d.ts","sourceRoot":"","sources":["../src/card-builder.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAEzD,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"}

package/lib/card-builder.js

@@ -0,0 +1,87 @@
+import { A2A_PROTOCOL_VERSION } from '@a2a-js/sdk';
+import { a2aAgentCardUrl, a2aJsonRpcUrl, a2aRestUrl } from './config.js';
+function makeSkill(partial) {
+    return {
+        ...partial,
+        tags: partial.tags ?? [],
+        examples: [],
+        inputModes: ['text/plain'],
+        outputModes: ['text/plain'],
+        securityRequirements: [{ schemes: { bearer: { list: [] } } }],
+    };
+}
+const DEFAULT_SKILLS = [
+    makeSkill({
+        id: 'delegate',
+        name: 'Delegate Task',
+        description: 'Accept structured task delegation via A2A Send Message',
+        tags: ['orchestration', 'delegate'],
+    }),
+];
+export function buildAgentCardForBinding(agentName, registry, publicBaseUrl) {
+    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 skills = [
+        makeSkill({
+            id: agentName,
+            name: nickname,
+            description: `Zhin agent "${agentName}" (${binding.providerAlias}/${binding.model})`,
+            tags: ['zhin', agentName],
+        }),
+        ...DEFAULT_SKILLS,
+    ];
+    return {
+        name: nickname,
+        description: `Zhin.js A2A agent "${agentName}" — provider ${binding.providerAlias}, model ${binding.model}`,
+        version: '1.0.0',
+        supportedInterfaces: [
+            {
+                url: jsonRpcUrl,
+                protocolBinding: 'JSONRPC',
+                protocolVersion: A2A_PROTOCOL_VERSION,
+                tenant: '',
+            },
+            {
+                url: restUrl,
+                protocolBinding: 'HTTP+JSON',
+                protocolVersion: A2A_PROTOCOL_VERSION,
+                tenant: '',
+            },
+        ],
+        provider: {
+            organization: 'Zhin.js',
+            url: 'https://github.com/zhinjs/zhin',
+        },
+        capabilities: {
+            streaming: true,
+            pushNotifications: false,
+            extensions: [],
+        },
+        securitySchemes: {
+            bearer: {
+                scheme: {
+                    $case: 'httpAuthSecurityScheme',
+                    value: {
+                        description: 'Bearer token (http.token)',
+                        scheme: 'Bearer',
+                        bearerFormat: '',
+                    },
+                },
+            },
+        },
+        securityRequirements: [{ schemes: { bearer: { list: [] } } }],
+        defaultInputModes: ['text/plain', 'application/json'],
+        defaultOutputModes: ['text/plain'],
+        skills,
+        signatures: [],
+        documentationUrl: a2aAgentCardUrl(publicBaseUrl, agentName),
+    };
+}
+export function listExposableAgentNames(registry) {
+    return registry.listAgentNames();
+}
+//# sourceMappingURL=card-builder.js.map

package/lib/card-builder.js.map

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

package/lib/config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Build public base URL for Agent Card interfaces.
+ */
+export declare function resolvePublicBaseUrl(config: {
+    http?: {
+        host?: string;
+        port?: number;
+        publicUrl?: string;
+    };
+}): string;
+export declare function a2aAgentBasePath(agentName: string): string;
+export declare function a2aJsonRpcUrl(publicBase: string, agentName: string): string;
+export declare function a2aRestUrl(publicBase: string, agentName: string): string;
+export declare function a2aAgentCardUrl(publicBase: string, agentName: string): string;
+//# sourceMappingURL=config.d.ts.map

package/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D,GAAG,MAAM,CAST;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7E"}

package/lib/config.js

@@ -0,0 +1,26 @@
+/**
+ * Build public base URL for Agent Card interfaces.
+ */
+export function resolvePublicBaseUrl(config) {
+    const http = config.http ?? {};
+    if (http.publicUrl?.trim()) {
+        return http.publicUrl.trim().replace(/\/$/, '');
+    }
+    const host = http.host?.trim() || '127.0.0.1';
+    const port = http.port ?? 8086;
+    const hostname = host === '0.0.0.0' ? '127.0.0.1' : host;
+    return `http://${hostname}:${port}`;
+}
+export function a2aAgentBasePath(agentName) {
+    return `/a2a/${encodeURIComponent(agentName)}`;
+}
+export function a2aJsonRpcUrl(publicBase, agentName) {
+    return `${publicBase}${a2aAgentBasePath(agentName)}/jsonrpc`;
+}
+export function a2aRestUrl(publicBase, agentName) {
+    return `${publicBase}${a2aAgentBasePath(agentName)}/rest`;
+}
+export function a2aAgentCardUrl(publicBase, agentName) {
+    return `${publicBase}${a2aAgentBasePath(agentName)}/.well-known/agent-card.json`;
+}
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAEpC;IACC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;IAC/B,IAAI,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,WAAW,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;IAC/B,MAAM,QAAQ,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;IACzD,OAAO,UAAU,QAAQ,IAAI,IAAI,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,OAAO,QAAQ,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,UAAkB,EAAE,SAAiB;IACjE,OAAO,GAAG,UAAU,GAAG,gBAAgB,CAAC,SAAS,CAAC,UAAU,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,UAAkB,EAAE,SAAiB;IAC9D,OAAO,GAAG,UAAU,GAAG,gBAAgB,CAAC,SAAS,CAAC,OAAO,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,UAAkB,EAAE,SAAiB;IACnE,OAAO,GAAG,UAAU,GAAG,gBAAgB,CAAC,SAAS,CAAC,8BAA8B,CAAC;AACnF,CAAC"}

package/lib/http-handlers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * HTTP handlers for A2A JSON-RPC, REST, and Agent Card (Node http — no Express).
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { A2ARequestHandler } from '@a2a-js/sdk/server';
+export declare function handleAgentCard(req: IncomingMessage, res: ServerResponse, requestHandler: A2ARequestHandler): Promise<void>;
+export declare function handleJsonRpc(req: IncomingMessage, res: ServerResponse, requestHandler: A2ARequestHandler, preParsedBody?: unknown): Promise<void>;
+export declare function handleRest(req: IncomingMessage, res: ServerResponse, requestHandler: A2ARequestHandler, subPath: string, preParsedBody?: unknown): Promise<void>;
+export declare function handleRestStreamError(res: ServerResponse, err: unknown, requestId: unknown): Promise<void>;
+//# sourceMappingURL=http-handlers.d.ts.map

package/lib/http-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-handlers.d.ts","sourceRoot":"","sources":["../src/http-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAcjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AA+C5D,wBAAsB,eAAe,CACnC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,cAAc,EAAE,iBAAiB,GAChC,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,cAAc,EAAE,iBAAiB,EACjC,aAAa,CAAC,EAAE,OAAO,GACtB,OAAO,CAAC,IAAI,CAAC,CAmDf;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,cAAc,EAAE,iBAAiB,EACjC,OAAO,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,OAAO,GACtB,OAAO,CAAC,IAAI,CAAC,CAiEf;AAED,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,IAAI,CAAC,CAWf"}