@nylorun/runtime 0.32.0-beta → 0.33.0-beta

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.2.0",
   "info": {
     "title": "Nylorun Runtime API",
-    "version": "0.32.0-beta",
+    "version": "0.33.0-beta",
     "x-nylorun-protocol": {
       "min": 16,
       "max": 18,
@@ -34,7 +34,9 @@
         "traces",
         "artifact-reads",
         "gateway-credentials",
-        "agent-folders"
+        "agent-folders",
+        "session-model",
+        "model-host-identity"
       ]
     },
     "description": "For developers: agent manifests, Agents, sessions (with AG-UI and A2A) and artifacts, through `@nylorun/agents`. Every Tenant serves it on its one URL, beside the Management API (`/openapi/management.json`). Every request sends `Nylorun-Protocol`. Who may call each operation is its `security` and its `x-nylorun-credentials` and `x-nylorun-scopes` (the subject scopes that reach it) fields: an application key (servers) or a trusted issuer's token (browsers and apps)."
@@ -8867,6 +8869,113 @@
         ],
         "additionalProperties": false
       },
+      "SessionModelView": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "configured": {
+                "type": "boolean",
+                "enum": [
+                  false
+                ]
+              },
+              "choice": {
+                "type": "object",
+                "properties": {
+                  "provider": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "model": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "provider",
+                  "model"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "configured"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "configured": {
+                "type": "boolean",
+                "enum": [
+                  true
+                ]
+              },
+              "source": {
+                "type": "string",
+                "enum": [
+                  "session",
+                  "tenant"
+                ]
+              },
+              "provider": {
+                "type": "string"
+              },
+              "model": {
+                "type": "string"
+              },
+              "baseUrl": {
+                "type": "string"
+              },
+              "choice": {
+                "type": "object",
+                "properties": {
+                  "provider": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "model": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "provider",
+                  "model"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "configured",
+              "source",
+              "provider",
+              "model"
+            ],
+            "additionalProperties": false
+          }
+        ]
+      },
+      "PutSessionModelRequest": {
+        "type": "object",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "minLength": 1
+          },
+          "model": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "provider",
+          "model"
+        ],
+        "additionalProperties": false
+      },
       "SessionItemsResponse": {
         "type": "object",
         "properties": {
@@ -32816,6 +32925,410 @@
         }
       }
     },
+    "/v1/sessions/{sessionId}/model": {
+      "get": {
+        "tags": [
+          "Sessions API"
+        ],
+        "summary": "Get a session's model",
+        "description": "The model the session's next turn uses (feature `session-model`): its own (`source: \"session\"`) while its provider is connected, else the Tenant's (`source: \"tenant\"`). `choice` is the session's own model, kept while its provider is disconnected.",
+        "security": [
+          {
+            "applicationKey": []
+          },
+          {
+            "issuerToken": []
+          }
+        ],
+        "x-nylorun-credentials": [
+          "application",
+          "subject",
+          "token"
+        ],
+        "x-nylorun-scopes": [
+          "sessions:own"
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "sessionId",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "The protocol version, `18`"
+            },
+            "required": true,
+            "description": "The protocol version, `18`",
+            "name": "Nylorun-Protocol",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "The person an application key acts for"
+            },
+            "required": false,
+            "description": "The person an application key acts for",
+            "name": "Nylorun-Subject",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "The subject's space-separated scopes; required with a subject"
+            },
+            "required": false,
+            "description": "The subject's space-separated scopes; required with a subject",
+            "name": "Nylorun-Scopes",
+            "in": "header"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The session's model",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SessionModelView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid headers, path, body or cursor",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "No credential (`credential_required`), one the Tenant does not accept (`credential_invalid`), a token that expired (`token_expired`), or a token whose issuer's keys cannot be fetched now (`issuer_unavailable`). `WWW-Authenticate: Bearer` names the protected resource metadata (`resource_metadata`)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Not allowed for this credential or subject scope (`scope_required`; a token also gets `WWW-Authenticate: Bearer error=\"insufficient_scope\"` and the scope), a key of the other API (`key_role_mismatch`), or an application key from a browser (`origin_rejected`)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found (`not_found`)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "426": {
+            "description": "`Nylorun-Protocol` missing or unsupported",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProtocolRejected"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "The Tenant's storage or streams are unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "tags": [
+          "Sessions API"
+        ],
+        "summary": "Choose a session's model",
+        "description": "Chooses one of a connected provider's models for the session's turns (feature `session-model`), in place of the Tenant's model. The Tenant's model and every other session's stay as they are. Only the application sets it, for itself or for a subject: a trusted issuer's token is refused. A turn calls one model, so the choice changes only while no turn runs or waits (`409 session_busy`). A provider that is not connected, or a model its catalog does not list, is `422 request_rejected`.",
+        "security": [
+          {
+            "applicationKey": []
+          }
+        ],
+        "x-nylorun-credentials": [
+          "application",
+          "subject"
+        ],
+        "x-nylorun-scopes": [
+          "sessions:own"
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "sessionId",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "The protocol version, `18`"
+            },
+            "required": true,
+            "description": "The protocol version, `18`",
+            "name": "Nylorun-Protocol",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "The person an application key acts for"
+            },
+            "required": false,
+            "description": "The person an application key acts for",
+            "name": "Nylorun-Subject",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "The subject's space-separated scopes; required with a subject"
+            },
+            "required": false,
+            "description": "The subject's space-separated scopes; required with a subject",
+            "name": "Nylorun-Scopes",
+            "in": "header"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutSessionModelRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The session's model",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SessionModelView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid headers, path, body or cursor",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "No credential (`credential_required`), or one the Tenant does not accept (`credential_invalid`), with a `WWW-Authenticate: Bearer` challenge",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "A trusted issuer's token (`scope_required`)"
+          },
+          "404": {
+            "description": "Not found (`not_found`)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "A turn is running or waits (`session_busy`)"
+          },
+          "422": {
+            "description": "The provider is not connected, or the model is not one of its models"
+          },
+          "426": {
+            "description": "`Nylorun-Protocol` missing or unsupported",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProtocolRejected"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "The Tenant's storage or streams are unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Sessions API"
+        ],
+        "summary": "Clear a session's model",
+        "description": "Clears the session's own model (feature `session-model`): its next turns use the Tenant's model. Refused while a turn runs or waits (`409 session_busy`).",
+        "security": [
+          {
+            "applicationKey": []
+          }
+        ],
+        "x-nylorun-credentials": [
+          "application",
+          "subject"
+        ],
+        "x-nylorun-scopes": [
+          "sessions:own"
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "sessionId",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "The protocol version, `18`"
+            },
+            "required": true,
+            "description": "The protocol version, `18`",
+            "name": "Nylorun-Protocol",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "The person an application key acts for"
+            },
+            "required": false,
+            "description": "The person an application key acts for",
+            "name": "Nylorun-Subject",
+            "in": "header"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "The subject's space-separated scopes; required with a subject"
+            },
+            "required": false,
+            "description": "The subject's space-separated scopes; required with a subject",
+            "name": "Nylorun-Scopes",
+            "in": "header"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The session's model",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SessionModelView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid headers, path, body or cursor",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "No credential (`credential_required`), or one the Tenant does not accept (`credential_invalid`), with a `WWW-Authenticate: Bearer` challenge",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "A trusted issuer's token (`scope_required`)"
+          },
+          "404": {
+            "description": "Not found (`not_found`)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "A turn is running or waits (`session_busy`)"
+          },
+          "426": {
+            "description": "`Nylorun-Protocol` missing or unsupported",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProtocolRejected"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "The Tenant's storage or streams are unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Rejected"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/sessions/{sessionId}/usage": {
       "get": {
         "tags": [

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>;