toolpack-sdk 1.4.0 → 2.0.0-alpha.1

package/dist/index.d.ts

@@ -221,6 +221,16 @@ interface ToolCallRequest {
     type: 'function';
     function: ToolCallFunction;
 }
+interface RequestToolDefinition {
+    name: string;
+    displayName: string;
+    description: string;
+    parameters: Record<string, any>;
+    category: string;
+    execute: (args: Record<string, any>) => Promise<any>;
+    cacheable?: boolean;
+    confirmation?: ToolConfirmation;
+}
 interface ToolCallResult {
     id: string;
     name: string;
@@ -237,6 +247,7 @@ interface CompletionRequest {
     response_format?: 'text' | 'json_object';
     stream?: boolean;
     tools?: ToolCallRequest[];
+    requestTools?: RequestToolDefinition[];
     tool_choice?: 'auto' | 'none' | 'required';
     /** AbortSignal to cancel the request */
     signal?: AbortSignal;
@@ -391,6 +402,59 @@ interface ProviderInfo {
     /** Available models from this provider */
     models: ProviderModelInfo[];
 }
+/**
+ * Strategy for handling context window limit scenarios
+ */
+type ContextWindowStrategy = 'prune' | 'summarize' | 'fail';
+/**
+ * Configuration for automatic context window management
+ */
+interface ContextWindowConfig {
+    /** Master switch for context window management. Default: true */
+    enabled?: boolean;
+    /** Strategy when context limit is approached or exceeded. Default: 'prune' */
+    strategy?: ContextWindowStrategy;
+    /**
+     * Percentage of context window to trigger pruning/summarization.
+     * When current tokens exceed this percentage, cleanup is initiated.
+     * Default: 85
+     */
+    pruneThreshold?: number;
+    /**
+     * Optional maximum message history length as fallback limit.
+     * Useful for caps independent of token counting.
+     * When set, removes messages when count exceeds this.
+     */
+    maxMessageHistoryLength?: number;
+    /**
+     * Model to use for conversation summarization (if strategy is 'summarize').
+     * If omitted, uses the same model as the current request.
+     * Example: 'gpt-4.1-mini' for faster/cheaper summaries
+     */
+    summarizerModel?: string;
+    /**
+     * Whether to always retain system messages (never prune them).
+     * Default: true
+     */
+    retainSystemMessages?: boolean;
+    /**
+     * Percentage buffer above actual maxOutputTokens to reserve for safety.
+     * Default: 1.15 (15% buffer)
+     */
+    outputTokenBuffer?: number;
+}
+/**
+ * Tracks context window state per conversation for monitoring
+ */
+interface ContextWindowState {
+    conversationId?: string;
+    estimatedTokens: number;
+    lastUpdated: number;
+    pruneCount: number;
+    lastPrunedAt?: number;
+    warningsSent: number;
+    summarizationCount: number;
+}
 
 declare class SDKError extends Error {
     code: string;
@@ -422,6 +486,109 @@ declare class TimeoutError extends SDKError {
     phase?: string | undefined;
     constructor(message: string, phase?: string | undefined, cause?: any);
 }
+/**
+ * Thrown when a conversation exceeds the configured context window limit
+ * and cannot be recovered through pruning or summarization
+ */
+declare class ContextWindowExceededError extends SDKError {
+    conversationId: string;
+    currentTokens: number;
+    contextWindowLimit: number;
+    strategy: 'prune' | 'summarize' | 'fail';
+    constructor(message: string, conversationId: string, currentTokens: number, contextWindowLimit: number, strategy: 'prune' | 'summarize' | 'fail', cause?: any);
+    /**
+     * Get the number of tokens over the limit
+     */
+    getOverageTokens(): number;
+    /**
+     * Get the percentage of the context window being used
+     */
+    getUsagePercentage(): number;
+    /**
+     * Get a detailed error report
+     */
+    getDetailedReport(): string;
+}
+/**
+ * Thrown when there is insufficient context remaining to process a request
+ * after pruning or summarization, even though tokens are within limits
+ */
+declare class InsufficientContextError extends SDKError {
+    conversationId: string;
+    requiredTokens: number;
+    availableTokens: number;
+    minimumRequiredTokens: number;
+    constructor(message: string, conversationId: string, requiredTokens: number, availableTokens: number, minimumRequiredTokens: number, cause?: any);
+    /**
+     * Get the token deficit
+     */
+    getDeficit(): number;
+    /**
+     * Whether the deficit could be recovered by adjusting the strategy
+     */
+    isRecoverable(): boolean;
+    /**
+     * Get a detailed error report
+     */
+    getDetailedReport(): string;
+}
+/**
+ * Thrown when summarization fails or produces inadequate results
+ */
+declare class SummarizationError extends SDKError {
+    conversationId: string;
+    messageCount: number;
+    failureReason: 'provider_error' | 'invalid_response' | 'insufficient_tokens' | 'invalid_quality' | 'unknown';
+    summaryAttempt?: string | undefined;
+    constructor(message: string, conversationId: string, messageCount: number, failureReason: 'provider_error' | 'invalid_response' | 'insufficient_tokens' | 'invalid_quality' | 'unknown', summaryAttempt?: string | undefined, cause?: any);
+    /**
+     * Whether the error is retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Get suggested recovery action
+     */
+    getSuggestedRecovery(): string;
+    /**
+     * Get a detailed error report
+     */
+    getDetailedReport(): string;
+}
+/**
+ * Thrown when context window configuration is invalid
+ */
+declare class ContextWindowConfigError extends SDKError {
+    configField: string;
+    providedValue: any;
+    constraint: string;
+    constructor(message: string, configField: string, providedValue: any, constraint: string, cause?: any);
+    /**
+     * Get a detailed error report
+     */
+    getDetailedReport(): string;
+}
+/**
+ * Thrown when a state operation is performed on a non-existent conversation
+ */
+declare class ConversationNotFoundError extends SDKError {
+    conversationId: string;
+    constructor(message: string, conversationId: string, cause?: any);
+}
+/**
+ * Utility function to check if an error is context window related
+ */
+declare function isContextWindowError(error: any): error is SDKError & {
+    code: string;
+};
+/**
+ * Utility function to handle context window errors
+ */
+declare function handleContextWindowError(error: SDKError, _conversationId?: string): {
+    shouldRetry: boolean;
+    shouldFallback: boolean;
+    action: 'prune' | 'summarize' | 'fail' | 'none';
+    message: string;
+};
 
 declare abstract class ProviderAdapter {
     /**
@@ -473,6 +640,13 @@ declare abstract class ProviderAdapter {
      * @throws InvalidRequestError if not supported by this provider.
      */
     deleteFile(_fileId: string): Promise<void>;
+    /**
+     * Estimates the number of tokens for the given messages and model.
+     * @param _messages The messages to count.
+     * @param _model The model to count for.
+     * @returns The number of tokens or null if not supported.
+     */
+    countTokens(_messages: Message[], _model: string): Promise<number | null>;
 }
 
 /**
@@ -720,11 +894,48 @@ interface WorkflowEvents {
     'workflow:step_added': (step: PlanStep, plan: Plan) => void;
     /** Emitted for progress updates */
     'workflow:progress': (progress: WorkflowProgress) => void;
+    /** Emitted when context window usage is high (approaching limit) */
+    'workflow:context_warning': (event: ContextWindowWarningEvent) => void;
+    /** Emitted when context window would be exceeded */
+    'workflow:context_exceeded': (event: ContextWindowExceededEvent) => void;
+    /** Emitted when messages are pruned to recover context */
+    'workflow:context_pruned': (event: ContextPrunedEvent) => void;
+    /** Emitted when conversation is summarized for context recovery */
+    'workflow:conversation_summarized': (event: ConversationSummarizedEvent) => void;
     /** Emitted when workflow completes */
     'workflow:completed': (plan: Plan, result: WorkflowResult) => void;
     /** Emitted when workflow fails */
     'workflow:failed': (plan: Plan, error: Error) => void;
 }
+interface ContextWindowWarningEvent {
+    currentTokens: number;
+    contextWindow: number;
+    percentage: number;
+    model: string;
+    conversationId?: string;
+}
+interface ContextWindowExceededEvent {
+    currentTokens: number;
+    contextWindow: number;
+    maxOutputTokens: number;
+    model: string;
+    strategy: 'prune' | 'summarize' | 'fail';
+    conversationId?: string;
+}
+interface ContextPrunedEvent {
+    removed: number;
+    tokensReclaimed: number;
+    newTotal: number;
+    conversationId?: string;
+    beforeCount: number;
+    afterCount: number;
+}
+interface ConversationSummarizedEvent {
+    summarized: number;
+    summaryTokens: number;
+    tokensSaved: number;
+    conversationId?: string;
+}
 interface WorkflowProgress {
     planId: string;
     currentStep: number;
@@ -879,6 +1090,8 @@ interface ToolpackConfig {
     };
     /** Human-in-the-loop configuration for tool confirmation */
     hitl?: HitlConfig;
+    /** Context window management configuration for automatic conversation pruning/summarization */
+    contextWindow?: ContextWindowConfig;
 }
 declare function getToolpackConfig(configPath?: string): ToolpackConfig;
 declare function reloadToolpackConfig(): void;
@@ -964,6 +1177,8 @@ interface AIClientConfig {
     onToolConfirm?: OnToolConfirmCallback;
     /** Optional conversation ID for tracking context */
     conversationId?: string;
+    /** Context window management configuration */
+    contextWindowConfig?: ContextWindowConfig;
 }
 declare class AIClient extends EventEmitter {
     private providers;
@@ -982,7 +1197,17 @@ declare class AIClient extends EventEmitter {
     private onToolConfirm?;
     private currentRound;
     private conversationId?;
+    private contextWindowConfig?;
+    private contextWindowStateManager?;
+    private providerModelCache;
     constructor(config: AIClientConfig);
+    private getConversationId;
+    private getModelInfo;
+    private countRequestTokens;
+    private pruneConversation;
+    private pruneToMaxMessageHistory;
+    private summarizeConversation;
+    private enforceContextWindow;
     /**
      * Check if a tool should bypass confirmation based on HITL config.
      * Returns true if the tool should execute without confirmation.
@@ -1072,6 +1297,13 @@ declare class AIClient extends EventEmitter {
      * Applies mode-based tool filtering when an active mode is set.
      */
     private enrichRequestWithTools;
+    private buildRequestToolMap;
+    private requestToolToSchema;
+    private mergeSchemas;
+    private schemasToToolCallRequests;
+    private mergeToolCallRequests;
+    private injectRequestToolGuidance;
+    private stripRequestTools;
     /**
      * Filter tool schemas based on mode permissions.
      * blockedTools/blockedToolCategories always take precedence.
@@ -1351,6 +1583,24 @@ declare class OpenAIAdapter extends ProviderAdapter {
     private handleError;
 }
 
+interface OpenRouterOptions {
+    siteUrl?: string;
+    siteName?: string;
+}
+declare class OpenRouterAdapter extends OpenAIAdapter {
+    name: string;
+    private readonly _apiKey;
+    constructor(apiKey: string, options?: OpenRouterOptions);
+    getDisplayName(): string;
+    supportsFileUpload(): boolean;
+    generate(request: CompletionRequest): Promise<CompletionResponse>;
+    stream(request: CompletionRequest): AsyncGenerator<CompletionChunk>;
+    private normalizeRequest;
+    getModels(): Promise<ProviderModelInfo[]>;
+    private mapModel;
+    private deriveCostTier;
+}
+
 declare function getMimeType(filePath: string): string;
 declare function isDataUri(url: string): boolean;
 declare function parseDataUri(dataUri: string): {
@@ -1833,6 +2083,24 @@ declare const httpDownloadTool: ToolDefinition;
 
 declare const httpToolsProject: ToolProject;
 
+declare const githubGraphqlExecuteTool: ToolDefinition;
+
+declare const githubContentsGetTextTool: ToolDefinition;
+
+declare const githubPrReviewThreadsListTool: ToolDefinition;
+
+declare const githubPrReviewThreadsResolveTool: ToolDefinition;
+
+declare const githubPrReviewCommentsReplyTool: ToolDefinition;
+
+declare const githubPrDiffGetTool: ToolDefinition;
+
+declare const githubPrFilesListTool: ToolDefinition;
+
+declare const githubPrReviewsSubmitTool: ToolDefinition;
+
+declare const githubToolsProject: ToolProject;
+
 declare const webFetchTool: ToolDefinition;
 
 declare const webSearchTool: ToolDefinition;
@@ -2041,6 +2309,15 @@ declare const AGENT_MODE: ModeConfig;
  * Ideal for general Q&A, research, and online assistance.
  */
 declare const CHAT_MODE: ModeConfig;
+/**
+ * Built-in mode: Coding
+ *
+ * Optimized for software development tasks. Uses concise step outputs with
+ * minimal conversational text. Each step produces focused technical output,
+ * and only the final step provides a summary of execution. Ideal for coding,
+ refactoring, debugging, and file manipulation tasks where brevity matters.
+ */
+declare const CODING_MODE: ModeConfig;
 /**
  * All built-in modes.
  *
@@ -2246,6 +2523,10 @@ interface ProviderOptions {
     model?: string;
     /** Base URL override (for OpenAI-compatible endpoints or custom Ollama host) */
     baseUrl?: string;
+    /** OpenRouter only: your site URL for the leaderboard/attribution header */
+    siteUrl?: string;
+    /** OpenRouter only: your site name for the leaderboard/attribution header */
+    siteName?: string;
 }
 interface ToolpackInitConfig {
     /** Single provider shorthand (e.g. 'openai', 'anthropic', 'gemini') */
@@ -2259,6 +2540,8 @@ interface ToolpackInitConfig {
     model?: string;
     /** Load built-in tools (fs, http, etc.)? Default: false */
     tools?: boolean;
+    /** Context window management configuration for automatic conversation pruning/summarization */
+    contextWindow?: ContextWindowConfig;
     /** Custom tool projects to load in addition to built-ins */
     customTools?: ToolProject[];
     /** Multi-provider config (overrides single provider settings) */
@@ -2288,12 +2571,13 @@ interface ToolpackInitConfig {
     mcp?: McpToolsConfig;
     /**
      * Optional Knowledge instance for RAG (Retrieval-Augmented Generation).
-     * When provided, the knowledge base will be registered as a tool that the AI can use to search documentation.
+     * When provided, knowledge_search and knowledge_add tools are automatically available
+     * as request-scoped tools that the AI can use to retrieve and store information.
      * Can be null if initialization fails - will be gracefully skipped.
      *
      * Accepts any object with a `toTool()` method (e.g. `Knowledge` from `@toolpack-sdk/knowledge`).
      */
-    knowledge?: KnowledgeInstance | null;
+    knowledge?: KnowledgeInstance | KnowledgeInstance[] | null;
     /**
      * Human-in-the-loop configuration for tool confirmation.
      * Default: 'all' when onToolConfirm is provided, 'off' otherwise.
@@ -2340,6 +2624,7 @@ interface KnowledgeInstance {
             }>;
         }) => Promise<any>;
     };
+    add(content: string, metadata?: Record<string, unknown>): Promise<string>;
     query(text: string, options?: Record<string, unknown>): Promise<any[]>;
     stop(): Promise<void>;
 }
@@ -2348,9 +2633,12 @@ declare class Toolpack extends EventEmitter {
     private activeProviderName;
     private modeRegistry;
     private workflowExecutor;
+    private knowledgeLayers;
     customProviderNames: Set<string>;
     private mcpToolProject;
     private constructor();
+    private buildKnowledgeRequestTools;
+    private prepareRequest;
     /**
      * Initialize the Toolpack SDK.
      *
@@ -2433,6 +2721,183 @@ declare class Toolpack extends EventEmitter {
     private forwardWorkflowEvents;
 }
 
+/**
+ * A participant in a conversation — a human user, another agent, or the
+ * system itself. Stored alongside each `StoredMessage` so the prompt
+ * assembler can reconstruct who said what without extra lookups.
+ */
+interface Participant {
+    /** Coarse participant kind */
+    kind: 'system' | 'user' | 'agent';
+    /** Stable identifier for this participant (platform-specific id or agent name) */
+    id: string;
+    /** Human-readable display name, resolved lazily. Falls back to `id` if unset. */
+    displayName?: string;
+    /** For `kind: 'agent'` only: an optional role label for rendering */
+    agentType?: string;
+    /** Optional free-form metadata (e.g. platform-specific profile info) */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Coarse scope of a stored message.
+ *
+ * - `thread`  — a reply inside a specific thread (Slack thread, email thread)
+ * - `channel` — top-level message in a channel / group chat
+ * - `dm`      — direct / private message between two participants
+ */
+type ConversationScope = 'thread' | 'channel' | 'dm';
+/**
+ * A single stored message in conversation history.
+ *
+ * This is the canonical storage shape. It is deliberately richer than
+ * the LLM's role-based format — the prompt assembler projects it into
+ * whatever the provider expects at render time.
+ */
+interface StoredMessage {
+    /** Stable, unique message id. Used for dedup at capture time. */
+    id: string;
+    /**
+     * Conversation key. Identifies the thread / DM / channel this message
+     * belongs to.
+     */
+    conversationId: string;
+    /** Who sent this message. */
+    participant: Participant;
+    /** Plain-text content of the message. */
+    content: string;
+    /** ISO 8601 timestamp of when the message was received/sent. */
+    timestamp: string;
+    /** Coarse scope used by the assembler to filter by context type. */
+    scope: ConversationScope;
+    metadata?: {
+        /** Platform channel type, e.g. 'im' for Slack DMs, 'private' for Telegram DMs. */
+        channelType?: string;
+        /** Thread timestamp / id within a channel (e.g. Slack thread_ts). */
+        threadId?: string;
+        /** Platform-specific message id for dedup and linking. */
+        messageId?: string;
+        /** Participant ids explicitly @-mentioned in this message. */
+        mentions?: string[];
+        /** Whether this message is a rolling summary replacing older turns. */
+        isSummary?: boolean;
+        /** Human-readable channel or group name (e.g. '#general', 'Project Kore'). */
+        channelName?: string;
+        /** Platform-specific channel identifier (e.g. Slack 'C12345', Telegram chat id). */
+        channelId?: string;
+    };
+}
+/** Options for retrieving messages from the store. */
+interface GetOptions {
+    /** Filter to a specific scope within the conversation. */
+    scope?: ConversationScope;
+    /** Only return messages at or after this ISO timestamp. */
+    sinceTimestamp?: string;
+    /** Maximum number of messages to return (most recent N). */
+    limit?: number;
+    /**
+     * When set, only return messages whose `participant.id` is in this set.
+     * Used by the assembler's addressed-only mode.
+     */
+    participantIds?: string[];
+}
+/** Options for the conversation search tool. */
+interface ConversationSearchOptions {
+    /** Maximum number of results to return. Default: 10. */
+    limit?: number;
+    /**
+     * Rough token cap for total search results.
+     * The store truncates content to fit within this budget.
+     * Default: 2000.
+     */
+    tokenCap?: number;
+}
+/** Options for the prompt assembler (used by toolpack-agents). */
+interface AssemblerOptions {
+    scope?: ConversationScope;
+    addressedOnlyMode?: boolean;
+    tokenBudget?: number;
+    rollingSummaryThreshold?: number;
+    timeWindowMinutes?: number;
+    maxTurnsToLoad?: number;
+    agentAliases?: string[];
+}
+/** A single message entry in the assembled prompt, ready to send to the LLM. */
+interface PromptMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/** The output of the prompt assembler. */
+interface AssembledPrompt {
+    messages: PromptMessage[];
+    estimatedTokens: number;
+    turnsLoaded: number;
+    hasSummary: boolean;
+}
+/**
+ * Interface for conversation history storage.
+ *
+ * Implementations must be:
+ * - **Append-only safe**: `append()` must be idempotent on duplicate `id`.
+ * - **Ordered**: `get()` returns messages in ascending timestamp order.
+ * - **Scope-aware**: `get()` must respect `options.scope` when provided.
+ */
+interface ConversationStore {
+    append(message: StoredMessage): Promise<void>;
+    get(conversationId: string, options?: GetOptions): Promise<StoredMessage[]>;
+    search(conversationId: string, query: string, options?: ConversationSearchOptions): Promise<StoredMessage[]>;
+    deleteMessages(conversationId: string, ids: string[]): Promise<void>;
+}
+
+interface InMemoryConversationStoreConfig {
+    /** Maximum conversations to keep in memory. Default: 500. */
+    maxConversations?: number;
+    /** Maximum messages per conversation. Default: 500. */
+    maxMessagesPerConversation?: number;
+}
+/**
+ * In-memory implementation of `ConversationStore`.
+ *
+ * Good for single-process deployments, local development, and tests.
+ * Memory is bounded by `maxConversations × maxMessagesPerConversation`.
+ *
+ * **Not suitable for multi-process or serverless deployments** — each
+ * process has its own isolated store. For those environments, implement
+ * `ConversationStore` against a shared database.
+ */
+declare class InMemoryConversationStore implements ConversationStore {
+    private readonly lru;
+    private readonly maxMessagesPerConversation;
+    constructor(config?: InMemoryConversationStoreConfig);
+    append(message: StoredMessage): Promise<void>;
+    get(conversationId: string, options?: GetOptions): Promise<StoredMessage[]>;
+    search(conversationId: string, query: string, options?: ConversationSearchOptions): Promise<StoredMessage[]>;
+    deleteMessages(conversationId: string, ids: string[]): Promise<void>;
+    clearConversation(conversationId: string): void;
+    get conversationCount(): number;
+}
+
+interface SQLiteConversationStoreConfig {
+    dbPath?: string;
+    maxMessagesPerConversation?: number;
+    enableWAL?: boolean;
+    useFTS?: boolean;
+}
+declare class SQLiteConversationStore implements ConversationStore {
+    private readonly db;
+    private readonly maxMessagesPerConversation;
+    private readonly useFTS;
+    constructor(config?: SQLiteConversationStoreConfig);
+    private initSchema;
+    append(message: StoredMessage): Promise<void>;
+    get(conversationId: string, options?: GetOptions): Promise<StoredMessage[]>;
+    search(conversationId: string, query: string, options?: ConversationSearchOptions): Promise<StoredMessage[]>;
+    deleteMessages(conversationId: string, ids: string[]): Promise<void>;
+    clearConversation(conversationId: string): void;
+    private rowToMessage;
+    close(): void;
+}
+
 declare const TOOLPACK_DIR_NAME = ".toolpack";
 declare const CONFIG_DIR_NAME = "config";
 declare const CONFIG_FILE_NAME = "toolpack.config.json";
@@ -2494,6 +2959,254 @@ declare function getRuntimeConfigStatus(workspacePath?: string): RuntimeConfigSt
  */
 declare function initializeGlobalConfigIfFirstRun(workspacePath?: string): void;
 
+/**
+ * Token Counting Utilities
+ *
+ * Provider-specific token counting for accurate context window management.
+ * Supports OpenAI (js-tiktoken), Anthropic, Gemini, and Ollama with fallback estimation.
+ */
+
+declare function estimateTokenCount(messages: Message[]): number;
+declare function countTokens(messages: Message[], model: string, provider: string): Promise<number>;
+/**
+ * Calculate if a request would exceed the context window given available space
+ */
+declare function wouldExceedContextWindow(currentTokens: number, contextWindow: number, maxOutputTokens: number): boolean;
+/**
+ * Calculate percentage of context window used
+ */
+declare function getContextWindowPercentage(currentTokens: number, contextWindow: number): number;
+/**
+ * Get safe reserve tokens for output (accounting for overhead)
+ */
+declare function getSafeOutputReserve(maxOutputTokens: number, bufferPercentage?: number): number;
+
+/**
+ * Message Pruning Utilities
+ *
+ * Implements strategies for removing messages from conversation history
+ * to stay within context window limits.
+ */
+
+interface PruneResult {
+    removed: number;
+    tokensReclaimed: number;
+    newTotal: number;
+    pruneInfo: {
+        beforeCount: number;
+        afterCount: number;
+        removedMessages: Message[];
+    };
+}
+/**
+ * Remove oldest messages to reclaim tokens
+ *
+ * Strategy: Remove oldest user/assistant pairs first, keeping system messages always.
+ * When an assistant message with tool_calls is removed, its paired tool result messages
+ * are also removed to prevent orphaned tool results that providers reject.
+ */
+declare function pruneMessages(messages: Message[], targetTokens: number, retainSystemMessages?: boolean): PruneResult;
+/**
+ * Truncate messages that exceed context window
+ */
+declare function truncateMessage(message: Message, maxTokens: number): Message;
+/**
+ * Group messages by type for analysis
+ */
+declare function groupMessagesByRole(messages: Message[]): Record<string, Message[]>;
+/**
+ * Get summary stats about messages
+ */
+declare function getMessageStats(messages: Message[]): {
+    totalMessages: number;
+    totalTokens: number;
+    byRole: Record<string, number>;
+    largestMessageTokens: number;
+};
+
+/**
+ * Options for summarizing messages
+ */
+interface SummarizationOptions {
+    /** Model to use for summarization (e.g., 'gpt-4-turbo') */
+    model: string;
+    /** Maximum tokens for summary (default: 500) */
+    maxSummaryTokens?: number;
+    /** Whether to preserve exact message boundaries or create coherent summary (default: false) */
+    preserveExactMessages?: boolean;
+    /** Custom summarization prompt template */
+    summaryPrompt?: string;
+    /** Custom format for summary marker in message history */
+    summaryMarkerFormat?: string;
+}
+/**
+ * Result of a summarization operation
+ */
+interface SummarizationResult {
+    /** Summary content */
+    summary: string;
+    /** Number of messages that were summarized */
+    messageCount: number;
+    /** Approximate tokens in original messages */
+    originalTokens: number;
+    /** Approximate tokens in summary */
+    summaryTokens: number;
+    /** Number of tokens saved */
+    tokensSaved: number;
+    /** Timestamp of summarization */
+    timestamp: Date;
+}
+/**
+ * Generates a default summarization prompt for the given messages
+ */
+declare function generateSummarizationPrompt(messages: Message[], userPrompt?: string): string;
+/**
+ * Creates a system message containing the conversation summary
+ */
+declare function createSummarySystemMessage(summary: string, originalMessageCount: number): Message;
+/**
+ * Extracts key information from messages for summarization
+ */
+declare function extractConversationKeypoints(messages: Message[]): {
+    topics: string[];
+    decisions: string[];
+    userGoals: string[];
+    context: string;
+};
+/**
+ * Estimates tokens in a summary (rough estimation)
+ */
+declare function estimateSummaryTokens(summaryText: string): number;
+/**
+ * Validates that a summarization result is sensible
+ */
+declare function validateSummarizationResult(result: SummarizationResult): {
+    valid: boolean;
+    issues: string[];
+};
+/**
+ * Prepares messages for summarization by the LLM
+ * Returns the messages that should be sent to the summarizer model
+ */
+declare function prepareSummarizationRequest(messagesToSummarize: Message[], options: SummarizationOptions): Message[];
+/**
+ * Parses the summarization response from the LLM
+ */
+declare function parseSummarizationResponse(response: string, originalMessages: Message[], originalTokenCount: number): SummarizationResult;
+/**
+ * Builds a new message array with summarized history
+ */
+declare function buildSummarizedHistory(systemMessages: Message[], summarizedContent: SummarizationResult, recentMessages: Message[]): Message[];
+/**
+ * Creates a detailed summarization report
+ */
+declare function createSummarizationReport(result: SummarizationResult, beforeMessageCount: number, afterMessageCount: number): string;
+/**
+ * Merges multiple summarization results into one
+ */
+declare function mergeSummarizationResults(results: SummarizationResult[]): SummarizationResult;
+
+/**
+ * Manages per-conversation context window state
+ * Tracks token usage, pruning operations, and summarization events
+ */
+declare class ContextWindowStateManager {
+    private states;
+    private config;
+    private maxTokens;
+    constructor(config: ContextWindowConfig);
+    /**
+     * Gets or creates state for a conversation
+     */
+    getOrCreateState(conversationId: string): ContextWindowState;
+    /**
+     * Updates token count for a conversation
+     */
+    updateTokenCount(conversationId: string, tokens: number): ContextWindowState;
+    /**
+     * Increments pruning operation counter
+     */
+    recordPruneOperation(conversationId: string, tokensRecovered: number): ContextWindowState;
+    /**
+     * Increments warning count
+     */
+    recordWarning(conversationId: string): ContextWindowState;
+    /**
+     * Increments summarization count
+     */
+    recordSummarization(conversationId: string, tokensSaved: number): ContextWindowState;
+    /**
+     * Gets the current state for a conversation
+     */
+    getState(conversationId: string): ContextWindowState | undefined;
+    /**
+     * Gets all tracked conversation states
+     */
+    getAllStates(): ContextWindowState[];
+    /**
+     * Deletes state for a conversation
+     */
+    deleteState(conversationId: string): boolean;
+    /**
+     * Clears all states
+     */
+    clearAllStates(): void;
+    /**
+     * Gets statistics for a conversation
+     */
+    getStatistics(conversationId: string): {
+        conversationId: string;
+        currentTokens: number;
+        pruneCount: number;
+        summarizationCount: number;
+        warningsSent: number;
+        lastActivity: Date | undefined;
+        contextWindowPercentage: number;
+    } | null;
+    /**
+     * Gets conversations exceeding a threshold
+     */
+    getExceedingThreshold(threshold?: number): ContextWindowState[];
+    /**
+     * Gets conversations at risk (approaching threshold)
+     */
+    getAtRiskConversations(riskPercentage?: number): ContextWindowState[];
+    /**
+     * Generates a report of all conversation states
+     */
+    generateReport(): string;
+    /**
+     * Exports state as JSON for persistence
+     */
+    export(): Record<string, ContextWindowState>;
+    /**
+     * Imports state from JSON
+     */
+    import(data: Record<string, ContextWindowState>): void;
+    /**
+     * Prunes old conversations (no activity in specified time)
+     */
+    pruneInactiveConversations(inactivityMinutes?: number): string[];
+    /**
+     * Gets memory usage of the state manager
+     */
+    getMemoryUsage(): {
+        conversationCount: number;
+        approximateByteSize: number;
+    };
+    /**
+     * Validates state integrity
+     */
+    validateIntegrity(): {
+        isValid: boolean;
+        issues: string[];
+    };
+}
+/**
+ * Creates a new ContextWindowStateManager with the given config
+ */
+declare function createContextWindowStateManager(config: ContextWindowConfig): ContextWindowStateManager;
+
 interface JsonRpcRequest {
     jsonrpc: '2.0';
     id: number | string;
@@ -2525,4 +3238,4 @@ interface McpServerCapabilities {
     prompts?: Record<string, any>;
 }
 
-export { AGENT_MODE, AGENT_PLANNING_PROMPT, AGENT_STEP_PROMPT, AGENT_WORKFLOW, AIClient, type AIClientConfig, type AddBypassRuleOptions, AnthropicAdapter, AuthenticationError, BM25SearchEngine, BUILT_IN_MODES, type BypassRuleType, CHAT_MODE, CHAT_WORKFLOW, CODING_PLANNING_PROMPT, CODING_STEP_PROMPT, CODING_WORKFLOW, CONFIG_DIR_NAME, CONFIG_FILE_NAME, type CompletionChunk, type CompletionOptions, type CompletionRequest, type CompletionResponse, type ConfirmationDecision, type ConfirmationLevel$1 as ConfirmationLevel, ConnectionError, DEFAULT_MODE_NAME, DEFAULT_TOOLS_CONFIG, DEFAULT_TOOL_SEARCH_CONFIG, DEFAULT_WORKFLOW, DEFAULT_WORKFLOW_CONFIG, type EmbeddingRequest, type EmbeddingResponse, type FileUploadRequest, type FileUploadResponse, GeminiAdapter, type HitlConfig, type ImageDataPart, type ImageFilePart, type ImagePart, type ImageUrlPart, type IntelligentToolDetectionConfig, InvalidRequestError, type JsonRpcRequest, type JsonRpcResponse, type KnowledgeInstance, McpClient, type McpClientConfig, McpConnectionError, type McpServerCapabilities, type McpServerConfig, McpTimeoutError, type McpTool, McpToolManager, type McpToolsConfig, type MediaOptions, type MediaUploadStrategy, type Message, type MessageContent, type ModeBlockedHint, type ModeConfig, ModeRegistry, OllamaAdapter, type OllamaAdapterConfig, type OllamaModelInfo, OllamaProvider, type OllamaProviderEntry, type OnToolConfirmCallback, OpenAIAdapter, PageError, type Plan, type PlanStep, Planner, ProviderAdapter, type ProviderConfig, ProviderError, type ProviderInfo, type ProviderModelInfo, type ProviderOptions, RateLimitError, type Role, type RuntimeConfigStatus, SDKError, type SearchHistoryEntry, type SearchOptions, type SearchResult, type SlmModelEntry, StepExecutor, TOOLPACK_DIR_NAME, TOOL_SEARCH_NAME, type TextPart, TimeoutError, type ToolCall, type ToolCallFunction, type ToolCallMessage, type ToolCallRequest, type ToolCallResult, type ToolCategory, type ToolConfirmation, type ToolConfirmationRequestedEvent, type ToolConfirmationResolvedEvent, type ToolContext, type ToolDefinition, ToolDiscoveryCache, type ToolLogEvent, type ToolParameterProperty, type ToolParameters, type ToolProgressEvent, type ToolProject, type ToolProjectDependencies, type ToolProjectManifest, ToolRegistry, type ToolResult, ToolRouter, type ToolSchema, type ToolSearchConfig, Toolpack, type ToolpackConfig, type ToolpackInitConfig, type ToolsConfig, type Usage, type WorkflowConfig, type WorkflowEvents, WorkflowExecutor, type WorkflowProgress, type WorkflowResult, addBypassRule, cloudDeployTool, cloudListTool, cloudStatusTool, cloudToolsProject, codingFindSymbolTool, codingGetImportsTool, codingGetSymbolsTool, codingToolsProject, createMcpToolProject, createMode, createToolProject, dbCountTool, dbDeleteTool, dbInsertTool, dbQueryTool, dbSchemaTool, dbTablesTool, dbToolsProject, dbUpdateTool, diffApplyTool, diffCreateTool, diffPreviewTool, diffToolsProject, disconnectMcpToolProject, ensureGlobalConfigDir, ensureLocalConfigDir, execKillTool, execListProcessesTool, execReadOutputTool, execRunBackgroundTool, execRunShellTool, execRunTool, execToolsProject, fetchUrlAsBase64, fsAppendFileTool, fsCopyTool, fsCreateDirTool, fsDeleteFileTool, fsExistsTool, fsListDirTool, fsMoveTool, fsReadFileRangeTool, fsReadFileTool, fsReplaceInFileTool, fsSearchTool, fsStatTool, fsToolsProject, fsTreeTool, fsWriteFileTool, generateToolCategoriesPrompt, getDefaultSlmModel, getGlobalConfigDir, getGlobalConfigPath, getGlobalToolpackDir, getLocalConfigDir, getLocalConfigPath, getLocalToolpackDir, getMimeType, getOllamaBaseUrl, getOllamaProviderEntries, getRegisteredSlmModels, getRuntimeConfigStatus, getToolSearchSchema, getToolpackConfig, getUserHomeDir, gitAddTool, gitBlameTool, gitBranchCreateTool, gitBranchListTool, gitCheckoutTool, gitCommitTool, gitDiffTool, gitLogTool, gitStatusTool, gitToolsProject, httpDeleteTool, httpDownloadTool, httpGetTool, httpPostTool, httpPutTool, httpToolsProject, initializeGlobalConfigIfFirstRun, isDataUri, isRegisteredSlm, isToolSearchTool, k8sApplyManifestTool, k8sDeleteResourceTool, k8sDescribeTool, k8sGetConfigMapTool, k8sGetLogsTool, k8sGetNamespacesTool, k8sListDeploymentsTool, k8sListPodsTool, k8sListServicesTool, k8sSwitchContextTool, k8sToolsProject, k8sWaitForDeploymentTool, loadFullConfig, loadRuntimeConfig, loadToolsConfig, normalizeImagePart, ollamaRequest, ollamaStream, parseDataUri, readFileAsBase64, reloadToolpackConfig, removeBypassRule, saveToolsConfig, systemCwdTool, systemDiskUsageTool, systemEnvTool, systemInfoTool, systemSetEnvTool, systemToolsProject, toDataUri, toolSearchDefinition, webExtractLinksTool, webFetchTool, webScrapeTool, webSearchTool, webToolsProject };
+export { AGENT_MODE, AGENT_PLANNING_PROMPT, AGENT_STEP_PROMPT, AGENT_WORKFLOW, AIClient, type AIClientConfig, type AddBypassRuleOptions, AnthropicAdapter, type AssembledPrompt, type AssemblerOptions, AuthenticationError, BM25SearchEngine, BUILT_IN_MODES, type BypassRuleType, CHAT_MODE, CHAT_WORKFLOW, CODING_MODE, CODING_PLANNING_PROMPT, CODING_STEP_PROMPT, CODING_WORKFLOW, CONFIG_DIR_NAME, CONFIG_FILE_NAME, type CompletionChunk, type CompletionOptions, type CompletionRequest, type CompletionResponse, type ConfirmationDecision, type ConfirmationLevel$1 as ConfirmationLevel, ConnectionError, type ContextPrunedEvent, type ContextWindowConfig, ContextWindowConfigError, ContextWindowExceededError, type ContextWindowExceededEvent, type ContextWindowState, ContextWindowStateManager, type ContextWindowStrategy, type ContextWindowWarningEvent, ConversationNotFoundError, type ConversationScope, type ConversationSearchOptions, type ConversationStore, type ConversationSummarizedEvent, DEFAULT_MODE_NAME, DEFAULT_TOOLS_CONFIG, DEFAULT_TOOL_SEARCH_CONFIG, DEFAULT_WORKFLOW, DEFAULT_WORKFLOW_CONFIG, type EmbeddingRequest, type EmbeddingResponse, type FileUploadRequest, type FileUploadResponse, GeminiAdapter, type GetOptions, type HitlConfig, type ImageDataPart, type ImageFilePart, type ImagePart, type ImageUrlPart, InMemoryConversationStore, type InMemoryConversationStoreConfig, InsufficientContextError, type IntelligentToolDetectionConfig, InvalidRequestError, type JsonRpcRequest, type JsonRpcResponse, type KnowledgeInstance, McpClient, type McpClientConfig, McpConnectionError, type McpServerCapabilities, type McpServerConfig, McpTimeoutError, type McpTool, McpToolManager, type McpToolsConfig, type MediaOptions, type MediaUploadStrategy, type Message, type MessageContent, type ModeBlockedHint, type ModeConfig, ModeRegistry, OllamaAdapter, type OllamaAdapterConfig, type OllamaModelInfo, OllamaProvider, type OllamaProviderEntry, type OnToolConfirmCallback, OpenAIAdapter, OpenRouterAdapter, type OpenRouterOptions, PageError, type Participant, type Plan, type PlanStep, Planner, type PromptMessage, ProviderAdapter, type ProviderConfig, ProviderError, type ProviderInfo, type ProviderModelInfo, type ProviderOptions, type PruneResult, RateLimitError, type RequestToolDefinition, type Role, type RuntimeConfigStatus, SDKError, SQLiteConversationStore, type SQLiteConversationStoreConfig, type SearchHistoryEntry, type SearchOptions, type SearchResult, type SlmModelEntry, StepExecutor, type StoredMessage, SummarizationError, type SummarizationOptions, type SummarizationResult, TOOLPACK_DIR_NAME, TOOL_SEARCH_NAME, type TextPart, TimeoutError, type ToolCall, type ToolCallFunction, type ToolCallMessage, type ToolCallRequest, type ToolCallResult, type ToolCategory, type ToolConfirmation, type ToolConfirmationRequestedEvent, type ToolConfirmationResolvedEvent, type ToolContext, type ToolDefinition, ToolDiscoveryCache, type ToolLogEvent, type ToolParameterProperty, type ToolParameters, type ToolProgressEvent, type ToolProject, type ToolProjectDependencies, type ToolProjectManifest, ToolRegistry, type ToolResult, ToolRouter, type ToolSchema, type ToolSearchConfig, Toolpack, type ToolpackConfig, type ToolpackInitConfig, type ToolsConfig, type Usage, type WorkflowConfig, type WorkflowEvents, WorkflowExecutor, type WorkflowProgress, type WorkflowResult, addBypassRule, buildSummarizedHistory, cloudDeployTool, cloudListTool, cloudStatusTool, cloudToolsProject, codingFindSymbolTool, codingGetImportsTool, codingGetSymbolsTool, codingToolsProject, countTokens, createContextWindowStateManager, createMcpToolProject, createMode, createSummarizationReport, createSummarySystemMessage, createToolProject, dbCountTool, dbDeleteTool, dbInsertTool, dbQueryTool, dbSchemaTool, dbTablesTool, dbToolsProject, dbUpdateTool, diffApplyTool, diffCreateTool, diffPreviewTool, diffToolsProject, disconnectMcpToolProject, ensureGlobalConfigDir, ensureLocalConfigDir, estimateSummaryTokens, estimateTokenCount, execKillTool, execListProcessesTool, execReadOutputTool, execRunBackgroundTool, execRunShellTool, execRunTool, execToolsProject, extractConversationKeypoints, fetchUrlAsBase64, fsAppendFileTool, fsCopyTool, fsCreateDirTool, fsDeleteFileTool, fsExistsTool, fsListDirTool, fsMoveTool, fsReadFileRangeTool, fsReadFileTool, fsReplaceInFileTool, fsSearchTool, fsStatTool, fsToolsProject, fsTreeTool, fsWriteFileTool, generateSummarizationPrompt, generateToolCategoriesPrompt, getContextWindowPercentage, getDefaultSlmModel, getGlobalConfigDir, getGlobalConfigPath, getGlobalToolpackDir, getLocalConfigDir, getLocalConfigPath, getLocalToolpackDir, getMessageStats, getMimeType, getOllamaBaseUrl, getOllamaProviderEntries, getRegisteredSlmModels, getRuntimeConfigStatus, getSafeOutputReserve, getToolSearchSchema, getToolpackConfig, getUserHomeDir, gitAddTool, gitBlameTool, gitBranchCreateTool, gitBranchListTool, gitCheckoutTool, gitCommitTool, gitDiffTool, gitLogTool, gitStatusTool, gitToolsProject, githubContentsGetTextTool, githubGraphqlExecuteTool, githubPrDiffGetTool, githubPrFilesListTool, githubPrReviewCommentsReplyTool, githubPrReviewThreadsListTool, githubPrReviewThreadsResolveTool, githubPrReviewsSubmitTool, githubToolsProject, groupMessagesByRole, handleContextWindowError, httpDeleteTool, httpDownloadTool, httpGetTool, httpPostTool, httpPutTool, httpToolsProject, initializeGlobalConfigIfFirstRun, isContextWindowError, isDataUri, isRegisteredSlm, isToolSearchTool, k8sApplyManifestTool, k8sDeleteResourceTool, k8sDescribeTool, k8sGetConfigMapTool, k8sGetLogsTool, k8sGetNamespacesTool, k8sListDeploymentsTool, k8sListPodsTool, k8sListServicesTool, k8sSwitchContextTool, k8sToolsProject, k8sWaitForDeploymentTool, loadFullConfig, loadRuntimeConfig, loadToolsConfig, mergeSummarizationResults, normalizeImagePart, ollamaRequest, ollamaStream, parseDataUri, parseSummarizationResponse, prepareSummarizationRequest, pruneMessages, readFileAsBase64, reloadToolpackConfig, removeBypassRule, saveToolsConfig, systemCwdTool, systemDiskUsageTool, systemEnvTool, systemInfoTool, systemSetEnvTool, systemToolsProject, toDataUri, toolSearchDefinition, truncateMessage, validateSummarizationResult, webExtractLinksTool, webFetchTool, webScrapeTool, webSearchTool, webToolsProject, wouldExceedContextWindow };