@possumtech/rummy 0.2.7 → 0.3.0

package/src/plugins/mv/mv.js

@@ -1,26 +1,28 @@
-import { readFileSync } from "node:fs";
 import KnownStore from "../../agent/KnownStore.js";
+import docs from "./mvDoc.js";
 
 export default class Mv {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
-		core.registerScheme({
-			validStates: ["full", "proposed", "pass", "rejected", "error", "pattern"],
-		});
+		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,
-		);
+		core.filter("instructions.toolDocs", async (docsMap) => {
+			docsMap.mv = docs;
+			return docsMap;
+		});
 	}
 
 	async handler(entry, rummy) {
-		const { entries: store, sequence: turn, runId } = rummy;
+		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const { path, to } = entry.attributes;
+		const VALID = { stored: 1, summary: 1, index: 1, full: 1 };
+		const fidelity = VALID[entry.attributes.fidelity]
+			? entry.attributes.fidelity
+			: undefined;
 
 		const source = await store.getBody(runId, path);
 		if (source === null) return;
@@ -34,14 +36,16 @@ export default class Mv {
 
 		const body = `${path} ${to}`;
 		if (destScheme === null) {
-			await store.upsert(runId, turn, entry.resultPath, body, "proposed", {
+			await store.upsert(runId, turn, entry.resultPath, body, 202, {
 				attributes: { from: path, to, isMove: true, warning },
+				loopId,
 			});
 		} else {
-			await store.upsert(runId, turn, to, source, "full");
+			await store.upsert(runId, turn, to, source, 200, { fidelity, loopId });
 			await store.remove(runId, path);
-			await store.upsert(runId, turn, entry.resultPath, body, "pass", {
+			await store.upsert(runId, turn, entry.resultPath, body, 200, {
 				attributes: { from: path, to, isMove: true, warning },
+				loopId,
 			});
 		}
 	}

package/src/plugins/mv/mvDoc.js

@@ -0,0 +1,31 @@
+// Tool doc for <mv>. Each entry: [text, rationale].
+// 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.",
+	],
+	[
+		'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.",
+	],
+
+	// --- Constraints
+	[
+		"* Source path accepts globs 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.",
+	],
+];
+
+export default LINES.map(([text]) => text).join("\n");

package/src/plugins/persona/persona.js

@@ -0,0 +1,78 @@
+import fs from "node:fs/promises";
+import { join } from "node:path";
+
+export default class Persona {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		const r = core.hooks.rpc.registry;
+
+		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(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 () => {
+				const dir = configDir();
+				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 [];
+				}
+			},
+			description: "List available persona files. Returns [{ name, path }].",
+			requiresInit: true,
+		});
+	}
+}
+
+function configDir() {
+	const home = process.env.RUMMY_HOME;
+	if (home) return join(home, "personas");
+	return null;
+}
+
+async function loadFile(name) {
+	const dir = configDir();
+	if (!dir) throw new Error("RUMMY_HOME not configured");
+	const path = join(dir, `${name}.md`);
+	try {
+		return await fs.readFile(path, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") throw new Error(`Not found: ${path}`);
+		throw err;
+	}
+}

package/src/plugins/previous/README.md

@@ -10,6 +10,6 @@ history from prior ask/act invocations on this run.
 
 ## Behavior
 
-Filters turn_context rows where `category` is `result` or `structural`
+Filters turn_context rows where `category` is `logging` or `prompt`
 and `source_turn < loopStartTurn`. Renders each entry chronologically
-with status symbols (✓/✗/·).
+with turn number and status.

package/src/plugins/previous/previous.js

@@ -11,32 +11,36 @@ export default class Previous {
 
 		const entries = ctx.rows.filter(
 			(r) =>
-				(r.category === "result" || r.category === "structural") &&
+				(r.category === "logging" || r.category === "prompt") &&
 				r.source_turn < ctx.loopStartTurn,
 		);
 		if (entries.length === 0) return content;
 
 		const lines = await Promise.all(
-			entries.map((e) => renderToolTag(e, "summary", this.#core)),
+			entries.map((e) => renderToolTag(e, this.#core)),
 		);
 		return `${content}\n\n<previous>\n${lines.join("\n")}\n</previous>`;
 	}
 }
 
-async function renderToolTag(entry, fidelity, core) {
+async function renderToolTag(entry, core) {
 	const attrs =
 		typeof entry.attributes === "string"
 			? JSON.parse(entry.attributes)
 			: entry.attributes;
 
-	const path = `${entry.scheme}://${attrs?.path || attrs?.file || attrs?.command || ""}`;
-	const status = entry.state ? ` status="${entry.state}"` : "";
+	const target = attrs?.path || attrs?.file || attrs?.command || "";
+	const turn = entry.source_turn ? ` turn="${entry.source_turn}"` : "";
+	const status = entry.status ? ` status="${entry.status}"` : "";
+	const summary =
+		typeof attrs?.summary === "string"
+			? ` summary="${attrs.summary.slice(0, 80)}"`
+			: "";
 
 	let body;
 	try {
 		body = await core.hooks.tools.view(entry.scheme, {
 			...entry,
-			fidelity,
 			attributes: attrs,
 		});
 	} catch {
@@ -44,7 +48,7 @@ async function renderToolTag(entry, fidelity, core) {
 	}
 
 	if (body) {
-		return `<tool path="${path}"${status}>${body}</tool>`;
+		return `<${entry.scheme} path="${target}"${turn}${status}${summary}>${body}</${entry.scheme}>`;
 	}
-	return `<tool path="${path}"${status}/>`;
+	return `<${entry.scheme} path="${target}"${turn}${status}${summary}/>`;
 }

package/src/plugins/progress/progress.js

@@ -7,31 +7,63 @@ export default class Progress {
 	}
 
 	async assembleProgress(content, ctx) {
-		const usedTokens = ctx.rows.reduce((sum, r) => sum + (r.tokens || 0), 0);
+		// Use last turn's real assembled token count when available.
+		// Falls back to row token sum (less accurate — missing system prompt overhead).
+		const rowTokens = ctx.rows.reduce((sum, r) => sum + (r.tokens || 0), 0);
+		const usedTokens = ctx.lastContextTokens || rowTokens;
 		const contextSize = ctx.contextSize || 0;
 		const pct = contextSize ? Math.round((usedTokens / contextSize) * 100) : 0;
 
+		// Fidelity distribution across known/file entries
+		const entries = ctx.rows.filter((r) => r.category === "data");
+		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), 0);
+		const summaryTokens = summaryEntries.reduce(
+			(s, r) => s + (r.tokens || 0),
+			0,
+		);
+		const indexTokens = indexEntries.reduce((s, r) => s + (r.tokens || 0), 0);
+
 		const unknownCount = ctx.rows.filter(
 			(r) => r.category === "unknown",
 		).length;
 
 		const hasCurrent = ctx.rows.some(
-			(r) =>
-				(r.category === "result" || r.category === "structural") &&
-				r.source_turn >= ctx.loopStartTurn,
+			(r) => r.category === "logging" && r.source_turn >= ctx.loopStartTurn,
 		);
 
 		const parts = [];
 
-		const tokenInfo = contextSize
-			? `${usedTokens} of ${contextSize} tokens (${pct}%)`
+		const knownCount = entries.length;
+		const tokenLine = contextSize
+			? `${usedTokens} of ${contextSize} tokens (${pct}%) · ${knownCount} known${knownCount !== 1 ? "s" : ""} · ${unknownCount} unknown${unknownCount !== 1 ? "s" : ""}`
 			: "";
-		const unknownInfo =
-			unknownCount > 0
-				? `${unknownCount} unknown${unknownCount > 1 ? "s" : ""} remaining`
-				: "0 unknowns";
-		const status = [tokenInfo, unknownInfo].filter(Boolean).join(" · ");
-		if (status) parts.push(status);
+		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 (pct > 75) {
+			parts.push(
+				'Context above 75%. YOU MUST free space: <set fidelity="summary" summary="topic,detail,keyword"/>, <set fidelity="archive"/>, or <rm/>. Target the largest entries.',
+			);
+		} else if (pct > 50) {
+			parts.push(
+				'Context above 50%. You may free space: <set fidelity="summary" summary="topic,detail,keyword"/>, <set fidelity="archive"/>, or <rm/>.',
+			);
+		}
 
 		if (hasCurrent) {
 			parts.push(

package/src/plugins/prompt/README.md

@@ -1,6 +1,6 @@
 # prompt
 
-Renders the `<ask>` or `<act>` tag at the end of the user message.
+Renders the `<prompt mode="ask|act">` tag at the end of the user message.
 Always present on every turn — the model always sees its task.
 
 ## Registration
@@ -9,8 +9,8 @@ Always present on every turn — the model always sees its task.
 
 ## Behavior
 
-Finds the latest `ask://` or `act://` entry in the turn_context rows.
-Renders with `tools` attribute (available tool list) and optional `warn`
-attribute in ask mode ("File and system modification prohibited on this
-turn."). Falls back to the mode passed by the core if no prompt entry
+Finds the latest `prompt://` entry in the turn_context rows. The mode
+(`ask` or `act`) is stored in `attributes.mode`. Renders with `tools`
+attribute (available tool list) and optional `warn` attribute in ask
+mode. Falls back to the mode passed by the core if no prompt entry
 exists.

package/src/plugins/prompt/prompt.js

@@ -3,43 +3,47 @@ export default class Prompt {
 
 	constructor(core) {
 		this.#core = core;
+		core.hooks.tools.onView("prompt", (entry) => entry.body);
+		core.hooks.tools.onView("progress", (entry) => entry.body);
 		core.on("turn.started", this.onTurnStarted.bind(this));
 		core.filter("assembly.user", this.assemblePrompt.bind(this), 300);
 	}
 
 	async onTurnStarted({ rummy, mode, prompt, isContinuation }) {
-		const { entries: store, sequence: turn, runId } = rummy;
+		const { entries: store, sequence: turn, runId, loopId } = rummy;
 
 		if (!isContinuation && prompt) {
-			await store.upsert(runId, turn, `prompt://${turn}`, "", "info", {
+			await store.upsert(runId, turn, `prompt://${turn}`, prompt, 200, {
 				attributes: { mode },
+				loopId,
 			});
-			await store.upsert(runId, turn, `${mode}://${turn}`, prompt, "info");
 		} else {
-			await store.upsert(
-				runId,
-				turn,
-				`progress://${turn}`,
-				prompt || "",
-				"info",
-			);
+			await store.upsert(runId, turn, `progress://${turn}`, prompt || "", 200, {
+				loopId,
+			});
 		}
 	}
 
 	async assemblePrompt(content, ctx) {
 		const promptEntry = ctx.rows.findLast(
-			(r) =>
-				r.category === "prompt" && (r.scheme === "ask" || r.scheme === "act"),
+			(r) => r.category === "prompt" && r.scheme === "prompt",
 		);
 
-		const mode = promptEntry?.scheme || ctx.type;
+		const attrs =
+			typeof promptEntry?.attributes === "string"
+				? JSON.parse(promptEntry.attributes)
+				: promptEntry?.attributes;
+		const mode = attrs?.mode || ctx.type;
 		const body = promptEntry?.body || "";
-		const tools = this.#core.hooks.tools.namesForMode(mode).join(", ");
-		const warn =
-			mode === "ask"
-				? ' warn="File and system modification prohibited on this turn."'
-				: "";
+		const toolNames = ctx.toolSet
+			? [...ctx.toolSet]
+			: [...this.#core.hooks.tools.resolveForLoop(mode)];
+		const tools = toolNames.join(",");
+		let warn = "";
+		if (mode === "ask") warn = ' warn="File editing disallowed."';
+		if (mode === "panic")
+			warn = ' warn="Context overflow. Free space to continue."';
 
-		return `${content}<${mode} tools="${tools}"${warn}>${body}</${mode}>`;
+		return `${content}<prompt mode="${mode}" tools="${tools}"${warn}>${body}</prompt>`;
 	}
 }

package/src/plugins/rm/README.md

@@ -5,9 +5,8 @@ Removes entries by path or glob pattern.
 ## Registration
 
 - **Tool**: `rm`
-- **Modes**: ask, act
-- **Category**: act
-- **Handler**: Matches entries by pattern. K/V entries are removed immediately (`pass`); file entries produce `proposed` state for client approval.
+- **Category**: `logging`
+- **Handler**: Matches entries by pattern. Scheme entries are removed immediately (status 200); file entries produce status 202 (proposed) for client approval.
 
 ## Projection
 
@@ -15,4 +14,5 @@ Shows `rm {path}`.
 
 ## Behavior
 
-Supports glob patterns and body filters via `getEntriesByPattern`. Each matched entry is processed independently.
+Supports glob patterns and body filters via `getEntriesByPattern`. Each
+matched entry is processed independently.

package/src/plugins/rm/rm.js

@@ -1,41 +1,58 @@
-import { readFileSync } from "node:fs";
+import KnownStore from "../../agent/KnownStore.js";
+import docs from "./rmDoc.js";
 
 export default class Rm {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
-		core.registerScheme({
-			validStates: ["full", "proposed", "pass", "rejected", "error", "pattern"],
-		});
+		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,
-		);
+		core.filter("instructions.toolDocs", async (docsMap) => {
+			docsMap.rm = docs;
+			return docsMap;
+		});
 	}
 
 	async handler(entry, rummy) {
-		const { entries: store, sequence: turn, runId } = rummy;
+		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const target = entry.attributes.path;
+		if (!target) {
+			await store.upsert(runId, turn, entry.resultPath, "", 400, {
+				attributes: { error: "path is required" },
+				loopId,
+			});
+			return;
+		}
+		const normalized = KnownStore.normalizePath(target);
 		const matches = await store.getEntriesByPattern(
 			runId,
-			target,
+			normalized,
 			entry.attributes.body,
 		);
 
+		if (matches.length === 0) {
+			await store.upsert(runId, turn, entry.resultPath, "", 404, {
+				attributes: { path: target, error: `${target} not found` },
+				loopId,
+			});
+			return;
+		}
+
 		for (const match of matches) {
 			const resultPath = `rm://${match.path}`;
 			if (match.scheme === null) {
-				await store.upsert(runId, turn, resultPath, match.path, "proposed", {
+				await store.upsert(runId, turn, resultPath, match.path, 202, {
 					attributes: { path: match.path },
+					loopId,
 				});
 			} else {
 				await store.remove(runId, match.path);
-				await store.upsert(runId, turn, resultPath, match.path, "pass", {
+				await store.upsert(runId, turn, resultPath, match.path, 200, {
 					attributes: { path: match.path },
+					loopId,
 				});
 			}
 		}

package/src/plugins/rm/rmDoc.js

@@ -0,0 +1,30 @@
+// Tool doc for <rm>. Each entry: [text, rationale].
+// 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://donald-rumsfeld-was-born-in-1932"/>',
+		"Shows the slugified path convention. Model sees these paths in <knowns> section.",
+	],
+	[
+		'Example: <rm path="known://temp_*" preview/>',
+		"Preview before deleting. Glob pattern. 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.",
+	],
+	[
+		"* Paths accept globs — use `preview` to check matches first",
+		"Reinforces preview safety pattern. Prevents accidental bulk deletion.",
+	],
+];
+
+export default LINES.map(([text]) => text).join("\n");

package/src/plugins/rpc/README.md

@@ -1,45 +1,32 @@
 # rpc
 
-Registers all core RPC methods and dispatches client operations through the tool handler chain.
+Registers core RPC methods and provides automatic tool dispatch for
+all registered tools.
 
 ## Registration
 
-- **No tool handler** — this plugin registers RPC methods on `hooks.rpc.registry`, not tool handlers.
+- **No tool handler** — registers RPC methods on `hooks.rpc.registry`.
+- **Tool fallback** — any registered tool is automatically callable via
+  RPC without explicit registration. Third-party plugins get RPC for free.
 
 ## RPC Methods
 
 ### Protocol
-- `ping` — liveness check.
-- `discover` — returns method/notification catalog.
-- `init` — initialize project (sets projectId, projectRoot, configPath).
+- `ping`, `discover`, `init`
 
 ### Models
-- `getModels`, `addModel`, `removeModel` — CRUD for model aliases.
+- `getModels`, `addModel`, `removeModel`
 
-### Entry Operations
-- `read` — promote entry to full state, or create persistent file constraint.
-- `store` — demote entry to stored state, or manage file constraints (ignore/clear).
-- `write` — create/update entry. K/V paths write directly; file paths dispatch through `set` handler.
-- `delete` — remove entry via `rm` handler dispatch.
+### Entry Operations (all dispatch through tool handler chain)
+- `get` — promote entry; with `persist` flag, also sets file constraint.
+- `store` — demote entry or manage file constraints (not a model tool).
+- All other registered tools — auto-dispatched via tool fallback.
 - `getEntries` — query entries by glob pattern.
 
 ### Runs
-- `startRun` — pre-create a run with model/config.
-- `ask` — non-mutating model query.
-- `act` — mutating model directive.
-- `run/resolve` — resolve a proposed entry (accept/reject).
-- `run/abort` — abort an in-flight run.
-- `run/rename` — rename a run alias.
-- `run/inject` — inject a message into an idle or active run.
-- `run/config` — update run parameters (temperature, persona, context_limit, model).
-- `getRuns`, `getRun` — query run list and full run detail.
+- `startRun`, `ask`, `act`
+- `run/resolve`, `run/abort`, `run/rename`, `run/inject`, `run/config`
+- `getRuns`, `getRun`
 
 ### Notifications
-- `run/state` — turn state update with history, unknowns, proposed, telemetry.
-- `run/progress` — turn status (thinking/processing).
-- `ui/render` — streaming output.
-- `ui/notify` — toast notification.
-
-## Behavior
-
-Client operations (read, write, delete, store) build a `RummyContext` for the target run and dispatch through the same handler chain as model operations via `dispatchTool`.
+- `run/state`, `run/progress`, `ui/render`, `ui/notify`