@code-yeongyu/senpi-codemode 2026.9.27 → 2026.9.28-3

package/CHANGELOG.md

@@ -12,6 +12,82 @@
 
 ### Removed
 
+## [2026.9.28-3] - 2026-09-28
+
+### Breaking Changes
+
+### Added
+
+### Changed
+
+### Fixed
+
+- `new Bun.WebView()` in a JavaScript eval cell no longer fails with `Bun.WebView with backend "chrome" is only available on the main thread` (every call on Windows and Linux, `backend: "chrome"` on macOS). Cells see a `Bun` whose `WebView` (also through `import { WebView } from "bun"`) hands Chrome-backed views to the process main thread with the same API: navigation, input, `evaluate`, screenshots, `cdp()` and its events, `console` capture, `url`/`title`/`loading`, `close()` and `await using`. The macOS default (WebKit) stays a native view in the kernel worker. `Bun.WebView.closeAll()` in a cell closes only that kernel's views. ([#2248](https://github.com/code-yeongyu/senpi/issues/2248))
+
+### Removed
+
+## [2026.9.28-2] - 2026-09-28
+
+### Breaking Changes
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [2026.9.28] - 2026-09-28
+
+### Breaking Changes
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [2026.9.27-4] - 2026-09-27
+
+### Breaking Changes
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [2026.9.27-3] - 2026-09-27
+
+### Breaking Changes
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [2026.9.27-2] - 2026-09-27
+
+### Breaking Changes
+
+### Added
+
+- The eval kernels install each active tool's `kernelPrelude`: its JavaScript or Python statements run before a cell whenever one of the prelude's exports is missing, a deactivated tool's exports are removed before the next cell, and each prelude's documentation line joins the eval prompt's helper list. Exports that would shadow a built-in helper are rejected. ([#2178](https://github.com/code-yeongyu/senpi/pull/2178))
+
+### Changed
+
+### Fixed
+
+### Removed
+
 ## [2026.9.27] - 2026-09-27
 
 ### Breaking Changes

package/README.md

@@ -162,6 +162,13 @@ into the cell carries the tool's expected parameters, so the cell can correct th
 arguments and retry instead of falling back to one-at-a-time tool calls.
 `tool_schema()` exposes the same catalog up front.
 
+A tool may also contribute globals of its own through `ToolDefinition.kernelPrelude`
+(JavaScript and Python snippets that call the ordinary `tool.<name>()`, one
+documentation line, and the exported names). While the tool is active, each
+JavaScript and Python cell installs any missing export first and the eval prompt
+lists the documentation line; once the tool is deactivated, the next cell deletes
+those names. Exports that shadow a built-in helper are rejected by the host.
+
 `agent()` is available only when the configured task tool is active in the
 session. `output()` similarly requires the configured task-output tool and
 returns immediately: a running task reports its current status, while completed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.9.27",
+	"version": "2026.9.28-3",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -30,14 +30,14 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.9.27",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.9.28-3",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.9.27"
+		"@code-yeongyu/senpi": "2026.9.28-3"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.9.27"
+		"@code-yeongyu/senpi": "2026.9.28-3"
 	},
 	"keywords": [
 		"senpi",

package/src/bridge/protocol.ts

@@ -37,6 +37,15 @@ const hostToKernelMessageSchema = Type.Union([
 		cellId: Type.String({ minLength: 1 }),
 		code: Type.String(),
 		timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
+		/** Python only: active tool globals to install before the cell and deactivated ones to remove. */
+		preludes: Type.Optional(
+			Type.Object({
+				install: Type.Array(
+					Type.Object({ exports: Type.Array(Type.String({ minLength: 1 })), python: Type.String() }),
+				),
+				remove: Type.Array(Type.String({ minLength: 1 })),
+			}),
+		),
 	}),
 	Type.Object({
 		type: Type.Literal("tool-reply"),
@@ -57,6 +66,19 @@ const hostToKernelMessageSchema = Type.Union([
 	Type.Object({
 		type: Type.Literal("close"),
 	}),
+	/** JS only: the kernel's private port to the main-thread Bun.WebView service, sent in the transfer list. */
+	Type.Object({
+		type: Type.Literal("webview-port"),
+		requestId: Type.String({ minLength: 1 }),
+		ok: Type.Literal(true),
+		port: Type.Unknown(),
+	}),
+	Type.Object({
+		type: Type.Literal("webview-port"),
+		requestId: Type.String({ minLength: 1 }),
+		ok: Type.Literal(false),
+		error: bridgeErrorSchema,
+	}),
 	...kernelToolHostToKernelSchemas,
 ]);
 
@@ -97,6 +119,7 @@ const kernelToHostMessageSchema = Type.Union([
 		durationMs: Type.Integer({ minimum: 0 }),
 	}),
 	Type.Object({ type: Type.Literal("closed") }),
+	Type.Object({ type: Type.Literal("webview-connect"), requestId: Type.String({ minLength: 1 }) }),
 	...kernelToolKernelToHostSchemas,
 ]);
 

package/src/bridges/schema-bridge.ts

@@ -1,3 +1,4 @@
+import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
 import { type Static, Type } from "typebox";
 import { Check, Errors } from "typebox/value";
 
@@ -12,6 +13,7 @@ export interface EvalSchemaToolInfo {
 	readonly name: string;
 	readonly description?: string | undefined;
 	readonly parameters?: unknown;
+	readonly kernelPrelude?: KernelPreludeContribution | undefined;
 }
 
 export interface RunEvalSchemaOptions {

package/src/extension/kernel-preludes.ts

@@ -0,0 +1,30 @@
+import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
+import type { CodemodeRuntimeAPI } from "./runtime-factory.ts";
+
+type ToolRegistry = Pick<CodemodeRuntimeAPI, "getActiveTools" | "getAllTools">;
+
+/**
+ * Kernel globals of the tools active right now. Read per cell, so a tool activated by `tool_search`, a by-name
+ * call, or a command shows up in the next cell and a deactivated one disappears, whatever the registration order.
+ */
+export function activeKernelPreludes(pi: ToolRegistry): readonly KernelPreludeContribution[] {
+	const active = new Set(pi.getActiveTools());
+	return pi.getAllTools().flatMap((tool) => (tool.kernelPrelude && active.has(tool.name) ? [tool.kernelPrelude] : []));
+}
+
+/** Identity of the prompt's contribution doc lines; the eval tool re-registers only when it changes. */
+export function kernelPreludeDocsKey(preludes: readonly KernelPreludeContribution[]): string {
+	return preludes.map((prelude) => prelude.documentation).join("\n");
+}
+
+/**
+ * The contributions the eval description documents. Like the monitor probe, an unreadable registry (the loader's
+ * action methods throw until the runtime binds) teaches nothing; the per-cell read still surfaces any error.
+ */
+export function promptKernelPreludes(pi: ToolRegistry): readonly KernelPreludeContribution[] {
+	try {
+		return activeKernelPreludes(pi);
+	} catch {
+		return [];
+	}
+}

package/src/index.ts

@@ -13,6 +13,7 @@ import {
 import { EvalNotifier } from "./extension/eval-notifier.ts";
 import { EVAL_CELLS_STATUS_KEY } from "./extension/eval-status.ts";
 import { EvalStatusTicker } from "./extension/eval-status-ticker.ts";
+import { activeKernelPreludes, kernelPreludeDocsKey, promptKernelPreludes } from "./extension/kernel-preludes.ts";
 import {
 	createExecuteTool,
 	createRuntime,
@@ -43,7 +44,7 @@ const SESSION_LIFECYCLE_EVENTS = [
 
 type SessionLifecycleEvent = (typeof SESSION_LIFECYCLE_EVENTS)[number];
 
-type CodemodeEvent = SessionLifecycleEvent | "model_select";
+type CodemodeEvent = SessionLifecycleEvent | "model_select" | "turn_start";
 
 export interface CodemodeExtensionAPI {
 	registerTool(tool: ReturnType<typeof createEvalTool>): void;
@@ -91,6 +92,7 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 	let activeModelId: string | undefined;
 	let activeContext: ExtensionContext | undefined;
 	let activeCells: EvalDetachedCellManager | undefined;
+	let promptPreludeDocs = "";
 	const notifier = new EvalNotifier({
 		sendMessage: (message, notifyOptions) => pi.sendMessage(message, notifyOptions),
 		getContext: () => activeContext,
@@ -134,6 +136,8 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 		// reaches this before the runtime is bound). An unreadable registry means "do not teach
 		// a tool we cannot confirm"; session_start / model_select re-register once it is live.
 		const monitor = monitorIsRegistered(pi);
+		const preludes = promptKernelPreludes(pi);
+		promptPreludeDocs = kernelPreludeDocsKey(preludes);
 		pi.registerTool(
 			createEvalTool({
 				enabledLanguages: runtime.enabledLanguages,
@@ -156,6 +160,8 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 				spawnDefaultAgent: runtime.settings.taskTools.task,
 				hostLine: hostLine(),
 				runtimes: runtime.runtimes,
+				kernelPreludes: () => activeKernelPreludes(pi),
+				promptKernelPreludes: preludes,
 				...(bunSkillPath === undefined ? {} : { bunSkillPath }),
 				...(modelId === undefined ? {} : { modelId }),
 			}),
@@ -252,6 +258,14 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 		if (cellManager === undefined) return;
 		registerEvalForRuntime(runtime, modelId, cellManager);
 	});
+	// Tool activation has no event of its own; the next turn re-documents a changed contribution set.
+	pi.on("turn_start", async () => {
+		const runtime = activeRuntime;
+		const cellManager = activeCells;
+		if (runtime === undefined || cellManager === undefined) return;
+		if (kernelPreludeDocsKey(promptKernelPreludes(pi)) === promptPreludeDocs) return;
+		registerEvalForRuntime(runtime, activeModelId, cellManager);
+	});
 }
 
 function hostLine(): string {

package/src/kernels/js/context-manager.ts

@@ -195,7 +195,7 @@ export class JavaScriptKernel {
 		this.#slot.postMessage({
 			type: "run",
 			cellId: next.input.cellId,
-			code: this.#moduleLoader.prepareCell(next.input.code),
+			code: this.#moduleLoader.prepareCell(next.input.code, next.input.kernelPreludes),
 			timeoutMs: next.input.timeoutMs,
 		});
 	}

package/src/kernels/js/inline-worker.ts

@@ -1,5 +1,6 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import type { MessagePort } from "node:worker_threads";
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import type { JavaScriptKernelMode } from "./kernel-contract.ts";
@@ -18,7 +19,7 @@ export function resolveInlineWorkerEntryUrl(options: JavaScriptInlineWorkerEntry
 
 export interface WorkerLike {
 	readonly mode: JavaScriptKernelMode;
-	postMessage(message: HostToKernelMessage): void;
+	postMessage(message: HostToKernelMessage, transfer?: readonly MessagePort[]): void;
 	onMessage(handler: (message: KernelToHostMessage) => void): () => void;
 	onError(handler: (error: Error) => void): () => void;
 	terminate(): Promise<void>;

package/src/kernels/js/local-module-loader.ts

@@ -1,5 +1,6 @@
 import { join, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
+import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
 import type { BridgeConnectionConfig } from "../../bridge/protocol.ts";
 import {
 	RESERVED_AGENT_TOOL,
@@ -8,6 +9,7 @@ import {
 	TIMEOUT_PAUSE_OP,
 	TIMEOUT_RESUME_OP,
 } from "../../bridge/reserved.ts";
+import { type KernelPreludePlan, KernelPreludeTracker } from "../shared/kernel-prelude-plan.ts";
 import type { JavaScriptKernelOptions as BaseJavaScriptKernelOptions } from "./kernel-contract.ts";
 import { rewriteImports } from "./rewrite-imports.ts";
 
@@ -75,6 +77,8 @@ function loaderPrelude(context: RuntimeModuleContext): string {
 		"globalThis.__senpi_import__ = async (source, options) => {",
 		"  const context = globalThis.__senpi_module_context__;",
 		"  const specifier = String(source);",
+		"  const kernelBun = globalThis[Symbol.for('senpi.kernel.bun')];",
+		"  if (specifier === 'bun' && kernelBun) return { ...(await import('bun')), WebView: kernelBun.WebView, default: kernelBun };",
 		"  const match = /^([a-z][a-z0-9+.-]*):\\/\\/(.*)$/i.exec(specifier);",
 		"  let target = specifier;",
 		"  if (match) {",
@@ -99,14 +103,26 @@ function loaderPrelude(context: RuntimeModuleContext): string {
 	].join("\n");
 }
 
+/** Removes deactivated exports, then installs each contribution only while one of its exports is missing. */
+function contributionPrelude(plan: KernelPreludePlan): string {
+	const removals = plan.remove.map((name) => `delete globalThis[${JSON.stringify(name)}];`);
+	const installs = plan.install.map((contribution) => {
+		const missing = contribution.exports.map((name) => `!globalThis[${JSON.stringify(name)}]`).join(" || ");
+		return `if (${missing}) {\n${contribution.javascript}\n}`;
+	});
+	return [...removals, ...installs].join("\n");
+}
+
 export class LocalModuleLoader {
 	readonly #prelude: string;
+	readonly #contributions = new KernelPreludeTracker();
 
 	constructor(options: LocalModuleLoaderOptions) {
 		this.#prelude = loaderPrelude(runtimeContext(options));
 	}
 
-	prepareCell(code: string): string {
-		return `${PREPARED_CELL_PREFIX}${JSON.stringify({ prelude: this.#prelude, code: rewriteImports(code) })}`;
+	prepareCell(code: string, contributions: readonly KernelPreludeContribution[] = []): string {
+		const prelude = `${this.#prelude}\n${contributionPrelude(this.#contributions.plan(contributions))}`;
+		return `${PREPARED_CELL_PREFIX}${JSON.stringify({ prelude, code: rewriteImports(code) })}`;
 	}
 }

package/src/kernels/js/webview-host.ts

@@ -0,0 +1,59 @@
+import type { MessagePort } from "node:worker_threads";
+import type { WebViewServiceConnection } from "@code-yeongyu/senpi";
+import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
+import { bridgeError } from "./worker-host.ts";
+
+export type WebViewConnector = () => Promise<WebViewServiceConnection>;
+
+// Loaded on the first WebView a cell asks for, so starting a kernel never pays for the host barrel.
+const connectThroughHost: WebViewConnector = async () => (await import("@code-yeongyu/senpi")).connectWebViewService();
+
+/**
+ * The WebView clients one worker generation asked for. Chrome-backed `Bun.WebView`s only run on the
+ * process main thread, so the worker gets a private port to the main-thread service; retiring the
+ * generation (reset, close, crash, timeout) releases every view created through those ports.
+ */
+export class KernelWebViewClients {
+	readonly #post: (message: HostToKernelMessage, transfer: readonly MessagePort[]) => void;
+	readonly #connect: WebViewConnector;
+	readonly #connections = new Set<WebViewServiceConnection>();
+	#retired = false;
+
+	constructor(
+		post: (message: HostToKernelMessage, transfer: readonly MessagePort[]) => void,
+		connect: WebViewConnector = connectThroughHost,
+	) {
+		this.#post = post;
+		this.#connect = connect;
+	}
+
+	consume(message: KernelToHostMessage): boolean {
+		if (message.type !== "webview-connect") return false;
+		void this.#grant(message.requestId);
+		return true;
+	}
+
+	async release(): Promise<void> {
+		this.#retired = true;
+		const connections = [...this.#connections];
+		this.#connections.clear();
+		await Promise.allSettled(connections.map((connection) => connection.release()));
+	}
+
+	async #grant(requestId: string): Promise<void> {
+		let connection: WebViewServiceConnection;
+		try {
+			connection = await this.#connect();
+		} catch (error) {
+			const cause = error instanceof Error ? error : new Error(String(error));
+			if (!this.#retired) this.#post({ type: "webview-port", requestId, ok: false, error: bridgeError(cause) }, []);
+			return;
+		}
+		if (this.#retired) {
+			await connection.release();
+			return;
+		}
+		this.#connections.add(connection);
+		this.#post({ type: "webview-port", requestId, ok: true, port: connection.port }, [connection.port]);
+	}
+}

package/src/kernels/js/worker-core.js

@@ -3,6 +3,7 @@ import { kernelToolError } from "./kernel-tools-errors.js";
 import { createKernelToolPump } from "./kernel-tools-pump.js";
 import { hostDeniedError, hostToolRefusal } from "./kernel-tools-scope.js";
 import { JsWorkerRuntime } from "./worker-runtime.js";
+import { installKernelWebView } from "./worker-webview.js";
 
 // Mirrors INTERRUPT_ACK_OP and CHILD_LIFECYCLE_OP in src/bridge/reserved.ts (this worker file cannot import TypeScript).
 const INTERRUPT_ACK_OP = "interrupt-ack";
@@ -25,6 +26,7 @@ export function createWorkerCore(transport, options) {
 	let runtime = null;
 	let activeCell = null;
 	const pendingTools = new Map();
+	const pendingWebViewPorts = new Map();
 	const nestedInvokes = new Map();
 	const kernelTools = createKernelToolPump({
 		getRuntime: () => runtime,
@@ -73,6 +75,13 @@ export function createWorkerCore(transport, options) {
 		return await promise;
 	}
 
+	function requestWebViewPort() {
+		const requestId = crypto.randomUUID();
+		const promise = new Promise((resolve, reject) => pendingWebViewPorts.set(requestId, { resolve, reject }));
+		emit({ type: "webview-connect", requestId });
+		return promise;
+	}
+
 	function interruptCell(reason) {
 		if (!activeCell || !runtime) return;
 		emit({ type: "status", event: { op: INTERRUPT_ACK_OP, cellId: activeCell.cellId } });
@@ -92,8 +101,16 @@ export function createWorkerCore(transport, options) {
 			runtime?.kernelTools.setCollisionNames(message.hostToolNames ?? [], message.foreignLanguageNames ?? []);
 			return;
 		}
+		if (message.type === "webview-port") {
+			const pending = pendingWebViewPorts.get(message.requestId);
+			pendingWebViewPorts.delete(message.requestId);
+			if (message.ok) pending?.resolve(message.port);
+			else pending?.reject(errorFromBridge(message.error));
+			return;
+		}
 		if (message.type === "init") {
 			applySessionEnvironment(message.sessionEnv);
+			installKernelWebView(requestWebViewPort);
 			runtime = new JsWorkerRuntime({
 				cwd: options.cwd,
 				parallelPoolWidth: options.parallelPoolWidth,

package/src/kernels/js/worker-host.ts

@@ -88,7 +88,8 @@ export function bridgeError(error: Error): {
 function wrapNodeWorker(worker: Worker, mode: JavaScriptKernelMode): WorkerLike {
 	return {
 		mode,
-		postMessage: (message) => worker.postMessage(message),
+		postMessage: (message, transfer) =>
+			worker.postMessage(message, transfer === undefined ? undefined : [...transfer]),
 		onMessage(handler) {
 			const listener = (message: KernelToHostMessage): void => handler(message);
 			worker.on("message", listener);

package/src/kernels/js/worker-runtime.js

@@ -6,6 +6,7 @@ import { encodeDisplayImage, resolveDisplayOps } from "./display-image.js";
 import { terminateProcessTrees } from "./process-tree.js";
 import { awaitMaybePromise, indirectEval, wrapUserCode } from "./worker-indirect-eval.js";
 import { installShellCapture } from "./worker-shell-capture.js";
+import { bindKernelBun } from "./worker-webview.js";
 import { createWorkpool } from "./workpool.js";
 import { inKernelToolInvoke } from "./kernel-tools-context.js";
 import { kernelToolError } from "./kernel-tools-errors.js";
@@ -57,7 +58,7 @@ export class JsWorkerRuntime {
 				({ prelude, code: cellCode } = prepared);
 			}
 			if (prelude) indirectEval(prelude, `${cellId}:prelude`);
-			const value = await awaitMaybePromise(indirectEval(wrapUserCode(cellCode), cellId));
+			const value = await awaitMaybePromise(indirectEval(bindKernelBun(wrapUserCode(cellCode)), cellId));
 			await this.#drainPendingDisplays();
 			return value;
 		} finally {

package/src/kernels/js/worker-slot.ts

@@ -1,8 +1,10 @@
+import type { MessagePort } from "node:worker_threads";
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { WorkerLike } from "./inline-worker.ts";
 import { retireWorker, type WorkerRetirement } from "./interrupt-bounds.ts";
 import type { JavaScriptKernelMode } from "./kernel-contract.ts";
 import type { JavaScriptKernelOptions } from "./local-module-loader.ts";
+import { KernelWebViewClients } from "./webview-host.ts";
 import { WorkerStartupCancelledError } from "./worker-host.ts";
 import { startWorkerWithInlineFallback } from "./worker-startup.ts";
 
@@ -17,6 +19,7 @@ export class WorkerSlot {
 	readonly #options: JavaScriptKernelOptions;
 	readonly #listeners: WorkerSlotListeners;
 	#worker: WorkerLike | null = null;
+	#webViews: KernelWebViewClients | null = null;
 	#mode: JavaScriptKernelMode = "worker";
 	#generation = 0;
 	#ready: Promise<void> | null = null;
@@ -43,8 +46,8 @@ export class WorkerSlot {
 		return this.#generation;
 	}
 
-	postMessage(message: HostToKernelMessage): void {
-		this.#worker?.postMessage(message);
+	postMessage(message: HostToKernelMessage, transfer?: readonly MessagePort[]): void {
+		this.#worker?.postMessage(message, transfer);
 	}
 
 	async ensureReady(): Promise<void> {
@@ -89,16 +92,22 @@ export class WorkerSlot {
 		this.#startupAbort = null;
 		this.#ready = null;
 		const worker = this.#worker;
+		const webViews = this.#webViews;
 		this.#worker = null;
-		if (!worker) return "terminated";
-		return await retireWorker(worker);
+		this.#webViews = null;
+		const retirement = worker ? await retireWorker(worker) : "terminated";
+		await webViews?.release();
+		return retirement;
 	}
 
 	#publish(worker: WorkerLike, generation: number): void {
 		if (!this.#listeners.isOpen() || generation !== this.#generation) throw new WorkerStartupCancelledError();
 		this.#worker = worker;
+		const webViews = new KernelWebViewClients((message, transfer) => worker.postMessage(message, transfer));
+		this.#webViews = webViews;
 		worker.onMessage((message) => {
-			if (this.#isCurrent(worker, generation)) this.#listeners.onMessage(message);
+			if (!this.#isCurrent(worker, generation) || webViews.consume(message)) return;
+			this.#listeners.onMessage(message);
 		});
 		worker.onError((error) => {
 			if (this.#isCurrent(worker, generation)) this.#listeners.onCrash(error);

package/src/kernels/js/worker-webview-client.js

@@ -0,0 +1,79 @@
+// The kernel worker's end of its private port to the main-thread Bun.WebView service. Mirrors
+// the message shapes in packages/coding-agent/src/core/webview/webview-wire.ts (this worker file
+// cannot import TypeScript); keep the two in sync.
+
+export const DELIVER_EVENT = Symbol("senpi.webview.deliver");
+
+export function webViewError(wire) {
+	const error = new Error(wire?.message ?? "Bun.WebView request failed");
+	if (typeof wire?.name === "string") error.name = wire.name;
+	if (typeof wire?.code === "string") error.code = wire.code;
+	return error;
+}
+
+export class WebViewPortClient {
+	#port;
+	#pending = new Map();
+	#views = new Map();
+	#nextId = 1;
+	#closed = false;
+	#onClosed;
+
+	constructor(port, onClosed) {
+		this.#port = port;
+		this.#onClosed = onClosed;
+		port.on("message", message => this.#receive(message));
+		port.on("close", () => this.#fail(new Error("Bun.WebView service connection closed")));
+	}
+
+	register(viewId, view) {
+		this.#views.set(viewId, new WeakRef(view));
+	}
+
+	forget(viewId) {
+		this.#views.delete(viewId);
+	}
+
+	request(message) {
+		if (this.#closed) return Promise.reject(new Error("Bun.WebView service connection closed"));
+		const id = this.#nextId++;
+		return new Promise((resolve, reject) => {
+			this.#pending.set(id, { resolve, reject });
+			try {
+				this.#port.postMessage({ ...message, id });
+			} catch (error) {
+				this.#pending.delete(id);
+				reject(error);
+			}
+		});
+	}
+
+	post(message) {
+		if (this.#closed) return;
+		try {
+			this.#port.postMessage(message);
+		} catch {
+			// A closed port has already released every view on the service side.
+		}
+	}
+
+	#receive(message) {
+		if (message?.kind === "reply") {
+			const pending = this.#pending.get(message.id);
+			if (!pending) return;
+			this.#pending.delete(message.id);
+			if (message.ok) pending.resolve({ value: message.value, state: message.state });
+			else pending.reject(webViewError(message.error));
+			return;
+		}
+		if (message?.kind === "event") this.#views.get(message.viewId)?.deref()?.[DELIVER_EVENT](message.event);
+	}
+
+	#fail(error) {
+		if (this.#closed) return;
+		this.#closed = true;
+		for (const pending of this.#pending.values()) pending.reject(error);
+		this.#pending.clear();
+		this.#onClosed();
+	}
+}

package/src/kernels/js/worker-webview.js

@@ -0,0 +1,204 @@
+import { DELIVER_EVENT, WebViewPortClient, webViewError } from "./worker-webview-client.js";
+
+// Bun constructs "chrome"-backend WebViews only on the process main thread, and this kernel runs in
+// a worker where `globalThis.Bun` and `Bun.WebView` are non-writable. Cells therefore run with a
+// `Bun` parameter bound to a stand-in whose `WebView` forwards Chrome-backed views to the
+// main-thread service over a private port; every other `Bun.*` member is the real one.
+const KERNEL_BUN = Symbol.for("senpi.kernel.bun");
+
+export function bindKernelBun(source) {
+	if (!globalThis[KERNEL_BUN]) return source;
+	return `((Bun) => ${source})(globalThis[Symbol.for("senpi.kernel.bun")])`;
+}
+
+export function installKernelWebView(requestPort) {
+	const bun = globalThis.Bun;
+	if (typeof bun !== "object" || bun === null || typeof bun.WebView !== "function") return;
+	globalThis[KERNEL_BUN] = shadowBun(bun, createKernelWebView(bun.WebView, requestPort));
+}
+
+function shadowBun(real, WebView) {
+	return new Proxy(
+		{},
+		{
+			get: (_target, key) => (key === "WebView" ? WebView : Reflect.get(real, key)),
+			set: (_target, key, value) => Reflect.set(real, key, value),
+			has: (_target, key) => key === "WebView" || Reflect.has(real, key),
+			ownKeys: () => Reflect.ownKeys(real),
+			getOwnPropertyDescriptor: (_target, key) => {
+				if (key === "WebView") return { value: WebView, writable: false, enumerable: true, configurable: true };
+				const descriptor = Reflect.getOwnPropertyDescriptor(real, key);
+				return descriptor && { ...descriptor, configurable: true };
+			},
+		},
+	);
+}
+
+// The macOS default (WebKit) stays a native worker view: its host process serves any thread.
+function needsMainThread(options) {
+	const backend = options?.backend;
+	if (backend === undefined) return process.platform !== "darwin";
+	return backend === "chrome" || (typeof backend === "object" && backend !== null && backend.type === "chrome");
+}
+
+function closedError(method) {
+	const error = new Error(`Invalid state: WebView.${method}: view is closed`);
+	error.code = "ERR_INVALID_STATE";
+	return error;
+}
+
+function createKernelWebView(NativeWebView, requestPort) {
+	let connecting = null;
+	const proxied = new WeakSet();
+	const live = new Set();
+	const natives = new Set();
+	const finalizer = new FinalizationRegistry(({ client, viewId }) => client.post({ kind: "close", viewId }));
+
+	function connect() {
+		if (!connecting) {
+			const attempt = requestPort().then(port => new WebViewPortClient(port, () => (connecting = null)));
+			attempt.catch(() => {
+				if (connecting === attempt) connecting = null;
+			});
+			connecting = attempt;
+		}
+		return connecting;
+	}
+
+	class WebView extends EventTarget {
+		static closeAll() {
+			for (const view of [...live]) view.close();
+			for (const ref of [...natives]) ref.deref()?.close();
+			natives.clear();
+		}
+
+		static [Symbol.hasInstance](value) {
+			return value instanceof NativeWebView || proxied.has(value);
+		}
+
+		#viewId = crypto.randomUUID();
+		#state = { url: "", title: "", loading: false };
+		#listening = new Set();
+		#console;
+		#ready;
+		#closed = false;
+		onNavigated = null;
+		onNavigationFailed = null;
+
+		constructor(options = {}) {
+			if (!needsMainThread(options)) {
+				const view = new NativeWebView(options);
+				natives.add(new WeakRef(view));
+				return view;
+			}
+			super();
+			const { console: capture, ...rest } = options;
+			this.#console = capture;
+			proxied.add(this);
+			live.add(this);
+			const viewId = this.#viewId;
+			this.#ready = connect().then(async client => {
+				client.register(viewId, this);
+				finalizer.register(this, { client, viewId }, this);
+				const reply = await client.request({ kind: "create", viewId, options: rest, captureConsole: capture !== undefined });
+				this.#apply(reply.state);
+				return client;
+			});
+			this.#ready.catch(() => {});
+		}
+
+		get url() {
+			return this.#state.url;
+		}
+
+		get title() {
+			return this.#state.title;
+		}
+
+		get loading() {
+			return this.#state.loading;
+		}
+
+		navigate(url) { return this.#call("navigate", [url]); }
+		evaluate(script) { return this.#call("evaluate", [script]); }
+		click(...args) { return this.#call("click", args); }
+		type(text) { return this.#call("type", [text]); }
+		press(...args) { return this.#call("press", args); }
+		scroll(dx, dy) { return this.#call("scroll", [dx, dy]); }
+		scrollTo(...args) { return this.#call("scrollTo", args); }
+		resize(width, height) { return this.#call("resize", [width, height]); }
+		back() { return this.#call("back", []); }
+		forward() { return this.#call("forward", []); }
+		reload() { return this.#call("reload", []); }
+		cdp(...args) { return this.#call("cdp", args); }
+
+		async screenshot(options) {
+			const value = await this.#call("screenshot", [options]);
+			if (options?.encoding === "buffer" && value instanceof Uint8Array) return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+			return value;
+		}
+
+		addEventListener(type, listener, options) {
+			super.addEventListener(type, listener, options);
+			if (this.#closed || this.#listening.has(type)) return;
+			this.#listening.add(type);
+			const viewId = this.#viewId;
+			this.#ready.then(client => client.post({ kind: "listen", viewId, event: type }), () => {});
+		}
+
+		close() {
+			if (this.#closed) return;
+			this.#closed = true;
+			live.delete(this);
+			const viewId = this.#viewId;
+			this.#ready.then(
+				client => {
+					client.post({ kind: "close", viewId });
+					client.forget(viewId);
+					finalizer.unregister(this);
+				},
+				() => {},
+			);
+		}
+
+		[Symbol.dispose]() {
+			this.close();
+		}
+
+		[Symbol.asyncDispose]() {
+			this.close();
+		}
+
+		[DELIVER_EVENT](event) {
+			if (event.type === "console") {
+				const [type, ...args] = event.args;
+				if (typeof this.#console === "function") this.#console(type, ...args);
+				else this.#console?.[type]?.(...args);
+			} else if (event.type === "navigated") {
+				this.#state = { ...this.#state, url: event.url, title: event.title };
+				this.onNavigated?.(event.url, event.title);
+			} else if (event.type === "navigation-failed") {
+				this.onNavigationFailed?.(webViewError(event.error));
+			} else if (event.type === "dom") {
+				this.dispatchEvent(new MessageEvent(event.name, { data: event.data }));
+			}
+		}
+
+		async #call(method, args) {
+			if (this.#closed) throw closedError(method);
+			const client = await this.#ready;
+			if (this.#closed) throw closedError(method);
+			const trimmed = [...args];
+			while (trimmed.length > 0 && trimmed.at(-1) === undefined) trimmed.pop();
+			const reply = await client.request({ kind: "call", viewId: this.#viewId, method, args: trimmed });
+			this.#apply(reply.state);
+			return reply.value;
+		}
+
+		#apply(state) {
+			if (state) this.#state = state;
+		}
+	}
+
+	return WebView;
+}

package/src/kernels/py/kernel.ts

@@ -1,6 +1,7 @@
 import type { KernelInterruptHandle } from "../../tool/types.ts";
 import type { KernelToolsInvokeOptions } from "../js/kernel-tools-types.ts";
 import { rejectKernelToolsUnavailable } from "../kernel-tools-unavailable.ts";
+import { KernelPreludeTracker } from "../shared/kernel-prelude-plan.ts";
 import type { PendingRun, PythonKernelRunOptions, PythonKernelStartOptions, ResultMessage } from "./kernel-contract.ts";
 import { failedPythonResult, PythonKernelTransport } from "./transport.ts";
 
@@ -20,6 +21,7 @@ export class PythonKernel {
 	#retirement: Promise<void> | null = null;
 	#closePromise: Promise<void> | null = null;
 	#failure: Error | null = null;
+	readonly #preludes = new KernelPreludeTracker();
 	#generation = 0;
 	#closed = false;
 
@@ -180,7 +182,10 @@ export class PythonKernel {
 		if (timeoutMs !== undefined)
 			pending.timeoutTimer = setTimeout(() => this.#timeoutRun(pending, timeoutMs), timeoutMs);
 		try {
-			this.#transport?.run(pending.input);
+			this.#transport?.run({
+				...pending.input,
+				preludePlan: this.#preludes.plan(pending.input.kernelPreludes ?? []),
+			});
 		} catch (error) {
 			const failure = error instanceof Error ? error : new Error(String(error));
 			this.#rejectRun(pending, failure);

package/src/kernels/py/prelude.py

@@ -1020,7 +1020,19 @@ async def run_code(code: Any, want_value: bool) -> Any:
     return None
 
 
-def run_cell(cell_id: str, code: str) -> None:
+def apply_preludes(preludes: Any) -> None:
+    # Host-computed per cell: globals of tools deactivated since the last cell are dropped,
+    # and an active tool's snippet runs only while one of its exports is missing.
+    if not isinstance(preludes, dict):
+        return
+    for name in preludes.get("remove", []):
+        USER_NS.pop(name, None)
+    for contribution in preludes.get("install", []):
+        if any(name not in USER_NS for name in contribution.get("exports", [])):
+            exec(compile(contribution.get("python", ""), "<kernel-prelude>", "exec"), USER_NS)
+
+
+def run_cell(cell_id: str, code: str, preludes: Any = None) -> None:
     start = time.monotonic()
     stdout = io.StringIO()
     stderr = io.StringIO()
@@ -1029,6 +1041,7 @@ def run_cell(cell_id: str, code: str) -> None:
     signal.signal(signal.SIGINT, signal.default_int_handler)
     try:
         with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+            apply_preludes(preludes)
             body, expression = compile_cell(code)
             LOOP.run_until_complete(run_code(body, False))
             value = LOOP.run_until_complete(run_code(expression, True))
@@ -1075,7 +1088,7 @@ def handle(message: dict[str, Any]) -> bool:
         emit({"type": "ready"})
         return True
     if message_type == "run":
-        run_cell(str(message.get("cellId", "")), str(message.get("code", "")))
+        run_cell(str(message.get("cellId", "")), str(message.get("code", "")), message.get("preludes"))
         return True
     if message_type == "close":
         emit({"type": "closed"})

package/src/kernels/py/transport.ts

@@ -9,6 +9,7 @@ import {
 	type KernelToHostMessage,
 } from "../../bridge/protocol.ts";
 import { applySessionEnvironment, type SessionEnvironment } from "../session-env.ts";
+import type { KernelPreludePlan } from "../shared/kernel-prelude-plan.ts";
 import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import {
 	defaultSpawn,
@@ -30,6 +31,7 @@ export interface PythonTransportRunInput {
 	readonly cellId: string;
 	readonly code: string;
 	readonly timeoutMs?: number;
+	readonly preludePlan?: KernelPreludePlan;
 }
 
 export interface PythonTransportOptions {
@@ -115,7 +117,11 @@ export class PythonKernelTransport {
 	}
 
 	run(input: PythonTransportRunInput): void {
-		this.#write({ type: "run", cellId: input.cellId, code: input.code, timeoutMs: input.timeoutMs });
+		const preludes = input.preludePlan && {
+			install: input.preludePlan.install.map(({ exports, python }) => ({ exports: [...exports], python })),
+			remove: [...input.preludePlan.remove],
+		};
+		this.#write({ type: "run", cellId: input.cellId, code: input.code, timeoutMs: input.timeoutMs, preludes });
 	}
 
 	interrupt(reason: string): void {

package/src/kernels/shared/kernel-prelude-plan.ts

@@ -0,0 +1,19 @@
+import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
+
+/** What a kernel applies before a cell: contributions to (re)install and exports whose tool is no longer active. */
+export interface KernelPreludePlan {
+	readonly install: readonly KernelPreludeContribution[];
+	readonly remove: readonly string[];
+}
+
+/** Remembers the exports one kernel was last told to hold, so a deactivated tool's globals are removed. */
+export class KernelPreludeTracker {
+	#installed: ReadonlySet<string> = new Set();
+
+	plan(contributions: readonly KernelPreludeContribution[]): KernelPreludePlan {
+		const active = new Set(contributions.flatMap((contribution) => contribution.exports));
+		const remove = [...this.#installed].filter((name) => !active.has(name));
+		this.#installed = active;
+		return { install: contributions, remove };
+	}
+}

package/src/kernels/shared/subprocess-queue.ts

@@ -113,6 +113,8 @@ export class SubprocessRunQueue {
 			case "kernel-tool-invoke-reply":
 				onMessage?.(message);
 				return false;
+			case "webview-connect":
+				return false;
 			default: {
 				const exhaustive: never = message;
 				return exhaustive;

package/src/prompt/eval-prompt-template.ts

@@ -69,7 +69,8 @@ log(message) → None
     Progress line above the status tree.
 phase(title) → None
     Phase grouping subsequent status lines.
-\`\`\`
+{{#if kernelPreludeDocs}}{{kernelPreludeDocs}}
+{{/if}}\`\`\`
 </prelude>
 {{#if spawns}}
 <workflow>

package/src/prompt/eval-prompt.ts

@@ -1,3 +1,4 @@
+import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
 import { DEFAULT_MAX_DETACHED_CELLS, DEFAULT_RUN_BUDGET_SECONDS } from "../config/settings.ts";
 import type { EvalRuntimeInfo } from "../tool/types.ts";
 import { EVAL_PROMPT_TEMPLATE } from "./eval-prompt-template.ts";
@@ -32,6 +33,8 @@ export interface EvalPromptOptions {
 	readonly runBudgetSeconds?: number;
 	/** Global background capacity advertised to the model. */
 	readonly maxDetachedCells?: number;
+	/** Active tools' kernel globals; each documentation line joins the prelude helper list. */
+	readonly kernelPreludes?: readonly KernelPreludeContribution[];
 }
 
 /** Prompt dialect for the eval-first batching emphasis. */
@@ -99,6 +102,7 @@ export function buildEvalPrompt(
 		bunSkillPath: options.bunSkillPath ?? "",
 		runBudgetSeconds: String(options.runBudgetSeconds ?? DEFAULT_RUN_BUDGET_SECONDS),
 		maxDetachedCells: String(options.maxDetachedCells ?? DEFAULT_MAX_DETACHED_CELLS),
+		kernelPreludeDocs: (options.kernelPreludes ?? []).map((prelude) => prelude.documentation).join("\n"),
 	};
 	const description = renderTemplate(EVAL_PROMPT_TEMPLATE, context)
 		.replace(/\n{3,}/g, "\n\n")

package/src/skill/bun-1-4/references/runtime-apis.md

@@ -34,6 +34,7 @@ await Bun.write("page.png", await view.screenshot());
 ```
 
 - macOS: system WebKit, nothing to install. macOS/Linux/Windows: can drive installed Chrome/Chromium/Edge.
+- In the eval js kernel, Chrome-backed views (the default off macOS, or `backend: "chrome"`) are served by the process main thread; the API is the same, a constructor error surfaces on the first awaited call, and `Bun.WebView.closeAll()` closes only this kernel's views. A kernel reset closes every view the kernel left open.
 - Clicks/scrolls are trusted user input (`event.isTrusted === true`).
 - Extends `EventTarget`; screenshots are `Blob`s; `.cdp(method, params?)` escape hatch for raw Chrome DevTools Protocol.
 

package/src/tool/eval-tool-options.ts

@@ -1,4 +1,10 @@
-import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext, ToolDefinition } from "@code-yeongyu/senpi";
+import type {
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	ExtensionContext,
+	KernelPreludeContribution,
+	ToolDefinition,
+} from "@code-yeongyu/senpi";
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import type { ResolvedCodemodeSettings } from "../config/settings.ts";
@@ -58,6 +64,10 @@ export interface CreateEvalToolOptions {
 	readonly runtimes?: EvalRuntimes;
 	/** Absolute path of the active bun-1-4 skill; the prompt names it as MUST READ on a bun kernel. */
 	readonly bunSkillPath?: string;
+	/** Kernel globals of the tools active when a cell is submitted; read once per cell. */
+	readonly kernelPreludes?: () => readonly KernelPreludeContribution[];
+	/** Contributions whose documentation lines the description lists; snapshot taken when the tool is (re)registered. */
+	readonly promptKernelPreludes?: readonly KernelPreludeContribution[];
 }
 
 export interface EvalCellInvocation {

package/src/tool/eval-tool.ts

@@ -54,6 +54,7 @@ export function createEvalTool(options: CreateEvalToolOptions) {
 		...(options.hostLine === undefined ? {} : { hostLine: options.hostLine }),
 		...(options.runtimes?.js === undefined ? {} : { jsRuntime: options.runtimes.js }),
 		...(options.bunSkillPath === undefined ? {} : { bunSkillPath: options.bunSkillPath }),
+		...(options.promptKernelPreludes === undefined ? {} : { kernelPreludes: options.promptKernelPreludes }),
 	});
 	const languages = enabledLanguageList(options.enabledLanguages);
 	const cellManager =

package/src/tool/run-eval-cell.ts

@@ -251,6 +251,7 @@ async function executeCell(
 				kernel.run({
 					cellId: invocation.cellId,
 					code: invocation.input.code,
+					kernelPreludes: options.kernelPreludes?.(),
 					onMessage,
 					onStarted: () => {
 						cellManager.markRunning(cell);

package/src/tool/types.ts

@@ -1,4 +1,4 @@
-import type { AgentToolResult, AgentToolUpdateCallback } from "@code-yeongyu/senpi";
+import type { AgentToolResult, AgentToolUpdateCallback, KernelPreludeContribution } from "@code-yeongyu/senpi";
 import { type TSchema, type TUnsafe, Type } from "typebox";
 import type { HostToKernelMessage, KernelToHostMessage } from "../bridge/protocol.ts";
 import {
@@ -141,6 +141,8 @@ export interface EvalKernelRunInput {
 	readonly timeoutMs?: number;
 	readonly onStarted?: () => void;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
+	/** Globals of the tools active when the cell was submitted; kernels without preludes ignore them. */
+	readonly kernelPreludes?: readonly KernelPreludeContribution[];
 }
 
 export interface KernelInterruptHandle {