@gavin-hu/my-pi-agent 0.12.0 → 0.13.0

package/extensions/bytefly/update/cache.ts

@@ -0,0 +1,73 @@
+/**
+ * The published-version answer, cached on disk with the time it was read.
+ *
+ * The check already fires once per session, which leaves two gaps: a session open
+ * for days never re-reads npm, and every new session pays for a request it made
+ * minutes earlier. A timestamp is what fixes the second, so the cache lives in the
+ * agent directory rather than in memory — one entry, one window, shared by every
+ * session that starts inside it.
+ *
+ * A cache can only ever be a miss. An absent, unreadable, or wrong-typed file
+ * reads as `undefined` and the caller fetches; nothing here throws, because a
+ * stale file must never become a session error.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeConfigFile } from "../../../lib/config.ts";
+import { parseVersion } from "./version.ts";
+
+/** The file name under `<agentDir>/bytefly/`. */
+export const UPDATE_CACHE_FILE = "update.json";
+
+/** How long a cached answer is reused before the next session re-reads npm. */
+export const UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** One cached answer: the newest published version and when it was read. */
+export interface UpdateCacheEntry {
+	/** The version npm's `latest` tag pointed at. */
+	latest: string;
+	/** Epoch milliseconds of the read that produced `latest`. */
+	checkedAt: number;
+}
+
+/** Where the cache lives for an agent directory. */
+export function updateCachePath(agentDir: string): string {
+	return join(agentDir, "bytefly", UPDATE_CACHE_FILE);
+}
+
+/** Read the cache; a missing, corrupt, or mistyped entry is `undefined`. */
+export function readUpdateCache(path: string): UpdateCacheEntry | undefined {
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown> | undefined;
+		if (!raw || typeof raw !== "object") return undefined;
+		const latest = typeof raw.latest === "string" ? raw.latest.trim() : "";
+		const checkedAt = typeof raw.checkedAt === "number" && Number.isFinite(raw.checkedAt) ? raw.checkedAt : 0;
+		if (!parseVersion(latest) || checkedAt <= 0) return undefined;
+		return { latest, checkedAt };
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Write the cache atomically (a sibling temp file, then a rename). The caller
+ * treats a throw as a miss: a read-only agent directory must not break a session.
+ */
+export function writeUpdateCache(path: string, entry: UpdateCacheEntry): void {
+	writeConfigFile(path, { latest: entry.latest, checkedAt: entry.checkedAt });
+}
+
+/**
+ * Whether an entry is still inside the window. The boundary is inclusive: an
+ * entry read exactly `ttlMs` ago is reused, so the window never flickers.
+ */
+export function isFresh(
+	entry: UpdateCacheEntry | undefined,
+	now: number,
+	ttlMs: number = UPDATE_CACHE_TTL_MS,
+): boolean {
+	if (!entry) return false;
+	const age = now - entry.checkedAt;
+	return age >= 0 && age <= ttlMs;
+}

package/extensions/bytefly/update/format.ts

@@ -1,32 +1,87 @@
 /**
- * Wording for the update check: the header marker and the one transcript notice.
+ * Wording for the update check: the header marker, the one transcript notice, and
+ * the answer an explicit re-check prints.
  *
- * Both read the same two facts — the version this session loaded and the version
- * the registry publishes — and neither adds a third. The marker is the shortest
- * honest form (`↑0.12.0`), and the notice names the command instead of printing
- * a changelog link the notice renderer cannot open.
+ * All three read the same two facts — the version this session loaded and the
+ * version the registry publishes — and none adds a third. The marker is the
+ * shortest honest form (`↑0.12.0`); the notice names the command and the release
+ * URL as text, because the notice renderer has no link support; and the re-check
+ * says what it just found, including the two cases it cannot answer (offline, and
+ * a registry it could not read).
  */
 
+import pkg from "../../../package.json";
 import { noticeMessage, type NoticeMessage } from "../../../lib/notice.ts";
 import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+import type { UpdateOutcome } from "./state.ts";
 
 /** The header marker: an up arrow and the newest version, e.g. `↑0.12.0`. */
 export function updateMarker(latest: string): string {
 	return `${GLYPHS.update}${latest}`;
 }
 
+/**
+ * The release page for a version, or `undefined` when this checkout does not name
+ * a GitHub repository. Derived from `package.json` so a rename cannot leave a dead
+ * link behind in the notice.
+ */
+export function releaseUrl(version: string): string | undefined {
+	const url = (pkg.repository as { url?: string } | undefined)?.url ?? "";
+	const base = url.replace(/\.git$/, "");
+	if (!/^https:\/\/github\.com\/[^/]+\/[^/]+$/.test(base)) return undefined;
+	return `${base}/releases/tag/v${version}`;
+}
+
 /** The single notice a session posts when a newer version is published. */
 export function updateNotice(current: string, latest: string): NoticeMessage {
+	const release = releaseUrl(latest);
+	const command = "pi update --extensions";
 	return noticeMessage({
-		content: `bytefly ${latest} is available (current ${current}). Run \`pi update --extensions\` to update.`,
+		content:
+			`bytefly ${latest} is available (current ${current}). Run \`${command}\` to update.` +
+			(release ? ` Release notes: ${release}` : ""),
 		details: {
 			source: "bytefly",
 			title: `${latest} is available`,
 			severity: "info",
-			items: [
-				{ label: "current", detail: `v${current}` },
-				{ label: "update", detail: "pi update --extensions" },
-			],
+			items: release
+				? [
+						{ label: "current", detail: `v${current}` },
+						{ label: "update", detail: command },
+						{ label: "release", detail: release },
+					]
+				: [
+						{ label: "current", detail: `v${current}` },
+						{ label: "update", detail: command },
+					],
 		},
 	});
 }
+
+/**
+ * What `/bytefly update` prints. The background check is silent because nobody
+ * asked; here someone did, so a skip and a failed read are answers too.
+ */
+export function updateOutcomeText(
+	outcome: UpdateOutcome,
+	current: string,
+): { text: string; severity: "info" | "warning" } {
+	switch (outcome.kind) {
+		case "offline":
+			return { text: "bytefly: the update check was skipped (PI_OFFLINE is set).", severity: "info" };
+		case "failed":
+			return {
+				text: "bytefly: could not read the published version — check the network and try again.",
+				severity: "warning",
+			};
+		case "current":
+			return { text: `bytefly: up to date — v${outcome.latest} is the newest published version.`, severity: "info" };
+		case "available": {
+			const release = releaseUrl(outcome.latest);
+			return {
+				text: `bytefly: v${outcome.latest} is available (current ${current}).${release ? ` ${release}` : ""}`,
+				severity: "info",
+			};
+		}
+	}
+}

package/extensions/bytefly/update/register.ts

@@ -1,6 +1,6 @@
 /**
- * The update check's lifecycle: read the published version once per interactive
- * session, record it when it is newer, and announce it once per load.
+ * The update check's lifecycle: reuse the cached answer or read the registry once
+ * per interactive session, record a newer version, and announce it once per load.
  *
  * The request is fired without awaiting. Pi awaits `session_start` handlers, so
  * a slow registry would otherwise hold the first prompt; Pi's own version check
@@ -8,49 +8,106 @@
  * version is silent, and a generation counter keeps a request that resolves
  * after shutdown from writing into the next session's state.
  *
- * `/bytefly` and `doctor` do not report this: an available update is not a
- * prerequisite problem, and the header plus one notice are the whole surface.
+ * A cached answer with a timestamp is what makes a long-lived session different
+ * from a fresh one: a session that starts inside the window reuses the last read
+ * instead of repeating it, and `recheck()` ignores the window so `/bytefly update`
+ * can look again without a restart. `/bytefly` and `doctor` do not report the
+ * version: an available update is not a prerequisite problem.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import pkg from "../../../package.json";
 import { isOffline } from "../../../lib/env.ts";
+import { isFresh, readUpdateCache, updateCachePath, writeUpdateCache, type UpdateCacheEntry } from "./cache.ts";
 import { fetchLatestVersion } from "./check.ts";
 import { updateNotice } from "./format.ts";
-import type { UpdateSource } from "./state.ts";
+import type { UpdateOutcome, UpdateSource } from "./state.ts";
 import { isNewerVersion } from "./version.ts";
 
-/** Test seams; production uses the registry read and `PI_OFFLINE`. */
+/** The cache, as the lifecycle sees it: read on start, written after a read. */
+export interface UpdateCache {
+	/** The last recorded answer, or `undefined` for a miss. */
+	read(): UpdateCacheEntry | undefined;
+	/** Record an answer; a throw is treated as a miss. */
+	write(entry: UpdateCacheEntry): void;
+}
+
+/** What `registerUpdate` returns, so the panel can re-run the check on demand. */
+export interface UpdateHandle {
+	/** Read the registry now, ignoring the cache window. Never throws. */
+	recheck(): Promise<UpdateOutcome>;
+}
+
+/** Test seams; production uses the registry read, `PI_OFFLINE`, and the agent dir. */
 export interface UpdateDeps {
 	/** Replace the registry read; a rejection counts as no answer. */
 	fetchLatest?: () => Promise<string | undefined>;
 	/** Replace the `PI_OFFLINE` check. */
 	isOffline?: () => boolean;
+	/** Replace the disk cache. */
+	cache?: UpdateCache;
+	/** Replace the clock the cache timestamp is read from. */
+	now?: () => number;
 	/** Called once a newer version is recorded, so a mounted surface repaints. */
 	onUpdate?: () => void;
 }
 
+/** The on-disk cache under the agent directory, built lazily so it is per call. */
+function diskCache(): UpdateCache {
+	return {
+		read: () => readUpdateCache(updateCachePath(getAgentDir())),
+		write: (entry) => {
+			try {
+				writeUpdateCache(updateCachePath(getAgentDir()), entry);
+			} catch {
+				// A read-only agent directory costs the next session one request, nothing more.
+			}
+		},
+	};
+}
+
 /**
  * Register the check. `updates` is the same store the header reads, so recording
  * a version and calling `onUpdate` is what puts the marker on screen.
  */
-export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: UpdateDeps = {}): void {
+export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: UpdateDeps = {}): UpdateHandle {
 	const readLatest = deps.fetchLatest ?? (() => fetchLatestVersion());
 	const offline = deps.isOffline ?? isOffline;
+	const cache = deps.cache ?? diskCache();
+	const now = deps.now ?? Date.now;
 	// A session is announced at most once per load, even if `session_start` fires
 	// again after a resume or a session replacement.
 	let announced = false;
 	let generation = 0;
 
+	/** Record a newer version and repaint the marker. */
+	const paint = (latest: string): void => {
+		if (!isNewerVersion(latest, pkg.version)) return;
+		updates.set(latest);
+		deps.onUpdate?.();
+	};
+
+	/** The once-per-load transcript notice, posted only for a strictly newer version. */
+	const announce = (latest: string): void => {
+		if (announced || !isNewerVersion(latest, pkg.version)) return;
+		announced = true;
+		pi.sendMessage(updateNotice(pkg.version, latest));
+	};
+
+	/** One answer, from the cache or the registry: paint the marker, announce it once. */
+	const record = (entry: UpdateCacheEntry): void => {
+		paint(entry.latest);
+		announce(entry.latest);
+	};
+
 	const check = async (token: number): Promise<void> => {
 		try {
 			const latest = await readLatest();
 			if (latest === undefined || token !== generation) return;
-			if (announced || !isNewerVersion(latest, pkg.version)) return;
-			announced = true;
-			updates.set(latest);
-			deps.onUpdate?.();
-			pi.sendMessage(updateNotice(pkg.version, latest));
+			const entry = { latest, checkedAt: now() };
+			cache.write(entry);
+			record(entry);
 		} catch {
 			// A background check never surfaces an error: the session does not know it ran.
 		}
@@ -60,7 +117,19 @@ export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: Up
 		// The marker lives in bytefly's header and the notice in a transcript, so a
 		// non-interactive run has nothing to draw and makes no request.
 		if (ctx.mode !== "tui") return;
-		if (announced || offline()) return;
+		if (offline()) {
+			// No request, so the window does not matter: the cached answer is the best
+			// one available, and the marker is advisory.
+			const cached = cache.read();
+			if (cached) record(cached);
+			return;
+		}
+		const cached = cache.read();
+		if (cached && isFresh(cached, now())) {
+			record(cached);
+			return;
+		}
+		if (announced) return;
 		void check(generation);
 	});
 
@@ -69,4 +138,21 @@ export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: Up
 		generation++;
 		updates.set();
 	});
+
+	return {
+		async recheck() {
+			if (offline()) return { kind: "offline" };
+			let latest: string | undefined;
+			try {
+				latest = await readLatest();
+			} catch {
+				return { kind: "failed" };
+			}
+			if (latest === undefined) return { kind: "failed" };
+			cache.write({ latest, checkedAt: now() });
+			// The caller prints the answer, so this path never posts a notice.
+			paint(latest);
+			return isNewerVersion(latest, pkg.version) ? { kind: "available", latest } : { kind: "current", latest };
+		},
+	};
 }

package/extensions/bytefly/update/state.ts

@@ -1,5 +1,6 @@
 /**
- * Where a surface reads the newest published version this load found.
+ * Where a surface reads the newest published version this load found, and what an
+ * explicit re-check reported.
  *
  * The check resolves after the session started, so the header cannot be handed
  * the value up front: it reads through this store on every apply, and the
@@ -16,6 +17,17 @@ export interface UpdateSource {
 	set(latest?: string): void;
 }
 
+/**
+ * What one explicit re-check found. The background check reports nothing — nobody
+ * asked — so this vocabulary exists only for `/bytefly update`, where a failure or
+ * a skip is an answer rather than silence.
+ */
+export type UpdateOutcome =
+	| { kind: "offline" }
+	| { kind: "failed" }
+	| { kind: "current"; latest: string }
+	| { kind: "available"; latest: string };
+
 /** A store holding at most one version. */
 export function createUpdateState(): UpdateSource {
 	let latest: string | undefined;

package/extensions/document/README.md

@@ -124,11 +124,12 @@ merged over the defaults and clamped:
 |---|---|---|---|
 | `maxFileBytes` | `20971520` (20 MiB) | 1 KiB – 512 MiB | Reject larger files. |
 | `maxChars` | `40000` | 200 – 100000 | Default slice size. |
+| `extractTimeoutMs` | `30000` (30 s) | 1 s – 5 min | Per-call extraction deadline; a parser that outlasts it is abandoned. |
 | `formats` | `{ "pdf": true, "docx": true, "doc": true, "odt": true, "rtf": true, "xlsx": true }` | — | Per-format on/off, merged over each registry entry's default; unknown keys are ignored. |
 
 ```jsonc
 // bytefly.json → "document"
-{ "maxChars": 80000, "formats": { "docx": false } }
+{ "maxChars": 80000, "extractTimeoutMs": 60000, "formats": { "docx": false } }
 ```
 
 `doc.json` is not read, and neither is the old per-extension `document.json`;
@@ -142,8 +143,9 @@ run `bun run config:migrate` to move a `document.json` into the shared file.
   `resolveEffectiveCwd`; absolute paths are allowed only inside it. Containment
   is symlink-aware (`isInsideReal`), and the real, resolved path is what the
   parser receives.
-- **Size-capped.** Files larger than `maxFileBytes` are rejected before any
-  parser runs.
+- **Size-capped and time-bounded.** Files larger than `maxFileBytes` are rejected
+  before any parser runs, and a parser that outlasts `extractTimeoutMs` is
+  abandoned so the turn is not held open by one document.
 - **No subprocesses.** Extraction never spawns a process, so it grants no
   privileges beyond the current process.
 - **Untrusted text.** Extracted document text is treated as untrusted: it is
@@ -171,6 +173,10 @@ Each extractor builds a plain-text document from the format's bytes:
 The tool is pageable across the whole extracted text, so a word-processing
 document or workbook is read in the same `startIndex` / `maxChars` way as a PDF.
 
+Each call is bounded by `extractTimeoutMs` (30 s by default). A parser that
+outlasts the deadline is abandoned — the read fails with the limit named, and a
+late result is discarded — so a pathological document cannot park the turn.
+
 ## Supported formats
 
 | Format | Extensions | Extractor | Enabled by default |
@@ -203,13 +209,17 @@ config defaults, and error listing all derive from it.
 
 - Parsing is best-effort and format-specific: output fidelity varies by library,
   and a malformed file fails with that library's message.
-- Legacy `.doc` relies on `word-extractor`; there is no fixture for the OLE
-  format in the test suite, so that path is covered only for its error case.
+- Legacy `.doc` relies on `word-extractor`, which now has a committed OLE fixture
+  (`test/helpers/fixtures/files/legacy.doc`, two paragraphs generated once by a
+  real word processor). Real Word 6/95 documents vary far more than one fixture
+  can show, so the format stays best-effort.
 - No OCR: scanned or image-only PDFs return little or no text.
 - Formatting, tables, and images are not preserved (XLSX keeps the row/column
   shape but drops cell styling and formulas; DOCX/ODT keep table cells as tabs).
-- No extraction timeout. `maxFileBytes` bounds the input, but a complex PDF can
-  be CPU-heavy; `maxChars` limits the returned slice, not peak extraction memory.
+- The deadline stops waiting and discards the result; it cannot preempt a parser
+  that never yields to the event loop, because JavaScript cannot interrupt a
+  synchronous parse. A worker thread could; the package does not use one.
+- `maxChars` limits the returned slice, not peak extraction memory.
 - Only one file per call; legacy `.xls` gets a conversion hint.
 
 ## Non-goals
@@ -285,8 +295,8 @@ bun test extensions/document
 ```
 
 Extractor tests run against real minimal files (`test/helpers/fixtures/documents.ts`
-builds a genuine PDF, DOCX, and ODT; XLSX is written with `exceljs`), so the
-libraries are exercised, not stubbed. `tool.test.ts` injects fake extractors for
-behavioural cases and reads one real PDF end to end;
-`test/helpers/fixtures/document.ts` provides the scratch root and an escape
-symlink.
+builds a genuine PDF, DOCX, and ODT; XLSX is written with `exceljs`; legacy `.doc`
+reads the committed `files/legacy.doc`), so the libraries are exercised, not
+stubbed. `tool.test.ts` injects fake extractors for behavioural cases and reads a
+real PDF and a real `.doc` end to end; `test/helpers/fixtures/document.ts`
+provides the scratch root and an escape symlink.

package/extensions/document/config.ts

@@ -15,6 +15,8 @@ export interface DocConfig {
 	maxFileBytes: number;
 	/** Default character budget for the returned slice. */
 	maxChars: number;
+	/** Per-call extraction deadline; a parser that outlasts it is abandoned. */
+	extractTimeoutMs: number;
 	/** Per-format on/off, merged over each registry entry's `defaultEnabled`. */
 	formats: Record<FormatId, boolean>;
 }
@@ -22,6 +24,7 @@ export interface DocConfig {
 export const DEFAULT_CONFIG: DocConfig = {
 	maxFileBytes: 20 * 1024 * 1024,
 	maxChars: 40_000,
+	extractTimeoutMs: 30_000,
 	formats: Object.fromEntries(FORMATS.map((format) => [format.id, format.defaultEnabled])) as Record<FormatId, boolean>,
 };
 
@@ -43,6 +46,7 @@ export function normalizeConfig(raw: Record<string, unknown> | undefined, base:
 	return {
 		maxFileBytes: clampInteger(raw.maxFileBytes, base.maxFileBytes, 1_024, 512 * 1024 * 1024),
 		maxChars: clampInteger(raw.maxChars, base.maxChars, 200, 100_000),
+		extractTimeoutMs: clampInteger(raw.extractTimeoutMs, base.extractTimeoutMs, 1_000, 300_000),
 		formats: normalizeFormats(raw.formats, base.formats),
 	};
 }

package/extensions/document/deadline.ts

@@ -0,0 +1,61 @@
+/**
+ * A per-call deadline for one in-process extraction.
+ *
+ * A parser is a library call, not a subprocess: JavaScript cannot preempt a
+ * synchronous parse, so the deadline stops *waiting* for the work and discards
+ * its result rather than killing it. What it guarantees is the turn: a
+ * pathological file fails with the limit named instead of parking the session,
+ * and a late settle from the abandoned promise never surfaces.
+ *
+ * The timer is a plain `setTimeout` cleared in `finally` (unlike
+ * `AbortSignal.timeout`, whose timer cannot be cancelled and would stay pending
+ * after every fast read). The deadline is deliberately not passed into `work`:
+ * the caller's abort signal is the only abort an extractor sees, so a timeout
+ * can never be reported as a turn abort or the reverse.
+ */
+
+/** How the deadline reports, and when to give up. */
+export interface DeadlineOptions {
+	/** Milliseconds to wait before abandoning the work. */
+	timeoutMs: number;
+	/** The error message a timeout throws; the caller names its own limit. */
+	timeoutMessage: string;
+	/** The turn's abort signal; an abort wins over the deadline. */
+	signal?: AbortSignal;
+}
+
+/**
+ * Run `work` with a deadline. Resolves with its value, rethrows its error
+ * unchanged, or rejects with `timeoutMessage` (or the caller's abort reason).
+ */
+export async function withDeadline<T>(work: () => Promise<T>, options: DeadlineOptions): Promise<T> {
+	const { timeoutMs, timeoutMessage, signal } = options;
+
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const expiry = new Promise<never>((_resolve, reject) => {
+		timer = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+		// A pending timer must not keep a short-lived process alive.
+		(timer as { unref?: () => void }).unref?.();
+	});
+
+	let onAbort: (() => void) | undefined;
+	const aborted = signal
+		? new Promise<never>((_resolve, reject) => {
+				onAbort = () => reject(signal.reason ?? new Error("aborted"));
+				if (signal.aborted) onAbort();
+				else signal.addEventListener("abort", onAbort, { once: true });
+			})
+		: undefined;
+
+	const pending = work();
+	// One observed promise: if the deadline or the abort wins, a late resolve or
+	// rejection from the abandoned work has nobody left to reach.
+	pending.catch(() => {});
+
+	try {
+		return await Promise.race(aborted ? [pending, expiry, aborted] : [pending, expiry]);
+	} finally {
+		clearTimeout(timer);
+		if (onAbort) signal?.removeEventListener("abort", onAbort);
+	}
+}

package/extensions/document/tool.ts

@@ -18,6 +18,7 @@ import { isInsideReal, realPathOfNearest } from "../../lib/path.ts";
 import { reuseText } from "../../lib/tui/chrome.ts";
 import { elapsedSuffix, reuseCallText, startToolProgress, syncElapsedTimer } from "../../lib/tui/tool.ts";
 import { isFormatEnabled, loadConfig } from "./config.ts";
+import { withDeadline } from "./deadline.ts";
 import type { DocExtractor } from "./extract/file.ts";
 import { detectFormat, supportedExtensions, unsupportedHint, type FormatId } from "./formats.ts";
 import { formatDoc } from "./paging.ts";
@@ -63,6 +64,8 @@ async function statFile(abs: string, display: string, maxFileBytes: number): Pro
 /** Per-format extractor overrides, for tests; the format table supplies the rest. */
 export interface DocToolDeps {
 	extractors?: Partial<Record<FormatId, DocExtractor>>;
+	/** Test seam: replace the configured `document.extractTimeoutMs`. */
+	timeoutMs?: number;
 }
 
 export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void {
@@ -71,7 +74,8 @@ export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void
 		label: "Read document",
 		description:
 			"Read a local PDF, DOCX, DOC, ODT, RTF, or XLSX file and return its extracted text, pageable with " +
-			"startIndex/maxChars. Extraction runs in process, so no external tools are needed.",
+			"startIndex/maxChars. Extraction runs in process, so no external tools are needed; a read that outlasts " +
+			"document.extractTimeoutMs fails with the limit named.",
 		promptSnippet: "Read a PDF, DOCX, DOC, ODT, RTF, or XLSX as text, paged with startIndex/maxChars.",
 		promptGuidelines: [
 			"Use read_doc for .pdf/.docx/.doc/.odt/.rtf/.xlsx; the built-in read tool is for text and images.",
@@ -101,8 +105,15 @@ export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void
 
 			const size = await statFile(abs, display, config.maxFileBytes);
 			const extractor = deps.extractors?.[format.id] ?? format.extract;
+			const timeoutMs = deps.timeoutMs ?? config.extractTimeoutMs;
 			startToolProgress(onUpdate);
-			const text = await extractor({ path: abs, signal });
+			const text = await withDeadline(() => extractor({ path: abs, signal }), {
+				timeoutMs,
+				signal,
+				timeoutMessage:
+					`Extraction of ${display} did not finish within ${timeoutMs} ms (document.extractTimeoutMs). ` +
+					`The ${format.label} parser was abandoned; raise the limit or read a smaller file.`,
+			});
 
 			const startIndex = typeof args.startIndex === "number" ? Math.max(0, Math.round(args.startIndex)) : 0;
 			const requested = typeof args.maxChars === "number" ? args.maxChars : config.maxChars;

package/extensions/file-browse/README.md

@@ -22,8 +22,9 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   opens the browser (unless `autoOpen: false`).
 - **Two-pane UI.** A server-rendered tree, directory listings, and file pages,
   progressively enhanced by one first-party script (filter, lazy tree
-  expansion, thumbnail fallback). Below 860px the tree collapses into a
-  `Files` disclosure above the listing. A hairline progress bar tracks whichever
+  expansion, thumbnail fallback). The tree scrolls in its own pane with quick
+  open and the filter pinned above it; below 860px it collapses into a `Files`
+  disclosure above the listing. A hairline progress bar tracks whichever
   column is scrolling (the card body for a file or diff, the main column
   otherwise), and the served folder names the root page.
 - **Rich previews.** Text, rendered Markdown, images (thumbnails), and
@@ -222,11 +223,14 @@ document and the project document (project wins):
   non-matching rows while keeping ancestors, disclosure triangles lazily
   `fetch("/api/tree")`, broken thumbnails fall back to the category icon, the
   listing headers sort in place, the wrap toggle is remembered, and the copy
-  buttons use the clipboard. Without JS the page still browses and renders
-  Markdown, and the JS-only controls (filter, disclosure, actions, quick open)
-  are hidden; the sort buttons lose their pointer so they do not look live. The
-  palette is the shared Bytefly web theme (`lib/web/tokens.ts`), derived from the
-  `bytefly-dark`/`bytefly-light` terminal themes; it follows
+  buttons use the clipboard. On wide screens the tree is its own scroll pane
+  under the pinned filter and quick-open trigger; the sidebar is a `<details>`
+  whose content wrapper has no definite height, so the panel fills it
+  absolutely and the tree flexes inside. Without JS the page still browses and
+  renders Markdown, and the JS-only controls (filter, disclosure, actions, quick
+  open) are hidden; the sort buttons lose their pointer so they do not look
+  live. The palette is the shared Bytefly web theme (`lib/web/tokens.ts`),
+  derived from the `bytefly-dark`/`bytefly-light` terminal themes; it follows
   `prefers-color-scheme` until an explicit choice sets `data-theme` on the root:
   `/theme.js` applies the saved choice in the head before first paint, and the
   header toggle flips and stores it (`pi-web-theme` in `localStorage`, the key
@@ -273,7 +277,7 @@ document and the project document (project wins):
   `--cached` before the first commit), `staged` against the index, and
   `worktree` against the index from the other side. An untracked file renders as
   all-add through `readFileView`, so binary and over-size handling is shared
-  with the file view. `git diff --shortstat` supplies the chip totals and
+  with the file view. `git diff --stat` supplies the chip totals and
   `changeDirs` derives the directory markers; the changed lines are highlighted
   per hunk by rebuilding the old and new sides for `lib/highlight`.
 - **Streaming responses.** The server streams `filePath` responses and