@oh-my-pi/pi-coding-agent 10.3.2 → 10.6.0

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 ## [Unreleased]
 
+## [10.6.0] - 2026-02-04
+### Breaking Changes
+
+- Removed `output_mode` parameter from grep tool—results now always use content mode with formatted match output
+- Renamed grep context parameters from `context_pre`/`context_post` to `pre`/`post`
+- Removed `n` (show line numbers) parameter—line numbers are now always displayed in grep results
+
+### Added
+
+- Added Jina as a web search provider option alongside Exa, Perplexity, and Anthropic
+- Added support for Jina Reader API integration with automatic provider detection when JINA_API_KEY is configured
+
+### Changed
+
+- Reformatted grep output to display matches grouped by file with numbered match headers and aligned context lines
+- Updated grep output to use `>>` prefix for match lines and aligned spacing for context lines for improved readability
+- Changed multiline matching to automatically enable when pattern contains literal newlines (`
+`)
+- Split grep context parameter into separate `context_pre` and `context_post` options for independent control of lines before and after matches
+- Updated grep tool to use configurable default context settings from `grep.contextBefore` and `grep.contextAfter` configuration
+- Added configurable grep context defaults and reduced the default to 1 line before, 3 lines after
+- Enabled the browser tool by default
+
+### Removed
+
+- Removed `filesWithMatches` and `count` output modes from grep tool
+
+## [10.5.0] - 2026-02-04
+
+### Breaking Changes
+
+- Changed `ask` tool to require `questions` array parameter; single-question mode with `question`, `options`, `multi`, and `recommended` parameters is no longer supported
+- Removed support for local Python kernel gateway startup; shared gateway is now required
+
+### Added
+
+- Added browser tool powered by Ulixee Hero with support for navigation, DOM interaction, screenshots, and readable content extraction
+- Added `/browser` command to toggle browser headless vs visible mode in interactive sessions
+- Added `browser.enabled` and `browser.headless` settings to control browser automation behavior
+- Added Python prelude caching to improve startup performance by storing compiled prelude helpers and module metadata
+- Added `OMP_DEBUG_STARTUP` environment variable for conditional startup performance debugging output
+- Added autonomous memory system with storage, memory tools, and context injection
+
+### Changed
+
+- Updated task tool guidance to enforce small, well-defined task scope with maximum 3-5 files per task to prevent timeouts and improve parallel execution
+- Updated browser viewport to use 1.25x device scale factor for improved rendering on high-DPI displays
+- Modified device pixel ratio detection to respect actual screen capabilities instead of forcing 1x ratio
+- Updated system prompt guidance to state assumptions and proceed without asking for confirmation, reducing unnecessary round-trips
+- Tightened `ask` tool conditions to require multiple approaches with significantly different tradeoffs before prompting user
+- Strengthened `ask` tool guidance to default to action and only ask when genuinely blocked by decisions with materially different outcomes
+- Changed refactor workflow to automatically remove now-unused elements and note removals instead of asking for confirmation
+- Enforced exclusive concurrency mode for all file-modifying tools (edit, write, bash, python, ssh, todo-write) to prevent concurrent execution conflicts
+- Updated `ask` tool guidance to prioritize proactive problem-solving and default to action, asking only when truly blocked by decisions that materially change scope or behavior
+- Changed Python kernel initialization to require shared gateway mode; local gateway startup has been removed
+- Changed shared gateway error handling to retry on server errors (5xx status codes) before failing
+
+### Fixed
+
+- Fixed glob search returning no results when all files are ignored by gitignore by automatically retrying without gitignore filtering
+
 ## [10.3.2] - 2026-02-03
 ### Added
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "10.3.2",
+	"version": "10.6.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -79,31 +79,36 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@oh-my-pi/omp-stats": "10.3.2",
-		"@oh-my-pi/pi-agent-core": "10.3.2",
-		"@oh-my-pi/pi-ai": "10.3.2",
-		"@oh-my-pi/pi-natives": "10.3.2",
-		"@oh-my-pi/pi-tui": "10.3.2",
-		"@oh-my-pi/pi-utils": "10.3.2",
-		"@openai/agents": "^0.4.4",
+		"@mozilla/readability": "0.6.0",
+		"@oh-my-pi/omp-stats": "10.6.0",
+		"@oh-my-pi/pi-agent-core": "10.6.0",
+		"@oh-my-pi/pi-ai": "10.6.0",
+		"@oh-my-pi/pi-natives": "10.6.0",
+		"@oh-my-pi/pi-tui": "10.6.0",
+		"@oh-my-pi/pi-utils": "10.6.0",
+		"@openai/agents": "^0.4.5",
 		"@sinclair/typebox": "^0.34.48",
 		"ajv": "^8.17.1",
 		"chalk": "^5.6.2",
 		"diff": "^8.0.3",
 		"file-type": "^21.3.0",
-		"glob": "^13.0.0",
+		"glob": "^13.0.1",
 		"handlebars": "^4.7.8",
 		"ignore": "^7.0.5",
+		"jsdom": "28.0.0",
 		"marked": "^17.0.1",
 		"nanoid": "^5.1.6",
 		"node-html-parser": "^7.0.2",
+		"puppeteer": "^24.36.1",
 		"smol-toml": "^1.6.0",
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@types/diff": "^8.0.0",
+		"@types/diff": "^7.0.2",
+		"@types/jsdom": "27.0.0",
+		"bun-types": "^1.3.8",
 		"@types/ms": "^2.1.0",
-		"@types/node": "^25.0.10",
+		"@types/bun": "^1.3.8",
 		"ms": "^2.1.3"
 	},
 	"keywords": [

package/src/capability/index.ts

@@ -8,6 +8,12 @@
  */
 import * as os from "node:os";
 import * as path from "node:path";
+
+/** Conditional startup debug prints (stderr) when OMP_DEBUG_STARTUP is set */
+const debugStartup = process.env.OMP_DEBUG_STARTUP
+	? (stage: string) => process.stderr.write(`[startup] ${stage}\n`)
+	: () => {};
+
 import type { Settings } from "../config/settings";
 import { clearCache as clearFsCache, cacheStats as fsCacheStats, invalidate as invalidateFs } from "./fs";
 import type {
@@ -109,9 +115,12 @@ async function loadImpl<T>(
 	const results = await Promise.all(
 		providers.map(async provider => {
 			try {
+				debugStartup(`capability:${capability.id}:${provider.id}:start`);
 				const result = await provider.load(ctx);
+				debugStartup(`capability:${capability.id}:${provider.id}:done`);
 				return { provider, result };
 			} catch (error) {
+				debugStartup(`capability:${capability.id}:${provider.id}:error`);
 				return { provider, error };
 			}
 		}),

package/src/cli/update-cli.ts

@@ -7,7 +7,6 @@
 import { execSync, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { isEnoent } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
@@ -200,8 +199,7 @@ async function updateViaBinary(release: ReleaseInfo): Promise<void> {
 	}
 
 	const fileStream = fs.createWriteStream(tempPath, { mode: 0o755 });
-	const nodeStream = Readable.fromWeb(response.body as import("stream/web").ReadableStream);
-	await pipeline(nodeStream, fileStream);
+	await pipeline(response.body, fileStream);
 
 	// Download native addon
 	console.log(chalk.dim(`Downloading ${nativeAddonName}...`));
@@ -212,8 +210,7 @@ async function updateViaBinary(release: ReleaseInfo): Promise<void> {
 	}
 
 	const nativeFileStream = fs.createWriteStream(nativeTempPath, { mode: 0o755 });
-	const nativeNodeStream = Readable.fromWeb(nativeResponse.body as import("stream/web").ReadableStream);
-	await pipeline(nativeNodeStream, nativeFileStream);
+	await pipeline(nativeResponse.body, nativeFileStream);
 
 	// Replace current binary
 	console.log(chalk.dim("Installing update..."));

package/src/config/settings-schema.ts

@@ -329,6 +329,26 @@ export const SETTINGS_SCHEMA = {
 		default: true,
 		ui: { tab: "tools", label: "Enable Grep", description: "Enable the grep tool for content searching" },
 	},
+	"grep.contextBefore": {
+		type: "number",
+		default: 1,
+		ui: {
+			tab: "tools",
+			label: "Grep context before",
+			description: "Lines of context before each grep match",
+			submenu: true,
+		},
+	},
+	"grep.contextAfter": {
+		type: "number",
+		default: 3,
+		ui: {
+			tab: "tools",
+			label: "Grep context after",
+			description: "Lines of context after each grep match",
+			submenu: true,
+		},
+	},
 	"notebook.enabled": {
 		type: "boolean",
 		default: true,
@@ -358,6 +378,24 @@ export const SETTINGS_SCHEMA = {
 			description: "Enable the calculator tool for basic calculations",
 		},
 	},
+	"browser.enabled": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "tools",
+			label: "Enable Browser",
+			description: "Enable the browser tool (Ulixee Hero)",
+		},
+	},
+	"browser.headless": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "tools",
+			label: "Browser headless",
+			description: "Launch browser in headless mode (disable to show browser UI)",
+		},
+	},
 
 	// ─────────────────────────────────────────────────────────────────────────
 	// Startup settings
@@ -467,7 +505,7 @@ export const SETTINGS_SCHEMA = {
 	// ─────────────────────────────────────────────────────────────────────────
 	"providers.webSearch": {
 		type: "enum",
-		values: ["auto", "exa", "perplexity", "anthropic"] as const,
+		values: ["auto", "exa", "jina", "perplexity", "anthropic"] as const,
 		default: "auto",
 		ui: { tab: "services", label: "Web search provider", description: "Provider for web search tool", submenu: true },
 	},

package/src/cursor.ts

@@ -167,7 +167,7 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 			pattern: args.pattern,
 			path: args.path || undefined,
 			glob: args.glob || undefined,
-			output_mode: args.outputMode || undefined,
+			mode: args.outputMode || undefined,
 			context: args.context ?? args.contextBefore ?? args.contextAfter ?? undefined,
 			ignore_case: args.caseInsensitive || undefined,
 			type: args.type || undefined,

package/src/extensibility/custom-tools/wrapper.ts

@@ -1,34 +1,25 @@
 /**
  * CustomToolAdapter wraps CustomTool instances into AgentTool for use with the agent.
  */
-import type { AgentTool, AgentToolResult, AgentToolUpdateCallback, RenderResultOptions } from "@oh-my-pi/pi-agent-core";
-import type { Component } from "@oh-my-pi/pi-tui";
+import type { AgentTool, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Static, TSchema } from "@sinclair/typebox";
 import type { Theme } from "../../modes/theme/theme";
+import { applyToolProxy } from "../tool-proxy";
 import type { CustomTool, CustomToolContext, LoadedCustomTool } from "./types";
 
 export class CustomToolAdapter<TParams extends TSchema = TSchema, TDetails = any, TTheme extends Theme = Theme>
 	implements AgentTool<TParams, TDetails, TTheme>
 {
+	declare name: string;
+	declare label: string;
+	declare description: string;
+	declare parameters: TParams;
+
 	constructor(
 		private tool: CustomTool<TParams, TDetails>,
 		private getContext: () => CustomToolContext,
-	) {}
-
-	get name() {
-		return this.tool.name;
-	}
-
-	get label() {
-		return this.tool.label;
-	}
-
-	get description() {
-		return this.tool.description;
-	}
-
-	get parameters() {
-		return this.tool.parameters;
+	) {
+		applyToolProxy(tool, this);
 	}
 
 	execute(
@@ -41,21 +32,6 @@ export class CustomToolAdapter<TParams extends TSchema = TSchema, TDetails = any
 		return this.tool.execute(toolCallId, params, onUpdate, context ?? this.getContext(), signal);
 	}
 
-	/** Optional custom rendering for tool call display (returns UI component) */
-	renderCall(args: Static<TParams>, theme: TTheme): Component | undefined {
-		return this.tool.renderCall?.(args, theme);
-	}
-
-	/** Optional custom rendering for tool result display (returns UI component) */
-	renderResult(
-		result: AgentToolResult<TDetails>,
-		options: RenderResultOptions,
-		theme: TTheme,
-		args?: Static<TParams>,
-	): Component | undefined {
-		return this.tool.renderResult?.(result, options, theme, args);
-	}
-
 	/**
 	 * Backward-compatible export of factory function for existing callers.
 	 * Prefer CustomToolAdapter constructor directly.

package/src/extensibility/extensions/wrapper.ts

@@ -5,6 +5,7 @@ import type { AgentTool, AgentToolContext, AgentToolUpdateCallback } from "@oh-m
 import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
 import type { Static, TSchema } from "@sinclair/typebox";
 import type { Theme } from "../../modes/theme/theme";
+import { applyToolProxy } from "../tool-proxy";
 import type { ExtensionRunner } from "./runner";
 import type { RegisteredTool, ToolCallEventResult, ToolResultEventResult } from "./types";
 
@@ -12,20 +13,16 @@ import type { RegisteredTool, ToolCallEventResult, ToolResultEventResult } from
  * Adapts a RegisteredTool into an AgentTool.
  */
 export class RegisteredToolAdapter implements AgentTool<any, any, any> {
-	readonly name: string;
-	readonly label: string;
-	readonly description: string;
-	readonly parameters: any;
+	declare name: string;
+	declare description: string;
+	declare parameters: any;
+	declare label: string;
 
 	constructor(
 		private registeredTool: RegisteredTool,
 		private runner: ExtensionRunner,
 	) {
-		const { definition } = registeredTool;
-		this.name = definition.name;
-		this.label = definition.label || "";
-		this.description = definition.description;
-		this.parameters = definition.parameters;
+		applyToolProxy(registeredTool.definition, this);
 	}
 
 	async execute(
@@ -74,35 +71,25 @@ export function wrapRegisteredTools(registeredTools: RegisteredTool[], runner: E
 export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetails = unknown>
 	implements AgentTool<TParameters, TDetails>
 {
-	renderCall?: AgentTool<TParameters, TDetails>["renderCall"];
-	renderResult?: AgentTool<TParameters, TDetails>["renderResult"];
-	mergeCallAndResult?: boolean;
-	inline?: boolean;
+	declare name: string;
+	declare description: string;
+	declare parameters: TParameters;
+	declare label: string;
 
 	constructor(
 		private tool: AgentTool<TParameters, TDetails>,
 		private runner: ExtensionRunner,
 	) {
-		this.renderCall = tool.renderCall?.bind(tool);
-		this.renderResult = tool.renderResult?.bind(tool);
-		this.mergeCallAndResult = (tool as { mergeCallAndResult?: boolean }).mergeCallAndResult;
-		this.inline = (tool as { inline?: boolean }).inline;
+		applyToolProxy(tool, this);
 	}
 
-	get name(): string {
-		return this.tool.name;
-	}
-
-	get label(): string {
-		return this.tool.label ?? "";
-	}
-
-	get description(): string {
-		return this.tool.description;
-	}
-
-	get parameters(): TParameters {
-		return this.tool.parameters;
+	/**
+	 * Forward browser mode changes when available.
+	 */
+	restartForModeChange(): Promise<void> {
+		const target = this.tool as { restartForModeChange?: () => Promise<void> };
+		if (!target.restartForModeChange) return Promise.resolve();
+		return target.restartForModeChange();
 	}
 
 	async execute(

package/src/extensibility/hooks/tool-wrapper.ts

@@ -3,6 +3,7 @@
  */
 import type { AgentTool, AgentToolContext, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Static, TSchema } from "@sinclair/typebox";
+import { applyToolProxy } from "../tool-proxy";
 import type { HookRunner } from "./runner";
 import type { ToolCallEventResult, ToolResultEventResult } from "./types";
 
@@ -17,27 +18,16 @@ import type { ToolCallEventResult, ToolResultEventResult } from "./types";
 export class HookToolWrapper<TParameters extends TSchema = TSchema, TDetails = unknown>
 	implements AgentTool<TParameters, TDetails>
 {
-	name: string;
-	label: string;
-	description: string;
-	parameters: TParameters;
-	renderCall?: AgentTool<TParameters, TDetails>["renderCall"];
-	renderResult?: AgentTool<TParameters, TDetails>["renderResult"];
-	mergeCallAndResult?: boolean;
-	inline?: boolean;
+	declare name: string;
+	declare description: string;
+	declare parameters: TParameters;
+	declare label: string;
 
 	constructor(
 		private tool: AgentTool<TParameters, TDetails>,
 		private hookRunner: HookRunner,
 	) {
-		this.name = tool.name;
-		this.label = tool.label ?? "";
-		this.description = tool.description;
-		this.parameters = tool.parameters;
-		this.renderCall = tool.renderCall?.bind(tool);
-		this.renderResult = tool.renderResult?.bind(tool);
-		this.mergeCallAndResult = (tool as { mergeCallAndResult?: boolean }).mergeCallAndResult;
-		this.inline = (tool as { inline?: boolean }).inline;
+		applyToolProxy(tool, this);
 	}
 
 	async execute(

package/src/extensibility/tool-proxy.ts

@@ -0,0 +1,25 @@
+/**
+ * Defines lazy proxy properties on a wrapper so it forwards to the underlying tool.
+ */
+export function applyToolProxy<TTool extends object>(tool: TTool, wrapper: object): void {
+	const visited = new Set<PropertyKey>();
+	let current: object | null = tool;
+
+	while (current && current !== Object.prototype) {
+		for (const key of Reflect.ownKeys(current)) {
+			if (key === "constructor" || visited.has(key) || key in wrapper) {
+				continue;
+			}
+			visited.add(key);
+			Object.defineProperty(wrapper, key, {
+				get() {
+					const value = (tool as Record<PropertyKey, unknown>)[key];
+					return typeof value === "function" ? value.bind(tool) : value;
+				},
+				enumerable: true,
+				configurable: true,
+			});
+		}
+		current = Object.getPrototypeOf(current);
+	}
+}

package/src/index.ts

@@ -239,6 +239,7 @@ export {
 // Tools (detail types and utilities)
 export {
 	type BashToolDetails,
+	type BrowserToolDetails,
 	DEFAULT_MAX_BYTES,
 	DEFAULT_MAX_LINES,
 	type FindOperations,

package/src/ipy/executor.ts

@@ -1,4 +1,6 @@
-import { logger } from "@oh-my-pi/pi-utils";
+import * as path from "node:path";
+import { isEnoent, logger } from "@oh-my-pi/pi-utils";
+import { getAgentDir } from "../config";
 import { OutputSink } from "../session/streaming-output";
 import { time } from "../utils/timings";
 import { shutdownSharedGateway } from "./gateway-coordinator";
@@ -10,6 +12,12 @@ import {
 	type PreludeHelper,
 	PythonKernel,
 } from "./kernel";
+import { discoverPythonModules } from "./modules";
+import { PYTHON_PRELUDE } from "./prelude";
+
+const debugStartup = process.env.OMP_DEBUG_STARTUP
+	? (stage: string) => process.stderr.write(`[startup] ${stage}\n`)
+	: () => {};
 
 const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 const MAX_KERNEL_SESSIONS = 4;
@@ -86,6 +94,72 @@ const kernelSessions = new Map<string, KernelSession>();
 let cachedPreludeDocs: PreludeHelper[] | null = null;
 let cleanupTimer: NodeJS.Timeout | null = null;
 
+interface PreludeCacheSource {
+	path: string;
+	hash: string;
+}
+
+interface PreludeCachePayload {
+	helpers: PreludeHelper[];
+	sources: PreludeCacheSource[];
+}
+
+interface PreludeCacheState {
+	cacheKey: string;
+	cachePath: string;
+	sources: PreludeCacheSource[];
+}
+
+const PRELUDE_CACHE_DIR = "pycache";
+
+function hashPreludeContent(content: string): string {
+	return Bun.hash(content).toString(16);
+}
+
+async function buildPreludeCacheState(cwd: string): Promise<PreludeCacheState> {
+	const modules = await discoverPythonModules({ cwd });
+	const moduleSources = modules
+		.map(module => ({ path: module.path, hash: hashPreludeContent(module.content) }))
+		.sort((a, b) => a.path.localeCompare(b.path));
+	const sources: PreludeCacheSource[] = [
+		{ path: "omp:prelude", hash: hashPreludeContent(PYTHON_PRELUDE) },
+		...moduleSources,
+	];
+	const composite = sources.map(source => `${source.path}:${source.hash}`).join("|");
+	const cacheKey = Bun.hash(composite).toString(16);
+	const cachePath = path.join(getAgentDir(), PRELUDE_CACHE_DIR, `${cacheKey}.json`);
+	return { cacheKey, cachePath, sources };
+}
+
+async function readPreludeCache(state: PreludeCacheState): Promise<PreludeHelper[] | null> {
+	let raw: string;
+	try {
+		raw = await Bun.file(state.cachePath).text();
+	} catch (err) {
+		if (isEnoent(err)) return null;
+		logger.warn("Failed to read Python prelude cache", { path: state.cachePath, error: String(err) });
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw) as PreludeCachePayload | PreludeHelper[];
+		const helpers = Array.isArray(parsed) ? parsed : parsed.helpers;
+		if (!Array.isArray(helpers) || helpers.length === 0) return null;
+		return helpers;
+	} catch (err) {
+		logger.warn("Failed to parse Python prelude cache", { path: state.cachePath, error: String(err) });
+		return null;
+	}
+}
+
+async function writePreludeCache(state: PreludeCacheState, helpers: PreludeHelper[]): Promise<void> {
+	const payload: PreludeCachePayload = { helpers, sources: state.sources };
+	try {
+		await Bun.write(state.cachePath, JSON.stringify(payload));
+	} catch (err) {
+		logger.warn("Failed to write Python prelude cache", { path: state.cachePath, error: String(err) });
+	}
+}
+
 function startCleanupTimer(): void {
 	if (cleanupTimer) return;
 	cleanupTimer = setInterval(() => {
@@ -153,19 +227,37 @@ export async function warmPythonEnvironment(
 	useSharedGateway?: boolean,
 	sessionFile?: string,
 ): Promise<{ ok: boolean; reason?: string; docs: PreludeHelper[] }> {
+	const isTestEnv = process.env.BUN_ENV === "test" || process.env.NODE_ENV === "test";
+	let cacheState: PreludeCacheState | null = null;
 	try {
+		debugStartup("warmPython:ensureKernel:start");
 		await ensureKernelAvailable(cwd);
+		debugStartup("warmPython:ensureKernel:done");
 		time("warmPython:ensureKernelAvailable");
 	} catch (err: unknown) {
 		const reason = err instanceof Error ? err.message : String(err);
 		cachedPreludeDocs = [];
 		return { ok: false, reason, docs: [] };
 	}
+	if (!isTestEnv) {
+		try {
+			cacheState = await buildPreludeCacheState(cwd);
+			const cached = await readPreludeCache(cacheState);
+			if (cached) {
+				cachedPreludeDocs = cached;
+				return { ok: true, docs: cached };
+			}
+		} catch (err) {
+			logger.warn("Failed to resolve Python prelude cache", { error: String(err) });
+			cacheState = null;
+		}
+	}
 	if (cachedPreludeDocs && cachedPreludeDocs.length > 0) {
 		return { ok: true, docs: cachedPreludeDocs };
 	}
 	const resolvedSessionId = sessionId ?? `session:${cwd}`;
 	try {
+		debugStartup("warmPython:withKernelSession:start");
 		const docs = await withKernelSession(
 			resolvedSessionId,
 			cwd,
@@ -173,8 +265,13 @@ export async function warmPythonEnvironment(
 			useSharedGateway,
 			sessionFile,
 		);
+		debugStartup("warmPython:withKernelSession:done");
 		time("warmPython:withKernelSession");
 		cachedPreludeDocs = docs;
+		if (!isTestEnv && docs.length > 0) {
+			const state = cacheState ?? (await buildPreludeCacheState(cwd));
+			await writePreludeCache(state, docs);
+		}
 		return { ok: true, docs };
 	} catch (err: unknown) {
 		const reason = err instanceof Error ? err.message : String(err);
@@ -226,6 +323,7 @@ async function createKernelSession(
 	artifactsDir?: string,
 	isRetry?: boolean,
 ): Promise<KernelSession> {
+	debugStartup("kernel:createSession:entry");
 	const env: Record<string, string> | undefined =
 		sessionFile || artifactsDir
 			? {
@@ -236,7 +334,9 @@ async function createKernelSession(
 
 	let kernel: PythonKernel;
 	try {
+		debugStartup("kernel:PythonKernel.start:start");
 		kernel = await PythonKernel.start({ cwd, useSharedGateway, env });
+		debugStartup("kernel:PythonKernel.start:done");
 		time("createKernelSession:PythonKernel.start");
 	} catch (err) {
 		if (!isRetry && isResourceExhaustionError(err)) {
@@ -314,6 +414,7 @@ async function withKernelSession<T>(
 	sessionFile?: string,
 	artifactsDir?: string,
 ): Promise<T> {
+	debugStartup("kernel:withSession:entry");
 	let session = kernelSessions.get(sessionId);
 	if (!session) {
 		// Evict oldest session if at capacity
@@ -321,17 +422,21 @@ async function withKernelSession<T>(
 			await evictOldestSession();
 		}
 		session = await createKernelSession(sessionId, cwd, useSharedGateway, sessionFile, artifactsDir);
+		debugStartup("kernel:withSession:created");
 		kernelSessions.set(sessionId, session);
 		startCleanupTimer();
 	}
 
 	const run = async (): Promise<T> => {
+		debugStartup("kernel:withSession:run");
 		session!.lastUsedAt = Date.now();
 		if (session!.dead || !session!.kernel.isAlive()) {
 			await restartKernelSession(session!, cwd, useSharedGateway, sessionFile, artifactsDir);
 		}
 		try {
+			debugStartup("kernel:withSession:handler:start");
 			const result = await handler(session!.kernel);
+			debugStartup("kernel:withSession:handler:done");
 			session!.restartCount = 0;
 			return result;
 		} catch (err) {
@@ -424,8 +529,7 @@ export async function executePython(code: string, options?: PythonExecutorOption
 	await ensureKernelAvailable(cwd);
 
 	const kernelMode = options?.kernelMode ?? "session";
-	const isTestEnv = process.env.BUN_ENV === "test" || process.env.NODE_ENV === "test";
-	const useSharedGateway = isTestEnv ? false : options?.useSharedGateway;
+	const useSharedGateway = options?.useSharedGateway;
 	const sessionFile = options?.sessionFile;
 	const artifactsDir = options?.artifactsDir;