RunRecord

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

Durable bookkeeping for a single run.

Properties#

activity?#

optional activity?: string;

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

The activity of a kind: 'activity' run ('image', 'chat', ...).

agent?#

optional agent?: string;

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

The agent name of a kind: 'agent' run.

artifacts?#

optional artifacts?: RunArtifactRef[];

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

Durable artifact references produced by this run.

cancelRequested?#

optional cancelRequested?: boolean;

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

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.

checkpoint?#

optional checkpoint?: RunCheckpoint;

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

Crash-resume data saved at the last model or tool boundary.

detachedSince?#

optional detachedSince?: number;

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

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:178

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:137

finishedAt?#

optional finishedAt?: number;

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

kind?#

optional kind?: RunKind;

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

What kind of work this run is, when a host session recorded it: a chat turn, an agent run, one activity call inside an agent, a user command, or a compaction. Absent on runs recorded by plain chat().

leaseExpiresAt?#

optional leaseExpiresAt?: number;

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

leaseOwner?#

optional leaseOwner?: string;

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

The host that currently drives this run, and when its claim expires. The driver renews leaseExpiresAt. Another host may resume the run after it passes. Pairs with driverEpoch for fencing.

name?#

optional name?: string;

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

Agent name (researcher, writer) when this record is a subagent.

parentRunId?#

optional parentRunId?: string;

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

Parent chat run that started this child, when this record is a subagent. Absent on the parent run itself.

principal?#

optional principal?: object;

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

Who started this run, from the host's authorize.

id#

id: string;

result?#

optional result?: unknown;

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

Terminal result metadata (ids, urls, text). Never media bytes.

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:148

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:135

status#

status: RunStatus;

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

subagentRunId?#

optional subagentRunId?: string;

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

The child's AG-UI subagentRunId, the id on its SUBAGENT_* chunks and on every chunk it streams. On a child record this equals runId. Absent on the parent run.

threadId#

threadId: string;

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

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.

A subagent child record stores subagent:<subagentRunId> here, the key of its own transcript, so findActiveRun and listByThread on the conversation never return children. Use listByParentRun.

usage?#

optional usage?: TokenUsage<ProviderUsageDetails>;

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