@falai/agent 1.2.7 → 2.0.0

package/examples/09-signals.ts

@@ -0,0 +1,144 @@
+/**
+ * Signals — pre-phase escalation with halt + replyWith, post-phase entity capture with extract.
+ * Teaches: Signal, SignalContext, SignalDirective, behavior: 'cooldown', extract schema.
+ * Read next: docs/reference/signals.md
+ */
+
+import {
+    createAgent,
+    GeminiProvider,
+    createSession,
+    type Signal,
+    type SignalContext,
+    type SignalDirective,
+    type SignalFiring,
+} from "@falai/agent";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface AppContext {
+    supportTier: "free" | "premium";
+}
+
+interface AppData {
+    topic: string;
+    sentiment: string;
+    contactName: string;
+    contactEmail: string;
+}
+
+// ─── Signal 1: Pre-phase escalation with cooldown ────────────────────────────
+// Detects angry messages BEFORE the LLM responds. Halts normal flow and
+// replies with an escalation notice. Cooldown prevents re-triggering for 60s.
+
+const escalationSignal: Signal<AppContext, AppData> = {
+    id: "escalation",
+    title: "Anger Escalation",
+    description: "Detects user frustration and halts to escalate.",
+    phase: "pre",
+
+    when: "The user is expressing strong frustration, anger, or threats to leave",
+
+    behavior: "cooldown",
+    cooldownMs: 60_000,
+
+    handler(ctx: SignalContext<AppContext, AppData>): SignalDirective<AppContext, AppData> {
+        // halt: stops the LLM call from running
+        // replyWith: sends a canned response instead
+        return {
+            halt: true,
+            replyWith: "I can see this is frustrating — let me connect you with a specialist right away.",
+            dataUpdate: { sentiment: "escalated" },
+            stopOtherSignals: true,
+        };
+    },
+};
+
+// ─── Signal 2: Post-phase entity capture with extract ────────────────────────
+// After the LLM responds, extracts contact info the user may have provided.
+// Uses `extract` schema so the classifier pulls structured data alongside
+// the match decision.
+
+interface ContactExtract {
+    name: string | null;
+    email: string | null;
+}
+
+const contactCaptureSignal: Signal<AppContext, AppData, ContactExtract> = {
+    id: "contact_capture",
+    title: "Contact Info Capture",
+    description: "Extracts name and email from the conversation when mentioned.",
+    phase: "post",
+
+    when: "The user has provided their name or email address in this message",
+
+    extract: {
+        type: "object",
+        properties: {
+            name: { type: ["string", "null"], description: "The user's full name, or null if not provided" },
+            email: { type: ["string", "null"], description: "The user's email address, or null if not provided" },
+        },
+        required: ["name", "email"],
+    } as const,
+
+    async handler(ctx: SignalContext<AppContext, AppData, ContactExtract>): Promise<void> {
+        const { extracted } = ctx;
+
+        // Only update fields that were actually extracted
+        if (extracted.name) {
+            await ctx.updateData({ contactName: extracted.name });
+        }
+        if (extracted.email) {
+            await ctx.updateData({ contactEmail: extracted.email });
+        }
+    },
+};
+
+// ─── Agent ───────────────────────────────────────────────────────────────────
+
+const agent = createAgent<AppContext, AppData>({
+    name: "SupportAgent",
+    provider: new GeminiProvider({
+        apiKey: process.env.GEMINI_API_KEY!,
+        model: "models/gemini-2.5-flash",
+    }),
+    context: { supportTier: "free" },
+    schema: {
+        type: "object",
+        properties: {
+            topic: { type: "string" },
+            sentiment: { type: "string" },
+            contactName: { type: "string" },
+            contactEmail: { type: "string" },
+        },
+    },
+    signals: [escalationSignal, contactCaptureSignal],
+    flows: [
+        {
+            title: "Support",
+            when: "User needs help with a product issue",
+            steps: [
+                { id: "triage", prompt: "Identify the user's issue and ask clarifying questions.", collect: ["topic"] },
+                { id: "resolve", prompt: "Provide a solution based on the identified topic." },
+            ],
+        },
+    ],
+});
+
+// ─── Run ─────────────────────────────────────────────────────────────────────
+
+const session = createSession<AppData>("signals-demo");
+
+const response = await agent.respond({
+    history: [{ role: "user", content: "This is ridiculous! I've been waiting 3 days. My name is Alex and my email is alex@example.com." }],
+    session,
+});
+
+console.log(response.message);
+
+// Observability: log which signals fired this turn
+if (response.triggeredSignals?.length) {
+    for (const firing of response.triggeredSignals as SignalFiring[]) {
+        console.log(`[signal] ${firing.id} (${firing.phase}) — ${firing.reason ?? "no reason"}`);
+    }
+}

package/examples/tsconfig.json

@@ -0,0 +1,30 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ESNext",
+        "lib": [
+            "ES2022",
+            "DOM"
+        ],
+        "moduleResolution": "bundler",
+        "types": [
+            "@types/bun"
+        ],
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "allowSyntheticDefaultImports": true,
+        "noEmit": true,
+        "paths": {
+            "@falai/agent": [
+                "../src/index.ts"
+            ]
+        },
+        "baseUrl": "."
+    },
+    "include": [
+        "./*.ts"
+    ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "1.2.7",
+  "version": "2.0.0",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -44,6 +44,7 @@
     "fix:cjs": "echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
+    "typecheck:examples": "tsc --noEmit --project examples/tsconfig.json",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
     "clean": "rm -rf dist",

package/src/adapters/MemoryAdapter.ts

@@ -171,14 +171,14 @@ class MemorySessionRepository<TData = Record<string, unknown>>
     return Promise.resolve(null);
   }
 
-  async updateRouteStep(
+  async updateFlowStep(
     id: string,
-    route?: string,
+    flow?: string,
     step?: string
   ): Promise<SessionData<TData> | null> {
     const session = this.sessions.get(id);
     if (session) {
-      session.currentRoute = route;
+      session.currentFlow = flow;
       session.currentStep = step;
       this.sessions.set(id, cloneDeep(session));
       return Promise.resolve(cloneDeep(session));

package/src/adapters/MongoAdapter.ts

@@ -213,13 +213,13 @@ class MongoSessionRepository<TData = Record<string, unknown>>
     return await this.update(id, { collectedData });
   }
 
-  async updateRouteStep(
+  async updateFlowStep(
     id: string,
-    route?: string,
+    flow?: string,
     step?: string
   ): Promise<SessionData<TData> | null> {
     return await this.update(id, {
-      currentRoute: route,
+      currentFlow: flow,
       currentStep: step,
     });
   }

package/src/adapters/OpenSearchAdapter.ts

@@ -194,9 +194,11 @@ export class OpenSearchAdapter<TData = Record<string, unknown>> implements Persi
               userId: { type: "keyword" },
               agentName: { type: "keyword" },
               status: { type: "keyword" },
-              currentRoute: { type: "keyword" },
+              currentFlow: { type: "keyword" },
               currentStep: { type: "keyword" },
               collectedData: { type: "object", enabled: false },
+              pendingDirective: { type: "object", enabled: false },
+              signals: { type: "object", enabled: false },
               messageCount: { type: "integer" },
               createdAt: { type: "date" },
               updatedAt: { type: "date" },
@@ -224,7 +226,7 @@ export class OpenSearchAdapter<TData = Record<string, unknown>> implements Persi
               userId: { type: "keyword" },
               role: { type: "keyword" },
               content: { type: "text" },
-              route: { type: "keyword" },
+              flow: { type: "keyword" },
               step: { type: "keyword" },
               toolCalls: { type: "object", enabled: false },
               event: { type: "object", enabled: false },
@@ -407,17 +409,17 @@ class OpenSearchSessionRepository<TData = Record<string, unknown>>
     return await this.findById(id);
   }
 
-  async updateRouteStep(
+  async updateFlowStep(
     id: string,
-    route?: string,
+    flow?: string,
     step?: string
   ): Promise<SessionData<TData> | null> {
     const doc: Record<string, unknown> = {
       updatedAt: new Date().toISOString(),
     };
 
-    if (route !== undefined) {
-      doc.currentRoute = route;
+    if (flow !== undefined) {
+      doc.currentFlow = flow;
     }
     if (step !== undefined) {
       doc.currentStep = step;
@@ -479,7 +481,7 @@ class OpenSearchSessionRepository<TData = Record<string, unknown>>
       userId: doc.userId as string | undefined,
       agentName: doc.agentName as string | undefined,
       status: doc.status as SessionData<TData>["status"],
-      currentRoute: doc.currentRoute as string | undefined,
+      currentFlow: doc.currentFlow as string | undefined,
       currentStep: doc.currentStep as string | undefined,
       collectedData: doc.collectedData as CollectedStateData<TData> | undefined,
       messageCount: (doc.messageCount as number) || 0,
@@ -647,7 +649,7 @@ class OpenSearchMessageRepository implements MessageRepository {
       userId: doc.userId as string | undefined,
       role: doc.role as MessageData["role"],
       content: doc.content as string,
-      route: doc.route as string | undefined,
+      flow: doc.flow as string | undefined,
       step: doc.step as string | undefined,
       toolCalls: doc.toolCalls as
         | Array<{ toolName: string; arguments: Record<string, unknown> }>

package/src/adapters/PostgreSQLAdapter.ts

@@ -1,6 +1,20 @@
 /**
  * PostgreSQL adapter for persistence
  * Raw SQL adapter for PostgreSQL with custom schemas
+ *
+ * ## v2 Migration
+ *
+ * If upgrading from v1, run the following migration on your sessions table:
+ *
+ * ```sql
+ * ALTER TABLE agent_sessions DROP COLUMN IF EXISTS pending_transition;
+ * ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS pending_directive JSONB;
+ * ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS signals JSONB;
+ * ```
+ *
+ * `pending_directive` stores the serialized `Directive` that the pipeline
+ * applies at the start of the next turn. `signals` is a reserved JSONB column
+ * for the v2.x Signals feature — pass-through only in v2.0.
  */
 
 import type {
@@ -111,9 +125,11 @@ export class PostgreSQLAdapter<TData = Record<string, unknown>> implements Persi
         user_id VARCHAR(255),
         agent_name VARCHAR(255),
         status VARCHAR(50) DEFAULT 'active',
-        current_route VARCHAR(255),
+        current_flow VARCHAR(255),
         current_step VARCHAR(255),
         collected_data JSONB,
+        pending_directive JSONB,
+        signals JSONB,
         message_count INTEGER DEFAULT 0,
         last_message_at TIMESTAMP,
         completed_at TIMESTAMP,
@@ -134,7 +150,7 @@ export class PostgreSQLAdapter<TData = Record<string, unknown>> implements Persi
         user_id VARCHAR(255),
         role VARCHAR(50) NOT NULL,
         content TEXT NOT NULL,
-        route VARCHAR(255),
+        flow VARCHAR(255),
         step VARCHAR(255),
         tool_calls JSONB,
         event JSONB,
@@ -242,9 +258,9 @@ class PostgreSQLSessionRepository<TData = Record<string, unknown>>
       fields.push(`collected_data = $${paramIndex++}`);
       values.push(JSON.stringify(data.collectedData));
     }
-    if (data.currentRoute !== undefined) {
-      fields.push(`current_route = $${paramIndex++}`);
-      values.push(data.currentRoute);
+    if (data.currentFlow !== undefined) {
+      fields.push(`current_flow = $${paramIndex++}`);
+      values.push(data.currentFlow);
     }
     if (data.currentStep !== undefined) {
       fields.push(`current_step = $${paramIndex++}`);
@@ -294,13 +310,13 @@ class PostgreSQLSessionRepository<TData = Record<string, unknown>>
     return await this.update(id, { collectedData });
   }
 
-  async updateRouteStep(
+  async updateFlowStep(
     id: string,
-    route?: string,
+    flow?: string,
     step?: string
   ): Promise<SessionData<TData> | null> {
     return await this.update(id, {
-      currentRoute: route,
+      currentFlow: flow,
       currentStep: step,
     });
   }
@@ -342,7 +358,7 @@ class PostgreSQLMessageRepository implements MessageRepository {
 
     const result = await this.client.query<MessageData>(
       `INSERT INTO ${this.tableName}
-       (id, session_id, user_id, role, content, route, step, tool_calls, event, created_at)
+       (id, session_id, user_id, role, content, flow, step, tool_calls, event, created_at)
        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, NOW())
        RETURNING *`,
       [
@@ -351,7 +367,7 @@ class PostgreSQLMessageRepository implements MessageRepository {
         data.userId || null,
         data.role,
         data.content,
-        data.route || null,
+        data.flow || null,
         data.step || null,
         JSON.stringify(data.toolCalls || null),
         JSON.stringify(data.event || null),

package/src/adapters/PrismaAdapter.ts

@@ -248,7 +248,7 @@ class PrismaSessionRepository<TData = Record<string, unknown>>
       userId: unmapped.userId as string | undefined,
       agentName: unmapped.agentName as string | undefined,
       status: unmapped.status as "active" | "completed" | "abandoned",
-      currentRoute: unmapped.currentRoute as string | undefined,
+      currentFlow: unmapped.currentFlow as string | undefined,
       currentStep: unmapped.currentStep as string | undefined,
       collectedData: unmapped.collectedData as CollectedStateData<TData>,
       messageCount: unmapped.messageCount as number | undefined,
@@ -360,16 +360,16 @@ class PrismaSessionRepository<TData = Record<string, unknown>>
     return this.unmapFields(result);
   }
 
-  async updateRouteStep(
+  async updateFlowStep(
     id: string,
-    route?: string,
+    flow?: string,
     step?: string
   ): Promise<SessionData<TData> | null> {
     const data: Record<string, unknown> = {
       [this.fieldMap.updatedAt || "updatedAt"]: new Date(),
     };
-    if (route !== undefined) {
-      data[this.fieldMap.currentRoute || "currentRoute"] = route;
+    if (flow !== undefined) {
+      data[this.fieldMap.currentFlow || "currentFlow"] = flow;
     }
     if (step !== undefined) {
       data[this.fieldMap.currentStep || "currentStep"] = step;
@@ -460,7 +460,7 @@ class PrismaMessageRepository implements MessageRepository {
       userId: unmapped.userId as string | undefined,
       role: unmapped.role as MessageRole,
       content: unmapped.content as string,
-      route: unmapped.route as string | undefined,
+      flow: unmapped.flow as string | undefined,
       step: unmapped.step as string | undefined,
       toolCalls: unmapped.toolCalls as
         | Array<{ toolName: string; arguments: Record<string, unknown> }>

package/src/adapters/RedisAdapter.ts

@@ -232,12 +232,12 @@ class RedisSessionRepository<TData = Record<string, unknown>>
     return this.update(id, { collectedData });
   }
 
-  async updateRouteStep(
+  async updateFlowStep(
     id: string,
-    route?: string,
+    flow?: string,
     step?: string
   ): Promise<SessionData<TData> | null> {
-    return this.update(id, { currentRoute: route, currentStep: step });
+    return this.update(id, { currentFlow: flow, currentStep: step });
   }
 
   async incrementMessageCount(id: string): Promise<SessionData<TData> | null> {

package/src/adapters/SQLiteAdapter.ts

@@ -1,6 +1,23 @@
 /**
  * SQLite adapter for persistence
  * Lightweight, file-based database perfect for local development
+ *
+ * ## v2 Migration
+ *
+ * If upgrading from v1, run the following migration on your sessions table:
+ *
+ * ```sql
+ * -- SQLite 3.35.0+ supports DROP COLUMN:
+ * ALTER TABLE agent_sessions DROP COLUMN pending_transition;
+ * -- For older versions, recreate the table without pending_transition.
+ *
+ * ALTER TABLE agent_sessions ADD COLUMN pending_directive TEXT;
+ * ALTER TABLE agent_sessions ADD COLUMN signals TEXT;
+ * ```
+ *
+ * `pending_directive` stores the JSON-serialized `Directive` that the pipeline
+ * applies at the start of the next turn. `signals` is a reserved TEXT (JSON)
+ * column for the v2.x Signals feature — pass-through only in v2.0.
  */
 
 import type {
@@ -100,9 +117,11 @@ export class SQLiteAdapter<TData = Record<string, unknown>> implements Persisten
         user_id TEXT,
         agent_name TEXT,
         status TEXT DEFAULT 'active',
-        current_route TEXT,
+        current_flow TEXT,
         current_step TEXT,
         collected_data TEXT,
+        pending_directive TEXT,
+        signals TEXT,
         message_count INTEGER DEFAULT 0,
         last_message_at TEXT,
         completed_at TEXT,
@@ -125,7 +144,7 @@ export class SQLiteAdapter<TData = Record<string, unknown>> implements Persisten
         user_id TEXT,
         role TEXT NOT NULL,
         content TEXT NOT NULL,
-        route TEXT,
+        flow TEXT,
         step TEXT,
         tool_calls TEXT,
         event TEXT,
@@ -233,9 +252,9 @@ class SQLiteSessionRepository<TData = Record<string, unknown>>
       fields.push("collected_data = ?");
       values.push(JSON.stringify(data.collectedData));
     }
-    if (data.currentRoute !== undefined) {
-      fields.push("current_route = ?");
-      values.push(data.currentRoute);
+    if (data.currentFlow !== undefined) {
+      fields.push("current_flow = ?");
+      values.push(data.currentFlow);
     }
     if (data.currentStep !== undefined) {
       fields.push("current_step = ?");
@@ -286,13 +305,13 @@ class SQLiteSessionRepository<TData = Record<string, unknown>>
     return await this.update(id, { collectedData });
   }
 
-  async updateRouteStep(
+  async updateFlowStep(
     id: string,
-    route?: string,
+    flow?: string,
     step?: string
   ): Promise<SessionData<TData> | null> {
     return await this.update(id, {
-      currentRoute: route,
+      currentFlow: flow,
       currentStep: step,
     });
   }
@@ -325,7 +344,7 @@ class SQLiteSessionRepository<TData = Record<string, unknown>>
       userId: (row.user_id as string) || undefined,
       agentName: (row.agent_name as string) || undefined,
       status: row.status as SessionStatus,
-      currentRoute: (row.current_route as string) || undefined,
+      currentFlow: (row.current_flow as string) || undefined,
       currentStep: (row.current_step as string) || undefined,
       collectedData: row.collected_data
         ? (JSON.parse(
@@ -363,7 +382,7 @@ class SQLiteMessageRepository implements MessageRepository {
 
     const stmt = this.db.prepare(`
       INSERT INTO ${this.tableName}
-      (id, session_id, user_id, role, content, route, step, tool_calls, event, created_at)
+      (id, session_id, user_id, role, content, flow, step, tool_calls, event, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
 
@@ -373,7 +392,7 @@ class SQLiteMessageRepository implements MessageRepository {
       data.userId || null,
       data.role,
       data.content,
-      data.route || null,
+      data.flow || null,
       data.step || null,
       JSON.stringify(data.toolCalls || null),
       JSON.stringify(data.event || null),
@@ -442,7 +461,7 @@ class SQLiteMessageRepository implements MessageRepository {
       userId: (row.user_id as string) || undefined,
       role: row.role as MessageData["role"],
       content: row.content as string,
-      route: (row.route as string) || undefined,
+      flow: (row.flow as string) || undefined,
       step: (row.step as string) || undefined,
       toolCalls: row.tool_calls
         ? (JSON.parse(row.tool_calls as string) as MessageData["toolCalls"])

package/src/constants/index.ts

@@ -1,10 +1,2 @@
-/**
- * Special marker to end a route/journey
- */
-export const END_ROUTE = Symbol("END_ROUTE");
-
-/**
- * String constant for END_ROUTE comparisons
- * Use this when checking if currentStep.id has reached END_ROUTE
- */
-export const END_ROUTE_ID = "END_ROUTE";
+// Constants module - intentionally empty after END_FLOW removal in v2
+// Flow completion is now implicit: the last step in a flow terminates it.