@code-yeongyu/senpi-codemode 2026.10.6 → 2026.10.7

package/src/kernels/py/prelude.py

@@ -18,6 +18,7 @@ import inspect
 import io
 import json
 import locale
+import math
 import os
 import re
 import signal
@@ -48,6 +49,11 @@ EMIT_LOCK = Lock()
 RESERVED_AGENT_TOOL = "__agent__"
 RESERVED_OUTPUT_TOOL = "__output__"
 RESERVED_SCHEMA_TOOL = "__schema__"
+RESERVED_WAIT_TOOL = "__wait__"
+RESERVED_HANDLE_STATUS_TOOL = "__handle_status__"
+RESERVED_HANDLE_OUTPUT_TOOL = "__handle_output__"
+RESERVED_HANDLE_SEND_TOOL = "__handle_send__"
+RESERVED_HANDLE_CANCEL_TOOL = "__handle_cancel__"
 TIMEOUT_PAUSE_OP = "timeout-pause"
 TIMEOUT_RESUME_OP = "timeout-resume"
 
@@ -357,9 +363,12 @@ def write(path: str | Path, content: str) -> Path:
 # The bridge is a loopback call: urllib's default opener would route it through a configured proxy
 # (the environment everywhere, the registry on Windows), which a 127.0.0.1 request must never use.
 _BRIDGE_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+# Ordinary bridge calls keep this socket timeout; only `__wait__` passes its own bound (see `_bridge_wait_post`).
+_BRIDGE_SOCKET_TIMEOUT_SECONDS = 60
+_WAIT_SOCKET_GRACE_SECONDS = 30
 
 
-def bridge_post(path: str, payload: dict[str, Any]) -> Any:
+def bridge_post(path: str, payload: dict[str, Any], *, socket_timeout: float | None = _BRIDGE_SOCKET_TIMEOUT_SECONDS) -> Any:
     port = CONNECTION.get("port")
     token = CONNECTION.get("token")
     if not isinstance(port, int) or not isinstance(token, str):
@@ -374,7 +383,7 @@ def bridge_post(path: str, payload: dict[str, Any]) -> Any:
     emit_status(TIMEOUT_PAUSE_OP, force=True)
     try:
         try:
-            with _BRIDGE_OPENER.open(request, timeout=60) as response:
+            with _BRIDGE_OPENER.open(request, timeout=socket_timeout) as response:
                 response_data = response.read()
         except urllib.error.HTTPError as exc:
             response_data = exc.read()
@@ -500,6 +509,8 @@ def completion(
     if schema is not None:
         options["schema"] = schema
     response = bridge_post("/completion", {"prompt": prompt, "opts": options})
+    if options.get("handle") is True:
+        return handle(response)
     if not isinstance(response, dict):
         return response
     if "value" in response:
@@ -616,6 +627,129 @@ def agent(
     return node
 
 
+_HANDLE_KINDS = ("agent", "completion", "workpool")
+_WAIT_MODES = ("all", "any", "settled")
+_HANDLE_USAGE = (
+    "handle() expects an agent(..., handle=True) record, a workpool, a completion handle, "
+    "or a saved {kind, id, run_epoch} reference"
+)
+
+
+def _handle_ref(value: Any) -> dict[str, Any]:
+    if isinstance(value, HandleView):
+        return dict(value.ref)
+    if isinstance(value, Workpool):
+        return {"kind": "workpool", "id": value.pool_id, "run_epoch": 0}
+    if not isinstance(value, dict):
+        raise PreludeTypeError(_HANDLE_USAGE)
+    if isinstance(value.get("pool_id"), str):
+        return {"kind": "workpool", "id": value["pool_id"], "run_epoch": 0}
+    kind = value.get("kind")
+    if kind not in _HANDLE_KINDS:
+        handle_uri = value.get("handle")
+        scheme = handle_uri.split("://", 1)[0] if isinstance(handle_uri, str) else None
+        kind = scheme if scheme in _HANDLE_KINDS else None
+    identity = value.get("id", value.get("task_id"))
+    if kind is None or not isinstance(identity, str) or not identity:
+        raise PreludeTypeError(_HANDLE_USAGE)
+    run_epoch = value.get("run_epoch", 0 if kind == "workpool" else None)
+    if isinstance(run_epoch, bool) or not isinstance(run_epoch, int) or run_epoch < 0:
+        raise PreludeTypeError(f"{_HANDLE_USAGE}; run_epoch must be a non-negative integer")
+    return {"kind": kind, "id": identity, "run_epoch": run_epoch}
+
+
+def _handle_call(tool_name: str, args: dict[str, Any]) -> Any:
+    return bridge_post("/call", {"callId": f"py-{uuid.uuid4()}", "toolName": tool_name, "args": args})
+
+
+def _bridge_wait_post(args: dict[str, Any], timeout: float | None) -> Any:
+    # A long-lived request: no 60 s socket cap. An explicit timeout bounds it (plus grace for the host's
+    # reply); without one only the cell's own end does: SIGINT from the host (cancel, the cell's hard limit,
+    # which the eval timeout can raise) interrupts the blocking read, which closes the socket and so the
+    # host-side subscription.
+    socket_timeout = None if timeout is None else float(timeout) + _WAIT_SOCKET_GRACE_SECONDS
+    return bridge_post(
+        "/call",
+        {"callId": f"py-{uuid.uuid4()}", "toolName": RESERVED_WAIT_TOOL, "args": args},
+        socket_timeout=socket_timeout,
+    )
+
+
+def wait(handles: Any, *, timeout: float | None = None, mode: str = "all") -> Any:
+    """Block until the handles settle; never cancels work. See tool_schema("eval:wait")."""
+    if handles is None:
+        items: list[Any] = []
+    elif isinstance(handles, (list, tuple)):
+        items = list(handles)
+    else:
+        items = [handles]
+    if timeout is not None and (
+        isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not math.isfinite(timeout) or timeout < 0
+    ):
+        raise PreludeValueError("wait() timeout must be a finite number of seconds >= 0")
+    if mode not in _WAIT_MODES:
+        raise PreludeValueError("wait() mode must be 'all', 'any' or 'settled'")
+    args: dict[str, Any] = {"refs": [_handle_ref(item) for item in items], "mode": mode}
+    if timeout is not None:
+        args["timeout"] = timeout
+    return _bridge_wait_post(args, timeout)
+
+
+class HandleControl:
+    """Epoch-fenced control over one handle; every call goes through the host capability."""
+
+    __slots__ = ("_ref",)
+
+    def __init__(self, ref: dict[str, Any]) -> None:
+        self._ref = dict(ref)
+
+    def __repr__(self) -> str:
+        return f"<handle.control {self._ref['kind']}://{self._ref['id']}@{self._ref['run_epoch']}>"
+
+    def status(self) -> Any:
+        return _handle_call(RESERVED_HANDLE_STATUS_TOOL, {"ref": self._ref})
+
+    def output(self, format: str = "raw", offset: int | None = None, limit: int | None = None) -> Any:
+        args: dict[str, Any] = {"ref": self._ref, "format": format}
+        if offset is not None:
+            args["offset"] = offset
+        if limit is not None:
+            args["limit"] = limit
+        return _handle_call(RESERVED_HANDLE_OUTPUT_TOOL, args)
+
+    def send(self, message: str) -> Any:
+        return _handle_call(RESERVED_HANDLE_SEND_TOOL, {"ref": self._ref, "message": str(message)})
+
+    def cancel(self) -> Any:
+        return _handle_call(RESERVED_HANDLE_CANCEL_TOOL, {"ref": self._ref})
+
+    def wait(self, timeout: float | None = None) -> Any:
+        return wait([self._ref], timeout=timeout, mode="all")[0]
+
+
+class HandleView(dict):
+    """The legacy record's fields as a dict, plus `control` and `ref` as attributes (never keys)."""
+
+    __slots__ = ("control", "ref")
+
+    def __init__(self, fields: dict[str, Any], ref: dict[str, Any]) -> None:
+        super().__init__(fields)
+        self.ref = dict(ref)
+        self.control = HandleControl(ref)
+
+
+def handle(value: Any) -> HandleView:
+    """Rich view of an agent record, workpool, completion handle or saved reference; see tool_schema("eval:helpers")."""
+    ref = _handle_ref(value)
+    fields: dict[str, Any] = {}
+    if isinstance(value, dict):
+        fields.update({key: item for key, item in value.items() if not callable(item)})
+    fields.setdefault("id", ref["id"])
+    fields.setdefault("run_epoch", ref["run_epoch"])
+    fields.setdefault("handle", f"{ref['kind']}://{ref['id']}")
+    return HandleView(fields, ref)
+
+
 def _pool_map(items: Iterable[Any], function: Callable[[Any], Any]) -> list[Any]:
     values = list(items)
     if not values:
@@ -997,6 +1131,8 @@ USER_NS.update(
         "workpool": workpool,
         "output": output,
         "tool_schema": tool_schema,
+        "wait": wait,
+        "handle": handle,
         "__senpi_magic": _magic,
         "__senpi_magic_cell": _magic_cell,
         "__senpi_shell": _shell,
@@ -1405,7 +1541,7 @@ def elapsed(start: float) -> int:
     return max(0, int((time.monotonic() - start) * 1000))
 
 
-def handle(message: dict[str, Any]) -> bool:
+def _handle_message(message: dict[str, Any]) -> bool:
     global CONNECTION
     message_type = message.get("type")
     if message_type == "init":
@@ -1483,7 +1619,7 @@ def main() -> None:
     host_closed = False
     for raw in sys.stdin:
         try:
-            if not handle(json.loads(raw)):
+            if not _handle_message(json.loads(raw)):
                 host_closed = True
                 break
         except BaseException as exc:  # noqa: BROAD_EXCEPT_OK — process boundary serializes malformed input and interrupts.

package/src/kernels/rb/handles.rb

@@ -0,0 +1,97 @@
+# In-cell wait()/handle() over the host's handle capability. Mirrors src/bridge/reserved.ts.
+SENPI_RESERVED_WAIT_TOOL = "__wait__"
+SENPI_RESERVED_HANDLE_STATUS_TOOL = "__handle_status__"
+SENPI_RESERVED_HANDLE_OUTPUT_TOOL = "__handle_output__"
+SENPI_RESERVED_HANDLE_SEND_TOOL = "__handle_send__"
+SENPI_RESERVED_HANDLE_CANCEL_TOOL = "__handle_cancel__"
+SENPI_HANDLE_KINDS = ["agent", "completion", "workpool"].freeze
+SENPI_WAIT_MODES = ["all", "any", "settled"].freeze
+SENPI_WAIT_SOCKET_GRACE_SECONDS = 30
+SENPI_HANDLE_USAGE = "handle() expects an agent(..., handle: true) record, a workpool, a completion handle, or a saved {kind, id, run_epoch} reference"
+
+def __senpi_handle_ref(value)
+  return value.ref.dup if value.respond_to?(:ref) && value.respond_to?(:control)
+  return { "kind" => "workpool", "id" => value.pool_id, "run_epoch" => 0 } if value.is_a?(SenpiWorkpool)
+  raise TypeError, SENPI_HANDLE_USAGE unless value.is_a?(Hash)
+  record = value.transform_keys(&:to_s)
+  return { "kind" => "workpool", "id" => record["pool_id"], "run_epoch" => 0 } if record["pool_id"].is_a?(String)
+  kind = record["kind"]
+  unless SENPI_HANDLE_KINDS.include?(kind)
+    scheme = record["handle"].is_a?(String) ? record["handle"].split("://", 2).first : nil
+    kind = SENPI_HANDLE_KINDS.include?(scheme) ? scheme : nil
+  end
+  identity = record.fetch("id", record["task_id"])
+  raise TypeError, SENPI_HANDLE_USAGE if kind.nil? || !identity.is_a?(String) || identity.empty?
+  run_epoch = record.fetch("run_epoch", kind == "workpool" ? 0 : nil)
+  raise TypeError, "#{SENPI_HANDLE_USAGE}; run_epoch must be a non-negative integer" unless run_epoch.is_a?(Integer) && run_epoch >= 0
+  { "kind" => kind, "id" => identity, "run_epoch" => run_epoch }
+end
+
+# A long-lived request: ordinary calls keep their 60 s read timeout; this one is bounded by the explicit
+# timeout (plus grace for the host's reply) or else only by the cell's own end: SIGINT from the host (cancel,
+# the cell's hard limit) interrupts the read, which closes the socket and the host-side subscription.
+def __senpi_wait_post(args, timeout)
+  read_timeout = timeout.nil? ? nil : timeout.to_f + SENPI_WAIT_SOCKET_GRACE_SECONDS
+  payload = { "callId" => "rb-#{Process.pid}-#{rand(1_000_000)}", "toolName" => SENPI_RESERVED_WAIT_TOOL, "args" => args }
+  __senpi_bridge_request("/call", payload, read_timeout: read_timeout)
+end
+
+def __senpi_wait(handles, timeout: nil, mode: "all")
+  items = handles.nil? ? [] : handles.is_a?(Array) ? handles : [handles]
+  unless timeout.nil? || (timeout.is_a?(Numeric) && timeout.to_f.finite? && timeout >= 0)
+    raise ArgumentError, "wait() timeout must be a finite number of seconds >= 0"
+  end
+  raise ArgumentError, "wait() mode must be 'all', 'any' or 'settled'" unless SENPI_WAIT_MODES.include?(mode.to_s)
+  args = { "refs" => items.map { |item| __senpi_handle_ref(item) }, "mode" => mode.to_s }
+  args["timeout"] = timeout unless timeout.nil?
+  __senpi_wait_post(args, timeout)
+end
+
+class SenpiHandleControl
+  def initialize(ref)
+    @ref = ref.dup.freeze
+    freeze
+  end
+
+  def status
+    __senpi_call_tool(SENPI_RESERVED_HANDLE_STATUS_TOOL, { "ref" => @ref })
+  end
+
+  def output(format: "raw", offset: nil, limit: nil)
+    args = { "ref" => @ref, "format" => format }
+    args["offset"] = offset unless offset.nil?
+    args["limit"] = limit unless limit.nil?
+    __senpi_call_tool(SENPI_RESERVED_HANDLE_OUTPUT_TOOL, args)
+  end
+
+  def send_message(message)
+    __senpi_call_tool(SENPI_RESERVED_HANDLE_SEND_TOOL, { "ref" => @ref, "message" => message.to_s })
+  end
+  # Deliberately shadows Object#send so control.send(msg) matches the other languages; use __send__ for reflection.
+  alias send send_message
+
+  def cancel
+    __senpi_call_tool(SENPI_RESERVED_HANDLE_CANCEL_TOOL, { "ref" => @ref })
+  end
+
+  def wait(timeout: nil)
+    __senpi_wait([@ref], timeout: timeout, mode: "all")[0]
+  end
+
+  def inspect
+    "#<handle.control #{@ref["kind"]}://#{@ref["id"]}@#{@ref["run_epoch"]}>"
+  end
+end
+
+# The legacy record's fields as a Hash copy; `control` and `ref` are singleton methods, never keys.
+def __senpi_handle_view(value)
+  ref = __senpi_handle_ref(value)
+  view = value.is_a?(Hash) ? value.transform_keys(&:to_s).reject { |_key, item| item.respond_to?(:call) } : {}
+  view["id"] ||= ref["id"]
+  view["run_epoch"] ||= ref["run_epoch"]
+  view["handle"] ||= "#{ref["kind"]}://#{ref["id"]}"
+  control = SenpiHandleControl.new(ref)
+  view.define_singleton_method(:control) { control }
+  view.define_singleton_method(:ref) { ref.dup }
+  view
+end

package/src/kernels/rb/paths.rb

@@ -0,0 +1,37 @@
+# Path resolution (local:// roots) and display payload shaping for the Ruby prelude helpers.
+def __senpi_resolve_path(value)
+  raw = value.to_s
+  match = SENPI_INTERNAL_URL.match(raw)
+  return File.expand_path(raw) unless match
+
+  scheme = match[1].downcase
+  roots = $__senpi_connection.is_a?(Hash) ? $__senpi_connection["localRoots"] : nil
+  root = roots[scheme] if roots.is_a?(Hash)
+  raise "Protocol paths are not supported by this helper: #{raw}" unless root.is_a?(String) && !root.empty?
+
+  relative = URI::DEFAULT_PARSER.unescape(match[2].tr("\\", "/"))
+  root_path = File.expand_path(root)
+  return root_path if relative.empty?
+  if relative.start_with?("/") || relative.split("/").include?("..")
+    raise "Unsafe #{scheme}:// path (absolute or traversal): #{raw}"
+  end
+
+  resolved = File.expand_path(relative, root_path)
+  unless resolved == root_path || resolved.start_with?(root_path + File::SEPARATOR)
+    raise "#{scheme}:// path escapes its root: #{raw}"
+  end
+  resolved
+end
+
+def __senpi_display_payload(value)
+  if value.is_a?(Hash)
+    kind = value["type"] || value[:type]
+    text_value = value["text"] || value[:text]
+    return ["text/markdown", text_value.to_s] if kind == "markdown" && !text_value.nil?
+    return ["image/png", value["data"].to_s] if kind == "image" && value["mimeType"] == "image/png"
+    return ["image/jpeg", value["data"].to_s] if kind == "image" && value["mimeType"] == "image/jpeg"
+    return ["application/json", JSON.generate(value)]
+  end
+  return ["application/json", JSON.generate(value)] if value.is_a?(Array)
+  ["text/plain", value.to_s]
+end

package/src/kernels/rb/prelude.rb

@@ -19,42 +19,7 @@ def __senpi_emit_status(op, fields = {}, force: false)
   __senpi_emit({ "type" => "status", "event" => { "op" => op }.merge(fields.transform_keys(&:to_s)) })
 end
 
-def __senpi_resolve_path(value)
-  raw = value.to_s
-  match = SENPI_INTERNAL_URL.match(raw)
-  return File.expand_path(raw) unless match
-
-  scheme = match[1].downcase
-  roots = $__senpi_connection.is_a?(Hash) ? $__senpi_connection["localRoots"] : nil
-  root = roots[scheme] if roots.is_a?(Hash)
-  raise "Protocol paths are not supported by this helper: #{raw}" unless root.is_a?(String) && !root.empty?
-
-  relative = URI::DEFAULT_PARSER.unescape(match[2].tr("\\", "/"))
-  root_path = File.expand_path(root)
-  return root_path if relative.empty?
-  if relative.start_with?("/") || relative.split("/").include?("..")
-    raise "Unsafe #{scheme}:// path (absolute or traversal): #{raw}"
-  end
-
-  resolved = File.expand_path(relative, root_path)
-  unless resolved == root_path || resolved.start_with?(root_path + File::SEPARATOR)
-    raise "#{scheme}:// path escapes its root: #{raw}"
-  end
-  resolved
-end
-
-def __senpi_display_payload(value)
-  if value.is_a?(Hash)
-    kind = value["type"] || value[:type]
-    text_value = value["text"] || value[:text]
-    return ["text/markdown", text_value.to_s] if kind == "markdown" && !text_value.nil?
-    return ["image/png", value["data"].to_s] if kind == "image" && value["mimeType"] == "image/png"
-    return ["image/jpeg", value["data"].to_s] if kind == "image" && value["mimeType"] == "image/jpeg"
-    return ["application/json", JSON.generate(value)]
-  end
-  return ["application/json", JSON.generate(value)] if value.is_a?(Array)
-  ["text/plain", value.to_s]
-end
+require_relative "paths"
 
 def display(value)
   mime_type, payload = __senpi_display_payload(value)
@@ -118,7 +83,7 @@ def env(key = nil, value = nil)
   resolved
 end
 
-def __senpi_bridge_request(path, payload)
+def __senpi_bridge_request(path, payload, read_timeout: 60)
   connection = $__senpi_connection
   raise "Ruby tool bridge is not initialized" unless connection.is_a?(Hash)
   port = connection["port"]
@@ -132,7 +97,7 @@ def __senpi_bridge_request(path, payload)
   request.body = JSON.generate(payload)
   __senpi_emit_status("timeout-pause", force: true)
   begin
-    response = Net::HTTP.start(uri.hostname, uri.port, open_timeout: 10, read_timeout: 60) { |http| http.request(request) }
+    response = Net::HTTP.start(uri.hostname, uri.port, open_timeout: 10, read_timeout: read_timeout) { |http| http.request(request) }
   ensure
     __senpi_emit_status("timeout-resume", force: true)
   end
@@ -187,12 +152,24 @@ def tool
 end
 
 require_relative "workpool"
+require_relative "handles"
+
+# Block until the handles settle; never cancels work. See tool_schema("eval:wait").
+def wait(handles, timeout: nil, mode: "all")
+  __senpi_wait(handles, timeout: timeout, mode: mode)
+end
+
+# Rich view of an agent record, workpool, completion handle or saved reference; see tool_schema("eval:helpers").
+def handle(value)
+  __senpi_handle_view(value)
+end
 
 def completion(prompt, model: "default", system: nil, schema: nil, **kwargs)
   options = { "model" => model }.merge(kwargs.transform_keys(&:to_s))
   options["system"] = system unless system.nil?
   options["schema"] = schema unless schema.nil?
   result = __senpi_bridge_request("/completion", { "prompt" => prompt.to_s, "opts" => options })
+  return handle(result) if options["handle"] == true
   return result unless result.is_a?(Hash)
   return result["value"] if result.key?("value")
 

package/src/kernels/rb/runner.rb

@@ -165,27 +165,27 @@ class SenpiGlobalSizer
     return ObjectSpace.memsize_of(value) if Integer === value || Float === value
     return 0 if @seen.key?(value)
     @seen[value] = true
-    return SENPI_SIZER_OBJECT + SENPI_STRING_BYTESIZE.bind_call(value) if String === value
+    return SENPI_SIZER_OBJECT + SENPI_STRING_BYTESIZE.bind(value).call() if String === value
     if depth >= SENPI_SIZER_MAX_DEPTH || @nodes >= SENPI_SIZER_NODE_BUDGET
       @approximate = true
       return ObjectSpace.memsize_of(value)
     end
     if Array === value
-      length = SENPI_ARRAY_SIZE.bind_call(value)
-      SENPI_SIZER_OBJECT + length * SENPI_SIZER_POINTER + sampled(length, depth) { |index| SENPI_ARRAY_AT.bind_call(value, index) }
+      length = SENPI_ARRAY_SIZE.bind(value).call()
+      SENPI_SIZER_OBJECT + length * SENPI_SIZER_POINTER + sampled(length, depth) { |index| SENPI_ARRAY_AT.bind(value).call(index) }
     elsif Hash === value
       hash_size(value, depth)
     else
-      ivars = SENPI_IVARS.bind_call(value)
-      ObjectSpace.memsize_of(value) + sampled(ivars.length, depth) { |index| SENPI_IVAR_GET.bind_call(value, ivars[index]) }
+      ivars = SENPI_IVARS.bind(value).call()
+      ObjectSpace.memsize_of(value) + sampled(ivars.length, depth) { |index| SENPI_IVAR_GET.bind(value).call(ivars[index]) }
     end
   end
 
   def hash_size(hash, depth)
-    count = SENPI_HASH_SIZE.bind_call(hash)
+    count = SENPI_HASH_SIZE.bind(hash).call()
     taken = 0
     total = 0
-    SENPI_HASH_EACH.bind_call(hash) do |key, item|
+    SENPI_HASH_EACH.bind(hash).call() do |key, item|
       total += size(key, depth + 1) + size(item, depth + 1)
       taken += 1
       break if taken >= SENPI_SIZER_SAMPLE

package/src/tool/cell-handler.ts

@@ -14,6 +14,7 @@ import { appendSchemaHint } from "../bridges/schema-hint.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import { handleCompletionToolCall } from "../completion/tool-bridge.ts";
 import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { KernelToolsCapability } from "../kernels/js/kernel-tools-types.ts";
 import {
 	boundToolCallArgs,
@@ -24,6 +25,7 @@ import {
 	type ToolCallCapture,
 	toolCallResultPreview,
 } from "./call-capture.ts";
+import { completionCallOptions, reservedDispatchContext } from "./cell-reserved-dispatch.ts";
 import { CellResultBuilder, type CellState } from "./cell-runtime.ts";
 import { type EvalImageResizer, marshalToolResult, toolResultIsError } from "./image.ts";
 import { upsertStatusEvent } from "./status-events.ts";
@@ -48,6 +50,10 @@ export interface CellBridgeRuntime {
 	readonly imageResizer?: EvalImageResizer;
 	/** This cell's live kernel-tool capability; only a JS kernel has one (#1754). */
 	readonly kernelTools?: KernelToolsCapability;
+	/** The session generation's handle registry behind `wait()` / `handle()` / completion handles. */
+	readonly handles?: HandleRegistry;
+	/** Absolute wall-clock deadline of this cell; a completion handle it creates is bounded by it. */
+	readonly hardDeadlineMs?: number;
 }
 
 export class CellHandler {
@@ -159,17 +165,12 @@ export class CellHandler {
 			await this.#deliverToolReply(
 				message,
 				async () => ({
-					value: await runReservedTool(message.toolName, {
-						callId: message.callId,
-						args: message.args,
-						executeTool: this.#runtime.executeTool,
-						taskToolName: this.#runtime.settings.taskTools.task,
-						taskOutputToolName: this.#runtime.settings.taskTools.output,
-						listTools: this.#runtime.listTools,
-						signal: this.#state.signal,
-						emitStatus: (event) => this.#recordStatus(event),
-						marshalToolResult,
-					}),
+					value: await runReservedTool(
+						message.toolName,
+						reservedDispatchContext(message, this.#runtime, this.#state.signal, (event) =>
+							this.#recordStatus(event),
+						),
+					),
 					toolCallOk: true,
 				}),
 				capture,
@@ -177,13 +178,15 @@ export class CellHandler {
 			return;
 		}
 		if (message.toolName === "completion" && this.#runtime.complete) {
-			const result = await handleCompletionToolCall({
-				message,
-				kernel: this.#kernel,
-				complete: this.#runtime.complete,
-				ctx: this.#runtime.ctx,
-				isActive: () => this.#state.active,
-			});
+			const result = await handleCompletionToolCall(
+				completionCallOptions(
+					message,
+					this.#kernel,
+					this.#runtime,
+					this.#runtime.complete,
+					() => this.#state.active,
+				),
+			);
 			if (!this.#state.active) return;
 			recordToolCall(this.#state.toolCalls, result.ok, capture, undefined, result.ok ? undefined : result.error);
 			this.#resultBuilder.emitUpdate(false);

package/src/tool/cell-reserved-dispatch.ts

@@ -0,0 +1,51 @@
+import type { ExtensionContext } from "@code-yeongyu/senpi";
+import type { KernelToHostMessage } from "../bridge/protocol.ts";
+import type { ReservedDispatchContext } from "../bridges/reserved-dispatch.ts";
+import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
+import type { CompletionToolCallOptions } from "../completion/tool-bridge.ts";
+import type { CellBridgeRuntime } from "./cell-handler.ts";
+import { marshalToolResult } from "./image.ts";
+import type { EvalKernel, EvalStatusEvent } from "./types.ts";
+
+type ToolCallMessage = Extract<KernelToHostMessage, { type: "tool-call" }>;
+
+/** The in-process (JS kernel) dispatch context for a reserved helper call; mirrors the bridge route for py/rb/jl. */
+export function reservedDispatchContext(
+	message: ToolCallMessage,
+	runtime: CellBridgeRuntime,
+	signal: AbortSignal,
+	emitStatus: (event: EvalStatusEvent) => void,
+): ReservedDispatchContext {
+	const host = runtime.ctx.evalHandleHost;
+	return {
+		callId: message.callId,
+		args: message.args,
+		executeTool: runtime.executeTool,
+		taskToolName: runtime.settings.taskTools.task,
+		taskOutputToolName: runtime.settings.taskTools.output,
+		listTools: runtime.listTools,
+		signal,
+		emitStatus,
+		marshalToolResult,
+		...(runtime.handles === undefined ? {} : { handles: runtime.handles }),
+		...(host === undefined ? {} : { evalHandleHost: host }),
+	};
+}
+
+export function completionCallOptions(
+	message: ToolCallMessage,
+	kernel: EvalKernel,
+	runtime: CellBridgeRuntime,
+	complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>,
+	isActive: () => boolean,
+): CompletionToolCallOptions {
+	return {
+		message,
+		kernel,
+		complete,
+		ctx: runtime.ctx,
+		isActive,
+		...(runtime.handles === undefined ? {} : { handles: runtime.handles }),
+		...(runtime.hardDeadlineMs === undefined ? {} : { hardDeadlineMs: runtime.hardDeadlineMs }),
+	};
+}

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

@@ -9,6 +9,7 @@ import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import type { ResolvedCodemodeSettings } from "../config/settings.ts";
 import type { EvalExecutionTracker } from "../extension/session-manager.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { EvalTimeoutFactory } from "./cell-execution.ts";
 import type { EvalDetachedCellManager } from "./detached-cell-manager.ts";
 import type { EvalExecutionEventPayload } from "./eval-execution-event.ts";
@@ -50,6 +51,8 @@ export interface CreateEvalToolOptions {
 	readonly imageResizer?: EvalImageResizer;
 	readonly executionTracker?: EvalExecutionTracker;
 	readonly cellManager?: EvalDetachedCellManager;
+	/** The session generation's handle registry (`wait()`, `handle()`, completion handles); absent before session_start. */
+	readonly handles?: HandleRegistry;
 	readonly onCellSettled?: (payload: EvalExecutionEventPayload) => void;
 	readonly timeoutFactory?: EvalTimeoutFactory;
 	readonly proxyExecutor?: (params: EvalToolInput, signal?: AbortSignal) => Promise<AgentToolResult<EvalToolDetails>>;

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

@@ -224,6 +224,8 @@ async function executeCell(
 					: { artifactPath: join(options.artifactsDir, `eval-${randomUUID()}.log`) }),
 				...(options.imageResizer === undefined ? {} : { imageResizer: options.imageResizer }),
 				...(kernelTools === undefined ? {} : { kernelTools }),
+				...(options.handles === undefined ? {} : { handles: options.handles }),
+				hardDeadlineMs: cell.startedAtMs + cell.hardLimitSeconds * 1_000,
 			});
 			handler = activeHandler;
 			cellManager.bindKernel(

package/src/tool/types.ts

@@ -144,9 +144,24 @@ export function createEvalInputSchema(
 export type EvalKernelResult = Extract<KernelToHostMessage, { type: "result" }>;
 export type EvalToolCallMessage = Extract<KernelToHostMessage, { type: "tool-call" }>;
 
+export type HostCellOutcome =
+	| { readonly ok: true; readonly valueRepr?: string }
+	| { readonly ok: false; readonly error: { readonly message: string; readonly name?: string } };
+
+/**
+ * Work the host runs in the cell's place when the entry reaches the front of the kernel's queue: no code is
+ * sent to the interpreter, and aborting the signal (interrupt, timeout, kernel close) ends it without
+ * restarting the interpreter.
+ */
+export type HostCellExecutor = (context: {
+	readonly signal: AbortSignal;
+	readonly emit: (message: KernelToHostMessage) => void;
+}) => Promise<HostCellOutcome>;
+
 export interface EvalKernelRunInput {
 	readonly cellId: string;
 	readonly code: string;
+	readonly host?: HostCellExecutor;
 	readonly timeoutMs?: number;
 	readonly onStarted?: () => void;
 	readonly onMessage?: (message: KernelToHostMessage) => void;