Class: StateManager
Defined in: packages/agentos/src/orchestration/runtime/StateManager.ts:75
Manages the GraphState partitions (input, scratch, artifacts,
memory, diagnostics) for a single graph run.
All methods return a new GraphState object; the original is never mutated.
Example
const manager = new StateManager({ 'scratch.messages': 'concat' });
let state = manager.initialize({ prompt: 'Hello' });
state = manager.updateScratch(state, { messages: ['first'] });
state = manager.updateScratch(state, { messages: ['second'] });
// state.scratch.messages === ['first', 'second']
Constructors
Constructor
new StateManager(
reducers):StateManager
Defined in: packages/agentos/src/orchestration/runtime/StateManager.ts:81
Parameters
reducers
Field-level reducer configuration keyed by dot-notation paths
(e.g. 'scratch.messages'). Determines how conflicting values
are merged during updateScratch() and mergeParallelBranches().
Returns
StateManager
Methods
initialize()
initialize(
input):GraphState
Defined in: packages/agentos/src/orchestration/runtime/StateManager.ts:96
Create a clean initial GraphState from the caller-supplied input value.
The input partition is frozen with Object.freeze() so that no node can
accidentally mutate it. All other partitions start empty.
Parameters
input
unknown
Arbitrary value provided by the graph caller; becomes state.input.
Returns
A fully initialised GraphState ready for the first node execution.
mergeParallelBranches()
mergeParallelBranches(
baseState,branchStates,writes?):GraphState
Defined in: packages/agentos/src/orchestration/runtime/StateManager.ts:220
Merge the scratch and artifacts partitions of one or more parallel branch
states back into a single GraphState.
Each branch started from baseState, so its state also holds every key it did
not write. A branch contributes only the keys it wrote, so a value it carried
from baseState never replaces another branch's write. The branches are merged
in the order given: for each key a branch wrote, the reducer registered at
scratch.<key> or artifacts.<key> (if any) combines the branch's value with
the value merged so far, when there is one; otherwise the branch's value
replaces it, so the last branch to write a key wins.
The merged value starts from baseState's, so a branch's value for a key with
a reducer has to be the value the branch wrote: a value the reducer already
combined with baseState's, as updateScratch() leaves it, counts
baseState's value again. GraphRuntime passes each branch's state with the
scratch values its node wrote.
Each merged key is an own property of the merged partition, __proto__
included, as updateScratch() and updateArtifacts() keep it.
The memory, diagnostics, visitedNodes, and iteration fields of
baseState are preserved unchanged — the caller is responsible for merging
those separately if needed.
Parameters
baseState
State prior to the parallel fan-out (provides the baseline scratch and artifacts).
branchStates
GraphState<unknown, unknown, unknown>[]
States produced by each parallel branch.
writes?
readonly (ParallelBranchWrites | undefined)[]
What each branch wrote, at the index of its state in
branchStates: the scratch and artifacts patches its
node applied. Only their keys are read; the values come from
the branch states. A branch with no entry wrote nothing.
Without writes, a branch's writes are the keys
whose value differs from baseState's (compared with
Object.is), so a branch that writes the value a key held
before the fan-out is taken as leaving the key alone.
Returns
New GraphState with the merged scratch and artifacts partitions.
recordNodeVisit()
recordNodeVisit(
state,nodeId):GraphState
Defined in: packages/agentos/src/orchestration/runtime/StateManager.ts:173
Record that execution has entered nodeId.
Updates currentNodeId, appends to visitedNodes, and increments iteration.
Parameters
state
Current graph state (not mutated).
nodeId
string
Id of the node that is about to execute.
Returns
New GraphState reflecting the visit.
updateArtifacts()
updateArtifacts(
state,patch):GraphState
Defined in: packages/agentos/src/orchestration/runtime/StateManager.ts:157
Apply a patch to the artifacts partition using last-write-wins semantics.
Artifact fields are intended for caller-facing outputs and are not subject to
reducer logic in this method. If you need reducer-aware artifact merging, use
mergeParallelBranches() instead.
Parameters
state
Current graph state (not mutated).
patch
Record<string, unknown>
Partial artifacts update emitted by a completed node.
Returns
New GraphState with the updated artifacts partition.
updateScratch()
updateScratch(
state,patch):GraphState
Defined in: packages/agentos/src/orchestration/runtime/StateManager.ts:126
Apply a patch to the scratch partition, honoring any registered reducers.
For each key in patch:
- If a reducer is registered at
scratch.<key>and the key already exists in the current scratch, the reducer is called to merge the existing and incoming values. - Otherwise the incoming value simply overwrites (last-write-wins semantics).
Each key becomes an own property of the new scratch, __proto__ included, as
a patch parsed from JSON can carry it: it never sets the prototype of the
scratch, so nothing reads a value no node wrote.
Parameters
state
Current graph state (not mutated).
patch
Record<string, unknown>
Partial scratch update emitted by a completed node.
Returns
New GraphState with the merged scratch partition.