@falai/agent 0.8.1 → 0.9.0-alpha-2

package/src/types/index.ts

@@ -7,8 +7,13 @@ export type {
   AgentOptions,
   Term,
   Guideline,
-  Capability,
   GuidelineMatch,
+  AgentResponseStreamChunk,
+  AgentResponse,
+  ContextLifecycleHooks,
+  ContextProvider,
+  ValidationError,
+  ValidationResult,
 } from "./agent";
 export { CompositionMode } from "./agent";
 
@@ -22,38 +27,71 @@ export type {
   Participant,
   ToolResult as EventToolResult,
   ToolCall,
+  HistoryMessage,
+  Role,
+  HistoryItem,
+  History,
+  UserHistoryItem,
+  AssistantHistoryItem,
+  SystemHistoryItem,
+  ToolHistoryItem,
 } from "./history";
-export { EventKind, EventSource } from "./history";
+export { EventKind, MessageRole } from "./history";
+export * from "./history";
 
 // Route types
 export type {
+  RouteOptions,
   RouteRef,
   StepRef,
-  RouteOptions,
-  TransitionSpec,
-  TransitionResult,
+  StepOptions,
+  StepResult,
+  BranchSpec,
+  BranchResult,
+  RouteCompletionHandler,
+  RouteTransitionConfig,
+  RouteLifecycleHooks,
 } from "./route";
+export * from "./route";
+
+// Session types
+export type { SessionState, PendingTransition } from "./session";
 
 // Tool types
-export type { ToolContext, ToolResult, ToolHandler, ToolRef } from "./tool";
+export type { Tool, ToolContext, ToolResult, ToolHandler } from "./tool";
 
 // AI provider types
 export type {
   AiProvider,
   GenerateMessageInput,
   GenerateMessageOutput,
+  AgentStructuredResponse,
+  ReasoningConfig,
+  GenerateMessageStreamChunk,
 } from "./ai";
 
+// Schema types
+export type { StructuredSchema } from "./schema";
+
+// Routing types
+export type { RoutingDecision } from "./routing";
+export * from "./routing";
+
 // Persistence types
 export type {
   SessionData,
   MessageData,
   SessionStatus,
-  MessageRole,
   SessionRepository,
   MessageRepository,
   PersistenceAdapter,
   PersistenceConfig,
   CreateSessionOptions,
+  CreateSessionData,
   SaveMessageOptions,
+  CollectedStateData,
 } from "./persistence";
+export * from "./persistence";
+
+// Template types
+export type { Template, TemplateContext } from "./template";

package/src/types/persistence.ts

@@ -3,29 +3,25 @@
  * Support for optional database persistence (Prisma, etc.)
  */
 
-import type { Event } from "./history";
+import type { Event, MessageRole } from "./history";
+import type { SessionState } from "./session";
 
 /**
  * Session status enum
  */
 export type SessionStatus = "active" | "completed" | "abandoned";
 
-/**
- * Message role enum
- */
-export type MessageRole = "user" | "agent" | "system";
-
 /**
  * Base session data structure
  */
-export interface SessionData {
+export interface SessionData<TData = Record<string, unknown>> {
   id: string;
   userId?: string;
   agentName?: string;
   status: SessionStatus;
   currentRoute?: string;
   currentStep?: string;
-  collectedData?: Record<string, unknown>;
+  collectedData?: CollectedStateData<TData>;
   messageCount?: number;
   lastMessageAt?: Date;
   completedAt?: Date;
@@ -33,6 +29,29 @@ export interface SessionData {
   updatedAt: Date;
 }
 
+/**
+ * Data for creating a new session (subset of SessionData)
+ */
+export type CreateSessionData<TData = Record<string, unknown>> = Omit<
+  SessionData<TData>,
+  "id" | "createdAt" | "updatedAt"
+> & {
+  id?: string;
+};
+
+/**
+ * Structure for data collected during a session that needs to be persisted.
+ * This is a subset of SessionState, stored within SessionData.
+ */
+export interface CollectedStateData<TData = Record<string, unknown>> {
+  data: Partial<TData>;
+  routeHistory: SessionState<TData>["routeHistory"];
+  history?: SessionState<TData>["history"];
+  currentRouteTitle?: string;
+  currentStepDescription?: string;
+  metadata: SessionState<TData>["metadata"];
+}
+
 /**
  * Base message data structure
  */
@@ -53,36 +72,34 @@ export interface MessageData {
  * Repository interface for sessions
  * Implement this interface with your database of choice
  */
-export interface SessionRepository {
+export interface SessionRepository<TData = Record<string, unknown>> {
   /**
    * Create a new session
    */
-  create(
-    data: Omit<SessionData, "id" | "createdAt" | "updatedAt">
-  ): Promise<SessionData>;
+  create(data: CreateSessionData<TData>): Promise<SessionData<TData>>;
 
   /**
    * Find session by ID
    */
-  findById(id: string): Promise<SessionData | null>;
+  findById(id: string): Promise<SessionData<TData> | null>;
 
   /**
    * Find active session by user ID
    */
-  findActiveByUserId(userId: string): Promise<SessionData | null>;
+  findActiveByUserId(userId: string): Promise<SessionData<TData> | null>;
 
   /**
    * Find all sessions for a user
    */
-  findByUserId(userId: string, limit?: number): Promise<SessionData[]>;
+  findByUserId(userId: string, limit?: number): Promise<SessionData<TData>[]>;
 
   /**
    * Update session
    */
   update(
     id: string,
-    data: Partial<Omit<SessionData, "id" | "createdAt">>
-  ): Promise<SessionData | null>;
+    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>
+  ): Promise<SessionData<TData> | null>;
 
   /**
    * Update session status
@@ -91,15 +108,15 @@ export interface SessionRepository {
     id: string,
     status: SessionStatus,
     completedAt?: Date
-  ): Promise<SessionData | null>;
+  ): Promise<SessionData<TData> | null>;
 
   /**
    * Update collected data
    */
   updateCollectedData(
     id: string,
-    collectedData: Record<string, unknown>
-  ): Promise<SessionData | null>;
+    collectedData: CollectedStateData<TData>
+  ): Promise<SessionData<TData> | null>;
 
   /**
    * Update current route and step
@@ -108,12 +125,12 @@ export interface SessionRepository {
     id: string,
     route?: string,
     step?: string
-  ): Promise<SessionData | null>;
+  ): Promise<SessionData<TData> | null>;
 
   /**
    * Increment message count
    */
-  incrementMessageCount(id: string): Promise<SessionData | null>;
+  incrementMessageCount(id: string): Promise<SessionData<TData> | null>;
 
   /**
    * Delete session
@@ -166,11 +183,11 @@ export interface MessageRepository {
  * Persistence adapter interface
  * Implement this to create adapters for different databases
  */
-export interface PersistenceAdapter {
+export interface PersistenceAdapter<TData = Record<string, unknown>> {
   /**
    * Session repository
    */
-  readonly sessionRepository: SessionRepository;
+  readonly sessionRepository: SessionRepository<TData>;
 
   /**
    * Message repository
@@ -192,11 +209,11 @@ export interface PersistenceAdapter {
 /**
  * Configuration for persistence
  */
-export interface PersistenceConfig {
+export interface PersistenceConfig<TData = Record<string, unknown>> {
   /**
    * Persistence adapter instance (e.g., PrismaAdapter)
    */
-  adapter: PersistenceAdapter;
+  adapter: PersistenceAdapter<TData>;
 
   /**
    * Whether to auto-save messages (default: true)
@@ -213,10 +230,10 @@ export interface PersistenceConfig {
 /**
  * Options for creating a session
  */
-export interface CreateSessionOptions {
+export interface CreateSessionOptions<TData = Record<string, unknown>> {
   userId?: string;
   agentName?: string;
-  initialData?: Record<string, unknown>;
+  initialData?: Partial<TData>;
 }
 
 /**

package/src/types/route.ts

@@ -2,8 +2,9 @@
  * Route/Journey DSL type definitions
  */
 
-import type { ToolRef, ToolResult } from "./tool";
+import type { Tool } from "./tool";
 import type { StructuredSchema } from "./schema";
+import { Template } from "./template";
 
 /**
  * Reference to a route
@@ -24,18 +25,46 @@ export interface StepRef {
 }
 
 /**
- * Forward declare Guideline for circular dependency
+ * Forward declare Guideline and Term for circular dependency
  */
-import type { Guideline } from "./agent";
+import type { Guideline, Term } from "./agent";
+
+/**
+ * Route lifecycle hooks for managing route-specific data and behavior
+ */
+export interface RouteLifecycleHooks<TContext = unknown, TData = unknown> {
+  /**
+   * Called after collected data is updated for this route (from AI response or tool execution)
+   * Useful for validation, enrichment, or persistence of route-specific collected data
+   * Return modified collected data or the same data to keep it unchanged
+   *
+   * Unlike Agent-level onDataUpdate, this only triggers for data changes in this specific route.
+   */
+  onDataUpdate?: (
+    data: Partial<TData>,
+    previousCollected: Partial<TData>
+  ) => Partial<TData> | Promise<Partial<TData>>;
+
+  /**
+   * Called after context is updated via updateContext() when this route is active
+   * Useful for route-specific context reactions, validation, or side effects
+   *
+   * Unlike Agent-level onContextUpdate, this only triggers when this specific route is active.
+   */
+  onContextUpdate?: (
+    newContext: TContext,
+    previousContext: TContext
+  ) => void | Promise<void>;
+}
 
 /**
  * Route transition configuration when route completes
  */
-export interface RouteTransitionConfig {
+export interface RouteTransitionConfig<TContext = unknown, TData = unknown> {
   /** Target route ID or title to transition to */
   nextStep: string;
   /** Optional AI-evaluated condition for the transition */
-  condition?: string;
+  condition?: Template<TContext, TData>;
 }
 
 /**
@@ -49,9 +78,9 @@ export type RouteCompletionHandler<TContext = unknown, TData = unknown> = (
   context?: TContext
 ) =>
   | string
-  | RouteTransitionConfig
+  | RouteTransitionConfig<TContext, TData>
   | undefined
-  | Promise<string | RouteTransitionConfig | undefined>;
+  | Promise<string | RouteTransitionConfig<TContext, TData> | undefined>;
 
 /**
  * Options for creating a route
@@ -64,29 +93,41 @@ export interface RouteOptions<TContext = unknown, TData = unknown> {
   title: string;
   /** Description of what this route accomplishes */
   description?: string;
+  /** Optional identity prompt defining the agent's role and persona for this route */
+  identity?: Template<TContext, TData>;
+  /** Optional personality prompt defining the agent's communication style for this route */
+  personality?: Template<TContext, TData>;
   /** Conditions that activate this route */
-  conditions?: string[];
+  conditions?: Template<TContext, TData>[];
   /** Initial guidelines for this route */
-  guidelines?: Guideline[];
-  /** Domain names that are allowed in this route (undefined = all domains) */
-  domains?: string[];
+  guidelines?: Guideline<TContext>[];
+  /** Initial terms for the route's domain glossary */
+  terms?: Term<TContext>[];
+  /** Tools available in this route */
+  tools?: Tool<TContext, TData, unknown[], unknown>[];
   /** Absolute rules the agent must follow in this route */
-  rules?: string[];
+  rules?: Template<TContext, TData>[];
   /** Absolute prohibitions the agent must never do in this route */
-  prohibitions?: string[];
+  prohibitions?: Template<TContext, TData>[];
   /** Optional: extractions the router may return (added to routing schema) */
   routingExtrasSchema?: StructuredSchema;
   /** 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
+   */
+  requiredFields?: (keyof TData)[];
+  /**
+   * Optional fields that enhance the route but aren't required for completion
+   * Must be valid keys from agent's TData type
    */
-  schema?: StructuredSchema;
+  optionalFields?: (keyof TData)[];
   /**
-   * NEW: Initial data to pre-populate when entering this route
+   * 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>;
   /**
@@ -94,26 +135,20 @@ export interface RouteOptions<TContext = unknown, TData = unknown> {
    * If provided, automatically chains the steps from initialStep to END_ROUTE
    * For complex flows with branching, build the step machine manually instead
    */
-  steps?: TransitionSpec<TContext, TData>[];
+  steps?: StepOptions<TContext, TData>[];
   /**
    * Configure the initial step (optional)
-   * Accepts full TransitionSpec configuration (id, instructions, collect, skipIf, etc.)
+   * Accepts full StepOptions configuration (id, prompt, collect, skipIf, etc.)
    * Note: tool and step properties are ignored for initial step
    */
-  initialStep?: Omit<
-    TransitionSpec<TContext, TData>,
-    "tool" | "step" | "condition"
-  >;
+  initialStep?: Omit<StepOptions<TContext, TData>, "step">;
   /**
    * Configure the end step (optional)
    * Defines what happens when the route completes (reaches END_ROUTE)
-   * Can include instructions for completion message, tool for final actions, etc.
+   * Can include prompt for completion message, tool for final actions, etc.
    * Note: step, condition, skipIf properties are ignored for end step
    */
-  endStep?: Omit<
-    TransitionSpec<TContext, TData>,
-    "step" | "condition" | "skipIf"
-  >;
+  endStep?: Omit<StepOptions<TContext, TData>, "step" | "condition" | "skipIf">;
   /**
    * Optional transition when route completes (reaches END_ROUTE)
    * Can be:
@@ -141,65 +176,95 @@ export interface RouteOptions<TContext = unknown, TData = unknown> {
    */
   onComplete?:
     | string
-    | RouteTransitionConfig
+    | RouteTransitionConfig<TContext, TData>
     | RouteCompletionHandler<TContext, TData>;
+  /**
+   * Route lifecycle hooks
+   */
+  hooks?: RouteLifecycleHooks<TContext, TData>;
+  /** Knowledge base specific to this route containing any JSON structure the AI should know */
+  knowledgeBase?: Record<string, unknown>;
 }
 
-/**
- * Inline tool handler for dynamic tool generation
- */
-export type InlineToolHandler<TContext = unknown, TData = unknown> = (
-  context: import("./tool").ToolContext<TContext, TData>
-) =>
-  | ToolResult<unknown, TContext, TData>
-  | Promise<ToolResult<unknown, TContext, TData>>;
-
 /**
  * Specification for a step transition
  */
-export interface TransitionSpec<TContext = unknown, TData = unknown> {
+export interface StepOptions<TContext = unknown, TData = unknown> {
   /** Custom ID for this step (optional - will generate deterministic ID if not provided) */
   id?: string;
+  /** Description of the transition */
+  description?: string;
   /** Transition to a chat state with this description */
-  instructions?: string;
-  /** Transition to execute a tool */
-  tool?: // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ToolRef<TContext, any[], any, TData> | InlineToolHandler<TContext, TData>;
+  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>)[];
+  /** Programmatic function or tool to run before AI responds */
+  prepare?:
+    | string
+    | 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, 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
    */
-  condition?: string;
+  when?: Template<TContext, TData>;
+}
+
+/**
+ * Specification for a branch in the conversation flow
+ */
+export interface BranchSpec<TContext = unknown, TData = unknown> {
+  /** User-friendly identifier for this branch (used as object key) */
+  name: string;
+  /** Optional ID for this branch (auto-generated if not provided) */
+  id?: string;
+  /** Step configuration for this branch */
+  step: StepOptions<TContext, TData>;
+}
+
+/**
+ * Result of a branch operation
+ * Maps branch names to their respective step results for continued chaining
+ */
+export interface BranchResult<TContext = unknown, TData = unknown> {
+  [branchName: string]: StepResult<TContext, TData>;
 }
 
 /**
  * Result of a transition operation
- * Combines step reference with the ability to chain transitions
+ * Combines step reference with the ability to chain transitions and create branches
  */
-export interface TransitionResult<TContext = unknown, TData = unknown>
+export interface StepResult<TContext = unknown, TData = unknown>
   extends StepRef {
   /** Allow chaining transitions */
-  nextStep: (
-    spec: TransitionSpec<TContext, TData>
-  ) => TransitionResult<TContext, TData>;
+  nextStep: (spec: StepOptions<TContext, TData>) => StepResult<TContext, TData>;
+  /** Create multiple branches from this step */
+  branch: (
+    branches: BranchSpec<TContext, TData>[]
+  ) => BranchResult<TContext, TData>;
 }