@nylorun/runtime 0.24.0-beta → 0.25.0-beta

package/dist/tenant/environments.js

@@ -11,12 +11,16 @@
  *   keyed by the Environment id and created on the first tool call), `pod` (an agent-sandbox pod
  *   on the Tenant's cluster, Host feature `sandbox-pods`, created at once) or `none` (no compute).
  *   Each has one vault (`vault/service.ts`), created and deleted with it in one transaction.
- * - **A recipe that changes.** `PUT` on an existing id compares the fields sent: `kind` and
- *   `storage` are fixed (`409`), labels replace, and any other change writes the recipe and bumps
- *   `version`. A pod runs `applied`: image and resources reach it when it is next asked to run
- *   from stopped (`wantRunning`), so nothing swaps them mid-turn; so does `harness`, which picks
- *   what the pod runs (R4.4). Network and lifecycle apply at once. A virtual or `none`
- *   Environment applies every change at once.
+ * - **Made once, never changed** (protocol 14, D63). An Environment is made from one version of
+ *   an environment manifest (`manifest: "name"` or `"name@n"`, `environment-manifests.ts`) or
+ *   from an inline manifest (the fields of the `PUT`, its `recipe`), and keeps what it runs for
+ *   life: a `PUT` on an existing id may change its labels and owner guard, a field that matches
+ *   what it runs is accepted (so get-or-create stays one call), and anything else is
+ *   `409 environment_immutable`, naming the fork that makes a new Environment instead.
+ *   `version` and `appliedVersion` stay 1 for an Environment made since then.
+ * - **Secret slots** (D64): when what it runs declares `secrets`, a secret write sends only the
+ *   value, the binding comes from the slot, and a name it does not declare is
+ *   `409 secret_not_in_manifest` (`secretRequestFor`).
  * - **Access.** An application key reaches every Environment, and so does an application key
  *   acting for a subject (`Nylorun-Subject`), which needs `environments:write` to change one. A
  *   token caller reaches only the ids its grants match, and changes them only with
@@ -24,8 +28,10 @@
  * - **The owner guard.** When `ownerUserId` is set, only that owner's sessions may name the
  *   Environment, checked when a session opens and at every turn start (`403
  *   environment_owner_mismatch`; the opaque 404 to a caller acting for a person).
- * - **Serial turns.** One turn at a time per Environment with a sandbox: a session whose
- *   Environment another session's turn holds is refused (`409 environment_busy`).
+ * - **Parallel turns (D66).** Sessions on one Environment run their turns at the same time and
+ *   share its `/workspace`; one turn per session stays. Which sessions work on one disk, and when,
+ *   is the app's call. Disk work (snapshot, restore, stop, reset) waits until no turn runs
+ *   (`409 environment_busy`), and a turn waits while a seed copies a disk.
  * - **Lifecycle.** `POST .../stop` suspends a pod (the volume is kept; the next turn starts it),
  *   `POST .../reset` gives it a new pod on a new volume. A lost pod refuses turns
  *   (`environment_lost`) until a reset. `lifecycle.deleteAfter` deletes an Environment unused
@@ -34,7 +40,9 @@
  * - **Lifecycle events** go to the Environment's own stream in the record (`Tx.environmentEvent`,
  *   `record/environment.ts`); the session's log records `environment.attached` too.
  */
-import { environmentGranted, } from "@nylorun/core/contracts";
+import { randomUUID } from "node:crypto";
+import { environmentGranted, parseEnvironmentManifestRef, PutEnvironmentSecretRequestSchema, PutEnvironmentSecretValueRequestSchema, } from "@nylorun/core/contracts";
+import { hashManifest } from "@nylorun/core/compatibility";
 import { isWorkflowManifest, parseSandboxDuration } from "@nylorun/core/define";
 import { canonical } from "../store/canonical.js";
 import { resolveRecipe } from "../sandbox/resolve.js";
@@ -44,7 +52,8 @@ import { podName } from "../sandbox/pods/name.js";
 import { podLifecycleConfig } from "../sandbox/pods/spec.js";
 import { SETUP_FAILED } from "../sandbox/pods/lifecycle.js";
 import { requirePods } from "../sandbox/placement.js";
-import { deleteDiskArtifact, forkSeedOf, runPendingSeed } from "../artifacts/disk.js";
+import { deleteDiskArtifact, forkSeedOf, runPendingSeed, snapshotEnvironment } from "../artifacts/disk.js";
+import { manifestChanges, manifestRecipeRequest } from "./environment-manifests.js";
 import { harnessOf, sessionOf } from "./context.js";
 import { fail } from "./http.js";
 /** The Environment grants that limit `scope`, or undefined when it reaches every Environment. */
@@ -91,11 +100,17 @@ async function viewOf(ctx, t, environment, owner) {
         ? await t.get("sandboxes", sandboxWorkspaceKey(ctx.config.tenantId, environment.id))
         : undefined;
     const pod = environment.pod;
+    const slots = await slotsOf(t, environment);
     return {
         id: environment.id,
         kind: environment.kind,
         labels: environment.labels,
-        recipe: environment.recipe,
+        manifest: environment.recipe,
+        ...(environment.manifestName === undefined ? {} : { manifestName: environment.manifestName }),
+        ...(environment.manifestVersion === undefined ? {} : { manifestVersion: environment.manifestVersion }),
+        ...(environment.manifestHash === undefined ? {} : { manifestHash: environment.manifestHash }),
+        ...(environment.forkedFrom === undefined ? {} : { forkedFrom: environment.forkedFrom }),
+        ...(slots === undefined ? {} : { slots }),
         version: environment.version,
         appliedVersion: environment.appliedVersion,
         ownerUserId: environment.ownerUserId ?? null,
@@ -108,6 +123,7 @@ async function viewOf(ctx, t, environment, owner) {
                     volumeGeneration: pod.volumeGen,
                     hostEpoch: pod.hostEpoch,
                     ...(pod.reason ? { reason: pod.reason } : {}),
+                    ...(pod.imageDigest ? { imageDigest: pod.imageDigest } : {}),
                 },
             }
             : {}),
@@ -135,6 +151,34 @@ async function viewOf(ctx, t, environment, owner) {
         updatedAt: environment.updatedAt,
     };
 }
+/** Each secret slot `environment` declares, and whether its vault holds a value for it. */
+async function slotsOf(t, environment) {
+    const declared = environment.recipe.secrets;
+    if (declared === undefined)
+        return undefined;
+    const vault = await t.vaultOfEnvironment(environment.id);
+    const held = new Set(vault ? (await t.credentialsForVault(vault.id)).map((row) => row.name) : []);
+    return Object.entries(declared)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, slot]) => ({ name, type: slot.type, required: slot.required ?? false, set: held.has(name) }));
+}
+/** The inline fields of a `PUT`: what it would run, besides labels, owner and `from`. */
+const INLINE_FIELDS = [
+    "kind",
+    "image",
+    "resources",
+    "storage",
+    "network",
+    "harness",
+    "lifecycle",
+    "setup",
+    "files",
+    "secrets",
+];
+/** The hash of what an Environment runs, recorded when it is made. */
+function recipeHash(recipe) {
+    return hashManifest(recipe);
+}
 /** What a `PUT` asks of the recipe: its fields over `existing`'s (fixed `storage` kept). */
 function recipeRequest(body, existing) {
     const recipe = existing?.recipe;
@@ -152,20 +196,38 @@ function recipeRequest(body, existing) {
         ...pick("lifecycle", body.lifecycle),
         ...pick("setup", body.setup),
         ...pick("files", body.files),
+        ...pick("secrets", body.secrets),
     };
 }
 /**
- * Refuses input files that are not a version of a Tenant-wide artifact (a session's artifacts
- * go with the session); pins nothing else: the version is the one named.
+ * Why input files cannot be used: each that is not a version of a Tenant-wide artifact (a
+ * session's artifacts go with the session). Pins nothing else: the version is the one named.
  */
-async function checkFiles(t, files) {
+export async function fileErrors(t, files) {
+    const errors = [];
     for (const file of files ?? []) {
+        if ("files" in file) {
+            // Files by hash (Q6): each a definition file the Tenant holds.
+            const wanted = [...new Set(Object.values(file.files))];
+            const held = await t.heldDefinitionFiles(wanted);
+            for (const [path, sha256] of Object.entries(file.files))
+                if (!held.has(sha256))
+                    errors.push(`files: ${file.path}/${path} names ${sha256}, which the Tenant does not hold: upload it first (PUT /v1/files/${sha256}).`);
+            continue;
+        }
         const artifact = await t.artifact(file.artifactId);
         if (!artifact || artifact.sessionId !== null)
-            fail(400, `files: ${file.artifactId} is not an artifact of the Tenant (an artifact of a session cannot be one).`);
-        if (!(await t.artifactVersion(file.artifactId, file.version)))
-            fail(400, `files: ${file.artifactId} has no version ${file.version}.`);
+            errors.push(`files: ${file.artifactId} is not an artifact of the Tenant (an artifact of a session cannot be one).`);
+        else if (!(await t.artifactVersion(file.artifactId, file.version)))
+            errors.push(`files: ${file.artifactId} has no version ${file.version}.`);
     }
+    return errors;
+}
+/** Refuses input files that cannot be used (`fileErrors`). */
+async function checkFiles(t, files) {
+    const errors = await fileErrors(t, files);
+    if (errors.length > 0)
+        fail(400, errors.join(" "));
 }
 /** Refuses an owner guard a caller acting for a person may not set. */
 function checkGuard(scope, asked, current) {
@@ -213,15 +275,33 @@ async function wantRunning(t, environment, now) {
 }
 /**
  * `PUT /v1/environments/{id}`: creates the Environment and its vault (within the Tenant's limit
- * on their number), or finds the one with this id, so "get or create" is one call. On an
- * existing one, `kind` and `storage` must match, labels replace, the owner guard is set or
- * cleared, and a recipe change bumps `version`. Every `PUT` counts as the Environment's use.
+ * on their number) from an environment manifest's version or from the inline fields, or finds
+ * the one with this id, so "get or create" is one call. An existing one never changes what it
+ * runs (D63): its labels and owner guard may change, fields that match are accepted, and any
+ * other difference is `409 environment_immutable`. Every `PUT` counts as the Environment's use.
  */
-export async function putEnvironment(ctx, id, body, scope) {
+export async function putEnvironment(ctx, id, body, scope, options = {}) {
+    const fork = options.fork;
     reachable(environmentGrantsOf(scope), id);
+    const ref = body.manifest === undefined ? undefined : parseEnvironmentManifestRef(body.manifest);
+    if (body.manifest !== undefined) {
+        if (ref === undefined)
+            fail(400, "manifest is an environment manifest's name, or name@version such as analyst-box@3.");
+        const inline = INLINE_FIELDS.filter((field) => body[field] !== undefined);
+        if (inline.length > 0)
+            fail(400, `An Environment made from manifest ${body.manifest} runs what the manifest says: send no ${inline.join(", ")} with it.`);
+    }
     if (body.kind === "pod")
         await requirePods(ctx.pods, "A pod Environment");
-    const conflict = (field) => fail(409, `Environment ${id} exists with another ${field}, which is fixed: delete it to create it again.`);
+    const immutable = (fields, existing) => fail(409, `Environment ${id} exists and never changes what it runs (${fields.join(", ")} differ${fields.length === 1 ? "s" : ""}): fork it into a new Environment with POST /v1/environments/${encodeURIComponent(id)}/fork, or use another id.`, {
+        code: "environment_immutable",
+        details: {
+            fields: [...fields],
+            ...(existing.manifestName === undefined
+                ? {}
+                : { manifest: `${existing.manifestName}@${existing.manifestVersion}` }),
+        },
+    });
     const view = await ctx.store.tx(async (t) => {
         const now = new Date().toISOString();
         const config = effectiveSandboxConfig(await readSandboxConfig(t));
@@ -237,56 +317,36 @@ export async function putEnvironment(ctx, id, body, scope) {
                 }, { "retry-after": "5" });
         };
         const found = async (existing) => {
+            if (fork !== undefined)
+                fail(409, `Environment ${id} exists: a fork makes a new Environment, so name another id.`);
             if (body.from !== undefined)
                 fail(409, `Environment ${id} exists: from applies only when a PUT creates one.`);
-            if (body.kind !== undefined && body.kind !== existing.kind)
-                conflict("kind");
-            if (body.storage !== undefined && body.storage !== existing.recipe.storage)
-                conflict("storage");
+            if (ref !== undefined) {
+                // A bare name matches the manifest it was made from, whatever its latest version is now.
+                if (ref.name !== existing.manifestName)
+                    immutable(["manifest"], existing);
+                if (ref.version !== undefined && ref.version !== existing.manifestVersion)
+                    immutable(["manifest"], existing);
+            }
+            else if (INLINE_FIELDS.some((field) => body[field] !== undefined)) {
+                if (body.kind !== undefined && body.kind !== existing.kind)
+                    immutable(["kind"], existing);
+                if (body.storage !== undefined && body.storage !== existing.recipe.storage)
+                    immutable(["storage"], existing);
+                const recipe = resolve(existing.kind, recipeRequest(body, existing));
+                const differing = Object.keys({ ...recipe, ...existing.recipe })
+                    .filter((field) => canonical(recipe[field]) !== canonical(existing.recipe[field]))
+                    .sort();
+                if (differing.length > 0)
+                    immutable(differing, existing);
+            }
             checkGuard(scope, body.ownerUserId, existing.ownerUserId);
-            const recipe = resolve(existing.kind, recipeRequest(body, existing));
-            if (body.files !== undefined)
-                await checkFiles(t, recipe.files);
             const patch = { lastUsedAt: now };
             if (body.labels !== undefined && canonical(body.labels) !== canonical(existing.labels))
                 patch.labels = body.labels;
             if (body.ownerUserId !== undefined && (body.ownerUserId ?? undefined) !== existing.ownerUserId)
                 patch.ownerUserId = body.ownerUserId;
-            if (canonical(recipe) !== canonical(existing.recipe)) {
-                const version = existing.version + 1;
-                patch.recipe = recipe;
-                patch.version = version;
-                // What waits for the pod to start from stopped; setup and files run only on a new disk.
-                // The harness is what a pod runs (R4.4): it changes with the pod, like its image.
-                const compute = (r) => canonical({
-                    image: r.image ?? null,
-                    resources: r.resources ?? null,
-                    setup: r.setup ?? null,
-                    files: r.files ?? null,
-                    harness: r.harness,
-                });
-                if (existing.kind !== "pod" || compute(recipe) === compute(existing.applied)) {
-                    // Nothing waits for a wake: apply all of it.
-                    patch.applied = recipe;
-                    patch.appliedVersion = version;
-                }
-                else
-                    // Network and lifecycle apply at once; image, resources and harness at the next wake.
-                    patch.applied = {
-                        ...existing.applied,
-                        ...(recipe.network === undefined ? {} : { network: recipe.network }),
-                        lifecycle: recipe.lifecycle,
-                    };
-            }
             await t.updateEnvironment(id, patch, now);
-            if (patch.recipe !== undefined && existing.pod?.desired === "running")
-                // A new `lifecycle.idle` applies to the running pod's idle timer.
-                await t.signalSandbox(id, {
-                    kind: "arm",
-                    timer: "idle",
-                    at: Date.parse(existing.pod.lastActiveAt ?? existing.createdAt) +
-                        podLifecycleConfig(await readSandboxConfig(t), patch.recipe).idleMs,
-                });
             return viewOf(ctx, t, (await t.environment(id)) ?? existing, subjectOf(scope));
         };
         const existing = await t.environment(id, { lock: true });
@@ -294,10 +354,20 @@ export async function putEnvironment(ctx, id, body, scope) {
         if (existing)
             return found(existing);
         checkGuard(scope, body.ownerUserId);
-        const kind = body.kind ?? "virtual";
-        const recipe = resolve(kind, recipeRequest(body));
+        const manifest = ref === undefined
+            ? undefined
+            : ((await t.environmentManifest(ref.name, ref.version)) ??
+                fail(404, ref.version === undefined
+                    ? `No environment manifest is named ${ref.name}: save it first (PUT /v1/environment-manifests/${ref.name}).`
+                    : `Environment manifest ${ref.name} has no version ${ref.version}.`, { code: "manifest_not_found" }));
+        const kind = manifest ? (manifest.body.kind ?? "virtual") : (body.kind ?? "virtual");
+        if (manifest && kind === "pod")
+            await requirePods(ctx.pods, `Environment manifest ${manifest.name} is of kind pod, and a pod Environment`);
+        const recipe = resolve(kind, manifest ? manifestRecipeRequest(manifest.body) : recipeRequest(body));
         await checkFiles(t, recipe.files);
-        const seed = body.from === undefined ? undefined : await forkSource(t, scope, kind, body.from);
+        const from = body.from === undefined ? undefined : await forkSource(t, scope, kind, body.from);
+        // A fork onto other setup runs it on the written disk (Q17).
+        const seed = from && fork?.setup ? { ...from, setup: true } : from;
         const row = {
             id,
             kind,
@@ -310,6 +380,9 @@ export async function putEnvironment(ctx, id, body, scope) {
             lastUsedAt: now,
             createdAt: now,
             updatedAt: now,
+            ...(manifest ? { manifestName: manifest.name, manifestVersion: manifest.version } : {}),
+            manifestHash: recipeHash(recipe),
+            ...(fork ? { forkedFrom: { environment: fork.source, disk: seed?.version ?? null } } : {}),
             ...(seed
                 ? {
                     diskSeed: seed,
@@ -348,12 +421,24 @@ export async function putEnvironment(ctx, id, body, scope) {
             deleting(again);
             return found(again);
         }
-        await ctx.vault.createEnvironmentVault(t, id, actorOf(scope));
+        const vaultId = await ctx.vault.createEnvironmentVault(t, id, actorOf(scope), fork?.sealed?.vaultId);
+        if (fork?.sealed)
+            fork.copied = await ctx.vault.insertEnvironmentSecretCopies(t, vaultId, fork.source, actorOf(scope), fork.sealed.copies);
+        const madeFrom = manifest ? { manifest: { name: manifest.name, version: manifest.version } } : {};
         await t.environmentEvent(id, "environment.created", {
             kind,
             labels: row.labels,
+            ...madeFrom,
             ...(seed ? { from: { environment: body.from.environment, version: seed.version } } : {}),
+            ...(row.forkedFrom ? { forkedFrom: row.forkedFrom } : {}),
         });
+        if (fork)
+            await t.environmentEvent(fork.source, "environment.forked", {
+                to: id,
+                disk: seed?.version ?? null,
+                ...madeFrom,
+                secrets: fork.copied?.copied.length ?? 0,
+            });
         if (row.pod) {
             // Created at once; idle from now if no turn comes.
             await reconcileAfter(t, id);
@@ -369,6 +454,45 @@ export async function putEnvironment(ctx, id, body, scope) {
     }
     return view;
 }
+/**
+ * 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.
+ */
+export async function secretRequestFor(ctx, id, name, raw) {
+    const environment = await ctx.store.tx((t) => liveEnvironment(t, id));
+    const slots = environment?.recipe.secrets;
+    if (!environment || slots === undefined)
+        return PutEnvironmentSecretRequestSchema.parse(raw);
+    const slot = slots[name] ??
+        fail(409, `What Environment ${id} runs declares no secret ${name}${environment.manifestName ? ` (manifest ${environment.manifestName}@${environment.manifestVersion})` : ""}: add the slot to the manifest, then make or fork an Environment from the new version.`, { code: "secret_not_in_manifest", details: { declared: Object.keys(slots).sort() } });
+    const full = slotRequest(slot);
+    if (raw !== null && typeof raw === "object" && "type" in raw) {
+        const body = PutEnvironmentSecretRequestSchema.parse(raw);
+        const { requestId: _, value: _v, headers: _h, ...binding } = body;
+        if (canonical(binding) !== canonical(full))
+            fail(409, `Secret ${name}'s type and binding come from what Environment ${id} runs: send only its value ({ "value": "…" }).`, {
+                code: "secret_not_in_manifest",
+            });
+        return body;
+    }
+    const { requestId, value, headers } = PutEnvironmentSecretValueRequestSchema.parse(raw);
+    const withId = requestId === undefined ? {} : { requestId };
+    if (slot.type === "headers") {
+        if (headers === undefined)
+            fail(400, `Secret ${name} is a headers credential: send { "headers": { … } }.`);
+        return PutEnvironmentSecretRequestSchema.parse({ ...withId, ...full, headers });
+    }
+    if (value === undefined)
+        fail(400, `Secret ${name} takes a value: send { "value": "…" }.`);
+    return PutEnvironmentSecretRequestSchema.parse({ ...withId, ...full, value });
+}
+/** A slot's type and binding, as a secret write's fields (without the value). */
+function slotRequest(slot) {
+    const { required: _r, description: _d, ...binding } = slot;
+    return binding;
+}
 /**
  * The disk version a create's `from` names (R2d step 3): the caller's grants must reach the
  * source, a caller acting for a person must be its guard's owner, and kind `none` has no disk.
@@ -383,6 +507,113 @@ async function forkSource(t, scope, kind, from) {
         notFound();
     return forkSeedOf(t, from);
 }
+/**
+ * `POST /v1/environments/{id}/fork` (Q15): how an Environment gets a new manifest version. A new
+ * Environment `body.id` is made from the manifest version (default the source's manifest at its
+ * latest), its disk started from a version of the source's (`latest` takes a snapshot first,
+ * refused during a turn), and its secrets copied inside the Runtime. A fork onto other setup
+ * runs that setup on the copied disk before its first turn (Q17). The source keeps what it runs,
+ * its disk and its sessions. With `dryRun`, the plan only.
+ */
+export async function forkEnvironment(ctx, sourceId, body, scope) {
+    const grants = environmentGrantsOf(scope);
+    reachable(grants, sourceId);
+    reachable(grants, body.id);
+    if (body.id === sourceId)
+        fail(400, "A fork is a new Environment: give it another id.");
+    const { plan: planned, slots } = await ctx.store.tx(async (t) => {
+        const source = (await liveEnvironment(t, sourceId)) ?? notFound();
+        const subject = subjectOf(scope);
+        if (subject !== undefined && source.ownerUserId !== undefined && source.ownerUserId !== subject)
+            notFound();
+        const ref = body.manifest === undefined ? undefined : parseEnvironmentManifestRef(body.manifest);
+        if (body.manifest !== undefined && ref === undefined)
+            fail(400, "manifest is an environment manifest's name, or name@version such as analyst-box@3.");
+        const name = ref?.name ??
+            source.manifestName ??
+            fail(400, `Environment ${sourceId} was made from inline fields, not a manifest: name the manifest to fork it onto (manifest).`);
+        const manifest = (await t.environmentManifest(name, ref?.version)) ??
+            fail(404, ref?.version === undefined
+                ? `No environment manifest is named ${name}.`
+                : `Environment manifest ${name} has no version ${ref.version}.`, { code: "manifest_not_found" });
+        const kind = manifest.body.kind ?? "virtual";
+        const resolved = resolveRecipe(kind, manifestRecipeRequest(manifest.body), effectiveSandboxConfig(await readSandboxConfig(t)));
+        if (resolved.kind === "error")
+            return fail(400, resolved.errors.join(" "));
+        const recipe = resolved.recipe;
+        const asked = body.disk ?? "latest";
+        const disk = kind === "none" || source.kind === "none" || asked === "empty"
+            ? null
+            : asked === "latest"
+                ? "latest"
+                : (await forkSeedOf(t, { environment: sourceId, version: asked })).version;
+        const vault = await t.vaultOfEnvironment(sourceId);
+        const names = vault
+            ? (await t.credentialsForVault(vault.id)).filter((row) => row.type !== "model").map((row) => row.name).sort()
+            : [];
+        const copied = body.secrets === "none" ? [] : names.filter((item) => recipe.secrets === undefined || item in recipe.secrets);
+        const plan = {
+            source: sourceId,
+            id: body.id,
+            kind,
+            manifest: { name: manifest.name, version: manifest.version },
+            disk,
+            setup: kind === "pod" &&
+                disk !== null &&
+                recipeHash(recipe) !== source.manifestHash &&
+                Boolean(recipe.setup?.length || recipe.files?.length),
+            secrets: {
+                copied,
+                dropped: names.filter((item) => !copied.includes(item)),
+                missing: Object.entries(recipe.secrets ?? {})
+                    .filter(([item, slot]) => slot.required === true && !copied.includes(item))
+                    .map(([item]) => item)
+                    .sort(),
+            },
+            changes: manifestChanges(source.recipe, recipe),
+            sessions: (await t.sessionsOnEnvironment(sourceId)).length,
+        };
+        const slots = recipe.secrets === undefined
+            ? null
+            : Object.fromEntries(Object.entries(recipe.secrets).map(([item, slot]) => [item, slotRequest(slot)]));
+        return { plan, slots };
+    });
+    if (body.dryRun)
+        return { dryRun: true, plan: planned };
+    // `latest`: a version of the disk as it is now, between turns (an unchanged disk makes none).
+    const disk = planned.disk === "latest" ? (await snapshotEnvironment(ctx, sourceId, scope)).version : planned.disk;
+    // Keys holds the vault key (F4.2): it seals the copies first, outside the create's transaction,
+    // and the create inserts them, so the fork is still one commit.
+    const vaultId = randomUUID();
+    const sealed = (body.secrets ?? "copy") === "copy"
+        ? { vaultId, copies: await ctx.keys.sealEnvironmentSecretCopies(sourceId, vaultId, slots) }
+        : undefined;
+    const fork = { source: sourceId, setup: planned.setup, ...(sealed ? { sealed } : {}) };
+    const environment = await putEnvironment(ctx, body.id, {
+        ...(body.requestId === undefined ? {} : { requestId: body.requestId }),
+        manifest: `${planned.manifest.name}@${planned.manifest.version}`,
+        ...(body.labels === undefined ? {} : { labels: body.labels }),
+        ...(body.ownerUserId === undefined ? {} : { ownerUserId: body.ownerUserId }),
+        ...(disk === null ? {} : { from: { environment: sourceId, version: disk } }),
+    }, scope, { fork });
+    const copied = fork.copied ?? { copied: [], dropped: planned.secrets.copied };
+    const dropped = [...new Set([...planned.secrets.dropped, ...copied.dropped])].sort();
+    return {
+        environment,
+        plan: {
+            ...planned,
+            disk,
+            secrets: {
+                copied: copied.copied,
+                dropped,
+                missing: Object.entries(environment.manifest.secrets ?? {})
+                    .filter(([item, slot]) => slot.required === true && !copied.copied.includes(item))
+                    .map(([item]) => item)
+                    .sort(),
+            },
+        },
+    };
+}
 /** `GET /v1/environments/{id}`. */
 export async function getEnvironment(ctx, id, scope) {
     reachable(environmentGrantsOf(scope), id);
@@ -645,11 +876,9 @@ export async function newVolume(ctx, t, environment, options = {}) {
 /** How long a pending seed holds the disk before another process may take it over. */
 export const SEED_LEASE_MS = 10 * 60_000;
 /** `GET /v1/environments/{id}/events`: the Environment's lifecycle stream. */
-export async function environmentEventsOf(ctx, id, scope, fromSeq) {
+export async function environmentEventsOf(ctx, id, scope, query = {}) {
     reachable(environmentGrantsOf(scope), id);
-    return ctx.store.tx(async (t) => ({
-        events: await t.environmentEvents(id, fromSeq === undefined ? {} : { fromSeq }),
-    }));
+    return ctx.store.tx(async (t) => ({ events: await t.environmentEvents(id, query) }));
 }
 /**
  * The owner guard (Q7): refuses a session of `ownerUserId` on an Environment guarded for
@@ -681,9 +910,9 @@ export async function recordAttachment(t, sessionId, environmentId) {
 /**
  * Checks a turn start on a session that names an Environment, in the command's transaction
  * after the session row lock: the Environment still exists, a token caller's grants reach it,
- * its owner guard admits the session's owner, and, with a sandbox, no other session's turn
- * holds it. Holds the Environment row's lock until the transaction ends, so two turn starts on
- * one Environment are decided one after the other.
+ * its owner guard admits the session's owner, and no disk copy holds it. Other sessions' turns
+ * do not stop it (D66). Holds the Environment row's lock until the transaction ends, so a turn
+ * start and disk work on one Environment are decided one after the other.
  *
  * A pod Environment must also be usable: not lost (`environment_lost`), on a Runtime with
  * sandbox pods (`environment_unavailable`). A stopped or failed pod is asked to run again, with
@@ -718,19 +947,11 @@ export async function checkEnvironmentTurn(t, session, scope, ctx) {
         return;
     // A snapshot or restore copies the disk between turns (R2d step 3); a seed's turn waits.
     refuseDiskCopy(environment);
-    // A flow tree's sessions nest their turns in its root's: one holder.
-    const tree = session.flowRootId ?? session.id;
-    const holder = (await t.sessionsOnEnvironment(id)).find((other) => other.id !== session.id && other.activeTurnId !== null && (other.flowRootId ?? other.id) !== tree);
-    if (holder)
-        fail(409, `Environment ${id} is running another session's turn. Turns are serial per Environment.`, {
-            code: "environment_busy",
-            details: { retryAfterSeconds: 5 },
-        }, { "retry-after": "5" });
     const pod = environment.pod;
     if (!pod)
         return;
     if (!ctx?.pods)
-        fail(409, `Environment ${id} is a pod Environment, and this Runtime has no sandbox pods: run \`nylorun sandbox enable --context <name>\`.`, {
+        fail(409, `Environment ${id} is a pod Environment, and this Runtime has no sandbox pods: run \`nylorun local sandbox enable --context <name>\`.`, {
             code: "environment_unavailable",
         });
     if (pod.observed === "lost")

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/sessions.d.ts

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