openmausbot 0.1.55

package/dist-server/server/team-manifest.js

@@ -0,0 +1,224 @@
+import { z } from "zod";
+import { schemaIssue } from "./schema.js";
+import { botMascotBody } from "../shared/mascot-bodies.js";
+import { takeImportName } from "../shared/import-name.js";
+export const TEAM_MANIFEST_FORMAT = "openmaus.team";
+export const TEAM_MANIFEST_VERSION = 2;
+export const LEGACY_TEAM_MANIFEST_VERSION = 1;
+export const MAX_TEAM_MEMBERS = 200;
+const COLORS = [
+    "green",
+    "blue",
+    "red",
+    "orange",
+    "purple",
+    "cyan",
+    "pink",
+    "yellow",
+    "teal",
+    "coral",
+];
+const requiredText = (max) => z.string({ error: "must be text" }).trim().min(1, { message: "is required" }).max(max, { message: "is too long" });
+const optionalText = (max) => z
+    .union([z.string({ error: "must be text" }), z.null(), z.undefined()])
+    .transform((value) => value?.trim() || undefined)
+    .refine((value) => value === undefined || value.length <= max, { message: "is too long" })
+    .optional();
+const responderSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("member"), member: requiredText(64) }),
+    z.object({ kind: z.literal("everyone") }),
+    z.object({ kind: z.literal("mentions") }),
+]);
+const memberSchema = z.object({
+    key: requiredText(64).regex(/^[a-z0-9][a-z0-9_-]*$/, {
+        message: "may only contain lowercase letters, numbers, - and _",
+    }),
+    name: requiredText(100),
+    title: optionalText(200),
+    description: optionalText(4_000),
+    appearance: z.object({
+        color: z.enum(COLORS, { error: "is not supported" }),
+        mascotExpression: optionalText(80),
+        mascotBody: optionalText(40),
+    }),
+});
+const membersSchema = z
+    .array(memberSchema)
+    .min(1, { message: "A team needs at least one member" })
+    .max(MAX_TEAM_MEMBERS, { message: `A team can have at most ${MAX_TEAM_MEMBERS} members` });
+const manifestSchema = z.discriminatedUnion("version", [
+    z.object({
+        format: z.literal(TEAM_MANIFEST_FORMAT, { error: "This is not an OpenMaus team file" }),
+        version: z.literal(LEGACY_TEAM_MANIFEST_VERSION),
+        team: z.object({
+            name: requiredText(100),
+            description: optionalText(2_000),
+            members: membersSchema,
+            room: z.object({
+                name: requiredText(100),
+                bulletin: optionalText(12_000),
+                defaultResponder: responderSchema,
+            }),
+        }),
+    }),
+    z.object({
+        format: z.literal(TEAM_MANIFEST_FORMAT, { error: "This is not an OpenMaus team file" }),
+        version: z.literal(TEAM_MANIFEST_VERSION),
+        team: z.object({
+            name: requiredText(100),
+            description: optionalText(2_000),
+            members: membersSchema,
+        }),
+    }),
+]);
+export function parseTeamManifest(value) {
+    const parsed = manifestSchema.safeParse(value);
+    if (!parsed.success) {
+        const formatIssue = parsed.error.issues.find((issue) => issue.path[0] === "format");
+        if (formatIssue)
+            throw new Error(formatIssue.message);
+        const versionIssue = parsed.error.issues.find((issue) => issue.path[0] === "version");
+        if (versionIssue)
+            throw new Error("Team file version is not supported");
+        throw new Error(schemaIssue(parsed.error, "This is not a team file"));
+    }
+    const seenKeys = new Set();
+    const members = parsed.data.team.members.map((member) => {
+        if (seenKeys.has(member.key))
+            throw new Error(`Duplicate member key: ${member.key}`);
+        seenKeys.add(member.key);
+        const appearance = { color: member.appearance.color };
+        if (member.appearance.mascotExpression)
+            appearance.mascotExpression = member.appearance.mascotExpression;
+        if (member.appearance.mascotBody)
+            appearance.mascotBody = member.appearance.mascotBody;
+        return {
+            key: member.key,
+            name: member.name,
+            title: member.title ?? "",
+            description: member.description ?? "",
+            appearance,
+        };
+    });
+    const result = {
+        format: TEAM_MANIFEST_FORMAT,
+        version: parsed.data.version,
+        team: {
+            name: parsed.data.team.name,
+            members,
+        },
+    };
+    if (parsed.data.team.description)
+        result.team.description = parsed.data.team.description;
+    if (parsed.data.version === LEGACY_TEAM_MANIFEST_VERSION) {
+        const defaultResponder = parsed.data.team.room.defaultResponder;
+        if (defaultResponder.kind === "member" && !seenKeys.has(defaultResponder.member)) {
+            throw new Error(`Unknown default responder: ${defaultResponder.member}`);
+        }
+        result.team.room = {
+            name: parsed.data.team.room.name,
+            bulletin: parsed.data.team.room.bulletin ?? "",
+            defaultResponder,
+        };
+    }
+    return result;
+}
+/** Everything an untrusted manifest may seed into a brand-new bot — and
+ * nothing else.
+ *
+ * A team file can come from the remote catalog, a GitHub repo, or a file
+ * someone shared, so import is additive-only: a manifest is a persona
+ * description, never a grant, and never a handle on records the user
+ * already has. Two rules are enforced here, at the single point where a
+ * member becomes bot fields:
+ *
+ * 1. Allowlist, not blocklist. The returned object is built field by field
+ *    from the parsed member, so every privilege-bearing BotRecord field —
+ *    approvalMode, autoApprove, autoReview, alwaysAllow, chiefOfStaff, approvePeerComms, composio,
+ *    computer, cloudBackend, cwd — is structurally absent, whatever the
+ *    file claimed. parseTeamManifest already drops unknown member keys;
+ *    this keeps the guarantee even if the schema grows a field later,
+ *    because nothing new can reach a bot record without someone
+ *    consciously widening this return type. The caller must still force
+ *    composio: false on the created record — that is the one privilege
+ *    where *absence* means allowed, so leaving it unset is not safe.
+ *
+ * 2. No name captures. Display names are identity wherever bots address
+ *    each other — @mention resolution in rooms, the Chief of Staff roster,
+ *    peer-approval prompts — so an imported member wearing an existing
+ *    bot's name could be mentioned, granted, or listed as if it were that
+ *    bot. A colliding name is therefore visibly numbered ("Scout" →
+ *    "Scout 2"), the same convention the name generator uses when its pool
+ *    runs out. Matching is case-insensitive because @mention matching is.
+ *    `takenNames` (lowercased) is mutated as names are claimed, so one
+ *    import batch also stays unique against itself; a suffixed name never
+ *    exceeds the member-name cap.
+ */
+export function importedMemberProfile(member, takenNames) {
+    const name = takeImportName(member.name, takenNames);
+    const profile = {
+        name,
+        title: member.title,
+        description: member.description,
+        color: member.appearance.color,
+    };
+    if (member.appearance.mascotExpression)
+        profile.mascotExpression = member.appearance.mascotExpression;
+    // The manifest carries the body as free text (parseTeamManifest only
+    // bounds its length); an untrusted or stale value must never reach a
+    // BotRecord unvalidated, so it is safe-parsed here — the one point where
+    // an imported member becomes bot fields — falling back to the default
+    // body rather than rejecting the whole import over a cosmetic field.
+    if (member.appearance.mascotBody)
+        profile.mascotBody = botMascotBody(member.appearance.mascotBody);
+    return profile;
+}
+function memberKey(name, index, used) {
+    const stem = name
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 48) || `member-${index + 1}`;
+    let key = stem;
+    let suffix = 2;
+    while (used.has(key))
+        key = `${stem}-${suffix++}`;
+    used.add(key);
+    return key;
+}
+/** Build a shareable definition only: no IDs, transcripts, engines or permissions. */
+export function createTeamManifest(team, bots) {
+    const byId = new Map(bots.map((bot) => [bot.id, bot]));
+    const usedKeys = new Set();
+    const members = team.memberIds.map((id, index) => {
+        const bot = byId.get(id);
+        if (!bot)
+            throw new Error(`Team member ${id} no longer exists`);
+        const key = memberKey(bot.name, index, usedKeys);
+        const appearance = { color: bot.color };
+        if (bot.mascotExpression)
+            appearance.mascotExpression = bot.mascotExpression;
+        if (bot.mascotBody)
+            appearance.mascotBody = bot.mascotBody;
+        return {
+            key,
+            name: bot.name,
+            title: bot.title,
+            description: bot.description,
+            appearance,
+        };
+    });
+    const manifest = {
+        format: TEAM_MANIFEST_FORMAT,
+        version: TEAM_MANIFEST_VERSION,
+        team: {
+            name: team.name,
+            members,
+        },
+    };
+    // Keep export and import in lockstep: a file produced here must satisfy
+    // the exact same limits and normalization as an untrusted shared file.
+    return parseTeamManifest(manifest);
+}

package/dist-server/server/thread-events.js

@@ -0,0 +1,226 @@
+// The inspector's data: what a thread's turn actually looked like on the
+// wire. Nothing new is captured here — the harness already tees two logs
+// per thread, and this just reads them back:
+//
+//   events/<threadId>.ndjson  — the normalized RuntimeEvent stream the bus
+//                               publishes (server/harness/bus.ts)
+//   native/<threadId>.ndjson  — the provider's own protocol messages,
+//                               verbatim and secret-redacted
+//                               (server/drivers/native.ts)
+//
+// Merged by timestamp so a tool call and the raw message behind it sit
+// next to each other. Newest-`limit` only: a long-lived thread has
+// thousands of native lines and the panel wants the recent ones first.
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULT_LIMIT = 300;
+const MAX_LIMIT = 2000;
+const READ_CHUNK = 64 * 1024;
+const MAX_TAIL_BYTES = 8 * 1024 * 1024;
+// Counts are incremental per append-only log. The first request scans bytes
+// once (without decoding or parsing every JSON record); later requests inspect
+// only bytes appended since the cached size. Keep this bounded across threads.
+const lineCounts = new Map();
+const LINE_COUNT_CACHE_MAX = 256;
+/** Thread ids are uuids the harness minted; anything else is not a file we
+ * should be reading. */
+function assertThreadId(threadId) {
+    if (!/^[\w-]+$/.test(threadId))
+        throw new Error("invalid thread id");
+}
+function countLines(fd, file, stat) {
+    const previous = lineCounts.get(file);
+    const appended = previous &&
+        previous.dev === stat.dev &&
+        previous.ino === stat.ino &&
+        stat.size >= previous.size &&
+        (stat.size > previous.size || stat.mtimeMs === previous.mtimeMs);
+    if (appended && stat.size === previous.size)
+        return previous.complete + Number(previous.trailing);
+    let offset = appended ? previous.size : 0;
+    let complete = appended ? previous.complete : 0;
+    let trailing = appended ? previous.trailing : false;
+    while (offset < stat.size) {
+        const length = Math.min(READ_CHUNK, stat.size - offset);
+        const chunk = Buffer.allocUnsafe(length);
+        const read = readSync(fd, chunk, 0, length, offset);
+        if (read <= 0)
+            break;
+        for (let i = 0; i < read; i++) {
+            if (chunk[i] === 0x0a) {
+                if (trailing)
+                    complete++;
+                trailing = false;
+            }
+            else if (chunk[i] !== 0x0d) {
+                trailing = true;
+            }
+        }
+        offset += read;
+    }
+    const next = { dev: stat.dev, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs, complete, trailing };
+    lineCounts.delete(file);
+    lineCounts.set(file, next);
+    while (lineCounts.size > LINE_COUNT_CACHE_MAX)
+        lineCounts.delete(lineCounts.keys().next().value);
+    return complete + Number(trailing);
+}
+function parseRecent(text, includeFirst, limit, valid) {
+    const lines = text.split("\n");
+    if (!includeFirst)
+        lines.shift();
+    const out = [];
+    for (const raw of lines) {
+        if (!raw)
+            continue;
+        try {
+            const value = JSON.parse(raw);
+            if (valid(value))
+                out.push(value);
+        }
+        catch {
+            // A torn line during a write, or a hand-edited record. Keep looking
+            // farther back until we still have `limit` valid recent entries.
+        }
+    }
+    return out.slice(-limit);
+}
+function readRecentLines(file, limit, valid) {
+    let fd;
+    try {
+        fd = openSync(file, "r");
+    }
+    catch {
+        return { lines: [], total: 0 };
+    }
+    try {
+        const stat = fstatSync(fd);
+        const total = countLines(fd, file, stat);
+        let position = stat.size;
+        let bytes = Buffer.alloc(0);
+        let lines = [];
+        while (position > 0 && bytes.length < MAX_TAIL_BYTES) {
+            const remaining = MAX_TAIL_BYTES - bytes.length;
+            const start = Math.max(0, position - Math.min(READ_CHUNK, remaining));
+            const length = position - start;
+            const chunk = Buffer.allocUnsafe(length);
+            const read = readSync(fd, chunk, 0, length, start);
+            if (read <= 0)
+                break;
+            bytes = Buffer.concat([chunk.subarray(0, read), bytes]);
+            position = start;
+            // The first line is partial until we reach byte zero. Parse only once
+            // enough complete candidates exist; corrupt candidates make us keep
+            // walking backwards rather than returning fewer valid rows.
+            const text = bytes.toString("utf8");
+            if (position === 0 || text.split("\n").length - 1 >= limit) {
+                lines = parseRecent(text, position === 0, limit, valid);
+                if (lines.length >= limit || position === 0)
+                    break;
+            }
+        }
+        if (lines.length === 0 && bytes.length > 0) {
+            lines = parseRecent(bytes.toString("utf8"), position === 0, limit, valid);
+        }
+        return { lines, total };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const stringOrMissing = (value) => value === undefined || typeof value === "string";
+const stringOrNullOrMissing = (value) => value === undefined || value === null || typeof value === "string";
+const numberOrNullOrMissing = (value) => value === undefined || value === null || typeof value === "number";
+const stringsOrMissing = (value) => value === undefined || (Array.isArray(value) && value.every((item) => typeof item === "string"));
+function isRuntimeEvent(value) {
+    if (!isRecord(value) ||
+        typeof value.eventId !== "string" ||
+        typeof value.provider !== "string" ||
+        typeof value.threadId !== "string" ||
+        typeof value.createdAt !== "string" ||
+        typeof value.type !== "string" ||
+        !stringOrMissing(value.providerInstanceId) ||
+        !stringOrMissing(value.turnId) ||
+        !stringOrMissing(value.itemId) ||
+        !stringOrMissing(value.requestId))
+        return false;
+    switch (value.type) {
+        case "session.started":
+            return (value.sessionId === null || typeof value.sessionId === "string") && stringOrNullOrMissing(value.model);
+        case "session.exited":
+            return stringOrMissing(value.reason);
+        case "turn.started":
+            return true;
+        case "turn.retrying":
+            return (typeof value.attempt === "number" &&
+                Number.isInteger(value.attempt) &&
+                value.attempt >= 1 &&
+                typeof value.delayMs === "number" &&
+                Number.isFinite(value.delayMs) &&
+                value.delayMs >= 0 &&
+                typeof value.reason === "string");
+        case "turn.completed":
+            return (typeof value.ok === "boolean" &&
+                stringOrNullOrMissing(value.stopReason) &&
+                numberOrNullOrMissing(value.cost) &&
+                stringsOrMissing(value.denials) &&
+                (value.usage === undefined ||
+                    (isRecord(value.usage) && typeof value.usage.input === "number" && typeof value.usage.output === "number")));
+        case "item.started":
+            return (value.itemType === "tool" || value.itemType === "reasoning") && stringOrMissing(value.title);
+        case "item.updated":
+            return (value.itemType === "tool" || value.itemType === "reasoning") && numberOrNullOrMissing(value.tokens);
+        case "item.completed":
+            return value.itemType === "assistant_text" ? typeof value.text === "string" : value.itemType === "tool" && typeof value.ok === "boolean";
+        case "content.delta":
+            return (value.streamKind === "assistant_text" || value.streamKind === "reasoning_text") && typeof value.delta === "string";
+        case "request.opened":
+            return ((value.requestType === "permission" || value.requestType === "question") &&
+                typeof value.tool === "string" &&
+                typeof value.summary === "string" &&
+                stringsOrMissing(value.choices));
+        case "request.resolved":
+            return ((value.behavior === "allow" || value.behavior === "deny" || value.behavior === "answer") &&
+                (value.source === "user" ||
+                    value.source === "auto" ||
+                    value.source === "timeout" ||
+                    value.source === "system" ||
+                    value.source === "unavailable" ||
+                    value.source === "peer"));
+        case "thread.token-usage.updated":
+            return typeof value.input === "number" && typeof value.output === "number";
+        case "runtime.error":
+            return typeof value.message === "string" && (value.setup === undefined || typeof value.setup === "boolean");
+        default:
+            return false;
+    }
+}
+function isNativeRecord(value) {
+    return (isRecord(value) &&
+        typeof value.at === "string" &&
+        (value.dir === "in" || value.dir === "out") &&
+        typeof value.source === "string" &&
+        Object.hasOwn(value, "msg"));
+}
+export function readThreadEvents(input) {
+    const { eventsDir, nativeDir, threadId } = input;
+    assertThreadId(threadId);
+    const requested = input.limit ?? DEFAULT_LIMIT;
+    const limit = Number.isFinite(requested) ? Math.max(1, Math.min(Math.trunc(requested), MAX_LIMIT)) : DEFAULT_LIMIT;
+    const runtime = readRecentLines(join(eventsDir, `${threadId}.ndjson`), limit, isRuntimeEvent);
+    const native = readRecentLines(join(nativeDir, `${threadId}.ndjson`), limit, isNativeRecord);
+    // cap each log on its own, then merge: the native tee is several times
+    // chattier than the runtime stream, and one shared cap would leave the
+    // Events lens with a handful of rows behind hundreds of raw ones
+    const merged = [
+        ...runtime.lines.map((data) => ({ kind: "runtime", at: data.createdAt, data })),
+        ...native.lines.map((data) => ({ kind: "native", at: data.at, data })),
+    ];
+    // stable sort: ties keep file order, which is emit order
+    merged.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
+    return {
+        entries: merged,
+        total: { runtime: runtime.total, native: native.total },
+    };
+}

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

@@ -0,0 +1,92 @@
+// ElevenLabs, the one voice.
+//
+// Everything about talking to the service lives in this file: verifying a
+// key, listing voices, and turning one utterance into mp3 bytes. It runs on
+// the HARNESS, never the renderer, because the key must not leave the
+// server — GET /api/config reports configured-or-not booleans and nothing
+// else, and that invariant is worth more than a saved round trip.
+//
+// One request per utterance rather than the streaming-input WebSocket: the
+// client already splits text into utterances and fetches the next while the
+// current one plays, which gets the same perceived latency with far fewer
+// moving parts — and no socket to leak when a turn is interrupted.
+const API = process.env.OMB_ELEVENLABS_API || "https://api.elevenlabs.io/v1";
+const MODEL = "eleven_flash_v2_5";
+// 64kbps mono is indistinguishable for speech and a third of the bytes
+const FORMAT = "mp3_44100_64";
+async function safeJson(res) {
+    try {
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+/** Prefer ElevenLabs' own words over anything we can invent — it knows the
+ * plan, the quota and the model name. Mirrors box.boxErrorMessage. */
+function message(status, what, body) {
+    const theirs = (typeof body?.detail === "string" && body.detail.trim()) ||
+        (typeof body?.detail?.message === "string" && body.detail.message.trim()) ||
+        (typeof body?.message === "string" && body.message.trim()) ||
+        "";
+    if (status === 401 || status === 403) {
+        // Restricted keys are the common case, not a corner: a key with the
+        // wrong scopes is REAL and still fails, so saying "copy a fresh one"
+        // sends people to regenerate a key that was never the problem.
+        return "ElevenLabs rejected that key. If it's a restricted key, give it the Voices and Text to Speech permissions — or paste an unrestricted one.";
+    }
+    if (status === 429)
+        return theirs || "ElevenLabs is rate-limiting this account — wait a moment and try again.";
+    if (status === 402)
+        return theirs || "ElevenLabs says this account is out of credit.";
+    return theirs ? `${what} failed: ${theirs}` : `${what} failed (${status})`;
+}
+/** Check a key before we store it: a rejected credential must fail at the
+ * paste, not hours later in another panel with nothing to act on.
+ *
+ * Checked against /voices, NOT /user. ElevenLabs keys carry per-endpoint
+ * scopes, and a key restricted to speech has no `user_read` — verifying
+ * there rejects perfectly good keys for a permission this feature never
+ * uses (found the hard way, with a real key). /voices is what the settings
+ * picker needs next, so it tests exactly the capability that matters. */
+export async function verifyKey(key) {
+    try {
+        const res = await fetch(`${API}/voices`, {
+            headers: { "xi-api-key": key },
+            signal: AbortSignal.timeout(20_000),
+        });
+        if (res.ok)
+            return { ok: true };
+        return { ok: false, message: message(res.status, "checking that key", await safeJson(res)) };
+    }
+    catch {
+        return { ok: false, message: "Couldn't reach ElevenLabs to check that key — check your connection." };
+    }
+}
+export async function listVoices(key) {
+    const res = await fetch(`${API}/voices`, {
+        headers: { "xi-api-key": key },
+        signal: AbortSignal.timeout(20_000),
+    });
+    const body = await safeJson(res);
+    if (!res.ok)
+        throw new Error(message(res.status, "listing voices", body));
+    return (body?.voices ?? [])
+        .map((v) => ({
+        id: String(v.voice_id ?? ""),
+        label: String(v.name ?? "Voice"),
+        description: [v.labels?.accent, v.labels?.description].filter(Boolean).join(" · ") || undefined,
+    }))
+        .filter((v) => v.id);
+}
+export async function synthesize(text, voiceId, key) {
+    const res = await fetch(`${API}/text-to-speech/${encodeURIComponent(voiceId)}?output_format=${FORMAT}`, {
+        method: "POST",
+        headers: { "xi-api-key": key, "content-type": "application/json", accept: "audio/mpeg" },
+        body: JSON.stringify({ text, model_id: MODEL }),
+        signal: AbortSignal.timeout(60_000),
+    });
+    if (!res.ok)
+        throw new Error(message(res.status, "speaking", await safeJson(res)));
+    return { bytes: new Uint8Array(await res.arrayBuffer()), mime: "audio/mpeg" };
+}

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

@@ -0,0 +1,79 @@
+import * as elevenlabs from "./elevenlabs.js";
+import * as systemVoices from "./system-voices.js";
+export class NoVoiceConfigured extends Error {
+    // a plain field rather than a constructor parameter property: the harness
+    // runs under `node --experimental-strip-types`, which is strip-ONLY, so a
+    // parameter property is rejected at load time even though it typechecks
+    reason;
+    constructor(reason) {
+        super(reason === "key"
+            ? "Add an ElevenLabs key in Settings on the computer to turn on voice."
+            : "Pick a voice in the agent profile.");
+        this.reason = reason;
+    }
+}
+export function voiceProvider(cfg) {
+    return cfg.tts?.provider === "system" ? "system" : "elevenlabs";
+}
+/** The system provider needs no credential — it is only ever offered where
+ * the platform actually has it, so "configured" means "this engine can
+ * speak", not "a key is on file". */
+export function providerConfigured(cfg) {
+    return voiceProvider(cfg) === "system" ? systemVoices.systemVoicesAvailable() : Boolean(cfg.tts?.key);
+}
+export function voiceConfigured(cfg) {
+    if (voiceProvider(cfg) === "system") {
+        return systemVoices.systemVoicesAvailable() && Boolean(cfg.tts?.voice);
+    }
+    return Boolean(cfg.tts?.key && cfg.tts?.voice);
+}
+/** A per-bot voice is a complete choice too; it should not be blocked just
+ * because the app-wide fallback has not been selected yet. */
+export function voiceReady(cfg, voiceId) {
+    if (voiceProvider(cfg) === "system") {
+        return systemVoices.systemVoicesAvailable() && Boolean(voiceId || cfg.tts?.voice);
+    }
+    return Boolean(cfg.tts?.key && (voiceId || cfg.tts?.voice));
+}
+/** What the settings panel needs. Never includes the key — same write-only
+ * rule as every other credential. */
+export function describeVoice(cfg) {
+    return {
+        configured: providerConfigured(cfg),
+        ready: voiceConfigured(cfg),
+        voice: cfg.tts?.voice ?? "",
+        provider: voiceProvider(cfg),
+    };
+}
+export function verifyKey(key) {
+    return elevenlabs.verifyKey(key);
+}
+export async function listVoices(cfg, run) {
+    if (voiceProvider(cfg) === "system")
+        return systemVoices.listSystemVoices(run);
+    const key = cfg.tts?.key;
+    if (!key)
+        return [];
+    return elevenlabs.listVoices(key);
+}
+/** Synthesize one utterance. Throws NoVoiceConfigured when there is nothing
+ * to speak with, which the route turns into a 409 the client can explain. */
+export function speak(cfg, text, voiceId, run) {
+    if (voiceProvider(cfg) === "system") {
+        const voice = voiceId || cfg.tts?.voice;
+        // An injected runner is the cross-platform test seam for `/usr/bin/say`;
+        // production calls omit it and remain strictly Darwin-gated.
+        if (!systemVoices.systemVoicesAvailable() && !run)
+            throw new NoVoiceConfigured("key");
+        if (!voice)
+            throw new NoVoiceConfigured("voice");
+        return systemVoices.synthesizeSystem(text, voice, run);
+    }
+    const key = cfg.tts?.key;
+    if (!key)
+        throw new NoVoiceConfigured("key");
+    const voice = voiceId || cfg.tts?.voice;
+    if (!voice)
+        throw new NoVoiceConfigured("voice");
+    return elevenlabs.synthesize(text, voice, key);
+}