@possumtech/rummy 0.2.8 → 0.3.1

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) {
@@ -30,12 +30,81 @@ export default class Get {
 		const normalized = KnownStore.normalizePath(target);
 		const bodyFilter = entry.attributes.body || null;
 		const isPattern = bodyFilter || normalized.includes("*");
+
+		const line =
+			entry.attributes.line != null
+				? Math.max(1, parseInt(entry.attributes.line, 10))
+				: null;
+		const limit =
+			entry.attributes.limit != null
+				? Math.max(1, parseInt(entry.attributes.limit, 10))
+				: null;
+
 		const matches = await store.getEntriesByPattern(
 			runId,
 			normalized,
 			bodyFilter,
 		);
+
+		// Partial read — no fidelity promotion, returns a line slice as the log item.
+		if (line !== null || limit !== null) {
+			if (isPattern) {
+				await store.upsert(
+					runId,
+					turn,
+					entry.resultPath,
+					"line/limit requires a single path, not a glob or body filter",
+					400,
+					{ loopId },
+				);
+				return;
+			}
+			if (matches.length === 0) {
+				await store.upsert(
+					runId,
+					turn,
+					entry.resultPath,
+					`${target} not found`,
+					200,
+					{ loopId },
+				);
+				return;
+			}
+			const allLines = matches[0].body.split("\n");
+			const total = allLines.length;
+			const startLine = line ?? 1;
+			const startIdx = startLine - 1;
+			const endIdx = limit !== null ? Math.min(startIdx + limit, total) : total;
+			const slice = allLines.slice(startIdx, endIdx).join("\n");
+			const endLine = endIdx;
+			const header = `[lines ${startLine}–${endLine} / ${total} total]`;
+			await store.upsert(
+				runId,
+				turn,
+				entry.resultPath,
+				`${header}\n${slice}`,
+				200,
+				{ loopId },
+			);
+			return;
+		}
+
+		const VALID_FIDELITY = {
+			stored: 1,
+			summary: 1,
+			index: 1,
+			full: 1,
+			archive: 1,
+		};
+		const fidelityAttr = VALID_FIDELITY[entry.attributes.fidelity]
+			? entry.attributes.fidelity
+			: null;
+
 		await store.promoteByPattern(runId, normalized, bodyFilter, turn);
+		if (fidelityAttr) {
+			for (const match of matches)
+				await store.setFidelity(runId, match.path, fidelityAttr);
+		}
 
 		if (isPattern) {
 			await storePatternResult(
@@ -52,7 +121,9 @@ export default class Get {
 			const total = matches.reduce((s, m) => s + m.tokens_full, 0);
 			const paths = matches.map((m) => m.path).join(", ");
 			const body =
-				matches.length > 0 ? `${paths} ${total} tokens` : `${target} not found`;
+				matches.length > 0
+					? `${paths} loaded into <knowns> (${total} tokens)`
+					: `${target} not found`;
 			await store.upsert(runId, turn, entry.resultPath, body, 200, {
 				loopId,
 			});

package/src/plugins/get/getDoc.js

@@ -0,0 +1,51 @@
+// 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>authentication</get>',
+		"Full pattern: recursive glob + preview + content filter. Shows all 3 features at once. Body is a filter keyword, never file content.",
+	],
+
+	// --- Partial read: line/limit — show before constraints so model sees it as a first-class pattern
+	[
+		'Example: <get path="src/agent/AgentLoop.js" line="644" limit="80"/>',
+		"Partial read. Returns lines 644–723 as the log item without promoting the entry to full. Use summary fidelity to find line numbers, then target the symbol directly.",
+	],
+
+	// --- Constraints: RFC-style. Each prevents a specific failure mode.
+	[
+		"* Paths accept patterns: `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.",
+	],
+	[
+		"* `line` and `limit` read a slice without promoting — patterns not allowed",
+		"The no-promotion constraint is what makes partial read safe: context budget is unaffected.",
+	],
+	[
+		'* Use <set path="..." fidelity="archive"/> to remove loaded content from context',
+		"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/matcher.js

@@ -1,34 +1,15 @@
-import { execSync } from "node:child_process";
-import { unlinkSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { createTwoFilesPatch } from "diff";
 
 export function generatePatch(filePath, oldContent, newContent) {
-	const id = `${Date.now()}_${Math.random().toString(36).slice(2)}`;
-	const oldPath = join(tmpdir(), `rummy_diff_old_${id}`);
-	const newPath = join(tmpdir(), `rummy_diff_new_${id}`);
-
-	try {
-		writeFileSync(oldPath, oldContent);
-		writeFileSync(newPath, newContent);
-
-		const result = execSync(
-			`diff -u --label "${filePath}\told" --label "${filePath}\tnew" "${oldPath}" "${newPath}"`,
-			{ encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] },
-		);
-		return result;
-	} catch (err) {
-		// diff exits 1 when files differ — that's the success case
-		if (err.stdout) return err.stdout;
-		return "";
-	} finally {
-		try {
-			unlinkSync(oldPath);
-		} catch {}
-		try {
-			unlinkSync(newPath);
-		} catch {}
-	}
+	return createTwoFilesPatch(
+		`${filePath}\told`,
+		`${filePath}\tnew`,
+		oldContent,
+		newContent,
+		"",
+		"",
+		{ context: 3 },
+	);
 }
 
 export default class HeuristicMatcher {

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,26 @@
-You are an assistant. You gather information, then either answer questions or take action.
+You are a folksonomic memory agent. YOU MUST organize all information into searchable taxonomies with navigable path hierarchies and searchable summary tags, then YOU MAY answer questions and/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 facts, decisions, and plans with <known path="topic/subtopic" summary="keyword,keyword,keyword">[specific facts, decisions, or plans]</known>.
+Required: Every <known> MUST include summary="keyword,keyword" tags.
+Info: Paths are addresses for tools. Summary tags tell you what's inside.
+Info: 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 archive is not. Organize and categorize your facts, decisions, plans, and history to optimize your context.
+
+Required: YOU MUST promote all relevant "summary" entries to "full".
+Required: YOU MUST demote all irrelevant "full" entries to "summary".
+
+Required: YOU MUST conclude every turn with EITHER <update></update> if still working OR <summarize></summarize> if done. Never both.
+Required: YOU MUST use one and only one <update></update> or <summarize></summarize> tag, and only at the end.
 
 # Tool Commands
 
 Tools: [%TOOLS%]
-Required: Either `<update/>` if still working or `<summarize/>` if done. Never both.