@tanstack/ai-sandbox 0.2.4 → 0.3.0

package/src/index.ts

@@ -1,22 +1,32 @@
-// Capability tokens + accessors
+// Capability tokens + accessors (sandbox-owned only).
+// LockStore / withLocks / defineLock: import from @tanstack/ai/locks.
 export {
   SandboxCapability,
-  SandboxStoreCapability,
-  LocksCapability,
   SandboxPolicyCapability,
   ToolBridgeProvisionerCapability,
   getSandbox,
   provideSandbox,
-  getSandboxStore,
-  provideSandboxStore,
-  getLocks,
-  provideLocks,
   getSandboxPolicy,
   provideSandboxPolicy,
   getToolBridgeProvisioner,
   provideToolBridgeProvisioner,
 } from './capabilities'
 
+// Durable instance map (resume-or-create across processes).
+// Pass a store to `withSandbox(sandbox, { instances })`; the capability is the
+// ambient alternative for platform-level wiring.
+export {
+  SandboxInstanceStoreCapability,
+  getSandboxInstanceStore,
+  provideSandboxInstanceStore,
+  InMemorySandboxInstanceStore,
+  defineSandboxInstanceStore,
+} from './instance-store'
+export type {
+  SandboxInstanceStore,
+  SandboxInstanceRecord,
+} from './instance-store'
+
 // Workspace projection capability (provided by withSandbox, consumed by harness adapters)
 export {
   ProjectionCapability,
@@ -27,6 +37,13 @@ export type { WorkspaceProjection } from './projection'
 
 // Middleware
 export { withSandbox } from './middleware'
+export type { SandboxMiddlewareOptions } from './middleware'
+
+// Harness tool history: `withSandbox` records the tool calls a harness ran INSIDE the
+// sandbox into the transcript, so a finished run restores its tool cards. This is how
+// an app recognises them — e.g. in its own `MessageStore.saveThread`, to cap or drop
+// what it does not want to store.
+export { isSandboxToolCall } from './tool-history'
 
 // Sandbox definition + lifecycle
 export { defineSandbox } from './sandbox'
@@ -100,10 +117,6 @@ export type {
   SandboxDestroyInput,
 } from './contracts'
 
-// Stores (interfaces + in-memory defaults)
-export { InMemorySandboxStore, InMemoryLockStore } from './store'
-export type { SandboxStore, LockStore, SandboxRecord } from './store'
-
 // Bootstrap engine (exported for provider/adapter authors + tests)
 export {
   bootstrapWorkspace,
@@ -125,8 +138,191 @@ export {
 export { createExecBackedGit } from './git-exec'
 
 // Harness runner: spawn an agent CLI in a sandbox + stream NDJSON stdout
-export { spawnNdjson, toLines } from './runner'
-export type { SpawnNdjsonOptions } from './runner'
+export {
+  spawnNdjson,
+  toLines,
+  startJournaledAgent,
+  readJournalNdjson,
+} from './runner'
+export type { SpawnNdjsonOptions, JournalOptions } from './runner'
+
+// The agent output journal: the durability boundary for a sandboxed run.
+//
+// journalListCommand/journalMtimeListCommand/parseJournalMtimeListing back the
+// journal-directory sweep (`journal-sweep.ts`); journalExitProbeCommand/
+// parseJournalExit/parseExitSentinel back the reaper's out-of-band exit probe
+// (`reap.ts`) and the streaming reader, which must agree on what "the run
+// ended" means; EXIT_SENTINEL_NONCE_KEY/exitSentinelLine are what make that
+// sentinel unforgeable by the agent's own stdout and are needed by anything
+// that seeds a journal by hand (a fake host, a test); the
+// mechanism that lets a sweep learn a detached run finished WITHOUT driving
+// it; decodeJournalRunId recovers the runId a listed filename encodes, fail
+// closed. `encodeRunId` is exported for adapters that derive their OWN
+// in-sandbox paths from a caller-supplied `runId` (prompt files, MCP bridge
+// configs) and must not hand-roll a second, divergent encoder.
+// `normalizeJournalDir` is intentionally NOT exported: it is a path
+// formatting detail of this module's own commands, not something a caller
+// composes with.
+export {
+  DEFAULT_JOURNAL_DIR,
+  encodeRunId,
+  EXIT_SENTINEL_KEY,
+  EXIT_SENTINEL_NONCE_KEY,
+  exitSentinelLine,
+  parseExitSentinel,
+  journalPaths,
+  journaledCommand,
+  journalFollowCommand,
+  journalReadCommand,
+  journalExistsCommand,
+  journalListCommand,
+  journalMtimeListCommand,
+  parseJournalMtimeListing,
+  journalExitProbeCommand,
+  parseJournalExit,
+  decodeJournalRunId,
+} from './journal'
+export type {
+  JournalPaths,
+  JournalMtimeListing,
+  JournalDirEntry,
+  DecodedJournalRunId,
+} from './journal'
+
+// Journal-directory sweep: bound the journals a detached run's sentinel never
+// got OBSERVED for (see `journal-sweep.ts`'s module doc for why almost every
+// branch keeps rather than deletes — deleting a live run's journal makes it
+// unresumable, with no undo).
+export {
+  pruneJournals,
+  DEFAULT_ORPHAN_TTL_MS,
+  DEFAULT_MAX_DELETES,
+} from './journal-sweep'
+export type {
+  PruneJournalsOptions,
+  PruneJournalsResult,
+  KeptJournal,
+  KeptJournalReason,
+  PruneJournalsFailure,
+} from './journal-sweep'
+
+// Detached-run reaper: sweep a `RunStore`'s reclaimable runs, driving a run to
+// terminal ONLY once the out-of-band journal probe (`probeRunExit`) already
+// knows the agent exited, or once its TTL has expired — never to find out
+// whether it finished (see `reap.ts`'s module doc for why that design was
+// rejected).
+export {
+  reapDetachedRuns,
+  probeRunExit,
+  DEFAULT_RUN_BUDGET_MS,
+  DEFAULT_MAX_RUNS,
+  DEFAULT_EXIT_PROBE_BYTES,
+} from './reap'
+export type {
+  RunExitProbe,
+  ReapRunOutcome,
+  ReapRunEntry,
+  ReapResult,
+  ReapOptions,
+} from './reap'
+
+// Sandbox reclaim: tear down the sandbox behind a terminal run.
+// `sandboxReclaimer` adapts `reclaimSandbox` to `ReapOptions.reclaim`.
+export {
+  reclaimSandbox,
+  sandboxReclaimer,
+  SandboxReclaimFailedError,
+} from './reclaim'
+export type { ReclaimOutcome, ReclaimSandboxOptions } from './reclaim'
+export {
+  DEFAULT_JOURNAL_POLL_MS,
+  journalReadStrategy,
+  readJournal,
+} from './journal-reader'
+export type { ReadJournalOptions } from './journal-reader'
+export { decodeBase64Stream, toJournalLines } from './journal-bytes'
+export type { JournalLine } from './journal-bytes'
+export {
+  createRunScopedIdGen,
+  chunkFingerprint,
+  chunkFingerprintIgnoringThreadId,
+  chunkThreadId,
+} from './chunk-identity'
+export {
+  alignToStoredLog,
+  isBridgeCustomChunk,
+  JournalReplayDivergedError,
+  JournalReplayThreadIdMismatchError,
+  DEFAULT_MAX_OUT_OF_BAND_SKIP,
+} from './align'
+export type { AlignToStoredLogOptions } from './align'
+
+// Attach preflight: the gate that makes a hopeless attach fail instead of
+// tailing an empty journal forever. `JournalAttachUnavailableError` and its
+// `reason` are the branchable surface (404 / 410 / 504 at an attach route), and
+// the bounded-wait default is exported because it bounds an attach REQUEST.
+export {
+  awaitAttachableJournal,
+  JournalAttachUnavailableError,
+  DEFAULT_ATTACH_JOURNAL_WAIT_MS,
+  DEFAULT_ATTACH_PROBE_INTERVAL_MS,
+} from './attach-preflight'
+export type {
+  AttachUnavailableReason,
+  AwaitAttachableJournalOptions,
+} from './attach-preflight'
+
+// Durability seam: the `withSandbox(sandbox, { runs, durability })` option
+// shape, the capability harness adapters read back via `getSandboxDurability`,
+// and the two helpers that turn a resolved durability into the pieces a
+// harness adapter actually drives with — a `journalOptionsFor` journal option
+// and an attach-only `alignedIfAttaching` alignment transform.
+//
+// `resolveSandboxDurability` is deliberately NOT exported: it is
+// `withSandbox`'s own path from raw options to the capability payload (see
+// `middleware.ts`), and a harness adapter only ever needs the ALREADY-RESOLVED
+// value read back off the capability bus, never to re-run that resolution
+// itself.
+export {
+  SandboxDurabilityCapability,
+  getSandboxDurability,
+  provideSandboxDurability,
+  DurableAttachNotSupportedError,
+  DurableRunIdRequiredError,
+  DurableThreadIdRequiredError,
+  resolveDurableRunId,
+  resolveDurableThreadId,
+  journalOptionsFor,
+  alignedIfAttaching,
+} from './durability'
+export type {
+  SandboxDurabilityOptions,
+  SandboxDurabilityLog,
+  SandboxRunDurability,
+} from './durability'
+
+// Run driver: fills in core's injected takeover seams (`claim`/`pipe`) with
+// this package's single-writer claim (`claim.ts`) and run log (`run.ts`), so
+// an application wires `request`/`runs`/`locks`/`durability`/`drive` instead of
+// hand-rolling the claim/fence dance itself.
+//
+// `claim.ts`'s own primitives — `withRunClaim`, `fenceDurability`,
+// `awaitLogQuiescence`, `runDriverLockKey`, and their `RunClaim` /
+// `WithRunClaimOptions` types — are deliberately NOT exported. They are
+// exactly the "easy to get wrong" seam `sandboxRunDriver` exists to make
+// impossible (see `driver.ts`'s module doc, points 1-3), and publishing them
+// would invite the same hand-rolled fencing bugs as a supported path. The two
+// error classes below ARE exported despite that: both can surface through
+// `sandboxRunDriver` itself, so a caller needs `instanceof` to branch on them,
+// and `DEFAULT_FENCE_QUIET_MS` is exported because it is the documented
+// default for `sandboxRunDriver`'s own `fenceQuietMs` option.
+export { sandboxRunDriver, RunDriverPipeOutsideClaimError } from './driver'
+export type { SandboxRunDriverOptions } from './driver'
+export {
+  RunClaimNotAcquiredError,
+  RunClaimLostError,
+  DEFAULT_FENCE_QUIET_MS,
+} from './claim'
 
 // MCP tool-proxy bridge (shared by harness adapters): transport-agnostic core
 // + the node:http host transport + a fetch-friendly JSON-RPC dispatcher.
@@ -173,23 +369,12 @@ export type {
   ToolExecRequest,
 } from './remote-tools'
 
-// Resumable run event-log — the primitive that lets a trigger start a run and
-// return while a durable orchestrator drives it and clients tail from a cursor.
-export { InMemoryRunEventLog, isTerminalRunStatus } from './run-log'
-export type {
-  RunEventLog,
-  RunRecord,
-  RunEvent,
-  RunStatus,
-  TerminalRunStatus,
-  RunError,
-  RunEventLogReadOptions,
-} from './run-log'
-
-// Run driver — pump a chat() stream into the event-log so a trigger returns
+// Run driver — pumps a chat() stream into core's `StreamDurability` and
+// records run status/lifecycle in core's `RunStore`, so a trigger returns
 // immediately while a durable orchestrator drives the run and clients tail it.
 export { pipeToRunLog, RunController } from './run'
 export type {
+  RunDeps,
   PipeToRunLogOptions,
   RunControllerStartInput,
   RunHandle,

package/src/instance-store.ts

@@ -0,0 +1,122 @@
+/**
+ * Durable sandbox **instance** map — which provider sandbox (and snapshot) to
+ * resume for a compound key. Owned by `@tanstack/ai-sandbox` (not chat
+ * persistence): domain is runtime placement for `ensure`, not conversation state.
+ *
+ * Pass to `withSandbox(sandbox, { instances })`, which uses it in `ensure`
+ * (in-memory fallback when absent). {@link SandboxInstanceStoreCapability} is
+ * the ambient alternative for platform-level wiring.
+ */
+import { createCapability } from '@tanstack/ai'
+
+/** One persisted sandbox instance, keyed by the compound sandbox instance key. */
+export interface SandboxInstanceRecord {
+  /** Compound key (see `computeSandboxKey`). */
+  key: string
+  /** Provider name that owns `providerSandboxId`. */
+  provider: string
+  /** Provider-assigned sandbox id used to resume. */
+  providerSandboxId: string
+  /** Most recent snapshot id, when the provider supports snapshots. */
+  latestSnapshotId?: string
+  threadId: string
+  latestRunId?: string
+  /**
+   * Epoch ms of last write (for keepAlive / GC by the host app).
+   */
+  updatedAt: number
+}
+
+/**
+ * Maps a compound key to the provider sandbox that should be resumed.
+ *
+ * Implement against your own database (BYO). Prove the contract with
+ * `runSandboxInstanceStoreConformance` from `@tanstack/ai-sandbox/testkit`.
+ */
+export interface SandboxInstanceStore {
+  /**
+   * Return the record for `key`, or `null` if none exists.
+   *
+   * INVARIANT: missing keys return `null` (never throw).
+   */
+  get: (key: string) => Promise<SandboxInstanceRecord | null>
+  /**
+   * Insert or fully replace the record for `record.key`.
+   *
+   * INVARIANT (full replace): omitted optional fields (`latestSnapshotId`,
+   * `latestRunId`) MUST clear any previously stored values. Do not merge with
+   * the prior row — a create-without-snapshot path must not leave a stale
+   * snapshot id.
+   */
+  upsert: (record: SandboxInstanceRecord) => Promise<void>
+  /**
+   * Remove the record for `key`.
+   *
+   * INVARIANT: deleting a missing key is a **no-op** (must not throw).
+   */
+  delete: (key: string) => Promise<void>
+}
+
+/**
+ * Type a {@link SandboxInstanceStore} implementation inline: pass the object and
+ * get autocomplete + contract checking, with no separate
+ * `: SandboxInstanceStore` annotation. Hand the result to
+ * `withSandbox(sandbox, { instances })`. Matches `defineLock` /
+ * `defineMessageStore` style helpers elsewhere in the monorepo.
+ */
+export function defineSandboxInstanceStore(
+  store: SandboxInstanceStore,
+): SandboxInstanceStore {
+  return store
+}
+
+/**
+ * Capability for the instance map — the ambient alternative to
+ * `withSandbox(sandbox, { instances })`. Provide it from any middleware with
+ * {@link provideSandboxInstanceStore}; `withSandbox` reads it when no explicit
+ * option was passed.
+ */
+export const SandboxInstanceStoreCapability =
+  createCapability<SandboxInstanceStore>()('sandbox-instance-store')
+
+/** Destructured accessors: `getSandboxInstanceStore` / `provideSandboxInstanceStore`. */
+export const [getSandboxInstanceStore, provideSandboxInstanceStore] =
+  SandboxInstanceStoreCapability
+
+/** In-memory {@link SandboxInstanceStore}. Resume works only within one process. */
+export class InMemorySandboxInstanceStore implements SandboxInstanceStore {
+  private readonly map = new Map<string, SandboxInstanceRecord>()
+
+  get(key: string): Promise<SandboxInstanceRecord | null> {
+    return Promise.resolve(this.map.get(key) ?? null)
+  }
+
+  upsert(record: SandboxInstanceRecord): Promise<void> {
+    this.map.set(record.key, record)
+    return Promise.resolve()
+  }
+
+  delete(key: string): Promise<void> {
+    this.map.delete(key)
+    return Promise.resolve()
+  }
+}
+
+/**
+ * Wiring note: hand the store straight to the consumer —
+ * `withSandbox(sandbox, { instances: store })`. That cannot be mis-ordered,
+ * unlike a separate provider middleware composed after `withSandbox` (which
+ * silently degrades to the in-memory fallback).
+ *
+ * ```ts
+ * middleware: [
+ *   withLocks(locks), // from @tanstack/ai/locks — multi-replica
+ *   withSandbox(sandbox, { instances: instanceStore }),
+ * ]
+ * ```
+ *
+ * For ambient/platform wiring (a hosting layer injecting infra without touching
+ * the call site), any middleware may still
+ * `provideSandboxInstanceStore(ctx, store)` on the capability bus; an explicit
+ * option takes precedence over it.
+ */

package/src/journal-bytes.ts

@@ -0,0 +1,136 @@
+/**
+ * Byte-exact framing for journal reads.
+ *
+ * Both read paths end in {@link toJournalLines}, which counts absolute file
+ * offsets over BYTES, because a position is only useful if `tail -c +N` can
+ * resume from it. The two paths differ only in how they get bytes:
+ *
+ * - The **bounded** read is base64-framed (see `journal.ts` rule 2) and arrives
+ *   as one complete `ExecResult.stdout` string, so {@link decodeBase64Stream}
+ *   recovers the file's exact bytes regardless of how the provider decoded its
+ *   stdout.
+ * - The **follow** read cannot be base64-framed — the encoder's stdio buffer
+ *   would swallow the stream — so it arrives as provider-decoded text chunks
+ *   and {@link encodeUtf8Stream} turns them back into bytes.
+ *
+ * `atob`, not `Buffer`: this module runs on the host, and the host can itself be
+ * a Cloudflare Worker (`ai-sandbox-cloudflare` drives its sandbox over Workers
+ * RPC from Worker code), where `Buffer` is not a global unless the `nodejs_compat`
+ * flag is on. `atob` is a Web/DOM API available in every host runtime this
+ * package targets, so it is the portable choice here.
+ */
+
+const NEWLINE = 0x0a
+
+/** Decode one complete base64 quantum group to bytes. */
+function decodeQuantumGroup(group: string): Uint8Array {
+  const binary = atob(group)
+  const out = new Uint8Array(binary.length)
+  for (let index = 0; index < binary.length; index += 1) {
+    out[index] = binary.charCodeAt(index)
+  }
+  return out
+}
+
+/**
+ * Decode a streaming base64 frame into raw bytes.
+ *
+ * Whitespace is stripped because `base64(1)` wraps at 76 columns by default and
+ * busybox's build does not accept `-w 0`, so the wrapping cannot be turned off
+ * portably. Only complete 4-character quanta are decoded; a remainder is held
+ * for the next chunk. Padding (`=`) appears only in the final quantum, so an
+ * intermediate group always decodes to exactly 3 bytes.
+ */
+export async function* decodeBase64Stream(
+  chunks: AsyncIterable<string>,
+): AsyncIterable<Uint8Array> {
+  let pending = ''
+  for await (const chunk of chunks) {
+    pending += chunk.replace(/\s+/g, '')
+    const usable = pending.length - (pending.length % 4)
+    if (usable === 0) continue
+    const group = pending.slice(0, usable)
+    pending = pending.slice(usable)
+    yield decodeQuantumGroup(group)
+  }
+  if (pending.length > 0) {
+    // Fail loud. A remainder means the frame was cut off mid-quantum, i.e. the
+    // reader died partway through. Rounding it away would silently drop journal
+    // bytes and desync every position derived from this stream.
+    throw new Error(
+      `journal: base64 frame ended mid-quantum with ${pending.length} character(s) pending`,
+    )
+  }
+}
+
+/**
+ * Re-encode provider-decoded text chunks as UTF-8 bytes.
+ *
+ * This is the follow path's replacement for {@link decodeBase64Stream}: the
+ * follow command emits the journal's raw bytes, the provider hands them over as
+ * `AsyncIterable<string>`, and `TextEncoder` round-trips that text back to the
+ * bytes it was decoded from. Chunk boundaries do not need to fall on character
+ * boundaries here — {@link toJournalLines} buffers bytes until a newline, so a
+ * multi-byte character split across two chunks is reassembled there, exactly as
+ * it is on the base64 path.
+ *
+ * Empty chunks are dropped rather than forwarded: a zero-length `Uint8Array`
+ * carries no bytes and would only make the downstream loop spin.
+ */
+export async function* encodeUtf8Stream(
+  chunks: AsyncIterable<string>,
+): AsyncIterable<Uint8Array> {
+  const encoder = new TextEncoder()
+  for await (const chunk of chunks) {
+    if (chunk.length === 0) continue
+    yield encoder.encode(chunk)
+  }
+}
+
+/** One complete journal line plus the absolute byte position just past its newline. */
+export interface JournalLine {
+  /** The line's text, newline excluded. */
+  line: string
+  /**
+   * Absolute byte offset immediately AFTER this line's newline — i.e. the count
+   * of journal bytes fully consumed once this line has been handled, and
+   * therefore the exact value to resume a `tail -c +N` from.
+   */
+  endPosition: number
+}
+
+function concatBytes(left: Uint8Array, right: Uint8Array): Uint8Array {
+  const out = new Uint8Array(left.length + right.length)
+  out.set(left, 0)
+  out.set(right, left.length)
+  return out
+}
+
+/**
+ * Split a byte stream into newline-terminated lines, tracking absolute
+ * positions from `startPosition`.
+ *
+ * Deliberately unlike `toLines` in `runner.ts`, which yields a trailing
+ * unterminated line: here a trailing partial line is a line the agent is still
+ * writing. Yielding it would hand a truncated JSON string downstream AND
+ * advance the position past bytes the next read must re-see.
+ */
+export async function* toJournalLines(
+  byteChunks: AsyncIterable<Uint8Array>,
+  startPosition: number,
+): AsyncIterable<JournalLine> {
+  const decoder = new TextDecoder()
+  let buffer: Uint8Array = new Uint8Array(0)
+  let position = startPosition
+  for await (const bytes of byteChunks) {
+    buffer = concatBytes(buffer, bytes)
+    let newline = buffer.indexOf(NEWLINE)
+    while (newline !== -1) {
+      const lineBytes = buffer.subarray(0, newline)
+      position += newline + 1
+      yield { line: decoder.decode(lineBytes), endPosition: position }
+      buffer = buffer.slice(newline + 1)
+      newline = buffer.indexOf(NEWLINE)
+    }
+  }
+}