@falai/agent 0.9.0-alpha-1 → 0.9.0

package/src/types/agent.ts

@@ -7,6 +7,7 @@ import type { Tool } from "./tool";
 import type { RouteOptions } from "./route";
 import type { PersistenceConfig } from "./persistence";
 import type { SessionState } from "./session";
+import type { StructuredSchema } from "./schema";
 import { Template } from "./template";
 
 /**
@@ -26,7 +27,7 @@ export enum CompositionMode {
 /**
  * Context lifecycle hooks for managing step persistence
  */
-export interface ContextLifecycleHooks<TContext = unknown> {
+export interface ContextLifecycleHooks<TContext = unknown, TData = unknown> {
   /**
    * Called before respond() to get fresh context
    * Useful for loading context from a database or cache
@@ -47,13 +48,12 @@ export interface ContextLifecycleHooks<TContext = unknown> {
    * Useful for validation, enrichment, or persistence of collected data
    * Return modified collected data or the same data to keep it unchanged
    *
-   * Note: This hook works with ANY route's collected data (since an agent can have
-   * multiple routes with different extraction schemas). Use type guards or runtime
-   * checks if you need type-specific logic.
+   * Note: This hook now works with agent-level data collection (TData type)
    */
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  onDataUpdate?: (data: any, previousCollected: any) => any;
+  onDataUpdate?: (
+    data: Partial<TData>,
+    previousCollected: Partial<TData>
+  ) => Partial<TData> | Promise<Partial<TData>>;
 }
 
 /**
@@ -67,7 +67,7 @@ export type ContextProvider<TContext = unknown> = () =>
 /**
  * Options for creating an Agent
  */
-export interface AgentOptions<TContext = unknown> {
+export interface AgentOptions<TContext = unknown, TData = unknown> {
   /** Display name of the agent */
   name: string;
   /** Detailed description of the agent's purpose and personality */
@@ -89,47 +89,51 @@ export interface AgentOptions<TContext = unknown> {
   /** Context provider function for always-fresh context (alternative to static context) */
   contextProvider?: ContextProvider<TContext>;
   /** Lifecycle hooks for context management */
-  hooks?: ContextLifecycleHooks<TContext>;
+  hooks?: ContextLifecycleHooks<TContext, TData>;
   /** AI provider strategy for generating responses */
   provider: AiProvider;
   /** Composition mode for response generation */
   compositionMode?: CompositionMode;
   /** Initial terms for domain glossary */
-  terms?: Term<TContext>[];
+  terms?: Term<TContext, TData>[];
   /** Initial guidelines for agent behavior */
-  guidelines?: Guideline<TContext>[];
+  guidelines?: Guideline<TContext, TData>[];
   /** Global tools available to all routes */
-  tools?: Tool<TContext, unknown[], unknown, unknown>[];
+  tools?: Tool<TContext, TData, unknown[], unknown>[];
   /** Initial routes (will be instantiated as Route objects) */
-  routes?: RouteOptions<TContext, unknown>[];
+  routes?: RouteOptions<TContext, TData>[];
   /** Optional persistence configuration for auto-saving sessions and messages */
-  persistence?: PersistenceConfig;
+  persistence?: PersistenceConfig<TData>;
   /** Knowledge base containing any JSON structure the AI should know */
   knowledgeBase?: Record<string, unknown>;
+  /** Agent-level data schema defining the complete data structure for collection */
+  schema?: StructuredSchema;
+  /** Initial data to pre-populate when creating the agent */
+  initialData?: Partial<TData>;
 }
 
 /**
  * A term in the domain glossary
  */
-export interface Term<TContext = unknown> {
+export interface Term<TContext = unknown, TData = unknown> {
   /** Name of the term */
-  name: Template<TContext>;
+  name: Template<TContext, TData>;
   /** Description/definition of the term */
-  description: Template<TContext>;
+  description: Template<TContext, TData>;
   /** Alternative names or synonyms */
-  synonyms?: Template<TContext>[];
+  synonyms?: Template<TContext, TData>[];
 }
 
 /**
  * A behavioral guideline for the agent
  */
-export interface Guideline<TContext = unknown> {
+export interface Guideline<TContext = unknown, TData = unknown> {
   /** Unique identifier */
   id?: string;
   /** Condition that triggers this guideline (optional for always-active guidelines) */
-  condition?: Template<TContext>;
+  condition?: Template<TContext, TData>;
   /** Action the agent should take when the condition is met */
-  action: Template<TContext>;
+  action: Template<TContext, TData>;
   /** Whether this guideline is currently enabled */
   enabled?: boolean;
   /** Tags for organizing and filtering guidelines */
@@ -141,9 +145,9 @@ export interface Guideline<TContext = unknown> {
 /**
  * Guideline match with rationale
  */
-export interface GuidelineMatch<TContext = unknown> {
+export interface GuidelineMatch<TContext = unknown, TData = unknown> {
   /** The matched guideline */
-  guideline: Guideline<TContext>;
+  guideline: Guideline<TContext, TData>;
   /** Explanation of why this guideline was matched */
   rationale?: string;
 }
@@ -169,4 +173,24 @@ export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
     [key: string]: unknown;
   };
   structured?: AgentStructuredResponse;
+  error?: Error;
+}
+
+/**
+ * Validation error for data validation
+ */
+export interface ValidationError {
+  field: string;
+  value: unknown;
+  message: string;
+  schemaPath: string;
+}
+
+/**
+ * Result of data validation
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationError[];
 }

package/src/types/ai.ts

@@ -66,7 +66,7 @@ export interface GenerateMessageInput<TContext = unknown> {
 /**
  * Structured response from AI containing message and metadata
  */
-export interface AgentStructuredResponse {
+export interface AgentStructuredResponse extends Record<string, unknown> {
   /** The actual message to send to the user */
   message: string;
   /** Route chosen by the agent (route title or null if no route) */

package/src/types/index.ts

@@ -12,6 +12,8 @@ export type {
   AgentResponse,
   ContextLifecycleHooks,
   ContextProvider,
+  ValidationError,
+  ValidationResult,
 } from "./agent";
 export { CompositionMode } from "./agent";
 

package/src/types/persistence.ts

@@ -45,7 +45,6 @@ export type CreateSessionData<TData = Record<string, unknown>> = Omit<
  */
 export interface CollectedStateData<TData = Record<string, unknown>> {
   data: Partial<TData>;
-  dataByRoute: Record<string, Partial<TData>>;
   routeHistory: SessionState<TData>["routeHistory"];
   history?: SessionState<TData>["history"];
   currentRouteTitle?: string;

package/src/types/route.ts

@@ -104,7 +104,7 @@ export interface RouteOptions<TContext = unknown, TData = unknown> {
   /** Initial terms for the route's domain glossary */
   terms?: Term<TContext>[];
   /** Tools available in this route */
-  tools?: Tool<TContext, unknown[], unknown, TData>[];
+  tools?: Tool<TContext, TData, unknown[], unknown>[];
   /** Absolute rules the agent must follow in this route */
   rules?: Template<TContext, TData>[];
   /** Absolute prohibitions the agent must never do in this route */
@@ -114,14 +114,20 @@ export interface RouteOptions<TContext = unknown, TData = unknown> {
   /** Optional: structured response data for this route's message generation */
   responseOutputSchema?: StructuredSchema;
   /**
-   * NEW: Schema defining data to extract throughout this route
-   * This creates a type-safe contract for what data the route collects
+   * Required fields for route completion - must be valid keys from agent's TData type
+   * Route is considered complete when all required fields are present in agent data
    */
-  schema?: StructuredSchema;
+  requiredFields?: (keyof TData)[];
   /**
-   * NEW: Initial data to pre-populate when entering this route
+   * Optional fields that enhance the route but aren't required for completion
+   * Must be valid keys from agent's TData type
+   */
+  optionalFields?: (keyof TData)[];
+  /**
+   * Initial data to pre-populate when entering this route
    * Useful for restoring sessions or pre-filling known information
    * Steps with skipIf conditions will be automatically bypassed if data is present
+   * Now refers to agent-level data
    */
   initialData?: Partial<TData>;
   /**
@@ -191,37 +197,37 @@ 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, unknown[], unknown, TData>)[];
+  tools?: (string | Tool<TContext, TData, unknown[], unknown>)[];
   /** Programmatic function or tool to run before AI responds */
   prepare?:
     | string
-    | Tool<TContext, unknown[], unknown, TData>
+    | Tool<TContext, TData, unknown[], unknown>
     | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
   /** Programmatic function or tool to run after AI responds */
   finalize?:
     | string
-    | Tool<TContext, unknown[], unknown, TData>
+    | Tool<TContext, TData, unknown[], unknown>
     | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
   /** Transition to a specific step or end marker */
   step?: StepRef | symbol;
   /**
-   * NEW: Fields to collect from the conversation in this step
-   * These should match keys in the route's schema
+   * Fields to collect from the conversation in this step
+   * These should match keys in the agent's TData schema
    */
-  collect?: string[];
+  collect?: (keyof TData)[];
   /**
-   * NEW: Function to determine if this step should be skipped
+   * Function to determine if this step should be skipped
    * If returns true, the step will be bypassed
-   * @param data - Currently collected data
+   * @param data - Currently collected agent-level data
    * @returns true if step should be skipped, false otherwise
    */
   skipIf?: (data: Partial<TData>) => boolean;
   /**
-   * NEW: Required data fields that must be present before entering this step
+   * Required data fields that must be present before entering this step
    * If any required field is missing, step cannot be entered
-   * Uses string[] for developer-friendly usage (same as collect)
+   * Must be valid keys from agent's TData type
    */
-  requires?: string[];
+  requires?: (keyof TData)[];
   /**
    * Optional condition for this transition
    * Description of when this transition should be taken

package/src/types/session.ts

@@ -17,8 +17,8 @@ export interface PendingTransition {
 }
 
 /**
- * Session step tracks the current position in the conversation flow
- * and data collected during the route progression
+ * Session state tracks the current position in the conversation flow
+ * and data collected at the agent level across all routes
  */
 export interface SessionState<TData = unknown> {
   /** Unique session identifier (useful for persistence) */
@@ -39,17 +39,11 @@ export interface SessionState<TData = unknown> {
   };
 
   /**
-   * Data collected during the current route
-   * Convenience reference to dataByRoute[currentRoute.id]
+   * Agent-level data collected across all routes
+   * This is the single source of truth for all collected data
+   * Routes can access and contribute to this shared data structure
    */
-  data?: Partial<TData>;
-
-  /**
-   * Data collected organized by route ID
-   * Persists data when switching between routes
-   * Allows resuming incomplete routes where they left off
-   */
-  dataByRoute?: Record<string, Partial<TData>>;
+  data: Partial<TData>;
 
   /** History of routes visited in this session */
   routeHistory?: Array<{

package/src/types/tool.ts

@@ -12,11 +12,13 @@ export interface ToolContext<TContext = unknown, TData = unknown> {
   context: TContext;
   /** Update the agent's context (triggers lifecycle hooks if configured) */
   updateContext: (updates: Partial<TContext>) => Promise<void>;
+  /** Update the agent's collected data (triggers lifecycle hooks if configured) */
+  updateData: (updates: Partial<TData>) => Promise<void>;
   /** Current step reference (if in a route) */
   step?: StepRef;
   /** Interaction history */
   history: Event[];
-  /** Data collected so far in the current route */
+  /** Complete agent-level data collected so far */
   data?: Partial<TData>;
   /** Additional metadata */
   metadata?: Record<string, unknown>;
@@ -31,11 +33,15 @@ export interface ToolResult<
   TData = unknown
 > {
   /** The result data */
-  data: TResultData;
+  data?: TResultData;
   /** Optional context update to be merged with current context */
   contextUpdate?: Partial<TContext>;
-  /** Optional collected data update to be merged with session step */
+  /** Optional agent-level data update to be merged with collected data */
   dataUpdate?: Partial<TData>;
+  /** Success indicator */
+  success?: boolean;
+  /** Error message if operation failed */
+  error?: string;
   /** Optional metadata about the execution */
   meta?: Record<string, unknown>;
 }
@@ -45,9 +51,9 @@ export interface ToolResult<
  */
 export type ToolHandler<
   TContext,
-  TArgs extends unknown[],
-  TResult,
-  TData = unknown
+  TData = unknown,
+  TArgs extends unknown[] = unknown[],
+  TResult = unknown
 > = (
   context: ToolContext<TContext, TData>,
   ...args: TArgs
@@ -60,16 +66,16 @@ export type ToolHandler<
  */
 export interface Tool<
   TContext = unknown,
+  TData = unknown,
   TArgs extends unknown[] = unknown[],
-  TResult = unknown,
-  TData = unknown
+  TResult = unknown
 > {
   /** Tool identifier */
   id: string;
   /** Tool display name (shown to AI models) */
   name?: string;
   /** Tool handler function */
-  handler: ToolHandler<TContext, TArgs, TResult, TData>;
+  handler: ToolHandler<TContext, TData, TArgs, TResult>;
   /** Description of what the tool does (for AI discovery) */
   description?: string;
   /** Parameter schema or description */

package/src/utils/clone.ts

@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
+
 /**
  * Deep clone utility to avoid adding large dependencies like lodash.
  * Handles objects, arrays, dates, and primitives.
@@ -11,21 +11,19 @@ export function cloneDeep<T>(obj: T): T {
   }
 
   if (obj instanceof Date) {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    return new Date(obj.getTime()) as any;
+    return new Date(obj.getTime()) as T;
   }
 
   if (Array.isArray(obj)) {
-    const arrCopy = [] as any[];
+    const arrCopy: unknown[] = [];
     for (let i = 0; i < obj.length; i++) {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+       
       arrCopy[i] = cloneDeep(obj[i]);
     }
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    return arrCopy as any;
+    return arrCopy as T;
   }
 
-  const objCopy = {} as { [key: string]: any };
+  const objCopy: Record<string, unknown> = {};
   for (const key in obj) {
     if (Object.prototype.hasOwnProperty.call(obj, key)) {
       objCopy[key] = cloneDeep((obj as Record<string, unknown>)[key]);