@code-yeongyu/senpi-codemode 2026.10.10 → 2026.10.12

package/src/extension/runtime-factory.ts

@@ -2,6 +2,8 @@ import { type ExtensionContext, withBundledBunCommands } from "@code-yeongyu/sen
 import type { AgentExecuteTool } from "../bridges/agent-bridge.ts";
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
+import { resolveJsIsolation } from "../config/feature-settings.ts";
+import { withoutUntrustedInterpreter } from "../config/project-trust.ts";
 import {
 	type CodemodeSettings,
 	loadCodemodeSettings,
@@ -16,6 +18,7 @@ import {
 	getInterpreterAvailability,
 	type InterpreterAvailability,
 } from "../interpreters/detect.ts";
+import { processRuntimeInfo } from "../kernels/js/process-worker.ts";
 import { sessionEnvironmentFrom } from "../kernels/session-env.ts";
 import { resolveSessionArtifactsDir } from "../output/streaming-output.ts";
 import type { EnabledEvalLanguages, EvalLanguage, EvalRuntimes } from "../tool/types.ts";
@@ -62,12 +65,25 @@ export async function createRuntime(
 	handles?: HandleRegistry,
 ): Promise<SessionRuntime> {
 	const loaded = await loadCodemodeSettings({ cwd: ctx.cwd });
+	const trusted = withoutUntrustedInterpreter(
+		loaded.settings,
+		loaded.source,
+		ctx.cwd,
+		typeof ctx.isProjectTrusted === "function" ? () => ctx.isProjectTrusted() : undefined,
+	);
 	const settings: ResolvedCodemodeSettings = {
-		...loaded.settings,
-		languages: resolveEnabledLanguages(loaded.settings),
+		...trusted.settings,
+		languages: resolveEnabledLanguages(trusted.settings),
 	};
 	const availability = await getInterpreterAvailability(settings, createInterpreterDetector());
+	const pyReason = availability.py.detected.ok ? undefined : availability.py.detected.reason;
+	reportSettingsProblems(ctx, [
+		...loaded.warnings,
+		...(trusted.warning === undefined ? [] : [trusted.warning]),
+		...(pyReason === undefined ? [] : [pyReason]),
+	]);
 	const enabledLanguages = enabledLanguagesFrom(settings, availability);
+	const jsProcessIsolation = resolveJsIsolation(settings) === "process";
 	const artifacts = resolveSessionArtifactsDir(ctx.sessionManager.getSessionFile());
 	const activeTools = new Set(pi.getActiveTools());
 	const executeTool = createExecuteTool(pi, activeTools);
@@ -76,6 +92,15 @@ export async function createRuntime(
 	const sessionEnv = { ...sessionEnvironmentFrom(ctx), ...bundledBunPathEntry() };
 	const configuredPoolWidth = settings.parallelPoolWidth;
 	const parallelPoolWidth = Number.isFinite(configuredPoolWidth) ? Math.max(1, Math.trunc(configuredPoolWidth)) : 1;
+	const pythonEnvironments =
+		availability.py.detected.ok && enabledLanguages.py
+			? new PythonEnvironments({
+					artifactsDir: artifacts.dir,
+					cwd: ctx.cwd,
+					interpreter: availability.py.detected.path,
+					settings,
+				})
+			: undefined;
 	const manager = await create({
 		sessionId,
 		ownerSessionId: ctx.sessionManager.getSessionId(),
@@ -88,6 +113,7 @@ export async function createRuntime(
 		listTools: () => pi.getAllTools(),
 		complete,
 		...(handles === undefined ? {} : { handles }),
+		...(pythonEnvironments === undefined ? {} : { environments: { python: pythonEnvironments } }),
 	});
 	return {
 		sessionId,
@@ -95,7 +121,11 @@ export async function createRuntime(
 		parallelPoolWidth,
 		manager,
 		enabledLanguages,
-		runtimes: runtimesFromAvailability(availability, jsRuntimeInfo()),
+		runtimes: runtimesFromAvailability(
+			availability,
+			(jsProcessIsolation ? processRuntimeInfo(undefined) : undefined) ??
+				jsRuntimeInfo(process.versions, process.execPath, jsProcessIsolation),
+		),
 		settings,
 		artifactsDir: artifacts.dir,
 		executeTool,
@@ -107,19 +137,18 @@ export async function createRuntime(
 			env: { ...process.env, ...sessionEnv },
 			settings,
 		}),
-		...(availability.py.detected.ok && enabledLanguages.py
-			? {
-					pythonEnvironments: new PythonEnvironments({
-						artifactsDir: artifacts.dir,
-						cwd: ctx.cwd,
-						interpreter: availability.py.detected.path,
-						settings,
-					}),
-				}
-			: {}),
+		...(pythonEnvironments === undefined ? {} : { pythonEnvironments }),
 	};
 }
 
+/** Settings problems reach the user: a notice with a UI, otherwise stderr (print and RPC runs). */
+function reportSettingsProblems(ctx: ExtensionContext, problems: readonly string[]): void {
+	for (const problem of problems) {
+		if (ctx.hasUI) ctx.ui.notify(`[senpi-codemode] ${problem}`, "warning");
+		else console.error(`[senpi-codemode] ${problem}`);
+	}
+}
+
 export function createExecuteTool(pi: CodemodeRuntimeAPI, activeTools?: ReadonlySet<string>): AgentExecuteTool {
 	// A cell names tools directly and cannot run tool_search first, so eval opts in to
 	// lazy activation. Eligibility still belongs to the extension that registered the tool.

package/src/extension/runtime-info.ts

@@ -10,10 +10,14 @@ export interface JsRuntimeVersions {
 export function jsRuntimeInfo(
 	versions: JsRuntimeVersions = process.versions,
 	execPath: string = process.execPath,
+	processIsolation = false,
 ): EvalRuntimeInfo {
 	const bun = versions.bun;
-	if (bun !== undefined && bun.length > 0) return { name: "bun", version: bun, path: execPath };
-	return { name: "node", version: versions.node, path: execPath };
+	const base =
+		bun !== undefined && bun.length > 0
+			? { name: "bun", version: bun, path: execPath }
+			: { name: "node", version: versions.node, path: execPath };
+	return processIsolation ? { ...base, isolation: "process" } : base;
 }
 
 /** Short host-line segment, e.g. "node 26.7.0" or "bun 1.4.0". */

package/src/extension/session-cwd.ts

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 import { stat } from "node:fs/promises";
 
 // Only these codes mean the directory is gone or was never one; anything else (EACCES, ELOOP,
@@ -21,15 +22,30 @@ export async function assertSessionCwdAvailable(cwd: string): Promise<void> {
 	try {
 		isDirectory = (await stat(cwd)).isDirectory();
 	} catch (error) {
-		if (
-			error instanceof Error &&
-			"code" in error &&
-			typeof error.code === "string" &&
-			MISSING_DIRECTORY_CODES.has(error.code)
-		) {
-			throw new CodemodeSessionCwdUnavailableError(cwd, error.code);
-		}
-		throw error;
+		throw sessionCwdStatError(cwd, error);
 	}
 	if (!isDirectory) throw new CodemodeSessionCwdUnavailableError(cwd, "not a directory");
 }
+
+/** Warm reuse checks every cell without a filesystem thread-pool round trip. */
+export function assertSessionCwdAvailableSync(cwd: string): void {
+	let isDirectory: boolean;
+	try {
+		isDirectory = statSync(cwd).isDirectory();
+	} catch (error) {
+		throw sessionCwdStatError(cwd, error);
+	}
+	if (!isDirectory) throw new CodemodeSessionCwdUnavailableError(cwd, "not a directory");
+}
+
+function sessionCwdStatError(cwd: string, error: unknown): unknown {
+	if (
+		error instanceof Error &&
+		"code" in error &&
+		typeof error.code === "string" &&
+		MISSING_DIRECTORY_CODES.has(error.code)
+	) {
+		return new CodemodeSessionCwdUnavailableError(cwd, error.code);
+	}
+	return error;
+}

package/src/extension/session-manager-contract.ts

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import type { CodemodeSettings } from "../config/settings.ts";
+import type { PackagesInstallEnvironments } from "../environments/packages-install.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { InterpreterAvailability } from "../interpreters/detect.ts";
 import type { SessionEnvironment } from "../kernels/session-env.ts";
@@ -42,4 +43,6 @@ export interface CreateCodemodeSessionManagerOptions {
 	readonly complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
 	/** The session generation's handle registry; subprocess kernels reach `wait()`/`handle()` through the bridge. */
 	readonly handles?: HandleRegistry;
+	/** The Python environment `packages.install("pip", ...)` reaches from a Python cell over the bridge. */
+	readonly environments?: PackagesInstallEnvironments;
 }

package/src/extension/session-manager.ts

@@ -1,12 +1,15 @@
 import { join } from "node:path";
 import type { ExtensionContext } from "@code-yeongyu/senpi";
+import { readProcessFootprint } from "@code-yeongyu/senpi";
 import { type BridgeServerHandle, startBridgeServer } from "../bridge/http-server.ts";
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
+import { resolveJsIsolation, resolveKernelToolsEnabled } from "../config/feature-settings.ts";
 import { resolveKernelMemoryThresholds } from "../config/memory-settings.ts";
 import { collectOrphanedChildren } from "../host-sdk.ts";
 import { JavaScriptKernel } from "../kernels/js/context-manager.ts";
 import type { KernelToolsCapability, KernelToolsDescribeResult } from "../kernels/js/kernel-tools-types.ts";
+import type { SessionEnvironment } from "../kernels/session-env.ts";
 import type { KernelLifecycle } from "../kernels/shared/kernel-death.ts";
 import type { EvalKernel, EvalLanguage } from "../tool/types.ts";
 import { type BridgeDispatchContext, dispatchBridgeCompletion } from "./bridge-dispatch.ts";
@@ -21,7 +24,7 @@ import {
 } from "./kernel-registration.ts";
 import type { RegisteredKernelSource } from "./kernel-registry.ts";
 import { ReplaceableKernel } from "./kernel-replacement.ts";
-import { assertSessionCwdAvailable } from "./session-cwd.ts";
+import { assertSessionCwdAvailable, assertSessionCwdAvailableSync } from "./session-cwd.ts";
 import type {
 	BridgeEndpoint,
 	CodemodeSessionManager,
@@ -111,7 +114,7 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 		this.#onMessageRefs.set(language, onMessage);
 		const existing = this.#kernels.get(language);
 		if (existing) {
-			await assertSessionCwdAvailable(this.#options.cwd);
+			assertSessionCwdAvailableSync(this.#options.cwd);
 			return existing;
 		}
 		const pending = this.#kernelCreations.get(language);
@@ -252,6 +255,8 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 			this.#options.localRoots ??
 			(this.#options.artifactsDir ? { local: join(this.#options.artifactsDir, "local") } : undefined);
 		if (language === "js") {
+			const memoryThresholds = resolveKernelMemoryThresholds(this.#options.settings.memory);
+			const processIsolation = resolveJsIsolation(this.#options.settings) === "process";
 			const kernel = new JavaScriptKernel({
 				sessionId: this.#options.sessionId,
 				cwd: this.#options.cwd,
@@ -259,8 +264,13 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 				onMessage,
 				hostToolNames: () => this.#options.listTools?.().map((tool) => tool.name) ?? [],
 				foreignLanguageNames: () => this.#foreignKernelToolNames(),
-				memory: resolveKernelMemoryThresholds(this.#options.settings.memory),
+				memory: memoryThresholds,
 				collectOrphanedChildren,
+				...(processIsolation ? { isolation: "process" as const } : {}),
+				...(processIsolation && memoryThresholds !== undefined
+					? { processMemory: { thresholds: memoryThresholds, readFootprint: readProcessFootprint } }
+					: {}),
+				...(resolveKernelToolsEnabled(this.#options.settings) ? {} : { kernelToolsEnabled: false }),
 				...(this.#options.sessionEnv ? { sessionEnv: this.#options.sessionEnv } : {}),
 				...(localRoots ? { localRoots: { ...localRoots } } : {}),
 				...(this.#options.artifactsDir ? { artifactsDir: this.#options.artifactsDir } : {}),
@@ -276,10 +286,14 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 			...(localRoots ? { localRoots: { ...localRoots } } : {}),
 			...(this.#options.artifactsDir ? { artifactsDir: this.#options.artifactsDir } : {}),
 		};
+		// The Python prelude reads this when a cell defines an @tool; only a disabled setting adds it.
+		const sessionEnv: SessionEnvironment | undefined = resolveKernelToolsEnabled(this.#options.settings)
+			? this.#options.sessionEnv
+			: { ...this.#options.sessionEnv, SENPI_CODEMODE_KERNEL_TOOLS: "0" };
 		const shared = {
 			sessionId: this.#options.sessionId,
 			cwd: this.#options.cwd,
-			...(this.#options.sessionEnv ? { sessionEnv: this.#options.sessionEnv } : {}),
+			...(sessionEnv ? { sessionEnv } : {}),
 			connection,
 			onMessage,
 			...lifecycle,
@@ -297,8 +311,8 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 	/** Only an already running JavaScript kernel can define a colliding name; none is started for this. */
 	#javaScriptKernelToolsDescribe(names: readonly string[]): Promise<KernelToolsDescribeResult> | undefined {
 		const js = this.#kernels.get("js");
-		if (!js || !("describeKernelTools" in js) || typeof js.describeKernelTools !== "function") return undefined;
-		return (js.describeKernelTools as (names: readonly string[]) => Promise<KernelToolsDescribeResult>)(names);
+		if (!js || typeof js.describeKernelTools !== "function") return undefined;
+		return js.describeKernelTools(names);
 	}
 
 	#foreignKernelToolNames(): string[] {

package/src/index.ts

@@ -10,7 +10,8 @@ import {
 	resolveMaxDetachedCells,
 	resolveRunBudgetSeconds,
 } from "./config/settings.ts";
-import { EvalNotifier } from "./extension/eval-notifier.ts";
+import { registerEvalCellsRpc } from "./extension/eval-cells-rpc.ts";
+import { type EvalNotificationContent, 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 { hostLine, modelIdFrom } from "./extension/host-facts.ts";
@@ -57,13 +58,16 @@ export interface CodemodeExtensionAPI {
 	getActiveTools(): string[];
 	getAllTools(): readonly EvalSchemaToolInfo[];
 	sendMessage(
-		message: { customType: string; content: string; display: boolean },
+		message: { customType: string; content: EvalNotificationContent; display: boolean },
 		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
 	): void;
 	/** Optional host event bus; a host without one turns extension event emission into a harmless no-op. */
 	events?: { emit(name: string, data: unknown): void };
 	/** Optional host RPC surface for forwarding extension-owned events to connected clients. */
-	rpc?: { emit(name: string, data: unknown): void };
+	rpc?: {
+		emit(name: string, data: unknown): void;
+		handle?(name: string, handler: (data: unknown) => unknown | Promise<unknown>): void;
+	};
 }
 
 export interface SenpiCodemodeOptions {
@@ -94,6 +98,7 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 	let activeContext: ExtensionContext | undefined;
 	let activeCells: EvalDetachedCellManager | undefined;
 	let activeHandles: HandleRegistry | undefined;
+	registerEvalCellsRpc(pi.rpc, () => activeCells);
 	let promptPreludeDocs = "";
 	const notifier = new EvalNotifier({
 		sendMessage: (message, notifyOptions) => pi.sendMessage(message, notifyOptions),

package/src/interpreters/detect.ts

@@ -20,6 +20,8 @@ export interface InterpreterDetected {
 
 export interface InterpreterUnavailable {
 	readonly ok: false;
+	/** Why a configured interpreter could not be used; unset when detection simply found none. */
+	readonly reason?: string;
 }
 
 export type InterpreterDetection = InterpreterDetected | InterpreterUnavailable;
@@ -43,6 +45,8 @@ export interface CreateInterpreterDetectorOptions {
 
 export interface InterpreterDetector {
 	detect(language: CodemodeLanguage): Promise<InterpreterDetection>;
+	/** Probes exactly this executable (no PATH candidates, no splitting on spaces). */
+	detectExplicit(path: string): Promise<InterpreterDetection>;
 }
 
 export interface LanguageAvailability {
@@ -74,6 +78,9 @@ export function createInterpreterDetector(options: CreateInterpreterDetectorOpti
 			cache.set(language, pending);
 			return pending;
 		},
+		detectExplicit(path) {
+			return probeExplicit(path, probe);
+		},
 	};
 }
 
@@ -82,7 +89,7 @@ export async function getInterpreterAvailability(
 	detector: InterpreterDetector,
 ): Promise<InterpreterAvailability> {
 	return {
-		py: await availabilityFor("py", settings.languages.py, detector),
+		py: await pythonAvailability(settings, detector),
 		js: await availabilityFor("js", settings.languages.js, detector),
 		rb: await availabilityFor("rb", settings.languages.rb, detector),
 		jl: await availabilityFor("jl", settings.languages.jl, detector),
@@ -100,6 +107,32 @@ async function availabilityFor(
 	};
 }
 
+/** `languages.pyInterpreter`, when set, is the only interpreter Python uses; a path that does not answer makes Python unavailable. */
+async function pythonAvailability(
+	settings: CodemodeSettings,
+	detector: InterpreterDetector,
+): Promise<LanguageAvailability> {
+	const configured = settings.languages.pyInterpreter;
+	if (configured === undefined || !settings.languages.py)
+		return await availabilityFor("py", settings.languages.py, detector);
+	return { enabled: true, detected: await detector.detectExplicit(configured) };
+}
+
+async function probeExplicit(path: string, probe: ExecFileProbe): Promise<InterpreterDetection> {
+	const reason = (detail: string): InterpreterUnavailable => ({
+		ok: false,
+		reason: `languages.pyInterpreter "${path}" ${detail}; Python is unavailable in this session`,
+	});
+	try {
+		const result = await probe(path, ["--version"], { timeoutMs: probeTimeoutMs });
+		const version = parseVersion(`${result.stdout}\n${result.stderr}`);
+		if (version === null) return reason("did not report a Python version");
+		return { ok: true, path, version, resolvedPath: path };
+	} catch (error) {
+		return reason(`could not run (${error instanceof Error ? error.message.split("\n")[0] : String(error)})`);
+	}
+}
+
 async function detectUncached(
 	language: CodemodeLanguage,
 	hostPlatform: NodeJS.Platform,

package/src/kernels/AGENTS.md

@@ -16,6 +16,8 @@ runner/prelude assets).
 | Julia kernel | `jl/kernel.ts` + `jl/prelude.jl`, `jl/runner.jl` |
 | Shared subprocess layer | `shared/subprocess-kernel.ts`, `subprocess-{contract,process,queue,run}.ts`, `runtime-asset.ts` |
 | Session environment | `session-env.ts` (PI_* contract shared by all kernels; mirrors the core bash tool) |
+| JS process isolation | `js/process-worker.ts` (host side), `js/process-entry.js` (child entry), `js/kernel-memory.ts`, `js/control-frames.ts` |
+| Sandbox cells | `sandbox/sandbox-cell.ts` (host executor); `sandbox/vendor/pi-codemode/**` (vendored runtime, see its `VENDORED.md`) |
 
 ## CONVENTIONS
 

package/src/kernels/jl/globals.jl

@@ -0,0 +1,128 @@
+const SENPI_MEMORY_INTERNALS = Set([:senpi_current_cell, :senpi_connection, :senpi_frame_io, :senpi_stdout_capture, :senpi_stderr_capture, :senpi_protocol_stdin])
+
+const SENPI_SIZER_SAMPLE = 1_000
+const SENPI_SIZER_NODE_BUDGET = 5_000
+const SENPI_SIZER_MAX_DEPTH = 64
+const SENPI_SIZER_POINTER = 8
+const SENPI_SIZER_OBJECT = 16
+const SENPI_SIZER_MIN_REPORTED = 1024 * 1024
+
+# Sizes a global with sampling and a node budget per global (leaves count too), so one deep global
+# never hides the ones measured after it and a huge container costs a bounded walk. Only concrete Base
+# containers are iterated; any other AbstractDict or AbstractSet is sized as an opaque struct, so no user
+# length or iterate method runs during a memory report.
+mutable struct SenpiSizer
+    seen::IdDict{Any, Nothing}
+    nodes::Int
+    approximate::Bool
+end
+SenpiSizer() = SenpiSizer(IdDict{Any, Nothing}(), 0, false)
+
+senpi_over_budget(sizer::SenpiSizer) = sizer.nodes >= SENPI_SIZER_NODE_BUDGET
+
+function senpi_size(sizer::SenpiSizer, value, depth::Int)::Int
+    sizer.nodes += 1
+    value isa Type && return 0
+    value isa Union{Number, Char, Bool, Symbol, Nothing} && return isbits(value) ? sizeof(value) : 0
+    value isa String && return SENPI_SIZER_OBJECT + sizeof(value)
+    if ismutable(value)
+        haskey(sizer.seen, value) && return 0
+        sizer.seen[value] = nothing
+    end
+    if depth >= SENPI_SIZER_MAX_DEPTH || senpi_over_budget(sizer)
+        sizer.approximate = true
+        return SENPI_SIZER_OBJECT
+    end
+    if value isa Array
+        isbitstype(eltype(value)) && return SENPI_SIZER_OBJECT + sizeof(value)
+        return SENPI_SIZER_OBJECT + length(value) * SENPI_SIZER_POINTER +
+            senpi_sampled(sizer, length(value), depth) do index
+                isassigned(value, index) ? value[index] : nothing
+            end
+    elseif value isa Union{Dict, IdDict}
+        count = length(value)
+        total = 0
+        taken = 0
+        for (key, item) in value
+            senpi_over_budget(sizer) && break
+            total += senpi_size(sizer, key, depth + 1) + senpi_size(sizer, item, depth + 1)
+            taken += 1
+            taken >= SENPI_SIZER_SAMPLE && break
+        end
+        taken < count && (sizer.approximate = true)
+        return SENPI_SIZER_OBJECT + count * 2 * SENPI_SIZER_POINTER + (taken == 0 ? 0 : div(total * count, taken))
+    elseif value isa Union{Set, Tuple}
+        count = length(value)
+        total = 0
+        taken = 0
+        for item in value
+            senpi_over_budget(sizer) && break
+            total += senpi_size(sizer, item, depth + 1)
+            taken += 1
+            taken >= SENPI_SIZER_SAMPLE && break
+        end
+        taken < count && (sizer.approximate = true)
+        return SENPI_SIZER_OBJECT + count * SENPI_SIZER_POINTER + (taken == 0 ? 0 : div(total * count, taken))
+    end
+    isbits(value) && return sizeof(value)
+    fields = fieldcount(typeof(value))
+    return SENPI_SIZER_OBJECT + fields * SENPI_SIZER_POINTER +
+        senpi_sampled(sizer, fields, depth) do index
+            isdefined(value, index) ? getfield(value, index) : nothing
+        end
+end
+
+# Up to SENPI_SIZER_SAMPLE evenly spaced elements; once the budget runs out part-way, the elements measured
+# so far stand in for the rest.
+function senpi_sampled(at, sizer::SenpiSizer, count::Int, depth::Int)::Int
+    count == 0 && return 0
+    picks = min(count, SENPI_SIZER_SAMPLE)
+    picks < count && (sizer.approximate = true)
+    step = count / picks
+    total = 0
+    measured = 0
+    for sample in 1:picks
+        if senpi_over_budget(sizer)
+            sizer.approximate = true
+            break
+        end
+        total += senpi_size(sizer, at(1 + floor(Int, (sample - 1) * step)), depth + 1)
+        measured += 1
+    end
+    return measured == 0 ? 0 : round(Int, total / measured * count)
+end
+
+function senpi_largest_globals(limit::Int)
+    try
+        sizer = SenpiSizer()
+        candidates = Tuple{String, Int, Bool}[]
+        Base.invokelatest() do
+            for name in names(Main, all = true)
+                name in SENPI_MEMORY_INTERNALS && continue
+                name in (:Main, :Base, :Core, :Ans, :ans) && continue
+                lowered = lowercase(string(name))
+                startswith(lowered, "senpi_") && continue
+                startswith(string(name), "Senpi") && continue
+                startswith(string(name), "#") && continue
+                isdefined(Main, name) || continue
+                value = getfield(Main, name)
+                value isa Module && continue
+                value isa IO && continue
+                value isa Type && continue
+                value isa Function && continue
+                sizer.approximate = false
+                sizer.nodes = 0
+                bytes = try
+                    senpi_size(sizer, value, 0) + SENPI_SIZER_POINTER
+                catch
+                    0
+                end
+                bytes >= SENPI_SIZER_MIN_REPORTED && push!(candidates, (string(name), bytes, sizer.approximate))
+            end
+        end
+        sort!(candidates, by = entry -> entry[2], rev = true)
+        [approximate ? Dict{String, Any}("name" => name, "bytes" => bytes, "approximate" => true) : Dict{String, Any}("name" => name, "bytes" => bytes) for (name, bytes, approximate) in candidates[1:min(limit, end)]]
+    catch
+        Dict{String, Any}[]
+    end
+end

package/src/kernels/jl/prelude.jl

@@ -231,12 +231,25 @@ function workpool(agent::AbstractDict, name::AbstractString; mode=nothing, tools
     throw(SenpiBridgeError("Host did not return a workpool identity", "workpool_unavailable"))
 end
 
-include("handles.jl")
+const SENPI_HANDLES_INCLUDED = Ref(false)
+const SENPI_HANDLES_INCLUDE_LOCK = ReentrantLock()
+
+function senpi_ensure_handles()
+    lock(SENPI_HANDLES_INCLUDE_LOCK) do
+        if !SENPI_HANDLES_INCLUDED[]
+            include(joinpath(@__DIR__, "handles.jl"))
+            SENPI_HANDLES_INCLUDED[] = true
+        end
+    end
+    nothing
+end
 
 # Rich view of an agent record, workpool, completion handle or saved reference; see tool_schema("eval:helpers").
 # The barrier is `Base.wait` on the view types (never a `Main.wait`): wait(handle(node)) or wait([handle(a), handle(b)]).
 function handle(value)
-    senpi_handle_view(value)
+    senpi_ensure_handles()
+    # Julia 1.12 ages global bindings too: resolve the new helper inside the latest world.
+    Base.invokelatest(() -> senpi_handle_view(value))
 end
 
 function completion(prompt::AbstractString; model="default", system=nothing, schema=nothing, kwargs...)