opencode-clm 0.1.0

package/index.ts

@@ -0,0 +1,332 @@
+/**
+ * opencode-clm: Context Language Model mode for OpenCode.
+ *
+ * Before every model request the plugin writes the model-visible conversation to a mirror
+ * file. The model may rewrite that file with its ordinary tools, and what it leaves there
+ * is what it is sent on the following request. OpenCode's stored history is never
+ * rewritten: the edit is applied in `experimental.chat.messages.transform`, which OpenCode
+ * calls before every LLM request.
+ *
+ * Port of pi-clm (https://github.com/lolipopshock/pi-clm, MIT, Copyright 2026 Emanuel
+ * Casco), whose src/index.ts registers the Pi equivalents of these hooks.
+ *
+ * Hook behaviour, checked against the opencode 1.18.34 bundle:
+ * - `experimental.chat.messages.transform` gets `{}` as input; the session id comes from
+ *   `messages[0].info.sessionID`, and OpenCode keeps its own reference to the array, so the
+ *   result is written into it in place. The main loop calls it before
+ *   `experimental.chat.system.transform` for the same request, so system-prompt sizes and
+ *   model limits reach the session one request late.
+ * - `experimental.session.compacting` runs right before the compaction's own
+ *   `messages.transform` over a clone of the history's head slice; its `output.context`
+ *   strings are appended to the compaction prompt.
+ * - A finished compaction is signalled by `experimental.compaction.autocontinue` (auto
+ *   compaction, before the synthetic "continue" turn) and by the `session.compacted` bus
+ *   event (every successful compaction). Either one marks the session for a rebase.
+ * - `experimental.chat.system.transform` also runs for OpenCode's helper agents (title,
+ *   summary, compaction); those get no protocol text.
+ * - `tool.definition` carries no session id; it runs per tool each time OpenCode builds the
+ *   tool set, before the request's `messages.transform`.
+ */
+import { tool, type Hooks, type Plugin, type PluginInput, type PluginOptions } from "@opencode-ai/plugin";
+
+import { ClmSession } from "./src/clm.ts";
+import { buildCompactPrompt, loadCompactPrompt } from "./src/compact.ts";
+import { continuityTools } from "./src/continuity.ts";
+import { replaceInPlace, type OcMessage } from "./src/opencode.ts";
+import { statusText, systemGuidance } from "./src/presentation.ts";
+import { resolveSettings, SKILLS_DIR, type ClmSettings } from "./src/settings.ts";
+import { loadSteeringDocument, steeringPromptSection, type SteeringDocument } from "./src/steering.ts";
+
+export const PLUGIN_ID = "opencode-clm";
+export const STATUS_COMMAND = "clm";
+export const COMPACT_COMMAND = "clm-compact";
+
+/** Opening words of the system prompts of OpenCode 1.18 helper agents (title, summary, compaction). */
+const HELPER_PROMPTS = [
+	"You are a title generator",
+	"Summarize what was done in this conversation",
+	"You are a context summarization agent",
+];
+
+const STATUS_USAGE = "Usage: /clm [status | path | on | off | reset]";
+
+type ToastVariant = "info" | "success" | "warning" | "error";
+
+function describe(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Session ids name a directory (`<mirrorDir>/clm-<id>`). A separator or `..` would reach
+ * outside it, so such ids are refused before anything touches the file system.
+ */
+export function checkSessionID(sessionID: unknown): string {
+	if (typeof sessionID !== "string" || sessionID === "" || /[/\\]/.test(sessionID) || sessionID.includes("..")) {
+		throw new Error(`CLM refuses session id ${JSON.stringify(sessionID)}: it must not contain "/", "\\" or "..".`);
+	}
+	return sessionID;
+}
+
+function isHelperPrompt(system: readonly string[]): boolean {
+	const first = system[0]?.trimStart() ?? "";
+	return HELPER_PROMPTS.some((prompt) => first.startsWith(prompt));
+}
+
+/** The text the model receives in place of the `/clm` template. */
+function relay(text: string): string {
+	return `${text}\n\nShow the CLM text above to the user exactly as written. Do not edit the mirror or run tools.`;
+}
+
+export const server: Plugin = async (input: PluginInput, options?: PluginOptions): Promise<Hooks> => {
+	const settings: ClmSettings = resolveSettings(options ?? {}, process.env, input.directory);
+	if (!settings.enabled) return {};
+	// Read once at load: a missing or empty steering file fails the plugin with its path.
+	const steering: SteeringDocument | undefined = settings.steeringPath ? loadSteeringDocument(settings.steeringPath) : undefined;
+
+	const sessions = new Map<string, Promise<ClmSession>>();
+	/** Estimated tokens per tool schema, from `tool.definition` (no session id there). */
+	const toolSizes = new Map<string, number>();
+
+	const toast = (message: string, variant: ToastVariant = "info") => {
+		// The TUI shows it; `opencode run` and a bare server ignore it.
+		void Promise.resolve()
+			.then(() => input.client?.tui?.showToast?.({ body: { title: "CLM", message, variant } }))
+			.catch(() => undefined);
+	};
+
+	/** Server log (`opencode` log file); best effort, never throws. */
+	const log = (level: "info" | "warn" | "error", message: string) => {
+		void Promise.resolve()
+			.then(() => input.client?.app?.log?.({ body: { service: PLUGIN_ID, level, message } }))
+			.catch(() => undefined);
+	};
+	/** Command names this plugin defined; a user's own `clm` / `clm-compact` stays theirs. */
+	const ownCommands = new Set<string>();
+
+	const session = (sessionID: string): Promise<ClmSession> => {
+		const id = checkSessionID(sessionID);
+		let existing = sessions.get(id);
+		if (!existing) {
+			existing = ClmSession.open(id, settings).then((clm) => {
+				if (clm.loadWarning) toast(`state reset for ${id}: ${clm.loadWarning}`, "warning");
+				return clm;
+			});
+			existing.catch(() => sessions.delete(id));
+			sessions.set(id, existing);
+		}
+		return existing;
+	};
+	/** An already open session, without opening one. */
+	const opened = async (sessionID: string): Promise<ClmSession | undefined> => {
+		try {
+			return await sessions.get(sessionID);
+		} catch {
+			return undefined;
+		}
+	};
+
+	const toolTokens = (): number | undefined => {
+		if (toolSizes.size === 0) return undefined;
+		let total = 0;
+		for (const size of toolSizes.values()) total += size;
+		return total;
+	};
+
+	async function statusCommand(clm: ClmSession, argument: string): Promise<string> {
+		switch (argument) {
+			case "":
+			case "status": {
+				const text = statusText(clm.status(steering));
+				toast(text.split("\n").slice(0, 3).join("\n"));
+				return text;
+			}
+			case "path":
+				return `CLM mirror: ${clm.mirrorPath}`;
+			case "on":
+			case "off": {
+				await clm.setEnabled(argument === "on");
+				toast(`CLM ${argument} for this session`);
+				return argument === "on"
+					? "CLM is on for this session: the mirror is refreshed before the next request."
+					: "CLM is off for this session: requests carry the raw history and the mirror is no longer read.";
+			}
+			case "reset": {
+				await clm.resetProjection("/clm reset");
+				toast("CLM revision dropped");
+				return "CLM dropped the accepted revision: the next request carries the stored history, and the mirror is rewritten from it.";
+			}
+			default:
+				return `${STATUS_USAGE}\nUnknown argument: ${JSON.stringify(argument)}`;
+		}
+	}
+
+	function compactCommand(clm: ClmSession, argument: string): string {
+		return buildCompactPrompt(loadCompactPrompt(settings.compactPromptPath), {
+			mirror: clm.mirrorPath,
+			current: clm.lastReading?.estimated ?? 0,
+			budget: clm.resolvedBudget()?.budget,
+			instructions: argument,
+		});
+	}
+
+	const hooks: Hooks = {
+		async config(config) {
+			if (settings.commands) {
+				const commands = (config.command ??= {});
+				const ours = {
+					[STATUS_COMMAND]: {
+						description: "CLM: status of the editable context; /clm path | on | off | reset",
+						template: "Show the CLM status. $ARGUMENTS",
+					},
+					[COMPACT_COMMAND]: {
+						description: "CLM: ask the model to compact its context by editing the mirror",
+						template: "Compact your context. $ARGUMENTS",
+					},
+				};
+				for (const [name, definition] of Object.entries(ours)) {
+					if (commands[name] === undefined) {
+						commands[name] = definition;
+						ownCommands.add(name);
+					} else if (!ownCommands.has(name)) {
+						log("warn", `the config already defines /${name}; CLM leaves it alone and does not handle it`);
+					}
+				}
+			}
+			if (settings.skill) {
+				// `skills.paths` exists in the 1.18 config schema; the SDK's v1 Config type lacks it.
+				const skills = ((config as { skills?: { paths?: string[] } }).skills ??= {});
+				const paths = (skills.paths ??= []);
+				if (!paths.includes(SKILLS_DIR)) paths.push(SKILLS_DIR);
+			}
+		},
+
+		async "experimental.chat.system.transform"(hookInput, output) {
+			if (!hookInput.sessionID) return;
+			const existing = await opened(hookInput.sessionID);
+			// The compaction request follows the compaction's messages.transform; a flag that
+			// transform did not consume (an empty head) must not leak into the next request.
+			if (existing) existing.compacting = false;
+			if (isHelperPrompt(output.system)) return;
+			let clm: ClmSession;
+			try {
+				clm = existing ?? (await session(hookInput.sessionID));
+			} catch {
+				return;
+			}
+			if (!clm.state.enabled) return;
+			const limit = (hookInput.model as { limit?: { context?: number; output?: number } } | undefined)?.limit;
+			if (limit) clm.limits = { context: limit.context || undefined, output: limit.output || undefined };
+			const sections = [systemGuidance(clm.mirrorPath, clm.resolvedBudget()?.budget)];
+			if (steering) sections.push(steeringPromptSection(steering));
+			output.system.push(sections.join("\n\n"));
+			clm.scope = { ...clm.scope, systemTokens: clm.textTokens(output.system.join("\n")) };
+		},
+
+		async "experimental.chat.messages.transform"(_hookInput, output) {
+			const raw = output.messages as unknown as OcMessage[];
+			const sessionID = raw[0]?.info?.sessionID;
+			if (!sessionID) return;
+			let clm: ClmSession;
+			try {
+				clm = await session(sessionID);
+			} catch (error) {
+				toast(`not active for session ${sessionID}: ${describe(error)}`, "error");
+				return;
+			}
+			const tools = toolTokens();
+			if (tools !== undefined) clm.scope = { ...clm.scope, toolTokens: tools };
+			try {
+				const result = await clm.transform(raw);
+				replaceInPlace(raw, result.messages);
+			} catch (error) {
+				// Fail open: the request goes out with the raw history.
+				await clm.log({ event: "error", message: describe(error), stack: error instanceof Error ? error.stack : undefined });
+				toast(`transform failed: ${describe(error)}`, "error");
+			}
+		},
+
+		async "experimental.session.compacting"(hookInput, output) {
+			const clm = await opened(hookInput.sessionID);
+			if (!clm) return;
+			clm.compacting = true;
+			try {
+				const context = await clm.compactionContext();
+				if (context) output.context.push(context);
+			} catch (error) {
+				await clm.log({ event: "error", message: describe(error) });
+			}
+		},
+
+		async "experimental.compaction.autocontinue"(hookInput) {
+			const clm = await opened(hookInput.sessionID);
+			if (clm) clm.compacted = true;
+		},
+
+		async event({ event }) {
+			if (event.type !== "session.compacted") return;
+			const clm = await opened(event.properties.sessionID);
+			if (clm) clm.compacted = true;
+		},
+
+		async "tool.definition"(hookInput, output) {
+			// Runtime output also carries `jsonSchema` (set for plugin and MCP tools). OpenCode's
+			// built-in tools carry an Effect schema instead, which is not measured here.
+			const schema = (output as { jsonSchema?: unknown }).jsonSchema;
+			let size = output.description?.length ?? 0;
+			if (schema && typeof schema === "object") {
+				try {
+					size += JSON.stringify(schema).length;
+				} catch {
+					// unmeasurable schema: description only
+				}
+			}
+			toolSizes.set(hookInput.toolID, Math.ceil((size / 4) * settings.estimateFactor));
+		},
+
+		async "tool.execute.after"(hookInput, output) {
+			const clm = await opened(hookInput.sessionID);
+			if (!clm || typeof output.output !== "string") return;
+			// Runs inside the tool's own call: a throw here would fail the model's command.
+			let receipt: string | undefined;
+			try {
+				receipt = clm.receipt(hookInput.tool, hookInput.args, input.directory);
+			} catch (error) {
+				await clm.log({ event: "receipt-error", tool: hookInput.tool, message: describe(error) });
+				return;
+			}
+			if (!receipt) return;
+			output.output = output.output ? `${output.output}${output.output.endsWith("\n") ? "\n" : "\n\n"}${receipt}` : receipt;
+		},
+
+		async "command.execute.before"(hookInput, output) {
+			if (!settings.commands || !ownCommands.has(hookInput.command)) return;
+			// A rejected hook fails the command request: report errors as the command's text.
+			let text: string;
+			try {
+				const clm = await session(hookInput.sessionID);
+				const argument = (hookInput.arguments ?? "").trim();
+				text = hookInput.command === STATUS_COMMAND
+					? relay(await statusCommand(clm, argument.toLowerCase()))
+					: compactCommand(clm, argument);
+			} catch (error) {
+				const message = `/${hookInput.command} failed: ${describe(error)}`;
+				toast(message, "error");
+				log("error", message);
+				text = relay(`[CLM] ${message}`);
+			}
+			const parts = output.parts as Array<{ type: string; text?: string }>;
+			const first = parts.find((part) => part.type === "text");
+			if (first) first.text = text;
+			else parts.unshift({ type: "text", text } as never);
+		},
+
+		tool: continuityTools({
+			schema: tool.schema,
+			store: async (sessionID) => (await session(sessionID)).annotations,
+			block: async (sessionID, blockId) => (await session(sessionID)).blockSource(blockId),
+		}),
+	};
+	return hooks;
+};
+
+export default { id: PLUGIN_ID, server };

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "opencode-clm",
+  "version": "0.1.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",
+  "author": "B Guest",
+  "homepage": "https://github.com/bcmyguest/opencode-clm#readme",
+  "bugs": { "url": "https://github.com/bcmyguest/opencode-clm/issues" },
+  "repository": { "type": "git", "url": "git+https://github.com/bcmyguest/opencode-clm.git" },
+  "keywords": ["opencode", "opencode-plugin", "context-management", "context-window", "context-language-models", "clm"],
+  "main": "./index.ts",
+  "exports": { ".": "./index.ts" },
+  "files": ["index.ts", "src/**/*.ts", "skills/**", "steering/**", "LICENSE", "NOTICE", "README.md", "CHANGELOG.md"],
+  "engines": { "bun": ">=1.2", "opencode": ">=1.18" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "check": "tsc --noEmit && bun test",
+    "test:e2e": "OPENCODE_CLM_E2E=1 bun test test/e2e"
+  },
+  "dependencies": { "@opencode-ai/plugin": "^1.18.34" },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "typescript": "5.9.3"
+  }
+}

package/skills/clm-context/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: clm-context
+description: Compact stale conversation history by editing the opencode-clm context mirror. Use when a [CLM BUDGET] note arrives, tool outputs are large, or old exploration should be replaced by a durable summary.
+---
+
+# Editing the CLM context mirror
+
+Adapted from pi-clm's `live-context` skill (MIT, Copyright 2026 Emanuel Casco).
+
+The opencode-clm plugin writes the conversation you see (everything after the first user
+message) to the mirror path named in the `## Editable context` section of the system
+prompt. Whatever the file holds when your step ends replaces those messages on your next
+request.
+
+Edit the mirror only when a meaningful batch compaction will help later work. Do not
+compact after every step.
+
+## Rules
+
+1. Do not print or `cat` the whole mirror. You already see its contents.
+2. Keep line 1 (`[[LIVE_CONTEXT ...]]`), and for each block you keep, its `[[CTX_TURN ...]]`
+   line.
+3. Write the file through the bash tool (python3, `sed -i`). The edit and write tools keep
+   a copy that goes stale when the plugin regenerates the file.
+4. Make one batched write per step. One write may hold any number of independent block
+   replacements and removals; read-only inspection does not count.
+5. Default to a surgical revision: keep message order, leave unrelated blocks alone,
+   shorten stale bodies in place, and remove only blocks that are clearly obsolete.
+   Do not collapse the whole context into one summary unless the user asks for that.
+6. Keep conversational units together. If a user request still matters, keep the
+   assistant answer to it, or replace that answer with a specific summary at the same
+   position.
+7. Read retention requests literally: "keep these messages" means the user and assistant
+   messages unchanged; "keep the findings" allows a faithful summary. Ask when the scope
+   is unclear.
+8. To shrink a tool result, replace its text with a short note and keep its block.
+   Deleting one result of a step that called several tools turns that whole step into
+   plain notes.
+9. Remove large tool output and superseded exploration before shortening useful dialogue.
+   An edit may not grow the context past the size gate; it is refused if it does.
+10. Keep decisions, constraints, open questions, file paths, commands still needed, test
+   results, the evidence behind conclusions, and the next action. Copy exact values
+   forward; never invent them.
+11. Read the verdict the plugin appends to your bash command's output: the edit is valid,
+    or the reason it would be refused. A `[CLM]` note on the next request confirms what
+    was applied. After a refusal, fix the file and write it again.
+
+## Expected edit shape
+
+Prefer a sparse patch over the existing conversation:
+
+```text
+before: user A -> assistant investigation A -> tool output -> user B -> assistant result B
+after:  user A -> concise assistant A       -> user B      -> concise assistant B
+```
+
+Avoid flattening independent episodes into one synthetic message:
+
+```text
+avoid:  user A -> one global summary of everything -> user B
+```
+
+## Edit cost
+
+An accepted edit changes the request prefix: the provider re-processes everything after
+the first changed block on the next request. Hence:
+
+- One large batched compaction costs less than several small edits.
+- Compact stale early blocks while little useful text sits below them.
+- Write detailed replacement summaries. Text below the edit is re-processed either
+  way, so detail costs little and saves repeated investigation.
+
+## List the headers
+
+Print only headers that carry the current document id. A broad `grep '^\[\['` also
+matches header-shaped text quoted inside tool output.
+
+```bash
+python3 - "<mirror path>" <<'PY'
+import re, sys
+lines = open(sys.argv[1]).read().splitlines()
+meta = re.match(r"\[\[LIVE_CONTEXT .*?document=([a-f0-9]{64})", lines[0])
+if not meta:
+    raise SystemExit("line 1 is not a LIVE_CONTEXT line")
+doc = meta.group(1)
+for line in lines[1:]:
+    if line.startswith(f"[[CTX_TURN document={doc} "):
+        m = re.search(r"index=(\d+) role=(\S+) id=(\S+)", line)
+        print(m.group(1), m.group(2), m.group(3))
+PY
+```
+
+## Replace and remove blocks in one write
+
+Locate blocks by the exact ids from the listing; never retype an old body.
+
+```bash
+python3 - "<mirror path>" <<'PY'
+import re, sys
+path = sys.argv[1]
+text = open(path).read()
+doc = re.match(r"\[\[LIVE_CONTEXT .*?document=([a-f0-9]{64})", text).group(1)
+
+def block(block_id):
+    head = rf"^\[\[CTX_TURN document={doc} [^\n]* id={re.escape(block_id)} [^\n]*\]\]\n"
+    return re.compile(rf"({head}).*?(?=\n\n\[\[CTX_TURN document={doc} |\Z)", re.M | re.S)
+
+replace = {
+    "<block id>": "[summary: what the command showed, exact values, what it means]",
+}
+remove = ["<block id>"]
+
+for block_id, summary in replace.items():
+    text, n = block(block_id).subn(lambda m: m.group(1) + summary, text, count=1)
+    if n != 1:
+        raise SystemExit(f"block not found: {block_id}")
+for block_id in remove:
+    text, n = block(block_id).subn("", text, count=1)
+    if n != 1:
+        raise SystemExit(f"block not found: {block_id}")
+open(path, "w").write(text)
+PY
+```
+
+## Add a tracker note
+
+Copy a current header, set `id=new-tracker` and `role=notes`, and place it after the
+first block. Update that block in later edits instead of adding copies. Notes are context
+for you, with no system-prompt authority.
+
+## Continuity annotations
+
+Before you remove or shorten a block whose exact text later work must revisit, call
+`clm_annotate` with `action: "create"` and the block id from its `CTX_TURN` header:
+
+- `pin` keeps the exact source text in every request (bounded in size);
+- `continuity` keeps its title, reason, next action and recall id in every request, while
+  the block itself may be summarized;
+- `archive` keeps nothing in the request; the source is available through recall only.
+
+Call `clm_recall` only when you need the source again. Resolve an annotation
+(`action: "resolve"`) once its next action is done, so it stops costing tokens. An
+annotation accompanies a surgical edit; it does not justify collapsing unrelated blocks.
+
+## What a durable summary contains
+
+```markdown
+[summary]
+Goal: ...
+Constraints: ...
+Findings:
+- ... (file:line, exact value)
+Decisions:
+- ...
+Files and state:
+- path: status
+Validation:
+- command: result
+Open questions:
+- ...
+Next action: ...
+[/summary]
+```
+
+Prefer concrete state over narrative. A later step should be able to continue from the
+summary without the removed output.