Graphorin API reference v0.7.0
Graphorin API reference / @graphorin/core / / RunState
Interface: RunState
Defined in: packages/core/src/types/run.ts:85
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.
Stable
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
agentId | readonly | string | - | packages/core/src/types/run.ts:87 |
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 (W-034) - the child's identity is durably recorded in RunState.handoffs, never here. | packages/core/src/types/run.ts:94 |
error? | public | RunError | - | packages/core/src/types/run.ts:142 |
finishedAt? | public | string | - | packages/core/src/types/run.ts:141 |
handoffs | readonly | HandoffRecord[] | - | packages/core/src/types/run.ts:101 |
id | readonly | string | - | packages/core/src/types/run.ts:86 |
messages | readonly | Message[] | - | packages/core/src/types/run.ts:99 |
pendingApprovals | readonly | ToolApproval[] | - | packages/core/src/types/run.ts:100 |
pendingSubRuns? | public | PendingSubRun[] | W-001: 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:139 |
promotedTools? | public | readonly string[] | AG-19: 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:124 |
sessionId | readonly | string | - | packages/core/src/types/run.ts:95 |
startedAt | readonly | string | - | packages/core/src/types/run.ts:140 |
status | public | RunStatus | - | packages/core/src/types/run.ts:97 |
steps | readonly | RunStep[] | - | packages/core/src/types/run.ts:98 |
taintSummary? | public | RunTaintSummary | AG-19: 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:119 |
todos? | public | readonly TodoItem[] | D6 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:131 |
usage | readonly | Usage | - | packages/core/src/types/run.ts:102 |
usageByModel? | public | RunStateUsageByModel | Per-model usage breakdown. Populated by the per-step retry loop when Agent.fallbackModels fires (RB-48 / suggested DEC-164 / suggested ADR-052). 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:110 |
userId? | readonly | string | - | packages/core/src/types/run.ts:96 |