@nylorun/runtime 0.36.1-beta → 0.38.0-beta

package/dist/api/a2a/routes.js

@@ -1,28 +1,47 @@
 /**
- * The A2A endpoint (Host feature `a2a-endpoint`): `POST /v1/a2a/agents/:agent` answers A2A 1.0
- * JSON-RPC for one subject, and `GET /v1/a2a/agents/:agent/card` returns the agent's card
- * without interfaces. v1 serves `SendMessage` (blocking, or `returnImmediately`), `GetTask`
- * and `CancelTask`; every other operation answers with the error the specification defines
- * for it (docs: `implementation/a2a-implementation.md`).
+ * The A2A endpoint (Host features `a2a-endpoint` and `a2a-profile-v2`): `POST
+ * /v1/a2a/agents/:agent` answers A2A 1.0 JSON-RPC for one subject, and `GET
+ * /v1/a2a/agents/:agent/card` returns the agent's card. It serves `SendMessage` (blocking up to
+ * `a2aWaitMs`, or `returnImmediately`), `GetTask`, `ListTasks`, `CancelTask` and the four push
+ * notification config methods; every other operation answers with the error the specification
+ * defines for it (docs: `implementation/a2a-implementation.md`, profile v2:
+ * `design/runtime/a2a-profile.md`). Tasks are found through the turn index (Host feature
+ * `turns`, `list.ts`): a context's session carries `info.a2a`, and a task's events are read from
+ * its turn's first event, never the whole history.
  *
  * Every task operation goes through the session contract as the caller: `command` with the
  * caller's scope (limits and owner checks apply), sessions derived from the caller's own
  * subject, history from Durable Streams. A task id from the client only selects a context and
  * a turn within the caller's own sessions, so another subject's task is `TaskNotFoundError`.
  *
- * A message's `raw` file parts are stored as artifacts of the context's session once it is open,
- * and the message goes in as `parts` (`../inbound-files.ts`): a file the model does not read is
- * `ContentTypeNotSupportedError`, and the files of a refused message are deleted.
+ * Profile v2:
+ * - A message to a busy context is **queued** (`delivery: "queue"`, protocol 17) and answered
+ *   with the task that will take it: `SUBMITTED`, its id the queued message's own until a turn
+ *   takes it, then that turn's state. `metadata.delivery: "reject"` keeps v1's
+ *   `UnsupportedOperationError` (reason `CONTEXT_BUSY`).
+ * - An open interaction shows on the status message under `interactions/v1`; the caller answers
+ *   on the same task with `{ interactionId, approved }` (the Runtime's `approve`, recorded with
+ *   the caller as `approvedBy`) or `{ interactionId, value }` (`respond`). Text never approves.
+ * - A push config (in `SendMessage`, or the config methods) sends the task's updates to the
+ *   caller's URL (`push.ts`).
+ * - A message's `raw` and `url` file parts are stored as artifacts of the context's session once
+ *   it is open (`../inbound-files.ts`; a `url` is fetched under the push address policy), and the
+ *   message goes in as `parts`. The files the turn writes come back as artifacts whose `url`
+ *   parts point at `/v1/a2a/files/…`, served to the same subject, with `files/v1`.
  */
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { SessionCommandSchema, } from "@nylorun/core/contracts";
 import { commandKey } from "../../core/flow-host.js";
 import { contentTypeFor } from "@nylorun/core/contracts";
-import { discardFiles, inlineFileName, messageParts, } from "../inbound-files.js";
+import { discardFiles, fetchUrlFile, inlineFileName, messageParts, } from "../inbound-files.js";
 import { agentCard, inputModesFor } from "./card.js";
-import { A2aError, a2aFail, checkVersion, jsonRpcError, jsonRpcResult, parseEnvelope, parseSendParams, parseTaskParams, } from "./protocol.js";
-import { SETTLED_EVENTS, buildTask, contextSessionId, newContextId, parseTaskId, pendingInteraction, taskIdOf, } from "./tasks.js";
+import { keepExtensions } from "./extensions.js";
+import { indexedTurnEvents, listTasks, parseListParams } from "./list.js";
+import { A2aError, a2aFail, checkVersion, jsonRpcError, jsonRpcResult, parseCreatePushParams, parseEnvelope, parseListPushParams, parsePushConfigRef, parseSendParams, parseTaskParams, } from "./protocol.js";
+import { configView, kickPushes, pushEnabled, pushPolicy, savePushConfig, } from "./push.js";
+import { ENDED, SETTLED_EVENTS, buildTask, callerTraceId, contextSessionId, newContextId, parseTaskId, pendingInteraction, pendingInteractions, submittedTask, taskIdOf, } from "./tasks.js";
 import { currentModelDescriptor } from "../../model/descriptor.js";
+import { decodeCursor } from "../../record/cursor.js";
 import { accessOf } from "../../tenant/auth.js";
 import { command } from "../../tenant/commands.js";
 import { loadSession, reachesAgent, } from "../../tenant/context.js";
@@ -31,21 +50,32 @@ import { HttpError, fail } from "../../tenant/http.js";
 import { observeSession, readHistory } from "../../tenant/session-streams.js";
 import { putSession } from "../../tenant/sessions.js";
 import { readRuntimeLimits } from "../../tenant/runtime-limits.js";
+import { traceKey } from "../../traces/key.js";
+import { parseTraceparent, traceIdOf } from "../../traces/ids.js";
+/** The A2A endpoint's route for a published agent, from the Runtime's base URL. */
+export function agentEndpoint(baseUrl, agentId) {
+    return `${baseUrl}/v1/a2a/agents/${encodeURIComponent(agentId)}`;
+}
 /**
  * `GET /v1/a2a/agents/:agent/card`: the agent's card, for a caller who may use the agent. Its
  * input modes name the files the Tenant's model reads natively: a hint, since any file is
- * accepted and the agent's harness decides how its model sees it (protocol 15).
+ * accepted and the agent's harness decides how its model sees it (protocol 15). Its interface is
+ * this Runtime's JSON-RPC endpoint at `baseUrl` (a gateway lists its own instead).
  */
-export async function a2aCard(ctx, scope, agentId) {
+export async function a2aCard(ctx, scope, agentId, baseUrl) {
     const definition = await definitionFor(ctx, agentId, accessOf(scope));
     // The files the Tenant's model reads now.
-    return agentCard(agentId, definition, inputModesFor((await currentModelDescriptor(ctx))?.inputs));
+    return agentCard(agentId, definition, inputModesFor((await currentModelDescriptor(ctx))?.inputs), {
+        url: agentEndpoint(baseUrl, agentId),
+        pushNotifications: pushEnabled(ctx),
+    });
 }
 /**
  * `POST /v1/a2a/agents/:agent`: one A2A JSON-RPC call, for a subject. JSON-RPC answers (errors
- * included) are the body to send with 200; HTTP-level refusals (unknown agent, no subject,
- * limits) are thrown as `HttpError` like any Tenant route. `body` is read once the agent is
- * known to be the caller's; closing `response` stops a blocking wait, never the task.
+ * included) are the body to send with 200, without the data of extensions the request did not
+ * activate; HTTP-level refusals (unknown agent, no subject, limits) are thrown as `HttpError`
+ * like any Tenant route. `body` is read once the agent is known to be the caller's; closing
+ * `response` stops a blocking wait, never the task.
  */
 export async function a2aCall(ctx, scope, agentId, input, response) {
     const access = accessOf(scope);
@@ -60,11 +90,20 @@ export async function a2aCall(ctx, scope, agentId, input, response) {
     // A blocking call stops waiting when the caller hangs up; the task keeps running.
     const hangup = new AbortController();
     response.on("close", () => hangup.abort());
-    const caller = { ctx, scope, access, agentId, ...(input.trace ? { trace: input.trace } : {}) };
+    const caller = {
+        ctx,
+        scope,
+        access,
+        agentId,
+        ...(input.trace ? { trace: input.trace } : {}),
+        extensions: input.extensions,
+        baseUrl: input.baseUrl,
+    };
     const { id } = envelope.request;
     try {
         checkVersion(input.version);
-        return jsonRpcResult(id, await operation(caller, envelope.request, hangup.signal));
+        const result = await operation(caller, envelope.request, hangup.signal);
+        return jsonRpcResult(id, keepExtensions(result, input.extensions));
     }
     catch (error) {
         if (error instanceof A2aError)
@@ -91,15 +130,18 @@ async function operation(caller, request, signal) {
         case "CancelTask":
             return cancelTask(caller, parseTaskParams(request.params).id);
         case "ListTasks":
-            return a2aFail("unsupportedOperation", "ListTasks is not supported by this agent yet");
+            return listTasks(caller, parseListParams(request.params), (row, session, historyLength) => indexedTask(caller, row, session, { historyLength }).then((built) => built?.task));
         case "SendStreamingMessage":
         case "SubscribeToTask":
-            return a2aFail("unsupportedOperation", "Streaming is not supported: the Agent Card declares capabilities.streaming false");
+            return a2aFail("unsupportedOperation", "Streaming is not supported: the Agent Card declares capabilities.streaming false; register a push notification config");
         case "CreateTaskPushNotificationConfig":
+            return createPushConfig(caller, request.params);
         case "GetTaskPushNotificationConfig":
+            return getPushConfig(caller, request.params);
         case "ListTaskPushNotificationConfigs":
+            return listPushConfigs(caller, request.params);
         case "DeleteTaskPushNotificationConfig":
-            return a2aFail("pushNotSupported", "Push notifications are not supported");
+            return deletePushConfig(caller, request.params);
         case "GetExtendedAgentCard":
             return a2aFail("unsupportedOperation", "This agent has no extended Agent Card");
         default:
@@ -135,30 +177,96 @@ async function contextSession(caller, sessionId) {
         throw error;
     }
 }
-/** The events of one turn, in stream order. */
-async function turnEvents(ctx, sessionId, turnId) {
-    const { items } = await readHistory(ctx, sessionId, undefined, undefined);
-    return items.filter((event) => event.turnId === turnId);
+/** Every event of a session, in stream order: only to find a queued message no turn took yet. */
+async function sessionEvents(ctx, sessionId) {
+    return (await readHistory(ctx, sessionId, undefined, undefined)).items;
+}
+/** `telemetry/v1`'s trace id for a turn: the caller's `traceparent`'s, else the Runtime's own. */
+async function turnTraceId(ctx, sessionId, turnId, events) {
+    return callerTraceId(events) ?? traceIdOf(await traceKey(ctx.store), ctx.store.tenantId, sessionId, turnId);
 }
+const payloadOf = (event) => (event.payload ?? {});
+/**
+ * The task of turn index row `row` as the caller sees it (`taskId`: the id the caller knows it
+ * by), built from that turn's own events (`indexedTurnEvents`): what `GetTask` and `ListTasks`
+ * answer.
+ */
+async function indexedTask(caller, row, session, options = {}) {
+    const contextId = row.a2aContextId ?? parseTaskId(options.taskId ?? "")?.contextId;
+    if (contextId === undefined)
+        return undefined;
+    const events = await indexedTurnEvents(caller.ctx, row);
+    const ended = events.some((event) => ENDED.has(event.type));
+    const task = buildTask({
+        contextId,
+        turnId: row.turnId,
+        ...(options.taskId !== undefined ? { taskId: options.taskId } : {}),
+        session,
+        events,
+        baseUrl: caller.baseUrl,
+        ...(ended ? { traceId: await turnTraceId(caller.ctx, row.sessionId, row.turnId, events) } : {}),
+        ...(options.historyLength !== undefined ? { historyLength: options.historyLength } : {}),
+    });
+    return task ? { task, events } : undefined;
+}
+/**
+ * The caller's task `taskId`, found through the turn index. Its last part is a turn, or a queued
+ * message's id: while the message waits the task is `SUBMITTED`, and once a turn took it (the
+ * index keeps the queued messages each turn took) the task is that turn's, under the id the
+ * caller knows. Only a message still in the queue is looked for in the session's history.
+ */
 async function ownedTask(caller, taskId, historyLength) {
     const ids = parseTaskId(taskId) ?? taskNotFound(taskId);
     const sessionId = contextSessionId(caller.access.owner, caller.agentId, ids.contextId);
     const session = (await contextSession(caller, sessionId)) ?? taskNotFound(taskId);
-    const task = buildTask({
-        ...ids,
-        session,
-        events: await turnEvents(caller.ctx, sessionId, ids.turnId),
+    const found = await caller.ctx.store.tx(async (t) => {
+        const turn = await t.turn(sessionId, ids.turnId);
+        if (turn)
+            return { turn };
+        // Still queued, or taken: the queue is read first, so a message taken meanwhile is found.
+        if ((await t.queuedMessages(sessionId)).some((row) => row.id === ids.turnId))
+            return { queued: true };
+        const taken = await t.turnOfQueuedMessage(sessionId, ids.turnId);
+        return taken ? { turn: taken } : {};
+    });
+    if (found.queued) {
+        const queued = (await sessionEvents(caller.ctx, sessionId)).find((event) => event.type === "message.queued" && payloadOf(event).queuedMessageId === ids.turnId);
+        if (queued)
+            return {
+                task: submittedTask(ids.contextId, taskId, queued),
+                session,
+                sessionId,
+                contextId: ids.contextId,
+                turnId: ids.turnId,
+                events: [],
+                queued,
+            };
+    }
+    const row = found.turn ?? taskNotFound(taskId);
+    const built = (await indexedTask(caller, { ...row, a2aContextId: ids.contextId }, session, {
+        taskId,
         ...(historyLength !== undefined ? { historyLength } : {}),
-    }) ?? taskNotFound(taskId);
-    return { task, session, sessionId, ...ids };
+    })) ?? taskNotFound(taskId);
+    return {
+        task: built.task,
+        session,
+        sessionId,
+        contextId: ids.contextId,
+        turnId: row.turnId,
+        events: built.events,
+    };
 }
 /** Runs a session command as the caller, mapping the Runtime's refusals to A2A errors. */
 async function run(caller, sessionId, input, 
 /** The error for a `409` conflict: the session is busy or no longer waiting. */
-conflict) {
+conflict, 
+/** What a message to a busy session does: queued (profile v2), or `409`. */
+delivery = "reject") {
     try {
-        const accepted = (await command(caller.ctx, sessionId, SessionCommandSchema.parse(input), caller.scope, caller.trace ? { trace: caller.trace } : {}));
-        return { turnId: accepted.turnId, cursor: accepted.cursor };
+        const accepted = (await command(caller.ctx, sessionId, SessionCommandSchema.parse(input), caller.scope, { ...(caller.trace ? { trace: caller.trace } : {}), delivery }));
+        return accepted.status === "queued"
+            ? { queuedMessageId: accepted.queuedMessageId, cursor: accepted.cursor }
+            : { turnId: accepted.turnId, cursor: accepted.cursor };
     }
     catch (error) {
         if (!(error instanceof HttpError))
@@ -170,59 +278,56 @@ conflict) {
         throw await conflict();
     }
 }
-/** Opens the caller's session for a context: created when missing, never changed after. */
-async function openContext(caller, sessionId) {
+/**
+ * Opens the caller's session for a context: created when missing, with `info.a2a` naming the
+ * context and the subject, so the turn index can list its tasks (`ListTasks`); the session id
+ * stays the one-way `contextSessionId`. A context opened before `info.a2a` gets it now, for the
+ * turns it starts from here on. Nothing else changes after.
+ */
+async function openContext(caller, sessionId, contextId) {
+    const a2a = { contextId, subject: caller.access.owner };
     const existing = await contextSession(caller, sessionId);
-    if (existing)
-        return existing;
+    if (existing) {
+        if (existing.info?.a2a?.contextId === contextId)
+            return existing;
+        return caller.ctx.store.tx(async (t) => {
+            const session = (await t.lockSession(sessionId));
+            if (session.info?.a2a?.contextId !== contextId) {
+                session.info = { ...(session.info ?? {}), a2a };
+                await t.put("sessions", sessionId, session);
+            }
+            return session;
+        });
+    }
     return putSession(caller.ctx, sessionId, {
         requestId: randomUUID(),
         agent: caller.agentId,
         ownerUserId: caller.access.owner,
+        info: { a2a },
     }, caller.access, agentGrantsOf(caller.scope) === undefined ? {} : { agentGrants: agentGrantsOf(caller.scope) });
 }
 async function sendMessage(caller, params, signal) {
     const send = parseSendParams(params);
+    if (send.push && !pushEnabled(caller.ctx))
+        a2aFail("pushNotSupported", "Push notifications are not configured on this Runtime");
     const idempotencyKey = `a2a:${send.messageId}`;
     let contextId;
     let sessionId;
     let accepted;
     if (send.taskId !== undefined) {
-        // A reply on an existing task: only a question it is waiting on can take it.
         const ids = parseTaskId(send.taskId) ?? taskNotFound(send.taskId);
-        const value = "content" in send.input
-            ? send.input.content
-            : "data" in send.input
-                ? send.input.data
-                : a2aFail("contentTypeNotSupported", "A reply takes text or one data part; send files in a new message", { accepted: "text/plain,application/json" });
         if (send.contextId !== undefined && send.contextId !== ids.contextId)
             a2aFail("invalidParams", "message.contextId does not match the task's context", {}, "message.contextId");
         contextId = ids.contextId;
-        sessionId = contextSessionId(caller.access.owner, caller.agentId, contextId);
-        const session = (await contextSession(caller, sessionId)) ?? taskNotFound(send.taskId);
-        const prior = await caller.ctx.store.tx((t) => t.get("commands", commandKey(sessionId, idempotencyKey)));
-        // A retried reply replays through `command`, which compares it with the first one.
-        const interactionId = prior?.command.type === "respond"
-            ? prior.command.interactionId
-            : prior
-                ? a2aFail("invalidParams", "message.messageId was already used for a different message", {}, "message.messageId")
-                : await replyTarget(caller, session, sessionId, ids.turnId, send.taskId);
-        accepted = await run(caller, sessionId, {
-            type: "respond",
-            requestId: randomUUID(),
-            idempotencyKey,
-            interactionId,
-            value,
-        }, async () => new A2aError("unsupportedOperation", "The task is no longer waiting for input", {
-            taskId: send.taskId,
-        }));
-        accepted = { ...accepted, turnId: ids.turnId };
+        const owned = await ownedTask(caller, send.taskId, 0);
+        sessionId = owned.sessionId;
+        accepted = await reply(caller, send, owned, idempotencyKey);
     }
     else {
         contextId =
             send.contextId ?? newContextId(caller.access.owner, caller.agentId, send.messageId);
         sessionId = contextSessionId(caller.access.owner, caller.agentId, contextId);
-        await openContext(caller, sessionId);
+        await openContext(caller, sessionId, contextId);
         const context = contextId;
         const { body, stored } = await messageBody(caller, sessionId, idempotencyKey, send.input);
         accepted = await run(caller, sessionId, {
@@ -234,40 +339,144 @@ async function sendMessage(caller, params, signal) {
             const active = (await contextSession(caller, sessionId))?.activeTurnId;
             const taskId = active ? taskIdOf(context, active) : undefined;
             return taskId
-                ? new A2aError("unsupportedOperation", `The context has a task in progress (${taskId}); reply to it or cancel it`, { taskId })
-                : new A2aError("unsupportedOperation", "The context has unresolved work; start a new context");
-        }).catch(async (error) => {
+                ? new A2aError("unsupportedOperation", `The context has a task in progress (${taskId}); reply to it, cancel it, or send without delivery "reject" to queue the message`, { taskId }, undefined, "CONTEXT_BUSY")
+                : new A2aError("unsupportedOperation", "The context has unresolved work; start a new context", {}, undefined, "CONTEXT_BUSY");
+        }, send.delivery).catch(async (error) => {
             await discardFiles(caller.ctx, stored, caller.access);
             throw error;
         });
     }
+    const turnId = accepted.turnId ?? accepted.queuedMessageId;
+    const taskId = send.taskId ?? taskIdOf(contextId, turnId);
+    if (send.push)
+        await registerPush(caller, send.push, {
+            sessionId,
+            contextId,
+            taskId,
+            turnId: accepted.turnId ?? accepted.queuedMessageId,
+            nextSeq: decodeCursor(sessionId, accepted.cursor),
+            ...(accepted.turnId !== undefined ? { traceId: await sendTraceId(caller, sessionId, accepted.turnId) } : {}),
+        });
     if (!send.returnImmediately)
-        await settled(caller.ctx, sessionId, accepted.turnId, accepted.cursor, signal);
-    const { task } = await ownedTask(caller, taskIdOf(contextId, accepted.turnId), send.historyLength);
+        await settled(caller.ctx, sessionId, accepted, signal);
+    const { task } = await ownedTask(caller, taskId, send.historyLength);
     return { task };
 }
+/** The trace id of a turn this request started: its `traceparent`'s, else the Runtime's own. */
+async function sendTraceId(caller, sessionId, turnId) {
+    const parsed = caller.trace ? parseTraceparent(caller.trace.traceparent) : undefined;
+    return parsed?.traceId ?? traceIdOf(await traceKey(caller.ctx.store), caller.ctx.store.tenantId, sessionId, turnId);
+}
 /**
- * A new message's body: its text, its JSON value, or parts with its `raw` files stored as
- * artifacts of the session (`stored`: the ones this call created). A file the Runtime cannot
- * store is `InvalidParamsError`; one past a limit stays an HTTP `413`.
+ * A message on an existing task: an answer to one of its open interactions (`interactions/v1`),
+ * or a text or data reply to the question it waits on. A retried answer replays through
+ * `command`, which compares it with the first one.
+ */
+async function reply(caller, send, owned, idempotencyKey) {
+    const { session, sessionId, turnId } = owned;
+    const taskId = owned.task.id;
+    const prior = await caller.ctx.store.tx((t) => t.get("commands", commandKey(sessionId, idempotencyKey)));
+    const reused = () => a2aFail("invalidParams", "message.messageId was already used for a different message", {}, "message.messageId");
+    let answer;
+    if (send.answer) {
+        const kind = prior?.command.type === "approve" || prior?.command.type === "respond"
+            ? prior.command.type
+            : prior
+                ? reused()
+                : answerTarget(owned, send.answer).engineKind === "approval"
+                    ? "approve"
+                    : "respond";
+        answer = answerCommand(kind, send.answer, idempotencyKey);
+    }
+    else {
+        const value = "content" in send.input
+            ? send.input.content
+            : "data" in send.input
+                ? send.input.data
+                : a2aFail("contentTypeNotSupported", "A reply takes text or one data part; send files in a new message", { accepted: "text/plain,application/json" });
+        const interactionId = prior?.command.type === "respond"
+            ? prior.command.interactionId
+            : prior
+                ? reused()
+                : replyTarget(owned);
+        answer = { type: "respond", requestId: randomUUID(), idempotencyKey, interactionId, value };
+    }
+    const accepted = await run(caller, sessionId, answer, async () => new A2aError("unsupportedOperation", "The task is no longer waiting for input", { taskId }));
+    return { turnId, cursor: accepted.cursor };
+}
+/**
+ * The command an `interactions/v1` answer is: `approve` with `approved`, or `respond` with
+ * `value` (an `approved` answer to a question or connection is its value).
+ */
+function answerCommand(kind, answer, idempotencyKey) {
+    const base = { requestId: randomUUID(), idempotencyKey, interactionId: answer.interactionId };
+    if (kind === "approve") {
+        const approved = "approved" in answer
+            ? answer.approved
+            : typeof answer.value === "boolean"
+                ? answer.value
+                : a2aFail("invalidParams", "An approval is answered with approved: true or false", {}, "message.metadata");
+        return { type: "approve", ...base, approved };
+    }
+    return {
+        type: "respond",
+        ...base,
+        value: "approved" in answer ? answer.approved : (answer.value ?? null),
+    };
+}
+/** A reply to a task that is not active: it is queued, or in a terminal state. */
+function notActive(owned) {
+    const taskId = owned.task.id;
+    if (owned.queued)
+        return a2aFail("unsupportedOperation", "The task is queued and waits for nothing yet", { taskId });
+    return a2aFail("unsupportedOperation", "The task is in a terminal state and accepts no more messages; send a new message without taskId", { taskId });
+}
+/** The task must be active and waiting on the interaction the answer names. */
+function answerTarget(owned, answer) {
+    const { session } = owned;
+    if (owned.queued || session.activeTurnId !== owned.turnId)
+        return notActive(owned);
+    const open = session.status === "paused" ? pendingInteractions(session) : [];
+    return (open.find((interaction) => interaction.id === answer.interactionId) ??
+        a2aFail("invalidParams", open.length === 0
+            ? "The task is not waiting for an answer"
+            : `The task does not wait on interaction ${answer.interactionId}`, { taskId: owned.task.id }, "message.metadata"));
+}
+/**
+ * A new message's body: its text, its JSON value, or parts with its `raw` and `url` files stored
+ * as artifacts of the session (`stored`: the ones this call created). A file the Runtime cannot
+ * fetch or store is `InvalidParamsError`; one past a limit stays an HTTP `413`.
  */
 async function messageBody(caller, sessionId, idempotencyKey, input) {
     if (!("files" in input))
         return { body: input, stored: [] };
-    let files = 0;
-    const inbound = input.files.map((part) => {
-        if ("text" in part)
-            return { type: "text", text: part.text };
-        const index = files++;
-        const mediaType = part.mediaType ?? (part.filename !== undefined ? contentTypeFor(part.filename) : "application/octet-stream");
-        return {
-            type: "inline",
-            name: part.filename ?? inlineFileName(mediaType, index),
-            mediaType,
-            data: part.raw,
-        };
-    });
     try {
+        let files = 0;
+        const inbound = [];
+        for (const part of input.files) {
+            if ("text" in part) {
+                inbound.push({ type: "text", text: part.text });
+                continue;
+            }
+            const index = files++;
+            if ("url" in part) {
+                inbound.push({
+                    type: "inline",
+                    ...(await fetchUrlFile(caller.ctx, part.url, {
+                        ...(part.mediaType !== undefined ? { mediaType: part.mediaType } : {}),
+                        ...(part.filename !== undefined ? { filename: part.filename } : {}),
+                    }, pushPolicy(caller.ctx, part.url))),
+                });
+                continue;
+            }
+            const mediaType = part.mediaType ?? (part.filename !== undefined ? contentTypeFor(part.filename) : "application/octet-stream");
+            inbound.push({
+                type: "inline",
+                name: part.filename ?? inlineFileName(mediaType, index),
+                mediaType,
+                data: part.raw,
+            });
+        }
         const { parts, stored } = await messageParts(caller.ctx, sessionId, idempotencyKey, inbound, caller.access);
         return { body: { parts }, stored };
     }
@@ -277,29 +486,29 @@ async function messageBody(caller, sessionId, idempotencyKey, input) {
         throw error;
     }
 }
-/** The interaction a reply answers: the task must be active and paused on a question. */
-async function replyTarget(caller, session, sessionId, turnId, taskId) {
-    if (session.activeTurnId !== turnId) {
-        // Ended, or never this caller's: a terminal task takes no more messages.
-        const task = buildTask({
-            contextId: parseTaskId(taskId).contextId,
-            turnId,
-            session,
-            events: await turnEvents(caller.ctx, sessionId, turnId),
-        });
-        if (!task)
-            return taskNotFound(taskId);
-        return a2aFail("unsupportedOperation", "The task is in a terminal state and accepts no more messages; send a new message without taskId", { taskId });
-    }
+/**
+ * The question a text or data reply answers: the task must be active and paused on one. An
+ * approval takes only an `interactions/v1` answer: text never approves (profile v2 §1).
+ */
+function replyTarget(owned) {
+    const { session } = owned;
+    const taskId = owned.task.id;
+    if (owned.queued || session.activeTurnId !== owned.turnId)
+        return notActive(owned);
     const pending = session.status === "paused" ? pendingInteraction(session) : undefined;
     if (!pending)
         return a2aFail("unsupportedOperation", "The task is working and not waiting for input; wait for it or cancel it", { taskId });
-    if (pending.kind === "approval")
-        return a2aFail("unsupportedOperation", "The task waits for an approval, which A2A callers cannot give yet; cancel the task instead", { taskId });
+    if (pending.engineKind === "approval")
+        return a2aFail("unsupportedOperation", "The task waits for an approval, which text never gives: answer it under the interactions/v1 extension ({ interactionId, approved }), or cancel the task", { taskId, interactionId: pending.id });
     return pending.id;
 }
 async function cancelTask(caller, taskId) {
     const owned = await ownedTask(caller, taskId);
+    if (owned.queued)
+        return a2aFail("taskNotCancelable", "The task is queued and starts when the context's running task ends; cancel it then", {
+            taskId,
+            state: owned.task.status.state,
+        });
     if (owned.session.activeTurnId !== owned.turnId) {
         if (owned.task.status.state === "TASK_STATE_CANCELED")
             return owned.task;
@@ -322,14 +531,95 @@ async function cancelTask(caller, taskId) {
     }
     return (await ownedTask(caller, taskId)).task;
 }
+// ---------------------------------------------------------------------------
+// Push notification configs
+/** A config's id when the caller names none: one per task. */
+const DEFAULT_PUSH_CONFIG = "default";
+/** Stores a push config for a task this request started or answered, then pumps the session. */
+async function registerPush(caller, config, start) {
+    const configId = config.id ?? DEFAULT_PUSH_CONFIG;
+    const saved = await caller.ctx.store.tx(async (t) => {
+        // A retried message keeps its config where it is, so updates are not sent again.
+        const existing = await t.pushConfig(start.sessionId, start.taskId, configId);
+        if (existing && sameConfig(existing, config))
+            return configView(existing);
+        return savePushConfig(caller.ctx, t, { ...start, baseUrl: caller.baseUrl, extensions: caller.extensions }, config, configId);
+    });
+    void kickPushes(caller.ctx, start.sessionId);
+    return saved;
+}
+function sameConfig(row, config) {
+    return (row.url === config.url &&
+        (row.token ?? undefined) === config.token &&
+        JSON.stringify(row.authentication ?? null) === JSON.stringify(config.authentication ?? null));
+}
+function requirePush(caller) {
+    if (!pushEnabled(caller.ctx))
+        a2aFail("pushNotSupported", "Push notifications are not configured on this Runtime");
+}
 /**
- * Waits until the turn ends, pauses or has an uncertain effect, the caller hangs up, or the
- * Tenant's Runtime limit `a2aWaitMs` passes: after it, the task is returned `WORKING` and keeps
- * running, and the caller polls `GetTask`. Follows the session's shared stream from the command's
- * cursor, so the events the task is built from are there when it returns. A feed that ends
- * (reset, deleted, closing) ends the wait: the task says what the session says then.
+ * `CreateTaskPushNotificationConfig`: from the task's next event on. A config on a finished task
+ * is stored and sends nothing.
  */
-async function settled(ctx, sessionId, turnId, cursor, signal) {
+async function createPushConfig(caller, params) {
+    requirePush(caller);
+    const { taskId, config } = parseCreatePushParams(params);
+    const owned = await ownedTask(caller, taskId);
+    const last = owned.queued ?? owned.events.at(-1);
+    const ended = owned.events.some((event) => ENDED.has(event.type));
+    const configId = config.id ?? createHash("sha256").update(`${config.url}\u0000${config.token ?? ""}`).digest("hex").slice(0, 16);
+    return registerPush(caller, { ...config, id: configId }, {
+        sessionId: owned.sessionId,
+        contextId: owned.contextId,
+        taskId: owned.task.id,
+        turnId: owned.turnId,
+        nextSeq: last ? last.seq + 1 : 0,
+        ...(owned.queued ? {} : { traceId: await turnTraceId(caller.ctx, owned.sessionId, owned.turnId, owned.events) }),
+        done: ended,
+    });
+}
+async function getPushConfig(caller, params) {
+    requirePush(caller);
+    const ref = parsePushConfigRef(params);
+    const owned = await ownedTask(caller, ref.taskId, 0);
+    const row = await caller.ctx.store.tx((t) => t.pushConfig(owned.sessionId, owned.task.id, ref.id));
+    return row ? configView(row) : a2aFail("taskNotFound", "Push notification config not found", { taskId: ref.taskId, id: ref.id });
+}
+async function listPushConfigs(caller, params) {
+    requirePush(caller);
+    const query = parseListPushParams(params);
+    const owned = await ownedTask(caller, query.taskId, 0);
+    let after;
+    if (query.pageToken !== undefined) {
+        after = Buffer.from(query.pageToken, "base64url").toString("utf8");
+        if (after === "")
+            a2aFail("invalidParams", "pageToken is not one this agent issued", {}, "pageToken");
+    }
+    const rows = await caller.ctx.store.tx((t) => t.pushConfigs(owned.sessionId, owned.task.id, { ...(after !== undefined ? { after } : {}), limit: query.pageSize + 1 }));
+    const page = rows.slice(0, query.pageSize);
+    return {
+        configs: page.map(configView),
+        nextPageToken: rows.length > query.pageSize ? Buffer.from(page.at(-1).configId, "utf8").toString("base64url") : "",
+    };
+}
+async function deletePushConfig(caller, params) {
+    requirePush(caller);
+    const ref = parsePushConfigRef(params);
+    const owned = await ownedTask(caller, ref.taskId, 0);
+    // Idempotent: a config already gone is deleted.
+    await caller.ctx.store.tx((t) => t.deletePushConfig(owned.sessionId, owned.task.id, ref.id));
+    return {};
+}
+/**
+ * Waits until the task's turn ends, pauses or has an uncertain effect, the caller hangs up, or
+ * the Tenant's Runtime limit `a2aWaitMs` passes: after it, the task is returned as it is
+ * (`WORKING`, or `SUBMITTED` while queued) and keeps running, and the caller polls `GetTask` or
+ * waits for pushes. A queued message's task is followed to the turn that takes it. Follows the
+ * session's shared stream from the command's cursor, so the events the task is built from are
+ * there when it returns. A feed that ends (reset, deleted, closing) ends the wait: the task says
+ * what the session says then.
+ */
+async function settled(ctx, sessionId, accepted, signal) {
     const stop = new AbortController();
     const { a2aWaitMs } = await ctx.store.tx((t) => readRuntimeLimits(t));
     const timer = setTimeout(() => stop.abort(), a2aWaitMs);
@@ -338,12 +628,19 @@ async function settled(ctx, sessionId, turnId, cursor, signal) {
     signal.addEventListener("abort", hangup, { once: true });
     if (signal.aborted)
         stop.abort();
+    let turnId = accepted.turnId;
     try {
-        for await (const event of observeSession(ctx, sessionId, cursor, {
+        for await (const event of observeSession(ctx, sessionId, accepted.cursor, {
             signal: stop.signal,
-        }))
-            if (event.turnId === turnId && SETTLED_EVENTS.has(event.type))
+        })) {
+            if (turnId === undefined &&
+                event.type === "command.message" &&
+                event.turnId &&
+                payloadOf(event).queuedMessageId === accepted.queuedMessageId)
+                turnId = event.turnId;
+            if (turnId !== undefined && event.turnId === turnId && SETTLED_EVENTS.has(event.type))
                 return;
+        }
     }
     finally {
         clearTimeout(timer);