@dexto/core 1.1.4 → 1.1.6

package/dist/context/manager.d.cts

@@ -0,0 +1,254 @@
+import { IMessageFormatter } from '../llm/formatters/types.cjs';
+import { LLMContext } from '../llm/types.cjs';
+import { InternalMessage, ImageData, FileData } from './types.cjs';
+import { ITokenizer } from '../llm/tokenizer/types.cjs';
+import { ICompressionStrategy } from './compression/types.cjs';
+import { DynamicContributorContext } from '../systemPrompt/types.cjs';
+import { PromptManager } from '../systemPrompt/manager.cjs';
+import { IConversationHistoryProvider } from '../session/history/types.cjs';
+import { ValidatedLLMConfig } from '../llm/schemas.cjs';
+import '../mcp/manager.cjs';
+import '../mcp/schemas.cjs';
+import 'zod';
+import '../mcp/types.cjs';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '../tools/types.cjs';
+import 'json-schema';
+import '@modelcontextprotocol/sdk/types.js';
+import '../systemPrompt/schemas.cjs';
+
+/**
+ * Manages conversation history and provides message formatting capabilities for the LLM context.
+ * The ContextManager is responsible for:
+ * - Validating and storing conversation messages via the history provider
+ * - Managing the system prompt
+ * - Formatting messages for specific LLM providers through an injected formatter
+ * - Optionally counting tokens using a provided tokenizer
+ * - Applying compression strategies sequentially if token limits are exceeded
+ * - Providing access to conversation history
+ *
+ * Note: All conversation history is stored and retrieved via the injected ConversationHistoryProvider.
+ * The ContextManager does not maintain an internal history cache.
+ * TODO: clean up tokenizer logic if we are relying primarily on LLM API to give us token count.
+ * TODO: Move InternalMessage parsing logic to zod
+ * Right now its weaker because it doesn't account for tools and other non-text content in the prompt.
+ *
+ * @template TMessage The message type for the specific LLM provider (e.g., MessageParam, ChatCompletionMessageParam, ModelMessage)
+ */
+declare class ContextManager<TMessage = unknown> {
+    /**
+     * The validated LLM configuration.
+     */
+    private llmConfig;
+    /**
+     * PromptManager used to generate/manage the system prompt
+     */
+    private promptManager;
+    /**
+     * Formatter used to convert internal messages to LLM-specific format
+     */
+    private formatter;
+    /**
+     * Maximum number of tokens allowed in the conversation (if specified)
+     */
+    private maxInputTokens;
+    /**
+     * Actual token count from the last LLM response.
+     * Used for more accurate token estimation in hybrid approach.
+     */
+    private lastActualTokenCount;
+    /**
+     * Compression threshold as a percentage of maxInputTokens.
+     * When estimated tokens exceed (maxInputTokens * threshold), compression is triggered.
+     */
+    private compressionThreshold;
+    /**
+     * Tokenizer used for counting tokens and enabling compression (if specified)
+     */
+    private tokenizer;
+    /**
+     * The sequence of compression strategies to apply when maxInputTokens is exceeded.
+     * The order in this array matters, as strategies are applied sequentially until
+     * the token count is within the limit.
+     */
+    private compressionStrategies;
+    private historyProvider;
+    private readonly sessionId;
+    /**
+     * Creates a new ContextManager instance
+     * @param llmConfig The validated LLM configuration.
+     * @param formatter Formatter implementation for the target LLM provider
+     * @param promptManager PromptManager instance for the conversation
+     * @param maxInputTokens Maximum token limit for the conversation history. Triggers compression if exceeded and a tokenizer is provided.
+     * @param tokenizer Tokenizer implementation used for counting tokens and enabling compression.
+     * @param historyProvider Session-scoped ConversationHistoryProvider instance for managing conversation history
+     * @param sessionId Unique identifier for the conversation session (readonly, for debugging)
+     * @param compressionStrategies Optional array of compression strategies to apply when token limits are exceeded
+     */
+    constructor(llmConfig: ValidatedLLMConfig, formatter: IMessageFormatter, promptManager: PromptManager, maxInputTokens: number, tokenizer: ITokenizer, historyProvider: IConversationHistoryProvider, sessionId: string, compressionStrategies?: ICompressionStrategy[]);
+    /**
+     * Returns the current token count of the conversation history.
+     * @returns Promise that resolves to the number of tokens in the current history
+     */
+    getTokenCount(): Promise<number>;
+    /**
+     * Returns the total token count that will be sent to the LLM provider,
+     * including system prompt, formatted messages, and provider-specific overhead.
+     * This provides a more accurate estimate than getTokenCount() alone.
+     *
+     * @param context The DynamicContributorContext for system prompt contributors
+     * @returns Promise that resolves to the total number of tokens that will be sent to the provider
+     */
+    getTotalTokenCount(context: DynamicContributorContext): Promise<number>;
+    /**
+     * Returns the configured maximum number of input tokens for the conversation.
+     */
+    getMaxInputTokens(): number;
+    /**
+     * Updates the ContextManager configuration when LLM config changes.
+     * This is called when DextoAgent.switchLLM() updates the LLM configuration.
+     *
+     * @param newMaxInputTokens New maximum token limit
+     * @param newTokenizer Optional new tokenizer if provider changed
+     * @param newFormatter Optional new formatter if provider/router changed
+     */
+    updateConfig(newMaxInputTokens: number, newTokenizer?: ITokenizer, newFormatter?: IMessageFormatter): void;
+    /**
+     * Updates the actual token count from the last LLM response.
+     * This enables hybrid token counting for more accurate estimates.
+     *
+     * @param actualTokens The actual token count reported by the LLM provider
+     */
+    updateActualTokenCount(actualTokens: number): void;
+    /**
+     * Estimates if new input would trigger compression using hybrid approach.
+     * Combines actual tokens from last response with estimated tokens for new input.
+     *
+     * @param newInputTokens Estimated tokens for the new user input
+     * @returns True if compression should be triggered
+     */
+    shouldCompress(newInputTokens: number): boolean;
+    /**
+     * Assembles and returns the current system prompt by invoking the PromptManager.
+     */
+    getSystemPrompt(context: DynamicContributorContext): Promise<string>;
+    /**
+     * Gets the raw conversation history
+     * Returns a defensive copy to prevent modification
+     *
+     * @returns Promise that resolves to a read-only copy of the conversation history
+     */
+    getHistory(): Promise<Readonly<InternalMessage[]>>;
+    /**
+     * Adds a message to the conversation history.
+     * Performs validation based on message role and required fields.
+     * Note: Compression based on token limits is applied lazily when calling `getFormattedMessages`, not immediately upon adding.
+     *
+     * @param message The message to add to the history
+     * @throws Error if message validation fails
+     */
+    addMessage(message: InternalMessage): Promise<void>;
+    /**
+     * Adds a user message to the conversation
+     * Can include image data for multimodal input
+     *
+     * @param textContent The user message content
+     * @param imageData Optional image data for multimodal input
+     * @param fileData Optional file data for file input
+     * @throws Error if content is empty or not a string
+     */
+    addUserMessage(textContent: string, imageData?: ImageData, fileData?: FileData): Promise<void>;
+    /**
+     * Adds an assistant message to the conversation
+     * Can include tool calls if the assistant is requesting tool execution
+     *
+     * @param content The assistant's response text (can be null if only tool calls)
+     * @param toolCalls Optional tool calls requested by the assistant
+     * @param metadata Optional metadata including token usage, reasoning, and model info
+     * @throws Error if neither content nor toolCalls are provided
+     */
+    addAssistantMessage(content: string | null, toolCalls?: InternalMessage['toolCalls'], metadata?: {
+        tokenUsage?: InternalMessage['tokenUsage'];
+        reasoning?: string;
+    }): Promise<void>;
+    /**
+     * Adds a tool result message to the conversation
+     *
+     * @param toolCallId ID of the tool call this result is responding to
+     * @param name Name of the tool that executed
+     * @param result The result returned by the tool
+     * @throws Error if required parameters are missing
+     */
+    addToolResult(toolCallId: string, name: string, result: unknown): Promise<void>;
+    /**
+     * Sets the system prompt for the conversation
+     *
+     * @param prompt The system prompt text
+     */
+    setSystemPrompt(_prompt: string): void;
+    /**
+     * Gets the conversation history formatted for the target LLM provider.
+     * Applies compression strategies sequentially if the manager is configured with a `maxInputTokens` limit
+     * and a `tokenizer`, and the current token count exceeds the limit. Compression happens *before* formatting.
+     * Uses the injected formatter to convert internal messages (potentially compressed) to the provider's format.
+     *
+     * @param contributorContext The DynamicContributorContext for system prompt contributors and formatting
+     * @param llmContext The llmContext for the formatter to decide which messages to include based on the model's capabilities
+     * @param systemPrompt (Optional) Precomputed system prompt string. If provided, it will be used instead of recomputing the system prompt. Useful for avoiding duplicate computation when both the formatted messages and the raw system prompt are needed in the same request.
+     * @param history (Optional) Pre-fetched and potentially compressed history. If not provided, will fetch from history provider.
+     * @returns Formatted messages ready to send to the LLM provider API
+     * @throws Error if formatting or compression fails critically
+     */
+    getFormattedMessages(contributorContext: DynamicContributorContext, llmContext: LLMContext, systemPrompt?: string | undefined, history?: InternalMessage[]): Promise<TMessage[]>;
+    /**
+     * Gets the conversation ready for LLM consumption with proper flow:
+     * 1. Get system prompt
+     * 2. Get history and compress if needed
+     * 3. Format messages
+     * This method implements the correct ordering to avoid circular dependencies.
+     *
+     * @param contributorContext The DynamicContributorContext for system prompt contributors and formatting
+     * @param llmContext The llmContext for the formatter to decide which messages to include based on the model's capabilities
+     * @returns Object containing formatted messages and system prompt
+     */
+    getFormattedMessagesWithCompression(contributorContext: DynamicContributorContext, llmContext: LLMContext): Promise<{
+        formattedMessages: TMessage[];
+        systemPrompt: string;
+        tokensUsed: number;
+    }>;
+    /**
+     * Gets the system prompt formatted for the target LLM provider
+     * Some providers handle system prompts differently
+     *
+     * @returns Formatted system prompt or null/undefined based on formatter implementation
+     * @throws Error if formatting fails
+     */
+    getFormattedSystemPrompt(context: DynamicContributorContext): Promise<string | null | undefined>;
+    /**
+     * Resets the conversation history
+     * Does not reset the system prompt
+     */
+    resetConversation(): Promise<void>;
+    /**
+     * Checks if history compression is needed based on token count and applies strategies.
+     *
+     * @param history The conversation history to potentially compress
+     * @param systemPromptTokens The actual token count of the system prompt
+     * @returns The potentially compressed history
+     */
+    compressHistoryIfNeeded(history: InternalMessage[], systemPromptTokens: number): Promise<InternalMessage[]>;
+    /**
+     * Parses a raw LLM stream response, converts it into internal messages and adds them to the history.
+     *
+     * @param response The stream response from the LLM provider
+     */
+    processLLMStreamResponse(response: unknown): Promise<void>;
+    /**
+     * Parses a raw LLM response, converts it into internal messages and adds them to the history.
+     *
+     * @param response The response from the LLM provider
+     */
+    processLLMResponse(response: unknown): Promise<void>;
+}
+
+export { ContextManager };

package/dist/context/manager.d.ts

@@ -0,0 +1,254 @@
+import { IMessageFormatter } from '../llm/formatters/types.js';
+import { LLMContext } from '../llm/types.js';
+import { InternalMessage, ImageData, FileData } from './types.js';
+import { ITokenizer } from '../llm/tokenizer/types.js';
+import { ICompressionStrategy } from './compression/types.js';
+import { DynamicContributorContext } from '../systemPrompt/types.js';
+import { PromptManager } from '../systemPrompt/manager.js';
+import { IConversationHistoryProvider } from '../session/history/types.js';
+import { ValidatedLLMConfig } from '../llm/schemas.js';
+import '../mcp/manager.js';
+import '../mcp/schemas.js';
+import 'zod';
+import '../mcp/types.js';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '../tools/types.js';
+import 'json-schema';
+import '@modelcontextprotocol/sdk/types.js';
+import '../systemPrompt/schemas.js';
+
+/**
+ * Manages conversation history and provides message formatting capabilities for the LLM context.
+ * The ContextManager is responsible for:
+ * - Validating and storing conversation messages via the history provider
+ * - Managing the system prompt
+ * - Formatting messages for specific LLM providers through an injected formatter
+ * - Optionally counting tokens using a provided tokenizer
+ * - Applying compression strategies sequentially if token limits are exceeded
+ * - Providing access to conversation history
+ *
+ * Note: All conversation history is stored and retrieved via the injected ConversationHistoryProvider.
+ * The ContextManager does not maintain an internal history cache.
+ * TODO: clean up tokenizer logic if we are relying primarily on LLM API to give us token count.
+ * TODO: Move InternalMessage parsing logic to zod
+ * Right now its weaker because it doesn't account for tools and other non-text content in the prompt.
+ *
+ * @template TMessage The message type for the specific LLM provider (e.g., MessageParam, ChatCompletionMessageParam, ModelMessage)
+ */
+declare class ContextManager<TMessage = unknown> {
+    /**
+     * The validated LLM configuration.
+     */
+    private llmConfig;
+    /**
+     * PromptManager used to generate/manage the system prompt
+     */
+    private promptManager;
+    /**
+     * Formatter used to convert internal messages to LLM-specific format
+     */
+    private formatter;
+    /**
+     * Maximum number of tokens allowed in the conversation (if specified)
+     */
+    private maxInputTokens;
+    /**
+     * Actual token count from the last LLM response.
+     * Used for more accurate token estimation in hybrid approach.
+     */
+    private lastActualTokenCount;
+    /**
+     * Compression threshold as a percentage of maxInputTokens.
+     * When estimated tokens exceed (maxInputTokens * threshold), compression is triggered.
+     */
+    private compressionThreshold;
+    /**
+     * Tokenizer used for counting tokens and enabling compression (if specified)
+     */
+    private tokenizer;
+    /**
+     * The sequence of compression strategies to apply when maxInputTokens is exceeded.
+     * The order in this array matters, as strategies are applied sequentially until
+     * the token count is within the limit.
+     */
+    private compressionStrategies;
+    private historyProvider;
+    private readonly sessionId;
+    /**
+     * Creates a new ContextManager instance
+     * @param llmConfig The validated LLM configuration.
+     * @param formatter Formatter implementation for the target LLM provider
+     * @param promptManager PromptManager instance for the conversation
+     * @param maxInputTokens Maximum token limit for the conversation history. Triggers compression if exceeded and a tokenizer is provided.
+     * @param tokenizer Tokenizer implementation used for counting tokens and enabling compression.
+     * @param historyProvider Session-scoped ConversationHistoryProvider instance for managing conversation history
+     * @param sessionId Unique identifier for the conversation session (readonly, for debugging)
+     * @param compressionStrategies Optional array of compression strategies to apply when token limits are exceeded
+     */
+    constructor(llmConfig: ValidatedLLMConfig, formatter: IMessageFormatter, promptManager: PromptManager, maxInputTokens: number, tokenizer: ITokenizer, historyProvider: IConversationHistoryProvider, sessionId: string, compressionStrategies?: ICompressionStrategy[]);
+    /**
+     * Returns the current token count of the conversation history.
+     * @returns Promise that resolves to the number of tokens in the current history
+     */
+    getTokenCount(): Promise<number>;
+    /**
+     * Returns the total token count that will be sent to the LLM provider,
+     * including system prompt, formatted messages, and provider-specific overhead.
+     * This provides a more accurate estimate than getTokenCount() alone.
+     *
+     * @param context The DynamicContributorContext for system prompt contributors
+     * @returns Promise that resolves to the total number of tokens that will be sent to the provider
+     */
+    getTotalTokenCount(context: DynamicContributorContext): Promise<number>;
+    /**
+     * Returns the configured maximum number of input tokens for the conversation.
+     */
+    getMaxInputTokens(): number;
+    /**
+     * Updates the ContextManager configuration when LLM config changes.
+     * This is called when DextoAgent.switchLLM() updates the LLM configuration.
+     *
+     * @param newMaxInputTokens New maximum token limit
+     * @param newTokenizer Optional new tokenizer if provider changed
+     * @param newFormatter Optional new formatter if provider/router changed
+     */
+    updateConfig(newMaxInputTokens: number, newTokenizer?: ITokenizer, newFormatter?: IMessageFormatter): void;
+    /**
+     * Updates the actual token count from the last LLM response.
+     * This enables hybrid token counting for more accurate estimates.
+     *
+     * @param actualTokens The actual token count reported by the LLM provider
+     */
+    updateActualTokenCount(actualTokens: number): void;
+    /**
+     * Estimates if new input would trigger compression using hybrid approach.
+     * Combines actual tokens from last response with estimated tokens for new input.
+     *
+     * @param newInputTokens Estimated tokens for the new user input
+     * @returns True if compression should be triggered
+     */
+    shouldCompress(newInputTokens: number): boolean;
+    /**
+     * Assembles and returns the current system prompt by invoking the PromptManager.
+     */
+    getSystemPrompt(context: DynamicContributorContext): Promise<string>;
+    /**
+     * Gets the raw conversation history
+     * Returns a defensive copy to prevent modification
+     *
+     * @returns Promise that resolves to a read-only copy of the conversation history
+     */
+    getHistory(): Promise<Readonly<InternalMessage[]>>;
+    /**
+     * Adds a message to the conversation history.
+     * Performs validation based on message role and required fields.
+     * Note: Compression based on token limits is applied lazily when calling `getFormattedMessages`, not immediately upon adding.
+     *
+     * @param message The message to add to the history
+     * @throws Error if message validation fails
+     */
+    addMessage(message: InternalMessage): Promise<void>;
+    /**
+     * Adds a user message to the conversation
+     * Can include image data for multimodal input
+     *
+     * @param textContent The user message content
+     * @param imageData Optional image data for multimodal input
+     * @param fileData Optional file data for file input
+     * @throws Error if content is empty or not a string
+     */
+    addUserMessage(textContent: string, imageData?: ImageData, fileData?: FileData): Promise<void>;
+    /**
+     * Adds an assistant message to the conversation
+     * Can include tool calls if the assistant is requesting tool execution
+     *
+     * @param content The assistant's response text (can be null if only tool calls)
+     * @param toolCalls Optional tool calls requested by the assistant
+     * @param metadata Optional metadata including token usage, reasoning, and model info
+     * @throws Error if neither content nor toolCalls are provided
+     */
+    addAssistantMessage(content: string | null, toolCalls?: InternalMessage['toolCalls'], metadata?: {
+        tokenUsage?: InternalMessage['tokenUsage'];
+        reasoning?: string;
+    }): Promise<void>;
+    /**
+     * Adds a tool result message to the conversation
+     *
+     * @param toolCallId ID of the tool call this result is responding to
+     * @param name Name of the tool that executed
+     * @param result The result returned by the tool
+     * @throws Error if required parameters are missing
+     */
+    addToolResult(toolCallId: string, name: string, result: unknown): Promise<void>;
+    /**
+     * Sets the system prompt for the conversation
+     *
+     * @param prompt The system prompt text
+     */
+    setSystemPrompt(_prompt: string): void;
+    /**
+     * Gets the conversation history formatted for the target LLM provider.
+     * Applies compression strategies sequentially if the manager is configured with a `maxInputTokens` limit
+     * and a `tokenizer`, and the current token count exceeds the limit. Compression happens *before* formatting.
+     * Uses the injected formatter to convert internal messages (potentially compressed) to the provider's format.
+     *
+     * @param contributorContext The DynamicContributorContext for system prompt contributors and formatting
+     * @param llmContext The llmContext for the formatter to decide which messages to include based on the model's capabilities
+     * @param systemPrompt (Optional) Precomputed system prompt string. If provided, it will be used instead of recomputing the system prompt. Useful for avoiding duplicate computation when both the formatted messages and the raw system prompt are needed in the same request.
+     * @param history (Optional) Pre-fetched and potentially compressed history. If not provided, will fetch from history provider.
+     * @returns Formatted messages ready to send to the LLM provider API
+     * @throws Error if formatting or compression fails critically
+     */
+    getFormattedMessages(contributorContext: DynamicContributorContext, llmContext: LLMContext, systemPrompt?: string | undefined, history?: InternalMessage[]): Promise<TMessage[]>;
+    /**
+     * Gets the conversation ready for LLM consumption with proper flow:
+     * 1. Get system prompt
+     * 2. Get history and compress if needed
+     * 3. Format messages
+     * This method implements the correct ordering to avoid circular dependencies.
+     *
+     * @param contributorContext The DynamicContributorContext for system prompt contributors and formatting
+     * @param llmContext The llmContext for the formatter to decide which messages to include based on the model's capabilities
+     * @returns Object containing formatted messages and system prompt
+     */
+    getFormattedMessagesWithCompression(contributorContext: DynamicContributorContext, llmContext: LLMContext): Promise<{
+        formattedMessages: TMessage[];
+        systemPrompt: string;
+        tokensUsed: number;
+    }>;
+    /**
+     * Gets the system prompt formatted for the target LLM provider
+     * Some providers handle system prompts differently
+     *
+     * @returns Formatted system prompt or null/undefined based on formatter implementation
+     * @throws Error if formatting fails
+     */
+    getFormattedSystemPrompt(context: DynamicContributorContext): Promise<string | null | undefined>;
+    /**
+     * Resets the conversation history
+     * Does not reset the system prompt
+     */
+    resetConversation(): Promise<void>;
+    /**
+     * Checks if history compression is needed based on token count and applies strategies.
+     *
+     * @param history The conversation history to potentially compress
+     * @param systemPromptTokens The actual token count of the system prompt
+     * @returns The potentially compressed history
+     */
+    compressHistoryIfNeeded(history: InternalMessage[], systemPromptTokens: number): Promise<InternalMessage[]>;
+    /**
+     * Parses a raw LLM stream response, converts it into internal messages and adds them to the history.
+     *
+     * @param response The stream response from the LLM provider
+     */
+    processLLMStreamResponse(response: unknown): Promise<void>;
+    /**
+     * Parses a raw LLM response, converts it into internal messages and adds them to the history.
+     *
+     * @param response The response from the LLM provider
+     */
+    processLLMResponse(response: unknown): Promise<void>;
+}
+
+export { ContextManager };