@possumtech/rummy 0.5.0 → 2.0.1

package/src/plugins/log/README.md

@@ -0,0 +1,48 @@
+# log {#log_plugin}
+
+Assembles the `<log>` block in the user message: every
+`category="logging"` entry across the entire run, rendered as XML tool
+tags in v_model_context sort order.
+
+## Registration
+
+- **Filter**: `assembly.user` (priority 100) — contributes the `<log>`
+  block to the user packet.
+
+## Rendering
+
+Each logging entry renders with its scheme as the tag name (`<get>`,
+`<set>`, `<search>`, `<rm>`, `<cp>`, `<mv>`, `<sh>`, `<env>`,
+`<update>`, `<ask_user>`, `<error>`, `<budget>`). Attributes:
+`path`, `turn`, `status`, `state`, `outcome`, `summary`, `visibility`,
+`tokens`.
+
+**`tokens=` invariant.** The value is always the full-visibility cost
+of the thing the tag represents — never the log entry's own stub body
+size. Resolution:
+
+- If the log entry has `attrs.path` referencing a data entry (`get`,
+  `set`, `mv`, `cp`): `tokens=` is that target's tokens. Promotes the
+  audit record into a cost-accurate signal the model can plan against.
+- If the action's log body itself IS the cost-bearing content
+  (`search`, `update`, `error`, `ask_user`): `tokens=` is the entry's
+  own body tokens.
+- `sh` and `env` own multiple streaming channels (`sh://turn_N/{slug}_N`)
+  — no single target to point at. `tokens=` is omitted; the channels
+  render their own tokens in `<context>`.
+
+## Behavior
+
+No loop-boundary split. The `turn` attribute on every entry carries
+when it happened; the model derives loop membership from the data if
+it matters. One chronological log from turn 1 to now.
+
+## Scheme invariant
+
+Log entries (`log://turn_N/{action}/{slug}`) are audit records —
+summary, exit status, references to where the data lives — and never
+carry the payload itself. Payload for streaming actions lives under the
+producer's own scheme (`sh://`, `env://`, future `search://`, etc.) at
+`category=data`, and is rendered inside `<context>` by the known
+plugin. Scheme determines category; data and logging never share a
+scheme. See [scheme_category_split](#scheme_category_split).

package/src/plugins/log/log.js

@@ -0,0 +1,129 @@
+import { stateToStatus } from "../../agent/httpStatus.js";
+
+// Schemes whose log body is an action summary, not the cost-bearing
+// content. For these, the action's cost lives on a separate data entry
+// (sh/env: streaming channels; set/mv/cp: the target entry). Report
+// tokens from the target when we can resolve it (set/mv/cp via
+// attrs.path); omit entirely for sh/env (multiple channels, no single
+// target to point at).
+const STREAM_NO_TOKENS = new Set(["sh", "env"]);
+
+export default class Log {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.filter("assembly.user", this.assembleLog.bind(this), 100);
+	}
+
+	async assembleLog(content, ctx) {
+		// Log includes action entries (scheme=log) AND prior prompts. The
+		// most recent prompt is rendered separately by the prompt plugin
+		// as `<prompt>`; everything older lives in the log so the model
+		// can see the full question history across a sustained run.
+		const latestPrompt = ctx.rows.findLast(
+			(r) => r.category === "prompt" && r.scheme === "prompt",
+		);
+		const entries = ctx.rows.filter((r) => {
+			if (r.category === "logging" && r.scheme === "log") return true;
+			if (r.category === "prompt" && r.scheme === "prompt") {
+				return r !== latestPrompt;
+			}
+			return false;
+		});
+		if (entries.length === 0) return content;
+		const rowsByPath = new Map();
+		for (const r of ctx.rows) rowsByPath.set(r.path, r);
+		const lines = entries.map((e) => renderLogTag(e, rowsByPath));
+		return `${content}<log>\n${lines.join("\n")}\n</log>\n`;
+	}
+}
+
+// Log paths are log://turn_N/action/slug. The second segment is the
+// action — the plugin/tool that produced this log entry (set, get,
+// search, update, error, etc.). Used as the XML tag name. Prompt
+// entries live at prompt://N; they render as <prompt> in history.
+function actionFromPath(path) {
+	if (path?.startsWith("prompt://")) return "prompt";
+	const match = path?.match(/^log:\/\/turn_\d+\/([^/]+)\//);
+	return match ? match[1] : "log";
+}
+
+function renderLogTag(entry, rowsByPath) {
+	const attrs =
+		typeof entry.attributes === "string"
+			? JSON.parse(entry.attributes)
+			: entry.attributes;
+
+	const action = actionFromPath(entry.path);
+
+	const statusValue =
+		attrs?.status != null
+			? attrs.status
+			: entry.state
+				? stateToStatus(entry.state, entry.outcome)
+				: null;
+	// Prompts are uniformly status=200 — uniform value carries no signal
+	// and read as "settled, no action needed." Suppress so cultivation
+	// vocabulary (vary, demote, archive) applies to prompts the same
+	// way it applies to other log entries.
+	const status =
+		statusValue != null && action !== "prompt"
+			? ` status="${statusValue}"`
+			: "";
+	const outcomeAttr = entry.outcome ? ` outcome="${entry.outcome}"` : "";
+	// `tokens=` is the promotion premium (aTokens) of the thing this tag
+	// represents — what the model would free by demoting it. For actions
+	// that reference a separate data entry (get/set/mv/cp), resolve via
+	// attrs.path and report the target's aTokens. For actions whose log
+	// body IS the cost-bearing content (search/update/error/ask_user,
+	// plus <get> slice reads), use the log entry's own aTokens. sh/env
+	// span multiple channel entries and are omitted — the channels
+	// render their own tokens in <context>.
+	const isSlice = attrs?.lineStart != null;
+	const targetEntry = attrs?.path ? rowsByPath.get(attrs.path) : null;
+	let tokenSource = null;
+	let lineSource = null;
+	if (STREAM_NO_TOKENS.has(action)) {
+		tokenSource = null;
+		lineSource = null;
+	} else if (isSlice) {
+		tokenSource = entry.aTokens;
+		lineSource = entry.vLines;
+	} else if (targetEntry) {
+		tokenSource = targetEntry.aTokens;
+		lineSource = targetEntry.vLines;
+	} else {
+		tokenSource = entry.aTokens;
+		lineSource = entry.vLines;
+	}
+	const tokens = tokenSource != null ? ` tokens="${tokenSource}"` : "";
+	const summary =
+		typeof attrs?.summary === "string"
+			? ` summary="${attrs.summary.slice(0, 80)}"`
+			: "";
+	const query =
+		typeof attrs?.query === "string" ? ` query="${attrs.query}"` : "";
+	const command =
+		typeof attrs?.command === "string" ? ` command="${attrs.command}"` : "";
+	// target= is the path the action touched (e.g. the file/known that was
+	// set, the URL that was fetched). Plugins store it in attrs.path when
+	// they write the log entry.
+	const target = attrs?.path ? ` target="${attrs.path}"` : "";
+	// Slice reads tag the log entry with lineStart/lineEnd/totalLines so
+	// the <get> tag surfaces `lines="a-b/total"` — a concrete handle for
+	// the model to re-issue or compare against another slice. Non-slice
+	// entries surface the simple `lines="N"` from the projected body.
+	const lines = isSlice
+		? ` lines="${attrs.lineStart}-${attrs.lineEnd}/${attrs.totalLines}"`
+		: lineSource != null
+			? ` lines="${lineSource}"`
+			: "";
+
+	const attrStr = `${target}${status}${outcomeAttr}${query}${command}${summary}${lines}${tokens}`;
+
+	if (entry.body) {
+		return `<${action} path="${entry.path}"${attrStr}>${entry.body}</${action}>`;
+	}
+	return `<${action} path="${entry.path}"${attrStr}/>`;
+}

package/src/plugins/mv/README.md

@@ -1,4 +1,4 @@
-# mv
+# mv {#mv_plugin}
 
 Moves (renames) an entry from one path to another within the K/V store.
 
@@ -15,5 +15,5 @@ Shows `mv {from} {to}`.
 ## Behavior
 
 Warns if the destination already exists and will be overwritten. Uses
-`KnownStore.scheme()` to determine scheme vs file paths. Source entry
+`Entries.scheme()` to determine scheme vs file paths. Source entry
 is removed on successful scheme moves.

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.