@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/interactive/leader-key.ts

@@ -0,0 +1,143 @@
+import type { ClioKeybinding } from "../domains/config/keybindings.js";
+import { isKeyRelease, type KeyId, matchesKey } from "../engine/tui.js";
+
+export interface LeaderTarget {
+	key: string;
+	id: ClioKeybinding;
+}
+
+export type LeaderKeyState = { status: "idle" } | { status: "pending"; expiresAt: number };
+
+export interface LeaderKeyRouteDeps {
+	matchesLeader: (data: string) => boolean;
+	leaderTargets: ReadonlyArray<LeaderTarget>;
+	dispatchAction: (id: ClioKeybinding) => boolean;
+	now: number;
+	timeoutMs?: number;
+	isRelease?: (data: string) => boolean;
+}
+
+export interface LeaderKeyRouteResult {
+	state: LeaderKeyState;
+	consumed: boolean;
+}
+
+export const LEADER_TIMEOUT_MS = 1500;
+export const IDLE_LEADER_STATE: LeaderKeyState = { status: "idle" };
+
+function baseLetterFromInput(data: string): string | null {
+	if (data.length === 1) {
+		const lower = data.toLowerCase();
+		return lower >= "a" && lower <= "z" ? lower : null;
+	}
+	for (let code = 97; code <= 122; code += 1) {
+		const key = String.fromCharCode(code) as KeyId;
+		if (matchesKey(data, key) || matchesKey(data, `shift+${key}` as KeyId)) return key;
+	}
+	return null;
+}
+
+function isEscapeKey(data: string): boolean {
+	return matchesKey(data, "escape") && !isKeyRelease(data);
+}
+
+/** Pure leader-key router: returns the next leader state and whether input was swallowed. */
+export function routeLeaderKey(data: string, state: LeaderKeyState, deps: LeaderKeyRouteDeps): LeaderKeyRouteResult {
+	const timeoutMs = deps.timeoutMs ?? LEADER_TIMEOUT_MS;
+	if (state.status === "pending") {
+		if (deps.now > state.expiresAt) return { state: IDLE_LEADER_STATE, consumed: true };
+		if (deps.isRelease?.(data) ?? false) return { state, consumed: true };
+		if (isEscapeKey(data)) return { state: IDLE_LEADER_STATE, consumed: true };
+		const base = baseLetterFromInput(data);
+		const target = base ? deps.leaderTargets.find((entry) => entry.key === base) : undefined;
+		if (target) {
+			deps.dispatchAction(target.id);
+			return { state: IDLE_LEADER_STATE, consumed: true };
+		}
+		return { state: IDLE_LEADER_STATE, consumed: true };
+	}
+	if (deps.isRelease?.(data) ?? false) return { state, consumed: false };
+	if (!deps.matchesLeader(data)) return { state, consumed: false };
+	return { state: { status: "pending", expiresAt: deps.now + timeoutMs }, consumed: true };
+}
+
+export interface LeaderKeyTimeout {
+	unref?(): void;
+}
+
+export interface LeaderKeyControllerDeps {
+	matchesLeader: (data: string) => boolean;
+	leaderTargets: () => ReadonlyArray<LeaderTarget>;
+	dispatchAction: (id: ClioKeybinding) => boolean;
+	isRelease: (data: string) => boolean;
+	now?: () => number;
+	timeoutMs?: number;
+	scheduleTimeout?: (callback: () => void, delayMs: number) => LeaderKeyTimeout;
+	clearScheduledTimeout?: (timeout: LeaderKeyTimeout) => void;
+	/**
+	 * Fired when the leader arms or disarms, including on timeout.
+	 *
+	 * Ctrl+G is the fallback for terminals where Alt is broken, and the frame
+	 * between it and the next key was identical to the idle frame: nothing said
+	 * the leader had taken, on the one surface whose users cannot test it with a
+	 * working Alt shortcut.
+	 */
+	onStateChange?: (pending: boolean) => void;
+}
+
+export interface LeaderKeyController {
+	isPending(): boolean;
+	route(data: string): boolean;
+	reset(): void;
+	dispose(): void;
+}
+
+export function createLeaderKeyController(deps: LeaderKeyControllerDeps): LeaderKeyController {
+	const now = deps.now ?? Date.now;
+	const scheduleTimeout = deps.scheduleTimeout ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+	const clearScheduledTimeout =
+		deps.clearScheduledTimeout ?? ((timeout: LeaderKeyTimeout) => clearTimeout(timeout as ReturnType<typeof setTimeout>));
+	let state: LeaderKeyState = IDLE_LEADER_STATE;
+	let timer: LeaderKeyTimeout | null = null;
+
+	const setState = (next: LeaderKeyState): void => {
+		const wasPending = state.status === "pending";
+		state = next;
+		if (timer) {
+			clearScheduledTimeout(timer);
+			timer = null;
+		}
+		if (next.status !== "pending") {
+			if (wasPending) deps.onStateChange?.(false);
+			return;
+		}
+		if (!wasPending) deps.onStateChange?.(true);
+		timer = scheduleTimeout(
+			() => {
+				state = IDLE_LEADER_STATE;
+				timer = null;
+				deps.onStateChange?.(false);
+			},
+			Math.max(0, next.expiresAt - now()),
+		);
+		timer.unref?.();
+	};
+
+	return {
+		isPending: () => state.status === "pending",
+		route: (data) => {
+			const result = routeLeaderKey(data, state, {
+				matchesLeader: deps.matchesLeader,
+				leaderTargets: deps.leaderTargets(),
+				dispatchAction: deps.dispatchAction,
+				now: now(),
+				...(deps.timeoutMs === undefined ? {} : { timeoutMs: deps.timeoutMs }),
+				isRelease: deps.isRelease,
+			});
+			if (result.state !== state) setState(result.state);
+			return result.consumed;
+		},
+		reset: () => setState(IDLE_LEADER_STATE),
+		dispose: () => setState(IDLE_LEADER_STATE),
+	};
+}

package/src/interactive/loop-guard-interrupt.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared loop-guard interrupt handling. The backend loop guard
+ * (engine/loop-guard.ts) emits `LoopBlocked`/`ToolBudgetExceeded` over the bus;
+ * when a turn is interrupted, the active turn must be stopped with a durable,
+ * visible closing message rather than left to spin.
+ *
+ * The interactive TUI wires its own subscriber (it also renders the per-block
+ * warn notices). Operatorless surfaces (headless `clio-coder run`, ACP) have no such
+ * subscriber, so a degenerate local model spins until an external timeout: the
+ * `block_tool` effect blocks each call but nothing aborts the run. This module
+ * is the single source of truth for the closing-message text and the
+ * interrupt-to-stop subscriber both surfaces use, so messaging never drifts.
+ */
+
+import { BusChannels, type LoopBlockedPayload, type ToolBudgetExceededPayload } from "../core/bus-events.js";
+import type { SafeEventBus } from "../core/event-bus.js";
+import type { ChatCancelOptions } from "./chat-loop.js";
+
+/** Minimal chat surface the loop-guard stop needs: only the cancel entry point. */
+export interface LoopGuardStoppableChat {
+	cancel(options?: ChatCancelOptions): void;
+}
+
+function isLoopBlockedInterrupt(payload: unknown): payload is LoopBlockedPayload {
+	const evt = payload as LoopBlockedPayload | null | undefined;
+	return (
+		!!evt &&
+		typeof evt === "object" &&
+		evt.interrupted === true &&
+		typeof evt.tool === "string" &&
+		typeof evt.repeatCount === "number"
+	);
+}
+
+function isToolBudgetInterrupt(payload: unknown): payload is ToolBudgetExceededPayload {
+	const evt = payload as ToolBudgetExceededPayload | null | undefined;
+	return (
+		!!evt &&
+		typeof evt === "object" &&
+		evt.interrupted === true &&
+		typeof evt.tool === "string" &&
+		typeof evt.callsThisTurn === "number"
+	);
+}
+
+/** Operator-facing closing message for an identical-call loop interrupt. */
+export function loopBlockedStopReason(evt: LoopBlockedPayload): string {
+	const blockWord = evt.blocksThisTurn === 1 ? "block" : "blocks";
+	return (
+		`[Clio Coder] loop guard stopped this turn: ${evt.tool} was called with identical arguments ` +
+		`${evt.repeatCount} times without new results (${evt.blocksThisTurn} loop ${blockWord}). I likely ` +
+		`already have enough to answer. Ask me to continue with a different approach, or narrow the request.`
+	);
+}
+
+/** Operator-facing closing message for a per-turn tool-call ceiling interrupt. */
+export function toolBudgetStopReason(evt: ToolBudgetExceededPayload): string {
+	return (
+		`[Clio Coder] loop guard stopped this turn: ${evt.callsThisTurn} tool calls reached the per-turn ceiling ` +
+		`(${evt.hardCeiling}) without converging. Tell me a single concrete next step, or narrow the request.`
+	);
+}
+
+/** Audit reason (short) for an identical-call loop interrupt. */
+export function loopBlockedAuditReason(evt: LoopBlockedPayload): string {
+	return `loop: ${evt.tool} repeated ${evt.repeatCount}x`;
+}
+
+/** Audit reason (short) for a tool-call ceiling interrupt. */
+export function toolBudgetAuditReason(evt: ToolBudgetExceededPayload): string {
+	return `tool-call ceiling: ${evt.callsThisTurn} calls`;
+}
+
+/**
+ * Stop the active turn with a durable closing message when the loop guard
+ * interrupts. Used by the operatorless surfaces (headless, ACP); the
+ * interactive TUI wires the equivalent inline so it can also render the
+ * per-block warn notices. Returns an unsubscribe handle.
+ */
+export function subscribeLoopGuardStop(bus: SafeEventBus, chat: LoopGuardStoppableChat): () => void {
+	const unsubscribeLoopBlocked = bus.on(BusChannels.LoopBlocked, (payload) => {
+		if (!isLoopBlockedInterrupt(payload)) return;
+		chat.cancel({
+			reason: loopBlockedStopReason(payload),
+			source: "loop_guard",
+			auditReason: loopBlockedAuditReason(payload),
+		});
+	});
+	const unsubscribeToolBudget = bus.on(BusChannels.ToolBudgetExceeded, (payload) => {
+		if (!isToolBudgetInterrupt(payload)) return;
+		chat.cancel({
+			reason: toolBudgetStopReason(payload),
+			source: "loop_guard",
+			auditReason: toolBudgetAuditReason(payload),
+		});
+	});
+	return () => {
+		unsubscribeLoopBlocked();
+		unsubscribeToolBudget();
+	};
+}

package/src/interactive/memory-overlay.ts

@@ -0,0 +1,280 @@
+import {
+	describeTaskMemoryActivity,
+	type MemoryRecord,
+	type TaskMemoryActivityEvent,
+	type TaskMemoryEntry,
+	type TaskMemoryOperatorStatus,
+	type TaskMemorySnapshot,
+	type TaskMemoryTelemetryDecision,
+} from "../domains/memory/index.js";
+import type { Component, OverlayHandle, TUI } from "../engine/tui.js";
+import { clockLocal } from "./format-time.js";
+import { showClioOverlayFrame } from "./overlay-frame.js";
+import { type ListOverlayItem, ListOverlayView } from "./overlays/list-overlay.js";
+import { clioTheme, fitUnits, rule } from "./theme/index.js";
+
+const DEFAULT_CONTENT_WIDTH = 96;
+const REFRESH_MS = 1_000;
+
+export const MEMORY_OVERLAY_WIDTH = DEFAULT_CONTENT_WIDTH + 4;
+
+const EMPTY_MESSAGE = "no approved lessons, task-bank entries, or memory steps captured yet.";
+
+/**
+ * The one-line header that stays above the list.
+ *
+ * `step running` rides here rather than in a row because a detached step has no
+ * row of its own until it finishes, and an operator who cannot see it in flight
+ * reads an unchanged bank as an idle memory agent.
+ */
+export function formatMemoryStatusLine(status: TaskMemoryOperatorStatus, contentWidth: number): string {
+	const theme = clioTheme();
+	const width = Math.max(1, Math.floor(contentWidth));
+	const units = [
+		theme.fg(status.enabled ? "success" : "dim", `memory ${status.enabled ? "on" : "off"}`),
+		theme.fg(status.tier === "llm" ? "reason" : "muted", `tier ${status.tier === "llm" ? "LLM" : "rules"}`),
+		theme.fg("muted", `bank ${status.size}`),
+		theme.fg("muted", `last ${status.lastDecision ?? "none"}`),
+	];
+	if (status.stepInFlight) units.push(theme.fg("reason", "step running"));
+	return fitUnits(theme, "", units, width);
+}
+
+function bankEntries(snapshot: TaskMemorySnapshot): TaskMemoryEntry[] {
+	return [...(snapshot.status === null ? [] : [snapshot.status]), ...snapshot.knowledge, ...snapshot.procedural];
+}
+
+function firstLine(content: string): string {
+	return content.replace(/\s+/gu, " ").trim();
+}
+
+function entryClassLabel(entry: TaskMemoryEntry): string {
+	return entry.kind === "status" ? "status (private)" : entry.kind;
+}
+
+function lessonItems(records: ReadonlyArray<MemoryRecord>, group: string): ListOverlayItem[] {
+	const theme = clioTheme();
+	return records.map((record) => ({
+		id: `lesson:${record.id}`,
+		label: firstLine(record.lesson),
+		meta: theme.fg("dim", `${record.scope}:${record.key}`),
+		group,
+		detail: () => [
+			`# ${record.id}`,
+			`**Scope:** ${record.scope}:${record.key}`,
+			`**Confidence:** ${record.confidence}`,
+			`**Created:** ${record.createdAt}`,
+			...(record.evidenceRefs.length > 0 ? [`**Evidence:** ${record.evidenceRefs.join(", ")}`] : []),
+			...(record.appliesWhen.length > 0 ? [`**Applies when:** ${record.appliesWhen.join("; ")}`] : []),
+			...(record.avoidWhen.length > 0 ? [`**Avoid when:** ${record.avoidWhen.join("; ")}`] : []),
+			"",
+			"---",
+			"",
+			record.lesson,
+		],
+	}));
+}
+
+function bankItems(entries: ReadonlyArray<TaskMemoryEntry>, group: string): ListOverlayItem[] {
+	const theme = clioTheme();
+	return entries.map((entry) => ({
+		id: `bank:${entry.id}`,
+		label: firstLine(entry.content),
+		meta: theme.fg("dim", `${entryClassLabel(entry)} · injected ${entry.injectionCount}`),
+		group,
+		detail: () => [
+			`# ${entry.id}`,
+			`**Class:** ${entryClassLabel(entry)}`,
+			`**Injected:** ${entry.injectionCount}`,
+			`**Created:** ${entry.createdAt}`,
+			`**Last touched:** ${entry.lastTouchedAt}`,
+			"",
+			"---",
+			"",
+			entry.content,
+		],
+	}));
+}
+
+/**
+ * The row clock, in the timezone the operator's own clock is in.
+ *
+ * `event.at` is an ISO-8601 UTC instant, so slicing `HH:MM:SS` out of it
+ * printed a UTC clock with no marker saying so: a step captured at 06:18 CDT
+ * rendered as 11:18 and read as five hours stale. The detail pane keeps the
+ * ISO string, so converting here is what makes the two surfaces agree.
+ */
+function rowClock(at: string): string {
+	return Number.isFinite(Date.parse(at)) ? clockLocal(at) : at;
+}
+
+function activityItems(events: ReadonlyArray<TaskMemoryActivityEvent>, group: string): ListOverlayItem[] {
+	const theme = clioTheme();
+	return events.map((event, index) => ({
+		id: `step:${index}:${event.at}`,
+		label: `${theme.fg("dim", rowClock(event.at))} ${theme.fg(
+			decisionToken(event.decision),
+			describeTaskMemoryActivity(event),
+		)}`,
+		meta: theme.fg("dim", `${event.tier} ${Math.round(event.latencyMs)}ms`),
+		group,
+		detail: () => [
+			`# ${event.at}`,
+			`**Decision:** ${event.decision} (${event.reason})`,
+			`**Triggers:** ${event.triggerReasons.join(", ")}`,
+			`**Tier:** ${event.tier}`,
+			`**Latency:** ${Math.round(event.latencyMs)}ms`,
+			`**Bank writes:** ${event.bankWrites}`,
+			`**Cited entries:** ${event.citedEntries}`,
+		],
+	}));
+}
+
+/**
+ * Every memory row the operator can reach, as one grouped list.
+ *
+ * The counts live in the group headers because the static dump printed them as
+ * section titles and they are the only place a reader learns that a class is
+ * empty: a group with no rows renders no header at all.
+ */
+export function buildMemoryOverlayItems(
+	status: TaskMemoryOperatorStatus,
+	records: ReadonlyArray<MemoryRecord>,
+): ListOverlayItem[] {
+	const approved = records.filter((record) => record.approved && record.rejectedAt === undefined);
+	const entries = bankEntries(status.bank);
+	return [
+		...lessonItems(approved, `approved lessons (${approved.length})`),
+		...bankItems(entries, `task bank (${status.size})`),
+		...activityItems(status.activity, `recent steps (${status.activity.length})`),
+	];
+}
+
+function decisionToken(decision: TaskMemoryTelemetryDecision): "success" | "warning" | "muted" {
+	if (decision === "injected") return "success";
+	return decision === "silent" ? "muted" : "warning";
+}
+
+/**
+ * A signature of everything the rows are built from.
+ *
+ * The overlay repaints once a second whether or not memory moved. Rebuilding
+ * the item array on every one of those frames would hand the list a fresh
+ * array each time, which resets nothing by itself but defeats both the list's
+ * render memo and the frame's identity cache; keying the rebuild on the data
+ * means an idle second costs one string compare.
+ */
+function memorySignature(status: TaskMemoryOperatorStatus, records: ReadonlyArray<MemoryRecord>): string {
+	const parts = [
+		status.enabled ? "on" : "off",
+		status.tier,
+		String(status.size),
+		status.lastDecision ?? "none",
+		status.stepInFlight ? "running" : "idle",
+	];
+	for (const record of records) parts.push(`r:${record.id}:${record.approved}:${record.rejectedAt ?? ""}`);
+	for (const entry of bankEntries(status.bank)) {
+		parts.push(`e:${entry.id}:${entry.lastTouchedAt}:${entry.injectionCount}`);
+	}
+	for (const event of status.activity) parts.push(`a:${event.at}:${event.decision}`);
+	return parts.join("|");
+}
+
+interface OpenMemoryOverlayOptions {
+	onClose?: () => void;
+}
+
+/** Master-detail memory view: status header, grouped list, scrollable detail pane. */
+export class MemoryOverlayView implements Component {
+	private readonly list: ListOverlayView;
+	private signature: string | null = null;
+	private renderMemo: { width: number; status: string; listLines: string[]; lines: string[] } | null = null;
+
+	constructor(
+		private readonly getStatus: () => TaskMemoryOperatorStatus,
+		private readonly getRecords: () => ReadonlyArray<MemoryRecord>,
+		onClose: () => void,
+		onChange: () => void,
+	) {
+		this.list = new ListOverlayView(
+			{
+				title: "Memory",
+				items: [],
+				filterable: true,
+				layout: "split",
+				emptyMessage: EMPTY_MESSAGE,
+				onClose,
+			},
+			onChange,
+		);
+	}
+
+	getHint(): string {
+		this.sync();
+		return this.list.getHint();
+	}
+
+	render(width: number): string[] {
+		const status = this.sync();
+		const statusLine = formatMemoryStatusLine(status, width);
+		const listLines = this.list.render(width);
+		const memo = this.renderMemo;
+		if (memo && memo.width === width && memo.status === statusLine && memo.listLines === listLines) return memo.lines;
+		const lines = [statusLine, rule(clioTheme(), width), ...listLines];
+		this.renderMemo = { width, status: statusLine, listLines, lines };
+		return lines;
+	}
+
+	handleInput(data: string): void {
+		// A key that lands between the refresh and the repaint must act on the rows
+		// the operator is looking at, so the sync happens before the routing.
+		this.sync();
+		this.list.handleInput(data);
+	}
+
+	invalidate(): void {
+		this.renderMemo = null;
+		this.list.invalidate();
+	}
+
+	private sync(): TaskMemoryOperatorStatus {
+		const status = this.getStatus();
+		const records = this.getRecords();
+		const signature = memorySignature(status, records);
+		if (signature !== this.signature) {
+			this.signature = signature;
+			this.list.setItems(buildMemoryOverlayItems(status, records));
+		}
+		return status;
+	}
+}
+
+/** Mount the read-only durable-lessons and live task-bank view. */
+export function openMemoryOverlay(
+	tui: TUI,
+	getStatus: () => TaskMemoryOperatorStatus,
+	getRecords: () => ReadonlyArray<MemoryRecord>,
+	options: OpenMemoryOverlayOptions = {},
+): OverlayHandle {
+	const view = new MemoryOverlayView(
+		getStatus,
+		getRecords,
+		() => options.onClose?.(),
+		() => tui.requestRender(),
+	);
+	const handle = showClioOverlayFrame(tui, view, {
+		anchor: "center",
+		width: MEMORY_OVERLAY_WIDTH,
+		title: () => "Memory",
+		footerHint: () => view.getHint(),
+	});
+	const timer = setInterval(() => tui.requestRender(), REFRESH_MS);
+	timer.unref?.();
+	return {
+		...handle,
+		hide(): void {
+			clearInterval(timer);
+			handle.hide();
+		},
+	};
+}

package/src/interactive/overlay-ask-user-lifecycle.ts

@@ -0,0 +1,110 @@
+import type { TUI } from "../engine/tui.js";
+import { type AskUserHandler, cancelledAskUserResult } from "../tools/ask-user.js";
+import type { OverlayState } from "./overlay-key-routing.js";
+import { type AskUserOverlaySession, openAskUserOverlay } from "./overlays/ask-user.js";
+
+export interface OverlayAskUserLifecycleDeps {
+	tui: TUI;
+	getOverlayState(): OverlayState;
+	setOverlayState(state: OverlayState): void;
+	getOverlayHandle(): unknown;
+	setOverlayHandle(handle: AskUserOverlaySession | null): void;
+	renderContextIsland(): void;
+	renderTaskIsland(): void;
+	requestRender(): void;
+	registerHandler?(handler: AskUserHandler): () => void;
+	openAskUserOverlay?: typeof openAskUserOverlay;
+}
+
+export interface OverlayAskUserLifecycle {
+	handler: AskUserHandler;
+	close(): void;
+	cancel(): void;
+	cancelPending(): boolean;
+	isWaiting(): boolean;
+	resetCancellation(): void;
+	dispose(): void;
+}
+
+export function createOverlayAskUserLifecycle(deps: OverlayAskUserLifecycleDeps): OverlayAskUserLifecycle {
+	let pendingCancel: (() => void) | null = null;
+	let session: AskUserOverlaySession | null = null;
+	let cancelledForTurn = false;
+	let unregisterHandler: (() => void) | null = null;
+	const openSession = deps.openAskUserOverlay ?? openAskUserOverlay;
+
+	const refresh = (): void => {
+		deps.renderContextIsland();
+		deps.renderTaskIsland();
+		deps.requestRender();
+	};
+
+	const close = (): void => {
+		pendingCancel = null;
+		const current = session;
+		session = null;
+		if (current) {
+			current.close();
+			if (deps.getOverlayHandle() === current) deps.setOverlayHandle(null);
+		} else if (deps.getOverlayState() === "ask-user") {
+			const handle = deps.getOverlayHandle() as { hide?: () => void } | null;
+			handle?.hide?.();
+			deps.setOverlayHandle(null);
+		}
+		if (deps.getOverlayState() === "ask-user") deps.setOverlayState("closed");
+		refresh();
+	};
+
+	const ensureSession = (): AskUserOverlaySession | null => {
+		if (deps.getOverlayState() !== "closed" && deps.getOverlayState() !== "ask-user") return null;
+		if (session) return session;
+		deps.setOverlayState("ask-user");
+		session = openSession(deps.tui, { onCancel: () => pendingCancel?.() });
+		deps.setOverlayHandle(session);
+		deps.requestRender();
+		return session;
+	};
+
+	const cancel = (): void => {
+		cancelledForTurn = true;
+		session?.cancel();
+		close();
+	};
+
+	const handler: AskUserHandler = async (questions, invokeOptions) => {
+		const toolBacked = Boolean(invokeOptions?.turnId || invokeOptions?.toolCallId);
+		if (toolBacked && cancelledForTurn) return cancelledAskUserResult();
+		const activeSession = ensureSession();
+		if (!activeSession) return cancelledAskUserResult();
+		pendingCancel = cancel;
+		const result = await activeSession.ask(questions);
+		if (result.cancelled === true || !toolBacked) {
+			if (result.cancelled === true) cancelledForTurn = true;
+			close();
+		} else {
+			refresh();
+		}
+		return result;
+	};
+
+	unregisterHandler = deps.registerHandler?.(handler) ?? null;
+	return {
+		handler,
+		close,
+		cancel,
+		cancelPending: () => {
+			if (!pendingCancel) return false;
+			pendingCancel();
+			return true;
+		},
+		isWaiting: () => session?.isWaiting() ?? false,
+		resetCancellation: () => {
+			cancelledForTurn = false;
+		},
+		dispose: () => {
+			unregisterHandler?.();
+			unregisterHandler = null;
+			pendingCancel?.();
+		},
+	};
+}