Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
feat(bots): give a bot a face in the web cockpit
Jean-Christophe Tournierb7e559d6d24c
diff --git a/BOTS-ARCHITECTURE.md b/BOTS-ARCHITECTURE.mdindex 81aa74f4..e949a013 100644--- a/BOTS-ARCHITECTURE.md+++ b/BOTS-ARCHITECTURE.md@@ -187,7 +187,7 @@ Inherited from Mercury's "always uses a solution" ethos, hardened:| Surface | How ||---|---|| **Real-time activity bus** | Every bot turn emits granular events (turn-start, step, tool start/finish, turn-end) via `BotManager.onBotActivity`. Consumed by: the open bot thread's live region (same spinner block as the main chat), the `/bots` roster `↳ activity` line and `fleet_status` (mirrored into the activity map), and the web SSE feed (`bot_activity` events — dashboards / third-party backends). |-| **Web cockpit** ("Mercury Bots" section) | Full fleet management in the dashboard (`ui/src/pages/Bots.tsx` + `ui/src/components/bots/`): live roster with fleet nesting (SSE `bot_activity` over `GET /api/bots/events`, 4s poll fallback), onboarding wizard with executable permission tiers, persona + permissions editors (single source of truth), per-bot panels (send/daily ops/DLQ replay), **deliverables inbox** (`bot_deliver` → `outputs/<botId>/` — fleet-wide list/preview/download/remove + live `Delivered` banner; exempt from the janitor, removed only by the owner), bundle export/import. Endpoints in `src/web/api/bots.ts` (output file routes containment-guarded like `deliver()`). |+| **Web cockpit** ("Mercury Bots" section) | Full fleet management in the dashboard (`ui/src/pages/Bots.tsx` + `ui/src/components/bots/`): live roster with fleet nesting (SSE `bot_activity` over `GET /api/bots/events`, 4s poll fallback), onboarding wizard with executable permission tiers, persona + permissions editors (single source of truth), a **face per bot** in the roster and in the panel header (`GET/PUT/DELETE /api/bots/:id/avatar`, monogram from the id when there is none — same letters and colour as the Android roster), per-bot panels (send/daily ops/DLQ replay), **deliverables inbox** (`bot_deliver` → `outputs/<botId>/` — fleet-wide list/preview/download/remove + live `Delivered` banner; exempt from the janitor, removed only by the owner), bundle export/import. Endpoints in `src/web/api/bots.ts` (output file routes containment-guarded like `deliver()`). || **TUI** | New `/bots` slash command (fast-path, like `/agents`) → interactive panel: list bots (live states), onboard (guided, fully automatic config generation), edit config/persona, view journal, enable/disable, send a message. Also a TUI page in `cli.ts` command layer. || **Local HTTP API** | Hono module `src/web/api/bots.ts`: `GET /api/bots`, `POST /api/bots` (onboard), `GET/PATCH/DELETE /api/bots/:id`, `POST /api/bots/:id/message` (enqueue; returns job id), `POST /api/bots/:id/enable|disable`, `GET /api/bots/:id/journal`, `POST /api/bots/:id/replay`. Auth: existing web auth + attach token. || **Mercury Cloud** | `agent.command` envelope gains `bot.*` command types (list, message, configure) — same pattern as existing `model.select`/`task.stop`; cross-instance bot↔bot via `agent.message.relay`. |diff --git a/ui/src/components/bots/BotDetail.tsx b/ui/src/components/bots/BotDetail.tsxindex ac0869e1..9da8046e 100644--- a/ui/src/components/bots/BotDetail.tsx+++ b/ui/src/components/bots/BotDetail.tsx@@ -1,7 +1,7 @@-import { useCallback, useEffect, useState } from "react";+import { useCallback, useEffect, useRef, useState } from "react";import {Bot, Send, Pause, Play, Square, RotateCw, AlertTriangle, Crown, Shield,- Download, Package, Clock, Save, RefreshCw, Users,+ Download, Package, Clock, Save, RefreshCw, Users, Camera, Trash2,} from "lucide-react";import { Badge } from "@/components/ui/badge";import { Button } from "@/components/ui/button";@@ -15,6 +15,7 @@ import {} from "@/components/ui/dialog";import { cn } from "@/lib/utils";import api, { type BotManifest, type BotStatus, type BotRunRecord, type BotDlqEntry, type BotTierInfo, type BotPermissionsFile } from "@/lib/api";+import { BotFace } from "./BotFace";import { DeliverablesList } from "./DeliverablesList";import type { BotEventState } from "./useBotEvents";@@ -57,6 +58,19 @@ export function BotDetail({const [crewName, setCrewName] = useState("");const [crewPersona, setCrewPersona] = useState("");const [crewTier, setCrewTier] = useState("inherit");+ // The face: bytes go up as base64 (the core sniffs them and refuses anything that is not+ // an image), and `avatarVersion` re-requests the image after a change — the browser would+ // otherwise keep the old bytes, the ETag on the route notwithstanding.+ const avatarInput = useRef<HTMLInputElement | null>(null);+ const [hasAvatar, setHasAvatar] = useState(Boolean(bot?.state?.hasAvatar));+ const [avatarVersion, setAvatarVersion] = useState(0);+ const [avatarBusy, setAvatarBusy] = useState(false);+ const [avatarError, setAvatarError] = useState<string | null>(null);++ useEffect(() => {+ setHasAvatar(Boolean(bot?.state?.hasAvatar));+ setAvatarError(null);+ }, [bot?.state?.hasAvatar, id]);const loadJournal = useCallback(async () => {if (!id) return;@@ -120,6 +134,49 @@ export function BotDetail({}).catch(() => setPersonaState("error"));};+ const pickAvatar = async (file: File | null) => {+ if (!id || !file) return;+ if (file.size > 2 * 1024 * 1024) {+ setAvatarError(`That photo is ${Math.round(file.size / 1048576)} MB; the limit is 2 MB.`);+ return;+ }+ setAvatarBusy(true);+ try {+ const data = await new Promise<string>((resolve, reject) => {+ const reader = new FileReader();+ reader.onload = () => resolve(String(reader.result));+ reader.onerror = () => reject(new Error("Could not read that file"));+ reader.readAsDataURL(file);+ });+ await api.bots.setAvatar(id, data);+ setHasAvatar(true);+ setAvatarVersion((v) => v + 1);+ setAvatarError(null);+ onChanged();+ } catch (e) {+ setAvatarError(e instanceof Error ? e.message : "Could not store that photo");+ } finally {+ setAvatarBusy(false);+ if (avatarInput.current) avatarInput.current.value = "";+ }+ };++ const removeAvatar = async () => {+ if (!id) return;+ setAvatarBusy(true);+ try {+ await api.bots.clearAvatar(id);+ setHasAvatar(false);+ setAvatarVersion((v) => v + 1);+ setAvatarError(null);+ onChanged();+ } catch {+ setAvatarError("Could not remove the photo");+ } finally {+ setAvatarBusy(false);+ }+ };+const applyTier = async (tier: string) => {await api.bots.setPermissions(id, { tier });await loadConfig();@@ -150,11 +207,36 @@ export function BotDetail({<DialogContent className="max-w-4xl max-h-[85vh] overflow-y-auto"><DialogHeader><DialogTitle className="flex items-center gap-2">- <Bot className="h-5 w-5" /> {m.name}+ <button+ type="button"+ onClick={() => avatarInput.current?.click()}+ disabled={avatarBusy}+ title={hasAvatar ? "Change this bot's photo" : "Give this bot a photo"}+ className="rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary disabled:opacity-60"+ >+ <BotFace id={id ?? ""} name={m.name} hasAvatar={hasAvatar} version={avatarVersion} size={32} />+ </button>+ {m.name}<span className="text-muted-foreground text-sm">({id})</span>{m.fleetRole === "lead" && <Badge variant="secondary" className="text-yellow-500"><Crown className="h-3 w-3" /> fleet lead</Badge>}{m.fleetRole === "crew" && <Badge variant="secondary">crew of {m.parent}</Badge>}+ <input+ ref={avatarInput}+ type="file"+ accept="image/png,image/jpeg,image/webp,image/gif"+ className="hidden"+ onChange={(e) => void pickAvatar(e.target.files?.[0] ?? null)}+ />+ <Button size="sm" variant="outline" disabled={avatarBusy} onClick={() => avatarInput.current?.click()}>+ <Camera className="h-3.5 w-3.5" /> {hasAvatar ? "Change photo" : "Add photo"}+ </Button>+ {hasAvatar && (+ <Button size="sm" variant="ghost" disabled={avatarBusy} onClick={() => void removeAvatar()}>+ <Trash2 className="h-3.5 w-3.5" /> Remove+ </Button>+ )}</DialogTitle>+ {avatarError && <p className="text-xs text-red-500">{avatarError}</p>}<DialogDescription className="flex flex-wrap items-center gap-2"><Badge variant="secondary">model: {m.model?.provider ?? "inherit"}{m.model?.model ? `:${m.model.model}` : ""}</Badge><Badge variant="secondary">memory: {m.memory?.scope ?? "own"}</Badge>diff --git a/ui/src/components/bots/BotFace.tsx b/ui/src/components/bots/BotFace.tsxnew file mode 100644index 00000000..ca9b9134--- /dev/null+++ b/ui/src/components/bots/BotFace.tsx@@ -0,0 +1,62 @@+import { useEffect, useState } from "react";+import { botFace } from "@/lib/botFace";+import { cn } from "@/lib/utils";++/**+ * A bot's face: the photo its owner gave it, or — until there is one — a monogram on a+ * colour derived from the id (the same letters and colour the Android roster draws).+ *+ * `hasAvatar` comes from the roster, so the dashboard asks for bytes only for bots that+ * have a face; `broken` covers the other direction (bytes on disk that are not an image),+ * where a monogram beats a broken-image icon. `version` is the caller's cache-buster: the+ * server revalidates every request with an ETag, but React will not re-request an `<img>`+ * whose `src` never changed, so a face replaced elsewhere would otherwise stay stale.+ */+export function BotFace({+ id,+ name,+ hasAvatar,+ version = 0,+ size = 32,+ className,+}: {+ id: string;+ name?: string | null;+ hasAvatar?: boolean;+ version?: number;+ size?: number;+ className?: string;+}) {+ const [broken, setBroken] = useState(false);++ // A new bot in the same slot (or a fresh id) gets a fresh chance to load its photo.+ useEffect(() => setBroken(false), [id, hasAvatar, version]);++ const box = { width: size, height: size };+ if (hasAvatar && !broken) {+ return (+ <img+ src={`/api/bots/${encodeURIComponent(id)}/avatar${version ? `?v=${version}` : ""}`}+ alt={`Photo of ${name || id}`}+ width={size}+ height={size}+ loading="eager"+ onError={() => setBroken(true)}+ className={cn("rounded-full object-cover shrink-0 ring-1 ring-border", className)}+ style={box}+ />+ );+ }++ const { monogram, background } = botFace(id, name);+ return (+ <span+ aria-hidden="true"+ title={name || id}+ className={cn("inline-flex items-center justify-center rounded-full shrink-0 select-none font-medium", className)}+ style={{ ...box, backgroundColor: background, color: "rgba(0, 0, 0, 0.75)", fontSize: Math.round(size * 0.38) }}+ >+ {monogram}+ </span>+ );+}diff --git a/ui/src/components/bots/useBotEvents.ts b/ui/src/components/bots/useBotEvents.tsindex 5054c846..cfc12860 100644--- a/ui/src/components/bots/useBotEvents.ts+++ b/ui/src/components/bots/useBotEvents.ts@@ -11,6 +11,12 @@ export interface BotEventState {activity: Record<string, string>;/** Newest delivered artifact — the deliverables inbox banners + refreshes live on this. */lastDelivery: { botId: string; name: string; at: number } | null;+ /**+ * Bumped on every `bot_roster` frame — the core re-broadcasts the roster when an avatar+ * changes, which is how a face set on the phone reaches an open dashboard. Used as the+ * cache-buster of each `<img>`; the periodic poll stays the fallback.+ */+ rosterSeq: number;connected: boolean;}@@ -18,6 +24,7 @@ export function useBotEvents(): BotEventState {const [state, setState] = useState<BotEventState>({activity: {},lastDelivery: null,+ rosterSeq: 0,connected: false,});const esRef = useRef<EventSource | null>(null);@@ -59,6 +66,10 @@ export function useBotEvents(): BotEventState {} catch {}});+ es.addEventListener("bot_roster", () => {+ setState((prev) => ({ ...prev, rosterSeq: prev.rosterSeq + 1 }));+ });+es.onopen = () => setState((p) => ({ ...p, connected: true }));es.onerror = () => setState((p) => ({ ...p, connected: false }));diff --git a/ui/src/lib/api.ts b/ui/src/lib/api.tsindex d78e0d3d..34d83db6 100644--- a/ui/src/lib/api.ts+++ b/ui/src/lib/api.ts@@ -815,6 +815,8 @@ export interface BotStatus {fleetRole?: "lead" | "crew";parent?: string;crewWorking?: number;+ /** A custom face exists (`GET /api/bots/:id/avatar`); draw a monogram otherwise. */+ hasAvatar?: boolean;}export interface BotManifest {@@ -1081,6 +1083,10 @@ const api = {message: (id: string, message: string) =>post<{ accepted: boolean; jobId?: string; reasonCode?: string }>(`/api/bots/${id}/message`, { message }),patch: (id: string, body: Partial<BotManifest>) => patch<unknown>(`/api/bots/${id}`, body),+ /** The bot's face: base64 or a `data:` URL, 2 MB at most — the core sniffs the bytes, never the name. */+ setAvatar: (id: string, data: string) =>+ put<{ ok: boolean; mime: string; bytes: number }>(`/api/bots/${id}/avatar`, { data }),+ clearAvatar: (id: string) => del<{ ok: boolean; removed: boolean }>(`/api/bots/${id}/avatar`),enable: (id: string) => post<{ ok: boolean }>(`/api/bots/${id}/enable`),disable: (id: string) => post<{ ok: boolean }>(`/api/bots/${id}/disable`),stop: (id: string) => post<{ ok: boolean }>(`/api/bots/${id}/stop`),diff --git a/ui/src/lib/botFace.test.ts b/ui/src/lib/botFace.test.tsnew file mode 100644index 00000000..b414b054--- /dev/null+++ b/ui/src/lib/botFace.test.ts@@ -0,0 +1,89 @@+import { describe, expect, it } from 'vitest';+import { botFace, botFaceColor, botHue, botMonogram } from './botFace.js';++/**+ * The rules the phone already draws with (`BotJson.monogram`, `BotJson.hue`, `BotFace` in+ * `BotsScreen.kt`). Pinned here so the dashboard and the app cannot drift into showing the+ * same bot as "RL" on one and "RE" on the other.+ */+describe('botMonogram', () => {+ it('takes the initials of a two-word name', () => {+ expect(botMonogram('Research Lead', 'x')).toBe('RL');+ });++ it('takes the first two characters of a single-word name', () => {+ expect(botMonogram('Solo', 'solo-1')).toBe('SO');+ });++ it('falls back to the id when the name is blank, then splits it the same way', () => {+ expect(botMonogram('', 'gamma-7')).toBe('G7');+ expect(botMonogram(' ', 'ledger')).toBe('LE');+ });++ it('ignores empty segments, so a leading separator does not eat a letter', () => {+ expect(botMonogram(' lead-ops', 'x')).toBe('LO');+ });++ it('answers a single character when that is all there is', () => {+ expect(botMonogram('A', 'x')).toBe('A');+ });++ it('answers ? when there is neither name nor id', () => {+ expect(botMonogram('', '')).toBe('?');+ });+});++describe('botHue', () => {+ it('is stable for the same id', () => {+ expect(botHue('alpha')).toBe(botHue('alpha'));+ });++ it('matches the phone: 32-bit wrapping hash of the id, modulo 360', () => {+ // 97, 108, 112, 104, 97 folded with `hash * 31 + c` and masked to 31 bits.+ expect(botHue('alpha')).toBe(38);+ });++ it('stays in 0…359 for ids of every shape', () => {+ for (const id of ['a', 'alpha', 'gamma-7', 'bot_with_underscores', 'Ünïcode-id', '0', 'x'.repeat(200)]) {+ const hue = botHue(id);+ expect(hue).toBeGreaterThanOrEqual(0);+ expect(hue).toBeLessThan(360);+ expect(Number.isInteger(hue)).toBe(true);+ }+ });++ it('uses the name when there is no id, and a neutral blue when there is neither', () => {+ expect(botHue('', 'Research Lead')).toBe(botHue('Research Lead'));+ expect(botHue('', '')).toBe(210);+ expect(botHue(' ', ' ')).toBe(210);+ });+});++describe('botFaceColor', () => {+ it('is hsv(h, 45%, 75%) as rgb: full value on the dominant channel, 105 on the floor', () => {+ expect(botFaceColor(0)).toBe('rgb(191, 105, 105)');+ expect(botFaceColor(120)).toBe('rgb(105, 191, 105)');+ expect(botFaceColor(240)).toBe('rgb(105, 105, 191)');+ });++ it('keeps the same lightness for every hue, so no bot is illegible next to another', () => {+ for (let hue = 0; hue < 360; hue += 15) {+ const [r, g, b] = botFaceColor(hue).match(/\d+/g)!.map(Number);+ expect(Math.max(r, g, b)).toBe(191);+ expect(Math.min(r, g, b)).toBe(105);+ }+ });++ it('wraps out-of-range hues instead of rendering nothing', () => {+ expect(botFaceColor(360)).toBe(botFaceColor(0));+ expect(botFaceColor(-120)).toBe(botFaceColor(240));+ });+});++describe('botFace', () => {+ it('gives the letters and the background from one id in one call', () => {+ const face = botFace('alpha', 'Alpha');+ expect(face.monogram).toBe('AL');+ expect(face.background).toBe(botFaceColor(38));+ });+});diff --git a/ui/src/lib/botFace.ts b/ui/src/lib/botFace.tsnew file mode 100644index 00000000..e60e1c0a--- /dev/null+++ b/ui/src/lib/botFace.ts@@ -0,0 +1,59 @@+/**+ * The face of a bot, when there is no photo: a monogram on a colour derived from the id.+ *+ * These three rules are the ones the Android client already draws (`BotJson.monogram`,+ * `BotJson.hue` and `BotFace` in `BotsScreen.kt`), copied rather than reinvented so the+ * same bot looks the same on the phone and in the dashboard — same letters, same colour,+ * same lightness. Change one and change the other.+ */++/** Letters a bot shows when it has no photo: initials for a multi-word name, else its first two characters. */+export function botMonogram(name: string | null | undefined, id: string): string {+ const source = (name ?? "").trim() || id.trim();+ const words = source.split(/[ _-]+/).filter(Boolean);+ if (words.length >= 2) return (words[0][0] + words[1][0]).toUpperCase();+ if (source.length > 0) return source.slice(0, 2).toUpperCase();+ return "?";+}++/** Stable hue (0–359) derived from the id, so a bot keeps its colour across sessions. */+export function botHue(id: string, name?: string | null): number {+ const source = id.trim() || (name ?? "").trim();+ if (source.length === 0) return 210;+ let hash = 0;+ // Code units, not code points: `hash * 31 + char.code` and the `&` that follows are the+ // Kotlin side's 32-bit arithmetic, and JS `&` is ToInt32 — identical wrapping, identical hue.+ for (let i = 0; i < source.length; i++) hash = (hash * 31 + source.charCodeAt(i)) & 0x7fffffff;+ return hash % 360;+}++function clamp01(n: number): number {+ return Math.min(1, Math.max(0, n));+}++/**+ * `hsv(h, 45%, 75%)` as an `rgb(…)` string — CSS has no HSV, and converting here keeps the+ * colour equal to the phone's instead of merely close.+ */+export function botFaceColor(hue: number): string {+ const h = ((hue % 360) + 360) % 360;+ const s = clamp01(0.45);+ const v = clamp01(0.75);+ const c = v * s;+ const x = c * (1 - Math.abs(((h / 60) % 2) - 1));+ const m = v - c;+ const [r1, g1, b1] =+ h < 60 ? [c, x, 0] :+ h < 120 ? [x, c, 0] :+ h < 180 ? [0, c, x] :+ h < 240 ? [0, x, c] :+ h < 300 ? [x, 0, c] :+ [c, 0, x];+ const to255 = (n: number) => Math.round((n + m) * 255);+ return `rgb(${to255(r1)}, ${to255(g1)}, ${to255(b1)})`;+}++/** Everything a client needs to draw a bot without a photo. */+export function botFace(id: string, name?: string | null): { monogram: string; background: string } {+ return { monogram: botMonogram(name, id), background: botFaceColor(botHue(id, name)) };+}diff --git a/ui/src/pages/Bots.tsx b/ui/src/pages/Bots.tsxindex 13f76a3b..c4924332 100644--- a/ui/src/pages/Bots.tsx+++ b/ui/src/pages/Bots.tsx@@ -8,6 +8,7 @@ import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs";import { cn, formatDate } from "@/lib/utils";import api, { type BotStatus, type BotRunRecord, type BotDlqEntry, type BotManifest } from "@/lib/api";import { useBotEvents } from "@/components/bots/useBotEvents";+import { BotFace } from "@/components/bots/BotFace";import { BotDetail } from "@/components/bots/BotDetail";import { OnboardWizard } from "@/components/bots/OnboardWizard";import { DeliverablesList } from "@/components/bots/DeliverablesList";@@ -102,7 +103,7 @@ export function BotsPage() {<CardHeader className="pb-2" onClick={() => void openBot(bot.id)}><div className="flex items-center justify-between"><CardTitle className="flex items-center gap-2 text-base">- <Bot className="h-4 w-4" /> {bot.name}+ <BotFace id={bot.id} name={bot.name} hasAvatar={bot.hasAvatar} version={live.rosterSeq} size={28} /> {bot.name}{bot.fleetRole === "lead" && <Badge variant="secondary" className="text-yellow-500"><Crown className="h-3 w-3" /> lead</Badge>}{crewCount > 0 && <Badge variant="secondary"><Users className="h-3 w-3" /> {crewCount}</Badge>}</CardTitle>@@ -124,7 +125,7 @@ export function BotsPage() {const cl = live.activity[c.id];return (<span key={c.id} className="inline-flex items-center gap-1 mr-2">- ↳ {c.name}+ <BotFace id={c.id} name={c.name} hasAvatar={c.hasAvatar} version={live.rosterSeq} size={18} /> {c.name}{cl && <span className="text-emerald-400"> {cl.slice(0, 30)}</span>}{c.needsYou && <AlertTriangle className="h-3 w-3 text-yellow-500" />}</span>