@giselles-ai/sandkit 0.1.0

package/dist/index.js

@@ -0,0 +1,1102 @@
+import {
+  github
+} from "./chunk-XM4HGRXW.js";
+import "./chunk-UDFWES6J.js";
+import "./chunk-BDPTYR6V.js";
+import "./chunk-RMMOQD5Y.js";
+import {
+  createMemoryAdapter
+} from "./chunk-CSOBTLWV.js";
+import {
+  codex
+} from "./chunk-FSDVHEEX.js";
+import {
+  gemini
+} from "./chunk-7DLK7LOM.js";
+import {
+  aiGateway
+} from "./chunk-REGOUXVI.js";
+import {
+  getSandboxDriverFactory
+} from "./chunk-HVYCAAZQ.js";
+import "./chunk-DLGUA3H7.js";
+import {
+  allowAll,
+  allowService,
+  allowServices,
+  assertWorkspacePolicyIsDurable,
+  denyAll,
+  describeWorkspacePolicy,
+  parseWorkspacePolicy,
+  redactWorkspacePolicy,
+  serializeWorkspacePolicy
+} from "./chunk-VISDS5T7.js";
+
+// src/core/context.ts
+function resolveDeprecatedNetworkOption(options) {
+  if (options.network !== void 0) {
+    throw new Error(
+      "SandkitOptions.network has been removed. Use createWorkspace({ policy }), workspace.setPolicy(...), or per-run policy overrides instead."
+    );
+  }
+}
+function createSandkitContext(options) {
+  if (!options) {
+    throw new Error("SandkitOptions is required. Set sandbox to a Sandkit sandbox provider.");
+  }
+  resolveDeprecatedNetworkOption(options);
+  if (!options.sandbox) {
+    throw new Error(
+      "SandkitOptions.sandbox is required. Set it to a Sandkit sandbox provider (for example, vercelSandbox(...))."
+    );
+  }
+  return {
+    adapter: options.database ?? createMemoryAdapter(),
+    driverFactory: getSandboxDriverFactory(options.sandbox),
+    options
+  };
+}
+
+// src/core/workspace-policy.ts
+var WORKSPACE_POLICY_METADATA_KEY = "sandkit:policy";
+function corruptionError(reason) {
+  return new Error(`Sandkit durable state corruption in sandkit_workspaces.metadata: ${reason}`);
+}
+function readWorkspacePolicy(workspace, fallback = allowAll()) {
+  const value = workspace.metadata?.[WORKSPACE_POLICY_METADATA_KEY];
+  if (value === void 0) {
+    return fallback;
+  }
+  try {
+    return parseWorkspacePolicy(value);
+  } catch (error) {
+    throw corruptionError(error instanceof Error ? error.message : "invalid workspace policy");
+  }
+}
+function asWorkspacePolicyMetadata(policy) {
+  assertWorkspacePolicyIsDurable(policy);
+  return {
+    [WORKSPACE_POLICY_METADATA_KEY]: serializeWorkspacePolicy(policy)
+  };
+}
+function removeWorkspacePolicyMetadata(metadata) {
+  if (!metadata || typeof metadata !== "object") {
+    return metadata;
+  }
+  if (!Object.prototype.hasOwnProperty.call(metadata, WORKSPACE_POLICY_METADATA_KEY)) {
+    return metadata;
+  }
+  const { [WORKSPACE_POLICY_METADATA_KEY]: _policyMetadata, ...rest } = metadata;
+  return rest;
+}
+function asWorkspacePolicyPatch(policy) {
+  return {
+    metadata: asWorkspacePolicyMetadata(policy)
+  };
+}
+function describeWorkspacePolicyId(policy) {
+  return describeWorkspacePolicy(policy);
+}
+function asPolicySnapshotConfig(policy) {
+  return redactWorkspacePolicy(policy);
+}
+
+// src/core/workspace-sandbox-config.ts
+var WORKSPACE_SANDBOX_CONFIG_METADATA_KEY = "sandkit:sandbox-config";
+function isFinitePort(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
+}
+function normalizeExposedPorts(ports) {
+  if (ports === void 0) {
+    return [];
+  }
+  if (!Array.isArray(ports)) {
+    throw new Error("exposedPorts must be an array of positive integers in [1, 65535]");
+  }
+  const normalized = ports.map((value, index) => {
+    if (!isFinitePort(value)) {
+      throw new Error(`exposedPorts[${index}] must be a positive integer in [1, 65535]`);
+    }
+    return value;
+  });
+  return [...normalized];
+}
+function corruptionError2(reason) {
+  return new Error(`Sandkit durable state corruption in sandkit_workspaces.metadata: ${reason}`);
+}
+function readWorkspaceSandboxConfigValue(value) {
+  if (value === void 0) {
+    return {};
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Expected sandbox config metadata object");
+  }
+  const candidate = value;
+  const ports = normalizeExposedPorts(candidate.exposedPorts);
+  return ports.length === 0 ? {} : { exposedPorts: ports };
+}
+function normalizeWorkspaceSandboxCreateConfig(config) {
+  if (config === void 0) {
+    return {};
+  }
+  return {
+    exposedPorts: normalizeExposedPorts(config.exposedPorts)
+  };
+}
+function asWorkspaceSandboxConfigMetadata(config) {
+  if (!config.exposedPorts || config.exposedPorts.length === 0) {
+    return {};
+  }
+  return {
+    [WORKSPACE_SANDBOX_CONFIG_METADATA_KEY]: {
+      exposedPorts: [...config.exposedPorts]
+    }
+  };
+}
+function removeWorkspaceSandboxConfigMetadata(metadata) {
+  if (!metadata || typeof metadata !== "object") {
+    return metadata;
+  }
+  if (!Object.prototype.hasOwnProperty.call(metadata, WORKSPACE_SANDBOX_CONFIG_METADATA_KEY)) {
+    return metadata;
+  }
+  const { [WORKSPACE_SANDBOX_CONFIG_METADATA_KEY]: _sandboxConfigMetadata, ...rest } = metadata;
+  return rest;
+}
+function readWorkspaceSandboxConfig(workspace) {
+  const metadataValue = workspace.metadata?.[WORKSPACE_SANDBOX_CONFIG_METADATA_KEY];
+  if (metadataValue === void 0) {
+    return {};
+  }
+  try {
+    return readWorkspaceSandboxConfigValue(metadataValue);
+  } catch (error) {
+    throw corruptionError2(
+      error instanceof Error ? error.message : "invalid workspace sandbox config"
+    );
+  }
+}
+
+// src/core/workspace-state.ts
+var SANDBOX_METADATA_KEY = "sandkit:sandbox";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPersistedSandboxState(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (typeof value.kind !== "string" || typeof value.sessionId !== "string") {
+    return false;
+  }
+  return value.state === void 0 || isJsonValue(value.state);
+}
+function isJsonValue(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+    return true;
+  }
+  if (Array.isArray(value)) {
+    return value.every((item) => isJsonValue(item));
+  }
+  if (!isRecord(value)) {
+    return false;
+  }
+  return Object.values(value).every((item) => isJsonValue(item));
+}
+function isIsoTimestamp(value) {
+  return typeof value === "string" && !Number.isNaN(Date.parse(value));
+}
+function isSerializedSessionLease(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return isIsoTimestamp(value.observedAt) && isIsoTimestamp(value.expiresAt);
+}
+function readWorkspaceSessionPolicy(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  try {
+    return parseWorkspacePolicy(value);
+  } catch {
+    return void 0;
+  }
+}
+function toSnapshotCommit(snapshot) {
+  return { kind: "snapshot", state: snapshot };
+}
+function toSerializedWorkspaceState(state) {
+  switch (state.kind) {
+    case "cold":
+      return { kind: "cold" };
+    case "session":
+      return {
+        kind: "session",
+        sessionId: state.sandboxId,
+        lease: {
+          observedAt: state.lease.observedAt,
+          expiresAt: state.lease.expiresAt
+        },
+        policy: state.sessionPolicy === void 0 ? void 0 : serializeWorkspacePolicy(state.sessionPolicy)
+      };
+    case "snapshot":
+      return { kind: "snapshot", state: state.commit.state };
+    default:
+      return { kind: "cold" };
+  }
+}
+function makeSnapshotCommit(state) {
+  return toSnapshotCommit(state);
+}
+function asWorkspaceSandboxStateMetadata(state) {
+  return {
+    [SANDBOX_METADATA_KEY]: toSerializedWorkspaceState(state)
+  };
+}
+function readWorkspaceSandboxState(workspace) {
+  const value = workspace.metadata?.[SANDBOX_METADATA_KEY];
+  if (!isRecord(value)) {
+    return { kind: "cold" };
+  }
+  const raw = value;
+  if (raw.kind === "session" && typeof raw.sessionId === "string" && isSerializedSessionLease(raw.lease)) {
+    return {
+      kind: "session",
+      sandboxId: raw.sessionId,
+      lease: {
+        sandboxId: raw.sessionId,
+        observedAt: raw.lease.observedAt,
+        expiresAt: raw.lease.expiresAt
+      },
+      sessionPolicy: readWorkspaceSessionPolicy(raw.policy)
+    };
+  }
+  if ((raw.kind === "session" || raw.kind === "sandbox-session") && typeof raw.sessionId === "string") {
+    return { kind: "cold" };
+  }
+  if (raw.kind === "snapshot") {
+    const snapshot = isPersistedSandboxState(raw.state) ? raw.state : null;
+    if (!snapshot) {
+      return { kind: "cold" };
+    }
+    return {
+      kind: "snapshot",
+      commit: toSnapshotCommit(snapshot)
+    };
+  }
+  return { kind: "cold" };
+}
+function readWorkspaceSandboxLease(workspace) {
+  return workspaceSandboxLeaseFromState(readWorkspaceSandboxState(workspace));
+}
+function workspaceSandboxLeaseFromState(state) {
+  if (state.kind !== "session") {
+    return null;
+  }
+  const expiresAtMs = Date.parse(state.lease.expiresAt);
+  if (!Number.isFinite(expiresAtMs)) {
+    return null;
+  }
+  const remainingMs = Math.max(0, expiresAtMs - Date.now());
+  if (remainingMs <= 0) {
+    return null;
+  }
+  return {
+    sandboxId: state.sandboxId,
+    observedAt: state.lease.observedAt,
+    expiresAt: state.lease.expiresAt,
+    remainingMs
+  };
+}
+function isWorkspaceSessionStateExpired(state, nowMs = Date.now()) {
+  if (state.kind !== "session") {
+    return false;
+  }
+  return Date.parse(state.lease.expiresAt) <= nowMs;
+}
+function transitionToCold(at = (/* @__PURE__ */ new Date()).toISOString()) {
+  const nextState = { kind: "cold" };
+  return {
+    nextState,
+    patch: {
+      metadata: asWorkspaceSandboxStateMetadata(nextState),
+      sandboxId: null,
+      lastResumedAt: at
+    }
+  };
+}
+function transitionToSession(sandboxId, lease, sessionPolicy) {
+  const nextState = {
+    kind: "session",
+    sandboxId,
+    lease,
+    sessionPolicy
+  };
+  return {
+    nextState,
+    patch: {
+      metadata: asWorkspaceSandboxStateMetadata(nextState),
+      sandboxId,
+      lastResumedAt: lease.observedAt
+    }
+  };
+}
+function transitionAfterCommandCommit(commit, at) {
+  const nextState = {
+    kind: "snapshot",
+    commit
+  };
+  return {
+    nextState,
+    patch: {
+      metadata: asWorkspaceSandboxStateMetadata(nextState),
+      sandboxId: commit.state.sessionId,
+      lastResumedAt: at
+    }
+  };
+}
+function toDriverResumeState(state) {
+  if (state.kind === "snapshot") {
+    return state.commit.state;
+  }
+  if (state.kind === "session") {
+    return {
+      kind: "sandbox-session",
+      sessionId: state.sandboxId
+    };
+  }
+  return null;
+}
+async function persistSandboxTransition(store, workspaceId, transition) {
+  const record = await store.updateWorkspace(workspaceId, transition.patch);
+  return {
+    record,
+    state: transition.nextState
+  };
+}
+
+// src/core/sandbox.ts
+var ManagedSandbox = class {
+  #driver;
+  #onCommit;
+  #runLifecycle;
+  #resolveDefaultPolicy;
+  constructor(driver, resolveDefaultPolicy, onCommit, runLifecycle) {
+    this.#driver = driver;
+    this.#resolveDefaultPolicy = resolveDefaultPolicy;
+    this.#onCommit = onCommit;
+    this.#runLifecycle = runLifecycle;
+  }
+  get id() {
+    return this.#driver.id;
+  }
+  async runCommand(inputOrCommand, args = []) {
+    const normalized = await this.normalizeRunCommandInput(inputOrCommand, args);
+    this.ensureCommandShape(normalized.command, normalized.args);
+    return this.runUnitOfWork(
+      normalized.command,
+      normalized.args,
+      normalized.policy,
+      () => this.executeCommand(normalized.command, normalized.args, normalized.policy)
+    );
+  }
+  async normalizeRunCommandInput(inputOrCommand, args) {
+    if (typeof inputOrCommand === "string") {
+      return {
+        command: inputOrCommand,
+        args,
+        policy: await this.#resolveDefaultPolicy()
+      };
+    }
+    return {
+      command: inputOrCommand.command,
+      args: inputOrCommand.args ?? [],
+      policy: inputOrCommand.policy ?? await this.#resolveDefaultPolicy()
+    };
+  }
+  ensureCommandShape(command, args) {
+    if (!command.trim()) {
+      throw new Error("Sandbox command must not be empty.");
+    }
+    if (!Array.isArray(args)) {
+      throw new Error("Sandbox command arguments must be an array.");
+    }
+  }
+  async runUnitOfWork(command, args, effectivePolicy, operation) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const runId = await this.startRun(command, args, effectivePolicy, now);
+    let commandError;
+    let commandResult;
+    try {
+      commandResult = await operation();
+    } catch (error) {
+      commandError = error;
+    }
+    const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const commandStatus = commandError === void 0 ? commandResult?.exitCode === 0 ? "succeeded" : "failed" : "failed";
+    let providerCommit;
+    let finalizeError;
+    try {
+      const commit = await this.snapshotWithFallback();
+      providerCommit = commit.state;
+      if (this.#onCommit) {
+        await this.persistCommit(commit);
+      }
+    } catch (error) {
+      finalizeError = error;
+      providerCommit = void 0;
+    }
+    const finalRunStatus = commandError === void 0 && finalizeError === void 0 ? commandStatus : "failed";
+    try {
+      if (runId) {
+        await this.finishRun({
+          runId,
+          status: finalRunStatus,
+          providerCommit,
+          finishedAt,
+          exitCode: commandResult?.exitCode,
+          stdout: commandResult?.stdout,
+          stderr: commandResult?.stderr
+        });
+      }
+    } catch (error) {
+      finalizeError = finalizeError ?? error;
+    }
+    if (commandError !== void 0) {
+      if (finalizeError !== void 0) {
+        throw new AggregateError(
+          [commandError, finalizeError],
+          "Sandbox command failed and unit-of-work durability finalization did not complete."
+        );
+      }
+      throw commandError;
+    }
+    if (finalizeError !== void 0) {
+      throw finalizeError;
+    }
+    if (!commandResult) {
+      throw new Error("Command result was missing after successful execution.");
+    }
+    return commandResult;
+  }
+  async startRun(command, args, effectivePolicy, at) {
+    if (!this.#runLifecycle?.onRunStart) {
+      return void 0;
+    }
+    return this.#runLifecycle.onRunStart({
+      command,
+      args,
+      effectivePolicy,
+      startedAt: at
+    });
+  }
+  async executeCommand(command, args, policy) {
+    await this.#driver.applyPolicy(policy);
+    return this.#driver.runCommand(command, [...args]);
+  }
+  async finishRun(input) {
+    if (!this.#runLifecycle?.onRunFinish) {
+      return;
+    }
+    await this.#runLifecycle.onRunFinish(input);
+  }
+  async snapshotWithFallback() {
+    const snapshot = await this.#driver.snapshot();
+    return makeSnapshotCommit(snapshot);
+  }
+  async persistCommit(commit) {
+    if (!this.#onCommit) {
+      return;
+    }
+    await this.#onCommit(commit);
+  }
+};
+var ManagedSession = class {
+  #driver;
+  #onCommit;
+  #resolveDefaultPolicy;
+  #onPolicyChange;
+  #stateValidator;
+  #leaseLifecycle;
+  #sessionPolicyOverride;
+  #isActive = true;
+  constructor(driver, resolveDefaultPolicy, onCommit, stateValidator, leaseLifecycle, policyLifecycle) {
+    this.#driver = driver;
+    this.#resolveDefaultPolicy = resolveDefaultPolicy;
+    this.#onCommit = onCommit;
+    this.#stateValidator = stateValidator;
+    this.#leaseLifecycle = leaseLifecycle;
+    this.#onPolicyChange = policyLifecycle?.onPolicyChange;
+    this.#sessionPolicyOverride = policyLifecycle?.initialSessionPolicy;
+  }
+  get id() {
+    return this.#driver.id;
+  }
+  async exec(inputOrCommand, args = []) {
+    await this.assertSessionActive();
+    const normalized = await this.normalizeSessionInput(inputOrCommand, args);
+    this.ensureCommandShape(normalized.command, normalized.args);
+    await this.#driver.applyPolicy(normalized.policy);
+    return this.#driver.runCommand(normalized.command, [...normalized.args]);
+  }
+  async commit() {
+    await this.assertSessionActive();
+    let snapshot;
+    try {
+      snapshot = await this.snapshotWithFallback();
+      if (this.#onCommit) {
+        await this.persistCommit(snapshot);
+      }
+    } finally {
+      this.#isActive = false;
+    }
+  }
+  async setPolicy(policy) {
+    await this.assertSessionActive();
+    this.#sessionPolicyOverride = policy;
+    await this.#driver.applyPolicy(policy);
+    if (this.#onPolicyChange !== void 0) {
+      await this.#onPolicyChange(policy);
+    }
+  }
+  async startProcess(inputOrCommand, args = []) {
+    await this.assertSessionActive();
+    const startProcess = this.#driver.startProcess;
+    if (!startProcess) {
+      throw new Error(`This sandbox provider does not support startProcess().`);
+    }
+    const normalized = typeof inputOrCommand === "string" ? {
+      command: inputOrCommand,
+      args,
+      policy: this.#sessionPolicyOverride,
+      onStdout: void 0,
+      onStderr: void 0
+    } : inputOrCommand;
+    if (!normalized.command.trim()) {
+      throw new Error("Sandbox process command must not be empty.");
+    }
+    if (!Array.isArray(normalized.args)) {
+      throw new Error("Sandbox process args must be an array.");
+    }
+    const policy = await this.resolveSessionPolicy(normalized.policy);
+    await this.#driver.applyPolicy(policy);
+    return startProcess.call(this.#driver, {
+      command: normalized.command,
+      args: [...normalized.args],
+      policy,
+      onStdout: normalized.onStdout,
+      onStderr: normalized.onStderr
+    });
+  }
+  async url(port) {
+    await this.assertSessionActive();
+    const url = this.#driver.url;
+    if (!url) {
+      throw new Error(`This sandbox provider does not support url(port).`);
+    }
+    return url.call(this.#driver, port);
+  }
+  async extendTimeout(durationMs) {
+    await this.assertSessionActive();
+    const extendTimeout = this.#driver.extendTimeout;
+    if (!extendTimeout) {
+      throw new Error(`This sandbox provider does not support extendTimeout().`);
+    }
+    await extendTimeout.call(this.#driver, durationMs);
+    if (this.#leaseLifecycle?.onLeaseRefresh) {
+      await this.#leaseLifecycle.onLeaseRefresh();
+    }
+  }
+  async normalizeSessionInput(inputOrCommand, args) {
+    if (typeof inputOrCommand === "string") {
+      return {
+        command: inputOrCommand,
+        args,
+        policy: await this.resolveSessionPolicy()
+      };
+    }
+    return {
+      command: inputOrCommand.command,
+      args: inputOrCommand.args ?? [],
+      policy: await this.resolveSessionPolicy(inputOrCommand.policy)
+    };
+  }
+  async resolveSessionPolicy(override) {
+    if (override !== void 0) {
+      return override;
+    }
+    if (this.#sessionPolicyOverride !== void 0) {
+      return this.#sessionPolicyOverride;
+    }
+    return this.#resolveDefaultPolicy();
+  }
+  ensureCommandShape(command, args) {
+    if (!command.trim()) {
+      throw new Error("Sandbox command must not be empty.");
+    }
+    if (!Array.isArray(args)) {
+      throw new Error("Sandbox command arguments must be an array.");
+    }
+  }
+  async assertSessionActive() {
+    if (!this.#isActive) {
+      throw new Error("This sandbox session has already been committed and is no longer active.");
+    }
+    if (this.#stateValidator) {
+      await this.#stateValidator.assertActive();
+    }
+  }
+  async snapshotWithFallback() {
+    const snapshot = await this.#driver.snapshot();
+    return makeSnapshotCommit(snapshot);
+  }
+  async persistCommit(commit) {
+    if (!this.#onCommit) {
+      return;
+    }
+    await this.#onCommit(commit);
+  }
+};
+var LazySandboxHandle = class {
+  #resolveSandbox;
+  #openSession;
+  #attachSession;
+  #getActiveLease;
+  constructor(resolveSandbox, openSession, attachSession, getActiveLease) {
+    this.#resolveSandbox = resolveSandbox;
+    this.#openSession = openSession;
+    this.#attachSession = attachSession;
+    this.#getActiveLease = getActiveLease;
+  }
+  async runCommand(inputOrCommand, args = []) {
+    const sandbox = await this.#resolveSandbox();
+    if (typeof inputOrCommand === "string") {
+      return sandbox.runCommand(inputOrCommand, args);
+    }
+    return sandbox.runCommand(inputOrCommand);
+  }
+  async openSession(input) {
+    return this.#openSession(input);
+  }
+  async attachSession() {
+    return this.#attachSession();
+  }
+  async getActiveLease() {
+    return this.#getActiveLease();
+  }
+};
+
+// src/core/workspace.ts
+function setupStateFingerprint(command, args, policy) {
+  return encodeURIComponent(
+    JSON.stringify({
+      command,
+      args,
+      policy: policy ? {
+        id: describeWorkspacePolicyId(policy),
+        config: asPolicySnapshotConfig(policy)
+      } : null
+    })
+  );
+}
+var sharedSetupStateId = (adapterId, setup) => {
+  if (setup?.policy) {
+    assertWorkspacePolicyIsDurable(setup.policy);
+  }
+  const fingerprint = setup ? setupStateFingerprint(setup.command, [...setup.args ?? []], setup.policy) : "no-bootstrap";
+  return `${adapterId}:shared-bootstrap:${fingerprint}`;
+};
+var WorkspaceHandle = class {
+  #ctx;
+  #record;
+  #sandboxState;
+  #sandboxConfig;
+  #descriptor;
+  #lazySandbox;
+  constructor(ctx, record) {
+    this.#ctx = ctx;
+    this.#record = record;
+    this.#descriptor = this.resolveDescriptor(record);
+    this.#sandboxState = readWorkspaceSandboxState(record);
+    this.#sandboxConfig = readWorkspaceSandboxConfig(record);
+  }
+  get id() {
+    return this.#record.id;
+  }
+  get descriptor() {
+    return this.#descriptor;
+  }
+  get sandbox() {
+    if (!this.#lazySandbox) {
+      this.#lazySandbox = new LazySandboxHandle(
+        () => this.createOrResumeSandboxForCommand(),
+        (input) => this.openSession(input),
+        () => this.attachSession(),
+        () => this.getActiveLease()
+      );
+    }
+    return this.#lazySandbox;
+  }
+  async setPolicy(policy) {
+    await this.resolveLatestWorkspace();
+    const result = await this.#ctx.adapter.workspaces.updateWorkspace(
+      this.#record.id,
+      asWorkspacePolicyPatch(policy)
+    );
+    this.updateFromRecord(result);
+    this.#sandboxState = readWorkspaceSandboxState(result);
+  }
+  /**
+   * Returns a current lease only if a session is still attachable and unexpired.
+   * This is attachment-state derived from persisted metadata; it is not intended
+   * to reset expiry on read.
+   */
+  async getActiveLease() {
+    await this.resolveLatestWorkspace();
+    const sandbox = await this.resolveAttachableSession();
+    if (!sandbox) {
+      return null;
+    }
+    return readWorkspaceSandboxLease(this.#record);
+  }
+  async createOrResumeSandboxForCommand() {
+    await this.resolveLatestWorkspace();
+    if (await this.resolveAttachableSession()) {
+      throw new Error(
+        "Cannot run command while a sandbox session is active. Use attachSession() to reuse it or commit the session first."
+      );
+    }
+    const workspace = await this.resolveLatestWorkspace();
+    const sandbox = await this.resolveSandboxDriver(workspace);
+    return this.createManagedSandbox(sandbox);
+  }
+  async openSession(input) {
+    await this.resolveLatestWorkspace();
+    if (await this.resolveAttachableSession()) {
+      throw new Error("A sandbox session is already active for this workspace.");
+    }
+    const workspace = await this.resolveLatestWorkspace();
+    const sandbox = await this.resolveSandboxDriver(workspace, {
+      timeoutMs: normalizeSessionTimeoutMs(input?.timeoutMs)
+    });
+    const lease = await sandbox.getSessionLease();
+    await this.persistSandboxState(transitionToSession(sandbox.id, lease));
+    return this.makeSession(sandbox);
+  }
+  async attachSession() {
+    await this.resolveLatestWorkspace();
+    const sandbox = await this.resolveAttachableSession();
+    if (!sandbox) {
+      throw new Error("There is no active sandbox session to attach for this workspace.");
+    }
+    return this.makeSession(sandbox);
+  }
+  async persistSessionPolicy(policy) {
+    await this.resolveLatestWorkspace();
+    if (!workspaceStateIsSession(this.#sandboxState)) {
+      throw new Error("Cannot persist session policy without an active sandbox session.");
+    }
+    await this.persistSandboxState(
+      transitionToSession(this.#sandboxState.sandboxId, this.#sandboxState.lease, policy)
+    );
+  }
+  makeSession(sandbox) {
+    const sessionPolicy = workspaceStateIsSession(this.#sandboxState) ? this.#sandboxState.sessionPolicy : void 0;
+    return new ManagedSession(
+      sandbox,
+      async () => this.resolveDefaultPolicy(),
+      async (commit) => this.persistSandboxState(transitionAfterCommandCommit(commit, (/* @__PURE__ */ new Date()).toISOString())),
+      {
+        assertActive: async () => {
+          const activeSandbox = await this.resolveAttachableSession();
+          if (!activeSandbox || activeSandbox.id !== sandbox.id) {
+            throw new Error("This sandbox session is no longer active.");
+          }
+        }
+      },
+      {
+        onLeaseRefresh: async () => {
+          const lease = await sandbox.getSessionLease();
+          await this.refreshSessionLease(sandbox.id, lease);
+        }
+      },
+      {
+        initialSessionPolicy: sessionPolicy,
+        onPolicyChange: async (policy) => {
+          await this.persistSessionPolicy(policy);
+        }
+      }
+    );
+  }
+  async refreshSessionLease(sandboxId, lease) {
+    await this.resolveLatestWorkspace();
+    if (!workspaceStateIsSession(this.#sandboxState) || this.#sandboxState.sandboxId !== sandboxId) {
+      throw new Error("Cannot refresh lease for an inactive sandbox session.");
+    }
+    await this.persistSandboxState(
+      transitionToSession(sandboxId, lease, this.#sandboxState.sessionPolicy)
+    );
+  }
+  async resolveAttachableSession() {
+    if (!workspaceStateIsSession(this.#sandboxState)) {
+      return null;
+    }
+    if (isWorkspaceSessionStateExpired(this.#sandboxState)) {
+      await this.persistSandboxState(transitionToCold());
+      return null;
+    }
+    try {
+      return await this.resolveSandboxDriver(this.#record);
+    } catch (error) {
+      if (!this.#ctx.driverFactory.isSessionUnavailableError?.(error)) {
+        throw error;
+      }
+      await this.persistSandboxState(transitionToCold());
+      return null;
+    }
+  }
+  async resolveSandboxDriver(workspace, overrides) {
+    const policy = readWorkspacePolicy(workspace, allowAll());
+    const options = this.makeSandboxDriverOptions(policy, overrides?.timeoutMs);
+    const currentState = toDriverResumeState(this.#sandboxState);
+    if (currentState) {
+      return this.#ctx.driverFactory.resumeSandbox(workspace, currentState, options);
+    }
+    try {
+      const setupState = await this.#readSharedSetupState();
+      if (!setupState) {
+        return this.#bootstrapSetupState(workspace, options);
+      }
+      return await this.#ctx.driverFactory.resumeSandbox(workspace, setupState, options);
+    } catch (error) {
+      if (!this.#ctx.driverFactory.isSessionUnavailableError?.(error) && !this.#isRecoverableSetupStateError(error)) {
+        throw error;
+      }
+      await this.#clearSharedSetupState();
+      return this.#bootstrapSetupState(workspace, options);
+    }
+  }
+  async #bootstrapSetupState(workspace, options) {
+    const setup = this.#ctx.options.setup;
+    if (!setup) {
+      return this.#ctx.driverFactory.createSandbox(workspace, options);
+    }
+    const setupPolicy = setup.policy ?? options.policy;
+    const sandbox = await this.#ctx.driverFactory.createSandbox(workspace, {
+      ...options,
+      policy: setupPolicy
+    });
+    const result = await sandbox.runCommand(setup.command, [...setup.args ?? []]);
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Workspace setup failed with exit code ${result.exitCode}. ${result.stderr.trim()}`.trim()
+      );
+    }
+    const setupState = await sandbox.snapshot();
+    await this.#persistSharedSetupState(setupState);
+    return this.#ctx.driverFactory.resumeSandbox(workspace, setupState, options);
+  }
+  async #readSharedSetupState() {
+    if (!this.#ctx.options.setup) {
+      return null;
+    }
+    const setupState = await this.#ctx.adapter.setupStates.getSetupState(
+      this.#sharedSetupStateId()
+    );
+    return setupState ? setupState.state : null;
+  }
+  async #persistSharedSetupState(state) {
+    await this.#ctx.adapter.setupStates.putSetupState({
+      id: this.#sharedSetupStateId(),
+      state: {
+        kind: state.kind,
+        sessionId: state.sessionId,
+        state: state.state
+      }
+    });
+  }
+  async #clearSharedSetupState() {
+    await this.#ctx.adapter.setupStates.deleteSetupState(this.#sharedSetupStateId());
+  }
+  #sharedSetupStateId() {
+    return sharedSetupStateId(this.#ctx.adapter.id, this.#ctx.options.setup);
+  }
+  #isRecoverableSetupStateError(error) {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    return error.message.includes("Sandkit durable state corruption") && error.message.includes("sandkit_setup_states");
+  }
+  createManagedSandbox(sandbox) {
+    return new ManagedSandbox(
+      sandbox,
+      async () => this.resolveDefaultPolicy(),
+      async (commit) => this.persistSandboxState(transitionAfterCommandCommit(commit, (/* @__PURE__ */ new Date()).toISOString())),
+      this.createRunLifecycle(sandbox)
+    );
+  }
+  makeSandboxDriverOptions(policy, timeoutMs) {
+    const next = {
+      policy
+    };
+    if (this.#sandboxConfig.exposedPorts && this.#sandboxConfig.exposedPorts.length > 0) {
+      next.exposedPorts = this.#sandboxConfig.exposedPorts;
+    }
+    if (timeoutMs !== void 0) {
+      next.timeoutMs = timeoutMs;
+    }
+    return next;
+  }
+  createRunLifecycle(sandbox) {
+    return {
+      onRunStart: async (input) => {
+        const policySnapshot = await this.createPolicySnapshot(input.effectivePolicy);
+        const run = await this.#ctx.adapter.runs.createRun({
+          workspaceId: this.#record.id,
+          provider: sandbox.provider,
+          executionTargetId: sandbox.id,
+          command: input.command,
+          args: input.args,
+          status: "started",
+          startedAt: input.startedAt,
+          policySnapshotId: policySnapshot.id
+        });
+        return run.id;
+      },
+      onRunFinish: async (input) => {
+        await this.#ctx.adapter.runs.finishRun(input.runId, {
+          status: input.status,
+          finishedAt: input.finishedAt,
+          exitCode: input.exitCode ?? null,
+          stdout: input.stdout ?? null,
+          stderr: input.stderr ?? null,
+          providerCommit: input.providerCommit
+        });
+      }
+    };
+  }
+  async persistSandboxState(transition) {
+    const result = await persistSandboxTransition(
+      this.#ctx.adapter.workspaces,
+      this.#record.id,
+      transition
+    );
+    this.updateFromRecord(result.record);
+    this.#sandboxState = result.state;
+  }
+  async resolveLatestWorkspace() {
+    const latest = await this.#ctx.adapter.workspaces.getWorkspace(this.#record.id);
+    if (!latest) {
+      throw new Error(`Workspace with id "${this.#record.id}" no longer exists`);
+    }
+    this.updateFromRecord(latest);
+    this.#sandboxState = readWorkspaceSandboxState(latest);
+    this.#sandboxConfig = readWorkspaceSandboxConfig(latest);
+    if (isWorkspaceSessionStateExpired(this.#sandboxState)) {
+      const result = await persistSandboxTransition(
+        this.#ctx.adapter.workspaces,
+        this.#record.id,
+        transitionToCold()
+      );
+      this.updateFromRecord(result.record);
+      this.#sandboxState = result.state;
+      this.#sandboxConfig = readWorkspaceSandboxConfig(result.record);
+    }
+    return this.#record;
+  }
+  resolveDescriptor(record) {
+    return {
+      id: record.id,
+      name: record.name,
+      status: record.status,
+      createdAt: record.createdAt,
+      updatedAt: record.updatedAt
+    };
+  }
+  updateFromRecord(record) {
+    this.#record = record;
+    this.#descriptor = this.resolveDescriptor(record);
+    this.#sandboxConfig = readWorkspaceSandboxConfig(record);
+  }
+  async createPolicySnapshot(policy) {
+    return this.#ctx.adapter.policySnapshots.createPolicySnapshot({
+      workspaceId: this.#record.id,
+      policyId: describeWorkspacePolicyId(policy),
+      config: asPolicySnapshotConfig(policy)
+    });
+  }
+  async resolveDefaultPolicy() {
+    const workspace = await this.resolveLatestWorkspace();
+    return readWorkspacePolicy(workspace, allowAll());
+  }
+};
+function normalizeSessionTimeoutMs(timeoutMs) {
+  if (timeoutMs === void 0) {
+    return void 0;
+  }
+  if (!Number.isInteger(timeoutMs) || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("openSession timeoutMs must be a positive integer in milliseconds.");
+  }
+  return timeoutMs;
+}
+function workspaceStateIsSession(state) {
+  return state.kind === "session";
+}
+
+// src/core/sandkit.ts
+var Sandkit = class {
+  #ctx;
+  constructor(options) {
+    this.#ctx = createSandkitContext(options);
+  }
+  get context() {
+    return this.#ctx;
+  }
+  async createWorkspace(input = {}) {
+    const { id, name, policy, metadata, status, sandboxId, lastResumedAt } = input;
+    const sandboxConfig = normalizeWorkspaceSandboxCreateConfig(input.sandbox);
+    const sanitizedMetadata = removeWorkspaceSandboxConfigMetadata(
+      removeWorkspacePolicyMetadata(metadata)
+    );
+    const workspaceMetadata = policy ? {
+      ...sanitizedMetadata,
+      ...asWorkspacePolicyMetadata(policy),
+      ...asWorkspaceSandboxConfigMetadata(sandboxConfig)
+    } : {
+      ...sanitizedMetadata,
+      ...asWorkspaceSandboxConfigMetadata(sandboxConfig)
+    };
+    const workspace = await this.#ctx.adapter.workspaces.createWorkspace({
+      id,
+      name,
+      metadata: workspaceMetadata,
+      status,
+      sandboxId,
+      lastResumedAt
+    });
+    return new WorkspaceHandle(this.#ctx, workspace);
+  }
+  async getWorkspace(id) {
+    const workspace = await this.#ctx.adapter.workspaces.getWorkspace(id);
+    if (!workspace) {
+      throw new Error(`Workspace not found: ${id}`);
+    }
+    return new WorkspaceHandle(this.#ctx, workspace);
+  }
+};
+function createSandkit(options) {
+  return new Sandkit(options);
+}
+export {
+  Sandkit,
+  aiGateway,
+  allowAll,
+  allowService,
+  allowServices,
+  codex,
+  createSandkit,
+  denyAll,
+  gemini,
+  github
+};
+//# sourceMappingURL=index.js.map