Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

instance-store.ts

122 lines4.3 KB

1/**
2 * Durable sandbox **instance** map — which provider sandbox (and snapshot) to
3 * resume for a compound key. Owned by `@tanstack/ai-sandbox` (not chat
4 * persistence): domain is runtime placement for `ensure`, not conversation state.
5 *
6 * Pass to `withSandbox(sandbox, { instances })`, which uses it in `ensure`
7 * (in-memory fallback when absent). {@link SandboxInstanceStoreCapability} is
8 * the ambient alternative for platform-level wiring.
9 */
10import { createCapability } from '@tanstack/ai'
11​
12/** One persisted sandbox instance, keyed by the compound sandbox instance key. */
13export interface SandboxInstanceRecord {
14 /** Compound key (see `computeSandboxKey`). */
15 key: string
16 /** Provider name that owns `providerSandboxId`. */
17 provider: string
18 /** Provider-assigned sandbox id used to resume. */
19 providerSandboxId: string
20 /** Most recent snapshot id, when the provider supports snapshots. */
21 latestSnapshotId?: string
22 threadId: string
23 latestRunId?: string
24 /**
25 * Epoch ms of last write (for keepAlive / GC by the host app).
26 */
27 updatedAt: number
29​
30/**
31 * Maps a compound key to the provider sandbox that should be resumed.
32 *
33 * Implement against your own database (BYO). Prove the contract with
34 * `runSandboxInstanceStoreConformance` from `@tanstack/ai-sandbox/testkit`.
35 */
36export interface SandboxInstanceStore {
37 /**
38 * Return the record for `key`, or `null` if none exists.
39 *
40 * INVARIANT: missing keys return `null` (never throw).
41 */
42 get: (key: string) => Promise<SandboxInstanceRecord | null>
43 /**
44 * Insert or fully replace the record for `record.key`.
45 *
46 * INVARIANT (full replace): omitted optional fields (`latestSnapshotId`,
47 * `latestRunId`) MUST clear any previously stored values. Do not merge with
48 * the prior row — a create-without-snapshot path must not leave a stale
49 * snapshot id.
50 */
51 upsert: (record: SandboxInstanceRecord) => Promise<void>
52 /**
53 * Remove the record for `key`.
54 *
55 * INVARIANT: deleting a missing key is a **no-op** (must not throw).
56 */
57 delete: (key: string) => Promise<void>
59​
60/**
61 * Type a {@link SandboxInstanceStore} implementation inline: pass the object and
62 * get autocomplete + contract checking, with no separate
63 * `: SandboxInstanceStore` annotation. Hand the result to
64 * `withSandbox(sandbox, { instances })`. Matches `defineLock` /
65 * `defineMessageStore` style helpers elsewhere in the monorepo.
66 */
67export function defineSandboxInstanceStore(
68 store: SandboxInstanceStore,
69): SandboxInstanceStore {
70 return store
72​
73/**
74 * Capability for the instance map — the ambient alternative to
75 * `withSandbox(sandbox, { instances })`. Provide it from any middleware with
76 * {@link provideSandboxInstanceStore}; `withSandbox` reads it when no explicit
77 * option was passed.
78 */
79export const SandboxInstanceStoreCapability =
80 createCapability<SandboxInstanceStore>()('sandbox-instance-store')
81​
82/** Destructured accessors: `getSandboxInstanceStore` / `provideSandboxInstanceStore`. */
83export const [getSandboxInstanceStore, provideSandboxInstanceStore] =
84 SandboxInstanceStoreCapability
85​
86/** In-memory {@link SandboxInstanceStore}. Resume works only within one process. */
87export class InMemorySandboxInstanceStore implements SandboxInstanceStore {
88 private readonly map = new Map<string, SandboxInstanceRecord>()
89​
90 get(key: string): Promise<SandboxInstanceRecord | null> {
91 return Promise.resolve(this.map.get(key) ?? null)
92 }
93​
94 upsert(record: SandboxInstanceRecord): Promise<void> {
95 this.map.set(record.key, record)
96 return Promise.resolve()
97 }
98​
99 delete(key: string): Promise<void> {
100 this.map.delete(key)
101 return Promise.resolve()
102 }
104​
105/**
106 * Wiring note: hand the store straight to the consumer —
107 * `withSandbox(sandbox, { instances: store })`. That cannot be mis-ordered,
108 * unlike a separate provider middleware composed after `withSandbox` (which
109 * silently degrades to the in-memory fallback).
110 *
111 * ```ts
112 * middleware: [
113 * withLocks(locks), // from @tanstack/ai/locks — multi-replica
114 * withSandbox(sandbox, { instances: instanceStore }),
115 * ]
116 * ```
117 *
118 * For ambient/platform wiring (a hosting layer injecting infra without touching
119 * the call site), any middleware may still
120 * `provideSandboxInstanceStore(ctx, store)` on the capability bus; an explicit
121 * option takes precedence over it.
122 */