@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/lib/session-tool.ts

@@ -0,0 +1,184 @@
+/**
+ * The `session` tool, as the extensions that are not `session-bus` call it.
+ *
+ * `board` and `team` are the user's surface for the team; the bus is the transport
+ * underneath, and neither may import it (`test/structure.test.ts`). So the one place
+ * that turns a call into a typed answer lives here, next to the tool's name in
+ * `lib/tool-names.ts` — two copies would be two copies of the details-shape
+ * knowledge, and a bus that renamed a field would be broken in one of them.
+ *
+ * There are two transports, and the difference is the context, not the caller's
+ * choice: `join` travels as an in-process request on `pi.events` because a *command*
+ * context has no `ctx.executeTool` — the same constraint `lib/plan-entry.ts` exists
+ * for — while `peers` and `send` are nested tool calls, which only ever run inside a
+ * tool. One function either way, so a caller never has to know which it is holding.
+ *
+ * Every function returns a result and none throws: "the bus is not loaded", "a plan
+ * is open", and "that label is taken" are all answers a caller reports, not reasons
+ * to abandon a board write or a card operation that has nothing to do with the bus.
+ *
+ * This module is the *caller* side only. Reading the bus's records from disk is
+ * `session-roster.ts`, which is what works when the bus is not loaded at all.
+ */
+
+import type { ExtensionAPI, ExtensionContext, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { messageOf } from "./errors.ts";
+import { watchingOf } from "./session-roster.ts";
+import { SESSION_TOOL } from "./tool-names.ts";
+
+/**
+ * The `session send` text limit, which is also the longest handoff or offer.
+ *
+ * It is copied from the bus's protocol rather than imported — the dependency runs one
+ * way — and it lives here so `team` and `board` clip to one number instead of two.
+ */
+export const MAX_MESSAGE_TEXT = 4_000;
+
+/** Whether a session is listening for mail, and whether it raises a turn. */
+export interface Watching {
+	armed: boolean;
+	wake: boolean;
+}
+
+/** One session the bus lists. */
+export interface Peer {
+	id: string;
+	label: string;
+	/** Absent when the record does not say, which is not the same as "not listening". */
+	listening?: boolean;
+}
+
+/** What a join did: the label it landed on, and whether mail will reach the session. */
+export type JoinResult = { ok: true; label: string; watching: Watching } | { ok: false; error: string };
+
+/** EventBus channel on which a caller asks `session-bus` to join the team for it. */
+export const TEAM_JOIN_REQUEST = "my-pi-agent/team-join/request";
+
+/** What a caller sends on {@link TEAM_JOIN_REQUEST}. */
+export interface TeamJoinRequest {
+	/** The caller's context; the bus starts and names through it. */
+	ctx: ExtensionContext;
+	/** What to join as and how to listen. */
+	input: { label?: string; wake?: boolean; listen?: boolean };
+	/** Called once, when the bus has answered. */
+	respond(result: JoinResult): void;
+}
+
+/** What a send did. */
+export type SendResult = { ok: true; delivered: string[] } | { ok: false; error: string };
+
+/** One nested call's answer: the details on success, the sentence on failure. */
+type Answer = { details: Record<string, unknown> } | { error: string };
+
+/**
+ * Call the `session` tool once.
+ *
+ * A nested call reports failure in its result rather than by rejecting; a rejection
+ * is still caught, because a bus that is not registered at all throws before the
+ * tool runs and the caller deserves the sentence rather than an exception.
+ */
+async function call(ctx: ExtensionToolContext, args: Record<string, unknown>): Promise<Answer> {
+	const outcome = await ctx.executeTool(SESSION_TOOL, args).catch((error: unknown) => ({
+		isError: true as const,
+		result: { content: [{ type: "text", text: messageOf(error) }], details: undefined },
+	}));
+	if (outcome.isError) return { error: nestedMessage(outcome.result) };
+	const details = outcome.result.details;
+	return { details: typeof details === "object" && details !== null ? (details as Record<string, unknown>) : {} };
+}
+
+/** The message a failed nested call carries, or a sentence that says only that it failed. */
+function nestedMessage(result: { content?: Array<{ type: string; text?: string }> } | undefined): string {
+	const text = result?.content?.find((block) => block.type === "text")?.text;
+	return text !== undefined && text !== "" ? text.replace(/^Error:\s*/, "") : "the session bus did not answer.";
+}
+
+/**
+ * How an extension joins the team, whatever kind of context it is holding.
+ *
+ * Two extensions ask — `board` when the page opens or a card is worked, `team` for
+ * `/team join` — and both hold a command or a tool context, so the request is the one
+ * transport that works from either.
+ */
+export interface TeamJoin {
+	/** Join the team, naming this session when `label` is given. Never throws. */
+	join(ctx: ExtensionContext, label?: string): Promise<JoinResult>;
+}
+
+/** The production join, bound to one extension's `pi`. */
+export function createTeamJoin(pi: Pick<ExtensionAPI, "events" | "getAllTools">): TeamJoin {
+	return {
+		join: (ctx, label) => join(pi, ctx, label === undefined ? {} : { label }),
+	};
+}
+
+/**
+ * Join the team: on the bus, named when a label is given, and listening for mail.
+ *
+ * One call for all three, because that is one act — see `join` in
+ * `extensions/session-bus` — and one transport for both kinds of caller: the request
+ * travels on `pi.events` and the bus answers it.
+ *
+ * With no bus loaded there is no listener, so the answer is the sentence the caller
+ * reports rather than a promise that never settles: the `session` tool's presence is
+ * the same check `lib/plan-entry.ts` makes, and the listener always answers.
+ */
+export async function join(
+	pi: Pick<ExtensionAPI, "events" | "getAllTools">,
+	ctx: ExtensionContext,
+	input: { label?: string; wake?: boolean; listen?: boolean } = {},
+): Promise<JoinResult> {
+	if (!pi.getAllTools().some((tool) => tool.name === SESSION_TOOL)) {
+		return { ok: false, error: "the session bus is not loaded" };
+	}
+	return new Promise<JoinResult>((resolve) => {
+		let settled = false;
+		const respond = (result: JoinResult): void => {
+			if (settled) return;
+			settled = true;
+			resolve(result);
+		};
+		pi.events.emit(TEAM_JOIN_REQUEST, { ctx, input, respond } satisfies TeamJoinRequest);
+	});
+}
+
+/**
+ * Every session the bus lists, or `undefined` when it cannot answer.
+ *
+ * Named `listPeers` rather than `peers` so it cannot be mistaken for a caller's own
+ * formatting helper — `wechat`'s doctor has one — and a caller reads the verb.
+ *
+ * A caller renders "the record does not say" differently from "nobody is here", so a
+ * failed read is not an empty list.
+ */
+export async function listPeers(ctx: ExtensionToolContext): Promise<Peer[] | undefined> {
+	const answer = await call(ctx, { action: "status" });
+	if ("error" in answer) return undefined;
+	const status = answer.details.status;
+	if (typeof status !== "object" || status === null) return undefined;
+	const sessions = (status as { sessions?: unknown }).sessions;
+	if (!Array.isArray(sessions)) return undefined;
+	const peers: Peer[] = [];
+	for (const entry of sessions) {
+		if (typeof entry !== "object" || entry === null) continue;
+		const { id, label, watching } = entry as Record<string, unknown>;
+		if (typeof id !== "string" || typeof label !== "string") continue;
+		const state = watchingOf(watching);
+		peers.push({ id, label, ...(state === undefined ? {} : { listening: state.armed }) });
+	}
+	return peers;
+}
+
+/** Send one message, and report the labels a message file was written for. */
+export async function send(
+	ctx: ExtensionToolContext,
+	input: { kind: "handoff" | "event"; to: string; text: string },
+): Promise<SendResult> {
+	const answer = await call(ctx, { action: "send", kind: input.kind, to: input.to, text: input.text });
+	if ("error" in answer) return { ok: false, error: answer.error };
+	const delivered = answer.details.delivered;
+	return {
+		ok: true,
+		delivered: Array.isArray(delivered) ? delivered.filter((label): label is string => typeof label === "string") : [],
+	};
+}

package/lib/tool-names.ts

@@ -4,8 +4,9 @@
  * Tool names are otherwise owned by the extension that registers the tool, and
  * no extension imports another's modules (see this directory's README). When an
  * orchestrating tool calls another extension's tool through `ctx.executeTool`,
- * or reads another extension's registered parameter schema, the shared name
- * lives here so a rename breaks the build on both sides instead of silently
+ * reads another extension's registered parameter schema, lists the name in a
+ * read-only policy, or passes it on a child's `--tools` allowlist, the shared
+ * name lives here so a rename breaks the build on both sides instead of silently
  * disabling the integration.
  */
 
@@ -31,9 +32,31 @@ export const SUBAGENT_TOOL = "subagent";
  */
 export const ASK_USER_QUESTION_TOOL = "ask_user_question";
 
+/**
+ * The `session` tool. `session-bus` registers it, and `team` calls it through
+ * `ctx.executeTool` to send a handoff, so a rename breaks both sides.
+ */
+export const SESSION_TOOL = "session";
+
 /**
  * Parameter on the `subagent` tool that forces every spawned agent to a
  * read-only tool set. Plan mode sets it on every call while planning, and
  * refuses a `subagent` whose schema does not declare it.
  */
 export const SUBAGENT_READ_ONLY_PARAM = "readOnly";
+
+/**
+ * The `read_doc` tool. `file-read` registers it, and the plan, rewind, and
+ * subagent reader lists carry the name, so the document reader is one reader
+ * everywhere instead of three spellings.
+ */
+export const READ_DOC_TOOL = "read_doc";
+
+/**
+ * The `web_search` tool. `web-access` registers it; plan's and subagent's reader
+ * lists carry the name, so a rename cannot silently drop the web reader.
+ */
+export const WEB_SEARCH_TOOL = "web_search";
+
+/** The `web_fetch` tool, shared the same way as {@link WEB_SEARCH_TOOL}. */
+export const WEB_FETCH_TOOL = "web_fetch";

package/lib/tui/README.md

@@ -35,8 +35,8 @@ Reach for a `lib/tui/` primitive before composing your own: `plainRule` /
 `fitCells` for two columns, `LinePane` for a scrollable log, `ListCursor` /
 `IdCursor` for selection, `byRunningFirst` for a live list's order,
 `DockListScreen` for a list that opens a pane, `TailResult` for a tool result
-that lists rows or tails output, `screenFooter` for a screen's own last three
-rows, and `ConfirmState` before a destructive action.
+that lists rows, heads several row sections, or tails output, `screenFooter` for a
+screen's own last three rows, and `ConfirmState` before a destructive action.
 
 ## Docked list screens
 
@@ -81,6 +81,20 @@ what a plain list wants — do not hand-roll the frame to get one of them:
   (`c` collect, `x` cancel). Return `true` for the keys it claimed; everything
   else falls through to the pane's scroll keys.
 
+A pane is a log by default: it opens at the tail and its subtitle says
+`following` or `paused`. Two more fields cover the other body:
+
+- `DetailContents.text` — prose instead of `lines`, wrapped to the width the pane
+  renders at and re-wrapped on a resize. One source line is one paragraph; a blank
+  line stays blank. `lines` remains the right shape for output that is already
+  split.
+- `DetailContents.tail: false` — a prose or list pane opens at the top and never
+  claims to follow anything. Leave it out for a log.
+
+A screen whose list is one of several scopes overrides `headerLabel()` (the
+header rule's name) and `emptyLabel()` (the empty-list line), so `Tab` can change
+what is listed without a second renderer; both default to the screen's options.
+
 A destructive action asks through [`confirm.ts`](./confirm.ts):
 `ConfirmState.ask(prompt, accept)` holds the question, `resolve(data)` accepts on
 `y`/`Y`/Enter, dismisses on `n`/`N`/Esc/`q`, and returns `undefined` for any

package/lib/tui/dock-screen.ts

@@ -20,11 +20,13 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { detailBlockRows, dockListFrame, screenHint, type ScreenHint, type ViewportRowsSource } from "./chrome.ts";
 import { clip, fitCells } from "./columns.ts";
 import { ConfirmState } from "./confirm.ts";
 import { fitRows, formatRange, IdCursor, isCloseKey, navIntent, wheelDelta } from "./cursor.ts";
 import { SEPARATORS } from "./glyphs.ts";
+import { BODY_INDENT } from "./indent.ts";
 import { LinePane } from "./line-pane.ts";
 import { emptyState } from "./rows.ts";
 import { titleRule } from "./rules.ts";
@@ -43,12 +45,23 @@ const DETAIL_CHROME_ROWS = 6;
 export interface DetailContents {
 	/** Pane title, e.g. `j1 build`. */
 	title: string;
-	/** The body lines, already sanitized by the caller. */
-	lines: string[];
+	/** The body lines, already sanitized by the caller. Omit for a `text` pane. */
+	lines?: string[];
+	/**
+	 * Prose body, built once at open and wrapped to the render width on every
+	 * frame. Takes precedence over `lines`. A resize re-wraps; a blank line in the
+	 * source stays a blank line in the pane.
+	 */
+	text?: string;
 	/** More lines exist above the ones supplied. */
 	more?: boolean;
 	/** Subtitle under the title, e.g. the log file path. */
 	subtitle?: string;
+	/**
+	 * Whether the pane follows its tail. Default true, which is a log's behavior;
+	 * false opens a prose or list pane at the top and never says `following`.
+	 */
+	tail?: boolean;
 	/**
 	 * Rows above the scrollable body that depend on the width: key/value facts,
 	 * a legend, a divider. Read fresh every frame with the live width and already
@@ -101,6 +114,9 @@ export abstract class DockListScreen<T> implements Component {
 	private readonly confirmState = new ConfirmState();
 	private feedback: string | undefined;
 	private detailFacts: ((width: number) => string[]) | undefined;
+	/** Prose body for the open pane, wrapped to the width it is rendered at. */
+	private detailText: string | undefined;
+	private detailWrap: { width: number; lines: string[] } | undefined;
 
 	constructor(protected readonly options: DockListScreenOptions) {}
 
@@ -163,6 +179,19 @@ export abstract class DockListScreen<T> implements Component {
 		this.options.requestRender();
 	}
 
+	/**
+	 * The header rule's label. A screen whose list is one of several scopes
+	 * overrides it, so the rule names what is on screen.
+	 */
+	protected headerLabel(): string {
+		return this.options.title;
+	}
+
+	/** The empty-list line; a screen whose scopes differ overrides it. */
+	protected emptyLabel(): string {
+		return this.options.emptyList;
+	}
+
 	/** Show one line of feedback in place of the hints. */
 	protected notify(text: string): void {
 		this.feedback = text;
@@ -182,6 +211,12 @@ export abstract class DockListScreen<T> implements Component {
 		// Facts stay with the pane unless this update supplies its own, so a poll that
 		// only refreshes the body cannot drop the facts the row opened with.
 		if (contents.facts) this.detailFacts = contents.facts;
+		// `text` and `tail` belong to the row that opened the pane; an update either
+		// replaces the prose or settles the pane back onto a line buffer.
+		if (contents.text !== undefined || contents.lines !== undefined) {
+			this.detailText = contents.text;
+			this.detailWrap = undefined;
+		}
 		const changed =
 			contents.subtitle === undefined
 				? this.pane.update({ title: contents.title, lines: contents.lines, more: contents.more })
@@ -201,6 +236,7 @@ export abstract class DockListScreen<T> implements Component {
 
 	/** Re-read the open detail pane, so a poll cannot show stale lines. */
 	refreshDetail(id: string): void {
+		if (this.detailText !== undefined) return;
 		const source = this.detailById?.(id);
 		if (source && this.pane.update({ lines: source.lines, more: source.more })) this.options.requestRender();
 	}
@@ -242,10 +278,30 @@ export abstract class DockListScreen<T> implements Component {
 		const contents = this.detailFor(row);
 		this.mode = "detail";
 		this.detailFacts = contents.facts;
-		this.pane.open(this.idOf(row), contents);
+		this.detailText = contents.text;
+		this.detailWrap = undefined;
+		this.pane.open(
+			this.idOf(row),
+			{
+				title: contents.title,
+				lines: contents.text === undefined ? (contents.lines ?? []) : [],
+				more: contents.more,
+				subtitle: contents.subtitle,
+			},
+			contents.tail ?? true,
+		);
 		this.options.requestRender();
 	}
 
+	/** Leave detail mode and drop everything that belonged to the open row. */
+	private closeDetail(): void {
+		this.mode = "list";
+		this.pane.close();
+		this.detailFacts = undefined;
+		this.detailText = undefined;
+		this.detailWrap = undefined;
+	}
+
 	private handleListKey(data: string): void {
 		if (isCloseKey(data) || data === "q") {
 			this.options.onClose();
@@ -294,9 +350,7 @@ export abstract class DockListScreen<T> implements Component {
 
 	private handleDetailKey(data: string): void {
 		if (matchesKey(data, Key.escape) || matchesKey(data, Key.backspace) || data === "q") {
-			this.mode = "list";
-			this.pane.close();
-			this.detailFacts = undefined;
+			this.closeDetail();
 			this.options.requestRender();
 			return;
 		}
@@ -307,11 +361,11 @@ export abstract class DockListScreen<T> implements Component {
 	}
 
 	/** The footer: a pending confirmation, one line of feedback, or the hints. */
-	private hint(width: number, rows: readonly T[]): string {
+	private footer(width: number, hints: ScreenHint[]): string {
 		const pending = this.confirmState.pending;
 		if (pending) return clip(`  ${paint(this.theme, "warn", pending.prompt)}`, width);
 		if (this.feedback) return clip(`  ${paint(this.theme, "meta", this.feedback)}`, width);
-		return screenHint(this.theme, width, this.listHints(rows));
+		return screenHint(this.theme, width, hints);
 	}
 
 	private summary(rows: readonly T[], width: number): string {
@@ -343,7 +397,7 @@ export abstract class DockListScreen<T> implements Component {
 		const body: string[] = [];
 		let range: string | undefined;
 		if (rows.length === 0) {
-			body.push(...emptyState(this.theme, w, { label: this.options.emptyList }));
+			body.push(...emptyState(this.theme, w, { label: this.emptyLabel() }));
 		} else {
 			const end = Math.min(rows.length, this.cursor.scroll + this.cursor.visible);
 			for (let i = this.cursor.scroll; i < end; i++) body.push(this.rowLine(rows[i], w, i === index));
@@ -355,12 +409,12 @@ export abstract class DockListScreen<T> implements Component {
 		return dockListFrame({
 			theme: this.theme,
 			width: w,
-			header: titleRule(this.theme, w, this.options.title),
+			header: titleRule(this.theme, w, this.headerLabel()),
 			summary: this.summary(rows, w),
 			body,
 			range,
 			detail: block.map((line) => clip(`  ${paint(this.theme, "meta", line)}`, w)),
-			hint: this.hint(w, rows),
+			hint: this.footer(w, this.listHints(rows)),
 		});
 	}
 
@@ -368,6 +422,7 @@ export abstract class DockListScreen<T> implements Component {
 		this.syncDetail();
 		// A live pane whose row is gone has already closed itself: draw the list.
 		if (this.mode !== "detail") return this.renderList(w);
+		this.syncText(w);
 		const facts = this.detailFacts ? this.detailFacts(w) : [];
 		const visible = fitRows(
 			this.options.viewportRowsSource,
@@ -397,14 +452,15 @@ export abstract class DockListScreen<T> implements Component {
 			summary: clip(`  ${paint(this.theme, "faint", this.pane.subtitleLine())}`, w),
 			body,
 			range,
-			hint: screenHint(this.theme, w, this.detailHints(this.detailRow)),
+			hint: this.footer(w, this.detailHints(this.detailRow)),
 		});
 	}
 
 	/**
 	 * Re-read a live pane in place. This runs inside a render, so it must not ask
 	 * for another frame; a source that disappeared closes the pane instead of
-	 * showing lines the list no longer has a row for.
+	 * showing lines the list no longer has a row for. A prose pane is skipped here:
+	 * `syncText` owns its lines, and this still closes it when the row is gone.
 	 */
 	private syncDetail(): void {
 		if (!this.liveDetail()) return;
@@ -412,11 +468,23 @@ export abstract class DockListScreen<T> implements Component {
 		if (!id) return;
 		const source = this.detailById?.(id);
 		if (!source) {
-			this.mode = "list";
-			this.pane.close();
-			this.detailFacts = undefined;
+			this.closeDetail();
 			return;
 		}
-		this.pane.update({ lines: source.lines, more: source.more });
+		if (this.detailText === undefined) this.pane.update({ lines: source.lines, more: source.more });
+	}
+
+	/**
+	 * Wrap a prose body to the width the pane actually renders at, once per width.
+	 * The pane's body lines are built at open, so this is the one source that can
+	 * follow a resize.
+	 */
+	private syncText(width: number): void {
+		if (this.detailText === undefined) return;
+		const inner = Math.max(1, width - BODY_INDENT);
+		if (this.detailWrap?.width === inner) return;
+		const lines = this.detailText.split("\n").flatMap((line) => (line === "" ? [""] : wrapTextWithAnsi(line, inner)));
+		this.detailWrap = { width: inner, lines };
+		this.pane.update({ lines });
 	}
 }

package/lib/tui/glyphs.ts

@@ -30,6 +30,7 @@ export const GLYPHS = {
 	jobsFailure: "✗",
 	stopped: "⊘",
 	browse: "◉",
+	board: "▤",
 	delegation: "↳",
 	wechat: "✆",
 	gaugeFull: "▰",
@@ -71,6 +72,7 @@ export const STATUS_KEYS = {
 	watch: "watch",
 	watchMatches: "watch-matches",
 	browse: "browse",
+	board: "board",
 	rewind: "rewind",
 	agents: "agents",
 	wechat: "wechat",

package/lib/tui/line-pane.ts

@@ -45,6 +45,11 @@ export class LinePane {
 	visible = 1;
 	/** Whether the view is parked at the tail; set false once the user scrolls up. */
 	follow = true;
+	/**
+	 * Whether this pane follows its tail. A log does; a prose or list pane does not:
+	 * it opens at the top and never reports `following`/`paused`.
+	 */
+	tail = true;
 
 	private buffer: string[] = [];
 	private label = "";
@@ -66,16 +71,21 @@ export class LinePane {
 		return Math.max(0, this.buffer.length - this.visible);
 	}
 
-	/** Open the pane on a row, reset to the tail. */
-	open(id: string, source: PaneSource): void {
+	/** Open the pane on a row, reset to the tail for a log, or to the top for prose. */
+	open(id: string, source: PaneSource, tail = true): void {
 		this.id = id;
 		this.buffer = [];
 		this.label = "";
 		this.subtitle = undefined;
 		this.more = false;
 		this.scroll = 0;
-		this.follow = true;
+		this.tail = tail;
+		this.follow = tail;
 		this.update(source);
+		if (!tail) {
+			this.follow = false;
+			this.scroll = 0;
+		}
 	}
 
 	/** Close the pane and drop its buffer. */
@@ -87,6 +97,7 @@ export class LinePane {
 		this.more = false;
 		this.scroll = 0;
 		this.follow = true;
+		this.tail = true;
 	}
 
 	/**
@@ -127,7 +138,7 @@ export class LinePane {
 		const parts: string[] = [];
 		if (this.subtitle) parts.push(this.subtitle);
 		if (this.more && this.buffer.length > 0) parts.push(`showing last ${this.buffer.length} lines`);
-		if (this.buffer.length > 0) parts.push(this.follow ? "following" : "paused");
+		if (this.tail && this.buffer.length > 0) parts.push(this.follow ? "following" : "paused");
 		return parts.join(" · ");
 	}
 

package/lib/tui/tool.ts

@@ -200,18 +200,29 @@ export function earlierHint(theme: Theme, hidden: number, label: string): string
 /** The row renderer a {@link TailResult} list uses: the extension's row grammar at a width. */
 export type TailRowLine<Row> = (row: Row, width: number, theme: Theme) => string;
 
-/** What a {@link TailResult} draws: the caller's rows plus a hidden count, or a bounded tail. */
+/** One group of rows inside a {@link TailResult}, under an optional faint heading. */
+export interface TailSection<Row> {
+	/** A faint heading above the rows, e.g. `Claims`; omit for the block's primary list. */
+	label?: string;
+	rows: readonly Row[];
+	more: number;
+	rowLine: TailRowLine<Row>;
+}
+
+/** What a {@link TailResult} draws: the caller's rows plus a hidden count, a headed row list, or a bounded tail. */
 export type TailResultInput<Row> =
 	| { kind: "list"; rows: readonly Row[]; more: number; rowLine: TailRowLine<Row> }
+	| { kind: "sections"; sections: readonly TailSection<Row>[] }
 	| { kind: "lines"; lines: readonly string[]; earlier: number; earlierLabel: string };
 
 /**
  * The transcript result block a tool that lists rows or tails output shares.
  *
  * One leading blank line per the block grammar, then either the caller's rows
- * (already ordered and capped) with a "more" note, or the themed tail with an
- * "earlier" note. The caller owns the row renderer, so the extension's own row
- * grammar — a peer-session tag, a status glyph — stays with its vocabulary.
+ * (already ordered and capped) with a "more" note, one headed group of rows per
+ * section, or the themed tail with an "earlier" note. The caller owns the row
+ * renderer, so the extension's own row grammar — a peer-session tag, a status
+ * glyph — stays with its vocabulary.
  */
 export class TailResult<Row> implements Component {
 	private input: TailResultInput<Row>;
@@ -239,6 +250,14 @@ export class TailResult<Row> implements Component {
 			if (input.more > 0) lines.push(clip(`  ${overflowHint(this.theme, input.more)}`, w));
 			return lines;
 		}
+		if (input.kind === "sections") {
+			for (const section of input.sections) {
+				if (section.label) lines.push(clip(paint(this.theme, "faint", section.label), w));
+				for (const row of section.rows) lines.push(section.rowLine(row, w, this.theme));
+				if (section.more > 0) lines.push(clip(`  ${overflowHint(this.theme, section.more)}`, w));
+			}
+			return lines;
+		}
 		if (input.earlier > 0) lines.push(clip(earlierHint(this.theme, input.earlier, input.earlierLabel), w));
 		for (const line of input.lines) lines.push(this.theme.fg("toolOutput", clip(line, w)));
 		return lines;

package/lib/web/README.md

@@ -3,7 +3,7 @@
 The tokens, base rules, app shell, `bf-*` components, HTML atoms, and client
 runtime the two loopback pages draw with: the plan review
 ([`../../extensions/plan/web-page.ts`](../../extensions/plan/web-page.ts)) and
-file browse ([`../../extensions/file-browse/styles.ts`](../../extensions/file-browse/styles.ts)).
+file browse ([`../../extensions/file-browse/view/styles.ts`](../../extensions/file-browse/view/styles.ts)).
 The module-by-module inventory is the `web/` row of [`../README.md`](../README.md);
 this file is the conventions those modules exist to make easy.
 
@@ -34,7 +34,10 @@ are computed rather than mapped:
 - `--scrim` and `--shadow` — per appearance, because a dimming layer and a lifted
   panel need their own alpha rather than a palette entry.
 
-Components read tokens only: no literal hex or `rgba()` in `components.ts`, and a
+`--raised` is the one derived neutral: `--surface` mixed 6% (dark) or 3% (light)
+toward `--text`, for a block that has to read as a plane above the page rather than
+as an outline — the light step is smaller because a darker accent on a lighter step
+falls below AA. Components read tokens only: no literal hex or `rgba()` in `components.ts`, and a
 test fails one. Contrast is asserted, not assumed — text, muted, and accent at
 4.5:1 on both surfaces, the primary label at 4.5:1 on the accent fill, `--dim` at
 3:1 because it carries the line-number gutter, and the status colours at 3:1.

package/lib/web/components.ts

@@ -18,6 +18,8 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-btn:hover{border-color:var(--accent);color:var(--accent);text-decoration:none}
 .bf-btn[aria-pressed="true"]{border-color:var(--accent);color:var(--accent);background:var(--accent-soft)}
 .bf-btn--primary{background:var(--accent);border-color:var(--accent);color:var(--on-accent)}
+.bf-btn--danger{border-color:var(--danger);color:var(--danger)}
+.bf-btn--danger:hover{border-color:var(--danger);background:var(--danger);color:var(--on-accent)}
 .bf-btn--primary:hover{filter:brightness(1.06);color:var(--on-accent)}
 .bf-btn--ghost{border-color:transparent;background:none;padding:0;font:inherit;color:inherit}
 .bf-btn--ghost:hover{color:var(--accent)}
@@ -36,6 +38,9 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-segmented__item[aria-current="page"],.bf-segmented__item[aria-pressed="true"]{background:var(--accent-soft);color:var(--accent)}
 .bf-input{border:0;background:transparent;color:var(--text);font:var(--fs-sm) var(--font-mono);width:100%;outline:none}
 .bf-field{display:flex;align-items:center;gap:var(--space-1);background:var(--canvas);border:1px solid var(--border);border-radius:var(--radius-md);padding:var(--space-1) var(--space-2);color:var(--muted);font-size:var(--fs-sm)}
+/* The field is the control: ringing the input inside it drew a border within a border. */
+.bf-field:focus-within{outline:var(--focus-ring) solid var(--accent);outline-offset:2px}
+.bf-field .bf-input:focus-visible{outline:none}
 .bf-textarea{width:100%;min-height:72px;padding:var(--space-2);font:inherit;color:var(--text);background:var(--canvas);border:1px solid var(--border);border-radius:var(--radius-md);resize:vertical}
 .bf-panel{min-width:0;overflow:auto;overscroll-behavior:contain}
 .bf-panel__summary{display:none}
@@ -60,7 +65,7 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-dialog mark{background:transparent;color:var(--warn);font-weight:var(--fw-semibold)}
 .bf-dialog__head{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-3) var(--space-4);border-bottom:1px solid var(--border)}
 .bf-dialog__head h2{margin:0;font-size:var(--fs-lg)}
-.bf-dialog__body{padding:var(--space-3) var(--space-4);font-size:var(--fs-sm);line-height:var(--lh-relaxed)}
+.bf-dialog__body{padding:var(--space-3) var(--space-4);font-size:var(--fs-sm);line-height:var(--lh-relaxed);overflow:auto;min-height:0}
 .bf-dialog__body p{margin:0 0 var(--space-2)}
 .bf-dialog__body p:last-child{margin:0}
 .bf-dialog__hint{color:var(--muted)}

package/lib/web/runtime.ts

@@ -123,9 +123,15 @@ export function dialogScript(options: DialogOptions): string {
   // A button inside a closed dialog has no boxes, so the rects are the test that
   // survives a hidden attribute, a collapsed panel, and a stylesheet swap alike.
   function focusables() {
-    return Array.prototype.filter.call(dialog.querySelectorAll('${FOCUSABLE}'), function (node) {
+    var nodes = Array.prototype.filter.call(dialog.querySelectorAll('${FOCUSABLE}'), function (node) {
       return node.getClientRects && node.getClientRects().length > 0;
     });
+    // A panel that names itself focusable is where focus lands on open, so the close
+    // button is not the first thing a dialog says with its ring. It stays first in the
+    // list, which is what keeps Shift+Tab wrapping inside instead of escaping the scrim.
+    var panel = dialog.querySelector('[role="dialog"][tabindex]');
+    if (panel && panel.getClientRects && panel.getClientRects().length > 0) nodes.unshift(panel);
+    return nodes;
   }
   function toggle(force) {
     var open = force === undefined ? dialog.hidden : force;