@code-yeongyu/senpi 2026.7.5-2 → 2026.7.9

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/rb/prelude.rb

@@ -0,0 +1,57 @@
+require "base64"
+require "json"
+
+def display(value)
+  payload = Base64.strict_encode64(JSON.generate(value))
+  __senpi_emit({ "type" => "display", "mimeType" => "application/json", "dataBase64" => payload })
+  nil
+end
+
+def print(*values)
+  __senpi_emit({ "type" => "text", "stream" => "stdout", "data" => values.join })
+  nil
+end
+
+def read(path)
+  File.read(path.to_s)
+end
+
+def write(path, content)
+  File.write(path.to_s, content.to_s)
+  path.to_s
+end
+
+def env(key = nil, value = nil)
+  return ENV.to_h if key.nil?
+  if value.nil?
+    ENV[key.to_s]
+  else
+    ENV[key.to_s] = value.to_s
+  end
+end
+
+def log(message)
+  __senpi_emit({ "type" => "log", "message" => message.to_s })
+  nil
+end
+
+def phase(title)
+  __senpi_emit({ "type" => "phase", "title" => title.to_s })
+  nil
+end
+
+class SenpiToolProxy < BasicObject
+  def method_missing(name, args = nil, **kwargs)
+    merged = args.is_a?(::Hash) ? args.transform_keys(&:to_s) : {}
+    kwargs.each { |key, value| merged[key.to_s] = value }
+    ::Object.__send__(:__senpi_call_tool, name.to_s, merged)
+  end
+
+  def respond_to_missing?(_name, _private = false)
+    true
+  end
+end
+
+def tool
+  $__senpi_tool_proxy ||= SenpiToolProxy.new
+end

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/rb/runner.rb

@@ -0,0 +1,101 @@
+require "json"
+require "net/http"
+require "stringio"
+require "uri"
+require_relative "prelude"
+
+$__senpi_binding = TOPLEVEL_BINDING
+$__senpi_mutex = Mutex.new
+$__senpi_current_cell = nil
+$__senpi_connection = nil
+
+def __senpi_emit(frame)
+  STDOUT.write(JSON.generate(frame))
+  STDOUT.write("\n")
+  STDOUT.flush
+end
+
+def __senpi_error(error)
+  { "name" => error.class.name, "message" => error.message, "stack" => error.backtrace&.join("\n") }
+end
+
+def __senpi_call_tool(name, args)
+  connection = $__senpi_connection
+  raise "Ruby tool bridge is not initialized" unless connection.is_a?(Hash)
+  port = connection["port"]
+  token = connection["token"]
+  raise "Ruby tool bridge is not initialized" unless port.is_a?(Integer) && token.is_a?(String)
+
+  call_id = "#{Time.now.to_i}-#{rand(1_000_000)}"
+  uri = URI("http://127.0.0.1:#{port}/call")
+  request = Net::HTTP::Post.new(uri)
+  request["authorization"] = "Bearer #{token}"
+  request["content-type"] = "application/json"
+  request.body = JSON.generate({ "callId" => call_id, "toolName" => name, "args" => args })
+  response = Net::HTTP.start(uri.hostname, uri.port, read_timeout: 60) { |http| http.request(request) }
+  body = JSON.parse(response.body.to_s)
+  return body["value"] if body.is_a?(Hash) && body["ok"] == true
+
+  error = body.is_a?(Hash) ? body["error"] : body
+  if error.is_a?(Hash)
+    raise error["message"].to_s
+  end
+  raise error.to_s
+end
+
+# Capture the cell's $stdout writes (puts/print) and emit them as `text` frames.
+# $stdout is redirected to a buffer during eval so user output never contaminates
+# the JSONL protocol channel, which __senpi_emit writes to via the STDOUT constant
+# (the STDOUT constant is unaffected by reassigning the $stdout global).
+def __senpi_run_cell(message)
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  $__senpi_current_cell = message["cellId"]
+  captured = StringIO.new
+  previous_stdout = $stdout
+  $stdout = captured
+  begin
+    value = eval(message["code"].to_s, $__senpi_binding, "(senpi-rb)")
+    $stdout = previous_stdout
+    __senpi_flush_stdout(captured)
+    frame = {
+      "type" => "result",
+      "cellId" => message["cellId"],
+      "ok" => true,
+      "durationMs" => ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round,
+    }
+    frame["valueRepr"] = JSON.generate(value) unless value.nil?
+    __senpi_emit(frame)
+  rescue Exception => error
+    $stdout = previous_stdout
+    __senpi_flush_stdout(captured)
+    __senpi_emit({
+      "type" => "result",
+      "cellId" => message["cellId"],
+      "ok" => false,
+      "error" => __senpi_error(error),
+      "durationMs" => ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round,
+    })
+  ensure
+    $stdout = previous_stdout
+    $__senpi_current_cell = nil
+  end
+end
+
+def __senpi_flush_stdout(captured)
+  data = captured.string
+  __senpi_emit({ "type" => "text", "stream" => "stdout", "data" => data }) unless data.empty?
+end
+
+STDIN.each_line do |line|
+  message = JSON.parse(line)
+  case message["type"]
+  when "init"
+    $__senpi_connection = message["connection"]
+    __senpi_emit({ "type" => "ready" })
+  when "run"
+    __senpi_run_cell(message)
+  when "close"
+    __senpi_emit({ "type" => "closed" })
+    exit 0
+  end
+end

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/shared/subprocess-kernel.ts

@@ -0,0 +1,241 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { spawn as nodeSpawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import type { BridgeConnectionConfig, HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
+import { decodeBridgeFrame, encodeBridgeFrame } from "../../bridge/protocol.ts";
+
+export interface KernelRunInput {
+	readonly cellId: string;
+	readonly code: string;
+	readonly timeoutMs?: number;
+}
+
+export type KernelResult = Extract<KernelToHostMessage, { type: "result" }>;
+export type ToolCallMessage = Extract<KernelToHostMessage, { type: "tool-call" }>;
+
+export interface SubprocessLike {
+	readonly pid?: number;
+	readonly stdin: { write(chunk: string): unknown };
+	readonly stdout: NodeJS.ReadableStream;
+	readonly stderr: NodeJS.ReadableStream;
+	once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+	kill(signal?: NodeJS.Signals): boolean;
+}
+
+export type SubprocessSpawn = (
+	command: string,
+	args: readonly string[],
+	options: { readonly cwd?: string; readonly env?: NodeJS.ProcessEnv },
+) => SubprocessLike;
+
+export interface SubprocessKernelOptions {
+	readonly command: string;
+	readonly args: readonly string[];
+	readonly cwd?: string;
+	readonly env?: NodeJS.ProcessEnv;
+	readonly sessionId: string;
+	readonly connection: BridgeConnectionConfig;
+	readonly spawn?: SubprocessSpawn;
+	readonly onMessage?: (message: KernelToHostMessage) => void;
+}
+
+export class SubprocessKernel {
+	private process!: SubprocessLike;
+	private readonly options: SubprocessKernelOptions;
+	private readonly onMessage?: (message: KernelToHostMessage) => void;
+	private readonly processes = new Set<SubprocessLike>();
+	private readonly exitPromises = new WeakMap<SubprocessLike, Promise<void>>();
+	private readonly terminatingProcesses = new WeakSet<SubprocessLike>();
+	private readonly pendingRuns = new Map<
+		string,
+		{ readonly resolve: (message: KernelResult) => void; readonly timer: NodeJS.Timeout | null }
+	>();
+	private readonly retiringProcesses = new WeakSet<SubprocessLike>();
+	private readonly pendingCalls: ToolCallMessage[] = [];
+	private readonly callWaiters: ((message: ToolCallMessage) => void)[] = [];
+	private closed = false;
+
+	constructor(options: SubprocessKernelOptions) {
+		this.options = options;
+		this.onMessage = options.onMessage;
+		this.process = this.spawnProcess();
+	}
+
+	run(input: KernelRunInput): Promise<KernelResult> {
+		if (this.closed) throw new Error("Kernel is closed");
+		const message: HostToKernelMessage = {
+			type: "run",
+			cellId: input.cellId,
+			code: input.code,
+			timeoutMs: input.timeoutMs,
+		};
+		this.send(message);
+		return new Promise((resolve) => {
+			const timeoutMs = input.timeoutMs;
+			const timer =
+				timeoutMs === undefined
+					? null
+					: setTimeout(() => {
+							this.pendingRuns.delete(input.cellId);
+							resolve({
+								type: "result",
+								cellId: input.cellId,
+								ok: false,
+								error: { message: `Cell timed out after ${timeoutMs}ms` },
+								durationMs: timeoutMs,
+							});
+							this.restartProcess();
+						}, timeoutMs);
+			this.pendingRuns.set(input.cellId, { resolve, timer });
+		});
+	}
+
+	nextToolCall(): Promise<ToolCallMessage> {
+		const queued = this.pendingCalls.shift();
+		if (queued !== undefined) return Promise.resolve(queued);
+		return new Promise((resolve) => this.callWaiters.push(resolve));
+	}
+
+	deliverToolReply(message: Extract<HostToKernelMessage, { type: "tool-reply" }>): void {
+		this.send(message);
+	}
+
+	async reset(): Promise<void> {
+		this.restartProcess();
+		this.pendingRuns.clear();
+		this.pendingCalls.length = 0;
+		this.callWaiters.length = 0;
+	}
+
+	async close(): Promise<void> {
+		if (this.closed) return;
+		this.closed = true;
+		this.send({ type: "close" });
+		await Promise.all([...this.processes].map((process) => this.terminateProcess(process)));
+	}
+
+	private attachReaders(): void {
+		const activeProcess = this.process;
+		this.processes.add(activeProcess);
+		const exitPromise = new Promise<void>((resolve) => {
+			activeProcess.once("exit", () => {
+				this.processes.delete(activeProcess);
+				resolve();
+			});
+		});
+		this.exitPromises.set(activeProcess, exitPromise);
+		const stdout = createInterface({ input: this.process.stdout });
+		stdout.on("line", (line) => {
+			if (this.process !== activeProcess) return;
+			this.handleLine(`${line}\n`);
+		});
+		this.process.stderr.on("data", (chunk) => {
+			if (this.process !== activeProcess) return;
+			this.handleMessage({ type: "text", stream: "stderr", data: String(chunk) });
+		});
+		this.process.once("exit", (code, signal) => {
+			if (this.retiringProcesses.has(activeProcess)) return;
+			if (this.process !== activeProcess) return;
+			this.closed = true;
+			const error = { message: `Kernel exited before completing the cell (${signal ?? code ?? "unknown"})` };
+			for (const [cellId, pending] of this.pendingRuns) {
+				if (pending.timer) clearTimeout(pending.timer);
+				pending.resolve({ type: "result", cellId, ok: false, error, durationMs: 0 });
+			}
+			this.pendingRuns.clear();
+		});
+	}
+
+	private handleLine(line: string): void {
+		const decoded = decodeBridgeFrame(line);
+		if (!decoded.ok) {
+			this.handleMessage({ type: "text", stream: "stderr", data: `${decoded.error.message}\n` });
+			return;
+		}
+		this.handleMessage(decoded.message as KernelToHostMessage);
+	}
+
+	private handleMessage(message: KernelToHostMessage): void {
+		this.onMessage?.(message);
+		if (message.type === "tool-call") {
+			const waiter = this.callWaiters.shift();
+			if (waiter) waiter(message);
+			else this.pendingCalls.push(message);
+			return;
+		}
+		if (message.type === "result") {
+			const pending = this.pendingRuns.get(message.cellId);
+			if (pending?.timer) clearTimeout(pending.timer);
+			pending?.resolve(message);
+			this.pendingRuns.delete(message.cellId);
+		}
+	}
+
+	private send(message: HostToKernelMessage): void {
+		this.process.stdin.write(encodeBridgeFrame(message));
+	}
+
+	private restartProcess(): void {
+		const activeProcess = this.process;
+		this.retiringProcesses.add(activeProcess);
+		this.process = this.spawnProcess();
+		void this.terminateProcess(activeProcess);
+	}
+
+	private spawnProcess(): SubprocessLike {
+		const spawn = this.options.spawn ?? defaultSpawn;
+		this.closed = false;
+		const child = spawn(this.options.command, this.options.args, { cwd: this.options.cwd, env: this.options.env });
+		this.process = child;
+		this.attachReaders();
+		this.send({ type: "init", sessionId: this.options.sessionId, connection: this.options.connection });
+		return child;
+	}
+
+	private async terminateProcess(process: SubprocessLike): Promise<void> {
+		if (!this.terminatingProcesses.has(process)) {
+			this.terminatingProcesses.add(process);
+			this.killProcess(process, "SIGTERM");
+		}
+		const exitPromise = this.exitPromises.get(process);
+		if (!exitPromise) return;
+		let forceTimer: NodeJS.Timeout | undefined;
+		try {
+			await Promise.race([
+				exitPromise,
+				new Promise<void>((resolve) => {
+					forceTimer = setTimeout(() => {
+						this.killProcess(process, "SIGKILL");
+						resolve();
+					}, 1_500);
+				}),
+			]);
+			await exitPromise;
+		} finally {
+			if (forceTimer) clearTimeout(forceTimer);
+		}
+	}
+
+	private killProcess(process: SubprocessLike, signal: NodeJS.Signals): void {
+		if (process.pid !== undefined) {
+			try {
+				globalThis.process.kill(-process.pid, signal);
+				return;
+			} catch {}
+		}
+		process.kill(signal);
+	}
+}
+
+function defaultSpawn(
+	command: string,
+	args: readonly string[],
+	options: { readonly cwd?: string; readonly env?: NodeJS.ProcessEnv },
+): SubprocessLike {
+	return nodeSpawn(command, [...args], {
+		cwd: options.cwd,
+		detached: true,
+		env: options.env,
+		stdio: "pipe",
+	}) as ChildProcessWithoutNullStreams;
+}

package/node_modules/@code-yeongyu/senpi-codemode/src/prompt/eval-prompt.ts

@@ -0,0 +1,182 @@
+export interface EnabledLanguages {
+	readonly py: boolean;
+	readonly js: boolean;
+	readonly rb: boolean;
+	readonly jl: boolean;
+}
+
+export interface EvalPromptParts {
+	readonly description: string;
+	readonly promptSnippet: string;
+	readonly promptGuidelines: readonly string[];
+}
+
+type ContextValue = string | boolean;
+type Context = Readonly<Record<string, ContextValue>>;
+
+const EVAL_PROMPT_TEMPLATE = `Run one step of code in a persistent kernel.
+
+<instruction>
+**One eval call = one cell = one logical step.** State persists per language across separate eval calls and tool calls — define helpers, datasets, and clients in one call, then later calls reuse them directly.
+
+Work incrementally: imports in one call, define in the next, test, then use — each its own eval call. Re-run setup ONLY after \`reset\`, a kernel crash, or a \`NameError\`/\`ReferenceError\` proving the state is gone. Parallelize work *within* a cell with the \`parallel(thunks)\` helper, not by batching steps.
+
+Fields:
+
+- \`language\` — {{#if py}}\`"py"\` IPython kernel{{/if}}{{#ifAll py js}}, {{/ifAll}}{{#if js}}\`"js"\` persistent JavaScript VM{{/if}}{{#if rb}}{{#ifAny py js}}, {{/ifAny}}\`"rb"\` persistent Ruby kernel{{/if}}{{#if jl}}{{#ifAny py js rb}}, {{/ifAny}}\`"jl"\` persistent Julia kernel{{/if}}.
+- \`code\` — cell body, verbatim. Newlines/quotes JSON-encoded; no fences, no headers.
+- \`title\` (optional) — short transcript label (e.g. \`"imports"\`).
+- \`timeout\` (optional) — seconds. Raise only for heavy compute or long delegated tool calls.
+- \`reset\` (optional) — wipe this language's kernel first.{{#ifAll py js}} Per-language: a \`py\` reset never touches the JS VM.{{/ifAll}}
+
+{{#if py}}Live event loop: use top-level \`await\` directly; \`asyncio.run(...)\` raises "cannot be called from a running event loop".{{/if}}
+{{#if js}}JS runs under Node.js worker: top-level \`await\`/\`return\` work; \`fetch\`/\`Buffer\` available.{{/if}}
+{{#if rb}}Ruby: synchronous; helper options are keyword args; the last expression auto-displays unless it is \`nil\`, an assignment, or a definition.{{/if}}
+{{#if jl}}Julia: synchronous; helper options are standard keyword args; the last expression auto-displays unless it is an assignment or a definition.{{/if}}
+On error, fix and re-run only the failing step — prior calls' state survives.
+</instruction>
+
+<prelude>
+{{#ifAll py js}}Same helpers + arg order, both runtimes. Python: sync, options = trailing kwargs. JS: async/\`await\`able, options = ONE trailing object literal, never positional.{{else}}{{#if py}}Sync; options = trailing kwargs.{{/if}}{{#if js}}Async/\`await\`able; options = ONE trailing object literal, never positional.{{/if}}{{/ifAll}}{{#if rb}} Ruby: sync, options = trailing keyword args.{{/if}}{{#if jl}} Julia: sync, options = trailing keyword args.{{/if}}
+\`\`\`
+display(value) -> None
+    Cell result; figures/images/dataframes shown natively.
+print(value, ...) -> None
+    Text stream.
+read(path, offset?=1, limit?=None) -> str
+    File as text; offset/limit are 1-indexed lines.
+write(path, content) -> str
+    Write file, creating parents, and return the resolved path.
+env(key?=None, value?=None) -> str | None | dict
+    No args -> full env dict; one -> value of key; two -> set key=value and return value.
+tool.<name>(args) -> unknown
+    Invoke any active session tool; args = its parameter object.
+completion(prompt, model?="default", system?=None, schema?=None) -> str | dict
+    Oneshot, stateless completion. model "default" uses the session model; schema is JSON Schema for structured results.
+parallel(thunks) -> list
+    Thunks through a bounded pool, input order kept; returns when all finish, a throwing thunk propagates.
+pipeline(items, ...stages) -> list
+    Map items through one-arg stages left-to-right, barrier between stages; stage 1 gets the item, later stages the previous result.
+log(message) -> None
+    Progress line above the status tree.
+phase(title) -> None
+    Phase grouping subsequent status lines.
+\`\`\`
+</prelude>
+
+<critical>
+Prior top-level names survive into the next eval call — reuse them; NEVER re-import, re-require, or re-declare a helper. Re-read a file only if it may have changed since the last read. Re-run setup only after \`reset\`, a crash, or a \`NameError\`/\`ReferenceError\`.
+</critical>`;
+
+export function buildEvalPrompt(enabled: EnabledLanguages): EvalPromptParts {
+	if (!enabled.py && !enabled.js && !enabled.rb && !enabled.jl) {
+		throw new Error("no kernels enabled for eval prompt");
+	}
+	const context: Context = {
+		py: enabled.py,
+		js: enabled.js,
+		rb: enabled.rb,
+		jl: enabled.jl,
+	};
+	const description = renderTemplate(EVAL_PROMPT_TEMPLATE, context)
+		.replace(/\n{3,}/g, "\n\n")
+		.trim();
+	return {
+		description,
+		promptSnippet: "Run one incremental code cell in a persistent language kernel.",
+		promptGuidelines: [
+			"Use eval for incremental code execution when a persistent JS, Python, Ruby, or Julia kernel is available.",
+			"Use eval reset only when a language kernel must be wiped; reset is scoped to the selected language.",
+		],
+	};
+}
+
+function renderTemplate(template: string, context: Context): string {
+	let index = 0;
+	const [rendered, nextIndex] = renderUntil(template, context, index, []);
+	index = nextIndex;
+	if (index !== template.length) {
+		throw new Error("unexpected template close tag");
+	}
+	return rendered;
+}
+
+function renderUntil(
+	template: string,
+	context: Context,
+	start: number,
+	stopTags: readonly string[],
+): readonly [string, number, string?] {
+	let rendered = "";
+	let index = start;
+	while (index < template.length) {
+		const open = template.indexOf("{{", index);
+		if (open < 0) {
+			return [rendered + template.slice(index), template.length];
+		}
+		rendered += template.slice(index, open);
+		const close = template.indexOf("}}", open + 2);
+		if (close < 0) {
+			throw new Error("unterminated template tag");
+		}
+		const tag = template.slice(open + 2, close).trim();
+		index = close + 2;
+		if (stopTags.includes(tag)) {
+			return [rendered, index, tag];
+		}
+		if (tag.startsWith("#")) {
+			const [block, nextIndex] = renderBlock(template, context, index, tag);
+			rendered += block;
+			index = nextIndex;
+			continue;
+		}
+		if (tag.startsWith("/")) {
+			throw new Error(`unexpected template close tag ${tag}`);
+		}
+		rendered += valueFor(tag, context);
+	}
+	return [rendered, index];
+}
+
+function renderBlock(template: string, context: Context, start: number, openTag: string): readonly [string, number] {
+	const [kind, ...names] = openTag.slice(1).split(/\s+/);
+	const closeTag = `/${kind}`;
+	const [truthyText, afterTruthy, stopTag] = renderUntil(template, context, start, ["else", closeTag]);
+	let falseyText = "";
+	let end = afterTruthy;
+	if (stopTag === "else") {
+		const [elseText, afterElse, elseStop] = renderUntil(template, context, afterTruthy, [closeTag]);
+		if (elseStop !== closeTag) {
+			throw new Error(`missing close tag for ${kind}`);
+		}
+		falseyText = elseText;
+		end = afterElse;
+	} else if (stopTag !== closeTag) {
+		throw new Error(`missing close tag for ${kind}`);
+	}
+	return [condition(kind, names, context) ? truthyText : falseyText, end];
+}
+
+function condition(kind: string, names: readonly string[], context: Context): boolean {
+	if (kind === "if") {
+		return names.length === 1 && Boolean(context[names[0]]);
+	}
+	if (kind === "ifAll") {
+		return names.length > 0 && names.every((name) => Boolean(context[name]));
+	}
+	if (kind === "ifAny") {
+		return names.length > 0 && names.some((name) => Boolean(context[name]));
+	}
+	throw new Error(`unknown template condition ${kind}`);
+}
+
+function valueFor(name: string, context: Context): string {
+	const value = context[name];
+	if (typeof value === "string") {
+		return value;
+	}
+	if (typeof value === "boolean" || value === undefined) {
+		return "";
+	}
+	return String(value);
+}

package/node_modules/@code-yeongyu/senpi-codemode/src/timeouts/bridge-timeout.ts

@@ -0,0 +1,14 @@
+import type { TimeoutPauseHandle } from "./idle-timeout.ts";
+
+export async function withBridgeTimeoutPause<T>(
+	watchdog: TimeoutPauseHandle | undefined,
+	operation: () => Promise<T>,
+): Promise<T> {
+	if (watchdog === undefined) return operation();
+	watchdog.pause();
+	try {
+		return await operation();
+	} finally {
+		watchdog.resume();
+	}
+}

package/node_modules/@code-yeongyu/senpi-codemode/src/timeouts/idle-timeout.ts

@@ -0,0 +1,95 @@
+export interface IdleTimeoutEvent {
+	readonly cellId: string;
+	readonly error: Error;
+}
+
+export interface IdleTimeoutOptions {
+	readonly cellId: string;
+	readonly timeoutMs: number;
+	readonly onTimeout: (event: IdleTimeoutEvent) => void;
+}
+
+export interface TimeoutPauseHandle {
+	pause(): void;
+	resume(): void;
+}
+
+export class IdleTimeout implements TimeoutPauseHandle {
+	readonly #cellId: string;
+	readonly #timeoutMs: number;
+	readonly #onTimeout: (event: IdleTimeoutEvent) => void;
+	readonly #controller = new AbortController();
+	#remainingMs: number;
+	#deadlineMs: number;
+	#timer: ReturnType<typeof setTimeout> | undefined;
+	#pauseDepth = 0;
+	#settled = false;
+
+	constructor(options: IdleTimeoutOptions) {
+		this.#cellId = options.cellId;
+		this.#timeoutMs = Math.max(1, Math.floor(options.timeoutMs));
+		this.#remainingMs = this.#timeoutMs;
+		this.#deadlineMs = Date.now() + this.#remainingMs;
+		this.#onTimeout = options.onTimeout;
+		this.#arm(this.#remainingMs);
+	}
+
+	get signal(): AbortSignal {
+		return this.#controller.signal;
+	}
+
+	get timeoutMs(): number {
+		return this.#timeoutMs;
+	}
+
+	pause(): void {
+		if (this.#settled) return;
+		this.#pauseDepth++;
+		if (this.#pauseDepth !== 1) return;
+		this.#remainingMs = Math.max(0, this.#deadlineMs - Date.now());
+		this.#clearTimer();
+	}
+
+	resume(): void {
+		if (this.#settled || this.#pauseDepth === 0) return;
+		this.#pauseDepth--;
+		if (this.#pauseDepth > 0) return;
+		this.#deadlineMs = Date.now() + this.#remainingMs;
+		this.#arm(this.#remainingMs);
+	}
+
+	dispose(): void {
+		if (this.#settled) return;
+		this.#settled = true;
+		this.#clearTimer();
+	}
+
+	#arm(delayMs: number): void {
+		this.#clearTimer();
+		const timer = setTimeout(() => this.#expire(), Math.max(0, delayMs));
+		timer.unref?.();
+		this.#timer = timer;
+	}
+
+	#clearTimer(): void {
+		if (this.#timer === undefined) return;
+		clearTimeout(this.#timer);
+		this.#timer = undefined;
+	}
+
+	#expire(): void {
+		if (this.#settled || this.#pauseDepth > 0) return;
+		const remainingMs = this.#deadlineMs - Date.now();
+		if (remainingMs > 0) {
+			this.#remainingMs = remainingMs;
+			this.#arm(remainingMs);
+			return;
+		}
+		this.#settled = true;
+		this.#timer = undefined;
+		const error = new Error(`Cell timed out after ${this.#timeoutMs}ms`);
+		error.name = "TimeoutError";
+		this.#controller.abort(error);
+		this.#onTimeout({ cellId: this.#cellId, error });
+	}
+}