@nylorun/runtime 0.23.0-beta → 0.25.0-beta

package/dist/tenant/harness-tokens.d.ts

@@ -0,0 +1,21 @@
+import type { SessionStore } from "../store/types.js";
+export declare const HARNESS_TOKENS_SETTING = "harness.tokens";
+export interface HarnessTokenInfo {
+    readonly id: string;
+    readonly createdAt: string;
+}
+export type HarnessTokenRefusal = {
+    readonly reason: "invalid_id";
+    readonly message: string;
+};
+/** The harness id `token` is for, or undefined when it is none of the Tenant's harness tokens. */
+export declare function harnessOfToken(store: SessionStore, token: string): Promise<string | undefined>;
+/** Creates or rotates harness `id`'s token; the token is returned this once. */
+export declare function putHarnessToken(store: SessionStore, id: string): Promise<{
+    id: string;
+    token: string;
+    rotated: boolean;
+} | HarnessTokenRefusal>;
+export declare function listHarnessTokens(store: SessionStore): Promise<HarnessTokenInfo[]>;
+/** Deletes harness `id`'s token; whether there was one. */
+export declare function deleteHarnessToken(store: SessionStore, id: string): Promise<boolean>;

package/dist/tenant/harness-tokens.js

@@ -0,0 +1,61 @@
+/**
+ * Per-harness tokens (R4.1): the credential a custom harness's container connects to the Harness
+ * API listener with. Each is bound to one harness id, so a harness can only say that id in
+ * `hello` and only take the sessions pinned to it. Our harness keeps the installation's
+ * `NYLORUN_HARNESS_TOKEN`, bound to `nylorun`; a pod's harness holds neither (it joins).
+ *
+ * The Tenant setting `harness.tokens` keeps each token's sha256 and when it was made, never the
+ * token: `nylorun-operate harness token put <id>` prints it once. Putting an id again rotates its
+ * token; the old one stops working at its next connection.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { DEFAULT_HARNESS, isHarnessId } from "@nylorun/core/contracts";
+export const HARNESS_TOKENS_SETTING = "harness.tokens";
+const sha256 = (token) => createHash("sha256").update(token).digest("hex");
+async function read(store) {
+    const raw = await store.tx((t) => t.getSetting(HARNESS_TOKENS_SETTING));
+    return raw === undefined ? {} : JSON.parse(raw);
+}
+/** The harness id `token` is for, or undefined when it is none of the Tenant's harness tokens. */
+export async function harnessOfToken(store, token) {
+    const hash = Buffer.from(sha256(token), "hex");
+    for (const [id, stored] of Object.entries(await read(store))) {
+        const candidate = Buffer.from(stored.sha256, "hex");
+        if (candidate.length === hash.length && timingSafeEqual(candidate, hash))
+            return id;
+    }
+    return undefined;
+}
+/** Creates or rotates harness `id`'s token; the token is returned this once. */
+export async function putHarnessToken(store, id) {
+    if (!isHarnessId(id))
+        return { reason: "invalid_id", message: `${id} is not a harness id: lowercase letters, digits and dashes, starting with a letter` };
+    if (id === DEFAULT_HARNESS)
+        return { reason: "invalid_id", message: `${DEFAULT_HARNESS} is our harness: it connects with NYLORUN_HARNESS_TOKEN` };
+    const token = randomBytes(32).toString("hex");
+    return store.tx(async (t) => {
+        const raw = await t.getSetting(HARNESS_TOKENS_SETTING);
+        const tokens = raw === undefined ? {} : JSON.parse(raw);
+        const rotated = id in tokens;
+        tokens[id] = { sha256: sha256(token), createdAt: new Date().toISOString() };
+        await t.putSetting(HARNESS_TOKENS_SETTING, JSON.stringify(tokens));
+        return { id, token, rotated };
+    });
+}
+export async function listHarnessTokens(store) {
+    return Object.entries(await read(store))
+        .map(([id, stored]) => ({ id, createdAt: stored.createdAt }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Deletes harness `id`'s token; whether there was one. */
+export async function deleteHarnessToken(store, id) {
+    return store.tx(async (t) => {
+        const raw = await t.getSetting(HARNESS_TOKENS_SETTING);
+        const tokens = raw === undefined ? {} : JSON.parse(raw);
+        if (!(id in tokens))
+            return false;
+        delete tokens[id];
+        await t.putSetting(HARNESS_TOKENS_SETTING, JSON.stringify(tokens));
+        return true;
+    });
+}

package/dist/tenant/host-token.d.ts

@@ -85,7 +85,7 @@ declare const KINDS: {
 export declare function verifyHostToken(store: SessionStore, tenantId: string, raw: string, kind: keyof typeof KINDS, cache?: HostTokenKeyCache): Promise<HostTokenVerdict>;
 /**
  * Why a host's claims are stale, or undefined while they are its sandbox's current host: the
- * sandbox exists as a pod sandbox, is not deleted, lost or expired, and its epoch and pod are
+ * sandbox exists as a pod Environment, is not deleted or lost, and its epoch and pod are
  * the token's. One indexed read of the sandbox's row.
  */
 export declare function staleHost(store: SessionStore, claims: HostClaims): Promise<string | undefined>;

package/dist/tenant/host-token.js

@@ -157,11 +157,11 @@ export async function verifyHostToken(store, tenantId, raw, kind, cache = new Ma
 }
 /**
  * Why a host's claims are stale, or undefined while they are its sandbox's current host: the
- * sandbox exists as a pod sandbox, is not deleted, lost or expired, and its epoch and pod are
+ * sandbox exists as a pod Environment, is not deleted or lost, and its epoch and pod are
  * the token's. One indexed read of the sandbox's row.
  */
 export async function staleHost(store, claims) {
-    const row = await store.tx((t) => t.sandboxResource(claims.sandboxId));
+    const row = await store.tx((t) => t.environment(claims.sandboxId));
     const pod = row?.pod;
     if (!row || row.kind !== "pod" || !pod)
         return "the sandbox is gone";
@@ -169,8 +169,6 @@ export async function staleHost(store, claims) {
         return "the sandbox was deleted";
     if (pod.observed === "lost")
         return "the sandbox was lost";
-    if (pod.observed === "expired")
-        return "the sandbox expired";
     if (pod.hostEpoch !== claims.epoch)
         return "another host holds the sandbox now";
     if (pod.podUid !== claims.podUid)

package/dist/tenant/identity-file.d.ts

@@ -15,9 +15,9 @@
  *     # Optional, with their defaults:
  *     subject: "{sub}"                           # scalar claims only
  *     scopes: { claim: scope }                   # or { fixed: [sessions:own, agents:read] }
- *     allowedScopes: [agents:read, sessions:own, sandboxes:write]   # add studio to grant it
+ *     allowedScopes: [agents:read, sessions:own, environments:write]   # add studio to grant it
  *     agents: [support]                          # absent reaches every agent
- *     sandboxes: ["{org_id}/*"]                  # absent reaches no sandbox
+ *     environments: ["{org_id}/*"]               # absent reaches no Environment
  * ```
  */
 import { type KeyObject } from "node:crypto";
@@ -55,8 +55,8 @@ export interface TrustedIssuerConfig {
     readonly allowedScopes: readonly IssuerScope[];
     /** The agents its tokens reach; absent reaches all. */
     readonly agents?: readonly string[];
-    /** Sandbox grant templates, such as `{org_id}/*`; absent reaches no sandbox. */
-    readonly sandboxes?: readonly string[];
+    /** Environment grant templates, such as `{org_id}/*`; absent reaches no Environment. */
+    readonly environments?: readonly string[];
 }
 /** A malformed identity file: the message names the issuer and the field. */
 export declare class IdentityFileError extends Error {

package/dist/tenant/identity-file.js

@@ -15,15 +15,15 @@
  *     # Optional, with their defaults:
  *     subject: "{sub}"                           # scalar claims only
  *     scopes: { claim: scope }                   # or { fixed: [sessions:own, agents:read] }
- *     allowedScopes: [agents:read, sessions:own, sandboxes:write]   # add studio to grant it
+ *     allowedScopes: [agents:read, sessions:own, environments:write]   # add studio to grant it
  *     agents: [support]                          # absent reaches every agent
- *     sandboxes: ["{org_id}/*"]                  # absent reaches no sandbox
+ *     environments: ["{org_id}/*"]               # absent reaches no Environment
  * ```
  */
 import { createPublicKey } from "node:crypto";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
-import { ISSUER_SCOPES, isSandboxGrant, TOKEN_SANDBOX_GRANTS_MAX, TOKEN_SCOPES, } from "@nylorun/core/contracts";
+import { ISSUER_SCOPES, isEnvironmentGrant, TOKEN_ENVIRONMENT_GRANTS_MAX, TOKEN_SCOPES, } from "@nylorun/core/contracts";
 /** The JWT algorithms an issuer may sign with. */
 export const ISSUER_ALGORITHMS = ["RS256", "ES256", "EdDSA"];
 /** An entry's defaults: the `sub` claim, the RFC 9068 `scope` claim, every token scope but `studio`. */
@@ -119,11 +119,11 @@ const IssuerEntrySchema = z
         .default(DEFAULT_SCOPES),
     allowedScopes: z.array(IssuerScopeSchema).min(1).default([...DEFAULT_ALLOWED_SCOPES]),
     agents: z.array(z.string().min(1)).optional(),
-    sandboxes: z
-        .array(template("a sandbox grant").refine(
+    environments: z
+        .array(template("an Environment grant").refine(
     // A rendered grant must be a grant: checked here with a sample value per claim.
-    (value) => isSandboxGrant(renderTemplate(value, () => "x")), "must render to a sandbox id or a prefix ending in /*, as {org_id}/*"))
-        .max(TOKEN_SANDBOX_GRANTS_MAX)
+    (value) => isEnvironmentGrant(renderTemplate(value, () => "x")), "must render to an Environment id or a prefix ending in /*, as {org_id}/*"))
+        .max(TOKEN_ENVIRONMENT_GRANTS_MAX)
         .optional(),
 });
 const IdentityFileSchema = z.object({ issuers: z.array(z.unknown()) });
@@ -173,6 +173,15 @@ export function parseIdentityFile(text, source = "identity file", options = {})
             ? entry.name
             : `#${index + 1}`;
         const where = `issuer ${named}`;
+        // Protocol 11 renamed these (R2d Q11): refused, never read as no grants.
+        if (entry && typeof entry === "object" && "sandboxes" in entry)
+            return fail(`${where}: sandboxes: renamed environments in protocol 11`);
+        const scopesNamed = JSON.stringify([
+            entry?.allowedScopes,
+            entry?.scopes,
+        ]);
+        if (scopesNamed.includes('"sandboxes:write"'))
+            return fail(`${where}: sandboxes:write: renamed environments:write in protocol 11`);
         const parsed = IssuerEntrySchema.safeParse(entry);
         if (!parsed.success)
             return fail(`${where}: ${issueText(parsed.error.issues)}`);
@@ -207,7 +216,7 @@ export function parseIdentityFile(text, source = "identity file", options = {})
             scopes: value.scopes,
             allowedScopes: [...new Set(value.allowedScopes)],
             ...(value.agents ? { agents: [...new Set(value.agents)] } : {}),
-            ...(value.sandboxes ? { sandboxes: value.sandboxes } : {}),
+            ...(value.environments ? { environments: value.environments } : {}),
         });
     });
     return issuers;

package/dist/tenant/issuers.js

@@ -37,7 +37,7 @@ const JWKS_MAX_BYTES = 256 * 1024;
 const JWKS_MAX_KEYS = 64;
 const DEFAULT_REFETCH_MS = 60_000;
 const DEFAULT_MAX_AGE_MS = 10 * 60_000;
-/** A grant's claim value: one sandbox id segment, so a claim never widens the template. */
+/** A grant's claim value: one Environment id segment, so a claim never widens the template. */
 const GRANT_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 /** The issuer's public keys: static, or its JWKS's as last fetched. */
 class IssuerKeys {
@@ -292,7 +292,7 @@ export async function verifyIssuerToken(ctx, issuer, raw, resourceMetadata) {
     const subject = renderTemplate(config.subject, (claim) => scalarClaim(payload, claim));
     if (subject === undefined || !isSubject(subject) || RESERVED.has(subject))
         return rejected("issuer_token_subject");
-    const sandboxes = config.sandboxes?.flatMap((grant) => {
+    const environments = config.environments?.flatMap((grant) => {
         const rendered = renderTemplate(grant, (claim) => {
             const value = scalarClaim(payload, claim);
             return value !== undefined && GRANT_SEGMENT.test(value) ? value : undefined;
@@ -309,7 +309,7 @@ export async function verifyIssuerToken(ctx, issuer, raw, resourceMetadata) {
         subject,
         scopes: scopesOf(config, payload),
         agents: config.agents ? new Set(config.agents) : "*",
-        sandboxes: [...new Set(sandboxes ?? [])],
+        environments: [...new Set(environments ?? [])],
         expiresAt: payload.exp * 1000,
         tokenId: jti,
         ...(verdict.kid !== undefined ? { keyId: verdict.kid } : {}),

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

@@ -1,4 +1,7 @@
 /**
+ * The Tenant's model settings: the fixture model, and the inputs the operator added to catalog
+ * models (`model.inputs`, below).
+ *
  * The Tenant-level fixture model: Tenant setting `model.fixture`, seeded with
  * `fixtureModel: true` (`PUT /v1/tenant/config/seed`, Host feature `tenant-fixture-model`).
  * A Tenant with it answers every model call with the Runtime's deterministic fixture model
@@ -8,9 +11,20 @@
  * The setting is read once per advance, in a transaction the advance makes anyway, so a Tenant
  * seeded on another node takes it at its next advance.
  */
+import { type ModelInput } from "@nylorun/core/contracts";
 import type { Tx } from "../store/types.js";
 export declare const FIXTURE_MODEL_SETTING = "model.fixture";
 /** Whether the Tenant uses the fixture model. */
 export declare function usesFixtureModel(t: Tx): Promise<boolean>;
 /** Seeds the setting if absent. Returns whether it was inserted. */
 export declare function seedFixtureModel(t: Tx): Promise<boolean>;
+/**
+ * The inputs the operator added to catalog models (protocol 12, `PUT /v1/tenant/models/inputs`):
+ * Tenant setting `model.inputs`, JSON `{ "<provider>/<model>": ModelInput[] }`. A custom
+ * endpoint keeps its own in its `settings.inputs` instead.
+ */
+export declare const MODEL_INPUTS_SETTING = "model.inputs";
+/** The added inputs by `<provider>/<model>`. Bad JSON, keys and inputs are left out: never throws. */
+export declare function readAddedInputs(t: Pick<Tx, "getSetting">): Promise<Record<string, ModelInput[]>>;
+/** Sets the inputs added to `<provider>/<model>`; an empty list removes its entry. */
+export declare function writeAddedInputs(t: Pick<Tx, "getSetting" | "putSetting">, key: string, inputs: readonly ModelInput[]): Promise<void>;

package/dist/tenant/model-setting.js

@@ -1,3 +1,17 @@
+/**
+ * The Tenant's model settings: the fixture model, and the inputs the operator added to catalog
+ * models (`model.inputs`, below).
+ *
+ * The Tenant-level fixture model: Tenant setting `model.fixture`, seeded with
+ * `fixtureModel: true` (`PUT /v1/tenant/config/seed`, Host feature `tenant-fixture-model`).
+ * A Tenant with it answers every model call with the Runtime's deterministic fixture model
+ * (`core/provider.ts` `toolFixtureModel`) instead of its configured model. Smoke checks seed
+ * it (scripts/lib/stack-tenant.mjs).
+ *
+ * The setting is read once per advance, in a transaction the advance makes anyway, so a Tenant
+ * seeded on another node takes it at its next advance.
+ */
+import { ModelInputSchema } from "@nylorun/core/contracts";
 export const FIXTURE_MODEL_SETTING = "model.fixture";
 /** Whether the Tenant uses the fixture model. */
 export async function usesFixtureModel(t) {
@@ -10,3 +24,40 @@ export async function seedFixtureModel(t) {
     await t.putSetting(FIXTURE_MODEL_SETTING, "true");
     return true;
 }
+/**
+ * The inputs the operator added to catalog models (protocol 12, `PUT /v1/tenant/models/inputs`):
+ * Tenant setting `model.inputs`, JSON `{ "<provider>/<model>": ModelInput[] }`. A custom
+ * endpoint keeps its own in its `settings.inputs` instead.
+ */
+export const MODEL_INPUTS_SETTING = "model.inputs";
+/** The added inputs by `<provider>/<model>`. Bad JSON, keys and inputs are left out: never throws. */
+export async function readAddedInputs(t) {
+    const raw = await t.getSetting(MODEL_INPUTS_SETTING);
+    if (raw === undefined)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    const added = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!key.includes("/") || !Array.isArray(value))
+            continue;
+        added[key] = value.filter((input) => ModelInputSchema.safeParse(input).success);
+    }
+    return added;
+}
+/** Sets the inputs added to `<provider>/<model>`; an empty list removes its entry. */
+export async function writeAddedInputs(t, key, inputs) {
+    const added = await readAddedInputs(t);
+    if (inputs.length === 0)
+        delete added[key];
+    else
+        added[key] = [...inputs];
+    await t.putSetting(MODEL_INPUTS_SETTING, JSON.stringify(added));
+}

package/dist/tenant/principals.js

@@ -6,7 +6,7 @@
  * `nylorun-operate keys`, `operator-keys.ts`); no other key is derived.
  *
  * The derivation is the one `@nylorun/admin` computes on the client side
- * (`admin/src/derived-credentials.ts`: `deriveStudioToken`); both sides must stay byte for byte
+ * (`sdks/admin/src/derived-credentials.ts`: `deriveStudioToken`); both sides must stay byte for byte
  * the same.
  */
 import { createHmac } from "node:crypto";

package/dist/tenant/reset.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
-import { detachAllSessions } from "./sandboxes.js";
+import { detachAllSessions } from "./environments.js";
 import { contentKey } from "../artifacts/folders.js";
 /**
  * Rename `dir` to a sibling, delete the sibling, recreate an empty `dir`.
@@ -38,14 +38,14 @@ function replaceDirectory(dir) {
  */
 export async function resetTenant(ctx, scope) {
     const clearSessions = scope === "sessions" || scope === "all";
-    const clearSandboxes = scope === "sandboxes" || scope === "all";
+    const clearSandboxes = scope === "environments" || scope === "all";
     const clearAll = scope === "all";
     if (clearSandboxes) {
         await ctx.sandbox.removeAll();
     }
     // The artifacts the reset deletes: their rows go in its transaction, their bytes after it.
     const blobKeys = await ctx.store.tx(async (t) => {
-        // Sandbox resources outlive their sessions: a sessions reset only detaches them.
+        // Environments outlive their sessions: a sessions reset only detaches them.
         if (clearSessions && !clearSandboxes)
             await detachAllSessions(t);
         const scoped = clearAll ? "all" : "sessions";

package/dist/tenant/runtime.d.ts

@@ -14,6 +14,7 @@ import type { HarnessChannel, MemoryPortsOptions } from "@nylorun/core/harness-a
 import { type HarnessPeer } from "../harness-api/server.js";
 import { type HostAuthority } from "../sandbox/join.js";
 import type { TenantPods } from "./context.js";
+import type { TraceOptions } from "../traces/options.js";
 /** TENANTS-CCR: test/injection hooks until TenantConfig gains them. */
 export type TenantOpenHooks = {
     modelProvider?: ModelProvider;
@@ -80,9 +81,11 @@ export type TenantOpenHooks = {
     harnessTap?: MemoryPortsOptions["tap"];
     /**
      * Sandbox pods (F7.2): the sandboxes service (`NYLORUN_SANDBOXES_URL`) and the Runtime image
-     * pods copy the engine from. Without it, kind `pod` is `sandbox_unavailable`.
+     * pods copy the engine from. Without it, kind `pod` is `environment_unavailable`.
      */
     pods?: TenantPods;
+    /** How the trace route makes spans (R7.5): the Host's `OTEL_*` resource and content opt-ins. */
+    traces?: TraceOptions;
 } & OpenedTenant;
 export declare class TenantRuntime implements TenantHandle {
     private readonly ctx;
@@ -97,6 +100,8 @@ export declare class TenantRuntime implements TenantHandle {
     private constructor();
     /** The Tenant's side of a sandbox pod's join (F7.2). */
     hostAuthority(): HostAuthority | undefined;
+    /** The custom harness a per-harness token is for (R4.1), or undefined. */
+    harnessOfToken(token: string): Promise<string | undefined>;
     static open(config: TenantConfig, hooks: TenantOpenHooks): Promise<TenantRuntime>;
     fetch(request: Request, node: NodeBindings): Promise<Response>;
     authorize(sessionId: string, request: {

package/dist/tenant/runtime.js

@@ -29,6 +29,7 @@ import { harnessStatusOf } from "./status.js";
 import { startInProcessHarness, startLoopbackHarness, } from "../harness-api/in-process.js";
 import { localWorkspace, remoteWorkspace, withPodWorkspaces, } from "../harness-api/workspace.js";
 import { hostAuthority } from "../sandbox/join.js";
+import { harnessOfToken } from "./harness-tokens.js";
 import { reconcileSandbox } from "../sandbox/pods/reconcile.js";
 import { sandboxWorkspaceReader } from "../artifacts/workspace.js";
 import { readDefinitionFile } from "./definition-files.js";
@@ -74,6 +75,10 @@ export class TenantRuntime {
     hostAuthority() {
         return this.ctx.closing || this.ctx.closed ? undefined : this.hosts;
     }
+    /** The custom harness a per-harness token is for (R4.1), or undefined. */
+    harnessOfToken(token) {
+        return harnessOfToken(this.ctx.store, token);
+    }
     static async open(config, hooks) {
         const envelope = hooks.envelope;
         const flowLimits = validateConfig(config);
@@ -193,7 +198,7 @@ export class TenantRuntime {
                     store: opened,
                     logger: config.logger,
                     preference,
-                    isPod: async (sandboxId) => (await opened.tx((t) => t.sandboxResource(sandboxId)))?.kind === "pod",
+                    isPod: async (sandboxId) => (await opened.tx((t) => t.environment(sandboxId)))?.kind === "pod",
                 })
                 : workspaces;
             const useVaultModel = config.model.kind === "vault";
@@ -256,6 +261,7 @@ export class TenantRuntime {
                 keys,
                 blobs,
                 workspaces: sandboxWorkspaceReader(sandbox),
+                ...(hooks.traces ? { traces: hooks.traces } : {}),
                 ...(hooks.runGrants ? { runGrants: hooks.runGrants } : {}),
                 workerId: hooks.workerId ?? WORKER_ID,
                 ownerLeaseMs: config.ownerLeaseMs ?? DEFAULT_OWNER_LEASE_MS,

package/dist/tenant/session.d.ts

@@ -1,16 +1,16 @@
 /**
- * Pure helpers over the session document: turn-manifest pins and variants, and state rebasing.
+ * Pure helpers over the session document: turn-manifest pins and variants. The engine's state
+ * is the harness's (R4.2): nothing here reads it.
  * No store access and no I/O. (The tools of an MCP snapshot
  * live in `mcp/snapshot.ts`.)
  *
  * Later waves: stable; the async store conversion (Wave 1 / A) does not change these.
  */
 import type { AgentManifest } from "@nylorun/core/define";
-import { type TurnManifestStore } from "../core/turn-manifest.js";
+import type { TurnManifestStore } from "../core/turn-manifest.js";
 import type { Session } from "./context.js";
 export { manifestFor, sessionToolsOf } from "../mcp/snapshot.js";
 /** Turn-manifest store backed by the session's `variants` map (no schema change). */
 export declare function variantStore(session: Session): TurnManifestStore;
 /** Manifest this turn's checkpoint is pinned to (session pin or a stored variant). */
 export declare function turnManifestOf(session: Session): AgentManifest;
-export declare function rebaseSessionState(session: Session, turnHash: string): void;

package/dist/tenant/session.js

@@ -1,4 +1,3 @@
-import { allowedManifestHashes, rebaseTurnState, } from "../core/turn-manifest.js";
 export { manifestFor, sessionToolsOf } from "../mcp/snapshot.js";
 /** Turn-manifest store backed by the session's `variants` map (no schema change). */
 export function variantStore(session) {
@@ -18,16 +17,3 @@ export function turnManifestOf(session) {
         return session.manifest;
     return session.variants?.[hash] ?? session.manifest;
 }
-export function rebaseSessionState(session, turnHash) {
-    const allowed = allowedManifestHashes({
-        pinnedHash: session.manifestHash,
-        variantHashes: Object.keys(session.variants ?? {}),
-    });
-    const next = rebaseTurnState({
-        state: session.state,
-        turnManifestHash: turnHash,
-        isAllowedHash: (hash) => allowed.has(hash),
-    });
-    if (next !== session.state)
-        session.state = next;
-}

package/dist/tenant/sessions.d.ts

@@ -1,7 +1,7 @@
 /**
- * Session and definition resources: `PUT/GET /v1/agents`, `PUT /v1/sessions/:id` (create or
- * re-attach vaults), the session list and the session view. Reads use the store's typed
- * queries; `PUT /v1/sessions/:id` runs in one transaction with the vault attachment checks.
+ * Session and definition resources: `PUT/GET /v1/agents`, `PUT /v1/sessions/:id` (create, or
+ * find an identical one), the session list and the session view. Reads use the store's typed
+ * queries; `PUT /v1/sessions/:id` runs in one transaction with the Environment's checks.
  */
 import { type PutAgentRequest, type PutSessionRequest } from "@nylorun/core/contracts";
 import type { Tx } from "../store/types.js";
@@ -25,10 +25,14 @@ export declare function listAgentsPublic(ctx: TenantContext, agents: ReadonlySet
         description?: any;
     }[];
 }>;
-export declare function putDefinition(ctx: TenantContext, agentId: string, body: PutAgentRequest): Promise<{
+export declare function putDefinition(ctx: TenantContext, agentId: string, body: PutAgentRequest, options?: {
+    /** Run every check and save nothing (`?dryRun=true`, protocol 14). */
+    dryRun?: boolean;
+}): Promise<{
     agentId: string;
     manifestHash: string;
     implementationVersion: string;
+    dryRun?: boolean | undefined;
 }>;
 /**
  * `access`, when the request acts for a person, limits the list to that person's sessions of
@@ -44,14 +48,14 @@ export declare function listSessions(ctx: TenantContext, agentId: string | null,
     }[];
 }>;
 /**
- * Create a session from its definition, or re-attach vaults to an identical one. `owner`, when
- * the request acts for a subject, must be the session's owner: another owner's session id is
- * the 404 of a missing one (not the 409 of a mismatch), and so are another owner's vaults and
- * sandboxes.
+ * Create a session from its definition, or find an identical one. `access`, when the request
+ * acts for a subject, must be the session's owner: another owner's session id is the 404 of a
+ * missing one (not the 409 of a mismatch), and so is an Environment whose owner guard names
+ * another owner.
  *
- * The session's sandbox is decided here and fixed for its life (§5 of Sandboxes v3): shared
- * with `{ session }`, none with `false`, inline, or the Tenant default when omitted. A definition
- * that declares its own sandbox (`.sandbox()`) keeps it and takes no sandbox request.
+ * The session's Environment is fixed for its life: its sandbox (kinds `virtual` and `pod`) is
+ * the session's, with the spec of the Environment's applied recipe pinned now, and its vault
+ * holds the session's credentials. Without one the session has no sandbox and no credentials.
  */
 export declare function putSession(ctx: TenantContext, id: string, body: PutSessionRequest, access?: SessionAccess, options?: {
     /**
@@ -60,10 +64,10 @@ export declare function putSession(ctx: TenantContext, id: string, body: PutSess
      */
     createOnly?: boolean;
     /**
-     * The sandboxes the caller reaches (a token caller's grants, `sandboxGrantsOf`); undefined
-     * reaches every one. `sandbox: { id }` must name one of them.
+     * The Environments the caller reaches (a token caller's grants, `environmentGrantsOf`);
+     * undefined reaches every one. `environment` must name one of them.
      */
-    sandboxGrants?: readonly string[];
+    environmentGrants?: readonly string[];
 }): Promise<Session>;
 /** The session resource returned by `GET`/`PUT /v1/sessions/:id`. */
 export declare function sessionView(t: Tx, s: Session): Promise<unknown>;