@tanstack/ai 0.42.0 → 0.43.1

package/dist/esm/activities/chat/middleware/run-store.d.ts

@@ -0,0 +1,283 @@
+import { TokenUsage } from '../../../types.js';
+/** A terminal run status: no further events will be appended. */
+export type TerminalRunStatus = 'completed' | 'failed' | 'aborted';
+/**
+ * Lifecycle status of one run (one agent turn within a conversation).
+ *
+ * `interrupted` is a human-in-the-loop PAUSE that interrupt-resume continues
+ * from — it is deliberately NOT terminal, and must never be conflated with
+ * `aborted` (an explicit cancellation).
+ *
+ * The two are now written by different hooks and cannot be confused:
+ *
+ * - `'interrupted'` is written ONLY by `withPersistence`'s `onInterrupt`, and
+ *   carries NO `finishedAt` (a non-terminal status has not finished).
+ * - `'aborted'` is written by `withPersistence`'s `onAbort`, and only for an
+ *   abort that is an explicit cancel or that is ending the run for good.
+ * - A mere client disconnect on a run with durable storage wired writes
+ *   NEITHER: the record stays `'running'` and gains `detachedSince`, because the
+ *   agent is still running and a later attach can take it over.
+ *
+ * Intent is never inferred from the abort itself — see `RUN_CANCEL_REASON` and
+ * `requestRunCancel` in `../cancel`.
+ */
+export type RunStatus = 'running' | 'interrupted' | TerminalRunStatus;
+/**
+ * Whether `value` is a {@link RunStatus} — the guard a backend validates a row
+ * with at DESERIALIZATION.
+ *
+ * `RunStatus` is a compile-time claim about a storage column. A row arrives as
+ * JSON out of D1, a Durable Object, or Postgres, and nothing in the type system
+ * checked what that column actually held, so a `RunStore` implementation should
+ * run its row's `status` through this before handing the record on. The readers
+ * downstream act DESTRUCTIVELY on the answer — `@tanstack/ai-sandbox`'s journal
+ * sweep DELETES the journal of a run it believes terminal — so a row that lies
+ * about its status is not a display bug.
+ */
+export declare function isRunStatus(value: unknown): value is RunStatus;
+/**
+ * Whether `status` means no further events will be appended. Narrows, so a
+ * caller inside the guard can pass `status` where a {@link TerminalRunStatus}
+ * is required without a cast.
+ *
+ * `Object.hasOwn`, never `in`: `in` walks the prototype chain, so a row whose
+ * `status` column held `'toString'` or `'constructor'` would be reported
+ * terminal. `status` is TYPED `RunStatus`, but every value reaching here comes
+ * off a user-implemented {@link RunStore} and the type is only a claim (see
+ * {@link isRunStatus}). A false `true` deletes a live run's journal
+ * (`@tanstack/ai-sandbox`'s journal sweep), fails its attach as `'terminal-run'`
+ * (`attach-preflight`), and refuses to drive it (`stream-to-response.ts`).
+ */
+export declare function isTerminalRunStatus(status: RunStatus): status is TerminalRunStatus;
+/**
+ * Why a run failed.
+ *
+ * A bare message is an LLM provider's prose: it changes between model
+ * versions and cannot be branched on. `code` is what a consumer switches over
+ * to decide whether to retry, escalate, or surface a specific UI.
+ */
+export interface RunError {
+    message: string;
+    /** Stable, machine-branchable classification, when the provider supplies one. */
+    code?: string;
+}
+/** Durable bookkeeping for a single run. */
+export interface RunRecord {
+    runId: string;
+    /**
+     * Conversation this run belongs to — the `Scope.threadId`.
+     *
+     * Generation jobs (a one-shot `generate()` with no conversation) must not
+     * reuse this record by faking `threadId = requestId`; they need a separate
+     * job store. `withGenerationPersistence` currently does exactly that and
+     * labels itself a stopgap — do not copy it.
+     */
+    threadId: string;
+    status: RunStatus;
+    startedAt: number;
+    finishedAt?: number;
+    error?: RunError;
+    usage?: TokenUsage;
+    /**
+     * Compound sandbox key this run was bound to, when it ran in a sandbox.
+     * Recorded so a future reclaimer can identify the sandbox to tear down
+     * without re-deriving the key. Written by `withSandbox`'s detach path
+     * (`onAbort` in `@tanstack/ai-sandbox`'s `middleware.ts`) at the same time as
+     * `detachedSince`, when a disconnect leaves the run detached rather than
+     * destroying the sandbox. A backend must round-trip this field — see
+     * `listReclaimable` below for who eventually reads it.
+     */
+    sandboxKey?: string;
+    /**
+     * Epoch ms when the last viewer detached; absent while someone is attached.
+     * Written by `withSandbox`'s detach path (`onAbort` in `@tanstack/ai-sandbox`'s
+     * `middleware.ts`) alongside `sandboxKey`, when a disconnect leaves the
+     * agent running rather than tearing the sandbox down. A backend must
+     * round-trip this field: `listReclaimable` depends on it, and
+     * `@tanstack/ai-sandbox`'s `reapDetachedRuns` sweeps the candidates it
+     * surfaces (see that method's doc comment).
+     */
+    detachedSince?: number;
+    /**
+     * Set by an explicit out-of-band cancel, to be distinguished from a mere
+     * client disconnect (the two produce an identical TCP close, so intent is not
+     * inferable from the disconnect).
+     *
+     * Written by `requestRunCancel` and read by `wasCancelRequested` (both in
+     * `../cancel`). Deliberately NOT a status: recording intent is not the same as
+     * the run having stopped, and only the driver knows when it has.
+     */
+    cancelRequested?: boolean;
+    /**
+     * Monotonic fencing token for the run's driver. Bumped by each host that
+     * successfully claims the run (see `withRunClaim` in `@tanstack/ai-sandbox`),
+     * so a superseded host can discover it lost by comparing the stored value
+     * against the one it holds.
+     *
+     * A lock alone cannot provide this: it tells the winner it won, but gives a
+     * loser nothing to read. Absent on a run that was never claimed.
+     */
+    driverEpoch?: number;
+}
+/**
+ * Durable store for run lifecycle records.
+ *
+ * REQUIRED: `createOrResume`, `update`, `get`, `findActiveRun`. Every backend
+ * must implement all four — they are what the persistence middleware calls
+ * unconditionally. `findActiveRun` is required rather than feature-detected
+ * because a backend that has not implemented it is indistinguishable from one
+ * whose answer is legitimately `null`, so reconnect would silently do nothing
+ * instead of failing at build time. It was optional for exactly one release
+ * cycle and cost precisely that.
+ *
+ * OPTIONAL: `listByThread`, `listReclaimable`. Each serves one higher-level
+ * feature (thread history, reclaim reaping) and callers feature-detect them,
+ * degrading gracefully when a backend omits them.
+ */
+export interface RunStore {
+    /**
+     * Create a run record, or return the existing one unchanged if `runId` is
+     * already present.
+     *
+     * INVARIANT (idempotency): an existing record is returned **unchanged** and
+     * the passed `threadId`/`startedAt`/`status` are ignored. This is what makes
+     * resuming a run safe. `status` defaults to `'running'` on first creation.
+     */
+    createOrResume: (input: Pick<RunRecord, 'runId' | 'threadId' | 'startedAt'> & {
+        status?: RunStatus;
+    }) => Promise<RunRecord>;
+    /**
+     * Patch a record's mutable fields.
+     *
+     * INVARIANT: updating an unknown `runId` is a **no-op** — it must not throw
+     * and must not create a record.
+     */
+    update: (runId: string, patch: Partial<Pick<RunRecord, 'status' | 'finishedAt' | 'error' | 'usage' | 'sandboxKey' | 'detachedSince' | 'cancelRequested' | 'driverEpoch'>>) => Promise<void>;
+    /** Current record, or null when unknown. */
+    get: (runId: string) => Promise<RunRecord | null>;
+    /**
+     * Every run in a conversation, ascending by `startedAt`. OPTIONAL: only
+     * needed to render a thread's past agent activity. Consumers feature-detect.
+     */
+    listByThread?: (threadId: string) => Promise<Array<RunRecord>>;
+    /**
+     * Runs that may be reclaimed: ALL THREE of `status === 'running'`,
+     * `detachedSince` is set, and `detachedSince <= now - ttlMs`. The cutoff is
+     * **inclusive** — a run detached at exactly `now - ttlMs` IS reclaimable.
+     *
+     * OPTIONAL: only needed by a reaper. Consumers feature-detect.
+     *
+     * `detachedSince` is populated by `withSandbox`'s detach path (see
+     * {@link RunRecord.detachedSince}). The sweep over the candidates this
+     * surfaces is `@tanstack/ai-sandbox`'s `reapDetachedRuns`: it finalizes a run
+     * whose agent already finished, expires one past its TTL, and reclaims the
+     * sandbox. That is a function, not a scheduler — the application invokes it
+     * (cron, queue, `alarm()`, `waitUntil`) — and a backend that omits this
+     * method cannot be reaped at all.
+     */
+    listReclaimable?: (opts: {
+        now: number;
+        ttlMs: number;
+    }) => Promise<Array<RunRecord>>;
+    /**
+     * The most recent `'running'` run for `threadId`, or `null` if none is active.
+     *
+     * REQUIRED. This resolves "does this thread have a live run to attach to?"
+     * from the STABLE thread id, which is the durable basis for reconnecting a
+     * client (a reload, or the same thread opened on another device) — independent
+     * of the ephemeral run id, which a single turn may mint several of. When more
+     * than one run is `'running'`, the one with the greatest `startedAt` wins.
+     *
+     * A backend that stubs this to `null` turns reconnect off silently, because
+     * `null` is also the correct answer for an idle thread. A backend with no run
+     * lifecycle at all should omit the whole `runs` store instead — capability
+     * tiers belong at the store level, not the method level.
+     */
+    findActiveRun: (threadId: string) => Promise<RunRecord | null>;
+}
+/**
+ * Type a {@link RunStore} implementation inline: pass the object and get
+ * autocomplete plus contract checking with no separate annotation. Mirrors
+ * `defineLock` / `defineSandboxInstanceStore`.
+ *
+ * The generic return preserves the argument's own type, so an optional method
+ * the implementation actually provides stays known-present on the result
+ * instead of collapsing back to `| undefined` on the interface.
+ */
+export declare function defineRunStore<const T extends RunStore>(store: T): T;
+/**
+ * Whether the current run can be DETACHED rather than destroyed when its client
+ * disconnects — `true` only when some middleware has both a {@link RunStore} and
+ * a durable event log wired (`withSandbox`'s `runs` + `durability.adapter`).
+ *
+ * Lives in core for the same reason `LockStore` does: it is a coordination fact
+ * that two consumer packages must agree on, and neither may depend on the other.
+ * `@tanstack/ai-sandbox` provides it; `@tanstack/ai-persistence` reads it to
+ * decide whether an abort is terminal (`'aborted'`) or a detach (write nothing).
+ * A persistence → sandbox import would be a layering inversion.
+ *
+ * Consumers read it with `{ optional: true }`: absent means "not detachable",
+ * which is every app that has not wired durability.
+ *
+ * Typed `true`, not `boolean`: ABSENCE is the negative, so a published `false`
+ * has no meaning — and a consumer that tests PRESENCE rather than the value
+ * would read one as "detachable". Narrowing the payload makes that
+ * unrepresentable instead of merely undocumented.
+ */
+export declare const DetachableRunCapability: import('./capabilities.js').Capability<true, "detachable-run">;
+/**
+ * Destructured accessors: `getDetachableRun(ctx, { optional: true })` /
+ * `provideDetachableRun(ctx, true)`.
+ */
+export declare const getDetachableRun: import('./capabilities.js').CapabilityGetter<true>, provideDetachableRun: import('./capabilities.js').CapabilityProvider<true>;
+/**
+ * Whether this run's teardown DID detach — the disconnect was survived, the
+ * agent is still working, and a later attach can take the run over.
+ *
+ * The past-tense counterpart of {@link DetachableRunCapability}, and the two must
+ * not be confused:
+ *
+ * - **detachABLE** is published at `setup`, and only says a disconnect *may* be
+ *   survived (a `RunStore` and a durable log are wired).
+ * - **detachED** is published on the ABORT path, by the middleware that actually
+ *   makes the call — `withSandbox`'s `onAbort`, which is the only actor that has
+ *   resolved BOTH out-of-band cancel bands (`AbortInfo.cancelRequested` and
+ *   `wasCancelRequested` on the record) and `detachOnDisconnect`. An explicit
+ *   cancel, a non-detachable disconnect, an error, and a normal finish all leave
+ *   it unpublished.
+ *
+ * Its consumer is the durable DELIVERY sink in `stream-to-response.ts`: a
+ * detached run's log must stay OPEN and un-terminalized so the takeover can
+ * continue it (see `wasRunDetached` in `../../../delivery-detach`). Reading it
+ * is safe and race-free only because a `for await` over the chat stream awaits
+ * the generator's `return()` — and therefore the whole `onAbort` chain — before
+ * the sink's own `finally` runs.
+ *
+ * Read with `{ optional: true }`: absent means "not detached", which is every
+ * other exit path and every app that has not wired durability.
+ *
+ * Typed `true`, not `boolean`, for the same reason as
+ * {@link DetachableRunCapability}: absence is the only negative, so publishing
+ * `false` must not be representable.
+ */
+export declare const RunDetachedCapability: import('./capabilities.js').Capability<true, "run-detached">;
+/**
+ * Destructured accessors: `getRunDetached(ctx, { optional: true })` /
+ * `provideRunDetached(ctx, true)`.
+ */
+export declare const getRunDetached: import('./capabilities.js').CapabilityGetter<true>, provideRunDetached: import('./capabilities.js').CapabilityProvider<true>;
+/** In-memory {@link RunStore}. Single process only. */
+export declare class InMemoryRunStore implements RunStore {
+    private readonly runs;
+    createOrResume(input: Pick<RunRecord, 'runId' | 'threadId' | 'startedAt'> & {
+        status?: RunStatus;
+    }): Promise<RunRecord>;
+    update(runId: string, patch: Partial<Pick<RunRecord, 'status' | 'finishedAt' | 'error' | 'usage' | 'sandboxKey' | 'detachedSince' | 'cancelRequested' | 'driverEpoch'>>): Promise<void>;
+    get(runId: string): Promise<RunRecord | null>;
+    listByThread(threadId: string): Promise<Array<RunRecord>>;
+    listReclaimable(opts: {
+        now: number;
+        ttlMs: number;
+    }): Promise<Array<RunRecord>>;
+    findActiveRun(threadId: string): Promise<RunRecord | null>;
+}

package/dist/esm/activities/chat/middleware/run-store.js

@@ -0,0 +1,176 @@
+import { createCapability } from "./capabilities.js";
+//#region src/activities/chat/middleware/run-store.ts
+/**
+* Run lifecycle types — the neutral home for what a "run" is.
+*
+* Shared by `@tanstack/ai-persistence` (which exposes a `runs` store through
+* `withPersistence`) and `@tanstack/ai-sandbox` (whose run driver records run
+* status). Living in core is what lets one `RunRecord` per run be shared by
+* both, instead of each package keeping its own and disagreeing. Same rationale
+* as `LockStore` (`packages/ai/src/locks.ts`), which is likewise a
+* coordination primitive that core owns so that no consumer package has to.
+*/
+var TERMINAL = {
+	completed: true,
+	failed: true,
+	aborted: true
+};
+var ALL_STATUSES = {
+	running: true,
+	interrupted: true,
+	completed: true,
+	failed: true,
+	aborted: true
+};
+/**
+* Whether `value` is a {@link RunStatus} — the guard a backend validates a row
+* with at DESERIALIZATION.
+*
+* `RunStatus` is a compile-time claim about a storage column. A row arrives as
+* JSON out of D1, a Durable Object, or Postgres, and nothing in the type system
+* checked what that column actually held, so a `RunStore` implementation should
+* run its row's `status` through this before handing the record on. The readers
+* downstream act DESTRUCTIVELY on the answer — `@tanstack/ai-sandbox`'s journal
+* sweep DELETES the journal of a run it believes terminal — so a row that lies
+* about its status is not a display bug.
+*/
+function isRunStatus(value) {
+	return typeof value === "string" && Object.hasOwn(ALL_STATUSES, value);
+}
+/**
+* Whether `status` means no further events will be appended. Narrows, so a
+* caller inside the guard can pass `status` where a {@link TerminalRunStatus}
+* is required without a cast.
+*
+* `Object.hasOwn`, never `in`: `in` walks the prototype chain, so a row whose
+* `status` column held `'toString'` or `'constructor'` would be reported
+* terminal. `status` is TYPED `RunStatus`, but every value reaching here comes
+* off a user-implemented {@link RunStore} and the type is only a claim (see
+* {@link isRunStatus}). A false `true` deletes a live run's journal
+* (`@tanstack/ai-sandbox`'s journal sweep), fails its attach as `'terminal-run'`
+* (`attach-preflight`), and refuses to drive it (`stream-to-response.ts`).
+*/
+function isTerminalRunStatus(status) {
+	return Object.hasOwn(TERMINAL, status);
+}
+/**
+* Type a {@link RunStore} implementation inline: pass the object and get
+* autocomplete plus contract checking with no separate annotation. Mirrors
+* `defineLock` / `defineSandboxInstanceStore`.
+*
+* The generic return preserves the argument's own type, so an optional method
+* the implementation actually provides stays known-present on the result
+* instead of collapsing back to `| undefined` on the interface.
+*/
+function defineRunStore(store) {
+	return store;
+}
+/**
+* Whether the current run can be DETACHED rather than destroyed when its client
+* disconnects — `true` only when some middleware has both a {@link RunStore} and
+* a durable event log wired (`withSandbox`'s `runs` + `durability.adapter`).
+*
+* Lives in core for the same reason `LockStore` does: it is a coordination fact
+* that two consumer packages must agree on, and neither may depend on the other.
+* `@tanstack/ai-sandbox` provides it; `@tanstack/ai-persistence` reads it to
+* decide whether an abort is terminal (`'aborted'`) or a detach (write nothing).
+* A persistence → sandbox import would be a layering inversion.
+*
+* Consumers read it with `{ optional: true }`: absent means "not detachable",
+* which is every app that has not wired durability.
+*
+* Typed `true`, not `boolean`: ABSENCE is the negative, so a published `false`
+* has no meaning — and a consumer that tests PRESENCE rather than the value
+* would read one as "detachable". Narrowing the payload makes that
+* unrepresentable instead of merely undocumented.
+*/
+var DetachableRunCapability = createCapability()("detachable-run");
+/**
+* Destructured accessors: `getDetachableRun(ctx, { optional: true })` /
+* `provideDetachableRun(ctx, true)`.
+*/
+var [getDetachableRun, provideDetachableRun] = DetachableRunCapability;
+/**
+* Whether this run's teardown DID detach — the disconnect was survived, the
+* agent is still working, and a later attach can take the run over.
+*
+* The past-tense counterpart of {@link DetachableRunCapability}, and the two must
+* not be confused:
+*
+* - **detachABLE** is published at `setup`, and only says a disconnect *may* be
+*   survived (a `RunStore` and a durable log are wired).
+* - **detachED** is published on the ABORT path, by the middleware that actually
+*   makes the call — `withSandbox`'s `onAbort`, which is the only actor that has
+*   resolved BOTH out-of-band cancel bands (`AbortInfo.cancelRequested` and
+*   `wasCancelRequested` on the record) and `detachOnDisconnect`. An explicit
+*   cancel, a non-detachable disconnect, an error, and a normal finish all leave
+*   it unpublished.
+*
+* Its consumer is the durable DELIVERY sink in `stream-to-response.ts`: a
+* detached run's log must stay OPEN and un-terminalized so the takeover can
+* continue it (see `wasRunDetached` in `../../../delivery-detach`). Reading it
+* is safe and race-free only because a `for await` over the chat stream awaits
+* the generator's `return()` — and therefore the whole `onAbort` chain — before
+* the sink's own `finally` runs.
+*
+* Read with `{ optional: true }`: absent means "not detached", which is every
+* other exit path and every app that has not wired durability.
+*
+* Typed `true`, not `boolean`, for the same reason as
+* {@link DetachableRunCapability}: absence is the only negative, so publishing
+* `false` must not be representable.
+*/
+var RunDetachedCapability = createCapability()("run-detached");
+/**
+* Destructured accessors: `getRunDetached(ctx, { optional: true })` /
+* `provideRunDetached(ctx, true)`.
+*/
+var [getRunDetached, provideRunDetached] = RunDetachedCapability;
+/** In-memory {@link RunStore}. Single process only. */
+var InMemoryRunStore = class {
+	runs = /* @__PURE__ */ new Map();
+	createOrResume(input) {
+		const existing = this.runs.get(input.runId);
+		if (existing) return Promise.resolve(existing);
+		const record = {
+			runId: input.runId,
+			threadId: input.threadId,
+			status: input.status ?? "running",
+			startedAt: input.startedAt
+		};
+		this.runs.set(record.runId, record);
+		return Promise.resolve(record);
+	}
+	update(runId, patch) {
+		const existing = this.runs.get(runId);
+		if (existing) this.runs.set(runId, {
+			...existing,
+			...patch
+		});
+		return Promise.resolve();
+	}
+	get(runId) {
+		return Promise.resolve(this.runs.get(runId) ?? null);
+	}
+	listByThread(threadId) {
+		const matching = [...this.runs.values()].filter((run) => run.threadId === threadId).sort((a, b) => a.startedAt - b.startedAt);
+		return Promise.resolve(matching);
+	}
+	listReclaimable(opts) {
+		const cutoff = opts.now - opts.ttlMs;
+		const matching = [...this.runs.values()].filter((run) => run.status === "running" && run.detachedSince !== void 0 && run.detachedSince <= cutoff);
+		return Promise.resolve(matching);
+	}
+	findActiveRun(threadId) {
+		let active = null;
+		for (const run of this.runs.values()) {
+			if (run.threadId !== threadId || run.status !== "running") continue;
+			if (active === null || run.startedAt > active.startedAt) active = run;
+		}
+		return Promise.resolve(active);
+	}
+};
+//#endregion
+export { DetachableRunCapability, InMemoryRunStore, RunDetachedCapability, defineRunStore, getDetachableRun, getRunDetached, isRunStatus, isTerminalRunStatus, provideDetachableRun, provideRunDetached };
+
+//# sourceMappingURL=run-store.js.map

package/dist/esm/activities/chat/middleware/run-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-store.js","names":[],"sources":["../../../../../src/activities/chat/middleware/run-store.ts"],"sourcesContent":["/**\n * Run lifecycle types — the neutral home for what a \"run\" is.\n *\n * Shared by `@tanstack/ai-persistence` (which exposes a `runs` store through\n * `withPersistence`) and `@tanstack/ai-sandbox` (whose run driver records run\n * status). Living in core is what lets one `RunRecord` per run be shared by\n * both, instead of each package keeping its own and disagreeing. Same rationale\n * as `LockStore` (`packages/ai/src/locks.ts`), which is likewise a\n * coordination primitive that core owns so that no consumer package has to.\n */\nimport { createCapability } from './capabilities'\nimport type { TokenUsage } from '../../../types'\n\n/** A terminal run status: no further events will be appended. */\nexport type TerminalRunStatus = 'completed' | 'failed' | 'aborted'\n\n/**\n * Lifecycle status of one run (one agent turn within a conversation).\n *\n * `interrupted` is a human-in-the-loop PAUSE that interrupt-resume continues\n * from — it is deliberately NOT terminal, and must never be conflated with\n * `aborted` (an explicit cancellation).\n *\n * The two are now written by different hooks and cannot be confused:\n *\n * - `'interrupted'` is written ONLY by `withPersistence`'s `onInterrupt`, and\n *   carries NO `finishedAt` (a non-terminal status has not finished).\n * - `'aborted'` is written by `withPersistence`'s `onAbort`, and only for an\n *   abort that is an explicit cancel or that is ending the run for good.\n * - A mere client disconnect on a run with durable storage wired writes\n *   NEITHER: the record stays `'running'` and gains `detachedSince`, because the\n *   agent is still running and a later attach can take it over.\n *\n * Intent is never inferred from the abort itself — see `RUN_CANCEL_REASON` and\n * `requestRunCancel` in `../cancel`.\n */\nexport type RunStatus = 'running' | 'interrupted' | TerminalRunStatus\n\n// A Record keyed by the union is exhaustiveness-checked: adding a member to\n// TerminalRunStatus is a compile error here until this map is updated. A\n// `Set<RunStatus>` would silently answer `false` for the new member instead.\nconst TERMINAL: Record<TerminalRunStatus, true> = {\n  completed: true,\n  failed: true,\n  aborted: true,\n}\n\n// Same exhaustiveness trick over the FULL union, for {@link isRunStatus}.\nconst ALL_STATUSES: Record<RunStatus, true> = {\n  running: true,\n  interrupted: true,\n  completed: true,\n  failed: true,\n  aborted: true,\n}\n\n/**\n * Whether `value` is a {@link RunStatus} — the guard a backend validates a row\n * with at DESERIALIZATION.\n *\n * `RunStatus` is a compile-time claim about a storage column. A row arrives as\n * JSON out of D1, a Durable Object, or Postgres, and nothing in the type system\n * checked what that column actually held, so a `RunStore` implementation should\n * run its row's `status` through this before handing the record on. The readers\n * downstream act DESTRUCTIVELY on the answer — `@tanstack/ai-sandbox`'s journal\n * sweep DELETES the journal of a run it believes terminal — so a row that lies\n * about its status is not a display bug.\n */\nexport function isRunStatus(value: unknown): value is RunStatus {\n  return typeof value === 'string' && Object.hasOwn(ALL_STATUSES, value)\n}\n\n/**\n * Whether `status` means no further events will be appended. Narrows, so a\n * caller inside the guard can pass `status` where a {@link TerminalRunStatus}\n * is required without a cast.\n *\n * `Object.hasOwn`, never `in`: `in` walks the prototype chain, so a row whose\n * `status` column held `'toString'` or `'constructor'` would be reported\n * terminal. `status` is TYPED `RunStatus`, but every value reaching here comes\n * off a user-implemented {@link RunStore} and the type is only a claim (see\n * {@link isRunStatus}). A false `true` deletes a live run's journal\n * (`@tanstack/ai-sandbox`'s journal sweep), fails its attach as `'terminal-run'`\n * (`attach-preflight`), and refuses to drive it (`stream-to-response.ts`).\n */\nexport function isTerminalRunStatus(\n  status: RunStatus,\n): status is TerminalRunStatus {\n  return Object.hasOwn(TERMINAL, status)\n}\n\n/**\n * Why a run failed.\n *\n * A bare message is an LLM provider's prose: it changes between model\n * versions and cannot be branched on. `code` is what a consumer switches over\n * to decide whether to retry, escalate, or surface a specific UI.\n */\nexport interface RunError {\n  message: string\n  /** Stable, machine-branchable classification, when the provider supplies one. */\n  code?: string\n}\n\n/** Durable bookkeeping for a single run. */\nexport interface RunRecord {\n  runId: string\n  /**\n   * Conversation this run belongs to — the `Scope.threadId`.\n   *\n   * Generation jobs (a one-shot `generate()` with no conversation) must not\n   * reuse this record by faking `threadId = requestId`; they need a separate\n   * job store. `withGenerationPersistence` currently does exactly that and\n   * labels itself a stopgap — do not copy it.\n   */\n  threadId: string\n  status: RunStatus\n  startedAt: number\n  finishedAt?: number\n  error?: RunError\n  usage?: TokenUsage\n  /**\n   * Compound sandbox key this run was bound to, when it ran in a sandbox.\n   * Recorded so a future reclaimer can identify the sandbox to tear down\n   * without re-deriving the key. Written by `withSandbox`'s detach path\n   * (`onAbort` in `@tanstack/ai-sandbox`'s `middleware.ts`) at the same time as\n   * `detachedSince`, when a disconnect leaves the run detached rather than\n   * destroying the sandbox. A backend must round-trip this field — see\n   * `listReclaimable` below for who eventually reads it.\n   */\n  sandboxKey?: string\n  /**\n   * Epoch ms when the last viewer detached; absent while someone is attached.\n   * Written by `withSandbox`'s detach path (`onAbort` in `@tanstack/ai-sandbox`'s\n   * `middleware.ts`) alongside `sandboxKey`, when a disconnect leaves the\n   * agent running rather than tearing the sandbox down. A backend must\n   * round-trip this field: `listReclaimable` depends on it, and\n   * `@tanstack/ai-sandbox`'s `reapDetachedRuns` sweeps the candidates it\n   * surfaces (see that method's doc comment).\n   */\n  detachedSince?: number\n  /**\n   * Set by an explicit out-of-band cancel, to be distinguished from a mere\n   * client disconnect (the two produce an identical TCP close, so intent is not\n   * inferable from the disconnect).\n   *\n   * Written by `requestRunCancel` and read by `wasCancelRequested` (both in\n   * `../cancel`). Deliberately NOT a status: recording intent is not the same as\n   * the run having stopped, and only the driver knows when it has.\n   */\n  cancelRequested?: boolean\n  /**\n   * Monotonic fencing token for the run's driver. Bumped by each host that\n   * successfully claims the run (see `withRunClaim` in `@tanstack/ai-sandbox`),\n   * so a superseded host can discover it lost by comparing the stored value\n   * against the one it holds.\n   *\n   * A lock alone cannot provide this: it tells the winner it won, but gives a\n   * loser nothing to read. Absent on a run that was never claimed.\n   */\n  driverEpoch?: number\n}\n\n/**\n * Durable store for run lifecycle records.\n *\n * REQUIRED: `createOrResume`, `update`, `get`, `findActiveRun`. Every backend\n * must implement all four — they are what the persistence middleware calls\n * unconditionally. `findActiveRun` is required rather than feature-detected\n * because a backend that has not implemented it is indistinguishable from one\n * whose answer is legitimately `null`, so reconnect would silently do nothing\n * instead of failing at build time. It was optional for exactly one release\n * cycle and cost precisely that.\n *\n * OPTIONAL: `listByThread`, `listReclaimable`. Each serves one higher-level\n * feature (thread history, reclaim reaping) and callers feature-detect them,\n * degrading gracefully when a backend omits them.\n */\nexport interface RunStore {\n  /**\n   * Create a run record, or return the existing one unchanged if `runId` is\n   * already present.\n   *\n   * INVARIANT (idempotency): an existing record is returned **unchanged** and\n   * the passed `threadId`/`startedAt`/`status` are ignored. This is what makes\n   * resuming a run safe. `status` defaults to `'running'` on first creation.\n   */\n  createOrResume: (\n    input: Pick<RunRecord, 'runId' | 'threadId' | 'startedAt'> & {\n      status?: RunStatus\n    },\n  ) => Promise<RunRecord>\n  /**\n   * Patch a record's mutable fields.\n   *\n   * INVARIANT: updating an unknown `runId` is a **no-op** — it must not throw\n   * and must not create a record.\n   */\n  update: (\n    runId: string,\n    patch: Partial<\n      Pick<\n        RunRecord,\n        | 'status'\n        | 'finishedAt'\n        | 'error'\n        | 'usage'\n        | 'sandboxKey'\n        | 'detachedSince'\n        | 'cancelRequested'\n        | 'driverEpoch'\n      >\n    >,\n  ) => Promise<void>\n  /** Current record, or null when unknown. */\n  get: (runId: string) => Promise<RunRecord | null>\n  /**\n   * Every run in a conversation, ascending by `startedAt`. OPTIONAL: only\n   * needed to render a thread's past agent activity. Consumers feature-detect.\n   */\n  listByThread?: (threadId: string) => Promise<Array<RunRecord>>\n  /**\n   * Runs that may be reclaimed: ALL THREE of `status === 'running'`,\n   * `detachedSince` is set, and `detachedSince <= now - ttlMs`. The cutoff is\n   * **inclusive** — a run detached at exactly `now - ttlMs` IS reclaimable.\n   *\n   * OPTIONAL: only needed by a reaper. Consumers feature-detect.\n   *\n   * `detachedSince` is populated by `withSandbox`'s detach path (see\n   * {@link RunRecord.detachedSince}). The sweep over the candidates this\n   * surfaces is `@tanstack/ai-sandbox`'s `reapDetachedRuns`: it finalizes a run\n   * whose agent already finished, expires one past its TTL, and reclaims the\n   * sandbox. That is a function, not a scheduler — the application invokes it\n   * (cron, queue, `alarm()`, `waitUntil`) — and a backend that omits this\n   * method cannot be reaped at all.\n   */\n  listReclaimable?: (opts: {\n    now: number\n    ttlMs: number\n  }) => Promise<Array<RunRecord>>\n  /**\n   * The most recent `'running'` run for `threadId`, or `null` if none is active.\n   *\n   * REQUIRED. This resolves \"does this thread have a live run to attach to?\"\n   * from the STABLE thread id, which is the durable basis for reconnecting a\n   * client (a reload, or the same thread opened on another device) — independent\n   * of the ephemeral run id, which a single turn may mint several of. When more\n   * than one run is `'running'`, the one with the greatest `startedAt` wins.\n   *\n   * A backend that stubs this to `null` turns reconnect off silently, because\n   * `null` is also the correct answer for an idle thread. A backend with no run\n   * lifecycle at all should omit the whole `runs` store instead — capability\n   * tiers belong at the store level, not the method level.\n   */\n  findActiveRun: (threadId: string) => Promise<RunRecord | null>\n}\n\n/**\n * Type a {@link RunStore} implementation inline: pass the object and get\n * autocomplete plus contract checking with no separate annotation. Mirrors\n * `defineLock` / `defineSandboxInstanceStore`.\n *\n * The generic return preserves the argument's own type, so an optional method\n * the implementation actually provides stays known-present on the result\n * instead of collapsing back to `| undefined` on the interface.\n */\nexport function defineRunStore<const T extends RunStore>(store: T): T {\n  return store\n}\n\n/**\n * Whether the current run can be DETACHED rather than destroyed when its client\n * disconnects — `true` only when some middleware has both a {@link RunStore} and\n * a durable event log wired (`withSandbox`'s `runs` + `durability.adapter`).\n *\n * Lives in core for the same reason `LockStore` does: it is a coordination fact\n * that two consumer packages must agree on, and neither may depend on the other.\n * `@tanstack/ai-sandbox` provides it; `@tanstack/ai-persistence` reads it to\n * decide whether an abort is terminal (`'aborted'`) or a detach (write nothing).\n * A persistence → sandbox import would be a layering inversion.\n *\n * Consumers read it with `{ optional: true }`: absent means \"not detachable\",\n * which is every app that has not wired durability.\n *\n * Typed `true`, not `boolean`: ABSENCE is the negative, so a published `false`\n * has no meaning — and a consumer that tests PRESENCE rather than the value\n * would read one as \"detachable\". Narrowing the payload makes that\n * unrepresentable instead of merely undocumented.\n */\nexport const DetachableRunCapability =\n  createCapability<true>()('detachable-run')\n\n/**\n * Destructured accessors: `getDetachableRun(ctx, { optional: true })` /\n * `provideDetachableRun(ctx, true)`.\n */\nexport const [getDetachableRun, provideDetachableRun] = DetachableRunCapability\n\n/**\n * Whether this run's teardown DID detach — the disconnect was survived, the\n * agent is still working, and a later attach can take the run over.\n *\n * The past-tense counterpart of {@link DetachableRunCapability}, and the two must\n * not be confused:\n *\n * - **detachABLE** is published at `setup`, and only says a disconnect *may* be\n *   survived (a `RunStore` and a durable log are wired).\n * - **detachED** is published on the ABORT path, by the middleware that actually\n *   makes the call — `withSandbox`'s `onAbort`, which is the only actor that has\n *   resolved BOTH out-of-band cancel bands (`AbortInfo.cancelRequested` and\n *   `wasCancelRequested` on the record) and `detachOnDisconnect`. An explicit\n *   cancel, a non-detachable disconnect, an error, and a normal finish all leave\n *   it unpublished.\n *\n * Its consumer is the durable DELIVERY sink in `stream-to-response.ts`: a\n * detached run's log must stay OPEN and un-terminalized so the takeover can\n * continue it (see `wasRunDetached` in `../../../delivery-detach`). Reading it\n * is safe and race-free only because a `for await` over the chat stream awaits\n * the generator's `return()` — and therefore the whole `onAbort` chain — before\n * the sink's own `finally` runs.\n *\n * Read with `{ optional: true }`: absent means \"not detached\", which is every\n * other exit path and every app that has not wired durability.\n *\n * Typed `true`, not `boolean`, for the same reason as\n * {@link DetachableRunCapability}: absence is the only negative, so publishing\n * `false` must not be representable.\n */\nexport const RunDetachedCapability = createCapability<true>()('run-detached')\n\n/**\n * Destructured accessors: `getRunDetached(ctx, { optional: true })` /\n * `provideRunDetached(ctx, true)`.\n */\nexport const [getRunDetached, provideRunDetached] = RunDetachedCapability\n\n/** In-memory {@link RunStore}. Single process only. */\nexport class InMemoryRunStore implements RunStore {\n  private readonly runs = new Map<string, RunRecord>()\n\n  createOrResume(\n    input: Pick<RunRecord, 'runId' | 'threadId' | 'startedAt'> & {\n      status?: RunStatus\n    },\n  ): Promise<RunRecord> {\n    const existing = this.runs.get(input.runId)\n    if (existing) return Promise.resolve(existing)\n    const record: RunRecord = {\n      runId: input.runId,\n      threadId: input.threadId,\n      status: input.status ?? 'running',\n      startedAt: input.startedAt,\n    }\n    this.runs.set(record.runId, record)\n    return Promise.resolve(record)\n  }\n\n  update(\n    runId: string,\n    patch: Partial<\n      Pick<\n        RunRecord,\n        | 'status'\n        | 'finishedAt'\n        | 'error'\n        | 'usage'\n        | 'sandboxKey'\n        | 'detachedSince'\n        | 'cancelRequested'\n        | 'driverEpoch'\n      >\n    >,\n  ): Promise<void> {\n    const existing = this.runs.get(runId)\n    if (existing) this.runs.set(runId, { ...existing, ...patch })\n    return Promise.resolve()\n  }\n\n  get(runId: string): Promise<RunRecord | null> {\n    return Promise.resolve(this.runs.get(runId) ?? null)\n  }\n\n  listByThread(threadId: string): Promise<Array<RunRecord>> {\n    const matching = [...this.runs.values()]\n      .filter((run) => run.threadId === threadId)\n      .sort((a, b) => a.startedAt - b.startedAt)\n    return Promise.resolve(matching)\n  }\n\n  listReclaimable(opts: {\n    now: number\n    ttlMs: number\n  }): Promise<Array<RunRecord>> {\n    const cutoff = opts.now - opts.ttlMs\n    const matching = [...this.runs.values()].filter(\n      (run) =>\n        run.status === 'running' &&\n        run.detachedSince !== undefined &&\n        run.detachedSince <= cutoff,\n    )\n    return Promise.resolve(matching)\n  }\n\n  findActiveRun(threadId: string): Promise<RunRecord | null> {\n    let active: RunRecord | null = null\n    for (const run of this.runs.values()) {\n      if (run.threadId !== threadId || run.status !== 'running') continue\n      if (active === null || run.startedAt > active.startedAt) active = run\n    }\n    return Promise.resolve(active)\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAyCA,IAAM,WAA4C;CAChD,WAAW;CACX,QAAQ;CACR,SAAS;AACX;AAGA,IAAM,eAAwC;CAC5C,SAAS;CACT,aAAa;CACb,WAAW;CACX,QAAQ;CACR,SAAS;AACX;;;;;;;;;;;;;AAcA,SAAgB,YAAY,OAAoC;CAC9D,OAAO,OAAO,UAAU,YAAY,OAAO,OAAO,cAAc,KAAK;AACvE;;;;;;;;;;;;;;AAeA,SAAgB,oBACd,QAC6B;CAC7B,OAAO,OAAO,OAAO,UAAU,MAAM;AACvC;;;;;;;;;;AAiLA,SAAgB,eAAyC,OAAa;CACpE,OAAO;AACT;;;;;;;;;;;;;;;;;;;;AAqBA,IAAa,0BACX,iBAAuB,CAAC,CAAC,gBAAgB;;;;;AAM3C,IAAa,CAAC,kBAAkB,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCxD,IAAa,wBAAwB,iBAAuB,CAAC,CAAC,cAAc;;;;;AAM5E,IAAa,CAAC,gBAAgB,sBAAsB;;AAGpD,IAAa,mBAAb,MAAkD;CAChD,uBAAwB,IAAI,IAAuB;CAEnD,eACE,OAGoB;EACpB,MAAM,WAAW,KAAK,KAAK,IAAI,MAAM,KAAK;EAC1C,IAAI,UAAU,OAAO,QAAQ,QAAQ,QAAQ;EAC7C,MAAM,SAAoB;GACxB,OAAO,MAAM;GACb,UAAU,MAAM;GAChB,QAAQ,MAAM,UAAU;GACxB,WAAW,MAAM;EACnB;EACA,KAAK,KAAK,IAAI,OAAO,OAAO,MAAM;EAClC,OAAO,QAAQ,QAAQ,MAAM;CAC/B;CAEA,OACE,OACA,OAae;EACf,MAAM,WAAW,KAAK,KAAK,IAAI,KAAK;EACpC,IAAI,UAAU,KAAK,KAAK,IAAI,OAAO;GAAE,GAAG;GAAU,GAAG;EAAM,CAAC;EAC5D,OAAO,QAAQ,QAAQ;CACzB;CAEA,IAAI,OAA0C;EAC5C,OAAO,QAAQ,QAAQ,KAAK,KAAK,IAAI,KAAK,KAAK,IAAI;CACrD;CAEA,aAAa,UAA6C;EACxD,MAAM,WAAW,CAAC,GAAG,KAAK,KAAK,OAAO,CAAC,CAAC,CACrC,QAAQ,QAAQ,IAAI,aAAa,QAAQ,CAAC,CAC1C,MAAM,GAAG,MAAM,EAAE,YAAY,EAAE,SAAS;EAC3C,OAAO,QAAQ,QAAQ,QAAQ;CACjC;CAEA,gBAAgB,MAGc;EAC5B,MAAM,SAAS,KAAK,MAAM,KAAK;EAC/B,MAAM,WAAW,CAAC,GAAG,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,QACtC,QACC,IAAI,WAAW,aACf,IAAI,kBAAkB,KAAA,KACtB,IAAI,iBAAiB,MACzB;EACA,OAAO,QAAQ,QAAQ,QAAQ;CACjC;CAEA,cAAc,UAA6C;EACzD,IAAI,SAA2B;EAC/B,KAAK,MAAM,OAAO,KAAK,KAAK,OAAO,GAAG;GACpC,IAAI,IAAI,aAAa,YAAY,IAAI,WAAW,WAAW;GAC3D,IAAI,WAAW,QAAQ,IAAI,YAAY,OAAO,WAAW,SAAS;EACpE;EACA,OAAO,QAAQ,QAAQ,MAAM;CAC/B;AACF"}

package/dist/esm/activities/chat/middleware/sandbox-runtime.js

@@ -1,9 +1,15 @@
 import { createCapability } from "./capabilities.js";
-const SandboxRuntimeCapability = createCapability()("sandbox-runtime");
-const [getSandboxRuntime, provideSandboxRuntime] = SandboxRuntimeCapability;
-export {
-  SandboxRuntimeCapability,
-  getSandboxRuntime,
-  provideSandboxRuntime
-};
-//# sourceMappingURL=sandbox-runtime.js.map
+//#region src/activities/chat/middleware/sandbox-runtime.ts
+/**
+* Internal runtime seam the chat engine PROVIDES so the sandbox middleware can
+* surface file events without a public ctx method. `emit` runs every
+* middleware's `sandbox` hooks AND emits a CUSTOM `sandbox.file` chunk into the
+* stream; `logger` lets the sandbox layer log under the `sandbox` debug
+* category. Consumed (optionally) by `withSandbox` in `@tanstack/ai-sandbox`.
+*/
+var SandboxRuntimeCapability = createCapability()("sandbox-runtime");
+var [getSandboxRuntime, provideSandboxRuntime] = SandboxRuntimeCapability;
+//#endregion
+export { SandboxRuntimeCapability, getSandboxRuntime, provideSandboxRuntime };
+
+//# sourceMappingURL=sandbox-runtime.js.map

package/dist/esm/activities/chat/middleware/sandbox-runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox-runtime.js","sources":["../../../../../src/activities/chat/middleware/sandbox-runtime.ts"],"sourcesContent":["/**\n * Internal runtime seam the chat engine PROVIDES so the sandbox middleware can\n * surface file events without a public ctx method. `emit` runs every\n * middleware's `sandbox` hooks AND emits a CUSTOM `sandbox.file` chunk into the\n * stream; `logger` lets the sandbox layer log under the `sandbox` debug\n * category. Consumed (optionally) by `withSandbox` in `@tanstack/ai-sandbox`.\n */\nimport { createCapability } from './capabilities'\nimport type { InternalLogger } from '../../../logger/internal-logger'\nimport type { SandboxFileHookEvent } from './types'\n\nexport interface SandboxRuntime {\n  emit: (event: SandboxFileHookEvent) => void\n  /** Emit an opt-in per-file `sandbox.file.diff` CUSTOM chunk. */\n  emitFileDiff: (value: { path: string; diff: string }) => void\n  logger: InternalLogger\n}\n\nexport const SandboxRuntimeCapability =\n  createCapability<SandboxRuntime>()('sandbox-runtime')\n\nexport const [getSandboxRuntime, provideSandboxRuntime] =\n  SandboxRuntimeCapability\n"],"names":[],"mappings":";AAkBO,MAAM,2BACX,iBAAA,EAAmC,iBAAiB;AAE/C,MAAM,CAAC,mBAAmB,qBAAqB,IACpD;"}
+{"version":3,"file":"sandbox-runtime.js","names":[],"sources":["../../../../../src/activities/chat/middleware/sandbox-runtime.ts"],"sourcesContent":["/**\n * Internal runtime seam the chat engine PROVIDES so the sandbox middleware can\n * surface file events without a public ctx method. `emit` runs every\n * middleware's `sandbox` hooks AND emits a CUSTOM `sandbox.file` chunk into the\n * stream; `logger` lets the sandbox layer log under the `sandbox` debug\n * category. Consumed (optionally) by `withSandbox` in `@tanstack/ai-sandbox`.\n */\nimport { createCapability } from './capabilities'\nimport type { InternalLogger } from '../../../logger/internal-logger'\nimport type { SandboxFileHookEvent } from './types'\n\nexport interface SandboxRuntime {\n  emit: (event: SandboxFileHookEvent) => void\n  /** Emit an opt-in per-file `sandbox.file.diff` CUSTOM chunk. */\n  emitFileDiff: (value: { path: string; diff: string }) => void\n  logger: InternalLogger\n}\n\nexport const SandboxRuntimeCapability =\n  createCapability<SandboxRuntime>()('sandbox-runtime')\n\nexport const [getSandboxRuntime, provideSandboxRuntime] =\n  SandboxRuntimeCapability\n"],"mappings":";;;;;;;;;AAkBA,IAAa,2BACX,iBAAiC,CAAC,CAAC,iBAAiB;AAEtD,IAAa,CAAC,mBAAmB,yBAC/B"}