@possumtech/rummy 2.0.0 → 2.1.0

package/src/plugins/cli/README.md

@@ -0,0 +1,87 @@
+# cli
+
+One-shot CLI client. Boots the service, runs a single `ask`/`act`,
+prints the final summary to stdout, exits with code `0` on terminal
+status `200` (non-zero otherwise). Server mode is unaffected — the
+plugin is inert when `RUMMY_PROMPT` is unset.
+
+## Invocation
+
+```bash
+rummy-cli --RUMMY_PROMPT="list files in /tmp" --RUMMY_MODEL=xfast
+```
+
+All args are env-var-shape: `--KEY=value`, `--KEY value`, or `--KEY`
+(boolean shorthand → `"1"`). Anything else is rejected with exit
+code `2`. CLI flags trump every `.env*` file (Node's `loadEnvFile`
+preserves existing vars).
+
+## Required env
+
+| Var | Effect |
+|---|---|
+| `RUMMY_PROMPT` | Activates the plugin and supplies the instruction. |
+| `RUMMY_MODEL` | Model alias (must match a registered `RUMMY_MODEL_<alias>`). |
+
+## Optional env
+
+| Var | Default | Effect |
+|---|---|---|
+| `RUMMY_MODE` | `act` | `ask` or `act`. |
+
+`RUMMY_RUN_TIMEOUT` is required at boot via `src/agent/config.js`;
+default lives in `.env.example`. Watchdog exits with code `124` on
+overflow.
+
+Per-run defaults (`RUMMY_YOLO`, `RUMMY_NO_REPO`, `RUMMY_NO_WEB`,
+`RUMMY_NO_INTERACTION`, `RUMMY_NO_PROPOSALS`) cascade through
+`AgentLoop`'s boundary normalization — see `.env.example`.
+
+## Profile pattern
+
+Layer profile-specific defaults via Node's `--env-file-if-exists`:
+
+```bash
+node --env-file-if-exists=.env.example \
+     --env-file-if-exists=.env \
+     --env-file-if-exists=.env.tbench \
+     src/plugins/cli/bin.js \
+     --RUMMY_PROMPT="..." --RUMMY_MODEL=xfast
+```
+
+A `.env.tbench` profile typically pins `RUMMY_YOLO=1`,
+`RUMMY_NO_INTERACTION=1`, `RUMMY_NO_WEB=1`, plus model alias and
+provider key. Bench harnesses call `rummy-cli` with just
+`--RUMMY_PROMPT="..."` and let the profile carry the rest.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Terminal status `200`. Model claimed success. |
+| `1` | Terminal status in `{204, 413, 422, 499, 500}` or run crashed. |
+| `2` | Arg parse error (invalid flag shape, missing required env). |
+| `124` | Wall-clock timeout (`RUMMY_RUN_TIMEOUT` exceeded). |
+
+External verifiers (terminal-bench, SWE-bench, etc.) decide actual
+task success — the exit code only reports rummy's internal terminal
+status.
+
+## Files
+
+- **`cli.js`** — plugin class. Subscribes to `boot.completed`; on fire,
+  if `RUMMY_PROMPT` is set, constructs a `ProjectAgent`, kicks off
+  the run, awaits its terminal status, prints the latest update body,
+  exits.
+- **`bin.js`** — executable. Parses env-shape args, mirrors
+  `bin/rummy.js`'s env-loading prelude, imports `service.js`.
+
+## Architectural notes
+
+- The plugin uses the same `ProjectAgent` constructor as
+  `ClientConnection`. In CLI mode, `SocketServer` still starts (it's
+  cheap) — `process.exit()` from the plugin terminates everything.
+- `core.on("boot.completed", ...)` is the plugin's only hook.
+  Subscribing earlier (e.g. constructor-time) would race plugin
+  registration order; `boot.completed` fires after all plugins are
+  inited and the DB is open.

package/src/plugins/cli/bin.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import resolveRummyHome from "../../agent/rummyHome.js";
+
+// Env-var-shape args: --KEY=value, --KEY value, or --KEY (→ "1").
+const ENV_FLAG = /^--([A-Z][A-Z0-9_]*)(?:=([\s\S]*))?$/;
+
+function parseEnvArgs(argv) {
+	const args = argv.slice(2);
+	let i = 0;
+	while (i < args.length) {
+		const m = args[i].match(ENV_FLAG);
+		if (!m) {
+			console.error(
+				`rummy-cli: unknown arg ${JSON.stringify(args[i])}. ` +
+					"All args must be --KEY=value, --KEY value, or --KEY (env-var-shape).",
+			);
+			process.exit(2);
+		}
+		const [, name, inline] = m;
+		if (inline !== undefined) {
+			process.env[name] = inline;
+			i += 1;
+			continue;
+		}
+		const next = args[i + 1];
+		if (next === undefined || next.startsWith("--")) {
+			process.env[name] = "1";
+			i += 1;
+			continue;
+		}
+		process.env[name] = next;
+		i += 2;
+	}
+}
+
+parseEnvArgs(process.argv);
+
+// Same env cascade as bin/rummy.js; CLI flags trump because loadEnvFile preserves existing vars.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, "../../..");
+const rummyHome = resolveRummyHome();
+
+const cwd = process.cwd();
+const baseDir = existsSync(join(cwd, ".env.example")) ? cwd : rummyHome;
+if (existsSync(join(baseDir, ".env.example"))) {
+	process.loadEnvFile(join(baseDir, ".env.example"));
+}
+const userEnv = join(baseDir, ".env");
+if (existsSync(userEnv)) process.loadEnvFile(userEnv);
+
+process.env.RUMMY_HOME = rummyHome;
+const dbPath = process.env.RUMMY_DB_PATH;
+if (dbPath && !isAbsolute(dbPath)) {
+	process.env.RUMMY_DB_PATH = join(rummyHome, dbPath);
+}
+
+await import(join(packageRoot, "service.js"));

package/src/plugins/cli/cli.js

@@ -0,0 +1,120 @@
+import config from "../../agent/config.js";
+import ProjectAgent from "../../agent/ProjectAgent.js";
+
+const TERMINAL_STATUSES = new Set([200, 204, 413, 422, 499, 500]);
+
+// Inert unless RUMMY_PROMPT is set; see plugin README.
+export default class Cli {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.on("boot.completed", this.#onBoot.bind(this));
+	}
+
+	async #onBoot({ db, hooks }) {
+		const prompt = process.env.RUMMY_PROMPT;
+		if (!prompt) return;
+
+		const model = process.env.RUMMY_MODEL;
+		if (!model) {
+			console.error("rummy-cli: RUMMY_MODEL is required");
+			process.exit(2);
+		}
+
+		const rawMode = process.env.RUMMY_MODE;
+		const mode = rawMode == null ? "act" : rawMode;
+		if (mode !== "ask" && mode !== "act") {
+			console.error(
+				`rummy-cli: RUMMY_MODE must be "ask" or "act" (got ${JSON.stringify(rawMode)})`,
+			);
+			process.exit(2);
+		}
+
+		// In-process CLI has no socket client to resolve proposals; default
+		// YOLO so any proposal-emitting tool auto-accepts. Operator can
+		// pass --RUMMY_YOLO=0 to opt out.
+		if (process.env.RUMMY_YOLO == null) process.env.RUMMY_YOLO = "1";
+
+		const projectRoot = process.cwd();
+		const alias = `cli_${Date.now()}`;
+
+		const projectAgent = new ProjectAgent(db, hooks);
+		const { projectId } = await projectAgent.init(alias, projectRoot);
+
+		// Watchdog; overridable via --RUMMY_RUN_TIMEOUT=<ms>.
+		const timeoutMs = config.RUN_TIMEOUT;
+		const timer = setTimeout(() => {
+			console.error(`rummy-cli: timed out after ${timeoutMs}ms`);
+			process.exit(124);
+		}, timeoutMs);
+		timer.unref();
+
+		// stderr progress: log update entries as they land.
+		hooks.entry.created.on((entry) => {
+			if (entry?.scheme !== "update") return;
+			const turnMatch = entry.path?.match(/^log:\/\/turn_(\d+)\//);
+			if (!turnMatch) return;
+			const status = entry.attributes?.status ?? 102;
+			console.error(`[rummy-cli] turn ${turnMatch[1]} status=${status}`);
+		});
+
+		// Capture enriched terminal payload (status, cost, tokens, model)
+		// from ask.completed / act.completed. Only one fires for our run.
+		let runSummary = null;
+		const captureSummary = (payload) => {
+			if (payload.run !== alias) return;
+			runSummary = payload;
+		};
+		hooks.ask.completed.on(captureSummary);
+		hooks.act.completed.on(captureSummary);
+
+		const runFn =
+			mode === "act"
+				? projectAgent.act.bind(projectAgent)
+				: projectAgent.ask.bind(projectAgent);
+
+		try {
+			const result = await runFn(projectId, model, prompt, alias, {});
+			const { status } = result;
+			if (TERMINAL_STATUSES.has(status)) {
+				const text = await this.#findLatestSummary(db, alias);
+				if (text) process.stdout.write(`${text}\n`);
+			}
+			if (runSummary) {
+				process.stdout.write(
+					`__RUMMY_RUN_SUMMARY__ ${JSON.stringify({
+						run: runSummary.run,
+						status: runSummary.status,
+						turn: runSummary.turn,
+						turns: runSummary.turns,
+						cost: runSummary.cost,
+						tokens: runSummary.tokens,
+						model: runSummary.model,
+					})}\n`,
+				);
+			}
+			await new Promise((r) => setTimeout(r, 50));
+			process.exit(status === 200 ? 0 : 1);
+		} catch (err) {
+			console.error(`rummy-cli: run crashed: ${err.message}`);
+			process.exit(1);
+		}
+	}
+
+	async #findLatestSummary(db, alias) {
+		const runRow = await db.get_run_by_alias.get({ alias });
+		if (!runRow) return null;
+		const entries = await db.get_known_entries.all({ run_id: runRow.id });
+		const updates = entries
+			.filter(
+				(e) =>
+					e.scheme === "log" &&
+					/^log:\/\/turn_\d+\/update\//.test(e.path) &&
+					e.state === "resolved",
+			)
+			.toSorted((a, b) => a.turn - b.turn);
+		if (updates.length === 0) return null;
+		return updates.at(-1).body;
+	}
+}

package/src/plugins/env/README.md

@@ -17,7 +17,8 @@ side effects.
   The audit record (renders inside `<log>` as `<env>`).
 - **Data channels**: `env://turn_N/{slug}_1` (stdout), `env://turn_N/{slug}_2`
   (stderr) — scheme=`env`, category=`data`. The captured payload
-  (renders inside `<context>` as `<env>`).
+  (renders inside `<visible>` as `<env>` when promoted; otherwise listed
+  in `<summarized>`).
 
 The `env` scheme exists **only** for the data channels. See
 [scheme_category_split](#scheme_category_split).

package/src/plugins/env/env.js

@@ -1,4 +1,4 @@
-import { logPathToDataBase } from "../helpers.js";
+import { logPathToDataBase, streamSummary } from "../helpers.js";
 import docs from "./envDoc.js";
 
 const LOG_ACTION_RE = /^log:\/\/turn_\d+\/(\w+)\//;
@@ -8,9 +8,7 @@ export default class Env {
 
 	constructor(core) {
 		this.#core = core;
-		// `env` scheme holds the streamed stdout/stderr payload. See sh.js
-		// for the scheme/category split rationale. env differs from sh only
-		// in ask-mode policy (env is safe/read-only; sh has side effects).
+		// env vs sh: env is read-only (allowed in ask-mode); see plugin README.
 		core.registerScheme({ category: "data" });
 		core.on("handler", this.handler.bind(this));
 		core.on("visible", this.full.bind(this));
@@ -66,7 +64,7 @@ export default class Env {
 		return `# env ${entry.attributes.command}\n${entry.body}`;
 	}
 
-	summary() {
-		return "";
+	summary(entry) {
+		return streamSummary("env", entry);
 	}
 }

package/src/plugins/env/envDoc.md

@@ -6,8 +6,8 @@ Example: <env>npm --version</env>
 Example: <env>git log --oneline -5</env>
 <!-- Git history. Shows env for read-only investigation. -->
 
-* YOU MUST NOT use <env></env> to read or list files — use <get path="*"/> instead
+YOU MUST NOT use <env></env> to read or list files — use <get path="*"/> instead
 <!-- Prevents cat/ls through shell. Forces file access through get. -->
 
-* YOU MUST NOT use <env></env> for commands with side effects
+YOU MUST NOT use <env></env> for commands with side effects
 <!-- Separates exploration from action. env = observe only. -->

package/src/plugins/error/error.js

@@ -1,6 +1,6 @@
-const MAX_STRIKES = Number(process.env.RUMMY_MAX_STRIKES);
-const MIN_CYCLES = Number(process.env.RUMMY_MIN_CYCLES);
-const MAX_CYCLE_PERIOD = Number(process.env.RUMMY_MAX_CYCLE_PERIOD);
+import config from "../../agent/config.js";
+
+const { MAX_STRIKES, MIN_CYCLES, MAX_CYCLE_PERIOD } = config;
 
 const CONTRACT_REMINDER = "Missing update";
 
@@ -88,28 +88,29 @@ export default class ErrorPlugin {
 		if (state) state.turnErrors++;
 	}
 
-	async #verdict({ store, runId, loopId, turn, recorded, summaryText }) {
+	async #verdict({ store, runId, loopId, recorded, summaryText }) {
 		const state = this.#loopState.get(loopId);
 
 		let cycleReason = null;
-		if (recorded && recorded.length > 0) {
-			const fp = recorded.map(fingerprint).toSorted().join("|");
-			state.history.push(fp);
-			const cycle = detectCycle(state.history);
-			if (cycle.detected) {
-				cycleReason = "Loop detected";
-				await this.#core.hooks.error.log.emit({
-					store,
-					runId,
-					turn,
-					loopId,
-					message: cycleReason,
-					status: 429,
-				});
-			}
+		// Empty turns share a blank fingerprint; intentional.
+		const fp = recorded.map(fingerprint).toSorted().join("|");
+		state.history.push(fp);
+		const cycle = detectCycle(state.history);
+		if (cycle.detected) {
+			cycleReason = "Loop detected";
+			// Silent strike: increment turn-errors without a model-facing entry.
+			state.turnErrors++;
 		}
 
-		const struck = state.turnErrors > 0;
+		let recordedFailed = false;
+		for (const e of recorded) {
+			const current = await store.getState(runId, e.path);
+			if (current?.state === "failed") {
+				recordedFailed = true;
+				break;
+			}
+		}
+		const struck = state.turnErrors > 0 || recordedFailed;
 
 		if (summaryText && !struck) {
 			state.streak = 0;
@@ -121,8 +122,7 @@ export default class ErrorPlugin {
 		if (struck) {
 			state.streak++;
 			if (state.streak >= MAX_STRIKES) {
-				// On the abandoning strike, a same-turn terminal update
-				// is honored as completion rather than overridden by 499.
+				// Abandoning-strike turn: same-turn terminal update wins over 499.
 				if (summaryText) {
 					state.streak = 0;
 					const updateEntry = recorded?.findLast?.(
@@ -141,7 +141,7 @@ export default class ErrorPlugin {
 			}
 			return {
 				continue: true,
-				reason: cycleReason || CONTRACT_REMINDER,
+				reason: CONTRACT_REMINDER,
 			};
 		}
 

package/src/plugins/file/file.js

@@ -1,20 +1,11 @@
 import { isAbsolute, relative } from "node:path";
 
-/**
- * File plugin: projections and constraints for filesystem entries.
- *
- * Bare file paths (src/app.js) have scheme=NULL in the DB because
- * schemeOf() only recognizes "://" patterns. The schemes table has
- * a "file" entry so v_model_context can JOIN via COALESCE(scheme, 'file').
- * This is the one exception to "every scheme has a plugin owner" —
- * the file plugin owns the NULL scheme through the "file" registry entry.
- */
+// Owns NULL scheme (bare paths) via the "file" registry entry; see plugin README.
 export default class File {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
-		// "file" scheme covers bare paths (scheme IS NULL in DB)
 		core.registerScheme({ category: "data" });
 		core.on("visible", this.full.bind(this));
 		core.on("summarized", this.summary.bind(this));
@@ -28,10 +19,6 @@ export default class File {
 		return "";
 	}
 
-	/**
-	 * Set a project-level file constraint. Backbone operation —
-	 * constraints are project config, not tool dispatch.
-	 */
 	static async setConstraint(db, projectId, pattern, visibility = "active") {
 		const path = await normalizePath(db, projectId, pattern);
 		if (!path) return null;
@@ -45,9 +32,6 @@ export default class File {
 		return path;
 	}
 
-	/**
-	 * Remove a project-level file constraint.
-	 */
 	static async dropConstraint(db, projectId, pattern) {
 		const path = await normalizePath(db, projectId, pattern);
 		if (!path) return null;
@@ -60,11 +44,7 @@ export default class File {
 		return path;
 	}
 
-	/**
-	 * True if `path` is covered by any readonly constraint for the project.
-	 * Constraints can be globs; hedberg.match provides the pattern engine.
-	 * Called from AgentLoop set-accept to refuse writes to protected paths.
-	 */
+	// True if any readonly constraint matches; called from set-accept gate.
 	static async isReadonly(db, projectId, path) {
 		const rows = await db.get_file_constraints.all({ project_id: projectId });
 		const { hedmatch } = await import("./../hedberg/patterns.js");

package/src/plugins/get/get.js

@@ -21,32 +21,23 @@ export default class Get {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const target = entry.attributes.path;
 		if (!target) {
-			// Route through the unified error channel so the message lands
-			// as `<error>` in <log> with a readable body AND the failure
-			// counts as a strike. The previous direct `store.set` wrote a
-			// blank-bodied failed entry whose `error` attribute was never
-			// rendered — model saw a vague 400 and repeated the mistake.
-			await rummy.hooks.error.log.emit({
-				store,
+			await store.set({
 				runId,
 				turn,
 				loopId,
-				message:
-					'Missing required "path" attribute on <get>. Use <get path="..."/>.',
-				status: 400,
+				path: entry.resultPath,
+				body: 'Missing required "path" attribute on <get>. Use <get path="..."/>.',
+				state: "failed",
+				outcome: "validation",
 			});
 			return;
 		}
 		const normalized = Entries.normalizePath(target);
-		// XmlParser passes attributes through; `body` attr is optional.
 		const bodyFilter = entry.attributes.body;
-		const preview = entry.attributes.preview !== undefined;
+		const manifest = entry.attributes.manifest !== undefined;
 		const isPattern = bodyFilter || normalized.includes("*");
 
-		// Negative `line` is idiomatic tail-from-end: `line="-50"` means
-		// "start 50 lines from the end," enabling `tail -n N` behavior.
-		// Positive `line` is 1-indexed from start (classic). `limit` is
-		// always a positive count.
+		// Negative line = tail-from-end (line=-50 starts 50 from end).
 		const lineRaw = entry.attributes.line;
 		const line = lineRaw != null ? parseInt(lineRaw, 10) : null;
 		const limit =
@@ -60,12 +51,8 @@ export default class Get {
 			bodyFilter,
 		);
 
-		// Preview — list matches with their full-body token costs. No promotion,
-		// no visibility change, no Token Budget spent. Model uses this to plan
-		// which entries to actually promote. getDoc promises this behavior; the
-		// prior implementation silently promoted anyway, burning the Token Budget
-		// on entries the model thought it was only inspecting.
-		if (preview) {
+		// Manifest: list matches + full-body token costs; no promotion.
+		if (manifest) {
 			await storePatternResult(
 				store,
 				runId,
@@ -74,12 +61,12 @@ export default class Get {
 				target,
 				bodyFilter,
 				matches,
-				{ preview: true, loopId, attributes: { path: target } },
+				{ manifest: true, loopId, attributes: { path: target } },
 			);
 			return;
 		}
 
-		// Partial read — no visibility promotion, returns a line slice as the log item.
+		// Partial read: line slice in the log entry; no promotion.
 		if (line !== null || limit !== null) {
 			if (isPattern) {
 				await store.set({
@@ -108,8 +95,6 @@ export default class Get {
 			}
 			const allLines = matches[0].body.split("\n");
 			const total = allLines.length;
-			// Negative line offsets from the end: line=-50 starts 50 lines
-			// before the end. Clamped to 1 if the offset exceeds total.
 			const startLine =
 				line == null
 					? 1
@@ -120,10 +105,6 @@ export default class Get {
 			const endIdx = limit !== null ? Math.min(startIdx + limit, total) : total;
 			const slice = allLines.slice(startIdx, endIdx).join("\n");
 			const endLine = endIdx;
-			// Body leads with the source path so the model can re-issue
-			// a full or different-range read without guessing the URL.
-			// lineStart/lineEnd/totalLines ride attrs so renderLogTag can
-			// surface `lines="a-b/total"` without parsing the body.
 			const header = `${target}\n[lines ${startLine}–${endLine} / ${total} total]`;
 			await store.set({
 				runId,
@@ -188,10 +169,7 @@ export default class Get {
 				attributes: { path: target },
 			});
 		} else {
-			// Log a concise record of the promotion. The promoted entry
-			// itself is visible in <context>; this log line is the model's
-			// proof in <log> that the get has already been done so it
-			// doesn't re-issue the same fetch on a later turn.
+			// Log line in <log> proves the promotion happened so the model doesn't re-fetch.
 			await store.set({
 				runId,
 				turn,

package/src/plugins/get/getDoc.md

@@ -1,7 +1,7 @@
-## <get>[path/to/file]</get> - Promote an entry
+## <get path="[path/to/file]"/> - Promote an entry
 
-Example: <get>src/app.js</get>
-<!-- Simplest form. Body = path. -->
+Example: <get path="src/app.js"/>
+<!-- Simplest form. Path attribute. Body is reserved for content filter. -->
 
 Example: <get path="known://*">auth</get>
 <!-- Keyword recall: glob in path, search term in body. -->
@@ -9,7 +9,7 @@ Example: <get path="known://*">auth</get>
 Example: <get path="src/**/*.js">authentication</get>
 <!-- Full pattern: recursive glob + content filter. -->
 
-Example: <get path="src/**/*.js" preview>authentication</get>
+Example: <get path="src/**/*.js" manifest>authentication</get>
 <!-- Full pattern: recursive glob + content filter. -->
 
 Example: <get path="src/agent/AgentLoop.js" line="644" limit="80"/>
@@ -30,7 +30,9 @@ Example: <get path="https://en.wikipedia.org/wiki/Long_Page" line="1" limit="200
 * `line` and `limit` read a slice without promoting the entry, which costs as many tokens as the slice contains. Negative `line` reads from the end (tail).
 <!-- Partial read is safe: context budget unaffected. Tail idiom enables watching growing entries. -->
 
-* `preview` lists the paths and token budget impact of an operation without performing it.
-<!-- Partial read is safe: context budget unaffected. Tail idiom enables watching growing entries. -->
+* `manifest` lists the paths and their token amounts instead of performing the operation; useful for bulk and pattern matching tasks.
+<!-- manifest = listing, not snippet. The natural-language reading of "preview" pulled small models toward content-sampling; for body samples use line/limit. -->
 
 * Remember to <set path="..." visibility="summarize"/> when entries or log events are no longer relevant.
+
+* Promotions don't appear until next turn — emit Stage Continuation (1xx), not Completion (200)

package/src/plugins/hedberg/edits.js

@@ -1,14 +1,4 @@
-/**
- * Edit format detection. Identifies the edit syntax the model used
- * and normalizes it into { search, replace } blocks.
- *
- * Supported formats:
- * 1. SEARCH/REPLACE merge conflict blocks
- * 2. Replace-only blocks (no search)
- * 3. Unified diff
- * 4. Claude XML (<old_text>/<new_text>)
- */
-
+// Detects merge-conflict / replace-only / udiff / Claude XML edits → {search,replace}; SPEC #hedberg.
 export function parseEditContent(content) {
 	const blocks = [];
 

package/src/plugins/hedberg/hedberg.js

@@ -4,18 +4,7 @@ import { parseJsonEdit } from "./normalize.js";
 import { hedmatch, hedsearch } from "./patterns.js";
 import { parseSed } from "./sed.js";
 
-/**
- * Hedberg: the interpretation boundary between stochastic model output
- * and deterministic system operations.
- *
- * Registers its functions on core.hedberg so any plugin can call them:
- *   core.hedberg.match(pattern, string)
- *   core.hedberg.search(pattern, string)
- *   core.hedberg.replace(body, search, replacement, options?)
- *   core.hedberg.parseSed(input)
- *   core.hedberg.parseEdits(content)
- *   core.hedberg.generatePatch(path, old, new)
- */
+// Stochastic→deterministic boundary; exposes pattern/edit utilities on core.hedberg. SPEC #hedberg.
 export default class Hedberg {
 	#core;
 
@@ -31,17 +20,9 @@ export default class Hedberg {
 			parseJsonEdit,
 			generatePatch,
 		};
-
-		// Patterns documentation distributed to individual tool docs.
-		// Hedberg has no model-facing docs of its own.
 	}
 
-	/**
-	 * Apply a replacement to text. Handles sed regex, literal match,
-	 * and heuristic fuzzy match — in that order.
-	 *
-	 * Returns { patch, searchText, replaceText, warning, error }
-	 */
+	// Order: sed regex → literal → heuristic fuzzy.
 	static replace(body, search, replacement, { sed = false, flags = "" } = {}) {
 		let patch = null;
 		let warning = null;
@@ -55,11 +36,7 @@ export default class Hedberg {
 					searchText,
 					flags.includes("g") ? flags : `${flags}g`,
 				);
-				// Unescape regex metacharacter escapes in the replacement string.
-				// The model writes `\[x\]` meaning literal `[x]` in both search
-				// and replace. RegExp handles this in search; in the replacement
-				// string we must strip the backslashes ourselves since
-				// String.replace only interprets `$` sequences, not `\`.
+				// Strip regex-meta escapes in replacement; String.replace only interprets `$`, not `\`.
 				const unescaped = replaceText.replace(/\\([[\](){}.*+?^$|\\])/g, "$1");
 				patch = body.replace(re, unescaped);
 				if (patch === body) patch = null;

package/src/plugins/hedberg/normalize.js

@@ -1,8 +1,4 @@
-/**
- * Parse JSON-style edit from body content.
- * Accepts: {"search":"old","replace":"new"} and {search="old",replace="new"}
- * Returns { search, replace } or null.
- */
+// {"search":"old","replace":"new"} or {search="old",replace="new"} → {search,replace}|null.
 export function parseJsonEdit(text) {
 	const trimmed = text.trim();
 	if (!trimmed.startsWith("{") || !/search/.test(trimmed)) return null;