opencode-clm 0.2.0 → 0.4.0

package/src/tui/plugin.ts

@@ -6,16 +6,20 @@ 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, resetSettings, sessionValues, showSetting } from "../overrides.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 { readSessionFiles, sessionDirectory } from "../session-files.ts";
+import { readSessionDirectory, sessionDirectory, type SessionReader } from "../session-files.ts";
 import { resolveSettings, type ClmSettings } from "../settings.ts";
-import { fallbackBudget, latestUsage, modelLimits, overridesNewer, serverBase, serverPluginOptions, settingsView } from "./data.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 { createPanel, type PanelController } from "./panel.ts";
+import { createFooter, createPanel, type PanelController } from "./panel.ts";
 
 export const PANEL_ROUTE = "opencode-clm.panel";
 const OPEN_COMMAND = "opencode-clm.panel.open";
@@ -24,6 +28,15 @@ const RELOAD_DEBOUNCE_MS = 250;
 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);
@@ -40,6 +53,60 @@ export const tui: TuiPlugin = async (api, tuiOptions) => {
 		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
@@ -47,48 +114,73 @@ export const tui: TuiPlugin = async (api, tuiOptions) => {
 	 * 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, files: Pick<SessionFiles, "state" | "snapshot">) => {
+	const sessionSettings = async (sessionID: string, from: SessionSource, files: Pick<SessionFiles, "state" | "snapshot">) => {
 		const own = settings();
-		const { base, source } = serverBase(own, files.snapshot);
-		const directory = sessionDirectory(own.mirrorDir, sessionID);
+		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 = await sessionValues(directory, base, baseEditing);
+		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: source, baseEditing, directory, values, ...(read.warning ? { warning: read.warning } : {}), ...(read.mtimeMs !== undefined ? { overridesAt: read.mtimeMs } : {}) };
+		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 resolved = settings();
-		const files = await readSessionFiles(resolved.mirrorDir, sessionID);
+		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, files);
+		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;
+		if (current.values.effective.settings.mode === "notices-only") model.noticesOnly = true;
 		model.settings = settingsView(current.values, model, {
-			format: { ...(limits.context ? { modelWindow: limits.context } : {}) },
+			format: { ...(limits.context ? { modelWindow: limits.context } : {}), ...(limits.output ? { modelOutput: limits.output } : {}) },
 			...(current.warning ? { warning: current.warning } : {}),
 		});
+		model.settings.rows.push(resetRow(model.settings.changed.length));
 		return model;
 	};
 
-	/** Validates and writes one setting to the session's overrides.json; returns `Label: value`. */
-	const applySetting = async (sessionID: string, name: string, value: string): Promise<string> => {
-		const files = await readSessionFiles(settings().mirrorDir, sessionID);
-		const current = await sessionSettings(sessionID, files);
+	/** 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 result.text;
+		return { text: result.text, viaServer: false };
 	};
 
 	/** False when `/clm` belongs to someone else: `commands: false`, or a user-defined command. */
@@ -125,10 +217,26 @@ export const tui: TuiPlugin = async (api, tuiOptions) => {
 			active?.controller.dispose();
 			const controller = createPanel(api, {
 				page,
-				load: () => loadModel(sessionID).catch((error: unknown) => errorModel(sessionID, error)),
+				// 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);
@@ -168,10 +276,11 @@ export const tui: TuiPlugin = async (api, tuiOptions) => {
 	/** 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). */
-	const handle = async (command: Exclude<ClmCommand, { kind: "server" }>): Promise<void> => {
+	/** 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;
@@ -186,64 +295,142 @@ export const tui: TuiPlugin = async (api, tuiOptions) => {
 			return;
 		}
 		switch (command.kind) {
-			case "path":
-				toast(sessionDirectory(settings().mirrorDir, sessionID));
+			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 files = await readSessionFiles(settings().mirrorDir, sessionID);
-				const current = await sessionSettings(sessionID, files);
+				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 {
-					toast(`CLM ${await applySetting(sessionID, command.setting, command.value)}.`);
+					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":
-				await resetSettings(sessionDirectory(settings().mirrorDir, sessionID));
-				toast("CLM settings reset to the defaults.");
+			case "config-reset": {
+				if (!(await resetSessionSettings(sessionID)).viaServer) toast("CLM settings reset to the defaults.");
 				refreshPanel(sessionID);
 				return;
-			case "enable":
+			}
+			case "enable": {
 				// The same override as the server's `/clm on|off` and `/clm config editing`.
-				await applySetting(sessionID, "editing", command.enabled ? "on" : "off");
-				toast(`CLM ${command.enabled ? "on" : "off"} for this session`);
+				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));
-	const offMessage = api.event.on("message.updated", (event) =>
-		scheduleReload((event.properties as { info?: { sessionID?: unknown } }).info?.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();
 	});
@@ -270,7 +457,7 @@ 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}`,
+		`CLM ${model.enabled ? "on" : "off"}${model.enabled && model.noticesOnly ? " · mode notices-only" : ""} · 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,

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).";
+}