opencode-clm 0.2.0 → 0.3.0

package/src/tui/complete.ts

@@ -0,0 +1,102 @@
+// Tab completion for typed `/clm …` lines in the TUI prompt. OpenCode has no argument
+// completion for commands (its slash menu closes at the first space), so the TUI plugin
+// completes inline: Tab extends the line to the longest common prefix of the matching items
+// and lists them when several remain. Items follow pi-clm's `getArgumentCompletions`
+// (pi src/index.ts:961-980) plus `budget` and setting values. Written for this package.
+
+import { PAGES } from "../panel/command.ts";
+import { SETTING_NAMES, settingDescriptor } from "../settings-table.ts";
+import type { FocusedPrompt, InterceptContext } from "./intercept.ts";
+
+const PREFIX = "/clm ";
+
+/** pi's word list: pages, status, config, `config <setting>`, config reset, on, off, reset, path; plus budget. */
+export const CLM_COMPLETIONS: readonly string[] = [
+	...PAGES,
+	"status",
+	"config",
+	...SETTING_NAMES.map((name) => `config ${name}`),
+	"config reset",
+	"on",
+	"off",
+	"reset",
+	"path",
+	"budget",
+];
+
+/** Items for the text after `/clm `: subcommands, or a setting's choices after `config <setting> `. */
+export function clmCompletions(args: string): string[] {
+	const lower = args.toLowerCase();
+	const value = /^config\s+(\S+)\s+(.*)$/i.exec(args);
+	if (value) {
+		const choices = settingDescriptor(value[1]!)?.choices ?? [];
+		return choices
+			.filter((choice) => choice.toLowerCase().startsWith(value[2]!.toLowerCase()))
+			.map((choice) => `config ${value[1]} ${choice}`);
+	}
+	return CLM_COMPLETIONS.filter((item) => item.startsWith(lower));
+}
+
+function commonPrefix(items: readonly string[]): string {
+	let prefix = items[0] ?? "";
+	for (const item of items) {
+		while (!item.startsWith(prefix)) prefix = prefix.slice(0, -1);
+	}
+	return prefix;
+}
+
+export interface Completion {
+	/** The new prompt text; the same text when no item extends it. */
+	text: string;
+	/** Items still matching; more than one when the line stays ambiguous. */
+	items: string[];
+}
+
+/** `undefined` unless `text` is `/clm ` followed by something an item completes. */
+export function completeClmLine(text: string): Completion | undefined {
+	if (!text.startsWith(PREFIX)) return undefined;
+	const args = text.slice(PREFIX.length).replace(/^\s+/, "");
+	const items = clmCompletions(args);
+	if (items.length === 0) return undefined;
+	if (items.length === 1) return { text: `${PREFIX}${items[0]} `, items };
+	const common = commonPrefix(items);
+	return { text: common.length > args.length ? `${PREFIX}${common}` : text, items };
+}
+
+export interface TabDeps {
+	focused(): (FocusedPrompt & { cursorOffset?: unknown }) | null | undefined;
+	/** False when `/clm` is not this package's (as for Enter). */
+	owned(): boolean;
+	/** Shows the remaining items when Tab cannot extend the line. */
+	show(items: readonly string[]): void;
+}
+
+/**
+ * Called for every key. Consumes Tab (no modifiers) on a `/clm …` line with the cursor at the
+ * end when an item matches; everything else, `/clm` without a space (OpenCode's own slash
+ * menu completes that) and lines with no match included, passes through to the host's Tab.
+ * Returns the completion applied, for tests.
+ */
+export function interceptTab(context: InterceptContext, deps: TabDeps): Completion | undefined {
+	const event = context.event;
+	if (event.name !== "tab" || 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 text = focused.plainText;
+	if (typeof focused.cursorOffset === "number" && focused.cursorOffset !== text.length) return undefined;
+	const completion = completeClmLine(text);
+	if (!completion) return undefined;
+	try {
+		if (!deps.owned()) return undefined;
+	} catch {
+		return undefined;
+	}
+	context.consume();
+	if (completion.text !== text) {
+		focused.setText(completion.text);
+		if (typeof focused.cursorOffset === "number") focused.cursorOffset = completion.text.length;
+	} else {
+		deps.show(completion.items);
+	}
+	return completion;
+}

package/src/tui/data.ts

@@ -4,7 +4,7 @@
 
 import { resolveBudget } from "../budget.ts";
 import type { LatestUsage, PanelModel, PanelSettings, SettingRow } from "../panel/model.ts";
-import { formatTokenCount } from "../panel/timeline.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";
 
@@ -109,7 +109,7 @@ export function fallbackBudget(settings: ClmSettings, limits: { context?: number
  */
 export function settingsView(
 	values: { base: SettingsValues; effective: SettingsValues },
-	model: Pick<PanelModel, "budgetInfo" | "timeline" | "mirrorPath">,
+	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));
@@ -124,9 +124,10 @@ export function settingsView(
 	}));
 	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)"}`);
+	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,
@@ -136,6 +137,85 @@ export function settingsView(
 	};
 }
 
+/**
+ * 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.

package/src/tui/intercept.ts

@@ -1,5 +1,6 @@
-// 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
+// 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";
@@ -20,8 +21,10 @@ 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>;
+	/** 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;
 }
@@ -31,7 +34,7 @@ export interface InterceptDeps {
  * 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.
+ * 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;
@@ -39,7 +42,8 @@ export function interceptEnter(context: InterceptContext, deps: InterceptDeps):
 	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;
+	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 {

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

@@ -66,6 +66,17 @@ export function toStyledText(lines: readonly Line[], theme: TuiThemeCurrent): St
 	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. */