@nylorun/runtime 0.22.0-beta → 0.24.0-beta

package/dist/sandbox/pods/lifecycle.js

@@ -1,3 +1,5 @@
+/** A setup failure's `reason` starts with this (`sandbox/setup.ts`); it is sticky. */
+export const SETUP_FAILED = "setup:";
 /** A pod not ready this long after it was asked to run has failed. */
 export const READY_DEADLINE_MS = 5 * 60_000;
 /** How soon to look again while the pod changes. */
@@ -67,24 +69,6 @@ export function decide(facts) {
             again(POLL_MS);
         return done();
     }
-    const expiresAt = pod.expiresAt === undefined ? undefined : Date.parse(pod.expiresAt);
-    if (expiresAt !== undefined && now >= expiresAt) {
-        if (pod.observed !== "expired") {
-            patch.observed = "expired";
-            patch.hostEpoch = pod.hostEpoch + 1;
-            events.push(event("sandbox.expired", { onExpiry: facts.config.onExpiry }));
-        }
-        if (facts.config.onExpiry === "delete") {
-            patch.desired = "deleted";
-            patch.rev = pod.rev + 1;
-            if (status.exists && !status.deleting)
-                deletes.push(pod.k8sName);
-            again(POLL_MS);
-        }
-        return done();
-    }
-    if (expiresAt !== undefined)
-        arm.push({ timer: "ttl", at: expiresAt });
     let desired = pod.desired;
     let rev = pod.rev;
     if (facts.trigger === "idle" && desired === "running" && !facts.busy) {
@@ -96,7 +80,7 @@ export function decide(facts) {
             patch.desired = desired;
             patch.rev = rev;
             patch.hostEpoch = pod.hostEpoch + 1;
-            events.push(event("sandbox.suspended", { reason: "idle" }));
+            events.push(event("environment.suspended", { reason: "idle" }));
         }
         else
             arm.push({ timer: "idle", at: due });
@@ -104,14 +88,14 @@ export function decide(facts) {
     // An incarnation a pod has joined, whose Sandbox or volume is gone: lost.
     if (pod.podUid !== undefined && (!status.exists || status.deleting || status.volume === "missing")) {
         const reason = !status.exists
-            ? "The sandbox's pod and volume were deleted outside the Runtime"
+            ? "The Environment's pod and volume were deleted outside the Runtime"
             : status.deleting
-                ? "The sandbox is being deleted outside the Runtime"
-                : "The sandbox's volume is gone";
+                ? "The Environment's pod is being deleted outside the Runtime"
+                : "The Environment's volume is gone";
         patch.observed = "lost";
         patch.reason = reason;
         patch.hostEpoch = (patch.hostEpoch ?? pod.hostEpoch) + 1;
-        events.push(event("sandbox.lost", { reason }));
+        events.push(event("environment.lost", { reason }));
         if (status.exists && !status.deleting)
             deletes.push(pod.k8sName);
         if (status.exists)
@@ -119,7 +103,7 @@ export function decide(facts) {
         return done();
     }
     if (status.deleting) {
-        // The previous incarnation of this name is still going (a sandbox deleted and created again).
+        // The previous incarnation of this name is still going (an Environment deleted and created again).
         again(POLL_MS);
         return done();
     }
@@ -135,7 +119,7 @@ export function decide(facts) {
             patch.startedAt = new Date(now).toISOString();
             patch.reason = null;
         }
-        // A pod started by this apply (a create, a resume) is the sandbox's first, not a relaunch.
+        // A pod started by this apply (a create, a resume) is the Environment's first, not a relaunch.
         if (desired === "running" && pod.podUid !== undefined)
             patch.podUid = null;
         again(POLL_MS);
@@ -144,6 +128,10 @@ export function decide(facts) {
         });
     }
     if (desired === "running") {
+        // A failed setup (R2d step 2) stays failed until a turn start asks the pod to run again,
+        // though the pod itself is ready: its engine takes no turn meanwhile.
+        if (pod.observed === "failed" && pod.reason?.startsWith(SETUP_FAILED))
+            return done();
         if (status.ready) {
             if (pod.observed !== "running") {
                 patch.observed = "running";
@@ -159,7 +147,7 @@ export function decide(facts) {
                 `The pod was not ready within ${READY_DEADLINE_MS / 60_000} minutes`;
             patch.observed = "failed";
             patch.reason = reason;
-            events.push(event("sandbox.failed", { reason }));
+            events.push(event("environment.failed", { reason }));
             return done();
         }
         if (pod.observed !== "creating")

package/dist/sandbox/pods/reconcile.js

@@ -15,8 +15,10 @@
  * infrastructure errors throw; Restate retries those.
  */
 import { randomBytes } from "node:crypto";
-import { readSandboxConfig } from "../tenant-config.js";
+import { effectiveSandboxConfig, readSandboxConfig } from "../tenant-config.js";
+import { podSandboxSpecOf } from "../resolve.js";
 import { sha256Hex } from "../join.js";
+import { recoverLostVolume } from "../../artifacts/disk.js";
 import { decide } from "./lifecycle.js";
 import { podLifecycleConfig, podSpecOf } from "./spec.js";
 export async function reconcileSandbox(ctx, sandboxId, trigger) {
@@ -24,11 +26,11 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
     if (!pods || ctx.closed)
         return {};
     const read = await ctx.store.tx(async (t) => {
-        const row = await t.sandboxResource(sandboxId);
+        const row = await t.environment(sandboxId);
         if (!row || row.kind !== "pod" || !row.pod)
             return undefined;
         const config = await readSandboxConfig(t);
-        const busy = (await t.sessionsOnSandbox(sandboxId)).some((session) => session.activeTurnId != null);
+        const busy = (await t.sessionsOnEnvironment(sandboxId)).some((session) => session.activeTurnId != null);
         return { row: row, config, busy };
     });
     if (!read)
@@ -47,7 +49,7 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
             return undefined;
         }
     };
-    const lifecycle = podLifecycleConfig(config);
+    const lifecycle = podLifecycleConfig(config, row.recipe);
     const decision = decide({
         row,
         config: lifecycle,
@@ -69,10 +71,10 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
         joinToken = randomBytes(32).toString("base64url");
         rev += 1;
         const recorded = await ctx.store.tx(async (t) => {
-            const current = await t.sandboxResource(sandboxId, { lock: true });
+            const current = await t.environment(sandboxId, { lock: true });
             if (!unchanged(current?.pod))
                 return false;
-            await t.updateSandboxPod(sandboxId, { joinTokenHash: sha256Hex(joinToken), rev }, new Date().toISOString());
+            await t.updateEnvironmentPod(sandboxId, { joinTokenHash: sha256Hex(joinToken), rev }, new Date().toISOString());
             return true;
         });
         if (!recorded)
@@ -95,12 +97,13 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
     }
     if (decision.apply) {
         const spec = podSpecOf({
-            sandboxId,
-            spec: row.spec,
+            environmentId: sandboxId,
+            spec: podSandboxSpecOf(row.applied, effectiveSandboxConfig(config).limits.idle),
             pod: { ...row.pod, rev },
             config,
             mode: decision.apply.mode,
             harnessImage: pods.harnessImage,
+            harness: row.applied.harness,
             ...(joinToken ? { joinToken } : {}),
         });
         try {
@@ -117,13 +120,13 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
         }
     }
     const written = await ctx.store.tx(async (t) => {
-        const current = await t.sandboxResource(sandboxId, { lock: true });
+        const current = await t.environment(sandboxId, { lock: true });
         if (!current?.pod)
             return { kind: "gone" };
         if (!unchanged(current.pod))
             return { kind: "changed" };
         if (decision.removeRow) {
-            await t.deleteSandboxResource(sandboxId);
+            await t.deleteEnvironment(sandboxId);
             return { kind: "removed" };
         }
         const epochMoved = patch.hostEpoch !== undefined && patch.hostEpoch !== null;
@@ -132,10 +135,12 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
             ...(epochMoved ? { hostEpoch: current.pod.hostEpoch + 1 } : {}),
         };
         if (Object.keys(finalPatch).length > 0)
-            await t.updateSandboxPod(sandboxId, finalPatch, new Date().toISOString());
+            await t.updateEnvironmentPod(sandboxId, finalPatch, new Date().toISOString());
         for (const item of decision.events)
-            await t.sandboxEvent(sandboxId, item.type, item.payload);
-        return { kind: "written", epoch: epochMoved ? current.pod.hostEpoch + 1 : undefined };
+            await t.environmentEvent(sandboxId, item.type, item.payload);
+        if (epochMoved)
+            await t.signal({ type: "host.revoked", sandboxId, epoch: finalPatch.hostEpoch });
+        return { kind: "written" };
     });
     if (written.kind === "changed")
         return { retryAfterMs: 0 };
@@ -143,8 +148,9 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
         await ctx.sandbox.removeSandbox(sandboxId).catch(() => undefined);
         return {};
     }
-    if (written.kind === "written" && written.epoch !== undefined)
-        ctx.harness.revokeHost(sandboxId, written.epoch);
+    // A lost volume with a disk version starts again from the latest one (R2d step 3).
+    if (patch.observed === "lost" && (await recoverLostVolume(ctx, sandboxId).catch(() => false)))
+        return { retryAfterMs: 0 };
     return {
         ...(decision.retryAfterMs === undefined ? {} : { retryAfterMs: decision.retryAfterMs }),
         ...(decision.arm.length > 0 ? { arm: decision.arm } : {}),

package/dist/sandbox/pods/spec.d.ts

@@ -1,10 +1,11 @@
 /**
- * The `PUT /v1/pods/{name}` body of a pod sandbox: its resolved spec, the Tenant's lifecycle
+ * The `PUT /v1/pods/{name}` body of a pod Environment: its applied recipe, the Tenant's lifecycle
  * settings (D36, read at every apply) and the incarnation's fences. The pod shape itself is
  * rendered only by the sandboxes service.
  */
 import { type SandboxManifest } from "@nylorun/core/define";
-import type { TenantSandboxConfig } from "@nylorun/core/contracts";
+import { type EnvironmentRecipe } from "@nylorun/core/contracts";
+import type { TenantSandboxConfig } from "../tenant-config.js";
 import type { SandboxPodState } from "../../store/types.js";
 import type { PodSpec } from "./client.js";
 import { type PodLifecycleConfig } from "./lifecycle.js";
@@ -14,32 +15,33 @@ export declare const DEFAULT_STOP_GRACE_SECONDS = 10;
 export declare const DEFAULT_STORAGE_GIB = 5;
 /** Where the engine in the pod keeps its records, plugin data and home (on the volume). */
 export declare const POD_HARNESS_ROOT = "/harness";
-/** What a pod sandbox's spec holds beyond a virtual one's. */
+/** What a pod's spec holds beyond a virtual sandbox's. */
 export type PodSandboxSpec = SandboxManifest & {
     readonly storage?: string;
-    readonly lifecycle?: {
-        readonly ttl?: string;
-    };
 };
-/** The Tenant's lifecycle settings with their defaults. */
-export declare function podLifecycleConfig(config: TenantSandboxConfig): PodLifecycleConfig & {
+/**
+ * The lifecycle settings with their defaults: the Tenant's (D36), and the Environment's
+ * `lifecycle.idle` within the Tenant's `limits.idle` when `recipe` is given.
+ */
+export declare function podLifecycleConfig(config: TenantSandboxConfig, recipe?: Pick<EnvironmentRecipe, "lifecycle">): PodLifecycleConfig & {
     readonly stopGraceSeconds: number;
 };
 /** The volume's size in GiB. */
 export declare function storageGiBOf(spec: PodSandboxSpec): number;
-/** The Tenant's default image, when its default sandbox names one. */
-export declare function tenantDefaultImage(config: TenantSandboxConfig): string | undefined;
 export interface PodSpecInput {
-    readonly sandboxId: string;
+    readonly environmentId: string;
     readonly spec: PodSandboxSpec;
     readonly pod: SandboxPodState;
     readonly config: TenantSandboxConfig;
     readonly mode: "Running" | "Suspended";
     /** The Runtime image the engine is copied from. */
     readonly harnessImage: string;
+    /**
+     * The harness the pod runs (R4.4): ours, copied in from `harnessImage`, or a custom one, which
+     * is the workload image itself and runs as its entrypoint.
+     */
+    readonly harness?: string;
     /** The join token, when this apply rotates it. */
     readonly joinToken?: string;
 }
 export declare function podSpecOf(input: PodSpecInput): PodSpec;
-/** When a sandbox with this TTL, created at `createdAt`, expires. */
-export declare function expiresAtOf(createdAt: string, ttl: string | undefined): string | undefined;

package/dist/sandbox/pods/spec.js

@@ -1,9 +1,10 @@
 /**
- * The `PUT /v1/pods/{name}` body of a pod sandbox: its resolved spec, the Tenant's lifecycle
+ * The `PUT /v1/pods/{name}` body of a pod Environment: its applied recipe, the Tenant's lifecycle
  * settings (D36, read at every apply) and the incarnation's fences. The pod shape itself is
  * rendered only by the sandboxes service.
  */
 import { parseSandboxDuration, parseSandboxSize } from "@nylorun/core/define";
+import { DEFAULT_HARNESS } from "@nylorun/core/contracts";
 import { memoryMiBOf } from "../policy.js";
 import { opIdOf } from "./lifecycle.js";
 /** The pod's grace period to stop when the Tenant sets none (D34). */
@@ -12,12 +13,16 @@ export const DEFAULT_STOP_GRACE_SECONDS = 10;
 export const DEFAULT_STORAGE_GIB = 5;
 /** Where the engine in the pod keeps its records, plugin data and home (on the volume). */
 export const POD_HARNESS_ROOT = "/harness";
-/** The Tenant's lifecycle settings with their defaults. */
-export function podLifecycleConfig(config) {
+/**
+ * The lifecycle settings with their defaults: the Tenant's (D36), and the Environment's
+ * `lifecycle.idle` within the Tenant's `limits.idle` when `recipe` is given.
+ */
+export function podLifecycleConfig(config, recipe) {
     const stopGrace = config.lifecycle?.stopGrace;
+    const tenantIdle = parseSandboxDuration(config.limits?.idle ?? "15m") ?? 15 * 60_000;
+    const own = recipe?.lifecycle.idle === undefined ? undefined : parseSandboxDuration(recipe.lifecycle.idle);
     return {
-        onExpiry: config.lifecycle?.onExpiry ?? "retain",
-        idleMs: parseSandboxDuration(config.limits?.idle ?? "15m") ?? 15 * 60_000,
+        idleMs: own === undefined ? tenantIdle : Math.min(own, tenantIdle),
         stopGraceSeconds: stopGrace === undefined
             ? DEFAULT_STOP_GRACE_SECONDS
             : Math.max(1, Math.min(30, Math.round((parseSandboxDuration(stopGrace) ?? 10_000) / 1000))),
@@ -28,35 +33,26 @@ export function storageGiBOf(spec) {
     const bytes = spec.storage === undefined ? undefined : parseSandboxSize(spec.storage);
     return bytes === undefined ? DEFAULT_STORAGE_GIB : Math.max(1, Math.ceil(bytes / 1024 ** 3));
 }
-/** The Tenant's default image, when its default sandbox names one. */
-export function tenantDefaultImage(config) {
-    const fallback = config.default;
-    return typeof fallback === "object" ? fallback.image : undefined;
-}
 export function podSpecOf(input) {
     const { spec, pod, config } = input;
     const lifecycle = podLifecycleConfig(config);
-    const image = spec.image ?? tenantDefaultImage(config);
+    const image = spec.image;
+    const ours = (input.harness ?? DEFAULT_HARNESS) === DEFAULT_HARNESS;
     return {
         opId: opIdOf(pod),
         mode: input.mode,
         ...(image ? { image } : {}),
-        harnessImage: input.harnessImage,
+        // A custom harness is its image: the pod runs the image's entrypoint, nothing copied in.
+        ...(ours ? { harnessImage: input.harnessImage } : { entrypoint: "image" }),
         cpus: spec.resources?.cpus ?? 1,
         memoryMiB: memoryMiBOf(spec),
         storageGiB: storageGiBOf(spec),
         stopGraceSeconds: lifecycle.stopGraceSeconds,
-        ...(pod.expiresAt ? { shutdownTime: new Date(pod.expiresAt).toISOString().replace(/\.\d{3}Z$/, "Z") } : {}),
-        shutdownPolicy: lifecycle.onExpiry === "delete" ? "Delete" : "Retain",
+        shutdownPolicy: "Retain",
         env: {
-            NYLORUN_SANDBOX_ID: input.sandboxId,
+            NYLORUN_SANDBOX_ID: input.environmentId,
             NYLORUN_HARNESS_ROOT: POD_HARNESS_ROOT,
         },
         ...(input.joinToken ? { joinToken: input.joinToken } : {}),
     };
 }
-/** When a sandbox with this TTL, created at `createdAt`, expires. */
-export function expiresAtOf(createdAt, ttl) {
-    const ms = ttl === undefined ? undefined : parseSandboxDuration(ttl);
-    return ms === undefined ? undefined : new Date(Date.parse(createdAt) + ms).toISOString();
-}

package/dist/sandbox/records.d.ts

@@ -16,10 +16,10 @@ export declare function workspacePrefix(scope: string): string;
 /** The key of session `sessionId`'s own workspace. */
 export declare function sessionWorkspaceKey(scope: string, sessionId: string): string;
 /**
- * The key of sandbox resource `sandboxId`'s workspace: apart from every session key (16 hex
+ * The key of sandbox resource `environmentId`'s workspace: apart from every session key (16 hex
  * characters after the prefix). The virtual backend keeps it in `<sandboxes>/<key>/workspace`.
  */
-export declare function sandboxWorkspaceKey(scope: string, sandboxId: string): string;
+export declare function sandboxWorkspaceKey(scope: string, environmentId: string): string;
 /** The records in the Tenant's `sandboxes` table. */
 export declare function storeSandboxRecords(store: SessionStore): SandboxRecords;
 /**

package/dist/sandbox/records.js

@@ -21,11 +21,11 @@ export function sessionWorkspaceKey(scope, sessionId) {
     return workspacePrefix(scope) + createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
 }
 /**
- * The key of sandbox resource `sandboxId`'s workspace: apart from every session key (16 hex
+ * The key of sandbox resource `environmentId`'s workspace: apart from every session key (16 hex
  * characters after the prefix). The virtual backend keeps it in `<sandboxes>/<key>/workspace`.
  */
-export function sandboxWorkspaceKey(scope, sandboxId) {
-    return `${workspacePrefix(scope)}sbx-${createHash("sha256").update(sandboxId).digest("hex").slice(0, 16)}`;
+export function sandboxWorkspaceKey(scope, environmentId) {
+    return `${workspacePrefix(scope)}sbx-${createHash("sha256").update(environmentId).digest("hex").slice(0, 16)}`;
 }
 /** The records in the Tenant's `sandboxes` table. */
 export function storeSandboxRecords(store) {

package/dist/sandbox/resolve.d.ts

@@ -1,37 +1,45 @@
 /**
- * Resolves the sandbox a session asks for when it is opened against its Tenant's configuration.
- * Pure: the caller supplies the configuration and who is asking. Every problem is
- * reported, not only the first, so one response lists all of them.
+ * Resolves an Environment's recipe (`PUT /v1/environments/{id}`) against its Tenant's limits,
+ * and the sandbox spec a recipe gives the session's sandbox capability and the pod. Pure: the
+ * caller supplies the configuration. Every problem is reported, not only the first, so one
+ * response lists all of them.
  */
-import type { SandboxInlineRequest } from "@nylorun/core/contracts";
-import type { SandboxManifest } from "@nylorun/core/define";
+import type { EnvironmentFile, EnvironmentKind, EnvironmentLifecycle, EnvironmentRecipe, EnvironmentSetupCommand } from "@nylorun/core/contracts";
+import { type SandboxManifest } from "@nylorun/core/define";
+import type { PodSandboxSpec } from "./pods/spec.js";
 import { type EffectiveSandboxConfig } from "./tenant-config.js";
-export type SandboxSource = "default" | "inline";
-export type SandboxResolution = {
-    readonly kind: "none";
-} | {
-    readonly kind: "sandbox";
-    readonly spec: SandboxManifest;
-    readonly source: SandboxSource;
+/** What a `PUT` asks of the recipe: the request's fields, over the existing recipe's. */
+export interface RecipeRequest {
+    readonly image?: string;
+    readonly resources?: {
+        readonly cpus?: number;
+        readonly memory?: string;
+    };
+    readonly storage?: string;
+    readonly network?: {
+        readonly allowedHosts?: readonly string[];
+    };
+    readonly harness?: string;
+    readonly lifecycle?: EnvironmentLifecycle;
+    readonly setup?: readonly EnvironmentSetupCommand[];
+    readonly files?: readonly EnvironmentFile[];
+}
+export type RecipeResolution = {
+    readonly kind: "recipe";
+    readonly recipe: EnvironmentRecipe;
 } | {
     readonly kind: "error";
-    readonly status: 400 | 403;
     readonly errors: readonly string[];
 };
-export interface ResolveSandboxInput {
-    /** `PutSessionRequest.sandbox` other than `{ session }`, which the caller handles. */
-    readonly request: false | SandboxInlineRequest | undefined;
-    readonly config: EffectiveSandboxConfig;
-    /** The request acts for a subject (`Nylorun-Subject`) rather than as the application. */
-    readonly actingForSubject: boolean;
-    /**
-     * The sandbox's kind. Default `virtual`, which runs no images and allows exact host names
-     * only; a `pod` (F7.2) takes an image and `*.suffix` hosts.
-     */
-    readonly kind?: "virtual" | "pod";
-}
-export declare const SUBJECT_INLINE_MESSAGE = "Defining a sandbox needs an application key. Use the Tenant default, or open the session from the application backend.";
-export declare function resolveSandbox(input: ResolveSandboxInput): SandboxResolution;
+/** The recipe `request` asks for an Environment of `kind`, or every reason it cannot have it. */
+export declare function resolveRecipe(kind: EnvironmentKind, request: RecipeRequest, config: EffectiveSandboxConfig): RecipeResolution;
+/**
+ * The sandbox spec of a recipe: what the session's sandbox capability pins and the virtual
+ * workspace runs. Idle is the Environment's `lifecycle.idle`, else the Tenant's.
+ */
+export declare function sandboxSpecOf(recipe: EnvironmentRecipe, tenantIdle: string): SandboxManifest;
+/** The pod's spec of a recipe: its sandbox spec and its volume's size. */
+export declare function podSandboxSpecOf(recipe: EnvironmentRecipe, tenantIdle: string): PodSandboxSpec;
 /** Whether `host` (a name or `*.suffix` pattern) is inside one of the ceiling's patterns. */
 export declare function withinCeiling(host: string, ceiling: readonly string[]): boolean;
 /** Problems with a Tenant configuration, checked when an operator saves it. */

package/dist/sandbox/resolve.js

@@ -1,50 +1,84 @@
+import { DEFAULT_HARNESS } from "@nylorun/core/contracts";
+import { parseSandboxDuration } from "@nylorun/core/define";
 import { memoryMiB } from "./tenant-config.js";
-export const SUBJECT_INLINE_MESSAGE = "Defining a sandbox needs an application key. Use the Tenant default, or open the session from the application backend.";
-export function resolveSandbox(input) {
-    const { request, config } = input;
-    if (request === false)
-        return { kind: "none" };
-    if (request === undefined) {
-        const fallback = config.default;
-        if (fallback === "none")
-            return { kind: "none" };
-        return build(fallback === "virtual" ? {} : fallback, "default", input);
-    }
-    if (input.actingForSubject)
-        return { kind: "error", status: 403, errors: [SUBJECT_INLINE_MESSAGE] };
-    return build(request, "inline", input);
-}
-function build(request, source, input) {
-    const { limits } = input.config;
+/** The recipe `request` asks for an Environment of `kind`, or every reason it cannot have it. */
+export function resolveRecipe(kind, request, config) {
+    const { limits } = config;
     const errors = [];
-    const pod = input.kind === "pod";
+    const pod = kind === "pod";
+    // Any harness id (R4.1): placement decides where it may run, when a session opens.
+    const harness = request.harness ?? DEFAULT_HARNESS;
+    if (pod && harness !== DEFAULT_HARNESS && request.image === undefined)
+        errors.push(`harness ${harness} needs image: a pod Environment runs its image as the harness.`);
+    const lifecycle = request.lifecycle ?? {};
+    const idle = lifecycle.idle === undefined ? undefined : parseSandboxDuration(lifecycle.idle);
+    if (idle !== undefined && idle > (parseSandboxDuration(limits.idle) ?? Infinity))
+        errors.push(`lifecycle.idle is ${lifecycle.idle}; this Tenant allows at most ${limits.idle}.`);
+    if (kind === "none") {
+        for (const field of ["image", "resources", "storage", "network", "setup", "files"])
+            if (request[field] !== undefined)
+                errors.push(`${field} is for an Environment with a sandbox: kind none has none.`);
+        if (errors.length > 0)
+            return { kind: "error", errors };
+        return { kind: "recipe", recipe: { harness, lifecycle: { ...lifecycle } } };
+    }
     if (request.image !== undefined && !pod)
-        errors.push("sandbox.image is not supported: the virtual sandbox has no images.");
-    const allow = (request.network?.allow ?? []).map((host) => host.toLowerCase());
+        errors.push("image is for kind pod: a virtual Environment runs no images.");
+    if (request.storage !== undefined && !pod)
+        errors.push("storage is for kind pod: a virtual Environment has no volume.");
+    for (const field of ["setup", "files"])
+        if (request[field] !== undefined && request[field].length > 0 && !pod)
+            errors.push(`${field} is for kind pod: it runs when a pod's disk is made or reset.`);
+    const allow = (request.network?.allowedHosts ?? []).map((host) => host.toLowerCase());
     for (const host of allow) {
         if (!withinCeiling(host, limits.network))
-            errors.push(`sandbox.network.allow includes ${host}, which this Tenant does not allow.`);
+            errors.push(`network.allowedHosts includes ${host}, which this Tenant does not allow.`);
         else if (host.startsWith("*.") && !pod)
-            errors.push(`sandbox.network.allow includes ${host}; the virtual sandbox allows exact host names only, such as ${host.slice(2)}.`);
+            errors.push(`network.allowedHosts includes ${host}; a virtual Environment allows exact host names only, such as ${host.slice(2)}.`);
     }
     const cpus = request.resources?.cpus ?? limits.defaultResources.cpus;
     const memory = request.resources?.memory === undefined
         ? limits.defaultResources.memoryMiB
         : memoryMiB(request.resources.memory);
     if (cpus > limits.resources.cpus)
-        errors.push(`sandbox.resources.cpus asks for ${cpus}; this Tenant allows at most ${limits.resources.cpus}.`);
+        errors.push(`resources.cpus asks for ${cpus}; this Tenant allows at most ${limits.resources.cpus}.`);
     if (memory > limits.resources.memoryMiB)
-        errors.push(`sandbox.resources.memory asks for ${memory}MiB; this Tenant allows at most ${limits.resources.memoryMiB}MiB.`);
+        errors.push(`resources.memory asks for ${memory}MiB; this Tenant allows at most ${limits.resources.memoryMiB}MiB.`);
     if (errors.length > 0)
-        return { kind: "error", status: 400, errors };
-    const unique = [...new Set(allow)].sort();
-    const spec = {
-        ...(request.image === undefined ? {} : { image: request.image }),
-        network: { preset: "none", ...(unique.length > 0 ? { allow: unique } : {}) },
-        resources: { cpus, memory: `${memory}MiB` },
-        idle: limits.idle,
+        return { kind: "error", errors };
+    return {
+        kind: "recipe",
+        recipe: {
+            ...(request.image === undefined ? {} : { image: request.image }),
+            resources: { cpus, memory: `${memory}MiB` },
+            ...(request.storage === undefined ? {} : { storage: request.storage }),
+            network: { allowedHosts: [...new Set(allow)].sort() },
+            harness,
+            lifecycle: { ...lifecycle },
+            ...(pod && request.setup?.length ? { setup: request.setup.map((command) => ({ ...command })) } : {}),
+            ...(pod && request.files?.length ? { files: request.files.map((file) => ({ ...file })) } : {}),
+        },
+    };
+}
+/**
+ * The sandbox spec of a recipe: what the session's sandbox capability pins and the virtual
+ * workspace runs. Idle is the Environment's `lifecycle.idle`, else the Tenant's.
+ */
+export function sandboxSpecOf(recipe, tenantIdle) {
+    const allow = recipe.network?.allowedHosts ?? [];
+    return {
+        ...(recipe.image === undefined ? {} : { image: recipe.image }),
+        network: { preset: "none", ...(allow.length > 0 ? { allow: [...allow] } : {}) },
+        ...(recipe.resources === undefined ? {} : { resources: { ...recipe.resources } }),
+        idle: recipe.lifecycle.idle ?? tenantIdle,
+    };
+}
+/** The pod's spec of a recipe: its sandbox spec and its volume's size. */
+export function podSandboxSpecOf(recipe, tenantIdle) {
+    return {
+        ...sandboxSpecOf(recipe, tenantIdle),
+        ...(recipe.storage === undefined ? {} : { storage: recipe.storage }),
     };
-    return { kind: "sandbox", spec, source };
 }
 /** Whether `host` (a name or `*.suffix` pattern) is inside one of the ceiling's patterns. */
 export function withinCeiling(host, ceiling) {
@@ -69,14 +103,5 @@ export function sandboxConfigErrors(config) {
         errors.push("limits.defaultResources.cpus is above limits.resources.cpus.");
     if (limits.defaultResources.memoryMiB > limits.resources.memoryMiB)
         errors.push("limits.defaultResources.memory is above limits.resources.memory.");
-    if (config.default !== "none" && config.default !== "virtual") {
-        const resolved = resolveSandbox({
-            request: undefined,
-            config,
-            actingForSubject: false,
-        });
-        if (resolved.kind === "error")
-            errors.push(...resolved.errors.map((message) => `default: ${message}`));
-    }
     return errors;
 }

package/dist/sandbox/session-sandbox.js

@@ -102,7 +102,7 @@ function checked(original, sandboxed) {
         return {
             ok: false,
             message: clash
-                ? `'${original.id}' declares a tool named like a sandbox tool (bash, read, write, edit, grep, glob, save_artifact). Rename it, or open the session with sandbox: false.`
+                ? `'${original.id}' declares a tool named like a sandbox tool (bash, read, write, edit, grep, glob, save_artifact). Rename it, or open the session on no Environment or one of kind none.`
                 : `'${original.id}' cannot take this sandbox: ${[...new Set(issues)].join("; ")}`,
         };
     }

package/dist/sandbox/setup.d.ts

@@ -0,0 +1,61 @@
+import type { Environment, Tx } from "../store/types.js";
+import type { TenantContext } from "../tenant/context.js";
+import { SETUP_FAILED } from "./pods/lifecycle.js";
+export { SETUP_FAILED };
+/** What the engine runs on a new disk. */
+export interface SetupPlan {
+    /** The applied recipe's version: written into the volume's marker. */
+    readonly recipeVersion: number;
+    readonly commands: readonly {
+        readonly command: string;
+        readonly cwd: string;
+        readonly timeoutMs: number;
+    }[];
+    /** Each input file by its index into the recipe's `files`, and where it goes. */
+    readonly files: readonly {
+        readonly index: number;
+        readonly path: string;
+    }[];
+    /** Variables every command gets: secrets as the sentinel, plain values (R2c). */
+    readonly environment: Readonly<Record<string, string>>;
+}
+/** The setup of `recipe`, or undefined when it has neither commands nor files. */
+export declare function setupPlanOf(ctx: TenantContext, t: Tx, environment: Environment): Promise<SetupPlan | undefined>;
+/** What the engine reports after running a setup. */
+export interface SetupReport {
+    readonly status: "ok" | "failed";
+    /** The failed command's index into the plan's commands; absent for an input file. */
+    readonly index?: number;
+    readonly exitCode?: number;
+    /** The end of the failed command's output, or why an input file could not be copied. */
+    readonly output?: string;
+}
+export declare function parseSetupReport(value: unknown): SetupReport | undefined;
+/**
+ * Records a failed setup on Environment `id` held at host epoch `epoch` (the reporting engine's):
+ * the pod is `failed` with a reason that starts `setup:`, and `environment.failed` says which
+ * command failed and how. A report from an older host, or a success, changes nothing.
+ */
+export declare function recordSetup(ctx: TenantContext, id: string, epoch: number, report: SetupReport): Promise<void>;
+/** Whether the engine of `id` should run its setup again: the pod is no longer `failed`. */
+export declare function setupState(ctx: TenantContext, id: string): Promise<{
+    retry: boolean;
+    setup?: SetupPlan;
+}>;
+/** One input file's bytes, or a folder's listing (`path` absent). */
+export type SetupFile = {
+    readonly kind: "file";
+    readonly contentType: string;
+    readonly body: ReadableStream<Uint8Array>;
+} | {
+    readonly kind: "folder";
+    readonly entries: readonly {
+        readonly path: string;
+        readonly size: number;
+    }[];
+};
+/**
+ * Input file `index` of Environment `id`'s applied recipe: a file artifact's bytes, a folder's
+ * listing, or (with `path`) one of the folder's files. Undefined when there is no such file.
+ */
+export declare function setupFile(ctx: TenantContext, id: string, index: number, path: string | undefined): Promise<SetupFile | undefined>;