reactive-fsm 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Alvarado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,324 @@
+# 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.
+
+```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'
+
+const fsm = createFSM({
+  initialState: 'IDENTITY',
+  states: ['IDENTITY', 'BOOKING', 'PAYMENT'],
+  tools: {
+    IDENTITY: ['validate_dni'],
+    BOOKING: ['check_availability', 'reserve_slot'],
+    PAYMENT: ['process_payment'],
+  },
+  loopShield: { enabled: true, maxConsecutiveTools: 3 },
+})
+
+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
+
+```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 response = await generateText({
+  model: openai('gpt-4o'),
+  messages: [{ role: 'user', content: 'Quiero agendar una cita' }],
+  ...adapter.inject(),   // → { tools, prepareStep }
+})
+```
+
+#### OpenAI SDK
+
+```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' },
+]
+
+while (true) {
+  const { tools } = adapter.inject()
+
+  const response = await openai.chat.completions.create({
+    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
+}
+```
+
+---
+
+## Real-World Patterns
+
+### Booking Funnel (3 gates)
+
+```typescript
+const bookingFSM = 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'],
+  },
+  loopShield: { enabled: true, maxConsecutiveTools: 3 },
+})
+
+// Flow: GREETING → user shows interest → IDENTITY → collects data → SCHEDULING → booked → CONFIRMED
+```
+
+### Payment Gate (block everything except payment)
+
+```typescript
+const paymentFSM = createFSM({
+  initialState: 'SHOPPING',
+  states: ['SHOPPING', 'PAYMENT', 'CONFIRMED'],
+  tools: {
+    SHOPPING: ['browse', 'add_to_cart', 'checkout'],
+    PAYMENT: ['process_payment', 'cancel_order'],  // only these two
+    CONFIRMED: ['send_receipt'],
+  },
+})
+
+// When entering PAYMENT, the adapter removes all shopping tools.
+// The LLM can ONLY call process_payment or cancel_order.
+```
+
+### Conditional Tool: Admin vs User
+
+```typescript
+const registry: ToolEntry<{ role: 'user' | 'admin' }>[] = [
+  { name: 'view_profile', gates: ['DASHBOARD'], build: () => ({ /* ... */ }) },
+  {
+    name: 'delete_user',
+    gates: ['DASHBOARD'],
+    condition: (ctx) => ctx.role === 'admin',
+    build: () => ({ /* ... */ }),
+  },
+]
+
+// Regular user → only view_profile
+// Admin → view_profile + delete_user
+```
+
+---
+
+## API Reference
+
+### `createFSM(config)`
+
+```typescript
+interface FSMConfig {
+  initialState: string
+  states: string[]
+  tools: Record<string, string[]>       // state → tool names
+  loopShield?: LoopShieldConfig
+}
+
+interface FSMInstance {
+  readonly currentState: string
+  readonly allowedTools: string[]
+  readonly isLooping: boolean
+  transitionTo(state: string): void
+}
+```
+
+### `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
+}
+
+const shield = createLoopShield({ enabled: true, maxConsecutiveTools: 3 })
+shield.registerToolCall()
+shield.isLooping()   // boolean
+shield.reset()
+```
+
+---
+
+## 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
+```
+
+- **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
+
+MIT

package/dist/adapters/openai.d.ts

@@ -0,0 +1,14 @@
+import type { FSMInstance } from '../core/machine';
+import { type ToolEntry } from '../core/tool-gating';
+export interface OpenAIInjectResult {
+    tools: unknown[];
+}
+export interface OpenAIAdapter<TContext = any> {
+    inject(): OpenAIInjectResult;
+    isLooping(): boolean;
+    registerToolCall(): void;
+    resetLoopShield(): void;
+    refreshGate(state: string): void;
+}
+export declare function createOpenAIAdapter<TContext = any>(fsm: FSMInstance, registry: ToolEntry<TContext>[], context: TContext): OpenAIAdapter<TContext>;
+//# sourceMappingURL=openai.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,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,WAAW,EAChB,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAC/B,OAAO,EAAE,QAAQ,GAChB,aAAa,CAAC,QAAQ,CAAC,CAuBzB"}

package/dist/adapters/openai.js

@@ -0,0 +1,22 @@
+import { buildToolsForGate } from '../core/tool-gating';
+export function createOpenAIAdapter(fsm, registry, context) {
+    return {
+        inject() {
+            const toolMap = buildToolsForGate(fsm.currentState, context, registry);
+            return { tools: Object.values(toolMap) };
+        },
+        isLooping() {
+            return fsm.isLooping;
+        },
+        registerToolCall() {
+            fsm._registerToolCall();
+        },
+        resetLoopShield() {
+            fsm._resetLoopShield();
+        },
+        refreshGate(state) {
+            fsm._setState(state);
+        },
+    };
+}
+//# sourceMappingURL=openai.js.map

package/dist/adapters/openai.js.map

@@ -0,0 +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,GAAgB,EAChB,QAA+B,EAC/B,OAAiB;IAEjB,OAAO;QACL,MAAM;YACJ,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;YACvE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,CAAC;QAED,SAAS;YACP,OAAO,GAAG,CAAC,SAAS,CAAC;QACvB,CAAC;QAED,gBAAgB;YACd,GAAG,CAAC,iBAAiB,EAAE,CAAC;QAC1B,CAAC;QAED,eAAe;YACb,GAAG,CAAC,gBAAgB,EAAE,CAAC;QACzB,CAAC;QAED,WAAW,CAAC,KAAa;YACvB,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,28 @@
+import type { FSMInstance } from '../core/machine';
+import { type ToolEntry } from '../core/tool-gating';
+export interface VercelStepInfo {
+    toolCalls?: Array<{
+        toolName: string;
+        args?: unknown;
+    }>;
+    toolResults?: Array<{
+        toolName: string;
+        result?: unknown;
+    }>;
+}
+export interface VercelPrepareStepParams {
+    steps: VercelStepInfo[];
+    stepNumber: number;
+}
+export interface VercelInjectResult {
+    tools: Record<string, unknown>;
+    prepareStep?: (params: VercelPrepareStepParams) => Promise<{
+        toolChoice?: 'none';
+    } | Record<string, never>>;
+}
+export interface VercelAdapter<TContext = any> {
+    inject(): VercelInjectResult;
+    refreshGate(state: string): void;
+}
+export declare function createVercelAdapter<TContext = any>(fsm: FSMInstance, registry: ToolEntry<TContext>[], context: TContext): VercelAdapter<TContext>;
+//# sourceMappingURL=vercel-ai.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-ai.d.ts","sourceRoot":"","sources":["../../src/adapters/vercel-ai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,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,WAAW,EAChB,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAC/B,OAAO,EAAE,QAAQ,GAChB,aAAa,CAAC,QAAQ,CAAC,CA4CzB"}

package/dist/adapters/vercel-ai.js

@@ -0,0 +1,50 @@
+import { buildToolsForGate } from '../core/tool-gating';
+function syncTools(target, gate, ctx, registry) {
+    const fresh = buildToolsForGate(gate, ctx, registry);
+    for (const key of Object.keys(target)) {
+        delete target[key];
+    }
+    for (const [key, value] of Object.entries(fresh)) {
+        target[key] = value;
+    }
+}
+export function createVercelAdapter(fsm, registry, context) {
+    const tools = {};
+    let currentGate = null;
+    return {
+        inject() {
+            currentGate = fsm.currentState;
+            syncTools(tools, currentGate, context, registry);
+            return {
+                tools,
+                prepareStep: async ({ steps }) => {
+                    let consecutiveToolSteps = 0;
+                    for (let i = steps.length - 1; i >= 0; i--) {
+                        if ((steps[i].toolCalls?.length ?? 0) > 0) {
+                            consecutiveToolSteps++;
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                    fsm._resetLoopShield();
+                    for (let i = 0; i < consecutiveToolSteps; i++) {
+                        fsm._registerToolCall();
+                    }
+                    if (fsm.isLooping) {
+                        return { toolChoice: 'none' };
+                    }
+                    if (fsm.currentState !== currentGate) {
+                        currentGate = fsm.currentState;
+                        syncTools(tools, currentGate, context, registry);
+                    }
+                    return {};
+                },
+            };
+        },
+        refreshGate(state) {
+            fsm._setState(state);
+        },
+    };
+}
+//# sourceMappingURL=vercel-ai.js.map

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

@@ -0,0 +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,GAAgB,EAChB,QAA+B,EAC/B,OAAiB;IAEjB,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,IAAI,WAAW,GAAkB,IAAI,CAAC;IAEtC,OAAO;QACL,MAAM;YACJ,WAAW,GAAG,GAAG,CAAC,YAAY,CAAC;YAC/B,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,GAAG,CAAC,gBAAgB,EAAE,CAAC;oBACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,oBAAoB,EAAE,CAAC,EAAE,EAAE,CAAC;wBAC9C,GAAG,CAAC,iBAAiB,EAAE,CAAC;oBAC1B,CAAC;oBAED,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;wBAClB,OAAO,EAAE,UAAU,EAAE,MAAe,EAAE,CAAC;oBACzC,CAAC;oBAED,IAAI,GAAG,CAAC,YAAY,KAAK,WAAW,EAAE,CAAC;wBACrC,WAAW,GAAG,GAAG,CAAC,YAAY,CAAC;wBAC/B,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,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/loop-shield.d.ts

@@ -0,0 +1,11 @@
+export interface LoopShieldConfig {
+    enabled: boolean;
+    maxConsecutiveTools: number;
+}
+export interface LoopShieldInstance {
+    registerToolCall(): void;
+    isLooping(): boolean;
+    reset(): void;
+}
+export declare function createLoopShield(config: LoopShieldConfig): LoopShieldInstance;
+//# sourceMappingURL=loop-shield.d.ts.map

package/dist/core/loop-shield.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-shield.d.ts","sourceRoot":"","sources":["../../src/core/loop-shield.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,IAAI,IAAI,CAAC;IACzB,SAAS,IAAI,OAAO,CAAC;IACrB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,CAkB7E"}

package/dist/core/loop-shield.js

@@ -0,0 +1,19 @@
+export function createLoopShield(config) {
+    let consecutiveToolCalls = 0;
+    return {
+        registerToolCall() {
+            if (!config.enabled)
+                return;
+            consecutiveToolCalls++;
+        },
+        isLooping() {
+            if (!config.enabled)
+                return false;
+            return consecutiveToolCalls >= config.maxConsecutiveTools;
+        },
+        reset() {
+            consecutiveToolCalls = 0;
+        },
+    };
+}
+//# sourceMappingURL=loop-shield.js.map

package/dist/core/loop-shield.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-shield.js","sourceRoot":"","sources":["../../src/core/loop-shield.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,gBAAgB,CAAC,MAAwB;IACvD,IAAI,oBAAoB,GAAG,CAAC,CAAC;IAE7B,OAAO;QACL,gBAAgB;YACd,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO;YAC5B,oBAAoB,EAAE,CAAC;QACzB,CAAC;QAED,SAAS;YACP,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO,KAAK,CAAC;YAClC,OAAO,oBAAoB,IAAI,MAAM,CAAC,mBAAmB,CAAC;QAC5D,CAAC;QAED,KAAK;YACH,oBAAoB,GAAG,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/machine.d.ts

@@ -0,0 +1,18 @@
+import { type LoopShieldConfig } from './loop-shield';
+export interface FSMConfig {
+    initialState: string;
+    states: string[];
+    tools: Record<string, string[]>;
+    loopShield?: LoopShieldConfig;
+}
+export interface FSMInstance {
+    readonly currentState: string;
+    readonly allowedTools: string[];
+    readonly isLooping: boolean;
+    transitionTo(state: string): void;
+    _registerToolCall(): void;
+    _resetLoopShield(): void;
+    _setState(state: string): void;
+}
+export declare function createFSM(config: FSMConfig): FSMInstance;
+//# sourceMappingURL=machine.d.ts.map

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

@@ -0,0 +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,WAAW;IAC1B,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,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"}

package/dist/core/machine.js

@@ -0,0 +1,42 @@
+import { createLoopShield } from './loop-shield';
+export function createFSM(config) {
+    const validStates = new Set(config.states);
+    if (!validStates.has(config.initialState)) {
+        throw new Error(`Initial state "${config.initialState}" is not in the states list`);
+    }
+    let _currentState = config.initialState;
+    const shield = createLoopShield(config.loopShield ?? { enabled: false, maxConsecutiveTools: 3 });
+    function getAllowedTools() {
+        return config.tools[_currentState] ?? [];
+    }
+    return {
+        get currentState() {
+            return _currentState;
+        },
+        get allowedTools() {
+            return getAllowedTools();
+        },
+        get isLooping() {
+            return shield.isLooping();
+        },
+        transitionTo(state) {
+            if (!validStates.has(state)) {
+                throw new Error(`Invalid state "${state}". Valid states: ${config.states.join(', ')}`);
+            }
+            _currentState = state;
+        },
+        _registerToolCall() {
+            shield.registerToolCall();
+        },
+        _resetLoopShield() {
+            shield.reset();
+        },
+        _setState(state) {
+            if (!validStates.has(state)) {
+                throw new Error(`Invalid state "${state}". Valid states: ${config.states.join(', ')}`);
+            }
+            _currentState = state;
+        },
+    };
+}
+//# sourceMappingURL=machine.js.map

package/dist/core/machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.js","sourceRoot":"","sources":["../../src/core/machine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAyB,MAAM,eAAe,CAAC;AAmBxE,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"}

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

@@ -0,0 +1,8 @@
+export interface ToolEntry<TContext = any> {
+    name: string;
+    gates: string[];
+    condition?: (ctx: TContext) => boolean;
+    build: (ctx: TContext) => unknown;
+}
+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

@@ -0,0 +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"}

package/dist/core/tool-gating.js

@@ -0,0 +1,7 @@
+export function buildToolsForGate(gate, ctx, registry) {
+    return Object.fromEntries(registry
+        .filter((entry) => entry.gates.includes(gate))
+        .filter((entry) => entry.condition === undefined || entry.condition(ctx))
+        .map((entry) => [entry.name, entry.build(ctx)]));
+}
+//# sourceMappingURL=tool-gating.js.map

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

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { createFSM } from './core/machine';
+export type { FSMConfig, FSMInstance } from './core/machine';
+export { buildToolsForGate } 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';
+export { createVercelAdapter } from './adapters/vercel-ai';
+export type { VercelAdapter, VercelInjectResult, VercelStepInfo, VercelPrepareStepParams, } from './adapters/vercel-ai';
+export { createOpenAIAdapter } from './adapters/openai';
+export type { OpenAIAdapter, OpenAIInjectResult, } from './adapters/openai';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7D,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"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createFSM } from './core/machine';
+export { buildToolsForGate } from './core/tool-gating';
+export { createLoopShield } from './core/loop-shield';
+export { createVercelAdapter } from './adapters/vercel-ai';
+export { createOpenAIAdapter } from './adapters/openai';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,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"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "reactive-fsm",
+  "version": "1.0.0",
+  "description": "Reactive Finite State Machine for AI agent orchestration — zero dependencies core, conditional tool gating, loop shield, adapters for Vercel AI SDK and OpenAI SDK",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapters/vercel-ai": {
+      "types": "./dist/adapters/vercel-ai.d.ts",
+      "import": "./dist/adapters/vercel-ai.js"
+    },
+    "./adapters/openai": {
+      "types": "./dist/adapters/openai.d.ts",
+      "import": "./dist/adapters/openai.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "fsm",
+    "finite-state-machine",
+    "ai-agents",
+    "vercel-ai-sdk",
+    "openai",
+    "tool-gating"
+  ],
+  "author": "Alejandro Alvarado <roddcode.dev@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/roddcode/reactive-fsm"
+  },
+  "bugs": {
+    "url": "https://github.com/roddcode/reactive-fsm/issues"
+  },
+  "homepage": "https://github.com/roddcode/reactive-fsm#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "tsx": "^4.22.4",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
+  },
+  "peerDependencies": {
+    "ai": "^4.0.0",
+    "openai": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}