opencode-clm 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-clm",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "OpenCode plugin for Context Language Models: the model edits a file mirror of its own context, and the edited mirror becomes its next input.",
   "type": "module",
   "license": "MIT",
@@ -63,11 +63,11 @@
     }
   },
   "devDependencies": {
-    "@opentui/core": "0.4.5",
-    "@opentui/keymap": "0.4.5",
-    "@opentui/solid": "0.4.5",
-    "@types/bun": "1.3.14",
+    "@opentui/core": "0.5.14",
+    "@opentui/keymap": "0.5.14",
+    "@opentui/solid": "0.5.14",
+    "@types/bun": "1.4.2",
     "@xterm/headless": "6.0.0",
-    "typescript": "5.9.3"
+    "typescript": "7.0.2"
   }
 }

package/src/budget.ts

@@ -7,36 +7,53 @@
  *
  * Two measurements are kept apart and always labelled:
  *
- * - `estimated`: the harness estimate of the conversation in the *next* request (pinned
- *   task + editable context + notices). Available before every call.
+ * - `estimated`: the harness estimate of the *next* request (pinned task + editable
+ *   context + notices, plus the system prompt and tool schemas once their sizes are
+ *   known). Available before every call.
  * - `observed`: the provider-reported input size of the *previous* request (OpenCode's
- *   assistant `tokens`). Authoritative but one call late, and it includes the system
- *   prompt and tool schemas, which the budget does not cover.
+ *   assistant `tokens`). Authoritative but one call late.
  *
- * The estimate alone governs reminder tiers and the reminder text; `observed` is shown
- * for reference only, because it covers more than the budget does. The harness never
+ * The estimate alone governs reminder tiers and the reminder text; `observed` calibrates
+ * the estimate and is shown for reference. The harness never
  * blocks a request; the overflow guard (overflow.ts) withholds old tool output when the
  * estimate exceeds budget - reserve.
  */
 export interface BudgetPolicyConfig {
 	/**
 	 * Context budget in tokens the reminders are measured against. Advisory: requests are
-	 * never blocked or rolled back. `undefined` means "use the model context window".
+	 * never blocked or rolled back. When undefined, `contextFraction` decides; when both are
+	 * undefined, the budget is the model context window (the `window` setting).
 	 */
 	contextBudget?: number;
+	/**
+	 * Budget as a fraction (0 < f <= 1) of the model window minus its output limit, used when
+	 * `contextBudget` is undefined (the `50%` setting). With the window unknown the budget is
+	 * `FALLBACK_BUDGET`.
+	 */
+	contextFraction?: number;
 	/** Generation headroom reserved below the budget. The final reminder fires at budget - reserve. */
 	reserve: number;
 	/** Fractions of the budget at which escalating reminders fire (0 < f < 1), ascending. */
 	remindAtFractions: readonly number[];
 	/** Whether to fire the final "budget - reserve" reminder. */
 	remindAtReserve: boolean;
+	/**
+	 * Share of the budget (0 <= f < 1) the context must grow past its size after an accepted
+	 * edit before percentage reminders fire again; 0 turns the cooldown off. The
+	 * budget − reserve reminder is exempt.
+	 */
+	reminderCooldown: number;
 }
 
+/** Budget when a percentage budget meets an unknown model window. */
+export const FALLBACK_BUDGET = 32_000;
+
 export const DEFAULT_BUDGET_POLICY: BudgetPolicyConfig = {
-	contextBudget: 32000,
+	contextFraction: 0.5,
 	reserve: 2048,
 	remindAtFractions: [0.25, 0.5, 0.75],
 	remindAtReserve: true,
+	reminderCooldown: 0.1,
 };
 
 /**
@@ -70,23 +87,44 @@ export interface BudgetReading {
 	 * describes a context that no longer exists. The notice says so.
 	 */
 	observedStale?: boolean;
-	/** Where `budget` came from, for status text. */
-	source: "config" | "model-window";
+	/**
+	 * Where `budget` came from, for status text: `config` (a token count), `model-window`
+	 * (the window, or a token count capped by it), `window-fraction` (`fraction` of the
+	 * window), `fallback` (`FALLBACK_BUDGET`: a percentage with the window unknown).
+	 */
+	source: BudgetSource;
+	/** The configured fraction, for `window-fraction` and `fallback`. */
+	fraction?: number;
 	/** Set when `budget` was raised above the configured value to cover the fixed overhead (see `budgetFit`). */
 	raisedFrom?: number;
 }
 
+export type BudgetSource = "config" | "model-window" | "window-fraction" | "fallback";
+
 /** A reminder threshold in absolute tokens plus a stable label for re-arming. */
 export interface BudgetTier {
 	label: string;
 	tokens: number;
 }
 
+/**
+ * Defaults plus `overrides`, validated. An own `contextBudget` key without an own
+ * `contextFraction` key replaces the default fraction (`{ contextBudget: undefined }` still
+ * means "the model window"); a defined `contextBudget` always clears `contextFraction`.
+ */
 export function resolveBudgetPolicy(overrides: Partial<BudgetPolicyConfig> | undefined): BudgetPolicyConfig {
 	const merged: BudgetPolicyConfig = { ...DEFAULT_BUDGET_POLICY, ...(overrides ?? {}) };
+	const budgetGiven = overrides !== undefined && Object.hasOwn(overrides, "contextBudget");
+	const fractionGiven = overrides !== undefined && Object.hasOwn(overrides, "contextFraction");
+	if (merged.contextBudget !== undefined || (budgetGiven && !fractionGiven)) delete merged.contextFraction;
 	if (merged.contextBudget !== undefined && (!Number.isFinite(merged.contextBudget) || merged.contextBudget <= 0)) {
 		throw new Error(`contextBudget must be a positive number of tokens, got ${String(merged.contextBudget)}`);
 	}
+	if (merged.contextFraction !== undefined && (!Number.isFinite(merged.contextFraction) || merged.contextFraction <= 0 || merged.contextFraction > 1)) {
+		throw new Error(`contextFraction must be in (0, 1], got ${String(merged.contextFraction)}`);
+	}
+	if (merged.contextFraction === undefined) delete merged.contextFraction;
+	if (merged.contextBudget === undefined) delete merged.contextBudget;
 	if (!Number.isFinite(merged.reserve) || merged.reserve < 0) {
 		throw new Error(`reserve must be a nonnegative number of tokens, got ${String(merged.reserve)}`);
 	}
@@ -97,25 +135,35 @@ export function resolveBudgetPolicy(overrides: Partial<BudgetPolicyConfig> | und
 		}
 	}
 	fractions.sort((left, right) => left - right);
+	if (!Number.isFinite(merged.reminderCooldown) || merged.reminderCooldown < 0 || merged.reminderCooldown >= 1) {
+		throw new Error(`reminderCooldown must be in [0, 1) (0 = off), got ${String(merged.reminderCooldown)}`);
+	}
 	return { ...merged, remindAtFractions: fractions };
 }
 
 /**
- * Effective budget: the configured budget (default 32,000), capped by the model's context
- * window minus its output allowance when that is smaller. `undefined` contextBudget means
- * "use the window". An output limit that is not finite, <= 0, or >= the window is ignored.
+ * Effective budget against the model window minus its output allowance (the base): a token
+ * count, capped by the base when that is smaller; else `contextFraction` of the base
+ * (default 50%), or `FALLBACK_BUDGET` with the window unknown; else the base itself. An
+ * output limit that is not finite, <= 0, or >= the window is ignored. Undefined only for
+ * the `window` setting with the window unknown.
  */
 export function resolveBudget(
 	policy: BudgetPolicyConfig,
 	modelContextWindow: number | undefined,
 	modelOutputLimit = 0,
-): Pick<BudgetReading, "budget" | "reserve" | "source"> | undefined {
+): Pick<BudgetReading, "budget" | "reserve" | "source" | "fraction"> | undefined {
 	const window = modelContextWindow !== undefined && Number.isFinite(modelContextWindow) && modelContextWindow > 0
 		? modelContextWindow - (Number.isFinite(modelOutputLimit) && modelOutputLimit > 0 && modelOutputLimit < modelContextWindow ? modelOutputLimit : 0)
 		: undefined;
 	if (policy.contextBudget !== undefined && (window === undefined || policy.contextBudget <= window)) {
 		return { budget: policy.contextBudget, reserve: Math.min(policy.reserve, policy.contextBudget), source: "config" };
 	}
+	const fraction = policy.contextBudget === undefined ? policy.contextFraction : undefined;
+	if (fraction !== undefined) {
+		const budget = window !== undefined ? Math.max(1, Math.floor(window * fraction)) : FALLBACK_BUDGET;
+		return { budget, reserve: Math.min(policy.reserve, budget), source: window !== undefined ? "window-fraction" : "fallback", fraction };
+	}
 	if (window !== undefined) {
 		return { budget: window, reserve: Math.min(policy.reserve, window), source: "model-window" };
 	}
@@ -202,7 +250,7 @@ export function budgetFitLine(fit: BudgetFit): string {
  * The one-time model notice for a budget that cannot hold OpenCode's fixed overhead plus a
  * working margin. Text written for this package.
  */
-export function budgetTooSmallNoticeText(fit: BudgetFit): string {
+export function budgetTooSmallNoticeText(fit: BudgetFit, options: NoticeOptions = {}): string {
 	const head =
 		`[CLM BUDGET] The configured budget of ${formatTokens(fit.configured)} tokens is too small for this session: ` +
 		`OpenCode's system prompt and tool schemas take about ${formatTokens(fit.overhead ?? 0)} tokens of every request, ` +
@@ -212,7 +260,9 @@ export function budgetTooSmallNoticeText(fit: BudgetFit): string {
 		const raise = fit.raised ? `CLM raised this session's budget to ${formatTokens(fit.effective)} tokens, the most the model window allows, ` : "The model window allows no larger budget, ";
 		return (
 			`${head} ${raise}which still leaves only ${left} tokens for the conversation. ` +
-			"The overflow guard will hold back most tool results: keep the context mirror short and read files in small parts."
+			(options.noticesOnly
+				? "The overflow guard will hold back most tool results: read files in small parts."
+				: "The overflow guard will hold back most tool results: keep the context mirror short and read files in small parts.")
 		);
 	}
 	return (
@@ -252,35 +302,93 @@ export function governingTokens(reading: Pick<BudgetReading, "estimated">): numb
 	return reading.estimated;
 }
 
+/** The outcome of one `BudgetTracker.check`. */
+export interface BudgetCheck {
+	/** The highest newly crossed tier to announce, if any. */
+	tier?: BudgetTier;
+	/** Tiers crossed during a reminder cooldown: consumed without a notice. */
+	suppressed: BudgetTier[];
+	/** Governing size at which the active cooldown ends; undefined without one. */
+	cooldownUntil?: number;
+}
+
 /**
  * Escalating, re-arming tier tracker over absolute token thresholds. Re-derives its state
  * when the tier set changes (for example after the budget changes).
+ *
+ * Reminder cooldown: `editAccepted()` marks an accepted context edit. The next check records
+ * the governing size E; until the size reaches E + cooldown × budget, crossed percentage tiers
+ * are marked fired without a notice (consumed, not deferred). The budget-reserve tier is
+ * exempt. A later accepted edit restarts the cooldown; a reset, `clearCooldown` or a tier change ends it.
  */
 export class BudgetTracker {
 	private fired = new Set<string>();
 	private tierKey = "";
+	/** An edit was accepted and the next check has not yet recorded its size. */
+	private cooldownPending = false;
+	/** Governing size recorded after the last accepted edit, while the cooldown runs. */
+	private cooldownStart: number | undefined;
 
 	reset(): void {
 		this.fired.clear();
+		this.clearCooldown();
+	}
+
+	/** End the reminder cooldown; fired tiers stay fired. */
+	clearCooldown(): void {
+		this.cooldownPending = false;
+		this.cooldownStart = undefined;
+	}
+
+	/** Start (or restart) the reminder cooldown from the next reading. */
+	editAccepted(): void {
+		this.cooldownPending = true;
+		this.cooldownStart = undefined;
 	}
 
 	/** Returns the highest newly crossed tier, or undefined when nothing new fired. */
-	observe(reading: BudgetReading, tiers: readonly BudgetTier[]): BudgetTier | undefined {
+	observe(reading: BudgetReading, tiers: readonly BudgetTier[], cooldown = 0): BudgetTier | undefined {
+		return this.check(reading, tiers, cooldown).tier;
+	}
+
+	/** `observe` with the tiers a cooldown suppressed. `cooldown`: share of the budget, 0 = off. */
+	check(reading: BudgetReading, tiers: readonly BudgetTier[], cooldown = 0): BudgetCheck {
 		const key = tiers.map((tier) => `${tier.label}:${tier.tokens}`).join("|");
 		if (key !== this.tierKey) {
 			this.tierKey = key;
 			this.fired.clear();
+			this.cooldownStart = undefined;
 		}
 		const tokens = governingTokens(reading);
 		this.fired = new Set([...this.fired].filter((label) => {
 			const tier = tiers.find((candidate) => candidate.label === label);
 			return tier !== undefined && tokens >= tier.tokens;
 		}));
-		const crossed = tiers.filter((tier) => tokens >= tier.tokens && !this.fired.has(tier.label));
-		if (crossed.length === 0) return undefined;
+		if (this.cooldownPending) {
+			this.cooldownPending = false;
+			this.cooldownStart = tokens;
+		}
+		let cooldownUntil: number | undefined;
+		if (this.cooldownStart !== undefined) {
+			const until = this.cooldownStart + cooldown * reading.budget;
+			// cooldown 0 (off, possibly set mid-cooldown) ends it outright.
+			if (cooldown > 0 && tokens < until) cooldownUntil = until;
+			else this.cooldownStart = undefined;
+		}
+		let crossed = tiers.filter((tier) => tokens >= tier.tokens && !this.fired.has(tier.label));
+		const suppressed: BudgetTier[] = [];
+		if (cooldownUntil !== undefined) {
+			for (const tier of crossed) {
+				if (tier.label === "budget-reserve") continue;
+				suppressed.push(tier);
+				this.fired.add(tier.label);
+			}
+			crossed = crossed.filter((tier) => tier.label === "budget-reserve");
+		}
+		if (crossed.length === 0) return { suppressed, cooldownUntil };
 		const top = crossed[crossed.length - 1]!;
 		for (const tier of tiers) if (tier.tokens <= top.tokens) this.fired.add(tier.label);
-		return top;
+		return { tier: top, suppressed, cooldownUntil };
 	}
 }
 
@@ -293,11 +401,27 @@ function calibrated(reading: Pick<BudgetReading, "calibration">): boolean {
 	return reading.calibration !== undefined && reading.calibration > 1.005;
 }
 
+/** `0.5` → `50%`, `0.125` → `12.5%`. */
+export function formatPercent(fraction: number): string {
+	return `${Number((fraction * 100).toFixed(2))}%`;
+}
+
+/** Short origin label of a budget: `configured`, `model window`, `50% of model window`, … */
+export function budgetOrigin(reading: Pick<BudgetReading, "source" | "fraction">): string {
+	const percent = reading.fraction !== undefined ? formatPercent(reading.fraction) : "";
+	switch (reading.source) {
+		case "config": return "configured";
+		case "model-window": return "model window";
+		case "window-fraction": return `${percent} of model window`;
+		case "fallback": return `fallback, ${percent} of an unknown model window`;
+	}
+}
+
 /** One line for status text: budget, estimate, and observation, each labelled. */
 export function budgetSummaryLine(reading: BudgetReading): string {
 	const origin = reading.raisedFrom !== undefined
 		? `raised from ${formatTokens(reading.raisedFrom)} to cover the fixed overhead`
-		: reading.source === "config" ? "configured" : "model window";
+		: budgetOrigin(reading);
 	const parts = [
 		`budget ${formatTokens(reading.budget)} tok (${origin}, reserve ${formatTokens(reading.reserve)})`,
 		`estimated next request ${formatTokens(reading.estimated)}${calibrated(reading) ? ` (×${reading.calibration!.toFixed(2)} calibrated)` : ""}`,
@@ -310,17 +434,24 @@ export function budgetSummaryLine(reading: BudgetReading): string {
 	return parts.join(" · ");
 }
 
+/** Model-facing notice variants. `noticesOnly`: the session runs `mode notices-only`, so no text may point the model at a mirror. */
+export interface NoticeOptions {
+	noticesOnly?: boolean;
+}
+
 /**
  * The model-facing reminder. States the estimate and the provider count separately, the
  * budget and the tokens left, the mirror path, and, from the third tier up, what the
  * overflow guard does above `overflowLimit` (default budget - reserve). Pass `null` when the
- * guard is off: the notice then leaves the guard out.
+ * guard is off: the notice then leaves the guard out. `noticesOnly` keeps the measurement,
+ * the budget, the tokens left and the guard sentence, and drops every invitation to edit.
  */
 export function budgetNoticeText(
 	reading: BudgetReading,
 	tier: BudgetTier,
 	mirrorPath: string | undefined,
 	overflowLimit: number | null = reading.budget - reading.reserve,
+	options: NoticeOptions = {},
 ): string {
 	const governing = governingTokens(reading);
 	const remaining = Math.max(0, reading.budget - governing);
@@ -334,6 +465,19 @@ export function budgetNoticeText(
 	const overflow = overflowLimit === null
 		? ""
 		: ` Above ${formatTokens(overflowLimit)} tokens the overflow guard holds back the oldest new tool results and saves them to files.`;
+	if (options.noticesOnly) {
+		const fraction = tier.tokens / reading.budget;
+		if (tier.label === "budget-reserve") {
+			return (
+				`[CLM BUDGET] Context is at ${formatTokens(governing)} of a ${formatTokens(reading.budget)}-token budget ` +
+				`(${measurement}). Only ${formatTokens(remaining)} tokens remain, which is inside the ${formatTokens(reading.reserve)}-token generation reserve.${overflow}`
+			);
+		}
+		const base =
+			`[CLM BUDGET] Context crossed ${tier.label} of a ${formatTokens(reading.budget)}-token budget: ${measurement}. ` +
+			`${formatTokens(remaining)} tokens remain; the final reminder comes at ${formatTokens(reading.budget - reading.reserve)} tokens.`;
+		return fraction <= 0.5 ? base : `${base}${overflow}`;
+	}
 	if (tier.label === "budget-reserve") {
 		return (
 			`[CLM BUDGET] Context is at ${formatTokens(governing)} of a ${formatTokens(reading.budget)}-token budget ` +

package/src/channel.ts

@@ -0,0 +1,187 @@
+// The turn-free channel between the TUI plugin and the server plugin. Both sides speak
+// through OpenCode's `tui.command.execute` bus event: `POST /tui/publish` accepts any
+// command string, the server publishes it on the instance bus, and every listener sees it:
+// the server plugin's `event` hook, each TUI's own `api.event` and the TUI app, which
+// dispatches the string as a keymap command (an unknown name is a no-op). Requests and
+// replies are prefixed, base64url-encoded JSON, so they carry no spaces and never collide
+// with a real keymap command. Written for this package. Verified against opencode 1.18.34:
+// publish handler server/routes/instance/httpapi/handlers/tui.ts:84-93; command schema
+// packages/schema/src/tui-event.ts:13-37; plugin `event` hook plugin/index.ts:255-260 (events
+// of the plugin's own directory only); TUI app dispatch packages/tui/src/app.tsx:987-990.
+
+/** `tui.command.execute` event type (opencode packages/schema/src/tui-event.ts). */
+export const COMMAND_EVENT = "tui.command.execute";
+export const REQUEST_PREFIX = "opencode-clm.request:";
+export const REPLY_PREFIX = "opencode-clm.reply:";
+export const CHANNEL_VERSION = 1;
+
+export type ChannelOperation =
+	/** Where the server keeps the session's files. Answer: `directory` and `root`. */
+	| { op: "locate" }
+	/** `/clm config <setting> <value>`, `/clm on|off` and the panel's apply. */
+	| { op: "set"; setting: string; value: string }
+	/** `/clm config reset`. */
+	| { op: "settings-reset" }
+	/** `/clm reset`: drop the accepted revision. */
+	| { op: "reset" }
+	/** A file of the session directory (`path` relative to it). Answer: `content`, absent when missing. */
+	| { op: "read"; path: string }
+	/** A directory of the session directory (`""` = itself). Answer: `names`, absent when missing. */
+	| { op: "list"; path: string };
+
+/** Largest file a `read` reply carries; replies travel on the instance bus to every client. */
+export const MAX_READ_BYTES = 4 * 1024 * 1024;
+
+export type ChannelRequest = ChannelOperation & { v: typeof CHANNEL_VERSION; id: string; session: string };
+
+export interface ChannelReply {
+	v: typeof CHANNEL_VERSION;
+	id: string;
+	ok: boolean;
+	/** User-facing result or error. */
+	text: string;
+	/** `locate`: the session directory on the server. */
+	directory?: string;
+	/** `locate`: the server's instance directory, the root `file.read` paths are relative to. */
+	root?: string;
+	/** `read`: the file text. */
+	content?: string;
+	/** `list`: the entry names. */
+	names?: string[];
+}
+
+function encode(prefix: string, value: unknown): string {
+	return prefix + Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}
+
+function decode(prefix: string, command: unknown): Record<string, unknown> | undefined {
+	if (typeof command !== "string" || !command.startsWith(prefix)) return undefined;
+	try {
+		const value: unknown = JSON.parse(Buffer.from(command.slice(prefix.length), "base64url").toString("utf8"));
+		if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+		const record = value as Record<string, unknown>;
+		if (record.v !== CHANNEL_VERSION || typeof record.id !== "string" || record.id === "") return undefined;
+		return record;
+	} catch {
+		return undefined;
+	}
+}
+
+export function encodeRequest(request: ChannelRequest): string {
+	return encode(REQUEST_PREFIX, request);
+}
+
+/** The request in a command string; undefined for anything else (foreign or malformed). */
+export function decodeRequest(command: unknown): ChannelRequest | undefined {
+	const record = decode(REQUEST_PREFIX, command);
+	if (!record || typeof record.session !== "string" || record.session === "") return undefined;
+	switch (record.op) {
+		case "locate":
+		case "settings-reset":
+		case "reset":
+			return { v: CHANNEL_VERSION, id: record.id as string, session: record.session, op: record.op };
+		case "read":
+		case "list":
+			if (typeof record.path !== "string") return undefined;
+			return { v: CHANNEL_VERSION, id: record.id as string, session: record.session, op: record.op, path: record.path };
+		case "set":
+			if (typeof record.setting !== "string" || typeof record.value !== "string") return undefined;
+			return { v: CHANNEL_VERSION, id: record.id as string, session: record.session, op: "set", setting: record.setting, value: record.value };
+		default:
+			return undefined;
+	}
+}
+
+export function encodeReply(reply: ChannelReply): string {
+	return encode(REPLY_PREFIX, reply);
+}
+
+export function decodeReply(command: unknown): ChannelReply | undefined {
+	const record = decode(REPLY_PREFIX, command);
+	if (!record || typeof record.ok !== "boolean" || typeof record.text !== "string") return undefined;
+	return {
+		v: CHANNEL_VERSION,
+		id: record.id as string,
+		ok: record.ok,
+		text: record.text,
+		...(typeof record.directory === "string" ? { directory: record.directory } : {}),
+		...(typeof record.root === "string" ? { root: record.root } : {}),
+		...(typeof record.content === "string" ? { content: record.content } : {}),
+		...(Array.isArray(record.names) && record.names.every((name) => typeof name === "string") ? { names: record.names as string[] } : {}),
+	};
+}
+
+/** The command string of a `tui.command.execute` event, if the value is one. */
+export function commandOf(event: unknown): string | undefined {
+	if (!event || typeof event !== "object") return undefined;
+	const { type, properties } = event as { type?: unknown; properties?: { command?: unknown } };
+	if (type !== COMMAND_EVENT) return undefined;
+	return typeof properties?.command === "string" ? properties.command : undefined;
+}
+
+/** The TUI side: send a request, wait for the reply with the same id. */
+export interface ChannelClientDeps {
+	/** Publishes a `tui.command.execute` event with this command string. */
+	publish(command: string): Promise<void>;
+	/** Subscribes to `tui.command.execute` command strings; returns the unsubscribe. */
+	subscribe(handler: (command: string) => void): () => void;
+	timeoutMs?: number;
+	/** Request ids; random by default. */
+	newId?: () => string;
+}
+
+export interface ChannelClient {
+	/** `timeoutMs` overrides the client's default for this request. */
+	request(session: string, operation: ChannelOperation, timeoutMs?: number): Promise<ChannelReply>;
+	dispose(): void;
+}
+
+export class ChannelTimeout extends Error {
+	constructor(readonly timeoutMs: number) {
+		super(
+			`the opencode-clm server plugin did not answer within ${Math.round(timeoutMs / 100) / 10} s: the server does not load ` +
+				"opencode-clm, loads an older version without the TUI channel, or has CLM disabled (enabled: false)",
+		);
+	}
+}
+
+export const CHANNEL_TIMEOUT_MS = 5_000;
+/** `locate` is asked on panel loads; a short wait keeps a missing server plugin from stalling them. */
+export const LOCATE_TIMEOUT_MS = 1_000;
+
+export function createChannelClient(deps: ChannelClientDeps): ChannelClient {
+	const pending = new Map<string, (reply: ChannelReply) => void>();
+	const unsubscribe = deps.subscribe((command) => {
+		const reply = decodeReply(command);
+		if (!reply) return;
+		pending.get(reply.id)?.(reply);
+	});
+	const newId = deps.newId ?? (() => crypto.randomUUID());
+	const defaultTimeoutMs = deps.timeoutMs ?? CHANNEL_TIMEOUT_MS;
+	return {
+		request(session, operation, timeoutMs = defaultTimeoutMs) {
+			const id = newId();
+			const request = { ...operation, v: CHANNEL_VERSION, id, session } as ChannelRequest;
+			return new Promise<ChannelReply>((resolve, reject) => {
+				const timer = setTimeout(() => {
+					pending.delete(id);
+					reject(new ChannelTimeout(timeoutMs));
+				}, timeoutMs);
+				pending.set(id, (reply) => {
+					clearTimeout(timer);
+					pending.delete(id);
+					resolve(reply);
+				});
+				deps.publish(encodeRequest(request)).catch((error: unknown) => {
+					clearTimeout(timer);
+					pending.delete(id);
+					reject(error instanceof Error ? error : new Error(String(error)));
+				});
+			});
+		},
+		dispose() {
+			unsubscribe();
+			pending.clear();
+		},
+	};
+}