@possumtech/rummy 0.3.1 → 0.5.0

package/src/plugins/set/set.js

@@ -4,7 +4,7 @@ import Hedberg, { generatePatch } from "../hedberg/hedberg.js";
 import { storePatternResult } from "../helpers.js";
 import docs from "./setDoc.js";
 
-const VALID_FIDELITY = { archive: 1, summary: 1, index: 1, full: 1 };
+const VALID_FIDELITY = { archived: 1, demoted: 1, promoted: 1 };
 
 // biome-ignore lint/suspicious/noShadowRestrictedNames: tool name is "set"
 export default class Set {
@@ -14,8 +14,8 @@ export default class Set {
 		this.#core = core;
 		core.registerScheme();
 		core.on("handler", this.handler.bind(this));
-		core.on("full", this.full.bind(this));
-		core.on("summary", this.summary.bind(this));
+		core.on("promoted", this.full.bind(this));
+		core.on("demoted", this.summary.bind(this));
 		core.on("turn.proposing", this.#materializeRevisions.bind(this));
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.set = docs;
@@ -26,47 +26,18 @@ export default class Set {
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const attrs = entry.attributes;
-
-		// Fidelity control: <set path="..." fidelity="archive"/>
 		const fidelityAttr = VALID_FIDELITY[attrs.fidelity] ? attrs.fidelity : null;
-		if (fidelityAttr && attrs.path) {
+		const rawSummary = typeof attrs.summary === "string" ? attrs.summary : null;
+		const summaryText = rawSummary ? rawSummary.slice(0, 80) : null;
+
+		// Pure fidelity/metadata change — no body content
+		if (!entry.body && fidelityAttr && attrs.path) {
 			const target = attrs.path;
-			const rawSummary =
-				typeof attrs.summary === "string" ? attrs.summary : null;
-			const summaryText = rawSummary ? rawSummary.slice(0, 80) : null;
 			const matches = await store.getEntriesByPattern(
 				runId,
 				target,
 				attrs.body,
 			);
-			if (entry.body) {
-				// Write content directly at specified fidelity
-				const entryAttrs = summaryText ? { summary: summaryText } : null;
-				for (const match of matches) {
-					await store.upsert(runId, turn, match.path, entry.body, 200, {
-						fidelity: fidelityAttr,
-						attributes: entryAttrs,
-						loopId,
-					});
-				}
-				if (matches.length === 0) {
-					await store.upsert(runId, turn, target, entry.body, 200, {
-						fidelity: fidelityAttr,
-						attributes: entryAttrs,
-						loopId,
-					});
-				}
-			} else {
-				// No body — change fidelity, attach summary if provided
-				for (const match of matches) {
-					await store.setFidelity(runId, match.path, fidelityAttr);
-					if (summaryText) {
-						await store.setAttributes(runId, match.path, {
-							summary: summaryText,
-						});
-					}
-				}
-			}
 			if (matches.length === 0) {
 				await store.upsert(
 					runId,
@@ -74,35 +45,35 @@ export default class Set {
 					entry.resultPath,
 					`${target} not found`,
 					404,
-					{
-						fidelity: "archive",
-						loopId,
-					},
+					{ fidelity: "archived", loopId },
 				);
 				return;
 			}
-			const label =
-				fidelityAttr === "archive" ? "archived" : `set to ${fidelityAttr}`;
+			for (const match of matches) {
+				await store.setFidelity(runId, match.path, fidelityAttr);
+				if (summaryText) {
+					await store.setAttributes(runId, match.path, {
+						summary: summaryText,
+					});
+				}
+			}
+			const label = `set to ${fidelityAttr}`;
 			await store.upsert(
 				runId,
 				turn,
 				entry.resultPath,
 				`${matches.map((m) => m.path).join(", ")} ${label}`,
 				200,
-				{
-					fidelity: "archive",
-					loopId,
-				},
+				{ fidelity: "archived", loopId },
 			);
 			return;
 		}
 
+		// Edit: sed patterns or SEARCH/REPLACE blocks
 		if (attrs.blocks || attrs.search != null) {
 			await this.#processEdit(rummy, entry, attrs);
-			return;
-		}
-
-		if (attrs.preview && attrs.path) {
+		} else if (attrs.preview && attrs.path) {
+			// Preview
 			const matches = await store.getEntriesByPattern(
 				runId,
 				attrs.path,
@@ -119,43 +90,68 @@ export default class Set {
 				{ preview: true, loopId },
 			);
 			return;
-		}
+		} else {
+			// Write content
+			const target = attrs.path;
+			if (!target) return;
 
-		const target = attrs.path;
-		if (!target) return;
+			const scheme = KnownStore.scheme(target);
+			if (scheme === null) {
+				// File write — diff against existing content
+				const existing = await store.getBody(runId, target);
+				const oldContent = existing ?? "";
+				const newContent = entry.body || "";
+				const udiff = generatePatch(target, oldContent, newContent);
+				const merge = oldContent
+					? `<<<<<<< SEARCH\n${oldContent}\n=======\n${newContent}\n>>>>>>> REPLACE`
+					: `<<<<<<< SEARCH\n=======\n${newContent}\n>>>>>>> REPLACE`;
+				await store.upsert(runId, turn, entry.resultPath, oldContent, 202, {
+					attributes: { file: target, patch: udiff, merge },
+					loopId,
+				});
+			} else if (attrs.filter || target.includes("*")) {
+				// Pattern update
+				const matches = await store.getEntriesByPattern(
+					runId,
+					target,
+					attrs.filter,
+				);
+				await store.updateBodyByPattern(
+					runId,
+					target,
+					attrs.filter || null,
+					entry.body,
+				);
+				await storePatternResult(
+					store,
+					runId,
+					turn,
+					"set",
+					target,
+					attrs.filter,
+					matches,
+					{ loopId },
+				);
+			} else {
+				// Direct scheme write
+				await store.upsert(runId, turn, target, entry.body, 200, {
+					fidelity: fidelityAttr || "promoted",
+					attributes: summaryText ? { summary: summaryText } : null,
+					loopId,
+				});
+			}
+		}
 
-		const scheme = KnownStore.scheme(target);
-		if (scheme === null) {
-			const udiff = generatePatch(target, "", entry.body || "");
-			const merge = `<<<<<<< SEARCH\n=======\n${entry.body || ""}\n>>>>>>> REPLACE`;
-			await store.upsert(runId, turn, entry.resultPath, "", 202, {
-				attributes: { file: target, patch: udiff, merge },
-				loopId,
-			});
-		} else if (attrs.filter || target.includes("*")) {
-			const matches = await store.getEntriesByPattern(
-				runId,
-				target,
-				attrs.filter,
-			);
-			await store.updateBodyByPattern(
-				runId,
-				target,
-				attrs.filter || null,
-				entry.body,
-			);
-			await storePatternResult(
-				store,
-				runId,
-				turn,
-				"set",
-				target,
-				attrs.filter,
-				matches,
-				{ loopId },
-			);
-		} else {
-			await store.upsert(runId, turn, target, entry.body, 200, { loopId });
+		// Apply fidelity after all write operations
+		if (fidelityAttr && attrs.path) {
+			const target = attrs.path;
+			const scheme = KnownStore.scheme(target);
+			if (scheme !== null) {
+				await store.setFidelity(runId, target, fidelityAttr);
+			}
+			if (summaryText) {
+				await store.setAttributes(runId, target, { summary: summaryText });
+			}
 		}
 	}
 
@@ -171,8 +167,8 @@ export default class Set {
 		return `# set ${file}${tokens}\n${attrs.merge}`;
 	}
 
-	summary(entry) {
-		return entry.attributes.merge || "";
+	summary() {
+		return "";
 	}
 
 	async #processEdit(rummy, entry, attrs) {
@@ -215,7 +211,7 @@ export default class Set {
 				searchText != null
 					? `<<<<<<< SEARCH\n${searchText}\n=======\n${replaceText}\n>>>>>>> REPLACE`
 					: null;
-			const beforeTokens = match.tokens_full || 0;
+			const beforeTokens = match.tokens || 0;
 			const afterTokens = patch ? countTokens(patch) : beforeTokens;
 
 			await store.upsert(runId, turn, resultPath, match.body, status, {
@@ -282,7 +278,7 @@ export default class Set {
 					? generatePatch(filePath, original, current)
 					: null;
 			const merge = mergeBlocks.length > 0 ? mergeBlocks.join("\n") : null;
-			const beforeTokens = fileEntry[0].tokens_full || 0;
+			const beforeTokens = fileEntry[0].tokens || 0;
 			const afterTokens = current ? countTokens(current) : beforeTokens;
 
 			await store.upsert(runId, turn, entry.path, original, state, {
@@ -334,7 +330,6 @@ export default class Set {
 					flags: block.flags,
 				});
 			}
-			// Multi-block: apply sequentially, no per-hunk merge notation
 			let current = body;
 			let lastWarning = null;
 			for (const block of attrs.blocks) {

package/src/plugins/set/setDoc.js

@@ -2,48 +2,35 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: path attr + body = edit content
-	['## <set path="[path/to/file]">[edit]</set> - Edit a file or entry'],
-
-	// --- Examples: sed, SEARCH/REPLACE, fidelity control
-	[
-		'Example: <set path="src/config.js">s/port = 3000/port = 8080/g</set>',
-		"Sed syntax: most common edit pattern. Shows s/old/new/ with g flag.",
-	],
-	[
-		`Example: <set path="src/app.js"><<<<<<< SEARCH
-// TODO: add error handling
+  [
+    '## <set path="[path/to/file]">[content or edit]</set> - Create, edit, or update a file or entry',
+  ],
+  [
+    'Example: <set path="known://project/milestones" fidelity="demoted" summary="milestone,deadline,2026"/>',
+    "Fidelity control first — most unique capability of set.",
+  ],
+  [
+    `Example: <set path="src/app.js">
+<<<<<<< SEARCH
+old text
 =======
-// error handler configured
->>>>>>> REPLACE</set>`,
-		"SEARCH/REPLACE block: literal match and replace. Use when sed escaping is complex.",
-	],
-	[
-		'Example: <set path="known://project/milestones" fidelity="summary" summary="milestone,deadline,2026"/> ... <set path="prompt://3" fidelity="index"/>',
-		"Fidelity control: compress a known entry to keywords, demote a previous prompt to index-only. Both free context while keeping paths visible.",
-	],
-
-	// --- Constraints
-	[
-		'* `fidelity="..."`: `archive`, `summary`, `index`, `full`',
-		"Fidelity control. Archive removes from context but preserves for retrieval.",
-	],
-	[
-		'* `fidelity="summary"` HIDES the body — does NOT require reading or compressing content. Write any short keyword label you already know.',
-		"M-10 fix: model was reading files before compressing to summary, believing it needed semantic content. It does not. The body is preserved on disk; only context visibility changes.",
-	],
-	[
-		'* `summary="..."` (<= 80 chars) persists across fidelity changes',
-		"Model-authored descriptions survive demotion. No janitorial pass needed.",
-	],
-	[
-		"* YOU MUST NOT use <sh/> or <env/> to read, create, or edit files",
-		"Forces file operations through set/get. Prevents untracked mutations.",
-	],
-	[
-		"* Editing: s/old/new/ sed patterns and literal SEARCH/REPLACE blocks",
-		"Both syntaxes supported. Hedberg normalizes either form.",
-	],
+new text
+>>>>>>> REPLACE
+</set>`,
+    "SEARCH/REPLACE block — primary edit pattern for existing files.",
+  ],
+  [
+    `Example: <set path="src/config.js">s/port = 3000/port = 8080/g;s/We're almost done/We're done./g;</set>`,
+    "Sed syntax: chained s/old/new/ patterns with semicolons.",
+  ],
+  [
+    'Example: <set path="example.md">Full file content here</set>',
+    "Create: body contents are entire file.",
+  ],
+  [
+    "* YOU MUST NOT use <sh></sh> or <env></env> to list, create, read, or edit files — use <get></get> and <set></set>",
+    "Reinforces at the decision point — model reading setDoc for file ops sees the prohibition here, not just buried in shDoc/envDoc which it may not be reading.",
+  ],
 ];
 
 export default LINES.map(([text]) => text).join("\n");

package/src/plugins/sh/sh.js

@@ -7,8 +7,8 @@ export default class Sh {
 		this.#core = core;
 		core.registerScheme();
 		core.on("handler", this.handler.bind(this));
-		core.on("full", this.full.bind(this));
-		core.on("summary", this.summary.bind(this));
+		core.on("promoted", this.full.bind(this));
+		core.on("demoted", this.summary.bind(this));
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.sh = docs;
 			return docsMap;
@@ -27,7 +27,7 @@ export default class Sh {
 		return `# sh ${entry.attributes.command || ""}\n${entry.body}`;
 	}
 
-	summary(entry) {
-		return entry.attributes.command || "";
+	summary() {
+		return "";
 	}
 }

package/src/plugins/sh/shDoc.js

@@ -2,26 +2,21 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax
 	["## <sh>[command]</sh> - Run a shell command with side effects"],
-
-	// --- Examples: install and test — real mutations
 	[
 		"Example: <sh>npm install express</sh>",
-		"Package install. Shows a real side-effect command.",
+		"Package install. Real side-effect command.",
 	],
 	[
 		"Example: <sh>npm test</sh>",
 		"Test execution. Another common side-effect action.",
 	],
-
-	// --- Constraints
 	[
-		"* YOU MUST NOT use <sh/> to read, create, or edit files — use <get/> and <set/>",
-		"Forces file operations through the entry system. Prevents untracked mutations.",
+		"* YOU MUST NOT use <sh></sh> to read, create, or edit files — use <get></get> and <set></set>",
+		"Forces file operations through the entry system.",
 	],
 	[
-		"* YOU MUST use <env/> for commands without side effects",
+		"* YOU MUST use <env></env> for commands without side effects",
 		"Reinforces the env/sh split. Read = env, mutate = sh.",
 	],
 ];

package/src/plugins/skill/skill.js

@@ -10,7 +10,8 @@ export default class Skill {
 			name: "skill",
 			category: "data",
 		});
-		core.hooks.tools.onView("skill", (entry) => entry.body);
+		core.hooks.tools.onView("skill", (entry) => entry.body, "promoted");
+		core.hooks.tools.onView("skill", () => "", "demoted");
 
 		const r = core.hooks.rpc.registry;
 

package/src/plugins/summarize/summarize.js

@@ -7,14 +7,21 @@ export default class Summarize {
 		this.#core = core;
 		core.ensureTool();
 		core.registerScheme({ category: "logging" });
-		core.on("full", this.full.bind(this));
-		core.on("summary", this.summary.bind(this));
+		core.on("handler", this.handler.bind(this));
+		core.on("promoted", this.full.bind(this));
+		core.on("demoted", this.summary.bind(this));
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.summarize = docs;
 			return docsMap;
 		});
 	}
 
+	async handler(entry, rummy) {
+		const { entries: store, sequence: turn, runId, loopId } = rummy;
+		const statusPath = await store.slugPath(runId, "summarize", entry.body);
+		await store.upsert(runId, turn, statusPath, entry.body, 200, { loopId });
+	}
+
 	full(entry) {
 		return `# summarize\n${entry.body}`;
 	}

package/src/plugins/summarize/summarizeDoc.js

@@ -2,31 +2,25 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax
-	["## <summarize>[answer or summary]</summarize> - Signal completion"],
-
-	// --- Examples: answer and task completion
 	[
-		"Example: <summarize>The port is 8080</summarize>",
-		"Direct answer. Shows summarize as the vehicle for delivering answers.",
+		"## <summarize>[answer or final summary]</summarize> - Terminate the run with the final answer",
+		"Header teaches consequence (run ends), not just label. Model now knows emitting this stops everything.",
 	],
 	[
-		"Example: <summarize>Installed express, updated config</summarize>",
-		"Task summary. Shows summarize for action completion.",
+		"Example: <summarize>The port is 8080</summarize>",
+		"Direct answer. Summarize delivers answers.",
 	],
-
-	// --- Constraints: RFC-style MUST/MUST NOT
 	[
-		"* YOU MUST use <summarize> when done — describes the final state",
-		"Completion signal. Without this, the loop continues indefinitely.",
+		"* Urgent: <summarize></summarize> ENDS THE RUN. After this, no more turns happen.",
+		"Direct statement of terminal behavior — the model treating summarize as a generic 'done message' was causing zombie-update loops (model unsure if truly finished, defaulted to update).",
 	],
 	[
-		"* YOU MUST NOT use <summarize> if still working — use <update/> instead",
-		"Mutual exclusion with update. Prevents premature completion.",
+		"* Urgent: YOU MUST NOT include <summarize></summarize> with other tools. Termination is a deliberate, isolated act — not a side effect of a turn doing other things.",
+		"Prior 'they might fail' rationale was argued around (when set on known:// succeeds, model rationalized bundling). Reframing as architectural ('termination is deliberate') removes the argument surface.",
 	],
 	[
-		"* YOU MUST keep <summarize> to <= 80 characters",
-		"Length cap. Matches the summary attribute constraint. Prevents verbose output.",
+		"* YOU MUST keep <summarize></summarize> to <= 80 characters",
+		"Length cap.",
 	],
 ];
 

package/src/plugins/telemetry/telemetry.js

@@ -1,17 +1,23 @@
-import { writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 export default class Telemetry {
 	#core;
 	#starts = new Map();
 	#lastRunPath = null;
+	#turnsDir = null;
 	#turnLog = [];
+	#currentRunAlias = null;
+	#currentTurn = null;
 
 	constructor(core) {
 		this.#core = core;
 
 		const home = process.env.RUMMY_HOME;
-		if (home) this.#lastRunPath = join(home, "last_run.txt");
+		if (home) {
+			this.#lastRunPath = join(home, "last_run.txt");
+			this.#turnsDir = join(home, "turns");
+		}
 
 		core.on("rpc.started", this.#onRpcStarted.bind(this));
 		core.on("rpc.completed", this.#onRpcCompleted.bind(this));
@@ -85,20 +91,20 @@ export default class Telemetry {
 		// assistant://N — the model's raw response
 		await store.upsert(runId, turn, `assistant://${turn}`, content, 200, {
 			loopId,
-			fidelity: "archive",
+			fidelity: "archived",
 		});
 
 		// system://N, user://N — assembled messages as audit
 		if (systemMsg) {
 			await store.upsert(runId, turn, `system://${turn}`, systemMsg, 200, {
 				loopId,
-				fidelity: "archive",
+				fidelity: "archived",
 			});
 		}
 		if (userMsg) {
 			await store.upsert(runId, turn, `user://${turn}`, userMsg, 200, {
 				loopId,
-				fidelity: "archive",
+				fidelity: "archived",
 			});
 		}
 
@@ -115,7 +121,7 @@ export default class Telemetry {
 				model: result.model || null,
 			}),
 			200,
-			{ loopId, fidelity: "archive" },
+			{ loopId, fidelity: "archived" },
 		);
 
 		// reasoning://N
@@ -126,15 +132,18 @@ export default class Telemetry {
 				`reasoning://${turn}`,
 				responseMessage.reasoning_content,
 				200,
-				{ loopId, fidelity: "archive" },
+				{ loopId, fidelity: "archived" },
 			);
 		}
 
-		// content://N — unparsed text
+		// content://N — unparsed text. 400 Bad Request because anything in
+		// unparsed is text the parser couldn't dispatch (malformed XML, native
+		// tool call attempts, reasoning bleed). Visible to the model so it
+		// sees the rejection on its next turn and can correct.
 		if (unparsed) {
-			await store.upsert(runId, turn, `content://${turn}`, unparsed, 200, {
+			await store.upsert(runId, turn, `content://${turn}`, unparsed, 400, {
 				loopId,
-				fidelity: "archive",
+				fidelity: "promoted",
 			});
 		}
 
@@ -168,8 +177,10 @@ export default class Telemetry {
 	}
 
 	async #logMessages(messages, context) {
+		this.#currentRunAlias = context.runAlias || `run_${context.runId}`;
+		this.#currentTurn = context.turn ?? null;
 		this.#turnLog.push(
-			`\n${"=".repeat(60)}\nTURN — model=${context.model} run=${context.runId}\n${"=".repeat(60)}`,
+			`\n${"=".repeat(60)}\nTURN ${this.#currentTurn ?? "?"} — model=${context.model} run=${this.#currentRunAlias}\n${"=".repeat(60)}`,
 		);
 		for (const msg of messages) {
 			const label = msg.role.toUpperCase();
@@ -191,6 +202,7 @@ export default class Telemetry {
 		const usage = response.usage || {};
 		this.#turnLog.push(`\n--- USAGE ---\n${JSON.stringify(usage)}`);
 		this.#flush();
+		this.#writeTurnFile();
 		return response;
 	}
 
@@ -200,4 +212,17 @@ export default class Telemetry {
 			() => {},
 		);
 	}
+
+	async #writeTurnFile() {
+		if (!this.#turnsDir || !this.#currentRunAlias || this.#currentTurn == null)
+			return;
+		const runDir = join(this.#turnsDir, this.#currentRunAlias);
+		try {
+			await mkdir(runDir, { recursive: true });
+			const fileName = `turn_${String(this.#currentTurn).padStart(3, "0")}.txt`;
+			await writeFile(join(runDir, fileName), `${this.#turnLog.join("\n")}\n`);
+		} catch {
+			// best effort — diagnostic feature, don't fail the turn
+		}
+	}
 }

package/src/plugins/think/think.js

@@ -1,5 +1,18 @@
+import docs from "./thinkDoc.js";
+
+const THINK_ENABLED = process.env.RUMMY_THINK;
+if (THINK_ENABLED === undefined)
+	throw new Error("RUMMY_THINK must be set (1 or 0)");
+
 export default class Think {
 	constructor(core) {
 		core.registerScheme({ modelVisible: 0, category: "logging" });
+		if (THINK_ENABLED === "1") {
+			core.ensureTool();
+			core.filter("instructions.toolDocs", async (docsMap) => {
+				docsMap.think = docs;
+				return docsMap;
+			});
+		}
 	}
 }

package/src/plugins/think/thinkDoc.js

@@ -0,0 +1,16 @@
+// Tool doc for <think/>. Each entry: [text, rationale].
+// Text goes to the model. Rationale stays in source.
+// Changing ANY line requires reading ALL rationales first.
+const LINES = [
+	["## <think>[reasoning]</think> - Think before acting"],
+	[
+		"* Use <think></think> before any other tools to plan your approach",
+		"Positioning: think first, then act. Prevents degenerate tool-call storms.",
+	],
+	[
+		"* Reasoning inside <think></think> is private — it does not appear in your context",
+		"Frees the model to reason without consuming context budget.",
+	],
+];
+
+export default LINES.map(([text]) => text).join("\n");