opencode-clm 0.1.1 → 0.3.0

package/src/tui/data.ts

@@ -0,0 +1,241 @@
+// Host data the TUI panel needs, extracted from plain values so it is testable without
+// opentui: the server plugin's options, the newest provider count, the model limits and
+// the read-only settings rows. Written for this package.
+
+import { resolveBudget } from "../budget.ts";
+import type { LatestUsage, PanelModel, PanelSettings, SettingRow } from "../panel/model.ts";
+import { formatTokenCount, type TimelinePoint } from "../panel/timeline.ts";
+import type { ClmSettings } from "../settings.ts";
+import { applyOverrides, changedSettings, sanitizeOverrides, SETTINGS_TABLE, type FormatContext, type SettingsValues } from "../settings-table.ts";
+
+/**
+ * The package by name, with any version, tag or source after `@` (`opencode-clm`,
+ * `opencode-clm@0.2.0`, `opencode-clm@latest`, `opencode-clm@file:/x/opencode-clm-0.2.0.tgz`
+ * as `opencode plugin <tarball>` writes it), optionally behind `npm:`.
+ */
+const NPM_SPEC = /^(?:npm:)?opencode-clm(?:@.*)?$/;
+/** A path or URL whose last segment names the package (a checkout, an unpacked or packed copy). */
+const PATH_NAME = /(?:^|\/)opencode-clm(?:@[^/]*|-\d[^/]*\.tgz)?\/?$/;
+
+/** True when a server plugin spec names this package. */
+export function isPackageSpec(spec: string, packageIndexUrl: string): boolean {
+	if (NPM_SPEC.test(spec)) return true;
+	// Another package's `name@version-or-source`: the source may be a path, but the name decides.
+	if (/^(?:npm:)?(?:@[^/@]+\/)?[^@/.~][^@/]*@/.test(spec)) return false;
+	const target = normalizeUrl(packageIndexUrl);
+	const packageDirectory = target.replace(/\/index\.ts$/, "");
+	const path = spec.startsWith("file:") ? normalizeUrl(spec) : spec.includes("/") ? spec.replace(/\/+$/, "") : undefined;
+	if (path === undefined) return false;
+	if (path === target || path === packageDirectory) return true;
+	return PATH_NAME.test(path) || /(?:^|\/)opencode-clm\/index\.ts$/.test(path);
+}
+
+/**
+ * Options of the server plugin entry in `api.state.config.plugin` (see `isPackageSpec`).
+ * Undefined when no entry matches (the caller falls back to the TUI plugin's options).
+ */
+export function serverPluginOptions(entries: unknown, packageIndexUrl: string): Record<string, unknown> | undefined {
+	if (!Array.isArray(entries)) return undefined;
+	for (const entry of entries) {
+		const [spec, options] = Array.isArray(entry) ? entry : [entry, undefined];
+		if (typeof spec !== "string") continue;
+		if (!isPackageSpec(spec, packageIndexUrl)) continue;
+		return options && typeof options === "object" && !Array.isArray(options) ? (options as Record<string, unknown>) : {};
+	}
+	return undefined;
+}
+
+function normalizeUrl(value: string): string {
+	try {
+		return decodeURIComponent(new URL(value).pathname).replace(/\/+$/, "");
+	} catch {
+		return value;
+	}
+}
+
+interface MessageLike {
+	role?: string;
+	time?: { created?: number; completed?: number };
+	error?: unknown;
+	summary?: boolean;
+	tokens?: { input?: number; cache?: { read?: number; write?: number } };
+	providerID?: string;
+	modelID?: string;
+}
+
+/**
+ * The newest assistant reply with usage, measured as clm.ts measures `observedPrevious`
+ * (input + cache read + cache write). Errored and summary messages are skipped.
+ */
+export function latestUsage(messages: ReadonlyArray<unknown>): LatestUsage | undefined {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index] as MessageLike;
+		if (message?.role !== "assistant" || message.error || message.summary || !message.tokens) continue;
+		const tokens = Number(message.tokens.input ?? 0) + Number(message.tokens.cache?.read ?? 0) + Number(message.tokens.cache?.write ?? 0);
+		if (!Number.isFinite(tokens) || tokens <= 0) continue;
+		return { tokens, ...(message.time?.completed !== undefined ? { completedAt: message.time.completed } : {}) };
+	}
+	return undefined;
+}
+
+/** Context and output limits of the model of the newest assistant message. */
+export function modelLimits(messages: ReadonlyArray<unknown>, providers: ReadonlyArray<unknown>): { context?: number; output?: number } {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index] as MessageLike;
+		if (message?.role !== "assistant" || !message.providerID || !message.modelID) continue;
+		const provider = providers.find((item) => (item as { id?: string })?.id === message.providerID) as
+			| { models?: Record<string, { limit?: { context?: number; output?: number } }> }
+			| undefined;
+		const limit = provider?.models?.[message.modelID]?.limit;
+		return { context: limit?.context, output: limit?.output };
+	}
+	return {};
+}
+
+/** Budget for sessions without snapshot.json, resolved as the server resolves it. */
+export function fallbackBudget(settings: ClmSettings, limits: { context?: number; output?: number }) {
+	const resolved = resolveBudget(settings.budget, limits.context, limits.output);
+	if (!resolved) return undefined;
+	const cap = limits.context !== undefined
+		? limits.context - (limits.output !== undefined && limits.output > 0 && limits.output < limits.context ? limits.output : 0)
+		: undefined;
+	return { budget: resolved.budget, reserve: resolved.reserve, source: resolved.source, ...(cap !== undefined ? { cap } : {}) };
+}
+
+/**
+ * Settings page rows from the settings table: the values in force (base + this session's
+ * overrides.json), marked when changed, with choices or a placeholder so Enter cycles or
+ * prompts. `base` is what the session would use without overrides.
+ */
+export function settingsView(
+	values: { base: SettingsValues; effective: SettingsValues },
+	model: Pick<PanelModel, "budgetInfo" | "timeline" | "mirrorPath"> & Partial<Pick<PanelModel, "calibration" | "steering" | "annotations">>,
+	options: { format?: FormatContext; warning?: string } = {},
+): PanelSettings {
+	const changed = new Set<string>(changedSettings(values.base, values.effective));
+	const rows: SettingRow[] = SETTINGS_TABLE.map((item) => ({
+		key: item.name,
+		label: item.label,
+		value: item.format(values.effective, options.format),
+		description: `${item.description} Default: ${item.format(values.base, options.format)}.`,
+		...(changed.has(item.key) ? { changed: true } : {}),
+		...(item.choices ? { choices: item.choices } : {}),
+		...(item.placeholder ? { placeholder: item.placeholder } : {}),
+	}));
+	const latest = model.timeline.points.at(-1);
+	const summary: string[] = [];
+	if (latest) summary.push(sizeLine(latest, model.budgetInfo?.budget));
+	const info = model.budgetInfo;
+	if (info?.overhead !== undefined) summary.push(`Fixed overhead ~${formatTokenCount(info.overhead)} · usable ${formatTokenCount(info.usable ?? 0)}`);
+	summary.push(...detailLines(values.effective, model));
+	summary.push(`Files mirror ${model.mirrorPath}`);
+	return {
+		rows,
+		summary,
+		changed: SETTINGS_TABLE.filter((item) => changed.has(item.key)).map((item) => item.name),
+		...(options.warning ? { warning: options.warning } : {}),
+	};
+}
+
+/**
+ * pi's settings-page Size line ("next request ~E of B · last request M (provider count)").
+ * pi's "next request" is the estimate of the request built last, here the newest request.
+ * The line shows its provider count and the logged estimate side by side. The budget is
+ * today's, so after a budget change it is off until the next request.
+ */
+export function sizeLine(latest: Pick<TimelinePoint, "tokens" | "measured" | "estimated">, budget?: number): string {
+	const of = budget !== undefined ? ` of ${formatTokenCount(budget)}` : "";
+	if (!latest.measured) return `Size last request ~${formatTokenCount(latest.tokens)}${of} (estimate)`;
+	const estimate = latest.estimated !== undefined ? ` · estimated ~${formatTokenCount(latest.estimated)}` : "";
+	return `Size last request ${formatTokenCount(latest.tokens)}${of} (provider count)${estimate}`;
+}
+
+/**
+ * Footer text in the session prompt's right slot, as pi's status line:
+ * `clm 12k / 32k · r2` (newest size against the budget in force), `clm off · r2`, or
+ * undefined before the session has CLM data.
+ */
+export function footerText(model: Pick<PanelModel, "found" | "enabled" | "revision" | "timeline" | "budget">): string | undefined {
+	if (!model.found) return undefined;
+	if (!model.enabled) return `clm off · r${model.revision}`;
+	const latest = model.timeline.points.at(-1);
+	const size = latest === undefined
+		? ""
+		: ` ${latest.measured ? "" : "~"}${formatTokenCount(latest.tokens)}${model.budget !== undefined ? ` / ${formatTokenCount(model.budget)}` : ""}`;
+	return `clm${size} · r${model.revision}`;
+}
+
+/** Key of the settings page's "Reset to defaults" row, and the choice that resets. */
+export const RESET_ROW = "reset";
+export const RESET_NOW = "reset now";
+
+/**
+ * pi's "Reset to defaults" row: Enter cycles to "reset now", which drops this session's
+ * changes (the same as `/clm config reset`). With nothing changed Enter does nothing.
+ */
+export function resetRow(changed: number): SettingRow {
+	const value = changed === 0 ? "nothing changed" : `${changed} changed`;
+	return {
+		key: RESET_ROW,
+		label: "Reset to defaults",
+		value,
+		description: "Drop this session's changes; the plugin options, environment and defaults apply again from the next request. Same as /clm config reset. Enter on \"reset now\" resets at once.",
+		choices: changed === 0 ? [value] : [value, RESET_NOW],
+	};
+}
+
+/**
+ * Settings-page details after the size lines (pi's settings summary): calibration, the
+ * overflow guard's limit, the steering document with its hash, annotation counts.
+ */
+export function detailLines(
+	effective: SettingsValues,
+	model: Pick<PanelModel, "budgetInfo"> & Partial<Pick<PanelModel, "calibration" | "steering" | "annotations">>,
+): string[] {
+	const lines: string[] = [];
+	const calibration = model.calibration;
+	if (calibration) {
+		lines.push(calibration.samples === 0
+			? "Estimate not calibrated yet (characters ÷ 4 until the provider reports a size)"
+			: `Estimate ×${calibration.factor.toFixed(2)}, calibrated from ${calibration.samples} provider count${calibration.samples === 1 ? "" : "s"}`);
+	}
+	const limit = model.budgetInfo?.limit;
+	lines.push(effective.settings.guard === "off"
+		? "Guard off"
+		: `Guard withholds the oldest tool results above ${limit === undefined ? "budget − reserve" : formatTokenCount(limit)}`);
+	// pi appends the native-compaction state; `auto` and `on` leave OpenCode's own config.
+	if (effective.settings.compaction === "off") lines[lines.length - 1] += " · OpenCode's automatic compaction off";
+	// The hash prefix identifies an experiment arm (compare with sha256sum).
+	if (model.steering) lines.push(`Steering ${model.steering.name} (sha256 ${model.steering.hash}…)`);
+	const counts = model.annotations;
+	if (counts) {
+		lines.push(counts.total === 0
+			? "Annotations none"
+			: `Annotations ${counts.active} continuity/pin · ${counts.archived} archive · ${counts.total} total`);
+	}
+	return lines;
+}
+
+/**
+ * The server's base settings, from snapshot.json `base` (the server writes it each
+ * request), applied over the TUI's own resolution so non-table settings (mirrorDir…) stay.
+ * `tui` when there is no usable snapshot base yet.
+ */
+export function serverBase(own: ClmSettings, snapshot: unknown): { base: ClmSettings; source: "server" | "tui" } {
+	const raw = snapshot && typeof snapshot === "object" ? (snapshot as { base?: unknown }).base : undefined;
+	if (!raw || typeof raw !== "object") return { base: own, source: "tui" };
+	const { overrides } = sanitizeOverrides(raw);
+	try {
+		return { base: applyOverrides(own, overrides), source: "server" };
+	} catch {
+		return { base: own, source: "tui" };
+	}
+}
+
+/** True when overrides.json (mtime, ms) is newer than snapshot.json's `at`, or there is no snapshot. */
+export function overridesNewer(overridesAt: number | undefined, snapshot: unknown): boolean {
+	if (overridesAt === undefined) return false;
+	const at = snapshot && typeof snapshot === "object" ? (snapshot as { at?: unknown }).at : undefined;
+	const snapshotAt = typeof at === "string" ? Date.parse(at) : Number.NaN;
+	return !Number.isFinite(snapshotAt) || overridesAt > snapshotAt;
+}

package/src/tui/intercept.ts

@@ -0,0 +1,60 @@
+// The TUI's Enter intercept for typed `/clm …` lines: handled in the TUI with no model turn.
+// `/clm reset` (the server owns state.json) is consumed only when `serverChannel` says the
+// TUI can hand it to the server plugin without a turn (src/channel.ts). Host-free so it can be unit-tested with
+// a fake key context and focused prompt. Written for this package.
+
+import { parseClmCommand, type ClmCommand } from "../panel/command.ts";
+
+/** The parts of the host's key-intercept context this uses. */
+export interface InterceptContext {
+	event: { name?: string; shift?: boolean; ctrl?: boolean; meta?: boolean };
+	consume(): void;
+}
+
+/** The focused prompt: host internals (textarea `plainText` / `setText`), checked at runtime. */
+export interface FocusedPrompt {
+	plainText?: unknown;
+	setText?: (text: string) => void;
+}
+
+export interface InterceptDeps {
+	focused(): FocusedPrompt | null | undefined;
+	/** False when `/clm` is not this package's to handle (`commands: false`, or a user-defined `/clm`). */
+	owned(): boolean;
+	/** Runs a command the TUI handles (a `server` one only when `serverChannel()` is true). */
+	handle(command: ClmCommand): Promise<void>;
+	/** True when `server` commands (`/clm reset`) go over the turn-free channel; absent = pass through. */
+	serverChannel?(): boolean;
+	/** Shows an error from `handle`. */
+	report(message: string): void;
+}
+
+/**
+ * Called for every key. Consumes Enter (no modifiers) on a `/clm …` prompt line the TUI
+ * handles; everything else passes through untouched: other text, `/clm-compact`, `/clm
+ * reset`, modified Enter, a prompt without the expected internals, and every `/clm` line
+ * when the command belongs to someone else. A usage error keeps the typed text so it can be
+ * fixed. With `serverChannel`, `/clm reset` is consumed as well. Returns the command handled, for tests.
+ */
+export function interceptEnter(context: InterceptContext, deps: InterceptDeps): ClmCommand | undefined {
+	const event = context.event;
+	if (event.name !== "return" || event.shift || event.ctrl || event.meta) return undefined;
+	const focused = deps.focused();
+	if (!focused || typeof focused.plainText !== "string" || typeof focused.setText !== "function") return undefined;
+	const command = parseClmCommand(focused.plainText);
+	if (!command) return undefined;
+	if (command.kind === "server" && !deps.serverChannel?.()) return undefined;
+	// A throw here would land in the host's key handling: fail open, let the line through.
+	let owned: boolean;
+	try {
+		owned = deps.owned();
+	} catch (error) {
+		deps.report(`CLM: ${error instanceof Error ? error.message : String(error)}`);
+		return undefined;
+	}
+	if (!owned) return undefined;
+	context.consume();
+	if (command.kind !== "usage") focused.setText("");
+	void Promise.resolve().then(() => deps.handle(command)).catch((error: unknown) => deps.report(`CLM: ${error instanceof Error ? error.message : String(error)}`));
+	return command;
+}

package/src/tui/locator.ts

@@ -0,0 +1,101 @@
+// TUI-side helpers around the channel (src/channel.ts) that need no opentui: the per-session
+// `locate` cache and `/clm reset` with its fallback. Written for this package.
+
+import { ChannelTimeout, LOCATE_TIMEOUT_MS, type ChannelOperation, type ChannelReply } from "../channel.ts";
+
+export interface Location {
+	directory: string;
+	root: string;
+}
+
+/** How long a failed `locate` (no answering server plugin) is remembered. */
+export const LOCATE_RETRY_MS = 60_000;
+/** How long a `locate` answer is trusted (a restarted server may use another mirrorDir). */
+export const LOCATE_TTL_MS = 5 * 60_000;
+
+export interface Locator {
+	/** The cached answer, or a new `locate` (short timeout); undefined when the server did not answer. */
+	locate(sessionID: string): Promise<Location | undefined>;
+	/** The cached answer if still fresh, without asking. */
+	fresh(sessionID: string): Location | undefined;
+	/** Drop the cached answer (reading through it failed). */
+	forget(sessionID: string): void;
+	/** `locate` in the background, once at a time per session; `onAnswer` gets a new answer. */
+	relocate(sessionID: string, onAnswer: (location: Location) => void): void;
+}
+
+export function createLocator(deps: {
+	ask(sessionID: string, operation: ChannelOperation, timeoutMs?: number): Promise<ChannelReply>;
+	now?: () => number;
+	ttlMs?: number;
+	retryMs?: number;
+}): Locator {
+	const now = deps.now ?? Date.now;
+	const ttl = deps.ttlMs ?? LOCATE_TTL_MS;
+	const retry = deps.retryMs ?? LOCATE_RETRY_MS;
+	const cache = new Map<string, { at: number; value?: Location }>();
+	const running = new Set<string>();
+	const entry = (sessionID: string) => {
+		const known = cache.get(sessionID);
+		if (!known) return undefined;
+		return now() - known.at < (known.value ? ttl : retry) ? known : undefined;
+	};
+	const locate = async (sessionID: string): Promise<Location | undefined> => {
+		const known = entry(sessionID);
+		if (known) return known.value;
+		let value: Location | undefined;
+		try {
+			const reply = await deps.ask(sessionID, { op: "locate" }, LOCATE_TIMEOUT_MS);
+			if (reply.directory && reply.root) value = { directory: reply.directory, root: reply.root };
+		} catch {
+			value = undefined;
+		}
+		cache.set(sessionID, { at: now(), ...(value ? { value } : {}) });
+		return value;
+	};
+	return {
+		locate,
+		fresh: (sessionID) => entry(sessionID)?.value,
+		forget: (sessionID) => {
+			cache.delete(sessionID);
+		},
+		relocate(sessionID, onAnswer) {
+			if (running.has(sessionID)) return;
+			running.add(sessionID);
+			void locate(sessionID)
+				.then((value) => {
+					if (value) onAnswer(value);
+				})
+				.finally(() => running.delete(sessionID));
+		},
+	};
+}
+
+/**
+ * `/clm reset` from the TUI: over the channel (no model turn). When the server plugin does not
+ * answer (not loaded there, an older version, or CLM disabled), fall back to the server
+ * command, as before the channel: it costs one model turn, and the toast says so.
+ */
+export async function resetSession(deps: {
+	sessionID: string;
+	ask(sessionID: string, operation: ChannelOperation): Promise<ChannelReply>;
+	/** `api.client.session.command`, flat v2 parameters. */
+	command(parameters: { sessionID: string; command: string; arguments: string }): Promise<{ error?: unknown } | undefined>;
+	toast(message: string, variant?: "info" | "warning"): void;
+}): Promise<"channel" | "command"> {
+	try {
+		await deps.ask(deps.sessionID, { op: "reset" });
+		return "channel";
+	} catch (error) {
+		if (!(error instanceof ChannelTimeout)) throw error;
+		deps.toast(`${error.message}. Sent /clm reset as a command instead; it costs one model turn.`, "warning");
+		// The command runs a model turn; do not wait for it.
+		void Promise.resolve()
+			.then(() => deps.command({ sessionID: deps.sessionID, command: "clm", arguments: "reset" }))
+			.then((result) => {
+				if (result?.error !== undefined) deps.toast(`/clm reset failed: ${JSON.stringify(result.error)}`, "warning");
+			})
+			.catch((failure: unknown) => deps.toast(`/clm reset failed: ${failure instanceof Error ? failure.message : String(failure)}`, "warning"));
+		return "command";
+	}
+}

package/src/tui/panel.ts

@@ -0,0 +1,205 @@
+// opentui adapter for the `/clm` panel: one Text renderable holding the frame as
+// StyledText, a key layer in its own mode, and the effects of the pure reducer (close,
+// reload, settings prompt/apply). Everything else is in src/panel/*. Written for this package.
+//
+// `@opentui/core` must stay a static ESM import: the host rewrites it to its own instance.
+
+import { BoxRenderable, RGBA, StyledText, TextAttributes, TextRenderable } from "@opentui/core";
+import type { TextChunk } from "@opentui/core";
+import type { TuiPluginApi, TuiThemeCurrent } from "@opencode-ai/plugin/tui";
+
+import type { Page } from "../panel/command.ts";
+import { reduce, type Effect, type Key } from "../panel/keys.ts";
+import type { Line, Tone } from "../panel/lines.ts";
+import type { PanelModel } from "../panel/model.ts";
+import { initialPanelState, renderPanel, type PanelSize, type PanelState } from "../panel/view.ts";
+
+export const PANEL_MODE = "opencode-clm.panel";
+
+/** Host key names (opentui keymap) → panel keys. */
+export const KEY_BINDINGS: ReadonlyArray<readonly [string, Key]> = [
+	["1", "1"], ["2", "2"], ["3", "3"], ["4", "4"],
+	["tab", "tab"], ["shift+tab", "shift+tab"],
+	["left", "left"], ["right", "right"], ["up", "up"], ["down", "down"],
+	["pageup", "pageup"], ["pagedown", "pagedown"],
+	["home", "home"], ["end", "end"], ["g", "g"], ["shift+g", "G"],
+	["return", "enter"], ["space", "space"],
+	["a", "a"], ["z", "z"], ["r", "r"], ["q", "q"], ["escape", "escape"], ["ctrl+c", "q"],
+	["j", "j"], ["k", "k"], ["[", "["], ["]", "]"],
+];
+
+type ToneStyle = { color: keyof TuiThemeCurrent; attributes?: number };
+
+const TONES: Record<Tone, ToneStyle> = {
+	text: { color: "text" },
+	muted: { color: "textMuted" },
+	dim: { color: "textMuted", attributes: TextAttributes.DIM },
+	accent: { color: "accent" },
+	edit: { color: "markdownLink" },
+	warning: { color: "warning" },
+	error: { color: "error" },
+	success: { color: "success" },
+	diffAdd: { color: "diffAdded" },
+	diffDel: { color: "diffRemoved" },
+	diffAddEm: { color: "diffHighlightAdded", attributes: TextAttributes.BOLD },
+	diffDelEm: { color: "diffHighlightRemoved", attributes: TextAttributes.BOLD },
+	border: { color: "border" },
+};
+
+/** Lines → one StyledText, tones resolved against the current theme. */
+export function toStyledText(lines: readonly Line[], theme: TuiThemeCurrent): StyledText {
+	const chunks: TextChunk[] = [];
+	lines.forEach((line, index) => {
+		if (index > 0) chunks.push({ __isChunk: true, text: "\n" });
+		for (const part of line) {
+			const style = TONES[part.tone ?? "text"];
+			const color = theme[style.color];
+			const attributes = (style.attributes ?? 0) | (part.bold ? TextAttributes.BOLD : 0);
+			chunks.push({
+				__isChunk: true,
+				text: part.text,
+				...(color instanceof RGBA ? { fg: color } : {}),
+				...(attributes ? { attributes } : {}),
+			});
+		}
+	});
+	return new StyledText(chunks);
+}
+
+/** A one-line text renderable for a host slot (the footer), restyled on each `set`. */
+export function createFooter(api: Pick<TuiPluginApi, "renderer" | "theme">, id: string): { renderable: TextRenderable; set(text: string | undefined): void } {
+	const renderable = new TextRenderable(api.renderer, { id, content: "", wrapMode: "none" });
+	return {
+		renderable,
+		set(text) {
+			renderable.content = toStyledText(text ? [[{ text, tone: "muted" }]] : [[]], api.theme.current);
+		},
+	};
+}
+
+export interface PanelOptions {
+	page: Page;
+	/** Reads the session files and builds the model. Never rejects with a broken panel: errors become a model. */
+	load: () => Promise<PanelModel>;
+	/** Applies a setting; resolves to an error message, or undefined on success. */
+	apply: (setting: string, value: string) => Promise<string | undefined>;
+	/** Called once after the panel released its key layer and mode (q, Esc, ctrl+c). */
+	onClose: () => void;
+	/** Called once when the panel is disposed for any reason, including the host unmounting the route. */
+	onDispose?: () => void;
+}
+
+export interface PanelController {
+	readonly renderable: BoxRenderable;
+	dispatch(key: Key): void;
+	reload(): Promise<void>;
+	setPage(page: Page): void;
+	/** Current state and model, for tests. */
+	snapshot(): { state: PanelState; model: PanelModel | undefined };
+	dispose(): void;
+}
+
+type PanelApi = Pick<TuiPluginApi, "renderer" | "theme" | "keymap" | "mode" | "ui">;
+
+export function createPanel(api: PanelApi, options: PanelOptions): PanelController {
+	let state = initialPanelState(options.page);
+	let model: PanelModel | undefined;
+	let disposed = false;
+	const box = new BoxRenderable(api.renderer, { id: "opencode-clm-panel", width: "100%", height: "100%", flexDirection: "column" });
+	const text = new TextRenderable(api.renderer, { id: "opencode-clm-panel-text", content: "Loading CLM panel…", wrapMode: "none", width: "100%", height: "100%" });
+	box.add(text);
+
+	const size = (): PanelSize => ({
+		width: Math.max(20, box.width || api.renderer.width),
+		height: Math.max(10, box.height || api.renderer.height),
+	});
+	const render = () => {
+		if (disposed || !model) return;
+		text.content = toStyledText(renderPanel(model, state, size()), api.theme.current);
+	};
+	box.onSizeChange = render;
+	// Leaving the route any other way (another plugin's navigate, a session event) removes or
+	// destroys the box: release the key mode then, or the prompt's base-mode keys stay dead.
+	const unmounted = () => controller.dispose();
+	(box as unknown as { onRemove: () => void }).onRemove = unmounted;
+	(box as unknown as { on?: (event: string, fn: () => void) => void }).on?.("destroyed", unmounted);
+
+	const popMode = api.mode.push(PANEL_MODE);
+	const dropLayer = api.keymap.registerLayer({
+		mode: PANEL_MODE,
+		bindings: KEY_BINDINGS.map(([key, panelKey]) => ({ key, desc: `CLM panel: ${panelKey}`, cmd: () => controller.dispatch(panelKey) })),
+	});
+
+	const perform = (effect: Effect | undefined) => {
+		if (!effect) return;
+		switch (effect.kind) {
+			case "close":
+				controller.dispose();
+				options.onClose();
+				return;
+			case "reload":
+				void controller.reload();
+				return;
+			case "apply":
+				void applySetting(effect.setting, effect.value);
+				return;
+			case "prompt":
+				api.ui.dialog.replace(() =>
+					api.ui.DialogPrompt({
+						title: `${effect.setting} · currently ${effect.current}`,
+						...(effect.placeholder ? { placeholder: effect.placeholder } : {}),
+						value: effect.current,
+						onConfirm: (value: string) => {
+							api.ui.dialog.clear();
+							if (value.trim() !== "") void applySetting(effect.setting, value.trim());
+						},
+						onCancel: () => api.ui.dialog.clear(),
+					}),
+				);
+				return;
+		}
+	};
+
+	const applySetting = async (setting: string, value: string) => {
+		const error = await options.apply(setting, value).catch((cause: unknown) => (cause instanceof Error ? cause.message : String(cause)));
+		await controller.reload();
+		const row = model?.settings.rows.find((candidate) => candidate.key === setting);
+		const shown = `${row?.label ?? setting}: ${row?.value ?? value}`;
+		state = { ...state, message: error ? { text: error, warning: true } : { text: shown, warning: false } };
+		render();
+	};
+
+	const controller: PanelController = {
+		renderable: box,
+		dispatch(key) {
+			if (disposed || !model) {
+				if (key === "q" || key === "escape") perform({ kind: "close" });
+				return;
+			}
+			const result = reduce(state, key, model, size());
+			state = result.state;
+			render();
+			perform(result.effect);
+		},
+		async reload() {
+			const next = await options.load();
+			if (disposed) return;
+			model = next;
+			render();
+		},
+		setPage(page) {
+			state = { ...state, page, scroll: 0 };
+			render();
+		},
+		snapshot: () => ({ state, model }),
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			dropLayer();
+			popMode();
+			options.onDispose?.();
+		},
+	};
+	void controller.reload();
+	return controller;
+}