@possumtech/rummy 0.5.0 → 2.0.0

package/src/plugins/env/env.js

@@ -1,30 +1,69 @@
+import { logPathToDataBase } from "../helpers.js";
 import docs from "./envDoc.js";
 
+const LOG_ACTION_RE = /^log:\/\/turn_\d+\/(\w+)\//;
+
 export default class Env {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
-		core.registerScheme();
+		// `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).
+		core.registerScheme({ category: "data" });
 		core.on("handler", this.handler.bind(this));
-		core.on("promoted", this.full.bind(this));
-		core.on("demoted", this.summary.bind(this));
+		core.on("visible", this.full.bind(this));
+		core.on("summarized", this.summary.bind(this));
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.env = docs;
 			return docsMap;
 		});
+		core.on("proposal.accepted", this.#onAccepted.bind(this));
+	}
+
+	async #onAccepted(ctx) {
+		const m = LOG_ACTION_RE.exec(ctx.path);
+		if (m?.[1] !== "env") return;
+		let command = "";
+		if (ctx.attrs?.command) command = ctx.attrs.command;
+		else if (ctx.attrs?.summary) command = ctx.attrs.summary;
+		const turn = (await ctx.db.get_run_by_id.get({ id: ctx.runId })).next_turn;
+		const dataBase = logPathToDataBase(ctx.path);
+		for (const ch of [1, 2]) {
+			await ctx.entries.set({
+				runId: ctx.runId,
+				turn,
+				path: `${dataBase}_${ch}`,
+				body: "",
+				state: "streaming",
+				visibility: "summarized",
+				attributes: { command, summary: command, channel: ch },
+			});
+		}
+		await ctx.entries.set({
+			runId: ctx.runId,
+			path: ctx.path,
+			state: "resolved",
+			body: `ran '${command}' (in progress). Output: ${dataBase}_1, ${dataBase}_2`,
+		});
 	}
 
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
-		await store.upsert(runId, turn, entry.resultPath, entry.body, 202, {
-			attributes: entry.attributes,
+		await store.set({
+			runId,
+			turn,
+			path: entry.resultPath,
+			body: "",
+			state: "proposed",
+			attributes: { ...entry.attributes, summary: entry.attributes.command },
 			loopId,
 		});
 	}
 
 	full(entry) {
-		return `# env ${entry.attributes.command || ""}\n${entry.body}`;
+		return `# env ${entry.attributes.command}\n${entry.body}`;
 	}
 
 	summary() {

package/src/plugins/env/envDoc.js

@@ -1,24 +1,3 @@
-// Tool doc for <env>. Each entry: [text, rationale].
-// Text goes to the model. Rationale stays in source.
-// Changing ANY line requires reading ALL rationales first.
-const LINES = [
-	["## <env>[command]</env> - Run an exploratory shell command"],
-	[
-		"Example: <env>npm --version</env>",
-		"Version check. Safe, no side effects.",
-	],
-	[
-		"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',
-		"Prevents cat/ls through shell. Forces file access through get.",
-	],
-	[
-		"* YOU MUST NOT use <env></env> for commands with side effects",
-		"Separates exploration from action. env = observe only.",
-	],
-];
+import { loadDoc } from "../helpers.js";
 
-export default LINES.map(([text]) => text).join("\n");
+export default loadDoc(import.meta.url, "envDoc.md");

package/src/plugins/env/envDoc.md

@@ -0,0 +1,13 @@
+## <env>[command]</env> - Run an exploratory shell command
+
+Example: <env>npm --version</env>
+<!-- Version check. Safe, no side effects. -->
+
+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
+<!-- Prevents cat/ls through shell. Forces file access through get. -->
+
+* YOU MUST NOT use <env></env> for commands with side effects
+<!-- Separates exploration from action. env = observe only. -->

package/src/plugins/error/README.md

@@ -0,0 +1,16 @@
+# error {#error_plugin}
+
+Subscribes to `error.log` hook and writes `error://` entries for any
+runtime error a plugin or the turn executor wants surfaced to the
+model.
+
+## Registration
+
+- **Scheme**: `error` (category: `logging`)
+- **Hook subscriber**: `error.log` → writes entry at `error://<slug>`
+  with `state: "failed"`, `outcome: "validation"`.
+
+## Projection
+
+- **Promoted**: `# error\n{body}`
+- **Demoted**: body only.

package/src/plugins/error/error.js

@@ -0,0 +1,151 @@
+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);
+
+const CONTRACT_REMINDER = "Missing update";
+
+function fingerprint(entry) {
+	const parts = Object.keys(entry.attributes)
+		.toSorted()
+		.filter((k) => entry.attributes[k] != null)
+		.map((k) => `${k}=${entry.attributes[k]}`);
+	return `${entry.scheme}:${parts.join(",")}`;
+}
+
+function detectCycle(history) {
+	for (let k = 1; k <= MAX_CYCLE_PERIOD; k++) {
+		const needed = k * MIN_CYCLES;
+		if (history.length < needed) continue;
+		const tail = history.slice(-needed);
+		const cycle = tail.slice(0, k);
+		let match = true;
+		outer: for (let rep = 0; rep < MIN_CYCLES; rep++) {
+			for (let j = 0; j < k; j++) {
+				if (tail[rep * k + j] !== cycle[j]) {
+					match = false;
+					break outer;
+				}
+			}
+		}
+		if (match) return { detected: true, period: k, cycles: MIN_CYCLES };
+	}
+	return { detected: false };
+}
+
+export default class ErrorPlugin {
+	#core;
+	#loopState = new Map();
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme({ category: "logging" });
+		core.on("visible", (entry) => `# error\n${entry.body}`);
+		core.on("summarized", (entry) => entry.body);
+
+		core.hooks.error.log.on(this.#onErrorLog.bind(this));
+		core.hooks.loop.started.on(this.#onLoopStarted.bind(this));
+		core.hooks.loop.completed.on(this.#onLoopCompleted.bind(this));
+		core.hooks.turn.started.on(this.#onTurnStarted.bind(this));
+
+		core.hooks.error.verdict = this.#verdict.bind(this);
+	}
+
+	#onLoopStarted({ loopId }) {
+		this.#loopState.set(loopId, { streak: 0, history: [], turnErrors: 0 });
+	}
+
+	#onLoopCompleted({ loopId }) {
+		this.#loopState.delete(loopId);
+	}
+
+	#onTurnStarted({ rummy }) {
+		const state = this.#loopState.get(rummy.loopId);
+		state.turnErrors = 0;
+	}
+
+	async #onErrorLog({
+		store,
+		runId,
+		turn,
+		loopId,
+		message,
+		status,
+		attributes,
+	}) {
+		const statusValue = status ?? 400;
+		const path = await store.logPath(runId, turn, "error", message);
+		await store.set({
+			runId,
+			turn,
+			path,
+			body: message,
+			state: "failed",
+			outcome: `status:${statusValue}`,
+			loopId,
+			attributes: { ...attributes, status: statusValue },
+		});
+		const state = this.#loopState.get(loopId);
+		if (state) state.turnErrors++;
+	}
+
+	async #verdict({ store, runId, loopId, turn, 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,
+				});
+			}
+		}
+
+		const struck = state.turnErrors > 0;
+
+		if (summaryText && !struck) {
+			state.streak = 0;
+			const updateEntry = recorded?.findLast?.((e) => e.scheme === "update");
+			const terminalStatus = updateEntry?.attributes?.status ?? 200;
+			return { continue: false, status: terminalStatus };
+		}
+
+		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.
+				if (summaryText) {
+					state.streak = 0;
+					const updateEntry = recorded?.findLast?.(
+						(e) => e.scheme === "update",
+					);
+					const terminalStatus = updateEntry?.attributes?.status ?? 200;
+					return { continue: false, status: terminalStatus };
+				}
+				return {
+					continue: false,
+					status: 499,
+					reason:
+						cycleReason ||
+						`Abandoned after ${state.streak} consecutive strikes.`,
+				};
+			}
+			return {
+				continue: true,
+				reason: cycleReason || CONTRACT_REMINDER,
+			};
+		}
+
+		state.streak = 0;
+		return { continue: true };
+	}
+}

package/src/plugins/file/README.md

@@ -1,4 +1,4 @@
-# file
+# file {#file_plugin}
 
 Owns file-related projections and file constraint management.
 
@@ -13,10 +13,10 @@ Owns file-related projections and file constraint management.
 
 Static methods `setConstraint` and `dropConstraint` manage per-project
 file constraints in the database. Constraints are project-level config
-(backbone), not tool dispatch. See SPEC.md §2.3.
+(backbone), not tool dispatch. See [file_constraints](../../../SPEC.md#file_constraints).
 
-- `active` / `readonly` — promoted into context.
-- `ignore` — excluded from scans; demotes existing entries.
+- `active` / `readonly` — promoted into context (visibility=visible).
+- `ignore` — excluded from scans; summarizes existing entries.
 
-Entry promotion/demotion from constraints goes through the standard
-tool handler chain via `dispatchTool`.
+Promotion/demotion from constraints goes through the standard tool
+handler chain via `dispatchTool`.

package/src/plugins/file/file.js

@@ -16,8 +16,8 @@ export default class File {
 		this.#core = core;
 		// "file" scheme covers bare paths (scheme IS NULL in DB)
 		core.registerScheme({ category: "data" });
-		core.on("promoted", this.full.bind(this));
-		core.on("demoted", this.summary.bind(this));
+		core.on("visible", this.full.bind(this));
+		core.on("summarized", this.summary.bind(this));
 	}
 
 	full(entry) {
@@ -59,6 +59,19 @@ 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.
+	 */
+	static async isReadonly(db, projectId, path) {
+		const rows = await db.get_file_constraints.all({ project_id: projectId });
+		const { hedmatch } = await import("./../hedberg/patterns.js");
+		return rows.some(
+			(r) => r.visibility === "readonly" && hedmatch(r.pattern, path),
+		);
+	}
 }
 
 async function normalizePath(db, projectId, path) {

package/src/plugins/get/README.md

@@ -1,4 +1,4 @@
-# get
+# get {#get_plugin}
 
 Retrieves and promotes entries by path or glob pattern.
 

package/src/plugins/get/get.js

@@ -1,4 +1,4 @@
-import KnownStore from "../../agent/KnownStore.js";
+import Entries from "../../agent/Entries.js";
 import { storePatternResult } from "../helpers.js";
 import docs from "./getDoc.js";
 
@@ -9,8 +9,8 @@ export default class Get {
 		this.#core = core;
 		core.registerScheme();
 		core.on("handler", this.handler.bind(this));
-		core.on("promoted", this.full.bind(this));
-		core.on("demoted", this.summary.bind(this));
+		core.on("visible", this.full.bind(this));
+		core.on("summarized", this.summary.bind(this));
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.get = docs;
 			return docsMap;
@@ -21,21 +21,34 @@ export default class Get {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const target = entry.attributes.path;
 		if (!target) {
-			await store.upsert(runId, turn, entry.resultPath, "", 400, {
-				attributes: { error: "path is required" },
+			// 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,
+				runId,
+				turn,
 				loopId,
+				message:
+					'Missing required "path" attribute on <get>. Use <get path="..."/>.',
+				status: 400,
 			});
 			return;
 		}
-		const normalized = KnownStore.normalizePath(target);
-		const bodyFilter = entry.attributes.body || null;
+		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 isPattern = bodyFilter || normalized.includes("*");
 
-		const line =
-			entry.attributes.line != null
-				? Math.max(1, parseInt(entry.attributes.line, 10))
-				: null;
+		// 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.
+		const lineRaw = entry.attributes.line;
+		const line = lineRaw != null ? parseInt(lineRaw, 10) : null;
 		const limit =
 			entry.attributes.limit != null
 				? Math.max(1, parseInt(entry.attributes.limit, 10))
@@ -48,7 +61,7 @@ export default class Get {
 		);
 
 		// Preview — list matches with their full-body token costs. No promotion,
-		// no fidelity change, no Token Budget spent. Model uses this to plan
+		// 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.
@@ -66,62 +79,91 @@ export default class Get {
 			return;
 		}
 
-		// Partial read — no fidelity promotion, returns a line slice as the log item.
+		// Partial read — no visibility promotion, returns a line slice as the log item.
 		if (line !== null || limit !== null) {
 			if (isPattern) {
-				await store.upsert(
+				await store.set({
 					runId,
 					turn,
-					entry.resultPath,
-					"line/limit requires a single path, not a glob or body filter",
-					400,
-					{ loopId, attributes: { path: target } },
-				);
+					path: entry.resultPath,
+					body: "line/limit requires a single path, not a glob or body filter",
+					state: "failed",
+					outcome: "validation",
+					loopId,
+					attributes: { path: target },
+				});
 				return;
 			}
 			if (matches.length === 0) {
-				await store.upsert(
+				await store.set({
 					runId,
 					turn,
-					entry.resultPath,
-					`${target} not found`,
-					200,
-					{ loopId, attributes: { path: target } },
-				);
+					path: entry.resultPath,
+					body: `${target} not found`,
+					state: "resolved",
+					loopId,
+					attributes: { path: target },
+				});
 				return;
 			}
 			const allLines = matches[0].body.split("\n");
 			const total = allLines.length;
-			const startLine = line ?? 1;
+			// 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
+					: line < 0
+						? Math.max(1, total + line + 1)
+						: Math.max(1, line);
 			const startIdx = startLine - 1;
 			const endIdx = limit !== null ? Math.min(startIdx + limit, total) : total;
 			const slice = allLines.slice(startIdx, endIdx).join("\n");
 			const endLine = endIdx;
-			const header = `[lines ${startLine}–${endLine} / ${total} total]`;
-			await store.upsert(
+			// 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,
 				turn,
-				entry.resultPath,
-				`${header}\n${slice}`,
-				200,
-				{ loopId, attributes: { path: target } },
-			);
+				path: entry.resultPath,
+				body: `${header}\n${slice}`,
+				state: "resolved",
+				loopId,
+				attributes: {
+					path: target,
+					lineStart: startLine,
+					lineEnd: endLine,
+					totalLines: total,
+				},
+			});
 			return;
 		}
 
-		const VALID_FIDELITY = {
-			demoted: 1,
-			promoted: 1,
+		const VALID_VISIBILITY = {
+			summarized: 1,
+			visible: 1,
 			archived: 1,
 		};
-		const fidelityAttr = VALID_FIDELITY[entry.attributes.fidelity]
-			? entry.attributes.fidelity
+		const visibilityAttr = VALID_VISIBILITY[entry.attributes.visibility]
+			? entry.attributes.visibility
 			: null;
 
-		await store.promoteByPattern(runId, normalized, bodyFilter, turn);
-		if (fidelityAttr) {
+		await store.get({
+			runId: runId,
+			turn: turn,
+			path: normalized,
+			bodyFilter: bodyFilter,
+		});
+		if (visibilityAttr) {
 			for (const match of matches)
-				await store.setFidelity(runId, match.path, fidelityAttr);
+				await store.set({
+					runId: runId,
+					path: match.path,
+					visibility: visibilityAttr,
+				});
 		}
 
 		if (isPattern) {
@@ -135,14 +177,27 @@ export default class Get {
 				matches,
 				{ loopId, attributes: { path: target } },
 			);
+		} else if (matches.length === 0) {
+			await store.set({
+				runId,
+				turn,
+				path: entry.resultPath,
+				body: `${target} not found`,
+				state: "resolved",
+				loopId,
+				attributes: { path: target },
+			});
 		} else {
-			const total = matches.reduce((s, m) => s + m.tokens, 0);
-			const paths = matches.map((m) => m.path).join(", ");
-			const body =
-				matches.length > 0
-					? `${paths} promoted (${total} tokens)`
-					: `${target} not found`;
-			await store.upsert(runId, turn, entry.resultPath, body, 200, {
+			// 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.
+			await store.set({
+				runId,
+				turn,
+				path: entry.resultPath,
+				body: `${target} promoted`,
+				state: "resolved",
 				loopId,
 				attributes: { path: target },
 			});

package/src/plugins/get/getDoc.js

@@ -1,33 +1,3 @@
-// Tool doc for <get>. Each entry: [text, rationale].
-// Text goes to the model. Rationale stays in source.
-// Changing ANY line requires reading ALL rationales first.
-const LINES = [
-  ["## <get>[path/to/file]</get> - Promote an entry"],
-  ["Example: <get>src/app.js</get>", "Simplest form. Body = path."],
-  [
-    'Example: <get path="known://*">auth</get>',
-    "Keyword recall: glob in path, search term in body.",
-  ],
-  [
-    'Example: <get path="src/**/*.js">authentication</get>',
-    "Full pattern: recursive glob + content filter.",
-  ],
-  [
-    'Example: <get path="src/agent/AgentLoop.js" line="644" limit="80"/>',
-    "Partial read. Returns lines 644–723 without promoting.",
-  ],
-  [
-    "* Paths accept patterns: `src/**/*.js`, `known://api_*`",
-    "Reinforces picomatch patterns work everywhere.",
-  ],
-  [
-    "* Body text filters results by content match",
-    "Body = filter, not just path.",
-  ],
-  [
-    "* `line` and `limit` read a slice without promoting the entry, which costs as many tokens as the slice contains.",
-    "Partial read is safe: context budget unaffected.",
-  ],
-];
+import { loadDoc } from "../helpers.js";
 
-export default LINES.map(([text]) => text).join("\n");
+export default loadDoc(import.meta.url, "getDoc.md");

package/src/plugins/get/getDoc.md

@@ -0,0 +1,36 @@
+## <get>[path/to/file]</get> - Promote an entry
+
+Example: <get>src/app.js</get>
+<!-- Simplest form. Body = path. -->
+
+Example: <get path="known://*">auth</get>
+<!-- Keyword recall: glob in path, search term in body. -->
+
+Example: <get path="src/**/*.js">authentication</get>
+<!-- Full pattern: recursive glob + content filter. -->
+
+Example: <get path="src/**/*.js" preview>authentication</get>
+<!-- Full pattern: recursive glob + content filter. -->
+
+Example: <get path="src/agent/AgentLoop.js" line="644" limit="80"/>
+<!-- Partial read. Returns lines 644–723 without promoting. -->
+
+Example: <get path="sh://turn_3/npm_test_1" line="-50"/>
+<!-- Tail: negative line reads the last 50 lines. Works on any growing entry — streaming sh output, logs, knowns. -->
+
+Example: <get path="https://en.wikipedia.org/wiki/Long_Page" line="1" limit="200"/>
+<!-- URL partial read. When a page is too large to promote whole, read a slice. Pattern generalizes to every scheme. -->
+
+* Paths accept patterns: `src/**/*.js`, `known://api_*`
+<!-- Reinforces picomatch patterns work everywhere. -->
+
+* Body text filters results by content match (can use glob, regex, jsonpath, or xpath patterns)
+<!-- Body = filter, not just path. -->
+
+* `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. -->
+
+* Remember to <set path="..." visibility="summarize"/> when entries or log events are no longer relevant.

package/src/plugins/hedberg/README.md

@@ -1,4 +1,4 @@
-# hedberg
+# hedberg {#hedberg_plugin}
 
 The interpretation boundary between stochastic model output and
 deterministic system operations.
@@ -26,7 +26,6 @@ constructor(core) {
 | `replace(body, search, replacement, opts?)` | Apply replacement (sed regex → literal → heuristic) |
 | `parseSed(input)` | Parse sed syntax into `[{ search, replace, flags, sed }]` |
 | `parseEdits(content)` | Detect edit format (merge conflict, udiff, Claude XML) |
-| `normalizeAttrs(attrs)` | Heal model attribute names (value→body, unknown→path) |
 | `generatePatch(path, old, new)` | Generate unified diff |
 
 ### Hedberg.replace(body, search, replacement, options?)