Class: StateMachineGate

Defined in: packages/core/src/fsm/StateMachineGate.ts:196

Temporal Anti-Hallucination Engine.

Wraps an XState v5 finite state machine and controls which MCP tools are visible to the LLM based on the current workflow state.

Hard constraint: Tools not bound to the current state are removed from tools/list entirely — the LLM physically cannot call them.

Soft constraint: suggestActions (HATEOAS) continues to recommend the best next action within the visible set. Zero conflict.

Constructors

Constructor

new StateMachineGate(config): StateMachineGate;

Defined in: packages/core/src/fsm/StateMachineGate.ts:207

Parameters

Parameter	Type	Description
config	FsmConfig	FSM definition (states, transitions, initial state)

Returns

StateMachineGate

Accessors

currentState

Get Signature

get currentState(): string;

Defined in: packages/core/src/fsm/StateMachineGate.ts:293

Get the current FSM state.

Returns

string

---

hasBindings

Get Signature

get hasBindings(): boolean;

Defined in: packages/core/src/fsm/StateMachineGate.ts:337

Check if any tools are bound to this FSM gate.

Returns

boolean

true if at least one tool is state-gated

Methods

bindTool()

bindTool(
   toolName, 
   allowedStates, 
   transitionEvent?): StateMachineGate;

Defined in: packages/core/src/fsm/StateMachineGate.ts:279

Bind a tool to specific FSM states.

The tool will only appear in tools/list when the FSM is in one of the specified states.

Parameters

Parameter	Type	Description
toolName	string	MCP tool name (flat: cart_add_item, grouped: cart)
allowedStates	string[]	FSM states where this tool is visible
transitionEvent?	string	Event to send on successful execution (optional)

Returns

StateMachineGate

this for chaining

Example

gate.bindTool('cart_add_item', ['empty', 'has_items'], 'ADD_ITEM');
gate.bindTool('cart_checkout', ['has_items'], 'CHECKOUT');

---

clone()

clone(): StateMachineGate;

Defined in: packages/core/src/fsm/StateMachineGate.ts:474

Create a lightweight clone of this gate with the same config and bindings but independent mutable state.

Used in serverless/edge deployments where concurrent requests must not share _currentState. Each request gets its own clone, restores session state into it, transitions, and saves — without interfering with other concurrent requests.

The clone starts uninitialized (no XState actor) so the first transition() call will create a fresh actor from the cloned state.

Returns

StateMachineGate

A new StateMachineGate with identical config and bindings

---

dispose()

dispose(): void;

Defined in: packages/core/src/fsm/StateMachineGate.ts:491

Stop the XState actor and release resources.

Returns

void

---

getTransitionEvent()

getTransitionEvent(toolName): string | undefined;

Defined in: packages/core/src/fsm/StateMachineGate.ts:328

Get the transition event for a tool (if any).

Parameters

Parameter	Type	Description
toolName	string	MCP tool name

Returns

string | undefined

The event string, or undefined if no transition is bound

---

getVisibleToolNames()

getVisibleToolNames(toolNames): string[];

Defined in: packages/core/src/fsm/StateMachineGate.ts:318

Filter a list of tool names by the current FSM state.

Parameters

Parameter	Type	Description
toolNames	string[]	All registered tool names

Returns

string[]

Only the tools allowed in the current state

---

init()

init(): Promise<boolean>;

Defined in: packages/core/src/fsm/StateMachineGate.ts:222

Initialize the XState actor (lazy-loaded).

Called automatically on first use. Can be called explicitly at boot time for eager initialization.

Returns

Promise<boolean>

true if XState is available and the actor started

---

isToolAllowed()

isToolAllowed(toolName): boolean;

Defined in: packages/core/src/fsm/StateMachineGate.ts:306

Check if a specific tool is allowed in the current FSM state.

Tools not registered via bindTool() are always visible (ungated — they don't participate in FSM gating).

Parameters

Parameter	Type	Description
toolName	string	MCP tool name to check

Returns

boolean

true if the tool should appear in tools/list

---

onTransition()

onTransition(callback): () => void;

Defined in: packages/core/src/fsm/StateMachineGate.ts:408

Register a callback that fires when the FSM state changes.

Used by ServerAttachment to emit notifications/tools/list_changed when a state transition makes tools appear or disappear.

Parameters

Parameter	Type	Description
callback	() => void	Function to call on state change

Returns

Unsubscribe function

(): void;

Returns

void

---

restore()

restore(snap): void;

Defined in: packages/core/src/fsm/StateMachineGate.ts:443

Restore FSM state from a persisted snapshot.

Resets the XState actor (if running) so the next transition() re-initializes the machine starting from the restored state. This ensures restore → transition works correctly in serverless/edge deployments (Vercel, Cloudflare Workers).

Parameters

Parameter	Type	Description
snap	FsmSnapshot	Previously saved snapshot

Returns

void

---

snapshot()

snapshot(): FsmSnapshot;

Defined in: packages/core/src/fsm/StateMachineGate.ts:426

Create a serializable snapshot of the current FSM state.

Used with FsmStateStore for serverless deployments where FSM state must survive across request boundaries.

Returns

FsmSnapshot

Serializable snapshot

---

transition()

transition(eventType): Promise<TransitionResult>;

Defined in: packages/core/src/fsm/StateMachineGate.ts:349

Send an event to the FSM, potentially triggering a state transition.

Parameters

Parameter	Type	Description
eventType	string	The event to send (e.g. 'ADD_ITEM', 'CHECKOUT')

Returns

Promise<TransitionResult>

Result indicating whether the state changed