@possumtech/rummy 0.2.1

package/src/plugins/set/set.js

@@ -0,0 +1,268 @@
+import { readFileSync } from "node:fs";
+import KnownStore from "../../agent/KnownStore.js";
+import Hedberg, { generatePatch } from "../hedberg/hedberg.js";
+import { storePatternResult } from "../helpers.js";
+
+// biome-ignore lint/suspicious/noShadowRestrictedNames: tool name is "set"
+export default class Set {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme({
+			validStates: ["full", "proposed", "pass", "rejected", "error", "pattern"],
+		});
+		core.on("handler", this.handler.bind(this));
+		core.on("full", this.full.bind(this));
+		core.on("summary", this.summary.bind(this));
+		core.on("turn.proposing", this.#materializeRevisions.bind(this));
+		const docs = readFileSync(new URL("./docs.md", import.meta.url), "utf8");
+		core.filter("instructions.toolDocs", async (content) =>
+			content ? `${content}\n\n${docs}` : docs,
+		);
+	}
+
+	async handler(entry, rummy) {
+		const { entries: store, sequence: turn, runId } = rummy;
+		const attrs = entry.attributes;
+
+		if (attrs.blocks || attrs.search != null) {
+			await this.#processEdit(rummy, entry, attrs);
+			return;
+		}
+
+		if (attrs.preview && attrs.path) {
+			const matches = await store.getEntriesByPattern(
+				runId,
+				attrs.path,
+				attrs.body,
+			);
+			await storePatternResult(
+				store,
+				runId,
+				turn,
+				"set",
+				attrs.path,
+				attrs.body,
+				matches,
+				true,
+			);
+			return;
+		}
+
+		const target = attrs.path;
+		if (!target) return;
+
+		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, "", "proposed", {
+				attributes: { file: target, patch: udiff, merge },
+			});
+		} 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,
+			);
+		} else {
+			await store.upsert(runId, turn, target, entry.body, "full");
+		}
+	}
+
+	full(entry) {
+		const attrs = entry.attributes;
+		const file = attrs.file || entry.path;
+		if (attrs.error) return `# set ${file}\n${attrs.error}`;
+		const tokens =
+			attrs.beforeTokens != null
+				? ` ${attrs.beforeTokens}→${attrs.afterTokens} tokens`
+				: "";
+		if (!attrs.merge) return `# set ${file}${tokens}`;
+		return `# set ${file}${tokens}\n${attrs.merge}`;
+	}
+
+	summary(entry) {
+		return entry.attributes.merge || "";
+	}
+
+	async #processEdit(rummy, entry, attrs) {
+		const { entries: store, sequence: turn, runId } = rummy;
+		const target = attrs.path;
+		const matches = await store.getEntriesByPattern(runId, target, attrs.body);
+
+		if (matches.length === 0) {
+			await store.upsert(runId, turn, entry.resultPath, "", "error", {
+				attributes: { file: target, error: `${target} not found in context` },
+			});
+			return;
+		}
+
+		for (const match of matches) {
+			if (match.scheme === null) {
+				const canonicalPath = `set://${match.path}`;
+				const revision = Set.#buildRevision(attrs);
+				const existingAttrs = await rummy.getAttributes(canonicalPath);
+				const revisions = existingAttrs?.revisions || [];
+				revisions.push(revision);
+				await store.upsert(runId, turn, canonicalPath, "", "full", {
+					attributes: { file: match.path, revisions },
+				});
+				if (KnownStore.normalizePath(entry.resultPath) !== canonicalPath) {
+					await store.remove(runId, entry.resultPath);
+				}
+				return;
+			}
+
+			const { patch, searchText, replaceText, warning, error } =
+				Set.#applyRevision(match.body, attrs);
+
+			const state = error ? "error" : "pass";
+			const resultPath = `set://${match.path}`;
+			const udiff = patch ? generatePatch(match.path, match.body, patch) : null;
+			const merge =
+				searchText != null
+					? `<<<<<<< SEARCH\n${searchText}\n=======\n${replaceText}\n>>>>>>> REPLACE`
+					: null;
+			const beforeTokens = match.tokens_full || 0;
+			const afterTokens = patch ? (patch.length / 4) | 0 : beforeTokens;
+
+			await store.upsert(runId, turn, resultPath, match.body, state, {
+				attributes: {
+					file: match.path,
+					patch: udiff,
+					merge,
+					beforeTokens,
+					afterTokens,
+					warning,
+					error,
+				},
+			});
+
+			if (state === "pass" && patch) {
+				await store.upsert(runId, turn, match.path, patch, match.state);
+			}
+		}
+	}
+
+	async #materializeRevisions({ rummy }) {
+		const { entries: store, sequence: turn, runId } = rummy;
+		const setEntries = await store.getEntriesByPattern(runId, "set://*");
+
+		for (const entry of setEntries) {
+			const attrs =
+				typeof entry.attributes === "string"
+					? JSON.parse(entry.attributes)
+					: entry.attributes;
+			if (!attrs?.revisions?.length) continue;
+
+			const filePath = attrs.file;
+			const fileEntry = await store.getEntriesByPattern(runId, filePath);
+			if (fileEntry.length === 0) continue;
+
+			const original = fileEntry[0].body;
+			let current = original;
+			const mergeBlocks = [];
+			let lastError = null;
+			let lastWarning = null;
+
+			for (const rev of attrs.revisions) {
+				if (!rev) continue;
+				const { patch, searchText, replaceText, warning, error } =
+					Set.#applyRevision(current, rev);
+
+				if (error) lastError = error;
+				else if (patch) current = patch;
+				if (warning) lastWarning = warning;
+
+				if (searchText != null) {
+					mergeBlocks.push(
+						`<<<<<<< SEARCH\n${searchText}\n=======\n${replaceText}\n>>>>>>> REPLACE`,
+					);
+				}
+			}
+
+			const state = lastError ? "error" : "proposed";
+			const udiff =
+				current !== original
+					? generatePatch(filePath, original, current)
+					: null;
+			const merge = mergeBlocks.length > 0 ? mergeBlocks.join("\n") : null;
+			const beforeTokens = fileEntry[0].tokens_full || 0;
+			const afterTokens = current ? (current.length / 4) | 0 : beforeTokens;
+
+			await store.upsert(runId, turn, entry.path, original, state, {
+				attributes: {
+					file: filePath,
+					patch: udiff,
+					merge,
+					beforeTokens,
+					afterTokens,
+					warning: lastWarning,
+					error: lastError,
+				},
+			});
+		}
+	}
+
+	static #buildRevision(attrs) {
+		if (attrs.search != null) {
+			return { search: attrs.search, replace: attrs.replace ?? "" };
+		}
+		if (attrs.blocks?.length > 0) {
+			return {
+				search: attrs.blocks[0].search,
+				replace: attrs.blocks[0].replace,
+			};
+		}
+		return null;
+	}
+
+	static #applyRevision(body, attrs) {
+		if (attrs.search != null) {
+			return Hedberg.replace(body, attrs.search, attrs.replace ?? "", {
+				sed: attrs.sed,
+				flags: attrs.flags,
+			});
+		}
+		if (attrs.blocks?.length > 0 && attrs.blocks[0].search === null) {
+			return {
+				patch: attrs.blocks[0].replace,
+				searchText: null,
+				replaceText: attrs.blocks[0].replace,
+				warning: null,
+				error: null,
+			};
+		}
+		if (body && attrs.blocks?.length > 0) {
+			const block = attrs.blocks[0];
+			return Hedberg.replace(body, block.search, block.replace, {
+				sed: block.sed,
+				flags: block.flags,
+			});
+		}
+		return {
+			patch: null,
+			searchText: null,
+			replaceText: null,
+			warning: null,
+			error: null,
+		};
+	}
+}

package/src/plugins/sh/README.md

@@ -0,0 +1,18 @@
+# sh
+
+Proposes shell command execution for client approval.
+
+## Registration
+
+- **Tool**: `sh`
+- **Modes**: act only
+- **Category**: act
+- **Handler**: Upserts the entry as `proposed` state. The client must approve execution.
+
+## Projection
+
+Shows `sh {command}` followed by the entry body.
+
+## Behavior
+
+All shell commands require client-side approval — nothing executes server-side. Act mode only; blocked in ask mode.

package/src/plugins/sh/docs.md

@@ -0,0 +1,2 @@
+## <sh>[command]</sh> - Run a shell command with side effects
+Example: <sh>npm install</sh>

package/src/plugins/sh/sh.js

@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+
+export default class Sh {
+	#core;
+
+	constructor(core) {
+		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));
+		const docs = readFileSync(new URL("./docs.md", import.meta.url), "utf8");
+		core.filter("instructions.toolDocs", async (content) =>
+			content ? `${content}\n\n${docs}` : docs,
+		);
+	}
+
+	async handler(entry, rummy) {
+		const { entries: store, sequence: turn, runId } = rummy;
+		await store.upsert(runId, turn, entry.resultPath, entry.body, "proposed", {
+			attributes: entry.attributes,
+		});
+	}
+
+	full(entry) {
+		return `# sh ${entry.attributes.command || ""}\n${entry.body}`;
+	}
+
+	summary(entry) {
+		return entry.attributes.command || "";
+	}
+}

package/src/plugins/skills/README.md

@@ -0,0 +1,25 @@
+# skills
+
+Manages skills and personas via RPC methods. Skills are stackable per-run entries; personas are exclusive per-run configuration.
+
+## Registration
+
+- **No tool handler** — registers RPC methods on `hooks.rpc.registry`.
+
+## RPC Methods
+
+### Skills
+- `skill/add` — Load a skill from `config/skills/{name}.md` into the run as a `skill://` entry at full state.
+- `skill/remove` — Remove a skill entry from a run.
+- `getSkills` — List active skills on a run.
+- `listSkills` — List available skill files from disk.
+
+### Personas
+- `persona/set` — Set persona on a run. Load from `config/personas/{name}.md` by name, pass raw text, or clear by omitting both.
+- `listPersonas` — List available persona files from disk.
+
+## Behavior
+
+- Skills stack: multiple skills can be active on a run simultaneously as separate `skill://` entries.
+- Personas are exclusive: setting a persona replaces the previous one (stored as a run column, not an entry).
+- File paths resolve from `RUMMY_HOME` environment variable.

package/src/plugins/skills/skills.js

@@ -0,0 +1,175 @@
+import fs from "node:fs/promises";
+import { join } from "node:path";
+
+export default class Skills {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme({
+			name: "skill",
+			validStates: ["full", "stored"],
+			category: "knowledge",
+		});
+		const r = core.hooks.rpc.registry;
+
+		r.register("skill/add", {
+			handler: async (params, ctx) => {
+				if (!params.name) throw new Error("name is required");
+				if (!params.run) throw new Error("run is required");
+
+				const runRow = await ctx.db.get_run_by_alias.get({ alias: params.run });
+				if (!runRow) throw new Error(`Run not found: ${params.run}`);
+
+				const body = await loadFile("skills", params.name);
+				const store = ctx.projectAgent.entries;
+				await store.upsert(
+					runRow.id,
+					runRow.next_turn,
+					`skill://${params.name}`,
+					body,
+					"full",
+					{
+						attributes: {
+							name: params.name,
+							source: filePath("skills", params.name),
+						},
+					},
+				);
+
+				return { status: "ok", skill: params.name };
+			},
+			description:
+				"Add a skill to a run. Reads from RUMMY_HOME/skills/{name}.md.",
+			params: {
+				run: "string — run alias",
+				name: "string — skill name (filename without .md)",
+			},
+			requiresInit: true,
+		});
+
+		r.register("skill/remove", {
+			handler: async (params, ctx) => {
+				if (!params.name) throw new Error("name is required");
+				if (!params.run) throw new Error("run is required");
+
+				const runRow = await ctx.db.get_run_by_alias.get({ alias: params.run });
+				if (!runRow) throw new Error(`Run not found: ${params.run}`);
+
+				const store = ctx.projectAgent.entries;
+				await store.remove(runRow.id, `skill://${params.name}`);
+
+				return { status: "ok" };
+			},
+			description: "Remove a skill from a run.",
+			params: {
+				run: "string — run alias",
+				name: "string — skill name",
+			},
+			requiresInit: true,
+		});
+
+		r.register("getSkills", {
+			handler: async (params, ctx) => {
+				if (!params.run) throw new Error("run is required");
+
+				const runRow = await ctx.db.get_run_by_alias.get({ alias: params.run });
+				if (!runRow) throw new Error(`Run not found: ${params.run}`);
+
+				const store = ctx.projectAgent.entries;
+				const entries = await store.getEntriesByPattern(
+					runRow.id,
+					"skill://*",
+					null,
+				);
+				return entries.map((e) => ({
+					name: e.path.replace("skill://", ""),
+					state: e.state,
+				}));
+			},
+			description: "List skills active on a run. Returns [{ name, state }].",
+			params: { run: "string — run alias" },
+			requiresInit: true,
+		});
+
+		r.register("listSkills", {
+			handler: async () => listAvailable("skills"),
+			description: "List available skill files. Returns [{ name, path }].",
+			requiresInit: true,
+		});
+
+		r.register("persona/set", {
+			handler: async (params, ctx) => {
+				if (!params.run) throw new Error("run is required");
+
+				const runRow = await ctx.db.get_run_by_alias.get({ alias: params.run });
+				if (!runRow) throw new Error(`Run not found: ${params.run}`);
+
+				let text = params.text;
+				if (params.name && !text) {
+					text = await loadFile("personas", params.name);
+				}
+
+				await ctx.db.update_run_config.run({
+					id: runRow.id,
+					temperature: null,
+					persona: text || null,
+					context_limit: null,
+					model: null,
+				});
+
+				return { status: "ok" };
+			},
+			description:
+				"Set persona on a run. Pass name or text. Pass neither to clear.",
+			params: {
+				run: "string — run alias",
+				name: "string? — persona filename (without .md)",
+				text: "string? — raw persona text (overrides name)",
+			},
+			requiresInit: true,
+		});
+
+		r.register("listPersonas", {
+			handler: async () => listAvailable("personas"),
+			description: "List available persona files. Returns [{ name, path }].",
+			requiresInit: true,
+		});
+	}
+}
+
+function configDir(subfolder) {
+	const home = process.env.RUMMY_HOME;
+	if (home) return join(home, subfolder);
+	return null;
+}
+
+function filePath(subfolder, name) {
+	const dir = configDir(subfolder);
+	if (!dir) return null;
+	return join(dir, `${name}.md`);
+}
+
+async function loadFile(subfolder, name) {
+	const path = filePath(subfolder, name);
+	if (!path) throw new Error("RUMMY_HOME not configured");
+	try {
+		return await fs.readFile(path, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") throw new Error(`Not found: ${path}`);
+		throw err;
+	}
+}
+
+async function listAvailable(subfolder) {
+	const dir = configDir(subfolder);
+	if (!dir) return [];
+	try {
+		const files = await fs.readdir(dir);
+		return files
+			.filter((f) => f.endsWith(".md"))
+			.map((f) => ({ name: f.replace(".md", ""), path: join(dir, f) }));
+	} catch {
+		return [];
+	}
+}

package/src/plugins/store/README.md

@@ -0,0 +1,20 @@
+# store
+
+Demotes entries from active context to stored (background) state.
+
+## Registration
+
+- **Tool**: `store`
+- **Modes**: ask, act
+- **Category**: ask
+- **Handler**: Matches entries by pattern, demotes them via `demoteByPattern`, and records the result.
+
+## Projection
+
+Shows `store {path}`.
+
+## Behavior
+
+- Pattern queries (globs or body filters) produce a summary of matched paths.
+- Exact path queries report "{path} stored" or "{path} not found".
+- Stored entries remain in the database but are excluded from model context.

package/src/plugins/store/docs.md

@@ -0,0 +1,5 @@
+## <store path="[path/to/file]"/> - Store a file or entry
+Example: <store path="src/config.js"/>
+Example: <store path="unknown://42"/>
+* <store/> removes the file or entry from context, but does not delete it
+* A stored file or entry can be restored with <get/>

package/src/plugins/store/store.js

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs";
+import { storePatternResult } from "../helpers.js";
+
+export default class Store {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme({ validStates: ["full", "stored", "pattern"] });
+		core.on("handler", this.handler.bind(this));
+		core.on("full", this.full.bind(this));
+		core.on("summary", this.summary.bind(this));
+		const docs = readFileSync(new URL("./docs.md", import.meta.url), "utf8");
+		core.filter("instructions.toolDocs", async (content) =>
+			content ? `${content}\n\n${docs}` : docs,
+		);
+	}
+
+	async handler(entry, rummy) {
+		const { entries: store, sequence: turn, runId } = rummy;
+		const target = entry.attributes.path;
+		const bodyFilter = entry.attributes.body || null;
+		const isPattern = bodyFilter || target.includes("*");
+		const matches = await store.getEntriesByPattern(runId, target, bodyFilter);
+		await store.demoteByPattern(runId, target, bodyFilter);
+
+		if (isPattern) {
+			await storePatternResult(
+				store,
+				runId,
+				turn,
+				"store",
+				target,
+				bodyFilter,
+				matches,
+			);
+		} else {
+			const paths = matches.map((m) => m.path).join(", ");
+			const body =
+				matches.length > 0 ? `${paths} stored` : `${target} not found`;
+			await store.upsert(runId, turn, entry.resultPath, body, "stored");
+		}
+	}
+
+	full(entry) {
+		return `# store ${entry.attributes.path || entry.path}`;
+	}
+
+	summary(entry) {
+		return this.full(entry);
+	}
+}

package/src/plugins/summarize/README.md

@@ -0,0 +1,18 @@
+# summarize
+
+Structural tool for model-generated summaries.
+
+## Registration
+
+- **Tool**: `summarize`
+- **Modes**: ask, act
+- **Category**: structural
+- **Handler**: None — projection only.
+
+## Projection
+
+Shows `summarize` followed by the entry body.
+
+## Behavior
+
+No handler logic. The tool registration exists so the model can emit summary entries that appear in context via projection.

package/src/plugins/summarize/docs.md

@@ -0,0 +1,4 @@
+## <summarize>[Answer or summary]</summarize>
+* Describe the final state
+* ONLY use if done
+* Keep brief (<= 80 characters)

package/src/plugins/summarize/summarize.js

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+
+export default class Summarize {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme({ validStates: ["summary"], category: "structural" });
+		core.on("full", this.full.bind(this));
+		core.on("summary", this.summary.bind(this));
+		const docs = readFileSync(new URL("./docs.md", import.meta.url), "utf8");
+		core.filter("instructions.toolDocs", async (content) =>
+			content ? `${content}\n\n${docs}` : docs,
+		);
+	}
+
+	full(entry) {
+		return `# summarize\n${entry.body}`;
+	}
+
+	summary(entry) {
+		return this.full(entry);
+	}
+}

package/src/plugins/telemetry/README.md

@@ -0,0 +1,19 @@
+# telemetry
+
+Console logging for RPC lifecycle and turn events.
+
+## Files
+
+- **telemetry.js** — Plugin registration. Hooks into `rpc.started`, `rpc.completed`, `rpc.error`, and `run.step.completed`.
+- **RunDumper.js** — Dumps a run's complete exchange to a readable text file. Active when `RUMMY_DEBUG=true`.
+- **rpc_log.sql** — SQL for RPC audit logging.
+
+## Registration
+
+- **No tool handler** — hooks into RPC and run lifecycle events.
+
+## Behavior
+
+- Logs RPC method calls with timing (elapsed seconds) and contextual summaries (prompt text, run alias, resolution action).
+- Errors are logged with their message.
+- Turn completion debug logging is gated behind `RUMMY_DEBUG=true`.