@aria-cli/tools 1.0.12 → 1.0.14

package/dist/executors/shell.js

@@ -1,954 +0,0 @@
-/**
- * @aria/tools - Shell tool executors
- *
- * Implementation of shell operations for ARIA tool system.
- */
-import { spawn } from "node:child_process";
-import { constants as osConstants } from "node:os";
-import { success, fail, getErrorMessage } from "./utils.js";
-import { classifyCommand, classifyExecInvocation } from "./shell-safety.js";
-/**
- * Environment variables that are dangerous in ALL contexts — including
- * the host's own process.env. These enable code injection or library
- * hijacking and should never reach child processes.
- */
-export const BLOCKED_ENV_VARS = new Set([
-    "LD_PRELOAD",
-    "LD_LIBRARY_PATH",
-    "DYLD_INSERT_LIBRARIES",
-    "DYLD_FRAMEWORK_PATH",
-    "DYLD_LIBRARY_PATH",
-    "BASH_ENV",
-    "ENV",
-    "CDPATH",
-    "GLOBIGNORE",
-    "PROMPT_COMMAND",
-    "SHELLOPTS",
-    "BASHOPTS",
-    // Git context hijacks: inherited vars can redirect repository resolution.
-    "GIT_DIR",
-    "GIT_WORK_TREE",
-    "GIT_INDEX_FILE",
-    "GIT_OBJECT_DIRECTORY",
-    "GIT_ALTERNATE_OBJECT_DIRECTORIES",
-    "GIT_COMMON_DIR",
-    "GIT_PREFIX",
-    "GIT_INTERNAL_SUPER_PREFIX",
-    "GIT_CONFIG",
-    "GIT_CONFIG_GLOBAL",
-    "GIT_CONFIG_SYSTEM",
-    "GIT_CONFIG_COUNT",
-    "GIT_CEILING_DIRECTORIES",
-]);
-/**
- * Git environment keys that can redirect repository/config context or mutate
- * commit identity unexpectedly when inherited by child processes.
- *
- * NOTE: We intentionally keep transport/debug keys like GIT_SSH_COMMAND and
- * GIT_TRACE untouched to avoid breaking legitimate workflows.
- */
-const GIT_BLOCKED_EXACT_KEYS = new Set([
-    "GIT_DIR",
-    "GIT_WORK_TREE",
-    "GIT_INDEX_FILE",
-    "GIT_INDEX_VERSION",
-    "GIT_COMMON_DIR",
-    "GIT_OBJECT_DIRECTORY",
-    "GIT_ALTERNATE_OBJECT_DIRECTORIES",
-    "GIT_CEILING_DIRECTORIES",
-    "GIT_DISCOVERY_ACROSS_FILESYSTEM",
-    "GIT_NAMESPACE",
-    "GIT_CONFIG",
-    "GIT_CONFIG_GLOBAL",
-    "GIT_CONFIG_SYSTEM",
-    "GIT_CONFIG_NOSYSTEM",
-    "GIT_CONFIG_COUNT",
-    "GIT_CONFIG_PARAMETERS",
-]);
-const GIT_BLOCKED_PREFIXES = [
-    "GIT_CONFIG_KEY_",
-    "GIT_CONFIG_VALUE_",
-    "GIT_AUTHOR_",
-    "GIT_COMMITTER_",
-];
-export function isBlockedGitEnvVar(key) {
-    const upper = key.toUpperCase();
-    if (GIT_BLOCKED_EXACT_KEYS.has(upper)) {
-        return true;
-    }
-    return GIT_BLOCKED_PREFIXES.some((prefix) => upper.startsWith(prefix));
-}
-/**
- * Strip git-context env keys from a source env object.
- */
-export function sanitizeGitEnv(env = process.env) {
-    const sanitized = {};
-    for (const [key, value] of Object.entries(env)) {
-        if (value === undefined)
-            continue;
-        if (isBlockedGitEnvVar(key))
-            continue;
-        sanitized[key] = value;
-    }
-    return sanitized;
-}
-/**
- * Additional variables blocked from tool-injected input (inputEnv, ctx.env)
- * but NOT from process.env. The host's PATH/HOME/SHELL are legitimate —
- * only tool-provided overrides are dangerous (hijacking resolution paths).
- */
-export const BLOCKED_INPUT_ENV_VARS = new Set([
-    ...BLOCKED_ENV_VARS,
-    // Executable/module resolution hijacks (aria-mx5)
-    "PATH",
-    "NODE_OPTIONS",
-    "NODE_PATH",
-    "PYTHONPATH",
-    // Shell/environment manipulation
-    "IFS",
-    "HOME",
-    "SHELL",
-    "EDITOR",
-    "VISUAL",
-    // Java runtime hijacks (aria-skg)
-    "JAVA_TOOL_OPTIONS",
-    "_JAVA_OPTIONS",
-    "CLASSPATH",
-    // Ruby runtime hijacks (aria-skg)
-    "RUBYOPT",
-    "GEM_HOME",
-    "GEM_PATH",
-    // Perl runtime hijacks (aria-skg)
-    "PERL5OPT",
-    "PERL5LIB",
-    // Python startup hijack (aria-skg) — PYTHONPATH already covered above
-    "PYTHONSTARTUP",
-]);
-function isBlockedProcessEnvVar(key) {
-    return BLOCKED_ENV_VARS.has(key.toUpperCase()) || isBlockedGitEnvVar(key);
-}
-function isBlockedInputEnvVar(key) {
-    return BLOCKED_INPUT_ENV_VARS.has(key.toUpperCase()) || isBlockedGitEnvVar(key);
-}
-/**
- * Merges environment variables from context and input.
- *
- * Three-tier filtering:
- * - process.env: filtered through BLOCKED_ENV_VARS (injection-only vars like LD_PRELOAD)
- * - ctx.env / inputEnv: filtered through BLOCKED_INPUT_ENV_VARS (also blocks PATH/HOME/SHELL hijacking)
- */
-export function mergeEnv(ctx, inputEnv) {
-    let sanitizedInput = inputEnv;
-    if (inputEnv) {
-        sanitizedInput = {};
-        for (const [key, value] of Object.entries(inputEnv)) {
-            if (isBlockedInputEnvVar(key)) {
-                continue;
-            }
-            sanitizedInput[key] = value;
-        }
-    }
-    let sanitizedCtxEnv = ctx.env;
-    if (ctx.env) {
-        sanitizedCtxEnv = {};
-        for (const [key, value] of Object.entries(ctx.env)) {
-            if (isBlockedInputEnvVar(key)) {
-                continue;
-            }
-            sanitizedCtxEnv[key] = value;
-        }
-    }
-    // Filter process.env through the base blocklist only — the host's
-    // PATH/HOME/SHELL are legitimate and needed by child processes.
-    const sanitizedProcessEnv = {};
-    for (const [key, value] of Object.entries(process.env)) {
-        if (value === undefined)
-            continue;
-        if (isBlockedProcessEnvVar(key)) {
-            continue;
-        }
-        sanitizedProcessEnv[key] = value;
-    }
-    return {
-        ...sanitizedProcessEnv,
-        ...sanitizedCtxEnv,
-        ...sanitizedInput,
-    };
-}
-/**
- * Sanitize environment for child processes without requiring a ToolContext.
- *
- * Applies the same two-tier filtering as mergeEnv:
- * - process.env is filtered through BLOCKED_ENV_VARS
- * - inputEnv (caller-supplied overrides) is filtered through BLOCKED_INPUT_ENV_VARS
- *
- * Intended for executors (e.g. PTY) that do not have a ToolContext.
- */
-export function sanitizeEnv(inputEnv) {
-    // Filter process.env through the base blocklist
-    const sanitizedProcessEnv = {};
-    for (const [key, value] of Object.entries(process.env)) {
-        if (value === undefined)
-            continue;
-        if (isBlockedProcessEnvVar(key)) {
-            continue;
-        }
-        sanitizedProcessEnv[key] = value;
-    }
-    // Filter inputEnv through the stricter input blocklist
-    let sanitizedInput;
-    if (inputEnv) {
-        sanitizedInput = {};
-        for (const [key, value] of Object.entries(inputEnv)) {
-            if (isBlockedInputEnvVar(key)) {
-                continue;
-            }
-            sanitizedInput[key] = value;
-        }
-    }
-    return {
-        ...sanitizedProcessEnv,
-        ...sanitizedInput,
-    };
-}
-/**
- * Executes a command through bash shell.
- * Supports shell features like pipes, redirection, and variable expansion.
- */
-export async function executeBash(input, ctx) {
-    // Shell safety: block catastrophic commands before any execution
-    const risk = classifyCommand(input.command);
-    if (risk === "blocked") {
-        return fail(`Command blocked by shell safety policy: ${input.command}`);
-    }
-    // Check if already aborted before starting
-    if (ctx.abortSignal?.aborted) {
-        return fail("Command cancelled");
-    }
-    const cwd = input.cwd ?? ctx.workingDir;
-    const env = mergeEnv(ctx, input.env);
-    const timeout = input.timeout ?? 120_000;
-    return executeExec({
-        program: "/bin/bash",
-        args: ["-lc", input.command],
-        cwd,
-        env: input.env,
-        timeout,
-    }, {
-        ...ctx,
-        workingDir: cwd,
-        env,
-    });
-}
-function signalExecProcessTree(pid, signal, detachedProcessGroup) {
-    if (!pid) {
-        return;
-    }
-    if (detachedProcessGroup) {
-        try {
-            process.kill(-pid, signal);
-            return;
-        }
-        catch {
-            // Fall back to the leader PID if the process group is already gone or unsupported.
-        }
-    }
-    try {
-        process.kill(pid, signal);
-    }
-    catch {
-        // Process may already be dead.
-    }
-}
-function isExecProcessTreeAlive(pid, detachedProcessGroup) {
-    if (!pid) {
-        return false;
-    }
-    if (detachedProcessGroup) {
-        try {
-            process.kill(-pid, 0);
-            return true;
-        }
-        catch {
-            // Fall through to the leader PID check in case the group probe is unsupported.
-        }
-    }
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-async function waitForExecProcessTreeExit(pid, detachedProcessGroup, timeoutMs = 1_000) {
-    if (!pid) {
-        return;
-    }
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if (!isExecProcessTreeAlive(pid, detachedProcessGroup)) {
-            return;
-        }
-        await new Promise((resolve) => setTimeout(resolve, 25));
-    }
-}
-/**
- * Executes a program directly without shell interpretation.
- * Safer than bash as it doesn't expand shell metacharacters.
- */
-export async function executeExec(input, ctx) {
-    const args = input.args ?? [];
-    // Shell safety: block catastrophic commands before any execution.
-    // For explicit shell wrappers (e.g. bash -c ...), classify payload command.
-    const reconstructed = [input.program, ...args].join(" ");
-    const risk = classifyExecInvocation(input.program, args);
-    if (risk === "blocked") {
-        return fail(`Command blocked by shell safety policy: ${reconstructed}`, {
-            stdout: "",
-            stderr: "",
-            exitCode: 1,
-        });
-    }
-    // Check if already aborted before starting
-    if (ctx.abortSignal?.aborted) {
-        return fail("Command cancelled", {
-            stdout: "",
-            stderr: "",
-            exitCode: 1,
-        });
-    }
-    const cwd = input.cwd ?? ctx.workingDir;
-    const env = mergeEnv(ctx, input.env);
-    const timeout = input.timeout ?? 120_000;
-    return new Promise((resolve) => {
-        const detachedProcessGroup = process.platform !== "win32";
-        const proc = spawn(input.program, args, {
-            cwd,
-            env,
-            detached: detachedProcessGroup,
-        });
-        // Track PID in process registry for cleanup on session close
-        if (proc.pid && ctx.processRegistry) {
-            ctx.processRegistry.add(proc.pid, {
-                command: input.program,
-                args,
-                cwd,
-                interactive: false,
-            });
-        }
-        let stdout = "";
-        let stderr = "";
-        let timedOut = false;
-        let cancelled = false;
-        let resolved = false;
-        let timeoutId;
-        let killTimeoutId;
-        const doResolve = (result, exit) => {
-            if (resolved)
-                return;
-            resolved = true;
-            if (timeoutId)
-                clearTimeout(timeoutId);
-            if (killTimeoutId)
-                clearTimeout(killTimeoutId);
-            // Clean up abort listener
-            if (ctx.abortSignal && onAbort) {
-                ctx.abortSignal.removeEventListener("abort", onAbort);
-            }
-            // Keep detached process groups tracked until the whole group is gone.
-            ctx.processRegistry?.recordExitMetadata?.(proc.pid ?? 0, exit);
-            if (proc.pid &&
-                ctx.processRegistry &&
-                !(detachedProcessGroup && isExecProcessTreeAlive(proc.pid, detachedProcessGroup))) {
-                ctx.processRegistry.remove(proc.pid, exit);
-            }
-            resolve(result);
-        };
-        // Wire abort signal to kill the process
-        let onAbort;
-        if (ctx.abortSignal) {
-            onAbort = () => {
-                cancelled = true;
-                signalExecProcessTree(proc.pid, "SIGTERM", detachedProcessGroup);
-                // Follow up with SIGKILL if SIGTERM doesn't work
-                killTimeoutId = setTimeout(() => {
-                    signalExecProcessTree(proc.pid, "SIGKILL", detachedProcessGroup);
-                }, 1000);
-            };
-            ctx.abortSignal.addEventListener("abort", onAbort, { once: true });
-        }
-        if (timeout) {
-            timeoutId = setTimeout(() => {
-                timedOut = true;
-                signalExecProcessTree(proc.pid, "SIGTERM", detachedProcessGroup);
-                // If SIGTERM doesn't work, follow up with SIGKILL after 1 second
-                killTimeoutId = setTimeout(() => {
-                    signalExecProcessTree(proc.pid, "SIGKILL", detachedProcessGroup);
-                }, 1000);
-            }, timeout);
-        }
-        proc.stdout?.on("data", (data) => {
-            stdout += data.toString();
-        });
-        proc.stderr?.on("data", (data) => {
-            stderr += data.toString();
-        });
-        proc.on("error", (err) => {
-            const exitCode = typeof err === "object" &&
-                err &&
-                "code" in err &&
-                err.code === "ENOENT"
-                ? 127
-                : 1;
-            doResolve(fail(getErrorMessage(err), {
-                stdout: "",
-                stderr,
-                exitCode,
-            }));
-        });
-        proc.on("close", (code, signal) => {
-            void (async () => {
-                if (cancelled || timedOut) {
-                    if (killTimeoutId) {
-                        clearTimeout(killTimeoutId);
-                        killTimeoutId = undefined;
-                    }
-                    signalExecProcessTree(proc.pid, "SIGKILL", detachedProcessGroup);
-                    await waitForExecProcessTreeExit(proc.pid, detachedProcessGroup);
-                }
-                if (cancelled) {
-                    doResolve(fail("Command cancelled", {
-                        stdout,
-                        stderr,
-                        exitCode: code ?? 1,
-                    }), { exitCode: code, signal });
-                    return;
-                }
-                if (timedOut) {
-                    doResolve(fail("Command timed out", {
-                        stdout,
-                        stderr,
-                        exitCode: code ?? 1,
-                    }), { exitCode: code, signal });
-                    return;
-                }
-                if (signal) {
-                    const signaledExitCode = osConstants.signals[signal] ?? 1;
-                    doResolve(fail(`Command exited due to signal ${signal}`, {
-                        stdout,
-                        stderr,
-                        exitCode: code ?? signaledExitCode,
-                    }), { exitCode: code, signal });
-                    return;
-                }
-                const exitCode = code ?? 0;
-                if (exitCode === 0) {
-                    doResolve(success("Command executed successfully", {
-                        stdout,
-                        stderr,
-                        exitCode,
-                    }), { exitCode, signal });
-                }
-                else {
-                    doResolve(fail(`Command exited with code ${exitCode}`, {
-                        stdout,
-                        stderr,
-                        exitCode,
-                    }), { exitCode, signal });
-                }
-            })();
-        });
-    });
-}
-/**
- * Spawns a background process and returns immediately with its PID.
- * The process is detached and will continue running after the parent exits.
- */
-export async function executeSpawn(input, ctx) {
-    // Shell safety: block catastrophic commands before spawning.
-    // Detached processes are especially dangerous — they outlive the session.
-    // For explicit shell wrappers (e.g. bash -c ...), classify payload command.
-    const args = input.args ?? [];
-    const reconstructed = [input.program, ...args].join(" ");
-    const risk = classifyExecInvocation(input.program, args);
-    if (risk === "blocked") {
-        return fail(`Command blocked by shell safety policy: ${reconstructed}`);
-    }
-    // Check if already aborted before spawning
-    if (ctx.abortSignal?.aborted) {
-        return fail("Command cancelled");
-    }
-    // Check for interactive mode — use PTY instead of detached spawn
-    if (input.interactive === true) {
-        if (!ctx.ptySessionStore) {
-            return fail("PTY session store not available — interactive mode requires runner wiring");
-        }
-        // Import createPTYSession dynamically to avoid circular deps at module level
-        const { createPTYSession } = await import("./pty.js");
-        const session = await createPTYSession({
-            command: input.program,
-            args: input.args,
-            cwd: input.cwd ?? ctx.workingDir,
-            env: mergeEnv(ctx, input.env),
-        });
-        const pid = session.pid;
-        if (!pid) {
-            session.close();
-            return fail("Failed to start interactive session: no PID");
-        }
-        // Register in both stores
-        ctx.ptySessionStore.add(pid, session);
-        if (ctx.processRegistry) {
-            ctx.processRegistry.add(pid, {
-                command: input.program,
-                args: input.args ?? [],
-                cwd: input.cwd ?? ctx.workingDir,
-                interactive: true,
-            });
-        }
-        const deregisterInteractiveSession = () => {
-            ctx.ptySessionStore?.remove(pid);
-            if (ctx.processRegistry?.has(pid)) {
-                ctx.processRegistry.remove(pid, {
-                    exitCode: session.exitCode ?? null,
-                });
-            }
-        };
-        if (!session.isRunning) {
-            deregisterInteractiveSession();
-        }
-        else {
-            const lifecycleCheckInterval = setInterval(() => {
-                if (!session.isRunning) {
-                    clearInterval(lifecycleCheckInterval);
-                    deregisterInteractiveSession();
-                }
-            }, 50);
-            lifecycleCheckInterval.unref?.();
-            // Wire abort signal to PTY cleanup so ESC/Ctrl+C kills the session
-            if (ctx.abortSignal) {
-                const onAbort = () => {
-                    clearInterval(lifecycleCheckInterval);
-                    session.close();
-                    deregisterInteractiveSession();
-                };
-                ctx.abortSignal.addEventListener("abort", onAbort, { once: true });
-            }
-        }
-        return success(`Started interactive session with PID ${pid}`, { pid });
-    }
-    const cwd = input.cwd ?? ctx.workingDir;
-    const env = mergeEnv(ctx, input.env);
-    return new Promise((resolve) => {
-        let resolved = false;
-        let fallbackTimeoutId;
-        const doResolve = (result) => {
-            if (resolved)
-                return;
-            resolved = true;
-            if (fallbackTimeoutId)
-                clearTimeout(fallbackTimeoutId);
-            resolve(result);
-        };
-        // Wire abort signal to kill the spawned process.
-        // The listener is NOT removed in doResolve because the spawned process
-        // outlives the function call. The { once: true } option auto-cleans it.
-        let spawnedPid;
-        if (ctx.abortSignal) {
-            ctx.abortSignal.addEventListener("abort", () => {
-                if (spawnedPid) {
-                    try {
-                        // Kill the process group (negative PID) since process is detached
-                        process.kill(-spawnedPid, "SIGTERM");
-                    }
-                    catch {
-                        try {
-                            process.kill(spawnedPid, "SIGTERM");
-                        }
-                        catch {
-                            // Process may already be dead
-                        }
-                    }
-                }
-            }, { once: true });
-        }
-        try {
-            const proc = spawn(input.program, args, {
-                cwd,
-                env,
-                detached: true,
-                stdio: "ignore",
-            });
-            // Handle spawn errors (e.g., program not found)
-            proc.on("error", (err) => {
-                doResolve(fail(getErrorMessage(err)));
-            });
-            // If we have a PID, the spawn was successful
-            if (proc.pid) {
-                spawnedPid = proc.pid;
-                proc.on("exit", (code, signal) => {
-                    ctx.processRegistry?.recordExitMetadata?.(proc.pid, {
-                        exitCode: code,
-                        signal,
-                    });
-                    if (ctx.processRegistry && !isExecProcessTreeAlive(proc.pid, true)) {
-                        ctx.processRegistry.remove(proc.pid, {
-                            exitCode: code,
-                            signal,
-                        });
-                    }
-                });
-                // Track PID in process registry for cleanup on session close.
-                // Spawned (detached) processes are never deregistered here —
-                // they live until exit, killAll(), or the user explicitly kills them.
-                if (ctx.processRegistry) {
-                    ctx.processRegistry.add(proc.pid, {
-                        command: input.program,
-                        args,
-                        cwd,
-                        interactive: false,
-                    });
-                }
-                // Unref to allow parent to exit independently
-                proc.unref();
-                doResolve(success(`Spawned process with PID ${proc.pid}`, {
-                    pid: proc.pid,
-                }));
-            }
-            else {
-                // This shouldn't normally happen, but handle it just in case
-                // Wait briefly for error event
-                fallbackTimeoutId = setTimeout(() => {
-                    doResolve(fail("Failed to spawn process: no PID returned"));
-                }, 100);
-            }
-        }
-        catch (err) {
-            doResolve(fail(getErrorMessage(err)));
-        }
-    });
-}
-/**
- * Sends a signal to terminate a process by PID.
- */
-export async function executeKill(input, ctx) {
-    const signal = input.signal ?? "SIGTERM";
-    try {
-        // Validate and normalize the signal
-        const validatedSignal = validateSignal(signal);
-        if (validatedSignal === undefined) {
-            return fail(`Invalid signal: ${signal}`);
-        }
-        // Use process-tree signaling only for ARIA-tracked processes. Generic pid
-        // kills must preserve pid-only semantics for foreign process groups.
-        if (ctx.processRegistry?.has(input.pid)) {
-            signalProcessTree(input.pid, validatedSignal);
-        }
-        else {
-            process.kill(input.pid, validatedSignal);
-        }
-        // Keep tracked processes authoritative until exit is actually observed.
-        const registry = ctx.processRegistry;
-        if (registry?.waitForExit && shouldUntrackAfterSignal(validatedSignal)) {
-            await registry.waitForExit(input.pid, 2_000);
-        }
-        const signalName = typeof validatedSignal === "number" ? signal : validatedSignal;
-        return success(`Sent ${signalName} to process ${input.pid}`, {
-            pid: input.pid,
-            signal: signalName,
-        });
-    }
-    catch (err) {
-        if (err instanceof Error && "code" in err) {
-            const nodeErr = err;
-            if (nodeErr.code === "ESRCH") {
-                return fail(`Process not found: ${input.pid}`);
-            }
-            if (nodeErr.code === "EPERM") {
-                return fail(`Permission denied to kill process: ${input.pid}`);
-            }
-        }
-        return fail(getErrorMessage(err));
-    }
-}
-/**
- * Valid signal names that can be used with process.kill.
- */
-const VALID_SIGNALS = [
-    "SIGHUP",
-    "SIGINT",
-    "SIGQUIT",
-    "SIGILL",
-    "SIGTRAP",
-    "SIGABRT",
-    "SIGBUS",
-    "SIGFPE",
-    "SIGKILL",
-    "SIGUSR1",
-    "SIGSEGV",
-    "SIGUSR2",
-    "SIGPIPE",
-    "SIGALRM",
-    "SIGTERM",
-    "SIGSTKFLT",
-    "SIGCHLD",
-    "SIGCONT",
-    "SIGSTOP",
-    "SIGTSTP",
-    "SIGTTIN",
-    "SIGTTOU",
-    "SIGURG",
-    "SIGXCPU",
-    "SIGXFSZ",
-    "SIGVTALRM",
-    "SIGPROF",
-    "SIGWINCH",
-    "SIGIO",
-    "SIGPWR",
-    "SIGSYS",
-];
-const NON_TERMINATING_SIGNALS = new Set([
-    "SIGCHLD",
-    "SIGCONT",
-    "SIGSTOP",
-    "SIGTSTP",
-    "SIGTTIN",
-    "SIGTTOU",
-    "SIGURG",
-    "SIGWINCH",
-]);
-/**
- * Type guard to check if a string is a valid signal name.
- */
-function isValidSignalName(signal) {
-    return VALID_SIGNALS.includes(signal.toUpperCase());
-}
-/**
- * Validates a signal and returns either the validated signal name or number.
- * Returns undefined for invalid signals.
- */
-function validateSignal(signal) {
-    // Handle numeric signal
-    if (/^\d+$/.test(signal)) {
-        const num = parseInt(signal, 10);
-        if (num >= 1 && num <= 31) {
-            return num;
-        }
-        return undefined;
-    }
-    // Handle signal names
-    const upperSignal = signal.toUpperCase();
-    if (isValidSignalName(upperSignal)) {
-        return upperSignal;
-    }
-    return undefined;
-}
-function shouldUntrackAfterSignal(signal) {
-    if (typeof signal === "number") {
-        const signalName = resolveSignalName(signal);
-        if (!signalName) {
-            // Unknown numeric signals are treated conservatively.
-            return false;
-        }
-        return !NON_TERMINATING_SIGNALS.has(signalName);
-    }
-    return !NON_TERMINATING_SIGNALS.has(signal);
-}
-function signalProcessTree(pid, signal) {
-    try {
-        if (pid > 0) {
-            process.kill(-pid, signal);
-            return;
-        }
-    }
-    catch {
-        // Fall back to the tracked pid itself when there is no process group to target.
-    }
-    process.kill(pid, signal);
-}
-function resolveSignalName(signal) {
-    for (const [name, value] of Object.entries(osConstants.signals)) {
-        if (value === signal) {
-            return name;
-        }
-    }
-    return undefined;
-}
-function hasLegacyGetAll(registry) {
-    return typeof registry.getAll === "function";
-}
-export async function executeListProcesses(rawInput, ctx) {
-    const input = toRecord(rawInput);
-    const includeExited = typeof input?.includeExited === "boolean" ? input.includeExited : false;
-    if (!ctx.processRegistry) {
-        return fail("Process registry not available");
-    }
-    const registry = ctx.processRegistry;
-    const processes = typeof registry.listProcesses === "function"
-        ? registry.listProcesses({ includeExited })
-        : hasLegacyGetAll(registry)
-            ? registry.getAll().map((pid) => ({
-                pid,
-                command: null,
-                args: [],
-                cwd: null,
-                interactive: false,
-                startedAt: new Date().toISOString(),
-                runtimeMs: 0,
-                status: "running",
-                exitCode: null,
-                signal: null,
-                endedAt: null,
-            }))
-            : [];
-    return success(`Found ${processes.length} tracked process${processes.length === 1 ? "" : "es"}`, {
-        processes,
-        count: processes.length,
-    });
-}
-export async function executeWaitProcess(rawInput, ctx) {
-    const input = toRecord(rawInput);
-    if (!input) {
-        return fail("Invalid input: expected an object");
-    }
-    const pid = typeof input.pid === "number" ? input.pid : NaN;
-    if (!pid || pid <= 0 || !Number.isInteger(pid)) {
-        return fail("Invalid PID: must be a positive integer");
-    }
-    if (pid === process.pid) {
-        return fail("Cannot wait on own process");
-    }
-    const timeoutMsInput = input.timeoutMs;
-    if (timeoutMsInput !== undefined &&
-        (typeof timeoutMsInput !== "number" || Number.isNaN(timeoutMsInput))) {
-        return fail("Invalid timeoutMs: must be a number");
-    }
-    const timeoutInput = input.timeout;
-    if (timeoutInput !== undefined &&
-        (typeof timeoutInput !== "number" || Number.isNaN(timeoutInput))) {
-        return fail("Invalid timeout: must be a number");
-    }
-    const timeoutMs = Math.min(Math.max(0, timeoutMsInput ?? timeoutInput ?? 30_000), 300_000);
-    if (!ctx.processRegistry) {
-        return fail("Process registry not available");
-    }
-    if (typeof ctx.processRegistry.waitForExit !== "function") {
-        return fail("Process registry does not support waiting");
-    }
-    const startedAt = Date.now();
-    const waitResult = await ctx.processRegistry.waitForExit(pid, timeoutMs);
-    const waitedMs = Math.max(0, Date.now() - startedAt);
-    if (waitResult.status === "not_found" || !waitResult.process) {
-        return fail(`Process not tracked: ${pid}`, {
-            pid,
-            exited: false,
-            status: "not_found",
-            timedOut: false,
-            waitedMs,
-        });
-    }
-    const data = mapWaitResult(waitResult, waitedMs);
-    if (waitResult.status === "running" || waitResult.timedOut) {
-        return fail(`Timed out waiting for process ${pid}`, data);
-    }
-    return success(`Process ${pid} exited`, data);
-}
-function mapWaitResult(waitResult, waitedMs) {
-    const processInfo = waitResult.process;
-    const status = waitResult.status === "exited" ? "exited" : "running";
-    return {
-        pid: waitResult.pid,
-        status,
-        exited: status === "exited",
-        timedOut: waitResult.timedOut,
-        waitedMs,
-        command: processInfo.command,
-        args: processInfo.args,
-        cwd: processInfo.cwd,
-        interactive: processInfo.interactive,
-        startedAt: processInfo.startedAt,
-        endedAt: processInfo.endedAt,
-        runtimeMs: processInfo.runtimeMs,
-        exitCode: processInfo.exitCode,
-        signal: processInfo.signal,
-    };
-}
-function toRecord(rawInput) {
-    if (!rawInput || typeof rawInput !== "object") {
-        return undefined;
-    }
-    return rawInput;
-}
-/**
- * Sends input to an interactive PTY session by PID.
- * Requires the process to have been spawned with interactive=true.
- */
-export async function executeWriteStdin(rawInput, ctx) {
-    // Validate input shape at runtime
-    if (!rawInput || typeof rawInput !== "object") {
-        return fail("Invalid input: expected an object");
-    }
-    const input = rawInput;
-    const pid = typeof input.pid === "number" ? input.pid : NaN;
-    const inputStr = typeof input.input === "string" ? input.input : undefined;
-    const timeout = typeof input.timeout === "number" ? input.timeout : undefined;
-    // Validate PID
-    if (!pid || pid <= 0 || !Number.isInteger(pid)) {
-        return fail("Invalid PID: must be a positive integer");
-    }
-    if (pid === process.pid) {
-        return fail("Cannot write to own process");
-    }
-    // Validate input string
-    if (inputStr === undefined) {
-        return fail("Input must be a string");
-    }
-    // Look up PTY session store
-    if (!ctx.ptySessionStore) {
-        return fail("PTY session store not available");
-    }
-    if (!ctx.ptySessionStore.has(pid)) {
-        return fail(`No interactive session found for PID ${pid}. Use spawn with interactive=true first.`);
-    }
-    // The ptySessionStore ref uses `unknown` return to avoid circular deps,
-    // but the concrete store returns PTYSession instances.
-    const session = ctx.ptySessionStore.get(pid);
-    if (!session) {
-        return fail(`No interactive session found for PID ${pid}. Use spawn with interactive=true first.`);
-    }
-    if (!session.isRunning) {
-        return fail(`Process ${pid} has exited (code: ${session.exitCode ?? "unknown"})`);
-    }
-    try {
-        // Capture output length before write to extract new output after
-        const outputLenBefore = session.output.length;
-        // Write input to the PTY session
-        session.write(inputStr);
-        // If timeout specified, poll for new output with early return
-        if (timeout && timeout > 0) {
-            const waitMs = Math.min(timeout, 30_000);
-            const deadline = Date.now() + waitMs;
-            const pollInterval = 50; // Check every 50ms
-            while (Date.now() < deadline) {
-                await new Promise((resolve) => setTimeout(resolve, pollInterval));
-                if (session.output.length > outputLenBefore)
-                    break;
-                if (!session.isRunning)
-                    break;
-            }
-        }
-        // Extract output produced after the write
-        const fullOutput = session.output;
-        const newOutput = fullOutput.slice(outputLenBefore);
-        // Cap returned output to 10KB to avoid bloating tool results
-        const cappedOutput = newOutput.length > 10_000 ? newOutput.slice(-10_000) : newOutput;
-        return success(`Wrote ${inputStr.length} bytes to PID ${pid}`, {
-            output: cappedOutput,
-        });
-    }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return fail(`Failed to write to PID ${pid}: ${msg}`);
-    }
-}