@falai/agent 0.3.0 → 0.3.10

package/examples/domain-scoping.ts

@@ -0,0 +1,266 @@
+/**
+ * Domain Scoping Example
+ *
+ * This example demonstrates how to use domain scoping to restrict which tools
+ * are available in different conversation routes for security and clarity.
+ */
+
+import { Agent, createMessageEvent, EventSource } from "../src/index";
+import { GeminiProvider } from "../src/providers/GeminiProvider";
+
+// Initialize AI provider
+const ai = new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY || "your-api-key-here",
+  model: "gemini-2.0-flash-exp",
+});
+
+// Create agent
+const agent = new Agent({
+  name: "Multi-Domain Assistant",
+  description:
+    "An assistant that handles different tasks with domain-scoped tools",
+  ai,
+});
+
+// Register different domains with their tools
+agent.addDomain("scraping", {
+  scrapeSite: async (url: string) => {
+    console.log(`[Scraping] Scraping site: ${url}`);
+    return { success: true, data: "Scraped content..." };
+  },
+  extractData: async (html: string, selector: string) => {
+    console.log(`[Scraping] Extracting data with selector: ${selector}`);
+    return { elements: [] };
+  },
+});
+
+agent.addDomain("calendar", {
+  scheduleEvent: async (date: Date, title: string, description?: string) => {
+    console.log(`[Calendar] Scheduling event: ${title} on ${date}`);
+    return { eventId: "evt_123", success: true };
+  },
+  listEvents: async (startDate: Date, endDate: Date) => {
+    console.log(`[Calendar] Listing events from ${startDate} to ${endDate}`);
+    return { events: [] };
+  },
+  cancelEvent: async (eventId: string) => {
+    console.log(`[Calendar] Cancelling event: ${eventId}`);
+    return { success: true };
+  },
+});
+
+agent.addDomain("payment", {
+  processPayment: async (amount: number, currency: string) => {
+    console.log(`[Payment] Processing payment: ${amount} ${currency}`);
+    return { transactionId: "txn_456", success: true };
+  },
+  refund: async (transactionId: string) => {
+    console.log(`[Payment] Processing refund for: ${transactionId}`);
+    return { success: true };
+  },
+  checkBalance: async () => {
+    console.log(`[Payment] Checking balance`);
+    return { balance: 1000, currency: "USD" };
+  },
+});
+
+agent.addDomain("analytics", {
+  trackEvent: async (
+    eventName: string,
+    properties: Record<string, unknown>
+  ) => {
+    console.log(`[Analytics] Tracking event: ${eventName}`, properties);
+    return { success: true };
+  },
+  generateReport: async (
+    reportType: string,
+    dateRange: { start: Date; end: Date }
+  ) => {
+    console.log(`[Analytics] Generating ${reportType} report`);
+    return { report: {} };
+  },
+});
+
+// Create routes with domain scoping
+agent.createRoute({
+  title: "Data Collection",
+  description: "Collect and process web data",
+  conditions: ["User wants to scrape or extract data from websites"],
+  domains: ["scraping"], // ✅ Only scraping tools available
+});
+
+agent.createRoute({
+  title: "Schedule Meeting",
+  description: "Book and manage appointments",
+  conditions: ["User wants to schedule, view, or cancel events"],
+  domains: ["calendar"], // ✅ Only calendar tools available
+});
+
+agent.createRoute({
+  title: "Checkout Process",
+  description: "Process purchases and payments",
+  conditions: ["User wants to make a purchase or payment"],
+  domains: ["payment", "analytics"], // ✅ Multiple domains allowed
+});
+
+agent.createRoute({
+  title: "Customer Support",
+  description: "Answer general questions and provide help",
+  conditions: ["User has general questions or needs support"],
+  domains: [], // ✅ No tools available (conversation only)
+});
+
+agent.createRoute({
+  title: "Admin Support",
+  description: "Administrative tasks with full access",
+  conditions: ["User is admin and needs full system access"],
+  // domains not specified = all domains available
+});
+
+// Example conversations
+async function demonstrateScoping() {
+  console.log("\n=== Domain Scoping Demo ===\n");
+
+  // Example 1: Data Collection route - only scraping tools available
+  console.log("1️⃣  Example: User wants to scrape data");
+  const history1 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Alice",
+      "Can you scrape the homepage of example.com?"
+    ),
+  ];
+
+  const response1 = await agent.respond({ history: history1 });
+  console.log(`Route chosen: ${response1.route?.title}`);
+  console.log(`Available tools in this route: scraping only`);
+  console.log(`Response: ${response1.message}\n`);
+
+  // Example 2: Schedule Meeting route - only calendar tools available
+  console.log("2️⃣  Example: User wants to schedule a meeting");
+  const history2 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Bob",
+      "Schedule a meeting for tomorrow at 2pm"
+    ),
+  ];
+
+  const response2 = await agent.respond({ history: history2 });
+  console.log(`Route chosen: ${response2.route?.title}`);
+  console.log(`Available tools in this route: calendar only`);
+  console.log(`Response: ${response2.message}\n`);
+
+  // Example 3: Customer Support route - NO tools available
+  console.log("3️⃣  Example: User has a general question");
+  const history3 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Charlie",
+      "What are your business hours?"
+    ),
+  ];
+
+  const response3 = await agent.respond({ history: history3 });
+  console.log(`Route chosen: ${response3.route?.title}`);
+  console.log(`Available tools in this route: none (conversation only)`);
+  console.log(`Response: ${response3.message}\n`);
+
+  // Example 4: Admin Support route - ALL tools available (for demo purposes)
+  console.log("4️⃣  Example: Admin needs full access");
+  const history4 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Admin",
+      "I need to generate a report and process a refund"
+    ),
+  ];
+
+  const response4 = await agent.respond({ history: history4 });
+  console.log(`Route chosen: ${response4.route?.title}`);
+  console.log(`Available tools in this route: all domains`);
+  console.log(`Response: ${response4.message}\n`);
+}
+
+// Benefits demonstration
+console.log(`
+🔒 Security Benefits:
+- Customer Support route cannot accidentally call payment.processPayment()
+- Data Collection route cannot access calendar.scheduleEvent()
+- Each route has minimum necessary permissions
+
+⚡ Performance Benefits:
+- AI only sees relevant tools for each route
+- Faster decision making with reduced context
+- Clearer intent and fewer errors
+
+🎯 Clarity Benefits:
+- Routes clearly document their capabilities
+- Easy to audit what each route can do
+- Better debugging when tools are called
+`);
+
+// Inspect route configurations
+console.log("\n📋 Route Configurations:\n");
+for (const route of agent.getRoutes()) {
+  const domains = route.getDomains();
+  const domainsText =
+    domains === undefined
+      ? "all domains"
+      : domains.length === 0
+      ? "no tools (conversation only)"
+      : domains.join(", ");
+
+  console.log(`• ${route.title}: ${domainsText}`);
+}
+
+// Validate tool calls (example helper function)
+function validateToolCall(toolName: string, routeTitle: string): boolean {
+  const route = agent.getRoutes().find((r) => r.title === routeTitle);
+  if (!route) return false;
+
+  const allowedDomains = route.getDomains();
+
+  // If undefined, all domains allowed
+  if (allowedDomains === undefined) return true;
+
+  // If empty array, no tools allowed
+  if (allowedDomains.length === 0) return false;
+
+  // Check if tool's domain is in allowed list
+  const [domain] = toolName.split(".");
+  return allowedDomains.includes(domain);
+}
+
+console.log("\n✅ Validation Examples:");
+console.log(
+  `- scraping.scrapeSite in "Data Collection": ${validateToolCall(
+    "scraping.scrapeSite",
+    "Data Collection"
+  )}`
+);
+console.log(
+  `- calendar.scheduleEvent in "Data Collection": ${validateToolCall(
+    "calendar.scheduleEvent",
+    "Data Collection"
+  )}`
+);
+console.log(
+  `- payment.processPayment in "Customer Support": ${validateToolCall(
+    "payment.processPayment",
+    "Customer Support"
+  )}`
+);
+console.log(
+  `- analytics.trackEvent in "Admin Support": ${validateToolCall(
+    "analytics.trackEvent",
+    "Admin Support"
+  )}`
+);
+
+// Run demonstration
+if (import.meta.url === `file://${process.argv[1]}`) {
+  demonstrateScoping().catch(console.error);
+}
+
+export { agent };

package/examples/rules-prohibitions.ts

@@ -0,0 +1,258 @@
+/**
+ * Rules & Prohibitions Example
+ *
+ * Demonstrates how to use rules and prohibitions to control agent behavior
+ * in different conversation routes (e.g., WhatsApp bot with different styles)
+ */
+
+import { Agent, createMessageEvent, EventSource } from "../src/index";
+import { GeminiProvider } from "../src/providers/GeminiProvider";
+
+// Initialize AI provider
+const ai = new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY || "your-api-key-here",
+  model: "gemini-2.0-flash-exp",
+});
+
+// Create WhatsApp support bot with different styles per route
+const agent = new Agent({
+  name: "SupportBot",
+  description: "Customer support assistant for WhatsApp",
+  ai,
+});
+
+// Route 1: Quick Support - Short, direct messages
+agent.createRoute({
+  title: "Quick Support",
+  description: "Fast answers for common questions",
+  conditions: ["User has a simple question", "User wants quick help"],
+  rules: [
+    "Keep messages extremely short (1-2 lines maximum)",
+    "Use bullet points for lists",
+    "Maximum 1 emoji per message 👍",
+    "Be direct and to the point",
+  ],
+  prohibitions: [
+    "Never send long paragraphs",
+    "Do not over-explain",
+    "Never use more than 2 emojis",
+    "Do not ask follow-up questions unless necessary",
+  ],
+});
+
+// Route 2: Sales Consultation - Conversational, engaging
+agent.createRoute({
+  title: "Sales Consultation",
+  description: "Help customer discover needs and present solutions",
+  conditions: [
+    "User is interested in buying",
+    "User wants product information",
+  ],
+  rules: [
+    "Ask open-ended questions to discover needs",
+    "Use storytelling when presenting solutions",
+    "Emoji to reinforce positive emotions 😊✨",
+    "Present value before mentioning price",
+    "Make customer feel special and understood",
+  ],
+  prohibitions: [
+    "Never talk about price before showing value",
+    "Do not pressure or push",
+    "Avoid technical jargon",
+    "Never send more than 2 messages without waiting for response",
+    "Do not make promises you cannot keep",
+  ],
+});
+
+// Route 3: Technical Support - Detailed, step-by-step
+agent.createRoute({
+  title: "Technical Support",
+  description: "Help with technical issues and troubleshooting",
+  conditions: ["User has technical problem", "User needs step-by-step help"],
+  rules: [
+    "Provide clear, numbered steps",
+    "Use simple language for technical concepts",
+    "Confirm understanding after each major step",
+    "Offer screenshots or visual aids when helpful",
+    "Be patient and thorough",
+  ],
+  prohibitions: [
+    "Never skip steps or assume knowledge",
+    "Do not use excessive technical terms without explanation",
+    "Never blame the user for the issue",
+    "Do not rush through explanations",
+  ],
+});
+
+// Route 4: Emergency Support - Calm, reassuring, action-oriented
+agent.createRoute({
+  title: "Emergency Support",
+  description: "Handle urgent customer issues",
+  conditions: ["Customer is frustrated", "Urgent issue", "Service down"],
+  rules: [
+    "Acknowledge the urgency immediately",
+    "Express empathy and understanding",
+    "Provide concrete next steps",
+    "Set clear expectations on resolution time",
+    "Keep customer updated",
+  ],
+  prohibitions: [
+    "Never downplay the customer's concern",
+    "Do not use emojis (keep it professional)",
+    'Never say "calm down" or similar dismissive phrases',
+    "Do not transfer without explaining why",
+    "Never make excuses or blame others",
+  ],
+});
+
+// Route 5: General Chat - Friendly, casual, helpful
+agent.createRoute({
+  title: "General Chat",
+  description: "Casual conversation and general questions",
+  conditions: ["User is just chatting", "Greeting", "General question"],
+  rules: [
+    "Be friendly and conversational",
+    "Use emojis naturally 😊",
+    "Mirror the customer's tone and energy",
+    "Keep it light and positive",
+  ],
+  prohibitions: [
+    "Do not be overly formal",
+    "Never ignore the customer's mood",
+    "Do not push products unless asked",
+  ],
+});
+
+// Demonstration function
+async function demonstrateRulesAndProhibitions() {
+  console.log("\n=== Rules & Prohibitions Demo ===\n");
+
+  // Example 1: Quick Support - Should be short and direct
+  console.log("1️⃣  Quick Support Route (short, direct)");
+  const history1 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Alice",
+      "What are your business hours?"
+    ),
+  ];
+
+  const response1 = await agent.respond({ history: history1 });
+  console.log(`Route: ${response1.route?.title}`);
+  console.log(`Response: ${response1.message}`);
+  console.log(`Expected: Short, direct, max 1 emoji\n`);
+
+  // Example 2: Sales Consultation - Should be engaging and value-focused
+  console.log("2️⃣  Sales Consultation Route (conversational, value-first)");
+  const history2 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Bob",
+      "I'm interested in your premium plan"
+    ),
+  ];
+
+  const response2 = await agent.respond({ history: history2 });
+  console.log(`Route: ${response2.route?.title}`);
+  console.log(`Response: ${response2.message}`);
+  console.log(`Expected: Ask about needs, show value before price\n`);
+
+  // Example 3: Technical Support - Should be detailed and step-by-step
+  console.log("3️⃣  Technical Support Route (detailed, step-by-step)");
+  const history3 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Charlie",
+      "My app keeps crashing when I try to login"
+    ),
+  ];
+
+  const response3 = await agent.respond({ history: history3 });
+  console.log(`Route: ${response3.route?.title}`);
+  console.log(`Response: ${response3.message}`);
+  console.log(`Expected: Clear steps, simple language, patient\n`);
+
+  // Example 4: Emergency Support - Should be calm and action-oriented
+  console.log("4️⃣  Emergency Support Route (urgent, professional)");
+  const history4 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Diana",
+      "This is urgent! My payment failed and I need access NOW!"
+    ),
+  ];
+
+  const response4 = await agent.respond({ history: history4 });
+  console.log(`Route: ${response4.route?.title}`);
+  console.log(`Response: ${response4.message}`);
+  console.log(`Expected: Acknowledge urgency, no emojis, concrete steps\n`);
+
+  // Example 5: General Chat - Should be friendly and casual
+  console.log("5️⃣  General Chat Route (friendly, casual)");
+  const history5 = [
+    createMessageEvent(EventSource.CUSTOMER, "Eve", "Hey! How's it going?"),
+  ];
+
+  const response5 = await agent.respond({ history: history5 });
+  console.log(`Route: ${response5.route?.title}`);
+  console.log(`Response: ${response5.message}`);
+  console.log(`Expected: Friendly, emojis, mirrors customer tone\n`);
+}
+
+// Inspect route configurations
+console.log("\n📋 Route Configurations:\n");
+for (const route of agent.getRoutes()) {
+  console.log(`\n🛤️  ${route.title}`);
+
+  const rules = route.getRules();
+  if (rules.length > 0) {
+    console.log(`  ✅ Rules (${rules.length}):`);
+    rules.forEach((rule, i) => console.log(`     ${i + 1}. ${rule}`));
+  }
+
+  const prohibitions = route.getProhibitions();
+  if (prohibitions.length > 0) {
+    console.log(`  ❌ Prohibitions (${prohibitions.length}):`);
+    prohibitions.forEach((prohibition, i) =>
+      console.log(`     ${i + 1}. ${prohibition}`)
+    );
+  }
+}
+
+// Benefits explanation
+console.log(`
+\n💡 Benefits of Rules & Prohibitions:
+
+1️⃣  **Context-Specific Behavior**
+   - Each route can have completely different communication styles
+   - WhatsApp support: short messages
+   - Sales: engaging, story-driven
+   - Technical: detailed, step-by-step
+
+2️⃣  **Brand Consistency**
+   - Rules ensure the agent always follows brand guidelines
+   - Prohibitions prevent off-brand behavior
+   - Different routes for different contexts
+
+3️⃣  **User Experience**
+   - Emergency route: professional, no emojis
+   - General chat: friendly, casual
+   - Technical support: patient, thorough
+
+4️⃣  **Automatic Enforcement**
+   - Rules are applied in the AI prompt automatically
+   - No manual checking needed
+   - Consistent behavior across all conversations
+
+5️⃣  **Easy to Update**
+   - Change rules without changing code
+   - A/B test different communication styles
+   - Iterate based on customer feedback
+`);
+
+// Run demonstration
+if (import.meta.url === `file://${process.argv[1]}`) {
+  demonstrateRulesAndProhibitions().catch(console.error);
+}
+
+export { agent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.3.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());
+  }
 }