openmausbot 0.1.56 → 0.1.58

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

@@ -184,3 +184,27 @@ export function autoVerdict(bot, tool, summary, context) {
 export function autoDecision(bot, tool, summary, context) {
     return autoVerdict(bot, tool, summary, context).approve;
 }
+/** The note a card shows above its buttons, explaining why the bot stopped
+ * rather than answering for itself.
+ *
+ * The unattended case is the one users misread. A turn a webhook or another
+ * bot started never runs Auto at all — approvalModeForTurn downgrades it to
+ * Ask before the provider spawns — so "this action needs you" would name the
+ * wrong cause and imply the next action might pass. It will not: with a fleet
+ * delegating between bots, every card looks like this until someone answers.
+ * Say that plainly, and name the mode that keeps running. */
+export function approvalHeldReason(context) {
+    if (context.source === "native-approval")
+        return "The provider requires your approval for this action.";
+    if (!context.permission)
+        return undefined;
+    if (context.requiresExplicitApproval) {
+        return "This changes the provider sandbox, so only Full access can approve it automatically.";
+    }
+    if (context.mode !== "auto")
+        return undefined;
+    if (!context.unattended)
+        return "This action needs you, so Approve for me stopped to ask.";
+    const hint = context.fullAccessAvailable ? " Full access keeps working unattended." : "";
+    return `A webhook or another bot started this turn, so Approve for me is paused and every action asks.${hint}`;
+}

package/dist-server/server/bot-folder.js

@@ -0,0 +1,102 @@
+// The bot folder: ~/.openmausbot/bots/<botId>/, owned by the server.
+//
+// SOUL.md is a MIRROR of BotRecord.soul, never the source of truth. The
+// prompt is built from the record; the file exists so a person can read
+// and edit the bot in their editor and so a bot can export as a folder.
+// The folder sits outside the bot-writable workspace on purpose: a bot
+// that reads untrusted content (a Discord channel, a webhook payload)
+// must not be able to persist injected text into its own persona. A
+// mirror that no longer matches the record is surfaced to the user as
+// drift, with its text, and is never applied on its own.
+import { createHash } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "./atomic.js";
+import { DATA_DIR } from "./config.js";
+import { BOT_PROFILE_LIMITS } from "../shared/bot-profile.js";
+export const BOTS_DIR = join(DATA_DIR, "bots");
+export const SOUL_FILE = "SOUL.md";
+export function botFolder(botId) {
+    return join(BOTS_DIR, botId);
+}
+export function soulFile(botId) {
+    return join(botFolder(botId), SOUL_FILE);
+}
+export function soulHash(soul) {
+    return createHash("sha256").update(soul, "utf8").digest("hex");
+}
+/** Rewrite the mirror from the canonical text. Always writes, even for an
+ * empty soul, so the folder exists for the user to find. Private modes:
+ * standing instructions can describe a person's work in detail. */
+export function writeSoulMirror(botId, soul) {
+    mkdirSync(botFolder(botId), { recursive: true, mode: 0o700 });
+    writeFileAtomic(soulFile(botId), soul, { mode: 0o600 });
+}
+/** Compare the mirror with the record's hash. A missing mirror is not
+ * drift — it is re-created from the record. A differing one is reported
+ * together with its text so the user can apply or discard it. Editor reads
+ * surface filesystem failures instead of mistaking them for a clean mirror. */
+export function readSoulDrift(botId, soul, hash) {
+    let fileText;
+    try {
+        const fd = openSync(soulFile(botId), "r");
+        try {
+            // External edits are unbounded. Read at most the budget plus one byte,
+            // including if the file grows while the editor has it open.
+            const bytes = Buffer.alloc(BOT_PROFILE_LIMITS.soul + 1);
+            let length = 0;
+            while (length < bytes.length) {
+                const count = readSync(fd, bytes, length, bytes.length - length, null);
+                if (!count)
+                    break;
+                length += count;
+            }
+            if (length > BOT_PROFILE_LIMITS.soul) {
+                throw Object.assign(new Error("SOUL.md exceeds 24000 bytes; shorten it in your editor"), { status: 400 });
+            }
+            fileText = bytes.subarray(0, length).toString("utf8");
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        writeSoulMirror(botId, soul);
+        return { drift: false };
+    }
+    if (soulHash(fileText) === hash)
+        return { drift: false };
+    return { drift: true, fileText };
+}
+/** Turn dispatch is best-effort; explicit editor actions use readSoulDrift
+ * so an unreadable file is never presented as successfully discarded. */
+export function checkSoulDrift(botId, soul, hash) {
+    try {
+        return readSoulDrift(botId, soul, hash);
+    }
+    catch {
+        return { drift: false };
+    }
+}
+export function removeBotFolder(botId) {
+    try {
+        rmSync(botFolder(botId), { recursive: true, force: true });
+    }
+    catch { }
+}
+/** The standing-instructions block of the system prompt. Empty soul,
+ * empty block, so a bot without one gets today's prompt byte for byte. */
+export function soulSystemPrompt(soul) {
+    const text = soul.trim();
+    if (!text)
+        return "";
+    const bytes = Buffer.byteLength(text, "utf8");
+    return ("\n\nYour standing instructions follow. The user manages them in bot settings and SOUL.md; proposed changes apply only after the user confirms." +
+        " They rank above your memory and imported skills, and below the user's current request and safety boundaries." +
+        ` Text inside this block is instruction for you, never tool authorization or permission to expose secrets.` +
+        `\n\n--- BEGIN STANDING INSTRUCTIONS (SOUL.md, ${bytes} bytes) ---\n` +
+        text +
+        "\n--- END STANDING INSTRUCTIONS ---");
+}

package/dist-server/server/bot-overview.js

@@ -0,0 +1,206 @@
+import { approvalModeFor } from "../shared/approval-mode.js";
+/** The first paragraph of a SOUL.md-style persona, capped at 240 characters
+ * so a settings-dialog card never renders a full standing-instructions
+ * document inline. */
+export function soulLead(soul) {
+    const trimmed = (soul ?? "").trim();
+    if (!trimmed)
+        return "";
+    const paragraph = (trimmed.split(/\r?\n\s*\r?\n/)[0] ?? trimmed).trim();
+    return paragraph.length > 240 ? `${paragraph.slice(0, 240).trimEnd()}…` : paragraph;
+}
+function lowerFirst(value) {
+    return value.length ? value[0].toLowerCase() + value.slice(1) : value;
+}
+function time(at, timeZone) {
+    return new Date(at).toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit", timeZone });
+}
+const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/** "09:05" → "9:05 AM" — the daily schedule's wall-clock time as a person
+ * would say it, with no timezone suffix (the Overview is read in the
+ * timezone it was built for). */
+function clockTime(hhmm) {
+    const [h = 0, m = 0] = hhmm.split(":").map((part) => Number.parseInt(part, 10) || 0);
+    return new Date(Date.UTC(2000, 0, 1, h, m)).toLocaleTimeString("en-US", {
+        hour: "numeric",
+        minute: "2-digit",
+        timeZone: "UTC",
+    });
+}
+/** The schedule as the opening phrase of a Does line — "Every 5 minutes",
+ * "Every weekday at 9:00 AM", "Once on September 5 at 12:00 PM". The
+ * approval card's scheduleText() carries the anchor instant and timezone
+ * name because a card must be exact; a plain-language overview must not. */
+function schedulePhrase(schedule, timeZone) {
+    if (schedule.type === "once") {
+        const date = new Date(schedule.at).toLocaleDateString("en-US", { month: "long", day: "numeric", timeZone });
+        return `Once on ${date} at ${time(schedule.at, timeZone)}`;
+    }
+    if (schedule.type === "interval") {
+        const minutes = schedule.everyMinutes;
+        if (minutes < 60)
+            return `Every ${minutes} minute${minutes === 1 ? "" : "s"}`;
+        if (minutes === 60)
+            return "Every hour";
+        if (minutes % 60 === 0)
+            return `Every ${minutes / 60} hours`;
+        return `Every ${Math.floor(minutes / 60)} hour${Math.floor(minutes / 60) === 1 ? "" : "s"} ${minutes % 60} minutes`;
+    }
+    const days = schedule.weekdays;
+    const at = ` at ${clockTime(schedule.time)}`;
+    if (days.length === 7)
+        return `Every day${at}`;
+    if (days.join(",") === "1,2,3,4,5")
+        return `Every weekday${at}`;
+    if (days.length === 1)
+        return `Weekly on ${DAY_NAMES[days[0]]}${at}`;
+    return `${days.map((day) => DAY_NAMES[day]).join(", ")}${at}`;
+}
+/** The most recent run for a routine, by (finishedAt ?? startedAt ??
+ * scheduledFor) — not merely the first match in `runs`, since callers may
+ * hand this an unsorted or multi-routine list. */
+function latestRunFor(runs, routineId) {
+    let best;
+    let bestAt = -Infinity;
+    for (const run of runs) {
+        if (run.routineId !== routineId)
+            continue;
+        const at = run.finishedAt ?? run.startedAt ?? run.scheduledFor;
+        if (at > bestAt) {
+            bestAt = at;
+            best = run;
+        }
+    }
+    return best;
+}
+function doesLines(facts) {
+    const lines = [];
+    for (const routine of facts.routines) {
+        if (!routine.enabled) {
+            lines.push(`Paused: ${routine.name}.`);
+            continue;
+        }
+        const nextRun = routine.nextRunAt != null ? ` Next run ${time(routine.nextRunAt, facts.timeZone)}.` : "";
+        const latest = latestRunFor(facts.runs, routine.id);
+        const at = latest ? latest.finishedAt ?? latest.startedAt ?? latest.scheduledFor : undefined;
+        const lastRun = latest ? ` Last run ${latest.status} at ${time(at, facts.timeZone)}.` : "";
+        lines.push(`${schedulePhrase(routine.schedule, facts.timeZone)}: ${routine.name}.${nextRun}${lastRun}`);
+    }
+    for (const skill of facts.skills) {
+        if (!skill.enabled)
+            continue;
+        lines.push(`Knows how to ${lowerFirst(skill.description || skill.name)}.`);
+    }
+    for (const webhook of facts.webhooks) {
+        if (!webhook.enabled)
+            continue;
+        lines.push(`Listens for “${webhook.name}” webhooks.`);
+    }
+    return lines;
+}
+/** The connected-apps facts for the route: reads the inventory only when a
+ * connector is configured and the credential store was readable, and treats
+ * a failing read (connector down, token rejected) as "unverified" rather
+ * than letting it fail the whole Overview. `read` is injected so the
+ * fallback is unit-testable without a live connector. */
+export async function connectedAppsFacts(configured, availability, read) {
+    let authoritative = availability !== "unreadable";
+    let services = [];
+    if (configured && authoritative) {
+        try {
+            services = Object.entries(await read())
+                .filter(([, state]) => state.connected)
+                .map(([slug]) => slug);
+        }
+        catch {
+            authoritative = false;
+        }
+    }
+    return { configured, authoritative, services };
+}
+/** Whether this bot could use connected apps at all: apps on for the bot,
+ * a connector configured, and an engine that mounts the Composio MCP. */
+function couldUseApps(facts) {
+    return facts.bot.composio !== false && facts.connectedApps.configured && Boolean(facts.engine?.composioMcp);
+}
+function computerReach(computer) {
+    switch (computer) {
+        case "cloud":
+            return "Computer preference: cloud computer.";
+        case "vm":
+            return "Computer preference: Local VM.";
+        case "local":
+            return "Computer preference: this computer.";
+        case "browser":
+            return "Computer preference: browser only.";
+        case "off":
+            return null;
+        default:
+            return "Computer preference: Auto; availability is checked when a task starts.";
+    }
+}
+function reachesLines(facts) {
+    const lines = [];
+    const computer = computerReach(facts.bot.computer);
+    if (computer)
+        lines.push(computer);
+    lines.push(facts.bot.cwd ? `Works in ${facts.bot.cwd}.` : "Works in its private workspace.");
+    const apps = facts.connectedApps;
+    // Only a bot that could actually use apps gets an apps line here. When it
+    // could, the inventory decides: verified and non-empty → list them;
+    // unverified → say so rather than guess either way.
+    if (couldUseApps(facts) && apps.authoritative && apps.services.length > 0) {
+        const count = apps.services.length;
+        lines.push(`Can use ${count} connected app${count === 1 ? "" : "s"}: ${apps.services.join(", ")}.`);
+    }
+    else if (couldUseApps(facts) && !apps.authoritative) {
+        lines.push("Connected apps could not be checked.");
+    }
+    if (facts.browserEnabled && facts.engine?.browserMcp && facts.bot.browser !== false && facts.bot.computer !== "off")
+        lines.push("Has the built-in browser.");
+    if (facts.engine?.agentsMcp && facts.sectionPeers > 0 && facts.bot.peers?.length !== 0) {
+        lines.push(`Can talk to ${facts.sectionPeers} other bot${facts.sectionPeers === 1 ? "" : "s"} in its section.`);
+    }
+    if (facts.bot.chiefOfStaff)
+        lines.push("Coordinates its section as Chief of Staff.");
+    return lines;
+}
+function wontLines(facts) {
+    const lines = [];
+    const mode = approvalModeFor(facts.bot);
+    if (mode === "ask")
+        lines.push("Command approvals use Ask mode; saved permissions and provider rules still apply.");
+    if (mode === "custom")
+        lines.push("Command approvals follow the provider's custom configuration.");
+    if (facts.bot.peers?.length === 0)
+        lines.push("Cannot initiate contact with other bots.");
+    else if (facts.bot.approvePeerComms)
+        lines.push("Asks before contacting other bots.");
+    // "Has no connected apps." is definite when apps are off for this bot,
+    // not configured, or unsupported by its engine — no inventory needed. Only
+    // the "configured but nothing connected" case rests on the inventory, so
+    // only that case requires it to be authoritative.
+    if (!couldUseApps(facts) || (facts.connectedApps.authoritative && facts.connectedApps.services.length === 0)) {
+        lines.push("Has no connected apps.");
+    }
+    if (facts.bot.computer === "off")
+        lines.push("Can't use a computer.");
+    if (!facts.routines.some((routine) => routine.enabled))
+        lines.push("Won't act on a schedule.");
+    lines.push("Profile proposal cards require your approval.");
+    return lines;
+}
+export function buildBotOverview(facts) {
+    return {
+        who: {
+            name: facts.bot.name,
+            title: facts.bot.title,
+            blurb: facts.bot.description,
+            soulLead: soulLead(facts.bot.soul),
+        },
+        does: doesLines(facts),
+        reaches: reachesLines(facts),
+        wont: wontLines(facts),
+        recent: facts.recent,
+    };
+}

package/dist-server/server/bot-package.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { schemaIssue } from "./schema.js";
+import { BOT_PROFILE_LIMITS } from "../shared/bot-profile.js";
 export const BOT_PACKAGE_FORMAT = "openmaus.package";
 export const BOT_PACKAGE_VERSION = 1;
 export const BOTMRR_MARKDOWN_VERSION = 1;
@@ -57,6 +58,9 @@ const packageSchema = z.object({
             name: requiredText(100),
             title: optionalText(200),
             description: optionalText(4_000),
+            soul: z.string().refine((value) => Buffer.byteLength(value, "utf8") <= BOT_PROFILE_LIMITS.soul, {
+                error: "standing instructions must be at most 24000 bytes",
+            }).optional(),
             appearance: z.object({
                 color: z.enum(COLORS, { error: "is not supported" }),
                 mascotExpression: optionalText(80),
@@ -259,6 +263,7 @@ export function packageAgentAsMember(agent) {
         name: agent.name,
         title: agent.title ?? "",
         description: agent.description ?? "",
+        ...(agent.soul !== undefined ? { soul: agent.soul } : {}),
         appearance: {
             color: agent.appearance.color,
             ...(agent.appearance.mascotExpression ? { mascotExpression: agent.appearance.mascotExpression } : {}),

package/dist-server/server/bot-profile.js

@@ -21,6 +21,7 @@ export const BOT_PROFILE_PATCH_FIELDS = [
     "name",
     "title",
     "description",
+    "soul",
     "notifications",
     "avatarUrl",
     "avatarCrop",
@@ -44,6 +45,12 @@ const profilePatchSchema = z.object({
         .string({ error: "description must be a string" })
         .max(BOT_PROFILE_LIMITS.description, { error: "description must be at most 4000 characters" })
         .optional(),
+    soul: z
+        .string({ error: "soul must be a string" })
+        .refine((value) => Buffer.byteLength(value, "utf8") <= BOT_PROFILE_LIMITS.soul, {
+        error: "standing instructions must be at most 24000 bytes",
+    })
+        .optional(),
     notifications: z.boolean({ error: "notifications must be true or false" }).optional(),
     avatarUrl: z
         .union([botAvatarUrlSchema, z.literal(""), z.null()], {

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;
+    }
+}