@galdor/a2a 0.3.0

package/src/server.ts

@@ -0,0 +1,408 @@
+/**
+ * The A2A HTTP surface as a Bun.serve-compatible fetch handler.
+ *
+ * Two routes are served:
+ *   - GET  /.well-known/agent.json  → the Agent Card
+ *   - POST <any other path>         → JSON-RPC (tasks/send, tasks/get)
+ *
+ * Tasks live in an in-memory store keyed by id. Sends targeting the same id are
+ * serialized through a per-entry promise chain, while the task handler itself
+ * runs without holding any data lock — so a concurrent `tasks/get` observes the
+ * "working" state mid-flight. The single-threaded event loop keeps each
+ * synchronous section atomic.
+ */
+
+import {
+  AGENT_CARD_PATH,
+  agentText,
+  appendMessage,
+  ERR_INTERNAL_ERROR,
+  ERR_INVALID_PARAMS,
+  ERR_INVALID_REQUEST,
+  ERR_INVALID_TASK_STATE,
+  ERR_METHOD_NOT_FOUND,
+  ERR_PARSE_ERROR,
+  ERR_TASK_NOT_FOUND,
+  isTerminalState,
+  METHOD_TASKS_GET,
+  METHOD_TASKS_SEND,
+} from "./types.ts";
+import type {
+  AgentCard,
+  RPCErrorObject,
+  RPCId,
+  RPCRequest,
+  RPCResponse,
+  Task,
+  TaskMessage,
+  TasksGetParams,
+  TasksSendParams,
+} from "./types.ts";
+
+/**
+ * Processes a single task. The handler receives the task with the user's
+ * incoming message already appended and is expected to mutate it in place:
+ * append agent turns, set artifacts, and set `status.state` to a terminal value
+ * (`completed`/`failed`/`canceled`) — or to `input-required` when the agent
+ * needs more input from the user. Throwing transitions the task to `"failed"`,
+ * with the thrown message recorded in `status.message`.
+ */
+export interface Handler {
+  /**
+   * @param task - The task to advance; mutate it in place.
+   * @param signal - Aborts when the inbound request is cancelled.
+   */
+  handle(task: Task, signal?: AbortSignal): Promise<void>;
+}
+
+/** Plain-function form of a {@link Handler}. */
+export type HandlerFn = (task: Task, signal?: AbortSignal) => Promise<void>;
+
+/**
+ * Adapts a plain function into a {@link Handler}.
+ *
+ * @param fn - The task-handling function.
+ * @returns A {@link Handler} that delegates to `fn`.
+ */
+export function handlerFunc(fn: HandlerFn): Handler {
+  return { handle: fn };
+}
+
+// Inbound-request and store limits. The server accepts unauthenticated input,
+// so every growth vector is bounded.
+const MAX_REQUEST_BYTES = 4 << 20; // 4 MiB
+const MAX_TASK_ID_LEN = 512;
+const DEFAULT_MAX_TASKS = 4096;
+
+interface TaskEntry {
+  task: Task;
+  updated: number;
+  /** Promise chain that serializes sends targeting this task id. */
+  lock: Promise<void>;
+}
+
+/**
+ * Exposes an agent over the A2A HTTP surface.
+ *
+ * Prefer {@link newServer} for construction. Wire {@link Server.fetch} into
+ * Bun.serve to start listening.
+ *
+ * @example
+ * const server = newServer(card, async (task) => {
+ *   appendMessage(task, agentText("hi"));
+ *   task.status.state = "completed";
+ * });
+ * Bun.serve({ port: 8080, fetch: server.fetch });
+ */
+export class Server {
+  /** The Agent Card served verbatim at the well-known path. */
+  readonly card: AgentCard;
+  private readonly handler: Handler;
+  /** Maximum number of tasks retained in the in-memory store. */
+  maxTasks = DEFAULT_MAX_TASKS;
+  private readonly tasks = new Map<string, TaskEntry>();
+
+  /**
+   * @param card - The Agent Card to advertise.
+   * @param handler - The handler that processes each task.
+   */
+  constructor(card: AgentCard, handler: Handler) {
+    this.card = card;
+    this.handler = handler;
+  }
+
+  /**
+   * Bun.serve-compatible request handler, pre-bound so it can be passed by
+   * reference. Routes GETs of the well-known path to the Agent Card, POSTs to
+   * the JSON-RPC dispatcher, and rejects other methods with HTTP 405.
+   *
+   * @param req - The incoming HTTP request.
+   * @returns The HTTP response.
+   */
+  fetch = async (req: Request): Promise<Response> => {
+    const url = new URL(req.url);
+    if (req.method === "GET" && url.pathname === AGENT_CARD_PATH) {
+      return this.serveAgentCard();
+    }
+    if (req.method !== "POST") {
+      return new Response("method not allowed", { status: 405 });
+    }
+    return this.serveJSONRPC(req);
+  };
+
+  private serveAgentCard(): Response {
+    return new Response(JSON.stringify(this.card), {
+      status: 200,
+      headers: {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store",
+      },
+    });
+  }
+
+  private async serveJSONRPC(req: Request): Promise<Response> {
+    // Bound the body: an unauthenticated peer must not drive unbounded
+    // allocation with a giant POST. Reject early on a declared Content-Length
+    // over the cap, and otherwise count bytes as the body streams in so an
+    // unsized body is also rejected once it crosses the cap.
+    const declared = req.headers.get("content-length");
+    if (declared !== null) {
+      const n = Number(declared);
+      if (Number.isFinite(n) && n > MAX_REQUEST_BYTES) {
+        return jsonResponse(errorReply(null, ERR_PARSE_ERROR, "parse error", "request body too large"));
+      }
+    }
+    const body = await readRequestCapped(req, MAX_REQUEST_BYTES);
+    if (body === null) {
+      return jsonResponse(errorReply(null, ERR_PARSE_ERROR, "parse error", "request body too large"));
+    }
+    let msg: RPCRequest;
+    try {
+      msg = JSON.parse(body) as RPCRequest;
+    } catch (e) {
+      return jsonResponse(errorReply(null, ERR_PARSE_ERROR, "parse error", String(e)));
+    }
+    const id = msg.id ?? null;
+    if (msg.jsonrpc !== "2.0") {
+      return jsonResponse(
+        errorReply(id, ERR_INVALID_REQUEST, 'jsonrpc must be "2.0"', String(msg.jsonrpc)),
+      );
+    }
+    let reply: RPCResponse;
+    switch (msg.method) {
+      case METHOD_TASKS_SEND:
+        reply = await this.handleTasksSend(id, msg.params, req.signal);
+        break;
+      case METHOD_TASKS_GET:
+        reply = this.handleTasksGet(id, msg.params);
+        break;
+      default:
+        reply = errorReply(id, ERR_METHOD_NOT_FOUND, "method not found", String(msg.method));
+    }
+    return jsonResponse(reply);
+  }
+
+  private async handleTasksSend(
+    id: RPCId,
+    rawParams: unknown,
+    signal: AbortSignal,
+  ): Promise<RPCResponse> {
+    const p = rawParams as TasksSendParams | undefined;
+    if (!p || typeof p !== "object") {
+      return errorReply(id, ERR_INVALID_PARAMS, "decode params", "");
+    }
+    const message = p.message as TaskMessage | undefined;
+    if (!message || !Array.isArray(message.parts) || message.parts.length === 0) {
+      return errorReply(id, ERR_INVALID_PARAMS, "message.parts is empty", "");
+    }
+    const reqID = p.id ?? "";
+    if (reqID.length > MAX_TASK_ID_LEN) {
+      return errorReply(id, ERR_INVALID_PARAMS, "id too long", "");
+    }
+
+    // Look up or create the entry. The synchronous section is atomic on the
+    // event loop. An empty id always allocates a fresh uuid-keyed task.
+    let entry = reqID !== "" ? this.tasks.get(reqID) : undefined;
+    if (entry === undefined) {
+      if (this.tasks.size >= this.maxTasks && !this.evictOne()) {
+        return errorReply(id, ERR_INTERNAL_ERROR, "task store is full", "");
+      }
+      const newID = reqID !== "" ? reqID : crypto.randomUUID();
+      const task: Task = {
+        id: newID,
+        status: { state: "submitted", timestamp: new Date().toISOString() },
+        history: [],
+        ...(p.sessionId !== undefined && p.sessionId !== "" ? { sessionId: p.sessionId } : {}),
+        ...(p.metadata !== undefined ? { metadata: { ...p.metadata } } : {}),
+      };
+      entry = { task, updated: Date.now(), lock: Promise.resolve() };
+      this.tasks.set(newID, entry);
+    }
+
+    // Serialize same-id sends: chain onto the entry's lock.
+    const e = entry;
+    const prev = e.lock;
+    let release!: () => void;
+    e.lock = new Promise<void>((res) => {
+      release = res;
+    });
+    await prev;
+    try {
+      return await this.processSend(id, e, message, p, signal);
+    } finally {
+      release();
+    }
+  }
+
+  private async processSend(
+    id: RPCId,
+    e: TaskEntry,
+    message: TaskMessage,
+    p: TasksSendParams,
+    signal: AbortSignal,
+  ): Promise<RPCResponse> {
+    // Phase 1: reject a terminal task, append the user message, flip to
+    // "running" and commit — so a concurrent tasks/get observes progress.
+    if (isTerminalState(e.task.status.state)) {
+      return errorReply(
+        id,
+        ERR_INVALID_TASK_STATE,
+        "task is in a terminal state and cannot be continued",
+        e.task.status.state,
+      );
+    }
+    appendMessage(e.task, message);
+    if (p.sessionId !== undefined && p.sessionId !== "") {
+      e.task.sessionId = p.sessionId;
+    }
+    if (p.metadata !== undefined && Object.keys(p.metadata).length > 0) {
+      e.task.metadata = { ...(e.task.metadata ?? {}), ...p.metadata };
+    }
+    // Flip only state + timestamp; a prior status message (e.g. an
+    // input-required prompt) stays visible on the mid-handler snapshot.
+    e.task.status = {
+      ...e.task.status,
+      state: "working",
+      timestamp: new Date().toISOString(),
+    };
+    e.updated = Date.now();
+
+    // Detach an independent copy for the handler so its mutations can't bleed
+    // into the stored task until committed.
+    const wc = structuredClone(e.task);
+
+    // Phase 2: run the handler. No data lock is held across the await, so a
+    // concurrent tasks/get returns the "working" snapshot promptly.
+    try {
+      await this.handler.handle(wc, signal);
+    } catch (err) {
+      wc.status = {
+        state: "failed",
+        message: agentText(err instanceof Error ? err.message : String(err)),
+        timestamp: new Date().toISOString(),
+      };
+    }
+    if (!isTerminalState(wc.status.state) && wc.status.state !== "input-required") {
+      // Handler returned cleanly but forgot to set a terminal state. A handler
+      // that asked for more input (input-required) is left as-is so the task
+      // can be continued with a later tasks/send.
+      wc.status = { ...wc.status, state: "completed", timestamp: new Date().toISOString() };
+    }
+
+    // Phase 3: commit the result and snapshot for the reply.
+    e.task = wc;
+    e.updated = Date.now();
+    return successReply(id, structuredClone(wc));
+  }
+
+  private evictOne(): boolean {
+    let oldestID = "";
+    let oldest = Number.POSITIVE_INFINITY;
+    for (const [tid, e] of this.tasks) {
+      if (!isTerminalState(e.task.status.state)) continue;
+      if (oldestID === "" || e.updated < oldest) {
+        oldestID = tid;
+        oldest = e.updated;
+      }
+    }
+    if (oldestID === "") return false;
+    this.tasks.delete(oldestID);
+    return true;
+  }
+
+  private handleTasksGet(id: RPCId, rawParams: unknown): RPCResponse {
+    const p = rawParams as TasksGetParams | undefined;
+    if (!p || typeof p !== "object") {
+      return errorReply(id, ERR_INVALID_PARAMS, "decode params", "");
+    }
+    if (!p.id) {
+      return errorReply(id, ERR_INVALID_PARAMS, "id is required", "");
+    }
+    const e = this.tasks.get(p.id);
+    if (e === undefined) {
+      return errorReply(id, ERR_TASK_NOT_FOUND, "task not found", p.id);
+    }
+    const snap = structuredClone(e.task);
+    if (
+      p.historyLength !== undefined &&
+      p.historyLength > 0 &&
+      snap.history !== undefined &&
+      snap.history.length > p.historyLength
+    ) {
+      snap.history = snap.history.slice(snap.history.length - p.historyLength);
+    }
+    return successReply(id, snap);
+  }
+}
+
+/**
+ * Constructs a {@link Server}, accepting either a {@link Handler} object or a
+ * plain {@link HandlerFn}. The card is served verbatim at the well-known path.
+ *
+ * @param card - The Agent Card to advertise.
+ * @param handler - The task handler, as an object or a function.
+ * @returns A ready-to-serve {@link Server}.
+ */
+export function newServer(card: AgentCard, handler: Handler | HandlerFn): Server {
+  const h: Handler = typeof handler === "function" ? { handle: handler } : handler;
+  return new Server(card, h);
+}
+
+/**
+ * Reads a request body, counting bytes as they arrive and aborting once the
+ * cap is exceeded — so an oversized body is rejected without first being fully
+ * buffered.
+ *
+ * @param req - The incoming request.
+ * @param cap - Maximum number of body bytes to accept.
+ * @returns The decoded body text, or `null` if the body exceeds `cap`.
+ */
+async function readRequestCapped(req: Request, cap: number): Promise<string | null> {
+  const stream = req.body;
+  if (stream === null) {
+    return "";
+  }
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    if (value) {
+      total += value.byteLength;
+      if (total > cap) {
+        await reader.cancel();
+        return null;
+      }
+      chunks.push(value);
+    }
+  }
+  const buf = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    buf.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(buf);
+}
+
+function successReply(id: RPCId, result: unknown): RPCResponse {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function errorReply(id: RPCId, code: number, message: string, detail: string): RPCResponse {
+  const error: RPCErrorObject =
+    detail !== "" ? { code, message, data: { detail } } : { code, message };
+  return { jsonrpc: "2.0", id: id ?? null, error };
+}
+
+function jsonResponse(msg: RPCResponse): Response {
+  // JSON-RPC over HTTP always returns 200 even for protocol-level errors —
+  // the error lives in the response envelope.
+  return new Response(JSON.stringify(msg), {
+    status: 200,
+    headers: { "Content-Type": "application/json; charset=utf-8" },
+  });
+}

package/src/types.ts

@@ -0,0 +1,297 @@
+/**
+ * Wire types, constants, message helpers and errors for the Agent-to-Agent
+ * (A2A) protocol carried as JSON-RPC 2.0 over HTTP.
+ *
+ * Field names are camelCase and serialize directly to the on-wire JSON. Data
+ * shapes are plain interfaces; failures are represented as {@link Error}
+ * subclasses ({@link A2AError}, {@link RPCError}).
+ *
+ * Scope notes for this implementation:
+ *   - {@link TaskState} is the A2A-spec six-value lifecycle:
+ *     submitted | working | input-required | completed | failed | canceled.
+ *   - {@link TaskStatus} carries the state plus an optional status `message`
+ *     (e.g. an input-required prompt or a failure message) and a `timestamp`.
+ *   - A task's full message log lives in {@link Task.history}; non-message
+ *     outputs live in {@link Task.artifacts}.
+ */
+
+/**
+ * Well-known location of an agent's card. The A2A spec mandates this exact
+ * suffix; clients discover an agent at `<baseURL>/.well-known/agent.json`.
+ */
+export const AGENT_CARD_PATH = "/.well-known/agent.json";
+
+/** A2A protocol revision this implementation targets. */
+export const PROTOCOL_VERSION = "0.1";
+
+/** JSON-RPC method name for creating or continuing a task. */
+export const METHOD_TASKS_SEND = "tasks/send";
+/** JSON-RPC method name for fetching a task's current state. */
+export const METHOD_TASKS_GET = "tasks/get";
+
+// JSON-RPC 2.0 standard error codes.
+/** Malformed JSON in the request body. */
+export const ERR_PARSE_ERROR = -32700;
+/** Request envelope is not a valid JSON-RPC request. */
+export const ERR_INVALID_REQUEST = -32600;
+/** Requested method is not implemented. */
+export const ERR_METHOD_NOT_FOUND = -32601;
+/** Method params are missing or invalid. */
+export const ERR_INVALID_PARAMS = -32602;
+/** Unexpected server-side failure. */
+export const ERR_INTERNAL_ERROR = -32603;
+// A2A-specific error codes defined by the protocol.
+/** No task exists for the supplied id. */
+export const ERR_TASK_NOT_FOUND = -32001;
+/** Task cannot accept the request in its current state (e.g. terminal). */
+export const ERR_INVALID_TASK_STATE = -32002;
+
+/** AgentProvider identifies the organization running the agent. */
+export interface AgentProvider {
+  organization: string;
+  url: string;
+}
+
+/** AgentCapabilities advertises optional protocol features. */
+export interface AgentCapabilities {
+  streaming?: boolean;
+  pushNotifications?: boolean;
+}
+
+/** AgentSkill is one discrete capability the agent advertises. */
+export interface AgentSkill {
+  id: string;
+  name: string;
+  description?: string;
+  tags?: string[];
+  examples?: string[];
+}
+
+/** AgentCard is the metadata document served at /.well-known/agent.json. */
+export interface AgentCard {
+  name: string;
+  description?: string;
+  url: string;
+  version?: string;
+  provider?: AgentProvider;
+  capabilities: AgentCapabilities;
+  skills: AgentSkill[];
+  defaultInputModes?: string[];
+  defaultOutputModes?: string[];
+}
+
+/**
+ * Part is one element of a message's content. The A2A spec defines "text",
+ * "file" and "data" parts; only "text" is implemented. `type` is the
+ * discriminator so future parts deserialize without breaking older readers.
+ */
+export interface Part {
+  type: string;
+  /** Text is set when type === "text". */
+  text?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/** Role identifies who sent a message. */
+export type Role = "user" | "agent";
+
+/** TaskMessage is one turn in a task's message log. */
+export interface TaskMessage {
+  role: Role;
+  parts: Part[];
+}
+
+/**
+ * TaskState is the discrete lifecycle state of a task, per the A2A spec.
+ *
+ * `submitted` → `working` are non-terminal; `input-required` is non-terminal
+ * and signals the agent needs more input (the task can be continued with
+ * another tasks/send); `completed` / `failed` / `canceled` are terminal.
+ */
+export type TaskState =
+  | "submitted"
+  | "working"
+  | "input-required"
+  | "completed"
+  | "failed"
+  | "canceled";
+
+/** TaskStatus is the status block of a Task. */
+export interface TaskStatus {
+  state: TaskState;
+  /** Optional status message (e.g. an input-required prompt or a failure message). */
+  message?: TaskMessage;
+  /** RFC 3339 timestamp of the last status transition. Omitted when unset. */
+  timestamp?: string;
+}
+
+/** Artifact is a non-message output of a task (a file, a JSON blob, …). */
+export interface Artifact {
+  name?: string;
+  description?: string;
+  parts: Part[];
+}
+
+/**
+ * Task is the unit of work the protocol revolves around. Clients create one
+ * with tasks/send; servers append messages and transition Status as they
+ * process it; clients poll via tasks/get until the state is terminal.
+ */
+export interface Task {
+  id: string;
+  sessionId?: string;
+  status: TaskStatus;
+  /** The message log: the initial user message followed by assistant/user turns. */
+  history?: TaskMessage[];
+  /** Intermediate outputs that don't belong in the message log. */
+  artifacts?: Artifact[];
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Builds a text {@link Part} from a string.
+ *
+ * @param s - The text content.
+ * @returns A part with `type` `"text"`.
+ */
+export function textPart(s: string): Part {
+  return { type: "text", text: s };
+}
+
+/**
+ * Builds a user-role {@link TaskMessage} carrying a single text part.
+ *
+ * @param s - The user's text.
+ * @returns A message with role `"user"`.
+ * @example
+ * client.sendTask(userText("What is the weather?"));
+ */
+export function userText(s: string): TaskMessage {
+  return { role: "user", parts: [textPart(s)] };
+}
+
+/**
+ * Builds an agent-role {@link TaskMessage} carrying a single text part; the
+ * agent-side counterpart of {@link userText}.
+ *
+ * @param s - The agent's text.
+ * @returns A message with role `"agent"`.
+ */
+export function agentText(s: string): TaskMessage {
+  return { role: "agent", parts: [textPart(s)] };
+}
+
+/**
+ * Concatenates the text of every text part in a message, joined by newlines.
+ * Non-text parts are skipped.
+ *
+ * @param m - The message to flatten.
+ * @returns The combined text, or an empty string if the message has no text
+ * parts.
+ */
+export function messageText(m: TaskMessage): string {
+  let out = "";
+  for (const p of m.parts) {
+    if (p.type === "text") {
+      if (out !== "") out += "\n";
+      out += p.text ?? "";
+    }
+  }
+  return out;
+}
+
+/**
+ * Appends a message to a task's history, mutating the task in place. Stamps the
+ * status timestamp when it isn't set yet.
+ *
+ * @param task - The task whose history to extend.
+ * @param m - The message to append.
+ */
+export function appendMessage(task: Task, m: TaskMessage): void {
+  if (task.history === undefined) task.history = [];
+  task.history.push(m);
+  if (!task.status.timestamp) task.status.timestamp = new Date().toISOString();
+}
+
+/**
+ * Reports whether a task state is terminal (no further work will occur).
+ *
+ * @param state - The state to test.
+ * @returns `true` for `"completed"`, `"failed"`, or `"canceled"`.
+ */
+export function isTerminalState(state: TaskState): boolean {
+  return state === "completed" || state === "failed" || state === "canceled";
+}
+
+/** Base error for transport and protocol failures raised by this library. */
+export class A2AError extends Error {
+  override name = "A2AError";
+}
+
+/**
+ * Error carrying a JSON-RPC error envelope returned by a remote agent.
+ *
+ * @example
+ * try {
+ *   await client.getTask("missing");
+ * } catch (e) {
+ *   if (e instanceof RPCError) console.error(e.code, e.message);
+ * }
+ */
+export class RPCError extends A2AError {
+  override name = "RPCError";
+  /** The JSON-RPC numeric error code. */
+  readonly code: number;
+  /** Optional implementation-defined error detail. */
+  readonly data?: unknown;
+  /**
+   * @param code - JSON-RPC error code.
+   * @param message - Human-readable error message.
+   * @param data - Optional structured error detail.
+   */
+  constructor(code: number, message: string, data?: unknown) {
+    super(`a2a: JSON-RPC ${code}: ${message}`);
+    this.code = code;
+    if (data !== undefined) this.data = data;
+  }
+}
+
+/** JSON-RPC id: a number, string, or null. */
+export type RPCId = number | string | null;
+
+/** RPCRequest is an inbound JSON-RPC request envelope. */
+export interface RPCRequest {
+  jsonrpc: "2.0";
+  id?: RPCId;
+  method?: string;
+  params?: unknown;
+}
+
+/** RPCErrorObject is the `error` member of a JSON-RPC response. */
+export interface RPCErrorObject {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+/** RPCResponse is an outbound JSON-RPC response envelope. */
+export interface RPCResponse {
+  jsonrpc: "2.0";
+  id: RPCId;
+  result?: unknown;
+  error?: RPCErrorObject;
+}
+
+/** tasksSendParams is the params payload for `tasks/send`. */
+export interface TasksSendParams {
+  id?: string;
+  sessionId?: string;
+  message: TaskMessage;
+  metadata?: Record<string, unknown>;
+}
+
+/** tasksGetParams is the params payload for `tasks/get`. */
+export interface TasksGetParams {
+  id: string;
+  historyLength?: number;
+}