@possumtech/rummy 0.5.0 → 2.0.0

package/src/plugins/mv/mv.js

@@ -1,6 +1,8 @@
-import KnownStore from "../../agent/KnownStore.js";
+import Entries from "../../agent/Entries.js";
 import docs from "./mvDoc.js";
 
+const LOG_ACTION_RE = /^log:\/\/turn_\d+\/(\w+)\//;
+
 export default class Mv {
 	#core;
 
@@ -8,43 +10,56 @@ export default class Mv {
 		this.#core = core;
 		core.registerScheme();
 		core.on("handler", this.handler.bind(this));
-		core.on("promoted", this.full.bind(this));
-		core.on("demoted", 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.mv = 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] !== "mv") return;
+		if (!ctx.attrs?.isMove || !ctx.attrs?.from) return;
+		await ctx.entries.rm({ runId: ctx.runId, path: ctx.attrs.from });
 	}
 
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const { path, to } = entry.attributes;
-		const VALID = { stored: 1, summary: 1, index: 1, full: 1, archive: 1 };
-		const fidelity = VALID[entry.attributes.fidelity]
-			? entry.attributes.fidelity
+		const VALID = { visible: 1, summarized: 1, archived: 1 };
+		const visibility = VALID[entry.attributes.visibility]
+			? entry.attributes.visibility
 			: undefined;
 
-		// Fidelity-in-place: no destination, change visibility of matched entries
-		if (fidelity && !to) {
+		// Visibility-in-place: no destination, change visibility of matched entries
+		if (visibility && !to) {
 			const matches = await store.getEntriesByPattern(runId, path);
 			for (const match of matches)
-				await store.setFidelity(runId, match.path, fidelity);
-			const label = `set to ${fidelity}`;
-			await store.upsert(
+				await store.set({
+					runId: runId,
+					path: match.path,
+					visibility: visibility,
+				});
+			const label = `set to ${visibility}`;
+			await store.set({
 				runId,
 				turn,
-				entry.resultPath,
-				`${matches.map((m) => m.path).join(", ")} ${label}`,
-				200,
-				{ fidelity: "archived", loopId },
-			);
+				path: entry.resultPath,
+				body: `${matches.map((m) => m.path).join(", ")} ${label}`,
+				state: "resolved",
+				visibility: "archived",
+				loopId,
+			});
 			return;
 		}
 
 		const source = await store.getBody(runId, path);
 		if (source === null) return;
 
-		const destScheme = KnownStore.scheme(to);
+		const destScheme = Entries.scheme(to);
 		const existing = await store.getBody(runId, to);
 		const warning =
 			existing !== null && destScheme !== null
@@ -53,14 +68,32 @@ export default class Mv {
 
 		const body = `${path} ${to}`;
 		if (destScheme === null) {
-			await store.upsert(runId, turn, entry.resultPath, body, 202, {
+			await store.set({
+				runId,
+				turn,
+				path: entry.resultPath,
+				body,
+				state: "proposed",
 				attributes: { from: path, to, isMove: true, warning },
 				loopId,
 			});
 		} else {
-			await store.upsert(runId, turn, to, source, 200, { fidelity, loopId });
-			await store.remove(runId, path);
-			await store.upsert(runId, turn, entry.resultPath, body, 200, {
+			await store.set({
+				runId,
+				turn,
+				path: to,
+				body: source,
+				state: "resolved",
+				visibility,
+				loopId,
+			});
+			await store.rm({ runId: runId, path: path });
+			await store.set({
+				runId,
+				turn,
+				path: entry.resultPath,
+				body,
+				state: "resolved",
 				attributes: { from: path, to, isMove: true, warning },
 				loopId,
 			});
@@ -68,7 +101,7 @@ export default class Mv {
 	}
 
 	full(entry) {
-		return `# mv ${entry.attributes.from || ""} ${entry.attributes.to || ""}`;
+		return `# mv ${entry.attributes.from} ${entry.attributes.to}`;
 	}
 
 	summary() {

package/src/plugins/mv/mvDoc.js

@@ -1,19 +1,3 @@
-// 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 = [
-	[
-		'## <mv path="[source]">[destination]</mv> - Move or rename a file or entry',
-	],
-	[
-		'Example: <mv path="known://active_task">known://completed_task</mv>',
-		"Entry rename. Most common mv use case.",
-	],
-	['Example: <mv path="src/old_name.js">src/new_name.js</mv>', "File rename."],
-	[
-		'Example: <mv path="known://project/*" fidelity="demoted"/>',
-		"Batch fidelity change via pattern. No destination = fidelity in place.",
-	],
-];
+import { loadDoc } from "../helpers.js";
 
-export default LINES.map(([text]) => text).join("\n");
+export default loadDoc(import.meta.url, "mvDoc.md");

package/src/plugins/mv/mvDoc.md

@@ -0,0 +1,10 @@
+## <mv path="[source]">[destination]</mv> - Move or rename a file or entry
+
+Example: <mv path="known://active_task">known://completed_task</mv>
+<!-- Entry rename. Most common mv use case. -->
+
+Example: <mv path="src/old_name.js">src/new_name.js</mv>
+<!-- File rename. -->
+
+Example: <mv path="known://project/*" visibility="summarized"/>
+<!-- Batch visibility change via pattern. No destination = visibility in place. -->

package/src/plugins/ollama/README.md

@@ -0,0 +1,15 @@
+# ollama
+
+Ollama LLM provider. Handles model aliases prefixed with `ollama/`
+(e.g. `ollama/llama3.1:8b`).
+
+## Env
+
+- `OLLAMA_BASE_URL` — base URL (e.g. `http://localhost:11434`).
+  Plugin is inert if unset.
+
+## Context Size
+
+Calls `/api/show` for the requested model and scans `model_info` for
+any `*.context_length` key. Retries up to 3× with exponential backoff
+on non-Ollama transient errors.

package/src/{llm/OllamaClient.js → plugins/ollama/ollama.js}

@@ -1,19 +1,42 @@
-import msg from "../agent/messages.js";
+import msg from "../../agent/messages.js";
 
-export default class OllamaClient {
+const FETCH_TIMEOUT = Number(process.env.RUMMY_FETCH_TIMEOUT);
+if (!FETCH_TIMEOUT) throw new Error("RUMMY_FETCH_TIMEOUT must be set");
+
+const PROVIDER = "ollama";
+
+/**
+ * Ollama LLM provider plugin. Registers with hooks.llm.providers if
+ * OLLAMA_BASE_URL is set; inert otherwise. Handles model aliases of the
+ * form `ollama/{modelName}` — e.g. `ollama/llama3.1:8b` or
+ * `ollama/library/qwen:7b` (Ollama accepts both bare and
+ * registry-qualified model names).
+ */
+export default class Ollama {
 	#baseUrl;
 
-	constructor(baseUrl) {
+	constructor(core) {
+		const baseUrl = process.env.OLLAMA_BASE_URL;
+		if (!baseUrl) return;
 		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 = {}) {
+	async #completion(messages, model, options = {}) {
 		const body = { model, messages, think: true };
 		if (options.temperature !== undefined)
 			body.temperature = options.temperature;
 
-		const timeout = Number(process.env.RUMMY_FETCH_TIMEOUT) || 30_000;
-		const timeoutSignal = AbortSignal.timeout(timeout);
+		const timeoutSignal = AbortSignal.timeout(FETCH_TIMEOUT);
 		const signal = options.signal
 			? AbortSignal.any([options.signal, timeoutSignal])
 			: timeoutSignal;
@@ -34,29 +57,27 @@ export default class OllamaClient {
 
 		const data = await response.json();
 
-		for (const choice of data.choices || []) {
-			const msg = choice.message;
-			if (!msg) continue;
-			const parts = [msg.reasoning_content, msg.reasoning, msg.thinking].filter(
+		for (const choice of data.choices) {
+			const m = choice.message;
+			if (!m) continue;
+			const parts = [m.reasoning_content, m.reasoning, m.thinking].filter(
 				Boolean,
 			);
-			msg.reasoning_content =
+			m.reasoning_content =
 				parts.length > 0 ? [...new Set(parts)].join("\n") : null;
 		}
 
 		return data;
 	}
 
-	async getContextSize(model) {
+	async #getContextSize(model) {
 		for (let attempt = 0; attempt < 3; attempt++) {
 			try {
 				const response = await fetch(`${this.#baseUrl}/api/show`, {
 					method: "POST",
 					headers: { "Content-Type": "application/json" },
 					body: JSON.stringify({ model }),
-					signal: AbortSignal.timeout(
-						Number(process.env.RUMMY_FETCH_TIMEOUT) || 30_000,
-					),
+					signal: AbortSignal.timeout(FETCH_TIMEOUT),
 				});
 				if (!response.ok) {
 					throw new Error(
@@ -67,9 +88,10 @@ export default class OllamaClient {
 					);
 				}
 				const data = await response.json();
-				const info = data.model_info || {};
-				for (const [key, value] of Object.entries(info)) {
-					if (key.endsWith(".context_length")) return value;
+				if (data.model_info) {
+					for (const [key, value] of Object.entries(data.model_info)) {
+						if (key.endsWith(".context_length")) return value;
+					}
 				}
 				throw new Error(msg("error.ollama_no_context_length", { model }));
 			} catch (err) {

package/src/plugins/openai/README.md

@@ -0,0 +1,17 @@
+# openai
+
+OpenAI-compatible LLM provider. Handles any model whose alias doesn't
+carry a provider prefix — the default fallback provider. Works with
+OpenAI itself, llama.cpp, vLLM, and any other service that implements
+the `/v1/chat/completions` and `/v1/models` shape.
+
+## Env
+
+- `OPENAI_BASE_URL` — base URL (e.g. `https://api.openai.com` or
+  `http://localhost:8080`). Plugin is inert if unset.
+- `OPENAI_API_KEY` — bearer token (optional for local servers).
+
+## Context Size
+
+Probes `/props` first (llama.cpp runtime) for `n_ctx`, falls back to
+`/v1/models` for the training context length.

package/src/plugins/openai/openai.js

@@ -0,0 +1,120 @@
+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 = "openai";
+
+/**
+ * OpenAI-compatible LLM provider plugin. Registers with hooks.llm.providers
+ * if OPENAI_BASE_URL is set in env; silently inert otherwise. Handles
+ * model aliases of the form `openai/{modelName}` — the first path
+ * segment picks the provider, the rest is whatever the API expects.
+ */
+export default class OpenAi {
+	#baseUrl;
+	#apiKey;
+
+	constructor(core) {
+		const baseUrl = process.env.OPENAI_BASE_URL;
+		if (!baseUrl) return;
+		this.#baseUrl = String(baseUrl).replace(/\/v1\/?$/, "");
+		this.#apiKey = process.env.OPENAI_API_KEY;
+
+		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, think: 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 headers = { "Content-Type": "application/json" };
+		if (this.#apiKey) headers.Authorization = `Bearer ${this.#apiKey}`;
+
+		const response = await fetch(`${this.#baseUrl}/v1/chat/completions`, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body),
+			signal,
+		});
+
+		if (!response.ok) {
+			const error = await response.text();
+			throw new Error(
+				msg("error.openai_api", { status: `${response.status} - ${error}` }),
+			);
+		}
+
+		const data = await response.json();
+
+		for (const choice of data.choices) {
+			const m = choice.message;
+			if (!m) continue;
+			const parts = [m.reasoning_content, m.reasoning, m.thinking].filter(
+				Boolean,
+			);
+			m.reasoning_content =
+				parts.length > 0 ? [...new Set(parts)].join("\n") : null;
+
+			// Full reasoning dump is centralized in telemetry.js on every
+			// provider — keeping it out of provider plugins avoids double
+			// printing and per-provider drift.
+		}
+
+		return data;
+	}
+
+	async #getContextSize(_model) {
+		const headers = { "Content-Type": "application/json" };
+		if (this.#apiKey) headers.Authorization = `Bearer ${this.#apiKey}`;
+
+		// Try /props first — llama.cpp exposes runtime n_ctx here.
+		try {
+			const propsResponse = await fetch(`${this.#baseUrl}/props`, {
+				headers,
+				signal: AbortSignal.timeout(FETCH_TIMEOUT),
+			});
+			if (propsResponse.ok) {
+				const props = await propsResponse.json();
+				const runtimeCtx = props?.default_generation_settings?.n_ctx;
+				if (runtimeCtx) return runtimeCtx;
+			}
+		} catch (_err) {
+			// /props is a llama.cpp extension; absent on vanilla OpenAI.
+			// Fall through to /v1/models for the training-context-size hint.
+		}
+
+		// Fall back to /v1/models for training context.
+		const response = await fetch(`${this.#baseUrl}/v1/models`, {
+			headers,
+			signal: AbortSignal.timeout(FETCH_TIMEOUT),
+		});
+		if (!response.ok) {
+			throw new Error(
+				msg("error.openai_models_failed", {
+					status: response.status,
+					baseUrl: this.#baseUrl,
+				}),
+			);
+		}
+		const data = await response.json();
+		const model = data.data?.[0];
+		const ctx = model?.meta?.n_ctx_train || model?.context_length;
+		if (!ctx) throw new Error(msg("error.openai_no_context_length"));
+		return ctx;
+	}
+}

package/src/plugins/openrouter/README.md

@@ -0,0 +1,27 @@
+# openrouter
+
+OpenRouter LLM provider. Handles model aliases prefixed with
+`openrouter/` (e.g. `openrouter/anthropic/claude-3-opus`). Strips the
+provider segment and passes the rest (`publisher/model`) straight to
+OpenRouter's API.
+
+## Env
+
+- `OPENROUTER_BASE_URL` — base URL (e.g. `https://openrouter.ai/api/v1`).
+  Plugin is inert if `OPENROUTER_API_KEY` or base URL is unset.
+- `OPENROUTER_API_KEY` — bearer token.
+- `RUMMY_HTTP_REFERER` / `RUMMY_X_TITLE` — attribution headers
+  OpenRouter uses for rankings.
+
+## Reasoning Normalization
+
+OpenRouter's response shape varies by underlying provider. The plugin
+merges `reasoning_content` / `reasoning` / `thinking` /
+`reasoning_details[].text` into a deduplicated `reasoning_content`
+string on each choice's message.
+
+## Context Size
+
+Calls `/models` and reads `context_length` on the matching entry.
+Cached per model for the plugin lifetime. If the endpoint fails or the
+model is missing, the call throws — no hardcoded fallback.

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.