@nifrajs/a2a 3.2.0

package/README.md

@@ -0,0 +1,79 @@
+# @nifrajs/a2a
+
+Mount a nifra agent as an [Agent2Agent (A2A)](https://a2a-protocol.org) protocol server. The agent card is served on GET, the A2A 1.0 JSON-RPC binding on POST: `SendMessage` runs one bounded agent turn, `SendStreamingMessage` streams step evidence over SSE, `GetTask` projects the stored turn state.
+
+A protocol bridge over [`@nifrajs/agent`](../agent) - the request body reuses core's single bounded, prototype-guarded trust boundary, and the model, durable state store, and approval transport are injected per request through the same `ports` factory `mountAgent` uses. Dependency-free beyond the two nifra peers.
+
+## Install
+
+```bash
+bun add @nifrajs/a2a @nifrajs/agent
+```
+
+## Mount
+
+```ts
+import { server } from "@nifrajs/core"
+import { mountA2A } from "@nifrajs/a2a"
+import { agent } from "./agent" // an AgentDefinition
+
+const app = server()
+mountA2A(app, {
+  agent,
+  card: { url: "https://api.example.com/a2a", version: "1.0.0" },
+  ports: (c) => ({
+    model: myModelPort,        // scope to the request subject
+    capabilities: ["search.read"],
+    state: myStateStore,       // required for GetTask and resume
+  }),
+})
+// GET  /.well-known/agent-card.json  - the agent card
+// POST /a2a                          - SendMessage | SendStreamingMessage | GetTask
+```
+
+## Task mapping
+
+One A2A task is one agent turn: `taskId` is the runner's `turnId`.
+
+| Run result | Task state |
+| --- | --- |
+| completed with output | `TASK_STATE_COMPLETED` + an `output` artifact |
+| completed with a typed error | `TASK_STATE_FAILED` (error in `metadata`) |
+| suspended (approval, budget, model, max turns) | `TASK_STATE_INPUT_REQUIRED` |
+| suspended (cancelled) | `TASK_STATE_CANCELED` |
+
+Agent input is `message.metadata.input` when present, otherwise the first `text` part. Structured output returns as a `text` part carrying JSON.
+
+## Human-in-the-loop resume
+
+A suspended task's status message carries the pending continuation in `metadata`. Send it back to continue the same task - the runtime keeps state token-only, so a suspended tool's input must be replayed in `continuation.input`:
+
+```jsonc
+{
+  "jsonrpc": "2.0", "id": 2, "method": "SendMessage",
+  "params": {
+    "message": {
+      "messageId": "m2", "role": "ROLE_USER", "parts": [],
+      "taskId": "<task id from the suspension>",
+      "metadata": {
+        "input": { "prompt": "go" },
+        "resume": {
+          "continuation": { "kind": "approval", "tool": "search.read", "effectId": "…", "input": { "q": "…" } },
+          "approval": { "granted": true }
+        }
+      }
+    }
+  }
+}
+```
+
+Cross-request registries (cancellation, subscription fan-out, push notifications) are deliberately out of scope for the stateless seam; those spec methods answer `UnsupportedOperationError` (-32004).
+
+The seam performs no authentication or authorization - wrap it with your app's route guards and scope every port in `ports(c)` to the caller.
+
+## Docs
+
+Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
+
+For AI agents, see [`LLM.md`](./LLM.md) and the full corpus
+[`../../llms-full.txt`](../../llms-full.txt).

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `@nifrajs/a2a` - mount a nifra agent as an Agent2Agent (A2A) protocol server.
+ *
+ * The package is a protocol bridge over the `@nifrajs/agent` runner, mirroring the `mountAgent`
+ * seam: HTTP in, the bounded runner in the middle, A2A JSON-RPC out. The request body is read
+ * through core's single bounded, proto-guarded framing lane (`@nifrajs/core/edge-kit`); the model,
+ * durable state store, and approval transport arrive through a per-request `ports` factory and never
+ * live in this package.
+ *
+ * Wire contract (A2A protocol version 1.0, JSON-RPC binding):
+ * - `GET {cardPath}` (default `/.well-known/agent-card.json`) -> the agent card.
+ * - `POST {path}` (default `/a2a`) -> a JSON-RPC 2.0 request:
+ *   - `SendMessage` runs one turn and returns `{ task }` with a terminal or interrupted status.
+ *   - `SendStreamingMessage` responds `text/event-stream`; each SSE `data:` field is a complete
+ *     JSON-RPC response whose result is `{ statusUpdate }` per step-evidence item, then
+ *     `{ artifactUpdate }` for a produced output, then a final `{ statusUpdate }` with
+ *     `final: true`.
+ *   - `GetTask` projects the stored turn state for a task id (requires `ports.state`).
+ *   - Every other spec method returns `UnsupportedOperationError` (-32004): the seam is stateless
+ *     per request, so cross-request cancellation and subscription registries belong to the caller.
+ * - A task is one agent turn: `taskId` == the runner's `turnId`. A suspended run surfaces as
+ *   `TASK_STATE_INPUT_REQUIRED` whose status message carries the pending continuation in
+ *   `metadata`. To resume, send the continuation back via `message.taskId` +
+ *   `message.metadata.resume` (`{ continuation, approval? }`); the runtime keeps state token-only,
+ *   so a suspended tool's input must be replayed in `continuation.input`.
+ * - Agent input is `message.metadata.input` when present, otherwise the first `text` part.
+ *   Structured output is returned as a `text` part carrying JSON.
+ * - The seam performs no authentication or authorization. Wrap it with the app's own route guards,
+ *   and scope the store/model returned by `ports` to the caller.
+ */
+import { type AgentDefinition, type AgentPorts } from "@nifrajs/agent";
+import { type ProtoPoisoning } from "@nifrajs/core/edge-kit";
+import type { StandardSchemaV1 } from "@nifrajs/core/schema";
+export declare const A2A_PROTOCOL_VERSION = "1.0";
+export declare const AGENT_CARD_WELL_KNOWN_PATH = "/.well-known/agent-card.json";
+export declare const A2A_ERROR_CODES: {
+    readonly parseError: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internalError: -32603;
+    readonly taskNotFound: -32001;
+    readonly unsupportedOperation: -32004;
+};
+export type A2ATaskState = "TASK_STATE_SUBMITTED" | "TASK_STATE_WORKING" | "TASK_STATE_INPUT_REQUIRED" | "TASK_STATE_COMPLETED" | "TASK_STATE_FAILED" | "TASK_STATE_CANCELED";
+export interface A2AAgentSkill {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly tags: readonly string[];
+}
+export interface A2AAgentCard {
+    readonly protocolVersion: string;
+    readonly name: string;
+    readonly description: string;
+    readonly url: string;
+    readonly version: string;
+    readonly capabilities: {
+        readonly streaming: boolean;
+    };
+    readonly defaultInputModes: readonly string[];
+    readonly defaultOutputModes: readonly string[];
+    readonly skills: readonly A2AAgentSkill[];
+}
+/** Caller-supplied card identity; everything else derives from the agent definition. */
+export interface A2ACardInfo {
+    /** Public URL of the JSON-RPC endpoint, as advertised to A2A clients. */
+    readonly url: string;
+    /** Version of the exposed agent (the deployment's, not the protocol's). */
+    readonly version: string;
+    readonly name?: string;
+    readonly description?: string;
+}
+/** The structural slice of a route context the seam needs. */
+export interface A2ARouteContext {
+    readonly req: Request;
+}
+/** The structural slice of a nifra server `mountA2A` needs. */
+export interface A2AMountableApp {
+    get(path: string, handler: (c: A2ARouteContext) => Response | Promise<Response>): unknown;
+    post(path: string, handler: (c: A2ARouteContext) => Response | Promise<Response>): unknown;
+}
+export interface MountA2AOptions<InputSchema extends StandardSchemaV1, OutputSchema extends StandardSchemaV1> {
+    readonly agent: AgentDefinition<InputSchema, OutputSchema>;
+    readonly card: A2ACardInfo;
+    /** JSON-RPC endpoint path. Default `/a2a`. */
+    readonly path?: string;
+    /** Agent card path. Default `/.well-known/agent-card.json`. */
+    readonly cardPath?: string;
+    /** Bounded run length passed to the runner. */
+    readonly maxTurns?: number;
+    /** Maximum request body size in bytes. Default 1_000_000. */
+    readonly maxBodyBytes?: number;
+    /** Prototype-poisoning policy for the framing lane. Default `"reject"`. */
+    readonly protoPoisoning?: ProtoPoisoning;
+    /**
+     * Build the ports for one request - the model, durable state store, approval transport,
+     * capabilities, and budgets. Receives the route context so the caller can scope every port to the
+     * request subject.
+     */
+    readonly ports: (c: A2ARouteContext) => AgentPorts | Promise<AgentPorts>;
+}
+/** Derive a spec-shaped agent card from the agent definition plus the caller's identity fields. */
+export declare function agentCard<InputSchema extends StandardSchemaV1, OutputSchema extends StandardSchemaV1>(agent: AgentDefinition<InputSchema, OutputSchema>, info: A2ACardInfo): A2AAgentCard;
+/** Mount an agent as an A2A server: the agent card on GET, the JSON-RPC binding on POST. */
+export declare function mountA2A<InputSchema extends StandardSchemaV1, OutputSchema extends StandardSchemaV1>(app: A2AMountableApp, options: MountA2AOptions<InputSchema, OutputSchema>): void;
+//# 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":"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"}

package/dist/index.js

@@ -0,0 +1,369 @@
+/**
+ * `@nifrajs/a2a` - mount a nifra agent as an Agent2Agent (A2A) protocol server.
+ *
+ * The package is a protocol bridge over the `@nifrajs/agent` runner, mirroring the `mountAgent`
+ * seam: HTTP in, the bounded runner in the middle, A2A JSON-RPC out. The request body is read
+ * through core's single bounded, proto-guarded framing lane (`@nifrajs/core/edge-kit`); the model,
+ * durable state store, and approval transport arrive through a per-request `ports` factory and never
+ * live in this package.
+ *
+ * Wire contract (A2A protocol version 1.0, JSON-RPC binding):
+ * - `GET {cardPath}` (default `/.well-known/agent-card.json`) -> the agent card.
+ * - `POST {path}` (default `/a2a`) -> a JSON-RPC 2.0 request:
+ *   - `SendMessage` runs one turn and returns `{ task }` with a terminal or interrupted status.
+ *   - `SendStreamingMessage` responds `text/event-stream`; each SSE `data:` field is a complete
+ *     JSON-RPC response whose result is `{ statusUpdate }` per step-evidence item, then
+ *     `{ artifactUpdate }` for a produced output, then a final `{ statusUpdate }` with
+ *     `final: true`.
+ *   - `GetTask` projects the stored turn state for a task id (requires `ports.state`).
+ *   - Every other spec method returns `UnsupportedOperationError` (-32004): the seam is stateless
+ *     per request, so cross-request cancellation and subscription registries belong to the caller.
+ * - A task is one agent turn: `taskId` == the runner's `turnId`. A suspended run surfaces as
+ *   `TASK_STATE_INPUT_REQUIRED` whose status message carries the pending continuation in
+ *   `metadata`. To resume, send the continuation back via `message.taskId` +
+ *   `message.metadata.resume` (`{ continuation, approval? }`); the runtime keeps state token-only,
+ *   so a suspended tool's input must be replayed in `continuation.input`.
+ * - Agent input is `message.metadata.input` when present, otherwise the first `text` part.
+ *   Structured output is returned as a `text` part carrying JSON.
+ * - The seam performs no authentication or authorization. Wrap it with the app's own route guards,
+ *   and scope the store/model returned by `ports` to the caller.
+ */
+import { combineAgentTelemetry, createAgentState, resumeAgent, runAgent, } from "@nifrajs/agent";
+import { createAgentEvidenceStream } from "@nifrajs/agent/events";
+import { EMPTY_RESPONSE_CONTROLS, readBodyFramed, toResponse, } from "@nifrajs/core/edge-kit";
+export const A2A_PROTOCOL_VERSION = "1.0";
+export const AGENT_CARD_WELL_KNOWN_PATH = "/.well-known/agent-card.json";
+const DEFAULT_PATH = "/a2a";
+const DEFAULT_MAX_BODY_BYTES = 1_000_000;
+const PENDING_KINDS = ["approval", "budget", "model", "cancelled"];
+const TURN_ID_PATTERN = /^[a-zA-Z0-9._:-]{1,128}$/;
+// JSON-RPC 2.0 standard codes plus the A2A-specific range.
+export const A2A_ERROR_CODES = {
+    parseError: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internalError: -32603,
+    taskNotFound: -32001,
+    unsupportedOperation: -32004,
+};
+/** Derive a spec-shaped agent card from the agent definition plus the caller's identity fields. */
+export function agentCard(agent, info) {
+    return {
+        protocolVersion: A2A_PROTOCOL_VERSION,
+        name: info.name ?? agent.name,
+        description: info.description ?? agent.instruction,
+        url: info.url,
+        version: info.version,
+        capabilities: { streaming: true },
+        defaultInputModes: ["application/json", "text/plain"],
+        defaultOutputModes: ["application/json", "text/plain"],
+        skills: agent.tools.map((tool) => ({
+            id: tool.name,
+            name: tool.name,
+            description: tool.description,
+            tags: [tool.capability],
+        })),
+    };
+}
+/** Mount an agent as an A2A server: the agent card on GET, the JSON-RPC binding on POST. */
+export function mountA2A(app, options) {
+    const path = options.path ?? DEFAULT_PATH;
+    const cardPath = options.cardPath ?? AGENT_CARD_WELL_KNOWN_PATH;
+    const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const proto = options.protoPoisoning ?? "reject";
+    const runOptions = options.maxTurns === undefined ? {} : { maxTurns: options.maxTurns };
+    const card = agentCard(options.agent, options.card);
+    app.get(cardPath, () => jsonResponse(200, card));
+    app.post(path, (c) => readBodyFramed(c.req, maxBytes, proto, (parsed) => dispatch(c, parsed, options, runOptions), (rejection) => render(rejection), () => rpcErrorResponse(null, A2A_ERROR_CODES.parseError, "parse_error")).catch(() => rpcErrorResponse(null, A2A_ERROR_CODES.internalError, "internal_error")));
+}
+async function dispatch(c, parsed, options, runOptions) {
+    const request = asRecord(parsed);
+    const id = request === undefined ? undefined : asRpcId(request.id);
+    if (request === undefined || request.jsonrpc !== "2.0" || id === undefined)
+        return rpcErrorResponse(null, A2A_ERROR_CODES.invalidRequest, "invalid_request");
+    const method = request.method;
+    if (typeof method !== "string")
+        return rpcErrorResponse(id, A2A_ERROR_CODES.invalidRequest, "invalid_request");
+    const params = asRecord(request.params) ?? {};
+    switch (method) {
+        case "SendMessage":
+        case "SendStreamingMessage": {
+            const turn = prepareTurn(params);
+            if ("error" in turn)
+                return rpcErrorResponse(id, turn.error.code, turn.error.message);
+            const basePorts = await options.ports(c);
+            const start = (telemetry) => {
+                // Compose rather than replace: the SSE evidence stream must not displace a telemetry
+                // port the caller injected through `ports`.
+                const combined = combineAgentTelemetry(basePorts.telemetry, telemetry);
+                const ports = combined === undefined ? basePorts : { ...basePorts, telemetry: combined };
+                if (turn.resume !== undefined) {
+                    return resumeAgent(options.agent, turn.turnId, { value: turn.input, resume: turn.resume }, ports, runOptions);
+                }
+                return runAgent(options.agent, { value: turn.input }, ports, {
+                    ...runOptions,
+                    state: createAgentState(turn.turnId),
+                });
+            };
+            if (method === "SendMessage") {
+                try {
+                    return rpcResultResponse(id, { task: projectTask(turn.turnId, await start()) });
+                }
+                catch {
+                    return rpcErrorResponse(id, A2A_ERROR_CODES.taskNotFound, "task_not_resumable");
+                }
+            }
+            return streamingResponse(id, turn.turnId, start);
+        }
+        case "GetTask": {
+            const taskId = typeof params.id === "string" ? params.id : undefined;
+            if (taskId === undefined)
+                return rpcErrorResponse(id, A2A_ERROR_CODES.invalidParams, "invalid_params");
+            const basePorts = await options.ports(c);
+            const state = await basePorts.state?.load(taskId);
+            if (state === undefined)
+                return rpcErrorResponse(id, A2A_ERROR_CODES.taskNotFound, "task_not_found");
+            return rpcResultResponse(id, { task: projectStoredTask(state) });
+        }
+        case "ListTasks":
+        case "CancelTask":
+        case "SubscribeToTask":
+        case "CreateTaskPushNotificationConfig":
+        case "GetTaskPushNotificationConfig":
+        case "ListTaskPushNotificationConfigs":
+        case "DeleteTaskPushNotificationConfig":
+        case "GetExtendedAgentCard":
+            return rpcErrorResponse(id, A2A_ERROR_CODES.unsupportedOperation, "unsupported_operation");
+        default:
+            return rpcErrorResponse(id, A2A_ERROR_CODES.methodNotFound, "method_not_found");
+    }
+}
+function prepareTurn(params) {
+    const message = asRecord(params.message);
+    if (message === undefined)
+        return { error: { code: A2A_ERROR_CODES.invalidParams, message: "invalid_params" } };
+    const metadata = asRecord(message.metadata) ?? {};
+    const taskId = typeof message.taskId === "string" ? message.taskId : undefined;
+    const resume = parseResume(metadata.resume);
+    if (taskId !== undefined && !TURN_ID_PATTERN.test(taskId))
+        return { error: { code: A2A_ERROR_CODES.invalidParams, message: "invalid_task_id" } };
+    // A message that names a task must carry the continuation: the runtime keeps state token-only,
+    // so there is nothing to continue from without it.
+    if (taskId !== undefined && resume === undefined)
+        return { error: { code: A2A_ERROR_CODES.invalidParams, message: "resume_metadata_required" } };
+    if (resume !== undefined && taskId === undefined)
+        return { error: { code: A2A_ERROR_CODES.invalidParams, message: "task_id_required" } };
+    return {
+        turnId: taskId ?? crypto.randomUUID(),
+        input: Object.hasOwn(metadata, "input") ? metadata.input : firstTextPart(message.parts),
+        resume,
+    };
+}
+function firstTextPart(parts) {
+    if (!Array.isArray(parts))
+        return undefined;
+    for (const part of parts) {
+        const record = asRecord(part);
+        if (record !== undefined && typeof record.text === "string")
+            return record.text;
+    }
+    return undefined;
+}
+function streamingResponse(id, turnId, start) {
+    const stream = createAgentEvidenceStream();
+    const body = new ReadableStream({
+        async start(controller) {
+            const encoder = new TextEncoder();
+            const send = (payload) => {
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(payload)}\n\n`));
+            };
+            const run = start(stream);
+            // The evidence stream must terminate whether the run resolves or throws, or the `for await`
+            // below would hang; the run result (or the error) is still reported in-band after it drains.
+            run
+                .then(() => { }, () => { })
+                .finally(() => stream.complete());
+            try {
+                for await (const evidence of stream) {
+                    send(rpcResult(id, {
+                        statusUpdate: {
+                            taskId: turnId,
+                            contextId: turnId,
+                            status: { state: "TASK_STATE_WORKING" },
+                            final: false,
+                            metadata: { evidence },
+                        },
+                    }));
+                }
+                const result = await run;
+                if (result.status === "completed" && result.error === undefined) {
+                    send(rpcResult(id, {
+                        artifactUpdate: {
+                            taskId: turnId,
+                            contextId: turnId,
+                            artifact: outputArtifact(turnId, result.output),
+                            lastChunk: true,
+                        },
+                    }));
+                }
+                const task = projectTask(turnId, result);
+                send(rpcResult(id, {
+                    statusUpdate: {
+                        taskId: turnId,
+                        contextId: turnId,
+                        status: task.status,
+                        final: true,
+                        ...(task.metadata === undefined ? {} : { metadata: task.metadata }),
+                    },
+                }));
+            }
+            catch {
+                send(rpcError(id, A2A_ERROR_CODES.internalError, "run_failed"));
+            }
+            finally {
+                controller.close();
+            }
+        },
+    });
+    return new Response(body, {
+        status: 200,
+        headers: {
+            "content-type": "text/event-stream; charset=utf-8",
+            "cache-control": "no-cache, no-transform",
+            connection: "keep-alive",
+        },
+    });
+}
+/** Project a run result onto the A2A task shape. Evidence is token-only by design, so it passes through. */
+function projectTask(turnId, result) {
+    const base = { id: turnId, contextId: turnId };
+    if (result.status === "completed") {
+        if (result.error !== undefined) {
+            return {
+                ...base,
+                status: { state: "TASK_STATE_FAILED" },
+                metadata: { evidence: result.evidence, error: result.error },
+            };
+        }
+        return {
+            ...base,
+            status: { state: "TASK_STATE_COMPLETED" },
+            artifacts: [outputArtifact(turnId, result.output)],
+            metadata: { evidence: result.evidence },
+        };
+    }
+    if (result.status === "suspended") {
+        const state = result.reason === "cancelled" ? "TASK_STATE_CANCELED" : "TASK_STATE_INPUT_REQUIRED";
+        return {
+            ...base,
+            status: {
+                state,
+                message: {
+                    messageId: `${turnId}:pending`,
+                    taskId: turnId,
+                    role: "ROLE_AGENT",
+                    parts: [],
+                    metadata: { reason: result.reason, continuation: result.pending },
+                },
+            },
+            metadata: { evidence: result.evidence },
+        };
+    }
+    // `continue` never escapes the run loop; project it defensively as still-working.
+    return {
+        ...base,
+        status: { state: "TASK_STATE_WORKING" },
+        metadata: { evidence: result.evidence },
+    };
+}
+/** Project stored turn state (GetTask). Stored state cannot distinguish a failed completion. */
+function projectStoredTask(state) {
+    const taskState = state.status === "completed"
+        ? "TASK_STATE_COMPLETED"
+        : state.status === "suspended"
+            ? "TASK_STATE_INPUT_REQUIRED"
+            : "TASK_STATE_WORKING";
+    return {
+        id: state.turnId,
+        contextId: state.turnId,
+        status: { state: taskState },
+        metadata: {
+            evidence: state.evidence,
+            ...(state.pending === undefined ? {} : { continuation: state.pending }),
+        },
+    };
+}
+function outputArtifact(turnId, output) {
+    return {
+        artifactId: `${turnId}:output`,
+        name: "output",
+        parts: [typeof output === "string" ? { text: output } : { text: JSON.stringify(output) }],
+    };
+}
+function parseResume(raw) {
+    const record = asRecord(raw);
+    if (record === undefined)
+        return undefined;
+    const continuation = asRecord(record.continuation);
+    if (continuation === undefined)
+        return undefined;
+    const kind = continuation.kind;
+    if (typeof kind !== "string" || !PENDING_KINDS.includes(kind))
+        return undefined;
+    if (typeof continuation.effectId !== "string")
+        return undefined;
+    if (continuation.tool !== undefined && typeof continuation.tool !== "string")
+        return undefined;
+    const approval = asRecord(record.approval);
+    return {
+        continuation: {
+            kind: kind,
+            ...(continuation.tool === undefined ? {} : { tool: continuation.tool }),
+            ...(Object.hasOwn(continuation, "input") ? { input: continuation.input } : {}),
+            effectId: continuation.effectId,
+        },
+        ...(approval !== undefined && typeof approval.granted === "boolean"
+            ? {
+                approval: {
+                    granted: approval.granted,
+                    ...(typeof approval.reason === "string" ? { reason: approval.reason } : {}),
+                },
+            }
+            : {}),
+    };
+}
+function rpcResult(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function rpcError(id, code, message) {
+    return { jsonrpc: "2.0", id, error: { code, message } };
+}
+function rpcResultResponse(id, result) {
+    return jsonResponse(200, rpcResult(id, result));
+}
+function rpcErrorResponse(id, code, message) {
+    return jsonResponse(200, rpcError(id, code, message));
+}
+function asRpcId(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    return undefined;
+}
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8" },
+    });
+}
+function render(response) {
+    return response instanceof Response ? response : toResponse(response, EMPTY_RESPONSE_CONTROLS);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@nifrajs/a2a",
+  "version": "3.2.0",
+  "description": "Mount a nifra agent as an Agent2Agent (A2A) protocol server - the agent card on GET, the A2A 1.0 JSON-RPC binding on POST with SendMessage, streaming SendStreamingMessage over SSE, and GetTask projected from the runner's turn state. A protocol bridge over @nifrajs/agent; the model, state store, and approval transport stay injected per request.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "a2a",
+    "agent2agent",
+    "agents",
+    "json-rpc",
+    "sse",
+    "interop"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "peerDependencies": {
+    "@nifrajs/agent": "^3.2.0",
+    "@nifrajs/core": "^3.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@nifrajs/core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nifrajs/agent": "workspace:*",
+    "@nifrajs/core": "workspace:*",
+    "@nifrajs/schema": "workspace:*"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/a2a"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/index.ts

@@ -0,0 +1,528 @@
+/**
+ * `@nifrajs/a2a` - mount a nifra agent as an Agent2Agent (A2A) protocol server.
+ *
+ * The package is a protocol bridge over the `@nifrajs/agent` runner, mirroring the `mountAgent`
+ * seam: HTTP in, the bounded runner in the middle, A2A JSON-RPC out. The request body is read
+ * through core's single bounded, proto-guarded framing lane (`@nifrajs/core/edge-kit`); the model,
+ * durable state store, and approval transport arrive through a per-request `ports` factory and never
+ * live in this package.
+ *
+ * Wire contract (A2A protocol version 1.0, JSON-RPC binding):
+ * - `GET {cardPath}` (default `/.well-known/agent-card.json`) -> the agent card.
+ * - `POST {path}` (default `/a2a`) -> a JSON-RPC 2.0 request:
+ *   - `SendMessage` runs one turn and returns `{ task }` with a terminal or interrupted status.
+ *   - `SendStreamingMessage` responds `text/event-stream`; each SSE `data:` field is a complete
+ *     JSON-RPC response whose result is `{ statusUpdate }` per step-evidence item, then
+ *     `{ artifactUpdate }` for a produced output, then a final `{ statusUpdate }` with
+ *     `final: true`.
+ *   - `GetTask` projects the stored turn state for a task id (requires `ports.state`).
+ *   - Every other spec method returns `UnsupportedOperationError` (-32004): the seam is stateless
+ *     per request, so cross-request cancellation and subscription registries belong to the caller.
+ * - A task is one agent turn: `taskId` == the runner's `turnId`. A suspended run surfaces as
+ *   `TASK_STATE_INPUT_REQUIRED` whose status message carries the pending continuation in
+ *   `metadata`. To resume, send the continuation back via `message.taskId` +
+ *   `message.metadata.resume` (`{ continuation, approval? }`); the runtime keeps state token-only,
+ *   so a suspended tool's input must be replayed in `continuation.input`.
+ * - Agent input is `message.metadata.input` when present, otherwise the first `text` part.
+ *   Structured output is returned as a `text` part carrying JSON.
+ * - The seam performs no authentication or authorization. Wrap it with the app's own route guards,
+ *   and scope the store/model returned by `ports` to the caller.
+ */
+
+import {
+  type AgentDefinition,
+  type AgentPendingKind,
+  type AgentPorts,
+  type AgentRunResult,
+  type AgentTurnInput,
+  type AgentTurnState,
+  combineAgentTelemetry,
+  createAgentState,
+  resumeAgent,
+  runAgent,
+} from "@nifrajs/agent"
+import { createAgentEvidenceStream } from "@nifrajs/agent/events"
+import {
+  EMPTY_RESPONSE_CONTROLS,
+  type ProtoPoisoning,
+  type ResponseResult,
+  readBodyFramed,
+  toResponse,
+} from "@nifrajs/core/edge-kit"
+import type { StandardSchemaV1 } from "@nifrajs/core/schema"
+
+export const A2A_PROTOCOL_VERSION = "1.0"
+export const AGENT_CARD_WELL_KNOWN_PATH = "/.well-known/agent-card.json"
+
+const DEFAULT_PATH = "/a2a"
+const DEFAULT_MAX_BODY_BYTES = 1_000_000
+const PENDING_KINDS: readonly AgentPendingKind[] = ["approval", "budget", "model", "cancelled"]
+const TURN_ID_PATTERN = /^[a-zA-Z0-9._:-]{1,128}$/
+
+// JSON-RPC 2.0 standard codes plus the A2A-specific range.
+export const A2A_ERROR_CODES = {
+  parseError: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internalError: -32603,
+  taskNotFound: -32001,
+  unsupportedOperation: -32004,
+} as const
+
+export type A2ATaskState =
+  | "TASK_STATE_SUBMITTED"
+  | "TASK_STATE_WORKING"
+  | "TASK_STATE_INPUT_REQUIRED"
+  | "TASK_STATE_COMPLETED"
+  | "TASK_STATE_FAILED"
+  | "TASK_STATE_CANCELED"
+
+export interface A2AAgentSkill {
+  readonly id: string
+  readonly name: string
+  readonly description: string
+  readonly tags: readonly string[]
+}
+
+export interface A2AAgentCard {
+  readonly protocolVersion: string
+  readonly name: string
+  readonly description: string
+  readonly url: string
+  readonly version: string
+  readonly capabilities: { readonly streaming: boolean }
+  readonly defaultInputModes: readonly string[]
+  readonly defaultOutputModes: readonly string[]
+  readonly skills: readonly A2AAgentSkill[]
+}
+
+/** Caller-supplied card identity; everything else derives from the agent definition. */
+export interface A2ACardInfo {
+  /** Public URL of the JSON-RPC endpoint, as advertised to A2A clients. */
+  readonly url: string
+  /** Version of the exposed agent (the deployment's, not the protocol's). */
+  readonly version: string
+  readonly name?: string
+  readonly description?: string
+}
+
+/** The structural slice of a route context the seam needs. */
+export interface A2ARouteContext {
+  readonly req: Request
+}
+
+/** The structural slice of a nifra server `mountA2A` needs. */
+export interface A2AMountableApp {
+  get(path: string, handler: (c: A2ARouteContext) => Response | Promise<Response>): unknown
+  post(path: string, handler: (c: A2ARouteContext) => Response | Promise<Response>): unknown
+}
+
+export interface MountA2AOptions<
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1,
+> {
+  readonly agent: AgentDefinition<InputSchema, OutputSchema>
+  readonly card: A2ACardInfo
+  /** JSON-RPC endpoint path. Default `/a2a`. */
+  readonly path?: string
+  /** Agent card path. Default `/.well-known/agent-card.json`. */
+  readonly cardPath?: string
+  /** Bounded run length passed to the runner. */
+  readonly maxTurns?: number
+  /** Maximum request body size in bytes. Default 1_000_000. */
+  readonly maxBodyBytes?: number
+  /** Prototype-poisoning policy for the framing lane. Default `"reject"`. */
+  readonly protoPoisoning?: ProtoPoisoning
+  /**
+   * Build the ports for one request - the model, durable state store, approval transport,
+   * capabilities, and budgets. Receives the route context so the caller can scope every port to the
+   * request subject.
+   */
+  readonly ports: (c: A2ARouteContext) => AgentPorts | Promise<AgentPorts>
+}
+
+/** Derive a spec-shaped agent card from the agent definition plus the caller's identity fields. */
+export function agentCard<
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1,
+>(agent: AgentDefinition<InputSchema, OutputSchema>, info: A2ACardInfo): A2AAgentCard {
+  return {
+    protocolVersion: A2A_PROTOCOL_VERSION,
+    name: info.name ?? agent.name,
+    description: info.description ?? agent.instruction,
+    url: info.url,
+    version: info.version,
+    capabilities: { streaming: true },
+    defaultInputModes: ["application/json", "text/plain"],
+    defaultOutputModes: ["application/json", "text/plain"],
+    skills: agent.tools.map((tool) => ({
+      id: tool.name,
+      name: tool.name,
+      description: tool.description,
+      tags: [tool.capability],
+    })),
+  }
+}
+
+/** Mount an agent as an A2A server: the agent card on GET, the JSON-RPC binding on POST. */
+export function mountA2A<
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1,
+>(app: A2AMountableApp, options: MountA2AOptions<InputSchema, OutputSchema>): void {
+  const path = options.path ?? DEFAULT_PATH
+  const cardPath = options.cardPath ?? AGENT_CARD_WELL_KNOWN_PATH
+  const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES
+  const proto = options.protoPoisoning ?? "reject"
+  const runOptions = options.maxTurns === undefined ? {} : { maxTurns: options.maxTurns }
+  const card = agentCard(options.agent, options.card)
+
+  app.get(cardPath, () => jsonResponse(200, card))
+  app.post(path, (c) =>
+    readBodyFramed<Response>(
+      c.req,
+      maxBytes,
+      proto,
+      (parsed) => dispatch(c, parsed, options, runOptions),
+      (rejection) => render(rejection),
+      () => rpcErrorResponse(null, A2A_ERROR_CODES.parseError, "parse_error"),
+    ).catch(() => rpcErrorResponse(null, A2A_ERROR_CODES.internalError, "internal_error")),
+  )
+}
+
+type RpcId = string | number
+type RunStart = (telemetry?: AgentPorts["telemetry"]) => Promise<AgentRunResult<unknown>>
+
+async function dispatch<
+  InputSchema extends StandardSchemaV1,
+  OutputSchema extends StandardSchemaV1,
+>(
+  c: A2ARouteContext,
+  parsed: unknown,
+  options: MountA2AOptions<InputSchema, OutputSchema>,
+  runOptions: { readonly maxTurns?: number },
+): Promise<Response> {
+  const request = asRecord(parsed)
+  const id = request === undefined ? undefined : asRpcId(request.id)
+  if (request === undefined || request.jsonrpc !== "2.0" || id === undefined)
+    return rpcErrorResponse(null, A2A_ERROR_CODES.invalidRequest, "invalid_request")
+  const method = request.method
+  if (typeof method !== "string")
+    return rpcErrorResponse(id, A2A_ERROR_CODES.invalidRequest, "invalid_request")
+  const params = asRecord(request.params) ?? {}
+
+  switch (method) {
+    case "SendMessage":
+    case "SendStreamingMessage": {
+      const turn = prepareTurn(params)
+      if ("error" in turn) return rpcErrorResponse(id, turn.error.code, turn.error.message)
+      const basePorts = await options.ports(c)
+      const start: RunStart = (telemetry) => {
+        // Compose rather than replace: the SSE evidence stream must not displace a telemetry
+        // port the caller injected through `ports`.
+        const combined = combineAgentTelemetry(basePorts.telemetry, telemetry)
+        const ports = combined === undefined ? basePorts : { ...basePorts, telemetry: combined }
+        if (turn.resume !== undefined) {
+          return resumeAgent(
+            options.agent,
+            turn.turnId,
+            { value: turn.input, resume: turn.resume },
+            ports,
+            runOptions,
+          )
+        }
+        return runAgent(options.agent, { value: turn.input }, ports, {
+          ...runOptions,
+          state: createAgentState(turn.turnId),
+        })
+      }
+      if (method === "SendMessage") {
+        try {
+          return rpcResultResponse(id, { task: projectTask(turn.turnId, await start()) })
+        } catch {
+          return rpcErrorResponse(id, A2A_ERROR_CODES.taskNotFound, "task_not_resumable")
+        }
+      }
+      return streamingResponse(id, turn.turnId, start)
+    }
+    case "GetTask": {
+      const taskId = typeof params.id === "string" ? params.id : undefined
+      if (taskId === undefined)
+        return rpcErrorResponse(id, A2A_ERROR_CODES.invalidParams, "invalid_params")
+      const basePorts = await options.ports(c)
+      const state = await basePorts.state?.load(taskId)
+      if (state === undefined)
+        return rpcErrorResponse(id, A2A_ERROR_CODES.taskNotFound, "task_not_found")
+      return rpcResultResponse(id, { task: projectStoredTask(state) })
+    }
+    case "ListTasks":
+    case "CancelTask":
+    case "SubscribeToTask":
+    case "CreateTaskPushNotificationConfig":
+    case "GetTaskPushNotificationConfig":
+    case "ListTaskPushNotificationConfigs":
+    case "DeleteTaskPushNotificationConfig":
+    case "GetExtendedAgentCard":
+      return rpcErrorResponse(id, A2A_ERROR_CODES.unsupportedOperation, "unsupported_operation")
+    default:
+      return rpcErrorResponse(id, A2A_ERROR_CODES.methodNotFound, "method_not_found")
+  }
+}
+
+interface PreparedTurn {
+  readonly turnId: string
+  readonly input: unknown
+  readonly resume: AgentTurnInput["resume"]
+}
+
+function prepareTurn(
+  params: Record<string, unknown>,
+): PreparedTurn | { readonly error: { readonly code: number; readonly message: string } } {
+  const message = asRecord(params.message)
+  if (message === undefined)
+    return { error: { code: A2A_ERROR_CODES.invalidParams, message: "invalid_params" } }
+  const metadata = asRecord(message.metadata) ?? {}
+  const taskId = typeof message.taskId === "string" ? message.taskId : undefined
+  const resume = parseResume(metadata.resume)
+  if (taskId !== undefined && !TURN_ID_PATTERN.test(taskId))
+    return { error: { code: A2A_ERROR_CODES.invalidParams, message: "invalid_task_id" } }
+  // A message that names a task must carry the continuation: the runtime keeps state token-only,
+  // so there is nothing to continue from without it.
+  if (taskId !== undefined && resume === undefined)
+    return { error: { code: A2A_ERROR_CODES.invalidParams, message: "resume_metadata_required" } }
+  if (resume !== undefined && taskId === undefined)
+    return { error: { code: A2A_ERROR_CODES.invalidParams, message: "task_id_required" } }
+  return {
+    turnId: taskId ?? crypto.randomUUID(),
+    input: Object.hasOwn(metadata, "input") ? metadata.input : firstTextPart(message.parts),
+    resume,
+  }
+}
+
+function firstTextPart(parts: unknown): unknown {
+  if (!Array.isArray(parts)) return undefined
+  for (const part of parts) {
+    const record = asRecord(part)
+    if (record !== undefined && typeof record.text === "string") return record.text
+  }
+  return undefined
+}
+
+function streamingResponse(id: RpcId, turnId: string, start: RunStart): Response {
+  const stream = createAgentEvidenceStream()
+  const body = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const encoder = new TextEncoder()
+      const send = (payload: unknown): void => {
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(payload)}\n\n`))
+      }
+      const run = start(stream)
+      // The evidence stream must terminate whether the run resolves or throws, or the `for await`
+      // below would hang; the run result (or the error) is still reported in-band after it drains.
+      run
+        .then(
+          () => {},
+          () => {},
+        )
+        .finally(() => stream.complete())
+      try {
+        for await (const evidence of stream) {
+          send(
+            rpcResult(id, {
+              statusUpdate: {
+                taskId: turnId,
+                contextId: turnId,
+                status: { state: "TASK_STATE_WORKING" satisfies A2ATaskState },
+                final: false,
+                metadata: { evidence },
+              },
+            }),
+          )
+        }
+        const result = await run
+        if (result.status === "completed" && result.error === undefined) {
+          send(
+            rpcResult(id, {
+              artifactUpdate: {
+                taskId: turnId,
+                contextId: turnId,
+                artifact: outputArtifact(turnId, result.output),
+                lastChunk: true,
+              },
+            }),
+          )
+        }
+        const task = projectTask(turnId, result)
+        send(
+          rpcResult(id, {
+            statusUpdate: {
+              taskId: turnId,
+              contextId: turnId,
+              status: task.status,
+              final: true,
+              ...(task.metadata === undefined ? {} : { metadata: task.metadata }),
+            },
+          }),
+        )
+      } catch {
+        send(rpcError(id, A2A_ERROR_CODES.internalError, "run_failed"))
+      } finally {
+        controller.close()
+      }
+    },
+  })
+  return new Response(body, {
+    status: 200,
+    headers: {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+    },
+  })
+}
+
+interface ProjectedTask {
+  readonly id: string
+  readonly contextId: string
+  readonly status: { readonly state: A2ATaskState; readonly message?: unknown }
+  readonly artifacts?: readonly unknown[]
+  readonly metadata?: Record<string, unknown>
+}
+
+/** Project a run result onto the A2A task shape. Evidence is token-only by design, so it passes through. */
+function projectTask(turnId: string, result: AgentRunResult<unknown>): ProjectedTask {
+  const base = { id: turnId, contextId: turnId }
+  if (result.status === "completed") {
+    if (result.error !== undefined) {
+      return {
+        ...base,
+        status: { state: "TASK_STATE_FAILED" },
+        metadata: { evidence: result.evidence, error: result.error },
+      }
+    }
+    return {
+      ...base,
+      status: { state: "TASK_STATE_COMPLETED" },
+      artifacts: [outputArtifact(turnId, result.output)],
+      metadata: { evidence: result.evidence },
+    }
+  }
+  if (result.status === "suspended") {
+    const state: A2ATaskState =
+      result.reason === "cancelled" ? "TASK_STATE_CANCELED" : "TASK_STATE_INPUT_REQUIRED"
+    return {
+      ...base,
+      status: {
+        state,
+        message: {
+          messageId: `${turnId}:pending`,
+          taskId: turnId,
+          role: "ROLE_AGENT",
+          parts: [],
+          metadata: { reason: result.reason, continuation: result.pending },
+        },
+      },
+      metadata: { evidence: result.evidence },
+    }
+  }
+  // `continue` never escapes the run loop; project it defensively as still-working.
+  return {
+    ...base,
+    status: { state: "TASK_STATE_WORKING" },
+    metadata: { evidence: result.evidence },
+  }
+}
+
+/** Project stored turn state (GetTask). Stored state cannot distinguish a failed completion. */
+function projectStoredTask(state: AgentTurnState): ProjectedTask {
+  const taskState: A2ATaskState =
+    state.status === "completed"
+      ? "TASK_STATE_COMPLETED"
+      : state.status === "suspended"
+        ? "TASK_STATE_INPUT_REQUIRED"
+        : "TASK_STATE_WORKING"
+  return {
+    id: state.turnId,
+    contextId: state.turnId,
+    status: { state: taskState },
+    metadata: {
+      evidence: state.evidence,
+      ...(state.pending === undefined ? {} : { continuation: state.pending }),
+    },
+  }
+}
+
+function outputArtifact(turnId: string, output: unknown): Record<string, unknown> {
+  return {
+    artifactId: `${turnId}:output`,
+    name: "output",
+    parts: [typeof output === "string" ? { text: output } : { text: JSON.stringify(output) }],
+  }
+}
+
+function parseResume(raw: unknown): AgentTurnInput["resume"] | undefined {
+  const record = asRecord(raw)
+  if (record === undefined) return undefined
+  const continuation = asRecord(record.continuation)
+  if (continuation === undefined) return undefined
+  const kind = continuation.kind
+  if (typeof kind !== "string" || !PENDING_KINDS.includes(kind as AgentPendingKind))
+    return undefined
+  if (typeof continuation.effectId !== "string") return undefined
+  if (continuation.tool !== undefined && typeof continuation.tool !== "string") return undefined
+  const approval = asRecord(record.approval)
+  return {
+    continuation: {
+      kind: kind as AgentPendingKind,
+      ...(continuation.tool === undefined ? {} : { tool: continuation.tool as string }),
+      ...(Object.hasOwn(continuation, "input") ? { input: continuation.input } : {}),
+      effectId: continuation.effectId,
+    },
+    ...(approval !== undefined && typeof approval.granted === "boolean"
+      ? {
+          approval: {
+            granted: approval.granted,
+            ...(typeof approval.reason === "string" ? { reason: approval.reason } : {}),
+          },
+        }
+      : {}),
+  }
+}
+
+function rpcResult(id: RpcId, result: unknown): Record<string, unknown> {
+  return { jsonrpc: "2.0", id, result }
+}
+
+function rpcError(id: RpcId | null, code: number, message: string): Record<string, unknown> {
+  return { jsonrpc: "2.0", id, error: { code, message } }
+}
+
+function rpcResultResponse(id: RpcId, result: unknown): Response {
+  return jsonResponse(200, rpcResult(id, result))
+}
+
+function rpcErrorResponse(id: RpcId | null, code: number, message: string): Response {
+  return jsonResponse(200, rpcError(id, code, message))
+}
+
+function asRpcId(value: unknown): RpcId | undefined {
+  if (typeof value === "string") return value
+  if (typeof value === "number" && Number.isFinite(value)) return value
+  return undefined
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined
+  return value as Record<string, unknown>
+}
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8" },
+  })
+}
+
+function render(response: Response | ResponseResult): Response {
+  return response instanceof Response ? response : toResponse(response, EMPTY_RESPONSE_CONTROLS)
+}