opencode-clm 0.1.1 → 0.3.0

package/src/tui/plugin.ts

@@ -0,0 +1,466 @@
+// TUI side of opencode-clm: the `/clm` panel route, its slash row and palette command,
+// the Enter intercept that handles typed `/clm …` lines without a model turn, and live
+// reloads while the panel is open. Written for this package (v0.2.0 design §2–§3).
+
+import type { TuiPlugin, TuiPluginApi } from "@opencode-ai/plugin/tui";
+
+import { userOwnsStatusCommand } from "../commands.ts";
+import { type ClmCommand, type Page } from "../panel/command.ts";
+import { changeSetting, overridesValues, resetSettings, sessionValues, showSetting } from "../overrides.ts";
+import { COMMAND_EVENT, commandOf, createChannelClient, type ChannelOperation, type ChannelReply } from "../channel.ts";
+import { createLocator, resetSession } from "./locator.ts";
+import { outsideMessage, resolveSource, sourceOverrides, type FileApi, type SessionSource } from "./remote.ts";
+import type { SettingsValues } from "../settings-table.ts";
+import { interceptTab } from "./complete.ts";
+import { interceptEnter } from "./intercept.ts";
+import { buildPanelModel, type PanelModel } from "../panel/model.ts";
+import { formatTokenCount } from "../panel/timeline.ts";
+import { readSessionDirectory, sessionDirectory, type SessionReader } from "../session-files.ts";
+import { resolveSettings, type ClmSettings } from "../settings.ts";
+import { fallbackBudget, footerText, latestUsage, modelLimits, overridesNewer, RESET_NOW, RESET_ROW, resetRow, serverBase, serverPluginOptions, settingsView } from "./data.ts";
+import type { SessionFiles } from "../panel/files.ts";
+import { createFooter, createPanel, type PanelController } from "./panel.ts";
+
+export const PANEL_ROUTE = "opencode-clm.panel";
+const OPEN_COMMAND = "opencode-clm.panel.open";
+const RELOAD_DEBOUNCE_MS = 250;
+/** The package's server entry, to recognise a `file://` spec in the server plugin list. */
+const PACKAGE_INDEX_URL = new URL("../../index.ts", import.meta.url).href;
+
+const PAGES = new Set<Page>(["overview", "input", "edits", "settings"]);
+/** `/clm path` names how this TUI reads the files. */
+const SOURCE_LABEL: Record<SessionSource["kind"], string> = {
+	local: "local disk",
+	remote: "server file API",
+	channel: "server plugin channel",
+	outside: "unreadable from this TUI",
+};
+/** Reads nothing: a session directory the attached TUI cannot reach. */
+const NO_READER: SessionReader = { name: "none", isDirectory: async () => false, readText: async () => undefined, list: async () => [], stamp: async () => undefined };
+
+function describe(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export const tui: TuiPlugin = async (api, tuiOptions) => {
+	let active: { controller: PanelController; sessionID: string } | undefined;
+	let reloadTimer: ReturnType<typeof setTimeout> | undefined;
+
+	/** Settings as the server resolves them: its plugin entry's options, else this plugin's. */
+	const settings = (): ClmSettings => {
+		const fromServer = serverPluginOptions(api.state.config.plugin, PACKAGE_INDEX_URL);
+		const options = fromServer ?? ((tuiOptions ?? {}) as Record<string, unknown>);
+		return resolveSettings(options, process.env, api.state.path.directory);
+	};
+
+	// ---- the channel to the server plugin (src/channel.ts) --------------------------------
+	const channel = createChannelClient({
+		publish: async (command) => {
+			const result = await api.client.tui.publish({ body: { type: COMMAND_EVENT, properties: { command } } });
+			if (result.error !== undefined) throw new Error(`publishing to the server failed: ${JSON.stringify(result.error)}`);
+		},
+		subscribe: (handler) => api.event.on(COMMAND_EVENT, (event) => {
+			const command = commandOf(event);
+			if (command !== undefined) handler(command);
+		}),
+	});
+
+	/** Sends one operation; throws the server's error text, or a timeout. */
+	const ask = async (sessionID: string, operation: ChannelOperation, timeoutMs?: number): Promise<ChannelReply> => {
+		const reply = await channel.request(sessionID, operation, timeoutMs);
+		if (!reply.ok) throw new Error(reply.text);
+		return reply;
+	};
+
+	/** Where the server keeps each session's files (`locate`), cached; see locator.ts. */
+	const locator = createLocator({ ask });
+
+	/** When this TUI last changed a session's overrides through the channel (no mtime remotely). */
+	const channelWrites = new Map<string, number>();
+
+	/** `write`: the source a setting change goes to (never the read-only same-disk guess). */
+	const source = (sessionID: string, options: { write?: boolean } = {}): Promise<SessionSource> => resolveSource({
+		ownDirectory: sessionDirectory(settings().mirrorDir, sessionID),
+		serverRoot: api.state.path.directory,
+		file: api.client.file as unknown as FileApi,
+		locate: () => locator.locate(sessionID),
+		located: () => locator.fresh(sessionID),
+		relocate: () => {
+			const own = sessionDirectory(settings().mirrorDir, sessionID);
+			// The server keeps this session's files elsewhere: show them.
+			locator.relocate(sessionID, (value) => {
+				if (value.directory !== own) refreshPanel(sessionID);
+			});
+		},
+		ask: (operation) => ask(sessionID, operation),
+	}, options);
+
+	const readFiles = async (sessionID: string, from: SessionSource): Promise<SessionFiles> => {
+		if (from.kind === "outside") {
+			const files = await readSessionDirectory(from.directory, sessionID, NO_READER);
+			files.warnings.push(outsideMessage(from));
+			return files;
+		}
+		const files = await readSessionDirectory(from.directory, sessionID, from.reader);
+		// A read through the server failed: ask where the files are again next time.
+		if (from.kind !== "local" && files.warnings.some((warning) => warning.startsWith("Could not"))) locator.forget(sessionID);
+		return files;
+	};
+
+	/**
+	 * Base and effective settings of a session. The server is the authority on the base:
+	 * once it wrote snapshot.json, the base is the server's (`serverBase`), so a TUI whose
+	 * environment resolves differently still merges and validates as the server would.
+	 * Before the first request, the TUI's own resolution of the server's options stands in.
+	 * Editing base = state.json's `enabled`. Effective = base + the session's overrides.json.
+	 */
+	const sessionSettings = async (sessionID: string, from: SessionSource, files: Pick<SessionFiles, "state" | "snapshot">) => {
+		const own = settings();
+		const { base, source: baseSource } = serverBase(own, files.snapshot);
+		const stored = files.state && typeof files.state === "object" ? (files.state as { enabled?: unknown }).enabled : undefined;
+		const baseEditing = typeof stored === "boolean" ? stored : true;
+		const read = from.kind === "local"
+			? await sessionValues(from.directory, base, baseEditing)
+			: overridesValues(await sourceOverrides(from), base, baseEditing, channelWrites.get(sessionID));
+		const values: { base: SettingsValues; effective: SettingsValues } = { base: { editing: baseEditing, settings: base }, effective: read.values };
+		return { base, baseSource, baseEditing, directory: from.directory, values, ...(read.warning ? { warning: read.warning } : {}), ...(read.mtimeMs !== undefined ? { overridesAt: read.mtimeMs } : {}) };
+	};
+
+	const loadModel = async (sessionID: string): Promise<PanelModel> => {
+		const from = await source(sessionID);
+		const files = await readFiles(sessionID, from);
+		const messages = api.state.session.messages(sessionID);
+		const latest = latestUsage(messages);
+		const limits = modelLimits(messages, api.state.provider);
+		const current = await sessionSettings(sessionID, from, files);
+		const budget = fallbackBudget(current.values.effective.settings, limits);
+		// overrides.json written after the last request: its budget is in force from the next
+		// request, so the panel shows it rather than the snapshot's.
+		const preferSettings = overridesNewer(current.overridesAt, files.snapshot);
+		const model = buildPanelModel(files, { ...(latest ? { latest } : {}), ...(budget ? { budget } : {}), ...(preferSettings ? { preferSettings } : {}) });
+		model.enabled = current.values.effective.editing;
+		model.settings = settingsView(current.values, model, {
+			format: { ...(limits.context ? { modelWindow: limits.context } : {}) },
+			...(current.warning ? { warning: current.warning } : {}),
+		});
+		model.settings.rows.push(resetRow(model.settings.changed.length));
+		return model;
+	};
+
+	/** Drops the session's settings changes, locally or through the server. */
+	const resetSessionSettings = async (sessionID: string): Promise<{ viaServer: boolean }> => {
+		const from = await source(sessionID, { write: true });
+		if (from.kind === "local") {
+			await resetSettings(from.directory);
+			return { viaServer: false };
+		}
+		await ask(sessionID, { op: "settings-reset" });
+		channelWrites.set(sessionID, Date.now());
+		return { viaServer: true };
+	};
+
+	/**
+	 * Validates and saves one setting; returns `Label: value` and whether the server
+	 * confirmed it with its own toast. Local files: written here (overrides.json, which the
+	 * server reads before each request). Otherwise the server applies it over the channel.
+	 */
+	const applySetting = async (sessionID: string, name: string, value: string): Promise<{ text: string; viaServer: boolean }> => {
+		const from = await source(sessionID, { write: true });
+		if (from.kind !== "local") {
+			const reply = await ask(sessionID, { op: "set", setting: name, value });
+			channelWrites.set(sessionID, Date.now());
+			return { text: reply.text, viaServer: true };
+		}
+		const files = await readFiles(sessionID, from);
+		const current = await sessionSettings(sessionID, from, files);
+		const result = await changeSetting({
+			sessionDirectory: current.directory,
+			base: current.base,
+			baseEditing: current.baseEditing,
+			projectDirectory: api.state.path.directory,
+		}, name, value);
+		return { text: result.text, viaServer: false };
+	};
+
+	/** False when `/clm` belongs to someone else: `commands: false`, or a user-defined command. */
+	const owned = (): boolean => {
+		if (!settings().commands) return false;
+		return !userOwnsStatusCommand((api.state.config as { command?: unknown }).command);
+	};
+
+	const currentSessionID = (): string | undefined => {
+		const route = api.route.current;
+		if (route.name === "session" && route.params && typeof route.params.sessionID === "string") return route.params.sessionID;
+		if (route.name === PANEL_ROUTE) return active?.sessionID;
+		return undefined;
+	};
+
+	const open = (page: Page) => {
+		const sessionID = currentSessionID();
+		if (!sessionID) {
+			api.ui.toast({ variant: "warning", title: "CLM", message: "Open a session first." });
+			return;
+		}
+		if (active && active.sessionID === sessionID && api.route.current.name === PANEL_ROUTE) {
+			active.controller.setPage(page);
+			return;
+		}
+		api.route.navigate(PANEL_ROUTE, { sessionID, page });
+	};
+
+	api.route.register([{
+		name: PANEL_ROUTE,
+		render: ({ params }) => {
+			const sessionID = typeof params?.sessionID === "string" ? params.sessionID : "";
+			const page = typeof params?.page === "string" && PAGES.has(params.page as Page) ? (params.page as Page) : "overview";
+			active?.controller.dispose();
+			const controller = createPanel(api, {
+				page,
+				// The footer of this session takes the panel's model instead of reading the files again.
+				load: () => loadModel(sessionID).then(
+					(model) => {
+						showFooter(sessionID, model);
+						return model;
+					},
+					(error: unknown) => {
+						showFooter(sessionID, undefined);
+						return errorModel(sessionID, error);
+					},
+				),
+				apply: async (setting, value) => {
+					try {
+						if (setting === RESET_ROW) {
+							if (value === RESET_NOW) await resetSessionSettings(sessionID);
+							refreshFooter(sessionID);
+							return undefined;
+						}
+						await applySetting(sessionID, setting, value);
+						refreshFooter(sessionID);
+						return undefined;
+					} catch (error) {
+						return describe(error);
+					}
+				},
+				onDispose: () => {
+					if (active?.controller === controller) active = undefined;
+				},
+				onClose: () => {
+					if (active?.controller === controller) active = undefined;
+					if (sessionID) api.route.navigate("session", { sessionID });
+					else api.route.navigate("home");
+				},
+			});
+			active = { controller, sessionID };
+			// A raw renderable is accepted by the host's Solid insert (verified with 1.18.34).
+			return controller.renderable as unknown as ReturnType<Parameters<TuiPluginApi["route"]["register"]>[0][number]["render"]>;
+		},
+	}]);
+
+	const disposeLayer = api.keymap.registerLayer({
+		commands: [{
+			name: OPEN_COMMAND,
+			title: "CLM panel",
+			desc: "Context size, input, edits and settings of CLM",
+			namespace: "palette",
+			slashName: "clm",
+			run() {
+				open("overview");
+			},
+		}],
+	});
+
+	const toast = (message: string, variant: "info" | "warning" = "info") =>
+		api.ui.toast({ variant, title: "CLM", message });
+
+	/** After a change: refresh an open panel so it shows the new value. */
+	const refreshPanel = (sessionID: string) => {
+		if (active?.sessionID === sessionID) void active.controller.reload();
+		refreshFooter(sessionID);
+	};
+
+	/** Every `/clm …` line the intercept consumes (`/clm reset` goes to the server over the channel). */
+	const handle = async (command: ClmCommand): Promise<void> => {
+		if (command.kind === "open") {
+			open(command.page);
+			return;
+		}
+		if (command.kind === "usage") {
+			toast(command.text, "warning");
+			return;
+		}
+		const sessionID = currentSessionID();
+		if (!sessionID) {
+			toast("Open a session first.", "warning");
+			return;
+		}
+		switch (command.kind) {
+			case "path": {
+				const from = await source(sessionID);
+				toast(`${from.directory} (${SOURCE_LABEL[from.kind]})`);
+				return;
+			}
+			case "status":
+				toast(statusSummary(await loadModel(sessionID)));
+				return;
+			case "config-show": {
+				const from = await source(sessionID);
+				const current = await sessionSettings(sessionID, from, await readFiles(sessionID, from));
+				toast(showSetting(command.setting, current.values.effective));
+				return;
+			}
+			case "config-set":
+				try {
+					const result = await applySetting(sessionID, command.setting, command.value);
+					if (!result.viaServer) toast(`CLM ${result.text}.`);
+				} catch (error) {
+					toast(describe(error), "warning");
+				}
+				refreshPanel(sessionID);
+				return;
+			case "config-reset": {
+				if (!(await resetSessionSettings(sessionID)).viaServer) toast("CLM settings reset to the defaults.");
+				refreshPanel(sessionID);
+				return;
+			}
+			case "enable": {
+				// The same override as the server's `/clm on|off` and `/clm config editing`.
+				const result = await applySetting(sessionID, "editing", command.enabled ? "on" : "off");
+				if (!result.viaServer) toast(`CLM ${command.enabled ? "on" : "off"} for this session`);
+				refreshPanel(sessionID);
+				return;
+			}
+			case "server":
+				// `/clm reset`: the server owns state.json; it drops the revision and toasts.
+				await resetSession({
+					sessionID,
+					ask,
+					command: (parameters) => api.client.session.command(parameters),
+					toast,
+				});
+				refreshPanel(sessionID);
+				return;
+		}
+	};
+
+	const disposeIntercept = api.keymap.intercept("key", (context) => {
+		// Tab on a `/clm …` line completes it inline (OpenCode has no argument completion).
+		if (interceptTab(context as never, {
+			focused: () => api.renderer.currentFocusedRenderable as never,
+			owned,
+			show: (items) => toast(items.map((item) => `/clm ${item}`).join(" · ")),
+		})) return;
+		interceptEnter(context as never, {
+			focused: () => api.renderer.currentFocusedRenderable as never,
+			owned,
+			handle,
+			serverChannel: () => true,
+			report: (message) => toast(message, "warning"),
+		});
+	}, { priority: 100 });
+
+	// ---- footer: `clm 12k / 32k · r2` right of the session prompt (pi's status line) -----
+	/**
+	 * One footer per session, reused while it is alive: the host's Solid slot calls the
+	 * renderer again whenever its props change, and returning the same renderable keeps it
+	 * from piling up new ones. Leaving the session view destroys it; the next render makes a
+	 * new one.
+	 */
+	const footers = new Map<string, ReturnType<typeof createFooter>>();
+	const footerTimers = new Map<string, ReturnType<typeof setTimeout>>();
+	/** The session's footer while it can still be drawn; the host destroys one it unmounts. */
+	const liveFooter = (sessionID: string) => {
+		const footer = footers.get(sessionID);
+		if (footer?.renderable.isDestroyed) footers.delete(sessionID);
+		return footer?.renderable.isDestroyed ? undefined : footer;
+	};
+	const showFooter = (sessionID: string, model: PanelModel | undefined) =>
+		liveFooter(sessionID)?.set(model ? footerText(model) : undefined);
+	const refreshFooter = (sessionID: string) => {
+		if (!liveFooter(sessionID)) return;
+		// An open panel for this session reloads its model and feeds the footer (above).
+		if (active?.sessionID === sessionID) return;
+		clearTimeout(footerTimers.get(sessionID));
+		footerTimers.set(sessionID, setTimeout(() => {
+			footerTimers.delete(sessionID);
+			void loadModel(sessionID).then(
+				(model) => showFooter(sessionID, model),
+				() => showFooter(sessionID, undefined),
+			);
+		}, RELOAD_DEBOUNCE_MS));
+	};
+	api.slots.register({
+		order: 50,
+		slots: {
+			session_prompt_right(_context, props) {
+				const sessionID = (props as { session_id?: unknown }).session_id;
+				if (typeof sessionID !== "string" || !settings().enabled) return null as never;
+				let footer = liveFooter(sessionID);
+				if (!footer) {
+					footer = createFooter(api, `opencode-clm-footer-${sessionID}`);
+					footers.set(sessionID, footer);
+				}
+				refreshFooter(sessionID);
+				// A raw renderable, as the panel route returns (accepted by the host's Solid insert).
+				return footer.renderable as never;
+			},
+		},
+	});
+
+	const scheduleReload = (sessionID: unknown) => {
+		if (typeof sessionID === "string") refreshFooter(sessionID);
+		if (!active || (typeof sessionID === "string" && sessionID !== active.sessionID)) return;
+		clearTimeout(reloadTimer);
+		reloadTimer = setTimeout(() => void active?.controller.reload(), RELOAD_DEBOUNCE_MS);
+	};
+	const offIdle = api.event.on("session.idle", (event) => scheduleReload((event.properties as { sessionID?: unknown }).sessionID));
+	// Sizes change when a reply completes; streaming updates in between are skipped.
+	const offMessage = api.event.on("message.updated", (event) => {
+		const info = (event.properties as { info?: { sessionID?: unknown; role?: unknown; time?: { completed?: unknown } } }).info;
+		if (info?.role === "assistant" && info.time?.completed === undefined) return;
+		scheduleReload(info?.sessionID);
+	});
+
+	api.lifecycle.onDispose(() => {
+		clearTimeout(reloadTimer);
+		for (const timer of footerTimers.values()) clearTimeout(timer);
+		for (const footer of footers.values()) if (!footer.renderable.isDestroyed) footer.renderable.destroy();
+		footers.clear();
+		active?.controller.dispose();
+		active = undefined;
+		offIdle();
+		offMessage();
+		channel.dispose();
+		disposeIntercept();
+		disposeLayer();
+	});
+};
+
+/** A model that shows the read error on the overview instead of a broken panel. */
+function errorModel(sessionID: string, error: unknown): PanelModel {
+	return {
+		sessionID,
+		directory: "(unknown)",
+		found: false,
+		enabled: true,
+		revision: 0,
+		timeline: { points: [], markers: [], peakTokens: 0, turnStarts: [] },
+		revisions: [],
+		settings: { rows: [], summary: [], changed: [] },
+		mirrorPath: "",
+		warnings: [`Could not load the CLM files: ${describe(error)}`],
+	};
+}
+
+/** Toast text for `/clm status` typed in the TUI. */
+export function statusSummary(model: PanelModel): string {
+	if (!model.found) return `No CLM data for this session (${model.directory}).`;
+	const latest = model.timeline.points.at(-1);
+	const parts = [
+		`CLM ${model.enabled ? "on" : "off"} · revision ${model.revision}`,
+		latest ? `last request ${latest.measured ? "" : "~"}${formatTokenCount(latest.tokens)}` : "no requests yet",
+		model.budget !== undefined ? `budget ${formatTokenCount(model.budget)}` : undefined,
+		model.budgetInfo?.overhead !== undefined ? `fixed overhead ~${formatTokenCount(model.budgetInfo.overhead)}` : undefined,
+		model.lastOutcome ? `last: ${model.lastOutcome.kind}` : undefined,
+	];
+	return parts.filter(Boolean).join(" · ");
+}

package/src/tui/remote.ts

@@ -0,0 +1,199 @@
+// Where the TUI reads a session's CLM files from. Local disk first (the TUI and the server
+// share a file system); otherwise the server's own copy through OpenCode's file API
+// (`GET /file`, `GET /file/content`), which serves paths inside the server's instance
+// directory only. A session directory outside it cannot be read from an attached TUI.
+// Written for this package. Verified against opencode 1.18.34: `GET /file/content`
+// server/routes/instance/httpapi/handlers/file.ts:96-124 (missing file → empty text, text
+// trimmed, path must stay inside the instance directory); `GET /file` file.ts:66-92 and
+// packages/core/src/filesystem.ts:66-99 (a missing directory fails).
+
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+
+import { OVERRIDES_FILE, parseOverridesText, readOverrides, type OverridesRead } from "../overrides.ts";
+import { localReader, type SessionReader } from "../session-files.ts";
+
+/** The part of the TUI api's SDK client (`api.client.file`) this uses. */
+export interface FileApi {
+	read(parameters: { path: string }): Promise<{ data?: unknown; error?: unknown }>;
+	list(parameters: { path: string }): Promise<{ data?: unknown; error?: unknown }>;
+}
+
+export type SessionSource =
+	| { kind: "local"; directory: string; reader: SessionReader }
+	/** Read through the server; `root` is the server's instance directory. */
+	| { kind: "remote"; directory: string; root: string; reader: SessionReader }
+	/** On the server, outside its instance directory: the server plugin reads it and answers over the channel. */
+	| { kind: "channel"; directory: string; root: string; reader: SessionReader }
+	/** Outside the server directory and no server plugin answering: unreadable from here. */
+	| { kind: "outside"; directory: string; root: string };
+
+/** `path` relative to `root`, or undefined when it lies outside. */
+export function insideRoot(root: string, path: string): string | undefined {
+	const rel = relative(root, path);
+	if (rel === "") return ".";
+	if (isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`)) return undefined;
+	return rel;
+}
+
+function failure(error: unknown, path: string): Error {
+	if (error instanceof Error) return error;
+	const message = error && typeof error === "object" && "data" in error
+		? JSON.stringify((error as { data?: unknown }).data)
+		: JSON.stringify(error);
+	return new Error(`server file API refused ${path}: ${message}`);
+}
+
+/**
+ * A reader over the server's file API. `GET /file/content` answers a missing file with
+ * empty text and trims what it returns (whitespace only matters at the ends of the JSON and
+ * JSONL files read here); `GET /file` fails for a missing directory.
+ */
+export function remoteReader(file: FileApi, root: string): SessionReader {
+	const rel = (path: string): string => {
+		const inside = insideRoot(root, path);
+		if (inside === undefined) throw new Error(`${path} lies outside the server directory ${root}`);
+		return inside;
+	};
+	const list = async (path: string): Promise<string[] | undefined> => {
+		const result = await file.list({ path: rel(path) });
+		if (result.error !== undefined || !Array.isArray(result.data)) return undefined;
+		return result.data.flatMap((item) => (item && typeof (item as { name?: unknown }).name === "string" ? [(item as { name: string }).name] : []));
+	};
+	return {
+		name: `remote:${root}`,
+		async isDirectory(path) {
+			return (await list(path)) !== undefined;
+		},
+		async readText(path) {
+			const result = await file.read({ path: rel(path) });
+			if (result.error !== undefined) throw failure(result.error, path);
+			const data = result.data as { type?: unknown; content?: unknown } | undefined;
+			if (data?.type !== "text" || typeof data.content !== "string" || data.content === "") return undefined;
+			return data.content;
+		},
+		async list(path) {
+			return (await list(path)) ?? [];
+		},
+		// No mtimes over the API; revisions/rN files are written once, so a fixed stamp is safe.
+		async stamp() {
+			return "remote";
+		},
+	};
+}
+
+/** Asks the server plugin (src/channel.ts) for one operation on this session; throws on refusal. */
+export type ChannelAsk = (operation: { op: "read"; path: string } | { op: "list"; path: string }) => Promise<{ content?: string; names?: string[] }>;
+
+/**
+ * A reader that asks the server plugin over the channel: for a session directory the file
+ * API cannot reach (outside the server's instance directory). Paths go relative to the
+ * session directory; the server refuses anything outside it.
+ */
+export function channelReader(ask: ChannelAsk, directory: string): SessionReader {
+	const rel = (path: string): string => {
+		const inside = insideRoot(directory, path);
+		if (inside === undefined) throw new Error(`${path} lies outside the session directory ${directory}`);
+		return inside === "." ? "" : inside;
+	};
+	const list = async (path: string) => (await ask({ op: "list", path: rel(path) })).names;
+	return {
+		name: `channel:${directory}`,
+		async isDirectory(path) {
+			return (await list(path)) !== undefined;
+		},
+		async readText(path) {
+			return (await ask({ op: "read", path: rel(path) })).content;
+		},
+		async list(path) {
+			return (await list(path)) ?? [];
+		},
+		async stamp() {
+			return "channel";
+		},
+	};
+}
+
+export interface SourceDeps {
+	/** The session directory as this TUI resolves it (its own settings and environment). */
+	ownDirectory: string;
+	/** The server's instance directory (`api.state.path.directory`). */
+	serverRoot: string;
+	file: FileApi;
+	/** The server's answer to `locate`, if it gave one. */
+	locate(): Promise<{ directory: string; root: string } | undefined>;
+	/**
+	 * A fresh cached `locate` answer, without asking. With `relocate`, a TUI that shares the
+	 * server's disk skips the wait: see `resolveSource`.
+	 */
+	located?(): { directory: string; root: string } | undefined;
+	/** Starts a `locate` in the background (its answer serves the next resolve). */
+	relocate?(): void;
+	/** The server plugin, for a located directory outside the server root. */
+	ask?: ChannelAsk;
+	/** Local check; defaults to the disk. */
+	isLocalDirectory?(path: string): Promise<boolean>;
+}
+
+/**
+ * Local when this TUI's own session directory exists on its disk. Otherwise the server says
+ * where the directory is (`locate`), falling back to this TUI's resolution. Inside the
+ * server directory it is read through the file API; outside it, through the server plugin
+ * over the channel (only when `locate` answered, i.e. the plugin is there).
+ */
+export async function resolveSource(deps: SourceDeps, options: { write?: boolean } = {}): Promise<SessionSource> {
+	const isLocal = deps.isLocalDirectory ?? ((path: string) => localReader.isDirectory(path).catch(() => false));
+	if (await isLocal(deps.ownDirectory)) return { kind: "local", directory: deps.ownDirectory, reader: localReader };
+	const sameDisk = async () => (await isLocal(dirname(deps.ownDirectory))) && (await isLocal(deps.serverRoot));
+	// A write creates the directory it writes to, and the server must read it: no guessing.
+	// Locally only when the server names this TUI's own directory, or does not answer (CLM
+	// disabled there) on the server's own disk; otherwise wherever the server keeps the files.
+	if (options.write) {
+		const answer = await deps.locate().catch(() => undefined);
+		if ((answer === undefined || answer.directory === deps.ownDirectory) && (await sameDisk())) {
+			return { kind: "local", directory: deps.ownDirectory, reader: localReader };
+		}
+		return placed(deps, answer);
+	}
+	// Same disk as the server (its directory and this TUI's mirror parent both exist here), and
+	// no answer cached yet: most likely a session before its first request, or a server with
+	// CLM disabled. Read the (empty) local directory now instead of waiting for `locate`,
+	// which runs in the background and corrects the source on the next load if the server
+	// keeps the files elsewhere.
+	if (deps.relocate && !deps.located?.() && (await sameDisk())) {
+		deps.relocate();
+		return { kind: "local", directory: deps.ownDirectory, reader: localReader };
+	}
+	return placed(deps, await deps.locate().catch(() => undefined));
+}
+
+/** The source for the server's answer to `locate` (or this TUI's own path without one). */
+function placed(deps: SourceDeps, located: { directory: string; root: string } | undefined): SessionSource {
+	const directory = located?.directory ?? deps.ownDirectory;
+	const root = located?.root ?? deps.serverRoot;
+	if (insideRoot(root, directory) === undefined) {
+		if (located && deps.ask) return { kind: "channel", directory, root, reader: channelReader(deps.ask, directory) };
+		return { kind: "outside", directory, root };
+	}
+	return { kind: "remote", directory, root, reader: remoteReader(deps.file, root) };
+}
+
+/** overrides.json of a source. */
+export async function sourceOverrides(source: SessionSource): Promise<OverridesRead> {
+	if (source.kind === "local") return readOverrides(source.directory);
+	if (source.kind === "outside") return { overrides: {} };
+	const path = join(source.directory, OVERRIDES_FILE);
+	let text: string | undefined;
+	try {
+		text = await source.reader.readText(path);
+	} catch (error) {
+		return { overrides: {}, warning: `could not read ${path}: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	return text === undefined ? { overrides: {} } : parseOverridesText(text, path);
+}
+
+/** Panel text for a session directory the attached TUI cannot read. */
+export function outsideMessage(source: { directory: string; root: string }): string {
+	return `The CLM files of this session would be at ${source.directory} on the server, outside the server's directory ${source.root}. ` +
+		"OpenCode's file API reads only inside that directory, and the opencode-clm server plugin did not answer to read them instead. " +
+		"Check that the server loads opencode-clm at this version, or set mirrorDir inside the project (the default .opencode/clm is).";
+}

package/tui.ts

@@ -0,0 +1,7 @@
+/**
+ * opencode-clm TUI plugin: the `/clm` panel (context size, input, edits, settings).
+ * Loaded from `tui.json` (`exports["./tui"]`); the server plugin is index.ts.
+ */
+import { tui } from "./src/tui/plugin.ts";
+
+export default { id: "opencode-clm", tui };