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

package/extensions/context/types.ts

@@ -0,0 +1,122 @@
+/**
+ * The report's data contract.
+ *
+ * `ContextInputs` is what the host hands over: the effective system prompt, the
+ * tool surface, the host's usage estimate, the messages that will be sent, and
+ * the branch the compaction history is read from. `ContextReport` is what the
+ * pure builder derives from it and what the text detail and the screen render.
+ *
+ * Host types that the package root does not re-export are named through the
+ * extension surface (`ReturnType<…>`) rather than a deep import, so a peer
+ * version change fails to typecheck instead of resolving a second copy.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** The host's context-usage estimate (`ctx.getContextUsage()`). */
+export type ContextUsage = NonNullable<ReturnType<ExtensionContext["getContextUsage"]>>;
+
+/** The active branch entries (`sessionManager.getBranch()`). */
+export type BranchEntries = ReturnType<ExtensionContext["sessionManager"]["getBranch"]>;
+
+/** Merged global and project settings (`pi.getSettings()`). */
+export type ContextSettings = ReturnType<ExtensionAPI["getSettings"]>;
+
+/** Everything the pure report needs; collected once per open or refresh. */
+export interface ContextInputs {
+	/** The model in effect, or `null` before one is selected. */
+	model: { provider: string; id: string } | null;
+	/** The active model's context window, or `0` when unknown. */
+	window: number;
+	/** The effective system prompt for this turn (`ctx.getSystemPrompt()`). */
+	systemPrompt: string;
+	/** The active tool surface, with the definition estimate already computed. */
+	tools: { active: number; total: number; tokens: number };
+	/** The host's estimate; `tokens` is `null` between a compaction and the next reply. */
+	usage: ContextUsage | undefined;
+	/** The model-visible messages for the next request. */
+	messages: readonly AgentMessage[];
+	/** The branch the latest compaction entry and its count are read from. */
+	branch: BranchEntries;
+	/** Merged settings, for the compaction threshold. */
+	settings: ContextSettings;
+}
+
+/** One row of the composition table. */
+export interface ContextBucket {
+	/** Stable id; an injected child is `injected:<customType>`. */
+	id: string;
+	/** Display label, already plain text. */
+	label: string;
+	/** Estimated tokens. */
+	tokens: number;
+	/** Share of the composition estimate, `0..100`. */
+	share: number;
+	/** `0` for a top-level bucket, `1` for an injected child. */
+	depth: number;
+	/** A short factual suffix: `18 active of 24`, a message count. */
+	note?: string;
+}
+
+/** The latest compaction's effect. */
+export interface CompactionSummary {
+	/** `YYYY-MM-DD HH:MMZ` from the entry's ISO timestamp, in UTC. */
+	at: string;
+	/** The estimate the host recorded before compacting. */
+	tokensBefore: number;
+	/** The summary's own estimate. */
+	summaryTokens: number;
+	/** `tokensBefore - summaryTokens`, floored at zero. */
+	freed: number;
+}
+
+/** What the branch remembers about compaction. */
+export interface CompactionHistory {
+	/** How many compaction entries the branch holds. */
+	count: number;
+	/** The newest one, or `null` when the branch has never been compacted. */
+	last: CompactionSummary | null;
+}
+
+/** One of the largest single blocks in the projected context. */
+export interface LargestBlock {
+	/** Estimated tokens. */
+	tokens: number;
+	/** What kind of message it is: `user`, `assistant`, `tool result`, … */
+	role: string;
+	/** Sanitized, clipped descriptor (a tool name, the first line, a custom type). */
+	label: string;
+}
+
+/** The finished report. */
+export interface ContextReport {
+	/** The context window, `0` when unknown. */
+	window: number;
+	/** The host's estimate, `null` between a compaction and the next reply. */
+	tokens: number | null;
+	/** `tokens / window`, `null` when either is unknown. */
+	percent: number | null;
+	/** `window - tokens`, `null` when `tokens` is unknown. */
+	free: number | null;
+	/** `window - reserve - tokens`, `null` when `tokens` is unknown. */
+	headroom: number | null;
+	/** The resolved `reserveTokens` for the active model. */
+	reserve: number;
+	/** The resolved `keepRecentTokens` for the active model. */
+	keepRecentTokens: number;
+	/** Whether the host's automatic compaction is on. */
+	enabled: boolean;
+	/** `max(0, window - reserve)`: where the host would compact. */
+	autoCompactAt: number;
+	/** The composition rows, ordered for display. */
+	buckets: ContextBucket[];
+	/** Sum of the bucket estimates. */
+	estimate: number;
+	/** `tokens - estimate` when the host's estimate is known, else `null`. */
+	drift: number | null;
+	/** The branch's compaction history. */
+	compaction: CompactionHistory;
+	/** The largest projected blocks, biggest first. */
+	largest: LargestBlock[];
+}

package/extensions/file-browse/README.md

@@ -83,13 +83,16 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   `worktree`; untracked files show as all-add, an unborn `HEAD` falls back to the
   index, and a non-repository is a plain empty state. Read-only, capped, and
   rendered with the shared diff colors.
-- **Live status.** A page left open keeps up with the session: a `◉ live · 2s`
-  chip beside `read-only` says whether status is flowing (green, with the age of
-  the last frame), still connecting (accent), stalled (amber), 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`. One Server-Sent Events stream per page carries it, on the same
-  loopback server, so nothing extra is opened and nothing is written.
+- **Live status.** A page left open keeps up with the session: a `◉ live`
+  chip beside `read-only` says whether status is flowing (green), still
+  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.
 - **No dependencies.** `node:http` plus the inline sprite, CSS, and client
   script.
 
@@ -110,7 +113,10 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   port; a busy port is reported, not silently changed.
 - Starting while already running with the same root reprints the URL without
   restarting; a different root (or a changed pinned port) restarts the server.
-- The server is closed on `session_shutdown`.
+- The server is closed when its last page has been gone for ten seconds, so
+  closing the browser window ends the session's browse server and `/browse`
+  starts it again on the same port. A reload or a new tab inside that grace keeps
+  it. `session_shutdown` closes it too, and `/browse stop` closes it at once.
 
 ### Status
 
@@ -122,11 +128,12 @@ is cleared on stop and on `session_shutdown`. The chip is session-local: it
 reflects only this session's server, with no cross-session sharing.
 
 The page has its own live status, which is what a left-open tab reads. The
-header chip starts hidden and is painted by the client from `/events`: `◉ live ·
-2s` in the success colour while frames arrive, `◉ connecting` before the first
-one, `◉ stale · 9s` in the warning colour when three intervals pass without a
-frame on an open connection, and `◉ offline` in the danger colour once the
-stream errors. The same frame carries the branch (or detached head), the
+header chip starts hidden and is painted by the client from `/events`: `◉ live`
+in the success colour while frames arrive, `◉ connecting` before the first
+one, `◉ stale` in the warning colour when three intervals pass without a frame
+on an open connection, and `◉ offline` in the danger colour once the stream
+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
@@ -134,6 +141,12 @@ 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.
 
+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
+nothing is left to serve. That is why a page with JavaScript off — or with live
+status off — never counts as a reader, and the server then waits for
+`/browse stop` or the end of the session.
+
 ## Routes
 
 | Route | Result |
@@ -256,7 +269,7 @@ document and the project document (project wins):
 |---|---|
 | Command | `/browse` registers a single command from the factory; no tools are exposed. |
 | State | The running server, its root, and the session port live in a module-local closure; nothing is persisted and no session entries are written. |
-| Lifecycle | The factory opens no socket; the server is created on `/browse` and closed idempotently by `/browse stop` and `session_shutdown`, which also ends every attached status stream. |
+| Lifecycle | The factory opens no socket; the server is created on `/browse` and closed idempotently by `/browse stop`, by `session_shutdown`, and once its last page has been gone for the idle grace, which also ends every attached status stream. |
 
 ## Design notes
 
@@ -267,7 +280,10 @@ document and the project document (project wins):
   wins, otherwise a random port is drawn and cached after the first successful
   bind, so later starts reuse it (a conflict is reported and the next `/browse`
   rolls another). `/browse stop` and `session_shutdown` await the idempotent
-  `close()`; `session_shutdown` also clears the cached port.
+  `close()`; `session_shutdown` also clears the cached port. The page is the
+  server's only reader, so the channel reports the last page's departure after
+  `IDLE_STOP_MS` and the command closes the server and clears the chip — the
+  cached port survives, so the next `/browse` binds the same one.
 - **Pure routing.** `handleRequest(context, method, rawUrl, headers)` validates
   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
@@ -350,13 +366,15 @@ document and the project document (project wins):
   attached pages and starts the ticker on the first attach, so an idle server
   does no work; it shares a single in-flight snapshot between pages, drops a
   page whose write fails, and stops on the last detach and on `close()`, which
-  `server.ts` calls before closing the socket. Both providers are already
+  `server.ts` calls before closing the socket. The last detach also arms one
+  idle-stop timer — a reload re-attaches and cancels it — and `server.ts` turns
+  that into the extension's `close()` and a cleared chip. Both providers are already
   TTL-cached, so a tick re-reads at most one `git status`, and every read
   failure degrades to `null` rather than a failed frame. The event-stream
   headers and the `retry:` preamble live in `lib/http` with the rest of the
   loopback policy, shared with plan's review page. The client half is
   `live-client.ts`: one `EventSource`, one snapshot paint (`textContent` only,
-  never markup), a one-second age ticker, and a `pagehide` cleanup.
+  never markup), one staleness timeout armed per frame, and a `pagehide` cleanup.
 - **Streaming responses.** The server streams `filePath` responses and
   suppresses bodies for `HEAD`, so large `/raw` files are not buffered.
 - **Root confinement over feature breadth.** The root is deliberately confined
@@ -412,7 +430,9 @@ and provider (line kinds, line numbers, status and rename parsing, mode
 filtering, untracked all-add, unborn-HEAD fallback, literal pathspec, and TTL
 cache), the diff renderers (highlighted changed lines, marker sets, and chip
 totals), the live status feed (snapshot fields, degraded providers, the frame,
-and the channel's ticker driven by an injected timer), the `/events` route and
+and the channel's ticker driven by an injected timer, plus the idle stop armed on
+the last detach and cancelled by the next page or by `close()`), the `/events`
+route and
 its 404 when the channel is off, a real socket that reads a page's first frame
 and the ticker's next one and sees the stream end when the server closes, the
 live chrome a page renders when on and not when off, and the command

package/extensions/file-browse/config.ts

@@ -73,6 +73,14 @@ export const LIVE_INTERVAL_MIN = 250;
 /** Slowest live-status cadence, so a page cannot look abandoned. */
 export const LIVE_INTERVAL_MAX = 60_000;
 
+/**
+ * How long the server keeps listening once the last page has gone. A reload or a
+ * navigation detaches the stream and re-attaches within a moment, so the grace has
+ * to outlast one; a closed window never re-attaches, and the port is released
+ * instead of listening for nobody until the session ends.
+ */
+export const IDLE_STOP_MS = 10_000;
+
 /** A random port in the per-session range `PORT_BASE`–`PORT_BASE + PORT_RANGE - 1`. */
 export function randomPort(): number {
 	return PORT_BASE + randomInt(PORT_RANGE);

package/extensions/file-browse/html.ts

@@ -76,8 +76,8 @@ export interface LivePage {
  * client reveals and paints it from the event stream, so a page with JS off — or
  * with live status disabled — never shows a state it cannot keep true.
  *
- * It is deliberately not a `role="status"` region: the age in the label is
- * rewritten every second, and a live region would announce each rewrite.
+ * It 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.
  */
 function renderLiveChip(live: LivePage | undefined): string {
 	if (!live) return "";

package/extensions/file-browse/index.ts

@@ -4,7 +4,8 @@
  * Registers the read-only `/browse` command. It starts a `node:http` server
  * bound to 127.0.0.1, rooted at the effective cwd, and opens the default
  * browser at a two-pane tree browser. No tool is registered; the server is
- * closed on `session_shutdown`.
+ * closed on `session_shutdown`, by `/browse stop`, and once its last page has
+ * been gone for the idle grace — a closed window is not a running server.
  *
  * Load with:  pi --extension ./extensions/file-browse
  */
@@ -32,6 +33,8 @@ export interface FileBrowserDeps {
 
 interface RunningServer {
 	server: FileServer;
+	/** The context of the command that started it, used to clear the chip later. */
+	ctx: ExtensionContext;
 }
 
 export default function fileBrowser(pi: ExtensionAPI, deps: FileBrowserDeps = {}): void {
@@ -62,6 +65,17 @@ export default function fileBrowser(pi: ExtensionAPI, deps: FileBrowserDeps = {}
 		return true;
 	};
 
+	/**
+	 * Close the server once the page that was its only reader has gone: nothing is
+	 * left to serve, and the chip would otherwise advertise a port that answers no
+	 * one. `/browse` starts it again on the same session port.
+	 */
+	const stopWhenPageLeft = async (): Promise<void> => {
+		const current = running;
+		if (!current) return;
+		if (await stop(current.ctx)) current.ctx.ui.notify("browse: stopped — the last page was closed", "info");
+	};
+
 	const start = async (args: string, ctx: ExtensionContext): Promise<void> => {
 		const target = args.trim();
 		if (target === "status") {
@@ -121,9 +135,10 @@ export default function fileBrowser(pi: ExtensionAPI, deps: FileBrowserDeps = {}
 					maxFileBytes: config.maxFileBytes,
 					maxTextLines: config.maxTextLines,
 				}),
+				onIdle: () => void stopWhenPageLeft(),
 			});
 			if (unpinned) sessionPort = port;
-			running = { server };
+			running = { server, ctx };
 			setBrowseStatus(ctx, server.port);
 			ctx.ui.notify(`browse: ${server.root} at ${server.url}`, "info");
 			if (config.autoOpen) (deps.open ?? openInBrowser)(server.url);

package/extensions/file-browse/live-client.ts

@@ -20,7 +20,7 @@ export const LIVE_CLIENT_JS = `	// Live status: one event stream feeds the heade
 		var liveGit = document.querySelector(".browse-git");
 		var liveChanges = document.getElementById("browse-changes");
 		var liveInterval = Number(liveChip.getAttribute("data-interval")) || 3000;
-		var liveReceived = 0;
+		var liveStale = 0;
 		var liveTone = "";
 
 		function formatSpan(ms) {
@@ -38,14 +38,15 @@ export const LIVE_CLIENT_JS = `	// Live status: one event stream feeds the heade
 			if (liveText) liveText.textContent = label;
 		}
 
-		// The age is the local elapsed time since the last frame, so it stays right
-		// even when the loopback server's clock and this browser's disagree. Three
-		// missed frames on an open connection is a stalled feed, not a live one.
-		function paintLiveAge() {
-			if (!liveText || (liveTone !== "success" && liveTone !== "warn")) return;
-			var idle = Date.now() - liveReceived;
-			if (idle > liveInterval * 3) setLiveTone("warn", "stale \\u00B7 " + formatSpan(idle));
-			else liveText.textContent = "live \\u00B7 " + formatSpan(idle);
+		// The chip names its state and never counts: nothing is repainted between
+		// frames, and the age of the last one is the footer's uptime to report. Three
+		// missed frames on an open connection is a stalled feed, not a live one, so
+		// one timeout is armed per frame instead of a second-by-second tick.
+		function armLiveStale() {
+			window.clearTimeout(liveStale);
+			liveStale = window.setTimeout(function () {
+				if (liveTone === "success") setLiveTone("warn", "stale");
+			}, liveInterval * 3);
 		}
 
 		function paintLiveGit(git) {
@@ -124,8 +125,8 @@ export const LIVE_CLIENT_JS = `	// Live status: one event stream feeds the heade
 		}
 
 		function paintLiveSnapshot(snapshot) {
-			liveReceived = Date.now();
-			setLiveTone("success", "live \\u00B7 0s");
+			setLiveTone("success", "live");
+			armLiveStale();
 			if (liveLine) {
 				liveLine.hidden = false;
 				var requests = Number(snapshot.requests) || 0;
@@ -137,7 +138,6 @@ export const LIVE_CLIENT_JS = `	// Live status: one event stream feeds the heade
 
 		if (window.EventSource) {
 			var liveStream = new EventSource("/events");
-			var liveTicker = window.setInterval(paintLiveAge, 1000);
 			liveStream.addEventListener("open", function () {
 				if (liveTone !== "success") setLiveTone("accent", "connecting");
 			});
@@ -151,7 +151,7 @@ export const LIVE_CLIENT_JS = `	// Live status: one event stream feeds the heade
 			});
 			window.addEventListener("pagehide", function () {
 				liveStream.close();
-				window.clearInterval(liveTicker);
+				window.clearTimeout(liveStale);
 			});
 		}
 	}

package/extensions/file-browse/live.ts

@@ -11,6 +11,7 @@
  * pair — so the whole feed is tested without one.
  */
 
+import { defaultInterval, defaultTimer } from "../../lib/timer.ts";
 import { changeDirs } from "./diff.ts";
 import type { DiffList, GitDiffProvider, GitStatus, GitStatusProvider } from "./git.ts";
 
@@ -141,38 +142,50 @@ export interface LiveClient {
 /** Starts a repeating tick and returns its cancel. */
 export type LiveTimer = (tick: () => void, intervalMs: number) => () => void;
 
+/** Starts a one-shot delay and returns its cancel. */
+export type LiveTimeout = (run: () => void, delayMs: number) => () => void;
+
 /** The default ticker: a repeating timer that cannot hold the process open. */
-const defaultTimer: LiveTimer = (tick, intervalMs) => {
-	const handle = setInterval(tick, intervalMs);
-	(handle as { unref?: () => void }).unref?.();
-	return () => clearInterval(handle);
-};
+const defaultTicker: LiveTimer = (tick, intervalMs) => defaultInterval(intervalMs, tick);
+
+/** The default grace timer: one shot, and it cannot hold the process open either. */
+const defaultTimeout: LiveTimeout = (run, delayMs) => defaultTimer(delayMs, run);
 
 export interface LiveChannelOptions {
 	/** What each frame carries. */
 	status: LiveStatusSource;
 	/** How far apart the frames are, in ms. */
 	intervalMs: number;
+	/** How long the last page's departure is held before `onIdle` is called, in ms. */
+	idleMs: number;
+	/** Called once the last page has been gone for `idleMs`; omitted, the channel only idles. */
+	onIdle?: () => void;
 	/** Timer seam; defaults to an unref'd interval. */
 	timer?: LiveTimer;
+	/** Grace seam; defaults to an unref'd timeout. */
+	timeout?: LiveTimeout;
 }
 
 /** The fan-out for one server: pages attach, ticks publish, close ends them. */
 export interface LiveChannel {
 	/** Add a connected page, send it the current status, and return its detach. */
 	attach(client: LiveClient): () => void;
-	/** End every connected page and stop the ticker. */
+	/** End every connected page, stop the ticker, and drop a pending idle stop. */
 	close(): void;
 }
 
 /**
  * Build a channel for one server. The ticker runs only while at least one page
- * is attached, so an idle server does no status work at all.
+ * is attached, so an idle server does no status work at all; the idle stop is one
+ * timer armed when the last page leaves and cancelled by the next page, so a
+ * reload keeps the server and a closed window releases it.
  */
 export function createLiveChannel(options: LiveChannelOptions): LiveChannel {
-	const timer = options.timer ?? defaultTimer;
+	const timer = options.timer ?? defaultTicker;
+	const timeout = options.timeout ?? defaultTimeout;
 	const clients = new Set<LiveClient>();
 	let cancel: (() => void) | undefined;
+	let cancelIdle: (() => void) | undefined;
 	let inFlight = false;
 
 	const stop = (): void => {
@@ -180,6 +193,25 @@ export function createLiveChannel(options: LiveChannelOptions): LiveChannel {
 		cancel = undefined;
 	};
 
+	const cancelIdleStop = (): void => {
+		cancelIdle?.();
+		cancelIdle = undefined;
+	};
+
+	const armIdleStop = (): void => {
+		if (!options.onIdle || cancelIdle) return;
+		cancelIdle = timeout(() => {
+			cancelIdle = undefined;
+			options.onIdle?.();
+		}, options.idleMs);
+	};
+
+	/** Nobody is reading a frame any more: park the ticker and start the grace. */
+	const pageLeft = (): void => {
+		stop();
+		armIdleStop();
+	};
+
 	const send = (frame: string): void => {
 		for (const client of clients) {
 			try {
@@ -188,7 +220,7 @@ export function createLiveChannel(options: LiveChannelOptions): LiveChannel {
 				clients.delete(client);
 			}
 		}
-		if (clients.size === 0) stop();
+		if (clients.size === 0) pageLeft();
 	};
 
 	// One snapshot serves every attached page, so a tick is one git read and one
@@ -205,15 +237,17 @@ export function createLiveChannel(options: LiveChannelOptions): LiveChannel {
 
 	return {
 		attach(client) {
+			cancelIdleStop();
 			clients.add(client);
 			cancel ??= timer(() => void publish(), options.intervalMs);
 			void publish();
 			return () => {
 				if (!clients.delete(client)) return;
-				if (clients.size === 0) stop();
+				if (clients.size === 0) pageLeft();
 			};
 		},
 		close() {
+			cancelIdleStop();
 			stop();
 			for (const client of clients) client.end();
 			clients.clear();

package/extensions/file-browse/markdown.ts

@@ -25,7 +25,7 @@
  * policy and raw HTML do not.
  */
 
-import { escapeHtml } from "../../lib/escape.ts";
+import { decodeCodePoint, escapeHtml } from "../../lib/escape.ts";
 import { fenceLanguage, highlightLines } from "../../lib/highlight.ts";
 import {
 	closesSuppressed,
@@ -739,13 +739,6 @@ interface Entity {
 	length: number;
 }
 
-/** A code point, or U+FFFD when the reference is a surrogate or out of range. */
-function codePoint(value: number): string {
-	if (!Number.isFinite(value) || value <= 0 || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff))
-		return "\uFFFD";
-	return String.fromCodePoint(value);
-}
-
 /**
  * Match a numeric or named character reference at `start`. Decoding happens in
  * the inline scanner rather than a pre-pass so an entity cannot become Markdown
@@ -755,8 +748,8 @@ function matchEntity(text: string, start: number): Entity | undefined {
 	const match = /^&(?:#([0-9]{1,7})|#[xX]([0-9a-fA-F]{1,6})|([a-zA-Z][a-zA-Z0-9]{1,31}));/.exec(text.slice(start));
 	if (!match) return undefined;
 	let value: string | undefined;
-	if (match[1] !== undefined) value = codePoint(Number(match[1]));
-	else if (match[2] !== undefined) value = codePoint(Number.parseInt(match[2], 16));
+	if (match[1] !== undefined) value = decodeCodePoint(Number(match[1]));
+	else if (match[2] !== undefined) value = decodeCodePoint(Number.parseInt(match[2], 16));
 	else if (match[3] !== undefined && Object.hasOwn(NAMED_ENTITIES, match[3])) value = NAMED_ENTITIES[match[3]];
 	if (value === undefined) return undefined;
 	return { value, length: match[0].length };

package/extensions/file-browse/raw-html.ts

@@ -25,7 +25,7 @@
  * how `<details>` wraps Markdown.
  */
 
-import { escapeHtml } from "../../lib/escape.ts";
+import { decodeCodePoint, escapeHtml } from "../../lib/escape.ts";
 import { resolveImage, resolveLink } from "./urls.ts";
 
 /** Elements re-emitted with sanitized attributes. */
@@ -353,21 +353,14 @@ function decodeAttribute(value: string): string {
 	return value.replace(
 		ATTRIBUTE_ENTITY,
 		(match, decimal: string | undefined, hex: string | undefined, named: string | undefined) => {
-			if (decimal !== undefined) return codePoint(Number(decimal));
-			if (hex !== undefined) return codePoint(Number.parseInt(hex, 16));
+			if (decimal !== undefined) return decodeCodePoint(Number(decimal));
+			if (hex !== undefined) return decodeCodePoint(Number.parseInt(hex, 16));
 			if (named !== undefined && Object.hasOwn(ATTRIBUTE_ENTITIES, named)) return ATTRIBUTE_ENTITIES[named];
 			return match;
 		},
 	);
 }
 
-/** A code point, or U+FFFD when the reference is a surrogate or out of range. */
-function codePoint(value: number): string {
-	if (!Number.isFinite(value) || value <= 0 || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff))
-		return "\uFFFD";
-	return String.fromCodePoint(value);
-}
-
 /** The first value for `name`, decoded, so a duplicate attribute cannot override it. */
 function attribute(tag: RawTag, name: string): string | undefined {
 	const found = tag.attrs.find((candidate) => candidate.name === name);

package/extensions/file-browse/server.ts

@@ -22,7 +22,7 @@ import {
 	textResponse,
 	type ServeResponse,
 } from "../../lib/http/index.ts";
-import type { ServeConfig } from "./config.ts";
+import { IDLE_STOP_MS, type ServeConfig } from "./config.ts";
 import { createFileIndex } from "./files.ts";
 import type { GitDiffProvider, GitStatusProvider } from "./git.ts";
 import { createLiveChannel, createLiveStatus } from "./live.ts";
@@ -46,6 +46,10 @@ export interface FileServerOptions {
 	git?: GitStatusProvider;
 	/** Read-only diff provider for the change and diff views; omitted when unavailable. */
 	diff?: GitDiffProvider;
+	/** Called once the last page has been gone for `idleStopMs`; omitted, the server waits for `close()`. */
+	onIdle?: () => void;
+	/** Grace before `onIdle`, in ms; defaults to `IDLE_STOP_MS`. */
+	idleStopMs?: number;
 	/** Override the request handler (tests). */
 	handler?: typeof handleRequest;
 }
@@ -65,7 +69,14 @@ export async function createFileServer(options: FileServerOptions): Promise<File
 				requests: () => requests,
 			})
 		: undefined;
-	const live = status ? createLiveChannel({ status, intervalMs: config.liveIntervalMs }) : undefined;
+	const live = status
+		? createLiveChannel({
+				status,
+				intervalMs: config.liveIntervalMs,
+				idleMs: options.idleStopMs ?? IDLE_STOP_MS,
+				onIdle: options.onIdle,
+			})
+		: undefined;
 	const context: ServeContext = {
 		root,
 		config,

package/extensions/file-open/README.md

@@ -152,5 +152,4 @@ of the model's active tool set unless a script explicitly reaches for it.
 | `index.ts` | The extension factory: registers `open_path` and the `/open` command, resolves the target, and routes a launch failure to `ctx.ui.notify`. |
 | `open.ts` | `normalizeTarget` and `buildCommand` (pure), `resolveTarget` (existence check), and `openTarget` with the injectable launcher, which reports a start failure and a meaningful non-zero exit. |
 | `schema.ts` | `TOOL_NAME`, the TypeBox `parameters` / `outputSchema`, and the `OpenPathArgs` / `OpenPathResult` types. |
-| `open.test.ts` | Pure-module tests for normalization, resolution, per-platform commands, and the launcher seam. |
-| `extension.test.ts` | Extension-surface tests: registration, disabling, the tool call, and the command. |
+| `extension.test.ts` | The capability suite: normalization, resolution, per-platform commands, the launcher seam, registration, disabling, the tool call, and the command. |