openmausbot 0.1.57 → 0.1.58

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

@@ -0,0 +1,44 @@
+// 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.
+export const AGENT_BROWSER_VERSION = "0.36.0";
+const RELEASES = new Map([
+    [
+        "darwin-arm64",
+        { target: "darwin-arm64", asset: "agent-browser-darwin-arm64", sha256: "b2106ab39db0838e7b1772f7f26f760518de56d09053150c56f9dddf15af997d", bytes: 12363200 },
+    ],
+    [
+        "darwin-x64",
+        { target: "darwin-x64", asset: "agent-browser-darwin-x64", sha256: "45d9ac061a7d72e61eaff905326e2e19365f4dadb12142ea2f2d76d84689c708", bytes: 13510280 },
+    ],
+    [
+        "linux-arm64",
+        { target: "linux-arm64", asset: "agent-browser-linux-arm64", sha256: "aeb556addca3903601a433de1acad3ace1c9c61d170084bf58d875884599a990", bytes: 12442720 },
+    ],
+    [
+        "linux-musl-arm64",
+        { target: "linux-musl-arm64", asset: "agent-browser-linux-musl-arm64", sha256: "1ca7e003c9cb185f174fc81e51a609db27c77e3bfe00a0edff60688f8cd14f88", bytes: 12297000 },
+    ],
+    [
+        "linux-musl-x64",
+        { target: "linux-musl-x64", asset: "agent-browser-linux-musl-x64", sha256: "a20cc2a5202a48f5820372803dedbcd5f556dff7a89421f1b0f2612962b10718", bytes: 13995728 },
+    ],
+    [
+        "linux-x64",
+        { target: "linux-x64", asset: "agent-browser-linux-x64", sha256: "56d15181e51e00213f907fcf39707cfc76bfa804ff20f5a9373661c73f96de5e", bytes: 14156776 },
+    ],
+    [
+        "win32-x64",
+        { target: "win32-x64", asset: "agent-browser-win32-x64.exe", sha256: "412ff72737a109e93f5304b0ff76c988fb6f1f451d0fc7e010577922bcc20ff3", bytes: 13837312 },
+    ],
+]);
+export function agentBrowserReleaseUrl(asset) {
+    return `https://github.com/vercel-labs/agent-browser/releases/download/v${AGENT_BROWSER_VERSION}/${asset.asset}`;
+}
+/** The asset for this machine, or null where Vercel publishes none. */
+export function resolveAgentBrowserReleaseAsset(platform = process.platform, arch = process.arch, musl = false) {
+    const key = platform === "linux" && musl ? `linux-musl-${arch}` : `${platform}-${arch}`;
+    return RELEASES.get(key) ?? null;
+}

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

@@ -0,0 +1,185 @@
+// The bots' browser engine: agent-browser (docs/plans/browser-engine.md).
+//
+// One engine on every platform. This module answers three questions for the
+// harness: is the engine here (and if not, why), how does a bot get it as an
+// MCP server for a turn, and where does the session state live. Everything
+// that runs Chrome is agent-browser's; we resolve a pinned binary (or fetch
+// it, verified), make sure it has a Chrome, and hand a turn the spec.
+//
+// Fail closed, say why: a missing engine reports `unavailable` with a
+// 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 { 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";
+const ENGINE_DIR = "tools/agent-browser";
+const KEY_FILE = "browser-engine-key";
+const DOWNLOAD_TIMEOUT_MS = 10 * 60_000;
+function executableName(platform = process.platform) {
+    return platform === "win32" ? "agent-browser.exe" : "agent-browser";
+}
+/** Alpine-style systems need the musl build. */
+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));
+}
+function onPath(env, platform, exists) {
+    const pathValue = platform === "win32"
+        ? Object.entries(env).findLast(([key]) => key.toUpperCase() === "PATH")?.[1]
+        : env.PATH;
+    for (const part of (pathValue ?? "").split(delimiter)) {
+        const dir = part.trim().replace(/^"|"$/gu, "");
+        if (!dir)
+            continue;
+        const candidate = resolve(dir, executableName(platform));
+        if (exists(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** OMB_AGENT_BROWSER_PATH, then the pinned download under the data dir, then
+ * PATH (a package or image that installed it globally). */
+export function resolveAgentBrowserBinary(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const exists = options.exists ?? existsSync;
+    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);
+    if (exists(pinned))
+        return pinned;
+    return onPath(env, platform, exists);
+}
+/** Download the pinned release asset for this machine into the data dir,
+ * verifying size and SHA-256 before the file gets its final name. */
+export async function installAgentBrowserBinary(options = {}) {
+    const platform = options.platform ?? process.platform;
+    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 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)`);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+    timer.unref?.();
+    let body;
+    try {
+        const response = await (options.fetchImpl ?? fetch)(url, { redirect: "follow", signal: controller.signal });
+        if (!response.ok)
+            throw new Error(`the agent-browser download failed (HTTP ${response.status})`);
+        body = Buffer.from(await response.arrayBuffer());
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (body.length !== asset.bytes)
+        throw new Error("the agent-browser download did not match its pinned size; nothing was installed");
+    const digest = createHash("sha256").update(body).digest("hex");
+    if (digest !== asset.sha256)
+        throw new Error("the agent-browser download failed its SHA-256 check; nothing was installed");
+    const staging = `${destination}.${randomBytes(6).toString("hex")}.part`;
+    writeFileSync(staging, body, { mode: 0o755 });
+    if (platform !== "win32")
+        chmodSync(staging, 0o755);
+    renameSync(staging, destination);
+    return destination;
+}
+/** `agent-browser install` fetches Chrome for Testing when no Chrome, Chromium
+ * 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 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 });
+        let output = "";
+        child.stdout?.on("data", (chunk) => { output += String(chunk); });
+        child.stderr?.on("data", (chunk) => { output += String(chunk); });
+        child.on("error", fail);
+        child.on("exit", (code) => {
+            if (code === 0) {
+                options.log?.("agent-browser: Chrome is ready");
+                done();
+            }
+            else {
+                fail(new Error(`agent-browser install exited ${code ?? "by signal"}: ${output.trim().split("\n").slice(-3).join(" ")}`));
+            }
+        });
+    });
+}
+/** The key agent-browser uses to encrypt saved session state at rest. Made
+ * once, 0600, beside the rest of the data dir's secrets. */
+export function browserEngineEncryptionKey(dataDir = DATA_DIR) {
+    const file = join(dataDir, KEY_FILE);
+    try {
+        const existing = readFileSync(file, "utf8").trim();
+        if (/^[0-9a-f]{64}$/u.test(existing))
+            return existing;
+    }
+    catch {
+        // first run
+    }
+    const key = randomBytes(32).toString("hex");
+    mkdirSync(dataDir, { recursive: true });
+    writeFileAtomic(file, `${key}\n`, { mode: 0o600 });
+    return key;
+}
+/** 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 platform = options.platform ?? process.platform;
+    const asset = resolveAgentBrowserReleaseAsset(platform, process.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 };
+}
+/** 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
+ * WebMCP tools off, and only the core tool set. */
+export function agentBrowserIntegration(input) {
+    const env = {
+        AGENT_BROWSER_SESSION: input.session,
+        // 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,
+        AGENT_BROWSER_RESTORE_SAVE: input.persistent === false ? "never" : "auto",
+        AGENT_BROWSER_ENCRYPTION_KEY: input.encryptionKey,
+    };
+    if (input.headless !== false)
+        env.AGENT_BROWSER_HEADLESS = "1";
+    const path = (input.env ?? process.env).PATH;
+    if (path)
+        env.PATH = path;
+    return { command: input.binaryPath, args: ["mcp", "--tools", "core", "--no-webmcp"], env };
+}
+/** Session ids are file-system and shell safe: a bot id or a profile partition. */
+export function browserSessionId(botId, partitionId) {
+    if (partitionId === "guest")
+        return `guest-${randomUUID()}`;
+    const raw = partitionId || `bot-${botId}`;
+    return raw.replace(/[^A-Za-z0-9_.-]/gu, "_").slice(0, 96);
+}
+export function describeBrowserEngine(status) {
+    return status.kind === "ready"
+        ? `browser engine: agent-browser ${status.version} at ${status.binaryPath}`
+        : `browser engine: unavailable (${status.reason})`;
+}
+// Kept for callers that want a file check without a full status.
+export function agentBrowserBinaryExists(dataDir = DATA_DIR) {
+    try {
+        return statSync(pinnedBinaryPath(dataDir)).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist-server/server/cli.js

@@ -28,9 +28,10 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import qrcode from "qrcode-terminal";
 import { explainTailscaleFailure, tailscaleServe, tailscaleServeOff, tailscaleStatus } from "./tailscale.js";
+import { browserEngineStatus, describeBrowserEngine, ensureChrome, installAgentBrowserBinary, resolveAgentBrowserBinary, } from "./browser-engine.js";
 import { cleanupTunnelOrigin, createTunnelAccount, createTunnelOrigin, describeTunnelAccount, describeTunnelState, ensureCloudflared, guardianEntry, startTunnel, tunnelAccess, } from "./tunnel.js";
 const HERE = dirname(fileURLToPath(import.meta.url));
-const COMMANDS = ["serve", "pair", "sessions", "status", "login", "logout", "help", "--help", "-h"];
+const COMMANDS = ["serve", "pair", "sessions", "status", "login", "logout", "browser", "help", "--help", "-h"];
 export function parseArgs(argv, env = process.env) {
     const [command = "help", ...rest] = argv;
     if (!COMMANDS.includes(command)) {
@@ -44,6 +45,7 @@ export function parseArgs(argv, env = process.env) {
         tunnel: false,
         client: false,
         pair: true,
+        withDeps: false,
         json: false,
     };
     for (let i = 0; i < rest.length; i += 1) {
@@ -78,6 +80,10 @@ export function parseArgs(argv, env = process.env) {
                 options.email = value();
             else if (options.command === "sessions" && arg === "revoke")
                 options.revoke = value();
+            else if (options.command === "browser" && (arg === "install" || arg === "status"))
+                options.browserAction = arg;
+            else if (options.command === "browser" && arg === "--with-deps")
+                options.withDeps = true;
             else
                 return { error: `unknown argument "${arg}"` };
         }
@@ -91,6 +97,8 @@ export function parseArgs(argv, env = process.env) {
         return { error: "--public-url must start with http:// or https://" };
     if (options.tailscale && options.tunnel)
         return { error: "choose one of --tailscale (your tailnet) and --tunnel (a public address)" };
+    if (options.command === "browser" && !options.browserAction)
+        return { error: "browser needs an action: install or status" };
     return options;
 }
 export const USAGE = `openmausbot — run the server anywhere, pair devices to it
@@ -102,6 +110,7 @@ export const USAGE = `openmausbot — run the server anywhere, pair devices to i
   openmausbot status
   openmausbot login [--email you@example.com]
   openmausbot logout
+  openmausbot browser install [--with-deps] | status
 
 serve   starts the server and prints a pairing link + QR code
 pair    mints a pairing code against a running server (--client: chat only)
@@ -110,6 +119,10 @@ status  what the server says about itself
 login   signs this machine in to an OpenMausBot account (an emailed code)
         and reserves its public address for --tunnel
 logout  releases that address and signs out
+browser install: the bots' browser engine (agent-browser, pinned) and a
+        Chrome for Testing, into the data dir; --with-deps also installs
+        the Linux libraries Chrome needs (run as root once). status: what
+        this machine has.
 
 --tailscale  serve over your tailnet: Tailscale terminates HTTPS and the
              link uses this machine's MagicDNS name (needs Tailscale signed in
@@ -329,6 +342,44 @@ export async function runLogout(options, io = defaultIo()) {
     io.log(`Signed out ${before.email}${before.address ? `; ${before.address} is released` : ""}.`);
     return 0;
 }
+export async function runBrowser(options, io = defaultIo()) {
+    const status = browserEngineStatus({ dataDir: options.dataDir });
+    if (options.browserAction === "status") {
+        io.log(describeBrowserEngine(status));
+        if (status.kind !== "ready" && status.installable)
+            io.log("install it with:  openmausbot browser install");
+        return status.kind === "ready" ? 0 : 1;
+    }
+    let binary = resolveAgentBrowserBinary({ dataDir: options.dataDir });
+    if (binary) {
+        io.log(`agent-browser is already here: ${binary}`);
+    }
+    else {
+        if (status.kind !== "ready" && !status.installable) {
+            io.error(status.reason);
+            return 1;
+        }
+        try {
+            binary = await installAgentBrowserBinary({ dataDir: options.dataDir, log: io.log });
+        }
+        catch (error) {
+            io.error(`could not install agent-browser: ${message(error)}`);
+            return 1;
+        }
+        io.log(`installed ${binary}`);
+    }
+    try {
+        await ensureChrome(binary, { withDeps: options.withDeps === true, log: io.log });
+    }
+    catch (error) {
+        io.error(`Chrome is not ready: ${message(error)}`);
+        if (process.platform === "linux" && !options.withDeps)
+            io.error("on Linux, Chrome needs system libraries: run `sudo openmausbot browser install --with-deps` once");
+        return 1;
+    }
+    io.log("bots on this server can use a browser now: turn it on under Settings → Experimental, then per bot");
+    return 0;
+}
 /** Where the server bundle lives relative to this file: next to it in the
  * npm package and the image (dist-server/), or the TypeScript source in a
  * checkout. */
@@ -485,6 +536,7 @@ export async function runServe(options, log = console.log) {
     log("");
     log(`OpenMausBot is running on http://127.0.0.1:${options.port}${publicUrl ? `, reachable at ${publicUrl}` : ""}`);
     log(`data: ${options.dataDir}`);
+    log(describeBrowserEngine(browserEngineStatus({ dataDir: options.dataDir })));
     if (options.pair) {
         log("");
         log(await mintPairing(options.port, { label: options.label ? `${options.label} owner` : undefined, publicUrl: publicUrl ?? undefined }));
@@ -517,6 +569,8 @@ export async function main(argv = process.argv.slice(2)) {
             return runLogin(options);
         case "logout":
             return runLogout(options);
+        case "browser":
+            return runBrowser(options);
         default:
             console.log(USAGE);
             return 0;

package/dist-server/server/drivers/antigravity-acp.js

@@ -48,6 +48,24 @@ function takeLines(buffer) {
     const rest = parts.pop() ?? "";
     return { lines: parts.map((line) => line.replace(/\r$/u, "")), rest };
 }
+/** Only fixed, allowlisted startup hints leave stderr. Native output can
+ * contain OAuth codes and credentials in arbitrary formats, so generic
+ * text redaction is not enough to safely echo a diagnostic tail. */
+function startupHint(line) {
+    if (/no space left|not enough (?:space|disk)|disk (?:is )?full|winerror\s*112/iu.test(line)) {
+        return "The runtime reported insufficient disk space while starting.";
+    }
+    if (/failed to (?:extract|load (?:python|embedded python))|could not load python/iu.test(line)) {
+        return "The runtime reported a problem unpacking or loading its bundled Python runtime.";
+    }
+    if (/permission denied|access is denied|winerror\s*5\b/iu.test(line)) {
+        return "The runtime reported a file or process permission failure.";
+    }
+    if (/address family not supported|failed to create.*(?:socket|listener)|failed to bind/iu.test(line)) {
+        return "The runtime reported a local network listener failure.";
+    }
+    return undefined;
+}
 /** The sign-in link in a server output line, or null for anything else.
  * Google announces it two ways and both land on stderr: it hands the link to
  * $BROWSER — our helper re-emits it JSON-encoded behind a private marker — and
@@ -125,6 +143,10 @@ export class AntigravityAcpClient {
     pending = new Map();
     buffer = "";
     diagnosticBuffer = "";
+    initializationComplete = false;
+    startupOutputBytes = 0;
+    startupDiagnosticBytes = 0;
+    nativeStartupHint;
     closed = false;
     onAuthorizationUrl;
     /** Settles once the runtime process is gone. On Windows a running
@@ -136,16 +158,17 @@ export class AntigravityAcpClient {
         this.child = spawnCli(runtime.executablePath, process.platform === "linux" ? ["--uid="] : [], { cwd, env: profile.environment, stdio: ["pipe", "pipe", "pipe"] });
         this.child.stdout.setEncoding("utf8");
         this.child.stdout.on("data", (chunk) => this.consume(chunk));
-        // Google announces the sign-in link on stderr, not stdout. Scan for that
-        // one line and drop every other byte: stderr also carries authorization
-        // codes, so nothing else is retained or surfaced.
+        // Keep only sign-in announcements and fixed startup failure categories;
+        // never surface raw stderr, which can contain authorization codes.
         this.child.stderr.setEncoding("utf8");
         this.child.stderr.on("data", (chunk) => this.consumeDiagnostics(chunk));
         this.child.once("error", (error) => this.failAll(error));
         this.exited = new Promise((resolve) => {
-            this.child.once("close", (code) => {
+            this.child.once("close", (code, signal) => {
+                this.noteStartupDiagnostic(this.diagnosticBuffer);
+                this.diagnosticBuffer = "";
                 if (!this.closed)
-                    this.failAll(new Error(`Antigravity ACP exited ${code ?? "unexpectedly"}.`));
+                    this.failAll(new Error(`Antigravity ACP exited ${code ?? signal ?? "unexpectedly"}.${this.nativeStartupHint ? ` ${this.nativeStartupHint}` : ""}`));
                 resolve();
             });
             // Failed spawns also emit `close`. An `error` alone can instead mean
@@ -153,6 +176,8 @@ export class AntigravityAcpClient {
         });
     }
     consume(chunk) {
+        if (!this.initializationComplete)
+            this.startupOutputBytes += Buffer.byteLength(chunk);
         this.buffer += chunk;
         if (Buffer.byteLength(this.buffer) > MAX_PROTOCOL_LINE_BYTES) {
             this.failAll(new Error("Antigravity sent a protocol line that is too large."));
@@ -206,11 +231,19 @@ export class AntigravityAcpClient {
      * and released immediately and the tail is capped, so no authorization code
      * is ever held. Draining also keeps the pipe from stalling the server. */
     consumeDiagnostics(chunk) {
+        if (!this.initializationComplete)
+            this.startupDiagnosticBytes += Buffer.byteLength(chunk);
         const { lines, rest } = takeLines(this.diagnosticBuffer + chunk);
         // A partial line already longer than any legal link cannot become one.
         this.diagnosticBuffer = rest.length > MAX_DIAGNOSTIC_LINE_CHARS ? "" : rest;
-        for (const line of lines)
-            this.announceAuthorizationUrl(line);
+        for (const line of lines) {
+            if (!this.announceAuthorizationUrl(line))
+                this.noteStartupDiagnostic(line);
+        }
+    }
+    noteStartupDiagnostic(line) {
+        if (!this.initializationComplete)
+            this.nativeStartupHint ??= startupHint(line);
     }
     failAll(error) {
         for (const pending of this.pending.values()) {
@@ -227,7 +260,16 @@ export class AntigravityAcpClient {
         return new Promise((resolveRequest, reject) => {
             const timer = setTimeout(() => {
                 this.pending.delete(id);
-                reject(new Error(`${method} timed out.`));
+                if (method === "initialize") {
+                    this.noteStartupDiagnostic(this.diagnosticBuffer);
+                    reject(new Error(`Antigravity initialization timed out after ${Math.ceil(timeoutMs / 1_000)} seconds (${process.platform}-${process.arch}). ` +
+                        "The executable was found, but did not finish starting. " +
+                        (this.nativeStartupHint ? `${this.nativeStartupHint} ` : "") +
+                        `Startup output: ${this.startupOutputBytes} bytes; diagnostic output: ${this.startupDiagnosticBytes} bytes. ` +
+                        "Retry setup. If it still fails, share this error and your OpenMausBot version; do not paste Google sign-in links or tokens."));
+                }
+                else
+                    reject(new Error(`${method} timed out.`));
             }, timeoutMs);
             timer.unref?.();
             this.pending.set(id, { resolve: resolveRequest, reject, timer });
@@ -235,11 +277,14 @@ export class AntigravityAcpClient {
         });
     }
     async initialize(timeoutMs = STARTUP_TIMEOUT_MS) {
-        return this.request("initialize", {
+        const initialized = await this.request("initialize", {
             protocolVersion: 1,
             clientInfo: { name: "openmausbot", version: "0.0.0" },
             clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
         }, timeoutMs);
+        this.initializationComplete = true;
+        this.nativeStartupHint = undefined;
+        return initialized;
     }
     close() {
         if (this.closed)
@@ -440,6 +485,12 @@ export async function validateAntigravityRuntime(runtime, expectedVersion) {
             instanceId: `verify-${randomUUID()}`,
             runtime,
             profileDirectory,
+            // Google's Windows one-file executable expands a large Python runtime
+            // into TEMP. Forced shutdown skips its own cleanup. Keep verification's
+            // extraction inside the profile we already remove after confirmed close.
+            baseEnv: process.platform === "win32"
+                ? { ...process.env, TEMP: profileDirectory, TMP: profileDirectory }
+                : undefined,
         });
         client = new AntigravityAcpClient(runtime, profile, profileDirectory);
         const initialized = await client.initialize();

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

@@ -2,6 +2,7 @@ import { createAcpDriver } from "./acp/core.js";
 import { AntigravityAuthController, antigravityProfileAuthenticated, catalogFromAntigravityConfigOptions, prepareAntigravityProfile, probeAntigravityModels, validateAntigravityRuntime, } from "./antigravity-acp.js";
 import { antigravityManagedInstallAvailable, installAntigravityRuntime, resolveAntigravityRuntime, } from "./antigravity-runtime.js";
 import { resolveAntigravityReleaseAsset } from "./antigravity-release.js";
+import { augmentedPath } from "../env-path.js";
 export const STATIC_ANTIGRAVITY_MODELS = {
     default: "gemini-3.8-flash-high",
     options: [
@@ -107,8 +108,11 @@ export const AntigravityDriver = {
     async create(input) {
         const base = await AcpAntigravityDriver.create(input);
         const auth = new AntigravityAuthController();
+        let installFailure;
         const runtimeAndProfile = async () => {
-            const environment = { ...process.env, ...input.environment };
+            // Match the ACP driver's discovery/chat environment. A GUI launch's
+            // raw PATH may omit an official runtime that the model picker found.
+            const environment = { ...process.env, ...input.environment, PATH: augmentedPath() };
             const runtime = await resolveAntigravityRuntime(input.config.cli, environment);
             const profile = await prepareAntigravityProfile({
                 instanceId: input.instanceId,
@@ -122,10 +126,27 @@ export const AntigravityDriver = {
             get models() {
                 return base.models;
             },
+            snapshot: async () => {
+                const snapshot = await base.snapshot();
+                if (snapshot.state === "available")
+                    installFailure = undefined;
+                // A failed first install has no promoted executable yet. Preserve
+                // why it failed across closing/reopening setup in this app session.
+                return snapshot.state === "unavailable" && installFailure
+                    ? { ...snapshot, reason: installFailure }
+                    : snapshot;
+            },
             ...(antigravityManagedInstallAvailable()
                 ? {
                     installRuntime: async () => {
-                        await installAntigravityRuntime({ validate: validateAntigravityRuntime });
+                        installFailure = undefined;
+                        try {
+                            await installAntigravityRuntime({ validate: validateAntigravityRuntime });
+                        }
+                        catch (error) {
+                            installFailure = error instanceof Error ? error.message : String(error);
+                            throw error;
+                        }
                     },
                 }
                 : {}),

package/dist-server/server/index.js

@@ -85,6 +85,7 @@ import * as vps from "./vps-computer.js";
 import { RoutineManager } from "./routines.js";
 import { CalendarCallManager } from "./calendar-calls.js";
 import { BUILT_IN_BROWSER_SYSTEM_PROMPT, applyDesktopBrowserConnectionMessage, availableBrowserConnection, browserScreenshot, clearBrowserCapabilities, registerBrowserCapability, revokeBrowserCapability, } from "./browser-connection.js";
+import { agentBrowserIntegration, browserEngineEncryptionKey, browserEngineStatus, browserSessionId, describeBrowserEngine, } from "./browser-engine.js";
 import { captureOutsideHumanControl } from "./private-screen-capture.js";
 import { screenFrameHash, screenTouchingTool, settledFrameIsNews } from "./screen-frame-gate.js";
 import { RoutineRequestService } from "./routine-requests.js";
@@ -542,7 +543,7 @@ function cancelDirectTurnDispatch(botId, expectedThreadId) {
 async function browserIntegration(botId, profile, threadId, generation, stillValid = () => true, ownerId = randomUUID()) {
     const connection = availableBrowserConnection();
     if (!connection)
-        return null;
+        return engineBrowserIntegration(botId, profile);
     const control = controlIntegration(botId, threadId, generation);
     // A profile that no longer exists falls back to the bot's own session.
     // Canonical ids belong to config/bot references; Electron must receive the
@@ -583,6 +584,43 @@ async function browserIntegration(botId, profile, threadId, generation, stillVal
         },
     };
 }
+/** No desktop surface (a server, or a Windows desktop): the bot's browser is
+ * agent-browser, one isolated session per profile or per bot
+ * (docs/plans/browser-engine.md). Returns null, with the reason logged once,
+ * when the engine is not on this machine. */
+function engineBrowserIntegration(botId, profile) {
+    const status = browserEngineStatus();
+    if (status.kind !== "ready") {
+        if (!engineUnavailableLogged) {
+            engineUnavailableLogged = true;
+            console.warn(`${describeBrowserEngine(status)}; bots get no browser tools until it is installed`);
+        }
+        return null;
+    }
+    const profileTarget = profile && profile !== "guest" ? browserProfilePartitionTarget(cfg, profile) : null;
+    const partitionId = profile === "guest" ? "guest" : (profileTarget?.partitionId ?? "");
+    const session = browserSessionId(botId, partitionId);
+    return {
+        connection: null,
+        capability: null,
+        profile: partitionId,
+        integration: agentBrowserIntegration({
+            binaryPath: status.binaryPath,
+            session,
+            encryptionKey: browserEngineEncryptionKey(),
+            persistent: profile !== "guest",
+        }),
+    };
+}
+let engineUnavailableLogged = false;
+export function browserEngineSummary() {
+    if (availableBrowserConnection())
+        return { kind: "desktop" };
+    const status = browserEngineStatus();
+    return status.kind === "ready"
+        ? { kind: "headless", version: status.version }
+        : { kind: "unavailable", reason: status.reason, installable: status.installable };
+}
 function phoneIntegration() {
     const env = { ...AGENTS_NODE_FLAG };
     if (process.env.OMB_ADB_PATH)
@@ -4002,9 +4040,9 @@ async function startTurn(botId, text, opts) {
             // after its own turn.completed would never be torn down — it would
             // keep polling the box forever, carrying dead per-turn state. busy
             // is flipped false in the fold, so it is the honest "still running".
-            if (!previewCapture && browser) {
-                const { connection } = browser;
-                previewCapture = () => browserScreenshot(connection, browser.capability, fetch);
+            if (!previewCapture && browser?.connection && browser.capability) {
+                const { connection, capability } = browser;
+                previewCapture = () => browserScreenshot(connection, capability, fetch);
             }
             if (previewCapture && store.bot(bot.id)?.busy) {
                 startScreenPoller(bot.id, previewCapture, { screenIsTheWork: instance.driverKind === "boxAgent" });
@@ -6534,6 +6572,9 @@ function configStatus() {
             showToolCalls: showToolCallsEnabled(cfg),
             browser: builtInBrowserEnabled(cfg),
         },
+        // Which browser this server can give bots: the desktop app's surface,
+        // the agent-browser engine, or nothing yet (with the reason).
+        browserEngine: browserEngineSummary(),
         // partitionId is non-secret routing metadata. The renderer needs it to
         // show the same durable session as an agent, but config PATCH validation
         // keeps it read-only and rejects callers that try to choose it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmausbot",
-  "version": "0.1.57",
+  "version": "0.1.58",
   "description": "Run the OpenMausBot server anywhere and pair your devices to it",
   "license": "Apache-2.0",
   "type": "module",