@claxedo/sandbox-manager 0.7.0 → 0.10.0

package/dist/drivers/docker.d.ts

@@ -1,17 +1,18 @@
-import type { SandboxDriver, SandboxDriverEnsureInput } from "..";
+import type { SandboxDriver, SandboxDriverEnsureInput } from "../contract";
 type SandboxEnv = Record<string, string | undefined>;
 export type DockerCommandResult = {
     stdout?: string | Buffer;
     stderr?: string | Buffer;
 };
-export type DockerCommandRunner = (args: string[], timeoutMs?: number) => Promise<DockerCommandResult>;
+/** `env` joins the docker CLI's own environment; a `--env NAME` argument with no value reads NAME from it. */
+export type DockerCommandRunner = (args: string[], timeoutMs?: number, env?: Record<string, string>) => Promise<DockerCommandResult>;
 export type DockerHealthFetch = (input: string, init?: RequestInit) => Promise<Response>;
 export type DockerSandboxDriverOptions = {
     image: string;
     runtimePort?: number;
     runtimeCommand?: string;
     workspaceDir?: string;
-    runner?: string;
+    nativeHarness?: string;
     env?: (input: SandboxDriverEnsureInput, host: {
         id: string;
     }) => Record<string, string> | Promise<Record<string, string>>;

package/dist/drivers/docker.mjs

@@ -5,7 +5,61 @@ import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 
+// ../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
+var WORKSPACE_RUNTIME_IDENTITY_ENV_KEYS = [
+  "WORKSPACE_RUNTIME_WORKSPACE_ID",
+  "WORKSPACE_RUNTIME_HOST_ID",
+  "WORKSPACE_RUNTIME_RELAY_WORKSPACE_IDS"
+];
+function workspaceRuntimeIdentityEnvConflicts(env) {
+  if (!env) return [];
+  return WORKSPACE_RUNTIME_IDENTITY_ENV_KEYS.filter((key) => env[key] !== void 0);
+}
+function assertWorkspaceRuntimeIdentityEnv(env) {
+  const conflicts = workspaceRuntimeIdentityEnvConflicts(env);
+  if (conflicts.length === 0) return;
+  throw new Error(
+    `sandbox env cannot set runtime identity ${conflicts.join(", ")}: the driver's placement owns the identity its target reports and the lease records`
+  );
+}
+var WORKSPACE_RUNTIME_PUBLIC_ENV_KEYS = /* @__PURE__ */ new Set([
+  ...WORKSPACE_RUNTIME_IDENTITY_ENV_KEYS,
+  "WORKSPACE_RUNTIME_DIRECTORY",
+  "WORKSPACE_RUNTIME_PORT",
+  "WORKSPACE_RUNTIME_HOST",
+  "WORKSPACE_RUNTIME_SOURCE_KIND",
+  "WORKSPACE_RUNTIME_GIT_REPO_URL",
+  "WORKSPACE_RUNTIME_GIT_BRANCH",
+  "WORKSPACE_RUNTIME_NATIVE_HARNESS",
+  "WORKSPACE_RUNTIME_RELAY_JWKS_URL",
+  "WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL",
+  "WORKSPACE_RUNTIME_SESSION_AUTHORITY_URL"
+]);
+function workspaceRuntimeBootEnv(input) {
+  assertWorkspaceRuntimeIdentityEnv(input.env);
+  const env = {
+    ...workspaceRuntimeTargetEnv(input),
+    ...workspaceRuntimeSourceEnv(input),
+    ...input.env
+  };
+  if (input.nativeHarness) env.WORKSPACE_RUNTIME_NATIVE_HARNESS = input.nativeHarness;
+  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,
@@ -32,9 +86,6 @@ 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";
 function workspaceRuntimeVersion() {
@@ -47,6 +98,12 @@ var DEFAULT_SANDBOX_IMAGE_REPOSITORY = "ghcr.io/kyashrathore/claxedo-sandbox";
 function snapshotVersion(value) {
   return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
+function assertSandboxImageReference(image) {
+  if (!image || image !== image.trim() || image.startsWith("-") || /\s/.test(image)) {
+    throw new Error(`sandbox image reference is not a legal image identifier: ${JSON.stringify(image)}`);
+  }
+  return image;
+}
 function sandboxImageRepository(env = process.env) {
   const repository = env.CLAXEDO_SANDBOX_IMAGE_REPOSITORY?.trim();
   return repository ? repository : DEFAULT_SANDBOX_IMAGE_REPOSITORY;
@@ -55,107 +112,87 @@ function buildIdSuffix(buildId, env) {
   const id = (buildId ?? env.CLAXEDO_SANDBOX_BUILD_ID)?.trim();
   return id ? `-${snapshotVersion(id)}` : "";
 }
-function defaultSandboxImage(version = workspaceRuntimeVersion(), buildId, env = process.env) {
-  return `${sandboxImageRepository(env)}:workspace-runtime-${snapshotVersion(version)}${buildIdSuffix(buildId, env)}-v${SNAPSHOT_SCHEMA_VERSION}`;
-}
-function defaultSnapshotName(version = workspaceRuntimeVersion(), buildId, env = process.env) {
-  return `claxedo-workspace-runtime-${snapshotVersion(version)}${buildIdSuffix(buildId, env)}-v${SNAPSHOT_SCHEMA_VERSION}`;
+var AGENT_PLUGINS_TAG = "-agent-plugins";
+function defaultSandboxImage(version = workspaceRuntimeVersion(), buildId, env = process.env, options = {}) {
+  const feature = options.agentPlugins ? AGENT_PLUGINS_TAG : "";
+  return `${sandboxImageRepository(env)}:workspace-runtime-${snapshotVersion(version)}${buildIdSuffix(buildId, env)}${feature}-v${SNAPSHOT_SCHEMA_VERSION}`;
 }
 
 // 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
-];
+// src/driver-billing.ts
+var HOUR_SECONDS = 3600;
+var boatBilling = {
+  source: { url: "https://docs.boat.dev/pricing", readOn: "2026-10-12" },
+  meter: "Boat bills machine time per second while a sandbox runs, at an hourly rate per size; a stopped sandbox costs nothing.",
+  rates: {
+    small: { size: "small", vcpu: 2, memoryGb: 4, usdPerHour: 0.018 },
+    default: { size: "default", vcpu: 4, memoryGb: 8, usdPerHour: 0.036 },
+    large: { size: "large", vcpu: 8, memoryGb: 16, usdPerHour: 0.072 }
+  }
+};
+var CLOUDFLARE_USD_PER_GIB_SECOND_MEMORY = 25e-7;
+var CLOUDFLARE_USD_PER_GB_SECOND_DISK = 7e-8;
+var CLOUDFLARE_USD_PER_VCPU_SECOND_ACTIVE = 2e-5;
+var CLOUDFLARE_STANDARD_1 = { size: "standard-1", vcpu: 0.5, memoryGb: 4, diskGb: 8 };
+var cloudflareBilling = {
+  source: { url: "https://developers.cloudflare.com/containers/pricing/", readOn: "2026-10-12" },
+  meter: "Cloudflare bills a container for every 10 ms it runs: memory at $0.0000025 per GiB-second and disk at $0.00000007 per GB-second for the whole run, plus CPU at $0.00002 per vCPU-second of active use.",
+  rates: {
+    default: {
+      size: CLOUDFLARE_STANDARD_1.size,
+      vcpu: CLOUDFLARE_STANDARD_1.vcpu,
+      memoryGb: CLOUDFLARE_STANDARD_1.memoryGb,
+      usdPerHour: (CLOUDFLARE_STANDARD_1.memoryGb * CLOUDFLARE_USD_PER_GIB_SECOND_MEMORY + CLOUDFLARE_STANDARD_1.diskGb * CLOUDFLARE_USD_PER_GB_SECOND_DISK) * HOUR_SECONDS
+    }
+  },
+  excludes: `active CPU, billed at $${CLOUDFLARE_USD_PER_VCPU_SECOND_ACTIVE} per vCPU-second and not measured by Claxedo, and the monthly allowance a Workers Paid plan includes`
+};
+
+// ../sandbox-contract/dist/index.mjs
+var sandboxDriverCredentialFields = {
+  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" }
+  ],
+  boat: [{ key: "api_key", label: "API Key", secret: true }],
+  docker: [{ key: "image", label: "Image" }]
+};
+var sandboxDriverLabels = {
+  modal: "Modal",
+  vercel: "Vercel",
+  cloudflare: "Cloudflare",
+  boat: "Boat",
+  docker: "Docker"
+};
 
 // src/driver-catalog.ts
 var sandboxDriverCatalog = {
-  exe: {
-    id: "exe",
-    label: "exe.dev",
-    credentialFields: [{ key: "api_token", label: "API Token", secret: true }],
-    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: "Daytona",
-    credentialFields: [{ key: "api_key", label: "API Key", secret: true }],
-    metadata: {
-      driverRunsIn: ["worker", "node"],
-      hostStopBehavior: "suspends-host",
-      hostResumeBehavior: "same-host",
-      targetAccess: "relay",
-      secretBrokering: "native",
-      // Daytona is the only driver that can filter egress by NAME as well as
-      // by address: `domainAllowList` (names) alongside `networkAllowList`
-      // (CIDRs), with `networkBlockAll` as the deny-all floor.
-      egressControl: "hosts-and-cidrs",
-      persistence: {
-        resume: "same-sandbox",
-        capture: "filesystem",
-        clone: false,
-        captureSource: "preserved",
-        retention: "provider-managed",
-        restoreMount: "new-resource"
-      }
-    }
-  },
   modal: {
     id: "modal",
-    label: "Modal",
-    credentialFields: [
-      { key: "token_id", label: "Token ID", secret: true },
-      { key: "token_secret", label: "Token Secret", secret: true }
-    ],
+    label: sandboxDriverLabels.modal,
+    credentialFields: sandboxDriverCredentialFields.modal,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
       hostResumeBehavior: "replacement-host",
       targetAccess: "relay",
       secretBrokering: "none",
-      // Modal can cut the network entirely (`blockNetwork`) but cannot express
-      // an allowlist, and its driver throws on a host policy. A blackout is
-      // not containment for a workspace that has to clone and reach a model.
+      // The driver does not install Modal's domain allowlist or alpha sidecar.
       egressControl: "none",
       persistence: {
         resume: "replacement-restore",
@@ -169,20 +206,18 @@ var sandboxDriverCatalog = {
   },
   vercel: {
     id: "vercel",
-    label: "Vercel",
-    credentialFields: [
-      { key: "access_token", label: "Access Token", secret: true },
-      { key: "team_id", label: "Team ID" },
-      { key: "project_id", label: "Project ID" }
-    ],
+    label: sandboxDriverLabels.vercel,
+    credentialFields: sandboxDriverCredentialFields.vercel,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: false,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
       hostResumeBehavior: "replacement-host",
       targetAccess: "relay",
       secretBrokering: "native",
-      // Vercel's sandbox firewall takes a hostname allow list (or "deny-all"),
-      // never CIDRs.
+      // The driver translates hosts only; the SDK's subnet rules are not wired to net.cidrs.
       egressControl: "hosts",
       persistence: {
         resume: "replacement-restore",
@@ -196,40 +231,42 @@ var sandboxDriverCatalog = {
   },
   cloudflare: {
     id: "cloudflare",
-    label: "Cloudflare",
-    credentialFields: [
-      { key: "api_token", label: "API Token", secret: true },
-      { key: "worker_url", label: "Worker URL" }
-    ],
+    label: sandboxDriverLabels.cloudflare,
+    credentialFields: sandboxDriverCredentialFields.cloudflare,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: false,
+    billing: cloudflareBilling,
     metadata: {
       driverRunsIn: ["worker"],
-      hostStopBehavior: "not-supported",
+      hostStopBehavior: "terminates-host",
       hostResumeBehavior: "same-host",
+      hostWatchesIdle: true,
       targetAccess: "relay",
-      secretBrokering: "proxy",
-      // The Cloudflare Sandbox Worker exposes no egress filter: its broker
-      // (drivers/cloudflare-egress.ts) is an OPT-IN proxy the sandbox chooses
-      // to route brokered-credential requests through, not a boundary. The
-      // driver therefore drops `net` entirely — which is exactly why this
-      // must be declared, so the manager refuses instead of provisioning a
-      // sandbox the caller believes is contained.
+      secretBrokering: "native",
+      // Credential handlers do not restrict unrelated destinations.
       egressControl: "none",
+      // A container snapshot holds the whole root filesystem; the platform keeps it 30 days past its last restore and offers no deletion.
       persistence: {
         resume: "replacement-restore",
-        capture: "directories",
+        capture: "filesystem",
         clone: false,
         captureSource: "preserved",
         retention: "provider-managed",
-        restoreMount: "copy-on-write"
+        restoreMount: "new-resource"
       }
     }
   },
-  box: {
-    id: "box",
-    label: "Box",
-    credentialFields: [{ key: "api_key", label: "API Key", secret: true }],
+  boat: {
+    id: "boat",
+    label: sandboxDriverLabels.boat,
+    credentialFields: sandboxDriverCredentialFields.boat,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
+    billing: boatBilling,
     metadata: {
-      driverRunsIn: ["node"],
+      driverRunsIn: ["worker", "node"],
       hostStopBehavior: "suspends-host",
       hostResumeBehavior: "same-host",
       targetAccess: "relay",
@@ -242,13 +279,17 @@ var sandboxDriverCatalog = {
         captureSource: "not-applicable",
         retention: "provider-managed",
         restoreMount: "same-resource"
-      }
+      },
+      machineClasses: ["small", "default", "large"]
     }
   },
   docker: {
     id: "docker",
-    label: "Docker",
-    credentialFields: [{ key: "image", label: "Image" }],
+    label: sandboxDriverLabels.docker,
+    credentialFields: sandboxDriverCredentialFields.docker,
+    runtimeNetwork: { controlPlane: "docker-host", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
     metadata: {
       driverRunsIn: ["local"],
       hostStopBehavior: "terminates-host",
@@ -268,6 +309,48 @@ var sandboxDriverCatalog = {
   }
 };
 
+// ../claxedo-helpers/dist/guards.mjs
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/json.ts
+function num(input) {
+  return typeof input === "number" ? input : void 0;
+}
+
+// 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 {
+    // `response.status` is the axios shape; `statusCode` is what SDK-native
+    // error classes expose instead.
+    status: num(nested.status) ?? num(shaped.status) ?? num(shaped.statusCode),
+    text: `${textOf(shaped.code)} ${textOf(shaped.name)} ${textOf(shaped.message)}`.toLowerCase()
+  };
+}
+function isTransientDriverError(err, markers) {
+  const { status, text } = driverErrorSignals(err);
+  if (status !== void 0 && status >= 500) return true;
+  return markers.some((marker) => text.includes(marker));
+}
+var TRANSIENT_DRIVER_RETRY_MS = 2e3;
+
+// ../claxedo-helpers/dist/deadline.mjs
+async function withDeadlineSignal(timeoutMs, work, parent) {
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(new DOMException("The operation timed out.", "TimeoutError")), timeoutMs);
+  try {
+    return await work(parent ? AbortSignal.any([parent, deadline.signal]) : deadline.signal);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/drivers/docker.ts
 var execFileAsync = promisify(execFile);
 var DEFAULT_OPERATION_TIMEOUT_MS = 6e4;
@@ -278,13 +361,13 @@ var DEFAULT_WORKSPACE_DIR = "/workspace";
 var DOCKER_LABEL = "claxedo";
 var AUTH_STAGE_DIR = "/tmp/claxedo-auth";
 function dockerSandboxSyncLocalAuth(env = process.env) {
-  return !disabled(env.CLAXEDO_DOCKER_SANDBOX_SYNC_LOCAL_AUTH);
+  return enabledFlag(env.CLAXEDO_DOCKER_SANDBOX_SYNC_LOCAL_AUTH);
 }
 function dockerSandboxAuthHome(env = process.env) {
-  return clean(env.CLAXEDO_DOCKER_SANDBOX_AUTH_HOME) ?? clean(env.HOME) ?? os.homedir();
+  return trimToUndefined(env.CLAXEDO_DOCKER_SANDBOX_AUTH_HOME) ?? trimToUndefined(env.HOME) ?? os.homedir();
 }
 function dockerSandboxImageFromEnv(env = process.env) {
-  return clean(env.CLAXEDO_DOCKER_SANDBOX_IMAGE) ?? clean(env.CLAXEDO_SANDBOX_IMAGE) ?? SANDBOX_IMAGE;
+  return trimToUndefined(env.CLAXEDO_DOCKER_SANDBOX_IMAGE) ?? trimToUndefined(env.CLAXEDO_SANDBOX_IMAGE) ?? SANDBOX_IMAGE;
 }
 function parseDockerPort(input) {
   const line = input.trim().split(/\r?\n/)[0]?.trim();
@@ -315,21 +398,18 @@ function dockerLocalAuthCandidates(home) {
     }
   ];
 }
-function clean(input) {
-  const txt = input?.trim();
-  return txt ? txt : void 0;
-}
-function disabled(input) {
-  return ["0", "false", "no", "off"].includes(input?.trim().toLowerCase() ?? "");
+function enabledFlag(input) {
+  return ["1", "true", "yes", "on"].includes(input?.trim().toLowerCase() ?? "");
 }
 function nameFor(workspaceId) {
   const cleanId = workspaceId.toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
   return `claxedo-${cleanId || "workspace"}-${Date.now().toString(36)}`.slice(0, 63);
 }
-async function docker(args, timeoutMs = DEFAULT_OPERATION_TIMEOUT_MS) {
+async function docker(args, timeoutMs = DEFAULT_OPERATION_TIMEOUT_MS, env) {
   return execFileAsync("docker", args, {
     maxBuffer: 20 * 1024 * 1024,
-    timeout: timeoutMs
+    timeout: timeoutMs,
+    ...env ? { env: { ...process.env, ...env } } : {}
   });
 }
 function sleep(ms) {
@@ -340,22 +420,25 @@ async function stageLocalAgentAuth(containerId, input) {
   const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "claxedo-docker-auth-"));
   try {
     const stagedRoot = path.join(tmp, "root");
-    const copied = await Promise.all(dockerLocalAuthCandidates(input.authHome).map(async (item) => {
-      const stat = await fs.stat(item.source).catch(() => void 0);
-      if (!stat) return false;
-      if (item.kind === "file" && !stat.isFile()) return false;
-      if (item.kind === "dir" && !stat.isDirectory()) return false;
+    let copied = false;
+    for (const item of dockerLocalAuthCandidates(input.authHome)) {
+      const stat = await fs.stat(item.source).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+        throw error;
+      });
+      if (!stat) continue;
+      if (item.kind === "file" && !stat.isFile()) continue;
+      if (item.kind === "dir" && !stat.isDirectory()) continue;
       const target = path.join(stagedRoot, item.target.replace(/^\/root\/?/, ""));
       await fs.mkdir(path.dirname(target), { recursive: true });
       if (item.kind === "dir") await fs.cp(item.source, target, { recursive: true });
       else await fs.copyFile(item.source, target);
-      return true;
-    }));
-    if (!copied.some(Boolean)) return;
+      copied = true;
+    }
+    if (!copied) return;
     await input.docker(["cp", stagedRoot, `${containerId}:${AUTH_STAGE_DIR}`], input.timeoutMs);
   } finally {
-    await fs.rm(tmp, { recursive: true, force: true }).catch(() => {
-    });
+    await fs.rm(tmp, { recursive: true, force: true });
   }
 }
 function authHydrationScript() {
@@ -377,16 +460,15 @@ function bootScript(directory, runtimeCommand) {
     `exec ${runtimeCommand}`
   ].join(" && ");
 }
-function envArgs(input) {
-  return Object.entries(input).flatMap(([key, value]) => ["--env", `${key}=${value}`]);
+function envNameArgs(input) {
+  return Object.keys(input).flatMap((key) => ["--env", key]);
 }
 function labelArgs(input) {
   return Object.entries(input).flatMap(([key, value]) => ["--label", `${key}=${value}`]);
 }
+var TRANSIENT_MARKERS = ["timeout", "temporarily unavailable", "connection refused"];
 function transientDriverError(err) {
-  const shaped = err;
-  const text = `${shaped.code ?? ""} ${shaped.message ?? ""}`.toLowerCase();
-  return text.includes("timeout") || text.includes("temporarily unavailable") || text.includes("connection refused");
+  return isTransientDriverError(err, TRANSIENT_MARKERS);
 }
 function createDockerSandboxDriver(options) {
   const dockerCommand = options.docker ?? docker;
@@ -408,22 +490,21 @@ function createDockerSandboxDriver(options) {
     if (input.bootSource?.kind === "driver-snapshot") {
       throw new Error("Docker SandboxDriver does not support driver snapshots; use image boot");
     }
-    return input.bootSource?.kind === "image" ? input.bootSource.image : input.snapshot ?? options.image;
+    return assertSandboxImageReference(
+      input.bootSource?.kind === "image" ? input.bootSource.image : input.snapshot ?? options.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,
+      nativeHarness: options.nativeHarness
+    });
   }
   async function readyTarget(input, sandboxId, hostId) {
     const out = await dockerCommand(["port", sandboxId, `${runtimePort(input)}/tcp`], timeoutMs);
@@ -448,9 +529,7 @@ function createDockerSandboxDriver(options) {
     let error = "workspace runtime not ready";
     while (Date.now() < until) {
       try {
-        const res = await healthFetch(`${url}/global/health`, {
-          signal: AbortSignal.timeout(Math.min(2e3, Math.max(1, healthTimeoutMs)))
-        });
+        const res = await withDeadlineSignal(Math.min(2e3, Math.max(1, healthTimeoutMs)), (signal) => healthFetch(`${url}/global/health`, { signal }));
         if (res.ok) return;
         error = `${res.status} ${res.statusText}`;
       } catch (err) {
@@ -480,17 +559,17 @@ function createDockerSandboxDriver(options) {
       ...labelArgs(input.labels),
       "-p",
       `127.0.0.1::${runtimePort(input)}`,
-      ...envArgs(env),
+      ...envNameArgs(env),
       "--entrypoint",
       "sh",
       image(input),
       "-lc",
       bootScript(workspaceDirectory(input), runtimeCommand)
-    ], 12e4).catch((err) => {
+    ], 12e4, env).catch((err) => {
       if (transientDriverError(err)) return void 0;
       throw err;
     });
-    if (!created) return { provisioning: true, retryAfterMs: 2e3 };
+    if (!created) return { provisioning: true, retryAfterMs: TRANSIENT_DRIVER_RETRY_MS };
     const sandboxId = String(created.stdout ?? "").trim() || hostId;
     await stageLocalAgentAuth(sandboxId, { authHome, syncLocalAuth, docker: dockerCommand, timeoutMs });
     await dockerCommand(["start", sandboxId], timeoutMs);
@@ -499,7 +578,7 @@ function createDockerSandboxDriver(options) {
   async function resumeHost(input) {
     const sandboxId = input.lease.sandboxId ?? input.lease.sandbox_id;
     if (!sandboxId) return ensureHost(input.ensure);
-    await dockerCommand(["inspect", "-f", "{{.Id}}", sandboxId], timeoutMs).catch(() => void 0);
+    await dockerCommand(["inspect", "-f", "{{.Id}}", sandboxId], timeoutMs);
     await dockerCommand(["start", sandboxId], timeoutMs).catch((err) => {
       if (transientDriverError(err)) return void 0;
       throw err;

package/dist/drivers/local-brokering.d.ts

@@ -0,0 +1,14 @@
+import type { SandboxDriver } from "../contract";
+import { localBrokeringTestDriverCatalogEntry } from "../driver-catalog";
+export type LocalBrokeringDriverOptions = {
+    root: string;
+    executable: string;
+    args: string[];
+    allowedOrigins: readonly string[];
+    directOrigins: readonly string[];
+    upstreams?: Readonly<Record<string, string>>;
+    inheritedEnv?: Record<string, string>;
+};
+export declare function createLocalBrokeringSandboxDriver(options: LocalBrokeringDriverOptions): SandboxDriver & {
+    catalogEntry: typeof localBrokeringTestDriverCatalogEntry;
+};