@possumtech/rummy 0.2.1

package/src/hooks/Hooks.js

@@ -0,0 +1,115 @@
+import HookRegistry from "./HookRegistry.js";
+import ToolRegistry from "./ToolRegistry.js";
+
+/**
+ * createHooks returns a structured, strictly-typed API for registering
+ * and emitting hooks, removing the dynamic stringly-typed Proxy magic.
+ */
+export default function createHooks(debug = false) {
+	const registry = new HookRegistry(debug);
+	const tools = new ToolRegistry();
+
+	const createEvent = (tag) => ({
+		on: (callback, priority) => registry.addEvent(tag, callback, priority),
+		emit: (...args) => registry.emitEvent(tag, ...args),
+	});
+
+	const createFilter = (tag) => ({
+		addFilter: (callback, priority) =>
+			registry.addFilter(tag, callback, priority),
+		filter: (value, ...args) => registry.applyFilters(tag, value, ...args),
+	});
+
+	return {
+		// Core Turn Pipeline
+		onTurn: registry.onTurn.bind(registry),
+		processTurn: registry.processTurn.bind(registry),
+
+		// Explicit Hook Schema
+		project: {
+			init: {
+				started: createEvent("project.init.started"),
+				completed: createEvent("project.init.completed"),
+			},
+			files: {
+				update: {
+					started: createEvent("project.files.update.started"),
+					completed: createEvent("project.files.update.completed"),
+				},
+			},
+		},
+		run: {
+			started: createEvent("run.started"),
+			progress: createEvent("run.progress"),
+			state: createEvent("run.state"),
+			config: createFilter("run.config"),
+			step: {
+				completed: createEvent("run.step.completed"),
+			},
+		},
+		turn: {
+			started: createEvent("turn.started"),
+			response: createEvent("turn.response"),
+			proposing: createEvent("turn.proposing"),
+		},
+		assembly: {
+			system: createFilter("assembly.system"),
+			user: createFilter("assembly.user"),
+		},
+		instructions: {
+			toolDocs: createFilter("instructions.toolDocs"),
+		},
+		ask: {
+			started: createEvent("ask.started"),
+			completed: createEvent("ask.completed"),
+		},
+		act: {
+			started: createEvent("act.started"),
+			completed: createEvent("act.completed"),
+		},
+		llm: {
+			request: {
+				started: createEvent("llm.request.started"),
+				completed: createEvent("llm.request.completed"),
+			},
+			messages: createFilter("llm.messages"),
+			response: createFilter("llm.response"),
+		},
+		file: {},
+		prompt: {
+			tools: createFilter("prompt.tools"),
+		},
+		entry: {
+			created: createEvent("entry.created"),
+			changed: createEvent("entry.changed"),
+		},
+		action: {},
+		ui: {
+			render: createEvent("ui.render"),
+			notify: createEvent("ui.notify"),
+		},
+		socket: {
+			message: {
+				raw: createFilter("socket.message.raw"),
+			},
+		},
+		rpc: {
+			started: createEvent("rpc.started"),
+			completed: createEvent("rpc.completed"),
+			error: createEvent("rpc.error"),
+			request: createFilter("rpc.request"),
+			response: {
+				result: createFilter("rpc.response.result"),
+			},
+			registry: null, // attached by service.js after RpcRegistry creation
+		},
+		agent: {},
+		tools,
+
+		// Utility to add raw filters/events directly if needed for tests
+		addFilter: registry.addFilter.bind(registry),
+		applyFilters: registry.applyFilters.bind(registry),
+		addEvent: registry.addEvent.bind(registry),
+		emitEvent: registry.emitEvent.bind(registry),
+	};
+}

package/src/hooks/PluginContext.js

@@ -0,0 +1,116 @@
+/**
+ * PluginContext is the plugin-only interface to the rummy system.
+ * Available as `rummy.core` on the per-turn RummyContext, and as the
+ * direct object passed to plugin constructors at startup.
+ *
+ * Carries plugin identity, hook registration, and infrastructure access.
+ * The unified API (tool verbs, queries) lives on RummyContext.
+ * This is the tier boundary: clients can't reach core.
+ */
+export default class PluginContext {
+	#name;
+	#hooks;
+	#db = null;
+	#store = null;
+
+	constructor(name, hooks) {
+		this.#name = name;
+		this.#hooks = hooks;
+	}
+
+	get name() {
+		return this.#name;
+	}
+
+	get db() {
+		return this.#db;
+	}
+
+	set db(value) {
+		this.#db = value;
+	}
+
+	get entries() {
+		return this.#store;
+	}
+
+	set entries(value) {
+		this.#store = value;
+	}
+
+	#schemes = [];
+
+	get hooks() {
+		return this.#hooks;
+	}
+
+	get schemes() {
+		return this.#schemes;
+	}
+
+	registerScheme({
+		name,
+		fidelity = "full",
+		modelVisible = 1,
+		validStates = ["full", "proposed", "pass", "rejected", "error"],
+		category = "result",
+	} = {}) {
+		this.#schemes.push({
+			name: name || this.#name,
+			fidelity,
+			model_visible: modelVisible,
+			valid_states: JSON.stringify(validStates),
+			category,
+		});
+	}
+
+	/**
+	 * Register a named callback for this plugin.
+	 * "handler" registers the tool handler.
+	 * "full"/"summary" register fidelity projections.
+	 * "docs" sets tool documentation.
+	 * Everything else resolves to a hook event.
+	 */
+	on(event, callback, priority = 10) {
+		if (event === "handler") {
+			this.#hooks.tools.ensureTool(this.#name);
+			this.#hooks.tools.onHandle(this.#name, callback, priority);
+			return;
+		}
+		if (event === "full" || event === "summary") {
+			this.#hooks.tools.ensureTool(this.#name);
+			this.#hooks.tools.onView(this.#name, callback, event);
+			return;
+		}
+		const hook = this.#resolveEvent(event);
+		if (hook) hook.on(callback, priority);
+	}
+
+	/**
+	 * Register a filter callback.
+	 */
+	filter(name, callback, priority = 10) {
+		const hook = this.#resolveFilter(name);
+		if (hook) hook.addFilter(callback, priority);
+	}
+
+	#resolveEvent(name) {
+		const parts = name.split(".");
+		let node = this.#hooks;
+		for (const part of parts) {
+			node = node?.[part];
+		}
+		if (node?.on) return node;
+		return null;
+	}
+
+	#resolveFilter(name) {
+		const parts = name.split(".");
+		let node = this.#hooks;
+		for (const part of parts) {
+			node = node?.[part];
+		}
+		if (node?.addFilter) return node;
+		return null;
+	}
+}

package/src/hooks/RummyContext.js

@@ -0,0 +1,181 @@
+/**
+ * RummyContext provides a unified, semantic API for plugins to interact with
+ * the Turn node tree and core resources like the Database and Project metadata.
+ */
+export default class RummyContext {
+	#root;
+	#context;
+
+	constructor(root, context) {
+		this.#root = root;
+		this.#context = context;
+	}
+
+	get hooks() {
+		return this.#context.hooks || null;
+	}
+
+	get db() {
+		return this.#context.db;
+	}
+
+	get entries() {
+		return this.#context.store || null;
+	}
+
+	get project() {
+		return this.#context.project;
+	}
+
+	get activeFiles() {
+		return this.#context.activeFiles || [];
+	}
+
+	get type() {
+		return this.#context.type;
+	}
+
+	get projectId() {
+		return this.#context.projectId;
+	}
+
+	get sequence() {
+		return this.#context.sequence || 0;
+	}
+
+	get runId() {
+		return this.#context.runId || null;
+	}
+
+	get turnId() {
+		return this.#context.turnId || null;
+	}
+
+	get noContext() {
+		return this.#context.noContext === true;
+	}
+
+	get contextSize() {
+		return this.#context.contextSize || null;
+	}
+
+	get systemPrompt() {
+		return this.#context.systemPrompt || "";
+	}
+
+	get loopPrompt() {
+		return this.#context.loopPrompt || "";
+	}
+
+	get system() {
+		return this.#root.children.find((c) => c.tag === "system");
+	}
+
+	get contextEl() {
+		return this.#root.children.find((c) => c.tag === "context");
+	}
+
+	get user() {
+		return this.#root.children.find((c) => c.tag === "user");
+	}
+
+	get assistant() {
+		return this.#root.children.find((c) => c.tag === "assistant");
+	}
+
+	// --- Tool methods (same operations the model uses) ---
+
+	async set({ path, body, state = "full", attributes } = {}) {
+		if (!path) {
+			const slugify = (await import("../sql/functions/slugify.js")).default;
+			const base = slugify(body || "");
+			path = `known://${base || Date.now()}`;
+		}
+		await this.entries.upsert(
+			this.runId,
+			this.sequence,
+			path,
+			body || "",
+			state,
+			attributes ? { attributes } : undefined,
+		);
+		return path;
+	}
+
+	async get(path) {
+		await this.entries.promoteByPattern(this.runId, path, null, this.sequence);
+	}
+
+	async store(path) {
+		await this.entries.demoteByPattern(this.runId, path, null);
+	}
+
+	async rm(path) {
+		await this.entries.remove(this.runId, path);
+	}
+
+	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.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");
+	}
+
+	// --- Plugin-only methods (superset) ---
+
+	async getBody(path) {
+		return this.entries.getBody(this.runId, path);
+	}
+
+	async getAttributes(path) {
+		return this.entries.getAttributes(this.runId, path);
+	}
+
+	async getState(path) {
+		const row = await this.entries.getState(this.runId, path);
+		return row?.state ?? null;
+	}
+
+	async getEntry(path) {
+		const results = await this.entries.getEntriesByPattern(
+			this.runId,
+			path,
+			null,
+		);
+		return results[0] || null;
+	}
+
+	async setAttributes(path, attrs) {
+		return this.entries.setAttributes(this.runId, path, attrs);
+	}
+
+	async getEntries(pattern, bodyFilter) {
+		return this.entries.getEntriesByPattern(this.runId, pattern, bodyFilter);
+	}
+
+	async log(message) {
+		const path = `content://${Date.now()}`;
+		await this.entries.upsert(this.runId, this.sequence, path, message, "info");
+	}
+
+	// --- Node tree methods ---
+
+	tag(name, attrs = {}, children = []) {
+		const node = { tag: name, attrs, content: null, children: [] };
+		const childArray = Array.isArray(children) ? children : [children];
+		for (const child of childArray) {
+			if (typeof child === "string") {
+				node.content = (node.content || "") + child;
+			} else if (child && typeof child === "object") {
+				node.children.push(child);
+			}
+		}
+		return node;
+	}
+}

package/src/hooks/ToolRegistry.js

@@ -0,0 +1,83 @@
+export default class ToolRegistry {
+	#tools = new Map();
+	#handlers = new Map();
+	#views = new Map();
+
+	ensureTool(scheme) {
+		if (this.#tools.has(scheme)) return;
+		this.#tools.set(scheme, Object.freeze({ modes: new Set(["ask", "act"]) }));
+	}
+
+	// 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);
+	}
+
+	has(name) {
+		return this.#tools.has(name);
+	}
+
+	onHandle(scheme, handler, priority = 10) {
+		if (!this.#handlers.has(scheme)) this.#handlers.set(scheme, []);
+		const list = this.#handlers.get(scheme);
+		list.push({ handler, priority });
+		list.sort((a, b) => a.priority - b.priority);
+	}
+
+	onView(scheme, fn, fidelity = "full") {
+		if (!this.#views.has(scheme)) this.#views.set(scheme, new Map());
+		this.#views.get(scheme).set(fidelity, fn);
+	}
+
+	async view(scheme, entry) {
+		const fidelityMap = this.#views.get(scheme);
+		if (!fidelityMap) {
+			throw new Error(
+				`No view registered for scheme '${scheme}'. ` +
+					`Every tool must define how its entries appear in the model view.`,
+			);
+		}
+		const fidelity = entry.fidelity || "full";
+		const fn = fidelityMap.get(fidelity);
+		if (!fn) return "";
+		return await fn(entry);
+	}
+
+	hasView(scheme) {
+		const fidelityMap = this.#views.get(scheme);
+		return fidelityMap?.size > 0;
+	}
+
+	async dispatch(scheme, entry, rummy) {
+		const list = this.#handlers.get(scheme);
+		if (!list) return;
+		for (const { handler } of list) {
+			const result = await handler(entry, rummy);
+			if (result === false) break;
+		}
+	}
+
+	get actTools() {
+		return new Set(
+			[...this.#tools.entries()]
+				.filter(([, def]) => def.category === "act")
+				.map(([name]) => name),
+		);
+	}
+
+	get names() {
+		return [...this.#tools.keys()];
+	}
+
+	namesForMode(mode) {
+		return [...this.#tools.entries()]
+			.filter(([, def]) => def.modes.has(mode))
+			.map(([name]) => name);
+	}
+
+	entries() {
+		return this.#tools.entries();
+	}
+}

package/src/llm/LlmProvider.js

@@ -0,0 +1,107 @@
+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";
+
+export default class LlmProvider {
+	#db;
+	#openRouter;
+	#ollama;
+	#openAi;
+	#xai;
+
+	constructor(db) {
+		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;
+	}
+
+	async resolve(alias) {
+		const row = await this.#db.get_model_by_alias.get({ alias });
+		if (row) return row.actual;
+		throw new Error(msg("error.model_alias_unknown", { alias }));
+	}
+
+	async completion(messages, model, options = {}) {
+		const resolvedModel = await this.resolve(model);
+
+		const temperature =
+			options.temperature ??
+			(process.env.RUMMY_TEMPERATURE !== undefined
+				? Number.parseFloat(process.env.RUMMY_TEMPERATURE)
+				: 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,
+			);
+		}
+
+		if (resolvedModel.startsWith("x.ai/")) {
+			const localModel = resolvedModel.replace("x.ai/", "");
+			return this.#getXai().completion(messages, localModel, resolvedOptions);
+		}
+
+		return this.#getOpenRouter().completion(
+			messages,
+			resolvedModel,
+			resolvedOptions,
+		);
+	}
+
+	async getContextSize(model) {
+		const resolvedModel = await this.resolve(model);
+		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/")) {
+			const localModel = resolvedModel.replace("x.ai/", "");
+			return this.#getXai().getContextSize(localModel);
+		}
+		return this.#getOpenRouter().getContextSize(resolvedModel);
+	}
+}

package/src/llm/OllamaClient.js

@@ -0,0 +1,88 @@
+import msg from "../agent/messages.js";
+
+export default class OllamaClient {
+	#baseUrl;
+
+	constructor(baseUrl) {
+		this.#baseUrl = baseUrl;
+	}
+
+	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 response = await fetch(`${this.#baseUrl}/v1/chat/completions`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body),
+			signal,
+		});
+
+		if (!response.ok) {
+			const error = await response.text();
+			throw new Error(
+				msg("error.ollama_api", { status: `${response.status} - ${error}` }),
+			);
+		}
+
+		const data = await response.json();
+
+		for (const choice of data.choices || []) {
+			const msg = choice.message;
+			if (!msg) continue;
+			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) {
+		for (let attempt = 0; attempt < 3; attempt++) {
+			try {
+				const response = await fetch(`${this.#baseUrl}/api/show`, {
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({ model }),
+					signal: AbortSignal.timeout(
+						Number(process.env.RUMMY_FETCH_TIMEOUT) || 30_000,
+					),
+				});
+				if (!response.ok) {
+					throw new Error(
+						msg("error.ollama_show_failed", {
+							status: response.status,
+							baseUrl: this.#baseUrl,
+						}),
+					);
+				}
+				const data = await response.json();
+				const info = data.model_info || {};
+				for (const [key, value] of Object.entries(info)) {
+					if (key.endsWith(".context_length")) return value;
+				}
+				throw new Error(msg("error.ollama_no_context_length", { model }));
+			} catch (err) {
+				if (err.message.includes("Ollama")) throw err;
+				if (attempt < 2) {
+					await new Promise((r) => setTimeout(r, (attempt + 1) * 2000));
+					continue;
+				}
+				throw new Error(
+					msg("error.ollama_unreachable", { baseUrl: this.#baseUrl }),
+					{ cause: err },
+				);
+			}
+		}
+	}
+}