@possumtech/rummy 2.1.0 → 2.2.0

package/src/plugins/openai/openai.js

@@ -1,8 +1,8 @@
-import config from "../../agent/config.js";
 import msg from "../../agent/messages.js";
 import { chatCompletionStream } from "../../llm/openaiStream.js";
 
-const { FETCH_TIMEOUT } = config;
+const FETCH_TIMEOUT = Number(process.env.RUMMY_FETCH_TIMEOUT);
+const THINK = process.env.RUMMY_THINK === "1";
 
 const PROVIDER = "openai";
 
@@ -29,7 +29,8 @@ export default class OpenAi {
 	}
 
 	async #completion(messages, model, options = {}) {
-		const body = { model, messages, think: true };
+		const body = { model, messages, think: THINK };
+		if (options.maxTokens !== undefined) body.max_tokens = options.maxTokens;
 		if (options.temperature !== undefined)
 			body.temperature = options.temperature;
 

package/src/plugins/openrouter/openrouter.js

@@ -1,8 +1,7 @@
-import config from "../../agent/config.js";
 import msg from "../../agent/messages.js";
 import { chatCompletionStream } from "../../llm/openaiStream.js";
 
-const { FETCH_TIMEOUT } = config;
+const FETCH_TIMEOUT = Number(process.env.RUMMY_FETCH_TIMEOUT);
 
 const PROVIDER = "openrouter";
 
@@ -31,7 +30,11 @@ export default class OpenRouter {
 	}
 
 	async #completion(messages, model, options = {}) {
+		// include_reasoning is OpenRouter's relay-level knob: does the proxy
+		// surface reasoning back to us? Always on — we pay for the tokens,
+		// we keep the telemetry. Orthogonal to RUMMY_THINK (model-side).
 		const body = { model, messages, include_reasoning: true };
+		if (options.maxTokens !== undefined) body.max_tokens = options.maxTokens;
 		if (options.temperature !== undefined)
 			body.temperature = options.temperature;
 
@@ -75,6 +78,13 @@ export default class OpenRouter {
 	async #getContextSize(model) {
 		if (this.#contextCache.has(model)) return this.#contextCache.get(model);
 
+		// OpenRouter provider-pinning shorthand (`google/gemma-4-31b-it:cloudflare`)
+		// routes the completion to a specific upstream, but the /models
+		// catalog lists the bare model id (`google/gemma-4-31b-it`). Split
+		// off the `:provider` suffix for the lookup; it's a routing hint,
+		// not part of the model identity.
+		const lookupId = model.split(":")[0];
+
 		const res = await fetch(`${this.#baseUrl}/models`, {
 			headers: { Authorization: `Bearer ${this.#apiKey}` },
 			signal: AbortSignal.timeout(FETCH_TIMEOUT),
@@ -85,10 +95,10 @@ export default class OpenRouter {
 			);
 		}
 		const data = await res.json();
-		const entry = data.data?.find((m) => m.id === model);
+		const entry = data.data?.find((m) => m.id === lookupId);
 		if (!entry?.context_length) {
 			throw new Error(
-				`OpenRouter /models has no context_length for "${model}".`,
+				`OpenRouter /models has no context_length for "${lookupId}".`,
 			);
 		}
 		this.#contextCache.set(model, entry.context_length);

package/src/plugins/persona/README.md

@@ -1,20 +1,18 @@
 # persona {#persona_plugin}
 
-Runtime persona management. A persona is free-form text that gets
-prepended to the model's system prompt for a run.
+Workflow specification rendered into the system prompt below the
+tooldocs. 1:1 run:persona — set at run creation, immutable thereafter.
 
 ## Files
 
-- **persona.js** — RPC registration and persona file loading.
+- **default.md** — default persona (7D state machine) injected when the
+  client supplies none.
+- **persona.js** — registers the `persona` scheme + view callbacks.
 
-## RPC Methods
+## Resolution
 
-| 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.
+- Client supplies persona text via the run-creation RPC's `persona`
+  option.
+- If null, `AgentLoop.ensureRun` loads `default.md`.
+- Result persists to `runs.persona`; the instructions plugin reads it
+  during system-prompt assembly.

package/src/plugins/persona/default.md

@@ -0,0 +1,29 @@
+# Folksonomic XML Command State Machine: Draft -> Decompose -> Discover -> Distill -> Define -> Determine -> Deliver
+
+YOU MUST ONLY use the available Folksonomic XML Commands to Draft a plan, Decompose the prompt into its unknowns, then Discover and Distill information into knowns while demoting irrelevant source entries and log entries before Defining, Determining, and Delivering.
+
+YOU MAY edit, expand, update, or revise the plan as you proceed.
+YOU MUST perform the next step in the plan, optimizing visibility for relevance and budget constraints.
+
+Example:
+	<set path="known://plan"><<NEW
+	- [ ] Draft a plan
+	- [ ] Decompose key, relevant unknowns into topical, taxonomized, and tagged unknown entries
+	- [ ] Discover key, relevant information
+	- [ ] Distill key, relevant information into topical, taxonomized, tagged, and referenced known entries
+	- [ ] Define the answer or solution
+	- [ ] Determine the validity of the answer or solution (and fix if failing)
+	- [ ] Deliver
+	NEW</set>
+	
+	<set path="unknown://countries/france/capital" tags="countries,france,capital,geography"><<NEW
+	What is the capital of France?
+	NEW</set>
+	<set path="unknown://countries/france/population" tags="countries,france,population,demographics"><<NEW
+	What is the population of France?
+	NEW</set>
+	<set path="unknown://countries/france/area" tags="countries,france,area,geography"><<NEW
+	What is the area of France?
+	NEW</set>
+	
+	<update status="102">plan drafted, unknowns decomposed</update>

package/src/plugins/persona/persona.js

@@ -1,71 +1,15 @@
-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);
-				}
-
-				// "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,
-					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 [];
-				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,
-		});
+		core.registerScheme({ name: "persona", category: "data" });
+		core.hooks.tools.onView("persona", (entry) => entry.body, "visible");
+		core.hooks.tools.onView("persona", () => "", "summarized");
+		// assembly.system @ 150 — last system-prompt section. Body comes
+		// from runs.persona, plumbed in via ctx.persona by TurnExecutor.
+		core.filter("assembly.system", this.assembleSystemPersona.bind(this), 150);
 	}
-}
 
-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");
-	return fs.readFile(join(dir, `${name}.md`), "utf8");
+	assembleSystemPersona(content, ctx) {
+		if (!ctx.persona) return content;
+		return `${content}\n\n## Operational Persona\n\n${ctx.persona}`;
+	}
 }

package/src/plugins/policy/policy.js

@@ -1,49 +1,50 @@
 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);
 	}
 
-	#fail(entry, body) {
-		return { ...entry, body, state: "failed", outcome: "permission" };
+	#fail(entry) {
+		return { ...entry, state: "failed", outcome: "permission" };
 	}
 
 	async #enforceAskMode(entry, ctx) {
 		if (ctx.mode !== "ask") return entry;
 
+		let message = null;
 		if (entry.scheme === "sh") {
-			return this.#fail(entry, "Rejected <sh> in ask mode");
-		}
-
-		if (entry.scheme === "set" && entry.attributes?.path) {
+			message = "Rejected <sh> in ask mode";
+		} else if (entry.scheme === "set" && entry.attributes?.path) {
 			const scheme = Entries.scheme(entry.attributes.path);
 			if (scheme === null && entry.body) {
-				return this.#fail(
-					entry,
-					`Rejected file edit to ${entry.attributes.path} in ask mode`,
-				);
+				message = `Rejected file edit to ${entry.attributes.path} in ask mode`;
 			}
-		}
-
-		if (entry.scheme === "rm") {
+		} else if (entry.scheme === "rm") {
 			const pathAttr = entry.attributes?.path || entry.path;
 			const scheme = Entries.scheme(pathAttr);
 			if (scheme === null) {
-				return this.#fail(entry, `Rejected file rm of ${pathAttr} in ask mode`);
+				message = `Rejected file rm of ${pathAttr} in ask mode`;
 			}
-		}
-
-		if (entry.scheme === "mv" || entry.scheme === "cp") {
+		} else if (entry.scheme === "mv" || entry.scheme === "cp") {
 			const destScheme = Entries.scheme(entry.attributes?.to);
 			if (destScheme === null) {
-				return this.#fail(
-					entry,
-					`Rejected ${entry.scheme} to file ${entry.attributes?.to} in ask mode`,
-				);
+				message = `Rejected ${entry.scheme} to file ${entry.attributes?.to} in ask mode`;
 			}
 		}
 
-		return entry;
+		if (!message) return entry;
+		await this.#core.hooks.error.log.emit({
+			store: ctx.store,
+			runId: ctx.runId,
+			turn: ctx.turn,
+			loopId: ctx.loopId,
+			message,
+			status: 403,
+		});
+		return this.#fail(entry);
 	}
 }

package/src/plugins/prompt/README.md

@@ -1,38 +1,48 @@
 # 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.
+Renders the `<prompt>` tag at the front of the user message —
+the model sees its task first, then the dynamic state blocks,
+then the late-bound rules and budget. Always present on every
+turn.
 
 ## Registration
 
-- **Filter**: `assembly.user` at priority 300 (always last)
+- **Filter**: `assembly.user` at priority 30 (front of user
+  message, before all dynamic state and the `<instructions>`
+  block at 165)
 
 ## Behavior
 
-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.
+Finds the latest `prompt://` entry in the turn_context rows. Renders
+with `commands` attribute (available tool list) and an optional
+`warn="File editing disallowed."` attribute when the loop's mode is
+`ask` (read from `attributes.mode` on the prompt entry, falling back
+to the type passed by the core). The mode itself is not rendered as
+a tag attribute — the warn copy carries the only model-relevant
+consequence.
 
-## Archived prompts: the singular exception to invisibility
+## Archived prompts disappear, by design
 
 `v_model_context.sql` filters archived entries out of the model's
-context — every scheme **except `prompt`**. Archived `prompt://`
-entries flow through with `effective_visibility = 'archived'` and
-their body suppressed (per `projected.body`'s visibility CASE). The
-plugin then renders the tag with full attributes (`path`,
-`visibility="archived"`, etc.) but empty body.
-
-The exception exists because the prompt is run identity: every other
-archived entry is recoverable by pattern search if the model ever
-needs it back, but the prompt is the question the run is answering.
-A model that loses sight of its prompt cannot honestly act. Keeping
-the archived prompt's path visible lets the model emit
-`<get path="prompt://N"/>` to promote it back if it archived
-prematurely (or step back to an earlier stage via
-`<update status="174">`).
-
-This is the only entry-type exception to the "archived = invisible"
-contract. New schemes that warrant similar treatment should be added
-explicitly here, not by accident.
+context for every scheme — `prompt` included. There is no carve-out.
+An archived `prompt://N` does not appear in the user message at
+all: no tag, no body, no metadata.
+
+The model receives no instruction-side hint not to archive the
+active prompt. If it archives the prompt anyway, the run will
+visibly fail on the next turn (no `<prompt>` tag for the model to
+act on; the model emits "please provide a prompt to act upon" or
+similar confusion). That instructive failure mode is intentional —
+paradigm purity (archived means archived, no exceptions) over
+silent data-layer rescue.
+
+If practical behavior at scale ever demands a guard, the right
+surface is an action-gate (refuse the `<set>` of `visibility="archived"`
+on the active `prompt://N` with a soft 403 the model can read),
+not a read-view carve-out that quietly keeps the entry visible.
+
+System-level auto-archive on new prompt is unaffected: when a fresh
+`prompt://M` arrives, the engine archives `prompt://N` (M > N) so
+the prior cycle's prompt cleanly leaves context. `unknown://` /
+`known://` entries persist across cycles; logs are demoted per
+stage instructions.

package/src/plugins/prompt/prompt.js

@@ -1,4 +1,4 @@
-const SUMMARIZED_PROMPT_CHAR_CAP = 500;
+import { renderEntry, SUMMARY_MAX_CHARS } from "../helpers.js";
 
 export default class Prompt {
 	#core;
@@ -8,24 +8,17 @@ export default class Prompt {
 		core.hooks.tools.onView("prompt", (entry) => entry.body, "visible");
 		core.hooks.tools.onView(
 			"prompt",
-			(entry) => {
-				const full = entry.body;
-				if (full.length <= SUMMARIZED_PROMPT_CHAR_CAP) return full;
-				return `${full.slice(0, SUMMARIZED_PROMPT_CHAR_CAP)}\n[truncated — promote to see the complete prompt]`;
-			},
+			(entry) => entry.body.slice(0, SUMMARY_MAX_CHARS),
 			"summarized",
 		);
 		core.on("turn.started", this.onTurnStarted.bind(this));
-		core.filter("assembly.user", this.assemblePrompt.bind(this), 225);
+		core.filter("assembly.user", this.assemblePrompt.bind(this), 60);
 	}
 
 	async onTurnStarted({ rummy, mode, prompt, isContinuation }) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 
 		if (!isContinuation && prompt) {
-			// New prompt = new cycle; archive prior cycle's prompts/logs (knowns/unknowns persist).
-			await store.archivePriorPromptArtifacts(runId, turn);
-
 			await store.set({
 				runId,
 				turn,
@@ -81,14 +74,15 @@ export default class Prompt {
 			}
 		}
 
-		const path = promptEntry ? ` path="${promptEntry.path}"` : "";
-		const visibility = promptEntry?.visibility
-			? ` visibility="${promptEntry.visibility}"`
-			: "";
-		const tokens =
-			promptEntry?.aTokens != null ? ` tokens="${promptEntry.aTokens}"` : "";
-		const lines =
-			promptEntry?.vLines != null ? ` lines="${promptEntry.vLines}"` : "";
-		return `${content}<prompt mode="${mode}"${path} commands="${commands}"${warn}${reverted}${visibility}${tokens}${lines}>${body}</prompt>`;
+		// <prompt> wrapper carries section-level metadata (commands, mode
+		// warn, reverted-from-413). The body is heredoc-fenced so any
+		// task description containing tag-shaped text won't be parsed as
+		// a tool call when the model echoes attention through the packet.
+		const meta = {};
+		if (promptEntry?.visibility) meta.visibility = promptEntry.visibility;
+		if (promptEntry?.aTokens != null) meta.tokens = promptEntry.aTokens;
+		if (promptEntry?.vLines != null) meta.lines = promptEntry.vLines;
+		const fenced = promptEntry ? renderEntry(promptEntry.path, meta, body) : "";
+		return `${content}<prompt commands="${commands}"${warn}${reverted}>\n${fenced}\n</prompt>`;
 	}
 }

package/src/plugins/rm/rm.js

@@ -1,4 +1,5 @@
 import Entries from "../../agent/Entries.js";
+import { storePatternResult } from "../helpers.js";
 import docs from "./rmDoc.js";
 
 const LOG_ACTION_RE = /^log:\/\/turn_\d+\/(\w+)\//;
@@ -63,6 +64,23 @@ export default class Rm {
 			entry.attributes.body,
 		);
 
+		// Manifest: list what would be removed without performing the rm.
+		// Safety idiom for destructive bulk ops — the model can audit a
+		// glob's reach before committing to it.
+		if (entry.attributes.manifest !== undefined) {
+			await storePatternResult(
+				store,
+				runId,
+				turn,
+				"rm",
+				target,
+				entry.attributes.body,
+				matches,
+				{ manifest: true, loopId, attributes: { path: target } },
+			);
+			return;
+		}
+
 		if (matches.length === 0) {
 			await store.set({
 				runId,

package/src/plugins/rm/rmDoc.md

@@ -3,11 +3,10 @@
 Example: <rm path="src/config.js"/>
 <!-- File removal. Simplest form. -->
 
-Example: <rm path="known://temp_*" manifest/>
-<!-- Optional: Manifest before deleting. Safety pattern for bulk operations. -->
+Example: <rm path="known://countries/france/*" manifest/>
+<!-- Manifest 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. -->
+Example: <rm path="log://turn_3/get/**"/>
+<!-- Bulk delete by glob. Recursive scheme glob; clears a turn's get logs in one call. -->
 
-* `manifest` lists what paths would be affected without performing the operation.
-<!-- Canonical manifest 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 manifest>) belong in persona/skill docs, not here. -->
+* Permanent. Prefer <set path="..." visibility="archived"/> to preserve for later retrieval.

package/src/plugins/rpc/rpc.js

@@ -2,7 +2,7 @@ import msg from "../../agent/messages.js";
 import RummyContext from "../../hooks/RummyContext.js";
 import File from "../file/file.js";
 
-const CONSTRAINT_VISIBILITIES = new Set(["active", "readonly", "ignore"]);
+const CONSTRAINT_VISIBILITIES = new Set(["add", "readonly", "ignore"]);
 
 export default class Rpc {
 	#core;
@@ -261,11 +261,11 @@ export default class Rpc {
 			},
 			description:
 				"Set a project-level file constraint. Visibility ∈ " +
-				"{active, readonly, ignore}. Patterns can be globs. " +
+				"{add, readonly, ignore}. Patterns can be globs. " +
 				"Persists across runs; overlays git defaults.",
 			params: {
 				pattern: "string — file path or glob",
-				visibility: "string — active | readonly | ignore",
+				visibility: "string — add | readonly | ignore",
 			},
 			requiresInit: true,
 		});