@anthropic-field/core 0.1.0

package/dist/src/tools/shell.js

@@ -0,0 +1,436 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+import os, { EOL } from 'node:os';
+import crypto from 'node:crypto';
+import { debugLogger } from '../index.js';
+import { ToolErrorType } from './tool-error.js';
+import { BaseDeclarativeTool, BaseToolInvocation, ToolConfirmationOutcome, Kind, } from './tools.js';
+import { getErrorMessage } from '../utils/errors.js';
+import { summarizeToolOutput } from '../utils/summarizer.js';
+import { ShellExecutionService } from '../services/shellExecutionService.js';
+import { formatBytes } from '../utils/formatters.js';
+import { getCommandRoots, initializeShellParsers, stripShellWrapper, parseCommandDetails, hasRedirection, } from '../utils/shell-utils.js';
+import { SHELL_TOOL_NAME } from './tool-names.js';
+export const OUTPUT_UPDATE_INTERVAL_MS = 1000;
+// Delay so user does not see the output of the process before the process is moved to the background.
+const BACKGROUND_DELAY_MS = 200;
+export class ShellToolInvocation extends BaseToolInvocation {
+    config;
+    constructor(config, params, messageBus, _toolName, _toolDisplayName) {
+        super(params, messageBus, _toolName, _toolDisplayName);
+        this.config = config;
+    }
+    getDescription() {
+        let description = `${this.params.command}`;
+        // append optional [in directory]
+        // note description is needed even if validation fails due to absolute path
+        if (this.params.dir_path) {
+            description += ` [in ${this.params.dir_path}]`;
+        }
+        else {
+            description += ` [current working directory ${process.cwd()}]`;
+        }
+        // append optional (description), replacing any line breaks with spaces
+        if (this.params.description) {
+            description += ` (${this.params.description.replace(/\n/g, ' ')})`;
+        }
+        if (this.params.is_background) {
+            description += ' [background]';
+        }
+        return description;
+    }
+    getPolicyUpdateOptions(outcome) {
+        if (outcome === ToolConfirmationOutcome.ProceedAlwaysAndSave ||
+            outcome === ToolConfirmationOutcome.ProceedAlways) {
+            const command = stripShellWrapper(this.params.command);
+            const rootCommands = [...new Set(getCommandRoots(command))];
+            if (rootCommands.length > 0) {
+                return { commandPrefix: rootCommands };
+            }
+            return { commandPrefix: this.params.command };
+        }
+        return undefined;
+    }
+    async getConfirmationDetails(_abortSignal) {
+        const command = stripShellWrapper(this.params.command);
+        const parsed = parseCommandDetails(command);
+        let rootCommandDisplay = '';
+        if (!parsed || parsed.hasError || parsed.details.length === 0) {
+            // Fallback if parser fails
+            const fallback = command.trim().split(/\s+/)[0];
+            rootCommandDisplay = fallback || 'shell command';
+            if (hasRedirection(command)) {
+                rootCommandDisplay += ', redirection';
+            }
+        }
+        else {
+            rootCommandDisplay = parsed.details
+                .map((detail) => detail.name)
+                .join(', ');
+        }
+        const rootCommands = [...new Set(getCommandRoots(command))];
+        // Rely entirely on PolicyEngine for interactive confirmation.
+        // If we are here, it means PolicyEngine returned ASK_USER (or no message bus),
+        // so we must provide confirmation details.
+        const confirmationDetails = {
+            type: 'exec',
+            title: 'Confirm Shell Command',
+            command: this.params.command,
+            rootCommand: rootCommandDisplay,
+            rootCommands,
+            onConfirm: async (outcome) => {
+                await this.publishPolicyUpdate(outcome);
+            },
+        };
+        return confirmationDetails;
+    }
+    async execute(signal, updateOutput, shellExecutionConfig, setPidCallback) {
+        const strippedCommand = stripShellWrapper(this.params.command);
+        if (signal.aborted) {
+            return {
+                llmContent: 'Command was cancelled by user before it could start.',
+                returnDisplay: 'Command cancelled by user.',
+            };
+        }
+        const isWindows = os.platform() === 'win32';
+        const tempFileName = `shell_pgrep_${crypto
+            .randomBytes(6)
+            .toString('hex')}.tmp`;
+        const tempFilePath = path.join(os.tmpdir(), tempFileName);
+        const timeoutMs = this.config.getShellToolInactivityTimeout();
+        const timeoutController = new AbortController();
+        let timeoutTimer;
+        // Handle signal combination manually to avoid TS issues or runtime missing features
+        const combinedController = new AbortController();
+        const onAbort = () => combinedController.abort();
+        try {
+            // pgrep is not available on Windows, so we can't get background PIDs
+            const commandToExecute = isWindows
+                ? strippedCommand
+                : (() => {
+                    // wrap command to append subprocess pids (via pgrep) to temporary file
+                    let command = strippedCommand.trim();
+                    if (!command.endsWith('&'))
+                        command += ';';
+                    return `{ ${command} }; __code=$?; pgrep -g 0 >${tempFilePath} 2>&1; exit $__code;`;
+                })();
+            const cwd = this.params.dir_path
+                ? path.resolve(this.config.getTargetDir(), this.params.dir_path)
+                : this.config.getTargetDir();
+            const validationError = this.config.validatePathAccess(cwd);
+            if (validationError) {
+                return {
+                    llmContent: validationError,
+                    returnDisplay: 'Path not in workspace.',
+                    error: {
+                        message: validationError,
+                        type: ToolErrorType.PATH_NOT_IN_WORKSPACE,
+                    },
+                };
+            }
+            let cumulativeOutput = '';
+            let lastUpdateTime = Date.now();
+            let isBinaryStream = false;
+            const resetTimeout = () => {
+                if (timeoutMs <= 0) {
+                    return;
+                }
+                if (timeoutTimer)
+                    clearTimeout(timeoutTimer);
+                timeoutTimer = setTimeout(() => {
+                    timeoutController.abort();
+                }, timeoutMs);
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+            timeoutController.signal.addEventListener('abort', onAbort, {
+                once: true,
+            });
+            // Start timeout
+            resetTimeout();
+            const { result: resultPromise, pid } = await ShellExecutionService.execute(commandToExecute, cwd, (event) => {
+                resetTimeout(); // Reset timeout on any event
+                if (!updateOutput) {
+                    return;
+                }
+                let shouldUpdate = false;
+                switch (event.type) {
+                    case 'data':
+                        if (isBinaryStream)
+                            break;
+                        cumulativeOutput = event.chunk;
+                        shouldUpdate = true;
+                        break;
+                    case 'binary_detected':
+                        isBinaryStream = true;
+                        cumulativeOutput =
+                            '[Binary output detected. Halting stream...]';
+                        shouldUpdate = true;
+                        break;
+                    case 'binary_progress':
+                        isBinaryStream = true;
+                        cumulativeOutput = `[Receiving binary output... ${formatBytes(event.bytesReceived)} received]`;
+                        if (Date.now() - lastUpdateTime > OUTPUT_UPDATE_INTERVAL_MS) {
+                            shouldUpdate = true;
+                        }
+                        break;
+                    case 'exit':
+                        break;
+                    default: {
+                        throw new Error('An unhandled ShellOutputEvent was found.');
+                    }
+                }
+                if (shouldUpdate && !this.params.is_background) {
+                    updateOutput(cumulativeOutput);
+                    lastUpdateTime = Date.now();
+                }
+            }, combinedController.signal, this.config.getEnableInteractiveShell(), {
+                ...shellExecutionConfig,
+                pager: 'cat',
+                sanitizationConfig: shellExecutionConfig?.sanitizationConfig ??
+                    this.config.sanitizationConfig,
+            });
+            if (pid) {
+                if (setPidCallback) {
+                    setPidCallback(pid);
+                }
+                // If the model requested to run in the background, do so after a short delay.
+                if (this.params.is_background) {
+                    setTimeout(() => {
+                        ShellExecutionService.background(pid);
+                    }, BACKGROUND_DELAY_MS);
+                }
+            }
+            const result = await resultPromise;
+            const backgroundPIDs = [];
+            if (os.platform() !== 'win32') {
+                let tempFileExists = false;
+                try {
+                    await fsPromises.access(tempFilePath);
+                    tempFileExists = true;
+                }
+                catch {
+                    tempFileExists = false;
+                }
+                if (tempFileExists) {
+                    const pgrepContent = await fsPromises.readFile(tempFilePath, 'utf8');
+                    const pgrepLines = pgrepContent.split(EOL).filter(Boolean);
+                    for (const line of pgrepLines) {
+                        if (!/^\d+$/.test(line)) {
+                            debugLogger.error(`pgrep: ${line}`);
+                        }
+                        const pid = Number(line);
+                        if (pid !== result.pid) {
+                            backgroundPIDs.push(pid);
+                        }
+                    }
+                }
+                else {
+                    if (!signal.aborted && !result.backgrounded) {
+                        debugLogger.error('missing pgrep output');
+                    }
+                }
+            }
+            let data;
+            let llmContent = '';
+            let timeoutMessage = '';
+            if (result.aborted) {
+                if (timeoutController.signal.aborted) {
+                    timeoutMessage = `Command was automatically cancelled because it exceeded the timeout of ${(timeoutMs / 60000).toFixed(1)} minutes without output.`;
+                    llmContent = timeoutMessage;
+                }
+                else {
+                    llmContent =
+                        'Command was cancelled by user before it could complete.';
+                }
+                if (result.output.trim()) {
+                    llmContent += ` Below is the output before it was cancelled:\n${result.output}`;
+                }
+                else {
+                    llmContent += ' There was no output before it was cancelled.';
+                }
+            }
+            else if (this.params.is_background || result.backgrounded) {
+                llmContent = `Command moved to background (PID: ${result.pid}). Output hidden. Press Ctrl+B to view.`;
+                data = {
+                    pid: result.pid,
+                    command: this.params.command,
+                    initialOutput: result.output,
+                };
+            }
+            else {
+                // Create a formatted error string for display, replacing the wrapper command
+                // with the user-facing command.
+                const llmContentParts = [`Output: ${result.output || '(empty)'}`];
+                if (result.error) {
+                    const finalError = result.error.message.replaceAll(commandToExecute, this.params.command);
+                    llmContentParts.push(`Error: ${finalError}`);
+                }
+                if (result.exitCode !== null && result.exitCode !== 0) {
+                    llmContentParts.push(`Exit Code: ${result.exitCode}`);
+                }
+                if (result.signal) {
+                    llmContentParts.push(`Signal: ${result.signal}`);
+                }
+                if (backgroundPIDs.length) {
+                    llmContentParts.push(`Background PIDs: ${backgroundPIDs.join(', ')}`);
+                }
+                if (result.pid) {
+                    llmContentParts.push(`Process Group PGID: ${result.pid}`);
+                }
+                llmContent = llmContentParts.join('\n');
+            }
+            let returnDisplayMessage = '';
+            if (this.config.getDebugMode()) {
+                returnDisplayMessage = llmContent;
+            }
+            else {
+                if (this.params.is_background || result.backgrounded) {
+                    returnDisplayMessage = `Command moved to background (PID: ${result.pid}). Output hidden. Press Ctrl+B to view.`;
+                }
+                else if (result.output.trim()) {
+                    returnDisplayMessage = result.output;
+                }
+                else {
+                    if (result.aborted) {
+                        if (timeoutMessage) {
+                            returnDisplayMessage = timeoutMessage;
+                        }
+                        else {
+                            returnDisplayMessage = 'Command cancelled by user.';
+                        }
+                    }
+                    else if (result.signal) {
+                        returnDisplayMessage = `Command terminated by signal: ${result.signal}`;
+                    }
+                    else if (result.error) {
+                        returnDisplayMessage = `Command failed: ${getErrorMessage(result.error)}`;
+                    }
+                    else if (result.exitCode !== null && result.exitCode !== 0) {
+                        returnDisplayMessage = `Command exited with code: ${result.exitCode}`;
+                    }
+                    // If output is empty and command succeeded (code 0, no error/signal/abort),
+                    // returnDisplayMessage will remain empty, which is fine.
+                }
+            }
+            const summarizeConfig = this.config.getSummarizeToolOutputConfig();
+            const executionError = result.error
+                ? {
+                    error: {
+                        message: result.error.message,
+                        type: ToolErrorType.SHELL_EXECUTE_ERROR,
+                    },
+                }
+                : {};
+            if (summarizeConfig && summarizeConfig[SHELL_TOOL_NAME]) {
+                const summary = await summarizeToolOutput(this.config, { model: 'summarizer-shell' }, llmContent, this.config.getGeminiClient(), signal);
+                return {
+                    llmContent: summary,
+                    returnDisplay: returnDisplayMessage,
+                    ...executionError,
+                };
+            }
+            return {
+                llmContent,
+                returnDisplay: returnDisplayMessage,
+                data,
+                ...executionError,
+            };
+        }
+        finally {
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            signal.removeEventListener('abort', onAbort);
+            timeoutController.signal.removeEventListener('abort', onAbort);
+            try {
+                await fsPromises.unlink(tempFilePath);
+            }
+            catch {
+                // Ignore errors during unlink
+            }
+        }
+    }
+}
+function getShellToolDescription(enableInteractiveShell) {
+    const returnedInfo = `
+
+      The following information is returned:
+
+      Output: Combined stdout/stderr. Can be \`(empty)\` or partial on error and for any unwaited background processes.
+      Exit Code: Only included if non-zero (command failed).
+      Error: Only included if a process-level error occurred (e.g., spawn failure).
+      Signal: Only included if process was terminated by a signal.
+      Background PIDs: Only included if background processes were started.
+      Process Group PGID: Only included if available.`;
+    if (os.platform() === 'win32') {
+        const backgroundInstructions = enableInteractiveShell
+            ? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use PowerShell background constructs.'
+            : 'Command can start background processes using PowerShell constructs such as `Start-Process -NoNewWindow` or `Start-Job`.';
+        return `This tool executes a given shell command as \`powershell.exe -NoProfile -Command <command>\`. ${backgroundInstructions}${returnedInfo}`;
+    }
+    else {
+        const backgroundInstructions = enableInteractiveShell
+            ? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use `&` to background commands.'
+            : 'Command can start background processes using `&`.';
+        return `This tool executes a given shell command as \`bash -c <command>\`. ${backgroundInstructions} Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.${returnedInfo}`;
+    }
+}
+function getCommandDescription() {
+    if (os.platform() === 'win32') {
+        return 'Exact command to execute as `powershell.exe -NoProfile -Command <command>`';
+    }
+    else {
+        return 'Exact bash command to execute as `bash -c <command>`';
+    }
+}
+export class ShellTool extends BaseDeclarativeTool {
+    config;
+    static Name = SHELL_TOOL_NAME;
+    constructor(config, messageBus) {
+        void initializeShellParsers().catch(() => {
+            // Errors are surfaced when parsing commands.
+        });
+        super(ShellTool.Name, 'Shell', getShellToolDescription(config.getEnableInteractiveShell()), Kind.Execute, {
+            type: 'object',
+            properties: {
+                command: {
+                    type: 'string',
+                    description: getCommandDescription(),
+                },
+                description: {
+                    type: 'string',
+                    description: 'Brief description of the command for the user. Be specific and concise. Ideally a single sentence. Can be up to 3 sentences for clarity. No line breaks.',
+                },
+                dir_path: {
+                    type: 'string',
+                    description: '(OPTIONAL) The path of the directory to run the command in. If not provided, the project root directory is used. Must be a directory within the workspace and must already exist.',
+                },
+                is_background: {
+                    type: 'boolean',
+                    description: 'Set to true if this command should be run in the background (e.g. for long-running servers or watchers). The command will be started, allowed to run for a brief moment to check for immediate errors, and then moved to the background.',
+                },
+            },
+            required: ['command'],
+        }, messageBus, false, // output is not markdown
+        true);
+        this.config = config;
+    }
+    validateToolParamValues(params) {
+        if (!params.command.trim()) {
+            return 'Command cannot be empty.';
+        }
+        if (params.dir_path) {
+            const resolvedPath = path.resolve(this.config.getTargetDir(), params.dir_path);
+            return this.config.validatePathAccess(resolvedPath);
+        }
+        return null;
+    }
+    createInvocation(params, messageBus, _toolName, _toolDisplayName) {
+        return new ShellToolInvocation(this.config, params, messageBus, _toolName, _toolDisplayName);
+    }
+}
+//# sourceMappingURL=shell.js.map

package/dist/src/tools/shell.js.map

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

package/dist/src/tools/tool-error.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A type-safe enum for tool-related errors.
+ *
+ * Error types are categorized as:
+ * - Recoverable: LLM can self-correct (e.g., invalid params, file not found)
+ * - Fatal: System-level issues that prevent continued execution (e.g., disk full, critical I/O errors)
+ */
+export declare enum ToolErrorType {
+    POLICY_VIOLATION = "policy_violation",
+    /**
+     * General tool execution failure (e.g. file system error, API error).
+     */
+    INVALID_TOOL_PARAMS = "invalid_tool_params",
+    UNKNOWN = "unknown",
+    UNHANDLED_EXCEPTION = "unhandled_exception",
+    TOOL_NOT_REGISTERED = "tool_not_registered",
+    EXECUTION_FAILED = "execution_failed",
+    FILE_NOT_FOUND = "file_not_found",
+    FILE_WRITE_FAILURE = "file_write_failure",
+    READ_CONTENT_FAILURE = "read_content_failure",
+    ATTEMPT_TO_CREATE_EXISTING_FILE = "attempt_to_create_existing_file",
+    FILE_TOO_LARGE = "file_too_large",
+    PERMISSION_DENIED = "permission_denied",
+    NO_SPACE_LEFT = "no_space_left",
+    TARGET_IS_DIRECTORY = "target_is_directory",
+    PATH_NOT_IN_WORKSPACE = "path_not_in_workspace",
+    SEARCH_PATH_NOT_FOUND = "search_path_not_found",
+    SEARCH_PATH_NOT_A_DIRECTORY = "search_path_not_a_directory",
+    EDIT_PREPARATION_FAILURE = "edit_preparation_failure",
+    EDIT_NO_OCCURRENCE_FOUND = "edit_no_occurrence_found",
+    EDIT_EXPECTED_OCCURRENCE_MISMATCH = "edit_expected_occurrence_mismatch",
+    EDIT_NO_CHANGE = "edit_no_change",
+    EDIT_NO_CHANGE_LLM_JUDGEMENT = "edit_no_change_llm_judgement",
+    GLOB_EXECUTION_ERROR = "glob_execution_error",
+    GREP_EXECUTION_ERROR = "grep_execution_error",
+    LS_EXECUTION_ERROR = "ls_execution_error",
+    PATH_IS_NOT_A_DIRECTORY = "path_is_not_a_directory",
+    MCP_TOOL_ERROR = "mcp_tool_error",
+    MEMORY_TOOL_EXECUTION_ERROR = "memory_tool_execution_error",
+    READ_MANY_FILES_SEARCH_ERROR = "read_many_files_search_error",
+    SHELL_EXECUTE_ERROR = "shell_execute_error",
+    DISCOVERED_TOOL_EXECUTION_ERROR = "discovered_tool_execution_error",
+    WEB_FETCH_NO_URL_IN_PROMPT = "web_fetch_no_url_in_prompt",
+    WEB_FETCH_FALLBACK_FAILED = "web_fetch_fallback_failed",
+    WEB_FETCH_PROCESSING_ERROR = "web_fetch_processing_error",
+    WEB_SEARCH_FAILED = "web_search_failed",
+    STOP_EXECUTION = "stop_execution"
+}
+/**
+ * Determines if a tool error type should be treated as fatal.
+ *
+ * Fatal errors are system-level issues that indicate the environment is in a bad state
+ * and continued execution is unlikely to succeed. These include:
+ * - Disk space issues (NO_SPACE_LEFT)
+ *
+ * Non-fatal errors are issues the LLM can potentially recover from by:
+ * - Correcting invalid parameters (INVALID_TOOL_PARAMS)
+ * - Trying different files (FILE_NOT_FOUND)
+ * - Respecting security boundaries (PATH_NOT_IN_WORKSPACE, PERMISSION_DENIED)
+ * - Using different tools or approaches
+ *
+ * @param errorType - The tool error type to check
+ * @returns true if the error should cause the CLI to exit, false if it's recoverable
+ */
+export declare function isFatalToolError(errorType?: string): boolean;

package/dist/src/tools/tool-error.js

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A type-safe enum for tool-related errors.
+ *
+ * Error types are categorized as:
+ * - Recoverable: LLM can self-correct (e.g., invalid params, file not found)
+ * - Fatal: System-level issues that prevent continued execution (e.g., disk full, critical I/O errors)
+ */
+export var ToolErrorType;
+(function (ToolErrorType) {
+    ToolErrorType["POLICY_VIOLATION"] = "policy_violation";
+    /**
+     * General tool execution failure (e.g. file system error, API error).
+     */
+    // General Errors
+    ToolErrorType["INVALID_TOOL_PARAMS"] = "invalid_tool_params";
+    ToolErrorType["UNKNOWN"] = "unknown";
+    ToolErrorType["UNHANDLED_EXCEPTION"] = "unhandled_exception";
+    ToolErrorType["TOOL_NOT_REGISTERED"] = "tool_not_registered";
+    ToolErrorType["EXECUTION_FAILED"] = "execution_failed";
+    // File System Errors
+    ToolErrorType["FILE_NOT_FOUND"] = "file_not_found";
+    ToolErrorType["FILE_WRITE_FAILURE"] = "file_write_failure";
+    ToolErrorType["READ_CONTENT_FAILURE"] = "read_content_failure";
+    ToolErrorType["ATTEMPT_TO_CREATE_EXISTING_FILE"] = "attempt_to_create_existing_file";
+    ToolErrorType["FILE_TOO_LARGE"] = "file_too_large";
+    ToolErrorType["PERMISSION_DENIED"] = "permission_denied";
+    ToolErrorType["NO_SPACE_LEFT"] = "no_space_left";
+    ToolErrorType["TARGET_IS_DIRECTORY"] = "target_is_directory";
+    ToolErrorType["PATH_NOT_IN_WORKSPACE"] = "path_not_in_workspace";
+    ToolErrorType["SEARCH_PATH_NOT_FOUND"] = "search_path_not_found";
+    ToolErrorType["SEARCH_PATH_NOT_A_DIRECTORY"] = "search_path_not_a_directory";
+    // Edit-specific Errors
+    ToolErrorType["EDIT_PREPARATION_FAILURE"] = "edit_preparation_failure";
+    ToolErrorType["EDIT_NO_OCCURRENCE_FOUND"] = "edit_no_occurrence_found";
+    ToolErrorType["EDIT_EXPECTED_OCCURRENCE_MISMATCH"] = "edit_expected_occurrence_mismatch";
+    ToolErrorType["EDIT_NO_CHANGE"] = "edit_no_change";
+    ToolErrorType["EDIT_NO_CHANGE_LLM_JUDGEMENT"] = "edit_no_change_llm_judgement";
+    // Glob-specific Errors
+    ToolErrorType["GLOB_EXECUTION_ERROR"] = "glob_execution_error";
+    // Grep-specific Errors
+    ToolErrorType["GREP_EXECUTION_ERROR"] = "grep_execution_error";
+    // Ls-specific Errors
+    ToolErrorType["LS_EXECUTION_ERROR"] = "ls_execution_error";
+    ToolErrorType["PATH_IS_NOT_A_DIRECTORY"] = "path_is_not_a_directory";
+    // MCP-specific Errors
+    ToolErrorType["MCP_TOOL_ERROR"] = "mcp_tool_error";
+    // Memory-specific Errors
+    ToolErrorType["MEMORY_TOOL_EXECUTION_ERROR"] = "memory_tool_execution_error";
+    // ReadManyFiles-specific Errors
+    ToolErrorType["READ_MANY_FILES_SEARCH_ERROR"] = "read_many_files_search_error";
+    // Shell errors
+    ToolErrorType["SHELL_EXECUTE_ERROR"] = "shell_execute_error";
+    // DiscoveredTool-specific Errors
+    ToolErrorType["DISCOVERED_TOOL_EXECUTION_ERROR"] = "discovered_tool_execution_error";
+    // WebFetch-specific Errors
+    ToolErrorType["WEB_FETCH_NO_URL_IN_PROMPT"] = "web_fetch_no_url_in_prompt";
+    ToolErrorType["WEB_FETCH_FALLBACK_FAILED"] = "web_fetch_fallback_failed";
+    ToolErrorType["WEB_FETCH_PROCESSING_ERROR"] = "web_fetch_processing_error";
+    // WebSearch-specific Errors
+    ToolErrorType["WEB_SEARCH_FAILED"] = "web_search_failed";
+    // Hook-specific Errors
+    ToolErrorType["STOP_EXECUTION"] = "stop_execution";
+})(ToolErrorType || (ToolErrorType = {}));
+/**
+ * Determines if a tool error type should be treated as fatal.
+ *
+ * Fatal errors are system-level issues that indicate the environment is in a bad state
+ * and continued execution is unlikely to succeed. These include:
+ * - Disk space issues (NO_SPACE_LEFT)
+ *
+ * Non-fatal errors are issues the LLM can potentially recover from by:
+ * - Correcting invalid parameters (INVALID_TOOL_PARAMS)
+ * - Trying different files (FILE_NOT_FOUND)
+ * - Respecting security boundaries (PATH_NOT_IN_WORKSPACE, PERMISSION_DENIED)
+ * - Using different tools or approaches
+ *
+ * @param errorType - The tool error type to check
+ * @returns true if the error should cause the CLI to exit, false if it's recoverable
+ */
+export function isFatalToolError(errorType) {
+    if (!errorType) {
+        return false;
+    }
+    const fatalErrors = new Set([ToolErrorType.NO_SPACE_LEFT]);
+    return fatalErrors.has(errorType);
+}
+//# sourceMappingURL=tool-error.js.map

package/dist/src/tools/tool-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-error.js","sourceRoot":"","sources":["../../../src/tools/tool-error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,aAmEX;AAnED,WAAY,aAAa;IACvB,sDAAqC,CAAA;IACrC;;OAEG;IACH,iBAAiB;IACjB,4DAA2C,CAAA;IAC3C,oCAAmB,CAAA;IACnB,4DAA2C,CAAA;IAC3C,4DAA2C,CAAA;IAC3C,sDAAqC,CAAA;IAErC,qBAAqB;IACrB,kDAAiC,CAAA;IACjC,0DAAyC,CAAA;IACzC,8DAA6C,CAAA;IAC7C,oFAAmE,CAAA;IACnE,kDAAiC,CAAA;IACjC,wDAAuC,CAAA;IACvC,gDAA+B,CAAA;IAC/B,4DAA2C,CAAA;IAC3C,gEAA+C,CAAA;IAC/C,gEAA+C,CAAA;IAC/C,4EAA2D,CAAA;IAE3D,uBAAuB;IACvB,sEAAqD,CAAA;IACrD,sEAAqD,CAAA;IACrD,wFAAuE,CAAA;IACvE,kDAAiC,CAAA;IACjC,8EAA6D,CAAA;IAE7D,uBAAuB;IACvB,8DAA6C,CAAA;IAE7C,uBAAuB;IACvB,8DAA6C,CAAA;IAE7C,qBAAqB;IACrB,0DAAyC,CAAA;IACzC,oEAAmD,CAAA;IAEnD,sBAAsB;IACtB,kDAAiC,CAAA;IAEjC,yBAAyB;IACzB,4EAA2D,CAAA;IAE3D,gCAAgC;IAChC,8EAA6D,CAAA;IAE7D,eAAe;IACf,4DAA2C,CAAA;IAE3C,iCAAiC;IACjC,oFAAmE,CAAA;IAEnE,2BAA2B;IAC3B,0EAAyD,CAAA;IACzD,wEAAuD,CAAA;IACvD,0EAAyD,CAAA;IAEzD,4BAA4B;IAC5B,wDAAuC,CAAA;IAEvC,uBAAuB;IACvB,kDAAiC,CAAA;AACnC,CAAC,EAnEW,aAAa,KAAb,aAAa,QAmExB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAkB;IACjD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,GAAG,CAAS,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC;IAEnE,OAAO,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC"}