opencode-clm 0.1.0 → 0.2.0

package/src/state.ts

@@ -24,6 +24,24 @@ export interface LiveContextOutcome {
 	at: string;
 }
 
+/**
+ * The once-per-session measurement of OpenCode's fixed overhead (system prompt and tool
+ * schemas). Its presence means the budget-too-small check has run; the session then derives
+ * its effective budget from `overhead` (clm.ts), so a raise survives a restart.
+ */
+export interface BudgetCheck {
+	/** Fixed overhead per request, tokens. */
+	overhead: number;
+	/** `provider`: the provider's count minus the conversation estimate; `estimate`: chars/4 sizes. */
+	source: "provider" | "estimate";
+	/** Budget and reserve in force when the check ran, and what it decided. */
+	configured: number;
+	reserve: number;
+	effective: number;
+	raised: boolean;
+	at: string;
+}
+
 export interface LiveContextState {
 	version: 1;
 	enabled: boolean;
@@ -31,12 +49,15 @@ export interface LiveContextState {
 	revision: number;
 	checkpoint?: ProjectionCheckpoint;
 	lastOutcome?: LiveContextOutcome;
+	budgetCheck?: BudgetCheck;
 }
 
 export interface LoadedState {
 	state: LiveContextState;
 	/** Set when a state file existed but could not be used; the state is then initial. */
 	warning?: string;
+	/** Set when an invalid optional field was dropped and the rest of the state kept. */
+	repaired?: string;
 }
 
 const SOURCE_KINDS = new Set(["kept", "edited", "removed", "restored", "normalized"]);
@@ -137,6 +158,24 @@ function isOutcome(value: unknown): value is LiveContextOutcome {
 	);
 }
 
+function isBudgetCheck(value: unknown): value is BudgetCheck {
+	if (!isObject(value)) return false;
+	return (
+		isCount(value.overhead) &&
+		(value.source === "provider" || value.source === "estimate") &&
+		isCount(value.configured) &&
+		isCount(value.reserve) &&
+		isCount(value.effective) &&
+		typeof value.raised === "boolean" &&
+		typeof value.at === "string"
+	);
+}
+
+/** The fields every state rewrite carries over (revision changes keep the budget check). */
+export function keptFields(state: LiveContextState): Pick<LiveContextState, "budgetCheck"> {
+	return state.budgetCheck ? { budgetCheck: state.budgetCheck } : {};
+}
+
 export function isLiveContextState(value: unknown): value is LiveContextState {
 	if (!isObject(value)) return false;
 	const state = value as Partial<LiveContextState>;
@@ -147,7 +186,8 @@ export function isLiveContextState(value: unknown): value is LiveContextState {
 		// Accept writes the checkpoint and the state with the same revision; reset moves past it.
 		(state.checkpoint === undefined ||
 			(isProjectionCheckpoint(state.checkpoint) && state.checkpoint.revision === state.revision)) &&
-		(state.lastOutcome === undefined || isOutcome(state.lastOutcome))
+		(state.lastOutcome === undefined || isOutcome(state.lastOutcome)) &&
+		(state.budgetCheck === undefined || isBudgetCheck(state.budgetCheck))
 	);
 }
 
@@ -162,6 +202,7 @@ export function resetProjectionState(
 		enabled: state.enabled,
 		revision: state.revision + 1,
 		lastOutcome: { kind: "reset", message, at },
+		...keptFields(state),
 	};
 }
 
@@ -191,10 +232,16 @@ export async function loadLiveContextState(directory: string): Promise<LoadedSta
 			warning: `${path} has unsupported version ${JSON.stringify(parsed.version)}; starting clean.`,
 		};
 	}
+	// A malformed budget check costs only itself: the session re-measures the overhead.
+	let repaired: string | undefined;
+	if (isObject(parsed) && parsed.budgetCheck !== undefined && !isBudgetCheck(parsed.budgetCheck)) {
+		delete parsed.budgetCheck;
+		repaired = `${path} had an invalid budgetCheck; dropped it, the fixed overhead is measured again.`;
+	}
 	if (!isLiveContextState(parsed)) {
 		return { state: initialLiveContextState(), warning: `${path} has an invalid shape; starting clean.` };
 	}
-	return { state: parsed };
+	return repaired ? { state: parsed, repaired } : { state: parsed };
 }
 
 /**

package/src/tui/data.ts

@@ -0,0 +1,161 @@
+// 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 } 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">,
+	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(`Size last request ${latest.measured ? "" : "~"}${formatTokenCount(latest.tokens)}${latest.measured ? " (provider count)" : " (estimate)"}`);
+	const info = model.budgetInfo;
+	if (info?.overhead !== undefined) summary.push(`Fixed overhead ~${formatTokenCount(info.overhead)} · usable ${formatTokenCount(info.usable ?? 0)}`);
+	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 } : {}),
+	};
+}
+
+/**
+ * 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,56 @@
+// The TUI's Enter intercept for typed `/clm …` lines: handled in the TUI with no model turn,
+// except `/clm reset` (the server owns state.json). 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. */
+	handle(command: Exclude<ClmCommand, { kind: "server" }>): Promise<void>;
+	/** 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. 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 || command.kind === "server") 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/panel.ts

@@ -0,0 +1,194 @@
+// 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);
+}
+
+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;
+}