@code-yeongyu/senpi-codemode 2026.10.6 → 2026.10.7

package/src/extension/start-recovery.ts

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import type { ExtensionContext } from "@code-yeongyu/senpi";
+import type { createEvalTool } from "../tool/eval-tool.ts";
+import { CodemodeSessionDisposedError } from "./session-manager.ts";
+import { CodemodeSessionNotStartedError } from "./session-manager-proxy.ts";
+
+export class CodemodeRuntimeRecreationError extends Error {
+	readonly name = "CodemodeRuntimeRecreationError";
+
+	constructor(reason: string) {
+		super(`codemode runtime could not be re-created: ${reason}. Start a new session or reload to bring eval back.`);
+	}
+}
+
+type StartSession = (event: unknown, ctx: ExtensionContext) => Promise<void>;
+
+/**
+ * A session_start whose runtime could not be created leaves the session running with no usable manager. The
+ * next eval re-creates the runtime once for that failed start (concurrent evals share the attempt) and runs; a
+ * failed re-creation is reported to every later eval until the next session_start. One stderr line names the
+ * failed start with a hashed session id so a recurrence stays visible. A session that ended is never recovered.
+ */
+export class StartRecovery {
+	readonly #startSession: StartSession;
+	readonly #report: (line: string) => void;
+	#failedStartEvent: { readonly event: unknown } | undefined;
+	#recreation: Promise<void> | undefined;
+	#recreationFailure: CodemodeRuntimeRecreationError | undefined;
+
+	constructor(
+		startSession: StartSession,
+		report: (line: string) => void = (line) => globalThis.process.stderr.write(`${line}\n`),
+	) {
+		this.#startSession = startSession;
+		this.#report = report;
+	}
+
+	async runStart(event: unknown, ctx: ExtensionContext): Promise<void> {
+		try {
+			await this.#startSession(event, ctx);
+			this.#reset();
+		} catch (error) {
+			this.#reset();
+			this.#failedStartEvent = { event };
+			throw error;
+		}
+	}
+
+	sessionEnded(): void {
+		this.#reset();
+	}
+
+	wrapExecute<Args extends unknown[], Result>(
+		execute: (...args: Args) => Promise<Result>,
+		contextOf: (args: Args) => ExtensionContext,
+	): (...args: Args) => Promise<Result> {
+		return async (...args) => {
+			try {
+				return await execute(...args);
+			} catch (error) {
+				if (!(error instanceof CodemodeSessionDisposedError || error instanceof CodemodeSessionNotStartedError)) {
+					throw error;
+				}
+				if (this.#recreationFailure !== undefined) throw this.#recreationFailure;
+				const recreation = this.#recreation ?? this.#beginRecreation(contextOf(args));
+				if (recreation === undefined) throw error;
+				await recreation;
+				return await execute(...args);
+			}
+		};
+	}
+
+	#beginRecreation(ctx: ExtensionContext): Promise<void> | undefined {
+		const failed = this.#failedStartEvent;
+		if (failed === undefined) return undefined;
+		this.#report(
+			`[senpi-codemode] eval re-created a runtime left disposed by a failed session_start (session ${sessionHash(ctx)})`,
+		);
+		const recreation = this.#startSession(failed.event, ctx).then(
+			() => {
+				this.#recreation = undefined;
+				this.#reset();
+			},
+			(error: unknown) => {
+				this.#recreation = undefined;
+				this.#recreationFailure = new CodemodeRuntimeRecreationError(
+					error instanceof Error ? error.message : String(error),
+				);
+				throw this.#recreationFailure;
+			},
+		);
+		this.#recreation = recreation;
+		return recreation;
+	}
+
+	#reset(): void {
+		this.#failedStartEvent = undefined;
+		this.#recreationFailure = undefined;
+	}
+}
+
+export function withStartRecovery<Tool extends ReturnType<typeof createEvalTool>>(
+	recovery: StartRecovery,
+	tool: Tool,
+): Tool {
+	return { ...tool, execute: recovery.wrapExecute(tool.execute, (args) => args[4]) };
+}
+
+function sessionHash(ctx: ExtensionContext): string {
+	return createHash("sha256").update(ctx.sessionManager.getSessionId()).digest("hex").slice(0, 12);
+}

package/src/handles/completion-handles.ts

@@ -0,0 +1,202 @@
+import { randomBytes } from "node:crypto";
+import {
+	type CancelReceipt,
+	EvalHandleError,
+	type HandleError,
+	type HandleOutcome,
+	type HandlePhase,
+	type HandleRef,
+	type HandleSnapshot,
+	type HandleWatch,
+	type OutputRequest,
+	type OutputSnapshot,
+} from "@code-yeongyu/senpi";
+import { refKey } from "./handle-args.ts";
+import { WatchQueue } from "./watch-queue.ts";
+
+export interface CompletionStart {
+	/** Runs the host completion; the signal aborts on cancel, on the deadline, and when the session generation drops. */
+	readonly run: (signal: AbortSignal) => Promise<unknown>;
+	/** Absolute wall-clock deadline (ms), derived from the creating cell's hard deadline. */
+	readonly deadlineMs: number;
+}
+
+interface CompletionEntry {
+	readonly ref: HandleRef;
+	phase: HandlePhase;
+	hostStatus: string;
+	revision: number;
+	value?: unknown;
+	error?: HandleError;
+	readonly controller: AbortController;
+	timer: ReturnType<typeof setTimeout> | undefined;
+	deadlineHit: boolean;
+}
+
+const TERMINAL: ReadonlySet<HandlePhase> = new Set(["succeeded", "failed", "cancelled", "lost"]);
+const DEADLINE_MESSAGE = "completion handle exceeded its cell's hard deadline";
+const MAX_TIMER_MS = 2 ** 31 - 1;
+
+/**
+ * codemode-owned completion handles (`completion(prompt, {handle: true})`). They live in the session's
+ * registry, so they survive a kernel restart and need no host capability; once the session generation
+ * is dropped every ref fails closed with `eval_handle_stale`.
+ */
+export class CompletionHandles {
+	readonly #entries = new Map<string, CompletionEntry>();
+	readonly #watches = new Set<WatchQueue>();
+	readonly #now: () => number;
+	#disposed = false;
+
+	constructor(now: () => number = Date.now) {
+		this.#now = now;
+	}
+
+	start(input: CompletionStart): HandleRef {
+		this.#assertLive();
+		const ref: HandleRef = { kind: "completion", id: `cp_${randomBytes(16).toString("hex")}`, run_epoch: 0 };
+		const controller = new AbortController();
+		const entry: CompletionEntry = {
+			ref,
+			phase: "pending",
+			hostStatus: "running",
+			revision: 1,
+			controller,
+			timer: undefined,
+			deadlineHit: false,
+		};
+		this.#entries.set(ref.id, entry);
+		const remainingMs = Math.min(MAX_TIMER_MS, Math.max(0, input.deadlineMs - this.#now()));
+		if (Number.isFinite(remainingMs)) {
+			entry.timer = setTimeout(() => {
+				entry.deadlineHit = true;
+				controller.abort(new Error(DEADLINE_MESSAGE));
+			}, remainingMs);
+			entry.timer.unref?.();
+		}
+		input.run(controller.signal).then(
+			(value) => this.#settle(entry, { phase: "succeeded", hostStatus: "completed", value }),
+			(error: unknown) => {
+				// cancel() and dispose() settle the entry before aborting; their rejection is not an outcome.
+				if (TERMINAL.has(entry.phase)) return;
+				const hostStatus = entry.deadlineHit ? "deadline" : "failed";
+				this.#settle(entry, { phase: "failed", hostStatus, error: toHandleError(error, entry.deadlineHit) });
+			},
+		);
+		return ref;
+	}
+
+	get openWatches(): number {
+		return this.#watches.size;
+	}
+
+	owns(ref: HandleRef): boolean {
+		return ref.kind === "completion";
+	}
+
+	watch(refs: readonly HandleRef[]): HandleWatch {
+		const entries = refs.map((ref) => this.#fence(ref));
+		const queue = new WatchQueue(refs.map(refKey));
+		// Subscribe first, then snapshot: a settle between the two is queued and arrives in updates once.
+		this.#watches.add(queue);
+		const initial = entries.map((entry) => snapshotOf(entry));
+		return queue.toWatch(initial, () => this.#watches.delete(queue));
+	}
+
+	result(ref: HandleRef): HandleOutcome {
+		const entry = this.#fence(ref);
+		if (!TERMINAL.has(entry.phase)) throw new EvalHandleError("eval_handle_pending", `${ref.id} is still running`);
+		if (entry.phase === "succeeded") return { status: "fulfilled", ref: entry.ref, value: entry.value };
+		return {
+			status: "rejected",
+			ref: entry.ref,
+			error: entry.error ?? { code: "eval_handle_lost", message: `${ref.id} ended without an outcome` },
+		};
+	}
+
+	cancel(ref: HandleRef): CancelReceipt {
+		const entry = this.#fence(ref);
+		if (TERMINAL.has(entry.phase)) return { ref: entry.ref, cancelled: false, phase: entry.phase };
+		const error = { code: "eval_handle_cancelled", message: `${ref.id} was cancelled` };
+		this.#settle(entry, { phase: "cancelled", hostStatus: "cancelled", error });
+		entry.controller.abort(new Error(error.message));
+		return { ref: entry.ref, cancelled: true, phase: "cancelled" };
+	}
+
+	output(ref: HandleRef, request: OutputRequest): OutputSnapshot {
+		const entry = this.#fence(ref);
+		const text =
+			entry.phase === "succeeded"
+				? typeof entry.value === "string"
+					? entry.value
+					: JSON.stringify(entry.value)
+				: (entry.error?.message ?? "");
+		const lines = text.length === 0 ? [] : text.split("\n");
+		const total = lines.length;
+		const window =
+			request.format === "tail"
+				? lines.slice(-(request.limit ?? 20))
+				: lines.slice(request.offset ?? 0, (request.offset ?? 0) + (request.limit ?? total));
+		const offset = request.format === "tail" ? total - window.length : (request.offset ?? 0);
+		return { ref: entry.ref, text: window.join("\n"), offset, total, truncated: window.length < total };
+	}
+
+	/** Aborts every in-flight completion and closes every watch; afterwards every ref is stale. */
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		for (const entry of this.#entries.values()) {
+			if (entry.timer !== undefined) clearTimeout(entry.timer);
+			if (!TERMINAL.has(entry.phase)) {
+				entry.phase = "lost";
+				entry.hostStatus = "session-dropped";
+				entry.controller.abort(new Error("session generation dropped"));
+			}
+		}
+		for (const queue of this.#watches) queue.close();
+		this.#watches.clear();
+	}
+
+	#assertLive(): void {
+		if (this.#disposed) throw new EvalHandleError("eval_handle_stale", "this session generation was dropped");
+	}
+
+	#fence(ref: HandleRef): CompletionEntry {
+		this.#assertLive();
+		const entry = this.#entries.get(ref.id);
+		if (ref.kind !== "completion" || !entry)
+			throw new EvalHandleError("eval_handle_not_found", `no completion handle ${ref.id}`);
+		if (ref.run_epoch !== entry.ref.run_epoch)
+			throw new EvalHandleError("eval_handle_stale", `${ref.id} run epoch ${ref.run_epoch} is not live`);
+		return entry;
+	}
+
+	#settle(
+		entry: CompletionEntry,
+		next: { phase: HandlePhase; hostStatus: string; value?: unknown; error?: HandleError },
+	): void {
+		if (TERMINAL.has(entry.phase)) return;
+		if (entry.timer !== undefined) clearTimeout(entry.timer);
+		entry.timer = undefined;
+		entry.phase = next.phase;
+		entry.hostStatus = next.hostStatus;
+		if ("value" in next) entry.value = next.value;
+		if (next.error) entry.error = next.error;
+		entry.revision += 1;
+		const snapshot = snapshotOf(entry);
+		for (const queue of this.#watches) queue.push(snapshot);
+	}
+}
+
+function snapshotOf(entry: CompletionEntry): HandleSnapshot {
+	return { ref: entry.ref, phase: entry.phase, host_status: entry.hostStatus, revision: entry.revision };
+}
+
+function toHandleError(error: unknown, timedOut: boolean): HandleError {
+	if (timedOut) return { code: "completion_deadline", message: DEADLINE_MESSAGE };
+	if (error instanceof Error) {
+		const code = "code" in error && typeof error.code === "string" ? error.code : "completion_failed";
+		return { code, message: error.message };
+	}
+	return { code: "completion_failed", message: String(error) };
+}

package/src/handles/handle-args.ts

@@ -0,0 +1,103 @@
+import type { HandleRef, OutputRequest } from "@code-yeongyu/senpi";
+import { type Static, type TSchema, Type } from "typebox";
+import { Check, Errors } from "typebox/value";
+
+/** Wire shapes of the five reserved handle tools; every ref carries kind, id and run epoch so the host can fence it. */
+const handleRefSchema = Type.Object(
+	{
+		kind: Type.Union([Type.Literal("agent"), Type.Literal("completion"), Type.Literal("workpool")]),
+		id: Type.String({ minLength: 1 }),
+		run_epoch: Type.Integer({ minimum: 0 }),
+	},
+	{ additionalProperties: true },
+);
+
+export const WAIT_MODES = ["all", "any", "settled"] as const;
+export type WaitMode = (typeof WAIT_MODES)[number];
+
+const waitArgsSchema = Type.Object(
+	{
+		refs: Type.Array(handleRefSchema),
+		timeout: Type.Optional(Type.Number({ minimum: 0 })),
+		mode: Type.Optional(Type.Union(WAIT_MODES.map((mode) => Type.Literal(mode)))),
+	},
+	{ additionalProperties: false },
+);
+const refArgsSchema = Type.Object({ ref: handleRefSchema }, { additionalProperties: false });
+const outputArgsSchema = Type.Object(
+	{
+		ref: handleRefSchema,
+		format: Type.Optional(Type.Union([Type.Literal("raw"), Type.Literal("tail")])),
+		offset: Type.Optional(Type.Integer({ minimum: 0 })),
+		limit: Type.Optional(Type.Integer({ minimum: 1 })),
+	},
+	{ additionalProperties: false },
+);
+const sendArgsSchema = Type.Object(
+	{ ref: handleRefSchema, message: Type.String({ minLength: 1 }) },
+	{ additionalProperties: false },
+);
+
+export interface WaitRequest {
+	readonly refs: readonly HandleRef[];
+	readonly mode: WaitMode;
+	readonly timeoutSeconds?: number;
+}
+
+export class HandleArgumentsError extends Error {
+	readonly name = "HandleArgumentsError";
+	readonly code = "eval_handle_invalid_arguments";
+
+	constructor(helper: string, summary: string) {
+		super(`eval_handle_invalid_arguments: ${helper} received invalid arguments: ${summary}`);
+	}
+}
+
+export function parseWaitArgs(value: unknown): WaitRequest {
+	const parsed = parseWith(waitArgsSchema, value, "wait()");
+	if (parsed.timeout !== undefined && !Number.isFinite(parsed.timeout)) {
+		throw new HandleArgumentsError("wait()", "timeout must be a finite number of seconds >= 0");
+	}
+	return {
+		refs: parsed.refs.map(toRef),
+		mode: parsed.mode ?? "all",
+		...(parsed.timeout === undefined ? {} : { timeoutSeconds: parsed.timeout }),
+	};
+}
+
+export function parseRefArgs(value: unknown, helper: string): HandleRef {
+	return toRef(parseWith(refArgsSchema, value, helper).ref);
+}
+
+export function parseOutputArgs(value: unknown): { readonly ref: HandleRef; readonly request: OutputRequest } {
+	const parsed = parseWith(outputArgsSchema, value, "control.output()");
+	return {
+		ref: toRef(parsed.ref),
+		request: {
+			...(parsed.format === undefined ? {} : { format: parsed.format }),
+			...(parsed.offset === undefined ? {} : { offset: parsed.offset }),
+			...(parsed.limit === undefined ? {} : { limit: parsed.limit }),
+		},
+	};
+}
+
+export function parseSendArgs(value: unknown): { readonly ref: HandleRef; readonly message: string } {
+	const parsed = parseWith(sendArgsSchema, value, "control.send()");
+	return { ref: toRef(parsed.ref), message: parsed.message };
+}
+
+export function refKey(ref: HandleRef): string {
+	return `${ref.kind}:${ref.id}:${ref.run_epoch}`;
+}
+
+function toRef(value: Static<typeof handleRefSchema>): HandleRef {
+	return { kind: value.kind, id: value.id, run_epoch: value.run_epoch };
+}
+
+function parseWith<T extends TSchema>(schema: T, value: unknown, helper: string): Static<T> {
+	if (Check(schema, value)) return value;
+	const summary = Errors(schema, value)
+		.map((error) => `${error.instancePath || "/"} ${error.message}`)
+		.join("; ");
+	throw new HandleArgumentsError(helper, summary || "invalid value");
+}

package/src/handles/handle-registry.ts

@@ -0,0 +1,164 @@
+import {
+	type CancelReceipt,
+	EvalHandleError,
+	type EvalHandleHost,
+	type HandleCallContext,
+	type HandleOutcome,
+	type HandleRef,
+	type HandleSnapshot,
+	type HandleWatch,
+	type OutputRequest,
+	type OutputSnapshot,
+} from "@code-yeongyu/senpi";
+import { CompletionHandles, type CompletionStart } from "./completion-handles.ts";
+import { refKey } from "./handle-args.ts";
+import { mergeWatches } from "./watch-queue.ts";
+
+/** What a bridge call brings along: the session's host capability (if any) and the calling cell's signal. */
+export interface HandleBackend {
+	readonly host: EvalHandleHost | undefined;
+	readonly signal: AbortSignal | undefined;
+}
+
+export interface HandleRegistryOptions {
+	/** The agent session that owns this registry; every host call is fenced with it. */
+	readonly ownerSessionId: string;
+	readonly now?: () => number;
+}
+
+/**
+ * One registry per session generation (created at `session_start`, disposed in `dropRuntime`). Agent and
+ * workpool refs are routed to the session's `EvalHandleHost`; completion refs are codemode's own in-flight
+ * completions. After disposal every ref fails closed with `eval_handle_stale` before any host is touched.
+ */
+export class HandleRegistry {
+	readonly ownerSessionId: string;
+	readonly #completions: CompletionHandles;
+	readonly #open = new Set<HandleWatch>();
+	#disposed = false;
+
+	constructor(options: HandleRegistryOptions) {
+		this.ownerSessionId = options.ownerSessionId;
+		this.#completions = new CompletionHandles(options.now);
+	}
+
+	get disposed(): boolean {
+		return this.#disposed;
+	}
+
+	get openWatches(): number {
+		return this.#open.size;
+	}
+
+	get openCompletionWatches(): number {
+		return this.#completions.openWatches;
+	}
+
+	startCompletion(input: CompletionStart): HandleRef {
+		this.#assertLive();
+		return this.#completions.start(input);
+	}
+
+	async watch(refs: readonly HandleRef[], backend: HandleBackend): Promise<HandleWatch> {
+		this.#assertLive();
+		const local = refs.filter((ref) => this.#completions.owns(ref));
+		const remote = refs.filter((ref) => !this.#completions.owns(ref));
+		const host = remote.length > 0 ? this.#requireHost(backend, remote) : undefined;
+		const parts: HandleWatch[] = [];
+		if (local.length > 0) parts.push(this.#completions.watch(local));
+		if (host !== undefined) {
+			try {
+				parts.push(await host.watch(remote, this.#callContext(backend)));
+			} catch (error) {
+				for (const part of parts) part.close();
+				throw error;
+			}
+		}
+		const byKey = new Map(parts.flatMap((part) => part.initial.map((snapshot) => [refKey(snapshot.ref), snapshot])));
+		const ordered = refs.map((ref) => {
+			const snapshot = byKey.get(refKey(ref));
+			if (snapshot === undefined) throw new EvalHandleError("eval_handle_not_found", `no snapshot for ${ref.id}`);
+			return snapshot;
+		});
+		const merged = mergeWatches(ordered, parts);
+		const tracked: HandleWatch = {
+			initial: merged.initial,
+			updates: merged.updates,
+			close: () => {
+				merged.close();
+				this.#open.delete(tracked);
+			},
+		};
+		this.#open.add(tracked);
+		if (this.#disposed) tracked.close();
+		return tracked;
+	}
+
+	async status(ref: HandleRef, backend: HandleBackend): Promise<HandleSnapshot> {
+		const watch = await this.watch([ref], backend);
+		try {
+			const snapshot = watch.initial[0];
+			if (snapshot === undefined) throw new EvalHandleError("eval_handle_not_found", `no snapshot for ${ref.id}`);
+			return snapshot;
+		} finally {
+			watch.close();
+		}
+	}
+
+	async result(ref: HandleRef, backend: HandleBackend): Promise<HandleOutcome> {
+		this.#assertLive();
+		if (this.#completions.owns(ref)) return this.#completions.result(ref);
+		return await this.#requireHost(backend, [ref]).result(ref, this.#callContext(backend));
+	}
+
+	async send(ref: HandleRef, message: string, backend: HandleBackend): Promise<HandleSnapshot> {
+		this.#assertLive();
+		if (this.#completions.owns(ref)) {
+			throw new EvalHandleError("eval_handle_operation_unsupported", "send() is for agent handles only");
+		}
+		return await this.#requireHost(backend, [ref]).send(ref, message, this.#callContext(backend));
+	}
+
+	async cancel(ref: HandleRef, backend: HandleBackend): Promise<CancelReceipt> {
+		this.#assertLive();
+		if (this.#completions.owns(ref)) return this.#completions.cancel(ref);
+		return await this.#requireHost(backend, [ref]).cancel(ref, this.#callContext(backend));
+	}
+
+	async output(ref: HandleRef, request: OutputRequest, backend: HandleBackend): Promise<OutputSnapshot> {
+		this.#assertLive();
+		if (this.#completions.owns(ref)) return this.#completions.output(ref, request);
+		return await this.#requireHost(backend, [ref]).output(ref, request, this.#callContext(backend));
+	}
+
+	/** Closes every open watch and aborts every in-flight completion; later calls fail with `eval_handle_stale`. */
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		for (const watch of [...this.#open]) watch.close();
+		this.#open.clear();
+		this.#completions.dispose();
+	}
+
+	#assertLive(): void {
+		if (this.#disposed) {
+			throw new EvalHandleError("eval_handle_stale", "this session generation was dropped; its handles are gone");
+		}
+	}
+
+	#requireHost(backend: HandleBackend, refs: readonly HandleRef[]): EvalHandleHost {
+		if (backend.host !== undefined) return backend.host;
+		const kinds = [...new Set(refs.map((ref) => ref.kind))].join("/");
+		throw new EvalHandleError(
+			"eval_wait_unavailable",
+			`wait()/handle() over ${kinds} work is not supported by this runtime: no EvalHandleHost is provided for this session`,
+		);
+	}
+
+	#callContext(backend: HandleBackend): HandleCallContext {
+		return {
+			ownerSessionId: this.ownerSessionId,
+			...(backend.signal === undefined ? {} : { signal: backend.signal }),
+		};
+	}
+}