Interface: RunRecord#

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:106

Durable bookkeeping for a single run.

Properties#

cancelRequested?#

optional cancelRequested?: boolean;

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:151

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.

detachedSince?#

optional detachedSince?: number;

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:141

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).

driverEpoch?#

optional driverEpoch?: number;

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:161

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.

error?#

optional error?: RunError;

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:120

finishedAt?#

optional finishedAt?: number;

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:119

runId#

runId: string;

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:107

sandboxKey?#

optional sandboxKey?: string;

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:131

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.

startedAt#

startedAt: number;

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:118

status#

status: RunStatus;

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:117

threadId#

threadId: string;

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:116

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.

usage?#

optional usage?: TokenUsage<ProviderUsageDetails>;

Defined in: packages/ai/src/activities/chat/middleware/run-store.ts:121