@possumtech/rummy 0.2.8 → 0.3.0

package/src/plugins/rpc/rpc.js

@@ -1,4 +1,3 @@
-import KnownStore from "../../agent/KnownStore.js";
 import msg from "../../agent/messages.js";
 import RummyContext from "../../hooks/RummyContext.js";
 import File from "../file/file.js";
@@ -90,15 +89,15 @@ export default class Rpc {
 
 		// --- Entry operations (same dispatch as model) ---
 
+		// Override: get has persist flag for file constraint management
 		r.register("get", {
 			handler: async (params, ctx) => {
 				if (!params.path) throw new Error("path is required");
 
 				if (params.persist) {
 					const visibility = params.readonly ? "readonly" : "active";
-					return File.activate(
+					await File.setConstraint(
 						ctx.db,
-						ctx.projectAgent.entries,
 						ctx.projectId,
 						params.path,
 						visibility,
@@ -115,101 +114,50 @@ export default class Rpc {
 			description: "Promote entry to full state.",
 			params: {
 				path: "string — file path or glob pattern",
-				run: "string? — run alias (required without persist)",
-				persist: "boolean? — create file constraint",
+				run: "string — run alias",
+				persist: "boolean? — also create file constraint",
 				readonly: "boolean? — with persist, set readonly instead of active",
 			},
 			requiresInit: true,
 		});
 
+		// store is not a tool — it manages file constraints
 		r.register("store", {
 			handler: async (params, ctx) => {
 				if (!params.path) throw new Error("path is required");
 
 				if (params.clear) {
-					return File.drop(ctx.db, ctx.projectId, params.path);
+					await File.dropConstraint(ctx.db, ctx.projectId, params.path);
+					return { status: "ok" };
 				}
 				if (params.persist) {
-					if (params.ignore) {
-						return File.ignore(
-							ctx.db,
-							ctx.projectAgent.entries,
-							ctx.projectId,
-							params.path,
-						);
-					}
-					return File.drop(ctx.db, ctx.projectId, params.path);
+					const visibility = params.ignore ? "ignore" : "active";
+					await File.setConstraint(
+						ctx.db,
+						ctx.projectId,
+						params.path,
+						visibility,
+					);
 				}
 
 				if (!params.run) throw new Error("run is required");
-				const { rummy } = await buildRunContext(hooks, ctx, params.run);
-				await dispatchTool(hooks, rummy, "store", params.path, "", {
-					path: params.path,
-				});
+				const runRow = await ctx.db.get_run_by_alias.get({ alias: params.run });
+				if (!runRow) throw new Error(`Run not found: ${params.run}`);
+				const store = ctx.projectAgent.entries;
+				await store.demoteByPattern(runRow.id, params.path, null);
 				return { status: "ok" };
 			},
 			description: "Demote entry to stored state.",
 			params: {
 				path: "string — file path or glob pattern",
 				run: "string? — run alias (required without persist)",
-				persist: "boolean? — create file constraint",
+				persist: "boolean? — also create file constraint",
 				ignore: "boolean? — with persist, exclude from scan",
 				clear: "boolean? — remove existing constraint",
 			},
 			requiresInit: true,
 		});
 
-		r.register("set", {
-			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);
-
-				const scheme = KnownStore.scheme(params.path);
-				if (scheme) {
-					await rummy.set({
-						path: params.path,
-						body: params.body,
-						status: params.status || 200,
-						attributes: params.attributes,
-					});
-				} else {
-					await dispatchTool(hooks, rummy, "set", params.path, params.body, {
-						path: params.path,
-						...params.attributes,
-					});
-				}
-				return { status: "ok" };
-			},
-			description: "Create or update an entry.",
-			params: {
-				run: "string — run alias",
-				path: "string — entry path",
-				body: "string? — entry content",
-				status: "number? — HTTP status code (default: 200)",
-				attributes: "object? — JSON attributes",
-			},
-			requiresInit: true,
-		});
-
-		r.register("rm", {
-			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, "rm", params.path, "", {
-					path: params.path,
-				});
-				return { status: "ok" };
-			},
-			description: "Remove an entry.",
-			params: {
-				run: "string — run alias",
-				path: "string — entry path",
-			},
-			requiresInit: true,
-		});
-
 		r.register("getEntries", {
 			handler: async (params, ctx) => {
 				let run;
@@ -283,7 +231,9 @@ export default class Rpc {
 						temperature: params.temperature ?? null,
 						persona: params.persona ?? null,
 						contextLimit: params.contextLimit,
-						noContext: params.noContext,
+						noRepo: params.noRepo,
+						noInteraction: params.noInteraction,
+						noWeb: params.noWeb,
 						fork: params.fork,
 					},
 				);
@@ -297,7 +247,9 @@ export default class Rpc {
 				temperature: "number?",
 				persona: "string?",
 				contextLimit: "number?",
-				noContext: "boolean?",
+				noRepo: "boolean?",
+				noInteraction: "boolean? — disable ask_user tool",
+				noWeb: "boolean? — disable search and URL fetch",
 				fork: "boolean?",
 			},
 			requiresInit: true,
@@ -315,7 +267,9 @@ export default class Rpc {
 						temperature: params.temperature ?? null,
 						persona: params.persona ?? null,
 						contextLimit: params.contextLimit,
-						noContext: params.noContext,
+						noRepo: params.noRepo,
+						noInteraction: params.noInteraction,
+						noWeb: params.noWeb,
 						fork: params.fork,
 					},
 				);
@@ -329,7 +283,9 @@ export default class Rpc {
 				temperature: "number?",
 				persona: "string?",
 				contextLimit: "number?",
-				noContext: "boolean?",
+				noRepo: "boolean?",
+				noInteraction: "boolean? — disable ask_user tool",
+				noWeb: "boolean? — disable search and URL fetch",
 				fork: "boolean?",
 			},
 			requiresInit: true,
@@ -524,6 +480,10 @@ export default class Rpc {
 		r.registerNotification("run/progress", "Turn status.");
 		r.registerNotification("ui/render", "Streaming output.");
 		r.registerNotification("ui/notify", "Toast notification.");
+
+		// Auto-dispatch: any registered tool is callable via RPC.
+		// Checked at request time — no timing dependency on plugin load order.
+		r.setToolFallback(hooks, buildRunContext, dispatchTool);
 	}
 }
 
@@ -544,7 +504,7 @@ async function buildRunContext(hooks, ctx, runAlias) {
 				sequence: runRow.next_turn,
 				runId: runRow.id,
 				turnId: null,
-				noContext: false,
+				noRepo: false,
 				contextSize: null,
 				systemPrompt: "",
 				loopPrompt: "",
@@ -555,7 +515,12 @@ async function buildRunContext(hooks, ctx, runAlias) {
 
 async function dispatchTool(hooks, rummy, scheme, path, body, attributes) {
 	const store = rummy.entries;
-	const resultPath = await store.dedup(rummy.runId, scheme, path);
+	const resultPath = await store.dedup(
+		rummy.runId,
+		scheme,
+		path,
+		rummy.sequence,
+	);
 
 	await store.upsert(rummy.runId, rummy.sequence, resultPath, body, 200, {
 		attributes: attributes,

package/src/plugins/set/README.md

@@ -1,32 +1,33 @@
 # set
 
-Writes or edits entry content. Handles new files, full overwrites, SEARCH/REPLACE edits, and pattern updates.
+Writes or edits entry content. Handles new files, full overwrites,
+SEARCH/REPLACE edits, and pattern updates.
 
 ## Files
 
 - **set.js** — Plugin registration and edit dispatch logic.
-- **HeuristicMatcher.js** — Fuzzy SEARCH/REPLACE matching. Handles whitespace/indentation differences and escaped characters when literal match fails.
+- **HeuristicMatcher.js** — Fuzzy SEARCH/REPLACE matching.
 - **HeuristicMatcher.test.js** — Tests for HeuristicMatcher.
 
 ## Registration
 
 - **Tool**: `set`
-- **Modes**: ask, act
-- **Category**: act
-- **Handler**: Routes to different paths based on attributes:
+- **Category**: `logging`
+- **Handler**: Routes based on attributes:
   - `blocks` or `search` — SEARCH/REPLACE edit via `processEdit`.
   - `preview` — pattern preview (dry run).
-  - K/V path — direct upsert at `full` state.
-  - File path — produces `proposed` entry with udiff patch.
+  - Scheme path — direct upsert at status 200.
+  - File path — produces status 202 (proposed) with unified diff patch.
   - Glob/filter — bulk update via `updateBodyByPattern`.
 
 ## Projection
 
-Shows `set {file}` with token delta (`before→after tokens`). Includes the merge conflict block when a SEARCH/REPLACE was performed.
+Shows `set {file}` with token delta (`before→after tokens`). Includes
+the merge conflict block when a SEARCH/REPLACE was performed.
 
 ## Behavior
 
-- **Literal match first**: SEARCH text is matched literally against the entry body.
-- **Heuristic fallback**: On literal failure, `HeuristicMatcher.matchAndPatch` attempts fuzzy matching with warnings.
-- **Patch generation**: `generatePatch` produces unified diff format for client display.
-- File writes are always `proposed`; K/V writes resolve immediately.
+- **Literal match first**: SEARCH text is matched literally.
+- **Heuristic fallback**: On literal failure, fuzzy matching with warnings.
+- **Patch generation**: `generatePatch` produces unified diff for client display.
+- File writes are always status 202 (proposed); scheme writes resolve immediately.

package/src/plugins/set/set.js

@@ -1,7 +1,9 @@
-import { readFileSync } from "node:fs";
 import KnownStore from "../../agent/KnownStore.js";
 import Hedberg, { generatePatch } from "../hedberg/hedberg.js";
 import { storePatternResult } from "../helpers.js";
+import docs from "./setDoc.js";
+
+const VALID_FIDELITY = { archive: 1, summary: 1, index: 1, full: 1 };
 
 // biome-ignore lint/suspicious/noShadowRestrictedNames: tool name is "set"
 export default class Set {
@@ -14,16 +16,69 @@ export default class Set {
 		core.on("full", this.full.bind(this));
 		core.on("summary", this.summary.bind(this));
 		core.on("turn.proposing", this.#materializeRevisions.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.set = docs;
+			return docsMap;
+		});
 	}
 
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 		const attrs = entry.attributes;
 
+		// Fidelity control: <set path="..." fidelity="archive"/>
+		const fidelityAttr = VALID_FIDELITY[attrs.fidelity] ? attrs.fidelity : null;
+		if (fidelityAttr && attrs.path) {
+			const target = attrs.path;
+			const rawSummary =
+				typeof attrs.summary === "string" ? attrs.summary : null;
+			const summaryText = rawSummary ? rawSummary.slice(0, 80) : null;
+			const matches = await store.getEntriesByPattern(
+				runId,
+				target,
+				attrs.body,
+			);
+			if (entry.body) {
+				// Write content directly at specified fidelity
+				const entryAttrs = summaryText ? { summary: summaryText } : null;
+				for (const match of matches) {
+					await store.upsert(runId, turn, match.path, entry.body, 200, {
+						fidelity: fidelityAttr,
+						attributes: entryAttrs,
+						loopId,
+					});
+				}
+				if (matches.length === 0) {
+					await store.upsert(runId, turn, target, entry.body, 200, {
+						fidelity: fidelityAttr,
+						attributes: entryAttrs,
+						loopId,
+					});
+				}
+			} else {
+				// No body — change fidelity, attach summary if provided
+				for (const match of matches) {
+					await store.setFidelity(runId, match.path, fidelityAttr);
+					if (summaryText) {
+						await store.setAttributes(runId, match.path, {
+							summary: summaryText,
+						});
+					}
+				}
+			}
+			const label =
+				fidelityAttr === "archive" ? "archived" : `set to ${fidelityAttr}`;
+			const body =
+				matches.length > 0
+					? `${matches.map((m) => m.path).join(", ")} ${label}`
+					: `${target} not found`;
+			await store.upsert(runId, turn, entry.resultPath, body, 200, {
+				fidelity: "archive",
+				loopId,
+			});
+			return;
+		}
+
 		if (attrs.blocks || attrs.search != null) {
 			await this.#processEdit(rummy, entry, attrs);
 			return;

package/src/plugins/set/setDoc.js

@@ -0,0 +1,45 @@
+// Tool doc for <set>. Each entry: [text, rationale].
+// Text goes to the model. Rationale stays in source.
+// Changing ANY line requires reading ALL rationales first.
+const LINES = [
+	// --- Syntax: path attr + body = edit content
+	['## <set path="[path/to/file]">[edit]</set> - Edit a file or entry'],
+
+	// --- Examples: sed, SEARCH/REPLACE, fidelity control
+	[
+		'Example: <set path="src/config.js">s/port = 3000/port = 8080/g</set>',
+		"Sed syntax: most common edit pattern. Shows s/old/new/ with g flag.",
+	],
+	[
+		`Example: <set path="src/app.js"><<<<<<< SEARCH
+// TODO: add error handling
+=======
+// error handler configured
+>>>>>>> REPLACE</set>`,
+		"SEARCH/REPLACE block: literal match and replace. Use when sed escaping is complex.",
+	],
+	[
+		'Example: <set path="known://plan" stored summary="Migration plan for Q2"/>',
+		"Fidelity + summary: archive an entry while preserving a description. Lifecycle endpoint.",
+	],
+
+	// --- Constraints
+	[
+		'* `fidelity="..."`: `archive`, `summary`, `index`, `full`',
+		"Fidelity control. Archive removes from context but preserves for retrieval.",
+	],
+	[
+		'* `summary="..."` (<= 80 chars) persists across fidelity changes',
+		"Model-authored descriptions survive demotion. No janitorial pass needed.",
+	],
+	[
+		"* YOU MUST NOT use <sh/> or <env/> to read, create, or edit files",
+		"Forces file operations through set/get. Prevents untracked mutations.",
+	],
+	[
+		"* Editing: s/old/new/ sed patterns and literal SEARCH/REPLACE blocks",
+		"Both syntaxes supported. Hedberg normalizes either form.",
+	],
+];
+
+export default LINES.map(([text]) => text).join("\n");

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

@@ -75,8 +75,8 @@ export default class Telemetry {
 		result,
 		responseMessage,
 		content,
-		commands,
 		unparsed,
+		assembledTokens,
 		systemMsg,
 		userMsg,
 	}) {
@@ -149,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,