reactive-fsm 1.1.0 → 1.2.0

package/README.md

@@ -1,27 +1,45 @@
 # reactive-fsm
 
-Reactive Finite State Machine for AI agent orchestration. Zero-dependency core with conditional tool gating, loop shield, and adapters for Vercel AI SDK and OpenAI SDK.
+[![npm](https://img.shields.io/npm/v/reactive-fsm)](https://www.npmjs.com/package/reactive-fsm)
+[![license](https://img.shields.io/npm/l/reactive-fsm)](https://github.com/roddcode/reactive-fsm/blob/main/LICENSE)
+
+**Deterministic control for AI agents with tool calling.** Define what tools an LLM can call at each step of a conversation. Zero dependencies. TypeScript.
+
+```mermaid
+stateDiagram-v2
+    GREETING: GREETING<br/><i>greet, show_services</i>
+    IDENTITY: IDENTITY<br/><i>collect_name, validate_dni</i>
+    BOOKING: BOOKING<br/><i>check_slots, reserve</i>
+    PAYMENT: PAYMENT<br/><i>process_payment</i>
+    CONFIRMED: CONFIRMED<br/><i>send_receipt</i>
+    [*] --> GREETING
+    [*] --> IDENTITY
+    [*] --> BOOKING
+    [*] --> PAYMENT
+    [*] --> CONFIRMED
+    GREETING --> [*]
+    IDENTITY --> [*]
+    BOOKING --> [*]
+    PAYMENT --> [*]
+    CONFIRMED --> [*]
+```
+
+> Generated by `fsm.toMermaid()`. Paste into any README, PR, or Notion.
+
+## What it does
+
+- **Tool gating per state.** In `PAYMENT`, the LLM sees only `process_payment` and `cancel_order`. No browsing, no upselling, no hallucinating tools that don't belong.
+- **Loop shield.** Detects when the LLM enters a tool-calling loop and forces it to stop. Configurable threshold. Prevents runaway token costs.
+- **Gate refresh mid-turn.** If a tool execution changes the conversation state (e.g., identity validated → move to booking), tools update immediately without restarting the FSM.
+- **Cross-session resume.** `snapshot()` returns `{ state }`. Store it anywhere. Next serverless invocation picks up where it left off.
+- **5 providers, 1 API.** Vercel AI SDK, OpenAI, Anthropic, LangChain, Google Gemini. Same FSM config, different adapter.
+
+## Get started
 
 ```bash
 pnpm add reactive-fsm
-# o npm install reactive-fsm
 ```
 
-## Concepts
-
-| Concept | Role |
-|---------|------|
-| **FSM** | Manages states and which tool names are allowed at each state |
-| **Tool Gating** | Registry of tool entries with runtime conditions and builders, filtered by gate |
-| **Loop Shield** | Detects consecutive tool-call loops and signals the adapter to force-stop |
-| **Adapters** | Translate the FSM into SDK-native format (Vercel AI SDK, OpenAI) |
-
----
-
-## Quick Start
-
-### 1. Define your FSM
-
 ```typescript
 import { createFSM } from 'reactive-fsm'
 
@@ -38,394 +56,182 @@ const fsm = createFSM({
 
 fsm.currentState        // 'IDENTITY'
 fsm.allowedTools        // ['validate_dni']
+
 fsm.transitionTo('BOOKING')
 fsm.allowedTools        // ['check_availability', 'reserve_slot']
 ```
 
-### 2. Build a tool registry
-
-```typescript
-import type { ToolEntry } from 'reactive-fsm'
-
-interface AppCtx { contactId: string; role: 'user' | 'admin' }
-
-const registry: ToolEntry<AppCtx>[] = [
-  {
-    name: 'validate_dni',
-    gates: ['IDENTITY'],
-    build: (ctx) => ({
-      description: `Validate DNI for ${ctx.contactId}`,
-      parameters: {},
-      execute: async () => ({ valid: true }),
-    }),
-  },
-  {
-    name: 'check_availability',
-    gates: ['BOOKING'],
-    build: () => ({
-      description: 'Check slot availability',
-      parameters: {},
-      execute: async () => ({ slots: ['10:00', '11:00'] }),
-    }),
-  },
-  {
-    name: 'reserve_slot',
-    gates: ['BOOKING'],
-    condition: (ctx) => ctx.contactId !== '',
-    build: () => ({
-      description: 'Reserve a time slot',
-      parameters: {},
-      execute: async () => ({ booked: true }),
-    }),
-  },
-  {
-    name: 'admin_panel',
-    gates: ['IDENTITY', 'BOOKING', 'PAYMENT'],
-    condition: (ctx) => ctx.role === 'admin',
-    build: () => ({
-      description: 'Access admin controls',
-      parameters: {},
-      execute: async () => ({ panel: 'open' }),
-    }),
-  },
-]
-```
-
-### 3. Use an adapter
-
-#### Vercel AI SDK
+### With Vercel AI SDK (3 lines)
 
 ```typescript
 import { createVercelAdapter } from 'reactive-fsm/adapters/vercel-ai'
-import { generateText } from 'ai'
-import { openai } from '@ai-sdk/openai'
 
-const adapter = createVercelAdapter(fsm, registry, appCtx)
+const adapter = createVercelAdapter(fsm, registry, context)
 
 const response = await generateText({
   model: openai('gpt-4o'),
-  messages: [{ role: 'user', content: 'Quiero agendar una cita' }],
-  ...adapter.inject(),   // → { tools, prepareStep }
+  messages,
+  ...adapter.inject(),   // { tools, prepareStep }
 })
 ```
 
-#### OpenAI SDK
+### With OpenAI (imperative loop)
 
 ```typescript
 import { createOpenAIAdapter } from 'reactive-fsm/adapters/openai'
-import OpenAI from 'openai'
 
-const openai = new OpenAI()
-const adapter = createOpenAIAdapter(fsm, registry, appCtx)
-
-const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
-  { role: 'user', content: 'Quiero agendar una cita' },
-]
+const adapter = createOpenAIAdapter(fsm, registry, context)
 
 while (true) {
   const { tools } = adapter.inject()
-
   const response = await openai.chat.completions.create({
-    model: 'gpt-4o',
-    messages,
-    tools,
+    model: 'gpt-4o', messages, tools,
     tool_choice: adapter.isLooping() ? 'none' : 'auto',
   })
-
-  const msg = response.choices[0].message
-  messages.push(msg)
-
-  if (msg.tool_calls?.length) {
-    adapter.registerToolCall()
-
-    // Execute tools, push results to messages
-    for (const tc of msg.tool_calls) {
-      const result = await executeTool(tc.function.name, tc.function.arguments)
-      messages.push({ role: 'tool', tool_call_id: tc.id, content: JSON.stringify(result) })
-    }
-
-    // If a tool mutated the DB state, refresh the gate
-    // adapter.refreshGate('BOOKING')
-    continue
-  }
-
-  console.log(msg.content)  // final response
-  break
-}
-```
-
-#### Anthropic SDK
-
-```typescript
-import { createAnthropicAdapter } from 'reactive-fsm/adapters/anthropic'
-import Anthropic from '@anthropic-ai/sdk'
-
-const anthropic = new Anthropic()
-const adapter = createAnthropicAdapter(fsm, registry, appCtx)
-
-const messages = [{ role: 'user' as const, content: 'Quiero agendar una cita' }]
-
-while (true) {
-  const { tools } = adapter.inject()
-
-  const response = await anthropic.messages.create({
-    model: 'claude-sonnet-4-20250514',
-    max_tokens: 1024,
-    messages,
-    tools,
-  })
-
-  const toolUses = response.content.filter(c => c.type === 'tool_use')
-  messages.push({ role: 'assistant', content: response.content })
-
-  if (toolUses.length > 0) {
-    adapter.registerToolCall()
-    if (adapter.isLooping()) break
-
-    const toolResults = toolUses.map(tc => ({
-      type: 'tool_result' as const,
-      tool_use_id: tc.id,
-      content: JSON.stringify(await executeTool(tc.name, tc.input)),
-    }))
-    messages.push({ role: 'user', content: toolResults })
-    continue
-  }
-
-  return response.content.find(c => c.type === 'text')?.text
-}
-```
-
-#### LangChain
-
-```typescript
-import { wrapWithFSM } from 'reactive-fsm/adapters/langchain'
-
-const wrapper = wrapWithFSM(fsm, registry, appCtx)
-// wrapper.getTools() returns available tools for current gate
-// wrapper.shouldStop() — check before each agent step
-// wrapper.onToolCall() — call after each tool invocation
-// wrapper.onStateChange('BOOKING') — refresh gate mid-flow
-
-// Integrate with your existing LangChain executor:
-const currentTools = Object.values(wrapper.getTools())
-// …pass to your agent, re-fetch tools each iteration
-```
-
-#### Google Gemini
-
-```typescript
-import { createGeminiAdapter } from 'reactive-fsm/adapters/gemini'
-import { GoogleGenerativeAI } from '@google/generative-ai'
-
-const genAI = new GoogleGenerativeAI(apiKey)
-const adapter = createGeminiAdapter(fsm, registry, appCtx)
-const model = genAI.getGenerativeModel({
-  model: 'gemini-2.0-flash',
-  tools: adapter.inject().tools,
-})
-
-const chat = model.startChat()
-
-while (true) {
-  const { tools } = adapter.inject()
-  const result = await chat.sendMessage(userMessage)
-  const calls = result.response.functionCalls()
-
-  if (calls?.length) {
+  if (response.choices[0].message.tool_calls?.length) {
     adapter.registerToolCall()
-    if (adapter.isLooping()) break
-
-    const parts = calls.map(call => ({
-      functionResponse: { name: call.name, response: executeTool(call.name, call.args) },
-    }))
-    await chat.sendMessage(parts)
     continue
   }
-
-  return result.response.text()
+  return response.choices[0].message.content
 }
 ```
 
----
-
-## Real-World Patterns
+## Real-world use cases
 
-### Booking Funnel (3 gates)
+### Booking funnel
 
 ```typescript
-const bookingFSM = createFSM({
+const booking = createFSM({
   initialState: 'GREETING',
   states: ['GREETING', 'IDENTITY', 'SCHEDULING', 'CONFIRMED'],
   tools: {
-    GREETING: ['greet', 'show_catalog'],
-    IDENTITY: ['collect_name', 'collect_dni', 'show_catalog'],
-    SCHEDULING: ['check_slots', 'book_appointment'],
-    CONFIRMED: ['send_confirmation'],
+    GREETING:    ['greet', 'show_services'],
+    IDENTITY:    ['collect_name', 'collect_contact'],
+    SCHEDULING:  ['check_slots', 'reserve_appointment'],
+    CONFIRMED:   ['send_confirmation', 'add_to_calendar'],
+  },
+  prompts: {
+    SCHEDULING: 'Offer available slots. Do not ask for identity again.',
   },
   loopShield: { enabled: true, maxConsecutiveTools: 3 },
 })
-
-// Flow: GREETING → user shows interest → IDENTITY → collects data → SCHEDULING → booked → CONFIRMED
 ```
 
-### Payment Gate (block everything except payment)
+In `SCHEDULING`, `collect_name` is gone. The LLM cannot loop back asking for data it already has.
+
+### Payment gate
 
 ```typescript
-const paymentFSM = createFSM({
-  initialState: 'SHOPPING',
-  states: ['SHOPPING', 'PAYMENT', 'CONFIRMED'],
+const checkout = createFSM({
+  initialState: 'BROWSING',
+  states: ['BROWSING', 'CART', 'PAYMENT', 'CONFIRMED'],
   tools: {
-    SHOPPING: ['browse', 'add_to_cart', 'checkout'],
-    PAYMENT: ['process_payment', 'cancel_order'],  // only these two
+    BROWSING:  ['search', 'add_to_cart'],
+    CART:      ['view_cart', 'apply_coupon', 'checkout'],
+    PAYMENT:   ['process_payment', 'cancel_order'],
     CONFIRMED: ['send_receipt'],
   },
+  guard: (from, to) => to === 'PAYMENT' && from !== 'CART' ? false : true,
 })
-
-// When entering PAYMENT, the adapter removes all shopping tools.
-// The LLM can ONLY call process_payment or cancel_order.
 ```
 
-### Conditional Tool: Admin vs User
+In `PAYMENT`: 2 tools. The LLM cannot browse, cannot suggest alternatives, cannot negotiate. The guard blocks jumping from BROWSING straight to PAYMENT.
+
+### Customer support with forced escalation
 
 ```typescript
-const registry: ToolEntry<{ role: 'user' | 'admin' }>[] = [
-  { name: 'view_profile', gates: ['DASHBOARD'], build: () => ({ /* ... */ }) },
-  {
-    name: 'delete_user',
-    gates: ['DASHBOARD'],
-    condition: (ctx) => ctx.role === 'admin',
-    build: () => ({ /* ... */ }),
+const support = createFSM({
+  initialState: 'TRIAGE',
+  states: ['TRIAGE', 'DIAGNOSIS', 'SOLUTION', 'ESCALATION'],
+  tools: {
+    TRIAGE:      ['classify_issue', 'verify_account'],
+    DIAGNOSIS:   ['search_kb', 'check_status'],
+    SOLUTION:    ['apply_fix', 'send_guide'],
+    ESCALATION:  ['transfer_to_human'],
   },
-]
-
-// Regular user → only view_profile
-// Admin → view_profile + delete_user
+  loopShield: { enabled: true, maxConsecutiveTools: 3 },
+})
 ```
 
----
+Loop shield triggers after 3 failed fix attempts. `ESCALATION` has exactly one tool. The bot cannot stay in the loop — it must escalate.
+
+## Adapters
+
+| Provider | Import | Loop shield |
+|----------|--------|-------------|
+| Vercel AI SDK | `reactive-fsm/adapters/vercel-ai` | Automatic via `prepareStep` |
+| OpenAI | `reactive-fsm/adapters/openai` | Manual via `isLooping()` |
+| Anthropic | `reactive-fsm/adapters/anthropic` | Manual via `isLooping()` |
+| LangChain | `reactive-fsm/adapters/langchain` | Manual via `shouldStop()` |
+| Google Gemini | `reactive-fsm/adapters/gemini` | Manual via `isLooping()` |
+
+All adapters share the same pattern: build an FSM once, pass it to any adapter, call `inject()` to get provider-formatted tools.
 
-## API Reference
+## vs LangGraph
 
-### `createFSM(config)`
+| | reactive-fsm | LangGraph |
+|---|---|---|
+| Dependencies | 0 (core) | LangChain + sub-dependencies |
+| Bundle size | ~7 KB | ~5 MB |
+| Define a 3-state FSM | 5 lines | 30+ lines |
+| Tool gating per state | Declarative (`tools: { ... }`) | Manual (`route_tools(state)`) |
+| Loop shield | Built-in | Not built-in |
+| Gate refresh mid-turn | Automatic | Manual |
+| Providers | Any (5 adapters) | LangChain ecosystem |
+
+[Full migration guide →](#) _(coming soon)_
+
+## API
 
 ```typescript
 interface FSMConfig {
   initialState: string
   states: string[]
-  tools: Record<string, string[]>       // state → tool names
-  loopShield?: LoopShieldConfig
+  tools: Record<string, string[]>
+  loopShield?: { enabled: boolean; maxConsecutiveTools: number }
+  onTransition?: (from: string, to: string) => void
+  guard?: (from: string, to: string) => boolean   // veto transitions
+  prompts?: Record<string, string>                 // state → system prompt
+  snapshot?: { state: string }                     // restore from saved state
 }
 
-interface FSMInstance {
-  readonly currentState: string
-  readonly allowedTools: string[]
-  readonly isLooping: boolean
-  transitionTo(state: string): void
+interface FSMPublic {
+  currentState: string          // getter
+  allowedTools: string[]        // getter
+  isLooping: boolean            // getter
+  transitionTo(state): void
+  snapshot(): { state: string }
+  toMermaid(): string           // Mermaid stateDiagram-v2
 }
 ```
 
-### `buildToolsForGate(gate, ctx, registry)`
-
 ```typescript
 interface ToolEntry<TContext = any> {
   name: string
   gates: string[]
-  condition?: (ctx: TContext) => boolean    // optional runtime filter
-  build: (ctx: TContext) => unknown          // returns the tool definition
-}
-
-function buildToolsForGate<TContext>(
-  gate: string,
-  ctx: TContext,
-  registry: ToolEntry<TContext>[]
-): Record<string, unknown>
-```
-
-### `createVercelAdapter(fsm, registry, context)`
-
-```typescript
-const adapter = createVercelAdapter(fsm, registry, context)
-
-const { tools, prepareStep } = adapter.inject()
-adapter.refreshGate('PAYMENT')   // external gate change (e.g., after DB mutation)
-```
-
-`prepareStep` automatically handles loop shield detection by counting consecutive tool steps from the history. When `maxConsecutiveTools` is exceeded, it returns `{ toolChoice: 'none' }`.
-
-### `createOpenAIAdapter(fsm, registry, context)`
-
-```typescript
-const adapter = createOpenAIAdapter(fsm, registry, context)
-
-const { tools } = adapter.inject()         // → { tools: OpenAI-formatted array }
-adapter.isLooping()                         // → boolean (check before each API call)
-adapter.registerToolCall()                  // → track tool call for loop shield
-adapter.resetLoopShield()                   // → reset counter
-adapter.refreshGate('PAYMENT')              // → external gate change
-```
-
-Since the OpenAI SDK is stateless, the consumer controls the orchestration loop. Use `isLooping()` to decide `tool_choice` and `registerToolCall()` after each API call that invoked tools.
-
-### `createLoopShield(config)`
-
-```typescript
-interface LoopShieldConfig {
-  enabled: boolean
-  maxConsecutiveTools: number
+  condition?: (ctx: TContext) => boolean
+  build: (ctx: TContext) => unknown
+  schema?: unknown              // Zod/Valibot/ArkType schema
 }
 
-const shield = createLoopShield({ enabled: true, maxConsecutiveTools: 3 })
-shield.registerToolCall()
-shield.isLooping()   // boolean
-shield.reset()
+buildToolsForGate(gate, ctx, registry): Record<string, unknown>
+validateWith(schema, args): { ok, data } | { ok, error }
 ```
 
----
-
-## Why reactive-fsm
-
-| | reactive-fsm | LangGraph | Manual |
-|---|---|---|---|
-| Dependencies | **0** (core) | LangChain + several | None |
-| Bundle size | **~7 KB** | ~5 MB | — |
-| Setup | **3 lines** | 30+ lines | 50+ lines |
-| Loop shield | **Built-in** | None | Manual |
-| Tool gating | **Per-state** | Manual filter | Manual |
-| Gate refresh | **Automatic** | None | None |
-| Provider | **Any** | LangChain-only | Any |
-| TypeScript | **100% typed** | Partial | Varies |
-
----
-
 ## Architecture
 
 ```
-src/
-├── core/
-│   ├── machine.ts          # createFSM() — state management
-│   ├── tool-gating.ts      # buildToolsForGate() — conditional tool injection
-│   └── loop-shield.ts      # createLoopShield() — cognitive loop detection
-├── adapters/
-│   ├── vercel-ai.ts        # createVercelAdapter() — Vercel AI SDK
-│   └── openai.ts           # createOpenAIAdapter() — OpenAI SDK
-└── index.ts
-```
+src/core/           — zero npm dependencies
+  machine.ts        createFSM()
+  tool-gating.ts    buildToolsForGate(), validateWith()
+  loop-shield.ts    createLoopShield()
 
-- **Core has zero npm dependencies.** Only TypeScript types.
-- **Adapters are optional.** `ai` and `openai` are optional peerDependencies.
-- **`ToolEntry<TContext>`** is fully generic — you define your own context shape.
-
----
-
-## Loop Shield
-
-The loop shield prevents LLMs from entering infinite tool-calling loops.
-
-- **Vercel adapter**: `prepareStep` counts consecutive tool steps from history and forces `toolChoice: 'none'` when `maxConsecutiveTools` is exceeded.
-- **OpenAI adapter**: the consumer checks `isLooping()` before each API call and sets `tool_choice: 'none'` when it returns `true`. Calls `registerToolCall()` after each tool-invoking response.
-
----
-
-## License
+src/adapters/       — optional peer dependencies
+  vercel-ai.ts      createVercelAdapter()
+  openai.ts         createOpenAIAdapter()
+  anthropic.ts      createAnthropicAdapter()
+  langchain.ts      wrapWithFSM()
+  gemini.ts         createGeminiAdapter()
+```
 
-MIT
+MIT · [GitHub](https://github.com/roddcode/reactive-fsm) · [Issues](https://github.com/roddcode/reactive-fsm/issues)

package/dist/adapters/openai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAExE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,aAAa,CAAC,QAAQ,GAAG,GAAG;IAC3C,MAAM,IAAI,kBAAkB,CAAC;IAC7B,SAAS,IAAI,OAAO,CAAC;IACrB,gBAAgB,IAAI,IAAI,CAAC;IACzB,eAAe,IAAI,IAAI,CAAC;IACxB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,GAAG,GAAG,EAChD,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAC/B,OAAO,EAAE,QAAQ,GAChB,aAAa,CAAC,QAAQ,CAAC,CAwBzB"}
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAExE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,aAAa,CAAC,QAAQ,GAAG,GAAG;IAC3C,MAAM,IAAI,kBAAkB,CAAC;IAC7B,SAAS,IAAI,OAAO,CAAC;IACrB,gBAAgB,IAAI,IAAI,CAAC;IACzB,eAAe,IAAI,IAAI,CAAC;IACxB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,GAAG,GAAG,EAChD,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAC/B,OAAO,EAAE,QAAQ,GAChB,aAAa,CAAC,QAAQ,CAAC,CAyBzB"}

package/dist/adapters/openai.js

@@ -17,6 +17,7 @@ export function createOpenAIAdapter(fsm, registry, context) {
         },
         refreshGate(state) {
             _fsm._setState(state);
+            _fsm._resetLoopShield();
         },
     };
 }

package/dist/adapters/openai.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAkB,MAAM,qBAAqB,CAAC;AAcxE,MAAM,UAAU,mBAAmB,CACjC,GAAc,EACd,QAA+B,EAC/B,OAAiB;IAEjB,MAAM,IAAI,GAAG,GAAkB,CAAC;IAChC,OAAO;QACL,MAAM;YACJ,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;YACxE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,CAAC;QAED,SAAS;YACP,OAAO,IAAI,CAAC,SAAS,CAAC;QACxB,CAAC;QAED,gBAAgB;YACd,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3B,CAAC;QAED,eAAe;YACb,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,CAAC;QAED,WAAW,CAAC,KAAa;YACvB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAkB,MAAM,qBAAqB,CAAC;AAcxE,MAAM,UAAU,mBAAmB,CACjC,GAAc,EACd,QAA+B,EAC/B,OAAiB;IAEjB,MAAM,IAAI,GAAG,GAAkB,CAAC;IAChC,OAAO;QACL,MAAM;YACJ,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;YACxE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,CAAC;QAED,SAAS;YACP,OAAO,IAAI,CAAC,SAAS,CAAC;QACxB,CAAC;QAED,gBAAgB;YACd,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3B,CAAC;QAED,eAAe;YACb,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,CAAC;QAED,WAAW,CAAC,KAAa;YACvB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACtB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/adapters/vercel-ai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vercel-ai.d.ts","sourceRoot":"","sources":["../../src/adapters/vercel-ai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAExE,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACxD,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,OAAO,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;CAC7G;AAED,MAAM,WAAW,aAAa,CAAC,QAAQ,GAAG,GAAG;IAC3C,MAAM,IAAI,kBAAkB,CAAC;IAC7B,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAiBD,wBAAgB,mBAAmB,CAAC,QAAQ,GAAG,GAAG,EAChD,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAC/B,OAAO,EAAE,QAAQ,GAChB,aAAa,CAAC,QAAQ,CAAC,CA6CzB"}
+{"version":3,"file":"vercel-ai.d.ts","sourceRoot":"","sources":["../../src/adapters/vercel-ai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAExE,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACxD,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,uBAAuB,KAAK,OAAO,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;CAC7G;AAED,MAAM,WAAW,aAAa,CAAC,QAAQ,GAAG,GAAG;IAC3C,MAAM,IAAI,kBAAkB,CAAC;IAC7B,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAiBD,wBAAgB,mBAAmB,CAAC,QAAQ,GAAG,GAAG,EAChD,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAC/B,OAAO,EAAE,QAAQ,GAChB,aAAa,CAAC,QAAQ,CAAC,CA8CzB"}

package/dist/adapters/vercel-ai.js

@@ -45,6 +45,7 @@ export function createVercelAdapter(fsm, registry, context) {
         },
         refreshGate(state) {
             _fsm._setState(state);
+            _fsm._resetLoopShield();
         },
     };
 }

package/dist/adapters/vercel-ai.js.map

@@ -1 +1 @@
-{"version":3,"file":"vercel-ai.js","sourceRoot":"","sources":["../../src/adapters/vercel-ai.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAkB,MAAM,qBAAqB,CAAC;AAsBxE,SAAS,SAAS,CAChB,MAA+B,EAC/B,IAAY,EACZ,GAAY,EACZ,QAAqB;IAErB,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;IACrD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,GAAc,EACd,QAA+B,EAC/B,OAAiB;IAEjB,MAAM,IAAI,GAAG,GAAkB,CAAC;IAChC,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,IAAI,WAAW,GAAkB,IAAI,CAAC;IAEtC,OAAO;QACL,MAAM;YACJ,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;YAChC,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;YAEjD,OAAO;gBACL,KAAK;gBACL,WAAW,EAAE,KAAK,EAAE,EAAE,KAAK,EAA2B,EAAE,EAAE;oBACxD,IAAI,oBAAoB,GAAG,CAAC,CAAC;oBAC7B,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;wBAC3C,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;4BAC1C,oBAAoB,EAAE,CAAC;wBACzB,CAAC;6BAAM,CAAC;4BACN,MAAM;wBACR,CAAC;oBACH,CAAC;oBAED,IAAI,CAAC,gBAAgB,EAAE,CAAC;oBACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,oBAAoB,EAAE,CAAC,EAAE,EAAE,CAAC;wBAC9C,IAAI,CAAC,iBAAiB,EAAE,CAAC;oBAC3B,CAAC;oBAED,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;wBACnB,OAAO,EAAE,UAAU,EAAE,MAAe,EAAE,CAAC;oBACzC,CAAC;oBAED,IAAI,IAAI,CAAC,YAAY,KAAK,WAAW,EAAE,CAAC;wBACtC,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;wBAChC,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;oBACnD,CAAC;oBAED,OAAO,EAAE,CAAC;gBACZ,CAAC;aACF,CAAC;QACJ,CAAC;QAED,WAAW,CAAC,KAAa;YACvB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"vercel-ai.js","sourceRoot":"","sources":["../../src/adapters/vercel-ai.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAkB,MAAM,qBAAqB,CAAC;AAsBxE,SAAS,SAAS,CAChB,MAA+B,EAC/B,IAAY,EACZ,GAAY,EACZ,QAAqB;IAErB,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;IACrD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,GAAc,EACd,QAA+B,EAC/B,OAAiB;IAEjB,MAAM,IAAI,GAAG,GAAkB,CAAC;IAChC,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,IAAI,WAAW,GAAkB,IAAI,CAAC;IAEtC,OAAO;QACL,MAAM;YACJ,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;YAChC,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;YAEjD,OAAO;gBACL,KAAK;gBACL,WAAW,EAAE,KAAK,EAAE,EAAE,KAAK,EAA2B,EAAE,EAAE;oBACxD,IAAI,oBAAoB,GAAG,CAAC,CAAC;oBAC7B,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;wBAC3C,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;4BAC1C,oBAAoB,EAAE,CAAC;wBACzB,CAAC;6BAAM,CAAC;4BACN,MAAM;wBACR,CAAC;oBACH,CAAC;oBAED,IAAI,CAAC,gBAAgB,EAAE,CAAC;oBACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,oBAAoB,EAAE,CAAC,EAAE,EAAE,CAAC;wBAC9C,IAAI,CAAC,iBAAiB,EAAE,CAAC;oBAC3B,CAAC;oBAED,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;wBACnB,OAAO,EAAE,UAAU,EAAE,MAAe,EAAE,CAAC;oBACzC,CAAC;oBAED,IAAI,IAAI,CAAC,YAAY,KAAK,WAAW,EAAE,CAAC;wBACtC,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;wBAChC,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;oBACnD,CAAC;oBAED,OAAO,EAAE,CAAC;gBACZ,CAAC;aACF,CAAC;QACJ,CAAC;QAED,WAAW,CAAC,KAAa;YACvB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACtB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/machine.d.ts

@@ -1,15 +1,26 @@
 import { type LoopShieldConfig } from './loop-shield';
+export interface FSMSnapshot {
+    state: string;
+}
 export interface FSMConfig {
     initialState: string;
     states: string[];
     tools: Record<string, string[]>;
     loopShield?: LoopShieldConfig;
+    onTransition?: (from: string, to: string) => void;
+    guard?: (from: string, to: string) => boolean;
+    prompts?: Record<string, string>;
+    snapshot?: FSMSnapshot;
+    context?: Record<string, unknown>;
 }
 export interface FSMPublic {
     readonly currentState: string;
     readonly allowedTools: string[];
     readonly isLooping: boolean;
     transitionTo(state: string): void;
+    snapshot(): FSMSnapshot;
+    toMermaid(): string;
+    context: Record<string, unknown>;
 }
 export interface FSMInstance extends FSMPublic {
     _registerToolCall(): void;

package/dist/core/machine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../src/core/machine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAExE,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,iBAAiB,IAAI,IAAI,CAAC;IAC1B,gBAAgB,IAAI,IAAI,CAAC;IACzB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,CAoDxD"}
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../src/core/machine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAExE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,IAAI,WAAW,CAAC;IACxB,SAAS,IAAI,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,iBAAiB,IAAI,IAAI,CAAC;IAC1B,gBAAgB,IAAI,IAAI,CAAC;IACzB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,CAuFxD"}

package/dist/core/machine.js

@@ -4,11 +4,23 @@ export function createFSM(config) {
     if (!validStates.has(config.initialState)) {
         throw new Error(`Initial state "${config.initialState}" is not in the states list`);
     }
-    let _currentState = config.initialState;
+    if (config.snapshot && !validStates.has(config.snapshot.state)) {
+        throw new Error(`Snapshot state "${config.snapshot.state}" is not in the states list`);
+    }
+    let _currentState = config.snapshot?.state ?? config.initialState;
+    const _context = config.context ? { ...config.context } : {};
     const shield = createLoopShield(config.loopShield ?? { enabled: false, maxConsecutiveTools: 3 });
     function getAllowedTools() {
         return config.tools[_currentState] ?? [];
     }
+    function doTransition(state) {
+        const from = _currentState;
+        if (config.guard && !config.guard(from, state)) {
+            throw new Error(`Guard blocked transition from "${from}" to "${state}"`);
+        }
+        _currentState = state;
+        config.onTransition?.(from, state);
+    }
     return {
         get currentState() {
             return _currentState;
@@ -23,7 +35,7 @@ export function createFSM(config) {
             if (!validStates.has(state)) {
                 throw new Error(`Invalid state "${state}". Valid states: ${config.states.join(', ')}`);
             }
-            _currentState = state;
+            doTransition(state);
         },
         _registerToolCall() {
             shield.registerToolCall();
@@ -35,8 +47,25 @@ export function createFSM(config) {
             if (!validStates.has(state)) {
                 throw new Error(`Invalid state "${state}". Valid states: ${config.states.join(', ')}`);
             }
-            _currentState = state;
+            doTransition(state);
+        },
+        snapshot() {
+            return { state: _currentState };
+        },
+        toMermaid() {
+            const lines = ['stateDiagram-v2'];
+            for (const state of config.states) {
+                const tools = (config.tools[state] ?? []).join('<br/>');
+                const label = tools ? `${state}<br/><i>${tools}</i>` : state;
+                lines.push(`    ${state}: ${label}`);
+            }
+            for (const state of config.states) {
+                lines.push(`    [*] --> ${state}`);
+                lines.push(`    ${state} --> [*]`);
+            }
+            return lines.join('\n');
         },
+        context: _context,
     };
 }
 //# sourceMappingURL=machine.js.map

package/dist/core/machine.js.map

@@ -1 +1 @@
-{"version":3,"file":"machine.js","sourceRoot":"","sources":["../../src/core/machine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAyB,MAAM,eAAe,CAAC;AAsBxE,MAAM,UAAU,SAAS,CAAC,MAAiB;IACzC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAE3C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,CAAC,YAAY,6BAA6B,CAAC,CAAC;IACtF,CAAC;IAED,IAAI,aAAa,GAAG,MAAM,CAAC,YAAY,CAAC;IAExC,MAAM,MAAM,GAAG,gBAAgB,CAC7B,MAAM,CAAC,UAAU,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,EAAE,CAChE,CAAC;IAEF,SAAS,eAAe;QACtB,OAAO,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;IAC3C,CAAC;IAED,OAAO;QACL,IAAI,YAAY;YACd,OAAO,aAAa,CAAC;QACvB,CAAC;QAED,IAAI,YAAY;YACd,OAAO,eAAe,EAAE,CAAC;QAC3B,CAAC;QAED,IAAI,SAAS;YACX,OAAO,MAAM,CAAC,SAAS,EAAE,CAAC;QAC5B,CAAC;QAED,YAAY,CAAC,KAAa;YACxB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,oBAAoB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACzF,CAAC;YACD,aAAa,GAAG,KAAK,CAAC;QACxB,CAAC;QAED,iBAAiB;YACf,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC5B,CAAC;QAED,gBAAgB;YACd,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;QAED,SAAS,CAAC,KAAa;YACrB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,oBAAoB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACzF,CAAC;YACD,aAAa,GAAG,KAAK,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"machine.js","sourceRoot":"","sources":["../../src/core/machine.ts"],"names":[],"mappings":"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"}

package/dist/core/tool-gating.d.ts

@@ -3,6 +3,14 @@ export interface ToolEntry<TContext = any> {
     gates: string[];
     condition?: (ctx: TContext) => boolean;
     build: (ctx: TContext) => unknown;
+    schema?: unknown;
 }
+export declare function validateWith(schema: unknown, args: unknown): {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: string;
+};
 export declare function buildToolsForGate<TContext = any>(gate: string, ctx: TContext, registry: ToolEntry<TContext>[]): Record<string, unknown>;
 //# sourceMappingURL=tool-gating.d.ts.map

package/dist/core/tool-gating.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-gating.d.ts","sourceRoot":"","sources":["../../src/core/tool-gating.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS,CAAC,QAAQ,GAAG,GAAG;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC;IACvC,KAAK,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC;CACnC;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,GAAG,GAAG,EAC9C,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,QAAQ,EACb,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB"}
+{"version":3,"file":"tool-gating.d.ts","sourceRoot":"","sources":["../../src/core/tool-gating.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS,CAAC,QAAQ,GAAG,GAAG;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC;IACvC,KAAK,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAMD,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,GACZ;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAa5D;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,GAAG,GAAG,EAC9C,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,QAAQ,EACb,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB"}

package/dist/core/tool-gating.js

@@ -1,3 +1,17 @@
+export function validateWith(schema, args) {
+    const s = schema;
+    if (!s || typeof s.safeParse !== 'function') {
+        return { ok: true, data: args };
+    }
+    const result = s.safeParse(args);
+    if (result.success) {
+        const data = 'data' in result ? result.data : 'output' in result ? result.output : args;
+        return { ok: true, data };
+    }
+    const issues = result.error?.issues ?? result.issues ?? [];
+    const error = issues.map((i) => i.message).join(', ') || 'Validation failed';
+    return { ok: false, error };
+}
 export function buildToolsForGate(gate, ctx, registry) {
     return Object.fromEntries(registry
         .filter((entry) => entry.gates.includes(gate))

package/dist/core/tool-gating.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-gating.js","sourceRoot":"","sources":["../../src/core/tool-gating.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,GAAa,EACb,QAA+B;IAE/B,OAAO,MAAM,CAAC,WAAW,CACvB,QAAQ;SACL,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;SAC7C,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;SACxE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAClD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool-gating.js","sourceRoot":"","sources":["../../src/core/tool-gating.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,YAAY,CAC1B,MAAe,EACf,IAAa;IAEb,MAAM,CAAC,GAAG,MAAsC,CAAC;IACjD,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;QAC5C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAClC,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,IAAI,GAAG,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAE,MAAkC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QACrH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC5B,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,MAAM,IAAI,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;IAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAsB,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,mBAAmB,CAAC;IAClG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,GAAa,EACb,QAA+B;IAE/B,OAAO,MAAM,CAAC,WAAW,CACvB,QAAQ;SACL,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;SAC7C,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;SACxE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAClD,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { createFSM as _createFSM } from './core/machine';
-import type { FSMConfig, FSMPublic } from './core/machine';
+import type { FSMConfig, FSMPublic, FSMSnapshot } from './core/machine';
 export { _createFSM as createFSM };
-export type { FSMConfig, FSMPublic };
-export { buildToolsForGate } from './core/tool-gating';
+export type { FSMConfig, FSMPublic, FSMSnapshot };
+export { buildToolsForGate, validateWith } from './core/tool-gating';
 export type { ToolEntry } from './core/tool-gating';
 export { createLoopShield } from './core/loop-shield';
 export type { LoopShieldConfig, LoopShieldInstance } from './core/loop-shield';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,EAAE,UAAU,IAAI,SAAS,EAAE,CAAC;AACnC,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;AAErC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EACV,aAAa,EACb,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAExE,OAAO,EAAE,UAAU,IAAI,SAAS,EAAE,CAAC;AACnC,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;AAElD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACrE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EACV,aAAa,EACb,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 import { createFSM as _createFSM } from './core/machine';
 export { _createFSM as createFSM };
-export { buildToolsForGate } from './core/tool-gating';
+export { buildToolsForGate, validateWith } from './core/tool-gating';
 export { createLoopShield } from './core/loop-shield';
 export { createVercelAdapter } from './adapters/vercel-ai';
 export { createOpenAIAdapter } from './adapters/openai';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGzD,OAAO,EAAE,UAAU,IAAI,SAAS,EAAE,CAAC;AAGnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAQ3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAMxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGzD,OAAO,EAAE,UAAU,IAAI,SAAS,EAAE,CAAC;AAGnC,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAQ3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAMxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reactive-fsm",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Reactive Finite State Machine for AI agent orchestration — zero dependencies core, conditional tool gating, loop shield, adapters for Vercel AI SDK, OpenAI, Anthropic, LangChain, and Google Gemini",
   "type": "module",
   "main": "dist/index.js",