@claxedo/sandbox-manager 0.9.0 → 0.10.0

package/dist/drivers/vercel.mjs

@@ -1,33 +1,4 @@
-// src/constants.ts
-var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
-
-// 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
+// src/egress-policy.ts
 function brokeredSecretPlaceholder(name) {
   return `claxedo-broker:${name}`;
 }
@@ -36,13 +7,43 @@ function brokeredPlaceholderEnv(secrets) {
 }
 
 // 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.runner) env.WORKSPACE_RUNTIME_RUNNER = input.runner;
+  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;
@@ -78,13 +79,43 @@ function shell(input) {
   return `'${input.replace(/'/g, `'"'"'`)}'`;
 }
 
+// src/constants.ts
+var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
+
 // src/defaults.ts
 var RUNTIME_DIR = "/opt/workspace-runtime";
 
+// 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 = {
-  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 }
@@ -98,68 +129,26 @@ var sandboxDriverCredentialFields = {
     { key: "api_token", label: "API Token", secret: true },
     { key: "worker_url", label: "Worker URL" }
   ],
-  box: [{ key: "api_key", label: "API Key", secret: true }],
+  boat: [{ 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",
+  boat: "Boat",
   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,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
@@ -182,6 +171,9 @@ var sandboxDriverCatalog = {
     id: "vercel",
     label: sandboxDriverLabels.vercel,
     credentialFields: sandboxDriverCredentialFields.vercel,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: false,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
@@ -204,30 +196,40 @@ var sandboxDriverCatalog = {
     id: "cloudflare",
     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: "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: sandboxDriverLabels.box,
-    credentialFields: sandboxDriverCredentialFields.box,
+  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",
@@ -240,13 +242,17 @@ var sandboxDriverCatalog = {
         captureSource: "not-applicable",
         retention: "provider-managed",
         restoreMount: "same-resource"
-      }
+      },
+      machineClasses: ["small", "default", "large"]
     }
   },
   docker: {
     id: "docker",
     label: sandboxDriverLabels.docker,
     credentialFields: sandboxDriverCredentialFields.docker,
+    runtimeNetwork: { controlPlane: "docker-host", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
     metadata: {
       driverRunsIn: ["local"],
       hostStopBehavior: "terminates-host",
@@ -287,7 +293,9 @@ function driverErrorSignals(err) {
   const shaped = isRecord(err) ? err : {};
   const nested = isRecord(shaped.response) ? shaped.response : {};
   return {
-    status: num(nested.status) ?? num(shaped.status),
+    // `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()
   };
 }
@@ -296,9 +304,28 @@ function isTransientDriverError(err, markers) {
   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/vercel.ts
 var DEFAULT_RUNTIME = "node22";
+var HARNESS_RELEASE_AGE_EXCLUSIONS = `printf '%s\\n' ${[
+  "@agentclientprotocol/sdk",
+  "@anthropic-ai/claude-*",
+  "@cursor/sdk*",
+  "@earendil-works/*",
+  "@openai/codex"
+].map((name) => `'min-release-age-exclude[]=${name}'`).join(" ")} >> "$HOME/.npmrc"`;
 var DEFAULT_RUNTIME_COMMAND = "/usr/local/bin/workspace-runtime";
 var DEFAULT_WORKSPACE_DIR = "/workspace";
 var DEFAULT_TIMEOUT_MS = 30 * 60 * 1e3;
@@ -346,8 +373,14 @@ function vercelBrokeredNetworkPolicy(secrets, base) {
     for (const host of secret.hosts) {
       const rules = allow[host] ??= [];
       for (const prefix of methods.length ? pathPrefixes : []) {
+        const path = credentialPathPattern(prefix);
+        if (path === void 0) continue;
         rules.push({
-          match: { path: { startsWith: prefix }, method: methods },
+          match: {
+            path: { regex: path },
+            method: methods,
+            headers: [{ key: { exact: secret.header.toLowerCase() }, value: { exact: `${secret.scheme ? `${secret.scheme} ` : ""}claxedo-broker:${secret.name}` } }]
+          },
           transform: [{ headers: { [secret.header]: value } }]
         });
       }
@@ -356,6 +389,17 @@ function vercelBrokeredNetworkPolicy(secrets, base) {
   const subnets = typeof base === "object" && base?.subnets ? { subnets: base.subnets } : {};
   return { allow, ...subnets };
 }
+var RE2_SPECIAL = /[\\.+*?()|[\]{}^$]/g;
+var PATH_CHAR = "(?:[^/\\\\%?#]|%(?:2[0-46-9a-dA-D]|5[0-9abd-fABD-F]|[013-46-9a-fA-F][0-9a-fA-F]))";
+var PATH_CHAR_NOT_DOT = "(?:[^./\\\\%?#]|%(?:2[0-46-9a-dA-D]|5[0-9abd-fABD-F]|[013-46-9a-fA-F][0-9a-fA-F]))";
+var SEGMENT = `(?:(?:${PATH_CHAR_NOT_DOT}|\\.${PATH_CHAR_NOT_DOT}|\\.\\.${PATH_CHAR})${PATH_CHAR}*)?`;
+function credentialPathPattern(prefix) {
+  if (!new RegExp(`^(?:/${SEGMENT})+$`).test(prefix)) return void 0;
+  const base = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  const literal = base.replace(RE2_SPECIAL, "\\$&");
+  const rest = prefix.endsWith("/") ? `/${SEGMENT}(?:/${SEGMENT})*` : `(?:/${SEGMENT})*`;
+  return `^${literal}${rest}(?:\\?.*)?$`;
+}
 function baseAllowEntries(base) {
   if (base === void 0 || base === "allow-all") return [["*", []]];
   if (base === "deny-all") return [];
@@ -409,14 +453,12 @@ function createVercelSandboxDriver(options) {
       host: "0.0.0.0",
       source: input.source,
       env: input.env,
-      runner: options.runner,
+      nativeHarness: options.nativeHarness,
       controlEnv: options.controlEnv
     });
   }
   async function runSetup(sandbox, command) {
-    await sandbox.runCommand("bash", ["-c", command], {
-      signal: AbortSignal.timeout(snapshotBuildTimeoutMs)
-    });
+    await withDeadlineSignal(snapshotBuildTimeoutMs, (signal) => sandbox.runCommand("bash", ["-c", command], { signal }));
   }
   async function ensureSnapshot() {
     if (options.baseSnapshotId) return options.baseSnapshotId;
@@ -440,7 +482,8 @@ function createVercelSandboxDriver(options) {
       });
       await runSetup(builder, "sudo dnf install -y git make gcc-c++ python3 > /dev/null 2>&1");
       await runSetup(builder, [
-        "npm i -g --min-release-age=2 tsx@4.22.3 opencode-ai@1.15.10 @anthropic-ai/claude-code@2.1.150 @openai/codex@0.133.0 @google/gemini-cli@0.43.0 @earendil-works/pi-coding-agent@0.75.5",
+        HARNESS_RELEASE_AGE_EXCLUSIONS,
+        "npm i -g --min-release-age=2 tsx@4.22.3 opencode-ai@1.15.10 @anthropic-ai/claude-code@2.1.285 @openai/codex@0.159.2",
         "curl https://cursor.com/install -fsS | bash",
         "curl -fsSL https://ampcode.com/install.sh | bash",
         "curl -fsSL https://app.factory.ai/cli | sh",
@@ -451,12 +494,10 @@ function createVercelSandboxDriver(options) {
         "command -v opencode",
         "command -v claude",
         "command -v codex",
-        "command -v gemini",
         "command -v agent",
         "command -v cursor-agent",
         "command -v amp",
-        "command -v droid",
-        "command -v pi"
+        "command -v droid"
       ].join(" && "));
       await runSetup(builder, [
         `sudo mkdir -p ${shell(RUNTIME_DIR)}`,
@@ -469,10 +510,7 @@ function createVercelSandboxDriver(options) {
         `sudo ln -sf ${RUNTIME_DIR}/node_modules/.bin/workspace-runtime /usr/local/bin/workspace-runtime`,
         "command -v workspace-runtime"
       ].join(" && "));
-      const snapshot = await builder.snapshot({
-        expiration: 0,
-        signal: AbortSignal.timeout(snapshotBuildTimeoutMs)
-      });
+      const snapshot = await withDeadlineSignal(snapshotBuildTimeoutMs, (signal) => builder.snapshot({ expiration: 0, signal }));
       cache.set(cacheKey, snapshot.snapshotId);
       cacheState.expires.set(cacheKey, now() + SNAPSHOT_CACHE_TTL_MS);
       return snapshot.snapshotId;
@@ -493,14 +531,14 @@ function createVercelSandboxDriver(options) {
   }
   async function startRuntime(sandbox, input, env) {
     const directory = workspaceDirectory(input);
-    await sandbox.runCommand({
+    await withDeadlineSignal(operationTimeoutMs, (signal) => sandbox.runCommand({
       cmd: "bash",
       args: ["-lc", `mkdir -p ${shell(directory)}; cd ${shell(directory)}; exec ${runtimeCommand}`],
       cwd: "/vercel/sandbox",
       env,
       detached: true,
-      signal: AbortSignal.timeout(operationTimeoutMs)
-    });
+      signal
+    }));
   }
   async function readyTarget(input, sandbox, hostId) {
     const url = sandbox.domain(runtimePort);
@@ -538,11 +576,11 @@ function createVercelSandboxDriver(options) {
       if (transientDriverError(err)) return void 0;
       throw err;
     });
-    if (!sandbox) return { provisioning: true, retryAfterMs: 2e3 };
+    if (!sandbox) return { provisioning: true, retryAfterMs: TRANSIENT_DRIVER_RETRY_MS };
+    await input.onImageReady?.();
     if (input.secrets?.length) {
-      await sandbox.updateNetworkPolicy(vercelBrokeredNetworkPolicy(input.secrets, createPolicy), {
-        signal: AbortSignal.timeout(operationTimeoutMs)
-      });
+      const secrets = input.secrets;
+      await withDeadlineSignal(operationTimeoutMs, (signal) => sandbox.updateNetworkPolicy(vercelBrokeredNetworkPolicy(secrets, createPolicy), { signal }));
     }
     await startRuntime(sandbox, input, env);
     return readyTarget(input, sandbox, hostId);
@@ -567,7 +605,7 @@ function createVercelSandboxDriver(options) {
     ensureHost,
     resumeHost: (input) => ensureHost(input.ensure),
     async touch(target) {
-      await (await sandboxById(target)).extendTimeout(keepAliveMs).catch(() => void 0);
+      await (await sandboxById(target)).extendTimeout(keepAliveMs);
     },
     async suspend(target) {
       await (await sandboxById(target)).stop({ blocking: false });
@@ -579,10 +617,8 @@ function createVercelSandboxDriver(options) {
       await (await sandboxById(target)).stop({ blocking: true });
     },
     async snapshot(target) {
-      const snapshot = await (await sandboxById(target)).snapshot({
-        expiration: 0,
-        signal: AbortSignal.timeout(snapshotBuildTimeoutMs)
-      });
+      const sandbox = await sandboxById(target);
+      const snapshot = await withDeadlineSignal(snapshotBuildTimeoutMs, (signal) => sandbox.snapshot({ expiration: 0, signal }));
       return { snapshotId: snapshot.snapshotId };
     }
   };

package/dist/egress-policy.d.ts

@@ -0,0 +1,134 @@
+export type SandboxNetworkPolicy = {
+    mode: "allow-all" | "restricted";
+    hosts?: string[];
+    cidrs?: string[];
+};
+/** Brokered destinations are the minimum egress needed to use the credential. */
+export declare function sandboxNetworkPolicyWithBrokeredHosts(policy: SandboxNetworkPolicy, secrets: readonly SandboxBrokeredSecret[] | undefined): SandboxNetworkPolicy;
+/** @see SandboxDriverMetadata.egressControl */
+export type SandboxEgressControl = "none" | "hosts" | "hosts-and-cidrs";
+/**
+ * What the manager does with a caller's `net` for a given driver: enforce
+ * where the driver can, and say so loudly rather than refuse where it cannot.
+ *
+ *  - `"enforce"` — the driver gets the policy verbatim and contains the
+ *    sandbox. Also the answer when the caller asked for no containment
+ *    (absent / `allow-all`), which is nothing to enforce.
+ *  - `"withhold"` — the driver declares `egressControl: "none"`, so there is no
+ *    containment to be had. The policy is NOT handed down: half the `"none"`
+ *    drivers throw on a restricted policy (docker, modal, boat) and the
+ *    other half silently drop it (cloudflare, the fetch bridge). Withholding at
+ *    the manager means the throwing drivers never see one — their throws stay
+ *    in place as their own last line of defence — and the silently-dropping
+ *    ones stop pretending. The sandbox comes up with UNRESTRICTED egress, which
+ *    is a real exposure, so the manager warns (see `onEgressUnenforced`).
+ *  - `"refuse"` — the driver HAS egress control but cannot express this
+ *    particular policy's encoding (a hosts-only driver handed an address-only
+ *    allowlist). Deliberately still fail-closed: this is a composition mistake
+ *    on an otherwise-enforcing driver, and degrading it to "withhold" would
+ *    weaken the enforcing path. `hostedSandboxNetworkPolicy` only ever emits
+ *    hosts, so no production path reaches it.
+ *
+ * Pure, like `validateSandboxPersistenceCapabilities`, so the manager, the
+ * composition layer, and tests can all ask the same question.
+ */
+export type SandboxEgressDisposition = {
+    action: "enforce";
+} | {
+    action: "withhold";
+    reason: "sandbox_egress_uncontained";
+} | {
+    action: "refuse";
+    reason: "sandbox_egress_policy_unenforceable";
+};
+/** @see SandboxEgressDisposition */
+export declare function sandboxEgressDisposition(control: SandboxEgressControl, net: SandboxNetworkPolicy | undefined): SandboxEgressDisposition;
+/**
+ * Emitted whenever a restricted egress policy is withheld because the composed
+ * driver declares no egress control: an unrestricted sandbox that nobody was
+ * told about is the exposure, so the degrade is never silent.
+ *
+ * Two phases, because a per-create line is easy to miss in request logs:
+ *  - `"composition"` — once per `createSandboxManager` per driver, at boot.
+ *  - `"ensure"` — every time a caller's policy is actually withheld, naming the
+ *    workspace and the allowlist that did not take effect.
+ */
+export type SandboxEgressUnenforcedEvent = {
+    phase: "composition" | "ensure";
+    reason: "sandbox_egress_uncontained";
+    /** `SandboxDriver.id` of the composed driver. */
+    driver: string;
+    /** Always `"none"` today — carried so a sink can group without re-deriving. */
+    egressControl: SandboxEgressControl;
+    /** Ready-to-log sentence. Sinks that only forward text can use this alone. */
+    message: string;
+    /** Present on `"ensure"`. */
+    workspaceId?: string;
+    /** The start's placement labels. Present on `"ensure"`. */
+    labels?: Record<string, string>;
+    /** The allowlist the caller asked for and did NOT get. Present on `"ensure"`. */
+    requested?: SandboxNetworkPolicy;
+};
+/**
+ * A credential the SANDBOX must be able to USE for outbound requests but must
+ * NEVER be able to READ. Unlike `env` (plaintext, readable — reserved for
+ * credentials the agent is trusted with, e.g. the user's own model
+ * subscription), a brokered secret's `value` never enters the sandbox: the
+ * provider injects it on egress to `hosts` only. Non-model credentials
+ * (connection tokens, deploy tokens) belong here.
+ *
+ * Guarantees enforced by the manager: brokered secrets are never written to
+ * labels, never logged, and never captured in a driver snapshot. A driver
+ * whose `metadata.secretBrokering` is not `"native"` cannot honor them and the
+ * manager refuses to provision (fail-closed).
+ */
+export type SandboxBrokeredSecret = {
+    /** Env var name the sandbox references. */
+    name: string;
+    /** The secret material. Never enters the sandbox in plaintext. */
+    value: string;
+    /** Egress allowlist: the only hosts for which the value is substituted/injected. */
+    hosts: string[];
+    /**
+     * The HTTP header the value is injected as on egress to `hosts`. Every
+     * native driver needs one and refuses a secret without it.
+     */
+    header?: string;
+    /**
+     * The authentication scheme `header` carries, when it has one (`Bearer`).
+     *
+     * A driver that WRITES the whole header composes `"<scheme> <value>"`; one
+     * that SUBSTITUTES a placeholder the sandbox already wrote after the scheme
+     * ignores it, because the scheme is in the request before the value is.
+     */
+    scheme?: string;
+    /**
+     * The methods and path prefixes the credential may be attached to, on top of
+     * `hosts`. A vendor host serves far more than the routes a turn needs —
+     * api.anthropic.com also answers the organization-admin API — and everything
+     * sharing the sandbox reaches the same host.
+     *
+     * Optional so a producer that has not been taught to state a policy still
+     * type-checks, and fails closed instead: a driver that can express them
+     * attaches the credential only within them, so an absent or empty policy
+     * names a host and nothing else, and nothing is spendable at a host alone. A
+     * driver whose provider cannot express them documents that it drops them,
+     * and the host allowlist is all the containment there is.
+     */
+    methods?: readonly string[];
+    pathPrefixes?: readonly string[];
+};
+/**
+ * What the sandbox presents so a header-injecting driver recognizes the request
+ * as one asking for that secret.
+ *
+ * Carries no authority: the value is attached at the edge, keyed by the host
+ * and this string, and the string itself is never accepted by a vendor. The
+ * Cloudflare sandbox Worker is deployed on its own and cannot depend on this
+ * package, so it matches on its own copy of the prefix; a driver minting
+ * anything else sends every brokered request upstream bare, which is what
+ * `brokered-placeholder.test.ts` exists to catch.
+ */
+export declare function brokeredSecretPlaceholder(name: string): string;
+/** The environment a header-injecting driver must add so the sandbox can present each secret. */
+export declare function brokeredPlaceholderEnv(secrets: readonly SandboxBrokeredSecret[] | undefined): Record<string, string>;

package/dist/egress-warnings.d.ts

@@ -0,0 +1,22 @@
+import type { SandboxEgressControl, SandboxEgressUnenforcedEvent, SandboxNetworkPolicy } from "./egress-policy";
+/**
+ * The two halves of the warning that a driver runs sandboxes with unrestricted
+ * egress. The composition half is raised here, once per driver per isolate: a
+ * per-create line lands in request logs and is easy to miss, this one lands
+ * wherever the process starts, so an operator learns of it BEFORE the first
+ * workspace exists. `withheld` is the start half, raised once per driver per
+ * isolate from the first start whose policy the driver could not enforce.
+ */
+export declare function createEgressWarnings(input: {
+    driver: {
+        id: string;
+        egressControl: SandboxEgressControl;
+    };
+    sink?: (event: SandboxEgressUnenforcedEvent) => void;
+}): {
+    withheld(start: {
+        workspaceId: string;
+        labels?: Record<string, string>;
+        requested: SandboxNetworkPolicy;
+    }): void;
+};

package/dist/garbage-collect.d.ts

@@ -0,0 +1,14 @@
+import { type SandboxDriver, type SandboxGarbageCollectResult, type SandboxLeaseStore } from "./contract";
+/**
+ * Destroys every sandbox the driver lists under `appLabel` that no lease owns.
+ * The lease store is authoritative for which provider resource a workspace
+ * owns, so the sweep reads the provider first and the leases second: a driver
+ * that cannot enumerate answers "we could not look", never "nothing is
+ * orphaned", because an empty listing reaching the sweep would make every live
+ * sandbox look like an orphan and destroy the fleet.
+ */
+export declare function sweepSandboxes(input: {
+    driver: SandboxDriver;
+    leaseStore: SandboxLeaseStore;
+    appLabel: string;
+}): Promise<SandboxGarbageCollectResult>;

package/dist/hosted-network-policy.d.ts

@@ -36,7 +36,8 @@
  * the only kind the Worker can compute, which is why `egressControl` treats
  * name filtering as the capability that qualifies a driver for hosted use.
  */
-import type { SandboxNetworkPolicy, SandboxSource } from ".";
+import type { SandboxSource } from "./contract";
+import type { SandboxNetworkPolicy } from "./egress-policy";
 /**
  * Model-provider endpoints. Derived from the harness→provider groups in
  * claxedo-server `network/types.ts` (`PROVIDER_TO_GROUP`): claude-sdk →
@@ -58,9 +59,15 @@ export declare const SANDBOX_BASELINE_EGRESS_HOSTS: readonly ["api.anthropic.com
  * The git host this workspace clones from.
  *
  * Scoped to the ONE repository host in the request rather than to a forge
- * allowlist, matching how `authenticatedGitHubCloneSource` scopes the clone
+ * allowlist, matching how `githubCloneSecret` scopes the clone
  * credential it brokers (`hosts: ["github.com"]`) — the credential and the
  * network policy should describe the same reachable surface.
+ *
+ * The host is caller-selected, so only a public spelling earns an allowlist
+ * entry: `169.254.169.254` or `localhost` named as a repoUrl would otherwise
+ * open the sandbox's egress to the provisioning network's own addresses. A
+ * DNS name cannot be seen through here (no resolver in this module); a name
+ * that hides a private answer is clone admission's refusal, not this one's.
  */
 export declare function sandboxSourceHost(source: SandboxSource | undefined): string | undefined;
 export type HostedSandboxNetworkPolicyInput = {