@falai/agent 0.9.0 → 1.0.0

package/src/providers/OpenAIProvider.ts

@@ -13,7 +13,7 @@ import type {
   AgentStructuredResponse,
   StructuredSchema,
 } from "../types";
-import { withTimeoutAndRetry } from "../utils/retry";
+import { withTimeoutAndRetry, logger } from "../utils";
 import { FunctionParameters } from "openai/resources/shared.mjs";
 
 const DEFAULT_RETRY_CONFIG = {
@@ -207,7 +207,7 @@ export class OpenAIProvider implements AiProvider {
       );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
-      console.warn(
+      logger.warn(
         `[OPENAI] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
       );
 
@@ -215,13 +215,13 @@ export class OpenAIProvider implements AiProvider {
         throw primaryError;
       }
 
-      console.log(`[OPENAI] Trying backup models`);
+      logger.debug(`[OPENAI] Trying backup models`);
 
       let lastBackupError: unknown = primaryError;
 
       for (let i = 0; i < this.backupModels.length; i++) {
         const backupModel = this.backupModels[i];
-        console.log(
+        logger.debug(
           `[OPENAI] Trying backup model ${i + 1}/${
             this.backupModels.length
           }: ${backupModel}`
@@ -229,11 +229,11 @@ export class OpenAIProvider implements AiProvider {
 
         try {
           const result = await this.generateWithModel(backupModel, input);
-          console.log(`[OPENAI] Backup model ${backupModel} succeeded`);
+          logger.debug(`[OPENAI] Backup model ${backupModel} succeeded`);
           return result as GenerateMessageOutput<TStructured>;
         } catch (backupError: unknown) {
           const backupErrMsg = getErrorMessage(backupError);
-          console.warn(
+          logger.warn(
             `[OPENAI] Backup model ${backupModel} failed: ${backupErrMsg}`
           );
           lastBackupError = backupError;
@@ -242,7 +242,7 @@ export class OpenAIProvider implements AiProvider {
             !shouldUseBackupModel(backupError) &&
             i < this.backupModels.length - 1
           ) {
-            console.log(
+            logger.debug(
               `[OPENAI] Backup model error doesn't qualify for further attempts`
             );
             break;
@@ -251,7 +251,7 @@ export class OpenAIProvider implements AiProvider {
       }
 
       const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      console.error(
+      logger.error(
         `[OPENAI] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
       );
       throw lastBackupError;
@@ -355,7 +355,7 @@ export class OpenAIProvider implements AiProvider {
                 toolCall.function.arguments
               ) as Record<string, unknown>;
             } catch (error) {
-              console.warn(
+              logger.warn(
                 `[OPENAI] Failed to parse tool call arguments: ${getErrorMessage(
                   error
                 )}`
@@ -408,7 +408,7 @@ export class OpenAIProvider implements AiProvider {
       );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
-      console.warn(
+      logger.warn(
         `[OPENAI] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
       );
 
@@ -416,13 +416,13 @@ export class OpenAIProvider implements AiProvider {
         throw primaryError;
       }
 
-      console.log(`[OPENAI] Trying backup models for streaming`);
+      logger.debug(`[OPENAI] Trying backup models for streaming`);
 
       let lastBackupError: unknown = primaryError;
 
       for (let i = 0; i < this.backupModels.length; i++) {
         const backupModel = this.backupModels[i];
-        console.log(
+        logger.debug(
           `[OPENAI] Trying backup model ${i + 1}/${
             this.backupModels.length
           }: ${backupModel}`
@@ -433,11 +433,11 @@ export class OpenAIProvider implements AiProvider {
             backupModel,
             input
           );
-          console.log(`[OPENAI] Backup model ${backupModel} succeeded`);
+          logger.debug(`[OPENAI] Backup model ${backupModel} succeeded`);
           return;
         } catch (backupError: unknown) {
           const backupErrMsg = getErrorMessage(backupError);
-          console.warn(
+          logger.warn(
             `[OPENAI] Backup model ${backupModel} failed: ${backupErrMsg}`
           );
           lastBackupError = backupError;
@@ -446,7 +446,7 @@ export class OpenAIProvider implements AiProvider {
             !shouldUseBackupModel(backupError) &&
             i < this.backupModels.length - 1
           ) {
-            console.log(
+            logger.debug(
               `[OPENAI] Backup model error doesn't qualify for further attempts`
             );
             break;
@@ -455,7 +455,7 @@ export class OpenAIProvider implements AiProvider {
       }
 
       const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      console.error(
+      logger.error(
         `[OPENAI] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
       );
       throw lastBackupError;
@@ -535,7 +535,7 @@ export class OpenAIProvider implements AiProvider {
                   >)
                 : {};
             } catch (error) {
-              console.warn(
+              logger.warn(
                 `[OPENAI] Failed to parse tool call arguments in stream: ${getErrorMessage(
                   error
                 )}`
@@ -577,7 +577,7 @@ export class OpenAIProvider implements AiProvider {
       try {
         structured = JSON.parse(accumulated) as TStructured;
       } catch (error) {
-        console.warn(
+        logger.warn(
           "[OPENAI] Failed to parse JSON response in stream:",
           error
         );

package/src/providers/OpenRouterProvider.ts

@@ -15,7 +15,7 @@ import type {
   GenerateMessageStreamChunk,
   StructuredSchema,
 } from "../types";
-import { withTimeoutAndRetry } from "../utils/retry";
+import { withTimeoutAndRetry, logger } from "../utils";
 
 const DEFAULT_RETRY_CONFIG = {
   timeout: 60000,
@@ -214,7 +214,7 @@ export class OpenRouterProvider implements AiProvider {
       return await this.generateWithModel(this.primaryModel, input);
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
-      console.warn(
+      logger.warn(
         `[OPENROUTER] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
       );
 
@@ -222,13 +222,13 @@ export class OpenRouterProvider implements AiProvider {
         throw primaryError;
       }
 
-      console.log(`[OPENROUTER] Trying backup models`);
+      logger.debug(`[OPENROUTER] Trying backup models`);
 
       let lastBackupError: unknown = primaryError;
 
       for (let i = 0; i < this.backupModels.length; i++) {
         const backupModel = this.backupModels[i];
-        console.log(
+        logger.debug(
           `[OPENROUTER] Trying backup model ${i + 1}/${
             this.backupModels.length
           }: ${backupModel}`
@@ -236,11 +236,11 @@ export class OpenRouterProvider implements AiProvider {
 
         try {
           const result = await this.generateWithModel(backupModel, input);
-          console.log(`[OPENROUTER] Backup model ${backupModel} succeeded`);
+          logger.debug(`[OPENROUTER] Backup model ${backupModel} succeeded`);
           return result as GenerateMessageOutput<TStructured>;
         } catch (backupError: unknown) {
           const backupErrMsg = getErrorMessage(backupError);
-          console.warn(
+          logger.warn(
             `[OPENROUTER] Backup model ${backupModel} failed: ${backupErrMsg}`
           );
           lastBackupError = backupError;
@@ -249,7 +249,7 @@ export class OpenRouterProvider implements AiProvider {
             !shouldUseBackupModel(backupError) &&
             i < this.backupModels.length - 1
           ) {
-            console.log(
+            logger.debug(
               `[OPENROUTER] Backup model error doesn't qualify for further attempts`
             );
             break;
@@ -258,7 +258,7 @@ export class OpenRouterProvider implements AiProvider {
       }
 
       const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      console.error(
+      logger.error(
         `[OPENROUTER] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
       );
       throw lastBackupError;
@@ -364,7 +364,7 @@ export class OpenRouterProvider implements AiProvider {
                 toolCall.function.arguments
               ) as Record<string, unknown>;
             } catch (error) {
-              console.warn(
+              logger.warn(
                 `[OPENROUTER] Failed to parse tool call arguments: ${getErrorMessage(
                   error
                 )}`
@@ -413,7 +413,7 @@ export class OpenRouterProvider implements AiProvider {
       yield* this.generateStreamWithModel(this.primaryModel, input);
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
-      console.warn(
+      logger.warn(
         `[OPENROUTER] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
       );
 
@@ -421,13 +421,13 @@ export class OpenRouterProvider implements AiProvider {
         throw primaryError;
       }
 
-      console.log(`[OPENROUTER] Trying backup models for streaming`);
+      logger.debug(`[OPENROUTER] Trying backup models for streaming`);
 
       let lastBackupError: unknown = primaryError;
 
       for (let i = 0; i < this.backupModels.length; i++) {
         const backupModel = this.backupModels[i];
-        console.log(
+        logger.debug(
           `[OPENROUTER] Trying backup model ${i + 1}/${
             this.backupModels.length
           }: ${backupModel}`
@@ -435,11 +435,11 @@ export class OpenRouterProvider implements AiProvider {
 
         try {
           yield* this.generateStreamWithModel(backupModel, input);
-          console.log(`[OPENROUTER] Backup model ${backupModel} succeeded`);
+          logger.debug(`[OPENROUTER] Backup model ${backupModel} succeeded`);
           return;
         } catch (backupError: unknown) {
           const backupErrMsg = getErrorMessage(backupError);
-          console.warn(
+          logger.warn(
             `[OPENROUTER] Backup model ${backupModel} failed: ${backupErrMsg}`
           );
           lastBackupError = backupError;
@@ -448,7 +448,7 @@ export class OpenRouterProvider implements AiProvider {
             !shouldUseBackupModel(backupError) &&
             i < this.backupModels.length - 1
           ) {
-            console.log(
+            logger.debug(
               `[OPENROUTER] Backup model error doesn't qualify for further attempts`
             );
             break;
@@ -457,7 +457,7 @@ export class OpenRouterProvider implements AiProvider {
       }
 
       const lastBackupErrMsg = getErrorMessage(lastBackupError);
-      console.error(
+      logger.error(
         `[OPENROUTER] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
       );
       throw lastBackupError;
@@ -537,7 +537,7 @@ export class OpenRouterProvider implements AiProvider {
                   >)
                 : {};
             } catch (error) {
-              console.warn(
+              logger.warn(
                 `[OPENROUTER] Failed to parse tool call arguments in stream: ${getErrorMessage(
                   error
                 )}`
@@ -579,7 +579,7 @@ export class OpenRouterProvider implements AiProvider {
       try {
         structured = JSON.parse(accumulated) as TStructured;
       } catch (error) {
-        console.warn(
+        logger.warn(
           "[OPENROUTER] Failed to parse JSON response in stream:",
           error
         );

package/src/types/agent.ts

@@ -4,11 +4,11 @@
 
 import type { AgentStructuredResponse, AiProvider } from "./ai";
 import type { Tool } from "./tool";
-import type { RouteOptions } from "./route";
+import type { RouteOptions, StepRef, StoppedReason } from "./route";
 import type { PersistenceConfig } from "./persistence";
 import type { SessionState } from "./session";
 import type { StructuredSchema } from "./schema";
-import { Template } from "./template";
+import { Template, ConditionTemplate } from "./template";
 
 /**
  * Composition mode determines how the agent processes and structures responses
@@ -99,7 +99,7 @@ export interface AgentOptions<TContext = unknown, TData = unknown> {
   /** Initial guidelines for agent behavior */
   guidelines?: Guideline<TContext, TData>[];
   /** Global tools available to all routes */
-  tools?: Tool<TContext, TData, unknown[], unknown>[];
+  tools?: Tool<TContext, TData, unknown>[];
   /** Initial routes (will be instantiated as Route objects) */
   routes?: RouteOptions<TContext, TData>[];
   /** Optional persistence configuration for auto-saving sessions and messages */
@@ -131,7 +131,7 @@ export interface Guideline<TContext = unknown, TData = unknown> {
   /** Unique identifier */
   id?: string;
   /** Condition that triggers this guideline (optional for always-active guidelines) */
-  condition?: Template<TContext, TData>;
+  condition?: ConditionTemplate<TContext, TData>;
   /** Action the agent should take when the condition is met */
   action: Template<TContext, TData>;
   /** Whether this guideline is currently enabled */
@@ -157,6 +157,10 @@ export interface AgentResponse<TData = Record<string, unknown>> {
   session?: SessionState<TData>;
   toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
   isRouteComplete?: boolean;
+  /** Steps executed in this response (for multi-step execution) */
+  executedSteps?: StepRef[];
+  /** Why execution stopped (for multi-step execution) */
+  stoppedReason?: StoppedReason;
 }
 
 export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
@@ -166,6 +170,10 @@ export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
   session?: SessionState<TData>;
   toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
   isRouteComplete?: boolean;
+  /** Steps executed in this response (for multi-step execution) */
+  executedSteps?: StepRef[];
+  /** Why execution stopped (for multi-step execution) */
+  stoppedReason?: StoppedReason;
   metadata?: {
     model?: string;
     tokensUsed?: number;

package/src/types/index.ts

@@ -45,8 +45,8 @@ export type {
   RouteRef,
   StepRef,
   StepOptions,
-  StepResult,
   BranchSpec,
+  StepResult,
   BranchResult,
   RouteCompletionHandler,
   RouteTransitionConfig,
@@ -58,7 +58,18 @@ export * from "./route";
 export type { SessionState, PendingTransition } from "./session";
 
 // Tool types
-export type { Tool, ToolContext, ToolResult, ToolHandler } from "./tool";
+export type { 
+  Tool, 
+  ToolContext, 
+  ToolResult, 
+  ToolHandler,
+  ToolExecutionResult,
+  DataEnrichmentConfig,
+  ValidationConfig,
+  ApiCallConfig,
+  ComputationConfig
+} from "./tool";
+export { ToolScope } from "./tool";
 
 // AI provider types
 export type {
@@ -94,4 +105,15 @@ export type {
 export * from "./persistence";
 
 // Template types
-export type { Template, TemplateContext } from "./template";
+export type { 
+  Template, 
+  TemplateContext, 
+  ConditionTemplate, 
+  ConditionEvaluationResult 
+} from "./template";
+export { 
+  ConditionEvaluator, 
+  createConditionEvaluator, 
+  extractAIContextStrings, 
+  hasProgrammaticConditions 
+} from "../utils/condition";

package/src/types/route.ts

@@ -4,7 +4,79 @@
 
 import type { Tool } from "./tool";
 import type { StructuredSchema } from "./schema";
-import { Template } from "./template";
+import type { Guideline, Term } from "./agent";
+import { Template, ConditionTemplate } from "./template";
+
+/**
+ * Reason why batch execution stopped
+ * Used to indicate the stopping condition for multi-step execution
+ */
+export type StoppedReason =
+  | 'needs_input'      // Step requires uncollected data
+  | 'end_route'        // Reached END_ROUTE
+  | 'route_complete'   // All Steps processed
+  | 'prepare_error'    // Error in prepare hook
+  | 'llm_error'        // Error during LLM call
+  | 'validation_error' // Error validating collected data
+  | 'finalize_error';  // Error in finalize hook (non-fatal, logged)
+
+/**
+ * Event types for batch execution observability
+ */
+export type BatchExecutionEventType = 
+  | 'batch_start' 
+  | 'step_included' 
+  | 'step_skipped' 
+  | 'batch_stop' 
+  | 'batch_complete';
+
+/**
+ * Event emitted during batch execution for debugging and observability
+ * 
+ * **Validates: Requirements 11.3**
+ */
+export interface BatchExecutionEvent {
+  /** Type of batch execution event */
+  type: BatchExecutionEventType;
+  /** Timestamp when the event occurred */
+  timestamp: Date;
+  /** Event-specific details */
+  details: {
+    /** Step ID related to this event (for step_included, step_skipped) */
+    stepId?: string;
+    /** Reason for the event (e.g., why step was skipped or batch stopped) */
+    reason?: string;
+    /** Current batch size (for batch_start, batch_complete) */
+    batchSize?: number;
+    /** Stopped reason (for batch_stop, batch_complete) */
+    stoppedReason?: StoppedReason;
+    /** Phase timing information (for batch_complete) */
+    timing?: BatchExecutionTiming;
+  };
+}
+
+/**
+ * Timing information for batch execution phases
+ */
+export interface BatchExecutionTiming {
+  /** Total batch execution time in milliseconds */
+  totalMs: number;
+  /** Time spent in batch determination phase */
+  determinationMs?: number;
+  /** Time spent executing prepare hooks */
+  prepareHooksMs?: number;
+  /** Time spent in LLM call */
+  llmCallMs?: number;
+  /** Time spent collecting data */
+  dataCollectionMs?: number;
+  /** Time spent executing finalize hooks */
+  finalizeHooksMs?: number;
+}
+
+/**
+ * Callback type for batch execution event listeners
+ */
+export type BatchExecutionEventListener = (event: BatchExecutionEvent) => void;
 
 /**
  * Reference to a route
@@ -25,9 +97,52 @@ export interface StepRef {
 }
 
 /**
- * Forward declare Guideline and Term for circular dependency
+ * Result of batch determination - which steps can execute together
+ * @template TContext - Type of context data
+ * @template TData - Type of collected data
  */
-import type { Guideline, Term } from "./agent";
+export interface BatchResult<TContext = unknown, TData = unknown> {
+  /** Steps included in this batch */
+  steps: StepOptions<TContext, TData>[];
+  /** Why the batch stopped */
+  stoppedReason: StoppedReason;
+  /** The Step that caused the stop (if applicable) */
+  stoppedAtStep?: StepOptions<TContext, TData>;
+}
+
+/**
+ * Error details for batch execution failures
+ */
+export interface BatchExecutionError {
+  /** Type of error that occurred */
+  type: 'pre_extraction' | 'skipif_evaluation' | 'prepare_hook' | 
+        'llm_call' | 'data_validation' | 'finalize_hook';
+  /** Error message */
+  message: string;
+  /** Step where error occurred (if applicable) */
+  stepId?: string;
+  /** Additional error details */
+  details?: unknown;
+}
+
+/**
+ * Result of executing a batch of steps
+ * @template TData - Type of collected data
+ */
+export interface BatchExecutionResult<TData = unknown> {
+  /** The generated message */
+  message: string;
+  /** Updated session state */
+  session: import('./session').SessionState<TData>;
+  /** Steps that were executed */
+  executedSteps: StepRef[];
+  /** Why execution stopped */
+  stoppedReason: StoppedReason;
+  /** Collected data from the batch */
+  collectedData?: Partial<TData>;
+  /** Any errors that occurred */
+  error?: BatchExecutionError;
+}
 
 /**
  * Route lifecycle hooks for managing route-specific data and behavior
@@ -98,13 +213,15 @@ export interface RouteOptions<TContext = unknown, TData = unknown> {
   /** Optional personality prompt defining the agent's communication style for this route */
   personality?: Template<TContext, TData>;
   /** Conditions that activate this route */
-  conditions?: Template<TContext, TData>[];
+  when?: ConditionTemplate<TContext, TData>;
+  /** Conditions that prevent this route from being considered */
+  skipIf?: ConditionTemplate<TContext, TData>;
   /** Initial guidelines for this route */
-  guidelines?: Guideline<TContext>[];
+  guidelines?: Guideline<TContext, TData>[];
   /** Initial terms for the route's domain glossary */
   terms?: Term<TContext>[];
   /** Tools available in this route */
-  tools?: Tool<TContext, TData, unknown[], unknown>[];
+  tools?: (string | Tool<TContext, TData>)[];
   /** Absolute rules the agent must follow in this route */
   rules?: Template<TContext, TData>[];
   /** Absolute prohibitions the agent must never do in this route */
@@ -197,16 +314,16 @@ export interface StepOptions<TContext = unknown, TData = unknown> {
   /** Transition to a chat state with this description */
   prompt?: Template<TContext, TData>;
   /** Tools available for AI to call in this step (by ID reference or inline definition) */
-  tools?: (string | Tool<TContext, TData, unknown[], unknown>)[];
+  tools?: (string | Tool<TContext, TData>)[];
   /** Programmatic function or tool to run before AI responds */
   prepare?:
     | string
-    | Tool<TContext, TData, unknown[], unknown>
+    | Tool<TContext, TData>
     | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
   /** Programmatic function or tool to run after AI responds */
   finalize?:
     | string
-    | Tool<TContext, TData, unknown[], unknown>
+    | Tool<TContext, TData>
     | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
   /** Transition to a specific step or end marker */
   step?: StepRef | symbol;
@@ -216,12 +333,11 @@ export interface StepOptions<TContext = unknown, TData = unknown> {
    */
   collect?: (keyof TData)[];
   /**
-   * Function to determine if this step should be skipped
-   * If returns true, the step will be bypassed
-   * @param data - Currently collected agent-level data
-   * @returns true if step should be skipped, false otherwise
+   * Condition to determine if this step should be skipped
+   * If evaluates to true, the step will be bypassed
+   * Supports strings (AI context), functions (programmatic), and arrays
    */
-  skipIf?: (data: Partial<TData>) => boolean;
+  skipIf?: ConditionTemplate<TContext, TData>;
   /**
    * Required data fields that must be present before entering this step
    * If any required field is missing, step cannot be entered
@@ -231,8 +347,11 @@ export interface StepOptions<TContext = unknown, TData = unknown> {
   /**
    * Optional condition for this transition
    * Description of when this transition should be taken
+   * Supports strings (AI context), functions (programmatic), and arrays
    */
-  when?: Template<TContext, TData>;
+  when?: ConditionTemplate<TContext, TData>;
+  /** Initial guidelines for this step */
+  guidelines?: Guideline<TContext, TData>[];
 }
 
 /**
@@ -267,4 +386,6 @@ export interface StepResult<TContext = unknown, TData = unknown>
   branch: (
     branches: BranchSpec<TContext, TData>[]
   ) => BranchResult<TContext, TData>;
+  /** Shortcut to end the current route */
+  endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) => StepResult<TContext, TData>;
 }