@falai/agent 0.2.0 → 0.3.0

package/README.md

@@ -292,12 +292,12 @@ const askName = onboardingRoute.initialState.transitionTo({
   chatState: "Ask for user's full name",
 });
 
-const askEmail = askName.target.transitionTo({
+const askEmail = askName.transitionTo({
   chatState: "Request email address",
   condition: "User provided their name",
 });
 
-const confirmDetails = askEmail.target.transitionTo({
+const confirmDetails = askEmail.transitionTo({
   chatState: "Confirm all details before proceeding",
 });
 
@@ -310,13 +310,13 @@ onboardingRoute.createGuideline({
 });
 
 // Happy path completion
-confirmDetails.target.transitionTo({
+confirmDetails.transitionTo({
   chatState: "Welcome message and next steps",
   condition: "User confirms details",
 });
 
 // End the route
-confirmDetails.target.transitionTo({ state: END_ROUTE });
+confirmDetails.transitionTo({ state: END_ROUTE });
 ```
 
 ### 🔀 Disambiguation with Observations

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

@@ -19,7 +19,7 @@ export declare class State<TContext = unknown> {
      *
      * @param spec - Transition specification (chatState, toolState, or direct state)
      * @param condition - Optional condition for this transition
-     * @returns Object with target state that supports chaining
+     * @returns TransitionResult that supports chaining
      */
     transitionTo(spec: TransitionSpec<TContext>, condition?: string): TransitionResult<TContext>;
     /**

package/dist/cjs/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;aAMjB,OAAO,EAAE,MAAM;aACf,WAAW,CAAC,EAAE,MAAM;IANtC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,UAAU,CAAmB;gBAGnB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,YAAA,EACpC,QAAQ,CAAC,EAAE,MAAM;IAMnB;;;;;;OAMG;IACH,YAAY,CACV,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,GACjB,gBAAgB,CAAC,QAAQ,CAAC;IAiD7B;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIxC;;OAEG;IACH,aAAa,IAAI,SAAS,EAAE;IAI5B;;OAEG;IACH,cAAc,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE;IAIxC;;OAEG;IACH,MAAM,IAAI,QAAQ;IAOlB;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAkBpC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAkB1B"}
+{"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;aAMjB,OAAO,EAAE,MAAM;aACf,WAAW,CAAC,EAAE,MAAM;IANtC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,UAAU,CAAmB;gBAGnB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,YAAA,EACpC,QAAQ,CAAC,EAAE,MAAM;IAMnB;;;;;;OAMG;IACH,YAAY,CACV,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,GACjB,gBAAgB,CAAC,QAAQ,CAAC;IAwC7B;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIxC;;OAEG;IACH,aAAa,IAAI,SAAS,EAAE;IAI5B;;OAEG;IACH,cAAc,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE;IAIxC;;OAEG;IACH,MAAM,IAAI,QAAQ;IAOlB;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAapC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAa1B"}

package/dist/cjs/core/State.js

@@ -24,7 +24,7 @@ class State {
      *
      * @param spec - Transition specification (chatState, toolState, or direct state)
      * @param condition - Optional condition for this transition
-     * @returns Object with target state that supports chaining
+     * @returns TransitionResult that supports chaining
      */
     transitionTo(spec, condition) {
         // Handle END_ROUTE
@@ -34,26 +34,20 @@ class State {
             const endTransition = new Transition_1.Transition(this.getRef(), { state: constants_1.END_ROUTE }, condition);
             this.transitions.push(endTransition);
             // Return a terminal state reference
-            return {
-                target: this.createTerminalRef(),
-            };
+            return this.createTerminalRef();
         }
         // Handle direct state reference
         if (spec.state && typeof spec.state !== "symbol") {
             const transition = new Transition_1.Transition(this.getRef(), spec, condition);
             this.transitions.push(transition);
-            return {
-                target: this.createStateRefWithTransition(spec.state),
-            };
+            return this.createStateRefWithTransition(spec.state);
         }
         // Create new target state for chatState or toolState
         const targetState = new State(this.routeId, spec.chatState);
         const transition = new Transition_1.Transition(this.getRef(), spec, condition);
         transition.setTarget(targetState);
         this.transitions.push(transition);
-        return {
-            target: this.createStateRefWithTransition(targetState.getRef(), targetState),
-        };
+        return this.createStateRefWithTransition(targetState.getRef(), targetState);
     }
     /**
      * Add a guideline specific to this state

package/dist/cjs/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/cjs/types/route.d.ts

@@ -50,12 +50,10 @@ export interface TransitionSpec<TContext = unknown> {
 }
 /**
  * Result of a transition operation
+ * Combines state reference with the ability to chain transitions
  */
-export interface TransitionResult<TContext = unknown> {
-    /** The target state after transition */
-    target: StateRef & {
-        /** Allow chaining transitions */
-        transitionTo: (spec: TransitionSpec<TContext>, condition?: string) => TransitionResult<TContext>;
-    };
+export interface TransitionResult<TContext = unknown> extends StateRef {
+    /** Allow chaining transitions */
+    transitionTo: (spec: TransitionSpec<TContext>, condition?: string) => TransitionResult<TContext>;
 }
 //# sourceMappingURL=route.d.ts.map

package/dist/cjs/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;AAEtC;;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;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,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;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO;IAChD,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;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO;IAClD,wCAAwC;IACxC,MAAM,EAAE,QAAQ,GAAG;QACjB,iCAAiC;QACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,KACf,gBAAgB,CAAC,QAAQ,CAAC,CAAC;KACjC,CAAC;CACH"}
+{"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;AAEtC;;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;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,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;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO;IAChD,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;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO,CAAE,SAAQ,QAAQ;IACpE,iCAAiC;IACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,KACf,gBAAgB,CAAC,QAAQ,CAAC,CAAC;CACjC"}

package/dist/core/State.d.ts

@@ -19,7 +19,7 @@ export declare class State<TContext = unknown> {
      *
      * @param spec - Transition specification (chatState, toolState, or direct state)
      * @param condition - Optional condition for this transition
-     * @returns Object with target state that supports chaining
+     * @returns TransitionResult that supports chaining
      */
     transitionTo(spec: TransitionSpec<TContext>, condition?: string): TransitionResult<TContext>;
     /**

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;aAMjB,OAAO,EAAE,MAAM;aACf,WAAW,CAAC,EAAE,MAAM;IANtC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,UAAU,CAAmB;gBAGnB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,YAAA,EACpC,QAAQ,CAAC,EAAE,MAAM;IAMnB;;;;;;OAMG;IACH,YAAY,CACV,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,GACjB,gBAAgB,CAAC,QAAQ,CAAC;IAiD7B;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIxC;;OAEG;IACH,aAAa,IAAI,SAAS,EAAE;IAI5B;;OAEG;IACH,cAAc,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE;IAIxC;;OAEG;IACH,MAAM,IAAI,QAAQ;IAOlB;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAkBpC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAkB1B"}
+{"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;aAMjB,OAAO,EAAE,MAAM;aACf,WAAW,CAAC,EAAE,MAAM;IANtC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,UAAU,CAAmB;gBAGnB,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,YAAA,EACpC,QAAQ,CAAC,EAAE,MAAM;IAMnB;;;;;;OAMG;IACH,YAAY,CACV,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,GACjB,gBAAgB,CAAC,QAAQ,CAAC;IAwC7B;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIxC;;OAEG;IACH,aAAa,IAAI,SAAS,EAAE;IAI5B;;OAEG;IACH,cAAc,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE;IAIxC;;OAEG;IACH,MAAM,IAAI,QAAQ;IAOlB;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAapC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAa1B"}

package/dist/core/State.js

@@ -21,7 +21,7 @@ export class State {
      *
      * @param spec - Transition specification (chatState, toolState, or direct state)
      * @param condition - Optional condition for this transition
-     * @returns Object with target state that supports chaining
+     * @returns TransitionResult that supports chaining
      */
     transitionTo(spec, condition) {
         // Handle END_ROUTE
@@ -31,26 +31,20 @@ export class State {
             const endTransition = new Transition(this.getRef(), { state: END_ROUTE }, condition);
             this.transitions.push(endTransition);
             // Return a terminal state reference
-            return {
-                target: this.createTerminalRef(),
-            };
+            return this.createTerminalRef();
         }
         // Handle direct state reference
         if (spec.state && typeof spec.state !== "symbol") {
             const transition = new Transition(this.getRef(), spec, condition);
             this.transitions.push(transition);
-            return {
-                target: this.createStateRefWithTransition(spec.state),
-            };
+            return this.createStateRefWithTransition(spec.state);
         }
         // Create new target state for chatState or toolState
         const targetState = new State(this.routeId, spec.chatState);
         const transition = new Transition(this.getRef(), spec, condition);
         transition.setTarget(targetState);
         this.transitions.push(transition);
-        return {
-            target: this.createStateRefWithTransition(targetState.getRef(), targetState),
-        };
+        return this.createStateRefWithTransition(targetState.getRef(), targetState);
     }
     /**
      * Add a guideline specific to this state

package/dist/core/State.js.map

@@ -1 +1 @@
-{"version":3,"file":"State.js","sourceRoot":"","sources":["../../src/core/State.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;GAEG;AACH,MAAM,OAAO,KAAK;IAKhB,YACkB,OAAe,EACf,WAAoB,EACpC,QAAiB;QAFD,YAAO,GAAP,OAAO,CAAQ;QACf,gBAAW,GAAX,WAAW,CAAS;QAL9B,gBAAW,GAA2B,EAAE,CAAC;QACzC,eAAU,GAAgB,EAAE,CAAC;QAOnC,kDAAkD;QAClD,IAAI,CAAC,EAAE,GAAG,QAAQ,IAAI,eAAe,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CACV,IAA8B,EAC9B,SAAkB;QAElB,mBAAmB;QACnB,IACE,IAAI,CAAC,KAAK;YACV,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;YAC9B,IAAI,CAAC,KAAK,KAAK,SAAS,EACxB,CAAC;YACD,MAAM,aAAa,GAAG,IAAI,UAAU,CAClC,IAAI,CAAC,MAAM,EAAE,EACb,EAAE,KAAK,EAAE,SAAS,EAAE,EACpB,SAAS,CACV,CAAC;YACF,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAErC,oCAAoC;YACpC,OAAO;gBACL,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE;aACjC,CAAC;QACJ,CAAC;QAED,gCAAgC;QAChC,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACjD,MAAM,UAAU,GAAG,IAAI,UAAU,CAC/B,IAAI,CAAC,MAAM,EAAE,EACb,IAAI,EACJ,SAAS,CACV,CAAC;YACF,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAElC,OAAO;gBACL,MAAM,EAAE,IAAI,CAAC,4BAA4B,CAAC,IAAI,CAAC,KAAK,CAAC;aACtD,CAAC;QACJ,CAAC;QAED,qDAAqD;QACrD,MAAM,WAAW,GAAG,IAAI,KAAK,CAAW,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACtE,MAAM,UAAU,GAAG,IAAI,UAAU,CAAW,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QAC5E,UAAU,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QAElC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAElC,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,4BAA4B,CACvC,WAAW,CAAC,MAAM,EAAE,EACpB,WAAW,CACZ;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,SAAoB;QAC/B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,4BAA4B,CAClC,GAAa,EACb,KAAuB;QAOvB,MAAM,aAAa,GAAG,KAAK,IAAI,IAAI,CAAC;QAEpC,OAAO;YACL,GAAG,GAAG;YACN,YAAY,EAAE,CAAC,IAA8B,EAAE,SAAkB,EAAE,EAAE,CACnE,aAAa,CAAC,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC;SAC9C,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,iBAAiB;QAMvB,MAAM,WAAW,GAAa;YAC5B,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;QAEF,OAAO;YACL,GAAG,WAAW;YACd,YAAY,EAAE,GAAG,EAAE;gBACjB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC5D,CAAC;SACF,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"State.js","sourceRoot":"","sources":["../../src/core/State.ts"],"names":[],"mappings":"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"}

package/dist/types/route.d.ts

@@ -50,12 +50,10 @@ export interface TransitionSpec<TContext = unknown> {
 }
 /**
  * Result of a transition operation
+ * Combines state reference with the ability to chain transitions
  */
-export interface TransitionResult<TContext = unknown> {
-    /** The target state after transition */
-    target: StateRef & {
-        /** Allow chaining transitions */
-        transitionTo: (spec: TransitionSpec<TContext>, condition?: string) => TransitionResult<TContext>;
-    };
+export interface TransitionResult<TContext = unknown> extends StateRef {
+    /** Allow chaining transitions */
+    transitionTo: (spec: TransitionSpec<TContext>, condition?: string) => TransitionResult<TContext>;
 }
 //# 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;AAEtC;;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;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,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;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO;IAChD,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;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO;IAClD,wCAAwC;IACxC,MAAM,EAAE,QAAQ,GAAG;QACjB,iCAAiC;QACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,KACf,gBAAgB,CAAC,QAAQ,CAAC,CAAC;KACjC,CAAC;CACH"}
+{"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;AAEtC;;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;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,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;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO;IAChD,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;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO,CAAE,SAAQ,QAAQ;IACpE,iCAAiC;IACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,KACf,gBAAgB,CAAC,QAAQ,CAAC,CAAC;CACjC"}

package/docs/API_REFERENCE.md

@@ -195,7 +195,7 @@ Represents a state within a conversation route.
 
 ##### `transitionTo(spec: TransitionSpec, condition?: string): TransitionResult`
 
-Creates a transition from this state.
+Creates a transition from this state and returns a chainable result.
 
 ```typescript
 interface TransitionSpec {
@@ -203,6 +203,30 @@ interface TransitionSpec {
   toolState?: ToolRef; // Transition to execute a tool
   state?: StateRef | symbol; // Transition to specific state or END_ROUTE
 }
+
+interface TransitionResult {
+  id: string; // State identifier
+  routeId: string; // Route identifier
+  transitionTo: (spec: TransitionSpec, condition?: string) => TransitionResult;
+}
+```
+
+**Returns:** A `TransitionResult` that includes the target state's reference (`id`, `routeId`) and a `transitionTo` method for chaining additional transitions.
+
+**Example:**
+
+```typescript
+const t0 = route.initialState.transitionTo({
+  chatState: "Ask for user name",
+});
+
+const t1 = t0.transitionTo({
+  chatState: "Ask for email",
+});
+
+// Access state properties
+console.log(t1.id); // State ID
+console.log(t1.routeId); // Route ID
 ```
 
 ##### `addGuideline(guideline: Guideline): void`

package/docs/GETTING_STARTED.md

@@ -159,16 +159,16 @@ const step1 = onboardingRoute.initialState.transitionTo({
   chatState: "Ask for user's name",
 });
 
-const step2 = step1.target.transitionTo({
+const step2 = step1.transitionTo({
   chatState: "Ask for user's email",
 });
 
-const step3 = step2.target.transitionTo({
+const step3 = step2.transitionTo({
   chatState: "Confirm details and welcome user",
 });
 
 // End the route
-step3.target.transitionTo({ state: END_ROUTE });
+step3.transitionTo({ state: END_ROUTE });
 ```
 
 ### Handle Context Dynamically

package/examples/healthcare-agent.ts

@@ -107,54 +107,54 @@ async function createHealthcareAgent() {
     chatState: "Determine the reason for the visit",
   });
 
-  const t1 = t0.target.transitionTo({
+  const t1 = t0.transitionTo({
     toolState: getUpcomingSlots,
   });
 
-  const t2 = t1.target.transitionTo({
+  const t2 = t1.transitionTo({
     chatState: "List available times and ask which ones works for them",
   });
 
-  const t3 = t2.target.transitionTo(
+  const t3 = t2.transitionTo(
     {
       chatState: "Confirm the details with the patient before scheduling",
     },
     "The patient picks a time"
   );
 
-  const t4 = t3.target.transitionTo(
+  const t4 = t3.transitionTo(
     {
       toolState: scheduleAppointment,
     },
     "The patient confirms the details"
   );
 
-  const t5 = t4.target.transitionTo({
+  const t5 = t4.transitionTo({
     chatState: "Confirm the appointment has been scheduled",
   });
 
-  t5.target.transitionTo({ state: END_ROUTE });
+  t5.transitionTo({ state: END_ROUTE });
 
   // Alternative path: no times work
-  const t6 = t2.target.transitionTo(
+  const t6 = t2.transitionTo(
     {
       toolState: getLaterSlots,
     },
     "None of those times work for the patient"
   );
 
-  const t7 = t6.target.transitionTo({
+  const t7 = t6.transitionTo({
     chatState: "List later times and ask if any of them works",
   });
 
-  t7.target.transitionTo(
+  t7.transitionTo(
     {
-      state: t3.target,
+      state: t3,
     },
     "The patient picks a time"
   );
 
-  const t8 = t7.target.transitionTo(
+  const t8 = t7.transitionTo(
     {
       chatState:
         "Ask the patient to call the office to schedule an appointment",
@@ -162,7 +162,7 @@ async function createHealthcareAgent() {
     "None of those times work for the patient either"
   );
 
-  t8.target.transitionTo({ state: END_ROUTE });
+  t8.transitionTo({ state: END_ROUTE });
 
   schedulingRoute.createGuideline({
     condition: "The patient says their visit is urgent",
@@ -180,7 +180,7 @@ async function createHealthcareAgent() {
     toolState: getLabResults,
   });
 
-  l0.target.transitionTo(
+  l0.transitionTo(
     {
       chatState:
         "Tell the patient that the results are not available yet, and to try again later",
@@ -188,7 +188,7 @@ async function createHealthcareAgent() {
     "The lab results could not be found"
   );
 
-  l0.target.transitionTo(
+  l0.transitionTo(
     {
       chatState:
         "Explain the lab results to the patient - that they are normal",
@@ -196,7 +196,7 @@ async function createHealthcareAgent() {
     "The lab results are good - i.e., nothing to worry about"
   );
 
-  l0.target.transitionTo(
+  l0.transitionTo(
     {
       chatState:
         "Present the results and ask them to call the office for clarifications on the results as you are not a doctor",

package/examples/openai-agent.ts

@@ -108,12 +108,12 @@ async function main() {
     chatState: "Ask which city they want weather for",
   });
 
-  const fetchWeather = askLocation.target.transitionTo({
+  const fetchWeather = askLocation.transitionTo({
     toolState: getWeather,
     condition: "User provides a city name",
   });
 
-  const showWeather = fetchWeather.target.transitionTo({
+  const showWeather = fetchWeather.transitionTo({
     chatState:
       "Present the weather information in a friendly way with temperature and condition",
   });

package/examples/persistent-onboarding.ts

@@ -243,34 +243,34 @@ async function createPersistentOnboardingAgent(sessionId: string) {
     chatState: "Ask for business name and a brief description",
   });
 
-  const saveBusinessStep = askBusinessInfo.target.transitionTo({
+  const saveBusinessStep = askBusinessInfo.transitionTo({
     toolState: saveBusinessInfo,
   });
 
   // Step 2: Collect industry
-  const askIndustry = saveBusinessStep.target.transitionTo({
+  const askIndustry = saveBusinessStep.transitionTo({
     chatState: "Ask what industry the business operates in",
   });
 
-  const saveIndustryStep = askIndustry.target.transitionTo({
+  const saveIndustryStep = askIndustry.transitionTo({
     toolState: saveIndustry,
   });
 
   // Step 3: Collect contact
-  const askContact = saveIndustryStep.target.transitionTo({
+  const askContact = saveIndustryStep.transitionTo({
     chatState: "Ask for their contact email",
   });
 
-  const saveContactStep = askContact.target.transitionTo({
+  const saveContactStep = askContact.transitionTo({
     toolState: saveContactEmail,
   });
 
   // Step 4: Confirmation
-  const confirm = saveContactStep.target.transitionTo({
+  const confirm = saveContactStep.transitionTo({
     chatState: "Summarize all collected information and ask for confirmation",
   });
 
-  confirm.target.transitionTo({ state: END_ROUTE });
+  confirm.transitionTo({ state: END_ROUTE });
 
   // Guidelines
   onboardingRoute.createGuideline({

package/examples/travel-agent.ts

@@ -162,20 +162,20 @@ async function createTravelAgent() {
     chatState: "Ask about the destination",
   });
 
-  const t1 = t0.target.transitionTo({
+  const t1 = t0.transitionTo({
     chatState: "Ask about preferred travel dates",
   });
 
-  const t2 = t1.target.transitionTo({
+  const t2 = t1.transitionTo({
     toolState: getAvailableFlights,
   });
 
-  const t3 = t2.target.transitionTo({
+  const t3 = t2.transitionTo({
     chatState: "Present available flights and ask which one works for them",
   });
 
   // Happy path: customer selects a flight
-  const t4 = t3.target.transitionTo(
+  const t4 = t3.transitionTo(
     {
       chatState:
         "Collect passenger information and confirm booking details before proceeding",
@@ -183,41 +183,41 @@ async function createTravelAgent() {
     "The customer selects a flight"
   );
 
-  const t5 = t4.target.transitionTo(
+  const t5 = t4.transitionTo(
     {
       toolState: bookFlight,
     },
     "The customer confirms the booking details"
   );
 
-  const t6 = t5.target.transitionTo({
+  const t6 = t5.transitionTo({
     chatState: "Provide confirmation number and booking summary",
   });
 
-  t6.target.transitionTo({ state: END_ROUTE });
+  t6.transitionTo({ state: END_ROUTE });
 
   // Alternative path: no flights work
-  const t7 = t3.target.transitionTo(
+  const t7 = t3.transitionTo(
     {
       toolState: getAlternativeFlights,
     },
     "None of the flights work for the customer"
   );
 
-  const t8 = t7.target.transitionTo({
+  const t8 = t7.transitionTo({
     chatState: "Present alternative flights and ask if any work",
   });
 
   // Link back to happy path
-  t8.target.transitionTo(
+  t8.transitionTo(
     {
-      state: t4.target,
+      state: t4,
     },
     "The customer selects a flight"
   );
 
   // No alternative flights work either
-  const t9 = t8.target.transitionTo(
+  const t9 = t8.transitionTo(
     {
       chatState:
         "Suggest calling our office or visiting our website for more options",
@@ -225,7 +225,7 @@ async function createTravelAgent() {
     "None of the alternative flights work either"
   );
 
-  t9.target.transitionTo({ state: END_ROUTE });
+  t9.transitionTo({ state: END_ROUTE });
 
   // Add route-specific guidelines
   flightBookingRoute.createGuideline({
@@ -253,11 +253,11 @@ async function createTravelAgent() {
     chatState: "Ask for the confirmation number or booking reference",
   });
 
-  const s1 = s0.target.transitionTo({
+  const s1 = s0.transitionTo({
     toolState: getBookingStatus,
   });
 
-  s1.target.transitionTo(
+  s1.transitionTo(
     {
       chatState:
         "Tell the customer that the booking could not be found and ask them to verify the confirmation number or call the office",
@@ -265,7 +265,7 @@ async function createTravelAgent() {
     "The booking could not be found"
   );
 
-  s1.target.transitionTo(
+  s1.transitionTo(
     {
       chatState:
         "Provide the booking details and confirm everything is in order",
@@ -273,7 +273,7 @@ async function createTravelAgent() {
     "The booking is confirmed and all details are correct"
   );
 
-  s1.target.transitionTo(
+  s1.transitionTo(
     {
       chatState:
         "Present the booking information and mention any issues or pending actions required",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/State.ts

@@ -35,7 +35,7 @@ export class State<TContext = unknown> {
    *
    * @param spec - Transition specification (chatState, toolState, or direct state)
    * @param condition - Optional condition for this transition
-   * @returns Object with target state that supports chaining
+   * @returns TransitionResult that supports chaining
    */
   transitionTo(
     spec: TransitionSpec<TContext>,
@@ -55,9 +55,7 @@ export class State<TContext = unknown> {
       this.transitions.push(endTransition);
 
       // Return a terminal state reference
-      return {
-        target: this.createTerminalRef(),
-      };
+      return this.createTerminalRef();
     }
 
     // Handle direct state reference
@@ -69,9 +67,7 @@ export class State<TContext = unknown> {
       );
       this.transitions.push(transition);
 
-      return {
-        target: this.createStateRefWithTransition(spec.state),
-      };
+      return this.createStateRefWithTransition(spec.state);
     }
 
     // Create new target state for chatState or toolState
@@ -81,12 +77,7 @@ export class State<TContext = unknown> {
 
     this.transitions.push(transition);
 
-    return {
-      target: this.createStateRefWithTransition(
-        targetState.getRef(),
-        targetState
-      ),
-    };
+    return this.createStateRefWithTransition(targetState.getRef(), targetState);
   }
 
   /**
@@ -126,12 +117,7 @@ export class State<TContext = unknown> {
   private createStateRefWithTransition(
     ref: StateRef,
     state?: State<TContext>
-  ): StateRef & {
-    transitionTo: (
-      spec: TransitionSpec<TContext>,
-      condition?: string
-    ) => TransitionResult<TContext>;
-  } {
+  ): TransitionResult<TContext> {
     const stateInstance = state || this;
 
     return {
@@ -144,12 +130,7 @@ export class State<TContext = unknown> {
   /**
    * Create a terminal state reference (for END_ROUTE)
    */
-  private createTerminalRef(): StateRef & {
-    transitionTo: (
-      spec: TransitionSpec<TContext>,
-      condition?: string
-    ) => TransitionResult<TContext>;
-  } {
+  private createTerminalRef(): TransitionResult<TContext> {
     const terminalRef: StateRef = {
       id: "END",
       routeId: this.routeId,

package/src/types/route.ts

@@ -58,14 +58,12 @@ export interface TransitionSpec<TContext = unknown> {
 
 /**
  * Result of a transition operation
+ * Combines state reference with the ability to chain transitions
  */
-export interface TransitionResult<TContext = unknown> {
-  /** The target state after transition */
-  target: StateRef & {
-    /** Allow chaining transitions */
-    transitionTo: (
-      spec: TransitionSpec<TContext>,
-      condition?: string
-    ) => TransitionResult<TContext>;
-  };
+export interface TransitionResult<TContext = unknown> extends StateRef {
+  /** Allow chaining transitions */
+  transitionTo: (
+    spec: TransitionSpec<TContext>,
+    condition?: string
+  ) => TransitionResult<TContext>;
 }