@code-yeongyu/senpi-codemode 2026.10.6 → 2026.10.7

package/src/kernels/jl/handles.jl

@@ -0,0 +1,124 @@
+# In-cell wait()/handle() over the host's handle capability. Mirrors src/bridge/reserved.ts.
+# `Main.wait` is never defined here: `Base.wait` gains methods for the handle types, so `wait(::Task)` for
+# `@async` users keeps working.
+const SENPI_RESERVED_WAIT_TOOL = "__wait__"
+const SENPI_RESERVED_HANDLE_STATUS_TOOL = "__handle_status__"
+const SENPI_RESERVED_HANDLE_OUTPUT_TOOL = "__handle_output__"
+const SENPI_RESERVED_HANDLE_SEND_TOOL = "__handle_send__"
+const SENPI_RESERVED_HANDLE_CANCEL_TOOL = "__handle_cancel__"
+const SENPI_HANDLE_KINDS = ("agent", "completion", "workpool")
+const SENPI_WAIT_MODES = ("all", "any", "settled")
+const SENPI_WAIT_SOCKET_GRACE_SECONDS = 30
+const SENPI_HANDLE_USAGE = "handle() expects an agent(...; handle=true) record, a workpool, a completion handle, or a saved {kind, id, run_epoch} reference"
+
+struct SenpiHandleControl
+    ref::Dict{String, Any}
+end
+
+# The legacy record's fields behave as a Dict; `control` and `ref` are properties, never keys.
+struct SenpiHandle <: AbstractDict{String, Any}
+    fields::Dict{String, Any}
+    ref::Dict{String, Any}
+end
+
+Base.iterate(handle::SenpiHandle, state...) = iterate(getfield(handle, :fields), state...)
+Base.length(handle::SenpiHandle) = length(getfield(handle, :fields))
+Base.get(handle::SenpiHandle, key, default) = get(getfield(handle, :fields), key, default)
+Base.getindex(handle::SenpiHandle, key) = getfield(handle, :fields)[key]
+Base.haskey(handle::SenpiHandle, key) = haskey(getfield(handle, :fields), key)
+Base.keys(handle::SenpiHandle) = keys(getfield(handle, :fields))
+Base.values(handle::SenpiHandle) = values(getfield(handle, :fields))
+
+function Base.getproperty(handle::SenpiHandle, name::Symbol)
+    name === :ref && return copy(getfield(handle, :ref))
+    name === :control && return SenpiHandleControl(copy(getfield(handle, :ref)))
+    fields = getfield(handle, :fields)
+    key = string(name)
+    haskey(fields, key) && return fields[key]
+    getfield(handle, name)
+end
+
+Base.propertynames(handle::SenpiHandle) = (Symbol.(collect(keys(getfield(handle, :fields))))..., :control, :ref)
+
+function senpi_handle_ref(value)
+    value isa SenpiHandle && return copy(getfield(value, :ref))
+    value isa SenpiWorkpool && return Dict{String, Any}("kind" => "workpool", "id" => getfield(value, :pool_id), "run_epoch" => 0)
+    value isa AbstractDict || error(SENPI_HANDLE_USAGE)
+    record = Dict{String, Any}(string(key) => item for (key, item) in value)
+    pool_id = get(record, "pool_id", nothing)
+    pool_id isa AbstractString && return Dict{String, Any}("kind" => "workpool", "id" => string(pool_id), "run_epoch" => 0)
+    kind = get(record, "kind", nothing)
+    if !(kind in SENPI_HANDLE_KINDS)
+        handle_uri = get(record, "handle", nothing)
+        scheme = handle_uri isa AbstractString ? first(split(handle_uri, "://"; limit=2)) : nothing
+        kind = scheme in SENPI_HANDLE_KINDS ? scheme : nothing
+    end
+    identity = get(record, "id", get(record, "task_id", nothing))
+    (kind === nothing || !(identity isa AbstractString) || isempty(identity)) && error(SENPI_HANDLE_USAGE)
+    run_epoch = get(record, "run_epoch", kind == "workpool" ? 0 : nothing)
+    (run_epoch isa Integer && !(run_epoch isa Bool) && run_epoch >= 0) || error(SENPI_HANDLE_USAGE * "; run_epoch must be a non-negative integer")
+    Dict{String, Any}("kind" => string(kind), "id" => string(identity), "run_epoch" => Int(run_epoch))
+end
+
+function senpi_handle_call(tool_name::String, arguments)
+    senpi_with_bridge_timeout_pause(() -> senpi_call_tool(tool_name, arguments))
+end
+
+# A long-lived request bounded by the explicit timeout (plus grace for the host's reply) or else only by the
+# cell's own end; an interrupt from the host (cancel, the cell's hard limit) closes the socket and so the
+# host-side subscription.
+function senpi_wait_post(arguments, timeout)
+    read_timeout = timeout === nothing ? nothing : Float64(timeout) + SENPI_WAIT_SOCKET_GRACE_SECONDS
+    payload = Dict("callId" => "jl-" * string(time_ns()), "toolName" => SENPI_RESERVED_WAIT_TOOL, "args" => arguments)
+    senpi_with_bridge_timeout_pause(() -> senpi_bridge_request("/call", payload; read_timeout=read_timeout))
+end
+
+function senpi_wait(handles; timeout=nothing, mode="all")
+    items = handles === nothing ? Any[] : handles isa AbstractVector || handles isa Tuple ? collect(handles) : Any[handles]
+    if timeout !== nothing
+        (timeout isa Real && !(timeout isa Bool) && isfinite(timeout) && timeout >= 0) || error("wait() timeout must be a finite number of seconds >= 0")
+    end
+    string(mode) in SENPI_WAIT_MODES || error("wait() mode must be \"all\", \"any\" or \"settled\"")
+    arguments = Dict{String, Any}("refs" => [senpi_handle_ref(item) for item in items], "mode" => string(mode))
+    timeout === nothing || (arguments["timeout"] = timeout)
+    senpi_wait_post(arguments, timeout)
+end
+
+function Base.getproperty(control::SenpiHandleControl, name::Symbol)
+    ref = getfield(control, :ref)
+    name === :ref && return copy(ref)
+    name === :status && return () -> senpi_handle_call(SENPI_RESERVED_HANDLE_STATUS_TOOL, Dict("ref" => ref))
+    if name === :output
+        return (; format="raw", offset=nothing, limit=nothing) -> begin
+            arguments = Dict{String, Any}("ref" => ref, "format" => string(format))
+            offset === nothing || (arguments["offset"] = offset)
+            limit === nothing || (arguments["limit"] = limit)
+            senpi_handle_call(SENPI_RESERVED_HANDLE_OUTPUT_TOOL, arguments)
+        end
+    end
+    name === :send && return message -> senpi_handle_call(SENPI_RESERVED_HANDLE_SEND_TOOL, Dict("ref" => ref, "message" => string(message)))
+    name === :cancel && return () -> senpi_handle_call(SENPI_RESERVED_HANDLE_CANCEL_TOOL, Dict("ref" => ref))
+    name === :wait && return (; timeout=nothing) -> senpi_wait([ref]; timeout=timeout, mode="all")[1]
+    getfield(control, name)
+end
+
+Base.propertynames(::SenpiHandleControl) = (:status, :output, :send, :cancel, :wait, :ref)
+Base.show(io::IO, control::SenpiHandleControl) = Base.print(io, "<handle.control ", getfield(control, :ref)["kind"], "://", getfield(control, :ref)["id"], "@", getfield(control, :ref)["run_epoch"], ">")
+
+function senpi_handle_view(value)
+    ref = senpi_handle_ref(value)
+    fields = Dict{String, Any}()
+    if value isa AbstractDict
+        for (key, item) in value
+            item isa Function || (fields[string(key)] = item)
+        end
+    end
+    get!(fields, "id", ref["id"])
+    get!(fields, "run_epoch", ref["run_epoch"])
+    get!(fields, "handle", ref["kind"] * "://" * ref["id"])
+    SenpiHandle(fields, ref)
+end
+
+# Block until the handles settle; never cancels work. See tool_schema("eval:wait").
+Base.wait(handle::SenpiHandle; timeout=nothing, mode="all") = senpi_wait([handle]; timeout=timeout, mode=mode)
+Base.wait(handles::AbstractVector{<:SenpiHandle}; timeout=nothing, mode="all") = senpi_wait(handles; timeout=timeout, mode=mode)

package/src/kernels/jl/prelude.jl

@@ -226,6 +226,14 @@ function workpool(agent::AbstractDict, name::AbstractString; mode=nothing)
     throw(SenpiBridgeError("Host did not return a workpool identity", "workpool_unavailable"))
 end
 
+include("handles.jl")
+
+# 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)
+end
+
 function completion(prompt::AbstractString; model="default", system=nothing, schema=nothing, kwargs...)
     options = Dict{String, Any}("model" => model)
     system !== nothing && (options["system"] = system)
@@ -234,6 +242,7 @@ function completion(prompt::AbstractString; model="default", system=nothing, sch
         options[string(key)] = value
     end
     response = senpi_with_bridge_timeout_pause(() -> senpi_completion(string(prompt), options))
+    get(options, "handle", false) === true && return handle(response)
     response isa AbstractDict || return response
     haskey(response, "value") && return response["value"]
     get(response, "text", response)

package/src/kernels/jl/runner.jl

@@ -224,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",
@@ -244,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

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/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);

package/src/kernels/py/host-cell.ts

@@ -0,0 +1,42 @@
+import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+import type { HostCellExecutor } from "../../tool/types.ts";
+
+type HostCellOutcome = Awaited<ReturnType<HostCellExecutor>>;
+
+import type { PendingRun, ResultMessage } from "./kernel-contract.ts";
+import { failedPythonResult } from "./transport.ts";
+
+export function runHostCell(
+	pending: PendingRun,
+	host: HostCellExecutor,
+	io: { readonly emit: (message: KernelToHostMessage) => void; readonly settle: (result: ResultMessage) => void },
+): void {
+	const abort = new AbortController();
+	pending.hostAbort = abort;
+	const cellId = pending.input.cellId;
+	let finished = false;
+	// Output from an executor that was aborted, or after its outcome, belongs to no cell.
+	const emit = (message: KernelToHostMessage): void => {
+		if (!finished && !abort.signal.aborted) io.emit(message);
+	};
+	// Calling the executor inside a promise keeps a synchronous throw in this cell instead of failing the queue.
+	const done = new Promise<HostCellOutcome>((resolve) => resolve(host({ signal: abort.signal, emit }))).then(
+		(outcome): ResultMessage =>
+			outcome.ok
+				? {
+						type: "result",
+						cellId,
+						ok: true,
+						durationMs: 0,
+						...(outcome.valueRepr === undefined ? {} : { valueRepr: outcome.valueRepr }),
+					}
+				: { type: "result", cellId, ok: false, error: outcome.error, durationMs: 0 },
+		(error: unknown): ResultMessage =>
+			failedPythonResult(cellId, error instanceof Error ? error.message : String(error)),
+	);
+	pending.hostDone = done;
+	void done.then((result) => {
+		finished = true;
+		if (!abort.signal.aborted) io.settle(result);
+	});
+}

package/src/kernels/py/kernel-contract.ts

@@ -39,4 +39,6 @@ export interface PendingRun {
 	interruptReason?: string;
 	/** Set while an interrupt outcome is pending; resolved once the kernel knows whether state survived. */
 	resolveStateRetained?: (retained: boolean) => void;
+	hostAbort?: AbortController;
+	hostDone?: Promise<ResultMessage>;
 }

package/src/kernels/py/kernel.ts

@@ -5,6 +5,7 @@ import { rejectKernelToolsUnavailable } from "../kernel-tools-unavailable.ts";
 import { describeExit } from "../shared/kernel-death.ts";
 import { KernelMemoryHost } from "../shared/kernel-memory-host.ts";
 import { KernelPreludeTracker } from "../shared/kernel-prelude-plan.ts";
+import { runHostCell } from "./host-cell.ts";
 import type { PendingRun, PythonKernelRunOptions, PythonKernelStartOptions, ResultMessage } from "./kernel-contract.ts";
 import { pythonStartupHangGuardMs } from "./startup.ts";
 import { failedPythonResult, PythonKernelTransport } from "./transport.ts";
@@ -104,6 +105,11 @@ export class PythonKernel {
 			}
 		}
 		const active = this.#active;
+		if (active?.hostAbort && active.interruptReason === undefined) {
+			active.interruptReason = reason;
+			void this.#stopHostEntry(active, failedPythonResult(active.input.cellId, "Eval interrupted"));
+			return { stateRetained: Promise.resolve(true) };
+		}
 		const transport = this.#transport;
 		if (!active || !transport || active.interruptReason !== undefined)
 			return { stateRetained: Promise.resolve(true) };
@@ -201,6 +207,14 @@ export class PythonKernel {
 		const timeoutMs = pending.input.timeoutMs;
 		if (timeoutMs !== undefined)
 			pending.timeoutTimer = setTimeout(() => this.#timeoutRun(pending, timeoutMs), timeoutMs);
+		const host = pending.input.host;
+		if (host !== undefined) {
+			runHostCell(pending, host, {
+				emit: (message) => (pending.input.onMessage ?? this.#options.onMessage)?.(message),
+				settle: (result) => this.#settleRun(pending, result),
+			});
+			return;
+		}
 		try {
 			this.#transport?.run({
 				...pending.input,
@@ -219,11 +233,40 @@ export class PythonKernel {
 
 	#timeoutRun(pending: PendingRun, timeoutMs: number): void {
 		if (this.#active !== pending) return;
+		const timedOut = failedPythonResult(pending.input.cellId, `Python kernel timed out after ${timeoutMs}ms`);
+		if (pending.hostAbort) {
+			void this.#stopHostEntry(pending, timedOut);
+			return;
+		}
 		if (this.#transport) void this.#beginRetirement(this.#transport).catch(() => undefined);
-		this.#settleRun(
-			pending,
-			failedPythonResult(pending.input.cellId, `Python kernel timed out after ${timeoutMs}ms`),
-		);
+		this.#settleRun(pending, timedOut);
+	}
+
+	/**
+	 * Aborts a running host entry and settles it only once its executor has stopped (or after the same bound the
+	 * interpreter gets before escalation), so the next queue entry never overlaps the aborted host work. An
+	 * executor that finished successfully despite the abort reports that outcome: its work did commit.
+	 */
+	async #stopHostEntry(pending: PendingRun, stopped: ResultMessage): Promise<void> {
+		pending.hostAbort?.abort();
+		const done = pending.hostDone;
+		let bound: ReturnType<typeof setTimeout> | undefined;
+		const outcome =
+			done === undefined
+				? undefined
+				: await Promise.race([
+						done,
+						new Promise<undefined>((resolve) => {
+							bound = setTimeout(() => resolve(undefined), interruptEscalationMs);
+						}),
+					]);
+		if (bound !== undefined) clearTimeout(bound);
+		if (outcome?.ok === true) {
+			pending.interruptReason = undefined;
+			this.#settleRun(pending, outcome);
+			return;
+		}
+		this.#settleRun(pending, stopped);
 	}
 
 	async #ensureStarted(): Promise<void> {
@@ -354,6 +397,7 @@ export class PythonKernel {
 	}
 
 	#removePending(pending: PendingRun): void {
+		pending.hostAbort?.abort();
 		if (pending.timeoutTimer) clearTimeout(pending.timeoutTimer);
 		if (pending.escalationTimer) clearTimeout(pending.escalationTimer);
 		pending.timeoutTimer = null;