@tanstack/ai-sandbox 0.3.3 → 0.4.0

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
+  }
+}