openmausbot 0.1.68 → 0.1.70

package/dist-server/server/index.js

@@ -21,7 +21,7 @@ import { appendDecision, readDecisions } from "./decision-log.js";
 import { validateBotCwd } from "./bot-cwd.js";
 import { ATTACHMENTS_DIR, attachmentExists, cleanupStaleAttachmentPartials, deleteAttachment, extensionForMime, FILE_MAX_BYTES, IMAGE_MAX_BYTES, readAttachment, saveFile, saveImage, saveImageUpload, validateAttachmentUploadId, } from "./attachments.js";
 import { messageFileDisposition, messageFileDownloadName, messageAttachmentName, messageFileRoots, messageImageTargetAt, messageReferencesFile, openMessageFile, } from "./message-file.js";
-import { avatarGenerationRequestSchema, avatarGenerationStateMatches, generateAvatarImage, snapshotAvatarGenerationState, } from "./avatar-image.js";
+import { avatarGenerationRequestSchema, avatarGenerationStateMatches, generateAvatarImage, avatarImageStatus, snapshotAvatarGenerationState, } from "./avatar-image.js";
 import { fitsOnOneLine, parseBotProfilePatch } from "./bot-profile.js";
 import { groupTurnCwd } from "./room-cwd.js";
 import { RoomTurnDeadline, RoomTurnStallRegistry, roomTurnTimeoutMessage } from "./room-turn-timeout.js";
@@ -37,6 +37,7 @@ import { ensureDirs, instanceConfigs, loadConfig, localVmMaxInstances, localVmMo
 import { ComputerControl } from "./computer-control.js";
 import { MAX_REMOTE_COMMAND_LENGTH } from "./remote-computer.js";
 import { augmentedPath, findCliCandidates, resetPathCache } from "./env-path.js";
+import { registerEnginesBinDir } from "./engine-install.js";
 import { describeSpawnFailure, execCli } from "./procs.js";
 import { blockedTarget, buildNotification } from "./notify.js";
 import { isEffortLevel, newId, } from "./contracts.js";
@@ -54,7 +55,7 @@ import { claimRecallCrossings, recallCrossingLabel } from "./recall-disclosure.j
 const SESSION_READ_MAX_CHARS = 8_000;
 import { promptWithReply, transcriptText } from "./replies.js";
 import { _loadPending, buildDelegationFailurePrompt, buildDelegationRevivalPrompt, DelegationWakeBudget, discardDelegations, drainDelegations, findDelegationReceipt, pendingDelegationInfo, pendingDelegationSnapshot, pendingThreads, queueDelegation, recordDelegationReceipt, releaseDelegationsWaitingOn, summarizeDelegatedActivity } from "./delegations.js";
-import { cancelSteeredMessage, drainSteeredMessages, queuedSteeredMessage, queueSteeredMessage, } from "./steer-queue.js";
+import { cancelSteeredMessage, drainSteeredMessages, onSteeredQueueChange, queuedSteerSnapshot, queuedSteeredMessage, queuedThreadPosition, queueSteeredMessage, } from "./steer-queue.js";
 import { cancelChannelMessage, drainChannelMessages, queuedChannelMessage, queueChannelMessage, } from "./channel-queue.js";
 import { acceptedSendMatch, parseSendId, sendFingerprint, SendSequencer, } from "./send-idempotency.js";
 import { EventBus } from "./harness/bus.js";
@@ -78,7 +79,7 @@ import { fetchSkillFromSource } from "./skill-fetch.js";
 import { expandLearnTurnText, learnSource } from "./skill-learn.js";
 import { expandSetupTurnText, setupModeActive, setupSystemPrompt } from "./setup-mode.js";
 import { checkSoulDrift, readSoulDrift, soulFile, writeSoulMirror } from "./bot-folder.js";
-import { buildSystemPrompt, computerPrompt, mentionPrompt, COMPOSIO_PROMPT, CREDENTIAL_PROMPT, LEARN_PROMPT, PROFILE_PROMPT, ROUTINE_PROMPT, ROUTINE_EXECUTION_PROMPT, WEBHOOK_PROMPT, } from "./system-prompt.js";
+import { buildSystemPrompt, computerPrompt, mentionPrompt, COMPOSIO_PROMPT, CREDENTIAL_PROMPT, THREADS_PROMPT, LEARN_PROMPT, PROFILE_PROMPT, ROUTINE_PROMPT, ROUTINE_EXECUTION_PROMPT, WEBHOOK_PROMPT, } from "./system-prompt.js";
 import { readCuaConnection, gatedLocalComputer } from "./local-computer.js";
 import { discoverExistingPerBotLocalVms, localVmInventoryEntry, shouldArmLocalVmIdle, } from "./local-vm-inventory.js";
 import { LocalVmIdleTimer } from "./local-vm-idle.js";
@@ -208,6 +209,9 @@ function customDomainStatus() {
     };
 }
 const registry = new ProviderRegistry(BUILT_IN_DRIVERS);
+// Engines installed from Settings live under the data directory and win over
+// any other copy on PATH.
+registerEnginesBinDir();
 const providerAuthSessions = new ProviderAuthSessions();
 await registry.load(instanceConfigs(cfg));
 const bundledSkills = loadBundledSkills();
@@ -426,6 +430,7 @@ function agentsIntegration(botId, threadId, depth, skillAuthoring, generation) {
         kind: "agents",
         skillAuthoring,
         createdBots: 0,
+        openedThreads: 0,
     });
     return {
         command: process.execPath,
@@ -672,7 +677,7 @@ async function browserIntegration(botId, profile, turn) {
     if (!turn)
         return { profile: partitionId, session, spec, integration: spec };
     const token = mintInternalCapability({ botId, ...turn, browserSession: session,
-        kind: "browser", depth: 0, skillAuthoring: false, createdBots: 0 });
+        kind: "browser", depth: 0, skillAuthoring: false, createdBots: 0, openedThreads: 0 });
     return { profile: partitionId, session, spec, integration: {
             command: process.execPath, args: [SPAWNED_PROXIES.browser], env: {
                 ...AGENTS_NODE_FLAG, OMB_BROWSER_TOKEN: token, OMB_HARNESS_URL: `http://127.0.0.1:${PORT}`,
@@ -708,6 +713,7 @@ function connectedAppsIntegration(botId, threadId, generation) {
         kind: "connectors",
         skillAuthoring: false,
         createdBots: 0,
+        openedThreads: 0,
     });
     return composio.mcpIntegration(cfg, {
         harnessUrl: `http://127.0.0.1:${PORT}`,
@@ -760,6 +766,7 @@ function controlIntegration(botId, threadId, generation, localVmTarget) {
             ...(localVmTarget ? { localVmTarget } : {}),
             skillAuthoring: false,
             createdBots: 0,
+            openedThreads: 0,
         }),
     };
 }
@@ -1368,6 +1375,7 @@ const publicBot = (bot) => ({
     activeLeafId: store.activeLeaf(bot.threadId),
     tasks: store.tasks(bot.id).map(wireTask),
 });
+const publicBotQueuedMessages = () => queuedSteerSnapshot((botId, threadId) => Boolean(store.taskByThread(botId, threadId)));
 // busyBotId names only the speaker that currently owns the provider process.
 // A room turn is wider: it also includes async setup and every responder still
 // queued behind that speaker. Keep that operation visible for its whole
@@ -1750,6 +1758,14 @@ store.onChange((change) => {
             break;
         case "thread.deleted":
             routines?.forgetRoutineRequestReceiptsForThread(change.threadId);
+            // A deleted destination must not strand an approval in an internal
+            // task. Keep each run's snapshot and expose its execution as fallback.
+            for (const run of routines?.listRuns() ?? []) {
+                if (run.resultsThreadId === change.threadId || run.sourceThreadId === change.threadId) {
+                    syncRoutineRunToSource(run);
+                }
+            }
+            broadcast({ kind: "bot.queued", queues: publicBotQueuedMessages() });
             break;
         case "bot": {
             const bot = store.bot(change.botId);
@@ -1893,6 +1909,7 @@ function broadcast(payload) {
         }
     }
 }
+onSteeredQueueChange(() => broadcast({ kind: "bot.queued", queues: publicBotQueuedMessages() }));
 // ── server-side event folding (upstream's ingestion worker, miniature) ──
 // The canonical stream is the source of truth; the persisted transcript
 // and every client view are projections of it.
@@ -2999,13 +3016,12 @@ bus.subscribe((event) => {
                     costUsd: event.cost ?? null,
                 });
                 const routineReportThread = routineRun ? routineSourceThread(routineRun) : null;
-                const routineReportGroup = routineReportThread ? store.groupByThread(routineReportThread) : undefined;
-                // Group-origin routines belong to that channel's unread state. Their
-                // hidden execution task should not light up the bot's 1:1 sidebar too.
+                // A routine's result belongs to its reporting thread's unread state.
+                // Its internal execution should not light up the sidebar as well.
                 // Neither should a peer's hop: the exchange is already recorded in the
                 // pair channel and chipped into both threads, which is the whole of
                 // what the person needs to be able to find it.
-                if (!routineReportGroup && !internal)
+                if (!routineReportThread && !internal)
                     store.patchTask(bot.id, event.threadId, { unread: true });
                 // A failed peer turn stays a chip too. The bot that delegated is woken
                 // with the failure and answers the person in its own thread — buzzing
@@ -3354,13 +3370,27 @@ bus.subscribe((event) => {
 /** How a drained delegation becomes a real turn on the target. Shared by
  * the settle-time drain and the boot-time drain of what a previous process
  * left queued. */
-const runDelegatedTurn = (toBotId, text, commsDepth, sourceThreadId, channel, taskId, sourceBotId) => {
+const runDelegatedTurn = (toBotId, rawText, commsDepth, sourceThreadId, channel, taskId, sourceBotId, openedThreadId) => {
     // startTurn REJECTS on an ordinary condition — busy target, deleted bot,
     // unavailable provider. Unhandled, that rejection is fatal to the
     // harness (Node's default), which in the packaged app kills the server
     // child. Every delegation failure has to land as a chip instead.
-    const targetThreadId = store.bot(toBotId)?.threadId;
+    // A fresh-thread handoff runs in the thread the opener created — the
+    // drain already dropped it if that thread is gone — never in whatever
+    // the person is looking at.
+    const targetThreadId = openedThreadId ?? store.bot(toBotId)?.threadId;
     const target = store.bot(toBotId);
+    const opener = store.bot(sourceBotId);
+    const unattended = isUnattended(sourceBotId, sourceThreadId);
+    // The first line of an opened thread is another bot's words: it carries
+    // the same provenance note every relayed peer line does, structurally
+    // (peerAsk) as well as in the text.
+    const peerAsk = openedThreadId && opener
+        ? { botId: opener.id, name: opener.name, unattended: unattended || undefined }
+        : undefined;
+    const text = openedThreadId && opener
+        ? withPeerProvenance(rawText, { botName: opener.name, delivery: "start_thread", unattended })
+        : rawText;
     if (targetThreadId) {
         delegationWatch.set(targetThreadId, {
             channelId: channel?.id,
@@ -3397,7 +3427,8 @@ const runDelegatedTurn = (toBotId, text, commsDepth, sourceThreadId, channel, ta
     return startTurn(toBotId, text, {
         threadId: targetThreadId,
         commsDepth,
-        unattended: isUnattended(sourceBotId, sourceThreadId),
+        unattended,
+        peerAsk,
         // startTurn schedules provider/integration setup after marking the bot
         // busy. Those asynchronous setup failures do not emit turn.completed,
         // so clear the watch and report them through this callback too.
@@ -3425,9 +3456,16 @@ function retryDelegationsWaitingOn(botId) {
         // Explicit idle releases (room/setup/reload/watchdog fallbacks) may not
         // publish turn.completed. They free a waiting source continuation too.
         drainDelegationWakes();
-        if (store.bot(botId)?.busy)
+        // A bot still busy in one thread has nevertheless freed a slot: the
+        // fresh-thread handoffs waiting on it can move, while the active-thread
+        // ones keep waiting for it to go idle, as they always have.
+        const stillBusy = store.bot(botId)?.busy === true;
+        if (stillBusy && botAtThreadCapacity(botId))
             return;
-        for (const waitingThread of releaseDelegationsWaitingOn(botId)) {
+        const released = stillBusy
+            ? releaseDelegationsWaitingOn(botId, (item) => item.targetThreadId !== undefined)
+            : releaseDelegationsWaitingOn(botId);
+        for (const waitingThread of released) {
             drainThreadDelegations(waitingThread);
         }
     });
@@ -3471,13 +3509,15 @@ bus.subscribe((event) => {
     drainDelegationWakes();
 });
 function drainQueuedSends() {
-    drainSteeredMessages(store, (botId, threadId, prompt, userMessage, excludeIds) => 
-    // A plain attended turn — no automationSource, no unattended, no comms
-    // depth: exactly what typing the same words into an idle bot would run.
+    drainSteeredMessages(store, (botId, threadId, prompt, userMessage, excludeIds, unattended) => 
+    // A plain attended turn — no automationSource, no comms depth: exactly
+    // what typing the same words into an idle bot would run. The one
+    // exception is `unattended`: a thread a bot opened on itself while
+    // nobody was watching stays unwatched through the wait for a slot.
     // Drain just appended the held lines; userMessage keeps startTurn
     // from duplicating the last one, and excludeIds drops every drained
     // line from the transcript-replay so they are not also in `prompt`.
-    startTurn(botId, prompt, { threadId, userMessage, excludeMessageIds: excludeIds }).then(() => undefined).catch((err) => {
+    startTurn(botId, prompt, { threadId, userMessage, excludeMessageIds: excludeIds, unattended }).then(() => undefined).catch((err) => {
         store.appendMessage(threadId, {
             role: "bot",
             kind: "activity",
@@ -3508,6 +3548,36 @@ async function startOrQueueDirectMessage(botId, threadId, text, replyTo, sendId)
     const message = await startTurn(botId, text, { threadId, replyTo, sendId });
     return { ok: true, threadId, message };
 }
+/** How many start_thread calls one turn may make. Same spirit as the
+ * create-bot ceiling above: a handful is a plan, more is a fan-out. */
+const MAX_THREADS_OPENED_PER_TURN = 5;
+/** A thread a bot opened on itself gets its first turn exactly the way a
+ * person's message would: it runs now if the bot has a free slot, and
+ * otherwise waits in the same composer queue, in line behind whatever the
+ * bot already has waiting. The only inheritance is `unattended` — a bot
+ * nobody is watching does not become watched by opening a thread. */
+async function startOrQueueOpenedThread(botId, threadId, text, unattended) {
+    // A room turn holds the bot too (startTurn refuses a direct turn during
+    // one); the drain's own block check already waits for it, so the words
+    // queue here rather than bounce.
+    if (botAtThreadCapacity(botId) || activeGroupTurnForBot(botId)) {
+        queueSteeredMessage(botId, threadId, text, { reason: "capacity", unattended });
+        return { state: "queued", position: queuedThreadPosition(botId, threadId) ?? 1 };
+    }
+    try {
+        await startTurn(botId, text, { threadId, unattended });
+        return { state: "running" };
+    }
+    catch (error) {
+        const why = error instanceof Error ? error.message : String(error);
+        store.appendMessage(threadId, {
+            role: "bot",
+            kind: "activity",
+            tool: { name: `error: this thread could not start — ${why.slice(0, 120)}`, ok: false },
+        });
+        return { state: "failed", error: why };
+    }
+}
 const screenPollers = new Map();
 /** The preview shares the box's single command endpoint with the agent's
  * own actions, so every frame we take is latency stolen from the work the
@@ -3763,6 +3833,10 @@ async function startTurn(botId, text, opts) {
     if (!opts?.cardContinuation) {
         if (commsDepth === 0 && opts?.automationSource === undefined && !opts?.unattended) {
             personAskAt.set(threadId, userMessage.at);
+            // Continuing an old run as a normal conversation makes that task
+            // visible again; these new replies are not routine report updates.
+            if (task.routineRunId)
+                store.patchTask(bot.id, threadId, { routineRunId: undefined });
         }
         else {
             personAskAt.delete(threadId);
@@ -4164,7 +4238,7 @@ async function startTurn(botId, text, opts) {
                     // model mostly did not think to make.
                     ? peerRosterSystemPrompt(sectionPeers)
                     : "";
-            const credentialPrompt = integrations.agents ? CREDENTIAL_PROMPT : "";
+            const credentialPrompt = integrations.agents ? CREDENTIAL_PROMPT + THREADS_PROMPT : "";
             const routinePrompt = integrations.agents ? ROUTINE_PROMPT : "";
             const profilePrompt = integrations.agents ? PROFILE_PROMPT : "";
             const recallPrompt = integrations.agents ? SESSION_SEARCH_SYSTEM_PROMPT : "";
@@ -4380,6 +4454,13 @@ async function startTurn(botId, text, opts) {
 // The scheduler owns timing and receipts; the existing harness remains the
 // only owner of provider sessions, approvals, tools, computers and messages.
 function routineSourceOwner(run) {
+    if (run.resultsThreadId) {
+        const bot = store.bot(run.botId);
+        const task = bot && store.taskByThread(bot.id, run.resultsThreadId);
+        return bot && !bot.hidden && task && !task.routineRunId
+            ? { bot, group: undefined, threadId: task.threadId }
+            : null;
+    }
     const threadId = run.sourceThreadId?.trim();
     if (!threadId)
         return null;
@@ -4393,7 +4474,8 @@ function routineSourceOwner(run) {
     // whose conversation held the card. Recheck their section before sharing
     // a result, since either bot may have moved since confirmation.
     const sourceBot = store.botByThread(threadId);
-    if (sourceBot && sectionKey(sourceBot.section) === sectionKey(bot.section)) {
+    if (sourceBot && !sourceBot.hidden && !store.taskByThread(sourceBot.id, threadId)?.routineRunId &&
+        sectionKey(sourceBot.section) === sectionKey(bot.section)) {
         return { bot: sourceBot, group: undefined, threadId };
     }
     const group = store.groupByThread(threadId);
@@ -4410,6 +4492,7 @@ function routineRunCard(run) {
         runId: run.id,
         routineId: run.routineId,
         routineName: redactSecretsInText(run.routineName),
+        scheduledFor: run.scheduledFor,
         status: run.status,
     };
     if (run.goalStatus)
@@ -4452,8 +4535,16 @@ function routineRunFallbackText(card) {
  * another chat message. */
 function syncRoutineRunToSource(run) {
     const source = routineSourceOwner(run);
-    if (!source)
+    if (!source) {
+        const execution = run.threadId ? store.taskByThread(run.botId, run.threadId) : null;
+        if (execution?.routineRunId === run.id) {
+            store.patchTask(run.botId, execution.threadId, {
+                routineRunId: undefined,
+                ...(["waiting", "completed", "failed", "missed"].includes(run.status) ? { unread: true } : {}),
+            });
+        }
         return null;
+    }
     const sourceThreadId = source.threadId;
     const card = routineRunCard(run);
     const text = routineRunFallbackText(card);
@@ -4474,6 +4565,18 @@ function syncRoutineRunToSource(run) {
         }
         store.appendMessage(sourceThreadId, message);
     }
+    // Mark only the fresh execution, after its first running card persisted
+    // and before dispatch adds any transcript. A user can later promote it by
+    // sending a normal follow-up; replaying/marking the old receipt seen must
+    // never hide that conversation again.
+    if (run.target === "bot" && run.triggerSource !== "webhook" && run.threadId && run.threadId !== sourceThreadId) {
+        const execution = store.taskByThread(run.botId, run.threadId);
+        const freshExecution = execution && run.status === "running" && !execution.routineRunId &&
+            store.messagesFor(run.threadId).length === 0;
+        if (execution && (freshExecution || (execution.routineRunId === run.id && execution.unread))) {
+            store.patchTask(run.botId, run.threadId, { routineRunId: run.id, unread: false });
+        }
+    }
     // Merely queueing/running is ambient progress. Attention and terminal
     // states become unread in the conversation where the user asked for them.
     if (statusChanged && ["waiting", "completed", "failed", "missed"].includes(run.status)) {
@@ -4538,7 +4641,7 @@ async function stopBotForEmergencyApprovalDowngrade(botId) {
 // Load queued handoffs before scheduler recovery can fail an interrupted
 // run. Its failure callback can then durably drop that work immediately;
 // nothing dispatches until the listener is ready below.
-const commsBus = { store, broadcast };
+const commsBus = { store, broadcast, threadSlotFree: (botId) => !botAtThreadCapacity(botId) };
 _loadPending();
 routines = new RoutineManager({
     emit: broadcast,
@@ -4570,6 +4673,25 @@ routines = new RoutineManager({
         return task;
     },
     createGoalTask: (groupId, title) => store.createGroupTask(groupId, title, false),
+    isResultsThread: (botId, threadId) => {
+        const bot = store.bot(botId);
+        const task = store.taskByThread(botId, threadId);
+        return Boolean(bot && !bot.hidden && task && !task.routineRunId);
+    },
+    resolveResultsThread: (routine, forceNew) => {
+        // A trusted chat source is already snapshotted as sourceThreadId on each
+        // run. Keep it distinct: it can belong to a teammate or room, whereas an
+        // explicit resultsThreadId must be a visible task owned by the running bot.
+        if (!forceNew && routineSourceOwner(routine))
+            return routine.resultsThreadId;
+        return store.createTask(routine.botId, `${routine.name} · Results`, false)?.threadId;
+    },
+    discardResultsThread: (botId, threadId) => {
+        const task = store.taskByThread(botId, threadId);
+        if (task && !task.busy && !task.routineRunId && store.messagesFor(threadId).length === 0) {
+            store.deleteTask(botId, threadId);
+        }
+    },
     startTurn: (botId, threadId, prompt, runOn, triggerSource, onDispatchError) => startTurn(botId, prompt, { threadId, runOn, automationSource: triggerSource, onDispatchError })
         .then(() => undefined),
     startGoal: async (groupId, threadId, prompt, coordinatorBotId, runId, _onDispatchError) => {
@@ -4738,6 +4860,13 @@ const agentRoutine = (routine, latestRun) => {
                     type: "interval",
                     everyMinutes: routine.schedule.everyMinutes,
                     anchorAt: new Date(routine.schedule.anchorAt).toISOString(),
+                    ...(routine.schedule.weekdays === undefined
+                        ? {}
+                        : { weekdays: routine.schedule.weekdays.map((day) => ROUTINE_WEEKDAY_NAMES[day]) }),
+                    ...(routine.schedule.window === undefined ? {} : { window: { ...routine.schedule.window } }),
+                    ...(routine.schedule.endsAt === undefined
+                        ? {}
+                        : { endsAt: new Date(routine.schedule.endsAt).toISOString() }),
                 }
                 : {
                     type: "weekly",
@@ -5237,7 +5366,7 @@ setupRetry = 0) {
             readyGroup.bulletin.trim() && `Room bulletin (shared instructions for everyone):\n${readyGroup.bulletin.trim()}`,
             `Reply as yourself, briefly and conversationally. To bring a teammate in, mention them like @Name — they'll see the conversation and respond.`,
             outsideRoom.length > 0 && roomPeerRosterSystemPrompt(outsideRoom),
-            integrations.agents && CREDENTIAL_PROMPT.trim(),
+            integrations.agents && (CREDENTIAL_PROMPT + THREADS_PROMPT).trim(),
             integrations.agents && ROUTINE_PROMPT.trim(),
             integrations.agents && PROFILE_PROMPT.trim(),
             skillAuthoring && LEARN_PROMPT.trim(),
@@ -6790,6 +6919,7 @@ function cliProbeEnvironment() {
         "OMB_COMPOSIO_BROKER_TOKEN",
         "OMB_TTS_KEY",
         "OMB_OPENAI_IMAGE_KEY",
+        "OMB_CUSTOM_IMAGE_KEY",
         "ANTHROPIC_API_KEY",
         "OPENAI_API_KEY",
     ]) {
@@ -6902,7 +7032,7 @@ function configStatus() {
         // the chosen voice is a setting, not a secret; the key is reported the
         // same configured-or-not way as every other credential
         tts: tts.describeVoice(cfg),
-        imageGen: { configured: Boolean(cfg.imageGen?.key) },
+        imageGen: avatarImageStatus(cfg),
         // not a secret — the sidebar shows it
         profile: { name: cfg.profile?.name ?? "", email: cfg.profile?.email ?? "" },
         // not a secret — the settings picker shows it; "" = follow the system
@@ -7406,6 +7536,7 @@ const handleRequest = async (req, res) => {
                 ...parsed.data,
                 generation,
                 createdBots: 0,
+                openedThreads: 0,
             });
             return json(res, 201, { token });
         }
@@ -7527,6 +7658,82 @@ const handleRequest = async (req, res) => {
             // to keep trying — but it is still NAMED, with the refusal it would
             // have met. Without that the bot can only say it is in no room at
             // all, while the person is looking at it in that very room.
+            // list_threads: the caller's own threads, plus — on every peer it can
+            // reach — only the threads the caller itself opened. A peer's other
+            // threads are its own business (and the person's), so the scope is
+            // "what you started", never "what that bot is doing". State is read
+            // the way the sidebar reads it, so the bot and the person agree.
+            if (method === "GET" && path === "/api/internal/threads") {
+                const from = internalSender;
+                const fromThreadId = internalCapability.threadId;
+                if (!connectorThread(from.id, fromThreadId)) {
+                    return json(res, 403, { error: "source conversation does not belong to sender" });
+                }
+                const rows = [];
+                const stateOf = (bot, task) => {
+                    if (task.activity === "waiting-on-you")
+                        return "waiting-on-you";
+                    if (threadBusy(bot.id, task.threadId))
+                        return "running";
+                    if (queuedThreadPosition(bot.id, task.threadId) !== null)
+                        return "queued";
+                    return "idle";
+                };
+                for (const task of store.tasks(from.id)) {
+                    rows.push({
+                        threadId: task.threadId, botId: from.id, botName: from.name, title: task.title,
+                        state: stateOf(from, task), unread: task.unread === true, openedAt: task.openedBy?.at ?? task.createdAt,
+                        delegationId: task.openedBy?.delegationId, own: true,
+                    });
+                }
+                for (const peer of reachablePeers(store.bots, from)) {
+                    for (const task of store.tasks(peer.id)) {
+                        if (task.openedBy?.botId !== from.id)
+                            continue;
+                        rows.push({
+                            threadId: task.threadId, botId: peer.id, botName: peer.name, title: task.title,
+                            state: stateOf(peer, task), unread: task.unread === true, openedAt: task.openedBy.at,
+                            delegationId: task.openedBy.delegationId, own: false,
+                        });
+                    }
+                }
+                rows.sort((a, b) => b.openedAt - a.openedAt);
+                return json(res, 200, { threads: rows.slice(0, 100) });
+            }
+            // close_thread: a bot tidies a thread it opened (or one of its own)
+            // once its result has been read. Closing is the sidebar's idle state
+            // plus a chip saying who closed it — never a deletion, which stays a
+            // person's confirmed action, and never while the thread is running.
+            const closeMatch = method === "POST" ? path.match(/^\/api\/internal\/threads\/([\w-]+)\/close$/) : null;
+            if (closeMatch) {
+                const from = internalSender;
+                const fromThreadId = internalCapability.threadId;
+                if (!connectorThread(from.id, fromThreadId)) {
+                    return json(res, 403, { error: "source conversation does not belong to sender" });
+                }
+                const threadId = closeMatch[1];
+                const owner = [from, ...reachablePeers(store.bots, from)].find((bot) => store.taskByThread(bot.id, threadId));
+                const task = owner ? store.taskByThread(owner.id, threadId) : undefined;
+                if (!owner || !task)
+                    return json(res, 404, { error: "no such thread — call list_threads for the ones you can see" });
+                if (owner.id !== from.id && task.openedBy?.botId !== from.id) {
+                    return json(res, 403, { error: "that thread is not yours to close — only the bot that opened it, or its own bot, can" });
+                }
+                if (threadId === fromThreadId)
+                    return json(res, 400, { error: "you cannot close the thread you are speaking in — finish your turn instead" });
+                if (threadBusy(owner.id, threadId)) {
+                    return json(res, 409, { error: `#${task.title} is still running — wait for it to finish (list_threads), or the person can stop it from the app` });
+                }
+                store.appendMessage(threadId, {
+                    role: "bot",
+                    kind: "activity",
+                    from: { botId: from.id, name: from.name, color: from.color },
+                    tool: { name: `Closed by @${from.name}`, ok: true },
+                });
+                if (task.unread)
+                    store.patchTask(owner.id, threadId, { unread: false });
+                return json(res, 200, { closed: true, threadId, title: task.title, botName: owner.name });
+            }
             if (method === "GET" && path === "/api/internal/rooms") {
                 const from = internalSender;
                 const fromThreadId = internalCapability.threadId;
@@ -8220,6 +8427,128 @@ const handleRequest = async (req, res) => {
                 store.appendMessage(fromThreadId, chip);
                 return json(res, 201, { ok: true, messageId: posted.id, roomName: room.name });
             }
+            // start_thread: a bot opens a real thread — on itself for separate
+            // work, or on a teammate as a handoff that should run on its own.
+            // Never activates: a bot must not move what the person is looking at.
+            if (method === "POST" && path === "/api/internal/threads") {
+                const body = await readInternalBody();
+                const from = internalSender;
+                const fromThreadId = internalCapability.threadId;
+                const owner = connectorThread(from.id, fromThreadId);
+                if (!owner)
+                    return json(res, 403, { error: "source conversation does not belong to sender" });
+                if (body.depth !== undefined &&
+                    (!Number.isInteger(body.depth) || body.depth < 0 || body.depth !== internalCapability.depth)) {
+                    return json(res, 403, { error: "the recursion depth does not match this turn" });
+                }
+                const title = String(body.title ?? "").trim();
+                const message = String(body.message ?? "").trim();
+                if (!title || !message)
+                    return json(res, 400, { error: "title and message are required" });
+                if (title.length > 80)
+                    return json(res, 400, { error: "title must be at most 80 characters" });
+                // the title is quoted into chips and the sidebar, one line each
+                if (!fitsOnOneLine(title))
+                    return json(res, 400, { error: "title must fit on one line" });
+                if (internalCapability.openedThreads >= MAX_THREADS_OPENED_PER_TURN) {
+                    return json(res, 429, { error: `you can open at most ${MAX_THREADS_OPENED_PER_TURN} threads in one turn` });
+                }
+                const toBotId = typeof body.toBotId === "string" && body.toBotId.trim() ? body.toBotId.trim() : from.id;
+                const target = store.bot(toBotId);
+                if (!target)
+                    return json(res, 404, { error: "no such bot" });
+                // A folder is the target's own organisation; a name is what the
+                // model has, an id is what the sidebar has, so accept either.
+                const folder = typeof body.folder === "string" ? body.folder.trim() : "";
+                let projectId;
+                if (folder) {
+                    const project = (target.projects ?? []).find((candidate) => candidate.id === folder || candidate.name.trim().toLowerCase() === folder.toLowerCase());
+                    if (!project) {
+                        const names = (target.projects ?? []).map((candidate) => candidate.name).join(", ");
+                        return json(res, 400, { error: `@${target.name} has no folder named "${folder}"${names ? ` — the folders are: ${names}` : " — it has no folders; leave folder out"}` });
+                    }
+                    projectId = project.id;
+                }
+                const sourceTitle = owner.group ? owner.group.name : (store.taskByThread(from.id, fromThreadId)?.title ?? "");
+                if (target.id === from.id) {
+                    const task = store.createTask(from.id, title, false, projectId, { botId: from.id, name: from.name, at: Date.now() });
+                    if (!task)
+                        return json(res, 500, { error: "couldn't create that thread" });
+                    internalCapability.openedThreads += 1;
+                    const chip = {
+                        role: "bot",
+                        kind: "activity",
+                        tool: { name: `Opened thread #${task.title}`, ok: true },
+                        threadRef: { botId: from.id, threadId: task.threadId, title: task.title },
+                    };
+                    if (owner.group)
+                        chip.from = { botId: from.id, name: from.name, color: from.color };
+                    store.appendMessage(fromThreadId, chip);
+                    // The first line is the bot's own words. Say so where the model
+                    // reads it, so a later turn in that thread never mistakes the
+                    // request for the person's.
+                    const opening = `[Thread you opened yourself${sourceTitle ? ` from #${sourceTitle}` : ""}. The request below is your own words, not the person's: do the work here and end with a clear result they can read.]\n\n${message}`;
+                    const outcome = await startOrQueueOpenedThread(from.id, task.threadId, opening, isUnattended(from.id, fromThreadId));
+                    return json(res, 201, {
+                        threadId: task.threadId,
+                        title: task.title,
+                        botId: from.id,
+                        botName: from.name,
+                        self: true,
+                        limit: maxConcurrentBotThreads(cfg),
+                        ...outcome,
+                    });
+                }
+                // A peer thread is a handoff into a fresh thread: every gate the
+                // classic handoff has applies unchanged, here at queue time and
+                // again in the drain at dispatch time.
+                const depth = internalCapability.depth;
+                if (depth >= MAX_COMMS_DEPTH) {
+                    return json(res, 200, { error: "thread chains are limited to one hop — open the thread on yourself, or do this one here" });
+                }
+                if (sectionKey(from.section) !== sectionKey(target.section)) {
+                    return json(res, 403, { error: "that bot belongs to a different section" });
+                }
+                if (!peerAllowed(from, target.id)) {
+                    return json(res, 403, { error: "that bot is not on this bot's allowed peers — call list_bots for the ones you can reach" });
+                }
+                const task = store.createTask(target.id, title, false, projectId, { botId: from.id, name: from.name, at: Date.now() });
+                if (!task)
+                    return json(res, 500, { error: "couldn't create that thread" });
+                const queued = queueDelegation(commsBus, from, { toBotId: target.id, message, depth, targetThreadId: task.threadId }, MAX_COMMS_DEPTH, fromThreadId);
+                if (queued.result !== "ok" || !queued.id) {
+                    // nothing will ever run there: take the row back before the person
+                    // sees a thread that goes nowhere
+                    store.deleteTask(target.id, task.threadId);
+                    const said = {
+                        self: "a bot cannot hand a thread to itself this way — leave bot_id out",
+                        too_deep: "thread chains are limited to one hop — open the thread on yourself, or do this one here",
+                        no_target: "no such bot",
+                        too_many: "too many handoffs queued on this turn — finish your turn and open the rest next time",
+                    };
+                    return json(res, 200, { error: said[queued.result === "ok" ? "no_target" : queued.result] });
+                }
+                store.setTaskOpenedBy(target.id, task.threadId, { botId: from.id, name: from.name, delegationId: queued.id, at: task.openedBy?.at ?? Date.now() });
+                internalCapability.openedThreads += 1;
+                // An honest forecast, not a promise: the handoff starts when this
+                // turn ends, and by then the target's slots are taken by whatever is
+                // running there plus the threads this turn already opened ahead.
+                const limit = maxConcurrentBotThreads(cfg);
+                const running = store.tasks(target.id).filter((candidate) => threadBusy(target.id, candidate.threadId)).length;
+                const ahead = pendingDelegationSnapshot().filter((pending) => pending.toBotId === target.id && pending.targetThreadId !== undefined && pending.targetThreadId !== task.threadId).length;
+                const position = running + ahead + 1;
+                return json(res, 201, {
+                    threadId: task.threadId,
+                    title: task.title,
+                    botId: target.id,
+                    botName: target.name,
+                    self: false,
+                    delegationId: queued.id,
+                    approvalRequired: Boolean(from.approvePeerComms),
+                    limit,
+                    ...(position > limit ? { state: "queued", position: position - limit } : { state: "pending" }),
+                });
+            }
             if (method === "POST" && path === "/api/internal/create-bot") {
                 const body = await readInternalBody();
                 const chief = internalSender;
@@ -8732,6 +9061,7 @@ const handleRequest = async (req, res) => {
                 return json(res, 400, { error: "messages must be a non-negative whole number" });
             return json(res, 200, {
                 bots: store.bots.map((bot) => ({ ...publicBot(bot), ...messagePage(bot.threadId, limit) })),
+                botQueuedMessages: publicBotQueuedMessages(),
                 groups: store.groups.map((g) => ({ ...publicGroupState(g), ...messagePage(g.threadId, limit) })),
                 computerControl: Object.fromEntries(store.bots.map((bot) => {
                     const snapshot = computerControl.snapshot(bot.id);
@@ -10024,7 +10354,7 @@ const handleRequest = async (req, res) => {
             if (!parsed.success) {
                 return json(res, 400, { error: `prompt must be at most 400 characters` });
             }
-            const generated = await generateAvatarImage(cfg.imageGen?.key ?? "", existing, parsed.data.prompt);
+            const generated = await generateAvatarImage(cfg, existing, parsed.data.prompt);
             const current = store.bot(existing.id);
             if (!current)
                 return json(res, 404, { error: "no such bot" });
@@ -12005,7 +12335,7 @@ const handleRequest = async (req, res) => {
             const state = await providerAuthSessions.status(authStatus[1], auth.kind === "session" ? auth.session.id : "loopback", url.searchParams.get("flowId") ?? "");
             return json(res, 200, { auth: state });
         }
-        const instanceAction = /^\/api\/instances\/([\w.-]+)\/(refresh-models|install|auth\/start|auth\/complete|auth\/cancel)$/.exec(path);
+        const instanceAction = /^\/api\/instances\/([\w.-]+)\/(refresh-models|install|auth\/start|auth\/complete|auth\/cancel|auth\/sign-out)$/.exec(path);
         if (method === "POST" && instanceAction) {
             if (!String(req.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) {
                 return json(res, 415, { error: "content-type must be application/json" });
@@ -12023,7 +12353,7 @@ const handleRequest = async (req, res) => {
                 }
                 if (action === "install") {
                     if (!(await registry.installRuntime(instanceId)))
-                        return json(res, 404, { error: "managed installation is unavailable" });
+                        return json(res, 404, { error: "Installing this engine from Settings is not available on this server. Use the install command on the machine running OpenMausBot." });
                     return json(res, 200, { instances: await describeInstances() });
                 }
                 if (action === "auth/start") {
@@ -12038,6 +12368,13 @@ const handleRequest = async (req, res) => {
                     }
                     return json(res, 200, { auth: started });
                 }
+                if (action === "auth/sign-out") {
+                    const instance = registry.get(instanceId);
+                    if (!instance)
+                        return json(res, 404, { error: "unknown instance" });
+                    await providerAuthSessions.signOut(instance, owner);
+                    return json(res, 200, { instances: await describeInstances() });
+                }
                 if (action === "auth/complete") {
                     const body = await readBody(req);
                     const flowId = typeof body?.flowId === "string" ? body.flowId : "";
@@ -12613,6 +12950,8 @@ const handleRequest = async (req, res) => {
                             persisted.tts.key = "";
                         if (persisted.imageGen?.key !== undefined)
                             persisted.imageGen.key = "";
+                        if (persisted.imageGen?.customApiKey !== undefined)
+                            persisted.imageGen.customApiKey = "";
                         saveConfig(persisted);
                         configWriteCommitted = true;
                         syncCredentialEnv(patch);