@dexto/core 1.1.4 → 1.1.6

package/dist/context/manager.js

@@ -0,0 +1,492 @@
+import { MiddleRemovalStrategy } from "./compression/middle-removal.js";
+import { OldestRemovalStrategy } from "./compression/oldest-removal.js";
+import { logger } from "../logger/index.js";
+import { countMessagesTokens, sanitizeToolResultToContent } from "./utils.js";
+import { ContextError } from "./errors.js";
+class ContextManager {
+  /**
+   * The validated LLM configuration.
+   */
+  llmConfig;
+  /**
+   * PromptManager used to generate/manage the system prompt
+   */
+  promptManager;
+  /**
+   * Formatter used to convert internal messages to LLM-specific format
+   */
+  formatter;
+  /**
+   * Maximum number of tokens allowed in the conversation (if specified)
+   */
+  maxInputTokens;
+  /**
+   * Actual token count from the last LLM response.
+   * Used for more accurate token estimation in hybrid approach.
+   */
+  lastActualTokenCount = 0;
+  /**
+   * Compression threshold as a percentage of maxInputTokens.
+   * When estimated tokens exceed (maxInputTokens * threshold), compression is triggered.
+   */
+  compressionThreshold = 0.8;
+  // 80% threshold
+  /**
+   * Tokenizer used for counting tokens and enabling compression (if specified)
+   */
+  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.
+   */
+  compressionStrategies;
+  historyProvider;
+  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, formatter, promptManager, maxInputTokens, tokenizer, historyProvider, sessionId, compressionStrategies = [
+    new MiddleRemovalStrategy(),
+    new OldestRemovalStrategy()
+  ]) {
+    this.llmConfig = llmConfig;
+    this.formatter = formatter;
+    this.promptManager = promptManager;
+    this.maxInputTokens = maxInputTokens;
+    this.tokenizer = tokenizer;
+    this.historyProvider = historyProvider;
+    this.sessionId = sessionId;
+    this.compressionStrategies = compressionStrategies;
+    logger.debug(
+      `ContextManager: Initialized for session ${sessionId} - history will be managed by ${historyProvider.constructor.name}`
+    );
+  }
+  /**
+   * Returns the current token count of the conversation history.
+   * @returns Promise that resolves to the number of tokens in the current history
+   */
+  async getTokenCount() {
+    const history = await this.historyProvider.getHistory();
+    return countMessagesTokens(history, this.tokenizer);
+  }
+  /**
+   * 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
+   */
+  async getTotalTokenCount(context) {
+    try {
+      const systemPrompt = await this.getSystemPrompt(context);
+      let history = await this.historyProvider.getHistory();
+      const systemPromptTokens = this.tokenizer.countTokens(systemPrompt);
+      history = await this.compressHistoryIfNeeded(history, systemPromptTokens);
+      const historyTokens = countMessagesTokens(history, this.tokenizer);
+      const formattingOverhead = Math.ceil((systemPromptTokens + historyTokens) * 0.05);
+      const totalTokens = systemPromptTokens + historyTokens + formattingOverhead;
+      logger.debug(
+        `Token breakdown - System: ${systemPromptTokens}, History: ${historyTokens}, Overhead: ${formattingOverhead}, Total: ${totalTokens}`
+      );
+      return totalTokens;
+    } catch (error) {
+      logger.error("Error calculating total token count:", error);
+      return this.getTokenCount();
+    }
+  }
+  /**
+   * Returns the configured maximum number of input tokens for the conversation.
+   */
+  getMaxInputTokens() {
+    return this.maxInputTokens;
+  }
+  /**
+   * 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, newTokenizer, newFormatter) {
+    const oldMaxInputTokens = this.maxInputTokens;
+    this.maxInputTokens = newMaxInputTokens;
+    if (newTokenizer) {
+      this.tokenizer = newTokenizer;
+    }
+    if (newFormatter) {
+      this.formatter = newFormatter;
+    }
+    logger.debug(
+      `ContextManager config updated: maxInputTokens ${oldMaxInputTokens} -> ${newMaxInputTokens}`
+    );
+  }
+  /**
+   * 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) {
+    this.lastActualTokenCount = actualTokens;
+    logger.debug(`Updated actual token count to: ${actualTokens}`);
+  }
+  /**
+   * 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) {
+    const estimatedTotal = this.lastActualTokenCount + newInputTokens;
+    const compressionTrigger = this.maxInputTokens * this.compressionThreshold;
+    logger.debug(
+      `Compression check: actual=${this.lastActualTokenCount}, newInput=${newInputTokens}, total=${estimatedTotal}, trigger=${compressionTrigger}`
+    );
+    return estimatedTotal > compressionTrigger;
+  }
+  /**
+   * Assembles and returns the current system prompt by invoking the PromptManager.
+   */
+  async getSystemPrompt(context) {
+    const prompt = await this.promptManager.build(context);
+    logger.debug(`[SystemPrompt] Built system prompt:
+${prompt}`);
+    return prompt;
+  }
+  /**
+   * 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
+   */
+  async getHistory() {
+    const history = await this.historyProvider.getHistory();
+    return [...history];
+  }
+  /**
+   * 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
+   */
+  async addMessage(message) {
+    switch (message.role) {
+      case "user":
+        if (
+          // Allow array content for user messages
+          !(Array.isArray(message.content) && message.content.length > 0) && (typeof message.content !== "string" || message.content.trim() === "")
+        ) {
+          throw ContextError.userMessageContentInvalid();
+        }
+        break;
+      case "assistant":
+        if (message.content === null && (!message.toolCalls || message.toolCalls.length === 0)) {
+          throw ContextError.assistantMessageContentOrToolsRequired();
+        }
+        if (message.toolCalls) {
+          if (!Array.isArray(message.toolCalls) || message.toolCalls.some(
+            (tc) => !tc.id || !tc.function?.name || !tc.function?.arguments
+          )) {
+            throw ContextError.assistantMessageToolCallsInvalid();
+          }
+        }
+        message.provider = this.llmConfig.provider;
+        message.router = this.llmConfig.router;
+        message.model = this.llmConfig.model;
+        break;
+      case "tool":
+        if (!message.toolCallId || !message.name || message.content === null) {
+          throw ContextError.toolMessageFieldsMissing();
+        }
+        break;
+      case "system":
+        logger.warn(
+          "ContextManager: Adding system message directly to history. Use setSystemPrompt instead."
+        );
+        if (typeof message.content !== "string" || message.content.trim() === "") {
+          throw ContextError.systemMessageContentInvalid();
+        }
+        break;
+    }
+    logger.debug(
+      `ContextManager: Adding message to history provider: ${JSON.stringify(message, null, 2)}`
+    );
+    await this.historyProvider.saveMessage(message);
+    const history = await this.historyProvider.getHistory();
+    logger.debug(`ContextManager: History now contains ${history.length} messages`);
+  }
+  /**
+   * 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
+   */
+  async addUserMessage(textContent, imageData, fileData) {
+    if (typeof textContent !== "string" || textContent.trim() === "" && !imageData && !fileData) {
+      throw ContextError.userMessageContentEmpty();
+    }
+    const finalTextContent = textContent.trim() || (imageData || fileData ? "" : textContent);
+    const messageParts = [];
+    if (finalTextContent) {
+      messageParts.push({ type: "text", text: finalTextContent });
+    }
+    if (imageData) {
+      messageParts.push({
+        type: "image",
+        image: imageData.image,
+        mimeType: imageData.mimeType || "image/jpeg"
+      });
+    }
+    if (fileData) {
+      messageParts.push({
+        type: "file",
+        data: fileData.data,
+        mimeType: fileData.mimeType,
+        ...fileData.filename && { filename: fileData.filename }
+      });
+    }
+    if (messageParts.length === 0) {
+      messageParts.push({ type: "text", text: finalTextContent });
+    }
+    logger.debug(
+      `ContextManager: Adding user message: ${JSON.stringify(messageParts, null, 2)}`
+    );
+    await this.addMessage({ role: "user", content: messageParts });
+  }
+  /**
+   * 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
+   */
+  async addAssistantMessage(content, toolCalls, metadata) {
+    if (content === null && (!toolCalls || toolCalls.length === 0)) {
+      throw ContextError.assistantMessageContentOrToolsRequired();
+    }
+    await this.addMessage({
+      role: "assistant",
+      content,
+      ...toolCalls && toolCalls.length > 0 && { toolCalls },
+      ...metadata?.tokenUsage && { tokenUsage: metadata.tokenUsage },
+      ...metadata?.reasoning && { reasoning: metadata.reasoning }
+    });
+  }
+  /**
+   * 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
+   */
+  async addToolResult(toolCallId, name, result) {
+    if (!toolCallId || !name) {
+      throw ContextError.toolCallIdNameRequired();
+    }
+    let content;
+    content = sanitizeToolResultToContent(result);
+    if (typeof content === "string") {
+      const preview = content.slice(0, 200);
+      logger.debug(
+        `ContextManager: Storing tool result (text) for ${name} (len=${content.length}): ${preview}${content.length > 200 ? "..." : ""}`
+      );
+    } else if (Array.isArray(content)) {
+      const summary = content.map(
+        (p) => p.type === "text" ? `text(${p.text.length})` : p.type === "image" ? `image(${p.mimeType || "image"})` : `file(${p.mimeType || "file"})`
+      ).join(", ");
+      logger.debug(`ContextManager: Storing tool result (parts) for ${name}: [${summary}]`);
+    }
+    await this.addMessage({ role: "tool", content, toolCallId, name });
+  }
+  /**
+   * Sets the system prompt for the conversation
+   *
+   * @param prompt The system prompt text
+   */
+  setSystemPrompt(_prompt) {
+  }
+  /**
+   * 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
+   */
+  async getFormattedMessages(contributorContext, llmContext, systemPrompt, history) {
+    const messageHistory = history ?? await this.historyProvider.getHistory();
+    const prompt = systemPrompt ?? await this.getSystemPrompt(contributorContext);
+    return this.formatter.format([...messageHistory], llmContext, prompt);
+  }
+  /**
+   * 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
+   */
+  async getFormattedMessagesWithCompression(contributorContext, llmContext) {
+    const systemPrompt = await this.getSystemPrompt(contributorContext);
+    const systemPromptTokens = this.tokenizer.countTokens(systemPrompt);
+    let history = await this.historyProvider.getHistory();
+    history = await this.compressHistoryIfNeeded(history, systemPromptTokens);
+    const formattedMessages = await this.getFormattedMessages(
+      contributorContext,
+      llmContext,
+      systemPrompt,
+      history
+    );
+    const historyTokens = countMessagesTokens(history, this.tokenizer);
+    const formattingOverhead = Math.ceil((systemPromptTokens + historyTokens) * 0.05);
+    const tokensUsed = systemPromptTokens + historyTokens + formattingOverhead;
+    logger.debug(
+      `Final token breakdown - System: ${systemPromptTokens}, History: ${historyTokens}, Overhead: ${formattingOverhead}, Total: ${tokensUsed}`
+    );
+    return {
+      formattedMessages,
+      systemPrompt,
+      tokensUsed
+    };
+  }
+  /**
+   * 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
+   */
+  async getFormattedSystemPrompt(context) {
+    const systemPrompt = await this.getSystemPrompt(context);
+    return this.formatter.formatSystemPrompt?.(systemPrompt);
+  }
+  /**
+   * Resets the conversation history
+   * Does not reset the system prompt
+   */
+  async resetConversation() {
+    await this.historyProvider.clearHistory();
+    logger.debug(`ContextManager: Conversation history cleared for session ${this.sessionId}`);
+  }
+  /**
+   * 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
+   */
+  async compressHistoryIfNeeded(history, systemPromptTokens) {
+    let currentTotalTokens = countMessagesTokens(history, this.tokenizer);
+    currentTotalTokens += systemPromptTokens;
+    logger.debug(`ContextManager: Checking if history compression is needed.`);
+    logger.debug(
+      `History tokens: ${countMessagesTokens(history, this.tokenizer)}, System prompt tokens: ${systemPromptTokens}, Total: ${currentTotalTokens}`
+    );
+    if (currentTotalTokens <= this.maxInputTokens) {
+      logger.debug(
+        `ContextManager: History compression not needed. Total token count: ${currentTotalTokens}, Max tokens: ${this.maxInputTokens}`
+      );
+      return history;
+    }
+    logger.info(
+      `ContextManager: History exceeds token limit (${currentTotalTokens} > ${this.maxInputTokens}). Applying compression strategies sequentially.`
+    );
+    const initialLength = history.length;
+    let workingHistory = [...history];
+    const targetHistoryTokens = this.maxInputTokens - systemPromptTokens;
+    for (const strategy of this.compressionStrategies) {
+      const strategyName = strategy.constructor.name;
+      logger.debug(`ContextManager: Applying ${strategyName}...`);
+      try {
+        workingHistory = strategy.compress(
+          [...workingHistory],
+          this.tokenizer,
+          targetHistoryTokens
+          // Use target tokens that account for system prompt
+        );
+      } catch (error) {
+        logger.error(`ContextManager: Error applying ${strategyName}:`, error);
+        break;
+      }
+      const historyTokens = countMessagesTokens(workingHistory, this.tokenizer);
+      currentTotalTokens = historyTokens + systemPromptTokens;
+      const messagesRemoved = initialLength - workingHistory.length;
+      if (currentTotalTokens <= this.maxInputTokens) {
+        logger.debug(
+          `ContextManager: Compression successful after ${strategyName}. New total count: ${currentTotalTokens}, messages removed: ${messagesRemoved}`
+        );
+        break;
+      }
+    }
+    return workingHistory;
+  }
+  /**
+   * 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
+   */
+  async processLLMStreamResponse(response) {
+    if (this.formatter.parseStreamResponse) {
+      const msgs = await this.formatter.parseStreamResponse(response) ?? [];
+      for (const msg of msgs) {
+        try {
+          await this.addMessage(msg);
+        } catch (error) {
+          logger.error(
+            `ContextManager: Failed to process LLM stream response message for session ${this.sessionId}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+    } else {
+      await this.processLLMResponse(response);
+    }
+  }
+  /**
+   * Parses a raw LLM response, converts it into internal messages and adds them to the history.
+   *
+   * @param response The response from the LLM provider
+   */
+  async processLLMResponse(response) {
+    const msgs = this.formatter.parseResponse(response) ?? [];
+    for (const msg of msgs) {
+      try {
+        await this.addMessage(msg);
+      } catch (error) {
+        logger.error(
+          `ContextManager: Failed to process LLM response message for session ${this.sessionId}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+  }
+}
+export {
+  ContextManager
+};

package/dist/context/types.cjs

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/context/types.d.cts

@@ -0,0 +1,113 @@
+import { LLMProvider, LLMRouter } from '../llm/types.cjs';
+
+/**
+ * Internal representation of a message in a conversation.
+ * Standardizes message format across different LLM providers.
+ */
+interface ImageData {
+    image: string | Uint8Array | Buffer | ArrayBuffer | URL;
+    mimeType?: string;
+}
+interface FileData {
+    data: string | Uint8Array | Buffer | ArrayBuffer | URL;
+    mimeType: string;
+    filename?: string;
+}
+interface TextPart {
+    type: 'text';
+    text: string;
+}
+interface ImagePart extends ImageData {
+    type: 'image';
+}
+interface FilePart extends FileData {
+    type: 'file';
+}
+interface InternalMessage {
+    /**
+     * The role of the entity sending the message.
+     * - 'system': System instructions or context
+     * - 'user': End-user input
+     * - 'assistant': LLM response
+     * - 'tool': Result from a tool execution
+     */
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /**
+     * Timestamp when the message was created (Unix timestamp in milliseconds).
+     * TODO: Populate this field when messages are created. Currently not implemented.
+     * @see https://github.com/truffle-ai/dexto/issues/XXX
+     */
+    timestamp?: number;
+    /**
+     * The content of the message.
+     * - String for system, assistant (text only), and tool messages.
+     * - Array of parts for user messages (can include text, images, and files).
+     * - null if an assistant message only contains tool calls.
+     */
+    content: string | null | Array<TextPart | ImagePart | FilePart>;
+    /**
+     * Optional model reasoning text associated with an assistant response.
+     * Present when the provider supports reasoning and returns a final reasoning trace.
+     */
+    reasoning?: string;
+    /**
+     * Optional token usage accounting for this assistant response.
+     */
+    tokenUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        reasoningTokens?: number;
+        totalTokens?: number;
+    };
+    /**
+     * Optional model identifier for assistant messages.
+     * Indicates which LLM model generated this response.
+     */
+    model?: string;
+    /** Optional provider identifier for assistant messages. */
+    provider?: LLMProvider;
+    /**
+     * Optional router metadata for assistant messages.
+     * Indicates which router was used to route the request.
+     */
+    router?: LLMRouter;
+    /**
+     * Tool calls made by the assistant.
+     * Only present in assistant messages when the LLM requests tool execution.
+     */
+    toolCalls?: Array<{
+        /**
+         * Unique identifier for this tool call
+         */
+        id: string;
+        /**
+         * The type of tool call (currently only 'function' is supported)
+         */
+        type: 'function';
+        /**
+         * Function call details
+         */
+        function: {
+            /**
+             * Name of the function to call
+             */
+            name: string;
+            /**
+             * Arguments for the function in JSON string format
+             */
+            arguments: string;
+        };
+    }>;
+    /**
+     * ID of the tool call this message is responding to.
+     * Only present in tool messages.
+     */
+    toolCallId?: string;
+    /**
+     * Name of the tool that produced this result.
+     * Only present in tool messages.
+     */
+    name?: string;
+}
+
+export type { FileData, FilePart, ImageData, ImagePart, InternalMessage, TextPart };