opencode-clm 0.3.0 → 0.4.1

package/src/settings.ts

@@ -47,6 +47,22 @@ export interface ClmSettings {
 	oneTool: boolean;
 	/** Append `[context: ~N of B tokens after this result]` to tool results (paper-harness parity). */
 	trailer: boolean;
+	/**
+	 * `edit`: the model edits its context through the mirror. `notices-only`: no mirror, no
+	 * protocol prompt and no edits; budget notices, reminders, the guard, the cap and the
+	 * trailer still apply (to compare telling the model its budget with letting it edit).
+	 */
+	mode: ClmMode;
+}
+
+export type ClmMode = "edit" | "notices-only";
+
+/** `edit`, `notices-only`, or `notices` (an alias of `notices-only`). */
+export function parseMode(value: unknown, name = "mode"): ClmMode {
+	const text = String(value).trim().toLowerCase();
+	if (text === "edit") return "edit";
+	if (text === "notices-only" || text === "notices") return "notices-only";
+	throw new Error(`${name} must be edit or notices-only, got ${JSON.stringify(value)}`);
 }
 
 export type CompactionMode = "auto" | "off" | "on";
@@ -59,11 +75,12 @@ export function parseCompaction(value: unknown, name = "compaction"): Compaction
 
 export const PACKAGE_DIR = resolve(fileURLToPath(new URL("..", import.meta.url)));
 export const HOUSE_STEERING = join(PACKAGE_DIR, "steering", "house-brief.md");
-export const SKILLS_DIR = join(PACKAGE_DIR, "skills");
+export const SKILLS_DIR = join(PACKAGE_DIR, ".agents/skills/clm-context");
 
 type Env = Record<string, string | undefined>;
 
 const OFF_WORDS = ["none", "off"];
+const BUDGET_FORMS = `a number of tokens (32000, 32k), a percentage of the model window (1% to 100%), or "window"`;
 
 function pick(options: Record<string, unknown>, key: string, env: Env, envKey: string): unknown {
 	if (options[key] !== undefined) return options[key];
@@ -85,6 +102,34 @@ export function parseTokens(value: unknown, name: string): number {
 	return Math.round(Number(match[1]) * scale);
 }
 
+export type BudgetValue =
+	| { kind: "tokens"; tokens: number }
+	| { kind: "fraction"; fraction: number }
+	| { kind: "window" };
+
+/**
+ * A budget setting: `32000` / `32k` (tokens), `50%` (of the model window minus its output
+ * limit; 1% to 100%), or `window` / `model` (the whole of it).
+ */
+export function parseBudget(value: unknown, name = "budget"): BudgetValue {
+	const text = String(value).trim().toLowerCase();
+	if (text === "window" || text === "model") return { kind: "window" };
+	if (text.endsWith("%")) {
+		const number = text.slice(0, -1).trim();
+		const percent = /^\d+(?:\.\d+)?$/.test(number) ? Number(number) : Number.NaN;
+		if (!(percent >= 1 && percent <= 100)) throw new Error(`${name} must be ${BUDGET_FORMS}, got ${JSON.stringify(value)}`);
+		return { kind: "fraction", fraction: percent / 100 };
+	}
+	let tokens: number;
+	try {
+		tokens = parseTokens(value, name);
+	} catch {
+		throw new Error(`${name} must be ${BUDGET_FORMS}, got ${JSON.stringify(value)}`);
+	}
+	if (tokens <= 0) throw new Error(`${name} must be a positive number of tokens or "window", got ${JSON.stringify(value)}`);
+	return { kind: "tokens", tokens };
+}
+
 export function parseFlag(value: unknown, name: string): boolean {
 	if (typeof value === "boolean") return value;
 	const key = String(value).trim().toLowerCase();
@@ -111,6 +156,23 @@ export function parseFractions(value: unknown, name: string): number[] | "off" {
 	return [...new Set(fractions)];
 }
 
+const COOLDOWN_FORMS = `a share of the budget between 0 and 1, as a percentage (10%) or a fraction (0.1), or off`;
+
+/**
+ * The reminder cooldown: `10%` or `0.1` (a share of the budget, strictly between 0 and 1), or
+ * `off` / `none` / `0` for no cooldown (0).
+ */
+export function parseCooldown(value: unknown, name = "reminderCooldown"): number {
+	if (value === false) return 0;
+	const text = String(value).trim().toLowerCase();
+	if (text === "off" || text === "none" || text === "0" || text === "0%") return 0;
+	const percent = text.endsWith("%");
+	const number = percent ? text.slice(0, -1).trim() : text;
+	const parsed = /^\d*\.?\d+$/.test(number) ? Number(number) / (percent ? 100 : 1) : Number.NaN;
+	if (!(parsed > 0 && parsed < 1)) throw new Error(`${name} must be ${COOLDOWN_FORMS}, got ${JSON.stringify(value)}`);
+	return parsed;
+}
+
 function withName<T>(name: string, parse: () => T): T {
 	try {
 		return parse();
@@ -132,6 +194,7 @@ export function resolveSettings(options: Record<string, unknown> = {}, env: Env
 	const budgetRaw = pick(options, "budget", env, "CLM_BUDGET");
 	const reserveRaw = pick(options, "reserve", env, "CLM_RESERVE");
 	const remindRaw = pick(options, "remindAt", env, "CLM_REMIND_AT");
+	const cooldownRaw = pick(options, "reminderCooldown", env, "CLM_REMINDER_COOLDOWN");
 	const gateRaw = pick(options, "gate", env, "CLM_EDIT_GATE");
 	const guardRaw = pick(options, "guard", env, "CLM_OVERFLOW");
 	const capRaw = pick(options, "observationCap", env, "CLM_OBSERVATION_CAP");
@@ -144,11 +207,13 @@ export function resolveSettings(options: Record<string, unknown> = {}, env: Env
 	const compactionRaw = pick(options, "compaction", env, "CLM_NATIVE_COMPACTION");
 	const oneToolRaw = pick(options, "oneTool", env, "CLM_ONE_TOOL_PER_TURN");
 	const trailerRaw = pick(options, "trailer", env, "CLM_SIZE_TRAILER");
+	const modeRaw = pick(options, "mode", env, "CLM_MODE");
 
 	const overrides: Partial<BudgetPolicyConfig> = {};
 	if (budgetRaw !== undefined) {
-		overrides.contextBudget = String(budgetRaw).trim().toLowerCase() === "window" ? undefined : parseTokens(budgetRaw, "budget");
-		if (overrides.contextBudget === 0) throw new Error(`budget must be a positive number of tokens or "window", got ${JSON.stringify(budgetRaw)}`);
+		const parsed = parseBudget(budgetRaw, "budget");
+		overrides.contextBudget = parsed.kind === "tokens" ? parsed.tokens : undefined;
+		overrides.contextFraction = parsed.kind === "fraction" ? parsed.fraction : undefined;
 	}
 	if (reserveRaw !== undefined) overrides.reserve = parseTokens(reserveRaw, "reserve");
 	if (remindRaw !== undefined) {
@@ -164,6 +229,7 @@ export function resolveSettings(options: Record<string, unknown> = {}, env: Env
 			overrides.remindAtFractions = fractions;
 		}
 	}
+	if (cooldownRaw !== undefined) overrides.reminderCooldown = parseCooldown(cooldownRaw, "reminderCooldown");
 	const budget = withName("budget", () => resolveBudgetPolicy({ ...DEFAULT_BUDGET_POLICY, ...overrides }));
 
 	let guard: ClmSettings["guard"] = "withhold";
@@ -213,5 +279,6 @@ export function resolveSettings(options: Record<string, unknown> = {}, env: Env
 		compaction: compactionRaw === undefined ? "auto" : parseCompaction(compactionRaw),
 		oneTool: oneToolRaw === undefined ? false : parseFlag(oneToolRaw, "oneTool"),
 		trailer: trailerRaw === undefined ? false : parseFlag(trailerRaw, "trailer"),
+		mode: modeRaw === undefined ? "edit" : parseMode(modeRaw),
 	};
 }

package/src/state.ts

@@ -96,6 +96,23 @@ function isMessageArray(value: unknown): value is LiveContextMessage[] {
 	);
 }
 
+/** Per-message stamps (`projection.ts` SourceStamp): a hex digest and a finite `updatedAt`. */
+function isSourceStamps(value: unknown, count: unknown): boolean {
+	return (
+		Array.isArray(value) &&
+		value.length === count &&
+		value.every(
+			(stamp) =>
+				isObject(stamp) &&
+				typeof stamp.digest === "string" &&
+				/^[a-f0-9]{64}$/.test(stamp.digest) &&
+				Number.isFinite(stamp.updatedAt) &&
+				(stamp.strippedDigest === undefined ||
+					(typeof stamp.strippedDigest === "string" && /^[a-f0-9]{64}$/.test(stamp.strippedDigest))),
+		)
+	);
+}
+
 function isContextEditTrace(value: unknown): value is ContextEditTrace {
 	if (!isObject(value)) return false;
 	const trace = value as Partial<ContextEditTrace>;
@@ -134,6 +151,7 @@ export function isProjectionCheckpoint(value: unknown): value is ProjectionCheck
 		checkpoint.sourceIds.every((id) => typeof id === "string") &&
 		typeof checkpoint.sourceDigest === "string" &&
 		/^[a-f0-9]{64}$/.test(checkpoint.sourceDigest) &&
+		(checkpoint.sourceStamps === undefined || isSourceStamps(checkpoint.sourceStamps, checkpoint.sourceMessageCount)) &&
 		isMessageArray(checkpoint.projectedMessages) &&
 		Number.isFinite(checkpoint.beforeEstimate) &&
 		Number.isFinite(checkpoint.afterEstimate) &&
@@ -238,12 +256,43 @@ export async function loadLiveContextState(directory: string): Promise<LoadedSta
 		delete parsed.budgetCheck;
 		repaired = `${path} had an invalid budgetCheck; dropped it, the fixed overhead is measured again.`;
 	}
+	// A malformed outcome costs only itself: the panel loses one line, the checkpoint stays.
+	if (isObject(parsed) && parsed.lastOutcome !== undefined && !isOutcome(parsed.lastOutcome)) {
+		delete parsed.lastOutcome;
+		repaired = `${path} had an invalid lastOutcome; dropped it, the last outcome is unknown.`;
+	}
+	// Malformed per-message stamps cost only tail re-anchoring: the checkpoint keeps working
+	// with the whole-prefix digest and fails closed on a mismatch, as before.
+	if (
+		isObject(parsed) &&
+		isObject(parsed.checkpoint) &&
+		parsed.checkpoint.sourceStamps !== undefined &&
+		!isSourceStamps(parsed.checkpoint.sourceStamps, parsed.checkpoint.sourceMessageCount)
+	) {
+		delete parsed.checkpoint.sourceStamps;
+		repaired = `${path} had invalid sourceStamps; dropped them, tail re-anchoring is off for this checkpoint.`;
+	}
 	if (!isLiveContextState(parsed)) {
-		return { state: initialLiveContextState(), warning: `${path} has an invalid shape; starting clean.` };
+		return { state: initialLiveContextState(), warning: `${path} has an invalid shape (${stateProblem(parsed)}); starting clean.` };
 	}
 	return repaired ? { state: parsed, repaired } : { state: parsed };
 }
 
+/** Names the first state check `value` fails, so a load warning locates the bad field. */
+function stateProblem(value: unknown): string {
+	if (!isObject(value)) return "not an object";
+	if (value.version !== STATE_VERSION) return `unsupported version ${JSON.stringify(value.version)}`;
+	if (typeof value.enabled !== "boolean") return "enabled is not a boolean";
+	if (!isCount(value.revision)) return "revision is not a count";
+	if (value.checkpoint !== undefined) {
+		if (!isProjectionCheckpoint(value.checkpoint)) return "checkpoint is invalid";
+		if (value.checkpoint.revision !== value.revision) return "checkpoint revision does not match the state revision";
+	}
+	if (value.lastOutcome !== undefined && !isOutcome(value.lastOutcome)) return "lastOutcome is invalid";
+	if (value.budgetCheck !== undefined && !isBudgetCheck(value.budgetCheck)) return "budgetCheck is invalid";
+	return "unknown";
+}
+
 /**
  * Write `state.json` atomically with mode 0600: temp file, fsync, rename, then fsync the
  * directory (best effort). Concurrent saves are not ordered: the last rename wins, so an

package/src/tui/data.ts

@@ -155,14 +155,15 @@ export function sizeLine(latest: Pick<TimelinePoint, "tokens" | "measured" | "es
  * `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 {
+export function footerText(model: Pick<PanelModel, "found" | "enabled" | "revision" | "timeline" | "budget"> & Partial<Pick<PanelModel, "noticesOnly">>): string | undefined {
 	if (!model.found) return undefined;
 	if (!model.enabled) return `clm off · r${model.revision}`;
+	const mode = model.noticesOnly ? " notices-only" : "";
 	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}`;
+	return `clm${mode}${size} · r${model.revision}`;
 }
 
 /** Key of the settings page's "Reset to defaults" row, and the choice that resets. */
@@ -199,6 +200,11 @@ export function detailLines(
 			? "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"}`);
 	}
+	if (effective.settings.mode === "notices-only") {
+		lines.push(effective.editing
+			? "Mode notices-only: budget notices and the guard run; no mirror, the model cannot edit its context"
+			: "Mode notices-only (CLM editing is off, so nothing runs)");
+	}
 	const limit = model.budgetInfo?.limit;
 	lines.push(effective.settings.guard === "off"
 		? "Guard off"

package/src/tui/panel.ts

@@ -9,7 +9,7 @@ import type { TextChunk } from "@opentui/core";
 import type { TuiPluginApi, TuiThemeCurrent } from "@opencode-ai/plugin/tui";
 
 import type { Page } from "../panel/command.ts";
-import { reduce, type Effect, type Key } from "../panel/keys.ts";
+import { reduce, withMessage, type Effect, type Key } from "../panel/keys.ts";
 import type { Line, Tone } from "../panel/lines.ts";
 import type { PanelModel } from "../panel/model.ts";
 import { initialPanelState, renderPanel, type PanelSize, type PanelState } from "../panel/view.ts";
@@ -165,7 +165,8 @@ export function createPanel(api: PanelApi, options: PanelOptions): PanelControll
 		await controller.reload();
 		const row = model?.settings.rows.find((candidate) => candidate.key === setting);
 		const shown = `${row?.label ?? setting}: ${row?.value ?? value}`;
-		state = { ...state, message: error ? { text: error, warning: true } : { text: shown, warning: false } };
+		const message = error ? { text: error, warning: true } : { text: shown, warning: false };
+		state = model ? withMessage(state, message, model, size()) : { ...state, message };
 		render();
 	};
 

package/src/tui/plugin.ts

@@ -139,8 +139,9 @@ export const tui: TuiPlugin = async (api, tuiOptions) => {
 		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));
@@ -456,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/types.ts

@@ -4,6 +4,8 @@ export type LiveContextMessage = {
 	role: string;
 	content?: unknown;
 	timestamp?: number;
+	/** OpenCode's `info.time.updated`: the in-place write marker used for tail re-anchoring. */
+	updatedAt?: number;
 	[key: string]: unknown;
 };