@falai/agent 0.6.8 → 0.7.0

package/src/core/Events.ts

@@ -76,9 +76,9 @@ export function createMessageEvent(
     session?: {
       routeId?: string;
       routeTitle?: string;
-      stateId?: string;
-      stateDescription?: string;
-      extracted?: Record<string, unknown>;
+      stepId?: string;
+      stepDescription?: string;
+      data?: Record<string, unknown>;
     };
   }
 ): Event<MessageEventData>;
@@ -90,9 +90,9 @@ export function createMessageEvent(options: {
   session?: {
     routeId?: string;
     routeTitle?: string;
-    stateId?: string;
-    stateDescription?: string;
-    extracted?: Record<string, unknown>;
+    stepId?: string;
+    stepDescription?: string;
+    data?: Record<string, unknown>;
   };
 }): Event<MessageEventData>;
 export function createMessageEvent(
@@ -106,9 +106,9 @@ export function createMessageEvent(
         session?: {
           routeId?: string;
           routeTitle?: string;
-          stateId?: string;
-          stateDescription?: string;
-          extracted?: Record<string, unknown>;
+          stepId?: string;
+          stepDescription?: string;
+          data?: Record<string, unknown>;
         };
       },
   participantName?: string,
@@ -118,9 +118,9 @@ export function createMessageEvent(
     session?: {
       routeId?: string;
       routeTitle?: string;
-      stateId?: string;
-      stateDescription?: string;
-      extracted?: Record<string, unknown>;
+      stepId?: string;
+      stepDescription?: string;
+      data?: Record<string, unknown>;
     };
   }
 ): Event<MessageEventData> {

package/src/core/PersistenceManager.ts

@@ -14,11 +14,11 @@ import type {
   MessageRepository,
 } from "../types/persistence";
 import type { Event } from "../types/history";
-import type { SessionState } from "../types/session";
+import type { SessionStep } from "../types/session";
 import {
   createSession,
-  sessionStateToData,
-  sessionDataToState,
+  sessionStepToData,
+  sessionDataToStep,
 } from "../types/session";
 
 /**
@@ -119,18 +119,14 @@ export class PersistenceManager {
   }
 
   /**
-   * Update current route and state
+   * Update current route and step
    */
-  async updateRouteState(
+  async updateRouteStep(
     sessionId: string,
     route?: string,
-    state?: string
+    step?: string
   ): Promise<SessionData | null> {
-    return await this.sessionRepository.updateRouteState(
-      sessionId,
-      route,
-      state
-    );
+    return await this.sessionRepository.updateRouteStep(sessionId, route, step);
   }
 
   /**
@@ -145,7 +141,7 @@ export class PersistenceManager {
       role: options.role,
       content: options.content,
       route: options.route,
-      state: options.state,
+      step: options.step,
       toolCalls: options.toolCalls,
       event: options.event,
     });
@@ -227,77 +223,77 @@ export class PersistenceManager {
   }
 
   /**
-   * Save SessionState to database
-   * Converts SessionState to SessionData and persists it
+   * Save SessionStep to database
+   * Converts SessionStep to SessionData and persists it
    */
-  async saveSessionState<TExtracted = Record<string, unknown>>(
+  async saveSessionStep<TData = Record<string, unknown>>(
     sessionId: string,
-    sessionState: SessionState<TExtracted>
+    sessionStep: SessionStep<TData>
   ): Promise<SessionData | null> {
-    const persistenceData = sessionStateToData(sessionState);
+    const persistenceData = sessionStepToData(sessionStep);
 
     return await this.sessionRepository.update(sessionId, {
       currentRoute: persistenceData.currentRoute,
-      currentState: persistenceData.currentState,
+      currentStep: persistenceData.currentStep,
       collectedData: persistenceData.collectedData,
       lastMessageAt: new Date(),
     });
   }
 
   /**
-   * Load SessionState from database
-   * Converts SessionData to SessionState
+   * Load SessionStep from database
+   * Converts SessionData to SessionStep
    */
-  async loadSessionState<TExtracted = Record<string, unknown>>(
+  async loadSessionStep<TData = Record<string, unknown>>(
     sessionId: string
-  ): Promise<SessionState<TExtracted> | null> {
+  ): Promise<SessionStep<TData> | null> {
     const sessionData = await this.sessionRepository.findById(sessionId);
 
     if (!sessionData) {
       return null;
     }
 
-    const stateData = sessionDataToState<TExtracted>(sessionId, {
+    const stepData = sessionDataToStep<TData>(sessionId, {
       currentRoute: sessionData.currentRoute,
-      currentState: sessionData.currentState,
+      currentStep: sessionData.currentStep,
       collectedData: sessionData.collectedData,
     });
 
-    // Create a full session state with the loaded data
-    const session = createSession<TExtracted>(sessionId, {
+    // Create a full session step with the loaded data
+    const session = createSession<TData>(sessionId, {
       createdAt: sessionData.createdAt,
       lastUpdatedAt: sessionData.updatedAt,
     });
 
     return {
       ...session,
-      ...stateData,
+      ...stepData,
     };
   }
 
   /**
-   * Create session with SessionState support
-   * Returns both SessionData and initialized SessionState
+   * Create session with SessionStep support
+   * Returns both SessionData and initialized SessionStep
    */
-  async createSessionWithState<TExtracted = Record<string, unknown>>(
+  async createSessionWithStep<TData = Record<string, unknown>>(
     options: CreateSessionOptions
   ): Promise<{
     sessionData: SessionData;
-    sessionState: SessionState<TExtracted>;
+    sessionStep: SessionStep<TData>;
   }> {
     const sessionData = await this.createSession(options);
 
-    // Create SessionState with database session ID
-    const sessionState = createSession<TExtracted>(sessionData.id, {
+    // Create SessionStep with database session ID
+    const sessionStep = createSession<TData>(sessionData.id, {
       createdAt: sessionData.createdAt,
       lastUpdatedAt: sessionData.updatedAt,
     });
 
-    // If initial data was provided, merge it as extracted data
+    // If initial data was provided, merge it as collected data
     if (options.initialData) {
-      sessionState.extracted = options.initialData as Partial<TExtracted>;
+      sessionStep.data = options.initialData as Partial<TData>;
     }
 
-    return { sessionData, sessionState };
+    return { sessionData, sessionStep };
   }
 }

package/src/core/ResponseEngine.ts

@@ -1,19 +1,13 @@
 import type { Event } from "../types/history";
 import type { Route } from "./Route";
-import type { State } from "./State";
+import type { Step } from "./Step";
 import type { StructuredSchema } from "../types/schema";
 import { PromptComposer } from "./PromptComposer";
 
-export interface ResponseOutput<TData = unknown> {
-  message: string;
-  data?: TData;
-  contextUpdate?: Record<string, unknown>;
-}
-
 export class ResponseEngine<TContext = unknown> {
-  responseSchemaForRoute<TExtracted = unknown>(
-    route: Route<TContext, TExtracted>,
-    currentState?: State<TContext, TExtracted>
+  responseSchemaForRoute<TData = unknown>(
+    route: Route<TContext, TData>,
+    currentStep?: Step<TContext, TData>
   ): StructuredSchema {
     const base: StructuredSchema = {
       type: "object",
@@ -29,10 +23,10 @@ export class ResponseEngine<TContext = unknown> {
       base.properties!.data = route.responseOutputSchema;
     }
 
-    // Add gather fields from current state
-    if (currentState?.gatherFields && route.extractionSchema?.properties) {
-      for (const field of currentState.gatherFields) {
-        const fieldSchema = route.extractionSchema.properties[field];
+    // Add collect fields from current step
+    if (currentStep?.collectFields && route.schema?.properties) {
+      for (const field of currentStep.collectFields) {
+        const fieldSchema = route.schema.properties[field];
         if (fieldSchema) {
           base.properties![field] = fieldSchema;
         }
@@ -44,7 +38,7 @@ export class ResponseEngine<TContext = unknown> {
 
   buildResponsePrompt(
     route: Route<TContext>,
-    currentState: State<TContext>,
+    currentStep: Step<TContext>,
     rules: string[],
     prohibitions: string[],
     directives: string[] | undefined,
@@ -72,9 +66,9 @@ export class ResponseEngine<TContext = unknown> {
         route.description ? ` — ${route.description}` : ""
       }`
     );
-    if (currentState.chatState) {
+    if (currentStep.instructions) {
       pc.addInstruction(
-        `Guideline for your response (adapt to the conversation):\n${currentState.chatState}`
+        `Guideline for your response (adapt to the conversation):\n${currentStep.instructions}`
       );
     }
     if (rules.length) pc.addInstruction(`Rules:\n- ${rules.join("\n- ")}`);

package/src/core/Route.ts

@@ -13,13 +13,13 @@ import type {
 import type { StructuredSchema } from "../types/schema";
 import type { Guideline } from "../types/agent";
 
-import { State } from "./State";
+import { Step } from "./Step";
 import { generateRouteId } from "../utils/id";
 
 /**
  * Represents a conversational route/journey
  */
-export class Route<TContext = unknown, TExtracted = unknown> {
+export class Route<TContext = unknown, TData = unknown> {
   public readonly id: string;
   public readonly title: string;
   public readonly description?: string;
@@ -27,16 +27,22 @@ export class Route<TContext = unknown, TExtracted = unknown> {
   public readonly domains?: string[];
   public readonly rules: string[];
   public readonly prohibitions: string[];
-  public readonly initialState: State<TContext, TExtracted>;
-  public readonly endStateSpec: Omit<TransitionSpec<TContext, TExtracted>, "state" | "condition" | "skipIf">;
+  public readonly initialStep: Step<TContext, TData>;
+  public readonly endStepSpec: Omit<
+    TransitionSpec<TContext, TData>,
+    "step" | "condition" | "skipIf"
+  >;
   public readonly responseOutputSchema?: StructuredSchema;
-  public readonly extractionSchema?: StructuredSchema;
-  public readonly initialData?: Partial<TExtracted>;
-  public readonly onComplete?: string | RouteTransitionConfig | RouteCompletionHandler<TContext, TExtracted>;
+  public readonly schema?: StructuredSchema;
+  public readonly initialData?: Partial<TData>;
+  public readonly onComplete?:
+    | string
+    | RouteTransitionConfig
+    | RouteCompletionHandler<TContext, TData>;
   private routingExtrasSchema?: StructuredSchema;
   private guidelines: Guideline[] = [];
 
-  constructor(options: RouteOptions<TExtracted>) {
+  constructor(options: RouteOptions<TContext, TData>) {
     // Use provided ID or generate a deterministic one from the title
     this.id = options.id || generateRouteId(options.title);
     this.title = options.title;
@@ -45,22 +51,23 @@ export class Route<TContext = unknown, TExtracted = unknown> {
     this.domains = options.domains;
     this.rules = options.rules || ([] as string[]);
     this.prohibitions = options.prohibitions || ([] as string[]);
-    this.initialState = new State<TContext, TExtracted>(
+    this.initialStep = new Step<TContext, TData>(
       this.id,
-      options.initialState?.chatState || "Initial state",
-      options.initialState?.id,
-      options.initialState?.gather,
-      options.initialState?.skipIf,
-      options.initialState?.requiredData,
-      options.initialState?.chatState
+      options.initialStep?.instructions || "Initial step",
+      options.initialStep?.id,
+      options.initialStep?.collect,
+      options.initialStep?.skipIf,
+      options.initialStep?.requires,
+      options.initialStep?.instructions
     );
-    // Store endState spec (will be used when route completes)
-    this.endStateSpec = options.endState || {
-      chatState: "Summarize what was accomplished and confirm completion based on the conversation history and collected data"
+    // Store endStep spec (will be used when route completes)
+    this.endStepSpec = options.endStep || {
+      instructions:
+        "Summarize what was accomplished and confirm completion based on the conversation history and collected data",
     };
     this.routingExtrasSchema = options.routingExtrasSchema;
     this.responseOutputSchema = options.responseOutputSchema;
-    this.extractionSchema = options.extractionSchema;
+    this.schema = options.schema;
     this.initialData = options.initialData;
     this.onComplete = options.onComplete;
 
@@ -78,24 +85,23 @@ export class Route<TContext = unknown, TExtracted = unknown> {
   }
 
   /**
-   * Build a sequential state machine from an array of steps
+   * Build a sequential step machine from an array of steps
    * @private
    */
   private buildSequentialSteps(
-    steps: Array<TransitionSpec<TContext, TExtracted>>
+    steps: Array<TransitionSpec<TContext, TData>>
   ): void {
-    // Import END_STATE dynamically to avoid circular dependency
-    const END_STATE = Symbol.for("END_STATE");
+    // Import END_ROUTE dynamically to avoid circular dependency
+    const END_ROUTE = Symbol.for("END_ROUTE");
 
-    let currentState: TransitionResult<TContext, TExtracted> =
-      this.initialState;
+    let currentStep: TransitionResult<TContext, TData> = this.initialStep;
 
     for (const step of steps) {
-      currentState = currentState.transitionTo(step);
+      currentStep = currentStep.nextStep(step);
     }
 
     // End the route
-    currentState.transitionTo({ state: END_STATE });
+    currentStep.nextStep({ step: END_ROUTE });
   }
 
   /**
@@ -163,12 +169,12 @@ export class Route<TContext = unknown, TExtracted = unknown> {
   }
 
   /**
-   * Get all states in this route (via traversal from initial state)
+   * Get all steps in this route (via traversal from initial step)
    */
-  getAllStates(): State<TContext, TExtracted>[] {
+  getAllSteps(): Step<TContext, TData>[] {
     const visited = new Set<string>();
-    const states: State<TContext, TExtracted>[] = [];
-    const queue: State<TContext, TExtracted>[] = [this.initialState];
+    const steps: Step<TContext, TData>[] = [];
+    const queue: Step<TContext, TData>[] = [this.initialStep];
 
     while (queue.length > 0) {
       const current = queue.shift()!;
@@ -178,9 +184,9 @@ export class Route<TContext = unknown, TExtracted = unknown> {
       }
 
       visited.add(current.id);
-      states.push(current);
+      steps.push(current);
 
-      // Add target states from transitions
+      // Add target steps from transitions
       for (const transition of current.getTransitions()) {
         const target = transition.getTarget();
         if (target && !visited.has(target.id)) {
@@ -189,17 +195,17 @@ export class Route<TContext = unknown, TExtracted = unknown> {
       }
     }
 
-    return states;
+    return steps;
   }
 
   /**
-   * Get a specific state by ID
-   * @param stateId - The state ID to find
-   * @returns The state if found, undefined otherwise
+   * Get a specific step by ID
+   * @param stepId - The step ID to find
+   * @returns The step if found, undefined otherwise
    */
-  getState(stateId: string): State<TContext, TExtracted> | undefined {
-    const states = this.getAllStates();
-    return states.find((state) => state.id === stateId);
+  getStep(stepId: string): Step<TContext, TData> | undefined {
+    const steps = this.getAllSteps();
+    return steps.find((step) => step.id === stepId);
   }
 
   /**
@@ -212,16 +218,16 @@ export class Route<TContext = unknown, TExtracted = unknown> {
       `Description: ${this.description || "N/A"}`,
       `Conditions: ${this.conditions.join(", ") || "None"}`,
       "",
-      "States:",
+      "Steps:",
     ];
 
-    const states = this.getAllStates();
-    for (const state of states) {
+    const steps = this.getAllSteps();
+    for (const step of steps) {
       lines.push(
-        `  - ${state.id}${state.description ? `: ${state.description}` : ""}`
+        `  - ${step.id}${step.description ? `: ${step.description}` : ""}`
       );
 
-      const transitions = state.getTransitions();
+      const transitions = step.getTransitions();
       for (const transition of transitions) {
         lines.push(`    -> ${transition.describe()}`);
       }
@@ -232,12 +238,12 @@ export class Route<TContext = unknown, TExtracted = unknown> {
 
   /**
    * Evaluate the onComplete handler and return transition config
-   * @param session - Current session state
+   * @param session - Current session step
    * @param context - Agent context
    * @returns Transition config or undefined if no transition
    */
   async evaluateOnComplete(
-    session: { extracted?: Partial<TExtracted> },
+    session: { data?: Partial<TData> },
     context?: TContext
   ): Promise<RouteTransitionConfig | undefined> {
     if (!this.onComplete) {
@@ -247,7 +253,7 @@ export class Route<TContext = unknown, TExtracted = unknown> {
     // String form: just route ID/title
     if (typeof this.onComplete === "string") {
       return {
-        transitionTo: this.onComplete,
+        nextStep: this.onComplete,
       };
     }
 
@@ -261,7 +267,7 @@ export class Route<TContext = unknown, TExtracted = unknown> {
 
       if (typeof result === "string") {
         return {
-          transitionTo: result,
+          nextStep: result,
         };
       }