@falai/agent 0.3.10 → 0.3.12

package/src/providers/OpenAIProvider.ts

@@ -9,6 +9,7 @@ import type {
   AiProvider,
   GenerateMessageInput,
   GenerateMessageOutput,
+  GenerateMessageStreamChunk,
   AgentStructuredResponse,
 } from "../types/ai";
 import { withTimeoutAndRetry } from "../utils/retry";
@@ -164,6 +165,12 @@ export class OpenAIProvider implements AiProvider {
     return this.generateWithBackup(input);
   }
 
+  async *generateMessageStream<TContext = unknown>(
+    input: GenerateMessageInput<TContext>
+  ): AsyncGenerator<GenerateMessageStreamChunk> {
+    yield* this.generateStreamWithBackup(input);
+  }
+
   private async generateWithBackup<TContext = unknown>(
     input: GenerateMessageInput<TContext>
   ): Promise<GenerateMessageOutput> {
@@ -353,4 +360,154 @@ export class OpenAIProvider implements AiProvider {
       `OpenAI ${model}`
     );
   }
+
+  private async *generateStreamWithBackup<TContext = unknown>(
+    input: GenerateMessageInput<TContext>
+  ): AsyncGenerator<GenerateMessageStreamChunk> {
+    // Try primary model first
+    try {
+      yield* this.generateStreamWithModel(this.primaryModel, input);
+    } catch (primaryError: unknown) {
+      const primaryErrMsg = getErrorMessage(primaryError);
+      console.warn(
+        `[OPENAI] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
+      );
+
+      if (!shouldUseBackupModel(primaryError)) {
+        throw primaryError;
+      }
+
+      console.log(`[OPENAI] Trying backup models for streaming`);
+
+      let lastBackupError: unknown = primaryError;
+
+      for (let i = 0; i < this.backupModels.length; i++) {
+        const backupModel = this.backupModels[i];
+        console.log(
+          `[OPENAI] Trying backup model ${i + 1}/${
+            this.backupModels.length
+          }: ${backupModel}`
+        );
+
+        try {
+          yield* this.generateStreamWithModel(backupModel, input);
+          console.log(`[OPENAI] Backup model ${backupModel} succeeded`);
+          return;
+        } catch (backupError: unknown) {
+          const backupErrMsg = getErrorMessage(backupError);
+          console.warn(
+            `[OPENAI] Backup model ${backupModel} failed: ${backupErrMsg}`
+          );
+          lastBackupError = backupError;
+
+          if (
+            !shouldUseBackupModel(backupError) &&
+            i < this.backupModels.length - 1
+          ) {
+            console.log(
+              `[OPENAI] Backup model error doesn't qualify for further attempts`
+            );
+            break;
+          }
+        }
+      }
+
+      const lastBackupErrMsg = getErrorMessage(lastBackupError);
+      console.error(
+        `[OPENAI] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
+      );
+      throw lastBackupError;
+    }
+  }
+
+  private async *generateStreamWithModel<TContext = unknown>(
+    model: string,
+    input: GenerateMessageInput<TContext>
+  ): AsyncGenerator<GenerateMessageStreamChunk> {
+    const params = {
+      ...this.config,
+      model,
+      messages: [
+        {
+          role: "user" as const,
+          content: input.prompt,
+        },
+      ],
+      stream: true as const,
+    };
+
+    // Override with input parameters if provided
+    if (input.parameters?.maxOutputTokens !== undefined) {
+      params.max_tokens = input.parameters.maxOutputTokens;
+    }
+
+    // Use JSON mode if requested
+    // Note: OpenAI streaming doesn't support the responses.parse API,
+    // so we use response_format with JSON mode instead
+    if (input.parameters?.jsonMode) {
+      params.response_format = { type: "json_object" };
+    }
+
+    const stream = await this.client.chat.completions.create(params);
+
+    let accumulated = "";
+    let currentModel = model;
+    let finishReason: string | undefined;
+    let promptTokens: number | undefined;
+    let completionTokens: number | undefined;
+    let totalTokens: number | undefined;
+
+    for await (const chunk of stream) {
+      currentModel = chunk.model;
+      const delta = chunk.choices[0]?.delta?.content || "";
+
+      if (delta) {
+        accumulated += delta;
+        yield {
+          delta,
+          accumulated,
+          done: false,
+        };
+      }
+
+      if (chunk.choices[0]?.finish_reason) {
+        finishReason = chunk.choices[0].finish_reason;
+      }
+
+      // OpenAI includes usage in the final chunk for some models
+      if (chunk.usage) {
+        promptTokens = chunk.usage.prompt_tokens;
+        completionTokens = chunk.usage.completion_tokens;
+        totalTokens = chunk.usage.total_tokens;
+      }
+    }
+
+    // Parse JSON response if JSON mode was enabled
+    let structured: AgentStructuredResponse | undefined;
+    if (input.parameters?.jsonMode && accumulated) {
+      try {
+        structured = JSON.parse(accumulated) as AgentStructuredResponse;
+      } catch (error) {
+        console.warn(
+          "[OPENAI] Failed to parse JSON response in stream:",
+          error
+        );
+      }
+    }
+
+    // Yield final chunk
+    yield {
+      delta: "",
+      accumulated,
+      done: true,
+      metadata: {
+        model: currentModel,
+        finishReason,
+        tokensUsed: totalTokens,
+        promptTokens,
+        completionTokens,
+      },
+      structured,
+    };
+  }
 }

package/src/providers/OpenRouterProvider.ts

@@ -11,6 +11,7 @@ import type {
   AgentStructuredResponse,
   GenerateMessageInput,
   GenerateMessageOutput,
+  GenerateMessageStreamChunk,
 } from "../types/ai";
 import { withTimeoutAndRetry } from "../utils/retry";
 
@@ -174,6 +175,12 @@ export class OpenRouterProvider implements AiProvider {
     return this.generateWithBackup(input);
   }
 
+  async *generateMessageStream<TContext = unknown>(
+    input: GenerateMessageInput<TContext>
+  ): AsyncGenerator<GenerateMessageStreamChunk> {
+    yield* this.generateStreamWithBackup(input);
+  }
+
   private async generateWithBackup<TContext = unknown>(
     input: GenerateMessageInput<TContext>
   ): Promise<GenerateMessageOutput> {
@@ -363,4 +370,154 @@ export class OpenRouterProvider implements AiProvider {
       `OpenRouter ${model}`
     );
   }
+
+  private async *generateStreamWithBackup<TContext = unknown>(
+    input: GenerateMessageInput<TContext>
+  ): AsyncGenerator<GenerateMessageStreamChunk> {
+    // Try primary model first
+    try {
+      yield* this.generateStreamWithModel(this.primaryModel, input);
+    } catch (primaryError: unknown) {
+      const primaryErrMsg = getErrorMessage(primaryError);
+      console.warn(
+        `[OPENROUTER] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
+      );
+
+      if (!shouldUseBackupModel(primaryError)) {
+        throw primaryError;
+      }
+
+      console.log(`[OPENROUTER] Trying backup models for streaming`);
+
+      let lastBackupError: unknown = primaryError;
+
+      for (let i = 0; i < this.backupModels.length; i++) {
+        const backupModel = this.backupModels[i];
+        console.log(
+          `[OPENROUTER] Trying backup model ${i + 1}/${
+            this.backupModels.length
+          }: ${backupModel}`
+        );
+
+        try {
+          yield* this.generateStreamWithModel(backupModel, input);
+          console.log(`[OPENROUTER] Backup model ${backupModel} succeeded`);
+          return;
+        } catch (backupError: unknown) {
+          const backupErrMsg = getErrorMessage(backupError);
+          console.warn(
+            `[OPENROUTER] Backup model ${backupModel} failed: ${backupErrMsg}`
+          );
+          lastBackupError = backupError;
+
+          if (
+            !shouldUseBackupModel(backupError) &&
+            i < this.backupModels.length - 1
+          ) {
+            console.log(
+              `[OPENROUTER] Backup model error doesn't qualify for further attempts`
+            );
+            break;
+          }
+        }
+      }
+
+      const lastBackupErrMsg = getErrorMessage(lastBackupError);
+      console.error(
+        `[OPENROUTER] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
+      );
+      throw lastBackupError;
+    }
+  }
+
+  private async *generateStreamWithModel<TContext = unknown>(
+    model: string,
+    input: GenerateMessageInput<TContext>
+  ): AsyncGenerator<GenerateMessageStreamChunk> {
+    const params = {
+      ...this.config,
+      model,
+      messages: [
+        {
+          role: "user" as const,
+          content: input.prompt,
+        },
+      ],
+      stream: true as const,
+    };
+
+    // Override with input parameters if provided
+    if (input.parameters?.maxOutputTokens !== undefined) {
+      params.max_tokens = input.parameters.maxOutputTokens;
+    }
+
+    // Use JSON mode if requested
+    // Note: OpenRouter streaming doesn't support the responses.parse API,
+    // so we use response_format with JSON mode instead
+    if (input.parameters?.jsonMode) {
+      params.response_format = { type: "json_object" };
+    }
+
+    const stream = await this.client.chat.completions.create(params);
+
+    let accumulated = "";
+    let currentModel = model;
+    let finishReason: string | undefined;
+    let promptTokens: number | undefined;
+    let completionTokens: number | undefined;
+    let totalTokens: number | undefined;
+
+    for await (const chunk of stream) {
+      currentModel = chunk.model;
+      const delta = chunk.choices[0]?.delta?.content || "";
+
+      if (delta) {
+        accumulated += delta;
+        yield {
+          delta,
+          accumulated,
+          done: false,
+        };
+      }
+
+      if (chunk.choices[0]?.finish_reason) {
+        finishReason = chunk.choices[0].finish_reason;
+      }
+
+      // OpenRouter may include usage in the final chunk
+      if (chunk.usage) {
+        promptTokens = chunk.usage.prompt_tokens;
+        completionTokens = chunk.usage.completion_tokens;
+        totalTokens = chunk.usage.total_tokens;
+      }
+    }
+
+    // Parse JSON response if JSON mode was enabled
+    let structured: AgentStructuredResponse | undefined;
+    if (input.parameters?.jsonMode && accumulated) {
+      try {
+        structured = JSON.parse(accumulated) as AgentStructuredResponse;
+      } catch (error) {
+        console.warn(
+          "[OPENROUTER] Failed to parse JSON response in stream:",
+          error
+        );
+      }
+    }
+
+    // Yield final chunk
+    yield {
+      delta: "",
+      accumulated,
+      done: true,
+      metadata: {
+        model: currentModel,
+        finishReason,
+        tokensUsed: totalTokens,
+        promptTokens,
+        completionTokens,
+      },
+      structured,
+    };
+  }
 }

package/src/providers/index.ts

@@ -0,0 +1,16 @@
+/**
+ * AI Provider exports
+ * Centralized export point for all AI provider implementations
+ */
+
+export { AnthropicProvider } from "./AnthropicProvider";
+export type { AnthropicProviderOptions } from "./AnthropicProvider";
+
+export { GeminiProvider } from "./GeminiProvider";
+export type { GeminiProviderOptions } from "./GeminiProvider";
+
+export { OpenAIProvider } from "./OpenAIProvider";
+export type { OpenAIProviderOptions } from "./OpenAIProvider";
+
+export { OpenRouterProvider } from "./OpenRouterProvider";
+export type { OpenRouterProviderOptions } from "./OpenRouterProvider";

package/src/types/agent.ts

@@ -5,6 +5,7 @@
 import type { AiProvider } from "./ai";
 import type { ToolRef } from "./tool";
 import type { RouteOptions } from "./route";
+import type { PersistenceConfig } from "./persistence";
 
 /**
  * Composition mode determines how the agent processes and structures responses
@@ -85,6 +86,8 @@ export interface AgentOptions<TContext = unknown> {
   routes?: RouteOptions[];
   /** Initial observations for disambiguation */
   observations?: ObservationOptions[];
+  /** Optional persistence configuration for auto-saving sessions and messages */
+  persistence?: PersistenceConfig;
 }
 
 /**

package/src/types/ai.ts

@@ -94,6 +94,31 @@ export interface GenerateMessageOutput {
   structured?: AgentStructuredResponse;
 }
 
+/**
+ * Stream chunk from AI message generation
+ */
+export interface GenerateMessageStreamChunk {
+  /** 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?: AgentStructuredResponse;
+}
+
 /**
  * AI provider interface (strategy pattern)
  */
@@ -107,4 +132,11 @@ export interface AiProvider {
   generateMessage<TContext = unknown>(
     input: GenerateMessageInput<TContext>
   ): Promise<GenerateMessageOutput>;
+
+  /**
+   * Generate a message as a stream based on prompt and context
+   */
+  generateMessageStream<TContext = unknown>(
+    input: GenerateMessageInput<TContext>
+  ): AsyncGenerator<GenerateMessageStreamChunk>;
 }

package/src/types/index.ts

@@ -54,3 +54,17 @@ export { SectionStatus } from "./prompt";
 
 // Observation types
 export type { Observation, ObservationOptions } from "./observation";
+
+// Persistence types
+export type {
+  SessionData,
+  MessageData,
+  SessionStatus,
+  MessageRole,
+  SessionRepository,
+  MessageRepository,
+  PersistenceAdapter,
+  PersistenceConfig,
+  CreateSessionOptions,
+  SaveMessageOptions,
+} from "./persistence";

package/src/types/persistence.ts

@@ -0,0 +1,234 @@
+/**
+ * Persistence-related type definitions
+ * Support for optional database persistence (Prisma, etc.)
+ */
+
+import type { Event } from "./history";
+
+/**
+ * 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 {
+  id: string;
+  userId?: string;
+  agentName?: string;
+  status: SessionStatus;
+  currentRoute?: string;
+  currentState?: string;
+  collectedData?: Record<string, unknown>;
+  messageCount?: number;
+  lastMessageAt?: Date;
+  completedAt?: Date;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Base message data structure
+ */
+export interface MessageData {
+  id: string;
+  sessionId: string;
+  userId?: string;
+  role: MessageRole;
+  content: string;
+  route?: string;
+  state?: 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 {
+  /**
+   * Create a new session
+   */
+  create(
+    data: Omit<SessionData, "id" | "createdAt" | "updatedAt">
+  ): Promise<SessionData>;
+
+  /**
+   * Find session by ID
+   */
+  findById(id: string): Promise<SessionData | null>;
+
+  /**
+   * Find active session by user ID
+   */
+  findActiveByUserId(userId: string): Promise<SessionData | null>;
+
+  /**
+   * Find all sessions for a user
+   */
+  findByUserId(userId: string, limit?: number): Promise<SessionData[]>;
+
+  /**
+   * Update session
+   */
+  update(
+    id: string,
+    data: Partial<Omit<SessionData, "id" | "createdAt">>
+  ): Promise<SessionData | null>;
+
+  /**
+   * Update session status
+   */
+  updateStatus(
+    id: string,
+    status: SessionStatus,
+    completedAt?: Date
+  ): Promise<SessionData | null>;
+
+  /**
+   * Update collected data
+   */
+  updateCollectedData(
+    id: string,
+    collectedData: Record<string, unknown>
+  ): Promise<SessionData | null>;
+
+  /**
+   * Update current route and state
+   */
+  updateRouteState(
+    id: string,
+    route?: string,
+    state?: string
+  ): Promise<SessionData | null>;
+
+  /**
+   * Increment message count
+   */
+  incrementMessageCount(id: string): Promise<SessionData | 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 {
+  /**
+   * Session repository
+   */
+  readonly sessionRepository: SessionRepository;
+
+  /**
+   * 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 {
+  /**
+   * Persistence adapter instance (e.g., PrismaAdapter)
+   */
+  adapter: PersistenceAdapter;
+
+  /**
+   * 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 {
+  userId?: string;
+  agentName?: string;
+  initialData?: Record<string, unknown>;
+}
+
+/**
+ * Options for saving a message
+ */
+export interface SaveMessageOptions {
+  sessionId: string;
+  userId?: string;
+  role: MessageRole;
+  content: string;
+  route?: string;
+  state?: string;
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  event?: Event;
+}