@falai/agent 0.3.24 → 0.3.30

package/docs/STRUCTURE.md

@@ -3,6 +3,15 @@
 ```
 src/
 ├── types/          # Type definitions (interfaces, types, enums)
+│   ├── agent.ts           # Agent types and configuration
+│   ├── ai.ts              # AI provider interfaces
+│   ├── history.ts         # Event and message history types
+│   ├── observation.ts     # Observation and disambiguation types
+│   ├── persistence.ts     # Persistence adapter interfaces
+│   ├── prompt.ts          # Prompt building types
+│   ├── route.ts           # Route and state types
+│   ├── tool.ts            # Tool definition types
+│   └── index.ts           # Type exports
 ├── core/           # Core framework classes
 │   ├── Agent.ts           # Main agent class
 │   ├── Route.ts           # Route/Journey DSL
@@ -12,13 +21,28 @@ src/
 │   ├── Tool.ts            # Tool definitions
 │   ├── PromptBuilder.ts   # Prompt construction
 │   ├── Events.ts          # Event history
-│   └── DomainRegistry.ts  # Domain organization
+│   ├── DomainRegistry.ts  # Domain organization
+│   └── PersistenceManager.ts  # Persistence lifecycle management
 ├── providers/      # AI provider implementations
-│   └── GeminiProvider.ts  # Google Gemini AI
+│   ├── AnthropicProvider.ts   # Claude (Anthropic)
+│   ├── GeminiProvider.ts      # Google Gemini
+│   ├── OpenAIProvider.ts      # OpenAI GPT
+│   ├── OpenRouterProvider.ts  # OpenRouter (200+ models)
+│   └── index.ts               # Provider exports
+├── adapters/       # Database persistence adapters
+│   ├── MemoryAdapter.ts       # In-memory (testing/dev)
+│   ├── PrismaAdapter.ts       # Prisma ORM
+│   ├── RedisAdapter.ts        # Redis
+│   ├── MongoAdapter.ts        # MongoDB
+│   ├── PostgreSQLAdapter.ts   # PostgreSQL
+│   ├── SQLiteAdapter.ts       # SQLite
+│   ├── OpenSearchAdapter.ts   # OpenSearch/Elasticsearch
+│   └── index.ts               # Adapter exports
 ├── utils/          # Utility functions
-│   └── retry.ts           # Retry/timeout logic
+│   ├── retry.ts           # Retry/timeout logic
+│   └── id.ts              # Deterministic ID generation
 ├── constants/      # Constants and symbols
-│   └── index.ts           # END_ROUTE, etc.
+│   └── index.ts           # END_ROUTE, EventSource, etc.
 └── index.ts        # Public API exports
 ```
 
@@ -27,6 +51,8 @@ src/
 1. **Flat, organized structure** - Clear separation by purpose
 2. **Types-first** - All types in dedicated folder
 3. **Core logic isolated** - Business logic in \`core/\`
-4. **Provider pattern** - Pluggable AI backends
-5. **Path aliases** - Clean imports with \`@/types\`, \`@/core\`, etc.
-6. **Fluent API** - Methods return \`this\` for chaining
+4. **Provider pattern** - Pluggable AI backends and database adapters
+5. **Optional persistence** - Multiple database adapters following the same pattern
+6. **Extensibility** - Easy to add new providers, adapters, and tools
+7. **Path aliases** - Clean imports with \`@/types\`, \`@/core\`, etc.
+8. **Fluent API** - Methods return \`this\` for chaining

package/examples/domain-scoping.ts

@@ -2,7 +2,13 @@
  * 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.
+ * can EXECUTE in different conversation routes for security and isolation.
+ *
+ * Important: Domains are OPTIONAL. If you never use domains, all tools are
+ * available everywhere. Use domains when you need security and organization.
+ *
+ * Key Concept: The AI never sees tools. Domains control which tools can
+ * execute automatically when triggered by the state machine or guidelines.
  */
 
 import { Agent, createMessageEvent, EventSource } from "../src/index";
@@ -186,19 +192,21 @@ async function demonstrateScoping() {
 // 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
+- Customer Support route cannot execute payment.processPayment()
+- Data Collection route cannot execute calendar.scheduleEvent()
+- Each route has minimum necessary tool permissions
+- Prevents prompt injection attacks from calling sensitive tools
 
-⚡ Performance Benefits:
-- AI only sees relevant tools for each route
-- Faster decision making with reduced context
-- Clearer intent and fewer errors
+🎯 Isolation Benefits:
+- Route execution is isolated - tools can't cross boundaries
+- Checkout can't accidentally trigger admin operations
+- Clear separation of concerns by capability
 
-🎯 Clarity Benefits:
+📋 Clarity Benefits:
 - Routes clearly document their capabilities
-- Easy to audit what each route can do
+- Easy to audit what each route can execute
 - Better debugging when tools are called
+- Self-documenting security model
 `);
 
 // Inspect route configurations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.3.24",
+  "version": "0.3.30",
   "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

@@ -328,11 +328,9 @@ export class Agent<TContext = unknown> {
       );
     }
 
-    // Add domains (tools) information if any domains are registered
-    const allDomains = this.domainRegistry.all();
-    if (Object.keys(allDomains).length > 0) {
-      promptBuilder.addDomains(allDomains);
-    }
+    // NOTE: Domains/tools are NOT added to the prompt.
+    // Tools execute automatically based on state transitions and guideline matching,
+    // NOT based on AI decisions. The AI should never see available tools.
 
     // Add JSON response schema instructions
     promptBuilder.addJsonResponseSchema();
@@ -500,11 +498,9 @@ export class Agent<TContext = unknown> {
       );
     }
 
-    // Add domains (tools) information if any domains are registered
-    const allDomains = this.domainRegistry.all();
-    if (Object.keys(allDomains).length > 0) {
-      promptBuilder.addDomains(allDomains);
-    }
+    // NOTE: Domains/tools are NOT added to the prompt.
+    // Tools execute automatically based on state transitions and guideline matching,
+    // NOT based on AI decisions. The AI should never see available tools.
 
     // Add JSON response schema instructions
     promptBuilder.addJsonResponseSchema();

package/src/core/PromptBuilder.ts

@@ -449,7 +449,7 @@ 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}` : "";
-          
+
           let domainInfo = "";
           if (route.domains !== undefined) {
             if (route.domains.length === 0) {
@@ -461,17 +461,23 @@ When you detect any of these situations, consider which route would be most appr
 
           let rulesInfo = "";
           if (route.rules && route.rules.length > 0) {
-            const rulesList = route.rules.map((r, idx) => `${idx + 1}. ${r}`).join("; ");
+            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("; ");
+            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}`;
+          return `${i + 1}) ${
+            route.title
+          }${desc}${conditions}${domainInfo}${rulesInfo}${prohibitionsInfo}`;
         })
         .join("\n\n");
 
@@ -497,9 +503,7 @@ IMPORTANT:
   /**
    * Add domains (tools) information
    */
-  addDomains(
-    domains: Record<string, Record<string, unknown>>
-  ): this {
+  addDomains(domains: Record<string, Record<string, unknown>>): this {
     const domainNames = Object.keys(domains);
     if (domainNames.length > 0) {
       const domainsString = domainNames
@@ -526,21 +530,18 @@ When calling tools, use the format: domain.toolName (e.g., "payment.processPayme
     return this;
   }
 
-
   /**
    * Add JSON response schema instructions
+   *
+   * NOTE: toolCalls are NOT included. Tools execute automatically based on
+   * state transitions and guideline matching, NOT based on AI decisions.
    */
   addJsonResponseSchema(): this {
     const schema = {
       message: "The actual message to send to the user",
       route: "The title of the route you chose (or null if no specific route)",
-      state: "The current state within the route (or null if not in a route)",
-      toolCalls: [
-        {
-          toolName: "Name of the tool to call",
-          arguments: "Object with tool arguments",
-        },
-      ],
+      state:
+        "The current state within the chosen route (or null if not in a route)",
       reasoning: "Optional: Your internal reasoning for this response",
     };
 
@@ -556,7 +557,6 @@ Instructions:
 - "message": The actual message to send to the user (required)
 - "route": If you chose a specific conversation route, provide its exact title. If not in a route, use null.
 - "state": The current state within the chosen route. If not in a route or at initial state, use null.
-- "toolCalls": If you need to call any tools, provide an array of tool calls. If no tools needed, use an empty array or omit.
 - "reasoning": Optional field for your internal thinking process.
 
 Your entire response must be valid JSON. Do not include any text before or after the JSON object.`,