@possumtech/rummy 0.3.1 → 0.5.0

package/src/plugins/unknown/unknown.js

@@ -1,5 +1,3 @@
-import docs from "./unknownDoc.js";
-
 export default class Unknown {
 	#core;
 
@@ -9,16 +7,43 @@ export default class Unknown {
 		core.registerScheme({
 			category: "unknown",
 		});
-		core.on("full", this.full.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("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) {
+		const { entries: store, sequence: turn, runId, loopId } = rummy;
+
+		// Deduplicate — if this exact body already exists, skip
+		const existingValues = await store.getUnknownValues(runId);
+		if (existingValues.has(entry.body)) {
+			console.warn(`[RUMMY] Unknown deduped: "${entry.body.slice(0, 60)}"`);
+			return;
+		}
+
+		// 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() {
+		return "";
 	}
 
 	async assembleUnknowns(content, ctx) {
@@ -28,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

@@ -2,29 +2,20 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: body = what you need to learn
 	[
-		`## <unknown>[specific thing I need to learn]</unknown> - Track open questions`,
-	],
-
-	// --- Examples: concrete unknowns, not abstract
-	[
-		`Example: <unknown path="unknown://answer">contents of answer.txt</unknown>`,
-		`Specific and actionable. Shows that unknowns are concrete investigation targets.`,
+		"## <unknown>[specific thing I need to learn]</unknown> - Register gaps for research",
 	],
 	[
-		`Example: <unknown>which database adapter is configured</unknown>`,
-		`Domain question. Shows unknowns for configuration/architecture questions.`,
+		'Example: <unknown path="unknown://answer">contents of answer.txt</unknown>',
+		"Path form: explicit unknown path for structured tracking.",
 	],
-
-	// --- Lifecycle: register → investigate → resolve
 	[
-		`* Investigate with Tool Commands`,
-		`Cross-tool lifecycle: unknowns drive get/env/ask_user actions.`,
+		"* Investigate with Tool Commands",
+		"Unknowns drive action — get, env, search, ask_user.",
 	],
 	[
-		`* When resolved or irrelevant, remove with <rm path="unknown://..."/>`,
-		`Cross-tool lifecycle: rm cleans resolved unknowns from context.`,
+		'* 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

@@ -7,14 +7,21 @@ export default class Update {
 		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.update = docs;
 			return docsMap;
 		});
 	}
 
+	async handler(entry, rummy) {
+		const { entries: store, sequence: turn, runId, loopId } = rummy;
+		const statusPath = await store.slugPath(runId, "update", entry.body);
+		await store.upsert(runId, turn, statusPath, entry.body, 200, { loopId });
+	}
+
 	full(entry) {
 		return `# update\n${entry.body}`;
 	}

package/src/plugins/update/updateDoc.js

@@ -2,31 +2,29 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax
-	["## <update>[brief status]</update> - Signal continuation"],
-
-	// --- Examples: research progress and multi-step work
+	[
+		"## <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. Shows update as a status signal, not a log entry.",
+		"Progress checkpoint. Status signal, not a log entry.",
 	],
 	[
 		"Example: <update>Found 3 issues, fixing first</update>",
-		"Multi-step progress. Shows update for ongoing work.",
+		"Multi-step progress. Ongoing work.",
 	],
-
-	// --- Constraints: RFC-style MUST/MUST NOT
 	[
-		"* YOU MUST use <update> if still working — describes the current state",
-		"Continuation signal. Triggers the next turn in the loop.",
+		"* 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. Prevents infinite loops.",
+		"* 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",
-		"Length cap. Prevents models from writing essays in status updates.",
+		"* YOU MUST keep <update></update> to <= 80 characters",
+		"Length cap.",
 	],
 ];
 

package/src/server/ClientConnection.js

@@ -36,6 +36,15 @@ export default class ClientConnection {
 		}
 	};
 
+	#onProposal = (payload) => {
+		if (payload.projectId === this.#context.projectId) {
+			this.#sendNotification("run/proposal", {
+				run: payload.run,
+				proposed: payload.proposed,
+			});
+		}
+	};
+
 	#onRender = (payload) => {
 		if (payload.projectId === this.#context.projectId) {
 			this.#sendNotification("ui/render", {
@@ -63,7 +72,6 @@ export default class ClientConnection {
 				summary: payload.summary,
 				history: payload.history,
 				unknowns: payload.unknowns,
-				proposed: payload.proposed,
 				telemetry: payload.telemetry,
 			});
 		}
@@ -71,6 +79,7 @@ export default class ClientConnection {
 
 	#setupNotifications() {
 		this.#hooks.run.progress.on(this.#onProgress);
+		this.#hooks.turn.proposal.on(this.#onProposal);
 		this.#hooks.ui.render.on(this.#onRender);
 		this.#hooks.ui.notify.on(this.#onNotify);
 		this.#hooks.run.state.on(this.#onState);
@@ -78,6 +87,7 @@ export default class ClientConnection {
 
 	#teardown() {
 		this.#hooks.run.progress.off(this.#onProgress);
+		this.#hooks.turn.proposal.off(this.#onProposal);
 		this.#hooks.ui.render.off(this.#onRender);
 		this.#hooks.ui.notify.off(this.#onNotify);
 		this.#hooks.run.state.off(this.#onState);

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

@@ -13,11 +13,11 @@ visible AS (
 		, ke.turn
 		, ke.updated_at
 		, ke.attributes
-		, ke.tokens AS tokens_full
+		, ke.tokens
 		, 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
@@ -41,8 +41,9 @@ projected AS (
 		, attributes
 		-- Category comes from schemes table — plugins declare it via registerScheme().
 		, 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
@@ -71,9 +72,8 @@ SELECT
 			END
 			, CASE scheme WHEN 'skill' THEN 0 ELSE 1 END
 			, CASE fidelity
-				WHEN 'index' THEN 0
-				WHEN 'summary' THEN 1
-				ELSE 2
+				WHEN 'demoted' THEN 0
+				ELSE 1
 			END
 			, turn
 			, updated_at