@gavin-hu/my-pi-agent 0.16.0 → 0.18.0

package/extensions/context/tui.ts

@@ -16,7 +16,7 @@ import type { CompactionResult, Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
 import { messageOf } from "../../lib/errors.ts";
 import { formatTokens } from "../../lib/format.ts";
-import { screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { screenFooter, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
 import { ConfirmState } from "../../lib/tui/confirm.ts";
 import { clampScroll, fitRows, formatRange, isCloseKey, navigateScroll } from "../../lib/tui/cursor.ts";
 import { gaugeBar, gaugeRole } from "../../lib/tui/gauge.ts";
@@ -26,7 +26,7 @@ import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import { formatBudget, formatCompaction, formatDrift } from "./format.ts";
 import type { ContextBucket, ContextReport } from "./types.ts";
 
-/** Fixed rows around the scrollable body: title, gauge, budget, blank, blank, footer, blank. */
+/** Fixed rows around the scrollable body: title, gauge, budget, blank, blank, footer, closing rule. */
 const CHROME_ROWS = 7;
 
 /** Cells in the composition bar. */
@@ -137,16 +137,28 @@ export class ContextComponent implements Component {
 		const { percent, tokens, window } = this.report;
 		if (window <= 0) return truncateToWidth(`  ${paint(this.theme, "meta", "no model context window")}`, width);
 		const role = gaugeRole(percent);
+		// The bar and the printed percentage come from one rounded value, so a
+		// label reading `0%` can never sit beside a filled cell. The tone stays on
+		// the exact percent, so the warn and danger thresholds do not move.
+		const shown = percent === null ? null : Math.round(percent);
 		const value = tokens === null ? `? / ${formatTokens(window)}` : `${formatTokens(tokens)} / ${formatTokens(window)}`;
-		const bar = gaugeBar(this.theme, { percent, blocks: 10 });
-		const label = percent === null ? "unknown" : `${Math.round(percent)}%`;
+		const bar = gaugeBar(this.theme, { percent: shown, blocks: 10 });
+		const label = shown === null ? "unknown" : `${shown}%`;
 		return truncateToWidth(`  ${paint(this.theme, role, value)}  ${bar}  ${paint(this.theme, role, label)}`, width);
 	}
 
+	/** The composition header: the denominator the percent column is a share of. */
+	private compositionLine(width: number): string {
+		const label = paint(this.theme, "label", "Composition");
+		const total = paint(this.theme, "meta", `${formatTokens(this.report.estimate)} estimate`);
+		const full = `  ${label} · ${total}`;
+		return visibleWidth(full) <= width ? full : truncateToWidth(`  ${label}`, width);
+	}
+
 	/** One composition row; optional columns drop as the terminal narrows. */
 	private bucketLine(bucket: ContextBucket, width: number): string {
 		const indent = " ".repeat(bucket.depth > 0 ? 4 : 2);
-		const labelWidth = bucket.depth > 0 ? 16 : 18;
+		const labelWidth = bucket.depth > 0 ? 20 : 22;
 		const label = padCell(bucket.label, labelWidth);
 		const tokens = formatTokens(bucket.tokens).padStart(6);
 		const share = shareCell(bucket.share);
@@ -167,13 +179,17 @@ export class ContextComponent implements Component {
 		return truncateToWidth(head, width);
 	}
 
-	/** The scrollable body: composition, drift, compaction, and the largest blocks. */
+	/** The scrollable body: composition, drift, compaction, and the largest messages. */
 	private buildBody(width: number): string[] {
 		const report = this.report;
-		const lines: string[] = report.buckets.map((bucket) => this.bucketLine(bucket, width));
+		const lines: string[] = [];
+		if (report.buckets.length > 0) {
+			lines.push(this.compositionLine(width));
+			for (const bucket of report.buckets) lines.push(this.bucketLine(bucket, width));
+		}
 
 		const drift = formatDrift(report);
-		if (drift) lines.push("", truncateToWidth(`  ${paint(this.theme, "warn", drift)}`, width));
+		if (drift) lines.push("", truncateToWidth(`  ${paint(this.theme, "meta", drift)}`, width));
 
 		lines.push(
 			"",
@@ -184,7 +200,7 @@ export class ContextComponent implements Component {
 		);
 
 		if (report.largest.length > 0) {
-			lines.push("", `  ${paint(this.theme, "label", "Largest blocks")}`);
+			lines.push("", `  ${paint(this.theme, "label", "Largest messages")}`);
 			for (const block of report.largest) {
 				const tokens = formatTokens(block.tokens).padStart(6);
 				const role = padCell(block.role, 11);
@@ -230,7 +246,7 @@ export class ContextComponent implements Component {
 		if (this.body.length > this.visible) {
 			lines.push(formatRange(this.theme, w, { start: this.scroll, end, total: this.body.length }));
 		}
-		lines.push("", this.footerLine(w), "");
+		lines.push(...screenFooter(this.theme, w, this.footerLine(w)));
 		return lines.map((line) => truncateToWidth(line, w));
 	}
 

package/extensions/context/types.ts

@@ -79,7 +79,7 @@ export interface CompactionHistory {
 	last: CompactionSummary | null;
 }
 
-/** One of the largest single blocks in the projected context. */
+/** One of the largest single messages in the projected context. */
 export interface LargestBlock {
 	/** Estimated tokens. */
 	tokens: number;
@@ -99,7 +99,7 @@ export interface ContextReport {
 	percent: number | null;
 	/** `window - tokens`, `null` when `tokens` is unknown. */
 	free: number | null;
-	/** `window - reserve - tokens`, `null` when `tokens` is unknown. */
+	/** `window - reserve - tokens`, `null` when `tokens` is unknown or automatic compaction is off. */
 	headroom: number | null;
 	/** The resolved `reserveTokens` for the active model. */
 	reserve: number;
@@ -115,8 +115,10 @@ export interface ContextReport {
 	estimate: number;
 	/** `tokens - estimate` when the host's estimate is known, else `null`. */
 	drift: number | null;
+	/** True when the projection holds no assistant message: Pi's total is its message-only fallback. */
+	beforeFirstReply: boolean;
 	/** The branch's compaction history. */
 	compaction: CompactionHistory;
-	/** The largest projected blocks, biggest first. */
+	/** The largest projected messages, biggest first. */
 	largest: LargestBlock[];
 }

package/extensions/file-browse/README.md

@@ -56,8 +56,9 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   external images are shown as links rather than fetched.
 - **Sortable listings.** The Name / Size / Modified headers sort the current
   directory, directories first, and the choice is remembered per browser.
-- **Copy and wrap.** Copy a file's root-relative path or its contents, and
-  toggle line wrapping for text and raw views.
+- **Copy and wrap.** Copy a file's root-relative path or its contents, copy a
+  `path:12-30` reference for the lines you selected, and toggle line wrapping for
+  text and raw views.
 - **Theme toggle.** A header button switches between the dark and light
   palettes and remembers the choice per browser; until it is used, the palette
   follows the system `prefers-color-scheme`.
@@ -66,7 +67,8 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   highlighted match; Enter opens the file.
 - **Keyboard.** `/` or `Ctrl/Cmd+K` opens quick open, `-` folds or expands
   every folder in the tree, `u` toggles line wrapping, `r` switches rendered and
-  raw Markdown, `n`/`p` step between a diff's hunks, and `?` opens a shortcut
+  raw Markdown, `y` copies a reference to the selected lines, `n`/`p` step
+  between a diff's hunks, and `?` opens a shortcut
   sheet. A diff's hunk headers pin to the top of the code viewport while its
   body scrolls.
 - **Read-only and loopback-scoped.** No editing, no writing, no LAN exposure.
@@ -88,11 +90,13 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   connecting (accent), stalled (amber, after three missed frames), or offline
   (red); the branch chip, the `● N changes +A −D` chip, and the change markers in
   the tree and the listing update in place; and the footer line reports `up 2m
-  14s · 37 requests`. The chip names its state and never counts, so nothing is
-  repainted between frames. One Server-Sent Events stream per page carries it, on
-  the same loopback server, so nothing extra is opened and nothing is written;
-  that stream is also how the server notices the last page closing its window,
-  after which it stops listening.
+  14s · 37 requests`. The chip names its state and never counts, and a frame
+  whose change set did not move repaints nothing at all. One Server-Sent Events
+  stream per page carries it, on the same loopback server, so nothing extra is
+  opened and nothing is written; that stream is also how the server notices the
+  last page closing its window, after which it stops listening. A page that lists
+  a folder also checks that folder, and offers a `⟳ reload` control when a file
+  has appeared or gone on disk since it drew its rows.
 - **No dependencies.** `node:http` plus the inline sprite, CSS, and client
   script.
 
@@ -136,10 +140,24 @@ errors. The chip names its state rather than counting, so it is repainted only
 when that state changes. The same frame carries the branch (or detached head), the
 uncommitted-change totals and paths, the server's uptime, and the requests it
 has answered, so the branch chip, the changes chip, the markers, and the footer
-line are painted from one snapshot rather than four requests. Losing the stream
-leaves everything the page last showed in place: it is read-only, so a stale
-label is never a stale action. `"live": false` turns the whole surface off — no
-chip, no stream, no `/events` route — and so does JavaScript off.
+line are painted from one snapshot rather than four requests. Each change set
+also carries a short revision, and a frame whose revision the page already
+painted does no work at all — so an idle tree costs no DOM, however many rows the
+page drew. Losing the stream leaves everything the page last showed in place: it
+is read-only, so a stale label is never a stale action. `"live": false` turns the
+whole surface off — no chip, no stream, no `/events` route — and so does
+JavaScript off.
+
+A page that lists a folder carries the revision of the names it drew, and asks
+`/api/dir-rev` for the folder's current one on the frame cadence — one directory
+read every five seconds by default, skipped while the tab is hidden and stopped
+for good once it has an answer. A difference reveals `⟳ reload` beside the live
+chip, which reloads the page; the rows themselves are never touched, because a
+page that could grow a row is a page that writes. A folder whose listing was
+truncated, and a file, `/diff`, or error page, has nothing to compare and shows
+no control. At most eight pages may hold the stream at once: a ninth is refused
+and its chip reads `offline`, which keeps one local page from pinning the server
+— and the git read behind each frame — alive.
 
 The stream is also how the server knows a page is still there: when the last one
 leaves, the port is released after ten seconds and the chip is cleared, because
@@ -147,6 +165,32 @@ nothing is left to serve. That is why a page with JavaScript off — or with liv
 status off — never counts as a reader, and the server then waits for
 `/browse stop` or the end of the session.
 
+### The page
+
+The page is keyboard-first, and the tree is one tab stop rather than two per
+folder:
+
+| Key | What it does in the tree |
+|---|---|
+| `↑` / `↓` | Move between the rows on screen |
+| `→` | Open a folder (reading its children first if needed), or enter it |
+| `←` | Close the folder, or step out to its parent |
+| `Space` | Open or close the focused folder |
+| `Enter` | Follow the focused row's link |
+| `Home` / `End` | First or last row on screen |
+
+The folder's own link carries `aria-expanded`, so a screen reader hears its
+state once; the twisty beside it is a pointer control kept out of the tab order.
+A mouse click moves the tab stop to that row, so `Tab` comes back to where you
+were. Elsewhere the page keeps its own keys: `/` or `Ctrl`/`Cmd`+`K` for quick
+open, `-` to fold, `u` to wrap, `r` for raw Markdown, `n`/`p` between diff hunks,
+and `?` for the sheet, whose dialog now traps `Tab` and returns focus to its
+button.
+
+Printing is supported: the paper gets the light palette whatever the screen is
+showing, the chrome and the tree are dropped, and a file or diff prints whole
+instead of inside its scroll box.
+
 ## Routes
 
 | Route | Result |
@@ -186,7 +230,7 @@ document and the project document (project wins):
   "diffContext": 3,          // unified diff context lines
   "maxDiffLines": 4000,      // diff lines rendered before truncation
   "live": true,              // stream live status to open pages
-  "liveIntervalMs": 3000     // ms between status frames while a page is connected
+  "liveIntervalMs": 5000     // ms between status frames while a page is connected
 }
 ```
 
@@ -223,11 +267,18 @@ document and the project document (project wins):
   attributes; only the fixed `tok-*` class names reach the page.
 - **Event stream.** `/events` is a `GET` on the same loopback server, behind
   the same method and `Host` checks, and it only reads: the frame is the branch,
-  the change paths, an uptime, and a request count, all of which the page it
-  feeds already renders. It carries no page policy (`text/event-stream` is not a
-  document), sends `Cache-Control: no-store`, and cannot be cached or replayed.
-  A tick runs only while a page is attached, and the timer is `unref`ed, so an
-  idle server does no work and a forgotten tab cannot hold the process open.
+  the change paths and their revision, an uptime, and a request count, all of
+  which the page it feeds already renders. It carries no page policy
+  (`text/event-stream` is not a document), sends `Cache-Control: no-store`, and
+  cannot be cached or replayed. A tick runs only while a page is attached, and
+  the timer is `unref`ed, so an idle server does no work and a forgotten tab
+  cannot hold the process open. At most eight pages may attach; a ninth is
+  answered `204`, the one status an event source never reconnects after.
+- **Directory check.** `/api/dir-rev` answers one folder's listing revision, so
+  the page can tell whether its rows are stale. It goes through the same path
+  guard as every other route and reads one directory; its answer is a hash of the
+  names, not the names themselves, so it discloses nothing the page above it does
+  not already show.
 - **Caps.** `maxFileBytes` (inline rendering), `maxTextLines` (rendered lines),
   `maxThumbBytes` (thumbnails), and `maxDirEntries` (listings) bound every read.
 - **Git reads.** The header chip and the diff view run read-only git
@@ -245,9 +296,11 @@ document and the project document (project wins):
   approximated rather than parsed.
 - Live status updates what the page already contains: the header chips, the
   markers on the rows it rendered, and the footer line. A file that appears on
-  disk joins the listing on the next reload, the `/diff` table and a file page's
-  `changes` action stay page-load snapshots, and the branch chip is only patched
-  when the page was served inside a repository.
+  disk does not join the listing by itself — the page offers `⟳ reload` instead —
+  and the check covers the folder the page lists, by name, not the folders inside
+  it, a listed file's contents, the `/diff` table, or a file page's `changes`
+  action, which stay page-load snapshots. The branch chip is only patched when
+  the page was served inside a repository.
 - `/browse` has no auth; a malicious local page could probe the port. The `Host`
   allowlist and the absence of CORS headers mitigate reads, and the server is
   read-only.
@@ -288,6 +341,18 @@ document and the project document (project wins):
   method and `Host`, parses the URL, matches a route, and runs every path
   through `paths.ts`. It returns a plain `ServeResponse`, so routing is tested
   without a socket; `server.ts` is the only part that binds a port.
+- **One snapshot, one frame.** The status source is shared by every attached
+  page, so a tick costs one `git status`, one `git diff --stat`, and one
+  serialization however many tabs are open. The frame carries a revision of the
+  change set, and the client compares it before painting, which is why an idle
+  page does no DOM work. The cadence is what bounds those reads, so the default
+  is five seconds rather than matching the providers' two-second render cache.
+- **A poll, not a watcher.** The folder check is one request from the page to
+  `/api/dir-rev`, not an `fs.watch`: recursive watching is the one part of
+  `node:fs` whose availability and event semantics differ per platform, and it
+  would add a long-lived resource to start and release around `close()`. The
+  check compares names, so it is a directory read rather than a stat pass, and it
+  stops at the first difference because the control, not the checker, is the fix.
 - **Progressive UI.** The page is server-rendered HTML with an inline style
   block and inline SVG icons. `client.ts` enhances it: the filter hides
   non-matching rows while keeping ancestors, disclosure triangles lazily
@@ -399,7 +464,9 @@ document and the project document (project wins):
 | `urls.ts` | Shared link/image URL policy: scheme allowlist and `/view`/`/raw` rewriting |
 | `git.ts` | Read-only branch/dirty provider for the header chip |
 | `icons.ts` | Inline SVG sprite and the per-language mapping |
-| `client.ts` | The `/app.js` source (tree toggle, filter, sort, wrap, copy, quick open) |
+| `client.ts` | The `/app.js` source: sort, wrap, copy, hunk navigation, reading progress, and the page keymap |
+| `tree.ts` | The sidebar block: path filter, fold-all, lazy tree loading, and the tree's keyboard model (interpolated into `client.ts`) |
+| `palette.ts` | The quick-open palette: fuzzy search, the combobox wiring, and the `window.bfPalette` contract (interpolated into `client.ts`) |
 | `live-client.ts` | The client's live status block: the event stream, the chips, the markers, and the footer line (interpolated into `client.ts`) |
 | `live.ts` | The live status snapshot, its frame, and the fan-out channel that ticks it |
 | `styles.ts` | The page-only `browse-*` stylesheet (the `bf-*` kit comes from `lib/web`) |

package/extensions/file-browse/chrome.ts

@@ -0,0 +1,83 @@
+/**
+ * The header chrome for the browse pages.
+ *
+ * The chips the toolbar carries — the git branch, the change totals, the live
+ * connection state — and the footer's live line. Everything here is pure string
+ * building over an escaped view model: a branch name, a count, and a status word
+ * are all text a repository can choose, so each one crosses `escapeHtml` before
+ * it reaches the page. The page shell and the page bodies stay in `html.ts`.
+ */
+
+import { escapeHtml } from "../../lib/escape.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
+import type { GitStatus } from "./git.ts";
+import type { ChangeIndex } from "./live.ts";
+
+/** The header's git chip: the branch, or the detached head; changes are the changes chip's job. */
+export function renderGit(git: GitStatus | undefined): string {
+	if (!git) return "";
+	const name = git.branch ?? git.head;
+	if (!name) return "";
+	const glyph = git.branch ? GLYPHS.branch : GLYPHS.detached;
+	const aria = git.branch ? `git branch ${git.branch}` : `git detached at ${git.head ?? ""}`;
+	return `<span class="bf-chip browse-git" title="${escapeHtml(aria)}" aria-label="${escapeHtml(aria)}"><span class="browse-git__glyph" aria-hidden="true">${escapeHtml(glyph)}</span><span class="browse-git__name">${escapeHtml(name)}</span></span>`;
+}
+
+/** The live chrome a page renders: how often its stream is sent a frame. */
+export interface LivePage {
+	intervalMs: number;
+	/** Root-relative folder the page listed; absent on a page with no listing to check. */
+	dir?: string;
+	/** Revision of the names that listing drew, which the reload control compares against. */
+	rev?: string;
+}
+
+/**
+ * The header's live controls: the connection chip, and the reload control the
+ * client reveals once the folder the page drew has changed on disk. Both start
+ * hidden, so a page with JS off — or with live status disabled — never shows a
+ * state or a control it cannot keep true; the reload control is not rendered at
+ * all when the page has no listing revision to compare.
+ *
+ * The chip is deliberately not a `role="status"` region: the header is where a
+ * reader looks for the page's state, not a place to announce every change to it.
+ */
+export function renderLiveChrome(live: LivePage | undefined): string {
+	if (!live) return "";
+	const rev =
+		live.rev === undefined ? "" : ` data-dir="${escapeHtml(live.dir ?? "")}" data-rev="${escapeHtml(live.rev)}"`;
+	const chip = `<span class="bf-chip bf-chip--accent browse-live" id="live-state" title="Live status from the browse server" data-interval="${live.intervalMs}"${rev} hidden><span class="browse-live__glyph" aria-hidden="true">${escapeHtml(GLYPHS.browse)}</span><span class="browse-live__text">connecting</span></span>`;
+	if (live.rev === undefined) return chip;
+	return `${chip}<button type="button" class="bf-chip bf-chip--warn browse-reload" id="reload-hint" title="This folder changed on disk" hidden>⟳ reload</button>`;
+}
+
+/**
+ * The footer's live line, hidden until the first frame: uptime and requests are
+ * server facts the rendered page does not know at build time.
+ */
+export function renderLiveStatus(): string {
+	return `<span class="browse-live-line" id="live-status" hidden></span>`;
+}
+
+/**
+ * The header's changes chip, linking to the diff overview. With live status on,
+ * a hidden shell is always rendered so the chip can appear and disappear as the
+ * working tree changes, without the client inserting elements into the header.
+ */
+export function renderChanges(summary: ChangeIndex | undefined, live: LivePage | undefined): string {
+	const count = summary?.count ?? 0;
+	if (count <= 0) {
+		return live
+			? `<a class="bf-chip browse-diff" id="browse-changes" href="/diff" title="View uncommitted changes" hidden></a>`
+			: "";
+	}
+	const label = `${count} change${count === 1 ? "" : "s"}`;
+	const insertions = summary?.insertions ?? 0;
+	const deletions = summary?.deletions ?? 0;
+	const totals =
+		insertions + deletions > 0
+			? ` <span class="browse-diff-totals"><span class="browse-diff-add">+${insertions}</span> <span class="browse-diff-del">−${deletions}</span></span>`
+			: "";
+	const aria = `${label} against HEAD${insertions + deletions > 0 ? `, ${insertions} insertions and ${deletions} deletions` : ""}`;
+	return `<a class="bf-chip browse-diff" id="browse-changes" href="/diff" title="View uncommitted changes" aria-label="${escapeHtml(aria)}"><span class="browse-diff__dot" aria-hidden="true">●</span>${escapeHtml(label)}${totals}</a>`;
+}