Graphorin API reference v0.15.1
Graphorin API reference / @graphorin/core / / RunState
Interface: RunState
Defined in: packages/core/src/types/run.ts:93
Stable
The full, serializable state of a run. The agent runtime persists this to the checkpoint store on every awaiting_approval boundary, so a separate process can resume the run.
JSON stability is guaranteed by the serializer, not by naive JSON.stringify: messages and tool-outcome contentParts may carry Uint8Array | URL payloads, which the documented wire projection (WireRunState via toJsonSafeRunState) encodes as base64 / href envelopes before stringification. No Map, Set or Date appears anywhere in the shape.
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
agentId | readonly | string | - | packages/core/src/types/run.ts:95 |
currentAgentId | readonly | string | The agent whose model drives the NEXT step. During a handoff it is the target for exactly the child observation window and is restored to the parent when the child returns - the child's identity is durably recorded in RunState.handoffs, never here. | packages/core/src/types/run.ts:102 |
error? | public | RunError | - | packages/core/src/types/run.ts:160 |
finishedAt? | public | string | - | packages/core/src/types/run.ts:159 |
handoffs | readonly | HandoffRecord[] | - | packages/core/src/types/run.ts:109 |
id | readonly | string | - | packages/core/src/types/run.ts:94 |
messages | readonly | Message[] | - | packages/core/src/types/run.ts:107 |
pendingApprovals | readonly | ToolApproval[] | - | packages/core/src/types/run.ts:108 |
pendingSubRuns? | public | PendingSubRun[] | Sub-agent runs parked on this (parent) run because the child suspended with awaiting_approval. Each entry snapshots the suspended child state; the child's pending approvals are mirrored onto this run's pendingApprovals with subRunToolCallId set to the entry's toolCallId. Absent until a child parks. | packages/core/src/types/run.ts:157 |
promotedTools? | public | readonly string[] | Names of deferred tools promoted by tool_search this run, carried across suspend/resume so discovered tools remain in the per-step catalogue. | packages/core/src/types/run.ts:131 |
sessionId | readonly | string | - | packages/core/src/types/run.ts:103 |
startedAt | readonly | string | - | packages/core/src/types/run.ts:158 |
status | public | RunStatus | - | packages/core/src/types/run.ts:105 |
steps | readonly | RunStep[] | - | packages/core/src/types/run.ts:106 |
taintSummary? | public | RunTaintSummary | Coarse data-flow taint summary, carried across suspend/resume so a resumed run does not start with an empty ledger that silently un-gates sinks exposed before the suspend. Structurally matches @graphorin/security's TaintLedgerSnapshot (core takes no security dependency); only the load-bearing flags are persisted - never the tracked untrusted text spans. | packages/core/src/types/run.ts:126 |
todos? | public | readonly TodoItem[] | Structured plan/todo list - the agent's own working plan, journaled so it survives suspend/resume (a TodoWrite-style tool mutates it, and attention-recitation renders it back into the prompt each turn). Absent until the agent writes one. | packages/core/src/types/run.ts:149 |
usage | readonly | Usage | - | packages/core/src/types/run.ts:110 |
usageByModel? | public | RunStateUsageByModel | Per-model usage breakdown. Populated by the per-step retry loop when Agent.fallbackModels fires. Backward-compat: rehydrating a serialized state that omits the field synthesizes a single-entry map for the primary model. | packages/core/src/types/run.ts:117 |
userId? | readonly | string | - | packages/core/src/types/run.ts:104 |
verdicts? | public | RunVerdicts | Per-turn security verdicts, keyed by turn position '<stepNumber>:<offsetInStep>' (the step's assistant turn is offset 0; step 0 is the pre-step input stage). Stamped by the run loop's commit gates so downstream consumers - the Session.push boundary and the memory ingest gate - can exclude guardrail-blocked turns from long-term memory. Widen-only: gates only ever ADD entries. Compaction wipes entries for the turns it summarized away. Absent until a gate fires. | packages/core/src/types/run.ts:142 |