@blackbox_ai/blackbox-cli-core 0.0.4

package/dist/src/tools/tool-registry.test.js

@@ -0,0 +1,332 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Config, ApprovalMode } from '../config/config.js';
+import { ToolRegistry, DiscoveredTool } from './tool-registry.js';
+import { DiscoveredMCPTool } from './mcp-tool.js';
+import { mcpToTool } from '@google/genai';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { MockTool } from '../test-utils/tools.js';
+import { McpClientManager } from './mcp-client-manager.js';
+import { ToolErrorType } from './tool-error.js';
+vi.mock('node:fs');
+// Mock ./mcp-client.js to control its behavior within tool-registry tests
+vi.mock('./mcp-client.js', async () => {
+    const originalModule = await vi.importActual('./mcp-client.js');
+    return {
+        ...originalModule,
+    };
+});
+// Mock node:child_process
+vi.mock('node:child_process', async () => {
+    const actual = await vi.importActual('node:child_process');
+    return {
+        ...actual,
+        execSync: vi.fn(),
+        spawn: vi.fn(),
+    };
+});
+// Mock MCP SDK Client and Transports
+const mockMcpClientConnect = vi.fn();
+const mockMcpClientOnError = vi.fn();
+const mockStdioTransportClose = vi.fn();
+const mockSseTransportClose = vi.fn();
+vi.mock('@modelcontextprotocol/sdk/client/index.js', () => {
+    const MockClient = vi.fn().mockImplementation(() => ({
+        connect: mockMcpClientConnect,
+        set onerror(handler) {
+            mockMcpClientOnError(handler);
+        },
+    }));
+    return { Client: MockClient };
+});
+vi.mock('@modelcontextprotocol/sdk/client/stdio.js', () => {
+    const MockStdioClientTransport = vi.fn().mockImplementation(() => ({
+        stderr: {
+            on: vi.fn(),
+        },
+        close: mockStdioTransportClose,
+    }));
+    return { StdioClientTransport: MockStdioClientTransport };
+});
+vi.mock('@modelcontextprotocol/sdk/client/sse.js', () => {
+    const MockSSEClientTransport = vi.fn().mockImplementation(() => ({
+        close: mockSseTransportClose,
+    }));
+    return { SSEClientTransport: MockSSEClientTransport };
+});
+// Mock @google/genai mcpToTool
+vi.mock('@google/genai', async () => {
+    const actualGenai = await vi.importActual('@google/genai');
+    return {
+        ...actualGenai,
+        mcpToTool: vi.fn().mockImplementation(() => ({
+            tool: vi.fn().mockResolvedValue({ functionDeclarations: [] }),
+            callTool: vi.fn(),
+        })),
+    };
+});
+// Helper to create a mock CallableTool for specific test needs
+const createMockCallableTool = (toolDeclarations) => ({
+    tool: vi.fn().mockResolvedValue({ functionDeclarations: toolDeclarations }),
+    callTool: vi.fn(),
+});
+const baseConfigParams = {
+    cwd: '/tmp',
+    model: 'test-model',
+    embeddingModel: 'test-embedding-model',
+    sandbox: undefined,
+    targetDir: '/test/dir',
+    debugMode: false,
+    userMemory: '',
+    geminiMdFileCount: 0,
+    approvalMode: ApprovalMode.DEFAULT,
+    sessionId: 'test-session-id',
+};
+describe('ToolRegistry', () => {
+    let config;
+    let toolRegistry;
+    let mockConfigGetToolDiscoveryCommand;
+    beforeEach(() => {
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        vi.mocked(fs.statSync).mockReturnValue({
+            isDirectory: () => true,
+        });
+        config = new Config(baseConfigParams);
+        toolRegistry = new ToolRegistry(config);
+        vi.spyOn(console, 'warn').mockImplementation(() => { });
+        vi.spyOn(console, 'error').mockImplementation(() => { });
+        vi.spyOn(console, 'debug').mockImplementation(() => { });
+        vi.spyOn(console, 'log').mockImplementation(() => { });
+        mockMcpClientConnect.mockReset().mockResolvedValue(undefined);
+        mockStdioTransportClose.mockReset();
+        mockSseTransportClose.mockReset();
+        vi.mocked(mcpToTool).mockClear();
+        vi.mocked(mcpToTool).mockReturnValue(createMockCallableTool([]));
+        mockConfigGetToolDiscoveryCommand = vi.spyOn(config, 'getToolDiscoveryCommand');
+        vi.spyOn(config, 'getMcpServers');
+        vi.spyOn(config, 'getMcpServerCommand');
+        vi.spyOn(config, 'getPromptRegistry').mockReturnValue({
+            clear: vi.fn(),
+            removePromptsByServer: vi.fn(),
+        });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('registerTool', () => {
+        it('should register a new tool', () => {
+            const tool = new MockTool();
+            toolRegistry.registerTool(tool);
+            expect(toolRegistry.getTool('mock-tool')).toBe(tool);
+        });
+    });
+    describe('getAllTools', () => {
+        it('should return all registered tools sorted alphabetically by displayName', () => {
+            // Register tools with displayNames in non-alphabetical order
+            const toolC = new MockTool('c-tool', 'Tool C');
+            const toolA = new MockTool('a-tool', 'Tool A');
+            const toolB = new MockTool('b-tool', 'Tool B');
+            toolRegistry.registerTool(toolC);
+            toolRegistry.registerTool(toolA);
+            toolRegistry.registerTool(toolB);
+            const allTools = toolRegistry.getAllTools();
+            const displayNames = allTools.map((t) => t.displayName);
+            // Assert that the returned array is sorted by displayName
+            expect(displayNames).toEqual(['Tool A', 'Tool B', 'Tool C']);
+        });
+    });
+    describe('getAllToolNames', () => {
+        it('should return all registered tool names', () => {
+            // Register tools with displayNames in non-alphabetical order
+            const toolC = new MockTool('c-tool', 'Tool C');
+            const toolA = new MockTool('a-tool', 'Tool A');
+            const toolB = new MockTool('b-tool', 'Tool B');
+            toolRegistry.registerTool(toolC);
+            toolRegistry.registerTool(toolA);
+            toolRegistry.registerTool(toolB);
+            const toolNames = toolRegistry.getAllToolNames();
+            // Assert that the returned array contains all tool names
+            expect(toolNames).toEqual(['c-tool', 'a-tool', 'b-tool']);
+        });
+    });
+    describe('getToolsByServer', () => {
+        it('should return an empty array if no tools match the server name', () => {
+            toolRegistry.registerTool(new MockTool());
+            expect(toolRegistry.getToolsByServer('any-mcp-server')).toEqual([]);
+        });
+        it('should return only tools matching the server name, sorted by name', async () => {
+            const server1Name = 'mcp-server-uno';
+            const server2Name = 'mcp-server-dos';
+            const mockCallable = {};
+            const mcpTool1_c = new DiscoveredMCPTool(mockCallable, server1Name, 'zebra-tool', 'd1', {});
+            const mcpTool1_a = new DiscoveredMCPTool(mockCallable, server1Name, 'apple-tool', 'd2', {});
+            const mcpTool1_b = new DiscoveredMCPTool(mockCallable, server1Name, 'banana-tool', 'd3', {});
+            const mcpTool2 = new DiscoveredMCPTool(mockCallable, server2Name, 'tool-on-server2', 'd4', {});
+            const nonMcpTool = new MockTool('regular-tool');
+            toolRegistry.registerTool(mcpTool1_c);
+            toolRegistry.registerTool(mcpTool1_a);
+            toolRegistry.registerTool(mcpTool1_b);
+            toolRegistry.registerTool(mcpTool2);
+            toolRegistry.registerTool(nonMcpTool);
+            const toolsFromServer1 = toolRegistry.getToolsByServer(server1Name);
+            const toolNames = toolsFromServer1.map((t) => t.name);
+            // Assert that the array has the correct tools and is sorted by name
+            expect(toolsFromServer1).toHaveLength(3);
+            expect(toolNames).toEqual(['apple-tool', 'banana-tool', 'zebra-tool']);
+            // Assert that all returned tools are indeed from the correct server
+            for (const tool of toolsFromServer1) {
+                expect(tool.serverName).toBe(server1Name);
+            }
+            // Assert that the other server's tools are returned correctly
+            const toolsFromServer2 = toolRegistry.getToolsByServer(server2Name);
+            expect(toolsFromServer2).toHaveLength(1);
+            expect(toolsFromServer2[0].name).toBe(mcpTool2.name);
+        });
+    });
+    describe('discoverTools', () => {
+        it('should will preserve tool parametersJsonSchema during discovery from command', async () => {
+            const discoveryCommand = 'my-discovery-command';
+            mockConfigGetToolDiscoveryCommand.mockReturnValue(discoveryCommand);
+            const unsanitizedToolDeclaration = {
+                name: 'tool-with-bad-format',
+                description: 'A tool with an invalid format property',
+                parametersJsonSchema: {
+                    type: 'object',
+                    properties: {
+                        some_string: {
+                            type: 'string',
+                            format: 'uuid', // This is an unsupported format
+                        },
+                    },
+                },
+            };
+            const mockSpawn = vi.mocked(spawn);
+            const mockChildProcess = {
+                stdout: { on: vi.fn() },
+                stderr: { on: vi.fn() },
+                on: vi.fn(),
+            };
+            mockSpawn.mockReturnValue(mockChildProcess);
+            // Simulate stdout data
+            mockChildProcess.stdout.on.mockImplementation((event, callback) => {
+                if (event === 'data') {
+                    callback(Buffer.from(JSON.stringify([
+                        { function_declarations: [unsanitizedToolDeclaration] },
+                    ])));
+                }
+                return mockChildProcess;
+            });
+            // Simulate process close
+            mockChildProcess.on.mockImplementation((event, callback) => {
+                if (event === 'close') {
+                    callback(0);
+                }
+                return mockChildProcess;
+            });
+            await toolRegistry.discoverAllTools();
+            const discoveredTool = toolRegistry.getTool('tool-with-bad-format');
+            expect(discoveredTool).toBeDefined();
+            const registeredParams = discoveredTool.schema
+                .parametersJsonSchema;
+            expect(registeredParams).toStrictEqual({
+                type: 'object',
+                properties: {
+                    some_string: {
+                        type: 'string',
+                        format: 'uuid',
+                    },
+                },
+            });
+        });
+        it('should return a DISCOVERED_TOOL_EXECUTION_ERROR on tool failure', async () => {
+            const discoveryCommand = 'my-discovery-command';
+            mockConfigGetToolDiscoveryCommand.mockReturnValue(discoveryCommand);
+            vi.spyOn(config, 'getToolCallCommand').mockReturnValue('my-call-command');
+            const toolDeclaration = {
+                name: 'failing-tool',
+                description: 'A tool that fails',
+                parametersJsonSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            };
+            const mockSpawn = vi.mocked(spawn);
+            // --- Discovery Mock ---
+            const discoveryProcess = {
+                stdout: { on: vi.fn(), removeListener: vi.fn() },
+                stderr: { on: vi.fn(), removeListener: vi.fn() },
+                on: vi.fn(),
+            };
+            mockSpawn.mockReturnValueOnce(discoveryProcess);
+            discoveryProcess.stdout.on.mockImplementation((event, callback) => {
+                if (event === 'data') {
+                    callback(Buffer.from(JSON.stringify([{ functionDeclarations: [toolDeclaration] }])));
+                }
+            });
+            discoveryProcess.on.mockImplementation((event, callback) => {
+                if (event === 'close') {
+                    callback(0);
+                }
+            });
+            await toolRegistry.discoverAllTools();
+            const discoveredTool = toolRegistry.getTool('failing-tool');
+            expect(discoveredTool).toBeDefined();
+            // --- Execution Mock ---
+            const executionProcess = {
+                stdout: { on: vi.fn(), removeListener: vi.fn() },
+                stderr: { on: vi.fn(), removeListener: vi.fn() },
+                stdin: { write: vi.fn(), end: vi.fn() },
+                on: vi.fn(),
+                connected: true,
+                disconnect: vi.fn(),
+                removeListener: vi.fn(),
+            };
+            mockSpawn.mockReturnValueOnce(executionProcess);
+            executionProcess.stderr.on.mockImplementation((event, callback) => {
+                if (event === 'data') {
+                    callback(Buffer.from('Something went wrong'));
+                }
+            });
+            executionProcess.on.mockImplementation((event, callback) => {
+                if (event === 'close') {
+                    callback(1); // Non-zero exit code
+                }
+            });
+            const invocation = discoveredTool.build({});
+            const result = await invocation.execute(new AbortController().signal);
+            expect(result.error?.type).toBe(ToolErrorType.DISCOVERED_TOOL_EXECUTION_ERROR);
+            expect(result.llmContent).toContain('Stderr: Something went wrong');
+            expect(result.llmContent).toContain('Exit Code: 1');
+        });
+        it('should discover tools using MCP servers defined in getMcpServers', async () => {
+            const discoverSpy = vi.spyOn(McpClientManager.prototype, 'discoverAllMcpTools');
+            mockConfigGetToolDiscoveryCommand.mockReturnValue(undefined);
+            vi.spyOn(config, 'getMcpServerCommand').mockReturnValue(undefined);
+            const mcpServerConfigVal = {
+                'my-mcp-server': {
+                    command: 'mcp-server-cmd',
+                    args: ['--port', '1234'],
+                    trust: true,
+                },
+            };
+            vi.spyOn(config, 'getMcpServers').mockReturnValue(mcpServerConfigVal);
+            await toolRegistry.discoverAllTools();
+            expect(discoverSpy).toHaveBeenCalled();
+        });
+    });
+    describe('DiscoveredToolInvocation', () => {
+        it('should return the stringified params from getDescription', () => {
+            const tool = new DiscoveredTool(config, 'test-tool', 'A test tool', {});
+            const params = { param: 'testValue' };
+            const invocation = tool.build(params);
+            const description = invocation.getDescription();
+            expect(description).toBe(JSON.stringify(params));
+        });
+    });
+});
+//# sourceMappingURL=tool-registry.test.js.map

package/dist/src/tools/tool-registry.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.test.js","sourceRoot":"","sources":["../../../src/tools/tool-registry.test.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/tools.d.ts

@@ -0,0 +1,316 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { FunctionDeclaration, PartListUnion } from '@google/genai';
+import { ToolErrorType } from './tool-error.js';
+import type { DiffUpdateResult } from '../ide/ideContext.js';
+import { type SubagentStatsSummary } from '../subagents/subagent-statistics.js';
+/**
+ * Represents a validated and ready-to-execute tool call.
+ * An instance of this is created by a `ToolBuilder`.
+ */
+export interface ToolInvocation<TParams extends object, TResult extends ToolResult> {
+    /**
+     * The validated parameters for this specific invocation.
+     */
+    params: TParams;
+    /**
+     * Gets a pre-execution description of the tool operation.
+     *
+     * @returns A markdown string describing what the tool will do.
+     */
+    getDescription(): string;
+    /**
+     * Determines what file system paths the tool will affect.
+     * @returns A list of such paths.
+     */
+    toolLocations(): ToolLocation[];
+    /**
+     * Determines if the tool should prompt for confirmation before execution.
+     * @returns Confirmation details or false if no confirmation is needed.
+     */
+    shouldConfirmExecute(abortSignal: AbortSignal): Promise<ToolCallConfirmationDetails | false>;
+    /**
+     * Executes the tool with the validated parameters.
+     * @param signal AbortSignal for tool cancellation.
+     * @param updateOutput Optional callback to stream output.
+     * @returns Result of the tool execution.
+     */
+    execute(signal: AbortSignal, updateOutput?: (output: ToolResultDisplay) => void): Promise<TResult>;
+}
+/**
+ * A convenience base class for ToolInvocation.
+ */
+export declare abstract class BaseToolInvocation<TParams extends object, TResult extends ToolResult> implements ToolInvocation<TParams, TResult> {
+    readonly params: TParams;
+    constructor(params: TParams);
+    abstract getDescription(): string;
+    toolLocations(): ToolLocation[];
+    shouldConfirmExecute(_abortSignal: AbortSignal): Promise<ToolCallConfirmationDetails | false>;
+    abstract execute(signal: AbortSignal, updateOutput?: (output: ToolResultDisplay) => void): Promise<TResult>;
+}
+/**
+ * A type alias for a tool invocation where the specific parameter and result types are not known.
+ */
+export type AnyToolInvocation = ToolInvocation<object, ToolResult>;
+/**
+ * Interface for a tool builder that validates parameters and creates invocations.
+ */
+export interface ToolBuilder<TParams extends object, TResult extends ToolResult> {
+    /**
+     * The internal name of the tool (used for API calls).
+     */
+    name: string;
+    /**
+     * The user-friendly display name of the tool.
+     */
+    displayName: string;
+    /**
+     * Description of what the tool does.
+     */
+    description: string;
+    /**
+     * The kind of tool for categorization and permissions
+     */
+    kind: Kind;
+    /**
+     * Function declaration schema from @google/genai.
+     */
+    schema: FunctionDeclaration;
+    /**
+     * Whether the tool's output should be rendered as markdown.
+     */
+    isOutputMarkdown: boolean;
+    /**
+     * Whether the tool supports live (streaming) output.
+     */
+    canUpdateOutput: boolean;
+    /**
+     * Validates raw parameters and builds a ready-to-execute invocation.
+     * @param params The raw, untrusted parameters from the model.
+     * @returns A valid `ToolInvocation` if successful. Throws an error if validation fails.
+     */
+    build(params: TParams): ToolInvocation<TParams, TResult>;
+}
+/**
+ * New base class for tools that separates validation from execution.
+ * New tools should extend this class.
+ */
+export declare abstract class DeclarativeTool<TParams extends object, TResult extends ToolResult> implements ToolBuilder<TParams, TResult> {
+    readonly name: string;
+    readonly displayName: string;
+    readonly description: string;
+    readonly kind: Kind;
+    readonly parameterSchema: unknown;
+    readonly isOutputMarkdown: boolean;
+    readonly canUpdateOutput: boolean;
+    constructor(name: string, displayName: string, description: string, kind: Kind, parameterSchema: unknown, isOutputMarkdown?: boolean, canUpdateOutput?: boolean);
+    get schema(): FunctionDeclaration;
+    /**
+     * Validates the raw tool parameters.
+     * Subclasses should override this to add custom validation logic
+     * beyond the JSON schema check.
+     * @param params The raw parameters from the model.
+     * @returns An error message string if invalid, null otherwise.
+     */
+    validateToolParams(_params: TParams): string | null;
+    /**
+     * The core of the new pattern. It validates parameters and, if successful,
+     * returns a `ToolInvocation` object that encapsulates the logic for the
+     * specific, validated call.
+     * @param params The raw, untrusted parameters from the model.
+     * @returns A `ToolInvocation` instance.
+     */
+    abstract build(params: TParams): ToolInvocation<TParams, TResult>;
+    /**
+     * A convenience method that builds and executes the tool in one step.
+     * Throws an error if validation fails.
+     * @param params The raw, untrusted parameters from the model.
+     * @param signal AbortSignal for tool cancellation.
+     * @param updateOutput Optional callback to stream output.
+     * @returns The result of the tool execution.
+     */
+    buildAndExecute(params: TParams, signal: AbortSignal, updateOutput?: (output: ToolResultDisplay) => void): Promise<TResult>;
+    /**
+     * Similar to `build` but never throws.
+     * @param params The raw, untrusted parameters from the model.
+     * @returns A `ToolInvocation` instance.
+     */
+    private silentBuild;
+    /**
+     * A convenience method that builds and executes the tool in one step.
+     * Never throws.
+     * @param params The raw, untrusted parameters from the model.
+     * @params abortSignal a signal to abort.
+     * @returns The result of the tool execution.
+     */
+    validateBuildAndExecute(params: TParams, abortSignal: AbortSignal): Promise<ToolResult>;
+}
+/**
+ * New base class for declarative tools that separates validation from execution.
+ * New tools should extend this class, which provides a `build` method that
+ * validates parameters before deferring to a `createInvocation` method for
+ * the final `ToolInvocation` object instantiation.
+ */
+export declare abstract class BaseDeclarativeTool<TParams extends object, TResult extends ToolResult> extends DeclarativeTool<TParams, TResult> {
+    build(params: TParams): ToolInvocation<TParams, TResult>;
+    validateToolParams(params: TParams): string | null;
+    protected validateToolParamValues(_params: TParams): string | null;
+    protected abstract createInvocation(params: TParams): ToolInvocation<TParams, TResult>;
+}
+/**
+ * A type alias for a declarative tool where the specific parameter and result types are not known.
+ */
+export type AnyDeclarativeTool = DeclarativeTool<object, ToolResult>;
+/**
+ * Type guard to check if an object is a Tool.
+ * @param obj The object to check.
+ * @returns True if the object is a Tool, false otherwise.
+ */
+export declare function isTool(obj: unknown): obj is AnyDeclarativeTool;
+export interface ToolResult {
+    /**
+     * Content meant to be included in LLM history.
+     * This should represent the factual outcome of the tool execution.
+     */
+    llmContent: PartListUnion;
+    /**
+     * Markdown string for user display.
+     * This provides a user-friendly summary or visualization of the result.
+     * NOTE: This might also be considered UI-specific and could potentially be
+     * removed or modified in a further refactor if the server becomes purely API-driven.
+     * For now, we keep it as the core logic in ReadFileTool currently produces it.
+     */
+    returnDisplay: ToolResultDisplay;
+    /**
+     * If this property is present, the tool call is considered a failure.
+     */
+    error?: {
+        message: string;
+        type?: ToolErrorType;
+    };
+}
+/**
+ * Detects cycles in a JSON schemas due to `$ref`s.
+ * @param schema The root of the JSON schema.
+ * @returns `true` if a cycle is detected, `false` otherwise.
+ */
+export declare function hasCycleInSchema(schema: object): boolean;
+export interface TaskResultDisplay {
+    type: 'task_execution';
+    subagentName: string;
+    subagentColor?: string;
+    taskDescription: string;
+    taskPrompt: string;
+    status: 'running' | 'completed' | 'failed' | 'cancelled';
+    terminateReason?: string;
+    result?: string;
+    executionSummary?: SubagentStatsSummary;
+    pendingConfirmation?: ToolCallConfirmationDetails;
+    toolCalls?: Array<{
+        callId: string;
+        name: string;
+        status: 'executing' | 'awaiting_approval' | 'success' | 'failed';
+        error?: string;
+        args?: Record<string, unknown>;
+        result?: string;
+        resultDisplay?: string;
+        description?: string;
+    }>;
+}
+export type ToolResultDisplay = string | FileDiff | TodoResultDisplay | PlanResultDisplay | TaskResultDisplay;
+export interface FileDiff {
+    fileDiff: string;
+    fileName: string;
+    originalContent: string | null;
+    newContent: string;
+    diffStat?: DiffStat;
+}
+export interface DiffStat {
+    ai_removed_lines: number;
+    ai_added_lines: number;
+    user_added_lines: number;
+    user_removed_lines: number;
+}
+export interface TodoResultDisplay {
+    type: 'todo_list';
+    todos: Array<{
+        id: string;
+        content: string;
+        status: 'pending' | 'in_progress' | 'completed';
+    }>;
+}
+export interface PlanResultDisplay {
+    type: 'plan_summary';
+    message: string;
+    plan: string;
+}
+export interface ToolEditConfirmationDetails {
+    type: 'edit';
+    title: string;
+    onConfirm: (outcome: ToolConfirmationOutcome, payload?: ToolConfirmationPayload) => Promise<void>;
+    fileName: string;
+    filePath: string;
+    fileDiff: string;
+    originalContent: string | null;
+    newContent: string;
+    isModifying?: boolean;
+    ideConfirmation?: Promise<DiffUpdateResult>;
+}
+export interface ToolConfirmationPayload {
+    newContent: string;
+}
+export interface ToolExecuteConfirmationDetails {
+    type: 'exec';
+    title: string;
+    onConfirm: (outcome: ToolConfirmationOutcome) => Promise<void>;
+    command: string;
+    rootCommand: string;
+}
+export interface ToolMcpConfirmationDetails {
+    type: 'mcp';
+    title: string;
+    serverName: string;
+    toolName: string;
+    toolDisplayName: string;
+    onConfirm: (outcome: ToolConfirmationOutcome) => Promise<void>;
+}
+export interface ToolInfoConfirmationDetails {
+    type: 'info';
+    title: string;
+    onConfirm: (outcome: ToolConfirmationOutcome) => Promise<void>;
+    prompt: string;
+    urls?: string[];
+}
+export type ToolCallConfirmationDetails = ToolEditConfirmationDetails | ToolExecuteConfirmationDetails | ToolMcpConfirmationDetails | ToolInfoConfirmationDetails | ToolPlanConfirmationDetails;
+export interface ToolPlanConfirmationDetails {
+    type: 'plan';
+    title: string;
+    plan: string;
+    onConfirm: (outcome: ToolConfirmationOutcome) => Promise<void>;
+}
+export declare enum ToolConfirmationOutcome {
+    ProceedOnce = "proceed_once",
+    ProceedAlways = "proceed_always",
+    ProceedAlwaysServer = "proceed_always_server",
+    ProceedAlwaysTool = "proceed_always_tool",
+    ModifyWithEditor = "modify_with_editor",
+    Cancel = "cancel"
+}
+export declare enum Kind {
+    Read = "read",
+    Edit = "edit",
+    Delete = "delete",
+    Move = "move",
+    Search = "search",
+    Execute = "execute",
+    Think = "think",
+    Fetch = "fetch",
+    Other = "other"
+}
+export interface ToolLocation {
+    path: string;
+    line?: number;
+}