@code-yeongyu/senpi-codemode 2026.10.5 → 2026.10.7

package/src/kernels/jl/runner.jl

@@ -1,4 +1,6 @@
 # allow: SIZE_OK — parser, stream capture, bridge calls, and the persistent execution loop share Main globals.
+write(stdout, "{\"type\":\"status\",\"event\":{\"op\":\"kernel-startup\",\"stage\":\"stdlib-imports\"}}\n")
+flush(stdout)
 using Sockets
 
 const SENPI_ORIGINAL_STDOUT = stdout
@@ -7,6 +9,8 @@ out_read, out_write = redirect_stdout()
 err_read, err_write = redirect_stderr()
 redirect_stdin(devnull)
 
+write(SENPI_ORIGINAL_STDOUT, "{\"type\":\"status\",\"event\":{\"op\":\"kernel-startup\",\"stage\":\"runtime-init\"}}\n")
+flush(SENPI_ORIGINAL_STDOUT)
 include("prelude.jl")
 
 const senpi_connection = Dict{String, Any}()
@@ -220,12 +224,15 @@ function senpi_http_body(response::AbstractString)
     String(output)
 end
 
-function senpi_bridge_request(path::String, payload)
+# `read_timeout` (seconds) bounds only the long-lived `wait()` request; ordinary calls read until the host closes.
+function senpi_bridge_request(path::String, payload; read_timeout=nothing)
     port = get(senpi_connection, "port", nothing)
     token = get(senpi_connection, "token", nothing)
     port isa Integer && token isa AbstractString || error("Julia tool bridge is not initialized")
     body = senpi_json(payload)
     socket = connect(ip"127.0.0.1", port)
+    timed_out = Ref(false)
+    timer = read_timeout === nothing ? nothing : Timer(_ -> (timed_out[] = true; close(socket)), Float64(read_timeout))
     try
         request = join([
             "POST " * path * " HTTP/1.1",
@@ -240,12 +247,14 @@ function senpi_bridge_request(path::String, payload)
         Base.write(socket, request)
         flush(socket)
         response = Base.read(socket, String)
+        timed_out[] && throw(SenpiBridgeError("bridge request timed out after $(read_timeout)s", "bridge_timeout"))
         parsed = senpi_json_parse(senpi_http_body(response))
         parsed isa AbstractDict || error("Bridge returned invalid JSON")
         get(parsed, "ok", false) === true && return get(parsed, "value", nothing)
         failure = get(parsed, "error", parsed)
         throw(SenpiBridgeError(failure isa AbstractDict ? string(get(failure, "message", failure)) : string(failure), failure isa AbstractDict ? get(failure, "code", nothing) : nothing))
     finally
+        timer === nothing || close(timer)
         close(socket)
     end
 end
@@ -281,6 +290,152 @@ function senpi_set_connection(value)
     end
 end
 
+const senpi_memory = Ref{Any}(nothing)
+
+const SENPI_MEMORY_INTERNALS = Set([:senpi_current_cell, :senpi_memory, :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
+
+function senpi_memory_report()
+    try
+        senpi_memory[] === nothing && return nothing
+        # The host reads the interpreter's current footprint and decides on the notice; the runner only
+        # names its largest globals, with a bounded walk, so a cell never pays for an unbounded scan.
+        named = senpi_largest_globals(5)
+        # The host replaces liveBytes with the interpreter footprint it reads itself; only globals is used.
+        report = Dict{String, Any}("liveBytes" => 0, "measure" => "footprint")
+        isempty(named) || (report["globals"] = named)
+        report
+    catch
+        nothing
+    end
+end
+
 function senpi_run_cell(message)
     cell_id = string(get(message, "cellId", ""))
     code = string(get(message, "code", ""))
@@ -297,6 +452,8 @@ function senpi_run_cell(message)
         yield()
         frame = Dict{String, Any}("type" => "result", "cellId" => cell_id, "ok" => true, "durationMs" => round(Int, (time() - started) * 1000))
         value !== nothing && senpi_should_display_result(parsed) && (frame["valueRepr"] = senpi_json(value))
+        memory = senpi_memory_report()
+        memory !== nothing && (frame["memory"] = memory)
         senpi_emit(frame)
     catch error
         senpi_emit(Dict("type" => "result", "cellId" => cell_id, "ok" => false, "error" => senpi_error(error), "durationMs" => round(Int, (time() - started) * 1000)))
@@ -313,7 +470,9 @@ while !eof(SENPI_ORIGINAL_STDIN)
         message isa AbstractDict || error("Bridge frame must be an object")
         kind = get(message, "type", nothing)
         if kind == "init"
+            senpi_emit(Dict("type" => "status", "event" => Dict("op" => "kernel-startup", "stage" => "host-init")))
             senpi_set_connection(get(message, "connection", nothing))
+            senpi_memory[] = get(message, "memory", nothing)
             senpi_emit(Dict("type" => "ready"))
         elseif kind == "run"
             senpi_run_cell(message)

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

@@ -1,6 +1,7 @@
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { CHILD_LIFECYCLE_OP, INTERRUPT_ACK_OP } from "../../bridge/reserved.ts";
 import type { KernelInterruptHandle } from "../../tool/types.ts";
+import { KernelToolHostPump } from "../shared/kernel-tools-pump.ts";
 import { ActiveCellControl } from "./active-cell-control.ts";
 import { DEFAULT_INTERRUPT_BOUNDS, type WorkerRetirement } from "./interrupt-bounds.ts";
 import {
@@ -14,7 +15,6 @@ import {
 } from "./kernel-contract.ts";
 import { type JavaScriptMemoryReading, KernelMemoryBridge } from "./kernel-memory-bridge.ts";
 import { kernelToolError } from "./kernel-tools-errors.ts";
-import { KernelToolHostPump } from "./kernel-tools-host.ts";
 import type {
 	KernelToolsDescribeResult,
 	KernelToolsInvokeOptions,

package/src/kernels/js/handles.js

@@ -0,0 +1,93 @@
+// In-cell `wait()` / `handle()` over the host's handle capability. Mirrors src/bridge/reserved.ts; this
+// worker asset cannot import TypeScript. Every call rides the ordinary bridge-call path (`callTool`), so
+// the run budget pauses while the cell is parked and the hard limit still applies.
+const RESERVED_WAIT_TOOL = "__wait__";
+const RESERVED_HANDLE_STATUS_TOOL = "__handle_status__";
+const RESERVED_HANDLE_OUTPUT_TOOL = "__handle_output__";
+const RESERVED_HANDLE_SEND_TOOL = "__handle_send__";
+const RESERVED_HANDLE_CANCEL_TOOL = "__handle_cancel__";
+const KINDS = new Set(["agent", "completion", "workpool"]);
+const WAIT_MODES = new Set(["all", "any", "settled"]);
+const USAGE = "handle() expects an agent(..., {handle: true}) record, a workpool, a completion handle, or a saved {kind, id, run_epoch} reference";
+
+export function createHandleHelpers(callTool) {
+	const wait = async (handles, options) => {
+		const list = Array.isArray(handles) ? handles : handles === undefined || handles === null ? [] : [handles];
+		const refs = list.map(toHandleRef);
+		const { timeout, mode } = waitOptions(options);
+		return await callTool(RESERVED_WAIT_TOOL, {
+			refs,
+			...(timeout === undefined ? {} : { timeout }),
+			...(mode === undefined ? {} : { mode }),
+		});
+	};
+	const handle = value => {
+		const ref = toHandleRef(value);
+		const view = Object.create(Object.prototype);
+		if (isPlainObject(value)) {
+			for (const [key, field] of Object.entries(value)) {
+				if (typeof field !== "function") view[key] = field;
+			}
+		}
+		if (!Object.hasOwn(view, "id")) view.id = ref.id;
+		if (!Object.hasOwn(view, "run_epoch")) view.run_epoch = ref.run_epoch;
+		if (!Object.hasOwn(view, "handle")) view.handle = `${ref.kind}://${ref.id}`;
+		const control = Object.freeze({
+			status: async () => await callTool(RESERVED_HANDLE_STATUS_TOOL, { ref }),
+			output: async (opts = {}) => await callTool(RESERVED_HANDLE_OUTPUT_TOOL, { ref, ...outputOptions(opts) }),
+			send: async message => await callTool(RESERVED_HANDLE_SEND_TOOL, { ref, message: String(message) }),
+			cancel: async () => await callTool(RESERVED_HANDLE_CANCEL_TOOL, { ref }),
+			wait: async (opts = {}) => (await wait([ref], { ...waitOptions(opts), mode: "all" }))[0],
+		});
+		Object.defineProperty(view, "ref", { value: Object.freeze({ ...ref }), enumerable: false });
+		Object.defineProperty(view, "control", { value: control, enumerable: false });
+		return view;
+	};
+	return { wait, handle };
+}
+
+/** Accepts legacy agent records, handle() views, completion handles, workpools and saved refs. */
+export function toHandleRef(value) {
+	if (!isPlainObject(value)) throw new TypeError(USAGE);
+	if (isPlainObject(value.ref) && KINDS.has(value.ref.kind)) return toHandleRef(value.ref);
+	if (typeof value.pool_id === "string") return { kind: "workpool", id: value.pool_id, run_epoch: 0 };
+	const kind = KINDS.has(value.kind) ? value.kind : kindFromHandle(value.handle);
+	const id = value.id ?? value.task_id;
+	if (kind === undefined || typeof id !== "string" || id.length === 0) throw new TypeError(USAGE);
+	const run_epoch = value.run_epoch ?? (kind === "workpool" ? 0 : undefined);
+	if (!Number.isInteger(run_epoch) || run_epoch < 0) throw new TypeError(`${USAGE}; run_epoch must be a non-negative integer`);
+	return { kind, id, run_epoch };
+}
+
+function kindFromHandle(handle) {
+	if (typeof handle !== "string") return undefined;
+	const scheme = handle.split("://")[0];
+	return KINDS.has(scheme) ? scheme : undefined;
+}
+
+function waitOptions(options) {
+	if (options === undefined || options === null) return {};
+	if (!isPlainObject(options)) throw new TypeError("wait() accepts { timeout, mode }");
+	for (const key of Object.keys(options)) {
+		if (key !== "timeout" && key !== "mode") throw new TypeError("wait() accepts { timeout, mode }");
+	}
+	const { timeout, mode } = options;
+	if (timeout !== undefined && timeout !== null && (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout < 0)) {
+		throw new TypeError("wait() timeout must be a finite number of seconds >= 0");
+	}
+	if (mode !== undefined && mode !== null && !WAIT_MODES.has(mode)) throw new TypeError('wait() mode must be "all", "any" or "settled"');
+	return { ...(timeout === undefined || timeout === null ? {} : { timeout }), ...(mode === undefined || mode === null ? {} : { mode }) };
+}
+
+function outputOptions(options) {
+	if (!isPlainObject(options)) throw new TypeError("control.output() accepts { format, offset, limit }");
+	const picked = {};
+	for (const key of ["format", "offset", "limit"]) {
+		if (options[key] !== undefined && options[key] !== null) picked[key] = options[key];
+	}
+	return picked;
+}
+
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/kernels/js/kernel-tools-define.d.ts

@@ -2,9 +2,15 @@ export type KernelToolFunction = {
 	readonly name: string;
 };
 
+export type KernelToolNamespaceRegistry = {
+	readonly defined?: () => string[];
+	readonly undefine?: (name: unknown) => boolean;
+};
+
 export function createToolNamespace(
 	define: (fn: KernelToolFunction, metadata?: unknown) => unknown,
 	callHost: (name: string, args: unknown) => Promise<unknown>,
+	registry?: KernelToolNamespaceRegistry,
 ): ((fn: KernelToolFunction, metadata?: unknown) => unknown) & {
 	readonly [name: string]: (args?: unknown) => Promise<unknown>;
 };

package/src/kernels/js/kernel-tools-define.js

@@ -1,4 +1,4 @@
-export function createToolNamespace(define, callHost) {
+export function createToolNamespace(define, callHost, registry = {}) {
 	const registrar = function tool(fn, metadata) {
 		return define(fn, metadata);
 	};
@@ -6,6 +6,8 @@ export function createToolNamespace(define, callHost) {
 		get(target, prop) {
 			if (typeof prop !== "string") return undefined;
 			if (prop in Function.prototype || prop === "arguments" || prop === "caller") return target[prop];
+			if (prop === "defined" && registry.defined) return () => registry.defined();
+			if (prop === "undefine" && registry.undefine) return (name) => registry.undefine(name);
 			return async (args) => await callHost(prop, args ?? {});
 		},
 	});

package/src/kernels/js/kernel-tools-registry.d.ts

@@ -22,6 +22,8 @@ export function createKernelToolRegistry(options?: KernelToolRegistryOptions): {
 		},
 		signal?: AbortSignal,
 	): Promise<unknown>;
+	defined(): string[];
+	undefine(name: unknown): boolean;
 	bumpGeneration(): number;
 	setCollisionNames(hostToolNames?: readonly string[], foreignLanguageNames?: readonly string[]): void;
 };

package/src/kernels/js/kernel-tools-registry.js

@@ -6,7 +6,8 @@ import { orderedArgs, resolveToolMetadata, validateInvokeArgs } from "./kernel-t
 
 export { createToolNamespace };
 
-const DEFAULT_RESERVED = Object.freeze(["__agent__", "__output__", "__schema__"]);
+// "defined" and "undefine" are the tool namespace's own members, so a kernel tool by those names could never be reached.
+const DEFAULT_RESERVED = Object.freeze(["__agent__", "__output__", "__schema__", "defined", "undefine"]);
 
 function currentNames(source) {
 	return typeof source === "function" ? source() : (source ?? []);
@@ -47,21 +48,22 @@ export function createKernelToolRegistry(options = {}) {
 			assertJs();
 			const parsed = parseToolFunction(fn);
 			const resolved = resolveToolMetadata(metadata, parsed.params);
-			if (sanitizeNamePart(parsed.name) !== parsed.name || parsed.name.length > MCP_TOOL_NAME_MAX_LENGTH) {
+			const name = resolved.name ?? parsed.name;
+			if (sanitizeNamePart(name) !== name || name.length > MCP_TOOL_NAME_MAX_LENGTH) {
 				throw kernelToolError("invalid_tool_definition", "Kernel tool name must match MCP name grammar");
 			}
-			const normalizedName = parsed.name;
-			const key = kernelToolKey(parsed.name);
-			if (reservedKeys.has(key)) throw kernelToolError("reserved_tool_name", `Kernel tool name is reserved: ${parsed.name}`);
+			const normalizedName = name;
+			const key = kernelToolKey(name);
+			if (reservedKeys.has(key)) throw kernelToolError("reserved_tool_name", `Kernel tool name is reserved: ${name}`);
 			if (hasNameKey(hostSource, key) || hasNameKey(foreignSource, key)) {
-				throw kernelToolError("tool_name_collision", `Kernel tool name collides: ${parsed.name}`);
+				throw kernelToolError("tool_name_collision", `Kernel tool name collides: ${name}`);
 			}
 			const existing = entries.get(key);
-			if (existing && existing.originalName !== parsed.name) {
-				throw kernelToolError("tool_name_collision", `Kernel tool name collides: ${parsed.name}`);
+			if (existing && existing.originalName !== name) {
+				throw kernelToolError("tool_name_collision", `Kernel tool name collides: ${name}`);
 			}
 			const entry = {
-				originalName: parsed.name,
+				originalName: name,
 				normalizedName,
 				fn,
 				params: parsed.params,
@@ -114,6 +116,13 @@ export function createKernelToolRegistry(options = {}) {
 				throw kernelToolError("kernel_tool_failed", error instanceof Error ? error.message : String(error));
 			}
 		},
+		defined() {
+			return [...entries.values()].map((entry) => entry.normalizedName).sort();
+		},
+		undefine(name) {
+			if (typeof name !== "string") return false;
+			return entries.delete(kernelToolKey(name));
+		},
 		bumpGeneration() {
 			generation += 1;
 			entries.clear();

package/src/kernels/js/kernel-tools-schema.js

@@ -18,7 +18,11 @@ export function resolveToolMetadata(metadata, params) {
 	if (typeof description !== "string") {
 		throw kernelToolError("invalid_tool_definition", "tool() description must be a string");
 	}
-	if (metadata.schema === undefined) return { description, input_schema: defaultInputSchema(params) };
+	if (metadata.name !== undefined && typeof metadata.name !== "string") {
+		throw kernelToolError("invalid_tool_definition", "tool() name must be a string");
+	}
+	const named = metadata.name === undefined ? {} : { name: metadata.name };
+	if (metadata.schema === undefined) return { ...named, description, input_schema: defaultInputSchema(params) };
 	const schema = metadata.schema;
 	if (!isPlainJsonObject(schema) || schema.type !== "object" || !isPlainJsonObject(schema.properties)) {
 		throw kernelToolError("invalid_tool_definition", "tool() metadata schema must be a JSON object schema");
@@ -27,7 +31,7 @@ export function resolveToolMetadata(metadata, params) {
 	if (propertyKeys.length !== params.length || params.some((name) => !Object.hasOwn(schema.properties, name))) {
 		throw kernelToolError("invalid_tool_definition", "tool() metadata schema properties must match parameters");
 	}
-	return { description, input_schema: schema };
+	return { ...named, description, input_schema: schema };
 }
 
 export function validateInvokeArgs(schema, args) {

package/src/kernels/js/kernel-tools-types.ts

@@ -1,4 +1,5 @@
 import type { ExtensionKernelTools, KernelToolInvokeOptions, KernelToolInvokeScope } from "@code-yeongyu/senpi";
+import type { EvalLanguage } from "../../tool/types.ts";
 import type { KernelToolErrorCode, KernelToolHostDenial, KernelToolHostDenialReason } from "./kernel-tools-errors.ts";
 
 export type { KernelToolErrorCode, KernelToolHostDenial, KernelToolHostDenialReason };
@@ -7,7 +8,7 @@ export type KernelToolDescriptor = {
 	readonly name: string;
 	readonly description: string;
 	readonly input_schema: unknown;
-	readonly language: "js";
+	readonly language: EvalLanguage;
 	readonly kernel_generation: number;
 	readonly definition_revision: number;
 };

package/src/kernels/js/worker-global-sizes.js

@@ -9,6 +9,54 @@ const FUNCTION_BYTES = 64;
 const INTERNAL_GLOBAL_PREFIX = "__senpi";
 const MIN_REPORTED_BYTES = 1024 * 1024;
 
+function intrinsicGetter(prototype, name) {
+	return Object.getOwnPropertyDescriptor(prototype, name)?.get;
+}
+
+// Built-in getters captured at load: a user subclass that overrides `byteLength` or `size` is never called.
+const TYPED_ARRAY_BYTE_LENGTH = intrinsicGetter(Object.getPrototypeOf(Uint8Array.prototype), "byteLength");
+const DATA_VIEW_BYTE_LENGTH = intrinsicGetter(DataView.prototype, "byteLength");
+const ARRAY_BUFFER_BYTE_LENGTH = intrinsicGetter(ArrayBuffer.prototype, "byteLength");
+const SHARED_ARRAY_BUFFER_BYTE_LENGTH =
+	typeof SharedArrayBuffer === "function" ? intrinsicGetter(SharedArrayBuffer.prototype, "byteLength") : undefined;
+const MAP_SIZE = intrinsicGetter(Map.prototype, "size");
+const SET_SIZE = intrinsicGetter(Set.prototype, "size");
+const BLOB_SIZE = typeof Blob === "function" ? intrinsicGetter(Blob.prototype, "size") : undefined;
+// Iteration captured at load too: a user who replaces Map.prototype.entries or an iterator's next() is never called.
+const MAP_ENTRIES = Map.prototype.entries;
+const SET_VALUES = Set.prototype.values;
+const MAP_ITERATOR_NEXT = Object.getPrototypeOf(new Map().entries()).next;
+const SET_ITERATOR_NEXT = Object.getPrototypeOf(new Set().values()).next;
+
+function read(getter, value) {
+	return Reflect.apply(getter, value, []);
+}
+
+const GET_PROTOTYPE_OF = Object.getPrototypeOf;
+const BLOB_PROTOTYPE = typeof Blob === "function" ? Blob.prototype : undefined;
+
+function inheritsFromBlob(value) {
+	for (let prototype = GET_PROTOTYPE_OF(value); prototype !== null; prototype = GET_PROTOTYPE_OF(prototype)) {
+		// A Proxy in the chain would run its getPrototypeOf trap on the next step.
+		if (types.isProxy(prototype)) return false;
+		if (prototype === BLOB_PROTOTYPE) return true;
+	}
+	return false;
+}
+
+// The Blob brand: a cheap prototype-chain pre-check (no user hook; proxies never reach here) so ordinary
+// objects skip the try, then the size getter as the proof, which throws on a forged look-alike.
+// instanceof would call a user-redefinable Symbol.hasInstance.
+function isBlob(value) {
+	if (BLOB_SIZE === undefined || !inheritsFromBlob(value)) return false;
+	try {
+		read(BLOB_SIZE, value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 export function captureGlobalBaseline() {
 	return new Set(Object.getOwnPropertyNames(globalThis));
 }
@@ -55,11 +103,12 @@ function createSizer() {
 		return (total / SAMPLED_ELEMENTS) * length;
 	}
 
-	function entriesOf(iterable, count, depth, sizeOf) {
+	function entriesOf(iterator, next, count, depth, sizeOf) {
 		const taken = [];
-		for (const entry of iterable) {
-			taken.push(entry);
-			if (taken.length >= SAMPLED_ELEMENTS) break;
+		while (taken.length < SAMPLED_ELEMENTS) {
+			const step = Reflect.apply(next, iterator, []);
+			if (step.done) break;
+			taken.push(step.value);
 		}
 		if (taken.length < count) approximate = true;
 		let total = 0;
@@ -67,21 +116,42 @@ function createSizer() {
 		return total * (count / Math.max(1, taken.length));
 	}
 
+	// An own data element, never a getter: an accessor is left unsized and makes the estimate approximate.
+	function elementOf(array, index) {
+		const descriptor = Object.getOwnPropertyDescriptor(array, index);
+		if (descriptor === undefined) return undefined;
+		if ("value" in descriptor) return descriptor.value;
+		approximate = true;
+		return undefined;
+	}
+
 	function objectSize(value, depth) {
 		if (types.isProxy(value)) return OBJECT_BYTES;
-		if (ArrayBuffer.isView(value)) return value.byteLength;
-		if (types.isAnyArrayBuffer(value)) return value.byteLength;
-		if (typeof Blob === "function" && value instanceof Blob) return value.size;
-		if (Array.isArray(value)) return OBJECT_BYTES + value.length * POINTER_BYTES + sampled(value.length, (index) => value[index], depth);
-		if (value instanceof Map) {
-			const entries = Map.prototype.entries.call(value);
-			return OBJECT_BYTES + value.size * 2 * POINTER_BYTES + entriesOf(entries, value.size, depth, ([key, item], at) => size(key, at) + size(item, at));
+		if (types.isTypedArray(value)) return read(TYPED_ARRAY_BYTE_LENGTH, value);
+		if (types.isDataView(value)) return read(DATA_VIEW_BYTE_LENGTH, value);
+		if (types.isArrayBuffer(value)) return read(ARRAY_BUFFER_BYTE_LENGTH, value);
+		if (types.isSharedArrayBuffer(value) && SHARED_ARRAY_BUFFER_BYTE_LENGTH) return read(SHARED_ARRAY_BUFFER_BYTE_LENGTH, value);
+		if (isBlob(value)) return read(BLOB_SIZE, value);
+		if (Array.isArray(value)) {
+			const length = value.length;
+			return OBJECT_BYTES + length * POINTER_BYTES + sampled(length, (index) => elementOf(value, index), depth);
+		}
+		if (types.isMap(value)) {
+			const count = read(MAP_SIZE, value);
+			const entries = Reflect.apply(MAP_ENTRIES, value, []);
+			return OBJECT_BYTES + count * 2 * POINTER_BYTES + entriesOf(entries, MAP_ITERATOR_NEXT, count, depth, ([key, item], at) => size(key, at) + size(item, at));
+		}
+		if (types.isSet(value)) {
+			const count = read(SET_SIZE, value);
+			return OBJECT_BYTES + count * POINTER_BYTES + entriesOf(Reflect.apply(SET_VALUES, value, []), SET_ITERATOR_NEXT, count, depth, size);
 		}
-		if (value instanceof Set) return OBJECT_BYTES + value.size * POINTER_BYTES + entriesOf(Set.prototype.values.call(value), value.size, depth, size);
 		const keys = Object.keys(value);
 		const propertyValue = (index) => {
 			const descriptor = Object.getOwnPropertyDescriptor(value, keys[index]);
-			return descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+			if (descriptor === undefined) return undefined;
+			if ("value" in descriptor) return descriptor.value;
+			approximate = true;
+			return undefined;
 		};
 		return OBJECT_BYTES + keys.length * POINTER_BYTES + sampled(keys.length, propertyValue, depth);
 	}
@@ -114,7 +184,7 @@ function createSizer() {
 			try {
 				return { bytes: POINTER_BYTES + size(value, 0), approximate };
 			} catch (error) {
-				// A user value can still throw from an exotic element read (an index getter); it is left unsized.
+				// A forged built-in look-alike (a Blob-prototype object without its slot) throws from the intrinsic getter; it is left unsized.
 				if (error instanceof Error) return undefined;
 				throw error;
 			}

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

@@ -8,6 +8,7 @@ import { awaitMaybePromise, indirectEval, wrapUserCode } from "./worker-indirect
 import { installShellCapture } from "./worker-shell-capture.js";
 import { bindKernelBun } from "./worker-webview.js";
 import { createWorkpool } from "./workpool.js";
+import { createHandleHelpers } from "./handles.js";
 import { inKernelToolInvoke } from "./kernel-tools-context.js";
 import { kernelToolError } from "./kernel-tools-errors.js";
 import { createKernelToolRegistry, createToolNamespace } from "./kernel-tools-registry.js";
@@ -137,10 +138,18 @@ export class JsWorkerRuntime {
 		globalThis.workpool = (agent, name, options) => createWorkpool((toolName, args) => this.#callTool(toolName, args), agent, name, options);
 		globalThis.parallel = async thunks => await this.#parallel(thunks);
 		globalThis.pipeline = async (items, ...stages) => await this.#pipeline(items, stages);
-		globalThis.completion = async (prompt, opts) => await this.#callTool("completion", { prompt, opts });
+		const handles = createHandleHelpers(async (toolName, args) => await this.#callTool(toolName, args));
+		globalThis.completion = async (prompt, opts) => {
+			const value = await this.#callTool("completion", { prompt, opts });
+			// The host answers a {handle: true} request with a saved reference; the cell gets the control view.
+			return isPlainObject(opts) && opts.handle === true ? handles.handle(value) : value;
+		};
+		globalThis.wait = async (list, options) => await handles.wait(list, options);
+		globalThis.handle = value => handles.handle(value);
 		globalThis.tool = createToolNamespace(
 			(fn, metadata) => this.#tools.define(fn, metadata),
 			async (name, args) => await this.#callTool(name, args),
+			{ defined: () => this.#tools.defined(), undefine: (name) => this.#tools.undefine(name) },
 		);
 		globalThis.tools = globalThis.tool;
 		const originalLog = console.log.bind(console);