@code-yeongyu/senpi-codemode 2026.10.6 → 2026.10.7

package/CHANGELOG.md

@@ -12,6 +12,25 @@
 
 ### 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

package/README.md

@@ -200,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.6",
+	"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.6",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.7",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.10.6"
+		"@code-yeongyu/senpi": "2026.10.7"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.10.6"
+		"@code-yeongyu/senpi": "2026.10.7"
 	},
 	"keywords": [
 		"senpi",

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/extension/bridge-dispatch.ts

@@ -0,0 +1,41 @@
+import type { ExtensionContext } from "@code-yeongyu/senpi";
+import type { BridgeHttpCompletionRequest } from "../bridge/http-server.ts";
+import { startCompletionHandle, wantsCompletionHandle } from "../completion/handle.ts";
+import type { CompletionRequest } from "../completion/handler.ts";
+import { resolveHardLimitSeconds } from "../config/settings.ts";
+import type { CreateCodemodeSessionManagerOptions } from "./session-manager-contract.ts";
+
+export interface BridgeDispatchContext {
+	/** The context of the cell that last reached the manager; the handle host and completion owner are read from it. */
+	readonly context: ExtensionContext | undefined;
+	readonly contextFor: (signal: AbortSignal) => ExtensionContext;
+	readonly requireContext: () => ExtensionContext;
+}
+
+/**
+ * `completion(prompt, handle=True)` from a subprocess kernel: the handle lives in the session registry and is
+ * bounded by the hard limit measured from this request, the tightest bound the bridge knows for its cell.
+ */
+export async function dispatchBridgeCompletion(
+	options: CreateCodemodeSessionManagerOptions,
+	request: BridgeHttpCompletionRequest,
+	dispatch: BridgeDispatchContext,
+): Promise<unknown> {
+	const completion: CompletionRequest = { prompt: request.prompt, opts: request.opts };
+	if (!wantsCompletionHandle(request.opts)) {
+		return await options.complete(completion, dispatch.contextFor(request.signal));
+	}
+	const registry = options.handles;
+	if (registry === undefined) {
+		throw Object.assign(new Error("eval_wait_unavailable: completion handles are not available in this session"), {
+			code: "eval_wait_unavailable",
+		});
+	}
+	return startCompletionHandle({
+		registry,
+		request: completion,
+		complete: options.complete,
+		ctx: dispatch.requireContext(),
+		deadlineMs: Date.now() + resolveHardLimitSeconds(options.settings) * 1_000,
+	});
+}

package/src/extension/bridge-tool-call.ts

@@ -1,3 +1,4 @@
+import type { EvalHandleHost } from "@code-yeongyu/senpi";
 import { isReservedToolName, runReservedTool } from "../bridges/reserved-dispatch.ts";
 import { defaultCodemodeSettings } from "../config/settings.ts";
 import { marshalToolResult } from "../tool/image.ts";
@@ -16,8 +17,9 @@ export interface BridgeToolCallRequest {
 // and ordinary tool results are marshalled to { text, images, details, hasError } — the raw
 // { content } shape left python cells unable to reach tool.read image blocks.
 export async function routeBridgeToolCall(
-	options: Pick<CreateCodemodeSessionManagerOptions, "executeTool" | "listTools" | "settings">,
+	options: Pick<CreateCodemodeSessionManagerOptions, "executeTool" | "listTools" | "settings" | "handles">,
 	request: BridgeToolCallRequest,
+	evalHandleHost?: EvalHandleHost,
 ): Promise<unknown> {
 	if (!isReservedToolName(request.toolName)) {
 		return marshalToolResult(await options.executeTool(request.toolName, request.args, { signal: request.signal }));
@@ -33,5 +35,7 @@ export async function routeBridgeToolCall(
 		signal: request.signal,
 		emitStatus: () => {},
 		marshalToolResult,
+		...(options.handles === undefined ? {} : { handles: options.handles }),
+		...(evalHandleHost === undefined ? {} : { evalHandleHost }),
 	});
 }

package/src/extension/host-facts.ts

@@ -0,0 +1,18 @@
+import * as os from "node:os";
+import { jsRuntimeLabel } from "./runtime-info.ts";
+
+/** The one-line host description the eval prompt shows (platform, CPU, cores, JS runtime). */
+export function hostLine(): string {
+	const cpu = os.cpus()[0]?.model?.trim();
+	return [`${os.platform()} ${os.arch()}`, cpu, `${os.availableParallelism()} cores`, jsRuntimeLabel()]
+		.filter((part): part is string => !!part)
+		.join(" \u00b7 ");
+}
+
+/** The model id carried by a `model_select` event, when it has one. */
+export function modelIdFrom(event: unknown): string | undefined {
+	if (typeof event !== "object" || event === null || !("model" in event)) return undefined;
+	const model = event.model;
+	if (typeof model !== "object" || model === null || !("id" in model)) return undefined;
+	return typeof model.id === "string" ? model.id : undefined;
+}

package/src/extension/removed-tool-hints.ts

@@ -0,0 +1,15 @@
+/** Migration guidance for the tools eval replaced; the host returns it when a model calls them. */
+export interface RemovedToolHintRegistrar {
+	registerRemovedToolHint(name: string, hint: string): void;
+}
+
+export const WAIT_REMOVED_TOOL_HINT =
+	"wait is not a tool; inside a cell use the wait(handles) helper (tool_schema('eval:wait')), or let detached cells notify.";
+
+export function registerRemovedToolHints(pi: RemovedToolHintRegistrar): void {
+	pi.registerRemovedToolHint(
+		"exec",
+		'exec was removed; use eval({ language: "js", code }) instead. Long eval cells detach on their own and notify when complete.',
+	);
+	pi.registerRemovedToolHint("wait", WAIT_REMOVED_TOOL_HINT);
+}

package/src/extension/runtime-factory.ts

@@ -8,6 +8,7 @@ import {
 	type ResolvedCodemodeSettings,
 	resolveEnabledLanguages,
 } from "../config/settings.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import {
 	createInterpreterDetector,
 	getInterpreterAvailability,
@@ -54,6 +55,7 @@ export async function createRuntime(
 	event: unknown,
 	complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>,
 	options: RuntimeFactoryOptions,
+	handles?: HandleRegistry,
 ): Promise<SessionRuntime> {
 	const loaded = await loadCodemodeSettings({ cwd: ctx.cwd });
 	const settings: ResolvedCodemodeSettings = {
@@ -81,6 +83,7 @@ export async function createRuntime(
 		executeTool,
 		listTools: () => pi.getAllTools(),
 		complete,
+		...(handles === undefined ? {} : { handles }),
 	});
 	return {
 		sessionId,

package/src/extension/session-manager-contract.ts

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import type { CodemodeSettings } from "../config/settings.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { InterpreterAvailability } from "../interpreters/detect.ts";
 import type { SessionEnvironment } from "../kernels/session-env.ts";
 import type { EvalKernelManager, ExecuteTool } from "../tool/types.ts";
@@ -39,4 +40,6 @@ export interface CreateCodemodeSessionManagerOptions {
 	readonly executeTool: ExecuteTool;
 	readonly listTools?: () => readonly EvalSchemaToolInfo[];
 	readonly complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
+	/** The session generation's handle registry; subprocess kernels reach `wait()`/`handle()` through the bridge. */
+	readonly handles?: HandleRegistry;
 }

package/src/extension/session-manager.ts

@@ -8,6 +8,7 @@ import { collectOrphanedChildren } from "../host-sdk.ts";
 import { JavaScriptKernel } from "../kernels/js/context-manager.ts";
 import type { KernelLifecycle } from "../kernels/shared/kernel-death.ts";
 import type { EvalKernel, EvalLanguage } from "../tool/types.ts";
+import { type BridgeDispatchContext, dispatchBridgeCompletion } from "./bridge-dispatch.ts";
 import { type BridgeToolCallRequest, routeBridgeToolCall } from "./bridge-tool-call.ts";
 import { parkWhenIdle } from "./idle-parking-kernel.ts";
 import {
@@ -73,16 +74,23 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 	}
 
 	async start(): Promise<void> {
+		const manager = this;
+		const dispatch: BridgeDispatchContext = {
+			get context() {
+				return manager.#context;
+			},
+			contextFor: (signal) => this.#contextFor(signal),
+			requireContext: () => this.#requireContext(),
+		};
 		this.#bridge = await startBridgeServer({
 			onCall: async (request) => await this.#call(request),
 			onEmit: async () => undefined,
-			onCompletion: async (request) =>
-				this.#options.complete({ prompt: request.prompt, opts: request.opts }, this.#contextFor(request.signal)),
+			onCompletion: async (request) => await dispatchBridgeCompletion(this.#options, request, dispatch),
 		});
 	}
 
 	async #call(request: BridgeToolCallRequest): Promise<unknown> {
-		return await routeBridgeToolCall(this.#options, request);
+		return await routeBridgeToolCall(this.#options, request, this.#context?.evalHandleHost);
 	}
 
 	async getKernel(language: EvalLanguage, onMessage: (message: KernelToHostMessage) => void): Promise<EvalKernel> {
@@ -280,9 +288,14 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 		return names;
 	}
 
-	#contextFor(signal: AbortSignal): ExtensionContext {
+	#requireContext(): ExtensionContext {
 		const ctx = this.#context;
 		if (!ctx) throw new CodemodeContextUnavailableError();
+		return ctx;
+	}
+
+	#contextFor(signal: AbortSignal): ExtensionContext {
+		const ctx = this.#requireContext();
 		return { ...ctx, signal: ctx.signal ? AbortSignal.any([ctx.signal, signal]) : signal };
 	}
 }