@mario.andreschak/mcp-bash 3.42.1 → 3.44.0

package/dist/tools.d.ts

@@ -2,6 +2,8 @@ import { type ChildProcess } from 'node:child_process';
 import { type IPty } from '@lydell/node-pty';
 import type { Tool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 export declare const BASH_TERMINAL_APP_URI = "ui://bash/terminal";
+/** Test seam for the public timeout contract; not used by the runtime. */
+export declare function _resolveCommandTimeoutMsForTests(value: unknown): number | undefined;
 type EffectiveShell = 'pwsh' | 'powershell' | 'bash' | 'cmd' | 'sh';
 export interface BashToolProgress {
     progress: number;
@@ -11,6 +13,28 @@ export interface BashExecutionContext {
     signal?: AbortSignal;
     onProgress?: (progress: BashToolProgress) => void | Promise<void>;
 }
+export interface ShellInfoShellEntry {
+    shell: string;
+    available: boolean;
+    path: string | null;
+}
+export interface ShellInfoBinaryEntry {
+    name: string;
+    found: boolean;
+    path: string | null;
+    /** Windows Store app-execution alias stub: present on PATH but not runnable. */
+    alias?: boolean;
+}
+export interface ShellInfoPayload {
+    platform: NodeJS.Platform;
+    defaultShell: EffectiveShell;
+    defaultShellPath: string | null;
+    shells: ShellInfoShellEntry[];
+    binaries: ShellInfoBinaryEntry[];
+    notes: string[];
+}
+/** Describe the shells and interpreters actually available on this machine. */
+export declare function collectShellInfo(): ShellInfoPayload;
 /** Test-only: forget cached shell-executable lookups. */
 export declare function _resetBashShellCacheForTests(): void;
 interface BashSession {
@@ -22,12 +46,24 @@ interface BashSession {
     child: ChildProcess;
     output: string;
     truncated: boolean;
+    /** Characters that arrived on stderr (logging volume, not failure).  */
+    stderrChars?: number;
     running: boolean;
     exitCode: number | null;
     startedAt: number;
     endedAt?: number;
     cancelEscalation?: () => void;
     reapTimer?: NodeJS.Timeout;
+    /** Preflight found a command head that cannot be resolved on PATH. */
+    missingExecutableWarning?: boolean;
+    /**
+     * Explicit opt-in to surviving owner release (issue #413). Default false: a
+     * session outliving its run must be a deliberate choice, not the accident that
+     * made every `start` a permanent process.
+     */
+    detached?: boolean;
+    /** Last output/read/write — drives idle expiry. */
+    lastActivityAt: number;
 }
 interface TerminalSession {
     id: string;
@@ -43,15 +79,92 @@ interface TerminalSession {
     startedAt: number;
     endedAt?: number;
     reapTimer?: NodeJS.Timeout;
+    /** Explicit opt-in to surviving owner release (issue #413). */
+    detached?: boolean;
+    /** Last output/read/write — drives idle expiry. */
+    lastActivityAt: number;
 }
 declare global {
     var __flujo_bash_sessions: Map<string, BashSession> | undefined;
     var __flujo_terminal_sessions: Map<string, TerminalSession> | undefined;
     var __flujo_bash_foreground_children: Set<ChildProcess> | undefined;
     var __flujo_bash_cleanup_registered: boolean | undefined;
+    var __flujo_bash_sweep_timer: NodeJS.Timeout | undefined;
 }
-/** Kill every live session's process tree — used on FLUJO process exit. */
+export interface OwnerReleaseResult {
+    ownerScope: string;
+    /** Background session ids that were killed. */
+    killedSessions: string[];
+    /** PTY session ids that were closed. */
+    closedTerminals: string[];
+    /** Sessions deliberately left alive because they opted into `detached`. */
+    retainedDetached: string[];
+}
+/**
+ * Atomically remove and terminate every NON-DETACHED session of one owner.
+ *
+ * Called when the owning FLUJO run reaches a terminal state. Removing the map
+ * entry BEFORE killing means a concurrent release (or a second call from a retry
+ * path) cannot observe the same session twice, so the operation is idempotent -
+ * repeated releases of the same scope are a no-op instead of a double kill
+ * against a possibly-recycled pid.
+ */
+export declare function releaseOwnerScope(ownerScope: string): OwnerReleaseResult;
+/**
+ * Expire live sessions that exceeded the idle timeout or the absolute lifetime.
+ *
+ * Detached sessions are exempt from IDLE expiry (being idle is often the point of
+ * a detached watcher) but NOT from the absolute lifetime ceiling - otherwise
+ * `detached` would be an unbounded leak with extra steps.
+ */
+export declare function expireStaleSessions(now?: number): string[];
+/** Bounded per-session diagnostics: identity/state only, never output. */
+export declare function bashSessionDiagnostics(): {
+    liveSessions: number;
+    maxLiveSessions: number;
+    sessions: Array<{
+        sessionId: string;
+        type: 'background' | 'terminal';
+        ownerScope: string;
+        running: boolean;
+        detached: boolean;
+        ageMs: number;
+        idleMs: number;
+    }>;
+};
+/**
+ * Kill every live session's process tree - used on Bash server shutdown and on
+ * FLUJO process exit.
+ *
+ * Idempotent and DETACHED-INCLUSIVE: a detached session survives owner release,
+ * but nothing survives the death of the server that owns its pipes. Timers are
+ * cleared too, so a repeated call cannot leave a handle keeping the event loop
+ * alive after "shutdown".
+ */
 export declare function shutdownBashSessions(): void;
+export declare function wrapPowerShellCommand(command: string): string;
+/** `chcp 65001` forces UTF-8 output for cmd.exe children (issue #364). */
+export declare function wrapCmdCommand(command: string): string;
+export interface OutputAppender {
+    (chunk: string): void;
+    /** Total characters ever appended, including any omitted middle. */
+    totalChars: () => number;
+    /** Characters dropped from the middle because of the cap. */
+    droppedChars: () => number;
+}
+/** True when the command relies on POSIX `&&` / `||` statement chaining. */
+export declare function commandUsesPosixChaining(command: string): boolean;
+export declare function detectDialectMismatch(command: string, shell: EffectiveShell, isAvailable?: (name: string) => boolean): string[];
+/** Commands that typically hang forever waiting on a pager or interactive prompt. */
+export declare function detectInteractiveHangRisk(command: string): string[];
+export type OutputEncodingMode = 'utf8' | 'utf16le' | 'auto';
+/**
+ * Decode child output deterministically (issue #364). Windows tooling happily
+ * writes UTF-16LE (e.g. PowerShell redirection into a log) which the default
+ * UTF-8 decode turns into NUL-riddled mojibake. `auto` sniffs a BOM or a high
+ * NUL ratio in the first chunk and then stays with that choice.
+ */
+export declare function createStreamDecoder(mode?: OutputEncodingMode): (chunk: Buffer | string) => string;
 export declare function bashToolDefinitions(): Tool[];
 export declare function bashCallTool(toolName: string, args: Record<string, unknown>, callerNodeId?: string, ownerScope?: string, context?: BashExecutionContext): Promise<CallToolResult>;
 /** Test-only: force-kill and clear all sessions. */