@nylorun/runtime 0.36.1-beta → 0.37.0-beta

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.37.0-beta
+
+### Minor Changes
+
+- d48b6ef: The A2A endpoint serves the Nylorun A2A profile v2 (Host feature `a2a-profile-v2`, Engine R1).
+
+  - **Push notifications.** The four push config methods and `configuration.taskPushNotificationConfig` in `SendMessage`. Each task update is POSTed as one A2A `StreamResponse`, at least once, with `X-A2A-Notification-Token` and Standard Webhooks signatures (`webhook-id`, `webhook-timestamp`, `webhook-signature`) made with the new Runtime config `a2a.push.secret` (`NYLORUN_A2A_PUSH_SECRET`, `whsec_…`). Private hosts must be listed in `a2a.push.allowHosts` (`NYLORUN_A2A_PUSH_ALLOW_HOSTS`, `host:port` or `host:*`). Failed pushes are retried with backoff for 24 hours (Host tuning `a2a.pushRetry`, `a2a.pushMaxAgeMs`), then dropped. Configs and pushes live in two new tables (migration 0039).
+  - **Queued follow-ups.** A message to a busy context is queued and answered with the task that takes it (`TASK_STATE_SUBMITTED`); `metadata.delivery: "reject"` keeps `UnsupportedOperationError` with reason `CONTEXT_BUSY`.
+  - **Interactions.** Approvals and connection asks are `AUTH_REQUIRED`, questions `INPUT_REQUIRED`, shown under `interactions/v1`; an answer on the same task (`{ interactionId, approved }` or `{ interactionId, value }`) maps to `approve` or `respond`, with the caller as `approvedBy`. Text never approves.
+  - **Progress, telemetry, effects.** `plan.updated` events become `progress/v1`; the terminal status carries `telemetry/v1` (totals and trace id); an uncertain effect `effects/v1`.
+  - **Files.** `url` parts are fetched and stored like `raw` ones; the files a task writes are artifacts whose `url` points at the new `GET /v1/a2a/files/{artifactId}/versions/{version}`, served only to the same subject, with `files/v1`.
+  - **Extensions and card.** `A2A-Extensions` activates the five extensions and is echoed; data of the others is left out. The card lists the Runtime's JSON-RPC interface (A2A 1.0), `streaming: false`, `pushNotifications`, and the five extensions (`required: false`).
+  - ProtoJSON's original field names (`task_id`) are accepted in A2A params.
+
+- d48b6ef: An agent manifest names the model its agent runs on (Host feature `agent-model`).
+
+  - **`harness.model`**: `<provider>/<model>`, such as `anthropic/claude-sonnet-4-5` (the provider's id, a `/`, then the model's id, which may hold a `/`; at most 200 characters). In an agent folder it is `model:` in `AGENT.md`'s frontmatter; the compiler refuses any other shape (`value_invalid`) and a `model` in an agent under `agents/`, which runs on the root agent's. `harness.manifest.json` takes it too, and the composer keeps it.
+  - **A new session starts on it.** A session opened on a version that names a model gets it as its own model (`GET /v1/sessions/{id}/model` answers `source: "session"`), as `PUT /v1/sessions/{id}/model` would choose it, when the provider is connected and its catalog lists the model. Otherwise the session has none and the Tenant's model applies; nothing fails. Sessions opened by the A2A server and by triggers get it too. An explicit choice still replaces it, and an open session keeps its model across versions.
+  - `agentModelChoice` and `AgentModelSchema` in `@nylorun/core/contracts`.
+  - The JSON Schema documents that gained the field are published at new ids: `agent-manifest/v8.1.json`, `harness-manifest/v1.1.json` and `agent-folder/v1/agent-md.1.json`; the old ids are retired. `manifestSchemaVersion` stays 8.
+
+- d48b6ef: An agent keeps a durable plan (A2A profile v2, `progress/v1`; A2A-E10).
+
+  - **`plan.updated`**, a new durable session event: `{ steps: [{ label, state, note? }] }`, the agent's whole plan each time, never a diff. `state` is `pending`, `active`, `done`, `blocked` or `skipped`; at most 20 steps, labels of at most 120 and notes of at most 280 characters (`PLAN_LIMITS`, `PLAN_STEP_STATES`, `PlanUpdatedPayloadSchema` in `@nylorun/core/contracts`). The Runtime records and serves it like any public event, with the harness as its writer (evidence `claimed`), and the OpenAPI document lists it.
+  - **`update_plan`**, a built-in tool of our engine, off by default. A version opts in with `harness.loop.plan: true` (in an agent folder, `loop: { plan: true }` in `AGENT.md`'s frontmatter); the session's root agent then gets the tool, unless it declares its own tool of that name. A call takes `{ steps: [...] }`, cuts long labels and notes (ending in `…`) and steps past 20 rather than refusing them, claims one `plan.updated` and answers `Plan updated`. A malformed plan is a failed result the model sees.
+  - **Harness API**: `plan.updated` is a claim a harness may make (`HARNESS_CLAIMS`), additive within v5. The JSON Schema document is now published as `https://docs.nylorun.com/schemas/harness-api/v5.1.json`; `v5.json` is retired.
+  - The agent folder compiler takes `loop.plan` (true or false) and suggests it for a close typo.
+
+- d48b6ef: The Runtime keeps a turn index and serves it as a change feed (Host feature `turns`, A2A-E1 to E3).
+
+  - **The turn index.** Every turn has a row: its session, Agent, status (`running`, `paused`, `completed`, `failed`, `cancelled`), start, end, last change, totals and, for an A2A context, its context and task id. It is written in the same transaction as the event that changes the turn, so it always agrees with the session's log. Migration `0041_turn_index_backfill` indexes the turns already recorded when the Runtime first starts on this version.
+  - **`GET /v1/turns`** pages the turns in the order they changed: pass the page's `cursor` as `changedAfter` to read on (a turn comes again each time it changes, and the cursor comes back even when nothing changed), `limit` up to 500 (default 100). `sessionId` reads one session's turns, oldest first. An application key reads the whole Tenant; acting for a person, only their sessions' turns. A client that missed pushes catches up with one call per interval.
+  - **A2A `ListTasks`** is served: the caller's tasks with the Agent, latest status change first, filtered by `contextId`, `status` and `statusTimestampAfter`, paged with `pageSize` (up to 100, default 50) and `pageToken`, with `totalSize`; each task as `GetTask` answers it (interaction, `progress/v1` and `telemetry/v1` metadata), with history only for `historyLength` and artifacts only for `includeArtifacts`. A paused task is `AUTH_REQUIRED` for an approval or a connection and `INPUT_REQUIRED` for a question, and the `status` filter agrees. `GetTask`, `CancelTask`, replies and push configs find a task (a queued message's id too, once a turn took it) through the index and read only that turn's events.
+  - **A2A contexts are listable.** The session of a context now carries `info.a2a` (`contextId` and the subject); a context opened by an earlier version gets it with its next message. Its session id is still the one-way hash of the subject, Agent and context.
+  - `@nylorun/core` adds `TurnSummarySchema`, `TurnChangesPageSchema` and `TURN_STATUSES`.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin harness to the tested release.
+- Updated dependencies [d48b6ef]
+- Updated dependencies [d48b6ef]
+- Updated dependencies [d48b6ef]
+- Updated dependencies [d48b6ef]
+- Updated dependencies [d48b6ef]
+- Updated dependencies
+  - @nylorun/core@0.32.0-beta
+  - @nylorun/harness@0.30.0-beta
+
 ## 0.36.1-beta
 
 ### Patch Changes

package/README.md

@@ -340,6 +340,16 @@ requests without `limit` retain their response shapes. These are public APIs for
 CLI and custom clients; clients never need database access. See the
 [API contracts, authorization, SDK examples and Studio handoff](https://github.com/nylorun/agents/blob/main/runtime/docs/session-reads.md).
 
+## Turns
+
+Hosts advertising `turns` keep a turn index, written with the events that change each turn, and
+serve it as a change feed: `GET /v1/turns?changedAfter=<cursor>&limit=<1..500>` pages the turns a
+caller may see in the order they changed (a turn again each time it changes), each with its
+session, Agent, status, start and end, last change, totals and A2A context and task. Pass the
+page's `cursor` as `changedAfter` to read on; `sessionId` reads one session's turns. An application
+key reads the whole Tenant, a subject only its own sessions'. The A2A endpoint answers `ListTasks`
+from the same index.
+
 ## Artifact pages
 
 Hosts advertising `artifact-reads` accept `GET /v1/artifacts?limit=50`, returning

package/dist/api/a2a/card.d.ts

@@ -1,8 +1,11 @@
 /**
  * The Agent Card of one Agent, from its manifest version: its id as the name, the manifest's
- * description and one skill, never its instructions, tools or MCP servers. The Runtime does not know where callers reach it, so
- * `supportedInterfaces` is empty: whoever publishes the card (the gateway in v1) adds its own
- * URL, provider and security schemes.
+ * description and one skill, never its instructions, tools or MCP servers. Its one interface is
+ * the Runtime's own JSON-RPC endpoint (A2A 1.0) at the URL the caller reached, or
+ * `NYLORUN_PUBLIC_URL`; a gateway that publishes the card (the SDK's) lists its own URL,
+ * provider and security schemes instead. Capabilities (profile v2 §3): no streaming, push
+ * notifications when the Runtime has a push secret, no extended card, and the profile's five
+ * extensions, all optional.
  */
 export interface CardDefinition {
     readonly manifest: {
@@ -23,4 +26,7 @@ export declare function inputModesFor(inputs: readonly ModelInput[] | undefined)
  * `inputModes`: the media types the agent takes, when its model reads files; default text and
  * JSON. The output modes stay text and JSON.
  */
-export declare function agentCard(agentId: string, definition: CardDefinition, inputModes?: readonly string[]): Record<string, unknown>;
+export declare function agentCard(agentId: string, definition: CardDefinition, inputModes?: readonly string[], serving?: {
+    url?: string;
+    pushNotifications?: boolean;
+}): Record<string, unknown>;

package/dist/api/a2a/card.js

@@ -1,10 +1,15 @@
 /**
  * The Agent Card of one Agent, from its manifest version: its id as the name, the manifest's
- * description and one skill, never its instructions, tools or MCP servers. The Runtime does not know where callers reach it, so
- * `supportedInterfaces` is empty: whoever publishes the card (the gateway in v1) adds its own
- * URL, provider and security schemes.
+ * description and one skill, never its instructions, tools or MCP servers. Its one interface is
+ * the Runtime's own JSON-RPC endpoint (A2A 1.0) at the URL the caller reached, or
+ * `NYLORUN_PUBLIC_URL`; a gateway that publishes the card (the SDK's) lists its own URL,
+ * provider and security schemes instead. Capabilities (profile v2 §3): no streaming, push
+ * notifications when the Runtime has a push secret, no extended card, and the profile's five
+ * extensions, all optional.
  */
 import { MODEL_IMAGE_TYPES } from "@nylorun/core/contracts";
+import { cardExtensions } from "./extensions.js";
+import { A2A_VERSION } from "./protocol.js";
 const MODES = ["text/plain", "application/json"];
 /** The media types a card advertises for each file input a model reads. */
 const INPUT_MODES = {
@@ -29,7 +34,7 @@ export function inputModesFor(inputs) {
  * `inputModes`: the media types the agent takes, when its model reads files; default text and
  * JSON. The output modes stay text and JSON.
  */
-export function agentCard(agentId, definition, inputModes = MODES) {
+export function agentCard(agentId, definition, inputModes = MODES, serving = {}) {
     const { manifest } = definition;
     const name = typeof manifest.name === "string" && manifest.name !== "" ? manifest.name : agentId;
     const description = typeof manifest.description === "string" && manifest.description !== ""
@@ -38,9 +43,16 @@ export function agentCard(agentId, definition, inputModes = MODES) {
     return {
         name,
         description,
-        supportedInterfaces: [],
+        supportedInterfaces: serving.url
+            ? [{ url: serving.url, protocolBinding: "JSONRPC", protocolVersion: A2A_VERSION }]
+            : [],
         version: definition.version,
-        capabilities: { streaming: false, pushNotifications: false, extendedAgentCard: false },
+        capabilities: {
+            streaming: false,
+            pushNotifications: serving.pushNotifications === true,
+            extendedAgentCard: false,
+            extensions: cardExtensions(),
+        },
         defaultInputModes: [...inputModes],
         defaultOutputModes: MODES,
         skills: [{ id: agentId, name, description, tags: [] }],

package/dist/api/a2a/endpoint.d.ts

@@ -1,7 +1,10 @@
 /**
  * The A2A endpoint's routes (`/v1/a2a/agents/{agentId}[/card]`), declared for serving and for
- * the Runtime's OpenAPI document. What each does is in `routes.ts`. The JSON-RPC operations are
- * A2A's (specification 1.0); the document describes the envelope and links the specification.
+ * the Runtime's OpenAPI document. What each does is in `routes.ts`; the files tasks write are
+ * served at `/v1/a2a/files/…` (`../http/routes/artifacts.ts`). The JSON-RPC operations are A2A's
+ * (specification 1.0); the document describes the envelope and links the specification and the
+ * Nylorun profile v2. `A2A-Extensions` activates the profile's extensions, and the answer echoes
+ * the ones activated.
  */
 import type { OpenAPIHono } from "@hono/zod-openapi";
 import type { TenantEnv } from "../http/app.js";

package/dist/api/a2a/endpoint.js

@@ -4,6 +4,11 @@ import { TraceHeaders, tenantRoute } from "../http/define.js";
 import { traceContextOf } from "../../traces/ids.js";
 import { jsonResponse } from "../http/respond.js";
 import { a2aCall, a2aCard } from "./routes.js";
+import { A2A_PROFILE_URL, extensionsHeader, parseExtensions } from "./extensions.js";
+/** The Runtime's URL as a caller reaches it: `NYLORUN_PUBLIC_URL`, else the request's origin. */
+function baseUrlOf(publicUrl, url) {
+    return publicUrl ?? new URL(url).origin;
+}
 const A2A_SPECIFICATION = {
     description: "The A2A specification",
     url: "https://a2a-protocol.org/latest/specification/",
@@ -16,7 +21,9 @@ const JsonRpcRequest = z
     id: z.union([z.string(), z.number(), z.null()]).optional(),
     method: z
         .string()
-        .meta({ description: "`SendMessage`, `GetTask` or `CancelTask`; others answer their A2A error" }),
+        .meta({
+        description: "`SendMessage`, `GetTask`, `CancelTask`, `CreateTaskPushNotificationConfig`, `GetTaskPushNotificationConfig`, `ListTaskPushNotificationConfigs`, `DeleteTaskPushNotificationConfig` or `ListTasks`; others answer their A2A error",
+    }),
     params: z.unknown().optional(),
 })
     .meta({ id: "A2aJsonRpcRequest" });
@@ -32,7 +39,15 @@ const JsonRpcResponse = z
     .meta({ id: "A2aJsonRpcResponse" });
 const AgentCard = z
     .looseObject({ name: z.string(), description: z.string().optional(), skills: z.array(z.unknown()).optional() })
-    .meta({ id: "A2aAgentCard", description: "The agent's A2A card, without interfaces" });
+    .meta({
+    id: "A2aAgentCard",
+    description: "The agent's A2A card: this Runtime's JSON-RPC interface (A2A 1.0), `streaming: false`, `pushNotifications` when the Runtime has a push secret, and the Nylorun profile v2 extensions, all `required: false`",
+});
+const PROFILE = { description: "The Nylorun A2A profile v2", url: A2A_PROFILE_URL };
+const ExtensionsHeader = z
+    .string()
+    .optional()
+    .meta({ description: "Comma-separated profile v2 extension URIs to activate; the answer echoes the activated ones" });
 export function a2aRoutes(api) {
     tenantRoute(api, {
         credentials: ["application", "subject", "token"],
@@ -42,21 +57,22 @@ export function a2aRoutes(api) {
         path: "/v1/a2a/agents/{agentId}/card",
         tags: TAGS,
         summary: "Get an agent's A2A card",
-        externalDocs: A2A_SPECIFICATION,
+        externalDocs: PROFILE,
         request: { params: agentId },
         responses: {
             200: { description: "The card", content: { "application/json": { schema: AgentCard } } },
         },
     }, async (c) => {
         const scope = c.get("scope");
-        return jsonResponse(200, await a2aCard(c.env.tenant, scope, c.req.param("agentId")));
+        const ctx = c.env.tenant;
+        return jsonResponse(200, await a2aCard(ctx, scope, c.req.param("agentId"), baseUrlOf(ctx.config.publicUrl, c.req.url)));
     });
     tenantRoute(api, { credentials: ["subject", "token"], scopes: ["sessions:own"] }, {
         method: "post",
         path: "/v1/a2a/agents/{agentId}",
         tags: TAGS,
         summary: "Call an agent over A2A",
-        description: "A2A 1.0 JSON-RPC, for a subject: `SendMessage` (blocking up to the Runtime limit `a2aWaitMs`, 5 minutes by default, or `returnImmediately`), `GetTask` and `CancelTask`. A message is text, one data part, or text and `raw` files (at most the Runtime limit `inlineFileBytes` each, 20 MiB by default, stored as artifacts of the context's session); a file `url` is `ContentTypeNotSupportedError`. A context is one session per subject, agent and `contextId`; a task is one turn. JSON-RPC errors are answered with 200; limits, scopes and unavailable streams stay HTTP errors.",
+        description: "A2A 1.0 JSON-RPC, for a subject, under the Nylorun profile v2 (Host feature `a2a-profile-v2`). `SendMessage` blocks up to the Runtime limit `a2aWaitMs` (5 minutes by default; then the task is answered still `WORKING`) unless `returnImmediately`; `GetTask` (with `historyLength`), `CancelTask` and `ListTasks`; and the four push notification config methods, plus `configuration.taskPushNotificationConfig` in `SendMessage`: each update is POSTed as one `StreamResponse`, signed with Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature` with the Runtime's `a2a.push.secret`) and `X-A2A-Notification-Token`, at least once, retried for up to 24 hours, to hosts the Runtime allows (`a2a.push.allowHosts` for private ones). A message to a busy context is queued and answered with the task that will take it (`TASK_STATE_SUBMITTED`); `message.metadata.delivery: \"reject\"` asks for `UnsupportedOperationError` (reason `CONTEXT_BUSY`) instead. A message is text, one data part, or text with `raw` files (stored as artifacts of the context's session) and `url` files (fetched by the Runtime), each at most the Runtime limit `inlineFileBytes` (20 MiB by default). An approval, question or connection the task waits for (`AUTH_REQUIRED` or `INPUT_REQUIRED`) is shown under `interactions/v1` and answered on the same task with `{ interactionId, approved }` or `{ interactionId, value }` under that URI in the message's `metadata`; text never approves. Artifacts carry the turn's output and the files it wrote, as `url` parts at `/v1/a2a/files/…` with `files/v1`; the task's metadata carries `progress/v1`, `telemetry/v1` and `effects/v1`. Extension data is answered only for the extensions activated with `A2A-Extensions`. A context is one session per subject, agent and `contextId`; a task is one turn. JSON-RPC errors are answered with 200; limits, scopes and unavailable streams stay HTTP errors. Not served: streaming, `GetExtendedAgentCard`.",
         externalDocs: A2A_SPECIFICATION,
         request: {
             params: agentId,
@@ -64,23 +80,29 @@ export function a2aRoutes(api) {
                 "A2A-Version": z.string().optional().meta({ description: "Or the `A2A-Version` header: `1.0`" }),
             }),
             body: { required: true, content: { "application/json": { schema: JsonRpcRequest } } },
-            headers: TraceHeaders,
+            headers: TraceHeaders.extend({ "A2A-Extensions": ExtensionsHeader }),
         },
         responses: {
             200: {
                 description: "The JSON-RPC answer: a result, or an A2A error",
+                headers: z.object({ "A2A-Extensions": ExtensionsHeader }),
                 content: { "application/json": { schema: JsonRpcResponse } },
             },
         },
     }, async (c) => {
         const scope = c.get("scope");
+        const ctx = c.env.tenant;
         const version = c.env.incoming.headers["a2a-version"];
+        const extensions = parseExtensions(c.req.header("a2a-extensions"));
         const trace = traceContextOf(c.req.raw.headers);
-        return jsonResponse(200, await a2aCall(c.env.tenant, scope, c.req.param("agentId"), {
+        const echo = extensionsHeader(extensions);
+        return jsonResponse(200, await a2aCall(ctx, scope, c.req.param("agentId"), {
             // A message may carry files inline.
-            body: async () => readText(c.req.raw, await bodyLimit(c.env.tenant, "inline")),
+            body: async () => readText(c.req.raw, await bodyLimit(ctx, "inline")),
             version: typeof version === "string" ? version : (c.req.query("A2A-Version") ?? null),
             ...(trace ? { trace } : {}),
-        }, c.env.outgoing));
+            extensions,
+            baseUrl: baseUrlOf(ctx.config.publicUrl, c.req.url),
+        }, c.env.outgoing), echo ? { "A2A-Extensions": echo } : {});
     });
 }

package/dist/api/a2a/extensions.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The Nylorun A2A profile v2 (`docs.nylorun.com/a2a/profile/v2`, Host feature `a2a-profile-v2`):
+ * five extensions, each declared on the Agent Card with `required: false`. A client activates
+ * them with the `A2A-Extensions` request header (A2A §4.6); the Runtime echoes the ones it
+ * activated in the same header, and keeps the data of the others out of what it answers, so a
+ * client that activates none gets plain A2A 1.0. Data travels in `metadata` keyed by the URI.
+ */
+/** The profile's page: every extension's card entry links it. */
+export declare const A2A_PROFILE_URL = "https://docs.nylorun.com/a2a/profile/v2";
+/** The extension URIs (exact strings; profile v2 §2). */
+export declare const A2A_EXTENSIONS: {
+    /** An open interaction on a status message, and the caller's answer on a reply message. */
+    readonly interactions: "https://docs.nylorun.com/a2a/interactions/v1";
+    /** `uncertain`: the effect whose outcome was lost, on a status update. */
+    readonly effects: "https://docs.nylorun.com/a2a/effects/v1";
+    /** The agent's plan (`plan.updated`), on working status updates and the task. */
+    readonly progress: "https://docs.nylorun.com/a2a/progress/v1";
+    /** The turn's totals and trace id, on the terminal status update and the task. */
+    readonly telemetry: "https://docs.nylorun.com/a2a/telemetry/v1";
+    /** A file artifact's kind, path, version, size and `sha256`. */
+    readonly files: "https://docs.nylorun.com/a2a/files/v1";
+};
+export type A2aExtension = (typeof A2A_EXTENSIONS)[keyof typeof A2A_EXTENSIONS];
+/** Every extension: what a push config registered without the header keeps. */
+export declare const ALL_EXTENSIONS: ReadonlySet<string>;
+/** The card's `capabilities.extensions`: all five, optional, linking the profile. */
+export declare function cardExtensions(): Record<string, unknown>[];
+/**
+ * The extensions an `A2A-Extensions` header activates: the comma-separated URIs this Runtime
+ * serves, in the profile's order. Unknown URIs are ignored (A2A §4.6: an agent activates the
+ * ones it supports).
+ */
+export declare function parseExtensions(header: string | null | undefined): Set<string>;
+/** The `A2A-Extensions` answer header for `active`, or undefined when none is. */
+export declare function extensionsHeader(active: ReadonlySet<string>): string | undefined;
+/**
+ * `value` without the data of the extensions `active` leaves out: their keys in every `metadata`
+ * object (an emptied one goes), and their URIs in every `extensions` list. Parts' `data` is the
+ * agent's or caller's own and is never read. Returns a copy.
+ */
+export declare function keepExtensions<T>(value: T, active: ReadonlySet<string>): T;

package/dist/api/a2a/extensions.js

@@ -0,0 +1,92 @@
+/**
+ * The Nylorun A2A profile v2 (`docs.nylorun.com/a2a/profile/v2`, Host feature `a2a-profile-v2`):
+ * five extensions, each declared on the Agent Card with `required: false`. A client activates
+ * them with the `A2A-Extensions` request header (A2A §4.6); the Runtime echoes the ones it
+ * activated in the same header, and keeps the data of the others out of what it answers, so a
+ * client that activates none gets plain A2A 1.0. Data travels in `metadata` keyed by the URI.
+ */
+/** The profile's page: every extension's card entry links it. */
+export const A2A_PROFILE_URL = "https://docs.nylorun.com/a2a/profile/v2";
+/** The extension URIs (exact strings; profile v2 §2). */
+export const A2A_EXTENSIONS = {
+    /** An open interaction on a status message, and the caller's answer on a reply message. */
+    interactions: "https://docs.nylorun.com/a2a/interactions/v1",
+    /** `uncertain`: the effect whose outcome was lost, on a status update. */
+    effects: "https://docs.nylorun.com/a2a/effects/v1",
+    /** The agent's plan (`plan.updated`), on working status updates and the task. */
+    progress: "https://docs.nylorun.com/a2a/progress/v1",
+    /** The turn's totals and trace id, on the terminal status update and the task. */
+    telemetry: "https://docs.nylorun.com/a2a/telemetry/v1",
+    /** A file artifact's kind, path, version, size and `sha256`. */
+    files: "https://docs.nylorun.com/a2a/files/v1",
+};
+const ALL = new Set(Object.values(A2A_EXTENSIONS));
+/** Every extension: what a push config registered without the header keeps. */
+export const ALL_EXTENSIONS = ALL;
+const DESCRIPTIONS = {
+    [A2A_EXTENSIONS.interactions]: "Typed approvals, questions and connection requests on the status message, answered on the same task",
+    [A2A_EXTENSIONS.effects]: "The effect whose outcome was lost (`uncertain`) while the task stays working",
+    [A2A_EXTENSIONS.progress]: "The agent's plan: up to 20 steps, each with a label, a state and a note",
+    [A2A_EXTENSIONS.telemetry]: "The task's totals (steps, tokens, costUsd) and trace id, when it ends",
+    [A2A_EXTENSIONS.files]: "Each file artifact's kind, path, version, size and sha256",
+};
+/** The card's `capabilities.extensions`: all five, optional, linking the profile. */
+export function cardExtensions() {
+    return Object.values(A2A_EXTENSIONS).map((uri) => ({
+        uri,
+        description: DESCRIPTIONS[uri],
+        required: false,
+        params: { profile: A2A_PROFILE_URL },
+    }));
+}
+/**
+ * The extensions an `A2A-Extensions` header activates: the comma-separated URIs this Runtime
+ * serves, in the profile's order. Unknown URIs are ignored (A2A §4.6: an agent activates the
+ * ones it supports).
+ */
+export function parseExtensions(header) {
+    const asked = new Set((header ?? "")
+        .split(",")
+        .map((uri) => uri.trim())
+        .filter((uri) => uri !== ""));
+    return new Set(Object.values(A2A_EXTENSIONS).filter((uri) => asked.has(uri)));
+}
+/** The `A2A-Extensions` answer header for `active`, or undefined when none is. */
+export function extensionsHeader(active) {
+    return active.size === 0 ? undefined : [...active].join(", ");
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * `value` without the data of the extensions `active` leaves out: their keys in every `metadata`
+ * object (an emptied one goes), and their URIs in every `extensions` list. Parts' `data` is the
+ * agent's or caller's own and is never read. Returns a copy.
+ */
+export function keepExtensions(value, active) {
+    if (active.size === ALL.size)
+        return value;
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (!isObject(node))
+            return node;
+        const out = {};
+        for (const [key, child] of Object.entries(node)) {
+            if (key === "data")
+                out[key] = child;
+            else if (key === "metadata" && isObject(child)) {
+                const kept = Object.fromEntries(Object.entries(child).filter(([name]) => !ALL.has(name) || active.has(name)));
+                if (Object.keys(kept).length > 0)
+                    out[key] = kept;
+            }
+            else if (key === "extensions" && Array.isArray(child)) {
+                const kept = child.filter((uri) => typeof uri !== "string" || !ALL.has(uri) || active.has(uri));
+                if (kept.length > 0)
+                    out[key] = kept;
+            }
+            else
+                out[key] = walk(child);
+        }
+        return out;
+    };
+    return walk(value);
+}

package/dist/api/a2a/list.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A2A tasks read from the turn index (Host feature `turns`): `ListTasks` (A2A 1.0 §3.1.4) and
+ * the bounded reads of one turn's events that `GetTask`, `CancelTask` and replies use. A context
+ * is listable because `openContext` writes `info.a2a` on its session, which the index copies into
+ * each turn's row; nothing here scans a session's whole history.
+ *
+ * `ListTasks` is scoped before any lookup: the caller's own subject and this endpoint's Agent,
+ * A2A contexts only. Tasks come latest status change first; a page's token is the last task's
+ * position, bound to the caller and the filters. Each task is built as `GetTask` builds it, from
+ * its turn's own events (state, interaction, `progress/v1` and `telemetry/v1` metadata), with
+ * `history` only for `historyLength` and artifacts only for `includeArtifacts`; its
+ * `status.timestamp` is when its status last changed, which `statusTimestampAfter` compares with.
+ * A paused turn is `AUTH_REQUIRED` while it waits for an approval or a connection, and
+ * `INPUT_REQUIRED` for a question (the index's `waitingFor`). A queued message no turn took yet
+ * (`SUBMITTED`) is not a turn, so it is not listed.
+ */
+import type { LiveEvent } from "@nylorun/core/contracts";
+import type { TurnRow } from "../../store/types.js";
+import { type Session, type SessionAccess, type TenantContext } from "../../tenant/context.js";
+import { type Task, type TaskState } from "./protocol.js";
+/** `ListTasks`' page size when the request names none, and the most it may ask. */
+export declare const LIST_PAGE_DEFAULT = 50;
+export declare const LIST_PAGE_MAX = 100;
+/** `ListTasks` params, checked. */
+export interface ListParams {
+    readonly contextId?: string;
+    readonly status?: TaskState;
+    /** ISO, normalized to the index's form (`toISOString`). */
+    readonly statusTimestampAfter?: string;
+    readonly pageSize: number;
+    readonly pageToken?: string;
+    readonly historyLength?: number;
+    readonly includeArtifacts: boolean;
+}
+/** `ListTasks` result (A2A 1.0): `nextPageToken` is empty on the last page. */
+export interface ListTasksResult {
+    tasks: Task[];
+    nextPageToken: string;
+    pageSize: number;
+    totalSize: number;
+}
+/** `ListTasks` params (A2A 1.0 §3.1.4), checked in the order a client can fix them. */
+export declare function parseListParams(params: Record<string, unknown>): ListParams;
+/**
+ * One turn's events, in stream order, read from its first lifecycle event: up to its last one
+ * when it has ended, else to the stream's tail. Never the session's whole history.
+ */
+export declare function indexedTurnEvents(ctx: TenantContext, row: TurnRow): Promise<LiveEvent[]>;
+/** The events of a session's turn, from the turn index; none when the session never had it. */
+export declare function turnEventsOf(ctx: TenantContext, sessionId: string, turnId: string): Promise<LiveEvent[]>;
+/** The caller of `ListTasks`: one subject, with one Agent. */
+export interface ListCaller {
+    readonly ctx: TenantContext;
+    readonly access: SessionAccess;
+    readonly agentId: string;
+}
+/** Builds one listed turn's task as `GetTask` does (`routes.ts`), or undefined when it has none. */
+export type BuildListedTask = (row: TurnRow, session: Session, historyLength: number) => Promise<Task | undefined>;
+/** `ListTasks`: the caller's tasks with this Agent, from the turn index. */
+export declare function listTasks(caller: ListCaller, params: ListParams, build: BuildListedTask): Promise<ListTasksResult>;

package/dist/api/a2a/list.js

@@ -0,0 +1,169 @@
+import { encodeCursor } from "../../record/index.js";
+import { historyCursor, readCursor } from "../../reads/cursor.js";
+import { ENDED_TURN_STATUSES } from "../../store/postgres/turns.js";
+import { loadSession } from "../../tenant/context.js";
+import { HttpError } from "../../tenant/http.js";
+import { readHistory } from "../../tenant/session-streams.js";
+import { a2aFail, parseHistoryLength } from "./protocol.js";
+import { contextSessionId } from "./tasks.js";
+/** `ListTasks`' page size when the request names none, and the most it may ask. */
+export const LIST_PAGE_DEFAULT = 50;
+export const LIST_PAGE_MAX = 100;
+/**
+ * The turn index states each A2A state is (profile v2 §1): a paused turn by what its first open
+ * interaction asks for. `SUBMITTED` (a queued message), `REJECTED` and anything else: none.
+ */
+const TURN_STATES = {
+    TASK_STATE_WORKING: [{ status: "running" }],
+    TASK_STATE_INPUT_REQUIRED: [{ status: "paused", waitingFor: ["question"] }],
+    TASK_STATE_AUTH_REQUIRED: [{ status: "paused", waitingFor: ["approval", "connection"] }],
+    TASK_STATE_COMPLETED: [{ status: "completed" }],
+    TASK_STATE_FAILED: [{ status: "failed" }],
+    TASK_STATE_CANCELED: [{ status: "cancelled" }],
+};
+const TASK_STATES = [
+    "TASK_STATE_SUBMITTED",
+    "TASK_STATE_WORKING",
+    "TASK_STATE_INPUT_REQUIRED",
+    "TASK_STATE_AUTH_REQUIRED",
+    "TASK_STATE_COMPLETED",
+    "TASK_STATE_FAILED",
+    "TASK_STATE_CANCELED",
+    "TASK_STATE_REJECTED",
+];
+const VISIBLE = /^[\x21-\x7e]{1,200}$/;
+const present = (value) => value !== undefined && value !== null && value !== "";
+/** `ListTasks` params (A2A 1.0 §3.1.4), checked in the order a client can fix them. */
+export function parseListParams(params) {
+    const { contextId, status, statusTimestampAfter, pageSize, pageToken, includeArtifacts } = params;
+    if (present(contextId) && (typeof contextId !== "string" || !VISIBLE.test(contextId)))
+        a2aFail("invalidParams", "contextId must be 1 to 200 visible ASCII characters", {}, "contextId");
+    if (present(status) &&
+        status !== "TASK_STATE_UNSPECIFIED" &&
+        !TASK_STATES.includes(status))
+        a2aFail("invalidParams", "status must be a TaskState", {}, "status");
+    let since;
+    if (present(statusTimestampAfter)) {
+        const time = typeof statusTimestampAfter === "string" &&
+            /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/.test(statusTimestampAfter)
+            ? new Date(statusTimestampAfter)
+            : undefined;
+        if (!time || Number.isNaN(time.getTime()))
+            a2aFail("invalidParams", "statusTimestampAfter must be an ISO 8601 timestamp", {}, "statusTimestampAfter");
+        since = time.toISOString();
+    }
+    if (present(pageSize) &&
+        (typeof pageSize !== "number" ||
+            !Number.isInteger(pageSize) ||
+            pageSize < 1 ||
+            pageSize > LIST_PAGE_MAX))
+        a2aFail("invalidParams", `pageSize must be an integer from 1 to ${LIST_PAGE_MAX}`, {}, "pageSize");
+    if (present(pageToken) && typeof pageToken !== "string")
+        a2aFail("invalidParams", "pageToken must be a string", {}, "pageToken");
+    if (includeArtifacts !== undefined && includeArtifacts !== null && typeof includeArtifacts !== "boolean")
+        a2aFail("invalidParams", "includeArtifacts must be a boolean", {}, "includeArtifacts");
+    const historyLength = parseHistoryLength(params.historyLength, "historyLength");
+    return {
+        ...(present(contextId) ? { contextId: contextId } : {}),
+        ...(present(status) && status !== "TASK_STATE_UNSPECIFIED" ? { status: status } : {}),
+        ...(since !== undefined ? { statusTimestampAfter: since } : {}),
+        pageSize: present(pageSize) ? pageSize : LIST_PAGE_DEFAULT,
+        ...(present(pageToken) ? { pageToken: pageToken } : {}),
+        ...(historyLength !== undefined ? { historyLength } : {}),
+        includeArtifacts: includeArtifacts === true,
+    };
+}
+/**
+ * One turn's events, in stream order, read from its first lifecycle event: up to its last one
+ * when it has ended, else to the stream's tail. Never the session's whole history.
+ */
+export async function indexedTurnEvents(ctx, row) {
+    const after = row.firstSeq > 0 ? encodeCursor(row.sessionId, row.firstSeq - 1) : undefined;
+    const { items } = ENDED_TURN_STATUSES.has(row.status)
+        ? await readHistory(ctx, row.sessionId, after === undefined
+            ? undefined
+            : historyCursor(ctx.config.tenantId, row.sessionId).encode(after), undefined, row.lastSeq - row.firstSeq + 1)
+        : await readHistory(ctx, row.sessionId, after, undefined);
+    return items.filter((event) => event.turnId === row.turnId);
+}
+/** The events of a session's turn, from the turn index; none when the session never had it. */
+export async function turnEventsOf(ctx, sessionId, turnId) {
+    const row = await ctx.store.tx((t) => t.turn(sessionId, turnId));
+    return row ? indexedTurnEvents(ctx, row) : [];
+}
+/** `ListTasks`: the caller's tasks with this Agent, from the turn index. */
+export async function listTasks(caller, params, build) {
+    const { ctx, access, agentId } = caller;
+    const owner = access.owner;
+    const token = readCursor(ctx.config.tenantId, "a2a-tasks", {
+        owner,
+        agentId,
+        contextId: params.contextId ?? null,
+        status: params.status ?? null,
+        statusTimestampAfter: params.statusTimestampAfter ?? null,
+    });
+    let key;
+    try {
+        key = token.decode(params.pageToken);
+    }
+    catch (error) {
+        if (!(error instanceof HttpError))
+            throw error;
+        return a2aFail("invalidParams", "pageToken is not one this request returned", {}, "pageToken");
+    }
+    if (key && (key.length !== 3 || key.some((part) => typeof part !== "string")))
+        a2aFail("invalidParams", "pageToken is not one this request returned", {}, "pageToken");
+    const states = params.status === undefined ? undefined : (TURN_STATES[params.status] ?? []);
+    const { turns, total } = await ctx.store.tx((t) => t.listTurns({
+        ownerUserId: owner,
+        agentId,
+        a2a: true,
+        ...(params.contextId === undefined
+            ? {}
+            : { sessionId: contextSessionId(owner, agentId, params.contextId) }),
+        ...(states === undefined ? {} : { states }),
+        ...(params.statusTimestampAfter === undefined ? {} : { changedSince: params.statusTimestampAfter }),
+        ...(key ? { after: { changedAt: key[0], sessionId: key[1], turnId: key[2] } } : {}),
+        limit: params.pageSize + 1,
+    }));
+    const page = turns.slice(0, params.pageSize);
+    const last = page.at(-1);
+    const tasks = [];
+    const sessions = new Map();
+    for (const row of page) {
+        // Only a context the A2A server opened for this caller: its session id is the context's.
+        if (contextSessionId(owner, agentId, row.a2aContextId) !== row.sessionId)
+            continue;
+        if (!sessions.has(row.sessionId))
+            sessions.set(row.sessionId, await sessionOf(caller, row.sessionId));
+        const session = sessions.get(row.sessionId);
+        const built = session ? await build(row, session, params.historyLength ?? 0) : undefined;
+        if (!built)
+            continue;
+        const { artifacts, ...task } = built;
+        tasks.push({
+            ...task,
+            status: { ...task.status, timestamp: row.changedAt },
+            ...(params.includeArtifacts && artifacts ? { artifacts } : {}),
+        });
+    }
+    return {
+        tasks,
+        nextPageToken: turns.length > params.pageSize && last
+            ? token.encode([last.changedAt, last.sessionId, last.turnId])
+            : "",
+        pageSize: params.pageSize,
+        totalSize: total,
+    };
+}
+/** The caller's session for a listed task, or undefined when it is gone. */
+async function sessionOf(caller, sessionId) {
+    try {
+        return await loadSession(caller.ctx, sessionId, caller.access);
+    }
+    catch (error) {
+        if (error instanceof HttpError && error.status === 404)
+            return undefined;
+        throw error;
+    }
+}