@agen-ai/sandbox 0.0.0-stage → 0.4.4

package/dist/policy/schemas.js

@@ -0,0 +1,75 @@
+import { z } from "zod/v4";
+import { utf8Within } from "../internal/data.js";
+import { SANDBOX_LIMITS } from "./limits.js";
+const safeIdentity = (value, maximum) => typeof value === "string" && value.length > 0 && utf8Within(value, maximum) && !/[\u0000-\u0020\u007f/\\]/u.test(value);
+const identitySchema = z.string().refine((value) => safeIdentity(value, SANDBOX_LIMITS.maxIdentityBytes), "Expected a bounded identity without whitespace or separators");
+const namespaceSchema = z.custom((value) => safeIdentity(value, SANDBOX_LIMITS.maxNamespaceBytes), "Expected a bounded namespace");
+const sandboxIdSchema = z.custom((value) => safeIdentity(value, SANDBOX_LIMITS.maxIdentityBytes), "Expected a bounded sandbox ID");
+const processIdSchema = z.custom((value) => safeIdentity(value, SANDBOX_LIMITS.maxIdentityBytes), "Expected a bounded process ID");
+const positiveInteger = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const bounded = (maximum) => positiveInteger.max(maximum);
+const resourcesSchema = z.strictObject({ cpus: z.number().finite().positive(), memoryBytes: positiveInteger, pids: positiveInteger });
+const temporaryStorageSchema = z.strictObject({ homeBytes: positiveInteger, tempBytes: positiveInteger });
+const networkSchema = z.discriminatedUnion("kind", [z.strictObject({ kind: z.literal("isolated") }), z.strictObject({ kind: z.literal("outbound") })]);
+const noWorkspaceDiskQuotaSchema = z.strictObject({ kind: z.literal("not_requested") });
+const workspaceDiskQuotaSchema = z.discriminatedUnion("kind", [
+  noWorkspaceDiskQuotaSchema,
+  z.strictObject({ kind: z.literal("required"), bytes: positiveInteger, accounting: z.literal("allocated_blocks") })
+]);
+const executionSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("until_stopped") }),
+  z.strictObject({ kind: z.literal("deadline"), timeoutMs: positiveInteger })
+]);
+const transferBuffersSchema = z.strictObject({
+  chunkBytes: bounded(SANDBOX_LIMITS.maxTransferChunkBytes).min(512),
+  metadataBatchBytes: bounded(SANDBOX_LIMITS.maxMetadataBatchBytes).min(SANDBOX_LIMITS.maxPathBytes + 5),
+  metadataMergeFanIn: bounded(SANDBOX_LIMITS.maxMetadataMergeFanIn).min(2)
+});
+const streamLimitsSchema = z.strictObject({
+  maxStdinBytes: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+  maxOutputBytes: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+  maxBufferedInputBytes: bounded(SANDBOX_LIMITS.maxBufferedInputBytes),
+  maxBufferedOutputBytes: bounded(SANDBOX_LIMITS.maxBufferedOutputBytes),
+  highWaterMarkBytes: bounded(SANDBOX_LIMITS.highWaterMarkBytes)
+}).refine((value) => value.highWaterMarkBytes <= value.maxBufferedOutputBytes && value.highWaterMarkBytes <= value.maxBufferedInputBytes, "Stream high-water mark must fit within its buffer bounds");
+const policySchema = z.strictObject({
+  resources: resourcesSchema,
+  temporaryStorage: temporaryStorageSchema,
+  network: networkSchema,
+  workspaceDiskQuota: workspaceDiskQuotaSchema.default({ kind: "not_requested" }),
+  execution: executionSchema.default({ kind: "until_stopped" }),
+  deadlines: z.strictObject({ startupMs: bounded(SANDBOX_LIMITS.startupMs), cleanupMs: bounded(SANDBOX_LIMITS.cleanupMs) }),
+  transfers: transferBuffersSchema,
+  streams: streamLimitsSchema
+});
+const requestSchema = z.strictObject({ policy: policySchema });
+const supportSchema = z.strictObject({
+  backendId: identitySchema,
+  backendRevision: identitySchema,
+  networkModes: z.array(z.enum(["isolated", "outbound"])).min(1).max(2).refine((modes) => new Set(modes).size === modes.length, "Network modes must be unique"),
+  workspaceDiskQuota: z.literal(false),
+  networkAllowlist: z.literal(false),
+  independentProcessTermination: z.literal(false)
+});
+const effectiveSchema = z.strictObject({
+  backendIdentity: identitySchema,
+  isolation: z.enum(["container", "virtual_machine"]),
+  resources: resourcesSchema,
+  temporaryStorage: temporaryStorageSchema,
+  network: networkSchema,
+  nonRoot: z.literal(true),
+  readOnlyRoot: z.literal(true),
+  workspaceDiskQuota: noWorkspaceDiskQuotaSchema
+});
+export {
+  effectiveSchema,
+  identitySchema,
+  namespaceSchema,
+  policySchema,
+  processIdSchema,
+  requestSchema,
+  sandboxIdSchema,
+  streamLimitsSchema,
+  supportSchema,
+  transferBuffersSchema
+};

package/dist/policy/types.d.ts

@@ -0,0 +1,105 @@
+declare const namespaceBrand: unique symbol;
+declare const sandboxIdBrand: unique symbol;
+declare const processIdBrand: unique symbol;
+export type SandboxNamespace = string & {
+    readonly [namespaceBrand]: true;
+};
+export type SandboxId = string & {
+    readonly [sandboxIdBrand]: true;
+};
+export type SandboxProcessId = string & {
+    readonly [processIdBrand]: true;
+};
+export interface SandboxResources {
+    readonly cpus: number;
+    readonly memoryBytes: number;
+    readonly pids: number;
+}
+export interface SandboxTemporaryStorage {
+    readonly homeBytes: number;
+    readonly tempBytes: number;
+}
+export type SandboxNetworkPolicy = Readonly<{
+    kind: 'isolated';
+}> | Readonly<{
+    kind: 'outbound';
+}>;
+export type SandboxWorkspaceDiskQuota = Readonly<{
+    kind: 'not_requested';
+}>
+/** Allocated filesystem blocks; this does not request inode or logical-file-size enforcement. */
+ | Readonly<{
+    kind: 'required';
+    bytes: number;
+    accounting: 'allocated_blocks';
+}>;
+export type SandboxExecutionPolicy = Readonly<{
+    kind: 'until_stopped';
+}>
+/** Starts at process launch entry; withSandbox also bounds its callback by this duration. */
+ | Readonly<{
+    kind: 'deadline';
+    timeoutMs: number;
+}>;
+export interface SandboxDeadlines {
+    readonly startupMs: number;
+    readonly cleanupMs: number;
+}
+export interface SandboxPolicy {
+    readonly resources: SandboxResources;
+    readonly temporaryStorage: SandboxTemporaryStorage;
+    readonly network: SandboxNetworkPolicy;
+    readonly workspaceDiskQuota: SandboxWorkspaceDiskQuota;
+    readonly execution: SandboxExecutionPolicy;
+    readonly deadlines: SandboxDeadlines;
+    readonly transfers: SandboxTransferBuffers;
+    readonly streams: SandboxStreamLimits;
+}
+export type SandboxPolicyInput = Omit<SandboxPolicy, 'execution' | 'workspaceDiskQuota'> & {
+    /** Omission normalizes to until_stopped, with no execution timer. */
+    readonly execution?: SandboxExecutionPolicy;
+    /** Omission requests no hard workspace disk quota. Backend storage limits remain independent. */
+    readonly workspaceDiskQuota?: SandboxWorkspaceDiskQuota;
+};
+export interface SandboxRequestInput {
+    readonly policy: SandboxPolicyInput;
+}
+export interface SandboxRequest {
+    readonly policy: SandboxPolicy;
+}
+export interface SandboxTransferBuffers {
+    readonly chunkBytes: number;
+    readonly metadataBatchBytes: number;
+    readonly metadataMergeFanIn: number;
+}
+export interface SandboxStreamLimits {
+    readonly maxStdinBytes?: number;
+    readonly maxOutputBytes?: number;
+    /** Public stdin staging, including writes made without respecting backpressure. */
+    readonly maxBufferedInputBytes: number;
+    /** Combined public stdout/stderr staging; backend transport buffers are bounded separately. */
+    readonly maxBufferedOutputBytes: number;
+    readonly highWaterMarkBytes: number;
+}
+export interface SandboxSupport {
+    readonly backendId: string;
+    readonly backendRevision: string;
+    readonly networkModes: readonly SandboxNetworkPolicy['kind'][];
+    readonly workspaceDiskQuota: false;
+    readonly networkAllowlist: false;
+    readonly independentProcessTermination: false;
+}
+export interface SandboxEffectivePolicy {
+    readonly backendIdentity: string;
+    readonly isolation: 'container' | 'virtual_machine';
+    readonly resources: SandboxResources;
+    readonly temporaryStorage: SandboxTemporaryStorage;
+    readonly network: SandboxNetworkPolicy;
+    readonly nonRoot: true;
+    readonly readOnlyRoot: true;
+    readonly workspaceDiskQuota: Readonly<{
+        kind: 'not_requested';
+    }>;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/process/input.d.ts

@@ -0,0 +1,23 @@
+import { Writable } from 'node:stream';
+type WriteCallback = (error?: Error | null) => void;
+export declare class SandboxInput extends Writable {
+    private readonly target;
+    private readonly maximumBytes;
+    private readonly maximumBufferedBytes;
+    private readonly fail;
+    readonly settled: Promise<void>;
+    private admitted;
+    private closing;
+    private activeWrite;
+    constructor(target: Writable, maximumBytes: number | undefined, maximumBufferedBytes: number, highWaterMark: number, fail: (error: Error) => void);
+    write(chunk: unknown, encodingOrCallback?: BufferEncoding | WriteCallback, callback?: WriteCallback): boolean;
+    end(chunkOrCallback?: unknown, encodingOrCallback?: BufferEncoding | (() => void), callback?: () => void): this;
+    _write(chunk: Uint8Array, _encoding: BufferEncoding, callback: WriteCallback): void;
+    _final(callback: WriteCallback): void;
+    _destroy(error: Error | null, callback: WriteCallback): void;
+    close(error?: Error): void;
+    private admit;
+    private ownCallback;
+}
+export {};
+//# sourceMappingURL=input.d.ts.map

package/dist/process/input.js

@@ -0,0 +1,93 @@
+import { Writable } from "node:stream";
+import { finished } from "node:stream/promises";
+import { SandboxOperationError } from "../errors.js";
+class SandboxInput extends Writable {
+  constructor(target, maximumBytes, maximumBufferedBytes, highWaterMark, fail) {
+    super({ highWaterMark, decodeStrings: false });
+    this.target = target;
+    this.maximumBytes = maximumBytes;
+    this.maximumBufferedBytes = maximumBufferedBytes;
+    this.fail = fail;
+    this.settled = finished(target, { readable: false, cleanup: true }).then(() => void 0, () => void 0);
+    this.on("error", () => {
+    });
+    target.on("error", (error) => this.destroy(error));
+    target.on("close", () => {
+      if (!this.writableFinished) this.destroy();
+    });
+  }
+  settled;
+  admitted = 0n;
+  closing = false;
+  activeWrite;
+  write(chunk, encodingOrCallback, callback) {
+    const complete = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+    const error = this.admit(chunk);
+    if (error) {
+      if (complete) queueMicrotask(() => complete(error));
+      this.destroy(error);
+      return false;
+    }
+    return typeof encodingOrCallback === "string" ? super.write(chunk, encodingOrCallback, callback) : super.write(chunk, complete);
+  }
+  end(chunkOrCallback, encodingOrCallback, callback) {
+    if (typeof chunkOrCallback === "function") return super.end(chunkOrCallback);
+    const complete = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+    if (chunkOrCallback !== void 0 && chunkOrCallback !== null) this.write(chunkOrCallback);
+    return super.end(complete);
+  }
+  _write(chunk, _encoding, callback) {
+    const complete = this.ownCallback(callback);
+    try {
+      this.target.write(chunk, complete);
+    } catch (error) {
+      complete(error instanceof Error ? error : new SandboxOperationError("stream_failure", "Sandbox input failed.", { cause: error }));
+    }
+  }
+  _final(callback) {
+    const complete = this.ownCallback(callback);
+    try {
+      this.target.end(complete);
+    } catch (error) {
+      complete(error instanceof Error ? error : new SandboxOperationError("stream_failure", "Sandbox input failed.", { cause: error }));
+    }
+  }
+  _destroy(error, callback) {
+    this.activeWrite?.(error ?? new SandboxOperationError("cancelled", "Sandbox input was closed before its pending write settled."));
+    this.target.destroy(error ?? void 0);
+    if (!this.closing && (!this.writableFinished || error)) {
+      this.fail(error ?? new SandboxOperationError("stream_failure", "Sandbox input was abandoned."));
+    }
+    callback(error);
+  }
+  close(error) {
+    this.closing = true;
+    this.destroy(error);
+  }
+  admit(chunk) {
+    if (!(chunk instanceof Uint8Array)) return new SandboxOperationError("stream_failure", "Sandbox stdin accepts only binary byte chunks.");
+    if (chunk.byteLength > this.maximumBufferedBytes - this.writableLength) {
+      return new SandboxOperationError("input_limit", "Sandbox stdin exceeded its buffered byte limit.");
+    }
+    const next = this.admitted + BigInt(chunk.byteLength);
+    if (this.maximumBytes !== void 0 && next > BigInt(this.maximumBytes)) {
+      return new SandboxOperationError("input_limit", "Sandbox stdin exceeded its caller-selected lifetime byte limit.");
+    }
+    this.admitted = next;
+    return void 0;
+  }
+  ownCallback(callback) {
+    let settled = false;
+    const complete = (error) => {
+      if (settled) return;
+      settled = true;
+      this.activeWrite = void 0;
+      callback(error);
+    };
+    this.activeWrite = complete;
+    return complete;
+  }
+}
+export {
+  SandboxInput
+};

package/dist/process/output.d.ts

@@ -0,0 +1,13 @@
+import { Readable } from 'node:stream';
+export declare class SandboxOutput extends Readable {
+    private readonly abandoned;
+    private demand;
+    private complete;
+    constructor(highWaterMark: number, abandoned: (error: Error) => void);
+    _read(): void;
+    deliver(chunk: Uint8Array): Promise<void>;
+    finish(): void;
+    close(error?: Error): void;
+    _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
+}
+//# sourceMappingURL=output.d.ts.map

package/dist/process/output.js

@@ -0,0 +1,43 @@
+import { Readable } from "node:stream";
+import { SandboxOperationError } from "../errors.js";
+class SandboxOutput extends Readable {
+  constructor(highWaterMark, abandoned) {
+    super({ highWaterMark });
+    this.abandoned = abandoned;
+    this.on("error", () => {
+    });
+  }
+  demand;
+  complete = false;
+  _read() {
+    this.demand?.();
+    this.demand = void 0;
+  }
+  async deliver(chunk) {
+    if (this.destroyed) throw new SandboxOperationError("stream_failure", "Sandbox output is closed.");
+    const demand = Promise.withResolvers();
+    this.demand = demand.resolve;
+    if (this.push(chunk) || this.readableLength < this.readableHighWaterMark) {
+      this.demand = void 0;
+      return;
+    }
+    await demand.promise;
+  }
+  finish() {
+    this.complete = true;
+    this.push(null);
+  }
+  close(error) {
+    this.complete = true;
+    this.destroy(error);
+  }
+  _destroy(error, callback) {
+    this.demand?.();
+    this.demand = void 0;
+    if (!this.complete) this.abandoned(error ?? new SandboxOperationError("stream_failure", "Sandbox output reader was abandoned."));
+    callback(error);
+  }
+}
+export {
+  SandboxOutput
+};

package/dist/process/parse.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxProcessExit, SandboxProcessSpec } from './types.js';
+export declare function parseSandboxProcessSpec(input: unknown): SandboxProcessSpec;
+export declare function parseSandboxProcessExit(input: unknown): SandboxProcessExit;
+//# sourceMappingURL=parse.d.ts.map

package/dist/process/parse.js

@@ -0,0 +1,32 @@
+import { Buffer } from "node:buffer";
+import { z } from "zod/v4";
+import { guestPathSchema } from "../files/pathSchemas.js";
+import { utf8Within } from "../internal/data.js";
+import { parseData } from "../internal/parse.js";
+import { SANDBOX_LIMITS } from "../policy/limits.js";
+const argumentSchema = z.string().refine((value) => !value.includes("\0") && utf8Within(value, SANDBOX_LIMITS.maxRecipeBytes), "Process arguments must be bounded and NUL-free");
+const environmentSchema = z.record(
+  z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u).max(SANDBOX_LIMITS.maxIdentityBytes),
+  z.string().refine((value) => !value.includes("\0") && utf8Within(value, SANDBOX_LIMITS.maxEnvValueBytes), "Environment values must be bounded and NUL-free")
+).refine((value) => Object.keys(value).length <= SANDBOX_LIMITS.maxEnvEntries, "Too many explicit environment entries");
+const processSchema = z.strictObject({
+  executable: guestPathSchema,
+  args: z.array(argumentSchema).max(SANDBOX_LIMITS.maxArgs),
+  env: environmentSchema,
+  cwd: guestPathSchema
+}).refine((value) => Buffer.byteLength(JSON.stringify(value), "utf8") <= SANDBOX_LIMITS.maxRecipeBytes, "Process recipe exceeds its aggregate UTF-8 bound");
+const exitSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("exited"), code: z.number().int().min(0).max(255) }),
+  z.strictObject({ kind: z.literal("signaled"), signal: z.string().regex(/^SIG[A-Z0-9]+$/u).max(64) }),
+  z.strictObject({ kind: z.literal("unavailable"), reason: z.literal("sandbox_stopped") })
+]);
+function parseSandboxProcessSpec(input) {
+  return parseData(processSchema, input);
+}
+function parseSandboxProcessExit(input) {
+  return parseData(exitSchema, input);
+}
+export {
+  parseSandboxProcessExit,
+  parseSandboxProcessSpec
+};

package/dist/process/streams.d.ts

@@ -0,0 +1,9 @@
+import type { SandboxStreamLimits } from '../policy/types.js';
+import type { SandboxProcessStreams } from './types.js';
+export interface OwnedProcessStreams {
+    readonly streams: SandboxProcessStreams;
+    readonly settled: Promise<void>;
+    close(error?: Error): void;
+}
+export declare function ownProcessStreams(raw: SandboxProcessStreams, limits: SandboxStreamLimits, onFailure: (error: Error) => void): OwnedProcessStreams;
+//# sourceMappingURL=streams.d.ts.map

package/dist/process/streams.js

@@ -0,0 +1,61 @@
+import { Readable, Writable } from "node:stream";
+import { SandboxOperationError } from "../errors.js";
+import { parseSandboxProcessExit } from "./parse.js";
+import { SandboxInput } from "./input.js";
+import { SandboxOutput } from "./output.js";
+function ownProcessStreams(raw, limits, onFailure) {
+  if (!(raw.stdin instanceof Writable) || !(raw.stdout instanceof Readable) || !(raw.stderr instanceof Readable) || raw.stdin.writableObjectMode || raw.stdout.readableObjectMode || raw.stderr.readableObjectMode || raw.stdout.readableEncoding !== null || raw.stderr.readableEncoding !== null) {
+    throw new SandboxOperationError("stream_failure", "The backend must supply distinct binary Node stdin, stdout and stderr streams.");
+  }
+  if (Object.is(raw.stdout, raw.stderr) || Object.is(raw.stdin, raw.stdout) || Object.is(raw.stdin, raw.stderr)) {
+    throw new SandboxOperationError("stream_failure", "Sandbox standard streams must remain separate.");
+  }
+  let outputBytes = 0n;
+  let closed = false;
+  let failure;
+  const fail = (error) => {
+    if (closed || failure) return;
+    failure = error;
+    close(error);
+    onFailure(error);
+  };
+  const stdin = new SandboxInput(raw.stdin, limits.maxStdinBytes, limits.maxBufferedInputBytes, limits.highWaterMarkBytes, fail);
+  const stdout = new SandboxOutput(limits.highWaterMarkBytes, fail);
+  const stderr = new SandboxOutput(limits.highWaterMarkBytes, fail);
+  const close = (error) => {
+    if (closed) return;
+    closed = true;
+    stdin.close(error);
+    stdout.close(error);
+    stderr.close(error);
+    raw.stdout.destroy(error);
+    raw.stderr.destroy(error);
+  };
+  const pump = async (source, target) => {
+    try {
+      for await (const chunk of source) {
+        if (closed) return;
+        if (!(chunk instanceof Uint8Array)) throw new SandboxOperationError("stream_failure", "Backend output contained a non-binary chunk.");
+        if (limits.maxOutputBytes !== void 0 && outputBytes + BigInt(chunk.byteLength) > BigInt(limits.maxOutputBytes)) {
+          throw new SandboxOperationError("output_limit", "Sandbox output exceeded its caller-selected combined lifetime byte limit.");
+        }
+        if (chunk.byteLength + stdout.readableLength + stderr.readableLength > limits.maxBufferedOutputBytes) {
+          throw new SandboxOperationError("output_limit", "Sandbox output exceeded its aggregate buffered byte limit.");
+        }
+        outputBytes += BigInt(chunk.byteLength);
+        await target.deliver(chunk);
+      }
+      if (!closed) target.finish();
+    } catch (error) {
+      if (!closed) fail(error instanceof Error ? error : new SandboxOperationError("stream_failure", "Sandbox output failed.", { cause: error }));
+    }
+  };
+  const pumps = Promise.all([pump(raw.stdout, stdout), pump(raw.stderr, stderr)]).then(() => void 0);
+  const exit = Promise.resolve(raw.exit).then(parseSandboxProcessExit);
+  void exit.catch((error) => fail(error instanceof Error ? error : new SandboxOperationError("driver_failure", "Sandbox leader exit failed.", { cause: error })));
+  const settled = Promise.all([pumps, stdin.settled, exit.then(() => void 0, () => void 0)]).then(() => void 0);
+  return Object.freeze({ streams: Object.freeze({ stdin, stdout, stderr, exit }), settled, close });
+}
+export {
+  ownProcessStreams
+};

package/dist/process/types.d.ts

@@ -0,0 +1,38 @@
+import type { Readable, Writable } from 'node:stream';
+import type { OperationOptions } from '../contracts.js';
+import type { SandboxGuestPath } from '../files/types.js';
+import type { SandboxProcessId } from '../policy/types.js';
+export interface SandboxProcessInput {
+    readonly executable: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+    readonly cwd: string;
+}
+export interface SandboxProcessSpec extends Omit<SandboxProcessInput, 'executable' | 'cwd'> {
+    readonly executable: SandboxGuestPath;
+    readonly cwd: SandboxGuestPath;
+}
+export type SandboxProcessExit = Readonly<{
+    kind: 'exited';
+    code: number;
+}> | Readonly<{
+    kind: 'signaled';
+    signal: string;
+}> | Readonly<{
+    kind: 'unavailable';
+    reason: 'sandbox_stopped';
+}>;
+export interface SandboxProcessStreams {
+    readonly stdin: Writable;
+    readonly stdout: Readable;
+    readonly stderr: Readable;
+    /** The leader's exit observation does not establish descendant quiescence. */
+    readonly exit: Promise<SandboxProcessExit>;
+}
+export interface SandboxProcessReservation {
+    readonly id: SandboxProcessId;
+    readonly stopScope: 'sandbox';
+    start(options?: OperationOptions): Promise<SandboxProcessStreams>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/recovery/parse.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxRecoveryPolicy, SandboxRecoveryRecord } from './types.js';
+export declare function parseSandboxRecoveryRecord(input: unknown): SandboxRecoveryRecord;
+export declare function parseSandboxRecoveryPolicy(input: unknown): SandboxRecoveryPolicy;
+//# sourceMappingURL=parse.d.ts.map

package/dist/recovery/parse.js

@@ -0,0 +1,67 @@
+import { Buffer } from "node:buffer";
+import { z } from "zod/v4";
+import { SandboxValidationError } from "../errors.js";
+import { captureData, invalidInput } from "../internal/data.js";
+import { parseData } from "../internal/parse.js";
+import { SANDBOX_LIMITS } from "../policy/limits.js";
+import { identitySchema, namespaceSchema, sandboxIdSchema } from "../policy/schemas.js";
+const digestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
+const resourceSchema = z.strictObject({
+  role: z.enum(["compute", "storage", "export", "network"]),
+  name: identitySchema,
+  identity: z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("planned") }),
+    z.strictObject({ kind: z.literal("creating") }),
+    z.strictObject({ kind: z.literal("identified"), id: identitySchema, fingerprint: digestSchema })
+  ])
+});
+const recoverySchema = z.strictObject({
+  format: z.literal("agenai.sandbox-recovery.v2"),
+  backendId: identitySchema,
+  backendRevision: identitySchema,
+  namespace: namespaceSchema,
+  operationId: identitySchema,
+  sandboxId: sandboxIdSchema,
+  imageDigest: digestSchema,
+  policyDigest: digestSchema,
+  configurationDigest: digestSchema,
+  phase: z.enum(["reserved", "starting", "running", "stopping", "stopped", "destroying", "destroyed", "uncertain"]),
+  authority: z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("unverified") }),
+    z.strictObject({ kind: z.literal("verified"), backendIdentity: identitySchema })
+  ]),
+  resources: z.array(resourceSchema).min(1).max(4)
+}).superRefine((record, context) => {
+  if (new Set(record.resources.map((resource) => resource.role)).size !== record.resources.length) context.addIssue({ code: "custom", path: ["resources"], message: "Recovery resource roles must be unique" });
+  if (new Set(record.resources.map((resource) => resource.name)).size !== record.resources.length) context.addIssue({ code: "custom", path: ["resources"], message: "Recovery resource names must be unique" });
+  if (record.authority.kind === "unverified" && (record.phase !== "reserved" || record.resources.some((resource) => resource.identity.kind !== "planned"))) {
+    context.addIssue({ code: "custom", path: ["authority"], message: "Entered resource operations require verified backend authority" });
+  }
+});
+function parseSandboxRecoveryRecord(input) {
+  const captured = captureData(input);
+  const serialized = JSON.stringify(captured);
+  if (serialized === void 0 || Buffer.byteLength(serialized, "utf8") > SANDBOX_LIMITS.maxRecoveryBytes) invalidInput("Recovery record exceeds its serialized UTF-8 bound");
+  return parseData(recoverySchema, captured);
+}
+function parseSandboxRecoveryPolicy(input) {
+  if (input === null || typeof input !== "object" || Object.getPrototypeOf(input) !== Object.prototype && Object.getPrototypeOf(input) !== null) invalidInput("Recovery policy must be a plain object");
+  const keys = Reflect.ownKeys(input);
+  const kind = Object.getOwnPropertyDescriptor(input, "kind");
+  if (kind === void 0 || !("value" in kind)) invalidInput("Recovery policy requires a data kind");
+  if (kind.value === "in_process" && keys.length === 1) return Object.freeze({ kind: "in_process" });
+  const persist = Object.getOwnPropertyDescriptor(input, "persist");
+  if (kind.value !== "persisted" || keys.length !== 2 || persist === void 0 || !("value" in persist) || typeof persist.value !== "function") invalidInput("Persisted recovery requires only a persist function");
+  const callback = persist.value;
+  return Object.freeze({ kind: "persisted", async persist(record) {
+    const result = callback(record);
+    if (result === null || typeof result !== "object" || !("then" in result) || typeof result.then !== "function") {
+      throw new SandboxValidationError([{ code: "invalid_input", path: ["persist"], message: "Recovery persistence must return a promise" }]);
+    }
+    await result;
+  } });
+}
+export {
+  parseSandboxRecoveryPolicy,
+  parseSandboxRecoveryRecord
+};

package/dist/recovery/types.d.ts

@@ -0,0 +1,59 @@
+import type { SandboxId, SandboxNamespace } from '../policy/types.js';
+export type SandboxRecoveryPhase = 'reserved' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'uncertain';
+export type SandboxResourceIdentity = Readonly<{
+    kind: 'planned';
+}> | Readonly<{
+    kind: 'creating';
+}> | Readonly<{
+    kind: 'identified';
+    id: string;
+    fingerprint: string;
+}>;
+export interface SandboxRecoveryResource {
+    readonly role: 'compute' | 'storage' | 'export' | 'network';
+    readonly name: string;
+    readonly identity: SandboxResourceIdentity;
+}
+export type SandboxRecoveryAuthority = Readonly<{
+    kind: 'unverified';
+}> | Readonly<{
+    kind: 'verified';
+    backendIdentity: string;
+}>;
+export interface SandboxRecoveryRecord {
+    readonly format: 'agenai.sandbox-recovery.v2';
+    readonly backendId: string;
+    readonly backendRevision: string;
+    readonly namespace: SandboxNamespace;
+    readonly operationId: string;
+    readonly sandboxId: SandboxId;
+    readonly imageDigest: string;
+    readonly policyDigest: string;
+    /** Exact backend configuration identity, independent of the requested policy digest. */
+    readonly configurationDigest: string;
+    readonly phase: SandboxRecoveryPhase;
+    readonly authority: SandboxRecoveryAuthority;
+    readonly resources: readonly SandboxRecoveryResource[];
+}
+export type SandboxRecoveryPolicy = Readonly<{
+    kind: 'in_process';
+}> | Readonly<{
+    kind: 'persisted';
+    persist(record: SandboxRecoveryRecord): Promise<void>;
+}>;
+export interface SandboxCleanupOwner {
+    readonly recoveryRecord: SandboxRecoveryRecord;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
+}
+export type SandboxReconciliation = Readonly<{
+    kind: 'matched' | 'uncertain';
+    owner: SandboxCleanupOwner;
+}> | Readonly<{
+    kind: 'conflict';
+    reason: string;
+}> | Readonly<{
+    kind: 'absent';
+    record: SandboxRecoveryRecord;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/withSandbox.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxBackend, SandboxRunOptions, Sandbox } from './contracts.js';
+import type { SandboxRequestInput } from './policy/types.js';
+export declare function withSandbox<T>(backend: SandboxBackend, request: SandboxRequestInput, use: (sandbox: Sandbox) => Promise<T>, options: SandboxRunOptions): Promise<T>;
+//# sourceMappingURL=withSandbox.d.ts.map