@claxedo/sandbox-manager 0.6.0 → 0.9.0

package/dist/lease-policy.mjs

@@ -1,56 +1,230 @@
-// src/lease-policy.ts
-var DEFAULT_WORKSPACE_HOST_DECISION_CONFIG = {
-  maxRetries: 8,
-  idleMs: 10 * 60 * 1e3,
-  backoffMaxMs: 3e4,
-  healthTimeoutMs: 6e4
+// src/hosted-network-policy.ts
+var SANDBOX_MODEL_PROVIDER_HOSTS = [
+  "api.anthropic.com",
+  "api.openai.com",
+  "generativelanguage.googleapis.com",
+  "openrouter.ai",
+  // Model catalog + engine config, fetched on runner startup.
+  "models.dev",
+  "opencode.ai"
+];
+var SANDBOX_PACKAGE_REGISTRY_HOSTS = [
+  "registry.npmjs.org",
+  "nodejs.org",
+  "pypi.org",
+  "files.pythonhosted.org",
+  "crates.io",
+  "static.crates.io",
+  "index.crates.io",
+  "proxy.golang.org",
+  "sum.golang.org"
+];
+var SANDBOX_BASELINE_EGRESS_HOSTS = [
+  ...SANDBOX_MODEL_PROVIDER_HOSTS,
+  ...SANDBOX_PACKAGE_REGISTRY_HOSTS
+];
+
+// ../sandbox-contract/dist/index.mjs
+var sandboxDriverCredentialFields = {
+  exe: [{ key: "api_token", label: "API Token", secret: true }],
+  daytona: [{ key: "api_key", label: "API Key", secret: true }],
+  modal: [
+    { key: "token_id", label: "Token ID", secret: true },
+    { key: "token_secret", label: "Token Secret", secret: true }
+  ],
+  vercel: [
+    { key: "access_token", label: "Access Token", secret: true },
+    { key: "team_id", label: "Team ID" },
+    { key: "project_id", label: "Project ID" }
+  ],
+  cloudflare: [
+    { key: "api_token", label: "API Token", secret: true },
+    { key: "worker_url", label: "Worker URL" }
+  ],
+  box: [{ key: "api_key", label: "API Key", secret: true }],
+  docker: [{ key: "image", label: "Image" }]
+};
+var sandboxDriverLabels = {
+  exe: "exe.dev",
+  daytona: "Daytona",
+  modal: "Modal",
+  vercel: "Vercel",
+  cloudflare: "Cloudflare",
+  box: "Box",
+  docker: "Docker"
 };
-var DRIVER_PLACEMENT = {
+
+// src/driver-catalog.ts
+var sandboxDriverCatalog = {
+  exe: {
+    id: "exe",
+    label: sandboxDriverLabels.exe,
+    credentialFields: sandboxDriverCredentialFields.exe,
+    metadata: {
+      driverRunsIn: ["worker", "node"],
+      hostStopBehavior: "not-supported",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: {
+        resume: "same-sandbox",
+        capture: "none",
+        clone: true,
+        captureSource: "not-applicable",
+        retention: "provider-managed",
+        restoreMount: "same-resource"
+      }
+    }
+  },
   daytona: {
-    canPauseAndRestartSameResource: true,
-    canCreateFilesystemSnapshot: false,
-    canStartFromPreparedImage: true,
-    canStopExplicitly: true,
-    hasHealthProbe: true
+    id: "daytona",
+    label: sandboxDriverLabels.daytona,
+    credentialFields: sandboxDriverCredentialFields.daytona,
+    metadata: {
+      driverRunsIn: ["worker", "node"],
+      hostStopBehavior: "suspends-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "native",
+      // The driver translates names to domainAllowList, or addresses to networkAllowList.
+      egressControl: "hosts-and-cidrs",
+      persistence: {
+        resume: "same-sandbox",
+        capture: "filesystem",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "new-resource"
+      }
+    }
   },
   modal: {
-    canPauseAndRestartSameResource: false,
-    canCreateFilesystemSnapshot: true,
-    canStartFromPreparedImage: true,
-    canStopExplicitly: true,
-    hasHealthProbe: true
+    id: "modal",
+    label: sandboxDriverLabels.modal,
+    credentialFields: sandboxDriverCredentialFields.modal,
+    metadata: {
+      driverRunsIn: ["node"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "replacement-host",
+      targetAccess: "relay",
+      secretBrokering: "none",
+      // The driver does not install Modal's domain allowlist or alpha sidecar.
+      egressControl: "none",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "filesystem",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "new-resource"
+      }
+    }
   },
   vercel: {
-    canPauseAndRestartSameResource: false,
-    canCreateFilesystemSnapshot: true,
-    canStartFromPreparedImage: false,
-    canStopExplicitly: true,
-    hasHealthProbe: true
+    id: "vercel",
+    label: sandboxDriverLabels.vercel,
+    credentialFields: sandboxDriverCredentialFields.vercel,
+    metadata: {
+      driverRunsIn: ["node"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "replacement-host",
+      targetAccess: "relay",
+      secretBrokering: "native",
+      // The driver translates hosts only; the SDK's subnet rules are not wired to net.cidrs.
+      egressControl: "hosts",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "filesystem",
+        clone: false,
+        captureSource: "stopped",
+        retention: "explicit",
+        restoreMount: "new-resource"
+      }
+    }
   },
   cloudflare: {
-    canPauseAndRestartSameResource: false,
-    canCreateFilesystemSnapshot: true,
-    canStartFromPreparedImage: false,
-    canStopExplicitly: false,
-    hasHealthProbe: true
+    id: "cloudflare",
+    label: sandboxDriverLabels.cloudflare,
+    credentialFields: sandboxDriverCredentialFields.cloudflare,
+    metadata: {
+      driverRunsIn: ["worker"],
+      hostStopBehavior: "not-supported",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "native",
+      // Credential handlers do not restrict unrelated destinations.
+      egressControl: "none",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "directories",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "copy-on-write"
+      }
+    }
   },
   box: {
-    canPauseAndRestartSameResource: true,
-    canCreateFilesystemSnapshot: false,
-    canStartFromPreparedImage: true,
-    canStopExplicitly: true,
-    hasHealthProbe: true
+    id: "box",
+    label: sandboxDriverLabels.box,
+    credentialFields: sandboxDriverCredentialFields.box,
+    metadata: {
+      driverRunsIn: ["node"],
+      hostStopBehavior: "suspends-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: {
+        resume: "same-sandbox",
+        capture: "none",
+        clone: false,
+        captureSource: "not-applicable",
+        retention: "provider-managed",
+        restoreMount: "same-resource"
+      }
+    }
   },
   docker: {
-    canPauseAndRestartSameResource: true,
-    canCreateFilesystemSnapshot: false,
-    canStartFromPreparedImage: true,
-    canStopExplicitly: true,
-    hasHealthProbe: true
+    id: "docker",
+    label: sandboxDriverLabels.docker,
+    credentialFields: sandboxDriverCredentialFields.docker,
+    metadata: {
+      driverRunsIn: ["local"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "loopback",
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "same-resource",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "same-resource"
+      }
+    }
   }
 };
+
+// src/lease-policy.ts
+var DEFAULT_WORKSPACE_HOST_DECISION_CONFIG = {
+  maxRetries: 8,
+  idleMs: 10 * 60 * 1e3,
+  backoffMaxMs: 3e4,
+  healthTimeoutMs: 6e4
+};
 function sandboxDriverPlacement(driver) {
-  return DRIVER_PLACEMENT[driver];
+  const metadata = sandboxDriverCatalog[driver].metadata;
+  return {
+    canPauseAndRestartSameResource: metadata.persistence.resume === "same-sandbox",
+    canCreateFilesystemSnapshot: metadata.persistence.capture === "filesystem" || metadata.persistence.capture === "directories",
+    canStartFromPreparedImage: driver === "exe" || driver === "daytona" || driver === "modal" || driver === "box" || driver === "docker",
+    canStopExplicitly: metadata.hostStopBehavior !== "not-supported",
+    hasHealthProbe: true
+  };
 }
 function decideSandboxStart(lease, placement, now, config = DEFAULT_WORKSPACE_HOST_DECISION_CONFIG) {
   if (lease.status === "ready") {
@@ -72,7 +246,7 @@ function decideSandboxStart(lease, placement, now, config = DEFAULT_WORKSPACE_HO
   }
   return decideStartMethod(lease, placement);
 }
-function decideSandboxHealthFailure(lease, _placement, now, config = DEFAULT_WORKSPACE_HOST_DECISION_CONFIG) {
+function decideSandboxHealthFailure(lease, now, config = DEFAULT_WORKSPACE_HOST_DECISION_CONFIG) {
   if (lease.status !== "ready" && lease.status !== "unhealthy") {
     return { action: "skip", reason: `status is ${lease.status}, health check not applicable` };
   }
@@ -83,20 +257,6 @@ function decideSandboxHealthFailure(lease, _placement, now, config = DEFAULT_WOR
   const backoff = Math.min(config.backoffMaxMs, 1e3 * 2 ** Math.max(0, retryCount - 1));
   return { action: "wait", until: now + backoff, reason: `health failure #${retryCount}, backoff ${backoff}ms` };
 }
-function decideSandboxIdle(lease, activeHoldCount, now, config = DEFAULT_WORKSPACE_HOST_DECISION_CONFIG) {
-  if (lease.status !== "ready") {
-    return { action: "skip", reason: `status is ${lease.status}, not ready` };
-  }
-  if (activeHoldCount > 0) {
-    return { action: "skip", reason: `${activeHoldCount} active hold(s)` };
-  }
-  const lastActivity = lease.last_activity_at ?? lease.created_at;
-  const idleFor = now - lastActivity;
-  if (idleFor < config.idleMs) {
-    return { action: "wait", until: lastActivity + config.idleMs, reason: `idle for ${idleFor}ms, need ${config.idleMs}ms` };
-  }
-  return { action: "stop_idle", reason: `idle for ${idleFor}ms (threshold: ${config.idleMs}ms)` };
-}
 function nextSandboxRetryAt(retryCount, now, config = DEFAULT_WORKSPACE_HOST_DECISION_CONFIG) {
   if (retryCount >= config.maxRetries) return null;
   return now + Math.min(config.backoffMaxMs, 1e3 * 2 ** Math.max(0, retryCount));
@@ -124,7 +284,6 @@ function decideStartMethod(lease, placement) {
 export {
   DEFAULT_WORKSPACE_HOST_DECISION_CONFIG,
   decideSandboxHealthFailure,
-  decideSandboxIdle,
   decideSandboxStart,
   nextSandboxRetryAt,
   sandboxDriverPlacement

package/dist/lease-types.d.ts

@@ -1,5 +1,5 @@
-import type { SandboxDriverID } from "./driver-catalog";
-export type SandboxLeaseRowStatus = "pending" | "acquiring" | "starting" | "ready" | "unhealthy" | "backoff" | "stopping" | "stopped" | "failed";
+import type { SandboxCheckpointReference, SandboxPersistenceCapabilities, SandboxRestoreStatus } from "./index";
+export type SandboxLeaseRowStatus = "pending" | "acquiring" | "starting" | "ready" | "unhealthy" | "backoff" | "stopping" | "stopped" | "destroyed" | "failed";
 export type SandboxComputeClass = "small" | "medium" | "large" | "gpu";
 export type SandboxLeaseRow = {
     workspace_id: string;
@@ -7,7 +7,17 @@ export type SandboxLeaseRow = {
     home_region?: string;
     epoch: number;
     status: SandboxLeaseRowStatus;
-    driver: SandboxDriverID;
+    /**
+     * The id the driver was registered with, which is any string: the manager
+     * dispatches on whatever a composition registers (`stores/d1.test.ts`
+     * provisions one called `"test-provider"`), and every other type this value
+     * flows between — `SandboxLease["driver"]`, `SandboxLeaseAcquireInput["driver"]`,
+     * `SandboxTarget["driver"]["id"]` — is already `string`. Typing the row as the
+     * closed `SandboxDriverID` made it the odd one out and forced every store to
+     * assert into it. Narrow with `isSandboxDriverID` where a CATALOG entry is
+     * needed, which is the only place the closed set is the right question.
+     */
+    driver: string;
     driver_resource_id: string | null;
     driver_snapshot_id: string | null;
     sandbox_id: string | null;
@@ -22,6 +32,10 @@ export type SandboxLeaseRow = {
     accel_base_image_id: string | null;
     accel_prepared_image_id: string | null;
     accel_snapshot_id: string | null;
+    labels?: Record<string, string> | null;
+    checkpoint: SandboxCheckpointReference | null;
+    persistence: SandboxPersistenceCapabilities | null;
+    restore: SandboxRestoreStatus | null;
     created_at: number;
     updated_at: number;
 };

package/dist/runtime-env.d.ts

@@ -1,4 +1,15 @@
-import type { SandboxDriverID } from "./driver-catalog";
+import type { SandboxDriverID } from "@claxedo/sandbox-contract";
+export type WorkspaceRuntimeControlEnv = {
+    relayJwksUrl?: string;
+    relayVerifyPem?: string;
+    managementJwksUrl?: string;
+    sessionAuthorityUrl?: string;
+};
+export declare function workspaceRuntimeBootEnv(input: Parameters<typeof workspaceRuntimeTargetEnv>[0] & Parameters<typeof workspaceRuntimeSourceEnv>[0] & {
+    env?: Record<string, string>;
+    runner?: string;
+    controlEnv?: WorkspaceRuntimeControlEnv;
+}): Record<string, string>;
 export declare function workspaceRuntimeTargetEnv(input: {
     workspaceId: string;
     hostId?: string;

package/dist/runtime-env.mjs

@@ -1,4 +1,17 @@
 // src/runtime-env.ts
+function workspaceRuntimeBootEnv(input) {
+  const env = {
+    ...workspaceRuntimeTargetEnv(input),
+    ...workspaceRuntimeSourceEnv(input),
+    ...input.env
+  };
+  if (input.runner) env.WORKSPACE_RUNTIME_RUNNER = input.runner;
+  if (input.controlEnv?.relayJwksUrl) env.WORKSPACE_RUNTIME_RELAY_JWKS_URL = input.controlEnv.relayJwksUrl;
+  if (input.controlEnv?.relayVerifyPem) env.WORKSPACE_RUNTIME_RELAY_HOST_VERIFY_PEM = input.controlEnv.relayVerifyPem;
+  if (input.controlEnv?.managementJwksUrl) env.WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL = input.controlEnv.managementJwksUrl;
+  if (input.controlEnv?.sessionAuthorityUrl) env.WORKSPACE_RUNTIME_SESSION_AUTHORITY_URL = input.controlEnv.sessionAuthorityUrl;
+  return env;
+}
 function workspaceRuntimeTargetEnv(input) {
   return {
     WORKSPACE_RUNTIME_WORKSPACE_ID: input.workspaceId,
@@ -27,6 +40,7 @@ function workspaceRuntimeServiceExposureEnv(input) {
   };
 }
 export {
+  workspaceRuntimeBootEnv,
   workspaceRuntimeServiceExposureEnv,
   workspaceRuntimeSourceEnv,
   workspaceRuntimeTargetEnv

package/dist/runtime-version.mjs

@@ -1,15 +1,7 @@
 // src/runtime-version.ts
 var DEFAULT_WORKSPACE_RUNTIME_VERSION = "0.5.2";
-var versionCache;
 function workspaceRuntimeVersion() {
-  if (versionCache) return versionCache;
-  const envVersion = process.env.WORKSPACE_RUNTIME_VERSION;
-  if (envVersion) {
-    versionCache = envVersion;
-    return versionCache;
-  }
-  versionCache = DEFAULT_WORKSPACE_RUNTIME_VERSION;
-  return versionCache;
+  return process.env.WORKSPACE_RUNTIME_VERSION || DEFAULT_WORKSPACE_RUNTIME_VERSION;
 }
 export {
   workspaceRuntimeVersion

package/dist/service-url-exposure.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxDriverID } from "./driver-catalog";
+import type { SandboxDriverID } from "@claxedo/sandbox-contract";
 export type SandboxServiceUrlExposure = {
     source: "driver-service-url";
     access: "private" | "public" | "driver-authenticated" | "unknown";
@@ -7,4 +7,3 @@ export type SandboxServiceUrlExposure = {
     note?: string;
 };
 export declare function sandboxServiceUrlExposure(driver: SandboxDriverID): SandboxServiceUrlExposure;
-export declare function sandboxServiceUrlExposureEnv(driver: SandboxDriverID): Record<string, string>;

package/dist/service-url-exposure.mjs

@@ -1,15 +1,3 @@
-// src/runtime-env.ts
-function workspaceRuntimeServiceExposureEnv(input) {
-  return {
-    ...input.driver === "docker" ? { WORKSPACE_RUNTIME_HOST: "0.0.0.0" } : {},
-    WORKSPACE_RUNTIME_SERVICE_EXPOSURE_SOURCE: input.source,
-    WORKSPACE_RUNTIME_SERVICE_EXPOSURE_ACCESS: input.access,
-    WORKSPACE_RUNTIME_SERVICE_EXPOSURE_DRIVER: input.driver,
-    ...input.fallbackAccess ? { WORKSPACE_RUNTIME_SERVICE_EXPOSURE_FALLBACK_ACCESS: input.fallbackAccess } : {},
-    ...input.note ? { WORKSPACE_RUNTIME_SERVICE_EXPOSURE_NOTE: input.note } : {}
-  };
-}
-
 // src/service-url-exposure.ts
 function sandboxServiceUrlExposure(driver) {
   if (driver === "docker") {
@@ -35,10 +23,6 @@ function sandboxServiceUrlExposure(driver) {
     driver
   };
 }
-function sandboxServiceUrlExposureEnv(driver) {
-  return workspaceRuntimeServiceExposureEnv(sandboxServiceUrlExposure(driver));
-}
 export {
-  sandboxServiceUrlExposure,
-  sandboxServiceUrlExposureEnv
+  sandboxServiceUrlExposure
 };

package/dist/stores/memory.mjs

@@ -1,3 +1,29 @@
+// src/hosted-network-policy.ts
+var SANDBOX_MODEL_PROVIDER_HOSTS = [
+  "api.anthropic.com",
+  "api.openai.com",
+  "generativelanguage.googleapis.com",
+  "openrouter.ai",
+  // Model catalog + engine config, fetched on runner startup.
+  "models.dev",
+  "opencode.ai"
+];
+var SANDBOX_PACKAGE_REGISTRY_HOSTS = [
+  "registry.npmjs.org",
+  "nodejs.org",
+  "pypi.org",
+  "files.pythonhosted.org",
+  "crates.io",
+  "static.crates.io",
+  "index.crates.io",
+  "proxy.golang.org",
+  "sum.golang.org"
+];
+var SANDBOX_BASELINE_EGRESS_HOSTS = [
+  ...SANDBOX_MODEL_PROVIDER_HOSTS,
+  ...SANDBOX_PACKAGE_REGISTRY_HOSTS
+];
+
 // src/index.ts
 function applySandboxLeasePatch(current, patch, updatedAt) {
   return {
@@ -13,6 +39,9 @@ function applySandboxLeasePatch(current, patch, updatedAt) {
     ...patch.labels === void 0 ? {} : { labels: patch.labels },
     ...patch.nextRetryAt === void 0 ? {} : { nextRetryAt: patch.nextRetryAt ?? void 0 },
     ...patch.lastError === void 0 ? {} : { lastError: patch.lastError ?? void 0 },
+    ...patch.checkpoint === void 0 ? {} : { checkpoint: patch.checkpoint ?? void 0 },
+    ...patch.persistence === void 0 ? {} : { persistence: patch.persistence ?? void 0 },
+    ...patch.restore === void 0 ? {} : { restore: patch.restore ?? void 0 },
     updatedAt
   };
 }
@@ -50,21 +79,24 @@ function createMemoryLeaseStore(seed = []) {
         driverResourceId: resumable ? current.driverResourceId : void 0,
         lastHeartbeatAt: resumable ? current.lastHeartbeatAt : void 0,
         lastActivityAt: resumable ? current.lastActivityAt : void 0,
-        labels: resumable ? current.labels : void 0
+        labels: resumable ? current.labels : void 0,
+        checkpoint: current?.checkpoint,
+        persistence: current?.persistence,
+        restore: current?.restore
       };
       leases.set(workspaceId, next);
       return { acquired: true, lease: next };
     },
     async update(workspaceId, expectedEpoch, patch) {
       const current = leases.get(workspaceId);
-      if (!current || current.epoch !== expectedEpoch) return;
+      if (!current || current.epoch !== expectedEpoch) return void 0;
       const next = applySandboxLeasePatch(current, patch, Date.now());
       leases.set(workspaceId, next);
       return next;
     },
     async recordFailure(workspaceId, expectedEpoch, error, nextRetryAt) {
       const current = leases.get(workspaceId);
-      if (!current || current.epoch !== expectedEpoch) return;
+      if (!current || current.epoch !== expectedEpoch) return void 0;
       const next = {
         ...current,
         status: "unavailable",
@@ -106,7 +138,10 @@ function sandboxLease(input) {
     lastError: input.lastError,
     lastHeartbeatAt: input.lastHeartbeatAt,
     lastActivityAt: input.lastActivityAt,
-    labels: input.labels
+    labels: input.labels,
+    checkpoint: input.checkpoint,
+    persistence: input.persistence,
+    restore: input.restore
   };
 }
 export {