@aigne/core 1.72.0-beta.2 → 1.72.0-beta.23

package/lib/esm/prompt/agent-session.d.ts

@@ -0,0 +1,163 @@
+import type { AFS } from "@aigne/afs";
+import type { AgentInvokeOptions } from "../agents/agent.js";
+import type { ChatModelInputMessage } from "../agents/chat-model.js";
+import { type CompactConfig, type SessionMemoryConfig, type SessionMode, type UserMemoryConfig } from "./compact/types.js";
+export * from "./compact/types.js";
+export interface AgentSessionOptions {
+    sessionId: string;
+    userId?: string;
+    agentId?: string;
+    afs?: AFS;
+    /**
+     * Session mode
+     * - "auto": Enable history recording, compaction, and memory extraction
+     * - "disabled": Disable all session features (history, compaction, memory)
+     *
+     * **Should be "disabled" for internal utility agents** (extractors, compactors, etc.)
+     * to avoid recursive memory extraction and unnecessary overhead.
+     *
+     * @default DEFAULT_SESSION_MODE ("auto")
+     */
+    mode?: SessionMode;
+    /**
+     * Compaction configuration
+     */
+    compact?: CompactConfig;
+    /**
+     * Session memory configuration
+     */
+    sessionMemory?: SessionMemoryConfig;
+    /**
+     * User memory configuration
+     */
+    userMemory?: UserMemoryConfig;
+}
+export declare class AgentSession {
+    readonly sessionId: string;
+    readonly userId?: string;
+    readonly agentId?: string;
+    private afs?;
+    private historyModulePath?;
+    private mode;
+    private compactConfig;
+    private sessionMemoryConfig;
+    private userMemoryConfig;
+    private runtimeState;
+    private initialized?;
+    private compactionPromise?;
+    private sessionMemoryUpdatePromise?;
+    private userMemoryUpdatePromise?;
+    constructor(options: AgentSessionOptions);
+    /**
+     * Check if memory extraction is enabled
+     * Memory extraction requires mode to be "auto" AND AFS history module to be available
+     */
+    private get isMemoryEnabled();
+    setSystemMessages(...messages: ChatModelInputMessage[]): Promise<void>;
+    getMessages(): Promise<ChatModelInputMessage[]>;
+    /**
+     * Format user memory facts into a system message
+     * Applies token budget limit to ensure memory injection fits within constraints
+     */
+    private formatUserMemory;
+    /**
+     * Format session memory facts into a system message
+     * Applies token budget limit to ensure memory injection fits within constraints
+     */
+    private formatSessionMemory;
+    private formatMemoryTemplate;
+    startMessage(input: unknown, message: ChatModelInputMessage, options: AgentInvokeOptions): Promise<void>;
+    endMessage(output: unknown, message: ChatModelInputMessage | undefined, options: AgentInvokeOptions): Promise<void>;
+    /**
+     * Manually trigger compaction
+     */
+    compact(options: AgentInvokeOptions): Promise<void>;
+    /**
+     * Internal method that performs the actual compaction
+     */
+    private doCompact;
+    private compactCurrentEntry;
+    private maybeCompactCurrentEntry;
+    private maybeAutoCompact;
+    /**
+     * Estimate token count for messages
+     * Applies singleMessageLimit to each text block individually
+     * Non-text tokens (images, tool calls) are always counted in full
+     */
+    private estimateMessagesTokens;
+    /**
+     * Split entries into batches based on token limit
+     * Each batch will not exceed the specified maxTokens
+     */
+    private splitIntoBatches;
+    appendCurrentMessages(messages: ChatModelInputMessage | ChatModelInputMessage[], options: AgentInvokeOptions): Promise<void>;
+    /**
+     * Truncate text content to fit within target token limit
+     * @param text The text to truncate
+     * @param currentTokens Current token count of the text
+     * @param targetTokens Target token count after truncation
+     * @returns Truncated text
+     */
+    private truncateText;
+    private truncateLargeMessage;
+    private ensureInitialized;
+    private initialize;
+    /**
+     * Load session memory facts
+     * @returns Array of memory fact entries for the current session
+     */
+    private loadSessionMemory;
+    /**
+     * Load user memory facts
+     * @returns Array of memory fact entries for the current user
+     */
+    private loadUserMemory;
+    /**
+     * Load session history including compact content and history entries
+     * @returns Object containing history compact and history entries
+     */
+    private loadSessionHistory;
+    /**
+     * Manually trigger session memory update
+     */
+    updateSessionMemory(options: AgentInvokeOptions): Promise<void>;
+    private maybeAutoUpdateSessionMemory;
+    private maybeAutoUpdateUserMemory;
+    /**
+     * Internal method that performs the actual session memory update
+     */
+    private doUpdateSessionMemory;
+    /**
+     * Manually trigger user memory update
+     */
+    updateUserMemory(options: AgentInvokeOptions): Promise<void>;
+    /**
+     * Internal method that performs the actual user memory extraction
+     */
+    private doUpdateUserMemory;
+    /**
+     * Find Agent Skill content from a single message
+     * @param msg - Message to search in
+     * @returns The skill content text if found, undefined otherwise
+     */
+    private findSkillContentInMessage;
+    /**
+     * Find the last Agent Skill from a list of messages
+     * @param messages - Messages to search through
+     * @returns The last Agent Skill found, or undefined if none found
+     */
+    private findLastAgentSkillFromMessages;
+    /**
+     * Find the last Agent Skill from a list of history entries
+     * @param entries - History entries to search through
+     * @returns The last Agent Skill found, or undefined if none found
+     */
+    private findLastAgentSkill;
+    private initializeDefaultCompactor;
+    private initializeDefaultSessionMemoryExtractor;
+    private initializeDefaultUserMemoryExtractor;
+    private get maxTokens();
+    private get keepRecentRatio();
+    private get keepRecentTokens();
+    private get singleMessageLimit();
+}