openmausbot 0.1.55

package/dist-server/server/tts/speech-text.js

@@ -0,0 +1,195 @@
+// The spoken register — turning an agent's answer into something worth
+// hearing.
+//
+// Agents write for a screen: fenced code, file paths, tables, link soup,
+// bullet scaffolding. Read aloud verbatim that is unbearable — a 40-line
+// diff becomes four minutes of punctuation, and `server/drivers/acp/core.ts`
+// becomes "server slash drivers slash a c p slash core dot t s".
+//
+// So every string is passed through here before it reaches a voice. The
+// rule is: say the prose, name the artifacts, drop the syntax. A code block
+// becomes "a code block" — the user is looking at the screen if they care,
+// and this is the half of the feature that decides whether it is pleasant.
+//
+// Pure and synchronous on purpose: it is the piece most likely to need
+// tuning against real transcripts, so it stays trivially testable.
+/** A fenced block becomes a mention of itself, with its language if known. */
+function describeCodeBlock(fence) {
+    const lang = fence.trim().split(/\s+/)[0]?.replace(/[^a-z0-9+#]/gi, "") ?? "";
+    const spoken = {
+        ts: "TypeScript",
+        tsx: "TypeScript",
+        js: "JavaScript",
+        jsx: "JavaScript",
+        py: "Python",
+        sh: "shell",
+        bash: "shell",
+        zsh: "shell",
+        json: "JSON",
+        yml: "YAML",
+        yaml: "YAML",
+        sql: "SQL",
+        rs: "Rust",
+        go: "Go",
+        swift: "Swift",
+        diff: "diff",
+    };
+    const name = spoken[lang.toLowerCase()];
+    return name ? `. (a ${name} code block) ` : ". (a code block) ";
+}
+/** `a/b/c/file.ts` → `file.ts`. A path's directories are for the eye. */
+function shortenPaths(text) {
+    return text.replace(/(?:[\w.@-]+\/){1,}([\w.-]+\.\w{1,6})\b/g, "$1");
+}
+/** Trailing punctuation that already ends a sentence. */
+const ENDS_SENTENCE = /[.!?:;]\s*$/;
+/**
+ * Markdown (or any agent output) → a line a voice can read.
+ *
+ * Not a markdown parser: a sequence of narrow, ordered replacements, which
+ * is both fast enough to run per token-flush and easy to reason about when
+ * one of them misfires on a real transcript.
+ */
+export function speakable(input) {
+    if (!input)
+        return "";
+    let text = input;
+    // fenced code first — everything inside must survive none of the rules below
+    text = text.replace(/```([^\n]*)\n[\s\S]*?(?:```|$)/g, (_m, fence) => describeCodeBlock(fence));
+    text = text.replace(/~~~([^\n]*)\n[\s\S]*?(?:~~~|$)/g, (_m, fence) => describeCodeBlock(fence));
+    // images before links — the syntax differs by one character
+    text = text.replace(/!\[([^\]]*)\]\([^)]*\)/g, (_m, alt) => (alt ? `. (image: ${alt}) ` : ". (an image) "));
+    // [label](url) → label; a bare url becomes a noun rather than an alphabet soup
+    text = text.replace(/\[([^\]]+)\]\([^)]*\)/g, "$1");
+    text = text.replace(/<https?:\/\/[^>\s]+>/g, " a link ");
+    text = text.replace(/\bhttps?:\/\/\S+/g, " a link ");
+    // tables: a grid is hopeless aloud, and the separator row is pure noise
+    text = text.replace(/^\s*\|?[\s:-]*\|[\s|:-]*$/gm, "");
+    text = text.replace(/^\s*\|(.+)\|\s*$/gm, (_m, row) => row
+        .split("|")
+        .map((cell) => cell.trim())
+        .filter(Boolean)
+        .join(", "));
+    // inline code: keep short identifiers (they carry meaning), drop long ones
+    text = text.replace(/`([^`\n]+)`/g, (_m, code) => (code.length <= 40 ? code : " that snippet "));
+    // headings become sentences so the voice pauses instead of running on
+    text = text.replace(/^\s{0,3}#{1,6}\s+(.*)$/gm, (_m, head) => ENDS_SENTENCE.test(head) ? head : `${head.trim()}.`);
+    // list scaffolding: the marker is visual, the pause is what matters
+    text = text.replace(/^\s*[-*+]\s+/gm, "");
+    text = text.replace(/^\s*\d+[.)]\s+/gm, "");
+    text = text.replace(/^\s*>\s?/gm, "");
+    text = text.replace(/^\s*(?:[-*_]\s*){3,}$/gm, "");
+    // emphasis / strikethrough markers
+    text = text.replace(/(\*\*|__)(.*?)\1/g, "$2");
+    text = text.replace(/(\*|_)(?=\S)(.*?)(?<=\S)\1/g, "$2");
+    text = text.replace(/~~(.*?)~~/g, "$1");
+    // checkboxes read as literal brackets otherwise
+    text = text.replace(/\[[ xX]\]\s*/g, "");
+    text = shortenPaths(text);
+    // emoji and the pictographic ranges: a voice either ignores them or,
+    // worse, announces them by name
+    text = text.replace(/[\u{1F000}-\u{1FAFF}\u{2600}-\u{27BF}\u{FE00}-\u{FE0F}\u{2190}-\u{21FF}\u{2B00}-\u{2BFF}]/gu, "");
+    // a blank line is a paragraph break — make it an audible one
+    text = text.replace(/\n{2,}/g, ". ");
+    text = text.replace(/\n/g, ". ");
+    // tidy the punctuation the substitutions above inevitably pile up
+    text = text.replace(/\s+/g, " ");
+    text = text.replace(/\s+([.,!?;:])/g, "$1");
+    text = text.replace(/(?:\.\s*){2,}/g, ". ");
+    text = text.replace(/,\s*\./g, ".");
+    text = text.trim();
+    // The paragraph→". " rule turns whitespace-only input into a lone full
+    // stop, which a synthesizer happily renders as a click. Nothing to say
+    // means nothing to send.
+    return /[\p{L}\p{N}]/u.test(text) ? text : "";
+}
+/** Sentence-ish boundary: `.`/`!`/`?` followed by space, but not inside a
+ * decimal, an ellipsis, or a common abbreviation. */
+const BOUNDARY = /(?<!\b(?:e\.g|i\.e|etc|vs|Dr|Mr|Mrs|Ms|No|approx))(?<![.\d])([.!?])(["')\]]*)\s+/g;
+/**
+ * Split speakable text into utterances a synthesizer can start on.
+ *
+ * Both tiers want this: cloud TTS charges and buffers per request, and the
+ * local model generates per utterance — so the unit of work is a sentence
+ * either way. Very short fragments are glued onto their neighbour, because
+ * a synthesizer given two words produces two words of flat, contextless
+ * prosody.
+ */
+export function toUtterances(input, { minChars = 12, maxChars = 320 } = {}) {
+    const text = speakable(input);
+    if (!text)
+        return [];
+    // Split on a sentinel, never on the whitespace itself: the boundary
+    // match consumes the trailing space, so splitting on " " would split
+    // every word in the text rather than every sentence.
+    const MARK = "\u0000";
+    const rough = text
+        .replace(BOUNDARY, `$1$2${MARK}`)
+        .split(MARK)
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const out = [];
+    for (const piece of rough) {
+        // a sentence longer than the cap is broken at a clause, never mid-word
+        const parts = piece.length <= maxChars ? [piece] : splitLong(piece, maxChars);
+        for (const part of parts) {
+            const prev = out[out.length - 1];
+            if (prev && (prev.length < minChars || part.length < minChars)) {
+                out[out.length - 1] = `${prev} ${part}`;
+            }
+            else {
+                out.push(part);
+            }
+        }
+    }
+    return out;
+}
+function splitLong(text, maxChars) {
+    const out = [];
+    let rest = text;
+    while (rest.length > maxChars) {
+        const window = rest.slice(0, maxChars);
+        // prefer a clause break, then any space; never cut a word in half
+        const at = Math.max(window.lastIndexOf(", "), window.lastIndexOf("; "), window.lastIndexOf(" — "));
+        const cut = at > maxChars / 2 ? at + 1 : window.lastIndexOf(" ");
+        if (cut <= 0)
+            break;
+        out.push(rest.slice(0, cut).trim());
+        rest = rest.slice(cut).trim();
+    }
+    if (rest)
+        out.push(rest);
+    return out;
+}
+/** A tool-activity chip as a spoken progress line ("reading core.ts").
+ * Returns null for chips not worth interrupting the ear for. */
+export function narrateTool(toolName) {
+    const name = toolName.replace(/^mcp__[^_]+__/, "").trim();
+    if (!name)
+        return null;
+    // the harness writes these as chips too; they are already spoken elsewhere
+    if (/^(auto-approved|error):/i.test(name))
+        return null;
+    const bare = name.toLowerCase();
+    const verbs = [
+        [/^(bash|shell|terminal|run_command|execute|computer_exec)$/, "running a command"],
+        [/^(read|read_file|view)$/, "reading a file"],
+        [/^(write|create_file)$/, "writing a file"],
+        [/^(edit|apply_patch|str_replace|multiedit)$/, "editing a file"],
+        [/^(grep|search|glob|find)$/, "searching"],
+        [/^(web_?search|websearch)$/, "searching the web"],
+        [/^(web_?fetch|fetch)$/, "reading a page"],
+        [/^screenshot$/, "looking at the screen"],
+        [/^(click|type_text|press_key|scroll|computer_batch)$/, "using the computer"],
+        [/^open_url$/, "opening a page"],
+        [/^list_bots$/, "checking who's around"],
+        [/^ask_bot$/, "asking a teammate"],
+    ];
+    for (const [pattern, phrase] of verbs) {
+        if (pattern.test(bare))
+            return phrase;
+    }
+    // an unrecognized tool still deserves a beat, but not its raw argv
+    const short = shortenPaths(name).slice(0, 40);
+    return /^[\w .:/-]+$/.test(short) ? `running ${short}` : null;
+}

package/dist-server/server/tts/system-voices.js

@@ -0,0 +1,74 @@
+// Built-in macOS speech synthesis — the zero-key voice provider.
+//
+// Calls and spoken replies work with no ElevenLabs account by using the
+// voices already installed on the Mac (`/usr/bin/say`, the same engine the
+// Spoken Content pane uses). Everything about driving `say` lives in this
+// file: listing voices, and turning one utterance into WAV bytes.
+//
+// It runs on the HARNESS for the same reason ElevenLabs does — one place to
+// spawn processes, one place that owns the utterance split — and the
+// renderer keeps playing opaque audio bytes, so it never learns or cares
+// which provider produced them.
+//
+// Platform-gated: `say` is a Darwin binary. Elsewhere the provider simply
+// never appears as an option, and the ElevenLabs path is unchanged.
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const SAY = "/usr/bin/say";
+const execFileAsync = promisify(execFile);
+export function systemVoicesAvailable(platform = process.platform) {
+    return platform === "darwin";
+}
+const defaultRun = (file, args, timeout) => execFileAsync(file, args, { timeout, maxBuffer: 4 * 1024 * 1024 });
+/** Parse `say -v ?` output. Lines look like:
+ * `Albert              en_US    # Hello! My name is Albert.`
+ * The header above the table is localized, so anything without the
+ * `name  lang  # sample` shape is ignored rather than parsed. */
+export function parseVoiceList(stdout) {
+    const voices = [];
+    for (const line of stdout.split("\n")) {
+        const match = /^(.+?)\s{2,}(\S+)\s+#\s*(.+)$/.exec(line.trimEnd());
+        if (!match)
+            continue;
+        const [, name, locale, sample] = match;
+        const id = name.trim();
+        if (!id)
+            continue;
+        voices.push({ id, label: id, description: `${locale} — ${sample.trim()}` });
+    }
+    return voices;
+}
+export async function listSystemVoices(run = defaultRun) {
+    try {
+        const { stdout } = await run(SAY, ["-v", "?"], 5_000);
+        return parseVoiceList(stdout);
+    }
+    catch {
+        return [];
+    }
+}
+/** Synthesize one utterance to 22 kHz mono WAV — small, and every browser
+ * plays it. `say` writes the container itself; no conversion step needed.
+ * The voice id is a system voice name; empty falls back to the system's
+ * own default, which is what a fresh Mac already sounds like. */
+export async function synthesizeSystem(text, voiceId, run = defaultRun) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return { bytes: new Uint8Array(), mime: "audio/wav" };
+    const dir = await mkdtemp(join(tmpdir(), "openmausbot-say-"));
+    const out = join(dir, "utterance.wav");
+    try {
+        const args = ["-o", out, "--data-format=LEI16@22050"];
+        if (voiceId?.trim())
+            args.push("-v", voiceId.trim());
+        args.push(trimmed);
+        await run(SAY, args, 30_000);
+        return { bytes: new Uint8Array(await readFile(out)), mime: "audio/wav" };
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}

package/dist-server/server/tunnel.js

@@ -0,0 +1,202 @@
+// Rung three of the hosting ladder: `openmausbot serve --tunnel` gives a
+// server a public HTTPS address (https://c-<id>.openmausbot.com) with no
+// domain, no proxy and no open port, through the same control plane and
+// Cloudflare tunnel the desktop app already uses. Headless, so:
+//
+//   - the account and connector credentials live in a 0600 JSON file under
+//     the data dir instead of the OS keychain (a server has none; a key kept
+//     next to the ciphertext would be theatre), and its mode is re-tightened
+//     on every open;
+//   - cloudflared is fetched once into the data dir, by the same pinned
+//     version + digest script the release build uses, when nothing usable is
+//     on the machine;
+//   - the tunnel's loopback gateway forwards to an IPC listener the harness
+//     opens for it (OMB_TUNNEL_SOCKET), so to request-auth every public
+//     request is "through a proxy" by construction and needs a paired
+//     session — the loopback bind and its owner trust are untouched.
+//
+// Everything network- and process-shaped is the desktop's own code
+// (electron/control-plane-client.mjs, companion-account-service.mjs,
+// managed-companion-tunnel.mjs and the connector guardian): one
+// implementation, so a fix lands in both.
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { COMPANION_ACCOUNT_EMAIL_FIELD, COMPANION_INSTALLATION_ID_FIELD, createCompanionAccountService, resolveCompanionControlPlaneURL, } from "../electron/companion-account-service.mjs";
+import { cleanupCompanionOriginEndpoint, createCompanionOriginEndpoint, MANAGED_COMPANION_ORIGIN_PORT, } from "../electron/companion-origin-gateway.mjs";
+import { createControlPlaneClient } from "../electron/control-plane-client.mjs";
+import { createManagedCompanionTunnel, managedCompanionTunnelAccess, resolveCloudflaredBinary, } from "../electron/managed-companion-tunnel.mjs";
+import { createSecureCredentialState } from "../electron/secure-credential-state.mjs";
+import { writeFileAtomic } from "./atomic.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const TUNNEL_CREDENTIALS_FILE = "tunnel-account.json";
+export const TUNNEL_RUNTIME_DIR = "tunnel-runtime";
+function plainDocument(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const document = {};
+    for (const [key, entry] of Object.entries(value))
+        document[key] = entry;
+    return document;
+}
+export function openTunnelCredentials(dataDir) {
+    const file = join(dataDir, TUNNEL_CREDENTIALS_FILE);
+    let initial = {};
+    let status = "empty";
+    if (existsSync(file)) {
+        try {
+            // A file someone loosened (or an old umask) is tightened, not trusted as is.
+            if (process.platform !== "win32" && (statSync(file).mode & 0o077) !== 0)
+                chmodSync(file, 0o600);
+            const parsed = plainDocument(JSON.parse(readFileSync(file, "utf8")));
+            if (!parsed)
+                throw new Error("not a JSON object");
+            initial = parsed;
+            status = "ok";
+        }
+        catch {
+            status = "unavailable";
+        }
+    }
+    const persist = (next) => {
+        mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+        writeFileAtomic(file, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    };
+    const state = createSecureCredentialState(initial, persist, { writable: status !== "unavailable" });
+    return {
+        file,
+        status,
+        read: () => state.read(),
+        update: (derive, afterPersist) => state.update(derive, afterPersist),
+    };
+}
+function stringField(document, field) {
+    const value = document[field];
+    return typeof value === "string" && value ? value : null;
+}
+export function describeTunnelAccount(document) {
+    return {
+        email: stringField(document, COMPANION_ACCOUNT_EMAIL_FIELD),
+        address: managedCompanionTunnelAccess(document)?.endpoint ?? null,
+        installationId: stringField(document, COMPANION_INSTALLATION_ID_FIELD),
+    };
+}
+export function tunnelAccess(document) {
+    return managedCompanionTunnelAccess(document);
+}
+/** The control plane's platform vocabulary. */
+export function platformName(platform = process.platform) {
+    return platform === "darwin" ? "darwin" : platform === "win32" ? "windows" : "linux";
+}
+/** The desktop honours OMB_CONTROL_PLANE_URL only in development builds; a
+ * server's operator owns its environment, so it is honoured here always and
+ * the caller says so in its output. */
+export function createTunnelAccount(options) {
+    const env = options.env ?? process.env;
+    const credentials = openTunnelCredentials(options.dataDir);
+    const controlPlane = resolveCompanionControlPlaneURL({ isPackaged: true, environment: env });
+    const client = controlPlane ? createControlPlaneClient({ baseURL: controlPlane, fetchImpl: options.fetchImpl }) : null;
+    const service = createCompanionAccountService({
+        client,
+        readCredentials: () => credentials.read(),
+        updateCredentials: (derive, afterPersist) => credentials.update(derive, afterPersist),
+        identity: { name: options.machineName ?? hostname(), platform: platformName(), appVersion: options.version },
+        newClientInstanceId: () => randomUUID(),
+    });
+    return { service, credentials, controlPlane };
+}
+// ── cloudflared and the guardian: where they are, or how to get them ──────
+/** OMB_CLOUDFLARED_PATH, then the copy this command downloaded into the data
+ * dir, then PATH. */
+export function cloudflaredPath(dataDir, env = process.env) {
+    return resolveCloudflaredBinary({ isPackaged: false, appPath: dataDir, environment: env });
+}
+/** The pinned-download script: bundled beside the server in a package or
+ * image, the source in a checkout. */
+export function prepareEntry(here = HERE) {
+    const bundled = join(here, "prepare-cloudflared.js");
+    return existsSync(bundled) ? bundled : resolve(here, "..", "scripts", "prepare-cloudflared.mjs");
+}
+/** The connector guardian (the process that owns the gateway and cloudflared
+ * and tears both down if this process dies), same rule. */
+export function guardianEntry(here = HERE) {
+    const bundled = join(here, "tunnel-guardian.js");
+    if (existsSync(bundled))
+        return bundled;
+    const source = resolve(here, "..", "electron", "managed-companion-guardian.mjs");
+    return existsSync(source) ? source : null;
+}
+export async function ensureCloudflared(options) {
+    const env = options.env ?? process.env;
+    const found = cloudflaredPath(options.dataDir, env);
+    if (found)
+        return found;
+    options.log(`downloading cloudflared once (pinned version and digest, about 40 MB) into ${options.dataDir}`);
+    await new Promise((done, fail) => {
+        const child = spawn(process.execPath, [prepareEntry(options.here), "--current", "--root", options.dataDir], {
+            env,
+            stdio: ["ignore", "inherit", "inherit"],
+        });
+        child.on("error", fail);
+        child.on("exit", (code) => (code === 0 ? done() : fail(new Error(`the cloudflared download failed (exit ${code ?? "signal"})`))));
+    });
+    const staged = cloudflaredPath(options.dataDir, env);
+    if (!staged)
+        throw new Error("cloudflared was downloaded but is not where it should be; remove the data dir's dist-native folder and try again");
+    return staged;
+}
+// ── the origin: an IPC path the harness listens on for the gateway ────────
+export function createTunnelOrigin() {
+    return createCompanionOriginEndpoint({ processId: process.pid });
+}
+export function cleanupTunnelOrigin(origin) {
+    cleanupCompanionOriginEndpoint(origin);
+}
+/** The gateway listens on 127.0.0.1:<originPort> (the control plane points
+ * the tunnel at 8812; OMB_TUNNEL_ORIGIN_PORT exists for tests) and forwards
+ * to the harness's IPC socket. Verification polls the public address until
+ * it answers as this app, then retries with backoff forever if it never does. */
+export function startTunnel(options) {
+    const env = options.env ?? process.env;
+    const originPort = Number(env.OMB_TUNNEL_ORIGIN_PORT || MANAGED_COMPANION_ORIGIN_PORT);
+    let current = { status: "stopped", ready: false };
+    const tunnel = createManagedCompanionTunnel({
+        binaryPath: options.binaryPath,
+        guardianEntry: options.guardian,
+        runtimeRoot: join(options.dataDir, TUNNEL_RUNTIME_DIR),
+        originPort,
+        environment: env,
+        fetchImpl: options.fetchImpl,
+        onChange: (state) => {
+            current = state;
+            options.onState?.(state);
+        },
+    });
+    const started = tunnel.start({ endpoint: options.access.endpoint, token: options.access.token, originTarget: options.originTarget });
+    return {
+        address: options.access.endpoint,
+        state: () => current,
+        started,
+        stop: async () => {
+            await tunnel.stop();
+        },
+    };
+}
+/** One line per state change, for a terminal or a journal. */
+export function describeTunnelState(state, address) {
+    switch (state.status) {
+        case "starting":
+            return "tunnel: connecting…";
+        case "ready":
+            return `tunnel: live at ${address}`;
+        case "retrying":
+            return `tunnel: ${state.error ?? "not verified yet"} retrying in ${Math.max(1, Math.round((state.retryInMs ?? 0) / 1000))}s`;
+        case "stopped":
+            return "tunnel: stopped";
+        default:
+            return `tunnel: ${state.error ?? state.status}`;
+    }
+}

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

@@ -0,0 +1,40 @@
+/** Does this engine need the thread replayed to it? True when a DIFFERENT
+ * instance ran the last turn here — a cursor of our own is not enough,
+ * because it only proves we once had a session covering some prefix of the
+ * thread; every turn another engine took since is missing from it. Tasks
+ * from before `lastInstanceId` existed fall back to the cursor map: a lone
+ * cursor that is ours means a single-engine thread we can keep resuming;
+ * anything else is ambiguous, and replaying is the safe side of ambiguous.
+ * Gated on a prior USER turn: a new bot's thread is seeded with its own
+ * greeting, and that alone is nothing to join. */
+export function engineIsFresh(input) {
+    const { instanceId, lastInstanceId, resumeCursors, transcript } = input;
+    if (!transcript.some((m) => m.role === "user"))
+        return false;
+    if (lastInstanceId !== undefined)
+        return lastInstanceId !== instanceId || resumeCursors[instanceId] === undefined;
+    const cursorIds = Object.keys(resumeCursors);
+    return !(cursorIds.length === 1 && cursorIds[0] === instanceId);
+}
+const REWOUND_PREAMBLE = "[The user rewound this conversation (edited a message or switched to another version). Everything before this point was replaced by the following history:]";
+const FRESH_PREAMBLE = "[You are joining this conversation mid-thread (the user switched this bot over to you). The conversation so far:]";
+const EXTERNAL_UPDATE_PREAMBLE = "[This conversation received an update outside your provider session. The complete current history follows so you can use that update in your next response:]";
+export function buildTurnContext(input) {
+    const { text, transcript, rewound, fresh, externallyUpdated, replaysNatively } = input;
+    const resume = !rewound && !fresh && !externallyUpdated;
+    const replay = !resume && !replaysNatively && transcript.length > 0;
+    if (!replay)
+        return { turnText: text, resume };
+    return {
+        turnText: [
+            rewound ? REWOUND_PREAMBLE : externallyUpdated ? EXTERNAL_UPDATE_PREAMBLE : FRESH_PREAMBLE,
+            "",
+            ...transcript.map((m) => `${m.role === "user" ? "User" : "Assistant"}: ${m.text}`),
+            "",
+            "[Now reply to the user's latest message:]",
+            "",
+            text,
+        ].join("\n"),
+        resume,
+    };
+}

package/dist-server/server/turn-dispatch-guard.js

@@ -0,0 +1,152 @@
+/** Close the Stop-vs-provider-handshake race shared by direct and room turns.
+ * An adapter may not publish its active process until sendTurn resolves, so
+ * an interrupt during that await can be an honest no-op. Re-check once setup
+ * completes and issue a second interrupt only when cancellation won. */
+export async function guardTurnDispatch(started, cancelled, stopAfterSetup) {
+    const value = await started;
+    if (!cancelled())
+        return { value, cancelled: false };
+    await stopAfterSetup();
+    return { value, cancelled: true };
+}
+/** Bounded tombstones for provider turns cancelled during asynchronous
+ * startup. Their late completion/session events must not settle a newer turn
+ * that reused the same conversation thread. */
+export class RetiredTurnRegistry {
+    #turnIds = new Set();
+    #limit;
+    constructor(limit = 4_096) {
+        this.#limit = limit;
+    }
+    retire(turnId) {
+        this.#turnIds.add(turnId);
+        while (this.#turnIds.size > this.#limit) {
+            const oldest = this.#turnIds.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.#turnIds.delete(oldest);
+        }
+    }
+    has(turnId) {
+        return turnId !== undefined && this.#turnIds.has(turnId);
+    }
+}
+/** Correlate an internal capability generation with its provider turn without
+ * leaving a bearer alive when a very fast provider completes before
+ * sendTurn() returns its id. Completed ids are kept in a bounded tombstone
+ * registry, so a late bind fails closed instead of publishing stale ownership. */
+export class ProviderTurnGenerationRegistry {
+    #owners = new Map();
+    #completed;
+    constructor(limit = 4_096) {
+        this.#completed = new RetiredTurnRegistry(limit);
+    }
+    bind(threadId, generation, turnId) {
+        if (this.#completed.has(turnId))
+            return false;
+        this.#owners.set(turnId, { threadId, generation });
+        return true;
+    }
+    complete(threadId, turnId) {
+        this.#completed.retire(turnId);
+        const owner = this.#owners.get(turnId);
+        if (!owner || owner.threadId !== threadId)
+            return null;
+        this.#owners.delete(turnId);
+        return owner;
+    }
+    deleteGeneration(threadId, generation) {
+        for (const [turnId, owner] of this.#owners) {
+            if (owner.threadId === threadId && owner.generation === generation) {
+                this.#owners.delete(turnId);
+            }
+        }
+    }
+    clear() {
+        this.#owners.clear();
+    }
+}
+/** Thread gate for the narrow interval after Stop wins but before an async
+ * adapter returns the provider turn id that can be retired. Multiple queued
+ * room operations may share a thread, so ownership is reference-counted.
+ *
+ * A broken adapter is allowed to leave its sendTurn promise pending forever.
+ * The gate therefore expires each owner independently: by then any turn id
+ * observed during the vulnerable handshake has been moved to the longer-lived
+ * RetiredTurnRegistry, while a replacement turn's new id can flow normally. */
+export class PendingTurnCancellations {
+    #ownersByThread = new Map();
+    #clearWaitersByThread = new Map();
+    #ttlMs;
+    constructor(ttlMs = 30_000) {
+        this.#ttlMs = Math.max(1, Math.floor(ttlMs));
+    }
+    mark(threadId, ownerId) {
+        const owners = this.#ownersByThread.get(threadId) ?? new Map();
+        const previous = owners.get(ownerId);
+        if (previous)
+            clearTimeout(previous);
+        const expiry = setTimeout(() => {
+            // A clear + re-mark may have installed a newer timer for the same
+            // owner. The stale callback must not clear that renewed quarantine.
+            if (this.#ownersByThread.get(threadId)?.get(ownerId) !== expiry)
+                return;
+            this.clear(threadId, ownerId);
+        }, this.#ttlMs);
+        expiry.unref?.();
+        owners.set(ownerId, expiry);
+        this.#ownersByThread.set(threadId, owners);
+    }
+    clear(threadId, ownerId) {
+        const owners = this.#ownersByThread.get(threadId);
+        const expiry = owners?.get(ownerId);
+        if (expiry)
+            clearTimeout(expiry);
+        owners?.delete(ownerId);
+        if (owners?.size !== 0)
+            return;
+        this.#ownersByThread.delete(threadId);
+        const waiters = this.#clearWaitersByThread.get(threadId);
+        this.#clearWaitersByThread.delete(threadId);
+        for (const resolve of waiters ?? [])
+            resolve();
+    }
+    /** Do not overlap a replacement dispatch with the ambiguous pre-id window.
+     * Re-check after every wake: a cancellation can be renewed in the same
+     * microtask turn that clears an older owner. Each owner has its own bounded
+     * expiry, so a broken adapter cannot strand this await forever. */
+    async waitForClear(threadId) {
+        while (this.has(threadId)) {
+            await new Promise((resolve) => {
+                const waiters = this.#clearWaitersByThread.get(threadId) ?? new Set();
+                waiters.add(resolve);
+                this.#clearWaitersByThread.set(threadId, waiters);
+                // clear() cannot interleave with this synchronous block, but keeping
+                // the second check makes the registration safe if the implementation
+                // later gains an externally supplied scheduler.
+                if (!this.has(threadId)) {
+                    waiters.delete(resolve);
+                    if (waiters.size === 0)
+                        this.#clearWaitersByThread.delete(threadId);
+                    resolve();
+                }
+            });
+        }
+    }
+    has(threadId) {
+        return this.#ownersByThread.has(threadId);
+    }
+}
+/** Apply the two-stage cancellation quarantine. While the unresolved
+ * handshake owns the thread, every event is ignored and any stable provider
+ * turn id it reveals is retired. After the bounded gate expires, that old id
+ * remains ignored but an unrelated replacement id is admitted. */
+export function isTurnEventQuarantined(pending, retired, event) {
+    if (retired.has(event.turnId))
+        return true;
+    if (!pending.has(event.threadId))
+        return false;
+    if (event.turnId)
+        retired.retire(event.turnId);
+    return true;
+}