@prestyj/cli 5.28.0 → 5.29.0

package/dist/core/keep-awake.js

@@ -0,0 +1,251 @@
+/**
+ * Keep the computer from idle-sleeping while the agent works.
+ *
+ * Autopilot cycles, task sweeps and long runs die halfway when a laptop idles
+ * into system sleep. This holds an OS power assertion for as long as any agent
+ * work is in flight. Only idle SYSTEM sleep is prevented — the display may
+ * still turn off, and an explicit sleep (lid close, menu) still wins.
+ *
+ * No native dependencies: each platform's own tool holds the assertion in a
+ * child process, and the assertion dies with that child.
+ *
+ * - macOS: `caffeinate -i -w <pid>` — exits by itself when our process dies.
+ * - Linux: `systemd-inhibit --what=idle:sleep … tail --pid=<pid> -f /dev/null`
+ *   — the inhibitor lock lives as long as `tail`, which exits when our process
+ *   dies. Spawned as its own process group so release kills both. No
+ *   systemd-inhibit (non-systemd distro) → logged no-op.
+ * - Windows: a hidden PowerShell that P/Invokes `SetThreadExecutionState(
+ *   ES_CONTINUOUS | ES_SYSTEM_REQUIRED)` and then `Wait-Process`es our PID.
+ *   The execution state is per-thread, so it is cleared when that process ends.
+ *
+ * Reference-counted: overlapping runs (several windows, a run plus a Nolan reply,
+ * background sub-agents) share one OS assertion, which is dropped when the last
+ * holder releases.
+ */
+import { spawn } from "node:child_process";
+import { log } from "./logger.js";
+/** ES_CONTINUOUS (0x80000000) | ES_SYSTEM_REQUIRED (0x00000001). */
+const WINDOWS_EXECUTION_STATE = 2147483649;
+const LINUX_WHY = "Agent is working";
+function windowsScript(pid) {
+    return [
+        "$ErrorActionPreference = 'Stop'",
+        "$k = Add-Type -Name KeepAwake -Namespace GG -PassThru -MemberDefinition " +
+            "'[DllImport(\"kernel32.dll\")] public static extern uint SetThreadExecutionState(uint esFlags);'",
+        `if ($k::SetThreadExecutionState([uint32]${WINDOWS_EXECUTION_STATE}) -eq 0) { exit 1 }`,
+        // Blocks this (assertion-holding) thread until our process exits; release
+        // terminates PowerShell first, which clears the execution state.
+        `Wait-Process -Id ${pid} -ErrorAction SilentlyContinue`,
+    ].join("\n");
+}
+/** The OS tool that holds an idle-sleep assertion tied to `pid`, or null if none. */
+export function keepAwakeCommand(platform, pid) {
+    switch (platform) {
+        case "darwin":
+            return { command: "caffeinate", args: ["-i", "-w", String(pid)] };
+        case "linux":
+            return {
+                command: "systemd-inhibit",
+                args: [
+                    "--what=idle:sleep",
+                    "--who=GG",
+                    `--why=${LINUX_WHY}`,
+                    "--mode=block",
+                    "tail",
+                    `--pid=${pid}`,
+                    "-f",
+                    "/dev/null",
+                ],
+            };
+        case "win32":
+            return {
+                command: "powershell.exe",
+                args: [
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-ExecutionPolicy",
+                    "Bypass",
+                    "-WindowStyle",
+                    "Hidden",
+                    "-EncodedCommand",
+                    Buffer.from(windowsScript(pid), "utf16le").toString("base64"),
+                ],
+            };
+        default:
+            return null;
+    }
+}
+/** Real spawner: argv array, no shell, hidden window, stdio ignored. */
+export function spawnKeepAwakeProcess(cmd) {
+    // Linux gets its own process group so release can kill systemd-inhibit AND
+    // the `tail` it runs; macOS/Windows holders have no children of their own.
+    const group = process.platform === "linux";
+    const child = spawn(cmd.command, cmd.args, {
+        stdio: "ignore",
+        windowsHide: true,
+        shell: false,
+        detached: group,
+    });
+    // The holder must never keep the sidecar's event loop alive.
+    child.unref();
+    return {
+        stop() {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            if (group && child.pid !== undefined) {
+                try {
+                    process.kill(-child.pid, "SIGTERM");
+                    return;
+                }
+                catch {
+                    // Fall through to the single-process kill.
+                }
+            }
+            try {
+                child.kill();
+            }
+            catch {
+                // Already gone.
+            }
+        },
+        onExit(listener) {
+            child.once("exit", () => listener());
+        },
+        onError(listener) {
+            child.once("error", (error) => listener(error));
+        },
+    };
+}
+/** Reference-counted holder of one OS idle-sleep assertion. */
+export class KeepAwake {
+    holds = new Map();
+    nextId = 0;
+    enabled;
+    child = null;
+    /** The platform tool is missing — permanently a no-op for this process. */
+    unavailable = false;
+    /** The holder died on its own; don't respawn until holders drop to zero. */
+    suspended = false;
+    exitHookInstalled = false;
+    platform;
+    pid;
+    spawner;
+    logLine;
+    onProcessExit;
+    constructor(options = {}) {
+        this.platform = options.platform ?? process.platform;
+        this.pid = options.pid ?? process.pid;
+        this.enabled = options.enabled ?? true;
+        this.spawner = options.spawner ?? spawnKeepAwakeProcess;
+        this.logLine =
+            options.log ?? ((level, message, data) => log(level, "keep-awake", message, data));
+        this.onProcessExit = options.onProcessExit ?? ((cleanup) => process.once("exit", cleanup));
+    }
+    /** Hold the assertion until the returned release runs. Release is idempotent. */
+    acquire(reason) {
+        const id = ++this.nextId;
+        this.holds.set(id, reason);
+        this.sync();
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.holds.delete(id);
+            this.sync();
+        };
+    }
+    /** Apply the `keepAwake` setting live; outstanding holds survive a toggle. */
+    setEnabled(enabled) {
+        if (this.enabled === enabled)
+            return;
+        this.enabled = enabled;
+        this.suspended = false;
+        this.sync();
+    }
+    get isEnabled() {
+        return this.enabled;
+    }
+    get holderCount() {
+        return this.holds.size;
+    }
+    /** True while an OS assertion holder process is running. */
+    get asserting() {
+        return this.child !== null;
+    }
+    /** Drop every hold and the OS assertion (shutdown). */
+    dispose() {
+        this.holds.clear();
+        this.suspended = false;
+        this.stopChild();
+    }
+    sync() {
+        if (this.holds.size === 0)
+            this.suspended = false;
+        const want = this.enabled && this.holds.size > 0 && !this.unavailable && !this.suspended;
+        if (want && !this.child)
+            this.startChild();
+        else if (!want && this.child)
+            this.stopChild();
+    }
+    startChild() {
+        const cmd = keepAwakeCommand(this.platform, this.pid);
+        if (!cmd) {
+            this.unavailable = true;
+            this.logLine("INFO", "keep-awake unsupported on this platform; skipping", {
+                platform: this.platform,
+            });
+            return;
+        }
+        let child;
+        try {
+            child = this.spawner(cmd);
+        }
+        catch (error) {
+            this.markUnavailable(cmd, error);
+            return;
+        }
+        this.child = child;
+        if (!this.exitHookInstalled) {
+            this.exitHookInstalled = true;
+            this.onProcessExit(() => this.dispose());
+        }
+        child.onError((error) => {
+            if (this.child !== child)
+                return;
+            this.child = null;
+            this.markUnavailable(cmd, error);
+        });
+        child.onExit(() => {
+            // A holder we stopped, or a superseded one, is expected to exit.
+            if (this.child !== child)
+                return;
+            this.child = null;
+            this.suspended = true;
+            this.logLine("WARN", "keep-awake holder exited unexpectedly", { command: cmd.command });
+        });
+        this.logLine("INFO", "keep-awake on", {
+            command: cmd.command,
+            reasons: [...new Set(this.holds.values())].join(","),
+        });
+    }
+    stopChild() {
+        const child = this.child;
+        if (!child)
+            return;
+        this.child = null;
+        child.stop();
+        this.logLine("INFO", "keep-awake off");
+    }
+    markUnavailable(cmd, error) {
+        this.unavailable = true;
+        const code = error?.code;
+        this.logLine("INFO", code === "ENOENT"
+            ? "keep-awake tool not found; skipping"
+            : "keep-awake tool failed to start; skipping", {
+            command: cmd.command,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+//# sourceMappingURL=keep-awake.js.map

package/dist/core/keep-awake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keep-awake.js","sourceRoot":"","sources":["../../src/core/keep-awake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAsClC,oEAAoE;AACpE,MAAM,uBAAuB,GAAG,UAAU,CAAC;AAE3C,MAAM,SAAS,GAAG,kBAAkB,CAAC;AAErC,SAAS,aAAa,CAAC,GAAW;IAChC,OAAO;QACL,iCAAiC;QACjC,0EAA0E;YACxE,kGAAkG;QACpG,2CAA2C,uBAAuB,qBAAqB;QACvF,0EAA0E;QAC1E,iEAAiE;QACjE,oBAAoB,GAAG,gCAAgC;KACxD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAAC,QAAyB,EAAE,GAAW;IACrE,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,QAAQ;YACX,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACpE,KAAK,OAAO;YACV,OAAO;gBACL,OAAO,EAAE,iBAAiB;gBAC1B,IAAI,EAAE;oBACJ,mBAAmB;oBACnB,UAAU;oBACV,SAAS,SAAS,EAAE;oBACpB,cAAc;oBACd,MAAM;oBACN,SAAS,GAAG,EAAE;oBACd,IAAI;oBACJ,WAAW;iBACZ;aACF,CAAC;QACJ,KAAK,OAAO;YACV,OAAO;gBACL,OAAO,EAAE,gBAAgB;gBACzB,IAAI,EAAE;oBACJ,YAAY;oBACZ,iBAAiB;oBACjB,kBAAkB;oBAClB,QAAQ;oBACR,cAAc;oBACd,QAAQ;oBACR,iBAAiB;oBACjB,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;iBAC9D;aACF,CAAC;QACJ;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,qBAAqB,CAAC,GAAqB;IACzD,2EAA2E;IAC3E,2EAA2E;IAC3E,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;IAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE;QACzC,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,IAAI;QACjB,KAAK,EAAE,KAAK;QACZ,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAC;IACH,6DAA6D;IAC7D,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,OAAO;QACL,IAAI;YACF,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI;gBAAE,OAAO;YACjE,IAAI,KAAK,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBACrC,IAAI,CAAC;oBACH,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;oBACpC,OAAO;gBACT,CAAC;gBAAC,MAAM,CAAC;oBACP,2CAA2C;gBAC7C,CAAC;YACH,CAAC;YACD,IAAI,CAAC;gBACH,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,CAAC;YAAC,MAAM,CAAC;gBACP,gBAAgB;YAClB,CAAC;QACH,CAAC;QACD,MAAM,CAAC,QAAQ;YACb,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,CAAC,QAAQ;YACd,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;QAClD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,MAAM,OAAO,SAAS;IACH,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,GAAG,CAAC,CAAC;IACX,OAAO,CAAU;IACjB,KAAK,GAA4B,IAAI,CAAC;IAC9C,2EAA2E;IACnE,WAAW,GAAG,KAAK,CAAC;IAC5B,4EAA4E;IACpE,SAAS,GAAG,KAAK,CAAC;IAClB,iBAAiB,GAAG,KAAK,CAAC;IACjB,QAAQ,CAAkB;IAC1B,GAAG,CAAS;IACZ,OAAO,CAAmB;IAC1B,OAAO,CAAe;IACtB,aAAa,CAAgC;IAE9D,YAAY,UAA4B,EAAE;QACxC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;QACrD,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;QACtC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC;QACvC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,qBAAqB,CAAC;QACxD,IAAI,CAAC,OAAO;YACV,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QACrF,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7F,CAAC;IAED,iFAAiF;IACjF,OAAO,CAAC,MAAc;QACpB,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC;QACzB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,OAAO,GAAG,EAAE;YACV,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,IAAI,CAAC;YAChB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACtB,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,UAAU,CAAC,OAAgB;QACzB,IAAI,IAAI,CAAC,OAAO,KAAK,OAAO;YAAE,OAAO;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,4DAA4D;IAC5D,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC;IAC7B,CAAC;IAED,uDAAuD;IACvD,OAAO;QACL,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,IAAI,CAAC,SAAS,EAAE,CAAC;IACnB,CAAC;IAEO,IAAI;QACV,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;YAAE,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QAClD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;QACzF,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,UAAU,EAAE,CAAC;aACtC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,SAAS,EAAE,CAAC;IACjD,CAAC;IAEO,UAAU;QAChB,MAAM,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACtD,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YACxB,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,mDAAmD,EAAE;gBACxE,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACxB,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,IAAI,KAAuB,CAAC;QAC5B,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACjC,OAAO;QACT,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC5B,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC;YAC9B,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;YACtB,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK;gBAAE,OAAO;YACjC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE;YAChB,iEAAiE;YACjE,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK;gBAAE,OAAO;YACjC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACtB,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,uCAAuC,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1F,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE;YACpC,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,OAAO,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;SACrD,CAAC,CAAC;IACL,CAAC;IAEO,SAAS;QACf,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,KAAK,CAAC,IAAI,EAAE,CAAC;QACb,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACzC,CAAC;IAEO,eAAe,CAAC,GAAqB,EAAE,KAAc;QAC3D,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,MAAM,IAAI,GAAI,KAA2C,EAAE,IAAI,CAAC;QAChE,IAAI,CAAC,OAAO,CACV,MAAM,EACN,IAAI,KAAK,QAAQ;YACf,CAAC,CAAC,qCAAqC;YACvC,CAAC,CAAC,2CAA2C,EAC/C;YACE,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CACF,CAAC;IACJ,CAAC;CACF"}

package/dist/core/mcp/client.d.ts

@@ -3,6 +3,29 @@ import type { AgentTool } from "@prestyj/agent";
 import type { MCPServerConfig } from "./types.js";
 import { McpCatalogCache } from "./catalog-cache.js";
 import { type SharedMcpPool } from "./shared-pool.js";
+/**
+ * How long a stdio server may sit with no call in flight before its process is
+ * stopped. It is respawned transparently on the next call.
+ *
+ * 15 min, deliberately longer than pi-mcp-adapter's 10 min default: one pooled
+ * child here serves every window in the daemon, so a premature stop is paid as
+ * a cold start (`npx`/node boot + handshake, often seconds) by whichever chat
+ * calls next. 15 min still covers the read/think/edit pauses inside one task
+ * while reclaiming servers a session touched once and moved on from.
+ */
+export declare const MCP_DEFAULT_IDLE_TIMEOUT_MS: number;
+/**
+ * Default per-call window without a response or progress notification. Equal
+ * to the SDK's own `DEFAULT_REQUEST_TIMEOUT_MSEC`; `config.timeout` overrides.
+ */
+export declare const MCP_DEFAULT_CALL_TIMEOUT_MS = 60000;
+/**
+ * Default hard cap on one tool call, however much progress it reports — so a
+ * server stuck in a progress loop cannot hold a turn forever. Generous because
+ * the tools that report progress are the long ones (builds, crawls, renders);
+ * `config.maxTotalTimeout` overrides.
+ */
+export declare const MCP_DEFAULT_MAX_TOTAL_TIMEOUT_MS: number;
 /** Per-server connection outcome for the dashboard / non-interactive list. */
 export interface MCPConnectResult {
     name: string;
@@ -20,6 +43,15 @@ export interface MCPLoginResult {
     toolCount: number;
     error?: string;
 }
+/**
+ * A failed MCP tool call. Thrown (not returned as text) so the agent loop
+ * records the result as an error: the app shows it as failed and receipts,
+ * the loop breaker and verification all see a failure, not a success whose
+ * text happens to say "error". The message is what the model reads.
+ */
+export declare class McpToolError extends Error {
+    readonly name = "McpToolError";
+}
 /** Terminal state of one server's connection attempt, awaited by `whenConnected`. */
 type ConnectionOutcome = {
     ok: true;
@@ -88,13 +120,53 @@ export declare class MCPClientManager {
     private readonly onServerClosed?;
     /** Set while `dispose` runs, so our own teardown is not reported as a death. */
     private disposing;
+    /** Idle period before a stdio server is stopped; 0 disables idle shutdown. */
+    private readonly idleTimeoutMs;
+    /** Idle bookkeeping per server name, for servers eligible for idle shutdown. */
+    private idle;
+    /**
+     * Clients we closed ON PURPOSE for idleness. Their `onclose` must not be
+     * reported as a death — that would make the pool evict a connection whose
+     * tools are still published and which will respawn on the next call.
+     */
+    private idleStopped;
     constructor(opts?: {
         catalogCache?: McpCatalogCache;
         modernProtocol?: boolean;
         onElicit?: MCPElicitHandler;
         sharedPool?: SharedMcpPool;
         onServerClosed?: (name: string) => void;
+        /** Override `MCP_DEFAULT_IDLE_TIMEOUT_MS`; 0 disables idle shutdown. */
+        idleTimeoutMs?: number;
     });
+    /**
+     * Does this server get stopped when idle?
+     *
+     * Only stdio servers: idle shutdown exists to reclaim a child PROCESS, and an
+     * HTTP server has none on our side. Closing one would save nothing locally
+     * while throwing away its `Mcp-Session-Id` (server-side state) and forcing a
+     * fresh handshake — possibly an OAuth refresh — on the next call.
+     * `keepAlive: true` opts a stdio server out for state held in its process.
+     */
+    private idleEligible;
+    private idleState;
+    /** (Re)start the idle countdown for a server, unless a call is in flight. */
+    private armIdleTimer;
+    /**
+     * Stop an idle server's process, keeping its published tools. The entry is
+     * removed from `this.servers` synchronously, so a call landing during the
+     * close sees "not running" and respawns rather than using a closing client.
+     */
+    private stopIdleServer;
+    /**
+     * Make sure an idle-stopped server is running again before a call. Concurrent
+     * calls share one respawn. The fresh tool list is persisted to the catalog
+     * cache by `connectServer` but NOT republished: the model keeps the tools it
+     * already has, so a stop/restart cycle never churns the prompt.
+     */
+    private ensureRunning;
+    /** Is this server's connection currently live? Diagnostic/test use. */
+    isServerRunning(name: string): boolean;
     /**
      * Build a `Client` for one server, declaring elicitation support and wiring
      * the handler when the host can actually prompt the user.