@a-t-h-i/bot-lobby 0.1.0

package/src/pi/mascot-art.ts

@@ -0,0 +1,252 @@
+import type { TaskState } from "../schemas/task.ts";
+
+/**
+ * Pure ASCII art data for the scene-based zen panel. No logic lives here: the
+ * captions, status vocabulary, frame sets and tower templates are constants
+ * that `zen.ts` and `zen-large.ts` compose. Every glyph is exactly one visible
+ * column so the art stays narrow/ambiguous-width safe: the non-ASCII glyphs are
+ * the lobby `⌂` in `BANNER_NARROW`, the panel's ◐/✓/✗ status family, and the
+ * box-drawing, bar and eye glyphs of the large scene (─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ═ █ ▓ ░ ◉ ◍ ◎ ◌ ○).
+ */
+
+/**
+ * One-column status glyphs, matching the glyph family the panel already uses
+ * for runs and steps (◐ running, ✓ success, ✗ failure); the slot roster below
+ * reuses them so a status never rests on colour alone.
+ */
+const STATUS_GLYPHS = { idle: "·", running: "◐", done: "✓", failed: "✗" } as const;
+
+/** Braille spinner frames shared by the large scene and the compact working line. */
+export const SPIN_FRAMES: readonly string[] = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export const BANNER_TITLE = "THE BOT LOBBY";
+export const BANNER_NARROW = "⌂ THE BOT LOBBY";
+
+/** One-line (<= 30 chars) caption per task state, labelling the compact strip. */
+export const SCENE_PROPS: Record<TaskState, string> = {
+  created: "no work started yet",
+  clarifying: "clarifying the request",
+  scouting: "scouting the codebase",
+  synthesizing: "synthesizing findings",
+  awaiting_approval: "awaiting your approval",
+  planning: "writing the plan",
+  implementing: "agents at work",
+  reviewing: "reviewing the diff",
+  blocked: "blocked, needs a hand",
+  completed: "work complete",
+  abandoned: "task set aside",
+};
+
+
+/* -------------------------------------------------------------------------
+ * Slot roster and animated art for the zen scene (composed by zen-large.ts at
+ * >= LARGE_MIN_WIDTH and by zen.ts's compact strip below it).
+ * ---------------------------------------------------------------------- */
+
+/** The four agent columns of the large scene, in the order the scene draws them. */
+export type SlotId = "dev" | "design" | "research" | "qa";
+
+export const SLOT_IDS: readonly SlotId[] = ["dev", "design", "research", "qa"];
+
+/** Uppercase column captions; RESEARCH is the longest at 8 columns. */
+export const SLOT_LABELS: Record<SlotId, string> = {
+  dev: "DEV",
+  design: "DESIGN",
+  research: "RESEARCH",
+  qa: "QA",
+};
+
+/** Status the roster reports; drives the face, the colour and the state word. */
+export type SlotState = "working" | "idle" | "done" | "failed";
+
+export const SLOT_STATES: readonly SlotState[] = ["working", "idle", "done", "failed"];
+
+export const SLOT_STATE_WORDS: Record<SlotState, string> = {
+  working: "working",
+  idle: "idle",
+  done: "done",
+  failed: "failed",
+};
+
+/** One-column status glyph sitting beside the state word, so status never rests on colour alone. */
+export const SLOT_STATE_GLYPHS: Record<SlotState, string> = {
+  working: STATUS_GLYPHS.running,
+  idle: STATUS_GLYPHS.idle,
+  done: STATUS_GLYPHS.done,
+  failed: STATUS_GLYPHS.failed,
+};
+
+/** The slice of a panel theme's colour vocabulary this art maps onto. */
+export type PanelColor = "accent" | "muted" | "dim" | "success" | "error" | "warning";
+
+/** Status -> colour for the face, state word and bar fill. Working is bold as well. */
+export const SLOT_STATE_COLORS: Record<SlotState, { color: PanelColor; bold: boolean }> = {
+  working: { color: "accent", bold: true },
+  idle: { color: "dim", bold: false },
+  done: { color: "success", bold: false },
+  failed: { color: "error", bold: false },
+};
+
+/** Ten-cell progress bar; the caller fills `cells` of it from a percentage. */
+export const BAR = { filled: "█", empty: "░", cells: 10 } as const;
+
+/** The master's pose: orchestrating while the task is live, dormant when paused or finished. */
+export type OraclePose = "orchestrating" | "dormant";
+
+export const ORACLE_POSES: readonly OraclePose[] = ["orchestrating", "dormant"];
+
+export const ORACLE_WORDS: Record<OraclePose, string> = {
+  orchestrating: "orchestrating",
+  dormant: "dormant",
+};
+
+export const ORACLE_COLORS: Record<OraclePose, { color: PanelColor; bold: boolean }> = {
+  orchestrating: { color: "accent", bold: true },
+  dormant: { color: "dim", bold: false },
+};
+
+/** One oracle frame: the tower orb, both window eyes and the seven-column mouth. */
+export interface OracleFrame {
+  orb: string;
+  winL: string;
+  winR: string;
+  /** Exactly seven one-column glyphs; never moves the tower geometry. */
+  mouth: string;
+}
+
+/**
+ * Indexed oracle expressions per pose: 0 rests, 1 blinks and 2-3 emote with a
+ * pulsing orb, sweeping window eyes and a moving mouth. Every glyph is one
+ * column and every mouth seven, so a frame swap never moves the tower geometry.
+ */
+export const ORACLE_FRAMES: Record<OraclePose, readonly OracleFrame[]> = {
+  orchestrating: [
+    { orb: "◉", winL: "◉", winR: "◉", mouth: "═══════" },
+    { orb: "◉", winL: "─", winR: "─", mouth: "═══════" },
+    { orb: "◎", winL: "◍", winR: "◉", mouth: "◡◡◡◡◡◡◡" },
+    { orb: "◍", winL: "◉", winR: "◍", mouth: "▁▂▃▂▃▂▁" },
+  ],
+  dormant: [
+    { orb: "◌", winL: "◌", winR: "◌", mouth: "═══════" },
+    { orb: "◌", winL: "─", winR: "─", mouth: "═══════" },
+    { orb: "○", winL: "◌", winR: "◌", mouth: "▂▂▂▂▂▂▂" },
+    { orb: "○", winL: "─", winR: "─", mouth: "▁▁▁▁▁▁▁" },
+  ],
+};
+
+/**
+ * One frame per status and expression: index 0 is the calm rest face, 1 the
+ * blink and 2-3 the emotes. Every status keeps the same frame count and one row
+ * each, so a caller-chosen index stays comparable across statuses.
+ */
+const FACE_FRAMES: Record<SlotState, readonly string[]> = {
+  working: ["(^_^)", "(-_-)", "(^o^)", "(^-^)"],
+  idle: ["(-_-)", "(u_u)", "(-.-)", "(u.u)"],
+  done: ["(o_o)", "(-_-)", "(^-^)", "(^_^)"],
+  failed: ["(>_<)", "(x_x)", "(T_T)", "(;_;)"],
+};
+
+/** Kaomoji emotes for the large scene: working nervous, done happy, failed scared. */
+const EMOTE_FACES: Record<SlotState, readonly string[]> = {
+  working: ["(٥↼_↼)", "(●´⌓`●)"],
+  idle: ["(-.-)", "(u.u)"],
+  done: ["(✿^‿^)", "(っ˘з(˘⌣˘ )"],
+  failed: ["ಥ_ಥ", "(〒﹏〒)"],
+};
+
+/** QA's success emotes are a flex and a victory dance rather than a smile. */
+const QA_DONE_FACES: readonly string[] = ["ᕙ( • ‿ • )ᕗ", "ᕕ( ᐛ )ᕗ"];
+
+/** Every compact face is five columns, so a centered column never shifts between frames. */
+export const FACE_WIDTH = 5;
+
+function buildSlotFrames(id: SlotId): Record<SlotState, readonly string[][]> {
+  const frames = {} as Record<SlotState, readonly string[][]>;
+  for (const state of SLOT_STATES) {
+    const emotes = id === "qa" && state === "done" ? QA_DONE_FACES : EMOTE_FACES[state];
+    frames[state] = [...FACE_FRAMES[state].slice(0, 2), ...emotes].map((face) => [face]);
+  }
+  return frames;
+}
+
+/**
+ * Animated faces per slot: one row each. Rest (0) and blink (1) stay the five-column
+ * ASCII eyes; the emote frames (2+) are status-aware kaomoji, wider than five columns,
+ * so the scene centres each frame inside its fixed slot cell.
+ */
+export const SLOT_FRAMES: Record<SlotId, Record<SlotState, readonly string[][]>> = {
+  dev: buildSlotFrames("dev"),
+  design: buildSlotFrames("design"),
+  research: buildSlotFrames("research"),
+  qa: buildSlotFrames("qa"),
+};
+
+/** Three-column accessory that marks each slot in the one-row compact strip. */
+const SLOT_MARKS: Record<SlotId, string> = {
+  dev: "[=]",
+  design: "~,~",
+  research: "<?>",
+  qa: "<o>",
+};
+
+/** Eight columns: the slot's accessory followed by one face frame. */
+export const COMPACT_WIDTH = 8;
+
+function buildCompactFrames(id: SlotId): Record<SlotState, readonly string[]> {
+  const mark = SLOT_MARKS[id];
+  const frames = {} as Record<SlotState, readonly string[]>;
+  for (const state of SLOT_STATES) frames[state] = FACE_FRAMES[state].map((face) => `${mark}${face}`);
+  return frames;
+}
+
+/** Animated one-row sprites per slot and status for the compact strip. */
+export const COMPACT_FRAMES: Record<SlotId, Record<SlotState, readonly string[]>> = {
+  dev: buildCompactFrames("dev"),
+  design: buildCompactFrames("design"),
+  research: buildCompactFrames("research"),
+  qa: buildCompactFrames("qa"),
+};
+
+/**
+ * The oracle tower: 13 columns wide, `rows` while height allows and `smallRows`
+ * when it must shrink. `{orb}` is the pulsing bead, `{winL}`/`{winR}` the two
+ * window eyes and `{door}` the name over the door.
+ */
+export interface TowerSpec {
+  rows: readonly string[];
+  smallRows: readonly string[];
+  tokens: { orb: string; winL: string; winR: string; door: string; mouth: string };
+}
+
+export const TOWER_WIDTH = 13;
+
+export const TOWER_DOOR = "ORC";
+
+export const TOWER: TowerSpec = {
+  rows: [
+    "    \\ | /    ",
+    "     \\|/     ",
+    "     ─{orb}─     ",
+    "      │      ",
+    "┌─────┴─────┐",
+    "│▓▓▓▓▓▓▓▓▓▓▓│",
+    "├───────────┤",
+    "│ ┌─┐   ┌─┐ │",
+    "│ │{winL}│   │{winR}│ │",
+    "│ └─┘   └─┘ │",
+    "├───────────┤",
+    "│  {mouth}  │",
+    "├───┬───┬───┤",
+    "│▓▓▓│{door}│▓▓▓│",
+    "└───┴───┴───┘",
+  ],
+  smallRows: [
+    "     ─{orb}─     ",
+    "┌─────┴─────┐",
+    "│ ┌─┐   ┌─┐ │",
+    "│ │{winL}│   │{winR}│ │",
+    "│▓▓▓│{door}│▓▓▓│",
+    "└───┴───┴───┘",
+  ],
+  tokens: { orb: "{orb}", winL: "{winL}", winR: "{winR}", door: "{door}", mouth: "{mouth}" },
+};

package/src/pi/notify.ts

@@ -0,0 +1,42 @@
+import type { TaskState } from "../schemas/task.ts";
+import { isSubagentProcess } from "./quiet.ts";
+
+/** States worth an attention ping; every other transition stays silent. */
+const PING_LABELS: Partial<Record<TaskState, string>> = {
+  completed: "done",
+  blocked: "blocked",
+  awaiting_approval: "needs approval",
+};
+
+/** Strip control characters so a title can never break out of the OSC payload. */
+function sanitize(text: string): string {
+  return text.replace(/[\x00-\x1f\x7f]/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function notice(text: string): string {
+  return `\x07\x1b]9;${sanitize(text)}\x07`;
+}
+
+/** Terminal payload for one attention ping, or undefined when the state is not ping-worthy. Pure. */
+export function formatNotice(state: TaskState, title: string): string | undefined {
+  const label = PING_LABELS[state];
+  return label ? notice(`${title || "task"} ${label}`) : undefined;
+}
+
+/** Terminal payload for a worker-requested dependency or architecture approval. Pure. */
+export function formatApprovalNotice(domain: string, detail: string): string {
+  return notice(`${domain} approval needed: ${detail}`);
+}
+
+/** Emit a ping outside the TUI frame; never from a subagent process. */
+export function ping(state: TaskState, title: string): void {
+  if (isSubagentProcess()) return;
+  const payload = formatNotice(state, title);
+  if (payload) process.stderr.write(payload);
+}
+
+/** Emit one ping when an approval is first recorded; never from a subagent. */
+export function pingApproval(domain: string, detail: string): void {
+  if (isSubagentProcess()) return;
+  process.stderr.write(formatApprovalNotice(domain, detail));
+}

package/src/pi/quiet.ts

@@ -0,0 +1,46 @@
+/**
+ * Quiet mode for the master transcript: built-in tool rows render zero lines
+ * by default and `alt+t` reveals a compact one-line summary per call. The web
+ * tools are removed from the master's active set so the researcher subagent,
+ * running in its own process, stays the only web path.
+ *
+ * bot-lobby's extension also loads inside the subagent processes it spawns
+ * (see `spawnPiProcess`). Those children receive their tools from an explicit
+ * `--tools` allowlist, so the master-only filtering and renderer overrides must
+ * never run there or research silently degrades to repository-only.
+ */
+
+/** Web tools owned by pi-web-access; the researcher gets them, the master does not. */
+export const WEB_TOOL_NAMES: readonly string[] = [
+  "web_search",
+  "fetch_content",
+  "source_check",
+  "get_search_content",
+];
+
+let quiet = true;
+
+/** True while built-in tool rows consume no transcript lines. */
+export function isQuiet(): boolean {
+  return quiet;
+}
+
+export function setQuiet(value: boolean): void {
+  quiet = value;
+}
+
+/** Flip quiet mode and return the new value. */
+export function toggleQuiet(): boolean {
+  quiet = !quiet;
+  return quiet;
+}
+
+/** Drop the web tools from an active set, preserving every other name. */
+export function visibleTools(active: string[]): string[] {
+  return active.filter((name) => !WEB_TOOL_NAMES.includes(name));
+}
+
+/** True inside a bot-lobby subagent process (marked in `spawnPiProcess`). */
+export function isSubagentProcess(): boolean {
+  return process.env.BOT_LOBBY_SUBAGENT === "1";
+}

package/src/pi/settings-ui.ts

@@ -0,0 +1,258 @@
+import {
+  DynamicBorder,
+  getSelectListTheme,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type Theme,
+} from "@earendil-works/pi-coding-agent";
+import { Container, type Component, type Focusable, fuzzyFilter, getKeybindings, Input, type SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
+import { AGENT_KINDS, type AgentKind } from "../schemas/agent.ts";
+import {
+  INHERIT_MODEL,
+  INHERIT_THINKING,
+  isThinkingLevel,
+  THINKING_LEVELS,
+  type AgentModelConfig,
+  type BotLobbyConfig,
+} from "../schemas/configuration.ts";
+import { globalConfigPath, loadConfig, saveConfig } from "../state/project.ts";
+
+const CUSTOM_MODEL = "__custom__";
+const MAX_VISIBLE = 12;
+
+function agentLabel(agent: AgentKind): string {
+  return agent === "master" ? "Master" : `${agent[0]!.toUpperCase()}${agent.slice(1)}`;
+}
+
+function agentConfig(config: BotLobbyConfig, agent: AgentKind): AgentModelConfig {
+  return agent === "master" ? config.master : config.agents[agent];
+}
+
+function updateAgent(agent: AgentKind, patch: Partial<AgentModelConfig>): void {
+  const config = loadConfig();
+  if (agent === "master") config.master = { ...config.master, ...patch };
+  else config.agents[agent] = { ...config.agents[agent], ...patch };
+  saveConfig(config);
+}
+
+/** Find a `provider/id` (or bare id) among the models this session can use. */
+function findModel(ctx: ExtensionContext, ref: string) {
+  const slash = ref.indexOf("/");
+  if (slash > 0) return ctx.modelRegistry.find(ref.slice(0, slash), ref.slice(slash + 1));
+  return ctx.modelRegistry.getAvailable().find((model) => model.id === ref);
+}
+
+/** Apply the master model/thinking to the live session; "inherit" leaves it alone. */
+export async function applyMasterModel(pi: ExtensionAPI, ctx: ExtensionContext, config: BotLobbyConfig): Promise<void> {
+  const { model, thinking } = config.master;
+  if (model !== INHERIT_MODEL) {
+    const found = findModel(ctx, model);
+    if (!found) ctx.ui.notify(`bot-lobby: unknown master model "${model}".`, "warning");
+    else if (!(await pi.setModel(found))) ctx.ui.notify(`bot-lobby: no auth for ${model}.`, "warning");
+  }
+  if (isThinkingLevel(thinking)) pi.setThinkingLevel(thinking);
+}
+
+function hintText(search: boolean): string {
+  const nav = "↑↓ navigate • enter select • esc back";
+  return search ? `type to search • ${nav}` : nav;
+}
+
+function frame(theme: Theme, title: string, body: Component, search = false): Component {
+  const container = new Container();
+  container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+  container.addChild(new Text(theme.fg("accent", theme.bold(title)), 1, 0));
+  container.addChild(body);
+  container.addChild(new Text(theme.fg("dim", hintText(search)), 1, 0));
+  container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+  return container;
+}
+
+/** Fuzzy-filter picker items over label, value and description; blank queries pass through. */
+export function filterItems(items: SelectItem[], query: string): SelectItem[] {
+  if (query.trim() === "") return items;
+  return fuzzyFilter(items, query, (item) => `${item.label} ${item.value} ${item.description ?? ""}`);
+}
+
+function listFor(items: SelectItem[], done: (value: string | undefined) => void): SelectList {
+  const list = new SelectList(items, Math.min(items.length, MAX_VISIBLE), getSelectListTheme());
+  list.onSelect = (item) => done(item.value);
+  list.onCancel = () => done(undefined);
+  return list;
+}
+
+function isListKey(data: string): boolean {
+  const kb = getKeybindings();
+  return kb.matches(data, "tui.select.up") || kb.matches(data, "tui.select.down")
+    || kb.matches(data, "tui.select.confirm") || kb.matches(data, "tui.select.cancel");
+}
+
+/** Searchable picker: typing rebuilds the list, while arrows/enter/esc still drive it. */
+export class SearchPicker implements Component, Focusable {
+  private readonly body = new Container();
+  private readonly input = new Input({ placeholder: "search" });
+  private readonly frame: Component;
+  private readonly items: SelectItem[];
+  private readonly done: (value: string | undefined) => void;
+  private readonly requestRender: () => void;
+  private list: SelectList;
+  private query = "";
+
+  constructor(title: string, items: SelectItem[], theme: Theme, done: (value: string | undefined) => void, requestRender: () => void) {
+    this.items = items;
+    this.done = done;
+    this.requestRender = requestRender;
+    this.list = listFor(items, done);
+    this.body.addChild(this.input);
+    this.body.addChild(this.list);
+    this.frame = frame(theme, title, this.body, true);
+  }
+
+  get focused(): boolean {
+    return this.input.focused;
+  }
+
+  set focused(value: boolean) {
+    this.input.focused = value;
+  }
+
+  private refine(): void {
+    const query = this.input.getValue();
+    if (query === this.query) return;
+    this.query = query;
+    const next = filterItems(this.items, query);
+    this.body.removeChild(this.list);
+    this.list = listFor(next, this.done);
+    this.body.addChild(this.list);
+  }
+
+  handleInput(data: string): void {
+    if (isListKey(data)) this.list.handleInput(data);
+    else {
+      this.input.handleInput(data);
+      this.refine();
+    }
+    this.requestRender();
+  }
+
+  render(width: number): string[] {
+    return this.frame.render(width);
+  }
+
+  invalidate(): void {
+    this.frame.invalidate();
+  }
+}
+
+async function pickPlain(ctx: ExtensionContext, title: string, items: SelectItem[]): Promise<string | undefined> {
+  return ctx.ui.custom<string | undefined>((tui, theme, _keys, done) => {
+    const list = listFor(items, done);
+    const container = frame(theme, title, list);
+    return {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        list.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+}
+
+async function pickSearch(ctx: ExtensionContext, title: string, items: SelectItem[]): Promise<string | undefined> {
+  return ctx.ui.custom<string | undefined>((tui, theme, _keys, done) => {
+    return new SearchPicker(title, items, theme, done, () => tui.requestRender());
+  });
+}
+
+interface PickOptions {
+  search?: boolean;
+}
+
+async function pick(ctx: ExtensionContext, title: string, items: SelectItem[], options: PickOptions = {}): Promise<string | undefined> {
+  return options.search ? pickSearch(ctx, title, items) : pickPlain(ctx, title, items);
+}
+
+export function modelItems(ctx: ExtensionContext, current: string): SelectItem[] {
+  const inherit = current === INHERIT_MODEL ? `${INHERIT_MODEL} ✓` : INHERIT_MODEL;
+  const items: SelectItem[] = [{ value: INHERIT_MODEL, label: inherit, description: "Use the session's current model" }];
+  const usable = ctx.scopedModels.length > 0 ? ctx.scopedModels.map((entry) => entry.model) : ctx.modelRegistry.getAvailable();
+  for (const model of usable) {
+    const value = `${model.provider}/${model.id}`;
+    const label = value === current ? `${value} ✓` : value;
+    const description = model.name && model.name !== value ? model.name : undefined;
+    items.push(description ? { value, label, description } : { value, label });
+  }
+  items.push({ value: CUSTOM_MODEL, label: "custom…", description: "Type a provider/model id" });
+  return items;
+}
+
+async function commit(pi: ExtensionAPI, ctx: ExtensionContext, agent: AgentKind, patch: Partial<AgentModelConfig>, detail: string): Promise<void> {
+  updateAgent(agent, patch);
+  if (agent === "master") await applyMasterModel(pi, ctx, loadConfig());
+  ctx.ui.notify(`bot-lobby: ${agent} ${detail} — saved to ${globalConfigPath()}`, "info");
+}
+
+async function editModel(pi: ExtensionAPI, ctx: ExtensionContext, agent: AgentKind): Promise<void> {
+  const current = agentConfig(loadConfig(), agent).model;
+  const choice = await pick(ctx, `Model — ${agentLabel(agent)}`, modelItems(ctx, current), { search: true });
+  if (choice === undefined) return;
+  const typed = choice === CUSTOM_MODEL ? (await ctx.ui.input("Model id", "provider/model"))?.trim() : choice;
+  if (!typed) return;
+  await commit(pi, ctx, agent, { model: typed }, `model → ${typed}`);
+}
+
+async function editThinking(pi: ExtensionAPI, ctx: ExtensionContext, agent: AgentKind): Promise<void> {
+  const current = agentConfig(loadConfig(), agent).thinking;
+  const items: SelectItem[] = [
+    { value: INHERIT_THINKING, label: `${INHERIT_THINKING} (live session level)`, description: "Use the thinking level of the current session" },
+    ...THINKING_LEVELS.map((level) => ({ value: level, label: level })),
+  ].map((item) => (item.value === current ? { ...item, label: `${item.label} ✓` } : item));
+  const level = await pick(ctx, `Thinking — ${agentLabel(agent)}`, items);
+  if (!level) return;
+  await commit(pi, ctx, agent, { thinking: level }, `thinking → ${level}`);
+}
+
+async function editInstructions(pi: ExtensionAPI, ctx: ExtensionContext, agent: AgentKind): Promise<void> {
+  const current = agentConfig(loadConfig(), agent).instructions ?? "";
+  const text = await ctx.ui.editor(`Instructions — ${agentLabel(agent)}`, current);
+  if (text === undefined) return;
+  await commit(pi, ctx, agent, { instructions: text.trim() }, "instructions saved");
+}
+
+async function editAgent(pi: ExtensionAPI, ctx: ExtensionContext, agent: AgentKind): Promise<void> {
+  for (;;) {
+    const cfg = agentConfig(loadConfig(), agent);
+    const items: SelectItem[] = [
+      { value: "model", label: "Model", description: cfg.model },
+      { value: "thinking", label: "Thinking", description: cfg.thinking },
+      { value: "instructions", label: "Instructions", description: cfg.instructions ? `${cfg.instructions.length} chars` : "(none)" },
+      { value: "back", label: "Back" },
+    ];
+    const action = await pick(ctx, `${agentLabel(agent)} settings`, items);
+    if (!action || action === "back") return;
+    if (action === "model") await editModel(pi, ctx, agent);
+    else if (action === "thinking") await editThinking(pi, ctx, agent);
+    else await editInstructions(pi, ctx, agent);
+  }
+}
+
+/** Open the per-agent settings editor; every change is written to the global config. */
+export async function openSettings(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  if (ctx.mode !== "tui") {
+    ctx.ui.notify(`bot-lobby settings live in ${globalConfigPath()}; edit that file outside the TUI.`, "info");
+    return;
+  }
+  for (;;) {
+    const config = loadConfig();
+    const items: SelectItem[] = AGENT_KINDS.map((agent) => {
+      const cfg = agentConfig(config, agent);
+      const custom = cfg.instructions ? " · custom" : "";
+      return { value: agent, label: agentLabel(agent), description: `${cfg.model} · ${cfg.thinking}${custom}` };
+    });
+    items.push({ value: "close", label: "Close" });
+    const choice = await pick(ctx, "bot-lobby settings", items);
+    if (!choice || choice === "close") return;
+    await editAgent(pi, ctx, choice as AgentKind);
+  }
+}