@claxedo/sandbox-manager 0.7.0 → 0.10.0

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,11 +36,12 @@
  * 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-acp and
- * claude-sdk → anthropic, codex-acp/codex-app-server/cursor-acp → openai,
+ * claxedo-server `network/types.ts` (`PROVIDER_TO_GROUP`): claude-sdk →
+ * anthropic, codex-app-server/cursor-sdk → openai,
  * google → google_ai; plus the aggregator and catalog endpoints the engine
  * itself fetches at startup.
  */
@@ -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 = {

package/dist/hosted-network-policy.mjs

@@ -1,3 +1,220 @@
+// ../sandbox-contract/dist/index.mjs
+function ipv4Number(part) {
+  let value;
+  if (/^0[xX][0-9a-fA-F]+$/.test(part))
+    value = Number.parseInt(part.slice(2), 16);
+  else if (/^0[0-7]+$/.test(part))
+    value = Number.parseInt(part.slice(1), 8);
+  else if (/^\d+$/.test(part))
+    value = Number.parseInt(part, 10);
+  else
+    return;
+  return Number.isSafeInteger(value) ? value : void 0;
+}
+function parseIpv4(input) {
+  const parts = input.split(".");
+  if (parts.length > 1 && parts[parts.length - 1] === "")
+    parts.pop();
+  if (parts.length < 1 || parts.length > 4)
+    return;
+  const numbers = [];
+  for (const part of parts) {
+    const value = ipv4Number(part);
+    if (value === void 0)
+      return;
+    numbers.push(value);
+  }
+  const last = numbers[numbers.length - 1];
+  if (last >= 256 ** (5 - numbers.length))
+    return;
+  for (const value of numbers.slice(0, -1))
+    if (value > 255)
+      return;
+  let address = last;
+  for (let i = 0; i < numbers.length - 1; i++)
+    address += numbers[i] * 256 ** (3 - i);
+  return address >>> 0;
+}
+function hextet(part) {
+  return /^[0-9a-fA-F]{1,4}$/.test(part) ? Number.parseInt(part, 16) : void 0;
+}
+function embeddedQuad(input) {
+  const parts = input.split(".");
+  if (parts.length !== 4)
+    return;
+  const octets = [];
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part))
+      return;
+    const value = Number.parseInt(part, 10);
+    if (value > 255)
+      return;
+    octets.push(value);
+  }
+  return octets;
+}
+function parseIpv6(input) {
+  let body = input;
+  let tail;
+  const lastColon = body.lastIndexOf(":");
+  if (lastColon >= 0 && body.includes(".")) {
+    tail = embeddedQuad(body.slice(lastColon + 1));
+    if (!tail)
+      return;
+    body = body.slice(0, lastColon + 1) + "0:0";
+  }
+  if ((body.match(/::/g) ?? []).length > 1)
+    return;
+  let halves;
+  if (body.includes("::")) {
+    const [left = "", right = ""] = body.split("::");
+    const leftParts = left === "" ? [] : left.split(":");
+    const rightParts = right === "" ? [] : right.split(":");
+    const missing = 8 - leftParts.length - rightParts.length;
+    if (missing < 1)
+      return;
+    halves = [...leftParts, ...Array.from({ length: missing }, () => "0"), ...rightParts];
+  } else {
+    halves = body.split(":");
+    if (halves.length !== 8)
+      return;
+  }
+  if (halves.length !== 8)
+    return;
+  const segments = [];
+  for (const part of halves) {
+    const value = hextet(part);
+    if (value === void 0)
+      return;
+    segments.push(value);
+  }
+  if (tail) {
+    segments[6] = tail[0] * 256 + tail[1];
+    segments[7] = tail[2] * 256 + tail[3];
+  }
+  return segments;
+}
+function parseIpAddress(input) {
+  if (!input)
+    return;
+  let host = input.trim().toLowerCase();
+  if (host.startsWith("[") && host.endsWith("]") && host.includes(":"))
+    host = host.slice(1, -1);
+  if (host.includes(":")) {
+    const segments = parseIpv6(host);
+    return segments ? { kind: "v6", segments } : void 0;
+  }
+  const value = parseIpv4(host);
+  return value === void 0 ? void 0 : { kind: "v4", value };
+}
+var V4_PRIVATE = [
+  [0, 8],
+  [167772160, 8],
+  [1681915904, 10],
+  [2130706432, 8],
+  [2851995648, 16],
+  [2886729728, 12],
+  [3221225472, 24],
+  [3221225984, 24],
+  [3223307264, 24],
+  [3224682752, 24],
+  [3227017984, 24],
+  [3232235520, 16],
+  [3232706560, 24],
+  [3323068416, 15],
+  [3325256704, 24],
+  [3405803776, 24],
+  [3758096384, 4],
+  [4026531840, 4]
+];
+function inCidr(value, base, bits) {
+  return (value ^ base) >>> 32 - bits === 0;
+}
+function isPrivateIpv4(value) {
+  return V4_PRIVATE.some(([base, bits]) => inCidr(value, base, bits));
+}
+function embeddedIpv4(segments) {
+  const [a, b, c, d, e, f, g, h] = segments;
+  if (a === 0 && b === 0 && c === 0 && d === 0 && e === 0) {
+    if (f === 65535 || f === 0)
+      return g * 65536 + h >>> 0;
+  }
+  if (a === 100 && b === 65435 && c === 0 && d === 0 && e === 0 && f === 0)
+    return g * 65536 + h >>> 0;
+  if (a === 8194)
+    return b * 65536 + c >>> 0;
+  if (a === 8193 && b === 0)
+    return (g ^ 65535) * 65536 + (h ^ 65535) >>> 0;
+  return;
+}
+function isUnspecified(segments) {
+  return segments.every((segment) => segment === 0);
+}
+function isIpv6Loopback(segments) {
+  return segments.slice(0, 7).every((segment) => segment === 0) && segments[7] === 1;
+}
+function isPrivateIpAddress(ip) {
+  if (ip.kind === "v4")
+    return isPrivateIpv4(ip.value);
+  const segments = ip.segments;
+  if (isUnspecified(segments) || isIpv6Loopback(segments))
+    return true;
+  const first = segments[0];
+  if ((first & 65280) === 65280)
+    return true;
+  if ((first & 65024) === 64512)
+    return true;
+  if ((first & 65472) === 65152)
+    return true;
+  if ((first & 65472) === 65216)
+    return true;
+  if (first === 256 && segments[1] === 0 && segments[2] === 0 && segments[3] === 0)
+    return true;
+  if (first === 8193 && segments[1] === 3512)
+    return true;
+  const embedded = embeddedIpv4(segments);
+  if (embedded !== void 0)
+    return isPrivateIpv4(embedded);
+  return false;
+}
+function safeRepoUrl(input) {
+  try {
+    const url = new URL(input);
+    return url.protocol === "https:" || url.protocol === "http:" || url.protocol === "ssh:" ? input : void 0;
+  } catch {
+    return /^[\w.-]+@[\w.-]+:[\w./-]+$/.test(input) ? input : void 0;
+  }
+}
+function repoUrlHost(input) {
+  if (!safeRepoUrl(input))
+    return;
+  try {
+    const host = new URL(input).hostname;
+    return host || void 0;
+  } catch {
+    return /^[\w.-]+@([\w.-]+):[\w./-]+$/.exec(input)?.[1]?.toLowerCase();
+  }
+}
+function bareRepoHost(host) {
+  const bare = host.trim().toLowerCase();
+  return bare.startsWith("[") && bare.endsWith("]") && bare.includes(":") ? bare.slice(1, -1) : bare;
+}
+function loopbackRepoName(bare) {
+  return bare === "localhost" || bare.endsWith(".localhost");
+}
+function publicRepoHost(repoUrl) {
+  const host = repoUrlHost(repoUrl);
+  if (!host)
+    return;
+  const bare = bareRepoHost(host);
+  if (loopbackRepoName(bare))
+    return;
+  const ip = parseIpAddress(bare);
+  if (ip && isPrivateIpAddress(ip))
+    return;
+  return host;
+}
+
 // src/hosted-network-policy.ts
 var SANDBOX_MODEL_PROVIDER_HOSTS = [
   "api.anthropic.com",
@@ -25,17 +242,17 @@ var SANDBOX_BASELINE_EGRESS_HOSTS = [
 ];
 function hostOf(value) {
   const raw = value?.trim();
-  if (!raw) return;
+  if (!raw) return void 0;
   try {
     const host = new URL(raw).hostname.trim().toLowerCase();
     return host ? host : void 0;
   } catch {
-    return;
+    return void 0;
   }
 }
 function sandboxSourceHost(source) {
-  if (!source || source.kind !== "git") return;
-  return hostOf(source.repoUrl);
+  if (!source || source.kind !== "git") return void 0;
+  return publicRepoHost(source.repoUrl);
 }
 function hostedSandboxNetworkPolicy(input) {
   const hosts = /* @__PURE__ */ new Set();

package/dist/image-name.d.ts

@@ -2,6 +2,16 @@ export declare const SNAPSHOT_SCHEMA_VERSION = 8;
 export declare const DEFAULT_SANDBOX_IMAGE_REPOSITORY = "ghcr.io/kyashrathore/claxedo-sandbox";
 export type SandboxImageEnv = Record<string, string | undefined>;
 export declare function snapshotVersion(value: string): string;
+/**
+ * A caller-supplied image string lands verbatim inside provider argv or
+ * commands (`docker create` argv, `docker run` inside a Boat VM). A value that
+ * parses as an option — a leading `-` — or that splits into multiple words
+ * would be consumed as provider flags, not as an image reference.
+ */
+export declare function assertSandboxImageReference(image: string): string;
 export declare function sandboxImageRepository(env?: SandboxImageEnv): string;
-export declare function defaultSandboxImage(version?: string, buildId?: string, env?: SandboxImageEnv): string;
-export declare function defaultSnapshotName(version?: string, buildId?: string, env?: SandboxImageEnv): string;
+export declare function defaultSandboxImage(version?: string, buildId?: string, env?: SandboxImageEnv, options?: {
+    agentPlugins?: boolean;
+}): string;
+/** Whether an image's tag names a build that carries the Agent Plugins runtime entry. */
+export declare function sandboxImageCarriesAgentPlugins(image: string): boolean;

package/dist/image-name.mjs

@@ -0,0 +1,43 @@
+// src/runtime-version.ts
+var DEFAULT_WORKSPACE_RUNTIME_VERSION = "0.5.2";
+function workspaceRuntimeVersion() {
+  return process.env.WORKSPACE_RUNTIME_VERSION || DEFAULT_WORKSPACE_RUNTIME_VERSION;
+}
+
+// src/image-name.ts
+var SNAPSHOT_SCHEMA_VERSION = 8;
+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;
+}
+function buildIdSuffix(buildId, env) {
+  const id = (buildId ?? env.CLAXEDO_SANDBOX_BUILD_ID)?.trim();
+  return id ? `-${snapshotVersion(id)}` : "";
+}
+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}`;
+}
+function sandboxImageCarriesAgentPlugins(image) {
+  return new RegExp(`${AGENT_PLUGINS_TAG}-v\\d+$`).test(image);
+}
+export {
+  DEFAULT_SANDBOX_IMAGE_REPOSITORY,
+  SNAPSHOT_SCHEMA_VERSION,
+  assertSandboxImageReference,
+  defaultSandboxImage,
+  sandboxImageCarriesAgentPlugins,
+  sandboxImageRepository,
+  snapshotVersion
+};

package/dist/image.d.ts

@@ -1,23 +1,4 @@
-import { Daytona, Image } from "@daytona/sdk";
 export { RUNTIME_DIR, WORKSPACE_RUNTIME_PORT, WORKSPACE_DIR } from "./defaults";
-export { SNAPSHOT_SCHEMA_VERSION, snapshotVersion, defaultSandboxImage, defaultSnapshotName, } from "./image-name";
-/**
- * Sink for snapshot-build progress. Every message here reports a long
- * operation an operator is actively waiting on — a snapshot build takes
- * minutes, and the Daytona builder's `onLogs` stream is the only view into
- * whether it is progressing or wedged.
- *
- * Defaults to `console.info`, deliberately unconditional: the same reasoning as
- * `onEgressUnenforced` in index.ts — someone who never wires a sink still sees
- * the build. Pass your own to route it into a logger; pass `() => {}` only if
- * you have another way to observe the build.
- */
-export type SandboxImageLogSink = (message: string, context?: Record<string, unknown>) => void;
-export type SandboxImageOptions = {
-    log?: SandboxImageLogSink;
-};
+export { SNAPSHOT_SCHEMA_VERSION, snapshotVersion, assertSandboxImageReference, defaultSandboxImage, } from "./image-name";
 export declare const SANDBOX_IMAGE_REPOSITORY: string;
 export declare const SANDBOX_IMAGE: string;
-export declare const SNAPSHOT_NAME: string;
-export declare function buildSandboxImage(): Image;
-export declare function ensureSnapshot(daytona: Daytona, options?: SandboxImageOptions): Promise<string>;

package/dist/image.mjs

@@ -1,6 +1,3 @@
-// src/image.ts
-import { Image, DaytonaNotFoundError } from "@daytona/sdk";
-
 // src/constants.ts
 var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
 
@@ -21,6 +18,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;
@@ -29,81 +32,23 @@ 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
-function defaultImageLogSink(message, context) {
-  if (context) console.info(message, context);
-  else console.info(message);
-}
 var SANDBOX_IMAGE_REPOSITORY = sandboxImageRepository();
 var SANDBOX_IMAGE = process.env.CLAXEDO_SANDBOX_IMAGE || defaultSandboxImage();
-var SNAPSHOT_NAME = process.env.CLAXEDO_SNAPSHOT_NAME || defaultSnapshotName();
-function buildSandboxImage() {
-  return Image.base(SANDBOX_IMAGE);
-}
-function snapshotUsable(state) {
-  return state === "ready" || state === "active";
-}
-async function createSnapshot(daytona, log) {
-  log("Creating sandbox snapshot (this may take a few minutes)...", { name: SNAPSHOT_NAME });
-  await daytona.snapshot.create(
-    { name: SNAPSHOT_NAME, image: buildSandboxImage() },
-    {
-      timeout: 120,
-      onLogs: (chunk) => log("[snapshot]", { text: chunk })
-    }
-  );
-  return SNAPSHOT_NAME;
-}
-async function ensureSnapshot(daytona, options = {}) {
-  const log = options.log ?? defaultImageLogSink;
-  try {
-    const existing = await daytona.snapshot.get(SNAPSHOT_NAME);
-    if (existing.state === "inactive") {
-      log("Snapshot is inactive, reactivating...", { name: SNAPSHOT_NAME, id: existing.id });
-      await daytona.snapshot.activate({ id: existing.id });
-      for (let i = 0; i < 120; i++) {
-        const snap = await daytona.snapshot.get(SNAPSHOT_NAME);
-        if (snapshotUsable(snap.state)) return SNAPSHOT_NAME;
-        if (snap.state === "error") throw new Error(`Snapshot activation failed: ${snap.errorReason}`);
-        await new Promise((resolve) => setTimeout(resolve, 2e3));
-      }
-      throw new Error("Snapshot activation timed out");
-    }
-    if (existing.state === "building") {
-      log("Snapshot is building, waiting (up to 10 min)...", { name: SNAPSHOT_NAME });
-      for (let i = 0; i < 300; i++) {
-        const snap = await daytona.snapshot.get(SNAPSHOT_NAME);
-        if (snapshotUsable(snap.state)) return SNAPSHOT_NAME;
-        if (snap.state === "error") throw new Error(`Snapshot build failed: ${snap.errorReason}`);
-        if (i % 15 === 0) log("Still waiting for snapshot...", { state: snap.state, elapsed: `${i * 2}s` });
-        await new Promise((resolve) => setTimeout(resolve, 2e3));
-      }
-      throw new Error("Snapshot build timed out after 10 minutes");
-    }
-    return SNAPSHOT_NAME;
-  } catch (err) {
-    if (!(err instanceof DaytonaNotFoundError)) throw err;
-  }
-  return createSnapshot(daytona, log);
-}
 export {
   RUNTIME_DIR,
   SANDBOX_IMAGE,
   SANDBOX_IMAGE_REPOSITORY,
-  SNAPSHOT_NAME,
   SNAPSHOT_SCHEMA_VERSION,
   WORKSPACE_DIR,
   WORKSPACE_RUNTIME_PORT,
-  buildSandboxImage,
+  assertSandboxImageReference,
   defaultSandboxImage,
-  defaultSnapshotName,
-  ensureSnapshot,
   snapshotVersion
 };