@possumtech/rummy 2.2.1 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@possumtech/rummy",
-	"version": "2.2.1",
+	"version": "2.3.1",
 	"description": "Relational Unknowns Memory Management Yoke",
 	"keywords": [
 		"llm"
@@ -28,6 +28,14 @@
 	},
 	"type": "module",
 	"main": "service.js",
+	"files": [
+		"service.js",
+		"bin/",
+		"src/",
+		"migrations/",
+		"lang/",
+		"!**/*.test.js"
+	],
 	"scripts": {
 		"postinstall": "node ./bin/postinstall.js",
 		"start": "node --env-file-if-exists=.env.example --env-file-if-exists=.env service.js",
@@ -53,15 +61,15 @@
 		"test:lme:clean": "rm -rf test/lme/results/*/",
 		"test:swe:clean": "rm -rf test/swe/results/*/ test/swe/repos/",
 		"test:tbench:setup": "bash -c 'set -a; source .env.tbench; set +a; bash test/tbench/setup.sh'",
-		"test:tbench": "bash -c 'echo \"Specify a profile: test:tbench:xfast | :gemma | :xfast_or\" >&2 && exit 64'",
-		"test:tbench:xfast": "bash -c 'set -o pipefail; mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.tbench --env-file-if-exists=.env.tbench.xfast test/tbench/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/tbench_xfast_$(date +%Y%m%dT%H%M%S).log' --",
+		"test:tbench": "bash -c 'echo \"Specify a profile: test:tbench:grok | :gemma\" >&2 && exit 64'",
 		"test:tbench:gemma": "bash -c 'set -o pipefail; mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.tbench --env-file-if-exists=.env.tbench.gemma test/tbench/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/tbench_gemma_$(date +%Y%m%dT%H%M%S).log' --",
-		"test:tbench:xfast_or": "bash -c 'set -o pipefail; mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.tbench --env-file-if-exists=.env.tbench.xfast_or test/tbench/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/tbench_xfast_or_$(date +%Y%m%dT%H%M%S).log' --",
-		"test:tbench:g43": "bash -c 'set -o pipefail; mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.tbench --env-file-if-exists=.env.tbench.g43 test/tbench/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/tbench_g43_$(date +%Y%m%dT%H%M%S).log' --",
+		"test:tbench:grok": "bash -c 'set -o pipefail; mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.tbench --env-file-if-exists=.env.tbench.grok test/tbench/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/tbench_grok_$(date +%Y%m%dT%H%M%S).log' --",
 		"test:tbench:clean": "rm -rf test/tbench/results/*/",
 		"test:tbench:summary": "node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.tbench test/tbench/summarize.js",
 		"test:programbench:setup": "bash test/programbench/setup.sh",
-		"test:programbench": "bash -c 'set -o pipefail; mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.tbench --env-file-if-exists=.env.tbench.gemma test/programbench/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/programbench_$(date +%Y%m%dT%H%M%S).log' --",
+		"test:programbench": "bash -c 'echo \"Specify a profile: test:programbench:grok | :gemma\" >&2 && exit 64'",
+		"test:programbench:grok": "bash -c 'set -o pipefail; mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.programbench.grok test/programbench/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/programbench_grok_$(date +%Y%m%dT%H%M%S).log' --",
+		"test:programbench:gemma": "bash -c 'set -o pipefail; mkdir -p /tmp/rummy_test_diag && node --env-file-if-exists=.env.example --env-file-if-exists=.env --env-file-if-exists=.env.programbench.gemma test/programbench/runner.js \"$@\" 2>&1 | tee /tmp/rummy_test_diag/programbench_gemma_$(date +%Y%m%dT%H%M%S).log' --",
 		"test:programbench:eval": "bash -c 'cd test/programbench && . .venv/bin/activate && programbench eval \"$@\"' --",
 		"test:programbench:clean": "rm -rf test/programbench/results/*/",
 		"test:clear": "rm -rf /tmp/rummy_test_diag /tmp/rummy_test_*.db /tmp/rummy_test_*.db-shm /tmp/rummy_test_*.db-wal /tmp/rummy-stories-*",

package/service.js

@@ -112,24 +112,32 @@ async function main() {
 	// 6. Initialize plugins (register schemes)
 	await initPlugins(db, hooks, pluginInstances);
 
-	// 7. Bootstrap models from env vars
+	// 7. Reconcile models to env. The env cascade is the single source of
+	// truth for app configuration: every `RUMMY_MODEL_<alias>=...` becomes
+	// (or refreshes) a row in the `models` table, and every row whose
+	// alias is NOT in the current env is dropped. No accumulated cruft
+	// from prior sessions; no surprises at the CLI surface.
 	{
-		const modelAliases = [];
+		const envAliases = new Set();
 		for (const key of Object.keys(process.env)) {
 			if (!key.startsWith("RUMMY_MODEL_")) continue;
 			const alias = key.replace("RUMMY_MODEL_", "");
 			const actual = process.env[key];
 			const contextEnv = process.env[`RUMMY_CONTEXT_${alias}`];
 			const context_length = contextEnv ? Number.parseInt(contextEnv, 10) : null;
-			await db.upsert_model.get({
-				alias,
-				actual,
-				context_length,
-			});
-			modelAliases.push(alias);
+			await db.upsert_model.get({ alias, actual, context_length });
+			envAliases.add(alias);
 		}
-		if (modelAliases.length > 0) {
-			console.log(`[RUMMY] Models: ${modelAliases.join(", ")}`);
+		const dbRows = await db.get_models.all({ limit: null, offset: null });
+		for (const row of dbRows) {
+			if (!envAliases.has(row.alias)) {
+				await db.delete_model.run({ alias: row.alias });
+			}
+		}
+		if (envAliases.size > 0) {
+			console.log(
+				`[RUMMY] Models: ${[...envAliases].toSorted().join(", ")}`,
+			);
 		}
 	}
 

package/src/agent/AgentLoop.js

@@ -156,11 +156,7 @@ export default class AgentLoop {
 				context_limit: contextLimit,
 			});
 			await this.#entries.forkEntries(existingRun.id, runRow.id);
-			// Absolute turn numbering across the lineage; SPEC
-			// §budget_enforcement. Without this, the fork's first
-			// dispatch lands at turn 1 while inherited run_views carry
-			// parent-side turn values, and the budget grinder's
-			// `current_turn − 1` rule sees nothing meaningful.
+			// Absolute turn numbering across the lineage; SPEC §budget_enforcement.
 			await this.#entries.setNextTurn(runRow.id, existingRun.next_turn);
 			await this.#writeRunEntry(runRow.id, alias, prompt, {
 				projectId,
@@ -693,14 +689,9 @@ export default class AgentLoop {
 
 		const nextTurn = runRow.next_turn;
 
-		// Resolve the owning loop_id BEFORE writing the prompt entry so
-		// it lands with correct loop scope. Active run → reuse the
-		// running loop; otherwise enqueue the next loop and write the
-		// prompt with the new loop's id.
+		// Resolve loop_id before writing the prompt entry so loop scope is correct.
 		let loopId;
 		if (this.#activeRuns.has(runRow.id)) {
-			// Active runs have exactly one loop at status=102 by the
-			// loops table invariant — trust the contract.
 			const currentLoop = await this.#db.get_current_loop.get({
 				run_id: runRow.id,
 			});

package/src/agent/ContextAssembler.js

@@ -1,4 +1,9 @@
-// Orchestrates assembly.system / assembly.user filter chains; plugins do all rendering.
+import {
+	ceiling,
+	computePacketTokens,
+	substituteBudgetPlaceholders,
+} from "../plugins/budget/budget.js";
+
 export default class ContextAssembler {
 	static async assembleFromTurnContext(
 		rows,
@@ -13,7 +18,6 @@ export default class ContextAssembler {
 		} = {},
 		hooks,
 	) {
-		// Loop boundary from active prompt; absent on turn 1 before prompt plugin's turn.started.
 		const promptEntry = rows.findLast(
 			(r) => r.category === "prompt" && r.scheme === "prompt",
 		);
@@ -32,7 +36,34 @@ export default class ContextAssembler {
 		};
 
 		const system = await hooks.assembly.system.filter(systemPrompt, ctx);
-		const user = await hooks.assembly.user.filter("", ctx);
+		const userWithPlaceholders = await hooks.assembly.user.filter("", ctx);
+
+		// Iterate to a fixed point: substituted numbers are shorter than the
+		// placeholders, so the re-measured packet shifts slightly. Converges
+		// in 1-2 passes (only the digit-count varies). SPEC §token_accounting.
+		let tokenUsage = computePacketTokens({
+			system,
+			user: userWithPlaceholders,
+		});
+		let tokensFree = contextSize
+			? Math.max(0, ceiling(contextSize) - tokenUsage)
+			: 0;
+		let user = substituteBudgetPlaceholders(userWithPlaceholders, {
+			tokenUsage,
+			tokensFree,
+		});
+		for (let i = 0; i < 5; i++) {
+			const measured = computePacketTokens({ system, user });
+			if (measured === tokenUsage) break;
+			tokenUsage = measured;
+			tokensFree = contextSize
+				? Math.max(0, ceiling(contextSize) - tokenUsage)
+				: 0;
+			user = substituteBudgetPlaceholders(userWithPlaceholders, {
+				tokenUsage,
+				tokensFree,
+			});
+		}
 
 		return [
 			{ role: "system", content: system },

package/src/agent/Entries.js

@@ -2,18 +2,10 @@ import slugify from "../sql/functions/slugify.js";
 import { EntryOverflowError, PermissionError } from "./errors.js";
 import encodeSegment from "./pathEncode.js";
 
-// Update entry bodies are promised ≤ 80 chars to clients (run summary
-// payload, model-facing <log> rendering). Mirror of SUMMARY_MAX_CHARS:
-// the boundary chops + emits a soft error so the violation is visible
-// without crashing the run. Lives here because Entries.update is the
-// canonical persistence boundary all callers fund-route through.
 const UPDATE_BODY_MAX = 80;
 
-// SQLite surfaces the CHECK as either err.code === "SQLITE_CONSTRAINT_CHECK"
-// or an Error whose message names the failing column. Both forms appear in
-// the wild depending on the driver build, so we match defensively.
-// Caller-side contract: only invoked from a SQL try/catch, so err is always
-// an Error instance — err.message is a string (possibly empty), not undefined.
+// SQLite surfaces the body-length CHECK as either an error code or message;
+// match both because the driver build varies in the wild.
 function isBodyOverflow(err) {
 	if (!err) return false;
 	if (err.code === "SQLITE_CONSTRAINT_CHECK") return true;
@@ -26,16 +18,10 @@ function translateBodyOverflow(err, path, body) {
 	return new EntryOverflowError(path, size);
 }
 
-// Already-an-error path: log://turn_N/error/<slug>. The auto-failure
-// hook below skips these to break the recursion (error.log.emit's
-// handler ALSO writes state=failed when materializing its own entry).
+// Skipped by the auto-failure hook to break recursion (error.log emits its own).
 const ERROR_PATH_RE = /^log:\/\/turn_\d+\/error\//;
 
-// Streaming data channels for env/sh actions (env://turn_N/cmd_K,
-// sh://turn_N/cmd_K). Their failure is already captured by the parent
-// log://turn_N/<scheme>/<slug> action entry's auto-emit; emitting again
-// for each channel produces redundant duplicates with empty-body
-// fallback messages.
+// Stream channels — failure already captured by the parent action entry.
 const CHANNEL_PATH_RE = /^(env|sh):\/\/turn_\d+\//;
 
 export default class Entries {
@@ -49,23 +35,10 @@ export default class Entries {
 	#seq = 0;
 	#pendingResolutions = new Map();
 
-	// onError is the centralized site for storage-layer rejections that
-	// should surface to the model as strikes rather than crash the run.
-	// Today: EntryOverflowError (RUMMY_ENTRY_SIZE_MAX CHECK violations).
-	// When onError is supplied, set() catches the typed error, dispatches
-	// it to the callback (which emits hooks.error.log → 413 strike), and
-	// returns silently — callers don't need to handle storage-layer
-	// rejections at every write site. When onError is null (e.g. unit
-	// tests with a bare Entries), the error propagates as before.
-	//
-	// onFailed is the universal failure-rendering enforcer: every
-	// transition to state="failed" on a non-error path fires this
-	// callback so a SEPARATE log://turn_N/error/<slug> entry is created
-	// alongside the action entry. Without this, plugins that record
-	// failure via entries.set({state: "failed", ...}) leave nothing for
-	// the model to recognize as an error — failure encodes only as tiny
-	// JSON metadata indistinguishable from a successful entry. The
-	// callback wires to hooks.error.log.emit (see ProjectAgent).
+	// onError: catches storage-layer rejections (EntryOverflowError) and routes
+	// to error.log → strike; callers don't handle at each write site.
+	// onFailed: every state="failed" on a non-error path fires this so a
+	// sibling log://turn_N/error/ entry materializes (model-facing).
 	constructor(
 		db,
 		{
@@ -82,7 +55,6 @@ export default class Entries {
 		this.#onSoftError = onSoftError;
 	}
 
-	// Populate the scheme cache; idempotent, lazy on first need.
 	async loadSchemes(db) {
 		const rows = await (db || this.#db).get_all_schemes.all();
 		this.#schemes.clear();
@@ -111,11 +83,7 @@ export default class Entries {
 	static normalizePath(path) {
 		if (!path) return path;
 		if (!path.includes("://")) {
-			// Bare file path: strip a single leading `./` for canonical
-			// form. `./main.go` and `main.go` must resolve to the same
-			// entry — otherwise SEARCH/REPLACE edits on `./main.go`
-			// land in a phantom entry while reads of `main.go` see the
-			// original, and the model can't reconcile.
+			// Strip leading `./` so `./main.go` and `main.go` are one entry.
 			if (path.startsWith("./")) return path.slice(2);
 			return path;
 		}
@@ -123,7 +91,6 @@ export default class Entries {
 		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(encodeSegment).join("/")}`;
 		} catch {
@@ -148,12 +115,7 @@ export default class Entries {
 		return `${candidate}_${++this.#seq}`;
 	}
 
-	// Single namespace log://turn_N/action/slug. slug is built via slugify
-	// (80-char cap + integer tie-breaker on collision) — same contract as
-	// slugPath. Plugins (including externals) can trust that any target
-	// they pass will produce a bounded, unique log path, regardless of
-	// the target's length or character composition. Full payload always
-	// belongs in the entry body, not the slug.
+	// log://turn_N/action/slug — slugify caps + collision-suffixes.
 	async logPath(runId, turn, action, target) {
 		const slug = target == null ? "" : slugify(String(target));
 		const base = slug
@@ -168,7 +130,7 @@ export default class Entries {
 	}
 
 	async slugPath(runId, scheme, content, tags) {
-		// tags > content > empty; slugify("") yields "" and we sequence-only.
+		// tags > content > sequence-only.
 		let source = "";
 		if (tags) source = tags;
 		else if (content) source = content;
@@ -187,7 +149,6 @@ export default class Entries {
 		return `${prefix}${base}_${++this.#seq}`;
 	}
 
-	// Scheme's scope/writers/category; bare paths default to run + model/plugin.
 	async #schemeRules(scheme) {
 		await this.#ensureSchemes();
 		const row = scheme ? this.#schemes.get(scheme) : null;
@@ -225,22 +186,14 @@ export default class Entries {
 		return `run:${runId}`;
 	}
 
-	// set — create or update an entry; see PLUGINS.md primitives.
 	async set(args) {
 		if (!args.runId) throw new Error("set: runId is required");
 		if (!args.path) throw new Error("set: path is required");
 		try {
 			return await this.#setImpl(args);
 		} catch (err) {
-			// EntryOverflowError: storage-layer CHECK fired. When the host
-			// supplies onError (the production wiring), route the strike
-			// to error.log and return silently — every set() caller in
-			// the codebase becomes overflow-safe without per-site catches.
-			// Without onError (raw unit tests), propagate as before.
+			// EntryOverflowError → error.log when onError is wired.
 			if (err instanceof EntryOverflowError && this.#onError) {
-				// Destructure with the same defaults as #setImpl so the
-				// callback sees the same loopId/turn shape callers wrote
-				// against — no `??` fallback shim, just contract alignment.
 				const { runId, loopId = null, turn = 0 } = args;
 				await this.#onError({
 					runId,
@@ -271,7 +224,6 @@ export default class Entries {
 		loopId = null,
 		writer = "plugin",
 	}) {
-		// Pattern mode is explicit; never inferred from `*` in path.
 		const isPattern = pattern === true || bodyFilter !== null;
 
 		if (isPattern) {
@@ -315,7 +267,6 @@ export default class Entries {
 		const normalized = Entries.normalizePath(path);
 		const scheme = Entries.scheme(normalized);
 
-		// Append mode: streaming body growth on an existing entry.
 		if (append) {
 			if (body == null) throw new Error("set: append requires body");
 			try {
@@ -331,7 +282,6 @@ export default class Entries {
 			return;
 		}
 
-		// Body-less state or visibility change on an existing entry.
 		if (body == null) {
 			if (state != null) {
 				await this.#db.resolve_known_entry_view.run({
@@ -371,13 +321,11 @@ export default class Entries {
 			return;
 		}
 
-		// Full write/upsert: body + state + visibility + attributes.
 		const { kind, writers, category } = await this.#schemeRules(scheme);
 		if (!writers.includes(writer)) {
 			throw new PermissionError(scheme, writer, writers);
 		}
 		const scope = this.#resolveScope(kind, runId, projectId);
-		// Inject `action` only when caller passes attributes; null means COALESCE preserves existing.
 		const effectiveAttributes = attributes ? { ...attributes } : null;
 		if (scheme === "log" && effectiveAttributes) {
 			const m = normalized.match(/^log:\/\/turn_\d+\/([^/]+)\//);
@@ -398,11 +346,7 @@ export default class Entries {
 			throw translateBodyOverflow(err, normalized, body);
 		}
 		const effectiveState = state === undefined ? "resolved" : state;
-		// Visibility resolution: explicit > preserve-existing > scheme-default.
-		// A body update without visibility= must NOT silently reset visibility
-		// to the scheme default — that would hide content the model just
-		// promoted (e.g. a model <get>'d file then <set> SEARCH/REPLACE
-		// would lose its visible status). Preserve what's there.
+		// Visibility: explicit > preserve-existing > scheme-default.
 		let effectiveVisibility;
 		if (visibility !== undefined) {
 			effectiveVisibility = visibility;
@@ -439,17 +383,10 @@ export default class Entries {
 		}
 	}
 
-	// Fire onFailed for any state→failed transition on a non-error path.
-	// The auto-emit creates a sibling log://turn_N/error/<slug> entry so
-	// the failure appears in the model's <log> as a category-distinct
-	// item, not just metadata buried in the action's own log entry.
 	async #fireFailed({ runId, turn, loopId, path, body, outcome }) {
 		if (!this.#onFailed) return;
 		if (ERROR_PATH_RE.test(path)) return;
 		if (CHANNEL_PATH_RE.test(path)) return;
-		// Body-less state changes don't carry a message; fall back to the
-		// outcome string (or the path itself) so the error entry has a
-		// recognizable slug instead of an empty one.
 		let message = body;
 		if (!message) {
 			if (outcome) message = `failed: ${outcome}`;
@@ -465,7 +402,6 @@ export default class Entries {
 		});
 	}
 
-	// get — promote entry(ies); see PLUGINS.md primitives.
 	async get({
 		runId,
 		turn = 0,
@@ -492,7 +428,6 @@ export default class Entries {
 		this.#emitChanged(runId, path, "promote");
 	}
 
-	// rm — remove entry view(s); see PLUGINS.md primitives.
 	async rm({ runId, path, bodyFilter = null, filesOnly = false }) {
 		if (!runId) throw new Error("rm: runId is required");
 		if (!path) throw new Error("rm: path is required");
@@ -517,7 +452,6 @@ export default class Entries {
 		this.#emitChanged(runId, path, "remove");
 	}
 
-	// cp — copy an entry to a new path; see PLUGINS.md primitives.
 	async cp({
 		runId,
 		turn = 0,
@@ -544,7 +478,6 @@ export default class Entries {
 		});
 	}
 
-	// mv — rename (cp + rm).
 	async mv({
 		runId,
 		turn = 0,
@@ -570,10 +503,7 @@ export default class Entries {
 		await this.rm({ runId, path: from });
 	}
 
-	// update — once-per-turn lifecycle signal; see PLUGINS.md.
-	// Body chopped to UPDATE_BODY_MAX with a soft error fire so clients
-	// always receive ≤ 80 chars and the violation is visible to the model
-	// next turn. Applies to ALL callers — system, plugin, model.
+	// Inner text capped at UPDATE_BODY_MAX with soft-error emission.
 	async update({
 		runId,
 		turn = 0,
@@ -643,7 +573,7 @@ export default class Entries {
 	}
 
 	async waitForResolution(runId, path) {
-		// Pre-check: yolo's synchronous resolver may have already flipped state, no drain will fire.
+		// Pre-check: yolo may have already flipped state synchronously.
 		const current = await this.getState(runId, path);
 		if (
 			current &&
@@ -702,7 +632,6 @@ export default class Entries {
 		return new Set(rows.map((r) => r.body));
 	}
 
-	// Unknown entries in DB order; rows include path + body.
 	async getUnknowns(runId) {
 		return this.#db.get_unknowns.all({ run_id: runId });
 	}
@@ -721,7 +650,7 @@ export default class Entries {
 		});
 	}
 
-	// SELECT-then-UPDATE: SQLite RETURNING can't cross to the view layer.
+	// SELECT-then-UPDATE: RETURNING can't cross to the view layer in SQLite.
 	async demoteTurnEntries(runId, turn) {
 		const targets = await this.#db.get_turn_demotion_targets.all({
 			run_id: runId,
@@ -731,12 +660,10 @@ export default class Entries {
 		return targets;
 	}
 
-	// Plugin-facing run lookup; avoids reaching into core.db.
 	async getRun(runId) {
 		return this.#db.get_run_by_id.get({ id: runId });
 	}
 
-	// Plugin-facing turn-stats write.
 	async updateTurnStats(stats) {
 		return this.#db.update_turn_stats.run(stats);
 	}

package/src/agent/ProjectAgent.js

@@ -27,20 +27,7 @@ export default class ProjectAgent {
 					status: 413,
 					attributes: { path: error.path, size: error.size },
 				}),
-			// Universal failure-rendering: every state→failed transition on
-			// a non-error path fires error.log.emit so a sibling
-			// log://turn_N/error/<slug> entry is created. The error plugin's
-			// own #onErrorLog handler also writes state=failed on the error
-			// entry; Entries.#fireFailed skips when path matches
-			// log://turn_*/error/* so no recursion.
-			//
-			// soft=true when the outcome is in SOFT_FAILURE_OUTCOMES
-			// (not_found, conflict): the error entry still renders so the
-			// model can read the finding, but error.log skips turnErrors++
-			// so the strike accumulator doesn't penalize legitimate
-			// state-discovery via the auto-emit path. Without this, soft
-			// outcomes count as strikes on the turnErrors path even though
-			// recordedFailed correctly excludes them.
+			// soft=true for SOFT_FAILURE_OUTCOMES so auto-emitted errors don't strike.
 			onFailed: ({ runId, loopId, turn, sourcePath, body, outcome }) =>
 				hooks.error.log.emit({
 					store: this.#entries,
@@ -131,7 +118,6 @@ export default class ProjectAgent {
 		return this.#agentLoop.inject(run, message, mode, options);
 	}
 
-	// Create/fork the run row synchronously; caller follows up with ask/act.
 	async ensureRun(projectId, model, run, prompt, options = {}) {
 		return this.#agentLoop.ensureRun(projectId, model, run, prompt, options);
 	}
@@ -144,7 +130,6 @@ export default class ProjectAgent {
 		this.#agentLoop.abort(runId);
 	}
 
-	// Abort all in-flight runs and drain so the event loop can exit.
 	async shutdown() {
 		await this.#agentLoop.abortAll();
 	}

package/src/agent/TurnExecutor.js

@@ -89,10 +89,6 @@ export default class TurnExecutor {
 
 		await this.#hooks.processTurn(rummy);
 
-		// Run persona feeds the assembly.system chain (persona plugin's
-		// participant at priority 150). Loaded once per turn; the system
-		// prompt is built directly by the chain — no resolveSystemPrompt
-		// indirection.
 		const runRow = await this.#db.get_run_by_id.get({ id: currentRunId });
 
 		const budgetCtx = {
@@ -164,9 +160,10 @@ export default class TurnExecutor {
 				{
 					temperature: options?.temperature,
 					signal,
-					// Per-run stable identifier for provider-side prompt caching
-					// (xAI prompt_cache_key, OpenAI prompt_cache_key, etc.).
+					// Stable per-run id for provider prompt caching.
 					runAlias: runRow?.alias || `run_${currentRunId}`,
+					// Real prompt_tokens for accurate max_tokens derivation.
+					lastPromptTokens: initial.lastContextTokens,
 				},
 			);
 		} catch (err) {
@@ -189,15 +186,8 @@ export default class TurnExecutor {
 					contextSize,
 				};
 			}
-			// LLM fetch hit its per-call ceiling (provider's
-			// AbortSignal.timeout(FETCH_TIMEOUT) fired). Convert to a
-			// 504 strike so the loop continues — one timed-out turn is
-			// recoverable; MAX_STRIKES in a row abandon at 499. Without
-			// this catch the AbortError escapes to AgentLoop's outer
-			// catch and the run dies at status=500, losing all prior
-			// productive turns. signal.aborted being true means OUR
-			// controller fired (drain), not a fetch timeout — re-throw
-			// so AgentLoop ends the run cleanly at 499.
+			// LLM fetch hit per-call ceiling → 504 strike (recoverable).
+			// signal.aborted is OUR drain — re-throw to end run at 499.
 			if (err?.name === "TimeoutError" || err?.name === "AbortError") {
 				if (signal?.aborted) throw err;
 				await this.#hooks.error.log.emit({
@@ -234,10 +224,8 @@ export default class TurnExecutor {
 		const content = responseMessage?.content ? responseMessage.content : "";
 
 		const { commands, warnings, unparsed } = XmlParser.parse(content);
-		// Parser warnings are recovered emissions — the parser already
-		// corrected a mismatched/unclosed tag and produced commands. Log
-		// them so the model sees what happened, but don't strike: the
-		// turn's productive work is intact.
+		// Parser warnings are recovered emissions — visible to the model,
+		// no strike.
 		for (const w of warnings) {
 			await this.#hooks.error.log.emit({
 				store: this.#entries,
@@ -260,28 +248,11 @@ export default class TurnExecutor {
 			});
 		}
 
-		// Contract floor: a turn without <update> is malformed; refuse to
-		// honor its side effects. Repetition loops, partial outputs, and
-		// other broken responses commonly emit actions without closure;
-		// dispatching them anyway lets a broken turn corrupt state. Skip
-		// recording AND dispatching when commands are present but no
-		// <update> closes the turn — the strike system still fires via
-		// turnErrors, model retries cleanly next turn.
+		// Skip dispatch when commands but no <update> — broken turn, no side
+		// effects. The missing-update strike fires from update.resolve below.
 		const hasUpdate = commands.some((c) => c.name === "update");
 		const skipDispatch = commands.length > 0 && !hasUpdate;
-		if (skipDispatch) {
-			await this.#hooks.error.log.emit({
-				store: this.#entries,
-				runId: currentRunId,
-				turn,
-				loopId: currentLoopId,
-				message:
-					"Turn rejected: no <update> emitted. Actions are not honored unless the turn ends with an <update>.",
-				status: 422,
-			});
-		}
 
-		// Layer plugin reasoning contributions onto the API-provided seed.
 		if (responseMessage) {
 			const seed = responseMessage.reasoning_content
 				? responseMessage.reasoning_content
@@ -306,7 +277,6 @@ export default class TurnExecutor {
 			userMsg: userMsg?.content,
 		});
 
-		// PHASE 1: RECORD (skipped when skipDispatch — broken turn, no side effects)
 		const recorded = [];
 		if (!skipDispatch) {
 			for (const cmd of commands) {
@@ -321,7 +291,7 @@ export default class TurnExecutor {
 			}
 		}
 
-		// PHASE 2: DISPATCH — sequential; abort-after-failure; proposals notify-and-await.
+		// Sequential dispatch; abort-after-failure; proposals notify-and-await.
 		let abortAfter = null;
 
 		for (const entry of recorded) {
@@ -346,10 +316,7 @@ export default class TurnExecutor {
 			try {
 				await this.#hooks.tools.dispatch(entry.scheme, entry, rummy);
 			} catch (dispatchErr) {
-				// PermissionError is the model attempting a documented-forbidden
-				// write (e.g. <set path="prompt://1"> with body). Surface as a
-				// soft 403 so the model can adjust on the next turn; do not
-				// abort sibling entries — the rest of the turn was valid.
+				// PermissionError → soft 403, no sibling abort.
 				if (dispatchErr instanceof PermissionError) {
 					await this.#hooks.error.log.emit({
 						store: this.#entries,
@@ -375,7 +342,6 @@ export default class TurnExecutor {
 			await this.#hooks.tool.after.emit({ entry, rummy });
 			await this.#hooks.entry.created.emit(entry);
 
-			// Plugins materialize pending proposals (e.g. set search/replace → 202).
 			await this.#hooks.proposal.prepare.emit({ rummy, recorded: [entry] });
 
 			const proposed = await this.#entries.getUnresolved(currentRunId);
@@ -388,8 +354,6 @@ export default class TurnExecutor {
 				});
 				await this.#entries.waitForResolution(currentRunId, p.path);
 				const resolved = await this.#entries.getState(currentRunId, p.path);
-				// Failure surfaces in the proposal entry itself; abort cascade
-				// triggers the trailing-action "Aborted — preceding <X>" body.
 				if (resolved?.status >= 400) abortAfter = entry.scheme;
 			}
 
@@ -438,17 +402,13 @@ export default class TurnExecutor {
 		return turnResult;
 	}
 
-	// Record a parsed command; returns the entry descriptor or rejects on bad shapes.
 	async #record(runId, loopId, turn, mode, cmd) {
 		const scheme = cmd.name;
 		let rawTarget = "";
 		if (cmd.path) rawTarget = cmd.path;
 		else if (cmd.command) rawTarget = cmd.command;
 		else if (cmd.question) rawTarget = cmd.question;
-		// Reject reasoning-bleed in path-shaped fields only. cmd.command
-		// (sh/env shell scripts) and cmd.question (ask_user prose) are
-		// content fields where newlines/tabs/length are legitimate; the
-		// slugifier sanitizes them downstream when deriving the log path.
+		// Reject reasoning-bleed in path-shaped fields only.
 		if (cmd.path && (cmd.path.length > 2048 || /\p{Cc}/u.test(cmd.path))) {
 			const rejectPath = await this.#entries.logPath(
 				runId,