@nylorun/runtime 0.31.0-beta → 0.33.0-beta

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

@@ -1,4 +1,4 @@
-import { type AgentManifestChange, type AgentManifestPlan, type AgentManifestSource, type AgentManifestV8, type AgentManifestVersions, type AgentManifestView, type PutAgentFolderRequest, type PutAgentManifestRequest, type SaveAgentManifestResponse } from "@nylorun/core/contracts";
+import { type AgentManifestChange, type AgentManifestPlan, type AgentManifestSource, type AgentManifestSourceDiff, type AgentManifestV8, type AgentManifestVersions, type AgentManifestView, type PutAgentFolderRequest, type PutAgentManifestRequest, type SaveAgentManifestResponse } from "@nylorun/core/contracts";
 import { type RecipeRequest } from "../sandbox/resolve.js";
 import type { AuthScope, TenantContext } from "./context.js";
 /** What a manifest's runtime section asks of an Agent's recipe, with the harness its loop names. */
@@ -47,6 +47,11 @@ export declare function readAgentManifestSourceFile(ctx: TenantContext, name: st
     body: ReadableStream<Uint8Array>;
     size: number;
 }>;
+/**
+ * `GET /v1/agent-manifests/{name}/source/diff?from=&to=`: the files added, removed and changed
+ * (by SHA-256) from version `from`'s source to version `to`'s; a `404` when either was saved as JSON.
+ */
+export declare function diffAgentManifestSources(ctx: TenantContext, name: string, from: number, to: number): Promise<AgentManifestSourceDiff>;
 /** `GET /v1/agent-manifests/{name}` (the latest) and `.../versions/{n}`. */
 export declare function getAgentManifest(ctx: TenantContext, name: string, version?: number): Promise<AgentManifestView>;
 /** `GET /v1/agent-manifests`: each manifest's latest version. */

package/dist/tenant/agent-manifests.js

@@ -27,9 +27,11 @@
  *   compile is `422 folder_invalid`, every diagnostic in `details.diagnostics`), and saves the
  *   manifest as above, with the folder kept as the version's source (`source`, its files recorded
  *   as the version's definition files). A folder whose manifest is unchanged saves no new
- *   version, so its source is not saved either.
+ *   version, so its source is not saved either. What a folder may hold is the Tenant's Runtime
+ *   limits `folderFiles`, `folderBytes` and `folderTextFileBytes` (track T7), which the compiler
+ *   is given too; `source/diff` compares two versions' sources by path and hash.
  */
-import { compileAgentFolder, folderTextPaths, AGENT_FOLDER_LIMITS, } from "@nylorun/core/folder";
+import { compileAgentFolder, folderTextPaths, } from "@nylorun/core/folder";
 import { definitionFilesOf, } from "@nylorun/core/contracts";
 import { hashManifest } from "@nylorun/core/compatibility";
 import { approvalRefusal, codeToolRefusal, harnessIdOf, loopManifestOf, runtimeOf, sectionGaps, } from "@nylorun/core/define";
@@ -356,10 +358,17 @@ async function saveManifest(ctx, name, manifest, scope, options, folder) {
  */
 export async function saveAgentFolder(ctx, name, body, scope, options = {}) {
     const entries = [...body.entries].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
-    if (entries.length > AGENT_FOLDER_LIMITS.files)
-        fail(413, `An agent folder holds at most ${AGENT_FOLDER_LIMITS.files} files; this one holds ${entries.length}`, {
+    const limits = folderLimitsOf(await ctx.store.tx((t) => readRuntimeLimits(t)));
+    if (entries.length > limits.files)
+        fail(413, `An agent folder holds at most ${limits.files} files (the Runtime limit folderFiles); this one holds ${entries.length}`, {
             code: "limit_exceeded",
-            details: { limit: AGENT_FOLDER_LIMITS.files },
+            details: { limit: "folderFiles", value: limits.files },
+        });
+    const bytes = entries.reduce((sum, entry) => sum + entry.size, 0);
+    if (bytes > limits.totalBytes)
+        fail(413, `An agent folder holds at most ${limits.totalBytes} bytes (the Runtime limit folderBytes); this one holds ${bytes}`, {
+            code: "limit_exceeded",
+            details: { limit: "folderBytes", value: limits.totalBytes },
         });
     // Every file must be held: the version keeps them all as its source.
     const shas = [...new Set(entries.map((entry) => `sha256:${entry.sha256}`))].sort();
@@ -377,13 +386,13 @@ export async function saveAgentFolder(ctx, name, body, scope, options = {}) {
     const files = new Map();
     for (const path of folderTextPaths(entries)) {
         const entry = entries.find((item) => item.path === path);
-        if (entry.size > AGENT_FOLDER_LIMITS.textFileBytes)
+        if (entry.size > limits.textFileBytes)
             continue;
         const bytes = await readDefinitionFile(ctx.blobs, `sha256:${entry.sha256}`);
         if (bytes)
             files.set(path, bytes);
     }
-    const compiled = compileAgentFolder({ entries, files, name });
+    const compiled = compileAgentFolder({ entries, files, name, limits });
     if (!compiled.manifest) {
         const errors = compiled.diagnostics.filter((item) => item.severity === "error");
         fail(422, `Agent folder ${name} does not compile: ${errors.length} error(s), the first: ${located(errors[0])}`, {
@@ -394,7 +403,7 @@ export async function saveAgentFolder(ctx, name, body, scope, options = {}) {
     const source = {
         compiler: compiled.compiler,
         files: entries.length,
-        bytes: entries.reduce((sum, entry) => sum + entry.size, 0),
+        bytes,
         entries: entries.map((entry) => ({ path: entry.path, size: entry.size, sha256: entry.sha256 })),
     };
     return saveManifest(ctx, name, compiled.manifest, scope, options, {
@@ -403,6 +412,10 @@ export async function saveAgentFolder(ctx, name, body, scope, options = {}) {
         compiler: compiled.compiler,
     });
 }
+/** What a folder may hold: the Tenant's Runtime limits, as the compiler takes them. */
+function folderLimitsOf(limits) {
+    return { files: limits.folderFiles, totalBytes: limits.folderBytes, textFileBytes: limits.folderTextFileBytes };
+}
 /** A diagnostic as a person reads it: `file:line:column message`. */
 function located(diagnostic) {
     if (!diagnostic)
@@ -435,6 +448,35 @@ export async function readAgentManifestSourceFile(ctx, name, version, path) {
         fail(404, `The Runtime no longer holds ${path} of version ${version} of agent manifest ${name}.`, { code: "not_found" });
     return { body: body, size: entry.size };
 }
+/**
+ * `GET /v1/agent-manifests/{name}/source/diff?from=&to=`: the files added, removed and changed
+ * (by SHA-256) from version `from`'s source to version `to`'s; a `404` when either was saved as JSON.
+ */
+export async function diffAgentManifestSources(ctx, name, from, to) {
+    const before = new Map((await sourceOf(ctx, name, from)).entries.map((entry) => [entry.path, entry]));
+    const after = (await sourceOf(ctx, name, to)).entries;
+    const diff = { name, from, to, added: [], removed: [], changed: [], unchanged: 0 };
+    for (const entry of after) {
+        const was = before.get(entry.path);
+        before.delete(entry.path);
+        if (!was)
+            diff.added.push(entry);
+        else if (was.sha256 === entry.sha256)
+            diff.unchanged++;
+        else
+            diff.changed.push({
+                path: entry.path,
+                from: { size: was.size, sha256: was.sha256 },
+                to: { size: entry.size, sha256: entry.sha256 },
+            });
+    }
+    diff.removed.push(...before.values());
+    const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    diff.added.sort(byPath);
+    diff.removed.sort(byPath);
+    diff.changed.sort(byPath);
+    return diff;
+}
 /** `GET /v1/agent-manifests/{name}` (the latest) and `.../versions/{n}`. */
 export async function getAgentManifest(ctx, name, version) {
     return ctx.store.tx(async (t) => {

package/dist/tenant/agents.d.ts

@@ -17,10 +17,11 @@ export declare function liveEnvironment(t: Tx, id: string, options?: {
  * An Agent's state (protocol 16), from its desired state, its compute and its sessions, and
  * every state that holds with the session behind it (`attention`), highest first. A session waits
  * on a person while it is paused (an approval or an interaction) or uncertain, and the Agent while
- * a move waits for its required secrets (track T3); a session's last turn
- * failed while it is `failed`; a turn runs while it is `running`, `runnable` or `waiting`.
+ * a move waits for its required secrets (track T3), or a required secret of the version it runs
+ * has no value (`unsetSecrets`, track T7: a tool would fail when it is called); a session's last
+ * turn failed while it is `failed`; a turn runs while it is `running`, `runnable` or `waiting`.
  */
-export declare function stateOf(agent: Pick<Environment, "desiredState" | "pod"> & Partial<Pick<Environment, "targetVersion" | "appliedVersion" | "version" | "failedVersion">>, sessions: readonly Pick<Session, "id" | "status">[]): {
+export declare function stateOf(agent: Pick<Environment, "desiredState" | "pod"> & Partial<Pick<Environment, "targetVersion" | "appliedVersion" | "version" | "failedVersion">>, sessions: readonly Pick<Session, "id" | "status">[], unsetSecrets?: readonly string[]): {
     state: AgentState;
     attention: AgentAttention[];
 };

package/dist/tenant/agents.js

@@ -22,7 +22,8 @@
  *   the Agent's id).
  * - **State on read.** `state` is derived when it is read, the first rule that holds: `paused`
  *   (desired `off`, track T6), `failing` (its compute failed or was lost, or a session's last
- *   turn failed), `input_required` (a session waits on a person), `working` (a turn runs),
+ *   turn failed), `input_required` (a session waits on a person, or a required secret is unset),
+ *   `working` (a turn runs),
  *   `sleeping`; `attention` names the sessions behind each that holds (`stateOf`).
  * - **Secret slots** (D64): when its manifest declares `secrets`, a secret write sends only the
  *   value, the binding comes from the slot, and a name it does not declare is
@@ -110,16 +111,20 @@ const STATE_RANK = ["paused", "failing", "input_required", "working", "sleeping"
  * An Agent's state (protocol 16), from its desired state, its compute and its sessions, and
  * every state that holds with the session behind it (`attention`), highest first. A session waits
  * on a person while it is paused (an approval or an interaction) or uncertain, and the Agent while
- * a move waits for its required secrets (track T3); a session's last turn
- * failed while it is `failed`; a turn runs while it is `running`, `runnable` or `waiting`.
+ * a move waits for its required secrets (track T3), or a required secret of the version it runs
+ * has no value (`unsetSecrets`, track T7: a tool would fail when it is called); a session's last
+ * turn failed while it is `failed`; a turn runs while it is `running`, `runnable` or `waiting`.
  */
-export function stateOf(agent, sessions) {
+export function stateOf(agent, sessions, unsetSecrets = []) {
     const attention = [];
     if (agent.desiredState === "off")
         attention.push({ state: "paused", reason: "desired off" });
     // A move that waits for a person to set its required secrets (track T3).
     if (agent.targetVersion !== undefined && agent.appliedVersion === agent.version)
         attention.push({ state: "input_required", reason: `secret_required: version ${agent.targetVersion} waits for its required secrets` });
+    // A required secret of the version it runs, unset (track T7).
+    for (const name of unsetSecrets)
+        attention.push({ state: "input_required", reason: `secret_unset: required secret ${name} unset` });
     const pod = agent.pod;
     if (pod && (pod.observed === "failed" || pod.observed === "lost") && pod.desired !== "deleted")
         attention.push({ state: "failing", reason: `compute ${pod.observed}${pod.reason ? `: ${pod.reason}` : ""}` });
@@ -152,7 +157,7 @@ async function viewOf(ctx, t, environment, owner) {
         : undefined;
     const pod = environment.pod;
     const visible = sessions.filter((session) => owner === undefined || session.ownerUserId === owner);
-    const { state, attention } = stateOf(environment, visible);
+    const { state, attention } = stateOf(environment, visible, await unsetRequiredSecrets(t, environment));
     return {
         id: environment.id,
         manifest: manifestRefOf(environment),
@@ -230,6 +235,22 @@ async function slotsAhead(t, environment) {
     const target = await t.agentManifest(environment.manifestName, environment.targetVersion);
     return target ? runtimeOf(target.body).secrets : environment.applied.secrets;
 }
+/**
+ * The required secret slots of the version `environment` runs (its applied runtime) that its vault
+ * holds no value for, by name: the Agent's attention (track T7), before a tool fails for want of
+ * one. A move waiting on the next version's secrets is its own attention item (`stateOf`).
+ */
+async function unsetRequiredSecrets(t, environment) {
+    const required = Object.entries(environment.applied.secrets ?? {}).filter(([, slot]) => slot.required === true);
+    if (required.length === 0)
+        return [];
+    const vault = await t.vaultOfEnvironment(environment.id);
+    const rows = vault ? await t.credentialsForVault(vault.id) : [];
+    return required
+        .filter(([name, slot]) => !rows.some((row) => row.name === name && slotHolds(slot, row)))
+        .map(([name]) => name)
+        .sort();
+}
 /** Each secret slot `environment` declares (`slotsAhead`), and whether its vault holds a value that fills it. */
 async function slotsOf(t, environment) {
     const declared = await slotsAhead(t, environment);

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, SubjectScope, TenantEnvelope } from "@nylorun/core/contracts";
+import type { IssuerScope, SessionModelChoice, 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";
@@ -141,6 +141,11 @@ export interface Session {
      * Tenant-wide ones beside the session's own. Absent until a message names a file.
      */
     fileArtifacts?: string[];
+    /**
+     * The session's own model (Host feature `session-model`): its turns' model calls use it in
+     * place of the Tenant's while its provider is connected. Absent: the Tenant's model.
+     */
+    model?: SessionModelChoice;
 }
 export type AuthScope = {
     kind: "application";

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

@@ -0,0 +1,16 @@
+/**
+ * A session's own model (Host feature `session-model`): one of a connected provider's models,
+ * which the session's turns use in place of the Tenant's. It is kept on the session
+ * (`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.
+ */
+import type { SessionModelChoice, SessionModelView } from "@nylorun/core/contracts";
+import { 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>;
+/**
+ * Chooses the session's own model, or clears it (`choice` undefined) so its turns use the
+ * 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>;

package/dist/tenant/session-model.js

@@ -0,0 +1,46 @@
+import { catalogModel, hostModelCatalog } from "../model/catalog.js";
+import { hostCredentialRowFor, modelBinding } from "../vault/service.js";
+import { takesMessages } from "./commands.js";
+import { lockedSession, sessionOf } from "./context.js";
+import { fail } from "./http.js";
+/** The model the session's next turn uses, and where it comes from. */
+export async function readSessionModel(ctx, id, access) {
+    const session = await ctx.store.tx((t) => sessionOf(t, id, access));
+    return ctx.vault.getSessionModel(session.model);
+}
+/**
+ * Chooses the session's own model, or clears it (`choice` undefined) so its turns use the
+ * Tenant's. A turn calls one model: the choice changes only while no turn runs or waits.
+ */
+export async function chooseSessionModel(ctx, id, choice, access) {
+    const session = await ctx.store.tx(async (t) => {
+        const s = await lockedSession(t, id, access);
+        if (!takesMessages(s))
+            fail(409, "The session's turn is running or waits: choose its model when the turn ends", {
+                code: "session_busy",
+            });
+        if (choice)
+            await checkChoice(t, choice);
+        const { model: _model, ...rest } = s;
+        const next = choice ? { ...rest, model: { provider: choice.provider, model: choice.model } } : rest;
+        await t.put("sessions", id, next);
+        return next;
+    });
+    return ctx.vault.getSessionModel(session.model);
+}
+/** A choice names a connected provider and, when its catalog lists models, one of them. */
+async function checkChoice(t, choice) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(choice.provider))
+        fail(400, "Invalid provider id", { code: "invalid_request" });
+    const row = await hostCredentialRowFor(t, choice.provider);
+    if (!row)
+        fail(422, `Model provider ${choice.provider} is not connected: connect it in Model Settings first`, {
+            code: "request_rejected",
+        });
+    // 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;
+    const listed = hostModelCatalog().providers.find((provider) => provider.id === choice.provider);
+    if (listed && listed.models.length > 0 && !catalogModel(choice.provider, choice.model))
+        fail(422, `Unknown model ${choice.model} for provider ${choice.provider}`, { code: "request_rejected" });
+}

package/dist/vault/host-identity.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The Host's identity for model calls (ADR-71): a model credential of type `host_identity` holds
+ * no secret, only the Google Cloud project and location. The model gate calls Agent Platform with
+ * the Host's Google Application Default Credentials, which Google's client library finds at each
+ * call (`GOOGLE_APPLICATION_CREDENTIALS`, gcloud's file, or the metadata server on Google Cloud).
+ * Nothing of them is stored, logged or passed to a sandbox.
+ *
+ * Off unless the Host's operator lends it, per provider, with `NYLORUN_MODEL_HOST_IDENTITY` on the
+ * process that runs the gates. Every Tenant on the Host may then use it, so a Host that serves
+ * several organizations must not set it.
+ */
+/** The providers that can use the Host's identity. */
+export declare const HOST_IDENTITY_PROVIDERS: readonly ["google-vertex"];
+/**
+ * What pi-ai's Vertex AI client takes in place of an API key to use Application Default
+ * Credentials, with the project and location in the call's `env`.
+ */
+export declare const VERTEX_ADC_MARKER = "gcp-vertex-credentials";
+/** Sets the providers this process lends the Host's identity to (at startup). */
+export declare function useHostIdentity(providers: readonly string[]): void;
+/** Why a model of `provider` may not use the Host's identity here, or undefined when it may. */
+export declare function hostIdentityRefused(provider: string): string | undefined;
+/** The call's `env` for a `host_identity` credential: where Agent Platform runs it. */
+export declare function hostIdentityEnv(project: string, location: string): Record<string, string>;

package/dist/vault/host-identity.js

@@ -0,0 +1,35 @@
+/**
+ * The Host's identity for model calls (ADR-71): a model credential of type `host_identity` holds
+ * no secret, only the Google Cloud project and location. The model gate calls Agent Platform with
+ * the Host's Google Application Default Credentials, which Google's client library finds at each
+ * call (`GOOGLE_APPLICATION_CREDENTIALS`, gcloud's file, or the metadata server on Google Cloud).
+ * Nothing of them is stored, logged or passed to a sandbox.
+ *
+ * Off unless the Host's operator lends it, per provider, with `NYLORUN_MODEL_HOST_IDENTITY` on the
+ * process that runs the gates. Every Tenant on the Host may then use it, so a Host that serves
+ * several organizations must not set it.
+ */
+/** The providers that can use the Host's identity. */
+export const HOST_IDENTITY_PROVIDERS = ["google-vertex"];
+/**
+ * What pi-ai's Vertex AI client takes in place of an API key to use Application Default
+ * Credentials, with the project and location in the call's `env`.
+ */
+export const VERTEX_ADC_MARKER = "gcp-vertex-credentials";
+let lent = [];
+/** Sets the providers this process lends the Host's identity to (at startup). */
+export function useHostIdentity(providers) {
+    lent = [...providers];
+}
+/** Why a model of `provider` may not use the Host's identity here, or undefined when it may. */
+export function hostIdentityRefused(provider) {
+    if (!HOST_IDENTITY_PROVIDERS.includes(provider))
+        return `The Host's identity authenticates ${HOST_IDENTITY_PROVIDERS.join(", ")} only, not ${provider}.`;
+    if (!lent.includes(provider))
+        return `This Host doesn't lend its identity to ${provider}: its operator sets NYLORUN_MODEL_HOST_IDENTITY=${provider}.`;
+    return undefined;
+}
+/** The call's `env` for a `host_identity` credential: where Agent Platform runs it. */
+export function hostIdentityEnv(project, location) {
+    return { GOOGLE_CLOUD_PROJECT: project, GOOGLE_CLOUD_LOCATION: location };
+}

package/dist/vault/host-model.d.ts

@@ -18,11 +18,15 @@ export declare class HostModelVault {
     private readonly kek;
     constructor(options: HostModelVaultOptions);
     /**
-     * Reads the active host model secret, with the inputs the operator added to catalog models
-     * (protocol 12). Decrypts after the read commits.
+     * Reads the host model secret a call uses, with the inputs the operator added to catalog
+     * models (protocol 12): the session's own model while its provider is connected (Host feature
+     * `session-model`), else the Tenant's active one. Decrypts after the read commits.
+     */
+    readHostModel(sessionId?: string): Promise<HostModelSecret | undefined>;
+    /**
+     * Replaces a host model's secret, keeping its binding: `provider`'s, the one the refreshed
+     * credential was read for, else the active one's.
      */
-    readHostModel(): Promise<HostModelSecret | undefined>;
-    /** Replaces the active host model's secret, keeping its binding. */
     updateHostCredential(credential: {
         type: "api_key" | "oauth";
         key?: string;
@@ -30,5 +34,5 @@ export declare class HostModelVault {
         refresh?: string;
         access?: string;
         expires?: number;
-    }): Promise<void>;
+    }, provider?: string): Promise<void>;
 }

package/dist/vault/host-model.js

@@ -1,7 +1,7 @@
 import { readAddedInputs } from "../tenant/model-setting.js";
 import { encryptSecret } from "./crypto.js";
 import { VaultError } from "./error.js";
-import { activeHostCredentialRow, HOST_VAULT_ID, hostModelAad, modelBinding, readHostPayload, } from "./service.js";
+import { activeHostCredentialRow, hostCredentialRowFor, hostCredentialRowOf, HOST_VAULT_ID, hostModelAad, modelBinding, readHostPayload, } from "./service.js";
 export class HostModelVault {
     store;
     kek;
@@ -10,28 +10,36 @@ export class HostModelVault {
         this.kek = options.kek;
     }
     /**
-     * Reads the active host model secret, with the inputs the operator added to catalog models
-     * (protocol 12). Decrypts after the read commits.
+     * Reads the host model secret a call uses, with the inputs the operator added to catalog
+     * models (protocol 12): the session's own model while its provider is connected (Host feature
+     * `session-model`), else the Tenant's active one. Decrypts after the read commits.
      */
-    async readHostModel() {
-        const { row, addedInputs } = await this.store.tx(async (t) => ({
-            row: await activeHostCredentialRow(t),
-            addedInputs: await readAddedInputs(t),
-        }));
-        if (!row)
+    async readHostModel(sessionId) {
+        const { found, addedInputs } = await this.store.tx(async (t) => {
+            const session = sessionId === undefined ? undefined : await t.get("sessions", sessionId);
+            return {
+                found: await hostCredentialRowOf(t, session?.model),
+                addedInputs: await readAddedInputs(t),
+            };
+        });
+        if (!found)
             return undefined;
-        const binding = modelBinding(row);
-        const payload = readHostPayload(this.kek(), row, binding);
+        const { row, binding } = found;
+        // The row's own binding seals its secret; a session's model only changes what is called.
+        const payload = readHostPayload(this.kek(), row, modelBinding(row));
         const credential = binding.authType === "oauth"
             ? { type: "oauth", ...payload.oauth }
             : binding.authType === "workload"
                 ? // The workload token is read from its file at each call (#496), never stored.
                     { type: "workload" }
-                : {
-                    type: "api_key",
-                    key: payload.apiKey,
-                    ...(payload.env ? { env: payload.env } : {}),
-                };
+                : binding.authType === "host_identity"
+                    ? // The Host's identity is found at each call (ADR-71): only where the calls go is kept.
+                        { type: "host_identity", ...(payload.env ? { env: payload.env } : {}) }
+                    : {
+                        type: "api_key",
+                        key: payload.apiKey,
+                        ...(payload.env ? { env: payload.env } : {}),
+                    };
         return {
             provider: binding.provider,
             model: binding.model,
@@ -42,11 +50,14 @@ export class HostModelVault {
             credential,
         };
     }
-    /** Replaces the active host model's secret, keeping its binding. */
-    async updateHostCredential(credential) {
+    /**
+     * Replaces a host model's secret, keeping its binding: `provider`'s, the one the refreshed
+     * credential was read for, else the active one's.
+     */
+    async updateHostCredential(credential, provider) {
         const kek = this.kek();
         await this.store.tx(async (t) => {
-            const row = await activeHostCredentialRow(t);
+            const row = provider === undefined ? await activeHostCredentialRow(t) : await hostCredentialRowFor(t, provider);
             if (!row)
                 throw new VaultError(404, "Model provider is not configured");
             const binding = modelBinding(row);

package/dist/vault/service.d.ts

@@ -1,4 +1,4 @@
-import type { CredentialCoverage, CredentialCoverageRequest, CredentialIdentity, EnvironmentSecretSlot, AgentSecretView, HostModelAuthType, HostModelProviderInfo, HostModelView, PutAgentSecretRequest, PutHostModelRequest, CustomModelSettings, ModelInput, SelectHostModelRequest } from "@nylorun/core/contracts";
+import type { CredentialCoverage, CredentialCoverageRequest, CredentialIdentity, EnvironmentSecretSlot, AgentSecretView, HostModelAuthType, HostModelProviderInfo, HostModelView, SessionModelChoice, SessionModelView, PutAgentSecretRequest, PutHostModelRequest, CustomModelSettings, ModelInput, SelectHostModelRequest } from "@nylorun/core/contracts";
 import type { AgentManifest, WorkflowManifest } from "@nylorun/core/define";
 import type { SessionStore, Tx, VaultCredentialRow } from "../store/types.js";
 export declare const HOST_VAULT_ID = "host";
@@ -166,7 +166,13 @@ export declare class VaultService {
      * the credential of the Agent's vault bound to the URL. Reads no secret, writes no audit row.
      */
     coverage(manifest: AgentManifest | WorkflowManifest, request: CredentialCoverageRequest): Promise<CredentialCoverage>;
-    getHostModel(): Promise<HostModelView>;
+    /**
+     * The Tenant's model, or the model a session's turns use (`choice`, its own, while its provider
+     * is connected).
+     */
+    getHostModel(choice?: SessionModelChoice): Promise<HostModelView>;
+    /** The model a session's next turn uses, and where it comes from (Host feature `session-model`). */
+    getSessionModel(choice?: SessionModelChoice): Promise<SessionModelView>;
     listHostProviders(): Promise<{
         providers: HostModelProviderInfo[];
     }>;
@@ -194,6 +200,16 @@ export declare function hostModelRows(t: Tx): Promise<VaultCredentialRow[]>;
 export declare function hostCredentialRowFor(t: Tx, provider: string): Promise<VaultCredentialRow | undefined>;
 /** The provider the host model selection names, or the only (or legacy) one configured. */
 export declare function activeProviderId(t: Tx): Promise<string | undefined>;
+/**
+ * The host model credential row a session's calls use (ciphertext), in `t`, with the binding
+ * they call: its own model (`choice`) on its provider's row while that provider is connected,
+ * else the Tenant's active one. `row`'s own binding seals its secret (`readHostPayload`).
+ */
+export declare function hostCredentialRowOf(t: Tx, choice: SessionModelChoice | undefined): Promise<{
+    row: VaultCredentialRow;
+    binding: ModelBinding;
+    source: "session" | "tenant";
+} | undefined>;
 /** The active host model credential row (ciphertext), in `t`. */
 export declare function activeHostCredentialRow(t: Tx): Promise<VaultCredentialRow | undefined>;
 export declare function readHostPayload(kek: Buffer, row: VaultCredentialRow, binding: ModelBinding): HostSecretPayload;

package/dist/vault/service.js

@@ -39,7 +39,8 @@
  * coverage(manifest: AgentManifest | WorkflowManifest, request: CredentialCoverageRequest): Promise<CredentialCoverage>
  *
  * // Host model credential: each opens its own transaction.
- * getHostModel(): Promise<HostModelView>
+ * getHostModel(choice?: SessionModelChoice): Promise<HostModelView>
+ * getSessionModel(choice?: SessionModelChoice): Promise<SessionModelView>
  * listHostProviders(): Promise<{ providers: HostModelProviderInfo[] }>
  * putHostModel(body: PutHostModelRequest): Promise<HostModelView>
  * selectHostModel(body: SelectHostModelRequest): Promise<HostModelView>
@@ -88,6 +89,7 @@ import { hostModelCatalog, inputsOfHostModel } from "../model/catalog.js";
 import { inputsError } from "../model/capabilities.js";
 import { readAddedInputs } from "../tenant/model-setting.js";
 import { normalizeVaultUrl } from "./url.js";
+import { hostIdentityEnv, hostIdentityRefused } from "./host-identity.js";
 export const HOST_VAULT_ID = "host";
 const HOST_MODEL_ID = "host-model";
 export class VaultService {
@@ -510,8 +512,29 @@ export class VaultService {
         });
     }
     // --- host model ----------------------------------------------------------------
-    async getHostModel() {
-        return this.store.tx((t) => this.hostModelView(t));
+    /**
+     * The Tenant's model, or the model a session's turns use (`choice`, its own, while its provider
+     * is connected).
+     */
+    async getHostModel(choice) {
+        return this.store.tx((t) => this.hostModelView(t, choice));
+    }
+    /** The model a session's next turn uses, and where it comes from (Host feature `session-model`). */
+    async getSessionModel(choice) {
+        return this.store.tx(async (t) => {
+            const found = await hostCredentialRowOf(t, choice);
+            const kept = choice ? { choice } : {};
+            if (!found)
+                return { configured: false, ...kept };
+            return {
+                configured: true,
+                source: found.source,
+                provider: found.binding.provider,
+                model: found.binding.model,
+                ...(found.binding.baseUrl ? { baseUrl: found.binding.baseUrl } : {}),
+                ...kept,
+            };
+        });
     }
     async listHostProviders() {
         return this.store.tx(async (t) => {
@@ -546,10 +569,16 @@ export class VaultService {
             this.validateHostModel(body);
             if (body.auth.type === "workload" && body.provider !== "custom")
                 throw new VaultError(400, "The workload token authenticates a custom provider only.");
+            if (body.auth.type === "host_identity") {
+                const refused = hostIdentityRefused(body.provider);
+                if (refused)
+                    throw new VaultError(400, refused);
+            }
             await this.ensureHostVault(t);
             const credentialId = hostModelCredentialId(body.provider);
             await this.deleteHostProviderRows(t, body.provider);
-            // The workload token is read on every call and never stored (#496).
+            // The workload token is read on every call and never stored (#496); the Host's identity
+            // too (ADR-71), which keeps only where its calls go.
             const payload = body.auth.type === "api_key"
                 ? {
                     apiKey: body.auth.key,
@@ -557,7 +586,9 @@ export class VaultService {
                 }
                 : body.auth.type === "oauth"
                     ? { oauth: body.auth }
-                    : {};
+                    : body.auth.type === "host_identity"
+                        ? { env: hostIdentityEnv(body.auth.project, body.auth.location) }
+                        : {};
             await this.insertHostCredential(t, kek, {
                 id: credentialId,
                 provider: body.provider,
@@ -714,11 +745,11 @@ export class VaultService {
             ...sealed,
         });
     }
-    async hostModelView(t) {
-        const row = await activeHostCredentialRow(t);
-        if (!row)
+    async hostModelView(t, choice) {
+        const found = await hostCredentialRowOf(t, choice);
+        if (!found)
             return { configured: false };
-        const binding = modelBinding(row);
+        const { binding } = found;
         return {
             configured: true,
             provider: binding.provider,
@@ -904,6 +935,18 @@ export async function activeProviderId(t) {
         return modelBinding(legacy).provider;
     return modelBinding(rows[0]).provider;
 }
+/**
+ * The host model credential row a session's calls use (ciphertext), in `t`, with the binding
+ * they call: its own model (`choice`) on its provider's row while that provider is connected,
+ * else the Tenant's active one. `row`'s own binding seals its secret (`readHostPayload`).
+ */
+export async function hostCredentialRowOf(t, choice) {
+    const chosen = choice && (await hostCredentialRowFor(t, choice.provider));
+    if (chosen)
+        return { row: chosen, binding: { ...modelBinding(chosen), model: choice.model }, source: "session" };
+    const row = await activeHostCredentialRow(t);
+    return row && { row, binding: modelBinding(row), source: "tenant" };
+}
 /** The active host model credential row (ciphertext), in `t`. */
 export async function activeHostCredentialRow(t) {
     const active = await activeProviderId(t);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const RUNTIME_VERSION = "0.31.0-beta";
+export declare const RUNTIME_VERSION = "0.33.0-beta";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in step with package.json by runtime/server/scripts/check-package.mjs, which runs in npm run check.
 // release:prepare also rewrites this when it bumps @nylorun/runtime.
-export const RUNTIME_VERSION = "0.31.0-beta";
+export const RUNTIME_VERSION = "0.33.0-beta";