@zhin.js/a2a 1.0.0

package/src/agent-executor.ts

@@ -0,0 +1,160 @@
+/**
+ * ZhinA2AExecutor — runs inbound A2A tasks via bound ZhinAgent.
+ */
+import { randomUUID } from 'node:crypto';
+import type { Task } from '@a2a-js/sdk';
+import { TaskState } from '@a2a-js/sdk';
+import {
+  AgentEvent,
+  type AgentExecutor,
+  type ExecutionEventBus,
+  type RequestContext,
+} from '@a2a-js/sdk/server';
+import { createSyntheticMessage } from '@zhin.js/core';
+import type { ZhinAgent } from '@zhin.js/agent';
+import type { ResolvedAgentBinding } from '@zhin.js/agent/config';
+import { agentTextMessage, partsToPromptText, textPart } from './a2a-parts.js';
+
+export interface ZhinA2AExecutorOptions {
+  agentName: string;
+  getAgent: () => ZhinAgent | null;
+  resolveBinding: () => ResolvedAgentBinding | null;
+}
+
+function outputElementsToText(elements: Array<{ type: string; content?: string }>): string {
+  return elements
+    .map((el) => (el.type === 'text' ? el.content || '' : ''))
+    .join('\n')
+    .trim();
+}
+
+function initialTask(requestContext: RequestContext, agentName: string): Task {
+  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 implements AgentExecutor {
+  private readonly running = new Set<string>();
+
+  constructor(private readonly options: ZhinA2AExecutorOptions) {}
+
+  async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
+    const agent = this.options.getAgent();
+    const binding = this.options.resolveBinding();
+    if (!agent || !binding) {
+      const failed: Task = {
+        ...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 as Array<{ type: string; content?: string }>)
+        || '（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: string, eventBus: ExecutionEventBus): Promise<void> {
+    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();
+  }
+}

package/src/auth.ts

@@ -0,0 +1,23 @@
+/**
+ * Bearer auth for A2A HTTP endpoints (reuses MCP mesh-auth timing-safe compare).
+ */
+import type { IncomingMessage } from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+
+export function timingSafeEqualString(a: string, b: string): boolean {
+  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: IncomingMessage): string {
+  const auth = req.headers.authorization ?? '';
+  return auth.startsWith('Bearer ') ? auth.slice(7) : '';
+}
+
+export function verifyA2aBearer(req: IncomingMessage, expectedToken: string): boolean {
+  if (!expectedToken) return false;
+  return timingSafeEqualString(expectedToken, extractBearerToken(req));
+}

package/src/card-builder.ts

@@ -0,0 +1,101 @@
+/**
+ * Build A2A AgentCard per ai.agents binding.
+ */
+import type { AgentCard, AgentSkill } from '@a2a-js/sdk';
+import { A2A_PROTOCOL_VERSION } from '@a2a-js/sdk';
+import type { AgentBindingRegistry } from '@zhin.js/agent/config';
+import { a2aAgentCardUrl, a2aJsonRpcUrl, a2aRestUrl } from './config.js';
+
+function makeSkill(partial: Pick<AgentSkill, 'id' | 'name' | 'description'> & { tags?: string[] }): AgentSkill {
+  return {
+    ...partial,
+    tags: partial.tags ?? [],
+    examples: [],
+    inputModes: ['text/plain'],
+    outputModes: ['text/plain'],
+    securityRequirements: [{ schemes: { bearer: { list: [] } } }],
+  };
+}
+
+const DEFAULT_SKILLS: AgentSkill[] = [
+  makeSkill({
+    id: 'delegate',
+    name: 'Delegate Task',
+    description: 'Accept structured task delegation via A2A Send Message',
+    tags: ['orchestration', 'delegate'],
+  }),
+];
+
+export function buildAgentCardForBinding(
+  agentName: string,
+  registry: AgentBindingRegistry,
+  publicBaseUrl: string,
+): 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 skills: AgentSkill[] = [
+    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: AgentBindingRegistry): string[] {
+  return registry.listAgentNames();
+}

package/src/config.ts

@@ -0,0 +1,31 @@
+/**
+ * Build public base URL for Agent Card interfaces.
+ */
+export function resolvePublicBaseUrl(config: {
+  http?: { host?: string; port?: number; publicUrl?: string };
+}): string {
+  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: string): string {
+  return `/a2a/${encodeURIComponent(agentName)}`;
+}
+
+export function a2aJsonRpcUrl(publicBase: string, agentName: string): string {
+  return `${publicBase}${a2aAgentBasePath(agentName)}/jsonrpc`;
+}
+
+export function a2aRestUrl(publicBase: string, agentName: string): string {
+  return `${publicBase}${a2aAgentBasePath(agentName)}/rest`;
+}
+
+export function a2aAgentCardUrl(publicBase: string, agentName: string): string {
+  return `${publicBase}${a2aAgentBasePath(agentName)}/.well-known/agent-card.json`;
+}

package/src/http-handlers.ts

@@ -0,0 +1,237 @@
+/**
+ * HTTP handlers for A2A JSON-RPC, REST, and Agent Card (Node http — no Express).
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { createHash } from 'node:crypto';
+import {
+  A2A_CONTENT_TYPE,
+  A2A_VERSION_HEADER,
+  HTTP_EXTENSION_HEADER,
+} from '@a2a-js/sdk';
+import {
+  JsonRpcTransportHandler,
+  ServerCallContext,
+  UnauthenticatedUser,
+  validateVersion,
+} from '@a2a-js/sdk/server';
+import { Extensions } from '@a2a-js/sdk';
+import type { A2ARequestHandler } from '@a2a-js/sdk/server';
+import { RestTransportHandler } from './rest-transport-handler.js';
+
+const SSE_HEADERS: Record<string, string> = {
+  'Content-Type': 'text/event-stream',
+  'Cache-Control': 'no-cache',
+  Connection: 'keep-alive',
+};
+
+function formatSSEEvent(data: unknown): string {
+  return `data: ${JSON.stringify(data)}\n\n`;
+}
+
+function formatSSEErrorEvent(data: unknown): string {
+  return `event: error\ndata: ${JSON.stringify(data)}\n\n`;
+}
+
+async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  }
+  const raw = Buffer.concat(chunks).toString('utf8');
+  if (!raw.trim()) return {};
+  return JSON.parse(raw) as unknown;
+}
+
+function buildServerContext(req: IncomingMessage): ServerCallContext {
+  return new ServerCallContext({
+    requestedExtensions: Extensions.parseServiceParameter(
+      req.headers[HTTP_EXTENSION_HEADER.toLowerCase()] as string | undefined,
+    ),
+    user: new UnauthenticatedUser(),
+    requestedVersion: req.headers[A2A_VERSION_HEADER.toLowerCase()] as string | undefined,
+  });
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown, extraHeaders?: Record<string, string>): void {
+  res.writeHead(status, { 'Content-Type': 'application/json', ...extraHeaders });
+  res.end(JSON.stringify(body));
+}
+
+function computeETag(json: string): string {
+  const hash = createHash('sha256').update(json).digest('hex').slice(0, 16);
+  return `W/"${hash}"`;
+}
+
+export async function handleAgentCard(
+  req: IncomingMessage,
+  res: ServerResponse,
+  requestHandler: A2ARequestHandler,
+): Promise<void> {
+  if (req.method !== 'GET') {
+    sendJson(res, 405, { error: 'Method not allowed' });
+    return;
+  }
+  try {
+    const agentCard = await requestHandler.getAgentCard();
+    const body = JSON.stringify(agentCard);
+    const etag = computeETag(body);
+    res.setHeader('ETag', etag);
+    res.setHeader('Cache-Control', 'public, max-age=3600');
+    if (req.headers['if-none-match'] === etag) {
+      res.writeHead(304);
+      res.end();
+      return;
+    }
+    sendJson(res, 200, agentCard);
+  } catch (err) {
+    sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+export async function handleJsonRpc(
+  req: IncomingMessage,
+  res: ServerResponse,
+  requestHandler: A2ARequestHandler,
+  preParsedBody?: unknown,
+): Promise<void> {
+  if (req.method !== 'POST') {
+    sendJson(res, 405, { error: 'Method not allowed', Allow: 'POST' });
+    return;
+  }
+
+  const transport = new JsonRpcTransportHandler(requestHandler);
+  try {
+    const body = preParsedBody !== undefined ? preParsedBody : await readJsonBody(req);
+    const context = buildServerContext(req);
+    const agentCard = await requestHandler.getAgentCard();
+    validateVersion(context.requestedVersion, agentCard, 'JSONRPC');
+
+    const rpcResponseOrStream = await transport.handle(
+      body as string | Record<string, unknown>,
+      context,
+    );
+
+    if (context.activatedExtensions) {
+      res.setHeader(HTTP_EXTENSION_HEADER, Array.from(context.activatedExtensions).join(', '));
+    }
+
+    if (rpcResponseOrStream && typeof (rpcResponseOrStream as AsyncIterable<unknown>)[Symbol.asyncIterator] === 'function') {
+      const stream = rpcResponseOrStream as AsyncGenerator<unknown, void, undefined>;
+      const iterator = stream[Symbol.asyncIterator]();
+      let firstResult = await iterator.next();
+
+      for (const [key, value] of Object.entries(SSE_HEADERS)) {
+        res.setHeader(key, value);
+      }
+      if (!firstResult.done) {
+        res.write(formatSSEEvent(firstResult.value));
+      }
+      for (;;) {
+        const next = await iterator.next();
+        if (next.done) break;
+        res.write(formatSSEEvent(next.value));
+      }
+      if (!res.writableEnded) res.end();
+      return;
+    }
+
+    sendJson(res, 200, rpcResponseOrStream);
+  } catch (err) {
+    const errorResponse = {
+      jsonrpc: '2.0',
+      id: null,
+      error: JsonRpcTransportHandler.mapToJSONRPCError(err),
+    };
+    sendJson(res, 200, errorResponse);
+  }
+}
+
+export async function handleRest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  requestHandler: A2ARequestHandler,
+  subPath: string,
+  preParsedBody?: unknown,
+): Promise<void> {
+  const transport = new RestTransportHandler(requestHandler);
+  const context = buildServerContext(req);
+  const method = req.method ?? 'GET';
+  const path = subPath.replace(/^\//, '');
+
+  try {
+    const agentCard = await requestHandler.getAgentCard();
+    validateVersion(context.requestedVersion, agentCard, 'HTTP+JSON');
+
+    if (method === 'GET' && (path === '' || path === 'v1/card')) {
+      sendJson(res, 200, await transport.getAgentCard(), { 'Content-Type': A2A_CONTENT_TYPE });
+      return;
+    }
+
+    if (method === 'POST' && path === 'v1/message:send') {
+      const params = preParsedBody !== undefined ? preParsedBody : await readJsonBody(req);
+      const result = await transport.sendMessage(params as never, context);
+      sendJson(res, 200, result, { 'Content-Type': A2A_CONTENT_TYPE });
+      return;
+    }
+
+    if (method === 'POST' && path === 'v1/message:stream') {
+      const params = preParsedBody !== undefined ? preParsedBody : await readJsonBody(req);
+      const stream = await transport.sendMessageStream(params as never, context);
+      for (const [key, value] of Object.entries(SSE_HEADERS)) {
+        res.setHeader(key, value);
+      }
+      for await (const event of stream) {
+        res.write(formatSSEEvent(event));
+      }
+      if (!res.writableEnded) res.end();
+      return;
+    }
+
+    const taskGet = path.match(/^v1\/tasks\/([^/]+)$/);
+    if (method === 'GET' && taskGet) {
+      const historyLength = req.url?.includes('historyLength=')
+        ? new URL(req.url, 'http://localhost').searchParams.get('historyLength') ?? undefined
+        : undefined;
+      const result = await transport.getTask(taskGet[1]!, context, historyLength ?? undefined);
+      sendJson(res, 200, result, { 'Content-Type': A2A_CONTENT_TYPE });
+      return;
+    }
+
+    const taskCancel = path.match(/^v1\/tasks\/([^/]+):cancel$/);
+    if (method === 'POST' && taskCancel) {
+      const result = await transport.cancelTask(taskCancel[1]!, context);
+      sendJson(res, 200, result, { 'Content-Type': A2A_CONTENT_TYPE });
+      return;
+    }
+
+    if (method === 'GET' && path === 'v1/tasks') {
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      const query: Record<string, string | undefined> = {};
+      url.searchParams.forEach((v, k) => { query[k] = v; });
+      const result = await transport.listTasks(query, context);
+      sendJson(res, 200, result, { 'Content-Type': A2A_CONTENT_TYPE });
+      return;
+    }
+
+    sendJson(res, 404, { error: 'Not found' });
+  } catch (err) {
+    sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+export async function handleRestStreamError(
+  res: ServerResponse,
+  err: unknown,
+  requestId: unknown,
+): Promise<void> {
+  if (!res.headersSent) {
+    sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+    return;
+  }
+  res.write(formatSSEErrorEvent({
+    jsonrpc: '2.0',
+    id: requestId ?? null,
+    error: JsonRpcTransportHandler.mapToJSONRPCError(err),
+  }));
+  if (!res.writableEnded) res.end();
+}