@galdor/a2a 0.3.0

package/dist/client.d.ts

@@ -0,0 +1,107 @@
+/**
+ * A2A client speaking JSON-RPC 2.0 over HTTP to a single remote agent.
+ *
+ * Each {@link Client} instance issues auto-incrementing JSON-RPC ids that are
+ * unique within that client. Response bodies are size-capped so a hostile
+ * agent cannot exhaust memory with an oversized reply, every request is bound
+ * by a default deadline, and redirects are confined to the original host so
+ * card discovery cannot be turned into a server-side request forgery pivot.
+ */
+import type { AgentCard, Task, TaskMessage } from "./types.ts";
+/** A `fetch`-compatible function, so callers can inject a custom HTTP client. */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** Construction options for {@link Client}. */
+export interface ClientOptions {
+    /**
+     * Override the `fetch` used for every request — a custom agent, auth wrapper,
+     * proxy, or retry layer. Same-host redirect confinement and the body cap still
+     * apply. Defaults to the global `fetch`.
+     */
+    fetch?: FetchLike;
+    /**
+     * Per-request deadline in milliseconds, combined with any caller signal.
+     * Defaults to 60000. Raise it to allow longer requests, or set 0 to disable
+     * the built-in deadline entirely so a caller-supplied signal has full control
+     * (including extending past the default 60s).
+     */
+    timeoutMs?: number;
+}
+/** Options for {@link Client.sendTask}. */
+export interface SendOptions {
+    /** Id of an existing task to continue (multi-turn conversation). */
+    taskId?: string;
+    /** Logical session id grouping related tasks together. */
+    sessionId?: string;
+    /** Metadata to attach to the task on the server. */
+    metadata?: Record<string, unknown>;
+    /** Abort signal to cancel the in-flight request. */
+    signal?: AbortSignal;
+}
+/**
+ * Client for one remote A2A agent, identified by its base URL.
+ *
+ * @example
+ * const client = new Client("https://agent.example.com");
+ * const task = await client.sendTask(userText("hello"));
+ * console.log(task.status.state);
+ */
+export declare class Client {
+    private readonly baseURL;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private id;
+    /**
+     * Overrides the default card-discovery URL ({@link AGENT_CARD_PATH} appended
+     * to the base URL). Set this when the Agent Card is served from a different
+     * host than the JSON-RPC endpoint.
+     */
+    agentCardURL?: string;
+    /**
+     * @param baseURL - The agent's base URL; any trailing slashes are stripped.
+     * @param opts - Optional custom `fetch` and per-request `timeoutMs`.
+     */
+    constructor(baseURL: string, opts?: ClientOptions);
+    /**
+     * Fetches and parses the agent's card from the well-known path.
+     *
+     * @param signal - Optional abort signal, combined with the default deadline.
+     * @returns The parsed {@link AgentCard}.
+     * @throws {A2AError} On a non-2xx HTTP status, an oversized body, a
+     * cross-host redirect, or invalid JSON.
+     */
+    fetchAgentCard(signal?: AbortSignal): Promise<AgentCard>;
+    /**
+     * Posts a `tasks/send` request and returns the resulting task.
+     *
+     * When `opts.taskId` is omitted the server allocates a fresh id; reuse the
+     * returned task's id on follow-up sends to continue a multi-turn
+     * conversation.
+     *
+     * @param message - The user message to send; must contain at least one part.
+     * @param opts - Optional task continuation, session, metadata and abort
+     * controls.
+     * @returns The task after the server has processed this turn.
+     * @throws {A2AError} If the message has no parts, on a transport/decoding
+     * failure, an oversized response, or a cross-host redirect.
+     * @throws {RPCError} If the agent returns a JSON-RPC error envelope.
+     * @example
+     * const task = await client.sendTask(userText("hi"), { sessionId: "s1" });
+     */
+    sendTask(message: TaskMessage, opts?: SendOptions): Promise<Task>;
+    /**
+     * Fetches the current state of a task by id.
+     *
+     * @param taskId - Id of the task to fetch; required.
+     * @param historyLength - When greater than 0, truncates the returned message
+     * log to the most-recent N messages.
+     * @param signal - Optional abort signal, combined with the default deadline.
+     * @returns The task's current {@link Task} snapshot.
+     * @throws {A2AError} If `taskId` is empty, on a transport/decoding failure,
+     * an oversized response, or a cross-host redirect.
+     * @throws {RPCError} If the agent returns a JSON-RPC error (e.g. unknown id).
+     */
+    getTask(taskId: string, historyLength?: number, signal?: AbortSignal): Promise<Task>;
+    /** Issues a JSON-RPC request and decodes the reply. */
+    private call;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAe,IAAI,EAAE,WAAW,EAAmC,MAAM,YAAY,CAAC;AA2B7G,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE/E,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,oDAAoD;IACpD,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,EAAE,CAAK;IAEf;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB;IAMrD;;;;;;;OAOG;IACG,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;IAc9D;;;;;;;;;;;;;;;;OAgBG;IACG,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAa3E;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,SAAI,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrF,uDAAuD;YACzC,IAAI;CA6BnB"}

package/dist/client.js

@@ -0,0 +1,241 @@
+/**
+ * A2A client speaking JSON-RPC 2.0 over HTTP to a single remote agent.
+ *
+ * Each {@link Client} instance issues auto-incrementing JSON-RPC ids that are
+ * unique within that client. Response bodies are size-capped so a hostile
+ * agent cannot exhaust memory with an oversized reply, every request is bound
+ * by a default deadline, and redirects are confined to the original host so
+ * card discovery cannot be turned into a server-side request forgery pivot.
+ */
+import { A2AError, AGENT_CARD_PATH, METHOD_TASKS_GET, METHOD_TASKS_SEND, RPCError } from "./types.js";
+/**
+ * Upper bound, in bytes, on how much of a remote agent's response is buffered
+ * or decoded. A hostile or compromised agent could otherwise stream an
+ * arbitrarily large body and exhaust client memory; 4 MiB is far larger than
+ * any legitimate Agent Card or task reply needs.
+ */
+const MAX_RESPONSE_BYTES = 4 << 20;
+/**
+ * Default per-request deadline, in milliseconds. A request that has not
+ * completed within this window is aborted. Callers can pass their own
+ * {@link AbortSignal}; both bounds are honored together.
+ */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * Maximum number of HTTP redirects followed for a single request before the
+ * client gives up. Bounds the same-host redirect loop so a server cannot pin
+ * the client in an endless redirect cycle.
+ */
+const MAX_REDIRECTS = 10;
+/** HTTP status codes that request a redirect to the `Location` header. */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * Client for one remote A2A agent, identified by its base URL.
+ *
+ * @example
+ * const client = new Client("https://agent.example.com");
+ * const task = await client.sendTask(userText("hello"));
+ * console.log(task.status.state);
+ */
+export class Client {
+    baseURL;
+    fetchImpl;
+    timeoutMs;
+    id = 0;
+    /**
+     * Overrides the default card-discovery URL ({@link AGENT_CARD_PATH} appended
+     * to the base URL). Set this when the Agent Card is served from a different
+     * host than the JSON-RPC endpoint.
+     */
+    agentCardURL;
+    /**
+     * @param baseURL - The agent's base URL; any trailing slashes are stripped.
+     * @param opts - Optional custom `fetch` and per-request `timeoutMs`.
+     */
+    constructor(baseURL, opts = {}) {
+        this.baseURL = baseURL.replace(/\/+$/, "");
+        this.fetchImpl = opts.fetch ?? ((url, init) => fetch(url, init));
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /**
+     * Fetches and parses the agent's card from the well-known path.
+     *
+     * @param signal - Optional abort signal, combined with the default deadline.
+     * @returns The parsed {@link AgentCard}.
+     * @throws {A2AError} On a non-2xx HTTP status, an oversized body, a
+     * cross-host redirect, or invalid JSON.
+     */
+    async fetchAgentCard(signal) {
+        const url = this.agentCardURL ?? this.baseURL + AGENT_CARD_PATH;
+        const resp = await sameHostFetch(url, { method: "GET" }, signal, this.fetchImpl, this.timeoutMs);
+        const raw = await readCapped(resp);
+        if (resp.status < 200 || resp.status >= 300) {
+            throw new A2AError(`a2a: agent card HTTP ${resp.status}: ${raw}`);
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch (e) {
+            throw new A2AError(`a2a: decode agent card: ${String(e)}`);
+        }
+    }
+    /**
+     * Posts a `tasks/send` request and returns the resulting task.
+     *
+     * When `opts.taskId` is omitted the server allocates a fresh id; reuse the
+     * returned task's id on follow-up sends to continue a multi-turn
+     * conversation.
+     *
+     * @param message - The user message to send; must contain at least one part.
+     * @param opts - Optional task continuation, session, metadata and abort
+     * controls.
+     * @returns The task after the server has processed this turn.
+     * @throws {A2AError} If the message has no parts, on a transport/decoding
+     * failure, an oversized response, or a cross-host redirect.
+     * @throws {RPCError} If the agent returns a JSON-RPC error envelope.
+     * @example
+     * const task = await client.sendTask(userText("hi"), { sessionId: "s1" });
+     */
+    async sendTask(message, opts = {}) {
+        if (!message.parts || message.parts.length === 0) {
+            throw new A2AError("a2a: sendTask: message has no parts");
+        }
+        const params = {
+            message,
+            ...(opts.taskId !== undefined ? { id: opts.taskId } : {}),
+            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+            ...(opts.metadata !== undefined ? { metadata: opts.metadata } : {}),
+        };
+        return this.call(METHOD_TASKS_SEND, params, opts.signal);
+    }
+    /**
+     * Fetches the current state of a task by id.
+     *
+     * @param taskId - Id of the task to fetch; required.
+     * @param historyLength - When greater than 0, truncates the returned message
+     * log to the most-recent N messages.
+     * @param signal - Optional abort signal, combined with the default deadline.
+     * @returns The task's current {@link Task} snapshot.
+     * @throws {A2AError} If `taskId` is empty, on a transport/decoding failure,
+     * an oversized response, or a cross-host redirect.
+     * @throws {RPCError} If the agent returns a JSON-RPC error (e.g. unknown id).
+     */
+    async getTask(taskId, historyLength = 0, signal) {
+        if (!taskId) {
+            throw new A2AError("a2a: getTask: id is required");
+        }
+        const params = {
+            id: taskId,
+            ...(historyLength > 0 ? { historyLength } : {}),
+        };
+        return this.call(METHOD_TASKS_GET, params, signal);
+    }
+    /** Issues a JSON-RPC request and decodes the reply. */
+    async call(method, params, signal) {
+        this.id += 1;
+        const body = JSON.stringify({ jsonrpc: "2.0", id: this.id, method, params });
+        const resp = await sameHostFetch(this.baseURL, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json" },
+            body,
+        }, signal, this.fetchImpl, this.timeoutMs);
+        const raw = await readCapped(resp);
+        if (resp.status < 200 || resp.status >= 300) {
+            throw new A2AError(`a2a: HTTP ${resp.status}: ${raw}`);
+        }
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch (e) {
+            throw new A2AError(`a2a: decode response: ${String(e)}`);
+        }
+        if (msg.error) {
+            throw new RPCError(msg.error.code, msg.error.message, msg.error.data);
+        }
+        return msg.result;
+    }
+}
+/**
+ * Issues a fetch that follows only same-host 3xx redirects and is bound by the
+ * default deadline together with any caller-supplied signal.
+ *
+ * Redirects are resolved manually: a redirect whose target host differs from
+ * the previous request's host is refused, so a semi-trusted discovery URL
+ * cannot bounce the client onto an internal address (a 302 to 169.254.169.254
+ * or localhost). Same-host redirects are followed, up to {@link MAX_REDIRECTS}.
+ *
+ * @param url - The initial request URL.
+ * @param init - Request init, applied to every hop; `redirect` is forced to
+ * `"manual"`.
+ * @param signal - Optional caller signal, combined with the default deadline
+ * via {@link AbortSignal.any}.
+ * @returns The first non-redirect {@link Response}.
+ * @throws {A2AError} On a cross-host redirect or after too many redirects.
+ */
+async function sameHostFetch(url, init, signal, fetchImpl = (u, i) => fetch(u, i), timeoutMs = DEFAULT_TIMEOUT_MS) {
+    // A positive timeout installs a default deadline; 0 disables it so a
+    // caller-supplied signal alone controls the deadline (and can extend it).
+    const timeout = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+    const combined = signal && timeout ? AbortSignal.any([signal, timeout]) : (signal ?? timeout);
+    let current = url;
+    for (let hop = 0;; hop++) {
+        const resp = await fetchImpl(current, { ...init, redirect: "manual", ...(combined ? { signal: combined } : {}) });
+        if (!REDIRECT_STATUSES.has(resp.status)) {
+            return resp;
+        }
+        const location = resp.headers.get("location");
+        if (location === null || location === "") {
+            // A redirect status without a usable target: treat as final.
+            return resp;
+        }
+        if (hop >= MAX_REDIRECTS) {
+            throw new A2AError(`a2a: too many redirects (>${MAX_REDIRECTS})`);
+        }
+        const next = new URL(location, current);
+        if (next.host !== new URL(current).host) {
+            throw new A2AError(`a2a: refusing cross-host redirect to "${next.host}"`);
+        }
+        current = next.toString();
+    }
+}
+/**
+ * Reads a response body, counting bytes as they arrive and aborting once the
+ * size cap is exceeded — so an oversized body is rejected without first being
+ * fully buffered.
+ *
+ * @param resp - The response whose body to read.
+ * @returns The decoded body text.
+ * @throws {A2AError} If the body exceeds {@link MAX_RESPONSE_BYTES}.
+ */
+async function readCapped(resp) {
+    const stream = resp.body;
+    if (stream === null) {
+        return "";
+    }
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        if (value) {
+            total += value.byteLength;
+            if (total > MAX_RESPONSE_BYTES) {
+                await reader.cancel();
+                throw new A2AError(`a2a: response exceeds ${MAX_RESPONSE_BYTES} bytes`);
+            }
+            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);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @galdor/a2a — Agent-to-Agent (A2A) protocol over JSON-RPC 2.0 and HTTP.
+ *
+ * Expose an agent over HTTP with {@link newServer}, which returns a
+ * Bun.serve-compatible fetch handler, and call a remote agent with
+ * {@link Client}. Shared wire types, constants and helpers live alongside.
+ */
+export { AGENT_CARD_PATH, PROTOCOL_VERSION, METHOD_TASKS_SEND, METHOD_TASKS_GET, ERR_PARSE_ERROR, ERR_INVALID_REQUEST, ERR_METHOD_NOT_FOUND, ERR_INVALID_PARAMS, ERR_INTERNAL_ERROR, ERR_TASK_NOT_FOUND, ERR_INVALID_TASK_STATE, textPart, userText, agentText, messageText, appendMessage, isTerminalState, A2AError, RPCError, } from "./types.ts";
+export type { AgentCard, AgentProvider, AgentCapabilities, AgentSkill, Part, Role, TaskMessage, TaskState, TaskStatus, Artifact, Task, RPCId, RPCRequest, RPCResponse, RPCErrorObject, TasksSendParams, TasksGetParams, } from "./types.ts";
+export { Server, newServer, handlerFunc } from "./server.ts";
+export type { Handler, HandlerFn } from "./server.ts";
+export { Client } from "./client.ts";
+export type { SendOptions } from "./client.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,WAAW,EACX,aAAa,EACb,eAAe,EACf,QAAQ,EACR,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,IAAI,EACJ,IAAI,EACJ,WAAW,EACX,SAAS,EACT,UAAU,EACV,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,UAAU,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7D,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @galdor/a2a — Agent-to-Agent (A2A) protocol over JSON-RPC 2.0 and HTTP.
+ *
+ * Expose an agent over HTTP with {@link newServer}, which returns a
+ * Bun.serve-compatible fetch handler, and call a remote agent with
+ * {@link Client}. Shared wire types, constants and helpers live alongside.
+ */
+export { AGENT_CARD_PATH, PROTOCOL_VERSION, METHOD_TASKS_SEND, METHOD_TASKS_GET, ERR_PARSE_ERROR, ERR_INVALID_REQUEST, ERR_METHOD_NOT_FOUND, ERR_INVALID_PARAMS, ERR_INTERNAL_ERROR, ERR_TASK_NOT_FOUND, ERR_INVALID_TASK_STATE, textPart, userText, agentText, messageText, appendMessage, isTerminalState, A2AError, RPCError, } from "./types.js";
+export { Server, newServer, handlerFunc } from "./server.js";
+export { Client } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,WAAW,EACX,aAAa,EACb,eAAe,EACf,QAAQ,EACR,QAAQ,GACT,MAAM,YAAY,CAAC;AAqBpB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG7D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 type { AgentCard, Task } 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 declare function handlerFunc(fn: HandlerFn): Handler;
+/**
+ * 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 declare class Server {
+    /** The Agent Card served verbatim at the well-known path. */
+    readonly card: AgentCard;
+    private readonly handler;
+    /** Maximum number of tasks retained in the in-memory store. */
+    maxTasks: number;
+    private readonly tasks;
+    /**
+     * @param card - The Agent Card to advertise.
+     * @param handler - The handler that processes each task.
+     */
+    constructor(card: AgentCard, 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: (req: Request) => Promise<Response>;
+    private serveAgentCard;
+    private serveJSONRPC;
+    private handleTasksSend;
+    private processSend;
+    private evictOne;
+    private handleTasksGet;
+}
+/**
+ * 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 declare function newServer(card: AgentCard, handler: Handler | HandlerFn): Server;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAiBH,OAAO,KAAK,EACV,SAAS,EAKT,IAAI,EAIL,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED,gDAAgD;AAChD,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5E;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAElD;AAeD;;;;;;;;;;;;GAYG;AACH,qBAAa,MAAM;IACjB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,+DAA+D;IAC/D,QAAQ,SAAqB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IAEtD;;;OAGG;gBACS,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO;IAK7C;;;;;;;OAOG;IACH,KAAK,GAAU,KAAK,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAS7C;IAEF,OAAO,CAAC,cAAc;YAUR,YAAY;YA0CZ,eAAe;YAoDf,WAAW;IA6DzB,OAAO,CAAC,QAAQ;IAehB,OAAO,CAAC,cAAc;CAuBvB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAG/E"}