sub-agents-mcp 0.14.1 → 0.14.2

package/dist/execution/AgentExecutor.js

@@ -3,7 +3,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { StringDecoder } from 'node:string_decoder';
-import { Logger } from '../utils/Logger.js';
+import { toErrorMessage } from '../utils/ErrorHandler.js';
+import { isLogLevel, Logger } from '../utils/Logger.js';
 import { StreamProcessor } from './StreamProcessor.js';
 export const DEFAULT_EXECUTION_TIMEOUT = 300000; // 5 minutes
 const MAX_CAPTURED_OUTPUT_BYTES = 16 * 1024 * 1024;
@@ -31,7 +32,7 @@ export const AGENT_TYPES = [
     'command-code',
 ];
 export function isAgentType(value) {
-    return typeof value === 'string' && AGENT_TYPES.includes(value);
+    return typeof value === 'string' && AGENT_TYPES.some((agentType) => agentType === value);
 }
 export const AGENT_EFFORT_SUPPORTED_TYPES = [
     'codex',
@@ -44,11 +45,11 @@ export const AGENT_EFFORT_SUPPORTED_TYPES = [
     'command-code',
 ];
 export function supportsAgentEffort(agentType) {
-    return AGENT_EFFORT_SUPPORTED_TYPES.includes(agentType);
+    return AGENT_EFFORT_SUPPORTED_TYPES.some((supported) => supported === agentType);
 }
 export const AGENT_PERMISSIONS = ['read-only', 'safe-edit', 'yolo'];
 export function isAgentPermission(value) {
-    return typeof value === 'string' && AGENT_PERMISSIONS.includes(value);
+    return typeof value === 'string' && AGENT_PERMISSIONS.some((permission) => permission === value);
 }
 export const DEFAULT_AGENT_PERMISSION = 'safe-edit';
 const PERMISSION_FLAGS = {
@@ -135,14 +136,258 @@ export function createExecutionConfig(agentType, overrides) {
         agentType,
     };
 }
+/** Reads LOG_LEVEL from the environment, falling back to `info` when unset or invalid. */
+function resolveLogLevelFromEnv() {
+    const value = process.env['LOG_LEVEL'];
+    return isLogLevel(value) ? value : 'info';
+}
+function errorCode(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error)) {
+        return undefined;
+    }
+    return typeof error.code === 'string' ? error.code : undefined;
+}
+function signalNumber(signal) {
+    if (signal === 'SIGTERM') {
+        return 15;
+    }
+    if (signal === 'SIGKILL') {
+        return 9;
+    }
+    return 1;
+}
+/**
+ * Owns the lifecycle of one spawned agent process: output capture with a byte
+ * cap, incremental stream parsing, timeout-driven termination, and settlement
+ * into a single {@link SpawnOutcome}.
+ */
+class SpawnSession {
+    childProcess;
+    config;
+    logger;
+    cleanup;
+    streamProcessor;
+    stdoutParts = [];
+    stderrParts = [];
+    stdoutDecoder = new StringDecoder('utf8');
+    stderrDecoder = new StringDecoder('utf8');
+    stdoutLineParts = [];
+    stdoutTruncated = false;
+    stderrTruncated = false;
+    capturedBytes = 0;
+    timedOut = false;
+    cancelled = false;
+    outputExceeded = false;
+    processError;
+    settled = false;
+    forceKillTimer;
+    executionTimeout;
+    constructor(childProcess, config, logger, cleanup) {
+        this.childProcess = childProcess;
+        this.config = config;
+        this.logger = logger;
+        this.cleanup = cleanup;
+        this.streamProcessor = new StreamProcessor(config.agentType);
+    }
+    run(cancelSignal) {
+        return new Promise((resolve) => {
+            if (cancelSignal) {
+                // Reuses the same graceful SIGTERM -> SIGKILL path as a timeout, so a
+                // cancelled request cannot leave the CLI running.
+                if (cancelSignal.aborted) {
+                    queueMicrotask(() => this.cancel());
+                }
+                else {
+                    cancelSignal.addEventListener('abort', () => this.cancel(), { once: true });
+                }
+            }
+            const settle = (code, signal) => {
+                if (this.settled) {
+                    return;
+                }
+                this.settled = true;
+                this.finish(code, signal).then(resolve, (error) => {
+                    resolve({
+                        stdout: '',
+                        stderr: toErrorMessage(error),
+                        exitCode: 1,
+                        hasResult: false,
+                    });
+                });
+            };
+            this.executionTimeout = setTimeout(() => {
+                this.timedOut = true;
+                this.logger.warn('Execution timeout reached', { timeout: this.config.executionTimeout });
+                this.requestTermination();
+            }, this.config.executionTimeout);
+            this.childProcess.stdout?.on('data', (data) => {
+                this.consumeStdout(data);
+            });
+            this.childProcess.stderr?.on('data', (data) => {
+                this.stderrParts.push(this.captureChunk(data, this.stderrDecoder, () => {
+                    this.stderrTruncated = true;
+                }));
+            });
+            this.childProcess.on('close', (code, signal) => {
+                settle(code, signal);
+            });
+            this.childProcess.on('error', (error) => {
+                this.processError = error;
+                settle(null);
+            });
+        });
+    }
+    /**
+     * Stops the agent process, whether the client cancelled the request or the
+     * server is shutting down. Reuses the graceful SIGTERM -> SIGKILL escalation.
+     */
+    cancel() {
+        if (this.settled || this.cancelled) {
+            return;
+        }
+        this.cancelled = true;
+        this.logger.info('Execution cancelled before the agent finished');
+        this.requestTermination();
+    }
+    clearTimers() {
+        if (this.executionTimeout) {
+            clearTimeout(this.executionTimeout);
+        }
+        if (this.forceKillTimer) {
+            clearTimeout(this.forceKillTimer);
+        }
+    }
+    requestTermination() {
+        this.childProcess.kill('SIGTERM');
+        if (this.forceKillTimer) {
+            return;
+        }
+        this.forceKillTimer = setTimeout(() => {
+            this.childProcess.kill('SIGKILL');
+        }, TERMINATION_GRACE_MS);
+    }
+    /**
+     * Copies at most the remaining byte budget out of `data`, flagging truncation
+     * and terminating the process once the cap is reached.
+     */
+    captureChunk(data, decoder, markTruncated) {
+        const remaining = this.config.maxOutputBytes - this.capturedBytes;
+        if (remaining <= 0) {
+            this.outputExceeded = true;
+            markTruncated();
+            this.requestTermination();
+            return '';
+        }
+        const captured = data.length <= remaining ? data : data.subarray(0, remaining);
+        this.capturedBytes += captured.length;
+        if (captured.length < data.length) {
+            this.outputExceeded = true;
+            markTruncated();
+            this.requestTermination();
+        }
+        return decoder.write(captured);
+    }
+    consumeStdout(data) {
+        const chunk = this.captureChunk(data, this.stdoutDecoder, () => {
+            this.stdoutTruncated = true;
+        });
+        this.stdoutParts.push(chunk);
+        let chunkOffset = 0;
+        while (chunkOffset < chunk.length) {
+            const newlineIndex = chunk.indexOf('\n', chunkOffset);
+            if (newlineIndex < 0) {
+                this.stdoutLineParts.push(chunk.slice(chunkOffset));
+                break;
+            }
+            this.stdoutLineParts.push(chunk.slice(chunkOffset, newlineIndex));
+            const line = this.stdoutLineParts.join('');
+            this.stdoutLineParts = [];
+            chunkOffset = newlineIndex + 1;
+            if (this.streamProcessor.processLine(line)) {
+                this.requestTermination();
+                break;
+            }
+        }
+    }
+    /** Flushes both decoders and parses any line left without a trailing newline. */
+    flushStreams() {
+        if (!this.stdoutTruncated) {
+            const tail = this.stdoutDecoder.end();
+            this.stdoutParts.push(tail);
+            this.stdoutLineParts.push(tail);
+        }
+        if (!this.stderrTruncated) {
+            this.stderrParts.push(this.stderrDecoder.end());
+        }
+        const trailingLine = this.stdoutLineParts.join('');
+        if (trailingLine.trim()) {
+            this.streamProcessor.processLine(trailingLine);
+        }
+        this.stdoutLineParts = [];
+    }
+    resolveExitCode(code, signal) {
+        if (this.outputExceeded || this.processError) {
+            return errorCode(this.processError) === 'ENOENT' ? 127 : 1;
+        }
+        if (this.timedOut) {
+            return 124;
+        }
+        if (this.cancelled) {
+            return 130;
+        }
+        return code ?? (signal ? 128 + signalNumber(signal) : 1);
+    }
+    collectErrors(stderr) {
+        const errors = [];
+        if (stderr) {
+            errors.push(stderr);
+        }
+        if (this.timedOut) {
+            errors.push(`Execution timeout: ${this.config.executionTimeout}ms`);
+        }
+        if (this.cancelled) {
+            errors.push('Execution was cancelled by the client before the agent finished.');
+        }
+        if (this.outputExceeded) {
+            errors.push(`Sub-agent output exceeded ${this.config.maxOutputBytes} bytes`);
+        }
+        if (this.processError && !stderr) {
+            errors.push(this.processError.message);
+        }
+        return errors;
+    }
+    async finish(code, signal) {
+        this.clearTimers();
+        this.flushStreams();
+        const stdout = this.stdoutParts.join('');
+        const stderr = this.stderrParts.join('');
+        let result = this.streamProcessor.getResult();
+        if (result === null) {
+            this.streamProcessor.processCompleteOutput(stdout);
+            result = this.streamProcessor.getResult();
+        }
+        await this.cleanup();
+        return {
+            stdout: result ? JSON.stringify(result) : stdout,
+            stderr: this.collectErrors(stderr).join('\n'),
+            exitCode: this.resolveExitCode(code, signal),
+            hasResult: result !== null,
+            resultJson: result !== null ? result : undefined,
+        };
+    }
+}
 export class AgentExecutor {
     config;
     logger;
     constructor(config, logger) {
         this.config = config;
-        this.logger = logger || new Logger(process.env['LOG_LEVEL'] || 'info');
+        this.logger = logger || new Logger(resolveLogLevelFromEnv());
     }
-    async executeAgent(params) {
+    /**
+     * Guards against untrusted callers that bypass the declared parameter type
+     * (for example MCP requests deserialized as `unknown`).
+     */
+    assertExecutableParams(params) {
         if (!params?.agent || !params.prompt) {
             const error = 'Invalid execution parameters: agent and prompt are required';
             this.logger.error('Agent execution failed during validation', undefined, { error, params });
@@ -153,6 +398,17 @@ export class AgentExecutor {
             this.logger.error('Agent execution failed during validation', undefined, { error, params });
             throw new Error(error);
         }
+    }
+    /** Sessions still running, so shutdown does not orphan agent processes. */
+    activeSessions = new Set();
+    /** Terminates every agent process this executor still has running. */
+    terminateAll() {
+        for (const session of this.activeSessions) {
+            session.cancel();
+        }
+    }
+    async executeAgent(params, signal) {
+        this.assertExecutableParams(params);
         const startTime = Date.now();
         const requestId = this.generateRequestId();
         this.logger.info('Starting agent execution', {
@@ -160,12 +416,9 @@ export class AgentExecutor {
             agent: params.agent,
             promptLength: params.prompt.length,
             cwd: params.cwd,
-            extraArgs: params.extra_args?.length || 0,
         });
         try {
-            // Add minimal delay to ensure execution time is measurable
-            await new Promise((resolve) => setTimeout(resolve, 1));
-            const result = await this.executeWithSpawn(params);
+            const result = await this.executeWithSpawn(params, signal);
             const executionTime = Date.now() - startTime;
             this.logger.info('Agent execution completed', {
                 requestId,
@@ -180,6 +433,7 @@ export class AgentExecutor {
                 executionTime,
                 ...(result.hasResult !== undefined && { hasResult: result.hasResult }),
                 ...(result.resultJson !== undefined && { resultJson: result.resultJson }),
+                ...(result.failureReason !== undefined && { failureReason: result.failureReason }),
             };
         }
         catch (error) {
@@ -188,10 +442,6 @@ export class AgentExecutor {
                 requestId,
                 executionTime,
             });
-            if (error instanceof Error &&
-                (error.message.includes('enhance') || error.message.includes('Enhancement'))) {
-                throw error;
-            }
             return {
                 stdout: '',
                 stderr: error instanceof Error ? error.message : 'Unknown execution error',
@@ -229,8 +479,9 @@ export class AgentExecutor {
     }
     buildSettingsPathEnv() {
         const env = {};
-        if (!this.config.agentsSettingsPath)
+        if (!this.config.agentsSettingsPath) {
             return env;
+        }
         switch (this.config.agentType) {
             case 'cursor':
                 env['CURSOR_CONFIG_DIR'] = this.config.agentsSettingsPath;
@@ -331,16 +582,25 @@ export class AgentExecutor {
         if (!apiKey?.trim()) {
             throw new Error(GLM_MISSING_API_KEY_ERROR);
         }
-        return this.buildRedirectedClaudeArgs(params, envOverrides, GLM_BASE_URL, apiKey, 'ANTHROPIC_AUTH_TOKEN');
+        return this.buildRedirectedClaudeArgs(params, envOverrides, {
+            baseUrl: GLM_BASE_URL,
+            apiKey,
+            credentialEnv: 'ANTHROPIC_AUTH_TOKEN',
+        });
     }
     buildKimiArgs(params, envOverrides) {
         const apiKey = this.config.kimiApiKey;
         if (!apiKey?.trim()) {
             throw new Error(KIMI_MISSING_API_KEY_ERROR);
         }
-        return this.buildRedirectedClaudeArgs(params, envOverrides, KIMI_BASE_URL, apiKey, 'ANTHROPIC_API_KEY');
+        return this.buildRedirectedClaudeArgs(params, envOverrides, {
+            baseUrl: KIMI_BASE_URL,
+            apiKey,
+            credentialEnv: 'ANTHROPIC_API_KEY',
+        });
     }
-    buildRedirectedClaudeArgs(params, envOverrides, baseUrl, apiKey, credentialEnv) {
+    buildRedirectedClaudeArgs(params, envOverrides, redirect) {
+        const { baseUrl, apiKey, credentialEnv } = redirect;
         const flags = this.invocationFlags();
         const cwd = params.cwd || process.cwd();
         const systemPrompt = `cwd: ${cwd}\n\n${params.agent}`;
@@ -459,10 +719,10 @@ export class AgentExecutor {
                 await fs.promises.copyFile(authSource, authDestination);
             }
             catch (error) {
-                const code = this.errorCode(error);
+                const code = errorCode(error);
                 if (code !== 'ENOENT') {
                     this.logger.warn('Could not copy OpenCode authentication into isolated data home', {
-                        error: error instanceof Error ? error.message : String(error),
+                        error: toErrorMessage(error),
                     });
                 }
             }
@@ -482,189 +742,61 @@ export class AgentExecutor {
             throw error;
         }
     }
-    errorCode(error) {
-        if (typeof error !== 'object' || error === null || !('code' in error)) {
-            return undefined;
-        }
-        return typeof error.code === 'string' ? error.code : undefined;
-    }
-    async executeWithSpawn(params) {
+    async executeWithSpawn(params, signal) {
         const { command, args, envOverrides } = this.buildCommandArgs(params);
         const preparedEnvironment = await this.prepareSpawnEnvironment(envOverrides);
-        return new Promise((resolve) => {
-            this.logger.debug('Executing with spawn', {
-                command,
+        this.logger.debug('Executing with spawn', {
+            command,
+            cwd: params.cwd || process.cwd(),
+        });
+        let childProcess;
+        try {
+            childProcess = spawn(command, args, {
                 cwd: params.cwd || process.cwd(),
+                stdio: ['ignore', 'pipe', 'pipe'],
+                shell: false,
+                env: preparedEnvironment.env,
             });
-            let childProcess;
-            try {
-                childProcess = spawn(command, args, {
-                    cwd: params.cwd || process.cwd(),
-                    stdio: ['ignore', 'pipe', 'pipe'],
-                    shell: false,
-                    env: preparedEnvironment.env,
-                });
-            }
-            catch (error) {
-                void preparedEnvironment.cleanup().finally(() => {
-                    resolve({
-                        stdout: '',
-                        stderr: error instanceof Error ? error.message : String(error),
-                        exitCode: this.errorCode(error) === 'ENOENT' ? 127 : 1,
-                        hasResult: false,
-                    });
-                });
-                return;
+        }
+        catch (error) {
+            await this.cleanupQuietly(preparedEnvironment.cleanup);
+            if (errorCode(error) === 'E2BIG') {
+                const promptBytes = Buffer.byteLength(params.prompt, 'utf8');
+                return {
+                    stdout: '',
+                    stderr: `The prompt is too large to pass to the "${command}" CLI: ` +
+                        `${promptBytes} bytes exceeds this operating system's argument limit.`,
+                    exitCode: 1,
+                    hasResult: false,
+                    failureReason: 'argv_too_long',
+                };
             }
-            const streamProcessor = new StreamProcessor(this.config.agentType);
-            const stdoutParts = [];
-            const stderrParts = [];
-            let stdoutLineParts = [];
-            const stdoutDecoder = new StringDecoder('utf8');
-            const stderrDecoder = new StringDecoder('utf8');
-            let stdoutTruncated = false;
-            let stderrTruncated = false;
-            let capturedBytes = 0;
-            let timedOut = false;
-            let outputExceeded = false;
-            let processError;
-            let settled = false;
-            let forceKillTimer;
-            const executionTimeout = setTimeout(() => {
-                timedOut = true;
-                this.logger.warn('Execution timeout reached', {
-                    timeout: this.config.executionTimeout,
-                });
-                requestTermination();
-            }, this.config.executionTimeout);
-            const clearTimers = () => {
-                clearTimeout(executionTimeout);
-                if (forceKillTimer)
-                    clearTimeout(forceKillTimer);
-            };
-            const finish = async (code, signal) => {
-                if (settled)
-                    return;
-                settled = true;
-                clearTimers();
-                if (!stdoutTruncated) {
-                    const tail = stdoutDecoder.end();
-                    stdoutParts.push(tail);
-                    stdoutLineParts.push(tail);
-                }
-                if (!stderrTruncated) {
-                    stderrParts.push(stderrDecoder.end());
-                }
-                const trailingLine = stdoutLineParts.join('');
-                if (trailingLine.trim()) {
-                    streamProcessor.processLine(trailingLine);
-                }
-                stdoutLineParts = [];
-                const stdout = stdoutParts.join('');
-                const stderr = stderrParts.join('');
-                let result = streamProcessor.getResult();
-                if (result === null) {
-                    streamProcessor.processCompleteOutput(stdout);
-                    result = streamProcessor.getResult();
-                }
-                let exitCode = code ?? (signal ? 128 + this.signalNumber(signal) : 1);
-                if (timedOut)
-                    exitCode = 124;
-                if (outputExceeded || processError)
-                    exitCode = this.errorCode(processError) === 'ENOENT' ? 127 : 1;
-                const errors = [];
-                if (stderr)
-                    errors.push(stderr);
-                if (timedOut)
-                    errors.push(`Execution timeout: ${this.config.executionTimeout}ms`);
-                if (outputExceeded) {
-                    errors.push(`Sub-agent output exceeded ${this.config.maxOutputBytes} bytes`);
-                }
-                if (processError && !stderr)
-                    errors.push(processError.message);
-                try {
-                    await preparedEnvironment.cleanup();
-                }
-                catch (error) {
-                    this.logger.warn('Failed to clean up per-run environment', {
-                        error: error instanceof Error ? error.message : String(error),
-                    });
-                }
-                resolve({
-                    stdout: result ? JSON.stringify(result) : stdout,
-                    stderr: errors.join('\n'),
-                    exitCode,
-                    hasResult: result !== null,
-                    resultJson: result !== null ? result : undefined,
-                });
-            };
-            const requestTermination = () => {
-                childProcess.kill('SIGTERM');
-                if (forceKillTimer)
-                    return;
-                forceKillTimer = setTimeout(() => {
-                    childProcess.kill('SIGKILL');
-                }, TERMINATION_GRACE_MS);
-            };
-            const captureChunk = (data, decoder, markTruncated) => {
-                const remaining = this.config.maxOutputBytes - capturedBytes;
-                if (remaining <= 0) {
-                    outputExceeded = true;
-                    markTruncated();
-                    requestTermination();
-                    return '';
-                }
-                const captured = data.length <= remaining ? data : data.subarray(0, remaining);
-                capturedBytes += captured.length;
-                if (captured.length < data.length) {
-                    outputExceeded = true;
-                    markTruncated();
-                    requestTermination();
-                }
-                return decoder.write(captured);
+            return {
+                stdout: '',
+                stderr: toErrorMessage(error),
+                exitCode: errorCode(error) === 'ENOENT' ? 127 : 1,
+                hasResult: false,
             };
-            childProcess.stdout?.on('data', (data) => {
-                const chunk = captureChunk(data, stdoutDecoder, () => {
-                    stdoutTruncated = true;
-                });
-                stdoutParts.push(chunk);
-                let chunkOffset = 0;
-                while (chunkOffset < chunk.length) {
-                    const newlineIndex = chunk.indexOf('\n', chunkOffset);
-                    if (newlineIndex < 0) {
-                        stdoutLineParts.push(chunk.slice(chunkOffset));
-                        break;
-                    }
-                    stdoutLineParts.push(chunk.slice(chunkOffset, newlineIndex));
-                    const line = stdoutLineParts.join('');
-                    stdoutLineParts = [];
-                    chunkOffset = newlineIndex + 1;
-                    if (streamProcessor.processLine(line)) {
-                        requestTermination();
-                        break;
-                    }
-                }
-            });
-            childProcess.stderr?.on('data', (data) => {
-                stderrParts.push(captureChunk(data, stderrDecoder, () => {
-                    stderrTruncated = true;
-                }));
-            });
-            childProcess.on('close', (code, signal) => {
-                void finish(code, signal);
-            });
-            childProcess.on('error', (error) => {
-                processError = error;
-                void finish(null);
-            });
-        });
+        }
+        const session = new SpawnSession(childProcess, this.config, this.logger, () => this.cleanupQuietly(preparedEnvironment.cleanup));
+        this.activeSessions.add(session);
+        try {
+            return await session.run(signal);
+        }
+        finally {
+            this.activeSessions.delete(session);
+        }
     }
-    signalNumber(signal) {
-        if (signal === 'SIGTERM')
-            return 15;
-        if (signal === 'SIGKILL')
-            return 9;
-        return 1;
+    /** Runs a cleanup callback, logging rather than propagating its failures. */
+    async cleanupQuietly(cleanup) {
+        try {
+            await cleanup();
+        }
+        catch (error) {
+            this.logger.warn('Failed to clean up per-run environment', {
+                error: toErrorMessage(error),
+            });
+        }
     }
     generateRequestId() {
         return `req_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;