@agentskit/statechart — for agents

#Purpose

Represent deterministic interaction state independently from UI frameworks, providers, agent execution, and persistence.

#Install

npm install @agentskit/statechart

#Primary exports

• defineStatechart(definition) — validates transition targets and returns a frozen definition.
• createStatechartInstance(definition, context, { instanceId, now }) — validates JSON context and creates revision zero.
• transitionStatechart(definition, instance, event, { now }) — pure synchronous transition with an accepted / rejected result.
• serializeStatechart(instance) — versioned JSON snapshot.
• restoreStatechart(definition, unknown) — runtime-validated restore using the definition's injected parseContext.
• notifyStatechartObserver(observer, result) — isolated observer delivery after transition.
• StatechartDiagnosticCodes / StatechartError — stable diagnostic surface.
• STATECHART_SNAPSHOT_VERSION — current serialized snapshot schema version.

#Constraints

• Supply IDs and timestamps from the host; the package has no clock or randomness.
• Context and event data must be JSON-compatible.
• Keep guards and reducers deterministic for replay equivalence.
• Persistence, event deduplication, effects, tools, agents, and rendering are outside this package.
• Never deserialize a definition; restore snapshots against trusted runtime code.

#Choose the right owner

• Interaction state and snapshots: @agentskit/statechart.
• Agent loop, durable execution, DAGs, tools, effects: @agentskit/runtime.
• Chat orchestration and shared contracts: @agentskit/core.
• Framework rendering and hooks: the matching UI binding.

#Source

• README
• ADR-0020
• Issue #1199