@possumtech/rummy 0.4.0 → 2.0.0

package/EXCEPTIONS.md

@@ -1,46 +0,0 @@
-# EXCEPTIONS.md — Documented Backbone Responsibilities
-
-Operations that bypass the plugin protocol. Each must justify WHY it
-can't go through the standard tool handler path. If the justification
-is weak, the exception should be eliminated.
-
-## Resolved
-
-### File.setConstraint / File.dropConstraint
-
-**What:** Direct DB writes to `file_constraints` table.
-**Justification:** File constraints are project-level config — they
-define which files a project cares about. This is backbone, not tool
-dispatch. Entry promotion/demotion that follows constraints now goes
-through the standard tool handler chain via `dispatchTool`.
-**Boundary documented:** SPEC.md §2.3.
-
-## Currently Identified
-
-### 1. TurnExecutor#record — tool-specific handling
-
-**What:** `known`, `unknown`, `summarize`, `update` have special-case
-code in `#record` (dedup, slug paths, lifecycle classification).
-**Bypasses:** These tools don't go through the same dispatch path as
-`get`, `set`, `rm` etc.
-**Justification:** Lifecycle signals (`summarize`, `update`) are state
-declarations, not tool operations — they always dispatch and cannot be
-409'd. `known` and `unknown` generate their own paths from body content
-(slug paths). The classification is a fundamental architectural split
-(lifecycle vs action), not a protocol violation.
-
-### 2. Token math — multiple measurement points
-
-**What:** `known_entries.tokens`, `turn_context.tokens`,
-`turns.context_tokens`, `countTokens()` estimates.
-**Bypasses:** No single function call, but a strict rule.
-**Justification:** Each serves a different purpose. `known_entries.tokens`
-is display-only (model sees entry sizes in `<knowns>`). `turn_context.tokens`
-is per-turn snapshot. `turns.context_tokens` is assembled ground truth for
-budget. The rule: budget decisions use ONLY assembled message tokens.
-DB tokens are NEVER used for budget. Documented in PLUGINS.md §7.5.
-
----
-
-*This file should shrink over time. Every entry is a debt to be paid
-or a boundary to be justified.*

package/src/agent/KnownStore.js

@@ -1,338 +0,0 @@
-import slugify from "../sql/functions/slugify.js";
-
-export default class KnownStore {
-	#db;
-	#onChanged;
-	#schemes = new Map();
-	#seq = 0;
-	#pendingResolutions = new Map();
-
-	constructor(db, { onChanged } = {}) {
-		this.#db = db;
-		this.#onChanged = onChanged || null;
-	}
-
-	async loadSchemes(db) {
-		const rows = await (db || this.#db).get_all_schemes.all();
-		this.#schemes.clear();
-		for (const row of rows) {
-			this.#schemes.set(row.name, row);
-		}
-	}
-
-	#emitChanged(runId, path, changeType) {
-		if (this.#onChanged) this.#onChanged({ runId, path, changeType });
-	}
-
-	static scheme(path) {
-		const idx = path.indexOf("://");
-		return idx > 0 ? path.slice(0, idx) : null;
-	}
-
-	static normalizePath(path) {
-		if (!path?.includes("://")) return path;
-		const sep = path.indexOf("://");
-		const scheme = path.slice(0, sep).toLowerCase();
-		const rest = path.slice(sep + 3);
-		try {
-			// Decode first (idempotent), then encode — but preserve slashes
-			const decoded = decodeURIComponent(rest);
-			return `${scheme}://${decoded.split("/").map(encodeURIComponent).join("/")}`;
-		} catch {
-			return `${scheme}://${rest.split("/").map(encodeURIComponent).join("/")}`;
-		}
-	}
-
-	async nextTurn(runId) {
-		const row = await this.#db.next_turn.get({ run_id: runId });
-		return row.turn;
-	}
-
-	async dedup(runId, scheme, target, turn) {
-		const encodedTarget = encodeURIComponent(target);
-		const turnPrefix = turn ? `turn_${turn}/` : "";
-		const candidate = `${scheme}://${turnPrefix}${encodedTarget}`;
-		const existing = await this.#db.get_entry_body.get({
-			run_id: runId,
-			path: candidate,
-		});
-		if (!existing) return candidate;
-		return `${candidate}_${++this.#seq}`;
-	}
-
-	async slugPath(runId, scheme, content, summary) {
-		const source = summary || content || "";
-		const base = slugify(source);
-		const prefix = `${scheme}://`;
-
-		if (!base) return `${prefix}${++this.#seq}`;
-
-		const candidate = `${prefix}${base}`;
-		const existing = await this.#db.get_entry_body.get({
-			run_id: runId,
-			path: candidate,
-		});
-		if (!existing) return candidate;
-
-		return `${prefix}${base}_${++this.#seq}`;
-	}
-
-	async upsert(
-		runId,
-		turn,
-		path,
-		body,
-		status,
-		{
-			fidelity = "full",
-			attributes = null,
-			hash = null,
-			updatedAt = null,
-			loopId = null,
-		} = {},
-	) {
-		const normalized = KnownStore.normalizePath(path);
-		await this.#db.upsert_known_entry.run({
-			run_id: runId,
-			loop_id: loopId,
-			turn,
-			path: normalized,
-			body,
-			status,
-			fidelity,
-			hash,
-			attributes: attributes ? JSON.stringify(attributes) : null,
-			updated_at: updatedAt,
-		});
-		this.#emitChanged(runId, normalized, "upsert");
-	}
-
-	async promote(runId, path, turn) {
-		const normalized = KnownStore.normalizePath(path);
-		await this.#db.promote_path.run({
-			run_id: runId,
-			path: normalized,
-			turn,
-		});
-		this.#emitChanged(runId, normalized, "promote");
-	}
-
-	async setFileFidelity(runId, pattern, fidelity) {
-		const result = await this.#db.set_file_fidelity.run({
-			run_id: runId,
-			pattern,
-			fidelity,
-		});
-		if (result.changes === 0) {
-			await this.upsert(runId, 0, pattern, "", 200, { fidelity });
-		}
-		this.#emitChanged(runId, pattern, "fidelity");
-	}
-
-	async setFidelity(runId, path, fidelity) {
-		const normalized = KnownStore.normalizePath(path);
-		await this.#db.set_fidelity.run({
-			run_id: runId,
-			path: normalized,
-			fidelity,
-		});
-		this.#emitChanged(runId, normalized, "fidelity");
-	}
-
-	async demote(runId, path) {
-		const normalized = KnownStore.normalizePath(path);
-		await this.#db.demote_path.run({
-			run_id: runId,
-			path: normalized,
-		});
-		this.#emitChanged(runId, normalized, "demote");
-	}
-
-	async remove(runId, path) {
-		const normalized = KnownStore.normalizePath(path);
-		await this.#db.delete_known_entry.run({
-			run_id: runId,
-			path: normalized,
-		});
-		this.#emitChanged(runId, normalized, "remove");
-	}
-
-	async removeFilesByPattern(runId, pattern) {
-		await this.#db.delete_file_entries_by_pattern.run({
-			run_id: runId,
-			pattern,
-		});
-		this.#emitChanged(runId, pattern, "remove");
-	}
-
-	static #bodyPattern(body) {
-		return body || null;
-	}
-
-	async promoteByPattern(runId, path, body, turn) {
-		await this.#db.promote_by_pattern.run({
-			run_id: runId,
-			path,
-			body: KnownStore.#bodyPattern(body),
-			turn,
-		});
-		this.#emitChanged(runId, path, "promote");
-	}
-
-	async demoteByPattern(runId, path, body) {
-		await this.#db.demote_by_pattern.run({
-			run_id: runId,
-			path,
-			body: KnownStore.#bodyPattern(body),
-		});
-		this.#emitChanged(runId, path, "demote");
-	}
-
-	async getEntriesByPattern(runId, path, body, { limit, offset } = {}) {
-		return this.#db.get_entries_by_pattern.all({
-			run_id: runId,
-			path,
-			body: KnownStore.#bodyPattern(body),
-			limit: limit ?? null,
-			offset: offset ?? null,
-		});
-	}
-
-	async deleteByPattern(runId, path, body) {
-		await this.#db.delete_entries_by_pattern.run({
-			run_id: runId,
-			path,
-			body: KnownStore.#bodyPattern(body),
-		});
-		this.#emitChanged(runId, path, "remove");
-	}
-
-	async updateBodyByPattern(runId, path, body, newBody) {
-		await this.#db.update_body_by_pattern.run({
-			run_id: runId,
-			path,
-			body: KnownStore.#bodyPattern(body),
-			new_body: newBody,
-		});
-		this.#emitChanged(runId, path, "body");
-	}
-
-	async resolve(runId, path, status, body) {
-		const normalized = KnownStore.normalizePath(path);
-		await this.#db.resolve_known_entry.run({
-			run_id: runId,
-			path: normalized,
-			status,
-			body,
-		});
-		this.#emitChanged(runId, normalized, "resolve");
-		const key = `${runId}:${normalized}`;
-		const resolver = this.#pendingResolutions.get(key);
-		if (resolver) {
-			this.#pendingResolutions.delete(key);
-			resolver();
-		}
-	}
-
-	waitForResolution(runId, path) {
-		const normalized = KnownStore.normalizePath(path);
-		const key = `${runId}:${normalized}`;
-		return new Promise((resolve) => {
-			this.#pendingResolutions.set(key, resolve);
-		});
-	}
-
-	async restoreSummarizedPrompts(runId) {
-		await this.#db.restore_summarized_prompts.run({ run_id: runId });
-		this.#emitChanged(runId, "prompt://batch", "fidelity");
-	}
-
-
-	async getLog(runId) {
-		return this.#db.get_results.all({ run_id: runId });
-	}
-
-	async getEntries(runId) {
-		return this.#db.get_known_entries.all({ run_id: runId });
-	}
-
-	async getFileEntries(runId) {
-		return this.#db.get_file_entries.all({ run_id: runId });
-	}
-
-	async getFileStatesByPattern(runId, pattern) {
-		return this.#db.get_file_states_by_pattern.all({ run_id: runId, pattern });
-	}
-
-	async hasRejections(runId, loopId) {
-		const row = await this.#db.has_rejections.get({
-			run_id: runId,
-			loop_id: loopId,
-		});
-		return row.count > 0;
-	}
-
-	async hasAcceptedActions(runId) {
-		const row = await this.#db.has_accepted_actions.get({ run_id: runId });
-		return row.count > 0;
-	}
-
-	async getUnresolved(runId) {
-		return this.#db.get_unresolved.all({ run_id: runId });
-	}
-
-	async countUnknowns(runId) {
-		const row = await this.#db.count_unknowns.get({ run_id: runId });
-		return row.count;
-	}
-
-	async getUnknownValues(runId) {
-		const rows = await this.#db.get_unknown_values.all({ run_id: runId });
-		return new Set(rows.map((r) => r.body));
-	}
-
-	async getBody(runId, path) {
-		const row = await this.#db.get_entry_body.get({
-			run_id: runId,
-			path: KnownStore.normalizePath(path),
-		});
-		return row?.body ?? null;
-	}
-
-	async setAttributes(runId, path, attrs) {
-		const normalized = KnownStore.normalizePath(path);
-		await this.#db.update_entry_attributes.run({
-			run_id: runId,
-			path: normalized,
-			attributes: JSON.stringify(attrs),
-		});
-		this.#emitChanged(runId, normalized, "attributes");
-	}
-
-	async getState(runId, path) {
-		return this.#db.get_entry_state.get({
-			run_id: runId,
-			path: KnownStore.normalizePath(path),
-		});
-	}
-
-	async getAttributes(runId, path) {
-		const row = await this.#db.get_entry_attributes.get({
-			run_id: runId,
-			path: KnownStore.normalizePath(path),
-		});
-		return row?.attributes ? JSON.parse(row.attributes) : null;
-	}
-
-	async getTurnAudit(runId, turn) {
-		return this.#db.get_turn_audit.all({ run_id: runId, turn });
-	}
-
-	static toolFromPath(path) {
-		return KnownStore.scheme(path);
-	}
-
-	static isSystemPath(path) {
-		return path.includes("://");
-	}
-}

package/src/agent/ResponseHealer.js

@@ -1,188 +0,0 @@
-const MAX_STALLS = Number(process.env.RUMMY_MAX_STALLS) || 3;
-const MIN_CYCLES = Number(process.env.RUMMY_MIN_CYCLES) || 3;
-const MAX_CYCLE_PERIOD = Number(process.env.RUMMY_MAX_CYCLE_PERIOD) || 4;
-const MAX_UPDATE_REPEATS = Number(process.env.RUMMY_MAX_UPDATE_REPEATS) || 3;
-
-/**
- * Build a stable fingerprint for a single recorded entry.
- * Uses scheme + original command target + all op-defining attributes.
- * Excludes body (content too granular; same operation ≠ same content).
- */
-function cmdFingerprint(entry) {
-	const attrs = { ...(entry.attributes ?? {}) };
-	delete attrs.body;
-	const target =
-		attrs.path ?? attrs.command ?? attrs.query ?? attrs.question ?? "";
-	delete attrs.path;
-	const extra = Object.keys(attrs)
-		.toSorted()
-		.filter((k) => attrs[k] != null)
-		.map((k) => `${k}=${attrs[k]}`)
-		.join(",");
-	return `${entry.scheme}:${target}${extra ? `[${extra}]` : ""}`;
-}
-
-/**
- * Detect a repeating cycle in the fingerprint history.
- * Checks periods 1..MAX_CYCLE_PERIOD for MIN_CYCLES consecutive repetitions.
- * Catches AAAA (period 1), ABABAB (period 2), ABCABCABC (period 3), etc.
- */
-function detectCycle(history) {
-	for (let k = 1; k <= MAX_CYCLE_PERIOD; k++) {
-		const needed = k * MIN_CYCLES;
-		if (history.length < needed) continue;
-		const tail = history.slice(-needed);
-		const cycle = tail.slice(0, k);
-		let match = true;
-		outer: for (let rep = 0; rep < MIN_CYCLES; rep++) {
-			for (let j = 0; j < k; j++) {
-				if (tail[rep * k + j] !== cycle[j]) {
-					match = false;
-					break outer;
-				}
-			}
-		}
-		if (match) return { detected: true, period: k, cycles: MIN_CYCLES };
-	}
-	return { detected: false };
-}
-
-export default class ResponseHealer {
-	#stallCount = 0;
-	#turnHistory = [];
-	#lastUpdateText = null;
-	#updateRepeatCount = 0;
-
-	/**
-	 * Heal a missing status tag. Called when the model emits
-	 * neither <summarize/> nor <update/>.
-	 */
-	/**
-	 * Heal a missing status tag. Called when the model emits
-	 * neither <summarize/> nor <update/>.
-	 *
-	 * Plain text with no commands = the model answered. Treat as summary.
-	 * Commands with no status tag = the model is working. Treat as update.
-	 */
-	static healStatus(content, commands) {
-		const trimmed = content.trim();
-
-		// No commands + plain text = answered. Treat as summary.
-		if (commands.length === 0 && trimmed) {
-			console.warn("[RUMMY] Healed: plain text response treated as summary");
-			return { summaryText: trimmed.slice(0, 500), updateText: null };
-		}
-
-		// Only write/unknown commands + no investigation tools = completed action.
-		// The model did the thing without saying <summarize>. Treat as summary.
-		const hasInvestigation = commands.some((c) =>
-			["get", "env", "search", "ask_user"].includes(c.name),
-		);
-		if (!hasInvestigation && commands.length > 0) {
-			const names = commands.map((c) => c.name).join(", ");
-			console.warn(
-				`[RUMMY] Healed: action-only response (${names}) treated as summary`,
-			);
-			return {
-				summaryText: trimmed.slice(0, 500) || "Done.",
-				updateText: null,
-			};
-		}
-
-		console.warn(
-			`[RUMMY] Healed: missing <update>/<summarize>. Tools: ${commands.map((c) => c.name).join(", ") || "none"}`,
-		);
-		return { summaryText: null, updateText: "..." };
-	}
-
-	/**
-	 * Detect cyclic tool patterns across turns.
-	 * Returns { continue: boolean, reason?: string }
-	 *
-	 * Appends this turn's fingerprint to history, then checks whether the
-	 * history ends in a repeating cycle of period 1..MAX_CYCLE_PERIOD with
-	 * at least MIN_CYCLES consecutive repetitions.
-	 *
-	 * Catches AAAA (period 1), ABABAB (period 2), ABCABC (period 3), etc.
-	 * Turns with no tool calls are skipped — they don't contribute to a cycle.
-	 */
-	assessRepetition({ actionCalls, writeCalls }) {
-		const commands = [...(actionCalls || []), ...(writeCalls || [])];
-		if (commands.length === 0) return { continue: true };
-
-		const fp = commands.map(cmdFingerprint).toSorted().join("|");
-		this.#turnHistory.push(fp);
-
-		const cycle = detectCycle(this.#turnHistory);
-		if (cycle.detected) {
-			const reason = `Cyclic tool pattern (period ${cycle.period}, ${cycle.cycles} repetitions)`;
-			console.warn(`[RUMMY] Loop detected: ${reason}. Force-completing.`);
-			return { continue: false, reason };
-		}
-
-		return { continue: true };
-	}
-
-	/**
-	 * Assess whether the run should continue.
-	 *
-	 * Returns { continue: boolean, reason?: string }
-	 *
-	 * Rules:
-	 *   <summarize/> present → done (terminate)
-	 *   <summarize/> + failed actions → overridden to <update> (continue)
-	 *   <update/> present  → continue (model says it's working)
-	 *   neither present    → warn, increment stall counter, continue
-	 *   stall counter hits MAX_STALLS → force-complete
-	 */
-	assessProgress({ summaryText, updateText, statusHealed, flags }) {
-		if (summaryText) {
-			this.#stallCount = 0;
-			return { continue: false };
-		}
-
-		if (updateText && !statusHealed) {
-			this.#stallCount = 0;
-			// Track repeated update text — model stuck declaring readiness
-			// But if the model created new entries this turn, it's making
-			// progress even if the update text is the same.
-			const madeProgress = flags?.hasWrites || flags?.hasReads;
-			if (updateText === this.#lastUpdateText && !madeProgress) {
-				this.#updateRepeatCount++;
-				if (this.#updateRepeatCount >= MAX_UPDATE_REPEATS) {
-					const reason = `Same <update/> repeated ${this.#updateRepeatCount} turns: "${updateText.slice(0, 60)}"`;
-					console.warn(`[RUMMY] Stalled: ${reason}. Force-completing.`);
-					return { continue: false, reason };
-				}
-			} else {
-				this.#lastUpdateText = updateText;
-				this.#updateRepeatCount = 1;
-			}
-			return { continue: true };
-		}
-
-		// Healed or neither — model is glitching
-		this.#stallCount++;
-
-		if (this.#stallCount >= MAX_STALLS) {
-			const reason = `${this.#stallCount} turns with no <update/> or <summarize/>`;
-			console.warn(`[RUMMY] Stalled: ${reason}. Force-completing.`);
-			return { continue: false, reason };
-		}
-
-		console.warn(
-			`[RUMMY] No <update/> or <summarize/> (stall ${this.#stallCount}/${MAX_STALLS})`,
-		);
-		return { continue: true };
-	}
-
-	/**
-	 * Reset state for a new run or after resolution resume.
-	 */
-	reset() {
-		this.#stallCount = 0;
-		this.#turnHistory = [];
-		this.#lastUpdateText = null;
-		this.#updateRepeatCount = 0;
-	}
-}

package/src/llm/OpenAiClient.js

@@ -1,100 +0,0 @@
-import msg from "../agent/messages.js";
-
-export default class OpenAiClient {
-	#baseUrl;
-	#apiKey;
-
-	constructor(baseUrl, apiKey) {
-		this.#baseUrl = String(baseUrl || "").replace(/\/v1\/?$/, "");
-		this.#apiKey = apiKey || "";
-	}
-
-	async completion(messages, model, options = {}) {
-		const body = { model, messages, think: true };
-		if (options.temperature !== undefined)
-			body.temperature = options.temperature;
-
-		const timeout = Number(process.env.RUMMY_FETCH_TIMEOUT) || 30_000;
-		const timeoutSignal = AbortSignal.timeout(timeout);
-		const signal = options.signal
-			? AbortSignal.any([options.signal, timeoutSignal])
-			: timeoutSignal;
-
-		const headers = { "Content-Type": "application/json" };
-		if (this.#apiKey) headers.Authorization = `Bearer ${this.#apiKey}`;
-
-		const response = await fetch(`${this.#baseUrl}/v1/chat/completions`, {
-			method: "POST",
-			headers,
-			body: JSON.stringify(body),
-			signal,
-		});
-
-		if (!response.ok) {
-			const error = await response.text();
-			throw new Error(
-				msg("error.openai_api", { status: `${response.status} - ${error}` }),
-			);
-		}
-
-		const data = await response.json();
-
-		for (const choice of data.choices || []) {
-			const msg = choice.message;
-			if (!msg) continue;
-
-			// Normalize reasoning
-			const parts = [msg.reasoning_content, msg.reasoning, msg.thinking].filter(
-				Boolean,
-			);
-			msg.reasoning_content =
-				parts.length > 0 ? [...new Set(parts)].join("\n") : null;
-
-			if (process.env.RUMMY_DEBUG === "true" && msg.reasoning_content) {
-				console.warn(
-					`[RUMMY] Reasoning (${msg.reasoning_content.length} chars): ${msg.reasoning_content.slice(0, 120)}`,
-				);
-			}
-		}
-
-		return data;
-	}
-
-	async getContextSize(_model) {
-		const timeout = Number(process.env.RUMMY_FETCH_TIMEOUT) || 30_000;
-		const headers = { "Content-Type": "application/json" };
-		if (this.#apiKey) headers.Authorization = `Bearer ${this.#apiKey}`;
-
-		// Try /props first — llama.cpp exposes runtime n_ctx here
-		try {
-			const propsResponse = await fetch(`${this.#baseUrl}/props`, {
-				headers,
-				signal: AbortSignal.timeout(timeout),
-			});
-			if (propsResponse.ok) {
-				const props = await propsResponse.json();
-				const runtimeCtx = props?.default_generation_settings?.n_ctx;
-				if (runtimeCtx) return runtimeCtx;
-			}
-		} catch {}
-
-		// Fall back to /v1/models for training context
-		const response = await fetch(`${this.#baseUrl}/v1/models`, {
-			headers,
-			signal: AbortSignal.timeout(timeout),
-		});
-		if (!response.ok) {
-			throw new Error(
-				msg("error.openai_models_failed", {
-					status: response.status,
-					baseUrl: this.#baseUrl,
-				}),
-			);
-		}
-		const data = await response.json();
-		const model = data.data?.[0];
-		const ctx = model?.meta?.n_ctx_train || model?.context_length;
-		if (!ctx) throw new Error(msg("error.openai_no_context_length"));
-		return ctx;
-	}
-}