@ap3x/a2a 1.0.0 → 2.0.0

package/dist/client.d.ts

@@ -0,0 +1,116 @@
+import { type AgentCard, type Message, type RemoteAgentCard, type Task, type TaskArtifactUpdateEvent, type TaskStatusUpdateEvent } from "./model";
+import type { ListTasksFilter } from "./task-store";
+/** Header carrying the protocol version on every client request. */
+export declare const A2A_VERSION_HEADER = "A2A-Version";
+/** Default per-request timeout: remote agents can be whole orchestrators. */
+export declare const DEFAULT_TIMEOUT_MS: number;
+/** Any client-side protocol failure: HTTP, envelope, validation, RPC error. */
+export declare class A2aClientError extends Error {
+    /** JSON-RPC error code when the server answered with an error object. */
+    readonly code?: number;
+    constructor(message: string, code?: number);
+}
+export interface A2aClientOptions {
+    /** Sent as `Authorization: Bearer <token>` on every request. */
+    bearerToken?: string;
+    /** Injectable fetch (tests); defaults to the global. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout in milliseconds. Default {@link DEFAULT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+export interface SendMessageConfig {
+    /**
+     * When true, ask the server to return the Task snapshot immediately instead
+     * of waiting for the terminal state. Default false — `SendMessage` is
+     * blocking by default per the v1.0.0 spec.
+     */
+    returnImmediately?: boolean;
+}
+export type A2aStreamFrame = Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent | Message;
+/**
+ * Whether a stream frame is the Task object. Discriminates structurally: our
+ * Task model carries no `kind`, but a peer that tags Tasks with `kind: "task"`
+ * (0.2.x style) is accepted too — a residual v1.0 doubt, see the binding.
+ * A kindless frame is a Task unless it carries a Message's `messageId`.
+ */
+export declare function isTaskFrame(frame: A2aStreamFrame): frame is Task;
+/**
+ * Whether a stream frame is a bare Message (a peer answering directly with no
+ * task). Only Message frames carry a top-level `messageId`, so the check also
+ * accepts a peer that omits `kind: "message"`.
+ */
+export declare function isMessageFrame(frame: A2aStreamFrame): frame is Message;
+/** Whether a stream frame is a TaskStatusUpdateEvent. */
+export declare function isStatusUpdateFrame(frame: A2aStreamFrame): frame is TaskStatusUpdateEvent;
+/** The transports this client can negotiate, in preference order. */
+export type A2aClientTransport = "JSONRPC" | "HTTP+JSON" | "GRPC";
+/**
+ * Normalize a LIBERALLY-parsed remote card into the canonical
+ * {@link AgentCard}. The reference SDK (0.3.x) exposes the endpoint via
+ * top-level `url` + `preferredTransport` (plus `additionalInterfaces`); AP3X
+ * cards use `interfaces`. Both collapse into one deduplicated `interfaces`
+ * list (top-level endpoint first — it is the peer's declared preference);
+ * transports this client cannot speak are dropped. Fields we model loosely
+ * (skills, securitySchemes, provider) are carried over only when they match
+ * our schemas — a peer's exotic security scheme must not sink the connect.
+ */
+export declare function normalizeRemoteCard(card: RemoteAgentCard): AgentCard;
+export declare class A2aClient {
+    /** The Agent Card fetched (once) at connect time. */
+    readonly card: AgentCard;
+    /** The transport negotiated from the card (JSONRPC preferred). */
+    readonly transport: A2aClientTransport;
+    private readonly endpoint;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly bearerToken?;
+    private nextId;
+    /** Present exactly when `transport` is GRPC (lazy-loaded at connect time). */
+    private grpcTransport?;
+    private constructor();
+    /**
+     * Fetch + validate the Agent Card from the well-known path, negotiate the
+     * transport (JSONRPC preferred, then HTTP+JSON, then GRPC as a last resort),
+     * and return a connected client.
+     */
+    static connect(baseUrl: string, options?: A2aClientOptions): Promise<A2aClient>;
+    /** Release transport resources (the gRPC channel; HTTP needs nothing). */
+    close(): void;
+    /**
+     * `SendMessage` — blocking by default; returns the (validated) Task
+     * snapshot, or a bare Message when the peer's executor answered directly
+     * without creating a task (a Task has `status`, a Message does not).
+     *
+     * `signal` cancels the in-flight HTTP request (combined with the per-request
+     * timeout). The gRPC transport relies on its own deadline — best-effort.
+     */
+    sendMessage(message: Message, config?: SendMessageConfig, signal?: AbortSignal): Promise<Task | Message>;
+    /** `SendStreamingMessage` — SSE: the Task object first, then update events. */
+    sendStreamingMessage(message: Message, signal?: AbortSignal): AsyncGenerator<A2aStreamFrame>;
+    /** `GetTask`. */
+    getTask(id: string, signal?: AbortSignal): Promise<Task>;
+    /** `ListTasks`. */
+    listTasks(filter?: ListTasksFilter): Promise<Task[]>;
+    /** `CancelTask`. */
+    cancelTask(id: string): Promise<Task>;
+    /** `SubscribeToTask` — SSE: the Task snapshot first, then update events. */
+    subscribeToTask(id: string): AsyncGenerator<A2aStreamFrame>;
+    private headers;
+    /** Per-request timeout signal, optionally combined with a caller's signal. */
+    private requestSignal;
+    private post;
+    private rpc;
+    /** Validate a JSON-RPC response envelope; throw the server's error typed. */
+    private unwrap;
+    private expect;
+    private rpcSse;
+    private parseSseFrame;
+    /** The raw `data:` payloads of an SSE response — shared by both transports. */
+    private sseData;
+    private restRequest;
+    /** Map a non-2xx REST answer to a typed error carrying the A2A code. */
+    private restErrorFrom;
+    private restJson;
+    private restSse;
+}
+//# 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":"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"}

package/dist/executor.d.ts

@@ -0,0 +1,91 @@
+/**
+ * A2aExecutor: fulfills A2A tasks by running ANY {@link AgentBackend}.
+ *
+ * The executor is the SOLE WRITER of TaskStore tasks — every public read
+ * returns a deep copy so callers (HTTP bindings, tests) can never mutate
+ * around the state machine. All runs route through the shared agent-core
+ * limiter, so a request flood cannot fan out unbounded. Deterministic: the
+ * clock is injected and threaded into the store.
+ */
+import { type AgentBackend, type AgentMessage } from "@ap3x/agent-core";
+import { type Message, type Task } from "./model";
+import { type ListTasksFilter, type TaskSubscriber } from "./task-store";
+export interface A2aExecutorOptions {
+    /** Injected clock (epoch millis). */
+    now: () => number;
+    /** Cap on concurrently running backend tasks. Default: max(4, availableParallelism()). */
+    maxConcurrentTasks?: number;
+    /** Retain at most this many TERMINAL tasks (see {@link TaskStore}). Default: unbounded. */
+    maxRetainedTasks?: number;
+    /**
+     * Retain at most this many contextId transcripts, evicting the
+     * LEAST-RECENTLY-USED context beyond the cap (an active multi-turn thread is
+     * never evicted just for being old). An evicted context loses only its prior
+     * conversational transcript — the next message on it starts fresh; no error,
+     * no task loss. Default: unbounded — long-lived servers should set it.
+     */
+    maxRetainedContexts?: number;
+}
+export interface SendMessageOptions {
+    /** When true, resolve only once the task reaches a terminal state. Default false. */
+    blocking?: boolean;
+    /**
+     * Fired with the Task snapshot BEFORE the run starts — the spec-mandated
+     * first frame of a stream (the stream MUST begin with the Task object).
+     */
+    onTask?: (task: Task) => void;
+    /**
+     * Status subscriber attached BEFORE the run starts, so a streaming consumer
+     * can never miss an event.
+     */
+    onEvent?: TaskSubscriber;
+}
+/** Concatenated text rendering of an A2A message's parts. */
+export declare function messageText(message: Message): string;
+/** Concatenated text of an agent-core transcript message. */
+export declare function agentMessageText(message: AgentMessage): string;
+export declare class A2aExecutor {
+    private readonly backend;
+    private readonly store;
+    private readonly now;
+    private readonly limit;
+    /**
+     * contextId -> transcript so a follow-up message keeps its conversational
+     * thread. Access-ordered (delete + re-set on touch) so Map insertion order
+     * doubles as LRU order for {@link maxRetainedContexts} eviction.
+     */
+    private readonly transcripts;
+    private readonly maxRetainedContexts?;
+    private readonly aborts;
+    constructor(backend: AgentBackend, options: A2aExecutorOptions);
+    /** Whether the wrapped backend supports incremental streaming. */
+    get streaming(): boolean;
+    /** Accept an inbound message: create a task and run the backend against it. */
+    sendMessage(message: Message, options?: SendMessageOptions): Promise<Task>;
+    /** Deep-copied task lookup (undefined when unknown). */
+    getTask(id: string): Task | undefined;
+    /** Deep-copied task listing. */
+    listTasks(filter?: ListTasksFilter): Task[];
+    /**
+     * Cancel a task: best-effort abort of the underlying run + store cancel.
+     * A backend without `abort` still cancels — the guarded terminal write in
+     * {@link execute} discards the late result. Throws TaskNotFoundError /
+     * IllegalTaskTransitionError for unknown / already-terminal tasks.
+     */
+    cancel(taskId: string): Task;
+    /** Subscribe to a task's status updates; returns an unsubscribe function. */
+    subscribe(taskId: string, fn: TaskSubscriber): () => void;
+    /** LRU read: touching a context moves it to the back of the eviction order. */
+    private recallTranscript;
+    /** LRU write: (re-)insert at the back, then evict the oldest beyond the cap. */
+    private retainTranscript;
+    private snapshot;
+    private agentMessage;
+    /**
+     * Terminal write, guarded: a task canceled mid-run stays canceled — the
+     * store's terminal-state rejection is caught and the late result discarded.
+     */
+    private finish;
+    private execute;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,YAAY,EAMlB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,KAAK,OAAO,EAAa,KAAK,IAAI,EAA8B,MAAM,SAAS,CAAC;AACzF,OAAO,EAEL,KAAK,eAAe,EAEpB,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,0FAA0F;IAC1F,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2FAA2F;IAC3F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CASpD;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAe9D;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0C;IAChE;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;IACjE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;gBAEjD,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,kBAAkB;IAe9D,kEAAkE;IAClE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,+EAA+E;IACzE,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBpF,wDAAwD;IACxD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC,gCAAgC;IAChC,SAAS,CAAC,MAAM,GAAE,eAAoB,GAAG,IAAI,EAAE;IAI/C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO5B,6EAA6E;IAC7E,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,MAAM,IAAI;IAIzD,+EAA+E;IAC/E,OAAO,CAAC,gBAAgB;IASxB,gFAAgF;IAChF,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,YAAY;IAKpB;;;OAGG;IACH,OAAO,CAAC,MAAM;YAYA,OAAO;CAyFtB"}