Skip to content

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.md
index 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.tsx
index 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.tsx
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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>