@falai/agent 0.6.7 → 0.6.9

package/src/core/Agent.ts

@@ -8,7 +8,7 @@ import type { RouteOptions } from "../types/route";
 
 import type { SessionState } from "../types/session";
 import type { AgentStructuredResponse } from "../types/ai";
-import { createSession, enterState, mergeExtracted } from "../types/session";
+import { createSession, enterRoute, enterState, mergeExtracted } from "../types/session";
 import { PromptComposer } from "./PromptComposer";
 import { logger, LoggerLevel } from "../utils/logger";
 
@@ -243,11 +243,10 @@ export class Agent<TContext = unknown> {
 
     // Trigger lifecycle hook if configured
     if (this.options.hooks?.onExtractedUpdate) {
-      const updatedExtracted = (await this.options.hooks.onExtractedUpdate(
+        newExtracted = (await this.options.hooks.onExtractedUpdate(
         newExtracted,
         previousExtracted
       )) as Partial<TExtracted>;
-      newExtracted = updatedExtracted;
     }
 
     // Return updated session
@@ -363,7 +362,43 @@ export class Agent<TContext = unknown> {
     let selectedState: State<TContext> | undefined;
     let isRouteComplete = false;
 
-    if (this.routes.length > 0) {
+    // Check for pending transition from previous route completion
+    if (session.pendingTransition) {
+      const targetRoute = this.routes.find(
+        (r) => r.id === session.pendingTransition?.targetRouteId
+      );
+
+      if (targetRoute) {
+        logger.debug(
+          `[Agent] Auto-transitioning from pending transition to route: ${targetRoute.title}`
+        );
+        // Clear pending transition and enter new route
+        session = {
+          ...session,
+          pendingTransition: undefined,
+        };
+        session = enterRoute(session, targetRoute.id, targetRoute.title);
+
+        // Merge initial data if available
+        if (targetRoute.initialData) {
+          session = mergeExtracted(session, targetRoute.initialData);
+        }
+
+        selectedRoute = targetRoute;
+      } else {
+        logger.warn(
+          `[Agent] Pending transition target route not found: ${session.pendingTransition.targetRouteId}`
+        );
+        // Clear invalid transition
+        session = {
+          ...session,
+          pendingTransition: undefined,
+        };
+      }
+    }
+
+    // If no pending transition or transition handled, do normal routing
+    if (this.routes.length > 0 && !selectedRoute) {
       const orchestration = await this.routingEngine.decideRouteAndState({
         routes: this.routes,
         session,
@@ -531,19 +566,118 @@ export class Agent<TContext = unknown> {
         };
       }
     } else if (isRouteComplete && selectedRoute) {
-      // Route is complete - set state to END_STATE marker and yield completion signal
+      // Route is complete - generate completion message then check for onComplete transition
+      const lastUserMessage = getLastMessageFromHistory(history);
+
+      // Get endState spec from route
+      const endStateSpec = selectedRoute.endStateSpec;
+
+      // Create a temporary state for completion message generation using endState configuration
+      const completionState = new State<TContext>(
+        selectedRoute.id,
+        endStateSpec.chatState || "Summarize what was accomplished and confirm completion",
+        endStateSpec.id || END_STATE_ID,
+        endStateSpec.gather,
+        undefined,
+        endStateSpec.requiredData,
+        endStateSpec.chatState || "Summarize what was accomplished and confirm completion based on the conversation history and collected data"
+      );
+
+      // Build response schema for completion
+      const responseSchema = this.responseEngine.responseSchemaForRoute(
+        selectedRoute,
+        completionState
+      );
+
+      // Build completion response prompt
+      const completionPrompt = this.responseEngine.buildResponsePrompt(
+        selectedRoute,
+        completionState,
+        selectedRoute.getRules(),
+        selectedRoute.getProhibitions(),
+        undefined, // No directives for completion
+        history,
+        lastUserMessage,
+        {
+          name: this.options.name,
+          goal: this.options.goal,
+          description: this.options.description,
+          personality: this.options.personality,
+        }
+      );
+
+      // Stream completion message using AI provider
+      const stream = this.options.ai.generateMessageStream({
+        prompt: completionPrompt,
+        history,
+        context: effectiveContext,
+        signal,
+        parameters: {
+          jsonSchema: responseSchema,
+          schemaName: "completion_message_stream",
+        },
+      });
+
+      logger.debug(
+        `[Agent] Streaming completion message for route: ${selectedRoute.title}`
+      );
+
+      // Check for onComplete transition
+      const transitionConfig = await selectedRoute.evaluateOnComplete(
+        { extracted: session.extracted },
+        effectiveContext
+      );
+
+      if (transitionConfig) {
+        // Find target route by ID or title
+        const targetRoute = this.routes.find(
+          (r) =>
+            r.id === transitionConfig.transitionTo ||
+            r.title === transitionConfig.transitionTo
+        );
+
+        if (targetRoute) {
+          // Set pending transition in session
+          session = {
+            ...session,
+            pendingTransition: {
+              targetRouteId: targetRoute.id,
+              condition: transitionConfig.condition,
+              reason: "route_complete",
+            },
+          };
+          logger.debug(
+            `[Agent] Route ${selectedRoute.title} completed with pending transition to: ${targetRoute.title}`
+          );
+        } else {
+          logger.warn(
+            `[Agent] Route ${selectedRoute.title} completed but target route not found: ${transitionConfig.transitionTo}`
+          );
+        }
+      }
+
+      // Set state to END_STATE marker
       session = enterState(session, END_STATE_ID, "Route completed");
       logger.debug(
         `[Agent] Route ${selectedRoute.title} completed. Entered END_STATE state.`
       );
-      yield {
-        delta: "",
-        accumulated: "",
-        done: true,
-        session,
-        toolCalls: undefined,
-        isRouteComplete: true,
-      };
+
+      // Stream completion chunks
+      for await (const chunk of stream) {
+        // Update current session if we have one
+        if (chunk.done && this.currentSession) {
+          this.currentSession = session;
+        }
+
+        yield {
+          delta: chunk.delta,
+          accumulated: chunk.accumulated,
+          done: chunk.done,
+          session,
+          toolCalls: undefined,
+          isRouteComplete: true,
+        };
+      }
     } else {
       // Fallback: No routes defined, stream a simple response
       const fallbackPrompt = new PromptComposer<TContext>()
@@ -689,7 +823,43 @@ export class Agent<TContext = unknown> {
     let selectedState: State<TContext> | undefined;
     let isRouteComplete = false;
 
-    if (this.routes.length > 0) {
+    // Check for pending transition from previous route completion
+    if (session.pendingTransition) {
+      const targetRoute = this.routes.find(
+        (r) => r.id === session.pendingTransition?.targetRouteId
+      );
+
+      if (targetRoute) {
+        logger.debug(
+          `[Agent] Auto-transitioning from pending transition to route: ${targetRoute.title}`
+        );
+        // Clear pending transition and enter new route
+        session = {
+          ...session,
+          pendingTransition: undefined,
+        };
+        session = enterRoute(session, targetRoute.id, targetRoute.title);
+
+        // Merge initial data if available
+        if (targetRoute.initialData) {
+          session = mergeExtracted(session, targetRoute.initialData);
+        }
+
+        selectedRoute = targetRoute;
+      } else {
+        logger.warn(
+          `[Agent] Pending transition target route not found: ${session.pendingTransition.targetRouteId}`
+        );
+        // Clear invalid transition
+        session = {
+          ...session,
+          pendingTransition: undefined,
+        };
+      }
+    }
+
+    // If no pending transition or transition handled, do normal routing
+    if (this.routes.length > 0 && !selectedRoute) {
       const orchestration = await this.routingEngine.decideRouteAndState({
         routes: this.routes,
         session,
@@ -829,9 +999,99 @@ export class Agent<TContext = unknown> {
         );
       }
     } else if (isRouteComplete && selectedRoute) {
-      // Route is complete - set state to END_STATE marker and return completion signal
+      // Route is complete - generate completion message then check for onComplete transition
+      const lastUserMessage = getLastMessageFromHistory(history);
+
+      // Get endState spec from route
+      const endStateSpec = selectedRoute.endStateSpec;
+
+      // Create a temporary state for completion message generation using endState configuration
+      const completionState = new State<TContext>(
+        selectedRoute.id,
+        endStateSpec.chatState || "Summarize what was accomplished and confirm completion",
+        endStateSpec.id || END_STATE_ID,
+        endStateSpec.gather,
+        undefined,
+        endStateSpec.requiredData,
+        endStateSpec.chatState || "Summarize what was accomplished and confirm completion based on the conversation history and collected data"
+      );
+
+      // Build response schema for completion
+      const responseSchema = this.responseEngine.responseSchemaForRoute(
+        selectedRoute,
+        completionState
+      );
+
+      // Build completion response prompt
+      const completionPrompt = this.responseEngine.buildResponsePrompt(
+        selectedRoute,
+        completionState,
+        selectedRoute.getRules(),
+        selectedRoute.getProhibitions(),
+        undefined, // No directives for completion
+        history,
+        lastUserMessage,
+        {
+          name: this.options.name,
+          goal: this.options.goal,
+          description: this.options.description,
+          personality: this.options.personality,
+        }
+      );
+
+      // Generate completion message using AI provider
+      const completionResult = await this.options.ai.generateMessage({
+        prompt: completionPrompt,
+        history,
+        context: effectiveContext,
+        signal,
+        parameters: {
+          jsonSchema: responseSchema,
+          schemaName: "completion_message",
+        },
+      });
+
+      message = completionResult.structured?.message || completionResult.message;
+      logger.debug(
+        `[Agent] Generated completion message for route: ${selectedRoute.title}`
+      );
+
+      // Check for onComplete transition
+      const transitionConfig = await selectedRoute.evaluateOnComplete(
+        { extracted: session.extracted },
+        effectiveContext
+      );
+
+      if (transitionConfig) {
+        // Find target route by ID or title
+        const targetRoute = this.routes.find(
+          (r) =>
+            r.id === transitionConfig.transitionTo ||
+            r.title === transitionConfig.transitionTo
+        );
+
+        if (targetRoute) {
+          // Set pending transition in session
+          session = {
+            ...session,
+            pendingTransition: {
+              targetRouteId: targetRoute.id,
+              condition: transitionConfig.condition,
+              reason: "route_complete",
+            },
+          };
+          logger.debug(
+            `[Agent] Route ${selectedRoute.title} completed with pending transition to: ${targetRoute.title}`
+          );
+        } else {
+          logger.warn(
+            `[Agent] Route ${selectedRoute.title} completed but target route not found: ${transitionConfig.transitionTo}`
+          );
+        }
+      }
+
+      // Set state to END_STATE marker
       session = enterState(session, END_STATE_ID, "Route completed");
-      message = "";
       logger.debug(
         `[Agent] Route ${selectedRoute.title} completed. Entered END_STATE state.`
       );
@@ -1023,4 +1283,66 @@ export class Agent<TContext = unknown> {
     }
     return (this.currentSession.extracted as Partial<TExtracted>) || {};
   }
+
+  /**
+   * Manually transition to a different route
+   * Sets a pending transition that will be executed on the next respond() call
+   *
+   * @param routeIdOrTitle - Route ID or title to transition to
+   * @param session - Session state to update (uses current session if not provided)
+   * @param condition - Optional AI-evaluated condition for the transition
+   * @returns Updated session with pending transition
+   *
+   * @example
+   * // After route completes
+   * if (response.isRouteComplete && response.session) {
+   *   const updatedSession = agent.transitionToRoute("feedback-collection", response.session);
+   *   // Next respond() call will automatically transition to feedback route
+   *   const nextResponse = await agent.respond({ history, session: updatedSession });
+   * }
+   */
+  transitionToRoute(
+    routeIdOrTitle: string,
+    session?: SessionState,
+    condition?: string
+  ): SessionState {
+    const targetSession = session || this.currentSession;
+
+    if (!targetSession) {
+      throw new Error(
+        "No session provided and no current session available. Please provide a session to transition."
+      );
+    }
+
+    // Find target route by ID or title
+    const targetRoute = this.routes.find(
+      (r) => r.id === routeIdOrTitle || r.title === routeIdOrTitle
+    );
+
+    if (!targetRoute) {
+      throw new Error(
+        `Route not found: ${routeIdOrTitle}. Available routes: ${this.routes.map((r) => r.title).join(", ")}`
+      );
+    }
+
+    const updatedSession: SessionState = {
+      ...targetSession,
+      pendingTransition: {
+        targetRouteId: targetRoute.id,
+        condition,
+        reason: "manual",
+      },
+    };
+
+    // Update current session if using it
+    if (!session && this.currentSession) {
+      this.currentSession = updatedSession;
+    }
+
+    logger.debug(
+      `[Agent] Set pending manual transition to route: ${targetRoute.title}`
+    );
+
+    return updatedSession;
+  }
 }

package/src/core/Route.ts

@@ -7,6 +7,8 @@ import type {
   RouteRef,
   TransitionSpec,
   TransitionResult,
+  RouteTransitionConfig,
+  RouteCompletionHandler,
 } from "../types/route";
 import type { StructuredSchema } from "../types/schema";
 import type { Guideline } from "../types/agent";
@@ -26,9 +28,11 @@ export class Route<TContext = unknown, TExtracted = unknown> {
   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 responseOutputSchema?: StructuredSchema;
   public readonly extractionSchema?: StructuredSchema;
   public readonly initialData?: Partial<TExtracted>;
+  public readonly onComplete?: string | RouteTransitionConfig | RouteCompletionHandler<TContext, TExtracted>;
   private routingExtrasSchema?: StructuredSchema;
   private guidelines: Guideline[] = [];
 
@@ -47,12 +51,18 @@ export class Route<TContext = unknown, TExtracted = unknown> {
       options.initialState?.id,
       options.initialState?.gather,
       options.initialState?.skipIf,
-      options.initialState?.requiredData
+      options.initialState?.requiredData,
+      options.initialState?.chatState
     );
+    // 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"
+    };
     this.routingExtrasSchema = options.routingExtrasSchema;
     this.responseOutputSchema = options.responseOutputSchema;
     this.extractionSchema = options.extractionSchema;
     this.initialData = options.initialData;
+    this.onComplete = options.onComplete;
 
     // Initialize guidelines from options
     if (options.guidelines) {
@@ -219,4 +229,46 @@ export class Route<TContext = unknown, TExtracted = unknown> {
 
     return lines.join("\n");
   }
+
+  /**
+   * Evaluate the onComplete handler and return transition config
+   * @param session - Current session state
+   * @param context - Agent context
+   * @returns Transition config or undefined if no transition
+   */
+  async evaluateOnComplete(
+    session: { extracted?: Partial<TExtracted> },
+    context?: TContext
+  ): Promise<RouteTransitionConfig | undefined> {
+    if (!this.onComplete) {
+      return undefined;
+    }
+
+    // String form: just route ID/title
+    if (typeof this.onComplete === "string") {
+      return {
+        transitionTo: this.onComplete,
+      };
+    }
+
+    // Function form: execute and normalize result
+    if (typeof this.onComplete === "function") {
+      const result = await this.onComplete(session, context);
+
+      if (!result) {
+        return undefined;
+      }
+
+      if (typeof result === "string") {
+        return {
+          transitionTo: result,
+        };
+      }
+
+      return result;
+    }
+
+    // Object form: return as-is
+    return this.onComplete;
+  }
 }

package/src/core/RoutingEngine.ts

@@ -213,7 +213,9 @@ export class RoutingEngine<TContext = unknown> {
         typeof transition.spec.state === "symbol"
       ) {
         // Found END_STATE - route is complete
-        return { isRouteComplete: true };
+        return {
+          isRouteComplete: true
+        };
       }
 
       if (!target) continue;

package/src/core/State.ts

@@ -88,7 +88,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
     ) {
       const endTransition = new Transition<TContext, TExtracted>(
         this.getRef(),
-        { state: END_STATE, condition: spec.condition }
+        { state: END_STATE, condition: spec.condition, chatState: spec.chatState }
       );
       this.transitions.push(endTransition);
 

package/src/index.ts

@@ -95,9 +95,11 @@ export type {
   RouteOptions,
   TransitionSpec,
   TransitionResult,
+  RouteTransitionConfig,
+  RouteCompletionHandler,
 } from "./types/route";
 
-export type { SessionState } from "./types/session";
+export type { SessionState, PendingTransition } from "./types/session";
 export {
   createSession,
   enterRoute,

package/src/types/route.ts

@@ -28,6 +28,27 @@ export interface StateRef {
  */
 import type { Guideline } from "./agent";
 
+/**
+ * Route transition configuration when route completes
+ */
+export interface RouteTransitionConfig {
+  /** Target route ID or title to transition to */
+  transitionTo: 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 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> },
+  context?: TContext
+) => string | RouteTransitionConfig | undefined | Promise<string | RouteTransitionConfig | undefined>;
+
 /**
  * Options for creating a route
  * @template TExtracted - Type of data extracted throughout the route (inferred from extractionSchema)
@@ -79,6 +100,42 @@ export interface RouteOptions<TExtracted = unknown> {
     TransitionSpec<unknown, TExtracted>,
     "toolState" | "state" | "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
+   */
+  endState?: Omit<
+    TransitionSpec<unknown, TExtracted>,
+    "state" | "condition" | "skipIf"
+  >;
+  /**
+   * Optional transition when route completes (reaches END_STATE)
+   * Can be:
+   * - String: Route ID or title to transition to
+   * - Object: Transition config with optional AI-evaluated condition
+   * - Function: Dynamic logic that returns route ID, config, or undefined
+   *
+   * @example
+   * // Simple string
+   * onComplete: "feedback-collection"
+   *
+   * @example
+   * // With condition
+   * onComplete: {
+   *   transitionTo: "feedback-collection",
+   *   condition: "if booking succeeded"
+   * }
+   *
+   * @example
+   * // Dynamic function
+   * onComplete: (session) => {
+   *   if (session.extracted?.success) return "feedback";
+   *   return "error-recovery";
+   * }
+   */
+  onComplete?: string | RouteTransitionConfig | RouteCompletionHandler<unknown, TExtracted>;
 }
 
 /**
@@ -91,7 +148,7 @@ export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
   chatState?: string;
   /** Transition to execute a tool */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  toolState?: ToolRef<TContext, any[], any>;
+  toolState?: ToolRef<TContext, any[], any, TExtracted>;
   /** Transition to a specific state or end marker */
   state?: StateRef | symbol;
   /**

package/src/types/session.ts

@@ -2,6 +2,18 @@
  * Session state types for tracking conversation progress
  */
 
+/**
+ * Pending route transition information
+ */
+export interface PendingTransition {
+  /** Target route ID to transition to */
+  targetRouteId: string;
+  /** Optional AI-evaluated condition for the transition */
+  condition?: string;
+  /** Reason for the transition */
+  reason: "route_complete" | "manual";
+}
+
 /**
  * Session state tracks the current position in the conversation flow
  * and data extracted during the route progression
@@ -45,6 +57,12 @@ export interface SessionState<TExtracted = Record<string, unknown>> {
     completed: boolean;
   }>;
 
+  /**
+   * Pending route transition after completion
+   * Set when a route completes with onComplete handler
+   */
+  pendingTransition?: PendingTransition;
+
   /** Session metadata */
   metadata?: {
     createdAt?: Date;
@@ -163,12 +181,12 @@ export function enterState<TExtracted = Record<string, unknown>>(
  */
 export function mergeExtracted<TExtracted = Record<string, unknown>>(
   session: SessionState<TExtracted>,
-  extracted: Partial<TExtracted>
+  extracted: Partial<unknown>
 ): SessionState<TExtracted> {
   const newExtracted = {
     ...session.extracted,
     ...extracted,
-  };
+  } as Partial<TExtracted>;
 
   // Also update the extractedByRoute map for the current route
   const extractedByRoute = { ...session.extractedByRoute };