@tanstack/ai-sandbox 0.2.4 → 0.3.0

package/src/tool-history.ts

@@ -0,0 +1,245 @@
+/**
+ * Turn a harness's PASSTHROUGH tool-call chunks into transcript messages, so a
+ * finished run's tool cards survive a reload.
+ *
+ * Why this is needed at all: a harness executes its tools INSIDE the sandbox, so
+ * `chat()` only relays its `TOOL_CALL_*` chunks — it never writes an assistant
+ * message for them (`addAssistantToolCallMessage` is gated on the engine having
+ * executed the tool itself). Chat persistence stores `ctx.messages`, so the whole
+ * tool history existed only in the delivery log. Replaying that log is what makes
+ * "switch away and come back" show everything; a FINISHED thread has no run to
+ * rejoin, hydrates from the message store instead, and so came back as nothing but
+ * the prompt and the final answer.
+ *
+ * Recording the calls as ordinary `toolCalls` + `role: 'tool'` messages needs no new
+ * wire format and no client change: `modelMessagesToUIMessages` already merges a tool
+ * result into the call it belongs to and marks the part complete, and
+ * `reconstructChat` already runs that converter.
+ */
+import { EventType } from '@tanstack/ai'
+import type { ModelMessage, StreamChunk } from '@tanstack/ai'
+
+/**
+ * Metadata key set on every tool call recorded here.
+ *
+ * INTERNAL, and deliberately not exported: an app asks {@link isSandboxToolCall}
+ * instead of knowing the key. Renaming it is a storage-visible change, because it ends
+ * up inside stored `toolCalls[].metadata`, so the recorder test pins the literal.
+ */
+const SANDBOX_OBSERVED = 'sandboxObserved'
+
+/**
+ * What the recorder writes into. `ChatMiddlewareContext.messages` is a
+ * `ReadonlyArray`, so the transcript grows by REPLACING the array — the same way the
+ * engine itself syncs `middlewareCtx.messages`.
+ */
+interface TranscriptTarget {
+  messages: ReadonlyArray<ModelMessage>
+}
+
+interface OpenCall {
+  name: string
+  /** Accumulated `TOOL_CALL_ARGS` deltas; superseded by `input` when the adapter sends it. */
+  args: string
+}
+
+export interface ToolHistoryRecorder {
+  /** Feed every chunk. Observes only — never transforms or drops. */
+  observe: (chunk: StreamChunk, target: TranscriptTarget) => void
+  /**
+   * Re-append anything missing from the transcript.
+   *
+   * The engine reassigns `middlewareCtx.messages` from its own array whenever it
+   * syncs config (once per agent iteration), which discards writes made during the
+   * previous iteration's stream. Reconciling at each iteration boundary and again at
+   * finish makes the result independent of that, and independent of where this
+   * middleware sits relative to persistence in the middleware array.
+   */
+  reconcile: (target: TranscriptTarget) => void
+}
+
+/**
+ * True when this tool call was executed by the HARNESS inside the sandbox, and
+ * recorded into the transcript for display, rather than executed by the agent loop.
+ *
+ * Use it to decide what your own `MessageStore` keeps — these calls are display
+ * history, so dropping or capping them is safe (they are already stripped from the
+ * request to the model on the next turn). Also works on a `tool-call` UI part, whose
+ * `metadata` is copied straight from the model message.
+ *
+ * `metadata` is `unknown` on both, so the key can only be read behind a typeof/`in`
+ * check; this mirrors the core `isProviderExecutedToolCall` convention.
+ *
+ * ```ts
+ * import { isSandboxToolCall } from '@tanstack/ai-sandbox'
+ *
+ * const kept = messages.filter(
+ *   (message) => !message.toolCalls?.every(isSandboxToolCall),
+ * )
+ * ```
+ */
+export function isSandboxToolCall(
+  toolCall: { metadata?: unknown } | null | undefined,
+): boolean {
+  const metadata = toolCall?.metadata
+  return (
+    typeof metadata === 'object' &&
+    metadata !== null &&
+    SANDBOX_OBSERVED in metadata &&
+    metadata[SANDBOX_OBSERVED] === true
+  )
+}
+
+/** Does the transcript already carry this tool call, from any source? */
+function hasCall(messages: ReadonlyArray<ModelMessage>, id: string): boolean {
+  return messages.some((message) =>
+    message.toolCalls?.some((call) => call.id === id),
+  )
+}
+
+/** Does the transcript already carry this tool result? */
+function hasResult(messages: ReadonlyArray<ModelMessage>, id: string): boolean {
+  return messages.some(
+    (message) => message.role === 'tool' && message.toolCallId === id,
+  )
+}
+
+function callMessage(id: string, name: string, args: string): ModelMessage {
+  return {
+    role: 'assistant',
+    content: null,
+    toolCalls: [
+      {
+        id,
+        type: 'function',
+        function: { name, arguments: args },
+        metadata: { [SANDBOX_OBSERVED]: true },
+      },
+    ],
+  }
+}
+
+function resultMessage(id: string, content: string): ModelMessage {
+  return { role: 'tool', toolCallId: id, content }
+}
+
+export function createToolHistoryRecorder(): ToolHistoryRecorder {
+  const open = new Map<string, OpenCall>()
+  /** Completed calls in the order they ran — the order `reconcile` restores. */
+  const recorded: Array<{ id: string; name: string; args: string }> = []
+  const results = new Map<string, string>()
+
+  function appendCall(
+    target: TranscriptTarget,
+    id: string,
+    name: string,
+    args: string,
+  ): void {
+    // An id already present is either the engine's own (it executed the tool itself)
+    // or a chunk seen before — a journal replay on takeover re-emits the whole
+    // stream. Either way a second write would duplicate the card.
+    if (hasCall(target.messages, id)) return
+    target.messages = [...target.messages, callMessage(id, name, args)]
+  }
+
+  function appendResult(
+    target: TranscriptTarget,
+    id: string,
+    content: string,
+  ): void {
+    if (hasResult(target.messages, id)) return
+    target.messages = [...target.messages, resultMessage(id, content)]
+  }
+
+  const recorder: ToolHistoryRecorder = {
+    // An if/else chain rather than a `switch`: only four of the ~20 chunk types are
+    // interesting here, and a `switch` on `chunk.type` has to enumerate all of them
+    // to satisfy the exhaustiveness lint.
+    observe(chunk, target) {
+      if (chunk.type === EventType.TOOL_CALL_START) {
+        // `toolCallName` is the AG-UI field; `toolName` is its deprecated alias, and
+        // that alias is what several harness adapters still emit.
+        const name = chunk.toolCallName ?? chunk.toolName
+        if (!name) return
+        open.set(chunk.toolCallId, { name, args: '' })
+        return
+      }
+      if (chunk.type === EventType.TOOL_CALL_ARGS) {
+        const call = open.get(chunk.toolCallId)
+        if (!call) return
+        // `args` is the accumulated-so-far field. Prefer it over stitching deltas:
+        // an adapter that sends both would otherwise double the arguments.
+        call.args = chunk.args ?? call.args + chunk.delta
+        return
+      }
+      if (chunk.type === EventType.TOOL_CALL_END) {
+        const call = open.get(chunk.toolCallId)
+        if (!call) return
+        open.delete(chunk.toolCallId)
+        // `input` is the final PARSED input, so it beats the streamed string, which
+        // can be a truncated fragment if the arguments stream was cut short.
+        const args =
+          chunk.input !== undefined ? JSON.stringify(chunk.input) : call.args
+        recorded.push({ id: chunk.toolCallId, name: call.name, args })
+        appendCall(target, chunk.toolCallId, call.name, args)
+        return
+      }
+      if (chunk.type === EventType.TOOL_CALL_RESULT) {
+        // AG-UI types `content` as a string; anything else is not a result we can
+        // store as a `role: 'tool'` message.
+        if (typeof chunk.content !== 'string') return
+        results.set(chunk.toolCallId, chunk.content)
+        appendResult(target, chunk.toolCallId, chunk.content)
+      }
+    },
+
+    reconcile(target) {
+      for (const { id, name, args } of recorded) {
+        appendCall(target, id, name, args)
+        const result = results.get(id)
+        // The result goes straight after its own call, so a restored transcript reads
+        // in the order the tools actually ran.
+        if (result !== undefined) appendResult(target, id, result)
+      }
+    },
+  }
+  return recorder
+}
+
+/**
+ * Drop recorded harness tool calls from a list of messages bound for the model.
+ *
+ * A stored transcript becomes the history for the NEXT turn. These calls name tools
+ * the provider was never given, and one triage-sized run is hundreds of kilobytes of
+ * tool output — so replaying them is wasteful at best and rejected at worst. They stay
+ * in `ctx.messages` (which is what gets stored and rendered); only the request to the
+ * model loses them.
+ *
+ * An assistant message is dropped only when EVERY call on it is observed, so a mixed
+ * message — one engine tool call plus one harness tool call — is left alone rather than
+ * silently losing the engine's half.
+ */
+export function stripObservedToolCalls(
+  messages: ReadonlyArray<ModelMessage>,
+): Array<ModelMessage> {
+  const dropped = new Set<string>()
+  const kept: Array<ModelMessage> = []
+  for (const message of messages) {
+    const calls = message.toolCalls
+    if (calls && calls.length > 0 && calls.every(isSandboxToolCall)) {
+      for (const call of calls) dropped.add(call.id)
+      continue
+    }
+    // Orphaning a result is worse than keeping it: a provider rejects a tool result
+    // whose call is not in the history.
+    if (
+      message.role === 'tool' &&
+      message.toolCallId !== undefined &&
+      dropped.has(message.toolCallId)
+    ) {
+      continue
+    }
+    kept.push(message)
+  }
+  return kept
+}

package/src/workspace.ts

@@ -137,7 +137,7 @@ export interface WorkspaceDefinition {
   /**
    * Typed secret references. The underlying values are injected into the
    * sandbox env at create/resume — NEVER written to snapshots, the
-   * SandboxStore, or the event log.
+   * SandboxInstanceStore, or the event log.
    */
   secrets?: Secrets
   /** Workspace root inside the sandbox. Defaults to `/workspace`. */

package/dist/esm/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/run-log.d.ts

@@ -1,81 +0,0 @@
-import { StreamChunk } from '@tanstack/ai';
-/** A terminal run status: no further events will be appended. */
-export type TerminalRunStatus = 'done' | 'error' | 'aborted';
-/** Lifecycle status of a run. `done`/`error`/`aborted` are terminal. */
-export type RunStatus = 'running' | TerminalRunStatus;
-/** Whether a run status is terminal (no further events will be appended). */
-export declare function isTerminalRunStatus(status: RunStatus): boolean;
-export interface RunError {
-    message: string;
-    code?: string;
-}
-/** Durable bookkeeping for a single run. */
-export interface RunRecord {
-    runId: string;
-    threadId?: string;
-    status: RunStatus;
-    /** Seq of the last appended event, or `-1` when no events yet. */
-    lastSeq: number;
-    error?: RunError;
-    createdAt: number;
-    updatedAt: number;
-}
-/** One persisted event: a chunk plus its monotonic, gap-free sequence number. */
-export interface RunEvent {
-    seq: number;
-    chunk: StreamChunk;
-}
-export interface RunEventLogReadOptions {
-    /**
-     * Exclusive cursor: only events with `seq > fromSeq` are yielded. Pass the
-     * client's last-seen `seq` to resume; omit (or `-1`) to replay from the start.
-     */
-    fromSeq?: number;
-    /** Stop tailing when this fires (e.g. the client disconnected). */
-    signal?: AbortSignal;
-}
-/**
- * Append-only, `seq`-indexed log of a run's stream, with resumable reads.
- *
- * Contract:
- * - `append` assigns the next `seq` (0, 1, 2, …) and returns it.
- * - `read` yields the backlog after `fromSeq` in order, then live-tails new
- *   events, and RETURNS once the run is terminal and the cursor has caught up.
- * - All methods reject for an unknown `runId` except `get`, which resolves null.
- */
-export interface RunEventLog {
-    /** Idempotently create (or return) the run record. */
-    open: (input: {
-        runId: string;
-        threadId?: string;
-    }) => Promise<RunRecord>;
-    /** Append one chunk; resolves with its assigned `seq`. */
-    append: (runId: string, chunk: StreamChunk) => Promise<number>;
-    /** Move the run to a terminal status. Idempotent for the same status. */
-    finish: (runId: string, status: TerminalRunStatus, error?: RunError) => Promise<void>;
-    /** Current record, or null if the run is unknown. */
-    get: (runId: string) => Promise<RunRecord | null>;
-    /** Replay-then-tail events with `seq > fromSeq` until the run is terminal. */
-    read: (runId: string, options?: RunEventLogReadOptions) => AsyncIterable<RunEvent>;
-}
-/**
- * Single-process {@link RunEventLog}. Backs `read`'s live-tail with an internal
- * waiter set: `append`/`finish` wake every blocked reader. Suitable for a
- * long-running Node host, tests, and as the reference implementation a durable
- * backend mirrors.
- */
-export declare class InMemoryRunEventLog implements RunEventLog {
-    private readonly runs;
-    private now;
-    private require;
-    private wake;
-    open(input: {
-        runId: string;
-        threadId?: string;
-    }): Promise<RunRecord>;
-    append(runId: string, chunk: StreamChunk): Promise<number>;
-    finish(runId: string, status: TerminalRunStatus, error?: RunError): Promise<void>;
-    get(runId: string): Promise<RunRecord | null>;
-    read(runId: string, options?: RunEventLogReadOptions): AsyncIterable<RunEvent>;
-    private waitForChange;
-}

package/dist/esm/run-log.js

@@ -1,107 +0,0 @@
-const TERMINAL = /* @__PURE__ */ new Set([
-  "done",
-  "error",
-  "aborted"
-]);
-function isTerminalRunStatus(status) {
-  return TERMINAL.has(status);
-}
-class InMemoryRunEventLog {
-  runs = /* @__PURE__ */ new Map();
-  now() {
-    return Date.now();
-  }
-  require(runId) {
-    const state = this.runs.get(runId);
-    if (!state) throw new Error(`run-log: unknown runId "${runId}"`);
-    return state;
-  }
-  wake(state) {
-    const waiters = [...state.waiters];
-    state.waiters.clear();
-    for (const resolve of waiters) resolve();
-  }
-  // Mutators return a Promise without `async` so contract violations REJECT
-  // (rather than throwing synchronously from a Promise-typed method — a
-  // `.catch()` footgun) without an `await`-less async body.
-  open(input) {
-    const existing = this.runs.get(input.runId);
-    if (existing) return Promise.resolve({ ...existing.record });
-    const now = this.now();
-    const record = {
-      runId: input.runId,
-      ...input.threadId !== void 0 ? { threadId: input.threadId } : {},
-      status: "running",
-      lastSeq: -1,
-      createdAt: now,
-      updatedAt: now
-    };
-    this.runs.set(input.runId, { record, chunks: [], waiters: /* @__PURE__ */ new Set() });
-    return Promise.resolve({ ...record });
-  }
-  append(runId, chunk) {
-    const state = this.runs.get(runId);
-    if (!state) {
-      return Promise.reject(new Error(`run-log: unknown runId "${runId}"`));
-    }
-    if (isTerminalRunStatus(state.record.status)) {
-      return Promise.reject(
-        new Error(
-          `run-log: cannot append to terminal run "${runId}" (status=${state.record.status})`
-        )
-      );
-    }
-    const seq = state.record.lastSeq + 1;
-    state.chunks.push(chunk);
-    state.record.lastSeq = seq;
-    state.record.updatedAt = this.now();
-    this.wake(state);
-    return Promise.resolve(seq);
-  }
-  finish(runId, status, error) {
-    const state = this.runs.get(runId);
-    if (!state) {
-      return Promise.reject(new Error(`run-log: unknown runId "${runId}"`));
-    }
-    if (isTerminalRunStatus(state.record.status)) return Promise.resolve();
-    state.record.status = status;
-    if (error !== void 0) state.record.error = error;
-    state.record.updatedAt = this.now();
-    this.wake(state);
-    return Promise.resolve();
-  }
-  get(runId) {
-    const state = this.runs.get(runId);
-    return Promise.resolve(state ? { ...state.record } : null);
-  }
-  async *read(runId, options) {
-    const state = this.require(runId);
-    const signal = options?.signal;
-    let cursor = options?.fromSeq ?? -1;
-    while (!signal?.aborted) {
-      while (cursor < state.record.lastSeq) {
-        cursor += 1;
-        const chunk = state.chunks[cursor];
-        if (chunk !== void 0) yield { seq: cursor, chunk };
-      }
-      if (isTerminalRunStatus(state.record.status)) return;
-      await this.waitForChange(state, signal);
-    }
-  }
-  waitForChange(state, signal) {
-    return new Promise((resolve) => {
-      const wake = () => {
-        state.waiters.delete(wake);
-        if (signal) signal.removeEventListener("abort", wake);
-        resolve();
-      };
-      state.waiters.add(wake);
-      if (signal) signal.addEventListener("abort", wake, { once: true });
-    });
-  }
-}
-export {
-  InMemoryRunEventLog,
-  isTerminalRunStatus
-};
-//# sourceMappingURL=run-log.js.map

package/dist/esm/run-log.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"run-log.js","sources":["../../src/run-log.ts"],"sourcesContent":["/**\n * Resumable run event-log — the primitive that lets a trigger (e.g. a\n * Cloudflare Worker) start an agent run and return immediately while a durable\n * orchestrator (e.g. a Durable Object) drives the run and persists every\n * emitted {@link StreamChunk} under a monotonic `seq`.\n *\n * Clients tail the log from a cursor (`fromSeq`), so a dropped connection, a new\n * browser tab, or an orchestrator that hibernated between chunks all reconnect\n * cleanly: replay everything after the client's last-seen `seq`, then live-tail\n * until the run reaches a terminal status. The *run* never depends on any single\n * connection staying open — that is what makes the serverless/edge model work.\n *\n * This module is transport- and storage-agnostic. {@link InMemoryRunEventLog} is\n * the default (single-process / tests); a durable backend (DO storage, KV, SQL)\n * implements the same {@link RunEventLog} interface — see the Cloudflare example.\n */\nimport type { StreamChunk } from '@tanstack/ai'\n\n/** A terminal run status: no further events will be appended. */\nexport type TerminalRunStatus = 'done' | 'error' | 'aborted'\n\n/** Lifecycle status of a run. `done`/`error`/`aborted` are terminal. */\nexport type RunStatus = 'running' | TerminalRunStatus\n\nconst TERMINAL: ReadonlySet<RunStatus> = new Set<RunStatus>([\n  'done',\n  'error',\n  'aborted',\n])\n\n/** Whether a run status is terminal (no further events will be appended). */\nexport function isTerminalRunStatus(status: RunStatus): boolean {\n  return TERMINAL.has(status)\n}\n\nexport interface RunError {\n  message: string\n  code?: string\n}\n\n/** Durable bookkeeping for a single run. */\nexport interface RunRecord {\n  runId: string\n  threadId?: string\n  status: RunStatus\n  /** Seq of the last appended event, or `-1` when no events yet. */\n  lastSeq: number\n  error?: RunError\n  createdAt: number\n  updatedAt: number\n}\n\n/** One persisted event: a chunk plus its monotonic, gap-free sequence number. */\nexport interface RunEvent {\n  seq: number\n  chunk: StreamChunk\n}\n\nexport interface RunEventLogReadOptions {\n  /**\n   * Exclusive cursor: only events with `seq > fromSeq` are yielded. Pass the\n   * client's last-seen `seq` to resume; omit (or `-1`) to replay from the start.\n   */\n  fromSeq?: number\n  /** Stop tailing when this fires (e.g. the client disconnected). */\n  signal?: AbortSignal\n}\n\n/**\n * Append-only, `seq`-indexed log of a run's stream, with resumable reads.\n *\n * Contract:\n * - `append` assigns the next `seq` (0, 1, 2, …) and returns it.\n * - `read` yields the backlog after `fromSeq` in order, then live-tails new\n *   events, and RETURNS once the run is terminal and the cursor has caught up.\n * - All methods reject for an unknown `runId` except `get`, which resolves null.\n */\nexport interface RunEventLog {\n  /** Idempotently create (or return) the run record. */\n  open: (input: { runId: string; threadId?: string }) => Promise<RunRecord>\n  /** Append one chunk; resolves with its assigned `seq`. */\n  append: (runId: string, chunk: StreamChunk) => Promise<number>\n  /** Move the run to a terminal status. Idempotent for the same status. */\n  finish: (\n    runId: string,\n    status: TerminalRunStatus,\n    error?: RunError,\n  ) => Promise<void>\n  /** Current record, or null if the run is unknown. */\n  get: (runId: string) => Promise<RunRecord | null>\n  /** Replay-then-tail events with `seq > fromSeq` until the run is terminal. */\n  read: (\n    runId: string,\n    options?: RunEventLogReadOptions,\n  ) => AsyncIterable<RunEvent>\n}\n\n/** Per-run state for the in-memory log. */\ninterface RunState {\n  record: RunRecord\n  chunks: Array<StreamChunk>\n  /** Resolved (and cleared) whenever an event is appended or status changes. */\n  waiters: Set<() => void>\n}\n\n/**\n * Single-process {@link RunEventLog}. Backs `read`'s live-tail with an internal\n * waiter set: `append`/`finish` wake every blocked reader. Suitable for a\n * long-running Node host, tests, and as the reference implementation a durable\n * backend mirrors.\n */\nexport class InMemoryRunEventLog implements RunEventLog {\n  private readonly runs = new Map<string, RunState>()\n\n  private now(): number {\n    return Date.now()\n  }\n\n  private require(runId: string): RunState {\n    const state = this.runs.get(runId)\n    if (!state) throw new Error(`run-log: unknown runId \"${runId}\"`)\n    return state\n  }\n\n  private wake(state: RunState): void {\n    const waiters = [...state.waiters]\n    state.waiters.clear()\n    for (const resolve of waiters) resolve()\n  }\n\n  // Mutators return a Promise without `async` so contract violations REJECT\n  // (rather than throwing synchronously from a Promise-typed method — a\n  // `.catch()` footgun) without an `await`-less async body.\n  open(input: { runId: string; threadId?: string }): Promise<RunRecord> {\n    const existing = this.runs.get(input.runId)\n    if (existing) return Promise.resolve({ ...existing.record })\n    const now = this.now()\n    const record: RunRecord = {\n      runId: input.runId,\n      ...(input.threadId !== undefined ? { threadId: input.threadId } : {}),\n      status: 'running',\n      lastSeq: -1,\n      createdAt: now,\n      updatedAt: now,\n    }\n    this.runs.set(input.runId, { record, chunks: [], waiters: new Set() })\n    return Promise.resolve({ ...record })\n  }\n\n  append(runId: string, chunk: StreamChunk): Promise<number> {\n    const state = this.runs.get(runId)\n    if (!state) {\n      return Promise.reject(new Error(`run-log: unknown runId \"${runId}\"`))\n    }\n    if (isTerminalRunStatus(state.record.status)) {\n      return Promise.reject(\n        new Error(\n          `run-log: cannot append to terminal run \"${runId}\" (status=${state.record.status})`,\n        ),\n      )\n    }\n    // Derive seq from the record's cursor (not `chunks.length`) so the gap-free\n    // invariant holds the same way the durable backend computes it, even if the\n    // backlog is ever trimmed/compacted.\n    const seq = state.record.lastSeq + 1\n    state.chunks.push(chunk)\n    state.record.lastSeq = seq\n    state.record.updatedAt = this.now()\n    this.wake(state)\n    return Promise.resolve(seq)\n  }\n\n  finish(\n    runId: string,\n    status: TerminalRunStatus,\n    error?: RunError,\n  ): Promise<void> {\n    const state = this.runs.get(runId)\n    if (!state) {\n      return Promise.reject(new Error(`run-log: unknown runId \"${runId}\"`))\n    }\n    if (isTerminalRunStatus(state.record.status)) return Promise.resolve()\n    state.record.status = status\n    if (error !== undefined) state.record.error = error\n    state.record.updatedAt = this.now()\n    this.wake(state)\n    return Promise.resolve()\n  }\n\n  get(runId: string): Promise<RunRecord | null> {\n    const state = this.runs.get(runId)\n    return Promise.resolve(state ? { ...state.record } : null)\n  }\n\n  async *read(\n    runId: string,\n    options?: RunEventLogReadOptions,\n  ): AsyncIterable<RunEvent> {\n    const state = this.require(runId)\n    const signal = options?.signal\n    let cursor = options?.fromSeq ?? -1\n    while (!signal?.aborted) {\n      while (cursor < state.record.lastSeq) {\n        cursor += 1\n        const chunk = state.chunks[cursor]\n        if (chunk !== undefined) yield { seq: cursor, chunk }\n      }\n      if (isTerminalRunStatus(state.record.status)) return\n      await this.waitForChange(state, signal)\n    }\n  }\n\n  private waitForChange(state: RunState, signal?: AbortSignal): Promise<void> {\n    return new Promise<void>((resolve) => {\n      const wake = (): void => {\n        state.waiters.delete(wake)\n        if (signal) signal.removeEventListener('abort', wake)\n        resolve()\n      }\n      state.waiters.add(wake)\n      if (signal) signal.addEventListener('abort', wake, { once: true })\n    })\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/store.d.ts

@@ -1,53 +0,0 @@
-/**
- * Persistence seams for the sandbox layer.
- *
- * v1 ships ONLY in-memory implementations (single-process resume). These are
- * deliberately pluggable OPTIONAL capabilities so the future persistence
- * package can `provide` durable implementations (D1/Postgres/Durable Objects)
- * without the sandbox layer changing. Do NOT hardcode storage here.
- */
-/** One persisted sandbox instance, keyed by the compound sandbox instance key. */
-export interface SandboxRecord {
-    /** 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 persistence layer). */
-    updatedAt: number;
-}
-/** Maps a compound key to the provider sandbox that should be resumed. */
-export interface SandboxStore {
-    get: (key: string) => Promise<SandboxRecord | null>;
-    upsert: (record: SandboxRecord) => Promise<void>;
-    delete: (key: string) => Promise<void>;
-}
-/**
- * Mutual exclusion around sandbox ensure so two concurrent runs for the same
- * thread don't both create a sandbox. The in-memory default is single-process;
- * the persistence layer provides a distributed lock (e.g. a Durable Object).
- */
-export interface LockStore {
-    withLock: <T>(key: string, fn: () => Promise<T>) => Promise<T>;
-}
-/** In-memory {@link SandboxStore}. Resume works only within one process. */
-export declare class InMemorySandboxStore implements SandboxStore {
-    private readonly map;
-    get(key: string): Promise<SandboxRecord | null>;
-    upsert(record: SandboxRecord): Promise<void>;
-    delete(key: string): Promise<void>;
-}
-/**
- * In-memory {@link LockStore} — a per-key promise chain. Correct within a
- * single process; multi-instance correctness needs a distributed lock from the
- * persistence layer.
- */
-export declare class InMemoryLockStore implements LockStore {
-    private readonly chains;
-    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
-}

package/dist/esm/store.js

@@ -1,34 +0,0 @@
-class InMemorySandboxStore {
-  map = /* @__PURE__ */ new Map();
-  get(key) {
-    return Promise.resolve(this.map.get(key) ?? null);
-  }
-  upsert(record) {
-    this.map.set(record.key, record);
-    return Promise.resolve();
-  }
-  delete(key) {
-    this.map.delete(key);
-    return Promise.resolve();
-  }
-}
-class InMemoryLockStore {
-  chains = /* @__PURE__ */ new Map();
-  withLock(key, fn) {
-    const prior = this.chains.get(key) ?? Promise.resolve();
-    const run = prior.then(fn, fn);
-    this.chains.set(
-      key,
-      run.then(
-        () => void 0,
-        () => void 0
-      )
-    );
-    return run;
-  }
-}
-export {
-  InMemoryLockStore,
-  InMemorySandboxStore
-};
-//# sourceMappingURL=store.js.map

package/dist/esm/store.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"store.js","sources":["../../src/store.ts"],"sourcesContent":["/**\n * Persistence seams for the sandbox layer.\n *\n * v1 ships ONLY in-memory implementations (single-process resume). These are\n * deliberately pluggable OPTIONAL capabilities so the future persistence\n * package can `provide` durable implementations (D1/Postgres/Durable Objects)\n * without the sandbox layer changing. Do NOT hardcode storage here.\n */\n\n/** One persisted sandbox instance, keyed by the compound sandbox instance key. */\nexport interface SandboxRecord {\n  /** Compound key (see computeSandboxKey). */\n  key: string\n  /** Provider name that owns `providerSandboxId`. */\n  provider: string\n  /** Provider-assigned sandbox id used to resume. */\n  providerSandboxId: string\n  /** Most recent snapshot id, when the provider supports snapshots. */\n  latestSnapshotId?: string\n  threadId: string\n  latestRunId?: string\n  /** Epoch ms of last write (for keepAlive / GC by the persistence layer). */\n  updatedAt: number\n}\n\n/** Maps a compound key to the provider sandbox that should be resumed. */\nexport interface SandboxStore {\n  get: (key: string) => Promise<SandboxRecord | null>\n  upsert: (record: SandboxRecord) => Promise<void>\n  delete: (key: string) => Promise<void>\n}\n\n/**\n * Mutual exclusion around sandbox ensure so two concurrent runs for the same\n * thread don't both create a sandbox. The in-memory default is single-process;\n * the persistence layer provides a distributed lock (e.g. a Durable Object).\n */\nexport interface LockStore {\n  withLock: <T>(key: string, fn: () => Promise<T>) => Promise<T>\n}\n\n/** In-memory {@link SandboxStore}. Resume works only within one process. */\nexport class InMemorySandboxStore implements SandboxStore {\n  private readonly map = new Map<string, SandboxRecord>()\n\n  get(key: string): Promise<SandboxRecord | null> {\n    return Promise.resolve(this.map.get(key) ?? null)\n  }\n\n  upsert(record: SandboxRecord): Promise<void> {\n    this.map.set(record.key, record)\n    return Promise.resolve()\n  }\n\n  delete(key: string): Promise<void> {\n    this.map.delete(key)\n    return Promise.resolve()\n  }\n}\n\n/**\n * In-memory {@link LockStore} — a per-key promise chain. Correct within a\n * single process; multi-instance correctness needs a distributed lock from the\n * persistence layer.\n */\nexport class InMemoryLockStore implements LockStore {\n  private readonly chains = new Map<string, Promise<unknown>>()\n\n  withLock<T>(key: string, fn: () => Promise<T>): Promise<T> {\n    const prior = this.chains.get(key) ?? Promise.resolve()\n    // Chain after the prior holder regardless of how it settled.\n    const run = prior.then(fn, fn)\n    // Keep the chain alive but swallow rejections so one failure doesn't poison the lock.\n    this.chains.set(\n      key,\n      run.then(\n        () => undefined,\n        () => undefined,\n      ),\n    )\n    return run\n  }\n}\n"],"names":[],"mappings":"AA0CO,MAAM,qBAA6C;AAAA,EACvC,0BAAU,IAAA;AAAA,EAE3B,IAAI,KAA4C;AAC9C,WAAO,QAAQ,QAAQ,KAAK,IAAI,IAAI,GAAG,KAAK,IAAI;AAAA,EAClD;AAAA,EAEA,OAAO,QAAsC;AAC3C,SAAK,IAAI,IAAI,OAAO,KAAK,MAAM;AAC/B,WAAO,QAAQ,QAAA;AAAA,EACjB;AAAA,EAEA,OAAO,KAA4B;AACjC,SAAK,IAAI,OAAO,GAAG;AACnB,WAAO,QAAQ,QAAA;AAAA,EACjB;AACF;AAOO,MAAM,kBAAuC;AAAA,EACjC,6BAAa,IAAA;AAAA,EAE9B,SAAY,KAAa,IAAkC;AACzD,UAAM,QAAQ,KAAK,OAAO,IAAI,GAAG,KAAK,QAAQ,QAAA;AAE9C,UAAM,MAAM,MAAM,KAAK,IAAI,EAAE;AAE7B,SAAK,OAAO;AAAA,MACV;AAAA,MACA,IAAI;AAAA,QACF,MAAM;AAAA,QACN,MAAM;AAAA,MAAA;AAAA,IACR;AAEF,WAAO;AAAA,EACT;AACF;"}