@falai/agent 3.4.5 → 4.0.0-alpha.2

package/src/core/SessionFinalizer.ts

@@ -1,108 +0,0 @@
-/**
- * SessionFinalizer owns end-of-turn session finalization: deterministic
- * history compaction, persistence auto-save, the step `finalize` hook,
- * and syncing the finalized session back to the agent's live session.
- *
- * Every turn finalizes exactly once: the non-streaming path in
- * `respond()` after generation completes; the streaming path in the
- * final-chunk interception loop after the post-signal phase (so
- * post-phase session mutations are persisted), with only the
- * pre-routing signal/auto-chain halt chunks finalizing at their own
- * yield sites.
- */
-
-import type { AgentOptions, SessionState } from "../types/index.js";
-import type { CompactionOptions } from "../types/compaction.js";
-import type { PersistenceManager } from "./PersistenceManager.js";
-import type { StepLifecycle } from "./StepLifecycle.js";
-import { flow } from "./flow-namespace.js";
-import { CompactionEngine } from "./CompactionEngine.js";
-import { boundConversationHistory, DEFAULT_MAX_HISTORY_MESSAGES, logger } from "../utils/index.js";
-
-export class SessionFinalizer<TContext = unknown, TData = unknown> {
-    constructor(
-        private readonly deps: {
-            getCompactionOptions: () => CompactionOptions | undefined;
-            getPersistenceManager: () => PersistenceManager<TData> | undefined;
-            getAgentOptions: () => AgentOptions<TContext, TData>;
-            getCurrentSession: () => SessionState<TData> | undefined;
-            setCurrentSession: (session: SessionState<TData>) => void;
-            stepLifecycle: StepLifecycle<TContext, TData>;
-            /** ResponseModalOptions.enableAutoSave (undefined means enabled). */
-            enableAutoSave?: boolean;
-        }
-    ) { }
-
-    /**
-     * Handle session persistence and finalization.
-     */
-    async finalize(session: SessionState<TData>, context: TContext): Promise<void> {
-        const agentOptions = this.deps.getAgentOptions();
-
-        // Hard history bound — backstop when no compaction is configured (or
-        // after it ran). Unbounded growth eventually bricks the thread at the
-        // provider context limit.
-        const historyCap = agentOptions.maxHistoryMessages ?? DEFAULT_MAX_HISTORY_MESSAGES;
-        if (historyCap > 0 && session.history && session.history.length > historyCap) {
-            const bounded = boundConversationHistory(session.history, historyCap);
-            if (bounded !== session.history) {
-                logger.warn(
-                    `[SessionFinalizer] Session "${session.id}" history exceeded ${historyCap} entries ` +
-                    `(${session.history.length}); trimmed the oldest. Configure compaction for ` +
-                    `summarization instead of truncation, or raise maxHistoryMessages.`
-                );
-                session.history = bounded;
-            }
-        }
-
-        // Deterministic compaction: runs on every finalize (not just addMessage)
-        // so respond()-only callers get bounded history too
-        const compactionOptions = this.deps.getCompactionOptions();
-        if (compactionOptions && session.history && session.history.length > 0) {
-            try {
-                const result = await CompactionEngine.checkAndCompact(session.history, compactionOptions);
-                if (result.strategy !== 'none') {
-                    session.history = result.history;
-                    logger.info(
-                        `[SessionFinalizer] Compaction applied: strategy='${result.strategy}', ` +
-                        `estimatedTokens=${result.estimatedTokens}, messagesCompacted=${result.messagesCompacted}`
-                    );
-                }
-            } catch (error) {
-                logger.warn("[SessionFinalizer] Compaction failed at finalize, continuing without compaction", error);
-            }
-        }
-
-        // Execute finalize BEFORE persisting so its state writes (which now
-        // land on this turn's session) are captured by the save below. A
-        // control-flow directive returned by finalize queues on the session —
-        // the pendingDirective applier applies it at the START of the next turn.
-        let finalizeDirective;
-        try {
-            finalizeDirective = await this.deps.stepLifecycle.runFinalize(session, context);
-        } catch (error) {
-            logger.error("[SessionFinalizer] Step finalize hook failed:", error);
-            throw error;
-        }
-        if (finalizeDirective) {
-            flow.queuePending(session, finalizeDirective);
-        }
-
-        // Auto-save session step to persistence if configured
-        const persistenceManager = this.deps.getPersistenceManager();
-        if (
-            persistenceManager &&
-            session.id &&
-            (this.deps.enableAutoSave !== false && agentOptions.persistence?.autoSave !== false)
-        ) {
-            await persistenceManager.saveSessionState(session.id, session);
-            logger.debug(`[SessionFinalizer] Auto-saved session step to persistence: ${session.id}`);
-        }
-
-        // Update current session if we have one
-        const currentSession = this.deps.getCurrentSession();
-        if (currentSession) {
-            this.deps.setCurrentSession(session);
-        }
-    }
-}

package/src/core/SessionManager.ts

@@ -1,372 +0,0 @@
-/**
- * SessionManager - Simplified session management with history
- *
- * Provides a clean, pragmatic API for managing sessions and conversation history
- * in both server and client environments.
- */
-
-import log from "loglevel";
-import type { SessionState } from "../types/session.js";
-import type { History, HistoryItem } from "../types/history.js";
-import { PersistenceManager } from "./PersistenceManager.js";
-import { CompactionEngine } from "./CompactionEngine.js";
-import type { PersistenceAdapter } from "../types/persistence.js";
-import type { Agent } from "./Agent.js";
-import { boundConversationHistory, createSession, DEFAULT_MAX_HISTORY_MESSAGES } from "../utils/index.js";
-
-/**
- * SessionManager handles session lifecycle and conversation history
- */
-export class SessionManager<TData = unknown> {
-  private currentSession?: SessionState<TData>;
-  private persistenceManager?: PersistenceManager<TData>;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private agent?: Agent<any, TData>;
-  private defaultSessionId?: string;
-
-  /** Coalesces concurrent getOrCreate calls for the same session id. */
-  private inflightGets = new Map<string, Promise<SessionState<TData>>>();
-
-  constructor(
-    persistenceManagerOrAdapter?:
-      | PersistenceManager<TData>
-      | PersistenceAdapter<TData>,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    agent?: Agent<any, TData>
-  ) {
-    if (persistenceManagerOrAdapter) {
-      // Check if it's a PersistenceManager or an adapter
-      if ("saveSessionState" in persistenceManagerOrAdapter) {
-        this.persistenceManager = persistenceManagerOrAdapter;
-      } else {
-        // It's an adapter, create a PersistenceManager
-        this.persistenceManager = new PersistenceManager({
-          adapter: persistenceManagerOrAdapter,
-        });
-      }
-    }
-
-    this.agent = agent;
-  }
-
-  /**
-   * Set the default session ID to use when getOrCreate is called without parameters
-   * @internal Used by Agent to set the sessionId from constructor options
-   */
-  setDefaultSessionId(sessionId: string): void {
-    this.defaultSessionId = sessionId;
-  }
-
-  /**
-   * Core method: getOrCreate handles both existing and new sessions
-   * Works for sessionIds that exist, don't exist, or auto-generated IDs.
-   *
-   * Concurrent calls for the same id are COALESCED into one in-flight load:
-   * the Agent constructor fires an un-awaited getOrCreate while a first turn
-   * may already be starting — without coalescing, both calls can observe a
-   * missing row and create two competing sessions (one blanking the other's
-   * persisted state).
-   */
-  async getOrCreate(sessionId?: string): Promise<SessionState<TData>> {
-    // SECURITY: a non-string sessionId (e.g. `{ $ne: null }` from an HTTP body
-    // or `?sessionId[$ne]=` query) forwarded into a NoSQL query becomes an
-    // operator clause. Reject it at the entry point; `undefined` is allowed and
-    // auto-generates an id, and an empty string keeps its fall-back semantics.
-    if (sessionId !== undefined && typeof sessionId !== "string") {
-      throw new Error("sessionId must be a string");
-    }
-    // Use provided sessionId or fall back to default
-    const effectiveSessionId = sessionId || this.defaultSessionId;
-
-    const inflightKey = effectiveSessionId || "__auto__";
-    const inflight = this.inflightGets.get(inflightKey);
-    if (inflight) {
-      return inflight;
-    }
-
-    const promise = this.getOrCreateInner(effectiveSessionId).finally(() => {
-      this.inflightGets.delete(inflightKey);
-    });
-    this.inflightGets.set(inflightKey, promise);
-    return promise;
-  }
-
-  private async getOrCreateInner(
-    effectiveSessionId: string | undefined
-  ): Promise<SessionState<TData>> {
-
-    // If we already have a session and no sessionId specified, return it
-    if (this.currentSession && !effectiveSessionId) {
-      return this.currentSession;
-    }
-
-    // If we have a session with the same ID, return it
-    if (this.currentSession && this.currentSession.id === effectiveSessionId) {
-      return this.currentSession;
-    }
-
-    // If sessionId provided, try to load it first. A missing row returns
-    // `null` (→ create below); a FAILED load throws — swallowing it here used
-    // to fall through to create(), which saved a blank session over the
-    // existing row and erased the user's conversation on a transient DB error.
-    if (effectiveSessionId && this.persistenceManager) {
-      const session = await this.persistenceManager.loadSessionState(
-        effectiveSessionId
-      );
-      if (session) {
-        // Loaded session data wins over anything staged before it existed
-        const pending = this.agent?.consumePendingData();
-        if (pending && Object.keys(pending).length > 0) {
-          log.debug(
-            "SessionManager: discarding pre-session staged data in favor of loaded session state",
-            pending
-          );
-        }
-        this.currentSession = session;
-        return session;
-      }
-    }
-
-    // Create new session (with provided ID or auto-generated)
-    return this.create(effectiveSessionId);
-  }
-
-  /**
-   * Create a new session with optional custom ID
-   */
-  private async create(sessionId?: string): Promise<SessionState<TData>> {
-    const session = createSession<TData>({
-      id: sessionId,
-      history: [], // Session manages its own history
-      // Seed with data staged before the session existed (initialData,
-      // pre-session updateCollectedData calls)
-      data: this.agent?.consumePendingData() ?? ({} as Partial<TData>),
-    });
-
-    this.currentSession = session;
-
-    // Save to persistence if available
-    if (this.persistenceManager) {
-      await this.persistenceManager.saveSessionState(session.id, session);
-    }
-
-    return session;
-  }
-
-  /**
-   * Add a message to the session history
-   */
-  async addMessage(
-    role: "user" | "assistant",
-    content: string,
-    name?: string
-  ): Promise<void> {
-    const session = await this.getOrCreate();
-
-    if (!session.history) {
-      session.history = [];
-    }
-
-    const historyItem: HistoryItem = {
-      role,
-      content,
-      ...(name && { name }),
-    };
-
-    session.history.push(historyItem);
-    // Same hard bound the finalizer applies — keeps interim auto-saves bounded
-    // on the chat()/stream() path too.
-    const cap = this.agent?.getAgentOptions().maxHistoryMessages ?? DEFAULT_MAX_HISTORY_MESSAGES;
-    if (cap > 0 && session.history) {
-      const bounded = boundConversationHistory(session.history, cap);
-      if (bounded !== session.history) {
-        log.warn(`SessionManager: history exceeded ${cap} entries; trimmed the oldest.`);
-        session.history = bounded;
-      }
-    }
-    session.metadata!.lastUpdatedAt = new Date();
-
-    // Ensure currentSession is updated
-    this.currentSession = session;
-
-    // Apply compaction if configured
-    try {
-      const compactionOptions = this.agent?.getCompactionOptions();
-      if (compactionOptions) {
-        const result = await CompactionEngine.checkAndCompact(session.history, compactionOptions);
-        if (result.strategy !== 'none') {
-          session.history = result.history;
-          log.info(
-            `CompactionEngine: applied strategy '${result.strategy}', ` +
-            `estimatedTokens=${result.estimatedTokens}, messagesCompacted=${result.messagesCompacted}`
-          );
-        }
-      }
-    } catch (error) {
-      log.warn("CompactionEngine: compaction failed, continuing without compaction", error);
-    }
-
-    // Auto-save to persistence
-    await this.save();
-  }
-
-  /**
-   * Get the current conversation history
-   */
-  getHistory(): History {
-    return this.currentSession?.history || [];
-  }
-
-  /**
-   * Set the entire conversation history
-   */
-  setHistory(history: History): void {
-    if (this.currentSession) {
-      this.currentSession.history = history ? [...history] : [];
-      this.currentSession.metadata!.lastUpdatedAt = new Date();
-    }
-  }
-
-  /**
-   * Clear all conversation history
-   */
-  clearHistory(): void {
-    if (this.currentSession) {
-      this.currentSession.history = [];
-      this.currentSession.metadata!.lastUpdatedAt = new Date();
-    }
-  }
-
-  /**
-   * Save the current session to persistence
-   */
-  async save(): Promise<void> {
-    if (this.currentSession && this.persistenceManager) {
-      await this.persistenceManager.saveSessionState(
-        this.currentSession.id,
-        this.currentSession
-      );
-    }
-  }
-
-  /**
-   * Delete the current session from persistence
-   */
-  async delete(): Promise<void> {
-    if (this.currentSession && this.persistenceManager) {
-      await this.persistenceManager.deleteSession(this.currentSession.id);
-      this.currentSession = undefined;
-    }
-  }
-
-  /**
-   * Get the current session
-   */
-  get current(): SessionState<TData> | undefined {
-    return this.currentSession;
-  }
-
-  /**
-   * Get the current session ID
-   */
-  get id(): string | undefined {
-    return this.currentSession?.id;
-  }
-
-  /**
-   * Get agent-level collected data from the current session
-   */
-  getData(): Partial<TData> {
-    return this.currentSession?.data || ({} as Partial<TData>);
-  }
-
-  /**
-   * Set/merge agent-level data into the current session
-   * This updates the single source of truth for all collected data
-   */
-  async setData(data: Partial<TData>): Promise<void> {
-    // Ensure session exists
-    await this.getOrCreate();
-
-    if (this.currentSession && data) {
-      if (this.agent) {
-        // Route through the agent so schema validation and onDataUpdate
-        // hooks run; it writes into this session's data directly
-        await this.agent.updateCollectedData(data);
-      } else {
-        this.currentSession.data = {
-          ...this.currentSession.data,
-          ...data,
-        };
-        this.currentSession.metadata!.lastUpdatedAt = new Date();
-      }
-
-      // Auto-save to persistence
-      await this.save();
-    }
-  }
-
-  /**
-   * Update specific fields in the agent-level data
-   * Provides a more explicit method for data updates
-   */
-  async updateData(updates: Partial<TData>): Promise<void> {
-    await this.setData(updates);
-  }
-
-  /**
-   * Clear all collected data while preserving session structure
-   */
-  async clearData(): Promise<void> {
-    if (this.currentSession) {
-      this.currentSession.data = {} as Partial<TData>;
-      this.currentSession.metadata!.lastUpdatedAt = new Date();
-
-      // Auto-save to persistence
-      await this.save();
-    }
-  }
-
-  /**
-   * Reset the session (creates new session, optionally preserving history)
-   */
-  async reset(preserveHistory = false): Promise<SessionState<TData>> {
-    const oldId = this.currentSession?.id;
-    const history = preserveHistory ? this.currentSession?.history : [];
-
-    // Create new session
-    const newSession = await this.create();
-
-    // Preserve history if requested
-    if (preserveHistory && history) {
-      newSession.history = [...history];
-    }
-
-    // Clean up old session from persistence
-    if (oldId && this.persistenceManager) {
-      await this.persistenceManager.deleteSession(oldId);
-    }
-
-    await this.save();
-    return newSession;
-  }
-
-  /**
-   * Sync the session state without triggering persistence save.
-   * Used by modern APIs (stream, generate, chat) to push the finalized session
-   * back to `currentSession` after completion. Persistence is handled separately
-   * by `finalizeSession()`.
-   *
-   * @internal Called from ResponseModal after stream()/generate() completion
-   */
-  syncSession(session: SessionState<TData> | undefined): void {
-    this.currentSession = session;
-  }
-
-  /**
-   * Get the persistence manager (for testing purposes)
-   */
-  getPersistenceManager(): PersistenceManager<TData> | undefined {
-    return this.persistenceManager;
-  }
-}