@falai/agent 0.9.0-alpha-1 → 0.9.0-alpha-2

package/src/core/ToolExecutor.ts

@@ -17,18 +17,20 @@ export interface ToolExecutionResult {
 }
 
 export interface ExecuteToolParams<TContext = unknown, TData = unknown> {
-  tool: Tool<TContext, unknown[], unknown>;
+  tool: Tool<TContext, TData, unknown[], unknown>;
   context: TContext;
   updateContext: (updates: Partial<TContext>) => Promise<void>;
+  updateData: (updates: Partial<TData>) => Promise<void>;
   history: Event[];
   data?: Partial<TData>;
   toolArguments?: Record<string, unknown>;
 }
 
 export interface ExecuteToolsParams<TContext = unknown, TData = unknown> {
-  tools: Array<Tool<TContext, unknown[], unknown>>;
+  tools: Array<Tool<TContext, TData, unknown[], unknown>>;
   context: TContext;
   updateContext: (updates: Partial<TContext>) => Promise<void>;
+  updateData: (updates: Partial<TData>) => Promise<void>;
   history: Event[];
   data?: Partial<TData>;
 }
@@ -41,13 +43,14 @@ export class ToolExecutor<TContext = unknown, TData = unknown> {
   async executeTool(
     params: ExecuteToolParams<TContext, TData>
   ): Promise<ToolExecutionResult> {
-    const { tool, context, updateContext, history, data, toolArguments } =
+    const { tool, context, updateContext, updateData, history, data, toolArguments } =
       params;
     try {
-      // Build tool context with collected data
+      // Build tool context with complete agent data
       const toolContext: ToolContext<TContext, TData> = {
         context,
         updateContext,
+        updateData,
         history,
         data,
       };
@@ -55,6 +58,11 @@ export class ToolExecutor<TContext = unknown, TData = unknown> {
       // Execute tool
       const result = await tool.handler(toolContext, toolArguments);
 
+      // Apply data updates from tool result
+      if (result.dataUpdate) {
+        await updateData(result.dataUpdate);
+      }
+
       // Return execution result
       return {
         toolName: tool.id || "unknown",
@@ -79,7 +87,7 @@ export class ToolExecutor<TContext = unknown, TData = unknown> {
   async executeTools(
     params: ExecuteToolsParams<TContext, TData>
   ): Promise<ToolExecutionResult[]> {
-    const { tools, context, updateContext, history, data } = params;
+    const { tools, context, updateContext, updateData, history, data } = params;
     const results: ToolExecutionResult[] = [];
 
     for (const tool of tools) {
@@ -87,6 +95,7 @@ export class ToolExecutor<TContext = unknown, TData = unknown> {
         tool,
         context,
         updateContext,
+        updateData,
         history,
         data,
       });
@@ -105,6 +114,11 @@ export class ToolExecutor<TContext = unknown, TData = unknown> {
       if (result.contextUpdate) {
         await updateContext(result.contextUpdate as Partial<TContext>);
       }
+
+      // Apply data updates from tool result
+      if (result.dataUpdate) {
+        await updateData(result.dataUpdate as Partial<TData>);
+      }
     }
 
     return results;

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;
 }
@@ -170,3 +174,22 @@ export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
   };
   structured?: AgentStructuredResponse;
 }
+
+/**
+ * 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/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/session.ts

@@ -16,8 +16,7 @@ export function createSession<TData = Record<string, unknown>>(
 
   return {
     id,
-    data: {} as Partial<TData>,
-    dataByRoute: {},
+    data: {} as Partial<TData>, // Agent-level data structure
     routeHistory: [],
     metadata: {
       ...metadata,
@@ -44,23 +43,13 @@ export function cloneSession<TData>(
 
 /**
  * Helper to update session with new route
- * Preserves collected data per route in dataByRoute map
+ * With agent-level data, routes share the same data structure
  */
 export function enterRoute<TData = Record<string, unknown>>(
   session: SessionState<TData>,
   routeId: string,
   routeTitle: string
 ): SessionState<TData> {
-  // Save current route's collected data before switching (if any)
-  const dataByRoute = { ...session.dataByRoute };
-  if (
-    session.currentRoute &&
-    session.data &&
-    Object.keys(session.data).length > 0
-  ) {
-    dataByRoute[session.currentRoute.id] = session.data;
-  }
-
   // Exit current route if exists
   const routeHistory = [...(session.routeHistory || [])];
   if (session.currentRoute) {
@@ -72,10 +61,7 @@ export function enterRoute<TData = Record<string, unknown>>(
     }
   }
 
-  // Load collected data for new route (if resuming) or start fresh
-  const newCollected = dataByRoute[routeId] || {};
-
-  // Enter new route
+  // Enter new route - data persists across routes at agent level
   const now = new Date();
   return {
     ...session,
@@ -85,8 +71,7 @@ export function enterRoute<TData = Record<string, unknown>>(
       enteredAt: now,
     },
     currentStep: undefined,
-    data: newCollected, // Load route's data or start fresh
-    dataByRoute,
+    // data remains the same - shared across all routes
     routeHistory: [
       ...routeHistory,
       {
@@ -126,7 +111,7 @@ export function enterStep<TData = Record<string, unknown>>(
 
 /**
  * Helper to merge collected data into session
- * Updates both data and dataByRoute for current route
+ * Updates agent-level data structure
  */
 export function mergeCollected<TData = Record<string, unknown>>(
   session: SessionState<TData>,
@@ -137,16 +122,9 @@ export function mergeCollected<TData = Record<string, unknown>>(
     ...data,
   } as Partial<TData>;
 
-  // Also update the dataByRoute map for the current route
-  const dataByRoute = { ...session.dataByRoute };
-  if (session.currentRoute) {
-    dataByRoute[session.currentRoute.id] = newCollected;
-  }
-
   return {
     ...session,
-    data: newCollected,
-    dataByRoute,
+    data: newCollected, // Agent-level data update
     metadata: {
       ...session.metadata,
       lastUpdatedAt: new Date(),
@@ -170,7 +148,6 @@ export function sessionStepToData<TData = Record<string, unknown>>(
     currentStep: session.currentStep?.id,
     collectedData: {
       data: session.data || {},
-      dataByRoute: session.dataByRoute || {}, // Include per-route data
       routeHistory: session.routeHistory,
       history: session.history, // Include conversation history
       currentRouteTitle: session.currentRoute?.title,
@@ -196,7 +173,6 @@ export function sessionDataToStep<TData = Record<string, unknown>>(
 ): SessionState<TData> {
   const collectedData: CollectedStateData<TData> = data.collectedData || {
     data: {},
-    dataByRoute: {},
     routeHistory: [],
     history: [],
     metadata: {},
@@ -221,7 +197,6 @@ export function sessionDataToStep<TData = Record<string, unknown>>(
         }
       : undefined,
     data: collectedData.data || {},
-    dataByRoute: collectedData.dataByRoute || {},
     routeHistory: collectedData.routeHistory || [],
     history: collectedData.history || [],
     metadata: collectedData.metadata || {},