@possumtech/rummy 2.0.1 → 2.2.0

package/src/plugins/rpc/rpc.js

@@ -2,7 +2,7 @@ import msg from "../../agent/messages.js";
 import RummyContext from "../../hooks/RummyContext.js";
 import File from "../file/file.js";
 
-const CONSTRAINT_VISIBILITIES = new Set(["active", "readonly", "ignore"]);
+const CONSTRAINT_VISIBILITIES = new Set(["add", "readonly", "ignore"]);
 
 export default class Rpc {
 	#core;
@@ -24,10 +24,7 @@ export default class Rpc {
 			description: "Returns { methods, notifications } catalog.",
 		});
 
-		// --- Primitives (SPEC primitives) ---
-		// The client surface is a thin projection of the plugin API.
-		// Six verbs, each takes an object of entry-grammar params.
-		// Writer is fixed to "client"; permissions enforced per scheme.
+		// Primitives (SPEC #primitives); writer fixed to "client".
 
 		r.register("set", {
 			handler: async (params, ctx) => {
@@ -139,8 +136,9 @@ export default class Rpc {
 				return { ok: true, path };
 			},
 			description:
-				"Write an update:// entry carrying a turn's continuation/terminal " +
-				"signal. Not general — this is the lifecycle verb.",
+				"Write a status update at log://turn_N/update/<slug> carrying a " +
+				"turn's continuation/terminal signal. Not general — this is the " +
+				"lifecycle verb.",
 			params: {
 				run: "string — run alias",
 				body: "string — update text",
@@ -151,9 +149,7 @@ export default class Rpc {
 			requiresInit: true,
 		});
 
-		// Connection handshake. First call a client makes. Establishes
-		// the project identity for this connection and announces the
-		// server's protocol version.
+		// Connection handshake; project identity + protocol version.
 		r.register("rummy/hello", {
 			handler: async (params, ctx) => {
 				const { RUMMY_PROTOCOL_VERSION } = await import(
@@ -265,11 +261,11 @@ export default class Rpc {
 			},
 			description:
 				"Set a project-level file constraint. Visibility ∈ " +
-				"{active, readonly, ignore}. Patterns can be globs. " +
+				"{add, readonly, ignore}. Patterns can be globs. " +
 				"Persists across runs; overlays git defaults.",
 			params: {
 				pattern: "string — file path or glob",
-				visibility: "string — active | readonly | ignore",
+				visibility: "string — add | readonly | ignore",
 			},
 			requiresInit: true,
 		});
@@ -311,11 +307,18 @@ export default class Rpc {
 		r.register("getEntries", {
 			handler: async (params, ctx) => {
 				const runRow = await this.#resolveRun(params.run, ctx);
-				const { pattern = "*", bodyFilter = null } = params;
+				const {
+					pattern = "*",
+					bodyFilter = null,
+					since = null,
+					limit = null,
+					withBody = false,
+				} = params;
 				const rows = await ctx.projectAgent.entries.getEntriesByPattern(
 					runRow.id,
 					pattern,
 					bodyFilter,
+					{ since, limit },
 				);
 				return rows
 					.filter((e) => !params.scheme || e.scheme === params.scheme)
@@ -323,30 +326,43 @@ export default class Rpc {
 					.filter(
 						(e) => !params.visibility || e.visibility === params.visibility,
 					)
-					.map((e) => ({
-						path: e.path,
-						scheme: e.scheme,
-						state: e.state,
-						outcome: e.outcome,
-						visibility: e.visibility,
-						turn: e.turn,
-						tokens: e.tokens,
-						attributes:
-							typeof e.attributes === "string"
-								? JSON.parse(e.attributes)
-								: e.attributes,
-					}));
+					.map((e) => {
+						const row = {
+							id: e.id,
+							path: e.path,
+							scheme: e.scheme,
+							state: e.state,
+							outcome: e.outcome,
+							visibility: e.visibility,
+							turn: e.turn,
+							tokens: e.tokens,
+							attributes:
+								typeof e.attributes === "string"
+									? JSON.parse(e.attributes)
+									: e.attributes,
+						};
+						if (withBody) row.body = e.body;
+						return row;
+					});
 			},
 			description:
 				"List entries matching a pattern. Read-only — no promotion. " +
-				"Optional filters: scheme, state, visibility, bodyFilter.",
+				"Optional filters: scheme, state, visibility, bodyFilter. " +
+				"Pass `withBody: true` to include `body` on each row (omitted by default to keep pulse-reconcile traffic lean). " +
+				"For incremental sync after a `run/changed` pulse, pass `since` (last seen entry id); " +
+				"use `limit` to chunk catch-up.",
 			params: {
 				run: "string — run alias",
 				pattern: "string? — glob pattern (default '*')",
 				scheme: "string? — filter by scheme (e.g. 'file')",
 				state: "string? — filter by state",
 				visibility: "string? — filter by visibility",
-				bodyFilter: "string? — narrow pattern matches by body content",
+				bodyFilter:
+					"string? — filter rows by content of body (substring/glob; NOT for body inclusion — see withBody)",
+				withBody:
+					"boolean? — include `body` field on each returned row (default false)",
+				since: "number? — only entries with id > since (insertion-ordered)",
+				limit: "number? — cap result count",
 			},
 			requiresInit: true,
 		});
@@ -436,9 +452,10 @@ export default class Rpc {
 
 		// --- Notifications ---
 
-		r.registerNotification("run/state", "Turn state update.");
-		r.registerNotification("run/progress", "Turn status.");
-		r.registerNotification("run/proposal", "Proposal awaiting resolution.");
+		r.registerNotification(
+			"run/changed",
+			"Pulse: an entry under this run changed. Query with `getEntries(run, { pattern, since })` to reconcile.",
+		);
 		r.registerNotification(
 			"stream/cancelled",
 			"Server-initiated stream cancellation.",
@@ -446,8 +463,7 @@ export default class Rpc {
 		r.registerNotification("ui/render", "Streaming output.");
 		r.registerNotification("ui/notify", "Toast notification.");
 
-		// Auto-dispatch: any registered tool is callable via RPC.
-		// Checked at request time — no timing dependency on plugin load order.
+		// Any registered tool is callable via RPC; resolved at request time.
 		r.setToolFallback(hooks, buildRunContext, dispatchTool);
 	}
 
@@ -464,18 +480,14 @@ export default class Rpc {
 	async #dispatchSet(params, ctx) {
 		if (!params.path) throw new Error("set: path is required");
 
-		// run:// is the lifecycle surface. A set to a brand-new run://
-		// alias starts a run loop; a state transition cancels or resolves.
+		// run:// = lifecycle surface (start run, cancel, resolve).
 		if (params.path.startsWith("run://")) {
 			return await this.#dispatchRunSet(params, ctx);
 		}
 
 		const runRow = await this.#resolveRun(params.run, ctx);
 
-		// State transition on an existing proposed entry → route through
-		// AgentLoop.resolve, which applies scheme-specific side effects
-		// (patch application for set://, file removal for rm://, stream
-		// setup for sh:// / env://, etc.).
+		// State transitions on proposed entries → AgentLoop.resolve for scheme-specific effects.
 		if (params.state && !params.append && !params.pattern) {
 			const current = await ctx.projectAgent.entries.getState(
 				runRow.id,
@@ -521,10 +533,7 @@ export default class Rpc {
 	async #dispatchRunSet(params, ctx) {
 		let alias = params.path.slice("run://".length);
 
-		// Empty alias on a new-run set → synthesize ${model}_${epoch}.
-		// Matches AgentLoop.#generateAlias so server- and client-initiated
-		// runs share one naming scheme. Clients that want a specific name
-		// pass it in the path; anonymous starts get the synthesized one.
+		// Empty alias → ${model}_${epoch}; mirrors AgentLoop.#generateAlias.
 		if (!alias) {
 			const { attributes: attrs = {} } = params;
 			if (!attrs.model) {
@@ -580,9 +589,7 @@ export default class Rpc {
 				fork: attrs.fork,
 			};
 			const { body = "" } = params;
-			// Fire-and-forget: client watches state via entry notifications.
-			// ProjectAgent exposes .ask/.act wrappers over AgentLoop#run; route
-			// by mode rather than calling the private loop directly.
+			// Fire-and-forget; client watches state via entry notifications.
 			const kickoff =
 				mode === "act"
 					? ctx.projectAgent.act(
@@ -605,10 +612,7 @@ export default class Rpc {
 			return { ok: true, alias };
 		}
 
-		// Existing run + fork=true: create a child run synchronously so we
-		// can return the child alias, then kick off the loop against it.
-		// fork needs a brand-new run row with parent_run_id set; inject()
-		// would just add another prompt to the parent.
+		// fork=true → new child run with parent_run_id; inject() would only add a prompt to parent.
 		const attrs = params.attributes ? params.attributes : {};
 		if (attrs.fork === true) {
 			const { mode } = attrs;

package/src/plugins/set/README.md

@@ -15,7 +15,7 @@ SEARCH/REPLACE edits, and pattern updates.
 - **Category**: `logging`
 - **Handler**: Routes based on attributes:
   - `blocks` or `search` — SEARCH/REPLACE edit via `processEdit`.
-  - `preview` — pattern preview (dry run).
+  - `manifest` — pattern manifest (lists matches without performing the set).
   - Scheme path — direct upsert at status 200.
   - File path — produces status 202 (proposed) with unified diff patch.
   - Glob/filter — bulk update via `updateBodyByPattern`.
@@ -31,3 +31,7 @@ the merge conflict block when a SEARCH/REPLACE was performed.
 - **Heuristic fallback**: On literal failure, fuzzy matching with warnings.
 - **Patch generation**: `generatePatch` produces unified diff for client display.
 - File writes are always status 202 (proposed); scheme writes resolve immediately.
+- **`proposal.content` filter** — when the client accepts a proposed
+  set, this plugin overrides the resolved body to the body it
+  already staged on the audit entry (rather than whatever literal
+  body the client passed through `resolve`).