openmausbot 0.1.80 → 0.1.82

package/dist-server/server/routines.js

@@ -20,6 +20,11 @@ function routineRequestOwnerKey(owner) {
 }
 const ALL_DAYS = [0, 1, 2, 3, 4, 5, 6];
 const CATCH_UP_MS = 12 * 60 * 60_000;
+/** How long before a due routine the computer is asked to stay awake. */
+const WAKE_HORIZON_MS = 60 * 60_000;
+/** How long a run may sit deferred behind a busy target before the user
+ * hears about it once. Surfacing only; dispatch semantics stay unchanged. */
+export const ROUTINE_DEFERRAL_NOTICE_MS = 30 * 60_000;
 const MAX_DATE_MS = 8_640_000_000_000_000;
 const LOCAL_DAY_MS = 24 * 60 * 60_000;
 const INTERVAL_RESTRICTION_SEARCH_MS = 9 * LOCAL_DAY_MS;
@@ -561,6 +566,21 @@ export class RoutineManager {
     listRoutines() {
         return this.routines.map(cloneRoutine);
     }
+    /** Whether this computer should stay awake for routines: a run is in
+     * flight, or an enabled routine is due within the horizon. The schedule
+     * runs inside this process — a sleeping computer runs nothing — so the
+     * desktop shell holds a power assertion while this says so, and releases
+     * it the rest of the time. */
+    wakeHold(horizonMs = WAKE_HORIZON_MS) {
+        const now = this.now();
+        if (this.runs.some((run) => ["queued", "running", "waiting"].includes(run.status)))
+            return { hold: true, reason: "running" };
+        const due = this.routines
+            .filter((routine) => routine.enabled && routine.nextRunAt != null && routine.nextRunAt <= now + horizonMs)
+            .map((routine) => routine.nextRunAt)
+            .sort((a, b) => a - b)[0];
+        return due === undefined ? { hold: false } : { hold: true, reason: "due", at: due };
+    }
     listRuns(from, to) {
         return this.runs
             .filter((r) => (from == null || r.scheduledFor >= from) && (to == null || r.scheduledFor <= to))
@@ -1151,8 +1171,23 @@ export class RoutineManager {
                     }
                 }
                 const state = this.targetState(run);
-                if (state === "busy")
+                if (state === "busy") {
+                    // A queued run behind a busy target is deferred, not silent. Stamp
+                    // the wait once so receipts and cards can say how long it has been
+                    // held; the run still dispatches the moment the target frees.
+                    if (run.deferredAt == null) {
+                        run.deferredAt = now;
+                        this.save();
+                        this.emitRun(run);
+                    }
+                    if (run.deferredNoticeAt == null && now - run.deferredAt >= ROUTINE_DEFERRAL_NOTICE_MS) {
+                        run.deferredNoticeAt = now;
+                        this.save();
+                        this.emitRun(run);
+                        this.options.onRunDeferred?.(cloneRun(run));
+                    }
                     continue;
+                }
                 if (state === "missing") {
                     this.failRun(run, this.missingTargetMessage(run.target));
                     continue;

package/dist-server/server/screen-frame-gate.js

@@ -11,80 +11,10 @@
 //      is what keeps its shell-only replies from re-picturing the same idle
 //      desktop.
 import { createHash } from "node:crypto";
-/** Tools that change or show the screen, by their bare MCP names. One list
- * for every computer surface, because the poke site only has the name: the
- * cloud box and remote computers (server/computer-proxy.ts), the built-in
- * browser (server/drivers/browser-proxy.ts) and Cua Driver's own surface
- * for the local Mac, Local VM and VPS (docs/computer-use-integration.md).
- *
- * Deliberately NOT here: computer_exec (a shell — no screenshot unless
- * asked, and the ask is not visible at the poke site); the read-only text
- * tools (computer_status, browser_state, browser_snapshot, browser_read,
- * observation_metrics, start_session, get_*, list_*, check_permissions);
- * the waits (wait_for, wait_for_navigation, browser_wait_for — they change
- * nothing, and the action they follow already counted); and the takeover
- * pleas (computer_request_help, browser_request_takeover — whatever changed
- * during those was the person's doing, and captures are withheld under
- * their lease anyway). */
-const SCREEN_TOUCHING_TOOLS = new Set([
-    // cloud box / remote computer
-    "screenshot",
-    "click",
-    "type_text",
-    "press_key",
-    "scroll",
-    "computer_batch",
-    "open_url",
-    "browser_click",
-    "browser_fill",
-    // built-in browser: the Electron surface's names, kept because a bot on an
-    // older remote harness can still call them
-    "browser_navigate",
-    "browser_type",
-    "browser_press",
-    "browser_scroll",
-    "browser_hover",
-    "browser_drag",
-    "browser_select_option",
-    "browser_back",
-    "browser_forward",
-    "browser_screenshot",
-    // built-in browser: agent-browser's names. The engine swap replaced the
-    // Electron surface without renaming these here, so every browser turn
-    // stopped counting as screen work and no page ever reached the transcript.
-    // Read-only tools stay out by the same rule as everywhere else in this
-    // list: agent_browser_snapshot, _read and _get_text return text, and the
-    // waits change nothing the action before them did not already count.
-    "agent_browser_open",
-    "agent_browser_click",
-    "agent_browser_fill",
-    "agent_browser_type",
-    "agent_browser_press",
-    "agent_browser_select",
-    "agent_browser_check",
-    "agent_browser_screenshot",
-    // Cua Driver (local Mac, Local VM, VPS)
-    "double_click",
-    "right_click",
-    "drag",
-    "hotkey",
-    "move_cursor",
-    "launch_app",
-    "bring_to_front",
-    "zoom",
-]);
-// Keep legacy MCP namespaces accepted; desktop server__tool names follow
-// MCP_NAME in mcp-registry.ts (lowercase letters, digits, underscores, hyphens).
-const TOOL_NAMESPACE = /^(?:mcp__.+?|[a-z][a-z0-9_-]{0,31})__/;
-/** The same tool reaches the poke site as `mcp__computer__click`,
- * `computer__click`, bare `click`, or pi's `computer_click`.
- * A single-underscore server prefix is stripped
- * at most once, so pi's `computer_computer_exec` lands on `computer_exec`
- * — still a shell — and never on a bare `exec`. */
-export function screenTouchingTool(toolName) {
-    const bare = toolName.toLowerCase().replace(TOOL_NAMESPACE, "");
-    return SCREEN_TOUCHING_TOOLS.has(bare) || SCREEN_TOUCHING_TOOLS.has(bare.replace(/^(?:computer|browser)_/, ""));
-}
+// Tool-name classification lives in shared/tool-surface.ts so the renderer
+// reads a tool the same way the poller does.
+import { screenSurfaceForTool, screenTouchingTool } from "../shared/tool-surface.js";
+export { screenSurfaceForTool, screenTouchingTool };
 /** sha256 over the base64 frame — the same fingerprint the model-side
  * observation dedupe uses (server/computer-observation.ts). */
 export function screenFrameHash(png) {
@@ -96,23 +26,3 @@ export function screenFrameHash(png) {
 export function settledFrameIsNews(shownFrameHash, png) {
     return shownFrameHash === undefined || screenFrameHash(png) !== shownFrameHash;
 }
-/** Which surface a screen-touching tool acted on. A bot can hold a computer
- * and a browser at once, and they are different pictures: agent-browser runs
- * its own headless Chrome on the host, not inside the bot's desktop. Picking
- * by the tool is what keeps a browsed page from being illustrated with an
- * idle Local VM. */
-export function screenSurfaceForTool(toolName) {
-    const name = toolName.toLowerCase();
-    // The computer server's browser_click/fill act inside the desktop, not
-    // in agent-browser. Keep the server identity before stripping prefixes.
-    if (name.startsWith("mcp__computer__") || name.startsWith("computer_"))
-        return "computer";
-    if (name.startsWith("mcp__browser__") || name.startsWith("browser__"))
-        return "browser";
-    const bare = name.replace(TOOL_NAMESPACE, "");
-    // Codex reports bare names. These two belong to computer-proxy; the
-    // standalone browser now uses the unambiguous agent_browser_* names.
-    if (bare === "browser_click" || bare === "browser_fill")
-        return "computer";
-    return bare.startsWith("agent_browser_") || bare.startsWith("browser_") ? "browser" : "computer";
-}

package/dist-server/server/sessions.js

@@ -95,6 +95,18 @@ export function generatePairingCode() {
     }
     return code;
 }
+/** The prefix that tells the two encodings apart on the wire. A credential is
+ * matched byte for byte; only a typed code is normalized. */
+export const PAIRING_CREDENTIAL_PREFIX = "omb_pair_";
+/** The same pairing window as a 256-bit secret, for a QR a native app scans
+ * rather than a code a person reads out. 9 + 43 characters: the Android
+ * companion checks that length exactly (android/core Connection.kt). */
+export function generatePairingCredential() {
+    return `${PAIRING_CREDENTIAL_PREFIX}${randomBytes(32).toString("base64url")}`;
+}
+export function isPairingCredential(value) {
+    return value.startsWith(PAIRING_CREDENTIAL_PREFIX);
+}
 /** Accept what a human typed: dashes, spaces, lowercase, lookalikes. */
 export function normalizePairingCode(input) {
     return input
@@ -245,17 +257,19 @@ export class SessionRegistry {
         this.prune();
         const now = this.now();
         const code = generatePairingCode();
+        const credential = generatePairingCredential();
         const scopes = input.scopes?.length ? [...new Set(input.scopes)] : [...SCOPES];
         const pairing = {
             id: randomUUID(),
             codeHash: sha256(code),
+            credentialHash: sha256(credential),
             scopes,
             label: (input.label ?? "").trim().slice(0, 80),
             createdAt: now,
             expiresAt: now + (input.ttlMs ?? PAIRING_CODE_TTL_MS),
         };
         this.pairings.push(pairing);
-        return { id: pairing.id, code, expiresAt: pairing.expiresAt };
+        return { id: pairing.id, code, credential, expiresAt: pairing.expiresAt };
     }
     openPairings() {
         this.prune();
@@ -303,7 +317,12 @@ export class SessionRegistry {
     exchange(input) {
         this.prune();
         const now = this.now();
-        const presented = sha256(normalizePairingCode(input.code));
+        // A credential is hashed as presented. Normalizing it would be actively
+        // unsafe: normalizePairingCode folds 0 to O and 1 to I, which both
+        // destroys a base64url secret and maps distinct secrets onto one digest.
+        const presented = isPairingCredential(input.code)
+            ? sha256(input.code)
+            : sha256(normalizePairingCode(input.code));
         const attemptId = typeof input.attemptId === "string" && /^[\w-]{8,64}$/.test(input.attemptId) ? input.attemptId : null;
         const replay = attemptId ? this.replays.find((r) => r.attemptId === attemptId && sameDigest(r.codeHash, presented)) : undefined;
         if (replay)
@@ -313,7 +332,7 @@ export class SessionRegistry {
             const seconds = Math.ceil(lock.retryAfterMs / 1000);
             return { ok: false, status: 429, error: `too many failed pairing attempts from your address; try again in ${seconds}s` };
         }
-        const index = this.pairings.findIndex((p) => sameDigest(p.codeHash, presented));
+        const index = this.pairings.findIndex((p) => sameDigest(p.codeHash, presented) || sameDigest(p.credentialHash, presented));
         if (index < 0) {
             this.recordFailure(input.source);
             return { ok: false, status: 401, error: "pairing code is wrong or has expired; create a new one on the server" };

package/dist-server/server/store.js

@@ -27,7 +27,7 @@ export function isProjectEmoji(value) {
 const TASK_PATCH_FIELDS = [
     "title", "projectId", "modelSelection", "approvalMode", "autoApprove", "alwaysAllow",
     "unread", "rewound", "archivedAt", "pinnedMessageId", "resumeCursors", "lastInstanceId", "cwd",
-    "routineRunId",
+    "routineRunId", "surface",
 ];
 /** Everything the BOT authored is scrubbed of content-shaped secrets before
  * it is stored: its reply text, a tool title (an ACP engine's title can be
@@ -1296,6 +1296,21 @@ export class Store {
         this.emit({ type: "bot", botId: id });
         return bot;
     }
+    /** Voice ids belong to one provider's catalog. Changing the workspace
+     * provider invalidates every per-agent selection as one durable mutation,
+     * before clients are told to pick replacement voices. */
+    clearVoiceSelections() {
+        const changed = this.bots.filter((bot) => bot.voice !== undefined && bot.voice !== "");
+        if (!changed.length)
+            return [];
+        const next = this.bots.map((bot) => bot.voice === undefined || bot.voice === "" ? bot : { ...bot, voice: undefined });
+        this.saveBots(next);
+        for (const bot of changed) {
+            delete bot.voice;
+            this.emit({ type: "bot", botId: bot.id });
+        }
+        return changed;
+    }
     /** Commit a validated profile change before publishing its fields. Unlike
      * runtime revocation, a failed user edit must leave the old profile intact. */
     patchBotProfile(id, patch) {

package/dist-server/server/surface.js

@@ -20,12 +20,15 @@ export function surfaceOfComputerKind(kind) {
 }
 const NO_BROWSER_NOTE = " This bot is set to work in the built-in browser, but the built-in browser is switched off in App Settings, so you have no browser and no computer this turn — say so instead of guessing.";
 const OFF_NOTE = " This bot's \"Works on\" setting is Off, so no computer and no built-in browser are mounted this turn: you cannot open a page, click, or type on any screen. If the user asks for something that needs one, tell them Works on is Off in this bot's settings — never claim you are opening a browser you do not have.";
-/** Decide what a turn mounts from the bot's destination, the task's pin
- * and what is actually reachable. Explicit choices are strict: Off mounts
- * neither surface, a computer destination keeps whatever browser the bot
- * has (the prompt tells the model which to use), a browser destination
- * mounts only the browser. Auto follows the task's pin while the pinned
- * place still exists, and otherwise re-resolves the way it always has. */
+/** Decide what a turn mounts. One place per turn: a computer destination
+ * mounts only that computer (web work happens in its own browser), a browser
+ * destination mounts only the built-in browser, Off mounts nothing. A
+ * conversation pin — set by the person from the composer, or by the
+ * conversation's own first turn on Auto — wins over the bot's default, so a
+ * thread never changes place under someone; only Off overrides it. Auto
+ * without a pin leaves the computer choice to the dispatch, which then
+ * mounts the browser only when no computer was reached. A pin the turn
+ * cannot honour is retained and reported instead of being swapped silently. */
 export function resolveSurface(input) {
     const { destination, browserOn } = input;
     // Off is the whole answer: no computer and no browser. It used to withhold
@@ -38,25 +41,27 @@ export function resolveSurface(input) {
     if (destination === "off") {
         return { computer: "off", browser: false, pinned: null, clearPin: false, note: OFF_NOTE };
     }
+    const pin = input.pinnedSurface ?? null;
+    if (pin === "browser") {
+        if (browserOn)
+            return { computer: "off", browser: true, pinned: "browser", clearPin: false, note: "" };
+        // A missing browser is not permission to act on the host instead. Keep
+        // the chosen place so a retry or unrelated provider failure cannot move
+        // the task to a different signed-in computer.
+        return { computer: "off", browser: false, pinned: pin, clearPin: false,
+            note: " This conversation is pinned to the built-in browser, but its tools are unavailable this turn. No computer is mounted instead. Do not claim to have used it; a different place must be selected before acting there." };
+    }
+    if (pin)
+        return { computer: pin, browser: false, pinned: pin, clearPin: false, note: "" };
     if (destination === "browser") {
         return browserOn
             ? { computer: "off", browser: true, pinned: null, clearPin: false, note: "" }
             : { computer: "off", browser: false, pinned: null, clearPin: false, note: NO_BROWSER_NOTE };
     }
     if (destination !== undefined) {
-        return { computer: destination, browser: browserOn, pinned: null, clearPin: false, note: "" };
-    }
-    const pin = input.pinnedSurface ?? null;
-    if (pin === null) {
-        return { computer: undefined, browser: browserOn, pinned: null, clearPin: false, note: "" };
-    }
-    const reachable = pin === "browser" ? browserOn : input.available?.[pin] === true;
-    if (!reachable) {
-        return { computer: undefined, browser: browserOn, pinned: null, clearPin: true, note: "" };
+        return { computer: destination, browser: false, pinned: null, clearPin: false, note: "" };
     }
-    return pin === "browser"
-        ? { computer: "off", browser: true, pinned: "browser", clearPin: false, note: "" }
-        : { computer: pin, browser: false, pinned: pin, clearPin: false, note: "" };
+    return { computer: undefined, browser: browserOn, pinned: null, clearPin: false, note: "" };
 }
 /** How the prompt and the app name a surface. Deliberately the same words
  * the panel uses, so "tell them it is on the cloud computer" points at a
@@ -73,6 +78,10 @@ export function surfaceLabel(surface) {
             return "the built-in browser";
     }
 }
+/** Said once per task, so the person hears the place before the first click
+ * lands there. Same words as the panel and the composer chip. */
+const RESTATE_SENTENCE = " Before your first action on a screen or page in a task, say in one short sentence where you are working, using that same name.";
+const SURFACE_AUTHORITY = " For browser and computer tasks, use OpenMausBot's mounted browser/computer tools first: inspect the target, perform the action, and verify its result before claiming success. Discover deferred tools by their server/name when needed. Do not substitute the provider's own desktop, a shell-launched browser, or another automation path for the selected OpenMausBot surface. Ordinary code and file tasks may still use their normal tools. Announcing an action is not performing it. A request naming another place does not move these tools: this computer is the user's host, Local VM is an isolated desktop, the cloud computer is remote, and the built-in browser is a separate browser. If the requested place differs from the mounted one, explain the mismatch and ask the user to change the conversation's computer selector; never act on a different computer or describe a host window as a VM.";
 /** The one paragraph that says where this turn's work happens. Assembled
  * from what was actually mounted, never from the setting, so the model is
  * only ever told about tools it can call. */
@@ -91,9 +100,22 @@ export function surfacePrompt(mounted, opts = {}) {
         text =
             " Everything you do on screen happens in the built-in browser tab; there is no desktop, file or shell computer this turn. If you need the user to sign in, tell them it is in the Browser tab of the Computer panel.";
     }
+    if (text)
+        text += RESTATE_SENTENCE + (opts.canSelect
+            ? SURFACE_AUTHORITY.replace("explain the mismatch and ask the user to change the conversation's computer selector", "inspect connected choices with select_computer and select the requested available place; on a pending result end this turn so OpenMausBot can reconnect the correct tools and continue the original request")
+            : SURFACE_AUTHORITY);
+    else if (!opts.note && !opts.canSelect) {
+        text = " No computer or built-in browser tools are mounted this turn. You cannot open apps, click, or inspect a screen through OpenMausBot. If asked for screen work, explain this and ask the user to choose and connect a computer in the Computer panel; do not claim to have opened or checked it.";
+    }
     if (opts.pinned) {
-        text += ` This task has been running on ${surfaceLabel(opts.pinned)}; keep using it unless the user says otherwise.`;
+        text += ` This conversation is pinned to ${surfaceLabel(opts.pinned)}; changing places requires ${opts.canSelect ? "select_computer or " : ""}the conversation's computer selector, not a different tool name.`;
     }
+    if (opts.canSelect)
+        text += " For a screen task, use select_computer with no arguments when you need to inspect the actual available targets. Choose the requested place from its result; if the user left the place open, use a suitable available target or surface auto instead of asking them to operate the menu. Browser-only work can stay in Browser; when it needs desktop apps or capabilities the current Browser lacks, select an available Local VM without asking the user to switch it manually. Choose before taking actions, and do not repeat actions already completed if the task must continue elsewhere. OpenMausBot can start an existing configured computer and highlight the selected target. If the right tools are already mounted, use them directly. On a pending switch, end this turn: the original request resumes automatically with the new tools, and then you must carry out the task. Only ask for input for a genuine blocker, such as missing setup, required sign-in or an approval. Never silently replace an explicitly requested VM with the host desktop.";
+    if (opts.canSelect)
+        text += " If no suitable computer is running but its provider is configured, select_computer can provision one for this computer task; reuse existing resources first. Do not provision merely for ordinary chat or inspection.";
+    if (opts.canSelect && !computer && !mounted.browser)
+        text += " No computer or browser tools are mounted yet; select_computer is the way to connect them before screen work, not a reason to claim you already performed it.";
     return text + (opts.note ?? "");
 }
 /** Tool names that touch a screen, for engines that report bare names.

package/dist-server/server/team-setup-requests.js

@@ -194,7 +194,7 @@ export class TeamSetupRequestService {
         const chief = this.chief(request.botId);
         const lines = [`Why: ${request.reason}`];
         if (request.deletion)
-            lines.push(`Delete @${request.deletion.name} (${request.deletion.botId}).`, "Permanently removes this bot, all its conversations, memory, instructions, and skills. Generated project files remain. Active work or owned computers can block deletion.");
+            lines.push(`Delete @${request.deletion.name} (${request.deletion.botId}).`, "Permanently removes this bot, all its conversations, memory, instructions, skills, and any computer owned only by it. Generated project files and shared team computers remain. Active work or an unavailable provider can block deletion safely.");
         if (request.newTeams.length)
             lines.push(`Create teams: ${request.newTeams.map((name) => JSON.stringify(name)).join(", ")}.`, `Authorize @${chief.name} to coordinate and propose setup changes in these new teams.`);
         for (const operation of request.operations) {

package/dist-server/server/thread-log-rotation.js

@@ -0,0 +1,104 @@
+// Per-thread log rotation — the size cap for the two NDJSON tees each
+// thread grows: events/<threadId>.ndjson (the bus's canonical stream,
+// server/harness/bus.ts) and native/<threadId>.ndjson (the provider-native
+// tee, server/drivers/native.ts). Retention sweeps only reach threads that
+// closed or archived; a thread that stays open grows both files without
+// bound (#1280), and a busy thread can stay open for weeks.
+//
+// When a capped file outgrows its limit it is rewritten in place, keeping
+// the newest half of its bytes and cutting only on a line boundary — the
+// same recent tail readThreadEvents already serves. One filename per
+// thread and log, before and after: every reader and every cleanup path
+// (thread, bot and group delete; the retention sweep) already targets that
+// one name, so rotation can never orphan a fragment. What rotates away is
+// gone; the cap is opt-in and off by default.
+import { closeSync, fstatSync, openSync, readSync, renameSync, rmSync, statSync, writeSync } from "node:fs";
+let capProvider = () => null;
+/** Bound once at server boot: config.json is read per process (a change
+ * restarts the server, like every other hand-edited knob), so a binding
+ * made at startup stays current for the life of the process. */
+export function bindThreadLogCapProvider(provider) {
+    capProvider = provider;
+}
+export function currentThreadLogCap() {
+    try {
+        return capProvider();
+    }
+    catch {
+        return null;
+    }
+}
+/** Check a freshly appended log against the configured cap. Best effort and
+ * never throwing: a rotation that cannot complete leaves the file exactly
+ * as it was, and logging must never break the run it is observing. */
+export function capThreadLog(file, maxBytes) {
+    if (typeof maxBytes !== "number" || !Number.isFinite(maxBytes) || maxBytes <= 0)
+        return;
+    let size;
+    try {
+        size = statSync(file).size;
+    }
+    catch {
+        return;
+    }
+    if (size <= maxBytes)
+        return;
+    trimToTail(file, Math.max(1, Math.floor(maxBytes / 2)));
+}
+function trimToTail(file, keepBytes) {
+    const staging = `${file}.trim`;
+    try {
+        const source = openSync(file, "r");
+        try {
+            const size = fstatSync(source).size;
+            const start = Math.max(0, size - keepBytes);
+            const window = Buffer.allocUnsafe(size - start);
+            // readSync may hand back fewer bytes than asked for, so fill the
+            // window in a loop. A zero count is an early EOF — the file shrank
+            // under us — and the original is left untouched.
+            let filled = 0;
+            while (filled < window.length) {
+                const count = readSync(source, window, filled, window.length - filled, start + filled);
+                if (count === 0)
+                    return;
+                filled += count;
+            }
+            // The window starts mid-line unless a record happened to end exactly
+            // at `start`; drop everything up to the first newline so the rewritten
+            // file opens on a record boundary. A window without a usable newline
+            // is a single record bigger than the keep window — leave the file
+            // alone rather than corrupt the only copy.
+            const firstNewline = window.indexOf(0x0a);
+            if (firstNewline === -1 || firstNewline + 1 >= window.length)
+                return;
+            const target = openSync(staging, "w", 0o600);
+            try {
+                // writeSync can also stop short of the requested length; keep
+                // going until every remaining byte lands, and treat zero progress
+                // as a failure so the outer catch clears the staging file.
+                let written = firstNewline + 1;
+                while (written < window.length) {
+                    const count = writeSync(target, window, written, window.length - written);
+                    if (count === 0)
+                        throw new Error(`no progress writing ${staging}`);
+                    written += count;
+                }
+            }
+            finally {
+                closeSync(target);
+            }
+        }
+        finally {
+            closeSync(source);
+        }
+        renameSync(staging, file);
+    }
+    catch {
+        try {
+            rmSync(staging, { force: true });
+        }
+        catch {
+            /* an inert staging file is the worst case */
+        }
+    }
+}

package/dist-server/server/tts/fish.js

@@ -0,0 +1,155 @@
+// Fish Audio text to speech. The API key stays on the harness: the renderer
+// receives only voice metadata and synthesized audio bytes.
+const API = (process.env.OMB_FISH_AUDIO_API || "https://api.fish.audio").replace(/\/+$/, "");
+const MODEL = "s2.1-pro";
+const MAX_ERROR_LENGTH = 240;
+const PAGE_SIZE = 100;
+const MAX_OWNED_PAGES = 100;
+async function safeBody(res) {
+    try {
+        const text = await res.text();
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return { message: text };
+        }
+    }
+    catch {
+        return null;
+    }
+}
+function serviceDetail(body) {
+    if (!body || typeof body !== "object")
+        return "";
+    const record = body;
+    const detail = record.detail;
+    const message = (typeof detail === "string" && detail) ||
+        (detail && typeof detail === "object" && typeof detail.message === "string"
+            ? detail.message
+            : "") ||
+        (typeof record.message === "string" && record.message) ||
+        (typeof record.error === "string" && record.error) ||
+        "";
+    return message.trim().slice(0, MAX_ERROR_LENGTH);
+}
+function errorMessage(status, action, body) {
+    const detail = serviceDetail(body);
+    if (status === 401 || status === 403) {
+        return "Fish Audio rejected that API key, or the key cannot access voice models.";
+    }
+    if (status === 402)
+        return detail || "Fish Audio says this account has insufficient balance.";
+    if (status === 429)
+        return detail || "Fish Audio is rate-limiting this account — wait a moment and try again.";
+    return detail ? `${action} failed: ${detail}` : `${action} failed (${status})`;
+}
+/** Verify the exact permission the voice picker needs. */
+export async function verifyKey(key) {
+    try {
+        // The public catalog is intentionally readable without authentication,
+        // so it cannot prove a supplied key. `self=true` crosses the account
+        // boundary and returns 401 for an absent or invalid Bearer token.
+        const res = await fetch(`${API}/model?page_size=1&self=true`, {
+            headers: { authorization: `Bearer ${key}` },
+            signal: AbortSignal.timeout(20_000),
+        });
+        if (res.ok)
+            return { ok: true };
+        return { ok: false, message: errorMessage(res.status, "checking that key", await safeBody(res)) };
+    }
+    catch {
+        return { ok: false, message: "Couldn't reach Fish Audio to check that key — check your connection." };
+    }
+}
+async function modelPage(key, query) {
+    let response;
+    try {
+        response = await fetch(`${API}/model?${query}`, {
+            headers: { authorization: `Bearer ${key}` },
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch {
+        throw new Error("Couldn't reach Fish Audio to list voices — check your connection.");
+    }
+    const body = await safeBody(response);
+    if (!response.ok)
+        throw new Error(errorMessage(response.status, "listing voices", body));
+    if (!body || typeof body !== "object")
+        return { items: [], hasMore: false };
+    const page = body;
+    return {
+        items: Array.isArray(page.items) ? page.items : [],
+        hasMore: page.has_more === true,
+    };
+}
+export async function listVoices(key) {
+    // Fish defaults to ten results and excludes private account voices from
+    // the public catalog. Load the popular public page and every page belonging
+    // to this account, so a user's 101st custom voice remains selectable.
+    const [publicPage, owned] = await Promise.all([
+        modelPage(key, `page_size=${PAGE_SIZE}&sort_by=task_count`),
+        (async () => {
+            const items = [];
+            for (let pageNumber = 1; pageNumber <= MAX_OWNED_PAGES; pageNumber += 1) {
+                const page = await modelPage(key, `page_size=${PAGE_SIZE}&self=true&sort_by=created_at&page_number=${pageNumber}`);
+                items.push(...page.items);
+                if (!page.hasMore)
+                    return items;
+            }
+            throw new Error("Fish Audio returned too many voice pages. Narrow the account's voice library and try again.");
+        })(),
+    ]);
+    const items = [...publicPage.items, ...owned];
+    const voices = items.flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const model = item;
+        // `/model` includes SVC models and account models that are still
+        // training or have failed. Only trained TTS models are valid
+        // `reference_id` values for `/v1/tts`.
+        if (model.type !== "tts" || model.state !== "trained")
+            return [];
+        const id = typeof model._id === "string" ? model._id.trim() : "";
+        if (!id)
+            return [];
+        const label = typeof model.title === "string" && model.title.trim() ? model.title.trim() : "Voice";
+        const description = typeof model.description === "string" && model.description.trim()
+            ? model.description.trim().slice(0, MAX_ERROR_LENGTH)
+            : undefined;
+        return [{ id, label, description }];
+    });
+    return [...new Map(voices.map((voice) => [voice.id, voice])).values()];
+}
+export async function synthesize(text, voiceId, key) {
+    let res;
+    try {
+        res = await fetch(`${API}/v1/tts`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${key}`,
+                "content-type": "application/json",
+                accept: "audio/mpeg",
+                model: MODEL,
+            },
+            body: JSON.stringify({
+                text,
+                reference_id: voiceId,
+                format: "mp3",
+                sample_rate: 44_100,
+                mp3_bitrate: 64,
+                latency: "normal",
+            }),
+            signal: AbortSignal.timeout(60_000),
+        });
+    }
+    catch {
+        throw new Error("Couldn't reach Fish Audio to generate speech — check your connection.");
+    }
+    if (!res.ok)
+        throw new Error(errorMessage(res.status, "speaking", await safeBody(res)));
+    return { bytes: new Uint8Array(await res.arrayBuffer()), mime: "audio/mpeg" };
+}