@volter/supercode-orchestrator 0.4.4

package/board.mjs

@@ -0,0 +1,81 @@
+// The board's dispatcher (docs/plans/hermes-compat.md row 14). A home's board is Hermes's: `kanban.db` at
+// the root, above the profiles, in Hermes's schema, written by Hermes's code. Where a Hermes gateway
+// would host the dispatcher, the orchestrator hosts it the same way: gated by `kanban.dispatch_in_gateway`
+// (and `HERMES_KANBAN_DISPATCH_IN_GATEWAY`), holding Hermes's one-dispatcher lock, one tick every
+// `kanban.dispatch_interval_seconds` (60, at least 1), the first after five seconds; each tick is Hermes's
+// own (`kanbanTick`). What differs is the worker: Hermes's spawn runs `HERMES_BIN`, here a wrapper that
+// starts `bin/hermes-worker.mjs` on this daemon's own runtime, so each task runs on its assignee
+// profile's worker harness. `hermes kanban` reads and writes the same file.
+import { createHash } from 'node:crypto';
+import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { hermesInstall, kanbanTick } from './hermes-cli.mjs';
+import { holdDispatcherLock } from './hermes-locks.mjs';
+
+const WORKER = fileURLToPath(new URL('./bin/hermes-worker.mjs', import.meta.url));
+
+/** The `HERMES_BIN` for a root: a script that runs the worker command on this very runtime. */
+function workerCommand(root) {
+  const dir = join(process.env.XDG_STATE_HOME || join(homedir(), '.local', 'state'), 'supercode', 'hermes-home', createHash('sha256').update(resolve(root)).digest('hex').slice(0, 16));
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, 'hermes-worker');
+  writeFileSync(file, `#!/bin/sh\nexec ${JSON.stringify(process.execPath)} ${JSON.stringify(WORKER)} "$@"\n`);
+  chmodSync(file, 0o755);
+  return file;
+}
+
+/** Start the board's dispatcher for the home at `root`; answers `{ stop }`, or null when it does not dispatch. */
+export async function startBoard({ root, config = {}, log = () => {} }) {
+  const kanban = config.kanban ?? {};
+  const off = String(process.env.HERMES_KANBAN_DISPATCH_IN_GATEWAY ?? '').trim().toLowerCase();
+  if (['0', 'false', 'no', 'off'].includes(off)) { log('info', 'board: not dispatched (HERMES_KANBAN_DISPATCH_IN_GATEWAY)'); return null; }
+  if (kanban.dispatch_in_gateway === false) { log('info', 'board: not dispatched (kanban.dispatch_in_gateway: false)'); return null; }
+  const install = hermesInstall();
+  if (!install?.python) { log('warn', 'board: not dispatched; the board is Hermes\'s and no Hermes is installed on PATH'); return null; }
+  let lock;
+  try { lock = await holdDispatcherLock(root, { python: install.python }); }
+  catch (error) { log('info', `board: not dispatched: ${error.message}`); return null; }
+  const env = {
+    HERMES_BIN: workerCommand(root),
+    PATH: `${dirname(process.execPath)}:${process.env.PATH ?? ''}`,
+    ...(process.env.SUPERCODE_BIN ? { SUPERCODE_BIN: process.env.SUPERCODE_BIN } : {}),
+    ...(process.env.XDG_STATE_HOME ? { XDG_STATE_HOME: process.env.XDG_STATE_HOME } : {}),
+  };
+  const seconds = Math.max(Number(kanban.dispatch_interval_seconds) || 60, 1);
+  let running = false;
+  let stopped = false;
+  const said = new Set();
+  // what a Hermes gateway does around the dispatcher and this one does not, said once per board
+  const unserved = (board) => {
+    if (board.subscriptions && !said.has(`subs:${board.board}`)) { said.add(`subs:${board.board}`); log('warn', `board ${board.board}: ${board.subscriptions} chat subscription(s) are delivered by Hermes's gateway notifier, which this orchestrator does not run`); }
+    if (board.triage && !said.has(`triage:${board.board}`)) { said.add(`triage:${board.board}`); log('warn', `board ${board.board}: ${board.triage} triage task(s) wait for decomposition, which Hermes's gateway runs on its auxiliary model and this orchestrator does not`); }
+  };
+  const tick = async () => {
+    if (running || stopped) return;
+    running = true;
+    try {
+      for (const board of await kanbanTick(root, env)) {
+        if (board.error) log('warn', `board ${board.board}: ${board.error}`);
+        unserved(board);
+        for (const [task, assignee] of board.spawned ?? []) log('info', `board ${board.board}: ${task} spawned for ${assignee}`);
+        for (const [what, ids] of [['reclaimed', board.reclaimed], ['crashed', board.crashed], ['timed out', board.timed_out]]) {
+          if (Array.isArray(ids) && ids.length) log('info', `board ${board.board}: ${what} ${ids.join(', ')}`);
+        }
+      }
+    } catch (error) {
+      log('warn', `board: tick failed: ${error.message}`);
+    } finally {
+      running = false;
+    }
+  };
+  const first = setTimeout(() => { void tick(); }, 5_000);
+  const timer = setInterval(() => { void tick(); }, seconds * 1000);
+  first.unref?.(); timer.unref?.();
+  log('info', `board: dispatching every ${seconds}s, each task on its assignee's worker`);
+  return {
+    tick,
+    stop() { stopped = true; clearTimeout(first); clearInterval(timer); lock.release(); },
+  };
+}

package/commands.mjs

@@ -0,0 +1,37 @@
+// Chat commands (docs/ORCHESTRATOR-IR.md §2.7, §4.5) and the channel frame.
+// Pure: no node imports.
+
+export const COMMANDS = new Set(['new', 'reset', 'sethome', 'status', 'whoami', 'model', 'sessions', 'handoff', 'bg']);
+
+/** `/word rest` → { name, args } for a known command; null otherwise (unknown `/word` goes to the worker as text). */
+export function parseCommand(text) {
+  const m = /^\/([a-z]+)(?:\s+([\s\S]*))?$/.exec(text.trim());
+  if (!m || !COMMANDS.has(m[1])) return null;
+  return { name: m[1], args: (m[2] ?? '').trim() };
+}
+
+/**
+ * The channel frame: who said it, where, and when, as text prepended to the
+ * message. Text because the orchestrator does not own the worker's system
+ * prompt (§0.3). One line, stable, greppable by the mock worker in tests.
+ */
+export function frame(profile, key, sender, senderName, at, text) {
+  const where = [key.platform, key.kind, key.chat_id, key.thread_id ? `thread ${key.thread_id}` : null].filter(Boolean).join(' ');
+  // In a Room the author reads as the token that addresses them (`aaron <@prn_…>`): written back, it is a mention RH2
+  // records and notifies, so the agent learns the form from every line it hears.
+  const who = key.platform === 'rh2' && /^prn_[a-z0-9]+$/.test(String(sender)) ? `${senderName ?? sender} <@${sender}>` : senderName ? `${senderName} (${sender})` : sender;
+  return `[channel: ${where} · from: ${who} · at: ${at} · profile: ${profile}]\n${text}`;
+}
+
+export const REPLY = Object.freeze({
+  newSession: 'New session started.',
+  reset: 'Session reset.',
+  homeSet: 'Home chat set.',
+  // Hermes's gateway's own words (gateway/run.py), so a stranger is told the same thing under either runtime
+  notPaired: (code, platform, profile) => `Hi~ I don't recognize you yet!\n\nHere's your pairing code: \`${code}\`\n\nAsk the bot owner to run:\n\`hermes ${profile && profile !== 'default' ? `-p ${profile} ` : ''}pairing approve ${platform} ${code}\``,
+  pairingBusy: 'Too many pairing requests right now~ Please try again later!',
+  paired: 'Paired.',
+  modelApplied: (m) => `Model set to ${m} for this conversation; applies on the next session.`,
+  bgQueued: (id) => `Queued as job ${id}.`,
+  interrupted: 'Session interrupted by a restart; send your message again.',
+});