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

package/extensions/rewind/snapshot-run.ts

@@ -15,8 +15,11 @@ import { createSnapshotPolicy, type SnapshotPolicy } from "./policy.ts";
 import type { RewindRuntime } from "./runtime.ts";
 
 export interface SnapshotRun {
-	/** Start a run for `prompt`: reset run state and resolve the snapshot decision. */
-	beginRun(prompt: string, ctx: ExtensionContext): Promise<void>;
+	/**
+	 * Start a run for `prompt` — `undefined` when a custom message started it: reset
+	 * run state and resolve the snapshot decision.
+	 */
+	beginRun(prompt: string | undefined, ctx: ExtensionContext): Promise<void>;
 	/** Take the run's single snapshot before the first mutating call, at most once. */
 	onToolCall(toolName: string, ctx: ExtensionContext): Promise<void>;
 	/** Drop run-scoped state (on session shutdown). */

package/extensions/rewind/types.ts

@@ -53,6 +53,8 @@ export interface RestoreSummary {
 	changed: number;
 	/** Files deleted because they were created after the snapshot. */
 	removed: number;
+	/** Paths the whole diff touched, present only when a subset was restored. */
+	of?: number;
 	/** Id of the pre-restore safety snapshot, when one was taken. */
 	safety?: string;
 }

package/extensions/subagent/README.md

@@ -236,7 +236,13 @@ step's `Output`.
   they are not written to the parent session.
 - **No cost attribution to the parent session.** A subagent's tokens and cost are
   captured in the tool result and shown in the transcript, but they belong to a
-  separate process and are not added to the dispatching session's totals.
+  separate process and are not added to the dispatching session's totals. Instead,
+  each finished run publishes `my-pi-agent/subagent-finished`
+  (`SubagentFinishedEvent` in `lib/events.ts`) and bytefly's footer shows the
+  session's child runs as their own `↳` roll-up, priced separately from the
+  session total (the last 500 runs). The roll-up is per process: a resumed session
+  starts from zero, and a run that never produced an assistant message publishes
+  nothing.
 
 ## Pi integration
 

package/extensions/subagent/accounting.ts

@@ -0,0 +1,34 @@
+/**
+ * The accounting event a finished child run publishes.
+ *
+ * `subagent` runs each child in its own `pi` process, so the dispatcher's own
+ * usage totals never include what the child spent. The event carries the child's
+ * pricing inputs (provider, model, token counts, Pi's recorded dollar cost, finish
+ * time) rather than a total, so the consumer can price them with the same rate
+ * table and currency it uses for the session — and re-price them after a currency
+ * change.
+ *
+ * A run with no assistant message spent nothing observable (an unknown agent, a
+ * spawn failure), so it publishes nothing at all.
+ */
+
+import type { SubagentFinishedEvent } from "../../lib/events.ts";
+import type { SingleResult } from "./types.ts";
+
+/** The event for one finished run, or `null` when it produced no usage. */
+export function finishedEvent(result: SingleResult): SubagentFinishedEvent | null {
+	const { usage } = result;
+	if (usage.turns === 0) return null;
+	return {
+		agent: result.agent,
+		provider: result.provider ?? null,
+		model: result.model ?? null,
+		input: usage.input,
+		output: usage.output,
+		cacheRead: usage.cacheRead,
+		cacheWrite: usage.cacheWrite,
+		recordedCost: usage.cost,
+		at: result.finishedAt ?? null,
+		exitCode: result.exitCode,
+	};
+}

package/extensions/subagent/index.ts

@@ -27,6 +27,8 @@ import {
 } from "./agents.ts";
 import { runChainMode, runParallelMode, runSingleMode, type ModeContext } from "./orchestrate.ts";
 import { renderSubagentCall, renderSubagentResult } from "./render.ts";
+import { SUBAGENT_FINISHED_CHANNEL } from "../../lib/events.ts";
+import { finishedEvent } from "./accounting.ts";
 import { runSingleAgent, type RunOptions } from "./run.ts";
 import { SubagentParams, resolveMode, type SubagentArgs } from "./schema.ts";
 import type { DispatchDefaults, SingleResult, SubagentDetails } from "./types.ts";
@@ -65,7 +67,27 @@ function requestedAgentNames(args: SubagentArgs): string[] {
 
 export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): void {
 	if (!isExtensionEnabled("subagent")) return;
-	const run = deps.run ?? runSingleAgent;
+	const runner = deps.run ?? runSingleAgent;
+
+	/**
+	 * Account for each finished child, then hand the result on unchanged.
+	 *
+	 * Every mode (`single`, `parallel` per task, `chain` per step) calls this once
+	 * per child, so one wrapper reports each run exactly once. The emit is guarded:
+	 * a bus listener that throws must not fail a delegation that already ran.
+	 */
+	const run = async (options: RunOptions): Promise<SingleResult> => {
+		const result = await runner(options);
+		const event = finishedEvent(result);
+		if (event) {
+			try {
+				pi.events.emit(SUBAGENT_FINISHED_CHANNEL, event);
+			} catch {
+				// Accounting is best-effort; the run's own result is what matters.
+			}
+		}
+		return result;
+	};
 
 	pi.registerTool({
 		name: TOOL_NAME,

package/extensions/subagent/stream.ts

@@ -47,6 +47,7 @@ export function applyEvent(result: SingleResult, event: unknown): boolean {
 
 		if (message.role === "assistant") {
 			const assistant = message as Message & {
+				provider?: string;
 				model?: string;
 				stopReason?: string;
 				errorMessage?: string;
@@ -69,6 +70,7 @@ export function applyEvent(result: SingleResult, event: unknown): boolean {
 				result.usage.cost += usage.cost?.total ?? 0;
 				result.usage.contextTokens = usage.totalTokens ?? result.usage.contextTokens;
 			}
+			if (!result.provider && assistant.provider) result.provider = assistant.provider;
 			if (!result.model && assistant.model) result.model = assistant.model;
 			if (assistant.stopReason) result.stopReason = assistant.stopReason;
 			if (assistant.errorMessage) result.errorMessage = assistant.errorMessage;

package/extensions/subagent/types.ts

@@ -37,6 +37,8 @@ export interface SingleResult {
 	messages: Message[];
 	stderr: string;
 	usage: UsageStats;
+	/** Provider and model the child reported; published for the accounting event. */
+	provider?: string;
 	model?: string;
 	stopReason?: string;
 	errorMessage?: string;

package/extensions/watch/README.md

@@ -29,7 +29,10 @@ How the `watch` call and its result look in the transcript — the call line as
 - Shows a `⊚ N` running-watcher chip and a `! N` unreported-match chip, raises a
   `ctx.ui.notify` alert once per unreported burst, and offers a `/watch` screen.
 - Reports pending matches to the model at the start of the next turn, or wakes a
-  turn for a watcher added with `wake: true`.
+  turn for a watcher added with `wake: true`. A wake also leaves the terminal: the
+  match is announced on `my-pi-agent/watch-match`, which bytefly's
+  [notify](../bytefly/README.md#notifications) capability turns into a desktop
+  notification when `notify.enabled` and `notify.matchFound` are on.
 - Watchers are session-only: `shutdown` flushes a partial line, kills every
   command's process tree, and clears the chips.
 
@@ -162,12 +165,14 @@ other.
 - `matches` and `logs` keep bounded histories (`maxMatches`/`maxLogLines`), so
   older lines are dropped.
 - Matching is per line; a pattern cannot span a newline.
+- Only a **wake** match raises an OS notification, and only when bytefly's
+  `notify.enabled` and `notify.matchFound` are on. A match collected while the
+  agent was busy is reported at the next turn without a notification, and `watch`
+  itself never sends one — it announces the match and bytefly owns delivery.
 
 ## Non-goals
 
 - Persisting or reattaching watchers across sessions.
-- Notifying through bytefly's OS-notification capability (the `job` extension
-  owns that channel; `watch` alerts in-session with `ctx.ui.notify`).
 - Multiline or stateful matching, log rotation hooks, and per-watcher poll
   intervals.
 

package/extensions/watch/index.ts

@@ -12,6 +12,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
+import { WATCH_MATCH_CHANNEL, type WatchMatchEvent } from "../../lib/events.ts";
 import { sanitizeLine } from "../../lib/format.ts";
 import { noticeMessage, type NoticeMessage, pruneStaleNotices } from "../../lib/notice.ts";
 import { STATUS_KEYS } from "../../lib/tui/glyphs.ts";
@@ -80,6 +81,24 @@ export default function watch(pi: ExtensionAPI, deps: WatchDeps = {}): void {
 			waking = true;
 		} catch {
 			// Waking is best-effort; the next turn still reports the matches.
+			return;
+		}
+		// A wake means the user is away from the terminal, so the alert also leaves
+		// the process. bytefly's notify capability owns delivery; this publishes the
+		// fact and never learns how it is sent. The newest match is the one an alert
+		// is about, while the count covers the whole cycle.
+		const newest = pending[pending.length - 1];
+		if (!newest) return;
+		try {
+			const event: WatchMatchEvent = {
+				count: pending.length,
+				watcherId: newest.watcherId,
+				label: newest.label,
+				line: newest.line,
+			};
+			pi.events.emit(WATCH_MATCH_CHANNEL, event);
+		} catch {
+			// A throwing listener must not cost the wake that already happened.
 		}
 	};
 

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)) {