@mario.andreschak/mcp-bash 3.39.0

package/dist/tools.js

@@ -0,0 +1,1493 @@
+/**
+ * Built-in `bash` MCP server (issue #170).
+ *
+ * Cross-platform shell execution (grep, curl, …) on Windows/macOS/Linux. It
+ * reuses the proven spawn + timeout + process-tree-kill primitives from the
+ * legacy `terminal` tool (which this server replaces) and adds:
+ *   - shell selection: PowerShell-first on Windows and `/bin/sh` on POSIX, or
+ *     explicit `pwsh` / `bash` / `cmd` (failing before execution when invalid
+ *     or unavailable),
+ *   - optional CRLF→LF normalization of captured output,
+ *   - background execution: start → status/wait → write_stdin → kill,
+ *   - orphan cleanup: every live session is force-killed on FLUJO process exit,
+ *     and idle finished sessions are swept after a TTL.
+ *
+ * Confinement + env hygiene (issue #175): the `cwd` is confined to the same
+ * effective roots as the built-in `filesystem` server (a HARD CEILING from
+ * `FLUJO_BASH_ROOTS`, falling back to `FLUJO_FS_ROOTS`, plus UI-persisted roots
+ * that may only narrow within it). This is a best-effort guardrail — a shell can
+ * `cd` elsewhere or use absolute paths, so `FLUJO_FS_ROOTS`/`FLUJO_BASH_ROOTS`
+ * and OS permissions remain the real boundary. Spawned commands also DO NOT
+ * inherit the full backend `process.env` by default (which would leak secrets);
+ * only a minimal allow-list is passed. Set `FLUJO_BASH_INHERIT_ENV=1` to restore
+ * full inheritance. Individual calls may pass explicit `env` overrides without
+ * enabling full inheritance.
+ *
+ * Every tool returns a machine-readable JSON envelope in a single text content
+ * block; failures come back as `isError: true` rather than thrown.
+ *
+ * MCP App contract (issue #330): ordinary run/background tools continue to use
+ * pipes, while the interactive terminal View uses a real OS pseudoterminal
+ * (ConPTY on Windows, forkpty on POSIX) with incremental reads, raw keyboard
+ * input, ANSI/VT output, and resize negotiation.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+import { spawn as spawnPty } from '@lydell/node-pty';
+import { ALLOW_PROTECTED_PATHS_ENV, createLogger, getDataDir, getHomeDir, isInside, isProtected, isProtectedPathsEnabled, killProcessTree, loadEffectiveRoots, } from './shared.js';
+const BASH_SERVER_NAME = 'bash';
+export const BASH_TERMINAL_APP_URI = 'ui://bash/terminal';
+const log = createLogger('backend/services/mcp/internal/bashTools');
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_TIMEOUT_MS = 600_000;
+const MAX_OUTPUT_CHARS = 100_000;
+const MAX_SESSIONS = 25;
+const MAX_TERMINAL_OUTPUT_CHARS = 2_000_000;
+/**
+ * Lifecycle: live sessions end only by process exit, explicit kill, or Bash
+ * server shutdown. Finished owner-scoped records remain readable for ten
+ * minutes, then are reaped. An MCP View teardown may be an inline→dock handoff,
+ * so it is not treated as an owner disconnect signal.
+ */
+const SESSION_TTL_MS = 10 * 60_000;
+/**
+ * Locate an executable by name on `PATH` ourselves (rather than relying on
+ * `spawn`'s own resolution) so we can know in advance whether `pwsh`/`bash`
+ * are actually available and return a deterministic error instead of failing
+ * asynchronously with ENOENT (issue #225).
+ */
+function getEnvCaseInsensitive(name) {
+    const direct = process.env[name];
+    if (direct !== undefined)
+        return direct;
+    const key = Object.keys(process.env).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+    return key ? process.env[key] : undefined;
+}
+function windowsExecutableExtensions() {
+    const inherited = (getEnvCaseInsensitive('PATHEXT') ?? '')
+        .split(';')
+        .map((extension) => extension.trim())
+        .filter(Boolean);
+    const required = ['.COM', '.EXE', '.BAT', '.CMD'];
+    return [...new Set([...required, ...inherited].map((extension) => (extension.startsWith('.') ? extension : `.${extension}`).toUpperCase()))];
+}
+function findExecutablesOnPath(name) {
+    const pathEnv = getEnvCaseInsensitive('PATH') ?? '';
+    const dirs = pathEnv
+        .split(path.delimiter)
+        .map((dir) => dir.trim().replace(/^"(.*)"$/, '$1'))
+        .filter(Boolean);
+    const exts = process.platform === 'win32'
+        ? windowsExecutableExtensions()
+        : [''];
+    const found = [];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const candidate = path.join(dir, `${name}${ext}`);
+            try {
+                if (fs.statSync(candidate).isFile())
+                    found.push(candidate);
+            }
+            catch {
+                /* not found here, keep looking */
+            }
+        }
+    }
+    return [...new Set(found.map((candidate) => path.resolve(candidate)))];
+}
+function findExecutableOnPath(name) {
+    return findExecutablesOnPath(name)[0] ?? null;
+}
+function firstExistingFile(candidates) {
+    const seen = new Set();
+    for (const rawCandidate of candidates) {
+        if (!rawCandidate)
+            continue;
+        const candidate = path.resolve(rawCandidate);
+        const key = process.platform === 'win32' ? candidate.toLowerCase() : candidate;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        try {
+            if (fs.statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            /* not found here, keep looking */
+        }
+    }
+    return null;
+}
+/**
+ * Well-known install locations for Git for Windows' `bash.exe`. These are
+ * preferred over the legacy System32 WSL launcher, which may exist even when
+ * its Linux `/bin/bash` does not (issues #225 and #327).
+ */
+function windowsGitBashCandidates() {
+    const roots = [
+        getEnvCaseInsensitive('ProgramFiles'),
+        getEnvCaseInsensitive('ProgramFiles(x86)'),
+        getEnvCaseInsensitive('LocalAppData'),
+    ]
+        .filter((v) => Boolean(v));
+    const git = findExecutableOnPath('git');
+    const gitRoot = git ? path.dirname(path.dirname(git)) : undefined;
+    return [
+        ...(gitRoot ? [
+            path.join(gitRoot, 'bin', 'bash.exe'),
+            path.join(gitRoot, 'usr', 'bin', 'bash.exe'),
+        ] : []),
+        ...roots.flatMap((root) => [
+            path.join(root, 'Git', 'bin', 'bash.exe'),
+            path.join(root, 'Git', 'usr', 'bin', 'bash.exe'),
+            path.join(root, 'Programs', 'Git', 'bin', 'bash.exe'),
+            path.join(root, 'Programs', 'Git', 'usr', 'bin', 'bash.exe'),
+        ]),
+    ];
+}
+function isWindowsWslBashLauncher(candidate) {
+    if (process.platform !== 'win32')
+        return false;
+    const systemRoot = getEnvCaseInsensitive('SystemRoot') ?? getEnvCaseInsensitive('windir');
+    if (!systemRoot)
+        return false;
+    return path.resolve(candidate).toLowerCase() === path.resolve(systemRoot, 'System32', 'bash.exe').toLowerCase();
+}
+let cachedBashPath;
+function resolveBashExecutable() {
+    if (cachedBashPath && firstExistingFile([cachedBashPath]))
+        return cachedBashPath;
+    const candidates = process.platform === 'win32'
+        ? [
+            ...windowsGitBashCandidates(),
+            ...findExecutablesOnPath('bash').filter((candidate) => !isWindowsWslBashLauncher(candidate)),
+        ]
+        : findExecutablesOnPath('bash');
+    cachedBashPath = firstExistingFile(candidates);
+    return cachedBashPath;
+}
+function windowsPwshCandidates() {
+    const localAppData = getEnvCaseInsensitive('LocalAppData');
+    const programFiles = getEnvCaseInsensitive('ProgramFiles');
+    return [
+        ...(localAppData ? [path.join(localAppData, 'Microsoft', 'WindowsApps', 'pwsh.exe')] : []),
+        ...(programFiles ? [
+            path.join(programFiles, 'PowerShell', '7', 'pwsh.exe'),
+            path.join(programFiles, 'PowerShell', '7-preview', 'pwsh.exe'),
+        ] : []),
+    ];
+}
+let cachedPwshPath;
+function resolvePwshExecutable() {
+    if (cachedPwshPath && firstExistingFile([cachedPwshPath]))
+        return cachedPwshPath;
+    cachedPwshPath = firstExistingFile([
+        ...findExecutablesOnPath('pwsh'),
+        ...(process.platform === 'win32' ? windowsPwshCandidates() : []),
+    ]);
+    return cachedPwshPath;
+}
+let cachedWindowsPowerShellPath;
+function resolveWindowsPowerShellExecutable() {
+    if (cachedWindowsPowerShellPath && firstExistingFile([cachedWindowsPowerShellPath])) {
+        return cachedWindowsPowerShellPath;
+    }
+    const systemRoot = getEnvCaseInsensitive('SystemRoot') ?? getEnvCaseInsensitive('windir');
+    cachedWindowsPowerShellPath = firstExistingFile([
+        findExecutableOnPath('powershell'),
+        ...(systemRoot
+            ? [path.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')]
+            : []),
+    ]);
+    return cachedWindowsPowerShellPath;
+}
+function resolveCmdExecutable() {
+    if (process.platform !== 'win32')
+        return null;
+    return firstExistingFile([
+        getEnvCaseInsensitive('ComSpec'),
+        findExecutableOnPath('cmd'),
+        path.join(getEnvCaseInsensitive('SystemRoot') ?? 'C:\\Windows', 'System32', 'cmd.exe'),
+    ]);
+}
+/** Test-only: forget cached shell-executable lookups. */
+export function _resetBashShellCacheForTests() {
+    cachedBashPath = undefined;
+    cachedPwshPath = undefined;
+    cachedWindowsPowerShellPath = undefined;
+}
+function sessions() {
+    if (!global.__flujo_bash_sessions)
+        global.__flujo_bash_sessions = new Map();
+    return global.__flujo_bash_sessions;
+}
+function terminalSessions() {
+    if (!global.__flujo_terminal_sessions)
+        global.__flujo_terminal_sessions = new Map();
+    return global.__flujo_terminal_sessions;
+}
+function foregroundChildren() {
+    if (!global.__flujo_bash_foreground_children)
+        global.__flujo_bash_foreground_children = new Set();
+    return global.__flujo_bash_foreground_children;
+}
+const ANONYMOUS_OWNER_SCOPE = 'legacy:anonymous';
+function effectiveOwnerScope(ownerScope, callerNodeId) {
+    const explicit = ownerScope?.trim();
+    if (explicit)
+        return explicit;
+    const caller = callerNodeId?.trim();
+    return caller ? `caller:${caller}` : ANONYMOUS_OWNER_SCOPE;
+}
+function ownedSession(id, ownerScope) {
+    const session = sessions().get(id);
+    return session?.ownerScope === ownerScope ? session : undefined;
+}
+function terminalMeta(visibility = ['model', 'app']) {
+    return { ui: { resourceUri: BASH_TERMINAL_APP_URI, visibility } };
+}
+/** Kill every live session's process tree — used on FLUJO process exit. */
+export function shutdownBashSessions() {
+    for (const child of foregroundChildren()) {
+        try {
+            killProcessTree(child);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    for (const s of sessions().values()) {
+        if (s.running) {
+            try {
+                killProcessTree(s.child);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        if (s.reapTimer)
+            clearTimeout(s.reapTimer);
+    }
+    for (const terminal of terminalSessions().values()) {
+        try {
+            if (terminal.running) {
+                terminal.running = false;
+                terminal.pty.kill();
+            }
+        }
+        catch {
+            /* best-effort */
+        }
+        if (terminal.reapTimer)
+            clearTimeout(terminal.reapTimer);
+    }
+}
+function registerExitCleanup() {
+    if (global.__flujo_bash_cleanup_registered)
+        return;
+    global.__flujo_bash_cleanup_registered = true;
+    const handler = () => shutdownBashSessions();
+    process.on('exit', handler);
+    process.on('SIGINT', handler);
+    process.on('SIGTERM', handler);
+}
+function textResult(payload, isError = false) {
+    return {
+        content: [{ type: 'text', text: typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+/** Env var names that supply the bash confinement ceiling (checked in order). */
+const BASH_ROOT_ENV_VARS = ['FLUJO_BASH_ROOTS', 'FLUJO_FS_ROOTS'];
+/**
+ * Resolve the working directory against the FLUJO data dir (for relative paths)
+ * and enforce the effective confinement roots when present. Throws on a
+ * confinement violation so callers surface a precise error (issue #175).
+ */
+async function resolveCwd(input, roots) {
+    const dataDir = getDataDir();
+    const raw = typeof input === 'string' ? input.trim() : '';
+    const resolved = raw ? (path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(dataDir, raw)) : dataDir;
+    // Optional defense-in-depth layer (issue #260). Configured roots win by
+    // default; users can opt into this stricter policy under Experimental Features.
+    if (await isProtectedPathsEnabled()) {
+        const prot = isProtected(resolved);
+        if (prot.denied) {
+            throw new Error(`cwd "${resolved}" is within a protected location (${prot.matchedRoot}) and is blocked by the FLUJO built-in server protected-path policy. ` +
+                `Disable "Protect sensitive home-directory paths" in Experimental Features or set ${ALLOW_PROTECTED_PATHS_ENV}=1 to override.`);
+        }
+    }
+    if (roots.length === 0 || !roots.some((root) => isInside(root, resolved))) {
+        throw new Error(`cwd "${resolved}" is outside the configured bash roots.`);
+    }
+    return resolved;
+}
+/**
+ * Best-effort advisory scan (issue #260, item 4) of a command string for
+ * absolute-looking paths that point OUTSIDE the configured roots or INTO a
+ * protected location. Returns human-readable warning strings; it NEVER blocks —
+ * a shell can reach anywhere regardless, so this is honest advice, not a
+ * boundary. Known limitation: shell variable expansions (e.g. `$HOME/AppData`)
+ * are not resolved.
+ */
+function maskGlobOptionValues(command) {
+    const chars = [...command];
+    const tokens = [...command.matchAll(/"(?:\\.|[^"\\])*"|'[^']*'|[^\s]+/g)];
+    let maskNext = false;
+    for (const match of tokens) {
+        const raw = match[0];
+        const start = match.index ?? 0;
+        const unquoted = raw.length >= 2 && ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'")))
+            ? raw.slice(1, -1)
+            : raw;
+        let valueOffset = 0;
+        if (maskNext) {
+            maskNext = false;
+        }
+        else if (unquoted === '-g' || unquoted === '--glob' || unquoted === '--iglob') {
+            maskNext = true;
+            continue;
+        }
+        else {
+            if (!/^(?:--glob|--iglob)=/.test(unquoted))
+                continue;
+            valueOffset = raw.indexOf('=') + 1;
+        }
+        for (let i = start + valueOffset; i < start + raw.length; i += 1)
+            chars[i] = ' ';
+    }
+    return chars.join('');
+}
+async function scanCommandForExternalPaths(command, cwd, roots) {
+    const warnings = [];
+    const protectedPathsEnabled = await isProtectedPathsEnabled();
+    const seen = new Set();
+    // Ripgrep glob values are patterns, not filesystem paths. Mask only option
+    // values so a real path elsewhere in the same command is still inspected.
+    const commandForPathScan = maskGlobOptionValues(command);
+    // Absolute-looking tokens: Windows drive (X:\ or X:/), UNC (\\host\share),
+    // POSIX (/foo), and ~-prefixed home paths.
+    const tokenRe = /(?:[A-Za-z]:[\\/][^\s"']*|\\\\[^\s"']+|~\/[^\s"']*|(?<![\w.])\/[^\s"']+)/g;
+    const matches = (commandForPathScan.match(tokenRe) ?? []).filter(
+    // A single-letter slash token is a Windows command switch, not a POSIX path.
+    // Keep longer tokens so genuine POSIX absolute paths remain advisory notices.
+    (token) => !(process.platform === 'win32' && /^\/[A-Za-z]$/.test(token)));
+    const home = (() => {
+        try {
+            return getHomeDir();
+        }
+        catch {
+            return '';
+        }
+    })();
+    for (const rawToken of matches) {
+        let token = rawToken;
+        if (token.startsWith('~/') && home)
+            token = path.join(home, token.slice(2));
+        let resolved;
+        try {
+            resolved = path.isAbsolute(token) ? path.resolve(token) : path.resolve(cwd, token);
+        }
+        catch {
+            continue;
+        }
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        const prot = protectedPathsEnabled ? isProtected(resolved) : { denied: false };
+        if (prot.denied) {
+            warnings.push(`Command references "${rawToken}", which is inside a protected location (${prot.matchedRoot}).`);
+        }
+        else if (roots.length > 0 && !roots.some((root) => isInside(root, resolved))) {
+            warnings.push(`Command references "${rawToken}", which is outside the configured working roots.`);
+        }
+    }
+    return warnings;
+}
+/**
+ * A truthy env flag: "1", "true", "yes", "on" (case-insensitive).
+ */
+function isTruthyEnv(value) {
+    return typeof value === 'string' && /^(1|true|yes|on)$/i.test(value.trim());
+}
+/**
+ * Names of environment variables that are safe (and often necessary) to pass to
+ * a spawned shell. Anything not on this list — notably API keys / secrets — is
+ * withheld by default so a command like `env` / `printenv` / `Get-ChildItem Env:`
+ * cannot read them back (issue #175). `LC_*` locale vars are allowed by prefix.
+ */
+const ENV_ALLOWLIST = new Set([
+    'path',
+    'home', 'userprofile', 'homedrive', 'homepath',
+    'appdata', 'localappdata', 'programdata',
+    'tmp', 'temp', 'tmpdir',
+    'lang', 'lc_all', 'term', 'colorterm', 'no_color',
+    'shell', 'user', 'username', 'logname',
+    // Windows essentials so the default shell can even start.
+    'systemroot', 'windir', 'comspec', 'pathext', 'systemdrive',
+    'programfiles', 'programfiles(x86)',
+    'number_of_processors', 'processor_architecture',
+]);
+/**
+ * Returns the managed utilities directory path where Unix-like utilities
+ * (BusyBox applets on Windows) are installed. This directory is prepended to
+ * the child process PATH so that tools like grep, find, sed, awk are available.
+ */
+function getManagedUtilsDir() {
+    return path.join(getDataDir(), 'bash-utils');
+}
+const CODEX_RIPGREP_TARGETS = {
+    win32: {
+        x64: ['@openai/codex-win32-x64', 'x86_64-pc-windows-msvc'],
+        arm64: ['@openai/codex-win32-arm64', 'aarch64-pc-windows-msvc'],
+    },
+    darwin: {
+        x64: ['@openai/codex-darwin-x64', 'x86_64-apple-darwin'],
+        arm64: ['@openai/codex-darwin-arm64', 'aarch64-apple-darwin'],
+    },
+    linux: {
+        x64: ['@openai/codex-linux-x64', 'x86_64-unknown-linux-musl'],
+        arm64: ['@openai/codex-linux-arm64', 'aarch64-unknown-linux-musl'],
+    },
+};
+/** Resolve the ripgrep binary already bundled with FLUJO's Codex dependency. */
+function getBundledRipgrepDir() {
+    const target = CODEX_RIPGREP_TARGETS[process.platform]?.[process.arch];
+    if (!target)
+        return null;
+    try {
+        const packageJson = require.resolve(`${target[0]}/package.json`);
+        const dir = path.join(path.dirname(packageJson), 'vendor', target[1], 'codex-path');
+        const executable = path.join(dir, process.platform === 'win32' ? 'rg.exe' : 'rg');
+        return fs.statSync(executable).isFile() ? dir : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the child process environment. By default only the minimal allow-list is
+ * inherited (secrets never leave the backend). Explicit per-command overrides
+ * are then applied. Setting `FLUJO_BASH_INHERIT_ENV` to a truthy value restores
+ * full `process.env` inheritance for power users.
+ */
+function buildChildEnv(overrides = {}) {
+    const out = isTruthyEnv(process.env.FLUJO_BASH_INHERIT_ENV)
+        ? { ...process.env }
+        : Object.fromEntries(Object.entries(process.env).filter(([key]) => ENV_ALLOWLIST.has(key.toLowerCase()) || /^LC_/i.test(key)));
+    const currentPath = getEnvCaseInsensitive('PATH') ?? '';
+    const utilityDirs = [getManagedUtilsDir(), getBundledRipgrepDir()]
+        .filter((dir) => Boolean(dir))
+        .filter((dir) => {
+        try {
+            return fs.statSync(dir).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+    out.PATH = [...utilityDirs, currentPath].filter(Boolean).join(path.delimiter);
+    if (process.platform === 'win32') {
+        // Node de-duplicates Windows environment keys case-insensitively; retain a
+        // single spelling so the augmented value is the one passed to the child.
+        for (const key of Object.keys(out)) {
+            if (key !== 'PATH' && key.toLowerCase() === 'path')
+                delete out[key];
+            if (key !== 'PATHEXT' && key.toLowerCase() === 'pathext')
+                delete out[key];
+        }
+        out.PATHEXT = windowsExecutableExtensions().join(';');
+    }
+    for (const [key, value] of Object.entries(overrides)) {
+        if (process.platform === 'win32') {
+            for (const existing of Object.keys(out)) {
+                if (existing !== key && existing.toLowerCase() === key.toLowerCase())
+                    delete out[existing];
+            }
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function validateEnv(input) {
+    if (input === undefined)
+        return { valid: true, env: {} };
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        return { valid: false, error: '"env" must be an object whose values are strings.' };
+    }
+    const env = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (!key || key.includes('=') || key.includes('\0')) {
+            return { valid: false, error: `Invalid environment variable name: ${JSON.stringify(key)}.` };
+        }
+        if (typeof value !== 'string' || value.includes('\0')) {
+            return { valid: false, error: `Environment variable ${JSON.stringify(key)} must be a string without NUL characters.` };
+        }
+        env[key] = value;
+    }
+    return { valid: true, env };
+}
+/**
+ * Build the spawn arguments for the requested shell. Returns the command, argv
+ * and whether Node's `shell:true` wrapping applies. Shells are resolved
+ * to a concrete executable path up front (checking Git for Windows' well-known
+ * install locations for `bash` when it isn't on `PATH`). An unavailable
+ * explicitly requested shell is reported before any user command is executed.
+ */
+function buildSpawn(command, shell) {
+    if (shell === 'pwsh') {
+        const resolved = resolvePwshExecutable();
+        if (resolved) {
+            return { file: resolved, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], useShell: false, effectiveShell: 'pwsh' };
+        }
+        return { file: '', args: [], useShell: false, effectiveShell: 'pwsh', unavailableShell: 'pwsh' };
+    }
+    if (shell === 'bash') {
+        const resolved = resolveBashExecutable();
+        if (resolved) {
+            return { file: resolved, args: ['-c', command], useShell: false, effectiveShell: 'bash' };
+        }
+        return { file: '', args: [], useShell: false, effectiveShell: 'bash', unavailableShell: 'bash' };
+    }
+    if (shell === 'cmd') {
+        const resolved = resolveCmdExecutable();
+        if (resolved) {
+            return {
+                file: resolved,
+                args: ['/d', '/s', '/c', command],
+                useShell: false,
+                effectiveShell: 'cmd',
+                windowsVerbatimArguments: true,
+            };
+        }
+        return { file: '', args: [], useShell: false, effectiveShell: 'cmd', unavailableShell: 'cmd' };
+    }
+    if (process.platform === 'win32') {
+        const pwsh = resolvePwshExecutable();
+        if (pwsh) {
+            return { file: pwsh, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], useShell: false, effectiveShell: 'pwsh' };
+        }
+        const windowsPowerShell = resolveWindowsPowerShellExecutable();
+        if (windowsPowerShell) {
+            return { file: windowsPowerShell, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], useShell: false, effectiveShell: 'powershell' };
+        }
+        const cmd = resolveCmdExecutable();
+        if (cmd) {
+            return {
+                file: cmd,
+                args: ['/d', '/s', '/c', command],
+                useShell: false,
+                effectiveShell: 'cmd',
+                windowsVerbatimArguments: true,
+            };
+        }
+        return {
+            file: '',
+            args: [],
+            useShell: false,
+            effectiveShell: 'cmd',
+            startError: 'No usable PowerShell or cmd executable was found.',
+        };
+    }
+    const sh = firstExistingFile(['/bin/sh', findExecutableOnPath('sh')]);
+    if (sh)
+        return { file: sh, args: ['-c', command], useShell: false, effectiveShell: 'sh' };
+    return {
+        file: '',
+        args: [],
+        useShell: false,
+        effectiveShell: 'sh',
+        startError: 'No POSIX /bin/sh executable was found.',
+    };
+}
+function safeRequestedShellValue(input) {
+    try {
+        const serialized = JSON.stringify(input);
+        if (serialized !== undefined)
+            return JSON.parse(serialized);
+    }
+    catch {
+        // Fall through to a non-throwing string representation.
+    }
+    try {
+        return String(input);
+    }
+    catch {
+        return '<unrepresentable>';
+    }
+}
+function validateShell(input) {
+    if (input === undefined)
+        return { valid: true, shell: 'default' };
+    if (input === 'default' || input === 'pwsh' || input === 'bash' || input === 'cmd') {
+        return { valid: true, shell: input };
+    }
+    return { valid: false, requestedShell: safeRequestedShellValue(input) };
+}
+function invalidShellResult(requestedShell) {
+    return textResult({
+        error: 'Invalid shell request. Expected one of: "default", "pwsh", "bash", or "cmd".',
+        requestedShell,
+    }, true);
+}
+function startChild(command, cwd, shell, env) {
+    const { file, args, useShell, effectiveShell, unavailableShell, startError, windowsVerbatimArguments, } = buildSpawn(command, shell);
+    if (unavailableShell)
+        return { effectiveShell, unavailableShell };
+    if (startError)
+        return { effectiveShell, startError };
+    // POSIX: detached so killProcessTree can signal the whole group (see killProcessTree).
+    const detached = process.platform !== 'win32';
+    try {
+        const child = spawn(file, args, {
+            cwd,
+            shell: useShell,
+            env: buildChildEnv(env),
+            detached,
+            ...(windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
+        });
+        return { child, effectiveShell };
+    }
+    catch (err) {
+        return {
+            startError: err instanceof Error ? err.message : String(err),
+            effectiveShell,
+        };
+    }
+}
+function makeAppender(get, set) {
+    return (chunk) => {
+        let out = get();
+        if (out.length >= MAX_OUTPUT_CHARS) {
+            if (chunk)
+                set(out, true);
+            return;
+        }
+        out += chunk;
+        let truncated = false;
+        if (out.length > MAX_OUTPUT_CHARS) {
+            out = out.slice(0, MAX_OUTPUT_CHARS) + '\n…[output truncated]';
+            truncated = true;
+        }
+        set(out, truncated);
+    };
+}
+/** Resolve an interactive shell executable without wrapping a command string. */
+function buildPtySpawn(shell) {
+    if (shell === 'pwsh') {
+        const file = resolvePwshExecutable();
+        return file
+            ? { file, args: ['-NoLogo'], effectiveShell: 'pwsh' }
+            : { file: '', args: [], effectiveShell: 'pwsh', unavailableShell: 'pwsh' };
+    }
+    if (shell === 'bash') {
+        const file = resolveBashExecutable();
+        return file
+            ? { file, args: ['--noprofile', '--norc', '-i'], effectiveShell: 'bash' }
+            : { file: '', args: [], effectiveShell: 'bash', unavailableShell: 'bash' };
+    }
+    if (shell === 'cmd') {
+        const file = resolveCmdExecutable();
+        return file
+            ? { file, args: ['/d', '/q'], effectiveShell: 'cmd' }
+            : { file: '', args: [], effectiveShell: 'cmd', unavailableShell: 'cmd' };
+    }
+    if (process.platform === 'win32') {
+        const pwsh = resolvePwshExecutable();
+        if (pwsh)
+            return { file: pwsh, args: ['-NoLogo'], effectiveShell: 'pwsh' };
+        const powershell = resolveWindowsPowerShellExecutable();
+        if (powershell)
+            return { file: powershell, args: ['-NoLogo'], effectiveShell: 'powershell' };
+        const cmd = resolveCmdExecutable();
+        if (cmd)
+            return { file: cmd, args: ['/d', '/q'], effectiveShell: 'cmd' };
+        return { file: '', args: [], effectiveShell: 'cmd', startError: 'No usable PowerShell or cmd executable was found.' };
+    }
+    const loginShell = getEnvCaseInsensitive('SHELL');
+    const bash = resolveBashExecutable();
+    const file = firstExistingFile([loginShell, bash, '/bin/sh', findExecutableOnPath('sh')]);
+    if (!file)
+        return { file: '', args: [], effectiveShell: 'sh', startError: 'No interactive POSIX shell was found.' };
+    const isBash = path.basename(file).toLowerCase().startsWith('bash');
+    return {
+        file,
+        args: isBash ? ['--noprofile', '--norc', '-i'] : ['-i'],
+        effectiveShell: isBash ? 'bash' : 'sh',
+    };
+}
+function createCommandProgressReporter(context) {
+    const report = context?.onProgress;
+    if (!report)
+        return { push: () => undefined, stop: async () => undefined };
+    const startedAt = Date.now();
+    const maxMessageChars = 4_000;
+    let progress = 0;
+    let pending = '';
+    let flushTimer;
+    let stopped = false;
+    let forwardedChars = 0;
+    let liveOutputTruncated = false;
+    let chain = Promise.resolve();
+    const deliver = (message) => {
+        if (!message)
+            return;
+        const snapshot = progress;
+        chain = chain
+            .then(() => report({ progress: snapshot, message }))
+            .catch((error) => {
+            log.debug('Could not deliver bash progress notification', error);
+        });
+    };
+    const flush = () => {
+        if (flushTimer)
+            clearTimeout(flushTimer);
+        flushTimer = undefined;
+        while (pending.length > 0) {
+            const message = pending.slice(0, maxMessageChars);
+            pending = pending.slice(message.length);
+            deliver(message);
+        }
+    };
+    const heartbeat = setInterval(() => {
+        if (stopped)
+            return;
+        if (pending)
+            flush();
+        else
+            deliver(`[command still running: ${Math.max(1, Math.round((Date.now() - startedAt) / 1000))}s]`);
+    }, 10_000);
+    heartbeat.unref?.();
+    return {
+        push: (chunk) => {
+            if (stopped || !chunk)
+                return;
+            progress += Buffer.byteLength(chunk, 'utf8');
+            const remaining = Math.max(0, MAX_OUTPUT_CHARS - forwardedChars);
+            if (remaining > 0) {
+                const accepted = chunk.slice(0, remaining);
+                pending += accepted;
+                forwardedChars += accepted.length;
+            }
+            if (chunk.length > remaining && !liveOutputTruncated) {
+                liveOutputTruncated = true;
+                pending += '\n…[live output truncated]';
+            }
+            if (pending.length >= maxMessageChars) {
+                flush();
+            }
+            else if (!flushTimer) {
+                flushTimer = setTimeout(flush, 75);
+                flushTimer.unref?.();
+            }
+        },
+        stop: async () => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            clearInterval(heartbeat);
+            flush();
+            let timer;
+            try {
+                await Promise.race([
+                    chain,
+                    new Promise((resolve) => {
+                        timer = setTimeout(resolve, 1_000);
+                    }),
+                ]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        },
+    };
+}
+export function bashToolDefinitions() {
+    const shellProp = {
+        type: 'string',
+        enum: ['default', 'pwsh', 'bash', 'cmd'],
+        description: 'Command parser. "default" uses PowerShell on Windows and /bin/sh elsewhere. Use "pwsh", "bash", or "cmd" for explicit syntax; unavailable explicit shells return an error.',
+    };
+    const cwdProp = { type: 'string', description: 'Working directory. Relative paths resolve from the FLUJO data directory; configured roots still apply.' };
+    const envProp = {
+        type: 'object',
+        additionalProperties: { type: 'string' },
+        description: 'Environment variables to add or override for this command.',
+    };
+    return [
+        {
+            name: 'open_terminal',
+            description: 'Open a real interactive pseudoterminal (PTY/ConPTY) and display its MCP App. Returns an owner-scoped terminal sessionId.',
+            _meta: terminalMeta(['model', 'app']),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    cwd: cwdProp,
+                    shell: shellProp,
+                    env: envProp,
+                    cols: { type: 'number', description: 'Initial terminal columns (20-400, default 100).' },
+                    rows: { type: 'number', description: 'Initial terminal rows (5-200, default 30).' },
+                },
+            },
+        },
+        {
+            name: 'terminal_read',
+            description: 'Read incremental ANSI/VT output from an owner-scoped interactive terminal session.',
+            _meta: terminalMeta(['app']),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sessionId: { type: 'string' },
+                    cursor: { type: 'number', description: 'Output cursor returned by the previous read.' },
+                },
+                required: ['sessionId'],
+            },
+        },
+        {
+            name: 'terminal_write',
+            description: 'Write raw keyboard or pasted input to an owner-scoped interactive terminal PTY.',
+            _meta: terminalMeta(['app']),
+            inputSchema: {
+                type: 'object',
+                properties: { sessionId: { type: 'string' }, data: { type: 'string' } },
+                required: ['sessionId', 'data'],
+            },
+        },
+        {
+            name: 'terminal_resize',
+            description: 'Resize an owner-scoped interactive terminal PTY.',
+            _meta: terminalMeta(['app']),
+            inputSchema: {
+                type: 'object',
+                properties: { sessionId: { type: 'string' }, cols: { type: 'number' }, rows: { type: 'number' } },
+                required: ['sessionId', 'cols', 'rows'],
+            },
+        },
+        {
+            name: 'terminal_close',
+            description: 'Close an owner-scoped interactive terminal PTY.',
+            _meta: terminalMeta(['app']),
+            inputSchema: {
+                type: 'object',
+                properties: { sessionId: { type: 'string' } },
+                required: ['sessionId'],
+            },
+        },
+        {
+            name: 'terminal_list',
+            description: 'List interactive terminal PTY sessions owned by this MCP App scope.',
+            _meta: terminalMeta(['app']),
+            inputSchema: { type: 'object', properties: {} },
+        },
+        {
+            name: 'run',
+            description: 'Run one command to completion. Output is sent as live progress when supported and returned with the exit code; use start/status for a persistent background session.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    command: { type: 'string', description: 'Command text in the selected shell\'s syntax.' },
+                    cwd: cwdProp,
+                    shell: shellProp,
+                    env: envProp,
+                    timeout: { type: 'number', description: 'Timeout in seconds (default 60, max 600).' },
+                    normalizeNewlines: { type: 'boolean', description: 'If true, CRLF/CR in the captured output are normalized to LF.' },
+                },
+                required: ['command'],
+            },
+        },
+        {
+            name: 'start',
+            description: 'Start an independent background command and return its sessionId. Multiple sessions may run in parallel; use status/wait, write_stdin, or kill.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    command: { type: 'string', description: 'The command line to execute in the background.' },
+                    cwd: cwdProp,
+                    shell: shellProp,
+                    env: envProp,
+                },
+                required: ['command'],
+            },
+        },
+        {
+            name: 'status',
+            description: 'Return the current state of a background session: { sessionId, running, exitCode, output, truncated }.',
+            inputSchema: {
+                type: 'object',
+                properties: { sessionId: { type: 'string', description: 'The id returned by start.' } },
+                required: ['sessionId'],
+            },
+        },
+        {
+            name: 'wait',
+            description: 'Wait for a background session, sending new output as live progress when supported. The wait timeout does not kill the session.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sessionId: { type: 'string', description: 'The id returned by start.' },
+                    timeout: { type: 'number', description: 'Max seconds to wait (default 60, max 600).' },
+                },
+                required: ['sessionId'],
+            },
+        },
+        {
+            name: 'write_stdin',
+            description: 'Write a string to a running background session\'s stdin. Pass "newline": false to omit the trailing newline. Returns { sessionId, written }.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sessionId: { type: 'string', description: 'The id returned by start.' },
+                    data: { type: 'string', description: 'Text to write to stdin.' },
+                    newline: { type: 'boolean', description: 'Append a trailing newline (default true).' },
+                },
+                required: ['sessionId', 'data'],
+            },
+        },
+        {
+            name: 'kill',
+            description: 'Kill a background session (and its whole process tree). Returns { sessionId, killed }.',
+            inputSchema: {
+                type: 'object',
+                properties: { sessionId: { type: 'string', description: 'The id returned by start.' } },
+                required: ['sessionId'],
+            },
+        },
+        {
+            name: 'list_sessions',
+            description: 'List background sessions owned by this caller scope. Returns { sessions: [{ sessionId, command, running, exitCode, startedAt, endedAt }] }.',
+            inputSchema: { type: 'object', properties: {} },
+        },
+    ];
+}
+function maybeNormalize(text, normalize) {
+    return normalize ? text.replace(/\r\n?/g, '\n') : text;
+}
+async function runTool(args, roots, context) {
+    const command = String(args?.command ?? '').trim();
+    if (!command)
+        return textResult({ error: 'Provide "command": a shell command line to run.' }, true);
+    const shellValidation = validateShell(args.shell);
+    if (!shellValidation.valid)
+        return invalidShellResult(shellValidation.requestedShell);
+    const requestedShell = shellValidation.shell;
+    const envValidation = validateEnv(args.env);
+    if (!envValidation.valid)
+        return textResult({ error: envValidation.error }, true);
+    if (context?.signal?.aborted) {
+        return textResult({ error: 'Command cancelled before it started.', cancelled: true, requestedShell }, true);
+    }
+    const cwd = await resolveCwd(args.cwd, roots);
+    const warnings = await scanCommandForExternalPaths(command, cwd, roots);
+    const warn = warnings.length ? { warnings } : {};
+    const normalize = args.normalizeNewlines === true;
+    const timeoutSec = typeof args.timeout === 'number' && args.timeout > 0 ? args.timeout : DEFAULT_TIMEOUT_MS / 1000;
+    const timeoutMs = Math.min(timeoutSec * 1000, MAX_TIMEOUT_MS);
+    registerExitCleanup();
+    return await new Promise((resolve) => {
+        let output = '';
+        let truncated = false;
+        let settled = false;
+        const append = makeAppender(() => output, (v, t) => { output = v; truncated = t || truncated; });
+        const progress = createCommandProgressReporter(context);
+        const { child, startError, effectiveShell, unavailableShell } = startChild(command, cwd, requestedShell, envValidation.env);
+        if (unavailableShell) {
+            void progress.stop().then(() => {
+                resolve(textResult({ error: `Requested shell "${unavailableShell}" is unavailable or could not be resolved.`, cwd, shell: unavailableShell }, true));
+            });
+            return;
+        }
+        if (startError || !child) {
+            void progress.stop().then(() => {
+                resolve(textResult({ error: `Failed to start command (${effectiveShell}): ${startError ?? 'unknown error'}`, cwd, shell: effectiveShell }, true));
+            });
+            return;
+        }
+        foregroundChildren().add(child);
+        let cancelEscalation;
+        let timer;
+        const onAbort = () => {
+            cancelEscalation = killProcessTree(child);
+            const finalOut = maybeNormalize(output, normalize);
+            void finish(textResult({
+                error: 'Command cancelled.',
+                cancelled: true,
+                cwd,
+                requestedShell,
+                shell: effectiveShell,
+                exitCode: null,
+                truncated,
+                output: finalOut,
+                ...warn,
+            }, true), true);
+        };
+        const finish = async (result, keepKillEscalation = false) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            context?.signal?.removeEventListener('abort', onAbort);
+            if (!keepKillEscalation)
+                cancelEscalation?.();
+            await progress.stop();
+            resolve(result);
+        };
+        timer = setTimeout(() => {
+            cancelEscalation = killProcessTree(child);
+            const finalOut = maybeNormalize(output, normalize);
+            void finish(textResult({
+                timedOut: true,
+                cwd,
+                requestedShell,
+                shell: effectiveShell,
+                exitCode: null,
+                truncated,
+                output: `${finalOut}${finalOut ? '\n' : ''}[killed after ${timeoutMs / 1000}s timeout]`,
+                ...warn,
+            }, true), true);
+        }, timeoutMs);
+        child.stdout?.on('data', (d) => {
+            const chunk = d.toString();
+            append(chunk);
+            progress.push(maybeNormalize(chunk, normalize));
+        });
+        child.stderr?.on('data', (d) => {
+            const chunk = d.toString();
+            append(chunk);
+            progress.push(maybeNormalize(chunk, normalize));
+        });
+        child.on('error', (err) => {
+            // ENOENT here means the resolved executable vanished between resolution and spawn.
+            foregroundChildren().delete(child);
+            append(`\n${err.message}`);
+            void finish(textResult({ error: `Command failed to start (${effectiveShell}): ${err.message}`, cwd, shell: effectiveShell, output: maybeNormalize(output, normalize) }, true));
+        });
+        child.on('close', (code) => {
+            foregroundChildren().delete(child);
+            cancelEscalation?.();
+            if (settled)
+                return;
+            const finalOut = maybeNormalize(output, normalize);
+            void finish(textResult({ exitCode: code, cwd, requestedShell, shell: effectiveShell, truncated, output: finalOut, ...warn }, code !== 0));
+        });
+        if (context?.signal?.aborted)
+            onAbort();
+        else
+            context?.signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function scheduleReap(session) {
+    session.reapTimer = setTimeout(() => {
+        sessions().delete(session.id);
+    }, SESSION_TTL_MS);
+    // Do not keep the event loop alive just to reap a session.
+    session.reapTimer.unref?.();
+}
+async function startTool(args, roots, ownerScope, context) {
+    const command = String(args?.command ?? '').trim();
+    if (!command)
+        return textResult({ error: 'Provide "command": a shell command line to run.' }, true);
+    const shellValidation = validateShell(args.shell);
+    if (!shellValidation.valid)
+        return invalidShellResult(shellValidation.requestedShell);
+    const requestedShell = shellValidation.shell;
+    const envValidation = validateEnv(args.env);
+    if (!envValidation.valid)
+        return textResult({ error: envValidation.error }, true);
+    if (context?.signal?.aborted) {
+        return textResult({ error: 'Command cancelled before it started.', cancelled: true, requestedShell }, true);
+    }
+    // Sweep finished sessions before enforcing the cap so a long-lived process
+    // doesn't get blocked by stale completed entries.
+    const table = sessions();
+    if (table.size >= MAX_SESSIONS) {
+        for (const [id, s] of table) {
+            if (!s.running)
+                table.delete(id);
+        }
+    }
+    if (table.size >= MAX_SESSIONS) {
+        return textResult({ error: `Too many active background sessions (max ${MAX_SESSIONS}). Kill some first.` }, true);
+    }
+    registerExitCleanup();
+    const cwd = await resolveCwd(args.cwd, roots);
+    const warnings = await scanCommandForExternalPaths(command, cwd, roots);
+    const warn = warnings.length ? { warnings } : {};
+    const { child, startError, effectiveShell, unavailableShell } = startChild(command, cwd, requestedShell, envValidation.env);
+    if (unavailableShell) {
+        return textResult({ error: `Requested shell "${unavailableShell}" is unavailable or could not be resolved.`, cwd, shell: unavailableShell }, true);
+    }
+    if (startError || !child) {
+        return textResult({ error: `Failed to start command (${effectiveShell}): ${startError ?? 'unknown error'}`, cwd, shell: effectiveShell }, true);
+    }
+    const id = `bash-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const session = {
+        id,
+        ownerScope,
+        command,
+        cwd,
+        child,
+        output: '',
+        truncated: false,
+        running: true,
+        exitCode: null,
+        startedAt: Date.now(),
+    };
+    table.set(id, session);
+    const append = makeAppender(() => session.output, (v, t) => { session.output = v; session.truncated = t || session.truncated; });
+    child.stdout?.on('data', (d) => append(d.toString()));
+    child.stderr?.on('data', (d) => append(d.toString()));
+    child.on('error', (err) => {
+        append(`\n${err.message}`);
+        session.running = false;
+        session.endedAt = Date.now();
+        scheduleReap(session);
+    });
+    child.on('close', (code) => {
+        session.running = false;
+        session.exitCode = code;
+        session.endedAt = Date.now();
+        scheduleReap(session);
+    });
+    return textResult({ sessionId: id, cwd, requestedShell, shell: effectiveShell, ...warn });
+}
+function snapshot(session, extra = {}) {
+    return {
+        sessionId: session.id,
+        running: session.running,
+        exitCode: session.exitCode,
+        output: session.output,
+        truncated: session.truncated,
+        ...extra,
+    };
+}
+function statusTool(args, ownerScope) {
+    const id = String(args?.sessionId ?? '');
+    const session = ownedSession(id, ownerScope);
+    if (!session)
+        return textResult({ error: `No background session with id "${id}".` }, true);
+    return textResult(snapshot(session));
+}
+async function waitTool(args, ownerScope, context) {
+    const id = String(args?.sessionId ?? '');
+    const session = ownedSession(id, ownerScope);
+    if (!session)
+        return textResult({ error: `No background session with id "${id}".` }, true);
+    if (!session.running)
+        return textResult(snapshot(session, { timedOut: false }));
+    if (context?.signal?.aborted) {
+        return textResult(snapshot(session, { timedOut: false, cancelled: true }), true);
+    }
+    const timeoutSec = typeof args.timeout === 'number' && args.timeout > 0 ? args.timeout : DEFAULT_TIMEOUT_MS / 1000;
+    const timeoutMs = Math.min(timeoutSec * 1000, MAX_TIMEOUT_MS);
+    const progress = createCommandProgressReporter(context);
+    const outcome = await new Promise((resolve) => {
+        let settled = false;
+        let pollTimer;
+        let timeoutTimer;
+        let outputOffset = 0;
+        const finish = async (value) => {
+            if (settled)
+                return;
+            settled = true;
+            if (pollTimer)
+                clearTimeout(pollTimer);
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            context?.signal?.removeEventListener('abort', onAbort);
+            if (session.output.length > outputOffset)
+                progress.push(session.output.slice(outputOffset));
+            await progress.stop();
+            resolve(value);
+        };
+        const onAbort = () => void finish('cancelled');
+        const poll = () => {
+            if (session.output.length > outputOffset) {
+                progress.push(session.output.slice(outputOffset));
+                outputOffset = session.output.length;
+            }
+            if (!session.running) {
+                void finish('completed');
+                return;
+            }
+            pollTimer = setTimeout(poll, 100);
+        };
+        timeoutTimer = setTimeout(() => void finish('timedOut'), timeoutMs);
+        context?.signal?.addEventListener('abort', onAbort, { once: true });
+        poll();
+    });
+    return textResult(snapshot(session, {
+        timedOut: outcome === 'timedOut',
+        ...(outcome === 'cancelled' ? { cancelled: true } : {}),
+    }), outcome === 'cancelled');
+}
+function writeStdinTool(args, ownerScope) {
+    const id = String(args?.sessionId ?? '');
+    const session = ownedSession(id, ownerScope);
+    if (!session)
+        return textResult({ error: `No background session with id "${id}".` }, true);
+    if (!session.running)
+        return textResult({ error: `Session "${id}" has already exited.` }, true);
+    const data = typeof args.data === 'string' ? args.data : '';
+    const withNewline = args.newline === false ? data : `${data}\n`;
+    try {
+        session.child.stdin?.write(withNewline);
+    }
+    catch (err) {
+        return textResult({ error: `Failed to write to stdin: ${err instanceof Error ? err.message : String(err)}` }, true);
+    }
+    return textResult({ sessionId: id, written: Buffer.byteLength(withNewline, 'utf8') });
+}
+function killTool(args, ownerScope) {
+    const id = String(args?.sessionId ?? '');
+    const session = ownedSession(id, ownerScope);
+    if (!session)
+        return textResult({ error: `No background session with id "${id}".` }, true);
+    if (session.running) {
+        session.cancelEscalation = killProcessTree(session.child);
+    }
+    return textResult({ sessionId: id, killed: true });
+}
+function listSessionsTool(ownerScope) {
+    const list = Array.from(sessions().values())
+        .filter((s) => s.ownerScope === ownerScope)
+        .map((s) => ({
+        sessionId: s.id,
+        command: s.command,
+        running: s.running,
+        exitCode: s.exitCode,
+        startedAt: new Date(s.startedAt).toISOString(),
+        endedAt: s.endedAt ? new Date(s.endedAt).toISOString() : undefined,
+    }));
+    return textResult({ sessions: list });
+}
+function terminalSnapshot(session) {
+    return {
+        sessionId: session.id,
+        shell: session.shell,
+        cwd: session.cwd,
+        running: session.running,
+        exitCode: session.exitCode,
+        cursor: session.nextCursor,
+    };
+}
+function scheduleTerminalReap(session) {
+    session.reapTimer = setTimeout(() => terminalSessions().delete(session.id), SESSION_TTL_MS);
+    session.reapTimer.unref?.();
+}
+function appendTerminalOutput(session, chunk) {
+    if (!chunk)
+        return;
+    session.output += chunk;
+    session.nextCursor += chunk.length;
+    if (session.output.length > MAX_TERMINAL_OUTPUT_CHARS) {
+        const remove = session.output.length - MAX_TERMINAL_OUTPUT_CHARS;
+        session.output = session.output.slice(remove);
+        session.outputStart += remove;
+    }
+}
+async function openTerminalTool(args, roots, ownerScope) {
+    const shellValidation = validateShell(args.shell);
+    if (!shellValidation.valid)
+        return invalidShellResult(shellValidation.requestedShell);
+    const envValidation = validateEnv(args.env);
+    if (!envValidation.valid)
+        return textResult({ error: envValidation.error }, true);
+    const ownedRunning = Array.from(terminalSessions().values())
+        .filter((session) => session.ownerScope === ownerScope && session.running);
+    if (ownedRunning.length >= MAX_SESSIONS) {
+        return textResult({ error: `Too many active terminal sessions (max ${MAX_SESSIONS}). Close one first.` }, true);
+    }
+    const cwd = await resolveCwd(args.cwd, roots);
+    const plan = buildPtySpawn(shellValidation.shell);
+    if (plan.unavailableShell) {
+        return textResult({ error: `Requested shell "${plan.unavailableShell}" is unavailable or could not be resolved.` }, true);
+    }
+    if (plan.startError)
+        return textResult({ error: plan.startError }, true);
+    const cols = Math.max(20, Math.min(400, Math.floor(typeof args.cols === 'number' ? args.cols : 100)));
+    const rows = Math.max(5, Math.min(200, Math.floor(typeof args.rows === 'number' ? args.rows : 30)));
+    let pty;
+    try {
+        pty = spawnPty(plan.file, plan.args, {
+            name: 'xterm-256color',
+            cols,
+            rows,
+            cwd,
+            env: {
+                ...buildChildEnv(envValidation.env),
+                TERM: 'xterm-256color',
+                COLORTERM: 'truecolor',
+            },
+        });
+    }
+    catch (error) {
+        return textResult({
+            error: `Failed to open pseudoterminal (${plan.effectiveShell}): ${error instanceof Error ? error.message : String(error)}`,
+            cwd,
+            shell: plan.effectiveShell,
+        }, true);
+    }
+    registerExitCleanup();
+    const id = `terminal-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const session = {
+        id,
+        ownerScope,
+        shell: plan.effectiveShell,
+        cwd,
+        pty,
+        output: '',
+        outputStart: 0,
+        nextCursor: 0,
+        running: true,
+        exitCode: null,
+        startedAt: Date.now(),
+    };
+    terminalSessions().set(id, session);
+    pty.onData((chunk) => appendTerminalOutput(session, chunk));
+    pty.onExit(({ exitCode }) => {
+        session.running = false;
+        session.exitCode = exitCode;
+        session.endedAt = Date.now();
+        scheduleTerminalReap(session);
+    });
+    return textResult({ ...terminalSnapshot(session), cols, rows });
+}
+function ownedTerminal(id, ownerScope) {
+    const session = terminalSessions().get(id);
+    return session?.ownerScope === ownerScope ? session : undefined;
+}
+function readTerminalTool(args, ownerScope) {
+    const id = String(args.sessionId ?? '');
+    const session = ownedTerminal(id, ownerScope);
+    if (!session)
+        return textResult({ error: `No terminal session with id "${id}".` }, true);
+    const requested = Number.isFinite(args.cursor) ? Math.max(0, Math.floor(Number(args.cursor))) : session.outputStart;
+    const reset = requested < session.outputStart || requested > session.nextCursor;
+    const cursor = reset ? session.outputStart : requested;
+    return textResult({
+        ...terminalSnapshot(session),
+        chunk: session.output.slice(cursor - session.outputStart),
+        nextCursor: session.nextCursor,
+        reset,
+    });
+}
+function writeTerminalTool(args, ownerScope) {
+    const id = String(args.sessionId ?? '');
+    const session = ownedTerminal(id, ownerScope);
+    if (!session)
+        return textResult({ error: `No terminal session with id "${id}".` }, true);
+    if (!session.running)
+        return textResult({ error: `Terminal session "${id}" has exited.` }, true);
+    const data = typeof args.data === 'string' ? args.data : '';
+    if (data.length > 65_536)
+        return textResult({ error: 'Terminal input is limited to 65,536 characters per write.' }, true);
+    try {
+        session.pty.write(data);
+        return textResult({ sessionId: id, written: Buffer.byteLength(data, 'utf8') });
+    }
+    catch (error) {
+        return textResult({ error: `Failed to write terminal input: ${error instanceof Error ? error.message : String(error)}` }, true);
+    }
+}
+function resizeTerminalTool(args, ownerScope) {
+    const id = String(args.sessionId ?? '');
+    const session = ownedTerminal(id, ownerScope);
+    if (!session)
+        return textResult({ error: `No terminal session with id "${id}".` }, true);
+    const cols = Math.max(20, Math.min(400, Math.floor(Number(args.cols))));
+    const rows = Math.max(5, Math.min(200, Math.floor(Number(args.rows))));
+    if (!Number.isFinite(cols) || !Number.isFinite(rows))
+        return textResult({ error: 'cols and rows must be finite numbers.' }, true);
+    try {
+        if (session.running)
+            session.pty.resize(cols, rows);
+        return textResult({ sessionId: id, cols, rows });
+    }
+    catch (error) {
+        return textResult({ error: `Failed to resize terminal: ${error instanceof Error ? error.message : String(error)}` }, true);
+    }
+}
+function closeTerminalTool(args, ownerScope) {
+    const id = String(args.sessionId ?? '');
+    const session = ownedTerminal(id, ownerScope);
+    if (!session)
+        return textResult({ error: `No terminal session with id "${id}".` }, true);
+    try {
+        if (session.running) {
+            session.running = false;
+            session.pty.kill();
+        }
+        return textResult({ sessionId: id, closed: true });
+    }
+    catch (error) {
+        return textResult({ error: `Failed to close terminal: ${error instanceof Error ? error.message : String(error)}` }, true);
+    }
+}
+function listTerminalsTool(ownerScope) {
+    return textResult({
+        sessions: Array.from(terminalSessions().values())
+            .filter((session) => session.ownerScope === ownerScope)
+            .map((session) => ({
+            ...terminalSnapshot(session),
+            startedAt: new Date(session.startedAt).toISOString(),
+            endedAt: session.endedAt ? new Date(session.endedAt).toISOString() : undefined,
+        })),
+    });
+}
+export async function bashCallTool(toolName, args, callerNodeId, ownerScope, context) {
+    try {
+        const scope = effectiveOwnerScope(ownerScope, callerNodeId);
+        switch (toolName) {
+            case 'open_terminal': {
+                const roots = await loadEffectiveRoots(BASH_SERVER_NAME, BASH_ROOT_ENV_VARS, callerNodeId);
+                return await openTerminalTool(args, roots, scope);
+            }
+            case 'terminal_read':
+                return readTerminalTool(args, scope);
+            case 'terminal_write':
+                return writeTerminalTool(args, scope);
+            case 'terminal_resize':
+                return resizeTerminalTool(args, scope);
+            case 'terminal_close':
+                return closeTerminalTool(args, scope);
+            case 'terminal_list':
+                return listTerminalsTool(scope);
+            case 'run': {
+                const roots = await loadEffectiveRoots(BASH_SERVER_NAME, BASH_ROOT_ENV_VARS, callerNodeId);
+                return await runTool(args, roots, context);
+            }
+            case 'start': {
+                const roots = await loadEffectiveRoots(BASH_SERVER_NAME, BASH_ROOT_ENV_VARS, callerNodeId);
+                return await startTool(args, roots, scope, context);
+            }
+            case 'status':
+                return statusTool(args, scope);
+            case 'wait':
+                return await waitTool(args, scope, context);
+            case 'write_stdin':
+                return writeStdinTool(args, scope);
+            case 'kill':
+                return killTool(args, scope);
+            case 'list_sessions':
+                return listSessionsTool(scope);
+            default:
+                return textResult({ error: `Unknown tool on the built-in bash server: ${toolName}` }, true);
+        }
+    }
+    catch (err) {
+        log.warn('bashCallTool failed', { toolName, err });
+        return textResult({ error: `Tool failed: ${err instanceof Error ? err.message : String(err)}` }, true);
+    }
+}
+/** Test-only: force-kill and clear all sessions. */
+export function _resetBashSessionsForTests() {
+    shutdownBashSessions();
+    foregroundChildren().clear();
+    sessions().clear();
+    terminalSessions().clear();
+}
+//# sourceMappingURL=tools.js.map