@possumtech/rummy 0.2.8 → 0.3.1

package/src/server/ClientConnection.js

@@ -21,53 +21,66 @@ export default class ClientConnection {
 		this.#projectAgent = new ProjectAgent(db, hooks);
 
 		this.#ws.on("message", (data) => this.#handleMessage(data));
+		this.#ws.on("close", () => this.#teardown());
 
 		this.#setupNotifications();
 	}
 
-	#setupNotifications() {
-		this.#hooks.run.progress.on((payload) => {
-			if (payload.projectId === this.#context.projectId) {
-				this.#sendNotification("run/progress", {
-					run: payload.run,
-					turn: payload.turn,
-					status: payload.status,
-				});
-			}
-		});
+	#onProgress = (payload) => {
+		if (payload.projectId === this.#context.projectId) {
+			this.#sendNotification("run/progress", {
+				run: payload.run,
+				turn: payload.turn,
+				status: payload.status,
+			});
+		}
+	};
 
-		this.#hooks.ui.render.on((payload) => {
-			if (payload.projectId === this.#context.projectId) {
-				this.#sendNotification("ui/render", {
-					text: payload.text,
-					append: payload.append,
-				});
-			}
-		});
+	#onRender = (payload) => {
+		if (payload.projectId === this.#context.projectId) {
+			this.#sendNotification("ui/render", {
+				text: payload.text,
+				append: payload.append,
+			});
+		}
+	};
 
-		this.#hooks.ui.notify.on((payload) => {
-			if (payload.projectId === this.#context.projectId) {
-				this.#sendNotification("ui/notify", {
-					text: payload.text,
-					level: payload.level,
-				});
-			}
-		});
+	#onNotify = (payload) => {
+		if (payload.projectId === this.#context.projectId) {
+			this.#sendNotification("ui/notify", {
+				text: payload.text,
+				level: payload.level,
+			});
+		}
+	};
 
-		this.#hooks.run.state.on((payload) => {
-			if (payload.projectId === this.#context.projectId) {
-				this.#sendNotification("run/state", {
-					run: payload.run,
-					turn: payload.turn,
-					status: payload.status,
-					summary: payload.summary,
-					history: payload.history,
-					unknowns: payload.unknowns,
-					proposed: payload.proposed,
-					telemetry: payload.telemetry,
-				});
-			}
-		});
+	#onState = (payload) => {
+		if (payload.projectId === this.#context.projectId) {
+			this.#sendNotification("run/state", {
+				run: payload.run,
+				turn: payload.turn,
+				status: payload.status,
+				summary: payload.summary,
+				history: payload.history,
+				unknowns: payload.unknowns,
+				proposed: payload.proposed,
+				telemetry: payload.telemetry,
+			});
+		}
+	};
+
+	#setupNotifications() {
+		this.#hooks.run.progress.on(this.#onProgress);
+		this.#hooks.ui.render.on(this.#onRender);
+		this.#hooks.ui.notify.on(this.#onNotify);
+		this.#hooks.run.state.on(this.#onState);
+	}
+
+	#teardown() {
+		this.#hooks.run.progress.off(this.#onProgress);
+		this.#hooks.ui.render.off(this.#onRender);
+		this.#hooks.ui.notify.off(this.#onNotify);
+		this.#hooks.run.state.off(this.#onState);
 	}
 
 	#buildHandlerContext() {
@@ -135,10 +148,11 @@ export default class ClientConnection {
 				);
 			} else {
 				const timeout = Number(process.env.RUMMY_RPC_TIMEOUT) || 10_000;
+				let timer;
 				result = await Promise.race([
 					registration.handler(params || {}, this.#buildHandlerContext()),
-					new Promise((_, reject) =>
-						setTimeout(
+					new Promise((_, reject) => {
+						timer = setTimeout(
 							() =>
 								reject(
 									new Error(
@@ -149,9 +163,9 @@ export default class ClientConnection {
 									),
 								),
 							timeout,
-						),
-					),
-				]);
+						);
+					}),
+				]).finally(() => clearTimeout(timer));
 			}
 
 			const finalResult = await this.#hooks.rpc.response.result.filter(result, {

package/src/server/RpcRegistry.js

@@ -12,8 +12,6 @@ export default class RpcRegistry {
 			longRunning = false,
 		},
 	) {
-		if (this.#methods.has(name))
-			throw new Error(`RPC method '${name}' already registered.`);
 		this.#methods.set(
 			name,
 			Object.freeze({
@@ -26,16 +24,57 @@ export default class RpcRegistry {
 		);
 	}
 
+	#toolFallback = null;
+
+	/**
+	 * Set a fallback that auto-dispatches any registered tool via RPC.
+	 * Checked at request time — tools registered after this call still work.
+	 */
+	setToolFallback(hooks, buildRunContext, dispatchTool) {
+		this.#toolFallback = { hooks, buildRunContext, dispatchTool };
+	}
+
 	registerNotification(name, description = "") {
 		this.#notifications.set(name, Object.freeze({ description }));
 	}
 
 	get(name) {
-		return this.#methods.get(name);
+		const method = this.#methods.get(name);
+		if (method) return method;
+		return this.#resolveToolFallback(name);
 	}
 
 	has(name) {
-		return this.#methods.has(name);
+		return this.#methods.has(name) || !!this.#resolveToolFallback(name);
+	}
+
+	#resolveToolFallback(name) {
+		if (!this.#toolFallback) return undefined;
+		const { hooks, buildRunContext, dispatchTool } = this.#toolFallback;
+		if (!hooks.tools.has(name)) return undefined;
+		return Object.freeze({
+			handler: async (params, ctx) => {
+				if (!params.path) throw new Error("path is required");
+				if (!params.run) throw new Error("run is required");
+				const { rummy } = await buildRunContext(hooks, ctx, params.run);
+				await dispatchTool(hooks, rummy, name, params.path, params.body || "", {
+					path: params.path,
+					to: params.to,
+					...params.attributes,
+				});
+				return { status: "ok" };
+			},
+			description: `Dispatch ${name} tool.`,
+			params: {
+				run: "string — run alias",
+				path: "string — entry path",
+				body: "string? — entry content",
+				to: "string? — destination path",
+				attributes: "object? — JSON attributes",
+			},
+			requiresInit: true,
+			longRunning: false,
+		});
 	}
 
 	discover() {
@@ -43,6 +82,15 @@ export default class RpcRegistry {
 		for (const [name, def] of this.#methods) {
 			methods[name] = { description: def.description, params: def.params };
 		}
+		// Include auto-dispatched tools not explicitly registered
+		if (this.#toolFallback) {
+			for (const name of this.#toolFallback.hooks.tools.names) {
+				if (methods[name]) continue;
+				const def = this.#resolveToolFallback(name);
+				if (def)
+					methods[name] = { description: def.description, params: def.params };
+			}
+		}
 		const notifications = {};
 		for (const [name, def] of this.#notifications) {
 			notifications[name] = { description: def.description };

package/src/sql/v_model_context.sql

@@ -14,9 +14,10 @@ visible AS (
 		, ke.updated_at
 		, ke.attributes
 		, ke.tokens AS tokens_full
+		, COALESCE(s.category, 'logging') AS category
 		, CASE
-			-- Stored entries not in context
-			WHEN ke.fidelity = 'stored' THEN NULL
+			-- Archived entries not in context
+			WHEN ke.fidelity = 'archive' THEN NULL
 			-- 202 Accepted (proposed) hidden until resolved
 			WHEN ke.status = 202 THEN NULL
 			-- Audit schemes (model_visible = 0) hidden
@@ -38,24 +39,12 @@ projected AS (
 		, turn
 		, updated_at
 		, attributes
+		-- Category comes from schemes table — plugins declare it via registerScheme().
+		, category
 		, CASE
 			WHEN visible_fidelity IN ('full', 'summary') THEN body
 			ELSE ''
 		END AS body
-		, CASE
-			WHEN scheme IS NULL AND visible_fidelity IN ('full', 'summary') THEN 'file'
-			WHEN scheme IS NULL THEN 'file_index'
-			WHEN scheme IN ('http', 'https') AND visible_fidelity IN ('full', 'summary') THEN 'file'
-			WHEN scheme IN ('http', 'https') THEN 'file_index'
-			WHEN scheme IN ('known', 'skill') AND visible_fidelity = 'full' THEN 'known'
-			WHEN scheme IN ('known', 'skill') THEN 'known_index'
-			WHEN scheme = 'unknown' THEN 'unknown'
-			WHEN scheme IN ('ask', 'act', 'progress') THEN 'prompt'
-			WHEN scheme = 'summarize' THEN 'structural'
-			WHEN scheme = 'update' THEN 'structural'
-			WHEN scheme = 'tool' THEN 'tool'
-			ELSE 'result'
-		END AS category
 	FROM visible
 	WHERE visible_fidelity IS NOT NULL
 )
@@ -74,15 +63,11 @@ SELECT
 		ORDER BY
 			CASE category
 				WHEN 'tool' THEN 1
-				WHEN 'known' THEN 2
-				WHEN 'known_index' THEN 2
-				WHEN 'file_index' THEN 2
-				WHEN 'file' THEN 2
-				WHEN 'result' THEN 3
-				WHEN 'structural' THEN 4
-				WHEN 'unknown' THEN 5
-				WHEN 'prompt' THEN 6
-				ELSE 6
+				WHEN 'data' THEN 2
+				WHEN 'logging' THEN 3
+				WHEN 'unknown' THEN 4
+				WHEN 'prompt' THEN 5
+				ELSE 5
 			END
 			, CASE scheme WHEN 'skill' THEN 0 ELSE 1 END
 			, CASE fidelity

package/src/plugins/ask_user/docs.md

@@ -1,2 +0,0 @@
-## <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/docs.md

@@ -1,2 +0,0 @@
-## <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

@@ -1,14 +0,0 @@
-# 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

@@ -1,47 +0,0 @@
-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, this.#core)),
-		);
-		return `${content}<current>\n${lines.join("\n")}\n</current>\n`;
-	}
-}
-
-async function renderToolTag(entry, 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.status ? ` status="${entry.status}"` : "";
-
-	let body;
-	try {
-		body = await core.hooks.tools.view(entry.scheme, {
-			...entry,
-			attributes: attrs,
-		});
-	} catch {
-		body = entry.body;
-	}
-
-	if (body) {
-		return `<tool path="${path}"${status}>${body}</tool>`;
-	}
-	return `<tool path="${path}"${status}/>`;
-}

package/src/plugins/env/docs.md

@@ -1,4 +0,0 @@
-## <env>[command]</env> - Run an exploratory shell command
-Example: <env>npm --version</env>
-* Do not use <env/> to read or list files — use <get path="*" preview/> instead
-* For commands with side effects, use <sh/> instead

package/src/plugins/get/docs.md

@@ -1,10 +0,0 @@
-## <get>[path/to/file]</get> - Load a file or entry into context
-Example: <get>docs/example.txt</get>
-Example: <get>known://auth_flow</get>
-Example: <get path="src/**/*.js" preview/> (list matching files without loading)
-Example: <get path="src/*.js" body="TODO" preview/> (find files containing TODO)
-* Paths accept globs: `src/**/*.js`, `known://api_*`
-* Adding `preview` shows matches without loading into context
-* Use `body` attribute to filter by content
-* Use "known://" paths to recall stored information
-* When irrelevant or resolved, use <store/> to remove from context

package/src/plugins/known/docs.md

@@ -1,3 +0,0 @@
-## <known>[information]</known> - Save knowledge
-Example: <known>Donald Rumsfeld was born in 1932</known>
-Example: <known path="known://auth">OAuth2 PKCE</known>

package/src/plugins/mv/docs.md

@@ -1,2 +0,0 @@
-## <mv path="[path/to/origin"]>[path/to/destination]</mv> - Move a file or entry
-Example: <mv path="known://active_user">known://inactive_user</mv>

package/src/plugins/rm/docs.md

@@ -1,6 +0,0 @@
-## <rm path="[path/to/file]"/> - Remove a file or entry
-Example: <rm path="src/config.js"/>
-Example: <rm path="known://donald-rumsfeld-was-born-in-1932"/>
-Example: <rm path="known://temp_*" preview/> (preview before deleting)
-* <rm/> removes the file or entry from context and deletes it PERMANENTLY
-* Paths accept globs — use `preview` to check matches before deleting

package/src/plugins/set/docs.md

@@ -1,6 +0,0 @@
-## <set path="[path/to/file]">[edit]</set> - Edit a file or entry
-Example: <set path="src/config.js">s/base_url = http:\/\/localhost/base_url = http:\/\/0.0.0.0/g s/port = 3000/port = 8080/g</set>
-* All editing syntaxes supported: s/old/new/, {"search":"old","replace":"new"}, literal SEARCH/REPLACE blocks
-* Chain multiple replacements: `s/old/new/ s/foo/bar/`
-* Regex patterns use /slashes/: `s/console\.log.*/\/\/ removed/g`
-* Do not use <sh/> or <env/> to read, create, update, or delete files or entries

package/src/plugins/sh/docs.md

@@ -1,2 +0,0 @@
-## <sh>[command]</sh> - Run a shell command with side effects
-Example: <sh>npm install</sh>

package/src/plugins/skills/README.md

@@ -1,25 +0,0 @@
-# skills
-
-Manages skills and personas via RPC methods. Skills are stackable per-run entries; personas are exclusive per-run configuration.
-
-## Registration
-
-- **No tool handler** — registers RPC methods on `hooks.rpc.registry`.
-
-## RPC Methods
-
-### Skills
-- `skill/add` — Load a skill from `config/skills/{name}.md` into the run as a `skill://` entry at full state.
-- `skill/remove` — Remove a skill entry from a run.
-- `getSkills` — List active skills on a run.
-- `listSkills` — List available skill files from disk.
-
-### Personas
-- `persona/set` — Set persona on a run. Load from `config/personas/{name}.md` by name, pass raw text, or clear by omitting both.
-- `listPersonas` — List available persona files from disk.
-
-## Behavior
-
-- Skills stack: multiple skills can be active on a run simultaneously as separate `skill://` entries.
-- Personas are exclusive: setting a persona replaces the previous one (stored as a run column, not an entry).
-- File paths resolve from `RUMMY_HOME` environment variable.

package/src/plugins/store/README.md

@@ -1,20 +0,0 @@
-# store
-
-Demotes entries from active context to stored (background) state.
-
-## Registration
-
-- **Tool**: `store`
-- **Modes**: ask, act
-- **Category**: ask
-- **Handler**: Matches entries by pattern, demotes them via `demoteByPattern`, and records the result.
-
-## Projection
-
-Shows `store {path}`.
-
-## Behavior
-
-- Pattern queries (globs or body filters) produce a summary of matched paths.
-- Exact path queries report "{path} stored" or "{path} not found".
-- Stored entries remain in the database but are excluded from model context.

package/src/plugins/store/docs.md

@@ -1,6 +0,0 @@
-## <store path="[path/to/file]"/> - Store a file or entry
-Example: <store path="src/config.js"/>
-Example: <store path="src/**/*.test.js"/> (store all test files at once)
-* <store/> removes the file or entry from context, but does not delete it
-* A stored file or entry can be restored with <get/>
-* Paths accept globs for bulk operations

package/src/plugins/store/store.js

@@ -1,63 +0,0 @@
-import { readFileSync } from "node:fs";
-import { storePatternResult } from "../helpers.js";
-
-export default class Store {
-	#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, loopId } = rummy;
-		const target = entry.attributes.path;
-		if (!target) {
-			await store.upsert(runId, turn, entry.resultPath, "", 400, {
-				attributes: { error: "path is required" },
-				loopId,
-			});
-			return;
-		}
-		const bodyFilter = entry.attributes.body || null;
-		const isPattern = bodyFilter || target.includes("*");
-		const matches = await store.getEntriesByPattern(runId, target, bodyFilter);
-		await store.demoteByPattern(runId, target, bodyFilter);
-
-		if (isPattern) {
-			await storePatternResult(
-				store,
-				runId,
-				turn,
-				"store",
-				target,
-				bodyFilter,
-				matches,
-				{ loopId },
-			);
-		} else {
-			const paths = matches.map((m) => m.path).join(", ");
-			const body =
-				matches.length > 0 ? `${paths} stored` : `${target} not found`;
-			await store.upsert(runId, turn, entry.resultPath, body, 200, {
-				fidelity: "stored",
-				loopId,
-			});
-		}
-	}
-
-	full(entry) {
-		return `# store ${entry.attributes.path || entry.path}`;
-	}
-
-	summary(entry) {
-		return this.full(entry);
-	}
-}

package/src/plugins/summarize/docs.md

@@ -1,4 +0,0 @@
-## <summarize>[Answer or summary]</summarize>
-* Describe the final state
-* ONLY use if done
-* Keep brief (<= 80 characters)

package/src/plugins/unknown/docs.md

@@ -1,5 +0,0 @@
-## <unknown>[what you need to learn]</unknown> - Track open questions
-Example: <unknown>contents of answer.txt</unknown>
-Example: <unknown>which database adapter is configured</unknown>
-* Use get, env, or ask_user to investigate unknowns
-* When irrelevant or resolved, use <rm/> to remove from context.

package/src/plugins/update/docs.md

@@ -1,4 +0,0 @@
-## <update>[Brief update]</update>
-* Describe the current state
-* DO NOT use if done
-* Keep brief (<= 80 characters)