@claxedo/sandbox-manager 0.5.1

package/dist/image.mjs

@@ -0,0 +1,124 @@
+import { createRequire as __createRequire } from 'module';var require = __createRequire(import.meta.url);
+
+// src/image.ts
+import { Image, DaytonaNotFoundError } from "@daytona/sdk";
+
+// src/constants.ts
+var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
+
+// src/defaults.ts
+var WORKSPACE_RUNTIME_PORT = DEFAULT_WORKSPACE_RUNTIME_PORT;
+var WORKSPACE_DIR = "/workspace";
+var RUNTIME_DIR = "/opt/workspace-runtime";
+
+// src/runtime-version.ts
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var versionCache;
+function workspaceRuntimeVersion() {
+  if (versionCache) return versionCache;
+  const envVersion = process.env.WORKSPACE_RUNTIME_VERSION;
+  if (envVersion) {
+    versionCache = envVersion;
+    return versionCache;
+  }
+  try {
+    versionCache = require2("@claxedo/workspace-runtime/package.json").version;
+    return versionCache;
+  } catch {
+  }
+  versionCache = "0.0.0";
+  return versionCache;
+}
+
+// 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 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)}` : "";
+}
+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}`;
+}
+
+// src/image.ts
+var log = {
+  info(_message, _context) {
+  }
+};
+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.info("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.info("[snapshot]", { text: chunk })
+    }
+  );
+  return SNAPSHOT_NAME;
+}
+async function ensureSnapshot(daytona) {
+  try {
+    const existing = await daytona.snapshot.get(SNAPSHOT_NAME);
+    if (existing.state === "inactive") {
+      log.info("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.info("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.info("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);
+}
+export {
+  RUNTIME_DIR,
+  SANDBOX_IMAGE,
+  SANDBOX_IMAGE_REPOSITORY,
+  SNAPSHOT_NAME,
+  SNAPSHOT_SCHEMA_VERSION,
+  WORKSPACE_DIR,
+  WORKSPACE_RUNTIME_PORT,
+  buildSandboxImage,
+  defaultSandboxImage,
+  defaultSnapshotName,
+  ensureSnapshot,
+  snapshotVersion
+};

package/dist/index.d.ts

@@ -0,0 +1,316 @@
+import { DEFAULT_WORKSPACE_RUNTIME_PORT } from "./constants";
+import type { SandboxDriverID } from "./driver-catalog";
+export { DEFAULT_WORKSPACE_RUNTIME_PORT };
+export type SandboxRegion = string;
+export type SandboxDriverId = SandboxDriverID | "fetch";
+export type SandboxDriverMetadata = {
+    /** Where the sandbox driver code can execute. This is not sandbox infrastructure. */
+    driverRunsIn: Array<"worker" | "node" | "local">;
+    /** What `SandboxManager.stop()` actually does to the driver-owned resource. */
+    hostStopBehavior: "not-supported" | "suspends-host" | "terminates-host";
+    /** Whether a stopped/stale lease can resume the same driver-owned resource. */
+    hostResumeBehavior: "same-host" | "replacement-host";
+    /** How the control plane reaches the sandbox target returned by the driver. */
+    targetAccess: "relay" | "loopback";
+    /**
+     * How the driver can honor a `SandboxBrokeredSecret` — a credential the
+     * sandbox may USE for outbound requests but must NEVER be able to READ.
+     *
+     * - `"native"` — the provider brokers it automatically on egress to the
+     *   allowlisted hosts, with no extra infrastructure: Daytona secret
+     *   placeholders + egress proxy; Vercel firewall header transforms. The
+     *   driver injects it during `ensureHost`.
+     * - `"proxy"` — brokering is achievable but only via a host-operated egress
+     *   proxy the driver routes through (Cloudflare's official Worker-proxy
+     *   pattern: the sandbox gets a short-lived JWT, egress hits the Worker,
+     *   the Worker injects the real credential — the raw value never enters the
+     *   sandbox). Not automatic; requires the host's proxy to be wired.
+     * - `"none"` — no way to keep the value out of sandbox processes. The
+     *   provider may still have an encrypted secret STORE (e.g. Modal secrets),
+     *   but those are exposed as readable env vars, so they cannot satisfy the
+     *   never-readable contract.
+     *
+     * The manager fails closed unless the driver actually injects brokered
+     * secrets (today: `"native"` only). `"proxy"` records an achievable ceiling
+     * that is not yet wired and therefore also fails closed.
+     */
+    secretBrokering: "native" | "proxy" | "none";
+};
+/**
+ * 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 !== "native"` cannot honor them and the
+ * manager refuses to provision (fail-closed).
+ */
+export type SandboxBrokeredSecret = {
+    /** Env var name the sandbox references (Daytona placeholder key). */
+    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[];
+    /**
+     * When set, the value is injected as this HTTP header on egress to `hosts`
+     * (required for the Vercel firewall-transform model). When omitted, the
+     * driver exposes the credential via its native placeholder mechanism for
+     * the sandbox to attach itself (Daytona).
+     */
+    header?: string;
+};
+export type SandboxExposure = {
+    kind: "loopback";
+} | {
+    kind: "relay";
+} | {
+    kind: "private-network";
+} | {
+    kind: "embedded";
+};
+export type SandboxLeaseStatus = "acquiring" | "ready" | "unavailable" | "stopped" | "destroyed";
+export type SandboxLease = {
+    workspaceId: string;
+    homeRegion: SandboxRegion;
+    driver: string;
+    epoch: number;
+    status: SandboxLeaseStatus;
+    retryCount: number;
+    updatedAt: number;
+    createdAt: number;
+    sandboxId?: string;
+    url?: string;
+    hostId?: string;
+    driverResourceId?: string;
+    nextRetryAt?: number;
+    lastError?: string;
+    lastHeartbeatAt?: number;
+    lastActivityAt?: number;
+    labels?: Record<string, string>;
+};
+export type SandboxLeaseAcquireInput = {
+    homeRegion: SandboxRegion;
+    driver: string;
+    staleAfterMs: number;
+    now?: number;
+};
+export type SandboxLeaseAcquireResult = {
+    acquired: true;
+    lease: SandboxLease;
+} | {
+    acquired: false;
+    lease: SandboxLease;
+    retryAfterMs: number;
+};
+export type SandboxLeasePatch = Partial<Pick<SandboxLease, "status" | "sandboxId" | "url" | "hostId" | "driverResourceId" | "retryCount" | "lastHeartbeatAt" | "lastActivityAt" | "labels">> & {
+    /** `null` clears the stored value; `undefined` leaves it unchanged. */
+    nextRetryAt?: number | null;
+    /** `null` clears the stored value; `undefined` leaves it unchanged. */
+    lastError?: string | null;
+};
+/**
+ * Canonical SandboxLeasePatch merge semantics shared by every lease store driver:
+ * absent/`undefined` keeps the current value, `null` clears it.
+ */
+export declare function applySandboxLeasePatch(current: SandboxLease, patch: SandboxLeasePatch, updatedAt: number): SandboxLease;
+export type SandboxLeaseStore = {
+    acquire: (workspaceId: string, input: SandboxLeaseAcquireInput) => Promise<SandboxLeaseAcquireResult>;
+    update: (workspaceId: string, expectedEpoch: number, patch: SandboxLeasePatch) => Promise<SandboxLease | undefined>;
+    recordFailure: (workspaceId: string, expectedEpoch: number, error: string, nextRetryAt?: number) => Promise<SandboxLease | undefined>;
+    release: (workspaceId: string) => Promise<void>;
+    get: (workspaceId: string) => Promise<SandboxLease | undefined>;
+    list: () => Promise<SandboxLease[]>;
+};
+export type SandboxNetworkPolicy = {
+    mode: "allow-all" | "restricted";
+    hosts?: string[];
+    cidrs?: string[];
+};
+export type SandboxBootSource = {
+    kind: "image";
+    image: string;
+} | {
+    kind: "driver-snapshot";
+    snapshotId: string;
+} | {
+    kind: "default";
+};
+export type SandboxSource = {
+    kind: "git";
+    repoUrl: string;
+    branch?: string;
+} | {
+    kind: "empty";
+};
+export type SandboxDriverEnsureInput = {
+    workspaceId: string;
+    hostId?: string;
+    homeRegion: SandboxRegion;
+    epoch: number;
+    labels: Record<string, string>;
+    bootSource?: SandboxBootSource;
+    workspaceRoot?: string;
+    runtimeCwd?: string;
+    workspaceRuntimePort?: number;
+    env?: Record<string, string>;
+    /** Brokered secrets: injected on egress, never readable inside the sandbox. */
+    secrets?: SandboxBrokeredSecret[];
+    source?: SandboxSource;
+    exposure?: SandboxExposure;
+    /** Optional egress policy (allow-all when omitted). */
+    net?: SandboxNetworkPolicy;
+    /** Optional snapshot/image to boot from (user-supplied or pre-built). */
+    snapshot?: string;
+};
+export type SandboxTarget = {
+    workspaceId?: string;
+    sandboxId: string;
+    url: string;
+    hostId: string;
+    driverResourceId?: string;
+    labels?: Record<string, string>;
+    driver?: {
+        id: string;
+        resourceId: string;
+        metadata?: Record<string, string>;
+    };
+};
+export type SandboxSnapshotResult = {
+    snapshotId: string;
+};
+export type SandboxDriver = {
+    id: string;
+    metadata: SandboxDriverMetadata;
+    ensureHost: (input: SandboxDriverEnsureInput) => Promise<SandboxTarget | {
+        provisioning: true;
+        retryAfterMs: number;
+    }>;
+    resumeHost?: (input: {
+        lease: SandboxLease;
+        ensure: SandboxDriverEnsureInput;
+    }) => Promise<SandboxTarget | {
+        provisioning: true;
+        retryAfterMs: number;
+    }>;
+    list?: () => Promise<SandboxTarget[]>;
+    touch?: (target: SandboxTarget) => Promise<void>;
+    suspend?: (target: SandboxTarget) => Promise<void>;
+    stop?: (target: SandboxTarget) => Promise<void>;
+    destroy?: (target: SandboxTarget) => Promise<void>;
+    snapshot?: (target: SandboxTarget) => Promise<SandboxSnapshotResult>;
+};
+export type SandboxManager = {
+    ensure: (workspaceId: string, input: SandboxManagerInput) => Promise<SandboxEnsureResult>;
+    register: (workspaceId: string, input: SandboxRegisterInput) => Promise<SandboxMutationResult>;
+    heartbeat: (workspaceId: string, input: SandboxHeartbeatInput) => Promise<SandboxMutationResult>;
+    target: (workspaceId: string) => Promise<SandboxTargetResult>;
+    touch: (workspaceId: string) => Promise<SandboxTouchResult>;
+    snapshot: (workspaceId: string) => Promise<SandboxSnapshotManagerResult>;
+    stop: (workspaceId: string) => Promise<SandboxMutationResult>;
+    destroy: (workspaceId: string) => Promise<SandboxMutationResult>;
+    release: (workspaceId: string) => Promise<{
+        released: boolean;
+    }>;
+    garbageCollect: () => Promise<SandboxGarbageCollectResult>;
+    list: () => Promise<SandboxLease[]>;
+};
+export type SandboxManagerInput = {
+    homeRegion: SandboxRegion;
+    hostId?: string;
+    labels?: Record<string, string>;
+    bootSource?: SandboxBootSource;
+    workspaceRoot?: string;
+    runtimeCwd?: string;
+    workspaceRuntimePort?: number;
+    env?: Record<string, string>;
+    /** Brokered secrets: injected on egress, never readable inside the sandbox. */
+    secrets?: SandboxBrokeredSecret[];
+    source?: SandboxSource;
+    exposure?: SandboxExposure;
+    net?: SandboxNetworkPolicy;
+    snapshot?: string;
+};
+export type SandboxRegisterInput = {
+    epoch?: number;
+    ok: boolean;
+    status?: string;
+    sandboxId?: string | null;
+    url?: string | null;
+    hostId?: string | null;
+    driverResourceId?: string | null;
+    active?: boolean;
+    now?: number;
+};
+export type SandboxHeartbeatInput = SandboxRegisterInput;
+export type SandboxEnsureResult = ({
+    status: "ready";
+} & SandboxTarget & {
+    epoch: number;
+    homeRegion: SandboxRegion;
+}) | {
+    status: "provisioning";
+    retryAfterMs: number;
+    epoch: number;
+    homeRegion: SandboxRegion;
+} | {
+    status: "unavailable";
+    retryAfterMs?: number;
+    error?: string;
+    epoch?: number;
+    homeRegion: SandboxRegion;
+};
+export type SandboxTargetResult = ({
+    status: "ready";
+} & SandboxTarget & {
+    epoch: number;
+    homeRegion: SandboxRegion;
+}) | {
+    status: "unavailable";
+    reason: string;
+};
+export type SandboxTouchResult = {
+    touched: boolean;
+    status: SandboxLeaseStatus | "missing";
+};
+export type SandboxMutationResult = {
+    ok: true;
+    status: SandboxLeaseStatus;
+} | {
+    ok: false;
+    reason: string;
+};
+export type SandboxSnapshotManagerResult = ({
+    ok: true;
+} & SandboxSnapshotResult) | {
+    ok: false;
+    reason: string;
+};
+export type SandboxGarbageCollectResult = {
+    destroyed: SandboxTarget[];
+    kept: SandboxTarget[];
+    skipped: Array<{
+        target: SandboxTarget;
+        reason: string;
+    }>;
+    failed: Array<{
+        target: SandboxTarget;
+        error: string;
+    }>;
+};
+export type SandboxManagerOptions = {
+    leaseStore: SandboxLeaseStore;
+    driver: SandboxDriver;
+    staleAfterMs?: number;
+    retryAfterMs?: number;
+    retryDelayMs?: (retryCount: number) => number;
+    maxRetryCount?: number;
+    retryCapCooldownMs?: number;
+    now?: () => number;
+    appLabel?: string;
+};
+export declare function createSandboxManager(options: SandboxManagerOptions): SandboxManager;