@nylorun/runtime 0.36.1-beta → 0.38.0-beta

package/dist/store/postgres/schema.js

@@ -171,6 +171,8 @@ export const agents = nylorun.table("agents", {
     volumeId: text(),
     /** The workload image by digest, from the first ready pod on (Q14): later pods run it. */
     imageDigest: textC(),
+    /** The engine the image carries (ADR-99): `{ version, digest? }`, from a join of its engine. */
+    engineImage: jsonText(),
     /**
      * The disk lease (R2d step 3): `{ kind, version?, startedAt, until }` while a snapshot, a
      * restore or a seed copies the disk; turns are refused until it ends or `until` passes.
@@ -495,6 +497,46 @@ export const modelBudgets = nylorun.table("model_budgets", {
     limitTokens: bigint({ mode: "number" }),
     updatedAt: text().notNull(),
 }, (t) => [primaryKey({ name: "model_budgets_pkey", columns: [t.scope, t.scopeId] })]);
+/**
+ * The turn index (A2A design §9, Host feature `turns`): one row per turn, written by `Tx.event`
+ * in the transaction of each event that changes the turn (`store/postgres/turns.ts`), so it
+ * agrees with the session's log. The session's Agent, owner and A2A context are copied in when
+ * the turn starts. `txid` is the transaction that last changed the row: the change feed reads
+ * rows in its order, only below every transaction still running (`pg_snapshot_xmin`), as the
+ * model call export does. `firstSeq` and `lastSeq` bound the turn's lifecycle events in the log.
+ */
+export const turns = nylorun.table("turns", {
+    sessionId: textC().notNull(),
+    turnId: textC().notNull(),
+    agentId: textC().notNull(),
+    /** The session owner (`ownerUserId`); null for an application's own session. */
+    ownerUserId: textC(),
+    /** `info.a2a.contextId` of an A2A context's session. */
+    a2aContextId: textC(),
+    status: text({ enum: ["running", "paused", "completed", "failed", "cancelled"] }).notNull(),
+    /** ISO times: of the turn's first event, its end, and its last status change. */
+    startedAt: textC().notNull(),
+    endedAt: textC(),
+    changedAt: textC().notNull(),
+    /** The end facts' `totals` (`{steps, tokens, costUsd}`), once it ended with them. */
+    totals: jsonText(),
+    /**
+     * While `paused`: what its first open interaction asks for, as profile v2 names it
+     * (`question`, `approval` or `connection`); null otherwise.
+     */
+    waitingFor: text({ enum: ["question", "approval", "connection"] }),
+    /** The queued messages it took (protocol 17): their A2A task ids name it too. */
+    queuedMessageIds: text().array().notNull().default(sql `'{}'`),
+    firstSeq: bigint({ mode: "number" }).notNull(),
+    lastSeq: bigint({ mode: "number" }).notNull(),
+    txid: xid8().notNull().default(sql `pg_current_xact_id()`),
+}, (t) => [
+    primaryKey({ name: "turns_pkey", columns: [t.sessionId, t.turnId] }),
+    index("turns_turn").on(t.turnId),
+    index("turns_changes").on(t.txid, t.sessionId, t.turnId),
+    index("turns_owner_changes").on(t.ownerUserId, t.txid),
+    index("turns_owner_agent").on(t.ownerUserId, t.agentId, t.changedAt),
+]);
 /**
  * Each session's queue (protocol 17, D76): messages that arrived while its turn ran or waited, in
  * order (`seq`), until a turn takes them. A row holds the command as sent, the turn input its
@@ -700,6 +742,58 @@ export const sandboxSignals = nylorun.table("sandbox_signals", {
     index("sandbox_signals_created_at").on(t.createdAt),
     check("sandbox_signals_kind_check", sql `${t.kind} IN ('reconcile', 'arm')`),
 ]);
+/**
+ * A2A push notification configs (Host feature `a2a-profile-v2`): where a task's updates go, one
+ * row per task and config id (`taskId`: the A2A id its caller knows, a queued message's own until
+ * a turn takes it; `turnId`: the turn it follows). The push translator (`api/a2a/push.ts`) reads
+ * the session's events from `nextSeq` on and writes each update as an `a2a_pushes` row in one
+ * transaction; `doneAt` is set once the task's turn ended, and the row is deleted after the
+ * Host tuning's `a2a.pushConfigRetentionMs`. `extensions` are the profile extensions the caller
+ * activated when it gave the config; `baseUrl` is the Runtime's URL as that caller reached it,
+ * for file URLs; `traceId` is `telemetry/v1`'s.
+ */
+export const a2aPushConfigs = nylorun.table("a2a_push_configs", {
+    sessionId: textC().notNull(),
+    taskId: textC().notNull(),
+    configId: textC().notNull(),
+    contextId: text().notNull(),
+    turnId: textC().notNull(),
+    url: text().notNull(),
+    token: text(),
+    authentication: jsonText(),
+    baseUrl: text().notNull(),
+    extensions: jsonText().notNull(),
+    traceId: text(),
+    nextSeq: bigint({ mode: "number" }).notNull(),
+    createdAt: timestamp({ withTimezone: true, mode: "date" })
+        .notNull()
+        .default(sql `clock_timestamp()`),
+    doneAt: timestamp({ withTimezone: true, mode: "date" }),
+}, (t) => [
+    primaryKey({ name: "a2a_push_configs_pkey", columns: [t.sessionId, t.taskId, t.configId] }),
+    index("a2a_push_configs_done_at").on(t.doneAt),
+]);
+/**
+ * The push outbox (outbox kind `push`): one row per A2A update a push config is owed, its body
+ * the exact JSON sent (a `StreamResponse`), delivered after commit and by the Tenant sweep as the
+ * other outbox rows are (`attempts`, `retry_at`, `parked_at`). The row id is the Standard
+ * Webhooks `webhook-id`, the same on every attempt. A row whose config is gone, or that kept
+ * failing for the Host tuning's `a2a.pushMaxAgeMs` (24 hours), is deleted: the change feed
+ * covers what it would have said.
+ */
+export const a2aPushes = nylorun.table("a2a_pushes", {
+    id: textC().primaryKey(),
+    sessionId: textC().notNull(),
+    taskId: textC().notNull(),
+    configId: textC().notNull(),
+    body: text().notNull(),
+    createdAt: timestamp({ withTimezone: true, mode: "date" })
+        .notNull()
+        .default(sql `clock_timestamp()`),
+    attempts: integer().notNull().default(0),
+    retryAt: timestamp({ withTimezone: true, mode: "date" }),
+    parkedAt: timestamp({ withTimezone: true, mode: "date" }),
+}, (t) => [index("a2a_pushes_created_at").on(t.createdAt)]);
 // ---------------------------------------------------------------------------
 // nylorun_streams: the record
 /**

package/dist/store/postgres/store.js

@@ -59,8 +59,9 @@ import { database, driverError } from "./db.js";
 import { expectedSchemaVersion, readSchemaVersion } from "./migrate.js";
 import { hostTuning } from "../../tuning.js";
 import { createPostgresRecordReader } from "./record.js";
+import { indexTurn, listTurns, turnOfQueuedMessage, turnRow } from "./turns.js";
 import { postgresAgentRecordWriter, postgresRecordWriter } from "./record-writer.js";
-import { artifacts, artifactVersions, artifactContent, definitionFiles, definitionFileUses, commands, effects, links, modelBudgets, modelUsage, principals, sandboxes, agentEvents, agents, agentManifests, sessionEvents, sessionLogHeads, sessions, sessionQueue, agentTriggers, triggerRuns, memories, memoryVersions, toJson, toolCrossings, signingKeys, tenant, tenantSettings, vaultAudit, vaultCredentials, vaultIdempotency, vaults, sandboxSignals, wakes, } from "./schema.js";
+import { artifacts, artifactVersions, artifactContent, definitionFiles, definitionFileUses, commands, effects, links, modelBudgets, modelUsage, principals, sandboxes, agentEvents, agents, agentManifests, sessionEvents, sessionLogHeads, sessions, sessionQueue, a2aPushConfigs, a2aPushes, agentTriggers, triggerRuns, memories, memoryVersions, toJson, toolCrossings, signingKeys, tenant, tenantSettings, turns, vaultAudit, vaultCredentials, vaultIdempotency, vaults, sandboxSignals, wakes, } from "./schema.js";
 export function createPostgresSessionStore(options) {
     return new PostgresSessionStore(options);
 }
@@ -282,6 +283,7 @@ function environmentOf(row) {
                     ...(row.retiring !== null ? { retiring: row.retiring } : {}),
                     ...(row.volumeId !== null ? { volumeId: row.volumeId } : {}),
                     ...(row.imageDigest !== null ? { imageDigest: row.imageDigest } : {}),
+                    ...(row.engineImage ? { engineImage: row.engineImage } : {}),
                 },
             }
             : {}),
@@ -316,6 +318,7 @@ function podColumns(patch) {
         retiring: patch.retiring,
         volumeId: patch.volumeId,
         imageDigest: patch.imageDigest,
+        engineImage: patch.engineImage,
     };
     return Object.fromEntries(Object.entries(columns).filter(([, value]) => value !== undefined));
 }
@@ -327,7 +330,17 @@ const SIGNING_KEY_STAMP = {
 };
 /** The audit columns a row has (`ord` only orders them). */
 const { ord: _ord, ...AUDIT } = getTableColumns(vaultAudit);
-const SESSION_TABLES = [sessions, commands, effects, links, wakes, sessionQueue];
+const SESSION_TABLES = [
+    sessions,
+    commands,
+    effects,
+    links,
+    wakes,
+    sessionQueue,
+    turns,
+    a2aPushConfigs,
+    a2aPushes,
+];
 /**
  * The outbox's tables, by the kind of request each holds. Their delivery columns (`id`,
  * `created_at`, `attempts`, `retry_at`, `parked_at`) are the same.
@@ -335,7 +348,12 @@ const SESSION_TABLES = [sessions, commands, effects, links, wakes, sessionQueue]
 const OUTBOX = {
     wake: wakes,
     sandbox: sandboxSignals,
+    push: a2aPushes,
 };
+/** A push outbox row as it is delivered. */
+function outboxPush(row) {
+    return { id: row.id, sessionId: row.sessionId, taskId: row.taskId, configId: row.configId, body: row.body };
+}
 /** A wake outbox row as it is delivered: its own dedupe key, or one made from the row id. */
 function outboxWake(id, reason, dedupeKey) {
     return { reason, dedupeKey: dedupeKey ?? `wake:${id}` };
@@ -439,10 +457,25 @@ class PostgresTx {
             ...(writer ? { writer } : {}),
             maxEntryBytes: await this.maxEntryBytes(),
         });
+        // The turn index changes with the log, in this transaction (Host feature `turns`).
+        await indexTurn(db, event);
         this.events.push(event);
         this.generations.push(generation);
         return structuredClone(event);
     }
+    // --- turn index ----------------------------------------------------------
+    async turn(sessionId, turnId) {
+        this.check();
+        return turnRow(this.db, sessionId, turnId);
+    }
+    async turnOfQueuedMessage(sessionId, queuedMessageId) {
+        this.check();
+        return turnOfQueuedMessage(this.db, sessionId, queuedMessageId);
+    }
+    async listTurns(query) {
+        this.check();
+        return listTurns(this.db, query);
+    }
     // --- wake outbox ---------------------------------------------------------
     async wake(sessionId, wake) {
         this.check();
@@ -514,12 +547,27 @@ class PostgresTx {
                 due: row.dueSeconds,
             })),
         ];
+        const push = DUE(OUTBOX.push, graceMs);
+        const pushRows = await this.db
+            .select({ ...getTableColumns(a2aPushes), dueSeconds: push.dueSeconds })
+            .from(a2aPushes)
+            .where(and(isNull(a2aPushes.parkedAt), lte(push.due, now)))
+            .orderBy(push.due, a2aPushes.id)
+            .limit(limit);
+        rows.push(...pushRows.map((row) => ({
+            kind: "push",
+            id: row.id,
+            request: { kind: "push", push: outboxPush(row) },
+            createdAt: row.createdAt.toISOString(),
+            attempts: row.attempts,
+            due: row.dueSeconds,
+        })));
         rows.sort((a, b) => a.due - b.due || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
         return rows.slice(0, limit).map(({ due: _due, ...row }) => row);
     }
     async deleteOutbox(rows) {
         this.check();
-        for (const kind of ["wake", "sandbox"]) {
+        for (const kind of ["wake", "sandbox", "push"]) {
             const ids = rows.filter((row) => row.kind === kind).map((row) => row.id);
             if (ids.length > 0)
                 await this.db.delete(OUTBOX[kind]).where(inArray(OUTBOX[kind].id, ids));
@@ -538,6 +586,90 @@ class PostgresTx {
         })
             .where(eq(table.id, row.id));
     }
+    // --- A2A push (Host feature `a2a-profile-v2`) ---------------------------------
+    async putPushConfig(row) {
+        this.check();
+        const { sessionId: _s, taskId: _t, configId: _c, ...set } = row;
+        await this.db
+            .insert(a2aPushConfigs)
+            .values({ ...row, doneAt: row.doneAt ?? null })
+            .onConflictDoUpdate({
+            target: [a2aPushConfigs.sessionId, a2aPushConfigs.taskId, a2aPushConfigs.configId],
+            set: { ...set, doneAt: row.doneAt ?? null, createdAt: sql `clock_timestamp()` },
+        });
+    }
+    async pushConfig(sessionId, taskId, configId) {
+        this.check();
+        const [row] = await this.db
+            .select()
+            .from(a2aPushConfigs)
+            .where(and(eq(a2aPushConfigs.sessionId, sessionId), eq(a2aPushConfigs.taskId, taskId), eq(a2aPushConfigs.configId, configId)));
+        return row;
+    }
+    async pushConfigs(sessionId, taskId, options = {}) {
+        this.check();
+        const query = this.db
+            .select()
+            .from(a2aPushConfigs)
+            .where(and(eq(a2aPushConfigs.sessionId, sessionId), eq(a2aPushConfigs.taskId, taskId), options.after === undefined ? undefined : gt(a2aPushConfigs.configId, options.after)))
+            .orderBy(a2aPushConfigs.configId)
+            .$dynamic();
+        return options.limit === undefined ? query : query.limit(options.limit);
+    }
+    async deletePushConfig(sessionId, taskId, configId) {
+        this.check();
+        const deleted = await this.db
+            .delete(a2aPushConfigs)
+            .where(and(eq(a2aPushConfigs.sessionId, sessionId), eq(a2aPushConfigs.taskId, taskId), eq(a2aPushConfigs.configId, configId)))
+            .returning({ id: a2aPushConfigs.configId });
+        return deleted.length > 0;
+    }
+    async activePushConfigs(sessionId, options = {}) {
+        this.check();
+        const query = this.db
+            .select()
+            .from(a2aPushConfigs)
+            .where(and(eq(a2aPushConfigs.sessionId, sessionId), isNull(a2aPushConfigs.doneAt)))
+            .orderBy(a2aPushConfigs.taskId, a2aPushConfigs.configId)
+            .$dynamic();
+        return options.lock ? query.for("update") : query;
+    }
+    async pushSessions(limit, after) {
+        this.check();
+        const rows = await this.db
+            .selectDistinct({ sessionId: a2aPushConfigs.sessionId })
+            .from(a2aPushConfigs)
+            .where(and(isNull(a2aPushConfigs.doneAt), after === undefined ? undefined : gt(a2aPushConfigs.sessionId, after)))
+            .orderBy(a2aPushConfigs.sessionId)
+            .limit(limit);
+        return rows.map((row) => row.sessionId);
+    }
+    async advancePushConfig(key, change) {
+        this.check();
+        await this.db
+            .update(a2aPushConfigs)
+            .set({
+            turnId: change.turnId,
+            nextSeq: change.nextSeq,
+            traceId: change.traceId,
+            ...(change.done ? { doneAt: sql `clock_timestamp()` } : {}),
+        })
+            .where(and(eq(a2aPushConfigs.sessionId, key.sessionId), eq(a2aPushConfigs.taskId, key.taskId), eq(a2aPushConfigs.configId, key.configId)));
+    }
+    async prunePushConfigs(before) {
+        this.check();
+        const deleted = await this.db
+            .delete(a2aPushConfigs)
+            .where(lt(a2aPushConfigs.doneAt, before))
+            .returning({ id: a2aPushConfigs.configId });
+        return deleted.length;
+    }
+    async enqueuePush(push) {
+        this.check();
+        const id = `push_${randomUUID()}`;
+        await this.db.insert(a2aPushes).values({ id, ...push });
+        this.outbox.push({ kind: "push", id, request: { kind: "push", push: { id, ...push } } });
+    }
     // --- ownership -----------------------------------------------------------
     async takeOwnership(sessionId, claim) {
         this.check();

package/dist/store/postgres/turns.d.ts

@@ -0,0 +1,62 @@
+import type { EventType, TurnStatus } from "@nylorun/core/contracts";
+import type { Queryable } from "./db.js";
+import { type TurnRow } from "./schema.js";
+/** The events that change a turn's row, and the status each leaves it in. */
+export declare const TURN_EVENT_STATUS: Readonly<Partial<Record<EventType, TurnStatus>>>;
+/** The statuses a turn ends in. */
+export declare const ENDED_TURN_STATUSES: ReadonlySet<TurnStatus>;
+/** What `indexTurn` reads of an event: the envelope fields, as `appendEvent` built them. */
+export interface IndexedEvent {
+    readonly sessionId: string;
+    readonly turnId: string | null;
+    readonly seq: number;
+    readonly time: string;
+    readonly type: string;
+    readonly payload: unknown;
+}
+/** What an interaction asks for, as profile v2 names it (`api/a2a/tasks.ts` `interactionOf`). */
+export type WaitingFor = "question" | "approval" | "connection";
+/** What a `turn.paused` payload's first open interaction asks for, or null. */
+export declare function waitingForOf(payload: unknown): WaitingFor | null;
+/**
+ * Writes the change `event` makes to its turn's row, in the event's transaction (the session
+ * row is locked). An event without a turn, or of a type that changes none, writes nothing.
+ */
+export declare function indexTurn(db: Queryable, event: IndexedEvent): Promise<void>;
+/** One turn's row, or undefined when the session never had that turn. */
+export declare function turnRow(db: Queryable, sessionId: string, turnId: string): Promise<TurnRow | undefined>;
+/** The turn that took queued message `queuedMessageId` of a session, if one did. */
+export declare function turnOfQueuedMessage(db: Queryable, sessionId: string, queuedMessageId: string): Promise<TurnRow | undefined>;
+/** A status a listed turn may have: `paused` narrowed by what it waits for. */
+export interface TurnState {
+    readonly status: TurnStatus;
+    readonly waitingFor?: readonly WaitingFor[];
+}
+/** Which turns `listTurns` reads: one owner's A2A tasks with one Agent (`ListTasks`). */
+export interface TurnListQuery {
+    readonly ownerUserId: string;
+    readonly agentId: string;
+    /** Only turns of A2A contexts. */
+    readonly a2a: true;
+    /** Only this session (one A2A context's). */
+    readonly sessionId?: string;
+    /** Only turns in one of these states; empty matches none. */
+    readonly states?: readonly TurnState[];
+    /** Only turns whose status changed at or after this ISO time. */
+    readonly changedSince?: string;
+    /** Only turns after this one in the order: the last row of the previous page. */
+    readonly after?: {
+        readonly changedAt: string;
+        readonly sessionId: string;
+        readonly turnId: string;
+    };
+    readonly limit: number;
+}
+/**
+ * The turns `query` names, latest status change first (then by session and turn id, descending),
+ * at most `limit`, and how many match without `after` and `limit`.
+ */
+export declare function listTurns(db: Queryable, query: TurnListQuery): Promise<{
+    turns: TurnRow[];
+    total: number;
+}>;

package/dist/store/postgres/turns.js

@@ -0,0 +1,153 @@
+/**
+ * The turn index (A2A design §9, Host feature `turns`): the `turns` table's writes and the typed
+ * queries on it. `Tx.event` calls `indexTurn` for every event it writes, in the same
+ * transaction, so a turn's row changes exactly when its log does:
+ *
+ * - `command.message` starts the turn (`running`), copying in its session's Agent, owner and A2A
+ *   context (`info.a2a.contextId`, `api/a2a/routes.ts`) and the queued message it took, if any;
+ *   a further message of the same turn only adds its queued message;
+ * - `command.approve` and `command.respond` set it `running` again, `turn.paused` `paused` with
+ *   what its first open interaction asks for (`waitingFor`, profile v2's kinds);
+ * - `turn.completed`, `turn.failed` and `turn.cancelled` end it, with their end facts' `totals`.
+ *
+ * Each change stamps the row with its transaction (`txid`), which orders the change feed
+ * (`reads.ts`). Rows for the turns recorded before the index are backfilled by migration
+ * `0041_turn_index_backfill`.
+ */
+import { and, desc, eq, isNotNull, gte, inArray, or, sql } from "drizzle-orm";
+import { sessions, toJson, turns } from "./schema.js";
+/** The events that change a turn's row, and the status each leaves it in. */
+export const TURN_EVENT_STATUS = {
+    "command.message": "running",
+    "command.approve": "running",
+    "command.respond": "running",
+    "turn.paused": "paused",
+    "turn.completed": "completed",
+    "turn.failed": "failed",
+    "turn.cancelled": "cancelled",
+};
+/** The statuses a turn ends in. */
+export const ENDED_TURN_STATUSES = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+]);
+/** An ended turn's `totals`, from its end facts, or null when it has none. */
+function totalsOf(payload) {
+    const totals = payload?.totals;
+    if (typeof totals?.steps !== "number" ||
+        typeof totals.tokens !== "number" ||
+        typeof totals.costUsd !== "number")
+        return null;
+    return { steps: totals.steps, tokens: totals.tokens, costUsd: totals.costUsd };
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** What a `turn.paused` payload's first open interaction asks for, or null. */
+export function waitingForOf(payload) {
+    const entries = isRecord(payload) && Array.isArray(payload.interactions) ? payload.interactions : [];
+    for (const entry of entries) {
+        if (!isRecord(entry) || (entry.status !== undefined && entry.status !== "interaction"))
+            continue;
+        const interaction = entry.interaction;
+        if (!isRecord(interaction) || typeof interaction.id !== "string")
+            continue;
+        const metadata = isRecord(interaction.metadata) ? interaction.metadata : undefined;
+        if (interaction.kind === "connection" || metadata?.kind === "connection")
+            return "connection";
+        return interaction.kind === "approval" ? "approval" : "question";
+    }
+    return null;
+}
+/**
+ * Writes the change `event` makes to its turn's row, in the event's transaction (the session
+ * row is locked). An event without a turn, or of a type that changes none, writes nothing.
+ */
+export async function indexTurn(db, event) {
+    const status = TURN_EVENT_STATUS[event.type];
+    if (status === undefined || event.turnId === null)
+        return;
+    const ended = ENDED_TURN_STATUSES.has(status);
+    const totals = ended ? totalsOf(event.payload) : null;
+    const waitingFor = event.type === "turn.paused" ? waitingForOf(event.payload) : null;
+    const queuedMessageId = event.type === "command.message" && isRecord(event.payload) && typeof event.payload.queuedMessageId === "string"
+        ? event.payload.queuedMessageId
+        : undefined;
+    const insert = sql `
+    INSERT INTO ${turns} (
+      "session_id", "turn_id", "agent_id", "owner_user_id", "a2a_context_id", "status",
+      "started_at", "ended_at", "changed_at", "totals", "waiting_for", "queued_message_ids",
+      "first_seq", "last_seq"
+    )
+    SELECT
+      ${sessions.id}, ${event.turnId}, coalesce(${sessions.agentId}, ''), ${sessions.ownerUserId},
+      nylorun.doc(${sessions.body})->'info'->'a2a'->>'contextId', ${status},
+      ${event.time}, ${ended ? event.time : null}, ${event.time},
+      ${totals === null ? null : sql `${toJson(totals)}::text::json`}, ${waitingFor},
+      ${queuedMessageId === undefined ? sql `'{}'::text[]` : sql `ARRAY[${queuedMessageId}]::text[]`},
+      ${event.seq}, ${event.seq}
+    FROM ${sessions}
+    WHERE ${sessions.id} = ${event.sessionId}`;
+    // A turn's further messages (a queued batch) add their queued ids and change nothing else.
+    await db.execute(event.type === "command.message"
+        ? sql `${insert} ON CONFLICT ("session_id", "turn_id") DO UPDATE SET
+          "queued_message_ids" = ${turns}."queued_message_ids" || excluded."queued_message_ids"`
+        : sql `${insert} ON CONFLICT ("session_id", "turn_id") DO UPDATE SET
+          "status" = excluded."status",
+          "ended_at" = excluded."ended_at",
+          "changed_at" = excluded."changed_at",
+          "totals" = excluded."totals",
+          "waiting_for" = excluded."waiting_for",
+          "last_seq" = excluded."last_seq",
+          "txid" = pg_current_xact_id()`);
+}
+/** One turn's row, or undefined when the session never had that turn. */
+export async function turnRow(db, sessionId, turnId) {
+    const [row] = await db
+        .select()
+        .from(turns)
+        .where(and(eq(turns.sessionId, sessionId), eq(turns.turnId, turnId)));
+    return row;
+}
+/** The turn that took queued message `queuedMessageId` of a session, if one did. */
+export async function turnOfQueuedMessage(db, sessionId, queuedMessageId) {
+    const [row] = await db
+        .select()
+        .from(turns)
+        .where(and(eq(turns.sessionId, sessionId), sql `${queuedMessageId} = ANY(${turns.queuedMessageIds})`))
+        .limit(1);
+    return row;
+}
+/**
+ * The turns `query` names, latest status change first (then by session and turn id, descending),
+ * at most `limit`, and how many match without `after` and `limit`.
+ */
+export async function listTurns(db, query) {
+    if (query.states?.length === 0)
+        return { turns: [], total: 0 };
+    const where = [
+        eq(turns.ownerUserId, query.ownerUserId),
+        eq(turns.agentId, query.agentId),
+        isNotNull(turns.a2aContextId),
+    ];
+    if (query.sessionId !== undefined)
+        where.push(eq(turns.sessionId, query.sessionId));
+    if (query.states !== undefined)
+        where.push(or(...query.states.map((state) => and(eq(turns.status, state.status), state.waitingFor === undefined ? undefined : inArray(turns.waitingFor, [...state.waitingFor])))));
+    if (query.changedSince !== undefined)
+        where.push(gte(turns.changedAt, query.changedSince));
+    const after = query.after;
+    // One statement at a time: a transaction runs on one connection.
+    const rows = await db
+        .select()
+        .from(turns)
+        .where(and(...where, after
+        ? sql `(${turns.changedAt}, ${turns.sessionId}, ${turns.turnId}) < (${after.changedAt}, ${after.sessionId}, ${after.turnId})`
+        : undefined))
+        .orderBy(desc(turns.changedAt), desc(turns.sessionId), desc(turns.turnId))
+        .limit(query.limit);
+    const [counted] = await db
+        .select({ total: sql `count(*)`.mapWith(Number) })
+        .from(turns)
+        .where(and(...where));
+    return { turns: rows, total: counted?.total ?? 0 };
+}

package/dist/store/types.d.ts

@@ -65,7 +65,9 @@ import type { RecordReader } from "../streams/relay/types.js";
 import type { SandboxSignal, Wake } from "../execution/types.js";
 import type { EventPayload, EventType, EventWriter, LiveEvent, AgentEvent, AgentEventPayload, AgentEventType, AgentManifestV8, EnvironmentKind, EnvironmentRecipe, PodDesired, PodObserved, SessionEventOf } from "@nylorun/core/contracts";
 import type { HostEffect } from "@nylorun/harness/run";
-import type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, PrincipalRow, ToolCrossingRow, QueuedMessageRow, AgentTriggerRow, TriggerRunRow, MemoryRow, MemoryVersionRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow } from "./postgres/schema.js";
+import type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, PrincipalRow, ToolCrossingRow, QueuedMessageRow, TurnRow, A2aPushConfigRow, AgentTriggerRow, TriggerRunRow, MemoryRow, MemoryVersionRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow } from "./postgres/schema.js";
+import type { TurnListQuery } from "./postgres/turns.js";
+export type { TurnListQuery };
 /** Tables holding JSON documents keyed by `id`. */
 export type DocTable = "sessions" | "commands" | "effects" | "sandboxes" | "links";
 export declare const DOC_TABLES: readonly DocTable[];
@@ -258,6 +260,15 @@ export interface SandboxPodState {
      * Environment is ready (Q14): every later pod, after a stop, a relaunch or a reset, runs it.
      */
     imageDigest?: string;
+    /**
+     * The engine the workload image carries (ADR-99, `sandbox/pods/builtin.ts`): its Runtime
+     * version, as its engine reported at join, and the digest that pod ran. It counts only while
+     * that digest is `imageDigest`.
+     */
+    engineImage?: {
+        version: string;
+        digest?: string;
+    };
 }
 /** A change to a pod's columns: `null` clears an optional one. */
 export type SandboxPodPatch = {
@@ -295,7 +306,7 @@ export type CommitListener = (commit: Commit) => void;
  * `bytea` columns, never inside a JSON body), the vault's audit and idempotency records, the
  * Tenant's signing keys, a model call in the usage ledger and a model budget.
  */
-export type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, ToolCrossingRow, QueuedMessageRow, AgentTriggerRow, TriggerRunRow, MemoryRow, MemoryVersionRow, PrincipalRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, };
+export type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, ToolCrossingRow, QueuedMessageRow, TurnRow, A2aPushConfigRow, AgentTriggerRow, TriggerRunRow, MemoryRow, MemoryVersionRow, PrincipalRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, };
 /** Which rows of the usage ledger a total covers. */
 export interface ModelUsageQuery {
     scope: "tenant" | "manifest" | "turn";
@@ -383,10 +394,22 @@ export interface SessionStore {
 export type OutboxWake = Wake & {
     dedupeKey: string;
 };
+/**
+ * One A2A push as the outbox delivers it (`Tx.enqueuePush`): the config it goes to (by session,
+ * task and config id) and the exact body. `id` is its Standard Webhooks `webhook-id`.
+ */
+export interface OutboxPush {
+    id: string;
+    sessionId: string;
+    taskId: string;
+    configId: string;
+    body: string;
+}
 /**
  * What a committed transaction asked of Durable Session Execution, as the outbox delivers it:
  * a wake (`Tx.wake`), or a pod sandbox's reconcile or timer (`Tx.signalSandbox`; a reconcile
- * carries its idempotency key, `signal:<row id>`).
+ * carries its idempotency key, `signal:<row id>`). Or an A2A push to a caller's URL (`push`,
+ * `Tx.enqueuePush`), which the Tenant sends itself (`api/a2a/push.ts`).
  */
 export type OutboxRequest = {
     kind: "wake";
@@ -396,6 +419,9 @@ export type OutboxRequest = {
     kind: "sandbox";
     sandboxId: string;
     signal: SandboxSignal;
+} | {
+    kind: "push";
+    push: OutboxPush;
 };
 /**
  * Hands an outbox request to Durable Session Execution (`SessionStore.deliverTo`). Resolving
@@ -502,6 +528,22 @@ export interface Tx {
     event<T extends EventType>(sessionId: string, turnId: string | null, type: T, payload: EventPayload<T>, 
     /** Who wrote it (R4.9): absent, core, observed. */
     writer?: EventWriter): Promise<SessionEventOf<T>>;
+    /**
+     * One turn's row of the turn index, or undefined when the session never had that turn. `event`
+     * keeps the index: each event that changes a turn (`command.message`, `command.approve`,
+     * `command.respond`, `turn.*`) writes its row in the same transaction.
+     */
+    turn(sessionId: string, turnId: string): Promise<TurnRow | undefined>;
+    /** The turn that took queued message `queuedMessageId` of the session, if one did (protocol 17). */
+    turnOfQueuedMessage(sessionId: string, queuedMessageId: string): Promise<TurnRow | undefined>;
+    /**
+     * One owner's A2A tasks with one Agent from the turn index (`ListTasks`), latest status change
+     * first, with how many match before paging.
+     */
+    listTurns(query: TurnListQuery): Promise<{
+        turns: TurnRow[];
+        total: number;
+    }>;
     /**
      * Asks for an advance of `sessionId` once this transaction commits. The request is a row
      * of the wake outbox written in this transaction, so it commits, or rolls back, with what
@@ -539,6 +581,43 @@ export interface Tx {
         retryInMs: number;
         park: boolean;
     }): Promise<void>;
+    /** Adds or replaces a task's push config (its `createdAt` and `doneAt` start again). */
+    putPushConfig(row: Omit<A2aPushConfigRow, "createdAt" | "doneAt"> & {
+        doneAt?: Date | null;
+    }): Promise<void>;
+    /** One push config of a task. */
+    pushConfig(sessionId: string, taskId: string, configId: string): Promise<A2aPushConfigRow | undefined>;
+    /** A task's push configs, by config id, after `after`, at most `limit`. */
+    pushConfigs(sessionId: string, taskId: string, options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<A2aPushConfigRow[]>;
+    /** Deletes a task's push config; whether it was there. */
+    deletePushConfig(sessionId: string, taskId: string, configId: string): Promise<boolean>;
+    /** A session's push configs still following their task (no `doneAt`); with `lock`, locked. */
+    activePushConfigs(sessionId: string, options?: {
+        lock?: boolean;
+    }): Promise<A2aPushConfigRow[]>;
+    /** Sessions with a push config still following its task, by id, after `after`, at most `limit`. */
+    pushSessions(limit: number, after?: string): Promise<string[]>;
+    /** Moves a push config on: the turn it follows, the next event it reads, and whether it is done. */
+    advancePushConfig(key: {
+        sessionId: string;
+        taskId: string;
+        configId: string;
+    }, change: {
+        turnId: string;
+        nextSeq: number;
+        traceId: string | null;
+        done: boolean;
+    }): Promise<void>;
+    /** Deletes push configs done before `before`; how many. */
+    prunePushConfigs(before: Date): Promise<number>;
+    /**
+     * Writes an A2A push to the outbox (kind `push`), delivered after commit as a wake is, and by
+     * the sweep with backoff until it is delivered or too old.
+     */
+    enqueuePush(push: Omit<OutboxPush, "id">): Promise<void>;
     /**
      * Locks the session and takes ownership when it has no owner or the owner's
      * lease ended at or before `now`; then increments `epoch` and sets the lease