@possumtech/rummy 0.4.0 → 2.0.0

package/src/plugins/update/updateDoc.js

@@ -1,28 +1,3 @@
-// Tool doc for <update>. Each entry: [text, rationale].
-// Text goes to the model. Rationale stays in source.
-// Changing ANY line requires reading ALL rationales first.
-const LINES = [
-	["## <update>[brief status]</update> - Signal continuation"],
-	[
-		"Example: <update>Reading config files</update>",
-		"Progress checkpoint. Status signal, not a log entry.",
-	],
-	[
-		"Example: <update>Found 3 issues, fixing first</update>",
-		"Multi-step progress. Ongoing work.",
-	],
-	[
-		"* YOU MUST use <update></update> if still working — describes the current state",
-		"Continuation signal. Triggers the next turn.",
-	],
-	[
-		"* YOU MUST NOT use <update> if done — use <summarize/> instead",
-		"Mutual exclusion with summarize.",
-	],
-	[
-		"* YOU MUST keep <update> to <= 80 characters",
-		"Length cap.",
-	],
-];
+import { loadDoc } from "../helpers.js";
 
-export default LINES.map(([text]) => text).join("\n");
+export default loadDoc(import.meta.url, "updateDoc.md");

package/src/plugins/update/updateDoc.md

@@ -0,0 +1,8 @@
+## <update status="N">{brief status}</update> - Status report (exactly one per turn, at the end)
+<!-- Header defines position, frequency, and status code requirement. -->
+
+REQUIRED: the valid values of N are defined by your current stage instructions.
+<!-- Single source of truth for codes is the current phase instructions block, not this doc. Listing codes here leaks termination knowledge (e.g. 200) that strong models use to short-circuit the protocol. -->
+
+REQUIRED: YOU MUST keep <update></update> body to <= 80 characters.
+<!-- Length cap. -->

package/src/plugins/xai/README.md

@@ -0,0 +1,23 @@
+# xai
+
+xAI (Grok) LLM provider. Handles model aliases prefixed with `xai/`
+(e.g. `xai/grok-2`).
+
+## Env
+
+- `XAI_BASE_URL` — full responses endpoint (e.g.
+  `https://api.x.ai/v1/responses`). Plugin is inert if unset.
+- `XAI_API_KEY` — bearer token.
+
+## Response Normalization
+
+xAI's response shape differs from OpenAI's. The plugin walks
+`data.output[]`, collecting text from items of type `message` as
+`content` and items of type `reasoning` as `reasoning_content`, then
+emits the common OpenAI-shaped envelope.
+
+## Context Size
+
+Tries `/models` first for a `context_length` field, then the
+`/language-models/<id>` endpoint as a fallback. Results are cached
+per model for the plugin lifetime.

package/src/{llm/XaiClient.js → plugins/xai/xai.js}

@@ -1,24 +1,46 @@
-import msg from "../agent/messages.js";
+import msg from "../../agent/messages.js";
 
-export default class XaiClient {
+const FETCH_TIMEOUT = Number(process.env.RUMMY_FETCH_TIMEOUT);
+if (!FETCH_TIMEOUT) throw new Error("RUMMY_FETCH_TIMEOUT must be set");
+
+const PROVIDER = "xai";
+
+/**
+ * xAI (Grok) LLM provider plugin. Registers with hooks.llm.providers if
+ * XAI_BASE_URL is set; inert otherwise. Handles model aliases of the
+ * form `xai/{modelName}`. Normalizes xAI's distinct response shape
+ * into the common OpenAI-shaped envelope.
+ */
+export default class Xai {
 	#baseUrl;
 	#apiKey;
 	#contextCache = new Map();
 
-	constructor(baseUrl, apiKey) {
+	constructor(core) {
+		const baseUrl = process.env.XAI_BASE_URL;
+		if (!baseUrl) return;
 		this.#baseUrl = baseUrl;
-		this.#apiKey = apiKey;
+		this.#apiKey = process.env.XAI_API_KEY;
+
+		const wireModel = (alias) => alias.split("/").slice(1).join("/");
+
+		core.hooks.llm.providers.push({
+			name: PROVIDER,
+			matches: (model) => model.split("/")[0] === PROVIDER,
+			completion: (messages, model, options) =>
+				this.#completion(messages, wireModel(model), options),
+			getContextSize: (model) => this.#getContextSize(wireModel(model)),
+		});
 	}
 
-	async completion(messages, model, options = {}) {
+	async #completion(messages, model, options = {}) {
 		if (!this.#apiKey) throw new Error(msg("error.xai_api_key_missing"));
 
 		const body = { model, input: messages };
 		if (options.temperature !== undefined)
 			body.temperature = options.temperature;
 
-		const timeout = Number(process.env.RUMMY_FETCH_TIMEOUT) || 30_000;
-		const timeoutSignal = AbortSignal.timeout(timeout);
+		const timeoutSignal = AbortSignal.timeout(FETCH_TIMEOUT);
 		const signal = options.signal
 			? AbortSignal.any([options.signal, timeoutSignal])
 			: timeoutSignal;
@@ -37,29 +59,22 @@ export default class XaiClient {
 			const error = await response.text();
 			if (response.status === 401 || response.status === 403) {
 				throw new Error(
-					msg("error.xai_auth", {
-						status: `${response.status} - ${error}`,
-					}),
+					msg("error.xai_auth", { status: `${response.status} - ${error}` }),
 				);
 			}
 			throw new Error(
-				msg("error.xai_api", {
-					status: `${response.status} - ${error}`,
-				}),
+				msg("error.xai_api", { status: `${response.status} - ${error}` }),
 			);
 		}
 
-		const data = await response.json();
-		return this.#normalize(data);
+		return this.#normalize(await response.json());
 	}
 
 	#normalize(data) {
-		const output = data.output || [];
-
 		let content = "";
 		let reasoningContent = null;
 
-		for (const item of output) {
+		for (const item of data.output) {
 			if (item.type === "reasoning") {
 				const text = this.#extractText(item.content);
 				if (text)
@@ -73,9 +88,13 @@ export default class XaiClient {
 			}
 		}
 
-		const usage = data.usage || {};
-		const inputTokens = usage.input_tokens || 0;
-		const outputTokens = usage.output_tokens || 0;
+		const { usage } = data;
+		const inputTokens = usage.input_tokens;
+		const outputTokens = usage.output_tokens;
+		// Optional per xAI API; absent on providers that don't surface them.
+		const cached = usage.input_tokens_details?.cached_tokens;
+		const reasoningTokens = usage.output_tokens_details?.reasoning_tokens;
+		const costTicks = usage.cost_in_usd_ticks;
 		return {
 			choices: [
 				{
@@ -88,11 +107,11 @@ export default class XaiClient {
 			],
 			usage: {
 				prompt_tokens: inputTokens,
-				cached_tokens: usage.input_tokens_details?.cached_tokens || 0,
+				cached_tokens: cached === undefined ? 0 : cached,
 				completion_tokens: outputTokens,
-				reasoning_tokens: usage.output_tokens_details?.reasoning_tokens || 0,
+				reasoning_tokens: reasoningTokens === undefined ? 0 : reasoningTokens,
 				total_tokens: inputTokens + outputTokens,
-				cost: (usage.cost_in_usd_ticks || 0) / 10_000_000_000,
+				cost: costTicks === undefined ? 0 : costTicks / 10_000_000_000,
 			},
 		};
 	}
@@ -100,29 +119,30 @@ export default class XaiClient {
 	#extractText(content) {
 		if (typeof content === "string") return content;
 		if (!Array.isArray(content)) return null;
-		return (
-			content
-				.filter((c) => c.type === "text" || c.type === "output_text")
-				.map((c) => c.text)
-				.join("\n") || null
-		);
+		const joined = content
+			.filter((c) => c.type === "text" || c.type === "output_text")
+			.map((c) => c.text)
+			.join("\n");
+		return joined ? joined : null;
 	}
 
-	async getContextSize(model) {
+	async #getContextSize(model) {
 		if (this.#contextCache.has(model)) return this.#contextCache.get(model);
-
 		if (!this.#apiKey) throw new Error(msg("error.xai_api_key_missing"));
 
-		// Query xAI models endpoint
 		const modelsUrl = this.#baseUrl.replace(/\/responses$/, "/models");
 		const res = await fetch(modelsUrl, {
 			headers: { Authorization: `Bearer ${this.#apiKey}` },
 			signal: AbortSignal.timeout(5000),
 		});
-
 		if (res.ok) {
 			const data = await res.json();
-			const models = data.data || data.models || [];
+			// xAI's /models returns either { data: [...] } or { models: [...] }
+			// depending on the API version; accept either and crash otherwise.
+			let models;
+			if (data.data) models = data.data;
+			else if (data.models) models = data.models;
+			else throw new Error("xAI /models response has neither data nor models");
 			const entry = models.find(
 				(m) => m.id === model || `${m.id}-latest` === model,
 			);
@@ -132,16 +152,17 @@ export default class XaiClient {
 			}
 		}
 
-		// Try /v1/language-models for richer metadata
 		const langUrl = this.#baseUrl.replace(
 			/\/responses$/,
 			`/language-models/${model}`,
 		);
+		// Optional endpoint probe. If the network call fails (404 on older
+		// API versions, timeout, etc.) we fall through to the next strategy
+		// below; a terminal throw fires if no strategy resolves.
 		const langRes = await fetch(langUrl, {
 			headers: { Authorization: `Bearer ${this.#apiKey}` },
 			signal: AbortSignal.timeout(5000),
 		}).catch(() => null);
-
 		if (langRes?.ok) {
 			const langData = await langRes.json();
 			if (langData?.context_length) {

package/src/server/ClientConnection.js

@@ -8,6 +8,7 @@ export default class ClientConnection {
 	#hooks;
 	#rpcRegistry;
 	#rpcLogPending = new Map();
+	#shutdownPromise = null;
 	#context = {
 		projectId: null,
 		projectRoot: null,
@@ -21,7 +22,13 @@ export default class ClientConnection {
 		this.#projectAgent = new ProjectAgent(db, hooks);
 
 		this.#ws.on("message", (data) => this.#handleMessage(data));
-		this.#ws.on("close", () => this.#teardown());
+		this.#ws.on("close", () => {
+			// Fire-and-forget: the Promise is cached by `shutdown()` so
+			// server-initiated close can await the same work.
+			this.shutdown().catch((err) => {
+				console.warn(`[RUMMY] shutdown on ws close failed: ${err.message}`);
+			});
+		});
 
 		this.#setupNotifications();
 	}
@@ -63,6 +70,16 @@ export default class ClientConnection {
 		}
 	};
 
+	#onStreamCancelled = (payload) => {
+		if (payload.projectId === this.#context.projectId) {
+			this.#sendNotification("stream/cancelled", {
+				run: payload.run,
+				path: payload.path,
+				reason: payload.reason,
+			});
+		}
+	};
+
 	#onState = (payload) => {
 		if (payload.projectId === this.#context.projectId) {
 			this.#sendNotification("run/state", {
@@ -79,18 +96,37 @@ export default class ClientConnection {
 
 	#setupNotifications() {
 		this.#hooks.run.progress.on(this.#onProgress);
-		this.#hooks.turn.proposal.on(this.#onProposal);
+		this.#hooks.proposal.pending.on(this.#onProposal);
 		this.#hooks.ui.render.on(this.#onRender);
 		this.#hooks.ui.notify.on(this.#onNotify);
 		this.#hooks.run.state.on(this.#onState);
+		this.#hooks.stream.cancelled.on(this.#onStreamCancelled);
 	}
 
 	#teardown() {
 		this.#hooks.run.progress.off(this.#onProgress);
-		this.#hooks.turn.proposal.off(this.#onProposal);
+		this.#hooks.proposal.pending.off(this.#onProposal);
 		this.#hooks.ui.render.off(this.#onRender);
 		this.#hooks.ui.notify.off(this.#onNotify);
 		this.#hooks.run.state.off(this.#onState);
+		this.#hooks.stream.cancelled.off(this.#onStreamCancelled);
+	}
+
+	/**
+	 * Abort in-flight runs on this connection and wait for them to
+	 * settle. Idempotent: `ws.on("close")` and server-initiated close
+	 * both call this; the cached Promise guarantees the work happens
+	 * exactly once and both callers observe the same completion.
+	 */
+	shutdown() {
+		if (!this.#shutdownPromise) {
+			this.#shutdownPromise = (async () => {
+				await this.#projectAgent.shutdown();
+				this.#teardown();
+				if (this.#ws.readyState === 1) this.#ws.terminate();
+			})();
+		}
+		return this.#shutdownPromise;
 	}
 
 	#buildHandlerContext() {
@@ -113,11 +149,8 @@ export default class ClientConnection {
 
 	async #handleMessage(data) {
 		let id = null;
-		const debug = process.env.RUMMY_DEBUG === "true";
 		try {
 			const rawMessage = await this.#hooks.socket.message.raw.filter(data);
-			if (debug) console.log(`[SOCKET] IN: ${rawMessage.toString()}`);
-
 			const message = JSON.parse(rawMessage.toString());
 
 			const filteredRequest = await this.#hooks.rpc.request.filter(message);
@@ -131,15 +164,13 @@ export default class ClientConnection {
 				projectId: this.#context.projectId,
 			});
 
-			try {
-				const logRow = await this.#db.log_rpc_call.get({
-					project_id: this.#context.projectId ?? null,
-					method,
-					rpc_id: id,
-					params: params ? JSON.stringify(params) : null,
-				});
-				if (logRow) this.#rpcLogPending.set(id, logRow.id);
-			} catch {}
+			const logRow = await this.#db.log_rpc_call.get({
+				project_id: this.#context.projectId,
+				method,
+				rpc_id: id,
+				params: params ? JSON.stringify(params) : null,
+			});
+			if (logRow) this.#rpcLogPending.set(id, logRow.id);
 
 			const resolvedMethod = method === "rpc/discover" ? "discover" : method;
 			const registration = this.#rpcRegistry.get(resolvedMethod);
@@ -150,17 +181,19 @@ export default class ClientConnection {
 				throw new Error(msg("error.not_initialized"));
 			}
 
+			// JSON-RPC requests may omit `params` entirely.
+			const handlerParams = params === undefined ? {} : params;
 			let result;
 			if (registration.longRunning) {
 				result = await registration.handler(
-					params || {},
+					handlerParams,
 					this.#buildHandlerContext(),
 				);
 			} else {
-				const timeout = Number(process.env.RUMMY_RPC_TIMEOUT) || 10_000;
+				const timeout = Number(process.env.RUMMY_RPC_TIMEOUT);
 				let timer;
 				result = await Promise.race([
-					registration.handler(params || {}, this.#buildHandlerContext()),
+					registration.handler(handlerParams, this.#buildHandlerContext()),
 					new Promise((_, reject) => {
 						timer = setTimeout(
 							() =>
@@ -198,43 +231,37 @@ export default class ClientConnection {
 			const logId = this.#rpcLogPending.get(id);
 			if (logId) {
 				this.#rpcLogPending.delete(id);
-				try {
-					await this.#db.log_rpc_result.run({
-						id: logId,
-						result: finalResult
-							? JSON.stringify(finalResult).slice(0, 4096)
-							: null,
-					});
-				} catch {}
+				await this.#db.log_rpc_result.run({
+					id: logId,
+					result: finalResult
+						? JSON.stringify(finalResult).slice(0, 4096)
+						: null,
+				});
 			}
 		} catch (error) {
 			console.error(`[RUMMY] RPC Error: ${error.message}`);
 			console.error(`[RUMMY] Stack: ${error.stack}`);
+			// JSON-RPC: error responses for malformed requests with no id
+			// MUST carry null per the spec.
 			this.#send({
 				jsonrpc: "2.0",
 				error: { code: -32603, message: error.message },
-				id: id || null,
+				id: id === undefined ? null : id,
 			});
 			await this.#hooks.rpc.error.emit({ id, error });
 
 			const errLogId = this.#rpcLogPending.get(id);
 			if (errLogId) {
 				this.#rpcLogPending.delete(id);
-				try {
-					await this.#db.log_rpc_error.run({
-						id: errLogId,
-						error: error.message,
-					});
-				} catch {}
+				await this.#db.log_rpc_error.run({
+					id: errLogId,
+					error: error.message,
+				});
 			}
 		}
 	}
 
 	#send(payload) {
-		const debug = process.env.RUMMY_DEBUG === "true";
-		if (debug) {
-			console.log(`[SOCKET] OUT: ${JSON.stringify(payload, null, 2)}`);
-		}
 		if (this.#ws.readyState === 1) {
 			this.#ws.send(JSON.stringify(payload));
 		}

package/src/server/SocketServer.js

@@ -5,17 +5,23 @@ export default class SocketServer {
 	#db;
 	#wss;
 	#hooks;
+	#connections = new Set();
 
 	constructor(db, options) {
 		this.#db = db;
 		this.#hooks = options.hooks;
 		this.#wss = new WebSocketServer(options);
 
-		this.#wss.on("connection", (ws, req) => {
-			if (process.env.RUMMY_DEBUG === "true") {
-				console.log(`[SOCKET] New connection from ${req.socket.remoteAddress}`);
-			}
-			new ClientConnection(ws, this.#db, this.#hooks);
+		this.#wss.on("connection", (ws, _req) => {
+			const conn = new ClientConnection(ws, this.#db, this.#hooks);
+			this.#connections.add(conn);
+			// Remove from the tracking set only after the connection's
+			// shutdown drain has fully settled — not on raw ws-close —
+			// so server close() can still find and await an in-progress
+			// shutdown kicked off by a client-initiated disconnect.
+			ws.on("close", () => {
+				conn.shutdown().finally(() => this.#connections.delete(conn));
+			});
 		});
 
 		this.#wss.on("error", (_err) => {
@@ -31,12 +37,19 @@ export default class SocketServer {
 		this.#wss.on(event, handler);
 	}
 
-	close() {
-		return new Promise((resolve) => {
+	async close() {
+		// Drain in-flight runs on each connection before closing the
+		// socket — otherwise detached kickoff Promises keep the Node
+		// event loop alive past server shutdown.
+		const shutdowns = [];
+		for (const conn of this.#connections) {
+			shutdowns.push(conn.shutdown().catch(() => {}));
+		}
+		await Promise.all(shutdowns);
+		this.#connections.clear();
+
+		await new Promise((resolve) => {
 			if (!this.#wss) return resolve();
-			for (const client of this.#wss.clients) {
-				client.terminate();
-			}
 			this.#wss.close(resolve);
 		});
 	}

package/src/server/protocol.js

@@ -0,0 +1,11 @@
+/**
+ * Server↔client wire-protocol version. Bumped whenever the RPC shape
+ * or notification payload shape changes in a way that breaks existing
+ * clients. Clients pass their own version in `rummy/hello`; server
+ * rejects MAJOR mismatch. Git commit log is the changelog.
+ *
+ *   MAJOR — breaking change (removed/renamed method, shape change)
+ *   MINOR — additive change (new method, new optional field)
+ *   PATCH — internal fix visible to the wire shape
+ */
+export const RUMMY_PROTOCOL_VERSION = "2.0.0";

package/src/sql/functions/slugify.js

@@ -1,6 +1,18 @@
 export const deterministic = true;
 
+// Build URI paths the model can round-trip:
+//   "history,mongol,khan"   → "history/mongol/khan"   (commas become path separators)
+//   "contents of Document 1" → "contents_of_Document_1" (spaces become underscores)
+// Slice on decoded text, then split-encode-join per segment so / survives as
+// a separator while anything URL-unsafe inside a segment gets escaped.
 export default function slugify(text) {
 	if (!text) return "";
-	return encodeURIComponent(text).slice(0, 80);
+	return text
+		.slice(0, 80)
+		.replace(/,/g, "/")
+		.replace(/ /g, "_")
+		.split("/")
+		.filter(Boolean)
+		.map(encodeURIComponent)
+		.join("/");
 }

package/src/sql/v_model_context.sql

@@ -3,30 +3,26 @@ CREATE VIEW IF NOT EXISTS v_model_context AS
 WITH
 visible AS (
 	SELECT
-		ke.run_id
-		, ke.id
-		, ke.path
-		, ke.body
-		, ke.scheme
-		, ke.status
-		, ke.fidelity
-		, ke.turn
-		, ke.updated_at
-		, ke.attributes
-		, ke.tokens
+		rv.run_id
+		, rv.id
+		, e.path
+		, e.body
+		, e.scheme
+		, rv.state
+		, rv.outcome
+		, rv.visibility
+		, rv.turn
+		, rv.updated_at
+		, e.attributes
 		, COALESCE(s.category, 'logging') AS category
 		, CASE
-			-- Archived entries not in context
-			WHEN ke.fidelity = 'archive' THEN NULL
-			-- 202 Accepted (proposed) hidden until resolved
-			WHEN ke.status = 202 THEN NULL
-			-- Audit schemes (model_visible = 0) hidden
+			WHEN rv.visibility = 'archived' THEN NULL
 			WHEN s.model_visible = 0 THEN NULL
-			-- Everything else visible at its fidelity
-			ELSE ke.fidelity
-		END AS visible_fidelity
-	FROM known_entries AS ke
-	JOIN schemes AS s ON s.name = COALESCE(ke.scheme, 'file')
+			ELSE rv.visibility
+		END AS effective_visibility
+	FROM run_views AS rv
+	JOIN entries AS e ON e.id = rv.entry_id
+	JOIN schemes AS s ON s.name = COALESCE(e.scheme, 'file')
 ),
 projected AS (
 	SELECT
@@ -34,27 +30,28 @@ projected AS (
 		, id
 		, path
 		, scheme
-		, status
-		, visible_fidelity AS fidelity
+		, state
+		, outcome
+		, effective_visibility AS visibility
 		, turn
 		, updated_at
 		, attributes
 		-- Category comes from schemes table — plugins declare it via registerScheme().
 		, category
-		, tokens
 		, CASE
-			WHEN visible_fidelity IN ('full', 'summary') THEN body
+			WHEN effective_visibility IN ('visible', 'summarized') THEN body
 			ELSE ''
 		END AS body
 	FROM visible
-	WHERE visible_fidelity IS NOT NULL
+	WHERE effective_visibility IS NOT NULL
 )
 SELECT
 	run_id
 	, path
 	, scheme
-	, fidelity
-	, status
+	, visibility
+	, state
+	, outcome
 	, body
 	, attributes
 	, category
@@ -71,13 +68,12 @@ SELECT
 				ELSE 5
 			END
 			, CASE scheme WHEN 'skill' THEN 0 ELSE 1 END
-			, CASE fidelity
-				WHEN 'summary' THEN 0
+			, CASE visibility
+				WHEN 'summarized' THEN 0
 				ELSE 1
 			END
 			, turn
 			, updated_at
 			, id
 	) AS ordinal
-	, countTokens(body) AS tokens
 FROM projected;

package/src/sql/v_run_log.sql

@@ -4,20 +4,15 @@ SELECT
 	ke.run_id
 	, ke.path
 	, ke.body
-	, ke.status
-	, COALESCE(ke.scheme, 'file') AS tool
-	, COALESCE(
-		json_extract(ke.attributes, '$.command')
-		, json_extract(ke.attributes, '$.file')
-		, json_extract(ke.attributes, '$.path')
-		, json_extract(ke.attributes, '$.question')
-		, ''
-	) AS target
+	, ke.state
+	, ke.outcome
+	, ke.turn
+	, ke.scheme AS tool
+	, ke.attributes
 FROM known_entries AS ke
-JOIN schemes AS s ON s.name = COALESCE(ke.scheme, 'file')
+JOIN schemes AS s ON s.name = ke.scheme
 WHERE
-	ke.scheme IS NOT NULL
-	AND ke.status != 202
-	AND s.category NOT IN ('knowledge', 'file')
-	AND ke.scheme NOT IN ('system', 'reasoning', 'model', 'content')
+	s.category IN ('logging', 'prompt', 'unknown')
+	AND ke.state != 'proposed'
+	AND ke.scheme != 'run'
 ORDER BY ke.id;