agent-world 0.11.1 → 0.12.0

package/dist/core/shell-cmd-tool.js

@@ -0,0 +1,1157 @@
+/**
+ * Shell Command Tool Module - Built-in LLM tool for executing shell commands
+ *
+ * Features:
+ * - Execute shell commands in child processes with parameter support
+ * - Capture stdout and stderr output
+ * - Persist command execution history (command, parameters, results, exceptions)
+ * - Return results to LLM for further processing
+ * - Error handling and exception tracking
+ * - Long-running command support with 10-minute default timeout
+ * - Trusted working-directory enforcement from world/tool context
+ * - Explicit rejection when LLM-supplied directory conflicts with trusted working directory
+ * - Graceful error handling for invalid tool calls
+ * - Universal parameter validation for consistent execution
+ * - Explicit execution safety configuration using structured metadata
+ *
+ * Implementation Details:
+ * - Uses Node.js child_process.spawn for command execution
+ * - Executes commands through shell for PATH resolution and shell features
+ * - Stores execution history in-memory (can be extended to persistent storage)
+ * - Provides MCP-compatible tool interface for LLM integration
+ * - Timeout support to prevent hanging processes (default: 10 minutes)
+ * - Resource cleanup on process completion
+ * - Resolves command cwd from trusted world/tool context, not LLM args
+ * - Rejects directory mismatch instead of silently overriding requested path
+ * - Returns error results instead of throwing to prevent agent crashes
+ * - Uses universal validation framework for consistent parameter checking
+ *
+ * Recent Changes:
+ * - 2026-02-15: Moved core cwd-boundary enforcement into `executeShellCommand` via optional `trustedWorkingDirectory` execution option.
+ * - 2026-02-15: Added optional `output_format=json` for machine-readable command results.
+ * - 2026-02-15: Added optional `artifact_paths` support with SHA-256 hashing and byte-size metadata for files within trusted scope.
+ * - 2026-02-14: Default trusted cwd now falls back to shared core default working directory (user home by default) instead of `./` when world variable is unset.
+ * - 2026-02-14: Added inline-script execution guard (e.g. `sh -c`, `node -e`) to prevent embedded path bypass outside trusted cwd.
+ * - 2026-02-14: Hardened cwd containment checks by canonicalizing absolute paths and validating additional path argument forms (`./`, `../`, and `--flag=/path`).
+ * - 2026-02-13: Updated directory-request validation to allow requested folders inside world working_directory and reject only outside paths.
+ * - 2026-02-13: Added command/parameter path scope validation so shell_cmd rejects path targets outside trusted world working_directory.
+ * - 2026-02-13: Added strict directory-mismatch guard for shell_cmd; mismatched LLM directory requests now fail with explicit error.
+ * - 2026-02-13: Fixed validation error result typing by including `executionId` when formatting failed shell_cmd calls.
+ * - 2026-02-13: Stopped trusting LLM-provided `directory`; shell commands now resolve working directory from trusted world/tool context only.
+ * - 2026-02-13: Added explicit command-cancellation detection and AbortError propagation in tool execution to prevent post-stop continuation.
+ * - 2026-02-13: Added chat-scoped shell process tracking and stop controls for Electron stop-message support.
+ * - 2026-02-08: Added streaming callback support for real-time output
+ *   * Added onStdout and onStderr callbacks to executeShellCommand options
+ *   * Callbacks invoked in real-time as data arrives from child process
+ *   * Maintains backwards compatibility - callbacks are optional
+ *   * Full output still accumulated and returned in CommandExecutionResult
+ * - 2026-02-06: Removed legacy manual tool-decision metadata
+ * - 2025-11-11: CRITICAL FIX - Quote parameters for shell execution
+ *   * Parameters with spaces/tabs/newlines now properly quoted before spawn
+ *   * Prevents shell from splitting multi-word parameters
+ *   * Applied to both execution AND display formatting
+ * - 2025-11-10: Fixed shell execution - enabled shell: true to support PATH resolution and installed commands
+ * - Integrated universal parameter validation for consistent tool execution
+ * - Enhanced validation to check required parameters and auto-correct types
+ * - Replaced custom validation with standardized validation framework
+ * - Added graceful error handling for empty commands to prevent agent crashes
+ * - Changed validation to return error results instead of throwing exceptions
+ * - Updated tests to expect error results rather than thrown errors
+ * - Added LLM guidance to ask user for directory when not provided
+ * - Made directory parameter required for shell command execution
+ * - Increased default timeout from 30s to 10 minutes (600000ms) for long-running commands
+ * - Initial implementation for shell_cmd LLM tool
+ */
+import { spawn } from 'child_process';
+import { resolve, join, relative } from 'path';
+import { createHash } from 'crypto';
+import { homedir } from 'os';
+import { realpathSync, promises as fsPromises } from 'fs';
+import { createCategoryLogger } from './logger.js';
+import { validateToolParameters } from './tool-utils.js';
+import { publishSSE } from './events/index.js';
+import { getDefaultWorkingDirectory, getEnvValueFromText } from './utils.js';
+import { createShellProcessExecution, transitionShellProcessExecution, attachShellProcessHandle, markShellProcessCancelRequested, listShellProcessExecutions, getShellProcessExecution, cancelShellProcessExecution, deleteShellProcessExecution, stopShellProcessesForChatScope, subscribeShellProcessStatus, clearShellProcessRegistryForTests } from './shell-process-registry.js';
+const logger = createCategoryLogger('shell-cmd');
+/**
+ * Resolve directory path, handling tilde expansion and relative paths
+ */
+function resolveDirectory(directory) {
+    if (directory.startsWith('~/')) {
+        return join(homedir(), directory.slice(2));
+    }
+    if (directory === '~') {
+        return homedir();
+    }
+    return resolve(directory);
+}
+const DEFAULT_MIN_OUTPUT_CHARS = 400;
+function buildOutputSnippet(content, maxOutputChars) {
+    if (!content) {
+        return { text: '', truncated: false };
+    }
+    if (maxOutputChars <= 0 || content.length <= maxOutputChars) {
+        return { text: content, truncated: false };
+    }
+    return {
+        text: content.slice(0, maxOutputChars),
+        truncated: true
+    };
+}
+/**
+ * In-memory storage for command execution history
+ * Can be extended to use persistent storage in the future
+ */
+const executionHistory = [];
+const MAX_HISTORY_SIZE = 1000; // Limit history size to prevent memory issues
+export function resolveTrustedShellWorkingDirectory(context) {
+    const contextDirectory = typeof context?.workingDirectory === 'string'
+        ? context.workingDirectory.trim()
+        : '';
+    if (contextDirectory) {
+        return contextDirectory;
+    }
+    const worldDirectory = getEnvValueFromText(context?.world?.variables, 'working_directory');
+    const trimmedWorldDirectory = typeof worldDirectory === 'string' ? worldDirectory.trim() : '';
+    return trimmedWorldDirectory || getDefaultWorkingDirectory();
+}
+export function validateShellDirectoryRequest(requestedDirectory, trustedWorkingDirectory) {
+    if (typeof requestedDirectory !== 'string') {
+        return { valid: true };
+    }
+    const requested = requestedDirectory.trim();
+    if (!requested) {
+        return { valid: true };
+    }
+    const trusted = String(trustedWorkingDirectory || '').trim() || getDefaultWorkingDirectory();
+    if (isPathWithinTrustedDirectory(requested, trusted)) {
+        return { valid: true };
+    }
+    return {
+        valid: false,
+        error: `Working directory mismatch: requested directory "${requested}" is outside world working directory "${trusted}". Update world working_directory first.`
+    };
+}
+function stripWrappingQuotes(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1).trim();
+    }
+    return trimmed;
+}
+function trimTrailingSeparators(pathValue) {
+    const root = getPathRoot(pathValue);
+    if (!root || pathValue === root) {
+        return pathValue;
+    }
+    let trimmed = pathValue;
+    while (trimmed.endsWith('/') || trimmed.endsWith('\\')) {
+        trimmed = trimmed.slice(0, -1);
+        if (trimmed === root) {
+            return trimmed;
+        }
+    }
+    return trimmed;
+}
+function getPathRoot(pathValue) {
+    const normalized = pathValue.replace(/\\/g, '/');
+    const driveMatch = normalized.match(/^[A-Za-z]:\//);
+    if (driveMatch) {
+        return driveMatch[0];
+    }
+    if (normalized.startsWith('/')) {
+        return '/';
+    }
+    return '';
+}
+function collapseDotSegments(pathValue) {
+    const normalized = pathValue.replace(/\\/g, '/');
+    const root = getPathRoot(normalized);
+    const segments = normalized.slice(root.length).split('/');
+    const collapsed = [];
+    for (const segment of segments) {
+        if (!segment || segment === '.') {
+            continue;
+        }
+        if (segment === '..') {
+            if (collapsed.length > 0 && collapsed[collapsed.length - 1] !== '..') {
+                collapsed.pop();
+            }
+            else if (!root) {
+                collapsed.push('..');
+            }
+            continue;
+        }
+        collapsed.push(segment);
+    }
+    const joined = collapsed.join('/');
+    if (root) {
+        return `${root}${joined}` || root;
+    }
+    return joined || '.';
+}
+function canonicalizePath(pathValue) {
+    const absolute = resolveDirectory(pathValue);
+    try {
+        const canonical = realpathSync.native ? realpathSync.native(absolute) : realpathSync(absolute);
+        return trimTrailingSeparators(collapseDotSegments(canonical));
+    }
+    catch {
+        return trimTrailingSeparators(collapseDotSegments(absolute));
+    }
+}
+function normalizeForPlatformComparison(pathValue) {
+    return process.platform === 'win32' ? pathValue.toLowerCase() : pathValue;
+}
+function isPathWithinTrustedDirectory(candidatePath, trustedWorkingDirectory) {
+    const normalizedCandidate = normalizeForPlatformComparison(canonicalizePath(candidatePath));
+    const normalizedTrusted = normalizeForPlatformComparison(canonicalizePath(trustedWorkingDirectory));
+    const trustedRoot = normalizeForPlatformComparison(getPathRoot(normalizedTrusted));
+    if (normalizedTrusted === trustedRoot) {
+        return normalizedCandidate.startsWith(normalizedTrusted);
+    }
+    return normalizedCandidate === normalizedTrusted ||
+        normalizedCandidate.startsWith(`${normalizedTrusted}/`);
+}
+function looksLikePathToken(token) {
+    if (!token)
+        return false;
+    return token === '~' ||
+        token === '.' ||
+        token.startsWith('~/') ||
+        token.startsWith('~\\') ||
+        token.startsWith('/') ||
+        token.startsWith('\\') ||
+        token.startsWith('./') ||
+        token.startsWith('.\\') ||
+        token === '..' ||
+        token.startsWith('../') ||
+        token.startsWith('..\\') ||
+        token.includes('/') ||
+        token.includes('\\');
+}
+function resolveTokenPath(token, trustedWorkingDirectory) {
+    if (token.startsWith('~')) {
+        return resolveDirectory(token);
+    }
+    if (token.startsWith('/')) {
+        return resolveDirectory(token);
+    }
+    return resolveDirectory(resolve(trustedWorkingDirectory, token));
+}
+function extractPathTokenFromOptionPrefix(token) {
+    if (!token.startsWith('-') || token.includes('=')) {
+        return null;
+    }
+    const pathStart = token.search(/(~|\/|\\|\.|[A-Za-z]:[\\/])/);
+    if (pathStart <= 1) {
+        return null;
+    }
+    const optionPart = token.slice(0, pathStart);
+    const candidate = token.slice(pathStart);
+    if (!/^-{1,2}[A-Za-z][A-Za-z0-9_-]*$/.test(optionPart)) {
+        return null;
+    }
+    if (!looksLikePathToken(candidate)) {
+        return null;
+    }
+    return candidate;
+}
+function extractPathTokenFromOptionAssignment(token) {
+    if (!token.startsWith('-')) {
+        return null;
+    }
+    const equalsIndex = token.indexOf('=');
+    if (equalsIndex <= 0) {
+        return null;
+    }
+    const assignedValue = stripWrappingQuotes(token.slice(equalsIndex + 1));
+    if (!assignedValue || !looksLikePathToken(assignedValue)) {
+        return null;
+    }
+    return assignedValue;
+}
+function extractPathToken(rawToken) {
+    const token = stripWrappingQuotes(rawToken);
+    if (!token) {
+        return null;
+    }
+    const fromAssignment = extractPathTokenFromOptionAssignment(token);
+    if (fromAssignment) {
+        return fromAssignment;
+    }
+    const fromOptionPrefix = extractPathTokenFromOptionPrefix(token);
+    if (fromOptionPrefix) {
+        return fromOptionPrefix;
+    }
+    if (token.startsWith('-')) {
+        return null;
+    }
+    return looksLikePathToken(token) ? token : null;
+}
+function tokenizeInlineCommandArgs(command) {
+    const tokens = command.match(/"([^"\\]|\\.)*"|'([^'\\]|\\.)*'|[^\s]+/g) ?? [];
+    if (tokens.length <= 1)
+        return [];
+    return tokens.slice(1);
+}
+function tokenizeCommand(command) {
+    return command.match(/"([^"\\]|\\.)*"|'([^'\\]|\\.)*'|[^\s]+/g) ?? [];
+}
+function hasDisallowedShellSyntax(value) {
+    if (!value)
+        return false;
+    return value.includes('&&') ||
+        value.includes('||') ||
+        value.includes('|') ||
+        value.includes(';') ||
+        value.includes('>') ||
+        value.includes('<') ||
+        value.includes('$(') ||
+        value.includes('`') ||
+        value.includes('&') ||
+        value.includes('\n') ||
+        value.includes('\r');
+}
+function validateSingleCommandContract(command) {
+    if (typeof command !== 'string' || !command.trim()) {
+        return {
+            valid: false,
+            error: 'Invalid command: command must be a non-empty string.'
+        };
+    }
+    if (hasDisallowedShellSyntax(command)) {
+        return {
+            valid: false,
+            error: 'Invalid command: shell control syntax is not allowed (`&&`, `||`, `|`, `;`, redirects, command substitution, backgrounding). Provide a single executable in `command` and pass arguments via `parameters`.'
+        };
+    }
+    const commandTokens = tokenizeCommand(command).map(stripWrappingQuotes).filter(Boolean);
+    if (commandTokens.length !== 1) {
+        return {
+            valid: false,
+            error: 'Invalid command format: provide a single executable in `command` and pass all arguments as separate `parameters` tokens.'
+        };
+    }
+    const executable = commandTokens[0];
+    if (!executable || /\s/.test(executable)) {
+        return {
+            valid: false,
+            error: 'Invalid command executable: `command` must be a single token without whitespace.'
+        };
+    }
+    return { valid: true, executable };
+}
+function getExecutableName(command) {
+    const tokens = tokenizeCommand(command);
+    if (tokens.length === 0)
+        return '';
+    const executable = stripWrappingQuotes(tokens[0]).replace(/\\/g, '/');
+    const parts = executable.split('/').filter(Boolean);
+    return String(parts[parts.length - 1] || executable).toLowerCase();
+}
+function getInterpreterInlineScriptFlags(executable) {
+    if (['sh', 'bash', 'zsh', 'dash', 'ksh', 'fish', 'cmd', 'cmd.exe'].includes(executable)) {
+        return new Set(['-c', '/c', '/k']);
+    }
+    if (['powershell', 'powershell.exe', 'pwsh', 'pwsh.exe'].includes(executable)) {
+        return new Set(['-c', '-command']);
+    }
+    if (['node', 'node.exe', 'deno', 'python', 'python3', 'python.exe', 'python3.exe'].includes(executable)) {
+        return new Set(['-c', '-e', '--eval']);
+    }
+    if (['perl', 'ruby', 'php'].includes(executable)) {
+        return new Set(['-e', '-r']);
+    }
+    return new Set();
+}
+function findInlineScriptExecutionFlag(command, parameters) {
+    if (typeof command !== 'string' || !command.trim()) {
+        return null;
+    }
+    const commandTokens = tokenizeCommand(command).map(stripWrappingQuotes).filter(Boolean);
+    const commandArgs = commandTokens.slice(1);
+    const parameterArgs = Array.isArray(parameters)
+        ? parameters.filter((p) => typeof p === 'string').map(stripWrappingQuotes).filter(Boolean)
+        : [];
+    const directExecutable = getExecutableName(command);
+    let executable = directExecutable;
+    let args = [...commandArgs, ...parameterArgs];
+    // Handle wrappers like `env bash -c ...`
+    if (directExecutable === 'env') {
+        const envArgs = [...args];
+        while (envArgs.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(envArgs[0])) {
+            envArgs.shift();
+        }
+        if (envArgs.length > 0) {
+            executable = getExecutableName(envArgs[0]);
+            args = envArgs.slice(1);
+        }
+    }
+    const scriptFlags = getInterpreterInlineScriptFlags(executable);
+    if (scriptFlags.size === 0) {
+        return null;
+    }
+    for (const rawArg of args) {
+        const arg = rawArg.toLowerCase();
+        if (scriptFlags.has(arg)) {
+            return { executable, flag: rawArg };
+        }
+        for (const scriptFlag of scriptFlags) {
+            if ((scriptFlag.startsWith('-') || scriptFlag.startsWith('/')) &&
+                arg.startsWith(scriptFlag) &&
+                arg.length > scriptFlag.length) {
+                return { executable, flag: rawArg };
+            }
+        }
+    }
+    return null;
+}
+export function validateShellCommandScope(command, parameters, trustedWorkingDirectory) {
+    const singleCommandValidation = validateSingleCommandContract(command);
+    if (!singleCommandValidation.valid) {
+        return singleCommandValidation;
+    }
+    if (Array.isArray(parameters)) {
+        for (const parameter of parameters) {
+            if (typeof parameter !== 'string') {
+                continue;
+            }
+            if (hasDisallowedShellSyntax(parameter)) {
+                return {
+                    valid: false,
+                    error: `Invalid parameter: shell control syntax is not allowed in parameters (received "${parameter}").`
+                };
+            }
+        }
+    }
+    const inlineScriptUsage = findInlineScriptExecutionFlag(command, parameters);
+    if (inlineScriptUsage) {
+        return {
+            valid: false,
+            error: `Working directory mismatch: inline script execution "${inlineScriptUsage.executable} ${inlineScriptUsage.flag}" is not allowed. Use direct command + parameters inside world working directory "${trustedWorkingDirectory}".`
+        };
+    }
+    const tokens = [];
+    if (typeof command === 'string' && command.trim()) {
+        tokens.push(...tokenizeInlineCommandArgs(command));
+    }
+    if (Array.isArray(parameters)) {
+        for (const parameter of parameters) {
+            if (typeof parameter === 'string') {
+                tokens.push(parameter);
+            }
+        }
+    }
+    for (const rawToken of tokens) {
+        const token = extractPathToken(rawToken);
+        if (!token)
+            continue;
+        const resolvedPath = resolveTokenPath(token, trustedWorkingDirectory);
+        if (!isPathWithinTrustedDirectory(resolvedPath, trustedWorkingDirectory)) {
+            return {
+                valid: false,
+                error: `Working directory mismatch: path "${token}" is outside world working directory "${trustedWorkingDirectory}".`
+            };
+        }
+    }
+    return { valid: true };
+}
+export function stopShellCommandsForChat(worldId, chatId) {
+    return stopShellProcessesForChatScope(worldId, chatId);
+}
+export function isCommandExecutionCanceled(result) {
+    if (result.canceled)
+        return true;
+    return result.error === 'Command execution canceled by user';
+}
+/**
+ * Execute a shell command with parameters and capture output
+ *
+ * @param command - The shell command to execute (e.g., 'ls', 'echo', 'cat')
+ * @param parameters - Array of parameters for the command (e.g., ['-la', '/tmp'])
+ * @param directory - Working directory for command execution (required)
+ * @param options - Execution options
+ * @returns Promise<CommandExecutionResult> - Execution result with output and metadata
+ */
+export async function executeShellCommand(command, parameters = [], directory, options = {}) {
+    const startTime = Date.now();
+    const timeout = options.timeout || 600000; // Default 10 minute timeout for long-running commands
+    const resolvedDirectory = resolveDirectory(directory);
+    const executionRecord = createShellProcessExecution({
+        command,
+        parameters,
+        directory: resolvedDirectory,
+        worldId: options.worldId,
+        chatId: options.chatId
+    });
+    const executionId = executionRecord.executionId;
+    options.onStatusChange?.({
+        executionId,
+        status: executionRecord.status,
+        record: executionRecord
+    });
+    logger.debug('Executing shell command', {
+        command,
+        parameters,
+        timeout,
+        directory,
+        resolvedDirectory,
+        trustedWorkingDirectory: options.trustedWorkingDirectory || null
+    });
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let aborted = false;
+        let processExited = false;
+        let unsubscribeStatusListener = null;
+        const result = {
+            executionId,
+            command,
+            parameters,
+            stdout: '',
+            stderr: '',
+            exitCode: null,
+            signal: null,
+            executedAt: new Date(),
+            duration: 0
+        };
+        if (options.onStatusChange) {
+            unsubscribeStatusListener = subscribeShellProcessStatus((event) => {
+                if (event.executionId !== executionId)
+                    return;
+                options.onStatusChange?.(event);
+            });
+        }
+        try {
+            const trustedWorkingDirectory = String(options.trustedWorkingDirectory || '').trim();
+            if (trustedWorkingDirectory && !isPathWithinTrustedDirectory(resolvedDirectory, trustedWorkingDirectory)) {
+                throw new Error(`Working directory mismatch: execution directory "${resolvedDirectory}" is outside trusted working directory "${trustedWorkingDirectory}".`);
+            }
+            // Quote parameters that contain spaces, tabs, or newlines for shell execution
+            const quotedParams = parameters.map(param => {
+                if (param.includes(' ') || param.includes('\t') || param.includes('\n') || param.includes('"')) {
+                    // Escape existing quotes and wrap in quotes
+                    return `"${param.replace(/"/g, '\\"')}"`;
+                }
+                return param;
+            });
+            transitionShellProcessExecution(executionId, 'starting', {
+                startedAt: new Date().toISOString()
+            });
+            // Spawn the child process
+            const childProcess = spawn(command, quotedParams, {
+                cwd: resolvedDirectory,
+                shell: true, // Use shell to enable PATH resolution and shell features
+                timeout: timeout
+            });
+            attachShellProcessHandle(executionId, childProcess);
+            transitionShellProcessExecution(executionId, 'running', {
+                startedAt: new Date().toISOString()
+            });
+            // Set up timeout handler
+            const timeoutHandle = setTimeout(() => {
+                if (!processExited) {
+                    timedOut = true;
+                    childProcess.kill('SIGTERM');
+                    logger.warn('Command execution timeout', { command, parameters, timeout, directory });
+                }
+            }, timeout);
+            const abortHandler = () => {
+                if (processExited)
+                    return;
+                aborted = true;
+                markShellProcessCancelRequested(executionId);
+                childProcess.kill('SIGTERM');
+                logger.info('Shell command aborted by request', {
+                    executionId,
+                    command,
+                    parameters,
+                    directory,
+                    worldId: options.worldId || null,
+                    chatId: options.chatId || null
+                });
+            };
+            options.abortSignal?.addEventListener('abort', abortHandler, { once: true });
+            // Capture stdout with optional streaming
+            childProcess.stdout?.on('data', (data) => {
+                const chunk = data.toString();
+                stdout += chunk;
+                // Call streaming callback if provided (with error handling)
+                if (options.onStdout) {
+                    try {
+                        options.onStdout(chunk);
+                    }
+                    catch (error) {
+                        logger.warn('Error in stdout streaming callback', {
+                            error: error instanceof Error ? error.message : error
+                        });
+                    }
+                }
+            });
+            // Capture stderr with optional streaming
+            childProcess.stderr?.on('data', (data) => {
+                const chunk = data.toString();
+                stderr += chunk;
+                // Call streaming callback if provided (with error handling)
+                if (options.onStderr) {
+                    try {
+                        options.onStderr(chunk);
+                    }
+                    catch (error) {
+                        logger.warn('Error in stderr streaming callback', {
+                            error: error instanceof Error ? error.message : error
+                        });
+                    }
+                }
+            });
+            // Handle process exit
+            childProcess.on('close', (code, signal) => {
+                processExited = true;
+                clearTimeout(timeoutHandle);
+                options.abortSignal?.removeEventListener('abort', abortHandler);
+                unsubscribeStatusListener?.();
+                unsubscribeStatusListener = null;
+                const duration = Date.now() - startTime;
+                result.stdout = stdout;
+                result.stderr = stderr;
+                result.exitCode = code;
+                result.signal = signal;
+                result.duration = duration;
+                const latestRecord = getShellProcessExecution(executionId);
+                const canceledByControlRequest = Boolean(latestRecord?.cancelRequested);
+                if (timedOut) {
+                    result.error = `Command execution timed out after ${timeout}ms`;
+                    result.timedOut = true;
+                    transitionShellProcessExecution(executionId, 'timed_out', {
+                        finishedAt: new Date().toISOString(),
+                        exitCode: code,
+                        signal,
+                        stdoutLength: stdout.length,
+                        stderrLength: stderr.length,
+                        error: result.error,
+                        durationMs: duration
+                    });
+                }
+                else if (aborted || canceledByControlRequest) {
+                    result.error = 'Command execution canceled by user';
+                    result.canceled = true;
+                    transitionShellProcessExecution(executionId, 'canceled', {
+                        finishedAt: new Date().toISOString(),
+                        exitCode: code,
+                        signal,
+                        stdoutLength: stdout.length,
+                        stderrLength: stderr.length,
+                        error: result.error,
+                        durationMs: duration
+                    });
+                }
+                else if (code !== 0) {
+                    result.error = `Command exited with code ${code}`;
+                    transitionShellProcessExecution(executionId, 'failed', {
+                        finishedAt: new Date().toISOString(),
+                        exitCode: code,
+                        signal,
+                        stdoutLength: stdout.length,
+                        stderrLength: stderr.length,
+                        error: result.error,
+                        durationMs: duration
+                    });
+                }
+                else {
+                    transitionShellProcessExecution(executionId, 'completed', {
+                        finishedAt: new Date().toISOString(),
+                        exitCode: code,
+                        signal,
+                        stdoutLength: stdout.length,
+                        stderrLength: stderr.length,
+                        durationMs: duration,
+                        error: null
+                    });
+                }
+                // Persist to history
+                persistExecutionResult(result);
+                logger.debug('Command execution completed', {
+                    command,
+                    executionId,
+                    parameters,
+                    directory,
+                    exitCode: code,
+                    signal,
+                    duration,
+                    stdoutLength: stdout.length,
+                    stderrLength: stderr.length,
+                    error: result.error
+                });
+                resolve(result);
+            });
+            // Handle process errors
+            childProcess.on('error', (error) => {
+                processExited = true;
+                clearTimeout(timeoutHandle);
+                options.abortSignal?.removeEventListener('abort', abortHandler);
+                unsubscribeStatusListener?.();
+                unsubscribeStatusListener = null;
+                const duration = Date.now() - startTime;
+                result.stdout = stdout;
+                result.stderr = stderr;
+                result.duration = duration;
+                result.error = error.message;
+                transitionShellProcessExecution(executionId, 'failed', {
+                    finishedAt: new Date().toISOString(),
+                    exitCode: null,
+                    signal: null,
+                    stdoutLength: stdout.length,
+                    stderrLength: stderr.length,
+                    error: result.error,
+                    durationMs: duration
+                });
+                // Persist to history
+                persistExecutionResult(result);
+                logger.warn('Command execution error', {
+                    command,
+                    parameters,
+                    directory,
+                    error: error.message,
+                    duration: Date.now() - startTime
+                });
+                resolve(result);
+            });
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            unsubscribeStatusListener?.();
+            unsubscribeStatusListener = null;
+            result.duration = duration;
+            result.error = error instanceof Error ? error.message : String(error);
+            transitionShellProcessExecution(executionId, 'failed', {
+                finishedAt: new Date().toISOString(),
+                exitCode: null,
+                signal: null,
+                stdoutLength: stdout.length,
+                stderrLength: stderr.length,
+                error: result.error,
+                durationMs: duration
+            });
+            // Persist to history
+            persistExecutionResult(result);
+            logger.warn('Failed to spawn command', {
+                command,
+                parameters,
+                directory,
+                error: result.error,
+                duration
+            });
+            resolve(result);
+        }
+    });
+}
+export function getProcessExecution(executionId) {
+    return getShellProcessExecution(executionId);
+}
+export function listProcessExecutions(options = {}) {
+    return listShellProcessExecutions(options);
+}
+export function cancelProcessExecution(executionId) {
+    return cancelShellProcessExecution(executionId);
+}
+export function deleteProcessExecution(executionId) {
+    const deleteResult = deleteShellProcessExecution(executionId);
+    if (deleteResult.outcome !== 'deleted') {
+        return {
+            executionId,
+            outcome: deleteResult.outcome,
+            removedHistoryEntries: 0
+        };
+    }
+    let removedHistoryEntries = 0;
+    for (let index = executionHistory.length - 1; index >= 0; index -= 1) {
+        if (executionHistory[index]?.executionId !== executionId)
+            continue;
+        executionHistory.splice(index, 1);
+        removedHistoryEntries += 1;
+    }
+    return {
+        executionId,
+        outcome: 'deleted',
+        removedHistoryEntries
+    };
+}
+export function subscribeProcessExecutionStatus(listener) {
+    return subscribeShellProcessStatus(listener);
+}
+export function clearProcessExecutionStateForTests() {
+    const historyCleared = clearExecutionHistory();
+    const registry = clearShellProcessRegistryForTests();
+    return {
+        historyCleared,
+        registryExecutionCount: registry.executionCount,
+        registryActiveCount: registry.activeCount
+    };
+}
+/**
+ * Persist command execution result to history
+ * Maintains a maximum history size to prevent memory issues
+ *
+ * @param result - Command execution result to persist
+ */
+function persistExecutionResult(result) {
+    executionHistory.push(result);
+    // Trim history if it exceeds max size
+    if (executionHistory.length > MAX_HISTORY_SIZE) {
+        const removeCount = executionHistory.length - MAX_HISTORY_SIZE;
+        executionHistory.splice(0, removeCount);
+        logger.debug('Trimmed execution history', {
+            removedCount: removeCount,
+            currentSize: executionHistory.length
+        });
+    }
+    logger.trace('Persisted execution result', {
+        command: result.command,
+        parameters: result.parameters,
+        historySize: executionHistory.length
+    });
+}
+/**
+ * Get command execution history
+ *
+ * @param limit - Maximum number of results to return (default: 100)
+ * @returns Array of command execution results, most recent first
+ */
+export function getExecutionHistory(limit = 100) {
+    const limitedHistory = executionHistory.slice(-limit).reverse();
+    logger.debug('Retrieved execution history', {
+        requestedLimit: limit,
+        returnedCount: limitedHistory.length,
+        totalHistorySize: executionHistory.length
+    });
+    return limitedHistory;
+}
+/**
+ * Clear execution history
+ * Useful for testing or memory management
+ *
+ * @returns Number of entries cleared
+ */
+export function clearExecutionHistory() {
+    const count = executionHistory.length;
+    executionHistory.length = 0;
+    logger.info('Cleared execution history', { clearedCount: count });
+    return count;
+}
+async function collectCommandArtifacts(artifactPaths, trustedWorkingDirectory) {
+    if (!Array.isArray(artifactPaths) || artifactPaths.length === 0) {
+        return [];
+    }
+    const trustedCanonical = canonicalizePath(trustedWorkingDirectory);
+    const artifacts = [];
+    for (const rawPath of artifactPaths) {
+        if (typeof rawPath !== 'string') {
+            continue;
+        }
+        const candidate = stripWrappingQuotes(rawPath);
+        if (!candidate) {
+            continue;
+        }
+        const resolvedPath = resolveTokenPath(candidate, trustedWorkingDirectory);
+        if (!isPathWithinTrustedDirectory(resolvedPath, trustedWorkingDirectory)) {
+            throw new Error(`Working directory mismatch: artifact path "${candidate}" is outside world working directory "${trustedWorkingDirectory}".`);
+        }
+        const statFn = fsPromises.stat;
+        if (typeof statFn === 'function') {
+            let stat;
+            try {
+                stat = await statFn(resolvedPath);
+            }
+            catch {
+                throw new Error(`Artifact not found: "${candidate}"`);
+            }
+            if (typeof stat?.isFile === 'function' && !stat.isFile()) {
+                throw new Error(`Artifact path is not a file: "${candidate}"`);
+            }
+        }
+        const readFileFn = fsPromises.readFile;
+        let fileBuffer = '';
+        if (typeof readFileFn === 'function') {
+            try {
+                const readResult = await readFileFn(resolvedPath);
+                fileBuffer = (readResult ?? '');
+            }
+            catch {
+                throw new Error(`Artifact not found: "${candidate}"`);
+            }
+        }
+        const sha256 = createHash('sha256').update(fileBuffer).digest('hex');
+        const bytes = Buffer.isBuffer(fileBuffer)
+            ? fileBuffer.byteLength
+            : Buffer.byteLength(fileBuffer);
+        const canonicalArtifactPath = canonicalizePath(resolvedPath);
+        const relativePath = relative(trustedCanonical, canonicalArtifactPath).replace(/\\/g, '/');
+        const isOutsideTrusted = relativePath.startsWith('..') || !relativePath;
+        artifacts.push({
+            path: isOutsideTrusted ? candidate : relativePath,
+            sha256,
+            bytes
+        });
+    }
+    return artifacts;
+}
+export function formatStructuredResult(result, artifacts = [], options = {}) {
+    const detail = options.detail ?? 'minimal';
+    const maxOutputChars = options.maxOutputChars ?? DEFAULT_MIN_OUTPUT_CHARS;
+    const stdoutSnippet = detail === 'full'
+        ? { text: result.stdout, truncated: false }
+        : buildOutputSnippet(result.stdout, maxOutputChars);
+    const stderrSnippet = detail === 'full'
+        ? { text: result.stderr, truncated: false }
+        : buildOutputSnippet(result.stderr, maxOutputChars);
+    return {
+        exit_code: result.exitCode,
+        stdout: stdoutSnippet.text,
+        stderr: stderrSnippet.text,
+        timed_out: Boolean(result.timedOut || result.error?.includes('timed out')),
+        duration_ms: result.duration,
+        artifacts,
+        ...(stdoutSnippet.truncated ? { stdout_truncated: true } : {}),
+        ...(stderrSnippet.truncated ? { stderr_truncated: true } : {})
+    };
+}
+/**
+ * Format command execution result for LLM consumption
+ * Provides a human-readable summary of the execution with improved markdown formatting
+ *
+ * @param result - Command execution result
+ * @returns Formatted markdown string suitable for LLM and display
+ */
+export function formatResultForLLM(result, options = {}) {
+    const detail = options.detail ?? 'minimal';
+    const maxOutputChars = options.maxOutputChars ?? DEFAULT_MIN_OUTPUT_CHARS;
+    const stdoutSnippet = detail === 'full'
+        ? { text: result.stdout, truncated: false }
+        : buildOutputSnippet(result.stdout, maxOutputChars);
+    const stderrSnippet = detail === 'full'
+        ? { text: result.stderr, truncated: false }
+        : buildOutputSnippet(result.stderr, maxOutputChars);
+    const parts = [];
+    // Command info section
+    parts.push('### Command Execution');
+    parts.push('');
+    // Quote parameters that contain spaces or special characters
+    const quotedParams = result.parameters.map(param => {
+        if (param.includes(' ') || param.includes('\t') || param.includes('\n')) {
+            return `"${param.replace(/"/g, '\\"')}"`;
+        }
+        return param;
+    });
+    parts.push(`**Command:** \`${result.command} ${quotedParams.join(' ')}\``);
+    parts.push(`**Duration:** ${result.duration}ms`);
+    if (detail === 'full') {
+        parts.push(`**Executed at:** ${result.executedAt.toISOString()}`);
+    }
+    if (result.error) {
+        parts.push(`**Status:** ❌ Error`);
+        parts.push(`**Error:** ${result.error}`);
+    }
+    else {
+        parts.push(`**Status:** ${result.exitCode === 0 ? '✅' : '⚠️'} Exit code ${result.exitCode}`);
+    }
+    // Standard output section
+    if (stdoutSnippet.text) {
+        parts.push('');
+        parts.push(detail === 'full' ? '### Standard Output' : '### Standard Output (preview)');
+        parts.push('');
+        parts.push('```');
+        parts.push(stdoutSnippet.text);
+        parts.push('```');
+        if (stdoutSnippet.truncated) {
+            parts.push('*(Output truncated to minimum necessary preview. Use `output_detail: "full"` for full output.)*');
+        }
+    }
+    // Standard error section (only show if there's content)
+    if (stderrSnippet.text) {
+        parts.push('');
+        parts.push(detail === 'full' ? '### Standard Error' : '### Standard Error (preview)');
+        parts.push('');
+        parts.push('```');
+        parts.push(stderrSnippet.text);
+        parts.push('```');
+        if (stderrSnippet.truncated) {
+            parts.push('*(Error output truncated to minimum necessary preview. Use `output_detail: "full"` for full output.)*');
+        }
+    }
+    // No output case
+    if (!stdoutSnippet.text && !stderrSnippet.text && !result.error) {
+        parts.push('');
+        parts.push('*(No output)*');
+    }
+    return parts.join('\n');
+}
+/**
+ * Create MCP-compatible tool definition for shell_cmd
+ * This tool can be registered with the MCP system for LLM use
+ *
+ * @returns MCP tool definition object
+ */
+export function createShellCmdToolDefinition() {
+    return {
+        description: 'Execute a user-requested shell command and capture output. Use this only when the user explicitly asks to run a command. Contract: `command` must be a single executable token, and each argument must be a separate `parameters` token (no mini-scripts in `command`). Working directory is resolved from trusted world context (`working_directory`) and defaults to the core default working directory (user home by default) when unset. Optional `directory` is allowed only when it resolves inside trusted scope; outside-scope requests are rejected. Path-like command arguments are scope-validated. Shell control syntax is blocked (`&&`, `||`, pipes, redirects, command substitution, backgrounding), and inline eval modes (for example `sh -c`, `node -e`, `python -c`, `powershell -Command`) are blocked. Execution uses OS shell mode (`shell: true`), so do not pass untrusted text as command content. Optional `output_format` supports `markdown` (default) and `json`; `output_detail` defaults to `minimal` to return minimum necessary output and can be set to `full`; `artifact_paths` can include files to hash and report in output metadata.',
+        parameters: {
+            type: 'object',
+            properties: {
+                command: {
+                    type: 'string',
+                    description: 'The shell command to execute (e.g., "ls", "echo", "cat", "grep")'
+                },
+                parameters: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Array of parameters/arguments for the command (e.g., ["-la", "./src"]). Pass each argument as a separate token.'
+                },
+                directory: {
+                    type: 'string',
+                    description: 'Optional model-provided target directory. Runtime allows this only when it resolves inside trusted world working-directory scope; outside-scope requests are rejected. If user asks for a target folder, set it here.'
+                },
+                timeout: {
+                    type: 'number',
+                    description: 'Timeout in milliseconds (default: 600000 = 10 minutes). Command will be terminated if it exceeds this time.'
+                },
+                output_format: {
+                    type: 'string',
+                    enum: ['markdown', 'json'],
+                    description: 'Output format for tool result. Use "markdown" (default) for human-readable output or "json" for structured output.'
+                },
+                output_detail: {
+                    type: 'string',
+                    enum: ['minimal', 'full'],
+                    description: 'Output detail level. `minimal` (default) returns bounded previews and essential metadata only; `full` returns complete stdout/stderr and timestamp fields.'
+                },
+                artifact_paths: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional file paths (within trusted working-directory scope) to include as hashed artifacts in result output.'
+                }
+            },
+            required: ['command'],
+            additionalProperties: false
+        },
+        execute: async (args, sequenceId, parentToolCall, context) => {
+            // Universal parameter validation
+            const toolSchema = {
+                type: 'object',
+                properties: {
+                    command: {
+                        type: 'string',
+                        description: 'The shell command to execute (e.g., "ls", "echo", "cat", "grep")'
+                    },
+                    parameters: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Array of parameters/arguments for the command (e.g., ["-la", "./src"]). Pass each argument as a separate token.'
+                    },
+                    directory: {
+                        type: 'string',
+                        description: 'Optional model-provided target directory. Runtime allows this only when it resolves inside trusted world working-directory scope; outside-scope requests are rejected. If user asks for a target folder, set it here.'
+                    },
+                    timeout: {
+                        type: 'number',
+                        description: 'Timeout in milliseconds (default: 600000 = 10 minutes). Command will be terminated if it exceeds this time.'
+                    },
+                    output_format: {
+                        type: 'string',
+                        enum: ['markdown', 'json'],
+                        description: 'Output format for tool result. Use "markdown" (default) for human-readable output or "json" for structured output.'
+                    },
+                    output_detail: {
+                        type: 'string',
+                        enum: ['minimal', 'full'],
+                        description: 'Output detail level. `minimal` (default) returns bounded previews and essential metadata only; `full` returns complete stdout/stderr and timestamp fields.'
+                    },
+                    artifact_paths: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Optional file paths (within trusted working-directory scope) to include as hashed artifacts in result output.'
+                    }
+                },
+                required: ['command']
+            };
+            const validation = validateToolParameters(args, toolSchema, 'shell_cmd');
+            if (!validation.valid) {
+                return formatResultForLLM({
+                    executionId: 'validation-error',
+                    command: args?.command || '<invalid>',
+                    parameters: [],
+                    exitCode: 1,
+                    signal: null,
+                    error: validation.error,
+                    stdout: '',
+                    stderr: '',
+                    executedAt: new Date(),
+                    duration: 0
+                });
+            }
+            const { command, parameters = [], timeout, output_format: outputFormat = 'markdown', output_detail: outputDetail = 'minimal', artifact_paths: artifactPaths = [] } = validation.correctedArgs;
+            // Ensure parameters is always an array
+            const validParameters = Array.isArray(parameters) ?
+                parameters.filter((p) => typeof p === 'string') :
+                [];
+            // Extract world and messageId from context for streaming
+            const world = context?.world;
+            const currentMessageId = context?.toolCallId;
+            const chatId = context?.chatId ? String(context.chatId) : undefined;
+            const abortSignal = context?.abortSignal;
+            const resolvedDirectory = resolveTrustedShellWorkingDirectory(context);
+            const directoryValidation = validateShellDirectoryRequest(validation.correctedArgs.directory, resolvedDirectory);
+            if (!directoryValidation.valid) {
+                throw new Error(directoryValidation.error);
+            }
+            const scopeValidation = validateShellCommandScope(command, validParameters, resolvedDirectory);
+            if (!scopeValidation.valid) {
+                throw new Error(scopeValidation.error);
+            }
+            // Execute command with streaming callbacks if world is available
+            const result = await executeShellCommand(command, validParameters, resolvedDirectory, {
+                timeout,
+                abortSignal,
+                worldId: world?.id,
+                chatId,
+                trustedWorkingDirectory: resolvedDirectory,
+                onStdout: world ? (chunk) => {
+                    // Publish streaming events to world event system
+                    publishSSE(world, {
+                        type: 'tool-stream',
+                        toolName: 'shell_cmd',
+                        content: chunk,
+                        stream: 'stdout',
+                        messageId: currentMessageId,
+                        agentName: 'shell_cmd'
+                    });
+                } : undefined,
+                onStderr: world ? (chunk) => {
+                    // Publish streaming events to world event system
+                    publishSSE(world, {
+                        type: 'tool-stream',
+                        toolName: 'shell_cmd',
+                        content: chunk,
+                        stream: 'stderr',
+                        messageId: currentMessageId,
+                        agentName: 'shell_cmd'
+                    });
+                } : undefined
+            });
+            if (isCommandExecutionCanceled(result)) {
+                throw new DOMException('Shell command execution canceled by user', 'AbortError');
+            }
+            const validatedArtifactPaths = Array.isArray(artifactPaths)
+                ? artifactPaths.filter((artifactPath) => typeof artifactPath === 'string')
+                : [];
+            const artifacts = await collectCommandArtifacts(validatedArtifactPaths, resolvedDirectory);
+            if (outputFormat === 'json') {
+                return JSON.stringify(formatStructuredResult(result, artifacts, { detail: outputDetail }), null, 2);
+            }
+            return formatResultForLLM(result, { detail: outputDetail });
+        }
+    };
+}
+//# sourceMappingURL=shell-cmd-tool.js.map