toolpack-sdk 2.2.0 → 2.3.0

package/dist/index.d.ts

@@ -3,6 +3,263 @@ import { EventEmitter } from 'events';
 import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
 export { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
 
+interface PlanStep {
+    /** Unique step ID */
+    id: string;
+    /** Step number (1-indexed) */
+    number: number;
+    /** Human-readable description */
+    description: string;
+    /** Expected tools to be used (optional, for validation) */
+    expectedTools?: string[];
+    /** Dependencies on other step IDs (must complete first) */
+    dependsOn?: string[];
+    /** Step status */
+    status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped';
+    /** Result after completion */
+    result?: {
+        success: boolean;
+        output?: string;
+        error?: string;
+        toolsUsed?: string[];
+        duration?: number;
+        response?: CompletionResponse;
+    };
+}
+interface Plan {
+    /** Unique plan ID */
+    id: string;
+    /** Original user request */
+    request: string;
+    /** Plan summary/goal */
+    summary: string;
+    /** Ordered steps */
+    steps: PlanStep[];
+    /** Plan status */
+    status: 'draft' | 'approved' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+    /** Timestamps */
+    createdAt: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+    /** Raw response from the planning phase */
+    planningResponse?: CompletionResponse;
+    /** Metrics */
+    metrics?: {
+        totalDuration: number;
+        stepsCompleted: number;
+        stepsFailed: number;
+        retriesUsed: number;
+    };
+}
+
+interface WorkflowConfig {
+    /**
+     * Workflow name for display purposes.
+     */
+    name?: string;
+    /**
+     * Planning phase configuration.
+     * If enabled, AI generates a plan before executing.
+     */
+    planning?: {
+        /** Enable planning phase. Default: false */
+        enabled: boolean;
+        /** Pause for user approval before executing plan. Default: false */
+        requireApproval?: boolean;
+        /** Custom system prompt for plan generation. */
+        planningPrompt?: string;
+        /** Maximum number of steps allowed in a plan. Default: 20 */
+        maxSteps?: number;
+    };
+    /**
+     * Progress reporting configuration.
+     */
+    progress?: {
+        /** Emit progress events. Default: true */
+        enabled: boolean;
+        /** Report estimated completion percentage. Default: true */
+        reportPercentage?: boolean;
+    };
+    /**
+     * Query complexity routing configuration.
+     * Routes simple queries to faster execution paths based on query classification.
+     */
+    complexityRouting?: {
+        /** Enable complexity-based routing. Default: false (opt-in) */
+        enabled: boolean;
+        /** Routing strategy for simple queries. Default: 'single-step' */
+        strategy: 'single-step' | 'bypass' | 'disabled';
+        /** Confidence threshold for routing analytical queries. Default: 0.6 */
+        confidenceThreshold?: number;
+    };
+}
+/**
+ * Default workflow config (direct execution, no planning).
+ */
+declare const DEFAULT_WORKFLOW_CONFIG: WorkflowConfig;
+interface WorkflowEvents {
+    /** Emitted when a plan is created (before approval if required) */
+    'workflow:plan_created': (plan: Plan) => void;
+    /** Emitted when user approves/rejects a plan */
+    'workflow:plan_decision': (plan: Plan, approved: boolean) => void;
+    /** Emitted when plan execution starts */
+    'workflow:started': (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;
+    totalSteps: number;
+    percentage: number;
+    currentStepDescription: string;
+    status: 'planning' | 'awaiting_approval' | 'executing' | 'completed' | 'failed';
+}
+interface WorkflowResult {
+    success: boolean;
+    plan: Plan;
+    output?: string;
+    error?: string;
+    response?: CompletionResponse;
+    metrics: {
+        totalDuration: number;
+        stepsCompleted: number;
+        stepsFailed: number;
+        retriesUsed: number;
+    };
+}
+
+/**
+ * Configuration for an AI agent mode.
+ * A mode shapes AI behavior by controlling which tools are available
+ * and injecting a persona-specific system prompt.
+ */
+interface ModeConfig {
+    /** Unique identifier for the mode (e.g., "all", "ask", "code") */
+    name: string;
+    /** Human-readable display name (e.g., "All", "Ask", "Code") */
+    displayName: string;
+    /** Short description for UI tooltips */
+    description: string;
+    /**
+     * System prompt prepended to every request in this mode.
+     * Empty string means no system prompt injection (passthrough).
+     */
+    systemPrompt: string;
+    /**
+     * Base agent context configuration for this mode.
+     * Controls whether working directory and tool categories are injected into system prompt.
+     *
+     * - undefined: Use global default behavior (include everything)
+     * - false: Disable base context entirely
+     * - object: Fine-grained control over what is included
+     */
+    baseContext?: {
+        /** Include working directory in system prompt. Default: true */
+        includeWorkingDirectory?: boolean;
+        /** Include available tool categories. Default: true */
+        includeToolCategories?: boolean;
+        /** Custom base context string (overrides auto-generated). */
+        custom?: string;
+    } | false;
+    /** Workflow configuration controlling planning, steps, and progress. */
+    workflow?: WorkflowConfig;
+    /**
+     * Tool search configuration specific to this mode.
+     * Overrides or extends the global toolSearch config.
+     */
+    toolSearch?: {
+        /** Enable/disable tool search for this mode */
+        enabled?: boolean;
+        /** Tools to always include (never defer) for this mode */
+        alwaysLoadedTools?: string[];
+        /** Categories to always include for this mode */
+        alwaysLoadedCategories?: string[];
+    };
+    /**
+     * Tool categories allowed in this mode.
+     * Empty array means all categories are allowed (unless blocked).
+     */
+    allowedToolCategories: string[];
+    /**
+     * Tool categories explicitly blocked in this mode.
+     * Takes precedence over allowedToolCategories.
+     */
+    blockedToolCategories: string[];
+    /**
+     * Specific tool names allowed in this mode.
+     * Empty array means all tools are allowed (unless blocked).
+     */
+    allowedTools: string[];
+    /**
+     * Specific tool names explicitly blocked in this mode.
+     * Takes precedence over allowedTools.
+     */
+    blockedTools: string[];
+    /**
+     * If true, ALL tools are blocked regardless of other settings.
+     * Shorthand for "no tool calls at all".
+     */
+    blockAllTools: boolean;
+    /**
+     * Response format constraint for all requests in this mode.
+     * - 'json_object': instructs the model to return valid JSON as its text content.
+     *   Useful for evaluator/parser agents whose final response must be machine-readable.
+     *   Tool-call rounds are unaffected — the model still returns functionCall parts
+     *   normally; the format only applies to text content.
+     * - 'text' (default): plain text, no constraint.
+     */
+    response_format?: 'text' | 'json_object';
+}
+/**
+ * A lightweight reference to a mode, used in tool-blocked hints.
+ */
+interface ModeBlockedHint {
+    blockedToolNames: string[];
+    suggestedMode: string;
+}
+
 /**
  * Core type definitions for the Tool Calling System.
  */
@@ -319,6 +576,18 @@ interface CompletionRequest<T = unknown> {
      * Useful for agents that should only ever make one tool call (e.g. routers).
      */
     maxToolRounds?: number;
+    /**
+     * Per-request mode override. Snapshotted for the entire duration of the
+     * request — concurrent `setMode()` calls (e.g. from another agent sharing
+     * this Toolpack instance during awaited delegation) cannot affect an
+     * in-flight request's system prompt, tool filtering, or response format.
+     *
+     * - `ModeConfig` — use this mode for the request
+     * - `string`     — mode name, resolved from Toolpack's mode registry
+     * - `null`       — explicitly run without a mode
+     * - omitted      — snapshot the instance's active mode at request start
+     */
+    mode?: ModeConfig | string | null;
 }
 interface Usage {
     prompt_tokens: number;
@@ -731,358 +1000,101 @@ declare class ToolRegistry {
     private projects;
     private config;
     /**
-     * Register a tool (built-in or custom).
-     */
-    register(tool: ToolDefinition): void;
-    /**
-     * Register a custom tool provided by the consumer.
-     * Identical to register() but semantically distinct for clarity.
-     */
-    registerCustom(tool: ToolDefinition): void;
-    /**
-     * Get a tool by name.
-     */
-    get(name: string): ToolDefinition | undefined;
-    /**
-     * Check if a tool exists.
-     */
-    has(name: string): boolean;
-    /**
-     * Get all registered tool names.
-     */
-    getNames(): string[];
-    /**
-     * Get all tools in a specific category.
-     */
-    getByCategory(category: string): ToolDefinition[];
-    /**
-     * Get all enabled tools based on config.
-     * If enabledTools and enabledToolCategories are both empty, returns all registered tools.
-     * Otherwise, returns only tools from enabledTools[] + enabledToolCategories[].
-     */
-    getEnabled(): ToolDefinition[];
-    /**
-     * Get tool schemas suitable for sending to AI providers.
-     * If toolNames is provided, only return schemas for those tools.
-     * Otherwise, return schemas for all enabled tools.
-     */
-    getSchemas(toolNames?: string[]): ToolSchema[];
-    /**
-     * Get all tools matching a list of names.
-     */
-    getByNames(names: string[]): ToolDefinition[];
-    /**
-     * Get all tools matching a list of categories.
-     */
-    getByCategories(categories: string[]): ToolDefinition[];
-    /**
-     * Get all registered categories (derived from tools).
-     */
-    getCategories(): string[];
-    /**
-     * Get all registered tools.
-     * Used by BM25SearchEngine for indexing.
-     */
-    getAll(): ToolDefinition[];
-    /**
-     * Update the config (called by config loader).
-     */
-    setConfig(config: ToolsConfig): void;
-    /**
-     * Get the current config.
-     */
-    getConfig(): ToolsConfig;
-    /**
-     * Get the total number of registered tools.
-     */
-    get size(): number;
-    /**
-     * Validate that a tool project's declared dependencies are resolvable.
-     * Returns an array of missing package names (empty = all good).
-     */
-    validateDependencies(project: ToolProject): Promise<string[]>;
-    /**
-     * Load a single tool project into the registry.
-     * Validates dependencies before loading — throws if any are missing.
-     */
-    loadProject(project: ToolProject): Promise<void>;
-    /**
-     * Load multiple tool projects.
-     */
-    loadProjects(projects: ToolProject[]): Promise<void>;
-    /**
-     * Get a loaded project by name.
-     */
-    getProject(name: string): ToolProject | undefined;
-    /**
-     * Get all loaded projects.
-     */
-    getProjects(): ToolProject[];
-    /**
-     * Get all loaded project names.
-     */
-    getProjectNames(): string[];
-    /**
-     * Load all built-in tool projects.
-     */
-    loadBuiltIn(): Promise<void>;
-}
-
-interface PlanStep {
-    /** Unique step ID */
-    id: string;
-    /** Step number (1-indexed) */
-    number: number;
-    /** Human-readable description */
-    description: string;
-    /** Expected tools to be used (optional, for validation) */
-    expectedTools?: string[];
-    /** Dependencies on other step IDs (must complete first) */
-    dependsOn?: string[];
-    /** Step status */
-    status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped';
-    /** Result after completion */
-    result?: {
-        success: boolean;
-        output?: string;
-        error?: string;
-        toolsUsed?: string[];
-        duration?: number;
-        response?: CompletionResponse;
-    };
-}
-interface Plan {
-    /** Unique plan ID */
-    id: string;
-    /** Original user request */
-    request: string;
-    /** Plan summary/goal */
-    summary: string;
-    /** Ordered steps */
-    steps: PlanStep[];
-    /** Plan status */
-    status: 'draft' | 'approved' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
-    /** Timestamps */
-    createdAt: Date;
-    startedAt?: Date;
-    completedAt?: Date;
-    /** Raw response from the planning phase */
-    planningResponse?: CompletionResponse;
-    /** Metrics */
-    metrics?: {
-        totalDuration: number;
-        stepsCompleted: number;
-        stepsFailed: number;
-        retriesUsed: number;
-    };
-}
-
-interface WorkflowConfig {
-    /**
-     * Workflow name for display purposes.
+     * Register a tool (built-in or custom).
      */
-    name?: string;
+    register(tool: ToolDefinition): void;
     /**
-     * Planning phase configuration.
-     * If enabled, AI generates a plan before executing.
+     * Register a custom tool provided by the consumer.
+     * Identical to register() but semantically distinct for clarity.
      */
-    planning?: {
-        /** Enable planning phase. Default: false */
-        enabled: boolean;
-        /** Pause for user approval before executing plan. Default: false */
-        requireApproval?: boolean;
-        /** Custom system prompt for plan generation. */
-        planningPrompt?: string;
-        /** Maximum number of steps allowed in a plan. Default: 20 */
-        maxSteps?: number;
-    };
+    registerCustom(tool: ToolDefinition): void;
     /**
-     * Progress reporting configuration.
+     * Get a tool by name.
      */
-    progress?: {
-        /** Emit progress events. Default: true */
-        enabled: boolean;
-        /** Report estimated completion percentage. Default: true */
-        reportPercentage?: boolean;
-    };
+    get(name: string): ToolDefinition | undefined;
     /**
-     * Query complexity routing configuration.
-     * Routes simple queries to faster execution paths based on query classification.
+     * Check if a tool exists.
      */
-    complexityRouting?: {
-        /** Enable complexity-based routing. Default: false (opt-in) */
-        enabled: boolean;
-        /** Routing strategy for simple queries. Default: 'single-step' */
-        strategy: 'single-step' | 'bypass' | 'disabled';
-        /** Confidence threshold for routing analytical queries. Default: 0.6 */
-        confidenceThreshold?: number;
-    };
-}
-/**
- * Default workflow config (direct execution, no planning).
- */
-declare const DEFAULT_WORKFLOW_CONFIG: WorkflowConfig;
-interface WorkflowEvents {
-    /** Emitted when a plan is created (before approval if required) */
-    'workflow:plan_created': (plan: Plan) => void;
-    /** Emitted when user approves/rejects a plan */
-    'workflow:plan_decision': (plan: Plan, approved: boolean) => void;
-    /** Emitted when plan execution starts */
-    'workflow:started': (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;
-    totalSteps: number;
-    percentage: number;
-    currentStepDescription: string;
-    status: 'planning' | 'awaiting_approval' | 'executing' | 'completed' | 'failed';
-}
-interface WorkflowResult {
-    success: boolean;
-    plan: Plan;
-    output?: string;
-    error?: string;
-    response?: CompletionResponse;
-    metrics: {
-        totalDuration: number;
-        stepsCompleted: number;
-        stepsFailed: number;
-        retriesUsed: number;
-    };
-}
-
-/**
- * Configuration for an AI agent mode.
- * A mode shapes AI behavior by controlling which tools are available
- * and injecting a persona-specific system prompt.
- */
-interface ModeConfig {
-    /** Unique identifier for the mode (e.g., "all", "ask", "code") */
-    name: string;
-    /** Human-readable display name (e.g., "All", "Ask", "Code") */
-    displayName: string;
-    /** Short description for UI tooltips */
-    description: string;
+    has(name: string): boolean;
     /**
-     * System prompt prepended to every request in this mode.
-     * Empty string means no system prompt injection (passthrough).
+     * Get all registered tool names.
      */
-    systemPrompt: string;
+    getNames(): string[];
     /**
-     * Base agent context configuration for this mode.
-     * Controls whether working directory and tool categories are injected into system prompt.
-     *
-     * - undefined: Use global default behavior (include everything)
-     * - false: Disable base context entirely
-     * - object: Fine-grained control over what is included
+     * Get all tools in a specific category.
      */
-    baseContext?: {
-        /** Include working directory in system prompt. Default: true */
-        includeWorkingDirectory?: boolean;
-        /** Include available tool categories. Default: true */
-        includeToolCategories?: boolean;
-        /** Custom base context string (overrides auto-generated). */
-        custom?: string;
-    } | false;
-    /** Workflow configuration controlling planning, steps, and progress. */
-    workflow?: WorkflowConfig;
+    getByCategory(category: string): ToolDefinition[];
     /**
-     * Tool search configuration specific to this mode.
-     * Overrides or extends the global toolSearch config.
+     * Get all enabled tools based on config.
+     * If enabledTools and enabledToolCategories are both empty, returns all registered tools.
+     * Otherwise, returns only tools from enabledTools[] + enabledToolCategories[].
      */
-    toolSearch?: {
-        /** Enable/disable tool search for this mode */
-        enabled?: boolean;
-        /** Tools to always include (never defer) for this mode */
-        alwaysLoadedTools?: string[];
-        /** Categories to always include for this mode */
-        alwaysLoadedCategories?: string[];
-    };
+    getEnabled(): ToolDefinition[];
     /**
-     * Tool categories allowed in this mode.
-     * Empty array means all categories are allowed (unless blocked).
+     * Get tool schemas suitable for sending to AI providers.
+     * If toolNames is provided, only return schemas for those tools.
+     * Otherwise, return schemas for all enabled tools.
      */
-    allowedToolCategories: string[];
+    getSchemas(toolNames?: string[]): ToolSchema[];
     /**
-     * Tool categories explicitly blocked in this mode.
-     * Takes precedence over allowedToolCategories.
+     * Get all tools matching a list of names.
      */
-    blockedToolCategories: string[];
+    getByNames(names: string[]): ToolDefinition[];
     /**
-     * Specific tool names allowed in this mode.
-     * Empty array means all tools are allowed (unless blocked).
+     * Get all tools matching a list of categories.
      */
-    allowedTools: string[];
+    getByCategories(categories: string[]): ToolDefinition[];
     /**
-     * Specific tool names explicitly blocked in this mode.
-     * Takes precedence over allowedTools.
+     * Get all registered categories (derived from tools).
      */
-    blockedTools: string[];
+    getCategories(): string[];
     /**
-     * If true, ALL tools are blocked regardless of other settings.
-     * Shorthand for "no tool calls at all".
+     * Get all registered tools.
+     * Used by BM25SearchEngine for indexing.
      */
-    blockAllTools: boolean;
+    getAll(): ToolDefinition[];
     /**
-     * Response format constraint for all requests in this mode.
-     * - 'json_object': instructs the model to return valid JSON as its text content.
-     *   Useful for evaluator/parser agents whose final response must be machine-readable.
-     *   Tool-call rounds are unaffected — the model still returns functionCall parts
-     *   normally; the format only applies to text content.
-     * - 'text' (default): plain text, no constraint.
+     * Update the config (called by config loader).
      */
-    response_format?: 'text' | 'json_object';
-}
-/**
- * A lightweight reference to a mode, used in tool-blocked hints.
- */
-interface ModeBlockedHint {
-    blockedToolNames: string[];
-    suggestedMode: string;
+    setConfig(config: ToolsConfig): void;
+    /**
+     * Get the current config.
+     */
+    getConfig(): ToolsConfig;
+    /**
+     * Get the total number of registered tools.
+     */
+    get size(): number;
+    /**
+     * Validate that a tool project's declared dependencies are resolvable.
+     * Returns an array of missing package names (empty = all good).
+     */
+    validateDependencies(project: ToolProject): Promise<string[]>;
+    /**
+     * Load a single tool project into the registry.
+     * Validates dependencies before loading — throws if any are missing.
+     */
+    loadProject(project: ToolProject): Promise<void>;
+    /**
+     * Load multiple tool projects.
+     */
+    loadProjects(projects: ToolProject[]): Promise<void>;
+    /**
+     * Get a loaded project by name.
+     */
+    getProject(name: string): ToolProject | undefined;
+    /**
+     * Get all loaded projects.
+     */
+    getProjects(): ToolProject[];
+    /**
+     * Get all loaded project names.
+     */
+    getProjectNames(): string[];
+    /**
+     * Load all built-in tool projects.
+     */
+    loadBuiltIn(): Promise<void>;
 }
 
 type ConfirmationLevel = 'high' | 'medium';
@@ -1342,6 +1354,11 @@ declare class AIClient extends EventEmitter {
      * Enrich a request with tools based on the router config.
      * Applies mode-based tool filtering when an active mode is set.
      */
+    /**
+     * @param mode Mode snapshot taken at request start. Passed explicitly (not
+     * read from `this.activeMode`) so that per-round re-enrichment inside the
+     * tool loop is immune to concurrent `setMode()` calls on this instance.
+     */
     private enrichRequestWithTools;
     private buildRequestToolMap;
     private requestToolToSchema;
@@ -1350,13 +1367,24 @@ declare class AIClient extends EventEmitter {
     private mergeToolCallRequests;
     private injectRequestToolGuidance;
     private stripRequestTools;
+    /**
+     * Resolve the mode snapshot for a request.
+     *
+     * - `request.mode` omitted → snapshot the instance's activeMode now
+     * - `request.mode === null` → explicitly no mode
+     * - `request.mode` is a ModeConfig → use it directly
+     * - `request.mode` is a string → mode names are resolved by Toolpack (which
+     *   owns the mode registry) before reaching the client; if an unresolved
+     *   name gets here, warn and fall back to the activeMode snapshot
+     */
+    private resolveRequestMode;
     /**
      * Filter tool schemas based on mode permissions.
      * blockedTools/blockedToolCategories always take precedence.
      */
     private filterSchemasByMode;
     /**
-     * Inject the active mode's system prompt into the request messages.
+     * Inject the given mode's system prompt into the request messages.
      * For the "All" mode (empty systemPrompt), this is a no-op.
      */
     private injectModeSystemPrompt;
@@ -1390,7 +1418,7 @@ declare class AIClient extends EventEmitter {
     /**
      * Execute tool.search using BM25 engine.
      */
-    executeToolSearch(args: Record<string, any>): string;
+    executeToolSearch(args: Record<string, any>, mode?: ModeConfig | null): string;
     private wrapError;
     /**
      * Truncate a tool result to fit within the remaining round budget.
@@ -3040,6 +3068,13 @@ declare class Toolpack extends EventEmitter {
      */
     private static createProvider;
     generate(request: CompletionRequest | string, providerName?: string): Promise<CompletionResponse>;
+    /**
+     * Resolve a string `mode` on the request to its registered ModeConfig.
+     * The AIClient cannot resolve names (the mode registry lives here), so
+     * names must be resolved before the request reaches the client.
+     * Throws for unknown names — same contract as setMode().
+     */
+    private resolveRequestModeName;
     private _buildInterceptorChain;
     stream(request: CompletionRequest, providerName?: string): AsyncGenerator<CompletionChunk>;
     embed(request: EmbeddingRequest, providerName?: string): Promise<EmbeddingResponse>;