@possumtech/rummy 0.2.8 → 0.3.0

package/src/plugins/file/file.js

@@ -1,34 +1,45 @@
 import { isAbsolute, relative } from "node:path";
 
+/**
+ * File plugin: projections and constraints for filesystem entries.
+ *
+ * Bare file paths (src/app.js) have scheme=NULL in the DB because
+ * schemeOf() only recognizes "://" patterns. The schemes table has
+ * a "file" entry so v_model_context can JOIN via COALESCE(scheme, 'file').
+ * This is the one exception to "every scheme has a plugin owner" —
+ * the file plugin owns the NULL scheme through the "file" registry entry.
+ */
 export default class File {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
-		core.registerScheme({ category: "file" });
-		core.registerScheme({ name: "http", category: "file" });
-		core.registerScheme({ name: "https", category: "file" });
+		// "file" scheme covers bare paths (scheme IS NULL in DB)
+		core.registerScheme({ category: "data" });
+		core.registerScheme({ name: "http", category: "data" });
+		core.registerScheme({ name: "https", category: "data" });
 		core.on("full", this.full.bind(this));
-
-		// Register identity projections for schemes that just pass through body
-		for (const scheme of ["known", "skill", "ask", "act", "progress"]) {
-			core.hooks.tools.onView(scheme, (entry) => entry.body);
-		}
+		core.on("summary", this.summary.bind(this));
+		// Default identity views for http/https — rummy.web overrides these
+		core.hooks.tools.onView("http", (entry) => entry.body);
+		core.hooks.tools.onView("https", (entry) => entry.body);
 	}
 
 	full(entry) {
 		return entry.body;
 	}
 
-	static async activate(
-		db,
-		knownStore,
-		projectId,
-		pattern,
-		visibility = "active",
-	) {
+	summary() {
+		return "";
+	}
+
+	/**
+	 * Set a project-level file constraint. Backbone operation —
+	 * constraints are project config, not tool dispatch.
+	 */
+	static async setConstraint(db, projectId, pattern, visibility = "active") {
 		const path = await normalizePath(db, projectId, pattern);
-		if (!path) return { status: "ok" };
+		if (!path) return null;
 
 		await db.upsert_file_constraint.run({
 			project_id: projectId,
@@ -36,34 +47,22 @@ export default class File {
 			visibility,
 		});
 
-		const runs = await db.get_all_runs.all({ project_id: projectId });
-		if (visibility === "active") {
-			for (const run of runs) {
-				await knownStore.promoteByPattern(run.id, path, null, 0);
-			}
-		} else if (visibility === "ignore") {
-			for (const run of runs) {
-				await knownStore.demoteByPattern(run.id, path, null);
-			}
-		}
-
-		return { status: "ok" };
-	}
-
-	static async ignore(db, knownStore, projectId, pattern) {
-		return File.activate(db, knownStore, projectId, pattern, "ignore");
+		return path;
 	}
 
-	static async drop(db, projectId, pattern) {
+	/**
+	 * Remove a project-level file constraint.
+	 */
+	static async dropConstraint(db, projectId, pattern) {
 		const path = await normalizePath(db, projectId, pattern);
-		if (!path) return { status: "ok" };
+		if (!path) return null;
 
 		await db.delete_file_constraint.run({
 			project_id: projectId,
 			pattern: path,
 		});
 
-		return { status: "ok" };
+		return path;
 	}
 }
 

package/src/plugins/get/README.md

@@ -5,8 +5,7 @@ Retrieves and promotes entries by path or glob pattern.
 ## Registration
 
 - **Tool**: `get`
-- **Modes**: ask, act
-- **Category**: ask
+- **Category**: `logging`
 - **Handler**: Fetches matching entries via `getEntriesByPattern`, promotes them with `promoteByPattern`, and records the result.
 
 ## Projection
@@ -17,3 +16,4 @@ Shows `get {path}` followed by the entry body.
 
 - Pattern queries (globs or body filters) produce a summary of matched paths.
 - Exact path queries report the path and token count, or "not found".
+- Budget check: rejects with 413 if incoming tokens exceed remaining context.

package/src/plugins/get/get.js

@@ -1,6 +1,6 @@
-import { readFileSync } from "node:fs";
 import KnownStore from "../../agent/KnownStore.js";
 import { storePatternResult } from "../helpers.js";
+import docs from "./getDoc.js";
 
 export default class Get {
 	#core;
@@ -11,10 +11,10 @@ export default class Get {
 		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.get = docs;
+			return docsMap;
+		});
 	}
 
 	async handler(entry, rummy) {
@@ -35,6 +35,7 @@ export default class Get {
 			normalized,
 			bodyFilter,
 		);
+
 		await store.promoteByPattern(runId, normalized, bodyFilter, turn);
 
 		if (isPattern) {

package/src/plugins/get/getDoc.js

@@ -0,0 +1,41 @@
+// Tool doc for <get>. 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-form is the primary invocation (simplest)
+	["## <get>[path/to/file]</get> - Load a file or entry into context"],
+
+	// --- Examples: 3 examples covering single file, known recall, and content search
+	[
+		"Example: <get>src/app.js</get>",
+		"Simplest form. Body = path. Teaches that get is the default read tool.",
+	],
+	[
+		'Example: <get path="known://*">auth</get>',
+		"Keyword recall: glob in path, search term in body. Cross-scheme hedberg pattern.",
+	],
+	[
+		'Example: <get path="src/**/*.js" preview>TODO</get>',
+		"Full pattern: recursive glob + preview + content filter. Shows all 3 features at once.",
+	],
+
+	// --- Constraints: RFC-style. Each prevents a specific failure mode.
+	[
+		"* Paths accept globs: `src/**/*.js`, `known://api_*`",
+		"Reinforces picomatch patterns work everywhere, not just in examples.",
+	],
+	[
+		"* `preview` shows matches without loading into context",
+		"Budget-awareness. Without this, models load everything and blow context.",
+	],
+	[
+		"* Body text filters results by content match",
+		"Generalizes examples 2-3. Body = filter, not just path.",
+	],
+	[
+		'* Use <set path="..." fidelity="index"/> to archive loaded content',
+		"Lifecycle: get→set. Load, read, archive. Prevents context hoarding.",
+	],
+];
+
+export default LINES.map(([text]) => text).join("\n");

package/src/plugins/hedberg/hedberg.js

@@ -1,6 +1,6 @@
 import { parseEditContent } from "./edits.js";
 import HeuristicMatcher, { generatePatch } from "./matcher.js";
-import { normalizeAttrs } from "./normalize.js";
+import { normalizeAttrs, parseJsonEdit } from "./normalize.js";
 import { hedmatch, hedsearch } from "./patterns.js";
 import { parseSed } from "./sed.js";
 
@@ -29,6 +29,7 @@ export default class Hedberg {
 			replace: Hedberg.replace,
 			parseSed,
 			parseEdits: parseEditContent,
+			parseJsonEdit,
 			normalizeAttrs,
 			generatePatch,
 		};

package/src/plugins/hedberg/normalize.js

@@ -19,6 +19,8 @@ const KNOWN_ATTRS = new Set([
 	"results",
 	"command",
 	"warn",
+	"summary",
+	"fidelity",
 ]);
 
 export function normalizeAttrs(attrs) {
@@ -37,5 +39,31 @@ export function normalizeAttrs(attrs) {
 		}
 	}
 	if ("preview" in out) out.preview = true;
+	// summary="..." is the description text, not a fidelity flag
+	if ("summary" in out && !out.summary) out.summary = true;
+	// file:// prefix — strip silently, bare paths are the convention
+	if (out.path?.startsWith("file://")) out.path = out.path.slice(7);
 	return out;
 }
+
+/**
+ * Parse JSON-style edit from body content.
+ * Accepts: {"search":"old","replace":"new"} and {search="old",replace="new"}
+ * Returns { search, replace } or null.
+ */
+export function parseJsonEdit(text) {
+	const trimmed = text.trim();
+	if (!trimmed.startsWith("{") || !/search/.test(trimmed)) return null;
+	try {
+		const json = JSON.parse(trimmed);
+		if (json.search != null)
+			return { search: json.search, replace: json.replace ?? "" };
+	} catch {
+		const searchMatch = trimmed.match(/search\s*=\s*"([^"]*)"/);
+		const replaceMatch = trimmed.match(/replace\s*=\s*"([^"]*)"/);
+		if (searchMatch) {
+			return { search: searchMatch[1], replace: replaceMatch?.[1] ?? "" };
+		}
+	}
+	return null;
+}

package/src/plugins/hedberg/patterns.js

@@ -1,4 +1,5 @@
 import { DOMParser } from "@xmldom/xmldom";
+import picomatch from "picomatch";
 import xpath from "xpath";
 
 export const deterministic = true;
@@ -131,26 +132,7 @@ function detect(pattern) {
 
 // --- Compilation ---
 
-function globToRegex(glob) {
-	let result = "";
-	for (let i = 0; i < glob.length; i++) {
-		const c = glob[i];
-		if (c === "*") result += ".*";
-		else if (c === "?") result += ".";
-		else if (c === "[") {
-			const close = glob.indexOf("]", i + 1);
-			if (close === -1) {
-				result += "\\[";
-				continue;
-			}
-			result += glob.slice(i, close + 1);
-			i = close;
-		} else if (/[.+^${}()|\\]/.test(c)) {
-			result += `\\${c}`;
-		} else result += c;
-	}
-	return result;
-}
+// Glob matching delegated to picomatch (standard, battle-tested).
 
 function parseRegex(pattern) {
 	const lastSlash = pattern.lastIndexOf("/");
@@ -214,12 +196,28 @@ function compile(pattern) {
 	switch (type) {
 		case "literal":
 			return { type, pattern };
-		case "glob":
-			return {
-				type,
-				anchoredRe: new RegExp(`^${globToRegex(pattern)}$`),
-				searchRe: new RegExp(globToRegex(pattern)),
-			};
+		case "glob": {
+			const escaped = pattern.replace(/([()])/g, "\\$1");
+			// Scheme paths have no directory structure — * matches everything
+			const opts = escaped.includes("://")
+				? {
+						dot: true,
+						nobrace: true,
+						noextglob: true,
+						bash: false,
+						regex: true,
+					}
+				: { dot: true, nobrace: true, noextglob: true };
+
+			// For scheme paths, convert single * after :// to ** so it crosses "/"
+			const prepared = escaped.includes("://")
+				? escaped.replace(/:\/\/\*(?!\*)/, "://**")
+				: escaped;
+
+			const isMatch = picomatch(prepared, opts);
+			const picoRe = picomatch.makeRe(prepared, opts);
+			return { type, isMatch, searchRe: picoRe };
+		}
 		case "regex": {
 			const { body, flags } = parseRegex(pattern);
 			return {
@@ -332,7 +330,7 @@ export function hedmatch(pattern, string) {
 		case "literal":
 			return string === compiled.pattern;
 		case "glob":
-			return compiled.anchoredRe.test(string);
+			return compiled.isMatch(string);
 		case "regex":
 			return compiled.re.test(string);
 		case "sed":

package/src/plugins/hedberg/sed.js

@@ -5,14 +5,15 @@
  * - Flag extraction (g, i, m, s, v)
  */
 
-function splitSed(str) {
+function splitSed(str, delim) {
 	const parts = [];
 	let current = "";
+	const escaped = `\\${delim}`;
 	for (let i = 0; i < str.length; i++) {
 		if (str[i] === "\\" && i + 1 < str.length) {
 			current += str[i] + str[i + 1];
 			i++;
-		} else if (str[i] === "/") {
+		} else if (str[i] === delim) {
 			parts.push(current);
 			current = "";
 		} else {
@@ -20,26 +21,32 @@ function splitSed(str) {
 		}
 	}
 	parts.push(current);
-	return parts;
+	return { parts, escaped };
 }
 
 export function parseSed(input) {
-	if (!input.startsWith("s/")) return null;
+	// Sed allows any non-alphanumeric delimiter: s/old/new/, s|old|new|, s#old#new#
+	const match = input.match(/^s([^\w\s])/);
+	if (!match) return null;
 
+	const delim = match[1];
 	const blocks = [];
 	let remaining = input;
-	while (remaining.startsWith("s/")) {
-		const parts = splitSed(remaining.slice(2));
+	const prefix = `s${delim}`;
+
+	while (remaining.startsWith(prefix)) {
+		const { parts, escaped } = splitSed(remaining.slice(2), delim);
 		if (parts.length < 2) break;
 		const flags = (parts[2] || "").match(/^[gimsv]*/)?.[0] || "";
+		const unesc = (s) => s.replaceAll(escaped, delim);
 		blocks.push({
-			search: parts[0].replaceAll("\\/", "/"),
-			replace: parts[1].replaceAll("\\/", "/"),
+			search: unesc(parts[0]),
+			replace: unesc(parts[1]),
 			flags,
 			sed: true,
 		});
-		const rest = parts.slice(2).join("/");
-		const next = rest.indexOf("s/");
+		const rest = parts.slice(2).join(delim);
+		const next = rest.indexOf(prefix);
 		remaining = next >= 0 ? rest.slice(next) : "";
 	}
 

package/src/plugins/index.js

@@ -1,7 +1,7 @@
 import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { basename, isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import PluginContext from "../hooks/PluginContext.js";
 
@@ -30,10 +30,6 @@ export async function registerPlugins(dirs = [], hooks) {
 const AUDIT_SCHEMES = [
 	"instructions",
 	"system",
-	"prompt",
-	"ask",
-	"act",
-	"progress",
 	"reasoning",
 	"model",
 	"error",
@@ -42,6 +38,8 @@ const AUDIT_SCHEMES = [
 	"content",
 ];
 
+const PROMPT_SCHEMES = ["prompt", "progress"];
+
 /**
  * After DB is ready, inject db and store into all PluginContext instances,
  * upsert declared schemes, and bootstrap audit schemes.
@@ -50,10 +48,17 @@ export async function initPlugins(db, store, hooks) {
 	for (const name of AUDIT_SCHEMES) {
 		await db.upsert_scheme.run({
 			name,
-			model_visible: ["ask", "act", "progress"].includes(name) ? 1 : 0,
+			model_visible: 0,
 			category: "audit",
 		});
 	}
+	for (const name of PROMPT_SCHEMES) {
+		await db.upsert_scheme.run({
+			name,
+			model_visible: 1,
+			category: "prompt",
+		});
+	}
 
 	for (const ctx of instances.values()) {
 		ctx.db = db;
@@ -70,16 +75,19 @@ export async function initPlugins(db, store, hooks) {
 			for (const s of ctx.schemes) registered.add(s.name);
 		}
 		for (const name of AUDIT_SCHEMES) registered.add(name);
+		for (const name of PROMPT_SCHEMES) registered.add(name);
 
 		for (const toolName of hooks.tools.names) {
 			if (registered.has(toolName)) continue;
 			await db.upsert_scheme.run({
 				name: toolName,
 				model_visible: 1,
-				category: "result",
+				category: "logging",
 			});
 		}
 	}
+
+	if (store) store.loadSchemes(db);
 }
 
 function resolvePlugin(packageName) {
@@ -105,9 +113,20 @@ async function loadEnvPlugins(hooks) {
 		if (!key.startsWith("RUMMY_PLUGIN_") || !value) continue;
 		const name = key.replace("RUMMY_PLUGIN_", "").toLowerCase();
 		try {
-			const { default: Plugin } = await importPlugin(value);
+			const importPromise = isAbsolute(value)
+				? importAbsolute(value)
+				: importPlugin(value);
+			const { default: Plugin } = await withTimeout(
+				importPromise,
+				PLUGIN_LOAD_TIMEOUT,
+				`Plugin import timed out: ${value}`,
+			);
 			if (typeof Plugin?.register === "function") {
-				await Plugin.register(hooks);
+				await withTimeout(
+					Plugin.register(hooks),
+					PLUGIN_LOAD_TIMEOUT,
+					`Plugin register timed out: ${value}`,
+				);
 			} else if (typeof Plugin === "function") {
 				const ctx = new PluginContext(name, hooks);
 				new Plugin(ctx);
@@ -120,6 +139,19 @@ async function loadEnvPlugins(hooks) {
 	}
 }
 
+async function importAbsolute(dir) {
+	const pkgPath = join(dir, "package.json");
+	if (!existsSync(pkgPath)) {
+		// Bare .js file
+		return import(pathToFileURL(dir).href);
+	}
+	const pkg = JSON.parse(
+		(await import("node:fs")).readFileSync(pkgPath, "utf8"),
+	);
+	const entry = pkg.exports?.["."] || pkg.main || "index.js";
+	return import(pathToFileURL(join(dir, entry)).href);
+}
+
 async function scanDir(dir, hooks, isRoot = false) {
 	if (!existsSync(dir)) return;
 
@@ -167,18 +199,29 @@ async function scanDir(dir, hooks, isRoot = false) {
 				await loadPlugin(fullPath, hooks);
 			}
 		} else if (stats.isDirectory()) {
+			if (existsSync(join(fullPath, "DISABLED"))) continue;
 			await scanDir(fullPath, hooks, false);
 		}
 	}
 }
 
+const PLUGIN_LOAD_TIMEOUT = 10000;
+
 async function loadPlugin(filePath, hooks) {
 	try {
 		const url = pathToFileURL(filePath).href;
-		const { default: Plugin } = await import(url);
+		const { default: Plugin } = await withTimeout(
+			import(url),
+			PLUGIN_LOAD_TIMEOUT,
+			`Plugin import timed out: ${filePath}`,
+		);
 
 		if (typeof Plugin?.register === "function") {
-			await Plugin.register(hooks);
+			await withTimeout(
+				Plugin.register(hooks),
+				PLUGIN_LOAD_TIMEOUT,
+				`Plugin register timed out: ${filePath}`,
+			);
 		} else if (typeof Plugin === "function") {
 			const name = basename(filePath, ".js");
 			const ctx = new PluginContext(name, hooks);
@@ -186,8 +229,17 @@ async function loadPlugin(filePath, hooks) {
 			instances.set(name, ctx);
 		}
 	} catch (err) {
-		if (process.env.RUMMY_DEBUG === "true") {
-			console.error(`[RUMMY] Plugin load failed at ${filePath}:`, err);
-		}
+		console.warn(
+			`[RUMMY] Plugin load failed: ${basename(filePath)} — ${err.message}`,
+		);
 	}
 }
+
+function withTimeout(promise, ms, message) {
+	return Promise.race([
+		promise,
+		new Promise((_, reject) =>
+			setTimeout(() => reject(new Error(message)), ms),
+		),
+	]);
+}

package/src/plugins/instructions/README.md

@@ -4,8 +4,12 @@ Projects the system prompt instructions into model context.
 
 ## Registration
 
-- **Projection**: `onProject("instructions", ...)` — no tool handler.
+- **View**: `full` — renders preamble + tool docs + persona.
+- **Event**: `turn.started` — writes `instructions://system` entry.
+- **Filter**: `instructions.toolDocs` — gathers docs from all tool plugins.
 
 ## Behavior
 
-Replaces the `[%TOOLS%]` placeholder in the prompt body with the `tools` attribute. Appends tool descriptions and persona text when present in attributes.
+Replaces the `[%TOOLS%]` placeholder in the preamble with the active
+tool list. Appends tool descriptions gathered via the `toolDocs` filter
+and persona text when present in attributes.

package/src/plugins/instructions/instructions.js

@@ -17,20 +17,36 @@ export default class Instructions {
 	async onTurnStarted({ rummy }) {
 		const { entries: store, sequence: turn, runId } = rummy;
 		const runRow = await rummy.db.get_run_by_id.get({ id: runId });
+		const toolSet = rummy.toolSet
+			? [...rummy.toolSet]
+			: this.#core.hooks.tools.names;
 		await store.upsert(runId, turn, "instructions://system", "", 200, {
-			attributes: { persona: runRow?.persona || null },
+			attributes: {
+				persona: runRow?.persona || null,
+				toolSet,
+			},
 		});
 	}
 
 	async full(entry) {
 		const attrs = entry.attributes;
-		const tools = this.#core.hooks.tools.names.join(", ");
+		const activeTools = attrs.toolSet
+			? new Set(attrs.toolSet)
+			: new Set(this.#core.hooks.tools.names);
+		const sorted = this.#core.hooks.tools.names.filter((n) =>
+			activeTools.has(n),
+		);
+		const tools = sorted.join(", ");
 		let prompt = preamble.replace("[%TOOLS%]", tools);
 		const toolDocs = await this.#core.hooks.instructions.toolDocs.filter(
-			"",
 			{},
+			{ toolSet: activeTools },
 		);
-		if (toolDocs) prompt += `\n\n${toolDocs}`;
+		const docsText = sorted
+			.filter((key) => toolDocs[key])
+			.map((key) => toolDocs[key])
+			.join("\n\n");
+		if (docsText) prompt += `\n\n${docsText}`;
 		if (attrs.persona) prompt += `\n\n## Persona\n\n${attrs.persona}`;
 		return prompt;
 	}

package/src/plugins/instructions/preamble.md

@@ -1,12 +1,16 @@
-You are an assistant. You gather information, then either answer questions or take action.
+You are an assistant. YOU MUST gather information, then YOU MAY either answer questions or take action.
 
 # Response Rules
 
-* You must register unknowns with <unknown>(thing I don't know yet)</unknown> before acting.
-* Save known information with <known>(thing I know now)</known>.
-* Respond with Tool Commands. You may use multiple tools in your response.
+Required: YOU MUST respond with Tool Commands in the XML format. YOU MAY use multiple tools in your response.
+Optional: YOU MAY think in an optional <think></think> tag before using any other Tool Commands.
+Required: YOU MUST register all unknowns with <unknown>(specific thing I need to learn)</unknown>.
+Required: YOU MUST register all new information, decisions, and plans with <known>(specific information, ideas, or plans)</known>.
+Required: YOU MUST conclude every turn with EITHER <update/> if still working OR <summarize/> if done. Never both.
+Required: Path and summary information is approximate. YOU MUST use <get> to verify before acting on summarized content.
+Info: When information conflicts, later turns are more likely to be relevant and correct than earlier turns.
+Info: Your context is limited but your storage is not. Organize and categorize your information, ideas, plans, and history to optimize your context.
 
 # Tool Commands
 
 Tools: [%TOOLS%]
-Required: Either `<update/>` if still working or `<summarize/>` if done. Never both.

package/src/plugins/known/README.md

@@ -1,18 +1,21 @@
 # known
 
-Writes arbitrary key/value entries into the store at full fidelity.
+Writes knowledge entries into the store at full fidelity.
 
 ## Registration
 
 - **Tool**: `known`
-- **Modes**: ask, act
-- **Category**: act
-- **Handler**: Upserts the entry body at the target path with `full` state.
+- **Category**: `data`
+- **Handler**: Upserts the entry body at the target path with status 200.
+- **Filter**: `assembly.system` at priority 100 — renders `<knowns>` section.
 
 ## Projection
 
-Shows `known {path}` followed by the entry body.
+Shows `# known {path}` followed by the entry body.
 
-## Behavior
+## Assembly
 
-The target path defaults to `entry.resultPath` but can be overridden via `attrs.path`. Used by the model to persist structured notes and context.
+Filters turn_context rows where `category === "data"`. Renders all
+data entries (files, knowledge, skills, URLs) into the `<knowns>` section
+of the system message. Third-party plugins that register with
+`category: "data"` automatically appear here.