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

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,
@@ -74,8 +96,6 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 		promptSnippet: "Delegate a task to a specialized subagent with an isolated context window.",
 		promptGuidelines: GUIDELINES,
 		parameters: SubagentParams,
-		exposure: "direct",
-		defaultActive: true,
 		// Deliberately no `executionMode`: sibling subagent calls are independent
 		// (each spawns its own child process), so they stay parallel by default.
 		annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },

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/todo/README.md

@@ -41,9 +41,13 @@ How the `todo` call and its result look in the transcript — the call line as a
   mutating tool call (`write`/`edit`/`bash`/`powershell`, or a tool declaring
   `readOnlyHint: false`) without a todo update, it injects one hidden reminder
   and forces a single continuation. A failed or blocked call changed nothing, so
-  it never triggers one. It only fires while the list has unfinished items, at
-  most once per user turn, and is dropped on the next user turn, so a reader can
-  never trigger it.
+  it never triggers one. It fires while the list has unfinished items, and —
+  when no list exists at all — only after three such calls in one turn, at least
+  one of them a file write (`write`/`edit`, or a tool declaring
+  `readOnlyHint: false`), so repeated `bash` inspection is not mistaken for
+  unplanned work. A list the model wrote or cleared during the turn is left
+  alone. At most one reminder per user turn, and it is dropped on the next user
+  turn, so a reader can never trigger it.
 - Declares an `outputSchema` and returns matching `structuredContent`
   (`{ todos, action, error? }`), so codemode/scripts can read the list as data.
 
@@ -157,7 +161,7 @@ depends on config.
 
 | Integration point | Value |
 |---|---|
-| Tool | `todo`; `exposure: "direct"` (default), `executionMode: "sequential"` |
+| Tool | `todo`; direct exposure (the default), `executionMode: "sequential"` |
 | Annotations | `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` |
 | Output | `outputSchema` `TodoResult` — `{ todos, action, error? }` — also returned as `structuredContent` |
 | Command | `/todos` |
@@ -196,12 +200,16 @@ depends on config.
   [`lib/rails.ts`](../../lib/rails.ts) and [`goal`](../goal/).
 - **The reminder is a bounded nudge, not a nag.** A prompt guideline cannot
   guarantee a timely update, so the extension backs it with one forced
-  continuation. `tool_execution_end` marks a lag only for a successful call by
-  an explicit mutator list plus `readOnlyHint: false` — a failed or blocked call
-  is ignored, and a false positive costs a whole extra model request, so an
-  unrecognized reader is treated as harmless. `nudged` caps it at one per user
-  turn, `setTodos` clears the work flag, and `context` drops the hidden message
-  on the next user turn so it never accumulates.
+  continuation. `tool_execution_end` counts a successful call by an explicit
+  mutator list plus `readOnlyHint: false` — a failed or blocked call is ignored,
+  and a false positive costs a whole extra model request, so an unrecognized
+  reader is treated as harmless. An open item makes one call enough; a run with
+  no list at all must reach `EMPTY_LIST_MUTATIONS` (three) first and include a
+  file write, because a shell call cannot be told apart from `rg` and counts as
+  work but not as a write; a list the model wrote or cleared this turn is its own
+  answer and never reopens that path. `nudged` caps it at one per user turn,
+  `setTodos` clears the counters, and `context` drops the hidden message on the
+  next user turn so it never accumulates.
 - **Content is sanitized at the boundary.** `normalizeTodos` replaces control
   characters and collapses whitespace before the length and duplicate checks,
   keeping `format.ts` free of terminal concerns and every surface to one row
@@ -228,7 +236,7 @@ depends on config.
 | `types.ts` | `Todo`, `TodoStatus`, `TodoDetails`. |
 | `schema.ts` | TypeBox parameters and pure validation/normalization. |
 | `state.ts` | Branch reconstruction and status queries (pure). |
-| `nudge.ts` | Lag detection: mutating-tool classification, due check, reminder text (pure). |
+| `nudge.ts` | Lag detection: mutating and file-write classification, due check, reminder text (pure). |
 | `format.ts` | Model-facing and transcript text (pure). |
 | `tui.ts` | Widget and scrollable `/todos` components, drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
 | `config.ts` | Widget config load/validation (the `todo` section of `bytefly.json`). |

package/extensions/todo/index.ts

@@ -16,7 +16,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { isExtensionEnabled } from "../../lib/env.ts";
 import { registerCommands } from "./commands.ts";
 import { loadTodoConfig } from "./config.ts";
-import { formatNudge, isMutatingTool } from "./nudge.ts";
+import { formatNudge, isFileWrite, isMutatingTool } from "./nudge.ts";
 import { createTodoRuntime } from "./runtime.ts";
 import { registerTools } from "./tools.ts";
 
@@ -55,11 +55,13 @@ export default function todo(pi: ExtensionAPI) {
 
 	// Only work that can change the working tree sets the lag flag; read-only
 	// tools and the todo call itself are ignored. A failed or blocked call changed
-	// nothing, so it must not force a reminder.
+	// nothing, so it must not force a reminder. A shell call counts as work but
+	// not as a write: its name cannot tell `rg` from `git commit`.
 	pi.on("tool_execution_end", (event) => {
 		if (event.isError) return;
 		const annotations = pi.getAllTools().find((tool) => tool.name === event.toolName)?.annotations;
-		if (isMutatingTool(event.toolName, annotations)) runtime.noteWork();
+		if (!isMutatingTool(event.toolName, annotations)) return;
+		runtime.noteWork(isFileWrite(event.toolName, annotations));
 	});
 
 	// When the run is about to settle with unfinished work done since the last

package/extensions/todo/nudge.ts

@@ -18,12 +18,15 @@ import { TODO_TOOL } from "../../lib/tool-names.ts";
 import { currentTodo, hasOpenTodos } from "./state.ts";
 import type { Todo } from "./types.ts";
 
+/** Tools that run a command, where reading and writing look the same by name. */
+const SHELL_TOOL_NAMES: ReadonlySet<string> = new Set(["bash", "powershell"]);
+
 /**
  * Tools whose calls mean the working tree may have changed: the built-in
- * writers and shells. Kept explicit so a reader or an MCP tool that does not
+ * writers and the shells. Kept explicit so a reader or an MCP tool that does not
  * declare a hint cannot force a continuation.
  */
-export const MUTATING_TOOL_NAMES: ReadonlySet<string> = new Set(["write", "edit", "bash", "powershell"]);
+export const MUTATING_TOOL_NAMES: ReadonlySet<string> = new Set(["write", "edit", ...SHELL_TOOL_NAMES]);
 
 /**
  * Whether a finished tool call counts as work for lag detection. The `todo`
@@ -37,22 +40,68 @@ export function isMutatingTool(toolName: string, annotations?: ToolAnnotations):
 }
 
 /**
- * Whether a reminder is due: work happened since the last update, no reminder
- * was sent for it yet, and the list still has an unfinished item.
+ * Whether a finished tool call can have changed files, as opposed to a shell
+ * command that may only have read them. The reminder for a run that never
+ * started a list needs this: three `rg` calls are investigation, not unplanned
+ * work, and a shell call cannot be told apart from one that wrote. So it is a
+ * mutating call that is not a shell.
+ */
+export function isFileWrite(toolName: string, annotations?: ToolAnnotations): boolean {
+	if (toolName === TODO_TOOL || SHELL_TOOL_NAMES.has(toolName)) return false;
+	return isMutatingTool(toolName, annotations);
+}
+
+/**
+ * Successful mutating calls needed before a run with no list at all is worth a
+ * reminder. A plan that was never started has no item to fall behind, and a
+ * false positive costs a whole extra model request, so one edit is not enough
+ * evidence that the work needed a list.
+ */
+export const EMPTY_LIST_MUTATIONS = 3;
+
+/** What the current turn knows about its work and the list. */
+export interface NudgeState {
+	/** Successful mutating calls since the turn began or the list was last written. */
+	mutations: number;
+	/** How many of those can change files, as opposed to a shell command that may have read. */
+	writes: number;
+	/** Whether the model wrote or cleared the list since the turn began. */
+	touched: boolean;
+	/** Whether a reminder was already sent this turn. */
+	nudged: boolean;
+	/** The current list. */
+	todos: Todo[];
+}
+
+/**
+ * Whether a reminder is due. With an unfinished item, one mutation is enough.
+ * With no list at all, the turn must also have written something: repeated
+ * inspection with no file change is not unplanned work. A list the model wrote
+ * or cleared this turn is its own answer, so an explicit clear is never
+ * second-guessed.
  */
-export function shouldNudge(dirty: boolean, nudged: boolean, todos: Todo[]): boolean {
-	return dirty && !nudged && hasOpenTodos(todos);
+export function shouldNudge({ mutations, writes, touched, nudged, todos }: NudgeState): boolean {
+	if (nudged || mutations <= 0) return false;
+	if (hasOpenTodos(todos)) return true;
+	return todos.length === 0 && !touched && writes > 0 && mutations >= EMPTY_LIST_MUTATIONS;
 }
 
 /** Marker on the injected reminder, so it is recognizable and filterable. */
 export const TODO_NUDGE_MARKER = "[TODO SYNC]";
 
 /**
- * Model-facing reminder injected before settlement. Points at the item the list
- * currently considers active, so the model can correct it without rereading the
- * whole list.
+ * Model-facing reminder injected before settlement. For a list with unfinished
+ * work it points at the item the list currently considers active, so the model
+ * can correct it without rereading the whole list; for no list at all it asks
+ * for one.
  */
 export function formatNudge(todos: Todo[]): string {
+	if (todos.length === 0) {
+		return (
+			`${TODO_NUDGE_MARKER} Work happened but no todo list was recorded. ` +
+			"Call the todo tool with the steps of this work, then continue."
+		);
+	}
 	const current = currentTodo(todos);
 	const item = current ? (current.activeForm ?? current.content) : undefined;
 	const pointer = item ? ` The list still points at "${item}".` : "";

package/extensions/todo/runtime.ts

@@ -4,10 +4,10 @@
  *
  * The list is reconstructed from the active branch on session start and tree
  * navigation, and the persistent widget mirrors it whenever it changes. Only
- * interactive (`tui`) sessions get a widget; the widget's row budget and
- * whether a finished list stays visible come from the todo config. The same
- * runtime carries the lag-tracking flags the `agent_before_settle` reminder
- * reads, so they reset with the session and the branch.
+ * interactive (`tui`) sessions get a widget; whether a finished list stays
+ * visible comes from the todo config. The same runtime carries the lag-tracking
+ * counters the `agent_before_settle` reminder reads, so they reset with the
+ * session and the branch.
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -27,8 +27,8 @@ export interface TodoRuntime {
 	reconstruct(ctx: ExtensionContext): void;
 	/** Apply the widget config (loaded per session). */
 	setConfig(config: TodoConfig): void;
-	/** Record that a mutating tool ran since the last update. */
-	noteWork(): void;
+	/** Record a successful mutating call; `fileWrite` marks one that can change files. */
+	noteWork(fileWrite?: boolean): void;
 	/** Whether a lag reminder is due and has not been sent for it yet. */
 	nudgeDue(): boolean;
 	/** Mark the current lag as reminded, activating the injected reminder. */
@@ -53,11 +53,15 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 	let lastTuiCtx: ExtensionContext | undefined;
 	// True while a dock screen owns the editor slot; the rail stays hidden.
 	let suppressed = false;
-	// Lag tracking: `dirty` is set when a mutating tool runs and cleared by a
-	// todo update, `nudged` caps the reminder to one per user turn, and
-	// `nudgeActive` marks an injected reminder as current so `context` keeps it
-	// for the continuation and drops it on the next user turn.
-	let dirty = false;
+	// Lag tracking: `mutations` counts successful mutating calls since the list
+	// was last written and `writes` how many of those can change files,
+	// `touched` records that the model wrote or cleared the list this turn (so an
+	// explicit clear is not second-guessed), `nudged` caps the reminder to one per
+	// user turn, and `nudgeActive` marks an injected reminder as current so
+	// `context` keeps it for the continuation and drops it on the next user turn.
+	let mutations = 0;
+	let writes = 0;
+	let touched = false;
 	let nudged = false;
 	let nudgeActive = false;
 	// Screens watching the list (for example the open `/todos` screen) so they
@@ -104,13 +108,17 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 			todos = next;
 			// A todo update is the model syncing the list, so the lag is cleared.
 			// `nudged` is not: the reminder stays capped at one per user turn.
-			dirty = false;
+			mutations = 0;
+			writes = 0;
+			touched = true;
 			syncWidget(ctx);
 			notify();
 		},
 		reconstruct: (ctx) => {
 			todos = reconstructTodos(ctx.sessionManager.getBranch());
-			dirty = false;
+			mutations = 0;
+			writes = 0;
+			touched = false;
 			nudged = false;
 			nudgeActive = false;
 			syncWidget(ctx);
@@ -119,10 +127,11 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 		setConfig: (next) => {
 			config = next;
 		},
-		noteWork: () => {
-			dirty = true;
+		noteWork: (fileWrite = false) => {
+			mutations++;
+			if (fileWrite) writes++;
 		},
-		nudgeDue: () => shouldNudge(dirty, nudged, todos),
+		nudgeDue: () => shouldNudge({ mutations, writes, touched, nudged, todos }),
 		markNudged: () => {
 			nudged = true;
 			nudgeActive = true;
@@ -132,7 +141,9 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 		},
 		isNudgeActive: () => nudgeActive,
 		resetNudge: () => {
-			dirty = false;
+			mutations = 0;
+			writes = 0;
+			touched = false;
 			nudged = false;
 		},
 		onChange: (listener) => {

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.
@@ -96,7 +99,7 @@ and unknown keys are ignored.
 {
   "search": {
     "provider": "auto",                                    // "auto" | "duckduckgo" | "searxng" | "brave"
-    "endpoint": "http://localhost:8080",                   // SearXNG base URL; "" means SearXNG is unavailable
+    "endpoint": "",                                        // SearXNG base URL, e.g. "http://localhost:8080"; "" means SearXNG is unavailable
     "language": "auto",                                     // SearXNG: "auto" (zh-CN for Han, else en) | language code
     "safeSearch": 0,                                        // SearXNG: 0 off, 1 moderate, 2 strict
     "categories": "general",                                // SearXNG categories
@@ -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`.
@@ -264,9 +283,9 @@ the content type and size.
 
 | Integration point | Value |
 |---|---|
-| Tools | `web_search`, `web_fetch`; `exposure: "direct"`, both `defaultActive: true` |
+| Tools | `web_search`, `web_fetch`; direct exposure, active on registration (the defaults, so not declared) |
 | Execution mode | `web_search`: `sequential`; `web_fetch`: default |
-| Annotations | both `readOnlyHint: true`, `openWorldHint: true`, `destructiveHint: false` |
+| Annotations | both `readOnlyHint: true`, `openWorldHint: true`; a read-only tool declares no `destructiveHint` |
 | Output | `outputSchema` (`WebSearchOutput` / `WebFetchOutput`) plus matching `structuredContent` |
 | State | none in the session branch; one fetch page cache per registration (`web_search` keeps a per-instance throttle) |
 | Lifecycle | the factory only registers (`index.ts`); `registerFetchTool` owns the page cache and clears it on `session_start` and idempotent `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.