@possumtech/rummy 0.4.0 → 2.0.0

package/src/llm/OpenRouterClient.js

@@ -1,100 +0,0 @@
-import msg from "../agent/messages.js";
-
-const DEFAULT_CONTEXT_SIZE = 131072;
-
-export default class OpenRouterClient {
-	#apiKey;
-	#baseUrl;
-
-	constructor(apiKey) {
-		this.#apiKey = apiKey;
-		this.#baseUrl = process.env.OPENROUTER_BASE_URL;
-	}
-
-	async completion(messages, model, options = {}) {
-		if (!this.#apiKey) throw new Error(msg("error.openrouter_api_key_missing"));
-		return this.#fetch(messages, model, options);
-	}
-
-	async #fetch(messages, model, options) {
-		const body = { model, messages, include_reasoning: 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 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 parts = [
-				cm.reasoning_content,
-				cm.reasoning,
-				cm.thinking,
-				...(cm.reasoning_details || []).map((d) => d.text),
-			].filter(Boolean);
-			cm.reasoning_content =
-				parts.length > 0 ? [...new Set(parts)].join("\n") : null;
-		}
-
-		return data;
-	}
-
-	#contextCache = new Map();
-
-	async getContextSize(model) {
-		if (process.env.RUMMY_CONTEXT_SIZE)
-			return Number(process.env.RUMMY_CONTEXT_SIZE);
-
-		if (this.#contextCache.has(model)) return this.#contextCache.get(model);
-
-		try {
-			const res = await fetch(`${this.#baseUrl}/models`, {
-				headers: { Authorization: `Bearer ${this.#apiKey}` },
-				signal: AbortSignal.timeout(5000),
-			});
-			if (res.ok) {
-				const data = await res.json();
-				const entry = data.data?.find((m) => m.id === model);
-				if (entry?.context_length) {
-					this.#contextCache.set(model, entry.context_length);
-					return entry.context_length;
-				}
-			}
-		} catch {}
-
-		return DEFAULT_CONTEXT_SIZE;
-	}
-}

package/src/plugins/budget/recovery.js

@@ -1,47 +0,0 @@
-/**
- * Pure recovery state transition — exported for testing.
- *
- * @param {object|null} recovery  Current recovery state.
- * @param {{ assembledTokens: number, budgetRecovery?: { target: number, promptPath: string|null } }} result
- * @returns {{ next: object|null, action: null|'restore'|'hard413', promptPath: string|null }}
- */
-export function advanceRecovery(recovery, result) {
-	// Initialise or update recovery state from a new Turn Demotion event.
-	if (result.budgetRecovery) {
-		if (!recovery) {
-			recovery = {
-				target: result.budgetRecovery.target,
-				promptPath: result.budgetRecovery.promptPath,
-				strikes: 0,
-				lastTokens: result.assembledTokens,
-			};
-		} else {
-			// Re-overflow during recovery: tighten target, don't count as strike.
-			recovery = {
-				...recovery,
-				target: Math.min(recovery.target, result.budgetRecovery.target),
-			};
-		}
-	}
-
-	if (recovery === null) return { next: null, action: null, promptPath: null };
-
-	const current = result.assembledTokens;
-
-	if (current <= recovery.target) {
-		return { next: null, action: "restore", promptPath: recovery.promptPath };
-	}
-
-	const noProgress = current >= recovery.lastTokens && !result.budgetRecovery;
-	const strikes = noProgress ? recovery.strikes + 1 : 0;
-
-	if (strikes >= 3) {
-		return { next: null, action: "hard413", promptPath: null };
-	}
-
-	return {
-		next: { ...recovery, strikes, lastTokens: current },
-		action: null,
-		promptPath: null,
-	};
-}

package/src/plugins/instructions/preamble.md

@@ -1,37 +0,0 @@
-You are a folksonomic knowledgebase assistant. YOU MUST discern what you don't know into unknowns, then extract and organize your findings into navigable and searchable knowns, then YOU MAY answer questions and/or perform actions.
-
-# Tool Commands
-
-Tools: [%TOOLS%]
-
-# Tool Rules
-
-## Response Rules
-Required: YOU MUST respond with Tool Commands in the XML format. YOU MAY use up to 12 tools in your response.
-Required: YOU MUST register all unknowns with <unknown>[specific thing I need to learn]</unknown>.
-Required: YOU MUST register all new facts, decisions, and plans with <known path="topic/subtopic" summary="keyword,keyword,keyword">[specific facts, decisions, or plans]</known>.
-
-## Folksonomic Memory Management
-* Write paths with navigable hierarchies and summaries with searchable tags.
-* When new facts, decisions, and plans appear, set them as <known/> entries with navigable hierarchies and summaries with searchable tags to improve your folksonomic knowledgebase.
-* When new questions emerge, use pattern matching operations to optimize the fidelity and relevance of your knowledgebase.
-* The turn attribute can be helpful for discerning what's fresh or stale, prefer more recent information if conflicts exist.
-* YOU MUST promote all relevant entries and demote all irrelevant entries before acting or answering. Use body pattern search (Example: <get path="known://*">John Doe</get>) to recall archived entries when needed.
-* Logging entries in <previous/> can also be demoted to optimize context.
-
-## Fidelity Management
-* full: Entire contents are shown (consumes token budget)
-* summary: Only path and summary are shown. (<= 80 chars, saves token budget)
-* archive: Archived in an unlimited archive. Entries can be recalled with path recall or pattern search. (use caution)
-
-## Token Budget Management
-* Entries contain a "fidelity" and a "token" attribute to enable token budget management and context optimization.
-* Set relevant entries to "full" and irrelevant entries to "summary" to optimize context.
-* The less irrelevant information in your context, the better.
-
-## Response Termination
-Required: YOU MUST conclude every turn with EITHER <update></update> if still working OR <summarize></summarize> if done. Never both.
-
-# Tool Usage
-
-[%TOOLDOCS%]

package/src/plugins/performed/README.md

@@ -1,15 +0,0 @@
-# performed
-
-Renders the `<performed>` section of the user message — the active loop's
-tool results and lifecycle signals.
-
-## Registration
-
-- **Filter**: `assembly.user` at priority 100
-
-## Behavior
-
-Filters turn_context rows where `category === "logging"` and
-`source_turn >= loopStartTurn`. Renders each entry chronologically
-with turn, status, summary, fidelity, and tokens. Empty on the first
-turn of a loop.

package/src/plugins/performed/performed.js

@@ -1,45 +0,0 @@
-export default class Performed {
-	#core;
-
-	constructor(core) {
-		this.#core = core;
-		core.filter("assembly.user", this.assemblePerformed.bind(this), 100);
-	}
-
-	async assemblePerformed(content, ctx) {
-		const entries = ctx.rows.filter(
-			(r) =>
-				r.category === "logging" &&
-				r.source_turn >= ctx.loopStartTurn &&
-				r.scheme !== "unknown",
-		);
-		if (entries.length === 0) return content;
-
-		const lines = entries.map((e) => renderToolTag(e));
-		return `${content}<performed>\n${lines.join("\n")}\n</performed>\n`;
-	}
-}
-
-function renderToolTag(entry) {
-	const attrs =
-		typeof entry.attributes === "string"
-			? JSON.parse(entry.attributes)
-			: entry.attributes;
-
-	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 fidelity = entry.fidelity ? ` fidelity="${entry.fidelity}"` : "";
-	const tokens = entry.tokens ? ` tokens="${entry.tokens}"` : "";
-	const summary =
-		typeof attrs?.summary === "string"
-			? ` summary="${attrs.summary.slice(0, 80)}"`
-			: "";
-
-	const body = entry.body || null;
-
-	if (body) {
-		return `<${entry.scheme} path="${target}"${turn}${status}${summary}${fidelity}${tokens}>${body}</${entry.scheme}>`;
-	}
-	return `<${entry.scheme} path="${target}"${turn}${status}${summary}${fidelity}${tokens}/>`;
-}

package/src/plugins/previous/README.md

@@ -1,16 +0,0 @@
-# previous
-
-Renders the `<previous>` section of the system message — completed loop
-history from prior ask/act invocations on this run.
-
-## Registration
-
-- **Filter**: `assembly.system` at priority 200
-- **Condition**: Omitted when `loopStartTurn <= 1` (first loop has no history)
-
-## Behavior
-
-Filters turn_context rows where `category` is `logging` or `prompt`
-and `source_turn < loopStartTurn`. Renders each entry chronologically
-with turn, status, summary, fidelity, and tokens. The model can target
-these entries by path with `<set>` or `<rm>` to free context space.

package/src/plugins/previous/previous.js

@@ -1,60 +0,0 @@
-export default class Previous {
-	#core;
-
-	constructor(core) {
-		this.#core = core;
-		core.filter("assembly.system", this.assemblePrevious.bind(this), 200);
-	}
-
-	async assemblePrevious(content, ctx) {
-		if (ctx.loopStartTurn <= 1) return content;
-
-		const entries = ctx.rows
-			.filter(
-				(r) =>
-					(r.category === "logging" || r.category === "prompt") &&
-					r.source_turn < ctx.loopStartTurn,
-			)
-			.toSorted((a, b) => {
-				if (a.source_turn !== b.source_turn)
-					return a.source_turn - b.source_turn;
-				// Within the same turn: prompt first (cause before effect)
-				if (a.category === "prompt" && b.category !== "prompt") return -1;
-				if (b.category === "prompt" && a.category !== "prompt") return 1;
-				return 0;
-			});
-		if (entries.length === 0) return content;
-
-		const lines = await Promise.all(
-			entries.map((e) => renderToolTag(e, this.#core)),
-		);
-		return `${content}\n\n<previous>\n${lines.join("\n")}\n</previous>`;
-	}
-}
-
-async function renderToolTag(entry, _core) {
-	const attrs =
-		typeof entry.attributes === "string"
-			? JSON.parse(entry.attributes)
-			: entry.attributes;
-
-	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 fidelity = entry.fidelity ? ` fidelity="${entry.fidelity}"` : "";
-	const tokens = entry.tokens ? ` tokens="${entry.tokens}"` : "";
-
-	// Previous entries render at summary. Prompts get 512 chars for orientation.
-	const limit = entry.scheme === "prompt" ? 512 : 80;
-	const rawSummary =
-		(typeof attrs?.summary === "string" ? attrs.summary : null) ||
-		entry.body?.slice(0, limit) ||
-		"";
-	// Strip internal dedup namespace prefixes (e.g. "get://turn_3/src/app.js" → "src/app.js")
-	const summaryText = rawSummary.replace(/\b\w+:\/\/turn_\d+\//g, "");
-	const summaryAttr = summaryText
-		? ` summary="${summaryText.replace(/"/g, "'").slice(0, limit)}"`
-		: "";
-
-	return `<${entry.scheme} path="${target}"${turn}${status}${summaryAttr}${fidelity}${tokens}/>`;
-}

package/src/plugins/progress/README.md

@@ -1,16 +0,0 @@
-# progress
-
-Renders the `<progress>` section of the user message — bridges the
-current work log to the active prompt.
-
-## Registration
-
-- **Filter**: `assembly.user` at priority 200
-
-## Behavior
-
-Emits `<progress turn="N">` carrying token budget and fidelity stats.
-On continuation turns with current entries: "The above actions were
-performed in response to the following prompt:"
-
-Progress text is the tuning knob for model orientation between turns.

package/src/plugins/progress/progress.js

@@ -1,26 +0,0 @@
-export default class Progress {
-	#core;
-
-	constructor(core) {
-		this.#core = core;
-		core.filter("assembly.user", this.assembleProgress.bind(this), 200);
-	}
-
-	async assembleProgress(content, ctx) {
-		const { lastContextTokens: usedTokens, contextSize } = ctx;
-		const pct = contextSize ? Math.round((usedTokens / contextSize) * 100) : 0;
-
-		const lines = [];
-		if (contextSize) {
-			lines.push(
-				`Using ${usedTokens} tokens (${pct}%) of ${contextSize} token budget. Use <get/> or set entry fidelity to "full" to spend tokens. Set entry fidelity to "summary" to save tokens.`,
-			);
-		}
-		lines.push(
-			'Conclude with a brief <update></update> to continue or a brief <summarize></summarize> if done.',
-		);
-		const body = lines.join("\n");
-
-		return `${content}<progress turn="${ctx.turn}">${body}</progress>\n`;
-	}
-}

package/src/plugins/summarize/README.md

@@ -1,19 +0,0 @@
-# summarize
-
-Lifecycle signal — the model declares it has completed the task.
-
-## Registration
-
-- **Tool**: `summarize`
-- **Category**: `logging`
-- **Handler**: None — recorded by TurnExecutor as a lifecycle signal.
-
-## Projection
-
-Shows `summarize` followed by the entry body.
-
-## Behavior
-
-If the model sends `<summarize>` but actions in the same turn failed,
-TurnExecutor overrides it to `<update>` — the model's assertion that
-it's done is false.

package/src/plugins/summarize/summarize.js

@@ -1,32 +0,0 @@
-import docs from "./summarizeDoc.js";
-
-export default class Summarize {
-	#core;
-
-	constructor(core) {
-		this.#core = core;
-		core.ensureTool();
-		core.registerScheme({ category: "logging" });
-		core.on("handler", this.handler.bind(this));
-		core.on("full", this.full.bind(this));
-		core.on("summary", this.summary.bind(this));
-		core.filter("instructions.toolDocs", async (docsMap) => {
-			docsMap.summarize = docs;
-			return docsMap;
-		});
-	}
-
-	async handler(entry, rummy) {
-		const { entries: store, sequence: turn, runId, loopId } = rummy;
-		const statusPath = await store.slugPath(runId, "summarize", entry.body);
-		await store.upsert(runId, turn, statusPath, entry.body, 200, { loopId });
-	}
-
-	full(entry) {
-		return `# summarize\n${entry.body}`;
-	}
-
-	summary(entry) {
-		return this.full(entry);
-	}
-}

package/src/plugins/summarize/summarizeDoc.js

@@ -1,28 +0,0 @@
-// Tool doc for <summarize>. Each entry: [text, rationale].
-// Text goes to the model. Rationale stays in source.
-// Changing ANY line requires reading ALL rationales first.
-const LINES = [
-	["## <summarize>[answer or summary]</summarize> - Signal completion"],
-	[
-		"Example: <summarize>The port is 8080</summarize>",
-		"Direct answer. Summarize delivers answers.",
-	],
-	[
-		"Example: <summarize>Installed express, updated config</summarize>",
-		"Task summary. Action completion.",
-	],
-	[
-		"* YOU MUST use <summarize></summarize> when done — describes the final state",
-		"Completion signal.",
-	],
-	[
-		"* YOU MUST NOT use <summarize> if still working — use <update/> instead",
-		"Mutual exclusion with update.",
-	],
-	[
-		"* YOU MUST keep <summarize> to <= 80 characters",
-		"Length cap.",
-	],
-];
-
-export default LINES.map(([text]) => text).join("\n");