@falai/agent 0.6.8 → 0.7.0

package/src/types/route.ts

@@ -2,7 +2,7 @@
  * Route/Journey DSL type definitions
  */
 
-import type { ToolRef } from "./tool";
+import type { ToolRef, ToolResult } from "./tool";
 import type { StructuredSchema } from "./schema";
 
 /**
@@ -14,12 +14,12 @@ export interface RouteRef {
 }
 
 /**
- * Reference to a state within a route
+ * Reference to a step within a route
  */
-export interface StateRef {
-  /** State identifier */
+export interface StepRef {
+  /** Step identifier */
   id: string;
-  /** Route this state belongs to */
+  /** Route this step belongs to */
   routeId: string;
 }
 
@@ -33,27 +33,31 @@ import type { Guideline } from "./agent";
  */
 export interface RouteTransitionConfig {
   /** Target route ID or title to transition to */
-  transitionTo: string;
+  nextStep: string;
   /** Optional AI-evaluated condition for the transition */
   condition?: string;
 }
 
 /**
  * Function type for dynamic route completion transitions
- * @param session - Current session state with extracted data
+ * @param session - Current session step with collected data
  * @param context - Agent context
  * @returns Route ID/title to transition to, or transition config, or undefined to end
  */
-export type RouteCompletionHandler<TContext = unknown, TExtracted = unknown> = (
-  session: { extracted?: Partial<TExtracted> },
+export type RouteCompletionHandler<TContext = unknown, TData = unknown> = (
+  session: { data?: Partial<TData> },
   context?: TContext
-) => string | RouteTransitionConfig | undefined | Promise<string | RouteTransitionConfig | undefined>;
+) =>
+  | string
+  | RouteTransitionConfig
+  | undefined
+  | Promise<string | RouteTransitionConfig | undefined>;
 
 /**
  * Options for creating a route
- * @template TExtracted - Type of data extracted throughout the route (inferred from extractionSchema)
+ * @template TData - Type of data collected throughout the route (inferred from schema)
  */
-export interface RouteOptions<TExtracted = unknown> {
+export interface RouteOptions<TContext = unknown, TData = unknown> {
   /** Custom ID for the route (optional - will generate deterministic ID from title if not provided) */
   id?: string;
   /** Title of the route */
@@ -78,40 +82,40 @@ export interface RouteOptions<TExtracted = unknown> {
    * NEW: Schema defining data to extract throughout this route
    * This creates a type-safe contract for what data the route collects
    */
-  extractionSchema?: StructuredSchema;
+  schema?: StructuredSchema;
   /**
    * NEW: Initial data to pre-populate when entering this route
    * Useful for restoring sessions or pre-filling known information
-   * States with skipIf conditions will be automatically bypassed if data is present
+   * Steps with skipIf conditions will be automatically bypassed if data is present
    */
-  initialData?: Partial<TExtracted>;
+  initialData?: Partial<TData>;
   /**
    * NEW: Sequential steps for simple linear flows
-   * If provided, automatically chains the steps from initialState to END_STATE
-   * For complex flows with branching, build the state machine manually instead
+   * If provided, automatically chains the steps from initialStep to END_ROUTE
+   * For complex flows with branching, build the step machine manually instead
    */
-  steps?: TransitionSpec<unknown, TExtracted>[];
+  steps?: TransitionSpec<TContext, TData>[];
   /**
-   * Configure the initial state (optional)
-   * Accepts full TransitionSpec configuration (id, chatState, gather, skipIf, etc.)
-   * Note: toolState and state properties are ignored for initial state
+   * Configure the initial step (optional)
+   * Accepts full TransitionSpec configuration (id, instructions, collect, skipIf, etc.)
+   * Note: tool and step properties are ignored for initial step
    */
-  initialState?: Omit<
-    TransitionSpec<unknown, TExtracted>,
-    "toolState" | "state" | "condition"
+  initialStep?: Omit<
+    TransitionSpec<TContext, TData>,
+    "tool" | "step" | "condition"
   >;
   /**
-   * Configure the end state (optional)
-   * Defines what happens when the route completes (reaches END_STATE)
-   * Can include chatState for completion message, toolState for final actions, etc.
-   * Note: state, condition, skipIf properties are ignored for end state
+   * Configure the end step (optional)
+   * Defines what happens when the route completes (reaches END_ROUTE)
+   * Can include instructions for completion message, tool for final actions, etc.
+   * Note: step, condition, skipIf properties are ignored for end step
    */
-  endState?: Omit<
-    TransitionSpec<unknown, TExtracted>,
-    "state" | "condition" | "skipIf"
+  endStep?: Omit<
+    TransitionSpec<TContext, TData>,
+    "step" | "condition" | "skipIf"
   >;
   /**
-   * Optional transition when route completes (reaches END_STATE)
+   * Optional transition when route completes (reaches END_ROUTE)
    * Can be:
    * - String: Route ID or title to transition to
    * - Object: Transition config with optional AI-evaluated condition
@@ -124,51 +128,63 @@ export interface RouteOptions<TExtracted = unknown> {
    * @example
    * // With condition
    * onComplete: {
-   *   transitionTo: "feedback-collection",
+   *   nextStep: "feedback-collection",
    *   condition: "if booking succeeded"
    * }
    *
    * @example
    * // Dynamic function
    * onComplete: (session) => {
-   *   if (session.extracted?.success) return "feedback";
+   *   if (session.data?.success) return "feedback";
    *   return "error-recovery";
    * }
    */
-  onComplete?: string | RouteTransitionConfig | RouteCompletionHandler<unknown, TExtracted>;
+  onComplete?:
+    | string
+    | RouteTransitionConfig
+    | RouteCompletionHandler<TContext, TData>;
 }
 
 /**
- * Specification for a state transition
+ * Inline tool handler for dynamic tool generation
  */
-export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
-  /** Custom ID for this state (optional - will generate deterministic ID if not provided) */
+export type InlineToolHandler<TContext = unknown, TData = unknown> = (
+  context: import("./tool").ToolContext<TContext, TData>
+) =>
+  | ToolResult<unknown, TContext, TData>
+  | Promise<ToolResult<unknown, TContext, TData>>;
+
+/**
+ * Specification for a step transition
+ */
+export interface TransitionSpec<TContext = unknown, TData = unknown> {
+  /** Custom ID for this step (optional - will generate deterministic ID if not provided) */
   id?: string;
   /** Transition to a chat state with this description */
-  chatState?: string;
+  instructions?: string;
   /** Transition to execute a tool */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  toolState?: ToolRef<TContext, any[], any>;
-  /** Transition to a specific state or end marker */
-  state?: StateRef | symbol;
+  tool?: // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ToolRef<TContext, any[], any, TData> | InlineToolHandler<TContext, TData>;
+  /** Transition to a specific step or end marker */
+  step?: StepRef | symbol;
   /**
-   * NEW: Fields to gather from the conversation in this state
-   * These should match keys in the route's extractionSchema
+   * NEW: Fields to collect from the conversation in this step
+   * These should match keys in the route's schema
    */
-  gather?: string[];
+  collect?: string[];
   /**
-   * NEW: Function to determine if this state should be skipped
-   * If returns true, the state will be bypassed
-   * @param extracted - Currently extracted data
-   * @returns true if state should be skipped, false otherwise
+   * NEW: Function to determine if this step should be skipped
+   * If returns true, the step will be bypassed
+   * @param data - Currently collected data
+   * @returns true if step should be skipped, false otherwise
    */
-  skipIf?: (extracted: Partial<TExtracted>) => boolean;
+  skipIf?: (data: Partial<TData>) => boolean;
   /**
-   * NEW: Required data fields that must be present before entering this state
-   * If any required field is missing, state cannot be entered
-   * Uses string[] for developer-friendly usage (same as gather)
+   * NEW: Required data fields that must be present before entering this step
+   * If any required field is missing, step cannot be entered
+   * Uses string[] for developer-friendly usage (same as collect)
    */
-  requiredData?: string[];
+  requires?: string[];
   /**
    * Optional condition for this transition
    * Description of when this transition should be taken
@@ -178,12 +194,12 @@ export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
 
 /**
  * Result of a transition operation
- * Combines state reference with the ability to chain transitions
+ * Combines step reference with the ability to chain transitions
  */
-export interface TransitionResult<TContext = unknown, TExtracted = unknown>
-  extends StateRef {
+export interface TransitionResult<TContext = unknown, TData = unknown>
+  extends StepRef {
   /** Allow chaining transitions */
-  transitionTo: (
-    spec: TransitionSpec<TContext, TExtracted>
-  ) => TransitionResult<TContext, TExtracted>;
+  nextStep: (
+    spec: TransitionSpec<TContext, TData>
+  ) => TransitionResult<TContext, TData>;
 }

package/src/types/session.ts

@@ -1,5 +1,5 @@
 /**
- * Session state types for tracking conversation progress
+ * Session step types for tracking conversation progress
  */
 
 /**
@@ -15,10 +15,10 @@ export interface PendingTransition {
 }
 
 /**
- * Session state tracks the current position in the conversation flow
- * and data extracted during the route progression
+ * Session step tracks the current position in the conversation flow
+ * and data collected during the route progression
  */
-export interface SessionState<TExtracted = Record<string, unknown>> {
+export interface SessionStep<TData = Record<string, unknown>> {
   /** Unique session identifier (useful for persistence) */
   id?: string;
 
@@ -29,25 +29,25 @@ export interface SessionState<TExtracted = Record<string, unknown>> {
     enteredAt: Date;
   };
 
-  /** Current state within the route */
-  currentState?: {
+  /** Current step within the route */
+  currentStep?: {
     id: string;
     description?: string;
     enteredAt: Date;
   };
 
   /**
-   * Data extracted during the current route
-   * This is a convenience reference to extractedByRoute[currentRoute.id]
+   * Data collected during the current route
+   * This is a convenience reference to dataByRoute[currentRoute.id]
    */
-  extracted?: Partial<TExtracted>;
+  data?: Partial<TData>;
 
   /**
-   * Extracted data organized by route ID
+   * Collected data organized by route ID
    * Preserves data when switching between routes
-   * Format: { "routeId": { ...extractedData } }
+   * Format: { "routeId": { ...dataData } }
    */
-  extractedByRoute?: Record<string, Partial<unknown>>;
+  dataByRoute?: Record<string, Partial<unknown>>;
 
   /** History of routes visited in this session */
   routeHistory: Array<{
@@ -76,14 +76,14 @@ export interface SessionState<TExtracted = Record<string, unknown>> {
  * @param sessionId - Optional session ID (e.g., from database)
  * @param metadata - Optional metadata to attach
  */
-export function createSession<TExtracted = Record<string, unknown>>(
+export function createSession<TData = Record<string, unknown>>(
   sessionId?: string,
-  metadata?: SessionState<TExtracted>["metadata"]
-): SessionState<TExtracted> {
+  metadata?: SessionStep<TData>["metadata"]
+): SessionStep<TData> {
   return {
     id: sessionId,
-    extracted: {},
-    extractedByRoute: {},
+    data: {},
+    dataByRoute: {},
     routeHistory: [],
     metadata: {
       ...metadata,
@@ -95,21 +95,21 @@ export function createSession<TExtracted = Record<string, unknown>>(
 
 /**
  * Helper to update session with new route
- * Preserves extracted data per route in extractedByRoute map
+ * Preserves collected data per route in dataByRoute map
  */
-export function enterRoute<TExtracted = Record<string, unknown>>(
-  session: SessionState<TExtracted>,
+export function enterRoute<TData = Record<string, unknown>>(
+  session: SessionStep<TData>,
   routeId: string,
   routeTitle: string
-): SessionState<TExtracted> {
-  // Save current route's extracted data before switching
-  const extractedByRoute = { ...session.extractedByRoute };
+): SessionStep<TData> {
+  // Save current route's collected data before switching
+  const dataByRoute = { ...session.dataByRoute };
   if (
     session.currentRoute &&
-    session.extracted &&
-    Object.keys(session.extracted).length > 0
+    session.data &&
+    Object.keys(session.data).length > 0
   ) {
-    extractedByRoute[session.currentRoute.id] = session.extracted;
+    dataByRoute[session.currentRoute.id] = session.data;
   }
 
   // Exit current route if exists
@@ -123,8 +123,8 @@ export function enterRoute<TExtracted = Record<string, unknown>>(
     }
   }
 
-  // Load extracted data for new route (if resuming) or start fresh
-  const newExtracted = (extractedByRoute[routeId] as Partial<TExtracted>) || {};
+  // Load collected data for new route (if resuming) or start fresh
+  const newCollected = (dataByRoute[routeId] as Partial<TData>) || {};
 
   // Enter new route
   const now = new Date();
@@ -135,9 +135,9 @@ export function enterRoute<TExtracted = Record<string, unknown>>(
       title: routeTitle,
       enteredAt: now,
     },
-    currentState: undefined,
-    extracted: newExtracted, // Load route's data or start fresh
-    extractedByRoute,
+    currentStep: undefined,
+    data: newCollected, // Load route's data or start fresh
+    dataByRoute,
     routeHistory: [
       ...routeHistory,
       {
@@ -154,18 +154,18 @@ export function enterRoute<TExtracted = Record<string, unknown>>(
 }
 
 /**
- * Helper to update session with new state
+ * Helper to update session with new step
  */
-export function enterState<TExtracted = Record<string, unknown>>(
-  session: SessionState<TExtracted>,
-  stateId: string,
-  stateDescription?: string
-): SessionState<TExtracted> {
+export function enterStep<TData = Record<string, unknown>>(
+  session: SessionStep<TData>,
+  stepId: string,
+  stepDescription?: string
+): SessionStep<TData> {
   return {
     ...session,
-    currentState: {
-      id: stateId,
-      description: stateDescription,
+    currentStep: {
+      id: stepId,
+      description: stepDescription,
       enteredAt: new Date(),
     },
     metadata: {
@@ -176,28 +176,28 @@ export function enterState<TExtracted = Record<string, unknown>>(
 }
 
 /**
- * Helper to merge extracted data into session
- * Updates both the extracted field and the extractedByRoute map
+ * Helper to merge collected data into session
+ * Updates both the data field and the dataByRoute map
  */
-export function mergeExtracted<TExtracted = Record<string, unknown>>(
-  session: SessionState<TExtracted>,
-  extracted: Partial<unknown>
-): SessionState<TExtracted> {
-  const newExtracted = {
-    ...session.extracted,
-    ...extracted,
-  } as Partial<TExtracted>;
+export function mergeCollected<TData = Record<string, unknown>>(
+  session: SessionStep<TData>,
+  data: Partial<unknown>
+): SessionStep<TData> {
+  const newCollected = {
+    ...session.data,
+    ...data,
+  } as Partial<TData>;
 
-  // Also update the extractedByRoute map for the current route
-  const extractedByRoute = { ...session.extractedByRoute };
+  // Also update the dataByRoute map for the current route
+  const dataByRoute = { ...session.dataByRoute };
   if (session.currentRoute) {
-    extractedByRoute[session.currentRoute.id] = newExtracted;
+    dataByRoute[session.currentRoute.id] = newCollected;
   }
 
   return {
     ...session,
-    extracted: newExtracted,
-    extractedByRoute,
+    data: newCollected,
+    dataByRoute,
     metadata: {
       ...session.metadata,
       lastUpdatedAt: new Date(),
@@ -206,44 +206,44 @@ export function mergeExtracted<TExtracted = Record<string, unknown>>(
 }
 
 /**
- * Helper to convert SessionState to persistence-friendly format
+ * Helper to convert SessionStep to persistence-friendly format
  * Used when saving to database
  */
-export function sessionStateToData<TExtracted = Record<string, unknown>>(
-  session: SessionState<TExtracted>
+export function sessionStepToData<TData = Record<string, unknown>>(
+  session: SessionStep<TData>
 ): {
   currentRoute?: string;
-  currentState?: string;
+  currentStep?: string;
   collectedData: Record<string, unknown>;
 } {
   return {
     currentRoute: session.currentRoute?.id,
-    currentState: session.currentState?.id,
+    currentStep: session.currentStep?.id,
     collectedData: {
-      extracted: session.extracted,
-      extractedByRoute: session.extractedByRoute, // Include per-route data
+      data: session.data,
+      dataByRoute: session.dataByRoute, // Include per-route data
       routeHistory: session.routeHistory,
       currentRouteTitle: session.currentRoute?.title,
-      currentStateDescription: session.currentState?.description,
+      currentStepDescription: session.currentStep?.description,
       metadata: session.metadata,
     },
   };
 }
 
 /**
- * Helper to convert database SessionData back to SessionState
+ * Helper to convert database SessionData back to SessionStep
  * Used when loading from database
  * @param sessionId - The database session ID
  * @param data - The database session data
  */
-export function sessionDataToState<TExtracted = Record<string, unknown>>(
+export function sessionDataToStep<TData = Record<string, unknown>>(
   sessionId: string,
   data: {
     currentRoute?: string;
-    currentState?: string;
+    currentStep?: string;
     collectedData?: Record<string, unknown>;
   }
-): SessionState<TExtracted> {
+): SessionStep<TData> {
   const collectedData = data.collectedData || {};
 
   return {
@@ -256,22 +256,19 @@ export function sessionDataToState<TExtracted = Record<string, unknown>>(
           enteredAt: new Date(),
         }
       : undefined,
-    currentState: data.currentState
+    currentStep: data.currentStep
       ? {
-          id: data.currentState,
+          id: data.currentStep,
           description:
-            (collectedData.currentStateDescription as string) || undefined,
+            (collectedData.currentStepDescription as string) || undefined,
           enteredAt: new Date(),
         }
       : undefined,
-    extracted: (collectedData.extracted as Partial<TExtracted>) || {},
-    extractedByRoute:
-      (collectedData.extractedByRoute as Record<string, Partial<unknown>>) ||
-      {}, // Restore per-route data
+    data: (collectedData.data as Partial<TData>) || {},
+    dataByRoute:
+      (collectedData.dataByRoute as Record<string, Partial<unknown>>) || {}, // Restore per-route data
     routeHistory:
-      (collectedData.routeHistory as SessionState<TExtracted>["routeHistory"]) ||
-      [],
-    metadata:
-      (collectedData.metadata as SessionState<TExtracted>["metadata"]) || {},
+      (collectedData.routeHistory as SessionStep<TData>["routeHistory"]) || [],
+    metadata: (collectedData.metadata as SessionStep<TData>["metadata"]) || {},
   };
 }

package/src/types/tool.ts

@@ -2,22 +2,22 @@
  * Tool system type definitions
  */
 
-import type { Event, StateRef } from "./index";
+import type { Event, StepRef } from "./index";
 
 /**
  * Context provided to tool handlers
  */
-export interface ToolContext<TContext = unknown, TExtracted = unknown> {
+export interface ToolContext<TContext = unknown, TData = unknown> {
   /** The agent's context data */
   context: TContext;
   /** Update the agent's context (triggers lifecycle hooks if configured) */
   updateContext: (updates: Partial<TContext>) => Promise<void>;
-  /** Current state reference (if in a route) */
-  state?: StateRef;
+  /** Current step reference (if in a route) */
+  step?: StepRef;
   /** Interaction history */
   history: Event[];
-  /** Data extracted so far in the current route */
-  extracted?: Partial<TExtracted>;
+  /** Data collected so far in the current route */
+  data?: Partial<TData>;
   /** Additional metadata */
   metadata?: Record<string, unknown>;
 }
@@ -26,16 +26,16 @@ export interface ToolContext<TContext = unknown, TExtracted = unknown> {
  * Result returned by a tool
  */
 export interface ToolResult<
-  TData = unknown,
+  TResultData = unknown,
   TContext = unknown,
-  TExtracted = unknown
+  TData = unknown
 > {
   /** The result data */
-  data: TData;
+  data: TResultData;
   /** Optional context update to be merged with current context */
   contextUpdate?: Partial<TContext>;
-  /** Optional extracted data update to be merged with session state */
-  extractedUpdate?: Partial<TExtracted>;
+  /** Optional collected data update to be merged with session step */
+  collectedUpdate?: Partial<TData>;
   /** Optional metadata about the execution */
   meta?: Record<string, unknown>;
 }
@@ -47,13 +47,13 @@ export type ToolHandler<
   TContext,
   TArgs extends unknown[],
   TResult,
-  TExtracted = unknown
+  TData = unknown
 > = (
-  context: ToolContext<TContext, TExtracted>,
+  context: ToolContext<TContext, TData>,
   ...args: TArgs
 ) =>
-  | Promise<ToolResult<TResult, TContext, TExtracted>>
-  | ToolResult<TResult, TContext, TExtracted>;
+  | Promise<ToolResult<TResult, TContext, TData>>
+  | ToolResult<TResult, TContext, TData>;
 
 /**
  * Reference to a defined tool
@@ -62,14 +62,14 @@ export interface ToolRef<
   TContext,
   TArgs extends unknown[],
   TResult,
-  TExtracted = unknown
+  TData = unknown
 > {
   /** Tool identifier */
   id: string;
   /** Tool name */
   name: string;
   /** Tool handler function */
-  handler: ToolHandler<TContext, TArgs, TResult, TExtracted>;
+  handler: ToolHandler<TContext, TArgs, TResult, TData>;
   /** Description of what the tool does */
   description?: string;
   /** Parameter schema or description */

package/src/utils/id.ts

@@ -35,10 +35,10 @@ export function generateRouteId(title: string): string {
 }
 
 /**
- * Generate a deterministic state ID
- * Format: state_{sanitized_description}_{hash} or state_{routeId}_{index}
+ * Generate a deterministic step ID
+ * Format: step_{sanitized_description}_{hash} or step_{routeId}_{index}
  */
-export function generateStateId(
+export function generateStepId(
   routeId: string,
   description?: string,
   index?: number
@@ -46,11 +46,11 @@ export function generateStateId(
   if (description) {
     const sanitized = sanitize(description);
     const hash = simpleHash(`${routeId}_${description}`);
-    return `state_${sanitized}_${hash}`;
+    return `step_${sanitized}_${hash}`;
   }
-  // Fallback for states without descriptions
+  // Fallback for steps without descriptions
   const suffix = index !== undefined ? index : simpleHash(routeId);
-  return `state_${routeId}_${suffix}`;
+  return `step_${routeId}_${suffix}`;
 }
 
 /**
@@ -62,3 +62,12 @@ export function generateToolId(name: string): string {
   const hash = simpleHash(name);
   return `tool_${sanitized}_${hash}`;
 }
+
+/**
+ * Generate a deterministic tool ID for inline tool handlers
+ * Format: tool_inline_{stepId}_{hash}
+ */
+export function generateInlineToolId(stepId: string): string {
+  const hash = simpleHash(`${stepId}_inline_tool`);
+  return `tool_inline_${stepId}_${hash}`;
+}