@tanstack/ai-sandbox 0.3.4 → 0.5.0

package/dist/esm/testkit/checkpoint-fork-conformance.js

@@ -0,0 +1,191 @@
+import { InMemorySandboxCheckpointStore } from "../checkpoint-store.js";
+import { describe, expect, it } from "vitest";
+//#region src/testkit/checkpoint-fork-conformance.ts
+function sourceCheckpoint() {
+	return {
+		id: "source-root",
+		threadId: "source",
+		parentCheckpointId: null,
+		createdAt: 10,
+		reason: "named",
+		label: "source label",
+		sourceRunId: "run-1",
+		files: [{
+			path: "a.txt",
+			kind: "file",
+			blobKey: `sandbox-files/sha256/${"a".repeat(64)}`,
+			size: 1
+		}],
+		conversation: [{
+			role: "user",
+			content: "checkpoint conversation"
+		}],
+		artifacts: []
+	};
+}
+async function appendSource(checkpoints) {
+	const sourceWriter = await checkpoints.acquireWriter("source");
+	const source = sourceCheckpoint();
+	await checkpoints.append({
+		checkpoint: source,
+		expectedHeadId: null,
+		writer: sourceWriter
+	});
+	return {
+		source,
+		sourceWriter
+	};
+}
+function forkInput(writer, overrides = {}) {
+	return {
+		sourceThreadId: "source",
+		sourceCheckpointId: "source-root",
+		destinationThreadId: "destination",
+		destinationCheckpointId: "fork-root",
+		createdAt: 20,
+		writer,
+		...overrides
+	};
+}
+async function destinationState(persistence, checkpoints) {
+	return {
+		transcript: await persistence.stores.messages.loadThread("destination"),
+		head: await checkpoints.getHead("destination"),
+		checkpoints: await checkpoints.list("destination"),
+		references: await checkpoints.listBlobReferences()
+	};
+}
+async function expectRejectedWithoutDestinationChanges(persistence, checkpoints, operation, code) {
+	const before = await destinationState(persistence, checkpoints);
+	await expect(operation).rejects.toMatchObject({ code });
+	expect(await destinationState(persistence, checkpoints)).toEqual(before);
+}
+function runSandboxCheckpointForkConformance(name, makeSnapshots) {
+	describe(`Sandbox checkpoint fork conformance: ${name}`, () => {
+		it("copies a selected historical checkpoint and creates an exact fork root", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			const { source, sourceWriter } = await appendSource(checkpoints);
+			await checkpoints.append({
+				checkpoint: {
+					id: "source-head",
+					threadId: "source",
+					parentCheckpointId: source.id,
+					createdAt: 11,
+					reason: "automatic",
+					files: [],
+					conversation: [{
+						role: "user",
+						content: "newer conversation"
+					}],
+					artifacts: []
+				},
+				expectedHeadId: source.id,
+				writer: sourceWriter
+			});
+			await persistence.stores.messages.saveThread("source", [{
+				role: "user",
+				content: "current source message"
+			}]);
+			const destinationWriter = await checkpoints.acquireWriter("destination");
+			const result = await checkpoints.forkFromCheckpoint(forkInput(destinationWriter));
+			expect(result.checkpoint).toEqual({
+				id: "fork-root",
+				threadId: "destination",
+				parentCheckpointId: null,
+				createdAt: 20,
+				reason: "fork-root",
+				files: source.files,
+				conversation: source.conversation,
+				artifacts: []
+			});
+			expect(await persistence.stores.messages.loadThread("destination")).toEqual(source.conversation);
+			expect(await checkpoints.getHead("source")).toBe("source-head");
+		});
+		it("rejects a plain checkpoint store because it has no fork capability", () => {
+			const store = new InMemorySandboxCheckpointStore();
+			expect("forkFromCheckpoint" in store).toBe(false);
+		});
+		it("rejects a missing source without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			const writer = await checkpoints.acquireWriter("destination");
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(writer, { sourceCheckpointId: "missing" })), "SANDBOX_SNAPSHOT_FORK_SOURCE_NOT_FOUND");
+		});
+		it("rejects a source thread mismatch without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			await appendSource(checkpoints);
+			const writer = await checkpoints.acquireWriter("destination");
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(writer, { sourceThreadId: "another-source" })), "SANDBOX_SNAPSHOT_FORK_SOURCE_THREAD_MISMATCH");
+		});
+		it("rejects equal source and destination threads without changing the source", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			const { source, sourceWriter } = await appendSource(checkpoints);
+			const before = {
+				transcript: await persistence.stores.messages.loadThread("source"),
+				head: await checkpoints.getHead("source"),
+				checkpoints: await checkpoints.list("source"),
+				references: await checkpoints.listBlobReferences()
+			};
+			await expect(checkpoints.forkFromCheckpoint(forkInput(sourceWriter, { destinationThreadId: source.threadId }))).rejects.toMatchObject({ code: "SANDBOX_SNAPSHOT_FORK_SOURCE_THREAD_MISMATCH" });
+			expect({
+				transcript: await persistence.stores.messages.loadThread("source"),
+				head: await checkpoints.getHead("source"),
+				checkpoints: await checkpoints.list("source"),
+				references: await checkpoints.listBlobReferences()
+			}).toEqual(before);
+		});
+		it("rejects a missing destination writer without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			await appendSource(checkpoints);
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput({
+				threadId: "destination",
+				ownerToken: "missing-owner",
+				fence: 1
+			})), "SANDBOX_SNAPSHOT_WRITER_LOST");
+		});
+		it("rejects a wrong destination writer without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			await appendSource(checkpoints);
+			const wrongWriter = await checkpoints.acquireWriter("another-thread");
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(wrongWriter)), "SANDBOX_SNAPSHOT_WRITER_LOST");
+		});
+		it("rejects a stale destination writer without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			await appendSource(checkpoints);
+			const staleWriter = await checkpoints.acquireWriter("destination");
+			await staleWriter.release();
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(staleWriter)), "SANDBOX_SNAPSHOT_WRITER_LOST");
+		});
+		it("rejects a destination transcript without changing its checkpoint state", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			await appendSource(checkpoints);
+			await persistence.stores.messages.saveThread("destination", [{
+				role: "user",
+				content: "already here"
+			}]);
+			const writer = await checkpoints.acquireWriter("destination");
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(writer)), "SANDBOX_SNAPSHOT_FORK_DESTINATION_NOT_EMPTY");
+		});
+		it("rejects an orphaned checkpoint id without changing the destination", async () => {
+			const { persistence, checkpoints } = await makeSnapshots();
+			const { source } = await appendSource(checkpoints);
+			const orphanWriter = await checkpoints.acquireWriter("orphan-thread");
+			await checkpoints.append({
+				checkpoint: {
+					...source,
+					id: "orphaned-id",
+					threadId: "orphan-thread",
+					parentCheckpointId: null,
+					createdAt: 11
+				},
+				expectedHeadId: null,
+				writer: orphanWriter
+			});
+			const destinationWriter = await checkpoints.acquireWriter("destination");
+			await expectRejectedWithoutDestinationChanges(persistence, checkpoints, checkpoints.forkFromCheckpoint(forkInput(destinationWriter, { destinationCheckpointId: "orphaned-id" })), "SANDBOX_SNAPSHOT_FORK_DESTINATION_NOT_EMPTY");
+		});
+	});
+}
+//#endregion
+export { runSandboxCheckpointForkConformance };
+
+//# sourceMappingURL=checkpoint-fork-conformance.js.map

package/dist/esm/testkit/checkpoint-fork-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-fork-conformance.js","names":[],"sources":["../../../src/testkit/checkpoint-fork-conformance.ts"],"sourcesContent":["import { describe, expect, it } from 'vitest'\nimport type { ModelMessage } from '@tanstack/ai'\nimport type {\n  ForkCapableSandboxCheckpointStore,\n  SandboxCheckpoint,\n  SandboxCheckpointForkInput,\n  SandboxCheckpointWriter,\n  SandboxCheckpointWriterLease,\n} from '../checkpoint-store'\nimport { InMemorySandboxCheckpointStore } from '../checkpoint-store'\n\n/** Combined stores required to exercise an atomic checkpoint fork. */\nexport interface SandboxCheckpointForkConformanceInput {\n  persistence: {\n    stores: {\n      messages: {\n        loadThread: (threadId: string) => Promise<Array<ModelMessage>>\n        saveThread: (\n          threadId: string,\n          messages: Array<ModelMessage>,\n        ) => Promise<void>\n      }\n    }\n  }\n  checkpoints: ForkCapableSandboxCheckpointStore\n}\n\nexport interface SandboxCheckpointForkConformanceFactory {\n  ():\n    | SandboxCheckpointForkConformanceInput\n    | Promise<SandboxCheckpointForkConformanceInput>\n}\n\ntype ForkInputWithoutWriter = Omit<SandboxCheckpointForkInput, 'writer'>\n\nfunction sourceCheckpoint(): SandboxCheckpoint {\n  return {\n    id: 'source-root',\n    threadId: 'source',\n    parentCheckpointId: null,\n    createdAt: 10,\n    reason: 'named',\n    label: 'source label',\n    sourceRunId: 'run-1',\n    files: [\n      {\n        path: 'a.txt',\n        kind: 'file',\n        blobKey: `sandbox-files/sha256/${'a'.repeat(64)}`,\n        size: 1,\n      },\n    ],\n    conversation: [{ role: 'user', content: 'checkpoint conversation' }],\n    artifacts: [],\n  }\n}\n\nasync function appendSource(\n  checkpoints: ForkCapableSandboxCheckpointStore,\n): Promise<{\n  source: SandboxCheckpoint\n  sourceWriter: SandboxCheckpointWriterLease\n}> {\n  const sourceWriter = await checkpoints.acquireWriter('source')\n  const source = sourceCheckpoint()\n  await checkpoints.append({\n    checkpoint: source,\n    expectedHeadId: null,\n    writer: sourceWriter,\n  })\n  return { source, sourceWriter }\n}\n\nfunction forkInput(\n  writer: SandboxCheckpointWriter,\n  overrides: Partial<ForkInputWithoutWriter> = {},\n): SandboxCheckpointForkInput {\n  return {\n    sourceThreadId: 'source',\n    sourceCheckpointId: 'source-root',\n    destinationThreadId: 'destination',\n    destinationCheckpointId: 'fork-root',\n    createdAt: 20,\n    writer,\n    ...overrides,\n  }\n}\n\nasync function destinationState(\n  persistence: SandboxCheckpointForkConformanceInput['persistence'],\n  checkpoints: ForkCapableSandboxCheckpointStore,\n) {\n  return {\n    transcript: await persistence.stores.messages.loadThread('destination'),\n    head: await checkpoints.getHead('destination'),\n    checkpoints: await checkpoints.list('destination'),\n    references: await checkpoints.listBlobReferences(),\n  }\n}\n\nasync function expectRejectedWithoutDestinationChanges(\n  persistence: SandboxCheckpointForkConformanceInput['persistence'],\n  checkpoints: ForkCapableSandboxCheckpointStore,\n  operation: Promise<unknown>,\n  code: string,\n): Promise<void> {\n  const before = await destinationState(persistence, checkpoints)\n  await expect(operation).rejects.toMatchObject({ code })\n  expect(await destinationState(persistence, checkpoints)).toEqual(before)\n}\n\nexport function runSandboxCheckpointForkConformance(\n  name: string,\n  makeSnapshots: SandboxCheckpointForkConformanceFactory,\n): void {\n  describe(`Sandbox checkpoint fork conformance: ${name}`, () => {\n    it('copies a selected historical checkpoint and creates an exact fork root', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      const { source, sourceWriter } = await appendSource(checkpoints)\n      await checkpoints.append({\n        checkpoint: {\n          id: 'source-head',\n          threadId: 'source',\n          parentCheckpointId: source.id,\n          createdAt: 11,\n          reason: 'automatic',\n          files: [],\n          conversation: [{ role: 'user', content: 'newer conversation' }],\n          artifacts: [],\n        },\n        expectedHeadId: source.id,\n        writer: sourceWriter,\n      })\n      await persistence.stores.messages.saveThread('source', [\n        { role: 'user', content: 'current source message' },\n      ])\n      const destinationWriter = await checkpoints.acquireWriter('destination')\n      const result = await checkpoints.forkFromCheckpoint(\n        forkInput(destinationWriter),\n      )\n      expect(result.checkpoint).toEqual({\n        id: 'fork-root',\n        threadId: 'destination',\n        parentCheckpointId: null,\n        createdAt: 20,\n        reason: 'fork-root',\n        files: source.files,\n        conversation: source.conversation,\n        artifacts: [],\n      })\n      expect(\n        await persistence.stores.messages.loadThread('destination'),\n      ).toEqual(source.conversation)\n      expect(await checkpoints.getHead('source')).toBe('source-head')\n    })\n\n    it('rejects a plain checkpoint store because it has no fork capability', () => {\n      const store = new InMemorySandboxCheckpointStore()\n      expect('forkFromCheckpoint' in store).toBe(false)\n    })\n\n    it('rejects a missing source without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      const writer = await checkpoints.acquireWriter('destination')\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(\n          forkInput(writer, { sourceCheckpointId: 'missing' }),\n        ),\n        'SANDBOX_SNAPSHOT_FORK_SOURCE_NOT_FOUND',\n      )\n    })\n\n    it('rejects a source thread mismatch without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      await appendSource(checkpoints)\n      const writer = await checkpoints.acquireWriter('destination')\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(\n          forkInput(writer, { sourceThreadId: 'another-source' }),\n        ),\n        'SANDBOX_SNAPSHOT_FORK_SOURCE_THREAD_MISMATCH',\n      )\n    })\n\n    it('rejects equal source and destination threads without changing the source', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      const { source, sourceWriter } = await appendSource(checkpoints)\n      const before = {\n        transcript: await persistence.stores.messages.loadThread('source'),\n        head: await checkpoints.getHead('source'),\n        checkpoints: await checkpoints.list('source'),\n        references: await checkpoints.listBlobReferences(),\n      }\n      await expect(\n        checkpoints.forkFromCheckpoint(\n          forkInput(sourceWriter, {\n            destinationThreadId: source.threadId,\n          }),\n        ),\n      ).rejects.toMatchObject({\n        code: 'SANDBOX_SNAPSHOT_FORK_SOURCE_THREAD_MISMATCH',\n      })\n      expect({\n        transcript: await persistence.stores.messages.loadThread('source'),\n        head: await checkpoints.getHead('source'),\n        checkpoints: await checkpoints.list('source'),\n        references: await checkpoints.listBlobReferences(),\n      }).toEqual(before)\n    })\n\n    it('rejects a missing destination writer without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      await appendSource(checkpoints)\n      const missingWriter: SandboxCheckpointWriter = {\n        threadId: 'destination',\n        ownerToken: 'missing-owner',\n        fence: 1,\n      }\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(forkInput(missingWriter)),\n        'SANDBOX_SNAPSHOT_WRITER_LOST',\n      )\n    })\n\n    it('rejects a wrong destination writer without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      await appendSource(checkpoints)\n      const wrongWriter = await checkpoints.acquireWriter('another-thread')\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(forkInput(wrongWriter)),\n        'SANDBOX_SNAPSHOT_WRITER_LOST',\n      )\n    })\n\n    it('rejects a stale destination writer without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      await appendSource(checkpoints)\n      const staleWriter = await checkpoints.acquireWriter('destination')\n      await staleWriter.release()\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(forkInput(staleWriter)),\n        'SANDBOX_SNAPSHOT_WRITER_LOST',\n      )\n    })\n\n    it('rejects a destination transcript without changing its checkpoint state', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      await appendSource(checkpoints)\n      await persistence.stores.messages.saveThread('destination', [\n        { role: 'user', content: 'already here' },\n      ])\n      const writer = await checkpoints.acquireWriter('destination')\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(forkInput(writer)),\n        'SANDBOX_SNAPSHOT_FORK_DESTINATION_NOT_EMPTY',\n      )\n    })\n\n    it('rejects an orphaned checkpoint id without changing the destination', async () => {\n      const { persistence, checkpoints } = await makeSnapshots()\n      const { source } = await appendSource(checkpoints)\n      const orphanWriter = await checkpoints.acquireWriter('orphan-thread')\n      await checkpoints.append({\n        checkpoint: {\n          ...source,\n          id: 'orphaned-id',\n          threadId: 'orphan-thread',\n          parentCheckpointId: null,\n          createdAt: 11,\n        },\n        expectedHeadId: null,\n        writer: orphanWriter,\n      })\n      const destinationWriter = await checkpoints.acquireWriter('destination')\n      await expectRejectedWithoutDestinationChanges(\n        persistence,\n        checkpoints,\n        checkpoints.forkFromCheckpoint(\n          forkInput(destinationWriter, {\n            destinationCheckpointId: 'orphaned-id',\n          }),\n        ),\n        'SANDBOX_SNAPSHOT_FORK_DESTINATION_NOT_EMPTY',\n      )\n    })\n  })\n}\n"],"mappings":"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"}

package/dist/esm/testkit/conformance.d.ts

@@ -8,6 +8,10 @@ export type { ReaperConformanceConfig } from './reaper-conformance.js';
 export { runDurableRunFieldsConformance } from './durable-run-fields-conformance.js';
 export type { MakeRunStore } from './durable-run-fields-conformance.js';
 export { makeFakeShellSpawn } from './shell-spawn.js';
+export { runSandboxCheckpointStoreConformance } from './checkpoint-conformance.js';
+export type { SandboxCheckpointStoreOptions } from '../checkpoint-store.js';
+export { runSandboxCheckpointForkConformance } from './checkpoint-fork-conformance.js';
+export type { SandboxCheckpointForkConformanceInput, SandboxCheckpointForkConformanceFactory, } from './checkpoint-fork-conformance.js';
 /**
  * Assert `makeStore()` produces a spec-compliant {@link SandboxInstanceStore}. Each
  * `it` gets a fresh store, so implementations may share process state across

package/dist/esm/testkit/conformance.js

@@ -3,6 +3,8 @@ import { runTakeoverConformance } from "./takeover-conformance.js";
 import { runReaperConformance } from "./reaper-conformance.js";
 import { runDurableRunFieldsConformance } from "./durable-run-fields-conformance.js";
 import { makeFakeShellSpawn } from "./shell-spawn.js";
+import { runSandboxCheckpointStoreConformance } from "./checkpoint-conformance.js";
+import { runSandboxCheckpointForkConformance } from "./checkpoint-fork-conformance.js";
 import { describe, expect, it } from "vitest";
 //#region src/testkit/conformance.ts
 /**
@@ -94,6 +96,6 @@ function runSandboxInstanceStoreConformance(name, makeStore) {
 	});
 }
 //#endregion
-export { makeFakeShellSpawn, runDurableRunFieldsConformance, runJournalConformance, runReaperConformance, runSandboxInstanceStoreConformance, runTakeoverConformance };
+export { makeFakeShellSpawn, runDurableRunFieldsConformance, runJournalConformance, runReaperConformance, runSandboxCheckpointForkConformance, runSandboxCheckpointStoreConformance, runSandboxInstanceStoreConformance, runTakeoverConformance };
 
 //# sourceMappingURL=conformance.js.map

package/dist/esm/testkit/conformance.js.map

@@ -1 +1 @@
-{"version":3,"file":"conformance.js","names":[],"sources":["../../../src/testkit/conformance.ts"],"sourcesContent":["/**\n * Conformance suite for a {@link SandboxInstanceStore} implementation.\n *\n * Run this against a fresh BYO store (or the in-memory reference) to prove it\n * satisfies the get / upsert / delete contract `@tanstack/ai-sandbox`'s ensure\n * algorithm relies on — including insert-vs-overwrite and optional-field\n * handling (full replace must clear omitted optionals).\n *\n * Vitest is an OPTIONAL peer dependency: this module is imported only from test\n * files, which already run under Vitest.\n */\nimport { describe, expect, it } from 'vitest'\nimport type {\n  SandboxInstanceRecord,\n  SandboxInstanceStore,\n} from '../instance-store'\n\n// The `./testkit` package.json subpath resolves to THIS module's build output\n// only (`dist/esm/testkit/conformance.js`), not a barrel over `src/testkit/`.\n// Re-export the journal, takeover, and reaper conformance suites here so they\n// are reachable from `@tanstack/ai-sandbox/testkit` without changing that\n// mapping.\nexport { runJournalConformance } from './journal-conformance'\nexport type { JournalConformanceConfig } from './journal-conformance'\nexport { runTakeoverConformance } from './takeover-conformance'\nexport type { TakeoverConformanceConfig } from './takeover-conformance'\nexport { runReaperConformance } from './reaper-conformance'\nexport type { ReaperConformanceConfig } from './reaper-conformance'\nexport { runDurableRunFieldsConformance } from './durable-run-fields-conformance'\nexport type { MakeRunStore } from './durable-run-fields-conformance'\nexport { makeFakeShellSpawn } from './shell-spawn'\n\nfunction makeRecord(\n  overrides?: Partial<SandboxInstanceRecord>,\n): SandboxInstanceRecord {\n  return {\n    key: 'thread-1',\n    provider: 'fake',\n    providerSandboxId: 'sb-1',\n    threadId: 'thread-1',\n    updatedAt: 1,\n    ...overrides,\n  }\n}\n\n/**\n * Assert `makeStore()` produces a spec-compliant {@link SandboxInstanceStore}. Each\n * `it` gets a fresh store, so implementations may share process state across\n * calls without cross-test bleed only if `makeStore` returns an isolated store.\n */\nexport function runSandboxInstanceStoreConformance(\n  name: string,\n  makeStore: () => SandboxInstanceStore | Promise<SandboxInstanceStore>,\n): void {\n  describe(`SandboxInstanceStore conformance: ${name}`, () => {\n    it('returns null for a missing key', async () => {\n      const store = await makeStore()\n      expect(await store.get('absent')).toBeNull()\n    })\n\n    it('round-trips an upserted record with all fields', async () => {\n      const store = await makeStore()\n      const record = makeRecord({\n        latestSnapshotId: 'snap-1',\n        latestRunId: 'run-1',\n      })\n      await store.upsert(record)\n      expect(await store.get(record.key)).toEqual(record)\n    })\n\n    it('omits absent optional fields on read', async () => {\n      const store = await makeStore()\n      const record = makeRecord()\n      await store.upsert(record)\n      const loaded = await store.get(record.key)\n      expect(loaded).toEqual(record)\n      expect(loaded && 'latestSnapshotId' in loaded).toBe(false)\n      expect(loaded && 'latestRunId' in loaded).toBe(false)\n    })\n\n    it('overwrites an existing record on re-upsert', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord({ latestSnapshotId: 'snap-1' }))\n      await store.upsert(\n        makeRecord({ providerSandboxId: 'sb-2', updatedAt: 2 }),\n      )\n      const loaded = await store.get('thread-1')\n      expect(loaded?.providerSandboxId).toBe('sb-2')\n      expect(loaded?.updatedAt).toBe(2)\n      // The overwrite dropped latestSnapshotId — a durable store must clear it,\n      // not retain the prior value.\n      expect(loaded && 'latestSnapshotId' in loaded).toBe(false)\n    })\n\n    it('isolates records by key', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord({ key: 'a', threadId: 'a' }))\n      await store.upsert(\n        makeRecord({ key: 'b', threadId: 'b', providerSandboxId: 'sb-b' }),\n      )\n      expect((await store.get('a'))?.providerSandboxId).toBe('sb-1')\n      expect((await store.get('b'))?.providerSandboxId).toBe('sb-b')\n    })\n\n    it('deletes a record', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord())\n      await store.delete('thread-1')\n      expect(await store.get('thread-1')).toBeNull()\n    })\n\n    it('delete of a missing key is a no-op', async () => {\n      const store = await makeStore()\n      await expect(store.delete('absent')).resolves.toBeUndefined()\n    })\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAgCA,SAAS,WACP,WACuB;CACvB,OAAO;EACL,KAAK;EACL,UAAU;EACV,mBAAmB;EACnB,UAAU;EACV,WAAW;EACX,GAAG;CACL;AACF;;;;;;AAOA,SAAgB,mCACd,MACA,WACM;CACN,SAAS,qCAAqC,cAAc;EAC1D,GAAG,kCAAkC,YAAY;GAC/C,MAAM,QAAQ,MAAM,UAAU;GAC9B,OAAO,MAAM,MAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,SAAS;EAC7C,CAAC;EAED,GAAG,kDAAkD,YAAY;GAC/D,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,SAAS,WAAW;IACxB,kBAAkB;IAClB,aAAa;GACf,CAAC;GACD,MAAM,MAAM,OAAO,MAAM;GACzB,OAAO,MAAM,MAAM,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,QAAQ,MAAM;EACpD,CAAC;EAED,GAAG,wCAAwC,YAAY;GACrD,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,SAAS,WAAW;GAC1B,MAAM,MAAM,OAAO,MAAM;GACzB,MAAM,SAAS,MAAM,MAAM,IAAI,OAAO,GAAG;GACzC,OAAO,MAAM,CAAC,CAAC,QAAQ,MAAM;GAC7B,OAAO,UAAU,sBAAsB,MAAM,CAAC,CAAC,KAAK,KAAK;GACzD,OAAO,UAAU,iBAAiB,MAAM,CAAC,CAAC,KAAK,KAAK;EACtD,CAAC;EAED,GAAG,8CAA8C,YAAY;GAC3D,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW,EAAE,kBAAkB,SAAS,CAAC,CAAC;GAC7D,MAAM,MAAM,OACV,WAAW;IAAE,mBAAmB;IAAQ,WAAW;GAAE,CAAC,CACxD;GACA,MAAM,SAAS,MAAM,MAAM,IAAI,UAAU;GACzC,OAAO,QAAQ,iBAAiB,CAAC,CAAC,KAAK,MAAM;GAC7C,OAAO,QAAQ,SAAS,CAAC,CAAC,KAAK,CAAC;GAGhC,OAAO,UAAU,sBAAsB,MAAM,CAAC,CAAC,KAAK,KAAK;EAC3D,CAAC;EAED,GAAG,2BAA2B,YAAY;GACxC,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW;IAAE,KAAK;IAAK,UAAU;GAAI,CAAC,CAAC;GAC1D,MAAM,MAAM,OACV,WAAW;IAAE,KAAK;IAAK,UAAU;IAAK,mBAAmB;GAAO,CAAC,CACnE;GACA,QAAQ,MAAM,MAAM,IAAI,GAAG,EAAA,EAAI,iBAAiB,CAAC,CAAC,KAAK,MAAM;GAC7D,QAAQ,MAAM,MAAM,IAAI,GAAG,EAAA,EAAI,iBAAiB,CAAC,CAAC,KAAK,MAAM;EAC/D,CAAC;EAED,GAAG,oBAAoB,YAAY;GACjC,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW,CAAC;GAC/B,MAAM,MAAM,OAAO,UAAU;GAC7B,OAAO,MAAM,MAAM,IAAI,UAAU,CAAC,CAAC,CAAC,SAAS;EAC/C,CAAC;EAED,GAAG,sCAAsC,YAAY;GACnD,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,OAAO,MAAM,OAAO,QAAQ,CAAC,CAAC,CAAC,SAAS,cAAc;EAC9D,CAAC;CACH,CAAC;AACH"}
+{"version":3,"file":"conformance.js","names":[],"sources":["../../../src/testkit/conformance.ts"],"sourcesContent":["/**\n * Conformance suite for a {@link SandboxInstanceStore} implementation.\n *\n * Run this against a fresh BYO store (or the in-memory reference) to prove it\n * satisfies the get / upsert / delete contract `@tanstack/ai-sandbox`'s ensure\n * algorithm relies on — including insert-vs-overwrite and optional-field\n * handling (full replace must clear omitted optionals).\n *\n * Vitest is an OPTIONAL peer dependency: this module is imported only from test\n * files, which already run under Vitest.\n */\nimport { describe, expect, it } from 'vitest'\nimport type {\n  SandboxInstanceRecord,\n  SandboxInstanceStore,\n} from '../instance-store'\n\n// The `./testkit` package.json subpath resolves to THIS module's build output\n// only (`dist/esm/testkit/conformance.js`), not a barrel over `src/testkit/`.\n// Re-export the journal, takeover, and reaper conformance suites here so they\n// are reachable from `@tanstack/ai-sandbox/testkit` without changing that\n// mapping.\nexport { runJournalConformance } from './journal-conformance'\nexport type { JournalConformanceConfig } from './journal-conformance'\nexport { runTakeoverConformance } from './takeover-conformance'\nexport type { TakeoverConformanceConfig } from './takeover-conformance'\nexport { runReaperConformance } from './reaper-conformance'\nexport type { ReaperConformanceConfig } from './reaper-conformance'\nexport { runDurableRunFieldsConformance } from './durable-run-fields-conformance'\nexport type { MakeRunStore } from './durable-run-fields-conformance'\nexport { makeFakeShellSpawn } from './shell-spawn'\nexport { runSandboxCheckpointStoreConformance } from './checkpoint-conformance'\nexport type { SandboxCheckpointStoreOptions } from '../checkpoint-store'\nexport { runSandboxCheckpointForkConformance } from './checkpoint-fork-conformance'\nexport type {\n  SandboxCheckpointForkConformanceInput,\n  SandboxCheckpointForkConformanceFactory,\n} from './checkpoint-fork-conformance'\n\nfunction makeRecord(\n  overrides?: Partial<SandboxInstanceRecord>,\n): SandboxInstanceRecord {\n  return {\n    key: 'thread-1',\n    provider: 'fake',\n    providerSandboxId: 'sb-1',\n    threadId: 'thread-1',\n    updatedAt: 1,\n    ...overrides,\n  }\n}\n\n/**\n * Assert `makeStore()` produces a spec-compliant {@link SandboxInstanceStore}. Each\n * `it` gets a fresh store, so implementations may share process state across\n * calls without cross-test bleed only if `makeStore` returns an isolated store.\n */\nexport function runSandboxInstanceStoreConformance(\n  name: string,\n  makeStore: () => SandboxInstanceStore | Promise<SandboxInstanceStore>,\n): void {\n  describe(`SandboxInstanceStore conformance: ${name}`, () => {\n    it('returns null for a missing key', async () => {\n      const store = await makeStore()\n      expect(await store.get('absent')).toBeNull()\n    })\n\n    it('round-trips an upserted record with all fields', async () => {\n      const store = await makeStore()\n      const record = makeRecord({\n        latestSnapshotId: 'snap-1',\n        latestRunId: 'run-1',\n      })\n      await store.upsert(record)\n      expect(await store.get(record.key)).toEqual(record)\n    })\n\n    it('omits absent optional fields on read', async () => {\n      const store = await makeStore()\n      const record = makeRecord()\n      await store.upsert(record)\n      const loaded = await store.get(record.key)\n      expect(loaded).toEqual(record)\n      expect(loaded && 'latestSnapshotId' in loaded).toBe(false)\n      expect(loaded && 'latestRunId' in loaded).toBe(false)\n    })\n\n    it('overwrites an existing record on re-upsert', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord({ latestSnapshotId: 'snap-1' }))\n      await store.upsert(\n        makeRecord({ providerSandboxId: 'sb-2', updatedAt: 2 }),\n      )\n      const loaded = await store.get('thread-1')\n      expect(loaded?.providerSandboxId).toBe('sb-2')\n      expect(loaded?.updatedAt).toBe(2)\n      // The overwrite dropped latestSnapshotId — a durable store must clear it,\n      // not retain the prior value.\n      expect(loaded && 'latestSnapshotId' in loaded).toBe(false)\n    })\n\n    it('isolates records by key', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord({ key: 'a', threadId: 'a' }))\n      await store.upsert(\n        makeRecord({ key: 'b', threadId: 'b', providerSandboxId: 'sb-b' }),\n      )\n      expect((await store.get('a'))?.providerSandboxId).toBe('sb-1')\n      expect((await store.get('b'))?.providerSandboxId).toBe('sb-b')\n    })\n\n    it('deletes a record', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord())\n      await store.delete('thread-1')\n      expect(await store.get('thread-1')).toBeNull()\n    })\n\n    it('delete of a missing key is a no-op', async () => {\n      const store = await makeStore()\n      await expect(store.delete('absent')).resolves.toBeUndefined()\n    })\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAuCA,SAAS,WACP,WACuB;CACvB,OAAO;EACL,KAAK;EACL,UAAU;EACV,mBAAmB;EACnB,UAAU;EACV,WAAW;EACX,GAAG;CACL;AACF;;;;;;AAOA,SAAgB,mCACd,MACA,WACM;CACN,SAAS,qCAAqC,cAAc;EAC1D,GAAG,kCAAkC,YAAY;GAC/C,MAAM,QAAQ,MAAM,UAAU;GAC9B,OAAO,MAAM,MAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,SAAS;EAC7C,CAAC;EAED,GAAG,kDAAkD,YAAY;GAC/D,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,SAAS,WAAW;IACxB,kBAAkB;IAClB,aAAa;GACf,CAAC;GACD,MAAM,MAAM,OAAO,MAAM;GACzB,OAAO,MAAM,MAAM,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,QAAQ,MAAM;EACpD,CAAC;EAED,GAAG,wCAAwC,YAAY;GACrD,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,SAAS,WAAW;GAC1B,MAAM,MAAM,OAAO,MAAM;GACzB,MAAM,SAAS,MAAM,MAAM,IAAI,OAAO,GAAG;GACzC,OAAO,MAAM,CAAC,CAAC,QAAQ,MAAM;GAC7B,OAAO,UAAU,sBAAsB,MAAM,CAAC,CAAC,KAAK,KAAK;GACzD,OAAO,UAAU,iBAAiB,MAAM,CAAC,CAAC,KAAK,KAAK;EACtD,CAAC;EAED,GAAG,8CAA8C,YAAY;GAC3D,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW,EAAE,kBAAkB,SAAS,CAAC,CAAC;GAC7D,MAAM,MAAM,OACV,WAAW;IAAE,mBAAmB;IAAQ,WAAW;GAAE,CAAC,CACxD;GACA,MAAM,SAAS,MAAM,MAAM,IAAI,UAAU;GACzC,OAAO,QAAQ,iBAAiB,CAAC,CAAC,KAAK,MAAM;GAC7C,OAAO,QAAQ,SAAS,CAAC,CAAC,KAAK,CAAC;GAGhC,OAAO,UAAU,sBAAsB,MAAM,CAAC,CAAC,KAAK,KAAK;EAC3D,CAAC;EAED,GAAG,2BAA2B,YAAY;GACxC,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW;IAAE,KAAK;IAAK,UAAU;GAAI,CAAC,CAAC;GAC1D,MAAM,MAAM,OACV,WAAW;IAAE,KAAK;IAAK,UAAU;IAAK,mBAAmB;GAAO,CAAC,CACnE;GACA,QAAQ,MAAM,MAAM,IAAI,GAAG,EAAA,EAAI,iBAAiB,CAAC,CAAC,KAAK,MAAM;GAC7D,QAAQ,MAAM,MAAM,IAAI,GAAG,EAAA,EAAI,iBAAiB,CAAC,CAAC,KAAK,MAAM;EAC/D,CAAC;EAED,GAAG,oBAAoB,YAAY;GACjC,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW,CAAC;GAC/B,MAAM,MAAM,OAAO,UAAU;GAC7B,OAAO,MAAM,MAAM,IAAI,UAAU,CAAC,CAAC,CAAC,SAAS;EAC/C,CAAC;EAED,GAAG,sCAAsC,YAAY;GACnD,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,OAAO,MAAM,OAAO,QAAQ,CAAC,CAAC,CAAC,SAAS,cAAc;EAC9D,CAAC;CACH,CAAC;AACH"}

package/dist/esm/tool-history.js

@@ -96,7 +96,7 @@ function createToolHistoryRecorder() {
 	return {
 		observe(chunk, target) {
 			if (chunk.type === EventType.TOOL_CALL_START) {
-				const name = chunk.toolCallName ?? chunk.toolName;
+				const name = chunk.toolCallName;
 				if (!name) return;
 				open.set(chunk.toolCallId, {
 					name,
@@ -107,20 +107,19 @@ function createToolHistoryRecorder() {
 			if (chunk.type === EventType.TOOL_CALL_ARGS) {
 				const call = open.get(chunk.toolCallId);
 				if (!call) return;
-				call.args = chunk.args ?? call.args + chunk.delta;
+				call.args += chunk.delta;
 				return;
 			}
 			if (chunk.type === EventType.TOOL_CALL_END) {
 				const call = open.get(chunk.toolCallId);
 				if (!call) return;
 				open.delete(chunk.toolCallId);
-				const args = chunk.input !== void 0 ? JSON.stringify(chunk.input) : call.args;
 				recorded.push({
 					id: chunk.toolCallId,
 					name: call.name,
-					args
+					args: call.args
 				});
-				appendCall(target, chunk.toolCallId, call.name, args);
+				appendCall(target, chunk.toolCallId, call.name, call.args);
 				return;
 			}
 			if (chunk.type === EventType.TOOL_CALL_RESULT) {

package/dist/esm/tool-history.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-history.js","names":[],"sources":["../../src/tool-history.ts"],"sourcesContent":["/**\n * Turn a harness's PASSTHROUGH tool-call chunks into transcript messages, so a\n * finished run's tool cards survive a reload.\n *\n * Why this is needed at all: a harness executes its tools INSIDE the sandbox, so\n * `chat()` only relays its `TOOL_CALL_*` chunks — it never writes an assistant\n * message for them (`addAssistantToolCallMessage` is gated on the engine having\n * executed the tool itself). Chat persistence stores `ctx.messages`, so the whole\n * tool history existed only in the delivery log. Replaying that log is what makes\n * \"switch away and come back\" show everything; a FINISHED thread has no run to\n * rejoin, hydrates from the message store instead, and so came back as nothing but\n * the prompt and the final answer.\n *\n * Recording the calls as ordinary `toolCalls` + `role: 'tool'` messages needs no new\n * wire format and no client change: `modelMessagesToUIMessages` already merges a tool\n * result into the call it belongs to and marks the part complete, and\n * `reconstructChat` already runs that converter.\n */\nimport { EventType } from '@tanstack/ai'\nimport type { ModelMessage, StreamChunk } from '@tanstack/ai'\n\n/**\n * Metadata key set on every tool call recorded here.\n *\n * INTERNAL, and deliberately not exported: an app asks {@link isSandboxToolCall}\n * instead of knowing the key. Renaming it is a storage-visible change, because it ends\n * up inside stored `toolCalls[].metadata`, so the recorder test pins the literal.\n */\nconst SANDBOX_OBSERVED = 'sandboxObserved'\n\n/**\n * What the recorder writes into. `ChatMiddlewareContext.messages` is a\n * `ReadonlyArray`, so the transcript grows by REPLACING the array — the same way the\n * engine itself syncs `middlewareCtx.messages`.\n */\ninterface TranscriptTarget {\n  messages: ReadonlyArray<ModelMessage>\n}\n\ninterface OpenCall {\n  name: string\n  /** Accumulated `TOOL_CALL_ARGS` deltas; superseded by `input` when the adapter sends it. */\n  args: string\n}\n\nexport interface ToolHistoryRecorder {\n  /** Feed every chunk. Observes only — never transforms or drops. */\n  observe: (chunk: StreamChunk, target: TranscriptTarget) => void\n  /**\n   * Re-append anything missing from the transcript.\n   *\n   * The engine reassigns `middlewareCtx.messages` from its own array whenever it\n   * syncs config (once per agent iteration), which discards writes made during the\n   * previous iteration's stream. Reconciling at each iteration boundary and again at\n   * finish makes the result independent of that, and independent of where this\n   * middleware sits relative to persistence in the middleware array.\n   */\n  reconcile: (target: TranscriptTarget) => void\n}\n\n/**\n * True when this tool call was executed by the HARNESS inside the sandbox, and\n * recorded into the transcript for display, rather than executed by the agent loop.\n *\n * Use it to decide what your own `MessageStore` keeps — these calls are display\n * history, so dropping or capping them is safe (they are already stripped from the\n * request to the model on the next turn). Also works on a `tool-call` UI part, whose\n * `metadata` is copied straight from the model message.\n *\n * `metadata` is `unknown` on both, so the key can only be read behind a typeof/`in`\n * check; this mirrors the core `isProviderExecutedToolCall` convention.\n *\n * ```ts\n * import { isSandboxToolCall } from '@tanstack/ai-sandbox'\n *\n * const kept = messages.filter(\n *   (message) => !message.toolCalls?.every(isSandboxToolCall),\n * )\n * ```\n */\nexport function isSandboxToolCall(\n  toolCall: { metadata?: unknown } | null | undefined,\n): boolean {\n  const metadata = toolCall?.metadata\n  return (\n    typeof metadata === 'object' &&\n    metadata !== null &&\n    SANDBOX_OBSERVED in metadata &&\n    metadata[SANDBOX_OBSERVED] === true\n  )\n}\n\n/** Does the transcript already carry this tool call, from any source? */\nfunction hasCall(messages: ReadonlyArray<ModelMessage>, id: string): boolean {\n  return messages.some((message) =>\n    message.toolCalls?.some((call) => call.id === id),\n  )\n}\n\n/** Does the transcript already carry this tool result? */\nfunction hasResult(messages: ReadonlyArray<ModelMessage>, id: string): boolean {\n  return messages.some(\n    (message) => message.role === 'tool' && message.toolCallId === id,\n  )\n}\n\nfunction callMessage(id: string, name: string, args: string): ModelMessage {\n  return {\n    role: 'assistant',\n    content: null,\n    toolCalls: [\n      {\n        id,\n        type: 'function',\n        function: { name, arguments: args },\n        metadata: { [SANDBOX_OBSERVED]: true },\n      },\n    ],\n  }\n}\n\nfunction resultMessage(id: string, content: string): ModelMessage {\n  return { role: 'tool', toolCallId: id, content }\n}\n\nexport function createToolHistoryRecorder(): ToolHistoryRecorder {\n  const open = new Map<string, OpenCall>()\n  /** Completed calls in the order they ran — the order `reconcile` restores. */\n  const recorded: Array<{ id: string; name: string; args: string }> = []\n  const results = new Map<string, string>()\n\n  function appendCall(\n    target: TranscriptTarget,\n    id: string,\n    name: string,\n    args: string,\n  ): void {\n    // An id already present is either the engine's own (it executed the tool itself)\n    // or a chunk seen before — a journal replay on takeover re-emits the whole\n    // stream. Either way a second write would duplicate the card.\n    if (hasCall(target.messages, id)) return\n    target.messages = [...target.messages, callMessage(id, name, args)]\n  }\n\n  function appendResult(\n    target: TranscriptTarget,\n    id: string,\n    content: string,\n  ): void {\n    if (hasResult(target.messages, id)) return\n    target.messages = [...target.messages, resultMessage(id, content)]\n  }\n\n  const recorder: ToolHistoryRecorder = {\n    // An if/else chain rather than a `switch`: only four of the ~20 chunk types are\n    // interesting here, and a `switch` on `chunk.type` has to enumerate all of them\n    // to satisfy the exhaustiveness lint.\n    observe(chunk, target) {\n      if (chunk.type === EventType.TOOL_CALL_START) {\n        // `toolCallName` is the AG-UI field; `toolName` is its deprecated alias, and\n        // that alias is what several harness adapters still emit.\n        const name = chunk.toolCallName ?? chunk.toolName\n        if (!name) return\n        open.set(chunk.toolCallId, { name, args: '' })\n        return\n      }\n      if (chunk.type === EventType.TOOL_CALL_ARGS) {\n        const call = open.get(chunk.toolCallId)\n        if (!call) return\n        // `args` is the accumulated-so-far field. Prefer it over stitching deltas:\n        // an adapter that sends both would otherwise double the arguments.\n        call.args = chunk.args ?? call.args + chunk.delta\n        return\n      }\n      if (chunk.type === EventType.TOOL_CALL_END) {\n        const call = open.get(chunk.toolCallId)\n        if (!call) return\n        open.delete(chunk.toolCallId)\n        // `input` is the final PARSED input, so it beats the streamed string, which\n        // can be a truncated fragment if the arguments stream was cut short.\n        const args =\n          chunk.input !== undefined ? JSON.stringify(chunk.input) : call.args\n        recorded.push({ id: chunk.toolCallId, name: call.name, args })\n        appendCall(target, chunk.toolCallId, call.name, args)\n        return\n      }\n      if (chunk.type === EventType.TOOL_CALL_RESULT) {\n        // AG-UI types `content` as a string; anything else is not a result we can\n        // store as a `role: 'tool'` message.\n        if (typeof chunk.content !== 'string') return\n        results.set(chunk.toolCallId, chunk.content)\n        appendResult(target, chunk.toolCallId, chunk.content)\n      }\n    },\n\n    reconcile(target) {\n      for (const { id, name, args } of recorded) {\n        appendCall(target, id, name, args)\n        const result = results.get(id)\n        // The result goes straight after its own call, so a restored transcript reads\n        // in the order the tools actually ran.\n        if (result !== undefined) appendResult(target, id, result)\n      }\n    },\n  }\n  return recorder\n}\n\n/**\n * Drop recorded harness tool calls from a list of messages bound for the model.\n *\n * A stored transcript becomes the history for the NEXT turn. These calls name tools\n * the provider was never given, and one triage-sized run is hundreds of kilobytes of\n * tool output — so replaying them is wasteful at best and rejected at worst. They stay\n * in `ctx.messages` (which is what gets stored and rendered); only the request to the\n * model loses them.\n *\n * An assistant message is dropped only when EVERY call on it is observed, so a mixed\n * message — one engine tool call plus one harness tool call — is left alone rather than\n * silently losing the engine's half.\n */\nexport function stripObservedToolCalls(\n  messages: ReadonlyArray<ModelMessage>,\n): Array<ModelMessage> {\n  const dropped = new Set<string>()\n  const kept: Array<ModelMessage> = []\n  for (const message of messages) {\n    const calls = message.toolCalls\n    if (calls && calls.length > 0 && calls.every(isSandboxToolCall)) {\n      for (const call of calls) dropped.add(call.id)\n      continue\n    }\n    // Orphaning a result is worse than keeping it: a provider rejects a tool result\n    // whose call is not in the history.\n    if (\n      message.role === 'tool' &&\n      message.toolCallId !== undefined &&\n      dropped.has(message.toolCallId)\n    ) {\n      continue\n    }\n    kept.push(message)\n  }\n  return kept\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,IAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;AAoDzB,SAAgB,kBACd,UACS;CACT,MAAM,WAAW,UAAU;CAC3B,OACE,OAAO,aAAa,YACpB,aAAa,QACb,oBAAoB,YACpB,SAAS,sBAAsB;AAEnC;;AAGA,SAAS,QAAQ,UAAuC,IAAqB;CAC3E,OAAO,SAAS,MAAM,YACpB,QAAQ,WAAW,MAAM,SAAS,KAAK,OAAO,EAAE,CAClD;AACF;;AAGA,SAAS,UAAU,UAAuC,IAAqB;CAC7E,OAAO,SAAS,MACb,YAAY,QAAQ,SAAS,UAAU,QAAQ,eAAe,EACjE;AACF;AAEA,SAAS,YAAY,IAAY,MAAc,MAA4B;CACzE,OAAO;EACL,MAAM;EACN,SAAS;EACT,WAAW,CACT;GACE;GACA,MAAM;GACN,UAAU;IAAE;IAAM,WAAW;GAAK;GAClC,UAAU,GAAG,mBAAmB,KAAK;EACvC,CACF;CACF;AACF;AAEA,SAAS,cAAc,IAAY,SAA+B;CAChE,OAAO;EAAE,MAAM;EAAQ,YAAY;EAAI;CAAQ;AACjD;AAEA,SAAgB,4BAAiD;CAC/D,MAAM,uBAAO,IAAI,IAAsB;;CAEvC,MAAM,WAA8D,CAAC;CACrE,MAAM,0BAAU,IAAI,IAAoB;CAExC,SAAS,WACP,QACA,IACA,MACA,MACM;EAIN,IAAI,QAAQ,OAAO,UAAU,EAAE,GAAG;EAClC,OAAO,WAAW,CAAC,GAAG,OAAO,UAAU,YAAY,IAAI,MAAM,IAAI,CAAC;CACpE;CAEA,SAAS,aACP,QACA,IACA,SACM;EACN,IAAI,UAAU,OAAO,UAAU,EAAE,GAAG;EACpC,OAAO,WAAW,CAAC,GAAG,OAAO,UAAU,cAAc,IAAI,OAAO,CAAC;CACnE;CAsDA,OAAO;EAhDL,QAAQ,OAAO,QAAQ;GACrB,IAAI,MAAM,SAAS,UAAU,iBAAiB;IAG5C,MAAM,OAAO,MAAM,gBAAgB,MAAM;IACzC,IAAI,CAAC,MAAM;IACX,KAAK,IAAI,MAAM,YAAY;KAAE;KAAM,MAAM;IAAG,CAAC;IAC7C;GACF;GACA,IAAI,MAAM,SAAS,UAAU,gBAAgB;IAC3C,MAAM,OAAO,KAAK,IAAI,MAAM,UAAU;IACtC,IAAI,CAAC,MAAM;IAGX,KAAK,OAAO,MAAM,QAAQ,KAAK,OAAO,MAAM;IAC5C;GACF;GACA,IAAI,MAAM,SAAS,UAAU,eAAe;IAC1C,MAAM,OAAO,KAAK,IAAI,MAAM,UAAU;IACtC,IAAI,CAAC,MAAM;IACX,KAAK,OAAO,MAAM,UAAU;IAG5B,MAAM,OACJ,MAAM,UAAU,KAAA,IAAY,KAAK,UAAU,MAAM,KAAK,IAAI,KAAK;IACjE,SAAS,KAAK;KAAE,IAAI,MAAM;KAAY,MAAM,KAAK;KAAM;IAAK,CAAC;IAC7D,WAAW,QAAQ,MAAM,YAAY,KAAK,MAAM,IAAI;IACpD;GACF;GACA,IAAI,MAAM,SAAS,UAAU,kBAAkB;IAG7C,IAAI,OAAO,MAAM,YAAY,UAAU;IACvC,QAAQ,IAAI,MAAM,YAAY,MAAM,OAAO;IAC3C,aAAa,QAAQ,MAAM,YAAY,MAAM,OAAO;GACtD;EACF;EAEA,UAAU,QAAQ;GAChB,KAAK,MAAM,EAAE,IAAI,MAAM,UAAU,UAAU;IACzC,WAAW,QAAQ,IAAI,MAAM,IAAI;IACjC,MAAM,SAAS,QAAQ,IAAI,EAAE;IAG7B,IAAI,WAAW,KAAA,GAAW,aAAa,QAAQ,IAAI,MAAM;GAC3D;EACF;CAEK;AACT;;;;;;;;;;;;;;AAeA,SAAgB,uBACd,UACqB;CACrB,MAAM,0BAAU,IAAI,IAAY;CAChC,MAAM,OAA4B,CAAC;CACnC,KAAK,MAAM,WAAW,UAAU;EAC9B,MAAM,QAAQ,QAAQ;EACtB,IAAI,SAAS,MAAM,SAAS,KAAK,MAAM,MAAM,iBAAiB,GAAG;GAC/D,KAAK,MAAM,QAAQ,OAAO,QAAQ,IAAI,KAAK,EAAE;GAC7C;EACF;EAGA,IACE,QAAQ,SAAS,UACjB,QAAQ,eAAe,KAAA,KACvB,QAAQ,IAAI,QAAQ,UAAU,GAE9B;EAEF,KAAK,KAAK,OAAO;CACnB;CACA,OAAO;AACT"}
+{"version":3,"file":"tool-history.js","names":[],"sources":["../../src/tool-history.ts"],"sourcesContent":["/**\n * Turn a harness's PASSTHROUGH tool-call chunks into transcript messages, so a\n * finished run's tool cards survive a reload.\n *\n * Why this is needed at all: a harness executes its tools INSIDE the sandbox, so\n * `chat()` only relays its `TOOL_CALL_*` chunks — it never writes an assistant\n * message for them (`addAssistantToolCallMessage` is gated on the engine having\n * executed the tool itself). Chat persistence stores `ctx.messages`, so the whole\n * tool history existed only in the delivery log. Replaying that log is what makes\n * \"switch away and come back\" show everything; a FINISHED thread has no run to\n * rejoin, hydrates from the message store instead, and so came back as nothing but\n * the prompt and the final answer.\n *\n * Recording the calls as ordinary `toolCalls` + `role: 'tool'` messages needs no new\n * wire format and no client change: `modelMessagesToUIMessages` already merges a tool\n * result into the call it belongs to and marks the part complete, and\n * `reconstructChat` already runs that converter.\n */\nimport { EventType } from '@tanstack/ai'\nimport type { ModelMessage, StreamChunk } from '@tanstack/ai'\n\n/**\n * Metadata key set on every tool call recorded here.\n *\n * INTERNAL, and deliberately not exported: an app asks {@link isSandboxToolCall}\n * instead of knowing the key. Renaming it is a storage-visible change, because it ends\n * up inside stored `toolCalls[].metadata`, so the recorder test pins the literal.\n */\nconst SANDBOX_OBSERVED = 'sandboxObserved'\n\n/**\n * What the recorder writes into. `ChatMiddlewareContext.messages` is a\n * `ReadonlyArray`, so the transcript grows by REPLACING the array — the same way the\n * engine itself syncs `middlewareCtx.messages`.\n */\ninterface TranscriptTarget {\n  messages: ReadonlyArray<ModelMessage>\n}\n\ninterface OpenCall {\n  name: string\n  /** Accumulated `TOOL_CALL_ARGS` deltas. */\n  args: string\n}\n\nexport interface ToolHistoryRecorder {\n  /** Feed every chunk. Observes only — never transforms or drops. */\n  observe: (chunk: StreamChunk, target: TranscriptTarget) => void\n  /**\n   * Re-append anything missing from the transcript.\n   *\n   * The engine reassigns `middlewareCtx.messages` from its own array whenever it\n   * syncs config (once per agent iteration), which discards writes made during the\n   * previous iteration's stream. Reconciling at each iteration boundary and again at\n   * finish makes the result independent of that, and independent of where this\n   * middleware sits relative to persistence in the middleware array.\n   */\n  reconcile: (target: TranscriptTarget) => void\n}\n\n/**\n * True when this tool call was executed by the HARNESS inside the sandbox, and\n * recorded into the transcript for display, rather than executed by the agent loop.\n *\n * Use it to decide what your own `MessageStore` keeps — these calls are display\n * history, so dropping or capping them is safe (they are already stripped from the\n * request to the model on the next turn). Also works on a `tool-call` UI part, whose\n * `metadata` is copied straight from the model message.\n *\n * `metadata` is `unknown` on both, so the key can only be read behind a typeof/`in`\n * check; this mirrors the core `isProviderExecutedToolCall` convention.\n *\n * ```ts\n * import { isSandboxToolCall } from '@tanstack/ai-sandbox'\n *\n * const kept = messages.filter(\n *   (message) => !message.toolCalls?.every(isSandboxToolCall),\n * )\n * ```\n */\nexport function isSandboxToolCall(\n  toolCall: { metadata?: unknown } | null | undefined,\n): boolean {\n  const metadata = toolCall?.metadata\n  return (\n    typeof metadata === 'object' &&\n    metadata !== null &&\n    SANDBOX_OBSERVED in metadata &&\n    metadata[SANDBOX_OBSERVED] === true\n  )\n}\n\n/** Does the transcript already carry this tool call, from any source? */\nfunction hasCall(messages: ReadonlyArray<ModelMessage>, id: string): boolean {\n  return messages.some((message) =>\n    message.toolCalls?.some((call) => call.id === id),\n  )\n}\n\n/** Does the transcript already carry this tool result? */\nfunction hasResult(messages: ReadonlyArray<ModelMessage>, id: string): boolean {\n  return messages.some(\n    (message) => message.role === 'tool' && message.toolCallId === id,\n  )\n}\n\nfunction callMessage(id: string, name: string, args: string): ModelMessage {\n  return {\n    role: 'assistant',\n    content: null,\n    toolCalls: [\n      {\n        id,\n        type: 'function',\n        function: { name, arguments: args },\n        metadata: { [SANDBOX_OBSERVED]: true },\n      },\n    ],\n  }\n}\n\nfunction resultMessage(id: string, content: string): ModelMessage {\n  return { role: 'tool', toolCallId: id, content }\n}\n\nexport function createToolHistoryRecorder(): ToolHistoryRecorder {\n  const open = new Map<string, OpenCall>()\n  /** Completed calls in the order they ran — the order `reconcile` restores. */\n  const recorded: Array<{ id: string; name: string; args: string }> = []\n  const results = new Map<string, string>()\n\n  function appendCall(\n    target: TranscriptTarget,\n    id: string,\n    name: string,\n    args: string,\n  ): void {\n    // An id already present is either the engine's own (it executed the tool itself)\n    // or a chunk seen before — a journal replay on takeover re-emits the whole\n    // stream. Either way a second write would duplicate the card.\n    if (hasCall(target.messages, id)) return\n    target.messages = [...target.messages, callMessage(id, name, args)]\n  }\n\n  function appendResult(\n    target: TranscriptTarget,\n    id: string,\n    content: string,\n  ): void {\n    if (hasResult(target.messages, id)) return\n    target.messages = [...target.messages, resultMessage(id, content)]\n  }\n\n  const recorder: ToolHistoryRecorder = {\n    // An if/else chain rather than a `switch`: only four of the ~20 chunk types are\n    // interesting here, and a `switch` on `chunk.type` has to enumerate all of them\n    // to satisfy the exhaustiveness lint.\n    observe(chunk, target) {\n      if (chunk.type === EventType.TOOL_CALL_START) {\n        const name = chunk.toolCallName\n        if (!name) return\n        open.set(chunk.toolCallId, { name, args: '' })\n        return\n      }\n      if (chunk.type === EventType.TOOL_CALL_ARGS) {\n        const call = open.get(chunk.toolCallId)\n        if (!call) return\n        call.args += chunk.delta\n        return\n      }\n      if (chunk.type === EventType.TOOL_CALL_END) {\n        const call = open.get(chunk.toolCallId)\n        if (!call) return\n        open.delete(chunk.toolCallId)\n        recorded.push({\n          id: chunk.toolCallId,\n          name: call.name,\n          args: call.args,\n        })\n        appendCall(target, chunk.toolCallId, call.name, call.args)\n        return\n      }\n      if (chunk.type === EventType.TOOL_CALL_RESULT) {\n        // AG-UI types `content` as a string; anything else is not a result we can\n        // store as a `role: 'tool'` message.\n        if (typeof chunk.content !== 'string') return\n        results.set(chunk.toolCallId, chunk.content)\n        appendResult(target, chunk.toolCallId, chunk.content)\n      }\n    },\n\n    reconcile(target) {\n      for (const { id, name, args } of recorded) {\n        appendCall(target, id, name, args)\n        const result = results.get(id)\n        // The result goes straight after its own call, so a restored transcript reads\n        // in the order the tools actually ran.\n        if (result !== undefined) appendResult(target, id, result)\n      }\n    },\n  }\n  return recorder\n}\n\n/**\n * Drop recorded harness tool calls from a list of messages bound for the model.\n *\n * A stored transcript becomes the history for the NEXT turn. These calls name tools\n * the provider was never given, and one triage-sized run is hundreds of kilobytes of\n * tool output — so replaying them is wasteful at best and rejected at worst. They stay\n * in `ctx.messages` (which is what gets stored and rendered); only the request to the\n * model loses them.\n *\n * An assistant message is dropped only when EVERY call on it is observed, so a mixed\n * message — one engine tool call plus one harness tool call — is left alone rather than\n * silently losing the engine's half.\n */\nexport function stripObservedToolCalls(\n  messages: ReadonlyArray<ModelMessage>,\n): Array<ModelMessage> {\n  const dropped = new Set<string>()\n  const kept: Array<ModelMessage> = []\n  for (const message of messages) {\n    const calls = message.toolCalls\n    if (calls && calls.length > 0 && calls.every(isSandboxToolCall)) {\n      for (const call of calls) dropped.add(call.id)\n      continue\n    }\n    // Orphaning a result is worse than keeping it: a provider rejects a tool result\n    // whose call is not in the history.\n    if (\n      message.role === 'tool' &&\n      message.toolCallId !== undefined &&\n      dropped.has(message.toolCallId)\n    ) {\n      continue\n    }\n    kept.push(message)\n  }\n  return kept\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,IAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;AAoDzB,SAAgB,kBACd,UACS;CACT,MAAM,WAAW,UAAU;CAC3B,OACE,OAAO,aAAa,YACpB,aAAa,QACb,oBAAoB,YACpB,SAAS,sBAAsB;AAEnC;;AAGA,SAAS,QAAQ,UAAuC,IAAqB;CAC3E,OAAO,SAAS,MAAM,YACpB,QAAQ,WAAW,MAAM,SAAS,KAAK,OAAO,EAAE,CAClD;AACF;;AAGA,SAAS,UAAU,UAAuC,IAAqB;CAC7E,OAAO,SAAS,MACb,YAAY,QAAQ,SAAS,UAAU,QAAQ,eAAe,EACjE;AACF;AAEA,SAAS,YAAY,IAAY,MAAc,MAA4B;CACzE,OAAO;EACL,MAAM;EACN,SAAS;EACT,WAAW,CACT;GACE;GACA,MAAM;GACN,UAAU;IAAE;IAAM,WAAW;GAAK;GAClC,UAAU,GAAG,mBAAmB,KAAK;EACvC,CACF;CACF;AACF;AAEA,SAAS,cAAc,IAAY,SAA+B;CAChE,OAAO;EAAE,MAAM;EAAQ,YAAY;EAAI;CAAQ;AACjD;AAEA,SAAgB,4BAAiD;CAC/D,MAAM,uBAAO,IAAI,IAAsB;;CAEvC,MAAM,WAA8D,CAAC;CACrE,MAAM,0BAAU,IAAI,IAAoB;CAExC,SAAS,WACP,QACA,IACA,MACA,MACM;EAIN,IAAI,QAAQ,OAAO,UAAU,EAAE,GAAG;EAClC,OAAO,WAAW,CAAC,GAAG,OAAO,UAAU,YAAY,IAAI,MAAM,IAAI,CAAC;CACpE;CAEA,SAAS,aACP,QACA,IACA,SACM;EACN,IAAI,UAAU,OAAO,UAAU,EAAE,GAAG;EACpC,OAAO,WAAW,CAAC,GAAG,OAAO,UAAU,cAAc,IAAI,OAAO,CAAC;CACnE;CAkDA,OAAO;EA5CL,QAAQ,OAAO,QAAQ;GACrB,IAAI,MAAM,SAAS,UAAU,iBAAiB;IAC5C,MAAM,OAAO,MAAM;IACnB,IAAI,CAAC,MAAM;IACX,KAAK,IAAI,MAAM,YAAY;KAAE;KAAM,MAAM;IAAG,CAAC;IAC7C;GACF;GACA,IAAI,MAAM,SAAS,UAAU,gBAAgB;IAC3C,MAAM,OAAO,KAAK,IAAI,MAAM,UAAU;IACtC,IAAI,CAAC,MAAM;IACX,KAAK,QAAQ,MAAM;IACnB;GACF;GACA,IAAI,MAAM,SAAS,UAAU,eAAe;IAC1C,MAAM,OAAO,KAAK,IAAI,MAAM,UAAU;IACtC,IAAI,CAAC,MAAM;IACX,KAAK,OAAO,MAAM,UAAU;IAC5B,SAAS,KAAK;KACZ,IAAI,MAAM;KACV,MAAM,KAAK;KACX,MAAM,KAAK;IACb,CAAC;IACD,WAAW,QAAQ,MAAM,YAAY,KAAK,MAAM,KAAK,IAAI;IACzD;GACF;GACA,IAAI,MAAM,SAAS,UAAU,kBAAkB;IAG7C,IAAI,OAAO,MAAM,YAAY,UAAU;IACvC,QAAQ,IAAI,MAAM,YAAY,MAAM,OAAO;IAC3C,aAAa,QAAQ,MAAM,YAAY,MAAM,OAAO;GACtD;EACF;EAEA,UAAU,QAAQ;GAChB,KAAK,MAAM,EAAE,IAAI,MAAM,UAAU,UAAU;IACzC,WAAW,QAAQ,IAAI,MAAM,IAAI;IACjC,MAAM,SAAS,QAAQ,IAAI,EAAE;IAG7B,IAAI,WAAW,KAAA,GAAW,aAAa,QAAQ,IAAI,MAAM;GAC3D;EACF;CAEK;AACT;;;;;;;;;;;;;;AAeA,SAAgB,uBACd,UACqB;CACrB,MAAM,0BAAU,IAAI,IAAY;CAChC,MAAM,OAA4B,CAAC;CACnC,KAAK,MAAM,WAAW,UAAU;EAC9B,MAAM,QAAQ,QAAQ;EACtB,IAAI,SAAS,MAAM,SAAS,KAAK,MAAM,MAAM,iBAAiB,GAAG;GAC/D,KAAK,MAAM,QAAQ,OAAO,QAAQ,IAAI,KAAK,EAAE;GAC7C;EACF;EAGA,IACE,QAAQ,SAAS,UACjB,QAAQ,eAAe,KAAA,KACvB,QAAQ,IAAI,QAAQ,UAAU,GAE9B;EAEF,KAAK,KAAK,OAAO;CACnB;CACA,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-sandbox",
-  "version": "0.3.4",
+  "version": "0.5.0",
   "description": "Provider-agnostic sandbox layer for TanStack AI — run harness adapters inside isolated sandboxes (defineSandbox, defineWorkspace, withSandbox) with a uniform SandboxHandle, workspace bootstrap, policy, and resumable lifecycle.",
   "author": "",
   "license": "MIT",
@@ -60,12 +60,16 @@
   "peerDependencies": {
     "@ngrok/ngrok": "^1.0.0",
     "vitest": "^4.1.10",
-    "@tanstack/ai": "^0.46.0"
+    "@tanstack/ai": "^0.48.0",
+    "@tanstack/ai-persistence": "^0.5.0"
   },
   "peerDependenciesMeta": {
     "@ngrok/ngrok": {
       "optional": true
     },
+    "@tanstack/ai-persistence": {
+      "optional": true
+    },
     "vitest": {
       "optional": true
     }
@@ -74,7 +78,8 @@
     "@ngrok/ngrok": "^1.7.0",
     "@vitest/coverage-v8": "4.1.10",
     "vitest": "^4.1.10",
-    "@tanstack/ai": "0.46.0"
+    "@tanstack/ai": "0.48.0",
+    "@tanstack/ai-persistence": "0.5.0"
   },
   "scripts": {
     "build": "vite build",

package/skills/ai-sandbox/SKILL.md

@@ -8,7 +8,13 @@ description: >
   fileSkill), plugins, instructions → canonical AGENTS.md + symlinks projected
   per harness; shallow-clone default with depth opt-out; serial/parallel setup
   callback over a persistent shell; snapshot-after-setup default with
-  snapshotMaxAge TTL; defineWorkspace (git/setup/scripts/skills/secrets/
+  snapshotMaxAge TTL. It also covers portable snapshots after a successful
+  terminal run with withPersistence before withSandbox and
+  memorySandboxSnapshots for local examples. It covers named saves with
+  snapshots.save, selected-checkpoint forks with snapshots.fork, and
+  authorized artifact reads with snapshots.readArtifact. See
+  docs/sandbox/portable-snapshots.md. It covers defineWorkspace
+  (git/setup/scripts/skills/secrets/
   instructions/plugins), defineSandboxPolicy (allow/ask/deny), lifecycle/resume,
   the SandboxHandle (fs/git/process/ports), capability tokens, defineSandbox
   hooks (onFile/onFileCreate/onFileChange/onFileDelete/onReady/onError/
@@ -185,6 +191,87 @@ lifecycle: {
 
 Providers without snapshot support skip the step silently.
 
+### Portable sandbox snapshots
+
+Portable snapshots keep completed workspace files in application persistence.
+They are separate from provider-native bootstrap snapshots. Configure the
+middleware in this order, with the same persistence value in both places:
+
+```typescript
+import { withPersistence } from '@tanstack/ai-persistence'
+import { memorySandboxSnapshots, withSandbox } from '@tanstack/ai-sandbox'
+
+const snapshots = await memorySandboxSnapshots({ sandbox, instances })
+
+const middleware = [
+  withPersistence(snapshots.persistence),
+  withSandbox(sandbox, { instances, snapshots }),
+]
+```
+
+Each successful terminal run saves regular files, empty directories, durable
+conversation data, and persisted thread artifacts. A later run restores the
+latest checkpoint only into a new private sandbox. A live resumed sandbox is
+never overwritten. The default policy excludes `.git`, `node_modules`, and
+`.env*` path segments at every depth. It excludes the exact projection marker
+only at the workspace root. It also excludes root `CLAUDE.md` and `GEMINI.md`,
+plus direct `.claude/skills/<name>`, `.codex/skills/<name>`, and
+`.grok/skills/<name>` paths. These exclusions use paths even for regular files
+or copies. If you pass only `include` or only `redact`, the default
+exclusions stay in place. If you pass `exclude`, that function replaces
+the default exclusions, except for exact projection-marker protection.
+Copy `defaultSandboxSnapshotPolicy()` first when you write `exclude`.
+Pass `include` and `exclude` functions on `policy` to store only some files,
+including one file. There is no `save({ files })` list. See
+`docs/sandbox/portable-snapshots-files.md`. Resolved secrets are redacted before the data is stored. Symlinks,
+executables, and special filesystem entries fail the capture or restore. Each
+thread has one writer lease. Pause and detach release the lease without a
+partial checkpoint. Blob retention is manual because there is no automatic
+garbage collection yet.
+
+Read these pages for the server-only setup:
+
+- `docs/sandbox/portable-snapshots.md`
+- `docs/sandbox/portable-snapshots-configure.md`
+- `docs/sandbox/portable-snapshots-save.md`
+- `docs/sandbox/portable-snapshots-fork.md`
+- `docs/sandbox/portable-snapshots-artifacts.md`
+- `docs/sandbox/portable-snapshots-tools.md`
+- `docs/sandbox/portable-snapshots-files.md`
+- `docs/sandbox/portable-snapshots-safety.md`
+
+For a user-marked workspace state, call `snapshots.save` on the server. Bind
+`sandbox` and `instances` at create time, or pass them on `save`. The call
+needs `threadId`, `runId`, and a label. It requires a live reusable sandbox.
+`reuse: 'none'` cannot save a named checkpoint.
+
+To branch from a selected checkpoint, call `snapshots.fork` with the thread id,
+checkpoint id, and destination thread id. The store must implement atomic
+`forkFromCheckpoint`. The destination thread must be empty. A fork copies the
+selected snapshot, not the latest snapshot.
+
+To send a checkpoint artifact, call `snapshots.readArtifact` on the server.
+First authorize the caller for the supplied thread. The method makes sure that
+the checkpoint belongs to that thread, then returns its metadata and bytes. It
+does not authorize a caller or create an HTTP response.
+
+For a SQLite checkpoint store, use one transaction for a checkpoint write, its
+head update, and every blob reference update. Use one transaction for a fork,
+including its copied conversation. A partial transaction breaks snapshot
+consistency.
+
+Snapshot capture supports regular files and empty directories only. It excludes
+`.git`, `node_modules`, and `.env*` path segments at every depth. It excludes
+the exact projection marker only at the workspace root. It also excludes root
+`CLAUDE.md` and `GEMINI.md`, plus direct `.claude/skills/<name>`,
+`.codex/skills/<name>`, and `.grok/skills/<name>` paths. These exclusions use
+paths even for regular files or copies. If you pass only `include` or only
+`redact`, the default exclusions stay in place. If you pass `exclude`, that
+function replaces the default exclusions, except for exact projection-marker
+protection. It rejects symlinks, executable files, and special filesystem
+entries. Restore verifies the manifest and blobs before
+it changes a new private sandbox. It never writes into a live resumed sandbox.
+
 ## Providers
 
 - `localProcessSandbox()` — runs on the host (no isolation; dev loop only).
@@ -983,14 +1070,15 @@ including the client `joinRun` side, is in `docs/sandbox/takeover.md`.
 
 - **Harness adapters require a sandbox.** Always include `withSandbox(...)` in
   `middleware` — without it `chat()` throws a missing-capability error.
-- **Secrets** (`workspace.secrets`) are injected into the sandbox env and never
-  persisted (no snapshots, no sandbox store, no event log). Always create them
-  with `createSecrets(...)` so the values stay hidden behind `SecretRef` tokens.
-  The agent binary (`claude`) must exist in the sandbox image (install it in
-  `setup` or bake it into the image).
+- **Secrets** (`workspace.secrets`) are injected into the sandbox env. Their
+  raw values are never persisted in snapshots, the sandbox store, or the event
+  log. Always create them with `createSecrets(...)` so the values stay hidden
+  behind `SecretRef` tokens. The agent binary (`claude`) must exist in the
+  sandbox image (install it in `setup` or bake it into the image).
 - **Secret-bearing projected files** (e.g. MCP config with resolved header
-  values) are re-written on every projection call so rotated secrets re-apply;
-  they are never included in a snapshot.
+  values) can be included by default capture. Capture replaces resolved secret
+  bytes with zero bytes before it hashes or writes snapshot blobs. Restore runs
+  before projection, so projection writes current secret values after restore.
 - **chat()-provided `tools` are bridged** into the in-sandbox agent over a
   host-side MCP tool-proxy: the agent calls them as `mcp__tanstack__<tool>` and
   each call is proxied back to the host where the tool's `execute()` runs (with

package/src/approvals.ts

@@ -15,7 +15,7 @@
  * `approvalId` is stable for a given (provider, kind, target) so a client grant
  * matches the same action on the resumed run.
  */
-import { EventType } from '@tanstack/ai'
+import { EventType, withTanstackMetadata } from '@tanstack/ai'
 import { evaluateCommand } from './policy'
 import type { SandboxPolicy } from './policy'
 import type { StreamChunk } from '@tanstack/ai'
@@ -81,16 +81,17 @@ export function buildApprovalRequestedEvent(input: {
   runId: string
   detail?: Record<string, unknown>
 }): StreamChunk {
-  return {
-    type: EventType.CUSTOM,
-    name: APPROVAL_REQUESTED_EVENT,
-    value: {
-      approvalId: input.approvalId,
-      title: input.title,
-      ...(input.detail ?? {}),
+  return withTanstackMetadata(
+    {
+      type: EventType.CUSTOM,
+      name: APPROVAL_REQUESTED_EVENT,
+      value: {
+        approvalId: input.approvalId,
+        title: input.title,
+        ...(input.detail ?? {}),
+      },
+      timestamp: Date.now(),
     },
-    timestamp: Date.now(),
-    threadId: input.threadId,
-    runId: input.runId,
-  }
+    { threadId: input.threadId, runId: input.runId },
+  ) as StreamChunk
 }

package/src/bridge-events.ts

@@ -10,7 +10,7 @@
  * stream into its translated output — so events interleave live while the agent
  * runs (e.g. code mode's `code_mode:console` logs during a long execution).
  */
-import { EventType } from '@tanstack/ai'
+import { EventType, withTanstackMetadata } from '@tanstack/ai'
 import type { StreamChunk } from '@tanstack/ai'
 
 export interface BridgeEventChannel {
@@ -50,15 +50,21 @@ export function createBridgeEventChannel(meta: {
   return {
     emitCustomEvent(eventName, value) {
       if (closed) return
-      buffer.push({
-        type: EventType.CUSTOM,
-        name: eventName,
-        value,
-        timestamp: Date.now(),
-        model: meta.model,
-        ...(meta.threadId !== undefined && { threadId: meta.threadId }),
-        ...(meta.runId !== undefined && { runId: meta.runId }),
-      })
+      buffer.push(
+        withTanstackMetadata(
+          {
+            type: EventType.CUSTOM,
+            name: eventName,
+            value,
+            timestamp: Date.now(),
+          },
+          {
+            model: meta.model,
+            ...(meta.threadId !== undefined ? { threadId: meta.threadId } : {}),
+            ...(meta.runId !== undefined ? { runId: meta.runId } : {}),
+          },
+        ) as StreamChunk,
+      )
       notify?.()
     },
     close() {