openmausbot 0.1.55

package/dist-server/server/store.js

@@ -0,0 +1,1217 @@
+// Bot + thread persistence. bots.json holds bot records (including the
+// thread→instance binding and per-instance resume cursors — upstream's
+// ProviderSessionDirectory, recipe step 6: persist the binding from day
+// one). messages-<threadId>.json holds the folded transcript.
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, mkdirSync, rmSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "./atomic.js";
+import { peerAllowKey } from "./peer-approval-key.js";
+import { DATA_DIR, loadBrowserProfileIdAliases } from "./config.js";
+import * as mdb from "./message-db.js";
+import { workspaceDir } from "./workspace.js";
+import { newId } from "./contracts.js";
+import { pickBotName } from "./names.js";
+import { redactSecretsInText } from "./redact.js";
+import { botAvatarProfile } from "../shared/bot-avatar.js";
+import { isApprovalMode } from "../shared/approval-mode.js";
+/** 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
+ * the whole command line), a permission card's summary. What the user typed
+ * is theirs and stays as typed. Stored, not just displayed: the transcript
+ * is replayed into every rebuild, and a leaked key would otherwise be
+ * permanent. */
+function redactBotAuthored(message) {
+    if (message.role !== "bot")
+        return message;
+    const out = { ...message };
+    if (typeof out.text === "string")
+        out.text = redactSecretsInText(out.text);
+    if (out.tool?.name)
+        out.tool = { ...out.tool, name: redactSecretsInText(out.tool.name) };
+    if (out.routineRun) {
+        const routineRun = { ...out.routineRun };
+        routineRun.routineName = redactSecretsInText(routineRun.routineName);
+        if (routineRun.summary)
+            routineRun.summary = redactSecretsInText(routineRun.summary);
+        if (routineRun.error)
+            routineRun.error = redactSecretsInText(routineRun.error);
+        out.routineRun = routineRun;
+    }
+    if (out.goalRun) {
+        out.goalRun = {
+            ...out.goalRun,
+            goal: redactSecretsInText(out.goalRun.goal),
+            coordinatorName: redactSecretsInText(out.goalRun.coordinatorName),
+            detail: out.goalRun.detail ? redactSecretsInText(out.goalRun.detail) : undefined,
+        };
+    }
+    if (out.card) {
+        const card = { ...out.card };
+        card.title = redactSecretsInText(card.title);
+        if (typeof card.subtitle === "string")
+            card.subtitle = redactSecretsInText(card.subtitle);
+        if (typeof card.summary === "string")
+            card.summary = redactSecretsInText(card.summary);
+        if (typeof card.held === "string")
+            card.held = redactSecretsInText(card.held);
+        // Routine definitions are executable bot-authored text stored behind the
+        // visible summary. Scrub the durable payload too so nesting it on a card
+        // cannot bypass the transcript's secret-redaction boundary.
+        if (card.routineRequest) {
+            const operation = card.routineRequest.operation;
+            card.routineRequest = {
+                ...card.routineRequest,
+                operation: operation.action === "create"
+                    ? {
+                        ...operation,
+                        routine: {
+                            ...operation.routine,
+                            name: redactSecretsInText(operation.routine.name),
+                            instructions: redactSecretsInText(operation.routine.instructions),
+                        },
+                    }
+                    : operation.action === "update"
+                        ? {
+                            ...operation,
+                            changes: {
+                                ...operation.changes,
+                                ...(typeof operation.changes.name === "string"
+                                    ? { name: redactSecretsInText(operation.changes.name) }
+                                    : {}),
+                                ...(typeof operation.changes.instructions === "string"
+                                    ? { instructions: redactSecretsInText(operation.changes.instructions) }
+                                    : {}),
+                            },
+                        }
+                        : { ...operation },
+            };
+        }
+        if (card.skillRequest) {
+            const originalPreview = card.skillRequest.preview;
+            const preview = originalPreview === undefined
+                ? undefined
+                : redactSecretsInText(originalPreview);
+            // Current skill proposals are scrubbed before staging and their digest
+            // binds the card to the exact SKILL.md bytes that apply will install.
+            // Keep that binding only when this store-wide safety pass is a no-op and
+            // the supplied digest already matches the persisted preview. A caller
+            // that bypassed staging (or an older malformed card) is therefore
+            // safely deny-only instead of showing one document and approving
+            // another.
+            const previewSha256 = preview !== undefined && preview === originalPreview
+                ? createHash("sha256").update(preview).digest("hex")
+                : undefined;
+            const sha256 = card.skillRequest.sha256 !== undefined
+                && card.skillRequest.sha256 === previewSha256
+                ? card.skillRequest.sha256
+                : undefined;
+            card.skillRequest = {
+                ...card.skillRequest,
+                gist: redactSecretsInText(card.skillRequest.gist),
+                source: card.skillRequest.source === undefined
+                    ? undefined
+                    : redactSecretsInText(card.skillRequest.source),
+                preview,
+                sha256,
+                warnings: card.skillRequest.warnings.map((warning) => redactSecretsInText(warning)),
+            };
+        }
+        out.card = card;
+    }
+    if (out.connector) {
+        out.connector = {
+            ...out.connector,
+            label: redactSecretsInText(out.connector.label),
+            description: redactSecretsInText(out.connector.description),
+            error: out.connector.error ? redactSecretsInText(out.connector.error) : undefined,
+        };
+    }
+    if (out.secret) {
+        out.secret = {
+            ...out.secret,
+            label: redactSecretsInText(out.secret.label),
+            description: redactSecretsInText(out.secret.description),
+            error: out.secret.error ? redactSecretsInText(out.secret.error) : undefined,
+        };
+    }
+    return out;
+}
+/** The states in which the bot cannot take a new message. */
+export const ACTIVITY_BUSY = new Set(["working", "waiting-on-you", "no-signal"]);
+/** What a task is called before its first message names it. */
+export const UNTITLED_TASK = "New task";
+/** A task's name, taken from the first thing you asked it to do. */
+export function titleFromMessage(text) {
+    const line = text.trim().split("\n")[0].trim();
+    return line.length > 48 ? `${line.slice(0, 47)}…` : line || UNTITLED_TASK;
+}
+const BOTS_FILE = join(DATA_DIR, "bots.json");
+const GROUPS_FILE = join(DATA_DIR, "groups.json");
+const messagesFile = (threadId) => join(DATA_DIR, `messages-${threadId}.json`);
+const COLORS = [
+    "green",
+    "blue",
+    "red",
+    "orange",
+    "purple",
+    "cyan",
+    "pink",
+    "yellow",
+    "teal",
+    "coral",
+];
+/** Sections are persisted as display labels, so exact trimmed labels are
+ * their identity. Missing/blank means the unsectioned (General) team. */
+export const sectionKey = (section) => section?.trim() || "";
+/** Resolve @mentions in a message against a bot roster: `@` must start a
+ * word, the name must end on a word boundary (so "@New Bottle" never matches
+ * "New Bot"), names match case-insensitively, longest name wins (so
+ * "@New Bot 2" never half-matches "New Bot"), hidden bots skipped, results
+ * deduped. Callers pre-filter the sender out of `peers`. */
+export function mentionedBots(text, peers) {
+    const candidates = peers
+        .filter((p) => !p.hidden && p.name.trim())
+        .sort((a, b) => b.name.length - a.name.length);
+    const lower = text.toLowerCase();
+    const found = [];
+    let at = -1;
+    while ((at = lower.indexOf("@", at + 1)) !== -1) {
+        if (at > 0 && !/\s/.test(text[at - 1]))
+            continue; // user@host, not a tag
+        const rest = lower.slice(at + 1);
+        const hit = candidates.find((p) => {
+            const name = p.name.toLowerCase();
+            if (!rest.startsWith(name))
+                return false;
+            const after = rest[name.length]; // must not run into a longer word
+            return after === undefined || !/[a-z0-9]/i.test(after);
+        });
+        if (hit && !found.includes(hit))
+            found.push(hit);
+    }
+    return found;
+}
+/** Normalize persisted or API-provided routing. Old rooms did not have this
+ * field; giving them their first member as lead fixes the old silent-send
+ * behavior without making every prompt fan out to every model. */
+export function normalizeGroupDefaultResponder(value, memberIds, dm = false) {
+    if (dm)
+        return { kind: "mentions" };
+    if (value && typeof value === "object") {
+        const candidate = value;
+        if (candidate.kind === "everyone")
+            return { kind: "everyone" };
+        if (candidate.kind === "mentions")
+            return { kind: "mentions" };
+        if (candidate.kind === "member" &&
+            typeof candidate.botId === "string" &&
+            memberIds.includes(candidate.botId)) {
+            return { kind: "member", botId: candidate.botId };
+        }
+    }
+    if (memberIds.length === 0)
+        return { kind: "mentions" };
+    return { kind: "member", botId: memberIds[0] };
+}
+/** Resolve the bots invoked by a human room message. Explicit targets win;
+ * otherwise the room policy chooses one member, everyone, or nobody. */
+export function roomResponders(text, members, defaultResponder) {
+    const available = members.filter((member) => !member.hidden);
+    if (/(?:^|\s)@everyone\b/i.test(text))
+        return available;
+    const mentioned = mentionedBots(text, available);
+    if (mentioned.length)
+        return mentioned;
+    if (defaultResponder.kind === "everyone")
+        return available;
+    if (defaultResponder.kind === "member") {
+        const lead = available.find((member) => member.id === defaultResponder.botId);
+        return lead ? [lead] : [];
+    }
+    return [];
+}
+const onboardingCard = () => ({
+    title: "What do you mostly want help with?",
+    subtitle: "Pick whatever's closest; we can always expand from there.",
+    options: ["Work & projects", "Writing & research", "Life admin", "A bit of everything"],
+});
+export class Store {
+    bots = [];
+    groups = [];
+    threads = new Map();
+    defaultSelection;
+    listeners = new Set();
+    constructor(defaultSelection) {
+        this.defaultSelection = defaultSelection;
+        mkdirSync(DATA_DIR, { recursive: true });
+        try {
+            this.bots = JSON.parse(readFileSync(BOTS_FILE, "utf8"));
+        }
+        catch {
+            this.bots = [];
+        }
+        try {
+            this.groups = JSON.parse(readFileSync(GROUPS_FILE, "utf8"));
+        }
+        catch {
+            this.groups = [];
+        }
+        // busy never survives a restart — no turn does either. Rooms saved
+        // before default responders existed adopt their first member as lead.
+        let botsMigrated = false;
+        const browserProfileAliases = loadBrowserProfileIdAliases();
+        const chiefSectionsSeen = new Set();
+        let groupsMigrated = false;
+        for (const b of this.bots) {
+            // transient state never survives a restart — and if a previous
+            // process died mid-turn, bots.json still says busy/working; persist
+            // the reset so the next load does not read it again
+            if (b.busy || (b.activity !== undefined && b.activity !== "idle"))
+                botsMigrated = true;
+            b.busy = false;
+            b.activity = "idle";
+            if (b.browserProfile) {
+                const browserProfile = browserProfileAliases.get(b.browserProfile);
+                if (browserProfile && browserProfile !== b.browserProfile) {
+                    b.browserProfile = browserProfile;
+                    botsMigrated = true;
+                }
+            }
+            if (b.cloudBackend !== undefined && b.cloudBackend !== "box" && b.cloudBackend !== "vps") {
+                delete b.cloudBackend;
+                botsMigrated = true;
+            }
+            if (b.autoStartVps !== undefined && b.autoStartVps !== true && b.autoStartVps !== false) {
+                delete b.autoStartVps;
+                botsMigrated = true;
+            }
+            if (b.approvalMode !== undefined && !isApprovalMode(b.approvalMode)) {
+                delete b.approvalMode;
+                botsMigrated = true;
+            }
+            // A trusted elevation is a prepare/confirm/activate commit. If the
+            // desktop process or its private reply path died before activation,
+            // the durable marker survives beside the mode in the same atomic
+            // bots.json write. Revoke it before schedulers, listeners, or HTTP can
+            // start any new work.
+            if (b.approvalGrant !== undefined) {
+                b.approvalMode = "ask";
+                b.autoApprove = false;
+                delete b.approvalGrant;
+                botsMigrated = true;
+            }
+            const avatar = botAvatarProfile(b);
+            if (b.avatarUrl !== undefined && avatar.avatarUrl !== b.avatarUrl) {
+                delete b.avatarUrl;
+                botsMigrated = true;
+            }
+            if (b.avatarCrop !== undefined && avatar.avatarCrop !== b.avatarCrop) {
+                delete b.avatarCrop;
+                botsMigrated = true;
+            }
+        }
+        for (const b of this.bots) {
+            if (!b.chiefOfStaff)
+                continue;
+            const key = sectionKey(b.section);
+            if (!chiefSectionsSeen.has(key)) {
+                chiefSectionsSeen.add(key);
+                if (b.hidden) {
+                    b.hidden = false;
+                    botsMigrated = true;
+                }
+                continue;
+            }
+            b.chiefOfStaff = false;
+            botsMigrated = true;
+        }
+        // Peer grants originally used mutable display names (ask_bot:@Helper).
+        // Convert only when exactly one bot has that name; ambiguous legacy
+        // entries remain inert rather than granting access to the wrong bot.
+        for (const b of this.bots) {
+            if (!b.alwaysAllow?.length)
+                continue;
+            let changed = false;
+            const migrated = b.alwaysAllow.map((key) => {
+                const match = key.match(/^(ask_bot|delegate_bot):@(.+)$/);
+                if (!match)
+                    return key;
+                const candidates = this.bots.filter((candidate) => candidate.name === match[2]);
+                if (candidates.length !== 1)
+                    return key;
+                changed = true;
+                return peerAllowKey(match[1], candidates[0].id);
+            });
+            if (changed) {
+                b.alwaysAllow = [...new Set(migrated)];
+                botsMigrated = true;
+            }
+        }
+        for (const g of this.groups) {
+            g.busyBotId = null;
+            const normalized = normalizeGroupDefaultResponder(g.defaultResponder, g.memberIds, Boolean(g.dm));
+            if (JSON.stringify(normalized) !== JSON.stringify(g.defaultResponder))
+                groupsMigrated = true;
+            g.defaultResponder = normalized;
+            // Bot-to-bot channels intentionally remain one canonical thread.
+            if (g.dm) {
+                if (g.tasks !== undefined) {
+                    delete g.tasks;
+                    groupsMigrated = true;
+                }
+                continue;
+            }
+            if (!g.tasks?.length) {
+                const initialTask = {
+                    threadId: g.threadId,
+                    title: this.firstUserLine(g.threadId) ?? UNTITLED_TASK,
+                    createdAt: g.createdAt,
+                };
+                if (g.pinnedCwd !== undefined)
+                    initialTask.pinnedCwd = g.pinnedCwd;
+                if (g.pinnedMessageId)
+                    initialTask.pinnedMessageId = g.pinnedMessageId;
+                g.tasks = [initialTask];
+                groupsMigrated = true;
+            }
+            // Repair a malformed/stale active pointer conservatively. Every task
+            // transcript is retained; the newest known task becomes active.
+            let active = g.tasks.find((task) => task.threadId === g.threadId);
+            if (!active) {
+                active = g.tasks[0];
+                g.threadId = active.threadId;
+                groupsMigrated = true;
+            }
+            g.pinnedCwd = active.pinnedCwd;
+            g.pinnedMessageId = active.pinnedMessageId;
+        }
+        if (botsMigrated)
+            this.saveBots();
+        if (groupsMigrated)
+            this.saveGroups();
+        // bots saved before tasks existed have one endless thread; adopt it as
+        // their first task so nothing is lost and nothing special-cases it
+        for (const b of this.bots) {
+            if (b.tasks?.length)
+                continue;
+            b.tasks = [
+                {
+                    threadId: b.threadId,
+                    title: this.firstUserLine(b.threadId) ?? UNTITLED_TASK,
+                    createdAt: b.createdAt,
+                    resumeCursors: b.resumeCursors ?? {},
+                },
+            ];
+        }
+        // Search reads SQLite directly, so migrate every known legacy transcript
+        // at startup rather than waiting until the user happens to open it. Only
+        // pending JSON files are touched; already-migrated threads stay lazy.
+        const knownThreads = new Set([
+            ...this.bots.flatMap((b) => [b.threadId, ...(b.tasks ?? []).map((task) => task.threadId)]),
+            ...this.groups.flatMap((group) => [group.threadId, ...(group.tasks ?? []).map((task) => task.threadId)]),
+        ]);
+        for (const threadId of knownThreads) {
+            const legacyFile = messagesFile(threadId);
+            if (existsSync(legacyFile))
+                mdb.readThread(threadId, legacyFile);
+        }
+    }
+    saveBots(bots = this.bots) {
+        writeFileAtomic(BOTS_FILE, JSON.stringify(bots, null, 2));
+    }
+    saveGroups() {
+        writeFileAtomic(GROUPS_FILE, JSON.stringify(this.groups.map(({ busyBotId: _busyBotId, ...g }) => g), null, 2));
+    }
+    // ── groups ────────────────────────────────────────────────────────────
+    /** Subscribe to every write. Listeners run after the write and after
+     * save; a throwing listener never breaks the write. */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emit(change) {
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(change);
+            }
+            catch (error) {
+                console.error("store: change listener threw", error);
+            }
+        }
+    }
+    group(id) {
+        return this.groups.find((g) => g.id === id);
+    }
+    groupByThread(threadId) {
+        return this.groups.find((group) => group.threadId === threadId || group.tasks?.some((task) => task.threadId === threadId));
+    }
+    createGroup(name, memberIds, dm = false, section, setup) {
+        const threadId = newId();
+        const createdAt = Date.now();
+        const group = {
+            id: newId(),
+            threadId,
+            name,
+            memberIds,
+            defaultResponder: dm
+                ? { kind: "mentions" }
+                : normalizeGroupDefaultResponder(setup?.defaultResponder, memberIds, false),
+            bulletin: setup?.bulletin ?? "",
+            unread: false,
+            createdAt,
+            dm: dm || undefined,
+            busyBotId: null,
+            section,
+        };
+        if (!dm) {
+            group.tasks = [{ threadId, title: UNTITLED_TASK, createdAt }];
+            group.setupCompletedAt = setup?.completed ? createdAt : null;
+            group.setupSkippedAt = null;
+        }
+        this.groups.unshift(group);
+        this.saveGroups();
+        this.emit({ type: "group", groupId: group.id });
+        return group;
+    }
+    /** The bot⇄bot channel for a pair, if it exists (order-insensitive). */
+    dmGroup(a, b) {
+        return this.groups.find((g) => g.dm && g.memberIds.length === 2 && g.memberIds.includes(a) && g.memberIds.includes(b));
+    }
+    patchGroup(id, patch) {
+        const group = this.group(id);
+        if (!group)
+            return null;
+        Object.assign(group, patch);
+        if (!group.dm && Object.prototype.hasOwnProperty.call(patch, "pinnedMessageId")) {
+            const active = this.activeGroupTask(group.id);
+            if (active)
+                active.pinnedMessageId = patch.pinnedMessageId;
+        }
+        group.defaultResponder = normalizeGroupDefaultResponder(group.defaultResponder, group.memberIds, Boolean(group.dm));
+        this.saveGroups();
+        this.emit({ type: "group", groupId: group.id });
+        return group;
+    }
+    /** A thread's durable record: DB rows plus any legacy JSON leftovers. */
+    deleteThreadRecord(threadId) {
+        this.threads.delete(threadId);
+        mdb.deleteThread(threadId);
+        for (const file of [messagesFile(threadId), `${messagesFile(threadId)}.imported`]) {
+            try {
+                unlinkSync(file);
+            }
+            catch { }
+        }
+        this.emit({ type: "thread.deleted", threadId });
+    }
+    deleteGroup(id) {
+        const group = this.group(id);
+        if (!group)
+            return false;
+        this.groups = this.groups.filter((g) => g.id !== id);
+        this.saveGroups();
+        for (const threadId of new Set([group.threadId, ...(group.tasks ?? []).map((task) => task.threadId)])) {
+            this.deleteThreadRecord(threadId);
+        }
+        this.emit({ type: "group.deleted", groupId: id });
+        return true;
+    }
+    /** A process restart cannot preserve an in-flight room orchestrator. Close
+     * every durable working receipt before clients load it, including manual
+     * goals that do not have a RoutineRun record to reconcile separately. */
+    reconcileInterruptedGroupGoals(resolve, fallbackDetail = "OpenMausBot restarted before this goal finished.", fallbackFinishedAt = Date.now()) {
+        const ownedThreadIds = new Set();
+        for (const group of this.groups) {
+            ownedThreadIds.add(group.threadId);
+            for (const task of group.tasks ?? [])
+                ownedThreadIds.add(task.threadId);
+        }
+        // load() already migrated every legacy transcript file into SQLite, so
+        // this recovery query is proportional to unfinished goals, not history.
+        let recovered = 0;
+        for (const hit of mdb.workingGoalRunMessages()) {
+            if (!ownedThreadIds.has(hit.threadId) || !hit.message.goalRun)
+                continue;
+            const resolution = resolve?.(hit.message.goalRun.runId, hit.threadId) ?? {
+                status: "failed",
+                detail: fallbackDetail,
+                finishedAt: fallbackFinishedAt,
+            };
+            const state = resolution.status === "needs-input"
+                ? "needs your input"
+                : resolution.status === "limit-reached"
+                    ? "reached its turn limit"
+                    : resolution.status;
+            this.patchMessage(hit.threadId, hit.message.id, {
+                text: `Goal ${state}: ${resolution.detail}`,
+                goalRun: {
+                    ...hit.message.goalRun,
+                    status: resolution.status,
+                    detail: resolution.detail,
+                    finishedAt: resolution.finishedAt,
+                },
+            });
+            recovered += 1;
+        }
+        return recovered;
+    }
+    // ── channel tasks ────────────────────────────────────────────────────
+    groupTasks(groupId) {
+        const group = this.group(groupId);
+        return group?.dm ? [] : (group?.tasks ?? []);
+    }
+    activeGroupTask(groupId) {
+        const group = this.group(groupId);
+        return group?.tasks?.find((task) => task.threadId === group.threadId);
+    }
+    groupTaskByThread(groupId, threadId) {
+        const group = this.group(groupId);
+        if (!group || group.dm)
+            return undefined;
+        return group.tasks?.find((task) => task.threadId === threadId);
+    }
+    createGroupTask(groupId, title, activate = true) {
+        const group = this.group(groupId);
+        if (!group || group.dm)
+            return null;
+        const task = {
+            threadId: newId(),
+            title: title?.trim().slice(0, 80) || UNTITLED_TASK,
+            createdAt: Date.now(),
+        };
+        group.tasks = [task, ...(group.tasks ?? [])];
+        if (activate) {
+            group.threadId = task.threadId;
+            group.pinnedCwd = undefined;
+            group.pinnedMessageId = undefined;
+        }
+        this.saveGroups();
+        this.emit({ type: "group", groupId });
+        return task;
+    }
+    switchGroupTask(groupId, threadId) {
+        const group = this.group(groupId);
+        const task = group?.tasks?.find((candidate) => candidate.threadId === threadId);
+        if (!group || group.dm || !task)
+            return null;
+        group.threadId = task.threadId;
+        group.pinnedCwd = task.pinnedCwd;
+        group.pinnedMessageId = task.pinnedMessageId;
+        this.saveGroups();
+        this.emit({ type: "group", groupId });
+        return group;
+    }
+    renameGroupTask(groupId, threadId, title) {
+        const task = this.groupTaskByThread(groupId, threadId);
+        if (!task)
+            return null;
+        task.title = title.trim().slice(0, 80) || UNTITLED_TASK;
+        this.saveGroups();
+        this.emit({ type: "group", groupId });
+        return task;
+    }
+    titleGroupTaskFromFirstMessage(groupId, text, threadId) {
+        const task = threadId ? this.groupTaskByThread(groupId, threadId) : this.activeGroupTask(groupId);
+        if (!task || task.title !== UNTITLED_TASK)
+            return;
+        task.title = titleFromMessage(text);
+        this.saveGroups();
+        this.emit({ type: "group", groupId });
+    }
+    deleteGroupTask(groupId, threadId) {
+        const group = this.group(groupId);
+        if (!group || group.dm || !group.tasks || group.tasks.length < 2)
+            return null;
+        if (!group.tasks.some((task) => task.threadId === threadId))
+            return null;
+        group.tasks = group.tasks.filter((task) => task.threadId !== threadId);
+        this.deleteThreadRecord(threadId);
+        if (group.threadId === threadId) {
+            const next = group.tasks[0];
+            group.threadId = next.threadId;
+            group.pinnedCwd = next.pinnedCwd;
+            group.pinnedMessageId = next.pinnedMessageId;
+        }
+        this.saveGroups();
+        this.emit({ type: "group", groupId });
+        return group;
+    }
+    /** Toggle an emoji reaction on a message ("user" or a member botId). */
+    toggleReaction(threadId, messageId, emoji, by) {
+        const existing = this.messagesFor(threadId).find((m) => m.id === messageId);
+        if (!existing)
+            return null;
+        const reactions = existing.reactions ?? [];
+        const at = reactions.findIndex((r) => r.emoji === emoji && r.by === by);
+        const next = at >= 0 ? reactions.filter((_, i) => i !== at) : [...reactions, { emoji, by }];
+        return this.patchMessage(threadId, messageId, { reactions: next.length ? next : undefined });
+    }
+    thread(threadId) {
+        let t = this.threads.get(threadId);
+        if (t)
+            return t;
+        // SQLite is the source of truth; a thread with no rows imports its
+        // legacy messages-<threadId>.json once, inside readThread
+        const { messages, activeLeafId: storedLeaf } = mdb.readThread(threadId, messagesFile(threadId));
+        let activeLeafId = storedLeaf;
+        // legacy rows carry no parentId — chain them in array order
+        let prev = null;
+        for (const m of messages) {
+            if (m.parentId === undefined)
+                m.parentId = prev;
+            prev = m.id;
+        }
+        if (!activeLeafId)
+            activeLeafId = messages.at(-1)?.id ?? null;
+        t = { messages, activeLeafId };
+        this.threads.set(threadId, t);
+        return t;
+    }
+    messagesFor(threadId) {
+        return this.thread(threadId).messages;
+    }
+    /** Used only with newly allocated import threads. No live actions are
+     * replayed: the importer supplies inert text and freshly remapped IDs. */
+    importTranscript(threadId, messages, activeLeafId) {
+        if (this.messagesFor(threadId).length)
+            throw new Error("Cannot import over an existing conversation");
+        mdb.importThread(threadId, messages, activeLeafId);
+        this.threads.delete(threadId);
+    }
+    activeLeaf(threadId) {
+        return this.thread(threadId).activeLeafId;
+    }
+    /** The visible conversation: root → activeLeafId. */
+    activePath(threadId) {
+        const t = this.thread(threadId);
+        const byId = new Map(t.messages.map((m) => [m.id, m]));
+        const path = [];
+        let cur = t.activeLeafId ? byId.get(t.activeLeafId) : undefined;
+        while (cur) {
+            path.push(cur);
+            cur = cur.parentId ? byId.get(cur.parentId) : undefined;
+        }
+        return path.reverse();
+    }
+    /** Mark the last assistant text on the active branch as this turn's final
+     * visible answer. If a provider ends after commentary without emitting a
+     * separate answer, that commentary remains visible as the safe fallback. */
+    markTerminalAssistantMessage(threadId, turnId) {
+        const path = this.activePath(threadId);
+        for (let i = path.length - 1; i >= 0; i -= 1) {
+            const message = path[i];
+            if (message.role === "bot" && message.kind === "text" && message.turnId === turnId) {
+                if (message.turnTerminal)
+                    return message;
+                return this.patchMessage(threadId, message.id, { turnTerminal: true });
+            }
+        }
+        return null;
+    }
+    appendMessage(threadId, message) {
+        const t = this.thread(threadId);
+        const full = { id: newId(), at: Date.now(), parentId: t.activeLeafId, ...redactBotAuthored(message) };
+        t.messages.push(full);
+        t.activeLeafId = full.id;
+        mdb.appendMessage(threadId, full);
+        if (full.kind === "screen") {
+            for (const pruned of this.pruneScreenFrames(t)) {
+                mdb.updateMessage(threadId, pruned);
+                this.emit({ type: "message.patch", threadId, message: pruned });
+            }
+        }
+        this.emit({ type: "message", threadId, message: full });
+        // The first-run quiz is not a live ask. Talking past it hides it so the
+        // transcript is just the greeting plus what they said. Cards with a
+        // requestId are permission/question prompts and stay until answered.
+        if (full.role === "user" && full.kind === "text")
+            this.dismissOnboardingCard(threadId);
+        return full;
+    }
+    /** Insert a message into the active chain directly after `anchorId` — the
+     * home for turn artifacts that finish AFTER the world moved on (the
+     * settle-time screen capture races a fast follow-up send, which used to
+     * leave the user's message stranded above the screenshot). When the anchor
+     * is still the leaf this is a plain append; otherwise the anchor's
+     * children are re-parented onto the inserted message, so the transcript
+     * reads turn → artifact → follow-up and the leaf stays where it was. */
+    insertMessageAfter(threadId, anchorId, message) {
+        const t = this.thread(threadId);
+        const anchorExists = anchorId !== undefined && t.messages.some((m) => m.id === anchorId);
+        if (!anchorExists || t.activeLeafId === anchorId)
+            return this.appendMessage(threadId, message);
+        const full = { id: newId(), at: Date.now(), ...redactBotAuthored(message), parentId: anchorId };
+        const children = t.messages.filter((m) => m.parentId === anchorId);
+        t.messages.push(full);
+        mdb.appendMessage(threadId, full);
+        if (full.kind === "screen") {
+            for (const pruned of this.pruneScreenFrames(t)) {
+                mdb.updateMessage(threadId, pruned);
+                this.emit({ type: "message.patch", threadId, message: pruned });
+            }
+        }
+        this.emit({ type: "message", threadId, message: full });
+        // announced after the insert so no client ever sees two siblings
+        // claiming the same parent
+        for (const child of children)
+            this.patchMessage(threadId, child.id, { parentId: full.id });
+        return full;
+    }
+    /** Hide the first-run quiz on this thread, if it is still open. */
+    dismissOnboardingCard(threadId) {
+        const t = this.thread(threadId);
+        const card = t.messages.find((message) => message.kind === "options" && message.card && !message.card.requestId && !message.card.dismissed);
+        if (!card?.card)
+            return null;
+        return this.patchMessage(threadId, card.id, { card: { ...card.card, dismissed: true } });
+    }
+    /** Screen frames are ~100-500KB of base64 each; keeping every frame of a
+     * long computer session bloats the transcript for nothing the client
+     * would ever show. The newest few keep their pixels; older ones stay in
+     * the transcript as placeholders. Mirrors the client's own frame cap.
+     * Returns the messages whose pixels were dropped so the caller can
+     * persist exactly those. */
+    pruneScreenFrames(t, keep = 4) {
+        const pruned = [];
+        let seen = 0;
+        for (let i = t.messages.length - 1; i >= 0 && seen < t.messages.length; i--) {
+            const m = t.messages[i];
+            if (m.kind !== "screen" || !m.png)
+                continue;
+            seen += 1;
+            if (seen > keep) {
+                m.png = undefined;
+                pruned.push(m);
+            }
+        }
+        return pruned;
+    }
+    /** Fork the conversation: a new user message that replaces `sourceId`
+     * (same parent, new text) and becomes the active leaf. */
+    branchMessage(threadId, sourceId, text) {
+        const t = this.thread(threadId);
+        const source = t.messages.find((m) => m.id === sourceId);
+        if (!source)
+            return null;
+        const full = {
+            id: newId(),
+            at: Date.now(),
+            role: "user",
+            kind: "text",
+            text,
+            parentId: source.parentId ?? null,
+            replyToId: source.replyToId,
+        };
+        t.messages.push(full);
+        t.activeLeafId = full.id;
+        mdb.appendMessage(threadId, full);
+        this.emit({ type: "message", threadId, message: full });
+        return full;
+    }
+    /** Point the visible conversation at the branch containing `messageId`,
+     * descending to that branch's most recently active leaf. */
+    setActiveLeaf(threadId, messageId) {
+        const t = this.thread(threadId);
+        if (!t.messages.some((m) => m.id === messageId))
+            return null;
+        let cur = messageId;
+        for (;;) {
+            const children = t.messages.filter((m) => m.parentId === cur);
+            if (!children.length)
+                break;
+            cur = children.reduce((a, b) => (b.at >= a.at ? b : a)).id;
+        }
+        t.activeLeafId = cur;
+        mdb.setActiveLeaf(threadId, cur);
+        this.emit({ type: "thread", threadId, activeLeafId: cur });
+        return cur;
+    }
+    patchMessage(threadId, messageId, patch) {
+        const t = this.thread(threadId);
+        const idx = t.messages.findIndex((m) => m.id === messageId);
+        if (idx === -1)
+            return null;
+        const next = { ...t.messages[idx], ...patch, card: patch.card ?? t.messages[idx].card };
+        // SQLite is the durable source of truth. Persist before changing memory so
+        // a failed write cannot make this process believe a card was answered
+        // while a restart would still show it as pending.
+        mdb.updateMessage(threadId, next);
+        t.messages[idx] = next;
+        this.emit({ type: "message.patch", threadId, message: next });
+        return next;
+    }
+    bot(id) {
+        return this.bots.find((b) => b.id === id) ?? null;
+    }
+    botByThread(threadId) {
+        return this.bots.find((b) => b.threadId === threadId || b.tasks?.some((t) => t.threadId === threadId)) ?? null;
+    }
+    createBot(profile = {}, opts = {}) {
+        const name = profile.name?.trim() || pickBotName(this.bots.map((b) => b.name));
+        const section = sectionKey(profile.section);
+        const bot = {
+            id: newId(),
+            threadId: newId(),
+            name,
+            title: profile.title ?? "",
+            description: profile.description ?? "",
+            notifications: true,
+            color: profile.color ?? COLORS[this.bots.length % COLORS.length],
+            ...(profile.mascotExpression ? { mascotExpression: profile.mascotExpression } : {}),
+            ...(profile.mascotBody ? { mascotBody: profile.mascotBody } : {}),
+            unread: false,
+            modelSelection: profile.modelSelection ?? this.defaultSelection(),
+            resumeCursors: {},
+            createdAt: Date.now(),
+        };
+        if (section)
+            bot.section = section;
+        bot.tasks = [{ threadId: bot.threadId, title: UNTITLED_TASK, createdAt: bot.createdAt, resumeCursors: {} }];
+        this.bots.unshift(bot);
+        this.saveBots();
+        // Announce the owner before its onboarding transcript. SSE clients need
+        // the bot/thread mapping before they can place either message.
+        this.emit({ type: "bot", botId: bot.id });
+        if (opts.seedMessages !== false) {
+            this.appendMessage(bot.threadId, {
+                role: "bot",
+                kind: "text",
+                text: `Hey — I'm ${name}. Nice to meet you.`,
+            });
+            this.appendMessage(bot.threadId, { role: "bot", kind: "options", card: onboardingCard() });
+        }
+        return bot;
+    }
+    deleteBot(id) {
+        const bot = this.bot(id);
+        if (!bot)
+            return false;
+        this.bots = this.bots.filter((b) => b.id !== id);
+        // every task's transcript goes with the bot, not just the open one
+        for (const threadId of new Set([bot.threadId, ...(bot.tasks ?? []).map((t) => t.threadId)])) {
+            this.deleteThreadRecord(threadId);
+        }
+        // the bot's workspace (files + memory) goes with it — same rule as its
+        // transcripts: deleting a bot deletes what it knew
+        try {
+            rmSync(workspaceDir(id), { recursive: true, force: true });
+        }
+        catch { }
+        // Approval state deliberately lives outside the bot-writable workspace.
+        // It still belongs to the bot, so deleting the bot must remove staged
+        // proposals, manifests, and native-link ownership records with it.
+        try {
+            rmSync(join(DATA_DIR, "skill-state", id), { recursive: true, force: true });
+        }
+        catch { }
+        this.saveBots();
+        this.emit({ type: "bot.deleted", botId: id });
+        return true;
+    }
+    patchBot(id, patch) {
+        const bot = this.bot(id);
+        if (!bot)
+            return null;
+        Object.assign(bot, patch);
+        this.saveBots();
+        this.emit({ type: "bot", botId: id });
+        return bot;
+    }
+    /** File visible bots into one sidebar section as a single durable write.
+     *
+     * This deliberately stages the complete next file before touching the
+     * live records. A missing/hidden target therefore changes nothing, and a
+     * failed atomic write cannot leave memory ahead of disk. A Chief collision
+     * is refused rather than silently removing somebody's coordinator role. */
+    setBotsSection(botIds, section) {
+        const ids = [...new Set(botIds)];
+        const targets = ids.map((id) => this.bot(id));
+        if (targets.some((bot) => !bot || bot.hidden))
+            return { ok: false, reason: "unavailable" };
+        const targetSection = sectionKey(section);
+        const selected = targets;
+        const destinationChiefIds = new Set([
+            ...selected.filter((bot) => bot.chiefOfStaff).map((bot) => bot.id),
+            ...this.bots
+                .filter((bot) => bot.chiefOfStaff && sectionKey(bot.section) === targetSection)
+                .map((bot) => bot.id),
+        ]);
+        if (destinationChiefIds.size > 1)
+            return { ok: false, reason: "chief-conflict" };
+        const patches = new Map();
+        for (const bot of selected) {
+            patches.set(bot.id, { section: targetSection || undefined });
+        }
+        const changedIds = new Set();
+        const nextBots = this.bots.map((bot) => {
+            const patch = patches.get(bot.id);
+            if (!patch)
+                return bot;
+            const next = { ...bot, ...patch };
+            if (JSON.stringify(next) !== JSON.stringify(bot))
+                changedIds.add(bot.id);
+            return next;
+        });
+        if (changedIds.size) {
+            this.saveBots(nextBots);
+            for (const bot of this.bots) {
+                const patch = patches.get(bot.id);
+                if (patch)
+                    Object.assign(bot, patch);
+            }
+            for (const botId of changedIds)
+                this.emit({ type: "bot", botId });
+        }
+        return { ok: true, bots: ids.map((id) => this.bot(id)) };
+    }
+    /** The one way runtime state changes. Sets `activity` and derives `busy`
+     * from it, so a reader that only knows busy sees the same truth. */
+    setActivity(botId, activity) {
+        const bot = this.bot(botId);
+        if (!bot)
+            return null;
+        const busy = ACTIVITY_BUSY.has(activity);
+        if (bot.activity === activity && Boolean(bot.busy) === busy)
+            return bot;
+        bot.activity = activity;
+        bot.busy = busy;
+        this.saveBots();
+        this.emit({ type: "bot", botId });
+        return bot;
+    }
+    /** Elect one Chief of Staff in its section (or clear one section) as one persisted change.
+     * The changed records are returned so the server can update every open
+     * window, including the bot that just handed the role over. */
+    setChiefOfStaff(id, section) {
+        const selected = id ? this.bot(id) : null;
+        if (id && !selected)
+            return null;
+        const targetSection = sectionKey(selected?.section ?? section);
+        const changed = [];
+        for (const bot of this.bots) {
+            if (sectionKey(bot.section) !== targetSection)
+                continue;
+            const next = bot.id === id;
+            if (Boolean(bot.chiefOfStaff) === next && !(next && bot.hidden))
+                continue;
+            if (next) {
+                bot.chiefOfStaff = true;
+                // A section's main contact must stay reachable in the sidebar.
+                bot.hidden = false;
+            }
+            else {
+                bot.chiefOfStaff = false;
+            }
+            changed.push(bot);
+        }
+        if (changed.length)
+            this.saveBots();
+        for (const bot of changed)
+            this.emit({ type: "bot", botId: bot.id });
+        return changed;
+    }
+    setResumeCursor(botId, instanceId, cursor, threadId) {
+        const bot = this.bot(botId);
+        if (!bot)
+            return;
+        // the cursor belongs to the task that produced it, not to the bot
+        const task = threadId ? this.taskByThread(botId, threadId) : this.activeTask(botId);
+        if (task)
+            task.resumeCursors[instanceId] = cursor;
+        // The legacy mirror follows the task visible in chat, never a detached
+        // routine task working in the background.
+        if (!threadId || bot.threadId === threadId)
+            bot.resumeCursors[instanceId] = cursor;
+        this.saveBots();
+        this.emit({ type: "bot", botId });
+    }
+    /** Record which instance just took a turn on this task. Called at
+     * dispatch, not at cursor time — transcript-replay engines never
+     * produce a cursor, and they still count as having run last. */
+    markTaskDispatched(botId, threadId, instanceId) {
+        const task = this.taskByThread(botId, threadId);
+        if (!task || task.lastInstanceId === instanceId)
+            return;
+        task.lastInstanceId = instanceId;
+        this.saveBots();
+    }
+    /** Bank one settled turn onto its task. Called once per turn.completed;
+     * the running per-driver token indicator is deliberately not used here
+     * because its meaning differs by driver. */
+    addTaskUsage(botId, threadId, turn) {
+        const task = this.taskByThread(botId, threadId);
+        if (!task)
+            return null;
+        const prev = { input: 0, output: 0, costUsd: null, turns: 0, ...task.usage };
+        const cost = typeof turn.costUsd === "number" && Number.isFinite(turn.costUsd) ? turn.costUsd : null;
+        const prevCost = typeof prev.costUsd === "number" ? prev.costUsd : null;
+        // providers occasionally report NaN or a negative on a partial turn —
+        // never let that poison a running tally
+        const clean = (n) => (typeof n === "number" && Number.isFinite(n) ? Math.max(0, Math.trunc(n)) : 0);
+        // the cached share exists on a record only once a driver has reported
+        // it — a driver that never does leaves the record shaped as before
+        const cachedKnown = typeof prev.cachedInput === "number" || typeof turn.cachedInput === "number";
+        const prevInput = clean(prev.input);
+        const turnInput = clean(turn.input);
+        const nextCachedInput = Math.min(clean(prev.cachedInput), prevInput)
+            + Math.min(clean(turn.cachedInput), turnInput);
+        task.usage = {
+            input: prevInput + turnInput,
+            output: prev.output + clean(turn.output),
+            ...(cachedKnown ? { cachedInput: nextCachedInput } : {}),
+            costUsd: cost === null ? prevCost : (prevCost ?? 0) + cost,
+            turns: prev.turns + 1,
+        };
+        this.saveBots();
+        this.emit({ type: "bot", botId });
+        return task.usage;
+    }
+    /** The folder a task's turn runs in. Pins on first call from the bot's
+     * current folder — unless the task already has a session (a thread from
+     * before folders existed), which pins to the default so the folder can't
+     * move under it. Returns the pinned value: a path, or null for default. */
+    pinTaskCwd(botId, threadId, fallbackCwd, opts = {}) {
+        const bot = this.bot(botId);
+        const task = bot ? this.taskByThread(botId, threadId) : undefined;
+        if (!bot || !task)
+            return null;
+        if (opts.none) {
+            if (task.cwd !== null) {
+                task.cwd = null;
+                this.saveBots();
+                this.emit({ type: "bot", botId });
+            }
+            return null;
+        }
+        if (task.cwd === undefined) {
+            task.cwd = Object.keys(task.resumeCursors).length === 0 ? (bot.cwd ?? fallbackCwd ?? null) : null;
+            this.saveBots();
+            this.emit({ type: "bot", botId });
+        }
+        return task.cwd;
+    }
+    /** The folder a room's member turns run in. Pins on the first turn that
+     * dispatches, from the room's `cwd` at that moment. Pinned, not read
+     * live, for the same reason tasks pin (see pinTaskCwd): engines key
+     * their sessions and files to the folder a thread starts in, and a room
+     * lives on ONE thread forever — so changing the room's folder applies to
+     * future rooms, never under a room that already started working
+     * somewhere. Returns the pinned value: a path, or null = each member's
+     * own default. */
+    pinGroupCwd(groupId, threadId) {
+        const group = this.group(groupId);
+        if (!group)
+            return null;
+        const task = threadId ? this.groupTaskByThread(groupId, threadId) : this.activeGroupTask(groupId);
+        // Direct-message channels retain the original single-thread contract.
+        if (!task) {
+            if (!group.dm)
+                return null;
+            if (group.pinnedCwd === undefined) {
+                group.pinnedCwd = group.cwd ?? null;
+                this.saveGroups();
+                this.emit({ type: "group", groupId: group.id });
+            }
+            return group.pinnedCwd;
+        }
+        if (task.pinnedCwd === undefined) {
+            task.pinnedCwd = group.cwd ?? null;
+            if (group.threadId === task.threadId)
+                group.pinnedCwd = task.pinnedCwd;
+            this.saveGroups();
+            this.emit({ type: "group", groupId: group.id });
+        }
+        return task.pinnedCwd;
+    }
+    // ── tasks ─────────────────────────────────────────────────────────────
+    /** The first thing the human asked in a thread — a task's natural name. */
+    firstUserLine(threadId) {
+        const first = this.messagesFor(threadId).find((m) => m.role === "user" && m.kind === "text" && m.text?.trim());
+        return first?.text ? titleFromMessage(first.text) : null;
+    }
+    tasks(botId) {
+        return this.bot(botId)?.tasks ?? [];
+    }
+    activeTask(botId) {
+        const bot = this.bot(botId);
+        return bot?.tasks?.find((t) => t.threadId === bot.threadId);
+    }
+    taskByThread(botId, threadId) {
+        return this.bot(botId)?.tasks?.find((t) => t.threadId === threadId);
+    }
+    /** A fresh context on the same bot: new thread, new session, same
+     * persona/tools/computer. Becomes the active task. */
+    createTask(botId, title, activate = true) {
+        const bot = this.bot(botId);
+        if (!bot)
+            return null;
+        const task = {
+            threadId: newId(),
+            title: title?.trim() || UNTITLED_TASK,
+            createdAt: Date.now(),
+            resumeCursors: {},
+        };
+        bot.tasks = [task, ...(bot.tasks ?? [])];
+        if (activate) {
+            bot.threadId = task.threadId;
+            bot.resumeCursors = {}; // legacy mirror follows the active task
+        }
+        this.saveBots();
+        this.emit({ type: "bot", botId });
+        return task;
+    }
+    switchTask(botId, threadId) {
+        const bot = this.bot(botId);
+        const task = bot?.tasks?.find((t) => t.threadId === threadId);
+        if (!bot || !task)
+            return null;
+        bot.threadId = task.threadId;
+        bot.resumeCursors = { ...task.resumeCursors };
+        this.saveBots();
+        this.emit({ type: "bot", botId });
+        return bot;
+    }
+    renameTask(botId, threadId, title) {
+        const task = this.bot(botId)?.tasks?.find((t) => t.threadId === threadId);
+        if (!task)
+            return null;
+        task.title = title.trim().slice(0, 80) || UNTITLED_TASK;
+        this.saveBots();
+        this.emit({ type: "bot", botId });
+        return task;
+    }
+    /** Name a task after its first message, once. */
+    titleTaskFromFirstMessage(botId, text, threadId) {
+        const task = threadId ? this.taskByThread(botId, threadId) : this.activeTask(botId);
+        if (!task || task.title !== UNTITLED_TASK)
+            return;
+        task.title = titleFromMessage(text);
+        this.saveBots();
+        this.emit({ type: "bot", botId });
+    }
+    /** Delete a task and its transcript. A bot always keeps one. */
+    deleteTask(botId, threadId) {
+        const bot = this.bot(botId);
+        if (!bot || !bot.tasks || bot.tasks.length < 2)
+            return null;
+        if (!bot.tasks.some((t) => t.threadId === threadId))
+            return null;
+        bot.tasks = bot.tasks.filter((t) => t.threadId !== threadId);
+        this.deleteThreadRecord(threadId);
+        if (bot.threadId === threadId) {
+            bot.threadId = bot.tasks[0].threadId;
+            bot.resumeCursors = { ...bot.tasks[0].resumeCursors };
+        }
+        this.saveBots();
+        this.emit({ type: "bot", botId });
+        return bot;
+    }
+    /** First-run seed: one bot so the app never opens empty — it gets a
+     * random friendly name like every other bot. */
+    seedIfEmpty() {
+        if (this.bots.length)
+            return;
+        this.createBot();
+    }
+}