@nylorun/runtime 0.38.0-beta → 0.40.0-beta

package/dist/store/postgres/store.js

@@ -1460,6 +1460,20 @@ class PostgresTx {
             .orderBy(desc(memoryVersions.id))
             .limit(options.limit);
     }
+    async memoryWritesSince(agentId, after, sessionId) {
+        this.check();
+        const conditions = [eq(memoryVersions.agentId, agentId)];
+        if (after !== undefined)
+            conditions.push(gt(memoryVersions.id, after));
+        const [row] = await this.db
+            .select({
+            newest: sql `max(${memoryVersions.id})`,
+            others: sql `coalesce(bool_or(${memoryVersions.sessionId} is distinct from ${sessionId}), false)`,
+        })
+            .from(memoryVersions)
+            .where(and(...conditions));
+        return { ...(row?.newest ? { newest: row.newest } : {}), others: row?.others === true };
+    }
     async memoryVersion(agentId, id) {
         this.check();
         const [row] = await this.db

package/dist/store/types.d.ts

@@ -803,6 +803,15 @@ export interface Tx {
         before?: string;
         limit: number;
     }): Promise<MemoryVersionRow[]>;
+    /**
+     * Of Agent `agentId`'s memory versions after version id `after` (every one without it): the
+     * newest's id, and whether any was written other than by session `sessionId` (another session,
+     * or the API).
+     */
+    memoryWritesSince(agentId: string, after: string | undefined, sessionId: string): Promise<{
+        newest?: string;
+        others: boolean;
+    }>;
     memoryVersion(agentId: string, id: string): Promise<MemoryVersionRow | undefined>;
     /** Copies Agent `from`'s memories to new Agent `to`, each at version 1, with no history (a fork). */
     copyMemories(from: string, to: string, now: string): Promise<number>;

package/dist/tenant/agent-versions.d.ts

@@ -21,8 +21,11 @@
  * - **A turn takes the Agent's version.** A turn's first segment re-pins its session to the
  *   version the Agent runs when that changed since the session's last turn (`repinTurn`), before
  *   anything of the turn has run: no effect is journaled for it yet. The turn keeps that version
- *   through every later segment, approval and rollover. A turn whose message named a variant,
- *   and a flow's sessions, keep the version they pinned.
+ *   through every later segment, approval and rollover. What its message asked of the turn's
+ *   manifest (`Session.turnRequest`) applies again to the new version: its `removeTools`, and its
+ *   variant, validated again against the new version. A variant that is no variant of it keeps
+ *   the turn on the version it pinned (`turn.version_kept`), so a variant never widens what the
+ *   turn may do. A flow's sessions keep the version they pinned.
  *
  * Re-pinning at the first segment, not when the message is accepted, keeps a turn that waits for
  * its compute to start on a version the Agent has at that start.
@@ -64,9 +67,14 @@ export declare function applyPin(session: Session, pin: SessionPin): void;
  * active turn is about to run its first segment and nothing of the turn has run yet: the turn
  * then runs that version. Returns whether it changed the session (the caller saves it).
  *
- * Leaves the session as it is for a flow and a flow's linked session, a turn whose message named
- * a variant, a later segment, a turn with any journaled effect, and a version whose harness is
- * not the session's (an Agent's harness is fixed for its life, D73).
+ * The turn's manifest on the new version is what its message asked (`Session.turnRequest`):
+ * its variant, validated against the new version, without the tools its `removeTools` names.
+ *
+ * Leaves the session as it is for a flow and a flow's linked session, a later segment, a turn
+ * with any journaled effect, a version whose harness is not the session's (an Agent's harness is
+ * fixed for its life, D73), a turn on a variant with no request recorded (accepted by an older
+ * Runtime), and a variant that is no variant of the new version: then the turn runs on the
+ * version it pinned, and `turn.version_kept` says why.
  */
 export declare function repinTurn(t: Tx, session: Session): Promise<boolean>;
 /** What a move of `agent` to `target` would do, and the target's runtime resolved. */

package/dist/tenant/agent-versions.js

@@ -1,6 +1,8 @@
 import { hashManifest } from "@nylorun/core/compatibility";
 import { loopManifestOf, runtimeOf } from "@nylorun/core/define";
 import { isWorkflowManifest } from "../core/flow-host.js";
+import { turnManifestFor } from "../core/turn-manifest.js";
+import { variantStore } from "./session.js";
 import { canonical } from "../store/canonical.js";
 import { resolveRecipe, sandboxSpecOf } from "../sandbox/resolve.js";
 import { effectiveSandboxConfig, readSandboxConfig } from "../sandbox/tenant-config.js";
@@ -60,9 +62,14 @@ export function applyPin(session, pin) {
  * active turn is about to run its first segment and nothing of the turn has run yet: the turn
  * then runs that version. Returns whether it changed the session (the caller saves it).
  *
- * Leaves the session as it is for a flow and a flow's linked session, a turn whose message named
- * a variant, a later segment, a turn with any journaled effect, and a version whose harness is
- * not the session's (an Agent's harness is fixed for its life, D73).
+ * The turn's manifest on the new version is what its message asked (`Session.turnRequest`):
+ * its variant, validated against the new version, without the tools its `removeTools` names.
+ *
+ * Leaves the session as it is for a flow and a flow's linked session, a later segment, a turn
+ * with any journaled effect, a version whose harness is not the session's (an Agent's harness is
+ * fixed for its life, D73), a turn on a variant with no request recorded (accepted by an older
+ * Runtime), and a variant that is no variant of the new version: then the turn runs on the
+ * version it pinned, and `turn.version_kept` says why.
  */
 export async function repinTurn(t, session) {
     const id = session.environmentId;
@@ -73,8 +80,9 @@ export async function repinTurn(t, session) {
         return false;
     if (!checkpoint || checkpoint.segment !== 0 || checkpoint.turnId !== session.activeTurnId)
         return false;
-    // A variant the message named (a turn-manifest variant) is validated against the old pin.
-    if (checkpoint.manifestHash !== session.manifestHash)
+    const request = session.turnRequest?.turnId === session.activeTurnId ? session.turnRequest : undefined;
+    // A variant whose request is not recorded cannot be validated against another version.
+    if (checkpoint.manifestHash !== session.manifestHash && request === undefined)
         return false;
     const agent = await t.environment(id);
     if (!agent)
@@ -86,10 +94,26 @@ export async function repinTurn(t, session) {
     const { pin } = await pinOf(t, agent);
     if (pin.harness !== harnessOf(session))
         return false;
+    const turn = request
+        ? turnManifestFor({ pinned: pin.manifest, pinnedHash: pin.manifestHash, request })
+        : { ok: true, manifest: pin.manifest, hash: pin.manifestHash };
+    if (!turn.ok) {
+        const from = { ...session.definition };
+        const to = { name: agent.manifestName, version: agent.manifestVersion };
+        await t.event(session.id, session.activeTurnId, "turn.version_kept", {
+            reason: "variant_invalid",
+            from,
+            to,
+            message: `The turn manifest the message carried is no variant of ${to.name}@${to.version}, the version Agent ${agent.id} runs now, so this turn runs on ${from.name}@${from.version}. Send a variant of the new version, or name the tools the turn may not use with removeTools.`,
+        });
+        return false;
+    }
     const changed = pin.manifestHash !== session.manifestHash;
     applyPin(session, pin);
     session.environmentVersion = agent.version;
-    session.checkpoint = { ...session.checkpoint, manifestHash: pin.manifestHash };
+    if (turn.hash !== pin.manifestHash)
+        variantStore(session).put(turn.hash, turn.manifest);
+    session.checkpoint = { ...session.checkpoint, manifestHash: turn.hash };
     // MCP discovery is per loop manifest: the next one is the new version's.
     if (changed) {
         delete session.mcpSnapshot;

package/dist/tenant/agents.d.ts

@@ -56,13 +56,25 @@ export declare function planAgentPut(ctx: TenantContext, id: string, body: PutAg
  * they are set (track T3). Best effort: the write stands either way.
  */
 export declare function secretWritten(ctx: TenantContext, id: string): Promise<void>;
+/**
+ * A secret write as the vault takes it (`Keys.putEnvironmentSecret`): the typed request, and
+ * whether its `via` is the slot's (`viaFromSlot`), so a session follows the slot of the version
+ * its Agent runs, rather than this installation's own `via` (Host feature `secret-routing`).
+ */
+export interface SecretWrite {
+    readonly request: PutAgentSecretRequest;
+    readonly viaFromSlot: boolean;
+}
 /**
  * The secret write `raw` asks of Environment `id` (D64). When what it runs declares secret
  * slots, the name must be one (`409 secret_not_in_manifest`), and the body is `{ value }` (or
  * `{ headers }` for a `headers` slot) with the binding from the slot; a full typed body is
- * accepted only when its binding is the slot's. Without slots, today's typed body.
+ * accepted only when its binding is the slot's. Without slots, today's typed body. Either way a
+ * `bearer` or `headers` slot's write may add this installation's routing (Host feature
+ * `secret-routing`): `via`, which wins over the slot's, and the gateway's `toolPrefix`, which
+ * gives way to the slot's (a different one is accepted, with a warning in the log).
  */
-export declare function secretRequestFor(ctx: TenantContext, id: string, name: string, raw: unknown): Promise<PutAgentSecretRequest>;
+export declare function secretRequestFor(ctx: TenantContext, id: string, name: string, raw: unknown): Promise<SecretWrite>;
 /** What a create does for a fork (`POST .../fork`); `copied` is filled in by the create. */
 interface Fork {
     source: string;

package/dist/tenant/agents.js

@@ -560,15 +560,18 @@ export async function secretWritten(ctx, id) {
  * The secret write `raw` asks of Environment `id` (D64). When what it runs declares secret
  * slots, the name must be one (`409 secret_not_in_manifest`), and the body is `{ value }` (or
  * `{ headers }` for a `headers` slot) with the binding from the slot; a full typed body is
- * accepted only when its binding is the slot's. Without slots, today's typed body.
+ * accepted only when its binding is the slot's. Without slots, today's typed body. Either way a
+ * `bearer` or `headers` slot's write may add this installation's routing (Host feature
+ * `secret-routing`): `via`, which wins over the slot's, and the gateway's `toolPrefix`, which
+ * gives way to the slot's (a different one is accepted, with a warning in the log).
  */
 export async function secretRequestFor(ctx, id, name, raw) {
-    const request = await parseSecretRequest(ctx, id, name, raw);
+    const write = await parseSecretRequest(ctx, id, name, raw);
     // Within the Tenant's Runtime limits `secretValueChars` and `secretHosts`, read for the write.
-    const issues = secretRequestIssues(request, await ctx.store.tx((t) => readRuntimeLimits(t)));
+    const issues = secretRequestIssues(write.request, await ctx.store.tx((t) => readRuntimeLimits(t)));
     if (issues.length > 0)
         fail(400, issues.join(" "));
-    return request;
+    return write;
 }
 async function parseSecretRequest(ctx, id, name, raw) {
     const { environment, slots } = await ctx.store.tx(async (t) => {
@@ -576,38 +579,73 @@ async function parseSecretRequest(ctx, id, name, raw) {
         return { environment, slots: environment && (await slotsAhead(t, environment)) };
     });
     if (!environment || slots === undefined)
-        return PutAgentSecretRequestSchema.parse(raw);
+        return { request: PutAgentSecretRequestSchema.parse(raw), viaFromSlot: false };
     const named = `${environment.manifestName}@${environment.targetVersion ?? environment.manifestVersion}`;
     const slot = slots[name] ??
         fail(409, `Agent ${id}'s manifest (${named}) declares no secret ${name}: add the slot to the manifest's runtime section, then move the Agent to the new version.`, { code: "secret_not_in_manifest", details: { declared: Object.keys(slots).sort() } });
     const full = slotRequest(slot);
+    const slotVia = typeof full.via === "string" ? full.via : undefined;
+    const routed = slot.type === "bearer" || slot.type === "headers";
+    /** The write's prefix gives way to the slot's: said in the log when they differ. */
+    const prefixed = (toolPrefix) => {
+        if (routed && toolPrefix !== undefined && slot.toolPrefix !== undefined && toolPrefix !== slot.toolPrefix)
+            ctx.config.logger.warn("secret tool prefix gives way to the manifest's", {
+                environmentId: id,
+                secret: name,
+                manifest: named,
+            });
+    };
     if (raw !== null && typeof raw === "object" && "type" in raw) {
         const body = PutAgentSecretRequestSchema.parse(raw);
-        // The gateway's tool prefix is this installation's to add (`gateway-credentials`).
-        const { requestId: _, value: _v, headers: _h, toolPrefix: _p, ...binding } = body;
-        if (canonical(binding) !== canonical(full))
+        // This installation's routing (`gateway-credentials`, `secret-routing`): its via and the
+        // gateway's tool prefix are its own to add.
+        const { requestId: _, value: _v, headers: _h, toolPrefix, via, ...binding } = body;
+        const { via: _s, ...slotBinding } = full;
+        if (canonical(binding) !== canonical(slotBinding))
             fail(409, `Secret ${name}'s type and binding come from Agent ${id}'s manifest: send only its value ({ "value": "…" }).`, {
                 code: "secret_not_in_manifest",
             });
-        return body;
+        prefixed(toolPrefix);
+        if (!routed || (via !== undefined && via !== slotVia))
+            return { request: body, viaFromSlot: false };
+        // No via of its own: the slot's, which a session reads from the version its Agent runs.
+        return {
+            request: PutAgentSecretRequestSchema.parse({ ...body, ...(slotVia === undefined ? {} : { via: slotVia }) }),
+            viaFromSlot: slotVia !== undefined,
+        };
     }
-    const { requestId, value, headers, toolPrefix } = PutAgentSecretValueRequestSchema.parse(raw);
+    const { requestId, value, headers, via, toolPrefix } = PutAgentSecretValueRequestSchema.parse(raw);
+    if (!routed && (via !== undefined || toolPrefix !== undefined))
+        fail(400, `Secret ${name} is an ${slot.type}: via and toolPrefix are for a bearer or headers secret.`);
+    if (toolPrefix !== undefined && via === undefined && slotVia === undefined)
+        fail(400, `toolPrefix needs via: Secret ${name}'s slot names none, so send one with the value.`);
+    prefixed(toolPrefix);
     const withId = {
         ...(requestId === undefined ? {} : { requestId }),
         ...(toolPrefix === undefined ? {} : { toolPrefix }),
     };
+    // The write's via wins over the slot's (`secret-routing`); the URL still picks the credential.
+    const routing = via === undefined ? {} : { via };
+    const viaFromSlot = via === undefined && slotVia !== undefined;
     if (slot.type === "headers") {
         if (headers === undefined)
             fail(400, `Secret ${name} is a headers credential: send { "headers": { … } }.`);
-        return PutAgentSecretRequestSchema.parse({ ...withId, ...full, headers });
+        return { request: PutAgentSecretRequestSchema.parse({ ...withId, ...full, ...routing, headers }), viaFromSlot };
     }
     if (value === undefined)
         fail(400, `Secret ${name} takes a value: send { "value": "…" }.`);
-    return PutAgentSecretRequestSchema.parse({ ...withId, ...full, value });
+    return { request: PutAgentSecretRequestSchema.parse({ ...withId, ...full, ...routing, value }), viaFromSlot };
 }
-/** A slot's type and binding, as a secret write's fields (without the value). */
+/**
+ * A slot's type and binding, as a secret write's fields (without the value). A slot's
+ * `toolPrefix` stays the slot's: a session reads it from the version its Agent runs.
+ */
 function slotRequest(slot) {
     const { required: _r, description: _d, ...binding } = slot;
+    if ("toolPrefix" in binding) {
+        const { toolPrefix: _p, ...rest } = binding;
+        return rest;
+    }
     return binding;
 }
 /**

package/dist/tenant/commands.js

@@ -24,7 +24,7 @@
 import { randomUUID } from "node:crypto";
 import { createDurableCheckpoint, createFlowCheckpoint, resumeFlowCheckpoint, } from "@nylorun/harness/run";
 import { commandKey, cancelQueuedEffects, flowInteractionOf, foreignInteractionConflict, isWorkflowManifest, planCancelCascade, wakeLinkedWorkflow, } from "../core/flow-host.js";
-import { resolveMessageManifest } from "../core/turn-manifest.js";
+import { resolveMessageManifest, turnManifestFor, turnManifestRequestOf } from "../core/turn-manifest.js";
 import { canonical } from "../store/canonical.js";
 import { lockedSession, } from "./context.js";
 import { fail, HttpError } from "./http.js";
@@ -388,14 +388,21 @@ async function beginMessageTurn(t, s, id, messages) {
             input: first.input,
         });
     else {
-        const resolved = resolveMessageManifest({
-            pinned: s.manifest,
-            pinnedHash: s.manifestHash,
-            messageManifest: first.command.manifest,
-            store: variantStore(s),
-        });
+        const request = turnManifestRequestOf(first.command);
+        const resolved = turnManifestFor({ pinned: s.manifest, pinnedHash: s.manifestHash, request: request ?? {} });
         if (!resolved.ok)
             return fail(400, resolved.message);
+        if (resolved.hash !== s.manifestHash)
+            variantStore(s).put(resolved.hash, resolved.manifest);
+        // A turn's first segment applies the request again to the version it re-pins (`repinTurn`).
+        if (request)
+            s.turnRequest = {
+                turnId,
+                ...(resolved.variant === undefined ? {} : { manifest: resolved.variant }),
+                ...(request.removeTools === undefined ? {} : { removeTools: [...request.removeTools] }),
+            };
+        else
+            delete s.turnRequest;
         checkpoint = createDurableCheckpoint({
             manifest: resolved.manifest,
             sessionId: id,
@@ -456,7 +463,8 @@ export async function startQueuedTurn(ctx, t, s, id) {
     const queued = await t.queuedMessages(id);
     if (queued.length === 0)
         return undefined;
-    const manifestOf = (row) => canonical(row.command.manifest ?? null);
+    // Messages that ask the same of their turn's manifest (a variant, `removeTools`) share a turn.
+    const manifestOf = (row) => canonical(turnManifestRequestOf(row.command) ?? null);
     const batch = isWorkflowManifest(s.manifest) ? [queued[0]] : [];
     if (batch.length === 0)
         for (const row of queued) {

package/dist/tenant/context.d.ts

@@ -15,7 +15,7 @@
  * under ownership (§10.6); `abortLocal` aborts an advance running on this process.
  */
 import type { SessionHistory } from "./history.js";
-import type { IssuerScope, SessionModelChoice, SubjectScope, TenantEnvelope } from "@nylorun/core/contracts";
+import type { IssuerScope, SessionModelChoice, SessionModelRecord, SubjectScope, TenantEnvelope } from "@nylorun/core/contracts";
 import type { DurableCheckpoint, FlowCheckpoint } from "@nylorun/harness/run";
 import type { AgentManifest, JsonValue, SandboxManifest } from "@nylorun/core/define";
 import type { OutboxRequest, SessionStore, Tx } from "../store/types.js";
@@ -63,6 +63,17 @@ export interface Session {
     loop?: Record<string, unknown>;
     /** Validated turn-manifest variants, keyed by hash (loops.md §4.2). */
     variants?: Record<string, AgentManifest>;
+    /**
+     * What the active turn's first message asked of its manifest: a variant (`manifest`) and the
+     * tools it may not use (`removeTools`, Host feature `remove-tools`). A turn's first segment that
+     * re-pins the session to its Agent's version applies it again to that version (`repinTurn`).
+     * Absent when the message asked for neither.
+     */
+    turnRequest?: {
+        turnId: string;
+        manifest?: AgentManifest;
+        removeTools?: string[];
+    };
     info?: any;
     status: string;
     activeTurnId: string | null;
@@ -147,6 +158,24 @@ export interface Session {
      * place of the Tenant's while its provider is connected. Absent: the Tenant's model.
      */
     model?: SessionModelChoice;
+    /**
+     * The Agent's memory as the session's last turn started (track T5): the newest memory version
+     * then (`seen`), and whether that turn's first segment asked the harness to pin the index again
+     * (`refresh`: someone else wrote the memory since the turn before). Absent before its first turn.
+     */
+    memoryIndex?: {
+        turnId: string;
+        seen?: string;
+        refresh: boolean;
+    };
+    /** Where `model` came from: `manifest` when its Agent's version named it (`harness.model`). Absent: chosen. */
+    modelSource?: "manifest";
+    /**
+     * The model the session's turns call and why (`SessionModelRecord`, `tenant/session-model.ts`):
+     * as the session opened or chose it, and at each segment's start since. Absent while the
+     * Tenant has no model, and on a session opened before it was kept.
+     */
+    modelRecord?: SessionModelRecord;
 }
 export type AuthScope = {
     kind: "application";

package/dist/tenant/session-model.d.ts

@@ -4,10 +4,15 @@
  * (`Session.model`): the Model Gate reads it at each call (`HostModelVault.readHostModel`) and a
  * turn's start describes it (`turn.start.model`). The Tenant's model, and every other session's,
  * stay as they are. While its provider is disconnected the session uses the Tenant's model again.
+ *
+ * What its turns call, and why, is kept too (`Session.modelRecord`, `SessionModelRecord`): set when
+ * the session opens (the manifest's model, or the Tenant's and why), when it chooses or clears its
+ * model, and again at each segment's start, when a provider was connected or disconnected or the
+ * Tenant's model changed. Each change writes `session.model`.
  */
-import { type SessionModelChoice, type SessionModelView } from "@nylorun/core/contracts";
+import { type SessionModelChoice, type SessionModelRecord, type SessionModelView } from "@nylorun/core/contracts";
 import type { Tx } from "../store/types.js";
-import { type SessionAccess, type TenantContext } from "./context.js";
+import { type Session, type SessionAccess, type TenantContext } from "./context.js";
 /** The model the session's next turn uses, and where it comes from. */
 export declare function readSessionModel(ctx: TenantContext, id: string, access: SessionAccess | undefined): Promise<SessionModelView>;
 /**
@@ -15,12 +20,36 @@ export declare function readSessionModel(ctx: TenantContext, id: string, access:
  * Tenant's. A turn calls one model: the choice changes only while no turn runs or waits.
  */
 export declare function chooseSessionModel(ctx: TenantContext, id: string, choice: SessionModelChoice | undefined, access: SessionAccess | undefined): Promise<SessionModelView>;
+/** Why a session's turns call the Tenant's model in place of the one asked for, and that one. */
+export interface ModelFallback {
+    readonly reason: NonNullable<SessionModelRecord["reason"]>;
+    readonly requested: NonNullable<SessionModelRecord["requested"]>;
+}
 /**
  * The model a new session starts with (Host feature `agent-model`): the one its version's
- * `harness.model` names, as `chooseSessionModel` would take it, or undefined when it names none or
- * one the Tenant cannot use now (a provider not connected, a model its catalog does not list), so
- * the Tenant's model applies. Never fails the session.
+ * `harness.model` names, as `chooseSessionModel` would take it (`choice`), or, when it names one
+ * the Tenant cannot use now (a provider not connected, a model its catalog does not list), why
+ * (`fallback`), so the Tenant's model applies. Undefined when it names none. Never fails the
+ * session.
  */
 export declare function agentModelOf(t: Tx, harness: {
     readonly model?: unknown;
-}): Promise<SessionModelChoice | undefined>;
+}): Promise<{
+    choice: SessionModelChoice;
+} | {
+    fallback: ModelFallback;
+} | undefined>;
+/**
+ * The model session `s`'s turns call now, and why (`SessionModelRecord`, as the Model Gate picks
+ * it: `hostCredentialRowOf`): its own model while its provider is connected (`source` `manifest`
+ * when its Agent's version named it, else `session`), else the Tenant's, with the reason when it
+ * falls back. `fallback` is why the session opened without the model its manifest names; kept
+ * from the session's record otherwise, until it chooses or clears a model. Undefined while the
+ * Tenant has no model to fall back to.
+ */
+export declare function sessionModelRecordOf(t: Tx, s: Pick<Session, "model" | "modelSource" | "modelRecord">, fallback?: ModelFallback): Promise<SessionModelRecord | undefined>;
+/**
+ * Keeps `record` as session `s`'s model record (the caller saves `s`) and, when it differs from
+ * the one it had, writes `session.model` with the one before. Returns whether it changed.
+ */
+export declare function noteSessionModel(t: Tx, s: Session, record: SessionModelRecord | undefined): Promise<boolean>;

package/dist/tenant/session-model.js

@@ -4,10 +4,16 @@
  * (`Session.model`): the Model Gate reads it at each call (`HostModelVault.readHostModel`) and a
  * turn's start describes it (`turn.start.model`). The Tenant's model, and every other session's,
  * stay as they are. While its provider is disconnected the session uses the Tenant's model again.
+ *
+ * What its turns call, and why, is kept too (`Session.modelRecord`, `SessionModelRecord`): set when
+ * the session opens (the manifest's model, or the Tenant's and why), when it chooses or clears its
+ * model, and again at each segment's start, when a provider was connected or disconnected or the
+ * Tenant's model changed. Each change writes `session.model`.
  */
-import { agentModelChoice } from "@nylorun/core/contracts";
+import { agentModelChoice, } from "@nylorun/core/contracts";
+import { canonical } from "../store/canonical.js";
 import { catalogModel, hostModelCatalog } from "../model/catalog.js";
-import { hostCredentialRowFor, modelBinding } from "../vault/service.js";
+import { activeHostCredentialRow, hostCredentialRowFor, modelBinding } from "../vault/service.js";
 import { takesMessages } from "./commands.js";
 import { lockedSession, sessionOf } from "./context.js";
 import { fail } from "./http.js";
@@ -29,8 +35,9 @@ export async function chooseSessionModel(ctx, id, choice, access) {
             });
         if (choice)
             await checkChoice(t, choice);
-        const { model: _model, ...rest } = s;
+        const { model: _model, modelSource: _source, ...rest } = s;
         const next = choice ? { ...rest, model: { provider: choice.provider, model: choice.model } } : rest;
+        await noteSessionModel(t, next, await sessionModelRecordOf(t, next));
         await t.put("sessions", id, next);
         return next;
     });
@@ -38,15 +45,70 @@ export async function chooseSessionModel(ctx, id, choice, access) {
 }
 /**
  * The model a new session starts with (Host feature `agent-model`): the one its version's
- * `harness.model` names, as `chooseSessionModel` would take it, or undefined when it names none or
- * one the Tenant cannot use now (a provider not connected, a model its catalog does not list), so
- * the Tenant's model applies. Never fails the session.
+ * `harness.model` names, as `chooseSessionModel` would take it (`choice`), or, when it names one
+ * the Tenant cannot use now (a provider not connected, a model its catalog does not list), why
+ * (`fallback`), so the Tenant's model applies. Undefined when it names none. Never fails the
+ * session.
  */
 export async function agentModelOf(t, harness) {
     if (typeof harness.model !== "string")
         return undefined;
     const choice = agentModelChoice(harness.model);
-    return choice && (await choiceIssue(t, choice)) === undefined ? choice : undefined;
+    if (!choice)
+        return undefined;
+    const issue = await choiceIssue(t, choice);
+    return issue === undefined
+        ? { choice }
+        : { fallback: { reason: issue.reason, requested: { ...choice, by: "manifest" } } };
+}
+/**
+ * The model session `s`'s turns call now, and why (`SessionModelRecord`, as the Model Gate picks
+ * it: `hostCredentialRowOf`): its own model while its provider is connected (`source` `manifest`
+ * when its Agent's version named it, else `session`), else the Tenant's, with the reason when it
+ * falls back. `fallback` is why the session opened without the model its manifest names; kept
+ * from the session's record otherwise, until it chooses or clears a model. Undefined while the
+ * Tenant has no model to fall back to.
+ */
+export async function sessionModelRecordOf(t, s, fallback) {
+    if (s.model) {
+        const by = s.modelSource ?? "session";
+        if (await hostCredentialRowFor(t, s.model.provider))
+            return { provider: s.model.provider, model: s.model.model, source: by };
+        return tenantModelRecord(t, { reason: "provider_not_connected", requested: { ...s.model, by } });
+    }
+    const kept = fallback ??
+        (s.modelRecord?.reason !== undefined && s.modelRecord.requested?.by === "manifest"
+            ? { reason: s.modelRecord.reason, requested: s.modelRecord.requested }
+            : undefined);
+    return tenantModelRecord(t, kept);
+}
+async function tenantModelRecord(t, fallback) {
+    const row = await activeHostCredentialRow(t);
+    if (!row)
+        return undefined;
+    const binding = modelBinding(row);
+    return {
+        provider: binding.provider,
+        model: binding.model,
+        source: "tenant",
+        ...(fallback === undefined ? {} : { reason: fallback.reason, requested: { ...fallback.requested } }),
+    };
+}
+/**
+ * Keeps `record` as session `s`'s model record (the caller saves `s`) and, when it differs from
+ * the one it had, writes `session.model` with the one before. Returns whether it changed.
+ */
+export async function noteSessionModel(t, s, record) {
+    if (canonical(record ?? null) === canonical(s.modelRecord ?? null))
+        return false;
+    const previous = s.modelRecord;
+    if (record === undefined) {
+        delete s.modelRecord;
+        return true;
+    }
+    s.modelRecord = record;
+    await t.event(s.id, s.activeTurnId, "session.model", { ...record, ...(previous ? { previous } : {}) });
+    return true;
 }
 /** A choice names a connected provider and, when its catalog lists models, one of them. */
 async function checkChoice(t, choice) {
@@ -57,19 +119,25 @@ async function checkChoice(t, choice) {
 /** Why `choice` is not one the Tenant can use now; undefined when it is. */
 async function choiceIssue(t, choice) {
     if (!/^[a-zA-Z0-9._-]+$/.test(choice.provider))
-        return { status: 400, message: "Invalid provider id", code: "invalid_request" };
+        return { status: 400, message: "Invalid provider id", code: "invalid_request", reason: "invalid_model" };
     const row = await hostCredentialRowFor(t, choice.provider);
     if (!row)
         return {
             status: 422,
             message: `Model provider ${choice.provider} is not connected: connect it in Model Settings first`,
             code: "request_rejected",
+            reason: "provider_not_connected",
         };
     // A custom endpoint serves the models it names; the provider's own model is always one.
     if (choice.provider === "custom" || modelBinding(row).model === choice.model)
         return undefined;
     const listed = hostModelCatalog().providers.find((provider) => provider.id === choice.provider);
     if (listed && listed.models.length > 0 && !catalogModel(choice.provider, choice.model))
-        return { status: 422, message: `Unknown model ${choice.model} for provider ${choice.provider}`, code: "request_rejected" };
+        return {
+            status: 422,
+            message: `Unknown model ${choice.model} for provider ${choice.provider}`,
+            code: "request_rejected",
+            reason: "not_in_catalog",
+        };
     return undefined;
 }

package/dist/tenant/sessions.js

@@ -15,7 +15,7 @@ import { openAgent, recordAttachment } from "./agents.js";
 import { harnessOf, reachesAgent, } from "./context.js";
 import { fail } from "./http.js";
 import { definitionFileIssues } from "./definition-files.js";
-import { agentModelOf } from "./session-model.js";
+import { agentModelOf, noteSessionModel, sessionModelRecordOf } from "./session-model.js";
 import { limitsInForce, readTenantLimits } from "./limits.js";
 /** A session's creation identity: everything but the request id. */
 const sessionIdentity = (value) => {
@@ -98,7 +98,8 @@ export async function openSessionIn(ctx, t, id, body, access, options = {}) {
         await requirePods(ctx.pods, `Agent ${agent.id}`);
     // The model the version names (`harness.model`, Host feature `agent-model`) is the new
     // session's own, as `chooseSessionModel` would make it, when the Tenant can use it now.
-    const model = await agentModelOf(t, version.body.harness);
+    const asked = await agentModelOf(t, version.body.harness);
+    const model = asked && "choice" in asked ? asked.choice : undefined;
     const created = {
         id,
         agentId: agent.id,
@@ -115,10 +116,16 @@ export async function openSessionIn(ctx, t, id, body, access, options = {}) {
         environmentId: agent.id,
         environmentVersion: agent.version,
         ...(pin.sandbox === undefined ? {} : { sandbox: pin.sandbox }),
-        ...(model === undefined ? {} : { model }),
+        ...(model === undefined ? {} : { model, modelSource: "manifest" }),
     };
     await t.put("sessions", id, created);
     await recordAttachment(t, id, agent.id);
+    // The model its turns call, and why: a flow's agents call theirs in their own sessions.
+    if (!isWorkflowManifest(pin.manifest)) {
+        const fallback = asked && "fallback" in asked ? asked.fallback : undefined;
+        if (await noteSessionModel(t, created, await sessionModelRecordOf(t, created, fallback)))
+            await t.put("sessions", id, created);
+    }
     return created;
 }
 /**
@@ -165,6 +172,9 @@ export async function sessionView(t, s) {
         ...(s.closedReason === undefined ? {} : { closedReason: s.closedReason }),
         mcpSnapshot: s.mcpSnapshot ?? null,
         mcpDiagnostics: s.mcpDiagnostics ?? [],
+        // As its last turn started; a session that kept none yet (older, or opened before the
+        // Tenant had a model) answers what its next turn would call.
+        model: isWorkflowManifest(s.manifest) ? null : (s.modelRecord ?? (await sessionModelRecordOf(t, s)) ?? null),
         waits,
         error: s.error,
         uncertainEffects: uncertain.map((e) => ({