@claxedo/sandbox-manager 0.6.0 → 0.9.0

package/dist/drivers/box.mjs

@@ -1,4 +1,28 @@
+// ../claxedo-helpers/dist/string.mjs
+function isString(value) {
+  return typeof value === "string";
+}
+function trimToUndefined(value) {
+  if (!isString(value))
+    return;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+
 // 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,
@@ -25,21 +49,10 @@ function shell(input) {
 // src/constants.ts
 var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
 
-// src/image.ts
-import { Image, DaytonaNotFoundError } from "@daytona/sdk";
-
 // 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;
 }
 
 // src/image-name.ts
@@ -63,11 +76,256 @@ function defaultSnapshotName(version = workspaceRuntimeVersion(), buildId, env =
   return `claxedo-workspace-runtime-${snapshotVersion(version)}${buildIdSuffix(buildId, env)}-v${SNAPSHOT_SCHEMA_VERSION}`;
 }
 
+// ../claxedo-helpers/dist/guards.mjs
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asRecord(value) {
+  return isRecord(value) ? value : void 0;
+}
+
+// src/json.ts
+function text(input) {
+  return typeof input === "string" && input.length > 0 ? input : void 0;
+}
+function num(input) {
+  return typeof input === "number" ? input : void 0;
+}
+
 // src/image.ts
 var SANDBOX_IMAGE_REPOSITORY = sandboxImageRepository();
 var SANDBOX_IMAGE = process.env.CLAXEDO_SANDBOX_IMAGE || defaultSandboxImage();
 var SNAPSHOT_NAME = process.env.CLAXEDO_SNAPSHOT_NAME || defaultSnapshotName();
 
+// 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"
+};
+
+// 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: {
+    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: {
+    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: {
+    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: {
+    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: {
+    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: {
+    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/drivers/transient-error.ts
+function textOf(input) {
+  return typeof input === "string" ? input : "";
+}
+function driverErrorSignals(err) {
+  const shaped = isRecord(err) ? err : {};
+  const nested = isRecord(shaped.response) ? shaped.response : {};
+  return {
+    status: num(nested.status) ?? num(shaped.status),
+    text: `${textOf(shaped.code)} ${textOf(shaped.name)} ${textOf(shaped.message)}`.toLowerCase()
+  };
+}
+function isTransientDriverError(err, markers) {
+  const { status, text: text2 } = driverErrorSignals(err);
+  if (status !== void 0 && status >= 500) return true;
+  return markers.some((marker) => text2.includes(marker));
+}
+
 // src/drivers/box.ts
 var DEFAULT_BASE_URL = "https://ascii.dev/api/box/v1";
 var DEFAULT_RUNTIME_COMMAND = "/usr/local/bin/workspace-runtime";
@@ -87,11 +345,9 @@ function clean(input) {
   const txt = input?.trim();
   return txt ? txt : void 0;
 }
+var TRANSIENT_MARKERS = ["timeout", "unavailable", "econnreset", "network"];
 function transientDriverError(err) {
-  const shaped = err;
-  if (typeof shaped.status === "number" && shaped.status >= 500) return true;
-  const text = `${shaped.code ?? ""} ${shaped.name ?? ""} ${shaped.message ?? ""}`.toLowerCase();
-  return text.includes("timeout") || text.includes("unavailable") || text.includes("econnreset") || text.includes("network");
+  return isTransientDriverError(err, TRANSIENT_MARKERS);
 }
 var BoxApiError = class extends Error {
   status;
@@ -129,14 +385,29 @@ function createBoxSandboxDriver(options) {
     } catch (err) {
       throw new BoxApiError(err instanceof Error ? err.message : String(err));
     }
-    const text = await res.text();
-    const body = text ? JSON.parse(text) : {};
+    const payload = await res.text();
+    const body = (payload ? asRecord(JSON.parse(payload)) : void 0) ?? {};
     if (!res.ok || body.ok === false) {
-      const detail = clean(body.error) ?? clean(body.message) ?? res.statusText;
+      const detail = clean(text(body.error)) ?? clean(text(body.message)) ?? res.statusText;
       throw new BoxApiError(`Box API ${init?.method ?? "GET"} ${path} failed: ${detail}`, res.status);
     }
     return body;
   }
+  function boxOf(body) {
+    const box = asRecord(body.box);
+    const id = text(box?.id);
+    const state = text(box?.state);
+    if (!box || !id || !state) throw new BoxApiError("Box API response omitted its box envelope");
+    return {
+      id,
+      state,
+      ...text(box.name) ? { name: text(box.name) } : {},
+      ...box.url === void 0 ? {} : { url: text(box.url) ?? null },
+      ...box.ip === void 0 ? {} : { ip: text(box.ip) ?? null },
+      ...box.subdomain === void 0 ? {} : { subdomain: text(box.subdomain) ?? null },
+      ...box.createdAt === void 0 ? {} : { createdAt: text(box.createdAt) ?? null }
+    };
+  }
   function runtimePort(input) {
     return input.workspaceRuntimePort ?? options.runtimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT;
   }
@@ -148,26 +419,23 @@ function createBoxSandboxDriver(options) {
     return input.snapshot ?? image;
   }
   function bootEnv(input, hostId) {
-    const env = {
-      ...workspaceRuntimeTargetEnv({
-        workspaceId: input.workspaceId,
-        hostId,
-        directory: workspaceDirectory(input),
-        port: runtimePort(input),
-        host: "0.0.0.0"
-      }),
-      ...workspaceRuntimeSourceEnv({ source: input.source }),
-      ...input.env
-    };
-    if (options.runner) env.WORKSPACE_RUNTIME_RUNNER = options.runner;
-    return env;
+    return workspaceRuntimeBootEnv({
+      workspaceId: input.workspaceId,
+      hostId,
+      directory: workspaceDirectory(input),
+      port: runtimePort(input),
+      host: "0.0.0.0",
+      source: input.source,
+      env: input.env,
+      runner: options.runner
+    });
   }
   async function exec(boxId, command) {
     const body = await api(`/boxes/${boxId}/commands`, {
       method: "POST",
       body: { command }
     });
-    const result = body.result ?? body;
+    const result = asRecord(body.result) ?? body;
     return {
       stdout: typeof result.stdout === "string" ? result.stdout : "",
       stderr: typeof result.stderr === "string" ? result.stderr : "",
@@ -177,14 +445,14 @@ function createBoxSandboxDriver(options) {
   async function execOrThrow(boxId, command, label) {
     const result = await exec(boxId, command);
     if ((result.exitCode ?? 0) !== 0) {
-      throw new BoxApiError(`Box ${boxId} ${label} failed (exit ${result.exitCode}): ${clean(result.stderr) ?? clean(result.stdout) ?? ""}`);
+      throw new BoxApiError(`Box ${boxId} ${label} failed (exit ${result.exitCode}): ${trimToUndefined(result.stderr) ?? trimToUndefined(result.stdout) ?? ""}`);
     }
     return result;
   }
   async function waitUntilReady(boxId) {
     const until = Date.now() + provisionTimeoutMs;
     for (; ; ) {
-      const { box } = await api(`/boxes/${boxId}`);
+      const box = boxOf(await api(`/boxes/${boxId}`));
       if (READY_STATES.has(box.state)) return true;
       if (!PENDING_STATES.has(box.state)) {
         throw new BoxApiError(`Box ${boxId} entered non-ready state: ${box.state}`);
@@ -210,7 +478,7 @@ function createBoxSandboxDriver(options) {
         boxId,
         `curl -sf -o /dev/null -w '%{http_code}' http://127.0.0.1:${port}/global/health || true`
       );
-      const code = clean(probe.stdout);
+      const code = trimToUndefined(probe.stdout);
       if (code === "200") return;
       last = `health probe returned ${code ?? "no response"}`;
       await sleep(healthIntervalMs);
@@ -227,7 +495,7 @@ function createBoxSandboxDriver(options) {
     await execOrThrow(boxId, `host ${port}`, "host publish");
     await waitForHealth(boxId, input);
     const urlResult = await execOrThrow(boxId, `host url ${port}`, "host url");
-    const url = clean(urlResult.stdout?.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).pop());
+    const url = trimToUndefined(urlResult.stdout?.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).pop());
     if (!url) throw new BoxApiError(`Box ${boxId} did not return a public URL for port ${port}`);
     return {
       workspaceId: input.workspaceId,
@@ -255,7 +523,7 @@ function createBoxSandboxDriver(options) {
       throw err;
     });
     if (!created) return { provisioning: true, retryAfterMs: provisionIntervalMs };
-    const boxId = created.box.id;
+    const boxId = boxOf(created).id;
     const ready = await waitUntilReady(boxId);
     if (!ready) return { provisioning: true, retryAfterMs: provisionIntervalMs };
     return boot(boxId, input, hostId);
@@ -288,7 +556,9 @@ function createBoxSandboxDriver(options) {
       hostStopBehavior: "suspends-host",
       hostResumeBehavior: "same-host",
       targetAccess: "relay",
-      secretBrokering: "none"
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: sandboxDriverCatalog.box.metadata.persistence
     },
     ensureHost,
     resumeHost,

package/dist/drivers/cloudflare.d.ts

@@ -1,4 +1,5 @@
-import type { SandboxDriver, SandboxDriverEnsureInput } from "..";
+import { type SandboxDriver, type SandboxDriverEnsureInput, type SandboxListingUnsupported } from "..";
+import { type WorkspaceRuntimeControlEnv } from "../runtime-env";
 export type CloudflareSandboxDriverOptions = {
     /** Base URL of the deployed Cloudflare Sandbox Worker (e.g. https://sbx.example.com). */
     workerUrl: string;
@@ -18,12 +19,8 @@ export type CloudflareSandboxDriverOptions = {
    *   relayVerifyPem   → WORKSPACE_RUNTIME_RELAY_HOST_VERIFY_PEM (fallback to JWKS)
    *   managementJwksUrl → WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL (config apply)
      */
-    controlEnv?: {
-        relayJwksUrl?: string;
-        relayVerifyPem?: string;
-        managementJwksUrl?: string;
-    };
-    /** Default runner injected as WORKSPACE_RUNTIME_RUNNER, e.g. "opencode" | "claude-acp" | "codex-acp". */
+    controlEnv?: WorkspaceRuntimeControlEnv;
+    /** Default runner injected as WORKSPACE_RUNTIME_RUNNER, for example "opencode". */
     runner?: string;
     /** Dynamic runtime env that needs the sandbox id or current lease. */
     env?: (input: SandboxDriverEnsureInput, sandbox: {
@@ -34,4 +31,18 @@ export type CloudflareSandboxDriverOptions = {
     /** ensure-runtime/HTTP timeout. */
     timeoutMs?: number;
 };
+/**
+ * Thrown when this driver's sandbox Worker cannot enumerate sandboxes — one
+ * deployed before the `/sandboxes` registry route, or without its R2 binding.
+ *
+ * A typed signal rather than a plain Error because the manager must tell apart
+ * two cases that both "fail to list": a transient listing error (a real sweep
+ * failure, propagate it) and a standing capability gap (report
+ * `listingUnsupported`, same as a driver with no `list()`). Returning `[]` for
+ * the latter would report a clean sweep while seeing nothing.
+ */
+export declare class CloudflareSandboxListingUnsupportedError extends Error implements SandboxListingUnsupported {
+    readonly listingUnsupported: true;
+    constructor(message: string);
+}
 export declare function createCloudflareSandboxDriver(options: CloudflareSandboxDriverOptions): SandboxDriver;