@falai/agent 0.1.0-alpha2

package/src/types/persistence.ts

@@ -0,0 +1,251 @@
+/**
+ * Persistence-related type definitions
+ * Support for optional database persistence (Prisma, etc.)
+ */
+
+import type { Event, MessageRole } from "./history";
+import type { SessionState } from "./session";
+
+/**
+ * Session status enum
+ */
+export type SessionStatus = "active" | "completed" | "abandoned";
+
+/**
+ * Base session data structure
+ */
+export interface SessionData<TData = Record<string, unknown>> {
+  id: string;
+  userId?: string;
+  agentName?: string;
+  status: SessionStatus;
+  currentRoute?: string;
+  currentStep?: string;
+  collectedData?: CollectedStateData<TData>;
+  messageCount?: number;
+  lastMessageAt?: Date;
+  completedAt?: Date;
+  createdAt: Date;
+  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
+ */
+export interface MessageData {
+  id: string;
+  sessionId: string;
+  userId?: string;
+  role: MessageRole;
+  content: string;
+  route?: string;
+  step?: string;
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  event?: Event; // Optional: store full event data
+  createdAt: Date;
+}
+
+/**
+ * Repository interface for sessions
+ * Implement this interface with your database of choice
+ */
+export interface SessionRepository<TData = Record<string, unknown>> {
+  /**
+   * Create a new session
+   */
+  create(data: CreateSessionData<TData>): Promise<SessionData<TData>>;
+
+  /**
+   * Find session by ID
+   */
+  findById(id: string): Promise<SessionData<TData> | null>;
+
+  /**
+   * Find active session by user ID
+   */
+  findActiveByUserId(userId: string): Promise<SessionData<TData> | null>;
+
+  /**
+   * Find all sessions for a user
+   */
+  findByUserId(userId: string, limit?: number): Promise<SessionData<TData>[]>;
+
+  /**
+   * Update session
+   */
+  update(
+    id: string,
+    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>
+  ): Promise<SessionData<TData> | null>;
+
+  /**
+   * Update session status
+   */
+  updateStatus(
+    id: string,
+    status: SessionStatus,
+    completedAt?: Date
+  ): Promise<SessionData<TData> | null>;
+
+  /**
+   * Update collected data
+   */
+  updateCollectedData(
+    id: string,
+    collectedData: CollectedStateData<TData>
+  ): Promise<SessionData<TData> | null>;
+
+  /**
+   * Update current route and step
+   */
+  updateRouteStep(
+    id: string,
+    route?: string,
+    step?: string
+  ): Promise<SessionData<TData> | null>;
+
+  /**
+   * Increment message count
+   */
+  incrementMessageCount(id: string): Promise<SessionData<TData> | null>;
+
+  /**
+   * Delete session
+   */
+  delete(id: string): Promise<boolean>;
+}
+
+/**
+ * Repository interface for messages
+ * Implement this interface with your database of choice
+ */
+export interface MessageRepository {
+  /**
+   * Create a new message
+   */
+  create(data: Omit<MessageData, "id" | "createdAt">): Promise<MessageData>;
+
+  /**
+   * Find message by ID
+   */
+  findById(id: string): Promise<MessageData | null>;
+
+  /**
+   * Find all messages for a session
+   */
+  findBySessionId(sessionId: string, limit?: number): Promise<MessageData[]>;
+
+  /**
+   * Find messages for a user
+   */
+  findByUserId(userId: string, limit?: number): Promise<MessageData[]>;
+
+  /**
+   * Delete message by ID
+   */
+  delete(id: string): Promise<boolean>;
+
+  /**
+   * Delete all messages for a session
+   */
+  deleteBySessionId(sessionId: string): Promise<number>;
+
+  /**
+   * Delete all messages for a user
+   */
+  deleteByUserId(userId: string): Promise<number>;
+}
+
+/**
+ * Persistence adapter interface
+ * Implement this to create adapters for different databases
+ */
+export interface PersistenceAdapter<TData = Record<string, unknown>> {
+  /**
+   * Session repository
+   */
+  readonly sessionRepository: SessionRepository<TData>;
+
+  /**
+   * Message repository
+   */
+  readonly messageRepository: MessageRepository;
+
+  /**
+   * Initialize the adapter (create tables, indexes, etc.)
+   * Called automatically when adapter is created
+   */
+  initialize?(): Promise<void>;
+
+  /**
+   * Disconnect/cleanup resources
+   */
+  disconnect?(): Promise<void>;
+}
+
+/**
+ * Configuration for persistence
+ */
+export interface PersistenceConfig<TData = Record<string, unknown>> {
+  /**
+   * Persistence adapter instance (e.g., PrismaAdapter)
+   */
+  adapter: PersistenceAdapter<TData>;
+
+  /**
+   * Whether to auto-save messages (default: true)
+   */
+  autoSave?: boolean;
+
+  /**
+   * User ID to associate with sessions/messages
+   * Can also be provided per-call in methods
+   */
+  userId?: string;
+}
+
+/**
+ * Options for creating a session
+ */
+export interface CreateSessionOptions<TData = Record<string, unknown>> {
+  userId?: string;
+  agentName?: string;
+  initialData?: Partial<TData>;
+}
+
+/**
+ * Options for saving a message
+ */
+export interface SaveMessageOptions {
+  sessionId: string;
+  userId?: string;
+  role: MessageRole;
+  content: string;
+  route?: string;
+  step?: string;
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  event?: Event;
+}

package/src/types/route.ts

@@ -0,0 +1,272 @@
+/**
+ * Route/Journey DSL type definitions
+ */
+
+import type { Tool } from "./tool";
+import type { StructuredSchema } from "./schema";
+import type { Guideline, Term } from "./agent";
+import { Template, ConditionTemplate } from "./template";
+
+/**
+ * Reference to a route
+ */
+export interface RouteRef {
+  /** Route identifier */
+  id: string;
+}
+
+/**
+ * Reference to a step within a route
+ */
+export interface StepRef {
+  /** Step identifier */
+  id: string;
+  /** Route this step belongs to */
+  routeId: string;
+}
+
+/**
+ * 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<TContext = unknown, TData = unknown> {
+  /** Target route ID or title to transition to */
+  nextStep: string;
+  /** Optional AI-evaluated condition for the transition */
+  condition?: Template<TContext, TData>;
+}
+
+/**
+ * Function type for dynamic route completion transitions
+ * @param session - Current session step with collected data
+ * @param context - Agent context
+ * @returns Route ID/title to transition to, or transition config, or undefined to end
+ */
+export type RouteCompletionHandler<TContext = unknown, TData = unknown> = (
+  session: { data?: Partial<TData> },
+  context?: TContext
+) =>
+  | string
+  | RouteTransitionConfig<TContext, TData>
+  | undefined
+  | Promise<string | RouteTransitionConfig<TContext, TData> | undefined>;
+
+/**
+ * Options for creating a route
+ * @template TData - Type of data collected throughout the route (inferred from schema)
+ */
+export interface RouteOptions<TContext = unknown, TData = unknown> {
+  /** Custom ID for the route (optional - will generate deterministic ID from title if not provided) */
+  id?: string;
+  /** Title of the route */
+  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 */
+  when?: ConditionTemplate<TContext, TData>;
+  /** Conditions that prevent this route from being considered */
+  skipIf?: ConditionTemplate<TContext, TData>;
+  /** Initial guidelines for this route */
+  guidelines?: Guideline<TContext, TData>[];
+  /** Initial terms for the route's domain glossary */
+  terms?: Term<TContext>[];
+  /** Tools available in this route */
+  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 */
+  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;
+  /**
+   * 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
+   */
+  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>;
+  /**
+   * NEW: Sequential steps for simple linear flows
+   * If provided, automatically chains the steps from initialStep to END_ROUTE
+   * For complex flows with branching, build the step machine manually instead
+   */
+  steps?: StepOptions<TContext, TData>[];
+  /**
+   * Configure the initial step (optional)
+   * Accepts full StepOptions configuration (id, prompt, collect, skipIf, etc.)
+   * Note: tool and step properties are ignored for initial step
+   */
+  initialStep?: Omit<StepOptions<TContext, TData>, "step">;
+  /**
+   * Configure the end step (optional)
+   * Defines what happens when the route completes (reaches END_ROUTE)
+   * Can include prompt for completion message, tool for final actions, etc.
+   * Note: step, condition, skipIf properties are ignored for end step
+   */
+  endStep?: Omit<StepOptions<TContext, TData>, "step" | "condition" | "skipIf">;
+  /**
+   * Optional transition when route completes (reaches END_ROUTE)
+   * Can be:
+   * - String: Route ID or title to transition to
+   * - Object: Transition config with optional AI-evaluated condition
+   * - Function: Dynamic logic that returns route ID, config, or undefined
+   *
+   * @example
+   * // Simple string
+   * onComplete: "feedback-collection"
+   *
+   * @example
+   * // With condition
+   * onComplete: {
+   *   nextStep: "feedback-collection",
+   *   condition: "if booking succeeded"
+   * }
+   *
+   * @example
+   * // Dynamic function
+   * onComplete: (session) => {
+   *   if (session.data?.success) return "feedback";
+   *   return "error-recovery";
+   * }
+   */
+  onComplete?:
+    | string
+    | 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>;
+}
+
+/**
+ * Specification for a step transition
+ */
+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 */
+  prompt?: Template<TContext, TData>;
+  /** Tools available for AI to call in this step (by ID reference or inline definition) */
+  tools?: (string | Tool<TContext, TData>)[];
+  /** Programmatic function or tool to run before AI responds */
+  prepare?:
+    | string
+    | 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>
+    | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+  /** Transition to a specific step or end marker */
+  step?: StepRef | symbol;
+  /**
+   * Fields to collect from the conversation in this step
+   * These should match keys in the agent's TData schema
+   */
+  collect?: (keyof TData)[];
+  /**
+   * 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?: ConditionTemplate<TContext, TData>;
+  /**
+   * Required data fields that must be present before entering this step
+   * If any required field is missing, step cannot be entered
+   * Must be valid keys from agent's TData type
+   */
+  requires?: (keyof TData)[];
+  /**
+   * Optional condition for this transition
+   * Description of when this transition should be taken
+   * Supports strings (AI context), functions (programmatic), and arrays
+   */
+  when?: ConditionTemplate<TContext, TData>;
+  /** Initial guidelines for this step */
+  guidelines?: Guideline<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 and create branches
+ */
+export interface StepResult<TContext = unknown, TData = unknown>
+  extends StepRef {
+  /** Allow chaining transitions */
+  nextStep: (spec: StepOptions<TContext, TData>) => StepResult<TContext, TData>;
+  /** Create multiple branches from this step */
+  branch: (
+    branches: BranchSpec<TContext, TData>[]
+  ) => BranchResult<TContext, TData>;
+  /** Shortcut to end the current route */
+  endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) => StepResult<TContext, TData>;
+}

package/src/types/routing.ts

@@ -0,0 +1,18 @@
+import type { StructuredSchema } from "./schema";
+
+export interface RoutingDecision {
+  context: string;
+  routes: Record<string, number>;
+  responseDirectives?: string[];
+  extractions?: unknown;
+  contextUpdate?: Record<string, unknown>;
+}
+
+export interface RoutingDecisionWithRoute extends RoutingDecision {
+  selectedRouteId: string;
+  maxScore: number;
+}
+
+export interface RoutingSchemaOptions {
+  extrasSchema?: StructuredSchema;
+}

package/src/types/schema.ts

@@ -0,0 +1,23 @@
+/**
+ * StructuredSchema - minimal JSON Schema subset used across providers
+ */
+export interface StructuredSchema {
+  type?: string | string[];
+  description?: string;
+  enum?: Array<string | number | boolean | null>;
+  nullable?: boolean;
+  properties?: Record<string, StructuredSchema>;
+  required?: string[];
+  items?: StructuredSchema;
+  additionalProperties?: boolean | StructuredSchema;
+  // Allow provider-specific passthroughs without breaking types
+  [key: string]: unknown;
+}
+
+/**
+ * A small helper describing a named schema (for providers that require a name)
+ */
+export interface NamedSchema {
+  name?: string;
+  schema: StructuredSchema;
+}

package/src/types/session.ts

@@ -0,0 +1,74 @@
+/**
+ * Session step types for tracking conversation progress
+ */
+
+import type { History } from "./history";
+
+/**
+ * Pending route transition information
+ */
+export interface PendingTransition {
+  /** Target route ID to transition to */
+  targetRouteId: string;
+  /** Optional AI-evaluated condition for the transition */
+  condition?: string;
+  /** Reason for the transition */
+  reason: "route_complete" | "manual";
+}
+
+/**
+ * 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) */
+  id: string;
+
+  /** Current route the conversation is in */
+  currentRoute?: {
+    id: string;
+    title: string;
+    enteredAt?: Date;
+  };
+
+  /** Current step within the route */
+  currentStep?: {
+    id: string;
+    description?: string;
+    enteredAt?: Date;
+  };
+
+  /**
+   * 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>;
+
+  /** History of routes visited in this session */
+  routeHistory?: Array<{
+    routeId: string;
+    enteredAt?: Date;
+    exitedAt?: Date;
+    completed: boolean;
+  }>;
+
+  /**
+   * Pending route transition after completion
+   * Set when a route completes with onComplete handler
+   */
+  pendingTransition?: PendingTransition;
+
+  /**
+   * Conversation history managed by the session
+   * Contains the full conversation between user and assistant
+   */
+  history?: History;
+
+  /** Session metadata */
+  metadata?: {
+    createdAt?: Date;
+    lastUpdatedAt?: Date;
+    [key: string]: unknown;
+  };
+}