@falai/agent 0.1.0-alpha2

package/src/types/agent.ts

@@ -0,0 +1,196 @@
+/**
+ * Agent-related type definitions
+ */
+
+import type { AgentStructuredResponse, AiProvider } from "./ai";
+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, ConditionTemplate } from "./template";
+
+/**
+ * Composition mode determines how the agent processes and structures responses
+ */
+export enum CompositionMode {
+  /** Fluid, natural conversation without strict structure */
+  FLUID = "fluid",
+  /** Canned responses with fluid fallback */
+  CANNED_FLUID = "canned_fluid",
+  /** Composited canned responses */
+  CANNED_COMPOSITED = "composited_canned",
+  /** Strict canned responses only */
+  CANNED_STRICT = "strict_canned",
+}
+
+/**
+ * Context lifecycle hooks for managing step persistence
+ */
+export interface ContextLifecycleHooks<TContext = unknown, TData = unknown> {
+  /**
+   * Called before respond() to get fresh context
+   * Useful for loading context from a database or cache
+   */
+  beforeRespond?: (currentContext: TContext) => Promise<TContext> | TContext;
+
+  /**
+   * Called after context is updated via updateContext() or tool execution
+   * Useful for persisting context to a database or cache
+   */
+  onContextUpdate?: (
+    newContext: TContext,
+    previousContext: TContext
+  ) => Promise<void> | void;
+
+  /**
+   * Called after collected data is updated (from AI response or tool execution)
+   * Useful for validation, enrichment, or persistence of collected data
+   * Return modified collected data or the same data to keep it unchanged
+   *
+   * Note: This hook now works with agent-level data collection (TData type)
+   */
+  onDataUpdate?: (
+    data: Partial<TData>,
+    previousCollected: Partial<TData>
+  ) => Partial<TData> | Promise<Partial<TData>>;
+}
+
+/**
+ * Context provider function for always-fresh context
+ * Alternative to static context, useful for loading from external sources
+ */
+export type ContextProvider<TContext = unknown> = () =>
+  | Promise<TContext>
+  | TContext;
+
+/**
+ * Options for creating an Agent
+ */
+export interface AgentOptions<TContext = unknown, TData = unknown> {
+  /** Display name of the agent */
+  name: string;
+  /** Detailed description of the agent's purpose and personality */
+  description?: string;
+  /** The agent's primary goal or objective */
+  goal?: string;
+  /** Optional personality/tone prompt used in prompts */
+  personality?: Template<TContext>;
+  /** Optional identity prompt defining the agent's self-concept and role */
+  identity?: Template<TContext>;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Default context data available to the agent */
+  context?: TContext;
+  /** Optional current session for convenience methods */
+  session?: SessionState;
+  /** Optional sessionId to load or create - managed by SessionManager */
+  sessionId?: string;
+  /** Context provider function for always-fresh context (alternative to static context) */
+  contextProvider?: ContextProvider<TContext>;
+  /** Lifecycle hooks for context management */
+  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, TData>[];
+  /** Initial guidelines for agent behavior */
+  guidelines?: Guideline<TContext, TData>[];
+  /** Global tools available to all routes */
+  tools?: Tool<TContext, TData, unknown>[];
+  /** Initial routes (will be instantiated as Route objects) */
+  routes?: RouteOptions<TContext, TData>[];
+  /** Optional persistence configuration for auto-saving sessions and messages */
+  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, TData = unknown> {
+  /** Name of the term */
+  name: Template<TContext, TData>;
+  /** Description/definition of the term */
+  description: Template<TContext, TData>;
+  /** Alternative names or synonyms */
+  synonyms?: Template<TContext, TData>[];
+}
+
+/**
+ * A behavioral guideline for the agent
+ */
+export interface Guideline<TContext = unknown, TData = unknown> {
+  /** Unique identifier */
+  id?: string;
+  /** Condition that triggers this guideline (optional for always-active guidelines) */
+  condition?: ConditionTemplate<TContext, TData>;
+  /** Action the agent should take when the condition is met */
+  action: Template<TContext, TData>;
+  /** Whether this guideline is currently enabled */
+  enabled?: boolean;
+  /** Tags for organizing and filtering guidelines */
+  tags?: string[];
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Guideline match with rationale
+ */
+export interface GuidelineMatch<TContext = unknown, TData = unknown> {
+  /** The matched guideline */
+  guideline: Guideline<TContext, TData>;
+  /** Explanation of why this guideline was matched */
+  rationale?: string;
+}
+
+export interface AgentResponse<TData = Record<string, unknown>> {
+  message: string;
+  session?: SessionState<TData>;
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  isRouteComplete?: boolean;
+}
+
+export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
+  delta: string;
+  accumulated: string;
+  done: boolean;
+  session?: SessionState<TData>;
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  isRouteComplete?: boolean;
+  metadata?: {
+    model?: string;
+    tokensUsed?: number;
+    finishReason?: string;
+    [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

@@ -0,0 +1,158 @@
+/**
+ * AI provider strategy types
+ */
+
+import type { Event } from "./history";
+
+/**
+ * Reasoning/thinking configuration for AI models
+ */
+export interface ReasoningConfig {
+  /**
+   * Effort level for reasoning models (OpenAI: gpt-5, o-series)
+   * - minimal: Fastest, least reasoning
+   * - low: Basic reasoning
+   * - medium: Balanced reasoning
+   * - high: Maximum reasoning effort
+   */
+  effort?: "minimal" | "low" | "medium" | "high";
+  /**
+   * Summary detail level of reasoning process
+   * - auto: Model decides
+   * - concise: Brief summary
+   * - detailed: Full reasoning details
+   */
+  summary?: "auto" | "concise" | "detailed";
+  /**
+   * Whether to include thinking/reasoning in response (Gemini)
+   */
+  includeThoughts?: boolean;
+}
+
+/**
+ * Input for AI message generation
+ */
+export interface GenerateMessageInput<TContext = unknown> {
+  /** The constructed prompt */
+  prompt: string;
+  /** Interaction history */
+  history: Event[];
+  /** Context data */
+  context: TContext;
+  /** Tools available for AI to call during this interaction */
+  tools?: Array<{
+    id: string;
+    name?: string;
+    description?: string;
+    parameters?: unknown;
+  }>;
+  /** Additional generation parameters */
+  parameters?: {
+    /** Maximum output tokens to generate */
+    maxOutputTokens?: number;
+    /** Reasoning/thinking configuration */
+    reasoning?: ReasoningConfig;
+    /**
+     * Required: Structured JSON schema the provider must enforce for output
+     */
+    jsonSchema: { [key: string]: unknown };
+    /** Optional schema name (used by providers that require one) */
+    schemaName?: string;
+  };
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Structured response from AI containing message and metadata
+ */
+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) */
+  route?: string | null;
+  /** Current step within the route (step description or null) */
+  step?: string | null;
+  /** Tool calls the agent wants to execute */
+  toolCalls?: Array<{
+    /** Name of the tool to call */
+    toolName: string;
+    /** Arguments to pass to the tool */
+    arguments: Record<string, unknown>;
+  }>;
+  /** Additional reasoning or internal thoughts (optional) */
+  reasoning?: string;
+}
+
+/**
+ * Output from AI message generation
+ */
+export interface GenerateMessageOutput<TStructured = AgentStructuredResponse> {
+  /** The generated message */
+  message: string;
+  /** Optional metadata about generation */
+  metadata?: {
+    /** Model used */
+    model?: string;
+    /** Tokens consumed */
+    tokensUsed?: number;
+    /** Finish reason */
+    finishReason?: string;
+    /** Additional provider-specific data */
+    [key: string]: unknown;
+  };
+  /** Structured response data (when JSON mode is enabled) */
+  structured?: TStructured;
+}
+
+/**
+ * Stream chunk from AI message generation
+ */
+export interface GenerateMessageStreamChunk<
+  TStructured = AgentStructuredResponse
+> {
+  /** The delta/chunk of the message */
+  delta: string;
+  /** Accumulated message so far */
+  accumulated: string;
+  /** Whether this is the final chunk */
+  done: boolean;
+  /** Optional metadata about generation */
+  metadata?: {
+    /** Model used */
+    model?: string;
+    /** Tokens consumed */
+    tokensUsed?: number;
+    /** Finish reason */
+    finishReason?: string;
+    /** Additional provider-specific data */
+    [key: string]: unknown;
+  };
+  /** Structured response data (only available when done=true and JSON mode is enabled) */
+  structured?: TStructured;
+}
+
+/**
+ * AI provider interface (strategy pattern)
+ */
+export interface AiProvider {
+  /** Provider name/identifier */
+  readonly name: string;
+
+  /**
+   * Generate a message based on prompt and context
+   */
+  generateMessage<TContext = unknown, TStructured = AgentStructuredResponse>(
+    input: GenerateMessageInput<TContext>
+  ): Promise<GenerateMessageOutput<TStructured>>;
+
+  /**
+   * Generate a message as a stream based on prompt and context
+   */
+  generateMessageStream<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
+    input: GenerateMessageInput<TContext>
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>>;
+}

package/src/types/history.ts

@@ -0,0 +1,206 @@
+/**
+ * Event history and interaction types
+ */
+
+/**
+ * Message source enum - defines valid sources for messages and events
+ */
+export enum MessageRole {
+  /** Message/event from user/customer */
+  USER = "user",
+  /** Conversational message from AI assistant */
+  ASSISTANT = "assistant",
+  /** Tool execution/action by AI agent */
+  AGENT = "agent",
+  /** System message/event */
+  SYSTEM = "system",
+}
+
+export type MessageRoleType = MessageRole;
+
+import type { SessionState } from "./session";
+
+/**
+ * Types of events in the interaction history
+ */
+export enum EventKind {
+  /** A text message event */
+  MESSAGE = "message",
+  /** A tool execution event */
+  TOOL = "tool",
+  /** A status update event */
+  STATUS = "status",
+}
+
+export type EventKindType = EventKind;
+
+/**
+ * Participant in a conversation
+ */
+export interface Participant {
+  /** Display name */
+  display_name: string;
+  /** Unique identifier */
+  id?: string;
+}
+
+/**
+ * Role types for simplified history format
+ */
+export type Role = "user" | "assistant" | "tool" | "system";
+
+export type UserHistoryItem = {
+  role: "user";
+  content: string;
+  name?: string;
+};
+
+export type AssistantHistoryItem = {
+  role: "assistant";
+  content: string | null;
+  tool_calls?: Array<{
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  }>;
+};
+export type ToolHistoryItem = {
+  role: "tool";
+  tool_call_id: string;
+  name: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  content: any;
+};
+
+export type SystemHistoryItem = {
+  role: "system";
+  content: string;
+};
+
+/**
+ * Simplified history item for developer-friendly API
+ */
+export type HistoryItem =
+  | UserHistoryItem
+  | AssistantHistoryItem
+  | ToolHistoryItem
+  | SystemHistoryItem;
+
+/**
+ * Simplified history array type
+ */
+export type History = HistoryItem[];
+
+/**
+ * Simple JSON format for history messages (developer-friendly)
+ */
+export interface HistoryMessage<TData = unknown> {
+  /** Role of the message sender */
+  role: MessageRole;
+  /** Message content */
+  content: string;
+  /** Optional participant name */
+  name?: string;
+  /** Optional timestamp (ISO string) */
+  timestamp?: string;
+  /** Optional session state */
+  session?: SessionState<TData>;
+  /** Optional additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Data for a message event
+ */
+export interface MessageEventData {
+  /** The participant who sent the message */
+  participant: Participant;
+  /** The message content */
+  message: string;
+  /** Whether the message was flagged/censored */
+  flagged?: boolean;
+  /** Tags/reasons if flagged */
+  tags?: string[];
+  /** Tool calls made by the assistant */
+  toolCalls?: Array<{
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  }>;
+  /** Session metadata attached to this message */
+  session?: {
+    routeId?: string;
+    routeTitle?: string;
+    stepId?: string;
+    stepDescription?: string;
+    data?: Record<string, unknown>;
+  };
+}
+
+/**
+ * Result of a tool execution
+ */
+export interface ToolResult<TData = unknown> {
+  /** The result data */
+  data: TData;
+  /** Optional metadata */
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * A single tool call within a tool event
+ */
+export interface ToolCall<TArgs = unknown, TResult = unknown> {
+  /** Tool identifier */
+  tool_id: string;
+  /** Arguments passed to the tool */
+  arguments: TArgs;
+  /** Result returned by the tool */
+  result: ToolResult<TResult>;
+}
+
+/**
+ * Data for a tool event
+ */
+export interface ToolEventData {
+  /** Array of tool calls executed */
+  tool_calls: ToolCall[];
+}
+
+/**
+ * Data for a status event
+ */
+export interface StatusEventData {
+  /** Status message */
+  status: string;
+  /** Additional details */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Base event structure
+ */
+export interface Event<
+  TData = MessageEventData | ToolEventData | StatusEventData
+> {
+  /** Type of event */
+  kind: EventKind;
+  /** Source of the event */
+  source: MessageRole;
+  /** Event-specific data */
+  data: TData;
+  /** Timestamp (ISO string) */
+  timestamp?: string;
+  /** Unique event identifier */
+  id?: string;
+}
+
+/**
+ * An emitted event (staged for inclusion)
+ */
+export interface EmittedEvent<
+  TData = MessageEventData | ToolEventData | StatusEventData
+> extends Event<TData> {
+  /** Whether this event has been committed */
+  committed?: boolean;
+}

package/src/types/index.ts

@@ -0,0 +1,119 @@
+/**
+ * Central type definitions export
+ */
+
+// Agent types
+export type {
+  AgentOptions,
+  Term,
+  Guideline,
+  GuidelineMatch,
+  AgentResponseStreamChunk,
+  AgentResponse,
+  ContextLifecycleHooks,
+  ContextProvider,
+  ValidationError,
+  ValidationResult,
+} from "./agent";
+export { CompositionMode } from "./agent";
+
+// History types
+export type {
+  Event,
+  EmittedEvent,
+  MessageEventData,
+  ToolEventData,
+  StatusEventData,
+  Participant,
+  ToolResult as EventToolResult,
+  ToolCall,
+  HistoryMessage,
+  Role,
+  HistoryItem,
+  History,
+  UserHistoryItem,
+  AssistantHistoryItem,
+  SystemHistoryItem,
+  ToolHistoryItem,
+} from "./history";
+export { EventKind, MessageRole } from "./history";
+export * from "./history";
+
+// Route types
+export type {
+  RouteOptions,
+  RouteRef,
+  StepRef,
+  StepOptions,
+  BranchSpec,
+  StepResult,
+  BranchResult,
+  RouteCompletionHandler,
+  RouteTransitionConfig,
+  RouteLifecycleHooks,
+} from "./route";
+export * from "./route";
+
+// Session types
+export type { SessionState, PendingTransition } from "./session";
+
+// Tool types
+export type { 
+  Tool, 
+  ToolContext, 
+  ToolResult, 
+  ToolHandler,
+  ToolExecutionResult,
+  DataEnrichmentConfig,
+  ValidationConfig,
+  ApiCallConfig,
+  ComputationConfig
+} from "./tool";
+export { ToolScope } 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,
+  SessionRepository,
+  MessageRepository,
+  PersistenceAdapter,
+  PersistenceConfig,
+  CreateSessionOptions,
+  CreateSessionData,
+  SaveMessageOptions,
+  CollectedStateData,
+} from "./persistence";
+export * from "./persistence";
+
+// Template types
+export type { 
+  Template, 
+  TemplateContext, 
+  ConditionTemplate, 
+  ConditionEvaluationResult 
+} from "./template";
+export { 
+  ConditionEvaluator, 
+  createConditionEvaluator, 
+  extractAIContextStrings, 
+  hasProgrammaticConditions 
+} from "../utils/condition";