@claxedo/sandbox-manager 0.10.0 → 0.10.2

package/dist/index.mjs

@@ -314,7 +314,7 @@ function isPrivateIpAddress(ip) {
     return isPrivateIpv4(embedded);
   return false;
 }
-var sandboxCheckpointUnusableCauses = ["expired", "runtime_outdated", "runtime_modified", "not_restorable"];
+var sandboxCheckpointUnusableCauses = ["expired", "runtime_modified", "not_restorable"];
 function isSandboxCheckpointUnusableCause(value) {
   return sandboxCheckpointUnusableCauses.some((cause) => cause === value);
 }
@@ -378,6 +378,17 @@ var SandboxRuntimeBootError = class extends Error {
     this.name = "SandboxRuntimeBootError";
   }
 };
+function isSandboxImageDownloadFailure(err) {
+  return err instanceof Error && "imageDownloadFailed" in err && err.imageDownloadFailed === true;
+}
+var SandboxImageDownloadError = class extends Error {
+  imageDownloadFailed = true;
+  constructor(reason) {
+    super(reason);
+    this.name = "SandboxImageDownloadError";
+  }
+};
+var SANDBOX_UPDATE_DOWNLOAD_INTERRUPTED = "update_download_interrupted";
 function isSandboxCheckpointUnusable(err) {
   return !!err && typeof err === "object" && isSandboxCheckpointUnusableCause(err.checkpointUnusable);
 }
@@ -516,7 +527,8 @@ var SANDBOX_RUNTIME_UNHEALTHY = "runtime_unhealthy";
 var SANDBOX_RETRY_CAP_EXCEEDED = "runtime_retry_cap_exceeded";
 var CODED_REASONS = /* @__PURE__ */ new Map([
   [SANDBOX_RUNTIME_UNHEALTHY, "The workspace machine stopped answering."],
-  [SANDBOX_RETRY_CAP_EXCEEDED, "Several tries in a row failed; try again later."]
+  [SANDBOX_RETRY_CAP_EXCEEDED, "Several tries in a row failed; try again later."],
+  [SANDBOX_UPDATE_DOWNLOAD_INTERRUPTED, "The update couldn't finish downloading; your workspace is still running. Try again."]
 ]);
 function firstLine(text) {
   return text.split("\n", 1)[0]?.trim() ?? text;
@@ -607,11 +619,19 @@ var PUBLIC_API_ERRORS = {
   enrollment_paused: { status: 403, message: "enrollment_paused" },
   enrollment_owner_ineligible: { status: 403, message: "enrollment_owner_ineligible" },
   enrollment_key_version_mismatch: { status: 403, message: "enrollment_key_version_mismatch" },
+  enrollment_denied: { status: 403, message: "enrollment_denied" },
+  enrollment_approval_expired: { status: 403, message: "enrollment_approval_expired" },
+  enrollment_awaiting_approval: { status: 403, message: "enrollment_awaiting_approval" },
   invitation_invalid: { status: 403, message: "invitation_invalid" },
   invitation_expired: { status: 410, message: "invitation_expired" },
   invitation_revoked: { status: 410, message: "invitation_revoked" },
   invitation_redeemed: { status: 409, message: "invitation_redeemed" },
   invitation_host_conflict: { status: 409, message: "invitation_host_conflict" },
+  pairing_invalid: { status: 403, message: "pairing_invalid" },
+  pairing_expired: { status: 410, message: "pairing_expired" },
+  pairing_used: { status: 409, message: "pairing_used" },
+  pairing_owner_signed_out: { status: 410, message: "pairing_owner_signed_out" },
+  pairing_decided: { status: 409, message: "pairing_decided" },
   enrollment_generation_superseded: { status: 409, message: "enrollment_generation_superseded" },
   host_assignment_outside_scope: { status: 400, message: "host_assignment_outside_scope" },
   host_sealing_key_undeclared: { status: 409, message: "host_sealing_key_undeclared" },
@@ -865,6 +885,51 @@ async function refusedReason(leaseStore, workspaceId, epoch) {
   return "runtime_lease_not_serving";
 }
 
+// src/driver-ensure-input.ts
+function sandboxId(driver, workspaceId) {
+  return `${driver}-${workspaceId}`;
+}
+function leaseHostId(driver, workspaceId, lease, managerInput) {
+  return managerInput?.hostId ?? lease.hostId ?? sandboxId(driver.id, workspaceId);
+}
+function ensureHostInput(input) {
+  const egress = sandboxEgressDisposition(input.driver.metadata.egressControl, input.managerInput?.net);
+  const labels = {
+    app: input.appLabel,
+    workspaceId: input.workspaceId,
+    epoch: String(input.lease.epoch),
+    homeRegion: input.homeRegion,
+    ...input.managerInput?.labels
+  };
+  return {
+    workspaceId: input.workspaceId,
+    hostId: leaseHostId(input.driver, input.workspaceId, input.lease, input.managerInput),
+    homeRegion: input.homeRegion,
+    epoch: input.lease.epoch,
+    labels,
+    bootSource: input.managerInput?.bootSource ?? (input.lease.checkpoint && input.lease.status !== "ready" && input.driver.metadata.persistence.resume === "replacement-restore" ? { kind: "driver-snapshot", snapshotId: input.lease.checkpoint.providerReference } : { kind: "default" }),
+    workspaceRoot: input.managerInput?.workspaceRoot ?? "/workspace",
+    runtimeCwd: input.managerInput?.runtimeCwd,
+    workspaceRuntimePort: input.managerInput?.workspaceRuntimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT,
+    env: { ...input.managerInput?.env, ...input.leaseEnv },
+    // Brokered secrets ride their own channel — NEVER merged into labels or env.
+    // Presence of the key, not its length, is the signal: `[]` is the caller
+    // withdrawing every brokered secret, and dropping it would reach the driver
+    // as "preserve what you have".
+    ...input.managerInput?.secrets ? { secrets: input.managerInput.secrets } : {},
+    source: input.managerInput?.source,
+    ...input.managerInput?.updateImage ? { updateImage: true } : {},
+    ...input.lease.machineClass ?? input.managerInput?.machineClass ? { machineClass: input.lease.machineClass ?? input.managerInput?.machineClass } : {},
+    exposure: input.managerInput?.exposure ?? (input.driver.metadata.targetAccess === "loopback" ? { kind: "loopback" } : { kind: "relay" }),
+    // Withheld, never downgraded: `undefined` here is the same shape a caller
+    // that asked for no containment produces, so the throwing drivers take
+    // their allow-all path and their throws stay intact for anyone who hands
+    // them a policy directly.
+    ...egress.action === "enforce" && input.managerInput?.net ? { net: sandboxNetworkPolicyWithBrokeredHosts(input.managerInput.net, input.managerInput.secrets) } : {},
+    snapshot: input.managerInput?.snapshot
+  };
+}
+
 // src/egress-warnings.ts
 function egressUnenforcedMessage(input) {
   const scope = input.workspaceId ? `workspace ${input.workspaceId}` : "every sandbox it provisions";
@@ -997,13 +1062,15 @@ function createSandboxStartRecorder(options) {
      * lease as it ends, so a poller reading the lease mid-boot sees how far the
      * start has come. `opened` writes the epoch's `lease_decision` before the
      * driver runs, so a stop that lands mid-boot finds the boot it ends on the
-     * row. A serving lease is not starting. An epoch acquired with a start it
-     * continues has that start and no phase yet; one acquired without begins
-     * its own here.
+     * row. A serving lease is not starting, unless the step is a person's
+     * update, which is a start of its own on the same epoch. An epoch acquired
+     * with a start it continues has that start and no phase yet; one acquired
+     * without begins its own here.
      */
     observe(lease, input) {
-      if (lease.status === "ready") return void 0;
-      let progress = lease.start ?? { requestedAt: input.enteredAt, startedAt: input.enteredAt, bootMode: input.bootMode, markedAt: input.enteredAt, phases: [] };
+      if (lease.status === "ready" && !input.update) return void 0;
+      const begun = { requestedAt: input.enteredAt, startedAt: input.enteredAt, bootMode: input.bootMode, markedAt: input.enteredAt, phases: [] };
+      let progress = lease.status === "ready" ? begun : lease.start ?? begun;
       const ended = [];
       let markedAt = progress.markedAt;
       const mark = (phase) => {
@@ -1135,48 +1202,6 @@ var WORKSPACE_RUNTIME_PUBLIC_ENV_KEYS = /* @__PURE__ */ new Set([
 
 // src/manager.ts
 var DEFAULT_APP_LABEL = "claxedo";
-function sandboxId(driver, workspaceId) {
-  return `${driver}-${workspaceId}`;
-}
-function leaseHostId(driver, workspaceId, lease, managerInput) {
-  return managerInput?.hostId ?? lease.hostId ?? sandboxId(driver.id, workspaceId);
-}
-function ensureHostInput(input) {
-  const egress = sandboxEgressDisposition(input.driver.metadata.egressControl, input.managerInput?.net);
-  const labels = {
-    app: input.appLabel,
-    workspaceId: input.workspaceId,
-    epoch: String(input.lease.epoch),
-    homeRegion: input.homeRegion,
-    ...input.managerInput?.labels
-  };
-  return {
-    workspaceId: input.workspaceId,
-    hostId: leaseHostId(input.driver, input.workspaceId, input.lease, input.managerInput),
-    homeRegion: input.homeRegion,
-    epoch: input.lease.epoch,
-    labels,
-    bootSource: input.managerInput?.bootSource ?? (input.lease.checkpoint && input.lease.status !== "ready" && input.driver.metadata.persistence.resume === "replacement-restore" ? { kind: "driver-snapshot", snapshotId: input.lease.checkpoint.providerReference } : { kind: "default" }),
-    workspaceRoot: input.managerInput?.workspaceRoot ?? "/workspace",
-    runtimeCwd: input.managerInput?.runtimeCwd,
-    workspaceRuntimePort: input.managerInput?.workspaceRuntimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT,
-    env: { ...input.managerInput?.env, ...input.leaseEnv },
-    // Brokered secrets ride their own channel — NEVER merged into labels or env.
-    // Presence of the key, not its length, is the signal: `[]` is the caller
-    // withdrawing every brokered secret, and dropping it would reach the driver
-    // as "preserve what you have".
-    ...input.managerInput?.secrets ? { secrets: input.managerInput.secrets } : {},
-    source: input.managerInput?.source,
-    ...input.lease.machineClass ?? input.managerInput?.machineClass ? { machineClass: input.lease.machineClass ?? input.managerInput?.machineClass } : {},
-    exposure: input.managerInput?.exposure ?? (input.driver.metadata.targetAccess === "loopback" ? { kind: "loopback" } : { kind: "relay" }),
-    // Withheld, never downgraded: `undefined` here is the same shape a caller
-    // that asked for no containment produces, so the throwing drivers take
-    // their allow-all path and their throws stay intact for anyone who hands
-    // them a policy directly.
-    ...egress.action === "enforce" && input.managerInput?.net ? { net: sandboxNetworkPolicyWithBrokeredHosts(input.managerInput.net, input.managerInput.secrets) } : {},
-    snapshot: input.managerInput?.snapshot
-  };
-}
 function createSandboxManager(options) {
   const persistence = validateSandboxPersistenceCapabilities(options.driver.metadata.persistence);
   if (!persistence.valid) throw new Error(`Invalid sandbox persistence capabilities: ${persistence.reason}`);
@@ -1286,7 +1311,7 @@ function createSandboxManager(options) {
       }
       const resuming = Boolean(lease.sandboxId && ensure.bootSource?.kind === "default" && options.driver.resumeHost);
       const bootMode = resuming && lease.url ? "resume" : ensure.bootSource?.kind === "driver-snapshot" ? "restore" : "cold-start";
-      const start = starts.observe(lease, { bootMode, enteredAt, labels: ensure.labels });
+      const start = starts.observe(lease, { bootMode, enteredAt, labels: ensure.labels, ...managerInput.updateImage ? { update: true } : {} });
       await start?.opened();
       ensure.onResource = async (resource) => {
         const recorded = await options.leaseStore.recordTarget(workspaceId, lease.epoch, {
@@ -1352,6 +1377,10 @@ function createSandboxManager(options) {
       const error = checkpointUnusable ? sandboxCheckpointUnusableError(checkpointUnusable, message) : bootFailed ? sandboxRuntimeBootFailedError(message) : startLimit ? sandboxProviderRateLimitedError(options.driver.id, startLimit) : isSandboxProviderKeyRefused(err) ? sandboxProviderKeyRefusedError(options.driver.id, message) : isSandboxStartRefusal(err) || sandboxLeaseEndedUnderStart(message) ? message : sandboxProviderFailedError(options.driver.id, message);
       if (lease.status === "ready" && !bootFailed) {
         const updated = await options.leaseStore.update(workspaceId, lease.epoch, { lastError: error }, "ready");
+        if (managerInput.updateImage) {
+          console.warn("A workspace's update to the deployment's image failed; it keeps serving its image", { workspaceId, epoch: lease.epoch, error });
+          return { status: "unavailable", error: isSandboxImageDownloadFailure(err) ? SANDBOX_UPDATE_DOWNLOAD_INTERRUPTED : error, epoch: lease.epoch, homeRegion };
+        }
         if (updated) {
           const resolved = await leaseTarget(updated);
           if (resolved.status === "ready") return { ...resolved, stale: true };
@@ -1698,8 +1727,10 @@ export {
   SANDBOX_RETRY_CAP_EXCEEDED,
   SANDBOX_RUNTIME_UNHEALTHY,
   SANDBOX_START_WINDOWS,
+  SANDBOX_UPDATE_DOWNLOAD_INTERRUPTED,
   SandboxCheckpointUnusableError,
   SandboxHostGoneError,
+  SandboxImageDownloadError,
   SandboxProviderKeyRefusedError,
   SandboxProviderRateLimitedError,
   SandboxRuntimeBootError,
@@ -1719,6 +1750,7 @@ export {
   isSandboxCheckpointUnusable,
   isSandboxCheckpointUnusableCause,
   isSandboxHostGone,
+  isSandboxImageDownloadFailure,
   isSandboxListingUnsupported,
   isSandboxProviderKeyRefused,
   isSandboxProviderRateLimited,

package/dist/lease-failure.d.ts

@@ -15,6 +15,23 @@ export declare class SandboxRuntimeBootError extends Error implements SandboxRun
     readonly runtimeBootFailed: true;
     constructor(reason: string);
 }
+/**
+ * A driver throws this shape when the image a start pulls did not finish
+ * downloading because the registry link kept breaking. Nothing the machine
+ * served has changed, so an update that fails this way leaves the workspace
+ * serving its image.
+ */
+export type SandboxImageDownloadFailure = {
+    imageDownloadFailed: true;
+    message: string;
+};
+export declare function isSandboxImageDownloadFailure(err: unknown): err is SandboxImageDownloadFailure;
+export declare class SandboxImageDownloadError extends Error implements SandboxImageDownloadFailure {
+    readonly imageDownloadFailed: true;
+    constructor(reason: string);
+}
+/** The answer to a person's update whose image download kept breaking; the lease keeps the provider's own text. */
+export declare const SANDBOX_UPDATE_DOWNLOAD_INTERRUPTED = "update_download_interrupted";
 export { isSandboxCheckpointUnusableCause, sandboxCheckpointUnusableCauses, type SandboxCheckpointUnusableCause };
 /**
  * A driver throws this shape when the checkpoint a start restores cannot be

package/dist/runtime-version.d.ts

@@ -1,10 +1,24 @@
 export declare function workspaceRuntimeVersion(): string;
 /**
- * The oldest workspace-runtime version a driver may restore a workspace's
- * snapshot into running again. A filesystem snapshot carries the runtime it
- * was taken with, so a fix to the runtime reaches a workspace that keeps
- * waking only when this rises. Raise it, together with the runtime version,
- * for a security-relevant runtime change alone: every snapshot below it is
- * refused and its person must start the workspace fresh.
+ * The oldest workspace-runtime version this control plane and relay serve, for
+ * every driver: a workspace's snapshot restored, or the older image a Boat wake
+ * keeps serving instead of waiting on the deployment's. A filesystem snapshot
+ * carries the runtime it was taken with, and a kept image the runtime it
+ * shipped, so a fix to the runtime reaches a workspace that keeps waking only
+ * when this rises. Below it a Cloudflare restore is refused and its person
+ * must start the workspace fresh, and a Boat wake boots the deployment's image.
+ *
+ * Raise it, and the workspace-runtime version with it in the same commit, for
+ * a runtime security fix or for a control-plane or relay contract an older
+ * runtime cannot speak, and name the first cloud image published at the new
+ * version: the version-skew suite (`bun run --cwd packages/harness flows:skew`)
+ * runs the current control plane and relay against exactly that image.
+ * Bumping the version with it keeps the comparison honest: every image below
+ * the new version was built before the change. What it does not cover: the
+ * images built after the floor's at the same version are trusted, not tested.
  */
-export declare const MINIMUM_RESTORABLE_WORKSPACE_RUNTIME_VERSION = "0.5.2";
+export declare const SERVED_WORKSPACE_RUNTIME_FLOOR: {
+    readonly version: "0.10.1";
+    readonly image: "ghcr.io/kyashrathore/claxedo-sandbox:workspace-runtime-0-10-1-40706b7356-agent-plugins-v8";
+};
+export declare const MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION: "0.10.1";

package/dist/runtime-version.mjs

@@ -3,8 +3,13 @@ var DEFAULT_WORKSPACE_RUNTIME_VERSION = "0.5.2";
 function workspaceRuntimeVersion() {
   return process.env.WORKSPACE_RUNTIME_VERSION || DEFAULT_WORKSPACE_RUNTIME_VERSION;
 }
-var MINIMUM_RESTORABLE_WORKSPACE_RUNTIME_VERSION = "0.5.2";
+var SERVED_WORKSPACE_RUNTIME_FLOOR = {
+  version: "0.10.1",
+  image: "ghcr.io/kyashrathore/claxedo-sandbox:workspace-runtime-0-10-1-40706b7356-agent-plugins-v8"
+};
+var MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION = SERVED_WORKSPACE_RUNTIME_FLOOR.version;
 export {
-  MINIMUM_RESTORABLE_WORKSPACE_RUNTIME_VERSION,
+  MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION,
+  SERVED_WORKSPACE_RUNTIME_FLOOR,
   workspaceRuntimeVersion
 };

package/dist/start-telemetry.d.ts

@@ -16,14 +16,16 @@ export declare function createSandboxStartRecorder(options: {
      * lease as it ends, so a poller reading the lease mid-boot sees how far the
      * start has come. `opened` writes the epoch's `lease_decision` before the
      * driver runs, so a stop that lands mid-boot finds the boot it ends on the
-     * row. A serving lease is not starting. An epoch acquired with a start it
-     * continues has that start and no phase yet; one acquired without begins
-     * its own here.
+     * row. A serving lease is not starting, unless the step is a person's
+     * update, which is a start of its own on the same epoch. An epoch acquired
+     * with a start it continues has that start and no phase yet; one acquired
+     * without begins its own here.
      */
     observe(lease: SandboxLease, input: {
         bootMode: SandboxBootMode;
         enteredAt: number;
         labels: Record<string, string>;
+        update?: true;
     }): {
         opened: () => Promise<void>;
         end: (phase: SandboxStartPhase) => Promise<void>;

package/package.json

@@ -163,7 +163,7 @@
     "access": "public"
   },
   "name": "@claxedo/sandbox-manager",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "scripts": {
     "build": "bun scripts/build.ts",
     "prepublishOnly": "npm run build",
@@ -172,8 +172,8 @@
     "test": "mkdir -p .artifacts/unit && node ../../script/test-deadline.mjs bun test src --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml"
   },
   "dependencies": {
-    "@claxedo/helpers": "0.2.0",
-    "@claxedo/sandbox-contract": "0.10.0",
+    "@claxedo/helpers": "0.2.2",
+    "@claxedo/sandbox-contract": "0.10.2",
     "@vercel/sandbox": "3.3.0",
     "modal": "0.10.1"
   },