@possumtech/rummy 0.5.0 → 2.0.0

package/src/hooks/HookRegistry.js

@@ -29,9 +29,8 @@ export default class HookRegistry {
 			await p.callback(rummy);
 			if (this.#debug) {
 				const duration = (performance.now() - start).toFixed(2);
-				console.log(
-					`[PIPELINE] Processor ${p.callback.name || "anonymous"} took ${duration}ms`,
-				);
+				const name = p.callback.name ? p.callback.name : "anonymous";
+				console.log(`[PIPELINE] Processor ${name} took ${duration}ms`);
 			}
 		}
 	}
@@ -46,7 +45,8 @@ export default class HookRegistry {
 	}
 
 	async applyFilters(tag, value, ...args) {
-		const hooks = this.#filters.get(tag) || [];
+		const hooks = this.#filters.get(tag);
+		if (!hooks) return value;
 		let result = value;
 		for (const h of hooks) {
 			result = await h.callback(result, ...args);
@@ -71,7 +71,8 @@ export default class HookRegistry {
 	}
 
 	async emitEvent(tag, ...args) {
-		const hooks = this.#events.get(tag) || [];
+		const hooks = this.#events.get(tag);
+		if (!hooks) return;
 		for (const h of hooks) {
 			await h.callback(...args);
 		}

package/src/hooks/Hooks.js

@@ -1,4 +1,5 @@
 import HookRegistry from "./HookRegistry.js";
+import RpcRegistry from "./RpcRegistry.js";
 import ToolRegistry from "./ToolRegistry.js";
 
 /**
@@ -56,10 +57,25 @@ export default function createHooks(debug = false) {
 		turn: {
 			started: createEvent("turn.started"),
 			response: createEvent("turn.response"),
-			proposal: createEvent("turn.proposal"),
-			proposing: createEvent("turn.proposing"),
 			completed: createEvent("turn.completed"),
 		},
+		proposal: {
+			prepare: createEvent("proposal.prepare"),
+			pending: createEvent("proposal.pending"),
+			// Plugins veto acceptance by returning {allow:false, outcome, body}.
+			// Used e.g. by set plugin's readonly constraint check.
+			accepting: createFilter("proposal.accepting"),
+			// Plugins compose the resolved body based on path/action. Default
+			// is output || "". Used e.g. by set plugin to preserve the
+			// model's proposed content as the resolved body.
+			content: createFilter("proposal.content"),
+			// Fires after a proposal resolves with action="accept". Plugins
+			// perform their side effects (file materialize, unlink, stream
+			// setup, etc.) here — NOT in AgentLoop.resolve.
+			accepted: createEvent("proposal.accepted"),
+			// Fires after a proposal resolves with action="error" or "reject".
+			rejected: createEvent("proposal.rejected"),
+		},
 		assembly: {
 			system: createFilter("assembly.system"),
 			user: createFilter("assembly.user"),
@@ -82,6 +98,25 @@ export default function createHooks(debug = false) {
 			},
 			messages: createFilter("llm.messages"),
 			response: createFilter("llm.response"),
+			// Reasoning merge filter. Subscribers contribute per-tag
+			// reasoning text (e.g. the think plugin's <think>…</think>)
+			// to the model's reasoning_content field. Fires between parse
+			// and turn.response.
+			reasoning: createFilter("llm.reasoning"),
+			// LLM provider registry. Plugins contribute entries shaped:
+			//   {
+			//     name: string,
+			//     matches: (modelAlias) => boolean,
+			//     completion: (messages, modelAlias, options) => Promise<response>,
+			//     getContextSize: (modelAlias) => Promise<number>,
+			//   }
+			// Each provider owns a prefix namespace (e.g. "openai/", "ollama/",
+			// "openrouter/"). LlmProvider picks the first provider whose
+			// matches() returns true. No catchall — if a model alias doesn't
+			// match any registered provider, the request fails with a clear
+			// "no provider registered" error. External plugins add new
+			// prefixes without namespace collision.
+			providers: [],
 		},
 		file: {},
 		prompt: {
@@ -100,6 +135,12 @@ export default function createHooks(debug = false) {
 			materialized: createEvent("context.materialized"),
 		},
 		action: {},
+		error: {
+			log: createEvent("error.log"),
+		},
+		stream: {
+			cancelled: createEvent("stream.cancelled"),
+		},
 		ui: {
 			render: createEvent("ui.render"),
 			notify: createEvent("ui.notify"),
@@ -117,7 +158,7 @@ export default function createHooks(debug = false) {
 			response: {
 				result: createFilter("rpc.response.result"),
 			},
-			registry: null, // attached by service.js after RpcRegistry creation
+			registry: new RpcRegistry(),
 		},
 		agent: {},
 		tools,

package/src/hooks/PluginContext.js

@@ -10,8 +10,6 @@
 export default class PluginContext {
 	#name;
 	#hooks;
-	#db = null;
-	#store = null;
 
 	constructor(name, hooks) {
 		this.#name = name;
@@ -22,22 +20,6 @@ export default class PluginContext {
 		return this.#name;
 	}
 
-	get db() {
-		return this.#db;
-	}
-
-	set db(value) {
-		this.#db = value;
-	}
-
-	get entries() {
-		return this.#store;
-	}
-
-	set entries(value) {
-		this.#store = value;
-	}
-
 	#schemes = [];
 
 	get hooks() {
@@ -48,16 +30,36 @@ export default class PluginContext {
 		return this.#schemes;
 	}
 
-	registerScheme({ name, modelVisible = 1, category = "logging" } = {}) {
+	registerScheme({
+		name,
+		modelVisible = 1,
+		category = "logging",
+		scope = "run",
+		writableBy = ["model", "plugin"],
+	} = {}) {
 		if (!PluginContext.CATEGORIES.has(category)) {
 			throw new Error(
 				`Invalid category "${category}". Must be one of: ${[...PluginContext.CATEGORIES].join(", ")}`,
 			);
 		}
+		if (!PluginContext.SCOPES.has(scope)) {
+			throw new Error(
+				`Invalid scope "${scope}". Must be one of: ${[...PluginContext.SCOPES].join(", ")}`,
+			);
+		}
+		for (const w of writableBy) {
+			if (!PluginContext.WRITERS.has(w)) {
+				throw new Error(
+					`Invalid writer "${w}" in writableBy. Must be one of: ${[...PluginContext.WRITERS].join(", ")}`,
+				);
+			}
+		}
 		this.#schemes.push({
 			name: name || this.#name,
 			model_visible: modelVisible,
 			category,
+			default_scope: scope,
+			writable_by: JSON.stringify(writableBy),
 		});
 	}
 
@@ -65,6 +67,12 @@ export default class PluginContext {
 		new Set(["data", "logging", "unknown", "prompt"]),
 	);
 
+	static SCOPES = Object.freeze(new Set(["run", "project", "global"]));
+
+	static WRITERS = Object.freeze(
+		new Set(["model", "plugin", "client", "system"]),
+	);
+
 	ensureTool() {
 		this.#hooks.tools.ensureTool(this.#name);
 	}
@@ -78,7 +86,7 @@ export default class PluginContext {
 	/**
 	 * Register a named callback for this plugin.
 	 * "handler" registers the tool handler.
-	 * "promoted"/"demoted" register fidelity projections.
+	 * "visible"/"summarized" register visibility projections.
 	 * "docs" sets tool documentation.
 	 * Everything else resolves to a hook event.
 	 */
@@ -88,7 +96,7 @@ export default class PluginContext {
 			this.#hooks.tools.onHandle(this.#name, callback, priority);
 			return;
 		}
-		if (event === "promoted" || event === "demoted") {
+		if (event === "visible" || event === "summarized") {
 			this.#hooks.tools.onView(this.#name, callback, event);
 			return;
 		}

package/src/{server → hooks}/RpcRegistry.js

@@ -57,7 +57,8 @@ export default class RpcRegistry {
 				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 || "", {
+				const { body = "" } = params;
+				await dispatchTool(hooks, rummy, name, params.path, body, {
 					path: params.path,
 					to: params.to,
 					...params.attributes,

package/src/hooks/RummyContext.js

@@ -2,17 +2,40 @@
  * RummyContext provides a unified, semantic API for plugins to interact with
  * the Turn node tree and core resources like the Database and Project metadata.
  */
+// Entries write verbs that should automatically carry the caller's
+// writer identity. Handler-issued writes on behalf of the model default
+// to writer=model; plugin background writes (set via rummy from a hook
+// with writer: "plugin" or "system" in ctx) get the context's writer.
+const WRITE_VERBS = new Set(["set", "rm", "cp", "mv", "update"]);
+
+// Defaults applied at construction so every plugin-facing getter
+// returns a predictable shape without per-access fallbacks.
+const CONTEXT_DEFAULTS = Object.freeze({
+	hooks: null,
+	activeFiles: [],
+	sequence: 0,
+	runId: null,
+	turnId: null,
+	loopId: null,
+	toolSet: null,
+	contextSize: null,
+	systemPrompt: "",
+	loopPrompt: "",
+	writer: "model",
+});
+
 export default class RummyContext {
 	#root;
 	#context;
+	#wrappedStore;
 
 	constructor(root, context) {
 		this.#root = root;
-		this.#context = context;
+		this.#context = { ...CONTEXT_DEFAULTS, ...context };
 	}
 
 	get hooks() {
-		return this.#context.hooks || null;
+		return this.#context.hooks;
 	}
 
 	get db() {
@@ -20,7 +43,19 @@ export default class RummyContext {
 	}
 
 	get entries() {
-		return this.#context.store || null;
+		if (this.#wrappedStore) return this.#wrappedStore;
+		const store = this.#context.store;
+		if (!store) return null;
+		const writer = this.writer;
+		this.#wrappedStore = new Proxy(store, {
+			get(target, prop) {
+				const val = target[prop];
+				if (typeof val !== "function") return val;
+				if (!WRITE_VERBS.has(prop)) return val.bind(target);
+				return (args = {}) => val.call(target, { writer, ...args });
+			},
+		});
+		return this.#wrappedStore;
 	}
 
 	get project() {
@@ -28,7 +63,7 @@ export default class RummyContext {
 	}
 
 	get activeFiles() {
-		return this.#context.activeFiles || [];
+		return this.#context.activeFiles;
 	}
 
 	get type() {
@@ -40,19 +75,19 @@ export default class RummyContext {
 	}
 
 	get sequence() {
-		return this.#context.sequence || 0;
+		return this.#context.sequence;
 	}
 
 	get runId() {
-		return this.#context.runId || null;
+		return this.#context.runId;
 	}
 
 	get turnId() {
-		return this.#context.turnId || null;
+		return this.#context.turnId;
 	}
 
 	get loopId() {
-		return this.#context.loopId || null;
+		return this.#context.loopId;
 	}
 
 	get noRepo() {
@@ -67,20 +102,34 @@ export default class RummyContext {
 		return this.#context.noWeb === true;
 	}
 
+	get noProposals() {
+		return this.#context.noProposals === true;
+	}
+
 	get toolSet() {
-		return this.#context.toolSet || null;
+		return this.#context.toolSet;
 	}
 
 	get contextSize() {
-		return this.#context.contextSize || null;
+		return this.#context.contextSize;
 	}
 
 	get systemPrompt() {
-		return this.#context.systemPrompt || "";
+		return this.#context.systemPrompt;
 	}
 
 	get loopPrompt() {
-		return this.#context.loopPrompt || "";
+		return this.#context.loopPrompt;
+	}
+
+	/**
+	 * Writer identity for Entries permission checks. Defaults to
+	 * 'model' — handlers write on behalf of the model's emitted command.
+	 * Non-handler plugin code (streaming callbacks, background emissions)
+	 * passes `writer: 'plugin'` or `'system'` explicitly.
+	 */
+	get writer() {
+		return this.#context.writer;
 	}
 
 	get system() {
@@ -101,51 +150,83 @@ export default class RummyContext {
 
 	// --- Tool methods (same operations the model uses) ---
 
-	async set({ path, body, status = 200, fidelity, attributes } = {}) {
+	async set({
+		path,
+		body = "",
+		state = "resolved",
+		outcome = null,
+		visibility,
+		attributes,
+	} = {}) {
 		if (!path) {
 			path = await this.entries.slugPath(
 				this.runId,
 				"known",
-				body || "",
+				body,
 				attributes?.summary,
 			);
 		}
-		await this.entries.upsert(
-			this.runId,
-			this.sequence,
+		await this.entries.set({
+			runId: this.runId,
+			turn: this.sequence,
 			path,
-			body || "",
-			status,
-			{ fidelity, attributes, loopId: this.loopId },
-		);
+			body,
+			state,
+			outcome,
+			visibility,
+			attributes,
+			loopId: this.loopId,
+		});
 		return path;
 	}
 
 	async get(path) {
-		await this.entries.promoteByPattern(this.runId, path, null, this.sequence);
+		await this.entries.get({
+			runId: this.runId,
+			turn: this.sequence,
+			path: path,
+			bodyFilter: null,
+		});
 	}
 
-	async store(path) {
-		await this.entries.demoteByPattern(this.runId, path, null);
+	async rm(path) {
+		await this.entries.rm({ runId: this.runId, path: path });
 	}
 
-	async rm(path) {
-		await this.entries.remove(this.runId, path);
+	async update(body, { status = 102, attributes = {} } = {}) {
+		return this.entries.update({
+			runId: this.runId,
+			turn: this.sequence,
+			body,
+			status,
+			attributes,
+			loopId: this.loopId,
+		});
 	}
 
 	async mv(from, to) {
 		const body = await this.entries.getBody(this.runId, from);
 		if (body === null) return;
-		await this.entries.upsert(this.runId, this.sequence, to, body, 200, {
+		await this.entries.set({
+			runId: this.runId,
+			turn: this.sequence,
+			path: to,
+			body,
+			state: "resolved",
 			loopId: this.loopId,
 		});
-		await this.entries.remove(this.runId, from);
+		await this.entries.rm({ runId: this.runId, path: from });
 	}
 
 	async cp(from, to) {
 		const body = await this.entries.getBody(this.runId, from);
 		if (body === null) return;
-		await this.entries.upsert(this.runId, this.sequence, to, body, 200, {
+		await this.entries.set({
+			runId: this.runId,
+			turn: this.sequence,
+			path: to,
+			body,
+			state: "resolved",
 			loopId: this.loopId,
 		});
 	}
@@ -160,9 +241,16 @@ export default class RummyContext {
 		return this.entries.getAttributes(this.runId, path);
 	}
 
-	async getStatus(path) {
+	async getState(path) {
 		const row = await this.entries.getState(this.runId, path);
-		return row?.status ?? null;
+		if (!row) return null;
+		return row.state;
+	}
+
+	async getOutcome(path) {
+		const row = await this.entries.getState(this.runId, path);
+		if (!row) return null;
+		return row.outcome;
 	}
 
 	async getEntry(path) {
@@ -171,11 +259,16 @@ export default class RummyContext {
 			path,
 			null,
 		);
-		return results[0] || null;
+		if (results.length === 0) return null;
+		return results[0];
 	}
 
 	async setAttributes(path, attrs) {
-		return this.entries.setAttributes(this.runId, path, attrs);
+		return this.entries.set({
+			runId: this.runId,
+			path: path,
+			attributes: attrs,
+		});
 	}
 
 	async getEntries(pattern, bodyFilter) {
@@ -184,7 +277,13 @@ export default class RummyContext {
 
 	async log(message) {
 		const path = `content://${Date.now()}`;
-		await this.entries.upsert(this.runId, this.sequence, path, message, 200);
+		await this.entries.set({
+			runId: this.runId,
+			turn: this.sequence,
+			path,
+			body: message,
+			state: "resolved",
+		});
 	}
 
 	// --- Node tree methods ---
@@ -194,7 +293,8 @@ export default class RummyContext {
 		const childArray = Array.isArray(children) ? children : [children];
 		for (const child of childArray) {
 			if (typeof child === "string") {
-				node.content = (node.content || "") + child;
+				if (node.content === null) node.content = "";
+				node.content += child;
 			} else if (child && typeof child === "object") {
 				node.children.push(child);
 			}

package/src/hooks/ToolRegistry.js

@@ -1,5 +1,6 @@
 // Tool display order: gather → reason → act → communicate.
 // Position in the list implies priority to the model.
+// `update` is pinned last — it's the turn-closer, not an action.
 const TOOL_ORDER = [
 	"think",
 	"unknown",
@@ -12,18 +13,18 @@ const TOOL_ORDER = [
 	"cp",
 	"mv",
 	"ask_user",
-	"update",
-	"summarize",
 	"search",
 ];
 
 function sortByPriority(names) {
 	return names.toSorted((a, b) => {
+		if (a === "update") return 1;
+		if (b === "update") return -1;
 		const ia = TOOL_ORDER.indexOf(a);
 		const ib = TOOL_ORDER.indexOf(b);
 		if (ia === -1 && ib === -1) return a.localeCompare(b);
 		if (ia === -1) return 1;
-		if (ib === -1) return 1;
+		if (ib === -1) return -1;
 		return ia - ib;
 	});
 }
@@ -39,10 +40,9 @@ export default class ToolRegistry {
 		this.#tools.set(scheme, Object.freeze({}));
 	}
 
-	// Mark a tool as hidden — handler still dispatches if the model emits the
-	// tag, but the tool is excluded from all model-facing tool lists. Used for
-	// legacy/internal schemes (e.g. <known>, <unknown>) we want to retire
-	// without deleting.
+	// Hidden tools dispatch on direct emission but don't appear in any
+	// model-facing tool list. Internal schemes (e.g. <known>, <unknown>)
+	// the model writes via <set path="scheme://..."> instead.
 	markHidden(scheme) {
 		this.#hidden.add(scheme);
 	}
@@ -62,30 +62,35 @@ export default class ToolRegistry {
 		list.sort((a, b) => a.priority - b.priority);
 	}
 
-	onView(scheme, fn, fidelity = "promoted") {
+	onView(scheme, fn, visibility = "visible") {
 		if (!this.#views.has(scheme)) this.#views.set(scheme, new Map());
-		this.#views.get(scheme).set(fidelity, fn);
+		this.#views.get(scheme).set(visibility, fn);
 	}
 
 	async view(scheme, entry) {
-		const fidelityMap = this.#views.get(scheme);
-		if (!fidelityMap) {
+		const visibilityMap = this.#views.get(scheme);
+		if (!visibilityMap) {
 			throw new Error(
 				`No view registered for scheme '${scheme}'. ` +
 					`Every tool must define how its entries appear in the model view.`,
 			);
 		}
 
-		const fidelity = entry.fidelity || "promoted";
-		const fn = fidelityMap.get(fidelity);
+		const visibility =
+			entry.visibility === undefined ? "visible" : entry.visibility;
+		const fn = visibilityMap.get(visibility);
 		if (!fn) return "";
 
-		return fn(entry);
+		const body = await fn(entry);
+		// View handlers MAY return undefined or null to mean "no projected
+		// body at this visibility" — normalize at this boundary so callers
+		// get a predictable string.
+		return body == null ? "" : body;
 	}
 
 	hasView(scheme) {
-		const fidelityMap = this.#views.get(scheme);
-		return fidelityMap?.size > 0;
+		const visibilityMap = this.#views.get(scheme);
+		return visibilityMap?.size > 0;
 	}
 
 	async dispatch(scheme, entry, rummy) {