@possumtech/rummy 0.2.7 → 0.3.0

package/src/plugins/sh/shDoc.js

@@ -0,0 +1,29 @@
+// Tool doc for <sh>. Each entry: [text, rationale].
+// Text goes to the model. Rationale stays in source.
+// Changing ANY line requires reading ALL rationales first.
+const LINES = [
+	// --- Syntax
+	["## <sh>[command]</sh> - Run a shell command with side effects"],
+
+	// --- Examples: install and test — real mutations
+	[
+		"Example: <sh>npm install express</sh>",
+		"Package install. Shows a real side-effect command.",
+	],
+	[
+		"Example: <sh>npm test</sh>",
+		"Test execution. Another common side-effect action.",
+	],
+
+	// --- Constraints
+	[
+		"* YOU MUST NOT use <sh/> to read, create, or edit files — use <get/> and <set/>",
+		"Forces file operations through the entry system. Prevents untracked mutations.",
+	],
+	[
+		"* YOU MUST use <env/> for commands without side effects",
+		"Reinforces the env/sh split. Read = env, mutate = sh.",
+	],
+];
+
+export default LINES.map(([text]) => text).join("\n");

package/src/plugins/{skills/skills.js → skill/skill.js}

@@ -1,16 +1,17 @@
 import fs from "node:fs/promises";
 import { join } from "node:path";
 
-export default class Skills {
+export default class Skill {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
 		core.registerScheme({
 			name: "skill",
-			validStates: ["full", "stored"],
-			category: "knowledge",
+			category: "data",
 		});
+		core.hooks.tools.onView("skill", (entry) => entry.body);
+
 		const r = core.hooks.rpc.registry;
 
 		r.register("skill/add", {
@@ -23,19 +24,12 @@ export default class Skills {
 
 				const body = await loadFile("skills", params.name);
 				const store = ctx.projectAgent.entries;
-				await store.upsert(
-					runRow.id,
-					runRow.next_turn,
-					`skill://${params.name}`,
-					body,
-					"full",
-					{
-						attributes: {
-							name: params.name,
-							source: filePath("skills", params.name),
-						},
+				await store.upsert(runRow.id, 0, `skill://${params.name}`, body, 200, {
+					attributes: {
+						name: params.name,
+						source: filePath("skills", params.name),
 					},
-				);
+				});
 
 				return { status: "ok", skill: params.name };
 			},
@@ -84,10 +78,10 @@ export default class Skills {
 				);
 				return entries.map((e) => ({
 					name: e.path.replace("skill://", ""),
-					state: e.state,
+					status: e.status,
 				}));
 			},
-			description: "List skills active on a run. Returns [{ name, state }].",
+			description: "List skills active on a run. Returns [{ name, status }].",
 			params: { run: "string — run alias" },
 			requiresInit: true,
 		});
@@ -98,43 +92,7 @@ export default class Skills {
 			requiresInit: true,
 		});
 
-		r.register("persona/set", {
-			handler: async (params, ctx) => {
-				if (!params.run) throw new Error("run is required");
-
-				const runRow = await ctx.db.get_run_by_alias.get({ alias: params.run });
-				if (!runRow) throw new Error(`Run not found: ${params.run}`);
-
-				let text = params.text;
-				if (params.name && !text) {
-					text = await loadFile("personas", params.name);
-				}
-
-				await ctx.db.update_run_config.run({
-					id: runRow.id,
-					temperature: null,
-					persona: text || null,
-					context_limit: null,
-					model: null,
-				});
-
-				return { status: "ok" };
-			},
-			description:
-				"Set persona on a run. Pass name or text. Pass neither to clear.",
-			params: {
-				run: "string — run alias",
-				name: "string? — persona filename (without .md)",
-				text: "string? — raw persona text (overrides name)",
-			},
-			requiresInit: true,
-		});
-
-		r.register("listPersonas", {
-			handler: async () => listAvailable("personas"),
-			description: "List available persona files. Returns [{ name, path }].",
-			requiresInit: true,
-		});
+		// Persona methods extracted to persona plugin.
 	}
 }
 

package/src/plugins/summarize/README.md

@@ -1,13 +1,12 @@
 # summarize
 
-Structural tool for model-generated summaries.
+Lifecycle signal — the model declares it has completed the task.
 
 ## Registration
 
 - **Tool**: `summarize`
-- **Modes**: ask, act
-- **Category**: structural
-- **Handler**: None — projection only.
+- **Category**: `logging`
+- **Handler**: None — recorded by TurnExecutor as a lifecycle signal.
 
 ## Projection
 
@@ -15,4 +14,6 @@ Shows `summarize` followed by the entry body.
 
 ## Behavior
 
-No handler logic. The tool registration exists so the model can emit summary entries that appear in context via projection.
+If the model sends `<summarize>` but actions in the same turn failed,
+TurnExecutor overrides it to `<update>` — the model's assertion that
+it's done is false.

package/src/plugins/summarize/summarize.js

@@ -1,17 +1,18 @@
-import { readFileSync } from "node:fs";
+import docs from "./summarizeDoc.js";
 
 export default class Summarize {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
-		core.registerScheme({ validStates: ["summary"], category: "structural" });
+		core.ensureTool();
+		core.registerScheme({ category: "logging" });
 		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.summarize = docs;
+			return docsMap;
+		});
 	}
 
 	full(entry) {

package/src/plugins/summarize/summarizeDoc.js

@@ -0,0 +1,33 @@
+// Tool doc for <summarize>. Each entry: [text, rationale].
+// Text goes to the model. Rationale stays in source.
+// Changing ANY line requires reading ALL rationales first.
+const LINES = [
+	// --- Syntax
+	["## <summarize>[answer or summary]</summarize> - Signal completion"],
+
+	// --- Examples: answer and task completion
+	[
+		"Example: <summarize>The port is 8080</summarize>",
+		"Direct answer. Shows summarize as the vehicle for delivering answers.",
+	],
+	[
+		"Example: <summarize>Installed express, updated config</summarize>",
+		"Task summary. Shows summarize for action completion.",
+	],
+
+	// --- Constraints: RFC-style MUST/MUST NOT
+	[
+		"* YOU MUST use <summarize> when done — describes the final state",
+		"Completion signal. Without this, the loop continues indefinitely.",
+	],
+	[
+		"* YOU MUST NOT use <summarize> if still working — use <update/> instead",
+		"Mutual exclusion with update. Prevents premature completion.",
+	],
+	[
+		"* YOU MUST keep <summarize> to <= 80 characters",
+		"Length cap. Matches the summary attribute constraint. Prevents verbose output.",
+	],
+];
+
+export default LINES.map(([text]) => text).join("\n");

package/src/plugins/telemetry/telemetry.js

@@ -75,22 +75,28 @@ export default class Telemetry {
 		result,
 		responseMessage,
 		content,
-		commands,
 		unparsed,
+		assembledTokens,
 		systemMsg,
 		userMsg,
 	}) {
-		const { entries: store, runId } = rummy;
+		const { entries: store, runId, loopId } = rummy;
 
 		// assistant://N — the model's raw response
-		await store.upsert(runId, turn, `assistant://${turn}`, content, "info");
+		await store.upsert(runId, turn, `assistant://${turn}`, content, 200, {
+			loopId,
+		});
 
 		// system://N, user://N — assembled messages as audit
 		if (systemMsg) {
-			await store.upsert(runId, turn, `system://${turn}`, systemMsg, "info");
+			await store.upsert(runId, turn, `system://${turn}`, systemMsg, 200, {
+				loopId,
+			});
 		}
 		if (userMsg) {
-			await store.upsert(runId, turn, `user://${turn}`, userMsg, "info");
+			await store.upsert(runId, turn, `user://${turn}`, userMsg, 200, {
+				loopId,
+			});
 		}
 
 		// model://N — raw API response diagnostics
@@ -105,7 +111,8 @@ export default class Telemetry {
 				usage: result.usage || null,
 				model: result.model || null,
 			}),
-			"info",
+			200,
+			{ loopId },
 		);
 
 		// reasoning://N
@@ -115,13 +122,16 @@ export default class Telemetry {
 				turn,
 				`reasoning://${turn}`,
 				responseMessage.reasoning_content,
-				"info",
+				200,
+				{ loopId },
 			);
 		}
 
 		// content://N — unparsed text
 		if (unparsed) {
-			await store.upsert(runId, turn, `content://${turn}`, unparsed, "info");
+			await store.upsert(runId, turn, `content://${turn}`, unparsed, 200, {
+				loopId,
+			});
 		}
 
 		// Commit usage stats
@@ -139,6 +149,8 @@ export default class Telemetry {
 			0;
 		await rummy.db.update_turn_stats.run({
 			id: rummy.turnId,
+			context_tokens: assembledTokens ?? 0,
+			reasoning_content: responseMessage?.reasoning_content || null,
 			prompt_tokens: usage.prompt_tokens ?? 0,
 			cached_tokens: cachedTokens ?? 0,
 			completion_tokens: usage.completion_tokens ?? 0,

package/src/plugins/think/README.md

@@ -0,0 +1,20 @@
+# think
+
+Provides a `<think>` tag for model reasoning. Not a tool — does not
+appear in the tool list.
+
+## Registration
+
+- **Scheme**: `think` — `category: "logging"`, `model_visible: 0`
+- **No handler, no view, no tool registration**
+
+## Behavior
+
+The model writes `<think>reasoning</think>` before tool commands.
+XmlParser captures it, TurnExecutor records it as a `think://` entry.
+Invisible to the model on subsequent turns (`model_visible: 0`).
+Available for debugging and audit.
+
+Models with server-side reasoning (extended thinking) use that
+capability independently. The `<think>` tag is a floor — every model
+gets at least this.

package/src/plugins/think/think.js

@@ -0,0 +1,5 @@
+export default class Think {
+	constructor(core) {
+		core.registerScheme({ modelVisible: 0, category: "logging" });
+	}
+}

package/src/plugins/unknown/README.md

@@ -7,9 +7,9 @@ The Rumsfeld mechanism. The model registers what it doesn't know before acting.
 ## Registration
 
 - **Tool**: `unknown`
-- **Modes**: ask, act
-- **Category**: structural
+- **Category**: `unknown`
 - **Handler**: None — recorded by TurnExecutor, deduplicated against existing unknowns.
+- **Filter**: `assembly.system` at priority 300 — renders `<unknowns>` section.
 
 ## Projection
 
@@ -18,6 +18,6 @@ The Rumsfeld mechanism. The model registers what it doesn't know before acting.
 ## Behavior
 
 Unknowns are sticky — they persist across turns until the model explicitly
-stores or removes them. The model investigates unknowns using `<get>`,
-`<env>`, or `<ask_user>`, then removes resolved ones with `<rm>`.
-Server deduplicates on insert.
+removes them with `<rm>`. The model investigates unknowns using `<get>`,
+`<env>`, or `<ask_user>`, then removes resolved ones. Server deduplicates
+on insert. Turn numbers shown on each unknown for temporal reasoning.

package/src/plugins/unknown/unknown.js

@@ -1,20 +1,20 @@
-import { readFileSync } from "node:fs";
+import docs from "./unknownDoc.js";
 
 export default class Unknown {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
+		core.ensureTool();
 		core.registerScheme({
-			validStates: ["full", "stored"],
-			category: "knowledge",
+			category: "unknown",
 		});
 		core.on("full", this.full.bind(this));
 		core.filter("assembly.system", this.assembleUnknowns.bind(this), 300);
-		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.unknown = docs;
+			return docsMap;
+		});
 	}
 
 	full(entry) {
@@ -25,7 +25,10 @@ export default class Unknown {
 		const entries = ctx.rows.filter((r) => r.category === "unknown");
 		if (entries.length === 0) return content;
 
-		const lines = entries.map((u) => `<unknown>${u.body}</unknown>`);
+		const lines = entries.map(
+			(u) =>
+				`<unknown path="${u.path}" turn="${u.source_turn || u.turn}">${u.body}</unknown>`,
+		);
 		return `${content}\n\n<unknowns>\n${lines.join("\n")}\n</unknowns>`;
 	}
 }

package/src/plugins/unknown/unknownDoc.js

@@ -0,0 +1,31 @@
+// Tool doc for <unknown>. Each entry: [text, rationale].
+// Text goes to the model. Rationale stays in source.
+// Changing ANY line requires reading ALL rationales first.
+const LINES = [
+	// --- Syntax: body = what you need to learn
+	[
+		`## <unknown>[specific thing I need to learn]</unknown> - Track open questions`,
+	],
+
+	// --- Examples: concrete unknowns, not abstract
+	[
+		`Example: <unknown path="unknown://answer">contents of answer.txt</unknown>`,
+		`Specific and actionable. Shows that unknowns are concrete investigation targets.`,
+	],
+	[
+		`Example: <unknown>which database adapter is configured</unknown>`,
+		`Domain question. Shows unknowns for configuration/architecture questions.`,
+	],
+
+	// --- Lifecycle: register → investigate → resolve
+	[
+		`* Investigate with Tool Commands`,
+		`Cross-tool lifecycle: unknowns drive get/env/ask_user actions.`,
+	],
+	[
+		`* When resolved or irrelevant, remove with <rm path="unknown://..."/>`,
+		`Cross-tool lifecycle: rm cleans resolved unknowns from context.`,
+	],
+];
+
+export default LINES.map(([text]) => text).join("\n");

package/src/plugins/update/README.md

@@ -1,18 +1,13 @@
 # update
 
-Structural tool for model-generated progress updates.
+Lifecycle signal — the model declares it has more work to do.
 
 ## Registration
 
 - **Tool**: `update`
-- **Modes**: ask, act
-- **Category**: structural
-- **Handler**: None — projection only.
+- **Category**: `logging`
+- **Handler**: None — recorded by TurnExecutor as a lifecycle signal.
 
 ## Projection
 
 Shows `update` followed by the entry body.
-
-## Behavior
-
-No handler logic. Allows the model to emit progress/status entries that appear in context via projection.

package/src/plugins/update/update.js

@@ -1,17 +1,18 @@
-import { readFileSync } from "node:fs";
+import docs from "./updateDoc.js";
 
 export default class Update {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
-		core.registerScheme({ validStates: ["info"], category: "structural" });
+		core.ensureTool();
+		core.registerScheme({ category: "logging" });
 		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.update = docs;
+			return docsMap;
+		});
 	}
 
 	full(entry) {

package/src/plugins/update/updateDoc.js

@@ -0,0 +1,33 @@
+// Tool doc for <update>. Each entry: [text, rationale].
+// Text goes to the model. Rationale stays in source.
+// Changing ANY line requires reading ALL rationales first.
+const LINES = [
+	// --- Syntax
+	["## <update>[brief status]</update> - Signal continuation"],
+
+	// --- Examples: research progress and multi-step work
+	[
+		"Example: <update>Reading config files</update>",
+		"Progress checkpoint. Shows update as a status signal, not a log entry.",
+	],
+	[
+		"Example: <update>Found 3 issues, fixing first</update>",
+		"Multi-step progress. Shows update for ongoing work.",
+	],
+
+	// --- Constraints: RFC-style MUST/MUST NOT
+	[
+		"* YOU MUST use <update> if still working — describes the current state",
+		"Continuation signal. Triggers the next turn in the loop.",
+	],
+	[
+		"* YOU MUST NOT use <update> if done — use <summarize/> instead",
+		"Mutual exclusion with summarize. Prevents infinite loops.",
+	],
+	[
+		"* YOU MUST keep <update> to <= 80 characters",
+		"Length cap. Prevents models from writing essays in status updates.",
+	],
+];
+
+export default LINES.map(([text]) => text).join("\n");

package/src/server/ClientConnection.js

@@ -110,7 +110,7 @@ export default class ClientConnection {
 
 			try {
 				const logRow = await this.#db.log_rpc_call.get({
-					project_id: this.#context.projectId || null,
+					project_id: this.#context.projectId ?? null,
 					method,
 					rpc_id: id,
 					params: params ? JSON.stringify(params) : null,
@@ -184,10 +184,8 @@ export default class ClientConnection {
 				} catch {}
 			}
 		} catch (error) {
-			if (debug) {
-				console.error(`[SOCKET] ERR: ${error.message}`);
-				console.error(`[DEBUG] Stack: ${error.stack}`);
-			}
+			console.error(`[RUMMY] RPC Error: ${error.message}`);
+			console.error(`[RUMMY] Stack: ${error.stack}`);
 			this.#send({
 				jsonrpc: "2.0",
 				error: { code: -32603, message: error.message },

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 };