openmausbot 0.1.93 → 0.1.95

package/dist-server/server/skills-library-migration.js

@@ -0,0 +1,235 @@
+// Skills library migration (features.skillsLibrary, skills lane S1).
+//
+// Per-bot skill copies move into the shared library, deduplicated by the
+// reviewed SKILL.md sha256. Originals are archived under the library root —
+// write-once, never deleted — and the per-bot manifest entry is dropped
+// only after the archive exists and the assignment is durably recorded. The
+// sweep is idempotent through state, not markers: a migrated skill has no
+// manifest entry left to re-read, and an existing archive short-circuits
+// the move.
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { writeFileAtomic } from "./atomic.js";
+import { installLibrarySkill, libraryArchiveDirectory, readSkillLibraryIndex, skillsLibraryRoot, } from "./skill-library.js";
+import { listMigratableSkills, removeManifestEntry } from "./skills.js";
+function sha256Hex(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/** Move a per-bot skill directory into its archive slot. Same-volume moves
+ * rename; a cross-device fallback copies recursively and verifies the
+ * SKILL.md hash before the copy counts as the archive. */
+function archiveSkillDirectory(source, archive, expectSha256) {
+    mkdirSync(dirname(archive), { recursive: true, mode: 0o700 });
+    // Every source directory gets its own slot: the same sha256 can be
+    // reinstalled after its manifest entry was cleared, so a collision takes
+    // a hash-qualified name, then numeric suffixes, never a silent drop.
+    let destination = archive;
+    if (existsSync(destination)) {
+        const stem = `${archive}.${expectSha256}`;
+        destination = stem;
+        let suffix = 1;
+        while (existsSync(destination))
+            destination = `${stem}.${suffix++}`;
+    }
+    try {
+        renameSync(source, destination);
+    }
+    catch (error) {
+        if (error.code !== "EXDEV")
+            throw error;
+        cpSync(source, destination, { recursive: true, force: false, errorOnExist: true });
+    }
+    const archived = readFileSync(join(destination, "SKILL.md"), "utf8");
+    if (sha256Hex(archived) !== expectSha256) {
+        throw new Error("the archived copy does not match the reviewed sha256");
+    }
+}
+/** Migrate one bot's per-bot skill copies into the library. Org-stamped
+ * skills carry their stamp onto the library entry, so an organization
+ * install becomes a library source instead of a parallel system. A bot is
+ * assigned only when its own copy was enabled; the first copy's enabled
+ * flag still decides the entry's reviewState. */
+export function migrateBotSkillsToLibrary(botId, root = skillsLibraryRoot()) {
+    const outcomes = [];
+    const assigned = [];
+    for (const copy of listMigratableSkills(botId)) {
+        if (!copy.intact || !copy.directory) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: "stored SKILL.md is missing or changed after review" });
+            continue;
+        }
+        // The shared library currently stores SKILL.md only. Moving a package
+        // with scripts/references/assets would make its relative paths vanish
+        // from the bot's usable directory, so keep that working private copy.
+        try {
+            if (readdirSync(copy.directory).some((name) => name !== "SKILL.md")) {
+                outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: "skill has auxiliary files — keeping its complete private directory" });
+                continue;
+            }
+        }
+        catch {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: "could not inspect the private skill directory" });
+            continue;
+        }
+        let instructions;
+        try {
+            instructions = readFileSync(join(copy.directory, "SKILL.md"), "utf8");
+        }
+        catch (error) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: `could not read the stored SKILL.md: ${error instanceof Error ? error.message : String(error)}` });
+            continue;
+        }
+        if (sha256Hex(instructions) !== copy.sha256) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: "stored SKILL.md changed after review" });
+            continue;
+        }
+        const existing = readSkillLibraryIndex(root)[copy.name];
+        if (existing && existing.sha256 !== copy.sha256) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: `the library already has a different "${copy.name}" — rename one of them` });
+            continue;
+        }
+        // The library entry's review state is shared by every assigned bot, so
+        // deduplicating a copy whose own on/off differs from it would silently
+        // flip that bot's switch. Keep the per-bot copy in place for a human to
+        // reconcile instead of archiving and assigning it.
+        if (existing && (existing.reviewState === "approved") !== copy.enabled) {
+            outcomes.push({
+                botId,
+                name: copy.name,
+                outcome: "skipped",
+                detail: `the library "${copy.name}" is ${existing.reviewState === "approved" ? "enabled" : "disabled"} while this bot had it ${copy.enabled ? "enabled" : "disabled"} — align them before migrating`,
+            });
+            continue;
+        }
+        if (!existing) {
+            const installed = installLibrarySkill({
+                name: copy.name,
+                description: copy.description,
+                instructions,
+                source: copy.source,
+                license: copy.license,
+                compatibility: copy.compatibility,
+                reviewState: copy.enabled ? "approved" : "disabled",
+                package: copy.package,
+                root,
+            });
+            if ("error" in installed) {
+                outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: installed.error });
+                continue;
+            }
+            outcomes.push({ botId, name: copy.name, outcome: "migrated" });
+        }
+        else {
+            outcomes.push({ botId, name: copy.name, outcome: "deduplicated", detail: "identical sha256 already in the library" });
+        }
+        // The manifest entry is the only re-readable record of this skill, so
+        // the assignment must be durable before it goes away. Record it in the
+        // pending-assignments file the boot sweep and the standalone script both
+        // replay: if this write — or the later patch to the bot record — fails,
+        // the next boot restores the assignment instead of stranding an
+        // archived skill with no manifest and no assignment.
+        try {
+            const pendingAssignments = readPendingAssignments(root);
+            if (copy.enabled)
+                writePendingAssignments({
+                    ...pendingAssignments,
+                    [botId]: [...new Set([...(pendingAssignments[botId] ?? []), ...assigned, copy.name])].sort(),
+                }, root);
+        }
+        catch (error) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: `could not record the assignment durably: ${error instanceof Error ? error.message : String(error)}` });
+            continue;
+        }
+        try {
+            archiveSkillDirectory(copy.directory, libraryArchiveDirectory(root, botId, copy.name), copy.sha256);
+        }
+        catch (error) {
+            // The library entry is idempotent, so leaving the per-bot copy in
+            // place only means the next sweep retries this skill. The assignment
+            // recorded above replays idempotently, so the extra pending entry a
+            // failed archive leaves behind is harmless.
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: `archiving failed: ${error instanceof Error ? error.message : String(error)}` });
+            continue;
+        }
+        const removed = removeManifestEntry(botId, copy.name, copy.sha256);
+        if ("error" in removed) {
+            outcomes.push({ botId, name: copy.name, outcome: "skipped", detail: removed.error });
+            continue;
+        }
+        // Assignment follows this bot's own copy.enabled: a disabled copy
+        // migrates its bytes but assigns nothing, so nobody gains a skill
+        // they never turned on.
+        if (copy.enabled)
+            assigned.push(copy.name);
+    }
+    return { ranAt: new Date().toISOString(), outcomes, assignments: assigned.length ? { [botId]: assigned } : {} };
+}
+export function pendingAssignmentsPath(root = skillsLibraryRoot()) {
+    return join(root, "pending-assignments.json");
+}
+/** Assignments waiting to reach bot records: recorded by the standalone
+ * script for a stopped server, and by the migration itself before a
+ * manifest entry is dropped. The next flag-on boot applies them through
+ * the Store, the single writer of bots.json. */
+export function readPendingAssignments(root = skillsLibraryRoot()) {
+    try {
+        const parsed = JSON.parse(readFileSync(pendingAssignmentsPath(root), "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const result = {};
+        for (const [botId, names] of Object.entries(parsed)) {
+            if (Array.isArray(names) && names.every((name) => typeof name === "string"))
+                result[botId] = [...names];
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+export function writePendingAssignments(assignments, root = skillsLibraryRoot()) {
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    writeFileAtomic(pendingAssignmentsPath(root), `${JSON.stringify(assignments, null, 2)}\n`, { mode: 0o600 });
+}
+/** The boot sweep: migrate every bot's copies, then apply assignments.
+ * With a `patch` callback (the live server) assignments land on the bot
+ * records directly and any script-recorded pending file is cleared; without
+ * one this only reports. Runs under features.skillsLibrary only. */
+export function runSkillsLibraryBootSweep(options) {
+    const root = options.root ?? skillsLibraryRoot();
+    const outcomes = [];
+    const assignments = {};
+    const pending = options.patch ? readPendingAssignments(root) : {};
+    for (const bot of options.bots) {
+        const report = migrateBotSkillsToLibrary(bot.id, root);
+        outcomes.push(...report.outcomes);
+        const current = bot.assignedSkills ?? [];
+        const merged = [...new Set([...(pending[bot.id] ?? []), ...(report.assignments[bot.id] ?? []), ...current])].sort();
+        const changed = merged.length !== current.length || merged.some((name, index) => name !== current[index]);
+        if (!changed)
+            continue;
+        if (options.patch)
+            options.patch(bot.id, merged);
+        assignments[bot.id] = merged;
+    }
+    // Clear the pending file once every patch applied: entries recorded by
+    // the script before this boot and recovery records written by this run's
+    // migrations are both spent.
+    if (options.patch && (Object.keys(pending).length || Object.keys(readPendingAssignments(root)).length)) {
+        writePendingAssignments({}, root);
+    }
+    return { ranAt: new Date().toISOString(), outcomes, assignments };
+}
+/** Bot ids that have per-bot skill manifests on disk. Used by the
+ * standalone script, which cannot reach the Store. */
+export function botIdsWithSkillState(dataDir) {
+    try {
+        return readdirSync(join(dataDir, "skill-state"), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}

package/dist-server/server/skills.js

@@ -33,6 +33,7 @@ import { writeFileAtomic } from "./atomic.js";
 import { DATA_DIR } from "./config.js";
 import { redactSecretsInText } from "./redact.js";
 import { LEARN_SOURCE_PREFIX } from "./skill-learn.js";
+import { librarySkillFilePath, listLibrarySkills } from "./skill-library.js";
 import { workspaceDir } from "./workspace.js";
 import { isSkillName, parseSkillMd, scanSkillText, SKILL_FILE_MAX_BYTES } from "../shared/skill-md.js";
 // SKILL.md parsing and the static scan live in shared/ so the package
@@ -1191,11 +1192,14 @@ export function applySkillWriteWithReceipt(botId, staged, recordApplied) {
  * index lines only — the same progressive-disclosure shape the spec asks
  * agents for. Bodies never ride the prompt; the bot reads the file when a
  * task matches. */
-export function skillsSystemPrompt(botId) {
+export function skillsSystemPrompt(botId, assignedLibrary) {
+    return composeSkillsSystemPrompt(botId, assignedLibrary);
+}
+function composeSkillsSystemPrompt(botId, assignedLibrary) {
     // Reconcile links on every turn. If the workspace copy changed since its
     // review, integrity filtering below removes it from native discovery too.
     syncSkillLinks(botId);
-    const enabled = listSkills(botId).filter((skill) => skill.enabled);
+    const enabled = resolveBotSkills(botId, assignedLibrary).filter((skill) => skill.enabled);
     if (!enabled.length) {
         loggedIndexOmissions.delete(botId);
         return "";
@@ -1212,7 +1216,7 @@ export function skillsSystemPrompt(botId) {
         (omitted ? `${entries.length ? "\n" : ""}${notice(omitted, entries.length)}` : "");
     for (const skill of enabled.slice(0, INDEX_MAX_SKILLS)) {
         const entry = manifest[skill.name];
-        const file = join(skillTarget(root, skill.name, entry), "SKILL.md");
+        const file = entry ? join(skillTarget(root, skill.name, entry), "SKILL.md") : librarySkillFilePath(skill.name);
         const line = `- ${skill.name}: ${skill.description} Read ${JSON.stringify(file)}.`;
         if (Buffer.byteLength(block([...lines, line], enabled.length - lines.length - 1), "utf8") > INDEX_MAX_BYTES)
             break;
@@ -1231,3 +1235,62 @@ export function skillsSystemPrompt(botId) {
     }
     return block(lines, omitted.length);
 }
+// --- Skills library composition (features.skillsLibrary) ---
+/** One bot's private skills plus its assigned library skills, private
+ * winning any name collision (the lane's resolution order: bot-private >
+ * library > bundled). `undefined` assignments return exactly
+ * `listSkills(botId)` — the flag-off contract. */
+export function resolveBotSkills(botId, assignedLibrary) {
+    const own = listSkills(botId);
+    if (!assignedLibrary?.length)
+        return own;
+    const ownNames = new Set(own.map((skill) => skill.name));
+    const assigned = new Set(assignedLibrary);
+    const fromLibrary = listLibrarySkills().filter((skill) => assigned.has(skill.name) && !ownNames.has(skill.name));
+    return [...own, ...fromLibrary];
+}
+export function listBotSkillsWithOrigin(botId, assignedLibrary) {
+    const own = listSkills(botId);
+    const ownNames = new Set(own.map((skill) => skill.name));
+    const assigned = new Set(assignedLibrary ?? []);
+    const skills = resolveBotSkills(botId, assignedLibrary).map((skill) => ({
+        ...skill,
+        origin: ownNames.has(skill.name) ? "private" : "library",
+    }));
+    const library = listLibrarySkills().filter((entry) => !ownNames.has(entry.name) && !assigned.has(entry.name));
+    return { skills, library };
+}
+export function listMigratableSkills(botId) {
+    return Object.entries(readManifest(botId))
+        .map(([name, entry]) => ({
+        name,
+        directory: skillDirectory(botId, name, entry),
+        sha256: entry.sha256,
+        enabled: entry.enabled,
+        source: entry.source,
+        description: entry.description,
+        ...(entry.license ? { license: entry.license } : {}),
+        ...(entry.compatibility ? { compatibility: entry.compatibility } : {}),
+        ...(entry.package ? { package: { ...entry.package } } : {}),
+        intact: skillContentMatches(botId, name, entry),
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Drop manifest entries the migration has archived. The caller archives
+ * the bytes first and passes the sha256 it read, so a skill that changed
+ * between read and removal is left untouched. */
+export function removeManifestEntry(botId, name, expectSha256) {
+    if (!isSkillName(name))
+        return { error: "invalid skill name" };
+    const manifest = readManifest(botId);
+    const entry = manifest[name];
+    if (!entry)
+        return { removed: true };
+    if (entry.sha256 !== expectSha256) {
+        return { error: `skill "${name}" changed since it was read — leaving it in place` };
+    }
+    delete manifest[name];
+    writeManifest(botId, manifest);
+    syncSkillLinks(botId);
+    return { removed: true };
+}

package/dist-server/server/steer-queue.js

@@ -28,8 +28,11 @@ export function restoreSteeredMessages() {
         const entry = queues.get(row.threadId) ?? { botId: row.ownerId, items: [] };
         if (entry.botId !== row.ownerId)
             throw new Error("queued task belongs to another bot");
+        // a 1:1 line is only ever stamped "call"; "api" belongs to channel rows
+        const { via, ...payload } = row.payload;
         entry.items.push({
-            ...row.payload,
+            ...payload,
+            ...(via === "call" ? { via } : {}),
             messageId: row.id,
             prompt: row.payload.prompt ?? row.payload.text,
             // rows queued before timestamps were kept read as queued at restore
@@ -83,6 +86,7 @@ export function queueSteeredMessage(botId, threadId, text, options = {}) {
         sender: options.sender,
         trigger: options.trigger,
         queuedAt: Date.now(),
+        via: options.via,
     };
     saveChatFollowup({ id, kind: "bot", ownerId: botId, threadId, payload: item });
     entry.items.push(item);
@@ -112,6 +116,13 @@ export function hasQueuedSteeredMessages(botId, threadId) {
     const entry = queues.get(threadId);
     return entry?.botId === botId && entry.items.length > 0;
 }
+/** Whether one send still waits in its thread's queue. False while it is
+ * out of the queue: drained onto the thread, held for a steer into the
+ * running turn, or cancelled (editing a queued line cancels it). */
+export function isSteeredMessageQueued(botId, threadId, queueId) {
+    const entry = queues.get(threadId);
+    return entry?.botId === botId && entry.items.some((item) => item.messageId === queueId);
+}
 /** Drain every queue whose task is idle: append the held lines (leaf is now
  * the finished turn's last item), then one run per thread whose prompt is
  * the drained group's texts separated by a blank line. `userMessage` is the last appended line
@@ -161,6 +172,7 @@ export function drainSteeredMessages(store, run, isBlocked) {
                 queueId: item.messageId,
                 peerAsk: item.peerAsk,
                 sender: item.sender,
+                ...(item.via ? { via: item.via } : {}),
             }));
         }
         const last = appended.at(-1);

package/dist-server/server/store.js

@@ -6,6 +6,7 @@ import { createHash } from "node:crypto";
 import { chmodSync, existsSync, readFileSync, mkdirSync, rmSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { writeFileAtomic } from "./atomic.js";
+import { parseToolScope, toolScopeWidens } from "../shared/tool-scope.js";
 import { ensureSections, readSections, changeEmptySection } from "./section-context.js";
 import { removeBotFolder, soulFile, soulHash, writeSoulMirror } from "./bot-folder.js";
 import { peerAllowKey } from "./peer-approval-key.js";
@@ -32,8 +33,10 @@ export const taskWireProjectionIsExact = true;
 /** The typed wire projection for one task. Pairs with the assertion above:
  * returning WireTask means an undeclared server field cannot ride silently. */
 export function toWireTask(task) {
-    const { resumeCursors: _resumeCursors, lastInstanceId: _lastInstanceId, handedMessages: _handedMessages, appliedCompactionId: _appliedCompactionId, contextFloor: _contextFloor, lastContextModel: _lastContextModel, surfaceSource: _surfaceSource, ...wire } = task;
-    return wire;
+    const { resumeCursors: _resumeCursors, lastInstanceId: _lastInstanceId, handedMessages: _handedMessages, appliedCompactionId: _appliedCompactionId, contextFloor: _contextFloor, lastContextModel: _lastContextModel, surfaceSource, ...wire } = task;
+    // Who pinned stays private. A client learns only whether the pin is the
+    // machine's own record, so it never presents one as the person's choice.
+    return surfaceSource === "auto" && wire.surface !== undefined ? { ...wire, surfaceAuto: true } : wire;
 }
 const TASK_PATCH_FIELDS = [
     "title", "projectId", "modelSelection", "approvalMode", "autoApprove", "alwaysAllow",
@@ -1460,7 +1463,7 @@ export class Store {
         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);
+        mdb.insertMessage(threadId, full); // the leaf stays where it was, in SQLite too
         if (full.kind === "screen") {
             for (const pruned of this.pruneScreenFrames(t)) {
                 mdb.updateMessage(threadId, pruned);
@@ -1586,6 +1589,9 @@ export class Store {
         return this.completeNewBotSelection(requested ?? this.defaultSelection());
     }
     createBot(profile = {}, opts = {}) {
+        const toolScope = parseToolScope(profile.toolScope);
+        if (!toolScope.ok)
+            throw new Error(toolScope.error);
         this.rememberSections([profile.section]);
         const name = profile.name?.trim() || pickBotName(this.bots.map((b) => b.name));
         const section = sectionKey(profile.section);
@@ -1603,6 +1609,7 @@ export class Store {
             ...(profile.mascotBody ? { mascotBody: profile.mascotBody } : {}),
             // Restricted from its first frame: no one else is ever told it exists.
             ...(profile.visibility && profile.visibility !== "everyone" ? { visibility: structuredClone(profile.visibility) } : {}),
+            ...(toolScope.scope ? { toolScope: toolScope.scope } : {}),
             unread: false,
             modelSelection: this.newBotSelection(profile.modelSelection),
             resumeCursors: {},
@@ -1623,8 +1630,10 @@ export class Store {
                 activity: "idle",
                 busy: false,
             }];
+        // Persist the selection in the first record, before publishing the bot
+        // or starting its greeting. An interrupted creation cannot inherit tools.
+        this.saveBots([bot, ...this.bots]);
         this.bots.unshift(bot);
-        this.saveBots();
         // The folder exists from the first moment, so the user can open
         // SOUL.md before the bot has said a word. The record is canonical: a
         // mirror-write failure must never fail bot creation.
@@ -1838,6 +1847,18 @@ export class Store {
                 throw new Error(parsed.error);
             patch = { ...patch, connectorTools: parsed.grants };
         }
+        if (Object.hasOwn(patch, "toolScope")) {
+            const parsed = parseToolScope(patch.toolScope);
+            if (!parsed.ok)
+                throw new Error(parsed.error);
+            patch = { ...patch, toolScope: parsed.scope };
+        }
+        const wideningToolScope = Object.hasOwn(patch, "toolScope") && toolScopeWidens(bot.toolScope, patch.toolScope);
+        const nextToolScope = patch.toolScope;
+        if (wideningToolScope) {
+            patch = { ...patch };
+            delete patch.toolScope;
+        }
         // Runtime revocations must become effective in memory even when disk is
         // unavailable. Profile edits use the separate atomic path below.
         Object.assign(bot, patch);
@@ -1850,7 +1871,14 @@ export class Store {
             }
             bot.unread = bot.tasks.some(taskCountsAsBotUnread);
         }
-        this.saveBots();
+        if (wideningToolScope) {
+            // New authority becomes live only after its durable save succeeds.
+            // Other runtime revocations above still take effect on a failed write.
+            this.saveBots(this.bots.map((candidate) => candidate === bot ? { ...bot, toolScope: nextToolScope } : candidate));
+            bot.toolScope = nextToolScope;
+        }
+        else
+            this.saveBots();
         this.emit({ type: "bot", botId: id });
         return bot;
     }
@@ -2348,6 +2376,14 @@ export class Store {
     taskByThread(botId, threadId) {
         return this.bot(botId)?.tasks?.find((t) => t.threadId === threadId);
     }
+    /** The thread `fromBotId` opened on this bot from its conversation
+     * `fromThreadId` with coordinate_bots: one per conversation and teammate,
+     * so whatever that conversation sends later continues it. A thread the
+     * person archived is left alone. */
+    workThread(botId, fromBotId, fromThreadId) {
+        return this.tasks(botId).find((t) => t.openedBy?.kind === "work" && t.openedBy.botId === fromBotId &&
+            t.openedBy.threadId === fromThreadId && t.archivedAt === undefined);
+    }
     /** A turn gets an independent snapshot without changing the selected task
      * or mutating the bot's defaults while another turn is running. */
     projectBotForTask(botId, threadId) {

package/dist-server/server/surface.js

@@ -5,6 +5,7 @@
 // next, and the "needs your hands" plea never said which. Everything that
 // decides or describes a surface lives here, so the picker, the dispatch,
 // the system prompt and the notification cannot drift apart.
+import { usesCloudComputer } from "./contracts.js";
 const SURFACES = new Set(["cloud", "vm", "local", "browser"]);
 /** Parse a surface arriving over the wire; anything else is "not said". */
 export function parseSurface(value) {
@@ -67,6 +68,70 @@ export function resolveSurface(input) {
     }
     return { computer: undefined, browser: browserOn, pinned: null, clearPin: false, note: "" };
 }
+/** The next action per source: the full sentence after a failed attach, and
+ * the clause after "Choose another model, or" when the engine is the cause. */
+const PLACE_ACTION = {
+    pin: {
+        sentence: "Clear this conversation's place in the composer to continue.",
+        clause: "clear this conversation's place in the composer",
+    },
+    // The dispatch clears an Auto-recorded pin that failed, so the next
+    // message runs on Auto: that pin was the machine's memory, not a choice.
+    "auto-pin": {
+        sentence: "This conversation is back on Auto; send your message again.",
+        clause: "send your message again; this conversation is back on Auto",
+    },
+    "works-on": {
+        sentence: "Set Works on to Auto in this bot's settings to continue.",
+        clause: "set Works on to Auto",
+    },
+    routine: {
+        sentence: "Change where this routine runs.",
+        clause: "change where this routine runs",
+    },
+};
+/** The one rule for which engines can work on a cloud computer (Hosted
+ * desktop on Boat, or a self-hosted VPS): an engine with computer tools gets
+ * it as one more stdio computer server, and the Computer engine runs on its
+ * Boat. Checked before anything is provisioned, so a turn that cannot run
+ * never creates or wakes a machine. */
+export function cloudPlaceDriverError(capabilities, backend, source = "works-on") {
+    const next = `Choose another model, or ${PLACE_ACTION[source].clause}.`;
+    if (!usesCloudComputer(capabilities))
+        return `This model can't use a computer. ${next}`;
+    if (backend === "vps" && capabilities.remoteAgent === true)
+        return `The Computer engine runs on Boat and can't use a self-hosted VPS. ${next}`;
+    return null;
+}
+export const CLOUD_PLACE_DRIVER_ERROR = cloudPlaceDriverError({}, "box");
+/** One line, cause then next action. A bot thread's transcript row keeps
+ * 160 characters, so the cause is shortened there, never the action; the
+ * cause keeps its own words otherwise. */
+export function placeFailureMessage(cause, source, limit = 160) {
+    const action = PLACE_ACTION[source].sentence;
+    const body = cause.trim().replace(/[\s.]+$/, "");
+    const room = limit - action.length - 2;
+    if (body.length <= room)
+        return `${body}. ${action}`;
+    return `${body.slice(0, Math.max(0, room - 1)).trimEnd()}… ${action}`;
+}
+/** A place the turn was told to use could not be used. Carries the place and
+ * where the choice came from, so the dispatch shows the one next action and
+ * clears a failed Auto-recorded pin: a failed place never sticks. */
+export class PlaceUnavailableError extends Error {
+    place;
+    source;
+    constructor(place, source, message) {
+        super(message);
+        this.name = "PlaceUnavailableError";
+        this.place = place;
+        this.source = source;
+    }
+}
+/** A failed attach: the attach's own words as the cause, plus the action. */
+export function placeUnavailable(place, source, cause, limit = 160) {
+    return new PlaceUnavailableError(place, source, placeFailureMessage(cause, source, limit));
+}
 /** How the prompt and the app name a surface. Deliberately the same words
  * the panel uses, so "tell them it is on the cloud computer" points at a
  * label the person can find. */
@@ -85,7 +150,13 @@ export function surfaceLabel(surface) {
 /** Said once per task, so the person hears the place before the first click
  * lands there. Same words as the panel and the composer chip. */
 const RESTATE_SENTENCE = " Before your first action on a screen or page in a task, say in one short sentence where you are working, using that same name.";
-const SURFACE_AUTHORITY = " For browser and computer tasks, use OpenMausBot's mounted browser/computer tools first: inspect the target, perform the action, and verify its result before claiming success. Discover deferred tools by their server/name when needed. Do not substitute the provider's own desktop, a shell-launched browser, or another automation path for the selected OpenMausBot surface. Ordinary code and file tasks may still use their normal tools. Announcing an action is not performing it. A request naming another place does not move these tools: this computer is the user's host, Local VM is an isolated desktop, the cloud computer is remote, and the built-in browser is a separate browser. If the requested place differs from the mounted one, explain the mismatch and ask the user to change the conversation's computer selector; never act on a different computer or describe a host window as a VM.";
+/** Where a person moves a conversation: the Computer panel is the one place
+ * control both interface modes show (Simple has no composer chip). */
+const PLACE_CONTROL = "the Computer panel";
+/** Without select_computer the person has to switch; with it, surfacePrompt
+ * swaps exactly this phrase for the model's own switch. */
+const ASK_TO_SWITCH = `explain the mismatch and ask the user to change where this conversation works in ${PLACE_CONTROL}`;
+const SURFACE_AUTHORITY = ` For browser and computer tasks, use OpenMausBot's mounted browser/computer tools first: inspect the target, perform the action, and verify its result before claiming success. Discover deferred tools by their server/name when needed. Do not substitute the provider's own desktop, a shell-launched browser, or another automation path for the selected OpenMausBot surface. Ordinary code and file tasks may still use their normal tools. Announcing an action is not performing it. A request naming another place does not move these tools: this computer is the user's host, Local VM is an isolated desktop, the cloud computer is remote, and the built-in browser is a separate browser. If the requested place differs from the mounted one, ${ASK_TO_SWITCH}; never act on a different computer or describe a host window as a VM.`;
 /** A Cloud home offers neither this computer nor a Local VM
  * (server/cloud-home.ts), so its bots are told only about the places it has.
  * Each pair rewrites one phrase of the desktop wording above. */
@@ -116,13 +187,13 @@ export function surfacePrompt(mounted, opts = {}) {
     }
     if (text)
         text += RESTATE_SENTENCE + (opts.canSelect
-            ? SURFACE_AUTHORITY.replace("explain the mismatch and ask the user to change the conversation's computer selector", "inspect connected choices with select_computer and select the requested available place; on a pending result end this turn so OpenMausBot can reconnect the correct tools and continue the original request")
+            ? SURFACE_AUTHORITY.replace(ASK_TO_SWITCH, "inspect connected choices with select_computer and select the requested available place; on a pending result end this turn so OpenMausBot can reconnect the correct tools and continue the original request")
             : SURFACE_AUTHORITY);
     else if (!opts.note && !opts.canSelect) {
         text = " No computer or built-in browser tools are mounted this turn. You cannot open apps, click, or inspect a screen through OpenMausBot. If asked for screen work, explain this and ask the user to choose and connect a computer in the Computer panel; do not claim to have opened or checked it.";
     }
     if (opts.pinned) {
-        text += ` This conversation is pinned to ${surfaceLabel(opts.pinned)}; changing places requires ${opts.canSelect ? "select_computer or " : ""}the conversation's computer selector, not a different tool name.`;
+        text += ` This conversation is pinned to ${surfaceLabel(opts.pinned)}; changing places requires ${opts.canSelect ? "select_computer or " : ""}the user's choice in ${PLACE_CONTROL}, not a different tool name.`;
     }
     if (opts.canSelect)
         text += " For a screen task, use select_computer with no arguments when you need to inspect the actual available targets. Choose the requested place from its result; if the user left the place open, use a suitable available target or surface auto instead of asking them to operate the menu. Browser-only work can stay in Browser; when it needs desktop apps or capabilities the current Browser lacks, select an available Local VM without asking the user to switch it manually. Choose before taking actions, and do not repeat actions already completed if the task must continue elsewhere. OpenMausBot can start an existing configured computer and highlight the selected target. If the right tools are already mounted, use them directly. On a pending switch, end this turn: the original request resumes automatically with the new tools, and then you must carry out the task. Only ask for input for a genuine blocker, such as missing setup, required sign-in or an approval. Never silently replace an explicitly requested VM with the host desktop.";
@@ -137,23 +208,3 @@ export function surfacePrompt(mounted, opts = {}) {
             text = text.replace(desktop, cloudHome);
     return text + (opts.note ?? "");
 }
-/** Tool names that touch a screen, for engines that report bare names.
- * Mirrors the screen-poller regex in the harness. */
-const SCREEN_TOOL = /^(?:screenshot|click|type_text|press_key|scroll|open_url|wait_for|computer_|browser_)/i;
-/** Which surface a completed tool call landed on, or null when it cannot
- * be told apart. The Claude driver namespaces MCP tools by server, which
- * is the only fully reliable signal; a bare name is trusted only when one
- * surface was mounted, because both servers expose `browser_snapshot`. */
-export function surfaceForTool(toolName, mounted) {
-    if (toolName.startsWith("mcp__browser__"))
-        return mounted.browser ? "browser" : null;
-    if (toolName.startsWith("mcp__computer__"))
-        return mounted.computer;
-    if (!SCREEN_TOOL.test(toolName))
-        return null;
-    if (mounted.computer && !mounted.browser)
-        return mounted.computer;
-    if (!mounted.computer && mounted.browser && /^browser_/i.test(toolName))
-        return "browser";
-    return null;
-}