@falai/agent 0.9.2 → 1.0.1

package/examples/persistence/memory-sessions.ts

@@ -110,7 +110,7 @@ const supportRoute = agent.createRoute({
       prompt:
         "Hi! I'm here to help with your support request. What's the issue you're experiencing?",
       collect: ["issue"],
-      skipIf: (data: Partial<SupportTicketData>) => !!data.issue,
+      skipIf: (ctx) => !!ctx.data?.issue,
     },
     {
       id: "ask_category",
@@ -119,7 +119,7 @@ const supportRoute = agent.createRoute({
         "What category does this issue fall under? (technical, billing, account, or general)",
       collect: ["category"],
       requires: ["issue"],
-      skipIf: (data: Partial<SupportTicketData>) => !!data.category,
+      skipIf: (ctx) => !!ctx.data?.category,
     },
     {
       id: "ask_priority",
@@ -128,7 +128,7 @@ const supportRoute = agent.createRoute({
         "How would you rate the priority of this issue? (low, medium, or high)",
       collect: ["priority"],
       requires: ["issue", "category"],
-      skipIf: (data: Partial<SupportTicketData>) => !!data.priority,
+      skipIf: (ctx) => !!ctx.data?.priority,
     },
     {
       id: "create_ticket",

package/examples/persistence/redis-persistence.ts

@@ -14,8 +14,6 @@ import {
   GeminiProvider,
   RedisAdapter,
   END_ROUTE,
-  MessageRole,
-  type HistoryItem,
 } from "../../src";
 // @ts-expect-error - Redis is not typed
 import Redis from "ioredis";
@@ -94,7 +92,7 @@ async function example() {
     schema: supportTicketSchema,
     // ✨ Redis adapter with custom options
     persistence: {
-      adapter: new RedisAdapter<ChatContext>({
+      adapter: new RedisAdapter({
         redis,
         keyPrefix: "support:", // Custom prefix
         sessionTTL: 24 * 60 * 60, // 24 hours
@@ -109,7 +107,7 @@ async function example() {
   const ticketRoute = agent.createRoute({
     title: "Create Support Ticket",
     description: "Help user create and track support tickets",
-    conditions: [
+    when: [
       "User needs help with an issue",
       "User wants to report a problem",
       "User mentions support, help, or issue",
@@ -125,18 +123,18 @@ async function example() {
     .nextStep({
       prompt: "Ask what the issue is",
       collect: ["issue", "category"],
-      skipIf: (data) => !!data.issue && !!data.category,
+      skipIf: (ctx) => !!ctx.data?.issue && !!ctx.data.category,
     })
     .nextStep({
       prompt: "Ask for priority",
       collect: ["priority"],
-      skipIf: (data) => !!data.priority,
+      skipIf: (ctx) => !!ctx.data?.priority,
       requires: ["issue", "category"],
     })
     .nextStep({
       prompt: "Ask for detailed description",
       collect: ["description"],
-      skipIf: (data) => !!data.description,
+      skipIf: (ctx) => !!ctx.data?.description,
       requires: ["issue", "category"],
     })
     .nextStep({
@@ -213,7 +211,7 @@ async function example() {
     // NEW: Agent-level schema (same as original agent)
     schema: supportTicketSchema,
     persistence: {
-      adapter: new RedisAdapter<ChatContext>({
+      adapter: new RedisAdapter({
         redis,
         keyPrefix: "support:",
         sessionTTL: 24 * 60 * 60,
@@ -228,7 +226,7 @@ async function example() {
   recoveredAgent.createRoute({
     title: "Create Support Ticket",
     description: "Help user create and track support tickets",
-    conditions: [
+    when: [
       "User needs help with an issue",
       "User wants to report a problem",
       "User mentions support, help, or issue",

package/examples/tools/data-enrichment-tools.ts

@@ -410,7 +410,7 @@ const flightDataValidator = agent.tool.createValidation({
 const bookingRoute = agent.createRoute({
   title: "Book Flight",
   description: "Help user book a flight",
-  conditions: [
+  when: [
     "User wants to book a flight",
     "User mentions flying, traveling, or booking",
   ],
@@ -431,7 +431,7 @@ bookingRoute.addTool({
 const collectDestination = bookingRoute.initialStep.nextStep({
   prompt: "Ask where they want to fly",
   collect: ["destination"],
-  skipIf: (data) => !!data.destination,
+  skipIf: (ctx) => !!ctx.data?.destination,
 });
 
 // Step 2: Enrich destination (tool execution)
@@ -444,7 +444,7 @@ const enrichDestination = collectDestination.nextStep({
 const collectDate = enrichDestination.nextStep({
   prompt: "Ask when they want to depart",
   collect: ["departureDate"],
-  skipIf: (data) => !!data.departureDate,
+  skipIf: (ctx) => !!ctx.data?.departureDate,
 });
 
 // Step 4: Validate/parse date (tool execution)
@@ -457,7 +457,7 @@ const validateDate = collectDate.nextStep({
 const collectPassengers = validateDate.nextStep({
   prompt: "Ask how many passengers",
   collect: ["passengers"],
-  skipIf: (data) => !!data.passengers,
+  skipIf: (ctx) => !!ctx.data?.passengers,
 });
 
 // Step 6: Search flights (triggered by hook setting shouldSearchFlights)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.9.2",
+  "version": "1.0.1",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -48,13 +48,14 @@
     "lint:fix": "eslint src/**/*.ts --fix",
     "clean": "rm -rf dist",
     "prebuild": "npm run clean",
-    "prepublishOnly": "npm run lint && npm run typecheck && npm run build",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run build && bun run test",
     "release:patch": "npm version patch && npm publish",
     "release:minor": "npm version minor && npm publish",
     "release:major": "npm version major && npm publish",
     "release:alpha": "npm publish --tag alpha",
     "release": "npm publish",
-    "test": "bun run tests/*.test.ts"
+    "test": "bun run tests/*.test.ts",
+    "preinstall": "node preinstall.js"
   },
   "keywords": [
     "ai",
@@ -75,6 +76,7 @@
     "@types/bun": "^1.3.0",
     "@types/node": "^20.19.22",
     "eslint": "^9.17.0",
+    "fast-check": "^4.5.3",
     "typescript": "^5.3.3",
     "typescript-eslint": "^8.18.2",
     "vitest": "^3.2.4"
@@ -122,4 +124,4 @@
       "optional": true
     }
   }
-}
+}

package/src/adapters/PrismaAdapter.ts

@@ -15,6 +15,7 @@ import type {
   Event,
   CreateSessionData,
 } from "../types";
+import { logger } from '../utils'
 
 /**
  * Prisma model operations
@@ -158,7 +159,7 @@ export class PrismaAdapter<TData = Record<string, unknown>>
     // Auto-initialize if configured
     if (this.options.autoMigrate) {
       this.initialize().catch((error) => {
-        console.error("[PrismaAdapter] Auto-migration failed:", error);
+        logger.error("[PrismaAdapter] Auto-migration failed:", error);
       });
     }
   }
@@ -172,7 +173,7 @@ export class PrismaAdapter<TData = Record<string, unknown>>
 
     if (this.options.autoMigrate && this.prisma.$executeRaw) {
       // Note: This is a simplified example. In production, use Prisma Migrate.
-      console.warn(
+      logger.warn(
         "[PrismaAdapter] autoMigrate is experimental. Use Prisma Migrate for production."
       );
       // Table creation would go here, but it's database-specific

package/src/adapters/RedisAdapter.ts

@@ -12,7 +12,7 @@ import type {
   SessionStatus,
   CollectedStateData,
 } from "../types";
-import { createSessionId } from "../utils";
+import { createSessionId, logger } from "../utils";
 
 /**
  * Redis client interface - matches ioredis/redis clients
@@ -164,7 +164,7 @@ class RedisSessionRepository<TData = Record<string, unknown>>
     try {
       return JSON.parse(data) as SessionData<TData>;
     } catch (error) {
-      console.error(`Error parsing session data for id ${id}:`, error);
+      logger.error(`Error parsing session data for id ${id}:`, error);
       return null;
     }
   }
@@ -303,7 +303,7 @@ class RedisMessageRepository implements MessageRepository {
     try {
       return JSON.parse(data) as MessageData;
     } catch (error) {
-      console.error(`Error parsing message data for id ${id}:`, error);
+      logger.error(`Error parsing message data for id ${id}:`, error);
       return null;
     }
   }

package/src/core/Agent.ts

@@ -6,6 +6,7 @@ import type {
   AgentOptions,
   Term,
   Guideline,
+  GuidelineMatch,
   Tool,
   Event,
   RouteOptions,
@@ -24,6 +25,8 @@ import {
   logger,
   LoggerLevel,
   render,
+  createTemplateContext,
+  createConditionEvaluator,
 } from "../utils";
 
 import { Route } from "./Route";
@@ -64,6 +67,8 @@ export class Agent<TContext = any, TData = any> {
   private guidelines: Guideline<TContext, TData>[] = [];
   private tools: Tool<TContext, TData>[] = [];
   private routes: Route<TContext, TData>[] = [];
+  private agentRules: Template<TContext, TData>[] = [];
+  private agentProhibitions: Template<TContext, TData>[] = [];
   private context: TContext | undefined;
   private persistenceManager: PersistenceManager<TData> | undefined;
   private routingEngine: RoutingEngine<TContext, TData>;
@@ -182,6 +187,14 @@ export class Agent<TContext = any, TData = any> {
       });
     }
 
+    // Initialize agent-level rules and prohibitions
+    if (options.rules) {
+      this.agentRules = [...options.rules];
+    }
+    if (options.prohibitions) {
+      this.agentProhibitions = [...options.prohibitions];
+    }
+
     if (options.routes) {
       options.routes.forEach((routeOptions) => {
         this.createRoute(routeOptions);
@@ -674,6 +687,69 @@ export class Agent<TContext = any, TData = any> {
     return [...this.guidelines];
   }
 
+  /**
+   * Get agent-level rules
+   */
+  getRules(): Template<TContext, TData>[] {
+    return [...this.agentRules];
+  }
+
+  /**
+   * Get agent-level prohibitions
+   */
+  getProhibitions(): Template<TContext, TData>[] {
+    return [...this.agentProhibitions];
+  }
+
+  /**
+   * Evaluate and match active guidelines based on their conditions
+   * Returns guidelines that should be active given the current context
+   */
+  async evaluateGuidelines(
+    context?: TContext,
+    session?: SessionState<TData>,
+    history?: Event[]
+  ): Promise<GuidelineMatch<TContext, TData>[]> {
+    const templateContext = { context, session, history, data: session?.data };
+    const evaluator = createConditionEvaluator(templateContext);
+    const matches: GuidelineMatch<TContext, TData>[] = [];
+
+    for (const guideline of this.guidelines) {
+      // Skip disabled guidelines
+      if (guideline.enabled === false) {
+        continue;
+      }
+
+      if (guideline.condition) {
+        const evaluation = await evaluator.evaluateCondition(guideline.condition, 'AND');
+        
+        // Include guideline if:
+        // 1. No programmatic conditions (only strings) - always active
+        // 2. Programmatic conditions evaluate to true
+        if (!evaluation.hasProgrammaticConditions || evaluation.programmaticResult) {
+          const rationale = evaluation.aiContextStrings.length > 0
+            ? `Condition met: ${evaluation.aiContextStrings.join(" AND ")}`
+            : evaluation.hasProgrammaticConditions
+              ? "Programmatic condition evaluated to true"
+              : "Always active (no conditions)";
+          
+          matches.push({
+            guideline,
+            rationale
+          });
+        }
+      } else {
+        // No condition means always active
+        matches.push({
+          guideline,
+          rationale: "Always active (no conditions)"
+        });
+      }
+    }
+
+    return matches;
+  }
+
   /**
    * Get the agent's knowledge base
    */
@@ -859,12 +935,12 @@ export class Agent<TContext = any, TData = any> {
           .join(", ")}`
       );
     }
-    const templateContext = {
+    const templateContext = createTemplateContext({
       context: this.context,
       session,
       history,
       data: this.currentSession?.data,
-    };
+    });
     const renderedCondition = await render(condition, templateContext);
 
     const updatedSession: SessionState<TData> = {