openmausbot 0.1.61 → 0.1.63

package/dist-server/server/auto-approve.js

@@ -11,27 +11,13 @@
 // backstop for the obvious catastrophes. Real containment is the
 // sandbox and the bot's own computer, not a regex.
 import { approvalModeFor } from "../shared/approval-mode.js";
-/** The mode a turn actually runs under, given where the turn came from.
- *
- * Full and Custom are Codex's: on any other engine they fall to Ask, so a
- * hand-edited record cannot hand Claude a bypass it was never granted.
- *
- * And Full is a decision the person made about THEIR OWN sessions with a
- * bot — "run without asking me". A turn started by another bot is not one
- * of those: the person never saw the request, and the sender may itself be
- * unattended or working off a page it just read. A Full target reached that
- * way runs as Approve for me instead — ordinary requests still flow, the
- * destructive and sensitive guards card, an unattended sender's block holds,
- * and every answer goes through the fold and into the decision log, where a
- * driver-side Full accept never appears. A webhook or scheduled turn on a
- * Full bot is unchanged: the person opted into that, and the docs say so. */
+/** Full access is the person's explicit grant to this receiving bot, including
+ * delegated work. It never inherits the sender's mode or elevates another bot.
+ * Custom is a provider-config choice rather than an app Full-access grant, so
+ * peer-started Custom turns still use Auto and its unattended downgrade.
+ * Provider support and grant confirmation are checked by the caller. */
 export function approvalModeForOrigin(mode, origin) {
-    // Provider support is settled by supportsApprovalMode at the call site;
-    // this only answers who STARTED the turn. A permissive mode is the
-    // person's grant to the bot they talk to, not to every teammate that can
-    // reach it, so a peer-started turn runs one notch down and still gets the
-    // unattended downgrade after this.
-    if ((mode === "full" || mode === "custom") && origin.peerInitiated)
+    if (mode === "custom" && origin.peerInitiated)
         return "auto";
     return mode;
 }

package/dist-server/server/browser-bundle-release.js

@@ -0,0 +1,56 @@
+// Reviewed vendor assets, downloaded and hashed on 2026-09-07. Update all
+// pins together and run each platform's packaged, offline browser smoke test.
+// This is Chromium's headless shell, not full Chrome (which includes Widevine).
+import { join } from "node:path";
+import { agentBrowserReleaseUrl, agentBrowserReleaseVersion, resolveAgentBrowserReleaseAsset, } from "./browser-engine-release.js";
+export const CHROME_VERSION = "152.0.7977.82";
+export const SUPPORTED_BROWSER_TARGETS = ["darwin-arm64", "darwin-x64", "linux-x64", "win32-x64"];
+const CHROME_ASSETS = {
+    "darwin-arm64": { platform: "mac-arm64", bytes: 97760996, sha256: "1615f063c894aa824fd55c89f8f05e9904f63cce0c95d0cbce7394d77884fba5", executableSha256: "ac18537fb2bc2b72b0440893b6ea5d4ef3bacc6220b1e9a1693c73f8b1045fbe" },
+    "darwin-x64": { platform: "mac-x64", bytes: 102895824, sha256: "c903707292c6aaed7c6e572c0bb5e6645454e45d9e0e6db27e876b18e9165f31", executableSha256: "2faefd55d4e47764956e31e338d362a1e794037fa772a426ffd510f122f33f19" },
+    "linux-x64": { platform: "linux64", bytes: 119454769, sha256: "0ca12ea26b502a83e32db334a17883c315348845efc071d908de7a6d94a97eff", executableSha256: "1301a5024fef1d58c4cfbde5d44794cb18c5b2cbbe4f3c64f81cc4eaa683c45f" },
+    "win32-x64": { platform: "win64", bytes: 119768220, sha256: "86fb1fa7fbbda65f6f1572062c358803e61a6e6d9489e6619b37a61d609fa845", executableSha256: "ec0744f041cb6c35c439c85a5ac42d77b507838cd59cac005e25114025336c98" },
+};
+export function browserBundleSpec(target) {
+    if (!Object.hasOwn(CHROME_ASSETS, target))
+        throw new Error(`Unsupported desktop browser target: ${target}`);
+    const pinned = CHROME_ASSETS[target];
+    const [platform, arch] = target.split("-");
+    const engine = resolveAgentBrowserReleaseAsset(platform, arch);
+    const suffix = platform === "win32" ? ".exe" : "";
+    const directory = `chrome-headless-shell-${pinned.platform}`;
+    return {
+        schemaVersion: 1,
+        target,
+        engine: {
+            version: agentBrowserReleaseVersion(engine),
+            asset: engine.asset,
+            url: agentBrowserReleaseUrl(engine),
+            bytes: engine.bytes,
+            sha256: engine.sha256,
+            executable: `agent-browser${suffix}`,
+        },
+        chrome: {
+            version: CHROME_VERSION,
+            asset: `${directory}.zip`,
+            url: `https://storage.googleapis.com/chrome-for-testing-public/${CHROME_VERSION}/${pinned.platform}/${directory}.zip`,
+            bytes: pinned.bytes,
+            sha256: pinned.sha256,
+            executableSha256: pinned.executableSha256,
+            executable: `chrome/${directory}/chrome-headless-shell${suffix}`,
+            license: `chrome/${directory}/LICENSE.headless_shell`,
+            about: `chrome/${directory}/ABOUT`,
+        },
+    };
+}
+/** bundleDirectory is the target's directory, e.g. Resources/browser-engine. */
+export function browserBundlePaths(bundleDirectory, target) {
+    const spec = browserBundleSpec(target);
+    return {
+        directory: bundleDirectory,
+        manifest: join(bundleDirectory, "manifest.json"),
+        engine: join(bundleDirectory, spec.engine.executable),
+        chrome: join(bundleDirectory, spec.chrome.executable),
+        licenses: join(bundleDirectory, "licenses"),
+    };
+}

package/dist-server/server/browser-engine-release.js

@@ -1,8 +1,8 @@
 // The pinned agent-browser release the harness downloads for the bots'
 // browser (docs/plans/browser-engine.md). Digests were computed from the
-// GitHub release assets on 2026-09-06; bump the version and every digest
-// together, through a pull request whose end-to-end run exercises the binary.
-// The Dockerfile pins the same version.
+// official GitHub assets on 2026-09-06, except the explicitly versioned Windows
+// vendor build below. Update pins through a reviewed native end-to-end run.
+// The Dockerfile retains the official Linux version.
 export const AGENT_BROWSER_VERSION = "0.36.0";
 const RELEASES = new Map([
     [
@@ -31,11 +31,19 @@ const RELEASES = new Map([
     ],
     [
         "win32-x64",
-        { target: "win32-x64", asset: "agent-browser-win32-x64.exe", sha256: "412ff72737a109e93f5304b0ff76c988fb6f1f451d0fc7e010577922bcc20ff3", bytes: 13837312 },
+        {
+            target: "win32-x64", version: "0.36.0-omb.1",
+            asset: "agent-browser-win32-x64-0.36.0-omb.1.exe",
+            url: "https://github.com/milind-soni/OpenMausBot/releases/download/browser-engine-v0.36.0-omb.1/agent-browser-win32-x64-0.36.0-omb.1.exe",
+            sha256: "33bee834f6a6072ec8688b0914726e0262874d758f69f27e8baf7eaac6b5ed15", bytes: 13806080,
+        },
     ],
 ]);
 export function agentBrowserReleaseUrl(asset) {
-    return `https://github.com/vercel-labs/agent-browser/releases/download/v${AGENT_BROWSER_VERSION}/${asset.asset}`;
+    return asset.url ?? `https://github.com/vercel-labs/agent-browser/releases/download/v${AGENT_BROWSER_VERSION}/${asset.asset}`;
+}
+export function agentBrowserReleaseVersion(asset) {
+    return asset?.version ?? AGENT_BROWSER_VERSION;
 }
 /** The asset for this machine, or null where Vercel publishes none. */
 export function resolveAgentBrowserReleaseAsset(platform = process.platform, arch = process.arch, musl = false) {

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

@@ -10,11 +10,13 @@
 // reason a person can act on, never a silently browserless bot.
 import { spawn } from "node:child_process";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { delimiter, join, resolve } from "node:path";
 import { writeFileAtomic } from "./atomic.js";
 import { DATA_DIR } from "./config.js";
-import { AGENT_BROWSER_VERSION, agentBrowserReleaseUrl, resolveAgentBrowserReleaseAsset, } from "./browser-engine-release.js";
+import { browserBundlePaths } from "./browser-bundle-release.js";
+import { AGENT_BROWSER_VERSION, agentBrowserReleaseUrl, agentBrowserReleaseVersion, resolveAgentBrowserReleaseAsset, } from "./browser-engine-release.js";
 const ENGINE_DIR = "tools/agent-browser";
 const KEY_FILE = "browser-engine-key";
 const DOWNLOAD_TIMEOUT_MS = 10 * 60_000;
@@ -25,8 +27,9 @@ function executableName(platform = process.platform) {
 export function isMusl(platform = process.platform, exists = existsSync) {
     return platform === "linux" && (exists("/lib/ld-musl-x86_64.so.1") || exists("/lib/ld-musl-aarch64.so.1"));
 }
-export function pinnedBinaryPath(dataDir = DATA_DIR, platform = process.platform) {
-    return join(dataDir, ENGINE_DIR, AGENT_BROWSER_VERSION, executableName(platform));
+export function pinnedBinaryPath(dataDir = DATA_DIR, platform = process.platform, arch = process.arch) {
+    const version = agentBrowserReleaseVersion(resolveAgentBrowserReleaseAsset(platform, arch));
+    return join(dataDir, ENGINE_DIR, version, executableName(platform));
 }
 function onPath(env, platform, exists) {
     const pathValue = platform === "win32"
@@ -42,7 +45,21 @@ function onPath(env, platform, exists) {
     }
     return null;
 }
-/** OMB_AGENT_BROWSER_PATH, then the pinned download under the data dir, then
+function packagedBrowser(options) {
+    const resources = (options.env ?? process.env).OMB_RESOURCES_PATH;
+    if (!resources)
+        return null;
+    try {
+        return browserBundlePaths(join(resolve(resources), "browser-engine"), `${options.platform ?? process.platform}-${options.arch ?? process.arch}`);
+    }
+    catch {
+        return null; // No desktop bundle for this platform/architecture.
+    }
+}
+function completePackage(bundle, exists) {
+    return [bundle.manifest, bundle.engine, bundle.chrome, bundle.licenses].every(exists);
+}
+/** OMB_AGENT_BROWSER_PATH, then the complete desktop bundle, pinned download, then
  * PATH (a package or image that installed it globally). */
 export function resolveAgentBrowserBinary(options = {}) {
     const env = options.env ?? process.env;
@@ -51,7 +68,10 @@ export function resolveAgentBrowserBinary(options = {}) {
     const override = env.OMB_AGENT_BROWSER_PATH?.trim();
     if (override)
         return resolve(override) && exists(resolve(override)) ? resolve(override) : null;
-    const pinned = pinnedBinaryPath(options.dataDir, platform);
+    const bundle = packagedBrowser(options);
+    if (bundle && exists(bundle.directory))
+        return completePackage(bundle, exists) ? bundle.engine : null;
+    const pinned = pinnedBinaryPath(options.dataDir, platform, options.arch);
     if (exists(pinned))
         return pinned;
     return onPath(env, platform, exists);
@@ -63,11 +83,11 @@ export async function installAgentBrowserBinary(options = {}) {
     const asset = options.asset ?? resolveAgentBrowserReleaseAsset(platform, options.arch ?? process.arch, options.musl ?? isMusl(platform));
     if (!asset)
         throw new Error(`agent-browser publishes no build for ${platform}-${options.arch ?? process.arch}.`);
-    const destination = pinnedBinaryPath(options.dataDir, platform);
+    const destination = pinnedBinaryPath(options.dataDir, platform, options.arch);
     const directory = join(destination, "..");
     mkdirSync(directory, { recursive: true, mode: 0o700 });
     const url = agentBrowserReleaseUrl(asset);
-    options.log?.(`downloading agent-browser ${AGENT_BROWSER_VERSION} (${Math.round(asset.bytes / 1024 / 1024)} MB, digest pinned)`);
+    options.log?.(`downloading agent-browser ${agentBrowserReleaseVersion(asset)} (${Math.round(asset.bytes / 1024 / 1024)} MB, digest pinned)`);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
     timer.unref?.();
@@ -97,6 +117,11 @@ export async function installAgentBrowserBinary(options = {}) {
  * or Brave is found; `--with-deps` adds the Linux libraries (needs a package
  * manager and privileges, so it is for images and root shells). */
 export function ensureChrome(binaryPath, options = {}) {
+    const bundle = packagedBrowser(options);
+    if (!options.withDeps && bundle && resolve(binaryPath) === bundle.engine && completePackage(bundle, existsSync)) {
+        options.log?.("agent-browser: the bundled browser is ready; no download needed");
+        return Promise.resolve();
+    }
     const args = ["install", ...(options.withDeps ? ["--with-deps"] : [])];
     return new Promise((done, fail) => {
         const child = spawn(binaryPath, args, { env: options.env ?? process.env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
@@ -135,13 +160,22 @@ export function browserEngineEncryptionKey(dataDir = DATA_DIR) {
 /** What the harness can offer bots right now, with the reason when nothing. */
 export function browserEngineStatus(options = {}) {
     const binaryPath = resolveAgentBrowserBinary(options);
-    if (binaryPath)
-        return { kind: "ready", binaryPath, version: AGENT_BROWSER_VERSION };
+    const bundle = packagedBrowser(options);
+    if (binaryPath) {
+        const platform = options.platform ?? process.platform;
+        const managed = binaryPath === bundle?.engine || binaryPath === pinnedBinaryPath(options.dataDir, platform, options.arch);
+        const version = managed ? agentBrowserReleaseVersion(resolveAgentBrowserReleaseAsset(platform, options.arch)) : AGENT_BROWSER_VERSION;
+        return { kind: "ready", binaryPath, version };
+    }
+    if (bundle && (options.exists ?? existsSync)(bundle.directory)) {
+        return { kind: "unavailable", reason: "The desktop browser bundle is incomplete. Reinstall or update OpenMausBot to repair it.", installable: false };
+    }
     const platform = options.platform ?? process.platform;
-    const asset = resolveAgentBrowserReleaseAsset(platform, process.arch, isMusl(platform));
+    const arch = options.arch ?? process.arch;
+    const asset = resolveAgentBrowserReleaseAsset(platform, arch, isMusl(platform));
     return asset
         ? { kind: "unavailable", reason: "agent-browser is not installed on this machine yet", installable: true }
-        : { kind: "unavailable", reason: `agent-browser publishes no build for ${platform}-${process.arch}`, installable: false };
+        : { kind: "unavailable", reason: `agent-browser publishes no build for ${platform}-${arch}`, installable: false };
 }
 /** The MCP server a turn mounts so the bot gets browser tools. One isolated,
  * auto-restored session per browser profile (or per bot), page-provided
@@ -149,6 +183,10 @@ export function browserEngineStatus(options = {}) {
 export function agentBrowserIntegration(input) {
     const env = {
         AGENT_BROWSER_SESSION: input.session,
+        // The MCP server invokes child CLI commands without forwarding its own
+        // global flags. The environment keeps page-provided tools disabled in
+        // those commands too, and avoids changing browser launch settings later.
+        AGENT_BROWSER_NO_WEBMCP: "1",
         // This is a restore *name*, not a boolean. "1" would give every bot
         // the same saved cookies despite using different daemon sessions.
         AGENT_BROWSER_RESTORE: input.session,
@@ -157,11 +195,72 @@ export function agentBrowserIntegration(input) {
     };
     if (input.headless !== false)
         env.AGENT_BROWSER_HEADLESS = "1";
-    const path = (input.env ?? process.env).PATH;
-    if (path)
-        env.PATH = path;
+    const sourceEnv = input.env ?? process.env;
+    // MCP clients may filter the parent environment. Carry the configured
+    // Chrome path explicitly without forwarding unrelated secrets or flags.
+    for (const name of ["PATH", "AGENT_BROWSER_EXECUTABLE_PATH"]) {
+        if (sourceEnv[name])
+            env[name] = sourceEnv[name];
+    }
+    const bundle = packagedBrowser({ env: sourceEnv });
+    if (!env.AGENT_BROWSER_EXECUTABLE_PATH && bundle && resolve(input.binaryPath) === bundle.engine && completePackage(bundle, existsSync)) {
+        env.AGENT_BROWSER_EXECUTABLE_PATH = bundle.chrome;
+    }
     return { command: input.binaryPath, args: ["mcp", "--tools", "core", "--no-webmcp"], env };
 }
+/** How long a settled-frame capture may take before the turn gives up on it.
+ * The poller runs beside a live turn, so a hung browser must not hold the
+ * transcript open; a missing picture is better than a stuck fold. */
+const FRAME_TIMEOUT_MS = 10_000;
+/** One PNG of a bot's browser, for the transcript's settled frame.
+ *
+ * The Electron browser surface used to supply this and was removed with the
+ * engine swap, leaving the computer surfaces as the only frame source — so a
+ * bot whose only surface is the browser showed the reader nothing at all,
+ * despite the panel promising screenshots in the chat.
+ *
+ * Runs the same binary with the same session env as the MCP mount, so it
+ * attaches to the daemon the bot is already driving rather than starting a
+ * second browser beside it. */
+export function agentBrowserFrame(input) {
+    const file = join(tmpdir(), `openmausbot-browser-${randomUUID()}.png`);
+    return new Promise((settle, fail) => {
+        const child = spawn(input.binaryPath, ["screenshot", file], {
+            env: { ...process.env, ...input.env },
+            stdio: ["ignore", "ignore", "pipe"],
+            windowsHide: true,
+        });
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => {
+            if (stderr.length < 2_000)
+                stderr += String(chunk);
+        });
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            fail(new Error("the browser did not return a picture in time"));
+        }, input.timeoutMs ?? FRAME_TIMEOUT_MS);
+        const done = (error) => {
+            clearTimeout(timer);
+            try {
+                if (error) {
+                    fail(error);
+                    return;
+                }
+                settle({ png: readFileSync(file).toString("base64"), format: "png" });
+            }
+            catch {
+                fail(new Error("the browser reported a picture it did not write"));
+            }
+            finally {
+                rmSync(file, { force: true });
+            }
+        };
+        child.on("error", (error) => done(error instanceof Error ? error : new Error(String(error))));
+        child.on("close", (code) => {
+            done(code === 0 ? null : new Error(`the browser could not be pictured${stderr.trim() ? `: ${stderr.trim().slice(0, 200)}` : ""}`));
+        });
+    });
+}
 /** Session ids are file-system and shell safe: a bot id or a profile partition. */
 export function browserSessionId(botId, partitionId) {
     if (partitionId === "guest")

package/dist-server/server/cli-api-setup.js

@@ -0,0 +1,144 @@
+// Small, stateless probes for CLI onboarding. The caller owns consent for the
+// metered completion and persistence; neither credentials nor replies are logged.
+export const API_ENDPOINTS = [
+    { id: "openai", label: "OpenAI API", url: "https://api.openai.com/v1", keyUrl: "https://platform.openai.com/api-keys" },
+    { id: "openrouter", label: "OpenRouter", url: "https://openrouter.ai/api/v1", keyUrl: "https://openrouter.ai/settings/keys" },
+    { id: "groq", label: "Groq", url: "https://api.groq.com/openai/v1", keyUrl: "https://console.groq.com/keys" },
+];
+export function normalizeApiUrl(value) {
+    const input = value.trim();
+    const invalid = () => new Error("Enter an HTTPS API base URL without credentials, a query, or a fragment. HTTP is allowed only for localhost.");
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw invalid();
+    }
+    const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if (
+    // Reject invisible URL characters and ambiguous authority/path separators.
+    // eslint-disable-next-line no-control-regex
+    /[\u0000-\u0020\u007f\\?#]/u.test(input) || url.username || url.password ||
+        input.slice(input.indexOf("://") + 3).split("/")[0]?.includes("@") ||
+        (url.protocol !== "https:" && !(url.protocol === "http:" && local)))
+        throw invalid();
+    return url.href.replace(/\/+$/u, "");
+}
+class SetupApiError extends Error {
+}
+function httpFailure(status, completion) {
+    const prefix = `API returned HTTP ${status}.`;
+    if (status === 401 || status === 403)
+        return new SetupApiError(`${prefix} Check the API key and its access permissions.`);
+    if (status === 402)
+        return new SetupApiError(`${prefix} Check the provider's credits and billing settings.`);
+    if (status === 429)
+        return new SetupApiError(`${prefix} A rate or quota limit was reached. Check credits and limits, then try again later.`);
+    if (status >= 300 && status < 400)
+        return new SetupApiError(`${prefix} Redirects are not followed. Use the provider's direct API base URL.`);
+    if (completion && [400, 404, 422].includes(status))
+        return new SetupApiError(`${prefix} Check the model ID and access, or choose a model that supports Chat Completions at this API URL.`);
+    if (status === 404)
+        return new SetupApiError(`${prefix} Check the API base URL: it must provide a /models endpoint.`);
+    if (status >= 500)
+        return new SetupApiError(`${prefix} The provider is unavailable. Try again later.`);
+    return new SetupApiError(`${prefix} Check the API URL and provider settings, then try again.`);
+}
+async function setupJson(url, key, body) {
+    const base = normalizeApiUrl(url);
+    // The wizard trims newly pasted keys. Existing credentials must be tested
+    // exactly as the runtime will send them, not silently repaired only here.
+    const token = key;
+    // Header credentials must not contain control characters or whitespace.
+    // eslint-disable-next-line no-control-regex
+    if (!token || /[\u0000-\u0020\u007f]/u.test(token))
+        throw new SetupApiError("Enter a non-empty API key without spaces or line breaks.");
+    const completion = body !== undefined;
+    const operation = completion ? "The test reply" : "The model list";
+    const timeoutMs = completion ? 30_000 : 8_000;
+    const abort = new AbortController();
+    let timer;
+    try {
+        // Include reading the response body in the deadline, not only headers.
+        return await Promise.race([
+            (async () => {
+                const response = await fetch(`${base}${completion ? "/chat/completions" : "/models"}`, {
+                    method: completion ? "POST" : "GET",
+                    headers: { authorization: `Bearer ${token}`, ...(completion ? { "content-type": "application/json" } : {}) },
+                    ...(completion ? { body: JSON.stringify(body) } : {}),
+                    signal: abort.signal,
+                    redirect: "error",
+                });
+                if (!response.ok) {
+                    void response.body?.cancel().catch(() => { });
+                    throw httpFailure(response.status, completion);
+                }
+                try {
+                    return await response.json();
+                }
+                catch {
+                    throw new SetupApiError(`${operation} returned invalid JSON. Check that the API URL supports the OpenAI-compatible API.`);
+                }
+            })(),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    abort.abort();
+                    reject(new SetupApiError(`${operation} timed out after ${timeoutMs / 1000} seconds. Check the connection and try again.`));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    catch (error) {
+        if (error instanceof SetupApiError)
+            throw error;
+        // fetch errors can contain a URL, echoed credentials, or provider content.
+        // Deliberately expose neither their message nor their cause.
+        throw new SetupApiError("Could not reach the API. Check the network and direct API URL; redirects are not followed.");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+export async function fetchSetupModels(url, key) {
+    const json = record(await setupJson(url, key));
+    const models = new Map();
+    for (const entry of Array.isArray(json?.data) ? json.data : []) {
+        const item = record(entry);
+        const id = typeof item?.id === "string" ? item.id.trim() : "";
+        // Model IDs and display labels reach the terminal; block control sequences.
+        // eslint-disable-next-line no-control-regex
+        if (!id || /[\u0000-\u001f\u007f]/u.test(id) || models.has(id))
+            continue;
+        // eslint-disable-next-line no-control-regex
+        const name = typeof item?.name === "string" ? item.name.replace(/[\u0000-\u001f\u007f]/gu, "").trim() : "";
+        models.set(id, { id, label: name || id });
+    }
+    if (!models.size)
+        throw new SetupApiError("The API returned no usable models. Check the API URL and model access, or enter a model ID from your provider manually.");
+    return [...models.values()];
+}
+/** Call only after consent, passing the effective instance's provider routing. */
+export async function verifySetupCompletion(url, key, model, provider) {
+    const id = model.trim();
+    // Keep manually entered IDs safe to show in the terminal and saved setup.
+    // eslint-disable-next-line no-control-regex
+    if (!id || /[\u0000-\u001f\u007f]/u.test(id))
+        throw new SetupApiError("Choose a non-empty model ID without control characters.");
+    const host = new URL(normalizeApiUrl(url)).hostname.toLowerCase();
+    // Mirror OpenAICompatDriver's OpenRouter-only routing, without inheriting
+    // environment overrides that the caller may have deliberately disabled.
+    const pinProvider = provider && (host === "openrouter.ai" || host.endsWith(".openrouter.ai"));
+    const json = record(await setupJson(url, key, {
+        model: id,
+        messages: [{ role: "user", content: "Reply with exactly OK." }],
+        stream: false,
+        ...(pinProvider ? { provider: { order: [provider], allow_fallbacks: false } } : {}),
+    }));
+    const choice = record(Array.isArray(json?.choices) ? json.choices[0] : undefined);
+    const message = record(choice?.message);
+    if (message?.role !== "assistant" || typeof message.content !== "string" || !message.content.trim()) {
+        throw new SetupApiError("The API did not return an assistant text reply. Choose a model that supports Chat Completions, then try again.");
+    }
+}

package/dist-server/server/cli-phone-setup.js

@@ -0,0 +1,130 @@
+import { SetupCancelled } from "./cli-prompts.js";
+/** A configured HTTPS origin, not proof that a phone can reach it. Never accept
+ * a pasted invitation, password, query token, localhost or unspecified bind. */
+export function normalizePhoneOrigin(raw) {
+    const value = raw.trim();
+    // Reject control characters before URL parsing can silently remove them.
+    // eslint-disable-next-line no-control-regex
+    if (!/^https:\/\/[^/]/i.test(value) || /[\s\u0000-\u001f\u007f\\?#@]/.test(value))
+        return null;
+    try {
+        const url = new URL(value);
+        const host = url.hostname.toLowerCase().replace(/\.$/, "");
+        if (url.protocol !== "https:" || url.username || url.password || url.pathname !== "/")
+            return null;
+        if (!host || host === "localhost" || host.endsWith(".localhost") || host === "0.0.0.0" || host.startsWith("127."))
+            return null;
+        if (host === "[::]" || host === "[::1]" || /^\[::ffff:(?:0:0|7f[0-9a-f]{2}:[0-9a-f]+)\]$/.test(host))
+            return null;
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runPhoneSetup(options, io, deps) {
+    const skip = () => ({ options });
+    const selected = (phone, route = {}) => ({
+        options: { ...options, ...route, client: true, pair: true }, phone,
+    });
+    const signIn = async () => {
+        try {
+            if (await deps.accountReady?.(options)) {
+                io.log("Your saved OpenMausBot account can be reused. The connection will be checked when the server starts.");
+                return true;
+            }
+            io.log("Sign in to an OpenMausBot account using an emailed code. This is separate from your AI provider account.");
+            if (await deps.login(options, io) === 0)
+                return true;
+        }
+        catch (error) {
+            if (error instanceof SetupCancelled)
+                throw error;
+            // Account errors can contain credentials or URLs. Leave details to the
+            // account UI rather than echoing an arbitrary error into terminal logs.
+        }
+        io.log("Phone access could not be prepared. Your AI provider setup is still saved; you can try phone setup later.");
+        return false;
+    };
+    for (;;) {
+        const device = await io.choose("Use OpenMausBot on your phone?", [
+            "Skip for now",
+            "iPhone / iPad — native app or Safari",
+            "Android — web browser",
+        ], 0);
+        if (device === 0)
+            return skip();
+        const phone = device === 1 ? "ios" : "android";
+        if (options.tunnel)
+            return await signIn() ? selected(phone) : skip();
+        if (options.tailscale) {
+            io.log("Keep Tailscale connected on both this computer and your phone, on the same tailnet.");
+            return selected(phone);
+        }
+        const existing = options.publicUrl ? normalizePhoneOrigin(options.publicUrl) : null;
+        if (existing) {
+            io.log("Your configured HTTPS address will be checked before a phone pairing link is shown.");
+            return selected(phone, { publicUrl: existing });
+        }
+        io.log("This server listens only on this computer. A localhost or LAN-IP link will not connect your phone.");
+        let back = false;
+        while (!back) {
+            const route = await io.choose("How should your phone reach this computer?", [
+                "Managed HTTPS address — protected by pairing",
+                "Existing Tailscale — only your tailnet",
+                "Existing HTTPS address — advanced",
+                "Back to phone choice",
+                "Skip for now",
+            ], 4);
+            if (route === 4)
+                return skip();
+            if (route === 3) {
+                back = true;
+                continue;
+            }
+            if (route === 0) {
+                io.log("This creates a public HTTPS endpoint through Cloudflare. Chat and settings require device pairing; the sign-in page and basic server identity are public.");
+                io.log("Starting it may download the Cloudflare connector. It stays active while OpenMausBot runs; stop OpenMausBot to close the connection.");
+                if (!await io.confirm("Allow this managed public endpoint and connector download?", false))
+                    continue;
+                if (!await signIn())
+                    return skip();
+                return selected(phone, { tunnel: true, tailscale: false, publicUrl: undefined });
+            }
+            if (route === 1) {
+                io.log("Tailscale must already be installed and signed in on this computer and phone, with HTTPS certificates enabled for the tailnet.");
+                if (!await io.confirm("Allow OpenMausBot to serve HTTPS to your tailnet while it runs?", false))
+                    continue;
+                return selected(phone, { tailscale: true, tunnel: false, publicUrl: undefined });
+            }
+            io.log("Use an HTTPS reverse proxy you already configured for this server. Enter only its origin, without a password, pairing code, path, query or fragment.");
+            const answer = await io.ask("Existing HTTPS address (Enter goes back): ");
+            if (!answer.trim())
+                continue;
+            const origin = normalizePhoneOrigin(answer);
+            if (!origin) {
+                io.log("Enter a non-localhost HTTPS origin, such as https://maus.example.com. The address was not saved.");
+                continue;
+            }
+            io.log("This does not create a proxy or open a LAN listener. Its connection will be checked before pairing.");
+            return selected(phone, { publicUrl: origin, tunnel: false, tailscale: false });
+        }
+    }
+}
+/** Call after route verification, beside the separately minted QR. The URL
+ * here is an origin, never the invitation containing its one-time credential. */
+export function phonePairingInstructions(phone, input) {
+    const origin = input.origin ? normalizePhoneOrigin(input.origin) : null;
+    if (!input.ready || !origin) {
+        return ["Phone access is not ready yet. No phone QR should be shown until the HTTPS connection is verified.",
+            "Your local OpenMausBot can still be used on this computer."];
+    }
+    return [
+        phone === "ios"
+            ? "On iPhone or iPad, scan the QR with Camera to open Safari. If you already have the OpenMausBot iOS app, use its pairing scanner or paste the full pairing link there."
+            : "On Android, scan the QR with Camera and open it in your web browser. This link is for the web app, not the Android native pairing scanner.",
+        `Or open ${origin}/pair on your phone and enter the code.`,
+        "Choose Connect on the phone. Scanning a QR does not mean the phone is paired.",
+        "The code works once and expires after five minutes. This phone receives client access: chat and approvals, not settings or pairing administration.",
+    ];
+}