@possumtech/rummy 0.5.0 → 2.0.1

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/plugins/yolo/yolo.js

@@ -0,0 +1,192 @@
+import { spawn } from "node:child_process";
+import { logPathToDataBase } from "../helpers.js";
+
+const SH_PATH_RE = /^log:\/\/turn_\d+\/(sh|env)\//;
+
+/**
+ * YOLO plugin — for runs started with `yolo: true`, auto-resolves every
+ * proposal server-side and spawns sh/env commands locally, streaming
+ * output to the same data-channel entries the existing `stream`/
+ * `stream/completed` RPC contract uses.
+ *
+ * Pattern parallel to `noRepo`/`noWeb`/`noInteraction`/`noProposals`:
+ * `yolo` is a run attribute plumbed via rpc.js → AgentLoop loop config →
+ * RummyContext.yolo. This plugin reads `rummy.yolo` off the proposal
+ * payload and engages only when set; non-yolo runs are unaffected.
+ *
+ * The plugin replicates AgentLoop.resolve()'s accept path inline rather
+ * than calling an exposed projectAgent — keeps yolo logic contained in
+ * the yolo plugin and out of backbone files.
+ */
+export default class Yolo {
+	constructor(core) {
+		this.core = core;
+		core.hooks.proposal.pending.on(this.#onPending.bind(this));
+	}
+
+	async #onPending({ run, proposed, rummy }) {
+		if (!rummy?.yolo) return;
+		for (const p of proposed) {
+			// Resolve first — that fires proposal.accepted, which lets the
+			// sh/env plugin seed the streaming channel entries. Then spawn
+			// into those existing channels. If we spawned first, sh.js's
+			// post-accept channel creation would clobber the body we just
+			// streamed (sets state=streaming, body="").
+			await this.#serverResolve(rummy, p.path);
+			if (SH_PATH_RE.test(p.path)) {
+				await this.#executeShellProposal(rummy, p.path);
+			}
+		}
+	}
+
+	/**
+	 * Replicate AgentLoop.resolve()'s accept path: accepting filter
+	 * (veto check), content filter (resolved body), set state="resolved",
+	 * emit proposal.accepted for plugin side effects.
+	 */
+	async #serverResolve(rummy, path) {
+		const runId = rummy.runId;
+		const entries = rummy.entries;
+		const db = rummy.db;
+		const runRow = await db.get_run_by_id.get({ id: runId });
+		const project = await db.get_project_by_id.get({ id: runRow.project_id });
+		const attrs = await entries.getAttributes(runId, path);
+		const ctx = {
+			runId,
+			runRow,
+			projectId: runRow.project_id,
+			projectRoot: project?.project_root,
+			path,
+			attrs,
+			output: "",
+			db,
+			entries,
+		};
+
+		const veto = await this.core.hooks.proposal.accepting.filter(null, ctx);
+		if (veto?.allow === false) {
+			await entries.set({
+				runId,
+				path,
+				state: "failed",
+				outcome: veto.outcome,
+				body: veto.body,
+			});
+			return;
+		}
+
+		const resolvedBody = await this.core.hooks.proposal.content.filter("", ctx);
+		const existing = await entries.getState(runId, path);
+		const existingTurn = existing?.turn === undefined ? 0 : existing.turn;
+		await entries.set({
+			runId,
+			turn: existingTurn,
+			path,
+			state: "resolved",
+			body: resolvedBody,
+		});
+		await this.core.hooks.proposal.accepted.emit({ ...ctx, resolvedBody });
+	}
+
+	/**
+	 * Spawn the sh/env command locally and stream stdout/stderr into
+	 * `{dataBase}_1` and `{dataBase}_2` data entries. Mirrors the
+	 * stream/stream-completed RPC contract — same channel layout, same
+	 * terminal-state transitions on exit. Done inline (no RPC roundtrip)
+	 * so the run is fully autonomous.
+	 */
+	async #executeShellProposal(rummy, logPath) {
+		const runId = rummy.runId;
+		const entries = rummy.entries;
+		const db = rummy.db;
+		const runRow = await db.get_run_by_id.get({ id: runId });
+		const project = await db.get_project_by_id.get({ id: runRow.project_id });
+		const projectRoot = project?.project_root;
+		if (!projectRoot) return;
+
+		const attrs = await entries.getAttributes(runId, logPath);
+		const command = attrs?.command || attrs?.summary;
+		if (!command) return;
+
+		const dataBase = logPathToDataBase(logPath);
+		if (!dataBase) return;
+		const stdoutPath = `${dataBase}_1`;
+		const stderrPath = `${dataBase}_2`;
+
+		const start = Date.now();
+		const child = spawn("bash", ["-lc", command], {
+			cwd: projectRoot,
+			env: process.env,
+		});
+		// Buffer chunks synchronously and write once after exit. Avoids
+		// the race where multiple async appends interleave with the
+		// terminal-state transition fired on 'close'.
+		const stdoutChunks = [];
+		const stderrChunks = [];
+		child.stdout.on("data", (data) => stdoutChunks.push(data.toString()));
+		child.stderr.on("data", (data) => stderrChunks.push(data.toString()));
+
+		await new Promise((resolve) => {
+			child.on("close", async (code) => {
+				const stdoutBody = stdoutChunks.join("");
+				const stderrBody = stderrChunks.join("");
+				if (stdoutBody) {
+					try {
+						await entries.set({
+							runId,
+							path: stdoutPath,
+							body: stdoutBody,
+							append: true,
+						});
+					} catch {}
+				}
+				if (stderrBody) {
+					try {
+						await entries.set({
+							runId,
+							path: stderrPath,
+							body: stderrBody,
+							append: true,
+						});
+					} catch {}
+				}
+				const exitCode = code === null ? 130 : code;
+				const duration = `${Math.round((Date.now() - start) / 1000)}s`;
+				const terminalState = exitCode === 0 ? "resolved" : "failed";
+				const outcome = exitCode === 0 ? null : `exit:${exitCode}`;
+				// Transition state without touching body — getState doesn't
+				// return body, and entries.set with body=undefined preserves
+				// the streamed content already in place. (`body: ""` would
+				// wipe everything we just streamed.)
+				for (const path of [stdoutPath, stderrPath]) {
+					try {
+						await entries.set({
+							runId,
+							path,
+							state: terminalState,
+							outcome,
+						});
+					} catch {}
+				}
+				try {
+					const channels = await entries.getEntriesByPattern(
+						runId,
+						`${dataBase}_*`,
+						null,
+					);
+					const summary = channels
+						.map((c) => `${c.path} (${c.tokens || 0} tokens)`)
+						.join(", ");
+					const exitLabel = exitCode === 0 ? "exit=0" : `exit=${exitCode}`;
+					await entries.set({
+						runId,
+						path: logPath,
+						state: "resolved",
+						body: `ran '${command}', ${exitLabel} (${duration}). Output: ${summary}`,
+					});
+				} catch {}
+				resolve();
+			});
+		});
+	}
+}

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";