@tanstack/ai-sandbox 0.3.4 → 0.5.0

package/dist/esm/snapshot-tools.js

@@ -0,0 +1,160 @@
+import { SandboxSnapshotError } from "./snapshots.js";
+import { toolDefinition } from "@tanstack/ai";
+//#region src/snapshot-tools.ts
+function field(value, key) {
+	if (value === null || typeof value !== "object") return void 0;
+	return Reflect.get(value, key);
+}
+function requiredString(value, key) {
+	const candidate = field(value, key);
+	if (typeof candidate !== "string" || candidate.length === 0) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_TOOL_INPUT", `Snapshot tool requires a non-empty ${key}`);
+	return candidate;
+}
+function optionalString(value, key) {
+	const candidate = field(value, key);
+	if (candidate === void 0) return void 0;
+	if (typeof candidate !== "string" || candidate.length === 0) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_TOOL_INPUT", `Snapshot tool ${key} must be a non-empty string when provided`);
+	return candidate;
+}
+function requireIdentifier(value, label) {
+	if (value.length === 0) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_TOOL_INPUT", `${label} must be a non-empty string`);
+	return value;
+}
+function createSnapshotTools(snapshots, options) {
+	const threadId = requireIdentifier(options.threadId, "threadId");
+	const runId = requireIdentifier(options.runId, "runId");
+	const createThreadId = options.createThreadId;
+	const tenant = options.tenant;
+	const onForked = options.onForked;
+	if (typeof createThreadId !== "function") throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_TOOL_INPUT", "createSnapshotTools requires createThreadId");
+	return [
+		toolDefinition({
+			name: "save_sandbox_snapshot",
+			description: "Save a named checkpoint of the current live sandbox for this thread. Do not pass a thread id.",
+			inputSchema: {
+				type: "object",
+				properties: { label: {
+					type: "string",
+					description: "A short name for this version, such as release-1."
+				} },
+				required: ["label"],
+				additionalProperties: false
+			},
+			outputSchema: {
+				type: "object",
+				properties: {
+					checkpointId: { type: "string" },
+					label: { type: "string" },
+					threadId: { type: "string" }
+				},
+				required: [
+					"checkpointId",
+					"label",
+					"threadId"
+				],
+				additionalProperties: false
+			}
+		}).server(async (input) => {
+			const label = requiredString(input, "label");
+			const checkpoint = await snapshots.save({
+				threadId,
+				runId,
+				label,
+				...tenant === void 0 ? {} : { tenant }
+			});
+			return {
+				checkpointId: checkpoint.id,
+				label: checkpoint.label ?? label,
+				threadId
+			};
+		}),
+		toolDefinition({
+			name: "fork_sandbox_snapshot",
+			description: "Copy one checkpoint from this thread into a new empty thread. Omit checkpointId to copy the latest checkpoint. Do not pass thread ids.",
+			inputSchema: {
+				type: "object",
+				properties: { checkpointId: {
+					type: "string",
+					description: "The checkpoint to copy. When omitted, the latest checkpoint is copied."
+				} },
+				additionalProperties: false
+			},
+			outputSchema: {
+				type: "object",
+				properties: {
+					checkpointId: { type: "string" },
+					destinationThreadId: { type: "string" }
+				},
+				required: ["checkpointId", "destinationThreadId"],
+				additionalProperties: false
+			}
+		}).server(async (input) => {
+			const checkpointId = optionalString(input, "checkpointId") ?? await snapshots.checkpoints.getHead(threadId);
+			if (checkpointId === null) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_MISSING_CHECKPOINT", "This thread has no checkpoint to fork");
+			const destinationThreadId = requireIdentifier(createThreadId(), "destinationThreadId");
+			const checkpoint = await snapshots.fork({
+				threadId,
+				checkpointId,
+				destinationThreadId
+			});
+			if (onForked !== void 0) await onForked({
+				destinationThreadId,
+				checkpointId: checkpoint.id
+			});
+			return {
+				checkpointId: checkpoint.id,
+				destinationThreadId
+			};
+		}),
+		toolDefinition({
+			name: "read_sandbox_snapshot_artifact",
+			description: "Read metadata for one artifact on a checkpoint in this thread. Do not pass a thread id.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					checkpointId: { type: "string" },
+					artifactId: { type: "string" }
+				},
+				required: ["checkpointId", "artifactId"],
+				additionalProperties: false
+			},
+			outputSchema: {
+				type: "object",
+				properties: {
+					artifactId: { type: "string" },
+					name: { type: "string" },
+					mimeType: { type: "string" },
+					size: { type: "number" },
+					createdAt: { type: "number" }
+				},
+				required: [
+					"artifactId",
+					"name",
+					"mimeType",
+					"size",
+					"createdAt"
+				],
+				additionalProperties: false
+			}
+		}).server(async (input) => {
+			const checkpointId = requiredString(input, "checkpointId");
+			const artifactId = requiredString(input, "artifactId");
+			const resolved = await snapshots.readArtifact({
+				threadId,
+				checkpointId,
+				artifactId
+			});
+			return {
+				artifactId: resolved.artifact.artifactId,
+				name: resolved.artifact.name,
+				mimeType: resolved.artifact.mimeType,
+				size: resolved.artifact.size,
+				createdAt: resolved.artifact.createdAt
+			};
+		})
+	];
+}
+//#endregion
+export { createSnapshotTools };
+
+//# sourceMappingURL=snapshot-tools.js.map

package/dist/esm/snapshot-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-tools.js","names":[],"sources":["../../src/snapshot-tools.ts"],"sourcesContent":["import { toolDefinition } from '@tanstack/ai'\nimport { SandboxSnapshotError } from './snapshots'\nimport type { SandboxSnapshots } from './snapshot-operations'\n\nexport interface CreateSnapshotToolsOptions {\n  threadId: string\n  runId: string\n  createThreadId: () => string\n  tenant?: { userId?: string; orgId?: string }\n  onForked?: (input: {\n    destinationThreadId: string\n    checkpointId: string\n  }) => void | Promise<void>\n}\n\nfunction field(value: unknown, key: string): unknown {\n  if (value === null || typeof value !== 'object') return undefined\n  return Reflect.get(value, key)\n}\n\nfunction requiredString(value: unknown, key: string): string {\n  const candidate = field(value, key)\n  if (typeof candidate !== 'string' || candidate.length === 0) {\n    throw new SandboxSnapshotError(\n      'SANDBOX_SNAPSHOT_INVALID_TOOL_INPUT',\n      `Snapshot tool requires a non-empty ${key}`,\n    )\n  }\n  return candidate\n}\n\nfunction optionalString(value: unknown, key: string): string | undefined {\n  const candidate = field(value, key)\n  if (candidate === undefined) return undefined\n  if (typeof candidate !== 'string' || candidate.length === 0) {\n    throw new SandboxSnapshotError(\n      'SANDBOX_SNAPSHOT_INVALID_TOOL_INPUT',\n      `Snapshot tool ${key} must be a non-empty string when provided`,\n    )\n  }\n  return candidate\n}\n\nfunction requireIdentifier(value: string, label: string): string {\n  if (value.length === 0) {\n    throw new SandboxSnapshotError(\n      'SANDBOX_SNAPSHOT_INVALID_TOOL_INPUT',\n      `${label} must be a non-empty string`,\n    )\n  }\n  return value\n}\n\nexport function createSnapshotTools(\n  snapshots: SandboxSnapshots,\n  options: CreateSnapshotToolsOptions,\n) {\n  const threadId = requireIdentifier(options.threadId, 'threadId')\n  const runId = requireIdentifier(options.runId, 'runId')\n  const createThreadId = options.createThreadId\n  const tenant = options.tenant\n  const onForked = options.onForked\n  if (typeof createThreadId !== 'function') {\n    throw new SandboxSnapshotError(\n      'SANDBOX_SNAPSHOT_INVALID_TOOL_INPUT',\n      'createSnapshotTools requires createThreadId',\n    )\n  }\n\n  const save = toolDefinition({\n    name: 'save_sandbox_snapshot',\n    description:\n      'Save a named checkpoint of the current live sandbox for this thread. Do not pass a thread id.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        label: {\n          type: 'string',\n          description: 'A short name for this version, such as release-1.',\n        },\n      },\n      required: ['label'],\n      additionalProperties: false,\n    },\n    outputSchema: {\n      type: 'object',\n      properties: {\n        checkpointId: { type: 'string' },\n        label: { type: 'string' },\n        threadId: { type: 'string' },\n      },\n      required: ['checkpointId', 'label', 'threadId'],\n      additionalProperties: false,\n    },\n  }).server(async (input) => {\n    const label = requiredString(input, 'label')\n    const checkpoint = await snapshots.save({\n      threadId,\n      runId,\n      label,\n      ...(tenant === undefined ? {} : { tenant }),\n    })\n    return {\n      checkpointId: checkpoint.id,\n      label: checkpoint.label ?? label,\n      threadId,\n    }\n  })\n\n  const fork = toolDefinition({\n    name: 'fork_sandbox_snapshot',\n    description:\n      'Copy one checkpoint from this thread into a new empty thread. Omit checkpointId to copy the latest checkpoint. Do not pass thread ids.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        checkpointId: {\n          type: 'string',\n          description:\n            'The checkpoint to copy. When omitted, the latest checkpoint is copied.',\n        },\n      },\n      additionalProperties: false,\n    },\n    outputSchema: {\n      type: 'object',\n      properties: {\n        checkpointId: { type: 'string' },\n        destinationThreadId: { type: 'string' },\n      },\n      required: ['checkpointId', 'destinationThreadId'],\n      additionalProperties: false,\n    },\n  }).server(async (input) => {\n    const suppliedCheckpointId = optionalString(input, 'checkpointId')\n    const checkpointId =\n      suppliedCheckpointId ?? (await snapshots.checkpoints.getHead(threadId))\n    if (checkpointId === null) {\n      throw new SandboxSnapshotError(\n        'SANDBOX_SNAPSHOT_MISSING_CHECKPOINT',\n        'This thread has no checkpoint to fork',\n      )\n    }\n    const destinationThreadId = requireIdentifier(\n      createThreadId(),\n      'destinationThreadId',\n    )\n    const checkpoint = await snapshots.fork({\n      threadId,\n      checkpointId,\n      destinationThreadId,\n    })\n    if (onForked !== undefined) {\n      await onForked({\n        destinationThreadId,\n        checkpointId: checkpoint.id,\n      })\n    }\n    return {\n      checkpointId: checkpoint.id,\n      destinationThreadId,\n    }\n  })\n\n  const readArtifact = toolDefinition({\n    name: 'read_sandbox_snapshot_artifact',\n    description:\n      'Read metadata for one artifact on a checkpoint in this thread. Do not pass a thread id.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        checkpointId: { type: 'string' },\n        artifactId: { type: 'string' },\n      },\n      required: ['checkpointId', 'artifactId'],\n      additionalProperties: false,\n    },\n    outputSchema: {\n      type: 'object',\n      properties: {\n        artifactId: { type: 'string' },\n        name: { type: 'string' },\n        mimeType: { type: 'string' },\n        size: { type: 'number' },\n        createdAt: { type: 'number' },\n      },\n      required: ['artifactId', 'name', 'mimeType', 'size', 'createdAt'],\n      additionalProperties: false,\n    },\n  }).server(async (input) => {\n    const checkpointId = requiredString(input, 'checkpointId')\n    const artifactId = requiredString(input, 'artifactId')\n    const resolved = await snapshots.readArtifact({\n      threadId,\n      checkpointId,\n      artifactId,\n    })\n    return {\n      artifactId: resolved.artifact.artifactId,\n      name: resolved.artifact.name,\n      mimeType: resolved.artifact.mimeType,\n      size: resolved.artifact.size,\n      createdAt: resolved.artifact.createdAt,\n    }\n  })\n\n  return [save, fork, readArtifact] as const\n}\n"],"mappings":"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"}

package/dist/esm/snapshots.d.ts

@@ -0,0 +1,51 @@
+import { SandboxHandle } from './contracts.js';
+import { SandboxSnapshotArtifact, SandboxSnapshotEntry } from './checkpoint-store.js';
+import { MemoryArtifactRecord as ArtifactRecord } from './memory-snapshot-types.js';
+type SnapshotBlobStore = {
+    get: (key: string) => Promise<{
+        arrayBuffer: () => Promise<ArrayBuffer>;
+    } | null>;
+    head: (key: string) => Promise<unknown>;
+    put: (key: string, body: Uint8Array) => Promise<unknown>;
+};
+export interface SandboxSnapshotPolicy {
+    /** Exact workspace projection hash, when known. */
+    workspaceHash?: string;
+    include?: (path: string, kind: 'file' | 'dir') => boolean;
+    exclude?: (path: string, kind: 'file' | 'dir') => boolean;
+    redact?: (input: {
+        path: string;
+        bytes: Uint8Array;
+        resolvedSecrets: Readonly<Record<string, string>>;
+    }) => Uint8Array;
+}
+export interface SandboxSnapshotBundle {
+    blobs: SnapshotBlobStore;
+    /** Internal resolved workspace root. */
+    workspaceRoot?: string;
+    /** Internal persistence stores used to capture immutable artifact bytes. */
+    artifacts?: {
+        listForThread: (threadId: string) => Promise<ReadonlyArray<ArtifactRecord>>;
+    };
+    resolveArtifactBlobKey?: (record: ArtifactRecord) => string;
+}
+export type SandboxSnapshotErrorCode = 'SANDBOX_SNAPSHOT_INVALID_TOOL_INPUT' | 'SANDBOX_SNAPSHOT_MISSING_SANDBOX' | 'SANDBOX_SNAPSHOT_MISSING_INSTANCES' | 'SANDBOX_SNAPSHOT_MISSING_PERSISTENCE_STORES' | 'SANDBOX_SNAPSHOT_MISSING_REUSABLE_SANDBOX' | 'SANDBOX_SNAPSHOT_REUSE_NONE' | 'SANDBOX_SNAPSHOT_MISSING_CHECKPOINT' | 'SANDBOX_SNAPSHOT_MISSING_CHECKPOINT_ARTIFACT' | 'SANDBOX_SNAPSHOT_FOREIGN_CHECKPOINT_ARTIFACT' | 'SANDBOX_SNAPSHOT_INVALID_ARTIFACT_BYTES' | 'SANDBOX_SNAPSHOT_FORK_UNAVAILABLE' | 'SANDBOX_SNAPSHOT_INVALID_PATH' | 'SANDBOX_SNAPSHOT_INVALID_WORKSPACE' | 'SANDBOX_SNAPSHOT_LSTAT_REQUIRED' | 'SANDBOX_SNAPSHOT_UNSUPPORTED_ENTRY' | 'SANDBOX_SNAPSHOT_MISSING_BLOB' | 'SANDBOX_SNAPSHOT_INVALID_BLOB' | 'SANDBOX_SNAPSHOT_ARTIFACT_SUPPORT_REQUIRED' | 'SANDBOX_SNAPSHOT_MISSING_ARTIFACT_BLOB';
+export declare class SandboxSnapshotError extends Error {
+    readonly code: SandboxSnapshotErrorCode;
+    constructor(code: SandboxSnapshotErrorCode, message: string);
+}
+export declare function defaultSandboxSnapshotPolicy(workspaceHash?: string): SandboxSnapshotPolicy;
+/**
+ * Keep default exclusions unless the caller passed `exclude`.
+ * `include` or `redact` alone must not capture `.env`, `.git`, or
+ * `node_modules`.
+ */
+export declare function resolveSandboxSnapshotPolicy(supplied: SandboxSnapshotPolicy | undefined, workspaceHash?: string): SandboxSnapshotPolicy;
+export declare function captureSandboxFiles(handle: SandboxHandle, bundle: SandboxSnapshotBundle, suppliedPolicy?: SandboxSnapshotPolicy, resolvedSecrets?: Readonly<Record<string, string>>): Promise<{
+    files: Array<SandboxSnapshotEntry>;
+}>;
+export declare function restoreSandboxFiles(handle: SandboxHandle, bundle: SandboxSnapshotBundle, snapshot: {
+    files: ReadonlyArray<SandboxSnapshotEntry>;
+}, suppliedPolicy?: SandboxSnapshotPolicy): Promise<void>;
+export declare function captureSandboxArtifacts(bundle: SandboxSnapshotBundle, threadId: string, resolvedSecrets?: Readonly<Record<string, string>>): Promise<ReadonlyArray<SandboxSnapshotArtifact>>;
+export {};

package/dist/esm/snapshots.js

@@ -0,0 +1,350 @@
+//#region src/snapshots.ts
+var SandboxSnapshotError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "SandboxSnapshotError";
+		this.code = code;
+	}
+};
+var DEFAULT_ROOT = "/workspace";
+var PROJECTED_SKILL_ROOTS = /* @__PURE__ */ new Set([
+	".claude",
+	".codex",
+	".grok"
+]);
+function isFrameworkGeneratedSymlinkPath(path) {
+	if (path === "CLAUDE.md" || path === "GEMINI.md") return true;
+	const segments = path.split("/");
+	return segments.length === 3 && PROJECTED_SKILL_ROOTS.has(segments[0] ?? "") && segments[1] === "skills";
+}
+function defaultExcluded(path, workspaceHash) {
+	const segments = path.split("/");
+	return isFrameworkGeneratedSymlinkPath(path) || segments.some((segment) => segment === ".git" || segment === "node_modules" || segment.startsWith(".env")) || workspaceHash !== void 0 && segments[0] === `.tanstack-projected-${workspaceHash}`;
+}
+function isProtectedPath(path, workspaceHash) {
+	return workspaceHash !== void 0 && path.split("/")[0] === `.tanstack-projected-${workspaceHash}`;
+}
+var FILE_BLOB_KEY = /^sandbox-files\/sha256\/[0-9a-f]{64}$/;
+function defaultSandboxSnapshotPolicy(workspaceHash) {
+	return {
+		workspaceHash,
+		exclude: (path) => defaultExcluded(path, workspaceHash)
+	};
+}
+/**
+* Keep default exclusions unless the caller passed `exclude`.
+* `include` or `redact` alone must not capture `.env`, `.git`, or
+* `node_modules`.
+*/
+function resolveSandboxSnapshotPolicy(supplied, workspaceHash) {
+	const defaults = defaultSandboxSnapshotPolicy(workspaceHash ?? supplied?.workspaceHash);
+	if (supplied === void 0) return defaults;
+	const include = supplied.include;
+	const exclude = supplied.exclude;
+	const redact = supplied.redact;
+	const suppliedWorkspaceHash = supplied.workspaceHash;
+	return {
+		...suppliedWorkspaceHash === void 0 ? {} : { workspaceHash: suppliedWorkspaceHash },
+		...workspaceHash === void 0 ? {} : { workspaceHash },
+		...include === void 0 ? {} : { include },
+		exclude: exclude ?? defaults.exclude,
+		...redact === void 0 ? {} : { redact }
+	};
+}
+function normalize(path) {
+	if (path.includes("\\")) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_PATH", `Unsafe snapshot path '${path}'`);
+	const value = path;
+	if (!value || value.includes("\0") || value.startsWith("/") || /^[A-Za-z]:/.test(value) || value.endsWith("/")) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_PATH", `Unsafe snapshot path '${path}'`);
+	const parts = value.split("/");
+	if (parts.some((part) => !part || part === "." || part === "..") || parts.join("/") !== value) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_PATH", `Unsafe snapshot path '${path}'`);
+	return value;
+}
+function childPath(parent, child) {
+	if (!child.name || child.name.includes("/") || child.name.includes("\\") || child.name.includes("\0") || child.name === "." || child.name === "..") throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_WORKSPACE", `Invalid workspace entry '${child.name}'`);
+	const absolute = `${parent}/${child.name}`;
+	if (child.path !== absolute) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_WORKSPACE", `Invalid workspace entry path '${child.path}'`);
+	return {
+		absolute,
+		relative: child.name
+	};
+}
+function lstat(handle, path) {
+	if (!handle.fs.lstat) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_LSTAT_REQUIRED", "Snapshot operations require fs.lstat");
+	return handle.fs.lstat(path);
+}
+function assertSupported(stat, path) {
+	if (stat.type === "symlink" || stat.type === "other" || stat.type === "file" && (stat.mode & 73) !== 0) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_UNSUPPORTED_ENTRY", `Unsupported entry '${path}'`);
+}
+function included(path, kind, policy) {
+	if (policy.exclude?.(path, kind)) return false;
+	return kind === "dir" ? true : policy.include?.(path, kind) ?? true;
+}
+async function hash(bytes) {
+	const digest = await crypto.subtle.digest("SHA-256", new Uint8Array(bytes));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function putIfAbsent(blobs, bytes, keys) {
+	const key = `sandbox-files/sha256/${await hash(bytes)}`;
+	if (!keys.has(key)) {
+		if (!await blobs.head(key)) await blobs.put(key, bytes);
+		keys.set(key, key);
+	}
+	return {
+		key,
+		size: bytes.byteLength
+	};
+}
+async function redactBytes(bytes, resolvedSecrets) {
+	const output = bytes.slice();
+	const redacted = new Uint8Array(bytes.length);
+	const secrets = Object.values(resolvedSecrets).filter(Boolean).map((secret) => new TextEncoder().encode(secret)).sort((a, b) => b.length - a.length || compareBytes(a, b));
+	for (const needle of secrets) {
+		if (!needle.length || needle.length > bytes.length) continue;
+		for (let start = 0; start <= bytes.length - needle.length; start++) {
+			let match = true;
+			for (let index = 0; index < needle.length; index++) if (bytes[start + index] !== needle[index]) {
+				match = false;
+				break;
+			}
+			if (!match) continue;
+			if (match) redacted.fill(1, start, start + needle.length);
+		}
+	}
+	for (let index = 0; index < output.length; index++) if (redacted[index]) output[index] = 0;
+	return output;
+}
+async function captureSandboxFiles(handle, bundle, suppliedPolicy = defaultSandboxSnapshotPolicy(), resolvedSecrets = {}) {
+	const policy = resolveSandboxSnapshotPolicy(suppliedPolicy, suppliedPolicy.workspaceHash);
+	if (!handle.fs.lstat) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_LSTAT_REQUIRED", "Snapshot capture requires fs.lstat");
+	const rootPath = bundle.workspaceRoot ?? DEFAULT_ROOT;
+	const root = await lstat(handle, rootPath);
+	if (!root || root.type !== "dir") throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_WORKSPACE", "Snapshot workspace is missing or is not a directory");
+	assertSupported(root, rootPath);
+	const files = [];
+	const destinationKeys = /* @__PURE__ */ new Map();
+	const walk = async (absolute, relative) => {
+		const stat = await lstat(handle, absolute);
+		if (!stat) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_WORKSPACE", `Snapshot entry disappeared '${relative}'`);
+		assertSupported(stat, relative);
+		if (stat.type !== "file" && stat.type !== "dir") throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_UNSUPPORTED_ENTRY", `Unsupported entry '${relative}'`);
+		if (relative && (isProtectedPath(relative, policy.workspaceHash) || policy.exclude?.(relative, stat.type))) return false;
+		if (stat.type === "file") {
+			const path = normalize(relative);
+			if (policy.include && !policy.include(path, "file")) return false;
+			let bytes = await handle.fs.readBytes(absolute);
+			if (policy.redact) bytes = policy.redact({
+				path,
+				bytes,
+				resolvedSecrets
+			});
+			bytes = await redactBytes(bytes, resolvedSecrets);
+			const blob = await putIfAbsent(bundle.blobs, bytes, destinationKeys);
+			files.push({
+				path,
+				kind: "file",
+				blobKey: blob.key,
+				size: blob.size
+			});
+			return true;
+		}
+		const children = await handle.fs.list(absolute);
+		let hasCapturedChild = false;
+		for (const child of children) {
+			const childEntry = childPath(absolute, child);
+			const childRelative = relative ? `${relative}/${childEntry.relative}` : childEntry.relative;
+			if (isProtectedPath(childRelative, policy.workspaceHash) || policy.exclude?.(childRelative, child.type)) continue;
+			hasCapturedChild = await walk(childEntry.absolute, childRelative) || hasCapturedChild;
+		}
+		if (relative && !hasCapturedChild && (!policy.include || policy.include(relative, "dir"))) files.push({
+			path: normalize(relative),
+			kind: "dir"
+		});
+		return hasCapturedChild || relative !== "" && (!policy.include || policy.include(relative, "dir"));
+	};
+	await walk(rootPath, "");
+	files.sort((a, b) => comparePath(a.path, b.path));
+	return { files };
+}
+function validateManifest(snapshot, policy) {
+	const paths = /* @__PURE__ */ new Map();
+	for (const entry of snapshot.files) {
+		const path = normalize(entry.path);
+		for (const ancestor of parents(path)) if (isProtectedPath(ancestor, policy.workspaceHash) || policy.exclude?.(ancestor, "dir")) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_PATH", `Excluded snapshot ancestor '${ancestor}'`);
+		if (isProtectedPath(path, policy.workspaceHash)) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_PATH", `Protected snapshot path '${path}'`);
+		if (!included(path, entry.kind, policy) || entry.kind === "dir" && policy.include?.(path, "dir") === false) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_PATH", `Excluded snapshot path '${path}'`);
+		if (paths.has(path)) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_PATH", `Duplicate path '${path}'`);
+		if (entry.kind === "file") {
+			const { blobKey, size } = entry;
+			if (typeof blobKey !== "string" || !FILE_BLOB_KEY.test(blobKey) || typeof size !== "number" || !Number.isSafeInteger(size) || size < 0) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_PATH", `Invalid file entry '${path}'`);
+			paths.set(path, {
+				path,
+				kind: "file",
+				blobKey,
+				size
+			});
+		} else if (entry.kind === "dir") paths.set(path, {
+			path,
+			kind: "dir"
+		});
+		else throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_PATH", `Unknown snapshot entry '${path}'`);
+	}
+	for (const [path] of paths) for (let index = path.indexOf("/"); index !== -1; index = path.indexOf("/", index + 1)) {
+		const parent = paths.get(path.slice(0, index));
+		if (parent?.kind === "file") throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_PATH", `File ancestor '${parent.path}'`);
+	}
+	return [...paths.values()];
+}
+async function loadBlobs(entries, bundle) {
+	const blobs = /* @__PURE__ */ new Map();
+	for (const entry of entries) if (entry.kind === "file" && !blobs.has(entry.blobKey)) {
+		const object = await bundle.blobs.get(entry.blobKey);
+		if (!object) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_MISSING_BLOB", `Missing snapshot blob '${entry.blobKey}'`);
+		const bytes = new Uint8Array(await object.arrayBuffer());
+		const expectedKey = `sandbox-files/sha256/${await hash(bytes)}`;
+		if (entry.blobKey !== expectedKey) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_BLOB", `Invalid content for snapshot blob '${entry.blobKey}'`);
+		blobs.set(entry.blobKey, bytes);
+	}
+	for (const entry of entries) if (entry.kind === "file") {
+		const bytes = blobs.get(entry.blobKey);
+		if (!bytes || bytes.byteLength !== entry.size) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_BLOB", `Wrong size for snapshot blob '${entry.blobKey}'`);
+	}
+	return blobs;
+}
+async function scanCurrent(handle, absolute, relative, policy) {
+	const stat = await lstat(handle, absolute);
+	if (!stat) return [];
+	assertSupported(stat, relative);
+	if (stat.type === "file") return [{
+		path: relative,
+		kind: "file"
+	}];
+	const paths = [];
+	for (const child of await handle.fs.list(absolute)) {
+		const childEntry = childPath(absolute, child);
+		const childRelative = relative ? `${relative}/${childEntry.relative}` : childEntry.relative;
+		if (isProtectedPath(childRelative, policy.workspaceHash)) {
+			paths.push({
+				path: childRelative,
+				kind: "dir",
+				protected: true
+			});
+			continue;
+		}
+		if (!included(childRelative, child.type, policy)) {
+			paths.push({
+				path: childRelative,
+				kind: child.type,
+				protected: true
+			});
+			continue;
+		}
+		paths.push(...await scanCurrent(handle, childEntry.absolute, childRelative, policy));
+	}
+	return relative ? [{
+		path: relative,
+		kind: "dir"
+	}, ...paths] : paths;
+}
+async function scanDestination(handle, policy, rootPath) {
+	const root = await lstat(handle, rootPath);
+	if (!root || root.type !== "dir") throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_WORKSPACE", "Snapshot workspace is missing or is not a directory");
+	assertSupported(root, rootPath);
+	return scanCurrent(handle, rootPath, "", policy);
+}
+function parents(path) {
+	const values = [];
+	const parts = path.split("/");
+	for (let length = 1; length < parts.length; length++) values.push(parts.slice(0, length).join("/"));
+	return values;
+}
+function comparePath(a, b) {
+	return compareBytes(new TextEncoder().encode(a), new TextEncoder().encode(b));
+}
+function compareBytes(a, b) {
+	for (let i = 0; i < Math.min(a.length, b.length); i++) {
+		const left = a[i];
+		const right = b[i];
+		if (left !== right) return (left ?? 0) - (right ?? 0);
+	}
+	return a.length - b.length;
+}
+function getRequiredBlob(blobs, key) {
+	const bytes = blobs.get(key);
+	if (!bytes) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_MISSING_BLOB", `Missing snapshot blob '${key}'`);
+	return bytes;
+}
+function depth(path) {
+	return path.split("/").length;
+}
+function buildRestorePlan(entries, current) {
+	const desired = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		desired.set(entry.path, entry.kind);
+		for (const parent of parents(entry.path)) desired.set(parent, "dir");
+	}
+	const currentKinds = new Map(current.map((entry) => [entry.path, entry.kind]));
+	const candidates = current.filter((entry) => desired.get(entry.path) !== entry.kind).map((entry) => entry.path).sort((a, b) => depth(a) - depth(b) || comparePath(a, b));
+	const removes = [];
+	for (const path of candidates) {
+		if (current.some((entry) => entry.protected && (entry.path === path || entry.path.startsWith(`${path}/`)))) continue;
+		if (removes.some((ancestor) => path.startsWith(`${ancestor}/`))) continue;
+		removes.push(path);
+	}
+	return {
+		removes,
+		mkdirs: [...desired].filter(([path, kind]) => kind === "dir" && currentKinds.get(path) !== "dir").map(([path]) => path).sort((a, b) => depth(a) - depth(b) || comparePath(a, b)),
+		writes: entries.filter((entry) => entry.kind === "file").sort((a, b) => comparePath(a.path, b.path))
+	};
+}
+async function restoreSandboxFiles(handle, bundle, snapshot, suppliedPolicy = defaultSandboxSnapshotPolicy()) {
+	const policy = resolveSandboxSnapshotPolicy(suppliedPolicy, suppliedPolicy.workspaceHash);
+	if (!handle.fs.lstat) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_LSTAT_REQUIRED", "Snapshot restore requires fs.lstat");
+	const entries = validateManifest(snapshot, policy);
+	const rootPath = bundle.workspaceRoot ?? DEFAULT_ROOT;
+	const current = await scanDestination(handle, policy, rootPath);
+	for (const entry of entries) if (entry.kind === "file" && current.some((currentEntry) => currentEntry.protected && currentEntry.path.startsWith(`${entry.path}/`))) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_INVALID_PATH", `Protected current descendant conflicts with '${entry.path}'`);
+	const blobs = await loadBlobs(entries, bundle);
+	const plan = buildRestorePlan(entries, current);
+	for (const path of plan.removes) await handle.fs.remove(`${rootPath}/${path}`);
+	for (const path of plan.mkdirs) await handle.fs.mkdir(`${rootPath}/${path}`);
+	for (const entry of plan.writes) await handle.fs.write(`${rootPath}/${entry.path}`, getRequiredBlob(blobs, entry.blobKey));
+}
+async function captureSandboxArtifacts(bundle, threadId, resolvedSecrets = {}) {
+	if (!bundle.artifacts) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_ARTIFACT_SUPPORT_REQUIRED", "Snapshot artifact capture requires an artifact store");
+	const records = await bundle.artifacts.listForThread(threadId);
+	const loaded = /* @__PURE__ */ new Map();
+	const destinationKeys = /* @__PURE__ */ new Map();
+	const resolveBlobKey = bundle.resolveArtifactBlobKey ?? ((record) => record.blobKey ?? `artifacts/${record.runId}/${record.artifactId}`);
+	for (const record of records) {
+		const sourceKey = resolveBlobKey(record);
+		if (loaded.has(sourceKey)) continue;
+		const source = await bundle.blobs.get(sourceKey);
+		if (!source) throw new SandboxSnapshotError("SANDBOX_SNAPSHOT_MISSING_ARTIFACT_BLOB", `Missing artifact source blob '${sourceKey}'`);
+		loaded.set(sourceKey, new Uint8Array(await source.arrayBuffer()));
+	}
+	const output = [];
+	for (const record of records) {
+		let bytes = getRequiredBlob(loaded, resolveBlobKey(record));
+		bytes = await redactBytes(bytes, resolvedSecrets);
+		const key = `sandbox-artifacts/sha256/${await hash(bytes)}`;
+		if (!destinationKeys.has(key)) {
+			if (!await bundle.blobs.head(key)) await bundle.blobs.put(key, bytes);
+			destinationKeys.set(key, key);
+		}
+		output.push({
+			artifactId: record.artifactId,
+			name: record.name,
+			mimeType: record.mimeType,
+			size: bytes.byteLength,
+			blobKey: key,
+			createdAt: record.createdAt
+		});
+	}
+	output.sort((a, b) => a.createdAt - b.createdAt || comparePath(a.artifactId, b.artifactId));
+	return Object.freeze(output.map((artifact) => Object.freeze(artifact)));
+}
+//#endregion
+export { SandboxSnapshotError, captureSandboxArtifacts, captureSandboxFiles, defaultSandboxSnapshotPolicy, resolveSandboxSnapshotPolicy, restoreSandboxFiles };
+
+//# sourceMappingURL=snapshots.js.map