feat(ai-sandbox): SandboxInstanceStore instance durability (BYO) #988
main fromrefs/pull/988/head·merged by tombeckenham View on GitHubSummary#
Durable sandbox instance resume for multi-process / multi-replica deploy, owned by @tanstack/ai-sandbox.
Based on main (after #984). Locks already live in @tanstack/ai/locks — this PR does not re-ship them. Chat persistence is independent: no stores bag key for sandbox instances.
API#
SandboxInstanceStore/SandboxInstanceRecord/InMemorySandboxInstanceStore/SandboxInstanceStoreCapabilitywithSandboxInstanceStore(store)— provide beforewithSandboxdefineSandboxInstanceStore— inline BYO typing (same pattern asdefineLock/defineMessageStore)withSandboxconsumes the capability inensure(in-memory fallback when absent)- Multi-instance: pair with
withLocksfrom@tanstack/ai/locks - Conformance:
runSandboxInstanceStoreConformancefrom@tanstack/ai-sandbox/testkit
Docs / e2e#
docs/sandbox/durability.md(Instance Durability)- Locks guide links to durability
- E2E:
sandbox-durability(store shared across independentchat()runs)
Test plan#
- Unit: in-memory store, conformance suite, ensure algorithm, resume-from-store middleware
- E2E durability route + spec
- CI green on PR
Summary by CodeRabbit#
- New Features
- Added durable sandbox instance resume across processes and replicas using shared storage.
- Added configurable instance storage and distributed locking, with in-memory fallback for single-process use.
- Added tools for validating custom storage implementations.
- Breaking Changes
- Replaced legacy sandbox store integrations with instance store APIs.
- Documentation
- Added a sandbox instance durability guide and updated related guidance.
- Tests
- Added coverage for durable resume, locking, and storage behavior.
- 1
🚀 Changeset Version Preview#
19 package(s) bumped directly, 32 bumped as dependents.
🟥 Major bumps#
Package Version Reason @tanstack/ai-angular0.3.1 → 1.0.0 Changeset @tanstack/ai-durable-stream0.0.0 → 1.0.0 Changeset @tanstack/ai-memory0.0.0 → 1.0.0 Changeset @tanstack/ai-openai0.17.1 → 1.0.0 Changeset @tanstack/ai-openrouter0.15.10 → 1.0.0 Changeset @tanstack/ai-persistence0.0.0 → 1.0.0 Changeset @tanstack/ai-preact0.11.1 → 1.0.0 Changeset @tanstack/ai-react0.18.1 → 1.0.0 Changeset @tanstack/ai-sandbox0.2.4 → 1.0.0 Changeset @tanstack/ai-solid0.15.1 → 1.0.0 Changeset @tanstack/ai-svelte0.15.1 → 1.0.0 Changeset @tanstack/ai-vue0.15.1 → 1.0.0 Changeset @tanstack/openai-base0.9.9 → 1.0.0 Changeset @tanstack/ai-acp0.2.3 → 1.0.0 Dependent @tanstack/ai-anthropic0.16.3 → 1.0.0 Dependent @tanstack/ai-bedrock0.1.4 → 1.0.0 Dependent @tanstack/ai-claude-code0.2.3 → 1.0.0 Dependent @tanstack/ai-code-mode0.3.8 → 1.0.0 Dependent @tanstack/ai-code-mode-skills0.3.11 → 1.0.0 Dependent @tanstack/ai-codex0.2.3 → 1.0.0 Dependent @tanstack/ai-elevenlabs0.2.34 → 1.0.0 Dependent @tanstack/ai-fal0.9.12 → 1.0.0 Dependent @tanstack/ai-gemini0.20.1 → 1.0.0 Dependent @tanstack/ai-grok0.14.9 → 1.0.0 Dependent @tanstack/ai-grok-build0.2.3 → 1.0.0 Dependent @tanstack/ai-groq0.5.3 → 1.0.0 Dependent @tanstack/ai-isolate-node0.1.47 → 1.0.0 Dependent @tanstack/ai-isolate-quickjs0.1.47 → 1.0.0 Dependent @tanstack/ai-mistral0.2.3 → 1.0.0 Dependent @tanstack/ai-ollama0.8.16 → 1.0.0 Dependent @tanstack/ai-opencode0.2.3 → 1.0.0 Dependent @tanstack/ai-react-ui0.8.15 → 1.0.0 Dependent @tanstack/ai-sandbox-cloudflare0.2.4 → 1.0.0 Dependent @tanstack/ai-sandbox-daytona0.2.0 → 1.0.0 Dependent @tanstack/ai-sandbox-docker0.2.0 → 1.0.0 Dependent @tanstack/ai-sandbox-local-process0.2.0 → 1.0.0 Dependent @tanstack/ai-sandbox-sprites0.2.1 → 1.0.0 Dependent @tanstack/ai-sandbox-vercel0.2.0 → 1.0.0 Dependent @tanstack/ai-solid-ui0.7.14 → 1.0.0 Dependent 🟨 Minor bumps#
Package Version Reason @tanstack/ai0.42.0 → 0.43.0 Changeset @tanstack/ai-client0.22.1 → 0.23.0 Changeset @tanstack/ai-devtools-core0.4.24 → 0.5.0 Changeset @tanstack/ai-event-client0.6.8 → 0.7.0 Changeset @tanstack/ai-utils0.3.1 → 0.4.0 Changeset 🟩 Patch bumps#
Package Version Reason @tanstack/ai-mcp0.2.5 → 0.2.6 Changeset @tanstack/ai-isolate-cloudflare0.2.38 → 0.2.39 Dependent @tanstack/ai-vue-ui0.2.34 → 0.2.35 Dependent @tanstack/preact-ai-devtools0.1.67 → 0.1.68 Dependent @tanstack/react-ai-devtools0.2.67 → 0.2.68 Dependent @tanstack/solid-ai-devtools0.2.67 → 0.2.68 Dependent ag-ui0.0.2 → 0.0.3 Dependent View your CI Pipeline Execution ↗ for commit 2d8e35fdfb387929cdbef26943d54b681b92b9c7
Command Status Duration Result nx run-many --targets=build --exclude=examples/...✅ Succeeded 25s View ↗
☁️ Nx Cloud last updated this comment at
2026-07-31 04:38:55UTC@tanstack/ai
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai@988@tanstack/ai-acp
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-acp@988@tanstack/ai-angular
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-angular@988@tanstack/ai-anthropic
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-anthropic@988@tanstack/ai-bedrock
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-bedrock@988@tanstack/ai-claude-code
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-claude-code@988@tanstack/ai-client
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-client@988@tanstack/ai-code-mode
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-code-mode@988@tanstack/ai-code-mode-skills
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-code-mode-skills@988@tanstack/ai-codex
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-codex@988@tanstack/ai-devtools-core
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-devtools-core@988@tanstack/ai-durable-stream
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-durable-stream@988@tanstack/ai-elevenlabs
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-elevenlabs@988@tanstack/ai-event-client
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-event-client@988@tanstack/ai-fal
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-fal@988@tanstack/ai-gemini
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-gemini@988@tanstack/ai-grok
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-grok@988@tanstack/ai-grok-build
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-grok-build@988@tanstack/ai-groq
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-groq@988@tanstack/ai-isolate-cloudflare
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-cloudflare@988@tanstack/ai-isolate-node
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-node@988@tanstack/ai-isolate-quickjs
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-isolate-quickjs@988@tanstack/ai-mcp
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-mcp@988@tanstack/ai-memory
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-memory@988@tanstack/ai-mistral
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-mistral@988@tanstack/ai-ollama
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-ollama@988@tanstack/ai-openai
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openai@988@tanstack/ai-opencode
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-opencode@988@tanstack/ai-openrouter
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openrouter@988@tanstack/ai-persistence
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-persistence@988@tanstack/ai-preact
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-preact@988@tanstack/ai-react
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react@988@tanstack/ai-react-ui
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react-ui@988@tanstack/ai-sandbox
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox@988@tanstack/ai-sandbox-cloudflare
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-cloudflare@988@tanstack/ai-sandbox-daytona
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-daytona@988@tanstack/ai-sandbox-docker
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-docker@988@tanstack/ai-sandbox-local-process
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-local-process@988@tanstack/ai-sandbox-sprites
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-sprites@988@tanstack/ai-sandbox-vercel
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-sandbox-vercel@988@tanstack/ai-solid
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-solid@988@tanstack/ai-solid-ui
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-solid-ui@988@tanstack/ai-svelte
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-svelte@988@tanstack/ai-utils
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-utils@988@tanstack/ai-vue
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vue@988@tanstack/ai-vue-ui
npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-vue-ui@988@tanstack/openai-base
npm i https://pkg.pr.new/TanStack/ai/@tanstack/openai-base@988@tanstack/preact-ai-devtools
npm i https://pkg.pr.new/TanStack/ai/@tanstack/preact-ai-devtools@988@tanstack/react-ai-devtools
npm i https://pkg.pr.new/TanStack/ai/@tanstack/react-ai-devtools@988@tanstack/solid-ai-devtools
npm i https://pkg.pr.new/TanStack/ai/@tanstack/solid-ai-devtools@988commit:
2d8e35fRebased onto latest
feat/persistence-core(3efe0c1d2) after the bottom of the stack moved.Adapted to the post-schema-first core design rather than a raw cherry-pick of the pre-refactor commit:
- Shared
LocksCapability+SandboxStoreCapability(and in-memory impls) live in core@tanstack/ai - Locks remain on
withLocks(not the state bag); optionalstores.sandboxis provided bywithPersistencewhen present - Backend surface:
createDrizzleSandboxStore(db, table)/createPrismaSandboxStore/createD1SandboxStore; NodesqlitePersistencestill returns a bag that includessandbox - Sandboxes stay outside the chat BYO schema contract
- Docs + e2e harness updated for
withLockscomposition
Local green: typecheck +
test:libfor@tanstack/ai-persistence,@tanstack/ai-sandbox, and all four persistence packages (incl. sandbox store conformance).- Shared
tombeckenham added labelspersistence
tombeckenham changed the title
Actionable comments posted: 4
🧹 Nitpick comments (2)
packages/ai-sandbox/tests/store.test.ts (1)
2-7: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winSplit and colocate these unit tests with their implementations.
Move the sandbox-store tests beside
packages/ai-sandbox/src/instance-store.tsand the lock tests besidepackages/ai/src/activities/chat/middleware/locks.ts; this file currently covers sources in two separate locations.As per coding guidelines, “Place unit tests in
*.test.tsfiles alongside the source they cover.”Also applies to: 22-65
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ai-sandbox/tests/store.test.ts` around lines 2 - 7, Split the tests in store.test.ts by implementation: move the InMemorySandboxInstanceStore tests beside instance-store.ts, and move the InMemoryLockStore tests beside locks.ts under the chat middleware implementation. Preserve each test’s existing behavior while ensuring both suites are colocated in *.test.ts files next to their covered source.Source: Coding guidelines
testing/e2e/src/routes/api.sandbox-durability.ts (1)
138-171: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winConsider a concurrent-request test for the lock contention path.
This route wires
withLocksinto the middleware chain, but the only assertions in the accompanying spec exercise strictly sequential requests. A test issuing two concurrent POSTs with the samethreadIdwould validate the actual purpose of the lock (preventing duplicate creation under a race), which is central to this PR's "multi-instance-correct" durability claim.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@testing/e2e/src/routes/api.sandbox-durability.ts` around lines 138 - 171, Add a concurrent-request test for the /api/sandbox-durability route using the same threadId, starting both POST requests before awaiting either. Assert that lock contention prevents duplicate sandbox creation and that the resulting create/resume counts and provider sandbox identity reflect a single shared instance, exercising the withLocks middleware path.🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@packages/ai-sandbox/package.json`: - Line 62: Update the `@tanstack/ai` dependency entry in package.json from the workspace:^ protocol to workspace:* while preserving the existing internal package reference. In `@packages/ai-sandbox/skills/ai-sandbox/SKILL.md`: - Around line 222-237: Update the multi-instance example around chat to import withLocks and LockStore from `@tanstack/ai/locks` instead of the main `@tanstack/ai` barrel, and replace InMemoryLockStore with the production BYO distributed LockStore instance. Preserve the existing withSandboxInstanceStore, withLocks, and withSandbox middleware order. In `@packages/ai-sandbox/src/instance-store.ts`: - Around line 80-83: Update InMemoryStore.upsert to normalize omitted optional fields before storing records, removing undefined-valued properties such as latestSnapshotId while preserving defined values. Ensure the in-memory fallback matches the store contract and durable adapters without changing the upsert return behavior. In `@packages/ai-sandbox/src/testkit/conformance.ts`: - Around line 68-77: Update the overwrite fixture in the conformance test around store.upsert and store.get to seed both latestSnapshotId and latestRunId on the initial record. After replacing the record, assert that loaded contains neither optional field, preserving the existing latestSnapshotId assertion and adding equivalent coverage for latestRunId. --- Nitpick comments: In `@packages/ai-sandbox/tests/store.test.ts`: - Around line 2-7: Split the tests in store.test.ts by implementation: move the InMemorySandboxInstanceStore tests beside instance-store.ts, and move the InMemoryLockStore tests beside locks.ts under the chat middleware implementation. Preserve each test’s existing behavior while ensuring both suites are colocated in *.test.ts files next to their covered source. In `@testing/e2e/src/routes/api.sandbox-durability.ts`: - Around line 138-171: Add a concurrent-request test for the /api/sandbox-durability route using the same threadId, starting both POST requests before awaiting either. Assert that lock contention prevents duplicate sandbox creation and that the resulting create/resume counts and provider sandbox identity reflect a single shared instance, exercising the withLocks middleware path.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
558feb63-3ea1-478b-a2f2-50ab698d93a2📥 Commits
Reviewing files that changed from the base of the PR and between 4ab149fd46a1cf55691266cdd118fdc9999c0b2a and e87d8e10c351c6e0114d6383d0e5698bd35bc7ff.
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (21)
.changeset/sandbox-durability.mddocs/config.jsondocs/sandbox/durability.mddocs/sandbox/overview.mdpackages/ai-sandbox/package.jsonpackages/ai-sandbox/skills/ai-sandbox/SKILL.mdpackages/ai-sandbox/src/capabilities.tspackages/ai-sandbox/src/index.tspackages/ai-sandbox/src/instance-store.tspackages/ai-sandbox/src/middleware.tspackages/ai-sandbox/src/sandbox.tspackages/ai-sandbox/src/store.tspackages/ai-sandbox/src/testkit/conformance.tspackages/ai-sandbox/src/workspace.tspackages/ai-sandbox/tests/ensure.test.tspackages/ai-sandbox/tests/store.test.tspackages/ai-sandbox/vite.config.tstesting/e2e/package.jsontesting/e2e/src/routeTree.gen.tstesting/e2e/src/routes/api.sandbox-durability.tstesting/e2e/tests/sandbox-durability.spec.ts
💤 Files with no reviewable changes (1)
- packages/ai-sandbox/src/store.ts
packages/ai-sandbox/package.json line 62@@ -55,4 +59,4 @@5559 },5660 "peerDependencies": {5761 "@ngrok/ngrok": "^1.0.0",58- "@tanstack/ai": "workspace:^"62+ "@tanstack/ai": "workspace:^",📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use
workspace:*for the internal peer dependency.@tanstack/aiusesworkspace:^, which does not follow the required internal dependency protocol.Proposed fix
- "`@tanstack/ai`": "workspace:^", + "`@tanstack/ai`": "workspace:*",As per coding guidelines, “Use the
workspace:*protocol for internal package dependencies inpackage.json.”📝 Committable suggestion
‼️ IMPORTANT Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
"`@tanstack/ai`": "workspace:*",🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ai-sandbox/package.json` at line 62, Update the `@tanstack/ai` dependency entry in package.json from the workspace:^ protocol to workspace:* while preserving the existing internal package reference.Source: Coding guidelines
packages/ai-sandbox/skills/ai-sandbox/SKILL.md lines 222 to 237Outdated@@ -213,0 +217,21 @@217+multi-instance resume, implement a durable `SandboxInstanceStore` (BYO) and218+provide it with `withSandboxInstanceStore`. Pair multi-instance with219+`withLocks` from `@tanstack/ai`. Order: providers **before** `withSandbox`.220+221+```typescript222+import { chat, InMemoryLockStore, withLocks } from '@tanstack/ai'223+import {224+ InMemorySandboxInstanceStore,225+ withSandbox,226+ withSandboxInstanceStore,227+} from '@tanstack/ai-sandbox'228+// Production: your BYO store — docs/sandbox/durability.md229+import { instanceStore } from './sandbox-instance-store'230+231+chat({232+ adapter,233+ messages,234+ middleware: [235+ withSandboxInstanceStore(instanceStore),236+ withLocks(new InMemoryLockStore()), // multi-instance: distributed lock237+ withSandbox(sandbox),🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash set -euo pipefail echo "== tracked files matching SKILL/durability/changeset ==" git ls-files | rg '(^|/)SKILL\.md$|durability|sandbox-instance-store|sandbox-lock-store|sandbox-lock' || true echo echo "== target lines in SKILL.md ==" fd -a 'SKILL.md' . | sed 's#^\./##' | while read -r f; do if [ "$(basename "$(dirname "$f")")" = "ai-sandbox" ] && grep -q "InMemoryLockStore" "$f"; then echo "--- $f" wc -l "$f" sed -n '200,250p' "$f" | nl -ba -v200 fi done echo echo "== lock import/usage references ==" rg -n "`@tanstack/ai/locks`|InMemoryLockStore|withLocks|distributed lock|multi-instance" -S . --glob '!node_modules' --glob '!dist' --glob '!build' || true echo echo "== candidate store files ==" git ls-files | rg 'sandbox.*(lock|instance).*store\.|lock.*store\.|instance.*store\.' || trueRepository: TanStack/ai
Length of output: 2680
🏁 Script executed:
#!/bin/bash set -uuo pipefail echo "== target lines in packages/ai-sandbox/skills/ai-sandbox/SKILL.md ==" sed -n '200,250p' packages/ai-sandbox/skills/ai-sandbox/SKILL.md | awk '{printf "%5d\t%s\n", NR+199, $0}' echo echo "== lock/store references in ai-sandbox skill, durability docs, changeset, and repo ==" rg -n "`@tanstack/ai`$|`@tanstack/ai/locks`|InMemoryLockStore|withLocks|distributed lock|multi-instance|sandbox-lock-store|lockStore" packages/ai-sandbox/skills/ai-sandbox/SKILL.md docs/sandbox/durability.md .changeset/sandbox-durability.md -S || true echo echo "== package exports / lock entry point ==" for f in packages/ai/package.json packages/ai/src/index.ts packages/ai/src/locks entry points...; do if [ -e "$f" ]; then echo "--- $f" sed -n '1,220p' "$f" | awk '{printf "%5d\t%s\n", NR, $0}' fi doneRepository: TanStack/ai
Length of output: 15067
🏁 Script executed:
#!/bin/bash set -uuo pipefail echo "== docs sandbox durability relevant lines ==" sed -n '1,130p' docs/sandbox/durability.md | awk '{printf "%5d\t%s\n", NR, $0}' echo "---" sed -n '160,185p' docs/sandbox/durability.md | awk '{printf "%5d\t%s\n", NR+159, $0}' echo echo "== changeset relevant lines ==" sed -n '1,80p' .changeset/sandbox-durability.md | awk '{printf "%5d\t%s\n", NR, $0}' echo echo "== lock source files ==" git ls-files | rg 'packages/ai/src/(locks|.*lock|locks/)' || true for f in packages/ai/src/locks.ts packages/ai/src/locks index.ts; do if [ -e "$f" ]; then echo "--- $f" sed -n '1,180p' "$f" | awk '{printf "%5d\t%s\n", NR, $0}' fi done echo echo "== lock definitions and InMemoryLockStore references ==" rg -n "class InMemoryLockStore|InMemoryLockStore|LockStore|withLocks|withLocks\\(" packages/ai/src docs packages/ai-sandbox/skills/ai-sandbox/SKILL.md -S || trueRepository: TanStack/ai
Length of output: 14025
Use the locks subpath and a real distributed
LockStorein this multi-instance example.This sandbox durability section introduces
@tanstack/ai/locks; importingwithLocks/InMemoryLockStorefrom the main@tanstack/aibarrel is wrong, andInMemoryLockStoreis process-local, so themulti-instance: distributed lockuse case can still race. Import from@tanstack/ai/locksand pass a BYO distributedLockStorefor production.🧰 Tools
🪛 SkillSpector (2.3.11)
[warning] 200: [PE2] Sudo/Root Execution: Commands invoke sudo or root privileges. Verify this elevated access is necessary and justified.
Remediation: Avoid sudo/root unless strictly required. Prefer least-privilege patterns. If elevation is needed, document the justification and scope.
(Privilege Escalation (PE2))
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ai-sandbox/skills/ai-sandbox/SKILL.md` around lines 222 - 237, Update the multi-instance example around chat to import withLocks and LockStore from `@tanstack/ai/locks` instead of the main `@tanstack/ai` barrel, and replace InMemoryLockStore with the production BYO distributed LockStore instance. Preserve the existing withSandboxInstanceStore, withLocks, and withSandbox middleware order.packages/ai-sandbox/src/instance-store.ts lines 94 to 97@@ -0,0 +63,21 @@63+ * consumed by {@link withSandbox}.64+ */65+export const SandboxInstanceStoreCapability =66+ createCapability<SandboxInstanceStore>()('sandbox-instance-store')67+68+/** Destructured accessors: `getSandboxInstanceStore` / `provideSandboxInstanceStore`. */69+export const [getSandboxInstanceStore, provideSandboxInstanceStore] =70+ SandboxInstanceStoreCapability71+72+/** In-memory {@link SandboxInstanceStore}. Resume works only within one process. */73+export class InMemorySandboxInstanceStore implements SandboxInstanceStore {74+ private readonly map = new Map<string, SandboxInstanceRecord>()75+76+ get(key: string): Promise<SandboxInstanceRecord | null> {77+ return Promise.resolve(this.map.get(key) ?? null)78+ }79+80+ upsert(record: SandboxInstanceRecord): Promise<void> {81+ this.map.set(record.key, record)82+ return Promise.resolve()83+ }🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Normalize omitted optional fields in the in-memory store.
upsertpreservesundefinedproperties.packages/ai-sandbox/src/sandbox.tswriteslatestSnapshotId: undefinedon the create path (Line 229-237), while the store contract/conformance expects absent optional fields to remain omitted. Normalize optional fields before storing, or construct the create record conditionally, so the in-memory fallback matches durable adapters.Proposed fix
upsert(record: SandboxInstanceRecord): Promise<void> { - this.map.set(record.key, record) + this.map.set(record.key, { + key: record.key, + provider: record.provider, + providerSandboxId: record.providerSandboxId, + threadId: record.threadId, + updatedAt: record.updatedAt, + ...(record.latestSnapshotId !== undefined + ? { latestSnapshotId: record.latestSnapshotId } + : {}), + ...(record.latestRunId !== undefined + ? { latestRunId: record.latestRunId } + : {}), + }) return Promise.resolve() }📝 Committable suggestion
‼️ IMPORTANT Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
upsert(record: SandboxInstanceRecord): Promise<void> { this.map.set(record.key, { key: record.key, provider: record.provider, providerSandboxId: record.providerSandboxId, threadId: record.threadId, updatedAt: record.updatedAt, ...(record.latestSnapshotId !== undefined ? { latestSnapshotId: record.latestSnapshotId } : {}), ...(record.latestRunId !== undefined ? { latestRunId: record.latestRunId } : {}), }) return Promise.resolve() }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ai-sandbox/src/instance-store.ts` around lines 80 - 83, Update InMemoryStore.upsert to normalize omitted optional fields before storing records, removing undefined-valued properties such as latestSnapshotId while preserving defined values. Ensure the in-memory fallback matches the store contract and durable adapters without changing the upsert return behavior.packages/ai-sandbox/src/testkit/conformance.ts lines 68 to 77@@ -0,0 +57,21 @@57+ const store = await makeStore()58+ const record = makeRecord()59+ await store.upsert(record)60+ const loaded = await store.get(record.key)61+ expect(loaded).toEqual(record)62+ expect(loaded && 'latestSnapshotId' in loaded).toBe(false)63+ expect(loaded && 'latestRunId' in loaded).toBe(false)64+ })65+66+ it('overwrites an existing record on re-upsert', async () => {67+ const store = await makeStore()68+ await store.upsert(makeRecord({ latestSnapshotId: 'snap-1' }))69+ await store.upsert(70+ makeRecord({ providerSandboxId: 'sb-2', updatedAt: 2 }),71+ )72+ const loaded = await store.get('thread-1')73+ expect(loaded?.providerSandboxId).toBe('sb-2')74+ expect(loaded?.updatedAt).toBe(2)75+ // The overwrite dropped latestSnapshotId — a durable store must clear it,76+ // not retain the prior value.77+ expect(loaded && 'latestSnapshotId' in loaded).toBe(false)🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Cover
latestRunIdclearing on replacement.The overwrite fixture only seeds
latestSnapshotId, so a store that incorrectly merges and retainslatestRunIdstill passes conformance. Seed both optional fields and assert both are absent after the replacement.Proposed test update
- await store.upsert(makeRecord({ latestSnapshotId: 'snap-1' })) + await store.upsert( + makeRecord({ latestSnapshotId: 'snap-1', latestRunId: 'run-1' }), + ) await store.upsert( makeRecord({ providerSandboxId: 'sb-2', updatedAt: 2 }), ) @@ expect(loaded && 'latestSnapshotId' in loaded).toBe(false) + expect(loaded && 'latestRunId' in loaded).toBe(false)Based on supplied contract context, full replacement must clear both optional fields.
📝 Committable suggestion
‼️ IMPORTANT Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
await store.upsert( makeRecord({ latestSnapshotId: 'snap-1', latestRunId: 'run-1' }), ) await store.upsert( makeRecord({ providerSandboxId: 'sb-2', updatedAt: 2 }), ) const loaded = await store.get('thread-1') expect(loaded?.providerSandboxId).toBe('sb-2') expect(loaded?.updatedAt).toBe(2) // The overwrite dropped latestSnapshotId — a durable store must clear it, // not retain the prior value. expect(loaded && 'latestSnapshotId' in loaded).toBe(false) expect(loaded && 'latestRunId' in loaded).toBe(false)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ai-sandbox/src/testkit/conformance.ts` around lines 68 - 77, Update the overwrite fixture in the conformance test around store.upsert and store.get to seed both latestSnapshotId and latestRunId on the initial record. After replacing the record, assert that loaded contains neither optional field, preserving the existing latestSnapshotId assertion and adding equivalent coverage for latestRunId.tombeckenham changed the title
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@packages/ai-sandbox/tests/resume-from-store.test.ts`: - Line 1: Move packages/ai-sandbox/tests/resume-from-store.test.ts alongside the middleware/source module it covers, preserving its tests and imports. Also move packages/ai-sandbox/tests/store.conformance.test.ts alongside packages/ai-sandbox/src/testkit/conformance.ts, updating relative imports as needed; both files should remain *.test.ts unit-test files co-located with their covered source. - Around line 81-95: Strengthen the resume-from-store test around run-2 by storing a provider sandbox ID distinct from the sandbox key after run-1, then capture the ID supplied to provider.resume and assert it equals that stored provider ID. Update the existing fake/provider setup and assertions near run('run-1') and run('run-2') without changing the production flow.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
de53f0bf-0ca0-4681-a850-e5d320408a57📥 Commits
Reviewing files that changed from the base of the PR and between e87d8e10c351c6e0114d6383d0e5698bd35bc7ff and ed3997b7b6b872c229aa9322612af53e20aeeda8.
📒 Files selected for processing (10)
.changeset/sandbox-durability.mddocs/advanced/locks.mddocs/config.jsondocs/sandbox/durability.mdpackages/ai-sandbox/skills/ai-sandbox/SKILL.mdpackages/ai-sandbox/src/capabilities.tspackages/ai-sandbox/src/index.tspackages/ai-sandbox/src/instance-store.tspackages/ai-sandbox/tests/resume-from-store.test.tspackages/ai-sandbox/tests/store.conformance.test.ts
🚧 Files skipped from review as they are similar to previous changes (5)
- docs/sandbox/durability.md
- .changeset/sandbox-durability.md
- packages/ai-sandbox/src/instance-store.ts
- packages/ai-sandbox/src/index.ts
- packages/ai-sandbox/src/capabilities.ts
packages/ai-sandbox/tests/resume-from-store.test.ts line 1@@ -0,0 +1 @@1+import { describe, expect, it } from 'vitest'📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Co-locate these unit tests with their covered source modules.
packages/ai-sandbox/tests/resume-from-store.test.ts#L1-L1: move alongside its primary middleware/source coverage.packages/ai-sandbox/tests/store.conformance.test.ts#L1-L1: move alongsidepackages/ai-sandbox/src/testkit/conformance.ts.
As per coding guidelines, “Place unit tests in
*.test.tsfiles alongside the source they cover.”📍 Affects 2 files
packages/ai-sandbox/tests/resume-from-store.test.ts#L1-L1(this comment)packages/ai-sandbox/tests/store.conformance.test.ts#L1-L1
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ai-sandbox/tests/resume-from-store.test.ts` at line 1, Move packages/ai-sandbox/tests/resume-from-store.test.ts alongside the middleware/source module it covers, preserving its tests and imports. Also move packages/ai-sandbox/tests/store.conformance.test.ts alongside packages/ai-sandbox/src/testkit/conformance.ts, updating relative imports as needed; both files should remain *.test.ts unit-test files co-located with their covered source.Sources: Coding guidelines, Learnings
packages/ai-sandbox/tests/resume-from-store.test.ts lines 98 to 109@@ -0,0 +75,21 @@75+ withLocks(locks),76+ withSandbox(sandbox),77+ ],78+ }) as AsyncIterable<StreamChunk>,79+ )80+81+ await run('run-1')82+ expect(provider.calls.create).toBe(1)83+ expect(provider.calls.resume).toBe(0)84+85+ await run('run-2')86+ expect(provider.calls.create).toBe(1)87+ expect(provider.calls.resume).toBe(1)88+89+ const key = sandbox.key({90+ threadId: 'thread-1',91+ runId: 'run-2',92+ })93+ const rec = await instanceStore.get(key)94+ expect(rec?.latestRunId).toBe('run-2')95+ expect(rec?.providerSandboxId).toBeTruthy()🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Assert the ID passed to
provider.resume.createis givenkeyas its ID, so a regression that resumes using the computed key instead ofexisting.providerSandboxIdstill passes these assertions. Store a distinct provider ID after run one and capture/assertresume’s input ID on run two.Based on provided context,
packages/ai-sandbox/src/sandbox.tspasseskeytocreate, whilepackages/ai-sandbox/tests/fakes.tsresumes the ID it receives.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ai-sandbox/tests/resume-from-store.test.ts` around lines 81 - 95, Strengthen the resume-from-store test around run-2 by storing a provider sandbox ID distinct from the sandbox key after run-1, then capture the ID supplied to provider.resume and assert it equals that stored provider ID. Update the existing fake/provider setup and assertions near run('run-1') and run('run-2') without changing the production flow.Note: instance-store conformance / testkit#
This PR ships
runSandboxInstanceStoreConformanceunder@tanstack/ai-sandbox/testkit(optional Vitest peer), mirroring chat persistence’srunPersistenceConformancepattern: contract + in-memory reference + a suite so BYO stores can prove full-replace upsert, missing-keynull, delete no-op, etc. beforeensuredepends on them.Open question for reviewers: do we think this is necessary now, and is it even discoverable enough?
- Necessary? Apps can ship a wrong store and only notice in multi-instance prod. Conformance is the cheap gate. Counter: we don’t ship a packaged sandbox DB backend yet, so maybe overkill until adapters land.
- Discoverable? Docs + skill mention it; the import is a subpath (
@tanstack/ai-sandbox/testkit). Easy to miss if you only look at the root export. Alternatives: drop for v1, or keep but surface harder (e.g. skill “required for production”, example in durability doc only, or delay untilfeat/persistence-sandbox-adapters).
Preference welcome: keep / drop / keep-but-hide-until-adapters.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@packages/ai-sandbox/src/index.ts`: - Around line 18-28: Preserve the legacy `@tanstack/ai-sandbox` exports InMemorySandboxStore, SandboxStore, and SandboxRecord by adding deprecated compatibility re-exports that point to their replacements in `@tanstack/ai`, and document the migration path. Keep the current SandboxInstanceStore exports intact.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
d2b14974-f6b6-47b1-aa1c-c6c5ab2005e1📥 Commits
Reviewing files that changed from the base of the PR and between 7b289308e6090bcc79c476082b49bfb8161a0276 and 2d8e35fdfb387929cdbef26943d54b681b92b9c7.
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (24)
.changeset/sandbox-durability.mddocs/advanced/locks.mddocs/config.jsondocs/sandbox/durability.mddocs/sandbox/overview.mdpackages/ai-sandbox/package.jsonpackages/ai-sandbox/skills/ai-sandbox/SKILL.mdpackages/ai-sandbox/src/capabilities.tspackages/ai-sandbox/src/index.tspackages/ai-sandbox/src/instance-store.tspackages/ai-sandbox/src/middleware.tspackages/ai-sandbox/src/sandbox.tspackages/ai-sandbox/src/store.tspackages/ai-sandbox/src/testkit/conformance.tspackages/ai-sandbox/src/workspace.tspackages/ai-sandbox/tests/ensure.test.tspackages/ai-sandbox/tests/resume-from-store.test.tspackages/ai-sandbox/tests/store.conformance.test.tspackages/ai-sandbox/tests/store.test.tspackages/ai-sandbox/vite.config.tstesting/e2e/package.jsontesting/e2e/src/routeTree.gen.tstesting/e2e/src/routes/api.sandbox-durability.tstesting/e2e/tests/sandbox-durability.spec.ts
💤 Files with no reviewable changes (1)
- packages/ai-sandbox/src/store.ts
🚧 Files skipped from review as they are similar to previous changes (20)
- docs/advanced/locks.md
- packages/ai-sandbox/vite.config.ts
- packages/ai-sandbox/src/workspace.ts
- packages/ai-sandbox/package.json
- docs/config.json
- testing/e2e/tests/sandbox-durability.spec.ts
- packages/ai-sandbox/tests/store.conformance.test.ts
- .changeset/sandbox-durability.md
- testing/e2e/package.json
- packages/ai-sandbox/tests/store.test.ts
- docs/sandbox/overview.md
- testing/e2e/src/routes/api.sandbox-durability.ts
- docs/sandbox/durability.md
- packages/ai-sandbox/src/capabilities.ts
- packages/ai-sandbox/src/sandbox.ts
- testing/e2e/src/routeTree.gen.ts
- packages/ai-sandbox/src/middleware.ts
- packages/ai-sandbox/tests/ensure.test.ts
- packages/ai-sandbox/src/instance-store.ts
- packages/ai-sandbox/tests/resume-from-store.test.ts
packages/ai-sandbox/src/index.ts lines 18 to 28@@ -11,7 +9,20 @@11- provideSandboxStore,129 getSandboxPolicy,1310 provideSandboxPolicy,1411 getToolBridgeProvisioner,1512 provideToolBridgeProvisioner,1613 } from './capabilities'171415+// Durable instance map (resume-or-create across processes).16+// Pass a store to `withSandbox(sandbox, { instances })`; the capability is the17+// ambient alternative for platform-level wiring.18+export {19+ SandboxInstanceStoreCapability,20+ getSandboxInstanceStore,21+ provideSandboxInstanceStore,22+ InMemorySandboxInstanceStore,23+ defineSandboxInstanceStore,24+} from './instance-store'25+export type {26+ SandboxInstanceStore,27+ SandboxInstanceRecord,28+} from './instance-store'🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash set -euo pipefail rg -n \ '\b(InMemorySandboxStore|SandboxStore|SandboxRecord)\b|`@tanstack/ai-sandbox/`(store|instance-store)' \ packages testing docs rg -n -C 3 '"exports"|"\./store"|"\./instance-store"' \ packages/ai-sandbox/package.jsonRepository: TanStack/ai
Length of output: 4587
🏁 Script executed:
#!/usr/bin/env bash set -euo pipefail printf '--- package export map ---\n' cat -n packages/ai-sandbox/package.json | sed -n '1,80p' printf '\n--- repository exports for sandbox root/import paths ---\n' rg -n '(`@tanstack/ai-sandbox`\b|from ["'\''](\/|\.\/)dist|from ["'\'']\./source\/|from ["'\'']\./src\/|from ["'\'']\./dist|from ["'\'']\./source|from ["'\'']\./src)' packages --glob '*.{js,ts,tsx,md,mdx,json}' printf '\n--- package files and relevant source ---\n' git ls-files packages/ai-sandbox printf '\n--- instance-store and store files ---\n' git ls-files packages/ai-sandbox/src | sed -n '1,200p'Repository: TanStack/ai
Length of output: 240
Preserve or version the removed
@tanstack/ai-sandboxexports.If
InMemorySandboxStore,SandboxStore, orSandboxRecordare published to@tanstack/ai-sandbox, dropping these exports is a compile-time breaking change. Add deprecated re-exports, document the migration to@tanstack/ai, or release this as a deliberate breaking change.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ai-sandbox/src/index.ts` around lines 18 - 28, Preserve the legacy `@tanstack/ai-sandbox` exports InMemorySandboxStore, SandboxStore, and SandboxRecord by adding deprecated compatibility re-exports that point to their replacements in `@tanstack/ai`, and document the migration path. Keep the current SandboxInstanceStore exports intact.tombeckenham approved these changes
tombeckenham merged this1cb04d5
tombeckenham closed this
Sign in to join this conversation.
📝 Walkthrough
Walkthrough#
Adds durable sandbox instance resume through a new store capability, middleware integration, conformance testkit, documentation, package exports, and tests for create-once and resume-on-subsequent-request behavior.
Changes#
Sandbox instance durability
packages/ai-sandbox/src/instance-store.ts,packages/ai-sandbox/src/capabilities.ts,packages/ai-sandbox/src/index.ts,packages/ai-sandbox/src/sandbox.tspackages/ai-sandbox/src/middleware.ts,packages/ai-sandbox/tests/ensure.test.ts,packages/ai-sandbox/tests/resume-from-store.test.ts,packages/ai-sandbox/src/workspace.tspackages/ai-sandbox/src/testkit/*,packages/ai-sandbox/package.json,packages/ai-sandbox/vite.config.ts,packages/ai-sandbox/tests/store.test.tstesting/e2e/src/routes/api.sandbox-durability.ts,testing/e2e/src/routeTree.gen.ts,testing/e2e/tests/sandbox-durability.spec.ts,testing/e2e/package.jsondocs/sandbox/durability.md,docs/sandbox/overview.md,docs/config.json,docs/advanced/locks.md,packages/ai-sandbox/skills/ai-sandbox/SKILL.md,.changeset/sandbox-durability.mdEstimated code review effort: 4 (Complex) | ~45 minutes
Suggested reviewers:
jherrSequence Diagram(s)#
🚥 Pre-merge checks | ✅ 3 | ❌ 2
❌ Failed checks (2 warnings)#
✅ Passed checks (3 passed)
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
❤️ Share