@possumtech/rummy 0.3.1 → 0.4.0

package/.env.example

@@ -17,6 +17,7 @@ RUMMY_MMAP_MB=0
 
 # Agent Loop Limits
 RUMMY_MAX_TURNS=99
+RUMMY_MAX_COMMANDS=15
 RUMMY_MAX_UNKNOWN_WARNINGS=3
 RUMMY_MAX_STALLS=3
 RUMMY_MIN_CYCLES=3
@@ -34,6 +35,16 @@ RUMMY_FETCH_TIMEOUT=300000
 # Debug
 # RUMMY_DEBUG=true
 
+# Think tag: 1 = model uses <think> tags for reasoning (default)
+# 0 = disabled, model reasons via API reasoning_content field only
+RUMMY_THINK=1
+
+# Budget
+# Fraction of context window used as ceiling. 0.9 = 90%, 10% reserved as headroom.
+RUMMY_BUDGET_CEILING=0.9
+# Maximum tokens per known entry. Entries exceeding this are rejected with 413.
+RUMMY_MAX_ENTRY_TOKENS=512
+
 # Token Estimation
 # Characters per token. Lower = more conservative (fewer tokens per character).
 # Default 2. Set to 1 for worst-case (1 token per character).

package/README.md

@@ -1,6 +1,6 @@
 # RUMMY: Relational Unknowns Memory Management Yoke
 
-Rummy is the only LLM agent service inspired by and dedicated to the memory of former Secretary of State Donald "Rummy" Rumsfeld. Our unique fusion of apophatic and hedbergian engineering strategies yields more accurate and efficient results than any other agent. Our client/server and plugin architecture integrates it into more workflows than any other agent. It's also more flexible and lean than any other agent. Our dynamic cache management, model hot-swapping, and flexible router interface make it more affordable than any other agent.
+Rummy is the only LLM agent service inspired by and dedicated to the memory of former Secretary of Defense Donald "Rummy" Rumsfeld. Our unique fusion of apophatic and hedbergian engineering strategies yields more accurate and efficient results than any other agent. Our client/server and plugin architecture integrates it into more workflows than any other agent. It's also more flexible and lean than any other agent. Our dynamic cache management, model hot-swapping, and flexible router interface make it more affordable than any other agent.
 
 ## Key Features
 
@@ -10,6 +10,10 @@ Rummy is the only LLM agent service inspired by and dedicated to the memory of f
 
 - **Hedberg:** The interpretation boundary between stochastic model output and deterministic system operations. Models speak in whatever syntax they were trained on — sed regex, SEARCH/REPLACE blocks, escaped characters. Hedberg normalizes all of it. Available to all plugins via `core.hooks.hedberg`.
 
+- **Folksonomic Memory:** The model organizes its own knowledge into navigable path hierarchies with searchable summary tags. Not RAG — the model builds and curates its own taxonomy using `<known>` entries with paths like `known://project/architecture`.
+
+- **Fidelity System:** Every entry has a visibility level: full, summary, index, archive. The model manages its own context by promoting what it needs and demoting what it doesn't. Budget enforcement catches overflow post-dispatch — tools run uninterrupted, demotion happens after.
+
 - **Plugin Architecture:** Every `<tag>` the model sees is a plugin. Every scheme is registered by its owner. The prompt itself is assembled from plugins. Drop a directory into `~/.rummy/plugins/` or install via npm. See [PLUGINS.md](PLUGINS.md) for the complete plugin API.
 
 - **Symbols Done Right:** Designed with universal language support in mind. Powered by [@possumtech/antlrmap](https://github.com/possumtech/antlrmap).

package/SPEC.md

@@ -44,7 +44,7 @@ body, attributes, and state.
 known_entries (
     id, run_id, loop_id, turn, path, body, scheme,
     status INTEGER, fidelity TEXT, hash,
-    attributes, tokens, tokens_full, refs, write_count,
+    attributes, tokens, refs, write_count,
     created_at, updated_at
 )
 ```
@@ -56,10 +56,9 @@ known_entries (
 | `attributes` | Tag attributes as JSON. Handler-private workspace. `CHECK (json_valid)` |
 | `scheme` | Generated from path via `schemeOf()`. Drives dispatch and view routing |
 | `status` | HTTP status code (200, 202, 400, 413, etc.) |
-| `fidelity` | Visibility level: full, summary, index, archive |
+| `fidelity` | Visibility level: full, summary, archive |
 | `hash` | SHA-256 for file change detection |
-| `tokens` | Display-only token count at current fidelity. NEVER used for budget. |
-| `tokens_full` | Cost of raw body at full fidelity |
+| `tokens` | Full-body token cost. Never changes on demotion/promotion. |
 | `turn` | Freshness — when was this entry last touched |
 
 ### 1.2 Schemes, Status & Fidelity
@@ -211,8 +210,8 @@ object is the same shape at every tier.
 Model tier restrictions enforced by unified `resolveForLoop(mode, flags)`.
 Ask mode excludes `sh`. Flags: `noInteraction` excludes `ask_user`,
 `noWeb` excludes `search`, `noProposals` excludes `ask_user`/`env`/`sh`.
-13 model tools: get, set, known, unknown, env, sh, rm, cp, mv, search,
-summarize, update, ask_user.
+14 model tools: think, unknown, known, get, set, env, sh, rm, cp, mv,
+ask_user, update, summarize, search.
 Client tier requires project init. Plugin tier has no restrictions.
 
 ### 3.2 Dispatch Path
@@ -225,13 +224,28 @@ Client: JSON-RPC  → { method, params }   → #record() → dispatch(scheme, en
 Plugin: rummy.rm({ path })               → #record() → dispatch(scheme, entry, rummy)
 ```
 
-**Lifecycle/action split:** Commands are classified as lifecycle signals
-(`summarize`, `update`, `unknown`, `known`) or action commands (everything
-else). Lifecycle signals always dispatch — they are state declarations that
-cannot be 409'd by sequential dispatch. Action commands dispatch sequentially;
-a 202 proposal or error aborts subsequent actions. If the model sends
-`<summarize>` but actions in the same turn failed, the summarize is
-overridden to an update (the model's assertion that it's done is false).
+**Tool dispatch:** Commands are dispatched sequentially in the order
+the model emitted them. Each tool either succeeds (200), fails (400+),
+or proposes (202). On failure, all remaining tools are aborted. On
+proposal, dispatch pauses, a notification is pushed to the client
+(same WebSocket push pattern as `run/progress`), the client resolves
+(accept/reject), and dispatch resumes — the proposal becomes 200 or
+400+ like any other tool. The `ask`/`act` RPC response is only sent
+when all tools have completed. Proposals are NOT batched — each is
+sent and resolved inline during dispatch. The model controls tool
+ordering; the system respects it.
+
+If the model sends `<summarize>` but a preceding action in the same
+turn failed, the summarize is overridden to an update (the model's
+assertion that it's done is false). Both `<summarize>` and `<update>`
+present → last signal wins.
+
+**Post-dispatch budget check:** After all tools dispatch, the system
+materializes context and checks the budget ceiling. If context exceeds
+the ceiling, Turn Demotion fires — all entries from this turn are
+demoted to summary and a `budget://` entry is written. This is a
+system housekeeping step independent of tool success/failure. The
+tools already ran; their outcomes are settled.
 
 ### 3.3 Plugin Convention
 
@@ -293,7 +307,7 @@ Two messages per turn. System = stable truth. User = active task.
         [skills/]
     [/instructions]
     <knowns>
-        ...entries sorted by fidelity (index, summary, full), then by scheme
+        ...entries sorted by fidelity (summary, full), then by scheme
     </knowns>
     <previous>
         (pre-loop entries, each with turn, status, summary, fidelity, tokens)
@@ -531,7 +545,7 @@ ask_user. `noRepo: true` — no file scanning during panic.
 `budget.panicPrompt()`: the assembled token count, the target, and
 the exact number of tokens to free. Turn 2+ receives a continuation
 prompt. The model uses `<set fidelity="archive">`, `<mv
-fidelity="index">`, and similar fidelity operations to free space,
+fidelity="summary">`, and similar fidelity operations to free space,
 concluding with `<summarize>` when done or `<update>` while working.
 
 ---
@@ -660,7 +674,7 @@ simple to powerful — weak models learn from examples 1-2, strong models
 pick up the pattern from example 3.
 
 **Lifecycle continuity.** Examples weave stories across tools. The get
-docs end with `<set path="..." fidelity="index"/>`. The known docs
+docs end with `<set path="..." fidelity="summary"/>`. The known docs
 reference `<get path="known://*">keyword</get>` for recall and
 `<set path="known://..." archive/>` for archiving. The unknown docs
 reference `<get/>` for investigation and `<rm/>` for cleanup. A model
@@ -746,7 +760,7 @@ Termination protocol:
 - `<summarize>` → run terminates
 - `<summarize>` + failed actions → overridden to `<update>` (continue)
 - `<update>` → run continues
-- Both → update wins (if the model can't decide, it's not done)
+- Both → last signal wins (respects the model's final intent)
 - Neither + investigation tools → stall counter (RUMMY_MAX_STALLS)
 - Neither + action-only tools → healed to summarize
 - Neither + plain text → healed to summarize

package/migrations/001_initial_schema.sql

@@ -125,12 +125,11 @@ CREATE TABLE IF NOT EXISTS known_entries (
 	, scheme TEXT GENERATED ALWAYS AS (schemeOf(path)) STORED
 	, status INTEGER NOT NULL DEFAULT 200 CHECK (status BETWEEN 100 AND 599)
 	, fidelity TEXT NOT NULL DEFAULT 'full' CHECK (
-		fidelity IN ('full', 'summary', 'index', 'archive')
+		fidelity IN ('full', 'summary', 'archive')
 	)
 	, hash TEXT
 	, attributes JSON NOT NULL DEFAULT '{}' CHECK (json_valid(attributes))
 	, tokens INTEGER NOT NULL DEFAULT 0 CHECK (tokens >= 0)
-	, tokens_full INTEGER NOT NULL DEFAULT 0 CHECK (tokens_full >= 0)
 	, refs INTEGER NOT NULL DEFAULT 0 CHECK (refs >= 0)
 	, write_count INTEGER NOT NULL DEFAULT 1 CHECK (write_count >= 1)
 	, created_at DATETIME DEFAULT CURRENT_TIMESTAMP
@@ -167,7 +166,7 @@ CREATE TABLE IF NOT EXISTS turn_context (
 	, path TEXT NOT NULL
 	, scheme TEXT GENERATED ALWAYS AS (schemeOf(path)) STORED
 	, status INTEGER NOT NULL DEFAULT 200 CHECK (status BETWEEN 100 AND 599)
-	, fidelity TEXT NOT NULL CHECK (fidelity IN ('full', 'summary', 'index'))
+	, fidelity TEXT NOT NULL CHECK (fidelity IN ('full', 'summary'))
 	, body TEXT NOT NULL DEFAULT ''
 	, tokens INTEGER NOT NULL DEFAULT 0 CHECK (tokens >= 0)
 	, attributes JSON NOT NULL DEFAULT '{}' CHECK (json_valid(attributes))

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@possumtech/rummy",
-	"version": "0.3.1",
+	"version": "0.4.0",
 	"description": "Relational Unknowns Memory Management Yoke",
 	"keywords": [
 		"llm"

package/src/agent/AgentLoop.js

@@ -1,3 +1,4 @@
+import { advanceRecovery } from "../plugins/budget/recovery.js";
 import KnownStore from "./KnownStore.js";
 import msg from "./messages.js";
 import ResponseHealer from "./ResponseHealer.js";
@@ -70,14 +71,15 @@ export default class AgentLoop {
 			const existing = this.#activeRuns.get(existingRun.id);
 			if (existing) existing.abort();
 
+			// Clean up stale proposals from interrupted runs
 			const unresolved = await this.#knownStore.getUnresolved(existingRun.id);
-			if (unresolved.length > 0) {
-				return {
-					runId: existingRun.id,
-					alias: existingRun.alias,
-					blocked: true,
-					proposed: unresolved,
-				};
+			for (const u of unresolved) {
+				await this.#knownStore.resolve(
+					existingRun.id,
+					u.path,
+					499,
+					"Stale proposal from interrupted run",
+				);
 			}
 			return { runId: existingRun.id, alias: existingRun.alias };
 		}
@@ -125,15 +127,6 @@ export default class AgentLoop {
 		const requestedModel = model;
 
 		const runInfo = await this.#ensureRun(projectId, model, run, options);
-		if (runInfo.blocked) {
-			return {
-				run: runInfo.alias,
-				status: 202,
-				remainingCount: runInfo.proposed.length,
-				proposed: runInfo.proposed,
-			};
-		}
-
 		const { runId: currentRunId, alias: currentAlias } = runInfo;
 
 		const loopSeq = await this.#db.next_loop.get({ run_id: currentRunId });
@@ -222,11 +215,9 @@ export default class AgentLoop {
 
 				await this.#db.complete_loop.run({
 					id: loop.id,
-					status: result.status === 202 ? 202 : result.status,
+					status: result.status,
 					result: JSON.stringify(result),
 				});
-
-				if (result.status === 202) return result;
 			}
 
 			const runRow = await this.#db.get_run_by_alias.get({
@@ -282,12 +273,9 @@ export default class AgentLoop {
 		let _lastAssembledTokens = 0;
 		let recovery = null; // { target, promptPath, strikes, lastTokens }
 
-		// Demote full logging entries from previous loops to summary before
-		// they appear in <previous>. General policy: keep <previous> compact.
-		await this.#knownStore.demotePreviousLoopLogging(
-			currentRunId,
-			currentLoopId,
-		);
+		// Previous loop entries stay at full fidelity — the model is
+		// instructed to summarize and demote them. Budget enforcement
+		// catches overflow if the model fails to manage context.
 
 		// Restore any prompt entries left at summary fidelity by a recovery
 		// phase that was interrupted (server crash, restart). If the full
@@ -347,7 +335,16 @@ export default class AgentLoop {
 				});
 
 				if (result.status === 413) {
-					return {
+					await this.#db.complete_loop.run({
+						id: currentLoopId,
+						status: 413,
+						result: null,
+					});
+					await this.#db.update_run_status.run({
+						id: currentRunId,
+						status: 200,
+					});
+					const out = {
 						run: currentAlias,
 						status: 413,
 						overflow: result.overflow,
@@ -355,6 +352,8 @@ export default class AgentLoop {
 						contextSize: result.contextSize,
 						turn: result.turn,
 					};
+					await hook.completed.emit({ projectId, ...out });
+					return out;
 				}
 
 				_lastAssembledTokens = result.assembledTokens;
@@ -390,8 +389,6 @@ export default class AgentLoop {
 				const unknowns = await this.#db.get_unknowns.all({
 					run_id: currentRunId,
 				});
-				const unresolved = await this.#knownStore.getUnresolved(currentRunId);
-
 				const latestSummary = history
 					.filter((e) => e.status === 200 && e.path?.startsWith("summarize://"))
 					.at(-1);
@@ -400,15 +397,10 @@ export default class AgentLoop {
 					projectId,
 					run: currentAlias,
 					turn: result.turn,
-					status: unresolved.length > 0 ? 202 : 102,
+					status: 102,
 					summary: latestSummary?.body || "",
 					history,
 					unknowns: unknowns.map((u) => ({ path: u.path, body: u.body })),
-					proposed: unresolved.map((p) => ({
-						path: p.path,
-						type: KnownStore.toolFromPath(p.path) || "unknown",
-						attributes: p.attributes ? JSON.parse(p.attributes) : null,
-					})),
 					telemetry: {
 						modelAlias: result.modelAlias,
 						model: result.model,
@@ -433,21 +425,6 @@ export default class AgentLoop {
 						}),
 					},
 				});
-				if (unresolved.length > 0) {
-					await this.#db.update_run_status.run({
-						id: currentRunId,
-						status: 202,
-					});
-					const out = {
-						run: currentAlias,
-						status: 202,
-						turn: result.turn,
-						proposed: unresolved,
-					};
-					await hook.completed.emit({ projectId, ...out });
-					return out;
-				}
-
 				await this.#hooks.run.step.completed.emit({
 					projectId,
 					run: currentAlias,
@@ -574,6 +551,12 @@ export default class AgentLoop {
 			}
 
 			if (action === "accept") {
+				const projectId = runRow.project_id;
+				const project = await this.#db.get_project_by_id.get({
+					id: projectId,
+				});
+				const projectRoot = project?.project_root;
+
 				if (path.startsWith("set://") && attrs?.file && attrs?.merge) {
 					const fileBody = await this.#knownStore.getBody(runId, attrs.file);
 					if (fileBody != null) {
@@ -594,12 +577,25 @@ export default class AgentLoop {
 							patched,
 							200,
 						);
+						// Write patched content to disk
+						if (projectRoot) {
+							const { writeFile } = await import("node:fs/promises");
+							const { join } = await import("node:path");
+							await writeFile(join(projectRoot, attrs.file), patched).catch(
+								() => {},
+							);
+						}
 					}
 				}
 
 				if (path.startsWith("rm://")) {
 					if (attrs?.path) {
 						await this.#knownStore.remove(runId, attrs.path);
+						if (projectRoot) {
+							const { unlink } = await import("node:fs/promises");
+							const { join } = await import("node:path");
+							await unlink(join(projectRoot, attrs.path)).catch(() => {});
+						}
 					}
 				}
 
@@ -615,68 +611,9 @@ export default class AgentLoop {
 			throw new Error(msg("error.resolution_invalid", { action }));
 		}
 
-		const unresolved = await this.#knownStore.getUnresolved(runId);
-		if (unresolved.length > 0) {
-			return {
-				run: runAlias,
-				status: 202,
-				remainingCount: unresolved.length,
-				proposed: unresolved,
-			};
-		}
-
-		// Scope completion checks to the current loop
-		const currentLoop = await this.#db.get_current_loop.get({ run_id: runId });
-		const loopId = currentLoop?.id ?? null;
-
-		if (await this.#knownStore.hasRejections(runId, loopId)) {
-			if (currentLoop)
-				await this.#db.complete_loop.run({
-					id: loopId,
-					status: 200,
-					result: null,
-				});
-			await this.#db.update_run_status.run({ id: runId, status: 200 });
-			return { run: runAlias, status: 200 };
-		}
-
-		const hasSummary = await this.#db.get_latest_summary.get({
-			run_id: runId,
-			loop_id: loopId,
-		});
-		if (hasSummary?.body) {
-			if (currentLoop)
-				await this.#db.complete_loop.run({
-					id: loopId,
-					status: 200,
-					result: null,
-				});
-			await this.#db.update_run_status.run({ id: runId, status: 200 });
-			return { run: runAlias, status: 200 };
-		}
-
-		// No summary and no rejections in this loop — resume it
-		const projectId = runRow.project_id;
-		const project = await this.#db.get_project_by_id.get({ id: projectId });
-
-		const latestPrompt = await this.#db.get_latest_prompt.get({
-			run_id: runId,
-		});
-		const resumeMode = latestPrompt?.attributes
-			? JSON.parse(latestPrompt.attributes).mode
-			: "ask";
-
-		// Re-enqueue the current loop's prompt to continue it
-		const loopSeq = await this.#db.next_loop.get({ run_id: runId });
-		await this.#db.enqueue_loop.get({
-			run_id: runId,
-			sequence: loopSeq.sequence,
-			mode: resumeMode,
-			model: runRow.model,
-			prompt: "",
-			config: currentLoop?.config || "{}",
-		});
-		return this.#drainQueue(runId, runAlias, projectId, project, {});
+		// The dispatch loop is awaiting resolution. This unblocks it.
+		// Dispatch continuation is handled by the loop, not here.
+		return { run: runAlias, status: 200 };
 	}
 
 	async #composeResolvedContent(runId, path, _attrs, output) {
@@ -741,43 +678,5 @@ export default class AgentLoop {
  * @param {{ assembledTokens: number, budgetRecovery?: { target: number, promptPath: string|null } }} result
  * @returns {{ next: object|null, action: null|'restore'|'hard413', promptPath: string|null }}
  */
-export function advanceRecovery(recovery, result) {
-	// Initialise or update recovery state from a new Turn Demotion event.
-	if (result.budgetRecovery) {
-		if (!recovery) {
-			recovery = {
-				target: result.budgetRecovery.target,
-				promptPath: result.budgetRecovery.promptPath,
-				strikes: 0,
-				lastTokens: result.assembledTokens,
-			};
-		} else {
-			// Re-overflow during recovery: tighten target, don't count as strike.
-			recovery = {
-				...recovery,
-				target: Math.min(recovery.target, result.budgetRecovery.target),
-			};
-		}
-	}
-
-	if (recovery === null) return { next: null, action: null, promptPath: null };
-
-	const current = result.assembledTokens;
-
-	if (current <= recovery.target) {
-		return { next: null, action: "restore", promptPath: recovery.promptPath };
-	}
-
-	const noProgress = current >= recovery.lastTokens && !result.budgetRecovery;
-	const strikes = noProgress ? recovery.strikes + 1 : 0;
-
-	if (strikes >= 3) {
-		return { next: null, action: "hard413", promptPath: null };
-	}
-
-	return {
-		next: { ...recovery, strikes, lastTokens: current },
-		action: null,
-		promptPath: null,
-	};
-}
+// Re-export for backward compatibility with tests
+export { advanceRecovery } from "../plugins/budget/recovery.js";

package/src/agent/KnownStore.js

@@ -5,6 +5,7 @@ export default class KnownStore {
 	#onChanged;
 	#schemes = new Map();
 	#seq = 0;
+	#pendingResolutions = new Map();
 
 	constructor(db, { onChanged } = {}) {
 		this.#db = db;
@@ -225,6 +226,20 @@ export default class KnownStore {
 			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) {
@@ -232,13 +247,6 @@ export default class KnownStore {
 		this.#emitChanged(runId, "prompt://batch", "fidelity");
 	}
 
-	async demotePreviousLoopLogging(runId, loopId) {
-		await this.#db.demote_previous_loop_logging.run({
-			run_id: runId,
-			loop_id: loopId,
-		});
-		this.#emitChanged(runId, "logging://batch", "fidelity");
-	}
 
 	async getLog(runId) {
 		return this.#db.get_results.all({ run_id: runId });