viberoom 0.5.8 → 0.6.0

package/dist/room.js

@@ -3,20 +3,25 @@ import { EventEmitter } from "node:events";
 import { randomUUID } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { writeFileAtomic } from "./atomic.js";
-import { NOTES_ONLY_PROMPT, NOTES_REQUEST, crossedThreshold, extractNotes, isBareContextFullError, isContextFullError, overThreshold, visibleChunk } from "./context.js";
+import { NOTES_ONLY_PROMPT, NOTES_REQUEST, crossedThreshold, emptyUsageReport, extractNotes, isBareContextFullError, isContextFullError, looksCompacted, overThreshold, visibleChunk } from "./context.js";
+import { formatDuration } from "./duration.js";
 import { affectedByEdit, editNotice, partitionHistory, rewriteNotice } from "./edit.js";
 import { saveImages } from "./files.js";
+import { agentReadableWindow, resolveQuotes } from "./quotes.js";
 import { join, resolve } from "node:path";
 import { AcpAgent } from "./acp-client.js";
 import { RemoteError } from "./jsonrpc.js";
 import { getRecipe, listRecipes } from "./recipes.js";
+import { classifyStartFailure } from "./agent-health.js";
+import { legacyRowTone } from "./rows.js";
 import { composeSkillBlock, skillPull, SKILL_TOOL_NAME } from "./persona.js";
 import { BUILTIN_AUTHOR, parseSkillInvocation, renderSkillBody, SKILL_NAME_PATTERN, } from "./skills.js";
-import { BRIEF_AFFECTING_SETTINGS, DEFAULT_ROOM_SETTINGS, REQUEST_BRIEF_MARKER, SILENT_MARKER, buildBrief, buildHeader, composeCorrectionPrompt, composePrompt, countSentences, ensureDir, } from "./persona.js";
+import { templateId } from "./templates.js";
+import { applyVibemateChanges, diffSettings, lintRoomDesign, ruleLines } from "./room-design.js";
+import { BRIEF_AFFECTING_SETTINGS, AGENT_SETTINGS, coerceSetting, describeSettings, DEFAULT_ROOM_SETTINGS, ROOM_SETTINGS_SPEC, REQUEST_BRIEF_MARKER, NAME_PATTERN, SILENT_MARKER, buildBrief, buildHeader, composeCorrectionPrompt, composePrompt, countSentences, ensureDir, } from "./persona.js";
 import { Transcript } from "./log.js";
 const SKILL_TOOL_READY_MS = 5000;
 const COLORS = ["#6d5dfc", "#16a34a", "#d97706", "#dc2626", "#0891b2", "#be185d", "#4d7c0f", "#7c3aed"];
-const NAME_PATTERN = /^[\p{L}\p{N}][\p{L}\p{N}_-]{0,23}$/u;
 const MENTION_PATTERN = /@([\p{L}\p{N}][\p{L}\p{N}_-]*)/gu;
 const RULE_REF_TOKEN = /@\{p:([^}]+)\}/g;
 const ADAPTER_ERROR_PATTERN = /^(?:Warning: Falling back from WebSockets|unexpected status \d{3}|Error when talking to|API Error|You have exhausted your (?:daily )?quota|Rate limit|429 |5\d\d )/i;
@@ -45,6 +50,8 @@ export class Room extends EventEmitter {
     runtimes = new Map();
     drafts = new Map();
     permissions = new Map();
+    proposals = new Map();
+    proposalPlans = new Map();
     optionCache;
     log;
     colorIndex = 0;
@@ -90,6 +97,11 @@ export class Room extends EventEmitter {
         for (const line of lines) {
             try {
                 const message = JSON.parse(line);
+                if (message.kind === "system" && !message.details?.tone) {
+                    const tone = legacyRowTone(message.text);
+                    if (tone)
+                        message.details = { ...(message.details ?? {}), tone };
+                }
                 this.messages.push(message);
                 if (message.seq > this.seq)
                     this.seq = message.seq;
@@ -209,6 +221,19 @@ export class Room extends EventEmitter {
         appendFileSync(this.historyPath(), JSON.stringify(message) + "\n");
         this.push({ type: "message", message });
     }
+    messagesWithLiveDrafts() {
+        const live = [...this.runtimes.values()].filter((r) => r.turn?.published).map((r) => r.turn.message);
+        if (!live.length)
+            return [...this.messages];
+        const out = [...this.messages];
+        for (const draft of live) {
+            let at = out.length;
+            while (at > 0 && out[at - 1].ts > draft.ts)
+                at--;
+            out.splice(at, 0, draft);
+        }
+        return out;
+    }
     get humanName() {
         return this.settings.humanName;
     }
@@ -229,8 +254,9 @@ export class Room extends EventEmitter {
             settings: this.settings,
             customRulesText: this.renderRuleReferences(this.settings.customRules),
             participants: [...this.participants.values()],
-            messages: [...this.messages, ...this.drafts.values()],
+            messages: this.messagesWithLiveDrafts(),
             permissions: [...this.permissions.values()].map(({ resolve: _r, ...p }) => p),
+            proposals: [...this.proposals.values()],
             recipes: listRecipes().map(({ build: _b, ...r }) => r),
             lastMessageAt: last?.ts ?? this.createdAt,
         };
@@ -292,13 +318,14 @@ export class Room extends EventEmitter {
     unstaffed() {
         return [...this.participants.values()].filter((p) => p.kind === "agent" && p.status === "unstaffed");
     }
-    postHumanMessage(text, images = []) {
+    postHumanMessage(text, images = [], quotes = []) {
         const waiting = this.unstaffed();
         if (waiting.length)
             throw new Error(`${waiting.map((p) => p.name).join(", ")} ${waiting.length === 1 ? "has" : "have"} no coding agent yet: summon ${waiting.length === 1 ? "it" : "them"} from the roster to start the conversation`);
         const trimmed = text.trim();
-        if (!trimmed && !images.length)
+        if (!trimmed && !images.length && !quotes.length)
             throw new Error("empty message");
+        const quoted = quotes.length ? resolveQuotes(quotes, this.messages) : [];
         const attachments = images.length ? saveImages(ensureDir(this.filesDir()), images) : [];
         this.humanTypingUntil = 0;
         const human = this.participants.get("human");
@@ -315,6 +342,8 @@ export class Room extends EventEmitter {
         };
         if (attachments.length)
             message.images = attachments;
+        if (quoted.length)
+            message.quotes = quoted;
         this.decorateHumanMessage(message);
         human.turns += 1;
         if (this.focused) {
@@ -466,6 +495,7 @@ export class Room extends EventEmitter {
         const memory = !!options.memory;
         const replay = memory ? Math.max(0, options.replay ?? this.settings.replayAfterRestart) : 0;
         const withNotes = memory && !!participant.notes;
+        const why = options.reason ?? "its context was cleared";
         this.dropScheduledTurn(id);
         this.cancelPermissionsOf(id);
         if (this.speaking === id)
@@ -476,18 +506,38 @@ export class Room extends EventEmitter {
         this.restoredSeen.set(id, this.seq);
         this.push({ type: "participant", participant });
         if (!online) {
-            participant.statusDetail = withNotes ? "its context was cleared; a reconnect starts it with its notes" : "its context was cleared; a reconnect starts it with an empty head";
-            this.postSystem(withNotes ? `${participant.name} was respawned while offline: it comes back with its notes.` : `${participant.name} was respawned while offline: it comes back knowing nothing from before.`);
+            participant.statusDetail = withNotes ? `${why}; a reconnect starts it with its notes` : `${why}; a reconnect starts it with an empty head`;
+            const comesBack = withNotes ? "it comes back with its notes" : "it comes back knowing nothing from before";
+            this.postSystem(options.reason ? `${participant.name} was respawned while offline (${why}): ${comesBack}.` : `${participant.name} was respawned while offline: ${comesBack}.`);
             this.push({ type: "participant", participant });
             this.log.info(`respawn of ${participant.name} (offline): stored session dropped`);
             return participant;
         }
         await this.reconnect(id, memory
-            ? { mode: "replay", replay, memory: withNotes, reason: `its context was cleared; it comes back with ${withNotes ? "its notes and " : ""}the last ${replay} messages` }
-            : { mode: "replay", replay: 0, reason: "its context was cleared, it remembers nothing from before" });
+            ? { mode: "replay", replay, memory: withNotes, reason: `${why}; it comes back with ${withNotes ? "its notes and " : ""}the last ${replay} messages` }
+            : { mode: "replay", replay: 0, reason: `${why}, it remembers nothing from before` });
         this.log.info(`respawn of ${participant.name}: fresh session, ${memory ? `${withNotes ? "notes + " : ""}replay ${replay}` : "no replay"}`);
         return participant;
     }
+    async restartWithPersona(id, patch) {
+        const participant = this.participants.get(id);
+        if (!participant || participant.kind !== "agent")
+            throw new Error("no such agent");
+        const runtime = this.runtimes.get(id);
+        const online = !!runtime && runtime.agent.alive;
+        if (online && runtime.turnActive)
+            throw new Error(`${participant.name} is in the middle of a reply; try again when it is idle`);
+        if (online) {
+            try {
+                await this.takeNotes(id);
+            }
+            catch (error) {
+                this.log.warn(`${participant.name}: notes before the restart failed (${describeError(error)}); it restarts with the notes it had`);
+            }
+        }
+        this.updatePersona(id, patch);
+        return this.respawnAgent(id, { memory: true, reason: "its role changed" });
+    }
     updateNotes(id, notes) {
         const participant = this.participants.get(id);
         if (!participant || participant.kind !== "agent")
@@ -510,7 +560,15 @@ export class Room extends EventEmitter {
             throw new Error(`${participant.name} is in the middle of a reply; try again when it is idle`);
         const header = buildHeader(this.effectiveSettings(), this.personaOf(participant), this.roster(), this.hops, ["hidden turn: notes only, nothing is posted"]);
         runtime.log.info("notes: hidden turn");
-        await this.executeTurn(participant, runtime, [{ type: "text", text: `${header}\n\n${NOTES_ONLY_PROMPT}` }], null, true);
+        participant.notesTurn = true;
+        this.push({ type: "participant", participant });
+        try {
+            await this.executeTurn(participant, runtime, [{ type: "text", text: `${header}\n\n${NOTES_ONLY_PROMPT}` }], null, true);
+        }
+        finally {
+            participant.notesTurn = undefined;
+            this.push({ type: "participant", participant });
+        }
         return participant;
     }
     keepNotes(participant, runtime, notes, via) {
@@ -532,14 +590,14 @@ export class Room extends EventEmitter {
             participant.status = "error";
             participant.statusDetail = "its context filled up again right after a respawn; it needs you (respawn it by hand, with fewer replayed messages)";
             this.push({ type: "participant", participant });
-            this.postSystem(`${participant.name} ran out of context again (${detail.slice(0, 120)}); it was respawned once already and now needs you.`, "human");
+            this.postSystem(`${participant.name} ran out of context again (${detail.slice(0, 120)}); it was respawned once already and now needs you.`, "human", false, { tone: "error" });
             runtime.log.warn(`context full again within 10 minutes: no automatic respawn`);
             return;
         }
         participant.autoRespawnAt = Date.now();
         this.push({ type: "participant", participant });
         const memory = !!participant.notes;
-        this.postSystem(`${participant.name} ran out of context (${detail.slice(0, 120)}); it is respawned ${memory ? `with its notes and the last ${this.settings.replayAfterRestart} messages` : `with the last ${this.settings.replayAfterRestart} messages (it had no notes)`}.`, "human");
+        this.postSystem(`${participant.name} ran out of context (${detail.slice(0, 120)}); it is respawned ${memory ? `with its notes and the last ${this.settings.replayAfterRestart} messages` : `with the last ${this.settings.replayAfterRestart} messages (it had no notes)`}.`, "human", false, { tone: "error" });
         runtime.log.warn(`context full: ${detail}; respawn with ${memory ? "notes" : "no notes"}`);
         setImmediate(() => {
             void (memory ? this.respawnAgent(participant.id, { memory: true }) : this.reconnectAfterFull(participant.id)).catch((error) => this.notice(`${participant.name}: respawn after a full context failed: ${describeError(error)}`, "error"));
@@ -595,7 +653,7 @@ export class Room extends EventEmitter {
         }
         this.focused = true;
         this.push(this.roomEvent());
-        this.postSystem(`Hush: ${stopped ? `${stopped} repl${stopped > 1 ? "ies" : "y"} stopped; ` : ""}everyone waits until ${this.humanName} writes again.`);
+        this.postSystem(`Hush: ${stopped ? `${stopped} repl${stopped > 1 ? "ies" : "y"} stopped; ` : ""}everyone waits until ${this.humanName} writes again.`, undefined, false, { tone: "hush" });
     }
     rename(name) {
         const trimmed = name.trim();
@@ -612,124 +670,20 @@ export class Room extends EventEmitter {
     updateSettings(patch) {
         const next = { ...this.settings };
         const changed = [];
-        const setNumber = (key, min, max) => {
-            if (patch[key] === undefined)
-                return;
-            const value = Number(patch[key]);
-            if (!Number.isInteger(value) || value < min || value > max)
-                throw new Error(`${key} must be an integer between ${min} and ${max}`);
-            if (value !== next[key]) {
-                next[key] = value;
-                changed.push(key);
+        let unknownRefs = [];
+        for (const key of Object.keys(ROOM_SETTINGS_SPEC)) {
+            if (patch[key] === undefined || ROOM_SETTINGS_SPEC[key].kind === "own-path")
+                continue;
+            let value = coerceSetting(key, patch[key]);
+            if (key === "customRules") {
+                const resolved = this.resolveRuleReferences(value);
+                unknownRefs = resolved.unknown;
+                value = resolved.stored;
             }
-        };
-        setNumber("hopLimit", 0, 10_000);
-        setNumber("fullBriefEveryTurns", 1, 10_000);
-        setNumber("fullBriefEveryTokens", 1000, 10_000_000);
-        setNumber("replayAfterRestart", 0, 200);
-        setNumber("backlogCap", 1, 1000);
-        if (patch.replyDelay !== undefined) {
-            const value = Number(patch.replyDelay);
-            if (!Number.isFinite(value) || value < 0 || value > 120)
-                throw new Error("replyDelay must be between 0 and 120 seconds");
-            next.replyDelay = value;
-        }
-        const setText = (key, max) => {
-            if (patch[key] === undefined)
-                return;
-            const value = String(patch[key]).slice(0, max);
-            if (value !== next[key]) {
+            if (JSON.stringify(value) !== JSON.stringify(next[key])) {
                 next[key] = value;
                 changed.push(key);
             }
-        };
-        setText("topic", 2000);
-        setText("emoji", 8);
-        setText("humanDescription", 200);
-        let unknownRefs = [];
-        if (patch.customRules !== undefined) {
-            const resolved = this.resolveRuleReferences(String(patch.customRules).slice(0, 4000));
-            unknownRefs = resolved.unknown;
-            if (resolved.stored !== next.customRules) {
-                next.customRules = resolved.stored;
-                changed.push("customRules");
-            }
-        }
-        if (patch.humanDescriptionMode !== undefined) {
-            const mode = String(patch.humanDescriptionMode);
-            if (mode !== "inherit" && mode !== "override" && mode !== "append" && mode !== "none")
-                throw new Error("humanDescriptionMode must be inherit, override, append or none");
-            if (mode !== next.humanDescriptionMode) {
-                next.humanDescriptionMode = mode;
-                changed.push("humanDescriptionMode");
-            }
-        }
-        if (patch.refereeAction !== undefined) {
-            const action = String(patch.refereeAction);
-            if (action !== "next-header" && action !== "retry-hidden")
-                throw new Error("refereeAction must be next-header or retry-hidden");
-            if (action !== next.refereeAction) {
-                next.refereeAction = action;
-                changed.push("refereeAction");
-            }
-        }
-        if (patch.turnTaking !== undefined) {
-            const mode = String(patch.turnTaking);
-            if (mode !== "parallel" && mode !== "one-at-a-time")
-                throw new Error("turnTaking must be parallel or one-at-a-time");
-            if (mode !== next.turnTaking) {
-                next.turnTaking = mode;
-                changed.push("turnTaking");
-            }
-        }
-        if (patch.agentsWakeEachOther !== undefined) {
-            const on = patch.agentsWakeEachOther === true || patch.agentsWakeEachOther === "true";
-            if (on !== next.agentsWakeEachOther) {
-                next.agentsWakeEachOther = on;
-                changed.push("agentsWakeEachOther");
-            }
-        }
-        if (patch.waitWhileHumanTypes !== undefined) {
-            const on = patch.waitWhileHumanTypes === true || patch.waitWhileHumanTypes === "true";
-            if (on !== next.waitWhileHumanTypes) {
-                next.waitWhileHumanTypes = on;
-                changed.push("waitWhileHumanTypes");
-            }
-        }
-        if (patch.language !== undefined) {
-            const raw = String(patch.language).trim();
-            const language = !raw || raw === "follow-human" ? { mode: "follow-human" } : { mode: "fixed", language: raw };
-            if (JSON.stringify(language) !== JSON.stringify(next.language)) {
-                next.language = language;
-                changed.push("language");
-            }
-        }
-        if (patch.tools !== undefined) {
-            const tools = String(patch.tools);
-            if (tools !== "on-request" && tools !== "never")
-                throw new Error("tools must be on-request or never");
-            if (tools !== next.tools) {
-                next.tools = tools;
-                changed.push("tools");
-            }
-        }
-        if (patch.maxSentences !== undefined) {
-            const value = patch.maxSentences === null || patch.maxSentences === "" ? null : Number(patch.maxSentences);
-            if (value !== null && (!Number.isInteger(value) || value < 1 || value > 100))
-                throw new Error("maxSentences must be 1-100 or empty");
-            if (value !== next.maxSentences) {
-                next.maxSentences = value;
-                changed.push("maxSentences");
-            }
-        }
-        for (const key of ["headerRules", "showVendorInRoster"]) {
-            if (patch[key] !== undefined) {
-                const value = patch[key] === true || patch[key] === "true";
-                if (value !== next[key]) {
-                    next[key] = value;
-                    changed.push(key);
-                }
-            }
         }
         this.settings = next;
         this.push(this.roomEvent());
@@ -987,20 +941,25 @@ export class Room extends EventEmitter {
         const spec = recipe.build({ model: launch.model });
         const transcript = new Transcript(join(this.dataDir, "transcripts"), name);
         log.info(`spawning ${spec.command} ${spec.args.join(" ")} (cwd ${cwd}); transcript ${transcript.path}`);
+        const stderrTail = [];
         let agent;
         try {
             agent = new AcpAgent({ ...spec, cwd }, {
                 onSessionUpdate: (_sessionId, update) => this.onSessionUpdate(id, update),
                 onPermissionRequest: (params) => this.onPermissionRequest(id, params),
-                onStderr: (line) => log.info(`stderr: ${line}`),
+                onStderr: (line) => {
+                    log.info(`stderr: ${line}`);
+                    stderrTail.push(line);
+                    if (stderrTail.length > 10)
+                        stderrTail.shift();
+                },
                 onExit: (code, signal) => this.onAgentExit(id, code, signal, agent),
                 onRaw: (direction, message) => transcript.record(direction, message),
                 onProtocolError: (text) => log.warn(`protocol: ${text}`),
             });
         }
         catch (error) {
-            this.failStart(participant, error, fresh);
-            throw error;
+            throw this.failStart(participant, error, fresh, stderrTail);
         }
         try {
             const init = await agent.initialize({ name: "viberoom", version: "0.2.0" });
@@ -1093,6 +1052,7 @@ export class Room extends EventEmitter {
                 this.notice(`${name}: ${w}`, "warn");
             participant.status = "idle";
             participant.statusDetail = undefined;
+            participant.trouble = undefined;
             this.push({ type: "participant", participant });
             if (fresh) {
                 const detail = this.settings.showVendorInRoster ? `${recipe.label}${participant.model ? `, model ${participant.model}` : ""}` : "agent";
@@ -1124,8 +1084,7 @@ export class Room extends EventEmitter {
         catch (error) {
             agent.kill();
             this.forgetRuntime(id);
-            this.failStart(participant, error, fresh);
-            throw error;
+            throw this.failStart(participant, error, fresh, stderrTail);
         }
     }
     async removeParticipant(id) {
@@ -1169,11 +1128,20 @@ export class Room extends EventEmitter {
         const participant = this.participants.get(id);
         if (!runtime || !participant)
             throw new Error("no such agent");
-        if (!runtime.turnActive)
-            return;
-        runtime.agent.cancel(runtime.sessionId);
-        this.cancelPermissionsOf(id);
-        this.notice(`${participant.name}: stop requested.`, "info");
+        if (runtime.turnActive) {
+            runtime.agent.cancel(runtime.sessionId);
+            this.cancelPermissionsOf(id);
+            this.notice(`${participant.name}: stop requested.`, "info");
+            return "turn";
+        }
+        if (runtime.pendingTurn || runtime.delayTimer || this.floorQueue.includes(id)) {
+            this.dropScheduledTurn(id);
+            this.notice(`${participant.name}: stopped before it began; the turn is dropped.`, "info");
+            this.postSystem(`${participant.name} was stopped by ${this.humanName} before it began.`, undefined, false, { tone: "attention" });
+            return "queued";
+        }
+        this.notice(`${participant.name}: nothing to stop, it is not writing.`, "info");
+        return "nothing";
     }
     async setConfig(id, configId, value) {
         const runtime = this.runtimes.get(id);
@@ -1260,7 +1228,7 @@ export class Room extends EventEmitter {
             if (wanted.length) {
                 if (this.hops >= this.hopLimit) {
                     const who = agentTargets.length ? message.toNames.join(", ") : "the other vibemates";
-                    this.postSystem(`Hop limit ${this.hopLimit} reached: ${who} will not be prompted until ${this.humanName} writes again.`);
+                    this.postSystem(`Hop limit ${this.hopLimit} reached: ${who} will not be prompted until ${this.humanName} writes again.`, undefined, false, { tone: "attention" });
                 }
                 else {
                     this.hops += 1;
@@ -1294,6 +1262,256 @@ export class Room extends EventEmitter {
             return undefined;
         return { items, channel, canCreate: channel === "tool" };
     }
+    skillsForDesign(participantId) {
+        if (!this.skills)
+            return undefined;
+        const runtime = this.runtimes.get(participantId);
+        const channel = runtime?.skillChannel === "tool" ? "tool" : "marker";
+        return {
+            library: this.skills.library.list().filter((s) => !s.problems.length && !s.draft && s.agentInvocable).map((s) => ({ name: s.name, description: s.description })),
+            channel,
+            canCreate: channel === "tool",
+        };
+    }
+    agentInRoom(participantId) {
+        const participant = this.participants.get(participantId);
+        if (!participant || !this.runtimes.has(participantId))
+            throw new Error("this agent is not in the room any more");
+        return participant;
+    }
+    describeRoomForAgent(participantId) {
+        const participant = this.agentInRoom(participantId);
+        const shape = this.templateOf();
+        const skills = this.skills ? this.skills.library.list().filter((s) => !s.problems.length && !s.draft).map((s) => ({ name: s.name, description: s.description })) : [];
+        const templates = this.skills ? this.skills.templates.list().map((t) => ({ id: t.id, name: t.name, builtin: !!t.builtin })) : [];
+        return {
+            room: { name: this.settings.name, topic: this.settings.topic, emoji: this.settings.emoji, dir: this.dir },
+            human: this.settings.humanName,
+            you: participant.name,
+            settings: describeSettings({ ...this.settings, customRules: this.renderRuleReferences(this.settings.customRules) }),
+            rules: ruleLines(this.renderRuleReferences(this.settings.customRules)),
+            vibemates: shape.vibemates.map((v) => {
+                const role = v.role ?? "";
+                const own = v.name === participant.name;
+                return {
+                    name: v.name,
+                    tagline: v.tagline ?? "",
+                    ...(own ? { role } : { rolePrivate: true, roleLength: role.length }),
+                    avatar: v.avatar ?? "",
+                    skills: v.skills ?? [],
+                    agentType: v.agentType,
+                };
+            }),
+            skills,
+            templates,
+            yourBrief: buildBrief(this.settings, this.personaOf(participant), this.roster(), undefined, this.skillsForPrompt(participant, this.runtimes.get(participant.id))),
+            howTo: "Settings are proposed by key with the values above; rules are one per line in customRules; a vibemate is { name, tagline, role, avatar, skills }. Another vibemate's role is private: you learn only that it has one and how long it is, and you may still propose a new one, which the human reads in full on the card. Check a design with lint_room_design, then create_template (a file for the human to pick) or propose_room_changes (a card the human applies).",
+        };
+    }
+    lintDesignForAgent(participantId, kind, design) {
+        this.agentInRoom(participantId);
+        const result = lintRoomDesign(design, { ...this.designContext(kind), skills: this.skillsForDesign(participantId) });
+        return { ok: !result.errors.length, errors: result.errors.map((e) => e.message), warnings: result.warnings.map((w) => w.message), preview: result.preview };
+    }
+    readMessageForAgent(participantId, seq, around) {
+        const participant = this.agentInRoom(participantId);
+        const window = agentReadableWindow(this.messages, seq, around);
+        if (!window)
+            throw new Error(`no message #${seq} in this room (or it is one the vibemates do not see)`);
+        const view = (m) => ({
+            seq: m.seq,
+            from: m.fromName,
+            to: m.toNames,
+            at: new Date(m.ts).toISOString(),
+            text: m.text,
+            ...(m.kind === "system" ? { kind: "system" } : {}),
+            ...(m.edited ? { edited: true } : {}),
+            ...(m.images && m.images.length ? { images: m.images.map((a, i) => ({ ref: `#${m.seq}.${a.n ?? i + 1}`, name: a.name, path: this.imagePath(a) })) } : {}),
+            ...(m.quotes && m.quotes.length ? { quotes: m.quotes.map((q) => ({ n: q.n, seq: q.seq, from: q.fromName, text: q.text })) } : {}),
+        });
+        this.log.info(`read_message: ${participant.name} read #${seq}${around ? ` (around ${around})` : ""}`);
+        return { message: view(window.message), before: window.before.map(view), after: window.after.map(view) };
+    }
+    designContext(kind) {
+        return {
+            kind,
+            humanName: this.settings.humanName,
+            roomName: this.settings.name,
+            base: kind === "room" ? { ...this.settings, customRules: this.renderRuleReferences(this.settings.customRules) } : undefined,
+            knownSkills: this.skills ? this.skills.library.list().map((s) => s.name) : undefined,
+        };
+    }
+    createTemplateForAgent(participantId, design, replace) {
+        const participant = this.agentInRoom(participantId);
+        if (!this.skills)
+            throw new Error("templates are not available in this hub");
+        const result = lintRoomDesign(design, this.designContext("template"));
+        if (result.errors.length)
+            throw new Error(`not saved: ${result.errors.map((e) => e.message).join("; ")}`);
+        const settings = result.settings;
+        const rest = {};
+        for (const key of Object.keys(design.settings ?? {}))
+            if (AGENT_SETTINGS.includes(key))
+                rest[key] = settings[key];
+        const draft = {
+            name: String(design.name).trim(),
+            description: String(design.description ?? "").trim(),
+            emoji: settings.emoji || undefined,
+            settings: rest,
+            vibemates: (design.vibemates ?? []).map((v) => {
+                const out = { name: v.name.trim() };
+                if (v.tagline?.trim())
+                    out.tagline = v.tagline.trim();
+                if (v.role?.trim())
+                    out.role = v.role.trim();
+                if (v.avatar?.trim())
+                    out.avatar = v.avatar.trim();
+                if (v.skills?.length)
+                    out.skills = v.skills.map((s) => s.trim()).filter(Boolean);
+                if (typeof v.replyDelay === "number")
+                    out.replyDelay = v.replyDelay;
+                return out;
+            }),
+        };
+        const library = this.skills.templates;
+        const wanted = templateId(draft.name);
+        const existing = library.list().find((t) => t.id === wanted);
+        let saved;
+        if (existing && replace) {
+            if (existing.builtin)
+                throw new Error(`"${existing.name}" is a template viberoom ships and cannot be replaced; pick another name`);
+            saved = library.overwrite(wanted, draft);
+        }
+        else
+            saved = library.save(draft);
+        this.skills.templatesChanged();
+        const warnings = result.warnings.map((w) => w.message);
+        this.postSystem(`${participant.name} ${existing && replace ? "updated" : "created"} the room template "${saved.name}" (${saved.vibemates.map((v) => v.name).join(", ") || "no vibemates"}); it is in the picker under New room.`);
+        this.log.info(`templates: ${participant.name} ${existing && replace ? "updated" : "created"} "${saved.name}" (${saved.id})`);
+        return {
+            ok: true,
+            message: `Template "${saved.name}" saved as ${saved.id}${existing && !replace ? ` (the name was taken, so the id got a number; pass replace: true to update your own template instead)` : ""}. The human creates a room from it under New room; nothing in this room changed.${warnings.length ? ` Warnings: ${warnings.join("; ")}` : ""}`,
+            id: saved.id,
+            path: join(library.dir, saved.id, "template.json"),
+            warnings,
+        };
+    }
+    proposeRoomChanges(participantId, why, changes) {
+        const participant = this.agentInRoom(participantId);
+        const shape = this.templateOf();
+        const current = shape.vibemates;
+        const vibes = applyVibemateChanges(current, changes.vibemates);
+        if (vibes.errors.length)
+            throw new Error(`not proposed: ${vibes.errors.join("; ")}`);
+        const touched = vibes.ops.flatMap((op) => [op.name, ...(op.fields ?? []).filter((f) => f.field === "name").map((f) => f.to)]);
+        const result = lintRoomDesign({ settings: changes.settings, vibemates: vibes.next }, { ...this.designContext("room"), changedVibemates: touched });
+        if (result.errors.length)
+            throw new Error(`not proposed: ${result.errors.map((e) => e.message).join("; ")}`);
+        const base = this.designContext("room").base;
+        const settingChanges = diffSettings(base, result.settings);
+        if (!settingChanges.length && !vibes.ops.length)
+            throw new Error("not proposed: the change set leaves the room as it is");
+        const touchesOwn = vibes.ops.some((op) => op.name.toLowerCase() === participant.name.toLowerCase()) || settingChanges.some((c) => c.key === "customRules");
+        const proposal = {
+            key: randomUUID(),
+            participantId,
+            participantName: participant.name,
+            ts: Date.now(),
+            why: String(why ?? "").trim().slice(0, 600),
+            settings: settingChanges,
+            vibemates: vibes.ops,
+            warnings: result.warnings.map((w) => w.message),
+            touchesOwn,
+            status: "pending",
+        };
+        const ids = {};
+        for (const op of vibes.ops) {
+            const target = op.op === "add" ? undefined : this.findByName(op.name);
+            if (target)
+                ids[op.name] = target.id;
+        }
+        this.proposalPlans.set(proposal.key, { settings: settingChanges, vibemates: vibes.next, ops: vibes.ops, ids });
+        this.proposals.set(proposal.key, proposal);
+        this.push({ type: "proposal", proposal });
+        const what = [...settingChanges.map((c) => c.key), ...vibes.ops.map((o) => `${o.op} ${o.name}`)].join(", ");
+        this.postSystem(`${participant.name} proposes changes to the room (${what}); apply or reject them on the card.`, "human", false, { tone: "attention" });
+        this.log.info(`proposal ${proposal.key} from ${participant.name}: ${what}`);
+        return {
+            ok: true,
+            message: `Proposal sent to ${this.settings.humanName} as a card in the room (${what}). Nothing changes until they apply it; you will see a room line with the outcome.${proposal.warnings.length ? ` Warnings shown on the card: ${proposal.warnings.join("; ")}` : ""}`,
+            key: proposal.key,
+            warnings: proposal.warnings,
+        };
+    }
+    async resolveProposal(key, accept) {
+        const proposal = this.proposals.get(key);
+        const plan = this.proposalPlans.get(key);
+        if (!proposal || !plan)
+            throw new Error("no such pending proposal");
+        if (proposal.status !== "pending")
+            return proposal;
+        const what = [...proposal.settings.map((c) => c.key), ...proposal.vibemates.map((o) => `${o.op} ${o.name}`)].join(", ");
+        if (!accept) {
+            proposal.status = "rejected";
+            this.proposalPlans.delete(key);
+            this.push({ type: "proposal.resolved", key, status: "rejected" });
+            this.postSystem(`${this.settings.humanName} rejected ${proposal.participantName}'s proposal (${what}).`);
+            return proposal;
+        }
+        const skipped = [];
+        for (const op of plan.ops) {
+            const known = plan.ids[op.name];
+            const existing = known ? this.participants.get(known) : this.findByName(op.name);
+            if (op.op !== "add" && (!existing || existing.kind !== "agent" || existing.status === "left")) {
+                skipped.push(`${op.op} ${op.name} (no longer in the room)`);
+                continue;
+            }
+            if (op.op === "remove") {
+                if (existing && existing.kind === "agent")
+                    await this.removeParticipant(existing.id);
+            }
+            else if (op.op === "update") {
+                if (!existing || existing.kind !== "agent")
+                    continue;
+                const target = plan.vibemates.find((v) => v.name === op.name) ?? plan.vibemates.find((v) => op.fields?.some((f) => f.field === "name" && f.to === v.name));
+                const patch = {};
+                for (const f of op.fields ?? []) {
+                    if (f.field === "name")
+                        patch.name = f.to;
+                    else if (f.field === "tagline")
+                        patch.tagline = target?.tagline ?? f.to;
+                    else if (f.field === "role")
+                        patch.role = target?.role ?? f.to;
+                    else if (f.field === "avatar")
+                        patch.avatar = target?.avatar ?? f.to;
+                    else if (f.field === "skills")
+                        patch.skills = target?.skills ?? [];
+                    else if (f.field === "replyDelay")
+                        patch.replyDelay = target?.replyDelay ?? null;
+                }
+                this.updatePersona(existing.id, patch);
+            }
+            else {
+                const v = plan.vibemates.find((x) => x.name === op.name);
+                if (!v || this.findByName(op.name))
+                    skipped.push(`add ${op.name} (the name is taken now)`);
+                else
+                    this.addUnstaffed({ name: v.name, tagline: v.tagline, role: v.role, avatar: v.avatar, skills: v.skills });
+            }
+        }
+        if (plan.settings.length) {
+            const patch = {};
+            for (const c of plan.settings)
+                patch[c.key] = c.key === "language" ? c.to : c.to;
+            this.updateSettings(patch);
+        }
+        proposal.status = "applied";
+        proposal.skipped = skipped;
+        this.proposalPlans.delete(key);
+        this.push({ type: "proposal.resolved", key, status: "applied", skipped });
+        this.postSystem(`${this.settings.humanName} applied ${proposal.participantName}'s proposal (${what}).${skipped.length ? ` Not applied: ${skipped.join("; ")}.` : ""}`);
+        return proposal;
+    }
     createSkillForAgent(participantId, input) {
         const participant = this.participants.get(participantId);
         if (!participant || !this.runtimes.has(participantId))
@@ -1708,6 +1926,7 @@ export class Room extends EventEmitter {
             const attached = seesImages && (m.to.length === 0 || m.to.includes(id));
             return m.images.map((a, i) => ({ n: a.n ?? i + 1, ref: `#${m.seq}.${a.n ?? i + 1}`, name: a.name, path: this.imagePath(a), mimeType: a.mimeType, attached, forNames: m.to.length ? m.toNames : [] }));
         };
+        const backlogQuotes = (m) => m.quotes && m.quotes.length ? m.quotes.map((q) => ({ n: q.n, seq: q.seq, fromName: q.fromName, ts: q.ts, text: q.text })) : undefined;
         const prompt = composePrompt({
             brief: briefReason ? buildBrief(settings, persona, roster, runtime.notesForBrief ?? (participant.notes && (participant.notesSeq ?? -1) >= runtime.lastBriefSeq ? participant.notes : undefined), skillsForPrompt) : undefined,
             header: buildHeader(settings, persona, roster, this.hops, notes, skillsForPrompt),
@@ -1720,6 +1939,7 @@ export class Room extends EventEmitter {
                     toNames: m.toNames,
                     text: m.text,
                     images: backlogImages(m),
+                    quotes: backlogQuotes(m),
                 }),
             omitted,
             personaName: participant.name,
@@ -1819,7 +2039,7 @@ export class Room extends EventEmitter {
             if (isContextFullError(failure))
                 this.contextFull(participant, runtime, failure ?? "");
             else
-                this.postSystem(`${participant.name} could not answer: ${(failure ?? "no result").slice(0, 240)}`);
+                this.postSystem(`${participant.name} could not answer: ${(failure ?? "no result").slice(0, 240)}`, undefined, false, { tone: "error" });
             return null;
         }
         return this.finalizeTurn(participant, runtime, draft, result, Date.now() - startedAt, retry, published, publishedAt);
@@ -1881,10 +2101,13 @@ export class Room extends EventEmitter {
             if (retry) {
                 this.closeRetry(retry, cancelled ? "the correction turn was stopped; nothing was posted" : "the agent withdrew the reply");
                 if (cancelled)
-                    this.postSystem(`${participant.name} was stopped.`);
+                    this.postSystem(`${participant.name} was stopped by ${this.humanName}.`, undefined, false, { tone: "attention" });
+            }
+            else if (cancelled) {
+                this.postSystem(`${participant.name} was stopped by ${this.humanName}.`, undefined, false, { tone: "attention" });
             }
             else {
-                this.postSystem(cancelled ? `${participant.name} was stopped.` : `${participant.name} read the room and has nothing to add.`);
+                this.postSystem(`${participant.name} read the room and has nothing to add.`);
             }
             return null;
         }
@@ -1894,7 +2117,7 @@ export class Room extends EventEmitter {
             participant.failedTurns = (participant.failedTurns ?? 0) + 1;
             participant.statusDetail = `agent error: ${text.replace(/\s+/g, " ").slice(0, 120)}${text.length > 120 ? "…" : ""}`;
             this.push({ type: "participant", participant });
-            this.postSystem(`${participant.name}'s agent reported an error instead of a reply: ${text.slice(0, 200)}${text.length > 200 ? "…" : ""}`);
+            this.postSystem(`${participant.name}'s agent reported an error instead of a reply: ${text.slice(0, 200)}${text.length > 200 ? "…" : ""}`, undefined, false, { tone: "error" });
             runtime.log.warn(`adapter error text treated as failed turn: ${text.slice(0, 200)}`);
             if (retry)
                 this.closeRetry(retry, "the agent reported an error instead of a corrected reply");
@@ -1945,6 +2168,7 @@ export class Room extends EventEmitter {
             text,
             streaming: false,
             stopReason: result.stopReason,
+            ...(cancelled ? { stoppedBy: this.humanName } : {}),
             usage: result.usage ?? null,
             durationMs,
         };
@@ -1952,17 +2176,17 @@ export class Room extends EventEmitter {
         if (publishedAt !== null && this.messages.some((x) => x.kind === "chat" && x.id !== message.id && x.ts > publishedAt)) {
             const at = new Date(draft.ts);
             const hhmm = `${String(at.getHours()).padStart(2, "0")}:${String(at.getMinutes()).padStart(2, "0")}`;
-            this.postSystem(`${participant.name} finished the reply started at ${hhmm} · ${Math.round(durationMs / 1000)} s`, "human", false, { refId: message.id, agentId: participant.id });
+            this.postSystem(`${participant.name} finished the reply started at ${hhmm} · ${formatDuration(durationMs)}`, "human", false, { refId: message.id, agentId: participant.id });
         }
         if (retry) {
             this.closeRetry(retry, corrections.length ? `corrected reply posted, but it still breaks: ${corrections.map((c) => c.replace(/^reminder:\s*/i, "")).join("; ")}` : "corrected reply posted");
         }
         if (cancelled) {
-            this.postSystem(`${participant.name} was stopped mid-reply; the partial reply stays in the log.`);
+            this.postSystem(`${participant.name} was stopped mid-reply by ${this.humanName}; what it had written stays in the room.`, "agents", false, { tone: "attention" });
             return null;
         }
         if (result.stopReason !== "end_turn") {
-            this.postSystem(`${participant.name} stopped with ${result.stopReason}.`);
+            this.postSystem(`${participant.name} stopped with ${result.stopReason}.`, undefined, false, { tone: "attention" });
         }
         this.route(message);
         return null;
@@ -2127,21 +2351,25 @@ export class Room extends EventEmitter {
             }
             case "usage_update": {
                 const u = update;
+                if (emptyUsageReport(runtime.lastUsed, u.used)) {
+                    runtime.log.info(`usage report of 0 after ${runtime.lastUsed} tokens ignored (failed request?)`);
+                    return;
+                }
                 participant.contextUsed = u.used;
                 participant.contextSize = u.size;
                 if (u.cost)
                     participant.cost = { amount: u.cost.amount, currency: u.cost.currency };
-                if (runtime.lastUsed > 0 && u.used < runtime.lastUsed * 0.7 && !runtime.briefPending) {
+                if (looksCompacted(runtime.lastUsed, u.used) && !runtime.briefPending) {
                     runtime.briefPending = `context shrank from ${runtime.lastUsed} to ${u.used} tokens (compaction?)`;
                     runtime.log.info(`usage dropped ${runtime.lastUsed} -> ${u.used}; brief scheduled`);
                     participant.contextEvent = { kind: "compacted", at: Date.now(), used: u.used, size: u.size };
                     runtime.notesDue = overThreshold(u.used, u.size);
-                    this.postSystem(`${participant.name} compacted its context (${Math.round(runtime.lastUsed / 1000)}k → ${Math.round(u.used / 1000)}k tokens); the room rules are re-sent with its next turn${participant.notes ? ", with its notes" : ""}.`, "human");
+                    this.postSystem(`${participant.name} compacted its context (${Math.round(runtime.lastUsed / 1000)}k → ${Math.round(u.used / 1000)}k tokens); the room rules are re-sent with its next turn${participant.notes ? ", with its notes" : ""}.`, "human", false, { tone: "attention" });
                 }
                 if (crossedThreshold(runtime.lastUsed, u.used, u.size)) {
                     runtime.notesDue = true;
                     participant.contextEvent = { kind: "threshold", at: Date.now(), used: u.used, size: u.size };
-                    this.postSystem(`${participant.name} is at ${Math.round((100 * u.used) / u.size)}% of its context; it will leave notes with its next reply. You can respawn it with memory from its panel.`, "human");
+                    this.postSystem(`${participant.name} is at ${Math.round((100 * u.used) / u.size)}% of its context; it will leave notes with its next reply. You can respawn it with memory from its panel.`, "human", false, { tone: "attention" });
                     runtime.log.info(`context at ${u.used}/${u.size}: notes due`);
                 }
                 runtime.lastUsed = u.used;
@@ -2308,8 +2536,17 @@ export class Room extends EventEmitter {
         participant.effort = pick("thought_level") ?? participant.effort;
         participant.mode = pick("mode") ?? participant.mode;
     }
-    failStart(participant, error, fresh) {
+    failStart(participant, error, fresh, stderr = []) {
         participant.statusDetail = error instanceof Error ? error.message : String(error);
+        const recipe = getRecipe(participant.agentType ?? "");
+        participant.trouble = classifyStartFailure({
+            error: participant.statusDetail,
+            stderr,
+            vendor: recipe?.vendor ?? participant.agentVendor ?? "The coding agent",
+            loginCommand: recipe?.loginCommand || undefined,
+            installHint: recipe?.installHint || undefined,
+            loginState: recipe?.loginState,
+        });
         this.notice(`${participant.name}: failed to start: ${participant.statusDetail}`, "error");
         if (fresh) {
             participant.status = "error";
@@ -2321,6 +2558,7 @@ export class Room extends EventEmitter {
             participant.status = "offline";
             this.push({ type: "participant", participant });
         }
+        return new Error(`${participant.trouble.what} ${participant.trouble.advice} (${participant.statusDetail})`);
     }
     cancelPermissionsOf(id) {
         for (const [key, entry] of this.permissions) {