@nylorun/runtime 0.23.0-beta → 0.25.0-beta

package/dist/sandbox/resolve.js

@@ -1,50 +1,91 @@
+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 }, ...slotsOf(request) } };
+    }
     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 })) } : {}),
+            ...slotsOf(request),
+        },
+    };
+}
+/** The request's secret slots, when it declares any. */
+function slotsOf(request) {
+    return request.secrets !== undefined && Object.keys(request.secrets).length > 0
+        ? { secrets: structuredClone(request.secrets) }
+        : {};
+}
+/**
+ * The sandbox spec of a recipe: what a session's `runtime` block 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 +110,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/runtime-tools.d.ts

@@ -0,0 +1,9 @@
+import { type AgentManifest, type SandboxManifest } from "@nylorun/core/define";
+/**
+ * The session's sandbox spec when `toolName` is one of the sandbox tools the Runtime pinned on
+ * `manifest` (its `runtime` block); undefined for any other tool. A tool's name alone says whose
+ * it is: an author tool may not take a Runtime tool's name.
+ */
+export declare function sandboxToolSpec(manifest: AgentManifest | undefined, toolName: string | undefined): SandboxManifest | undefined;
+/** True when `toolName` is a tool the Runtime pinned on `manifest` (its `runtime.tools`). */
+export declare function isPinnedRuntimeTool(manifest: AgentManifest | undefined, toolName: string | undefined): boolean;

package/dist/sandbox/runtime-tools.js

@@ -0,0 +1,16 @@
+import { isSandboxToolName, runtimeToolOf, } from "@nylorun/core/define";
+/**
+ * The session's sandbox spec when `toolName` is one of the sandbox tools the Runtime pinned on
+ * `manifest` (its `runtime` block); undefined for any other tool. A tool's name alone says whose
+ * it is: an author tool may not take a Runtime tool's name.
+ */
+export function sandboxToolSpec(manifest, toolName) {
+    if (!toolName || !isSandboxToolName(toolName))
+        return undefined;
+    const sandbox = manifest?.runtime?.sandbox;
+    return sandbox !== undefined && runtimeToolOf(manifest, toolName) !== undefined ? sandbox : undefined;
+}
+/** True when `toolName` is a tool the Runtime pinned on `manifest` (its `runtime.tools`). */
+export function isPinnedRuntimeTool(manifest, toolName) {
+    return runtimeToolOf(manifest, toolName) !== undefined;
+}

package/dist/sandbox/session-sandbox.d.ts

@@ -7,12 +7,10 @@ export type SandboxedManifest = {
     readonly ok: false;
     readonly message: string;
 };
-/** The agent's manifest with the sandbox capability added, or why it cannot take one. */
-export declare function withSandboxCapability(manifest: AgentManifest, spec: SandboxManifest): SandboxedManifest;
+/** The agent's pinned manifest with the session's sandbox, or why it cannot take one. */
+export declare function withSandbox(manifest: AgentManifest, spec: SandboxManifest): SandboxedManifest;
 /**
  * The pinned manifest of an agent session without a sandbox: `read_artifact` for each agent of
- * the tree with a remote MCP server or an HTTP tool (R2b C11), and `nylorun.tools` for each with
- * a remote MCP server (R2b C10). Undefined when nothing is added, and the session pins its
- * definition as it is.
+ * the tree (R2b C11, protocol 12), and the skill tools for each with skills.
  */
-export declare function withPlatformTools(manifest: AgentManifest): SandboxedManifest | undefined;
+export declare function withRuntimeTools(manifest: AgentManifest): SandboxedManifest;

package/dist/sandbox/session-sandbox.js

@@ -1,124 +1,77 @@
 /**
- * Gives a session the sandbox chosen when it was opened, and the platform tools its agents
- * need. An agent session's pinned manifest is its definition plus:
+ * Gives a session the sandbox chosen when it was opened, and the Runtime tools its agents need.
+ * An agent session's pinned manifest is its definition with a `runtime` block
+ * (`runtimeManifestFor`) on each agent of the tree:
  *
- * - with a sandbox, the `nylorun.sandbox` capability (the six built-in tools, the sandbox
- *   instructions and the resolved spec) and the `nylorun.artifacts` capability
- *   (`save_artifact`), also added to each agent it uses as a tool, so the tree shares one spec.
- *   The sandbox's instructions name the agent's skills' folders (`/skills/<name>/`);
- * - for each agent of the tree with a remote MCP server or an HTTP tool, `read_artifact` in its
- *   `nylorun.artifacts` capability (R2b C11), with or without a sandbox: the Runtime stores a
- *   result of those tools too large to show as an artifact, and the model reads it in pages.
- *   An agent that declares a tool named `read_artifact` keeps its own, and sees previews only;
- * - for each agent of the tree with a remote MCP server, the `nylorun.tools` capability (R2b
- *   C10), empty: when the session defers some of the agent's MCP tools, its session tools put
- *   `tool_search` and `tool_call` there. An agent that declares either name defers nothing.
+ * - with a sandbox, the six sandbox tools, their instructions and the resolved spec, and
+ *   `save_artifact`, so files the agent makes reach the user (F8.1). The agents it uses as tools
+ *   get the same spec, so the tree shares one sandbox. The sandbox's instructions name the
+ *   agent's skills' folders (`/skills/<name>@<hash>/`);
+ * - with or without a sandbox, `read_artifact` (R2b C11, protocol 12): the Runtime stores a result
+ *   of an MCP or HTTP tool too large to show as an artifact, and the model reads it in pages; a
+ *   file of an earlier turn is a reference line the model reads again with it;
+ * - with skills, `load_skill`, `read_skill_resource` and the skill catalog.
  *
- * The definition in the registry never changes.
+ * `tool_search` and `tool_call` are not pinned: they are session tools, given per run when the
+ * session defers some MCP tools (R2b C10). An author tool may not take any of these names (the
+ * manifest schema refuses it), so a tool's name alone says whose it is. The definition in the
+ * registry never changes.
  */
 import { AgentManifestSchema } from "@nylorun/core/contracts";
-import { READ_ARTIFACT_TOOL, TOOL_CALL_TOOL, TOOL_SEARCH_TOOL, TOOLS_CAPABILITY_ID, artifactsCapabilityManifest, hashManifest, sandboxCapabilityManifest, toolsCapabilityManifest, } from "@nylorun/core/define";
-import { sandboxSpecOf } from "./share.js";
+import { hashManifest, runtimeManifestFor, } from "@nylorun/core/define";
 function isAgentManifest(value) {
     return (typeof value === "object" &&
         value !== null &&
         value.kind !== "workflow" &&
-        Array.isArray(value.capabilities));
+        typeof value.id === "string");
 }
-/** The names of the agent's own skills. */
-function skillNamesOf(manifest) {
-    return manifest.capabilities.flatMap((capability) => Object.keys(capability.skills ?? {})).sort();
-}
-/**
- * True when the agent itself declares a remote MCP server or an HTTP tool, whose results the
- * Runtime may store as artifacts (R2b C11), and no tool of its own is named `read_artifact`.
- */
-function readsStoredResults(manifest) {
-    const remote = manifest.capabilities.some((capability) => Object.keys(capability.mcpServers ?? {}).length > 0 ||
-        (capability.tools ?? []).some((tool) => tool.http !== undefined));
-    const taken = manifest.capabilities.some((capability) => (capability.tools ?? []).some((tool) => tool.name === READ_ARTIFACT_TOOL));
-    return remote && !taken;
-}
-/**
- * True when the agent itself declares a remote MCP server, some of whose tools the session may
- * defer (R2b C10), and names no tool `tool_search` or `tool_call` (it then keeps every tool in
- * its list).
- */
-function defersTools(manifest) {
-    const servers = manifest.capabilities.some((capability) => Object.keys(capability.mcpServers ?? {}).length > 0);
-    const taken = manifest.capabilities.some((capability) => capability.id === TOOLS_CAPABILITY_ID ||
-        (capability.tools ?? []).some((tool) => tool.name === TOOL_SEARCH_TOOL || tool.name === TOOL_CALL_TOOL));
-    return servers && !taken;
-}
-/** `manifest` with the session's capabilities added; the same object when none are. */
-function addCapabilities(manifest, spec) {
+/** `manifest` with its `runtime` block, and each agent it uses as a tool with its own. */
+function pinRuntime(manifest, spec) {
     let changed = false;
-    const capabilities = manifest.capabilities.map((capability) => {
-        if (capability.tools === undefined)
-            return capability;
-        let toolsChanged = false;
-        const tools = capability.tools.map((tool) => {
-            // Agents used as tools share the session's sandbox; flow agents used as tools run in
-            // linked sessions that inherit it. One that declares its own sandbox keeps it.
-            if (tool.agent === undefined || !isAgentManifest(tool.agent))
-                return tool;
-            const agent = addCapabilities(tool.agent, sandboxSpecOf(tool.agent) === undefined ? spec : undefined);
-            if (agent === tool.agent)
-                return tool;
-            toolsChanged = true;
-            return { ...tool, agent };
-        });
-        if (!toolsChanged)
-            return capability;
+    const tools = manifest.tools?.map((tool) => {
+        // Agents used as tools share the session's sandbox; flow agents used as tools run in linked
+        // sessions that inherit it.
+        if (tool.agent === undefined || !isAgentManifest(tool.agent))
+            return tool;
+        const agent = pinRuntime(tool.agent, spec);
+        if (agent === tool.agent)
+            return tool;
         changed = true;
-        return { ...capability, tools };
+        return { ...tool, agent };
+    });
+    const runtime = runtimeManifestFor(manifest, {
+        ...(spec === undefined ? {} : { sandbox: spec }),
+        save: spec !== undefined,
+        read: true,
     });
-    const save = spec !== undefined;
-    const read = readsStoredResults(manifest);
-    const defer = defersTools(manifest);
-    if (!save && !read && !defer && !changed)
+    if (runtime === undefined && !changed)
         return manifest;
     return {
         ...manifest,
-        // With a sandbox comes `save_artifact`, so files the agent makes reach the user (F8.1). The
-        // sandbox's instructions name where the agent's skills are (R2 M4).
-        capabilities: [
-            ...capabilities,
-            ...(spec === undefined
-                ? []
-                : [sandboxCapabilityManifest(spec, { skills: skillNamesOf(manifest) })]),
-            ...(save || read ? [artifactsCapabilityManifest({ save, read })] : []),
-            // Empty: when the session defers MCP tools, its tools put tool_search and tool_call here.
-            ...(defer ? [toolsCapabilityManifest()] : []),
-        ],
+        ...(changed ? { tools } : {}),
+        ...(runtime === undefined ? {} : { runtime }),
     };
 }
-/** `sandboxed` checked as a manifest, with its hash. */
-function checked(original, sandboxed) {
-    const parsed = AgentManifestSchema.safeParse(sandboxed);
+/** `pinned` checked as a manifest, with its hash. */
+function checked(original, pinned) {
+    const parsed = AgentManifestSchema.safeParse(pinned);
     if (!parsed.success) {
         const issues = parsed.error.issues.map((issue) => issue.message);
-        const clash = issues.some((message) => message === "Tool names must be unique");
         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}' cannot take this sandbox: ${[...new Set(issues)].join("; ")}`,
+            message: `'${original.id}' cannot take the Runtime's tools: ${[...new Set(issues)].join("; ")}`,
         };
     }
-    return { ok: true, manifest: sandboxed, manifestHash: hashManifest(sandboxed) };
+    return { ok: true, manifest: pinned, manifestHash: hashManifest(pinned) };
 }
-/** The agent's manifest with the sandbox capability added, or why it cannot take one. */
-export function withSandboxCapability(manifest, spec) {
-    return checked(manifest, addCapabilities(manifest, spec));
+/** The agent's pinned manifest with the session's sandbox, or why it cannot take one. */
+export function withSandbox(manifest, spec) {
+    return checked(manifest, pinRuntime(manifest, spec));
 }
 /**
  * The pinned manifest of an agent session without a sandbox: `read_artifact` for each agent of
- * the tree with a remote MCP server or an HTTP tool (R2b C11), and `nylorun.tools` for each with
- * a remote MCP server (R2b C10). Undefined when nothing is added, and the session pins its
- * definition as it is.
+ * the tree (R2b C11, protocol 12), and the skill tools for each with skills.
  */
-export function withPlatformTools(manifest) {
-    const pinned = addCapabilities(manifest, undefined);
-    return pinned === manifest ? undefined : checked(manifest, pinned);
+export function withRuntimeTools(manifest) {
+    return checked(manifest, pinRuntime(manifest, undefined));
 }

package/dist/sandbox/setup.d.ts

@@ -0,0 +1,64 @@
+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`, and
+ * the disk version a fork starts from is written (Q17).
+ */
+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>;

package/dist/sandbox/setup.js

@@ -0,0 +1,160 @@
+import { parseSandboxDuration } from "@nylorun/core/define";
+import { contentKey, readManifest } from "../artifacts/folders.js";
+import { contentTypeFor } from "../artifacts/media-types.js";
+import { definitionFileKey } from "../tenant/definition-files.js";
+import { SETUP_FAILED } from "./pods/lifecycle.js";
+export { SETUP_FAILED };
+/** The most of a failed command's output kept in its event and reason. */
+const OUTPUT_TAIL = 4 * 1024;
+/** A command's timeout when the recipe gives none. */
+const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+/** The setup of `recipe`, or undefined when it has neither commands nor files. */
+export async function setupPlanOf(ctx, t, environment) {
+    const recipe = environment.applied;
+    if (!recipe.setup?.length && !recipe.files?.length)
+        return undefined;
+    return {
+        recipeVersion: environment.appliedVersion,
+        commands: (recipe.setup ?? []).map((command) => ({
+            command: command.command,
+            cwd: command.cwd ?? "/workspace",
+            timeoutMs: (command.timeout && parseSandboxDuration(command.timeout)) || DEFAULT_TIMEOUT_MS,
+        })),
+        files: (recipe.files ?? []).map((file, index) => ({ index, path: file.path })),
+        environment: await ctx.vault.environmentVariables(t, environment.id),
+    };
+}
+export function parseSetupReport(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const report = value;
+    if (report.status !== "ok" && report.status !== "failed")
+        return undefined;
+    const index = typeof report.index === "number" && Number.isInteger(report.index) ? report.index : undefined;
+    const exitCode = typeof report.exitCode === "number" && Number.isInteger(report.exitCode) ? report.exitCode : undefined;
+    const output = typeof report.output === "string" ? report.output.slice(-OUTPUT_TAIL) : undefined;
+    return {
+        status: report.status,
+        ...(index === undefined ? {} : { index }),
+        ...(exitCode === undefined ? {} : { exitCode }),
+        ...(output === undefined ? {} : { output }),
+    };
+}
+/**
+ * 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 async function recordSetup(ctx, id, epoch, report) {
+    await ctx.store.tx(async (t) => {
+        const environment = await t.environment(id, { lock: true });
+        const pod = environment?.pod;
+        if (!environment || !pod || pod.hostEpoch !== epoch || pod.desired !== "running")
+            return;
+        if (report.status === "ok") {
+            // A fork's setup ran on its written disk (Q17): its turns may start.
+            if (environment.diskSeed?.setup && environment.diskSeed.written)
+                await t.updateEnvironment(id, { diskSeed: null }, new Date().toISOString());
+            return;
+        }
+        const command = report.index === undefined ? undefined : environment.applied.setup?.[report.index];
+        const what = command === undefined ? "copying the input files failed" : `command ${report.index + 1} (${command.command.slice(0, 80)}) exited ${report.exitCode ?? "abnormally"}`;
+        const tail = (report.output ?? "").trim().slice(-500);
+        const reason = `${SETUP_FAILED} ${what}${tail ? `: ${tail}` : ""}`;
+        await t.updateEnvironmentPod(id, { observed: "failed", reason }, new Date().toISOString());
+        await t.environmentEvent(id, "environment.failed", {
+            reason,
+            setup: {
+                ...(report.index === undefined ? {} : { index: report.index }),
+                ...(report.exitCode === undefined ? {} : { exitCode: report.exitCode }),
+                output: report.output ?? "",
+            },
+        });
+    });
+    if (report.status === "failed")
+        ctx.config.logger.warn("environment setup failed", { environmentId: id, index: report.index, exitCode: report.exitCode });
+    else
+        ctx.config.logger.info("environment setup done", { environmentId: id });
+}
+/**
+ * Whether the engine of `id` should run its setup (again): the pod is no longer `failed`, and
+ * the disk version a fork starts from is written (Q17).
+ */
+export async function setupState(ctx, id) {
+    return ctx.store.tx(async (t) => {
+        const environment = await t.environment(id);
+        const pod = environment?.pod;
+        if (!environment || !pod)
+            return { retry: false };
+        if (pod.observed === "failed")
+            return { retry: false };
+        if (environment.diskSeed && !environment.diskSeed.written)
+            return { retry: false };
+        const setup = await setupPlanOf(ctx, t, environment);
+        return { retry: true, ...(setup ? { setup } : {}) };
+    });
+}
+/**
+ * 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 async function setupFile(ctx, id, index, path) {
+    const entry = await ctx.store.tx(async (t) => {
+        const environment = await t.environment(id);
+        return environment?.applied.files?.[index];
+    });
+    if (!entry)
+        return undefined;
+    if ("files" in entry) {
+        // Files by hash (Q6): a folder of definition files.
+        if (path === undefined) {
+            const sizes = await ctx.store.tx(async (t) => {
+                const found = new Map();
+                for (const sha256 of new Set(Object.values(entry.files))) {
+                    const row = await t.definitionFile(sha256);
+                    if (row)
+                        found.set(sha256, row.size);
+                }
+                return found;
+            });
+            return {
+                kind: "folder",
+                entries: Object.entries(entry.files).map(([item, sha256]) => ({ path: item, size: sizes.get(sha256) ?? 0 })),
+            };
+        }
+        const sha256 = Object.hasOwn(entry.files, path) ? entry.files[path] : undefined;
+        if (sha256 === undefined)
+            return undefined;
+        const got = await ctx.blobs.get(definitionFileKey(sha256));
+        return got ? { kind: "file", contentType: contentTypeFor(path), body: got.body } : undefined;
+    }
+    const file = entry;
+    const found = await ctx.store.tx(async (t) => {
+        const artifact = await t.artifact(file.artifactId);
+        if (!artifact || artifact.sessionId !== null)
+            return undefined;
+        const version = await t.artifactVersion(file.artifactId, file.version);
+        return version ? { artifact, version } : undefined;
+    });
+    if (!found)
+        return undefined;
+    if (found.artifact.kind === "file") {
+        if (path !== undefined)
+            return undefined;
+        const got = await ctx.blobs.get(found.version.blobKey);
+        return got ? { kind: "file", contentType: found.version.contentType ?? found.artifact.contentType, body: got.body } : undefined;
+    }
+    const manifest = await readManifest(ctx.blobs, found.version);
+    if (path === undefined)
+        return {
+            kind: "folder",
+            entries: manifest.entries
+                .filter((entry) => entry.type === undefined)
+                .map((entry) => ({ path: entry.path, size: entry.size })),
+        };
+    const listed = manifest.entries.find((item) => item.path === path && item.type === undefined);
+    if (!listed)
+        return undefined;
+    const got = await ctx.blobs.get(contentKey(listed.sha256));
+    return got ? { kind: "file", contentType: listed.contentType, body: got.body } : undefined;
+}