@possumtech/rummy 0.2.8 → 0.3.1

package/src/plugins/sh/README.md

@@ -5,9 +5,8 @@ Proposes shell command execution for client approval.
 ## Registration
 
 - **Tool**: `sh`
-- **Modes**: act only
-- **Category**: act
-- **Handler**: Upserts the entry as `proposed` state. The client must approve execution.
+- **Category**: `logging`
+- **Handler**: Upserts the entry at status 202 (proposed). The client must approve execution.
 
 ## Projection
 
@@ -15,4 +14,5 @@ Shows `sh {command}` followed by the entry body.
 
 ## Behavior
 
-All shell commands require client-side approval — nothing executes server-side. Act mode only; blocked in ask mode.
+All shell commands require client-side approval — nothing executes
+server-side. Act mode only; excluded in ask mode by `resolveForLoop`.

package/src/plugins/sh/sh.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import docs from "./shDoc.js";
 
 export default class Sh {
 	#core;
@@ -9,10 +9,10 @@ export default class Sh {
 		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,
-		);
+		core.filter("instructions.toolDocs", async (docsMap) => {
+			docsMap.sh = docs;
+			return docsMap;
+		});
 	}
 
 	async handler(entry, rummy) {

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,15 +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",
-			category: "knowledge",
+			category: "data",
 		});
+		core.hooks.tools.onView("skill", (entry) => entry.body);
+
 		const r = core.hooks.rpc.registry;
 
 		r.register("skill/add", {
@@ -22,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,
-					200,
-					{
-						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 };
 			},
@@ -97,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({ 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

@@ -1,4 +1,4 @@
-import { writeFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 export default class Telemetry {
@@ -75,8 +75,8 @@ export default class Telemetry {
 		result,
 		responseMessage,
 		content,
-		commands,
 		unparsed,
+		assembledTokens,
 		systemMsg,
 		userMsg,
 	}) {
@@ -85,17 +85,20 @@ export default class Telemetry {
 		// assistant://N — the model's raw response
 		await store.upsert(runId, turn, `assistant://${turn}`, content, 200, {
 			loopId,
+			fidelity: "archive",
 		});
 
 		// system://N, user://N — assembled messages as audit
 		if (systemMsg) {
 			await store.upsert(runId, turn, `system://${turn}`, systemMsg, 200, {
 				loopId,
+				fidelity: "archive",
 			});
 		}
 		if (userMsg) {
 			await store.upsert(runId, turn, `user://${turn}`, userMsg, 200, {
 				loopId,
+				fidelity: "archive",
 			});
 		}
 
@@ -112,7 +115,7 @@ export default class Telemetry {
 				model: result.model || null,
 			}),
 			200,
-			{ loopId },
+			{ loopId, fidelity: "archive" },
 		);
 
 		// reasoning://N
@@ -123,7 +126,7 @@ export default class Telemetry {
 				`reasoning://${turn}`,
 				responseMessage.reasoning_content,
 				200,
-				{ loopId },
+				{ loopId, fidelity: "archive" },
 			);
 		}
 
@@ -131,6 +134,7 @@ export default class Telemetry {
 		if (unparsed) {
 			await store.upsert(runId, turn, `content://${turn}`, unparsed, 200, {
 				loopId,
+				fidelity: "archive",
 			});
 		}
 
@@ -147,8 +151,13 @@ export default class Telemetry {
 			usage.completion_tokens_details?.reasoning_tokens ||
 			usage.output_tokens_details?.reasoning_tokens ||
 			0;
+		// Use LLM's actual prompt_tokens as the ground-truth context size when available.
+		// This back-fills context_tokens so get_last_context_tokens reflects reality for the next turn.
+		const actualContextTokens = usage.prompt_tokens || assembledTokens || 0;
 		await rummy.db.update_turn_stats.run({
 			id: rummy.turnId,
+			context_tokens: actualContextTokens,
+			reasoning_content: responseMessage?.reasoning_content || null,
 			prompt_tokens: usage.prompt_tokens ?? 0,
 			cached_tokens: cachedTokens ?? 0,
 			completion_tokens: usage.completion_tokens ?? 0,
@@ -187,10 +196,8 @@ export default class Telemetry {
 
 	#flush() {
 		if (!this.#lastRunPath || this.#turnLog.length === 0) return;
-		try {
-			writeFileSync(this.#lastRunPath, `${this.#turnLog.join("\n")}\n`);
-		} catch {
-			// RUMMY_HOME may not exist yet
-		}
+		writeFile(this.#lastRunPath, `${this.#turnLog.join("\n")}\n`).catch(
+			() => {},
+		);
 	}
 }

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,7 @@ 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. Each unknown renders with turn, fidelity, and tokens for
+temporal reasoning and context management.

package/src/plugins/unknown/unknown.js

@@ -1,19 +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({
-			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) {
@@ -24,9 +25,11 @@ 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 path="${u.path}">${u.body}</unknown>`,
-		);
+		const lines = entries.map((u) => {
+			const fidelity = u.fidelity ? ` fidelity="${u.fidelity}"` : "";
+			const tokens = u.tokens ? ` tokens="${u.tokens}"` : "";
+			return `<unknown path="${u.path}" turn="${u.source_turn || u.turn}"${fidelity}${tokens}>${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({ 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");