toolpack-sdk 1.4.0 → 2.0.0

package/dist/index.d.ts

@@ -104,13 +104,6 @@ interface ToolCategory {
     description: string;
     tools: string[];
 }
-/**
- * @deprecated This interface is deprecated and will be removed in a future version.
- */
-interface IntelligentToolDetectionConfig {
-    enabled: boolean;
-    maxFollowUpMessages: number;
-}
 /**
  * Tool Search Configuration (Anthropic-style on-demand tool discovery)
  */
@@ -127,10 +120,6 @@ interface ToolsConfig {
     maxToolRounds: number;
     toolChoicePolicy?: 'auto' | 'required' | 'required_for_actions';
     resultMaxChars?: number;
-    /**
-     * @deprecated This feature is deprecated and will be removed in a future version. Use `toolSearch` instead.
-     */
-    intelligentToolDetection?: IntelligentToolDetectionConfig;
     enabledTools: string[];
     enabledToolCategories: string[];
     toolSearch?: ToolSearchConfig;
@@ -221,6 +210,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,11 +236,19 @@ 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;
     /** Multimodal media handling options */
     mediaOptions?: MediaOptions;
+    /**
+     * Per-request hard cap on tool-call rounds.
+     * When set, overrides ToolsConfig.maxToolRounds and bypasses the query
+     * classifier adjustment for this specific request.
+     * Useful for agents that should only ever make one tool call (e.g. routers).
+     */
+    maxToolRounds?: number;
 }
 interface Usage {
     prompt_tokens: number;
@@ -391,6 +398,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 +482,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 +636,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>;
 }
 
 /**
@@ -650,24 +820,6 @@ interface WorkflowConfig {
         /** Maximum number of steps allowed in a plan. Default: 20 */
         maxSteps?: number;
     };
-    /**
-     * Step-based execution configuration.
-     * If enabled, tasks are broken into steps and executed sequentially.
-     */
-    steps?: {
-        /** Enable step-based execution. Default: false */
-        enabled: boolean;
-        /** Retry failed steps. Default: true */
-        retryOnFailure?: boolean;
-        /** Maximum retry attempts per step. Default: 3 */
-        maxRetries?: number;
-        /** Allow adding/modifying steps during execution. Default: true */
-        allowDynamicSteps?: boolean;
-        /** Maximum total steps (including dynamic). Default: 50 */
-        maxTotalSteps?: number;
-        /** Custom step execution prompt. Default: uses built-in STEP_EXECUTION_PROMPT */
-        stepPrompt?: string;
-    };
     /**
      * Progress reporting configuration.
      */
@@ -677,13 +829,6 @@ interface WorkflowConfig {
         /** Report estimated completion percentage. Default: true */
         reportPercentage?: boolean;
     };
-    /**
-     * Failure handling configuration.
-     */
-    onFailure?: {
-        /** Strategy when a step fails after all retries. Default: 'abort' */
-        strategy: 'abort' | 'skip' | 'ask_user';
-    };
     /**
      * Query complexity routing configuration.
      * Routes simple queries to faster execution paths based on query classification.
@@ -698,7 +843,7 @@ interface WorkflowConfig {
     };
 }
 /**
- * Default workflow config (direct execution, no planning/steps).
+ * Default workflow config (direct execution, no planning).
  */
 declare const DEFAULT_WORKFLOW_CONFIG: WorkflowConfig;
 interface WorkflowEvents {
@@ -708,23 +853,50 @@ interface WorkflowEvents {
     'workflow:plan_decision': (plan: Plan, approved: boolean) => void;
     /** Emitted when plan execution starts */
     'workflow:started': (plan: Plan) => void;
-    /** Emitted when a step starts */
-    'workflow:step_start': (step: PlanStep, plan: Plan) => void;
-    /** Emitted when a step completes successfully */
-    'workflow:step_complete': (step: PlanStep, plan: Plan) => void;
-    /** Emitted when a step fails */
-    'workflow:step_failed': (step: PlanStep, error: Error, plan: Plan) => void;
-    /** Emitted when a step is retried */
-    'workflow:step_retry': (step: PlanStep, attempt: number, plan: Plan) => void;
-    /** Emitted when a new step is dynamically added */
-    '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 +1051,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 +1138,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 +1158,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 +1258,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.
@@ -1114,6 +1307,12 @@ declare class AIClient extends EventEmitter {
      */
     private executeToolSearch;
     private wrapError;
+    /**
+     * Truncate a tool result to fit within the remaining round budget.
+     * Instead of silently dropping the output, include as much content as possible
+     * and append an actionable hint so the LLM can retry with a narrower query.
+     */
+    private budgetTruncate;
 }
 
 declare class AnthropicAdapter extends ProviderAdapter {
@@ -1152,6 +1351,43 @@ declare class AnthropicAdapter extends ProviderAdapter {
     private handleError;
 }
 
+interface VertexAIConfig {
+    /** GCP project ID. Falls back to TOOLPACK_VERTEXAI_PROJECT or VERTEX_AI_PROJECT env vars. */
+    projectId?: string;
+    /** GCP region. Defaults to 'us-central1'. Falls back to TOOLPACK_VERTEXAI_LOCATION or VERTEX_AI_LOCATION env vars. */
+    location?: string;
+    /**
+     * Optional Google Auth options.
+     * When omitted, Application Default Credentials (ADC) are used automatically.
+     * Set GOOGLE_APPLICATION_CREDENTIALS env var to point to a service account JSON file.
+     */
+    googleAuthOptions?: {
+        /** Path to a service account key JSON file. */
+        keyFilename?: string;
+        /** Inline service account credentials object. */
+        credentials?: Record<string, unknown>;
+    };
+}
+declare class VertexAIAdapter extends ProviderAdapter {
+    private vertexAI;
+    private readonly location;
+    constructor(config?: VertexAIConfig);
+    getDisplayName(): string;
+    getModels(): Promise<ProviderModelInfo[]>;
+    generate(request: CompletionRequest): Promise<CompletionResponse>;
+    stream(request: CompletionRequest): AsyncGenerator<CompletionChunk>;
+    embed(_request: EmbeddingRequest): Promise<EmbeddingResponse>;
+    private buildModel;
+    private formatHistory;
+    private contentToParts;
+    private parseResponse;
+    private extractSystemInstruction;
+    private sanitizeToolName;
+    private restoreToolName;
+    private sanitizeSchema;
+    private handleError;
+}
+
 declare class GeminiAdapter extends ProviderAdapter {
     private genAI;
     constructor(apiKey: string);
@@ -1351,6 +1587,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): {
@@ -1793,6 +2047,14 @@ declare const fsReplaceInFileTool: ToolDefinition;
 
 declare const fsTreeTool: ToolDefinition;
 
+declare const fsGlobTool: ToolDefinition;
+
+declare const fsDeleteDirTool: ToolDefinition;
+
+declare const fsBatchReadTool: ToolDefinition;
+
+declare const fsBatchWriteTool: ToolDefinition;
+
 declare const fsToolsProject: ToolProject;
 
 declare const execRunTool: ToolDefinition;
@@ -1833,6 +2095,26 @@ 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 githubIssuesCommentsCreateTool: ToolDefinition;
+
+declare const githubToolsProject: ToolProject;
+
 declare const webFetchTool: ToolDefinition;
 
 declare const webSearchTool: ToolDefinition;
@@ -1841,6 +2123,16 @@ declare const webScrapeTool: ToolDefinition;
 
 declare const webExtractLinksTool: ToolDefinition;
 
+declare const webMapTool: ToolDefinition;
+
+declare const webMetadataTool: ToolDefinition;
+
+declare const webSitemapTool: ToolDefinition;
+
+declare const webFeedTool: ToolDefinition;
+
+declare const webScreenshotTool: ToolDefinition;
+
 declare const webToolsProject: ToolProject;
 
 declare const codingFindSymbolTool: ToolDefinition;
@@ -1849,6 +2141,24 @@ declare const codingGetSymbolsTool: ToolDefinition;
 
 declare const codingGetImportsTool: ToolDefinition;
 
+declare const codingFindReferencesTool: ToolDefinition;
+
+declare const codingGoToDefinitionTool: ToolDefinition;
+
+declare const codingMultiFileEditTool: ToolDefinition;
+
+declare const codingRefactorRenameTool: ToolDefinition;
+
+declare const codingGetOutlineTool: ToolDefinition;
+
+declare const codingGetDiagnosticsTool: ToolDefinition;
+
+declare const codingGetExportsTool: ToolDefinition;
+
+declare const codingExtractFunctionTool: ToolDefinition;
+
+declare const codingGetCallHierarchyTool: ToolDefinition;
+
 declare const codingToolsProject: ToolProject;
 
 declare const gitStatusTool: ToolDefinition;
@@ -1869,6 +2179,8 @@ declare const gitBranchCreateTool: ToolDefinition;
 
 declare const gitCheckoutTool: ToolDefinition;
 
+declare const gitCloneTool: ToolDefinition;
+
 declare const gitToolsProject: ToolProject;
 
 declare const diffCreateTool: ToolDefinition;
@@ -1917,6 +2229,56 @@ declare const k8sWaitForDeploymentTool: ToolDefinition;
 
 declare const k8sToolsProject: ToolProject;
 
+declare const slackChatPostMessageTool: ToolDefinition;
+
+declare const slackChatPostEphemeralTool: ToolDefinition;
+
+declare const slackReactionsAddTool: ToolDefinition;
+
+declare const slackConversationsHistoryTool: ToolDefinition;
+
+declare const slackConversationsRepliesTool: ToolDefinition;
+
+declare const slackAuthTestTool: ToolDefinition;
+
+declare const slackToolsProject: ToolProject;
+
+type SkillSection = 'description' | 'triggers' | 'instructions' | 'examples' | 'metadata' | 'all';
+type SkillValidationMode = 'fail' | 'warn';
+interface Skill {
+    name: string;
+    title: string;
+    version?: string;
+    tags: string[];
+    category?: string;
+    filePath: string;
+    description: string;
+    triggers: string[];
+    instructions: string;
+    examples?: string;
+    lastModified: number;
+}
+interface SkillInterceptorOptions {
+    dir?: string;
+    maxSkills?: number;
+    minScore?: number;
+    onValidationError?: SkillValidationMode;
+}
+interface SkillToolsOptions {
+    /** Skills directory. Default: '.toolpack/skills' */
+    dir?: string;
+}
+
+/**
+ * Creates a ToolProject with 4 skill management tools: create, read, update, list.
+ *
+ * @example
+ * ```ts
+ * const skillTools = createSkillTools({ dir: '.toolpack/skills' });
+ * ```
+ */
+declare function createSkillTools(options?: SkillToolsOptions): ToolProject;
+
 /**
  * Central registry for AI agent modes (built-in + custom).
  * Handles registration, lookup, cycling, and defaults.
@@ -2013,11 +2375,6 @@ declare function createMode(config: {
             enabled: boolean;
             requireApproval?: boolean;
         };
-        steps?: {
-            enabled: boolean;
-            retryOnFailure?: boolean;
-            allowDynamicSteps?: boolean;
-        };
         progress?: {
             enabled: boolean;
         };
@@ -2041,6 +2398,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.
  *
@@ -2067,39 +2433,10 @@ declare class Planner {
     private createFallbackPlan;
 }
 
-declare class StepExecutor {
-    private client;
-    private config?;
-    constructor(client: AIClient, config?: WorkflowConfig['steps']);
-    /**
-     * Executes a single step of the plan using the full tool loop.
-     */
-    executeStep(step: PlanStep, plan: Plan, baseRequest: CompletionRequest, providerName?: string): Promise<NonNullable<PlanStep['result']>>;
-    /**
-     * Stream a single step execution, yielding chunks as they come.
-     */
-    streamStep(step: PlanStep, plan: Plan, baseRequest: CompletionRequest, providerName?: string): AsyncGenerator<CompletionChunk>;
-    /**
-     * Build a context-aware request for a specific step, including previous step results
-     * as conversation history so the AI knows what work was already done.
-     */
-    private buildStepRequest;
-    /**
-     * Optional: Check if the AI wants to add steps dynamically based on what just happened.
-     */
-    checkForDynamicSteps(step: PlanStep, plan: Plan, baseRequest: CompletionRequest, providerName?: string): Promise<PlanStep[]>;
-    /**
-     * Normalize step description for duplicate detection.
-     * Strips common variations to catch semantically similar steps.
-     */
-    private normalizeStepDescription;
-}
-
 declare class WorkflowExecutor extends EventEmitter {
     private client;
     private config;
     private planner;
-    private stepExecutor;
     private queryClassifier;
     private pendingApprovals;
     constructor(client: AIClient, config: WorkflowConfig, queryClassifier?: QueryClassifier);
@@ -2118,6 +2455,10 @@ declare class WorkflowExecutor extends EventEmitter {
     private shouldRouteSimpleQuery;
     /**
      * Execute a request using the configured workflow.
+     *
+     * Modes:
+     *   - Direct:       no planning — single generate() call
+     *   - Plan-direct:  planning generates a roadmap, then executes in one generate() call
      */
     execute(request: CompletionRequest, providerName?: string): Promise<WorkflowResult>;
     /**
@@ -2129,39 +2470,31 @@ declare class WorkflowExecutor extends EventEmitter {
      */
     private createPlan;
     /**
-     * Execute plan step by step using the StepExecutor.
-     */
-    private executeStepByStep;
-    /**
-     * Planning without steps — execute plan as single generate call.
+     * Planning without steps — inject plan as context prefix and execute in one generate() call.
+     * The LLM sees its own roadmap and uses it to guide tool usage and sequencing.
      */
     private executePlanDirect;
     /**
-     * Emit a progress event using StepTracker.
+     * Emit a progress event.
+     * @param percentageOverride - Optional fixed percentage (0–100). Use for plan-direct
+     *   mode where steps complete atomically and intermediate step-level progress is unavailable.
      */
     private emitProgress;
     /**
      * Compute metrics for the plan.
      */
     private computeMetrics;
-    /**
-     * Summarize the entire plan execution.
-     */
-    private summarizePlanResult;
-    /**
-     * Extract the final output from the plan.
-     * For plans with synthesis step: returns last step output.
-     * For plans without synthesis: concatenates all step outputs.
-     */
-    private extractFinalOutput;
-    /**
-     * Extract the full response metadata from the last completed step.
-     */
-    private extractFinalResponse;
     /**
      * Create a dummy plan for internal representation when no plan is generated.
      */
     private createDummyPlan;
+    /**
+     * Inject plan context as a system message.
+     * If the request already has a leading system message (e.g., a mode system prompt),
+     * merge the plan context into it to avoid sending multiple system messages to providers
+     * that don't support or handle them inconsistently.
+     */
+    private injectPlanContext;
     /**
      * Execute a request using the configured workflow, yielding chunks as they come.
      * This is the streaming equivalent of execute().
@@ -2172,11 +2505,8 @@ declare class WorkflowExecutor extends EventEmitter {
      */
     private streamDirect;
     /**
-     * Stream plan execution step by step.
-     */
-    private streamStepByStep;
-    /**
-     * Stream plan execution as a single request (planning without steps).
+     * Stream plan execution as a single request (plan-direct).
+     * Injects the plan as a system prefix so the LLM uses it as its own roadmap.
      */
     private streamPlanDirect;
     /**
@@ -2198,19 +2528,16 @@ declare class WorkflowExecutor extends EventEmitter {
  * Full detailed planning for general autonomous tasks.
  */
 declare const AGENT_PLANNING_PROMPT = "\nYou are a planning assistant. Given a user request, create a detailed step-by-step plan.\n\nRules:\n1. Break the task into clear, actionable steps\n2. Each step should be independently executable WITHOUT requiring additional user input\n3. Order steps by dependencies (what must happen first)\n4. Be specific about what each step will accomplish\n5. Estimate which tools will be needed for each step\n6. If the user's request is ambiguous, make reasonable assumptions and proceed - do NOT create steps that ask for clarification\n7. Steps should produce concrete outputs, not ask questions or wait for user input\n8. ALWAYS include at least one step, even for simple questions. For simple factual questions, create a single step like \"Provide the answer to [question]\"\n9. When a step uses information gathered by a previous step, set \"dependsOn\" to that step's number and phrase the description as \"Using the [data] from step N, [do something]\" instead of gathering it again\n10. For plans with MORE than 2 steps, the final step must synthesize the workflow's results into a concise deliverable, avoiding redundant word-for-word repetition of earlier step outputs. For plans with 1-2 steps, no synthesis step is needed.\n11. The exact result MUST be valid JSON matching this schema:\n{\n  \"summary\": \"Brief description of the overall goal\",\n  \"steps\": [\n    {\n      \"number\": 1,\n      \"description\": \"What this step does\",\n      \"expectedTools\": [\"tool.name\"],\n      \"dependsOn\": []\n    }\n  ]\n}\n";
-/**
- * Agent step execution prompt.
- * Standard execution with detailed instructions.
- */
-declare const AGENT_STEP_PROMPT = "\nYou are executing step {stepNumber} of a plan.\n\nPlan summary: {planSummary}\n\nCurrent step: {stepDescription}\n\nPrevious steps completed:\n{previousStepsResults}\n\nExecute this step now. Use the available tools as needed to accomplish this specific step.\nMake reasonable assumptions if any details are ambiguous - do NOT ask the user for clarification or additional input.\nProduce concrete results based on the information available.\nIf you cannot complete this step, explain why.\n\nIMPORTANT: Your response should be written as if you are directly answering the user.\nDo NOT mention steps, plans, workflow details, or internal process in your response.\nDo NOT say things like \"Step 1 is complete\" or \"proceeding to the next step\".\nJust provide the actual answer or result naturally.\n";
 /**
  * Default workflow configuration.
- * Direct execution with no planning or steps.
+ * Direct execution with no planning.
  */
 declare const DEFAULT_WORKFLOW: WorkflowConfig;
 /**
  * Agent workflow configuration.
- * Full planning and step execution with dynamic steps disabled.
+ * Plan-direct: planning phase generates a structured roadmap, then executes in a single
+ * generate() call with full tool parallelism. Simpler queries bypass planning via
+ * complexity routing.
  */
 declare const AGENT_WORKFLOW: WorkflowConfig;
 /**
@@ -2218,22 +2545,35 @@ declare const AGENT_WORKFLOW: WorkflowConfig;
  * Minimal rules focused on actionable code changes.
  */
 declare const CODING_PLANNING_PROMPT = "\nCreate a step-by-step plan for this coding task.\n\nRules:\n1. Break into actionable steps using tools (read/write files, search code)\n2. Each step executes independently without user input\n3. Order by dependencies\n4. Individual steps: be concise and technical. No conversational filler.\n5. For >2 steps, final step summarizes changes with conversational explanation\n6. Output valid JSON: {\"summary\": \"...\", \"steps\": [{...}]}\n\nJSON Schema:\n{\n  \"summary\": \"Brief description of the overall goal\",\n  \"steps\": [\n    {\n      \"number\": 1,\n      \"description\": \"What this step does\",\n      \"expectedTools\": [\"tool.name\"],\n      \"dependsOn\": []\n    }\n  ]\n}\n";
-/**
- * Concise step execution prompt for coding tasks.
- * No meta-commentary, focused on tool usage.
- */
-declare const CODING_STEP_PROMPT = "\nExecute step {stepNumber}: {stepDescription}\n\nPlan: {planSummary}\n\nPrevious: {previousStepsResults}\n\nUse tools. Be concise. Show code changes clearly.\nNo meta-commentary about steps or workflow.\n";
 /**
  * Coding workflow configuration.
- * Concise prompts optimized for software development tasks.
+ * Plan-direct: planning phase generates a structured roadmap using concise coding-focused prompts,
+ * then executes in a single generate() call with full tool parallelism.
  */
 declare const CODING_WORKFLOW: WorkflowConfig;
 /**
  * Chat workflow configuration.
- * No planning or steps - direct conversational responses.
+ * Direct conversational responses — no planning.
  */
 declare const CHAT_WORKFLOW: WorkflowConfig;
 
+type ToolpackNextFunction = (request?: CompletionRequest) => Promise<CompletionResponse>;
+/**
+ * An interceptor that wraps each `generate()` call.
+ *
+ * It is a callable with an optional `init()` hook. When `init()` is present,
+ * `Toolpack.init()` calls it once during startup — before any message is
+ * processed — so interceptors can validate config, warm caches, or fail fast
+ * on bad state (e.g. invalid skill files) rather than failing on the first request.
+ *
+ * Plain arrow functions without `init` are fully compatible with this type.
+ */
+type ToolpackInterceptor = {
+    (request: CompletionRequest, next: ToolpackNextFunction): Promise<CompletionResponse>;
+    /** Optional startup hook called once by `Toolpack.init()`. */
+    init?(): Promise<void>;
+};
+
 interface ProviderOptions {
     /**
      * API key for the provider.
@@ -2246,6 +2586,19 @@ 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;
+    /** Vertex AI only: GCP project ID. Falls back to TOOLPACK_VERTEXAI_PROJECT / VERTEX_AI_PROJECT / GOOGLE_CLOUD_PROJECT env vars. */
+    projectId?: string;
+    /** Vertex AI only: GCP region. Defaults to 'us-central1'. Falls back to TOOLPACK_VERTEXAI_LOCATION / VERTEX_AI_LOCATION env vars. */
+    location?: string;
+    /** Vertex AI only: optional Google Auth options (keyFilename or credentials). When omitted, ADC is used. */
+    googleAuthOptions?: {
+        keyFilename?: string;
+        credentials?: Record<string, unknown>;
+    };
 }
 interface ToolpackInitConfig {
     /** Single provider shorthand (e.g. 'openai', 'anthropic', 'gemini') */
@@ -2257,8 +2610,19 @@ interface ToolpackInitConfig {
     apiKey?: string;
     /** Model name for the single provider */
     model?: string;
+    /** Vertex AI only: GCP project ID. Falls back to TOOLPACK_VERTEXAI_PROJECT / VERTEX_AI_PROJECT / GOOGLE_CLOUD_PROJECT env vars. */
+    projectId?: string;
+    /** Vertex AI only: GCP region. Defaults to 'us-central1'. */
+    location?: string;
+    /** Vertex AI only: optional Google Auth options. When omitted, ADC is used automatically. */
+    googleAuthOptions?: {
+        keyFilename?: string;
+        credentials?: Record<string, unknown>;
+    };
     /** 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 +2652,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.
@@ -2310,6 +2675,15 @@ interface ToolpackInitConfig {
     }) => Promise<ConfirmationDecision>;
     /** Optional conversation ID for tracking context across confirmations */
     conversationId?: string;
+    /**
+     * Optional interceptors that wrap each `generate()` call in the direct execution path.
+     * Each interceptor receives the full CompletionRequest and a `next()` function.
+     * Interceptors run in order (first in array runs outermost).
+     *
+     * Note: interceptors apply to `generate()` only, not `stream()`.
+     * The workflow execution path (when a mode has planning enabled) is also unaffected.
+     */
+    interceptors?: ToolpackInterceptor[];
 }
 /**
  * Duck-typed interface for Knowledge instances to avoid circular dependency
@@ -2340,6 +2714,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 +2723,13 @@ declare class Toolpack extends EventEmitter {
     private activeProviderName;
     private modeRegistry;
     private workflowExecutor;
+    private knowledgeLayers;
     customProviderNames: Set<string>;
     private mcpToolProject;
+    private _interceptors;
     private constructor();
+    private buildKnowledgeRequestTools;
+    private prepareRequest;
     /**
      * Initialize the Toolpack SDK.
      *
@@ -2363,6 +2742,7 @@ declare class Toolpack extends EventEmitter {
      */
     private static createProvider;
     generate(request: CompletionRequest | string, providerName?: string): Promise<CompletionResponse>;
+    private _buildInterceptorChain;
     stream(request: CompletionRequest, providerName?: string): AsyncGenerator<CompletionChunk>;
     embed(request: EmbeddingRequest, providerName?: string): Promise<EmbeddingResponse>;
     /**
@@ -2433,6 +2813,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 +3051,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 +3330,6 @@ 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 };
+declare function createSkillInterceptor(options?: SkillInterceptorOptions): ToolpackInterceptor;
+
+export { AGENT_MODE, AGENT_PLANNING_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_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, 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 Skill, type SkillInterceptorOptions, type SkillSection, type SkillToolsOptions, type SkillValidationMode, type SlmModelEntry, 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 ToolpackInterceptor, type ToolpackNextFunction, type ToolsConfig, type Usage, VertexAIAdapter, type VertexAIConfig, type WorkflowConfig, type WorkflowEvents, WorkflowExecutor, type WorkflowProgress, type WorkflowResult, addBypassRule, buildSummarizedHistory, cloudDeployTool, cloudListTool, cloudStatusTool, cloudToolsProject, codingExtractFunctionTool, codingFindReferencesTool, codingFindSymbolTool, codingGetCallHierarchyTool, codingGetDiagnosticsTool, codingGetExportsTool, codingGetImportsTool, codingGetOutlineTool, codingGetSymbolsTool, codingGoToDefinitionTool, codingMultiFileEditTool, codingRefactorRenameTool, codingToolsProject, countTokens, createContextWindowStateManager, createMcpToolProject, createMode, createSkillInterceptor, createSkillTools, 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, fsBatchReadTool, fsBatchWriteTool, fsCopyTool, fsCreateDirTool, fsDeleteDirTool, fsDeleteFileTool, fsExistsTool, fsGlobTool, 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, gitCloneTool, gitCommitTool, gitDiffTool, gitLogTool, gitStatusTool, gitToolsProject, githubContentsGetTextTool, githubGraphqlExecuteTool, githubIssuesCommentsCreateTool, 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, slackAuthTestTool, slackChatPostEphemeralTool, slackChatPostMessageTool, slackConversationsHistoryTool, slackConversationsRepliesTool, slackReactionsAddTool, slackToolsProject, systemCwdTool, systemDiskUsageTool, systemEnvTool, systemInfoTool, systemSetEnvTool, systemToolsProject, toDataUri, toolSearchDefinition, truncateMessage, validateSummarizationResult, webExtractLinksTool, webFeedTool, webFetchTool, webMapTool, webMetadataTool, webScrapeTool, webScreenshotTool, webSearchTool, webSitemapTool, webToolsProject, wouldExceedContextWindow };