@falai/agent 0.3.10 → 0.3.12

package/src/core/Agent.ts

@@ -16,6 +16,7 @@ import { Route } from "./Route";
 import { DomainRegistry } from "./DomainRegistry";
 import { PromptBuilder } from "./PromptBuilder";
 import { Observation } from "./Observation";
+import { PersistenceManager } from "./PersistenceManager";
 
 /**
  * Main Agent class with generic context support
@@ -28,6 +29,7 @@ export class Agent<TContext = unknown> {
   private observations: Observation[] = [];
   private domainRegistry = new DomainRegistry();
   private context: TContext | undefined;
+  private persistenceManager: PersistenceManager | undefined;
 
   /**
    * Dynamic domain property - populated via addDomain
@@ -50,6 +52,21 @@ export class Agent<TContext = unknown> {
     // Initialize context if provided
     this.context = options.context;
 
+    // Initialize persistence if configured
+    if (options.persistence) {
+      this.persistenceManager = new PersistenceManager(options.persistence);
+
+      // Initialize the adapter if it has an initialize method
+      if (options.persistence.adapter.initialize) {
+        options.persistence.adapter.initialize().catch((error) => {
+          console.error(
+            "[Agent] Persistence adapter initialization failed:",
+            error
+          );
+        });
+      }
+    }
+
     // Initialize from options
     if (options.terms) {
       this.terms = [...options.terms];
@@ -211,6 +228,180 @@ export class Agent<TContext = unknown> {
     return this.context;
   }
 
+  /**
+   * Generate a response based on history and context as a stream
+   */
+  async *respondStream(params: {
+    history: Event[];
+    state?: StateRef;
+    contextOverride?: Partial<TContext>;
+    signal?: AbortSignal;
+  }): AsyncGenerator<{
+    delta: string;
+    accumulated: string;
+    done: boolean;
+    route?: { id: string; title: string } | null;
+    state?: { id: string; description?: string } | null;
+    toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  }> {
+    const { history, contextOverride, signal } = params;
+
+    // Get current context (may fetch from provider)
+    let currentContext = await this.getContext();
+
+    // Call beforeRespond hook if configured
+    if (this.options.hooks?.beforeRespond && currentContext !== undefined) {
+      currentContext = await this.options.hooks.beforeRespond(currentContext);
+      // Update stored context with the result from beforeRespond
+      this.context = currentContext;
+    }
+
+    // Merge context with override
+    const effectiveContext = {
+      ...(currentContext as Record<string, unknown>),
+      ...(contextOverride as Record<string, unknown>),
+    } as TContext;
+
+    // Build prompt (same as respond method)
+    const promptBuilder = new PromptBuilder();
+
+    // Add agent identity
+    if (this.options.description) {
+      promptBuilder.addAgentIdentity({
+        name: this.options.name,
+        description: this.options.description,
+      });
+    }
+
+    // Add interaction history
+    promptBuilder.addInteractionHistoryForMessageGeneration(history);
+
+    // Add glossary
+    if (this.terms.length > 0) {
+      promptBuilder.addGlossary(this.terms);
+    }
+
+    // Add guidelines (convert to GuidelineMatch format, filter enabled only)
+    const enabledGuidelines = this.guidelines.filter(
+      (g) => g.enabled !== false
+    );
+    if (enabledGuidelines.length > 0) {
+      const guidelineMatches: GuidelineMatch[] = enabledGuidelines.map((g) => ({
+        guideline: g,
+      }));
+      promptBuilder.addGuidelinesForMessageGeneration(guidelineMatches);
+    }
+
+    // Add capabilities
+    if (this.capabilities.length > 0) {
+      promptBuilder.addCapabilitiesForMessageGeneration(this.capabilities);
+    }
+
+    // Add observations
+    if (this.observations.length > 0) {
+      const observationsWithRoutes = this.observations
+        .map((obs) => ({
+          description: obs.description,
+          routes: obs.getRoutes().map((routeRef) => {
+            const route = this.routes.find((r) => r.id === routeRef.id);
+            return { title: route?.title || routeRef.id };
+          }),
+        }))
+        .filter((obs) => obs.routes.length > 0);
+
+      if (observationsWithRoutes.length > 0) {
+        promptBuilder.addObservations(observationsWithRoutes);
+      }
+    }
+
+    // Add active routes with their rules and prohibitions
+    if (this.routes.length > 0) {
+      promptBuilder.addActiveRoutes(
+        this.routes.map((r) => ({
+          title: r.title,
+          description: r.description,
+          conditions: r.conditions,
+          domains: r.getDomains(),
+          rules: r.getRules(),
+          prohibitions: r.getProhibitions(),
+        }))
+      );
+    }
+
+    // Add domains (tools) information if any domains are registered
+    const allDomains = this.domainRegistry.all();
+    if (Object.keys(allDomains).length > 0) {
+      promptBuilder.addDomains(allDomains);
+    }
+
+    // Add JSON response schema instructions
+    promptBuilder.addJsonResponseSchema();
+
+    // Build final prompt
+    const prompt = promptBuilder.build();
+
+    // Generate message stream using AI provider with JSON mode enabled
+    const stream = this.options.ai.generateMessageStream({
+      prompt,
+      history,
+      context: effectiveContext,
+      signal,
+      parameters: {
+        jsonMode: true,
+      },
+    });
+
+    // Stream chunks to caller
+    for await (const chunk of stream) {
+      // Extract route and state from structured response on final chunk
+      let route: { id: string; title: string } | null = null;
+      let state: { id: string; description?: string } | null = null;
+      let toolCalls:
+        | Array<{ toolName: string; arguments: Record<string, unknown> }>
+        | undefined;
+
+      if (chunk.done && chunk.structured) {
+        // Find route by title
+        if (chunk.structured.route) {
+          const foundRoute = this.routes.find(
+            (r) => r.title === chunk.structured?.route
+          );
+          if (foundRoute) {
+            route = {
+              id: foundRoute.id,
+              title: foundRoute.title,
+            };
+          }
+        }
+
+        // Create state reference if provided
+        if (chunk.structured.state) {
+          state = {
+            id: "dynamic_state",
+            description: chunk.structured.state,
+          };
+        }
+
+        // Extract tool calls
+        if (
+          chunk.structured.toolCalls &&
+          chunk.structured.toolCalls.length > 0
+        ) {
+          toolCalls = chunk.structured.toolCalls;
+        }
+      }
+
+      yield {
+        delta: chunk.delta,
+        accumulated: chunk.accumulated,
+        done: chunk.done,
+        route: route || undefined,
+        state: state || undefined,
+        toolCalls,
+      };
+    }
+  }
+
   /**
    * Generate a response based on history and context
    */
@@ -424,6 +615,20 @@ export class Agent<TContext = unknown> {
     return this.domainRegistry;
   }
 
+  /**
+   * Get the persistence manager (if configured)
+   */
+  getPersistenceManager(): PersistenceManager | undefined {
+    return this.persistenceManager;
+  }
+
+  /**
+   * Check if persistence is enabled
+   */
+  hasPersistence(): boolean {
+    return this.persistenceManager !== undefined;
+  }
+
   /**
    * Get allowed domains for a specific route
    * @param routeId - Route ID to check

package/src/core/PersistenceManager.ts

@@ -0,0 +1,222 @@
+/**
+ * Persistence Manager
+ * Handles optional persistence of sessions and messages
+ */
+
+import type {
+  PersistenceConfig,
+  SessionData,
+  MessageData,
+  CreateSessionOptions,
+  SaveMessageOptions,
+  SessionStatus,
+  SessionRepository,
+  MessageRepository,
+} from "../types/persistence";
+import type { Event } from "../types/history";
+
+/**
+ * Manager for handling persistence operations
+ * Provides a clean interface for optional database persistence
+ */
+export class PersistenceManager {
+  private config: PersistenceConfig;
+  private sessionRepository: SessionRepository;
+  private messageRepository: MessageRepository;
+
+  constructor(config: PersistenceConfig) {
+    this.config = {
+      autoSave: true,
+      ...config,
+    };
+    this.sessionRepository = config.adapter.sessionRepository;
+    this.messageRepository = config.adapter.messageRepository;
+  }
+
+  /**
+   * Create a new session
+   */
+  async createSession(options: CreateSessionOptions): Promise<SessionData> {
+    const userId = options.userId || this.config.userId;
+
+    return await this.sessionRepository.create({
+      userId,
+      agentName: options.agentName,
+      status: "active",
+      collectedData: options.initialData || {},
+      messageCount: 0,
+    });
+  }
+
+  /**
+   * Get session by ID
+   */
+  async getSession(sessionId: string): Promise<SessionData | null> {
+    return await this.sessionRepository.findById(sessionId);
+  }
+
+  /**
+   * Find active session for a user
+   */
+  async findActiveSession(userId?: string): Promise<SessionData | null> {
+    const effectiveUserId = userId || this.config.userId;
+    if (!effectiveUserId) {
+      throw new Error(
+        "userId must be provided or configured in PersistenceConfig"
+      );
+    }
+    return await this.sessionRepository.findActiveByUserId(effectiveUserId);
+  }
+
+  /**
+   * Get all sessions for a user
+   */
+  async getUserSessions(
+    userId?: string,
+    limit?: number
+  ): Promise<SessionData[]> {
+    const effectiveUserId = userId || this.config.userId;
+    if (!effectiveUserId) {
+      throw new Error(
+        "userId must be provided or configured in PersistenceConfig"
+      );
+    }
+    return await this.sessionRepository.findByUserId(effectiveUserId, limit);
+  }
+
+  /**
+   * Update session status
+   */
+  async updateSessionStatus(
+    sessionId: string,
+    status: SessionStatus,
+    completedAt?: Date
+  ): Promise<SessionData | null> {
+    return await this.sessionRepository.updateStatus(
+      sessionId,
+      status,
+      completedAt
+    );
+  }
+
+  /**
+   * Update collected data in session
+   */
+  async updateCollectedData(
+    sessionId: string,
+    collectedData: Record<string, unknown>
+  ): Promise<SessionData | null> {
+    return await this.sessionRepository.updateCollectedData(
+      sessionId,
+      collectedData
+    );
+  }
+
+  /**
+   * Update current route and state
+   */
+  async updateRouteState(
+    sessionId: string,
+    route?: string,
+    state?: string
+  ): Promise<SessionData | null> {
+    return await this.sessionRepository.updateRouteState(
+      sessionId,
+      route,
+      state
+    );
+  }
+
+  /**
+   * Save a message
+   */
+  async saveMessage(options: SaveMessageOptions): Promise<MessageData> {
+    const userId = options.userId || this.config.userId;
+
+    const message = await this.messageRepository.create({
+      sessionId: options.sessionId,
+      userId,
+      role: options.role,
+      content: options.content,
+      route: options.route,
+      state: options.state,
+      toolCalls: options.toolCalls,
+      event: options.event,
+    });
+
+    // Increment message count in session if autoSave is enabled
+    if (this.config.autoSave) {
+      await this.sessionRepository.incrementMessageCount(options.sessionId);
+    }
+
+    return message;
+  }
+
+  /**
+   * Get all messages for a session
+   */
+  async getSessionMessages(
+    sessionId: string,
+    limit?: number
+  ): Promise<MessageData[]> {
+    return await this.messageRepository.findBySessionId(sessionId, limit);
+  }
+
+  /**
+   * Get messages for a user
+   */
+  async getUserMessages(
+    userId?: string,
+    limit?: number
+  ): Promise<MessageData[]> {
+    const effectiveUserId = userId || this.config.userId;
+    if (!effectiveUserId) {
+      throw new Error(
+        "userId must be provided or configured in PersistenceConfig"
+      );
+    }
+    return await this.messageRepository.findByUserId(effectiveUserId, limit);
+  }
+
+  /**
+   * Delete a session and all its messages
+   */
+  async deleteSession(sessionId: string): Promise<boolean> {
+    // Delete all messages first
+    await this.messageRepository.deleteBySessionId(sessionId);
+
+    // Then delete the session
+    return await this.sessionRepository.delete(sessionId);
+  }
+
+  /**
+   * Complete a session
+   */
+  async completeSession(sessionId: string): Promise<SessionData | null> {
+    return await this.updateSessionStatus(sessionId, "completed", new Date());
+  }
+
+  /**
+   * Abandon a session
+   */
+  async abandonSession(sessionId: string): Promise<SessionData | null> {
+    return await this.updateSessionStatus(sessionId, "abandoned");
+  }
+
+  /**
+   * Helper: Convert message data to Event format
+   */
+  messageToEvent(message: MessageData): Event | undefined {
+    return message.event;
+  }
+
+  /**
+   * Helper: Load history from session messages
+   */
+  async loadSessionHistory(sessionId: string): Promise<Event[]> {
+    const messages = await this.getSessionMessages(sessionId);
+    return messages
+      .map((m) => this.messageToEvent(m))
+      .filter((e): e is Event => e !== undefined);
+  }
+}

package/src/index.ts

@@ -16,6 +16,7 @@ export { adaptEvent, createMessageEvent, createToolEvent } from "./core/Events";
 export { PromptBuilder } from "./core/PromptBuilder";
 export type { Customer, AgentInfo } from "./core/PromptBuilder";
 export { BuiltInSection } from "./core/PromptBuilder";
+export { PersistenceManager } from "./core/PersistenceManager";
 
 // Providers
 export { GeminiProvider } from "./providers/GeminiProvider";
@@ -24,6 +25,16 @@ export { OpenAIProvider } from "./providers/OpenAIProvider";
 export type { OpenAIProviderOptions } from "./providers/OpenAIProvider";
 export { OpenRouterProvider } from "./providers/OpenRouterProvider";
 export type { OpenRouterProviderOptions } from "./providers/OpenRouterProvider";
+export { AnthropicProvider } from "./providers/AnthropicProvider";
+export type { AnthropicProviderOptions } from "./providers/AnthropicProvider";
+
+// Adapters
+export { PrismaAdapter } from "./adapters/PrismaAdapter";
+export type {
+  PrismaClient,
+  FieldMappings,
+  PrismaAdapterOptions,
+} from "./adapters/PrismaAdapter";
 
 // Constants
 export { END_ROUTE } from "./constants";
@@ -92,3 +103,15 @@ export type {
   Observation as IObservation,
   ObservationOptions,
 } from "./types/observation";
+
+export type {
+  SessionData,
+  MessageData,
+  SessionStatus,
+  MessageRole,
+  SessionRepository,
+  MessageRepository,
+  PersistenceConfig,
+  CreateSessionOptions,
+  SaveMessageOptions,
+} from "./types/persistence";