@tanstack/ai-sandbox 0.2.4 → 0.3.0

package/dist/esm/driver.d.ts

@@ -0,0 +1,83 @@
+import { InternalLogger } from '@tanstack/ai/adapter-internals';
+import { LockStore } from '@tanstack/ai/locks';
+import { RunDriverOptions, RunStore, StreamChunk, StreamDurability } from '@tanstack/ai';
+export interface SandboxRunDriverOptions<TOffset extends string = string> {
+    /** The attach request; core reads its run id with `resolveResumeRunId`. */
+    request: Request;
+    runs: RunStore;
+    locks: LockStore;
+    /**
+     * Per-run event log factory, the same shape `RunDeps.durability` takes — a
+     * `StreamDurability` is bound to one run, so the log is resolved FROM the
+     * `runId` rather than handed in pre-bound.
+     *
+     * Generic in the offset type, defaulted to `string` so an existing call site
+     * needs no change. Hardcoding the default made a branded-cursor backend
+     * unusable here: `durableStream` returns
+     * `StreamDurability<DurableStreamOffset>`, which is not assignable to
+     * `StreamDurability<string>` because `read` is contravariant in its offset.
+     */
+    durability: (runId: string) => StreamDurability<TOffset>;
+    /** Produce the run's remaining events. Called only once the claim is held. */
+    drive: (input: {
+        runId: string;
+        threadId: string;
+        signal: AbortSignal;
+    }) => AsyncIterable<StreamChunk>;
+    /** Quiescence window; defaults to {@link DEFAULT_FENCE_QUIET_MS}. */
+    fenceQuietMs?: number;
+    /** Platform keep-alive (e.g. `ctx.waitUntil`) for the background drive. */
+    waitUntil?: (promise: Promise<unknown>) => void;
+    logger?: InternalLogger;
+}
+/**
+ * `pipe` ran without a held claim. Not a recoverable condition: it means the
+ * returned options object was taken apart and `pipe` called outside `claim`, so
+ * there is no epoch to fence with and no lease guaranteeing exclusivity. Any
+ * append made in that state is exactly the duplicate-write bug the claim exists
+ * to prevent, so this fails loudly rather than appending unfenced.
+ */
+export declare class RunDriverPipeOutsideClaimError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/**
+ * Fill in a core `driver` block with this package's claim and run log.
+ *
+ * `drive` receives an `AbortSignal` — the driver owns the abort, so it hands
+ * out a signal rather than a controller — but `chat()` takes an
+ * `AbortController`. Mirror one onto the other, exactly as
+ * {@link https://tanstack.com/ai/latest/docs/sandbox/takeover | Takeover & Detached Runs}'s
+ * `controllerFor` does, so a lost claim actually stops the drive.
+ *
+ * @example
+ * ```typescript
+ * function controllerFor(signal: AbortSignal): AbortController {
+ *   const controller = new AbortController()
+ *   const abort = (): void => controller.abort(signal.reason)
+ *   if (signal.aborted) abort()
+ *   else signal.addEventListener('abort', abort, { once: true })
+ *   return controller
+ * }
+ *
+ * export async function GET(request: Request) {
+ *   return resumeServerSentEventsResponse({
+ *     adapter: memoryStream(request),
+ *     driver: sandboxRunDriver({
+ *       request,
+ *       runs,
+ *       locks,
+ *       durability: (runId) => logFor(runId),
+ *       drive: ({ runId, threadId, signal }) =>
+ *         chat({
+ *           ...config,
+ *           runId,
+ *           threadId,
+ *           abortController: controllerFor(signal),
+ *         }),
+ *     }),
+ *   })
+ * }
+ * ```
+ */
+export declare function sandboxRunDriver<TOffset extends string = string>(input: SandboxRunDriverOptions<TOffset>): RunDriverOptions;

package/dist/esm/driver.js

@@ -0,0 +1,138 @@
+import { awaitLogQuiescence, fenceDurability, fenceRunStore, withRunClaim } from "./claim.js";
+import { pipeToRunLog } from "./run.js";
+//#region src/driver.ts
+/**
+* The convenience that turns core's *injected* takeover seams into this
+* package's real ones.
+*
+* `@tanstack/ai`'s `RunDriverOptions` deliberately takes `claim` and `pipe` as
+* functions instead of importing them: {@link withRunClaim} and
+* {@link pipeToRunLog} live here, and core must not depend on this package to
+* serve a plain chat run. {@link sandboxRunDriver} fills both in so an
+* application writes four fields instead of six, and — more importantly — so
+* the *fencing* is wired correctly by construction rather than by every caller
+* remembering to.
+*
+* WHAT IS EASY TO GET WRONG HERE, and therefore what this module exists to
+* make impossible:
+*
+* 1. **Carrying the real epoch into `pipe`.** Core's `pipe` receives only
+*    `{ runId, threadId, signal }` — no epoch — because core has no concept of
+*    one. But {@link fenceDurability} needs the epoch this driver actually
+*    acquired: a hardcoded epoch (say `0`) is not a weaker fence, it is a
+*    permanently *tripped* one, since `withRunClaim` bumps `driverEpoch` to at
+*    least `1` before `fn` ever runs, so `observed > claim.epoch` holds on the
+*    very first append and EVERY takeover fails. The claim is therefore
+*    captured in a closure by the `claim` wrapper and read back by `pipe`.
+* 2. **Fencing `close()`.** {@link fenceDurability} wraps only `append` for the
+*    reason spelled out in `claim.ts`: `close()` runs on every teardown path,
+*    including the teardown caused by losing the claim, and a fenced `close`
+*    would wedge the record at `'running'` with every live tailer parked
+*    forever. This module must not add a second fence around it.
+* 2b. **Fencing only ONE of the two authoritative seams.** A run's facts live in
+*    its log *and* in its record, and `pipeToRunLog` reacts to a refused append
+*    by writing a terminal record — so wrapping the log alone just moves the harm
+*    from "a dead host poisons the successor's stream" to "a dead host marks the
+*    successor's live run failed". {@link fenceRunStore} must be wired here too,
+*    over the SAME claim, which is what makes the two fences share one latch.
+* 3. **Skipping quiescence.** The successor's first append must come after the
+*    stored log has stopped growing, so a predecessor still writing is observed
+*    rather than raced. The gate belongs inside `pipe`, before `pipeToRunLog`
+*    takes its first `snapshot`.
+*/
+/**
+* `pipe` ran without a held claim. Not a recoverable condition: it means the
+* returned options object was taken apart and `pipe` called outside `claim`, so
+* there is no epoch to fence with and no lease guaranteeing exclusivity. Any
+* append made in that state is exactly the duplicate-write bug the claim exists
+* to prevent, so this fails loudly rather than appending unfenced.
+*/
+var RunDriverPipeOutsideClaimError = class extends Error {
+	runId;
+	constructor(runId) {
+		super(`run ${runId}: sandboxRunDriver.pipe was called outside its claim, so the driver epoch is unknown; call it from within the claim callback`);
+		this.runId = runId;
+		this.name = "RunDriverPipeOutsideClaimError";
+	}
+};
+/**
+* Fill in a core `driver` block with this package's claim and run log.
+*
+* `drive` receives an `AbortSignal` — the driver owns the abort, so it hands
+* out a signal rather than a controller — but `chat()` takes an
+* `AbortController`. Mirror one onto the other, exactly as
+* {@link https://tanstack.com/ai/latest/docs/sandbox/takeover | Takeover & Detached Runs}'s
+* `controllerFor` does, so a lost claim actually stops the drive.
+*
+* @example
+* ```typescript
+* function controllerFor(signal: AbortSignal): AbortController {
+*   const controller = new AbortController()
+*   const abort = (): void => controller.abort(signal.reason)
+*   if (signal.aborted) abort()
+*   else signal.addEventListener('abort', abort, { once: true })
+*   return controller
+* }
+*
+* export async function GET(request: Request) {
+*   return resumeServerSentEventsResponse({
+*     adapter: memoryStream(request),
+*     driver: sandboxRunDriver({
+*       request,
+*       runs,
+*       locks,
+*       durability: (runId) => logFor(runId),
+*       drive: ({ runId, threadId, signal }) =>
+*         chat({
+*           ...config,
+*           runId,
+*           threadId,
+*           abortController: controllerFor(signal),
+*         }),
+*     }),
+*   })
+* }
+* ```
+*/
+function sandboxRunDriver(input) {
+	const fenceQuietMs = input.fenceQuietMs ?? 5e3;
+	let current;
+	return {
+		request: input.request,
+		runs: input.runs,
+		locks: input.locks,
+		drive: input.drive,
+		claim: (claimInput, fn) => withRunClaim({
+			...claimInput,
+			fenceQuietMs,
+			...input.logger === void 0 ? {} : { logger: input.logger }
+		}, async (claim) => {
+			const previous = current;
+			current = claim;
+			try {
+				return await fn(claim);
+			} finally {
+				current = previous;
+			}
+		}),
+		pipe: async (stream, i) => {
+			const claim = current;
+			if (claim === void 0) throw new RunDriverPipeOutsideClaimError(i.runId);
+			await awaitLogQuiescence(input.durability(i.runId), fenceQuietMs);
+			return pipeToRunLog(stream, {
+				runs: fenceRunStore(input.runs, claim, { ...input.logger === void 0 ? {} : { logger: input.logger } }),
+				durability: (runId) => fenceDurability(input.durability(runId), claim, { runs: input.runs }),
+				runId: i.runId,
+				threadId: i.threadId,
+				signal: i.signal,
+				...input.logger === void 0 ? {} : { logger: input.logger }
+			});
+		},
+		...input.waitUntil === void 0 ? {} : { waitUntil: input.waitUntil },
+		...input.logger === void 0 ? {} : { logger: input.logger }
+	};
+}
+//#endregion
+export { RunDriverPipeOutsideClaimError, sandboxRunDriver };
+
+//# sourceMappingURL=driver.js.map

package/dist/esm/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","names":[],"sources":["../../src/driver.ts"],"sourcesContent":["/**\n * The convenience that turns core's *injected* takeover seams into this\n * package's real ones.\n *\n * `@tanstack/ai`'s `RunDriverOptions` deliberately takes `claim` and `pipe` as\n * functions instead of importing them: {@link withRunClaim} and\n * {@link pipeToRunLog} live here, and core must not depend on this package to\n * serve a plain chat run. {@link sandboxRunDriver} fills both in so an\n * application writes four fields instead of six, and — more importantly — so\n * the *fencing* is wired correctly by construction rather than by every caller\n * remembering to.\n *\n * WHAT IS EASY TO GET WRONG HERE, and therefore what this module exists to\n * make impossible:\n *\n * 1. **Carrying the real epoch into `pipe`.** Core's `pipe` receives only\n *    `{ runId, threadId, signal }` — no epoch — because core has no concept of\n *    one. But {@link fenceDurability} needs the epoch this driver actually\n *    acquired: a hardcoded epoch (say `0`) is not a weaker fence, it is a\n *    permanently *tripped* one, since `withRunClaim` bumps `driverEpoch` to at\n *    least `1` before `fn` ever runs, so `observed > claim.epoch` holds on the\n *    very first append and EVERY takeover fails. The claim is therefore\n *    captured in a closure by the `claim` wrapper and read back by `pipe`.\n * 2. **Fencing `close()`.** {@link fenceDurability} wraps only `append` for the\n *    reason spelled out in `claim.ts`: `close()` runs on every teardown path,\n *    including the teardown caused by losing the claim, and a fenced `close`\n *    would wedge the record at `'running'` with every live tailer parked\n *    forever. This module must not add a second fence around it.\n * 2b. **Fencing only ONE of the two authoritative seams.** A run's facts live in\n *    its log *and* in its record, and `pipeToRunLog` reacts to a refused append\n *    by writing a terminal record — so wrapping the log alone just moves the harm\n *    from \"a dead host poisons the successor's stream\" to \"a dead host marks the\n *    successor's live run failed\". {@link fenceRunStore} must be wired here too,\n *    over the SAME claim, which is what makes the two fences share one latch.\n * 3. **Skipping quiescence.** The successor's first append must come after the\n *    stored log has stopped growing, so a predecessor still writing is observed\n *    rather than raced. The gate belongs inside `pipe`, before `pipeToRunLog`\n *    takes its first `snapshot`.\n */\nimport { pipeToRunLog } from './run'\nimport {\n  DEFAULT_FENCE_QUIET_MS,\n  awaitLogQuiescence,\n  fenceDurability,\n  fenceRunStore,\n  withRunClaim,\n} from './claim'\nimport type { RunClaim } from './claim'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\nimport type { LockStore } from '@tanstack/ai/locks'\nimport type {\n  RunDriverOptions,\n  RunStore,\n  StreamChunk,\n  StreamDurability,\n} from '@tanstack/ai'\n\nexport interface SandboxRunDriverOptions<TOffset extends string = string> {\n  /** The attach request; core reads its run id with `resolveResumeRunId`. */\n  request: Request\n  runs: RunStore\n  locks: LockStore\n  /**\n   * Per-run event log factory, the same shape `RunDeps.durability` takes — a\n   * `StreamDurability` is bound to one run, so the log is resolved FROM the\n   * `runId` rather than handed in pre-bound.\n   *\n   * Generic in the offset type, defaulted to `string` so an existing call site\n   * needs no change. Hardcoding the default made a branded-cursor backend\n   * unusable here: `durableStream` returns\n   * `StreamDurability<DurableStreamOffset>`, which is not assignable to\n   * `StreamDurability<string>` because `read` is contravariant in its offset.\n   */\n  durability: (runId: string) => StreamDurability<TOffset>\n  /** Produce the run's remaining events. Called only once the claim is held. */\n  drive: (input: {\n    runId: string\n    threadId: string\n    signal: AbortSignal\n  }) => AsyncIterable<StreamChunk>\n  /** Quiescence window; defaults to {@link DEFAULT_FENCE_QUIET_MS}. */\n  fenceQuietMs?: number\n  /** Platform keep-alive (e.g. `ctx.waitUntil`) for the background drive. */\n  waitUntil?: (promise: Promise<unknown>) => void\n  logger?: InternalLogger\n}\n\n/**\n * `pipe` ran without a held claim. Not a recoverable condition: it means the\n * returned options object was taken apart and `pipe` called outside `claim`, so\n * there is no epoch to fence with and no lease guaranteeing exclusivity. Any\n * append made in that state is exactly the duplicate-write bug the claim exists\n * to prevent, so this fails loudly rather than appending unfenced.\n */\nexport class RunDriverPipeOutsideClaimError extends Error {\n  constructor(readonly runId: string) {\n    super(\n      `run ${runId}: sandboxRunDriver.pipe was called outside its claim, so the driver epoch is unknown; call it from within the claim callback`,\n    )\n    this.name = 'RunDriverPipeOutsideClaimError'\n  }\n}\n\n/**\n * Fill in a core `driver` block with this package's claim and run log.\n *\n * `drive` receives an `AbortSignal` — the driver owns the abort, so it hands\n * out a signal rather than a controller — but `chat()` takes an\n * `AbortController`. Mirror one onto the other, exactly as\n * {@link https://tanstack.com/ai/latest/docs/sandbox/takeover | Takeover & Detached Runs}'s\n * `controllerFor` does, so a lost claim actually stops the drive.\n *\n * @example\n * ```typescript\n * function controllerFor(signal: AbortSignal): AbortController {\n *   const controller = new AbortController()\n *   const abort = (): void => controller.abort(signal.reason)\n *   if (signal.aborted) abort()\n *   else signal.addEventListener('abort', abort, { once: true })\n *   return controller\n * }\n *\n * export async function GET(request: Request) {\n *   return resumeServerSentEventsResponse({\n *     adapter: memoryStream(request),\n *     driver: sandboxRunDriver({\n *       request,\n *       runs,\n *       locks,\n *       durability: (runId) => logFor(runId),\n *       drive: ({ runId, threadId, signal }) =>\n *         chat({\n *           ...config,\n *           runId,\n *           threadId,\n *           abortController: controllerFor(signal),\n *         }),\n *     }),\n *   })\n * }\n * ```\n */\nexport function sandboxRunDriver<TOffset extends string = string>(\n  input: SandboxRunDriverOptions<TOffset>,\n): RunDriverOptions {\n  const fenceQuietMs = input.fenceQuietMs ?? DEFAULT_FENCE_QUIET_MS\n  // The seam between core's `claim` and core's `pipe`. One options object serves\n  // one attach request and therefore one run, so a single slot is enough; it is\n  // cleared on the way out so a `pipe` after the claim released cannot reuse a\n  // stale epoch.\n  let current: RunClaim | undefined\n\n  return {\n    request: input.request,\n    runs: input.runs,\n    locks: input.locks,\n    drive: input.drive,\n    claim: (claimInput, fn) =>\n      withRunClaim(\n        {\n          ...claimInput,\n          fenceQuietMs,\n          ...(input.logger === undefined ? {} : { logger: input.logger }),\n        },\n        async (claim) => {\n          const previous = current\n          current = claim\n          try {\n            return await fn(claim)\n          } finally {\n            current = previous\n          }\n        },\n      ),\n    pipe: async (stream, i) => {\n      const claim = current\n      if (claim === undefined) {\n        throw new RunDriverPipeOutsideClaimError(i.runId)\n      }\n      // Before the first append, never after: `pipeToRunLog` snapshots to align\n      // and a predecessor still writing must be observed, not raced.\n      await awaitLogQuiescence(input.durability(i.runId), fenceQuietMs)\n      return pipeToRunLog(stream, {\n        // BOTH authoritative seams are fenced at the epoch this driver actually\n        // acquired, and they must be: `pipeToRunLog` answers a refused append by\n        // recording a terminal record, so fencing only the log leaves a\n        // superseded host marking a live run `'failed'` (see `fenceRunStore`).\n        // Neither fence covers `close()` — that stays unfenced on purpose.\n        runs: fenceRunStore(input.runs, claim, {\n          ...(input.logger === undefined ? {} : { logger: input.logger }),\n        }),\n        durability: (runId) =>\n          fenceDurability(input.durability(runId), claim, {\n            runs: input.runs,\n          }),\n        runId: i.runId,\n        threadId: i.threadId,\n        signal: i.signal,\n        ...(input.logger === undefined ? {} : { logger: input.logger }),\n      })\n    },\n    ...(input.waitUntil === undefined ? {} : { waitUntil: input.waitUntil }),\n    ...(input.logger === undefined ? {} : { logger: input.logger }),\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FA,IAAa,iCAAb,cAAoD,MAAM;CACnC;CAArB,YAAY,OAAwB;EAClC,MACE,OAAO,MAAM,6HACf;EAHmB,KAAA,QAAA;EAInB,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,iBACd,OACkB;CAClB,MAAM,eAAe,MAAM,gBAAA;CAK3B,IAAI;CAEJ,OAAO;EACL,SAAS,MAAM;EACf,MAAM,MAAM;EACZ,OAAO,MAAM;EACb,OAAO,MAAM;EACb,QAAQ,YAAY,OAClB,aACE;GACE,GAAG;GACH;GACA,GAAI,MAAM,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,MAAM,OAAO;EAC/D,GACA,OAAO,UAAU;GACf,MAAM,WAAW;GACjB,UAAU;GACV,IAAI;IACF,OAAO,MAAM,GAAG,KAAK;GACvB,UAAU;IACR,UAAU;GACZ;EACF,CACF;EACF,MAAM,OAAO,QAAQ,MAAM;GACzB,MAAM,QAAQ;GACd,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,+BAA+B,EAAE,KAAK;GAIlD,MAAM,mBAAmB,MAAM,WAAW,EAAE,KAAK,GAAG,YAAY;GAChE,OAAO,aAAa,QAAQ;IAM1B,MAAM,cAAc,MAAM,MAAM,OAAO,EACrC,GAAI,MAAM,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,MAAM,OAAO,EAC/D,CAAC;IACD,aAAa,UACX,gBAAgB,MAAM,WAAW,KAAK,GAAG,OAAO,EAC9C,MAAM,MAAM,KACd,CAAC;IACH,OAAO,EAAE;IACT,UAAU,EAAE;IACZ,QAAQ,EAAE;IACV,GAAI,MAAM,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,MAAM,OAAO;GAC/D,CAAC;EACH;EACA,GAAI,MAAM,cAAc,KAAA,IAAY,CAAC,IAAI,EAAE,WAAW,MAAM,UAAU;EACtE,GAAI,MAAM,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,MAAM,OAAO;CAC/D;AACF"}

package/dist/esm/durability.d.ts

@@ -0,0 +1,263 @@
+import { JournalOptions } from './runner.js';
+import { InternalLogger } from '@tanstack/ai/adapter-internals';
+import { RunStore, StreamChunk, StreamDurability } from '@tanstack/ai';
+/** `withSandbox(sandbox, { durability })`. */
+export interface SandboxDurabilityOptions<TOffset extends string = string> {
+    /**
+     * Delivery-durable event log for the run. Same key and shape as the
+     * transport's `durability.adapter`, so one adapter instance can be handed to
+     * both `withSandbox` and `toServerSentEventsResponse`.
+     *
+     * Generic in the offset type, defaulted to `string`, for the same reason
+     * {@link SandboxRunDriverOptions} and {@link ReapOptions} are:
+     * `StreamDurability` is INVARIANT in `TOffset` (`read` takes an offset in),
+     * so a backend that brands its cursors — `@tanstack/ai-durable-stream`'s
+     * `durableStream`, the multi-host production backend the sandbox docs point
+     * at — is not assignable to `StreamDurability<string>`. Without the parameter
+     * the resume route could be wired with it and the route that STARTS the run
+     * could not.
+     */
+    adapter: StreamDurability<TOffset>;
+    /** Journal directory inside the sandbox. Defaults to `/tmp/tanstack-runs`. */
+    journal?: string;
+    /**
+     * Whether a client disconnect DETACHES (leave the agent running) instead of
+     * destroying the sandbox. Defaults to `true` whenever durability is wired,
+     * because that is the whole point of wiring it.
+     *
+     * Set `false` to keep today's destroy-on-disconnect cost profile while still
+     * getting resumable DELIVERY (a reload replays the log). An explicit cancel
+     * destroys either way.
+     */
+    detachOnDisconnect?: boolean;
+    /**
+     * Read an EXISTING run's journal instead of starting a new agent. Set by the
+     * attach route's `drive()` callback, never by an application's POST handler.
+     *
+     * This is where `attach` lives, and deliberately NOT on `chat()`: `chat()` is
+     * core and must not gain sandbox vocabulary, and the provider options are
+     * per-model type state, not per-request lifecycle.
+     */
+    attach?: boolean;
+    /** Journal poll interval for providers that cannot follow. */
+    pollIntervalMs?: number;
+    /**
+     * How long an ATTACH waits for a live run's journal to appear before failing
+     * with a `JournalAttachUnavailableError`. Defaults to
+     * `DEFAULT_ATTACH_JOURNAL_WAIT_MS` (10s). Only the wait is configurable: an
+     * unknown or terminal runId fails immediately regardless, since no amount of
+     * waiting changes either verdict.
+     */
+    attachWaitMs?: number;
+}
+/**
+ * The view of a caller's event log that the capability bus carries.
+ *
+ * Deliberately NOT the whole `StreamDurability`. `read` is the only member that
+ * takes an offset *in*, which is what makes `StreamDurability` invariant in
+ * `TOffset` and a branded-cursor backend unassignable to
+ * `StreamDurability<string>`. Every other member mentions the offset only in a
+ * return position, so this type is a genuine SUPERTYPE of
+ * `StreamDurability<TOffset>` for every `TOffset extends string` — which is the
+ * one property that lets a single concrete capability instantiation accept a
+ * branded backend. `createCapability<T>()` forces exactly one instantiation
+ * (the value type is a plain type argument, and TypeScript has no higher-kinded
+ * types), so the payload cannot be parameterized the way the *option* above is.
+ *
+ * Dropping `read` costs nothing, and that is a property of the seam rather than
+ * luck: the bus is the JOURNAL/ALIGNMENT seam, and alignment reads the stored
+ * prefix through `snapshot()` — never `read()`, which tails an open log forever
+ * (see `alignToStoredLog`). Replay *by offset* belongs to the delivery seam,
+ * and that seam (`toServerSentEventsResponse`, `sandboxRunDriver`) receives the
+ * application's own adapter directly, with its brand intact.
+ */
+export type SandboxDurabilityLog = Omit<StreamDurability, 'read'>;
+/**
+ * Resolved durability, published on the capability bus by `withSandbox`.
+ *
+ * Deliberately carries NO detached-run TTL. The only actor that enforces one is
+ * `reapDetachedRuns`, which runs from a cron with no chat in flight — so it has
+ * no `CapabilityContext` and cannot read this bus at all. A TTL published here
+ * could therefore only ever be read by nobody, while the sweep took its own
+ * `ReapOptions.detachedRunTtlMs`; the two would silently disagree. The reaper's
+ * required option is the single source of truth.
+ */
+export interface SandboxRunDurability {
+    runs: RunStore;
+    adapter: SandboxDurabilityLog;
+    journalDir: string;
+    attach: boolean;
+    detachOnDisconnect: boolean;
+    pollIntervalMs?: number;
+    attachWaitMs?: number;
+}
+/**
+ * Provided by `withSandbox` only when a run is genuinely durable (both stores
+ * wired). Harness adapters read it with `getOptional` and treat its absence as
+ * "no journaling contract to honour", which is exactly today's behavior.
+ */
+export declare const SandboxDurabilityCapability: import('@tanstack/ai').Capability<SandboxRunDurability, "sandbox-durability">;
+/** Destructured accessors, matching `./capabilities`. */
+export declare const getSandboxDurability: import('@tanstack/ai').CapabilityGetter<SandboxRunDurability>, provideSandboxDurability: import('@tanstack/ai').CapabilityProvider<SandboxRunDurability>;
+/**
+ * A durable run was started without a caller-supplied `runId`.
+ *
+ * Thrown rather than defaulted because the failure is otherwise INVISIBLE: an
+ * adapter-generated id (`${name}-${Date.now()}-${Math.random()...}`) produces a
+ * journal path at `/tmp/tanstack-runs/<id>.ndjson` that no successor host can
+ * recompute, so the run streams normally, records normally, and is silently
+ * unrecoverable. A loud failure at the start of `chatStream` is strictly better
+ * than a run that only reveals itself as non-durable during an incident.
+ */
+export declare class DurableRunIdRequiredError extends Error {
+    readonly adapter: string;
+    constructor(adapter: string);
+}
+/**
+ * Resolve the `runId` a harness adapter will journal under.
+ *
+ * Replaces the bare `options.runId ?? this.generateId()` in every harness
+ * adapter. The fallback is preserved for non-durable runs — several `chat()`
+ * paths pass `runId` as a conditional spread, so `undefined` is reachable and
+ * removing the fallback would break them for no benefit.
+ *
+ * The `durable` check runs BEFORE `fallback()`, and that ordering is load
+ * bearing: a generated id must never be minted for a durable run, not even one
+ * that is discarded, because the whole point is that no such id can exist.
+ */
+export declare function resolveDurableRunId(runId: string | undefined, options: {
+    durable: boolean;
+    adapter: string;
+    fallback: () => string;
+}): string;
+/**
+ * An ATTACHING durable run was driven without the run record's `threadId`.
+ *
+ * The sibling of {@link DurableRunIdRequiredError}, for the other id an attach
+ * cannot mint for itself. `threadId` lands in EVERY chunk a harness adapter
+ * emits (see each package's `stream/translate.ts`), so a replay that generates a
+ * fresh one produces a stream that differs from the stored log in its very first
+ * chunk. `alignToStoredLog` then fails at index 0 with a
+ * `JournalReplayThreadIdMismatchError` — mid-stream, after the takeover has
+ * already claimed the run. Refusing up front is strictly better, and mirrors
+ * what `resolveDurableRunId` does for an id whose absence is equally fatal.
+ *
+ * Core already does its part: `startRunDriver` reads the record and hands
+ * `active.threadId` to `drive({ runId, threadId, signal })`. This error exists
+ * for the one gap it cannot close — application `drive` code that forgets to
+ * forward it into `chat()`.
+ */
+export declare class DurableThreadIdRequiredError extends Error {
+    readonly adapter: string;
+    constructor(adapter: string);
+}
+/**
+ * Resolve the `threadId` a harness adapter will stamp on every chunk.
+ *
+ * Replaces the bare `options.threadId ?? this.generateId()` in the journaling
+ * harness adapters. Only the durable-AND-attaching quadrant throws; the other
+ * three keep the generated fallback and are byte-identical to before:
+ *
+ * | durable | attaching | behavior                                            |
+ * | ------- | --------- | --------------------------------------------------- |
+ * | no      | no        | fallback — a plain non-durable run                  |
+ * | no      | yes       | fallback — not reachable today, and harmless anyway |
+ * | yes     | no        | fallback — the FRESH run that ESTABLISHES the id    |
+ * | yes     | yes       | throw {@link DurableThreadIdRequiredError}          |
+ *
+ * The durable-fresh row is the load-bearing one. A fresh durable run legitimately
+ * mints its `threadId` (there is no record to reuse one from), so throwing on
+ * `durable` alone — the obvious over-simplification — would break every durable
+ * run that has ever worked. Only re-entering an existing run has an id it MUST
+ * reuse, which is exactly the condition `attach` already expresses.
+ *
+ * As in `resolveDurableRunId`, the guard runs BEFORE `fallback()`: a generated id
+ * must never be minted on this path, not even one that is then discarded.
+ */
+export declare function resolveDurableThreadId(threadId: string | undefined, options: {
+    durable: boolean;
+    attaching: boolean;
+    adapter: string;
+    fallback: () => string;
+}): string;
+/**
+ * An ATTACH was driven into a code path that can never replay a run.
+ *
+ * The third sibling of {@link DurableRunIdRequiredError} and
+ * {@link DurableThreadIdRequiredError}, and the one that is not about a missing
+ * id: here every id is present and the path itself is the problem.
+ *
+ * `sandboxRunDriver`'s `drive()` re-invokes `chat()` with `attach: true`. On a
+ * JOURNALING path that is genuinely a replay — `spawnNdjson` tails the journal
+ * the previous host wrote, `awaitAttachableJournal` refuses a hopeless attach up
+ * front, and `alignedIfAttaching` suppresses the prefix already delivered. A
+ * protocol path with none of those three has no journal to tail and nothing to
+ * align against, so `attach: true` does not resume anything: it starts the agent
+ * over from scratch against the workspace the first attempt already mutated, and
+ * appends its entire output to a log that still holds the first attempt's.
+ *
+ * Deliberately NOT a `JournalAttachUnavailableError`. That error means "a
+ * journal that should exist has not appeared yet" — retryable, scoped to a wait
+ * (`attachWaitMs`). This condition is categorically different: the path cannot
+ * attach AT ALL, so telling a caller to wait would point it at something that is
+ * never coming. A 5xx/501-shaped refusal, not a 504.
+ *
+ * `reason` names the missing capability in the adapter's own vocabulary (which
+ * protocol, which spawn path), because the fix is always to change how the run
+ * is spawned or routed, never to retry.
+ */
+export declare class DurableAttachNotSupportedError extends Error {
+    readonly adapter: string;
+    readonly reason: string;
+    constructor(adapter: string, reason: string);
+}
+/**
+ * Resolve `withSandbox`'s two durability options into the capability payload, or
+ * `undefined` when the app has not opted in.
+ *
+ * BOTH `runs` and `durability` are required. A half-configured app gets
+ * `undefined` **silently** rather than a warning: it has not asked for
+ * durability, so there is nothing to warn about, and the resulting behavior
+ * (destroy on disconnect, no journal) is exactly today's.
+ */
+export declare function resolveSandboxDurability<TOffset extends string = string>(options: {
+    runs?: RunStore;
+    durability?: SandboxDurabilityOptions<TOffset>;
+} | undefined): SandboxRunDurability | undefined;
+/**
+ * Build the `spawnNdjson` journal option for a run, or `undefined` when the run
+ * is not durable — in which case `spawnNdjson` takes its original, unjournaled
+ * path (`isJournaled` tests `options.journal !== undefined`, `runner.ts:70-72`)
+ * and behavior is byte-identical to a pre-durability run.
+ *
+ * `JournalOptions.dir` is optional, but this always supplies it: the resolved
+ * durability has already defaulted `journalDir`, and a successor host must
+ * recompute the same path rather than re-derive the default independently.
+ *
+ * `runs` and `attachWaitMs` are carried ONLY when attaching, and that is not a
+ * micro-optimization: they exist for `awaitAttachableJournal`, which the reader
+ * runs on the attach path alone. A fresh run has no journal yet BY DESIGN (its own
+ * `journaledCommand` spawn creates it moments later), so handing it a run store
+ * would only invite a future change to gate a path where absence proves nothing.
+ */
+export declare function journalOptionsFor(durability: SandboxRunDurability | undefined, runId: string): JournalOptions | undefined;
+/**
+ * Align a harness stream against the run's stored log — but ONLY on an attach.
+ *
+ * The `attach` guard is not an optimization, it is a CORRECTNESS requirement.
+ * `alignToStoredLog` snapshots the log before the first chunk is pulled and
+ * treats everything in that snapshot as "already delivered". On a FRESH run that
+ * premise is false: if such a run were aligned against a log that already holds
+ * entries — a `runId` collision, a retried request — its own chunks would be
+ * matched against those entries and silently SUPPRESSED instead of delivered,
+ * which is silent data loss rather than a slow path. Aligning only when
+ * re-entering an existing run keeps the transform's premise ("this stream is a
+ * replay of what is already stored") actually true.
+ *
+ * `isBridgeCustomChunk` is passed because the stored log holds the previous
+ * host's MERGED output, including live bridged-tool CUSTOM events that a replay
+ * cannot reproduce; without it a bridged-tool run could not be taken over at
+ * all. Wrap the merge RESULT, never the pre-merge translator, or the comparison
+ * is against a stream the log never contained.
+ */
+export declare function alignedIfAttaching(chunks: AsyncIterable<StreamChunk>, durability: SandboxRunDurability | undefined, logger?: InternalLogger): AsyncIterable<StreamChunk>;