@volter/supercode-orchestrator 0.4.15 → 0.4.17

package/board/store.mjs

@@ -0,0 +1,150 @@
+// The board's store (docs/architecture/orchestrator.md §2.9). A board is a Kanban database in Hermes's own
+// format, so either implementation opens the other's board: `kanban.db` at the home's root is the default board,
+// `kanban/boards/<slug>/kanban.db` a named one; the tables, columns, statuses and event kinds are Hermes's. What
+// supercode knows beyond Hermes lives where Hermes leaves it alone: a run's `metadata` JSON (the session the
+// dispatcher launched) and a table of our own, `supercode_cards` (the machine a card runs on, the arc a subtask
+// belongs to).
+//
+// This module opens a board and gives its callers one primitive, a write transaction; the transitions are in
+// `engine.mjs`. Hermes's own tools may write the same file at the same time: every write takes SQLite's writer
+// lock (`BEGIN IMMEDIATE`) and retries while the other holds it.
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+export const DEFAULT_BOARD = 'default';
+
+// Hermes's tables as its boards carry them; a fresh board is created with them so Hermes opens it as its own.
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS tasks (
+    id TEXT PRIMARY KEY, title TEXT NOT NULL, body TEXT, assignee TEXT, status TEXT NOT NULL, priority INTEGER DEFAULT 0,
+    created_by TEXT, created_at INTEGER NOT NULL, started_at INTEGER, completed_at INTEGER,
+    workspace_kind TEXT NOT NULL DEFAULT 'scratch', workspace_path TEXT, branch_name TEXT, project_id TEXT,
+    claim_lock TEXT, claim_expires INTEGER, tenant TEXT, result TEXT, idempotency_key TEXT,
+    consecutive_failures INTEGER NOT NULL DEFAULT 0, worker_pid INTEGER, last_failure_error TEXT,
+    max_runtime_seconds INTEGER, last_heartbeat_at INTEGER, current_run_id INTEGER,
+    workflow_template_id TEXT, current_step_key TEXT, skills TEXT, model_override TEXT, provider_override TEXT,
+    reasoning_effort TEXT, max_retries INTEGER, goal_mode INTEGER NOT NULL DEFAULT 0, goal_max_turns INTEGER,
+    session_id TEXT, block_kind TEXT, block_recurrences INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS task_links (parent_id TEXT NOT NULL, child_id TEXT NOT NULL, PRIMARY KEY (parent_id, child_id));
+CREATE TABLE IF NOT EXISTS task_comments (id INTEGER PRIMARY KEY AUTOINCREMENT, task_id TEXT NOT NULL, author TEXT NOT NULL, body TEXT NOT NULL, created_at INTEGER NOT NULL);
+CREATE TABLE IF NOT EXISTS task_events (id INTEGER PRIMARY KEY AUTOINCREMENT, task_id TEXT NOT NULL, run_id INTEGER, kind TEXT NOT NULL, payload TEXT, created_at INTEGER NOT NULL);
+CREATE TABLE IF NOT EXISTS task_runs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT, task_id TEXT NOT NULL, profile TEXT, step_key TEXT, status TEXT NOT NULL,
+    claim_lock TEXT, claim_expires INTEGER, worker_pid INTEGER, max_runtime_seconds INTEGER, last_heartbeat_at INTEGER,
+    started_at INTEGER NOT NULL, ended_at INTEGER, outcome TEXT, summary TEXT, metadata TEXT, error TEXT
+);
+CREATE TABLE IF NOT EXISTS task_attachments (
+    id INTEGER PRIMARY KEY AUTOINCREMENT, task_id TEXT NOT NULL, filename TEXT NOT NULL, stored_path TEXT NOT NULL,
+    content_type TEXT, size INTEGER NOT NULL DEFAULT 0, uploaded_by TEXT, created_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS kanban_notify_subs (
+    task_id TEXT NOT NULL, platform TEXT NOT NULL, chat_id TEXT NOT NULL, thread_id TEXT NOT NULL DEFAULT '',
+    user_id TEXT, user_id_alt TEXT, chat_type TEXT, notifier_profile TEXT, delivery_mode TEXT NOT NULL DEFAULT 'notify',
+    delivery_metadata TEXT, created_at INTEGER NOT NULL, last_event_id INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (task_id, platform, chat_id, thread_id)
+);
+CREATE INDEX IF NOT EXISTS idx_tasks_assignee_status ON tasks(assignee, status);
+CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
+CREATE INDEX IF NOT EXISTS idx_tasks_session_id ON tasks(session_id);
+CREATE INDEX IF NOT EXISTS idx_links_child ON task_links(child_id);
+CREATE INDEX IF NOT EXISTS idx_links_parent ON task_links(parent_id);
+CREATE INDEX IF NOT EXISTS idx_comments_task ON task_comments(task_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_events_task ON task_events(task_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_runs_task ON task_runs(task_id, started_at);
+CREATE INDEX IF NOT EXISTS idx_runs_status ON task_runs(status);
+CREATE INDEX IF NOT EXISTS idx_attachments_task ON task_attachments(task_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_notify_task ON kanban_notify_subs(task_id);
+CREATE INDEX IF NOT EXISTS idx_tasks_tenant ON tasks(tenant);
+CREATE INDEX IF NOT EXISTS idx_tasks_idempotency ON tasks(idempotency_key);
+CREATE INDEX IF NOT EXISTS idx_events_run ON task_events(run_id, id);
+`;
+
+// supercode's part of a card, beside Hermes's row: where its session runs, and the arc a subtask belongs to (a
+// subtask is worked by its arc's session and never started on its own).
+const OURS = `CREATE TABLE IF NOT EXISTS supercode_cards (task_id TEXT PRIMARY KEY, machine TEXT, subtask_of TEXT);`;
+const OURS_COLUMNS = { subtask_of: 'TEXT' };
+
+/** The database file of board `slug` in the home at `root`. */
+export function boardPath(root, slug = DEFAULT_BOARD) {
+  return !slug || slug === DEFAULT_BOARD ? join(root, 'kanban.db') : join(root, 'kanban', 'boards', slug, 'kanban.db');
+}
+
+/** The home's boards that exist: `default` when `kanban.db` does, and every named one. */
+export function listBoards(root) {
+  const out = existsSync(boardPath(root)) ? [DEFAULT_BOARD] : [];
+  const named = join(root, 'kanban', 'boards');
+  if (existsSync(named)) {
+    for (const slug of readdirSync(named)) if (existsSync(boardPath(root, slug))) out.push(slug);
+  }
+  return out;
+}
+
+/** Open (creating when `create`) board `slug`: `{ db, root, slug, path, close }`. */
+export function openBoard(root, slug = DEFAULT_BOARD, { create = false } = {}) {
+  const path = boardPath(root, slug);
+  if (!existsSync(path)) {
+    if (!create) throw new Error(`no board ${slug} in ${root} (${path})`);
+    mkdirSync(dirname(path), { recursive: true });
+  }
+  const db = new DatabaseSync(path);
+  db.exec('PRAGMA busy_timeout = 10000');
+  db.exec('PRAGMA foreign_keys = OFF');
+  const fresh = !db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'tasks'").get();
+  if (fresh) {
+    if (!create) { db.close(); throw new Error(`${path} is not a board`); }
+    db.exec(SCHEMA);
+  }
+  db.exec(OURS);
+  const have = new Set(db.prepare('PRAGMA table_info(supercode_cards)').all().map((c) => c.name));
+  for (const [column, type] of Object.entries(OURS_COLUMNS)) if (!have.has(column)) db.exec(`ALTER TABLE supercode_cards ADD COLUMN ${column} ${type}`);
+  return { db, root, slug, path, close: () => db.close() };
+}
+
+/**
+ * Run `fn(db)` in one write transaction (`BEGIN IMMEDIATE`: the writer lock taken up front, so a read inside the
+ * transaction is the state it writes over). Answers what `fn` answers; rolls back on a throw.
+ */
+export function tx(board, fn) {
+  const { db } = board;
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      db.exec('BEGIN IMMEDIATE');
+      break;
+    } catch (error) {
+      if (!/locked|busy/i.test(error.message) || attempt >= 50) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+    }
+  }
+  try {
+    const out = fn(db);
+    db.exec('COMMIT');
+    return out;
+  } catch (error) {
+    try { db.exec('ROLLBACK'); } catch { /* already rolled back */ }
+    throw error;
+  }
+}
+
+export const now = () => Math.floor(Date.now() / 1000);
+
+/** A new card id in Hermes's form, `t_` and eight hex digits. */
+export const newTaskId = () => `t_${randomBytes(4).toString('hex')}`;
+
+/** The claim lock this process writes, in Hermes's `host:pid` form. */
+export const claimer = () => `${hostname()}:${process.pid}`;
+
+export function json(text, fallback = null) {
+  if (text === null || text === undefined || text === '') return fallback;
+  try { return JSON.parse(text); } catch { return fallback; }
+}
+
+/** Append one event to a card's thread (Hermes's `task_events`); answers its id. */
+export function event(db, taskId, kind, payload = null, runId = null) {
+  const r = db.prepare('INSERT INTO task_events (task_id, run_id, kind, payload, created_at) VALUES (?, ?, ?, ?, ?)')
+    .run(taskId, runId, kind, payload ? JSON.stringify(payload) : null, now());
+  return Number(r.lastInsertRowid);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.4.15",
+  "version": "0.4.17",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -46,6 +46,7 @@
     "bin",
     "mcp",
     "adapters",
+    "board",
     "apply",
     "README.md"
   ]