@falai/agent 0.6.8 → 0.7.0

package/src/core/Step.ts

@@ -0,0 +1,197 @@
+/**
+ * Step in the route DSL
+ */
+
+import type { StepRef, TransitionSpec, TransitionResult } from "../types/route";
+import type { Guideline } from "../types/agent";
+
+import { END_ROUTE } from "../constants";
+import { Transition } from "./Transition";
+import { generateStepId } from "../utils/id";
+
+/**
+ * Represents a step within a route
+ */
+export class Step<TContext = unknown, TData = unknown> {
+  public readonly id: string;
+  private transitions: Transition<TContext, TData>[] = [];
+  private guidelines: Guideline[] = [];
+  public collectFields?: string[];
+  public skipIf?: (data: Partial<TData>) => boolean;
+  public requires?: string[];
+  public instructions?: string;
+
+  constructor(
+    public readonly routeId: string,
+    public description?: string,
+    customId?: string,
+    collectFields?: string[],
+    skipIf?: (data: Partial<TData>) => boolean,
+    requires?: string[],
+    instructions?: string
+  ) {
+    // Use provided ID or generate a deterministic one
+    this.id = customId || generateStepId(routeId, description);
+    this.collectFields = collectFields;
+    this.skipIf = skipIf;
+    this.requires = requires;
+    this.instructions = instructions;
+  }
+
+  /**
+   * Configure the step properties after creation
+   * Useful for overriding initial step configuration
+   */
+  configure(config: {
+    description?: string;
+    collectFields?: string[];
+    skipIf?: (data: Partial<TData>) => boolean;
+    requires?: string[];
+    instructions?: string;
+  }): this {
+    if (config.description !== undefined) {
+      this.description = config.description;
+    }
+    if (config.collectFields !== undefined) {
+      this.collectFields = config.collectFields;
+    }
+    if (config.skipIf !== undefined) {
+      this.skipIf = config.skipIf;
+    }
+    if (config.requires !== undefined) {
+      this.requires = config.requires;
+    }
+    if (config.instructions !== undefined) {
+      this.instructions = config.instructions;
+    }
+    return this;
+  }
+
+  /**
+   * Create a transition from this step to another
+   *
+   * @param spec - Transition specification (instructions, tool, or direct step)
+   * @returns TransitionResult that supports chaining
+   */
+  nextStep(
+    spec: TransitionSpec<TContext, TData>
+  ): TransitionResult<TContext, TData> {
+    // Handle END_ROUTE
+    if (spec.step && typeof spec.step === "symbol" && spec.step === END_ROUTE) {
+      const endTransition = new Transition<TContext, TData>(this.getRef(), {
+        step: END_ROUTE,
+        condition: spec.condition,
+        instructions: spec.instructions,
+      });
+      this.transitions.push(endTransition);
+
+      // Return a terminal step reference
+      return this.createTerminalRef();
+    }
+
+    // Handle direct step reference
+    if (spec.step && typeof spec.step !== "symbol") {
+      const transition = new Transition<TContext, TData>(this.getRef(), spec);
+      this.transitions.push(transition);
+
+      return this.createStepRefWithTransition(spec.step);
+    }
+
+    // Create new target step for instructions or tool
+    const targetStep = new Step<TContext, TData>(
+      this.routeId,
+      spec.instructions,
+      spec.id, // Use custom ID if provided
+      spec.collect,
+      spec.skipIf,
+      spec.requires,
+      spec.instructions
+    );
+    const transition = new Transition<TContext, TData>(this.getRef(), spec);
+    transition.setTarget(targetStep);
+
+    this.transitions.push(transition);
+
+    return this.createStepRefWithTransition(targetStep.getRef(), targetStep);
+  }
+
+  /**
+   * Add a guideline specific to this step
+   */
+  addGuideline(guideline: Guideline): void {
+    this.guidelines.push(guideline);
+  }
+
+  /**
+   * Get guidelines for this step
+   */
+  getGuidelines(): Guideline[] {
+    return [...this.guidelines];
+  }
+
+  /**
+   * Get all transitions from this step
+   */
+  getTransitions(): Transition<TContext, TData>[] {
+    return [...this.transitions];
+  }
+
+  /**
+   * Check if this step should be skipped based on collected data
+   */
+  shouldSkip(data: Partial<TData>): boolean {
+    if (!this.skipIf) return false;
+    return this.skipIf(data);
+  }
+
+  /**
+   * Check if this step has all required data to proceed
+   */
+  hasRequires(data: Partial<TData>): boolean {
+    if (!this.requires || this.requires.length === 0) return true;
+    return this.requires.every((key) => data[key as keyof TData] !== undefined);
+  }
+
+  /**
+   * Get step reference
+   */
+  getRef(): StepRef {
+    return {
+      id: this.id,
+      routeId: this.routeId,
+    };
+  }
+
+  /**
+   * Create a step reference with nextStep capability for chaining
+   */
+  private createStepRefWithTransition(
+    ref: StepRef,
+    step?: Step<TContext, TData>
+  ): TransitionResult<TContext, TData> {
+    const stepInstance = step || this;
+
+    return {
+      ...ref,
+      nextStep: (spec: TransitionSpec<TContext, TData>) =>
+        stepInstance.nextStep(spec),
+    };
+  }
+
+  /**
+   * Create a terminal step reference (for END_ROUTE)
+   */
+  private createTerminalRef(): TransitionResult<TContext, TData> {
+    const terminalRef: StepRef = {
+      id: "END",
+      routeId: this.routeId,
+    };
+
+    return {
+      ...terminalRef,
+      nextStep: () => {
+        throw new Error("Cannot transition from END_ROUTE step");
+      },
+    };
+  }
+}

package/src/core/ToolExecutor.ts

@@ -13,13 +13,13 @@ export interface ToolExecutionResult {
   success: boolean;
   data?: unknown;
   contextUpdate?: Record<string, unknown>;
-  extractedUpdate?: Record<string, unknown>;
+  collectedUpdate?: Record<string, unknown>;
   error?: string;
 }
 
-export class ToolExecutor<TContext = unknown, TExtracted = unknown> {
+export class ToolExecutor<TContext = unknown, TData = unknown> {
   /**
-   * Execute a single tool with context and extracted data
+   * Execute a single tool with context and collected data
    * @param allowedDomains - Array of domain names allowed for this execution context (undefined = all domains allowed)
    */
   async executeTool(
@@ -27,7 +27,7 @@ export class ToolExecutor<TContext = unknown, TExtracted = unknown> {
     context: TContext,
     updateContext: (updates: Partial<TContext>) => Promise<void>,
     history: Event[],
-    extracted?: Partial<TExtracted>,
+    data?: Partial<TData>,
     allowedDomains?: string[]
   ): Promise<ToolExecutionResult> {
     try {
@@ -47,15 +47,15 @@ export class ToolExecutor<TContext = unknown, TExtracted = unknown> {
         }
       }
 
-      // Build tool context with extracted data
-      const toolContext: ToolContext<TContext, TExtracted> = {
+      // Build tool context with collected data
+      const toolContext: ToolContext<TContext, TData> = {
         context,
         updateContext,
         history,
-        extracted,
+        data,
       };
 
-      // Execute tool (no arguments - tools read from context/extracted)
+      // Execute tool (no arguments - tools read from context/data)
       const result = await tool.handler(toolContext);
 
       // Return execution result
@@ -64,7 +64,7 @@ export class ToolExecutor<TContext = unknown, TExtracted = unknown> {
         success: true,
         data: result.data,
         contextUpdate: result.contextUpdate,
-        extractedUpdate: result.extractedUpdate,
+        collectedUpdate: result.collectedUpdate,
       };
     } catch (error) {
       return {
@@ -84,7 +84,7 @@ export class ToolExecutor<TContext = unknown, TExtracted = unknown> {
     context: TContext,
     updateContext: (updates: Partial<TContext>) => Promise<void>,
     history: Event[],
-    extracted?: Partial<TExtracted>,
+    data?: Partial<TData>,
     allowedDomains?: string[]
   ): Promise<ToolExecutionResult[]> {
     const results: ToolExecutionResult[] = [];
@@ -95,7 +95,7 @@ export class ToolExecutor<TContext = unknown, TExtracted = unknown> {
         context,
         updateContext,
         history,
-        extracted,
+        data,
         allowedDomains
       );
       results.push(result);

package/src/core/Transition.ts

@@ -1,44 +1,90 @@
 /**
- * Transition between states in the route DSL
+ * Transition between steps in the route DSL
  */
 
-import type { StateRef, TransitionSpec } from "../types/route";
-import type { State } from "./State";
+import type {
+  StepRef,
+  TransitionSpec,
+  InlineToolHandler,
+} from "../types/route";
+import type { Step } from "./Step";
+import type { ToolRef, ToolResult, ToolContext } from "../types/tool";
+import { generateInlineToolId } from "../utils/id";
 
 /**
- * Represents a transition from one state to another
+ * Represents a transition from one step to another
  */
-export class Transition<TContext = unknown, TExtracted = unknown> {
-  private target?: State<TContext, TExtracted>;
+export class Transition<TContext = unknown, TData = unknown> {
+  private target?: Step<TContext, TData>;
   public readonly condition?: string;
 
   constructor(
-    public readonly source: StateRef,
-    public readonly spec: TransitionSpec<TContext, TExtracted>
+    public readonly source: StepRef,
+    public readonly spec: TransitionSpec<TContext, TData>
   ) {
     // Extract condition from spec for convenience
     this.condition = spec.condition;
-  }
 
+    // Normalize tool if present
+    if (spec.tool) {
+      this.spec = {
+        ...spec,
+        tool: this.normalizeTool(spec.tool, source.id),
+      };
+    }
+  }
   /**
-   * Set the target state for this transition
+   * Normalize tool - convert inline handler to ToolRef if needed
    */
-  setTarget(state: State<TContext, TExtracted>): void {
-    this.target = state;
+  private normalizeTool<TContext, TData>(
+    tool: // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ToolRef<TContext, any[], any, TData> | InlineToolHandler<TContext, TData>,
+    stepId: string
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): ToolRef<TContext, any[], any, TData> {
+    // If it's already a ToolRef (has id and name properties), return as-is
+    if (typeof tool === "object" && "id" in tool && "name" in tool) {
+      return tool;
+    }
+
+    // Otherwise, it's an inline handler function - wrap it in a ToolRef
+    const inlineHandler = tool;
+    const toolId = generateInlineToolId(stepId);
+
+    return {
+      id: toolId,
+      name: toolId,
+
+      handler: async (
+        context: ToolContext<TContext, TData>
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ): Promise<ToolResult<any, TContext, TData>> => {
+        const result = (await inlineHandler(context)) as ToolResult<
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          any,
+          TContext,
+          TData
+        >;
+        return {
+          data: result,
+        };
+      },
+      description: `Inline tool for step ${stepId}`,
+    };
   }
 
   /**
-   * Get the target state
+   * Set the target step for this transition
    */
-  getTarget(): State<TContext, TExtracted> | undefined {
-    return this.target;
+  setTarget(step: Step<TContext, TData>): void {
+    this.target = step;
   }
 
   /**
-   * Check if this transition has a condition
+   * Get the target step
    */
-  hasCondition(): boolean {
-    return !!this.condition;
+  getTarget(): Step<TContext, TData> | undefined {
+    return this.target;
   }
 
   /**
@@ -47,17 +93,17 @@ export class Transition<TContext = unknown, TExtracted = unknown> {
   describe(): string {
     const parts: string[] = [];
 
-    if (this.spec.chatState) {
-      parts.push(`chat: "${this.spec.chatState}"`);
+    if (this.spec.instructions) {
+      parts.push(`chat: "${this.spec.instructions}"`);
     }
-    if (this.spec.toolState) {
-      parts.push(`tool: ${this.spec.toolState.name}`);
+    if (this.spec.tool) {
+      parts.push(`tool: ${this.spec.tool.name}`);
     }
-    if (this.spec.state) {
-      if (typeof this.spec.state === "symbol") {
-        parts.push("state: END_STATE");
+    if (this.spec.step) {
+      if (typeof this.spec.step === "symbol") {
+        parts.push("step: END_ROUTE");
       } else {
-        parts.push(`state: ${this.spec.state.id}`);
+        parts.push(`step: ${this.spec.step.id}`);
       }
     }
 

package/src/index.ts

@@ -7,7 +7,7 @@
 // Core
 export { Agent } from "./core/Agent";
 export { Route } from "./core/Route";
-export { State } from "./core/State";
+export { Step } from "./core/Step";
 export { Transition } from "./core/Transition";
 export { defineTool } from "./core/Tool";
 export { DomainRegistry } from "./core/DomainRegistry";
@@ -51,7 +51,7 @@ export type {
 export { SQLiteAdapter } from "./adapters/SQLiteAdapter";
 export type {
   SqliteDatabase,
-  SqliteStatement,
+  SqliteStepment,
   SQLiteAdapterOptions,
 } from "./adapters/SQLiteAdapter";
 export { MemoryAdapter } from "./adapters/MemoryAdapter";
@@ -62,10 +62,10 @@ export type {
 } from "./adapters/OpenSearchAdapter";
 
 // Constants
-export { END_STATE, END_STATE_ID } from "./constants";
+export { END_ROUTE, END_ROUTE_ID } from "./constants";
 
 // Utils
-export { generateRouteId, generateStateId, generateToolId } from "./utils/id";
+export { generateRouteId, generateStepId, generateToolId } from "./utils/id";
 
 // Types
 export type {
@@ -91,7 +91,7 @@ export { EventKind, EventSource } from "./types/history";
 
 export type {
   RouteRef,
-  StateRef,
+  StepRef,
   RouteOptions,
   TransitionSpec,
   TransitionResult,
@@ -99,12 +99,12 @@ export type {
   RouteCompletionHandler,
 } from "./types/route";
 
-export type { SessionState, PendingTransition } from "./types/session";
+export type { SessionStep, PendingTransition } from "./types/session";
 export {
   createSession,
   enterRoute,
-  enterState,
-  mergeExtracted,
+  enterStep,
+  mergeCollected,
 } from "./types/session";
 
 export type {

package/src/types/agent.ts

@@ -6,7 +6,7 @@ import type { AiProvider } from "./ai";
 import type { ToolRef } from "./tool";
 import type { RouteOptions } from "./route";
 import type { PersistenceConfig } from "./persistence";
-import type { SessionState } from "./session";
+import type { SessionStep } from "./session";
 
 /**
  * Composition mode determines how the agent processes and structures responses
@@ -23,7 +23,7 @@ export enum CompositionMode {
 }
 
 /**
- * Context lifecycle hooks for managing state persistence
+ * Context lifecycle hooks for managing step persistence
  */
 export interface ContextLifecycleHooks<TContext = unknown> {
   /**
@@ -42,17 +42,17 @@ export interface ContextLifecycleHooks<TContext = unknown> {
   ) => Promise<void> | void;
 
   /**
-   * Called after extracted data is updated (from AI response or tool execution)
-   * Useful for validation, enrichment, or persistence of gathered data
-   * Return modified extracted data or the same data to keep it unchanged
+   * Called after collected data is updated (from AI response or tool execution)
+   * Useful for validation, enrichment, or persistence of collected data
+   * Return modified collected data or the same data to keep it unchanged
    *
-   * Note: This hook works with ANY route's extracted data (since an agent can have
+   * Note: This hook works with ANY route's collected data (since an agent can have
    * multiple routes with different extraction schemas). Use type guards or runtime
    * checks if you need type-specific logic.
    */
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  onExtractedUpdate?: (extracted: any, previousExtracted: any) => any;
+  onDataUpdate?: (data: any, previousCollected: any) => any;
 }
 
 /**
@@ -80,7 +80,7 @@ export interface AgentOptions<TContext = unknown> {
   /** Default context data available to the agent */
   context?: TContext;
   /** Optional current session for convenience methods */
-  session?: SessionState;
+  session?: SessionStep;
   /** Context provider function for always-fresh context (alternative to static context) */
   contextProvider?: ContextProvider<TContext>;
   /** Lifecycle hooks for context management */

package/src/types/ai.ts

@@ -64,8 +64,8 @@ export interface AgentStructuredResponse {
   message: string;
   /** Route chosen by the agent (route title or null if no route) */
   route?: string | null;
-  /** Current state within the route (state description or null) */
-  state?: string | null;
+  /** Current step within the route (step description or null) */
+  step?: string | null;
   /** Tool calls the agent wants to execute */
   toolCalls?: Array<{
     /** Name of the tool to call */

package/src/types/history.ts

@@ -58,9 +58,9 @@ export interface MessageEventData {
   session?: {
     routeId?: string;
     routeTitle?: string;
-    stateId?: string;
-    stateDescription?: string;
-    extracted?: Record<string, unknown>;
+    stepId?: string;
+    stepDescription?: string;
+    data?: Record<string, unknown>;
   };
 }
 

package/src/types/index.ts

@@ -28,7 +28,7 @@ export { EventKind, EventSource } from "./history";
 // Route types
 export type {
   RouteRef,
-  StateRef,
+  StepRef,
   RouteOptions,
   TransitionSpec,
   TransitionResult,

package/src/types/persistence.ts

@@ -24,7 +24,7 @@ export interface SessionData {
   agentName?: string;
   status: SessionStatus;
   currentRoute?: string;
-  currentState?: string;
+  currentStep?: string;
   collectedData?: Record<string, unknown>;
   messageCount?: number;
   lastMessageAt?: Date;
@@ -43,7 +43,7 @@ export interface MessageData {
   role: MessageRole;
   content: string;
   route?: string;
-  state?: string;
+  step?: string;
   toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
   event?: Event; // Optional: store full event data
   createdAt: Date;
@@ -102,12 +102,12 @@ export interface SessionRepository {
   ): Promise<SessionData | null>;
 
   /**
-   * Update current route and state
+   * Update current route and step
    */
-  updateRouteState(
+  updateRouteStep(
     id: string,
     route?: string,
-    state?: string
+    step?: string
   ): Promise<SessionData | null>;
 
   /**
@@ -228,7 +228,7 @@ export interface SaveMessageOptions {
   role: MessageRole;
   content: string;
   route?: string;
-  state?: string;
+  step?: string;
   toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
   event?: Event;
 }