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

package/extensions/watch/runtime.ts

@@ -22,6 +22,8 @@ import type { PendingMatch, WatchMatch, WatchRecord, WatchSource } from "./types
 const MAX_CHUNK = 1024 * 1024;
 /** A line without a newline is flushed once it grows past this. */
 const MAX_LINE_BYTES = 1024 * 1024;
+/** Grace period before a stopped command is escalated to SIGKILL. */
+const KILL_GRACE_MS = 2000;
 
 /** Internal watcher state: the public record plus non-serializable fields. */
 interface Internal {
@@ -50,6 +52,7 @@ interface Internal {
 	rawLines: string[];
 	matches: WatchMatch[];
 	child?: SpawnedProcess;
+	killTimer?: ReturnType<typeof setTimeout>;
 	notified: boolean;
 	seq: number;
 }
@@ -95,6 +98,8 @@ export interface WatchRuntimeOptions {
 	config?: WatchConfig;
 	/** When false, never create a real interval; tests call `tick()` directly. */
 	autoClock?: boolean;
+	/** Grace before SIGTERM escalates to SIGKILL; default {@link KILL_GRACE_MS}. */
+	killGraceMs?: number;
 }
 
 export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRuntime {
@@ -103,6 +108,7 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	const now = options.now ?? (() => Date.now());
 	const fixedConfig = options.config;
 	const autoClock = options.autoClock ?? true;
+	const killGraceMs = options.killGraceMs ?? KILL_GRACE_MS;
 
 	let config: WatchConfig = fixedConfig ?? DEFAULT_CONFIG;
 	const watches = new Map<string, Internal>();
@@ -243,15 +249,60 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 		emit(w, rest, time);
 	};
 
-	const killChild = (w: Internal): void => {
+	const clearKillTimer = (w: Internal): void => {
+		if (w.killTimer) {
+			clearTimeout(w.killTimer);
+			w.killTimer = undefined;
+		}
+	};
+
+	const killChild = (w: Internal, signal: "SIGTERM" | "SIGKILL"): void => {
 		const pid = w.pid;
 		try {
-			if (pid !== undefined) killTree(pid, "SIGTERM");
-			else w.child?.kill("SIGTERM");
+			if (pid !== undefined) killTree(pid, signal, signal === "SIGKILL");
+			else w.child?.kill(signal);
 		} catch {
 			// Best-effort: the child may already be gone.
 		}
-		w.child = undefined;
+	};
+
+	/** SIGTERM a command, escalating to SIGKILL when it has not closed in time. */
+	const terminateChild = (w: Internal): void => {
+		clearKillTimer(w);
+		killChild(w, "SIGTERM");
+		if (w.pid === undefined && !w.child) return;
+		w.killTimer = setTimeout(() => {
+			w.killTimer = undefined;
+			if (w.child) killChild(w, "SIGKILL");
+		}, killGraceMs);
+		w.killTimer.unref?.();
+	};
+
+	/** Resolve when every command has closed, or after `ms`, whichever comes first. */
+	const waitForChildren = (watches: Internal[], ms: number): Promise<void> => {
+		const alive = watches.filter((w) => w.child !== undefined);
+		if (alive.length === 0) return Promise.resolve();
+		return new Promise((resolve) => {
+			let remaining = alive.length;
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const settle = (): void => {
+				if (--remaining > 0) return;
+				if (timer !== undefined) clearTimeout(timer);
+				resolve();
+			};
+			for (const w of alive) {
+				let done = false;
+				const once = (): void => {
+					if (done) return;
+					done = true;
+					settle();
+				};
+				w.child?.on("close", once);
+				w.child?.on("error", once);
+			}
+			timer = setTimeout(resolve, ms);
+			timer.unref?.();
+		});
 	};
 
 	const pollFile = (w: Internal, time: number): void => {
@@ -278,6 +329,9 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 			const read = readSync(fd, buffer, 0, length, w.offset);
 			w.offset += read;
 			consume(w, buffer.subarray(0, read), time);
+		} catch {
+			// The path can vanish or change type between stat and read (rotation, a
+			// replacement); skip this tick and pick it up next time.
 		} finally {
 			if (fd !== undefined) {
 				try {
@@ -305,22 +359,24 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 		child.stdout?.on("data", onData);
 		child.stderr?.on("data", onData);
 		child.on("close", (code, signal) => {
+			clearKillTimer(w);
+			w.child = undefined;
 			if (w.status !== "running") return;
 			flushPending(w, now());
 			w.status = "exited";
 			w.exitCode = code;
 			w.signal = signal;
 			w.endedAt = now();
-			w.child = undefined;
 			ui.paint();
 			if (runningCount() === 0) stopClock();
 		});
 		child.on("error", (error) => {
+			clearKillTimer(w);
+			w.child = undefined;
 			if (w.status !== "running") return;
 			w.status = "error";
 			w.error = error.message;
 			w.endedAt = now();
-			w.child = undefined;
 			ui.paint();
 			if (runningCount() === 0) stopClock();
 		});
@@ -337,6 +393,7 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	};
 
 	const add = (opts: AddWatchOptions, ctx: ExtensionContext): WatchRecord => {
+		if (!config.enabled) throw new Error("watch is disabled.");
 		if (watches.size >= config.maxWatchers) {
 			throw new Error(`at most ${config.maxWatchers} watchers; stop one first.`);
 		}
@@ -349,11 +406,13 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 					cwd: opts.cwd ? (isAbsolute(opts.cwd) ? opts.cwd : resolve(base, opts.cwd)) : base,
 				};
 		if (source.kind === "file") {
+			let info: ReturnType<typeof statSync>;
 			try {
-				statSync(source.path ?? "");
+				info = statSync(source.path ?? "");
 			} catch {
 				throw new Error(`file not found: ${source.path}`);
 			}
+			if (!info.isFile()) throw new Error(`not a regular file: ${source.path}`);
 		}
 		const caseSensitive = opts.caseSensitive ?? false;
 		const regex = compileRegex(opts.pattern, caseSensitive);
@@ -423,7 +482,7 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 		const w = watches.get(id);
 		if (!w || w.status !== "running") return false;
 		flushPending(w, now());
-		killChild(w);
+		terminateChild(w);
 		w.status = "stopped";
 		w.endedAt = now();
 		ui.paint();
@@ -473,7 +532,13 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	const load = (ctx: ExtensionContext): void => {
 		disposed = false;
 		stopClock();
-		for (const w of watches.values()) if (w.status === "running") killChild(w);
+		for (const w of watches.values()) {
+			if (w.status !== "running") continue;
+			w.status = "stopped";
+			clearKillTimer(w);
+			killChild(w, "SIGKILL");
+			w.child = undefined;
+		}
 		watches.clear();
 		counter = 0;
 		config = fixedConfig ?? loadConfig(ctx.cwd);
@@ -484,12 +549,18 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	const shutdown = async (): Promise<void> => {
 		disposed = true;
 		stopClock();
-		for (const w of watches.values()) {
-			if (w.status !== "running") continue;
+		const running = [...watches.values()].filter((w) => w.status === "running");
+		for (const w of running) {
 			flushPending(w, now());
-			killChild(w);
 			w.status = "stopped";
 			w.endedAt = now();
+			clearKillTimer(w);
+			killChild(w, "SIGTERM");
+		}
+		await waitForChildren(running, killGraceMs);
+		for (const w of running) {
+			clearKillTimer(w);
+			if (w.child) killChild(w, "SIGKILL");
 		}
 		watches.clear();
 		ui.detach();

package/extensions/web-access/README.md

@@ -28,6 +28,9 @@ How the `web_search` and `web_fetch` calls and their results look in the transcr
   always with no configuration required.
 - Registers `web_fetch`, which fetches a URL (GET or POST) and
   returns readable text with links kept as `[text](url)`.
+- Decodes by the byte-order mark, the declared `Content-Type` charset, or the
+  page's own `<meta charset>`, so a GBK/GB18030 page reads as text instead of
+  replacement characters.
 - Pages long output and reports the next `startIndex` (`nextIndex` in
   `structuredContent`); `find` returns matching passages instead of the whole
   page, and says when the match cap hid further hits.
@@ -148,6 +151,8 @@ as `Authorization: Bearer <key>`; for Brave it is sent as
   cannot redirect into a private address.
 - Transport headers (`Host`, `Content-Length`, `Connection`, `Transfer-Encoding`,
   and similar) are refused, and request bodies are capped.
+- `maxBytes` is enforced while the body streams in: a chunked or compressed
+  response is abandoned at the limit instead of being buffered whole.
 
 ## `web_search`
 
@@ -173,6 +178,13 @@ The SearXNG instance must have the **JSON API enabled** (`format=json` in its
 `settings.yml`); most public instances disable it, so a self-hosted instance is
 recommended. If the response is not JSON, the error says so.
 
+`run_doctor` reports what this session actually resolved to — the provider id and
+whether it came from an explicit choice, the `auto` rule, or the keyless default;
+the API-key variable when the provider takes one and no literal `apiKey` is set,
+and whether that variable is present; and, only on an explicit `refresh`, whether
+the configured `endpoint` answers. The key is never reported, only its variable
+name. See [`bytefly`](../bytefly/README.md#what-it-does) for the report.
+
 | Parameter | Type | Notes |
 |---|---|---|
 | `query` | string | 1–400 chars, required, any language |
@@ -200,7 +212,7 @@ address. Loopback, private, link-local, and cloud-metadata addresses are refused
 | `headers` | object | Extra request headers (transport headers are refused) |
 | `body` | string | POST body; implies `method: "POST"` unless set explicitly |
 | `startIndex` | integer | Code-point offset to start from (default 0) |
-| `maxChars` | integer | ≥200; capped by `maxOutputChars` |
+| `maxChars` | integer | ≥200; capped by `maxOutputChars`; also caps `find` output |
 | `find` | string[] | 1–10 strings; return matching passages instead of the page |
 | `mode` | enum | `insensitive` (default) \| `exact` \| `fuzzy` |
 | `contextChars` | integer | 0–2000 chars of context per match (default 200) |
@@ -209,10 +221,14 @@ address. Loopback, private, link-local, and cloud-metadata addresses are refused
 
 Long pages are paged: a truncated page names the `startIndex` to use next, inside
 its own character budget, and `structuredContent` repeats it as `nextIndex`.
-Fetched pages are cached for the registration, so paging and `find` do not
-refetch. POST responses and requests with custom headers are never cached.
+A `find` result spends the same `maxChars` budget: passages are added while they
+fit, and the note names `maxMatches` when the match cap hid the rest or
+`maxChars`/`contextChars` when the budget did. Fetched pages are cached for the
+registration, so paging and `find` do not refetch. POST responses and requests
+with custom headers are never cached.
 `structuredContent` is the page object, with an `error` field when the fetch
-failed and `matchesTruncated` when `maxMatches` capped the match list.
+failed and `matchesTruncated` when the match cap or the `maxChars` budget hid
+matches.
 
 ```
 web_fetch({ url: "https://pi.dev/" })
@@ -243,6 +259,9 @@ the content type and size.
 - **Heuristic extraction**: `web_fetch` strips scripts/styles/nav/footer and
   prefers `<main>`/`<article>`, but is not a full readability engine. PDF
   extraction is optional (`unpdf`) and off unless installed.
+- **`find` output is budgeted.** With `maxMatches: 50` and `contextChars: 2000`
+  the passages alone would exceed `maxOutputChars`; the result shows the passages
+  that fit and names the knob to change.
 - **The page cache is in-memory and per registration**; a page can be stale
   within a session. `refresh: true` refetches, and it is cleared on
   `session_start` and `session_shutdown`.
@@ -279,7 +298,12 @@ the content type and size.
   live at the top level (`text.ts`, `html.ts`, `transcript.ts`, `http.ts`).
 - **Shared transport.** [`http.ts`](./http.ts) holds the fetch runner
   (`HttpRunner`, `createFetchRunner`, HTTP error types), used by both halves and
-  injectable for tests.
+  injectable for tests. It reads the body through a byte-counting stream, so
+  `maxBytes` stops a chunked or compressed response before it is buffered whole.
+- **Charset-aware decoding.** [`charset.ts`](./charset.ts) is the one place a
+  byte body becomes text: BOM first, then the declared `Content-Type` charset,
+  then the page's own `<meta charset>`, then UTF-8. An unknown label falls back
+  to UTF-8 instead of failing the fetch.
 - **One config file, isolated sections.** `config.ts` reads the global then
   project file and validates each section with its half's normalizer; unknown
   keys and malformed files are ignored.
@@ -302,7 +326,11 @@ the content type and size.
   mutable is held at module scope.
 - **The paging budget is explicit.** `formatPage` counts the header and the
   truncation note against `maxChars`, so a paged page always carries its
-  `startIndex` hint inside the limit.
+  `startIndex` hint inside the limit. `formatMatches` applies the same rule to
+  `find`: it includes the passages that fit and names the knob that hid the rest.
+- **Code points without a copy.** [`text.ts`](./text.ts) counts and slices by
+  walking the string in place, so a multi-megabyte page is never expanded into an
+  array of one-character strings on every call.
 - **One JSON boundary per concern.** `search/json.ts` owns `requestJson` (status
   check and parse error) and `collectResults` (title + http(s) URL + de-dupe), so
   the three providers cannot drift on either.
@@ -321,7 +349,8 @@ the content type and size.
 |---|---|
 | `index.ts` | Register both tools |
 | `config.ts` | The `web-access` section of `bytefly.json` loader (via `lib/config.ts`) |
-| `http.ts` | Shared fetch runner and HTTP error types |
+| `http.ts` | Shared fetch runner and HTTP error types; caps the body while streaming |
+| `charset.ts` | Charset-aware body decoding (BOM, header, `<meta>`, UTF-8 fallback) |
 | `text.ts` | Shared code-point length, slice, and truncation helpers |
 | `html.ts` | Shared HTML entity decoding |
 | `transcript.ts` | Shared `oneLine` sanitizer for both transcript renderers |
@@ -353,11 +382,12 @@ the content type and size.
 `config.test.ts` and `index.test.ts`. It covers the shared runner (via injected
 `fetch`), the provider registry and resolution, each provider's URL builder and
 parser (DuckDuckGo, SearXNG, Brave), the orchestration pipeline and throttle,
-redirect re-validation (per-hop SSRF with literal IPs), method/header/body
-validation, the nested config merge and section isolation, extraction,
-formatting/paging through the tool (including a regression test that a truncated
-page keeps its `startIndex` hint), find and its cap notice, the per-registration
-cache, the SSRF guard, the injected PDF dependency, and both tools'
-registration/execution. Tests inject the runner, throttle, and PDF extractor
+charset decoding (declared, `<meta>`, and BOM precedence), a streamed body over
+the byte cap, redirect re-validation (per-hop SSRF with literal IPs),
+method/header/body validation, the nested config merge and section isolation,
+extraction, formatting/paging through the tool (including a regression test that
+a truncated page keeps its `startIndex` hint), find and its cap/budget notices,
+the per-registration cache, the SSRF guard, the injected PDF dependency, and both
+tools' registration/execution. Tests inject the runner, throttle, and PDF extractor
 through the tools' dependencies, so no network or PDF library is needed; the
 runtime smoke test only asserts registration.

package/extensions/web-access/charset.ts

@@ -0,0 +1,58 @@
+/**
+ * Charset-aware body decoding shared by the web-access halves.
+ *
+ * HTTP lets a response name its encoding in `Content-Type`, and an HTML page can
+ * name one in its markup, so decoding every body as UTF-8 turns a GBK/GB18030
+ * page into replacement characters. `http.ts` honours the BOM and the declared
+ * charset; `page.ts` adds the `<meta charset>` fallback for HTML. An unknown
+ * label falls back to UTF-8 instead of failing the fetch.
+ */
+
+const FALLBACK_CHARSET = "utf-8";
+
+/** How much of an HTML document is scanned for a `<meta charset>` declaration. */
+const SNIFF_BYTES = 4096;
+
+/** The `charset` parameter of a content type, lowercased. */
+export function charsetOf(contentType: string): string | undefined {
+	const match = /;\s*charset\s*=\s*"?([^";\s]+)"?/i.exec(contentType);
+	return match?.[1]?.toLowerCase();
+}
+
+/** The charset a leading byte-order mark declares. */
+export function bomCharset(bytes: Uint8Array): string | undefined {
+	if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return "utf-8";
+	if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) return "utf-16le";
+	if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) return "utf-16be";
+	return undefined;
+}
+
+/**
+ * The charset a document declares in its first few kilobytes. Both
+ * `<meta charset="gbk">` and `<meta http-equiv="content-type" content="text/html; charset=gbk">`
+ * are matched by the same `charset=` scan.
+ */
+export function sniffHtmlCharset(bytes: Uint8Array): string | undefined {
+	// Latin-1 keeps every byte addressable and ASCII tags intact.
+	const head = new TextDecoder("latin1").decode(bytes.subarray(0, SNIFF_BYTES));
+	const match = /<meta[^>]+charset\s*=\s*["']?\s*([a-z0-9_.:-]+)/i.exec(head);
+	return match?.[1]?.toLowerCase();
+}
+
+/** The label type `TextDecoder` accepts; a runtime label is validated by the constructor. */
+type DecoderLabel = ConstructorParameters<typeof TextDecoder>[0];
+
+/** Decode bytes with `charset`, falling back to UTF-8 for an absent or unknown label. */
+export function decodeBytes(bytes: Uint8Array, charset?: string): string {
+	if (!charset) return new TextDecoder(FALLBACK_CHARSET).decode(bytes);
+	try {
+		return new TextDecoder(charset as DecoderLabel).decode(bytes);
+	} catch {
+		return new TextDecoder(FALLBACK_CHARSET).decode(bytes);
+	}
+}
+
+/** Decode an HTML body: BOM first, then the declared charset, then its own `<meta>`, then UTF-8. */
+export function decodeHtml(bytes: Uint8Array, contentType: string): string {
+	return decodeBytes(bytes, bomCharset(bytes) ?? charsetOf(contentType) ?? sniffHtmlCharset(bytes));
+}

package/extensions/web-access/fetch/find.ts

@@ -13,7 +13,7 @@
  * model already receives, not the raw HTML.
  */
 
-import { toChars } from "../text.ts";
+import { charLength, sliceChars } from "../text.ts";
 
 export type FindMode = "insensitive" | "exact" | "fuzzy";
 
@@ -46,12 +46,12 @@ export function toCodePointOffset(text: string, utf16Index: number): number {
 	return offset;
 }
 
-function passageAround(points: string[], start: number, end: number, contextChars: number): string {
+function passageAround(text: string, start: number, end: number, contextChars: number, total: number): string {
 	const from = Math.max(0, start - contextChars);
-	const to = Math.min(points.length, end + contextChars);
+	const to = Math.min(total, end + contextChars);
 	const prefix = from > 0 ? "…" : "";
-	const suffix = to < points.length ? "…" : "";
-	return `${prefix}${points.slice(from, to).join("").trim()}${suffix}`;
+	const suffix = to < total ? "…" : "";
+	return `${prefix}${sliceChars(text, from, to).trim()}${suffix}`;
 }
 
 function substringMatches(text: string, query: string, insensitive: boolean): Array<[number, number]> {
@@ -131,7 +131,7 @@ function fuzzyMatches(text: string, query: string): Array<[number, number]> {
  */
 export function findPassages(text: string, queries: string[], options: FindOptions): Passage[] {
 	if (text.length === 0) return [];
-	const points = toChars(text);
+	const total = charLength(text);
 	const results: Passage[] = [];
 	const seen = new Set<string>();
 
@@ -150,7 +150,11 @@ export function findPassages(text: string, queries: string[], options: FindOptio
 			if (seen.has(key)) continue;
 			seen.add(key);
 			const endOffset = toCodePointOffset(text, end);
-			results.push({ query: trimmed, offset, passage: passageAround(points, offset, endOffset, options.contextChars) });
+			results.push({
+				query: trimmed,
+				offset,
+				passage: passageAround(text, offset, endOffset, options.contextChars, total),
+			});
 		}
 	}
 

package/extensions/web-access/fetch/format.ts

@@ -5,10 +5,14 @@
  * and the truncation note — within `maxChars`. The header and the note are
  * counted against the budget up front, so the "call web_fetch again with
  * startIndex=" instruction always survives inside the limit.
- * `formatMatches` renders find-in-page passages with their offsets.
+ *
+ * `formatMatches` renders find-in-page passages with their offsets inside the
+ * same budget: it includes as many passages as fit and says which knob to turn
+ * when it had to drop the rest, rather than returning every match the caller
+ * allowed.
  */
 
-import { charLength, toChars } from "../text.ts";
+import { charLength, sliceChars, truncateChars } from "../text.ts";
 import type { Passage } from "./find.ts";
 
 interface PageFormatInput {
@@ -46,8 +50,7 @@ function truncationNote(nextIndex: number, total: number): string {
 }
 
 export function formatPage(input: PageFormatInput): FormattedPage {
-	const points = toChars(input.text);
-	const total = points.length;
+	const total = charLength(input.text);
 	const header = pageHeader(input.title, input.finalUrl, input.status, input.contentType);
 
 	if (total === 0) {
@@ -68,15 +71,14 @@ export function formatPage(input: PageFormatInput): FormattedPage {
 	// `total` for both offsets gives the widest digit count) so the hint survives.
 	const plainCapacity = Math.max(1, input.maxChars - charLength(header) - 2);
 	if (input.startIndex + plainCapacity >= total) {
-		const body = points.slice(input.startIndex).join("");
+		const body = sliceChars(input.text, input.startIndex);
 		return { body, text: `${header}\n\n${body}`, truncated: false, nextIndex: input.startIndex };
 	}
 
 	const reserve = charLength(header) + 2 + charLength(truncationNote(total, total));
 	const capacity = Math.max(1, input.maxChars - reserve);
-	const slicePoints = points.slice(input.startIndex, input.startIndex + capacity);
-	const body = slicePoints.join("");
-	const nextIndex = input.startIndex + slicePoints.length;
+	const body = sliceChars(input.text, input.startIndex, input.startIndex + capacity);
+	const nextIndex = input.startIndex + charLength(body);
 	const text = `${header}\n\n${body}${truncationNote(nextIndex, total)}`;
 
 	return { body, text, truncated: true, nextIndex };
@@ -89,15 +91,21 @@ interface MatchFormatInput {
 	contentType: string;
 	matches: Passage[];
 	find: string[];
-	/** True when the match list was capped by `maxMatches`. */
-	truncated: boolean;
+	/** Budget for the whole formatted result: header, passages, and note. */
+	maxChars: number;
+	/** True when the provider capped the list at `maxMatches`. */
+	cappedByMaxMatches: boolean;
 }
 
 interface FormattedMatches {
+	/** The passages that fit, rendered one per block. */
 	body: string;
+	/** Header, passages, and any truncation note. */
 	text: string;
-	/** True when the match list was capped by `maxMatches`. */
+	/** True when anything was hidden: the match cap, the budget, or an oversized passage. */
 	truncated: boolean;
+	/** The passages `body` and `text` actually contain. */
+	included: Passage[];
 }
 
 export function formatMatches(input: MatchFormatInput): FormattedMatches {
@@ -105,13 +113,51 @@ export function formatMatches(input: MatchFormatInput): FormattedMatches {
 	const header = `${pageHeader(input.title, input.finalUrl, input.status, input.contentType)}\nMatches for ${quoted}: ${input.matches.length}`;
 
 	if (input.matches.length === 0) {
-		return { body: "", text: `${header}\n\nNo matches.`, truncated: false };
+		return { body: "", text: `${header}\n\nNo matches.`, truncated: false, included: [] };
 	}
 
-	const body = input.matches
-		.map((match, index) => `${index + 1}. [offset ${match.offset}] ${match.passage}`)
-		.join("\n\n");
-	let text = `${header}\n\n${body}`;
-	if (input.truncated) text += `\n\n(first ${input.matches.length} matches; raise maxMatches for more)`;
-	return { body, text, truncated: input.truncated };
+	const blocks = input.matches.map((match, index) => `${index + 1}. [offset ${match.offset}] ${match.passage}`);
+
+	// Add whole blocks while they fit; the first one is kept even when oversized.
+	const shown: string[] = [];
+	let size = charLength(header) + 2;
+	for (const block of blocks) {
+		const length = charLength(block);
+		if (shown.length > 0 && size + length + 2 > input.maxChars) break;
+		shown.push(block);
+		size += length + 2;
+	}
+
+	const noteFor = (count: number): string => {
+		if (count < blocks.length) {
+			return `(showing ${count} of ${blocks.length} matches within ${input.maxChars} characters; narrow find or lower contextChars)`;
+		}
+		if (input.cappedByMaxMatches) return `(first ${count} matches; raise maxMatches for more)`;
+		return "";
+	};
+	const render = (count: number, note: string): string => {
+		const base = `${header}\n\n${shown.slice(0, count).join("\n\n")}`;
+		return note ? `${base}\n\n${note}` : base;
+	};
+
+	// The note must survive the budget too, so drop trailing passages until it fits.
+	let count = shown.length;
+	let note = noteFor(count);
+	while (count > 1 && charLength(render(count, note)) > input.maxChars) {
+		count--;
+		note = noteFor(count);
+	}
+	if (note && charLength(render(count, note)) > input.maxChars) note = "";
+
+	let text = render(count, note);
+	const overflow = charLength(text) > input.maxChars;
+	if (overflow) text = truncateChars(text, input.maxChars);
+
+	const body = shown.slice(0, count).join("\n\n");
+	return {
+		body,
+		text,
+		truncated: count < blocks.length || input.cappedByMaxMatches || overflow,
+		included: input.matches.slice(0, count),
+	};
 }

package/extensions/web-access/fetch/page.ts

@@ -13,6 +13,7 @@ import type { WebFetchConfig } from "./config.ts";
 import { extractReadable } from "./extract.ts";
 import { extractPdfText, type PdfExtractor } from "./pdf.ts";
 import { createFetchRunner, type HttpRunner, type HttpResponse } from "../http.ts";
+import { decodeHtml } from "../charset.ts";
 import { assertAllowedUrl } from "./ssrf.ts";
 import type { FetchRequest } from "./types.ts";
 
@@ -149,7 +150,10 @@ export async function runFetch(
 			text = `(binary content: ${response.contentType || "application/pdf"}, ${response.sizeBytes} bytes; PDF text extraction failed: ${reason})`;
 		}
 	} else if (isHtmlType(response.contentType)) {
-		const page = extractReadable(response.body, response.finalUrl);
+		// `bytes` carries the raw body, so a page that declares GBK in a `<meta>` tag
+		// but not in the header is still decoded correctly.
+		const html = response.bytes ? decodeHtml(response.bytes, response.contentType) : response.body;
+		const page = extractReadable(html, response.finalUrl);
 		title = page.title;
 		text = page.text;
 	} else if (isTextualType(response.contentType)) {

package/extensions/web-access/fetch/tool.ts

@@ -27,7 +27,7 @@ import { charLength } from "../text.ts";
 import { oneLine } from "../transcript.ts";
 import { createPageCache, type PageCache } from "./cache.ts";
 import type { WebFetchConfig } from "./config.ts";
-import { findPassages } from "./find.ts";
+import { findPassages, type Passage } from "./find.ts";
 import { formatMatches, formatPage } from "./format.ts";
 import { runFetch, type FetchDeps, type PageResult } from "./page.ts";
 import { resolveRequest, WebFetchOutput, WebFetchParams, type FetchResponse, type WebFetchArgs } from "./schema.ts";
@@ -85,29 +85,33 @@ async function loadPage(
 function pageResult(loaded: LoadedPage, request: FetchRequest): { response: FetchResponse; text: string } {
 	const { page, cached, fetchedAt } = loaded;
 	const finding = request.find.length > 0;
-	const matches = finding
-		? findPassages(page.text, request.find, {
-				mode: request.mode,
-				contextChars: request.contextChars,
-				maxMatches: request.maxMatches + 1,
-			})
-		: [];
-	// Request one extra so a full list proves more hits exist; only the cap is shown.
-	const matchesTruncated = finding && matches.length > request.maxMatches;
-	const visibleMatches = matchesTruncated ? matches.slice(0, request.maxMatches) : matches;
 
 	let formatted: { body: string; text: string; truncated: boolean };
 	let nextIndex: number;
+	let matches: Passage[] = [];
+	let matchesTruncated = false;
+
 	if (finding) {
-		formatted = formatMatches({
+		// Request one extra so a full list proves more hits exist; only the cap is shown.
+		const found = findPassages(page.text, request.find, {
+			mode: request.mode,
+			contextChars: request.contextChars,
+			maxMatches: request.maxMatches + 1,
+		});
+		const cappedByMaxMatches = found.length > request.maxMatches;
+		const rendered = formatMatches({
 			finalUrl: page.finalUrl,
 			title: page.title,
 			status: page.status,
 			contentType: page.contentType,
-			matches: visibleMatches,
+			matches: cappedByMaxMatches ? found.slice(0, request.maxMatches) : found,
 			find: request.find,
-			truncated: matchesTruncated,
+			maxChars: request.maxChars,
+			cappedByMaxMatches,
 		});
+		formatted = rendered;
+		matches = rendered.included;
+		matchesTruncated = rendered.truncated;
 		// Find results are not paged, so the caller keeps reading from the same offset.
 		nextIndex = request.startIndex;
 	} else {
@@ -136,7 +140,7 @@ function pageResult(loaded: LoadedPage, request: FetchRequest): { response: Fetc
 		nextIndex,
 		truncated: formatted.truncated,
 		cached,
-		matches: visibleMatches,
+		matches,
 		matchesTruncated,
 		fetchedAt,
 		error: "",
@@ -192,9 +196,6 @@ export function registerFetchTool(pi: ExtensionAPI, deps: FetchToolDeps = {}): v
 		parameters: WebFetchParams,
 		outputSchema: WebFetchOutput,
 		annotations: { readOnlyHint: true, openWorldHint: true },
-		// The page cache is shared in-memory state created per registration, so
-		// sibling calls must not run concurrently (matches web_search's throttle).
-		executionMode: "sequential",
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const config = loadFetchConfig(ctx.cwd);