@tanstack/ai-sandbox 0.3.4 → 0.5.0

package/src/chunk-identity.ts

@@ -29,8 +29,16 @@
  *    exactly that field — nothing downstream keys on a chunk's timestamp, so
  *    leaving it wall-clock is safe, but every other field must participate in
  *    the comparison or a real divergence would go undetected.
+ * 3. Adapter yields still carry leftover TanStack extras (`content`, `args`,
+ *    `finishReason`). The durability log stores spec chunks. Fingerprints keep
+ *    only AG-UI spec keys and drop `metadata.tanstack`, so a live adapter yield
+ *    matches the stored spec chunk.
  */
 import type { StreamChunk } from '@tanstack/ai'
+import {
+  isSpecTopLevelKey,
+  tanstackMetadata,
+} from '@tanstack/ai/adapter-internals'
 
 /**
  * A deterministic id generator scoped to one run.
@@ -112,16 +120,37 @@ function stableStringify(
  *   cannot spuriously diverge.
  * - **Recurses into nested arrays and objects**: tool-call arguments are
  *   nested, and a shallow fingerprint would miss a changed argument.
- * - **Excludes exactly `VOLATILE_FIELDS`** (`timestamp`) — everything else
- *   participates, including fields whose value is `undefined`.
+ * - **Excludes `timestamp` and leftover adapter extras.** Spec keys
+ *   participate, including `undefined` values. `metadata.tanstack` is dropped
+ *   so stored spec chunks match live adapter yields.
  * - **Distinguishes present-but-`undefined` from absent**: `undefined` is
  *   encoded as the sentinel string `"__undefined__"` rather than dropped, so
  *   `{a: undefined}` and `{}` do not collide. A translator emitting an
  *   explicit `undefined` is a different chunk shape and must fingerprint
  *   differently.
  */
+function fingerprintableChunk(chunk: StreamChunk): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(chunk)) {
+    if (key === 'timestamp') continue
+    if (!isSpecTopLevelKey(chunk.type, key)) continue
+    if (key === 'metadata' && value != null && typeof value === 'object') {
+      const rest: Record<string, unknown> = {}
+      for (const [metaKey, metaValue] of Object.entries(value)) {
+        if (metaKey === 'tanstack') continue
+        rest[metaKey] = metaValue
+      }
+      if (Object.keys(rest).length === 0) continue
+      out.metadata = rest
+      continue
+    }
+    out[key] = value
+  }
+  return out
+}
+
 export function chunkFingerprint(chunk: StreamChunk): string {
-  return stableStringify(chunk, VOLATILE_FIELDS)
+  return stableStringify(fingerprintableChunk(chunk), VOLATILE_FIELDS)
 }
 
 /**
@@ -136,7 +165,7 @@ export function chunkFingerprint(chunk: StreamChunk): string {
  * `JournalReplayThreadIdMismatchError` in `align.ts`).
  */
 export function chunkFingerprintIgnoringThreadId(chunk: StreamChunk): string {
-  return stableStringify(chunk, VOLATILE_AND_THREAD_ID)
+  return stableStringify(fingerprintableChunk(chunk), VOLATILE_AND_THREAD_ID)
 }
 
 /**
@@ -150,5 +179,7 @@ export function chunkFingerprintIgnoringThreadId(chunk: StreamChunk): string {
 export function chunkThreadId(chunk: StreamChunk): string | undefined {
   const record: Record<string, unknown> = chunk as Record<string, unknown>
   const value = record[THREAD_ID_FIELD]
-  return typeof value === 'string' ? value : undefined
+  if (typeof value === 'string') return value
+  const nested = tanstackMetadata(chunk)?.threadId
+  return typeof nested === 'string' ? nested : undefined
 }

package/src/contracts.ts

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

package/src/index.ts

@@ -27,6 +27,61 @@ export type {
   SandboxInstanceRecord,
 } from './instance-store'
 
+// Portable immutable sandbox checkpoint metadata.
+export {
+  SandboxCheckpointError,
+  SandboxCheckpointConflictError,
+  SandboxCheckpointDuplicateIdError,
+  SandboxCheckpointInvalidIdError,
+  SandboxCheckpointInvalidEntryError,
+  SandboxCheckpointParentMismatchError,
+  SandboxCheckpointNotHeadError,
+  SandboxCheckpointWriterConflictError,
+  SandboxCheckpointWriterLostError,
+  isForkCapableSandboxCheckpointStore,
+  InMemorySandboxCheckpointStore,
+  defineSandboxCheckpointStore,
+} from './checkpoint-store'
+
+export type {
+  SandboxCheckpoint,
+  SandboxCheckpointStore,
+  SandboxSnapshotEntry,
+  SandboxSnapshotFileEntry,
+  SandboxSnapshotDirectoryEntry,
+  SandboxSnapshotArtifact,
+  SandboxCheckpointErrorCode,
+  SandboxCheckpointWriter,
+  SandboxCheckpointWriterLease,
+  SandboxCheckpointStoreOptions,
+  SandboxCheckpointForkInput,
+  SandboxCheckpointForkCapability,
+  ForkCapableSandboxCheckpointStore,
+} from './checkpoint-store'
+
+// File snapshot policy used by provider snapshot create/restore inputs.
+export { SandboxSnapshotError, defaultSandboxSnapshotPolicy } from './snapshots'
+export type {
+  SandboxSnapshotErrorCode,
+  SandboxSnapshotPolicy,
+} from './snapshots'
+export { memorySandboxSnapshots } from './memory-snapshots'
+export type {
+  MemorySandboxSnapshots,
+  MemorySandboxSnapshotsOptions,
+} from './memory-snapshots'
+export { createSandboxSnapshots } from './snapshot-operations'
+export type {
+  CreateSandboxSnapshotsInput,
+  ForkSandboxSnapshotInput,
+  ReadSandboxSnapshotArtifactInput,
+  SandboxSnapshots,
+  SaveSandboxSnapshotInput,
+  SnapshotPersistence,
+} from './snapshot-operations'
+export { createSnapshotTools } from './snapshot-tools'
+export type { CreateSnapshotToolsOptions } from './snapshot-tools'
+
 // Workspace projection capability (provided by withSandbox, consumed by harness adapters)
 export {
   ProjectionCapability,
@@ -102,6 +157,7 @@ export type {
   SandboxHandle,
   SandboxCapabilities,
   SandboxFs,
+  SandboxFsStat,
   SandboxGit,
   SandboxProcess,
   SandboxPorts,

package/src/memory-snapshot-types.ts

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