@falai/agent 0.1.0

package/src/types/ai.ts

@@ -0,0 +1,85 @@
+/**
+ * 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;
+  /** Additional generation parameters */
+  parameters?: {
+    /** Maximum output tokens to generate */
+    maxOutputTokens?: number;
+    /** Reasoning/thinking configuration */
+    reasoning?: ReasoningConfig;
+  };
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+}
+
+/**
+ * Output from AI message generation
+ */
+export interface GenerateMessageOutput {
+  /** 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;
+  };
+}
+
+/**
+ * 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>(
+    input: GenerateMessageInput<TContext>
+  ): Promise<GenerateMessageOutput>;
+}

package/src/types/history.ts

@@ -0,0 +1,125 @@
+/**
+ * Event history and interaction types
+ */
+
+/**
+ * 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",
+}
+
+/**
+ * Source of an event
+ */
+export enum EventSource {
+  /** Event originated from the customer/user */
+  CUSTOMER = "customer",
+  /** Event from customer UI application */
+  CUSTOMER_UI = "customer_ui",
+  /** Event from human service agent */
+  HUMAN_AGENT = "human_agent",
+  /** Human agent acting on behalf of AI agent */
+  HUMAN_AGENT_ON_BEHALF_OF_AI_AGENT = "human_agent_on_behalf_of_ai_agent",
+  /** Event generated by AI agent */
+  AI_AGENT = "ai_agent",
+  /** System-generated event */
+  SYSTEM = "system",
+}
+
+/**
+ * Participant in a conversation
+ */
+export interface Participant {
+  /** Display name */
+  display_name: string;
+  /** Unique identifier */
+  id?: string;
+}
+
+/**
+ * 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[];
+}
+
+/**
+ * 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: EventSource;
+  /** 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,56 @@
+/**
+ * Central type definitions export
+ */
+
+// Agent types
+export type {
+  AgentOptions,
+  Term,
+  Guideline,
+  Capability,
+  GuidelineMatch,
+} from "./agent";
+export { CompositionMode } from "./agent";
+
+// History types
+export type {
+  Event,
+  EmittedEvent,
+  MessageEventData,
+  ToolEventData,
+  StatusEventData,
+  Participant,
+  ToolResult as EventToolResult,
+  ToolCall,
+} from "./history";
+export { EventKind, EventSource } from "./history";
+
+// Route types
+export type {
+  RouteRef,
+  StateRef,
+  RouteOptions,
+  TransitionSpec,
+  TransitionResult,
+} from "./route";
+
+// Tool types
+export type { ToolContext, ToolResult, ToolHandler, ToolRef } from "./tool";
+
+// AI provider types
+export type {
+  AiProvider,
+  GenerateMessageInput,
+  GenerateMessageOutput,
+} from "./ai";
+
+// Prompt types
+export type {
+  PromptSection,
+  ContextVariable,
+  ContextVariableValue,
+} from "./prompt";
+export { SectionStatus } from "./prompt";
+
+// Observation types
+export type { Observation, ObservationOptions } from "./observation";

package/src/types/observation.ts

@@ -0,0 +1,27 @@
+/**
+ * Observation types for disambiguation
+ */
+
+import type { RouteRef } from "./route";
+
+/**
+ * An observation that can disambiguate between multiple routes
+ */
+export interface Observation {
+  /** Unique identifier */
+  id: string;
+  /** The observation description */
+  description: string;
+  /** Routes this observation can disambiguate between */
+  routes?: RouteRef[];
+}
+
+/**
+ * Options for creating an observation
+ */
+export interface ObservationOptions {
+  /** The observation description */
+  description: string;
+  /** Route IDs or titles to disambiguate between (can be set later with disambiguate()) */
+  routeRefs?: string[];
+}

package/src/types/prompt.ts

@@ -0,0 +1,49 @@
+/**
+ * Prompt building types
+ */
+
+/**
+ * Status of a prompt section
+ */
+export enum SectionStatus {
+  /** Section has active information */
+  ACTIVE = "active",
+  /** Section is inactive but may have empty-state text */
+  PASSIVE = "passive",
+  /** Section is not included */
+  NONE = "none",
+}
+
+/**
+ * A section within a prompt
+ */
+export interface PromptSection {
+  /** Template string (may contain placeholders) */
+  template: string;
+  /** Properties to fill template placeholders */
+  props: Record<string, unknown>;
+  /** Status of this section */
+  status?: SectionStatus;
+}
+
+/**
+ * Context variable with value
+ */
+export interface ContextVariable {
+  /** Variable name */
+  name: string;
+  /** Variable description */
+  description?: string;
+  /** Variable type */
+  type?: string;
+}
+
+/**
+ * Value for a context variable
+ */
+export interface ContextVariableValue {
+  /** The variable definition */
+  variable: ContextVariable;
+  /** The current value */
+  value: unknown;
+}

package/src/types/route.ts

@@ -0,0 +1,68 @@
+/**
+ * Route/Journey DSL type definitions
+ */
+
+import type { ToolRef } from "./tool";
+
+/**
+ * Reference to a route
+ */
+export interface RouteRef {
+  /** Route identifier */
+  id: string;
+}
+
+/**
+ * Reference to a state within a route
+ */
+export interface StateRef {
+  /** State identifier */
+  id: string;
+  /** Route this state belongs to */
+  routeId: string;
+}
+
+/**
+ * Forward declare Guideline for circular dependency
+ */
+import type { Guideline } from "./agent";
+
+/**
+ * Options for creating a route
+ */
+export interface RouteOptions {
+  /** Title of the route */
+  title: string;
+  /** Description of what this route accomplishes */
+  description?: string;
+  /** Conditions that activate this route */
+  conditions?: string[];
+  /** Initial guidelines for this route */
+  guidelines?: Guideline[];
+}
+
+/**
+ * Specification for a state transition
+ */
+export interface TransitionSpec {
+  /** Transition to a chat state with this description */
+  chatState?: string;
+  /** Transition to execute a tool */
+  toolState?: ToolRef<unknown, unknown[], unknown>;
+  /** Transition to a specific state or end marker */
+  state?: StateRef | symbol;
+}
+
+/**
+ * Result of a transition operation
+ */
+export interface TransitionResult {
+  /** The target state after transition */
+  target: StateRef & {
+    /** Allow chaining transitions */
+    transitionTo: (
+      spec: TransitionSpec,
+      condition?: string
+    ) => TransitionResult;
+  };
+}

package/src/types/tool.ts

@@ -0,0 +1,53 @@
+/**
+ * Tool system type definitions
+ */
+
+import type { Event, StateRef } from "./index";
+
+/**
+ * Context provided to tool handlers
+ */
+export interface ToolContext<TContext = unknown> {
+  /** The agent's context data */
+  context: TContext;
+  /** Current state reference (if in a route) */
+  state?: StateRef;
+  /** Interaction history */
+  history: Event[];
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result returned by a tool
+ */
+export interface ToolResult<TData = unknown> {
+  /** The result data */
+  data: TData;
+  /** Optional metadata about the execution */
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Handler function for a tool
+ */
+export type ToolHandler<TContext, TArgs extends unknown[], TResult> = (
+  context: ToolContext<TContext>,
+  ...args: TArgs
+) => Promise<ToolResult<TResult>> | ToolResult<TResult>;
+
+/**
+ * Reference to a defined tool
+ */
+export interface ToolRef<TContext, TArgs extends unknown[], TResult> {
+  /** Tool identifier */
+  id: string;
+  /** Tool name */
+  name: string;
+  /** Tool handler function */
+  handler: ToolHandler<TContext, TArgs, TResult>;
+  /** Description of what the tool does */
+  description?: string;
+  /** Parameter schema or description */
+  parameters?: unknown;
+}

package/src/utils/retry.ts

@@ -0,0 +1,96 @@
+/**
+ * Retry utility with exponential backoff
+ */
+
+export interface RetryOptions<T> {
+  operation: () => Promise<T>;
+  maxRetries: number;
+  delay: (attempt: number) => number;
+  onRetry?: (attempt: number, error: unknown) => void;
+  onFailure?: (error: unknown) => boolean;
+}
+
+export async function retry<T>(options: RetryOptions<T>): Promise<T> {
+  const { operation, maxRetries, delay, onRetry, onFailure } = options;
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error: unknown) {
+      lastError = error;
+
+      if (attempt === maxRetries) {
+        const shouldRethrow = onFailure ? onFailure(lastError) : true;
+        if (shouldRethrow) {
+          throw lastError;
+        }
+        break;
+      }
+
+      if (onRetry) {
+        onRetry(attempt, lastError);
+      }
+
+      const delayMs = delay(attempt);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/only-throw-error
+  throw lastError ?? new Error("Operation failed");
+}
+
+export const withTimeoutAndRetry = async <T>(
+  operation: () => Promise<T>,
+  timeoutMs: number = 60000,
+  maxRetries: number = 3,
+  operationName: string = "AI operation"
+): Promise<T> => {
+  const createTimeoutOperation = () => async (): Promise<T> => {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort();
+    }, timeoutMs);
+
+    try {
+      const result = await Promise.race([
+        operation(),
+        new Promise<never>((_, reject) => {
+          controller.signal.addEventListener("abort", () => {
+            reject(new Error(`Operation timed out after ${timeoutMs}ms`));
+          });
+        }),
+      ]);
+
+      clearTimeout(timeoutId);
+      return result;
+    } catch (error: unknown) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  };
+
+  return retry<T>({
+    operation: createTimeoutOperation(),
+    maxRetries,
+    delay: (attempt: number) => Math.min(1000 * Math.pow(2, attempt), 5000),
+    onRetry: (attempt: number, error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(
+        `[${operationName}] Failed attempt ${attempt + 1}:`,
+        message
+      );
+      const delay = Math.min(1000 * Math.pow(2, attempt), 5000);
+      console.log(`[${operationName}] Retrying in ${delay}ms...`);
+      console.log(
+        `[${operationName}] Attempt ${attempt + 2}/${maxRetries + 1}`
+      );
+    },
+    onFailure: (_error: unknown) => {
+      console.error(`[${operationName}] All ${maxRetries + 1} attempts failed`);
+      return true;
+    },
+  });
+};