herm-tui 1.0.0-dev.1

package/src/components/sidebar/Sidebar.tsx

@@ -0,0 +1,143 @@
+import { useState, memo, type ReactNode } from "react"
+import { AnimatedAvatar } from "../avatar/AnimatedAvatar"
+import type { ParsedEikon } from "../avatar/eikon"
+import { useTheme } from "../../theme"
+import type { AvatarState } from "../avatar/states"
+import type { SessionInfo } from "../../utils/gateway-types"
+import type { Usage } from "../../types/message"
+import { useGitBranch, rtrunc } from "../../utils/git"
+import { Tail } from "../chat/ThoughtCloud"
+import { ContextGauge } from "./ContextGauge"
+
+// The pillar body carries a compact identity block, the MCP operational
+// section, and a context-usage gauge at the bottom. Stats/Memory/Recent/
+// Identity wrapper and the Plugins section were removed — they duplicated
+// dedicated tabs and cluttered the most-visible surface.
+
+const WIDTH = 48
+const PAD_L = 12
+
+const trunc = (s: string, max: number) => s.length <= max ? s : s.slice(0, max - 1) + "…"
+
+// ─── Primitives (pillar-colored) ─────────────────────────────────────
+
+const Section = memo((props: {
+  title: string; hint?: string
+  open: boolean; onToggle: () => void
+  children: ReactNode
+}) => {
+  const theme = useTheme().theme
+  const [hover, setHover] = useState(false)
+  return (
+    <box flexDirection="column" marginBottom={props.open ? 1 : 0}>
+      <box height={1}
+           onMouseDown={props.onToggle}
+           onMouseOver={() => setHover(true)}
+           onMouseOut={() => setHover(false)}>
+        <text>
+          <span fg={hover ? theme.hermBodyText : theme.hermBodyTextMuted}>
+            {props.open ? "▾ " : "▸ "}
+          </span>
+          <span fg={theme.hermBodyText}><strong>{props.title}</strong></span>
+          {props.hint ? <span fg={theme.hermBodyTextMuted}>{`  ${props.hint}`}</span> : null}
+        </text>
+      </box>
+      {props.open ? <box flexDirection="column">{props.children}</box> : null}
+    </box>
+  )
+})
+
+const Row = (props: { label: string; value: string; strong?: boolean }) => {
+  const theme = useTheme().theme
+  return (
+    <box height={1}>
+      <text>
+        <span fg={theme.hermBodyTextMuted}>{`  ${props.label.padEnd(PAD_L)}`}</span>
+        {props.strong
+          ? <span fg={theme.hermBodyText}><strong>{trunc(props.value, WIDTH - PAD_L - 4)}</strong></span>
+          : <span fg={theme.hermBodyText}>{trunc(props.value, WIDTH - PAD_L - 4)}</span>}
+      </text>
+    </box>
+  )
+}
+
+// ─── Main ────────────────────────────────────────────────────────────
+
+export const Sidebar = memo((props: {
+  agentState?: AvatarState
+  info?: SessionInfo | null
+  usage?: Usage
+  eikon?: ParsedEikon
+  profile?: string
+  title?: string
+  cloud?: boolean
+  pulse?: boolean
+  onAvatar?: () => void
+}) => {
+  const theme = useTheme().theme
+  const state = props.agentState ?? "idle"
+  const info = props.info
+
+  const [mcpOpen, setMcpOpen] = useState(false)
+
+  const cwd = info?.cwd ?? process.cwd()
+  const branch = useGitBranch(cwd)
+
+  return (
+    <box width={WIDTH} flexDirection="column">
+      {/* Avatar (bust) — also the anchor for the thought-cloud tail */}
+      <box position="relative" flexDirection="column" height={24} overflow="hidden"
+           onMouseDown={props.onAvatar}>
+        <AnimatedAvatar state={state} eikon={props.eikon} />
+        {props.cloud ? (
+          <box position="absolute" left={0} top={0}>
+            <Tail run={!!props.pulse} />
+          </box>
+        ) : null}
+      </box>
+
+      {/* Body (pillar) */}
+      <box padding={1} flexDirection="column" flexGrow={1}
+           backgroundColor={theme.hermBody} overflow="hidden">
+
+        {/* Flat identity block — Title is primary (always rendered so the
+            block doesn't reflow when `/title` fires), then Profile
+            (which IS agent lineage — each profile is an isolated
+            HERMES_HOME), then model/cwd/branch. */}
+        <Row label="Title" value={props.title || "—"} strong={!!props.title} />
+        <Row label="Profile" value={props.profile ?? "default"}
+             strong={!!props.profile && props.profile !== "default"} />
+        <Row label="Model" value={info?.model ?? "—"} />
+        {info?.cwd ? <Row label="cwd" value={info.cwd} /> : null}
+        {branch ? <Row label="Branch" value={rtrunc(branch, WIDTH - PAD_L - 4)} /> : null}
+
+        {(info?.mcp_servers?.length ?? 0) > 0 ? (() => {
+          const srv = info!.mcp_servers!
+          const ok = srv.filter(s => s.connected).length
+          return (
+            <Section title="MCP"
+                     hint={`${ok}/${srv.length} up`}
+                     open={mcpOpen} onToggle={() => setMcpOpen(o => !o)}>
+              {srv.map(s => (
+                <box key={s.name} height={1}>
+                  <text>
+                    <span fg={theme.hermBodyTextMuted}>{"  "}</span>
+                    <span fg={s.connected ? theme.hermBodyText : theme.hermBodyTextMuted}>
+                      {(s.connected ? "● " : "○ ") + trunc(s.name, 16).padEnd(16)}
+                    </span>
+                    <span fg={theme.hermBodyTextMuted}>
+                      {s.connected ? ` ${s.transport} · ${s.tools}t` : " failed"}
+                    </span>
+                  </text>
+                </box>
+              ))}
+            </Section>
+          )
+        })() : null}
+
+        <box flexGrow={1} />
+        <ContextGauge info={info} usage={props.usage} width={WIDTH - 4} />
+      </box>
+    </box>
+  )
+})

package/src/components/tabs/TabBar.tsx

@@ -0,0 +1,50 @@
+import { memo } from "react"
+import { useTheme } from "../../theme"
+import { useKeys } from "../../keys"
+
+type Tab = {
+  name: string
+  description: string
+}
+
+type TabBarProps = {
+  tabs: ReadonlyArray<Tab>
+  activeTab: number
+  onTabChange: (index: number) => void
+}
+
+// 1..9, 0, - — mirrors the <leader>+digit map in useAppKeys.
+const idx = (i: number) => i < 9 ? String(i + 1) : i === 9 ? "0" : "-"
+
+export const TabBar = memo(({ tabs, activeTab, onTabChange }: TabBarProps) => {
+  const theme = useTheme().theme
+  const keys = useKeys()
+
+  return (
+    <box width="100%" flexDirection="column" height={1}>
+      <box flexDirection="row" overflow="hidden">
+        {tabs.map((tab, i) => (
+          <box
+            key={i}
+            onMouseDown={() => onTabChange(i)}
+            paddingX={2}
+            marginRight={1}
+            flexShrink={0}
+            backgroundColor={i === activeTab ? theme.backgroundElement : undefined}
+          >
+            <text attributes={3}>
+              <span fg={theme.borderSubtle}>{idx(i)} </span>
+              <span fg={i === activeTab ? theme.primary : theme.textMuted}>{tab.name}</span>
+            </text>
+          </box>
+        ))}
+        <box flexGrow={1} minWidth={0} />
+        <box paddingX={1} flexShrink={1} minWidth={0} overflow="hidden">
+          <text fg={theme.borderSubtle}>
+            {`${keys.print("tab.prev")}/${keys.print("tab.next")} or ${keys.print("leader")} N`}
+          </text>
+        </box>
+      </box>
+    </box>
+  )
+})

package/src/components/ui/FileLink.tsx

@@ -0,0 +1,52 @@
+/**
+ * FileLink — Generic clickable file reference.
+ *
+ * Wraps in a box for mouse hit-testing. Opens the source file
+ * in the OS default handler when clicked. Underlines on hover.
+ */
+
+import { useState, memo } from "react";
+import { TextAttributes } from "@opentui/core";
+import type { Source } from "../../utils/hermes-home";
+import { openFile } from "../../utils/open-file";
+import { useTheme } from "../../theme";
+
+interface FileLinkProps {
+  source: Source;
+  children?: string;
+}
+
+export const FileLink = memo(({ source, children }: FileLinkProps) => {
+  const theme = useTheme().theme;
+  const [hovered, setHovered] = useState(false);
+
+  return (
+    <box
+      height={1}
+      onMouseDown={() => openFile(source.file)}
+      onMouseOver={() => setHovered(true)}
+      onMouseOut={() => setHovered(false)}
+    >
+      <text
+        fg={theme.info}
+        attributes={hovered ? TextAttributes.UNDERLINE : TextAttributes.NONE}
+      >
+        {children ?? source.label}
+      </text>
+    </box>
+  );
+});
+
+// KV row whose value is a clickable FileLink. Lives beside FileLink
+// rather than in ui/kv so that module stays free of data-layer deps.
+export const KVLink = (props: { label: string; source: Source; text?: string }) => {
+  const theme = useTheme().theme;
+  return (
+    <box height={1} flexDirection="row">
+      <box width={13} flexShrink={0}><text fg={theme.textMuted}>{props.label}</text></box>
+      <box flexGrow={1} minWidth={0} height={1} overflow="hidden">
+        <FileLink source={props.source}>{props.text ?? props.source.label}</FileLink>
+      </box>
+    </box>
+  );
+};

package/src/config/index.ts

@@ -0,0 +1,156 @@
+import { SCHEMA, SCHEMA_KEYS, type ConfigEffect } from "./schema"
+import { route } from "./lane"
+
+export type FieldType = "boolean" | "select" | "number" | "string" | "readonly"
+
+export type Field = {
+  key: string
+  label: string
+  type: FieldType
+  value: unknown
+  /** True when the user's config.yaml has this key; false when
+   *  falling through to the schema default. */
+  set: boolean
+  doc: string
+  effect: ConfigEffect
+  options?: string[]
+}
+
+// Enum-valued string fields the schema doesn't carry options for.
+// Kept minimal — most enums are validated by rules.ts on commit; these
+// are the ones worth cycling with [h/l] instead of free-typing.
+const SELECTS: Record<string, string[]> = {
+  "terminal.backend": ["local", "docker", "ssh", "modal", "daytona", "singularity", "vercel_sandbox"],
+  "tts.provider": ["edge", "elevenlabs", "openai", "neutts", "xai", "mistral"],
+  "display.skin": ["default", "ares", "mono", "slate"],
+  "logging.level": ["DEBUG", "INFO", "WARNING", "ERROR"],
+  "agent.reasoning_effort": ["", "none", "minimal", "low", "medium", "high", "xhigh"],
+  "display.busy_input_mode": ["queue", "steer", "interrupt"],
+  "display.details_mode": ["hidden", "collapsed", "expanded"],
+  "display.thinking_mode": ["collapsed", "truncated", "full"],
+  "display.tool_progress": ["off", "new", "all", "verbose"],
+  "approvals.mode": ["manual", "ask", "yolo", "deny"],
+}
+
+const get = (obj: Record<string, unknown>, path: string): unknown => {
+  let cur: unknown = obj
+  for (const p of path.split(".")) {
+    if (cur && typeof cur === "object" && !Array.isArray(cur)) cur = (cur as Record<string, unknown>)[p]
+    else return undefined
+  }
+  return cur
+}
+
+const classify = (key: string, t: string): FieldType => {
+  if (route(key).via === "readonly") return "readonly"
+  if (SELECTS[key]) return "select"
+  if (t === "bool") return "boolean"
+  if (t === "int" || t === "float") return "number"
+  return "string"
+}
+
+const labelOf = (key: string): string => {
+  const raw = SCHEMA[key]?.group ?? key.split(".")[0]
+  return key.startsWith(`${raw}.`) ? key.slice(raw.length + 1) : key
+}
+
+/** Build the full field model: every schema key, value = user-set
+ *  else default, plus any user keys the schema doesn't know about
+ *  (so surprises in config.yaml still surface). */
+export const buildFields = (user: Record<string, unknown>): Field[] => {
+  const seen = new Set<string>()
+  const out: Field[] = []
+
+  for (const key of SCHEMA_KEYS) {
+    const s = SCHEMA[key]
+    const uv = get(user, key)
+    const set = uv !== undefined
+    out.push({
+      key,
+      label: labelOf(key),
+      type: classify(key, s.type),
+      value: set ? uv : s.default,
+      set,
+      doc: s.doc,
+      effect: s.effect,
+      options: SELECTS[key],
+    })
+    seen.add(key)
+  }
+
+  // Unknown user keys (future agent version, hand-edits, plugins).
+  const walk = (obj: Record<string, unknown>, prefix = "") => {
+    for (const [k, v] of Object.entries(obj)) {
+      const key = prefix ? `${prefix}.${k}` : k
+      if (v && typeof v === "object" && !Array.isArray(v)) {
+        // Don't recurse into a dict that's itself a known readonly leaf.
+        if (SCHEMA[key]?.type === "dict") { seen.add(key); continue }
+        walk(v as Record<string, unknown>, key)
+        continue
+      }
+      if (seen.has(key)) continue
+      out.push({
+        key,
+        label: labelOf(key),
+        type: Array.isArray(v) ? "readonly"
+          : typeof v === "boolean" ? "boolean"
+          : typeof v === "number" ? "number"
+          : "string",
+        value: v, set: true, doc: "", effect: "live",
+      })
+    }
+  }
+  walk(user)
+
+  return out
+}
+
+// Small/satellite groups fold into a parent. This is a UX decision,
+// not derivable from source — keeps the sidebar to ~18 entries instead
+// of 34 with a dozen 1-field groups.
+const MERGE: Record<string, string> = {
+  approvals: "security", privacy: "security",
+  checkpoints: "agent", context: "agent", cron: "agent", network: "agent",
+  model_catalog: "general", onboarding: "general",
+  human_delay: "display", dashboard: "display",
+  tool_output: "agent", prompt_caching: "compression", code_execution: "terminal",
+  slack: "platforms", telegram: "platforms", mattermost: "platforms",
+  discord: "platforms", whatsapp: "platforms",
+}
+
+export const rawGroupOf = (key: string): string =>
+  SCHEMA[key]?.group ?? (key.includes(".") ? key.split(".")[0] : "general")
+
+export const groupOf = (key: string): string => {
+  const raw = rawGroupOf(key)
+  return MERGE[raw] ?? raw
+}
+
+export type Section = { head: string | null; items: Field[] }
+
+/** Chunk a merged-group field list by its raw (pre-merge) groups so the
+ *  UI can render sub-headers. Single-chunk → head=null. Multi-chunk →
+ *  the self-named chunk (raw === merged name) floats to the front. */
+export const sections = (group: string, fields: Field[]): Section[] => {
+  const by = new Map<string, Field[]>()
+  for (const f of fields) {
+    const r = rawGroupOf(f.key)
+    if (!by.has(r)) by.set(r, [])
+    by.get(r)!.push(f)
+  }
+  if (by.size <= 1) return [{ head: null, items: fields }]
+  const order = [...by.keys()].sort((a, b) =>
+    a === group ? -1 : b === group ? 1 : a.localeCompare(b))
+  return order.map(r => ({ head: r, items: by.get(r)! }))
+}
+
+/** Distinct groups in schema after merging, 'general' pinned first. */
+export const GROUPS: string[] = (() => {
+  const g = new Set<string>(["general"])
+  for (const k of SCHEMA_KEYS) g.add(groupOf(k))
+  return [...g]
+})()
+
+export const EFFECT_GLYPH: Record<ConfigEffect, string> = {
+  live: "", session: "↻", restart: "⟳",
+}

package/src/config/lane.ts

@@ -0,0 +1,161 @@
+import { SCHEMA, type ConfigSchemaEntry, type ConfigEffect } from "./schema"
+
+// ─── RPC alias map ───────────────────────────────────────────────────
+//
+// `config.set` on the gateway accepts a short whitelist of ALIAS keys,
+// not dotted paths (anything else → 4002). Several of these mutate the
+// live agent in place (reasoning effort, model, tool verbosity, …), so
+// routing those through the RPC lane is what makes Config-tab edits
+// apply to the running conversation without a new session.
+
+type RpcAlias = {
+  alias: string
+  /** Map the schema-typed value to the wire value the alias expects. */
+  toWire?: (v: unknown) => string
+}
+
+const onOff = (v: unknown) => (v ? "on" : "off")
+
+export const RPC_ALIAS: Record<string, RpcAlias> = {
+  model: { alias: "model" },
+  provider: { alias: "model" },
+  "agent.service_tier": { alias: "fast" },
+  "agent.reasoning_effort": { alias: "reasoning" },
+  "display.show_reasoning": { alias: "reasoning", toWire: v => (v ? "show" : "hide") },
+  "display.tool_progress": { alias: "verbose" },
+  "display.busy_input_mode": { alias: "busy" },
+  "display.details_mode": { alias: "details_mode" },
+  "display.thinking_mode": { alias: "thinking_mode" },
+  "display.tui_compact": { alias: "compact", toWire: onOff },
+  "display.tui_statusbar": { alias: "statusbar" },
+  "display.tui_mouse": { alias: "mouse", toWire: onOff },
+  "display.skin": { alias: "skin" },
+  "display.personality": { alias: "personality" },
+  custom_prompt: { alias: "prompt" },
+}
+
+// ─── lane routing ────────────────────────────────────────────────────
+
+export type Lane =
+  | { via: "rpc"; alias: string; toWire?: (v: unknown) => string }
+  | { via: "cli" }
+  | { via: "readonly" }
+
+export const route = (key: string): Lane => {
+  const a = RPC_ALIAS[key]
+  if (a) return { via: "rpc", alias: a.alias, toWire: a.toWire }
+  if (key.startsWith("display.sections."))
+    return { via: "rpc", alias: `details_mode.${key.slice("display.sections.".length)}` }
+  const s = SCHEMA[key]
+  if (s && (s.type === "list" || s.type === "dict")) return { via: "readonly" }
+  return { via: "cli" }
+}
+
+// ─── value coercion for cli.exec ─────────────────────────────────────
+//
+// `hermes config set` parses the string argv[2] with heuristics
+// (true/false/on/off/yes/no → bool, all-digits → int, digits.digits →
+// float, else raw string). We pre-format so the heuristic lands on the
+// schema's declared type — in particular, a str-typed field whose
+// value *looks* numeric stays a string by going through the cli raw.
+
+export const toCliString = (key: string, v: unknown): string => {
+  const t: ConfigSchemaEntry["type"] = SCHEMA[key]?.type ?? "str"
+  if (t === "bool") return v ? "true" : "false"
+  if (t === "int") return String(Math.trunc(Number(v)))
+  if (t === "float") return String(Number(v))
+  return String(v ?? "")
+}
+
+// ─── write engine ────────────────────────────────────────────────────
+
+export type Diff = { key: string; to: unknown }
+export type WriteResult = {
+  ok: string[]
+  failed: { key: string; err: string }[]
+  warnings: { key: string; msg: string }[]
+}
+
+type Gw = {
+  request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>
+}
+
+/** Apply a batch of config edits, routing each through its lane. RPC
+ *  calls run first (they may refuse with a structured error and carry
+ *  optional `warning`), then cli calls run serially — each one rewrites
+ *  the whole config file, so Promise.all would last-write-wins. */
+export const writeConfig = async (gw: Gw, diffs: Diff[]): Promise<WriteResult> => {
+  const ok: string[] = []
+  const failed: WriteResult["failed"] = []
+  const warnings: WriteResult["warnings"] = []
+
+  const rpc = diffs.filter(d => route(d.key).via === "rpc")
+  const cli = diffs.filter(d => route(d.key).via === "cli")
+  const ro = diffs.filter(d => route(d.key).via === "readonly")
+  for (const d of ro) failed.push({ key: d.key, err: "structured value — edit in YAML mode" })
+
+  for (const d of rpc) {
+    const lane = route(d.key) as Extract<Lane, { via: "rpc" }>
+    const value = lane.toWire ? lane.toWire(d.to) : String(d.to ?? "")
+    try {
+      const res = await gw.request<{ warning?: string }>("config.set", { key: lane.alias, value })
+      ok.push(d.key)
+      if (res?.warning) warnings.push({ key: d.key, msg: res.warning })
+    } catch (e) {
+      failed.push({ key: d.key, err: e instanceof Error ? e.message : String(e) })
+    }
+  }
+
+  for (const d of cli) {
+    try {
+      const res = await gw.request<{ code: number; output: string; blocked?: boolean; hint?: string }>(
+        "cli.exec", { argv: ["config", "set", d.key, toCliString(d.key, d.to)], timeout: 30 },
+      )
+      if (res.blocked) failed.push({ key: d.key, err: res.hint ?? "blocked" })
+      else if (res.code !== 0) failed.push({ key: d.key, err: res.output.split("\n")[0] || `exit ${res.code}` })
+      else ok.push(d.key)
+    } catch (e) {
+      failed.push({ key: d.key, err: e instanceof Error ? e.message : String(e) })
+    }
+  }
+
+  return { ok, failed, warnings }
+}
+
+// ─── effect aggregation ──────────────────────────────────────────────
+
+const EFFECT_RANK: Record<ConfigEffect, number> = { live: 0, session: 1, restart: 2 }
+
+export const maxEffect = (keys: string[]): ConfigEffect =>
+  keys.reduce<ConfigEffect>((acc, k) => {
+    const e = SCHEMA[k]?.effect ?? "live"
+    return EFFECT_RANK[e] > EFFECT_RANK[acc] ? e : acc
+  }, "live")
+
+// ─── verification ────────────────────────────────────────────────────
+
+const get = (obj: Record<string, unknown>, path: string): unknown => {
+  let cur: unknown = obj
+  for (const p of path.split(".")) {
+    if (cur && typeof cur === "object" && !Array.isArray(cur)) cur = (cur as Record<string, unknown>)[p]
+    else return undefined
+  }
+  return cur
+}
+
+const eq = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+
+/** After a write, compare intended values against a fresh config.get.
+ *  RPC-aliased keys are skipped — several aliases write to a different
+ *  dotted path than the one edited (e.g. reasoning:show →
+ *  display.show_reasoning), so a literal readback would false-positive. */
+export const verifyWrite = async (gw: Gw, applied: Diff[]): Promise<string[]> => {
+  const res = await gw.request<{ config?: Record<string, unknown> }>("config.get", { key: "full" })
+  const cfg = res.config ?? {}
+  const miss: string[] = []
+  for (const d of applied) {
+    if (route(d.key).via !== "cli") continue
+    if (!eq(get(cfg, d.key), d.to)) miss.push(d.key)
+  }
+  return miss
+}

package/src/config/models.ts

@@ -0,0 +1,95 @@
+// Model-slot view over config.yaml — the "Models" category in Config.
+//
+// Reads are pure projections over the `config.get {key:"full"}` object
+// Config.tsx already holds, so there's no second RPC. Writes route
+// through the existing lanes: main → `config.set key=model` (rpc lane,
+// hot-swaps the live agent and persists with --global); aux →
+// `writeConfig()` (cli lane, `hermes config set auxiliary.<t>.…`).
+//
+// Intentionally NOT a gateway client of /api/model/auxiliary or
+// /api/model/set — those are web_server-only endpoints. Everything
+// here is derivable from config + the stock tui_gateway surface.
+
+import { writeConfig, type WriteResult } from "./lane"
+import type { ConfigSetResponse } from "../utils/gateway-types"
+
+type Gw = {
+  request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>
+}
+
+// Mirrors _AUX_TASK_SLOTS in hermes_cli/web_server.py — ordering kept
+// so herm and the webui read the same top-to-bottom.
+export const AUX_TASKS = [
+  { key: "vision",           label: "Vision",         hint: "Image analysis" },
+  { key: "web_extract",      label: "Web Extract",    hint: "Page summarization" },
+  { key: "compression",      label: "Compression",    hint: "Context compaction" },
+  { key: "session_search",   label: "Session Search", hint: "Recall queries" },
+  { key: "skills_hub",       label: "Skills Hub",     hint: "Skill search" },
+  { key: "approval",         label: "Approval",       hint: "Smart auto-approve" },
+  { key: "mcp",              label: "MCP",            hint: "MCP tool routing" },
+  { key: "title_generation", label: "Title Gen",      hint: "Session titles" },
+  { key: "curator",          label: "Curator",        hint: "Skill-usage review" },
+] as const
+
+export type AuxKey = typeof AUX_TASKS[number]["key"]
+
+export type Slot =
+  | { kind: "main"; key: "main"; label: string; hint: string
+      provider: string; model: string; auto: false }
+  | { kind: "aux"; key: AuxKey; label: string; hint: string
+      provider: string; model: string; auto: boolean }
+
+const dig = (o: unknown, ...path: string[]): unknown =>
+  path.reduce<unknown>((c, p) =>
+    c && typeof c === "object" ? (c as Record<string, unknown>)[p] : undefined, o)
+
+const str = (v: unknown) => typeof v === "string" ? v : ""
+
+/** Project config.yaml → 1 main + 9 aux slots. */
+export const readSlots = (raw: Record<string, unknown>): Slot[] => {
+  const main: Slot = {
+    kind: "main", key: "main", label: "Main model", hint: "Primary agent model",
+    provider: str(dig(raw, "model", "provider")),
+    model: str(dig(raw, "model", "default")) || str(dig(raw, "model", "name")),
+    auto: false,
+  }
+  const aux = AUX_TASKS.map<Slot>(t => {
+    const p = str(dig(raw, "auxiliary", t.key, "provider"))
+    return {
+      kind: "aux", key: t.key, label: t.label, hint: t.hint,
+      provider: p, model: str(dig(raw, "auxiliary", t.key, "model")),
+      auto: p === "" || p === "auto",
+    }
+  })
+  return [main, ...aux]
+}
+
+export type AssignResult = WriteResult & { warning?: string }
+
+/** Write a slot. Main goes via the rpc `config.set key=model` alias
+ *  (same path as /model --global — live-applies and clears stale
+ *  base_url/context_length upstream). Aux writes two cli-lane keys. */
+export const assign = async (
+  gw: Gw, slot: Slot["key"], provider: string, model: string,
+): Promise<AssignResult> => {
+  if (slot === "main") {
+    const r = await gw.request<ConfigSetResponse>("config.set", {
+      key: "model", value: `${model} --provider ${provider} --global`,
+      session_id: undefined,
+    })
+    return { ok: ["model.default", "model.provider"], failed: [], warnings: [], warning: r.warning }
+  }
+  return writeConfig(gw, [
+    { key: `auxiliary.${slot}.provider`, to: provider },
+    { key: `auxiliary.${slot}.model`, to: model },
+  ])
+}
+
+/** Reset one aux slot (or all) to provider="auto", model="". */
+export const resetAux = (gw: Gw, slot: AuxKey | "all"): Promise<WriteResult> => {
+  const keys = slot === "all" ? AUX_TASKS.map(t => t.key) : [slot]
+  return writeConfig(gw, keys.flatMap(k => [
+    { key: `auxiliary.${k}.provider`, to: "auto" },
+    { key: `auxiliary.${k}.model`, to: "" },
+  ]))
+}