@nylorun/runtime 0.27.0-beta → 0.29.0-beta

package/dist/tenant/auth.d.ts

@@ -48,6 +48,6 @@ export declare function accessOf(scope: AuthScope): SessionAccess | undefined;
 export declare function ownerOf(scope: AuthScope): string | undefined;
 /** The application principal behind the request, acting for a subject or not. */
 export declare function requirePrincipal(scope: AuthScope): string;
-/** True when a token caller may reach `agentId` (its issuer's allowlist). Other callers always may. */
+/** True when a token caller may reach Agent `agentId` (its grants). Other callers always may. */
 export declare function mayUseAgent(scope: AuthScope, agentId: string): boolean;
 export declare function requireApplication(scope: AuthScope): string;

package/dist/tenant/auth.js

@@ -1,5 +1,5 @@
 import { SCOPES_HEADER, SUBJECT_HEADER, } from "@nylorun/core/compatibility";
-import { parseSubjectHeaders, TOKEN_SCOPES } from "@nylorun/core/contracts";
+import { agentGranted, parseSubjectHeaders, TOKEN_SCOPES } from "@nylorun/core/contracts";
 import { hashToken } from "../core/bearer.js";
 import { fail } from "./http.js";
 import { verifyIssuerToken } from "./issuers.js";
@@ -168,9 +168,9 @@ export function requirePrincipal(scope) {
         return scope.principalId;
     return fail(403, "Application credential required");
 }
-/** True when a token caller may reach `agentId` (its issuer's allowlist). Other callers always may. */
+/** True when a token caller may reach Agent `agentId` (its grants). Other callers always may. */
 export function mayUseAgent(scope, agentId) {
-    return scope.kind !== "token" || scope.agents === "*" || scope.agents.has(agentId);
+    return scope.kind !== "token" || scope.agents === "*" || agentGranted(scope.agents, agentId);
 }
 export function requireApplication(scope) {
     if (scope.kind === "application")

package/dist/tenant/commands.d.ts

@@ -1,5 +1,6 @@
-import type { EventWriter, SessionCommand } from "@nylorun/core/contracts";
-import { type AuthScope, type TenantContext } from "./context.js";
+import type { EventWriter, MessageDelivery, MessageEventBody, SessionCommand } from "@nylorun/core/contracts";
+import type { Tx } from "../store/types.js";
+import { type AuthScope, type Session, type TenantContext } from "./context.js";
 import type { TraceContext } from "../traces/ids.js";
 export declare function command(ctx: TenantContext, id: string, input: SessionCommand, scope: AuthScope, 
 /**
@@ -8,7 +9,67 @@ export declare function command(ctx: TenantContext, id: string, input: SessionCo
  */
 options?: {
     trace?: TraceContext;
+    /**
+     * What a message to a busy session does when it says nothing (`delivery`): the route's
+     * answer to the caller's protocol (`queue` from 17). Core's own messages and the AG-UI and
+     * A2A adapters, which stream the run they start, take `reject`.
+     */
+    delivery?: MessageDelivery;
 }): Promise<unknown>;
+export declare const takesMessages: (s: Session) => boolean;
+/** A message ready to start a turn: as sent, its engine input and who sent it. */
+export interface TurnMessage {
+    command: MessageEventBody;
+    /** An agent's message input, or a workflow's input value. */
+    input: unknown;
+    /** The artifacts its file parts named. */
+    fileArtifacts: string[];
+    writer: EventWriter;
+    /** Set for a message that waited in the session's queue. */
+    queuedMessageId?: string;
+    trace?: TraceContext;
+    /** What sent it when not a client (track T4): a trigger's run, or the session's own wake. */
+    cause?: MessageCause;
+}
+/** What sent a message when not a client (`command.message`'s `cause`). */
+export interface MessageCause {
+    kind: "trigger" | "self";
+    triggerId: string;
+    runId: string;
+}
+/** How a message was taken: it started a turn, or waits in the session's queue. */
+export type MessageAnswer = {
+    status: "accepted";
+    turnId: string;
+    cursor: string;
+} | {
+    status: "queued";
+    queuedMessageId: string;
+    position: number;
+    cursor: string;
+};
+/**
+ * Takes a resolved message on session `s` (locked) in transaction `t`: it starts a turn when the
+ * session takes messages and none wait, else it waits in the queue behind them (protocol 17), and
+ * an idle session whose queue was left waiting (its Agent was unavailable when the last turn
+ * ended) starts a turn with all of them, this one last. Past `sessionQueuedMessages` it is
+ * `429 queue_full`. `waiting` is the queue's length, read under the session's lock.
+ */
+export declare function acceptMessage(ctx: TenantContext, t: Tx, s: Session, id: string, message: TurnMessage, waiting?: number): Promise<MessageAnswer>;
+/** Who checks a queued message's turn start: core, since the sender's grants were checked when it was queued. */
+export declare const QUEUE_SCOPE: AuthScope;
+/**
+ * Starts the next turn of session `s` (locked) from its queue, when it takes messages and messages
+ * wait (protocol 17, D76): in the transaction that ended the last turn, or a cancel's. Our engine
+ * takes every queued message that carries the same turn manifest as the first, a workflow one.
+ * Writes `queue.taken`. Returns nothing when nothing started: an empty queue, or an Agent that
+ * cannot take a turn now, whose messages wait for the next message or turn end.
+ */
+export declare function startQueuedTurn(ctx: TenantContext, t: Tx, s: Session, id: string): Promise<{
+    turnId: string;
+    taken: string[];
+    cursor: string;
+} | undefined>;
 /**
  * Who sent a command (R4.9), from its credential and never its body: a client over the Runtime
  * API (an application, or a person through it or a token), or core itself.

package/dist/tenant/commands.js

@@ -14,6 +14,12 @@
  * same transaction; the engine host sees it before its next effect and before settlement on
  * any Worker. It then aborts an advance running on this process (`ctx.abortLocal`); every
  * other process aborts its own on the signal (`control.ts`).
+ *
+ * A message to a session whose turn runs or waits (protocol 17, D76) is queued
+ * (`session_queue`, `message.queued`) unless it asks `delivery: "reject"`, which is
+ * `409 session_busy`. A turn that ends takes every queued message in the same transaction
+ * (`startQueuedTurn`): client messages and queued ones start a turn through one door,
+ * `beginMessageTurn`, which writes each one's `command.message`.
  */
 import { randomUUID } from "node:crypto";
 import { createDurableCheckpoint, createFlowCheckpoint, resumeFlowCheckpoint, } from "@nylorun/harness/run";
@@ -21,10 +27,11 @@ import { commandKey, cancelQueuedEffects, flowInteractionOf, foreignInteractionC
 import { resolveMessageManifest } from "../core/turn-manifest.js";
 import { canonical } from "../store/canonical.js";
 import { lockedSession, } from "./context.js";
-import { fail } from "./http.js";
+import { fail, HttpError } from "./http.js";
+import { readRuntimeLimits } from "./runtime-limits.js";
 import { settleToolRow } from "../harness-api/tool-journal.js";
 import { accessOf } from "./auth.js";
-import { checkEnvironmentTurn } from "./environments.js";
+import { checkAgentTurn } from "./agents.js";
 import { turnManifestOf, variantStore } from "./session.js";
 import { slimModelEffects } from "./slim.js";
 import { resolveMessageParts } from "../artifacts/parts.js";
@@ -42,6 +49,7 @@ export async function command(ctx, id, input, scope,
 options = {}) {
     const { store } = ctx;
     const cascadeCancelIds = [];
+    let cancelledTurn = null;
     const response = await store.tx(async (t) => {
         const s = await lockedSession(t, id, accessOf(scope));
         const command = input;
@@ -64,8 +72,11 @@ options = {}) {
         let held;
         // The turn a `cancel` ended, if one was active.
         let cancelledTurnId = null;
+        /** A message's answer: accepted with its turn, or queued (protocol 17). */
+        let answer;
         if (command.type === "cancel") {
             cancelledTurnId = s.activeTurnId;
+            cancelledTurn = cancelledTurnId;
             const workflowCancel = isWorkflowManifest(s.manifest);
             // Linked sessions this one started: a workflow's agents, or flow agents an agent
             // uses as tools.
@@ -128,84 +139,25 @@ options = {}) {
             }
         }
         else {
-            // A session opened before protocol 11 (migration 0020), 13 (migration 0024) or 15
-            // (migrations 0029, 0030) keeps its history but takes no turn.
+            // A session opened before protocol 11 (migration 0020), 13 (migration 0024), 15
+            // (migrations 0029, 0030) or 16 (migration 0032) keeps its history but takes no turn.
             if (s.closedReason !== undefined)
-                fail(409, s.closedReason === "protocol_11"
-                    ? "This session was opened before protocol 11: open a new session that names an Environment."
-                    : s.closedReason === "protocol_15"
-                        ? "This session was opened before protocol 15, and its pinned manifest holds a runtime block: our harness now writes the model's instructions and defines its tools itself. Open a new session."
-                        : "This session was opened before protocol 13, on a manifest the Runtime no longer runs: register the agent again (manifest 7) and open a new session.", { code: "session_closed" });
+                fail(409, s.closedReason === "protocol_16"
+                    ? "This session was opened before protocol 16, from an agent definition: save the agent as an agent manifest (nylorun migrate v8, then nylorun apply), make an Agent from it and open a new session on it."
+                    : s.closedReason === "protocol_11"
+                        ? "This session was opened before protocol 11: open a new session on an Agent."
+                        : s.closedReason === "protocol_15"
+                            ? "This session was opened before protocol 15, and its pinned manifest holds a runtime block: our harness now writes the model's instructions and defines its tools itself. Open a new session."
+                            : "This session was opened before protocol 13, on a manifest the Runtime no longer runs: register the agent again (manifest 7) and open a new session.", { code: "session_closed" });
             if (command.type === "message") {
-                if (!["idle", "completed", "failed", "cancelled"].includes(s.status))
-                    fail(409, "Session has active or unresolved work");
+                const delivery = command.delivery ?? options.delivery ?? "reject";
+                const waiting = await t.countQueuedMessages(id);
+                if (!takesMessages(s) && delivery === "reject")
+                    fail(409, "Session has active or unresolved work", { code: "session_busy" });
                 // Every turn start on a sandbox: it exists, the token's grants reach it, and no other
-                // session's turn holds it.
-                await checkEnvironmentTurn(t, s, scope, ctx);
-                s.turnStartState = s.state;
-                // A new turn folds from the latest snapshot: a cancel or failure only reverts this turn.
-                if (s.history?.snapshot !== undefined)
-                    s.history = { ...s.history, from: s.history.snapshot };
-                s.activeTurnId = randomUUID();
-                startTurn(s);
-                if (options.trace)
-                    s.turnTrace = options.trace;
-                else
-                    delete s.turnTrace;
-                // File parts name artifacts the caller may read; each is pinned to a version now. Any
-                // file goes (protocol 15): the harness decides how the model sees it, and a workflow
-                // passes it on as data.
-                const parts = "parts" in command
-                    ? await resolveMessageParts(t, command.parts, id, accessOf(scope))
-                    : undefined;
-                // The files the session's messages named: `read_artifact` reads them again (protocol 12).
-                if (parts) {
-                    const named = parts.pinned.flatMap((part) => (part.type === "file" ? [part.artifactId] : []));
-                    if (named.length > 0)
-                        s.fileArtifacts = [...new Set([...(s.fileArtifacts ?? []), ...named])];
-                }
-                const data = "data" in command ? command.data : undefined;
-                if (isWorkflowManifest(s.manifest)) {
-                    const input = "content" in command
-                        ? command.content
-                        : parts
-                            ? { parts: parts.pinned }
-                            : data;
-                    s.checkpoint = createFlowCheckpoint({
-                        manifest: s.manifest,
-                        sessionId: id,
-                        turnId: s.activeTurnId,
-                        input,
-                    });
-                }
-                else {
-                    // Optional message.manifest: validate as variant, pin by hash, apply this turn only.
-                    const resolved = resolveMessageManifest({
-                        pinned: s.manifest,
-                        pinnedHash: s.manifestHash,
-                        messageManifest: command.manifest,
-                        store: variantStore(s),
-                    });
-                    if (!resolved.ok) {
-                        fail(400, resolved.message);
-                    }
-                    else {
-                        s.checkpoint = createDurableCheckpoint({
-                            manifest: resolved.manifest,
-                            sessionId: id,
-                            turnId: s.activeTurnId,
-                            input: "content" in command
-                                ? command.content
-                                : parts
-                                    ? { content: parts.engine }
-                                    : typeof data === "string"
-                                        ? data
-                                        : JSON.stringify(data),
-                            state: s.state,
-                            info: s.info,
-                        });
-                    }
-                }
+                // session's turn holds it. A queued message is checked when it is queued, too.
+                await checkAgentTurn(t, s, scope, ctx);
+                answer = await acceptMessage(ctx, t, s, id, await turnMessage(t, s, id, command, scope, options.trace), waiting);
             }
             else if (command.type === "approve" &&
                 (held = await heldCall(t, s, command.interactionId)) !== undefined) {
@@ -278,13 +230,15 @@ options = {}) {
                     segment: (s.checkpoint?.segment ?? 0) + 1,
                 });
             }
+        }
+        if (command.type !== "cancel" && command.type !== "message") {
             // A paused turn goes on: its wait for a person is not its running time (R7.1).
             resumeTurn(s);
             s.status = "runnable";
             s.waits = undefined;
             // A flow answers each interaction in the same segment, as a held tool call's approval is
             // answered (R5 step 2): the interaction names the cause.
-            const cause = command.type !== "message" && (isWorkflowManifest(s.manifest) || held !== undefined)
+            const cause = isWorkflowManifest(s.manifest) || held !== undefined
                 ? command.interactionId
                 : s.checkpoint.segment;
             const commandWake = {
@@ -292,8 +246,11 @@ options = {}) {
                 dedupeKey: `${command.type}:${s.activeTurnId}:${cause}`,
             };
             await t.wake(id, commandWake);
-            event = await t.event(id, s.activeTurnId, `command.${command.type}`, command.type === "message" && options.trace ? { ...command, trace: options.trace } : command, commandWriter(scope));
+            event = await t.event(id, s.activeTurnId, `command.${command.type}`, command, commandWriter(scope));
         }
+        // A cancel ends the turn, not the queue: the messages waiting start the next one.
+        if (command.type === "cancel")
+            await startQueuedTurn(ctx, t, s, id);
         await t.put("sessions", id, s);
         // Direct cancel of a linked agent fails that node with agent.cancelled (WF-R54). The agent
         // session is locked above, before wakeLinkedWorkflow locks its workflow.
@@ -306,16 +263,18 @@ options = {}) {
                 error: "Agent turn was cancelled",
             });
         const response = {
-            status: "accepted",
-            turnId: s.activeTurnId,
-            cursor: event.cursor,
+            ...(answer ?? {
+                status: "accepted",
+                turnId: command.type === "cancel" ? null : s.activeTurnId,
+                cursor: event.cursor,
+            }),
             requestId: command.requestId,
         };
         await t.put("commands", key, { command, response });
         return response;
     });
     if (input.type === "cancel")
-        ctx.abortLocal(id);
+        ctx.abortLocal(id, cancelledTurn ?? undefined);
     // Cascade cancel linked agents deepest-first under existing fencing (WF-R53).
     for (const agentId of cascadeCancelIds) {
         try {
@@ -332,6 +291,204 @@ options = {}) {
     }
     return response;
 }
+/** Statuses in which a session takes a message as a new turn; in the others a turn runs or waits. */
+const TAKES_MESSAGES = ["idle", "completed", "failed", "cancelled"];
+export const takesMessages = (s) => TAKES_MESSAGES.includes(s.status);
+/**
+ * Takes a resolved message on session `s` (locked) in transaction `t`: it starts a turn when the
+ * session takes messages and none wait, else it waits in the queue behind them (protocol 17), and
+ * an idle session whose queue was left waiting (its Agent was unavailable when the last turn
+ * ended) starts a turn with all of them, this one last. Past `sessionQueuedMessages` it is
+ * `429 queue_full`. `waiting` is the queue's length, read under the session's lock.
+ */
+export async function acceptMessage(ctx, t, s, id, message, waiting) {
+    const queued = waiting ?? (await t.countQueuedMessages(id));
+    const takes = takesMessages(s);
+    if (takes && queued === 0) {
+        const event = await beginMessageTurn(t, s, id, [message]);
+        return { status: "accepted", turnId: s.activeTurnId, cursor: event.cursor };
+    }
+    // The turn runs or waits, or earlier messages still wait: this one waits behind them.
+    const { sessionQueuedMessages } = await readRuntimeLimits(t);
+    if (queued >= sessionQueuedMessages)
+        fail(429, `Session ${id} already holds ${queued} queued messages, the Runtime limit sessionQueuedMessages (PUT /v1/tenant/limits); they start a turn when the running one ends.`, { code: "queue_full" });
+    const queuedMessageId = randomUUID();
+    await t.enqueueMessage({
+        id: queuedMessageId,
+        sessionId: id,
+        command: message.command,
+        input: message.input,
+        fileArtifacts: message.fileArtifacts,
+        writer: message.writer,
+        trace: message.trace ?? null,
+        cause: message.cause ?? null,
+        createdAt: new Date().toISOString(),
+    });
+    const position = queued + 1;
+    const event = await t.event(id, s.activeTurnId, "message.queued", { queuedMessageId, position, requestId: message.command.requestId }, message.writer);
+    const started = takes ? await startQueuedTurn(ctx, t, s, id) : undefined;
+    if (started?.taken.includes(queuedMessageId))
+        return { status: "accepted", turnId: started.turnId, cursor: started.cursor };
+    return { status: "queued", queuedMessageId, position, cursor: event.cursor };
+}
+/**
+ * Resolves a message for a turn, now or when it leaves the queue: file parts name artifacts the
+ * caller may read, each pinned to a version (any file goes since protocol 15: the harness decides
+ * how the model sees it, and a workflow passes it on as data), and a turn manifest must be a
+ * variant of the pinned agent.
+ */
+async function turnMessage(t, s, id, command, scope, trace) {
+    const parts = "parts" in command ? await resolveMessageParts(t, command.parts, id, accessOf(scope)) : undefined;
+    const fileArtifacts = (parts?.pinned ?? []).flatMap((part) => (part.type === "file" ? [part.artifactId] : []));
+    const data = "data" in command ? command.data : undefined;
+    let input;
+    if (isWorkflowManifest(s.manifest))
+        input =
+            "content" in command
+                ? command.content
+                : parts
+                    ? { parts: parts.pinned }
+                    : data;
+    else {
+        const resolved = resolveMessageManifest({
+            pinned: s.manifest,
+            pinnedHash: s.manifestHash,
+            messageManifest: command.manifest,
+            store: variantStore(s),
+        });
+        if (!resolved.ok)
+            fail(400, resolved.message);
+        input =
+            "content" in command
+                ? command.content
+                : parts
+                    ? { content: parts.engine }
+                    : typeof data === "string"
+                        ? data
+                        : JSON.stringify(data);
+    }
+    return { command, input, fileArtifacts, writer: commandWriter(scope), ...(trace ? { trace } : {}) };
+}
+/**
+ * Starts a turn on session `s` (locked, taking messages) with `messages`, in order: the one door
+ * for a client's message and queued ones (protocol 17). Our engine reads more than one as
+ * `{kind: "messages", messages}`, each its own user message; a workflow takes one. The checkpoint
+ * is made before the session changes, so a manifest that no longer resolves changes nothing.
+ * Writes each message's `command.message` and returns the last.
+ */
+async function beginMessageTurn(t, s, id, messages) {
+    const turnId = randomUUID();
+    const first = messages[0];
+    let checkpoint;
+    if (isWorkflowManifest(s.manifest))
+        checkpoint = createFlowCheckpoint({
+            manifest: s.manifest,
+            sessionId: id,
+            turnId,
+            input: first.input,
+        });
+    else {
+        const resolved = resolveMessageManifest({
+            pinned: s.manifest,
+            pinnedHash: s.manifestHash,
+            messageManifest: first.command.manifest,
+            store: variantStore(s),
+        });
+        if (!resolved.ok)
+            return fail(400, resolved.message);
+        checkpoint = createDurableCheckpoint({
+            manifest: resolved.manifest,
+            sessionId: id,
+            turnId,
+            input: (messages.length === 1
+                ? first.input
+                : { kind: "messages", messages: messages.map((message) => message.input) }),
+            state: s.state,
+            info: s.info,
+        });
+    }
+    s.turnStartState = s.state;
+    // A new turn folds from the latest snapshot: a cancel or failure only reverts this turn.
+    if (s.history?.snapshot !== undefined)
+        s.history = { ...s.history, from: s.history.snapshot };
+    s.activeTurnId = turnId;
+    startTurn(s);
+    if (first.trace)
+        s.turnTrace = first.trace;
+    else
+        delete s.turnTrace;
+    // A trigger's run or a booked wake among the messages started it (track T4).
+    const cause = messages.find((message) => message.cause)?.cause;
+    if (cause)
+        s.turnCause = { kind: cause.kind, triggerId: cause.triggerId, runId: cause.runId };
+    else
+        delete s.turnCause;
+    // The files the session's messages named: `read_artifact` reads them again (protocol 12).
+    const named = messages.flatMap((message) => message.fileArtifacts);
+    if (named.length > 0)
+        s.fileArtifacts = [...new Set([...(s.fileArtifacts ?? []), ...named])];
+    s.checkpoint = checkpoint;
+    s.status = "runnable";
+    s.waits = undefined;
+    await t.wake(id, { reason: "message", dedupeKey: `message:${turnId}:${checkpoint.segment}` });
+    let event;
+    for (const message of messages)
+        event = await t.event(id, turnId, "command.message", {
+            ...message.command,
+            ...(message.queuedMessageId === undefined ? {} : { queuedMessageId: message.queuedMessageId }),
+            ...(message.trace ? { trace: message.trace } : {}),
+            ...(message.cause ? { cause: message.cause } : {}),
+        }, message.writer);
+    return event;
+}
+/** Who checks a queued message's turn start: core, since the sender's grants were checked when it was queued. */
+export const QUEUE_SCOPE = { kind: "application", principalId: "queue" };
+/**
+ * Starts the next turn of session `s` (locked) from its queue, when it takes messages and messages
+ * wait (protocol 17, D76): in the transaction that ended the last turn, or a cancel's. Our engine
+ * takes every queued message that carries the same turn manifest as the first, a workflow one.
+ * Writes `queue.taken`. Returns nothing when nothing started: an empty queue, or an Agent that
+ * cannot take a turn now, whose messages wait for the next message or turn end.
+ */
+export async function startQueuedTurn(ctx, t, s, id) {
+    if (s.closedReason !== undefined || !takesMessages(s) || s.activeTurnId !== null)
+        return undefined;
+    const queued = await t.queuedMessages(id);
+    if (queued.length === 0)
+        return undefined;
+    const manifestOf = (row) => canonical(row.command.manifest ?? null);
+    const batch = isWorkflowManifest(s.manifest) ? [queued[0]] : [];
+    if (batch.length === 0)
+        for (const row of queued) {
+            if (manifestOf(row) !== manifestOf(queued[0]))
+                break;
+            batch.push(row);
+        }
+    try {
+        await checkAgentTurn(t, s, QUEUE_SCOPE, ctx);
+        await beginMessageTurn(t, s, id, batch.map((row) => ({
+            command: row.command,
+            input: row.input,
+            fileArtifacts: row.fileArtifacts,
+            writer: row.writer,
+            queuedMessageId: row.id,
+            ...(row.trace ? { trace: row.trace } : {}),
+            ...(row.cause ? { cause: row.cause } : {}),
+        })));
+    }
+    catch (error) {
+        if (error instanceof HttpError)
+            return undefined;
+        throw error;
+    }
+    const taken = batch.map((row) => row.id);
+    await t.deleteQueuedMessages(taken);
+    const event = await t.event(id, s.activeTurnId, "queue.taken", {
+        turnId: s.activeTurnId,
+        queuedMessageIds: taken,
+    });
+    return { turnId: s.activeTurnId, taken, cursor: event.cursor };
+}
 /** Core's own commands (R4.9): the flow host's, and a drain's cancels. */
 const CORE_PRINCIPALS = { "flow-host": "flow-host", drain: "core" };
 /**

package/dist/tenant/context.d.ts

@@ -40,19 +40,28 @@ import type { TraceOptions } from "../traces/options.js";
 import type { TraceContext } from "../traces/ids.js";
 export interface Session {
     id: string;
+    /** The Agent the session runs on (protocol 16; a definition id before). */
     agentId: string;
     ownerUserId: string;
-    /** Session pin — the manifest the session was created with. */
+    /**
+     * Session pin: the loop manifest the session runs, its Agent's manifest version's harness
+     * section as the harness runs it (`loopManifestOf`), or a flow's leaf agent.
+     */
     manifest: any;
     manifestHash: string;
     /**
-     * The hash of the definition the session was opened from (R2b C11); since protocol 15 it equals
-     * `manifestHash`. Absent on older sessions.
+     * The agent manifest version the session runs (protocol 16): its Agent's when it opened, and
+     * again at a turn's first segment when its Agent's version changed since (T3, `repinTurn`).
+     * Absent on a session opened before protocol 16.
      */
-    definitionHash?: string;
+    definition?: {
+        name: string;
+        version: number;
+    };
+    /** The pinned version's `harness.loop`: passed to the harness, never read by the Runtime. */
+    loop?: Record<string, unknown>;
     /** Validated turn-manifest variants, keyed by hash (loops.md §4.2). */
     variants?: Record<string, AgentManifest>;
-    implementationVersion: string;
     info?: any;
     status: string;
     activeTurnId: string | null;
@@ -83,26 +92,35 @@ export interface Session {
      * and the context core hands on (to the harness, tools and sandbox commands) is in it.
      */
     turnTrace?: TraceContext;
+    /**
+     * What started the active turn when not a client (track T4): the trigger's run, or the session's
+     * own booked wake. A memory version written in the turn names its run (track T5).
+     */
+    turnCause?: {
+        kind: "trigger" | "self";
+        triggerId: string;
+        runId: string;
+    };
     creation: unknown;
     mcpSnapshot?: McpSnapshot;
     mcpDiagnostics?: readonly McpDiagnostic[];
     /**
-     * The Environment the session names (`environment`, protocol 11): its sandbox is the
-     * session's (the Environment's id keys the workspace) and its vault holds the session's
+     * The Agent's environment the session runs on: since protocol 16 always its Agent's id. Its
+     * sandbox is the session's (the id keys the workspace) and its vault holds the session's
      * credentials. It outlives the session.
      */
     environmentId?: string;
-    /** The Environment's recipe version when the session opened (shown, never enforced). */
+    /** The Agent's recipe version when the session last pinned (shown, never enforced). */
     environmentVersion?: number;
     /**
-     * The harness that runs the session's turns (R4.1), pinned when it opened: its Environment's
-     * harness, else `nylorun`. Absent on a session opened before R4: ours (`harnessOf`).
+     * The harness that runs the session's turns (R4.1), pinned when it opened: its manifest's
+     * `harness.id`, else `nylorun`. Absent on a session opened before R4: ours (`harnessOf`).
      */
     harness?: string;
     /**
      * A flow agent's linked session: the session whose turn opened the flow tree. Its sessions
      * share the tree's Environment, and their turns nest in the root's, so they do not hold the
-     * Environment against each other (`checkEnvironmentTurn`).
+     * Environment against each other (`checkAgentTurn`).
      */
     flowRootId?: string;
     /**
@@ -114,7 +132,8 @@ export interface Session {
      * Why the session takes no new turn: `protocol_11` for a session opened before protocol 11
      * (migration 0020), `protocol_13` for one opened before protocol 13 (migration 0024),
      * `protocol_15` for an agent session that pinned a `runtime` block before protocol 15
-     * (migrations 0029, 0030). Its history stays readable.
+     * (migrations 0029, 0030), `protocol_16` for one opened from a definition before protocol 16
+     * (migration 0032). Its history stays readable.
      */
     closedReason?: string;
     /**
@@ -138,7 +157,7 @@ export type AuthScope = {
 }
 /**
  * A trusted issuer's token (Host feature `trusted-issuers`, F9-D12): one subject, with the
- * issuer's scopes, agents and Environment grants, until `expiresAt` (ms). Only its expiry ends it.
+ * issuer's scopes and Agent grants, until `expiresAt` (ms). Only its expiry ends it.
  */
  | {
     kind: "token";
@@ -147,9 +166,8 @@ export type AuthScope = {
     subject: string;
     /** The issuer's scopes the token holds, which may add `studio`. */
     scopes: ReadonlySet<IssuerScope>;
-    agents: ReadonlySet<string> | "*";
-    /** The Environments it reaches: exact ids or `p/*` prefixes. Absent or empty reaches none. */
-    environments?: readonly string[];
+    /** The Agents it reaches: `*`, else exact ids or `p/*` prefixes; empty reaches none. */
+    agents: readonly string[] | "*";
     expiresAt: number;
     /** The token's `jti`, or a hash of it. */
     tokenId: string;
@@ -264,7 +282,7 @@ export interface TenantContext {
     abortLocal(sessionId: string, turnId?: string): void;
     /**
      * Sandbox pods (F7.2): the sandboxes service and the Runtime image pods copy the engine from.
-     * Absent without a cluster (`nylorun local sandbox enable`): kind `pod` is `environment_unavailable`.
+     * Absent without a cluster (`nylorun local sandbox enable`): kind `pod` is `agent_unavailable`.
      */
     readonly pods?: TenantPods;
     /**
@@ -274,6 +292,12 @@ export interface TenantContext {
      * sent); `true` without sandbox pods, where there is nothing to send.
      */
     sandboxSignal(sandboxId: string, signal: SandboxSignal): Promise<boolean>;
+    /**
+     * Seam: arm a durable timer (`DurableExecution.timer`; track T4's triggers), outside any tx. The
+     * latest time for a key wins. `false` while the Tenant is closing (not armed): what it was for
+     * is in Postgres, and the sweep arms it again.
+     */
+    timer(key: string, at: Date): Promise<boolean>;
     /** This Tenant's execution invocations that need an operator, for Tenant status. */
     readonly stuckInvocations?: () => Promise<StuckInvocation[]>;
     /** Callbacks the Tenant sweep runs after its own steps (`sweep.ts`). */
@@ -283,12 +307,15 @@ export interface TenantContext {
 }
 /**
  * What a request acting for a person may reach: that person's sessions, and, for a token
- * caller, only sessions of the agents its issuer allows. Undefined means the whole Tenant.
+ * caller, only sessions on the Agents its grants reach (ids and `p/*` prefixes). Undefined means
+ * the whole Tenant.
  */
 export interface SessionAccess {
     readonly owner: string;
-    readonly agents?: ReadonlySet<string>;
+    readonly agents?: readonly string[];
 }
+/** Whether `access` reaches sessions on Agent `agentId`. */
+export declare function reachesAgent(access: SessionAccess | undefined, agentId: string): boolean;
 /** The session, or a 404. Reads without locking. */
 export declare function sessionOf(t: Tx, id: string, access?: SessionAccess): Promise<Session>;
 /** Locks the session for the rest of the transaction and returns it, or a 404. */