@possumtech/rummy 0.4.0 → 2.0.0

package/src/plugins/openrouter/openrouter.js

@@ -0,0 +1,121 @@
+import msg from "../../agent/messages.js";
+
+const FETCH_TIMEOUT = Number(process.env.RUMMY_FETCH_TIMEOUT);
+if (!FETCH_TIMEOUT) throw new Error("RUMMY_FETCH_TIMEOUT must be set");
+
+const PROVIDER = "openrouter";
+
+/**
+ * OpenRouter LLM provider plugin. Handles model aliases of the form
+ * `openrouter/{publisher}/{modelName}`. Strips only the provider
+ * segment — OpenRouter's own API expects the `publisher/model` form,
+ * so that's exactly what's passed through to it (e.g.
+ * `openrouter/anthropic/claude-3-opus` → API receives
+ * `anthropic/claude-3-opus`).
+ *
+ * Inert if OPENROUTER_API_KEY / OPENROUTER_BASE_URL aren't set.
+ */
+export default class OpenRouter {
+	#apiKey;
+	#baseUrl;
+	#contextCache = new Map();
+
+	constructor(core) {
+		const apiKey = process.env.OPENROUTER_API_KEY;
+		const baseUrl = process.env.OPENROUTER_BASE_URL;
+		if (!apiKey || !baseUrl) return;
+		this.#apiKey = apiKey;
+		this.#baseUrl = baseUrl;
+
+		const wireModel = (alias) => alias.split("/").slice(1).join("/");
+
+		core.hooks.llm.providers.push({
+			name: PROVIDER,
+			matches: (model) => model.split("/")[0] === PROVIDER,
+			completion: (messages, model, options) =>
+				this.#completion(messages, wireModel(model), options),
+			getContextSize: (model) => this.#getContextSize(wireModel(model)),
+		});
+	}
+
+	async #completion(messages, model, options = {}) {
+		const body = { model, messages, include_reasoning: true };
+		if (options.temperature !== undefined)
+			body.temperature = options.temperature;
+
+		const timeoutSignal = AbortSignal.timeout(FETCH_TIMEOUT);
+		const signal = options.signal
+			? AbortSignal.any([options.signal, timeoutSignal])
+			: timeoutSignal;
+
+		const response = await fetch(`${this.#baseUrl}/chat/completions`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${this.#apiKey}`,
+				"Content-Type": "application/json",
+				"HTTP-Referer": process.env.RUMMY_HTTP_REFERER,
+				"X-Title": process.env.RUMMY_X_TITLE,
+			},
+			body: JSON.stringify(body),
+			signal,
+		});
+
+		if (!response.ok) {
+			const error = await response.text();
+			if (response.status === 401 || response.status === 403) {
+				throw new Error(
+					msg("error.openrouter_auth", {
+						status: `${response.status} - ${error}`,
+					}),
+				);
+			}
+			throw new Error(
+				msg("error.openrouter_api", {
+					status: `${response.status} - ${error}`,
+				}),
+			);
+		}
+		const data = await response.json();
+
+		for (const choice of data.choices) {
+			const cm = choice.message;
+			if (!cm) continue;
+			const details = cm.reasoning_details
+				? cm.reasoning_details.map((d) => d.text)
+				: [];
+			const parts = [
+				cm.reasoning_content,
+				cm.reasoning,
+				cm.thinking,
+				...details,
+			].filter(Boolean);
+			cm.reasoning_content =
+				parts.length > 0 ? [...new Set(parts)].join("\n") : null;
+		}
+
+		return data;
+	}
+
+	async #getContextSize(model) {
+		if (this.#contextCache.has(model)) return this.#contextCache.get(model);
+
+		const res = await fetch(`${this.#baseUrl}/models`, {
+			headers: { Authorization: `Bearer ${this.#apiKey}` },
+			signal: AbortSignal.timeout(5000),
+		});
+		if (!res.ok) {
+			throw new Error(
+				`OpenRouter /models returned ${res.status}; cannot resolve context size for "${model}".`,
+			);
+		}
+		const data = await res.json();
+		const entry = data.data?.find((m) => m.id === model);
+		if (!entry?.context_length) {
+			throw new Error(
+				`OpenRouter /models has no context_length for "${model}".`,
+			);
+		}
+		this.#contextCache.set(model, entry.context_length);
+		return entry.context_length;
+	}
+}

package/src/plugins/persona/README.md

@@ -0,0 +1,20 @@
+# persona {#persona_plugin}
+
+Runtime persona management. A persona is free-form text that gets
+prepended to the model's system prompt for a run.
+
+## Files
+
+- **persona.js** — RPC registration and persona file loading.
+
+## RPC Methods
+
+| Method | Params | Notes |
+|--------|--------|-------|
+| `persona/set` | `{ run, name?, text? }` | Set persona by filename (`${RUMMY_HOME}/personas/<name>.md`) or raw text. Pass neither to clear. |
+| `listPersonas` | — | Return `[{name, path}]` for available persona files. |
+
+## Behavior
+
+Persona is stored on the run row (`runs.persona`). The instructions
+plugin reads it during system-prompt assembly.

package/src/plugins/persona/persona.js

@@ -20,10 +20,13 @@ export default class Persona {
 					text = await loadFile(params.name);
 				}
 
+				// "Pass neither to clear" — empty string counts as clear too.
+				let persona = null;
+				if (text) persona = text;
 				await ctx.db.update_run_config.run({
 					id: runRow.id,
 					temperature: null,
-					persona: text || null,
+					persona,
 					context_limit: null,
 					model: null,
 				});
@@ -44,14 +47,10 @@ export default class Persona {
 			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 [];
-				}
+				const files = await fs.readdir(dir);
+				return files
+					.filter((f) => f.endsWith(".md"))
+					.map((f) => ({ name: f.replace(".md", ""), path: join(dir, f) }));
 			},
 			description: "List available persona files. Returns [{ name, path }].",
 			requiresInit: true,
@@ -68,11 +67,5 @@ function configDir() {
 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;
-	}
+	return fs.readFile(join(dir, `${name}.md`), "utf8");
 }

package/src/plugins/policy/README.md

@@ -0,0 +1,21 @@
+# policy {#policy_plugin}
+
+Per-invocation enforcement of ask-mode restrictions. Rejects
+model-emitted commands that would mutate the filesystem when the run
+was started in `ask` mode.
+
+## Registration
+
+- **Filter**: `entry.recording` (priority 1) — runs before a command
+  becomes an entry.
+
+## Rejections (ask mode only)
+
+- `<sh>` — any shell command.
+- `<set path="file.txt">` — file-scheme writes (bare path, non-scheme).
+- `<rm path="file.txt">` — file-scheme deletes.
+- `<mv>` / `<cp>` into a file-scheme destination.
+
+Each rejection logs via `error.log` and returns an entry with
+`state: "failed"`, `outcome: "permission"` so it still appears in the
+turn's audit trail.

package/src/plugins/policy/policy.js

@@ -1,44 +1,59 @@
-import KnownStore from "../../agent/KnownStore.js";
+import Entries from "../../agent/Entries.js";
 
 export default class Policy {
+	#core;
+
 	constructor(core) {
+		this.#core = core;
 		core.filter("entry.recording", this.#enforceAskMode.bind(this), 1);
 	}
 
+	async #reject(ctx, message) {
+		await this.#core.hooks.error.log.emit({
+			store: ctx.store,
+			runId: ctx.runId,
+			turn: ctx.turn,
+			loopId: ctx.loopId,
+			message,
+		});
+	}
+
 	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 };
+			await this.#reject(ctx, "Rejected <sh> in ask mode");
+			return { ...entry, state: "failed", outcome: "permission" };
 		}
 
 		if (entry.scheme === "set" && entry.attributes?.path) {
-			const scheme = KnownStore.scheme(entry.attributes.path);
+			const scheme = Entries.scheme(entry.attributes.path);
 			if (scheme === null && entry.body) {
-				console.warn(
-					`[RUMMY] Rejected file edit to ${entry.attributes.path} in ask mode`,
+				await this.#reject(
+					ctx,
+					`Rejected file edit to ${entry.attributes.path} in ask mode`,
 				);
-				return { ...entry, status: 403 };
+				return { ...entry, state: "failed", outcome: "permission" };
 			}
 		}
 
 		if (entry.scheme === "rm") {
 			const pathAttr = entry.attributes?.path || entry.path;
-			const scheme = KnownStore.scheme(pathAttr);
+			const scheme = Entries.scheme(pathAttr);
 			if (scheme === null) {
-				console.warn(`[RUMMY] Rejected file rm of ${pathAttr} in ask mode`);
-				return { ...entry, status: 403 };
+				await this.#reject(ctx, `Rejected file rm of ${pathAttr} in ask mode`);
+				return { ...entry, state: "failed", outcome: "permission" };
 			}
 		}
 
 		if (entry.scheme === "mv" || entry.scheme === "cp") {
-			const destScheme = KnownStore.scheme(entry.attributes?.to);
+			const destScheme = Entries.scheme(entry.attributes?.to);
 			if (destScheme === null) {
-				console.warn(
-					`[RUMMY] Rejected ${entry.scheme} to file ${entry.attributes?.to} in ask mode`,
+				await this.#reject(
+					ctx,
+					`Rejected ${entry.scheme} to file ${entry.attributes?.to} in ask mode`,
 				);
-				return { ...entry, status: 403 };
+				return { ...entry, state: "failed", outcome: "permission" };
 			}
 		}
 

package/src/plugins/prompt/README.md

@@ -1,4 +1,4 @@
-# prompt
+# prompt {#prompt_plugin}
 
 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.

package/src/plugins/prompt/prompt.js

@@ -3,16 +3,17 @@ export default class Prompt {
 
 	constructor(core) {
 		this.#core = core;
-		core.hooks.tools.onView("prompt", (entry) => {
-			if (entry.fidelity === "summary") {
+		core.hooks.tools.onView("prompt", (entry) => entry.body, "visible");
+		core.hooks.tools.onView(
+			"prompt",
+			(entry) => {
 				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;
-		});
+				const full = entry.body;
+				if (full.length <= limit) return full;
+				return `${full.slice(0, limit)}\n[truncated — promote to see the complete prompt]`;
+			},
+			"summarized",
+		);
 		core.on("turn.started", this.onTurnStarted.bind(this));
 		core.filter("assembly.user", this.assemblePrompt.bind(this), 300);
 	}
@@ -21,15 +22,23 @@ export default class Prompt {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 
 		if (!isContinuation && prompt) {
-			await store.upsert(runId, turn, `prompt://${turn}`, prompt, 200, {
+			// prompt:// writable_by: ["plugin"] — explicit for clarity.
+			await store.set({
+				runId,
+				turn,
+				path: `prompt://${turn}`,
+				body: prompt,
+				state: "resolved",
 				attributes: { mode },
 				loopId,
+				writer: "plugin",
 			});
 		}
 	}
 
 	async assemblePrompt(content, ctx) {
-		const promptEntry = ctx.rows.findLast(
+		const { rows, contextSize, toolSet } = ctx;
+		const promptEntry = rows.findLast(
 			(r) => r.category === "prompt" && r.scheme === "prompt",
 		);
 
@@ -37,15 +46,51 @@ export default class Prompt {
 			typeof promptEntry?.attributes === "string"
 				? JSON.parse(promptEntry.attributes)
 				: promptEntry?.attributes;
-		const mode = attrs?.mode || ctx.type;
-		const body = promptEntry?.body || "";
-		const toolNames = ctx.toolSet
-			? [...ctx.toolSet]
-			: [...this.#core.hooks.tools.resolveForLoop(mode)];
-		const tools = toolNames.join(",");
+		const mode = attrs?.mode ? attrs.mode : ctx.type;
+		const body = promptEntry ? promptEntry.body : "";
+		const activeTools = toolSet
+			? new Set(toolSet)
+			: new Set(this.#core.hooks.tools.names);
+		const commands = this.#core.hooks.tools.advertisedNames
+			.filter((n) => activeTools.has(n))
+			.join(",");
 		let warn = "";
 		if (mode === "ask") warn = ' warn="File editing disallowed."';
 
-		return `${content}<prompt mode="${mode}" tools="${tools}"${warn}>${body}</prompt>`;
+		// Surface the most recent prior-turn budget demotion as a
+		// `reverted="N"` attribute on <prompt>. Historical error
+		// entries sit in <log> but read as ambient noise; this signal
+		// is dynamic and always fresh — the model sees that its
+		// promotions last turn were reverted, in the same spot where
+		// it reads budget numbers.
+		let reverted = "";
+		const priorTurn = ctx.turn - 1;
+		if (priorTurn >= 1) {
+			const priorDemotion = rows.find((r) => {
+				if (!r.path.startsWith(`log://turn_${priorTurn}/error/`)) return false;
+				const attrs =
+					typeof r.attributes === "string"
+						? JSON.parse(r.attributes)
+						: r.attributes;
+				return attrs?.status === 413 && attrs?.demotedCount > 0;
+			});
+			if (priorDemotion) {
+				const attrs =
+					typeof priorDemotion.attributes === "string"
+						? JSON.parse(priorDemotion.attributes)
+						: priorDemotion.attributes;
+				reverted = ` reverted="${attrs.demotedCount}"`;
+			}
+		}
+
+		const path = promptEntry ? ` path="${promptEntry.path}"` : "";
+		const visibility = promptEntry?.visibility
+			? ` visibility="${promptEntry.visibility}"`
+			: "";
+		const tokens =
+			promptEntry?.aTokens != null
+				? ` tokens="${promptEntry.aTokens}"`
+				: "";
+		return `${content}<prompt mode="${mode}"${path} commands="${commands}"${warn}${reverted}${visibility}${tokens}>${body}</prompt>`;
 	}
 }

package/src/plugins/rm/README.md

@@ -1,4 +1,4 @@
-# rm
+# rm {#rm_plugin}
 
 Removes entries by path or glob pattern.
 

package/src/plugins/rm/rm.js

@@ -1,6 +1,8 @@
-import KnownStore from "../../agent/KnownStore.js";
+import Entries from "../../agent/Entries.js";
 import docs from "./rmDoc.js";
 
+const LOG_ACTION_RE = /^log:\/\/turn_\d+\/(\w+)\//;
+
 export default class Rm {
 	#core;
 
@@ -8,25 +10,50 @@ export default class Rm {
 		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));
+		core.on("visible", this.full.bind(this));
+		core.on("summarized", this.summary.bind(this));
 		core.filter("instructions.toolDocs", async (docsMap) => {
 			docsMap.rm = docs;
 			return docsMap;
 		});
+		core.on("proposal.accepted", this.#onAccepted.bind(this));
+	}
+
+	async #onAccepted(ctx) {
+		const m = LOG_ACTION_RE.exec(ctx.path);
+		if (m?.[1] !== "rm") return;
+		const target = ctx.attrs?.path;
+		if (!target) return;
+		await ctx.entries.rm({ runId: ctx.runId, path: target });
+		if (ctx.projectRoot) {
+			const { unlink } = await import("node:fs/promises");
+			const { join } = await import("node:path");
+			try {
+				await unlink(join(ctx.projectRoot, target));
+			} catch (err) {
+				// File may already be absent — entry rm'd regardless.
+				if (err.code !== "ENOENT") throw err;
+			}
+		}
 	}
 
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const target = entry.attributes.path;
 		if (!target) {
-			await store.upsert(runId, turn, entry.resultPath, "", 400, {
+			await store.set({
+				runId,
+				turn,
+				path: entry.resultPath,
+				body: "",
+				state: "failed",
+				outcome: "validation",
 				attributes: { error: "path is required" },
 				loopId,
 			});
 			return;
 		}
-		const normalized = KnownStore.normalizePath(target);
+		const normalized = Entries.normalizePath(target);
 		const matches = await store.getEntriesByPattern(
 			runId,
 			normalized,
@@ -34,7 +61,13 @@ export default class Rm {
 		);
 
 		if (matches.length === 0) {
-			await store.upsert(runId, turn, entry.resultPath, "", 404, {
+			await store.set({
+				runId,
+				turn,
+				path: entry.resultPath,
+				body: "",
+				state: "failed",
+				outcome: "not_found",
 				attributes: { path: target, error: `${target} not found` },
 				loopId,
 			});
@@ -45,24 +78,35 @@ export default class Rm {
 		const schemeMatches = matches.filter((m) => m.scheme !== null);
 
 		// Scheme entries: remove all, write one aggregate result entry
-		for (const match of schemeMatches) await store.remove(runId, match.path);
+		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");
-			await store.upsert(runId, turn, entry.resultPath, paths, 200, {
+			await store.set({
+				runId,
+				turn,
+				path: entry.resultPath,
+				body: paths,
+				state: "resolved",
 				attributes: { path: target },
 				loopId,
 			});
 		}
 
-		// File entries: individual 202 proposals (require user resolution)
+		// File entries: individual proposals (require user resolution)
 		if (fileMatches.length > 0 && schemeMatches.length > 0)
-			await store.remove(runId, entry.resultPath);
+			await store.rm({ runId: runId, path: entry.resultPath });
 		for (const match of fileMatches) {
 			const resultPath =
 				schemeMatches.length === 0 && fileMatches.length === 1
 					? entry.resultPath
-					: await store.dedup(runId, "rm", match.path, turn);
-			await store.upsert(runId, turn, resultPath, match.path, 202, {
+					: await store.logPath(runId, turn, "rm", match.path);
+			await store.set({
+				runId,
+				turn,
+				path: resultPath,
+				body: match.path,
+				state: "proposed",
 				attributes: { path: match.path },
 				loopId,
 			});
@@ -74,7 +118,7 @@ export default class Rm {
 		return entry.body ? `${header}\n${entry.body}` : header;
 	}
 
-	summary(entry) {
-		return this.full(entry);
+	summary() {
+		return "";
 	}
 }

package/src/plugins/rm/rmDoc.js

@@ -1,25 +1,3 @@
-// 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 = [
-	['## <rm path="[path]"/> - Remove a file or entry'],
-	['Example: <rm path="src/config.js"/>', "File removal. Simplest form."],
-	[
-		'Example: <rm path="known://config/deprecated_service"/>',
-		"Shows topic-hierarchy path convention.",
-	],
-	[
-		'Example: <rm path="known://temp_*" preview/>',
-		"Preview before deleting. Safety pattern for bulk operations.",
-	],
-	[
-		'* Permanent. Prefer <set fidelity="archive"/> to preserve for later retrieval',
-		"Nudges toward archive over rm.",
-	],
-	[
-		"* Use `preview` to check matches before pattern-based bulk deletion",
-		"Reinforces preview safety pattern.",
-	],
-];
+import { loadDoc } from "../helpers.js";
 
-export default LINES.map(([text]) => text).join("\n");
+export default loadDoc(import.meta.url, "rmDoc.md");

package/src/plugins/rm/rmDoc.md

@@ -0,0 +1,13 @@
+## <rm path="[path]"/> - Remove a file or entry
+
+Example: <rm path="src/config.js"/>
+<!-- File removal. Simplest form. -->
+
+Example: <rm path="known://temp_*" preview/>
+<!-- Preview before deleting. Safety pattern for bulk operations. -->
+
+* Permanent. Prefer <set path="..." visibility="archived"/> to preserve for later retrieval
+<!-- Nudges toward archive over rm. Path attr included so the model sees a complete invocation shape, not a fragment. -->
+
+* `preview` shows what paths would be affected without performing the operation.
+<!-- Canonical preview teaching lives here — rm is the most intuitive 'check before committing' case. Model generalizes to cp/mv/get by analogy. Advanced uses (e.g. archive rediscovery via <get preview>) belong in persona/skill docs, not here. -->

package/src/plugins/rpc/README.md

@@ -1,4 +1,4 @@
-# rpc
+# rpc {#rpc_plugin}
 
 Registers core RPC methods and provides automatic tool dispatch for
 all registered tools.
@@ -29,4 +29,4 @@ all registered tools.
 - `getRuns`, `getRun`
 
 ### Notifications
-- `run/state`, `run/progress`, `ui/render`, `ui/notify`
+- `run/state`, `run/progress`, `run/proposal`, `ui/render`, `ui/notify`, `stream/cancelled`