@capagents/forgeqe 1.0.4 → 1.0.7

package/src/tui/palette.tsx

@@ -0,0 +1,173 @@
+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" | "wide" | "panels" }
+
+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"; chatWide?: boolean }): 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: "wide", group: "Action", title: opts.chatWide ? "Split view: chat and panels" : "Wide chat: the conversation across the screen", run: { kind: "action", id: "wide" } })
+    if (!opts.chatWide) items.push({ id: "panels", group: "Action", title: "Move to the panels: plan, activity, files", keys: "shift+tab", run: { kind: "action", id: "panels" } })
+  }
+  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>
+  )
+}

package/src/tui/setup.ts

@@ -0,0 +1,37 @@
+import type { AppConfig } from "../config.ts"
+import { MACHINE, requirementGap, type Probes } from "../capabilities/status.ts"
+import type { Requirement } from "../capabilities/registry.ts"
+
+/**
+ * The home screen's setup checklist: the few things most features rest on, each checked the way the capability
+ * registry checks a requirement, so the checklist and /features never disagree.
+ */
+export type SetupItem = {
+  id: "model" | "agent" | "system" | "domain" | "notify"
+  label: string
+  done: boolean
+  /** What is missing, and how to set it up: shown when the item is chosen. */
+  fix?: string
+  /** A command that sets it up, run when the item is chosen. */
+  command?: string
+}
+
+const CHECKS: { id: SetupItem["id"]; label: string; requirement: Requirement; command?: string }[] = [
+  { id: "model", label: "Model", requirement: { kind: "live_model" } },
+  { id: "agent", label: "Coding agent", requirement: { kind: "coding_agent" } },
+  { id: "system", label: "Work items", requirement: { kind: "system", anyOf: ["azure_devops", "jira", "testrail", "zephyr", "qtest", "xray"] }, command: "/auth" },
+  { id: "domain", label: "Domain", requirement: { kind: "domain" } },
+  { id: "notify", label: "Notifications", requirement: { kind: "notify_channels" } },
+]
+
+export function setupChecklist(cfg: AppConfig, probes: Probes = MACHINE): SetupItem[] {
+  return CHECKS.map((c) => {
+    const gap = requirementGap(c.requirement, cfg, probes)
+    return {
+      id: c.id,
+      label: c.label,
+      done: !gap,
+      ...(gap ? { fix: `${c.label}: ForgeQE needs ${gap.missing}. To set it up, ${gap.fix}.`, ...(c.command ? { command: c.command } : {}) } : {}),
+    }
+  })
+}

package/src/tui/suggest.ts

@@ -0,0 +1,111 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+import { adoSettings } from "../cases/ado.ts"
+import { http } from "../cases/http.ts"
+import type { AppConfig } from "../config.ts"
+import type { PaletteItem } from "./palette.tsx"
+
+/**
+ * Suggestions while typing: "/" completes a command, "@" a reference to something real (a recent run, a file in the
+ * repository, an Azure DevOps work item looked up by its id). Nothing is suggested that does not exist.
+ */
+
+export type Suggestion = { kind: "command" | "run" | "file" | "item"; label: string; detail?: string; insert: string }
+
+/** What is being completed: a command at the start of the prompt, or the "@" word being typed at its end. */
+export type Trigger = { kind: "/" | "@"; token: string; start: number }
+
+export function triggerAt(text: string): Trigger | null {
+  if (/^\/\S*$/.test(text)) return { kind: "/", token: text.slice(1), start: 0 }
+  const m = /(^|\s)@(\S*)$/.exec(text)
+  return m ? { kind: "@", token: m[2]!, start: m.index + m[1]!.length } : null
+}
+
+/** The prompt with the trigger's word replaced by the completion, ready for more typing. */
+export function complete(text: string, t: Trigger, insert: string): string {
+  return `${text.slice(0, t.start)}${insert} `
+}
+
+export function commandSuggestions(items: PaletteItem[], token: string): Suggestion[] {
+  const seen = new Set<string>()
+  const out: Suggestion[] = []
+  for (const item of items) {
+    if (item.run.kind !== "command" || seen.has(item.run.text)) continue
+    seen.add(item.run.text)
+    out.push({ kind: "command", label: item.run.text, detail: item.title, insert: item.run.text })
+  }
+  const t = token.toLowerCase()
+  return out.filter((s) => s.label.slice(1).toLowerCase().startsWith(t)).concat(out.filter((s) => !s.label.slice(1).toLowerCase().startsWith(t) && s.label.toLowerCase().includes(t)))
+}
+
+export type RecentRun = { id: string; dir: string; goal: string }
+
+/** The newest run folders (named by their start time) with their goals. */
+export function recentRuns(outDir: string, limit = 8): RecentRun[] {
+  if (!existsSync(outDir)) return []
+  return readdirSync(outDir)
+    .filter((d) => /^\d{8}-\d{6}(-\d+)?$/.test(d))
+    .sort()
+    .reverse()
+    .slice(0, limit)
+    .map((id) => {
+      let goal = ""
+      try {
+        goal = String(JSON.parse(readFileSync(path.join(outDir, id, "run.json"), "utf8")).goal || "")
+      } catch {}
+      return { id, dir: path.join(outDir, id), goal }
+    })
+}
+
+const filesCache = new Map<string, string[]>()
+
+/** The repository's tracked files (git ls-files), once per folder; none outside a git repository. */
+export function repoFiles(cwd: string): string[] {
+  const known = filesCache.get(cwd)
+  if (known) return known
+  const r = spawnSync("git", ["ls-files"], { cwd, encoding: "utf8", maxBuffer: 20_000_000 })
+  const files = r.status === 0 ? r.stdout.split("\n").filter(Boolean).slice(0, 20_000) : []
+  filesCache.set(cwd, files)
+  return files
+}
+
+export type WorkItem = { id: number; title: string; type: string; project: string }
+
+/** What `@` can refer to for the word typed after it. */
+export function referenceSuggestions(token: string, src: { runs: RecentRun[]; files: string[]; item?: WorkItem | null; cwd: string }): Suggestion[] {
+  const t = token.toLowerCase()
+  const out: Suggestion[] = []
+  if (/^\d+$/.test(token)) {
+    if (src.item) out.push({ kind: "item", label: `${src.item.type} ${src.item.id}`, detail: `${src.item.title} · ${src.item.project}`, insert: `Azure DevOps ${src.item.type.toLowerCase()} ${src.item.id} ("${src.item.title}")` })
+    return out
+  }
+  if (!t || "run".startsWith(t) || t.startsWith("run")) {
+    const runs = src.runs.filter((r) => !t.startsWith("run") || t === "run" || r.id.includes(t.slice(3)))
+    for (const [i, r] of runs.entries()) out.push({ kind: "run", label: i === 0 ? "last run" : `run ${r.id}`, detail: r.goal || r.id, insert: `the run in ${path.relative(src.cwd, r.dir) || r.dir}` })
+  }
+  if (t.length >= 2) {
+    const byName = src.files.filter((f) => path.basename(f).toLowerCase().includes(t))
+    const byPath = src.files.filter((f) => !path.basename(f).toLowerCase().includes(t) && f.toLowerCase().includes(t))
+    for (const f of [...byName, ...byPath].slice(0, 8)) out.push({ kind: "file", label: path.basename(f), detail: path.dirname(f) === "." ? "" : path.dirname(f), insert: f })
+  }
+  return out.slice(0, 10)
+}
+
+const itemCache = new Map<number, WorkItem | null>()
+
+/** An Azure DevOps work item's title, type, and project by its id; null when it does not exist or cannot be read. */
+export async function lookupWorkItem(cfg: AppConfig, id: number): Promise<WorkItem | null> {
+  if (itemCache.has(id)) return itemCache.get(id)!
+  let item: WorkItem | null = null
+  try {
+    const { auth, org } = adoSettings(cfg.sources)
+    const { data } = await http<{ id: number; fields: Record<string, unknown> }>(`${org}/_apis/wit/workitems/${id}?fields=System.Title,System.WorkItemType,System.TeamProject&api-version=7.1`, { auth })
+    item = { id: data.id, title: String(data.fields["System.Title"] || ""), type: String(data.fields["System.WorkItemType"] || "Work item"), project: String(data.fields["System.TeamProject"] || "") }
+  } catch {
+    item = null
+  }
+  itemCache.set(id, item)
+  return item
+}

package/src/tui/transcript.tsx

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs"
+import os from "node:os"
 import path from "node:path"
 import { SyntaxStyle } from "@opentui/core"
 
@@ -29,9 +31,11 @@ export type Produced = {
   runs: { runDir: string; status: RunStatus; files: string[] }[]
   suites: { html: string; junit: string }[]
   tests: { runDir: string; result?: CodeResult; error?: string }[]
+  /** Reports write_report saved: the page to open. */
+  reports: { title: string; html: string }[]
 }
 
-export const emptyProduced = (): Produced => ({ runs: [], suites: [], tests: [] })
+export const emptyProduced = (): Produced => ({ runs: [], suites: [], tests: [], reports: [] })
 
 /** Whether passed runs become tests this session, and why not when they don't. */
 export type TestsSetting = { on: boolean; why: string }
@@ -147,7 +151,7 @@ export function SummaryCard({ summary }: { summary: RunSummary }) {
       {summary.savedDir ? (
         <text>
           <span fg={theme.faint}>{"Saved     "}</span>
-          <span fg={theme.muted}>{`${summary.savedDir}/  `}</span>
+          <Linked text={`${summary.savedDir}/  `} color={theme.muted} />
           <span fg={theme.faint}>{summary.savedFiles.join(" · ")}</span>
         </text>
       ) : null}
@@ -155,12 +159,54 @@ export function SummaryCard({ summary }: { summary: RunSummary }) {
   )
 }
 
+/** A web address, or a path with at least one folder: what Linked turns into a link when it exists. */
+const LINKABLE = /(https?:\/\/[^\s)"'<>]+|(?:~|\.{1,2})?\/?[\w.@-]+(?:\/[\w.@-]+)+\/?)/g
+
+/** The target of a link: the address itself, or the file's absolute path; null for a path that does not exist. */
+export function linkTarget(token: string, cwd = process.cwd()): string | null {
+  if (/^https?:\/\//.test(token)) return token
+  const file = token.startsWith("~/") ? path.join(os.homedir(), token.slice(2)) : path.resolve(cwd, token)
+  return existsSync(file) ? `file://${file}` : null
+}
+
+/**
+ * Text whose web addresses and existing file paths can be opened from the terminal (OSC 8 links: cmd/ctrl+click in
+ * VS Code and most terminals). A path that does not exist stays plain text, so no link leads nowhere.
+ */
+export function Linked({ text, color }: { text: string; color: string }) {
+  const parts: { text: string; href?: string }[] = []
+  let at = 0
+  for (const m of text.matchAll(LINKABLE)) {
+    const href = linkTarget(m[0])
+    if (!href) continue
+    if (m.index! > at) parts.push({ text: text.slice(at, m.index) })
+    parts.push({ text: m[0], href })
+    at = m.index! + m[0].length
+  }
+  if (at < text.length) parts.push({ text: text.slice(at) })
+  return (
+    <>
+      {parts.map((p, i) =>
+        p.href ? (
+          <a key={i} href={p.href} fg={theme.accent}>
+            {p.text}
+          </a>
+        ) : (
+          <span key={i} fg={color}>
+            {p.text}
+          </span>
+        ),
+      )}
+    </>
+  )
+}
+
 export function Row({ label, value, color = theme.muted }: { label: string; value: string; color?: string }) {
   if (!value) return null
   return (
     <text>
       <span fg={theme.faint}>{label.padEnd(10)}</span>
-      <span fg={color}>{value}</span>
+      <Linked text={value} color={color} />
     </text>
   )
 }
@@ -257,9 +303,7 @@ export function ResultCard({ card }: { card: Card }) {
       </box>
       {card.body.length ? <box style={{ height: 1 }} /> : null}
       {card.body.map((l, i) => (
-        <text key={i} fg={lineColor(l)}>
-          {l || " "}
-        </text>
+        <text key={i}>{l ? <Linked text={l} color={lineColor(l)} /> : " "}</text>
       ))}
     </box>
   )
@@ -283,6 +327,80 @@ function replyStyle(): SyntaxStyle {
   return style
 }
 
+/** A reply cut into what reads better laid out than wrapped: headings, list items with their depth, and the rest. */
+export type ReplyBlock =
+  | { kind: "heading"; text: string }
+  | { kind: "item"; depth: number; mark: string; text: string }
+  | { kind: "markdown"; text: string }
+
+const ITEM = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/
+
+export function replyBlocks(md: string): ReplyBlock[] {
+  const blocks: ReplyBlock[] = []
+  let rest: string[] = []
+  let fence = false
+  const flush = () => {
+    const text = rest.join("\n").trim()
+    if (text) blocks.push({ kind: "markdown", text })
+    rest = []
+  }
+  for (const line of md.replace(/\r/g, "").split("\n")) {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence
+    const last = blocks.at(-1)
+    if (fence || /^\s*(```|~~~)/.test(line) || /^\s*\|/.test(line)) {
+      rest.push(line)
+      continue
+    }
+    const heading = /^#{1,6}\s+(.*)$/.exec(line)
+    const item = ITEM.exec(line)
+    if (heading) {
+      flush()
+      blocks.push({ kind: "heading", text: heading[1]!.replace(/\*\*/g, "").trim() })
+    } else if (item) {
+      flush()
+      const depth = Math.min(3, Math.floor(item[1]!.replace(/\t/g, "  ").length / 2))
+      const ordered = /\d/.test(item[2]!)
+      blocks.push({ kind: "item", depth, mark: ordered ? item[2]!.replace(")", ".") : depth ? "◦" : "•", text: item[3]! })
+    } else if (line.trim() && /^\s+\S/.test(line) && last?.kind === "item" && !rest.length) {
+      // A list item's continuation line: it belongs to the item, under its text.
+      last.text += ` ${line.trim()}`
+    } else if (!line.trim()) {
+      rest.push(line)
+    } else rest.push(line)
+  }
+  flush()
+  return blocks
+}
+
+/** The agent's reply: headings with room above, list items with their marks in a column so wrapped lines hang under the text. */
+function ReplyBody({ text }: { text: string }) {
+  const blocks = replyBlocks(text)
+  return (
+    <box style={{ flexDirection: "column", flexShrink: 0 }}>
+      {blocks.map((b, i) =>
+        b.kind === "heading" ? (
+          <text key={i} fg={theme.accent} style={{ marginTop: i ? 1 : 0, flexShrink: 0 }}>
+            <strong>{b.text}</strong>
+          </text>
+        ) : b.kind === "item" ? (
+          <box key={i} style={{ flexDirection: "row", flexShrink: 0, paddingLeft: b.depth * 2, marginTop: blocks[i - 1]?.kind === "markdown" ? 1 : 0 }}>
+            <text fg={theme.accent} style={{ width: b.mark.length + 1, flexShrink: 0 }}>
+              {b.mark}
+            </text>
+            <box style={{ flexGrow: 1, flexShrink: 1 }}>
+              <markdown content={b.text} syntaxStyle={replyStyle()} fg={theme.text} conceal />
+            </box>
+          </box>
+        ) : (
+          <box key={i} style={{ marginTop: i ? 1 : 0, flexShrink: 0 }}>
+            <markdown content={b.text} syntaxStyle={replyStyle()} fg={theme.text} conceal tableOptions={{ widthMode: "content", wrapMode: "word" }} />
+          </box>
+        ),
+      )}
+    </box>
+  )
+}
+
 export function TranscriptLine({ line }: { line: Line }) {
   if (line.kind === "card" && line.card) return <ResultCard card={line.card} />
   if (line.kind === "summary" && line.summary) return <SummaryCard summary={line.summary} />
@@ -296,7 +414,7 @@ export function TranscriptLine({ line }: { line: Line }) {
         customBorderChars={BAR}
         style={{ backgroundColor: theme.panel, paddingLeft: 2, paddingRight: 2, paddingTop: 1, paddingBottom: 1, marginTop: 1, marginBottom: 1, flexShrink: 0 }}
       >
-        <markdown content={line.text} syntaxStyle={replyStyle()} fg={theme.text} conceal tableOptions={{ widthMode: "content", wrapMode: "word" }} />
+        <ReplyBody text={line.text} />
       </box>
     )
   }

package/src/usage.ts

@@ -98,7 +98,7 @@ export function usageLine(usage: Usage, cost?: Cost | null): string {
 // The meter: every model session reports here, by role
 // ---------------------------------------------------------------------------------------------
 
-export type Role = "ForgeQE's agent" | "browser agent" | "Scribe" | "reviewer" | "judge"
+export type Role = "ForgeQE's agent" | "browser agent" | "Scribe" | "reviewer" | "judge" | "refiner"
 
 type Entry = { usage: Usage; cost?: Cost; priced: boolean }