@claxedo/sandbox-manager 0.7.0 → 0.10.0

package/dist/index.d.ts

@@ -1,535 +1,10 @@
-import { DEFAULT_WORKSPACE_RUNTIME_PORT } from "./constants";
-import type { SandboxDriverID } from "./driver-catalog";
-import { type SandboxCheckpointCaptureInput, type SandboxCheckpointRestoreInput, type SandboxCheckpointResult } from "./checkpoint-manager";
-export { DEFAULT_WORKSPACE_RUNTIME_PORT };
+export * from "./contract";
+export * from "./egress-policy";
+export * from "./driver-billing";
+export * from "./lease-failure";
+export * from "./lease-retry-wait";
 export * from "./checkpoint-manager";
 export * from "./hosted-network-policy";
-export type SandboxRegion = string;
-export type SandboxDriverId = SandboxDriverID | "fetch";
-export type SandboxCaptureScope = "none" | "same-resource" | "filesystem" | "directories";
-export type SandboxCaptureSourceBehavior = "not-applicable" | "preserved" | "stopped" | "deleted";
-export type SandboxRestoreMountBehavior = "not-applicable" | "same-resource" | "copy-on-write" | "new-resource";
-export type SandboxPersistenceCapabilities = {
-    resume: "same-sandbox" | "replacement-restore";
-    capture: SandboxCaptureScope;
-    clone: boolean;
-    captureSource: SandboxCaptureSourceBehavior;
-    retention: "not-applicable" | "provider-managed" | "explicit";
-    restoreMount: SandboxRestoreMountBehavior;
-};
-export declare function validateSandboxPersistenceCapabilities(input: SandboxPersistenceCapabilities): {
-    valid: false;
-    reason: string;
-} | {
-    reason?: undefined;
-    valid: true;
-};
-export type SandboxCheckpointReference = {
-    id: string;
-    providerReference: string;
-    sourceEpoch: number;
-    capturedAt: number;
-    metadata: {
-        scope: Exclude<SandboxCaptureScope, "none">;
-        sourceBehavior: Exclude<SandboxCaptureSourceBehavior, "not-applicable">;
-        retentionExpiresAt?: number;
-        restoreMount: Exclude<SandboxRestoreMountBehavior, "not-applicable">;
-    };
-};
-type SandboxRestoreIdentity = {
-    checkpointId: string;
-    sourceEpoch: number;
-};
-export type SandboxRestoreStatus = (SandboxRestoreIdentity & {
-    state: "pending";
-    requestedAt: number;
-}) | (SandboxRestoreIdentity & {
-    state: "restoring";
-    requestedAt: number;
-    startedAt: number;
-}) | (SandboxRestoreIdentity & {
-    state: "ready";
-    requestedAt: number;
-    startedAt: number;
-    completedAt: number;
-}) | (SandboxRestoreIdentity & {
-    state: "failed";
-    requestedAt: number;
-    startedAt?: number;
-    failedAt: number;
-    error: string;
-});
-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";
-    /**
-     * How the driver can enforce a RESTRICTED `SandboxNetworkPolicy` — i.e.
-     * whether the sandbox's outbound network can actually be contained.
-     *
-     * A `SandboxNetworkPolicy` states the same allowance in up to two encodings:
-     * `hosts` (names) and `cidrs` (addresses). A driver contains egress if it
-     * enforces AT LEAST ONE encoding the policy carries and blocks everything
-     * else; the encodings are alternatives, not additive requirements.
-     *
-     * - `"hosts-and-cidrs"` — the provider filters by name AND by address
-     *   (Daytona: `domainAllowList` + `networkAllowList`).
-     * - `"hosts"` — the provider filters by hostname only (Vercel firewall).
-     * - `"none"` — the driver cannot express an egress allowlist. This covers
-     *   BOTH drivers that throw when handed a restricted policy (exe, docker,
-     *   box, and modal for host policy) AND — more dangerously — drivers that
-     *   silently ignore `net` and run wide open (cloudflare, the fetch bridge).
-     *   Modal is `"none"` even though it can cut the network entirely: a total
-     *   blackout is not an allowlist and cannot serve a workspace that has to
-     *   clone a repo and reach a model provider.
-     *
-     * The manager reads this to decide what the driver is handed:
-     * `sandboxEgressDisposition` enforces where it can and WITHHOLDS (loudly)
-     * where it cannot. See `SandboxEgressDisposition` for the posture and
-     * `public-docs/sandbox-egress.md` for the operator-facing consequence.
-     */
-    egressControl: SandboxEgressControl;
-    persistence: SandboxPersistenceCapabilities;
-};
-/** @see SandboxDriverMetadata.egressControl */
-export type SandboxEgressControl = "none" | "hosts" | "hosts-and-cidrs";
-/**
- * What the manager does with a caller's `net` for a given driver.
- *
- * Owner directive (2026-07-28): *"for egress in sandbox enforce where we can
- * and document where we cant."* That replaces the previous fail-closed refusal
- * for drivers with no egress control at all — provisioning now proceeds, and
- * the gap is made loud instead of fatal.
- *
- *  - `"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 (exe, docker, modal, box) 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. This is the "document where we can't" half
- * of the directive expressed at runtime: an unrestricted sandbox that nobody
- * was told about is the original finding, 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 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 !== "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>;
-    checkpoint?: SandboxCheckpointReference;
-    persistence?: SandboxPersistenceCapabilities;
-    restore?: SandboxRestoreStatus;
-};
-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;
-    /** `null` clears the stored value; `undefined` leaves it unchanged. */
-    checkpoint?: SandboxCheckpointReference | null;
-    /** `null` clears the stored value; `undefined` leaves it unchanged. */
-    persistence?: SandboxPersistenceCapabilities | null;
-    /** `null` clears the stored value; `undefined` leaves it unchanged. */
-    restore?: SandboxRestoreStatus | 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;
-    /**
-     * Egress policy. Omitted means allow-all, which is only appropriate for a
-     * single-tenant deployment the operator already trusts.
-     *
-     * A driver can rely on this being ABSENT whenever it declares
-     * `egressControl: "none"`: the manager withholds the policy rather than hand
-     * it to a driver that would either throw on it or silently drop it. A driver
-     * that receives a restricted policy here is one that declared it can enforce
-     * it. @see SandboxEgressDisposition
-     */
-    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 SandboxCommandResult = {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-};
-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>;
-    inspect?: (target: SandboxTarget) => Promise<SandboxTarget | undefined>;
-    exec?: (target: SandboxTarget, command: string) => Promise<SandboxCommandResult>;
-    clone?: (target: SandboxTarget, input: {
-        name: string;
-    }) => Promise<SandboxTarget>;
-};
-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>;
-    checkpoint: (workspaceId: string, input: SandboxCheckpointCaptureInput) => Promise<SandboxCheckpointResult>;
-    restore: (workspaceId: string, input: SandboxCheckpointRestoreInput) => Promise<SandboxCheckpointResult>;
-    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;
-    /**
-     * @see SandboxDriverEnsureInput.net — enforced by a capable driver, withheld
-     * (with a warning) by one that declares `egressControl: "none"`.
-     */
-    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;
-    }>;
-    /**
-     * Set when the driver cannot enumerate provider state, so the four arrays
-     * above mean "we could not look" rather than "nothing is orphaned". Absent on
-     * a real sweep. Callers must treat it as a FAILED sweep: four empty arrays
-     * reported as success is the exact defect finding B1 names.
-     */
-    listingUnsupported?: true;
-    /** Driver id, so an ops report can name which driver could not look. */
-    driver?: string;
-};
-/**
- * A driver's `list()` may throw this shape to say "my backing service cannot
- * enumerate", as distinct from "listing failed this time". `garbageCollect()`
- * converts it into `listingUnsupported` (a loud, non-fatal capability gap);
- * every other error propagates as a real sweep failure.
- *
- * Structural rather than an `instanceof` check on purpose: drivers are published
- * as separate entry points and bundlers duplicate class identities, so a
- * nominal check would silently fall through to "transient failure" in exactly
- * the deployment that needs the distinction.
- */
-export type SandboxListingUnsupported = {
-    listingUnsupported: true;
-};
-export declare function isSandboxListingUnsupported(err: unknown): err is SandboxListingUnsupported;
-export type SandboxManagerOptions = {
-    leaseStore: SandboxLeaseStore;
-    driver: SandboxDriver;
-    staleAfterMs?: number;
-    retryAfterMs?: number;
-    retryDelayMs?: (retryCount: number) => number;
-    maxRetryCount?: number;
-    retryCapCooldownMs?: number;
-    now?: () => number;
-    appLabel?: string;
-    /**
-     * Sink for the loud half of "enforce where we can, document where we can't".
-     * Called at composition time and again every time a restricted policy is
-     * withheld from a driver that cannot enforce it.
-     *
-     * Defaults to `console.warn(event.message)`. Pass your own to route the gap
-     * into a telemetry pipeline instead — but note the default is deliberately
-     * unconditional: an operator who never wires a sink still gets the warning.
-     * Pass `() => {}` only if you have another way to surface it.
-     */
-    onEgressUnenforced?: (event: SandboxEgressUnenforcedEvent) => void;
-};
-export declare function createSandboxManager(options: SandboxManagerOptions): SandboxManager;
+export * from "./runtime-snapshot";
+export { createSandboxManager } from "./manager";
+export type { SandboxLifecycleEvent, SandboxStopCause } from "./lease-lifecycle";