@possumtech/rummy 0.2.1

package/src/plugins/instructions/instructions.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+
+const preamble = readFileSync(
+	new URL("./preamble.md", import.meta.url),
+	"utf8",
+);
+
+export default class Instructions {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.on("full", this.full.bind(this));
+		core.on("turn.started", this.onTurnStarted.bind(this));
+	}
+
+	async onTurnStarted({ rummy }) {
+		const { entries: store, sequence: turn, runId } = rummy;
+		const runRow = await rummy.db.get_run_by_id.get({ id: runId });
+		await store.upsert(runId, turn, "instructions://system", "", "info", {
+			attributes: { persona: runRow?.persona || null },
+		});
+	}
+
+	async full(entry) {
+		const attrs = entry.attributes;
+		const tools = this.#core.hooks.tools.names.join(", ");
+		let prompt = preamble.replace("[%TOOLS%]", tools);
+		const toolDocs = await this.#core.hooks.instructions.toolDocs.filter(
+			"",
+			{},
+		);
+		if (toolDocs) prompt += `\n\n${toolDocs}`;
+		if (attrs.persona) prompt += `\n\n## Persona\n\n${attrs.persona}`;
+		return prompt;
+	}
+}

package/src/plugins/instructions/preamble.md

@@ -0,0 +1,12 @@
+You are an assistant. You gather information, then 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.
+
+# Tool Commands
+
+Tools: [%TOOLS%]
+Required: Either `<update/>` if still working or `<summarize/>` if done. Never both.

package/src/plugins/known/README.md

@@ -0,0 +1,18 @@
+# known
+
+Writes arbitrary key/value 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.
+
+## Projection
+
+Shows `known {path}` followed by the entry body.
+
+## Behavior
+
+The target path defaults to `entry.resultPath` but can be overridden via `attrs.path`. Used by the model to persist structured notes and context.

package/src/plugins/known/docs.md

@@ -0,0 +1,3 @@
+## <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/known/known.js

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+
+export default class Known {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme({
+			fidelity: "turn",
+			validStates: ["full", "stored"],
+			category: "knowledge",
+		});
+		core.on("handler", this.handler.bind(this));
+		core.on("full", this.full.bind(this));
+		core.filter("assembly.system", this.assembleKnown.bind(this), 100);
+		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 } = rummy;
+		const target = entry.attributes.path || entry.resultPath;
+		await store.upsert(runId, turn, target, entry.body, "full");
+	}
+
+	full(entry) {
+		return `# known ${entry.path}\n${entry.body}`;
+	}
+
+	async assembleKnown(content, ctx) {
+		const entries = ctx.rows.filter(
+			(r) =>
+				r.category === "file" ||
+				r.category === "file_index" ||
+				r.category === "known" ||
+				r.category === "known_index",
+		);
+		if (entries.length === 0) return content;
+
+		// Rows arrive pre-sorted by SQL: skill → index → summary → full, then by recency
+		const lines = entries.map((e) => renderKnownTag(e));
+		return `${content}\n\n<knowns>\n${lines.join("\n")}\n</knowns>`;
+	}
+}
+
+function renderKnownTag(entry) {
+	const tokens = entry.tokens ? ` tokens="${entry.tokens}"` : "";
+	const state = entry.state ? ` state="${entry.state}"` : "";
+
+	if (entry.body) {
+		return `<known path="${entry.path}"${state}${tokens}>${entry.body}</known>`;
+	}
+
+	return `<known path="${entry.path}"${state}${tokens}/>`;
+}

package/src/plugins/mv/README.md

@@ -0,0 +1,18 @@
+# mv
+
+Moves (renames) an entry from one path to another within the K/V store.
+
+## Registration
+
+- **Tool**: `mv`
+- **Modes**: ask, act
+- **Category**: act
+- **Handler**: Reads source body, writes to destination, removes source. K/V destinations resolve immediately (`pass`); file destinations produce a `proposed` entry.
+
+## Projection
+
+Shows `mv {from} {to}`.
+
+## Behavior
+
+Warns if the destination already exists and will be overwritten. Uses `KnownStore.scheme()` to determine K/V vs file paths. Source entry is removed on successful K/V moves.

package/src/plugins/mv/docs.md

@@ -0,0 +1,2 @@
+## <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/mv/mv.js

@@ -0,0 +1,56 @@
+import { readFileSync } from "node:fs";
+import KnownStore from "../../agent/KnownStore.js";
+
+export default class Mv {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme({
+			validStates: ["full", "proposed", "pass", "rejected", "error", "pattern"],
+		});
+		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 } = rummy;
+		const { path, to } = entry.attributes;
+
+		const source = await store.getBody(runId, path);
+		if (source === null) return;
+
+		const destScheme = KnownStore.scheme(to);
+		const existing = await store.getBody(runId, to);
+		const warning =
+			existing !== null && destScheme !== null
+				? `Overwrote existing entry at ${to}`
+				: null;
+
+		const body = `${path} ${to}`;
+		if (destScheme === null) {
+			await store.upsert(runId, turn, entry.resultPath, body, "proposed", {
+				attributes: { from: path, to, isMove: true, warning },
+			});
+		} else {
+			await store.upsert(runId, turn, to, source, "full");
+			await store.remove(runId, path);
+			await store.upsert(runId, turn, entry.resultPath, body, "pass", {
+				attributes: { from: path, to, isMove: true, warning },
+			});
+		}
+	}
+
+	full(entry) {
+		return `# mv ${entry.attributes.from || ""} ${entry.attributes.to || ""}`;
+	}
+
+	summary(entry) {
+		return this.full(entry);
+	}
+}

package/src/plugins/previous/README.md

@@ -0,0 +1,15 @@
+# previous
+
+Renders the `<previous>` section of the system message — completed loop
+history from prior ask/act invocations on this run.
+
+## Registration
+
+- **Filter**: `assembly.system` at priority 200
+- **Condition**: Omitted when `loopStartTurn <= 1` (first loop has no history)
+
+## Behavior
+
+Filters turn_context rows where `category` is `result` or `structural`
+and `source_turn < loopStartTurn`. Renders each entry chronologically
+with status symbols (✓/✗/·).

package/src/plugins/previous/previous.js

@@ -0,0 +1,50 @@
+export default class Previous {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.filter("assembly.system", this.assemblePrevious.bind(this), 200);
+	}
+
+	async assemblePrevious(content, ctx) {
+		if (ctx.loopStartTurn <= 1) return content;
+
+		const entries = ctx.rows.filter(
+			(r) =>
+				(r.category === "result" || r.category === "structural") &&
+				r.source_turn < ctx.loopStartTurn,
+		);
+		if (entries.length === 0) return content;
+
+		const lines = await Promise.all(
+			entries.map((e) => renderToolTag(e, "summary", this.#core)),
+		);
+		return `${content}\n\n<previous>\n${lines.join("\n")}\n</previous>`;
+	}
+}
+
+async function renderToolTag(entry, fidelity, core) {
+	const attrs =
+		typeof entry.attributes === "string"
+			? JSON.parse(entry.attributes)
+			: entry.attributes;
+
+	const path = `${entry.scheme}://${attrs?.path || attrs?.file || attrs?.command || ""}`;
+	const status = entry.state ? ` status="${entry.state}"` : "";
+
+	let body;
+	try {
+		body = await core.hooks.tools.view(entry.scheme, {
+			...entry,
+			fidelity,
+			attributes: attrs,
+		});
+	} catch {
+		body = entry.body;
+	}
+
+	if (body) {
+		return `<tool path="${path}"${status}>${body}</tool>`;
+	}
+	return `<tool path="${path}"${status}/>`;
+}

package/src/plugins/progress/README.md

@@ -0,0 +1,17 @@
+# progress
+
+Renders the `<progress>` section of the user message — bridges the
+current work log to the active prompt.
+
+## Registration
+
+- **Filter**: `assembly.user` at priority 200
+
+## Behavior
+
+On first turn: "Begin."
+On continuation turns with current entries: "The above actions were
+performed in response to the following prompt:"
+If a `progress://` entry exists, uses its body directly.
+
+Progress text is the tuning knob for model orientation between turns.

package/src/plugins/progress/progress.js

@@ -0,0 +1,44 @@
+export default class Progress {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.filter("assembly.user", this.assembleProgress.bind(this), 200);
+	}
+
+	async assembleProgress(content, ctx) {
+		const usedTokens = ctx.rows.reduce((sum, r) => sum + (r.tokens || 0), 0);
+		const contextSize = ctx.contextSize || 0;
+		const pct = contextSize ? Math.round((usedTokens / contextSize) * 100) : 0;
+
+		const unknownCount = ctx.rows.filter(
+			(r) => r.category === "unknown",
+		).length;
+
+		const hasCurrent = ctx.rows.some(
+			(r) =>
+				(r.category === "result" || r.category === "structural") &&
+				r.source_turn >= ctx.loopStartTurn,
+		);
+
+		const parts = [];
+
+		const tokenInfo = contextSize
+			? `${usedTokens} of ${contextSize} tokens (${pct}%)`
+			: "";
+		const unknownInfo =
+			unknownCount > 0
+				? `${unknownCount} unknown${unknownCount > 1 ? "s" : ""} remaining`
+				: "0 unknowns";
+		const status = [tokenInfo, unknownInfo].filter(Boolean).join(" · ");
+		if (status) parts.push(status);
+
+		if (hasCurrent) {
+			parts.push(
+				"The above actions were performed in response to the following prompt:",
+			);
+		}
+
+		return `${content}<progress>${parts.join("\n")}</progress>\n`;
+	}
+}

package/src/plugins/prompt/README.md

@@ -0,0 +1,16 @@
+# prompt
+
+Renders the `<ask>` or `<act>` tag at the end of the user message.
+Always present on every turn — the model always sees its task.
+
+## Registration
+
+- **Filter**: `assembly.user` at priority 300 (always last)
+
+## Behavior
+
+Finds the latest `ask://` or `act://` entry in the turn_context rows.
+Renders with `tools` attribute (available tool list) and optional `warn`
+attribute in ask mode ("File and system modification prohibited on this
+turn."). Falls back to the mode passed by the core if no prompt entry
+exists.

package/src/plugins/prompt/prompt.js

@@ -0,0 +1,45 @@
+export default class Prompt {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.on("turn.started", this.onTurnStarted.bind(this));
+		core.filter("assembly.user", this.assemblePrompt.bind(this), 300);
+	}
+
+	async onTurnStarted({ rummy, mode, prompt, isContinuation }) {
+		const { entries: store, sequence: turn, runId } = rummy;
+
+		if (!isContinuation && prompt) {
+			await store.upsert(runId, turn, `prompt://${turn}`, "", "info", {
+				attributes: { mode },
+			});
+			await store.upsert(runId, turn, `${mode}://${turn}`, prompt, "info");
+		} else {
+			await store.upsert(
+				runId,
+				turn,
+				`progress://${turn}`,
+				prompt || "",
+				"info",
+			);
+		}
+	}
+
+	async assemblePrompt(content, ctx) {
+		const promptEntry = ctx.rows.findLast(
+			(r) =>
+				r.category === "prompt" && (r.scheme === "ask" || r.scheme === "act"),
+		);
+
+		const mode = promptEntry?.scheme || ctx.type;
+		const body = promptEntry?.body || "";
+		const tools = this.#core.hooks.tools.namesForMode(mode).join(", ");
+		const warn =
+			mode === "ask"
+				? ' warn="File and system modification prohibited on this turn."'
+				: "";
+
+		return `${content}<${mode} tools="${tools}"${warn}>${body}</${mode}>`;
+	}
+}

package/src/plugins/rm/README.md

@@ -0,0 +1,18 @@
+# rm
+
+Removes entries by path or glob pattern.
+
+## Registration
+
+- **Tool**: `rm`
+- **Modes**: ask, act
+- **Category**: act
+- **Handler**: Matches entries by pattern. K/V entries are removed immediately (`pass`); file entries produce `proposed` state for client approval.
+
+## Projection
+
+Shows `rm {path}`.
+
+## Behavior
+
+Supports glob patterns and body filters via `getEntriesByPattern`. Each matched entry is processed independently.

package/src/plugins/rm/docs.md

@@ -0,0 +1,4 @@
+## <rm path="[path/to/file]"/> - Remove a file or entry
+Example: <rm path="src/config.js"/>
+Example: <rm path="unknown://42"/>
+* <rm/> removes the file or entry from context and deletes it PERMANENTLY

package/src/plugins/rm/rm.js

@@ -0,0 +1,51 @@
+import { readFileSync } from "node:fs";
+
+export default class Rm {
+	#core;
+
+	constructor(core) {
+		this.#core = core;
+		core.registerScheme({
+			validStates: ["full", "proposed", "pass", "rejected", "error", "pattern"],
+		});
+		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 } = rummy;
+		const target = entry.attributes.path;
+		const matches = await store.getEntriesByPattern(
+			runId,
+			target,
+			entry.attributes.body,
+		);
+
+		for (const match of matches) {
+			const resultPath = `rm://${match.path}`;
+			if (match.scheme === null) {
+				await store.upsert(runId, turn, resultPath, match.path, "proposed", {
+					attributes: { path: match.path },
+				});
+			} else {
+				await store.remove(runId, match.path);
+				await store.upsert(runId, turn, resultPath, match.path, "pass", {
+					attributes: { path: match.path },
+				});
+			}
+		}
+	}
+
+	full(entry) {
+		return `# rm ${entry.attributes.path || entry.path}`;
+	}
+
+	summary(entry) {
+		return this.full(entry);
+	}
+}

package/src/plugins/rpc/README.md

@@ -0,0 +1,45 @@
+# rpc
+
+Registers all core RPC methods and dispatches client operations through the tool handler chain.
+
+## Registration
+
+- **No tool handler** — this plugin registers RPC methods on `hooks.rpc.registry`, not tool handlers.
+
+## RPC Methods
+
+### Protocol
+- `ping` — liveness check.
+- `discover` — returns method/notification catalog.
+- `init` — initialize project (sets projectId, projectRoot, configPath).
+
+### Models
+- `getModels`, `addModel`, `removeModel` — CRUD for model aliases.
+
+### Entry Operations
+- `read` — promote entry to full state, or create persistent file constraint.
+- `store` — demote entry to stored state, or manage file constraints (ignore/clear).
+- `write` — create/update entry. K/V paths write directly; file paths dispatch through `set` handler.
+- `delete` — remove entry via `rm` handler dispatch.
+- `getEntries` — query entries by glob pattern.
+
+### Runs
+- `startRun` — pre-create a run with model/config.
+- `ask` — non-mutating model query.
+- `act` — mutating model directive.
+- `run/resolve` — resolve a proposed entry (accept/reject).
+- `run/abort` — abort an in-flight run.
+- `run/rename` — rename a run alias.
+- `run/inject` — inject a message into an idle or active run.
+- `run/config` — update run parameters (temperature, persona, context_limit, model).
+- `getRuns`, `getRun` — query run list and full run detail.
+
+### Notifications
+- `run/state` — turn state update with history, unknowns, proposed, telemetry.
+- `run/progress` — turn status (thinking/processing).
+- `ui/render` — streaming output.
+- `ui/notify` — toast notification.
+
+## Behavior
+
+Client operations (read, write, delete, store) build a `RummyContext` for the target run and dispatch through the same handler chain as model operations via `dispatchTool`.