@falai/agent 0.2.0 → 0.3.10

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.10",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/Agent.ts

@@ -295,17 +295,26 @@ export class Agent<TContext = unknown> {
       }
     }
 
-    // Add active routes
+    // Add active routes with their rules and prohibitions
     if (this.routes.length > 0) {
       promptBuilder.addActiveRoutes(
         this.routes.map((r) => ({
           title: r.title,
           description: r.description,
           conditions: r.conditions,
+          domains: r.getDomains(),
+          rules: r.getRules(),
+          prohibitions: r.getProhibitions(),
         }))
       );
     }
 
+    // Add domains (tools) information if any domains are registered
+    const allDomains = this.domainRegistry.all();
+    if (Object.keys(allDomains).length > 0) {
+      promptBuilder.addDomains(allDomains);
+    }
+
     // Add JSON response schema instructions
     promptBuilder.addJsonResponseSchema();
 
@@ -414,4 +423,40 @@ export class Agent<TContext = unknown> {
   getDomainRegistry(): DomainRegistry {
     return this.domainRegistry;
   }
+
+  /**
+   * Get allowed domains for a specific route
+   * @param routeId - Route ID to check
+   * @returns Filtered domains object, or all domains if route has no restrictions
+   */
+  getDomainsForRoute(routeId: string): Record<string, Record<string, unknown>> {
+    const route = this.routes.find((r) => r.id === routeId);
+
+    if (!route) {
+      // Route not found, return all domains
+      return this.domainRegistry.all();
+    }
+
+    const allowedDomains = route.getDomains();
+    return this.domainRegistry.getFiltered(allowedDomains);
+  }
+
+  /**
+   * Get allowed domains for a specific route by title
+   * @param routeTitle - Route title to check
+   * @returns Filtered domains object, or all domains if route has no restrictions
+   */
+  getDomainsForRouteByTitle(
+    routeTitle: string
+  ): Record<string, Record<string, unknown>> {
+    const route = this.routes.find((r) => r.title === routeTitle);
+
+    if (!route) {
+      // Route not found, return all domains
+      return this.domainRegistry.all();
+    }
+
+    const allowedDomains = route.getDomains();
+    return this.domainRegistry.getFiltered(allowedDomains);
+  }
 }

package/src/core/DomainRegistry.ts

@@ -47,4 +47,34 @@ export class DomainRegistry {
     }
     return result;
   }
+
+  /**
+   * Get filtered domains by names
+   * @param allowedNames - Array of domain names to include (undefined = all domains)
+   * @returns Object with only the specified domains
+   */
+  getFiltered(
+    allowedNames?: string[]
+  ): Record<string, Record<string, unknown>> {
+    // If no filter specified, return all domains
+    if (!allowedNames) {
+      return this.all();
+    }
+
+    const result: Record<string, Record<string, unknown>> = {};
+    for (const name of allowedNames) {
+      const domain = this.domains.get(name);
+      if (domain) {
+        result[name] = domain;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Get list of all registered domain names
+   */
+  getDomainNames(): string[] {
+    return Array.from(this.domains.keys());
+  }
 }

package/src/core/PromptBuilder.ts

@@ -26,6 +26,7 @@ export enum BuiltInSection {
   OBSERVATIONS = "observations",
   CAPABILITIES = "capabilities",
   ACTIVE_ROUTES = "active_routes",
+  DOMAINS = "domains",
 }
 
 /**
@@ -431,7 +432,14 @@ When you detect any of these situations, consider which route would be most appr
    * Add active routes information
    */
   addActiveRoutes(
-    routes: Array<{ title: string; description?: string; conditions: string[] }>
+    routes: Array<{
+      title: string;
+      description?: string;
+      conditions: string[];
+      domains?: string[];
+      rules?: string[];
+      prohibitions?: string[];
+    }>
   ): this {
     if (routes.length > 0) {
       const routesString = routes
@@ -441,7 +449,29 @@ When you detect any of these situations, consider which route would be most appr
               ? `\n  Triggered when: ${route.conditions.join(" OR ")}`
               : "";
           const desc = route.description ? `\n  ${route.description}` : "";
-          return `${i + 1}) ${route.title}${desc}${conditions}`;
+          
+          let domainInfo = "";
+          if (route.domains !== undefined) {
+            if (route.domains.length === 0) {
+              domainInfo = "\n  Available tools: None (conversation only)";
+            } else {
+              domainInfo = `\n  Available tools: ${route.domains.join(", ")}`;
+            }
+          }
+
+          let rulesInfo = "";
+          if (route.rules && route.rules.length > 0) {
+            const rulesList = route.rules.map((r, idx) => `${idx + 1}. ${r}`).join("; ");
+            rulesInfo = `\n  RULES: ${rulesList}`;
+          }
+
+          let prohibitionsInfo = "";
+          if (route.prohibitions && route.prohibitions.length > 0) {
+            const prohibitionsList = route.prohibitions.map((p, idx) => `${idx + 1}. ${p}`).join("; ");
+            prohibitionsInfo = `\n  PROHIBITIONS: ${prohibitionsList}`;
+          }
+
+          return `${i + 1}) ${route.title}${desc}${conditions}${domainInfo}${rulesInfo}${prohibitionsInfo}`;
         })
         .join("\n\n");
 
@@ -452,7 +482,11 @@ When you detect any of these situations, consider which route would be most appr
 {routes_string}
 ###
 
-These routes represent different paths the conversation can take. Choose the most appropriate route based on the user's needs.`,
+These routes represent different paths the conversation can take. Choose the most appropriate route based on the user's needs.
+IMPORTANT: 
+- If a route specifies available tools, you can ONLY call tools from those domains when following that route.
+- If a route has RULES, you MUST follow them when you choose that route.
+- If a route has PROHIBITIONS, you MUST NEVER do those things when you choose that route.`,
         { routes_string: routesString },
         SectionStatus.ACTIVE
       );
@@ -460,6 +494,39 @@ These routes represent different paths the conversation can take. Choose the mos
     return this;
   }
 
+  /**
+   * Add domains (tools) information
+   */
+  addDomains(
+    domains: Record<string, Record<string, unknown>>
+  ): this {
+    const domainNames = Object.keys(domains);
+    if (domainNames.length > 0) {
+      const domainsString = domainNames
+        .map((name, i) => {
+          const toolNames = Object.keys(domains[name]);
+          const tools = toolNames.join(", ");
+          return `${i + 1}) Domain "${name}": ${tools}`;
+        })
+        .join("\n");
+
+      this.addSection(
+        BuiltInSection.DOMAINS,
+        `Available tool domains:
+###
+{domains_string}
+###
+
+These are the tool domains registered in the system. Each domain contains specific tools/methods.
+When calling tools, use the format: domain.toolName (e.g., "payment.processPayment").`,
+        { domains_string: domainsString },
+        SectionStatus.ACTIVE
+      );
+    }
+    return this;
+  }
+
+
   /**
    * Add JSON response schema instructions
    */

package/src/core/Route.ts

@@ -16,6 +16,9 @@ export class Route<TContext = unknown> {
   public readonly title: string;
   public readonly description?: string;
   public readonly conditions: string[];
+  public readonly domains?: string[];
+  public readonly rules: string[];
+  public readonly prohibitions: string[];
   public readonly initialState: State<TContext>;
   private guidelines: Guideline[] = [];
 
@@ -25,6 +28,9 @@ export class Route<TContext = unknown> {
     this.title = options.title;
     this.description = options.description;
     this.conditions = options.conditions || [];
+    this.domains = options.domains;
+    this.rules = options.rules || ([] as string[]);
+    this.prohibitions = options.prohibitions || ([] as string[]);
     this.initialState = new State<TContext>(this.id, "Initial state");
 
     // Initialize guidelines from options
@@ -54,6 +60,28 @@ export class Route<TContext = unknown> {
     return [...this.guidelines];
   }
 
+  /**
+   * Get allowed domain names for this route
+   * @returns Array of domain names, or undefined if all domains are allowed
+   */
+  getDomains(): string[] | undefined {
+    return this.domains ? [...this.domains] : undefined;
+  }
+
+  /**
+   * Get rules for this route
+   */
+  getRules(): string[] {
+    return [...this.rules];
+  }
+
+  /**
+   * Get prohibitions for this route
+   */
+  getProhibitions(): string[] {
+    return [...this.prohibitions];
+  }
+
   /**
    * Get route reference
    */

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

@@ -41,6 +41,12 @@ export interface RouteOptions {
   conditions?: string[];
   /** Initial guidelines for this route */
   guidelines?: Guideline[];
+  /** Domain names that are allowed in this route (undefined = all domains) */
+  domains?: string[];
+  /** Absolute rules the agent must follow in this route */
+  rules?: string[];
+  /** Absolute prohibitions the agent must never do in this route */
+  prohibitions?: string[];
 }
 
 /**
@@ -58,14 +64,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>;
 }