openmausbot 0.1.55

package/dist-server/server/mcp-bridge.js

@@ -0,0 +1,251 @@
+// The one transparent stdio bridge behind both MCP entry points
+// (container-mcp.ts for the Local VM, vps-container-mcp.ts for the BYO VPS).
+// It defines no tools and parses no MCP messages: bytes in, bytes out.
+//
+// The single exception to that transparency is the who-is-driving gate
+// (opt-in via `gate`). While the person holds control of this computer in
+// the app, a `tools/call` from the agent is answered with a refusal HERE,
+// on the near side, and never forwarded — Cua Driver on the far side has
+// no concept of a person holding the wheel, so the refusal cannot come
+// from anywhere else. Everything that is not a tools/call still passes
+// through untouched, and with no gate configured the bridge remains the
+// byte-for-byte pipe described above.
+//
+// Two behaviors live here so neither entry point can drift:
+//   1. Exit without truncation. `process.exit()` in a close/error handler
+//      discards whatever is still buffered on stdout — a final MCP result
+//      would be cut mid-frame. The bridge sets exitCode and unpipes instead,
+//      letting stdio drain before the process ends on its own.
+//   2. A dead-transport watchdog (opt-in via `liveness`). docker's ssh
+//      connection helper accepts no ConnectTimeout/ServerAlive options, so a
+//      VPS dropping mid-turn leaves the exec silently wedged until the OS
+//      gives up — the harness sees a hung tool call, not an error.
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import { CONTROL_REFUSAL_PLAIN, createControlClient } from "./control-client.js";
+import { augmentedPath } from "./env-path.js";
+// 45s of TOTAL silence before the bridge even probes. An MCP session is
+// legitimately quiet between tool calls and a slow screenshot can take tens
+// of seconds, so silence alone never kills anything — it only triggers a
+// liveness probe, and only a probe that FAILS ends the bridge. Any byte on
+// stdin/stdout/stderr resets the window.
+export const BRIDGE_INACTIVITY_MS = 45_000;
+const PROBE_TIMEOUT_MS = 10_000;
+/** Run the liveness command; alive means "exited 0 within the timeout". The
+ * probe is its own short-lived process, so it cannot inherit the wedged
+ * connection it is diagnosing. */
+export function runLivenessProbe(probe, timeoutMs = PROBE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const child = spawn(probe.command, probe.args, {
+            shell: false,
+            env: { ...process.env, PATH: augmentedPath() },
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            resolve(false);
+        }, timeoutMs);
+        timer.unref?.();
+        child.on("error", () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve(code === 0);
+        });
+    });
+}
+/** Inactivity → probe → (only then) declare dead. Traffic arriving while a
+ * probe is in flight vetoes even a failed probe: bytes are better evidence
+ * of life than a health command racing a congested link. */
+export function createInactivityWatchdog(options) {
+    let timer = null;
+    let stopped = false;
+    let probing = false;
+    let touchedWhileProbing = false;
+    const arm = () => {
+        if (stopped)
+            return;
+        timer = setTimeout(fire, options.inactivityMs);
+        timer.unref?.();
+    };
+    const settleProbe = (alive) => {
+        probing = false;
+        if (stopped)
+            return;
+        if (alive || touchedWhileProbing) {
+            arm();
+            return;
+        }
+        options.onDead();
+    };
+    const fire = () => {
+        probing = true;
+        touchedWhileProbing = false;
+        void options.probe().then(settleProbe, () => settleProbe(false));
+    };
+    arm();
+    return {
+        touch() {
+            if (stopped)
+                return;
+            if (probing) {
+                touchedWhileProbing = true;
+                return;
+            }
+            if (timer)
+                clearTimeout(timer);
+            arm();
+        },
+        stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+        },
+    };
+}
+/** Collect a byte stream into complete newline-terminated lines. MCP's
+ * stdio transport is one JSON-RPC frame per line, so line boundaries are
+ * the only safe place to inspect — or inject — anything. */
+export function createLineSplitter(onLine) {
+    let pending = "";
+    const decoder = new StringDecoder("utf8");
+    return {
+        push(chunk) {
+            pending += typeof chunk === "string" ? chunk : decoder.write(chunk);
+            let newline;
+            while ((newline = pending.indexOf("\n")) !== -1) {
+                const line = pending.slice(0, newline);
+                pending = pending.slice(newline + 1);
+                onLine(line);
+            }
+        },
+        flush() {
+            pending += decoder.end();
+            if (pending)
+                onLine(pending);
+            pending = "";
+        },
+    };
+}
+/** The gate itself, factored free of process wiring so a test can drive it
+ * with plain strings. Frames are handled on a serialized queue: the
+ * held-check is async, and answering frame N+1 before frame N would
+ * reorder the agent's protocol stream. Only a `tools/call` is ever
+ * refused; every other frame — handshakes, tools/list, notifications,
+ * lines that are not JSON — passes through untouched. */
+export function createGateInterceptor(options) {
+    const refusalText = options.refusalText ?? CONTROL_REFUSAL_PLAIN;
+    let queue = Promise.resolve();
+    return (line) => {
+        queue = queue.then(async () => {
+            let frame = null;
+            try {
+                frame = JSON.parse(line);
+            }
+            catch {
+                // not a frame this gate understands — never stand between the
+                // agent and its driver on anything but a recognized tool call
+            }
+            if (!frame || frame.method !== "tools/call") {
+                options.forward(line);
+                return;
+            }
+            const held = await options.isHeld().catch(() => false);
+            if (!held) {
+                options.forward(line);
+                return;
+            }
+            options.refuse(JSON.stringify({
+                jsonrpc: "2.0",
+                id: frame.id ?? null,
+                result: { content: [{ type: "text", text: refusalText }], isError: true },
+            }));
+        });
+    };
+}
+export function runMcpBridge(options) {
+    const child = spawn(options.command, options.args, {
+        shell: false,
+        env: { ...process.env, PATH: augmentedPath() },
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    // docker may exit before it drains stdin; pipe() leaves this error unhandled.
+    child.stdin.on("error", () => { });
+    child.stderr.pipe(process.stderr);
+    let detach;
+    if (options.gate) {
+        const client = createControlClient({ url: options.gate.url, token: options.gate.token });
+        const inbound = createLineSplitter(createGateInterceptor({
+            isHeld: async () => (await client.state(true)).held,
+            forward: (line) => child.stdin.write(line + "\n"),
+            refuse: (line) => process.stdout.write(line + "\n"),
+        }));
+        const onStdin = (chunk) => inbound.push(chunk);
+        process.stdin.on("data", onStdin);
+        process.stdin.on("end", () => {
+            inbound.flush();
+            child.stdin.end();
+        });
+        // Injected refusals must never land inside one of the child's
+        // half-written frames, so the child's stdout is re-emitted at line
+        // granularity as well.
+        const outbound = createLineSplitter((line) => process.stdout.write(line + "\n"));
+        child.stdout.on("data", (chunk) => outbound.push(chunk));
+        child.stdout.on("end", () => outbound.flush());
+        detach = () => {
+            process.stdin.off("data", onStdin);
+            process.stdin.pause();
+        };
+    }
+    else {
+        process.stdin.pipe(child.stdin);
+        child.stdout.pipe(process.stdout);
+        detach = () => {
+            process.stdin.unpipe(child.stdin);
+            process.stdin.pause();
+        };
+    }
+    let watchdog = null;
+    if (options.liveness) {
+        const liveness = options.liveness;
+        watchdog = createInactivityWatchdog({
+            inactivityMs: BRIDGE_INACTIVITY_MS,
+            probe: () => runLivenessProbe(liveness),
+            onDead: () => {
+                process.stderr.write(`${options.label} transport went silent and stopped answering liveness probes; ending the bridge\n`);
+                process.exitCode = 1;
+                detach();
+                child.kill("SIGKILL");
+                // A docker wedged on a dead ssh connection may never deliver close.
+                // Nothing can be buffered on stdout after 45 quiet seconds, so this
+                // hard exit — unlike the close-handler one this file exists to avoid —
+                // cannot truncate anything.
+                const failsafe = setTimeout(() => process.exit(1), 2_000);
+                failsafe.unref?.();
+            },
+        });
+        const touch = () => watchdog?.touch();
+        process.stdin.on("data", touch);
+        child.stdout.on("data", touch);
+        child.stderr.on("data", touch);
+    }
+    child.on("error", (error) => {
+        process.stderr.write(`could not connect to ${options.label}: ${error.message}\n`);
+        process.exitCode = 1;
+        watchdog?.stop();
+        detach();
+    });
+    child.on("close", (code, signal) => {
+        if (signal)
+            process.stderr.write(`${options.label} connection ended with ${signal}\n`);
+        // Let stdout and stderr drain before the bridge exits.
+        process.exitCode = process.exitCode ?? code ?? 1;
+        watchdog?.stop();
+        detach();
+    });
+    for (const signal of ["SIGTERM", "SIGINT"]) {
+        process.on(signal, () => child.kill(signal));
+    }
+}

package/dist-server/server/mcp-probe.js

@@ -0,0 +1,153 @@
+import { augmentedPath } from "./env-path.js";
+import { PROVIDER_CREDENTIAL_ENV, stripWorkspaceCredentialEnv, } from "./config.js";
+import { createLineSplitter } from "./mcp-bridge.js";
+import { killCliTree, spawnCli } from "./procs.js";
+const MAX_STDOUT_BYTES = 1_048_576;
+const MAX_TOOLS = 100;
+const DEFAULT_TIMEOUT_MS = 8_000;
+function probeEnvironment(server) {
+    const env = { ...process.env, PATH: augmentedPath() };
+    stripWorkspaceCredentialEnv(env);
+    for (const key of PROVIDER_CREDENTIAL_ENV)
+        delete env[key];
+    Object.assign(env, server.env);
+    return env;
+}
+function publicProbeError(kind) {
+    if (kind === "spawn")
+        return "Could not start this command. Check that it is installed and executable.";
+    if (kind === "timeout")
+        return "The server did not answer in time.";
+    if (kind === "closed")
+        return "The server stopped before the MCP handshake finished.";
+    if (kind === "cancelled")
+        return "Connection test was cancelled.";
+    return "The command did not return a valid MCP tools list.";
+}
+function redactConfiguredValues(value, env) {
+    let redacted = value;
+    for (const secret of Object.values(env)) {
+        if (secret)
+            redacted = redacted.split(secret).join("[redacted]");
+    }
+    return redacted;
+}
+/** Start one stdio server long enough to prove the MCP handshake and list its
+ * tools. It is always reaped, never inherits OpenMaus credentials, and never
+ * returns child stderr or environment values to the renderer. */
+export function probeMcpServer(server, timeoutMs = DEFAULT_TIMEOUT_MS, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve({ ok: false, error: publicProbeError("cancelled") });
+            return;
+        }
+        let child;
+        try {
+            child = spawnCli(server.command, server.args, {
+                cwd: process.cwd(),
+                env: probeEnvironment(server),
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch {
+            resolve({ ok: false, error: publicProbeError("spawn") });
+            return;
+        }
+        let settled = false;
+        let stdoutBytes = 0;
+        let initialized = false;
+        let timer;
+        const onAbort = () => finish({ ok: false, error: publicProbeError("cancelled") });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            killCliTree(child);
+            resolve(result);
+        };
+        const write = (frame) => {
+            try {
+                child.stdin.write(`${JSON.stringify(frame)}\n`);
+            }
+            catch {
+                finish({ ok: false, error: publicProbeError("closed") });
+            }
+        };
+        const splitter = createLineSplitter((line) => {
+            if (settled || !line.trim())
+                return;
+            let frame;
+            try {
+                frame = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (!frame || typeof frame !== "object")
+                return;
+            const value = frame;
+            if (value.id === 1 && value.result && !initialized) {
+                initialized = true;
+                write({ jsonrpc: "2.0", method: "notifications/initialized" });
+                write({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
+                return;
+            }
+            if (value.id !== 2)
+                return;
+            const result = value.result;
+            if (!Array.isArray(result?.tools)) {
+                finish({ ok: false, error: publicProbeError("protocol") });
+                return;
+            }
+            const tools = [];
+            for (const raw of result.tools.slice(0, MAX_TOOLS)) {
+                if (!raw || typeof raw !== "object")
+                    continue;
+                const candidate = raw;
+                if (typeof candidate.name !== "string" || !candidate.name.trim())
+                    continue;
+                tools.push({
+                    name: redactConfiguredValues(candidate.name, server.env).slice(0, 200),
+                    ...(typeof candidate.description === "string"
+                        ? { description: redactConfiguredValues(candidate.description, server.env).slice(0, 500) }
+                        : {}),
+                });
+            }
+            finish({ ok: true, tools });
+        });
+        timer = setTimeout(() => {
+            finish({ ok: false, error: publicProbeError("timeout") });
+        }, timeoutMs);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        child.stdout.on("data", (chunk) => {
+            stdoutBytes += chunk.byteLength;
+            if (stdoutBytes > MAX_STDOUT_BYTES) {
+                finish({ ok: false, error: publicProbeError("protocol") });
+                return;
+            }
+            splitter.push(chunk);
+        });
+        // Drain without retaining it. Child stderr often contains secrets or
+        // arbitrary native logs and is not part of the MCP protocol.
+        child.stderr.resume();
+        child.once("error", () => finish({ ok: false, error: publicProbeError("spawn") }));
+        child.once("close", () => finish({ ok: false, error: publicProbeError("closed") }));
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        write({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2025-06-18",
+                capabilities: {},
+                clientInfo: { name: "OpenMausBot", version: "probe" },
+            },
+        });
+    });
+}

package/dist-server/server/mcp-registry.js

@@ -0,0 +1,130 @@
+import { z } from "zod";
+export const MAX_MCP_SERVERS = 20;
+const MAX_ARGS = 64;
+const MAX_ENV = 64;
+const MCP_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Names used to route OpenMausBot's built-in MCP proxies and their ephemeral
+ * capabilities. Codex exposes MCP env names through one app-server process;
+ * a custom server must never request one of these names or it could redirect
+ * a built-in proxy or receive that proxy's bearer. */
+export function isHarnessOwnedMcpEnvName(name) {
+    return name === "ELECTRON_RUN_AS_NODE" || name.startsWith("OMB_") || name.startsWith("OGB_");
+}
+function environmentNameError(name) {
+    if (!ENV_NAME.test(name))
+        return `Environment variable “${name}” is not valid.`;
+    if (isHarnessOwnedMcpEnvName(name)) {
+        return `Environment variable “${name}” is reserved by OpenMausBot.`;
+    }
+    return null;
+}
+const RESERVED_MCP_NAMES = new Set([
+    "ogb",
+    "computer",
+    "agents",
+    "composio",
+    "browser",
+    "phone",
+    "dweb",
+    "openmausbot_connectors",
+    "openmausbot_phone",
+]);
+const storedEntrySchema = z.object({
+    command: z.string().trim().min(1).max(1_024),
+    args: z.array(z.string().max(4_096)).max(MAX_ARGS).optional(),
+    env: z.record(z.string(), z.string().max(16_384)).optional(),
+    enabled: z.boolean().optional(),
+}).strict();
+const mutationEntrySchema = storedEntrySchema.extend({
+    env: z.record(z.string(), z.union([z.string().max(16_384), z.literal(true)])).optional(),
+});
+export function mcpServerNameError(name) {
+    if (!MCP_NAME.test(name)) {
+        return "Use 1–32 lowercase letters, numbers, underscores, or hyphens, starting with a letter.";
+    }
+    if (RESERVED_MCP_NAMES.has(name))
+        return "That name is reserved by OpenMausBot.";
+    return null;
+}
+export function parseStoredMcpServer(name, raw) {
+    const nameError = mcpServerNameError(name);
+    if (nameError)
+        return { ok: false, error: nameError };
+    const parsed = storedEntrySchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, error: parsed.error.issues[0]?.message ?? "Invalid MCP server." };
+    }
+    const env = parsed.data.env ?? {};
+    const invalidEnv = Object.keys(env).map(environmentNameError).find((error) => error !== null);
+    if (invalidEnv)
+        return { ok: false, error: invalidEnv };
+    if (Object.keys(env).length > MAX_ENV) {
+        return { ok: false, error: `Use at most ${MAX_ENV} environment variables.` };
+    }
+    return {
+        ok: true,
+        server: {
+            command: parsed.data.command,
+            args: parsed.data.args ?? [],
+            env,
+            enabled: parsed.data.enabled !== false,
+        },
+    };
+}
+/** Parse a renderer mutation. `true` is a write-only placeholder meaning
+ * “keep this already stored value”; it is never accepted for a new key. */
+export function parseMcpServerMutation(name, raw, existing) {
+    const nameError = mcpServerNameError(name);
+    if (nameError)
+        return { ok: false, error: nameError };
+    const parsed = mutationEntrySchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, error: parsed.error.issues[0]?.message ?? "Invalid MCP server." };
+    }
+    const incomingEnv = parsed.data.env ?? {};
+    const invalidEnv = Object.keys(incomingEnv).map(environmentNameError).find((error) => error !== null);
+    if (invalidEnv)
+        return { ok: false, error: invalidEnv };
+    if (Object.keys(incomingEnv).length > MAX_ENV) {
+        return { ok: false, error: `Use at most ${MAX_ENV} environment variables.` };
+    }
+    const env = {};
+    for (const [key, value] of Object.entries(incomingEnv)) {
+        if (value === true) {
+            const saved = existing?.env[key];
+            if (saved === undefined)
+                return { ok: false, error: `No saved value exists for ${key}.` };
+            env[key] = saved;
+        }
+        else {
+            env[key] = value;
+        }
+    }
+    return {
+        ok: true,
+        server: {
+            command: parsed.data.command,
+            args: parsed.data.args ?? [],
+            env,
+            // A newly added command is inert until the person has tested and
+            // explicitly enabled it. Existing file-authored entries keep today's
+            // enabled-by-default behavior through parseStoredMcpServer.
+            enabled: existing ? (parsed.data.enabled ?? existing.enabled) : false,
+        },
+    };
+}
+export function listMcpServers(raw) {
+    return Object.entries(raw ?? {}).flatMap(([name, value]) => {
+        const parsed = parseStoredMcpServer(name, value);
+        if (!parsed.ok)
+            return [];
+        return [{
+                name,
+                command: parsed.server.command,
+                args: parsed.server.args,
+                envKeys: Object.keys(parsed.server.env).sort(),
+                enabled: parsed.server.enabled,
+            }];
+    });
+}

package/dist-server/server/member-turn.js

@@ -0,0 +1,6 @@
+export function memberTurnSelection(selection) {
+    return {
+        model: selection.model,
+        ...(selection.effort ? { effort: selection.effort } : {}),
+    };
+}