openmausbot 0.1.69 → 0.1.71

package/dist-server/server/drivers/claude.js

@@ -16,9 +16,12 @@ import { join, dirname, isAbsolute, normalize } from "node:path";
 import { DATA_DIR, stripWorkspaceCredentialEnv } from "../config.js";
 import { augmentedPath } from "../env-path.js";
 import { brokerSocketPath, describeSpawnFailure, execCli, killCliTree, spawnCli } from "../procs.js";
+import { classifyResumeFailure, mayReplay, recoveryPromptFor } from "../resume-recovery.js";
 import { ClaudeLoginController } from "./claude-login-auth.js";
 import { computerProxyEnv } from "../container-computer.js";
+import { gateServer, resultBudget } from "../mcp-gate-config.js";
 import { newEventId, newId } from "../contracts.js";
+import { askInputSummary, commandSummary } from "../tool-summary.js";
 import { classifyError, computeBackoff, interruptibleDelay, RETRY_MAX_ATTEMPTS } from "./retry.js";
 import { applyClaudeInject, decodeInjectId, mergeLocalInject, probeLocalInjects, resolveInjectId, } from "./local-inject.js";
 import { appendNative } from "./native.js";
@@ -131,6 +134,133 @@ function claudeEnvironment(model, source = process.env, configDir, instanceEnvir
         delete env.ANTHROPIC_API_KEY;
     return env;
 }
+/** Escape hatch back to the pre-isolation launch, where a bot inherited this
+ * machine's Claude Code setup: its MCP servers and connectors, skills,
+ * agents, hooks and personal CLAUDE.md. Set it only to recover a bot that
+ * genuinely depended on a user- or local-scope MCP server; the supported way
+ * to give a bot a server is the app's own `mcpServers` config or the bot
+ * project's `.mcp.json`. */
+function inheritsUserConfig(env) {
+    return env.OMB_CLAUDE_INHERIT_USER_CONFIG === "1";
+}
+/** MCP servers the bot's own project declares in `<cwd>/.mcp.json`.
+ *
+ * The CLI would find this file itself, but the harness launches it with
+ * --strict-mcp-config, which makes the harness's config the only source.
+ * The project file IS part of the bot's definition (its cwd is chosen per
+ * bot), so it is forwarded verbatim — including `type: "http"`/`"sse"`
+ * entries the harness never mounts itself, because the CLI, not this code,
+ * is what has to understand them. A malformed file is ignored rather than
+ * failing the turn: an unreadable project config must not brick a bot. */
+function projectMcpServers(cwd) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(cwd, ".mcp.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+    const servers = parsed?.mcpServers;
+    if (!servers || typeof servers !== "object" || Array.isArray(servers))
+        return {};
+    const out = {};
+    for (const [name, server] of Object.entries(servers)) {
+        if (server && typeof server === "object" && !Array.isArray(server))
+            out[name] = server;
+    }
+    return out;
+}
+/** The CLI compacts its own session when it approaches a window. Left alone
+ * that window is the model's, so a Sonnet 5 session runs to something near a
+ * million tokens before anything happens — and every model call until then
+ * re-reads the whole thing. The measured food-ordering thread sat at 330k
+ * tokens per call and looked perfectly healthy to the CLI.
+ *
+ * So the harness picks the window instead. This delegates the actual
+ * compaction to the CLI, which owns the session and already has a summarizer
+ * for it; the harness only decides when it is worth paying for.
+ *
+ * OMB_CLAUDE_AUTOCOMPACT takes a token count, "auto" to hand the decision
+ * back to the CLI, or "off" to pass nothing at all. The CLI rejects a window
+ * outside 100k-1M as a hard argument error, so a configured value is clamped
+ * rather than passed through: a mistyped setting must not fail every turn. */
+export function autoCompactWindow(env) {
+    const raw = (env.OMB_CLAUDE_AUTOCOMPACT ?? "").trim().toLowerCase();
+    if (raw === "off")
+        return null;
+    if (raw === "auto")
+        return "auto";
+    const parsed = raw ? Number(raw) : DEFAULT_AUTOCOMPACT_TOKENS;
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return String(DEFAULT_AUTOCOMPACT_TOKENS);
+    return String(Math.min(1_000_000, Math.max(100_000, Math.floor(parsed))));
+}
+/** Generous for real work, and still a third of where a 1M-window session
+ * would otherwise get to. With bot tool results gated (mcp-gate.ts) most
+ * threads never reach it; this is the backstop for the ones that do. */
+const DEFAULT_AUTOCOMPACT_TOKENS = 200_000;
+/** The Claude CLI version that first accepted each flag the harness passes
+ * for context control. An unknown flag is a hard argument error, so passing
+ * one to an older CLI would fail every turn rather than degrade; each flag
+ * is therefore only passed to a CLI known to accept it.
+ *
+ * Verified against the published binaries, not the changelog (which never
+ * records `--autocompact`): `--strict-mcp-config` is present in 1.0.60 and
+ * absent from 1.0.0; `--setting-sources` first appears in 1.0.122 (1.0.120
+ * lacks it); `--autocompact` first appears in 2.1.122 (2.1.121 lacks it). */
+export const CLAUDE_FLAG_FLOORS = {
+    "--strict-mcp-config": [1, 0, 60],
+    "--setting-sources": [1, 0, 122],
+    "--autocompact": [2, 1, 122],
+};
+/** The newest floor above: a CLI at or past it accepts everything the
+ * harness sends. Below it the engine still works, minus the flags the CLI
+ * predates, and the Engines page suggests an update. */
+export const CLAUDE_CONTEXT_CONTROL_MIN_VERSION = CLAUDE_FLAG_FLOORS["--autocompact"];
+/** `claude --version` prints "2.1.232 (Claude Code)"; the first dotted triple
+ * is the version. Null when nothing parses, e.g. a wrapper that prints its
+ * own banner first — see claudeCliSupports for how that is treated. */
+export function parseClaudeCliVersion(stdout) {
+    const match = /(\d+)\.(\d+)\.(\d+)/.exec(stdout ?? "");
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function versionAtLeast(installed, floor) {
+    for (let i = 0; i < 3; i += 1) {
+        if (installed[i] !== floor[i])
+            return installed[i] > floor[i];
+    }
+    return true;
+}
+/** Whether a CLI reporting `version` accepts `flag`. A version that could
+ * not be parsed counts as current: every CLI that predates a floor prints a
+ * plain "x.y.z (Claude Code)", so an unreadable version is far more likely
+ * a newer wrapper than an old build, and withholding the flags from a modern
+ * CLI would silently re-open the context leak this file exists to close. */
+export function claudeCliSupports(version, flag) {
+    return version === null || versionAtLeast(version, CLAUDE_FLAG_FLOORS[flag]);
+}
+/** The Engines-page notice for a CLI older than the newest floor. The engine
+ * keeps working: turns run without the flags the CLI predates, which means
+ * no harness-picked compaction window and, on a very old CLI, no isolation
+ * from this machine's own Claude Code setup. */
+export function claudeCliUpdate(version, cli) {
+    const parsed = parseClaudeCliVersion(version);
+    if (!parsed || versionAtLeast(parsed, CLAUDE_CONTEXT_CONTROL_MIN_VERSION))
+        return undefined;
+    const floor = CLAUDE_CONTEXT_CONTROL_MIN_VERSION.join(".");
+    const missing = Object.keys(CLAUDE_FLAG_FLOORS)
+        .filter((flag) => !claudeCliSupports(parsed, flag));
+    return {
+        title: "Update Claude Code for context controls",
+        message: `Claude Code ${parsed.join(".")} predates ${floor}, so bots run without ${missing.join(", ")}: ` +
+            "no compaction window picked by OpenMausBot" +
+            (missing.includes("--setting-sources") ? ", and bots still see this machine's own Claude Code setup" : "") +
+            ". Update it, then refresh Engines.",
+        command: cli === "claude" ? "claude update" : `${cli} update`,
+    };
+}
 const DRIVER_KIND = "claudeAgent";
 // model catalog ported from upstream packages/contracts/src/model.ts
 export const STATIC_CLAUDE_MODELS = {
@@ -235,15 +365,7 @@ function systemEndedReply(kind) {
 }
 /** One human-readable line for an ask — what the card subtitle shows. */
 function askSummary(ask) {
-    const input = ask.input ?? {};
-    if (typeof input.question === "string")
-        return input.question.slice(0, 300);
-    if (typeof input.command === "string")
-        return input.command.slice(0, 200);
-    if (typeof input.url === "string")
-        return input.url.slice(0, 200);
-    const text = JSON.stringify(input);
-    return text === "{}" ? (ask.tool ?? "tool") : text.slice(0, 200);
+    return askInputSummary(ask.input) ?? ask.tool ?? "tool";
 }
 export function permissionSocketPath(threadId) {
     // A readable prefix alone is not unique: ids that agree on their first
@@ -435,7 +557,7 @@ export async function createPermissionBroker(opts) {
     if (!server)
         throw new Error("claude: permission broker could not bind a local socket");
     const drain = () => {
-        for (const p of [...pending.values()]) {
+        for (const p of Array.from(pending.values())) {
             const { behavior, message } = systemEndedReply(p.ask.kind);
             p.finish(behavior, message, "system");
         }
@@ -524,6 +646,17 @@ function firstText(content) {
 /** Claude's stream-json input accepts the same image source blocks as the
  * Anthropic Messages API. Keep the old string form for text-only turns so a
  * CLI update cannot disturb the overwhelmingly common path. */
+/** How a mid-session change to the volatile half of the system prompt
+ * reaches a model whose process was launched with the old copy. The CLI's
+ * own out-of-band convention inside a user turn, and it costs one short
+ * append rather than a relaunch that re-uploads the whole prompt cache. */
+function withVolatileNote(text, volatile) {
+    const body = volatile.trim()
+        ? `This part of your instructions changed since this session started. It replaces the earlier copy:\n\n${volatile.trim()}`
+        : "The notes that were in your instructions when this session started have been cleared.";
+    const note = `<system-reminder>\n${body}\n</system-reminder>`;
+    return text ? `${note}\n\n${text}` : note;
+}
 function claudeUserMessage(text, images) {
     if (!images?.length)
         return { type: "user", message: { role: "user", content: text } };
@@ -594,6 +727,15 @@ export const ClaudeDriver = {
             }
         };
         await refreshModels();
+        // The installed CLI's version as snapshot() last read it, so a flag the
+        // CLI does not know is never passed to it (CLAUDE_FLAG_FLOORS). The
+        // harness snapshots every instance whenever it describes them — app
+        // load, the Engines page, and right after `claude update`, which is
+        // exactly when the answer changes — so a turn normally finds it filled.
+        // A turn before any snapshot assumes a current CLI rather than paying a
+        // CLI start-up of its own: the flags are the default, the exception is
+        // the older install, and the next snapshot corrects it.
+        let cliVersion = null;
         const listeners = new Set();
         // one active turn per thread; a second send while busy is a caller bug
         const active = new Map();
@@ -659,7 +801,7 @@ export const ClaudeDriver = {
             });
         };
         const emit = (event) => {
-            for (const l of [...listeners])
+            for (const l of Array.from(listeners))
                 l(event);
         };
         const base = (threadId, turnId) => ({
@@ -718,6 +860,26 @@ export const ClaudeDriver = {
                 args.push("--disallowedTools", config.disallowedTools.join(","));
             }
             const turnEnvironment = environment();
+            const isolated = !inheritsUserConfig(turnEnvironment);
+            if (isolated) {
+                // A bot gets the tools and instructions its owner gave it, not
+                // whatever this machine's Claude Code happens to be set up with.
+                // Without these the CLI silently adds, to EVERY turn of every bot:
+                // the desktop's own MCP servers and claude.ai connectors (one
+                // measured desktop mounted 407 extra tools, ~10k tokens), its skill
+                // and agent listings, its hooks, and its personal CLAUDE.md. Every
+                // model call in the session then re-reads all of it.
+                // Each flag only on a CLI that accepts it: an unknown flag is an
+                // argument error that would fail every turn (CLAUDE_FLAG_FLOORS).
+                if (claudeCliSupports(cliVersion, "--strict-mcp-config"))
+                    args.push("--strict-mcp-config");
+                if (claudeCliSupports(cliVersion, "--setting-sources"))
+                    args.push("--setting-sources", "project");
+            }
+            const compactWindow = autoCompactWindow(turnEnvironment);
+            if (compactWindow && claudeCliSupports(cliVersion, "--autocompact")) {
+                args.push("--autocompact", compactWindow);
+            }
             const turnModel = await resolveClaudeTurnModel(turn.model, turnEnvironment);
             const injected = applyClaudeInject({ ...turnEnvironment }, turnModel);
             if (injected.model)
@@ -794,10 +956,39 @@ export const ClaudeDriver = {
             // routes every custom tool call through the ogb permission broker
             // into an Allow/Deny card. Reserved names were filtered upstream;
             // skip any residual collision instead of clobbering a built-in.
+            // Bot-owned servers, gated below: they are the ones that answer for a
+            // machine rather than for a context window.
+            const botOwned = new Set();
             for (const [name, server] of Object.entries(turn.integrations?.custom ?? {})) {
                 if (name in mcpServers)
                     continue;
                 mcpServers[name] = { ...server };
+                botOwned.add(name);
+            }
+            // --strict-mcp-config (above) makes this config the CLI's only source
+            // of MCP servers, so a server the bot's OWN project declares would
+            // otherwise vanish with the machine's. Merge it last: a project file
+            // can add servers but never shadow a harness-owned mount.
+            if (isolated && turn.cwd) {
+                for (const [name, server] of Object.entries(projectMcpServers(turn.cwd))) {
+                    if (name in mcpServers)
+                        continue;
+                    mcpServers[name] = server;
+                    botOwned.add(name);
+                }
+            }
+            // One tool call can put more into the conversation than the whole rest
+            // of the session: a single product search measured 60-140 KB of JSON,
+            // and the CLI re-reads it on every later model call. The harness never
+            // sees these calls — the CLI runs the server itself — so the only place
+            // to stand is between the two processes. Harness-owned mounts (the
+            // permission broker, computer, browser, agents, dweb) are already
+            // bounded and are deliberately left alone.
+            const budget = resultBudget(turnEnvironment);
+            for (const name of botOwned) {
+                const gated = gateServer({ name, server: mcpServers[name], threadId, budget, nodeEnv: NODE_ENV_FLAG });
+                if (gated)
+                    mcpServers[name] = gated;
             }
             // Keep ask_user available even in Full access. Native bypass skips
             // permission prompts, not questions requiring a person's answer.
@@ -832,7 +1023,9 @@ export const ClaudeDriver = {
             const keyArgs = args.filter((a, i) => !privateFileFlags.has(a) && !privateFileFlags.has(args[i - 1] ?? ""));
             const argsKey = JSON.stringify({
                 args: keyArgs,
-                system: turn.system ?? null,
+                // the volatile half is deliberately absent: it must not respawn a
+                // healthy session (see Session.volatile)
+                system: turn.systemStable ?? turn.system ?? null,
                 mcpServers,
                 cwd,
                 model: injected.model ?? null,
@@ -852,7 +1045,12 @@ export const ClaudeDriver = {
                         killCliTree(live.child);
                     }, turnId, broker: live.broker });
                 emit({ ...base(threadId, turnId), type: "turn.started" });
-                const written = await writeUser(live, threadId, promptMsg);
+                const volatile = turn.systemVolatile ?? "";
+                const message = volatile === live.volatile
+                    ? promptMsg
+                    : claudeUserMessage(withVolatileNote(turn.text, volatile), turn.images);
+                live.volatile = volatile;
+                const written = await writeUser(live, threadId, message);
                 if (!written) {
                     active.delete(threadId);
                     live.turn = null;
@@ -982,7 +1180,9 @@ export const ClaudeDriver = {
                 mcpConfigPath,
                 systemPromptPath,
                 argsKey,
+                volatile: turn.systemVolatile ?? "",
                 sessionId: sessionId ?? newSessionId,
+                sawInit: false,
                 turn: { turnId, settled: false, sawStreamDelta: false },
                 idleTimer: null,
                 closing: false,
@@ -1035,6 +1235,7 @@ export const ClaudeDriver = {
                 switch (o.type) {
                     case "system":
                         if (o.subtype === "init") {
+                            session.sawInit = true;
                             if (typeof o.session_id === "string")
                                 session.sessionId = o.session_id;
                             emit({ ...base(threadId, currentTurnId()), type: "session.started", sessionId: o.session_id, model: o.model });
@@ -1087,7 +1288,14 @@ export const ClaudeDriver = {
                         }
                         for (const b of Array.isArray(msg.content) ? msg.content : []) {
                             if (b.type === "tool_use") {
-                                emit({ ...base(threadId, currentTurnId()), type: "item.started", itemType: "tool", itemId: b.id, title: b.name });
+                                emit({
+                                    ...base(threadId, currentTurnId()),
+                                    type: "item.started",
+                                    itemType: "tool",
+                                    itemId: b.id,
+                                    title: b.name,
+                                    summary: commandSummary(b.input),
+                                });
                             }
                         }
                         if (msg.usage) {
@@ -1240,6 +1448,67 @@ export const ClaudeDriver = {
                         })();
                         return;
                     }
+                    // A --resume that the CLI never acknowledged: it exited without
+                    // an `init` frame, so it never read the prompt and this turn has
+                    // caused nothing. Without this the thread is BRICKED — the dead
+                    // cursor is never cleared, so every later turn resumes the same
+                    // missing session and fails identically, and the user has no way
+                    // back except switching engines. One fresh session, carrying the
+                    // harness's rebuild of the conversation. Exactly one: the relaunch
+                    // offers no cursor, so `attempted` is false there and a second
+                    // failure is reported like any other.
+                    const resumeFailure = classifyResumeFailure({
+                        attempted: Boolean(sessionId),
+                        rejected: !session.sawInit,
+                        promptSubmitted: session.sawInit,
+                        producedOutput: session.turn.sawStreamDelta,
+                    });
+                    if (mayReplay(resumeFailure) && !retry.cancelled) {
+                        const recovery = recoveryPromptFor({
+                            recoveryText: turn.recoveryText,
+                            currentText: turn.text,
+                            failure: resumeFailure,
+                        });
+                        session.broker?.close();
+                        session.broker = undefined;
+                        if (session.mcpConfigPath) {
+                            try {
+                                rmSync(dirname(session.mcpConfigPath), { recursive: true, force: true });
+                            }
+                            catch { }
+                            session.mcpConfigPath = null;
+                        }
+                        if (session.systemPromptPath) {
+                            removePrivateTempDir(session.systemPromptPath);
+                            session.systemPromptPath = null;
+                        }
+                        sessions.delete(threadId);
+                        session.turn = null;
+                        active.delete(threadId);
+                        emit({
+                            ...base(threadId, turnId),
+                            type: "turn.retrying",
+                            attempt: retry.attempt + 1,
+                            delayMs: 0,
+                            reason: "resume_rejected",
+                        });
+                        void (async () => {
+                            try {
+                                // no cursor: a fresh session, carrying the rebuild
+                                await sendTurn({ ...turn, resumeCursor: undefined, recoveryText: undefined, text: recovery.text });
+                            }
+                            catch (e) {
+                                retryState.delete(threadId);
+                                emit({
+                                    ...base(threadId, turnId),
+                                    type: "runtime.error",
+                                    message: e instanceof Error ? e.message : String(e),
+                                });
+                                emit({ ...base(threadId, turnId), type: "turn.completed", ok: false, stopReason: "exit_before_result", cost: null });
+                            }
+                        })();
+                        return;
+                    }
                     retryState.delete(threadId);
                     emit({
                         ...base(threadId, currentTurnId()),
@@ -1298,11 +1567,13 @@ export const ClaudeDriver = {
             });
             if (!version)
                 return { state: "unavailable", reason: `\`${config.cli}\` CLI not found` };
+            cliVersion = parseClaudeCliVersion(version);
             const auth = await claudeAuthStatus(config.cli, env);
             // claudeEnvironment strips ANTHROPIC_API_KEY, so turns run on the
             // CLI's own login (Pro/Max): the cost it reports is what the call
             // WOULD bill, not a charge
-            return { state: "available", version, ...auth, billing: "subscription" };
+            const update = claudeCliUpdate(version, config.cli);
+            return { state: "available", version, ...auth, ...(update ? { update } : {}), billing: "subscription" };
         };
         /** One-shot Claude call with the prompt on stdin, never argv. Approval
          * summaries can contain paths, commands, or secrets, so the generic
@@ -1376,6 +1647,7 @@ export const ClaudeDriver = {
             getAuthentication: (flowId) => login.get(flowId),
             completeAuthentication: (flowId, code) => login.complete(flowId, code),
             cancelAuthentication: () => login.cancel(),
+            signOut: () => login.signOut(),
             adapter: {
                 provider: DRIVER_KIND,
                 capabilities: {
@@ -1412,7 +1684,7 @@ export const ClaudeDriver = {
                 stopAll: async () => {
                     for (const { stop } of active.values())
                         stop();
-                    for (const threadId of [...sessions.keys()])
+                    for (const threadId of Array.from(sessions.keys()))
                         closeSession(threadId, "stopAll");
                 },
                 onEvent: (listener) => {
@@ -1423,11 +1695,16 @@ export const ClaudeDriver = {
             generateText: (prompt) => generateReview(prompt),
             reviewPermission: generateReview,
             dispose: async () => {
-                for (const { stop } of active.values())
-                    stop();
-                for (const threadId of [...sessions.keys()])
-                    closeSession(threadId, "dispose");
-                listeners.clear();
+                try {
+                    await login.dispose();
+                }
+                finally {
+                    for (const { stop } of active.values())
+                        stop();
+                    for (const threadId of Array.from(sessions.keys()))
+                        closeSession(threadId, "dispose");
+                    listeners.clear();
+                }
             },
         };
     },

package/dist-server/server/drivers/codex.js

@@ -22,6 +22,7 @@ import { codexLocalProviderArgs } from "./local-inject.js";
 import { augmentedPath, splitCliString } from "../env-path.js";
 import { classifyError, computeBackoff, RETRY_MAX_ATTEMPTS } from "./retry.js";
 import { appendNative } from "./native.js";
+import { commandSummary } from "../tool-summary.js";
 import { codexDeveloperInstructions, syncCodexInstructions } from "./codex-instructions.js";
 import { CodexDeviceAuthController } from "./codex-device-auth.js";
 import { codexAccountEmail } from "./codex-identity.js";
@@ -434,7 +435,7 @@ export const CodexDriver = {
         const listeners = new Set();
         const active = new Map();
         const emit = (event) => {
-            for (const l of [...listeners])
+            for (const l of Array.from(listeners))
                 l(event);
         };
         const base = (threadId, turnId) => ({
@@ -571,7 +572,7 @@ export const CodexDriver = {
                     if (state.settled)
                         return;
                     state.settled = true;
-                    for (const finish of [...asks.values()])
+                    for (const finish of Array.from(asks.values()))
                         finish("deny", "OpenMausBot: the turn ended", "system");
                     for (const p of rpcPending.values())
                         p.reject(new Error("turn settled"));
@@ -738,8 +739,16 @@ export const CodexDriver = {
                                         : item.type === "webSearch"
                                             ? "web_search"
                                             : null;
-                            if (title)
-                                emit({ ...base(threadId, turnId), type: "item.started", itemType: "tool", itemId: item.id, title });
+                            if (title) {
+                                emit({
+                                    ...base(threadId, turnId),
+                                    type: "item.started",
+                                    itemType: "tool",
+                                    itemId: item.id,
+                                    title,
+                                    summary: item.type === "commandExecution" ? commandSummary({ command: item.command }) : undefined,
+                                });
+                            }
                             break;
                         }
                         case "item/completed": {

package/dist-server/server/drivers/pi.js

@@ -389,7 +389,7 @@ export const PiDriver = {
         // one active turn per thread
         const active = new Map();
         const emit = (event) => {
-            for (const l of [...listeners])
+            for (const l of Array.from(listeners))
                 l(event);
         };
         const base = (threadId, turnId) => ({

package/dist-server/server/engine-install.js

@@ -0,0 +1,137 @@
+// Install an engine's command-line app from Settings, on the machine that
+// runs this server, as this process's own user, into a directory the app
+// owns. No sudo, no shell, no terminal: the package name comes from the
+// driver's own install descriptor and never from a request, npm runs with
+// a fixed argument list, and the binary is found on the engines' PATH
+// afterwards because that directory is registered ahead of everything else.
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { DATA_DIR, stripWorkspaceCredentialEnv } from "./config.js";
+import { augmentedPath, findCliCandidates, registerPathDir, resetPathCache } from "./env-path.js";
+import { killCliTree, spawnCli } from "./procs.js";
+const MAX_OUTPUT = 64 * 1024;
+const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+/** npm's global prefix for engines the app installs itself. */
+export function enginesPrefix(baseDir = DATA_DIR) {
+    return join(baseDir, "tools", "npm");
+}
+/** Where that prefix puts executables: `bin/` on POSIX, the prefix itself on Windows. */
+export function enginesBinDir(baseDir = DATA_DIR, platform = process.platform) {
+    return platform === "win32" ? enginesPrefix(baseDir) : join(enginesPrefix(baseDir), "bin");
+}
+/** Called once at boot: engines installed here win over any other copy on PATH. */
+export function registerEnginesBinDir(baseDir = DATA_DIR) {
+    registerPathDir(enginesBinDir(baseDir));
+}
+/** The npm package a driver's own install one-liner names, when it is one. */
+export function npmPackageOf(install) {
+    const line = install?.command?.linux ?? install?.command?.darwin ?? install?.command?.win32;
+    const match = line ? /^npm install -g ((?:@[\w.-]+\/)?[\w.-]+)$/.exec(line.trim()) : null;
+    return match ? match[1] : null;
+}
+export function npmAvailable() {
+    return findCliCandidates("npm").length > 0;
+}
+/** What Settings may install for this engine on this machine, or null. A
+ * managed engine keeps its own verified download; anything else needs a
+ * plain npm package and npm on PATH. */
+export function serverInstallFor(install, npmPresent = npmAvailable()) {
+    if (!install || install.managed)
+        return null;
+    const pkg = npmPackageOf(install);
+    return pkg && npmPresent ? { package: pkg } : null;
+}
+const running = new Map();
+/** Install or update one npm engine. Concurrent clicks share one npm run. */
+export function installNpmEngine(pkg, options = {}) {
+    const key = `${options.baseDir ?? DATA_DIR} ${pkg}`;
+    const existing = running.get(key);
+    if (existing)
+        return existing;
+    const run = installOnce(pkg, options).finally(() => running.delete(key));
+    running.set(key, run);
+    return run;
+}
+async function installOnce(pkg, options) {
+    const prefix = enginesPrefix(options.baseDir);
+    mkdirSync(prefix, { recursive: true });
+    const env = {
+        ...(options.env ?? process.env),
+        PATH: options.path ?? augmentedPath(),
+        NO_COLOR: "1",
+        npm_config_update_notifier: "false",
+        npm_config_fund: "false",
+        npm_config_audit: "false",
+    };
+    // Workspace credentials (xai/box/voice keys) are not npm's to see.
+    stripWorkspaceCredentialEnv(env);
+    // npm 11 skips a dependency's install script unless the package is named
+    // here; the engines that need one (Claude Code) are exactly these.
+    const args = ["install", "-g", "--prefix", prefix, "--loglevel=error", `--allow-scripts=${pkg}`, `${pkg}@latest`];
+    const result = await runNpm(args, env, prefix, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    if (result.code !== 0) {
+        throw new Error(`npm could not install ${pkg} on this server.${tail(result.output)}`);
+    }
+    // Whatever the boot registration did, the directory we just filled must
+    // be on the engines' PATH from here on.
+    registerPathDir(enginesBinDir(options.baseDir));
+    resetPathCache();
+    if (options.cli) {
+        const binDir = enginesBinDir(options.baseDir);
+        if (!findCliCandidates(options.cli).some((path) => path.startsWith(binDir))) {
+            throw new Error(`${pkg} installed, but it did not provide a \`${options.cli}\` command. Check the package name in this engine's install descriptor.`);
+        }
+    }
+}
+function tail(output) {
+    const clean = stripVTControlCharacters(output).trim();
+    if (!clean)
+        return "";
+    const lines = clean.split(/\r?\n/).filter((line) => line.trim()).slice(-6);
+    return `\n${lines.join("\n").slice(-600)}`;
+}
+function runNpm(args, env, cwd, timeoutMs) {
+    return new Promise((resolveRun, rejectRun) => {
+        let child;
+        try {
+            child = spawnCli("npm", args, { env, cwd, stdio: ["pipe", "pipe", "pipe"] });
+        }
+        catch {
+            rejectRun(new Error("npm could not start on this server. Install Node.js with npm for the user running OpenMausBot, then try again."));
+            return;
+        }
+        child.stdin.end();
+        let output = "";
+        const receive = (chunk) => {
+            if (output.length < MAX_OUTPUT)
+                output += chunk.toString("utf8").slice(0, MAX_OUTPUT - output.length);
+        };
+        child.stdout.on("data", receive);
+        child.stderr.on("data", receive);
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            void killCliTree(child);
+        }, timeoutMs);
+        timer.unref();
+        child.once("error", (error) => {
+            clearTimeout(timer);
+            rejectRun(new Error(error.code === "ENOENT"
+                ? "npm is not installed on this server. Install Node.js with npm for the user running OpenMausBot, then try again."
+                : "npm could not start on this server. Check that Node.js is installed for the user running OpenMausBot."));
+        });
+        child.once("close", (code) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                rejectRun(new Error("The install took too long and was stopped. Check the server's network connection and try again."));
+                return;
+            }
+            resolveRun({ code, output });
+        });
+    });
+}
+/** True once something has been installed here, for status pages. */
+export function enginesInstalled(baseDir = DATA_DIR) {
+    return existsSync(enginesBinDir(baseDir));
+}