@possumtech/rummy 0.2.7 → 0.3.0

package/src/hooks/RummyContext.js

@@ -51,8 +51,24 @@ export default class RummyContext {
 		return this.#context.turnId || null;
 	}
 
-	get noContext() {
-		return this.#context.noContext === true;
+	get loopId() {
+		return this.#context.loopId || null;
+	}
+
+	get noRepo() {
+		return this.#context.noRepo === true;
+	}
+
+	get noInteraction() {
+		return this.#context.noInteraction === true;
+	}
+
+	get noWeb() {
+		return this.#context.noWeb === true;
+	}
+
+	get toolSet() {
+		return this.#context.toolSet || null;
 	}
 
 	get contextSize() {
@@ -85,7 +101,7 @@ export default class RummyContext {
 
 	// --- Tool methods (same operations the model uses) ---
 
-	async set({ path, body, state = "full", attributes } = {}) {
+	async set({ path, body, status = 200, fidelity, attributes } = {}) {
 		if (!path) {
 			const slugify = (await import("../sql/functions/slugify.js")).default;
 			const base = slugify(body || "");
@@ -96,8 +112,8 @@ export default class RummyContext {
 			this.sequence,
 			path,
 			body || "",
-			state,
-			attributes ? { attributes } : undefined,
+			status,
+			{ fidelity, attributes, loopId: this.loopId },
 		);
 		return path;
 	}
@@ -117,14 +133,18 @@ export default class RummyContext {
 	async mv(from, to) {
 		const body = await this.entries.getBody(this.runId, from);
 		if (body === null) return;
-		await this.entries.upsert(this.runId, this.sequence, to, body, "full");
+		await this.entries.upsert(this.runId, this.sequence, to, body, 200, {
+			loopId: this.loopId,
+		});
 		await this.entries.remove(this.runId, from);
 	}
 
 	async cp(from, to) {
 		const body = await this.entries.getBody(this.runId, from);
 		if (body === null) return;
-		await this.entries.upsert(this.runId, this.sequence, to, body, "full");
+		await this.entries.upsert(this.runId, this.sequence, to, body, 200, {
+			loopId: this.loopId,
+		});
 	}
 
 	// --- Plugin-only methods (superset) ---
@@ -137,9 +157,9 @@ export default class RummyContext {
 		return this.entries.getAttributes(this.runId, path);
 	}
 
-	async getState(path) {
+	async getStatus(path) {
 		const row = await this.entries.getState(this.runId, path);
-		return row?.state ?? null;
+		return row?.status ?? null;
 	}
 
 	async getEntry(path) {
@@ -161,7 +181,7 @@ export default class RummyContext {
 
 	async log(message) {
 		const path = `content://${Date.now()}`;
-		await this.entries.upsert(this.runId, this.sequence, path, message, "info");
+		await this.entries.upsert(this.runId, this.sequence, path, message, 200);
 	}
 
 	// --- Node tree methods ---

package/src/hooks/ToolRegistry.js

@@ -1,3 +1,32 @@
+// Tool display order: gather → reason → act → communicate.
+// Position in the list implies priority to the model.
+const TOOL_ORDER = [
+	"get",
+	"set",
+	"known",
+	"unknown",
+	"env",
+	"sh",
+	"rm",
+	"cp",
+	"mv",
+	"search",
+	"summarize",
+	"update",
+	"ask_user",
+];
+
+function sortByPriority(names) {
+	return names.toSorted((a, b) => {
+		const ia = TOOL_ORDER.indexOf(a);
+		const ib = TOOL_ORDER.indexOf(b);
+		if (ia === -1 && ib === -1) return a.localeCompare(b);
+		if (ia === -1) return 1;
+		if (ib === -1) return 1;
+		return ia - ib;
+	});
+}
+
 export default class ToolRegistry {
 	#tools = new Map();
 	#handlers = new Map();
@@ -5,12 +34,9 @@ export default class ToolRegistry {
 
 	ensureTool(scheme) {
 		if (this.#tools.has(scheme)) return;
-		this.#tools.set(scheme, Object.freeze({ modes: new Set(["ask", "act"]) }));
+		this.#tools.set(scheme, Object.freeze({}));
 	}
 
-	// Exception: old register() removed. Plugins use core.on("handler")/core.on("full").
-	// The only remaining caller pathway is ensureTool + onHandle + onView.
-
 	get(name) {
 		return this.#tools.get(name);
 	}
@@ -39,10 +65,33 @@ export default class ToolRegistry {
 					`Every tool must define how its entries appear in the model view.`,
 			);
 		}
+
+		const attrs =
+			typeof entry.attributes === "string"
+				? JSON.parse(entry.attributes)
+				: entry.attributes;
+		const summary = typeof attrs?.summary === "string" ? attrs.summary : null;
+
 		const fidelity = entry.fidelity || "full";
 		const fn = fidelityMap.get(fidelity);
-		if (!fn) return "";
-		return await fn(entry);
+		if (!fn) {
+			// No view for this fidelity — fall back on model-authored summary
+			return summary || "";
+		}
+
+		const body = await fn(entry);
+
+		// Prepend summary keywords above plugin output at summary fidelity
+		if (fidelity === "summary" && summary && body) {
+			return `${summary}\n${body}`;
+		}
+
+		// Fall back to summary attribute when plugin returns empty
+		if (fidelity === "summary" && summary && !body) {
+			return summary;
+		}
+
+		return body;
 	}
 
 	hasView(scheme) {
@@ -59,22 +108,37 @@ export default class ToolRegistry {
 		}
 	}
 
-	get actTools() {
-		return new Set(
-			[...this.#tools.entries()]
-				.filter(([, def]) => def.category === "act")
-				.map(([name]) => name),
-		);
-	}
-
 	get names() {
-		return [...this.#tools.keys()];
+		return sortByPriority([...this.#tools.keys()]);
 	}
 
-	namesForMode(mode) {
-		return [...this.#tools.entries()]
-			.filter(([, def]) => def.modes.has(mode))
-			.map(([name]) => name);
+	/**
+	 * Compute the active tool set for a loop.
+	 * All exclusions — mode, flags — handled here. One mechanism.
+	 */
+	resolveForLoop(
+		mode,
+		{ noInteraction = false, noWeb = false, noBench = false } = {},
+	) {
+		const excluded = new Set();
+		if (mode === "ask") excluded.add("sh");
+		if (mode === "panic") {
+			excluded.add("sh");
+			excluded.add("env");
+			excluded.add("search");
+			excluded.add("ask_user");
+		}
+		if (noInteraction) excluded.add("ask_user");
+		if (noWeb) excluded.add("search");
+		if (noBench) {
+			excluded.add("ask_user");
+			excluded.add("env");
+			excluded.add("sh");
+		}
+		const names = sortByPriority(
+			[...this.#tools.keys()].filter((n) => !excluded.has(n)),
+		);
+		return new Set(names);
 	}
 
 	entries() {

package/src/llm/LlmProvider.js

@@ -90,18 +90,37 @@ export default class LlmProvider {
 	}
 
 	async getContextSize(model) {
+		// DB is the authority — check models table first
+		if (this.#db) {
+			const row = await this.#db.get_model_by_alias.get({ alias: model });
+			if (row?.context_length) return row.context_length;
+		}
+
+		// Fall back to API query
 		const resolvedModel = await this.resolve(model);
+		let size;
 		if (resolvedModel.startsWith("ollama/")) {
 			const localModel = resolvedModel.replace("ollama/", "");
-			return this.#getOllama().getContextSize(localModel);
-		}
-		if (resolvedModel.startsWith("openai/")) {
-			return this.#getOpenAi().getContextSize(resolvedModel);
-		}
-		if (resolvedModel.startsWith("x.ai/")) {
+			size = await this.#getOllama().getContextSize(localModel);
+		} else if (resolvedModel.startsWith("openai/")) {
+			size = await this.#getOpenAi().getContextSize(resolvedModel);
+		} else if (resolvedModel.startsWith("x.ai/")) {
 			const localModel = resolvedModel.replace("x.ai/", "");
-			return this.#getXai().getContextSize(localModel);
+			size = await this.#getXai().getContextSize(localModel);
+		} else {
+			size = await this.#getOpenRouter().getContextSize(resolvedModel);
+		}
+
+		// Cache back to DB for next time
+		if (this.#db && size) {
+			await this.#db.update_model_context_length
+				.run({
+					alias: model,
+					context_length: size,
+				})
+				.catch(() => {});
 		}
-		return this.#getOpenRouter().getContextSize(resolvedModel);
+
+		return size;
 	}
 }

package/src/llm/OpenAiClient.js

@@ -49,6 +49,12 @@ export default class OpenAiClient {
 			);
 			msg.reasoning_content =
 				parts.length > 0 ? [...new Set(parts)].join("\n") : null;
+
+			if (process.env.RUMMY_DEBUG === "true" && msg.reasoning_content) {
+				console.warn(
+					`[RUMMY] Reasoning (${msg.reasoning_content.length} chars): ${msg.reasoning_content.slice(0, 120)}`,
+				);
+			}
 		}
 
 		return data;
@@ -59,6 +65,20 @@ export default class OpenAiClient {
 		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(timeout),
+			});
+			if (propsResponse.ok) {
+				const props = await propsResponse.json();
+				const runtimeCtx = props?.default_generation_settings?.n_ctx;
+				if (runtimeCtx) return runtimeCtx;
+			}
+		} catch {}
+
+		// Fall back to /v1/models for training context
 		const response = await fetch(`${this.#baseUrl}/v1/models`, {
 			headers,
 			signal: AbortSignal.timeout(timeout),

package/src/llm/OpenRouterClient.js

@@ -72,7 +72,29 @@ export default class OpenRouterClient {
 		return data;
 	}
 
-	async getContextSize(_model) {
-		return Number(process.env.RUMMY_CONTEXT_SIZE) || DEFAULT_CONTEXT_SIZE;
+	#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/llm/XaiClient.js

@@ -3,6 +3,7 @@ import msg from "../agent/messages.js";
 export default class XaiClient {
 	#baseUrl;
 	#apiKey;
+	#contextCache = new Map();
 
 	constructor(baseUrl, apiKey) {
 		this.#baseUrl = baseUrl;
@@ -107,7 +108,51 @@ export default class XaiClient {
 		);
 	}
 
-	async getContextSize(_model) {
-		return Number(process.env.RUMMY_CONTEXT_SIZE) || 131072;
+	async getContextSize(model) {
+		if (this.#contextCache.has(model)) return this.#contextCache.get(model);
+
+		if (!this.#apiKey) throw new Error(msg("error.xai_api_key_missing"));
+
+		// Query xAI models endpoint
+		const modelsUrl = this.#baseUrl.replace(/\/responses$/, "/models");
+		const res = await fetch(modelsUrl, {
+			headers: { Authorization: `Bearer ${this.#apiKey}` },
+			signal: AbortSignal.timeout(5000),
+		});
+
+		if (res.ok) {
+			const data = await res.json();
+			const models = data.data || data.models || [];
+			const entry = models.find(
+				(m) => m.id === model || `${m.id}-latest` === model,
+			);
+			if (entry?.context_length) {
+				this.#contextCache.set(model, entry.context_length);
+				return entry.context_length;
+			}
+		}
+
+		// Try /v1/language-models for richer metadata
+		const langUrl = this.#baseUrl.replace(
+			/\/responses$/,
+			`/language-models/${model}`,
+		);
+		const langRes = await fetch(langUrl, {
+			headers: { Authorization: `Bearer ${this.#apiKey}` },
+			signal: AbortSignal.timeout(5000),
+		}).catch(() => null);
+
+		if (langRes?.ok) {
+			const langData = await langRes.json();
+			if (langData?.context_length) {
+				this.#contextCache.set(model, langData.context_length);
+				return langData.context_length;
+			}
+		}
+
+		throw new Error(
+			`Cannot determine context size for xAI model "${model}". ` +
+				"Register the model with addModel(contextLength) or set context_length in the models table.",
+		);
 	}
 }

package/src/plugins/ask_user/README.md

@@ -5,9 +5,8 @@ Presents a question to the user with optional multiple-choice answers.
 ## Registration
 
 - **Tool**: `ask_user`
-- **Modes**: ask, act
-- **Category**: act
-- **Handler**: Parses options (semicolon or comma delimited) and upserts a `proposed` entry awaiting user response.
+- **Category**: `logging`
+- **Handler**: Parses options (semicolon or comma delimited) and upserts at status 202 (proposed) awaiting user response.
 
 ## Projection
 
@@ -15,4 +14,5 @@ Shows the question and answer attributes.
 
 ## Behavior
 
-Options are split by semicolons first, falling back to commas. The entry stays in `proposed` state until resolved by the client.
+Options are split by semicolons first, falling back to commas. The entry
+stays at status 202 until resolved by the client via `run/resolve`.

package/src/plugins/ask_user/ask_user.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import docs from "./ask_userDoc.js";
 
 export default class AskUser {
 	#core;
@@ -9,14 +9,14 @@ export default class AskUser {
 		core.on("handler", this.handler.bind(this));
 		core.on("full", this.full.bind(this));
 		core.on("summary", this.summary.bind(this));
-		const docs = readFileSync(new URL("./docs.md", import.meta.url), "utf8");
-		core.filter("instructions.toolDocs", async (content) =>
-			content ? `${content}\n\n${docs}` : docs,
-		);
+		core.filter("instructions.toolDocs", async (docsMap) => {
+			docsMap.ask_user = docs;
+			return docsMap;
+		});
 	}
 
 	async handler(entry, rummy) {
-		const { entries: store, sequence: turn, runId } = rummy;
+		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const { question, options: rawOptions } = entry.attributes;
 
 		const optionText = rawOptions || entry.body || "";
@@ -28,8 +28,9 @@ export default class AskUser {
 					.filter(Boolean)
 			: [];
 
-		await store.upsert(runId, turn, entry.resultPath, entry.body, "proposed", {
+		await store.upsert(runId, turn, entry.resultPath, entry.body, 202, {
 			attributes: { question, options },
+			loopId,
 		});
 	}
 

package/src/plugins/ask_user/ask_userDoc.js

@@ -0,0 +1,29 @@
+// Tool doc for <ask_user>. Each entry: [text, rationale].
+// Text goes to the model. Rationale stays in source.
+// Changing ANY line requires reading ALL rationales first.
+const LINES = [
+	// --- Syntax: question attr + options in body
+	['## <ask_user question="[Question?]">[option1; option2; ...]</ask_user>'],
+
+	// --- Constraints FIRST: frames correct usage before examples
+	[
+		"* YOU SHOULD use for decisions, preferences, or approvals the user must make",
+		"Positive framing. Shows what ask_user IS for, not just what it isn't.",
+	],
+	[
+		"* YOU SHOULD use <get> to find information before asking the user",
+		"Gentle redirect. Encourages self-sufficiency without forbidding interaction.",
+	],
+
+	// --- Examples: genuine decision points where user input is valuable
+	[
+		'Example: <ask_user question="Which test framework?">Mocha; Jest; Node Native</ask_user>',
+		"Preference decision. Model truly cannot know this without asking.",
+	],
+	[
+		'Example: <ask_user question="Deploy to staging or production?">staging; production</ask_user>',
+		"Consequential action. Shows ask_user for high-stakes choices.",
+	],
+];
+
+export default LINES.map(([text]) => text).join("\n");

package/src/plugins/budget/BudgetGuard.js

@@ -0,0 +1,74 @@
+import { countTokens } from "../../agent/tokens.js";
+
+export class BudgetExceeded extends Error {
+	constructor(path, requested, remaining) {
+		super(
+			`Budget exceeded: ${path} needs ${requested} tokens, ${remaining} remaining`,
+		);
+		this.name = "BudgetExceeded";
+		this.status = 413;
+		this.path = path;
+		this.requested = requested;
+		this.remaining = remaining;
+	}
+}
+
+export default class BudgetGuard {
+	#ceiling;
+	#baseline;
+	#spent;
+	#tripped;
+	#tripSource;
+
+	constructor(ceiling, baseline) {
+		this.#ceiling = ceiling ?? null;
+		this.#baseline = baseline;
+		this.#spent = 0;
+		this.#tripped = false;
+		this.#tripSource = null;
+	}
+
+	get isTripped() {
+		return this.#tripped;
+	}
+
+	get tripSource() {
+		return this.#tripSource;
+	}
+
+	get remaining() {
+		if (this.#ceiling === null) return Infinity;
+		return this.#ceiling - this.#baseline - this.#spent;
+	}
+
+	get spent() {
+		return this.#spent;
+	}
+
+	check(tokens, path) {
+		if (this.#ceiling === null) return;
+		if (this.#tripped) throw new BudgetExceeded(path, tokens, 0);
+		if (tokens <= 0) return;
+		const remaining = this.remaining;
+		if (tokens > remaining) throw new BudgetExceeded(path, tokens, remaining);
+	}
+
+	charge(tokens) {
+		if (tokens > 0) this.#spent += tokens;
+	}
+
+	trip(source) {
+		this.#tripped = true;
+		this.#tripSource = source;
+	}
+
+	/**
+	 * Compute the token delta for an upsert. New entry = full cost.
+	 * Update = difference between new and old body.
+	 */
+	static delta(newBody, existingBody) {
+		const newTokens = countTokens(newBody);
+		const oldTokens = existingBody ? countTokens(existingBody) : 0;
+		return newTokens - oldTokens;
+	}
+}

package/src/plugins/budget/README.md

@@ -0,0 +1,43 @@
+# budget
+
+Context ceiling enforcement and panic mode recovery.
+
+## Files
+
+- **budget.js** — Plugin. Pre-LLM enforce, BudgetGuard activation,
+  panic prompt generation.
+- **BudgetGuard.js** — Write-layer gate. Installed on KnownStore during
+  dispatch. Checks token delta on every upsert, promote, and body update.
+
+## Registration
+
+- **Hook**: `hooks.budget.enforce` — pre-LLM ceiling check.
+- **Hook**: `hooks.budget.activate(store, contextSize, assembledTokens)` — install guard.
+- **Hook**: `hooks.budget.deactivate(store)` — remove guard.
+- **Hook**: `hooks.budget.panicPrompt({ shortfall, assembledTokens, contextSize })` — generate panic prompt.
+
+## Budget Contract
+
+`contextSize` is the ceiling. `countTokens()` is the measurement.
+Over = 413. Under = 200. No margins.
+
+## BudgetGuard
+
+Installed on KnownStore by TurnExecutor before dispatch, cleared in
+`finally`. Gates `upsert()`, `promoteByPattern()`, `updateBodyByPattern()`.
+
+Exemptions: `status >= 400` (error entries), `model_visible = 0` (audit),
+`fidelity = "archive"` (not in context).
+
+On first violation: `BudgetExceeded` thrown, guard trips, all subsequent
+writes fail. TurnExecutor catches per-tool, writes 413 result entry.
+
+## Panic Mode
+
+When a new prompt exceeds the ceiling, AgentLoop enqueues a panic loop.
+The model receives the exact shortfall and must free space using core
+tools (get, set, known, unknown, rm, mv, cp, summarize, update).
+Excluded: sh, env, search, ask_user.
+
+Strike system: 3 consecutive turns without context reduction = hard 413.
+Any reduction resets the counter. One panic attempt per drain cycle.

package/src/plugins/budget/budget.js

@@ -0,0 +1,79 @@
+import { countTokens } from "../../agent/tokens.js";
+import BudgetGuard, { BudgetExceeded } from "./BudgetGuard.js";
+
+function measureMessages(messages) {
+	return messages.reduce((sum, m) => sum + countTokens(m.content), 0);
+}
+
+export { BudgetExceeded };
+
+export default class Budget {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.hooks.budget = {
+			enforce: this.enforce.bind(this),
+			activate: this.activate.bind(this),
+			deactivate: this.deactivate.bind(this),
+			panicPrompt: Budget.panicPrompt,
+			BudgetExceeded,
+		};
+	}
+
+	static panicPrompt({ assembledTokens, contextSize }) {
+		const target = Math.floor(contextSize * 0.75);
+		const mustFree = assembledTokens - target;
+		return [
+			`CONTEXT OVERFLOW: ${assembledTokens} tokens, ceiling ${contextSize}.`,
+			`YOU MUST free ${mustFree} tokens to get below ${target} (75%).`,
+			"YOU MUST NOT load or create new content. Only reduce.",
+			"",
+			"<knowns> above shows each entry with its token count.",
+			"Target the largest entries first.",
+			'<rm path="..."/> to delete entries you no longer need.',
+			'<set path="..." fidelity="summary" summary="keywords"/> to compress.',
+			'<set path="..." fidelity="archive"/> to archive out of context.',
+			"<summarize/> when done. <update/> if still working.",
+		].join("\n");
+	}
+
+	async enforce({ contextSize, messages, rows }) {
+		if (!contextSize) {
+			return { messages, rows, demoted: [], assembledTokens: 0, status: 200 };
+		}
+
+		const assembledTokens = measureMessages(messages);
+
+		console.warn(
+			`[RUMMY] Budget enforce: ${assembledTokens} tokens, ceiling ${contextSize}, ${rows.length} rows`,
+		);
+
+		if (assembledTokens > contextSize) {
+			const overflow = assembledTokens - contextSize;
+			console.warn(
+				`[RUMMY] Budget 413: ${assembledTokens} tokens > ${contextSize} ceiling (${overflow} over)`,
+			);
+			return {
+				messages,
+				rows,
+				demoted: [],
+				assembledTokens,
+				status: 413,
+				overflow,
+			};
+		}
+
+		return { messages, rows, demoted: [], assembledTokens, status: 200 };
+	}
+
+	activate(store, contextSize, assembledTokens) {
+		const guard = new BudgetGuard(contextSize, assembledTokens);
+		store.budgetGuard = guard;
+		return guard;
+	}
+
+	deactivate(store) {
+		store.budgetGuard = null;
+	}
+}