viberoom 0.7.0 → 0.9.0

package/dist/recipes.js

@@ -1,12 +1,21 @@
 // viberoom - Copyright (c) 2026 Todor Rusev - AGPL-3.0-or-later; see LICENSE
 import { execSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loginState } from "./agent-health.js";
 const isWindows = process.platform === "win32";
+const ICON_VERSION = (() => {
+    try {
+        return String(createRequire(import.meta.url)("../package.json").version ?? "0");
+    }
+    catch {
+        return "0";
+    }
+})();
+const iconUrl = (id) => `/vendor-icons/${id}.svg?v=${ICON_VERSION}`;
 function resolvePackageEntry(packageName, relativeEntry) {
     try {
         const require = createRequire(import.meta.url);
@@ -141,6 +150,46 @@ function resolveClaudeCode() {
 function resolveCodex() {
     return resolveGlobalNpmBin("codex") ?? resolveOnPath(["codex"]);
 }
+function realHome() {
+    try {
+        return realpathSync(homedir());
+    }
+    catch {
+        return null;
+    }
+}
+function resolveGrok() {
+    const exe = isWindows ? "grok.exe" : "grok";
+    const home = realHome();
+    const dirs = [process.env.GROK_BIN_DIR, process.env.GROK_HOME && join(process.env.GROK_HOME, "bin"), join(homedir(), ".grok", "bin"), home && join(home, ".grok", "bin")];
+    for (const dir of dirs)
+        if (dir && existsSync(join(dir, exe)))
+            return join(dir, exe);
+    const onPath = resolveOnPath(["grok"]);
+    return onPath && !/\.(cmd|bat|ps1)$/i.test(onPath) ? onPath : null;
+}
+function resolveHermes() {
+    const hermesHome = process.env.HERMES_HOME || (isWindows ? process.env.LOCALAPPDATA && join(process.env.LOCALAPPDATA, "hermes") : join(homedir(), ".hermes"));
+    const scripts = isWindows ? "Scripts" : "bin";
+    const exe = (name) => (isWindows ? `${name}.exe` : name);
+    const candidates = [];
+    if (hermesHome) {
+        const venv = join(hermesHome, "hermes-agent", "venv");
+        candidates.push({ command: join(venv, scripts, exe("hermes-acp")), args: [] }, { command: join(venv, scripts, exe("hermes")), args: ["acp"] });
+        if (isWindows)
+            candidates.push({ command: join(hermesHome, "bin", "hermes-acp.exe"), args: [] }, { command: join(hermesHome, "bin", "hermes.exe"), args: ["acp"] });
+    }
+    if (!isWindows) {
+        candidates.push({ command: join(homedir(), ".local", "bin", "hermes"), args: ["acp"] }, { command: "/usr/local/lib/hermes-agent/venv/bin/hermes-acp", args: [] }, { command: "/usr/local/bin/hermes", args: ["acp"] });
+    }
+    for (const candidate of candidates)
+        if (existsSync(candidate.command))
+            return candidate;
+    const onPath = resolveOnPath(["hermes-acp", "hermes"]);
+    if (onPath && !/\.(cmd|bat|ps1)$/i.test(onPath))
+        return { command: onPath, args: /^hermes-acp/i.test(basename(onPath)) ? [] : ["acp"] };
+    return null;
+}
 const vendorDir = join(dirname(fileURLToPath(import.meta.url)), "..", "vendor", "acp");
 const claudeAdapter = join(vendorDir, "claude-agent-acp", "dist", "index.js");
 const codexAdapter = join(vendorDir, "codex-acp", "dist", "index.js");
@@ -151,12 +200,14 @@ const geminiEntry = resolvePackageEntry("@google/gemini-cli", join("bundle", "ge
 const cursorAgent = resolveCursorAgent();
 const openCodeExe = resolveOpenCode();
 const copilotExe = resolveCopilot();
+const grokExe = resolveGrok();
+const hermesLaunch = resolveHermes();
 const recipes = [
     {
         id: "claude",
         label: "Claude (claude-agent-acp)",
         vendor: "Claude",
-        icon: "/vendor-icons/claude.svg",
+        icon: iconUrl("claude"),
         tested: true,
         note: "Adapter around the Claude Agent SDK, driving the Claude Code installed on this machine with its login and settings.",
         modelPresets: ["haiku", "sonnet", "opus", "default"],
@@ -182,7 +233,7 @@ const recipes = [
         id: "codex",
         label: "Codex (codex-acp)",
         vendor: "Codex",
-        icon: "/vendor-icons/codex.svg",
+        icon: iconUrl("codex"),
         tested: true,
         note: "Adapter around the Codex App Server of the Codex CLI installed on this machine; uses its login (~/.codex) or CODEX_API_KEY. Mode 'agent' edits the working directory without asking; 'read-only' for a chat-only participant.",
         modelPresets: ["gpt-5.4-mini", "gpt-5.5", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"],
@@ -208,7 +259,7 @@ const recipes = [
         id: "gemini",
         label: "Gemini CLI (gemini --acp)",
         vendor: "Gemini",
-        icon: "/vendor-icons/gemini.svg",
+        icon: iconUrl("gemini"),
         tested: true,
         note: "Native ACP mode of the globally installed Gemini CLI; uses the machine's Gemini login / API key. Exposes no config options over ACP: the model is fixed at launch (--model).",
         modelPresets: ["gemini-3.8-flash", "gemini-3.7-flash"],
@@ -235,7 +286,7 @@ const recipes = [
         id: "cursor",
         label: "Cursor (cursor-agent acp)",
         vendor: "Cursor",
-        icon: "/vendor-icons/cursor.svg",
+        icon: iconUrl("cursor"),
         tested: true,
         note: "Cursor's CLI agent in native ACP mode; uses the machine's Cursor login (agent login) or CURSOR_API_KEY. Mode 'agent' edits without asking; 'ask' is read-only Q&A. Models: see the session settings after joining.",
         modelPresets: [],
@@ -261,7 +312,7 @@ const recipes = [
         id: "opencode",
         label: "OpenCode (opencode acp)",
         vendor: "OpenCode",
-        icon: "/vendor-icons/opencode.svg",
+        icon: iconUrl("opencode"),
         tested: false,
         note: "The open-source coding agent in native ACP mode; the model list comes from the providers configured in OpenCode (opencode providers). Mode 'plan' is read-only; 'build' edits the working directory (OpenCode's own permission config decides what still asks; the questions arrive here).",
         modelPresets: [],
@@ -286,7 +337,7 @@ const recipes = [
         id: "copilot",
         label: "GitHub Copilot (copilot --acp)",
         vendor: "Copilot",
-        icon: "/vendor-icons/copilot.svg",
+        icon: iconUrl("copilot"),
         tested: false,
         note: "GitHub Copilot CLI in native ACP mode; uses the machine's Copilot login (copilot login). Session modes agent / plan / autopilot; the 'allow_all' option decides whether tool calls ask for permission. Exposes no model option over ACP: the model is fixed at launch (--model, e.g. auto).",
         modelPresets: ["auto"],
@@ -312,6 +363,57 @@ const recipes = [
             args: ["--acp", ...(model ? ["--model", model] : [])],
         }),
     },
+    {
+        id: "grok",
+        label: "Grok Build (grok agent stdio)",
+        vendor: "Grok",
+        icon: iconUrl("grok"),
+        tested: true,
+        note: "xAI's coding agent in its native ACP mode; uses this machine's Grok login (grok login) or XAI_API_KEY. It reports no session modes over ACP, so the mode is a launch flag: 'ask-first' asks before every tool call, 'always-approve' never does; a change restarts the session with its notes kept. Model and reasoning effort are session options (the model also goes on the launch command).",
+        modelPresets: ["grok-4.6", "grok-4.5"],
+        defaultModel: null,
+        effortPresets: ["xhigh", "high", "medium", "low"],
+        defaultEffort: null,
+        modePresets: ["ask-first", "always-approve"],
+        defaultMode: "ask-first",
+        bypassMode: "always-approve",
+        unavailableReason: grokExe ? null : "Grok Build not found",
+        installedAt: grokExe,
+        installHint: "curl -fsSL https://x.ai/cli/install.sh | bash (Windows: irm https://x.ai/cli/install.ps1 | iex), or npm install -g @xai-official/grok; then grok login",
+        loginCommand: "grok login",
+        login: { env: ["XAI_API_KEY", "GROK_DEPLOYMENT_KEY"], files: [".grok/auth.json"], command: "grok login" },
+        loginState: "unknown",
+        modeAtLaunch: true,
+        build: ({ model, mode }) => ({
+            command: grokExe ?? "",
+            args: ["agent", ...(model ? ["-m", model] : []), ...(mode === "always-approve" ? ["--always-approve"] : []), "stdio"],
+        }),
+    },
+    {
+        id: "hermes",
+        label: "Hermes Agent (hermes acp)",
+        vendor: "Hermes",
+        icon: iconUrl("hermes"),
+        tested: true,
+        note: "Nous Research's open-source agent in its native ACP mode; the provider and model are the ones configured in Hermes (hermes model). Mode 'default' asks before edits, 'accept_edits' auto-allows workspace and /tmp edits, 'dont_ask' auto-allows file edits except sensitive paths; a tool call that still needs permission arrives here with Hermes' own choices: once, this session, or always.",
+        modelPresets: [],
+        defaultModel: null,
+        effortPresets: [],
+        defaultEffort: null,
+        modePresets: ["default", "accept_edits", "dont_ask"],
+        defaultMode: "default",
+        bypassMode: "dont_ask",
+        unavailableReason: hermesLaunch ? null : "Hermes Agent not found",
+        installedAt: hermesLaunch?.command ?? null,
+        installHint: "curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash (Windows: iex (irm https://hermes-agent.nousresearch.com/install.ps1)), then hermes model",
+        loginCommand: "hermes model",
+        login: { env: [], files: [], command: "hermes model" },
+        loginState: "unknown",
+        build: () => ({
+            command: hermesLaunch?.command ?? "",
+            args: hermesLaunch?.args ?? [],
+        }),
+    },
 ];
 const fakeAgent = process.env.VIBEROOM_FAKE_AGENT;
 if (fakeAgent) {

package/dist/room-design.js

@@ -1,11 +1,11 @@
 // viberoom - Copyright (c) 2026 Todor Rusev - AGPL-3.0-or-later; see LICENSE
 import { AGENT_SETTINGS, DEFAULT_ROOM_SETTINGS, NAME_PATTERN, ROOM_SETTINGS_SPEC, SILENT_MARKER, REQUEST_BRIEF_MARKER, buildBrief, coerceSetting } from "./persona.js";
 export const TAGLINE_MAX = 80;
-export const ROLE_MAX = 4000;
+export const ROLE_MAX = 8000;
 export const AVATAR_MAX = 8;
 export const RULES_SOFT_MAX = 12;
 export const ROLE_SOFT_MAX = 1200;
-export const RULES_NEAR_LIMIT = 3000;
+export const RULES_NEAR_LIMIT = 0.75;
 export function ruleLines(customRules) {
     return customRules
         .split(/\r?\n/)
@@ -57,6 +57,7 @@ export function lintRoomDesign(design, context) {
         if (!vibemates.length)
             error("template-no-vibemates", "a template needs at least one vibemate");
     }
+    const roleMax = raw.briefTextLimit !== undefined ? settings.briefTextLimit : context.briefTextLimit ?? settings.briefTextLimit ?? ROLE_MAX;
     const seen = new Map();
     const touched = context.changedVibemates ? new Set(context.changedVibemates.map((n) => n.trim().toLowerCase())) : null;
     for (const [i, v] of vibemates.entries()) {
@@ -79,8 +80,8 @@ export function lintRoomDesign(design, context) {
             error("tagline-too-long", `${who}: the tagline is at most ${TAGLINE_MAX} characters (it is the one line the others see)`);
         else if (soft && !(v?.tagline ?? "").trim())
             warn("vibemate-no-tagline", `${who} has no tagline: the others read it in the roster to know what this one leans to`);
-        if ((v?.role ?? "").length > ROLE_MAX)
-            error("role-too-long", `${who}: the role is at most ${ROLE_MAX} characters`);
+        if ((v?.role ?? "").length > roleMax)
+            error("role-too-long", `${who}: the role is ${v.role.length} characters; the limit is ${roleMax} (the briefTextLimit setting)`);
         else if (soft && !(v?.role ?? "").trim())
             warn("vibemate-no-role", `${who} has no role: without one it is the agent's default self, not a character`);
         else if (soft && (v.role ?? "").length > ROLE_SOFT_MAX)
@@ -109,8 +110,10 @@ export function lintRoomDesign(design, context) {
     const rules = ruleLines(settings.customRules);
     if (rules.length > RULES_SOFT_MAX)
         warn("too-many-rules", `${rules.length} rules: every vibemate carries them on every turn; ${RULES_SOFT_MAX} is a full protocol, longer belongs in a skill`);
-    if (settings.customRules.length > RULES_NEAR_LIMIT)
-        warn("rules-near-limit", `the rules are ${settings.customRules.length} characters; the hub stores at most 4000`);
+    if (settings.customRules.length > roleMax)
+        error("rules-too-long", `the rules are ${settings.customRules.length} characters; the limit is ${roleMax} (the briefTextLimit setting)`);
+    else if (settings.customRules.length > roleMax * RULES_NEAR_LIMIT)
+        warn("rules-near-limit", `the rules are ${settings.customRules.length} characters; the limit is ${roleMax}`);
     for (const rule of rules) {
         for (const m of BRIEF_MECHANICS)
             if (m.pattern.test(rule))

package/dist/room.js

@@ -21,6 +21,7 @@ import { applyVibemateChanges, diffSettings, lintRoomDesign, ruleLines } from ".
 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 AUTH_WAIT_MS = 8000;
 const COLORS = ["#6d5dfc", "#16a34a", "#d97706", "#dc2626", "#0891b2", "#be185d", "#4d7c0f", "#7c3aed"];
 const MENTION_PATTERN = /@([\p{L}\p{N}][\p{L}\p{N}_-]*)/gu;
 const RULE_REF_TOKEN = /@\{p:([^}]+)\}/g;
@@ -113,7 +114,7 @@ export class Room extends EventEmitter {
     restore(stored) {
         for (const s of stored) {
             if (!s.agentType) {
-                this.addUnstaffed({ name: s.name, tagline: s.tagline, role: s.role, avatar: s.avatar, skills: s.skills, color: s.color, id: s.id });
+                this.addUnstaffed({ name: s.name, tagline: s.tagline, role: s.role, avatar: s.avatar, skills: s.skills, color: s.color, id: s.id, textCheck: "keep" });
                 continue;
             }
             const recipe = getRecipe(s.agentType);
@@ -505,14 +506,8 @@ export class Room extends EventEmitter {
         participant.sessionId = undefined;
         this.restoredSeen.set(id, this.seq);
         this.push({ type: "participant", participant });
-        if (!online) {
-            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;
-        }
+        if (!online)
+            this.log.info(`respawn of ${participant.name} (offline): stored session dropped, starting it now`);
         await this.reconnect(id, memory
             ? { 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` });
@@ -676,7 +671,7 @@ export class Room extends EventEmitter {
                 continue;
             let value = coerceSetting(key, patch[key]);
             if (key === "customRules") {
-                const resolved = this.resolveRuleReferences(value);
+                const resolved = this.resolveRuleReferences(this.guardBriefText("The room rules text", value, "refuse", next.briefTextLimit));
                 unknownRefs = resolved.unknown;
                 value = resolved.stored;
             }
@@ -699,6 +694,14 @@ export class Room extends EventEmitter {
         }
         return this.settings;
     }
+    guardBriefText(what, text, check = "refuse", limit = this.settings.briefTextLimit) {
+        if (check === "keep" || text.length <= limit)
+            return text;
+        if (check === "refuse")
+            throw new Error(`${what} is ${text.length} characters; this room's limit is ${limit} (the briefTextLimit setting). Shorten it, move the instructions into a skill, or raise the limit.`);
+        this.postSystem(`${what} is ${text.length} characters, over this room's limit of ${limit}; kept as it is, but the next edit has to fit (shorten it or raise briefTextLimit).`, "human", false, { tone: "attention" });
+        return text;
+    }
     updatePersona(id, patch) {
         const participant = this.participants.get(id);
         const runtime = this.runtimes.get(id);
@@ -727,7 +730,7 @@ export class Room extends EventEmitter {
             changed.push("tagline");
         }
         if (patch.role !== undefined && patch.role.trim() !== (participant.role ?? "")) {
-            participant.role = patch.role.trim().slice(0, 4000);
+            participant.role = this.guardBriefText(`${participant.name}'s vibio`, patch.role.trim());
             changed.push("role");
         }
         if (patch.avatar !== undefined) {
@@ -786,7 +789,7 @@ export class Room extends EventEmitter {
             return cached;
         const cwd = ensureDir(join(this.dataDir, ".probe"));
         const log = this.log.child(`probe:${recipeId}`);
-        const launch = recipe.build({ model: null });
+        const launch = recipe.build({ model: null, mode: null });
         const agent = new AcpAgent({ ...launch, cwd }, {
             onSessionUpdate: () => undefined,
             onPermissionRequest: async () => ({ outcome: { outcome: "cancelled" } }),
@@ -798,7 +801,7 @@ export class Room extends EventEmitter {
             const info = await Promise.race([
                 (async () => {
                     const init = await agent.initialize({ name: "viberoom", version: "0.2.0" });
-                    const session = await this.openSession(agent, cwd, log);
+                    const session = await this.openSession(agent, cwd, log, [], recipe);
                     const result = {
                         recipeId,
                         agentInfo: { name: init.agentInfo?.name ?? null, version: init.agentInfo?.version ?? null },
@@ -806,6 +809,7 @@ export class Room extends EventEmitter {
                         modes: session.modes ?? null,
                         configOptions: session.configOptions ?? [],
                         modelAtLaunch: !!recipe.modelAtLaunch,
+                        modeAtLaunch: !!recipe.modeAtLaunch,
                         discoveredAt: Date.now(),
                         durationMs: 0,
                     };
@@ -858,7 +862,7 @@ export class Room extends EventEmitter {
             turns: 0,
             color: options.color ?? COLORS[this.colorIndex++ % COLORS.length],
             tagline: (options.tagline ?? "").trim().slice(0, 80),
-            role: (options.role ?? "").trim().slice(0, 4000),
+            role: this.guardBriefText(`${name}'s vibio`, (options.role ?? "").trim(), options.textCheck),
             avatar: (options.avatar ?? "").trim().slice(0, 8) || undefined,
             replyDelay: options.replyDelay === undefined || options.replyDelay === null ? undefined : Math.max(0, Math.min(120, Number(options.replyDelay) || 0)),
             skills: normalizeSkillList(options.skills ?? undefined),
@@ -888,7 +892,7 @@ export class Room extends EventEmitter {
             turns: 0,
             color: input.color ?? COLORS[this.colorIndex++ % COLORS.length],
             tagline: (input.tagline ?? "").trim().slice(0, 80),
-            role: (input.role ?? "").trim().slice(0, 4000),
+            role: this.guardBriefText(`${name}'s vibio`, (input.role ?? "").trim(), input.textCheck),
             avatar: (input.avatar ?? "").trim().slice(0, 8) || undefined,
             skills: normalizeSkillList(input.skills),
             violations: 0,
@@ -938,7 +942,7 @@ export class Room extends EventEmitter {
         const name = participant.name;
         const log = this.log.child(name);
         const cwd = ensureDir(this.dir);
-        const spec = recipe.build({ model: launch.model });
+        const spec = recipe.build({ model: launch.model, mode: launch.mode });
         const transcript = new Transcript(join(this.dataDir, "transcripts"), name);
         log.info(`spawning ${spec.command} ${spec.args.join(" ")} (cwd ${cwd}); transcript ${transcript.path}`);
         const stderrTail = [];
@@ -990,7 +994,7 @@ export class Room extends EventEmitter {
                 }
             }
             if (!session)
-                session = await this.openSession(agent, cwd, log, mcpServers);
+                session = await this.openSession(agent, cwd, log, mcpServers, recipe);
             participant.sessionId = session.sessionId;
             participant.sessionOrigin = origin;
             const storedSeen = this.restoredSeen.get(id);
@@ -1044,10 +1048,15 @@ export class Room extends EventEmitter {
             const warnings = await this.applyConfig(runtime, participant, {
                 model: recipe.modelAtLaunch ? null : launch.model,
                 effort: launch.effort,
-                mode: launch.mode,
+                mode: recipe.modeAtLaunch ? null : launch.mode,
             });
             if (recipe.modelAtLaunch && launch.model)
                 participant.model = launch.model;
+            if (recipe.modeAtLaunch) {
+                if (!participant.modes?.length)
+                    participant.modes = recipe.modePresets.map((id) => ({ id, name: id }));
+                participant.mode = launch.mode ?? recipe.defaultMode ?? participant.mode;
+            }
             for (const w of warnings)
                 this.notice(`${name}: ${w}`, "warn");
             participant.status = "idle";
@@ -1148,6 +1157,16 @@ export class Room extends EventEmitter {
         const participant = this.participants.get(id);
         if (!runtime || !participant)
             throw new Error("no such agent (offline?)");
+        const recipe = getRecipe(participant.agentType ?? "");
+        if (recipe?.modeAtLaunch && configId === "mode") {
+            if (!recipe.modePresets.includes(String(value)))
+                throw new Error(`${participant.name}: no mode "${value}" (${recipe.modePresets.join(", ")})`);
+            participant.launch = { model: participant.launch?.model ?? null, effort: participant.launch?.effort ?? null, mode: String(value) };
+            participant.mode = String(value);
+            this.push({ type: "participant", participant });
+            await this.respawnAgent(id, { memory: true, reason: "its mode changed" });
+            return;
+        }
         const hasOption = participant.configOptions?.some((o) => o.id === configId);
         if (!hasOption && configId === "mode" && participant.modes?.some((m) => m.id === value)) {
             await runtime.agent.setMode(runtime.sessionId, String(value));
@@ -1205,6 +1224,11 @@ export class Room extends EventEmitter {
                 const skill = this.skills?.library.get(message.skill.name);
                 if (!message.to.length)
                     targets = targets.filter((id) => this.hasSkill(this.participants.get(id), message.skill.name));
+                if (!targets.length && !message.to.length) {
+                    const alone = [...this.runtimes.keys()].filter(live);
+                    if (alone.length === 1)
+                        targets = alone;
+                }
                 if (!targets.length)
                     this.notice(`Nobody in this room has the skill "${message.skill.name}"; attach it to an agent first, or address one with @.`, "warn");
                 if (skill) {
@@ -1241,13 +1265,19 @@ export class Room extends EventEmitter {
             this.requestTurn(id, message.to.includes(id) || !!message.skill);
     }
     hasSkill(participant, name) {
+        if (this.isBuiltinSkill(name))
+            return true;
         if (!participant?.skills)
             return false;
         const lower = name.toLowerCase();
         return participant.skills.some((s) => s.toLowerCase() === lower);
     }
+    isBuiltinSkill(name) {
+        const skill = this.skills?.library.get(name);
+        return !!skill && skill.author === BUILTIN_AUTHOR && !skill.draft && !skill.problems.length;
+    }
     attachedSkills(participant) {
-        if (!this.skills || !participant.skills?.length)
+        if (!this.skills)
             return [];
         return this.skills.library.list().filter((s) => !s.problems.length && !s.draft && this.hasSkill(participant, s.name));
     }
@@ -1338,6 +1368,7 @@ export class Room extends EventEmitter {
             humanName: this.settings.humanName,
             roomName: this.settings.name,
             base: kind === "room" ? { ...this.settings, customRules: this.renderRuleReferences(this.settings.customRules) } : undefined,
+            briefTextLimit: this.settings.briefTextLimit,
             knownSkills: this.skills ? this.skills.library.list().map((s) => s.name) : undefined,
         };
     }
@@ -1443,6 +1474,116 @@ export class Room extends EventEmitter {
             warnings: proposal.warnings,
         };
     }
+    async describeLooksForAgent(participantId) {
+        const participant = this.agentInRoom(participantId);
+        if (!this.skills?.looks || !this.skills.appearance)
+            throw new Error("looks are not available in this hub");
+        const described = await this.skills.looks.describe();
+        return { you: participant.name, human: this.settings.humanName, appearance: this.skills.appearance.current(), ...described };
+    }
+    async lintLookForAgent(participantId, raw) {
+        this.agentInRoom(participantId);
+        if (!this.skills?.looks)
+            throw new Error("looks are not available in this hub");
+        try {
+            const checked = await this.skills.looks.check(raw);
+            return { ok: checked.lint.ok, id: checked.spec.id, errors: checked.lint.errors.map((e) => ({ key: e.key, message: e.message })), warnings: checked.lint.warnings.map((w) => ({ key: w.key, message: w.message })), report: checked.lint.report };
+        }
+        catch (error) {
+            return { ok: false, errors: [{ key: "spec", message: error instanceof Error ? error.message : String(error) }], warnings: [], report: [] };
+        }
+    }
+    async createLookForAgent(participantId, raw, replace) {
+        const participant = this.agentInRoom(participantId);
+        if (!this.skills?.looks)
+            throw new Error("looks are not available in this hub");
+        let saved;
+        try {
+            saved = await this.skills.looks.save(raw, { author: participant.name, replace });
+        }
+        catch (error) {
+            throw new Error(`not saved: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const warnings = saved.lint.warnings.map((w) => w.message);
+        this.postSystem(`${participant.name} saved the look "${saved.spec.label}" (Settings → Appearance).`);
+        this.log.info(`${participant.name} saved look ${saved.spec.id}`);
+        return {
+            ok: true,
+            message: `Saved the look "${saved.spec.label}" (id ${saved.spec.id}) among ${this.settings.humanName}'s own looks: it is in Settings → Appearance now, after the looks viberoom ships. Nothing is worn until ${this.settings.humanName} picks it; propose_look_changes with look "${saved.spec.id}" offers it as a card.${warnings.length ? ` Warnings: ${warnings.join("; ")}` : ""}`,
+            id: saved.spec.id,
+            warnings,
+        };
+    }
+    async proposeLookChanges(participantId, why, changes) {
+        const participant = this.agentInRoom(participantId);
+        if (!this.skills?.appearance || !this.skills.looks)
+            throw new Error("looks are not available in this hub");
+        const current = this.skills.appearance.current();
+        const patch = {};
+        const rows = [];
+        if (changes.look !== undefined) {
+            const lookId = String(changes.look).trim();
+            const known = await this.skills.appearance.ownAdjustments(lookId);
+            if (!known)
+                throw new Error(`not proposed: no look "${lookId}" (the looks viberoom ships, or one of ${this.settings.humanName}'s own by its id)`);
+            patch.look = lookId;
+            if (lookId !== current.look)
+                rows.push({ key: "look", from: current.look, to: lookId });
+        }
+        if (changes.adjust !== undefined) {
+            if (!changes.adjust || typeof changes.adjust !== "object" || Array.isArray(changes.adjust))
+                throw new Error("not proposed: adjust is an object of adjustable keys and values");
+            const lookId = String(changes.look ?? current.look);
+            const own = await this.skills.appearance.ownAdjustments(lookId);
+            if (!own)
+                throw new Error(`not proposed: no look "${lookId}" to fine-tune`);
+            const merged = { ...(current.custom?.[lookId] ?? {}), ...changes.adjust };
+            patch.custom = { [lookId]: merged };
+            const previewed = this.skills.appearance.preview({ custom: { [lookId]: merged } });
+            for (const key of Object.keys(changes.adjust)) {
+                const from = current.custom?.[lookId]?.[key] ?? own.values[key] ?? "";
+                const to = previewed.custom[lookId]?.[key] ?? "";
+                if (String(from).toLowerCase() !== String(to).toLowerCase())
+                    rows.push({ key: `${key} (${own.label})`, from, to });
+            }
+        }
+        for (const key of ["chatFontSize", "font", "mono"]) {
+            if (changes[key] === undefined)
+                continue;
+            patch[key] = changes[key];
+            const previewed = this.skills.appearance.preview({ [key]: changes[key] });
+            if (String(previewed[key]) !== String(current[key]))
+                rows.push({ key: key === "chatFontSize" ? "text size" : key === "font" ? "font" : "code font", from: current[key], to: previewed[key] });
+        }
+        this.skills.appearance.preview(patch);
+        if (!rows.length)
+            throw new Error("not proposed: the change leaves the window as it is");
+        const proposal = {
+            key: randomUUID(),
+            participantId,
+            participantName: participant.name,
+            ts: Date.now(),
+            why: String(why ?? "").trim().slice(0, 600),
+            settings: [],
+            vibemates: [],
+            appearance: rows,
+            warnings: [],
+            touchesOwn: false,
+            status: "pending",
+        };
+        this.proposalPlans.set(proposal.key, { settings: [], vibemates: [], ops: [], ids: {}, appearance: patch });
+        this.proposals.set(proposal.key, proposal);
+        this.push({ type: "proposal", proposal });
+        const what = rows.map((c) => c.key).join(", ");
+        this.postSystem(`${participant.name} proposes a change to how the window looks (${what}); apply or reject it on the card.`, "human", false, { tone: "attention" });
+        this.log.info(`look proposal ${proposal.key} from ${participant.name}: ${what}`);
+        return {
+            ok: true,
+            message: `Proposal sent to ${this.settings.humanName} as a card in the room (${what}). It changes the whole window, not this room alone; nothing changes until they apply it, and you will see a room line with the outcome.`,
+            key: proposal.key,
+            warnings: [],
+        };
+    }
     async resolveProposal(key, accept) {
         const proposal = this.proposals.get(key);
         const plan = this.proposalPlans.get(key);
@@ -1450,7 +1591,7 @@ export class Room extends EventEmitter {
             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(", ");
+        const what = [...proposal.settings.map((c) => c.key), ...proposal.vibemates.map((o) => `${o.op} ${o.name}`), ...(proposal.appearance ?? []).map((c) => c.key)].join(", ");
         if (!accept) {
             proposal.status = "rejected";
             this.proposalPlans.delete(key);
@@ -1505,6 +1646,16 @@ export class Room extends EventEmitter {
                 patch[c.key] = c.key === "language" ? c.to : c.to;
             this.updateSettings(patch);
         }
+        if (plan.appearance) {
+            try {
+                if (!this.skills?.appearance)
+                    throw new Error("looks are not available in this hub");
+                this.skills.appearance.apply(plan.appearance);
+            }
+            catch (error) {
+                skipped.push(`appearance (${error instanceof Error ? error.message : String(error)})`);
+            }
+        }
         proposal.status = "applied";
         proposal.skipped = skipped;
         this.proposalPlans.delete(key);
@@ -1697,10 +1848,9 @@ export class Room extends EventEmitter {
         if (!this.skills)
             return { ok: false, reason: "skills are not available in this hub" };
         const skill = this.skills.library.get(name);
-        const builtin = !!skill && skill.author === BUILTIN_AUTHOR && !skill.draft;
         const mine = this.attachedSkills(participant).filter((s) => s.agentInvocable).map((s) => s.name);
         const list = mine.length ? `your skills: ${mine.join(", ")}` : "you have no skills";
-        if (!builtin && (!this.hasSkill(participant, name) || !mine.some((s) => s.toLowerCase() === name.toLowerCase()))) {
+        if (!this.hasSkill(participant, name) || !mine.some((s) => s.toLowerCase() === name.toLowerCase())) {
             return { ok: false, reason: `"${name}" is not one of your skills (${list})` };
         }
         if (!skill || skill.problems.length)
@@ -2447,7 +2597,7 @@ export class Room extends EventEmitter {
             this.notice(`${participant.name}: agent process exited.`, "error");
         }
     }
-    async openSession(agent, cwd, log, mcpServers = []) {
+    async openSession(agent, cwd, log, mcpServers = [], recipe) {
         try {
             return await agent.newSession(cwd, mcpServers);
         }
@@ -2455,12 +2605,22 @@ export class Room extends EventEmitter {
             if (!isAuthRequired(error) || !agent.authMethods.length)
                 throw error;
             log.info(`session/new needs authentication: ${describeError(error)}`);
+            if (recipe?.loginState === "missing")
+                throw new Error(`authentication required; log in with the agent's own CLI first${recipe.loginCommand ? ` (${recipe.loginCommand})` : ""}`);
         }
         const failures = [];
         for (const method of agent.authMethods) {
+            if (method.type === "terminal") {
+                failures.push(`${method.id}: needs a terminal`);
+                continue;
+            }
             log.info(`authenticate with "${method.id}"${method.name ? ` (${method.name})` : ""}`);
             try {
-                await agent.authenticate(method.id);
+                const done = await Promise.race([agent.authenticate(method.id).then(() => true), delay(AUTH_WAIT_MS).then(() => false)]);
+                if (!done) {
+                    failures.push(`${method.id}: no answer in ${AUTH_WAIT_MS / 1000} s (a sign-in that needs you)`);
+                    continue;
+                }
                 return await agent.newSession(cwd, mcpServers);
             }
             catch (error) {
@@ -2537,7 +2697,7 @@ export class Room extends EventEmitter {
         participant.mode = pick("mode") ?? participant.mode;
     }
     failStart(participant, error, fresh, stderr = []) {
-        participant.statusDetail = error instanceof Error ? error.message : String(error);
+        participant.statusDetail = describeError(error);
         const recipe = getRecipe(participant.agentType ?? "");
         participant.trouble = classifyStartFailure({
             error: participant.statusDetail,
@@ -2696,7 +2856,11 @@ function isAuthRequired(error) {
     return error instanceof Error && /auth/i.test(error.message);
 }
 function describeError(error) {
-    return error instanceof Error ? error.message : String(error);
+    if (!(error instanceof Error))
+        return String(error);
+    const data = error.rpc?.data ?? error.data;
+    const detail = typeof data === "string" ? data : data && typeof data === "object" && typeof data.details === "string" ? data.details : "";
+    return detail && !error.message.includes(detail) ? `${error.message}: ${detail}` : error.message;
 }
 function looksSilent(text) {
     const t = text.trim().toLowerCase();