toolpack-sdk 3.0.0 → 3.2.0

package/dist/index.d.cts

@@ -497,12 +497,6 @@ interface ModeConfig {
      * Shorthand for "no tool calls at all".
      */
     blockAllTools: boolean;
-    /**
-     * Whether to auto-inject relevant skill content into the system prompt
-     * via BM25 matching of the user's message (skill interceptor).
-     * Default: false — opt-in only. Set to true to enable auto-injection.
-     */
-    skillInterceptor?: boolean;
     /**
      * Root directory for rule files.
      * Auto-discovers:
@@ -579,7 +573,29 @@ interface ImageUrlPart {
     };
 }
 type ImagePart = ImageDataPart | ImageFilePart | ImageUrlPart;
-type MessageContent = string | (TextPart | ImagePart)[] | null;
+interface FilePart {
+    type: 'file';
+    file: {
+        /** Public or pre-signed bucket URL */
+        url: string;
+        /** MIME type, e.g. 'image/jpeg', 'application/pdf' */
+        mimeType: string;
+        /** Original filename, for display only */
+        name?: string;
+        /** File size in bytes — used for client-side validation */
+        size?: number;
+    };
+}
+declare const FILE_LIMITS: {
+    readonly image: {
+        readonly maxBytes: number;
+    };
+    readonly document: {
+        readonly maxBytes: number;
+        readonly maxPages: 20;
+    };
+};
+type MessageContent = string | (TextPart | ImagePart | FilePart)[] | null;
 type MediaUploadStrategy = 'inline' | 'upload' | 'auto';
 interface MediaOptions {
     /** How to handle image payloads */
@@ -2035,9 +2051,10 @@ declare class ToolDiscoveryCache {
 declare const TOOL_SEARCH_NAME = "tool.search";
 declare const toolSearchDefinition: ToolDefinition;
 /**
- * Get the tool.search schema (without execute function).
+ * Get the tool.search schema, optionally with a dynamic category enum
+ * derived from the currently registered tool categories.
  */
-declare function getToolSearchSchema(): ToolSchema;
+declare function getToolSearchSchema(categories?: string[]): ToolSchema;
 /**
  * Check if a tool name is the tool.search meta-tool.
  */
@@ -2548,12 +2565,6 @@ interface Skill {
     examples?: string;
     lastModified: number;
 }
-interface SkillInterceptorOptions {
-    dir?: string;
-    maxSkills?: number;
-    minScore?: number;
-    onValidationError?: SkillValidationMode;
-}
 interface SkillToolsOptions {
     /** Skills directory. Default: '.toolpack/skills' */
     dir?: string;
@@ -2674,11 +2685,6 @@ declare function createMode(config: {
             enabled: boolean;
         };
     };
-    /**
-     * Enable auto-injection of BM25-matched skill content into the system prompt.
-     * Default: false — opt-in only.
-     */
-    skillInterceptor?: boolean;
     /**
      * Root directory for rule files for this mode.
      * Auto-discovers __global__/ and <mode-name>/ subfolders within it.
@@ -3156,6 +3162,12 @@ interface ToolpackInitConfig {
     region?: string;
     /** Load built-in tools (fs, http, etc.)? Default: false */
     tools?: boolean;
+    /**
+     * Tool projects that override built-in tools by name.
+     * Loaded after built-ins, so any tool with the same name replaces the built-in version.
+     * Also used to extend the tool.search category enum dynamically.
+     */
+    toolOverrides?: ToolProject[];
     /** Context window management configuration for automatic conversation pruning/summarization */
     contextWindow?: ContextWindowConfig;
     /**
@@ -3268,8 +3280,18 @@ declare class Toolpack extends EventEmitter {
     customProviderNames: Set<string>;
     private mcpToolProject;
     private _interceptors;
+    private _instanceRequestTools;
     private constructor();
-    private buildKnowledgeRequestTools;
+    private _buildKnowledgeRequestTools;
+    /**
+     * Register tools that bypass mode filtering and are always available to the model.
+     * Use this for tools that must be accessible regardless of allowedToolCategories —
+     * the same mechanism used by knowledge, skill, and scheduler tools internally.
+     *
+     * Prefer `loadRequestToolProject` when you have a ToolProject; call this directly
+     * when you have a plain RequestToolDefinition array.
+     */
+    registerRequestTools(tools: RequestToolDefinition[]): void;
     private prepareRequest;
     /**
      * Initialize the Toolpack SDK.
@@ -3327,6 +3349,32 @@ declare class Toolpack extends EventEmitter {
      * Validates dependencies and registers all tools.
      */
     loadToolProject(project: ToolProject): Promise<void>;
+    /**
+     * Load multiple tool projects at runtime, rebuilding the BM25 index once after all are registered.
+     */
+    loadToolProjects(projects: ToolProject[]): Promise<void>;
+    /**
+     * Register a tool project's tools as request tools, bypassing mode filtering entirely.
+     * Use this instead of loadToolProject when the tools must always be available regardless
+     * of allowedToolCategories (analogous to how knowledge and mind tools bypass filtering).
+     */
+    loadRequestToolProject(project: ToolProject): void;
+    /**
+     * Search registered tools using BM25. Returns parsed search results ranked by relevance.
+     * Useful for inspecting what tools are available and verifiable in tests.
+     */
+    searchTools(query: string, category?: string): {
+        found: number;
+        tools: {
+            name: string;
+            description: string;
+            category: string;
+        }[];
+    };
+    /**
+     * Get all registered tool names. Useful for verifying tool registration in tests.
+     */
+    getRegisteredToolNames(): string[];
     /**
      * Expose Toolpack's built-in tools as an MCP server.
      *
@@ -3939,7 +3987,38 @@ interface McpServerCapabilities {
     prompts?: Record<string, any>;
 }
 
-declare function createSkillInterceptor(options?: SkillInterceptorOptions): ToolpackInterceptor;
+/**
+ * BM25 (Best Matching 25) search engine.
+ *
+ * A lightweight, zero-dependency implementation of the BM25 ranking algorithm.
+ * Parameters: k1=1.5, b=0.75 (standard BM25 defaults).
+ */
+interface BM25SearchResult {
+    id: string;
+    score: number;
+}
+declare class BM25Engine {
+    private documents;
+    private termFrequencies;
+    private documentLengths;
+    private avgDocLength;
+    private readonly k1;
+    private readonly b;
+    constructor(k1?: number, b?: number);
+    private tokenize;
+    addDocument(id: string, content: string): void;
+    clear(): void;
+    get size(): number;
+    private updateAvgDocLength;
+    private idf;
+    search(query: string, limit?: number): BM25SearchResult[];
+}
+
+/**
+ * Parse a .skill.md file from its string content and absolute file path.
+ * Returns a Skill object. Category is derived from subfolder between rootDir and file.
+ */
+declare function parseSkillFile(content: string, filePath: string, rootDir: string): Skill;
 
 declare class RuleLoader {
     private readonly cacheTtlMs;
@@ -3953,4 +4032,4 @@ declare class RuleLoader {
     private readFile;
 }
 
-export { AGENT_MODE, AGENT_PLANNING_PROMPT, AGENT_WORKFLOW, AIClient, type AIClientConfig, type AddBypassRuleOptions, AnthropicAdapter, AnthropicVertexAdapter, type AnthropicVertexConfig, 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, type McpAgentDefinition, type McpAuthConfig, McpClient, type McpClientConfig, McpConnectionError, type McpCustomAuthConfig, type McpJwtAuthConfig, type McpServerCapabilities, type McpServerConfig, type McpServerExposeConfig, type McpServerHandle, type McpStaticAuthConfig, McpTimeoutError, type McpTool, McpToolManager, type McpToolsConfig, type McpTransport, 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, RuleLoader, 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 ToolAnnotations, 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 ToolpackCredentials, type ToolpackInitConfig, type ToolpackInterceptor, type ToolpackMcpServerConfig, 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, execRunBlockingTool, execRunShellTool, execRunTool, execTailOutputTool, 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 };
+export { AGENT_MODE, AGENT_PLANNING_PROMPT, AGENT_WORKFLOW, AIClient, type AIClientConfig, type AddBypassRuleOptions, AnthropicAdapter, AnthropicVertexAdapter, type AnthropicVertexConfig, type AssembledPrompt, type AssemblerOptions, AuthenticationError, BM25Engine, BM25SearchEngine, type BM25SearchResult, 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, FILE_LIMITS, type FilePart, 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, type McpAgentDefinition, type McpAuthConfig, McpClient, type McpClientConfig, McpConnectionError, type McpCustomAuthConfig, type McpJwtAuthConfig, type McpServerCapabilities, type McpServerConfig, type McpServerExposeConfig, type McpServerHandle, type McpStaticAuthConfig, McpTimeoutError, type McpTool, McpToolManager, type McpToolsConfig, type McpTransport, 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, RuleLoader, type RuntimeConfigStatus, SDKError, SQLiteConversationStore, type SQLiteConversationStoreConfig, type SearchHistoryEntry, type SearchOptions, type SearchResult, type Skill, 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 ToolAnnotations, 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 ToolpackCredentials, type ToolpackInitConfig, type ToolpackInterceptor, type ToolpackMcpServerConfig, 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, 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, execRunBlockingTool, execRunShellTool, execRunTool, execTailOutputTool, 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, parseSkillFile, 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 };

package/dist/index.d.ts

@@ -497,12 +497,6 @@ interface ModeConfig {
      * Shorthand for "no tool calls at all".
      */
     blockAllTools: boolean;
-    /**
-     * Whether to auto-inject relevant skill content into the system prompt
-     * via BM25 matching of the user's message (skill interceptor).
-     * Default: false — opt-in only. Set to true to enable auto-injection.
-     */
-    skillInterceptor?: boolean;
     /**
      * Root directory for rule files.
      * Auto-discovers:
@@ -579,7 +573,29 @@ interface ImageUrlPart {
     };
 }
 type ImagePart = ImageDataPart | ImageFilePart | ImageUrlPart;
-type MessageContent = string | (TextPart | ImagePart)[] | null;
+interface FilePart {
+    type: 'file';
+    file: {
+        /** Public or pre-signed bucket URL */
+        url: string;
+        /** MIME type, e.g. 'image/jpeg', 'application/pdf' */
+        mimeType: string;
+        /** Original filename, for display only */
+        name?: string;
+        /** File size in bytes — used for client-side validation */
+        size?: number;
+    };
+}
+declare const FILE_LIMITS: {
+    readonly image: {
+        readonly maxBytes: number;
+    };
+    readonly document: {
+        readonly maxBytes: number;
+        readonly maxPages: 20;
+    };
+};
+type MessageContent = string | (TextPart | ImagePart | FilePart)[] | null;
 type MediaUploadStrategy = 'inline' | 'upload' | 'auto';
 interface MediaOptions {
     /** How to handle image payloads */
@@ -2035,9 +2051,10 @@ declare class ToolDiscoveryCache {
 declare const TOOL_SEARCH_NAME = "tool.search";
 declare const toolSearchDefinition: ToolDefinition;
 /**
- * Get the tool.search schema (without execute function).
+ * Get the tool.search schema, optionally with a dynamic category enum
+ * derived from the currently registered tool categories.
  */
-declare function getToolSearchSchema(): ToolSchema;
+declare function getToolSearchSchema(categories?: string[]): ToolSchema;
 /**
  * Check if a tool name is the tool.search meta-tool.
  */
@@ -2548,12 +2565,6 @@ interface Skill {
     examples?: string;
     lastModified: number;
 }
-interface SkillInterceptorOptions {
-    dir?: string;
-    maxSkills?: number;
-    minScore?: number;
-    onValidationError?: SkillValidationMode;
-}
 interface SkillToolsOptions {
     /** Skills directory. Default: '.toolpack/skills' */
     dir?: string;
@@ -2674,11 +2685,6 @@ declare function createMode(config: {
             enabled: boolean;
         };
     };
-    /**
-     * Enable auto-injection of BM25-matched skill content into the system prompt.
-     * Default: false — opt-in only.
-     */
-    skillInterceptor?: boolean;
     /**
      * Root directory for rule files for this mode.
      * Auto-discovers __global__/ and <mode-name>/ subfolders within it.
@@ -3156,6 +3162,12 @@ interface ToolpackInitConfig {
     region?: string;
     /** Load built-in tools (fs, http, etc.)? Default: false */
     tools?: boolean;
+    /**
+     * Tool projects that override built-in tools by name.
+     * Loaded after built-ins, so any tool with the same name replaces the built-in version.
+     * Also used to extend the tool.search category enum dynamically.
+     */
+    toolOverrides?: ToolProject[];
     /** Context window management configuration for automatic conversation pruning/summarization */
     contextWindow?: ContextWindowConfig;
     /**
@@ -3268,8 +3280,18 @@ declare class Toolpack extends EventEmitter {
     customProviderNames: Set<string>;
     private mcpToolProject;
     private _interceptors;
+    private _instanceRequestTools;
     private constructor();
-    private buildKnowledgeRequestTools;
+    private _buildKnowledgeRequestTools;
+    /**
+     * Register tools that bypass mode filtering and are always available to the model.
+     * Use this for tools that must be accessible regardless of allowedToolCategories —
+     * the same mechanism used by knowledge, skill, and scheduler tools internally.
+     *
+     * Prefer `loadRequestToolProject` when you have a ToolProject; call this directly
+     * when you have a plain RequestToolDefinition array.
+     */
+    registerRequestTools(tools: RequestToolDefinition[]): void;
     private prepareRequest;
     /**
      * Initialize the Toolpack SDK.
@@ -3327,6 +3349,32 @@ declare class Toolpack extends EventEmitter {
      * Validates dependencies and registers all tools.
      */
     loadToolProject(project: ToolProject): Promise<void>;
+    /**
+     * Load multiple tool projects at runtime, rebuilding the BM25 index once after all are registered.
+     */
+    loadToolProjects(projects: ToolProject[]): Promise<void>;
+    /**
+     * Register a tool project's tools as request tools, bypassing mode filtering entirely.
+     * Use this instead of loadToolProject when the tools must always be available regardless
+     * of allowedToolCategories (analogous to how knowledge and mind tools bypass filtering).
+     */
+    loadRequestToolProject(project: ToolProject): void;
+    /**
+     * Search registered tools using BM25. Returns parsed search results ranked by relevance.
+     * Useful for inspecting what tools are available and verifiable in tests.
+     */
+    searchTools(query: string, category?: string): {
+        found: number;
+        tools: {
+            name: string;
+            description: string;
+            category: string;
+        }[];
+    };
+    /**
+     * Get all registered tool names. Useful for verifying tool registration in tests.
+     */
+    getRegisteredToolNames(): string[];
     /**
      * Expose Toolpack's built-in tools as an MCP server.
      *
@@ -3939,7 +3987,38 @@ interface McpServerCapabilities {
     prompts?: Record<string, any>;
 }
 
-declare function createSkillInterceptor(options?: SkillInterceptorOptions): ToolpackInterceptor;
+/**
+ * BM25 (Best Matching 25) search engine.
+ *
+ * A lightweight, zero-dependency implementation of the BM25 ranking algorithm.
+ * Parameters: k1=1.5, b=0.75 (standard BM25 defaults).
+ */
+interface BM25SearchResult {
+    id: string;
+    score: number;
+}
+declare class BM25Engine {
+    private documents;
+    private termFrequencies;
+    private documentLengths;
+    private avgDocLength;
+    private readonly k1;
+    private readonly b;
+    constructor(k1?: number, b?: number);
+    private tokenize;
+    addDocument(id: string, content: string): void;
+    clear(): void;
+    get size(): number;
+    private updateAvgDocLength;
+    private idf;
+    search(query: string, limit?: number): BM25SearchResult[];
+}
+
+/**
+ * Parse a .skill.md file from its string content and absolute file path.
+ * Returns a Skill object. Category is derived from subfolder between rootDir and file.
+ */
+declare function parseSkillFile(content: string, filePath: string, rootDir: string): Skill;
 
 declare class RuleLoader {
     private readonly cacheTtlMs;
@@ -3953,4 +4032,4 @@ declare class RuleLoader {
     private readFile;
 }
 
-export { AGENT_MODE, AGENT_PLANNING_PROMPT, AGENT_WORKFLOW, AIClient, type AIClientConfig, type AddBypassRuleOptions, AnthropicAdapter, AnthropicVertexAdapter, type AnthropicVertexConfig, 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, type McpAgentDefinition, type McpAuthConfig, McpClient, type McpClientConfig, McpConnectionError, type McpCustomAuthConfig, type McpJwtAuthConfig, type McpServerCapabilities, type McpServerConfig, type McpServerExposeConfig, type McpServerHandle, type McpStaticAuthConfig, McpTimeoutError, type McpTool, McpToolManager, type McpToolsConfig, type McpTransport, 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, RuleLoader, 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 ToolAnnotations, 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 ToolpackCredentials, type ToolpackInitConfig, type ToolpackInterceptor, type ToolpackMcpServerConfig, 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, execRunBlockingTool, execRunShellTool, execRunTool, execTailOutputTool, 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 };
+export { AGENT_MODE, AGENT_PLANNING_PROMPT, AGENT_WORKFLOW, AIClient, type AIClientConfig, type AddBypassRuleOptions, AnthropicAdapter, AnthropicVertexAdapter, type AnthropicVertexConfig, type AssembledPrompt, type AssemblerOptions, AuthenticationError, BM25Engine, BM25SearchEngine, type BM25SearchResult, 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, FILE_LIMITS, type FilePart, 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, type McpAgentDefinition, type McpAuthConfig, McpClient, type McpClientConfig, McpConnectionError, type McpCustomAuthConfig, type McpJwtAuthConfig, type McpServerCapabilities, type McpServerConfig, type McpServerExposeConfig, type McpServerHandle, type McpStaticAuthConfig, McpTimeoutError, type McpTool, McpToolManager, type McpToolsConfig, type McpTransport, 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, RuleLoader, type RuntimeConfigStatus, SDKError, SQLiteConversationStore, type SQLiteConversationStoreConfig, type SearchHistoryEntry, type SearchOptions, type SearchResult, type Skill, 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 ToolAnnotations, 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 ToolpackCredentials, type ToolpackInitConfig, type ToolpackInterceptor, type ToolpackMcpServerConfig, 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, 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, execRunBlockingTool, execRunShellTool, execRunTool, execTailOutputTool, 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, parseSkillFile, 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 };