@code-yeongyu/senpi-codemode 2026.10.5 → 2026.10.7

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;

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"
 
@@ -354,7 +360,15 @@ def write(path: str | Path, content: str) -> Path:
     return target
 
 
-def bridge_post(path: str, payload: dict[str, Any]) -> Any:
+# 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], *, 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):
@@ -369,7 +383,7 @@ def bridge_post(path: str, payload: dict[str, Any]) -> Any:
     emit_status(TIMEOUT_PAUSE_OP, force=True)
     try:
         try:
-            with urllib.request.urlopen(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()
@@ -495,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:
@@ -611,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:
@@ -992,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,
@@ -1400,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":
@@ -1478,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/kernel.ts

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { SessionEnvironment } from "../session-env.ts";
 import type { KernelLifecycle } from "../shared/kernel-death.ts";
+import { readProcessGroupCpuTime } from "../shared/process-group-cpu.ts";
 import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import { SubprocessKernel, type SubprocessKernelMemory, type SubprocessSpawn } from "../shared/subprocess-kernel.ts";
 
@@ -14,7 +15,7 @@ export interface RubyKernelStartOptions extends KernelLifecycle {
 	readonly command?: string;
 	readonly spawn?: SubprocessSpawn;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
-	/** Ceiling-only memory management (no notice or globals list: the runner reports no memory). */
+	/** Memory management: the runner reports its largest globals and the host reads the interpreter footprint for the ceiling. */
 	readonly memory?: SubprocessKernelMemory;
 }
 
@@ -43,6 +44,7 @@ export class RubyKernel extends SubprocessKernel {
 			onMessage: options.onMessage,
 			memory: options.memory && { language: "rb", ...options.memory },
 			onDeath: options.onDeath,
+			startup: { label: "Ruby", readGroupCpuTime: readProcessGroupCpuTime },
 		});
 	}
 }

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")