@possumtech/rummy 2.0.0 → 2.1.0

package/src/plugins/xai/xai.js

@@ -1,16 +1,12 @@
+import config from "../../agent/config.js";
 import msg from "../../agent/messages.js";
+import { parseRetryAfter } from "../../llm/errors.js";
 
-const FETCH_TIMEOUT = Number(process.env.RUMMY_FETCH_TIMEOUT);
-if (!FETCH_TIMEOUT) throw new Error("RUMMY_FETCH_TIMEOUT must be set");
+const { FETCH_TIMEOUT } = config;
 
 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.
- */
+// Inert unless XAI_BASE_URL set; xai/{model} aliases; normalizes to OpenAI envelope.
 export default class Xai {
 	#baseUrl;
 	#apiKey;
@@ -39,6 +35,11 @@ export default class Xai {
 		const body = { model, input: messages };
 		if (options.temperature !== undefined)
 			body.temperature = options.temperature;
+		// xAI auto-caches per-server; stable prompt_cache_key keeps a multi-
+		// turn run pinned to the same backend so the cached prefix actually
+		// hits. Without this, requests load-balance and cache_tokens stays
+		// near-zero. See https://docs.x.ai/developers/advanced-api-usage/prompt-caching.
+		if (options.runAlias) body.prompt_cache_key = options.runAlias;
 
 		const timeoutSignal = AbortSignal.timeout(FETCH_TIMEOUT);
 		const signal = options.signal
@@ -56,15 +57,27 @@ export default class Xai {
 		});
 
 		if (!response.ok) {
-			const error = await response.text();
+			const errorBody = await response.text();
+			const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
 			if (response.status === 401 || response.status === 403) {
-				throw new Error(
-					msg("error.xai_auth", { status: `${response.status} - ${error}` }),
+				const err = new Error(
+					msg("error.xai_auth", {
+						status: `${response.status} - ${errorBody}`,
+					}),
 				);
+				err.status = response.status;
+				err.body = errorBody;
+				throw err;
 			}
-			throw new Error(
-				msg("error.xai_api", { status: `${response.status} - ${error}` }),
+			const err = new Error(
+				msg("error.xai_api", {
+					status: `${response.status} - ${errorBody}`,
+				}),
 			);
+			err.status = response.status;
+			err.body = errorBody;
+			err.retryAfter = retryAfter;
+			throw err;
 		}
 
 		return this.#normalize(await response.json());
@@ -133,12 +146,11 @@ export default class Xai {
 		const modelsUrl = this.#baseUrl.replace(/\/responses$/, "/models");
 		const res = await fetch(modelsUrl, {
 			headers: { Authorization: `Bearer ${this.#apiKey}` },
-			signal: AbortSignal.timeout(5000),
+			signal: AbortSignal.timeout(FETCH_TIMEOUT),
 		});
 		if (res.ok) {
 			const data = await res.json();
-			// xAI's /models returns either { data: [...] } or { models: [...] }
-			// depending on the API version; accept either and crash otherwise.
+			// xAI /models response shape varies by API version.
 			let models;
 			if (data.data) models = data.data;
 			else if (data.models) models = data.models;
@@ -156,12 +168,10 @@ export default class Xai {
 			/\/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.
+		// Optional probe; failure falls through to terminal throw below.
 		const langRes = await fetch(langUrl, {
 			headers: { Authorization: `Bearer ${this.#apiKey}` },
-			signal: AbortSignal.timeout(5000),
+			signal: AbortSignal.timeout(FETCH_TIMEOUT),
 		}).catch(() => null);
 		if (langRes?.ok) {
 			const langData = await langRes.json();

package/src/plugins/yolo/yolo.js

@@ -0,0 +1,159 @@
+import { spawn } from "node:child_process";
+import { logPathToDataBase } from "../helpers.js";
+
+const SH_PATH_RE = /^log:\/\/turn_\d+\/(sh|env)\//;
+
+// Auto-resolves proposals + spawns sh/env locally for runs started with yolo:true. SPEC #yolo_mode.
+export default class Yolo {
+	constructor(core) {
+		this.core = core;
+		core.hooks.proposal.pending.on(this.#onPending.bind(this));
+	}
+
+	async #onPending({ proposed, rummy }) {
+		if (!rummy?.yolo) return;
+		for (const p of proposed) {
+			// Resolve first so sh/env's post-accept seeds channels before we stream into them.
+			await this.#serverResolve(rummy, p.path);
+			if (SH_PATH_RE.test(p.path)) {
+				await this.#executeShellProposal(rummy, p.path);
+			}
+		}
+	}
+
+	// Inline mirror of AgentLoop.resolve()'s accept path.
+	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 locally and stream into {dataBase}_{1,2}; mirrors stream/stream-completed RPC.
+	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 + write-once-on-exit; async appends would race the terminal-state transition.
+		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}`;
+				// body=undefined preserves streamed content; body="" would wipe it.
+				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} 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

@@ -23,8 +23,7 @@ export default class ClientConnection {
 
 		this.#ws.on("message", (data) => this.#handleMessage(data));
 		this.#ws.on("close", () => {
-			// Fire-and-forget: the Promise is cached by `shutdown()` so
-			// server-initiated close can await the same work.
+			// Fire-and-forget; shutdown() caches the Promise for server-initiated close to await.
 			this.shutdown().catch((err) => {
 				console.warn(`[RUMMY] shutdown on ws close failed: ${err.message}`);
 			});
@@ -33,25 +32,6 @@ export default class ClientConnection {
 		this.#setupNotifications();
 	}
 
-	#onProgress = (payload) => {
-		if (payload.projectId === this.#context.projectId) {
-			this.#sendNotification("run/progress", {
-				run: payload.run,
-				turn: payload.turn,
-				status: payload.status,
-			});
-		}
-	};
-
-	#onProposal = (payload) => {
-		if (payload.projectId === this.#context.projectId) {
-			this.#sendNotification("run/proposal", {
-				run: payload.run,
-				proposed: payload.proposed,
-			});
-		}
-	};
-
 	#onRender = (payload) => {
 		if (payload.projectId === this.#context.projectId) {
 			this.#sendNotification("ui/render", {
@@ -80,44 +60,35 @@ export default class ClientConnection {
 		}
 	};
 
-	#onState = (payload) => {
-		if (payload.projectId === this.#context.projectId) {
-			this.#sendNotification("run/state", {
-				run: payload.run,
-				turn: payload.turn,
-				status: payload.status,
-				summary: payload.summary,
-				history: payload.history,
-				unknowns: payload.unknowns,
-				telemetry: payload.telemetry,
-			});
-		}
+	// Pulse: any entry write in this client's project. Content-free hint
+	// — client reconciles via getEntriesByPattern with `since`.
+	#onEntryChanged = async ({ runId, path, changeType }) => {
+		if (this.#context.projectId == null) return;
+		const run = await this.#db.get_run_by_id.get({ id: runId });
+		if (!run || run.project_id !== this.#context.projectId) return;
+		this.#sendNotification("run/changed", {
+			run: run.alias,
+			runId,
+			path,
+			changeType,
+		});
 	};
 
 	#setupNotifications() {
-		this.#hooks.run.progress.on(this.#onProgress);
-		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);
+		this.#hooks.entry.changed.on(this.#onEntryChanged);
 	}
 
 	#teardown() {
-		this.#hooks.run.progress.off(this.#onProgress);
-		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);
+		this.#hooks.entry.changed.off(this.#onEntryChanged);
 	}
 
-	/**
-	 * 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.
-	 */
+	// Idempotent abort+drain; cached Promise lets ws.close and server.close share completion.
 	shutdown() {
 		if (!this.#shutdownPromise) {
 			this.#shutdownPromise = (async () => {
@@ -241,8 +212,7 @@ export default class ClientConnection {
 		} 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.
+			// JSON-RPC requires null id for malformed requests with no id.
 			this.#send({
 				jsonrpc: "2.0",
 				error: { code: -32603, message: error.message },

package/src/server/SocketServer.js

@@ -15,18 +15,13 @@ export default class SocketServer {
 		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.
+			// Delete after drain settles so server.close() can await client-initiated shutdowns.
 			ws.on("close", () => {
 				conn.shutdown().finally(() => this.#connections.delete(conn));
 			});
 		});
 
-		this.#wss.on("error", (_err) => {
-			// Proxy to registry or handle locally
-		});
+		this.#wss.on("error", (_err) => {});
 	}
 
 	address() {
@@ -38,14 +33,19 @@ export default class SocketServer {
 	}
 
 	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(() => {}));
+		// Drain in-flight runs first; otherwise detached kickoffs pin the event loop.
+		// Best-effort: a single connection failing to shut down cleanly should not
+		// prevent the others from closing, but the failure must be visible.
+		const results = await Promise.allSettled(
+			Array.from(this.#connections, (conn) => conn.shutdown()),
+		);
+		for (const r of results) {
+			if (r.status === "rejected") {
+				console.error(
+					`[RUMMY] Connection shutdown failed: ${r.reason?.message ?? r.reason}`,
+				);
+			}
 		}
-		await Promise.all(shutdowns);
 		this.#connections.clear();
 
 		await new Promise((resolve) => {

package/src/server/protocol.js

@@ -1,11 +1,2 @@
-/**
- * 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
- */
+// Wire protocol version; rummy/hello rejects MAJOR mismatch. Semver.
 export const RUMMY_PROTOCOL_VERSION = "2.0.0";

package/src/sql/functions/slugify.js

@@ -1,18 +1,16 @@
+import encodeSegment from "../../agent/pathEncode.js";
+
 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.
+// commas→/, then encode-per-segment so / survives as separator.
+// encodeSegment handles spaces→_ + URL-encode (single rule, used everywhere).
 export default function slugify(text) {
 	if (!text) return "";
 	return text
 		.slice(0, 80)
 		.replace(/,/g, "/")
-		.replace(/ /g, "_")
 		.split("/")
 		.filter(Boolean)
-		.map(encodeURIComponent)
+		.map(encodeSegment)
 		.join("/");
 }

package/src/sql/v_model_context.sql

@@ -16,8 +16,8 @@ visible AS (
 		, e.attributes
 		, COALESCE(s.category, 'logging') AS category
 		, CASE
-			WHEN rv.visibility = 'archived' THEN NULL
 			WHEN s.model_visible = 0 THEN NULL
+			WHEN rv.visibility = 'archived' THEN NULL
 			ELSE rv.visibility
 		END AS effective_visibility
 	FROM run_views AS rv
@@ -38,10 +38,7 @@ projected AS (
 		, attributes
 		-- Category comes from schemes table — plugins declare it via registerScheme().
 		, category
-		, CASE
-			WHEN effective_visibility IN ('visible', 'summarized') THEN body
-			ELSE ''
-		END AS body
+		, body
 	FROM visible
 	WHERE effective_visibility IS NOT NULL
 )
@@ -67,13 +64,9 @@ SELECT
 				WHEN 'prompt' THEN 5
 				ELSE 5
 			END
-			, CASE scheme WHEN 'skill' THEN 0 ELSE 1 END
-			, CASE visibility
-				WHEN 'summarized' THEN 0
-				ELSE 1
-			END
+			, scheme
 			, turn
 			, updated_at
-			, id
+			, path
 	) AS ordinal
 FROM projected;