@oh-my-pi/pi-coding-agent 14.5.13 → 14.5.14

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [14.5.14] - 2026-05-01
+### Changed
+
+- Changed markdown conversion and archive tooling to defer loading heavy dependencies (Turndown, fflate, and browser agent content) until first use, reducing startup overhead for CLI startup and command initialization
+
+### Fixed
+
+- Fixed changelog state tracking by flushing `lastChangelogVersion` to settings immediately when showing new entries, so the updated version is persisted across restarts
+
 ## [14.5.13] - 2026-05-01
 
 ### Breaking Changes
@@ -34,6 +43,10 @@
 
 - Fixed eval startup messaging to report `eval` as unavailable when Python is unreachable and JavaScript backend is disabled
 
+### Fixed
+- Stabilized MCP tool ordering so reconnects and refreshes no longer reorder the tools array sent to the model. Anthropic prompt caching is keyed on byte-identical tool definitions; previously, the order depended on connection sequence and a single MCP server reconnect could shuffle tools across servers and invalidate the tools cache breakpoint.
+- Skipped redundant system-prompt rebuilds in `AgentSession.refreshMCPTools` when the active tool set is unchanged. MCP transport flapping (e.g. routine 5-minute SSE reconnects) used to call `rebuildSystemPrompt` on every reconnect even though the resulting prompt was byte-identical, eating CPU and risking cache misses if the rebuild ever became non-deterministic. The applied-tool signature also covers `customWireName` so a wire-name flip with the rest of the tool metadata constant still forces a rebuild.
+
 ## [14.5.12] - 2026-04-30
 
 ### Breaking Changes

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "14.5.13",
+	"version": "14.5.14",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -46,12 +46,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.20.0",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/omp-stats": "14.5.13",
-		"@oh-my-pi/pi-agent-core": "14.5.13",
-		"@oh-my-pi/pi-ai": "14.5.13",
-		"@oh-my-pi/pi-natives": "14.5.13",
-		"@oh-my-pi/pi-tui": "14.5.13",
-		"@oh-my-pi/pi-utils": "14.5.13",
+		"@oh-my-pi/omp-stats": "14.5.14",
+		"@oh-my-pi/pi-agent-core": "14.5.14",
+		"@oh-my-pi/pi-ai": "14.5.14",
+		"@oh-my-pi/pi-natives": "14.5.14",
+		"@oh-my-pi/pi-tui": "14.5.14",
+		"@oh-my-pi/pi-utils": "14.5.14",
 		"@puppeteer/browsers": "^2.13.0",
 		"@sinclair/typebox": "^0.34.49",
 		"@xterm/headless": "^6.0.0",

package/src/commit/pipeline.ts

@@ -25,7 +25,8 @@ import type { CommitCommandArgs, ConventionalAnalysis } from "./types";
 
 const SUMMARY_MAX_CHARS = 72;
 const RECENT_COMMITS_COUNT = 8;
-const TYPES_DESCRIPTION = prompt.render(typesDescriptionPrompt);
+let _typesDescription: string | undefined;
+const TYPES_DESCRIPTION = (): string => (_typesDescription ??= prompt.render(typesDescriptionPrompt));
 
 /**
  * Execute the omp commit pipeline for staged changes.
@@ -176,7 +177,7 @@ async function generateAnalysis(input: {
 			diff: input.diff,
 			stat: input.stat,
 			scopeCandidates: input.scopeCandidates,
-			typesDescription: TYPES_DESCRIPTION,
+			typesDescription: TYPES_DESCRIPTION(),
 			settings: {
 				enabled: input.commitSettings.mapReduceEnabled,
 				minFiles: input.commitSettings.mapReduceMinFiles,
@@ -193,7 +194,7 @@ async function generateAnalysis(input: {
 		thinkingLevel: input.primaryThinkingLevel,
 		contextFiles: input.contextFiles,
 		userContext: input.userContext,
-		typesDescription: TYPES_DESCRIPTION,
+		typesDescription: TYPES_DESCRIPTION(),
 		recentCommits: input.recentCommits,
 		scopeCandidates: input.scopeCandidates,
 		stat: input.stat,

package/src/config.ts

@@ -11,7 +11,7 @@ import {
 } from "@oh-my-pi/pi-utils";
 import type { TSchema } from "@sinclair/typebox";
 import { Value } from "@sinclair/typebox/value";
-import { Ajv, type ErrorObject, type ValidateFunction } from "ajv";
+import type { ErrorObject } from "ajv";
 import { JSONC, YAML } from "bun";
 import { expandTilde } from "./tools/path-utils";
 
@@ -143,7 +143,6 @@ export type LoadResult<T> =
 	| { value: T; error?: undefined; status: "ok" }
 	| { value?: null; error?: unknown; status: "not-found" };
 
-const ajv = new Ajv();
 export class ConfigFile<T> implements IConfigFile<T> {
 	readonly #basePath: string;
 	#cache?: LoadResult<T>;
@@ -221,13 +220,17 @@ export class ConfigFile<T> implements IConfigFile<T> {
 				throw new Error(`Invalid config file path: ${this.#basePath}`);
 			}
 
-			const validate = ajv.compile(this.schema) as ValidateFunction<T>;
-			if (!validate(parsed)) {
-				const error = new ConfigError(this.id, validate.errors);
+			if (!Value.Check(this.schema, parsed)) {
+				const schemaErrors: ErrorObject[] = [];
+				for (const err of Value.Errors(this.schema, parsed)) {
+					schemaErrors.push({ instancePath: err.path, message: err.message } as ErrorObject);
+					if (schemaErrors.length >= 50) break;
+				}
+				const error = new ConfigError(this.id, schemaErrors);
 				logger.warn("Failed to parse config file", { path: this.path(), error });
 				return this.#storeCache({ error, status: "error" });
 			}
-			return this.#storeCache({ value: parsed, status: "ok" });
+			return this.#storeCache({ value: parsed as T, status: "ok" });
 		} catch (error) {
 			if (isEnoent(error)) {
 				return this.#storeCache({ status: "not-found" });

package/src/eval/py/kernel.ts

@@ -271,10 +271,10 @@ function normalizeDisplayText(text: string): string {
 }
 
 /** Renders a Jupyter display_data message into text and structured outputs. */
-export function renderKernelDisplay(content: Record<string, unknown>): {
+export async function renderKernelDisplay(content: Record<string, unknown>): Promise<{
 	text: string;
 	outputs: KernelDisplayOutput[];
-} {
+}> {
 	const data = content.data as Record<string, unknown> | undefined;
 	if (!data) return { text: "", outputs: [] };
 
@@ -307,7 +307,7 @@ export function renderKernelDisplay(content: Record<string, unknown>): {
 		return { text: normalizeDisplayText(String(data["text/plain"])), outputs };
 	}
 	if (data["text/html"] !== undefined) {
-		const markdown = htmlToBasicMarkdown(String(data["text/html"])) || "";
+		const markdown = (await htmlToBasicMarkdown(String(data["text/html"]))) || "";
 		return { text: markdown ? normalizeDisplayText(markdown) : "", outputs };
 	}
 	return { text: "", outputs };
@@ -872,7 +872,7 @@ export class PythonKernel {
 				}
 				case "execute_result":
 				case "display_data": {
-					const { text, outputs } = renderKernelDisplay(response.content);
+					const { text, outputs } = await renderKernelDisplay(response.content);
 					if (text && options?.onChunk) {
 						await options.onChunk(text);
 					}

package/src/main.ts

@@ -253,12 +253,14 @@ async function getChangelogForDisplay(parsed: Args): Promise<string | undefined>
 	if (!lastVersion) {
 		if (entries.length > 0) {
 			settings.set("lastChangelogVersion", VERSION);
+			await flushChangelogVersion();
 			return entries.map(e => e.content).join("\n\n");
 		}
 	} else {
 		const newEntries = getNewEntries(entries, lastVersion);
 		if (newEntries.length > 0) {
 			settings.set("lastChangelogVersion", VERSION);
+			await flushChangelogVersion();
 			return newEntries.map(e => e.content).join("\n\n");
 		}
 	}
@@ -266,6 +268,14 @@ async function getChangelogForDisplay(parsed: Args): Promise<string | undefined>
 	return undefined;
 }
 
+async function flushChangelogVersion(): Promise<void> {
+	try {
+		await settings.flush();
+	} catch (error: unknown) {
+		logger.warn("Failed to persist lastChangelogVersion", { error });
+	}
+}
+
 async function createSessionManager(parsed: Args, cwd: string): Promise<SessionManager | undefined> {
 	if (parsed.fork) {
 		if (parsed.noSession) {

package/src/mcp/manager.ts

@@ -78,6 +78,21 @@ function delay(ms: number): Promise<void> {
 	return Bun.sleep(ms);
 }
 
+/**
+ * Stable, total ordering on MCP tools by name.
+ *
+ * Anthropic prompt caching keys on byte-identical tool definitions: any reorder
+ * of the tools array invalidates the tools cache breakpoint and forces a full
+ * prefix rebuild on the next request. MCP servers connect/reconnect at arbitrary
+ * times, so the natural "insertion order" of `#tools` is non-deterministic.
+ * Sorting after every mutation makes the array bytes independent of connection
+ * sequence.
+ */
+export function sortMCPToolsByName<T extends { name: string }>(tools: T[]): T[] {
+	tools.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+	return tools;
+}
+
 export function resolveSubscriptionPostAction(
 	notificationsEnabled: boolean,
 	currentEpoch: number,
@@ -459,6 +474,10 @@ export class MCPManager {
 			}
 		}
 
+		// Stable sort by name so the order is independent of connection completion.
+		// See `sortMCPToolsByName` for the cache-stability rationale.
+		sortMCPToolsByName(allTools);
+
 		// Update cached tools
 		this.#tools = allTools;
 		allowBackgroundLogging = true;
@@ -474,6 +493,9 @@ export class MCPManager {
 	#replaceServerTools(name: string, tools: CustomTool<TSchema, MCPToolDetails>[]): void {
 		this.#tools = this.#tools.filter(t => !t.name.startsWith(`mcp__${name}_`));
 		this.#tools.push(...tools);
+		// Stable sort by name so reconnect order does not perturb the array.
+		// See `sortMCPToolsByName` for the cache-stability rationale.
+		sortMCPToolsByName(this.#tools);
 	}
 
 	#triggerNotificationRefresh(serverName: string, kind: "tools" | "resources" | "prompts"): void {

package/src/modes/rpc/rpc-client.ts

@@ -11,6 +11,7 @@ import type { SessionStats } from "../../session/agent-session";
 import type { CompactionResult } from "../../session/compaction";
 import type {
 	RpcCommand,
+	RpcHandoffResult,
 	RpcHostToolCallRequest,
 	RpcHostToolCancelRequest,
 	RpcHostToolDefinition,
@@ -457,6 +458,14 @@ export class RpcClient {
 		return this.#getData(response);
 	}
 
+	/**
+	 * Hand off session context to a new session.
+	 */
+	async handoff(customInstructions?: string): Promise<RpcHandoffResult | null> {
+		const response = await this.#send({ type: "handoff", customInstructions });
+		return this.#getData(response);
+	}
+
 	/**
 	 * Export session to HTML.
 	 */

package/src/modes/rpc/rpc-mode.ts

@@ -574,6 +574,7 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 						description: tool.description,
 						parameters: tool.parameters,
 					})),
+					contextUsage: session.getContextUsage(),
 				};
 				return success(id, "get_state", state);
 			}
@@ -741,6 +742,11 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 				return success(id, "set_session_name");
 			}
 
+			case "handoff": {
+				const result = await session.handoff(command.customInstructions);
+				return success(id, "handoff", result ? { savedPath: result.savedPath } : null);
+			}
+
 			// =================================================================
 			// Messages
 			// =================================================================

package/src/modes/rpc/rpc-types.ts

@@ -7,6 +7,7 @@
 import type { AgentMessage, AgentToolResult, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Effort, ImageContent, Model } from "@oh-my-pi/pi-ai";
 import type { BashResult } from "../../exec/bash-executor";
+import type { ContextUsage } from "../../extensibility/extensions/types";
 import type { SessionStats } from "../../session/agent-session";
 import type { CompactionResult } from "../../session/compaction";
 import type { TodoPhase } from "../../tools/todo-write";
@@ -63,6 +64,7 @@ export type RpcCommand =
 	| { id?: string; type: "get_branch_messages" }
 	| { id?: string; type: "get_last_assistant_text" }
 	| { id?: string; type: "set_session_name"; name: string }
+	| { id?: string; type: "handoff"; customInstructions?: string }
 
 	// Messages
 	| { id?: string; type: "get_messages" };
@@ -89,6 +91,12 @@ export interface RpcSessionState {
 	/** For session dump / export (plain-text parity with /dump). */
 	systemPrompt?: string;
 	dumpTools?: Array<{ name: string; description: string; parameters: unknown }>;
+	/** Current context window usage. Null tokens/percent when unknown (e.g. right after compaction). */
+	contextUsage?: ContextUsage;
+}
+
+export interface RpcHandoffResult {
+	savedPath?: string;
 }
 
 // ============================================================================
@@ -180,6 +188,7 @@ export type RpcResponse =
 			data: { text: string | null };
 	  }
 	| { id?: string; type: "response"; command: "set_session_name"; success: true }
+	| { id?: string; type: "response"; command: "handoff"; success: true; data: RpcHandoffResult | null }
 
 	// Messages
 	| { id?: string; type: "response"; command: "get_messages"; success: true; data: { messages: AgentMessage[] } }

package/src/sdk.ts

@@ -300,7 +300,6 @@ function getDefaultAgentDir(): string {
  */
 export async function discoverAuthStorage(agentDir: string = getDefaultAgentDir()): Promise<AuthStorage> {
 	const dbPath = getAgentDbPath(agentDir);
-	logger.debug("discoverAuthStorage", { agentDir, dbPath });
 
 	const storage = await AuthStorage.create(dbPath, { configValueResolver: resolveConfigValue });
 	await storage.reload();
@@ -429,6 +428,9 @@ function isCustomTool(tool: CustomTool | ToolDefinition): tool is CustomTool {
 
 const TOOL_DEFINITION_MARKER = Symbol("__isToolDefinition");
 
+/** Matches the truncation applied to per-server instructions inside `rebuildSystemPrompt`. */
+const MAX_MCP_INSTRUCTIONS_LENGTH = 4000;
+
 let sshCleanupRegistered = false;
 
 async function cleanupSshResources(): Promise<void> {
@@ -1338,7 +1340,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const serverInstructions = mcpManager?.getServerInstructions();
 			let appendPrompt: string | undefined = memoryInstructions ?? undefined;
 			if (serverInstructions && serverInstructions.size > 0) {
-				const MAX_INSTRUCTIONS_LENGTH = 4000;
 				const parts: string[] = [];
 				if (appendPrompt) parts.push(appendPrompt);
 				parts.push(
@@ -1346,8 +1347,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				);
 				for (const [srvName, srvInstructions] of serverInstructions) {
 					const truncated =
-						srvInstructions.length > MAX_INSTRUCTIONS_LENGTH
-							? `${srvInstructions.slice(0, MAX_INSTRUCTIONS_LENGTH)}\n[truncated]`
+						srvInstructions.length > MAX_MCP_INSTRUCTIONS_LENGTH
+							? `${srvInstructions.slice(0, MAX_MCP_INSTRUCTIONS_LENGTH)}\n[truncated]`
 							: srvInstructions;
 					parts.push(`### ${srvName}\n${truncated}`);
 				}
@@ -1627,6 +1628,20 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			onResponse,
 			convertToLlm: convertToLlmFinal,
 			rebuildSystemPrompt,
+			getMcpServerInstructions: mcpManager
+				? () => {
+						const raw = mcpManager.getServerInstructions();
+						if (!raw || raw.size === 0) return raw;
+						const out = new Map<string, string>();
+						for (const [name, text] of raw) {
+							out.set(
+								name,
+								text.length > MAX_MCP_INSTRUCTIONS_LENGTH ? text.slice(0, MAX_MCP_INSTRUCTIONS_LENGTH) : text,
+							);
+						}
+						return out;
+					}
+				: undefined,
 			mcpDiscoveryEnabled,
 			initialSelectedMCPToolNames,
 			defaultSelectedMCPToolNames,

package/src/session/agent-session.ts

@@ -244,6 +244,13 @@ export interface AgentSessionConfig {
 	convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	/** System prompt builder that can consider tool availability */
 	rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<string>;
+	/**
+	 * Optional accessor for live MCP server instructions. Read by the session's
+	 * `rebuildSystemPrompt`-skip optimization to detect server-side instruction
+	 * changes (e.g. an MCP server upgrade) that would otherwise pass the tool-set
+	 * signature comparison and silently keep a stale prompt cached.
+	 */
+	getMcpServerInstructions?: () => Map<string, string> | undefined;
 	/** Enable hidden-by-default MCP tool discovery for this session. */
 	mcpDiscoveryEnabled?: boolean;
 	/** MCP tool names to activate for the current session when discovery mode is enabled. */
@@ -511,7 +518,15 @@ export class AgentSession {
 	#onResponse: SimpleStreamOptions["onResponse"] | undefined;
 	#convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	#rebuildSystemPrompt: ((toolNames: string[], tools: Map<string, AgentTool>) => Promise<string>) | undefined;
+	#getMcpServerInstructions: (() => Map<string, string> | undefined) | undefined;
 	#baseSystemPrompt: string;
+	/**
+	 * Signature of the (toolNames, tool descriptions) tuple passed to the most
+	 * recent successful `rebuildSystemPrompt` call. Used to skip redundant rebuilds
+	 * when MCP servers reconnect without changing their tool definitions, which is
+	 * the dominant cause of prompt-cache invalidation in long sessions.
+	 */
+	#lastAppliedToolSignature: string | undefined;
 	#mcpDiscoveryEnabled = false;
 	#discoverableMCPTools = new Map<string, DiscoverableMCPTool>();
 	#discoverableMCPSearchIndex: DiscoverableMCPSearchIndex | null = null;
@@ -595,6 +610,7 @@ export class AgentSession {
 		this.#onResponse = config.onResponse;
 		this.#convertToLlm = config.convertToLlm ?? convertToLlm;
 		this.#rebuildSystemPrompt = config.rebuildSystemPrompt;
+		this.#getMcpServerInstructions = config.getMcpServerInstructions;
 		this.#baseSystemPrompt = this.agent.state.systemPrompt;
 		this.#mcpDiscoveryEnabled = config.mcpDiscoveryEnabled ?? false;
 		this.#setDiscoverableMCPTools(this.#collectDiscoverableMCPToolsFromRegistry());
@@ -2211,10 +2227,18 @@ export class AgentSession {
 		}
 		this.agent.setTools(tools);
 
-		// Rebuild base system prompt with new tool set
+		// Rebuild base system prompt with new tool set, but only when the tool set
+		// actually changed. MCP servers can reconnect at arbitrary times and call
+		// `refreshMCPTools` -> `#applyActiveToolsByName` even though the resulting
+		// tool list is byte-identical. Skipping the rebuild keeps the system prompt
+		// stable, which is required for Anthropic prompt caching to keep hitting.
 		if (this.#rebuildSystemPrompt) {
-			this.#baseSystemPrompt = await this.#rebuildSystemPrompt(validToolNames, this.#toolRegistry);
-			this.agent.setSystemPrompt(this.#baseSystemPrompt);
+			const signature = this.#computeAppliedToolSignature(validToolNames, tools);
+			if (signature !== this.#lastAppliedToolSignature) {
+				this.#baseSystemPrompt = await this.#rebuildSystemPrompt(validToolNames, this.#toolRegistry);
+				this.agent.setSystemPrompt(this.#baseSystemPrompt);
+				this.#lastAppliedToolSignature = signature;
+			}
 		}
 		if (options?.persistMCPSelection !== false) {
 			this.#persistSelectedMCPToolNamesIfChanged(previousSelectedMCPToolNames);
@@ -2256,6 +2280,86 @@ export class AgentSession {
 		const activeToolNames = this.getActiveToolNames();
 		this.#baseSystemPrompt = await this.#rebuildSystemPrompt(activeToolNames, this.#toolRegistry);
 		this.agent.setSystemPrompt(this.#baseSystemPrompt);
+		// Refresh the cached signature so a subsequent `#applyActiveToolsByName` with
+		// the same tool set does not re-rebuild on top of the explicit refresh we
+		// just performed (and conversely, a different set forces a fresh rebuild).
+		const activeTools = activeToolNames
+			.map(name => this.#toolRegistry.get(name))
+			.filter((tool): tool is AgentTool => tool != null);
+		this.#lastAppliedToolSignature = this.#computeAppliedToolSignature(activeToolNames, activeTools);
+	}
+
+	/**
+	 * Compose a stable signature for the inputs that `rebuildSystemPrompt` reads.
+	 * Two calls producing identical signatures are guaranteed to produce identical
+	 * system prompt bytes, so the rebuild can be skipped.
+	 *
+	 * The signature covers:
+	 *   1. Active tool names in order (the prompt renders them in this order).
+	 *   2. Active tool labels, descriptions, and wire-visible names — all are
+	 *      rendered into the prompt body (see `system-prompt.md` `{{label}}: \`{{name}}\``
+	 *      and `toolPromptNames` in `buildSystemPrompt`). The wire name comes from
+	 *      `tool.customWireName` and overrides the internal name on the model wire
+	 *      (e.g. `edit` exposes itself as `apply_patch` to GPT-5 in apply_patch mode);
+	 *      a stale wire name would desync prompt guidance from actual tool routing.
+	 *   3. When MCP discovery is on, every registry tool's name+label+description+
+	 *      customWireName, since `rebuildSystemPrompt` summarizes discoverable MCP
+	 *      tools that are not in the active set.
+	 *   4. MCP server instructions text (per server), since `rebuildSystemPrompt`
+	 *      embeds these in the appended prompt under "## MCP Server Instructions".
+	 *      A server upgrade can change instructions while keeping tools identical.
+	 *
+	 * Settings-driven tool metadata is covered automatically: built-in tools that
+	 * depend on settings expose `description`/`label` via getters (see `TaskTool`,
+	 * `SearchToolBm25Tool`, `EditTool`), and the signature reads them live on every
+	 * call - so a settings flip that mutates the rendered string differs the signature
+	 * the next time `#applyActiveToolsByName` runs. Do not refactor `describeTool` to
+	 * cache per-tool strings without preserving this property.
+	 *
+	 * Inputs NOT covered: tool input schemas; memory instructions read from disk;
+	 * and SDK-init-time closure constants in `sdk.ts` (`repeatToolDescriptions`,
+	 * `eagerTasks`, `intentField`, `mcpDiscoveryEnabled`, `secretsEnabled`). The
+	 * closure-captured ones cannot change at runtime regardless of skip behavior.
+	 * For everything else, callers must explicitly call `refreshBaseSystemPrompt()`
+	 * after side-effecting changes; see e.g. the memory hooks and
+	 * `#syncEditToolModeAfterModelChange`.
+	 *
+	 * The current calendar date IS covered (appended as a segment) because
+	 * `buildSystemPrompt` injects it into the prompt body (`Today is '{{date}}'`).
+	 * Without this, a session spanning midnight with only tool-stable MCP
+	 * reconnects would keep yesterday's date indefinitely.
+	 */
+	#computeAppliedToolSignature(toolNames: string[], tools: AgentTool[]): string {
+		// Order-preserving join: any reorder must produce a different signature so
+		// the rebuild fires and the new tool list reaches the API.
+		const nameSegment = toolNames.join("\u0001");
+		const describeTool = (tool: AgentTool): string =>
+			`${tool.name}=${tool.label ?? ""}|${tool.description ?? ""}|${tool.customWireName ?? ""}`;
+		const descriptionSegment = tools.map(describeTool).join("\u0002");
+		let registrySegment = "";
+		if (this.#mcpDiscoveryEnabled) {
+			// Registry iteration order is not load-bearing for the prompt content, so we
+			// sort to keep the signature insensitive to incidental insertion order.
+			const entries: string[] = [];
+			for (const tool of this.#toolRegistry.values()) {
+				entries.push(describeTool(tool));
+			}
+			entries.sort();
+			registrySegment = entries.join("\u0004");
+		}
+		let instructionsSegment = "";
+		const serverInstructions = this.#getMcpServerInstructions?.();
+		if (serverInstructions && serverInstructions.size > 0) {
+			// Sort by server name so transport flap order does not perturb the signature.
+			const entries: string[] = [];
+			for (const [server, instructions] of serverInstructions) {
+				entries.push(`${server}=${instructions}`);
+			}
+			entries.sort();
+			instructionsSegment = entries.join("\u0006");
+		}
+		const date = new Date().toISOString().slice(0, 10);
+		return `${nameSegment}\u0003${descriptionSegment}\u0005${registrySegment}\u0007${instructionsSegment}|${date}`;
 	}
 
 	/**
@@ -4248,9 +4352,10 @@ export class AgentSession {
 			}
 
 			// Start a new session
+			const previousSessionFile = this.sessionFile;
 			await this.sessionManager.flush();
 			this.#asyncJobManager?.cancelAll();
-			await this.sessionManager.newSession();
+			await this.sessionManager.newSession(previousSessionFile ? { parentSession: previousSessionFile } : undefined);
 			this.agent.reset();
 			this.agent.sessionId = this.sessionManager.getSessionId();
 			this.#steeringMessages = [];
@@ -4262,6 +4367,7 @@ export class AgentSession {
 			// Inject the handoff document as a custom message
 			const handoffContent = `<handoff-context>\n${handoffText}\n</handoff-context>\n\nThe above is a handoff document from a previous session. Use this context to continue the work seamlessly.`;
 			this.sessionManager.appendCustomMessageEntry("handoff", handoffContent, true, undefined, "agent");
+			await this.sessionManager.ensureOnDisk();
 			let savedPath: string | undefined;
 			if (options?.autoTriggered && this.settings.get("compaction.handoffSaveToDisk")) {
 				const artifactsDir = this.sessionManager.getArtifactsDir();

package/src/task/agents.ts

@@ -69,10 +69,7 @@ const EMBEDDED_AGENT_DEFS: EmbeddedAgentDef[] = [
 	},
 ];
 
-const EMBEDDED_AGENTS: { name: string; content: string }[] = EMBEDDED_AGENT_DEFS.map(def => ({
-	name: def.fileName,
-	content: buildAgentContent(def),
-}));
+// Computed lazily on first loadBundledAgents() call to avoid eager prompt.render at module load.
 
 export class AgentParsingError extends Error {
 	constructor(
@@ -133,7 +130,9 @@ export function loadBundledAgents(): AgentDefinition[] {
 	if (bundledAgentsCache !== null) {
 		return bundledAgentsCache;
 	}
-	bundledAgentsCache = EMBEDDED_AGENTS.map(({ name, content }) => parseAgent(`embedded:${name}`, content, "bundled"));
+	bundledAgentsCache = EMBEDDED_AGENT_DEFS.map(def =>
+		parseAgent(`embedded:${def.fileName}`, buildAgentContent(def), "bundled"),
+	);
 	return bundledAgentsCache;
 }
 

package/src/tools/archive-reader.ts

@@ -1,6 +1,11 @@
-import { unzipSync } from "fflate";
 import { ToolError } from "./tool-errors";
 
+let fflateModulePromise: Promise<typeof import("fflate")> | undefined;
+async function loadFflate(): Promise<typeof import("fflate")> {
+	if (!fflateModulePromise) fflateModulePromise = import("fflate");
+	return fflateModulePromise;
+}
+
 export type ArchiveFormat = "zip" | "tar" | "tar.gz";
 
 export interface ArchivePathCandidate {
@@ -150,7 +155,8 @@ async function readTarEntries(bytes: Uint8Array): Promise<ArchiveIndexEntry[]> {
 	return entries;
 }
 
-function readZipEntries(bytes: Uint8Array): ArchiveIndexEntry[] {
+async function readZipEntries(bytes: Uint8Array): Promise<ArchiveIndexEntry[]> {
+	const { unzipSync } = await loadFflate();
 	let files: Record<string, Uint8Array>;
 	try {
 		files = unzipSync(bytes);
@@ -310,6 +316,6 @@ export async function openArchive(filePath: string): Promise<ArchiveReader> {
 	}
 
 	const bytes = await Bun.file(filePath).bytes();
-	const entries = format === "zip" ? readZipEntries(bytes) : await readTarEntries(bytes);
+	const entries = format === "zip" ? await readZipEntries(bytes) : await readTarEntries(bytes);
 	return new ArchiveReader(format, entries);
 }

package/src/tools/browser/readable.ts

@@ -26,13 +26,17 @@ function normalize(text: string | null | undefined): string | undefined {
  * CSS selector chain over the same pre-parsed DOM. Returns null if neither
  * path yields usable content.
  */
-export function extractReadableFromHtml(html: string, url: string, format: ReadableFormat): ReadableResult | null {
+export async function extractReadableFromHtml(
+	html: string,
+	url: string,
+	format: ReadableFormat,
+): Promise<ReadableResult | null> {
 	const { document } = parseHTML(html);
 
 	// --- Primary: Readability article extraction ---
 	const article = new Readability(document).parse();
 	if (article) {
-		const result = toReadableResult(url, format, article.textContent, article.content, {
+		const result = await toReadableResult(url, format, article.textContent, article.content, {
 			title: article.title,
 			byline: article.byline,
 			excerpt: article.excerpt,
@@ -55,7 +59,7 @@ export function extractReadableFromHtml(html: string, url: string, format: Reada
 		const innerHTML = el.innerHTML?.trim();
 		const textContent = el.textContent?.trim();
 		if (!innerHTML || !textContent) continue;
-		const result = toReadableResult(url, format, textContent, innerHTML, {
+		const result = await toReadableResult(url, format, textContent, innerHTML, {
 			title: document.title,
 			excerpt: textContent.slice(0, 240),
 			length: textContent.length,
@@ -67,15 +71,16 @@ export function extractReadableFromHtml(html: string, url: string, format: Reada
 }
 
 /** Shared builder for both extraction paths. */
-function toReadableResult(
+async function toReadableResult(
 	url: string,
 	format: ReadableFormat,
 	textContent: string | null | undefined,
 	htmlContent: string | null | undefined,
 	meta: { title?: string | null; byline?: string | null; excerpt?: string | null; length?: number | null },
-): ReadableResult | null {
+): Promise<ReadableResult | null> {
 	const text = normalize(textContent);
-	const markdown = format === "markdown" ? (normalize(htmlToBasicMarkdown(htmlContent ?? "")) ?? text) : undefined;
+	const markdown =
+		format === "markdown" ? (normalize(await htmlToBasicMarkdown(htmlContent ?? "")) ?? text) : undefined;
 	const normalizedText = format === "text" ? text : undefined;
 	if (!normalizedText && !markdown) return null;
 	return {

package/src/tools/browser/tab-supervisor.ts

@@ -16,7 +16,6 @@ import type {
 	WorkerInitPayload,
 	WorkerOutbound,
 } from "./tab-protocol";
-import { WorkerCore } from "./tab-worker";
 
 interface WorkerHandle {
 	send(msg: WorkerInbound, transferList?: Transferable[]): void;
@@ -398,7 +397,7 @@ function wrapBunWorker(worker: Worker): WorkerHandle {
  * entry. This preserves normal browser behavior but cannot interrupt synchronous
  * infinite loops because user code runs on the main thread.
  */
-function spawnInlineWorker(): WorkerHandle {
+async function spawnInlineWorker(): Promise<WorkerHandle> {
 	const hostListeners = new Set<(message: WorkerOutbound) => void>();
 	const workerListeners = new Set<(message: WorkerInbound) => void>();
 	const workerTransport: Transport = {
@@ -413,6 +412,7 @@ function spawnInlineWorker(): WorkerHandle {
 		},
 		close: () => {},
 	};
+	const { WorkerCore } = await import("./tab-worker");
 	new WorkerCore(workerTransport);
 	return {
 		mode: "inline",

package/src/tools/browser.ts

@@ -110,12 +110,14 @@ function resolveBrowserKind(params: BrowserParams, session: ToolSession): Browse
 export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolDetails> {
 	readonly name = "browser";
 	readonly label = "Browser";
-	readonly description: string;
 	readonly parameters = browserSchema;
 	readonly strict = true;
 
-	constructor(private readonly session: ToolSession) {
-		this.description = prompt.render(browserDescription, {});
+	constructor(private readonly session: ToolSession) {}
+	#description?: string;
+	get description(): string {
+		this.#description ??= prompt.render(browserDescription, {});
+		return this.#description;
 	}
 
 	/** Restart browser to apply mode changes (e.g. headless toggle). Drops only headless browsers. */

package/src/tools/image-gen.ts

@@ -1,6 +1,6 @@
 import * as os from "node:os";
 import * as path from "node:path";
-import { getAntigravityHeaders, getEnvApiKey, type Model, StringEnum } from "@oh-my-pi/pi-ai";
+import { getAntigravityUserAgent, getEnvApiKey, type Model, StringEnum } from "@oh-my-pi/pi-ai";
 import {
 	CODEX_BASE_URL,
 	getCodexAccountId,
@@ -1055,7 +1055,7 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 						Authorization: `Bearer ${apiKey.apiKey}`,
 						"Content-Type": "application/json",
 						Accept: "text/event-stream",
-						...getAntigravityHeaders(),
+						"User-Agent": getAntigravityUserAgent(),
 					},
 					body: JSON.stringify(requestBody),
 					signal: requestSignal,

package/src/tools/write.ts

@@ -6,7 +6,6 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { isEnoent, isRecord, prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
-import { unzipSync, zipSync } from "fflate";
 import { stripHashlinePrefixes } from "../edit";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { createLspWritethrough, type FileDiagnosticsResult, type WritethroughCallback, writethroughNoop } from "../lsp";
@@ -44,6 +43,12 @@ import {
 import { ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
 
+let fflateModulePromise: Promise<typeof import("fflate")> | undefined;
+async function loadFflate(): Promise<typeof import("fflate")> {
+	if (!fflateModulePromise) fflateModulePromise = import("fflate");
+	return fflateModulePromise;
+}
+
 const writeSchema = Type.Object({
 	path: Type.String({ description: "file path", examples: ["src/new.ts"] }),
 	content: Type.String({ description: "file content" }),
@@ -229,6 +234,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			if (resolvedArchivePath.exists) {
 				try {
 					const bytes = await Bun.file(resolvedArchivePath.absolutePath).bytes();
+					const { unzipSync } = await loadFflate();
 					const existing = unzipSync(new Uint8Array(bytes));
 					for (const [entryPath, data] of Object.entries(existing)) {
 						zipEntries[entryPath.replace(/\\/g, "/")] = data;
@@ -241,6 +247,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			zipEntries[resolvedArchivePath.archiveSubPath] = new TextEncoder().encode(content);
 
 			try {
+				const { zipSync } = await loadFflate();
 				const zipBuffer = zipSync(zipEntries);
 				await Bun.write(resolvedArchivePath.absolutePath, zipBuffer);
 			} catch (error) {

package/src/web/scrapers/crossref.ts

@@ -66,10 +66,10 @@ function formatDate(date?: CrossrefDate): string | null {
 	return formatted.join("-");
 }
 
-function formatAbstract(abstract?: string): string | null {
+async function formatAbstract(abstract?: string): Promise<string | null> {
 	if (!abstract) return null;
 	const normalized = abstract.replace(/<\/?jats:p[^>]*>/g, match => (match.startsWith("</") ? "</p>" : "<p>"));
-	const markdown = htmlToBasicMarkdown(normalized);
+	const markdown = await htmlToBasicMarkdown(normalized);
 	return markdown.trim().length > 0 ? markdown : null;
 }
 
@@ -114,7 +114,7 @@ export const handleCrossref: SpecialHandler = async (
 			formatDate(message.issued) ||
 			formatDate(message.created);
 		const doiValue = message.DOI || doi;
-		const abstract = formatAbstract(message.abstract);
+		const abstract = await formatAbstract(message.abstract);
 		const type = message.type?.replace(/-/g, " ");
 
 		let md = `# ${title}\n\n`;

package/src/web/scrapers/devto.ts

@@ -133,7 +133,7 @@ export const handleDevTo: SpecialHandler = async (
 			if (article.body_markdown) {
 				md += article.body_markdown;
 			} else if (article.body_html) {
-				md += htmlToBasicMarkdown(article.body_html);
+				md += await htmlToBasicMarkdown(article.body_html);
 			}
 
 			notes.push("Fetched via dev.to API");

package/src/web/scrapers/discourse.ts

@@ -77,12 +77,12 @@ function formatCategory(topic: DiscourseTopic): string | null {
 	return parts.length ? parts.join(" ") : null;
 }
 
-function formatPostBody(post: DiscoursePost): string {
+async function formatPostBody(post: DiscoursePost): Promise<string> {
 	const raw = post.raw?.trim();
 	if (raw) return raw;
 	const cooked = post.cooked?.trim();
 	if (!cooked) return "";
-	return htmlToBasicMarkdown(cooked);
+	return await htmlToBasicMarkdown(cooked);
 }
 
 function buildTopicUrl(baseUrl: string, topicId: string): string {
@@ -168,9 +168,9 @@ export const handleDiscourse: SpecialHandler = async (
 		md += "\n";
 
 		const description = topic.excerpt
-			? htmlToBasicMarkdown(topic.excerpt)
+			? await htmlToBasicMarkdown(topic.excerpt)
 			: posts.length
-				? formatPostBody(posts[0])
+				? await formatPostBody(posts[0])
 				: "";
 		if (description) {
 			md += `## Description\n\n${description}\n\n`;
@@ -182,7 +182,7 @@ export const handleDiscourse: SpecialHandler = async (
 				const author = formatAuthor({ name: post.name, username: post.username });
 				const date = formatIsoDate(post.created_at);
 				const likes = post.like_count ?? 0;
-				const content = formatPostBody(post);
+				const content = await formatPostBody(post);
 				const postLabel = post.post_number != null ? `Post ${post.post_number}` : `Post ${post.id}`;
 
 				md += `### ${postLabel} - ${author} - ${date} - Likes: ${likes}\n\n`;

package/src/web/scrapers/firefox-addons.ts

@@ -112,7 +112,7 @@ export const handleFirefoxAddons: SpecialHandler = async (
 		const name = getLocalizedText(data.name, defaultLocale) ?? slug;
 		const summary = getLocalizedText(data.summary, defaultLocale);
 		const descriptionRaw = getLocalizedText(data.description, defaultLocale);
-		const description = descriptionRaw ? htmlToBasicMarkdown(descriptionRaw) : undefined;
+		const description = descriptionRaw ? await htmlToBasicMarkdown(descriptionRaw) : undefined;
 
 		const authors = (data.authors ?? [])
 			.map(author => author.name ?? "")

package/src/web/scrapers/flathub.ts

@@ -170,7 +170,7 @@ export const handleFlathub: SpecialHandler = async (
 		}
 
 		if (app.description) {
-			const description = htmlToBasicMarkdown(app.description);
+			const description = await htmlToBasicMarkdown(app.description);
 			if (description) md += `\n## Description\n\n${description}\n`;
 		}
 
@@ -204,7 +204,7 @@ export const handleFlathub: SpecialHandler = async (
 				md += `${line}\n`;
 
 				if (release.description) {
-					const releaseDesc = htmlToBasicMarkdown(release.description).replace(/\n+/g, " ").trim();
+					const releaseDesc = (await htmlToBasicMarkdown(release.description)).replace(/\n+/g, " ").trim();
 					if (releaseDesc) md += `  - ${releaseDesc}\n`;
 				}
 			}

package/src/web/scrapers/gitlab.ts

@@ -259,7 +259,7 @@ async function renderGitLabIssue(
 	}
 
 	md += `\n---\n\n## Description\n\n`;
-	md += issue.description ? htmlToBasicMarkdown(issue.description) : "*No description*";
+	md += issue.description ? await htmlToBasicMarkdown(issue.description) : "*No description*";
 
 	return { content: md, ok: true };
 }

package/src/web/scrapers/go-pkg.ts

@@ -159,7 +159,7 @@ export const handleGoPkg: SpecialHandler = async (
 			// Get overview paragraph
 			const overview = docSection.querySelector(".go-Message");
 			if (overview) {
-				const overviewMd = htmlToBasicMarkdown(overview.innerHTML);
+				const overviewMd = await htmlToBasicMarkdown(overview.innerHTML);
 				sections.push(overviewMd);
 				sections.push("");
 			}
@@ -172,7 +172,7 @@ export const handleGoPkg: SpecialHandler = async (
 				const docParts: string[] = [];
 				for (let i = 0; i < Math.min(3, paragraphs.length); i++) {
 					const p = paragraphs[i];
-					const text = htmlToBasicMarkdown(p.innerHTML).trim();
+					const text = (await htmlToBasicMarkdown(p.innerHTML)).trim();
 					if (text) {
 						docParts.push(text);
 					}

package/src/web/scrapers/jetbrains-marketplace.ts

@@ -108,7 +108,7 @@ export const handleJetBrainsMarketplace: SpecialHandler = async (
 
 		const vendorName = plugin.vendor?.name ?? plugin.vendor?.publicName;
 		const descriptionSource = plugin.description ?? plugin.preview ?? "";
-		const description = descriptionSource ? htmlToBasicMarkdown(descriptionSource) : "";
+		const description = descriptionSource ? await htmlToBasicMarkdown(descriptionSource) : "";
 		const tags = (plugin.tags ?? []).map(tag => tag.name).filter(Boolean) as string[];
 		const rating = extractRating(plugin);
 		const buildCompatibility = update ? formatBuildCompatibility(update) : null;

package/src/web/scrapers/mastodon.ts

@@ -89,11 +89,11 @@ function formatDate(isoDate: string): string {
 /**
  * Format a status/post as markdown
  */
-function formatStatus(status: MastodonStatus, isReblog = false): string {
+async function formatStatus(status: MastodonStatus, isReblog = false): Promise<string> {
 	// Handle reblogs (boosts)
 	if (status.reblog && !isReblog) {
 		let md = `🔁 **${status.account.display_name || status.account.username}** boosted:\n\n`;
-		md += formatStatus(status.reblog, true);
+		md += await formatStatus(status.reblog, true);
 		return md;
 	}
 
@@ -116,7 +116,7 @@ function formatStatus(status: MastodonStatus, isReblog = false): string {
 	}
 
 	// Main content (convert HTML to markdown)
-	const content = htmlToBasicMarkdown(status.content);
+	const content = await htmlToBasicMarkdown(status.content);
 	md += `${content}\n\n`;
 
 	// Poll
@@ -152,7 +152,7 @@ function formatStatus(status: MastodonStatus, isReblog = false): string {
 /**
  * Format an account/profile as markdown
  */
-function formatAccount(account: MastodonAccount): string {
+async function formatAccount(account: MastodonAccount): Promise<string> {
 	let md = `# ${account.display_name || account.username}\n\n`;
 
 	md += `**@${account.acct}**`;
@@ -161,7 +161,7 @@ function formatAccount(account: MastodonAccount): string {
 
 	// Bio
 	if (account.note) {
-		const bio = htmlToBasicMarkdown(account.note);
+		const bio = await htmlToBasicMarkdown(account.note);
 		if (bio && bio !== account.display_name) {
 			md += `${bio}\n\n`;
 		}
@@ -179,7 +179,7 @@ function formatAccount(account: MastodonAccount): string {
 	if (account.fields && account.fields.length > 0) {
 		md += "\n**Profile Fields:**\n";
 		for (const field of account.fields) {
-			const value = htmlToBasicMarkdown(field.value);
+			const value = await htmlToBasicMarkdown(field.value);
 			md += `- **${field.name}:** ${value}\n`;
 		}
 	}
@@ -228,7 +228,7 @@ export const handleMastodon: SpecialHandler = async (
 			const status = tryParseJson<MastodonStatus>(result.content);
 			if (!status) return null;
 
-			const md = formatStatus(status);
+			const md = await formatStatus(status);
 
 			return buildResult(md, {
 				url,
@@ -263,7 +263,7 @@ export const handleMastodon: SpecialHandler = async (
 				signal,
 			});
 
-			let md = formatAccount(account);
+			let md = await formatAccount(account);
 
 			if (statusesResult.ok) {
 				const statuses = tryParseJson<MastodonStatus[]>(statusesResult.content);
@@ -271,7 +271,7 @@ export const handleMastodon: SpecialHandler = async (
 					md += "\n---\n\n## Recent Posts\n\n";
 					for (const status of statuses.slice(0, 5)) {
 						md += `### ${formatDate(status.created_at)}\n\n`;
-						const content = htmlToBasicMarkdown(status.content);
+						const content = await htmlToBasicMarkdown(status.content);
 						md += `${content}\n\n`;
 						md += `\uD83D\uDCAC ${status.replies_count} \u00B7 \uD83D\uDD01 ${status.reblogs_count} \u00B7 \u2B50 ${status.favourites_count}\n\n`;
 					}

package/src/web/scrapers/mdn.ts

@@ -29,7 +29,7 @@ interface MDNDoc {
 /**
  * Convert MDN body sections to markdown
  */
-function convertMDNBody(sections: MDNSection[]): string {
+async function convertMDNBody(sections: MDNSection[]): Promise<string> {
 	const parts: string[] = [];
 
 	for (const section of sections) {
@@ -38,7 +38,7 @@ function convertMDNBody(sections: MDNSection[]): string {
 		switch (type) {
 			case "prose":
 				if (value.content) {
-					const markdown = htmlToBasicMarkdown(value.content);
+					const markdown = await htmlToBasicMarkdown(value.content);
 					if (value.title) {
 						const level = value.isH3 ? "###" : "##";
 						parts.push(`${level} ${value.title}\n\n${markdown}`);
@@ -74,7 +74,7 @@ function convertMDNBody(sections: MDNSection[]): string {
 				if (value.items) {
 					for (const item of value.items) {
 						parts.push(`**${item.term}**`);
-						const desc = htmlToBasicMarkdown(item.description);
+						const desc = await htmlToBasicMarkdown(item.description);
 						parts.push(desc);
 					}
 				}
@@ -83,9 +83,13 @@ function convertMDNBody(sections: MDNSection[]): string {
 			case "table":
 				if (value.rows && value.rows.length > 0) {
 					// Simple markdown table
-					const header = value.rows[0].map(cell => htmlToBasicMarkdown(cell)).join(" | ");
+					const header = (await Promise.all(value.rows[0].map(cell => htmlToBasicMarkdown(cell)))).join(" | ");
 					const separator = value.rows[0].map(() => "---").join(" | ");
-					const bodyRows = value.rows.slice(1).map(row => row.map(cell => htmlToBasicMarkdown(cell)).join(" | "));
+					const bodyRows = await Promise.all(
+						value.rows
+							.slice(1)
+							.map(async row => (await Promise.all(row.map(cell => htmlToBasicMarkdown(cell)))).join(" | ")),
+					);
 
 					parts.push(`| ${header} |`);
 					parts.push(`| ${separator} |`);
@@ -144,12 +148,12 @@ export const handleMDN: SpecialHandler = async (url: string, timeout: number, si
 		parts.push(`# ${doc.title}`);
 
 		if (doc.summary) {
-			const summary = htmlToBasicMarkdown(doc.summary);
+			const summary = await htmlToBasicMarkdown(doc.summary);
 			parts.push(summary);
 		}
 
 		if (doc.body && doc.body.length > 0) {
-			const bodyMarkdown = convertMDNBody(doc.body);
+			const bodyMarkdown = await convertMDNBody(doc.body);
 			parts.push(bodyMarkdown);
 		}
 

package/src/web/scrapers/pub-dev.ts

@@ -125,7 +125,7 @@ export const handlePubDev: SpecialHandler = async (url: string, timeout: number,
 					/<div[^>]*class="[^"]*markdown-body[^"]*"[^>]*>([\s\S]*?)<\/div>/i,
 				);
 				if (readmeMatch) {
-					const readme = htmlToBasicMarkdown(readmeMatch[1]);
+					const readme = await htmlToBasicMarkdown(readmeMatch[1]);
 
 					if (readme.length > 100) {
 						md += `## README\n\n${readme}\n`;

package/src/web/scrapers/rawg.ts

@@ -63,7 +63,7 @@ export const handleRawg: SpecialHandler = async (
 		md += `**RAWG:** https://rawg.io/games/${encodeURIComponent(slug)}\n`;
 		md += "\n";
 
-		const description = extractDescription(game);
+		const description = await extractDescription(game);
 		if (description) {
 			md += `## Description\n\n${description}\n`;
 		}
@@ -91,11 +91,11 @@ function requiresApiKey(game: RawgGameResponse): boolean {
 	return detail.includes("api key") || detail.includes("key is required") || detail.includes("apikey");
 }
 
-function extractDescription(game: RawgGameResponse): string | null {
+async function extractDescription(game: RawgGameResponse): Promise<string | null> {
 	if (game.description_raw) return game.description_raw.trim();
 	if (!game.description) return null;
 
-	const markdown = htmlToBasicMarkdown(game.description).trim();
+	const markdown = (await htmlToBasicMarkdown(game.description)).trim();
 	return markdown || null;
 }
 

package/src/web/scrapers/readthedocs.ts

@@ -101,7 +101,7 @@ export const handleReadTheDocs: SpecialHandler = async (
 	// If no raw source, convert HTML to markdown
 	if (!content && mainContent) {
 		const html = mainContent.innerHTML;
-		content = htmlToBasicMarkdown(html);
+		content = await htmlToBasicMarkdown(html);
 	}
 
 	if (!content) {

package/src/web/scrapers/spdx.ts

@@ -94,7 +94,7 @@ export const handleSpdx: SpecialHandler = async (
 		const licenseText = license.licenseText
 			? license.licenseText
 			: license.licenseTextHtml
-				? htmlToBasicMarkdown(license.licenseTextHtml)
+				? await htmlToBasicMarkdown(license.licenseTextHtml)
 				: null;
 
 		if (licenseText) {

package/src/web/scrapers/stackoverflow.ts

@@ -90,7 +90,7 @@ export const handleStackOverflow: SpecialHandler = async (
 		md += question.is_answered ? " (Answered)" : "";
 		md += `\n**Tags:** ${question.tags.join(", ")}\n`;
 		md += `**Asked by:** ${question.owner.display_name} · ${formatIsoDate(question.creation_date * 1000)}\n\n`;
-		md += `---\n\n## Question\n\n${htmlToBasicMarkdown(question.body)}\n\n`;
+		md += `---\n\n## Question\n\n${await htmlToBasicMarkdown(question.body)}\n\n`;
 
 		// Fetch answers
 		const aUrl = `https://api.stackexchange.com/2.3/questions/${questionId}/answers?order=desc&sort=votes&site=${site}&filter=withbody`;
@@ -103,7 +103,7 @@ export const handleStackOverflow: SpecialHandler = async (
 				for (const answer of aData.items.slice(0, 5)) {
 					const accepted = answer.is_accepted ? " (Accepted)" : "";
 					md += `### Score: ${answer.score}${accepted} · by ${answer.owner.display_name}\n\n`;
-					md += `${htmlToBasicMarkdown(answer.body)}\n\n---\n\n`;
+					md += `${await htmlToBasicMarkdown(answer.body)}\n\n---\n\n`;
 				}
 			}
 		}

package/src/web/scrapers/types.ts

@@ -2,8 +2,8 @@
  * Shared types and utilities for web-fetch handlers
  */
 import { ptree } from "@oh-my-pi/pi-utils";
-import TurndownService from "turndown";
-import { gfm } from "turndown-plugin-gfm";
+import type TurndownService from "turndown";
+
 import { ToolAbortError } from "../../tools/tool-errors";
 
 export { formatNumber } from "@oh-my-pi/pi-utils";
@@ -155,28 +155,8 @@ export async function loadPage(url: string, options: LoadPageOptions = {}): Prom
 	return { content: "", contentType: "", finalUrl: url, ok: false };
 }
 
-/** Module-level Turndown instance — matches markit-ai's configuration. */
-const turndown = new TurndownService({
-	headingStyle: "atx",
-	codeBlockStyle: "fenced",
-	bulletListMarker: "-",
-});
-turndown.use(gfm);
-turndown.addRule("strikethrough", {
-	filter: ["del", "s", "strike"],
-	replacement(content) {
-		return `~~${content}~~`;
-	},
-});
-turndown.addRule("heading", {
-	filter: ["h1", "h2", "h3", "h4", "h5", "h6"],
-	replacement(content, node) {
-		const level = Number(node.nodeName.charAt(1));
-		const prefix = "#".repeat(level);
-		const cleaned = content.replace(/\\([.])/g, "$1").trim();
-		return `\n\n${prefix} ${cleaned}\n\n`;
-	},
-});
+/** Module-level Turndown instance — built lazily on first use. */
+let turndownPromise: Promise<TurndownService> | undefined;
 
 type TurndownListParent = {
 	nodeName: string;
@@ -184,27 +164,61 @@ type TurndownListParent = {
 	children: ArrayLike<unknown>;
 };
 
-turndown.addRule("listItem", {
-	filter: "li",
-	replacement(content, node, options) {
-		content = content.replace(/^\n+/, "").replace(/\n+$/, "\n").replace(/\n/gm, "\n  ");
-		const parent = node.parentNode as unknown as TurndownListParent | null;
-		let prefix = `${options.bulletListMarker} `;
-		if (parent?.nodeName === "OL") {
-			const start = parent.getAttribute("start");
-			const index = Array.prototype.indexOf.call(parent.children, node);
-			prefix = `${(start ? Number(start) : 1) + index}. `;
-		}
-		return prefix + content + (node.nextSibling ? "\n" : "");
-	},
-});
+function getTurndown(): Promise<TurndownService> {
+	turndownPromise ||= initTurndown();
+	return turndownPromise;
+}
+
+async function initTurndown(): Promise<TurndownService> {
+	const [{ default: TurndownService }, { gfm }] = await Promise.all([
+		import("turndown"),
+		import("turndown-plugin-gfm"),
+	]);
+	const turndown = new TurndownService({
+		headingStyle: "atx",
+		codeBlockStyle: "fenced",
+		bulletListMarker: "-",
+	});
+	turndown.use(gfm);
+	turndown.addRule("strikethrough", {
+		filter: ["del", "s", "strike"],
+		replacement(content) {
+			return `~~${content}~~`;
+		},
+	});
+	turndown.addRule("heading", {
+		filter: ["h1", "h2", "h3", "h4", "h5", "h6"],
+		replacement(content, node) {
+			const level = Number(node.nodeName.charAt(1));
+			const prefix = "#".repeat(level);
+			const cleaned = content.replace(/\\([.])/g, "$1").trim();
+			return `\n\n${prefix} ${cleaned}\n\n`;
+		},
+	});
+	turndown.addRule("listItem", {
+		filter: "li",
+		replacement(content, node, options) {
+			content = content.replace(/^\n+/, "").replace(/\n+$/, "\n").replace(/\n/gm, "\n  ");
+			const parent = node.parentNode as unknown as TurndownListParent | null;
+			let prefix = `${options.bulletListMarker} `;
+			if (parent?.nodeName === "OL") {
+				const start = parent.getAttribute("start");
+				const index = Array.prototype.indexOf.call(parent.children, node);
+				prefix = `${(start ? Number(start) : 1) + index}. `;
+			}
+			return prefix + content + (node.nextSibling ? "\n" : "");
+		},
+	});
+	return turndown;
+}
 
 /**
  * Convert HTML to markdown using Turndown with GFM support.
  * Strips script/style tags before conversion.
  */
-export function htmlToBasicMarkdown(html: string): string {
+export async function htmlToBasicMarkdown(html: string): Promise<string> {
 	const cleaned = html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "");
+	const turndown = await getTurndown();
 	return turndown.turndown(cleaned).trim();
 }
 

package/src/web/scrapers/w3c.ts

@@ -100,7 +100,7 @@ export const handleW3c: SpecialHandler = async (
 		const title = getString(specPayload, "title");
 		const shortnameValue = getString(specPayload, "shortname") ?? shortname;
 		const description = getString(specPayload, "description") ?? getString(specPayload, "abstract");
-		const abstract = description ? htmlToBasicMarkdown(description) : undefined;
+		const abstract = description ? await htmlToBasicMarkdown(description) : undefined;
 
 		const latestVersionUrl =
 			getString(latestPayload, "uri") ??

package/src/web/search/providers/gemini.ts

@@ -8,7 +8,7 @@
 import {
 	ANTIGRAVITY_SYSTEM_INSTRUCTION,
 	extractRetryDelay,
-	getAntigravityHeaders,
+	getAntigravityUserAgent,
 	getGeminiCliHeaders,
 } from "@oh-my-pi/pi-ai";
 import { refreshAntigravityToken } from "@oh-my-pi/pi-ai/utils/oauth/google-antigravity";
@@ -248,7 +248,7 @@ async function callGeminiSearch(
 	usage?: { inputTokens: number; outputTokens: number; totalTokens: number };
 }> {
 	const endpoints = auth.isAntigravity ? ANTIGRAVITY_ENDPOINT_FALLBACKS : [DEFAULT_ENDPOINT];
-	const headers = auth.isAntigravity ? getAntigravityHeaders() : getGeminiCliHeaders();
+	const headers = auth.isAntigravity ? { "User-Agent": getAntigravityUserAgent() } : getGeminiCliHeaders();
 
 	const requestMetadata = auth.isAntigravity
 		? {