@possumtech/rummy 0.2.1

package/src/agent/known_checks.sql

@@ -0,0 +1,42 @@
+-- PREP: count_unknowns
+SELECT COUNT(*) AS count
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND scheme = 'unknown';
+
+-- PREP: get_unknown_values
+SELECT body
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND scheme = 'unknown';
+
+-- PREP: get_unresolved
+SELECT path, body, attributes, turn
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND state = 'proposed';
+
+-- PREP: has_rejections
+SELECT COUNT(*) AS count
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND state = 'rejected';
+
+-- PREP: has_accepted_actions
+SELECT COUNT(*) AS count
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND state = 'pass'
+	AND scheme IN ('set', 'sh', 'rm', 'mv', 'cp');
+
+-- PREP: get_file_entries
+SELECT path, state, hash, updated_at
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND scheme IS NULL;

package/src/agent/known_queries.sql

@@ -0,0 +1,80 @@
+-- PREP: get_known_entries
+SELECT path, scheme, state, body, turn, hash, attributes
+FROM known_entries
+WHERE run_id = :run_id
+ORDER BY path;
+
+-- PREP: get_results
+SELECT tool, target, status, path, body
+FROM v_run_log
+WHERE run_id = :run_id;
+
+-- PREP: get_unknowns
+SELECT path, body
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND scheme = 'unknown'
+ORDER BY id;
+
+-- PREP: get_turn_audit
+SELECT path, scheme, state, turn, body, attributes
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND turn = :turn
+ORDER BY id;
+
+-- PREP: get_reasoning
+SELECT path, body, turn
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND scheme = 'reasoning'
+ORDER BY id;
+
+-- PREP: get_latest_user_prompt
+SELECT body
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND scheme IN ('ask', 'act')
+	AND body != ''
+ORDER BY id DESC
+LIMIT 1;
+
+-- PREP: get_latest_prompt
+SELECT path, scheme, body, attributes
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND scheme = 'prompt'
+ORDER BY id DESC
+LIMIT 1;
+
+-- PREP: get_latest_summary
+SELECT body
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND scheme = 'summarize'
+ORDER BY id DESC
+LIMIT 1;
+
+-- PREP: get_history
+SELECT ke.path, ke.state AS status, ke.body, ke.attributes, ke.turn
+FROM known_entries AS ke
+JOIN schemes AS s ON s.name = COALESCE(ke.scheme, 'file')
+WHERE
+	ke.run_id = :run_id
+	AND ke.scheme IS NOT NULL
+	AND s.category NOT IN ('knowledge', 'file', 'audit')
+ORDER BY ke.id;
+
+-- PREP: get_content
+SELECT path, body, turn
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND scheme = 'content'
+ORDER BY id;

package/src/agent/known_store.sql

@@ -0,0 +1,161 @@
+-- PREP: upsert_known_entry
+INSERT INTO known_entries (
+	run_id, turn, path, body, state, hash, attributes
+	, tokens, tokens_full, updated_at
+)
+VALUES (
+	:run_id, :turn, :path, :body, :state, :hash, COALESCE(:attributes, '{}')
+	, countTokens(:body)
+	, countTokens(:body)
+	, COALESCE(:updated_at, CURRENT_TIMESTAMP)
+)
+ON CONFLICT (run_id, path) DO UPDATE SET
+	body = excluded.body
+	, state = excluded.state
+	, hash = COALESCE(excluded.hash, known_entries.hash)
+	, attributes = COALESCE(excluded.attributes, known_entries.attributes)
+	, turn = excluded.turn
+	, tokens = countTokens(excluded.body)
+	, tokens_full = countTokens(excluded.body)
+	, write_count = known_entries.write_count + 1
+	, updated_at = COALESCE(excluded.updated_at, CURRENT_TIMESTAMP);
+
+-- PREP: recount_tokens
+UPDATE known_entries
+SET tokens = :tokens, tokens_full = :tokens
+WHERE run_id = :run_id AND path = :path;
+
+-- PREP: get_stale_tokens
+SELECT path, body
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND turn = :turn;
+
+-- PREP: delete_known_entry
+DELETE FROM known_entries
+WHERE run_id = :run_id AND path = :path;
+
+-- PREP: delete_file_entries_by_pattern
+DELETE FROM known_entries
+WHERE run_id = :run_id AND hedmatch(:pattern, path) AND scheme IS NULL;
+
+-- PREP: resolve_known_entry
+UPDATE known_entries
+SET
+	state = :state
+	, body = :body
+	, updated_at = CURRENT_TIMESTAMP
+WHERE run_id = :run_id AND path = :path;
+
+-- PREP: set_file_state
+UPDATE known_entries
+SET
+	state = :state
+	, tokens = CASE
+		WHEN :state = 'summary' THEN countTokens(body)
+		ELSE tokens_full
+	END
+	, updated_at = CURRENT_TIMESTAMP
+WHERE run_id = :run_id AND hedmatch(:pattern, path) AND scheme IS NULL;
+
+-- PREP: promote_path
+UPDATE known_entries
+SET
+	state = 'full'
+	, turn = :turn
+	, tokens = tokens_full
+	, updated_at = CURRENT_TIMESTAMP
+WHERE run_id = :run_id AND path = :path;
+
+-- PREP: demote_path
+UPDATE known_entries
+SET
+	state = 'stored'
+	, tokens = 0
+	, updated_at = CURRENT_TIMESTAMP
+WHERE run_id = :run_id AND path = :path;
+
+-- PREP: get_entry_body
+SELECT body
+FROM known_entries
+WHERE run_id = :run_id AND path = :path;
+
+-- PREP: get_entry_state
+SELECT state, scheme, turn
+FROM known_entries
+WHERE run_id = :run_id AND path = :path;
+
+-- PREP: get_file_states_by_pattern
+SELECT path, state, turn
+FROM known_entries
+WHERE run_id = :run_id AND hedmatch(:pattern, path) AND scheme IS NULL
+ORDER BY path;
+
+-- PREP: update_entry_attributes
+UPDATE known_entries
+SET
+	attributes = json_patch(attributes, :attributes)
+	, updated_at = CURRENT_TIMESTAMP
+WHERE run_id = :run_id AND path = :path;
+
+-- PREP: get_entry_attributes
+SELECT attributes
+FROM known_entries
+WHERE run_id = :run_id AND path = :path;
+
+-- PREP: promote_by_pattern
+UPDATE known_entries
+SET
+	state = 'full'
+	, turn = :turn
+	, tokens = tokens_full
+	, updated_at = CURRENT_TIMESTAMP
+WHERE
+	run_id = :run_id
+	AND hedmatch(:path, path)
+	AND (:body IS NULL OR hedsearch(:body, body));
+
+-- PREP: demote_by_pattern
+UPDATE known_entries
+SET
+	state = 'stored'
+	, tokens = 0
+	, updated_at = CURRENT_TIMESTAMP
+WHERE
+	run_id = :run_id
+	AND hedmatch(:path, path)
+	AND (:body IS NULL OR hedsearch(:body, body));
+
+-- PREP: get_entries_by_pattern
+SELECT path, body, scheme, state, tokens_full, attributes
+FROM known_entries
+WHERE
+	run_id = :run_id
+	AND hedmatch(:path, path)
+	AND (:body IS NULL OR hedsearch(:body, body))
+ORDER BY path
+LIMIT
+	COALESCE(:limit, -1)
+	OFFSET
+	COALESCE(:offset, 0);
+
+-- PREP: delete_entries_by_pattern
+DELETE FROM known_entries
+WHERE
+	run_id = :run_id
+	AND hedmatch(:path, path)
+	AND (:body IS NULL OR hedsearch(:body, body));
+
+-- PREP: update_body_by_pattern
+UPDATE known_entries
+SET
+	body = :new_body
+	, tokens = countTokens(:new_body)
+	, tokens_full = countTokens(:new_body)
+	, write_count = write_count + 1
+	, updated_at = CURRENT_TIMESTAMP
+WHERE
+	run_id = :run_id
+	AND hedmatch(:path, path)
+	AND (:body IS NULL OR hedsearch(:body, body));

package/src/agent/messages.js

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const catalog = JSON.parse(
+	readFileSync(join(__dirname, "../../lang/en.json"), "utf8"),
+);
+
+export default function msg(key, params = {}) {
+	const template = catalog[key];
+	if (!template) throw new Error(`Missing message key: ${key}`);
+	return template.replace(/\{(\w+)\}/g, (_, name) => {
+		if (name in params) return String(params[name]);
+		return `{${name}}`;
+	});
+}

package/src/agent/prompt_queue.sql

@@ -0,0 +1,39 @@
+-- PREP: enqueue_prompt
+INSERT INTO prompt_queue (run_id, mode, model, prompt, config)
+VALUES (:run_id, :mode, :model, :prompt, :config)
+RETURNING id;
+
+-- PREP: claim_next_prompt
+UPDATE prompt_queue
+SET status = 'active'
+WHERE
+	id = (
+		SELECT
+			id
+		FROM prompt_queue
+		WHERE run_id = :run_id AND status = 'pending'
+		ORDER BY id
+		LIMIT 1
+	)
+RETURNING id, run_id, mode, model, prompt, config;
+
+-- PREP: complete_prompt
+UPDATE prompt_queue
+SET status = 'completed', result = :result
+WHERE id = :id;
+
+-- PREP: abort_active_prompt
+UPDATE prompt_queue
+SET status = 'aborted'
+WHERE run_id = :run_id AND status = 'active';
+
+-- PREP: get_pending_prompts
+SELECT id, mode, model, prompt, status, created_at
+FROM prompt_queue
+WHERE run_id = :run_id AND status IN ('pending', 'active')
+ORDER BY id;
+
+-- PREP: reset_active_prompts
+UPDATE prompt_queue
+SET status = 'pending'
+WHERE status = 'active';

package/src/agent/runs.sql

@@ -0,0 +1,114 @@
+-- PREP: create_run
+INSERT INTO runs (
+	project_id
+	, parent_run_id
+	, model
+	, alias
+	, temperature
+	, persona
+	, context_limit
+)
+VALUES (
+	:project_id
+	, :parent_run_id
+	, :model
+	, :alias
+	, :temperature
+	, :persona
+	, :context_limit
+)
+RETURNING id;
+
+-- PREP: get_run_by_alias
+SELECT
+	id, project_id, parent_run_id, model, status, alias
+	, temperature, persona, context_limit, next_turn, created_at
+FROM runs
+WHERE alias = :alias;
+
+-- PREP: get_run_by_id
+SELECT
+	id, project_id, parent_run_id, model, status, alias
+	, temperature, persona, context_limit, next_turn, created_at
+FROM runs
+WHERE id = :id;
+
+-- PREP: get_runs_by_project
+SELECT
+	r.alias
+	, r.status
+	, r.created_at
+	, r.next_turn - 1 AS turn
+	, (
+		SELECT ke.body
+		FROM known_entries AS ke
+		WHERE
+			ke.run_id = r.id
+			AND ke.scheme = 'summarize'
+		ORDER BY ke.id DESC
+		LIMIT 1
+	) AS summary
+FROM runs AS r
+WHERE r.project_id = :project_id
+ORDER BY r.created_at DESC
+LIMIT
+	COALESCE(:limit, -1)
+	OFFSET
+	COALESCE(:offset, 0);
+
+-- PREP: rename_run
+UPDATE runs
+SET alias = :new_alias
+WHERE id = :id AND alias = :old_alias;
+
+-- PREP: update_run_status
+UPDATE runs SET status = :status WHERE id = :id;
+
+-- PREP: update_run_config
+UPDATE runs SET
+	temperature = COALESCE(:temperature, temperature)
+	, persona = COALESCE(:persona, persona)
+	, context_limit = COALESCE(:context_limit, context_limit)
+	, model = COALESCE(:model, model)
+WHERE id = :id;
+
+-- PREP: next_turn
+UPDATE runs
+SET next_turn = next_turn + 1
+WHERE id = :run_id
+RETURNING next_turn - 1 AS turn;
+
+-- PREP: fork_known_entries
+INSERT INTO known_entries (
+	run_id, turn, path, body, state
+	, hash, attributes, tokens, tokens_full, refs, write_count
+)
+SELECT
+	:new_run_id, turn, path, body, state
+	, hash, attributes, tokens, tokens_full, refs, write_count
+FROM known_entries
+WHERE run_id = :parent_run_id;
+
+-- PREP: get_active_runs
+SELECT r.id
+FROM runs AS r
+WHERE
+	r.project_id = :project_id
+	AND r.status IN ('queued', 'running', 'proposed');
+
+-- PREP: get_latest_run
+SELECT r.id
+FROM runs AS r
+WHERE r.project_id = :project_id
+ORDER BY r.created_at DESC
+LIMIT 1;
+
+-- PREP: get_all_runs
+SELECT r.id
+FROM runs AS r
+WHERE r.project_id = :project_id;
+
+-- PREP: abort_stuck_runs
+UPDATE runs
+SET status = 'aborted'
+WHERE status IN ('running', 'queued');

package/src/agent/schemes.sql

@@ -0,0 +1,3 @@
+-- PREP: upsert_scheme
+INSERT OR REPLACE INTO schemes (name, fidelity, model_visible, valid_states, category)
+VALUES (:name, :fidelity, :model_visible, :valid_states, :category);

package/src/agent/sessions.sql

@@ -0,0 +1,51 @@
+-- PREP: upsert_project
+INSERT INTO projects (name, project_root, config_path)
+VALUES (:name, :project_root, :config_path)
+ON CONFLICT (name) DO UPDATE SET
+	project_root = COALESCE(excluded.project_root, projects.project_root)
+	, config_path = COALESCE(excluded.config_path, projects.config_path)
+RETURNING id;
+
+-- PREP: get_project_by_id
+SELECT id, name, project_root, config_path, created_at
+FROM projects
+WHERE id = :id;
+
+-- PREP: get_project_by_name
+SELECT id, name, project_root, config_path, created_at
+FROM projects
+WHERE name = :name;
+
+-- PREP: upsert_model
+INSERT INTO models (alias, actual, context_length)
+VALUES (:alias, :actual, :context_length)
+ON CONFLICT (alias) DO UPDATE SET
+	actual = excluded.actual
+	, context_length = COALESCE(excluded.context_length, models.context_length)
+RETURNING id;
+
+-- PREP: get_model_by_alias
+SELECT id, alias, actual, context_length
+FROM models
+WHERE alias = :alias;
+
+-- PREP: get_models
+SELECT id, alias, actual, context_length
+FROM models
+ORDER BY alias
+LIMIT
+	COALESCE(:limit, -1)
+	OFFSET
+	COALESCE(:offset, 0);
+
+-- PREP: update_model_context_length
+UPDATE models SET context_length = :context_length WHERE alias = :alias;
+
+-- PREP: delete_model
+DELETE FROM models WHERE alias = :alias;
+
+-- PREP: purge_old_runs
+DELETE FROM runs
+WHERE
+	status IN ('completed', 'aborted')
+	AND created_at < datetime('now', '-' || :retention_days || ' days');

package/src/agent/tokens.js

@@ -0,0 +1,28 @@
+/**
+ * Token counting with tiktoken (o200k_base) and simple fallback.
+ * o200k_base is the tokenizer for GPT-4o and newer OpenAI models.
+ * Better multilingual and code handling than cl100k_base.
+ * Exact counts vary by model tokenizer — these are for budgeting, not billing.
+ */
+
+let encoder = null;
+
+try {
+	const tiktoken = await import("tiktoken");
+	encoder = tiktoken.get_encoding("o200k_base");
+} catch {
+	// tiktoken unavailable — use character-based estimate
+}
+
+export function countTokens(text) {
+	if (!text) return 0;
+	if (encoder) {
+		try {
+			const tokens = encoder.encode(text);
+			return tokens.length;
+		} catch {
+			// Fallback on encoding error
+		}
+	}
+	return Math.ceil(text.length / 4);
+}

package/src/agent/turns.sql

@@ -0,0 +1,36 @@
+-- PREP: create_turn
+INSERT INTO turns (run_id, sequence)
+VALUES (:run_id, :sequence)
+RETURNING id, sequence;
+
+-- PREP: update_turn_stats
+UPDATE turns
+SET
+	prompt_tokens = :prompt_tokens
+	, cached_tokens = :cached_tokens
+	, completion_tokens = :completion_tokens
+	, reasoning_tokens = :reasoning_tokens
+	, total_tokens = :total_tokens
+	, cost = :cost
+WHERE id = :id;
+
+-- PREP: get_run_usage
+SELECT
+	COALESCE(SUM(prompt_tokens), 0) AS prompt_tokens
+	, COALESCE(SUM(cached_tokens), 0) AS cached_tokens
+	, COALESCE(SUM(completion_tokens), 0) AS completion_tokens
+	, COALESCE(SUM(reasoning_tokens), 0) AS reasoning_tokens
+	, COALESCE(SUM(total_tokens), 0) AS total_tokens
+	, COALESCE(SUM(cost), 0) AS cost
+FROM turns
+WHERE run_id = :run_id;
+
+-- PREP: get_run_log
+SELECT ke.path, ke.state AS status, ke.body, ke.attributes
+FROM known_entries AS ke
+JOIN schemes AS s ON s.name = COALESCE(ke.scheme, 'file')
+WHERE
+	ke.run_id = :run_id
+	AND ke.scheme IS NOT NULL
+	AND s.category NOT IN ('knowledge')
+ORDER BY ke.id;

package/src/hooks/HookRegistry.js

@@ -0,0 +1,72 @@
+/**
+ * HookRegistry manages a simple, priority-ordered pipeline of processors.
+ * It also supports basic event emitters for side-effects.
+ */
+export default class HookRegistry {
+	#processors = [];
+	#events = new Map();
+	#filters = new Map();
+	#debug;
+
+	constructor(debug = false) {
+		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();
+			await p.callback(rummy);
+			if (this.#debug) {
+				const duration = (performance.now() - start).toFixed(2);
+				console.log(
+					`[PIPELINE] Processor ${p.callback.name || "anonymous"} took ${duration}ms`,
+				);
+			}
+		}
+	}
+
+	/**
+	 * 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 });
+		this.#filters.get(tag).sort((a, b) => a.priority - b.priority);
+	}
+
+	async applyFilters(tag, value, ...args) {
+		const hooks = this.#filters.get(tag) || [];
+		let result = value;
+		for (const h of hooks) {
+			result = await h.callback(result, ...args);
+		}
+		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 });
+		this.#events.get(tag).sort((a, b) => a.priority - b.priority);
+	}
+
+	async emitEvent(tag, ...args) {
+		const hooks = this.#events.get(tag) || [];
+		for (const h of hooks) {
+			await h.callback(...args);
+		}
+	}
+}