openmausbot 0.1.55

package/dist-server/server/cli.js

@@ -0,0 +1,524 @@
+// `openmausbot` on the command line: run the server anywhere and pair devices
+// to it. One implementation for three homes — `npx openmausbot` (the npm
+// package), `node dist-server/cli.js` (the container image) and
+// `pnpm omb` (a checkout) — because scripts/bundle-server.mjs bundles this
+// file next to the server.
+//
+//   openmausbot serve [--port 8799] [--data-dir ~/.openmausbot] [--label "cab mini"]
+//                     [--public-url https://host] [--tailscale | --tunnel] [--no-pair]
+//   openmausbot pair  [--label "My MacBook"] [--client] [--public-url https://host]
+//   openmausbot sessions [revoke <id>]
+//   openmausbot status
+//   openmausbot login [--email you@example.com]
+//   openmausbot logout
+//
+// `serve` starts the server, waits for it, and prints a pairing link with a
+// QR code: scan it with the phone or open it on a laptop. `--tailscale` asks
+// Tailscale to terminate HTTPS for it and uses the MagicDNS name in the link.
+// `--tunnel` (after `login`) serves at a public https://….openmausbot.com
+// address through a Cloudflare tunnel: no domain, no proxy, no open port.
+//
+// This module only exports; openmausbot.ts is the entry that runs main(), so
+// bundling this file into other entries (pair-cli.ts) never runs it twice.
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+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 { 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"];
+export function parseArgs(argv, env = process.env) {
+    const [command = "help", ...rest] = argv;
+    if (!COMMANDS.includes(command)) {
+        return { error: `unknown command "${command}"` };
+    }
+    const options = {
+        command: command === "--help" || command === "-h" ? "help" : command,
+        port: Number(env.OMB_PORT || 8799),
+        dataDir: env.OMB_DATA_DIR || join(homedir(), ".openmausbot"),
+        tailscale: false,
+        tunnel: false,
+        client: false,
+        pair: true,
+        json: false,
+    };
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        const value = () => {
+            const v = rest[i + 1];
+            if (v === undefined || v.startsWith("--"))
+                throw new Error(`${arg} needs a value`);
+            i += 1;
+            return v;
+        };
+        try {
+            if (arg === "--port")
+                options.port = Number(value());
+            else if (arg === "--data-dir")
+                options.dataDir = resolve(value());
+            else if (arg === "--label")
+                options.label = value();
+            else if (arg === "--public-url")
+                options.publicUrl = value().replace(/\/+$/, "");
+            else if (arg === "--tailscale")
+                options.tailscale = true;
+            else if (arg === "--tunnel")
+                options.tunnel = true;
+            else if (arg === "--client")
+                options.client = true;
+            else if (arg === "--no-pair")
+                options.pair = false;
+            else if (arg === "--json")
+                options.json = true;
+            else if (arg === "--email")
+                options.email = value();
+            else if (options.command === "sessions" && arg === "revoke")
+                options.revoke = value();
+            else
+                return { error: `unknown argument "${arg}"` };
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65_535)
+        return { error: "--port must be 1-65535" };
+    if (options.publicUrl && !/^https?:\/\//.test(options.publicUrl))
+        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)" };
+    return options;
+}
+export const USAGE = `openmausbot — run the server anywhere, pair devices to it
+
+  openmausbot serve [--port 8799] [--data-dir DIR] [--label NAME]
+                    [--public-url https://host] [--tailscale | --tunnel] [--no-pair]
+  openmausbot pair  [--label NAME] [--client] [--public-url https://host]
+  openmausbot sessions [revoke ID]
+  openmausbot status
+  openmausbot login [--email you@example.com]
+  openmausbot logout
+
+serve   starts the server and prints a pairing link + QR code
+pair    mints a pairing code against a running server (--client: chat only)
+sessions lists paired devices; "sessions revoke ID" signs one out
+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
+
+--tailscale  serve over your tailnet: Tailscale terminates HTTPS and the
+             link uses this machine's MagicDNS name (needs Tailscale signed in
+             and HTTPS certificates enabled for the tailnet)
+--tunnel     serve at a public https://….openmausbot.com address through a
+             Cloudflare tunnel: no domain, no proxy, no open port. Run
+             \`openmausbot login\` once on this machine first.
+`;
+export function defaultIo() {
+    return {
+        log: (line) => console.log(line),
+        error: (line) => console.error(line),
+        ask: async (question) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                return await rl.question(question);
+            }
+            finally {
+                rl.close();
+            }
+        },
+    };
+}
+/** The version this command ships with: package.json is one level up in the
+ * npm package (dist-server/), the image and a checkout (server/). */
+export function serverVersion(here = HERE) {
+    try {
+        const parsed = JSON.parse(readFileSync(resolve(here, "..", "package.json"), "utf8"));
+        const version = typeof parsed === "object" && parsed !== null ? Reflect.get(parsed, "version") : undefined;
+        return typeof version === "string" && version ? version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const message = (error) => (error instanceof Error ? error.message : String(error));
+// ── talking to a running server (loopback = owner) ────────────────────
+async function api(port, path, init = {}) {
+    const res = await fetch(`http://127.0.0.1:${port}${path}`, { method: init.method, body: init.body, headers: { "content-type": "application/json" } });
+    const body = await res.json().catch(() => ({}));
+    return { status: res.status, body };
+}
+async function serverUp(port) {
+    try {
+        const { status } = await api(port, "/api/health");
+        return status === 200;
+    }
+    catch {
+        return false;
+    }
+}
+/** The pairing link a device opens, rendered as text and a QR code. */
+export function pairingBlock(input) {
+    const lines = [`pairing code:  ${input.code}`, `expires:       ${new Date(input.expiresAt).toLocaleTimeString()} (single use)`];
+    if (input.url) {
+        lines.push(`open or scan:  ${input.url}`);
+        lines.push("");
+        lines.push(qrToString(input.url));
+    }
+    else {
+        lines.push(`open:          /pair on the address you use for this server, and type the code`);
+        if (input.hint)
+            lines.push(`               (${input.hint})`);
+    }
+    return lines.join("\n");
+}
+export function qrToString(text) {
+    let out = "";
+    qrcode.generate(text, { small: true }, (rendered) => {
+        out = rendered;
+    });
+    return out;
+}
+async function mintPairing(port, options) {
+    const request = {};
+    if (options.label)
+        request.label = options.label;
+    if (options.client)
+        request.scopes = ["client"];
+    const { status, body } = await api(port, "/api/auth/pairing", { method: "POST", body: JSON.stringify(request) });
+    if (status !== 200)
+        throw new Error(`server refused to mint a pairing code: ${typeof body?.error === "string" ? body.error : status}`);
+    const url = options.publicUrl ? `${options.publicUrl}/pair#code=${body.code}` : typeof body.url === "string" ? body.url : null;
+    return pairingBlock({ code: body.code, url, expiresAt: body.expiresAt, hint: typeof body.hint === "string" ? body.hint : null });
+}
+// ── commands ───────────────────────────────────────────────────────────
+export async function runPair(options) {
+    if (!(await serverUp(options.port))) {
+        console.error(`no OpenMausBot server on http://127.0.0.1:${options.port}; start one with \`openmausbot serve\` or set OMB_PORT`);
+        return 1;
+    }
+    console.log(await mintPairing(options.port, { label: options.label, client: options.client, publicUrl: options.publicUrl }));
+    if (options.client)
+        console.log("(client scope: chat and approvals only; cannot change settings or pair others)");
+    return 0;
+}
+export async function runSessions(options) {
+    if (!(await serverUp(options.port))) {
+        console.error(`no OpenMausBot server on http://127.0.0.1:${options.port}`);
+        return 1;
+    }
+    if (options.revoke) {
+        const { status, body } = await api(options.port, `/api/auth/sessions/${encodeURIComponent(options.revoke)}`, { method: "DELETE" });
+        if (status !== 200) {
+            console.error(`could not revoke: ${typeof body?.error === "string" ? body.error : status}`);
+            return 1;
+        }
+        console.log(`revoked ${options.revoke}: that device is signed out and its stream is closed`);
+        return 0;
+    }
+    const { body } = await api(options.port, "/api/auth/sessions");
+    const sessions = Array.isArray(body?.sessions) ? body.sessions : [];
+    if (options.json) {
+        console.log(JSON.stringify(sessions, null, 2));
+        return 0;
+    }
+    if (!sessions.length) {
+        console.log("no paired devices yet: run `openmausbot pair`");
+        return 0;
+    }
+    console.log(formatSessions(sessions));
+    return 0;
+}
+export function formatSessions(sessions, now = Date.now()) {
+    const age = (ms) => {
+        const m = Math.max(0, Math.floor((now - ms) / 60_000));
+        return m < 1 ? "just now" : m < 60 ? `${m} min ago` : m < 1440 ? `${Math.round(m / 60)} h ago` : `${Math.round(m / 1440)} d ago`;
+    };
+    const rows = sessions.map((s) => [s.id, s.label || "(unnamed)", s.scopes.includes("admin") ? "admin" : "client", age(s.lastSeenAt), new Date(s.expiresAt).toISOString().slice(0, 10)]);
+    const head = ["id", "device", "scope", "last seen", "expires"];
+    const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    const line = (r) => r.map((c, i) => c.padEnd(widths[i])).join("  ");
+    return [line(head), ...rows.map(line), "", "revoke one with: openmausbot sessions revoke <id>"].join("\n");
+}
+export async function runStatus(options, io = defaultIo()) {
+    let code = 0;
+    try {
+        const res = await fetch(`http://127.0.0.1:${options.port}/.well-known/openmausbot/environment`);
+        const body = await res.json();
+        io.log(options.json ? JSON.stringify(body, null, 2) : `${body.label} · OpenMausBot ${body.version} on ${body.platform} · id ${body.environmentId}`);
+    }
+    catch {
+        io.error(`no OpenMausBot server on http://127.0.0.1:${options.port}`);
+        code = 1;
+    }
+    if (!options.json) {
+        const account = describeTunnelAccount(createTunnelAccount({ dataDir: options.dataDir, version: serverVersion() }).credentials.read());
+        if (account.address)
+            io.log(`public address: ${account.address} (signed in as ${account.email ?? "?"}; serve it with --tunnel)`);
+    }
+    return code;
+}
+export async function runLogin(options, io = defaultIo()) {
+    const account = createTunnelAccount({ dataDir: options.dataDir, version: serverVersion() });
+    if (account.credentials.status === "unavailable") {
+        io.error(`${account.credentials.file} exists but could not be read; fix or remove it, then try again`);
+        return 1;
+    }
+    if (!account.controlPlane) {
+        io.error("OMB_CONTROL_PLANE_URL is set but is not an https address");
+        return 1;
+    }
+    const existing = describeTunnelAccount(account.credentials.read());
+    if (existing.address)
+        io.log(`already signed in as ${existing.email ?? "?"} (${existing.address}); signing in again refreshes it`);
+    const email = (options.email ?? (await io.ask("Email for your OpenMausBot account: "))).trim();
+    if (!email) {
+        io.error("an email address is needed: openmausbot login --email you@example.com");
+        return 1;
+    }
+    try {
+        await account.service.requestCode(email);
+    }
+    catch (error) {
+        io.error(`could not send a sign-in code: ${message(error)}`);
+        return 1;
+    }
+    const code = (await io.ask(`Enter the 8-digit code we emailed to ${email}: `)).trim();
+    let state;
+    try {
+        state = await account.service.verifyCode(email, code);
+    }
+    catch (error) {
+        io.error(`sign-in failed: ${message(error)}`);
+        return 1;
+    }
+    const signedIn = describeTunnelAccount(account.credentials.read());
+    if (!signedIn.address) {
+        io.error(`signed in, but no public address was issued${state.message ? `: ${state.message}` : ""}`);
+        return 1;
+    }
+    io.log(`Signed in as ${signedIn.email ?? email}.`);
+    io.log(`This machine's public address: ${signedIn.address}`);
+    io.log("Serve there with:  openmausbot serve --tunnel");
+    return 0;
+}
+export async function runLogout(options, io = defaultIo()) {
+    const account = createTunnelAccount({ dataDir: options.dataDir, version: serverVersion() });
+    const before = describeTunnelAccount(account.credentials.read());
+    if (!before.email) {
+        io.log("this machine is not signed in");
+        return 0;
+    }
+    let state;
+    try {
+        state = await account.service.signOut();
+    }
+    catch (error) {
+        io.error(`sign-out failed: ${message(error)}`);
+        return 1;
+    }
+    const after = describeTunnelAccount(account.credentials.read());
+    if (after.email) {
+        io.error(`still signed in${state.message ? `: ${state.message}` : ""}`);
+        return 1;
+    }
+    io.log(`Signed out ${before.email}${before.address ? `; ${before.address} is released` : ""}.`);
+    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. */
+export function serverEntry(here = HERE) {
+    const bundled = join(here, "index.js");
+    const root = resolve(here, "..");
+    if (existsSync(bundled)) {
+        const staticDir = [join(root, "dist"), join(here, "..", "ui")].find((d) => existsSync(join(d, "index.html"))) ?? null;
+        const skillsDir = existsSync(join(root, "skills")) ? join(root, "skills") : null;
+        return { command: process.execPath, args: [bundled], staticDir, skillsDir };
+    }
+    const source = join(here, "index.ts");
+    const staticDir = existsSync(join(root, "dist", "index.html")) ? join(root, "dist") : null;
+    return { command: process.execPath, args: ["--experimental-strip-types", source], staticDir, skillsDir: existsSync(join(root, "skills")) ? join(root, "skills") : null };
+}
+/** Everything `--tunnel` needs before the server starts, or the one reason
+ * it cannot have it. Fails closed: no silent fallback to a local-only server. */
+async function planTunnel(options, log) {
+    const account = createTunnelAccount({ dataDir: options.dataDir, version: serverVersion() });
+    if (account.credentials.status === "unavailable")
+        return { error: `${account.credentials.file} exists but could not be read; fix or remove it` };
+    if (!describeTunnelAccount(account.credentials.read()).email) {
+        return { error: "no account on this machine yet: run `openmausbot login` first, then `openmausbot serve --tunnel`" };
+    }
+    // A fresh connector token when the control plane answers; the saved one otherwise.
+    try {
+        const state = await account.service.retry();
+        if (state.message && !tunnelAccess(account.credentials.read()))
+            log(`tunnel: ${state.message}`);
+    }
+    catch (error) {
+        log(`tunnel: control plane not reachable right now (${message(error)}); using the saved address`);
+    }
+    const access = tunnelAccess(account.credentials.read());
+    if (!access)
+        return { error: "this machine has no public address; run `openmausbot login` again" };
+    let binary;
+    try {
+        binary = await ensureCloudflared({ dataDir: options.dataDir, log });
+    }
+    catch (error) {
+        return { error: `--tunnel: ${message(error)}` };
+    }
+    const guardian = guardianEntry();
+    if (!guardian)
+        return { error: "--tunnel: the connector guardian is missing from this install" };
+    return { access, binary, guardian, origin: createTunnelOrigin() };
+}
+export async function runServe(options, log = console.log) {
+    if (await serverUp(options.port)) {
+        console.error(`something already answers on http://127.0.0.1:${options.port}; use \`openmausbot pair\` against it, or --port for a second server`);
+        return 1;
+    }
+    let publicUrl = options.publicUrl;
+    let tailscale = null;
+    if (options.tailscale) {
+        const probe = await tailscaleStatus();
+        if ("failure" in probe) {
+            console.error(`--tailscale: ${explainTailscaleFailure(probe.failure)}`);
+            return 1;
+        }
+        tailscale = probe.status;
+    }
+    let plan = null;
+    if (options.tunnel) {
+        const planned = await planTunnel(options, log);
+        if ("error" in planned) {
+            console.error(planned.error);
+            return 1;
+        }
+        plan = planned;
+        if (publicUrl && publicUrl !== plan.access.endpoint)
+            log(`note: --public-url is ignored with --tunnel; the address is ${plan.access.endpoint}`);
+        publicUrl = plan.access.endpoint;
+    }
+    const entry = serverEntry();
+    if (!entry.staticDir)
+        log("note: no built UI found next to the server; the API runs but browsers get no page (build with `pnpm exec vite build`)");
+    const env = {
+        ...process.env,
+        OMB_DATA_DIR: options.dataDir,
+        OMB_PORT: String(options.port),
+        OMB_WEBHOOK_PORT: process.env.OMB_WEBHOOK_PORT || String(options.port + 1),
+    };
+    if (entry.staticDir)
+        env.OMB_STATIC_DIR = entry.staticDir;
+    if (entry.skillsDir && !process.env.OMB_SKILLS_DIR)
+        env.OMB_SKILLS_DIR = entry.skillsDir;
+    if (options.label && !process.env.OMB_ENVIRONMENT_LABEL)
+        env.OMB_ENVIRONMENT_LABEL = options.label;
+    if (plan)
+        env.OMB_TUNNEL_SOCKET = plan.origin.socketPath;
+    if (tailscale) {
+        const served = await tailscaleServe(tailscale, options.port);
+        if ("failure" in served) {
+            console.error(`--tailscale: ${explainTailscaleFailure(served.failure)}`);
+            return 1;
+        }
+        publicUrl = served.origin;
+        log(`tailscale: serving https://${tailscale.dnsName} → http://127.0.0.1:${options.port} (only your tailnet can reach it)`);
+    }
+    if (publicUrl)
+        env.OMB_PUBLIC_URL = publicUrl;
+    const child = spawn(entry.command, entry.args, { env, stdio: ["ignore", "inherit", "inherit"] });
+    let exited = null;
+    child.on("exit", (code) => {
+        exited = code ?? 1;
+    });
+    let tunnel = null;
+    let stopping = null;
+    const stop = () => {
+        stopping ??= (async () => {
+            // The gateway stops accepting before the server it forwards to goes away.
+            if (tunnel)
+                await tunnel.stop().catch(() => undefined);
+            if (tailscale)
+                await tailscaleServeOff(tailscale).catch(() => undefined);
+            if (exited === null)
+                child.kill("SIGTERM");
+            if (plan)
+                cleanupTunnelOrigin(plan.origin);
+        })();
+        return stopping;
+    };
+    process.on("SIGINT", () => void stop());
+    process.on("SIGTERM", () => void stop());
+    const deadline = Date.now() + 60_000;
+    while (Date.now() < deadline && exited === null) {
+        if (await serverUp(options.port))
+            break;
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    if (exited !== null) {
+        if (plan)
+            cleanupTunnelOrigin(plan.origin);
+        return exited;
+    }
+    if (!(await serverUp(options.port))) {
+        console.error("the server did not answer within a minute; see its output above");
+        await stop();
+        return 1;
+    }
+    if (plan && child.pid) {
+        tunnel = startTunnel({
+            dataDir: options.dataDir,
+            access: plan.access,
+            originTarget: { pid: child.pid, socketPath: plan.origin.socketPath },
+            binaryPath: plan.binary,
+            guardian: plan.guardian,
+            onState: (state) => log(describeTunnelState(state, plan.access.endpoint)),
+        });
+        tunnel.started.catch((error) => log(`tunnel: ${message(error)}`));
+    }
+    log("");
+    log(`OpenMausBot is running on http://127.0.0.1:${options.port}${publicUrl ? `, reachable at ${publicUrl}` : ""}`);
+    log(`data: ${options.dataDir}`);
+    if (options.pair) {
+        log("");
+        log(await mintPairing(options.port, { label: options.label ? `${options.label} owner` : undefined, publicUrl: publicUrl ?? undefined }));
+        log("");
+        log("another device later:  openmausbot pair --label \"Kitchen iPad\"");
+    }
+    log("stop with Ctrl+C");
+    return await new Promise((resolveExit) => {
+        child.on("exit", (code) => {
+            void stop().finally(() => resolveExit(code ?? 0));
+        });
+    });
+}
+export async function main(argv = process.argv.slice(2)) {
+    const options = parseArgs(argv);
+    if ("error" in options) {
+        console.error(`${options.error}\n\n${USAGE}`);
+        return 2;
+    }
+    switch (options.command) {
+        case "serve":
+            return runServe(options);
+        case "pair":
+            return runPair(options);
+        case "sessions":
+            return runSessions(options);
+        case "status":
+            return runStatus(options);
+        case "login":
+            return runLogin(options);
+        case "logout":
+            return runLogout(options);
+        default:
+            console.log(USAGE);
+            return 0;
+    }
+}

package/dist-server/server/cloud-backend.js

@@ -0,0 +1,30 @@
+export const CLOUD_BACKEND_CHANGE_ERROR = "stop the active turn before changing the cloud backend";
+export const VPS_ALIAS_CHANGE_ERROR = "stop the active VPS turn before changing the SSH config alias";
+export const BOX_ACCOUNT_RESOURCES_ERROR = "remove this installation's cloud computers before changing or clearing the Box account";
+export const VPS_ALIAS_RESOURCES_ERROR = "remove this installation's VPS computers before changing or clearing the SSH config alias";
+export function cloudBackendChangeError(botBusy, activeVpsThread) {
+    return botBusy || activeVpsThread ? CLOUD_BACKEND_CHANGE_ERROR : null;
+}
+export function vpsAliasChangeError(currentAlias, nextAlias, activeVpsThread) {
+    return activeVpsThread && currentAlias !== nextAlias ? VPS_ALIAS_CHANGE_ERROR : null;
+}
+/** An old Box account may be detached only when it owns no local resources.
+ * Token rotation is safe when the replacement credential proves access to
+ * the exact same provider identities. */
+export function boxAccountResourceChangeError(current, replacement) {
+    if (current.length === 0)
+        return null;
+    if (!replacement || replacement.length !== current.length)
+        return BOX_ACCOUNT_RESOURCES_ERROR;
+    const identities = (rows) => rows
+        .map(({ boxId, name }) => `${boxId}\u0000${name}`)
+        .sort();
+    const currentIdentities = identities(current);
+    const replacementIdentities = identities(replacement);
+    return currentIdentities.every((identity, index) => identity === replacementIdentities[index])
+        ? null
+        : BOX_ACCOUNT_RESOURCES_ERROR;
+}
+export function vpsAliasResourceChangeError(instanceCount) {
+    return instanceCount > 0 ? VPS_ALIAS_RESOURCES_ERROR : null;
+}

package/dist-server/server/comms-visibility.js

@@ -0,0 +1,109 @@
+// Bot⇄bot comms visibility: channel creation, message mirroring, and
+// per-thread chips. Extracted from /api/internal/ask-bot so delegations
+// (delegate_bot) and any future peer flow reuse the same UX without a copy.
+import { sectionKey } from "./store.js";
+/** Find or create the channel for a peer exchange. When an originating
+ * group is supplied and both bots are members, the exchange is mirrored
+ * back into that group. Otherwise the pair's DM is used (creating it if
+ * necessary) so 1:1-bot-thread delegations keep their historical fallback. */
+export function getOrCreateChannel(store, from, target, originatingGroup) {
+    if (originatingGroup &&
+        !originatingGroup.dm &&
+        originatingGroup.memberIds.includes(from.id) &&
+        originatingGroup.memberIds.includes(target.id)) {
+        return originatingGroup;
+    }
+    const existing = store.dmGroup(from.id, target.id);
+    if (existing) {
+        if (sectionKey(existing.section) !== sectionKey(from.section)) {
+            return store.patchGroup(existing.id, { section: from.section }) ?? existing;
+        }
+        return existing;
+    }
+    return store.createGroup(`${from.name} ⇄ ${target.name}`, [from.id, target.id], true, from.section);
+}
+/** Whether this mirror is worth a badge, and the group frame either way.
+ *
+ * A pair channel is the bots' own coordination: the person asked ONE bot,
+ * and the hops behind its answer are that bot's work, not mail addressed to
+ * them. Badging every hop turned the sidebar, the dock and the phone into a
+ * running commentary on chatter nobody asked to watch. What is NOT withheld
+ * is the record — the messages and chips above are already written, and the
+ * frame still goes out so the channel keeps its place in every client's
+ * list. Hidden bot-to-bot talk is where a prompt injection would propagate
+ * unobserved; silence the alert, never the record. A shared room is the
+ * other case: people are reading it, so it badges as it always has. */
+function markMirrored(bus, channel, notify) {
+    const patch = {};
+    if (notify ?? !channel.dm)
+        patch.unread = true;
+    bus.store.patchGroup(channel.id, patch);
+}
+/** Mirror `from`'s outgoing message into the channel and drop chips into
+ * both 1:1 threads linking to the channel. The chips are what make
+ * bot-to-bot turns observable — those turns cost the user tokens, and a
+ * hidden exchange is exactly the kind of mistake peer coordination is
+ * supposed to avoid. `notify` decides only whether the channel also raises
+ * a badge; it defaults to off for a bot⇄bot pair channel. */
+export function mirrorExchange(bus, from, target, message, channel, sourceThreadId = from.threadId, notify) {
+    const note = (threadId, m) => {
+        bus.store.appendMessage(threadId, m);
+        return message;
+    };
+    if (channel) {
+        note(channel.threadId, {
+            role: "bot",
+            kind: "text",
+            text: message,
+            from: { botId: from.id, name: from.name, color: from.color },
+        });
+    }
+    note(sourceThreadId, {
+        role: "bot",
+        kind: "activity",
+        tool: { name: `Messaged @${target.name}` },
+        comm: channel
+            ? { groupId: channel.id, withBotId: target.id, withName: target.name, withColor: target.color }
+            : undefined,
+    });
+    note(target.threadId, {
+        role: "bot",
+        kind: "activity",
+        tool: { name: `Message from @${from.name}` },
+        comm: channel
+            ? { groupId: channel.id, withBotId: from.id, withName: from.name, withColor: from.color }
+            : undefined,
+    });
+    if (channel)
+        markMirrored(bus, channel, notify);
+}
+/** Mirror `target`'s reply into the channel so the channel stays the
+ * single authoritative record of the exchange. The 1:1 threads already
+ * carry their own chips from `mirrorExchange`. */
+export function mirrorReply(bus, target, reply, channel, notify) {
+    if (!channel || !reply.trim())
+        return;
+    bus.store.appendMessage(channel.threadId, {
+        role: "bot",
+        kind: "text",
+        text: reply,
+        from: { botId: target.id, name: target.name, color: target.color },
+    });
+    markMirrored(bus, channel, notify);
+}
+/** Mirror a terminal activity note into the channel — for async handoffs
+ * whose terminal state is not a reply (turn failed, was stopped, or never
+ * started). Prior art (A2A, MCP Tasks) is unanimous that every terminal
+ * state of an async handoff should be visible where the human is looking,
+ * and the channel is that place. */
+export function mirrorActivity(bus, from, channel, name, ok, notify) {
+    if (!channel)
+        return;
+    bus.store.appendMessage(channel.threadId, {
+        role: "bot",
+        kind: "activity",
+        tool: { name, ok },
+        from: { botId: from.id, name: from.name, color: from.color },
+    });
+    markMirrored(bus, channel, notify);
+}