Graphorin API reference v0.1.0
Graphorin API reference / @graphorin/agent / run-state
run-state
RunState JSON serialization and rehydration.
The on-disk shape carries an explicit version field so future schema bumps can detect older payloads. v0.1 ships 'graphorin-run-state/1.0' — additive fields that older readers do not understand are ignored under the lenient-forward-parse discipline.
Interfaces
| Interface | Description |
|---|---|
| SerializedRunState | On-disk payload returned by serializeRunState and accepted by deserializeRunState. The shape is JSON-stable. |
| SerializeRunStateOptions | Options accepted by serializeRunState. |
Variables
| Variable | Description |
|---|---|
| RUN_STATE_SCHEMA_MAJOR_SUPPORTED | Reader-supported schema id range. Major version 1 only for v0.1. |
| RUN_STATE_SCHEMA_VERSION | Canonical schema id for serialized RunState payloads. |
Functions
| Function | Description |
|---|---|
| addModelUsage | Append a per-model usage entry to RunState.usageByModel. Mutates the supplied state in place — used by the agent runtime's per-step retry loop. Pure callers that need an immutable update should clone the state first. |
| aggregateUsageFromByModel | Recompute the aggregate usage from usageByModel. Returns the sum that callers can compare against state.usage to verify the per-step retry loop maintained the documented invariant. |
| completedToolCallsFromState | The "tools used" surface of a completed run. Cheap to compute from RunState.steps; surfaced as a stand-alone helper for Phase 17 example apps and operator-facing dashboards. |
| createInitialRunState | Build a fresh, minimal RunState for a new run. Helper used by createAgent({...}) so consumers can construct deterministic run state in tests. |
| deserializeRunState | Rehydrate a RunState from the on-disk payload. Throws RunStateVersionUnsupportedError when the payload version is from a future major; throws RunStateMalformedError when the payload is structurally invalid. |
| runStateFromJSON | Convenience JSON-string parser pairing with runStateToJSON. |
| runStateToJSON | Render the canonical JSON string representation of the supplied RunState. JSON.stringify(serializeRunState(state)) — provided as a convenience. |
| serializeRunState | Render a JSON-stable snapshot of the supplied RunState. The returned value is plain JSON (no Map, Set, Date, ...). |