@ap3x/a2a 1.0.0 → 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AP3X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @ap3x/a2a
+
+A2A protocol support: a client, a server, and the bindings that let a remote agent join a local swarm as an ordinary member.
+
+Part of [AP3X](https://github.com/AP3X-Dev/AP3X) — a TypeScript multi-agent framework.
+
+## Install
+
+```bash
+npm install @ap3x/a2a
+```
+
+## What's inside
+
+- **Client + server** — the A2A request/response surface with agent-card discovery.
+- **Transports** — JSON-RPC and REST, with an optional gRPC binding that is lazily loaded so gRPC stays an opt-in dependency.
+- **Swarm integration** — a remote A2A agent satisfies `AgentBackend`, so orchestration consumes it like any local member.
+
+The A2A specification is Apache-2.0; see [a2aproject/A2A](https://github.com/a2aproject/A2A).
+
+## Documentation
+
+See the [AP3X repository](https://github.com/AP3X-Dev/AP3X) for architecture notes, the full package map, and examples.
+
+## License
+
+MIT

package/dist/backend.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A2aBackend — an {@link AgentBackend} whose "runtime" is a remote A2A agent
+ * reached through an {@link A2aClient}. The mirror of `A2aExecutor`:
+ *
+ * - `run()` sends the task as an A2A Message (blocking by default) and, when
+ *   the answer is not yet terminal, polls `GetTask` with capped exponential
+ *   backoff.
+ * - `runStream()` (present only when the card declares streaming) maps the SSE
+ *   stream (initial Task frame, then status updates) back to agent-core
+ *   `AgentEvent`s.
+ * - ONE `contextId` per backend instance: consecutive runs share the remote
+ *   conversational thread, mirroring a local stateful agent.
+ * - Failure containment: network/HTTP/protocol/timeout failures surface as a
+ *   failed `AgentRunResult` (`stopReason: "error"`) — `run()` NEVER throws.
+ * - `abort()` (and `opts.signal`) cancels the in-flight HTTP request itself —
+ *   even a blocking send with no task id yet — and best-effort CancelTasks
+ *   once a task id is known; the run resolves a failed result, never throws.
+ * - `close()` / `Symbol.(async)Dispose` releases the shared client (refcounted
+ *   across clones) — the grpc channel, when one was negotiated.
+ * - Usage is ZEROED, never fabricated: remote usage is not in the v1 model.
+ */
+import type { AgentBackend, AgentEventStream, AgentMessage, AgentRunOptions, AgentRunResult, BackendCapability } from "@ap3x/agent-core";
+import { A2aClient, type A2aClientOptions } from "./client";
+import { type AgentCard } from "./model";
+export interface A2aBackendOptions {
+    /** First poll delay when the remote answer is not yet terminal. Default 250. */
+    pollInitialDelayMs?: number;
+    /** Backoff cap. Default 5000. */
+    pollMaxDelayMs?: number;
+    /** Overall run deadline. Default 10 minutes (remote agents are orchestrators). */
+    timeoutMs?: number;
+    /** Injectable sleep (tests assert the backoff schedule). */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injected clock (epoch millis). */
+    now?: () => number;
+}
+export declare class A2aBackend implements AgentBackend {
+    readonly card: AgentCard;
+    /** Present only when the card declares `capabilities.streaming`. */
+    runStream?: (task: string | AgentMessage[], opts?: AgentRunOptions) => AgentEventStream;
+    private readonly client;
+    private readonly options;
+    private readonly pollInitialDelayMs;
+    private readonly pollMaxDelayMs;
+    private readonly timeoutMs;
+    private readonly sleep;
+    private readonly now;
+    /** One conversational thread per instance; adopted from the first answer. */
+    private contextId?;
+    private currentTaskId?;
+    /** Aborts the in-flight HTTP request of the current run/stream. */
+    private runAbort?;
+    private closed;
+    /** Clones share the client (one grpc channel); the channel closes at zero. */
+    private readonly clientRefs;
+    constructor(client: A2aClient, options?: A2aBackendOptions, refs?: {
+        count: number;
+    });
+    run(task: string | AgentMessage[], opts?: AgentRunOptions): Promise<AgentRunResult>;
+    /**
+     * Cancel the current run: aborts the in-flight HTTP request (even a blocking
+     * send with no task id yet) and, when a task id is known, issues a
+     * best-effort remote CancelTask.
+     */
+    abort(): void;
+    /** A new backend over the SAME client/card (a remote agent is one endpoint). */
+    clone(): AgentBackend;
+    /**
+     * Release the shared client once EVERY clone has closed (refcounted): the
+     * underlying transport (the grpc channel, when negotiated) is released only
+     * when the last backend over it closes. Idempotent per backend.
+     */
+    close(): void;
+    [Symbol.dispose](): void;
+    [Symbol.asyncDispose](): Promise<void>;
+    supports(capability: BackendCapability): boolean;
+    private cancelRemote;
+    private adopt;
+    private outbound;
+    private assistant;
+    private inbound;
+    private failure;
+    /** Map a TERMINAL remote task back to the uniform backend result. */
+    private toRunResult;
+    private streamRun;
+}
+/** Connect to a remote A2A agent and wrap it as an {@link AgentBackend}. */
+export declare function connectA2a(baseUrl: string, options?: A2aClientOptions & A2aBackendOptions): Promise<A2aBackend>;
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EACV,YAAY,EAEZ,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,SAAS,EACT,KAAK,gBAAgB,EAItB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,KAAK,SAAS,EAAwD,MAAM,SAAS,CAAC;AAgB/F,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iCAAiC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAsDD,qBAAa,UAAW,YAAW,YAAY;IAC7C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,oEAAoE;IACpE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,EAAE,IAAI,CAAC,EAAE,eAAe,KAAK,gBAAgB,CAAC;IAExF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,6EAA6E;IAC7E,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;gBAEnC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,iBAAsB,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;IAkBlF,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAiDzF;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAKb,gFAAgF;IAChF,KAAK,IAAI,YAAY;IAKrB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAOb,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIlB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5C,QAAQ,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO;YAYlC,YAAY;IAU1B,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,SAAS;IAkBjB,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,OAAO;IAUf,qEAAqE;IACrE,OAAO,CAAC,WAAW;IAqBnB,OAAO,CAAC,SAAS;CAoGlB;AAED,4EAA4E;AAC5E,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gBAAgB,GAAG,iBAAsB,GACjD,OAAO,CAAC,UAAU,CAAC,CAGrB"}

package/dist/bindings/grpc.d.ts

@@ -0,0 +1,121 @@
+import { type A2aStreamFrame } from "../client";
+import type { A2aExecutor } from "../executor";
+import { type Message, type Task, type TaskState } from "../model";
+import { type ListTasksFilter } from "../task-store";
+/** A proto<->canonical conversion failure — maps to INVALID_ARGUMENT. */
+export declare class A2aGrpcMappingError extends Error {
+    constructor(message: string);
+}
+/** Canonical state -> proto `TASK_STATE_*` enum name. */
+export declare function taskStateToProto(state: TaskState): string;
+/** Proto `TASK_STATE_*` enum name -> canonical state; UNSPECIFIED is an error. */
+export declare function taskStateFromProto(value: unknown): TaskState;
+interface ProtoStruct {
+    fields?: Record<string, ProtoValue>;
+}
+interface ProtoValue {
+    kind?: string;
+    nullValue?: unknown;
+    numberValue?: number;
+    stringValue?: string;
+    boolValue?: boolean;
+    structValue?: ProtoStruct;
+    listValue?: {
+        values?: ProtoValue[];
+    };
+}
+interface ProtoTimestamp {
+    seconds?: number;
+    nanos?: number;
+}
+interface ProtoPart {
+    content?: string;
+    text?: string;
+    raw?: string;
+    url?: string;
+    data?: ProtoValue;
+    metadata?: ProtoStruct;
+    filename?: string;
+    mediaType?: string;
+}
+interface ProtoMessage {
+    messageId?: string;
+    contextId?: string;
+    taskId?: string;
+    role?: string;
+    parts?: ProtoPart[];
+    metadata?: ProtoStruct;
+}
+interface ProtoTaskStatus {
+    state?: string;
+    message?: ProtoMessage;
+    timestamp?: ProtoTimestamp;
+}
+interface ProtoArtifact {
+    artifactId?: string;
+    name?: string;
+    description?: string;
+    parts?: ProtoPart[];
+    metadata?: ProtoStruct;
+}
+interface ProtoTask {
+    id?: string;
+    contextId?: string;
+    status?: ProtoTaskStatus;
+    artifacts?: ProtoArtifact[];
+    history?: ProtoMessage[];
+    metadata?: ProtoStruct;
+}
+/** Canonical Task -> proto Task. */
+export declare function taskToProto(task: Task): ProtoTask;
+/** Proto Task -> canonical Task. */
+export declare function taskFromProto(proto: ProtoTask): Task;
+export interface A2aGrpcServerOptions {
+    /** Host to bind (same host as the HTTP server). */
+    host: string;
+    /** Port to bind; 0 picks an ephemeral port. */
+    port: number;
+    /** When set, every call requires metadata `authorization: Bearer <token>`. */
+    bearerToken?: string;
+}
+export interface A2aGrpcServer {
+    /** gRPC target of the bound server (`host:port`, no scheme). */
+    url: string;
+    close(): Promise<void>;
+}
+/** Serve `executor` over gRPC; resolves once bound. Card stays on HTTP. */
+export declare function startGrpcServer(executor: A2aExecutor, options: A2aGrpcServerOptions): Promise<A2aGrpcServer>;
+export interface GrpcClientTransportOptions {
+    /** Sent as metadata `authorization: Bearer <token>` on every call. */
+    bearerToken?: string;
+    /** Per-call deadline in milliseconds. */
+    timeoutMs: number;
+}
+/**
+ * The six A2A operations over a gRPC channel — the client half of this
+ * binding. Constructed by `A2aClient.connect` when the card negotiates GRPC.
+ */
+export declare class GrpcClientTransport {
+    private readonly client;
+    private readonly timeoutMs;
+    private readonly bearerToken?;
+    constructor(target: string, options: GrpcClientTransportOptions);
+    /** Close the underlying channel (keeps the event loop free after tests). */
+    close(): void;
+    sendMessage(message: Message, config?: {
+        returnImmediately?: boolean;
+    }): Promise<Task | Message>;
+    sendStreamingMessage(message: Message): AsyncGenerator<A2aStreamFrame>;
+    getTask(id: string): Promise<Task>;
+    listTasks(filter?: ListTasksFilter): Promise<Task[]>;
+    cancelTask(id: string): Promise<Task>;
+    subscribeToTask(id: string): AsyncGenerator<A2aStreamFrame>;
+    private metadata;
+    private callOptions;
+    private wrapError;
+    private convert;
+    private unary;
+    private stream;
+}
+export {};
+//# sourceMappingURL=grpc.d.ts.map

package/dist/bindings/grpc.d.ts.map

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

package/dist/bindings/jsonrpc.d.ts

@@ -0,0 +1,135 @@
+/**
+ * JSON-RPC 2.0 + SSE binding — the A2A wire dialect over the canonical model.
+ *
+ * One POST endpoint routes every method. Interop posture: **accept both
+ * dialects, emit slash.** The deployed reference SDK (0.3.x) speaks
+ * slash-methods (`message/send`, `tasks/get`, …) while the a2a-protocol.org
+ * "latest" spec text documents PascalCase operation names (`SendMessage`, …).
+ * {@link A2A_RPC_METHODS} holds the emit names (slash);
+ * {@link A2A_RPC_METHOD_ALIASES} is the accept-set routing BOTH families to
+ * the same handlers. `message/stream` and `tasks/resubscribe` answer with
+ * `text/event-stream`, one JSON-RPC result per event; per spec the stream
+ * MUST begin with the full Task object, followed by zero or more
+ * status/artifact update events, closing on the terminal event.
+ * `message/send` is BLOCKING by default — `configuration.returnImmediately:
+ * true` is the opt-out. JSON-RPC-level failures stay HTTP 200 per convention;
+ * every inbound payload is TypeBox-validated at this trust boundary.
+ *
+ * Residual interop doubts — confirm against a live reference peer, do not
+ * guess-implement:
+ * - Exact GetTask/CancelTask/SubscribeToTask param field name: we accept
+ *   `{ id }`; the spec's proto may serialize it as `taskId`/`name`.
+ * - ListTasks filter/pagination param shape: we accept `{ contextId?, state? }`.
+ * - Whether stream events carry the `kind` discriminator in v1.0 JSON: we
+ *   emit it on update events; clients here discriminate structurally (a Task
+ *   has `id` + `status` and no update `kind`), so either peer choice parses.
+ *
+ * Resolved against @a2a-js/sdk 0.3.13 (accept both, emit ours):
+ * - Blocking knob: the SDK sends `configuration.blocking` (true = wait for
+ *   terminal); we also accept our `configuration.returnImmediately`, which
+ *   wins when both are present. See {@link resolveBlocking}.
+ * - TaskState serialization: the SDK emits hyphenated states
+ *   (`input-required`, `auth-required`) plus `unknown`; we accept them via
+ *   `normalizeWireTaskStates` at the parse boundary and keep emitting
+ *   snake_case.
+ */
+import type { ServerResponse } from "node:http";
+import { type Static } from "@sinclair/typebox";
+import type { A2aExecutor } from "../executor";
+/**
+ * The JSON-RPC method strings AP3X EMITS — the slash dialect the deployed
+ * reference SDK (0.3.x) speaks. `tasks/list` is an AP3X extension (not in the
+ * 0.3.x SDK surface). `tasks/resubscribe` is the SDK's subscribe-to-existing
+ * verb.
+ */
+export declare const A2A_RPC_METHODS: {
+    readonly sendMessage: "message/send";
+    readonly sendStreamingMessage: "message/stream";
+    readonly getTask: "tasks/get";
+    readonly listTasks: "tasks/list";
+    readonly cancelTask: "tasks/cancel";
+    readonly subscribeToTask: "tasks/resubscribe";
+};
+export type A2aRpcOperation = keyof typeof A2A_RPC_METHODS;
+/**
+ * The ACCEPT-set: every inbound method string this binding routes, mapped to
+ * its canonical operation. Liberal in what we accept — both the slash dialect
+ * (emit names above) and the PascalCase names from the a2a-protocol.org spec
+ * text route to the same handlers.
+ */
+export declare const A2A_RPC_METHOD_ALIASES: Readonly<Record<string, A2aRpcOperation>>;
+export declare const JsonRpcRequestSchema: import("@sinclair/typebox").TObject<{
+    jsonrpc: import("@sinclair/typebox").TLiteral<"2.0">;
+    id: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TNull]>;
+    method: import("@sinclair/typebox").TString;
+    params: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+}>;
+export type JsonRpcRequest = Static<typeof JsonRpcRequestSchema>;
+export declare const MessageSendParamsSchema: import("@sinclair/typebox").TObject<{
+    message: import("@sinclair/typebox").TObject<{
+        messageId: import("@sinclair/typebox").TString;
+        contextId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        taskId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        role: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"user">, import("@sinclair/typebox").TLiteral<"agent">]>;
+        parts: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+            mediaType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+            kind: import("@sinclair/typebox").TLiteral<"text">;
+            text: import("@sinclair/typebox").TString;
+        }>, import("@sinclair/typebox").TObject<{
+            mediaType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+            kind: import("@sinclair/typebox").TLiteral<"data">;
+            data: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
+        }>, import("@sinclair/typebox").TObject<{
+            mediaType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+            kind: import("@sinclair/typebox").TLiteral<"url">;
+            url: import("@sinclair/typebox").TString;
+        }>, import("@sinclair/typebox").TObject<{
+            mediaType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+            kind: import("@sinclair/typebox").TLiteral<"raw">;
+            data: import("@sinclair/typebox").TString;
+        }>]>>;
+        metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+    }>;
+    configuration: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        /**
+         * When true, `SendMessage` returns the Task snapshot immediately instead
+         * of waiting for the terminal state. Default false — blocking is the
+         * spec default.
+         */
+        returnImmediately: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        /**
+         * The reference SDK's (0.3.x) knob for the same choice, inverted:
+         * `blocking: true` waits for the terminal state. Accepted for interop;
+         * AP3X clients emit `returnImmediately`.
+         */
+        blocking: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    }>>;
+}>;
+/**
+ * Blocking resolution for `SendMessage` — ACCEPT both knobs: AP3X's
+ * `returnImmediately` wins when present; else the reference SDK's `blocking`;
+ * else blocking (the v1.0 spec default).
+ */
+export declare function resolveBlocking(configuration?: {
+    returnImmediately?: boolean;
+    blocking?: boolean;
+}): boolean;
+export declare const TaskIdParamsSchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+}>;
+export declare const TaskListParamsSchema: import("@sinclair/typebox").TObject<{
+    contextId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    state: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"submitted" | "working" | "input_required" | "auth_required" | "completed" | "failed" | "canceled" | "rejected">[]>>;
+}>;
+/** Open an SSE response and register it for shutdown. Shared with rest.ts. */
+export declare function startSse(res: ServerResponse, sseStreams: Set<ServerResponse>): void;
+/**
+ * Handle one JSON-RPC request body. `sseStreams` registers any stream this
+ * request opens so the server can shut them down on `close()`.
+ */
+export declare function handleJsonRpc(executor: A2aExecutor, rawBody: string, res: ServerResponse, sseStreams: Set<ServerResponse>): Promise<void>;
+//# sourceMappingURL=jsonrpc.d.ts.map

package/dist/bindings/jsonrpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc.d.ts","sourceRoot":"","sources":["../../src/bindings/jsonrpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAW/C;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;;;;CAOlB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,eAAe,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAU5E,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEjE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAI9B;;;;WAIG;;QAEH;;;;WAIG;;;EAIP,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,aAAa,CAAC,EAAE;IAC9C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAGV;AAED,eAAO,MAAM,kBAAkB;;EAAqC,CAAC;AAErE,eAAO,MAAM,oBAAoB;;;EAG/B,CAAC;AAmCH,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,cAAc,EAAE,UAAU,EAAE,GAAG,CAAC,cAAc,CAAC,GAAG,IAAI,CAQnF;AAMD;;;GAGG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,GAAG,CAAC,cAAc,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,CA2If"}

package/dist/bindings/rest.d.ts

@@ -0,0 +1,75 @@
+/**
+ * HTTP+JSON/REST binding — the same canonical core (executor / TaskStore /
+ * model) behind resource-style routes. Per the A2A spec every transport
+ * binding is a functionally equivalent mapping, so this file mirrors
+ * bindings/jsonrpc.ts operation-for-operation: blocking-by-default
+ * SendMessage, Task-first SSE streams, identical TypeBox validation at the
+ * trust boundary. Differences are purely syntactic: operations are HTTP
+ * method + path (gRPC-transcoding-style colon verbs like `:send`), errors are
+ * HTTP status codes carrying the same A2A error codes in a JSON body, and SSE
+ * frames are the bare Task / update objects (no JSON-RPC envelope).
+ *
+ * Residual interop doubts — confirm against a live reference peer, do not
+ * guess-implement:
+ * - Custom-method verb spelling: we serve `/v1/message:send` and
+ *   `/v1/message:stream` (singular `message`, colon verbs per gRPC
+ *   transcoding); a peer may serve plain `/v1/messages` or `/v1/message/send`.
+ * - Subscribe verb: we serve POST `/v1/tasks/{id}:subscribe` (custom methods
+ *   transcode to POST); a peer may expect GET.
+ * - Error body: we send `{ error: { code, message } }` reusing the
+ *   JSON-RPC-aligned A2A error codes; a peer may send google.rpc.Status
+ *   (`{ code, message, details }`) with gRPC-numbered codes.
+ * - ListTasks result envelope: we return `{ tasks: [...] }` (identical to the
+ *   JSON-RPC result); a peer may return a bare array or pagination fields.
+ */
+import type { ServerResponse } from "node:http";
+import { type Static } from "@sinclair/typebox";
+import type { A2aExecutor } from "../executor";
+/**
+ * The HTTP+JSON route table — ONE source for both the server router and the
+ * client transport. `{id}` marks the task-id path parameter.
+ */
+export declare const A2A_REST_ROUTES: {
+    readonly sendMessage: {
+        readonly httpMethod: "POST";
+        readonly path: "/v1/message:send";
+    };
+    readonly sendStreamingMessage: {
+        readonly httpMethod: "POST";
+        readonly path: "/v1/message:stream";
+    };
+    readonly getTask: {
+        readonly httpMethod: "GET";
+        readonly path: "/v1/tasks/{id}";
+    };
+    readonly listTasks: {
+        readonly httpMethod: "GET";
+        readonly path: "/v1/tasks";
+    };
+    readonly cancelTask: {
+        readonly httpMethod: "POST";
+        readonly path: "/v1/tasks/{id}:cancel";
+    };
+    readonly subscribeToTask: {
+        readonly httpMethod: "POST";
+        readonly path: "/v1/tasks/{id}:subscribe";
+    };
+};
+export type A2aRestOperation = keyof typeof A2A_REST_ROUTES;
+/** The JSON error body every non-2xx REST answer carries. */
+export declare const RestErrorBodySchema: import("@sinclair/typebox").TObject<{
+    error: import("@sinclair/typebox").TObject<{
+        code: import("@sinclair/typebox").TNumber;
+        message: import("@sinclair/typebox").TString;
+    }>;
+}>;
+export type RestErrorBody = Static<typeof RestErrorBodySchema>;
+/** HTTP status conveying each A2A error code in the REST binding. */
+export declare function restStatusFor(code: number): number;
+/**
+ * Handle one HTTP+JSON request. `path`/`query` come pre-split from the URL;
+ * `rawBody` is empty for GETs. `sseStreams` registers any stream this request
+ * opens so the server can shut it down on `close()`.
+ */
+export declare function handleRest(executor: A2aExecutor, httpMethod: string, path: string, query: URLSearchParams, rawBody: string, res: ServerResponse, sseStreams: Set<ServerResponse>): Promise<void>;
+//# sourceMappingURL=rest.d.ts.map

package/dist/bindings/rest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.d.ts","sourceRoot":"","sources":["../../src/bindings/rest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAe/C;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;CAOlB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,eAAe,CAAC;AAE5D,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB;;;;;EAE9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAE/D,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAclD;AAuDD;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,WAAW,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,GAAG,CAAC,cAAc,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,CA6Gf"}