@agen-ai/sandbox 0.0.0-stage → 0.4.4

package/dist/files/parse.d.ts

@@ -0,0 +1,20 @@
+import type { SandboxTransferBudget, SandboxTransferOptions, SandboxTransferSummary } from './types.js';
+export declare function transferData(input: unknown, allowed: readonly string[]): Record<string, unknown>;
+export interface ParsedTransferOptions {
+    readonly signal?: AbortSignal;
+    readonly deadlineAt?: number;
+    readonly quotas: SandboxTransferBudget;
+}
+export declare function parseTransferOptions(input: SandboxTransferOptions | undefined): ParsedTransferOptions;
+export declare function parseTreeMetadata(input: unknown, bodyField: 'open' | 'bytes'): Readonly<{
+    kind: "directory";
+    path: import("./types.js").SandboxRelativePath;
+}> | Readonly<{
+    kind: "file";
+    path: import("./types.js").SandboxRelativePath;
+    byteLength: number;
+    executable: boolean;
+    body: unknown;
+}>;
+export declare function parseTransferSummary(input: unknown): SandboxTransferSummary;
+//# sourceMappingURL=parse.d.ts.map

package/dist/files/parse.js

@@ -0,0 +1,62 @@
+import { z } from "zod/v4";
+import { invalidInput } from "../internal/data.js";
+import { parseOperationOptions } from "../internal/operations.js";
+import { parseSandboxRelativePath } from "./paths.js";
+function transferData(input, allowed) {
+  if (input === null || typeof input !== "object" || Object.getPrototypeOf(input) !== Object.prototype && Object.getPrototypeOf(input) !== null) invalidInput("Transfer metadata must be a plain object");
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const key of Reflect.ownKeys(input)) {
+    if (typeof key !== "string" || !allowed.includes(key)) invalidInput("Unexpected transfer metadata field");
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) invalidInput("Transfer metadata must contain enumerable data fields");
+    result[key] = descriptor.value;
+  }
+  return result;
+}
+function parseTransferOptions(input) {
+  const data = input === void 0 ? {} : transferData(input, ["signal", "deadlineAt", "quotas"]);
+  const cancellation = parseOperationOptions(data.signal === void 0 ? void 0 : { signal: data.signal });
+  let deadlineAt;
+  if (data.deadlineAt !== void 0) {
+    if (!z.iso.datetime({ offset: true }).safeParse(data.deadlineAt).success) invalidInput("Transfer deadlineAt must be an ISO timestamp");
+    deadlineAt = Date.parse(String(data.deadlineAt));
+    if (!Number.isSafeInteger(deadlineAt)) invalidInput("Transfer deadlineAt must be representable in milliseconds");
+  }
+  const quotas = {};
+  if (data.quotas !== void 0) {
+    const selected = transferData(data.quotas, ["maxFiles", "maxFileBytes", "maxTotalBytes", "maxArchiveBytes", "maxPaths"]);
+    for (const key of ["maxFiles", "maxFileBytes", "maxTotalBytes", "maxArchiveBytes", "maxPaths"]) {
+      const value = selected[key];
+      if (value === void 0) continue;
+      if (typeof value !== "bigint" && (typeof value !== "number" || !Number.isSafeInteger(value))) invalidInput("Transfer quotas must be nonnegative integers");
+      if (value < 0) invalidInput("Transfer quotas must be nonnegative integers");
+      quotas[key] = BigInt(value);
+    }
+  }
+  return Object.freeze({ ...cancellation, ...deadlineAt === void 0 ? {} : { deadlineAt }, quotas: Object.freeze(quotas) });
+}
+function parseTreeMetadata(input, bodyField) {
+  const data = transferData(input, ["kind", "path", "byteLength", "executable", bodyField]);
+  const path = parseSandboxRelativePath(data.path);
+  if (data.kind === "directory") {
+    if (Reflect.ownKeys(data).length !== 2) invalidInput("Directories require only kind and path");
+    return Object.freeze({ kind: "directory", path });
+  }
+  if (data.kind !== "file" || Reflect.ownKeys(data).length !== 5) invalidInput("Files require kind, path, byteLength, executable and a body source");
+  if (typeof data.byteLength !== "number" || !Number.isSafeInteger(data.byteLength) || data.byteLength < 0) invalidInput("File byteLength must be a nonnegative safe integer");
+  if (typeof data.executable !== "boolean") invalidInput("File executable must be boolean");
+  if (bodyField === "open" && typeof data.open !== "function") invalidInput("Input files require an open function");
+  return Object.freeze({ kind: "file", path, byteLength: data.byteLength, executable: data.executable, body: data[bodyField] });
+}
+function parseTransferSummary(input) {
+  const data = transferData(input, ["files", "directories", "payloadBytes", "archiveBytes"]);
+  const { files, directories, payloadBytes, archiveBytes } = data;
+  if (typeof files !== "bigint" || files < 0n || typeof directories !== "bigint" || directories < 0n || typeof payloadBytes !== "bigint" || payloadBytes < 0n || typeof archiveBytes !== "bigint" || archiveBytes < 0n) invalidInput("Transfer summaries require nonnegative bigint counters");
+  return Object.freeze({ files, directories, payloadBytes, archiveBytes });
+}
+export {
+  parseTransferOptions,
+  parseTransferSummary,
+  parseTreeMetadata,
+  transferData
+};

package/dist/files/pathSchemas.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod/v4';
+import type { SandboxGuestPath, SandboxRelativePath } from './types.js';
+export declare const relativePathSchema: z.ZodCustom<SandboxRelativePath, SandboxRelativePath>;
+export declare const guestPathSchema: z.ZodCustom<SandboxGuestPath, SandboxGuestPath>;
+//# sourceMappingURL=pathSchemas.d.ts.map

package/dist/files/pathSchemas.js

@@ -0,0 +1,16 @@
+import { z } from "zod/v4";
+import { utf8Within } from "../internal/data.js";
+import { SANDBOX_LIMITS } from "../policy/limits.js";
+function safeSegments(path) {
+  const segments = path.split("/");
+  return segments.length <= SANDBOX_LIMITS.maxPathSegments && segments.every((segment) => segment.length > 0 && segment !== "." && segment !== ".." && utf8Within(segment, SANDBOX_LIMITS.maxPathSegmentBytes));
+}
+function safePath(value) {
+  return typeof value === "string" && value.length > 0 && utf8Within(value, SANDBOX_LIMITS.maxPathBytes) && !/[\\\u0000-\u001f\u007f]/u.test(value);
+}
+const relativePathSchema = z.custom((value) => safePath(value) && safeSegments(value), "Expected a bounded canonical relative file path");
+const guestPathSchema = z.custom((value) => safePath(value) && value.startsWith("/") && (value === "/" || safeSegments(value.slice(1))), "Expected a bounded canonical absolute guest path");
+export {
+  guestPathSchema,
+  relativePathSchema
+};

package/dist/files/paths.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxGuestPath, SandboxRelativePath } from './types.js';
+export declare function parseSandboxRelativePath(input: unknown): SandboxRelativePath;
+export declare function parseSandboxGuestPath(input: unknown): SandboxGuestPath;
+//# sourceMappingURL=paths.d.ts.map

package/dist/files/paths.js

@@ -0,0 +1,12 @@
+import { parseData } from "../internal/parse.js";
+import { guestPathSchema, relativePathSchema } from "./pathSchemas.js";
+function parseSandboxRelativePath(input) {
+  return parseData(relativePathSchema, input);
+}
+function parseSandboxGuestPath(input) {
+  return parseData(guestPathSchema, input);
+}
+export {
+  parseSandboxGuestPath,
+  parseSandboxRelativePath
+};

package/dist/files/quotas.d.ts

@@ -0,0 +1,18 @@
+import type { SandboxTransferBudget, SandboxTransferSummary } from './types.js';
+export declare class TransferCounters {
+    private readonly quotas;
+    private readonly direction;
+    files: bigint;
+    directories: bigint;
+    payloadBytes: bigint;
+    constructor(quotas: SandboxTransferBudget, direction: 'import' | 'export');
+    admit(entry: Readonly<{
+        kind: 'file';
+        byteLength: number;
+    }> | Readonly<{
+        kind: 'directory';
+    }>): void;
+    check(name: keyof SandboxTransferBudget, actual: bigint): void;
+    verify(input: unknown): SandboxTransferSummary;
+}
+//# sourceMappingURL=quotas.d.ts.map

package/dist/files/quotas.js

@@ -0,0 +1,37 @@
+import { SandboxOperationError } from "../errors.js";
+import { parseTransferSummary } from "./parse.js";
+class TransferCounters {
+  constructor(quotas, direction) {
+    this.quotas = quotas;
+    this.direction = direction;
+  }
+  files = 0n;
+  directories = 0n;
+  payloadBytes = 0n;
+  admit(entry) {
+    if (entry.kind === "directory") this.directories += 1n;
+    else {
+      this.files += 1n;
+      const bytes = BigInt(entry.byteLength);
+      this.payloadBytes += bytes;
+      this.check("maxFileBytes", bytes);
+      this.check("maxFiles", this.files);
+      this.check("maxTotalBytes", this.payloadBytes);
+    }
+  }
+  check(name, actual) {
+    const ceiling = this.quotas[name];
+    if (ceiling !== void 0 && actual > ceiling) throw new SandboxOperationError(this.direction === "import" ? "input_limit" : "output_limit", `Transfer exceeded caller quota ${name}.`);
+  }
+  verify(input) {
+    const summary = parseTransferSummary(input);
+    if (summary.files !== this.files || summary.directories !== this.directories || summary.payloadBytes !== this.payloadBytes) {
+      throw new SandboxOperationError("driver_failure", "Backend transfer summary disagrees with completely consumed entries.");
+    }
+    this.check("maxArchiveBytes", summary.archiveBytes);
+    return summary;
+  }
+}
+export {
+  TransferCounters
+};

package/dist/files/types.d.ts

@@ -0,0 +1,81 @@
+declare const relativePathBrand: unique symbol;
+declare const guestPathBrand: unique symbol;
+export type SandboxRelativePath = string & {
+    readonly [relativePathBrand]: true;
+};
+export type SandboxGuestPath = string & {
+    readonly [guestPathBrand]: true;
+};
+export type SandboxByteSource = AsyncIterable<Uint8Array> | Iterable<Uint8Array>;
+export type SandboxTreeEntry = Readonly<{
+    kind: 'directory';
+    path: string;
+}> | Readonly<{
+    kind: 'file';
+    path: string;
+    byteLength: number;
+    executable: boolean;
+    open(input: Readonly<{
+        signal: AbortSignal;
+    }>): SandboxByteSource;
+}>;
+export type SandboxTreeSource = AsyncIterable<SandboxTreeEntry> | Iterable<SandboxTreeEntry>;
+export type SandboxInputTreeEntry = Readonly<{
+    kind: 'directory';
+    path: SandboxRelativePath;
+}> | Readonly<{
+    kind: 'file';
+    path: SandboxRelativePath;
+    byteLength: number;
+    executable: boolean;
+    open(input: Readonly<{
+        signal: AbortSignal;
+    }>): SandboxByteSource;
+}>;
+export type SandboxExportEntry = Readonly<{
+    kind: 'directory';
+    path: string;
+}> | Readonly<{
+    kind: 'file';
+    path: string;
+    byteLength: number;
+    executable: boolean;
+    bytes: AsyncIterable<Uint8Array>;
+}>;
+export type SandboxExportConsumer = (entry: SandboxExportEntry, input: Readonly<{
+    signal: AbortSignal;
+}>) => Promise<void>;
+export type SandboxTreeSelection = Readonly<{
+    kind: 'workspace';
+}> | Readonly<{
+    kind: 'files';
+    paths: AsyncIterable<string> | Iterable<string>;
+}> | Readonly<{
+    kind: 'subtree';
+    path: string;
+}>;
+export type SandboxInputTreeSelection = Readonly<{
+    kind: 'workspace';
+}> | Readonly<{
+    kind: 'files';
+    paths: AsyncIterable<SandboxRelativePath>;
+}> | Readonly<{
+    kind: 'subtree';
+    path: SandboxRelativePath;
+}>;
+export type SandboxTransferQuotaName = 'maxFiles' | 'maxFileBytes' | 'maxTotalBytes' | 'maxArchiveBytes' | 'maxPaths';
+export type SandboxTransferQuotas = Readonly<Partial<Record<SandboxTransferQuotaName, number | bigint>>>;
+export type SandboxTransferBudget = Readonly<Partial<Record<SandboxTransferQuotaName, bigint>>>;
+export interface SandboxTransferOptions {
+    readonly signal?: AbortSignal;
+    readonly deadlineAt?: string;
+    readonly quotas?: SandboxTransferQuotas;
+}
+export interface SandboxTransferSummary {
+    readonly files: bigint;
+    readonly directories: bigint;
+    readonly payloadBytes: bigint;
+    readonly archiveBytes: bigint;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export type { OperationOptions, SandboxState, SandboxBackend, SandboxReservation, Sandbox, SandboxRunOptions } from './contracts.js';
+export type { SandboxNamespace, SandboxId, SandboxProcessId, SandboxResources, SandboxTemporaryStorage, SandboxNetworkPolicy, SandboxWorkspaceDiskQuota, SandboxExecutionPolicy, SandboxDeadlines, SandboxPolicyInput, SandboxPolicy, SandboxRequestInput, SandboxRequest, SandboxTransferBuffers, SandboxStreamLimits, SandboxSupport, SandboxEffectivePolicy } from './policy/types.js';
+export type { SandboxGuestPath, SandboxRelativePath, SandboxByteSource, SandboxTreeEntry, SandboxTreeSource, SandboxInputTreeEntry, SandboxExportEntry, SandboxExportConsumer, SandboxTreeSelection, SandboxInputTreeSelection, SandboxTransferQuotaName, SandboxTransferQuotas, SandboxTransferBudget, SandboxTransferOptions, SandboxTransferSummary } from './files/types.js';
+export type { SandboxProcessInput, SandboxProcessSpec, SandboxProcessExit, SandboxProcessStreams, SandboxProcessReservation } from './process/types.js';
+export type { SandboxRecoveryPhase, SandboxResourceIdentity, SandboxRecoveryResource, SandboxRecoveryAuthority, SandboxRecoveryRecord, SandboxRecoveryPolicy, SandboxCleanupOwner, SandboxReconciliation } from './recovery/types.js';
+export type { SandboxOperationErrorCode } from './errors.js';
+export { SandboxValidationError, SandboxUnsupportedError, SandboxStateError, SandboxOperationError, SandboxCleanupError, SandboxStartError, SandboxRunError } from './errors.js';
+export { SANDBOX_LIMITS, SANDBOX_DEFAULT_TRANSFER_BUFFERS, SANDBOX_DEFAULT_STREAM_LIMITS } from './policy/limits.js';
+export { parseSandboxNamespace, parseSandboxId, parseSandboxProcessId, parseSandboxPolicy, parseSandboxRequest, parseSandboxSupport, parseSandboxEffectivePolicy } from './policy/parse.js';
+export { parseSandboxRelativePath, parseSandboxGuestPath } from './files/paths.js';
+export { fileFromBytes } from './files/bytes.js';
+export { parseSandboxProcessSpec, parseSandboxProcessExit } from './process/parse.js';
+export { parseSandboxRecoveryRecord, parseSandboxRecoveryPolicy } from './recovery/parse.js';
+export { withSandbox } from './withSandbox.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,35 @@
+import { SandboxValidationError, SandboxUnsupportedError, SandboxStateError, SandboxOperationError, SandboxCleanupError, SandboxStartError, SandboxRunError } from "./errors.js";
+import { SANDBOX_LIMITS, SANDBOX_DEFAULT_TRANSFER_BUFFERS, SANDBOX_DEFAULT_STREAM_LIMITS } from "./policy/limits.js";
+import { parseSandboxNamespace, parseSandboxId, parseSandboxProcessId, parseSandboxPolicy, parseSandboxRequest, parseSandboxSupport, parseSandboxEffectivePolicy } from "./policy/parse.js";
+import { parseSandboxRelativePath, parseSandboxGuestPath } from "./files/paths.js";
+import { fileFromBytes } from "./files/bytes.js";
+import { parseSandboxProcessSpec, parseSandboxProcessExit } from "./process/parse.js";
+import { parseSandboxRecoveryRecord, parseSandboxRecoveryPolicy } from "./recovery/parse.js";
+import { withSandbox } from "./withSandbox.js";
+export {
+  SANDBOX_DEFAULT_STREAM_LIMITS,
+  SANDBOX_DEFAULT_TRANSFER_BUFFERS,
+  SANDBOX_LIMITS,
+  SandboxCleanupError,
+  SandboxOperationError,
+  SandboxRunError,
+  SandboxStartError,
+  SandboxStateError,
+  SandboxUnsupportedError,
+  SandboxValidationError,
+  fileFromBytes,
+  parseSandboxEffectivePolicy,
+  parseSandboxGuestPath,
+  parseSandboxId,
+  parseSandboxNamespace,
+  parseSandboxPolicy,
+  parseSandboxProcessExit,
+  parseSandboxProcessId,
+  parseSandboxProcessSpec,
+  parseSandboxRecoveryPolicy,
+  parseSandboxRecoveryRecord,
+  parseSandboxRelativePath,
+  parseSandboxRequest,
+  parseSandboxSupport,
+  withSandbox
+};

package/dist/internal/data.d.ts

@@ -0,0 +1,6 @@
+export declare function invalidInput(message: string, path?: readonly (string | number)[]): never;
+/** Capture plain data without invoking caller-controlled accessors or retaining mutable input. */
+export declare function captureData(input: unknown): unknown;
+export declare function freezeData<Value>(value: Value): Value;
+export declare function utf8Within(value: string, maximum: number): boolean;
+//# sourceMappingURL=data.d.ts.map

package/dist/internal/data.js

@@ -0,0 +1,68 @@
+import { Buffer } from "node:buffer";
+import { SandboxValidationError } from "../errors.js";
+function invalidInput(message, path = []) {
+  throw new SandboxValidationError([{ code: "invalid_input", path, message }]);
+}
+function captureData(input) {
+  const seen = /* @__PURE__ */ new Set();
+  let nodes = 0;
+  let bytes = 0;
+  function capture(value, depth) {
+    nodes += 1;
+    if (nodes > 8192 || depth > 16) invalidInput("Sandbox input exceeds structural bounds");
+    if (typeof value === "string") {
+      bytes += Buffer.byteLength(value, "utf8");
+      if (bytes > 1024 * 1024) invalidInput("Sandbox input exceeds text bounds");
+      if (!value.isWellFormed()) invalidInput("Sandbox strings must contain well-formed Unicode");
+      return value;
+    }
+    if (value === null || typeof value === "number" || typeof value === "boolean" || value === void 0) return value;
+    if (typeof value !== "object") invalidInput("Sandbox inputs must contain plain data");
+    if (seen.has(value)) invalidInput("Sandbox inputs cannot contain cycles");
+    seen.add(value);
+    const array = Array.isArray(value);
+    const prototype = Object.getPrototypeOf(value);
+    if (!array && prototype !== Object.prototype && prototype !== null) invalidInput("Sandbox inputs must contain plain objects");
+    const keys = Reflect.ownKeys(value);
+    if (keys.length > 8192) invalidInput("Sandbox input exceeds structural bounds");
+    if (array) {
+      const result2 = [];
+      for (let index = 0; index < value.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor === void 0 || !("value" in descriptor)) invalidInput("Sandbox arrays must be dense data arrays");
+        result2.push(capture(descriptor.value, depth + 1));
+      }
+      if (keys.length !== value.length + 1) invalidInput("Sandbox arrays cannot have extra properties");
+      seen.delete(value);
+      return result2;
+    }
+    const result = /* @__PURE__ */ Object.create(null);
+    for (const key of keys) {
+      if (typeof key !== "string") invalidInput("Sandbox inputs cannot contain symbol keys");
+      if (key === "__proto__") invalidInput("Sandbox inputs cannot contain prototype mutation keys");
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor === void 0 || !("value" in descriptor) || !descriptor.enumerable) invalidInput("Sandbox inputs cannot contain accessors or hidden fields");
+      result[key] = capture(descriptor.value, depth + 1);
+    }
+    seen.delete(value);
+    return result;
+  }
+  return capture(input, 0);
+}
+function freezeData(value) {
+  if (value !== null && typeof value === "object") {
+    if (Array.isArray(value)) value.forEach(freezeData);
+    else Object.values(value).forEach(freezeData);
+    Object.freeze(value);
+  }
+  return value;
+}
+function utf8Within(value, maximum) {
+  return value.isWellFormed() && Buffer.byteLength(value, "utf8") <= maximum;
+}
+export {
+  captureData,
+  freezeData,
+  invalidInput,
+  utf8Within
+};

package/dist/internal/operations.d.ts

@@ -0,0 +1,4 @@
+import type { OperationOptions, SandboxRunOptions } from '../contracts.js';
+export declare function parseOperationOptions(input?: unknown): OperationOptions;
+export declare function parseSandboxRunOptions(input: unknown): SandboxRunOptions;
+//# sourceMappingURL=operations.d.ts.map

package/dist/internal/operations.js

@@ -0,0 +1,30 @@
+import { parseSandboxRecoveryPolicy } from "../recovery/parse.js";
+import { invalidInput } from "./data.js";
+function parseOperationOptions(input = void 0) {
+  if (input === void 0) return Object.freeze({});
+  if (input === null || typeof input !== "object" || Object.getPrototypeOf(input) !== Object.prototype && Object.getPrototypeOf(input) !== null) invalidInput("Operation options must be a plain object");
+  const keys = Reflect.ownKeys(input);
+  if (keys.some((key) => key !== "signal")) invalidInput("Operation options support only signal");
+  const descriptor = Object.getOwnPropertyDescriptor(input, "signal");
+  if (descriptor === void 0) return Object.freeze({});
+  if (!("value" in descriptor) || !descriptor.enumerable) invalidInput("Operation signal must be a data field");
+  const signal = descriptor.value;
+  if (signal === void 0) return Object.freeze({});
+  if (!(signal instanceof AbortSignal)) invalidInput("Operation signal must be an AbortSignal");
+  return Object.freeze({ signal });
+}
+function parseSandboxRunOptions(input) {
+  if (input === null || typeof input !== "object" || Object.getPrototypeOf(input) !== Object.prototype && Object.getPrototypeOf(input) !== null) invalidInput("Sandbox run options must be a plain object");
+  if (Reflect.ownKeys(input).some((key) => key !== "signal" && key !== "recovery")) invalidInput("Sandbox run options support only recovery and signal");
+  const descriptor = Object.getOwnPropertyDescriptor(input, "recovery");
+  if (descriptor === void 0 || !("value" in descriptor) || !descriptor.enumerable) invalidInput("Sandbox run options require an explicit recovery policy");
+  const recovery = parseSandboxRecoveryPolicy(descriptor.value);
+  const signal = Object.getOwnPropertyDescriptor(input, "signal");
+  if (signal === void 0) return Object.freeze({ recovery });
+  if (!("value" in signal) || !signal.enumerable) invalidInput("Operation signal must be a data field");
+  return Object.freeze({ ...parseOperationOptions({ signal: signal.value }), recovery });
+}
+export {
+  parseOperationOptions,
+  parseSandboxRunOptions
+};

package/dist/internal/parse.d.ts

@@ -0,0 +1,3 @@
+import type { ZodType } from 'zod/v4';
+export declare function parseData<Value>(schema: ZodType<Value>, input: unknown): Value;
+//# sourceMappingURL=parse.d.ts.map

package/dist/internal/parse.js

@@ -0,0 +1,12 @@
+import { normalizeZodValidationError } from "@agen-ai/validation/zod";
+import { SandboxValidationError } from "../errors.js";
+import { captureData, freezeData } from "./data.js";
+function parseData(schema, input) {
+  const captured = captureData(input);
+  const result = schema.safeParse(captured);
+  if (!result.success) throw new SandboxValidationError(normalizeZodValidationError(schema, result.error, captured));
+  return freezeData(result.data);
+}
+export {
+  parseData
+};

package/dist/lifecycle/deadline.d.ts

@@ -0,0 +1,3 @@
+/** Slices an admitted finite duration without turning Node timer overflow into immediate expiry. */
+export declare function scheduleDeadline(timeoutMs: number, expire: () => void): () => void;
+//# sourceMappingURL=deadline.d.ts.map

package/dist/lifecycle/deadline.js

@@ -0,0 +1,18 @@
+const MAX_TIMER_DELAY_MS = 2147483647;
+function scheduleDeadline(timeoutMs, expire) {
+  const started = performance.now();
+  let timer;
+  const check = () => {
+    const remaining = timeoutMs - (performance.now() - started);
+    if (remaining <= 0) {
+      expire();
+      return;
+    }
+    timer = setTimeout(check, Math.min(Math.ceil(remaining), MAX_TIMER_DELAY_MS));
+  };
+  timer = setTimeout(check, Math.min(timeoutMs, MAX_TIMER_DELAY_MS));
+  return () => clearTimeout(timer);
+}
+export {
+  scheduleDeadline
+};

package/dist/lifecycle/journal.d.ts

@@ -0,0 +1,14 @@
+import type { SandboxRecoveryPolicy, SandboxRecoveryRecord } from '../recovery/types.js';
+export declare class RecoveryJournal {
+    private readonly policy;
+    private readonly onFailure;
+    private tail;
+    private failure;
+    private record;
+    constructor(record: SandboxRecoveryRecord, policy: SandboxRecoveryPolicy, onFailure: (error: unknown) => void);
+    get current(): SandboxRecoveryRecord;
+    initialize(): Promise<void>;
+    checkpoint: (input: SandboxRecoveryRecord) => Promise<void>;
+    private fail;
+}
+//# sourceMappingURL=journal.d.ts.map

package/dist/lifecycle/journal.js

@@ -0,0 +1,51 @@
+import { SandboxOperationError } from "../errors.js";
+import { parseSandboxRecoveryRecord } from "../recovery/parse.js";
+import { assertRecoveryContinuation } from "./recoveryIdentity.js";
+class RecoveryJournal {
+  constructor(record, policy, onFailure) {
+    this.policy = policy;
+    this.onFailure = onFailure;
+    this.record = record;
+  }
+  tail = Promise.resolve();
+  failure;
+  record;
+  get current() {
+    return this.record;
+  }
+  initialize() {
+    return this.checkpoint(this.record);
+  }
+  checkpoint = (input) => {
+    let next;
+    try {
+      next = parseSandboxRecoveryRecord(input);
+    } catch (error) {
+      return this.fail(error);
+    }
+    const work = this.tail.then(async () => {
+      if (this.failure) throw this.failure.error;
+      assertRecoveryContinuation(this.record, next, "checkpoint");
+      this.record = next;
+      if (this.policy.kind === "persisted") await this.policy.persist(next);
+    }).catch((error) => {
+      if (!this.failure) {
+        this.failure = { error: new SandboxOperationError("persistence_failure", "Sandbox recovery checkpoint failed.", { cause: error }) };
+        this.onFailure(this.failure.error);
+      }
+      throw this.failure.error;
+    });
+    this.tail = work;
+    void work.catch(() => {
+    });
+    return work;
+  };
+  fail(error) {
+    this.failure ??= { error: new SandboxOperationError("persistence_failure", "Sandbox recovery checkpoint is invalid.", { cause: error }) };
+    this.onFailure(this.failure.error);
+    return Promise.reject(this.failure.error);
+  }
+}
+export {
+  RecoveryJournal
+};

package/dist/lifecycle/observation.d.ts

@@ -0,0 +1,9 @@
+import { SandboxOperationError } from '../errors.js';
+/** Limits a caller's wait without replacing or abandoning the actual operation. */
+export declare function observe<T>(actual: Promise<T>, deadlineMs: number | undefined, options?: {
+    readonly signal?: AbortSignal;
+    readonly onInterrupt?: (error: SandboxOperationError) => void;
+}): Promise<T>;
+export declare function actualOperation<T>(perform: () => Promise<T>): Promise<T>;
+export declare function settled(actual: Promise<unknown> | undefined): Promise<void>;
+//# sourceMappingURL=observation.d.ts.map

package/dist/lifecycle/observation.js

@@ -0,0 +1,41 @@
+import { SandboxOperationError } from "../errors.js";
+import { scheduleDeadline } from "./deadline.js";
+function observe(actual, deadlineMs, options = {}) {
+  return new Promise((resolve, reject) => {
+    let settled2 = false;
+    const finish = (complete) => {
+      if (settled2) return;
+      settled2 = true;
+      cancelDeadline?.();
+      options.signal?.removeEventListener("abort", abort);
+      complete();
+    };
+    const interrupt = (error) => finish(() => {
+      options.onInterrupt?.(error);
+      reject(error);
+    });
+    const abort = () => interrupt(options.signal?.reason instanceof SandboxOperationError ? options.signal.reason : new SandboxOperationError("cancelled", "Sandbox operation was cancelled."));
+    const cancelDeadline = deadlineMs === void 0 ? void 0 : scheduleDeadline(
+      deadlineMs,
+      () => interrupt(new SandboxOperationError("deadline_exceeded", "Sandbox operation exceeded its observation deadline."))
+    );
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted) abort();
+    actual.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+  });
+}
+function actualOperation(perform) {
+  try {
+    return Promise.resolve(perform());
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+function settled(actual) {
+  return actual?.then(() => void 0, () => void 0) ?? Promise.resolve();
+}
+export {
+  actualOperation,
+  observe,
+  settled
+};

package/dist/lifecycle/owner.d.ts

@@ -0,0 +1,38 @@
+import type { SandboxDriverReservation } from '../backend/contracts.js';
+import type { OperationOptions, Sandbox, SandboxReservation, SandboxState } from '../contracts.js';
+import type { SandboxRequest } from '../policy/types.js';
+import type { SandboxRecoveryPolicy, SandboxRecoveryRecord } from '../recovery/types.js';
+export declare class SandboxOwner implements SandboxReservation {
+    private readonly driver;
+    private readonly request;
+    private snapshot;
+    private readonly journal;
+    private readonly startupController;
+    private startup;
+    private ready;
+    private transfer;
+    private processReserved;
+    private process;
+    private streams;
+    private cancelExecutionDeadline;
+    private stopActual;
+    private destroyActual;
+    private stopObservation;
+    private destroyObservation;
+    constructor(driver: SandboxDriverReservation, request: SandboxRequest, recovery: SandboxRecoveryPolicy, record: SandboxRecoveryRecord);
+    get id(): import("../index.js").SandboxId;
+    get state(): SandboxState;
+    get recoveryRecord(): SandboxRecoveryRecord;
+    start(input?: OperationOptions): Promise<Sandbox>;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
+    private beginStop;
+    private importTree;
+    private exportTree;
+    private enterFile;
+    private cleanupTransfer;
+    private reserveProcess;
+    private readyPort;
+    private fence;
+}
+//# sourceMappingURL=owner.d.ts.map