@falai/agent 0.5.4 → 0.6.0

package/src/core/State.ts

@@ -43,12 +43,10 @@ export class State<TContext = unknown, TExtracted = unknown> {
    * Create a transition from this state to another
    *
    * @param spec - Transition specification (chatState, toolState, or direct state)
-   * @param condition - Optional condition for this transition
    * @returns TransitionResult that supports chaining
    */
   transitionTo(
-    spec: TransitionSpec<TContext, TExtracted>,
-    condition?: string
+    spec: TransitionSpec<TContext, TExtracted>
   ): TransitionResult<TContext, TExtracted> {
     // Handle END_ROUTE
     if (
@@ -58,8 +56,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
     ) {
       const endTransition = new Transition<TContext, TExtracted>(
         this.getRef(),
-        { state: END_ROUTE },
-        condition
+        { state: END_ROUTE, condition: spec.condition }
       );
       this.transitions.push(endTransition);
 
@@ -71,8 +68,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
     if (spec.state && typeof spec.state !== "symbol") {
       const transition = new Transition<TContext, TExtracted>(
         this.getRef(),
-        spec,
-        condition
+        spec
       );
       this.transitions.push(transition);
 
@@ -90,8 +86,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
     );
     const transition = new Transition<TContext, TExtracted>(
       this.getRef(),
-      spec,
-      condition
+      spec
     );
     transition.setTarget(targetState);
 
@@ -160,10 +155,8 @@ export class State<TContext = unknown, TExtracted = unknown> {
 
     return {
       ...ref,
-      transitionTo: (
-        spec: TransitionSpec<TContext, TExtracted>,
-        condition?: string
-      ) => stateInstance.transitionTo(spec, condition),
+      transitionTo: (spec: TransitionSpec<TContext, TExtracted>) =>
+        stateInstance.transitionTo(spec),
     };
   }
 

package/src/core/Transition.ts

@@ -10,12 +10,15 @@ import type { State } from "./State";
  */
 export class Transition<TContext = unknown, TExtracted = unknown> {
   private target?: State<TContext, TExtracted>;
+  public readonly condition?: string;
 
   constructor(
     public readonly source: StateRef,
-    public readonly spec: TransitionSpec<TContext, TExtracted>,
-    public readonly condition?: string
-  ) {}
+    public readonly spec: TransitionSpec<TContext, TExtracted>
+  ) {
+    // Extract condition from spec for convenience
+    this.condition = spec.condition;
+  }
 
   /**
    * Set the target state for this transition

package/src/types/route.ts

@@ -30,7 +30,7 @@ import type { Guideline } from "./agent";
 
 /**
  * Options for creating a route
- * @template TExtracted - Type of data extracted throughout the route (inferred from gatherSchema)
+ * @template TExtracted - Type of data extracted throughout the route (inferred from extractionSchema)
  */
 export interface RouteOptions<TExtracted = unknown> {
   /** Custom ID for the route (optional - will generate deterministic ID from title if not provided) */
@@ -57,13 +57,19 @@ 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
    */
-  gatherSchema?: StructuredSchema;
+  extractionSchema?: 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
    */
   initialData?: Partial<TExtracted>;
+  /**
+   * NEW: Sequential steps for simple linear flows
+   * If provided, automatically chains the steps from initialState to END_ROUTE
+   * For complex flows with branching, build the state machine manually instead
+   */
+  steps?: TransitionSpec<unknown, TExtracted>[];
 }
 
 /**
@@ -81,7 +87,7 @@ export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
   state?: StateRef | symbol;
   /**
    * NEW: Fields to gather from the conversation in this state
-   * These should match keys in the route's gatherSchema
+   * These should match keys in the route's extractionSchema
    */
   gather?: string[];
   /**
@@ -97,6 +103,11 @@ export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
    * Uses string[] for developer-friendly usage (same as gather)
    */
   requiredData?: string[];
+  /**
+   * Optional condition for this transition
+   * Description of when this transition should be taken
+   */
+  condition?: string;
 }
 
 /**
@@ -107,7 +118,6 @@ export interface TransitionResult<TContext = unknown, TExtracted = unknown>
   extends StateRef {
   /** Allow chaining transitions */
   transitionTo: (
-    spec: TransitionSpec<TContext, TExtracted>,
-    condition?: string
+    spec: TransitionSpec<TContext, TExtracted>
   ) => TransitionResult<TContext, TExtracted>;
 }

package/src/utils/event.ts

@@ -0,0 +1,16 @@
+import { type Event, EventKind } from "../types/history";
+/**
+ * Helper to extract last message from history
+ */
+export function getLastMessageFromHistory(history: Event[]): string {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const event = history[i];
+    if (event.kind === EventKind.MESSAGE) {
+      if (!event.data || !("message" in event.data)) {
+        continue;
+      }
+      return event.data.message;
+    }
+  }
+  return "";
+}