@claxedo/sandbox-manager 0.6.0 → 0.9.0

package/dist/drivers/cloudflare.mjs

@@ -1,7 +1,252 @@
 // 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
+function brokeredSecretPlaceholder(name) {
+  return `claxedo-broker:${name}`;
+}
+function brokeredPlaceholderEnv(secrets) {
+  return Object.fromEntries((secrets ?? []).map((secret) => [secret.name, brokeredSecretPlaceholder(secret.name)]));
+}
+
+// ../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"
+      }
+    }
+  }
+};
+
+// ../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;
+}
+
 // 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,
@@ -21,21 +266,57 @@ function workspaceRuntimeSourceEnv(input) {
 }
 
 // src/drivers/cloudflare.ts
+function registryEntries(input) {
+  if (!Array.isArray(input)) return [];
+  return input.flatMap((item) => {
+    const row = asRecord(item);
+    if (!row) return [];
+    const entries = Object.entries(row).filter((entry) => typeof entry[1] === "string");
+    return [Object.fromEntries(entries)];
+  });
+}
 var DEFAULT_WORKSPACE_DIR = "/workspace";
 var DEFAULT_RUNTIME_COMMAND = "/usr/local/bin/workspace-runtime";
 var DEFAULT_TIMEOUT_MS = 45e3;
+var DEFAULT_ENSURE_TIMEOUT_MS = 3e5;
+var WORKSPACE_DIRECTORY_LABEL = "claxedo.workspaceDirectory";
+function deadlineSignal(timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(new DOMException("The operation timed out", "TimeoutError")),
+    timeoutMs
+  );
+  return {
+    signal: controller.signal,
+    cleanup() {
+      clearTimeout(timer);
+    }
+  };
+}
+var RUNTIME_DATA_DIR = "/var/lib/claxedo";
+function captureDirectories(workspaceDirectory) {
+  return [workspaceDirectory, RUNTIME_DATA_DIR];
+}
 function cleanUrl(input) {
   return input.replace(/\/+$/, "");
 }
 function sandboxIdFor(workspaceId) {
   return `claxedo-${workspaceId}`;
 }
+var CloudflareSandboxListingUnsupportedError = class extends Error {
+  listingUnsupported = true;
+  constructor(message) {
+    super(message);
+    this.name = "CloudflareSandboxListingUnsupportedError";
+  }
+};
 function createCloudflareSandboxDriver(options) {
   const doFetch = options.fetch ?? fetch;
   const runtimePort = options.runtimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT;
   const runtimeCommand = options.runtimeCommand ?? DEFAULT_RUNTIME_COMMAND;
   const workspaceDir = options.workspaceDir ?? DEFAULT_WORKSPACE_DIR;
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const ensureTimeoutMs = options.timeoutMs ?? DEFAULT_ENSURE_TIMEOUT_MS;
   const base = cleanUrl(options.workerUrl);
   const headers = {
     Authorization: `Bearer ${options.apiToken}`,
@@ -43,49 +324,64 @@ function createCloudflareSandboxDriver(options) {
   };
   async function call(sandboxId, action, body, method = "POST") {
     const url = `${base}/sandbox/${encodeURIComponent(sandboxId)}${action ? `/${action}` : ""}`;
-    const res = await doFetch(url, {
-      method,
-      headers,
-      ...method === "POST" ? { body: JSON.stringify(body) } : {},
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    const data = await res.json().catch(() => ({}));
-    return { status: res.status, data };
+    const deadline = deadlineSignal(action === "ensure-runtime" ? ensureTimeoutMs : timeoutMs);
+    try {
+      const res = await doFetch(url, {
+        method,
+        headers,
+        ...method === "POST" ? { body: JSON.stringify(body) } : {},
+        signal: deadline.signal
+      });
+      const data = asRecord(await res.json().catch(() => ({}))) ?? {};
+      return { status: res.status, data };
+    } finally {
+      deadline.cleanup();
+    }
   }
   function workspaceDirectory(input) {
     return input.workspaceRoot ?? workspaceDir;
   }
   async function bootEnv(input, hostId) {
-    const env = {
-      ...workspaceRuntimeTargetEnv({
-        workspaceId: input.workspaceId,
-        hostId,
-        directory: workspaceDirectory(input),
-        port: runtimePort,
-        host: "0.0.0.0"
-      }),
-      ...workspaceRuntimeSourceEnv({ source: input.source }),
-      ...input.env,
-      ...await options.env?.(input, { id: hostId })
-    };
-    if (options.runner) env.WORKSPACE_RUNTIME_RUNNER = options.runner;
-    if (options.controlEnv?.relayJwksUrl) env.WORKSPACE_RUNTIME_RELAY_JWKS_URL = options.controlEnv.relayJwksUrl;
-    if (options.controlEnv?.relayVerifyPem) env.WORKSPACE_RUNTIME_RELAY_HOST_VERIFY_PEM = options.controlEnv.relayVerifyPem;
-    if (options.controlEnv?.managementJwksUrl) env.WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL = options.controlEnv.managementJwksUrl;
-    return env;
+    return workspaceRuntimeBootEnv({
+      workspaceId: input.workspaceId,
+      hostId,
+      directory: workspaceDirectory(input),
+      port: runtimePort,
+      host: "0.0.0.0",
+      source: input.source,
+      env: {
+        // Must match the checkpoint capture set below.
+        CLAXEDO_DATA_DIR: RUNTIME_DATA_DIR,
+        ...input.env,
+        ...await options.env?.(input, { id: hostId }),
+        // Last, so no caller-supplied variable of the same name can stand in
+        // for a placeholder the outbound handler matches on.
+        ...brokeredPlaceholderEnv(input.secrets)
+      },
+      runner: options.runner,
+      controlEnv: options.controlEnv
+    });
   }
   function egressRegistrations(input) {
-    if (!input.secrets?.length) return void 0;
+    if (input.secrets === void 0) return void 0;
     return input.secrets.map((secret) => {
       if (!secret.header) {
         throw new Error(
-          `cloudflare brokered secret "${secret.name}" requires a header \u2014 the egress proxy injects the value as an HTTP header`
+          `cloudflare brokered secret "${secret.name}" requires a header for native outbound injection`
         );
       }
       if (secret.hosts.length === 0) {
         throw new Error(`cloudflare brokered secret "${secret.name}" requires at least one host in its egress allowlist`);
       }
-      return { hosts: secret.hosts, header: secret.header, value: secret.value };
+      const value = secret.scheme ? `${secret.scheme} ${secret.value}` : secret.value;
+      return {
+        name: secret.name,
+        hosts: secret.hosts,
+        header: secret.header,
+        value,
+        methods: [...secret.methods ?? []],
+        pathPrefixes: [...secret.pathPrefixes ?? []]
+      };
     });
   }
   async function ensureHost(input) {
@@ -99,6 +395,11 @@ function createCloudflareSandboxDriver(options) {
         env: await bootEnv(input, hostId),
         port: runtimePort,
         command: runtimeCommand,
+        // Sent so the Worker can record them in its sandbox registry, which is
+        // what makes this driver's `list()` (and therefore GC) possible at all.
+        // Not container env — labels are control-plane metadata.
+        labels: input.labels,
+        ...input.bootSource?.kind === "driver-snapshot" ? { restore: { backupId: input.bootSource.snapshotId, directories: captureDirectories(workspaceDirectory(input)) } } : {},
         ...egress ? { egress } : {}
       }
     ).catch((error) => {
@@ -107,32 +408,106 @@ function createCloudflareSandboxDriver(options) {
     });
     if (!response) return { provisioning: true, retryAfterMs: 2e3 };
     const { status, data } = response;
-    if (status >= 500) return { provisioning: true, retryAfterMs: 2e3 };
-    if (status >= 400 || !data?.url) {
-      throw new Error(`Cloudflare ensure-runtime failed (${status}): ${data?.error ?? "no runtime url"}`);
+    const runtimeUrl = text(data.url);
+    if (status === 503 && data.error === "workspace-runtime did not become ready") {
+      return { provisioning: true, retryAfterMs: 2e3 };
+    }
+    if (status >= 400 || !runtimeUrl) {
+      throw new Error(`Cloudflare ensure-runtime failed (${status}): ${text(data.error) ?? "no runtime url"}`);
     }
     const targetOut = {
       workspaceId: input.workspaceId,
       sandboxId,
-      url: data.url,
+      url: runtimeUrl,
       hostId,
       driverResourceId: sandboxId,
       driver: {
         id: "cloudflare",
         resourceId: sandboxId
       },
-      labels: input.labels
+      labels: {
+        ...input.labels,
+        [WORKSPACE_DIRECTORY_LABEL]: workspaceDirectory(input)
+      }
     };
     return targetOut;
   }
   return {
     id: "cloudflare",
+    // Provider-state enumeration, served by the sandbox Worker's registry
+    // (`GET /sandboxes`) rather than by Cloudflare's own APIs.
+    //
+    // Why a registry is REQUIRED here, checked against the installed SDK
+    // (@cloudflare/sandbox 0.8.9) rather than assumed:
+    //
+    //  1. The SDK has no enumeration surface. `getSandbox(ns, id)` is
+    //     get-or-create against a Durable Object; nothing in its exports lists
+    //     a namespace. `listDurableObjectIds` is `cloudflare:test`-only.
+    //  2. The account-level REST list-objects endpoint returns
+    //     `{ id: <hex>, hasStoredData }` and nothing else. `idFromName` is
+    //     one-way, so a hex id cannot be mapped back to `claxedo-<workspaceId>`
+    //     — no name means no labels, no `app` ownership check, and no safe
+    //     destroy. A sweep over hex ids could only guess what it was deleting.
+    //  3. It would also need account-level CF credentials this driver
+    //     deliberately does not hold; it authenticates to one user-deployed
+    //     Worker with that Worker's own bearer token.
+    //
+    // So the Worker records each sandbox on `ensure-runtime` and drops it on
+    // destroy — the pattern Cloudflare recommends for precisely this reason.
+    //
+    // A Worker predating that route (or deployed with no R2 binding) answers
+    // 404/501, which THROWS `CloudflareSandboxListingUnsupportedError` rather
+    // than returning `[]`. An empty list from an old Worker would mean "nothing
+    // is orphaned" and hand GC a silent success — the defect this whole
+    // workstream removes. The manager turns that throw back into
+    // `listingUnsupported`, so an un-upgraded Worker is loudly visible.
+    async list() {
+      const deadline = deadlineSignal(timeoutMs);
+      try {
+        const res = await doFetch(`${base}/sandboxes`, {
+          method: "GET",
+          headers,
+          signal: deadline.signal
+        });
+        const data = asRecord(await res.json().catch(() => ({}))) ?? {};
+        if (res.status === 404 || res.status === 501 || data.supported === false) {
+          throw new CloudflareSandboxListingUnsupportedError(
+            text(data.error) ?? `Cloudflare sandbox Worker cannot enumerate sandboxes (${res.status}) \u2014 deploy a Worker with the /sandboxes registry route and an R2 BACKUP_BUCKET binding`
+          );
+        }
+        if (!res.ok) {
+          throw new Error(`Cloudflare sandbox listing failed (${res.status}): ${text(data.error) ?? "unknown error"}`);
+        }
+        return registryEntries(data.sandboxes).flatMap((entry) => {
+          const sandboxId = entry.sandboxId;
+          if (!sandboxId) return [];
+          const { sandboxId: _id, ...labels } = entry;
+          const target = {
+            ...labels.workspaceId ? { workspaceId: labels.workspaceId } : {},
+            sandboxId,
+            // Identity, not a reachable address — GC only names what it destroys.
+            url: `${base}/sandbox/${encodeURIComponent(sandboxId)}/proxy`,
+            // Matches `ensureHost`'s `hostId = sandboxId`, so a live sandbox
+            // cannot fail GC's identity check and be destroyed as an orphan.
+            hostId: sandboxId,
+            driverResourceId: sandboxId,
+            labels,
+            driver: { id: "cloudflare", resourceId: sandboxId }
+          };
+          return [target];
+        });
+      } finally {
+        deadline.cleanup();
+      }
+    },
     metadata: {
       driverRunsIn: ["worker"],
       hostStopBehavior: "not-supported",
       hostResumeBehavior: "same-host",
       targetAccess: "relay",
-      secretBrokering: "proxy"
+      secretBrokering: "native",
+      egressControl: "none",
+      persistence: sandboxDriverCatalog.cloudflare.metadata.persistence
     },
     ensureHost,
     async touch(target) {
@@ -146,9 +521,23 @@ function createCloudflareSandboxDriver(options) {
       if (status >= 400 && status !== 404) {
         throw new Error(`Cloudflare destroy failed (${status}) for ${target.sandboxId}`);
       }
+    },
+    async snapshot(target) {
+      const directory = target.labels?.[WORKSPACE_DIRECTORY_LABEL] ?? workspaceDir;
+      const { status, data } = await call(
+        target.sandboxId,
+        "backup",
+        { directories: captureDirectories(directory) }
+      );
+      const backupId = text(data.backupId);
+      if (status >= 400 || !backupId) {
+        throw new Error(`Cloudflare backup failed (${status}): ${text(data.error) ?? "no backup id"}`);
+      }
+      return { snapshotId: backupId };
     }
   };
 }
 export {
+  CloudflareSandboxListingUnsupportedError,
   createCloudflareSandboxDriver
 };

package/dist/drivers/daytona.d.ts

@@ -1,4 +1,5 @@
 import type { SandboxDriver, SandboxDriverEnsureInput } from "..";
+import { type WorkspaceRuntimeControlEnv } from "../runtime-env";
 export type DaytonaSandboxLike = {
     id: string;
     state?: string;
@@ -18,9 +19,40 @@ export type DaytonaSandboxLike = {
     start: (timeout?: number) => Promise<void>;
     stop: (timeout?: number) => Promise<void>;
     delete: (timeout?: number) => Promise<void>;
+    updateSecrets: (secrets: Record<string, string>) => Promise<void>;
+    /**
+     * Replace the sandbox's outbound egress policy in place, without stopping it
+     * — the Daytona SDK's `Sandbox.updateNetworkSettings`, which drives the same
+     * runner-side iptables mechanism as `create`'s `networkBlockAll` /
+     * `networkAllowList` / `domainAllowList`. This is what makes the create-time
+     * policy reappliable on reuse and resume; see `applyNetworkPolicy` below.
+     *
+     * Optional because a client injected by an embedder may predate it. When it
+     * is absent and a restricted policy was requested, reuse is REFUSED rather
+     * than silently served on the creation-time policy.
+     */
+    updateNetworkSettings?: (settings: {
+        networkBlockAll?: boolean;
+        networkAllowList?: string;
+        domainAllowList?: string;
+    }) => Promise<void>;
+    _experimental_createSnapshot?: (name: string, timeout?: number) => Promise<void>;
 };
 export type DaytonaClientLike = {
     findByLabels?: (labels: Record<string, string>) => Promise<DaytonaSandboxLike | undefined>;
+    /**
+     * One page of sandboxes matching `labels`. Pages are 1-based; a page that
+     * returns fewer than `limit` items (or none) is the last one — that is the
+     * termination rule `list()` below relies on, and any implementation must
+     * honor it or the sweep loops forever.
+     *
+     * `createDefaultClient` satisfies it by returning every match on page 1 and
+     * nothing after: the Daytona SDK's `list()` is an `AsyncIterableIterator`
+     * that paginates internally, so `limit` is its per-page fetch size and NOT a
+     * cap on the total (see @daytona/sdk `ListSandboxesQuery.limit`). There is no
+     * cursor to hand back, so re-slicing per page would re-walk the whole account
+     * on every call.
+     */
     list?: (labels?: Record<string, string>, page?: number, limit?: number) => Promise<{
         items?: DaytonaSandboxLike[];
     }>;
@@ -36,23 +68,53 @@ export type DaytonaClientLike = {
         autoStopInterval?: number;
         autoDeleteInterval?: number;
         networkBlockAll?: boolean;
+        /** Comma-separated allowed CIDR network addresses. */
         networkAllowList?: string;
+        /** Comma-separated allowed domains — the name-based egress allowlist. */
+        domainAllowList?: string;
     }, options?: {
         timeout?: number;
     }) => Promise<DaytonaSandboxLike>;
     get: (sandboxIdOrName: string) => Promise<DaytonaSandboxLike>;
     /**
-     * Create-or-update an org secret whose value is only substituted by
-     * Daytona's egress proxy for requests to `hosts`
-     * (https://www.daytona.io/docs/en/secrets/). Referenced from `create`'s
-     * `secrets` map; inside the sandbox the env var holds only an opaque
-     * `dtn_secret_…` placeholder, never the value.
+     * The org-secret service, in the SDK's own shape so `createDefaultClient`
+     * hands `sdk.secret` straight through. Upsert and withdrawal POLICY lives in
+     * this driver (`reconcileBrokeredSecrets`) rather than behind a
+     * `upsertSecret` client method: `create` is a conflict on an existing name,
+     * so a client-level "upsert" is a second implementation of the lookup every
+     * embedder would have to get right.
      */
-    upsertSecret?: (params: {
+    secret?: DaytonaSecretServiceLike;
+};
+/** Identity of an org secret. The plaintext value is write-only and never returned. */
+export type DaytonaSecretLike = {
+    id: string;
+    name: string;
+};
+export type DaytonaSecretServiceLike = {
+    /**
+     * `name` is a PARTIAL match, and pages are cursor-based; callers filter the
+     * page themselves and follow `nextCursor` until it is null.
+     */
+    list: (query?: {
+        name?: string;
+        cursor?: string;
+        limit?: number;
+    }) => Promise<{
+        items: DaytonaSecretLike[];
+        nextCursor?: string | null;
+    }>;
+    /** Throws `DaytonaConflictError` when a secret of that name already exists. */
+    create: (params: {
         name: string;
         value: string;
-        hosts: string[];
-    }) => Promise<void>;
+        hosts?: string[];
+    }) => Promise<DaytonaSecretLike>;
+    update: (secretId: string, params: {
+        value?: string;
+        hosts?: string[];
+    }) => Promise<unknown>;
+    delete: (secretId: string) => Promise<void>;
 };
 export type DaytonaSandboxDriverOptions = {
     /** Daytona API base URL. Defaults to the SDK default. */
@@ -74,11 +136,7 @@ export type DaytonaSandboxDriverOptions = {
     /** Default runner injected as WORKSPACE_RUNTIME_RUNNER. */
     runner?: string;
     /** Static control-plane config injected so the runtime verifies relay-proxied requests. */
-    controlEnv?: {
-        relayJwksUrl?: string;
-        relayVerifyPem?: string;
-        managementJwksUrl?: string;
-    };
+    controlEnv?: WorkspaceRuntimeControlEnv;
     /** Dynamic runtime env that needs the acquired sandbox id or current lease. */
     env?: (input: SandboxDriverEnsureInput, sandbox: DaytonaSandboxLike) => Record<string, string> | Promise<Record<string, string>>;
     /** Auto-stop / auto-delete policy, in minutes. */
@@ -90,5 +148,16 @@ export type DaytonaSandboxDriverOptions = {
     operationTimeoutSeconds?: number;
     /** Injected for tests. */
     client?: DaytonaClientLike;
+    /**
+     * Sink for the two operator-visible events this driver has no other way to
+     * report: a restart it had to force on a live sandbox, and an org secret
+     * under this workspace's prefix that it did not mint and therefore emptied
+     * without mounting.
+     *
+     * Defaults to `console.warn`, deliberately unconditional — the same
+     * reasoning as `onEgressUnenforced` in index.ts. Pass your own to route them
+     * into a logger; pass `() => {}` only if you have another way to see them.
+     */
+    warn?: (message: string) => void;
 };
 export declare function createDaytonaSandboxDriver(options: DaytonaSandboxDriverOptions): SandboxDriver;