toolpack-sdk 2.1.1 → 2.3.0

package/dist/index.d.cts

@@ -1,4 +1,264 @@
+import * as zod from 'zod';
 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.
@@ -26,6 +286,45 @@ interface ToolContext {
     /** Scoped logger — writes to toolpack-sdk.log */
     log: (message: string) => void;
 }
+/**
+ * Hints about tool behaviour sent to MCP clients in tools/list.
+ * All fields are optional — clients use them for safety UX (e.g. confirmation
+ * dialogs before destructive actions) but must not rely on them for security.
+ *
+ * MCP spec defaults when annotations are omitted entirely:
+ *   readOnlyHint: false, destructiveHint: true, openWorldHint: true, idempotentHint: false
+ *
+ * The MCP server auto-derives annotations when this field is not set:
+ *   - confirmation present → { destructiveHint: true }
+ *   - neither set          → annotations omitted (MCP spec defaults apply)
+ * Set explicitly to override.
+ */
+interface ToolAnnotations {
+    /**
+     * Tool only reads data — never writes, calls APIs, or modifies state.
+     * MCP spec default (when absent): false.
+     * Set to true for pure read tools: fs.read_file, search, list-dir.
+     */
+    readOnlyHint?: boolean;
+    /**
+     * Tool may cause irreversible side-effects (delete, overwrite, deploy, send).
+     * MCP spec default (when absent): true — clients assume worst case.
+     * Set to false for safe write operations (e.g. create-if-not-exists).
+     */
+    destructiveHint?: boolean;
+    /**
+     * Calling the tool multiple times with the same args has no additional effect.
+     * MCP spec default (when absent): false.
+     * Set to true for idempotent operations.
+     */
+    idempotentHint?: boolean;
+    /**
+     * Tool may interact with external systems: web, APIs, databases, shell, filesystem.
+     * MCP spec default (when absent): true.
+     * Set to false only for purely in-process, local tools with no side-effects.
+     */
+    openWorldHint?: boolean;
+}
 type ConfirmationLevel$1 = 'high' | 'medium';
 interface ToolConfirmation {
     level: ConfirmationLevel$1;
@@ -51,6 +350,15 @@ interface ToolDefinition {
      * Note: Only effective when onToolConfirm callback is provided to AIClient.
      */
     confirmation?: ToolConfirmation;
+    /**
+     * MCP annotation hints describing tool behaviour to clients.
+     * When omitted, the MCP server auto-derives from `confirmation`:
+     *   - confirmation set  → { destructiveHint: true }
+     *   - no confirmation   → annotations omitted (MCP spec defaults apply)
+     * Set explicitly to override — particularly useful for marking read-only tools
+     * (readOnlyHint: true) or idempotent tools (idempotentHint: true).
+     */
+    annotations?: ToolAnnotations;
 }
 /**
  * Schema-only version of ToolDefinition (no execute function).
@@ -68,6 +376,8 @@ interface ToolSchema {
      * Default: true
      */
     cacheable?: boolean;
+    /** MCP annotation hints. See ToolAnnotations for details. */
+    annotations?: ToolAnnotations;
 }
 interface ToolProjectManifest {
     key: string;
@@ -227,13 +537,30 @@ interface ToolCallResult {
     result?: string;
     duration?: number;
 }
-interface CompletionRequest {
+interface CompletionRequest<T = unknown> {
     messages: Message[];
     model: string;
     temperature?: number;
     max_tokens?: number;
     top_p?: number;
-    response_format?: 'text' | 'json_object';
+    /**
+     * Controls the output format:
+     * - `'text'`        — plain text (default)
+     * - `'json_object'` — unstructured JSON; you parse `response.content` yourself
+     * - `ZodType<T>`    — structured JSON matching the schema; parsed and validated result
+     *                     available in `response.data` as fully typed `T`
+     *
+     * @example structured output
+     * ```typescript
+     * import { z } from 'zod'
+     * const result = await sdk.generate({
+     *   messages,
+     *   response_format: z.object({ sentiment: z.string(), score: z.number() }),
+     * })
+     * result.data.sentiment // typed as string
+     * ```
+     */
+    response_format?: 'text' | 'json_object' | zod.ZodType<T>;
     stream?: boolean;
     tools?: ToolCallRequest[];
     requestTools?: RequestToolDefinition[];
@@ -249,14 +576,32 @@ interface CompletionRequest {
      * 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;
     completion_tokens?: number;
     total_tokens: number;
 }
-interface CompletionResponse {
+interface CompletionResponse<T = unknown> {
     content: string | null;
+    /**
+     * Parsed and validated structured output.
+     * Only present when `response_format` is a ZodType.
+     * TypeScript type is inferred from the schema via the generic on `generate<T>()`.
+     */
+    data?: T;
     usage?: Usage;
     /** Detailed breakdown of token usage when executed in agent/workflow mode */
     usage_details?: {
@@ -493,520 +838,263 @@ declare class ContextWindowExceededError extends SDKError {
     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 {
-    /**
-     * Provider name used for registration and routing.
-     * Custom adapters should set this in their constructor.
-     */
-    name?: string;
-    /**
-     * Generates a text completion for the given request.
-     */
-    abstract generate(request: CompletionRequest): Promise<CompletionResponse>;
-    /**
-     * Streams text completion chunks for the given request.
-     */
-    abstract stream(request: CompletionRequest): AsyncGenerator<CompletionChunk>;
-    /**
-     * Generates embeddings for the given input.
-     */
-    abstract embed(request: EmbeddingRequest): Promise<EmbeddingResponse>;
-    /**
-     * Optional: Provide image generation if supported.
-     * Defined as any for now to avoid circular deps or complex types in base.
-     */
-    /**
-     * Returns the list of models available from this provider.
-     * Override to provide a curated list or fetch from the provider's API.
-     *
-     * Default: returns an empty array.
-     */
-    getModels(): Promise<ProviderModelInfo[]>;
-    /**
-     * Returns a human-readable display name for this provider.
-     * Override to customize.
-     *
-     * Default: uses `this.name` if set, otherwise derives from class name.
-     */
-    getDisplayName(): string;
-    /**
-     * Check if this provider supports the file upload API natively.
-     */
-    supportsFileUpload(): boolean;
-    /**
-     * Upload a file to the provider (if supported).
-     * @throws InvalidRequestError if not supported by this provider.
-     */
-    uploadFile(_request: FileUploadRequest): Promise<FileUploadResponse>;
-    /**
-     * Delete an uploaded file (if supported).
-     * @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>;
-}
-
-/**
- * Central registry for all tools (built-in + custom).
- * Handles registration, lookup, filtering by category, schema extraction,
- * and loading tool projects.
- */
-declare class ToolRegistry {
-    private tools;
-    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).
+     * Get the number of tokens over the limit
      */
-    setConfig(config: ToolsConfig): void;
+    getOverageTokens(): number;
     /**
-     * Get the current config.
+     * Get the percentage of the context window being used
      */
-    getConfig(): ToolsConfig;
+    getUsagePercentage(): number;
     /**
-     * Get the total number of registered tools.
+     * Get a detailed error report
      */
-    get size(): number;
+    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);
     /**
-     * Validate that a tool project's declared dependencies are resolvable.
-     * Returns an array of missing package names (empty = all good).
+     * Get the token deficit
      */
-    validateDependencies(project: ToolProject): Promise<string[]>;
+    getDeficit(): number;
     /**
-     * Load a single tool project into the registry.
-     * Validates dependencies before loading — throws if any are missing.
+     * Whether the deficit could be recovered by adjusting the strategy
      */
-    loadProject(project: ToolProject): Promise<void>;
+    isRecoverable(): boolean;
     /**
-     * Load multiple tool projects.
+     * Get a detailed error report
      */
-    loadProjects(projects: ToolProject[]): Promise<void>;
+    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);
     /**
-     * Get a loaded project by name.
+     * Whether the error is retryable
      */
-    getProject(name: string): ToolProject | undefined;
+    isRetryable(): boolean;
     /**
-     * Get all loaded projects.
+     * Get suggested recovery action
      */
-    getProjects(): ToolProject[];
+    getSuggestedRecovery(): string;
     /**
-     * Get all loaded project names.
+     * Get a detailed error report
      */
-    getProjectNames(): string[];
+    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);
     /**
-     * Load all built-in tool projects.
+     * Get a detailed error report
      */
-    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;
-    };
+    getDetailedReport(): string;
 }
-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;
-    };
+/**
+ * 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;
+};
 
-interface WorkflowConfig {
+declare abstract class ProviderAdapter {
     /**
-     * Workflow name for display purposes.
+     * Provider name used for registration and routing.
+     * Custom adapters should set this in their constructor.
      */
     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.
+     * Generates a text completion for the given request.
      */
-    progress?: {
-        /** Emit progress events. Default: true */
-        enabled: boolean;
-        /** Report estimated completion percentage. Default: true */
-        reportPercentage?: boolean;
-    };
+    abstract generate(request: CompletionRequest): Promise<CompletionResponse>;
     /**
-     * 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;
-    };
+     * Streams text completion chunks for the given request.
+     */
+    abstract stream(request: CompletionRequest): AsyncGenerator<CompletionChunk>;
+    /**
+     * Generates embeddings for the given input.
+     */
+    abstract embed(request: EmbeddingRequest): Promise<EmbeddingResponse>;
+    /**
+     * Optional: Provide image generation if supported.
+     * Defined as any for now to avoid circular deps or complex types in base.
+     */
+    /**
+     * Returns the list of models available from this provider.
+     * Override to provide a curated list or fetch from the provider's API.
+     *
+     * Default: returns an empty array.
+     */
+    getModels(): Promise<ProviderModelInfo[]>;
+    /**
+     * Returns a human-readable display name for this provider.
+     * Override to customize.
+     *
+     * Default: uses `this.name` if set, otherwise derives from class name.
+     */
+    getDisplayName(): string;
+    /**
+     * Check if this provider supports the file upload API natively.
+     */
+    supportsFileUpload(): boolean;
+    /**
+     * Upload a file to the provider (if supported).
+     * @throws InvalidRequestError if not supported by this provider.
+     */
+    uploadFile(_request: FileUploadRequest): Promise<FileUploadResponse>;
+    /**
+     * Delete an uploaded file (if supported).
+     * @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>;
 }
 
 /**
- * Configuration for an AI agent mode.
- * A mode shapes AI behavior by controlling which tools are available
- * and injecting a persona-specific system prompt.
+ * Central registry for all tools (built-in + custom).
+ * Handles registration, lookup, filtering by category, schema extraction,
+ * and loading tool projects.
  */
-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;
+declare class ToolRegistry {
+    private tools;
+    private projects;
+    private config;
     /**
-     * System prompt prepended to every request in this mode.
-     * Empty string means no system prompt injection (passthrough).
+     * Register a tool (built-in or custom).
      */
-    systemPrompt: string;
+    register(tool: ToolDefinition): void;
     /**
-     * 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
+     * Register a custom tool provided by the consumer.
+     * Identical to register() but semantically distinct for clarity.
      */
-    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;
+    registerCustom(tool: ToolDefinition): void;
     /**
-     * Tool search configuration specific to this mode.
-     * Overrides or extends the global toolSearch config.
+     * Get a tool by name.
      */
-    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[];
-    };
+    get(name: string): ToolDefinition | undefined;
     /**
-     * Tool categories allowed in this mode.
-     * Empty array means all categories are allowed (unless blocked).
+     * Check if a tool exists.
      */
-    allowedToolCategories: string[];
+    has(name: string): boolean;
     /**
-     * Tool categories explicitly blocked in this mode.
-     * Takes precedence over allowedToolCategories.
+     * Get all registered tool names.
      */
-    blockedToolCategories: string[];
+    getNames(): string[];
     /**
-     * Specific tool names allowed in this mode.
-     * Empty array means all tools are allowed (unless blocked).
+     * Get all tools in a specific category.
      */
-    allowedTools: string[];
+    getByCategory(category: string): ToolDefinition[];
     /**
-     * Specific tool names explicitly blocked in this mode.
-     * Takes precedence over allowedTools.
+     * 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[].
      */
-    blockedTools: string[];
+    getEnabled(): ToolDefinition[];
     /**
-     * If true, ALL tools are blocked regardless of other settings.
-     * Shorthand for "no tool calls at all".
+     * 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.
      */
-    blockAllTools: boolean;
+    getSchemas(toolNames?: string[]): ToolSchema[];
     /**
-     * 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.
+     * Get all tools matching a list of names.
      */
-    response_format?: 'text' | 'json_object';
-}
-/**
- * A lightweight reference to a mode, used in tool-blocked hints.
- */
-interface ModeBlockedHint {
-    blockedToolNames: string[];
-    suggestedMode: string;
+    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>;
 }
 
 type ConfirmationLevel = 'high' | 'medium';
@@ -1251,7 +1339,7 @@ declare class AIClient extends EventEmitter {
      * When tools are enabled and autoExecute is true, handles the full
      * tool call → execute → send result → get final answer loop.
      */
-    generate(request: CompletionRequest, providerName?: string): Promise<CompletionResponse>;
+    generate<T = unknown>(request: CompletionRequest<T>, providerName?: string): Promise<CompletionResponse<T>>;
     /**
      * unified stream completion
      * When tools are enabled and autoExecute is true, handles tool calls
@@ -1266,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;
@@ -1274,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;
@@ -1314,7 +1418,7 @@ declare class AIClient extends EventEmitter {
     /**
      * Execute tool.search using BM25 engine.
      */
-    private executeToolSearch;
+    executeToolSearch(args: Record<string, any>, mode?: ModeConfig | null): string;
     private wrapError;
     /**
      * Truncate a tool result to fit within the remaining round budget.
@@ -2072,8 +2176,12 @@ declare const execRunShellTool: ToolDefinition;
 
 declare const execRunBackgroundTool: ToolDefinition;
 
+declare const execRunBlockingTool: ToolDefinition;
+
 declare const execReadOutputTool: ToolDefinition;
 
+declare const execTailOutputTool: ToolDefinition;
+
 declare const execKillTool: ToolDefinition;
 
 declare const execListProcessesTool: ToolDefinition;
@@ -2588,6 +2696,210 @@ type ToolpackInterceptor = {
     init?(): Promise<void>;
 };
 
+type McpTransport = 'stdio' | 'http';
+
+interface McpServerExposeConfig {
+    /** Expose only tools in these categories. Mutually exclusive with `tools`. */
+    categories?: string[];
+    /** Expose only these exact tool names. Mutually exclusive with `categories`. */
+    tools?: string[];
+}
+interface McpStaticAuthConfig {
+    mode: 'static';
+    /**
+     * One or more pre-shared bearer tokens that grant access.
+     * Generate with: crypto.randomBytes(32).toString('hex')
+     * All tokens in the array are valid — useful for token rotation.
+     */
+    tokens: string[];
+}
+interface McpJwtAuthConfig {
+    mode: 'jwt';
+    /**
+     * JWKS endpoint URL for JWT signature verification.
+     * @example 'https://your-tenant.auth0.com/.well-known/jwks.json'
+     * @example 'https://your-project.supabase.co/auth/v1/jwks'
+     */
+    jwksUrl: string;
+    /**
+     * Expected `aud` claim in the JWT.
+     * Required for most OIDC providers — omitting may accept tokens intended for other services.
+     */
+    audience?: string;
+    /**
+     * Expected `iss` claim in the JWT. Recommended.
+     * Also used to populate the `authorization_servers` field in
+     * /.well-known/oauth-protected-resource when serverUrl is set.
+     */
+    issuer?: string;
+    /** JWT must have all of these scopes. Checked after signature verification. */
+    requiredScopes?: string[];
+}
+interface McpCustomAuthConfig {
+    mode: 'custom';
+    /**
+     * Your own token verification logic.
+     * Throw any error to reject the token — the caller receives a 401.
+     * Return a valid AuthInfo on success.
+     *
+     * @example
+     * ```typescript
+     * verifyAccessToken: async (token) => {
+     *   const user = await db.findByToken(token);
+     *   if (!user) throw new Error('Invalid token');
+     *   return { token, clientId: user.id, scopes: user.scopes };
+     * }
+     * ```
+     */
+    verifyAccessToken(token: string): Promise<AuthInfo>;
+    /** Token must have all of these scopes. Checked after verifyAccessToken resolves. */
+    requiredScopes?: string[];
+}
+type McpAuthConfig = McpStaticAuthConfig | McpJwtAuthConfig | McpCustomAuthConfig;
+/**
+ * Minimal contract for exposing an agent as an MCP tool.
+ * Satisfied by McpChannel.asAgentDefinition() from toolpack-agents,
+ * or by any plain object with these four fields.
+ */
+interface McpAgentDefinition {
+    /** Exposed as "agent.<name>" in tools/list. Must be unique across all agents. */
+    name: string;
+    /** Shown to the MCP client as the tool description. */
+    description: string;
+    /** JSON Schema for the arguments the agent accepts. Defaults to empty object schema. */
+    inputSchema?: Record<string, unknown>;
+    /**
+     * Called when tools/call arrives for this agent.
+     * Must return the agent's output as a string.
+     * Throw to signal an error — the MCP client receives isError: true.
+     */
+    invoke(args: Record<string, unknown>): Promise<string>;
+}
+interface ToolpackMcpServerConfig {
+    /** Transport type. 'stdio' for Claude Desktop / Cursor. 'http' for remote use. */
+    transport: McpTransport;
+    /** Port for HTTP transport. Default: 3000. Only used when transport is 'http'. */
+    port?: number;
+    /** Filter which tools to expose. Exposes all enabled tools when omitted. */
+    expose?: McpServerExposeConfig;
+    /** Server name shown to MCP clients. Default: 'Toolpack SDK'. */
+    serverName?: string;
+    /** Server version shown to MCP clients. Default: '2.0.0'. */
+    serverVersion?: string;
+    /**
+     * Authentication for the HTTP transport. Ignored when transport is 'stdio'.
+     *
+     * When omitted, the HTTP server accepts all requests — safe for localhost only.
+     * When set, every request must carry a valid Bearer token; missing or invalid
+     * tokens are rejected with 401. Scope violations are rejected with 403.
+     *
+     * @example Static tokens (dev / self-hosted)
+     * ```typescript
+     * auth: { mode: 'static', tokens: [process.env.MCP_TOKEN!] }
+     * ```
+     *
+     * @example JWT with Auth0 / Supabase / Clerk
+     * ```typescript
+     * auth: {
+     *   mode: 'jwt',
+     *   jwksUrl: 'https://your-tenant.auth0.com/.well-known/jwks.json',
+     *   audience: 'https://your-mcp-server.example.com',
+     *   issuer:   'https://your-tenant.auth0.com/',
+     * }
+     * ```
+     *
+     * @example Custom verification
+     * ```typescript
+     * auth: {
+     *   mode: 'custom',
+     *   verifyAccessToken: async (token) => {
+     *     const user = await db.findByToken(token);
+     *     if (!user) throw new Error('invalid');
+     *     return { token, clientId: user.id, scopes: user.scopes };
+     *   }
+     * }
+     * ```
+     */
+    auth?: McpAuthConfig;
+    /**
+     * Agents to expose as MCP tools alongside regular tools.
+     * Each agent appears in tools/list as "agent.<name>".
+     *
+     * Agents run to completion before returning — synchronous from the MCP
+     * client's perspective. For long-running agents, ensure the MCP client's
+     * timeout is set appropriately.
+     *
+     * The easiest way to produce an entry is via McpChannel.asAgentDefinition()
+     * from toolpack-agents. A plain object with { name, description, invoke }
+     * also works — no import from toolpack-agents required.
+     *
+     * @example using McpChannel (toolpack-agents)
+     * ```typescript
+     * const ch = new McpChannel();
+     * const agent = new PrReviewerAgent({ channels: [ch] });
+     * await agent.start();
+     * await sdk.startMcpServer({
+     *   transport: 'stdio',
+     *   agents: [ch.asAgentDefinition(agent)],
+     * });
+     * ```
+     *
+     * @example plain object (no extra dependency)
+     * ```typescript
+     * await sdk.startMcpServer({
+     *   transport: 'stdio',
+     *   agents: [{
+     *     name: 'pr_reviewer',
+     *     description: 'Reviews a pull request end-to-end.',
+     *     inputSchema: { type: 'object', properties: { pr_url: { type: 'string' } }, required: ['pr_url'] },
+     *     invoke: async (args) => {
+     *       const result = await prReviewer.invokeAgent({ data: args });
+     *       return result.output;
+     *     },
+     *   }],
+     * });
+     * ```
+     */
+    agents?: McpAgentDefinition[];
+    /**
+     * Enable tool search mode.
+     *
+     * When true, tools/list returns only `tool.search` plus any always-loaded tools
+     * configured in ToolSearchConfig (alwaysLoadedTools / alwaysLoadedCategories).
+     * MCP clients call `tool.search` first to discover tools on-demand, dramatically
+     * reducing context token usage for registries with 110+ tools.
+     *
+     * Requires the system prompt to instruct the client to use tool.search.
+     * See docs/examples/mcp-server-example.ts for the recommended prompt snippet.
+     *
+     * Default: false — all enabled tools sent upfront.
+     */
+    searchMode?: boolean;
+    /**
+     * Public base URL of this MCP server (e.g. 'https://mcp.example.com').
+     * Only used when auth.mode is 'jwt'.
+     *
+     * When provided alongside jwt auth, the server mounts
+     * /.well-known/oauth-protected-resource so MCP clients can
+     * auto-discover which OAuth server issues tokens for this server.
+     *
+     * Ignored for static and custom auth modes.
+     */
+    serverUrl?: string;
+}
+interface McpServerHandle {
+    /** Stop the MCP server and release all resources. */
+    stop(): Promise<void>;
+    /** Number of tools currently exposed. */
+    toolCount: number;
+    /**
+     * Actual bound port (HTTP transport only). Useful when port:0 is passed and
+     * the OS assigns a free port — integration tests read this to know where to connect.
+     * Always 0 for stdio transport.
+     */
+    port: number;
+}
+
 interface ProviderOptions {
     /**
      * API key for the provider.
@@ -2756,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>;
@@ -2793,6 +3112,67 @@ declare class Toolpack extends EventEmitter {
      * Validates dependencies and registers all tools.
      */
     loadToolProject(project: ToolProject): Promise<void>;
+    /**
+     * Expose Toolpack's built-in tools as an MCP server.
+     *
+     * Any MCP-compatible client (Claude Desktop, Cursor, Windsurf, custom agents)
+     * can connect and use the full tool catalog without importing this SDK.
+     *
+     * Requires `@modelcontextprotocol/sdk` to be installed:
+     *   npm install @modelcontextprotocol/sdk
+     *
+     * @example stdio — Claude Desktop / Cursor
+     * ```typescript
+     * const sdk = await Toolpack.init({ provider: 'anthropic', tools: true });
+     * await sdk.startMcpServer({ transport: 'stdio' });
+     * ```
+     *
+     * @example HTTP — open (localhost only)
+     * ```typescript
+     * await sdk.startMcpServer({ transport: 'http', port: 3000 });
+     * ```
+     *
+     * @example HTTP — with static bearer token auth (dev / self-hosted)
+     * ```typescript
+     * await sdk.startMcpServer({
+     *   transport: 'http',
+     *   port: 3000,
+     *   auth: { mode: 'static', tokens: [process.env.MCP_TOKEN!] },
+     * });
+     * ```
+     *
+     * @example HTTP — with JWT auth (Auth0 / Supabase / Clerk / any OIDC provider)
+     * ```typescript
+     * await sdk.startMcpServer({
+     *   transport: 'http',
+     *   port: 3000,
+     *   auth: {
+     *     mode: 'jwt',
+     *     jwksUrl: 'https://your-tenant.auth0.com/.well-known/jwks.json',
+     *     audience: 'https://your-mcp-server.example.com',
+     *     issuer:   'https://your-tenant.auth0.com/',
+     *   },
+     *   serverUrl: 'https://your-mcp-server.example.com',
+     * });
+     * ```
+     *
+     * @example expose only specific categories
+     * ```typescript
+     * await sdk.startMcpServer({
+     *   transport: 'stdio',
+     *   expose: { categories: ['filesystem', 'github', 'slack'] },
+     * });
+     * ```
+     *
+     * @example search mode — reduces context token usage for 110+ tools
+     * ```typescript
+     * // tools/list returns only tool.search; clients discover tools on-demand.
+     * // Add this to your system prompt:
+     * //   "Use tool.search to discover tools before calling them."
+     * await sdk.startMcpServer({ transport: 'stdio', searchMode: true });
+     * ```
+     */
+    startMcpServer(config: ToolpackMcpServerConfig): Promise<McpServerHandle>;
     /**
      * Convenience method to get a flat list of all models across all providers.
      */
@@ -3346,4 +3726,4 @@ interface McpServerCapabilities {
 
 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 };
+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, 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, 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 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 };