@dexto/core 1.1.10 → 1.2.0

package/dist/context/manager.d.cts

@@ -1,254 +0,0 @@
-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/types.d.cts

@@ -1,113 +0,0 @@
-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 };

package/dist/context/utils.d.cts

@@ -1,79 +0,0 @@
-import { InternalMessage } from './types.cjs';
-import { ITokenizer } from '../llm/tokenizer/types.cjs';
-import { LLMContext } from '../llm/types.cjs';
-
-/**
- * Counts the total tokens in an array of InternalMessages using a provided tokenizer.
- * Includes an estimated overhead per message.
- *
- * NOTE: This function counts tokens on the raw InternalMessage history and has limitations:
- * 1. It does not account for provider-specific formatting (uses raw content).
- * 2. It ignores the token cost of images and files in multimodal messages (counts text only).
- * 3. The overhead is a fixed approximation.
- * For more accurate counting reflecting the final provider payload, use ContextManager.countTotalTokens().
- *
- * @param history The array of messages to count.
- * @param tokenizer The tokenizer instance to use for counting.
- * @param overheadPerMessage Optional overhead tokens per message. Defaults to 4.
- * @returns The total token count.
- * @throws Error if token counting fails within the tokenizer.
- */
-declare function countMessagesTokens(history: InternalMessage[], tokenizer: ITokenizer, overheadPerMessage?: number): number;
-/**
- * Extracts image data (base64 or URL) from an ImagePart or raw buffer.
- * @param imagePart The image part containing image data
- * @returns Base64-encoded string or URL string
- */
-declare function getImageData(imagePart: {
-    image: string | Uint8Array | Buffer | ArrayBuffer | URL;
-}): string;
-/**
- * Extracts file data (base64 or URL) from a FilePart or raw buffer.
- * @param filePart The file part containing file data
- * @returns Base64-encoded string or URL string
- */
-declare function getFileData(filePart: {
-    data: string | Uint8Array | Buffer | ArrayBuffer | URL;
-}): string;
-/**
- * Filters message content based on LLM capabilities.
- * Removes unsupported file attachments while preserving supported content.
- * Uses model-specific validation when available, falls back to provider-level.
- * @param messages Array of internal messages to filter
- * @param config The LLM configuration (provider and optional model)
- * @returns Filtered messages with unsupported content removed
- */
-declare function filterMessagesByLLMCapabilities(messages: InternalMessage[], config: LLMContext): InternalMessage[];
-/**
- * Detect if a string is likely a Base64 blob (not a typical sentence/text).
- * Uses a length threshold and character set heuristic.
- */
-declare function isLikelyBase64String(value: string, minLength?: number): boolean;
-/**
- * Parse data URI and return { mediaType, base64 } or null if not a data URI.
- */
-declare function parseDataUri(value: string): {
-    mediaType: string;
-    base64: string;
-} | null;
-/**
- * Convert an arbitrary tool result into safe InternalMessage content.
- * - Converts data URIs and base64 blobs to media/file parts
- * - Removes huge binary blobs inside objects
- * - Truncates extremely long raw text
- */
-declare function sanitizeToolResultToContent(result: unknown): InternalMessage['content'];
-/**
- * Produce a short textual summary for tool content, to be used with providers
- * that only accept text for tool messages (e.g., OpenAI/Anthropic tool role).
- */
-declare function summarizeToolContentForText(content: InternalMessage['content']): string;
-/**
- * Convert arbitrary tool content to safe text for providers that only accept textual tool messages.
- * - If content is an array of parts, summarize it.
- * - If content is a string that looks like base64/data URI, replace with a short placeholder.
- * - Otherwise pass text through.
- */
-declare function toTextForToolMessage(content: InternalMessage['content']): string;
-
-export { countMessagesTokens, filterMessagesByLLMCapabilities, getFileData, getImageData, isLikelyBase64String, parseDataUri, sanitizeToolResultToContent, summarizeToolContentForText, toTextForToolMessage };

package/dist/errors/DextoBaseError.d.cts

@@ -1,15 +0,0 @@
-/**
- * Abstract base class for all Dexto errors
- * Provides common functionality like trace ID generation and JSON serialization
- */
-declare abstract class DextoBaseError extends Error {
-    readonly traceId: string;
-    constructor(message: string, traceId?: string);
-    /**
-     * Convert error to JSON representation
-     * Must be implemented by subclasses
-     */
-    abstract toJSON(): Record<string, any>;
-}
-
-export { DextoBaseError };

package/dist/errors/DextoRuntimeError.d.cts

@@ -1,37 +0,0 @@
-import { DextoBaseError } from './DextoBaseError.cjs';
-import { DextoErrorCode, ErrorScope, ErrorType } from './types.cjs';
-import '../agent/error-codes.cjs';
-import '../config/error-codes.cjs';
-import '../context/error-codes.cjs';
-import '../llm/error-codes.cjs';
-import '../mcp/error-codes.cjs';
-import '../session/error-codes.cjs';
-import '../storage/error-codes.cjs';
-import '../systemPrompt/error-codes.cjs';
-import '../tools/error-codes.cjs';
-import '../preferences/error-codes.cjs';
-import '../agent/registry/error-codes.cjs';
-
-/**
- * Runtime error class for single-issue errors
- * Provides structured error information with scope, type, and recovery guidance
- */
-declare class DextoRuntimeError<C = unknown> extends DextoBaseError {
-    readonly code: DextoErrorCode;
-    readonly scope: ErrorScope;
-    readonly type: ErrorType;
-    readonly context?: C | undefined;
-    readonly recovery?: string | string[] | undefined;
-    constructor(code: DextoErrorCode, scope: ErrorScope, type: ErrorType, message: string, context?: C | undefined, recovery?: string | string[] | undefined, traceId?: string);
-    toJSON(): {
-        code: DextoErrorCode;
-        message: string;
-        scope: ErrorScope;
-        type: ErrorType;
-        context: C | undefined;
-        recovery: string | string[] | undefined;
-        traceId: string;
-    };
-}
-
-export { DextoRuntimeError };

package/dist/errors/DextoValidationError.d.cts

@@ -1,65 +0,0 @@
-import { DextoBaseError } from './DextoBaseError.cjs';
-import { Issue } from './types.cjs';
-import '../agent/error-codes.cjs';
-import '../config/error-codes.cjs';
-import '../context/error-codes.cjs';
-import '../llm/error-codes.cjs';
-import '../mcp/error-codes.cjs';
-import '../session/error-codes.cjs';
-import '../storage/error-codes.cjs';
-import '../systemPrompt/error-codes.cjs';
-import '../tools/error-codes.cjs';
-import '../preferences/error-codes.cjs';
-import '../agent/registry/error-codes.cjs';
-
-/**
- * Validation error class for handling multiple validation issues
- * Similar to ZodError, provides first-class access to all validation issues
- */
-declare class DextoValidationError extends DextoBaseError {
-    readonly issues: Issue[];
-    constructor(issues: Issue[]);
-    /**
-     * Format multiple issues into a readable error message
-     */
-    private static formatMessage;
-    /**
-     * Get only error-severity issues
-     */
-    get errors(): Issue[];
-    /**
-     * Get only warning-severity issues
-     */
-    get warnings(): Issue[];
-    /**
-     * Check if there are any error-severity issues
-     */
-    hasErrors(): boolean;
-    /**
-     * Check if there are any warning-severity issues
-     */
-    hasWarnings(): boolean;
-    /**
-     * Get the first error-severity issue (if any)
-     * Useful for getting the primary error when multiple exist
-     */
-    get firstError(): Issue | undefined;
-    /**
-     * Get the first warning-severity issue (if any)
-     */
-    get firstWarning(): Issue | undefined;
-    /**
-     * Format issues for display
-     * Returns an object with categorized issues for easy logging
-     */
-    format(): {
-        errors: string[];
-        warnings: string[];
-    };
-    /**
-     * Convert to JSON representation
-     */
-    toJSON(): Record<string, any>;
-}
-
-export { DextoValidationError };

package/dist/errors/index.d.cts

@@ -1,18 +0,0 @@
-export { DextoBaseError } from './DextoBaseError.cjs';
-export { DextoRuntimeError } from './DextoRuntimeError.cjs';
-export { DextoValidationError } from './DextoValidationError.cjs';
-export { DextoErrorCode, ErrorScope, ErrorType, Issue, Severity } from './types.cjs';
-export { ensureOk } from './result-bridge.cjs';
-import '../agent/error-codes.cjs';
-import '../config/error-codes.cjs';
-import '../context/error-codes.cjs';
-import '../llm/error-codes.cjs';
-import '../mcp/error-codes.cjs';
-import '../session/error-codes.cjs';
-import '../storage/error-codes.cjs';
-import '../systemPrompt/error-codes.cjs';
-import '../tools/error-codes.cjs';
-import '../preferences/error-codes.cjs';
-import '../agent/registry/error-codes.cjs';
-import '../utils/result.cjs';
-import 'zod';

package/dist/errors/result-bridge.d.cts

@@ -1,39 +0,0 @@
-import { Result } from '../utils/result.cjs';
-import 'zod';
-import './types.cjs';
-import '../agent/error-codes.cjs';
-import '../config/error-codes.cjs';
-import '../context/error-codes.cjs';
-import '../llm/error-codes.cjs';
-import '../mcp/error-codes.cjs';
-import '../session/error-codes.cjs';
-import '../storage/error-codes.cjs';
-import '../systemPrompt/error-codes.cjs';
-import '../tools/error-codes.cjs';
-import '../preferences/error-codes.cjs';
-import '../agent/registry/error-codes.cjs';
-
-/**
- * Bridge function to convert Result pattern to validation exceptions
- * Used at public API boundaries for validation flows
- *
- * Note: Runtime errors are thrown directly, not through Result pattern
- *
- * @param result - The Result to check (typically from validation functions)
- * @returns The data if successful
- * @throws DextoValidationError if the result contains validation issues
- *
- * @example
- * ```typescript
- * // Validation flow
- * const result = validateInputForLLM(input, config);
- * const data = ensureOk(result); // Throws DextoValidationError if validation failed
- *
- * // LLM config validation
- * const configResult = resolveAndValidateLLMConfig(current, updates);
- * const validatedConfig = ensureOk(configResult);
- * ```
- */
-declare function ensureOk<T, C>(result: Result<T, C>): T;
-
-export { ensureOk };