@falai/agent 0.5.4 → 0.6.0

package/dist/core/State.d.ts

@@ -21,10 +21,9 @@ export declare 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): TransitionResult<TContext, TExtracted>;
+    transitionTo(spec: TransitionSpec<TContext, TExtracted>): TransitionResult<TContext, TExtracted>;
     /**
      * Add a guideline specific to this state
      */

package/dist/core/State.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"State.d.ts","sourceRoot":"","sources":["../../src/core/State.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EACd,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C;;GAEG;AACH,qBAAa,KAAK,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;aASvC,OAAO,EAAE,MAAM;aACf,WAAW,CAAC,EAAE,MAAM;IATtC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,WAAW,CAA0C;IAC7D,OAAO,CAAC,UAAU,CAAmB;IACrC,SAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxC,SAAgB,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC;IACrE,SAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;gBAGtB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,YAAA,EACpC,QAAQ,CAAC,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EAAE,EACvB,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,EACpD,YAAY,CAAC,EAAE,MAAM,EAAE;IASzB;;;;;;OAMG;IACH,YAAY,CACV,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,EAC1C,SAAS,CAAC,EAAE,MAAM,GACjB,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC;IAmDzC;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIxC;;OAEG;IACH,aAAa,IAAI,SAAS,EAAE;IAI5B;;OAEG;IACH,cAAc,IAAI,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE;IAIpD;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO;IAKnD;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO;IAOxD;;OAEG;IACH,MAAM,IAAI,QAAQ;IAOlB;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAepC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAa1B"}
+{"version":3,"file":"State.d.ts","sourceRoot":"","sources":["../../src/core/State.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EACd,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C;;GAEG;AACH,qBAAa,KAAK,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;aASvC,OAAO,EAAE,MAAM;aACf,WAAW,CAAC,EAAE,MAAM;IATtC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,WAAW,CAA0C;IAC7D,OAAO,CAAC,UAAU,CAAmB;IACrC,SAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxC,SAAgB,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC;IACrE,SAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;gBAGtB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,YAAA,EACpC,QAAQ,CAAC,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EAAE,EACvB,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,EACpD,YAAY,CAAC,EAAE,MAAM,EAAE;IASzB;;;;;OAKG;IACH,YAAY,CACV,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,GACzC,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC;IAgDzC;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIxC;;OAEG;IACH,aAAa,IAAI,SAAS,EAAE;IAI5B;;OAEG;IACH,cAAc,IAAI,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE;IAIpD;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO;IAKnD;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO;IAOxD;;OAEG;IACH,MAAM,IAAI,QAAQ;IAOlB;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAapC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAa1B"}

package/dist/core/State.js

@@ -23,29 +23,28 @@ export class State {
      * 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, condition) {
+    transitionTo(spec) {
         // Handle END_ROUTE
         if (spec.state &&
             typeof spec.state === "symbol" &&
             spec.state === END_ROUTE) {
-            const endTransition = new Transition(this.getRef(), { state: END_ROUTE }, condition);
+            const endTransition = new Transition(this.getRef(), { state: END_ROUTE, condition: spec.condition });
             this.transitions.push(endTransition);
             // Return a terminal state reference
             return this.createTerminalRef();
         }
         // Handle direct state reference
         if (spec.state && typeof spec.state !== "symbol") {
-            const transition = new Transition(this.getRef(), spec, condition);
+            const transition = new Transition(this.getRef(), spec);
             this.transitions.push(transition);
             return this.createStateRefWithTransition(spec.state);
         }
         // Create new target state for chatState or toolState
         const targetState = new State(this.routeId, spec.chatState, spec.id, // Use custom ID if provided
         spec.gather, spec.skipIf, spec.requiredData);
-        const transition = new Transition(this.getRef(), spec, condition);
+        const transition = new Transition(this.getRef(), spec);
         transition.setTarget(targetState);
         this.transitions.push(transition);
         return this.createStateRefWithTransition(targetState.getRef(), targetState);
@@ -100,7 +99,7 @@ export class State {
         const stateInstance = state || this;
         return {
             ...ref,
-            transitionTo: (spec, condition) => stateInstance.transitionTo(spec, condition),
+            transitionTo: (spec) => stateInstance.transitionTo(spec),
         };
     }
     /**

package/dist/core/State.js.map

@@ -1 +1 @@
-{"version":3,"file":"State.js","sourceRoot":"","sources":["../../src/core/State.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"State.js","sourceRoot":"","sources":["../../src/core/State.ts"],"names":[],"mappings":"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"}

package/dist/core/Transition.d.ts

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

package/dist/core/Transition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Transition.d.ts","sourceRoot":"","sources":["../../src/core/Transition.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;GAEG;AACH,qBAAa,UAAU,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;aAI5C,MAAM,EAAE,QAAQ;aAChB,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC;aAC1C,SAAS,CAAC,EAAE,MAAM;IALpC,OAAO,CAAC,MAAM,CAAC,CAA8B;gBAG3B,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,EAC1C,SAAS,CAAC,EAAE,MAAM,YAAA;IAGpC;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,GAAG,IAAI;IAInD;;OAEG;IACH,SAAS,IAAI,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,GAAG,SAAS;IAIpD;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,QAAQ,IAAI,MAAM;CAsBnB"}
+{"version":3,"file":"Transition.d.ts","sourceRoot":"","sources":["../../src/core/Transition.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;GAEG;AACH,qBAAa,UAAU,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;aAK5C,MAAM,EAAE,QAAQ;aAChB,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC;IAL5D,OAAO,CAAC,MAAM,CAAC,CAA8B;IAC7C,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;gBAGjB,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC;IAM5D;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,GAAG,IAAI;IAInD;;OAEG;IACH,SAAS,IAAI,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,GAAG,SAAS;IAIpD;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,QAAQ,IAAI,MAAM;CAsBnB"}

package/dist/core/Transition.js

@@ -5,10 +5,11 @@
  * Represents a transition from one state to another
  */
 export class Transition {
-    constructor(source, spec, condition) {
+    constructor(source, spec) {
         this.source = source;
         this.spec = spec;
-        this.condition = condition;
+        // Extract condition from spec for convenience
+        this.condition = spec.condition;
     }
     /**
      * Set the target state for this transition

package/dist/core/Transition.js.map

@@ -1 +1 @@
-{"version":3,"file":"Transition.js","sourceRoot":"","sources":["../../src/core/Transition.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;GAEG;AACH,MAAM,OAAO,UAAU;IAGrB,YACkB,MAAgB,EAChB,IAA0C,EAC1C,SAAkB;QAFlB,WAAM,GAAN,MAAM,CAAU;QAChB,SAAI,GAAJ,IAAI,CAAsC;QAC1C,cAAS,GAAT,SAAS,CAAS;IACjC,CAAC;IAEJ;;OAEG;IACH,SAAS,CAAC,KAAkC;QAC1C,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACpB,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACxC,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAEzE,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,UAAU,IAAI,aAAa,EAAE,CAAC;IAChE,CAAC;CACF"}
+{"version":3,"file":"Transition.js","sourceRoot":"","sources":["../../src/core/Transition.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;GAEG;AACH,MAAM,OAAO,UAAU;IAIrB,YACkB,MAAgB,EAChB,IAA0C;QAD1C,WAAM,GAAN,MAAM,CAAU;QAChB,SAAI,GAAJ,IAAI,CAAsC;QAE1D,8CAA8C;QAC9C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,KAAkC;QAC1C,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACpB,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACxC,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAEzE,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,UAAU,IAAI,aAAa,EAAE,CAAC;IAChE,CAAC;CACF"}

package/dist/types/route.d.ts

@@ -25,7 +25,7 @@ export interface StateRef {
 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) */
@@ -52,13 +52,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>[];
 }
 /**
  * Specification for a state transition
@@ -74,7 +80,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[];
     /**
@@ -90,6 +96,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;
 }
 /**
  * Result of a transition operation
@@ -97,6 +108,6 @@ export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
  */
 export interface TransitionResult<TContext = unknown, TExtracted = unknown> extends StateRef {
     /** Allow chaining transitions */
-    transitionTo: (spec: TransitionSpec<TContext, TExtracted>, condition?: string) => TransitionResult<TContext, TExtracted>;
+    transitionTo: (spec: TransitionSpec<TContext, TExtracted>) => TransitionResult<TContext, TExtracted>;
 }
 //# sourceMappingURL=route.d.ts.map

package/dist/types/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,UAAU,GAAG,OAAO;IAChD,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;IACvC,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,gBAAgB,CAAC;IACxC;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACtE,2FAA2F;IAC3F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IAEnC,SAAS,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC;IACrD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO,CACxE,SAAQ,QAAQ;IAChB,iCAAiC;IACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,EAC1C,SAAS,CAAC,EAAE,MAAM,KACf,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;CAC7C"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,UAAU,GAAG,OAAO;IAChD,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;IACvC,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,gBAAgB,CAAC;IACxC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACtE,2FAA2F;IAC3F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IAEnC,SAAS,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC;IACrD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO,CACxE,SAAQ,QAAQ;IAChB,iCAAiC;IACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,KACvC,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;CAC7C"}

package/dist/utils/event.d.ts

@@ -0,0 +1,6 @@
+import { type Event } from "../types/history";
+/**
+ * Helper to extract last message from history
+ */
+export declare function getLastMessageFromHistory(history: Event[]): string;
+//# sourceMappingURL=event.d.ts.map

package/dist/utils/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/utils/event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,kBAAkB,CAAC;AACzD;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,CAWlE"}

package/dist/utils/event.js

@@ -0,0 +1,17 @@
+import { EventKind } from "../types/history";
+/**
+ * Helper to extract last message from history
+ */
+export function getLastMessageFromHistory(history) {
+    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 "";
+}
+//# sourceMappingURL=event.js.map

package/dist/utils/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../../src/utils/event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACzD;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9C,SAAS;YACX,CAAC;YACD,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/docs/ADAPTERS.md

@@ -102,7 +102,7 @@ const agent = new Agent({
 // Create a route with data extraction
 const route = agent.createRoute<YourDataType>({
   title: "My Route",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       field1: { type: "string" },

package/docs/API_REFERENCE.md

@@ -321,7 +321,7 @@ interface RouteOptions<TExtracted = unknown> {
   prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do in this route
 
   // NEW: Schema-first data extraction
-  gatherSchema?: {
+  extractionSchema?: {
     type: "object";
     properties: Record<string, any>;
     required?: string[];
@@ -395,7 +395,7 @@ Represents a state within a conversation route.
 
 #### Methods
 
-##### `transitionTo(spec: TransitionSpec, condition?: string): TransitionResult`
+##### `transitionTo(spec: TransitionSpec): TransitionResult`
 
 Creates a transition from this state and returns a chainable result.
 
@@ -413,18 +413,24 @@ interface TransitionSpec<TExtracted = unknown> {
 
   // NEW: Prerequisites that must be met to enter this state
   requiredData?: string[];
+
+  // Optional: AI-evaluated text condition for this transition
+  condition?: string;
 }
 
 interface TransitionResult<TExtracted = unknown> {
   id: string; // State identifier
   routeId: string; // Route identifier
   transitionTo: (
-    spec: TransitionSpec<TExtracted>,
-    condition?: string
+    spec: TransitionSpec<TExtracted>
   ) => TransitionResult<TExtracted>;
 }
 ```
 
+**Parameters:**
+
+- `spec`: The transition specification (see `TransitionSpec` above). Can include an optional `condition` property for AI-evaluated state selection guidance.
+
 **Returns:** A `TransitionResult` that includes the target state's reference (`id`, `routeId`) and a `transitionTo` method for chaining additional transitions.
 
 **Example:**
@@ -440,7 +446,7 @@ interface FlightData {
 // Create a data-driven route
 const flightRoute = agent.createRoute<FlightData>({
   title: "Book Flight",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },
@@ -451,11 +457,12 @@ const flightRoute = agent.createRoute<FlightData>({
   },
 });
 
-// Approach 1: Step-by-step with data extraction
+// Approach 1: Step-by-step with data extraction and text conditions
 const askDestination = flightRoute.initialState.transitionTo({
   chatState: "Ask where they want to fly",
   gather: ["destination"],
   skipIf: (extracted) => !!extracted.destination, // Skip if already have destination
+  condition: "Customer hasn't specified destination yet", // AI-evaluated condition
 });
 
 const askDates = askDestination.transitionTo({
@@ -463,6 +470,7 @@ const askDates = askDestination.transitionTo({
   gather: ["departureDate"],
   skipIf: (extracted) => !!extracted.departureDate,
   requiredData: ["destination"], // Must have destination first
+  condition: "Destination confirmed, need travel dates",
 });
 
 const askPassengers = askDates.transitionTo({
@@ -1546,7 +1554,7 @@ interface SessionState<TExtracted = Record<string, unknown>> {
 **Key Features:**
 
 - **`id`** - Optional session identifier that persists across database operations
-- **`extracted`** - Type-safe data collected via `gatherSchema`
+- **`extracted`** - Type-safe data collected via `extractionSchema`
 - **`currentRoute`** / **`currentState`** - Track conversation position
 - **`routeHistory`** - Full audit trail of route transitions
 - **`metadata`** - Custom data (timestamps, user info, etc.)

package/docs/ARCHITECTURE.md

@@ -22,7 +22,7 @@ interface FlightData {
 const route = agent.createRoute<FlightData>({
   title: "Book Flight",
   description: "Help user book a flight",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },
@@ -106,9 +106,9 @@ const response = await agent.respond({
 - **State Recovery** - Resume conversations from any point
 - **Session Tracking** - Track conversations via session ID in database
 
-### 3. 🔧 Code-Based State Logic
+### 3. 🔧 Code-Based State Logic + AI-Driven Transitions
 
-Use TypeScript functions instead of LLM conditions for deterministic flow:
+Use TypeScript functions for deterministic flow control AND text conditions for AI-driven state selection:
 
 ```typescript
 // State with smart bypassing based on extracted data
@@ -117,6 +117,7 @@ const askDestination = route.initialState.transitionTo({
   chatState: "Ask where they want to fly",
   gather: ["destination"],
   skipIf: (extracted) => !!extracted.destination, // Code-based condition!
+  condition: "Customer hasn't specified destination yet", // Text condition for AI
 });
 
 const askDate = askDestination.transitionTo({
@@ -125,6 +126,8 @@ const askDate = askDestination.transitionTo({
   gather: ["departureDate"],
   skipIf: (extracted) => !!extracted.departureDate,
   requiredData: ["destination"], // Prerequisites
+  condition: "Destination confirmed, need travel dates now",
+});
 });
 ```
 
@@ -150,6 +153,23 @@ If you don't provide an ID, one is automatically generated from the route ID and
 - **Type Safety** - Full TypeScript support for data validation
 - **Custom IDs** - Easier tracking and debugging with meaningful state identifiers
 
+**How State Transitions Work:**
+
+1. **Code filters first**: `skipIf` and `requiredData` filter out invalid states deterministically
+2. **AI selects best state**: From valid candidates, AI evaluates text conditions to choose optimal state
+3. **Combined decision**: Single AI call handles both route selection AND state selection (no extra calls!)
+4. **Completion detection**: When all states are skipped and `END_ROUTE` is reached, route is marked complete
+
+```typescript
+// The AI sees:
+// "Available states: askDate, confirmBooking
+//  - askDate: Destination confirmed, need travel dates now
+//  - confirmBooking: All required info collected, ready to book
+//  Current extracted: {destination: 'Paris', departureDate: '2025-01-15'}
+//
+//  → AI selects 'confirmBooking' based on context"
+```
+
 ### 4. 🛠️ Tools with Data Access
 
 Tools execute with full context including extracted data:
@@ -350,7 +370,7 @@ interface BookingData {
 
 const bookingRoute = agent.createRoute<BookingData>({
   title: "Flight Booking",
-  gatherSchema: {
+  extractionSchema: {
     /* schema for all fields */
   },
 });
@@ -380,7 +400,7 @@ For simple question-answering without state:
 const qnaRoute = agent.createRoute({
   title: "Company Q&A",
   conditions: ["User asks about company"],
-  // NO gatherSchema - stateless!
+  // NO extractionSchema - stateless!
 });
 
 // Just use initial state

package/docs/CONSTRUCTOR_OPTIONS.md

@@ -103,7 +103,7 @@ const agent = new Agent<FlightBookingContext>({
       title: 'Book Flight',
       description: 'Help user book a flight',
       conditions: ['User wants to book a flight'],
-      gatherSchema: {
+      extractionSchema: {
         type: 'object',
         properties: {
           destination: { type: 'string' },
@@ -175,7 +175,7 @@ interface RouteOptions<TExtracted = unknown> {
   prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do
 
   // NEW: Schema-first data extraction
-  gatherSchema?: {
+  extractionSchema?: {
     type: "object";
     properties: Record<string, any>;
     required?: string[];

package/docs/CONTEXT_MANAGEMENT.md

@@ -182,7 +182,7 @@ interface FlightData {
 
 const route = agent.createRoute<FlightData>({
   title: "Book Flight",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },

package/docs/GETTING_STARTED.md

@@ -86,7 +86,7 @@ const bookingRoute = agent.createRoute<FlightData>({
   title: "Book Flight",
   description: "Help user book a flight",
   conditions: ["User wants to book a flight"],
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },

package/docs/PERSISTENCE.md

@@ -110,7 +110,7 @@ const agent = new Agent({
 // Create a route with data extraction
 const bookingRoute = agent.createRoute<BookingData>({
   title: "Book Flight",
-  gatherSchema: {
+  extractionSchema: {
     type: "object",
     properties: {
       destination: { type: "string" },
@@ -273,7 +273,7 @@ await agent.updateContext({ preferences: { theme: "dark" } });
 The new architecture automatically saves and loads `SessionState<TExtracted>` which includes:
 
 - **Current route and state** - Track conversation progress
-- **Extracted data** - All data gathered via `gatherSchema` and `gather` fields
+- **Extracted data** - All data gathered via `extractionSchema` and `gather` fields
 - **Route history** - History of route transitions
 - **Metadata** - Session timestamps and custom data
 
@@ -533,7 +533,7 @@ await persistence.saveMessage({
 
 1. ✅ **Use `createSessionWithState()`** - Get both database record and session state in one call
 2. ✅ **Enable `autoSave: true`** - Automatically persist session state after each response
-3. ✅ **Define extraction schemas** - Use `gatherSchema` in routes for structured data collection
+3. ✅ **Define extraction schemas** - Use `extractionSchema` in routes for structured data collection
 4. ✅ **Pass session state** - Always pass `session` parameter to `agent.respond()`
 5. ✅ **Load session state** - Use `loadSessionState()` to resume conversations
 6. ✅ **Store extracted data** - Leverage `collectedData.extracted` for user input tracking