@capagents/forgeqe 1.0.4 → 1.0.5

package/src/tui/components.tsx

@@ -50,6 +50,12 @@ export type PromptProps = {
   masked?: number
   /** Beside a session panel that names the model and profile, and a status bar: no bottom row. */
   compact?: boolean
+  /** Text the box starts with when `inputKey` changes (a refined request, an example from the palette). */
+  initialValue?: string
+  /** False while an overlay (the palette, a suggestion list) takes the keyboard. Default true. */
+  focused?: boolean
+  /** Called with the text as it changes, for actions on what is being typed (Refine). */
+  onText?: (text: string) => void
 }
 
 /** Enter sends; Shift+Enter, Alt+Enter or Ctrl+J start a new line. */
@@ -66,7 +72,12 @@ export function Prompt(props: PromptProps) {
   const ref = useRef<TextareaRenderable>(null)
   const [rows, setRows] = useState(props.minRows)
   useEffect(() => setRows(props.minRows), [props.inputKey, props.minRows])
+  // Inserted text (a completion, an example, a refined request) is continued from its end.
+  useEffect(() => {
+    if (props.initialValue) ref.current?.gotoBufferEnd()
+  }, [props.inputKey])
   const fit = () => {
+    props.onText?.(ref.current?.plainText ?? "")
     const lines = ref.current?.virtualLineCount ?? 1
     setRows(Math.min(props.maxRows, Math.max(props.minRows, lines)))
   }
@@ -95,7 +106,8 @@ export function Prompt(props: PromptProps) {
             key={props.inputKey}
             ref={ref}
             placeholder={props.placeholder}
-            focused
+            focused={props.focused !== false}
+            initialValue={props.initialValue || ""}
             wrapMode="word"
             keyBindings={PROMPT_KEYS}
             onSubmit={() => props.onSubmit(ref.current?.plainText ?? "")}
@@ -162,9 +174,23 @@ export function Spinner({ kind = "bar", color = theme.warn }: { kind?: "bar" | "
   )
 }
 
-export type Hint = { key: string; label: string; onPress?: () => void }
+/** `drop`: the order hints give way when the row is too narrow, highest first; without it a hint always stays. */
+export type Hint = { key: string; label: string; onPress?: () => void; drop?: number }
+
+/** The hints that fit in `room` columns: whole hints give way, by their `drop`, rather than every label being squeezed. */
+export function fitHints(items: Hint[], room: number): Hint[] {
+  const cells = (list: Hint[]) => list.reduce((n, h, i) => n + h.key.length + (h.label ? h.label.length + 1 : 0) + (i ? 2 : 0), 0)
+  let kept = [...items]
+  const order = items.filter((h) => h.drop !== undefined).sort((a, b) => b.drop! - a.drop!)
+  for (const h of order) {
+    if (cells(kept) <= room) break
+    kept = kept.filter((k) => k !== h)
+  }
+  return kept
+}
 
-export function Hints({ width, items, left }: { width: number; items: Hint[]; left?: ReactNode }) {
+export function Hints({ width, items: all, left, reserve = 0 }: { width: number; items: Hint[]; left?: ReactNode; reserve?: number }) {
+  const items = fitHints(all, width - reserve)
   return (
     <box style={{ width, height: 1, flexShrink: 0, flexDirection: "row", justifyContent: "space-between" }}>
       <box style={{ flexDirection: "row" }}>{left}</box>

package/src/tui/inspector.tsx

@@ -25,15 +25,33 @@ export const SECTION = {
 /** Rows a panel's border takes: top and bottom. */
 export const PANEL_CHROME = 2
 
-/** A titled, rounded panel; `width` and `height` include the border. */
-export function Panel(props: { title: string; color: string; width?: number; height?: number; children: ReactNode }) {
+/** The panels keys can move between (shift+tab), after the chat; the order they sit in on screen. */
+export type Focus = "chat" | "plan" | "activity" | "files"
+export const FOCUS_ORDER: Focus[] = ["chat", "plan", "activity", "files"]
+
+/** The next panel shift+tab moves to, past any that are not on screen. */
+export function nextFocus(at: Focus, shown: (f: Focus) => boolean): Focus {
+  for (let i = 1; i <= FOCUS_ORDER.length; i++) {
+    const f = FOCUS_ORDER[(FOCUS_ORDER.indexOf(at) + i) % FOCUS_ORDER.length]!
+    if (shown(f)) return f
+  }
+  return "chat"
+}
+
+/**
+ * A titled, rounded panel; `width` and `height` include the border. Focused, its border takes the section's colour and
+ * its keys show in the bottom border.
+ */
+export function Panel(props: { title: string; color: string; width?: number; height?: number; focused?: boolean; keys?: string; onFocus?: () => void; children: ReactNode }) {
   return (
     <box
       border
       borderStyle="rounded"
-      borderColor={theme.border}
+      borderColor={props.focused ? props.color : theme.border}
       title={` ${props.title} `}
       titleColor={props.color}
+      {...(props.focused && props.keys ? { bottomTitle: ` ${props.keys} `, bottomTitleAlignment: "right" as const } : {})}
+      {...(props.onFocus ? { onMouseDown: props.onFocus } : {})}
       style={{
         flexDirection: "column",
         paddingLeft: 1,
@@ -84,7 +102,23 @@ export function SessionPanel({ info, width }: { info: SessionInfo; width: number
 }
 
 /** The right pane's first line: who is working on what and for how long, and Stop while something runs. */
-export function StatusBar(props: { running: boolean; who: string; activity: string; elapsed: string; status: string; width: number; onStop: () => void }) {
+/** "███████░░░░░ 5/8": how far a suite has got, in `cells` cells. */
+export function progressBar(done: number, total: number, cells: number): [string, string] {
+  const filled = total ? Math.round((Math.min(done, total) / total) * cells) : 0
+  return ["█".repeat(filled), "░".repeat(cells - filled)]
+}
+
+export function StatusBar(props: {
+  running: boolean
+  who: string
+  activity: string
+  elapsed: string
+  status: string
+  width: number
+  onStop: () => void
+  /** A suite's cases: done so far, of how many. */
+  progress?: { done: number; total: number } | null
+}) {
   const done = props.status === "done"
   const failed = props.status === "fail"
   const color = props.running ? theme.warn : done ? theme.ok : failed ? theme.err : theme.muted
@@ -97,7 +131,11 @@ export function StatusBar(props: { running: boolean; who: string; activity: stri
         : props.status === "stopped"
           ? "Last request stopped"
           : "Ready for your next request"
-  const room = Math.max(10, props.width - props.who.length - (props.running ? 30 : 6))
+  const bar = props.running && props.progress && props.progress.total > 1 ? props.progress : null
+  const cells = 12
+  const barText = bar ? ` ${bar.done}/${bar.total}  ` : ""
+  const room = Math.max(10, props.width - props.who.length - (props.running ? 30 : 6) - (bar ? cells + barText.length : 0))
+  const [full, empty] = bar ? progressBar(bar.done, bar.total, cells) : ["", ""]
   return (
     <box style={{ flexDirection: "row", justifyContent: "space-between", height: 1, flexShrink: 0, paddingLeft: 1, paddingRight: 1 }}>
       <box style={{ flexDirection: "row" }}>
@@ -109,6 +147,13 @@ export function StatusBar(props: { running: boolean; who: string; activity: stri
       </box>
       {props.running ? (
         <box style={{ flexDirection: "row" }}>
+          {bar ? (
+            <text>
+              <span fg={theme.ok}>{full}</span>
+              <span fg={theme.border}>{empty}</span>
+              <span fg={theme.muted}>{barText}</span>
+            </text>
+          ) : null}
           <text fg={theme.faint}>{`${props.elapsed}  `}</text>
           <box onMouseDown={props.onStop} style={{ paddingLeft: 1, paddingRight: 1, backgroundColor: theme.warn }}>
             <text fg={theme.onButton}>{"■ Stop · esc"}</text>
@@ -132,9 +177,9 @@ const PROGRESS_MARK: Record<Progress["status"], [string, string]> = {
   skipped: ["■", theme.faint],
 }
 
-type PlanLine = { mark: string; color: string; text: string; textColor: string }
+export type PlanLine = { mark: string; color: string; text: string; textColor: string }
 
-function planLines(s: Inspector): PlanLine[] {
+export function planLines(s: Inspector): PlanLine[] {
   const lines: PlanLine[] = []
   for (const p of s.plan) {
     const [mark, color] = PLAN_MARK[p.status] || PLAN_MARK.pending!
@@ -154,20 +199,33 @@ export function planRows(s: Inspector, cap: number): number {
   return n ? Math.min(cap, n) + PANEL_CHROME : 0
 }
 
-/** The agent's to-do list, then the browser steps or suite cases; the latest that fit. */
-export function PlanPanel({ s, width, height }: { s: Inspector; width: number; height: number }) {
+/** The rows of `total` a panel of `rows` shows: the latest, or, while a row is selected, a window that keeps it in view. */
+export function windowRows(total: number, rows: number, selected?: number): [number, number] {
+  if (selected === undefined) return [Math.max(0, total - rows), total]
+  const first = Math.max(0, Math.min(selected - Math.floor(rows / 2), total - rows))
+  return [first, Math.min(total, first + rows)]
+}
+
+/** The agent's to-do list, then the browser steps or suite cases; the latest that fit, or around the selected one. */
+export function PlanPanel(props: { s: Inspector; width: number; height: number; selected?: number; onFocus?: () => void }) {
+  const { s, width, height } = props
   const lines = planLines(s)
   const done = s.plan.filter((p) => p.status === "completed").length
   const count = s.plan.length ? ` · ${done} of ${s.plan.length}` : s.progress.items.length ? ` · ${clip(s.progress.title, 40)}` : ""
-  const shown = lines.slice(-Math.max(1, height - PANEL_CHROME))
+  const [first, last] = windowRows(lines.length, Math.max(1, height - PANEL_CHROME), props.selected)
   return (
-    <Panel title={`Plan${count}`} color={SECTION.plan} width={width} height={height}>
-      {shown.map((l, i) => (
-        <text key={i}>
-          <span fg={l.color}>{`${l.mark} `}</span>
-          <span fg={l.textColor}>{clip(l.text, Math.max(10, width - 8))}</span>
-        </text>
-      ))}
+    <Panel title={`Plan${count}`} color={SECTION.plan} width={width} height={height} focused={props.selected !== undefined} keys="↑↓ select · enter details · esc chat" onFocus={props.onFocus}>
+      {lines.slice(first, last).map((l, i) => {
+        const active = first + i === props.selected
+        return (
+          <box key={first + i} style={{ flexDirection: "row", height: 1, flexShrink: 0, backgroundColor: active ? theme.button : undefined }}>
+            <text>
+              <span fg={l.color}>{`${l.mark} `}</span>
+              <span fg={active ? theme.text : l.textColor}>{clip(l.text, Math.max(10, width - 8))}</span>
+            </text>
+          </box>
+        )
+      })}
     </Panel>
   )
 }
@@ -199,19 +257,63 @@ export function ActivityRow({ line }: { line: Line }) {
   )
 }
 
-/** Everything the agents do, newest at the bottom. */
-export function ActivityPanel(props: { lines: Line[]; scrollRef: RefObject<ScrollBoxRenderable | null>; width: number; height: number }) {
+/** What the activity panel can narrow to, and the key for each while it has focus. */
+export const ACTIVITY_FILTERS = [
+  { id: "all", label: "All", key: "a", kinds: null },
+  { id: "errors", label: "Errors", key: "e", kinds: ["err"] },
+  { id: "steps", label: "Steps", key: "s", kinds: ["ok", "err", "thought", "memory", "timing"] },
+  { id: "tools", label: "Tools", key: "t", kinds: ["tool", "file", "code"] },
+] as const
+export type ActivityFilter = (typeof ACTIVITY_FILTERS)[number]["id"]
+
+export function filterActivity(lines: Line[], filter: ActivityFilter): Line[] {
+  const kinds = ACTIVITY_FILTERS.find((f) => f.id === filter)?.kinds
+  return kinds ? lines.filter((l) => (kinds as readonly string[]).includes(l.kind)) : lines
+}
+
+/** Everything the agents do, newest at the bottom; focused, it scrolls and narrows to errors, steps, or tools. */
+export function ActivityPanel(props: {
+  lines: Line[]
+  scrollRef: RefObject<ScrollBoxRenderable | null>
+  width: number
+  height: number
+  filter?: ActivityFilter
+  focused?: boolean
+  onFocus?: () => void
+  onFilter?: (f: ActivityFilter) => void
+}) {
+  const filter = props.filter || "all"
+  const shown = filterActivity(props.lines, filter)
+  const label = ACTIVITY_FILTERS.find((f) => f.id === filter)!.label
+  const count = filter === "all" ? (shown.length ? ` · ${shown.length}` : "") : ` · ${label} ${shown.length} of ${props.lines.length}`
   return (
-    <Panel title={`Activity${props.lines.length ? ` · ${props.lines.length}` : ""}`} color={SECTION.activity} width={props.width} height={props.height}>
-      {props.lines.length ? (
+    <Panel title={`Activity${count}`} color={SECTION.activity} width={props.width} height={props.height} focused={props.focused} keys="↑↓ pgup pgdn scroll · esc chat" onFocus={props.onFocus}>
+      {props.focused || filter !== "all" ? (
+        <box style={{ flexDirection: "row", height: 1, flexShrink: 0 }}>
+          {ACTIVITY_FILTERS.map((f) => {
+            const on = f.id === filter
+            return (
+              <box key={f.id} onMouseDown={() => props.onFilter?.(f.id)} style={{ paddingLeft: 1, paddingRight: 1, marginRight: 1, backgroundColor: on ? SECTION.activity : theme.button }}>
+                <text>
+                  <span fg={on ? theme.onButton : theme.text}>{f.key}</span>
+                  <span fg={on ? theme.onButton : theme.muted}>{` ${f.label}`}</span>
+                </text>
+              </box>
+            )
+          })}
+        </box>
+      ) : null}
+      {shown.length ? (
         <scrollbox ref={props.scrollRef} stickyScroll stickyStart="bottom" style={{ flexGrow: 1 }} focused={false}>
-          {props.lines.map((line) => (
+          {shown.map((line) => (
             <ActivityRow key={line.id} line={line} />
           ))}
         </scrollbox>
       ) : (
         <box style={{ flexGrow: 1, justifyContent: "center", alignItems: "center" }}>
-          <text fg={theme.faint}>{clip("Tool calls, browser steps, and the agents' reasoning show here", Math.max(10, props.width - 4))}</text>
+          <text fg={theme.faint}>
+            {clip(props.lines.length ? `Nothing under ${label} yet` : "Tool calls, browser steps, and the agents' reasoning show here", Math.max(10, props.width - 4))}
+          </text>
         </box>
       )}
     </Panel>
@@ -231,31 +333,37 @@ function fileLabel(path: string, room: number): [string, string] {
   return [name, dir && (dir.length <= space || space >= 12) ? tailCut(dir, space) : ""]
 }
 
-export function FilesPanel({ s, width, height }: { s: Inspector; width: number; height: number }) {
+export function FilesPanel(props: { s: Inspector; width: number; height: number; selected?: number; onFocus?: () => void; onOpen?: (file: string) => void }) {
+  const { s, width, height } = props
   const files = filesByUse(s)
   const rows = height - PANEL_CHROME
   const room = Math.max(8, width - 10)
-  const listed = files.length > rows ? files.slice(0, rows - 1) : files
+  const focused = props.selected !== undefined
+  // Unfocused: the most recent, and how many more; focused: a window that follows the selection through all of them.
+  const [first, last] = focused ? windowRows(files.length, rows, props.selected) : [0, files.length > rows ? rows - 1 : files.length]
   return (
-    <Panel title={`Files${files.length ? ` · ${files.length}` : ""}`} color={SECTION.files} width={width} height={height}>
+    <Panel title={`Files${files.length ? ` · ${files.length}` : ""}`} color={SECTION.files} width={width} height={height} focused={focused} keys="enter open" onFocus={props.onFocus}>
       {files.length ? (
-        listed.map((f) => {
+        files.slice(first, last).map((f, i) => {
           const [mark, color] = FILE_MARK[f.last]
           const [name, dir] = fileLabel(f.path, room)
           const times = f.reads + f.changes
+          const active = first + i === props.selected
           return (
-            <text key={f.path}>
-              <span fg={color}>{`${mark} `}</span>
-              <span fg={f.changes ? theme.text : theme.muted}>{name}</span>
-              {dir ? <span fg={theme.faint}>{`  ${dir}`}</span> : null}
-              {times > 1 ? <span fg={theme.faint}>{` ×${times}`}</span> : null}
-            </text>
+            <box key={f.path} onMouseDown={() => props.onOpen?.(f.path)} style={{ flexDirection: "row", height: 1, flexShrink: 0, backgroundColor: active ? theme.button : undefined }}>
+              <text>
+                <span fg={color}>{`${mark} `}</span>
+                <span fg={f.changes || active ? theme.text : theme.muted}>{name}</span>
+                {dir ? <span fg={theme.faint}>{`  ${dir}`}</span> : null}
+                {times > 1 ? <span fg={theme.faint}>{` ×${times}`}</span> : null}
+              </text>
+            </box>
           )
         })
       ) : (
         <text fg={theme.faint}>{"None yet"}</text>
       )}
-      {files.length > listed.length ? <text fg={theme.faint}>{`+${files.length - listed.length} more`}</text> : null}
+      {!focused && files.length > last ? <text fg={theme.faint}>{`+${files.length - last} more`}</text> : null}
     </Panel>
   )
 }

package/src/tui/next.ts

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs"
+import path from "node:path"
+
+import type { Produced } from "./transcript.tsx"
+
+/**
+ * What to do next, after a request: a few one-click follow-ups from what it actually produced (a run that passed and
+ * has no test yet, a failed run, a report to open). Requests are put in the prompt to adjust; nothing is sent by a chip.
+ */
+
+export type NextStep = { label: string; run: { kind: "insert"; text: string } | { kind: "open"; path: string } }
+
+export function nextSteps(p: Produced, opts: { testsOn: boolean }): NextStep[] {
+  const steps: NextStep[] = []
+  const run = p.runs.at(-1)
+  const suite = p.suites.at(-1)
+  if (suite) {
+    if (existsSync(suite.html)) steps.push({ label: "Open the suite report", run: { kind: "open", path: suite.html } })
+    steps.push({ label: "Rerun the cases that failed", run: { kind: "insert", text: "Run the cases that failed in the last suite again" } })
+  } else if (run) {
+    const report = path.join(run.runDir, "report.html")
+    if (run.status === "complete" && !p.tests.some((t) => t.runDir === run.runDir)) steps.push({ label: "Write a test for this run", run: { kind: "insert", text: "Write a test for the last run" } })
+    if (run.status !== "complete") {
+      steps.push({ label: "Why did it fail?", run: { kind: "insert", text: "Why did the last run fail, and what should change?" } })
+      steps.push({ label: "Run it again, visible", run: { kind: "insert", text: "Run the last goal again in a visible browser" } })
+    }
+    if (existsSync(report)) steps.push({ label: "Open the report", run: { kind: "open", path: report } })
+  }
+  const test = p.tests.at(-1)
+  if (test?.result?.testFile && test.result.status === "passed") steps.unshift({ label: "Open the new test", run: { kind: "open", path: test.result.testFile } })
+  return steps.slice(0, 3)
+}

package/src/tui/palette.tsx

@@ -0,0 +1,169 @@
+import { CAPABILITIES } from "../capabilities/registry.ts"
+import { clip } from "./text.ts"
+import { theme } from "./theme.ts"
+
+/**
+ * The command palette (ctrl+p): every action, command, profile, and example request, found by typing a few letters.
+ * Items that would start work only fill the prompt; nothing is sent without the user pressing enter there.
+ */
+
+export type PaletteGroup = "Action" | "Command" | "Profile" | "Ask"
+
+export type PaletteRun =
+  /** Sent as if typed: a slash command. */
+  | { kind: "command"; text: string }
+  /** Put in the prompt to edit and send: an example request. */
+  | { kind: "insert"; text: string }
+  /** Something the shell does itself. */
+  | { kind: "action"; id: "refine" | "stop" | "details" | "chat" }
+
+export type PaletteItem = { id: string; group: PaletteGroup; title: string; detail?: string; keys?: string; run: PaletteRun }
+
+export const GROUP_COLOR: Record<PaletteGroup, string> = { Action: theme.warn, Command: theme.accent, Profile: theme.memory, Ask: theme.ok }
+
+export function paletteItems(opts: { running: boolean; headed: boolean; detailsFull: boolean; profiles: string[]; active: string; narrow: boolean; view: "chat" | "details" }): PaletteItem[] {
+  const items: PaletteItem[] = []
+  const command = (id: string, title: string, text: string, detail?: string, keys?: string) => items.push({ id, group: "Command", title, detail, keys, run: { kind: "command", text } })
+  if (opts.running) items.push({ id: "stop", group: "Action", title: "Stop the running request", keys: "esc", run: { kind: "action", id: "stop" } })
+  items.push({ id: "refine", group: "Action", title: "Refine my request", detail: "check it against what ForgeQE knows before sending", keys: "ctrl+r", run: { kind: "action", id: "refine" } })
+  if (opts.narrow) items.push({ id: "view", group: "Action", title: opts.view === "chat" ? "Show the details view" : "Back to the chat", keys: "ctrl+o", run: { kind: "action", id: opts.view === "chat" ? "details" : "chat" } })
+  command("features", "What ForgeQE can do here", "/features", "and what each feature still needs")
+  command("auth", "Sign in to a system", "/auth", "Azure DevOps, GitHub, Jira, Confluence, TestRail, Zephyr, qTest, Xray")
+  command("auth-status", "What is signed in", "/auth status")
+  command("headed", opts.headed ? "Hide the browser window" : "Show the browser window", `/headed ${opts.headed ? "off" : "on"}`)
+  command("details", opts.detailsFull ? "Show progress only" : "Show everything the agents do", `/details ${opts.detailsFull ? "off" : "on"}`)
+  command("skills", "Skills each agent can use", "/skills")
+  command("logs", "Save this session's log to share", "/logs")
+  command("clear", "Clear the chat", "/clear")
+  command("help", "Help", "/help")
+  command("exit", "Quit ForgeQE", "/exit", undefined, "ctrl+c")
+  for (const p of opts.profiles) if (p !== opts.active) items.push({ id: `profile:${p}`, group: "Profile", title: `Use the ${p} profile`, keys: "tab", run: { kind: "command", text: `/profile ${p}` } })
+  for (const c of CAPABILITIES) for (const e of c.examples) items.push({ id: `ask:${c.id}:${e}`, group: "Ask", title: e, detail: c.title, run: { kind: "insert", text: e } })
+  return items
+}
+
+/**
+ * How well `query` matches `text`, case ignored; null when it does not. In order of strength: the text contains the
+ * query (best at the start of a word), every typed word starts a word of the text ("run sp" finds "Run … sprint"),
+ * or a short query is the text's initials ("rr" finds "Refine my request"). Letters merely scattered through the text
+ * do not match: they find everything and help nobody.
+ */
+export function fuzzyScore(query: string, text: string): number | null {
+  const q = query.trim().toLowerCase()
+  if (!q) return 0
+  const t = text.toLowerCase()
+  const words = t.split(/[^a-z0-9]+/).filter(Boolean)
+  const at = t.indexOf(q)
+  if (at >= 0) return 100 + (at === 0 || /[^a-z0-9]/.test(t[at - 1]!) ? 20 : 0) - Math.min(20, at / 4)
+  const typed = q.split(/\s+/).filter(Boolean)
+  if (typed.length > 1 && typed.every((w) => words.some((x) => x.startsWith(w)))) return 70 - typed.length
+  if (typed.length === 1 && q.length >= 2 && q.length <= 5) {
+    if (words.map((w) => w[0]).join("").includes(q)) return 40
+  }
+  return null
+}
+
+/** The items that match, best first; with no query, in their own order. */
+export function searchPalette(query: string, items: PaletteItem[], limit = 50): PaletteItem[] {
+  if (!query.trim()) return items.slice(0, limit)
+  return items
+    .map((item, order) => {
+      const own = fuzzyScore(query, item.title)
+      // Also what a command is typed as ("/auth", "/headed"), so people who know the command find it by its name.
+      const typedAs = item.run.kind === "command" ? item.run.text : ""
+      const more = fuzzyScore(query, `${item.title} ${item.detail || ""} ${typedAs} ${item.group}`)
+      const best = own === null ? (more === null ? null : more - 2) : Math.max(own + 2, more ?? own)
+      return { item, order, score: best }
+    })
+    .filter((x): x is { item: PaletteItem; order: number; score: number } => x.score !== null)
+    .sort((a, b) => b.score - a.score || a.order - b.order)
+    .slice(0, limit)
+    .map((x) => x.item)
+}
+
+export function Palette(props: { width: number; height: number; query: string; items: PaletteItem[]; selected: number; onPick: (item: PaletteItem) => void; onHover: (index: number) => void }) {
+  const boxWidth = Math.min(100, props.width - 8)
+  const rows = Math.max(4, Math.min(16, props.height - 12))
+  // Keep the selection in view: the window of rows slides with it.
+  const first = Math.max(0, Math.min(props.selected - Math.floor(rows / 2), props.items.length - rows))
+  const shown = props.items.slice(first, first + rows)
+  const room = boxWidth - 6
+  return (
+    <box
+      position="absolute"
+      zIndex={100}
+      border
+      borderStyle="rounded"
+      borderColor={theme.accent}
+      title=" Command palette "
+      titleColor={theme.accent}
+      bottomTitle=" ↑↓ select · enter choose · esc close "
+      bottomTitleAlignment="right"
+      style={{ top: 2, left: Math.floor((props.width - boxWidth) / 2), width: boxWidth, flexDirection: "column", backgroundColor: theme.panel, paddingLeft: 1, paddingRight: 1 }}
+    >
+      <text>
+        <span fg={theme.accent}>{"› "}</span>
+        {props.query ? <span fg={theme.text}>{props.query}</span> : <span fg={theme.faint}>{"Type to find an action, a command, a profile, or something to ask"}</span>}
+        <span fg={theme.accent}>{"▏"}</span>
+      </text>
+      <text fg={theme.border}>{"─".repeat(Math.max(4, boxWidth - 4))}</text>
+      {shown.length ? (
+        shown.map((item, i) => {
+          const index = first + i
+          const active = index === props.selected
+          const keys = item.keys ? ` ${item.keys}` : ""
+          const titleRoom = Math.max(10, room - 10 - keys.length - (item.detail ? Math.min(34, item.detail.length) + 2 : 0))
+          return (
+            <box
+              key={item.id}
+              onMouseDown={() => props.onPick(item)}
+              onMouseOver={() => props.onHover(index)}
+              style={{ flexDirection: "row", justifyContent: "space-between", backgroundColor: active ? theme.button : theme.panel, flexShrink: 0 }}
+            >
+              <text>
+                <span fg={active ? theme.accent : theme.panel}>{"▌"}</span>
+                <span fg={GROUP_COLOR[item.group]}>{item.group.padEnd(8)}</span>
+                <span fg={active ? theme.text : theme.muted}>{clip(item.title, titleRoom)}</span>
+                {item.detail ? <span fg={theme.faint}>{`  ${clip(item.detail, 34)}`}</span> : null}
+              </text>
+              <text fg={theme.faint}>{keys}</text>
+            </box>
+          )
+        })
+      ) : (
+        <text fg={theme.faint}>{"  Nothing matches. Enter puts what you typed in the prompt; esc closes."}</text>
+      )}
+      {props.items.length > rows ? <text fg={theme.faint}>{`  ${props.items.length} matches`}</text> : null}
+    </box>
+  )
+}
+
+/** The suggestions above the prompt while "/" or "@" is typed: same rows as the palette, so the two read as one. */
+export function SuggestList(props: { title: string; width: number; items: { label: string; detail?: string; color: string }[]; selected: number; onPick: (i: number) => void; onHover: (i: number) => void }) {
+  const room = props.width - 6
+  return (
+    <box
+      border
+      borderStyle="rounded"
+      borderColor={theme.border}
+      title={` ${props.title} `}
+      titleColor={theme.accent}
+      bottomTitle=" tab complete · ↑↓ · esc "
+      bottomTitleAlignment="right"
+      style={{ flexDirection: "column", width: props.width, paddingLeft: 1, paddingRight: 1, backgroundColor: theme.panel, flexShrink: 0 }}
+    >
+      {props.items.map((item, i) => {
+        const active = i === props.selected
+        return (
+          <box key={`${item.label}-${i}`} onMouseDown={() => props.onPick(i)} onMouseOver={() => props.onHover(i)} style={{ flexDirection: "row", backgroundColor: active ? theme.button : theme.panel, flexShrink: 0 }}>
+            <text>
+              <span fg={active ? theme.accent : theme.panel}>{"▌"}</span>
+              <span fg={item.color}>{clip(item.label, Math.max(10, Math.floor(room / 2)))}</span>
+              {item.detail ? <span fg={theme.faint}>{`  ${clip(item.detail, Math.max(8, room - item.label.length - 4))}`}</span> : null}
+            </text>
+          </box>
+        )
+      })}
+    </box>
+  )
+}

package/src/tui/refine-panel.tsx

@@ -0,0 +1,94 @@
+import type { Refined } from "../refine.ts"
+import { Spinner } from "./components.tsx"
+import { theme } from "./theme.ts"
+
+/** Refine's panel, in the prompt's place: working, the result with what was checked, or why it could not refine. */
+export type RefineState =
+  | { phase: "working"; original: string }
+  | { phase: "done"; original: string; result: Refined; choice: number }
+  | { phase: "error"; original: string; message: string }
+
+export const REFINE_CHOICES = [
+  { id: "use", label: "Use refined", key: "enter" },
+  { id: "edit", label: "Edit", key: "e" },
+  { id: "keep", label: "Keep mine", key: "esc" },
+] as const
+
+export type RefineChoice = (typeof REFINE_CHOICES)[number]["id"]
+
+const COLOR = theme.memory
+
+export function RefinePanel(props: { state: RefineState; width: number; onChoose: (id: RefineChoice) => void; onHover: (i: number) => void }) {
+  const { state, width } = props
+  const title = state.phase === "working" ? " ✦ Refining " : state.phase === "error" ? " ✦ Could not refine " : " ✦ Refined request "
+  const section = (label: string, color: string, mark: string, items: string[]) =>
+    items.length ? (
+      <box style={{ flexDirection: "column", marginTop: 1 }}>
+        <text fg={theme.muted}>{label}</text>
+        {items.map((it, i) => (
+          <box key={i} style={{ flexDirection: "row" }}>
+            <text fg={color} style={{ width: 2, flexShrink: 0 }}>
+              {mark}
+            </text>
+            <text fg={theme.text} style={{ flexGrow: 1, flexShrink: 1 }}>
+              {it}
+            </text>
+          </box>
+        ))}
+      </box>
+    ) : null
+  return (
+    <box style={{ flexDirection: "column", width, flexShrink: 0 }}>
+      <box border borderStyle="rounded" borderColor={COLOR} title={title} titleColor={COLOR} style={{ flexDirection: "column", paddingLeft: 1, paddingRight: 1, backgroundColor: theme.panel }}>
+        {state.phase === "working" ? (
+          <box style={{ flexDirection: "row" }}>
+            <Spinner kind="dots" color={COLOR} />
+            <text fg={theme.muted}>{" Checking your request against this setup: capabilities, systems, project, recent runs…"}</text>
+          </box>
+        ) : state.phase === "error" ? (
+          <text fg={theme.err}>{state.message}</text>
+        ) : (
+          <>
+            <text fg={theme.text}>{state.result.refined}</text>
+            {section("Checked", theme.ok, "✓", state.result.grounded.filter((g) => g.checked).map((g) => g.fact))}
+            {section("Assumed", theme.warn, "~", [...state.result.grounded.filter((g) => !g.checked).map((g) => g.fact), ...state.result.assumed])}
+            {section("Missing — answer these in your request", theme.err, "?", state.result.missing)}
+          </>
+        )}
+      </box>
+      <box style={{ flexDirection: "row", justifyContent: "space-between", height: 1, marginTop: 0 }}>
+        {state.phase === "done" ? (
+          <box style={{ flexDirection: "row" }}>
+            {REFINE_CHOICES.map((c, i) => {
+              const active = i === state.choice
+              return (
+                <box key={c.id} onMouseDown={() => props.onChoose(c.id)} onMouseOver={() => props.onHover(i)} style={{ paddingLeft: 1, paddingRight: 1, marginRight: 1, backgroundColor: active ? COLOR : theme.button }}>
+                  <text fg={active ? theme.onButton : theme.muted}>{c.label}</text>
+                </box>
+              )
+            })}
+          </box>
+        ) : (
+          <text fg={theme.faint}>{state.phase === "working" ? "" : "Your request is back in the prompt."}</text>
+        )}
+        <text>
+          {state.phase === "done" ? (
+            <>
+              <span fg={theme.text}>{"enter"}</span>
+              <span fg={theme.muted}>{" use  "}</span>
+              <span fg={theme.text}>{"e"}</span>
+              <span fg={theme.muted}>{" edit  "}</span>
+              <span fg={theme.text}>{"esc"}</span>
+              <span fg={theme.muted}>{" keep mine"}</span>
+            </>
+          ) : (
+            <>
+              <span fg={theme.text}>{"esc"}</span>
+              <span fg={theme.muted}>{state.phase === "working" ? " cancel" : " close"}</span>
+            </>
+          )}
+        </text>
+      </box>
+    </box>
+  )
+}