@possumtech/rummy 0.2.1

package/src/llm/OpenAiClient.js

@@ -0,0 +1,80 @@
+import msg from "../agent/messages.js";
+
+export default class OpenAiClient {
+	#baseUrl;
+	#apiKey;
+
+	constructor(baseUrl, apiKey) {
+		this.#baseUrl = String(baseUrl || "").replace(/\/v1\/?$/, "");
+		this.#apiKey = apiKey || "";
+	}
+
+	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 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 msg = choice.message;
+			if (!msg) continue;
+
+			// Normalize reasoning
+			const parts = [msg.reasoning_content, msg.reasoning, msg.thinking].filter(
+				Boolean,
+			);
+			msg.reasoning_content =
+				parts.length > 0 ? [...new Set(parts)].join("\n") : null;
+		}
+
+		return data;
+	}
+
+	async getContextSize(_model) {
+		const timeout = Number(process.env.RUMMY_FETCH_TIMEOUT) || 30_000;
+		const headers = { "Content-Type": "application/json" };
+		if (this.#apiKey) headers.Authorization = `Bearer ${this.#apiKey}`;
+
+		const response = await fetch(`${this.#baseUrl}/v1/models`, {
+			headers,
+			signal: AbortSignal.timeout(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/llm/OpenRouterClient.js

@@ -0,0 +1,78 @@
+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;
+	}
+
+	async getContextSize(_model) {
+		return Number(process.env.RUMMY_CONTEXT_SIZE) || DEFAULT_CONTEXT_SIZE;
+	}
+}

package/src/llm/XaiClient.js

@@ -0,0 +1,113 @@
+import msg from "../agent/messages.js";
+
+export default class XaiClient {
+	#baseUrl;
+	#apiKey;
+
+	constructor(baseUrl, apiKey) {
+		this.#baseUrl = baseUrl;
+		this.#apiKey = apiKey;
+	}
+
+	async completion(messages, model, options = {}) {
+		if (!this.#apiKey) throw new Error(msg("error.xai_api_key_missing"));
+
+		const body = { model, input: messages };
+		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, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${this.#apiKey}`,
+				"Content-Type": "application/json",
+			},
+			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.xai_auth", {
+						status: `${response.status} - ${error}`,
+					}),
+				);
+			}
+			throw new Error(
+				msg("error.xai_api", {
+					status: `${response.status} - ${error}`,
+				}),
+			);
+		}
+
+		const data = await response.json();
+		return this.#normalize(data);
+	}
+
+	#normalize(data) {
+		const output = data.output || [];
+
+		let content = "";
+		let reasoningContent = null;
+
+		for (const item of output) {
+			if (item.type === "reasoning") {
+				const text = this.#extractText(item.content);
+				if (text)
+					reasoningContent = reasoningContent
+						? `${reasoningContent}\n${text}`
+						: text;
+			}
+			if (item.type === "message") {
+				const text = this.#extractText(item.content);
+				if (text) content = content ? `${content}\n${text}` : text;
+			}
+		}
+
+		const usage = data.usage || {};
+		const inputTokens = usage.input_tokens || 0;
+		const outputTokens = usage.output_tokens || 0;
+		return {
+			choices: [
+				{
+					message: {
+						role: "assistant",
+						content,
+						reasoning_content: reasoningContent,
+					},
+				},
+			],
+			usage: {
+				prompt_tokens: inputTokens,
+				cached_tokens: usage.input_tokens_details?.cached_tokens || 0,
+				completion_tokens: outputTokens,
+				reasoning_tokens: usage.output_tokens_details?.reasoning_tokens || 0,
+				total_tokens: inputTokens + outputTokens,
+				cost: (usage.cost_in_usd_ticks || 0) / 10_000_000_000,
+			},
+		};
+	}
+
+	#extractText(content) {
+		if (typeof content === "string") return content;
+		if (!Array.isArray(content)) return null;
+		return (
+			content
+				.filter((c) => c.type === "text" || c.type === "output_text")
+				.map((c) => c.text)
+				.join("\n") || null
+		);
+	}
+
+	async getContextSize(_model) {
+		return Number(process.env.RUMMY_CONTEXT_SIZE) || 131072;
+	}
+}

package/src/plugins/ask_user/README.md

@@ -0,0 +1,18 @@
+# ask_user
+
+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.
+
+## Projection
+
+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.

package/src/plugins/ask_user/ask_user.js

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+
+export default class AskUser {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme();
+		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,
+		);
+	}
+
+	async handler(entry, rummy) {
+		const { entries: store, sequence: turn, runId } = rummy;
+		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)
+			: [];
+
+		await store.upsert(runId, turn, entry.resultPath, entry.body, "proposed", {
+			attributes: { question, options },
+		});
+	}
+
+	full(entry) {
+		const { question, answer } = entry.attributes;
+		const lines = ["# ask_user"];
+		if (question) lines.push(`# Question: ${question}`);
+		if (answer) lines.push(`# Answer: ${answer}`);
+		return lines.join("\n");
+	}
+
+	summary(entry) {
+		const { question, answer } = entry.attributes;
+		return answer ? `${question} → ${answer}` : question || "";
+	}
+}

package/src/plugins/ask_user/docs.md

@@ -0,0 +1,2 @@
+## <ask_user question="[Question?]">[option1; option2; ...]</ask_user>
+Example: <ask_user question="Which test framework?">Mocha; Jest; Node Native</ask_user>

package/src/plugins/cp/README.md

@@ -0,0 +1,18 @@
+# cp
+
+Copies an entry from one path to another within the K/V store.
+
+## Registration
+
+- **Tool**: `cp`
+- **Modes**: ask, act
+- **Category**: act
+- **Handler**: Reads source body, writes to destination. K/V destinations resolve immediately (`pass`); file destinations produce a `proposed` entry.
+
+## Projection
+
+Shows `cp {from} {to}`.
+
+## Behavior
+
+Warns if the destination already exists and will be overwritten. Uses `KnownStore.scheme()` to determine whether the destination is a K/V path or a file path.

package/src/plugins/cp/cp.js

@@ -0,0 +1,55 @@
+import { readFileSync } from "node:fs";
+import KnownStore from "../../agent/KnownStore.js";
+
+export default class Cp {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme({
+			validStates: ["full", "proposed", "pass", "rejected", "error", "pattern"],
+		});
+		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,
+		);
+	}
+
+	async handler(entry, rummy) {
+		const { entries: store, sequence: turn, runId } = rummy;
+		const { path, to } = entry.attributes;
+
+		const source = await store.getBody(runId, path);
+		if (source === null) return;
+
+		const destScheme = KnownStore.scheme(to);
+		const existing = await store.getBody(runId, to);
+		const warning =
+			existing !== null && destScheme !== null
+				? `Overwrote existing entry at ${to}`
+				: null;
+
+		const body = `${path} ${to}`;
+		if (destScheme === null) {
+			await store.upsert(runId, turn, entry.resultPath, body, "proposed", {
+				attributes: { from: path, to, isMove: false, warning },
+			});
+		} else {
+			await store.upsert(runId, turn, to, source, "full");
+			await store.upsert(runId, turn, entry.resultPath, body, "pass", {
+				attributes: { from: path, to, isMove: false, warning },
+			});
+		}
+	}
+
+	full(entry) {
+		return `# cp ${entry.attributes.from || ""} ${entry.attributes.to || ""}`;
+	}
+
+	summary(entry) {
+		return this.full(entry);
+	}
+}

package/src/plugins/cp/docs.md

@@ -0,0 +1,2 @@
+## <cp path="[path/to/origin"]>[path/to/destination]</cp> - Copy a file or entry
+Example: <cp path="docs/example.txt">docs/example_copy.txt</cp>

package/src/plugins/current/README.md

@@ -0,0 +1,14 @@
+# current
+
+Renders the `<current>` section of the user message — the active loop's
+model responses, tool results, and agent warnings.
+
+## Registration
+
+- **Filter**: `assembly.user` at priority 100
+
+## Behavior
+
+Filters turn_context rows where `category` is `result` or `structural`
+and `source_turn >= loopStartTurn`. Renders each entry chronologically
+with status symbols. Empty on the first turn of a loop.

package/src/plugins/current/current.js

@@ -0,0 +1,48 @@
+export default class Current {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.filter("assembly.user", this.assembleCurrent.bind(this), 100);
+	}
+
+	async assembleCurrent(content, ctx) {
+		const entries = ctx.rows.filter(
+			(r) =>
+				(r.category === "result" || r.category === "structural") &&
+				r.source_turn >= ctx.loopStartTurn,
+		);
+		if (entries.length === 0) return content;
+
+		const lines = await Promise.all(
+			entries.map((e) => renderToolTag(e, "full", this.#core)),
+		);
+		return `${content}<current>\n${lines.join("\n")}\n</current>\n`;
+	}
+}
+
+async function renderToolTag(entry, fidelity, core) {
+	const attrs =
+		typeof entry.attributes === "string"
+			? JSON.parse(entry.attributes)
+			: entry.attributes;
+
+	const path = `${entry.scheme}://${attrs?.path || attrs?.file || attrs?.command || ""}`;
+	const status = entry.state ? ` status="${entry.state}"` : "";
+
+	let body;
+	try {
+		body = await core.hooks.tools.view(entry.scheme, {
+			...entry,
+			fidelity,
+			attributes: attrs,
+		});
+	} catch {
+		body = entry.body;
+	}
+
+	if (body) {
+		return `<tool path="${path}"${status}>${body}</tool>`;
+	}
+	return `<tool path="${path}"${status}/>`;
+}

package/src/plugins/engine/README.md

@@ -0,0 +1,12 @@
+# engine
+
+SQL infrastructure for context assembly and turn management. No JS plugin.
+
+## Files
+
+- **engine.sql** — Queries for retrieving promoted entries by scheme tier, model visibility, and state.
+- **turn_context.sql** — Queries for clearing and reading the `turn_context` / `v_model_context` view, which produces the ordered context sent to the model.
+
+## Behavior
+
+These SQL files are loaded by the database layer and used by the agent loop to assemble per-turn model context. They are not a plugin in the `register()` sense.

package/src/plugins/engine/engine.sql

@@ -0,0 +1,18 @@
+-- PREP: get_promoted_entries
+SELECT ke.path, ke.scheme, ke.state, ke.turn, ke.tokens, ke.refs
+FROM known_entries AS ke
+JOIN schemes AS s ON s.name = COALESCE(ke.scheme, 'file')
+WHERE
+	ke.run_id = :run_id
+	AND ke.state IN ('full', 'summary')
+	AND s.model_visible = 1
+ORDER BY ke.turn, ke.refs, ke.tokens DESC;
+
+-- PREP: get_promoted_token_total
+SELECT COALESCE(SUM(ke.tokens), 0) AS total
+FROM known_entries AS ke
+JOIN schemes AS s ON s.name = COALESCE(ke.scheme, 'file')
+WHERE
+	ke.run_id = :run_id
+	AND ke.state IN ('full', 'summary')
+	AND s.model_visible = 1;

package/src/plugins/engine/turn_context.sql

@@ -0,0 +1,51 @@
+-- PREP: clear_turn_context
+DELETE FROM turn_context
+WHERE run_id = :run_id AND turn = :turn;
+
+-- PREP: get_model_context
+SELECT
+	ordinal, path, scheme, fidelity, state, body, tokens, attributes, category, turn
+FROM v_model_context
+WHERE run_id = :run_id
+ORDER BY ordinal;
+
+-- PREP: insert_turn_context
+INSERT INTO turn_context (
+	run_id, turn, ordinal, path, fidelity, state, body, tokens, attributes, category, source_turn
+)
+VALUES (
+	:run_id, :turn, :ordinal, :path, :fidelity, :state, :body, :tokens
+	, COALESCE(:attributes, '{}'), :category, :source_turn
+);
+
+-- PREP: get_turn_context
+SELECT ordinal, path, scheme, fidelity, state, body, tokens, attributes, category, source_turn
+FROM turn_context
+WHERE run_id = :run_id AND turn = :turn
+ORDER BY ordinal;
+
+-- PREP: get_turn_budget
+SELECT COALESCE(SUM(tokens), 0) AS total
+FROM turn_context
+WHERE run_id = :run_id AND turn = :turn;
+
+-- PREP: get_turn_distribution
+SELECT
+	CASE category
+		WHEN 'file' THEN 'files'
+		WHEN 'file_symbols' THEN 'files'
+		WHEN 'file_index' THEN 'keys'
+		WHEN 'known' THEN 'known'
+		WHEN 'known_index' THEN 'keys'
+		WHEN 'unknown' THEN 'history'
+		WHEN 'result' THEN 'history'
+		WHEN 'prompt' THEN 'system'
+		WHEN 'system' THEN 'system'
+		ELSE 'system'
+	END AS bucket,
+	COALESCE(SUM(tokens), 0) AS tokens,
+	COUNT(*) AS entries
+FROM turn_context
+WHERE run_id = :run_id AND turn = :turn
+GROUP BY 1
+ORDER BY 1;

package/src/plugins/env/README.md

@@ -0,0 +1,14 @@
+# env
+
+Stores environment/context information as a pass-through entry.
+
+## Registration
+
+- **Tool**: `env`
+- **Modes**: ask, act
+- **Category**: ask
+- **Handler**: Upserts the entry body as `pass` state with original attributes preserved.
+
+## Projection
+
+Shows `env {command}` followed by the entry body.

package/src/plugins/env/docs.md

@@ -0,0 +1,2 @@
+## <env>[command]</env> - Run an exploratory shell command
+Example: <env>npm --version</env>

package/src/plugins/env/env.js

@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+
+export default class Env {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme();
+		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,
+		);
+	}
+
+	async handler(entry, rummy) {
+		const { entries: store, sequence: turn, runId } = rummy;
+		await store.upsert(runId, turn, entry.resultPath, entry.body, "pass", {
+			attributes: entry.attributes,
+		});
+	}
+
+	full(entry) {
+		return `# env ${entry.attributes.command || ""}\n${entry.body}`;
+	}
+
+	summary(entry) {
+		return entry.attributes.command || "";
+	}
+}

package/src/plugins/file/README.md

@@ -0,0 +1,25 @@
+# file
+
+Owns file-related projections and file constraint management.
+
+## Files
+
+- **file.js** — Plugin registration, projection hooks, and constraint CRUD (activate, ignore, drop).
+- **FileScanner.js** — Scans project directories for file entries.
+- **GitProvider.js** — Git integration for file discovery and status.
+- **ProjectContext.js** — Builds project-level context from scanned files.
+- **FsProvider.js** — Filesystem abstraction for file reading/writing.
+
+## Registration
+
+- **Projections**: Registers `onProject` handlers for schemes: `file`, `known`, `skill`, `ask`, `act`, `progress`. All project the entry body directly.
+- **No tool handler** — file operations are dispatched through `set`, `get`, `rm`, etc.
+
+## File Constraints
+
+Static methods `activate`, `ignore`, and `drop` manage per-project file constraints in the database. Constraints control file visibility across all runs:
+
+- `active` / `readonly` — always promoted into context.
+- `ignore` — excluded from scans; demotes existing entries.
+
+Paths are normalized to project-relative when absolute.