@tanstack/ai-sandbox 0.3.4 → 0.5.0

package/dist/esm/chunk-identity.d.ts

@@ -11,23 +11,6 @@ import { StreamChunk } from '@tanstack/ai';
  * seeded fresh for every call to this factory.
  */
 export declare function createRunScopedIdGen(runId: string): () => string;
-/**
- * A stable, order-independent identity for a chunk, excluding wall-clock
- * fields. Used to recognize the chunks a previous host already appended.
- *
- * - **Key-order independent**: object keys are sorted before stringifying, so
- *   a JSON round trip through the journal (which does not preserve key order)
- *   cannot spuriously diverge.
- * - **Recurses into nested arrays and objects**: tool-call arguments are
- *   nested, and a shallow fingerprint would miss a changed argument.
- * - **Excludes exactly `VOLATILE_FIELDS`** (`timestamp`) — everything else
- *   participates, including fields whose value is `undefined`.
- * - **Distinguishes present-but-`undefined` from absent**: `undefined` is
- *   encoded as the sentinel string `"__undefined__"` rather than dropped, so
- *   `{a: undefined}` and `{}` do not collide. A translator emitting an
- *   explicit `undefined` is a different chunk shape and must fingerprint
- *   differently.
- */
 export declare function chunkFingerprint(chunk: StreamChunk): string;
 /**
  * {@link chunkFingerprint} with the chunk's own `threadId` also excluded.

package/dist/esm/chunk-identity.js

@@ -1,3 +1,4 @@
+import { isSpecTopLevelKey, tanstackMetadata } from "@tanstack/ai/adapter-internals";
 //#region src/chunk-identity.ts
 /**
 * A deterministic id generator scoped to one run.
@@ -59,16 +60,36 @@ function stableStringify(value, dropped) {
 *   cannot spuriously diverge.
 * - **Recurses into nested arrays and objects**: tool-call arguments are
 *   nested, and a shallow fingerprint would miss a changed argument.
-* - **Excludes exactly `VOLATILE_FIELDS`** (`timestamp`) — everything else
-*   participates, including fields whose value is `undefined`.
+* - **Excludes `timestamp` and leftover adapter extras.** Spec keys
+*   participate, including `undefined` values. `metadata.tanstack` is dropped
+*   so stored spec chunks match live adapter yields.
 * - **Distinguishes present-but-`undefined` from absent**: `undefined` is
 *   encoded as the sentinel string `"__undefined__"` rather than dropped, so
 *   `{a: undefined}` and `{}` do not collide. A translator emitting an
 *   explicit `undefined` is a different chunk shape and must fingerprint
 *   differently.
 */
+function fingerprintableChunk(chunk) {
+	const out = {};
+	for (const [key, value] of Object.entries(chunk)) {
+		if (key === "timestamp") continue;
+		if (!isSpecTopLevelKey(chunk.type, key)) continue;
+		if (key === "metadata" && value != null && typeof value === "object") {
+			const rest = {};
+			for (const [metaKey, metaValue] of Object.entries(value)) {
+				if (metaKey === "tanstack") continue;
+				rest[metaKey] = metaValue;
+			}
+			if (Object.keys(rest).length === 0) continue;
+			out.metadata = rest;
+			continue;
+		}
+		out[key] = value;
+	}
+	return out;
+}
 function chunkFingerprint(chunk) {
-	return stableStringify(chunk, VOLATILE_FIELDS);
+	return stableStringify(fingerprintableChunk(chunk), VOLATILE_FIELDS);
 }
 /**
 * {@link chunkFingerprint} with the chunk's own `threadId` also excluded.
@@ -82,7 +103,7 @@ function chunkFingerprint(chunk) {
 * `JournalReplayThreadIdMismatchError` in `align.ts`).
 */
 function chunkFingerprintIgnoringThreadId(chunk) {
-	return stableStringify(chunk, VOLATILE_AND_THREAD_ID);
+	return stableStringify(fingerprintableChunk(chunk), VOLATILE_AND_THREAD_ID);
 }
 /**
 * A chunk's own `threadId`, or `undefined` when it carries none.
@@ -94,7 +115,9 @@ function chunkFingerprintIgnoringThreadId(chunk) {
 */
 function chunkThreadId(chunk) {
 	const value = chunk[THREAD_ID_FIELD];
-	return typeof value === "string" ? value : void 0;
+	if (typeof value === "string") return value;
+	const nested = tanstackMetadata(chunk)?.threadId;
+	return typeof nested === "string" ? nested : void 0;
 }
 //#endregion
 export { chunkFingerprint, chunkFingerprintIgnoringThreadId, chunkThreadId, createRunScopedIdGen };

package/dist/esm/chunk-identity.js.map

@@ -1 +1 @@
-{"version":3,"file":"chunk-identity.js","names":[],"sources":["../../src/chunk-identity.ts"],"sourcesContent":["/**\n * Deterministic chunk identity — the prerequisite that makes journal replay\n * exact.\n *\n * The design premise is that re-translating a journal prefix reproduces the\n * chunks a previous host already delivered, so a successor can recognize and\n * skip them (see `align.ts`, a later task). Two things in the default path\n * break that premise:\n *\n * 1. `ChatAdapter.generateId()` — `packages/ai/src/activities/chat/adapter.ts:227`,\n *    read directly for this task — is:\n *\n *    ```ts\n *    protected generateId(): string {\n *      return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n *    }\n *    ```\n *\n *    and every harness translator mints message ids through it (wired as\n *    `genId` in the Grok Build, Claude Code, and Codex text adapters). Both\n *    `Date.now()` and `Math.random()` are non-reproducible: replaying the same\n *    journal bytes through a second `generateId()` call produces a different\n *    id every time, so \"same bytes ⇒ same chunks\" is false on the journaled\n *    path today. {@link createRunScopedIdGen} replaces it with a run-scoped\n *    counter that has neither a clock nor randomness, so two generators built\n *    from the same `runId` always produce the same sequence.\n * 2. Chunks also carry `timestamp: Date.now()`, which cannot be reproduced at\n *    all, deterministic id or not. {@link chunkFingerprint} therefore excludes\n *    exactly that field — nothing downstream keys on a chunk's timestamp, so\n *    leaving it wall-clock is safe, but every other field must participate in\n *    the comparison or a real divergence would go undetected.\n */\nimport type { StreamChunk } from '@tanstack/ai'\n\n/**\n * A deterministic id generator scoped to one run.\n *\n * Passed as the harness translators' `genId`, so translating the same journal\n * prefix twice mints the same message ids. The counter is per-generator, so a\n * replay must create a fresh one and start from the journal's first byte —\n * which is exactly what the alignment step (a later task) assumes.\n *\n * No clock, no `Math.random`, no crypto: `next` is the only state, and it is\n * seeded fresh for every call to this factory.\n */\nexport function createRunScopedIdGen(runId: string): () => string {\n  let next = 0\n  return () => {\n    const id = `${runId}-${next}`\n    next += 1\n    return id\n  }\n}\n\n/**\n * Fields excluded from a fingerprint because they are wall-clock and therefore\n * unreproducible. Kept as an explicit set so adding one is a deliberate,\n * reviewable act rather than a silent loosening of the comparison.\n */\nconst VOLATILE_FIELDS: ReadonlySet<string> = new Set(['timestamp'])\n\n/**\n * The conversation id every chunk carries. Excluded from\n * {@link chunkFingerprintIgnoringThreadId} — and ONLY from that variant — so\n * alignment can tell an id-only mismatch from a real content divergence.\n */\nconst THREAD_ID_FIELD = 'threadId'\n\nconst VOLATILE_AND_THREAD_ID: ReadonlySet<string> = new Set([\n  ...VOLATILE_FIELDS,\n  THREAD_ID_FIELD,\n])\n\n/**\n * `dropped` applies at the TOP LEVEL only (nested calls pass `undefined`).\n * A `threadId` nested inside, say, a tool call's arguments is real content and\n * must keep participating in the comparison.\n */\nfunction stableStringify(\n  value: unknown,\n  dropped: ReadonlySet<string> | undefined,\n): string {\n  if (value === null) return 'null'\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => stableStringify(item, undefined)).join(',')}]`\n  }\n  if (typeof value === 'object') {\n    const record: Record<string, unknown> = value as Record<string, unknown>\n    const keys = Object.keys(record)\n      .filter((key) => dropped === undefined || !dropped.has(key))\n      .sort()\n    const parts = keys.map((key) => {\n      const entry = record[key]\n      const encoded =\n        entry === undefined\n          ? '\"__undefined__\"'\n          : stableStringify(entry, undefined)\n      return `${JSON.stringify(key)}:${encoded}`\n    })\n    return `{${parts.join(',')}}`\n  }\n  const encoded = JSON.stringify(value)\n  return encoded === undefined ? 'null' : encoded\n}\n\n/**\n * A stable, order-independent identity for a chunk, excluding wall-clock\n * fields. Used to recognize the chunks a previous host already appended.\n *\n * - **Key-order independent**: object keys are sorted before stringifying, so\n *   a JSON round trip through the journal (which does not preserve key order)\n *   cannot spuriously diverge.\n * - **Recurses into nested arrays and objects**: tool-call arguments are\n *   nested, and a shallow fingerprint would miss a changed argument.\n * - **Excludes exactly `VOLATILE_FIELDS`** (`timestamp`) — everything else\n *   participates, including fields whose value is `undefined`.\n * - **Distinguishes present-but-`undefined` from absent**: `undefined` is\n *   encoded as the sentinel string `\"__undefined__\"` rather than dropped, so\n *   `{a: undefined}` and `{}` do not collide. A translator emitting an\n *   explicit `undefined` is a different chunk shape and must fingerprint\n *   differently.\n */\nexport function chunkFingerprint(chunk: StreamChunk): string {\n  return stableStringify(chunk, VOLATILE_FIELDS)\n}\n\n/**\n * {@link chunkFingerprint} with the chunk's own `threadId` also excluded.\n *\n * NOT an alternative identity — never use it to decide that two chunks are the\n * same. Its single purpose is DIAGNOSIS: when a replay diverges from the stored\n * log, comparing both fingerprints answers \"did the agent behave differently, or\n * did only the conversation id move?\". Two chunks that match here but not under\n * {@link chunkFingerprint} differ in `threadId` and nothing else, which is a\n * misconfigured attach route rather than a determinism regression (see\n * `JournalReplayThreadIdMismatchError` in `align.ts`).\n */\nexport function chunkFingerprintIgnoringThreadId(chunk: StreamChunk): string {\n  return stableStringify(chunk, VOLATILE_AND_THREAD_ID)\n}\n\n/**\n * A chunk's own `threadId`, or `undefined` when it carries none.\n *\n * Reads the field structurally rather than narrowing on `chunk.type`: nearly\n * every member of the `StreamChunk` union declares `threadId?: string`, and an\n * exhaustive switch would have to be revisited for each new member while adding\n * nothing — a chunk with no `threadId` is exactly the `undefined` case.\n */\nexport function chunkThreadId(chunk: StreamChunk): string | undefined {\n  const record: Record<string, unknown> = chunk as Record<string, unknown>\n  const value = record[THREAD_ID_FIELD]\n  return typeof value === 'string' ? value : undefined\n}\n"],"mappings":";;;;;;;;;;;;AA6CA,SAAgB,qBAAqB,OAA6B;CAChE,IAAI,OAAO;CACX,aAAa;EACX,MAAM,KAAK,GAAG,MAAM,GAAG;EACvB,QAAQ;EACR,OAAO;CACT;AACF;;;;;;AAOA,IAAM,kCAAuC,IAAI,IAAI,CAAC,WAAW,CAAC;;;;;;AAOlE,IAAM,kBAAkB;AAExB,IAAM,yCAA8C,IAAI,IAAI,CAC1D,GAAG,iBACH,eACF,CAAC;;;;;;AAOD,SAAS,gBACP,OACA,SACQ;CACR,IAAI,UAAU,MAAM,OAAO;CAC3B,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,IAAI,MAAM,KAAK,SAAS,gBAAgB,MAAM,KAAA,CAAS,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE;CAE7E,IAAI,OAAO,UAAU,UAAU;EAC7B,MAAM,SAAkC;EAYxC,OAAO,IAXM,OAAO,KAAK,MAAM,CAAC,CAC7B,QAAQ,QAAQ,YAAY,KAAA,KAAa,CAAC,QAAQ,IAAI,GAAG,CAAC,CAAC,CAC3D,KACW,CAAA,CAAK,KAAK,QAAQ;GAC9B,MAAM,QAAQ,OAAO;GACrB,MAAM,UACJ,UAAU,KAAA,IACN,sBACA,gBAAgB,OAAO,KAAA,CAAS;GACtC,OAAO,GAAG,KAAK,UAAU,GAAG,EAAE,GAAG;EACnC,CACW,CAAA,CAAM,KAAK,GAAG,EAAE;CAC7B;CACA,MAAM,UAAU,KAAK,UAAU,KAAK;CACpC,OAAO,YAAY,KAAA,IAAY,SAAS;AAC1C;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,iBAAiB,OAA4B;CAC3D,OAAO,gBAAgB,OAAO,eAAe;AAC/C;;;;;;;;;;;;AAaA,SAAgB,iCAAiC,OAA4B;CAC3E,OAAO,gBAAgB,OAAO,sBAAsB;AACtD;;;;;;;;;AAUA,SAAgB,cAAc,OAAwC;CAEpE,MAAM,QAAQ,MAAO;CACrB,OAAO,OAAO,UAAU,WAAW,QAAQ,KAAA;AAC7C"}
+{"version":3,"file":"chunk-identity.js","names":[],"sources":["../../src/chunk-identity.ts"],"sourcesContent":["/**\n * Deterministic chunk identity — the prerequisite that makes journal replay\n * exact.\n *\n * The design premise is that re-translating a journal prefix reproduces the\n * chunks a previous host already delivered, so a successor can recognize and\n * skip them (see `align.ts`, a later task). Two things in the default path\n * break that premise:\n *\n * 1. `ChatAdapter.generateId()` — `packages/ai/src/activities/chat/adapter.ts:227`,\n *    read directly for this task — is:\n *\n *    ```ts\n *    protected generateId(): string {\n *      return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n *    }\n *    ```\n *\n *    and every harness translator mints message ids through it (wired as\n *    `genId` in the Grok Build, Claude Code, and Codex text adapters). Both\n *    `Date.now()` and `Math.random()` are non-reproducible: replaying the same\n *    journal bytes through a second `generateId()` call produces a different\n *    id every time, so \"same bytes ⇒ same chunks\" is false on the journaled\n *    path today. {@link createRunScopedIdGen} replaces it with a run-scoped\n *    counter that has neither a clock nor randomness, so two generators built\n *    from the same `runId` always produce the same sequence.\n * 2. Chunks also carry `timestamp: Date.now()`, which cannot be reproduced at\n *    all, deterministic id or not. {@link chunkFingerprint} therefore excludes\n *    exactly that field — nothing downstream keys on a chunk's timestamp, so\n *    leaving it wall-clock is safe, but every other field must participate in\n *    the comparison or a real divergence would go undetected.\n * 3. Adapter yields still carry leftover TanStack extras (`content`, `args`,\n *    `finishReason`). The durability log stores spec chunks. Fingerprints keep\n *    only AG-UI spec keys and drop `metadata.tanstack`, so a live adapter yield\n *    matches the stored spec chunk.\n */\nimport type { StreamChunk } from '@tanstack/ai'\nimport {\n  isSpecTopLevelKey,\n  tanstackMetadata,\n} from '@tanstack/ai/adapter-internals'\n\n/**\n * A deterministic id generator scoped to one run.\n *\n * Passed as the harness translators' `genId`, so translating the same journal\n * prefix twice mints the same message ids. The counter is per-generator, so a\n * replay must create a fresh one and start from the journal's first byte —\n * which is exactly what the alignment step (a later task) assumes.\n *\n * No clock, no `Math.random`, no crypto: `next` is the only state, and it is\n * seeded fresh for every call to this factory.\n */\nexport function createRunScopedIdGen(runId: string): () => string {\n  let next = 0\n  return () => {\n    const id = `${runId}-${next}`\n    next += 1\n    return id\n  }\n}\n\n/**\n * Fields excluded from a fingerprint because they are wall-clock and therefore\n * unreproducible. Kept as an explicit set so adding one is a deliberate,\n * reviewable act rather than a silent loosening of the comparison.\n */\nconst VOLATILE_FIELDS: ReadonlySet<string> = new Set(['timestamp'])\n\n/**\n * The conversation id every chunk carries. Excluded from\n * {@link chunkFingerprintIgnoringThreadId} — and ONLY from that variant — so\n * alignment can tell an id-only mismatch from a real content divergence.\n */\nconst THREAD_ID_FIELD = 'threadId'\n\nconst VOLATILE_AND_THREAD_ID: ReadonlySet<string> = new Set([\n  ...VOLATILE_FIELDS,\n  THREAD_ID_FIELD,\n])\n\n/**\n * `dropped` applies at the TOP LEVEL only (nested calls pass `undefined`).\n * A `threadId` nested inside, say, a tool call's arguments is real content and\n * must keep participating in the comparison.\n */\nfunction stableStringify(\n  value: unknown,\n  dropped: ReadonlySet<string> | undefined,\n): string {\n  if (value === null) return 'null'\n  if (Array.isArray(value)) {\n    return `[${value.map((item) => stableStringify(item, undefined)).join(',')}]`\n  }\n  if (typeof value === 'object') {\n    const record: Record<string, unknown> = value as Record<string, unknown>\n    const keys = Object.keys(record)\n      .filter((key) => dropped === undefined || !dropped.has(key))\n      .sort()\n    const parts = keys.map((key) => {\n      const entry = record[key]\n      const encoded =\n        entry === undefined\n          ? '\"__undefined__\"'\n          : stableStringify(entry, undefined)\n      return `${JSON.stringify(key)}:${encoded}`\n    })\n    return `{${parts.join(',')}}`\n  }\n  const encoded = JSON.stringify(value)\n  return encoded === undefined ? 'null' : encoded\n}\n\n/**\n * A stable, order-independent identity for a chunk, excluding wall-clock\n * fields. Used to recognize the chunks a previous host already appended.\n *\n * - **Key-order independent**: object keys are sorted before stringifying, so\n *   a JSON round trip through the journal (which does not preserve key order)\n *   cannot spuriously diverge.\n * - **Recurses into nested arrays and objects**: tool-call arguments are\n *   nested, and a shallow fingerprint would miss a changed argument.\n * - **Excludes `timestamp` and leftover adapter extras.** Spec keys\n *   participate, including `undefined` values. `metadata.tanstack` is dropped\n *   so stored spec chunks match live adapter yields.\n * - **Distinguishes present-but-`undefined` from absent**: `undefined` is\n *   encoded as the sentinel string `\"__undefined__\"` rather than dropped, so\n *   `{a: undefined}` and `{}` do not collide. A translator emitting an\n *   explicit `undefined` is a different chunk shape and must fingerprint\n *   differently.\n */\nfunction fingerprintableChunk(chunk: StreamChunk): Record<string, unknown> {\n  const out: Record<string, unknown> = {}\n  for (const [key, value] of Object.entries(chunk)) {\n    if (key === 'timestamp') continue\n    if (!isSpecTopLevelKey(chunk.type, key)) continue\n    if (key === 'metadata' && value != null && typeof value === 'object') {\n      const rest: Record<string, unknown> = {}\n      for (const [metaKey, metaValue] of Object.entries(value)) {\n        if (metaKey === 'tanstack') continue\n        rest[metaKey] = metaValue\n      }\n      if (Object.keys(rest).length === 0) continue\n      out.metadata = rest\n      continue\n    }\n    out[key] = value\n  }\n  return out\n}\n\nexport function chunkFingerprint(chunk: StreamChunk): string {\n  return stableStringify(fingerprintableChunk(chunk), VOLATILE_FIELDS)\n}\n\n/**\n * {@link chunkFingerprint} with the chunk's own `threadId` also excluded.\n *\n * NOT an alternative identity — never use it to decide that two chunks are the\n * same. Its single purpose is DIAGNOSIS: when a replay diverges from the stored\n * log, comparing both fingerprints answers \"did the agent behave differently, or\n * did only the conversation id move?\". Two chunks that match here but not under\n * {@link chunkFingerprint} differ in `threadId` and nothing else, which is a\n * misconfigured attach route rather than a determinism regression (see\n * `JournalReplayThreadIdMismatchError` in `align.ts`).\n */\nexport function chunkFingerprintIgnoringThreadId(chunk: StreamChunk): string {\n  return stableStringify(fingerprintableChunk(chunk), VOLATILE_AND_THREAD_ID)\n}\n\n/**\n * A chunk's own `threadId`, or `undefined` when it carries none.\n *\n * Reads the field structurally rather than narrowing on `chunk.type`: nearly\n * every member of the `StreamChunk` union declares `threadId?: string`, and an\n * exhaustive switch would have to be revisited for each new member while adding\n * nothing — a chunk with no `threadId` is exactly the `undefined` case.\n */\nexport function chunkThreadId(chunk: StreamChunk): string | undefined {\n  const record: Record<string, unknown> = chunk as Record<string, unknown>\n  const value = record[THREAD_ID_FIELD]\n  if (typeof value === 'string') return value\n  const nested = tanstackMetadata(chunk)?.threadId\n  return typeof nested === 'string' ? nested : undefined\n}\n"],"mappings":";;;;;;;;;;;;;AAqDA,SAAgB,qBAAqB,OAA6B;CAChE,IAAI,OAAO;CACX,aAAa;EACX,MAAM,KAAK,GAAG,MAAM,GAAG;EACvB,QAAQ;EACR,OAAO;CACT;AACF;;;;;;AAOA,IAAM,kCAAuC,IAAI,IAAI,CAAC,WAAW,CAAC;;;;;;AAOlE,IAAM,kBAAkB;AAExB,IAAM,yCAA8C,IAAI,IAAI,CAC1D,GAAG,iBACH,eACF,CAAC;;;;;;AAOD,SAAS,gBACP,OACA,SACQ;CACR,IAAI,UAAU,MAAM,OAAO;CAC3B,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,IAAI,MAAM,KAAK,SAAS,gBAAgB,MAAM,KAAA,CAAS,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE;CAE7E,IAAI,OAAO,UAAU,UAAU;EAC7B,MAAM,SAAkC;EAYxC,OAAO,IAXM,OAAO,KAAK,MAAM,CAAC,CAC7B,QAAQ,QAAQ,YAAY,KAAA,KAAa,CAAC,QAAQ,IAAI,GAAG,CAAC,CAAC,CAC3D,KACW,CAAA,CAAK,KAAK,QAAQ;GAC9B,MAAM,QAAQ,OAAO;GACrB,MAAM,UACJ,UAAU,KAAA,IACN,sBACA,gBAAgB,OAAO,KAAA,CAAS;GACtC,OAAO,GAAG,KAAK,UAAU,GAAG,EAAE,GAAG;EACnC,CACW,CAAA,CAAM,KAAK,GAAG,EAAE;CAC7B;CACA,MAAM,UAAU,KAAK,UAAU,KAAK;CACpC,OAAO,YAAY,KAAA,IAAY,SAAS;AAC1C;;;;;;;;;;;;;;;;;;;AAoBA,SAAS,qBAAqB,OAA6C;CACzE,MAAM,MAA+B,CAAC;CACtC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,GAAG;EAChD,IAAI,QAAQ,aAAa;EACzB,IAAI,CAAC,kBAAkB,MAAM,MAAM,GAAG,GAAG;EACzC,IAAI,QAAQ,cAAc,SAAS,QAAQ,OAAO,UAAU,UAAU;GACpE,MAAM,OAAgC,CAAC;GACvC,KAAK,MAAM,CAAC,SAAS,cAAc,OAAO,QAAQ,KAAK,GAAG;IACxD,IAAI,YAAY,YAAY;IAC5B,KAAK,WAAW;GAClB;GACA,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,WAAW,GAAG;GACpC,IAAI,WAAW;GACf;EACF;EACA,IAAI,OAAO;CACb;CACA,OAAO;AACT;AAEA,SAAgB,iBAAiB,OAA4B;CAC3D,OAAO,gBAAgB,qBAAqB,KAAK,GAAG,eAAe;AACrE;;;;;;;;;;;;AAaA,SAAgB,iCAAiC,OAA4B;CAC3E,OAAO,gBAAgB,qBAAqB,KAAK,GAAG,sBAAsB;AAC5E;;;;;;;;;AAUA,SAAgB,cAAc,OAAwC;CAEpE,MAAM,QAAQ,MAAO;CACrB,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,MAAM,SAAS,iBAAiB,KAAK,CAAC,EAAE;CACxC,OAAO,OAAO,WAAW,WAAW,SAAS,KAAA;AAC/C"}

package/dist/esm/contracts.d.ts

@@ -98,6 +98,11 @@ export interface SandboxFs {
     remove: (path: string) => Promise<void>;
     rename: (from: string, to: string) => Promise<void>;
     exists: (path: string) => Promise<boolean>;
+    /**
+     * Optional metadata lookup. Implementations must not follow symlinks.
+     * Returns undefined only for a confirmed missing path. All other errors reject.
+     */
+    lstat?: (path: string) => Promise<SandboxFsStat | undefined>;
     /** Optional — present only when `capabilities.fs` providers advertise watch. */
     watch?: (path: string, onEvent: (event: {
         type: string;
@@ -106,6 +111,20 @@ export interface SandboxFs {
         stop: () => Promise<void>;
     }>;
 }
+export type SandboxFsStat = {
+    type: 'file';
+    mode: number;
+    size: number;
+} | {
+    type: 'dir';
+    mode: number;
+} | {
+    type: 'symlink';
+    mode: number;
+} | {
+    type: 'other';
+    mode: number;
+};
 /**
  * Uniform git surface. Implementations either delegate to the provider's
  * native git (when advertised) or desugar to `process.exec("git …")`, so the

package/dist/esm/index.d.ts

@@ -1,6 +1,16 @@
 export { SandboxCapability, SandboxPolicyCapability, ToolBridgeProvisionerCapability, getSandbox, provideSandbox, getSandboxPolicy, provideSandboxPolicy, getToolBridgeProvisioner, provideToolBridgeProvisioner, } from './capabilities.js';
 export { SandboxInstanceStoreCapability, getSandboxInstanceStore, provideSandboxInstanceStore, InMemorySandboxInstanceStore, defineSandboxInstanceStore, } from './instance-store.js';
 export type { SandboxInstanceStore, SandboxInstanceRecord, } from './instance-store.js';
+export { SandboxCheckpointError, SandboxCheckpointConflictError, SandboxCheckpointDuplicateIdError, SandboxCheckpointInvalidIdError, SandboxCheckpointInvalidEntryError, SandboxCheckpointParentMismatchError, SandboxCheckpointNotHeadError, SandboxCheckpointWriterConflictError, SandboxCheckpointWriterLostError, isForkCapableSandboxCheckpointStore, InMemorySandboxCheckpointStore, defineSandboxCheckpointStore, } from './checkpoint-store.js';
+export type { SandboxCheckpoint, SandboxCheckpointStore, SandboxSnapshotEntry, SandboxSnapshotFileEntry, SandboxSnapshotDirectoryEntry, SandboxSnapshotArtifact, SandboxCheckpointErrorCode, SandboxCheckpointWriter, SandboxCheckpointWriterLease, SandboxCheckpointStoreOptions, SandboxCheckpointForkInput, SandboxCheckpointForkCapability, ForkCapableSandboxCheckpointStore, } from './checkpoint-store.js';
+export { SandboxSnapshotError, defaultSandboxSnapshotPolicy } from './snapshots.js';
+export type { SandboxSnapshotErrorCode, SandboxSnapshotPolicy, } from './snapshots.js';
+export { memorySandboxSnapshots } from './memory-snapshots.js';
+export type { MemorySandboxSnapshots, MemorySandboxSnapshotsOptions, } from './memory-snapshots.js';
+export { createSandboxSnapshots } from './snapshot-operations.js';
+export type { CreateSandboxSnapshotsInput, ForkSandboxSnapshotInput, ReadSandboxSnapshotArtifactInput, SandboxSnapshots, SaveSandboxSnapshotInput, SnapshotPersistence, } from './snapshot-operations.js';
+export { createSnapshotTools } from './snapshot-tools.js';
+export type { CreateSnapshotToolsOptions } from './snapshot-tools.js';
 export { ProjectionCapability, getWorkspaceProjection, provideWorkspaceProjection, } from './projection.js';
 export type { WorkspaceProjection } from './projection.js';
 export { withSandbox } from './middleware.js';
@@ -14,7 +24,7 @@ export { createSecrets, bearer, isSecretRef, resolveSecret, resolveBearer, resol
 export type { SecretRef, Secrets, BearerRef } from './secrets.js';
 export { defineSandboxPolicy, evaluateCommand, commandAliases } from './policy.js';
 export type { SandboxPolicy, PolicyDecision, CommandRules, CapabilityRules, } from './policy.js';
-export type { SandboxProvider, SandboxHandle, SandboxCapabilities, SandboxFs, SandboxGit, SandboxProcess, SandboxPorts, SandboxEnv, SandboxChannel, SpawnHandle, ExecResult, ProcessOptions, SnapshotRef, SandboxCreateInput, SandboxResumeInput, SandboxRestoreInput, SandboxDestroyInput, } from './contracts.js';
+export type { SandboxProvider, SandboxHandle, SandboxCapabilities, SandboxFs, SandboxFsStat, SandboxGit, SandboxProcess, SandboxPorts, SandboxEnv, SandboxChannel, SpawnHandle, ExecResult, ProcessOptions, SnapshotRef, SandboxCreateInput, SandboxResumeInput, SandboxRestoreInput, SandboxDestroyInput, } from './contracts.js';
 export { bootstrapWorkspace, detectPackageManager, DEFAULT_WORKSPACE_ROOT, } from './bootstrap.js';
 export { resolveHarnessCwd } from './harness-cwd.js';
 export type { BootstrapResult } from './bootstrap.js';

package/dist/esm/index.js

@@ -1,19 +1,24 @@
 import { SandboxCapability, SandboxPolicyCapability, ToolBridgeProvisionerCapability, getSandbox, getSandboxPolicy, getToolBridgeProvisioner, provideSandbox, provideSandboxPolicy, provideToolBridgeProvisioner } from "./capabilities.js";
 import { InMemorySandboxInstanceStore, SandboxInstanceStoreCapability, defineSandboxInstanceStore, getSandboxInstanceStore, provideSandboxInstanceStore } from "./instance-store.js";
+import { InMemorySandboxCheckpointStore, SandboxCheckpointConflictError, SandboxCheckpointDuplicateIdError, SandboxCheckpointError, SandboxCheckpointInvalidEntryError, SandboxCheckpointInvalidIdError, SandboxCheckpointNotHeadError, SandboxCheckpointParentMismatchError, SandboxCheckpointWriterConflictError, SandboxCheckpointWriterLostError, defineSandboxCheckpointStore, isForkCapableSandboxCheckpointStore } from "./checkpoint-store.js";
+import { SandboxSnapshotError, defaultSandboxSnapshotPolicy } from "./snapshots.js";
+import { bearer, createSecrets, isSecretRef, resolveAllSecrets, resolveBearer, resolveSecret } from "./secrets.js";
+import { computeSandboxKey, computeWorkspaceHash } from "./key.js";
+import { resolveHarnessCwd } from "./harness-cwd.js";
+import { discoverSkillDirs, formatWorkspaceScriptsSection, mergeAgentsContent, resolveGitSkillDir, writeAgentsFile } from "./agents-file.js";
+import { DEFAULT_WORKSPACE_ROOT, bootstrapWorkspace, detectPackageManager } from "./bootstrap.js";
+import { defineSandbox } from "./sandbox.js";
+import { createSandboxSnapshots } from "./snapshot-operations.js";
+import { memorySandboxSnapshots } from "./memory-snapshots.js";
+import { createSnapshotTools } from "./snapshot-tools.js";
 import { ProjectionCapability, getWorkspaceProjection, provideWorkspaceProjection } from "./projection.js";
 import { DEFAULT_JOURNAL_DIR, EXIT_SENTINEL_KEY, EXIT_SENTINEL_NONCE_KEY, decodeJournalRunId, encodeRunId, exitSentinelLine, journalExistsCommand, journalExitProbeCommand, journalFollowCommand, journalListCommand, journalMtimeListCommand, journalPaths, journalReadCommand, journaledCommand, parseExitSentinel, parseJournalExit, parseJournalMtimeListing } from "./journal.js";
 import { chunkFingerprint, chunkFingerprintIgnoringThreadId, chunkThreadId, createRunScopedIdGen } from "./chunk-identity.js";
 import { DEFAULT_MAX_OUT_OF_BAND_SKIP, JournalReplayDivergedError, JournalReplayThreadIdMismatchError, alignToStoredLog, isBridgeCustomChunk } from "./align.js";
 import { DurableAttachNotSupportedError, DurableRunIdRequiredError, DurableThreadIdRequiredError, SandboxDurabilityCapability, alignedIfAttaching, getSandboxDurability, journalOptionsFor, provideSandboxDurability, resolveDurableRunId, resolveDurableThreadId } from "./durability.js";
-import { computeSandboxKey, computeWorkspaceHash } from "./key.js";
-import { bearer, createSecrets, isSecretRef, resolveAllSecrets, resolveBearer, resolveSecret } from "./secrets.js";
 import { isSandboxToolCall } from "./tool-history.js";
-import { resolveHarnessCwd } from "./harness-cwd.js";
-import { discoverSkillDirs, formatWorkspaceScriptsSection, mergeAgentsContent, resolveGitSkillDir, writeAgentsFile } from "./agents-file.js";
-import { DEFAULT_WORKSPACE_ROOT, bootstrapWorkspace, detectPackageManager } from "./bootstrap.js";
 import { diffSnapshots, watchWorkspace } from "./watch.js";
 import { withSandbox } from "./middleware.js";
-import { defineSandbox } from "./sandbox.js";
 import { agentSkill, defineWorkspace, fileSkill, gitSkill, gitSource, githubRepo, localSource, mcpSkill } from "./workspace.js";
 import { commandAliases, defineSandboxPolicy, evaluateCommand } from "./policy.js";
 import { createExecBackedGit } from "./git-exec.js";
@@ -32,4 +37,4 @@ import { createBridgeEventChannel, mergeChunkStreams } from "./bridge-events.js"
 import { executeHostTool, httpRemoteToolExecutor, isToolExecRequest, remoteToolStubs, toolDescriptors } from "./remote-tools.js";
 import { APPROVAL_REQUESTED_EVENT, approvalId, buildApprovalRequestedEvent, resolveApproval } from "./approvals.js";
 import { MissingSandboxError, UnsupportedCapabilityError } from "./errors.js";
-export { APPROVAL_REQUESTED_EVENT, BRIDGED_MCP_SERVER_NAME, DEFAULT_ATTACH_JOURNAL_WAIT_MS, DEFAULT_ATTACH_PROBE_INTERVAL_MS, DEFAULT_EXIT_PROBE_BYTES, DEFAULT_FENCE_QUIET_MS, DEFAULT_JOURNAL_DIR, DEFAULT_JOURNAL_POLL_MS, DEFAULT_MAX_DELETES, DEFAULT_MAX_OUT_OF_BAND_SKIP, DEFAULT_MAX_RUNS, DEFAULT_ORPHAN_TTL_MS, DEFAULT_RUN_BUDGET_MS, DEFAULT_WORKSPACE_ROOT, DurableAttachNotSupportedError, DurableRunIdRequiredError, DurableThreadIdRequiredError, EXIT_SENTINEL_KEY, EXIT_SENTINEL_NONCE_KEY, InMemorySandboxInstanceStore, JournalAttachUnavailableError, JournalReplayDivergedError, JournalReplayThreadIdMismatchError, MissingSandboxError, ProjectionCapability, RunClaimLostError, RunClaimNotAcquiredError, RunController, RunDriverPipeOutsideClaimError, SandboxCapability, SandboxDurabilityCapability, SandboxInstanceStoreCapability, SandboxPolicyCapability, SandboxReclaimFailedError, ToolBridgeProvisionerCapability, UnsupportedCapabilityError, agentSkill, alignToStoredLog, alignedIfAttaching, approvalId, awaitAttachableJournal, bearer, bootstrapWorkspace, buildApprovalRequestedEvent, chunkFingerprint, chunkFingerprintIgnoringThreadId, chunkThreadId, commandAliases, computeSandboxKey, computeWorkspaceHash, createBridgeEventChannel, createExecBackedGit, createRunScopedIdGen, createSecrets, createToolBridgeCore, decodeBase64Stream, decodeJournalRunId, defineSandbox, defineSandboxInstanceStore, defineSandboxPolicy, defineWorkspace, detectPackageManager, diffSnapshots, discoverSkillDirs, encodeRunId, evaluateCommand, executeHostTool, exitSentinelLine, fileSkill, formatWorkspaceScriptsSection, getSandbox, getSandboxDurability, getSandboxInstanceStore, getSandboxPolicy, getToolBridgeProvisioner, getWorkspaceProjection, gitSkill, gitSource, githubRepo, handleBridgeJsonRpc, hostForSandbox, httpRemoteToolExecutor, isBridgeCustomChunk, isSandboxToolCall, isSecretRef, isToolExecRequest, journalExistsCommand, journalExitProbeCommand, journalFollowCommand, journalListCommand, journalMtimeListCommand, journalOptionsFor, journalPaths, journalReadCommand, journalReadStrategy, journaledCommand, localSource, mcpSkill, mergeAgentsContent, mergeChunkStreams, nodeHttpBridgeProvisioner, parseExitSentinel, parseJournalExit, parseJournalMtimeListing, pipeToRunLog, probeRunExit, provideSandbox, provideSandboxDurability, provideSandboxInstanceStore, provideSandboxPolicy, provideToolBridgeProvisioner, provideWorkspaceProjection, pruneJournals, readJournal, readJournalNdjson, reapDetachedRuns, reclaimSandbox, remoteToolStubs, resolveAllSecrets, resolveApproval, resolveBearer, resolveDurableRunId, resolveDurableThreadId, resolveGitSkillDir, resolveHarnessCwd, resolveSecret, sandboxReclaimer, sandboxRunDriver, spawnNdjson, startHostToolBridge, startJournaledAgent, timingSafeBearerEqual, toJournalLines, toLines, toolDescriptors, watchWorkspace, withSandbox, writeAgentsFile };
+export { APPROVAL_REQUESTED_EVENT, BRIDGED_MCP_SERVER_NAME, DEFAULT_ATTACH_JOURNAL_WAIT_MS, DEFAULT_ATTACH_PROBE_INTERVAL_MS, DEFAULT_EXIT_PROBE_BYTES, DEFAULT_FENCE_QUIET_MS, DEFAULT_JOURNAL_DIR, DEFAULT_JOURNAL_POLL_MS, DEFAULT_MAX_DELETES, DEFAULT_MAX_OUT_OF_BAND_SKIP, DEFAULT_MAX_RUNS, DEFAULT_ORPHAN_TTL_MS, DEFAULT_RUN_BUDGET_MS, DEFAULT_WORKSPACE_ROOT, DurableAttachNotSupportedError, DurableRunIdRequiredError, DurableThreadIdRequiredError, EXIT_SENTINEL_KEY, EXIT_SENTINEL_NONCE_KEY, InMemorySandboxCheckpointStore, InMemorySandboxInstanceStore, JournalAttachUnavailableError, JournalReplayDivergedError, JournalReplayThreadIdMismatchError, MissingSandboxError, ProjectionCapability, RunClaimLostError, RunClaimNotAcquiredError, RunController, RunDriverPipeOutsideClaimError, SandboxCapability, SandboxCheckpointConflictError, SandboxCheckpointDuplicateIdError, SandboxCheckpointError, SandboxCheckpointInvalidEntryError, SandboxCheckpointInvalidIdError, SandboxCheckpointNotHeadError, SandboxCheckpointParentMismatchError, SandboxCheckpointWriterConflictError, SandboxCheckpointWriterLostError, SandboxDurabilityCapability, SandboxInstanceStoreCapability, SandboxPolicyCapability, SandboxReclaimFailedError, SandboxSnapshotError, ToolBridgeProvisionerCapability, UnsupportedCapabilityError, agentSkill, alignToStoredLog, alignedIfAttaching, approvalId, awaitAttachableJournal, bearer, bootstrapWorkspace, buildApprovalRequestedEvent, chunkFingerprint, chunkFingerprintIgnoringThreadId, chunkThreadId, commandAliases, computeSandboxKey, computeWorkspaceHash, createBridgeEventChannel, createExecBackedGit, createRunScopedIdGen, createSandboxSnapshots, createSecrets, createSnapshotTools, createToolBridgeCore, decodeBase64Stream, decodeJournalRunId, defaultSandboxSnapshotPolicy, defineSandbox, defineSandboxCheckpointStore, defineSandboxInstanceStore, defineSandboxPolicy, defineWorkspace, detectPackageManager, diffSnapshots, discoverSkillDirs, encodeRunId, evaluateCommand, executeHostTool, exitSentinelLine, fileSkill, formatWorkspaceScriptsSection, getSandbox, getSandboxDurability, getSandboxInstanceStore, getSandboxPolicy, getToolBridgeProvisioner, getWorkspaceProjection, gitSkill, gitSource, githubRepo, handleBridgeJsonRpc, hostForSandbox, httpRemoteToolExecutor, isBridgeCustomChunk, isForkCapableSandboxCheckpointStore, isSandboxToolCall, isSecretRef, isToolExecRequest, journalExistsCommand, journalExitProbeCommand, journalFollowCommand, journalListCommand, journalMtimeListCommand, journalOptionsFor, journalPaths, journalReadCommand, journalReadStrategy, journaledCommand, localSource, mcpSkill, memorySandboxSnapshots, mergeAgentsContent, mergeChunkStreams, nodeHttpBridgeProvisioner, parseExitSentinel, parseJournalExit, parseJournalMtimeListing, pipeToRunLog, probeRunExit, provideSandbox, provideSandboxDurability, provideSandboxInstanceStore, provideSandboxPolicy, provideToolBridgeProvisioner, provideWorkspaceProjection, pruneJournals, readJournal, readJournalNdjson, reapDetachedRuns, reclaimSandbox, remoteToolStubs, resolveAllSecrets, resolveApproval, resolveBearer, resolveDurableRunId, resolveDurableThreadId, resolveGitSkillDir, resolveHarnessCwd, resolveSecret, sandboxReclaimer, sandboxRunDriver, spawnNdjson, startHostToolBridge, startJournaledAgent, timingSafeBearerEqual, toJournalLines, toLines, toolDescriptors, watchWorkspace, withSandbox, writeAgentsFile };

package/dist/esm/memory-snapshot-types.d.ts

@@ -0,0 +1,129 @@
+import { ModelMessage, RunRecord, RunStatus, RunStore, PersistedArtifactRef, TokenUsage } from '@tanstack/ai';
+export interface MemoryMessageStore {
+    loadThread: (threadId: string) => Promise<Array<ModelMessage>>;
+    saveThread: (threadId: string, messages: Array<ModelMessage>) => Promise<void>;
+}
+export type MemoryRunRecord = RunRecord;
+export type MemoryRunStore = RunStore;
+export interface MemoryGenerationRunRecord {
+    runId: string;
+    threadId: string;
+    activity: string;
+    provider: string;
+    model: string;
+    status: RunStatus;
+    startedAt: number;
+    finishedAt?: number;
+    error?: {
+        message: string;
+        code?: string;
+    };
+    result?: unknown;
+    artifacts?: Array<PersistedArtifactRef>;
+    usage?: TokenUsage;
+}
+export interface MemoryGenerationRunStore {
+    createOrResume: (input: Pick<MemoryGenerationRunRecord, 'runId' | 'threadId' | 'activity' | 'provider' | 'model' | 'startedAt'> & {
+        status?: RunStatus;
+    }) => Promise<MemoryGenerationRunRecord>;
+    update: (runId: string, patch: Partial<Pick<MemoryGenerationRunRecord, 'status' | 'finishedAt' | 'error' | 'result' | 'artifacts' | 'usage'>>) => Promise<void>;
+    get: (runId: string) => Promise<MemoryGenerationRunRecord | null>;
+    findLatestForThread: (threadId: string) => Promise<MemoryGenerationRunRecord | null>;
+}
+export interface MemoryInterruptRecord {
+    interruptId: string;
+    runId: string;
+    threadId: string;
+    status: 'pending' | 'resolved' | 'cancelled';
+    requestedAt: number;
+    resolvedAt?: number;
+    payload: Record<string, unknown>;
+    response?: unknown;
+}
+export interface MemoryInterruptStore {
+    create: (record: Omit<MemoryInterruptRecord, 'status' | 'resolvedAt'>) => Promise<void>;
+    resolve: (interruptId: string, response?: unknown) => Promise<void>;
+    cancel: (interruptId: string) => Promise<void>;
+    get: (interruptId: string) => Promise<MemoryInterruptRecord | null>;
+    list: (threadId: string) => Promise<Array<MemoryInterruptRecord>>;
+    listPending: (threadId: string) => Promise<Array<MemoryInterruptRecord>>;
+    listByRun: (runId: string) => Promise<Array<MemoryInterruptRecord>>;
+    listPendingByRun: (runId: string) => Promise<Array<MemoryInterruptRecord>>;
+}
+export interface MemoryMetadataStore {
+    get: (namespace: string, key: string) => Promise<unknown | null>;
+    set: (namespace: string, key: string, value: unknown) => Promise<void>;
+    delete: (namespace: string, key: string) => Promise<void>;
+}
+export interface MemoryArtifactRecord {
+    artifactId: string;
+    runId: string;
+    threadId: string;
+    blobKey?: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    sourceUrl?: string;
+    createdAt: number;
+}
+export interface MemoryArtifactStore {
+    save: (record: MemoryArtifactRecord) => Promise<void>;
+    get: (artifactId: string) => Promise<MemoryArtifactRecord | null>;
+    list: (runId: string) => Promise<Array<MemoryArtifactRecord>>;
+    listForThread: (threadId: string) => Promise<Array<MemoryArtifactRecord>>;
+    delete: (artifactId: string) => Promise<void>;
+    deleteForRun: (runId: string) => Promise<void>;
+}
+export type MemoryBlobBody = ReadableStream<Uint8Array> | ArrayBuffer | ArrayBufferView | string | Blob;
+export interface MemoryBlobRecord {
+    key: string;
+    size?: number;
+    etag?: string;
+    contentType?: string;
+    customMetadata?: Record<string, string>;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export interface MemoryBlobStore {
+    put: (key: string, body: MemoryBlobBody, options?: {
+        contentType?: string;
+        customMetadata?: Record<string, string>;
+        expectedLength?: number;
+    }) => Promise<MemoryBlobRecord>;
+    get: (key: string, options?: {
+        range?: {
+            offset: number;
+            length?: number;
+        };
+    }) => Promise<(MemoryBlobRecord & {
+        arrayBuffer: () => Promise<ArrayBuffer>;
+        text: () => Promise<string>;
+        body?: ReadableStream<Uint8Array>;
+        range?: {
+            offset: number;
+            length: number;
+        };
+    }) | null>;
+    head: (key: string) => Promise<MemoryBlobRecord | null>;
+    delete: (key: string) => Promise<void>;
+    list: (options?: {
+        prefix?: string;
+        cursor?: string;
+        limit?: number;
+    }) => Promise<{
+        objects: Array<MemoryBlobRecord>;
+        cursor?: string;
+        truncated?: boolean;
+    }>;
+}
+export interface MemorySnapshotPersistence {
+    stores: {
+        messages: MemoryMessageStore;
+        runs: MemoryRunStore;
+        generationRuns: MemoryGenerationRunStore;
+        interrupts: MemoryInterruptStore;
+        metadata: MemoryMetadataStore;
+        artifacts: MemoryArtifactStore;
+        blobs: MemoryBlobStore;
+    };
+}

package/dist/esm/memory-snapshots.d.ts

@@ -0,0 +1,6 @@
+import { MemorySnapshotPersistence } from './memory-snapshot-types.js';
+import { ForkCapableSandboxCheckpointStore } from './checkpoint-store.js';
+import { CreateSandboxSnapshotsInput, SandboxSnapshots } from './snapshot-operations.js';
+export type MemorySandboxSnapshots = SandboxSnapshots<MemorySnapshotPersistence, ForkCapableSandboxCheckpointStore>;
+export type MemorySandboxSnapshotsOptions = Omit<CreateSandboxSnapshotsInput<MemorySnapshotPersistence, ForkCapableSandboxCheckpointStore>, 'persistence' | 'checkpoints'>;
+export declare function memorySandboxSnapshots(options?: MemorySandboxSnapshotsOptions): Promise<MemorySandboxSnapshots>;