opencode-clm 0.1.0

package/src/state.ts

@@ -0,0 +1,241 @@
+// Adapted from pi-clm src/state.ts (MIT, Copyright 2026 Emanuel Casco).
+//
+// Pi appends the state as custom session entries and reconstructs the latest one per
+// branch. OpenCode gives plugins no session store and has no branches, so the whole state
+// lives in one `state.json` in the session directory, replaced atomically on each save.
+import { randomUUID } from "node:crypto";
+import { open, readFile, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import type { ProjectionCheckpoint } from "./projection.ts";
+import type { ContextEditTrace, LiveContextMessage } from "./types.ts";
+
+export const STATE_FILE = "state.json";
+export const STATE_VERSION = 1;
+
+export type OutcomeKind = "applied" | "rejected" | "reset" | "compacted";
+
+export interface LiveContextOutcome {
+	kind: OutcomeKind;
+	message: string;
+	beforeEstimate?: number;
+	afterEstimate?: number;
+	estimateUnit?: "characters" | "tokens";
+	at: string;
+}
+
+export interface LiveContextState {
+	version: 1;
+	enabled: boolean;
+	/** Increases on every accepted edit and every reset. */
+	revision: number;
+	checkpoint?: ProjectionCheckpoint;
+	lastOutcome?: LiveContextOutcome;
+}
+
+export interface LoadedState {
+	state: LiveContextState;
+	/** Set when a state file existed but could not be used; the state is then initial. */
+	warning?: string;
+}
+
+const SOURCE_KINDS = new Set(["kept", "edited", "removed", "restored", "normalized"]);
+const OUTCOME_KINDS = new Set(["applied", "rejected", "reset", "compacted"]);
+
+export function initialLiveContextState(): LiveContextState {
+	return { version: 1, enabled: true, revision: 0 };
+}
+
+export function statePath(directory: string): string {
+	return join(directory, STATE_FILE);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isCount(value: unknown): value is number {
+	return Number.isInteger(value) && (value as number) >= 0;
+}
+
+function isEstimateUnit(value: unknown): boolean {
+	return value === "characters" || value === "tokens";
+}
+
+/** Content the unflattener can turn into OpenCode parts: absent, a string, or typed parts. */
+function isMessageContent(value: unknown): boolean {
+	if (value === undefined || typeof value === "string") return true;
+	return Array.isArray(value) && value.every((part) => isObject(part) && typeof part.type === "string");
+}
+
+function isMessageArray(value: unknown): value is LiveContextMessage[] {
+	return (
+		Array.isArray(value) &&
+		value.every((message) => isObject(message) && typeof message.role === "string" && isMessageContent(message.content))
+	);
+}
+
+function isContextEditTrace(value: unknown): value is ContextEditTrace {
+	if (!isObject(value)) return false;
+	const trace = value as Partial<ContextEditTrace>;
+	if (
+		trace.version !== 1 ||
+		!isCount(trace.sourceRevision) ||
+		!isCount(trace.sourceMessageCount) ||
+		!isCount(trace.outputMessageCount) ||
+		!Array.isArray(trace.sources) ||
+		!Array.isArray(trace.additions)
+	) return false;
+	const sourceCount = trace.sourceMessageCount;
+	const outputCount = trace.outputMessageCount;
+	const isOutputIndex = (index: unknown) => isCount(index) && index < outputCount;
+	return (
+		trace.sources.every((item) =>
+			isObject(item) &&
+			isCount(item.sourceIndex) &&
+			item.sourceIndex < sourceCount &&
+			SOURCE_KINDS.has(item.kind) &&
+			(item.outputIndex === undefined || isOutputIndex(item.outputIndex)),
+		) &&
+		trace.additions.every((item) => isObject(item) && item.kind === "added" && isOutputIndex(item.outputIndex))
+	);
+}
+
+export function isProjectionCheckpoint(value: unknown): value is ProjectionCheckpoint {
+	if (!isObject(value)) return false;
+	const checkpoint = value as Partial<ProjectionCheckpoint>;
+	return (
+		checkpoint.version === 1 &&
+		isCount(checkpoint.revision) &&
+		isCount(checkpoint.sourceMessageCount) &&
+		Array.isArray(checkpoint.sourceIds) &&
+		checkpoint.sourceIds.length === checkpoint.sourceMessageCount &&
+		checkpoint.sourceIds.every((id) => typeof id === "string") &&
+		typeof checkpoint.sourceDigest === "string" &&
+		/^[a-f0-9]{64}$/.test(checkpoint.sourceDigest) &&
+		isMessageArray(checkpoint.projectedMessages) &&
+		Number.isFinite(checkpoint.beforeEstimate) &&
+		Number.isFinite(checkpoint.afterEstimate) &&
+		isEstimateUnit(checkpoint.estimateUnit) &&
+		typeof checkpoint.createdAt === "string" &&
+		(checkpoint.editTrace === undefined ||
+			(isContextEditTrace(checkpoint.editTrace) &&
+				checkpoint.editTrace.sourceMessageCount === checkpoint.sourceMessageCount &&
+				checkpoint.editTrace.outputMessageCount === checkpoint.projectedMessages.length))
+	);
+}
+
+function isOutcome(value: unknown): value is LiveContextOutcome {
+	if (!isObject(value)) return false;
+	return (
+		OUTCOME_KINDS.has(value.kind as string) &&
+		typeof value.message === "string" &&
+		typeof value.at === "string" &&
+		(value.beforeEstimate === undefined || Number.isFinite(value.beforeEstimate)) &&
+		(value.afterEstimate === undefined || Number.isFinite(value.afterEstimate)) &&
+		(value.estimateUnit === undefined || isEstimateUnit(value.estimateUnit))
+	);
+}
+
+export function isLiveContextState(value: unknown): value is LiveContextState {
+	if (!isObject(value)) return false;
+	const state = value as Partial<LiveContextState>;
+	return (
+		state.version === STATE_VERSION &&
+		typeof state.enabled === "boolean" &&
+		isCount(state.revision) &&
+		// Accept writes the checkpoint and the state with the same revision; reset moves past it.
+		(state.checkpoint === undefined ||
+			(isProjectionCheckpoint(state.checkpoint) && state.checkpoint.revision === state.revision)) &&
+		(state.lastOutcome === undefined || isOutcome(state.lastOutcome))
+	);
+}
+
+/** Drop the checkpoint and advance the revision past it, keeping `enabled`. */
+export function resetProjectionState(
+	state: LiveContextState,
+	message: string,
+	at = new Date().toISOString(),
+): LiveContextState {
+	return {
+		version: 1,
+		enabled: state.enabled,
+		revision: state.revision + 1,
+		lastOutcome: { kind: "reset", message, at },
+	};
+}
+
+/**
+ * Read `state.json` from the session directory. A missing file is a new session. An
+ * unreadable, malformed or foreign-version file yields the initial state and a warning;
+ * this function never throws.
+ */
+export async function loadLiveContextState(directory: string): Promise<LoadedState> {
+	const path = statePath(directory);
+	let text: string;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return { state: initialLiveContextState() };
+		return { state: initialLiveContextState(), warning: `Could not read ${path}: ${describe(error)}; starting clean.` };
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		return { state: initialLiveContextState(), warning: `${path} is not valid JSON (${describe(error)}); starting clean.` };
+	}
+	if (isObject(parsed) && parsed.version !== STATE_VERSION) {
+		return {
+			state: initialLiveContextState(),
+			warning: `${path} has unsupported version ${JSON.stringify(parsed.version)}; starting clean.`,
+		};
+	}
+	if (!isLiveContextState(parsed)) {
+		return { state: initialLiveContextState(), warning: `${path} has an invalid shape; starting clean.` };
+	}
+	return { state: parsed };
+}
+
+/**
+ * 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
+ * older state can replace a newer one. Callers must serialize saves per session.
+ */
+export async function saveLiveContextState(directory: string, state: LiveContextState): Promise<void> {
+	const path = statePath(directory);
+	const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+	const text = `${JSON.stringify(state)}\n`;
+	try {
+		const handle = await open(temporary, "wx", 0o600);
+		try {
+			await handle.writeFile(text, "utf8");
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		await rename(temporary, path);
+	} catch (error) {
+		await rm(temporary, { force: true }).catch(() => undefined);
+		throw error;
+	}
+	await syncDirectory(dirname(path));
+}
+
+/** Persist the rename. Some platforms refuse to open or fsync a directory; ignore that. */
+async function syncDirectory(directory: string): Promise<void> {
+	try {
+		const handle = await open(directory, "r");
+		try {
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+	} catch {
+		// Best effort.
+	}
+}
+
+function describe(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/steering.ts

@@ -0,0 +1,54 @@
+// Adapted from pi-clm src/steering.ts (MIT, Copyright 2026 Emanuel Casco).
+/**
+ * Steering document: the one place where context-management *strategy* may enter the
+ * prompt. The harness itself only states the editing protocol; a steering file tells the
+ * model when to compact, what to keep, how to structure notes, and so on. It is
+ * swappable so experiments can compare "no strategy" against a paper-style brief or an
+ * evolved skill, and it is hashed so runs can be attributed to an exact document.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+
+export interface SteeringDocument {
+	path: string;
+	name: string;
+	text: string;
+	/** First 12 hex chars of the SHA-256 of the file bytes (matches `sha256sum`). */
+	hash: string;
+}
+
+export function steeringPathFromEnv(env: Record<string, string | undefined> = process.env): string | undefined {
+	const raw = env.CLM_STEERING?.trim();
+	if (!raw || raw === "none" || raw === "off") return undefined;
+	return raw;
+}
+
+export function loadSteeringDocument(path: string): SteeringDocument {
+	const absolute = resolve(path);
+	let raw: Buffer;
+	try {
+		raw = readFileSync(absolute);
+	} catch (error) {
+		throw new Error(`steering: cannot read ${absolute}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const text = raw.toString("utf8").trim();
+	if (!text) throw new Error(`steering: document is empty: ${absolute}`);
+	return {
+		path: absolute,
+		name: basename(absolute),
+		text,
+		// Hash of the file bytes, so it matches `sha256sum <file>`.
+		hash: createHash("sha256").update(raw).digest("hex").slice(0, 12),
+	};
+}
+
+/** System-prompt section appended after the editing protocol. */
+export function steeringPromptSection(doc: SteeringDocument): string {
+	return `## Context-management guidance (${doc.name})\n\n${doc.text}`;
+}
+
+export function steeringStatusLine(doc: SteeringDocument | undefined): string {
+	return doc ? `steering: ${doc.name} (sha256sum ${doc.hash}…) · ${doc.path}` : "steering: none (protocol only)";
+}

package/src/types.ts

@@ -0,0 +1,102 @@
+// Adapted from pi-clm src/types.ts (MIT, Copyright 2026 Emanuel Casco).
+
+export type LiveContextMessage = {
+	role: string;
+	content?: unknown;
+	timestamp?: number;
+	[key: string]: unknown;
+};
+
+export interface DocumentBlock {
+	index: number;
+	id: string;
+	role: string;
+	protected: boolean;
+	header: string;
+	body: string;
+	source: LiveContextMessage;
+}
+
+export interface ContextDocumentSnapshot {
+	version: 1;
+	revision: number;
+	baselineDigest: string;
+	/** Per-document framing nonce. Derived from the baseline digest, or from a stable seed. */
+	documentId: string;
+	/** True when the nonce is seed-based and bodies were escaped (see renderContextDocument). */
+	stableDocument?: boolean;
+	text: string;
+	messages: LiveContextMessage[];
+	blocks: DocumentBlock[];
+}
+
+/** What the transform rendered for one request; consumed once before the next request. */
+export interface TurnBaseline {
+	rawMessages: LiveContextMessage[];
+	effectiveMessages: LiveContextMessage[];
+	snapshot: ContextDocumentSnapshot;
+}
+
+export interface ApplyDocumentOptions {
+	/** CLM permits reordered blocks and new IDs prefixed with new-. */
+	editingMode?: "conservative" | "clm";
+	/**
+	 * Edit gate for edits that grow the context. "fit": growth is accepted while the result
+	 * stays within `limit`; "shrink": growth is rejected; "none": no size check.
+	 * Edits that do not grow are always accepted. Default: "fit" in CLM mode, else "shrink".
+	 */
+	gate?: "fit" | "shrink" | "none";
+	/**
+	 * Limit the fit gate measures against, in the unit of `estimate` (characters by default).
+	 * Without a positive finite limit the fit gate accepts every edit, like "none".
+	 */
+	limit?: number;
+	/**
+	 * The task statement is pinned outside the mirror, so a headerless rewrite replaces
+	 * every block (instead of keeping the first user turn of the document).
+	 */
+	taskPinned?: boolean;
+	/** Estimator for the shrink gate. Defaults to the rendered-character estimate. */
+	estimate?: (messages: LiveContextMessage[]) => number;
+	/** Unit named in gate diagnostics. Defaults to "characters". */
+	estimateUnit?: "characters" | "tokens";
+}
+
+export type ContextEditSourceKind = "kept" | "edited" | "removed" | "restored" | "normalized";
+
+export interface ContextEditSourceTrace {
+	/** Zero-based index in the exact effective context rendered to the mirror. */
+	sourceIndex: number;
+	/** Zero-based index in the accepted projected context; absent when removed. */
+	outputIndex?: number;
+	kind: ContextEditSourceKind;
+}
+
+export interface ContextEditAdditionTrace {
+	/** Zero-based index in the accepted projected context. */
+	outputIndex: number;
+	kind: "added";
+}
+
+/** Compact provenance for reconstructing one accepted mirror edit without duplicating message bodies. */
+export interface ContextEditTrace {
+	version: 1;
+	sourceRevision: number;
+	sourceMessageCount: number;
+	outputMessageCount: number;
+	sources: ContextEditSourceTrace[];
+	additions: ContextEditAdditionTrace[];
+}
+
+export interface ApplyDocumentResult {
+	accepted: boolean;
+	changed: boolean;
+	messages: LiveContextMessage[];
+	/** Sizes in the gate's estimate unit (characters by default, or the injected estimator's unit). */
+	beforeEstimate: number;
+	afterEstimate: number;
+	savingsEstimate: number;
+	diagnostics: string[];
+	editTrace?: ContextEditTrace;
+	reason?: string;
+}

package/steering/house-brief.md

@@ -0,0 +1,43 @@
+You manage your own context. The file named in "Editable context" is the exact
+conversation you will see on your next request; whatever you write there is what you
+will remember. Use it deliberately.
+
+When to act
+- Watch the [CLM BUDGET] notices; they state the estimated size of the next request and
+  the provider-reported size of the previous one. Edit before you reach the reserve, not
+  after: one turn with several large tool results can jump past the budget.
+- Prefer one larger batched edit over many small ones. Each accepted edit changes the
+  request prefix, so everything after the edit point is re-processed by the provider.
+
+What to keep
+- The task statement, the current plan, decisions and their reasons, verified facts with
+  their sources (file paths, ids, commands), dead ends so you do not retry them, and the
+  next action.
+- Anything you will need verbatim (exact values, keys, quotes). Either keep it in the
+  context, or offload it to a file and keep the path plus a one-line index; re-read on
+  demand.
+
+What to drop or shrink
+- Raw tool output you have already extracted the facts from: replace the block body with a
+  one-line summary of what the command was and what you learned.
+- Superseded exploration, duplicated content, your own scratch reasoning once its
+  conclusion is recorded.
+
+How to edit
+- Read the first line of the mirror right before you write and copy it unchanged; then
+  list the `[[CTX_TURN ...]]` header lines to get block ids. Do not print whole bodies.
+- Edit bodies in place with a small Python script (re.sub on the block body); keep every
+  header line you retain. Delete a block by removing its header and body together.
+- To add a durable note, insert a block whose id starts with `new-` (for example
+  `id=new-tracker`) with a role label such as `notes`. Never invent numeric ids; ids of
+  existing blocks come only from the current headers. Update the note in place afterwards
+  instead of appending new copies.
+- If you want to replace everything with a summary, you may write the file as plain text
+  without any headers: it becomes one notes block after the original task statement. Use
+  this sparingly; you lose everything else.
+- Tool results that were withheld by the overflow guard can be re-read from the file path
+  in their note; read only the part you need (offset/limit or grep), and record the fact
+  you extracted before moving on.
+- Keep a compact tracker block near the top (status, done/todo, key facts, next step) and
+  maintain it every few turns.
+- Never fabricate content in a summary; when unsure, keep the exact text or offload it.