@possumtech/rummy 2.2.0 → 2.3.1

package/src/plugins/prompt/README.md

@@ -8,7 +8,7 @@ turn.
 ## Registration
 
 - **Filter**: `assembly.user` at priority 30 (front of user
-  message, before all dynamic state and the `<instructions>`
+  message, before all dynamic state and the `<system_requirements>`
   block at 165)
 
 ## Behavior

package/src/plugins/prompt/prompt.js

@@ -12,7 +12,7 @@ export default class Prompt {
 			"summarized",
 		);
 		core.on("turn.started", this.onTurnStarted.bind(this));
-		core.filter("assembly.user", this.assemblePrompt.bind(this), 60);
+		core.filter("assembly.user", this.assemblePrompt.bind(this), 30);
 	}
 
 	async onTurnStarted({ rummy, mode, prompt, isContinuation }) {

package/src/plugins/rm/rm.js

@@ -1,5 +1,10 @@
 import Entries from "../../agent/Entries.js";
-import { storePatternResult } from "../helpers.js";
+import { countTokens } from "../../agent/tokens.js";
+import {
+	projectEmission,
+	storePatternResult,
+	summarizeEmission,
+} from "../helpers.js";
 import docs from "./rmDoc.js";
 
 const LOG_ACTION_RE = /^log:\/\/turn_\d+\/(\w+)\//;
@@ -64,9 +69,6 @@ export default class Rm {
 			entry.attributes.body,
 		);
 
-		// Manifest: list what would be removed without performing the rm.
-		// Safety idiom for destructive bulk ops — the model can audit a
-		// glob's reach before committing to it.
 		if (entry.attributes.manifest !== undefined) {
 			await storePatternResult(
 				store,
@@ -98,23 +100,29 @@ export default class Rm {
 		const fileMatches = matches.filter((m) => m.scheme === null);
 		const schemeMatches = matches.filter((m) => m.scheme !== null);
 
-		// Scheme entries: remove all, write one aggregate result entry
 		for (const match of schemeMatches)
 			await store.rm({ runId: runId, path: match.path });
 		if (schemeMatches.length > 0) {
-			const paths = schemeMatches.map((m) => m.path).join("\n");
+			const beforeTokens = schemeMatches.reduce(
+				(n, m) => n + countTokens(m.body),
+				0,
+			);
 			await store.set({
 				runId,
 				turn,
 				path: entry.resultPath,
-				body: paths,
+				body: "",
 				state: "resolved",
-				attributes: { path: target },
+				attributes: {
+					path: target,
+					beforeActionTokens: beforeTokens,
+					afterActionTokens: 0,
+				},
 				loopId,
 			});
 		}
 
-		// File entries: individual proposals (require user resolution)
+		// File matches: individual proposals (require user resolution).
 		if (fileMatches.length > 0 && schemeMatches.length > 0)
 			await store.rm({ runId: runId, path: entry.resultPath });
 		for (const match of fileMatches) {
@@ -126,20 +134,23 @@ export default class Rm {
 				runId,
 				turn,
 				path: resultPath,
-				body: match.path,
+				body: "",
 				state: "proposed",
-				attributes: { path: match.path },
+				attributes: {
+					path: match.path,
+					beforeActionTokens: countTokens(match.body),
+					afterActionTokens: 0,
+				},
 				loopId,
 			});
 		}
 	}
 
 	full(entry) {
-		const header = `# rm ${entry.attributes.path || entry.path}`;
-		return entry.body ? `${header}\n${entry.body}` : header;
+		return projectEmission(entry.body);
 	}
 
-	summary() {
-		return "";
+	summary(entry) {
+		return summarizeEmission(entry.body);
 	}
 }

package/src/plugins/rm/rmDoc.md

@@ -2,10 +2,8 @@
 
 Example: <rm path="src/config.js"/>
 <!-- File removal. Simplest form. -->
-
 Example: <rm path="known://countries/france/*" manifest/>
 <!-- Manifest before deleting. Safety pattern for bulk operations. -->
-
 Example: <rm path="log://turn_3/get/**"/>
 <!-- Bulk delete by glob. Recursive scheme glob; clears a turn's get logs in one call. -->
 

package/src/plugins/set/set.js

@@ -2,7 +2,11 @@ import Entries from "../../agent/Entries.js";
 import { countTokens } from "../../agent/tokens.js";
 import Hedberg, { generatePatch } from "../../lib/hedberg/hedberg.js";
 import File from "../file/file.js";
-import { SUMMARY_MAX_CHARS, storePatternResult } from "../helpers.js";
+import {
+	projectEmission,
+	storePatternResult,
+	summarizeEmission,
+} from "../helpers.js";
 import docs from "./setDoc.js";
 
 const VALID_VISIBILITY = { archived: 1, summarized: 1, visible: 1 };
@@ -13,10 +17,6 @@ function isSetProposal(path) {
 	return m?.[1] === "set";
 }
 
-// Cap the size of the current-body context surfaced on conflict. Big
-// enough for typical known:// entries (plans, notes) and a useful slice
-// of files; small enough that a 100k-line file doesn't blow the budget
-// on every conflict. The model can `<get>` the path for the full body.
 const CONFLICT_FEEDBACK_MAX_CHARS = 4000;
 function truncateForFeedback(body) {
 	if (body == null) return null;
@@ -41,9 +41,7 @@ export default class Set {
 		});
 		core.filter("proposal.accepting", this.#vetoReadonly.bind(this));
 		core.filter("proposal.content", this.#preferExistingBody.bind(this));
-		// Materialization is shape-coupled (attrs.path + attrs.patched), not
-		// path-coupled. Any plugin emitting a proposal in that shape
-		// (set, cp, future tools) gets fs materialization for free.
+		// Shape-coupled (attrs.path + attrs.patched) — cp/set share one materializer.
 		core.on("proposal.accepted", this.#materializeFile.bind(this));
 	}
 
@@ -73,19 +71,13 @@ export default class Set {
 
 	async #materializeFile(ctx) {
 		const { attrs, runId, projectId, projectRoot, db, entries } = ctx;
-		// Shape gate, not path gate: any accepted proposal whose
-		// attributes describe a file materialization (target path +
-		// authoritative patched body) lands a fresh file body and writes
-		// to disk. Lets cp/set/future tools share one materializer.
 		if (!attrs?.path || attrs?.patched == null) return;
 
 		const existing = await entries.getBody(runId, attrs.path);
 		const isNewFile = existing === null;
 		const patched = attrs.patched;
 		const turn = (await db.get_run_by_id.get({ id: runId })).next_turn;
-		// Visibility precedence: explicit attrs.visibility (mv/cp pass
-		// the model's tag attribute through) > current entry visibility
-		// (preserves an earlier <get>'s promotion) > scheme default.
+		// Visibility precedence: explicit attr > existing state > scheme default.
 		const existingState = await entries.getState(runId, attrs.path);
 		const visibility = attrs.visibility
 			? attrs.visibility
@@ -120,11 +112,7 @@ export default class Set {
 		const rawTags = typeof attrs.tags === "string" ? attrs.tags : null;
 		const tagsText = rawTags ? rawTags.slice(0, 80) : null;
 
-		// log:// is the immutable record of what happened. Visibility/metadata
-		// updates are fine (no body); rewriting the body destroys history.
-		// Models reach for this when the Demote example pattern primes
-		// `<set ... visibility="summarized">` and they tack on a body line —
-		// 405 here teaches the shape that's actually allowed.
+		// log:// is immutable; visibility flips OK, body rewrites are not.
 		if (attrs.path?.startsWith("log://") && entry.body) {
 			await store.set({
 				runId,
@@ -159,11 +147,6 @@ export default class Set {
 			return;
 		}
 
-		// Refuse parse-error edits (e.g., malformed sed). Without this the
-		// XmlParser would have either silently produced a corrupted edit
-		// or fallen through to body-replace, overwriting the target with
-		// the literal sed text. Surfacing the error gives the model a
-		// concrete signal it can adapt to.
 		if (attrs.error) {
 			await store.set({
 				runId,
@@ -178,10 +161,7 @@ export default class Set {
 			return;
 		}
 
-		// Manifest: universal preview gate. Fires before any operational
-		// branch so visibility flips, SEARCH/REPLACE edits, sed substitutions,
-		// pattern writes, and direct writes all support
-		// "list-without-doing" with the same flag.
+		// Manifest: universal preview gate, fires before any operational branch.
 		if (attrs.manifest !== undefined && attrs.path) {
 			const matches = await store.getEntriesByPattern(
 				runId,
@@ -251,36 +231,28 @@ export default class Set {
 			return;
 		}
 
-		// Build the new content. Either from the marker-parsed operation
-		// list (NEW / PREPEND / APPEND / REPLACE / DELETE / SEARCH+REPLACE)
-		// or from the plain body (full-replace shorthand).
 		const target = attrs.path;
 		if (!target) return;
 		let newContent;
 		if (attrs.operations) {
 			const existing = await store.getBody(runId, target);
-			const requiresExisting = attrs.operations.some(
-				(op) => op.op === "search_replace" || op.op === "delete",
-			);
-			if (requiresExisting && existing === null) {
-				await store.set({
-					runId,
-					turn,
-					loopId,
-					path: entry.resultPath,
-					body: `${target} not found in context`,
-					state: "failed",
-					outcome: "not_found",
-					attributes: {
-						path: target,
-						error: `${target} not found in context`,
-					},
-				});
-				return;
-			}
+			// Missing-path recovery: search_replace → append (replace text only),
+			// delete → drop. Lets the model's edit-shaped emission land on a
+			// fresh path without first having to write a NEW.
+			const operations =
+				existing === null
+					? attrs.operations.flatMap((op) => {
+							if (op.op === "search_replace") {
+								return [{ op: "append", content: op.replace }];
+							}
+							if (op.op === "delete") return [];
+							return [op];
+						})
+					: attrs.operations;
+			if (operations.length === 0) return;
 			const result = Set.#applyOperations(
 				existing == null ? "" : existing,
-				attrs.operations,
+				operations,
 			);
 			if (result.error) {
 				await store.set({
@@ -308,8 +280,7 @@ export default class Set {
 		if (newContent !== undefined) {
 			const scheme = Entries.scheme(target);
 			if (scheme === null) {
-				// File write — emit a "proposed" entry; #materializeFile
-				// writes to disk on accept.
+				// File write: proposed entry; #materializeFile writes to disk on accept.
 				const existing = await store.getBody(runId, target);
 				const oldContent = existing == null ? "" : existing;
 				const udiff = generatePatch(target, oldContent, newContent);
@@ -319,22 +290,20 @@ export default class Set {
 					runId,
 					turn,
 					path: entry.resultPath,
-					body: newContent,
+					body: attrs.inner,
 					state: "proposed",
 					attributes: {
 						path: target,
 						patch: udiff,
 						patched: newContent,
-						beforeTokens,
-						afterTokens,
+						beforeActionTokens: beforeTokens,
+						afterActionTokens: afterTokens,
 						tags: tagsText,
 					},
 					loopId,
 				});
 			} else if (attrs.filter || target.includes("*")) {
-				// Pattern body-update: write the same body to every matching
-				// entry. Operations don't apply here (this is a bulk
-				// metadata-flavored body assignment).
+				// Pattern body-update: bulk body assignment, no operations.
 				const matches = await store.getEntriesByPattern(
 					runId,
 					target,
@@ -357,7 +326,6 @@ export default class Set {
 					{ loopId },
 				);
 			} else {
-				// Direct scheme write; same diff-against-existing shape as file writes.
 				const existing = await store.getBody(runId, target);
 				const oldContent = existing == null ? "" : existing;
 				const udiff = generatePatch(target, oldContent, newContent);
@@ -378,21 +346,20 @@ export default class Set {
 					runId,
 					turn,
 					path: entry.resultPath,
-					body: newContent,
+					body: attrs.inner,
 					state: "resolved",
 					loopId,
 					attributes: {
 						path: target,
 						patch: udiff,
-						beforeTokens,
-						afterTokens,
+						beforeActionTokens: beforeTokens,
+						afterActionTokens: afterTokens,
 						tags: tagsText,
 					},
 				});
 			}
 		}
 
-		// Apply visibility after all write operations
 		if (visibilityAttr && attrs.path) {
 			const target = attrs.path;
 			const scheme = Entries.scheme(target);
@@ -415,38 +382,24 @@ export default class Set {
 
 	full(entry) {
 		const attrs = entry.attributes;
-		const target = attrs.path || entry.path;
 		if (attrs.error) {
-			const lines = [`# set ${target}`, attrs.error];
+			const target = attrs.path || entry.path;
+			const lines = [`error at ${target}: ${attrs.error}`];
 			if (attrs.attempted) {
 				lines.push("", "--- attempted ---", attrs.attempted);
 			}
 			if (attrs.currentBody != null) {
 				lines.push("", `--- current body of ${target} ---`, attrs.currentBody);
 			}
-			return lines.join("\n");
+			return projectEmission(lines.join("\n"));
 		}
-		const tokens =
-			attrs.beforeTokens != null
-				? ` ${attrs.beforeTokens}→${attrs.afterTokens} tokens`
-				: "";
-		if (!attrs.patch) return `# set ${target}${tokens}`;
-		return `# set ${target}${tokens}\n${attrs.patch}`;
+		return projectEmission(entry.body);
 	}
 
 	summary(entry) {
-		if (!entry.body) return "";
-		// Contract: summarized projections are ≤ SUMMARY_MAX_CHARS. The
-		// merge body for an edit can be many KB; truncate. The model
-		// reads the full body via promotion to visible if it needs the
-		// edit's exact content.
-		return entry.body.slice(0, SUMMARY_MAX_CHARS);
+		return summarizeEmission(entry.body);
 	}
 
-	// Walk the parsed marker operation list against a starting body, returning
-	// the final body or the first error. SEARCH/REPLACE and DELETE go through
-	// Hedberg.replace (fuzzy whitespace match); NEW/REPLACE/PREPEND/APPEND
-	// are direct string operations.
 	static #applyOperations(currentBody, operations) {
 		let body = currentBody;
 		for (const op of operations) {

package/src/plugins/set/setDoc.md

@@ -1,13 +1,18 @@
 ## <set path="{path}" tags="{topical,searchable,folksonomic,internal,tags}">[content or edit]</set> - Create, edit, or update an entry or file
 
-* The <set/> command requires HEREDOC string literal syntax
-* The <set/> command's SEARCH/REPLACE string literal syntax uses HEREDOC instead of git conflict markers
-* The `{SEARCH|REPLACE|NEW|APPEND|PREPEND|DELETE} Operative Labels determine the type of edit
+YOU SHOULD prefer minimal and multiple atomic edits to reduce the frequency and severity of conflicts and errors
 
-YOU MAY add additional characters to the Operative Labels to avoid collisions
+* The <set/> command requires matching HEREDOC label string literal syntax
+
+* Special Operative Labels: ({SEARCH|REPLACE|NEW|PREPEND|APPEND|DELETE}) dictate the type of edit
+	SEARCH/REPLACE - SEARCH/REPLACE string literal syntax uses HEREDOC in place of git conflict markers
+	NEW - Create (or clobber) entry content
+	PREPEND - Prepend content at beginning of existing entry
+	APPEND - Append content to end of existing entry
+	DELETE - Delete matching content in existing entry
 
 Example:
-	<set path="src/main.go" tags="go,source,unlinted"><<SEARCH
+	<set path="src/main.go"><<SEARCH
 	exact
 	text
 	to be
@@ -17,27 +22,23 @@ Example:
 	replacement
 	text
 	REPLACE</set>
-<!-- SEARCH/REPLACE: surgical edit, fuzzy on whitespace. Multiple pairs in one body apply in order. -->
 
 Example:
-	<set path="src/main.go"><<NEW
+	<set path="src/main.go" tags="go,source,unlinted"><<NEW
 	package main
 	
 	func main() {}
 	NEW</set>
-<!-- NEW: create with body content. -->
+
+Example:
+	<set path="known://plan" tags="docs"><<PREPEND0
+	Documenting the <<PREPEND label
+	PREPEND0</set>
 
 Example:
 	<set path="known://plan" tags="plan,project,todo"><<APPEND
 	- [ ] new task
 	APPEND</set>
-<!-- APPEND adds to the end; PREPEND to the start. -->
-
-Example:
-	<set path="known://plan" tags="docs"><<PREPEND0
-	Documenting the <<PREPEND label	
-	PREPEND0</set>
-<!-- APPEND adds to the end; PREPEND to the start. -->
 
 Example:
 	<set path="src/main.go"><<DELETE
@@ -49,4 +50,3 @@ Example:
 	<set path="docs/guide.md" tags="docs"><<GUIDE
 	The pair is <<SEARCH ... SEARCH<<REPLACE ... REPLACE.
 	GUIDE</set>
-<!-- Any IDENT brackets opaque body. Use a custom IDENT (GUIDE, EOF, DOC, file paths, etc.) for bodies that contain `<<` literally. -->

package/src/plugins/sh/sh.js

@@ -1,4 +1,9 @@
-import { logPathToDataBase, streamSummary } from "../helpers.js";
+import {
+	logPathToDataBase,
+	projectEmission,
+	streamSummary,
+	summarizeEmission,
+} from "../helpers.js";
 import docs from "./shDoc.js";
 
 const LOG_ACTION_RE = /^log:\/\/turn_\d+\/(\w+)\//;
@@ -8,10 +13,6 @@ export default class Sh {
 
 	constructor(core) {
 		this.#core = core;
-		// Streaming stdout/stderr is time-indexed activity output, not
-		// topic-indexed state — category="logging" so it renders in <log>
-		// adjacent to its action entry, not in <summary>/<visible> next
-		// to knowns and files. SPEC #streaming_entries.
 		core.registerScheme({ category: "logging" });
 		core.on("handler", this.handler.bind(this));
 		core.on("visible", this.full.bind(this));
@@ -46,13 +47,11 @@ export default class Sh {
 			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;
-		// 202 with command summary, empty body; stdout/stderr entries created on accept.
 		await store.set({
 			runId,
 			turn,
@@ -64,11 +63,14 @@ export default class Sh {
 		});
 	}
 
+	// log:// entries: emission, tab-indented. sh:// entries: stream bytes verbatim.
 	full(entry) {
-		return `# sh ${entry.attributes.command}\n${entry.body}`;
+		if (entry.path.startsWith("log://")) return projectEmission(entry.body);
+		return entry.body;
 	}
 
 	summary(entry) {
+		if (entry.path.startsWith("log://")) return summarizeEmission(entry.body);
 		return streamSummary("sh", entry);
 	}
 }

package/src/plugins/skill/skillDoc.md

@@ -1,4 +1,4 @@
-## <skill path="[path-or-url]"/> - Drop in a deep skill
+## <skill path="[path-or-url]"/> - Drop in a skill
 
 Example: <skill path="docs/refactoring.md"/>
 <!-- Single-file skill: archived at skill://refactoring (summarized). -->

package/src/plugins/unknown/README.md

@@ -9,7 +9,7 @@ The Rumsfeld mechanism. The model registers what it doesn't know before acting.
 - **Tool**: `unknown`
 - **Category**: `unknown`
 - **Handler**: None — recorded by TurnExecutor, deduplicated against existing unknowns.
-- **Filter**: `assembly.user` at priority 150 — renders `<unknowns>` after `<log>` (priority 100) and before `<instructions>` (priority 165) in the sandwich. Unknowns are active work, not stable environment state; they belong in the user packet.
+- **Filter**: `assembly.system` at priority 350 — renders `<unknowns>` at the bottom of the system message (after `<summary>` 200, `<visible>` 250, `<log>` 300). Open work surfaces alongside the rest of the accumulated state in system; the user message holds prompt + budget + per-turn requirements.
 
 ## Projection
 

package/src/plugins/unknown/unknown.js

@@ -9,10 +9,8 @@ export default class Unknown {
 		core.on("handler", this.handler.bind(this));
 		core.on("visible", this.full.bind(this));
 		core.on("summarized", this.summary.bind(this));
-		core.filter("assembly.user", this.assembleUnknowns.bind(this), 175);
-		// Hidden from the advertised tool list — the model writes unknowns
-		// via <set path="unknown://..."/>. The unknown:// scheme lifecycle
-		// is taught in instructions-user.md, not in a separate tooldoc.
+		core.filter("assembly.system", this.assembleUnknowns.bind(this), 350);
+		// Written via <set path="unknown://...">; lifecycle in instructions-user.md.
 		core.markHidden();
 	}
 
@@ -33,7 +31,6 @@ export default class Unknown {
 			return;
 		}
 
-		// tags > body for slug; lets the model round-trip via <get>.
 		const unknownPath = await store.slugPath(
 			runId,
 			"unknown",
@@ -54,7 +51,6 @@ export default class Unknown {
 		return entry.body;
 	}
 
-	// First SUMMARY_MAX_CHARS of the body. Matches <known> / <prompt>.
 	summary(entry) {
 		if (!entry.body) return "";
 		return entry.body.slice(0, SUMMARY_MAX_CHARS);

package/src/plugins/update/update.js

@@ -1,6 +1,7 @@
+import { projectEmission } from "../helpers.js";
 import docs from "./updateDoc.js";
 
-const CONTRACT_REMINDER = "Missing update";
+const CONTRACT_REMINDER = "UPDATE missing";
 
 const EMPTY_RESPONSE_REMINDER = "Response empty";
 
@@ -55,7 +56,7 @@ export default class Update {
 	}
 
 	full(entry) {
-		return `# update\n${entry.body}`;
+		return projectEmission(entry.body);
 	}
 
 	summary(entry) {

package/src/plugins/update/updateDoc.md

@@ -1,4 +1,4 @@
-## <update status="N">{ direct answer or one-line summary }</update> - Turn termination
+## <update status="N">{ direct one-line answer or one-line summary }</update> - Turn termination
 
 YOU MUST conclude every turn with one (and only one) <update status="N"></update>.
 YOU MUST keep the update body to <= 80 characters.