agent-relay 3.2.3 → 3.2.4

package/packages/sdk/src/communicate/a2a-server.ts

@@ -0,0 +1,277 @@
+/**
+ * A2A-compliant HTTP server that exposes a Relay agent as an A2A endpoint.
+ *
+ * Routes:
+ *   GET  /.well-known/agent.json  -> Agent Card
+ *   POST /                        -> JSON-RPC 2.0 dispatcher
+ */
+
+import { randomUUID } from 'node:crypto';
+import * as http from 'node:http';
+
+import {
+  type A2AAgentCard,
+  type A2AMessage,
+  type A2APart,
+  type A2ASkill,
+  type A2ATask,
+  type A2ATaskStatus,
+  a2aAgentCardToDict,
+  a2aMessageToDict,
+  createA2AAgentCard,
+  createA2ATaskStatus,
+} from './a2a-types.js';
+
+export type A2AMessageHandler = (
+  msg: A2AMessage,
+) => A2AMessage | null | Promise<A2AMessage | null>;
+
+export class A2AServer {
+  readonly agentName: string;
+  readonly port: number;
+  readonly host: string;
+  readonly skills: A2ASkill[];
+  readonly tasks: Map<string, A2ATask> = new Map();
+
+  private _onMessage?: A2AMessageHandler;
+  private _server?: http.Server;
+  private _actualPort?: number;
+
+  constructor(
+    agentName: string,
+    port: number = 5000,
+    host: string = '0.0.0.0',
+    skills: A2ASkill[] = [],
+  ) {
+    this.agentName = agentName;
+    this.port = port;
+    this.host = host;
+    this.skills = skills;
+  }
+
+  get url(): string {
+    const p = this._actualPort ?? this.port;
+    return `http://${this.host}:${p}`;
+  }
+
+  onMessage(callback: A2AMessageHandler): void {
+    this._onMessage = callback;
+  }
+
+  getAgentCard(): A2AAgentCard {
+    return createA2AAgentCard(
+      this.agentName,
+      `Agent Relay agent: ${this.agentName}`,
+      this.url,
+      [...this.skills],
+    );
+  }
+
+  async handleMessageSend(params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const messageData = (params.message ?? {}) as Record<string, unknown>;
+    const rawParts = (messageData.parts ?? []) as Record<string, unknown>[];
+    const parts: A2APart[] = rawParts.map((p) => ({ text: p.text as string | undefined }));
+
+    const incoming: A2AMessage = {
+      role: (messageData.role as 'user' | 'agent') ?? 'user',
+      parts,
+      messageId: (messageData.messageId as string) ?? randomUUID(),
+      contextId: messageData.contextId as string | undefined,
+      taskId: messageData.taskId as string | undefined,
+    };
+
+    // Create or find task
+    const taskId = incoming.taskId ?? randomUUID();
+    const contextId = incoming.contextId ?? randomUUID();
+
+    let task: A2ATask;
+    if (this.tasks.has(taskId)) {
+      task = this.tasks.get(taskId)!;
+      task.messages.push(incoming);
+      task.status = createA2ATaskStatus('working');
+    } else {
+      task = {
+        id: taskId,
+        contextId,
+        status: createA2ATaskStatus('working'),
+        messages: [incoming],
+        artifacts: [],
+      };
+      this.tasks.set(taskId, task);
+    }
+
+    // Invoke callback
+    let responseMsg: A2AMessage | null = null;
+    if (this._onMessage) {
+      const result = this._onMessage(incoming);
+      responseMsg = result instanceof Promise ? await result : result;
+    }
+
+    if (responseMsg) {
+      task.messages.push(responseMsg);
+      task.status = createA2ATaskStatus('completed', responseMsg);
+    } else {
+      task.status = createA2ATaskStatus('completed');
+    }
+
+    return taskToDict(task);
+  }
+
+  async handleTasksGet(taskId: string): Promise<Record<string, unknown>> {
+    const task = this.tasks.get(taskId);
+    if (!task) {
+      throw new Error(`Task not found: ${taskId}`);
+    }
+    return taskToDict(task);
+  }
+
+  async handleTasksCancel(taskId: string): Promise<Record<string, unknown>> {
+    const task = this.tasks.get(taskId);
+    if (!task) {
+      throw new Error(`Task not found: ${taskId}`);
+    }
+    task.status = createA2ATaskStatus('canceled');
+    return taskToDict(task);
+  }
+
+  async start(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const server = http.createServer((req, res) => {
+        void this._handleRequest(req, res);
+      });
+
+      server.on('error', reject);
+
+      server.listen(this.port, this.host, () => {
+        this._server = server;
+        const addr = server.address();
+        if (typeof addr === 'object' && addr) {
+          this._actualPort = addr.port;
+        }
+        resolve();
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (this._server) {
+      await new Promise<void>((resolve, reject) => {
+        this._server!.close((err) => (err ? reject(err) : resolve()));
+      });
+      this._server = undefined;
+      this._actualPort = undefined;
+    }
+  }
+
+  // --- HTTP handlers ---
+
+  private async _handleRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    if (req.method === 'GET' && req.url === '/.well-known/agent.json') {
+      const card = this.getAgentCard();
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(a2aAgentCardToDict(card)));
+      return;
+    }
+
+    if (req.method === 'POST' && (req.url === '/' || req.url === '')) {
+      await this._handleJsonRpc(req, res);
+      return;
+    }
+
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Not found' }));
+  }
+
+  private async _handleJsonRpc(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    let body: Record<string, unknown>;
+    try {
+      const raw = await readBody(req);
+      body = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(
+        JSON.stringify({
+          jsonrpc: '2.0',
+          error: { code: -32700, message: 'Parse error' },
+          id: null,
+        }),
+      );
+      return;
+    }
+
+    const method = (body.method ?? '') as string;
+    const params = (body.params ?? {}) as Record<string, unknown>;
+    const rpcId = body.id ?? null;
+
+    try {
+      let result: Record<string, unknown>;
+
+      if (method === 'message/send') {
+        result = await this.handleMessageSend(params);
+      } else if (method === 'tasks/get') {
+        const id = (params.id ?? params.taskId ?? '') as string;
+        result = await this.handleTasksGet(id);
+      } else if (method === 'tasks/cancel') {
+        const id = (params.id ?? params.taskId ?? '') as string;
+        result = await this.handleTasksCancel(id);
+      } else {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            jsonrpc: '2.0',
+            error: { code: -32601, message: `Method not found: ${method}` },
+            id: rpcId,
+          }),
+        );
+        return;
+      }
+
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ jsonrpc: '2.0', result, id: rpcId }));
+    } catch (err) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(
+        JSON.stringify({
+          jsonrpc: '2.0',
+          error: { code: -32602, message: String(err) },
+          id: rpcId,
+        }),
+      );
+    }
+  }
+}
+
+// --- Helpers ---
+
+function readBody(req: http.IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk: Buffer) => chunks.push(chunk));
+    req.on('end', () => resolve(Buffer.concat(chunks).toString()));
+    req.on('error', reject);
+  });
+}
+
+function taskToDict(task: A2ATask): Record<string, unknown> {
+  const statusDict: Record<string, unknown> = { state: task.status.state };
+  if (task.status.message) {
+    statusDict.message = a2aMessageToDict(task.status.message);
+  }
+
+  const messages = task.messages.map((m) => {
+    const md: Record<string, unknown> = {
+      role: m.role,
+      parts: m.parts.map((p) => ({ text: p.text })),
+    };
+    if (m.messageId) md.messageId = m.messageId;
+    return md;
+  });
+
+  return {
+    id: task.id,
+    contextId: task.contextId,
+    status: statusDict,
+    messages,
+    artifacts: task.artifacts,
+  };
+}

package/packages/sdk/src/communicate/a2a-transport.ts

@@ -0,0 +1,395 @@
+/**
+ * A2A (Agent-to-Agent) protocol transport implementation.
+ *
+ * Client side: sends JSON-RPC 2.0 to external A2A agent endpoints.
+ * Server side: runs a local HTTP server accepting A2A JSON-RPC calls.
+ */
+
+import { randomUUID } from 'node:crypto';
+import * as http from 'node:http';
+
+import type { Message, MessageCallback } from './types.js';
+import {
+  type A2AAgentCard,
+  type A2AConfig,
+  type A2AMessage,
+  type A2ATask,
+  type A2ATaskStatus,
+  type JsonRpcResponse,
+  A2A_TASK_NOT_CANCELABLE,
+  A2A_TASK_NOT_FOUND,
+  JSONRPC_INTERNAL_ERROR,
+  JSONRPC_INVALID_PARAMS,
+  JSONRPC_METHOD_NOT_FOUND,
+  JSONRPC_PARSE_ERROR,
+  a2aAgentCardFromDict,
+  a2aAgentCardToDict,
+  a2aMessageFromDict,
+  a2aMessageGetText,
+  a2aMessageToDict,
+  a2aTaskToDict,
+  createA2AAgentCard,
+  createA2ATaskStatus,
+  makeJsonRpcError,
+  makeJsonRpcRequest,
+  makeJsonRpcResponse,
+} from './a2a-types.js';
+
+export class A2AError extends Error {
+  readonly code: number;
+
+  constructor(code: number, message: string) {
+    super(`A2A error ${code}: ${message}`);
+    this.name = 'A2AError';
+    this.code = code;
+  }
+}
+
+export class A2ATransport {
+  readonly config: A2AConfig;
+
+  agentName?: string;
+  agentCard?: A2AAgentCard;
+  tasks: Map<string, A2ATask> = new Map();
+
+  private _messageCallbacks: MessageCallback[] = [];
+  private _server?: http.Server;
+  private _discoveredCards: Map<string, A2AAgentCard> = new Map();
+  private _closing = false;
+
+  constructor(config: A2AConfig) {
+    this.config = config;
+  }
+
+  // === Transport interface ===
+
+  async register(name: string): Promise<{ name: string; url: string; type: string }> {
+    this.agentName = name;
+    const host = this.config.serverHost ?? '0.0.0.0';
+    const port = this.config.serverPort ?? 5000;
+
+    this.agentCard = createA2AAgentCard(
+      name,
+      this.config.agentDescription ?? `Agent Relay agent: ${name}`,
+      `http://${host}:{PORT}`,
+      this.config.skills ?? [],
+    );
+
+    return new Promise((resolve, reject) => {
+      const server = http.createServer((req, res) => {
+        void this._handleRequest(req, res);
+      });
+
+      server.on('error', reject);
+
+      server.listen(port, host, () => {
+        this._server = server;
+        const addr = server.address();
+        const actualPort = typeof addr === 'object' && addr ? addr.port : port;
+        this.agentCard!.url = `http://${host}:${actualPort}`;
+        resolve({ name, url: this.agentCard!.url, type: 'a2a' });
+      });
+    });
+  }
+
+  async unregister(): Promise<void> {
+    this._closing = true;
+    if (this._server) {
+      await new Promise<void>((resolve, reject) => {
+        this._server!.close((err) => (err ? reject(err) : resolve()));
+      });
+      this._server = undefined;
+    }
+    this._closing = false;
+  }
+
+  async sendDm(target: string, text: string): Promise<Record<string, unknown>> {
+    const card = await this._discoverAgent(target);
+
+    const message: A2AMessage = {
+      role: 'user',
+      parts: [{ text }],
+      messageId: randomUUID(),
+    };
+
+    const rpcRequest = makeJsonRpcRequest('message/send', {
+      message: a2aMessageToDict(message),
+    });
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...this._authHeaders(),
+    };
+
+    const response = await fetch(card.url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(rpcRequest),
+    });
+
+    const body = (await response.json()) as JsonRpcResponse;
+
+    if (body.error) {
+      throw new A2AError(body.error.code, body.error.message);
+    }
+
+    const result = (body.result ?? {}) as Record<string, unknown>;
+    return this._a2aResultToRelay(result, card.name);
+  }
+
+  async listAgents(): Promise<Record<string, unknown>[]> {
+    const agents: Record<string, unknown>[] = [];
+    for (const url of this.config.registry ?? []) {
+      try {
+        const card = await this._discoverAgent(url);
+        agents.push({
+          name: card.name,
+          url: card.url,
+          description: card.description,
+          skills: card.skills.map((s) => ({ id: s.id, name: s.name, description: s.description })),
+        });
+      } catch {
+        continue;
+      }
+    }
+    return agents;
+  }
+
+  onMessage(callback: MessageCallback): void {
+    this._messageCallbacks.push(callback);
+  }
+
+  async connectWs(): Promise<void> {
+    // A2A uses HTTP, not WebSocket. No-op.
+  }
+
+  // === HTTP request handler ===
+
+  private async _handleRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    if (req.method === 'GET' && req.url === '/.well-known/agent.json') {
+      await this._handleAgentCard(res);
+      return;
+    }
+
+    if (req.method === 'POST' && (req.url === '/' || req.url === '')) {
+      await this._handleJsonRpcHttp(req, res);
+      return;
+    }
+
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Not found' }));
+  }
+
+  private async _handleAgentCard(res: http.ServerResponse): Promise<void> {
+    if (!this.agentCard) {
+      res.writeHead(503, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Not registered' }));
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(a2aAgentCardToDict(this.agentCard)));
+  }
+
+  private async _handleJsonRpcHttp(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+  ): Promise<void> {
+    let body: Record<string, unknown>;
+    try {
+      const raw = await this._readBody(req);
+      body = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      const error = makeJsonRpcError(JSONRPC_PARSE_ERROR, 'Parse error', null);
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(error));
+      return;
+    }
+
+    const result = await this._dispatchJsonRpc(body);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(result));
+  }
+
+  private _readBody(req: http.IncomingMessage): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      req.on('data', (chunk: Buffer) => chunks.push(chunk));
+      req.on('end', () => resolve(Buffer.concat(chunks).toString()));
+      req.on('error', reject);
+    });
+  }
+
+  // === JSON-RPC dispatch ===
+
+  private async _dispatchJsonRpc(request: Record<string, unknown>): Promise<JsonRpcResponse> {
+    const rpcId = (request.id ?? null) as string | number | null;
+    const method = (request.method ?? '') as string;
+    const params = (request.params ?? {}) as Record<string, unknown>;
+
+    const handlers: Record<string, (p: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
+      'message/send': (p) => this._handleMessageSend(p),
+      'tasks/get': (p) => this._handleTasksGet(p),
+      'tasks/cancel': (p) => this._handleTasksCancel(p),
+    };
+
+    const handler = handlers[method];
+    if (!handler) {
+      return makeJsonRpcError(JSONRPC_METHOD_NOT_FOUND, `Method not found: ${method}`, rpcId);
+    }
+
+    try {
+      const result = await handler(params);
+      return makeJsonRpcResponse(result, rpcId as string | number);
+    } catch (err) {
+      if (err instanceof A2AError) {
+        return makeJsonRpcError(err.code, err.message, rpcId);
+      }
+      return makeJsonRpcError(JSONRPC_INTERNAL_ERROR, String(err), rpcId);
+    }
+  }
+
+  private async _handleMessageSend(params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const msgData = params.message as Record<string, unknown> | undefined;
+    if (!msgData) {
+      throw new A2AError(JSONRPC_INVALID_PARAMS, "Missing 'message' in params");
+    }
+
+    const a2aMsg = a2aMessageFromDict(msgData);
+    const taskId = a2aMsg.taskId ?? randomUUID();
+    const contextId = a2aMsg.contextId ?? randomUUID();
+
+    let task: A2ATask;
+    if (this.tasks.has(taskId)) {
+      task = this.tasks.get(taskId)!;
+      task.messages.push(a2aMsg);
+      task.status = createA2ATaskStatus('working');
+    } else {
+      task = {
+        id: taskId,
+        contextId,
+        status: createA2ATaskStatus('working'),
+        messages: [a2aMsg],
+        artifacts: [],
+      };
+      this.tasks.set(taskId, task);
+    }
+
+    // Convert to Relay message and invoke callbacks
+    const relayMsg = A2ATransport._a2aToRelayMsg(a2aMsg, 'a2a-client');
+    await this._invokeCallbacks(relayMsg);
+
+    // Mark completed
+    task.status = createA2ATaskStatus('completed');
+
+    return a2aTaskToDict(task);
+  }
+
+  private async _handleTasksGet(params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const taskId = (params.id as string) ?? '';
+    if (!taskId || !this.tasks.has(taskId)) {
+      throw new A2AError(A2A_TASK_NOT_FOUND, `Task not found: ${taskId}`);
+    }
+    return a2aTaskToDict(this.tasks.get(taskId)!);
+  }
+
+  private async _handleTasksCancel(params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const taskId = (params.id as string) ?? '';
+    if (!taskId || !this.tasks.has(taskId)) {
+      throw new A2AError(A2A_TASK_NOT_FOUND, `Task not found: ${taskId}`);
+    }
+
+    const task = this.tasks.get(taskId)!;
+    if (['completed', 'failed', 'canceled'].includes(task.status.state)) {
+      throw new A2AError(
+        A2A_TASK_NOT_CANCELABLE,
+        `Task ${taskId} is already ${task.status.state}`,
+      );
+    }
+
+    task.status = createA2ATaskStatus('canceled');
+    return a2aTaskToDict(task);
+  }
+
+  // === Agent discovery ===
+
+  private async _discoverAgent(url: string): Promise<A2AAgentCard> {
+    const normalizedUrl = url.replace(/\/+$/, '');
+
+    if (this._discoveredCards.has(normalizedUrl)) {
+      return this._discoveredCards.get(normalizedUrl)!;
+    }
+
+    const cardUrl = `${normalizedUrl}/.well-known/agent.json`;
+    const response = await fetch(cardUrl);
+
+    if (!response.ok) {
+      throw new A2AError(-1, `Failed to discover agent at ${cardUrl}: HTTP ${response.status}`);
+    }
+
+    const data = (await response.json()) as Record<string, unknown>;
+    const card = a2aAgentCardFromDict(data);
+    this._discoveredCards.set(normalizedUrl, card);
+    return card;
+  }
+
+  // === Message conversion ===
+
+  static _relayMsgToA2A(text: string, _sender: string): A2AMessage {
+    return {
+      role: 'user',
+      parts: [{ text }],
+      messageId: randomUUID(),
+    };
+  }
+
+  static _a2aToRelayMsg(msg: A2AMessage, sender: string = 'unknown'): Message {
+    const text = a2aMessageGetText(msg);
+    return {
+      sender,
+      text,
+      channel: undefined,
+      threadId: msg.contextId,
+      messageId: msg.messageId,
+    };
+  }
+
+  private _a2aResultToRelay(result: Record<string, unknown>, sender: string): Record<string, unknown> {
+    const messages = (result.messages as Record<string, unknown>[] | undefined) ?? [];
+    let text = '';
+    if (messages.length > 0) {
+      const lastMsg = messages[messages.length - 1];
+      const parts = (lastMsg.parts as Record<string, unknown>[] | undefined) ?? [];
+      text = parts
+        .filter((p) => p.text)
+        .map((p) => p.text as string)
+        .join(' ');
+    }
+
+    return {
+      sender,
+      text,
+      task_id: result.id,
+      status: (result.status as Record<string, unknown> | undefined)?.state,
+    };
+  }
+
+  // === Internal helpers ===
+
+  private async _invokeCallbacks(msg: Message): Promise<void> {
+    for (const cb of this._messageCallbacks) {
+      await cb(msg);
+    }
+  }
+
+  private _authHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {};
+    if (this.config.authToken) {
+      if (this.config.authScheme === 'api_key') {
+        headers['X-API-Key'] = this.config.authToken;
+      } else {
+        headers['Authorization'] = `Bearer ${this.config.authToken}`;
+      }
+    }
+    return headers;
+  }
+}