@agen-ai/sandbox 0.0.0-stage → 0.4.4

package/dist/lifecycle/owner.js

@@ -0,0 +1,288 @@
+import { SandboxCleanupError, SandboxOperationError, SandboxStartError, SandboxStateError } from "../errors.js";
+import { parseTransferOptions } from "../files/parse.js";
+import { parseSandboxGuestPath } from "../files/paths.js";
+import { assertSandboxEffectivePolicy, parseSandboxEffectivePolicy, parseSandboxProcessId } from "../policy/parse.js";
+import { parseSandboxProcessSpec } from "../process/parse.js";
+import { ownProcessStreams } from "../process/streams.js";
+import { parseOperationOptions } from "../internal/operations.js";
+import { RecoveryJournal } from "./journal.js";
+import { scheduleDeadline } from "./deadline.js";
+import { actualOperation, observe, settled } from "./observation.js";
+import { importTree, exportTree } from "./transfer.js";
+class SandboxOwner {
+  constructor(driver, request, recovery, record) {
+    this.driver = driver;
+    this.request = request;
+    this.journal = new RecoveryJournal(record, recovery, (error) => {
+      this.startupController.abort(error);
+      this.fence("start");
+    });
+  }
+  snapshot = Object.freeze({ kind: "reserved" });
+  journal;
+  startupController = new AbortController();
+  startup;
+  ready;
+  transfer;
+  processReserved = false;
+  process;
+  streams;
+  cancelExecutionDeadline;
+  stopActual;
+  destroyActual;
+  stopObservation;
+  destroyObservation;
+  get id() {
+    return this.driver.id;
+  }
+  get state() {
+    return this.snapshot;
+  }
+  get recoveryRecord() {
+    return this.journal.current;
+  }
+  start(input) {
+    const options = parseOperationOptions(input);
+    if (this.snapshot.kind !== "reserved") return Promise.reject(new SandboxStateError("Sandbox startup is once-only and cannot follow cleanup."));
+    this.snapshot = Object.freeze({ kind: "starting" });
+    if (options.signal?.aborted) this.startupController.abort(new SandboxOperationError("cancelled", "Sandbox startup was cancelled before entry."));
+    this.startup = actualOperation(async () => {
+      this.startupController.signal.throwIfAborted();
+      await this.journal.initialize();
+      this.startupController.signal.throwIfAborted();
+      const ready = await this.driver.start({ signal: this.startupController.signal, checkpoint: this.journal.checkpoint });
+      this.ready = ready;
+      if (this.snapshot.kind !== "starting" || this.startupController.signal.aborted) {
+        throw new SandboxOperationError("cancelled", "Sandbox startup settled after its admission was closed.");
+      }
+      const effective = parseSandboxEffectivePolicy(ready.effective);
+      const workspace = parseSandboxGuestPath(ready.workspace);
+      assertSandboxEffectivePolicy(this.request, effective);
+      const owner = this;
+      const sandbox = Object.freeze({
+        id: this.id,
+        effective,
+        workspace,
+        get state() {
+          return owner.state;
+        },
+        get recoveryRecord() {
+          return owner.recoveryRecord;
+        },
+        importTree: (entries, operation) => owner.importTree(entries, operation),
+        reserveProcess: (spec) => owner.reserveProcess(spec),
+        exportTree: (selection, consume, operation) => owner.exportTree(selection, consume, operation),
+        stop: () => owner.stop(),
+        destroy: () => owner.destroy()
+      });
+      this.snapshot = Object.freeze({ kind: "ready" });
+      return sandbox;
+    });
+    void this.startup.catch(() => this.fence("start"));
+    return observe(this.startup, this.request.policy.deadlines.startupMs, {
+      signal: operationSignal(this.startupController, options),
+      onInterrupt: (error) => {
+        this.startupController.abort(error);
+        this.fence("start");
+        void this.stop().catch(() => {
+        });
+      }
+    }).catch((cause) => {
+      throw new SandboxStartError("Sandbox startup failed; its reservation retains cleanup ownership.", { cause, owner: this });
+    });
+  }
+  stop() {
+    if (this.snapshot.kind === "destroyed" || this.snapshot.kind === "stopped") return Promise.resolve();
+    if (this.stopObservation) return this.stopObservation;
+    const actual = this.beginStop();
+    this.stopObservation = observe(actual, this.request.policy.deadlines.cleanupMs).catch((cause) => {
+      this.fence("stop");
+      throw new SandboxCleanupError("Sandbox compute cleanup did not settle successfully.", { cause, owner: this, operation: "stop" });
+    }).finally(() => {
+      this.stopObservation = void 0;
+    });
+    return this.stopObservation;
+  }
+  destroy() {
+    if (this.snapshot.kind === "destroyed") return Promise.resolve();
+    if (this.destroyObservation) return this.destroyObservation;
+    this.snapshot = Object.freeze({ kind: "destroying" });
+    this.transfer?.controller.abort(new SandboxOperationError("cancelled", "Sandbox storage is being destroyed."));
+    if (!this.destroyActual) {
+      const transferCleanup = this.cleanupTransfer();
+      void transferCleanup.catch(() => {
+      });
+      const dispatch = Promise.withResolvers();
+      const actual = dispatch.promise.then(async () => {
+        await transferCleanup;
+        await this.driver.destroy();
+        this.snapshot = Object.freeze({ kind: "destroyed" });
+      }).catch((error) => {
+        this.destroyActual = void 0;
+        if (this.snapshot.kind !== "destroyed") this.snapshot = Object.freeze({ kind: "uncertain", operation: "destroy" });
+        throw error;
+      });
+      this.destroyActual = actual;
+      this.beginStop().then(dispatch.resolve, dispatch.reject);
+    }
+    this.destroyObservation = observe(this.destroyActual, this.request.policy.deadlines.cleanupMs).catch((cause) => {
+      this.fence("destroy");
+      throw new SandboxCleanupError("Sandbox destruction did not settle successfully.", { cause, owner: this, operation: "destroy" });
+    }).finally(() => {
+      this.destroyObservation = void 0;
+    });
+    return this.destroyObservation;
+  }
+  beginStop() {
+    if (this.stopActual) return this.stopActual;
+    if (this.snapshot.kind !== "destroying") this.snapshot = Object.freeze({ kind: "stopping" });
+    const physical = Promise.withResolvers();
+    let transferCleanup;
+    const actual = physical.promise.then(async () => {
+      await settled(this.startup);
+      await settled(this.process?.actual);
+      this.streams?.close();
+      await this.streams?.settled;
+      await transferCleanup;
+      if (this.snapshot.kind !== "destroying" && this.snapshot.kind !== "destroyed") this.snapshot = Object.freeze({ kind: "stopped" });
+    }).catch((error) => {
+      this.stopActual = void 0;
+      if (this.snapshot.kind !== "destroyed" && this.snapshot.kind !== "destroying") this.snapshot = Object.freeze({ kind: "uncertain", operation: "stop" });
+      throw error;
+    });
+    this.stopActual = actual;
+    void actual.catch(() => {
+    });
+    const reason = new SandboxOperationError("cancelled", "Sandbox compute is stopping.");
+    this.startupController.abort(reason);
+    this.process?.controller.abort(reason);
+    if (this.transfer?.kind === "import") this.transfer.controller.abort(reason);
+    this.cancelExecutionDeadline?.();
+    this.cancelExecutionDeadline = void 0;
+    actualOperation(() => this.driver.stop()).then(physical.resolve, physical.reject);
+    if (this.transfer?.kind === "import") {
+      transferCleanup = this.cleanupTransfer();
+      void transferCleanup.catch(() => {
+      });
+    }
+    this.streams?.close();
+    return actual;
+  }
+  importTree(entries, input) {
+    const options = parseTransferOptions(input);
+    if (this.snapshot.kind !== "ready" || this.processReserved || this.transfer) throw new SandboxStateError("File import requires ready compute, no entered import, and no process reservation.");
+    const ready = this.readyPort();
+    return this.enterFile("import", options, (controller) => importTree(ready, entries, {
+      signal: controller.signal,
+      quotas: options.quotas,
+      buffers: this.request.policy.transfers
+    }));
+  }
+  exportTree(selection, consume, input) {
+    const options = parseTransferOptions(input);
+    if (this.snapshot.kind !== "stopped" || this.transfer) throw new SandboxStateError("File export requires stopped compute and no other entered transfer.");
+    const ready = this.readyPort();
+    return this.enterFile("export", options, (controller) => exportTree(ready, selection, consume, {
+      signal: controller.signal,
+      quotas: options.quotas,
+      buffers: this.request.policy.transfers
+    }));
+  }
+  enterFile(kind, options, perform) {
+    if (options.signal?.aborted) return Promise.reject(new SandboxOperationError("cancelled", "Sandbox file transfer was cancelled before entry."));
+    if (options.deadlineAt !== void 0 && options.deadlineAt <= Date.now()) return Promise.reject(new SandboxOperationError("deadline_exceeded", "Sandbox file transfer deadline elapsed before entry."));
+    const controller = new AbortController();
+    const work = perform(controller);
+    const actual = work.actual;
+    const entry = { kind, controller, actual, work };
+    this.transfer = entry;
+    const release = () => {
+      if (this.transfer === entry && work.clean) this.transfer = void 0;
+    };
+    void actual.then(release, () => {
+      release();
+      if (kind === "import") this.fence("import");
+    });
+    const duration = options.deadlineAt === void 0 ? void 0 : Math.max(0, options.deadlineAt - Date.now());
+    const observation = observe(actual, duration, { signal: operationSignal(controller, options), onInterrupt: (error) => {
+      controller.abort(error);
+      this.fence(kind);
+      if (kind === "import") void this.stop().catch(() => {
+      });
+    } });
+    return observation;
+  }
+  async cleanupTransfer() {
+    const entry = this.transfer;
+    if (!entry) return;
+    await entry.work.cleanup();
+    if (this.transfer === entry && entry.work.clean) this.transfer = void 0;
+  }
+  reserveProcess(input) {
+    const spec = parseSandboxProcessSpec(input);
+    if (this.snapshot.kind !== "ready" || this.processReserved || this.transfer) throw new SandboxStateError("A sandbox admits one process reservation, after its imports settle.");
+    this.processReserved = true;
+    const reserved = this.readyPort().reserveProcess(spec);
+    const id = parseSandboxProcessId(reserved.id);
+    let entered = false;
+    return Object.freeze({ id, stopScope: "sandbox", start: (options) => {
+      const parsed = parseOperationOptions(options);
+      if (entered || this.snapshot.kind !== "ready") return Promise.reject(new SandboxStateError("Process startup is once-only and requires ready compute."));
+      entered = true;
+      const controller = new AbortController();
+      if (parsed.signal?.aborted) controller.abort(new SandboxOperationError("cancelled", "Process startup was cancelled before entry."));
+      const dispatch = Promise.withResolvers();
+      const actual = dispatch.promise;
+      this.process = { controller, actual };
+      const execution = this.request.policy.execution;
+      if (execution.kind === "deadline") {
+        this.cancelExecutionDeadline = scheduleDeadline(execution.timeoutMs, () => {
+          controller.abort(new SandboxOperationError("deadline_exceeded", "Sandbox execution exceeded its deadline."));
+          void this.stop().catch(() => {
+          });
+        });
+      }
+      const observation = observe(actual, this.request.policy.deadlines.startupMs, { signal: operationSignal(controller, parsed), onInterrupt: (error) => {
+        controller.abort(error);
+        this.fence("process");
+        void this.stop().catch(() => {
+        });
+      } });
+      void actual.catch(() => {
+        this.fence("process");
+        void this.stop().catch(() => {
+        });
+      });
+      actualOperation(async () => {
+        controller.signal.throwIfAborted();
+        const raw = await reserved.start({ signal: controller.signal });
+        const owned = ownProcessStreams(raw, this.request.policy.streams, () => {
+          void this.stop().catch(() => {
+          });
+        });
+        this.streams = owned;
+        if (controller.signal.aborted || this.snapshot.kind !== "ready") {
+          owned.close();
+          throw new SandboxOperationError("cancelled", "Process startup settled after its admission was closed.");
+        }
+        return owned.streams;
+      }).then(dispatch.resolve, dispatch.reject);
+      return observation;
+    }, stop: () => this.stop() });
+  }
+  readyPort() {
+    if (!this.ready) throw new SandboxStateError("Sandbox startup has not yielded a workspace.");
+    return this.ready;
+  }
+  fence(operation) {
+    if (this.snapshot.kind !== "destroyed" && this.snapshot.kind !== "destroying" && this.snapshot.kind !== "stopping" && this.snapshot.kind !== "stopped") {
+      this.snapshot = Object.freeze({ kind: "uncertain", operation });
+    }
+  }
+}
+function operationSignal(controller, options) {
+  return options.signal === void 0 ? controller.signal : AbortSignal.any([controller.signal, options.signal]);
+}
+export {
+  SandboxOwner
+};

package/dist/lifecycle/recovered.d.ts

@@ -0,0 +1,16 @@
+import type { SandboxCleanupOwner, SandboxRecoveryRecord } from '../recovery/types.js';
+/** Recovery grants cleanup only, using the driver that verified the original identities. */
+export declare class RecoveredSandboxOwner implements SandboxCleanupOwner {
+    private readonly driver;
+    private record;
+    private stopActual;
+    private destroyActual;
+    private stopObservation;
+    private destroyObservation;
+    constructor(driver: SandboxCleanupOwner, record: SandboxRecoveryRecord);
+    get recoveryRecord(): SandboxRecoveryRecord;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
+    private beginStop;
+}
+//# sourceMappingURL=recovered.d.ts.map

package/dist/lifecycle/recovered.js

@@ -0,0 +1,62 @@
+import { SandboxCleanupError } from "../errors.js";
+import { SANDBOX_LIMITS } from "../policy/limits.js";
+import { parseSandboxRecoveryRecord } from "../recovery/parse.js";
+import { actualOperation, observe } from "./observation.js";
+import { assertRecoveryContinuation } from "./recoveryIdentity.js";
+class RecoveredSandboxOwner {
+  constructor(driver, record) {
+    this.driver = driver;
+    this.record = record;
+  }
+  stopActual;
+  destroyActual;
+  stopObservation;
+  destroyObservation;
+  get recoveryRecord() {
+    const next = parseSandboxRecoveryRecord(this.driver.recoveryRecord);
+    assertRecoveryContinuation(this.record, next, "reconciliation");
+    this.record = next;
+    return next;
+  }
+  stop() {
+    this.stopObservation ??= observe(this.beginStop(), SANDBOX_LIMITS.cleanupMs).catch((cause) => {
+      throw new SandboxCleanupError("Recovered sandbox compute cleanup failed.", { cause, operation: "stop", owner: this });
+    }).finally(() => {
+      this.stopObservation = void 0;
+    });
+    return this.stopObservation;
+  }
+  destroy() {
+    this.destroyActual ??= this.beginStop().then(() => {
+      void this.recoveryRecord;
+      return this.driver.destroy();
+    }).catch((error) => {
+      this.destroyActual = void 0;
+      throw error;
+    });
+    this.destroyObservation ??= observe(this.destroyActual, SANDBOX_LIMITS.cleanupMs).catch((cause) => {
+      throw new SandboxCleanupError("Recovered sandbox destruction failed.", { cause, operation: "destroy", owner: this });
+    }).finally(() => {
+      this.destroyObservation = void 0;
+    });
+    return this.destroyObservation;
+  }
+  beginStop() {
+    if (!this.stopActual) {
+      const dispatch = Promise.withResolvers();
+      const actual = dispatch.promise.catch((error) => {
+        this.stopActual = void 0;
+        throw error;
+      });
+      this.stopActual = actual;
+      actualOperation(() => {
+        void this.recoveryRecord;
+        return this.driver.stop();
+      }).then(dispatch.resolve, dispatch.reject);
+    }
+    return this.stopActual;
+  }
+}
+export {
+  RecoveredSandboxOwner
+};

package/dist/lifecycle/recoveryIdentity.d.ts

@@ -0,0 +1,3 @@
+import type { SandboxRecoveryRecord } from '../recovery/types.js';
+export declare function assertRecoveryContinuation(previous: SandboxRecoveryRecord, next: SandboxRecoveryRecord, operation: 'checkpoint' | 'reconciliation'): void;
+//# sourceMappingURL=recoveryIdentity.d.ts.map

package/dist/lifecycle/recoveryIdentity.js

@@ -0,0 +1,18 @@
+import { SandboxStateError } from "../errors.js";
+function assertRecoveryContinuation(previous, next, operation) {
+  if (next.backendId !== previous.backendId || next.backendRevision !== previous.backendRevision || next.namespace !== previous.namespace || next.operationId !== previous.operationId || next.sandboxId !== previous.sandboxId || next.imageDigest !== previous.imageDigest || next.policyDigest !== previous.policyDigest || next.configurationDigest !== previous.configurationDigest || next.resources.length !== previous.resources.length) {
+    throw new SandboxStateError("Recovery observations cannot change their reserved ownership identity.");
+  }
+  if (previous.authority.kind === "verified" && (next.authority.kind !== "verified" || next.authority.backendIdentity !== previous.authority.backendIdentity)) {
+    throw new SandboxStateError("Recovery observations cannot replace verified backend authority.");
+  }
+  for (const resource of previous.resources) {
+    const replacement = next.resources.find((candidate) => candidate.role === resource.role);
+    if (!replacement || replacement.name !== resource.name || resource.identity.kind === "planned" && replacement.identity.kind === "identified" || resource.identity.kind === "planned" && replacement.identity.kind === "creating" && operation === "reconciliation" || resource.identity.kind === "creating" && replacement.identity.kind === "planned" || resource.identity.kind === "identified" && (replacement.identity.kind !== "identified" || replacement.identity.id !== resource.identity.id || replacement.identity.fingerprint !== resource.identity.fingerprint)) {
+      throw new SandboxStateError("Recovery observations cannot replace an owned resource identity or enter a new resource effect.");
+    }
+  }
+}
+export {
+  assertRecoveryContinuation
+};

package/dist/lifecycle/transfer.d.ts

@@ -0,0 +1,10 @@
+import type { SandboxDriverReady, SandboxDriverTransferOptions } from '../backend/contracts.js';
+import type { SandboxExportConsumer, SandboxTreeSelection, SandboxTreeSource, SandboxTransferSummary } from '../files/types.js';
+export interface OwnedTransfer {
+    readonly actual: Promise<SandboxTransferSummary>;
+    readonly clean: boolean;
+    cleanup(): Promise<void>;
+}
+export declare function importTree(ready: SandboxDriverReady, entries: SandboxTreeSource, selected: SandboxDriverTransferOptions): OwnedTransfer;
+export declare function exportTree(ready: SandboxDriverReady, input: SandboxTreeSelection, consume: SandboxExportConsumer, selectedOptions: SandboxDriverTransferOptions): OwnedTransfer;
+//# sourceMappingURL=transfer.d.ts.map