@code-yeongyu/senpi-codemode 2026.10.6 → 2026.10.8

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 }),
+		};
+	}
+}

package/src/handles/wait.ts

@@ -0,0 +1,214 @@
+import {
+	EvalHandleError,
+	type HandleOutcome,
+	type HandlePhase,
+	type HandleRef,
+	type HandleSnapshot,
+	type HandleWatch,
+} from "@code-yeongyu/senpi";
+import { refKey, type WaitRequest } from "./handle-args.ts";
+
+const MAX_TIMER_MS = 2 ** 31 - 1;
+
+export interface WaitBackend {
+	watch(refs: readonly HandleRef[]): Promise<HandleWatch>;
+	result(ref: HandleRef): Promise<HandleOutcome>;
+	readonly signal?: AbortSignal;
+}
+
+export type WaitAnyResult = { readonly index: number; readonly ref: HandleRef; readonly value: unknown };
+
+/** A handle's own failure, raised by `wait(..., {mode: "all"})` and `control.wait()`; `code` is in the text. */
+export class HandleOutcomeError extends Error {
+	readonly name = "HandleOutcomeError";
+	readonly code: string;
+	readonly ref: HandleRef;
+	readonly details: unknown;
+
+	constructor(outcome: Extract<HandleOutcome, { status: "rejected" }>) {
+		super(`${outcome.error.code}: ${outcome.error.message}`);
+		this.code = outcome.error.code;
+		this.ref = outcome.ref;
+		this.details = outcome.error.details;
+	}
+}
+
+export class WaitAllRejectedError extends Error {
+	readonly name = "WaitAllRejectedError";
+	readonly code = "eval_wait_all_rejected";
+	readonly outcomes: readonly HandleOutcome[];
+
+	constructor(outcomes: readonly HandleOutcome[]) {
+		const summary = outcomes
+			.map((outcome) =>
+				outcome.status === "rejected" ? `${outcome.ref.id}: ${outcome.error.code}` : outcome.ref.id,
+			)
+			.join("; ");
+		super(`eval_wait_all_rejected: wait(any) found no successful handle among ${outcomes.length}; ${summary}`);
+		this.outcomes = outcomes;
+	}
+}
+
+const TERMINAL: ReadonlySet<HandlePhase> = new Set(["succeeded", "failed", "cancelled", "lost"]);
+
+/**
+ * The in-cell barrier. Subscribes once per distinct ref, keeps duplicate slots, settles according to the
+ * mode, and never cancels work: a timeout only closes the subscription. The timeout runs from entry and,
+ * like cancelling the cell, also ends a wait that is still subscribing or fetching a result. Parked time
+ * is the caller's concern (the bridge-call path pauses the run budget around this call).
+ */
+export async function waitForHandles(request: WaitRequest, backend: WaitBackend): Promise<unknown> {
+	const { refs, mode } = request;
+	if (refs.length === 0) {
+		if (mode === "any") throw new EvalHandleError("eval_wait_empty", "wait(any) needs at least one handle");
+		return [];
+	}
+	const unique = [...new Map(refs.map((ref) => [refKey(ref), ref])).values()];
+	const outcomes = new Map<string, HandleOutcome>();
+	const revisions = new Map<string, number>();
+	const stop = interruption(request.timeoutSeconds, backend.signal, refs, outcomes);
+	let watch: HandleWatch | undefined;
+	const finish = (): unknown => {
+		switch (mode) {
+			case "all":
+				return refs.map((ref) => settledValue(outcomes, ref));
+			case "settled":
+				return refs.map((ref) => outcomeOf(outcomes, ref));
+			case "any":
+				return firstSuccess(refs, outcomes) ?? rejectAll(refs, outcomes);
+			default:
+				return assertNever(mode);
+		}
+	};
+	// Returns true once the mode can settle without waiting for the remaining handles.
+	const absorb = async (snapshot: HandleSnapshot): Promise<boolean> => {
+		const key = refKey(snapshot.ref);
+		const known = revisions.get(key);
+		if (known !== undefined && snapshot.revision <= known) return false;
+		revisions.set(key, snapshot.revision);
+		if (snapshot.ref.kind === "workpool" && snapshot.phase === "pending" && snapshot.host_status === "open") {
+			throw new EvalHandleError(
+				"eval_pool_open",
+				`workpool ${snapshot.ref.id} is still open; close() it before waiting`,
+			);
+		}
+		if (!TERMINAL.has(snapshot.phase) || outcomes.has(key)) return false;
+		const outcome = await stop.race(backend.result(snapshot.ref));
+		outcomes.set(key, outcome);
+		if (mode === "all" && outcome.status === "rejected") throw new HandleOutcomeError(outcome);
+		if (mode === "any" && outcome.status === "fulfilled") return true;
+		return outcomes.size === unique.length;
+	};
+	try {
+		const subscribing = backend.watch(unique);
+		// A watch that resolves after the wait already ended is closed, so its subscription never leaks.
+		void subscribing.then(
+			(late) => {
+				if (stop.ended) late.close();
+			},
+			() => undefined,
+		);
+		watch = await stop.race(subscribing);
+		for (const snapshot of watch.initial) {
+			if (await absorb(snapshot)) return finish();
+		}
+		if (outcomes.size === unique.length) return finish();
+		if (request.timeoutSeconds === 0) throw timeoutError(0, refs, outcomes);
+		const iterator = watch.updates[Symbol.asyncIterator]();
+		try {
+			while (true) {
+				const step = await stop.race(iterator.next());
+				if (step.done) return finish();
+				if (await absorb(step.value)) return finish();
+			}
+		} finally {
+			await iterator.return?.();
+		}
+	} finally {
+		stop.end();
+		watch?.close();
+	}
+}
+
+/** One deadline armed at entry plus the cell's abort; `race` rejects any pending step once either fires. */
+function interruption(
+	timeoutSeconds: number | undefined,
+	signal: AbortSignal | undefined,
+	refs: readonly HandleRef[],
+	outcomes: ReadonlyMap<string, HandleOutcome>,
+) {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let onAbort: (() => void) | undefined;
+	let ended = false;
+	const fired = new Promise<never>((_resolve, reject) => {
+		if (timeoutSeconds !== undefined && timeoutSeconds > 0) {
+			// A timer longer than the platform maximum fires at once, so a long deadline is armed in chunks.
+			const deadline = Date.now() + timeoutSeconds * 1_000;
+			const arm = (): void => {
+				const remainingMs = deadline - Date.now();
+				if (remainingMs <= 0) {
+					reject(timeoutError(timeoutSeconds, refs, outcomes));
+					return;
+				}
+				timer = setTimeout(arm, Math.min(remainingMs, MAX_TIMER_MS));
+			};
+			arm();
+		}
+		if (signal !== undefined) {
+			onAbort = () =>
+				reject(signal.reason instanceof Error ? signal.reason : new Error("wait() cancelled with its cell"));
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+		}
+	});
+	fired.catch(() => undefined);
+	return {
+		get ended(): boolean {
+			return ended;
+		},
+		race<T>(step: Promise<T>): Promise<T> {
+			return Promise.race([step, fired]);
+		},
+		end(): void {
+			ended = true;
+			if (timer !== undefined) clearTimeout(timer);
+			if (signal !== undefined && onAbort !== undefined) signal.removeEventListener("abort", onAbort);
+		},
+	};
+}
+
+function timeoutError(seconds: number, refs: readonly HandleRef[], outcomes: ReadonlyMap<string, HandleOutcome>) {
+	const settled = refs.filter((ref) => outcomes.has(refKey(ref))).length;
+	return new EvalHandleError(
+		"eval_wait_timeout",
+		`wait() timed out after ${seconds}s; ${settled}/${refs.length} handles settled; work was not cancelled`,
+	);
+}
+
+function outcomeOf(outcomes: ReadonlyMap<string, HandleOutcome>, ref: HandleRef): HandleOutcome {
+	const outcome = outcomes.get(refKey(ref));
+	if (outcome === undefined) throw new EvalHandleError("eval_handle_pending", `${ref.id} did not settle`);
+	return outcome;
+}
+
+function settledValue(outcomes: ReadonlyMap<string, HandleOutcome>, ref: HandleRef): unknown {
+	const outcome = outcomeOf(outcomes, ref);
+	if (outcome.status === "rejected") throw new HandleOutcomeError(outcome);
+	return outcome.value;
+}
+
+function firstSuccess(refs: readonly HandleRef[], outcomes: ReadonlyMap<string, HandleOutcome>) {
+	for (const [index, ref] of refs.entries()) {
+		const outcome = outcomes.get(refKey(ref));
+		if (outcome?.status === "fulfilled") return { index, ref, value: outcome.value } satisfies WaitAnyResult;
+	}
+	return undefined;
+}
+
+function rejectAll(refs: readonly HandleRef[], outcomes: ReadonlyMap<string, HandleOutcome>): never {
+	throw new WaitAllRejectedError(refs.map((ref) => outcomeOf(outcomes, ref)));
+}
+
+function assertNever(value: never): never {
+	throw new TypeError(`Unsupported wait mode: ${String(value)}`);
+}

package/src/handles/watch-queue.ts

@@ -0,0 +1,102 @@
+import type { HandleSnapshot, HandleWatch } from "@code-yeongyu/senpi";
+import { refKey } from "./handle-args.ts";
+
+/**
+ * A pull-side buffer for handle snapshots. Pushes queue up until the consumer iterates, so a change
+ * that lands between subscription and `initial` is delivered exactly once; `close()` is idempotent
+ * and ends the iterator.
+ */
+export class WatchQueue {
+	readonly #keys: ReadonlySet<string> | undefined;
+	readonly #queue: HandleSnapshot[] = [];
+	#wake: (() => void) | undefined;
+	#closed = false;
+	#failure: unknown;
+	#failed = false;
+
+	/** Without keys every snapshot is accepted (used by the merger); with keys only matching refs are. */
+	constructor(keys?: readonly string[]) {
+		this.#keys = keys === undefined ? undefined : new Set(keys);
+	}
+
+	get closed(): boolean {
+		return this.#closed;
+	}
+
+	push(snapshot: HandleSnapshot): void {
+		if (this.#closed || (this.#keys !== undefined && !this.#keys.has(refKey(snapshot.ref)))) return;
+		this.#queue.push(snapshot);
+		this.#wake?.();
+	}
+
+	close(): void {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#wake?.();
+	}
+
+	/** Ends the stream with an error: the next pull rejects instead of reporting a clean end. */
+	fail(error: unknown): void {
+		if (this.#closed) return;
+		this.#failed = true;
+		this.#failure = error;
+		this.close();
+	}
+
+	toWatch(initial: readonly HandleSnapshot[], onClose?: () => void): HandleWatch {
+		const close = (): void => {
+			this.close();
+			onClose?.();
+		};
+		const next = async (): Promise<IteratorResult<HandleSnapshot>> => {
+			while (this.#queue.length === 0 && !this.#closed) {
+				await new Promise<void>((resolve) => {
+					this.#wake = resolve;
+				});
+			}
+			this.#wake = undefined;
+			const value = this.#queue.shift();
+			if (value !== undefined) return { done: false, value };
+			if (this.#failed) throw this.#failure;
+			return { done: true, value: undefined };
+		};
+		const updates: AsyncIterable<HandleSnapshot> = {
+			[Symbol.asyncIterator]: () => ({
+				next,
+				return: async (): Promise<IteratorResult<HandleSnapshot>> => {
+					close();
+					return { done: true, value: undefined };
+				},
+			}),
+		};
+		return { initial, updates, close };
+	}
+}
+
+/** One watch over several: `initial` keeps the caller's order, updates from every part are drained eagerly. */
+export function mergeWatches(ordered: readonly HandleSnapshot[], parts: readonly HandleWatch[]): HandleWatch {
+	if (parts.length === 1 && parts[0] !== undefined) return { ...parts[0], initial: ordered };
+	const queue = new WatchQueue();
+	let open = parts.length;
+	const drain = async (part: HandleWatch): Promise<void> => {
+		try {
+			for await (const snapshot of part.updates) queue.push(snapshot);
+		} catch (error) {
+			queue.fail(error);
+		} finally {
+			open -= 1;
+			if (open === 0) queue.close();
+		}
+	};
+	if (parts.length === 0) queue.close();
+	for (const part of parts) void drain(part);
+	const merged = queue.toWatch(ordered);
+	return {
+		initial: merged.initial,
+		updates: merged.updates,
+		close: () => {
+			for (const part of parts) part.close();
+			merged.close();
+		},
+	};
+}