@possumtech/rummy 2.0.1 → 2.2.0

package/src/agent/errors.js

@@ -1,22 +1,51 @@
-/**
- * Typed errors for the agent/Entries layer. Callers catch by type,
- * not by regex.
- */
+// Outcomes that record a failure but don't strike — findings the model
+// adapts to, not contract violations. `not_found` (model acted on an
+// entry that doesn't exist) and `conflict` (SEARCH text didn't match
+// current body) are recoverable: read the new state, try again.
+// `unparsed` (free text outside any tool tag — comments, "thinking
+// out loud" between tool calls) is non-actionable but not malicious;
+// the empty-turn failure mode is already caught by update plugin's
+// 422 "Missing update", so striking unparsed too is duplicative.
+// Hard outcomes (validation, permission, exit:N) DO strike. Shared
+// between error.js's verdict accumulator (recordedFailed gate) and
+// Entries' auto-failure hook (passes soft=true so error.log.emit
+// skips turn errors increment when the outcome is soft).
+export const SOFT_FAILURE_OUTCOMES = new Set([
+	"not_found",
+	"conflict",
+	"unparsed",
+]);
 
-/**
- * Thrown when a writer tier isn't permitted to write to a scheme.
- * See SPEC writer_tiers: schemes declare writable_by = subset of
- * {system, plugin, client, model}. A write from an excluded tier
- * rejects with this error.
- */
+// Writer tier excluded from scheme.writable_by; see SPEC writer_tiers.
 export class PermissionError extends Error {
 	constructor(scheme, writer, allowed) {
+		// Paths without `://` have a null scheme. Report null verbatim
+		// rather than substituting a plausible-sounding "file" — there is
+		// no scheme called "file" and the error must reflect actual state.
+		const schemeLabel = scheme === null ? "(none)" : scheme;
 		super(
-			`403: writer "${writer}" not permitted for scheme "${scheme ?? "file"}" (allowed: ${allowed.join(", ")})`,
+			`403: writer "${writer}" not permitted for scheme "${schemeLabel}" (allowed: ${allowed.join(", ")})`,
 		);
 		this.name = "PermissionError";
-		this.scheme = scheme ?? "file";
+		this.scheme = scheme;
 		this.writer = writer;
 		this.allowed = [...allowed];
 	}
 }
+
+// Body length exceeded the entries.body CHECK constraint (RUMMY_ENTRY_SIZE_MAX
+// at create-time). Surfaced as a 413 strike. The cap value lives only in the
+// schema — JS does not duplicate it, because the database persists across
+// rummy invocations and the env var that built the schema may differ from
+// the env var seen by the running instance. Reporting body size is enough
+// for the model to adapt; operators can read the cap from the schema.
+export class EntryOverflowError extends Error {
+	constructor(path, size) {
+		super(
+			`413: entry "${path}" body ${size} bytes exceeds RUMMY_ENTRY_SIZE_MAX`,
+		);
+		this.name = "EntryOverflowError";
+		this.path = path;
+		this.size = size;
+	}
+}

package/src/agent/httpStatus.js

@@ -1,22 +1,4 @@
-/**
- * Map the entry-layer (state, outcome) tuple to an HTTP status number for
- * model-facing tag rendering.
- *
- * Model-facing tags still carry `status="NNN"` because the model's
- * vocabulary (instructions + tooldocs + training) is HTTP-shaped. The DB
- * stores categorical state + textual outcome (see SPEC entries); this helper
- * is the one-way translation for rendering.
- *
- * Outcome strings prefixed with a 3-digit HTTP code (e.g.
- * `"overflow:413:..."` or `"permission:403:..."`) extract the code
- * verbatim. Otherwise state maps to a canonical HTTP:
- *
- *   resolved   → 200
- *   proposed   → 202
- *   streaming  → 102
- *   cancelled  → 499
- *   failed     → 500 (unless outcome carries a code)
- */
+// (state, outcome) → HTTP status for model-facing tags; outcome's 3-digit prefix wins.
 export function stateToStatus(state, outcome = null) {
 	if (outcome) {
 		const match = /(\d{3})/.exec(outcome);

package/src/agent/known_queries.sql

@@ -1,7 +1,7 @@
 -- PREP: get_known_entries
 SELECT
 	path, scheme, state, outcome, visibility, body, turn, hash
-	, attributes, countTokens(body) AS tokens, scope, loop_id
+	, attributes, scope, loop_id, countTokens(body) AS tokens
 FROM known_entries
 WHERE run_id = :run_id
 ORDER BY path;

package/src/agent/known_store.sql

@@ -226,9 +226,11 @@ WHERE run_id = :run_id AND entry_id IN (
 -- Default excludes audit schemes (system://, reasoning://, model://, user://,
 -- assistant://, content://, instructions://) so model-facing tools never leak
 -- internal entries. Internal callers that need them pass include_audit_schemes=1.
+-- :since filters to entries created after a given id; when set, results order
+-- by id (insertion order) for streaming consumers; otherwise by path.
 SELECT
-	e.path, e.body, e.scheme, rv.state, rv.outcome, rv.visibility
-	, countTokens(e.body) AS tokens, e.attributes
+	e.id, e.path, e.body, e.scheme, rv.state, rv.outcome, rv.visibility, rv.turn
+	, e.attributes, countTokens(e.body) AS tokens
 FROM run_views AS rv
 JOIN entries AS e ON e.id = rv.entry_id
 JOIN schemes AS s ON s.name = COALESCE(e.scheme, 'file')
@@ -237,7 +239,10 @@ WHERE
 	AND hedmatch(:path, e.path)
 	AND (:body IS NULL OR hedsearch(:body, e.body))
 	AND (:include_audit_schemes IS NOT NULL OR s.model_visible = 1)
-ORDER BY e.path
+	AND (:since IS NULL OR e.id > :since)
+ORDER BY
+	CASE WHEN :since IS NOT NULL THEN e.id ELSE 0 END,
+	e.path
 LIMIT
 	COALESCE(:limit, -1)
 	OFFSET COALESCE(:offset, 0);
@@ -287,9 +292,7 @@ WHERE run_id = :run_id AND entry_id IN (
 -- matches the old RETURNING (path, tokens) for caller compatibility.
 -- State filter: skip failed/cancelled entries (they're already not
 -- contributing visible context — demoting them would be misleading).
--- Scheme filter: skip known/unknown — these are the model's deliverables,
--- not housekeeping. Auto-demoting just-created knowns punishes the
--- correct Distill+Demote pattern.
+-- All schemes participate uniformly per SPEC §budget_enforcement.
 SELECT e.path, countTokens(e.body) AS tokens
 FROM run_views AS rv
 JOIN entries AS e ON e.id = rv.entry_id
@@ -297,15 +300,12 @@ WHERE
 	rv.run_id = :run_id
 	AND rv.turn = :turn
 	AND rv.visibility = 'visible'
-	AND rv.state NOT IN ('failed', 'cancelled')
-	AND e.scheme NOT IN ('known', 'unknown');
+	AND rv.state NOT IN ('failed', 'cancelled');
 
 -- PREP: demote_turn_entries
 -- View-layer only — visibility lives on run_views. State untouched.
 -- Call get_turn_demotion_targets first if you need the list of what
 -- was demoted (used by budget plugin for the overflow error body).
--- Scheme filter mirrors get_turn_demotion_targets — never demote the
--- model's deliverables (known/unknown) along with housekeeping.
 UPDATE run_views
 SET
 	visibility = 'summarized'
@@ -314,38 +314,4 @@ WHERE
 	run_id = :run_id
 	AND turn = :turn
 	AND visibility = 'visible'
-	AND state NOT IN ('failed', 'cancelled')
-	AND NOT EXISTS (
-		SELECT 1
-		FROM entries AS e
-		WHERE
-			e.id = run_views.entry_id
-			AND e.scheme IN ('known', 'unknown')
-	);
-
--- PREP: get_run_visible_targets
--- All visible entries across the run, oldest promotion first. Used by
--- budget postDispatch as the fallback demotion set when this-turn
--- demotion yields nothing but the packet still overflows (promotions
--- from prior turns the model forgot to demote themselves).
-SELECT e.path, countTokens(e.body) AS tokens, rv.turn
-FROM run_views AS rv
-JOIN entries AS e ON e.id = rv.entry_id
-WHERE
-	rv.run_id = :run_id
-	AND rv.visibility = 'visible'
-	AND rv.state NOT IN ('failed', 'cancelled')
-ORDER BY rv.turn, e.id;
-
--- PREP: demote_run_visible
--- Broad cross-turn demotion. Separate prep from demote_turn_entries
--- so the caller's intent (surgical this-turn vs fallback all-visible)
--- stays explicit.
-UPDATE run_views
-SET
-	visibility = 'summarized'
-	, updated_at = CURRENT_TIMESTAMP
-WHERE
-	run_id = :run_id
-	AND visibility = 'visible'
 	AND state NOT IN ('failed', 'cancelled');

package/src/agent/materializeContext.js

@@ -1,14 +1,21 @@
+import { SUMMARY_MAX_CHARS } from "../plugins/helpers.js";
 import ContextAssembler from "./ContextAssembler.js";
 import { countLines, countTokens } from "./tokens.js";
 
-/**
- * Rebuild turn_context from v_model_context, then assemble messages.
- * Called at turn start and again by the budget plugin when it needs a
- * fresh measurement after mutating visibility.
- */
+// Defensive cap: model-written summary projections (knowns, unknowns,
+// log actions, etc.) must produce ≤ SUMMARY_MAX_CHARS — the contract
+// floor for terse model-authored summaries. File-scheme entries are
+// exempt: their summarized projection is a structural derivative
+// (rummy.repo's symbol map), bounded by the file's actual complexity,
+// not by writer discipline. Truncating symbol data at 500 chars
+// destroys its utility. Files either render blank (no symbols
+// extracted) or render their full symbol map.
+
+// Rebuild turn_context from v_model_context and assemble messages.
 export default async function materializeContext({
 	db,
 	hooks,
+	entries,
 	runId,
 	loopId,
 	turn,
@@ -16,22 +23,16 @@ export default async function materializeContext({
 	mode,
 	toolSet,
 	contextSize,
-	demoted,
+	persona = "",
 }) {
 	await db.clear_turn_context.run({ run_id: runId, turn });
 	const viewRows = await db.get_model_context.all({ run_id: runId });
-	// Per-entry token accounting (see SPEC @token_accounting): captured
-	// here while we still have the raw body, then merged onto rows after
-	// the read-back roundtrip through turn_context.
+	// Per-entry token accounting; merged back after the turn_context roundtrip.
 	const tokenAccounting = new Map();
 	for (const row of viewRows) {
-		// schemeOf() yields NULL (or "") for bare file paths — translate
-		// to "file" so the view lookup finds the file scheme handler.
 		const scheme = row.scheme ? row.scheme : "file";
 		const attrs = row.attributes ? JSON.parse(row.attributes) : null;
-		// Log entries live at log://turn_N/action/slug. Dispatch projection
-		// to the action plugin's view (set, update, search, etc.) by
-		// extracting the action segment from the path.
+		// Dispatch log entries to their action plugin's view via path segment.
 		let projectionKey = scheme;
 		if (scheme === "log") {
 			const m = row.path.match(/^log:\/\/turn_\d+\/([^/]+)\//);
@@ -48,14 +49,36 @@ export default async function materializeContext({
 			...baseEntry,
 			visibility: "visible",
 		});
-		const summarizedProjection = await hooks.tools.view(projectionKey, {
+		const rawSummarizedProjection = await hooks.tools.view(projectionKey, {
 			...baseEntry,
 			visibility: "summarized",
 		});
+		let summarizedProjection = rawSummarizedProjection;
+		if (
+			scheme !== "file" &&
+			typeof summarizedProjection === "string" &&
+			summarizedProjection.length > SUMMARY_MAX_CHARS
+		) {
+			summarizedProjection = summarizedProjection.slice(0, SUMMARY_MAX_CHARS);
+			await hooks.error.log.emit({
+				store: entries,
+				runId,
+				turn,
+				loopId,
+				message: `${row.path} summarized projection overflow`,
+				soft: true,
+			});
+		}
 		const vTokens = countTokens(visibleProjection);
 		const sTokens = countTokens(summarizedProjection);
 		const vLines = countLines(visibleProjection);
-		tokenAccounting.set(row.path, { vTokens, sTokens, vLines });
+		tokenAccounting.set(row.path, {
+			vTokens,
+			sTokens,
+			vLines,
+			vBody: visibleProjection,
+			sBody: summarizedProjection,
+		});
 		const projectedBody =
 			row.visibility === "visible" ? visibleProjection : summarizedProjection;
 		await db.insert_turn_context.run({
@@ -81,9 +104,10 @@ export default async function materializeContext({
 		row.sTokens = t.sTokens;
 		row.aTokens = t.vTokens - t.sTokens;
 		row.vLines = t.vLines;
+		row.vBody = t.vBody;
+		row.sBody = t.sBody;
 	}
 	const lastCtx = await db.get_last_context_tokens.get({ run_id: runId });
-	// First turn of a new run has no prior context.
 	let lastContextTokens = 0;
 	if (lastCtx) lastContextTokens = lastCtx.context_tokens;
 
@@ -93,10 +117,10 @@ export default async function materializeContext({
 			type: mode,
 			systemPrompt,
 			contextSize,
-			demoted,
 			toolSet,
 			lastContextTokens,
 			turn,
+			persona,
 		},
 		hooks,
 	);

package/src/agent/pathEncode.js

@@ -0,0 +1,5 @@
+// Single source of truth for path-segment encoding: spaces → _, then URL-encode.
+// Used by slugify (for summary-derived slugs) and Entries (for normalize/dedup/logPath).
+export default function encodeSegment(s) {
+	return encodeURIComponent(String(s).replace(/ /g, "_"));
+}

package/src/agent/rummyHome.js

@@ -0,0 +1,9 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// RUMMY_HOME default per README §Installation; resolved here because
+// entrypoints run before env files load.
+export default function resolveRummyHome() {
+	if (process.env.RUMMY_HOME) return process.env.RUMMY_HOME;
+	return join(homedir(), ".rummy");
+}

package/src/agent/runs.sql

@@ -56,6 +56,24 @@ LIMIT
 	OFFSET
 	COALESCE(:offset, 0);
 
+-- PREP: get_run_summary
+-- Per-run aggregation across all turns. LEFT JOIN: a run with zero
+-- recorded turns (e.g. signal abort before first turn) returns 0s,
+-- not NULL.
+SELECT
+	r.model AS model
+	, COUNT(t.id) AS turns
+	, COALESCE(SUM(t.cost), 0) AS cost
+	, COALESCE(SUM(t.prompt_tokens), 0) AS prompt_tokens
+	, COALESCE(SUM(t.cached_tokens), 0) AS cached_tokens
+	, COALESCE(SUM(t.completion_tokens), 0) AS completion_tokens
+	, COALESCE(SUM(t.reasoning_tokens), 0) AS reasoning_tokens
+	, COALESCE(SUM(t.total_tokens), 0) AS total_tokens
+FROM runs AS r
+LEFT JOIN turns AS t ON t.run_id = r.id
+WHERE r.id = :id
+GROUP BY r.id;
+
 -- PREP: rename_run
 UPDATE runs
 SET alias = :new_alias
@@ -92,24 +110,14 @@ SELECT
 FROM run_views
 WHERE run_id = :parent_run_id;
 
--- PREP: archive_prior_prompt_artifacts
--- Multi-prompt sessions accumulate artifacts from prior prompt cycles
--- (consumed prompts, their per-turn logs). These pollute the validator's
--- prior-prompts check on subsequent Deployment landings. Archive all
--- prior prompt:// entries and prior-turn log:// entries when a new
--- prompt arrives. Knowns/unknowns/file entries are untouched — they
--- carry persistent knowledge across cycles. The loop_id IS NULL clause
--- catches forked-in views from a parent run (per fork_known_entries),
--- which represent prior cycles' artifacts inherited into a clean child.
-UPDATE run_views
-SET visibility = 'archived'
-WHERE run_id = :run_id
-	AND visibility != 'archived'
-	AND (turn < :current_turn OR loop_id IS NULL)
-	AND entry_id IN (
-		SELECT id FROM entries
-		WHERE scheme IN ('prompt', 'log')
-	);
+-- PREP: set_next_turn
+-- Forks inherit parent's next_turn so turn numbering is absolute
+-- across the lineage; the budget grinder's `current_turn - 1` rule
+-- then targets parent's last-turn promotions on the fork's first
+-- dispatch. See SPEC §budget_enforcement.
+UPDATE runs
+SET next_turn = :next_turn
+WHERE id = :run_id;
 
 -- PREP: get_active_runs
 SELECT r.id

package/src/agent/tokens.js

@@ -1,12 +1,5 @@
-/**
- * Token estimation. Conservative character-based approximation.
- * RUMMY_TOKEN_DIVISOR controls characters per token.
- * No external dependencies. The budget contract is exact.
- * contextSize is the ceiling. countTokens is the measurement.
- */
-
+// Conservative chars/token approximation; RUMMY_TOKEN_DIVISOR controls the divisor.
 const DIVISOR = Number(process.env.RUMMY_TOKEN_DIVISOR);
-if (!DIVISOR) throw new Error("RUMMY_TOKEN_DIVISOR must be a non-zero number");
 
 export function countTokens(text) {
 	if (!text) return 0;
@@ -15,6 +8,6 @@ export function countTokens(text) {
 
 export function countLines(text) {
 	if (!text) return 0;
-	const newlines = (text.match(/\n/g) || []).length;
+	const newlines = text.split("\n").length - 1;
 	return text.endsWith("\n") ? newlines : newlines + 1;
 }

package/src/agent/turns.sql

@@ -14,6 +14,7 @@ SET
 	, reasoning_tokens = :reasoning_tokens
 	, total_tokens = :total_tokens
 	, cost = :cost
+	, response_metadata = :response_metadata
 WHERE id = :id;
 
 -- PREP: get_run_usage

package/src/hooks/HookRegistry.js

@@ -1,7 +1,4 @@
-/**
- * HookRegistry manages a simple, priority-ordered pipeline of processors.
- * It also supports basic event emitters for side-effects.
- */
+// Priority-ordered processors + filters + events.
 export default class HookRegistry {
 	#processors = [];
 	#events = new Map();
@@ -12,17 +9,11 @@ export default class HookRegistry {
 		this.#debug = debug;
 	}
 
-	/**
-	 * Register a processor for the Turn XML Document.
-	 */
 	onTurn(callback, priority = 10) {
 		this.#processors.push({ callback, priority });
 		this.#processors.sort((a, b) => a.priority - b.priority);
 	}
 
-	/**
-	 * Run all registered Turn processors.
-	 */
 	async processTurn(rummy) {
 		for (const p of this.#processors) {
 			const start = performance.now();
@@ -35,9 +26,6 @@ export default class HookRegistry {
 		}
 	}
 
-	/**
-	 * Standard WordPress-style Filters for non-DOM data.
-	 */
 	addFilter(tag, callback, priority = 10) {
 		if (!this.#filters.has(tag)) this.#filters.set(tag, []);
 		this.#filters.get(tag).push({ callback, priority });
@@ -54,9 +42,6 @@ export default class HookRegistry {
 		return result;
 	}
 
-	/**
-	 * Standard WordPress-style Events for side-effects.
-	 */
 	addEvent(tag, callback, priority = 10) {
 		if (!this.#events.has(tag)) this.#events.set(tag, []);
 		this.#events.get(tag).push({ callback, priority });

package/src/hooks/Hooks.js

@@ -2,10 +2,7 @@ import HookRegistry from "./HookRegistry.js";
 import RpcRegistry from "./RpcRegistry.js";
 import ToolRegistry from "./ToolRegistry.js";
 
-/**
- * createHooks returns a structured, strictly-typed API for registering
- * and emitting hooks, removing the dynamic stringly-typed Proxy magic.
- */
+// Strictly-typed hook surface; replaces the previous Proxy magic.
 export default function createHooks(debug = false) {
 	const registry = new HookRegistry(debug);
 	const tools = new ToolRegistry();
@@ -28,6 +25,10 @@ export default function createHooks(debug = false) {
 		processTurn: registry.processTurn.bind(registry),
 
 		// Explicit Hook Schema
+		boot: {
+			// Post-init, pre-accept-connections; one-shot post-init actions subscribe here.
+			completed: createEvent("boot.completed"),
+		},
 		project: {
 			init: {
 				started: createEvent("project.init.started"),
@@ -43,12 +44,18 @@ export default function createHooks(debug = false) {
 		run: {
 			created: createEvent("run.created"),
 			started: createEvent("run.started"),
-			progress: createEvent("run.progress"),
-			state: createEvent("run.state"),
 			config: createFilter("run.config"),
 			step: {
 				completed: createEvent("run.step.completed"),
 			},
+			// Fire-and-forget wake: any plugin that wants to deliver a new
+			// prompt onto a (possibly dormant) run emits with
+			// {runAlias, body, mode}. AgentLoop subscribes and runs inject —
+			// writes prompt://<nextTurn>, enqueues a loop, ensures the
+			// drainer is up. This is the "streaming child closed after the
+			// loop ended" rendezvous: the producer doesn't care whether the
+			// run is alive or asleep, just that the prompt reaches it.
+			wake: createEvent("run.wake"),
 		},
 		loop: {
 			started: createEvent("loop.started"),
@@ -56,24 +63,34 @@ export default function createHooks(debug = false) {
 		},
 		turn: {
 			started: createEvent("turn.started"),
+			// Pre-LLM packet shaping. Filter chain: subscribers receive
+			// `{ messages, rows, contextSize, lastPromptTokens,
+			// assembledTokens, ok, overflow }` and return a transformed
+			// packet. Budget plugin participates here to enforce ceilings
+			// (may demote, may set ok=false on overflow). Other plugins
+			// could trim, re-order, or annotate — same surface.
+			beforeDispatch: createFilter("turn.beforeDispatch"),
 			response: createEvent("turn.response"),
+			// Post-dispatch event. Fired after the per-entry dispatch
+			// loop, before turn.completed. Budget subscribes here for
+			// post-dispatch demotion / 413 overflow detection.
+			dispatched: createEvent("turn.dispatched"),
 			completed: createEvent("turn.completed"),
-		},
+			// Verdict filter chain: each subscriber receives the current
+			// verdict object and returns a (possibly modified) one.
+			// Initial value is { continue: true }; final value drives the
+			// loop's continue/abandon decision. Multi-plugin: strike streak,
+			// cycle detect, stagnation pressure, future voters all
+			// participate via this surface.
+			verdict: createFilter("turn.verdict"),
+		},
+		// SPEC #resolution covers the proposal hook chain.
 		proposal: {
 			prepare: createEvent("proposal.prepare"),
 			pending: createEvent("proposal.pending"),
-			// Plugins veto acceptance by returning {allow:false, outcome, body}.
-			// Used e.g. by set plugin's readonly constraint check.
 			accepting: createFilter("proposal.accepting"),
-			// Plugins compose the resolved body based on path/action. Default
-			// is output || "". Used e.g. by set plugin to preserve the
-			// model's proposed content as the resolved body.
 			content: createFilter("proposal.content"),
-			// Fires after a proposal resolves with action="accept". Plugins
-			// perform their side effects (file materialize, unlink, stream
-			// setup, etc.) here — NOT in AgentLoop.resolve.
 			accepted: createEvent("proposal.accepted"),
-			// Fires after a proposal resolves with action="error" or "reject".
 			rejected: createEvent("proposal.rejected"),
 		},
 		assembly: {
@@ -98,24 +115,9 @@ export default function createHooks(debug = false) {
 			},
 			messages: createFilter("llm.messages"),
 			response: createFilter("llm.response"),
-			// Reasoning merge filter. Subscribers contribute per-tag
-			// reasoning text (e.g. the think plugin's <think>…</think>)
-			// to the model's reasoning_content field. Fires between parse
-			// and turn.response.
+			// Plugins contribute reasoning text into reasoning_content; fires between parse and turn.response.
 			reasoning: createFilter("llm.reasoning"),
-			// LLM provider registry. Plugins contribute entries shaped:
-			//   {
-			//     name: string,
-			//     matches: (modelAlias) => boolean,
-			//     completion: (messages, modelAlias, options) => Promise<response>,
-			//     getContextSize: (modelAlias) => Promise<number>,
-			//   }
-			// Each provider owns a prefix namespace (e.g. "openai/", "ollama/",
-			// "openrouter/"). LlmProvider picks the first provider whose
-			// matches() returns true. No catchall — if a model alias doesn't
-			// match any registered provider, the request fails with a clear
-			// "no provider registered" error. External plugins add new
-			// prefixes without namespace collision.
+			// Provider entries: { name, matches, completion, getContextSize }.
 			providers: [],
 		},
 		file: {},
@@ -163,7 +165,6 @@ export default function createHooks(debug = false) {
 		agent: {},
 		tools,
 
-		// Utility to add raw filters/events directly if needed for tests
 		addFilter: registry.addFilter.bind(registry),
 		applyFilters: registry.applyFilters.bind(registry),
 		addEvent: registry.addEvent.bind(registry),

package/src/hooks/PluginContext.js

@@ -1,12 +1,4 @@
-/**
- * PluginContext is the plugin-only interface to the rummy system.
- * Available as `rummy.core` on the per-turn RummyContext, and as the
- * direct object passed to plugin constructors at startup.
- *
- * Carries plugin identity, hook registration, and infrastructure access.
- * The unified API (tool verbs, queries) lives on RummyContext.
- * This is the tier boundary: clients can't reach core.
- */
+// Plugin-only registration interface; tool verbs live on RummyContext. PLUGINS.md.
 export default class PluginContext {
 	#name;
 	#hooks;
@@ -77,19 +69,12 @@ export default class PluginContext {
 		this.#hooks.tools.ensureTool(this.#name);
 	}
 
-	// Mark this plugin's tool as hidden from model-facing tool lists.
-	// Handler still dispatches if the model emits the tag.
+	// Hide from tool lists; handler still dispatches if the model emits the tag.
 	markHidden() {
 		this.#hooks.tools.markHidden(this.#name);
 	}
 
-	/**
-	 * Register a named callback for this plugin.
-	 * "handler" registers the tool handler.
-	 * "visible"/"summarized" register visibility projections.
-	 * "docs" sets tool documentation.
-	 * Everything else resolves to a hook event.
-	 */
+	// "handler" / "visible" / "summarized" are special; everything else is a hook event name.
 	on(event, callback, priority = 10) {
 		if (event === "handler") {
 			this.#hooks.tools.ensureTool(this.#name);
@@ -104,9 +89,6 @@ export default class PluginContext {
 		if (hook) hook.on(callback, priority);
 	}
 
-	/**
-	 * Register a filter callback.
-	 */
 	filter(name, callback, priority = 10) {
 		const hook = this.#resolveFilter(name);
 		if (hook) hook.addFilter(callback, priority);

package/src/hooks/RpcRegistry.js

@@ -26,10 +26,7 @@ export default class RpcRegistry {
 
 	#toolFallback = null;
 
-	/**
-	 * Set a fallback that auto-dispatches any registered tool via RPC.
-	 * Checked at request time — tools registered after this call still work.
-	 */
+	// Late-binding tool dispatcher; resolved per request.
 	setToolFallback(hooks, buildRunContext, dispatchTool) {
 		this.#toolFallback = { hooks, buildRunContext, dispatchTool };
 	}