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

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: "",
@@ -191,12 +195,7 @@ export function registerFetchTool(pi: ExtensionAPI, deps: FetchToolDeps = {}): v
 		],
 		parameters: WebFetchParams,
 		outputSchema: WebFetchOutput,
-		exposure: "direct",
-		defaultActive: true,
-		annotations: { readOnlyHint: true, openWorldHint: true, destructiveHint: false },
-		// 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",
+		annotations: { readOnlyHint: true, openWorldHint: true },
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const config = loadFetchConfig(ctx.cwd);

package/extensions/web-access/http.ts

@@ -3,10 +3,12 @@
  *
  * No `curl`, no dependencies: one `fetch` call per request (with optional
  * manual redirect handling) with a combined caller-signal and timeout, optional
- * request body, and a size cap. `HttpRunner` is the seam tests use to avoid the
- * network.
+ * request body, and a size cap enforced while the body is read. `HttpRunner` is
+ * the seam tests use to avoid the network.
  */
 
+import { bomCharset, charsetOf, decodeBytes } from "./charset.ts";
+
 /** A request to send. */
 interface HttpRequest {
 	url: string;
@@ -15,7 +17,7 @@ interface HttpRequest {
 	/** Raw request body (for example a JSON-RPC payload). */
 	body?: string;
 	timeoutMs: number;
-	/** Maximum response size in bytes; larger responses raise `HttpTooLargeError`. */
+	/** Maximum response size in bytes, enforced while the body is read. */
 	maxBytes?: number;
 	/** Redirect handling: `"follow"` (default) or `"manual"` to inspect each hop. */
 	redirect?: "follow" | "manual";
@@ -63,6 +65,48 @@ export class HttpUnavailableError extends Error {
 	}
 }
 
+/**
+ * Concatenate chunks into one buffer. `total` is the caller's running byte count,
+ * so the allocation happens once rather than growing an array per chunk.
+ */
+function concatChunks(chunks: Uint8Array[], total: number): Uint8Array {
+	const merged = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		merged.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return merged;
+}
+
+/**
+ * Read a response body to completion, aborting the read as soon as it exceeds
+ * `maxBytes`. `response.arrayBuffer()` would buffer a whole chunked or
+ * compressed response first, which is the case the cap exists to prevent.
+ */
+async function readCappedBody(response: Response, maxBytes?: number): Promise<Uint8Array> {
+	if (!response.body) {
+		const bytes = new Uint8Array(await response.arrayBuffer());
+		if (maxBytes !== undefined && bytes.byteLength > maxBytes) throw new HttpTooLargeError(maxBytes);
+		return bytes;
+	}
+
+	const reader = response.body.getReader();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (maxBytes !== undefined && total > maxBytes) {
+			await reader.cancel().catch(() => undefined);
+			throw new HttpTooLargeError(maxBytes);
+		}
+		chunks.push(value);
+	}
+	return concatChunks(chunks, total);
+}
+
 /**
  * Create a runner backed by `fetch`.
  *
@@ -103,11 +147,8 @@ export function createFetchRunner(fetchImpl: typeof fetch = globalThis.fetch): H
 				throw new HttpTooLargeError(request.maxBytes);
 			}
 
-			const bytes = new Uint8Array(await response.arrayBuffer());
-			if (request.maxBytes !== undefined && bytes.byteLength > request.maxBytes) {
-				throw new HttpTooLargeError(request.maxBytes);
-			}
-			const body = new TextDecoder().decode(bytes);
+			const bytes = await readCappedBody(response, request.maxBytes);
+			const body = decodeBytes(bytes, bomCharset(bytes) ?? charsetOf(contentType));
 			const location = response.headers.get("location") ?? undefined;
 
 			return {

package/extensions/web-access/search/facts.ts

@@ -0,0 +1,38 @@
+/**
+ * What `web_search` resolved to, published for `doctor`.
+ *
+ * The provider registry, each provider's `isConfigured`, and the `auto`
+ * resolution rule all live in this extension, so this module is where the facts
+ * for a diagnostic come from. It publishes a summary only — the key itself never
+ * leaves the extension, just the variable name and whether a literal key exists.
+ *
+ * `endpoint` is deliberately null for the providers without a configurable
+ * endpoint: probing an API host would report a 401 as a failure for a provider
+ * that works, and there is nothing for the user to fix.
+ */
+
+import type { WebSearchProviderEvent } from "../../../lib/events.ts";
+import type { WebSearchConfig } from "./config.ts";
+import { DEFAULT_PROVIDER_ID, resolveProvider } from "./registry.ts";
+
+/**
+ * The facts for one session's config. `reason` distinguishes an explicit choice
+ * from the auto rule, so a report can tell "you asked for this and it is not
+ * configured" from "this is the keyless fallback".
+ */
+export function providerFacts(config: WebSearchConfig): WebSearchProviderEvent {
+	const provider = resolveProvider(config);
+	// `auto` only leaves the keyless default when another provider is configured,
+	// so the resolved id tells the two apart.
+	const reason: WebSearchProviderEvent["reason"] =
+		config.provider !== "auto" ? "explicit" : provider.id === DEFAULT_PROVIDER_ID ? "default" : "configured";
+	return {
+		provider: provider.id,
+		reason,
+		configured: provider.isConfigured(config),
+		// Only SearXNG's base URL is a setting a user can get wrong.
+		endpoint: provider.id === "searxng" && config.endpoint !== "" ? config.endpoint : null,
+		apiKeyEnv: config.apiKeyEnv || null,
+		keyConfigured: config.apiKey.trim() !== "",
+	};
+}

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

@@ -8,6 +8,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { WEB_SEARCH_PROVIDER_CHANNEL } from "../../../lib/events.ts";
 import { loadSearchConfig } from "../config.ts";
 import { oneLine } from "../transcript.ts";
 import { reuseText } from "../../../lib/tui/chrome.ts";
@@ -21,6 +22,7 @@ import {
 } from "../../../lib/tui/tool.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
 import { expandHint, SEPARATORS } from "../../../lib/tui/glyphs.ts";
+import { providerFacts } from "./facts.ts";
 import { formatResults } from "./format.ts";
 import { createThrottle, runSearch, type SearchDeps } from "./search.ts";
 import { resolveRequest, WebSearchOutput, WebSearchParams, type SearchResponse, type WebSearchArgs } from "./schema.ts";
@@ -32,6 +34,17 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 	// without any module-level state.
 	const runDeps: SearchDeps = { http: deps.http, throttle: deps.throttle ?? createThrottle() };
 
+	// Publish what this session resolved to, so `doctor` can report the provider,
+	// its key, and its endpoint without importing this extension. Accounting only:
+	// a bus listener that throws must not break the tool.
+	pi.on("session_start", (_event, ctx) => {
+		try {
+			pi.events.emit(WEB_SEARCH_PROVIDER_CHANNEL, providerFacts(loadSearchConfig(ctx.cwd)));
+		} catch {
+			// Diagnostics are best-effort.
+		}
+	});
+
 	pi.registerTool({
 		name: TOOL_NAME,
 		label: "Web search",
@@ -46,9 +59,7 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 		],
 		parameters: WebSearchParams,
 		outputSchema: WebSearchOutput,
-		exposure: "direct",
-		defaultActive: true,
-		annotations: { readOnlyHint: true, openWorldHint: true, destructiveHint: false },
+		annotations: { readOnlyHint: true, openWorldHint: true },
 		executionMode: "sequential",
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {

package/extensions/web-access/text.ts

@@ -3,24 +3,63 @@
  *
  * Character budgets are counted in code points, not UTF-16 units, so a slice
  * never splits a CJK character or an emoji, and a declared limit is honoured for
- * the text the model sees. `web_search` and `web_fetch` measure and slice here
- * rather than re-deriving `Array.from` at each site.
+ * the text the model sees. Everything here walks the string in place: a
+ * multi-megabyte page is never materialised as an array of one-character
+ * strings, which is what `Array.from(text)` would cost on every call.
  */
 
-/** Split text into code points (an array of one-code-point strings). */
-export function toChars(text: string): string[] {
-	return Array.from(text);
-}
+const SURROGATE = /[\uD800-\uDFFF]/;
 
 /** Length of text in code points. */
 export function charLength(text: string): number {
-	return Array.from(text).length;
+	// A native scan with no allocation covers the common all-BMP page.
+	if (!SURROGATE.test(text)) return text.length;
+
+	let count = 0;
+	for (let i = 0; i < text.length; i++) {
+		const code = text.charCodeAt(i);
+		if (code >= 0xd800 && code <= 0xdbff) {
+			const next = text.charCodeAt(i + 1);
+			if (next >= 0xdc00 && next <= 0xdfff) i++;
+		}
+		count++;
+	}
+	return count;
+}
+
+/**
+ * Slice text by code-point offsets, like `Array.from(text).slice(from, to).join("")`
+ * without building the array. Out-of-range offsets clamp, and `to` defaults to
+ * the end of the string.
+ */
+export function sliceChars(text: string, from: number, to: number = Number.POSITIVE_INFINITY): string {
+	const start = Math.max(0, Math.floor(from));
+	const end = Math.max(start, Math.floor(to));
+	if (start === 0 && end >= text.length) return text;
+
+	let startIndex = text.length;
+	let endIndex = text.length;
+	let codePoint = 0;
+	for (let i = 0; i < text.length; i++) {
+		if (codePoint === start && startIndex === text.length) startIndex = i;
+		if (codePoint === end) {
+			endIndex = i;
+			break;
+		}
+		const code = text.charCodeAt(i);
+		if (code >= 0xd800 && code <= 0xdbff) {
+			const next = text.charCodeAt(i + 1);
+			if (next >= 0xdc00 && next <= 0xdfff) i++;
+		}
+		codePoint++;
+	}
+	return text.slice(startIndex, endIndex);
 }
 
 /** Truncate to `maxChars` code points, appending `marker` when anything was cut. */
 export function truncateChars(text: string, maxChars: number, marker = "…"): string {
-	const points = toChars(text);
-	if (points.length <= maxChars) return text;
-	if (maxChars <= marker.length) return marker;
-	return `${points.slice(0, maxChars - marker.length).join("")}${marker}`;
+	if (charLength(text) <= maxChars) return text;
+	const markerLength = charLength(marker);
+	if (maxChars <= markerLength) return marker;
+	return `${sliceChars(text, 0, maxChars - markerLength)}${marker}`;
 }

package/extensions/wechat/README.md

@@ -272,7 +272,7 @@ overridden by the project `<cwd>/.pi/bytefly.json` (project wins):
   "maxInboundChars": 8000, // inbound text longer than this is truncated
   "typingIndicator": true,   // show typing while a turn is generated
   "remotePrompts": true,     // answer interactive dialogs on WeChat during a WeChat turn
-  "pollHoldMs": 0            // experimental: ask the server for a shorter long-poll hold
+  // "pollHoldMs": 3000      // experimental: request a shorter long-poll hold; unset by default
 }
 ```
 
@@ -392,8 +392,9 @@ never touches the stored cursor.
   supplies a `context_token` only then).
 - Slash commands are fixed built-ins; there is no user-defined snippet or action
   list yet, and `/new`, `/stop`, `/status`, and `/help` are registered.
-- There is no pause. The bridge runs whenever an account is stored, and
-  `/wechat logout` is the only way to stop it (and it discards the credentials).
+- Pause is runtime-local. `/wechat pause` stops polling and releases the lock,
+  but a reload, `/new`, or restart builds a fresh running bridge; only
+  `/wechat logout` stops it persistently (and discards the credentials).
 
 ## Non-goals
 
@@ -406,7 +407,7 @@ sessions are in-process).
 | Integration point | Detail |
 |---|---|
 | Command | `pi.registerCommand("wechat", …)` — `login`, `new`, `status`, `pause`, `resume`, `doctor`, `stop <peer>`, `reset <peer>`, `history <peer> [n]`, `allow [peer]`, `logout`, `help`; bare `/wechat` opens the control screen. |
-| Tools | `send_wechat` — owner-only proactive text; registered at factory time with `exposure: "direct"`, `executionMode: "sequential"`, `openWorldHint: true`. |
+| Tools | `send_wechat` — owner-only proactive text; registered at factory time with direct exposure (the default), `executionMode: "sequential"`, `openWorldHint: true`. |
 | Events | `session_start` (record the live context, auto-start the bridge when an account exists); `session_shutdown` (idempotent stop). No host run events: peer turns are not the host session's runs. |
 | Sessions | `openPeerSession` creates one SDK `AgentSession` per peer (`createAgentSession`, `SessionManager.continueRecent` under `<agent-dir>/wechat/sessions/<peer>/`), inheriting the host's model and thinking level. `DefaultResourceLoader` standard discovery minus this bridge (`withoutWechatExtensions`), so a peer session cannot start a second poller, plus a short channel contract appended to the system prompt so the model knows it is answering in a phone chat window. When `peers[<id>].tools` is set, only those names stay active. |
 | Turn ownership | `peer-worker.ts`: a serial queue per peer, `session.prompt()`/`session.abort()`, `getLastAssistantText()` for the answer, and one idle sweep per session. `concurrency` defaults to 1 so a forwarded dialog has one owner. |

package/extensions/wechat/tools.ts

@@ -68,8 +68,6 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 		],
 		parameters: WechatSendParams,
 		outputSchema: WechatSendResult,
-		exposure: "direct",
-		defaultActive: true,
 		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
 		executionMode: "sequential",