opencode-clm 0.1.0

package/src/presentation.ts

@@ -0,0 +1,127 @@
+/**
+ * Model-facing protocol text and user-facing status.
+ *
+ * The protocol section is written for this package from the behaviour of
+ * src/context-document.ts (file layout, what each kind of change does, what is refused).
+ * Its scope follows pi-clm src/presentation.ts (MIT, Copyright 2026 Emanuel Casco): it
+ * states the editing protocol only; context-management strategy belongs in a steering
+ * document.
+ */
+
+import { budgetSummaryLine, formatTokens, type BudgetReading } from "./budget.ts";
+import type { EditGate } from "./policy.ts";
+import { steeringStatusLine, type SteeringDocument } from "./steering.ts";
+
+/** System-prompt section that teaches the mirror protocol. */
+export function systemGuidance(path: string, budget: number | undefined): string {
+	const limit = budget
+		? `\nThe configured limit is ${formatTokens(budget)} tokens; [CLM BUDGET] notes carry the running estimate.`
+		: "";
+	return `## Editable context
+
+\`${path}\` holds this conversation as text: every message after the first user message.
+The plugin regenerates it before each model request. The system prompt and the first user
+message are not in it. When your step ends, the file's content takes the place of those
+messages on your next request; OpenCode's saved session keeps the originals.${limit}
+
+Layout: line 1 is \`[[LIVE_CONTEXT ...]]\` and names the revision and the document id.
+Each message follows as a block: a header line
+\`[[CTX_TURN document=<id> index=<n> role=<role> id=<block id> protected=<true|false>]]\`,
+then the message text. \`grep -n '^\\[\\[CTX_TURN' ${path}\` prints every header with its
+line number.
+
+Effect of each change:
+- Header and text deleted, or text emptied: the message is dropped.
+- New text under a tool result header: it replaces that output; the tool call stays.
+- New text under an assistant header: the reply becomes that text with no tool calls, and
+  the tool results it called become plain notes.
+- Blocks marked \`protected=true\` come back unchanged if you alter them; a deleted one
+  returns at the end of the file.
+- A block whose header you copied with \`id=new-NAME\` (NAME: letters, digits, hyphens;
+  unique) and a role label such as \`notes\` is inserted as a note where it stands. Notes are
+  context, with no system-prompt authority.
+- Text above the first header is kept as a note at the top.
+- A file with no headers at all, only text: everything becomes one notes block.
+
+Refused outright (the context stays as it was):
+- a line 1 that no longer parses or names a different document;
+- a duplicated block id, an id absent from the current headers that lacks the \`new-\`
+  prefix, or a malformed header carrying the current document id;
+- growth beyond what the size gate allows.
+
+Tools: change the file through the bash tool (python3, sed -i). The edit or write tools
+keep a copy that goes stale when the file is regenerated, so leave them off this file.
+
+Receipts: a bash command that writes the file returns a verdict (accepted, or the reason
+it is not); a [CLM] note on the next request reports what was applied. After a refusal,
+correct the file and write it again.
+
+Example: put a short note in place of block 4's text. Headers quoted inside message text
+can look like real ones, so the script matches on the document id from line 1:
+
+\`\`\`bash
+python3 - <<'PY'
+import re
+path = "${path}"
+text = open(path).read()
+doc = re.match(r"\\[\\[LIVE_CONTEXT [^\\n]*?document=([0-9a-f]+)", text).group(1)
+header = re.compile(r"^\\[\\[CTX_TURN document=" + doc + r" index=(\\d+) [^\\n]*$", re.M)
+heads = list(header.finditer(text))
+pos = next(i for i, h in enumerate(heads) if h.group(1) == "4")
+stop = heads[pos + 1].start() if pos + 1 < len(heads) else len(text)
+text = text[:heads[pos].end()] + "\\n[note: what block 4 established]\\n\\n" + text[stop:]
+open(path, "w").write(text)
+PY
+\`\`\``;
+}
+
+/** Inputs for the `/clm` status text; block 8 fills these from the session. */
+export interface ClmStatus {
+	sessionID: string;
+	mirrorPath: string;
+	revision: number;
+	accepted: number;
+	rejected: number;
+	gate: EditGate;
+	guard: "withhold" | "off";
+	/** Latest budget reading; undefined before the first request. */
+	reading?: BudgetReading;
+	/** Model context window in tokens, when known. */
+	modelWindow?: number;
+	/** The accepted revision now in effect, if any. */
+	checkpoint?: { revision: number; anchorCount: number; beforeEstimate: number; afterEstimate: number };
+	lastRequest?: { rawMessages: number; sentMessages: number; mirrorBlocks: number };
+	steering?: SteeringDocument;
+}
+
+/** One line for a toast. */
+export function statusLine(status: ClmStatus): string {
+	const size = status.reading
+		? ` · ${formatTokens(status.reading.estimated)} of ${formatTokens(status.reading.budget)} tok`
+		: "";
+	return `CLM r${status.revision} · ${status.accepted} accepted / ${status.rejected} rejected${size}`;
+}
+
+/** Multi-line status for `/clm`. */
+export function statusText(status: ClmStatus): string {
+	const lines = [
+		`CLM status for session ${status.sessionID}`,
+		`mirror: ${status.mirrorPath}`,
+		`revision ${status.revision} · edits accepted ${status.accepted} · rejected ${status.rejected} · gate ${status.gate} · guard ${status.guard}`,
+		status.reading
+			? `${budgetSummaryLine(status.reading)} · model window ${status.modelWindow ? formatTokens(status.modelWindow) : "unknown"}`
+			: "budget: unknown until the first request",
+	];
+	const checkpoint = status.checkpoint;
+	lines.push(
+		checkpoint
+			? `active revision ${checkpoint.revision}: covers ${checkpoint.anchorCount} raw messages; ~${formatTokens(checkpoint.beforeEstimate)}→${formatTokens(checkpoint.afterEstimate)} tokens when accepted`
+			: "no accepted edit: the model sees the raw history",
+	);
+	if (status.lastRequest) {
+		const request = status.lastRequest;
+		lines.push(`last request: ${request.rawMessages} raw messages → ${request.sentMessages} sent, ${request.mirrorBlocks} mirror blocks`);
+	}
+	lines.push(steeringStatusLine(status.steering));
+	return lines.join("\n");
+}

package/src/projection.ts

@@ -0,0 +1,146 @@
+// Adapted from pi-clm src/projection.ts (MIT, Copyright 2026 Emanuel Casco).
+//
+// A checkpoint records one accepted mirror edit: the flattened raw prefix it replaces
+// (count + SHA-256 digest) and the projected messages that stand in for that prefix.
+// Messages are the flat form `opencode.ts` produces from OpenCode's `{ info, parts }`
+// history. `digestSourcePrefix` hashes a key-sorted JSON serialization, so a checkpoint saved
+// by one process validates against the same history flattened by another.
+//
+// The anchor is prune-invariant. OpenCode's `compaction.prune` (opt-in) clears old tool
+// outputs in place (`state.time.compacted`), exactly in the old prefix a checkpoint covers.
+// The source digest therefore hashes each `toolResult` without its content, and the
+// checkpoint also stores the `ocMessageID` of every flat source message. Revert removes
+// whole messages (ids change) or truncates the parts of a kept message (its toolCall and
+// toolResult disappear, so the digest changes); both still fail closed.
+//
+// pi-clm's `recoverProjectionFromRetryErrors` is not ported. Pi writes failed assistant
+// responses to its session log but drops them from live state, so a resumed log hashes
+// differently. OpenCode keeps the error on the assistant message (`info.error`), and the
+// flattener drops failed assistant messages before digesting, both when the checkpoint is
+// created and when it is applied. The mismatch that recovery repairs cannot occur.
+import { digestMessages } from "./context-document.ts";
+import type { ContextEditTrace, LiveContextMessage } from "./types.ts";
+
+export const PROJECTION_PREFIX_MISMATCH_REASON =
+	"Raw context prefix no longer matches the projection checkpoint.";
+export const PROJECTION_SOURCE_IDS_REASON =
+	"Raw context prefix message ids no longer match the projection checkpoint (revert or compaction).";
+export const PROJECTION_SHORTER_REASON = "Raw context is shorter than the projection source prefix.";
+
+export type EstimateUnit = "characters" | "tokens";
+
+export interface ProjectionCheckpoint {
+	version: 1;
+	revision: number;
+	/** Number of flattened raw messages the projection replaces. */
+	sourceMessageCount: number;
+	/** `ocMessageID` of each of those messages ("" when absent); length is sourceMessageCount. */
+	sourceIds: string[];
+	/** `digestSourcePrefix` of those messages. */
+	sourceDigest: string;
+	projectedMessages: LiveContextMessage[];
+	beforeEstimate: number;
+	afterEstimate: number;
+	estimateUnit: EstimateUnit;
+	createdAt: string;
+	/** Provenance for the accepted edit that produced projectedMessages. */
+	editTrace?: ContextEditTrace;
+}
+
+export type ProjectionApplication =
+	| {
+			valid: true;
+			messages: LiveContextMessage[];
+			suffix: LiveContextMessage[];
+	  }
+	| {
+			valid: false;
+			messages: LiveContextMessage[];
+			reason: string;
+	  };
+
+/** The OpenCode message id a flat message came from, or "" when it has none. */
+export function sourceMessageId(message: LiveContextMessage): string {
+	return typeof message.ocMessageID === "string" ? message.ocMessageID : "";
+}
+
+/**
+ * Digest a raw source prefix in a form OpenCode's prune cannot change: every `toolResult`
+ * keeps only role, toolCallId, toolName, isError and ocMessageID. Content is dropped for
+ * every tool result, not only cleared ones: the output is intact when the checkpoint is
+ * created and may be cleared when it is validated.
+ */
+export function digestSourcePrefix(messages: readonly LiveContextMessage[]): string {
+	return digestMessages(
+		messages.map((message) => {
+			if (message.role !== "toolResult") return message;
+			return {
+				role: message.role,
+				toolCallId: message.toolCallId,
+				toolName: message.toolName,
+				isError: message.isError,
+				ocMessageID: message.ocMessageID,
+			};
+		}),
+	);
+}
+
+export function createProjectionCheckpoint(options: {
+	revision: number;
+	sourceMessages: readonly LiveContextMessage[];
+	projectedMessages: readonly LiveContextMessage[];
+	beforeEstimate: number;
+	afterEstimate: number;
+	estimateUnit: EstimateUnit;
+	createdAt?: string;
+	editTrace?: ContextEditTrace;
+}): ProjectionCheckpoint {
+	const checkpoint: ProjectionCheckpoint = {
+		version: 1,
+		revision: options.revision,
+		sourceMessageCount: options.sourceMessages.length,
+		sourceIds: options.sourceMessages.map(sourceMessageId),
+		sourceDigest: digestSourcePrefix(options.sourceMessages),
+		projectedMessages: [...options.projectedMessages],
+		beforeEstimate: options.beforeEstimate,
+		afterEstimate: options.afterEstimate,
+		estimateUnit: options.estimateUnit,
+		createdAt: options.createdAt ?? new Date().toISOString(),
+	};
+	if (options.editTrace) checkpoint.editTrace = options.editTrace;
+
+	// Fail at creation rather than when state.json is written.
+	JSON.stringify(checkpoint);
+	return checkpoint;
+}
+
+/**
+ * Replace the checkpoint's raw source prefix and keep every raw message appended after
+ * it. A mismatch fails closed and returns a copy of the untouched raw context.
+ */
+export function applyProjection(
+	rawMessages: readonly LiveContextMessage[],
+	checkpoint: ProjectionCheckpoint | undefined,
+): ProjectionApplication {
+	if (!checkpoint) return { valid: true, messages: [...rawMessages], suffix: [] };
+	if (checkpoint.version !== 1) {
+		return { valid: false, messages: [...rawMessages], reason: `Unsupported projection version: ${checkpoint.version}.` };
+	}
+	if (rawMessages.length < checkpoint.sourceMessageCount) {
+		return { valid: false, messages: [...rawMessages], reason: PROJECTION_SHORTER_REASON };
+	}
+	const prefix = rawMessages.slice(0, checkpoint.sourceMessageCount);
+	const ids = checkpoint.sourceIds;
+	if (
+		!Array.isArray(ids) ||
+		ids.length !== prefix.length ||
+		prefix.some((message, index) => sourceMessageId(message) !== ids[index])
+	) {
+		return { valid: false, messages: [...rawMessages], reason: PROJECTION_SOURCE_IDS_REASON };
+	}
+	if (digestSourcePrefix(prefix) !== checkpoint.sourceDigest) {
+		return { valid: false, messages: [...rawMessages], reason: PROJECTION_PREFIX_MISMATCH_REASON };
+	}
+	const suffix = rawMessages.slice(checkpoint.sourceMessageCount);
+	return { valid: true, messages: [...checkpoint.projectedMessages, ...suffix], suffix };
+}

package/src/settings.ts

@@ -0,0 +1,189 @@
+/**
+ * Settings: plugin options (the `plugin` entry in opencode.json) override environment
+ * variables, which override the defaults. Parsed once when the plugin loads; an invalid
+ * value throws an error naming the setting, so OpenCode reports the plugin as failed
+ * instead of running with a guess.
+ *
+ * Setting set adapted from pi-clm src/settings.ts (MIT, Copyright 2026 Emanuel Casco).
+ * pi-clm's per-session overrides (`/clm config` panel) are not ported: OpenCode commands
+ * cannot open a panel.
+ */
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { DEFAULT_BUDGET_POLICY, resolveBudgetPolicy, type BudgetPolicyConfig } from "./budget.ts";
+import { parseObservationCap, resolveObservationCap, type ObservationCapPolicy } from "./observation.ts";
+import { toEditGate, type EditGate } from "./policy.ts";
+
+export interface ClmSettings {
+	enabled: boolean;
+	budget: BudgetPolicyConfig;
+	gate: EditGate;
+	guard: "withhold" | "off";
+	/** Per-result cap on tool output in the effective context; `maxCharacters` undefined = off. */
+	observationCap: ObservationCapPolicy;
+	/** Parent directory of the per-session mirror directories. */
+	mirrorDir: string;
+	/** Steering document path; undefined means protocol only. */
+	steeringPath?: string;
+	/** `/clm-compact` template path; undefined means the built-in prompt. */
+	compactPromptPath?: string;
+	/** Multiplier on the chars/4 token estimate (dense content: 1.5–2). */
+	estimateFactor: number;
+	/** Render assistant reasoning in the mirror. */
+	reasoning: boolean;
+	/** Register the clm-context skill directory with OpenCode. */
+	skill: boolean;
+	/** Register the /clm and /clm-compact commands. */
+	commands: boolean;
+	/** Write every transformed request to `<session dir>/requests/nN.json` (debugging). */
+	dumpRequests: boolean;
+}
+
+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");
+
+type Env = Record<string, string | undefined>;
+
+const OFF_WORDS = ["none", "off"];
+
+function pick(options: Record<string, unknown>, key: string, env: Env, envKey: string): unknown {
+	if (options[key] !== undefined) return options[key];
+	const raw = env[envKey]?.trim();
+	return raw === undefined || raw === "" ? undefined : raw;
+}
+
+/** `32000`, `32k`, `1.5m`, `32_000`, `32,000`. */
+export function parseTokens(value: unknown, name: string): number {
+	const text = String(value).trim().toLowerCase().replace(/[_,]/g, "");
+	const match = /^(\d+(?:\.\d+)?)(k|m)?$/.exec(text);
+	if (!match) throw new Error(`${name} must be a number of tokens (e.g. 32000, 32k), got ${JSON.stringify(value)}`);
+	const scale = match[2] === "k" ? 1_000 : match[2] === "m" ? 1_000_000 : 1;
+	return Math.round(Number(match[1]) * scale);
+}
+
+function parseFlag(value: unknown, name: string): boolean {
+	if (typeof value === "boolean") return value;
+	const key = String(value).trim().toLowerCase();
+	if (["1", "true", "on", "yes"].includes(key)) return true;
+	if (["0", "false", "off", "no"].includes(key)) return false;
+	throw new Error(`${name} must be true or false, got ${JSON.stringify(value)}`);
+}
+
+function parseFractions(value: unknown, name: string): number[] | "off" {
+	if (value === false) return "off";
+	const parts: unknown[] = Array.isArray(value)
+		? value
+		: String(value).trim().toLowerCase() === "off" || String(value).trim().toLowerCase() === "none"
+			? []
+			: String(value).split(/[\s,/]+/).filter(Boolean);
+	if (parts.length === 0) return "off";
+	const fractions = parts.map((part) => {
+		const number = Number(String(part).trim().replace(/%$/, ""));
+		return number > 1 ? number / 100 : number;
+	});
+	if (fractions.some((fraction) => !Number.isFinite(fraction))) {
+		throw new Error(`${name} must be fractions like 0.25,0.5,0.75 (or 25/50/75%), or off; got ${JSON.stringify(value)}`);
+	}
+	return [...new Set(fractions)];
+}
+
+function withName<T>(name: string, parse: () => T): T {
+	try {
+		return parse();
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(message.startsWith(name) ? message : `${name}: ${message}`);
+	}
+}
+
+/** A path setting: off words mean unset; relative paths resolve against the project. */
+function parsePath(value: unknown, directory: string, offWords: string[]): string | undefined {
+	const text = String(value).trim();
+	if (!text || offWords.includes(text.toLowerCase())) return undefined;
+	return resolve(directory, text);
+}
+
+export function resolveSettings(options: Record<string, unknown> = {}, env: Env = process.env, directory = process.cwd()): ClmSettings {
+	const enabledRaw = pick(options, "enabled", env, "CLM_ENABLED");
+	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 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");
+	const dirRaw = pick(options, "mirrorDir", env, "CLM_MIRROR_DIR");
+	const steeringRaw = pick(options, "steering", env, "CLM_STEERING");
+	const compactRaw = pick(options, "compactPrompt", env, "CLM_COMPACT_PROMPT");
+	const factorRaw = pick(options, "estimateFactor", env, "CLM_ESTIMATE_FACTOR");
+	const reasoningRaw = pick(options, "reasoning", env, "CLM_REASONING");
+	const dumpRaw = pick(options, "dumpRequests", env, "CLM_DUMP_REQUESTS");
+
+	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)}`);
+	}
+	if (reserveRaw !== undefined) overrides.reserve = parseTokens(reserveRaw, "reserve");
+	if (remindRaw !== undefined) {
+		const fractions = parseFractions(remindRaw, "remindAt");
+		if (fractions === "off") {
+			overrides.remindAtFractions = [];
+			overrides.remindAtReserve = false;
+		} else {
+			const outside = fractions.find((fraction) => fraction <= 0 || fraction >= 1);
+			if (outside !== undefined) {
+				throw new Error(`remindAt entries must lie strictly between 0 and 1 (or 0% and 100%), got ${JSON.stringify(remindRaw)}`);
+			}
+			overrides.remindAtFractions = fractions;
+		}
+	}
+	const budget = withName("budget", () => resolveBudgetPolicy({ ...DEFAULT_BUDGET_POLICY, ...overrides }));
+
+	let guard: ClmSettings["guard"] = "withhold";
+	if (guardRaw !== undefined) {
+		const text = String(guardRaw).trim().toLowerCase();
+		if (text === "withhold" || text === "on" || text === "true") guard = "withhold";
+		else if (text === "off" || text === "false") guard = "off";
+		else throw new Error(`guard must be withhold or off, got ${JSON.stringify(guardRaw)}`);
+	}
+
+	const observationCap = withName("observationCap", () =>
+		resolveObservationCap(capRaw === undefined || capRaw === false ? {} : parseObservationCap(String(capRaw), "observationCap")),
+	);
+
+	let steeringPath: string | undefined;
+	if (steeringRaw !== undefined) {
+		const text = String(steeringRaw).trim().toLowerCase();
+		steeringPath = ["house", "house-brief", "house-brief.md"].includes(text)
+			? HOUSE_STEERING
+			: parsePath(steeringRaw, directory, OFF_WORDS);
+	}
+
+	const compactPromptPath = compactRaw === undefined ? undefined : parsePath(compactRaw, directory, ["default", ...OFF_WORDS]);
+
+	// Only a number or a numeric string: Number(true) and Number([2]) would pass silently.
+	const factorValid = factorRaw === undefined || typeof factorRaw === "number" ||
+		(typeof factorRaw === "string" && factorRaw.trim() !== "");
+	const estimateFactor = factorRaw === undefined ? 1 : factorValid ? Number(factorRaw) : Number.NaN;
+	if (!Number.isFinite(estimateFactor) || estimateFactor < 1 || estimateFactor > 4) {
+		throw new Error(`estimateFactor must be between 1 and 4, got ${JSON.stringify(factorRaw)}`);
+	}
+
+	return {
+		enabled: enabledRaw === undefined ? true : parseFlag(enabledRaw, "enabled"),
+		budget,
+		gate: gateRaw === undefined ? "fit" : withName("gate (CLM_EDIT_GATE)", () => toEditGate(gateRaw)),
+		guard,
+		observationCap,
+		mirrorDir: dirRaw === undefined ? join(directory, ".opencode", "clm") : resolve(directory, String(dirRaw)),
+		steeringPath,
+		compactPromptPath,
+		estimateFactor,
+		reasoning: reasoningRaw === undefined ? true : parseFlag(reasoningRaw, "reasoning"),
+		skill: options.skill === undefined ? true : parseFlag(options.skill, "skill"),
+		commands: options.commands === undefined ? true : parseFlag(options.commands, "commands"),
+		dumpRequests: dumpRaw === undefined ? false : parseFlag(dumpRaw, "dumpRequests"),
+	};
+}