@possumtech/rummy 0.2.8 → 0.3.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,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) {
@@ -25,7 +26,8 @@ export default class Unknown {
 		if (entries.length === 0) return content;
 
 		const lines = entries.map(
-			(u) => `<unknown path="${u.path}">${u.body}</unknown>`,
+			(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({ 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/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

@@ -15,8 +15,8 @@ visible AS (
 		, ke.attributes
 		, ke.tokens AS tokens_full
 		, 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
@@ -42,19 +42,18 @@ projected AS (
 			WHEN visible_fidelity IN ('full', 'summary') THEN body
 			ELSE ''
 		END AS body
+		-- Four roles: data, logging, unknown, prompt.
+		-- These are structural — see PluginContext.CATEGORIES.
+		-- 'tool' is internal (model_visible=0 in practice).
+		-- Default is 'logging' — plugins opt into 'data' explicitly.
 		, 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 IS NULL THEN 'data'
+			WHEN scheme IN ('http', 'https') THEN 'data'
+			WHEN scheme IN ('known', 'skill') THEN 'data'
 			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 = 'prompt' THEN 'prompt'
 			WHEN scheme = 'tool' THEN 'tool'
-			ELSE 'result'
+			ELSE 'logging'
 		END AS category
 	FROM visible
 	WHERE visible_fidelity IS NOT NULL
@@ -74,15 +73,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/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)