Skip to main content

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​

StateReducers

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​

GraphState

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​

GraphState

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​

GraphState

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​

GraphState

Current graph state (not mutated).

nodeId​

string

Id of the node that is about to execute.

Returns​

GraphState

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​

GraphState

Current graph state (not mutated).

patch​

Record<string, unknown>

Partial artifacts update emitted by a completed node.

Returns​

GraphState

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​

GraphState

Current graph state (not mutated).

patch​

Record<string, unknown>

Partial scratch update emitted by a completed node.

Returns​

GraphState

New GraphState with the merged scratch partition.