@ap3x/a2a 1.0.0 → 2.0.0

package/proto/google/api/annotations.proto

@@ -0,0 +1,6 @@
+// Minimal vendored stub of google/api/annotations.proto (Apache-2.0, googleapis).
+// The A2A proto imports it only for the (google.api.http) method option, which
+// protobufjs parses without needing the extension declaration. Empty stub keeps
+// runtime loading deterministic without vendoring the full googleapis tree.
+syntax = "proto3";
+package google.api;

package/proto/google/api/client.proto

@@ -0,0 +1,4 @@
+// Minimal vendored stub of google/api/client.proto (Apache-2.0, googleapis).
+// Imported by the A2A proto only for the (google.api.method_signature) option.
+syntax = "proto3";
+package google.api;

package/proto/google/api/field_behavior.proto

@@ -0,0 +1,4 @@
+// Minimal vendored stub of google/api/field_behavior.proto (Apache-2.0, googleapis).
+// Imported by the A2A proto only for the (google.api.field_behavior) option.
+syntax = "proto3";
+package google.api;

package/src/__tests__/a2a-auth-expired.test.ts

@@ -1,84 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { A2AClient } from "../client/index.js";
-import { A2AAuthExpiredError } from "../errors.js";
-
-/**
- * BUG-0284: A2AClient has no mechanism to surface expired auth credentials.
- * OAuth2 tokens expire, causing generic 401 failures with no typed error.
- *
- * Fix: detect 401 responses and throw A2AAuthExpiredError so callers can
- * catch it specifically and trigger token refresh / retry logic.
- */
-
-describe("BUG-0284: A2AClient throws A2AAuthExpiredError on 401", () => {
-  const originalFetch = globalThis.fetch;
-
-  beforeEach(() => {
-    // Reset fetch mock before each test
-    vi.restoreAllMocks();
-  });
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-  });
-
-  function mock401() {
-    globalThis.fetch = vi.fn().mockResolvedValue(
-      new Response("Unauthorized", { status: 401, statusText: "Unauthorized" }),
-    );
-  }
-
-  function mock403() {
-    globalThis.fetch = vi.fn().mockResolvedValue(
-      new Response("Forbidden", { status: 403, statusText: "Forbidden" }),
-    );
-  }
-
-  it("getCard throws A2AAuthExpiredError on 401", async () => {
-    mock401();
-    const client = new A2AClient({ baseUrl: "http://localhost:3001" });
-
-    await expect(client.getCard()).rejects.toThrow(A2AAuthExpiredError);
-    await expect(client.getCard()).rejects.toMatchObject({
-      name: "A2AAuthExpiredError",
-      statusCode: 401,
-      url: "http://localhost:3001/.well-known/agent.json",
-    });
-  });
-
-  it("sendTask throws A2AAuthExpiredError on 401", async () => {
-    mock401();
-    const client = new A2AClient({ baseUrl: "http://localhost:3001" });
-
-    await expect(client.sendTask("hello")).rejects.toThrow(A2AAuthExpiredError);
-    await expect(client.sendTask("hello")).rejects.toMatchObject({
-      statusCode: 401,
-      url: "http://localhost:3001",
-    });
-  });
-
-  it("streamTask throws A2AAuthExpiredError on 401", async () => {
-    mock401();
-    const client = new A2AClient({ baseUrl: "http://localhost:3001" });
-
-    const gen = client.streamTask("hello");
-    await expect(gen.next()).rejects.toThrow(A2AAuthExpiredError);
-  });
-
-  it("A2AAuthExpiredError extends Error for backward compatibility", () => {
-    const err = new A2AAuthExpiredError("test", "http://example.com");
-    expect(err).toBeInstanceOf(Error);
-    expect(err).toBeInstanceOf(A2AAuthExpiredError);
-    expect(err.name).toBe("A2AAuthExpiredError");
-    expect(err.statusCode).toBe(401);
-    expect(err.url).toBe("http://example.com");
-  });
-
-  it("non-401 errors still throw generic Error (e.g. 403)", async () => {
-    mock403();
-    const client = new A2AClient({ baseUrl: "http://localhost:3001" });
-
-    await expect(client.sendTask("hello")).rejects.toThrow(Error);
-    await expect(client.sendTask("hello")).rejects.not.toThrow(A2AAuthExpiredError);
-  });
-});

package/src/__tests__/a2a.test.ts

@@ -1,87 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { generateAgentCard } from "../card/generator.js";
-import { A2AClient } from "../client/index.js";
-import { A2AServer } from "../server/index.js";
-import { a2aAgent } from "../swarm/a2a-agent.js";
-
-describe("generateAgentCard", () => {
-  it("generates a valid agent card", () => {
-    const card = generateAgentCard({
-      name: "Test Agent",
-      description: "A test agent",
-      url: "http://localhost:3001",
-      skills: [{ id: "test", name: "Test Skill" }],
-    });
-    expect(card.name).toBe("Test Agent");
-    expect(card.capabilities).toBeDefined();
-    expect(card.skills).toHaveLength(1);
-  });
-});
-
-describe("A2AClient.asToolDefinition", () => {
-  it("returns valid ToolDefinition shape", () => {
-    const client = new A2AClient({ baseUrl: "http://localhost:3001" });
-    const tool = client.asToolDefinition({ name: "remote_agent", description: "A remote agent" });
-    expect(tool.name).toBe("remote_agent");
-    expect(tool.schema.type).toBe("object");
-    expect(tool.schema.required).toContain("message");
-  });
-});
-
-describe("A2AServer + A2AClient round trip", () => {
-  it("handles tasks/send in-process", async () => {
-    const card = generateAgentCard({
-      name: "Echo Agent",
-      description: "Echoes messages",
-      url: "http://test",
-    });
-
-    const server = new A2AServer(card, async (message) => `Echo: ${message}`);
-    const handler = server.requestHandler();
-
-    // Simulate a client request directly
-    const reqBody = {
-      jsonrpc: "2.0",
-      id: 1,
-      method: "tasks/send",
-      params: { id: "test-task", message: { role: "user", parts: [{ type: "text", text: "hello" }] } },
-    };
-
-    const req = new Request("http://test/", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(reqBody),
-    });
-
-    const res = await handler(req);
-    expect(res.status).toBe(200);
-    const data = await res.json() as { result: { artifacts: Array<{ parts: Array<{ text: string }> }> } };
-    expect(data.result.artifacts[0]!.parts[0]!.text).toBe("Echo: hello");
-  });
-
-  it("serves agent card at /.well-known/agent.json", async () => {
-    const card = generateAgentCard({ name: "Test", description: "Test", url: "http://test" });
-    const server = new A2AServer(card, async () => "ok");
-    const handler = server.requestHandler();
-
-    const req = new Request("http://test/.well-known/agent.json");
-    const res = await handler(req);
-    expect(res.status).toBe(200);
-    const returned = await res.json() as { name: string };
-    expect(returned.name).toBe("Test");
-  });
-});
-
-describe("a2aAgent", () => {
-  it("creates an agent def with correct shape", () => {
-    const agent = a2aAgent({
-      id: "remote-researcher",
-      role: "Researches topics using web search",
-      clientConfig: { baseUrl: "http://remote-agent:3000" },
-    });
-    expect(agent.id).toBe("remote-researcher");
-    expect(typeof agent.invoke).toBe("function");
-    const tool = agent.asTool();
-    expect(tool.name).toBe("remote-researcher");
-  });
-});

package/src/__tests__/handler-sendsubscribe-error.test.ts

@@ -1,32 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { handleJsonRPC } from "../server/handler.js";
-import { generateAgentCard } from "../card/generator.js";
-
-describe("handleJsonRPC — tasks/sendSubscribe", () => {
-  it("BUG-0001: should return JSON-RPC error when handler throws synchronously", async () => {
-    const card = generateAgentCard({ name: "Test", description: "Test", url: "http://test", streaming: true });
-
-    const throwingHandler = () => {
-      throw new Error("sync boom");
-    };
-
-    const result = await handleJsonRPC(
-      {
-        jsonrpc: "2.0",
-        id: 1,
-        method: "tasks/sendSubscribe",
-        params: { id: "t1", message: { parts: [{ type: "text", text: "hi" }] } },
-      },
-      throwingHandler as any,
-      card,
-    );
-
-    // Should return a well-formed JSON-RPC error, not throw
-    expect(result.response).toBeDefined();
-    const res = result.response as { jsonrpc: string; id: unknown; error: { code: number; message: string } };
-    expect(res.jsonrpc).toBe("2.0");
-    expect(res.id).toBe(1);
-    expect(res.error.code).toBe(-32603);
-    expect(res.error.message).toBe("sync boom");
-  });
-});

package/src/__tests__/sendsubscribe-rejected-promise.test.ts

@@ -1,89 +0,0 @@
-/**
- * Regression test for BUG-0361
- *
- * `handler()` for tasks/sendSubscribe was not awaited before checking
- * [Symbol.asyncIterator]. If handler() returns a rejected Promise instead of
- * throwing synchronously, the rejection bypassed the surrounding try/catch and
- * surfaced as an unhandled rejection rather than a well-formed JSON-RPC error.
- *
- * Fix: await handler(messageText, taskId) so rejected Promises are caught by
- * the existing try/catch block. Landed in commit ada9de7 on main.
- */
-import { describe, it, expect } from "vitest";
-import { handleJsonRPC } from "../server/handler.js";
-import { generateAgentCard } from "../card/generator.js";
-
-describe("BUG-0361: tasks/sendSubscribe — rejected Promise must be caught as JSON-RPC error", () => {
-  it("returns a JSON-RPC error when handler returns a rejected Promise", async () => {
-    const card = generateAgentCard({
-      name: "Test",
-      description: "Test",
-      url: "http://test",
-      streaming: true,
-    });
-
-    // A handler that returns a Promise.reject() rather than throwing synchronously.
-    // Before the fix, the rejection was not caught — handler() was called without
-    // await, so the rejected promise was never observed by the try/catch.
-    const rejectingHandler = () => Promise.reject(new Error("async rejection"));
-
-    const result = await handleJsonRPC(
-      {
-        jsonrpc: "2.0",
-        id: 42,
-        method: "tasks/sendSubscribe",
-        params: { id: "t1", message: { parts: [{ type: "text", text: "hello" }] } },
-      },
-      rejectingHandler as any,
-      card,
-    );
-
-    // Must return a well-formed JSON-RPC error response, not propagate the rejection
-    expect(result.response).toBeDefined();
-    expect(result.stream).toBeUndefined();
-
-    const res = result.response as {
-      jsonrpc: string;
-      id: unknown;
-      error: { code: number; message: string };
-    };
-    expect(res.jsonrpc).toBe("2.0");
-    expect(res.id).toBe(42);
-    expect(res.error).toBeDefined();
-    expect(res.error.code).toBe(-32603);
-  });
-
-  it("still returns a stream when handler returns a valid async generator", async () => {
-    const card = generateAgentCard({
-      name: "Test",
-      description: "Test",
-      url: "http://test",
-      streaming: true,
-    });
-
-    async function* validHandler(): AsyncGenerator<string> {
-      yield "chunk-1";
-      yield "chunk-2";
-    }
-
-    const result = await handleJsonRPC(
-      {
-        jsonrpc: "2.0",
-        id: 1,
-        method: "tasks/sendSubscribe",
-        params: { id: "t2", message: { parts: [{ type: "text", text: "hi" }] } },
-      },
-      validHandler as any,
-      card,
-    );
-
-    expect(result.stream).toBeDefined();
-    expect(result.response).toBeUndefined();
-
-    const chunks: string[] = [];
-    for await (const chunk of result.stream!) {
-      chunks.push(chunk);
-    }
-    expect(chunks).toEqual(["chunk-1", "chunk-2"]);
-  });
-});

package/src/__tests__/server-apikey-warning.test.ts

@@ -1,71 +0,0 @@
-import { describe, it, expect, vi, afterEach } from "vitest";
-import { generateAgentCard } from "../card/generator.js";
-import { A2AServer } from "../server/index.js";
-
-describe("A2AServer unauthenticated deployment warning (BUG-0256)", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it("BUG-0256: logs a warning to console.warn when no apiKey is configured", () => {
-    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-
-    const card = generateAgentCard({
-      name: "Open Agent",
-      description: "No auth",
-      url: "http://test",
-    });
-
-    new A2AServer(card, async () => "ok");
-
-    expect(warnSpy).toHaveBeenCalledOnce();
-    const [msg] = warnSpy.mock.calls[0]!;
-    expect(typeof msg).toBe("string");
-    expect((msg as string).toLowerCase()).toContain("unauthenticated");
-  });
-
-  it("BUG-0256: does NOT log a warning when apiKey is provided", () => {
-    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-
-    const card = generateAgentCard({
-      name: "Secure Agent",
-      description: "With auth",
-      url: "http://test",
-    });
-
-    new A2AServer(card, async () => "ok", { apiKey: "my-secret-key" });
-
-    expect(warnSpy).not.toHaveBeenCalled();
-  });
-
-  it("BUG-0256: unauthenticated server still handles requests (no regression)", async () => {
-    vi.spyOn(console, "warn").mockImplementation(() => {});
-
-    const card = generateAgentCard({
-      name: "Open Agent",
-      description: "No auth",
-      url: "http://test",
-    });
-
-    const server = new A2AServer(card, async (message) => `echo:${message}`);
-    const handler = server.requestHandler();
-
-    // Without apiKey, requests should be served with no auth gate
-    const req = new Request("http://test/", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-        id: 1,
-        method: "tasks/send",
-        params: {
-          id: "t1",
-          message: { role: "user", parts: [{ type: "text", text: "hello" }] },
-        },
-      }),
-    });
-
-    const res = await handler(req);
-    expect(res.status).toBe(200);
-  });
-});

package/src/__tests__/server-body-limit.test.ts

@@ -1,54 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { A2AServer } from "../server/index.js";
-import { generateAgentCard } from "../card/generator.js";
-
-describe("BUG-0077: A2A server rejects oversized request bodies", () => {
-  it("BUG-0077: should return 413 when Content-Length exceeds 1MB", async () => {
-    const card = generateAgentCard({
-      name: "Test",
-      description: "Test",
-      url: "http://test",
-    });
-    const server = new A2AServer(card, async () => "ok");
-    const handler = server.requestHandler();
-
-    // Create a request with Content-Length claiming > 1MB
-    const oversizedBody = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tasks/send", params: {} });
-    const req = new Request("http://test/", {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Content-Length": String(2 * 1024 * 1024), // 2MB
-      },
-      body: oversizedBody,
-    });
-
-    const res = await handler(req);
-    expect(res.status).toBe(413);
-    const data = await res.json() as { error: { message: string } };
-    expect(data.error.message).toContain("too large");
-  });
-
-  it("BUG-0077: should return 413 when actual body text exceeds 1MB", async () => {
-    const card = generateAgentCard({
-      name: "Test",
-      description: "Test",
-      url: "http://test",
-    });
-    const server = new A2AServer(card, async () => "ok");
-    const handler = server.requestHandler();
-
-    // Create a request with body text > 1MB but no Content-Length header hint
-    const largePayload = "x".repeat(1.5 * 1024 * 1024);
-    const req = new Request("http://test/", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: largePayload,
-    });
-
-    const res = await handler(req);
-    expect(res.status).toBe(413);
-    const data = await res.json() as { error: { message: string } };
-    expect(data.error.message).toContain("too large");
-  });
-});

package/src/__tests__/server-security-headers.test.ts

@@ -1,112 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { generateAgentCard } from "../card/generator.js";
-import { A2AServer } from "../server/index.js";
-
-// Suppress the "no apiKey" warning for tests that don't need auth
-const silenceWarn = () => vi.spyOn(console, "warn").mockImplementation(() => {});
-
-const REQUIRED_SECURITY_HEADERS: [string, string][] = [
-  ["x-content-type-options", "nosniff"],
-  ["x-frame-options", "DENY"],
-  ["content-security-policy", "default-src 'none'"],
-];
-
-function makeCard() {
-  return generateAgentCard({
-    name: "Security Header Test Agent",
-    description: "Tests security headers",
-    url: "http://test",
-  });
-}
-
-describe("A2AServer security headers (BUG-0257)", () => {
-  it("BUG-0257: includes security headers on a successful tasks/send response", async () => {
-    vi.spyOn(console, "warn").mockImplementation(() => {});
-    const server = new A2AServer(makeCard(), async (message) => `echo:${message}`);
-    const handler = server.requestHandler();
-
-    const req = new Request("http://test/", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-        id: 1,
-        method: "tasks/send",
-        params: {
-          id: "t1",
-          message: { role: "user", parts: [{ type: "text", text: "hello" }] },
-        },
-      }),
-    });
-
-    const res = await handler(req);
-    expect(res.status).toBe(200);
-
-    for (const [header, value] of REQUIRED_SECURITY_HEADERS) {
-      expect(
-        res.headers.get(header),
-        `Expected ${header}: ${value} on 200 response`,
-      ).toBe(value);
-    }
-  });
-
-  it("BUG-0257: includes security headers on agent-card GET response", async () => {
-    vi.spyOn(console, "warn").mockImplementation(() => {});
-    const server = new A2AServer(makeCard(), async () => "ok");
-    const handler = server.requestHandler();
-
-    const req = new Request("http://test/.well-known/agent.json");
-    const res = await handler(req);
-    expect(res.status).toBe(200);
-
-    for (const [header, value] of REQUIRED_SECURITY_HEADERS) {
-      expect(
-        res.headers.get(header),
-        `Expected ${header}: ${value} on agent card response`,
-      ).toBe(value);
-    }
-  });
-
-  it("BUG-0257: includes security headers on 401 Unauthorized response", async () => {
-    const server = new A2AServer(makeCard(), async () => "ok", {
-      apiKey: "secret",
-    });
-    const handler = server.requestHandler();
-
-    const req = new Request("http://test/", {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: "Bearer wrong",
-      },
-      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tasks/send", params: {} }),
-    });
-
-    const res = await handler(req);
-    expect(res.status).toBe(401);
-
-    for (const [header, value] of REQUIRED_SECURITY_HEADERS) {
-      expect(
-        res.headers.get(header),
-        `Expected ${header}: ${value} on 401 response`,
-      ).toBe(value);
-    }
-  });
-
-  it("BUG-0257: includes security headers on 405 Method Not Allowed response", async () => {
-    silenceWarn();
-    const server = new A2AServer(makeCard(), async () => "ok");
-    const handler = server.requestHandler();
-
-    const req = new Request("http://test/", { method: "DELETE" });
-    const res = await handler(req);
-    expect(res.status).toBe(405);
-
-    for (const [header, value] of REQUIRED_SECURITY_HEADERS) {
-      expect(
-        res.headers.get(header),
-        `Expected ${header}: ${value} on 405 response`,
-      ).toBe(value);
-    }
-  });
-});

package/src/__tests__/server-timing-safe-auth.test.ts

@@ -1,45 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { generateAgentCard } from "../card/generator.js";
-import { A2AServer } from "../server/index.js";
-
-describe("A2AServer API key authentication", () => {
-  it("BUG-0236: should use crypto.timingSafeEqual for API key comparison", async () => {
-    const card = generateAgentCard({
-      name: "Auth Test",
-      description: "Test",
-      url: "http://test",
-    });
-
-    const server = new A2AServer(card, async () => "ok", {
-      apiKey: "secret-key-12345",
-    });
-    const handler = server.requestHandler();
-
-    // Request with correct key should succeed
-    const goodReq = new Request("http://test/.well-known/agent.json", {
-      headers: { Authorization: "Bearer secret-key-12345" },
-    });
-    const goodRes = await handler(goodReq);
-    expect(goodRes.status).toBe(200);
-
-    // Request with wrong key should be rejected
-    const badReq = new Request("http://test/.well-known/agent.json", {
-      headers: { Authorization: "Bearer wrong-key" },
-    });
-    const badRes = await handler(badReq);
-    expect(badRes.status).toBe(401);
-
-    // Request with no auth header should be rejected
-    const noAuthReq = new Request("http://test/.well-known/agent.json");
-    const noAuthRes = await handler(noAuthReq);
-    expect(noAuthRes.status).toBe(401);
-
-    // Request with key of same length but different content should be rejected
-    // (this is the case that timing attacks exploit — same-length strings)
-    const sameLenReq = new Request("http://test/.well-known/agent.json", {
-      headers: { Authorization: "Bearer secret-key-12346" },
-    });
-    const sameLenRes = await handler(sameLenReq);
-    expect(sameLenRes.status).toBe(401);
-  });
-});

package/src/__tests__/sse-handler-error-propagation.test.ts

@@ -1,69 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { handleJsonRPC } from "../server/handler.js";
-import { createSSEResponse } from "../server/sse.js";
-import { generateAgentCard } from "../card/generator.js";
-
-describe("SSE stream error propagation", () => {
-  it("BUG-0054: handler generator errors produce a JSON-RPC error SSE event, not a 'working' state frame", async () => {
-    const card = generateAgentCard({
-      name: "Test",
-      description: "Test",
-      url: "http://test",
-      streaming: true,
-    });
-
-    // A streaming handler that yields one chunk then throws
-    const throwingStreamingHandler = async function* () {
-      yield "partial output";
-      throw new Error("boom mid-stream");
-    };
-
-    const result = await handleJsonRPC(
-      {
-        jsonrpc: "2.0",
-        id: 1,
-        method: "tasks/sendSubscribe",
-        params: { id: "t1", message: { parts: [{ type: "text", text: "go" }] } },
-      },
-      throwingStreamingHandler as unknown as Parameters<typeof handleJsonRPC>[1],
-      card,
-    );
-
-    // The result must have a stream (not an inline error response)
-    expect(result.stream).toBeDefined();
-    expect(result.taskId).toBeDefined();
-
-    // Consume the SSE response through createSSEResponse, collecting all frames
-    const sseResponse = createSSEResponse(result.stream!, result.taskId!);
-    const reader = sseResponse.body!.getReader();
-    const decoder = new TextDecoder();
-    const frames: string[] = [];
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        frames.push(decoder.decode(value));
-      }
-    } catch {
-      // The stream errors after emitting the JSON-RPC error frame;
-      // controller.error() causes the read loop to throw. That's expected.
-    }
-
-    const allSSE = frames.join("");
-
-    // Before the fix: safeStream caught the error and yielded it as a text string,
-    // so it appeared as a "working" state frame and the stream ended with "completed".
-    // After the fix: the error propagates to createSSEResponse's catch block,
-    // which emits a JSON-RPC error event with code -32603.
-    expect(allSSE).toContain('"code":-32603');
-
-    // The stream must NOT end with a "completed" state after an error
-    const lastDataFrame = allSSE.split("data: ").filter(Boolean).pop() ?? "";
-    expect(lastDataFrame).not.toContain('"state":"completed"');
-
-    // The error frame must not be disguised as a "working" status chunk
-    // (i.e., the error JSON should appear in an error-keyed object, not in status.message.parts)
-    expect(allSSE).toContain('"error"');
-    expect(allSSE).not.toMatch(/"state":"working"[^}]*"boom mid-stream"/);
-  });
-});