@galdor/a2a 0.3.0

package/dist/types.js

@@ -0,0 +1,148 @@
+/**
+ * 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;
+/**
+ * Builds a text {@link Part} from a string.
+ *
+ * @param s - The text content.
+ * @returns A part with `type` `"text"`.
+ */
+export function textPart(s) {
+    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) {
+    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) {
+    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) {
+    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, m) {
+    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) {
+    return state === "completed" || state === "failed" || state === "canceled";
+}
+/** Base error for transport and protocol failures raised by this library. */
+export class A2AError extends Error {
+    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 {
+    name = "RPCError";
+    /** The JSON-RPC numeric error code. */
+    code;
+    /** Optional implementation-defined error detail. */
+    data;
+    /**
+     * @param code - JSON-RPC error code.
+     * @param message - Human-readable error message.
+     * @param data - Optional structured error detail.
+     */
+    constructor(code, message, data) {
+        super(`a2a: JSON-RPC ${code}: ${message}`);
+        this.code = code;
+        if (data !== undefined)
+            this.data = data;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@galdor/a2a",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "galdor-bun a2a: Google Agent-to-Agent (A2A) protocol — JSON-RPC 2.0 over HTTP client + server.",
+  "author": {
+    "name": "Yasser Rosas",
+    "email": "yassros16@gmail.com"
+  },
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "engines": {
+    "node": ">=22.5",
+    "bun": ">=1.3"
+  },
+  "dependencies": {
+    "@galdor/core": "0.3.0"
+  }
+}

package/src/a2a.test.ts

@@ -0,0 +1,267 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { Client } from "./client.ts";
+import { type Handler, handlerFunc, newServer } from "./server.ts";
+import {
+  AGENT_CARD_PATH,
+  type AgentCard,
+  agentText,
+  appendMessage,
+  ERR_PARSE_ERROR,
+  messageText,
+  type Task,
+} from "./types.ts";
+
+let listening: ReturnType<typeof Bun.serve> | undefined;
+
+afterEach(() => {
+  listening?.stop(true);
+  listening = undefined;
+});
+
+/** start spins up an A2A Server on an ephemeral port and returns a Client. */
+function start(handler: Handler): Client {
+  const card: AgentCard = {
+    name: "test-agent",
+    description: "test fixture",
+    url: "",
+    version: "0.1",
+    capabilities: {},
+    skills: [{ id: "echo", name: "Echo", description: "Repeats whatever the user said" }],
+  };
+  const server = newServer(card, handler);
+  listening = Bun.serve({ port: 0, fetch: server.fetch });
+  return new Client(`http://localhost:${listening.port}`);
+}
+
+/** echo replays the latest user message back as an agent turn, then completes. */
+const echo = handlerFunc(async (task: Task) => {
+  let said = "";
+  for (const m of task.history ?? []) {
+    if (m.role === "user") said = messageText(m);
+  }
+  appendMessage(task, agentText(`echo: ${said}`));
+  task.status.state = "completed";
+});
+
+describe("a2a", () => {
+  test("fetchAgentCard returns the published card", async () => {
+    const client = start(echo);
+    const card = await client.fetchAgentCard();
+    expect(card.name).toBe("test-agent");
+    expect(card.version).toBe("0.1");
+    expect(card.skills).toHaveLength(1);
+    expect(card.skills[0]?.id).toBe("echo");
+  });
+
+  test("sendTask runs the handler and returns the completed task", async () => {
+    const client = start(echo);
+    const task = await client.sendTask({ role: "user", parts: [{ type: "text", text: "hello" }] });
+
+    expect(task.id).not.toBe("");
+    expect(task.status.state).toBe("completed");
+    // Log holds the user turn + the echoed agent turn.
+    expect(task.history).toHaveLength(2);
+    const agentTurn = task.history![1];
+    expect(agentTurn?.role).toBe("agent");
+    expect(messageText(agentTurn!)).toContain("echo: hello");
+  });
+
+  test("getTask retrieves a task by id", async () => {
+    const client = start(echo);
+    const created = await client.sendTask({
+      role: "user",
+      parts: [{ type: "text", text: "hi" }],
+    });
+    const got = await client.getTask(created.id);
+    expect(got.id).toBe(created.id);
+    expect(got.status.state).toBe("completed");
+    expect(messageText(got.history![1]!)).toContain("echo: hi");
+  });
+
+  test("handler errors mark the task failed with the message in status.message", async () => {
+    const client = start(
+      handlerFunc(async () => {
+        throw new Error("planet exploded");
+      }),
+    );
+    // SendTask succeeds at the protocol level; the failure is in the status.
+    const task = await client.sendTask({ role: "user", parts: [{ type: "text", text: "oops" }] });
+    expect(task.status.state).toBe("failed");
+    expect(task.status.message).toBeDefined();
+    expect(messageText(task.status.message!)).toContain("planet exploded");
+  });
+
+  test("server auto-completes when the handler forgets the terminal state", async () => {
+    const client = start(
+      handlerFunc(async (task: Task) => {
+        appendMessage(task, agentText("done but forgot the flag"));
+        // Intentionally leaves state at "working".
+      }),
+    );
+    const task = await client.sendTask({ role: "user", parts: [{ type: "text", text: "hi" }] });
+    expect(task.status.state).toBe("completed");
+  });
+
+  test("input-required is preserved (not coerced to completed) and the task can be continued", async () => {
+    // The handler asks for more input on the first turn, then completes on the second.
+    const client = start(
+      handlerFunc(async (task: Task) => {
+        const userTurns = (task.history ?? []).filter((m) => m.role === "user").length;
+        if (userTurns < 2) {
+          appendMessage(task, agentText("What is your name?"));
+          task.status = { state: "input-required", message: agentText("What is your name?") };
+          return;
+        }
+        appendMessage(task, agentText("Hello!"));
+        task.status.state = "completed";
+      }),
+    );
+    const first = await client.sendTask({ role: "user", parts: [{ type: "text", text: "hi" }] });
+    expect(first.status.state).toBe("input-required");
+    // Continue the same task by reusing its id (via the taskId option).
+    const second = await client.sendTask(
+      { role: "user", parts: [{ type: "text", text: "Ada" }] },
+      { taskId: first.id },
+    );
+    expect(second.status.state).toBe("completed");
+  });
+
+  test("a handler can attach artifacts to the task", async () => {
+    const client = start(
+      handlerFunc(async (task: Task) => {
+        task.artifacts = [{ name: "result.json", parts: [{ type: "text", text: '{"ok":true}' }] }];
+        task.status.state = "completed";
+      }),
+    );
+    const task = await client.sendTask({ role: "user", parts: [{ type: "text", text: "go" }] });
+    expect(task.artifacts).toHaveLength(1);
+    expect(task.artifacts![0]?.name).toBe("result.json");
+    expect(messageText({ role: "agent", parts: task.artifacts![0]!.parts })).toContain('"ok":true');
+  });
+
+  test("getTask on an unknown id rejects", async () => {
+    const client = start(echo);
+    await expect(client.getTask("ghost")).rejects.toThrow();
+  });
+
+  test("getTask truncates the log to historyLength", async () => {
+    const client = start(
+      handlerFunc(async (task: Task) => {
+        appendMessage(task, agentText("a"));
+        appendMessage(task, agentText("b"));
+        appendMessage(task, agentText("c"));
+        task.status.state = "completed";
+      }),
+    );
+    const created = await client.sendTask({ role: "user", parts: [{ type: "text", text: "go" }] });
+    // Full log = 1 user + 3 agent = 4 messages.
+    const got = await client.getTask(created.id, 2);
+    expect(got.history).toHaveLength(2);
+  });
+
+  test("server rejects an over-cap request body", async () => {
+    const client = start(echo);
+    // A text part larger than the 4 MiB request cap.
+    const big = "y".repeat((4 << 20) + 1024);
+    await expect(
+      client.sendTask({ role: "user", parts: [{ type: "text", text: big }] }),
+    ).rejects.toThrow();
+  });
+});
+
+/** A minimal Agent Card fixture for the protection tests. */
+function fixtureCard(name = "test-agent"): AgentCard {
+  return { name, description: "fixture", url: "", version: "0.1", capabilities: {}, skills: [] };
+}
+
+describe("a2a protections", () => {
+  let server: ReturnType<typeof Bun.serve> | undefined;
+
+  afterEach(() => {
+    server?.stop(true);
+    server = undefined;
+  });
+
+  test("client refuses a cross-host redirect (SSRF guard)", async () => {
+    server = Bun.serve({
+      port: 0,
+      fetch: () =>
+        new Response(null, { status: 302, headers: { Location: "http://example.com/evil" } }),
+    });
+    const client = new Client(`http://localhost:${server.port}`);
+    await expect(client.fetchAgentCard()).rejects.toThrow(/cross-host/);
+  });
+
+  test("client follows a same-host redirect", async () => {
+    server = Bun.serve({
+      port: 0,
+      fetch: (req) => {
+        const url = new URL(req.url);
+        if (url.pathname === AGENT_CARD_PATH) {
+          return new Response(null, { status: 302, headers: { Location: "/card" } });
+        }
+        return new Response(JSON.stringify(fixtureCard("redirected")), {
+          headers: { "Content-Type": "application/json" },
+        });
+      },
+    });
+    const client = new Client(`http://localhost:${server.port}`);
+    const card = await client.fetchAgentCard();
+    expect(card.name).toBe("redirected");
+  });
+
+  test("client rejects an over-cap response body", async () => {
+    // One byte past the 4 MiB response cap.
+    const big = "x".repeat((4 << 20) + 1);
+    server = Bun.serve({ port: 0, fetch: () => new Response(big) });
+    const client = new Client(`http://localhost:${server.port}`);
+    await expect(client.fetchAgentCard()).rejects.toThrow(/exceeds/);
+  });
+
+  test("client honors a caller signal alongside the default deadline", async () => {
+    server = Bun.serve({
+      port: 0,
+      fetch: async () => {
+        await Bun.sleep(2000);
+        return new Response("{}");
+      },
+    });
+    const client = new Client(`http://localhost:${server.port}`);
+    // The caller's 50ms signal must fire even though it is combined with the
+    // 60s default deadline.
+    await expect(client.fetchAgentCard(AbortSignal.timeout(50))).rejects.toThrow();
+  });
+
+  test("server rejects an over-cap streamed request without content-length", async () => {
+    const a2a = newServer(fixtureCard(), echo);
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new Uint8Array((4 << 20) + 1));
+        controller.close();
+      },
+    });
+    const req = new Request("http://localhost/rpc", {
+      method: "POST",
+      body: stream,
+      duplex: "half",
+    } as RequestInit & { duplex: "half" });
+    const resp = await a2a.fetch(req);
+    const reply = (await resp.json()) as { error?: { code: number } };
+    expect(reply.error?.code).toBe(ERR_PARSE_ERROR);
+  });
+
+  test("a custom fetch is used for requests (HTTP transport customization)", async () => {
+    const seen: string[] = [];
+    const card: AgentCard = { name: "custom", description: "d", url: "http://agent.invalid", version: "1", capabilities: {}, skills: [] };
+    const customFetch = async (url: string): Promise<Response> => {
+      seen.push(url);
+      return new Response(JSON.stringify(card), { status: 200, headers: { "content-type": "application/json" } });
+    };
+    // timeoutMs: 0 disables the built-in deadline so a caller-supplied client
+    // has full control (it could run longer than the default 60s).
+    const client = new Client("http://agent.invalid", { fetch: customFetch, timeoutMs: 0 });
+    const got = await client.fetchAgentCard();
+    expect(got.name).toBe("custom");
+    expect(seen).toEqual([`http://agent.invalid${AGENT_CARD_PATH}`]);
+  });
+});