opencode-clm 0.1.0

package/src/mirror-guard.ts

@@ -0,0 +1,95 @@
+// Adapted from pi-clm src/mirror-guard.ts (MIT, Copyright 2026 Emanuel Casco).
+
+import { dirname, resolve } from "node:path";
+
+/**
+ * What a tool call does to the mirror file.
+ *
+ * - "write": the call mutates the mirror (edit/write/apply_patch tools, or a bash command
+ *   with an explicit write indicator).
+ * - "read": the read tool targets the mirror, or a bash command references it without a
+ *   recognized write indicator (header discovery, grep, head). Allowed and never counted,
+ *   so inspection cannot consume the write allowance.
+ * - "none": the call does not reference the mirror.
+ *
+ * Bash classification is a heuristic on command text; validation before the next request
+ * remains the correctness boundary regardless of how a mutation was performed.
+ */
+export type MirrorToolIntent = "write" | "read" | "none";
+
+const WRITE_INDICATOR = new RegExp(
+	[
+		String.raw`>>?`,
+		String.raw`\btee\b`,
+		String.raw`\bsed\s+(?:-\S+\s+)*-i\b`,
+		String.raw`\bperl\s+(?:-\S+\s+)*-i\b`,
+		String.raw`\btruncate\b`,
+		String.raw`\brm\b`,
+		String.raw`\bmv\b`,
+		String.raw`\bcp\b`,
+		String.raw`\bdd\b`,
+		String.raw`\binstall\b`,
+		String.raw`\bln\b`,
+		String.raw`\brsync\b`,
+		String.raw`\bex\b`,
+		String.raw`write_text\s*\(`,
+		String.raw`\.write\s*\(`,
+		String.raw`\bwritelines\s*\(`,
+		String.raw`writeFile(?:Sync)?\s*\(`,
+		String.raw`\bopen\s*\([^()]*["'][wax+]`,
+		String.raw`\.open\(\s*["'][wax]`,
+		String.raw`\bmode\s*=\s*["'][wax]`,
+	].join("|"),
+);
+
+/** Redirections that never write the mirror: fd duplication (`2>&1`, `>&2`) and `/dev/null`. */
+const HARMLESS_REDIRECT = /\d*>&\d+|[12&]?>>?\s*\/dev\/null/g;
+
+/** File headers of OpenCode's `apply_patch` format (`*** Update File: <path>` and kin). */
+const PATCH_PATH = /^\s*\*\*\* (?:Add File|Update File|Delete File|Move to):\s*(.+?)\s*$/gm;
+
+function escapeRegExp(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Does the command name the mirror file, its directory, or the mirror's basename? */
+function referencesMirror(command: string, mirrorPath: string): boolean {
+	if (command.includes(mirrorPath) || command.includes("LIVE_CONTEXT.md")) return true;
+	const directory = new RegExp(`${escapeRegExp(dirname(mirrorPath))}(?=$|[/\\s"'\`;|&)])`);
+	return directory.test(command);
+}
+
+function pathArg(input: Record<string, unknown>): string {
+	const given = typeof input.filePath === "string" ? input.filePath : typeof input.path === "string" ? input.path : "";
+	return given.replace(/^@/, "");
+}
+
+function patchPaths(patchText: string): string[] {
+	return [...patchText.matchAll(PATCH_PATH)].map((match) => match[1]!);
+}
+
+export function classifyMirrorToolCall(
+	toolName: string,
+	input: Record<string, unknown>,
+	cwd: string,
+	mirrorPath: string,
+): MirrorToolIntent {
+	const isMirror = (path: string) => path !== "" && resolve(cwd, path) === mirrorPath;
+	switch (toolName) {
+		case "edit":
+		case "write":
+			return isMirror(pathArg(input)) ? "write" : "none";
+		case "apply_patch":
+			return typeof input.patchText === "string" && patchPaths(input.patchText).some(isMirror) ? "write" : "none";
+		case "read":
+			return isMirror(pathArg(input)) ? "read" : "none";
+		case "bash": {
+			if (typeof input.command !== "string") return "none";
+			const command = input.command;
+			if (!referencesMirror(command, mirrorPath)) return "none";
+			return WRITE_INDICATOR.test(command.replace(HARMLESS_REDIRECT, " ")) ? "write" : "read";
+		}
+		default:
+			return "none";
+	}
+}

package/src/mirror-store.ts

@@ -0,0 +1,154 @@
+// Adapted from pi-clm src/mirror-store.ts (MIT, Copyright 2026 Emanuel Casco).
+
+import { readFileSync } from "node:fs";
+import { chmod, lstat, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+const STALE_MIRROR_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** `${XDG_STATE_HOME || ~/.local/state}/opencode-clm/mirrors`, resolved at call time. */
+export function defaultMirrorParent(): string {
+	const stateHome = process.env.XDG_STATE_HOME || join(homedir(), ".local", "state");
+	return join(stateHome, "opencode-clm", "mirrors");
+}
+
+function safeSessionId(sessionId: string): string {
+	const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 64);
+	return safe || "session";
+}
+
+async function exists(path: string): Promise<boolean> {
+	return lstat(path).then(
+		() => true,
+		() => false,
+	);
+}
+
+/** Newest mtime among a directory and the entries directly inside it. */
+async function newestMtime(directory: string): Promise<number> {
+	let newest = (await stat(directory)).mtimeMs;
+	for (const name of await readdir(directory)) {
+		const info = await lstat(join(directory, name)).catch(() => undefined);
+		if (info && info.mtimeMs > newest) newest = info.mtimeMs;
+	}
+	return newest;
+}
+
+/**
+ * Best-effort removal of mirror directories left behind by sessions that never reached
+ * shutdown. Live sessions rewrite their mirror every turn, so a directory whose newest
+ * mtime (the directory or any file directly inside it) is older than the threshold has
+ * no owner. Failures are ignored: another process may remove or own an entry concurrently.
+ */
+async function sweepStaleMirrors(parentDirectory: string, keepDirectory: string, maxAgeMs: number): Promise<void> {
+	let names: string[];
+	try {
+		names = await readdir(parentDirectory);
+	} catch {
+		return;
+	}
+	const cutoff = Date.now() - maxAgeMs;
+	for (const name of names) {
+		if (!name.startsWith("clm-")) continue;
+		const directory = join(parentDirectory, name);
+		if (directory === keepDirectory) continue;
+		try {
+			const info = await lstat(directory);
+			if (!info.isDirectory() || (await newestMtime(directory)) >= cutoff) continue;
+			await rm(directory, { recursive: true, force: true });
+		} catch {
+			// Ignored: sweeping is opportunistic hygiene only.
+		}
+	}
+}
+
+/** Refuse a session directory that is a symlink, not a directory, or owned by another user. */
+async function assertPrivateDirectory(directory: string): Promise<void> {
+	const info = await lstat(directory);
+	if (info.isSymbolicLink() || !info.isDirectory()) {
+		throw new Error(`Refusing mirror directory ${directory}: not a real directory.`);
+	}
+	const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+	if (uid !== undefined && info.uid !== uid) {
+		throw new Error(`Refusing mirror directory ${directory}: owned by uid ${info.uid}, not ${uid}.`);
+	}
+}
+
+export class MirrorStore {
+	readonly directory: string;
+	readonly filePath: string;
+	private disposed = false;
+
+	private constructor(directory: string) {
+		this.directory = directory;
+		this.filePath = join(directory, "LIVE_CONTEXT.md");
+	}
+
+	/**
+	 * One directory per session: `<parent>/clm-<session>/`. The name is deterministic so a
+	 * resumed session finds its saved state; the parent gets a `.gitignore` of `*` if absent.
+	 * The parent is chmod 0700 when the store creates it or when it is the default parent.
+	 */
+	static async create(
+		sessionId: string,
+		parentDirectory?: string,
+		staleAgeMs = STALE_MIRROR_AGE_MS,
+	): Promise<MirrorStore> {
+		const parent = parentDirectory ?? defaultMirrorParent();
+		const ownsParent = parentDirectory === undefined || !(await exists(parent));
+		await mkdir(parent, { recursive: true, mode: 0o700 });
+		if (ownsParent) await chmod(parent, 0o700);
+		await writeFile(join(parent, ".gitignore"), "*\n", { flag: "wx" }).catch(() => undefined);
+		const directory = join(parent, `clm-${safeSessionId(sessionId)}`);
+		await mkdir(directory, { recursive: true, mode: 0o700 });
+		await assertPrivateDirectory(directory);
+		await chmod(directory, 0o700);
+		await sweepStaleMirrors(parent, directory, staleAgeMs).catch(() => undefined);
+		return new MirrorStore(directory);
+	}
+
+	/** Synchronous read for hooks that inspect the file right after a tool ran. */
+	readSync(): string | undefined {
+		if (this.disposed) return undefined;
+		try {
+			return readFileSync(this.filePath, "utf8");
+		} catch {
+			return undefined;
+		}
+	}
+
+	async write(content: string): Promise<void> {
+		if (this.disposed) throw new Error("Mirror store has been disposed.");
+		const temporaryPath = join(this.directory, `.${basename(this.filePath)}.${randomUUID()}.tmp`);
+		try {
+			await writeFile(temporaryPath, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+			await rename(temporaryPath, this.filePath);
+			await chmod(this.filePath, 0o600);
+		} catch (error) {
+			await rm(temporaryPath, { force: true }).catch(() => undefined);
+			throw error;
+		}
+	}
+
+	async read(): Promise<string | undefined> {
+		if (this.disposed) return undefined;
+		try {
+			return await readFile(this.filePath, "utf8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+			throw error;
+		}
+	}
+
+	/**
+	 * Deletes the session directory, including the saved state a resumed session would
+	 * read. Call only when the session itself is deleted, never on plain shutdown.
+	 */
+	async cleanup(): Promise<void> {
+		if (this.disposed) return;
+		this.disposed = true;
+		await rm(this.directory, { recursive: true, force: true });
+	}
+}

package/src/observation.ts

@@ -0,0 +1,155 @@
+/**
+ * Observation cap: bound the size of each tool result in the *effective* context.
+ *
+ * Adapted from pi-clm src/observation.ts (MIT, Copyright 2026 Emanuel Casco).
+ *
+ * One assistant turn can fan out into many parallel tool calls whose results land in the
+ * context together, before any request-boundary reminder can be acted on. Capping each
+ * result in the effective context (not in OpenCode's stored parts) keeps such a turn from
+ * jumping straight past the budget. The full output stays in the session; the marker tells
+ * the model how much was cut and that it can re-read with offset/limit when it needs more.
+ *
+ * Input is the flattened form (opencode.ts `flatten`): one `toolResult` message per tool
+ * part, `content: [{ type: "text", text }]`. Capped messages carry `capped: true` so the
+ * unflatten step writes the capped text back into the tool part.
+ *
+ * Capped messages are cached per source object so repeated transform calls produce the
+ * same object, which keeps identity-based comparisons and rendering stable.
+ */
+
+import type { LiveContextMessage } from "./types.ts";
+
+export interface ObservationCapPolicy {
+	/** Maximum characters of text kept per tool result. `undefined` disables the cap. */
+	maxCharacters?: number;
+	/** Fraction of the kept text taken from the start; the rest comes from the end. */
+	headFraction: number;
+}
+
+export const DEFAULT_OBSERVATION_CAP: ObservationCapPolicy = { headFraction: 0.8 };
+
+/** Smallest cap accepted: below this the marker alone would crowd out the output. */
+export const MIN_OBSERVATION_CAP = 200;
+
+/**
+ * Parse a `CLM_OBSERVATION_CAP` value: `10000` or `10000:0.5` (characters[:head fraction]);
+ * the CLM paper used 5k head + 5k tail, i.e. `10000:0.5`. Empty, `off` and `0` disable the
+ * cap (returns `{}`). `name` labels errors.
+ */
+export function parseObservationCap(raw: string | undefined, name = "CLM_OBSERVATION_CAP"): Partial<ObservationCapPolicy> {
+	const value = raw?.trim();
+	if (!value || value === "off" || value === "0") return {};
+	const [charsPart, headPart, ...rest] = value.split(":");
+	const chars = Number(charsPart);
+	if (rest.length > 0 || !Number.isFinite(chars) || chars <= 0) {
+		throw new Error(`${name} must be a positive number of characters[:head fraction] or "off", got ${value}`);
+	}
+	const overrides: Partial<ObservationCapPolicy> = { maxCharacters: Math.floor(chars) };
+	if (headPart !== undefined && headPart !== "") {
+		const head = Number(headPart);
+		if (!(head > 0 && head <= 1)) throw new Error(`${name} head fraction must be in (0, 1], got ${headPart}`);
+		overrides.headFraction = head;
+	}
+	return overrides;
+}
+
+export function resolveObservationCap(overrides: Partial<ObservationCapPolicy> | undefined): ObservationCapPolicy {
+	const merged = { ...DEFAULT_OBSERVATION_CAP, ...(overrides ?? {}) };
+	if (merged.maxCharacters !== undefined && (!Number.isFinite(merged.maxCharacters) || merged.maxCharacters < MIN_OBSERVATION_CAP)) {
+		throw new Error(`observation cap must be at least ${MIN_OBSERVATION_CAP} characters, got ${String(merged.maxCharacters)}`);
+	}
+	if (!(merged.headFraction > 0 && merged.headFraction <= 1)) {
+		throw new Error(`headFraction must be in (0, 1], got ${String(merged.headFraction)}`);
+	}
+	return merged;
+}
+
+interface TextPart {
+	type: "text";
+	text: string;
+}
+
+function isTextPart(part: unknown): part is TextPart {
+	return Boolean(part) && typeof part === "object" && (part as TextPart).type === "text" && typeof (part as TextPart).text === "string";
+}
+
+function isHighSurrogate(code: number): boolean {
+	return code >= 0xd800 && code <= 0xdbff;
+}
+
+function isLowSurrogate(code: number): boolean {
+	return code >= 0xdc00 && code <= 0xdfff;
+}
+
+export function truncationMarker(shown: number, total: number): string {
+	return (
+		`\n\n[clm observation cap: ${shown.toLocaleString("en-US")} of ${total.toLocaleString("en-US")} characters shown. ` +
+		"The complete output remains in the session history; re-read the source with offset/limit if you need the rest.]"
+	);
+}
+
+/** Capped message -> the uncapped source it was cut from. */
+const uncapped = new WeakMap<LiveContextMessage, LiveContextMessage>();
+
+/** The uncapped source of a capped tool result, or the message itself. */
+export function uncappedSource(message: LiveContextMessage): LiveContextMessage {
+	return uncapped.get(message) ?? message;
+}
+
+/** Cap one tool result. Returns the same object when nothing changes. */
+export function capToolResult(message: LiveContextMessage, policy: ObservationCapPolicy): LiveContextMessage {
+	if (policy.maxCharacters === undefined || message.role !== "toolResult") return message;
+	// Idempotent: never cap an already-capped result (also after a JSON round trip).
+	if (message.capped === true || uncapped.has(message)) return message;
+	const content = message.content;
+	const parts: unknown[] = Array.isArray(content) ? content : typeof content === "string" ? [{ type: "text", text: content }] : [];
+	const text = parts.filter(isTextPart).map((part) => part.text).join("");
+	const total = text.length;
+	if (total <= policy.maxCharacters) return message;
+
+	const headBudget = Math.floor(policy.maxCharacters * policy.headFraction);
+	const tailBudget = policy.maxCharacters - headBudget;
+	// Cut once across the concatenated text, then rebuild a single text part followed by
+	// any non-text parts (for example images), in their original order.
+	// Never split a UTF-16 surrogate pair at either cut.
+	let headEnd = headBudget;
+	if (headEnd > 0 && isHighSurrogate(text.charCodeAt(headEnd - 1))) headEnd -= 1;
+	let tailStart = total - tailBudget;
+	if (tailBudget > 0 && tailStart < total && isLowSurrogate(text.charCodeAt(tailStart))) tailStart += 1;
+	const head = text.slice(0, headEnd);
+	const tail = tailBudget > 0 ? text.slice(tailStart) : "";
+	const shown = head.length + tail.length;
+	const cut = tailBudget > 0 ? `${head}\n…[${(total - shown).toLocaleString("en-US")} characters omitted]…\n${tail}` : head;
+	const capped: LiveContextMessage = {
+		...message,
+		content: [{ type: "text", text: `${cut}${truncationMarker(shown, total)}` }, ...parts.filter((part) => !isTextPart(part))],
+		capped: true,
+	};
+	uncapped.set(capped, message);
+	return capped;
+}
+
+const cappedCache = new WeakMap<LiveContextMessage, Map<string, LiveContextMessage>>();
+
+/** Cap every tool result in `messages`; returns the same array when nothing changes. */
+export function capObservations(messages: LiveContextMessage[], policy: ObservationCapPolicy): LiveContextMessage[] {
+	if (policy.maxCharacters === undefined) return messages;
+	const key = `${policy.maxCharacters}:${policy.headFraction}`;
+	let changed = false;
+	const output = messages.map((message) => {
+		if (message.role !== "toolResult") return message;
+		let perPolicy = cappedCache.get(message);
+		if (!perPolicy) {
+			perPolicy = new Map();
+			cappedCache.set(message, perPolicy);
+		}
+		let capped = perPolicy.get(key);
+		if (!capped) {
+			capped = capToolResult(message, policy);
+			perPolicy.set(key, capped);
+		}
+		if (capped !== message) changed = true;
+		return capped;
+	});
+	return changed ? output : messages;
+}