opencode-clm 0.1.0

package/src/opencode.ts

@@ -0,0 +1,339 @@
+/**
+ * Conversion between OpenCode's `{ info, parts }` messages (as delivered to
+ * `experimental.chat.messages.transform`) and the flat message list the core
+ * (context-document.ts, projection.ts, observation.ts, overflow.ts) works on.
+ *
+ * Takes the place of pi-clm's identity cast between AgentMessage and LiveContextMessage
+ * (pi-clm src/index.ts, MIT, Copyright 2026 Emanuel Casco): Pi already stores pi-shaped
+ * messages, OpenCode does not.
+ *
+ * Shape. OpenCode keeps a tool call and its result in one `tool` part of an assistant
+ * message. The core expects an assistant message carrying `toolCall` blocks followed by one
+ * `toolResult` message per call, so `flatten` splits every assistant message that way and
+ * each tool result becomes its own mirror block. Every flat message carries `ocMessageID`,
+ * the OpenCode message it came from (projection checkpoints store these as `sourceIds`).
+ *
+ * Fidelity. `flatten` follows OpenCode 1.18.34 `MessageV2.toModelMessagesEffect`:
+ * - a message without parts is skipped;
+ * - a failed assistant message (`info.error`) is skipped unless the error is
+ *   `MessageAbortedError` and some part is neither `step-start` nor `reasoning`;
+ * - user text parts that are `ignored` or empty are skipped; `text/plain` and directory file
+ *   parts are skipped (OpenCode inlines their content as synthetic text parts); a
+ *   `compaction` part reads "What did we do so far?" and a `subtask` part "The following
+ *   tool was executed by the user" (OpenCode's own strings);
+ * - a completed tool sends its output, or "[Old tool result content cleared]" once
+ *   OpenCode's prune set `time.compacted`; an error sends its error text, or the partial
+ *   output of an interrupted call; a pending or running call sends
+ *   "[Tool execution was interrupted]".
+ * Flattening never depends on settings: the projection digest is computed from it, and a
+ * settings toggle must not discard an accepted revision. Reasoning is always flattened;
+ * `withoutReasoning` hides it from the mirror view only.
+ *
+ * Known gap: an assistant message whose only sendable parts are empty text parts has no
+ * flat form and is left out of the request. OpenCode sends it as an empty assistant turn.
+ *
+ * Identity rule for `unflatten`: a block the model did not touch maps back to the current
+ * raw OpenCode object (looked up by `ocMessageID` and call id), so untouched messages reach
+ * the provider exactly as OpenCode would send them. Only edited user and assistant bodies,
+ * tool results flagged `edited`, `withheld` or `capped`, and notes are synthesized. One
+ * exception: an untouched result that OpenCode's prune cleared while the flat text kept the
+ * full output (inside an accepted revision) is sent with the flat text.
+ */
+import { createHash } from "node:crypto";
+
+import { NOTE_TYPE, renderMessage } from "./context-document.ts";
+import type { LiveContextMessage } from "./types.ts";
+
+// Loose structural types: assignable from @opencode-ai/sdk `Message` / `Part`, which this
+// module does not import at runtime (the plugin package is an optional peer dependency).
+export type OcPart = { id: string; type: string; [key: string]: any };
+export type OcInfo = { id: string; sessionID: string; role: "user" | "assistant"; [key: string]: any };
+export interface OcMessage {
+	info: OcInfo;
+	parts: OcPart[];
+}
+
+/** OpenCode's own placeholder texts (packages/opencode/src/session/message-v2.ts). */
+export const INTERRUPTED_TOOL_TEXT = "[Tool execution was interrupted]";
+export const CLEARED_TOOL_TEXT = "[Old tool result content cleared]";
+export const COMPACTION_USER_TEXT = "What did we do so far?";
+export const SUBTASK_USER_TEXT = "The following tool was executed by the user";
+
+/** Placeholder for an assistant message whose only content is hidden reasoning. */
+export const REASONING_HIDDEN_TEXT = "[reasoning not shown in the mirror]";
+
+/** The text OpenCode sends as the result of one tool part, and whether it is an error. */
+export function toolPartOutput(part: OcPart): { text: string; isError: boolean } {
+	const state = part.state ?? {};
+	switch (state.status) {
+		case "completed":
+			return { text: state.time?.compacted ? CLEARED_TOOL_TEXT : String(state.output ?? ""), isError: false };
+		case "error": {
+			const partial = state.metadata?.interrupted === true ? state.metadata.output : undefined;
+			if (typeof partial === "string") return { text: partial, isError: false };
+			return { text: String(state.error ?? ""), isError: true };
+		}
+		default:
+			return { text: INTERRUPTED_TOOL_TEXT, isError: true };
+	}
+}
+
+/** OpenCode drops failed assistant messages, except aborted ones with real content. */
+export function sentToModel(message: OcMessage): boolean {
+	if (message.parts.length === 0) return false;
+	const error = message.info.role === "assistant" ? message.info.error : undefined;
+	if (!error) return true;
+	return error.name === "MessageAbortedError" &&
+		message.parts.some((part) => part.type !== "step-start" && part.type !== "reasoning");
+}
+
+function fileBlock(mime: string, filename: unknown): Record<string, unknown> {
+	if (mime.startsWith("image/")) return { type: "image", mimeType: mime };
+	return { type: "text", text: `[file ${mime}: ${typeof filename === "string" && filename ? filename : "file"}]` };
+}
+
+function userContent(message: OcMessage): Record<string, unknown>[] {
+	const content: Record<string, unknown>[] = [];
+	for (const part of message.parts) {
+		if (part.type === "text" && !part.ignored && part.text !== "") content.push({ type: "text", text: String(part.text ?? "") });
+		else if (part.type === "file" && part.mime !== "text/plain" && part.mime !== "application/x-directory") {
+			content.push(fileBlock(String(part.mime ?? "application/octet-stream"), part.filename));
+		} else if (part.type === "compaction") content.push({ type: "text", text: COMPACTION_USER_TEXT });
+		else if (part.type === "subtask") content.push({ type: "text", text: SUBTASK_USER_TEXT });
+	}
+	return content;
+}
+
+function toolResultContent(part: OcPart, text: string): Record<string, unknown>[] {
+	const content: Record<string, unknown>[] = [{ type: "text", text }];
+	const state = part.state ?? {};
+	if (state.status === "completed" && !state.time?.compacted && Array.isArray(state.attachments)) {
+		for (const attachment of state.attachments) {
+			if (attachment && typeof attachment.mime === "string") content.push(fileBlock(attachment.mime, attachment.filename));
+		}
+	}
+	return content;
+}
+
+/**
+ * OpenCode messages → flat messages, each tagged with `ocMessageID`. Deterministic and
+ * independent of settings, so the same stored history always digests the same way.
+ */
+export function flatten(messages: readonly OcMessage[]): LiveContextMessage[] {
+	const out: LiveContextMessage[] = [];
+	for (const message of messages) {
+		if (!sentToModel(message)) continue;
+		const id = message.info.id;
+		const timestamp = Number(message.info.time?.created ?? 0);
+		if (message.info.role === "user") {
+			const content = userContent(message);
+			if (content.length > 0) out.push({ role: "user", content, ocMessageID: id, timestamp });
+			continue;
+		}
+		const content: Record<string, unknown>[] = [];
+		const results: LiveContextMessage[] = [];
+		for (const part of message.parts) {
+			if (part.type === "text" && part.text) content.push({ type: "text", text: String(part.text) });
+			else if (part.type === "reasoning" && String(part.text ?? "").trim()) {
+				content.push({ type: "thinking", thinking: String(part.text) });
+			} else if (part.type === "tool") {
+				content.push({ type: "toolCall", id: part.callID, name: part.tool, arguments: part.state?.input ?? {} });
+				const output = toolPartOutput(part);
+				results.push({
+					role: "toolResult",
+					toolCallId: part.callID,
+					toolName: part.tool,
+					content: toolResultContent(part, output.text),
+					isError: output.isError,
+					ocMessageID: id,
+					timestamp,
+				});
+			}
+		}
+		if (content.length === 0) continue;
+		out.push({ role: "assistant", content, ocMessageID: id, timestamp });
+		out.push(...results);
+	}
+	return out;
+}
+
+const hiddenReasoning = new WeakMap<LiveContextMessage, LiveContextMessage>();
+
+/**
+ * Mirror view without reasoning (`reasoning: false`). Assistant messages lose their
+ * `thinking` blocks; one with nothing else keeps a short placeholder, so its block is not
+ * empty (an empty body deletes the block). One-to-one, so projection indexes still hold.
+ * Unflatten maps untouched assistant blocks back to the raw message, reasoning included.
+ */
+export function withoutReasoning(messages: LiveContextMessage[]): LiveContextMessage[] {
+	let changed = false;
+	const output = messages.map((message) => {
+		if (message.role !== "assistant" || !Array.isArray(message.content)) return message;
+		const cached = hiddenReasoning.get(message);
+		if (cached) {
+			changed ||= cached !== message;
+			return cached;
+		}
+		const content = message.content.filter((part) => !(part && typeof part === "object" && (part as { type?: unknown }).type === "thinking"));
+		let next = message;
+		if (content.length !== message.content.length) {
+			next = { ...message, content: content.length > 0 ? content : [{ type: "text", text: REASONING_HIDDEN_TEXT }] };
+			changed = true;
+		}
+		hiddenReasoning.set(message, next);
+		return next;
+	});
+	return changed ? output : messages;
+}
+
+function textOf(message: LiveContextMessage): string {
+	const content = message.content;
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((part): part is { type: "text"; text: string } => Boolean(part) && (part as { type?: string }).type === "text" && typeof (part as { text?: unknown }).text === "string")
+		.map((part) => part.text)
+		.join("\n");
+}
+
+function shortHash(value: string): string {
+	return createHash("sha256").update(value).digest("hex").slice(0, 20);
+}
+
+export interface UnflattenContext {
+	sessionID: string;
+	/** Current raw messages by id. */
+	rawById: Map<string, OcMessage>;
+	/** Info whose agent and model synthetic user messages copy (the newest user message). */
+	template?: OcInfo;
+}
+
+/** A synthetic user message carrying text: notes, notices, continuity, orphaned results. */
+export function noteMessage(text: string, seed: string, context: UnflattenContext, created = Date.now()): OcMessage {
+	const hash = shortHash(`${seed}\n${text}`);
+	const messageID = `msg_clm${hash}`;
+	return {
+		info: {
+			id: messageID,
+			sessionID: context.sessionID,
+			role: "user",
+			time: { created },
+			agent: context.template?.agent ?? "build",
+			model: context.template?.model ?? { providerID: "", modelID: "" },
+		},
+		parts: [{ id: `prt_clm${hash}`, sessionID: context.sessionID, messageID, type: "text", text, synthetic: true }],
+	};
+}
+
+function textPart(message: OcMessage, text: string, kind: string): OcPart {
+	return {
+		id: `prt_clm${shortHash(`${message.info.id}:${kind}:${text}`)}`,
+		sessionID: message.info.sessionID,
+		messageID: message.info.id,
+		type: "text",
+		text,
+		synthetic: true,
+	};
+}
+
+/**
+ * A tool part with its output replaced: the call keeps its pairing, only the result text
+ * changes. A capped result keeps its attachments; an edited or withheld one drops them.
+ */
+function withOutput(part: OcPart, result: LiveContextMessage, output = textOf(result)): OcPart {
+	const state = part.state ?? {};
+	const start = Number(state.time?.start ?? 0);
+	const keepAttachments = result.edited !== true && result.withheld !== true;
+	return {
+		...part,
+		state: {
+			status: "completed",
+			input: state.input ?? {},
+			output,
+			title: typeof state.title === "string" ? state.title : "",
+			metadata: state.metadata ?? {},
+			time: { start, end: Number(state.time?.end ?? start) },
+			...(keepAttachments && Array.isArray(state.attachments) ? { attachments: state.attachments } : {}),
+		},
+	};
+}
+
+function rewritten(result: LiveContextMessage): boolean {
+	return result.edited === true || result.withheld === true || result.capped === true;
+}
+
+/** The tool output text of a flat result: its first block (attachments follow it). */
+function resultOutput(result: LiveContextMessage): string | undefined {
+	const first = Array.isArray(result.content) ? (result.content[0] as { type?: unknown; text?: unknown } | undefined) : undefined;
+	return first?.type === "text" && typeof first.text === "string" ? first.text : undefined;
+}
+
+/**
+ * The tool part to send for an untouched result. A part OpenCode's prune cleared after a
+ * revision stored its full text is sent with the flat text, so the request matches the
+ * mirror and the estimate. Other changes to a stored output pass through as OpenCode sends them.
+ */
+function restored(part: OcPart, result: LiveContextMessage): OcPart {
+	if (part.state?.status !== "completed" || !part.state.time?.compacted) return part;
+	const output = resultOutput(result);
+	if (output === undefined || output === toolPartOutput(part).text) return part;
+	return withOutput(part, result, output);
+}
+
+/**
+ * Flat messages → OpenCode messages. Expects legal tool groups (applyContextDocument
+ * repairs them): a kept assistant is followed by the results of all its calls. Anything
+ * that cannot be mapped back to a raw message becomes a synthetic user note.
+ */
+export function unflatten(messages: readonly LiveContextMessage[], context: UnflattenContext): OcMessage[] {
+	const out: OcMessage[] = [];
+	for (let index = 0; index < messages.length; index++) {
+		const message = messages[index]!;
+		const id = typeof message.ocMessageID === "string" ? message.ocMessageID : undefined;
+		const raw = id ? context.rawById.get(id) : undefined;
+		if (raw && raw.info.role === "user" && message.role === "user") {
+			out.push(message.edited ? { info: raw.info, parts: [textPart(raw, textOf(message), "user")] } : raw);
+			continue;
+		}
+		if (raw && raw.info.role === "assistant" && message.role === "assistant") {
+			const results = new Map<string, LiveContextMessage>();
+			while (
+				index + 1 < messages.length &&
+				messages[index + 1]!.role === "toolResult" &&
+				messages[index + 1]!.ocMessageID === id
+			) {
+				const result = messages[++index]!;
+				results.set(String(result.toolCallId), result);
+			}
+			if (message.edited) {
+				out.push({ info: raw.info, parts: [textPart(raw, textOf(message), "assistant")] });
+				for (const result of results.values()) {
+					out.push(noteMessage(renderMessage(result), `orphan:${id}:${String(result.toolCallId)}`, context));
+				}
+				continue;
+			}
+			const parts = raw.parts.flatMap((part) => {
+				if (part.type !== "tool") return [part];
+				const result = results.get(String(part.callID));
+				if (!result) return [];
+				return [rewritten(result) ? withOutput(part, result) : restored(part, result)];
+			});
+			const untouched = parts.length === raw.parts.length && parts.every((part, at) => part === raw.parts[at]);
+			out.push(untouched ? raw : { info: raw.info, parts });
+			continue;
+		}
+		// Notes the model wrote, bodies whose role changed, results whose call was removed,
+		// and anything whose raw source is gone: plain synthetic user text.
+		const text = message.role === "custom" && message.customType === NOTE_TYPE ? textOf(message) : renderMessage(message);
+		if (text.trim()) {
+			const created = typeof message.timestamp === "number" && message.timestamp > 0 ? message.timestamp : Date.now();
+			out.push(noteMessage(text, `${index}:${id ?? ""}`, context, created));
+		}
+	}
+	return out;
+}
+
+/** Replace the contents of OpenCode's message array in place (the hook's output object). */
+export function replaceInPlace(target: OcMessage[], next: readonly OcMessage[]): void {
+	target.splice(0, target.length, ...next);
+}

package/src/overflow.ts

@@ -0,0 +1,212 @@
+/**
+ * Overflow guard: keep the next request under the budget when the model has not.
+ *
+ * Adapted from pi-clm src/overflow.ts (MIT, Copyright 2026 Emanuel Casco).
+ *
+ * Reminders arrive at request boundaries, but one assistant turn with many parallel tool
+ * calls can add tens of thousands of tokens at once. When the estimated request exceeds
+ * the guard limit, tool results are *withheld* from the effective context, oldest first —
+ * each replaced by a short note giving the tool, call id, size, and a file holding the
+ * full text — until the estimate fits or nothing withholdable is left.
+ *
+ * Properties:
+ * - transcript-only: OpenCode's stored parts are untouched and no tool is ever re-run;
+ * - oldest first, tool results only; user, assistant and note blocks are never touched.
+ *   Oldest first matters: the result the model just asked for (often a re-read of a
+ *   withheld file) must stay visible, otherwise withholding turns into a loop;
+ * - deterministic and cached per source message, so repeated transform calls agree;
+ * - a note keeps the `toolResult` role and `toolCallId`, so tool-call pairing stays legal,
+ *   and carries `withheld: true` so the unflatten step writes it into the tool part;
+ * - the note is an ordinary block in the mirror: the model can shorten, delete, or
+ *   replace it, and can re-read the saved file.
+ *
+ * OpenCode differences from pi-clm: the limit has no `window − 4096` ceiling (that one
+ * models pi-ai's `max_tokens` clamp). The caller must therefore pass the model's output
+ * limit to `resolveBudget` (budget.ts), which subtracts it from the window; otherwise the
+ * guard limit can exceed the room OpenCode leaves for input. The saved file holds the
+ * uncapped output when the observation cap cut it.
+ */
+
+import { createHash } from "node:crypto";
+import { chmodSync, closeSync, constants, fchmodSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { uncappedSource } from "./observation.ts";
+import type { LiveContextMessage } from "./types.ts";
+
+export interface OverflowGuardPolicy {
+	mode: "withhold" | "off";
+}
+
+export const DEFAULT_OVERFLOW_GUARD: OverflowGuardPolicy = { mode: "withhold" };
+
+/** Prefix of every withheld note; a result that starts with it is never withheld again. */
+export const WITHHELD_NOTE_PREFIX = "[clm overflow guard]";
+
+export function resolveOverflowGuard(overrides: Partial<OverflowGuardPolicy> | undefined): OverflowGuardPolicy {
+	return { ...DEFAULT_OVERFLOW_GUARD, ...(overrides ?? {}) };
+}
+
+/** The limit the guard enforces: the budget minus the generation reserve (at least 1). */
+export function overflowGuardLimit(budget: number, reserve: number): number {
+	return Math.max(1, budget - reserve);
+}
+
+export interface WithheldRecord {
+	message: LiveContextMessage;
+	toolCallId: string;
+	toolName: string;
+	tokens: number;
+	file?: string;
+}
+
+export interface OverflowGuardResult {
+	messages: LiveContextMessage[];
+	withheld: WithheldRecord[];
+	/** Estimated tokens of the returned messages plus `fixedTokens` (same estimator as the caller). */
+	estimated: number;
+}
+
+interface TextPart {
+	type: "text";
+	text: string;
+}
+
+function toolResultText(message: LiveContextMessage): string {
+	const content = message.content;
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((part): part is TextPart => Boolean(part) && typeof part === "object" && (part as TextPart).type === "text" && typeof (part as TextPart).text === "string")
+		.map((part) => part.text)
+		.join("\n");
+}
+
+/** Short by design: notes accumulate, so each costs as little context as possible. */
+export function withheldNoteText(record: Omit<WithheldRecord, "message">): string {
+	const where = record.file ? ` Full text: ${record.file}` : " Full text remains in the session history.";
+	return `${WITHHELD_NOTE_PREFIX} ${record.toolName}#${record.toolCallId} (~${record.tokens.toLocaleString("en-US")} tok) withheld over budget.${where}`;
+}
+
+const withheldCache = new WeakMap<LiveContextMessage, LiveContextMessage>();
+const savedFiles = new WeakMap<LiveContextMessage, string>();
+
+export interface ApplyOverflowGuardOptions {
+	limit: number;
+	/** Estimated tokens of everything outside `messages` (system prompt, notices). */
+	fixedTokens: number;
+	estimate: (messages: LiveContextMessage[]) => number;
+	/** Directory for saved outputs (`<mirror dir>/withheld`); omitted → nothing is written. */
+	saveDirectory?: string;
+	/** Only messages at or after this index are candidates (the raw suffix after the last accepted edit); default 0. */
+	protectBefore?: number;
+}
+
+const MAX_FILE_NAME = 120;
+
+function safeName(value: string): string {
+	return value.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+
+/**
+ * `<ocMessageID>-<callID>.txt`, sanitized. Call ids repeat across messages, so the
+ * message id is part of the name. Names over 120 characters are cut and suffixed with a
+ * short hash of the source text.
+ */
+export function withheldFileName(source: LiveContextMessage, index: number, text: string): string {
+	const base = `${safeName(String(source.ocMessageID ?? "msg"))}-${safeName(String(source.toolCallId ?? `idx${index}`))}`;
+	if (base.length + 4 <= MAX_FILE_NAME) return `${base}.txt`;
+	const hash = createHash("sha256").update(text).digest("hex").slice(0, 12);
+	return `${base.slice(0, MAX_FILE_NAME - 4 - hash.length - 1)}-${hash}.txt`;
+}
+
+function saveFullText(source: LiveContextMessage, index: number, directory: string): string | undefined {
+	let fd: number | undefined;
+	try {
+		mkdirSync(directory, { recursive: true, mode: 0o700 });
+		chmodSync(directory, 0o700); // an existing directory keeps its old mode otherwise
+		const text = toolResultText(uncappedSource(source));
+		const file = join(directory, withheldFileName(source, index, text));
+		// O_NOFOLLOW: never write through a symlink planted at the target path.
+		fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o600);
+		fchmodSync(fd, 0o600); // an existing file keeps its old mode otherwise
+		writeSync(fd, text);
+		return file;
+	} catch {
+		return undefined;
+	} finally {
+		if (fd !== undefined) closeSync(fd);
+	}
+}
+
+/**
+ * Withhold tool results, oldest first, until `fixedTokens + estimate(messages) <= limit`.
+ * Returns the same array when nothing needed to change.
+ */
+export function applyOverflowGuard(messages: LiveContextMessage[], options: ApplyOverflowGuardOptions): OverflowGuardResult {
+	let current = messages;
+	let estimated = options.fixedTokens + options.estimate(current);
+	const withheld: WithheldRecord[] = [];
+	if (estimated <= options.limit) return { messages, withheld, estimated };
+
+	const candidates: number[] = [];
+	for (let index = Math.max(0, options.protectBefore ?? 0); index < messages.length; index++) {
+		const message = messages[index]!;
+		if (message.role !== "toolResult") continue;
+		if (withheldCache.get(message) === message) continue; // already a note
+		if (toolResultText(message).startsWith(WITHHELD_NOTE_PREFIX)) continue;
+		candidates.push(index);
+	}
+	if (candidates.length === 0) return { messages, withheld, estimated };
+
+	const output = [...messages];
+	for (const index of candidates) {
+		const source = output[index]!;
+		const tokens = options.estimate([source]);
+		let file = savedFiles.get(source);
+		if (!file && options.saveDirectory) {
+			file = saveFullText(source, index, options.saveDirectory);
+			if (file) savedFiles.set(source, file);
+		}
+		const record: WithheldRecord = {
+			message: source,
+			toolCallId: String(source.toolCallId ?? "unknown"),
+			toolName: String(source.toolName ?? "tool"),
+			tokens,
+			file,
+		};
+		let note = withheldCache.get(source);
+		if (!note) {
+			// A note replaces the whole result, so the cap flag no longer applies.
+			const { capped: _capped, ...rest } = source;
+			note = {
+				...rest,
+				content: [{ type: "text", text: withheldNoteText(record) }],
+				withheld: true,
+			};
+			withheldCache.set(source, note);
+			withheldCache.set(note, note);
+		}
+		output[index] = note;
+		withheld.push(record);
+		current = output;
+		estimated = options.fixedTokens + options.estimate(current);
+		if (estimated <= options.limit) break;
+	}
+	return { messages: current, withheld, estimated };
+}
+
+export function overflowNoticeText(result: OverflowGuardResult, limit: number): string {
+	const count = result.withheld.length;
+	const files = result.withheld.filter((record) => record.file).length;
+	const list = result.withheld
+		.map((record) => `${record.toolName}#${record.toolCallId} (~${record.tokens.toLocaleString("en-US")} tok)`)
+		.join(", ");
+	const fits = result.estimated <= limit;
+	return (
+		`[CLM BUDGET] Overflow guard: the request would have exceeded the limit of ${limit.toLocaleString("en-US")} tokens, so ${count} tool result${count === 1 ? "" : "s"} ` +
+		`${count === 1 ? "was" : "were"} withheld from your context and replaced by notes${files > 0 ? " with file paths" : ""}: ${list}. ` +
+		`Estimated request is now ${result.estimated.toLocaleString("en-US")} tokens${fits ? "" : " and still over the limit; edit your context now"}. ` +
+		"Nothing was re-run; the full outputs are in the files named in the notes and in the session history. " +
+		"Free space by editing the context mirror, then re-read only the parts you need, e.g. with sed -n or grep."
+	);
+}

package/src/policy.ts

@@ -0,0 +1,60 @@
+// Gate design after the CLM paper's harness (fit / shrink / none); text written for this package.
+
+/**
+ * Edit gate: decides whether a mirror edit that grows the context is applied.
+ *
+ * - "fit":    growth is accepted while the result stays within the limit (budget − reserve).
+ *             Without a positive finite limit there is nothing to measure against, and
+ *             fit accepts every edit, like "none".
+ * - "shrink": growth is rejected; an edit with after <= before is accepted.
+ * - "none":   no size check (pi-clm's CLM mode).
+ *
+ * `before`, `after` and `limit` must share one unit: that of the estimator that produced them.
+ */
+export type EditGate = "fit" | "shrink" | "none";
+
+const GATES: readonly EditGate[] = ["fit", "shrink", "none"];
+
+/** Rule text quoted in a shrink refusal. */
+export const shrinkLimitText = "gate shrink: limit = size before the edit";
+
+/** Rule text quoted in a fit refusal. */
+export function fitLimitText(limit: number, unit: "characters" | "tokens" = "tokens"): string {
+	return `gate fit: limit ${limit} ${unit}`;
+}
+
+/** Reads a gate name, case-insensitive. Booleans are refused: `false` could mean shrink or none. */
+export function toEditGate(value: unknown): EditGate {
+	const name = typeof value === "string" ? value.trim().toLowerCase() : undefined;
+	const gate = GATES.find((candidate) => candidate === name);
+	if (gate) return gate;
+	throw new Error(`unknown edit gate ${JSON.stringify(value)}; use "fit", "shrink" or "none"`);
+}
+
+export interface GateInput {
+	gate: EditGate;
+	before: number;
+	after: number;
+	/** Same unit as `before` and `after`. */
+	limit?: number;
+	/** Unit named in the rejection text. */
+	unit?: "characters" | "tokens";
+}
+
+export function gateEdit(input: GateInput): { accepted: boolean; reason?: string } {
+	if (input.gate === "none" || input.after <= input.before) return { accepted: true };
+	const unit = input.unit ?? "tokens";
+	let rule = shrinkLimitText;
+	if (input.gate === "fit") {
+		const limit = input.limit;
+		if (limit === undefined || !Number.isFinite(limit) || limit <= 0) return { accepted: true };
+		if (input.after <= limit) return { accepted: true };
+		rule = fitLimitText(limit, unit);
+	}
+	return {
+		accepted: false,
+		reason:
+			`Edit refused (${rule}). Size ${input.before} -> ${input.after} ${unit} (estimated). ` +
+			"The previous context is still in effect.",
+	};
+}