@nylorun/runtime 0.23.0-beta → 0.25.0-beta

package/dist/sandbox/join.js

@@ -32,7 +32,9 @@
  * which check failed.
  */
 import { createHash, timingSafeEqual } from "node:crypto";
-import { isSandboxId } from "@nylorun/core/contracts";
+import { isEnvironmentId } from "@nylorun/core/contracts";
+import { recoverLostVolume, runPendingSeed } from "../artifacts/disk.js";
+import { recordSetup, setupFile, setupPlanOf, setupState, } from "./setup.js";
 import { mintHostTokens, staleHost, verifyHostToken, } from "../tenant/host-token.js";
 /** A refused join, renewal or host connection. */
 export class HostAuthError extends Error {
@@ -84,7 +86,7 @@ export function hostAuthority(ctx) {
     return {
         async join(request) {
             const { sandboxId, podUid, joinToken, volumeId } = request;
-            if (!isSandboxId(sandboxId) ||
+            if (!isEnvironmentId(sandboxId) ||
                 typeof podUid !== "string" ||
                 !POD_UID.test(podUid) ||
                 typeof joinToken !== "string" ||
@@ -107,11 +109,11 @@ export function hostAuthority(ctx) {
                 // A pod being stopped joins nothing: its sandbox runs again only when asked to.
                 if (pod.desired !== "running")
                     return refuse("the sandbox is stopped");
-                if (pod.observed === "lost" || pod.observed === "expired")
-                    return refuse(`the sandbox is ${pod.observed}`);
+                if (pod.observed === "lost")
+                    return refuse("the sandbox is lost");
                 return pod;
             };
-            const readRow = () => ctx.store.tx((t) => t.sandboxResource(sandboxId));
+            const readRow = () => ctx.store.tx((t) => t.environment(sandboxId));
             const before = usable(await readRow());
             let current;
             try {
@@ -123,7 +125,7 @@ export function hostAuthority(ctx) {
             if (current !== podUid)
                 refuse("the pod is not the sandbox's current pod");
             const joined = await ctx.store.tx(async (t) => {
-                const row = await t.sandboxResource(sandboxId, { lock: true });
+                const row = await t.environment(sandboxId, { lock: true });
                 const pod = usable(row);
                 if (pod.k8sName !== before.k8sName)
                     refuse("the sandbox was reset during the join");
@@ -132,14 +134,14 @@ export function hostAuthority(ctx) {
                 if (pod.volumeId !== undefined && volumeId !== pod.volumeId) {
                     // A new, empty volume under the same Sandbox: the sandbox's files are gone.
                     const reason = "The sandbox's volume was replaced: its files are gone";
-                    await t.updateSandboxPod(sandboxId, { observed: "lost", reason, hostEpoch: epoch }, now);
-                    await t.sandboxEvent(sandboxId, "sandbox.lost", { reason });
+                    await t.updateEnvironmentPod(sandboxId, { observed: "lost", reason, hostEpoch: epoch }, now);
+                    await t.environmentEvent(sandboxId, "environment.lost", { reason });
                     // Its Sandbox is deleted; only a reset brings the sandbox back.
                     await t.signal({ type: "host.revoked", sandboxId, epoch });
                     await t.signalSandbox(sandboxId, { kind: "reconcile" });
                     return { lost: epoch };
                 }
-                await t.updateSandboxPod(sandboxId, {
+                await t.updateEnvironmentPod(sandboxId, {
                     hostEpoch: epoch,
                     podUid,
                     ...(pod.volumeId === undefined && volumeId !== undefined ? { volumeId } : {}),
@@ -147,23 +149,52 @@ export function hostAuthority(ctx) {
                 }, now);
                 if (pod.podUid !== podUid) {
                     if (pod.podUid !== undefined)
-                        await t.sandboxEvent(sandboxId, "sandbox.relaunched", { hostEpoch: epoch });
+                        await t.environmentEvent(sandboxId, "environment.relaunched", { hostEpoch: epoch });
                     else
-                        await t.sandboxEvent(sandboxId, "sandbox.running", { hostEpoch: epoch });
+                        await t.environmentEvent(sandboxId, "environment.running", { hostEpoch: epoch });
                 }
                 // The previous host's connection (an older epoch) serves nothing more, on any process.
                 await t.signal({ type: "host.revoked", sandboxId, epoch });
-                return epoch;
+                return {
+                    epoch,
+                    setup: row ? await setupPlanOf(ctx, t, row) : undefined,
+                    seeded: row?.diskSeed !== undefined,
+                    afterSeed: row?.diskSeed?.setup === true,
+                };
             });
-            if (typeof joined === "object")
+            if ("lost" in joined) {
+                // With a disk version, a new volume seeded from the latest one (R2d step 3).
+                void recoverLostVolume(ctx, sandboxId).catch(() => undefined);
                 return refuse("the volume was replaced: the sandbox is lost");
-            ctx.config.logger.info("sandbox host joined", { sandboxId, epoch: joined });
-            return answerOf(await mintHostTokens(ctx, { sandboxId, epoch: joined, podUid }), await ctx.keys.egressCa());
+            }
+            ctx.config.logger.info("sandbox host joined", { sandboxId, epoch: joined.epoch });
+            const answer = answerOf(await mintHostTokens(ctx, { sandboxId, epoch: joined.epoch, podUid }), await ctx.keys.egressCa());
+            if (joined.seeded) {
+                // The engine connects next; the seed waits for it, then writes the version.
+                void runPendingSeed(ctx, sandboxId);
+                // A fork onto other setup (Q17): the engine runs it once the version is written.
+                if (joined.afterSeed)
+                    return { ...answer, seeded: true, afterSeed: true, ...(joined.setup ? { setup: joined.setup } : {}) };
+                return { ...answer, seeded: true };
+            }
+            return joined.setup ? { ...answer, setup: joined.setup } : answer;
         },
         async renew(hostToken) {
             const claims = await verified(hostToken);
             return answerOf(await mintHostTokens(ctx, claims), await ctx.keys.egressCa());
         },
         verify: verified,
+        async setup(hostToken) {
+            const claims = await verified(hostToken);
+            return setupState(ctx, claims.sandboxId);
+        },
+        async reportSetup(hostToken, report) {
+            const claims = await verified(hostToken);
+            await recordSetup(ctx, claims.sandboxId, claims.epoch, report);
+        },
+        async setupFile(hostToken, index, path) {
+            const claims = await verified(hostToken);
+            return setupFile(ctx, claims.sandboxId, index, path);
+        },
     };
 }

package/dist/sandbox/manager.d.ts

@@ -2,8 +2,11 @@
  * Sandbox Manager: owns sandbox lifecycle for the Runtime. One workspace per sandbox resource
  * (`sandbox: { id }`, keyed by the sandbox id), or per owning session for a sandbox chosen
  * inline or by the Tenant default (keyed by the session id); created on the first sandbox tool
- * call, stopped after its idle timeout, reattached on the next call. Commands against one
- * workspace run one at a time, whichever session sends them.
+ * call, stopped after its idle timeout, reattached on the next call. Each session's calls on a
+ * workspace run in the order it sends them, and different sessions' calls run at the same time
+ * (D66): the sessions of one Environment run their turns at once. Opening, stopping and removing
+ * a workspace run alone: a stop or removal waits for the calls running, and calls that come after
+ * it wait for it.
  *
  * The manager keeps no timers and reaches no store: it keeps its compute records through a
  * `SandboxRecords` port (the Tenant's `sandboxes` table in core's process, a file in a harness's)
@@ -12,17 +15,18 @@
  * (after a restart); `reconcile` removes workspaces whose owner is gone. `sweep` does both, the
  * reconcile once per process, as the Tenant sweep does in core's process.
  *
- * A session's skills (track R2 M4) are mounted on its workspace, read-only under
- * `/skills/<name>/`, before the first call that opens it (`skills.ts`); their bytes come
- * through the `definitionFile` port.
+ * A session's skills (track R2 M4) are mounted on its workspace, read-only, one folder per
+ * version (`/skills/<name>@<hash>/`, D66), before the first call that needs them (`skills.ts`);
+ * their bytes come through the `definitionFile` port.
  */
 import type { EventPayload } from "@nylorun/core/contracts";
-import { type AgentManifest, type CapabilityManifest, type SandboxToolName } from "@nylorun/core/define";
+import { type AgentManifest, type SandboxManifest, type SandboxToolName } from "@nylorun/core/define";
 import { type SandboxRecord, type SandboxRecords } from "./records.js";
 import { type SandboxSelection, type SandboxSelectionReport } from "./select.js";
+import { type DiskAnswer, type DiskOp } from "./disk-fs.js";
 import { type SandboxToolOutcome } from "./tools.js";
 import { type SandboxBackend, type SandboxListing } from "./types.js";
-export { sandboxCapabilityOf } from "./capability.js";
+export { sandboxToolSpec } from "./runtime-tools.js";
 export type { SandboxRecord, SandboxRecords, SandboxState } from "./records.js";
 export interface SandboxSessionRef {
     /** The session whose log records the workspace's events: the owning session. */
@@ -33,7 +37,12 @@ export interface SandboxSessionRef {
      * The sandbox resource the owning session is attached to. Its workspace is keyed by this id,
      * so every session attached to it shares the files; absent, the workspace is the session's.
      */
-    readonly sandboxId?: string;
+    readonly environmentId?: string;
+    /**
+     * For a pod Environment: the host epoch it is at, so the call reaches a host that joined at
+     * that epoch or later, never one a restore or a lost volume retired.
+     */
+    readonly hostEpoch?: number;
     /** Variables every command of the call gets (R2c): secret names set to the sentinel, plain values. */
     readonly environment?: Readonly<Record<string, string>>;
     /**
@@ -55,7 +64,7 @@ export interface SandboxSweepOptions {
     /** Whether a session still exists; sandboxes of deleted sessions are removed. */
     readonly sessionExists: (sessionId: string) => boolean | Promise<boolean>;
     /** Whether a sandbox resource still exists. Default: every one does. */
-    readonly sandboxExists?: (sandboxId: string) => boolean | Promise<boolean>;
+    readonly sandboxExists?: (environmentId: string) => boolean | Promise<boolean>;
 }
 export interface SandboxManagerOptions {
     /** Distinguishes this Runtime's sandboxes from other Runtimes on the same machine: the Tenant id. */
@@ -77,7 +86,7 @@ export interface SandboxManagerOptions {
     readonly emit: <T extends SandboxEventType>(sessionId: string, turnId: string | null, type: T, payload: EventPayload<T>, meta: SandboxEventMeta) => void | Promise<void>;
 }
 /** The session events a sandbox writes. */
-export type SandboxEventType = "sandbox.state" | "sandbox.exec";
+export type SandboxEventType = "environment.state" | "environment.exec";
 export declare class SandboxManager {
     private readonly options;
     private selection?;
@@ -104,19 +113,28 @@ export declare class SandboxManager {
     /** Whether any sandbox was ever recorded, so startup can skip probing for agents without one. */
     hasRecords(): Promise<boolean>;
     keyOf(sessionId: string): string;
-    /** The workspace key of sandbox resource `sandboxId` (`sandboxWorkspaceKey`). */
-    sandboxKeyOf(sandboxId: string): string;
+    /** The workspace key of sandbox resource `environmentId` (`sandboxWorkspaceKey`). */
+    sandboxKeyOf(environmentId: string): string;
     private keyFor;
     report(): Promise<SandboxSelectionReport & {
         readonly defaultImage: string;
     }>;
-    run(session: SandboxSessionRef, capability: CapabilityManifest, toolName: SandboxToolName, input: unknown, signal: AbortSignal): Promise<SandboxToolOutcome>;
+    run(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, toolName: SandboxToolName, input: unknown, signal: AbortSignal): Promise<SandboxToolOutcome>;
+    /**
+     * Runs `call` in session `sessionId`'s queue on `live`: after its earlier calls, and after any
+     * stop or removal pending, beside other sessions' calls (D66).
+     */
+    private inLane;
+    /** Runs `step` on `live` alone: after the calls running, before the calls that come after it. */
+    private alone;
+    /** The workspace's handle, opened once for the calls that need it at the same time. */
+    private handleOf;
     /**
      * The bytes of one file in the session's sandbox, for `save_artifact` (F8.1), in the same queue
      * as its tool calls: `missing` when there is no such file, a failed outcome when the sandbox
      * cannot open or the file is larger than `maxBytes`. Relative paths resolve in the workspace.
      */
-    readBytes(session: SandboxSessionRef, capability: CapabilityManifest, path: string, maxBytes: number, signal: AbortSignal): Promise<{
+    readBytes(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, path: string, maxBytes: number, signal: AbortSignal): Promise<{
         kind: "read";
         path: string;
         bytes: Uint8Array;
@@ -131,7 +149,7 @@ export declare class SandboxManager {
      * the same queue as its tool calls. `missing` when the sandbox was never created (nothing is
      * started to look) or `dir` is not a directory. Relative paths resolve in the workspace.
      */
-    listFiles(session: SandboxSessionRef, capability: CapabilityManifest, dir: string, maxEntries: number, signal: AbortSignal): Promise<{
+    listFiles(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, dir: string, maxEntries: number, signal: AbortSignal): Promise<{
         kind: "listed";
         path: string;
         listing: SandboxListing;
@@ -141,6 +159,13 @@ export declare class SandboxManager {
     } | Extract<SandboxToolOutcome, {
         kind: "failed";
     }>>;
+    /**
+     * One operation on the disk of the session's sandbox (R2d step 3, `sandbox/disk-fs.ts`), in the
+     * same queue as its tool calls, starting it first when it is stopped.
+     */
+    disk(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, op: DiskOp, signal: AbortSignal): Promise<DiskAnswer | Extract<SandboxToolOutcome, {
+        kind: "failed";
+    }>>;
     /** Runs `use` on the session's sandbox in its queue, starting it first when it is stopped. */
     private withHandle;
     /** The session's live sandbox entry and spec, or why it cannot run here. */
@@ -148,9 +173,10 @@ export declare class SandboxManager {
     private execute;
     private executeOpen;
     /**
-     * Mounts the session's skills the workspace does not hold as they are: on a handle just opened
-     * all of them, later only those another session brought or changed. A failed outcome when
-     * one cannot be mounted; nothing is marked mounted then, so the next call tries again.
+     * Mounts the skill folders the session needs that the workspace does not hold (D66): on a
+     * handle just opened all of them, later only versions another session has not mounted. Calls
+     * that need one folder at once share its mount. A failed outcome when one cannot be mounted;
+     * the folder is not marked mounted then, so the next call tries again.
      */
     private mountSkills;
     private open;
@@ -159,16 +185,16 @@ export declare class SandboxManager {
     /** The sandbox record for a session, if one was ever created. */
     status(sessionId: string): Promise<SandboxRecord | undefined>;
     /**
-     * Deletes sandbox resource `sandboxId`'s workspace, its files and its compute record, after
+     * Deletes sandbox resource `environmentId`'s workspace, its files and its compute record, after
      * any command queued on it. Called once the resource is deleted.
      */
-    removeSandbox(sandboxId: string): Promise<void>;
+    removeSandbox(environmentId: string): Promise<void>;
     /** Deletes the workspace `key`, its files and its record, after any command queued on it. */
     remove(key: string): Promise<void>;
     /**
      * Delete workspaces this Runtime owns whose owner is gone: a session's when `sessionExists`
      * says the session is gone, a sandbox resource's when `sandboxExists` says the resource is.
      */
-    reconcile(sessionExists: (sessionId: string) => boolean | Promise<boolean>, sandboxExists: (sandboxId: string) => boolean | Promise<boolean>): Promise<void>;
+    reconcile(sessionExists: (sessionId: string) => boolean | Promise<boolean>, sandboxExists: (environmentId: string) => boolean | Promise<boolean>): Promise<void>;
     close(): Promise<void>;
 }