@falai/agent 0.2.0 → 0.3.10

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

package/dist/types/route.d.ts

@@ -36,6 +36,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[];
 }
 /**
  * Specification for a state transition
@@ -50,12 +56,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;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;CACzB;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

@@ -40,9 +40,17 @@ Adds an agent capability. Returns `this` for chaining.
 
 Creates an observation for disambiguation.
 
-##### `addDomain<TName, TDomain>(name: TName, domainObject: TDomain): this`
+##### `addDomain<TName, TDomain>(name: TName, domainObject: TDomain): void`
 
-Registers a domain with tools/methods. Returns `this` for chaining.
+Registers a domain with tools/methods.
+
+##### `getDomainsForRoute(routeId: string): Record<string, Record<string, unknown>>`
+
+Gets allowed domains for a specific route by ID. Returns filtered domains based on route's `domains` property, or all domains if route has no restrictions.
+
+##### `getDomainsForRouteByTitle(routeTitle: string): Record<string, Record<string, unknown>>`
+
+Gets allowed domains for a specific route by title. Returns filtered domains based on route's `domains` property, or all domains if route has no restrictions.
 
 ##### `respond(input: RespondInput<TContext>): Promise<RespondOutput>`
 
@@ -136,6 +144,9 @@ interface RouteOptions {
   description?: string;     // Route description
   conditions?: string[];    // Conditions that activate this route
   guidelines?: Guideline[]; // Initial guidelines for this route
+  domains?: string[];       // Domain names allowed in this route (undefined = all domains)
+  rules?: string[];         // Absolute rules the agent MUST follow in this route
+  prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do in this route
 }
 ```
 
@@ -151,6 +162,18 @@ Adds a guideline specific to this route. Returns `this` for chaining.
 
 Returns all guidelines for this route.
 
+##### `getDomains(): string[] | undefined`
+
+Returns allowed domain names for this route. Returns `undefined` if all domains are allowed, or an array of domain names if restricted.
+
+##### `getRules(): string[]`
+
+Returns the rules that must be followed in this route.
+
+##### `getProhibitions(): string[]`
+
+Returns the prohibitions that must never be done in this route.
+
 ##### `getRef(): RouteRef`
 
 Returns a reference to this route.
@@ -195,7 +218,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 +226,52 @@ 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
+// Approach 1: Step-by-step (ideal for complex flows with branching)
+const t0 = route.initialState.transitionTo({
+  chatState: "Ask for user name",
+});
+
+const t1 = t0.transitionTo({
+  chatState: "Ask for email",
+});
+
+const t2 = t1.transitionTo({
+  chatState: "Confirm details",
+});
+
+// Access state properties
+console.log(t1.id); // State ID
+console.log(t1.routeId); // Route ID
+
+// Use saved references for branching
+t1.transitionTo(
+  { chatState: "Handle invalid email" },
+  "Email validation failed"
+);
+
+// Approach 2: Fluent chaining (elegant for linear flows)
+route.initialState
+  .transitionTo({ chatState: "Ask for user name" })
+  .transitionTo({ chatState: "Ask for email" })
+  .transitionTo({ chatState: "Confirm details" })
+  .transitionTo({ state: END_ROUTE });
+
+// Both approaches are equivalent - choose based on your needs:
+// - Use step-by-step for complex flows with conditional branches
+// - Use chaining for simple linear flows for conciseness
 ```
 
 ##### `addGuideline(guideline: Guideline): void`
@@ -265,6 +334,58 @@ Observation description (readonly).
 
 ---
 
+### `DomainRegistry`
+
+Registry for organizing agent tools and methods by domain.
+
+#### Methods
+
+##### `register<TDomain>(name: string, domain: TDomain): void`
+
+Registers a new domain with its tools/methods. Throws error if domain name already exists.
+
+##### `get<TDomain>(name: string): TDomain | undefined`
+
+Gets a registered domain by name. Returns `undefined` if not found.
+
+##### `has(name: string): boolean`
+
+Checks if a domain is registered.
+
+##### `all(): Record<string, Record<string, unknown>>`
+
+Returns all registered domains as a single object.
+
+##### `getFiltered(allowedNames?: string[]): Record<string, Record<string, unknown>>`
+
+Returns filtered domains by names. If `allowedNames` is `undefined`, returns all domains.
+
+**Example:**
+
+```typescript
+const registry = new DomainRegistry();
+
+registry.register("payment", {
+  processPayment: async (amount: number) => { /* ... */ },
+});
+
+registry.register("shipping", {
+  calculateShipping: (zipCode: string) => { /* ... */ },
+});
+
+// Get specific domains
+const filtered = registry.getFiltered(["payment"]); // Only payment domain
+
+// Get all domains
+const all = registry.getFiltered(); // payment + shipping
+```
+
+##### `getDomainNames(): string[]`
+
+Returns list of all registered domain names.
+
+---
+
 ### `GeminiProvider`
 
 AI provider implementation for Google Gemini.

package/docs/CONSTRUCTOR_OPTIONS.md

@@ -41,48 +41,48 @@ interface AgentOptions<TContext = unknown> {
 
 ```typescript
 const agent = new Agent({
-  name: "SupportBot",
-  description: "Helpful customer support",
-  goal: "Resolve issues efficiently",
-  ai: new GeminiProvider({ apiKey: "...", model: "..." }),
-  context: { userId: "123" },
+  name: 'SupportBot',
+  description: 'Helpful customer support',
+  goal: 'Resolve issues efficiently',
+  ai: new GeminiProvider({ apiKey: '...', model: '...' }),
+  context: { userId: '123' },
 
   terms: [
     {
-      name: "SLA",
-      description: "Service Level Agreement",
-      synonyms: ["response time"],
+      name: 'SLA',
+      description: 'Service Level Agreement',
+      synonyms: ['response time'],
     },
   ],
 
   guidelines: [
     {
-      condition: "User is frustrated",
-      action: "Show empathy and offer escalation",
-      tags: ["support"],
+      condition: 'User is frustrated',
+      action: 'Show empathy and offer escalation',
+      tags: ['support'],
       enabled: true,
     },
   ],
 
   capabilities: [
-    { title: "Ticket Management", description: "Create and track tickets" },
+    { title: 'Ticket Management', description: 'Create and track tickets' },
   ],
 
   routes: [
     {
-      title: "Create Ticket",
-      description: "Help user create a support ticket",
-      conditions: ["User wants to report an issue"],
+      title: 'Create Ticket',
+      description: 'Help user create a support ticket',
+      conditions: ['User wants to report an issue'],
       guidelines: [
-        { condition: "Issue is urgent", action: "Prioritize immediately" },
+        { condition: 'Issue is urgent', action: 'Prioritize immediately' },
       ],
     },
   ],
 
   observations: [
     {
-      description: "User mentions problem but unclear what kind",
-      routeRefs: ["Create Ticket", "Check Ticket Status"], // By title!
+      description: 'User mentions problem but unclear what kind',
+      routeRefs: ['Create Ticket', 'Check Ticket Status'], // By title!
     },
   ],
 });
@@ -98,33 +98,49 @@ interface RouteOptions {
   title: string;
 
   // Optional
+  id?: string;              // Custom ID (auto-generated from title if not provided)
   description?: string;
   conditions?: string[];
-  guidelines?: Guideline[]; // NEW!
+  guidelines?: Guideline[];
+  domains?: string[];       // Restrict which domains are available in this route
+  rules?: string[];         // Absolute rules the agent MUST follow
+  prohibitions?: string[];  // Absolute prohibitions the agent MUST NEVER do
 }
 ```
 
+**Domain Scoping:**
+- Use `domains` to limit which registered domains (tools/methods) can be accessed during this route
+- If `undefined` or omitted, all registered domains are available
+- Useful for security (preventing unauthorized tool calls) and performance (reducing AI decision space)
+
+**Rules & Prohibitions:**
+- **Rules**: Absolute requirements the agent must follow in this route (style, format, behavior)
+- **Prohibitions**: Things the agent must never do in this route
+- These override general guidelines if there's any conflict
+- Applied automatically when the route is active
+- Perfect for controlling message style, tone, length, emoji usage, etc.
+
 ### Example: Route with Nested Guidelines
 
 ```typescript
 const agent = new Agent({
-  name: "Bot",
+  name: 'Bot',
   ai: provider,
   routes: [
     {
-      title: "Onboarding",
-      description: "Guide new users",
-      conditions: ["User is new"],
+      title: 'Onboarding',
+      description: 'Guide new users',
+      conditions: ['User is new'],
       guidelines: [
         {
-          condition: "User skips a step",
+          condition: 'User skips a step',
           action: "Gently remind them it's important",
-          tags: ["onboarding"],
+          tags: ['onboarding'],
         },
         {
-          condition: "User seems confused",
-          action: "Offer a quick tutorial video",
-          tags: ["help"],
+          condition: 'User seems confused',
+          action: 'Offer a quick tutorial video',
+          tags: ['help'],
         },
       ],
     },
@@ -132,6 +148,131 @@ const agent = new Agent({
 });
 ```
 
+### Example: Route with Domain Scoping
+
+```typescript
+// Register domains
+agent.addDomain('scraping', {
+  scrapeSite: async (url: string) => {
+    /* ... */
+  },
+  extractData: async (html: string) => {
+    /* ... */
+  },
+});
+
+agent.addDomain('calendar', {
+  scheduleEvent: async (date: Date, title: string) => {
+    /* ... */
+  },
+  listEvents: async () => {
+    /* ... */
+  },
+});
+
+agent.addDomain('payment', {
+  processPayment: async (amount: number) => {
+    /* ... */
+  },
+});
+
+// Create routes with domain restrictions
+agent.createRoute({
+  title: 'Data Collection',
+  description: 'Collect and process web data',
+  domains: ['scraping'], // ✅ Only scraping tools available
+});
+
+agent.createRoute({
+  title: 'Schedule Meeting',
+  description: 'Book appointments',
+  domains: ['calendar'], // ✅ Only calendar tools available
+});
+
+agent.createRoute({
+  title: 'Checkout',
+  description: 'Process purchase',
+  domains: ['payment', 'calendar'], // ✅ Multiple domains allowed
+});
+
+agent.createRoute({
+  title: 'FAQ Support',
+  description: 'Answer general questions',
+  domains: [], // ✅ No tools available (conversation only)
+});
+
+agent.createRoute({
+  title: 'Admin Support',
+  description: 'Administrative tasks',
+  // domains not specified = all domains available (for demo purposes)
+});
+```
+
+### Example: Route with Rules & Prohibitions
+
+```typescript
+// WhatsApp support bot with different styles per route
+agent.createRoute({
+  title: 'Customer Support',
+  description: 'Help customers with issues',
+  domains: [],
+  rules: [
+    'Keep messages short (maximum 2 lines per message)',
+    'Use maximum 1 emoji per message',
+    'Always ask if the issue is resolved before ending',
+    'Professional but friendly tone'
+  ],
+  prohibitions: [
+    'Never send messages longer than 3 paragraphs',
+    'Do not use slang or informal language',
+    'Never promise what you cannot deliver',
+    'Do not ask for sensitive information via chat'
+  ]
+});
+
+agent.createRoute({
+  title: 'Sales Consultation',
+  description: 'Help customer discover needs and present solutions',
+  domains: ['calendar', 'analytics'],
+  rules: [
+    'Ask open-ended questions to discover needs',
+    'Use storytelling when presenting solutions',
+    'Emoji only to reinforce positive emotions 😊',
+    'Always present value before mentioning price'
+  ],
+  prohibitions: [
+    'Never talk about price before showing value',
+    'Do not pressure the customer',
+    'Avoid complex technical terms',
+    'Never send more than 2 messages in a row without customer response'
+  ]
+});
+
+agent.createRoute({
+  title: 'Emergency Support',
+  description: 'Handle urgent customer issues',
+  domains: ['notifications', 'ticketing'],
+  rules: [
+    'Respond immediately and acknowledge urgency',
+    'Use clear, direct language',
+    'Provide concrete next steps',
+    'Set clear expectations on resolution time'
+  ],
+  prohibitions: [
+    'Never downplay the customer\'s concern',
+    'Do not use emojis',
+    'Never say "calm down" or similar phrases',
+    'Do not transfer without explaining why'
+  ]
+});
+```
+
+**How it works:**
+- Rules and prohibitions are automatically applied when the route is active
+- They override general guidelines if there's any conflict
+- Perfect for controlling communication style per context
+- Applied in the AI prompt to ensure compliance
+
 ---
 
 ## 🔍 Observation Options
@@ -175,14 +316,14 @@ All constructor options also have fluent methods that **return `this`** for chai
 
 ```typescript
 agent
-  .createTerm({ name: "API", description: "..." })
-  .createGuideline({ condition: "...", action: "..." })
-  .createCapability({ title: "...", description: "..." });
+  .createTerm({ name: 'API', description: '...' })
+  .createGuideline({ condition: '...', action: '...' })
+  .createCapability({ title: '...', description: '...' });
 
-const route = agent.createRoute({ title: "..." });
-route.createGuideline({ condition: "...", action: "..." });
+const route = agent.createRoute({ title: '...' });
+route.createGuideline({ condition: '...', action: '...' });
 
-const obs = agent.createObservation("User intent unclear");
+const obs = agent.createObservation('User intent unclear');
 obs.disambiguate([route1, route2]);
 ```
 
@@ -209,7 +350,7 @@ obs.disambiguate([route1, route2]);
 ```typescript
 // Start with static config
 const agent = new Agent({
-  name: "Bot",
+  name: 'Bot',
   ai: provider,
   terms: loadTermsFromFile(),
   guidelines: loadGuidelinesFromDB(),
@@ -218,8 +359,8 @@ const agent = new Agent({
 // Add dynamic features
 if (user.isPremium) {
   agent.createGuideline({
-    condition: "User asks for priority support",
-    action: "Escalate immediately to premium team",
+    condition: 'User asks for priority support',
+    action: 'Escalate immediately to premium team',
   });
 }
 ```

package/docs/GETTING_STARTED.md

@@ -154,21 +154,29 @@ const onboardingRoute = agent.createRoute({
   conditions: ["User is new and needs onboarding"],
 });
 
-// Build the flow
+// Build the flow - two approaches:
+
+// Approach 1: Step-by-step (great for complex flows with branching)
 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 });
+
+// Approach 2: Fluent chaining (concise for linear flows)
+onboardingRoute.initialState
+  .transitionTo({ chatState: "Ask for user's name" })
+  .transitionTo({ chatState: "Ask for user's email" })
+  .transitionTo({ chatState: "Confirm details and welcome user" })
+  .transitionTo({ state: END_ROUTE });
 ```
 
 ### Handle Context Dynamically