@code-yeongyu/senpi-codemode 2026.10.5 → 2026.10.7

package/CHANGELOG.md

@@ -12,6 +12,47 @@
 
 ### Removed
 
+## [2026.10.7] - 2026-10-04
+
+### Breaking Changes
+
+### Added
+
+- JavaScript kernel tools: `tool.defined()` lists the defined kernel tools and `tool.undefine(name)` removes one; `tool(fn, { name })` registers a tool under an explicit name while keeping the function's argument order ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- In-cell `wait(handles, {timeout, mode})` barrier and `handle(node | ref | {pool_id})` rich views in all four kernels: `wait` returns values in input order (`all`), the first success (`any`) or every outcome (`settled`), times out with `eval_wait_timeout` without cancelling work, and pauses the run budget while parked; `handle(node).control` offers `status()`, `output()`, `send()`, `cancel()` and `wait()` fenced by owner, id and `run_epoch` through the host's `EvalHandleHost` capability (agent and workpool handles fail with `eval_wait_unavailable` on a host without it); `completion(prompt, {handle: true})` returns an opt-in completion handle bounded by its cell's hard deadline; `tool_schema("eval:helpers")` and `tool_schema("eval:wait")` document the surface and the removed-tool hint for `wait` points at them. The legacy `agent(..., {handle: true})` record, the eval description and the eval input schema are unchanged; the Python runner's dispatcher was renamed `_handle_message` so `handle()` is the helper ([#2687](https://github.com/code-yeongyu/senpi/pull/2687)).
+
+### Changed
+
+### Fixed
+
+- The Ruby kernel's memory notice names the largest globals again on Ruby 2.6 (the sizer used a Ruby 2.7 method) ([#2696](https://github.com/code-yeongyu/senpi/issues/2696)).
+- Eval no longer fails with "codemode session manager is disposed" for the rest of a session after a session switch or fork that another extension cancelled: codemode only tears its kernels down when the session actually ends ([#1706](https://github.com/code-yeongyu/senpi/issues/1706)).
+- A session whose codemode runtime failed to start is recovered by the next eval call (once, with one stderr line naming the failed start); if re-creation also fails, the call says "codemode runtime could not be re-created: <reason>" and how to bring eval back ([#1706](https://github.com/code-yeongyu/senpi/issues/1706)).
+
+### Removed
+
+## [2026.10.6] - 2026-10-04
+
+### Breaking Changes
+
+### Added
+
+- An opt-in `memory.idleParkMinutes` setting (off by default) closes a kernel that had no cell running or queued for that many minutes to give its memory back; the next cell starts a fresh kernel and its result says every earlier global is lost ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- Ruby eval results name their largest globals, and Ruby and Julia kernels now get the same large-memory notice as JavaScript and Python when the interpreter footprint crosses `memory.noticeMb` ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- Julia eval results name their largest globals in that notice ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Changed
+- Kernel tool descriptors may name any eval language (`js`, `py`, `rb`, `jl`), not only `js`; today only JavaScript kernels define tools, so nothing a session sees changes ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Fixed
+- A Ruby or Julia kernel whose start hangs no longer leaves its cells waiting forever: startup fails, naming the stage it stalled in, once the runner has printed nothing, changed no stage and its process group has used no CPU for 30 s, so a slow but busy start (a cold Julia compiling its prelude) is never cut off ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- A `codemode.json` that names a key this version does not know no longer throws away every other setting: the unknown key gets one warning and the rest still apply (known nested objects stay strict). Optional keys for upcoming features (`environments`, `isolation`, `sandbox`, `prompt.advertiseHelpers`, `kernelTools`, `languages.pyInterpreter`) parse with today's behaviour as their defaults ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+- A Python cell's host calls (`tool.*`, `completion`) no longer go through a configured HTTP proxy: the loopback bridge request ignores proxy settings from the environment and, on Windows, the registry, so a proxy can't refuse a `127.0.0.1` call that never needed it ([#2619](https://github.com/code-yeongyu/senpi/issues/2619)).
+- A JavaScript memory report no longer runs user code: array elements are read through their own descriptors (an index accessor is skipped and the estimate marked approximate), and typed arrays, buffers, Blob, Map and Set are sized through the built-in getters, so a subclass that overrides `byteLength` or `size` is never called ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Removed
+
 ## [2026.10.5] - 2026-10-03
 
 ### Breaking Changes

package/README.md

@@ -156,17 +156,31 @@ Configuration is loaded in this order:
 | `outputSink.maxColumns` | `768` | Maximum columns per printed output line; `0` disables column clamping. A cell's return value is never column-clamped (the byte and line budgets still apply). |
 | `statusEvents` | `true` | Enables kernel status-event forwarding and rendering. Each cell retains at most 100 status rows; after overflow, one omitted-count row precedes the latest 99 events. |
 | `memory.gcWatermarkMb` | `256` | JavaScript kernel: a finished cell whose heap reached this size and grew runs a full collection before its result; whenever at least this much stays live, an idle full collection runs about a second after the cell, so dropped globals return their memory without a reset. Python kernel: a finished cell whose process footprint reached this size and grew runs `gc.collect()` (plus glibc `malloc_trim(0)` on Linux) before its result, and while at least this much stays live the next cells collect too (at most 1/20 of the time), so `del rows` returns its memory. `0` disables. Env override: `SENPI_CODEMODE_MEMORY_GC_WATERMARK_MB`. |
-| `memory.noticeMb` | `1024` | JavaScript and Python kernels: when live memory after a collection (JS heap, Python process footprint) reaches this size (first time, or 25% more than at the last notice), the result gets one bracketed notice naming the largest globals and how to drop them (`rows = undefined`, `del rows`), plus `details.memory`. Ruby and Julia get no notice. `0` disables. Env override: `SENPI_CODEMODE_MEMORY_NOTICE_MB`. |
+| `memory.noticeMb` | `1024` | When live memory (JS heap or Python footprint after a collection; Ruby and Julia interpreter footprint read by the host after each cell) reaches this size (first time, or 25% more than at the last notice), the result gets one bracketed notice naming the largest globals and how to drop them (`rows = undefined`, `del rows`, `rows = nil`, `rows = nothing`), plus `details.memory`. `0` disables. Env override: `SENPI_CODEMODE_MEMORY_NOTICE_MB`. |
 | `memory.ceilingMb` | a quarter of physical memory, 2048-8192 | Every kernel (JS heap and Python footprint after a collection; Ruby and Julia interpreter footprint read by the host after each result, without a globals list): when live memory reaches this size, the result says so and the kernel restarts once no cell is running or queued on it; the next result says it was restarted (`details.memory.recycled`). `0` disables. Env override: `SENPI_CODEMODE_MEMORY_CEILING_MB`. Non-zero memory thresholds must satisfy watermark <= notice <= ceiling, otherwise all three use their defaults. |
 | `memory.retainedResultsMb` | `32` | In-memory byte budget (MiB) for the settled cells kept for `peek`/`list`, on top of the 32-cell count cap; the oldest go first and the newest is always kept. `0` keeps only the count cap. Env override: `SENPI_CODEMODE_RETAINED_RESULTS_MB` (a non-negative integer). |
 | `memory.retainedImagesMb` | `256` | Disk budget (MiB) for settled-cell images. Images of settled cells (foreground and detached) are written as base64 files under `<session artifacts>/settled-images/` instead of staying in memory, and `peek` reads them back, so it returns the full result. Beyond the budget the oldest files are deleted first; an evicted cell's files are deleted with it; the directory is removed when the session ends. A `peek` whose image file is gone returns the text plus a one-line note. `0` keeps only the count cap. Env override: `SENPI_CODEMODE_RETAINED_IMAGES_MB` (a non-negative integer). |
+| `memory.idleParkMinutes` | `0` | Off by default. When greater than 0, a kernel with no cell running or queued for this many minutes is closed to give its memory back, and the next cell for that language starts a fresh one; that cell's result says the kernel was restarted and every earlier global is lost. Applies to every language. |
+| `languages.pyInterpreter` | unset | Explicit Python interpreter path. Unset keeps today's `PATH` detection. |
+| `environments.managedRoot` | unset | Root directory for managed per-session environments; unset uses the session's default location. |
+| `environments.autoProvision` | `true` | Lets installs provision a managed environment. `false` makes installs refuse with `environment_installer_unavailable`. |
+| `environments.js.installer` | `auto` | Installer for the managed JavaScript environment: `auto`, `bun` or `npm`. |
+| `environments.py.installer` | `pip` | Installer for the managed Python environment. |
+| `isolation.js` | `worker` | JavaScript kernel isolation: `worker` (today's worker thread) or `process`. Env override: `SENPI_CODEMODE_JS_ISOLATION`. |
+| `sandbox.enabled` | `false` | Allows sandbox cells. While `false` the sandbox option is neither accepted nor advertised. |
+| `sandbox.memoryMb` | `64` | Memory cap (MiB) for a sandbox cell. Env override: `SENPI_CODEMODE_SANDBOX_MEMORY_MB` (a positive integer wins). |
+| `sandbox.timeoutSeconds` | `300` | Time limit for a sandbox cell. |
+| `prompt.advertiseHelpers` | `false` | When `true`, one pointer line to `tool_schema('eval:helpers')` is appended to the eval description. |
+| `kernelTools.enabled` | `true` | Allows cells to define kernel tools (`tool(fn)`, `@tool`). `false` makes them refuse with `tools_unavailable`. |
+
+The `languages.pyInterpreter`, `environments.*`, `isolation.*`, `sandbox.*`, `prompt.*` and `kernelTools.*` keys are accepted and validated now, with the defaults shown, which match today's behaviour. The effect each of those rows describes takes effect when its feature ships; until then, setting a key changes nothing.
 
 `SENPI_CODEMODE_PY`, `SENPI_CODEMODE_JS`, `SENPI_CODEMODE_RB`, and
 `SENPI_CODEMODE_JL` override the corresponding file setting. `1` or `true`
 enables; `0` or `false` disables. Any other value leaves the file setting in
 effect.
 
-Malformed JSON or invalid settings fall back to defaults with a warning.
+A top-level key this version does not know is ignored with one warning naming it, and the rest of the file still applies, so a settings file written for a newer senpi keeps working. Malformed JSON, or an invalid value or an unknown key inside a known setting, falls back to all defaults with a warning.
 The detached-cell environment override uses the run-budget parser: a positive
 base-10 integer wins over the file value; zero, negative, and malformed values
 leave the file value in effect.
@@ -186,8 +200,12 @@ options object and asynchronous helpers are `await`-able.
 | `env(key?, value?)` | Reads all kernel environment values, one value, or sets one value. Includes the session's `PI_*` values (see [Session environment](#session-environment)). |
 | `tool.<name>(args)` | Invokes an active Senpi tool through the normal `pi.executeTool` pipeline and returns `{ text, images?, details?, hasError? }` in every kernel; image blocks arrive as `images[i] = { mimeType, dataBase64 }`. |
 | `tool_schema(name?)` | Returns a tool's parameter schema without calling it; omit `name` to list tool names. |
+| `tool(fn, metadata?)` (js) | Registers a named function as a kernel tool for in-process children. `metadata.name` registers it under that name instead of the function's; arguments are still passed in the function's parameter order. |
+| `tool.defined()` / `tool.undefine(name)` (js) | List the kernel tools this kernel defines (sorted), and remove one (`true` if it existed). A descriptor taken before `undefine` can no longer be invoked. Both names are reserved: a kernel tool can't be registered as `defined` or `undefine` (`reserved_tool_name`), and a host tool with either name is shadowed in the `tool` namespace, so it can't be called from a JavaScript cell. |
 | `completion(prompt, model?, system?, schema?)` | Requests a one-shot host completion; `schema` asks the host to parse structured output. |
 | `agent(prompt, ...)` | Delegates to the configured active `taskTools.task` tool. Supports background handles and structured JSON results. |
+| `wait(handles, timeout?, mode?)` | Blocks the cell until the given handles settle (agent handle records, `handle()` views, completion handles, closed workpools, or saved `{kind, id, run_epoch}` references). `mode` is `all` (values in input order; the first failed, cancelled, or lost handle raises), `any` (`{index, ref, value}` of the first success), or `settled` (one outcome per input slot). `timeout` is wall-clock seconds from entry; on expiry `eval_wait_timeout` is raised and nothing is cancelled. Rides the bridge-call path, so the run budget pauses while parked. Agent and workpool handles need the host's `EvalHandleHost` capability (`eval_wait_unavailable` without it); completion handles always work. Julia extends `Base.wait` for handle views (`wait(handle(node))`). Details: `tool_schema("eval:wait")`. |
+| `handle(node \| ref \| {pool_id})` | Returns a rich view: the legacy record's fields plus a non-enumerable `control` (Python: attribute on a `dict` subclass; Ruby: singleton method) with `status()`, `output(format?, offset?, limit?)`, `send(message)` (agent handles only), `cancel()` (idempotent for that run epoch; never touches a successor run), and `wait(timeout?)`. Every control call is fenced by owner, id, and `run_epoch` inside the task owner (`eval_handle_stale`, `eval_handle_forbidden`). `completion(prompt, handle: true)` returns such a view for a host completion. The `agent(..., handle: true)` record itself is unchanged. Details: `tool_schema("eval:helpers")`. |
 | `workpool(agent, name, mode?)` | Creates a thin adapter over the normal host `workpool` tool; exposes `pool_id`, `push(items)`, `close()`, `inspect()`, and `cancel()`. JS awaits creation and operations. |
 | `output(ids, format?, offset?, limit?)` | Delegates transcript retrieval to the configured active `taskTools.output` tool. |
 | `parallel(thunks)` | Runs thunks through the configured bounded pool while preserving input order. |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.10.5",
+	"version": "2026.10.7",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -32,14 +32,14 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.5",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.7",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.10.5"
+		"@code-yeongyu/senpi": "2026.10.7"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.10.5"
+		"@code-yeongyu/senpi": "2026.10.7"
 	},
 	"keywords": [
 		"senpi",

package/src/bridge/kernel-tools-protocol.ts

@@ -29,7 +29,7 @@ export const kernelToolDescriptorSchema = Type.Object({
 	name: Type.String({ minLength: 1 }),
 	description: Type.String(),
 	input_schema: Type.Unknown(),
-	language: Type.Literal("js"),
+	language: Type.Union([Type.Literal("js"), Type.Literal("py"), Type.Literal("rb"), Type.Literal("jl")]),
 	kernel_generation: Type.Integer({ minimum: 0 }),
 	definition_revision: Type.Integer({ minimum: 1 }),
 });

package/src/bridge/reserved.ts

@@ -5,6 +5,16 @@ export const RESERVED_AGENT_TOOL = "__agent__" as const;
 export const RESERVED_OUTPUT_TOOL = "__output__" as const;
 /** ADAPTATION: senpi resolves tool parameter schemas through a reserved kernel-side tool name. */
 export const RESERVED_SCHEMA_TOOL = "__schema__" as const;
+/** In-cell `wait(handles)` barrier over the host's EvalHandleHost subscription capability. */
+export const RESERVED_WAIT_TOOL = "__wait__" as const;
+/** `handle(node).control.status()`: one epoch-fenced snapshot through the host's `watch`. */
+export const RESERVED_HANDLE_STATUS_TOOL = "__handle_status__" as const;
+/** `handle(node).control.output(opts)`: the transcript of exactly `ref.run_epoch`. */
+export const RESERVED_HANDLE_OUTPUT_TOOL = "__handle_output__" as const;
+/** `handle(node).control.send(message)`: agent handles only, fenced inside the task owner. */
+export const RESERVED_HANDLE_SEND_TOOL = "__handle_send__" as const;
+/** `handle(node).control.cancel()`: idempotent for its epoch; a successor run is never touched. */
+export const RESERVED_HANDLE_CANCEL_TOOL = "__handle_cancel__" as const;
 /** Canonical oh-my-pi eval-timeout pause operation. */
 export const TIMEOUT_PAUSE_OP = "timeout-pause" as const;
 /** Canonical oh-my-pi eval-timeout resume operation. */

package/src/bridges/eval-virtual-schemas.ts

@@ -0,0 +1,79 @@
+import type { EvalSchemaResult } from "./schema-bridge.ts";
+
+/**
+ * Virtual `tool_schema("eval:*")` entries: documentation a cell can read on demand. They are not tools,
+ * never execute anything, and never appear in the ordinary catalog listing, so the eval prompt and the
+ * host tool list stay byte-identical.
+ */
+const handleRefSchema = {
+	type: "object",
+	description:
+		"A saved handle reference. agent(..., {handle: true}) records, handle() views, completion handles and workpools ({pool_id}) are accepted directly.",
+	properties: {
+		kind: { enum: ["agent", "completion", "workpool"] },
+		id: { type: "string" },
+		run_epoch: {
+			type: "integer",
+			minimum: 0,
+			description:
+				"The run this reference is bound to; a resumed task gets a new epoch and the old reference fails with eval_handle_stale.",
+		},
+	},
+	required: ["kind", "id", "run_epoch"],
+} as const;
+
+const waitEntry: EvalSchemaResult = {
+	name: "eval:wait",
+	description: [
+		"wait(handles, {timeout?, mode?}) blocks the cell until the given handles settle (js: await wait(...); py/rb: wait(...); jl: wait(handle(node)) or wait([handle(a), handle(b)])).",
+		'mode "all" (default) returns the successful values in input order and raises the first failed, cancelled or lost handle\'s error; "any" returns {index, ref, value} of the first success or eval_wait_all_rejected; "settled" returns one {status, ref, value|error} outcome per input slot.',
+		"Duplicates keep their slots with one subscription. Empty handles: all/settled -> [], any -> eval_wait_empty.",
+		"timeout is wall-clock seconds from entry (finite, >= 0; 0 = one atomic check; omitted = no wait-specific deadline). On timeout the subscription closes and `eval_wait_timeout: wait() timed out after Ns; k/n handles settled; work was not cancelled` is raised. wait() never cancels work.",
+		"wait() rides the bridge-call path: the cell's run budget pauses while parked, the hard limit never pauses, and a long barrier detaches like any bridge-parked cell. Cancelling the cell closes its subscriptions at once. Task and workpool notifications are neither consumed nor suppressed.",
+		"A workpool must be closed first (eval_pool_open) and succeeds only when every key succeeds (eval_workpool_failed carries the keyed aggregate).",
+		"Agent and workpool handles need the host capability; without it wait() fails with eval_wait_unavailable and never polls task_output. Completion handles always work.",
+	].join("\n"),
+	parameters: {
+		type: "object",
+		properties: {
+			handles: { type: "array", items: handleRefSchema },
+			timeout: { type: "number", minimum: 0, description: "Wall-clock seconds from entry." },
+			mode: { enum: ["all", "any", "settled"], default: "all" },
+		},
+		required: ["handles"],
+	},
+};
+
+const helpersEntry: EvalSchemaResult = {
+	name: "eval:helpers",
+	description: [
+		"Advanced cell helpers (all four languages; js helpers are awaited).",
+		"handle(node | ref | {pool_id}) returns a rich view: the legacy fields plus a non-enumerable `control` (py: attribute, rb: singleton method) with status(), output({format, offset, limit}), send(message) (agent handles only; others eval_handle_operation_unsupported), cancel() (idempotent for that run epoch; never cancels a successor run) and wait({timeout}).",
+		"control.status() goes through the host subscription; control.send/cancel/output are fenced by owner, id and run_epoch inside the task owner (stale -> eval_handle_stale, foreign -> eval_handle_forbidden); control.output() returns only that epoch's transcript. The plain output() helper and task tools are unchanged.",
+		"The legacy agent(..., {handle: true}) record is unchanged: .output stays a string and no enumerable key is added. A saved {kind, id, run_epoch} (or the record itself) can be rebound with handle(ref) in a later cell or after a kernel reset while the owner and run epoch are valid.",
+		"completion(prompt, {handle: true}) (py: handle=True) returns a control handle after preflight validation; provider failures surface in its outcome; its deadline derives from the creating cell's hard deadline. Completion handles are codemode-owned and need no host capability; once the session generation is dropped they fail with eval_handle_stale.",
+		"See tool_schema('eval:wait') for the barrier semantics.",
+	].join("\n"),
+	parameters: {
+		type: "object",
+		properties: {
+			wait: { description: "wait(handles, {timeout?, mode?}) -> values | {index, ref, value} | outcomes[]" },
+			handle: { description: "handle(node | ref | {pool_id}) -> view with .control" },
+			"control.status": { description: "() -> {ref, phase, host_status, revision}" },
+			"control.output": { description: "({format?, offset?, limit?}) -> {ref, text, offset, total, truncated}" },
+			"control.send": { description: "(message) -> snapshot; agent handles only" },
+			"control.cancel": { description: "() -> {ref, cancelled, phase}" },
+			"control.wait": { description: "({timeout?}) -> value" },
+			completion: { description: "completion(prompt, {handle: true}) -> control handle" },
+		},
+	},
+};
+
+const VIRTUAL_ENTRIES: ReadonlyMap<string, EvalSchemaResult> = new Map([
+	[waitEntry.name, waitEntry],
+	[helpersEntry.name, helpersEntry],
+]);
+
+export function virtualEvalSchema(name: string): EvalSchemaResult | undefined {
+	return VIRTUAL_ENTRIES.get(name);
+}

package/src/bridges/handle-bridge.ts

@@ -0,0 +1,72 @@
+import { EvalHandleError, type EvalHandleHost } from "@code-yeongyu/senpi";
+import {
+	RESERVED_HANDLE_CANCEL_TOOL,
+	RESERVED_HANDLE_OUTPUT_TOOL,
+	RESERVED_HANDLE_SEND_TOOL,
+	RESERVED_HANDLE_STATUS_TOOL,
+	RESERVED_WAIT_TOOL,
+} from "../bridge/reserved.ts";
+import { parseOutputArgs, parseRefArgs, parseSendArgs, parseWaitArgs } from "../handles/handle-args.ts";
+import type { HandleBackend, HandleRegistry } from "../handles/handle-registry.ts";
+import { waitForHandles } from "../handles/wait.ts";
+
+export const HANDLE_TOOL_NAMES = [
+	RESERVED_WAIT_TOOL,
+	RESERVED_HANDLE_STATUS_TOOL,
+	RESERVED_HANDLE_OUTPUT_TOOL,
+	RESERVED_HANDLE_SEND_TOOL,
+	RESERVED_HANDLE_CANCEL_TOOL,
+] as const;
+
+export type HandleToolName = (typeof HANDLE_TOOL_NAMES)[number];
+
+export interface HandleBridgeContext {
+	/** The session generation's registry; absent only for the pre-session baseline tool. */
+	readonly registry: HandleRegistry | undefined;
+	/** `ctx.evalHandleHost` at dispatch time; absent on a runtime without a provider. */
+	readonly host: EvalHandleHost | undefined;
+	/** The calling cell's signal: cancelling the cell closes its subscriptions immediately. */
+	readonly signal: AbortSignal | undefined;
+}
+
+export function isHandleToolName(toolName: string): toolName is HandleToolName {
+	return HANDLE_TOOL_NAMES.some((name) => name === toolName);
+}
+
+/** Dispatches the five reserved handle tools; every path is fenced by the registry before any host call. */
+export async function runHandleTool(toolName: HandleToolName, args: unknown, context: HandleBridgeContext) {
+	const registry = context.registry;
+	if (registry === undefined) {
+		throw new EvalHandleError(
+			"eval_wait_unavailable",
+			"wait()/handle() are not supported by this runtime: this session has no handle registry yet",
+		);
+	}
+	const backend: HandleBackend = { host: context.host, signal: context.signal };
+	switch (toolName) {
+		case RESERVED_WAIT_TOOL:
+			return await waitForHandles(parseWaitArgs(args), {
+				watch: (refs) => registry.watch(refs, backend),
+				result: (ref) => registry.result(ref, backend),
+				...(context.signal === undefined ? {} : { signal: context.signal }),
+			});
+		case RESERVED_HANDLE_STATUS_TOOL:
+			return await registry.status(parseRefArgs(args, "control.status()"), backend);
+		case RESERVED_HANDLE_OUTPUT_TOOL: {
+			const { ref, request } = parseOutputArgs(args);
+			return await registry.output(ref, request, backend);
+		}
+		case RESERVED_HANDLE_SEND_TOOL: {
+			const { ref, message } = parseSendArgs(args);
+			return await registry.send(ref, message, backend);
+		}
+		case RESERVED_HANDLE_CANCEL_TOOL:
+			return await registry.cancel(parseRefArgs(args, "control.cancel()"), backend);
+		default:
+			return assertNever(toolName);
+	}
+}
+
+function assertNever(value: never): never {
+	throw new TypeError(`Unsupported handle tool: ${String(value)}`);
+}

package/src/bridges/reserved-dispatch.ts

@@ -1,7 +1,9 @@
-import type { AgentToolResult } from "@code-yeongyu/senpi";
+import type { AgentToolResult, EvalHandleHost } from "@code-yeongyu/senpi";
 import { RESERVED_AGENT_TOOL, RESERVED_OUTPUT_TOOL, RESERVED_SCHEMA_TOOL } from "../bridge/reserved.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { EvalStatusEvent, ExecuteTool } from "../tool/types.ts";
 import { type AgentExecuteTool, runEvalAgent } from "./agent-bridge.ts";
+import { isHandleToolName, runHandleTool } from "./handle-bridge.ts";
 import { type MarshalledToolResult, type OutputExecuteTool, runEvalOutput } from "./output-bridge.ts";
 import { type EvalSchemaToolInfo, runEvalSchema } from "./schema-bridge.ts";
 
@@ -15,6 +17,10 @@ export interface ReservedDispatchContext {
 	readonly signal: AbortSignal | undefined;
 	readonly emitStatus: (event: EvalStatusEvent) => void;
 	readonly marshalToolResult: (result: AgentToolResult<unknown>) => MarshalledToolResult;
+	/** The session generation's handle registry; `wait()`/`handle()` fail with `eval_wait_unavailable` without one. */
+	readonly handles?: HandleRegistry;
+	/** `ctx.evalHandleHost` at dispatch time; agent/workpool refs need it, completion refs do not. */
+	readonly evalHandleHost?: EvalHandleHost;
 }
 
 class SchemaUnavailableError extends Error {
@@ -26,10 +32,22 @@ class SchemaUnavailableError extends Error {
 }
 
 export function isReservedToolName(toolName: string): boolean {
-	return toolName === RESERVED_AGENT_TOOL || toolName === RESERVED_OUTPUT_TOOL || toolName === RESERVED_SCHEMA_TOOL;
+	return (
+		toolName === RESERVED_AGENT_TOOL ||
+		toolName === RESERVED_OUTPUT_TOOL ||
+		toolName === RESERVED_SCHEMA_TOOL ||
+		isHandleToolName(toolName)
+	);
 }
 
 export async function runReservedTool(toolName: string, context: ReservedDispatchContext): Promise<unknown> {
+	if (isHandleToolName(toolName)) {
+		return await runHandleTool(toolName, context.args, {
+			registry: context.handles,
+			host: context.evalHandleHost,
+			signal: context.signal,
+		});
+	}
 	if (toolName === RESERVED_AGENT_TOOL) {
 		return await runEvalAgent(context.args, {
 			callId: context.callId,

package/src/bridges/schema-bridge.ts

@@ -1,6 +1,7 @@
 import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
 import { type Static, Type } from "typebox";
 import { Check, Errors } from "typebox/value";
+import { virtualEvalSchema } from "./eval-virtual-schemas.ts";
 
 const schemaArgsSchema = Type.Object(
 	{ name: Type.Optional(Type.String({ minLength: 1 })) },
@@ -46,6 +47,9 @@ export function runEvalSchema(args: unknown, options: RunEvalSchemaOptions): Eva
 	const tools = options.listTools();
 	if (parsed.name === undefined) return { tools: tools.map((tool) => tool.name) };
 
+	// Documentation-only entries; they are not tools and the listing above stays the ordinary catalog.
+	const virtual = virtualEvalSchema(parsed.name);
+	if (virtual !== undefined) return virtual;
 	const match = tools.find((tool) => tool.name === parsed.name);
 	if (match) return { name: match.name, description: match.description, parameters: match.parameters };
 	throw new SchemaUnknownToolError(parsed.name, nearestNames(parsed.name, tools));

package/src/completion/handle.ts

@@ -0,0 +1,69 @@
+import type { ExtensionContext, HandleRef } from "@code-yeongyu/senpi";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
+import type { CompletionRequest, CompletionResult } from "./handler.ts";
+
+/** What `completion(prompt, {handle: true})` returns: a saved reference every prelude turns into a control view. */
+export interface CompletionHandleRecord {
+	readonly kind: "completion";
+	readonly id: string;
+	readonly run_epoch: number;
+	readonly handle: string;
+}
+
+export interface StartCompletionHandleOptions {
+	readonly registry: HandleRegistry;
+	readonly request: CompletionRequest;
+	readonly complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
+	readonly ctx: ExtensionContext;
+	/** The creating cell's hard deadline (absolute ms); the completion is aborted at it. */
+	readonly deadlineMs: number;
+}
+
+const COMPLETION_TIERS: ReadonlySet<string> = new Set(["smol", "default", "slow"]);
+
+class CompletionHandleArgumentsError extends Error {
+	readonly name = "CompletionHandleArgumentsError";
+	readonly code = "eval_handle_invalid_arguments";
+
+	constructor(detail: string) {
+		super(`eval_handle_invalid_arguments: completion(prompt, {handle: true}) ${detail}`);
+	}
+}
+
+/** True when the completion call opted into a handle (`{handle: true}` in its options). */
+export function wantsCompletionHandle(opts: unknown): boolean {
+	return typeof opts === "object" && opts !== null && "handle" in opts && opts.handle === true;
+}
+
+/**
+ * Preflight-validates the request, then starts the completion in the session registry and returns its
+ * reference at once. Provider failures surface in the handle's outcome, never here.
+ */
+export function startCompletionHandle(options: StartCompletionHandleOptions): CompletionHandleRecord {
+	const request = withoutHandleOption(options.request);
+	if (request.prompt.trim().length === 0) throw new CompletionHandleArgumentsError("needs a non-empty prompt");
+	const tier = request.model ?? tierFromOpts(request.opts);
+	if (tier !== undefined && !COMPLETION_TIERS.has(tier)) {
+		throw new CompletionHandleArgumentsError(`got model tier "${tier}"; expected "smol", "default", or "slow"`);
+	}
+	const ref: HandleRef = options.registry.startCompletion({
+		deadlineMs: options.deadlineMs,
+		run: async (signal) => replyValue(await options.complete(request, { ...options.ctx, signal })),
+	});
+	return { kind: "completion", id: ref.id, run_epoch: ref.run_epoch, handle: `completion://${ref.id}` };
+}
+
+export function replyValue(result: CompletionResult): unknown {
+	return "value" in result ? result.value : result.text;
+}
+
+function tierFromOpts(opts: unknown): string | undefined {
+	if (typeof opts !== "object" || opts === null || !("model" in opts)) return undefined;
+	return typeof opts.model === "string" ? opts.model : undefined;
+}
+
+function withoutHandleOption(request: CompletionRequest): CompletionRequest {
+	if (typeof request.opts !== "object" || request.opts === null || !("handle" in request.opts)) return request;
+	const { handle: _handle, ...opts } = request.opts;
+	return { ...request, opts };
+}

package/src/completion/tool-bridge.ts

@@ -1,6 +1,8 @@
 import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { EvalKernel } from "../tool/types.ts";
+import { replyValue, startCompletionHandle, wantsCompletionHandle } from "./handle.ts";
 import type { CompletionRequest, CompletionResult } from "./handler.ts";
 
 export interface CompletionToolCallOptions {
@@ -9,20 +11,28 @@ export interface CompletionToolCallOptions {
 	readonly complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
 	readonly ctx: ExtensionContext;
 	readonly isActive: () => boolean;
+	/** Needed only for `completion(prompt, {handle: true})`; without it that option is refused. */
+	readonly handles?: HandleRegistry;
+	/** The creating cell's hard deadline (absolute ms) bounding a completion handle. */
+	readonly hardDeadlineMs?: number;
 }
 
 export type CompletionToolCallSummary = { readonly ok: true } | { readonly ok: false; readonly error: string };
 
 export async function handleCompletionToolCall(options: CompletionToolCallOptions): Promise<CompletionToolCallSummary> {
 	try {
-		const result = await options.complete(toCompletionRequest(options.message.args), options.ctx);
+		const request = toCompletionRequest(options.message.args);
+		const value = wantsCompletionHandle(request.opts)
+			? startCompletionHandle({
+					registry: requireRegistry(options.handles),
+					request,
+					complete: options.complete,
+					ctx: options.ctx,
+					deadlineMs: options.hardDeadlineMs ?? Number.POSITIVE_INFINITY,
+				})
+			: replyValue(await options.complete(request, options.ctx));
 		if (!options.isActive()) return { ok: false, error: "completion() result ignored after eval finalization" };
-		options.kernel.deliverToolReply({
-			type: "tool-reply",
-			callId: options.message.callId,
-			ok: true,
-			value: completionReplyValue(result),
-		});
+		options.kernel.deliverToolReply({ type: "tool-reply", callId: options.message.callId, ok: true, value });
 		return { ok: true };
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
@@ -31,12 +41,25 @@ export async function handleCompletionToolCall(options: CompletionToolCallOption
 			type: "tool-reply",
 			callId: options.message.callId,
 			ok: false,
-			error: { message },
+			error: {
+				message,
+				...(error instanceof Error && "code" in error && typeof error.code === "string"
+					? { code: error.code }
+					: {}),
+			},
 		});
 		return { ok: false, error: message };
 	}
 }
 
+function requireRegistry(handles: HandleRegistry | undefined): HandleRegistry {
+	if (handles !== undefined) return handles;
+	throw Object.assign(
+		new Error("eval_wait_unavailable: completion handles are not available before the session starts"),
+		{ code: "eval_wait_unavailable" },
+	);
+}
+
 function toCompletionRequest(value: unknown): CompletionRequest {
 	if (typeof value === "object" && value !== null && "prompt" in value && typeof value.prompt === "string") {
 		return {
@@ -49,7 +72,3 @@ function toCompletionRequest(value: unknown): CompletionRequest {
 	}
 	throw new Error("completion() received invalid arguments");
 }
-
-function completionReplyValue(result: CompletionResult): unknown {
-	return "value" in result ? result.value : result.text;
-}

package/src/config/feature-settings.ts

@@ -0,0 +1,110 @@
+import type { Static } from "typebox";
+import { Type } from "typebox";
+
+type Environment = Readonly<Record<string, string | undefined>>;
+
+export const JS_ISOLATION_ENVIRONMENT_FLAG = "SENPI_CODEMODE_JS_ISOLATION";
+export const SANDBOX_MEMORY_ENVIRONMENT_FLAG = "SENPI_CODEMODE_SANDBOX_MEMORY_MB";
+
+export const featureSettingsProperties = {
+	environments: Type.Optional(
+		Type.Object(
+			{
+				managedRoot: Type.Optional(Type.String({ minLength: 1 })),
+				autoProvision: Type.Optional(Type.Boolean()),
+				js: Type.Optional(
+					Type.Object(
+						{ installer: Type.Union([Type.Literal("auto"), Type.Literal("bun"), Type.Literal("npm")]) },
+						{ additionalProperties: false },
+					),
+				),
+				py: Type.Optional(Type.Object({ installer: Type.Literal("pip") }, { additionalProperties: false })),
+			},
+			{ additionalProperties: false },
+		),
+	),
+	isolation: Type.Optional(
+		Type.Object(
+			{ js: Type.Optional(Type.Union([Type.Literal("worker"), Type.Literal("process")])) },
+			{ additionalProperties: false },
+		),
+	),
+	sandbox: Type.Optional(
+		Type.Object(
+			{
+				enabled: Type.Optional(Type.Boolean()),
+				memoryMb: Type.Optional(Type.Integer({ minimum: 1 })),
+				timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1 })),
+			},
+			{ additionalProperties: false },
+		),
+	),
+	prompt: Type.Optional(
+		Type.Object({ advertiseHelpers: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+	),
+	kernelTools: Type.Optional(Type.Object({ enabled: Type.Optional(Type.Boolean()) }, { additionalProperties: false })),
+};
+
+const featureSettingsSchema = Type.Object(featureSettingsProperties);
+
+export type CodemodeFeatureSettings = Static<typeof featureSettingsSchema>;
+
+export type JsIsolation = "worker" | "process";
+
+export interface ResolvedSandbox {
+	readonly enabled: boolean;
+	readonly memoryMb: number;
+	readonly timeoutSeconds: number;
+}
+
+export interface ResolvedEnvironments {
+	readonly managedRoot?: string;
+	readonly autoProvision: boolean;
+	readonly jsInstaller: "auto" | "bun" | "npm";
+	readonly pyInstaller: "pip";
+}
+
+export function pickFeatureSettings(input: CodemodeFeatureSettings): CodemodeFeatureSettings {
+	return {
+		...(input.environments === undefined ? {} : { environments: input.environments }),
+		...(input.isolation === undefined ? {} : { isolation: input.isolation }),
+		...(input.sandbox === undefined ? {} : { sandbox: input.sandbox }),
+		...(input.prompt === undefined ? {} : { prompt: input.prompt }),
+		...(input.kernelTools === undefined ? {} : { kernelTools: input.kernelTools }),
+	};
+}
+
+/** The environment wins over the file; an unknown value is ignored. Default: today's worker-thread kernel. */
+export function resolveJsIsolation(settings: CodemodeFeatureSettings, env: Environment = process.env): JsIsolation {
+	const fromEnv = env[JS_ISOLATION_ENVIRONMENT_FLAG];
+	if (fromEnv === "worker" || fromEnv === "process") return fromEnv;
+	return settings.isolation?.js ?? "worker";
+}
+
+/** Off by default; the environment's memory cap wins over the file when it is a positive integer. */
+export function resolveSandbox(settings: CodemodeFeatureSettings, env: Environment = process.env): ResolvedSandbox {
+	const fromEnv = Number.parseInt(env[SANDBOX_MEMORY_ENVIRONMENT_FLAG] ?? "", 10);
+	return {
+		enabled: settings.sandbox?.enabled ?? false,
+		memoryMb: Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : (settings.sandbox?.memoryMb ?? 64),
+		timeoutSeconds: settings.sandbox?.timeoutSeconds ?? 300,
+	};
+}
+
+export function resolveEnvironments(settings: CodemodeFeatureSettings): ResolvedEnvironments {
+	const environments = settings.environments;
+	return {
+		...(environments?.managedRoot === undefined ? {} : { managedRoot: environments.managedRoot }),
+		autoProvision: environments?.autoProvision ?? true,
+		jsInstaller: environments?.js?.installer ?? "auto",
+		pyInstaller: environments?.py?.installer ?? "pip",
+	};
+}
+
+export function resolveAdvertiseHelpers(settings: CodemodeFeatureSettings): boolean {
+	return settings.prompt?.advertiseHelpers ?? false;
+}
+
+export function resolveKernelToolsEnabled(settings: CodemodeFeatureSettings): boolean {
+	return settings.kernelTools?.enabled ?? true;
+}