@possumtech/rummy 0.4.0 → 0.5.0

package/src/plugins/rpc/rpc.js

@@ -111,7 +111,7 @@ export default class Rpc {
 				});
 				return { status: "ok" };
 			},
-			description: "Promote entry to full state.",
+			description: "Promote entry fidelity.",
 			params: {
 				path: "string — file path or glob pattern",
 				run: "string — run alias",

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, 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;
@@ -27,8 +27,7 @@ export default class Set {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const attrs = entry.attributes;
 		const fidelityAttr = VALID_FIDELITY[attrs.fidelity] ? attrs.fidelity : null;
-		const rawSummary =
-			typeof attrs.summary === "string" ? attrs.summary : null;
+		const rawSummary = typeof attrs.summary === "string" ? attrs.summary : null;
 		const summaryText = rawSummary ? rawSummary.slice(0, 80) : null;
 
 		// Pure fidelity/metadata change — no body content
@@ -46,7 +45,7 @@ export default class Set {
 					entry.resultPath,
 					`${target} not found`,
 					404,
-					{ fidelity: "archive", loopId },
+					{ fidelity: "archived", loopId },
 				);
 				return;
 			}
@@ -58,15 +57,14 @@ export default class Set {
 					});
 				}
 			}
-			const label =
-				fidelityAttr === "archive" ? "archived" : `set to ${fidelityAttr}`;
+			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;
 		}
@@ -137,7 +135,7 @@ export default class Set {
 			} else {
 				// Direct scheme write
 				await store.upsert(runId, turn, target, entry.body, 200, {
-					fidelity: fidelityAttr || "full",
+					fidelity: fidelityAttr || "promoted",
 					attributes: summaryText ? { summary: summaryText } : null,
 					loopId,
 				});
@@ -169,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) {

package/src/plugins/set/setDoc.js

@@ -6,7 +6,7 @@ const LINES = [
     '## <set path="[path/to/file]">[content or edit]</set> - Create, edit, or update a file or entry',
   ],
   [
-    'Example: <set path="known://project/milestones" fidelity="summary" summary="milestone,deadline,2026"/>',
+    'Example: <set path="known://project/milestones" fidelity="demoted" summary="milestone,deadline,2026"/>',
     "Fidelity control first — most unique capability of set.",
   ],
   [
@@ -20,7 +20,7 @@ new text
     "SEARCH/REPLACE block — primary edit pattern for existing files.",
   ],
   [
-    'Example: <set path="src/config.js">s/port = 3000/port = 8080/g;s/host = 127.0.0.1/host = localhost/g;</set>',
+    `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.",
   ],
   [
@@ -28,8 +28,8 @@ new text
     "Create: body contents are entire file.",
   ],
   [
-    "* YOU MUST NOT use <sh/> or <env/> to list, create, read, or edit files. Use the Tool Commands.",
-    "Forces file operations through set/get.",
+    "* 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.",
   ],
 ];
 

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

@@ -12,11 +12,11 @@ const LINES = [
 		"Test execution. Another common side-effect action.",
 	],
 	[
-		"* YOU MUST NOT use <sh/> to read, create, or edit files — use <get/> and <set/>",
+		"* 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

@@ -8,8 +8,8 @@ export default class Summarize {
 		core.ensureTool();
 		core.registerScheme({ category: "logging" });
 		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.summarize = docs;
 			return docsMap;

package/src/plugins/summarize/summarizeDoc.js

@@ -2,25 +2,24 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	["## <summarize>[answer or summary]</summarize> - Signal completion"],
 	[
-		"Example: <summarize>The port is 8080</summarize>",
-		"Direct answer. Summarize delivers 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. Action completion.",
+		"Example: <summarize>The port is 8080</summarize>",
+		"Direct answer. Summarize delivers answers.",
 	],
 	[
-		"* YOU MUST use <summarize></summarize> when done — describes the final state",
-		"Completion signal.",
+		"* 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.",
+		"* 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",
+		"* 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,7 +1,8 @@
 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)");
+if (THINK_ENABLED === undefined)
+	throw new Error("RUMMY_THINK must be set (1 or 0)");
 
 export default class Think {
 	constructor(core) {

package/src/plugins/think/thinkDoc.js

@@ -2,15 +2,13 @@
 // 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"],
 	[
-		"## <think>[reasoning]</think> - Think before acting",
-	],
-	[
-		"* Use <think> before any other tools to plan your approach",
+		"* Use <think></think> before any other tools to plan your approach",
 		"Positioning: think first, then act. Prevents degenerate tool-call storms.",
 	],
 	[
-		"* Reasoning inside <think> is private — it does not appear in your context",
+		"* Reasoning inside <think></think> is private — it does not appear in your context",
 		"Frees the model to reason without consuming context budget.",
 	],
 ];

package/src/plugins/unknown/unknown.js

@@ -1,5 +1,3 @@
-import docs from "./unknownDoc.js";
-
 export default class Unknown {
 	#core;
 
@@ -10,13 +8,13 @@ export default class Unknown {
 			category: "unknown",
 		});
 		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("assembly.system", this.assembleUnknowns.bind(this), 300);
-		core.filter("instructions.toolDocs", async (docsMap) => {
-			docsMap.unknown = docs;
-			return docsMap;
-		});
+		// <unknown> is internal — written via <set path="unknown://...">. Hidden
+		// from all model-facing tool lists. Handler still dispatches if the
+		// model emits <unknown> directly out of habit.
+		core.markHidden();
 	}
 
 	async handler(entry, rummy) {
@@ -29,17 +27,23 @@ export default class Unknown {
 			return;
 		}
 
-		// Generate slug path and upsert
-		const unknownPath = await store.slugPath(runId, "unknown", entry.body);
+		// Generate slug path and upsert. Summary (if provided) becomes the
+		// path so the model can round-trip it via <get>; body is the fallback.
+		const unknownPath = await store.slugPath(
+			runId,
+			"unknown",
+			entry.body,
+			entry.attributes?.summary,
+		);
 		await store.upsert(runId, turn, unknownPath, entry.body, 200, { loopId });
 	}
 
 	full(entry) {
-		return `# unknown\n${entry.body}`;
+		return entry.body;
 	}
 
-	summary(entry) {
-		return this.full(entry);
+	summary() {
+		return "";
 	}
 
 	async assembleUnknowns(content, ctx) {
@@ -49,7 +53,10 @@ export default class Unknown {
 		const lines = entries.map((u) => {
 			const fidelity = u.fidelity ? ` fidelity="${u.fidelity}"` : "";
 			const tokens = u.tokens ? ` tokens="${u.tokens}"` : "";
-			return `<unknown path="${u.path}" turn="${u.source_turn || u.turn}"${fidelity}${tokens}>${u.body}</unknown>`;
+			if (u.body) {
+				return `<unknown path="${u.path}" turn="${u.source_turn || u.turn}"${fidelity}${tokens}>${u.body}</unknown>`;
+			}
+			return `<unknown path="${u.path}" turn="${u.source_turn || u.turn}"${fidelity}${tokens}/>`;
 		});
 		return `${content}\n\n<unknowns>\n${lines.join("\n")}\n</unknowns>`;
 	}

package/src/plugins/unknown/unknownDoc.js

@@ -3,22 +3,18 @@
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
 	[
-		"## <unknown>[specific thing I need to learn]</unknown> - Track open questions",
+		"## <unknown>[specific thing I need to learn]</unknown> - Register gaps for research",
 	],
 	[
 		'Example: <unknown path="unknown://answer">contents of answer.txt</unknown>',
 		"Path form: explicit unknown path for structured tracking.",
 	],
-	[
-		"Example: <unknown>which database adapter is configured</unknown>",
-		"Body form: question as body, path auto-generated.",
-	],
 	[
 		"* Investigate with Tool Commands",
 		"Unknowns drive action — get, env, search, ask_user.",
 	],
 	[
-		'* When resolved or irrelevant, remove with <set path="unknown://..." fidelity="archive"/>',
+		'* When resolved or irrelevant, remove with <set path="unknown://..." fidelity="archived"/>',
 		"Archive instead of delete — preserves the question for context history.",
 	],
 ];

package/src/plugins/update/update.js

@@ -8,8 +8,8 @@ export default class Update {
 		core.ensureTool();
 		core.registerScheme({ category: "logging" });
 		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.update = docs;
 			return docsMap;

package/src/plugins/update/updateDoc.js

@@ -2,7 +2,10 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	["## <update>[brief status]</update> - Signal continuation"],
+	[
+		"## <update>[brief status]</update> - Heartbeat for ongoing work (one per turn, at the end)",
+		"Header defines position and frequency. Without this, model uses update as inline narration between tools — multiple updates per turn.",
+	],
 	[
 		"Example: <update>Reading config files</update>",
 		"Progress checkpoint. Status signal, not a log entry.",
@@ -12,15 +15,15 @@ const LINES = [
 		"Multi-step progress. Ongoing work.",
 	],
 	[
-		"* YOU MUST use <update></update> if still working — describes the current state",
-		"Continuation signal. Triggers the next turn.",
+		"* Urgent: ONE <update></update> per turn, AT THE END. Not inline narration between tools.",
+		"Single-update-per-turn is the missing rule. Model was emitting 3-6 updates per turn as progress commentary.",
 	],
 	[
-		"* YOU MUST NOT use <update> if done — use <summarize/> instead",
-		"Mutual exclusion with summarize.",
+		"* If you'd repeat the same <update></update> as last turn, the work is either stuck or done. Take a different action or <summarize></summarize>.",
+		"Points at the zombie-loop failure mode directly. Gives the model a trigger (same-text-as-prior-update) and two remedies.",
 	],
 	[
-		"* YOU MUST keep <update> to <= 80 characters",
+		"* YOU MUST keep <update></update> to <= 80 characters",
 		"Length cap.",
 	],
 ];

package/src/sql/functions/slugify.js

@@ -1,6 +1,18 @@
 export const deterministic = true;
 
+// Build URI paths the model can round-trip:
+//   "history,mongol,khan"   → "history/mongol/khan"   (commas become path separators)
+//   "contents of Document 1" → "contents_of_Document_1" (spaces become underscores)
+// Slice on decoded text, then split-encode-join per segment so / survives as
+// a separator while anything URL-unsafe inside a segment gets escaped.
 export default function slugify(text) {
 	if (!text) return "";
-	return encodeURIComponent(text).slice(0, 80);
+	return text
+		.slice(0, 80)
+		.replace(/,/g, "/")
+		.replace(/ /g, "_")
+		.split("/")
+		.filter(Boolean)
+		.map(encodeURIComponent)
+		.join("/");
 }

package/src/sql/v_model_context.sql

@@ -17,7 +17,7 @@ visible AS (
 		, COALESCE(s.category, 'logging') AS category
 		, CASE
 			-- Archived entries not in context
-			WHEN ke.fidelity = 'archive' THEN NULL
+			WHEN ke.fidelity = 'archived' THEN NULL
 			-- 202 Accepted (proposed) hidden until resolved
 			WHEN ke.status = 202 THEN NULL
 			-- Audit schemes (model_visible = 0) hidden
@@ -43,7 +43,7 @@ projected AS (
 		, category
 		, tokens
 		, CASE
-			WHEN visible_fidelity IN ('full', 'summary') THEN body
+			WHEN visible_fidelity IN ('promoted', 'demoted') THEN body
 			ELSE ''
 		END AS body
 	FROM visible
@@ -72,7 +72,7 @@ SELECT
 			END
 			, CASE scheme WHEN 'skill' THEN 0 ELSE 1 END
 			, CASE fidelity
-				WHEN 'summary' THEN 0
+				WHEN 'demoted' THEN 0
 				ELSE 1
 			END
 			, turn