@possumtech/rummy 0.5.0 → 2.0.0

package/src/llm/LlmProvider.js

@@ -1,46 +1,30 @@
 import msg from "../agent/messages.js";
-import OllamaClient from "./OllamaClient.js";
-import OpenAiClient from "./OpenAiClient.js";
-import OpenRouterClient from "./OpenRouterClient.js";
-import XaiClient from "./XaiClient.js";
-
+import {
+	ContextExceededError,
+	isContextExceededMessage,
+	isTransientMessage,
+} from "./errors.js";
+
+const MAX_TRANSIENT_RETRIES = 3;
+
+/**
+ * Thin dispatcher over the LLM provider registry (`hooks.llm.providers`).
+ * Resolves the model alias via the DB, finds the highest-priority provider
+ * whose `matches()` returns true, and delegates. Wraps the call with
+ * transient-error retry and surfaces context-exceeded as a typed
+ * ContextExceededError.
+ *
+ * Vendor-specific HTTP is owned by per-vendor plugins under
+ * `src/plugins/{openai,ollama,xai,openrouter,...}/`. Adding a new vendor
+ * is a matter of adding a plugin — no changes here.
+ */
 export default class LlmProvider {
 	#db;
-	#openRouter;
-	#ollama;
-	#openAi;
-	#xai;
+	#hooks;
 
-	constructor(db) {
+	constructor(db, hooks) {
 		this.#db = db;
-	}
-
-	#getOpenRouter() {
-		this.#openRouter ??= new OpenRouterClient(process.env.OPENROUTER_API_KEY);
-		return this.#openRouter;
-	}
-
-	#getOllama() {
-		this.#ollama ??= new OllamaClient(process.env.OLLAMA_BASE_URL);
-		return this.#ollama;
-	}
-
-	#getOpenAi() {
-		if (!this.#openAi) {
-			const baseUrl = process.env.OPENAI_BASE_URL;
-			if (!baseUrl) throw new Error(msg("error.openai_base_url_missing"));
-			this.#openAi = new OpenAiClient(baseUrl, process.env.OPENAI_API_KEY);
-		}
-		return this.#openAi;
-	}
-
-	#getXai() {
-		if (!this.#xai) {
-			const baseUrl = process.env.XAI_BASE_URL;
-			if (!baseUrl) throw new Error(msg("error.xai_base_url_missing"));
-			this.#xai = new XaiClient(baseUrl, process.env.XAI_API_KEY);
-		}
-		return this.#xai;
+		this.#hooks = hooks;
 	}
 
 	async resolve(alias) {
@@ -49,6 +33,10 @@ export default class LlmProvider {
 		throw new Error(msg("error.model_alias_unknown", { alias }));
 	}
 
+	#selectProvider(modelAlias) {
+		return this.#hooks.llm.providers.find((p) => p.matches(modelAlias));
+	}
+
 	async completion(messages, model, options = {}) {
 		const resolvedModel = await this.resolve(model);
 
@@ -59,68 +47,54 @@ export default class LlmProvider {
 				: undefined);
 		const resolvedOptions = { ...options, temperature };
 
-		if (resolvedModel.startsWith("ollama/")) {
-			const localModel = resolvedModel.replace("ollama/", "");
-			return this.#getOllama().completion(
-				messages,
-				localModel,
-				resolvedOptions,
-			);
-		}
-
-		if (resolvedModel.startsWith("openai/")) {
-			const localModel = resolvedModel.replace("openai/", "");
-			return this.#getOpenAi().completion(
-				messages,
-				localModel,
-				resolvedOptions,
+		const provider = this.#selectProvider(resolvedModel);
+		if (!provider) {
+			throw new Error(
+				`No LLM provider registered for model "${resolvedModel}". ` +
+					`Check your RUMMY_* env vars or register a provider plugin.`,
 			);
 		}
 
-		if (resolvedModel.startsWith("x.ai/")) {
-			const localModel = resolvedModel.replace("x.ai/", "");
-			return this.#getXai().completion(messages, localModel, resolvedOptions);
+		for (let attempt = 0; ; attempt++) {
+			try {
+				return await provider.completion(
+					messages,
+					resolvedModel,
+					resolvedOptions,
+				);
+			} catch (err) {
+				if (isContextExceededMessage(err.message)) {
+					throw new ContextExceededError(err.message, { cause: err });
+				}
+				if (
+					isTransientMessage(err.message) &&
+					attempt < MAX_TRANSIENT_RETRIES
+				) {
+					const delay = 1000 * 2 ** attempt;
+					await new Promise((r) => setTimeout(r, delay));
+					continue;
+				}
+				throw err;
+			}
 		}
-
-		return this.#getOpenRouter().completion(
-			messages,
-			resolvedModel,
-			resolvedOptions,
-		);
 	}
 
 	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;
-		}
+		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/", "");
-			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/", "");
-			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(() => {});
+		const provider = this.#selectProvider(resolvedModel);
+		if (!provider) {
+			throw new Error(
+				`No LLM provider registered for model "${resolvedModel}".`,
+			);
 		}
-
+		const size = await provider.getContextSize(resolvedModel);
+		await this.#db.update_model_context_length.run({
+			alias: model,
+			context_length: size,
+		});
 		return size;
 	}
 }

package/src/llm/errors.js

@@ -0,0 +1,21 @@
+export class ContextExceededError extends Error {
+	constructor(message, { cause } = {}) {
+		super(message);
+		this.name = "ContextExceededError";
+		if (cause) this.cause = cause;
+	}
+}
+
+const CONTEXT_EXCEEDED_PATTERN =
+	/\b(context.*(size|length|limit)|token.*(limit|exceed)|too.*(long|large))\b/i;
+
+export function isContextExceededMessage(message) {
+	return CONTEXT_EXCEEDED_PATTERN.test(String(message));
+}
+
+const TRANSIENT_PATTERN =
+	/\b(503|429|timeout|ECONNREFUSED|ECONNRESET|unavailable)\b/i;
+
+export function isTransientMessage(message) {
+	return TRANSIENT_PATTERN.test(String(message));
+}

package/src/plugins/ask_user/README.md

@@ -1,4 +1,4 @@
-# ask_user
+# ask_user {#ask_user_plugin}
 
 Presents a question to the user with optional multiple-choice answers.
 

package/src/plugins/ask_user/ask_user.js

@@ -1,5 +1,7 @@
 import docs from "./ask_userDoc.js";
 
+const LOG_ACTION_RE = /^log:\/\/turn_\d+\/(\w+)\//;
+
 export default class AskUser {
 	#core;
 
@@ -7,28 +9,50 @@ export default class AskUser {
 		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.ask_user = docs;
 			return docsMap;
 		});
+		core.on("proposal.accepted", this.#onResolved.bind(this));
+		core.on("proposal.rejected", this.#onResolved.bind(this));
+	}
+
+	async #onResolved(ctx) {
+		const m = LOG_ACTION_RE.exec(ctx.path);
+		if (m?.[1] !== "ask_user") return;
+		if (!ctx.output) return;
+		const turn = (await ctx.db.get_run_by_id.get({ id: ctx.runId })).next_turn;
+		await ctx.entries.set({
+			runId: ctx.runId,
+			turn,
+			path: ctx.path,
+			body: ctx.resolvedBody,
+			attributes: { ...ctx.attrs, answer: ctx.output },
+		});
 	}
 
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
+		// XmlParser resolved question/options from attr-or-body already.
 		const { question, options: rawOptions } = entry.attributes;
 
-		const optionText = rawOptions || entry.body || "";
-		const delimiter = optionText.includes(";") ? ";" : ",";
-		const options = optionText
-			? optionText
-					.split(delimiter)
-					.map((o) => o.trim())
-					.filter(Boolean)
-			: [];
+		let options = [];
+		if (rawOptions) {
+			const delimiter = rawOptions.includes(";") ? ";" : ",";
+			options = rawOptions
+				.split(delimiter)
+				.map((o) => o.trim())
+				.filter(Boolean);
+		}
 
-		await store.upsert(runId, turn, entry.resultPath, entry.body, 202, {
+		await store.set({
+			runId,
+			turn,
+			path: entry.resultPath,
+			body: entry.body,
+			state: "proposed",
 			attributes: { question, options },
 			loopId,
 		});
@@ -44,6 +68,7 @@ export default class AskUser {
 
 	summary(entry) {
 		const { question, answer } = entry.attributes;
-		return answer ? `${question} → ${answer}` : question || "";
+		if (answer) return `${question} → ${answer}`;
+		return question;
 	}
 }

package/src/plugins/ask_user/ask_userDoc.js

@@ -1,26 +1,3 @@
-// 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 = [
-	[
-		'## <ask_user question="[Question?]">[option1; option2; ...]</ask_user> - Ask the user a question',
-	],
-	[
-		"* YOU SHOULD use for decisions, preferences, or approvals the user must make",
-		"Positive framing. Shows what ask_user IS for.",
-	],
-	[
-		"* YOU SHOULD use <get></get> to find information before asking the user",
-		"Gentle redirect. Encourages self-sufficiency.",
-	],
-	[
-		'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. High-stakes choice.",
-	],
-];
+import { loadDoc } from "../helpers.js";
 
-export default LINES.map(([text]) => text).join("\n");
+export default loadDoc(import.meta.url, "ask_userDoc.md");

package/src/plugins/ask_user/ask_userDoc.md

@@ -0,0 +1,10 @@
+## <ask_user question="[Question?]">[option1; option2; ...]</ask_user> - Ask the user a question
+
+* YOU SHOULD ONLY use for decisions, preferences, or approvals the user must make
+<!-- Positive framing. Shows what ask_user IS for. -->
+
+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. High-stakes choice. -->

package/src/plugins/budget/README.md

@@ -1,41 +1,43 @@
-# budget
+# budget {#budget_plugin}
 
 Context ceiling enforcement.
 
 ## Design
 
-Ceiling = `floor(contextSize × 0.9)`. The 10% headroom is the system's
-operating room for graceful overflow handling. No per-write gating —
-tools run uninterrupted. Enforcement happens at boundaries.
+Ceiling = `floor(contextSize × RUMMY_BUDGET_CEILING)` (default 0.9). The
+10% headroom is the system's operating room for graceful overflow
+handling. No per-write gating — tools run uninterrupted. Enforcement
+happens at boundaries.
 
 ## Enforcement Points
 
-1. **Pre-LLM enforce** (`budget.enforce`): checks assembled context
-   before the LLM call. If over ceiling → Prompt Demotion (summarize
-   the incoming prompt). Model runs in the headroom.
+1. **Pre-LLM enforce** (`hooks.budget.enforce`): checks assembled context
+   before the LLM call. If over ceiling on turn 1 → Prompt Demotion
+   (demote the incoming prompt, re-materialize, re-check). Runs in the
+   headroom if that fits. On non-first turns or still-over after
+   Prompt Demotion, emits a 413 error via `hooks.error.log` so the
+   strike system treats the overflow as a turn-level event.
 
-2. **Post-dispatch Turn Demotion**: after all tools dispatch, check
-   context. If over ceiling → demote ALL entries from this turn
-   (every scheme except `budget`/`system`/`prompt`/`instructions`,
-   and 4xx error states stay promoted). Write `budget://` entry with
-   directive to demote irrelevant entries and promote fewer next time.
-   Model sees it next turn and adapts.
+2. **Post-dispatch Turn Demotion** (`hooks.budget.postDispatch`): after
+   all tools dispatch, re-materialize and check. If over ceiling →
+   demote ALL visible entries from this turn (status < 400, status
+   preserved — demotion only changes visibility). Emits a 413 error
+   with the 50% rule directive as its message; the error entry is
+   what the model sees next turn.
 
-3. **LLM rejection** (`isContextExceeded`): turn-1 token estimate
-   drift causes LLM to reject. Same demotion pattern.
-
-4. **AgentLoop recovery**: pre-LLM 413 that Prompt Demotion can't
-   resolve. Batch-demote all full entries, budget entry, model gets
-   recovery turns. 3 strikes without progress → hard 413 to client.
-   Only path where 413 reaches the client.
+3. **LLM rejection** (`isContextExceeded` in TurnExecutor): turn-1
+   token estimate drift causes LLM to reject. Same 413 error path as
+   pre-LLM overflow.
 
 ## Files
 
-- **budget.js** — Plugin. Pre-LLM enforce hook.
-- **BudgetGuard.js** — `BudgetExceeded` error type, `delta` utility.
+- **budget.js** — Plugin. Enforce + postDispatch methods exposed on
+  `core.hooks.budget`.
 
 ## Registration
 
-- **Hook**: `hooks.budget.enforce` — pre-LLM ceiling check.
-- **Scheme**: `budget://` — logging category, model-visible. `onView`
-  renders body at all fidelity levels (demoted shows full content).
+- **Hook**: `hooks.budget.enforce` — pre-LLM ceiling check + first-turn
+  Prompt Demotion.
+- **Hook**: `hooks.budget.postDispatch` — post-dispatch re-check + Turn
+  Demotion. Emits 413 errors through the unified error channel; there
+  is no separate `budget://` scheme.