@possumtech/rummy 0.3.1 → 0.4.0

package/src/plugins/instructions/preamble.md

@@ -1,26 +1,37 @@
-You are a folksonomic memory agent. YOU MUST organize all information into searchable taxonomies with navigable path hierarchies and searchable summary tags, then YOU MAY answer questions and/or take action.
+You are a folksonomic knowledgebase assistant. YOU MUST discern what you don't know into unknowns, then extract and organize your findings into navigable and searchable knowns, then YOU MAY answer questions and/or perform actions.
 
-# Response Rules
+# Tool Commands
 
-Required: YOU MUST respond with Tool Commands in the XML format. YOU MAY use multiple tools in your response.
+Tools: [%TOOLS%]
 
-Optional: YOU MAY think in an optional <think></think> tag before using any other Tool Commands.
+# Tool Rules
 
+## Response Rules
+Required: YOU MUST respond with Tool Commands in the XML format. YOU MAY use up to 12 tools in your response.
 Required: YOU MUST register all unknowns with <unknown>[specific thing I need to learn]</unknown>.
-
 Required: YOU MUST register all new facts, decisions, and plans with <known path="topic/subtopic" summary="keyword,keyword,keyword">[specific facts, decisions, or plans]</known>.
-Required: Every <known> MUST include summary="keyword,keyword" tags.
-Info: Paths are addresses for tools. Summary tags tell you what's inside.
-Info: Path and summary information is approximate. YOU MUST use <get/> to verify before acting on summarized content.
-Info: When information conflicts, later turns are more likely to be relevant and correct than earlier turns.
-Info: Your context is limited but your archive is not. Organize and categorize your facts, decisions, plans, and history to optimize your context.
-
-Required: YOU MUST promote all relevant "summary" entries to "full".
-Required: YOU MUST demote all irrelevant "full" entries to "summary".
 
+## Folksonomic Memory Management
+* Write paths with navigable hierarchies and summaries with searchable tags.
+* When new facts, decisions, and plans appear, set them as <known/> entries with navigable hierarchies and summaries with searchable tags to improve your folksonomic knowledgebase.
+* When new questions emerge, use pattern matching operations to optimize the fidelity and relevance of your knowledgebase.
+* The turn attribute can be helpful for discerning what's fresh or stale, prefer more recent information if conflicts exist.
+* YOU MUST promote all relevant entries and demote all irrelevant entries before acting or answering. Use body pattern search (Example: <get path="known://*">John Doe</get>) to recall archived entries when needed.
+* Logging entries in <previous/> can also be demoted to optimize context.
+
+## Fidelity Management
+* full: Entire contents are shown (consumes token budget)
+* summary: Only path and summary are shown. (<= 80 chars, saves token budget)
+* archive: Archived in an unlimited archive. Entries can be recalled with path recall or pattern search. (use caution)
+
+## Token Budget Management
+* Entries contain a "fidelity" and a "token" attribute to enable token budget management and context optimization.
+* Set relevant entries to "full" and irrelevant entries to "summary" to optimize context.
+* The less irrelevant information in your context, the better.
+
+## Response Termination
 Required: YOU MUST conclude every turn with EITHER <update></update> if still working OR <summarize></summarize> if done. Never both.
-Required: YOU MUST use one and only one <update></update> or <summarize></summarize> tag, and only at the end.
 
-# Tool Commands
+# Tool Usage
 
-Tools: [%TOOLS%]
+[%TOOLDOCS%]

package/src/plugins/known/known.js

@@ -1,5 +1,8 @@
+import { countTokens } from "../../agent/tokens.js";
 import docs from "./knownDoc.js";
 
+const MAX_ENTRY_TOKENS = Number(process.env.RUMMY_MAX_ENTRY_TOKENS) || 512;
+
 export default class Known {
 	#core;
 
@@ -8,6 +11,7 @@ export default class Known {
 		core.registerScheme({ category: "data" });
 		core.on("handler", this.handler.bind(this));
 		core.on("full", this.full.bind(this));
+		core.on("summary", this.summary.bind(this));
 		core.filter("assembly.system", this.assembleKnown.bind(this), 100);
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.known = docs;
@@ -17,19 +21,70 @@ export default class Known {
 
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
-		const target = entry.attributes.path || entry.resultPath;
-		await store.upsert(runId, turn, target, entry.body, 200, { loopId });
+		if (!entry.body) return;
+
+		// Size gate
+		const entryTokens = countTokens(entry.body);
+		if (entryTokens > MAX_ENTRY_TOKENS) {
+			const rejectPath = await store.slugPath(runId, "known", entry.body);
+			await store.upsert(
+				runId,
+				turn,
+				rejectPath,
+				`Entry too large (${entryTokens} tokens, max ${MAX_ENTRY_TOKENS}). Sort the information, ideas, or plans carefully into multiple entries.`,
+				413,
+				{ loopId },
+			);
+			return;
+		}
+
+		// Resolve path: explicit or auto-generated slug
+		let knownPath = entry.attributes?.path || null;
+		if (knownPath && !knownPath.includes("://")) {
+			knownPath = `known://${knownPath}`;
+		}
+		if (!knownPath) {
+			knownPath = await store.slugPath(
+				runId,
+				"known",
+				entry.body,
+				entry.attributes?.summary,
+			);
+		}
+
+		// Dedup: if path exists, update rather than duplicate
+		const existing = await store.getEntriesByPattern(runId, knownPath, null);
+		if (existing.length > 0) {
+			await store.upsert(
+				runId,
+				turn,
+				existing[0].path,
+				entry.body || existing[0].body,
+				200,
+				{ attributes: entry.attributes, loopId },
+			);
+			return;
+		}
+
+		await store.upsert(runId, turn, knownPath, entry.body, 200, {
+			attributes: entry.attributes,
+			loopId,
+		});
 	}
 
 	full(entry) {
 		return `# known ${entry.path}\n${entry.body}`;
 	}
 
+	summary(entry) {
+		return this.full(entry);
+	}
+
 	async assembleKnown(content, ctx) {
 		const entries = ctx.rows.filter((r) => r.category === "data");
 		if (entries.length === 0) return content;
 
-		// Rows arrive pre-sorted by SQL: skill → index → summary → full, then by recency
+		// Rows arrive pre-sorted by SQL: summary → full, then by recency
 		const demotedSet = new Set(ctx.demoted || []);
 		const lines = entries.map((e) => renderKnownTag(e, demotedSet));
 		return `${content}\n\n<knowns>\n${lines.join("\n")}\n</knowns>`;
@@ -50,12 +105,12 @@ function renderKnownTag(entry, demotedSet) {
 			: entry.attributes;
 	const summary =
 		typeof attrs?.summary === "string"
-			? ` summary="${attrs.summary.slice(0, 80)}"`
+			? ` summary="${attrs.summary.replace(/"/g, "'").slice(0, 80)}"`
 			: "";
 
-	if (entry.body) {
-		return `<${tag} path="${entry.path}"${turn}${status}${fidelity}${summary}${tokens}${flag}>${entry.body}</${tag}>`;
+	if (entry.fidelity === "archive") return "";
+	if (entry.fidelity === "summary") {
+		return `<${tag} path="${entry.path}"${turn}${status}${summary}${fidelity}${tokens}${flag}/>`;
 	}
-
-	return `<${tag} path="${entry.path}"${turn}${status}${fidelity}${summary}${tokens}${flag}/>`;
+	return `<${tag} path="${entry.path}"${turn}${status}${summary}${fidelity}${tokens}${flag}>${entry.body}</${tag}>`;
 }

package/src/plugins/known/knownDoc.js

@@ -2,32 +2,28 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: path = slash-separated topic hierarchy, body = the information to save
 	[
 		'## <known path="known://topic/subtopic" summary="keyword,keyword,keyword">[specific facts, decisions, or plans]</known> - Sort and save what you learn for later recall',
 	],
-	// --- Examples: category-level entries — multiple related facts per entry, not one per item
 	[
-		'Example: <known path="known://config/database" summary="database,host,port,pool,replica">Host: db.internal. Port: 5432. Pool: 10 connections. Replica: db-replica.internal:5432.</known>',
-		"Category entry: all database config facts in one entry. Path is an address (topic/subtopic), body collects every related fact, summary is comma-separated search keywords — not a description.",
+		'Example: <known summary="hedberg,comedian,death,2005">Mitch Hedberg died on March 30, 2005</known>',
+		"Summary-first pattern: comma-separated keywords, path auto-generated.",
 	],
 	[
-		'Example: <known path="known://project/milestones" summary="milestone,deadline,alpha,launch,2026">Alpha: 2026-03-01. Beta cutoff: 2026-04-15. GA launch: 2026-06-01.</known>',
-		"Timeline entry: all milestone dates under one path. Multiple facts per entry reduces fragmentation. Recall by glob or keyword.",
+		'Example: <known path="known://people/rumsfeld" summary="defense,secretary,born,1932">Donald Rumsfeld was born in 1932 and served as Secretary of Defense</known>',
+		"Explicit path form: slashed path=category/key, summary=keywords.",
 	],
-	// --- Constraints: summary and grouping first (model forms generation pattern from header + examples)
 	[
-		"* `summary` REQUIRED — at summary fidelity the body is hidden; these keywords are your only description",
-		"Self-interest framing: without summary, the model has a path but no idea what's inside.",
+		'* Recall with <get path="known://people/*">keyword</get>',
+		"Cross-tool lifecycle: glob by category, filter by keyword.",
 	],
 	[
-		"* Group related facts by topic — one entry per topic category, not one per input chunk",
-		"Critical behavioral constraint. Topic grouping enables semantic recall; chunk-based filing creates positional, irretrievable entries.",
+		"* YOU SHOULD write `summary` keywords, you can search for them later",
+		"Motivates summary writing through self-interest.",
 	],
-	// --- Lifecycle
 	[
-		'* Recall with <get path="known://config/*">replica</get>',
-		"Cross-tool lifecycle: glob by category, filter by keyword. Matches the slashed path convention.",
+		"* YOU MUST sort and save all new facts, decisions, and plans in their own <known> entries",
+		"Critical behavioral constraint. 'new' prevents re-saving known facts.",
 	],
 ];
 

package/src/plugins/mv/mvDoc.js

@@ -2,43 +2,28 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: path attr = source, body = destination
 	[
 		'## <mv path="[source]">[destination]</mv> - Move or rename a file or entry',
 	],
-
-	// --- Examples: entry rename and file move
 	[
 		'Example: <mv path="known://active_task">known://completed_task</mv>',
-		"Entry rename. Most common mv use case. Shows known:// path convention.",
+		"Entry rename. Most common mv use case.",
 	],
 	[
 		'Example: <mv path="src/old_name.js">src/new_name.js</mv>',
-		"File rename. Shows that mv works on files too, not just known entries.",
-	],
-
-	// --- Archive lifecycle
-	[
-		"* You may move entries or pattern-matching batches of entries to and from the archive to manage your context budget.",
-		"Teaches archival as a reversible budget operation, not permanent deletion.",
+		"File rename.",
 	],
 	[
-		'Example: <mv path="known://project/*" fidelity="index"/> ... <mv path="known://project/active_sprint" fidelity="full"/>',
-		"Index a whole category to free context while keeping paths visible, restore one entry when needed. No destination = fidelity change in place.",
+		'Example: <mv path="known://project/*" fidelity="summary"/>',
+		"Batch fidelity change via pattern. No destination = fidelity in place.",
 	],
-	[
-		"* YOU SHOULD demote irrelevant entries to `index` or `archive` — clean context improves reasoning.",
-		"Core curation principle: clean context is a quality signal, not just a budget concern. Teach the model to curate eagerly.",
-	],
-
-	// --- Constraints
 	[
 		"* Source path accepts patterns for batch moves",
 		"Pattern support consistent with get/cp/rm.",
 	],
 	[
-		"* In ask mode, destination MUST be a scheme path (not a file)",
-		"Mode constraint. Prevents file mutations in ask mode via mv.",
+		"* Use `preview` to check matches before pattern-based bulk moves",
+		"Safety pattern consistent with rm/cp.",
 	],
 ];
 

package/src/plugins/policy/policy.js

@@ -0,0 +1,47 @@
+import KnownStore from "../../agent/KnownStore.js";
+
+export default class Policy {
+	constructor(core) {
+		core.filter("entry.recording", this.#enforceAskMode.bind(this), 1);
+	}
+
+	async #enforceAskMode(entry, ctx) {
+		if (ctx.mode !== "ask") return entry;
+
+		if (entry.scheme === "sh") {
+			console.warn("[RUMMY] Rejected <sh> in ask mode");
+			return { ...entry, status: 403 };
+		}
+
+		if (entry.scheme === "set" && entry.attributes?.path) {
+			const scheme = KnownStore.scheme(entry.attributes.path);
+			if (scheme === null && entry.body) {
+				console.warn(
+					`[RUMMY] Rejected file edit to ${entry.attributes.path} in ask mode`,
+				);
+				return { ...entry, status: 403 };
+			}
+		}
+
+		if (entry.scheme === "rm") {
+			const pathAttr = entry.attributes?.path || entry.path;
+			const scheme = KnownStore.scheme(pathAttr);
+			if (scheme === null) {
+				console.warn(`[RUMMY] Rejected file rm of ${pathAttr} in ask mode`);
+				return { ...entry, status: 403 };
+			}
+		}
+
+		if (entry.scheme === "mv" || entry.scheme === "cp") {
+			const destScheme = KnownStore.scheme(entry.attributes?.to);
+			if (destScheme === null) {
+				console.warn(
+					`[RUMMY] Rejected ${entry.scheme} to file ${entry.attributes?.to} in ask mode`,
+				);
+				return { ...entry, status: 403 };
+			}
+		}
+
+		return entry;
+	}
+}

package/src/plugins/progress/progress.js

@@ -10,53 +10,17 @@ export default class Progress {
 		const { lastContextTokens: usedTokens, contextSize } = ctx;
 		const pct = contextSize ? Math.round((usedTokens / contextSize) * 100) : 0;
 
-		// Fidelity distribution across all manageable entries (data + logging)
-		const dataEntries = ctx.rows.filter((r) => r.category === "data");
-		const loggingEntries = ctx.rows.filter((r) => r.category === "logging");
-		const entries = [...dataEntries, ...loggingEntries];
-		const fullEntries = entries.filter((r) => r.fidelity === "full");
-		const summaryEntries = entries.filter((r) => r.fidelity === "summary");
-		const indexEntries = entries.filter((r) => r.fidelity === "index");
-		const fullTokens = fullEntries.reduce((s, r) => s + r.tokens, 0);
-		const summaryTokens = summaryEntries.reduce((s, r) => s + r.tokens, 0);
-		const indexTokens = indexEntries.reduce((s, r) => s + r.tokens, 0);
-
-		const unknownCount = ctx.rows.filter(
-			(r) => r.category === "unknown",
-		).length;
-
-		const hasPerformed = loggingEntries.some(
-			(r) => r.source_turn >= ctx.loopStartTurn,
-		);
-
-		const parts = [];
-
-		const knownCount = dataEntries.length;
-		const loggingCount = loggingEntries.length;
-		const tokenLine = contextSize
-			? `${usedTokens} of ${contextSize} tokens (${pct}%) · ${knownCount} known${knownCount !== 1 ? "s" : ""} · ${loggingCount} logging · ${unknownCount} unknown${unknownCount !== 1 ? "s" : ""}`
-			: "";
-		if (tokenLine) parts.push(tokenLine);
-
-		// Fidelity distribution
-		const fidelityParts = [];
-		if (fullEntries.length > 0)
-			fidelityParts.push(`${fullEntries.length} full (${fullTokens} tok)`);
-		if (summaryEntries.length > 0)
-			fidelityParts.push(
-				`${summaryEntries.length} summary (${summaryTokens} tok)`,
-			);
-		if (indexEntries.length > 0)
-			fidelityParts.push(`${indexEntries.length} index (${indexTokens} tok)`);
-		if (fidelityParts.length > 0)
-			parts.push(`Entries: ${fidelityParts.join(" · ")}`);
-
-		if (hasPerformed) {
-			parts.push(
-				"The above actions were performed in response to the following prompt:",
+		const lines = [];
+		if (contextSize) {
+			lines.push(
+				`Using ${usedTokens} tokens (${pct}%) of ${contextSize} token budget. Use <get/> or set entry fidelity to "full" to spend tokens. Set entry fidelity to "summary" to save tokens.`,
 			);
 		}
+		lines.push(
+			'Conclude with a brief <update></update> to continue or a brief <summarize></summarize> if done.',
+		);
+		const body = lines.join("\n");
 
-		return `${content}<progress turn="${ctx.turn}">${parts.join("\n")}</progress>\n`;
+		return `${content}<progress turn="${ctx.turn}">${body}</progress>\n`;
 	}
 }

package/src/plugins/prompt/prompt.js

@@ -3,7 +3,16 @@ export default class Prompt {
 
 	constructor(core) {
 		this.#core = core;
-		core.hooks.tools.onView("prompt", (entry) => entry.body);
+		core.hooks.tools.onView("prompt", (entry) => {
+			if (entry.fidelity === "summary") {
+				const limit = 500;
+				const text = entry.body?.slice(0, limit) || "";
+				return text.length < (entry.body?.length || 0)
+					? `${text}\n[truncated — promote to full to see the complete prompt]`
+					: text;
+			}
+			return entry.body;
+		});
 		core.on("turn.started", this.onTurnStarted.bind(this));
 		core.filter("assembly.user", this.assemblePrompt.bind(this), 300);
 	}

package/src/plugins/rm/rmDoc.js

@@ -2,28 +2,23 @@
 // Text goes to the model. Rationale stays in source.
 // Changing ANY line requires reading ALL rationales first.
 const LINES = [
-	// --- Syntax: path attr, self-closing
 	['## <rm path="[path]"/> - Remove a file or entry'],
-
-	// --- Examples: file, known (with slug path), preview safety
 	['Example: <rm path="src/config.js"/>', "File removal. Simplest form."],
 	[
 		'Example: <rm path="known://config/deprecated_service"/>',
-		"Shows topic-hierarchy path convention. Paths are category/key, not sentence slugs.",
+		"Shows topic-hierarchy path convention.",
 	],
 	[
 		'Example: <rm path="known://temp_*" preview/>',
-		"Preview before deleting. Glob pattern. Safety pattern for bulk operations.",
+		"Preview before deleting. Safety pattern for bulk operations.",
 	],
-
-	// --- Constraints
 	[
 		'* Permanent. Prefer <set fidelity="archive"/> to preserve for later retrieval',
-		"Nudges toward archive over rm. Archive keeps the key; rm deletes permanently.",
+		"Nudges toward archive over rm.",
 	],
 	[
-		"* Paths accept patterns — use `preview` to check matches first",
-		"Reinforces preview safety pattern. Prevents accidental bulk deletion.",
+		"* Use `preview` to check matches before pattern-based bulk deletion",
+		"Reinforces preview safety pattern.",
 	],
 ];
 

package/src/plugins/rpc/rpc.js

@@ -178,7 +178,7 @@ export default class Rpc {
 					scheme: e.scheme,
 					status: e.status,
 					fidelity: e.fidelity,
-					tokens: e.tokens_full,
+					tokens: e.tokens,
 				}));
 			},
 			description: "Query entries by pattern.",
@@ -233,6 +233,7 @@ export default class Rpc {
 						contextLimit: params.contextLimit,
 						noRepo: params.noRepo,
 						noInteraction: params.noInteraction,
+						noProposals: params.noProposals,
 						noWeb: params.noWeb,
 						fork: params.fork,
 					},
@@ -269,6 +270,7 @@ export default class Rpc {
 						contextLimit: params.contextLimit,
 						noRepo: params.noRepo,
 						noInteraction: params.noInteraction,
+						noProposals: params.noProposals,
 						noWeb: params.noWeb,
 						fork: params.fork,
 					},