@falai/agent 0.8.1 → 0.9.0-alpha-1

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,30 @@ 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>;
+  dataByRoute: Record<string, Partial<TData>>;
+  routeHistory: SessionState<TData>["routeHistory"];
+  history?: SessionState<TData>["history"];
+  currentRouteTitle?: string;
+  currentStepDescription?: string;
+  metadata: SessionState<TData>["metadata"];
+}
+
 /**
  * Base message data structure
  */
@@ -53,36 +73,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 +109,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 +126,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 +184,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 +210,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 +231,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,16 +93,22 @@ 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, unknown[], unknown, TData>[];
   /** 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 */
@@ -94,26 +129,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,30 +170,38 @@ 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, unknown[], unknown, TData>)[];
+  /** Programmatic function or tool to run before AI responds */
+  prepare?:
+    | string
+    | Tool<TContext, unknown[], unknown, TData>
+    | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+  /** Programmatic function or tool to run after AI responds */
+  finalize?:
+    | string
+    | Tool<TContext, unknown[], unknown, TData>
+    | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
   /** Transition to a specific step or end marker */
   step?: StepRef | symbol;
   /**
@@ -189,17 +226,39 @@ export interface TransitionSpec<TContext = unknown, TData = unknown> {
    * 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>;
 }

package/src/types/session.ts

@@ -2,6 +2,8 @@
  * Session step types for tracking conversation progress
  */
 
+import type { History } from "./history";
+
 /**
  * Pending route transition information
  */
@@ -18,41 +20,41 @@ export interface PendingTransition {
  * Session step tracks the current position in the conversation flow
  * and data collected during the route progression
  */
-export interface SessionState<TData = Record<string, unknown>> {
+export interface SessionState<TData = unknown> {
   /** Unique session identifier (useful for persistence) */
-  id?: string;
+  id: string;
 
   /** Current route the conversation is in */
   currentRoute?: {
     id: string;
     title: string;
-    enteredAt: Date;
+    enteredAt?: Date;
   };
 
   /** Current step within the route */
   currentStep?: {
     id: string;
     description?: string;
-    enteredAt: Date;
+    enteredAt?: Date;
   };
 
   /**
    * Data collected during the current route
-   * This is a convenience reference to dataByRoute[currentRoute.id]
+   * Convenience reference to dataByRoute[currentRoute.id]
    */
   data?: Partial<TData>;
 
   /**
-   * Collected data organized by route ID
-   * Preserves data when switching between routes
-   * Format: { "routeId": { ...dataData } }
+   * Data collected organized by route ID
+   * Persists data when switching between routes
+   * Allows resuming incomplete routes where they left off
    */
-  dataByRoute?: Record<string, Partial<unknown>>;
+  dataByRoute?: Record<string, Partial<TData>>;
 
   /** History of routes visited in this session */
-  routeHistory: Array<{
+  routeHistory?: Array<{
     routeId: string;
-    enteredAt: Date;
+    enteredAt?: Date;
     exitedAt?: Date;
     completed: boolean;
   }>;
@@ -63,6 +65,12 @@ export interface SessionState<TData = Record<string, unknown>> {
    */
   pendingTransition?: PendingTransition;
 
+  /**
+   * Conversation history managed by the session
+   * Contains the full conversation between user and assistant
+   */
+  history?: History;
+
   /** Session metadata */
   metadata?: {
     createdAt?: Date;
@@ -70,205 +78,3 @@ export interface SessionState<TData = Record<string, unknown>> {
     [key: string]: unknown;
   };
 }
-
-/**
- * Helper to create a new session
- * @param sessionId - Optional session ID (e.g., from database)
- * @param metadata - Optional metadata to attach
- */
-export function createSession<TData = Record<string, unknown>>(
-  sessionId?: string,
-  metadata?: SessionState<TData>["metadata"]
-): SessionState<TData> {
-  return {
-    id: sessionId,
-    data: {},
-    dataByRoute: {},
-    routeHistory: [],
-    metadata: {
-      ...metadata,
-      createdAt: new Date(),
-      lastUpdatedAt: new Date(),
-    },
-  };
-}
-
-/**
- * Helper to update session with new route
- * Preserves collected data per route in dataByRoute map
- */
-export function enterRoute<TData = Record<string, unknown>>(
-  session: SessionState<TData>,
-  routeId: string,
-  routeTitle: string
-): SessionState<TData> {
-  // Save current route's collected data before switching
-  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) {
-    const lastRouteIndex = routeHistory.findIndex(
-      (r) => r.routeId === session.currentRoute?.id && !r.exitedAt
-    );
-    if (lastRouteIndex >= 0) {
-      routeHistory[lastRouteIndex].exitedAt = new Date();
-    }
-  }
-
-  // Load collected data for new route (if resuming) or start fresh
-  const newCollected = (dataByRoute[routeId] as Partial<TData>) || {};
-
-  // Enter new route
-  const now = new Date();
-  return {
-    ...session,
-    currentRoute: {
-      id: routeId,
-      title: routeTitle,
-      enteredAt: now,
-    },
-    currentStep: undefined,
-    data: newCollected, // Load route's data or start fresh
-    dataByRoute,
-    routeHistory: [
-      ...routeHistory,
-      {
-        routeId,
-        enteredAt: now,
-        completed: false,
-      },
-    ],
-    metadata: {
-      ...session.metadata,
-      lastUpdatedAt: now,
-    },
-  };
-}
-
-/**
- * Helper to update session with new step
- */
-export function enterStep<TData = Record<string, unknown>>(
-  session: SessionState<TData>,
-  stepId: string,
-  stepDescription?: string
-): SessionState<TData> {
-  return {
-    ...session,
-    currentStep: {
-      id: stepId,
-      description: stepDescription,
-      enteredAt: new Date(),
-    },
-    metadata: {
-      ...session.metadata,
-      lastUpdatedAt: new Date(),
-    },
-  };
-}
-
-/**
- * Helper to merge collected data into session
- * Updates both the data field and the dataByRoute map
- */
-export function mergeCollected<TData = Record<string, unknown>>(
-  session: SessionState<TData>,
-  data: Partial<unknown>
-): SessionState<TData> {
-  const newCollected = {
-    ...session.data,
-    ...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,
-    metadata: {
-      ...session.metadata,
-      lastUpdatedAt: new Date(),
-    },
-  };
-}
-
-/**
- * Helper to convert SessionState to persistence-friendly format
- * Used when saving to database
- */
-export function sessionStepToData<TData = Record<string, unknown>>(
-  session: SessionState<TData>
-): {
-  currentRoute?: string;
-  currentStep?: string;
-  collectedData: Record<string, unknown>;
-} {
-  return {
-    currentRoute: session.currentRoute?.id,
-    currentStep: session.currentStep?.id,
-    collectedData: {
-      data: session.data,
-      dataByRoute: session.dataByRoute, // Include per-route data
-      routeHistory: session.routeHistory,
-      currentRouteTitle: session.currentRoute?.title,
-      currentStepDescription: session.currentStep?.description,
-      metadata: session.metadata,
-    },
-  };
-}
-
-/**
- * Helper to convert database SessionData back to SessionState
- * Used when loading from database
- * @param sessionId - The database session ID
- * @param data - The database session data
- */
-export function sessionDataToStep<TData = Record<string, unknown>>(
-  sessionId: string,
-  data: {
-    currentRoute?: string;
-    currentStep?: string;
-    collectedData?: Record<string, unknown>;
-  }
-): SessionState<TData> {
-  const collectedData = data.collectedData || {};
-
-  return {
-    id: sessionId,
-    currentRoute: data.currentRoute
-      ? {
-          id: data.currentRoute,
-          title:
-            (collectedData.currentRouteTitle as string) || data.currentRoute,
-          enteredAt: new Date(),
-        }
-      : undefined,
-    currentStep: data.currentStep
-      ? {
-          id: data.currentStep,
-          description:
-            (collectedData.currentStepDescription as string) || undefined,
-          enteredAt: new Date(),
-        }
-      : undefined,
-    data: (collectedData.data as Partial<TData>) || {},
-    dataByRoute:
-      (collectedData.dataByRoute as Record<string, Partial<unknown>>) || {}, // Restore per-route data
-    routeHistory:
-      (collectedData.routeHistory as SessionState<TData>["routeHistory"]) || [],
-    metadata: (collectedData.metadata as SessionState<TData>["metadata"]) || {},
-  };
-}