@volter/supercode-orchestrator 0.4.15 → 0.4.16

package/board/cli.mjs

@@ -0,0 +1,318 @@
+// `supercode workflow <verb>` (docs/architecture/orchestrator.md §2.9): supercode's own board, in Hermes Kanban's
+// format, and its dispatcher. The Rust CLI hands every verb but `load` to `bin/orchestrator.mjs workflow`, which
+// lands here. The home is `--root`, else `SUPERCODE_ORCHESTRATOR_HOME`, else `HERMES_HOME`; the board is
+// `--board <slug>` (default `default`). Every verb prints a line for a person, or one JSON object with `--json`.
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { read } from '../orchestration.mjs';
+import { holdDispatcherLock } from '../hermes-locks.mjs';
+import { boardPath, DEFAULT_BOARD, event, listBoards, openBoard, tx } from './store.mjs';
+import * as engine from './engine.mjs';
+import { attachSession, boardLabel, boardSettings, lanesOf, observeFleet, tick } from './dispatch.mjs';
+
+const HELP = `supercode workflow <verb> [--root <home>] [--board <slug>] [--json]
+
+  create <title> [--body T] [--assignee PROFILE] [--machine M] [--workspace dir:<path>|scratch|worktree[:<path>]]
+         [--branch B] [--parent ID]... [--priority N] [--tenant T] [--triage] [--idempotency-key K] [--max-runtime SECONDS]
+         [--max-retries N] [--skill S]... [--model M] [--provider P] [--created-by NAME] [--notify ADDRESS | --no-notify]
+         [--subtask-of ARC] [--no-start]
+      File a card. With a lane and capacity it starts at once and answers "started" with its session; otherwise it
+      answers why it waits, and its creator is told when it starts. A subtask is worked by its arc's session and never
+      starts on its own; another card may wait on it (link).
+  list [--status S] [--assignee P] [--machine M] [--all]     show <id>     context <id>
+  comment <id> <text> [--author NAME]      complete <id> [--summary T] [--result T]
+  block <id> [reason] [--kind dependency|needs_input|capability|transient]      unblock <id>
+  review <id> [--summary T] [--reviewer P]     changes <id> [--reason T] [--reviewer P]
+  schedule <id> [reason]     promote <id> [--force]     reclaim <id> [reason]     archive <id>
+  assign <id> <profile|none>     move <id> <machine|none>     link <parent> <child>     unlink <parent> <child>
+  subscribe <id> [--address A] [--role creator|worker|dependency]     unsubscribe <id> [--address A]
+  close <id>                close the session of a card that is not running (an idle session holds its machine's place)
+  attach <id> <session> [--workspace dir:<path>]
+                            put a live session the board did not start on the card (an address, id or name@machine the
+                            fleet lists); the board watches, resumes and tells it from then on
+
+  A card's own session may comment on, block (with --kind) or send to review its card, and create, complete, block and
+  comment on its subtasks; its arc is marked done by its reviewers, never by itself.
+  init                      create the board if it does not exist
+  dispatch                  one dispatcher tick over every board of the home
+  serve                     the dispatcher, a tick every kanban.dispatch_interval_seconds, until SIGTERM
+`;
+
+const MULTI = new Set(['parent', 'skill']);
+const FLAGS = new Set(['json', 'triage', 'no-notify', 'no-start', 'all', 'force', 'help']);
+
+function parse(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (!a.startsWith('--')) { out._.push(a); continue; }
+    const [key, inline] = a.slice(2).split(/=(.*)/s);
+    if (FLAGS.has(key)) { out[key] = true; continue; }
+    const value = inline ?? argv[++i];
+    if (value === undefined) throw new Error(`--${key} needs a value`);
+    if (MULTI.has(key)) (out[key] ??= []).push(value);
+    else out[key] = value;
+  }
+  return out;
+}
+
+function homeOf(args) {
+  const root = args.root ?? process.env.SUPERCODE_ORCHESTRATOR_HOME ?? process.env.HERMES_HOME;
+  if (!root) throw new Error('which home? --root <home> (or SUPERCODE_ORCHESTRATOR_HOME)');
+  return resolve(root);
+}
+
+/** The home's lanes (profiles' workers) and board settings (the root config's `kanban:` block), as the IR reads them. */
+async function laneState(root) {
+  const orchestration = await read(root);
+  const kanban = orchestration.profiles?.default?.residue?.config?.kanban ?? {};
+  return { lanes: lanesOf(orchestration.profiles), settings: boardSettings(kanban), kanban };
+}
+
+/** The caller's own supercode address, when it is a session supercode can reach (for its card's notices). */
+function callerAddress() {
+  const id = process.env.CLAUDE_CODE_SESSION_ID || process.env.CODEX_THREAD_ID;
+  if (!id) return null;
+  const fleet = observeFleet();
+  return [...fleet.alive].find((a) => a.endsWith(`:${id}`)) ?? null;
+}
+
+const say = (args, human, value) => { process.stdout.write(args.json ? `${JSON.stringify(value)}\n` : `${human}\n`); };
+
+function row(t) {
+  return `${t.id}  ${t.status.padEnd(9)} ${(t.assignee ?? '-').padEnd(14)} ${(t.machine ?? '-').padEnd(20)} ${t.title}`;
+}
+
+export async function runWorkflow(argv) {
+  const args = parse(argv);
+  const [verb, ...rest] = args._;
+  if (!verb || verb === 'help' || args.help) { process.stdout.write(HELP); return 0; }
+  const root = homeOf(args);
+  const slug = args.board ?? DEFAULT_BOARD;
+  const open = (create = false) => { const b = openBoard(root, slug, { create }); b.label = boardLabel(root, slug); return b; };
+  const withBoard = (fn, create = false) => { const b = open(create); try { return fn(b); } finally { b.close(); } };
+  const id = rest[0];
+  const need = (n, what) => { if (rest.length < n) throw new Error(`${verb} needs ${what}`); };
+
+  // a caller that is a card's own session (its harness names it; the board recorded which session it launched)
+  const sid = process.env.CLAUDE_CODE_SESSION_ID || process.env.CODEX_THREAD_ID;
+  if (sid && !READS.has(verb) && existsSync(boardPath(root, slug))) {
+    withBoard((b) => { const own = ownCard(b.db, sid); if (own) authorize(b.db, verb, rest, args, own); });
+  }
+
+  switch (verb) {
+    case 'close': {
+      need(1, 'a card id');
+      const closed = withBoard((b) => closeSession(b, id));
+      say(args, closed ? `closed ${closed.session_id} (pane ${closed.pane} on ${closed.machine})` : `${id} has no live session`, { ok: true, closed });
+      return 0;
+    }
+    case 'attach': {
+      need(2, 'a card id and a session');
+      const { settings } = await laneState(root);
+      const got = withBoard((b) => attachSession(b, id, rest[1], { workspace: args.workspace ?? null, ttl: settings.ttl }));
+      say(args, `${id} is worked by ${got.address} (pane ${got.pane ?? '?'} in ${got.workspace ?? 'its card\'s directory'})`, { ok: true, ...got });
+      return 0;
+    }
+    case 'init': withBoard(() => {}, true); say(args, `board ${slug} ready in ${root}`, { ok: true, board: slug }); return 0;
+    case 'create': {
+      need(1, 'a title');
+      const { lanes, settings } = await laneState(root);
+      const created = withBoard((b) => engine.createCard(b, {
+        title: rest.join(' '), body: args.body, assignee: args.assignee === 'none' ? null : args.assignee, machine: args.machine,
+        workspace: args.workspace, branch: args.branch, parents: args.parent, priority: args.priority, tenant: args.tenant,
+        triage: args.triage, idempotencyKey: args['idempotency-key'], maxRuntime: args['max-runtime'] ? Number(args['max-runtime']) : null,
+        maxRetries: args['max-retries'] ? Number(args['max-retries']) : null, skills: args.skill, model: args.model,
+        provider: args.provider, createdBy: args['created-by'] ?? callerName(), sessionId: process.env.CLAUDE_CODE_SESSION_ID ?? null,
+        subtaskOf: args['subtask-of'] ?? null,
+      }), true);
+      let answer = { id: created.id, existing: created.existing };
+      if (!args['no-start'] && !created.existing && !args['subtask-of']) {
+        const [report] = tick({ root, lanes, settings, only: created.id, slugs: [slug] });
+        const started = report.started.find(([t]) => t === created.id);
+        const queued = report.queued.find(([t]) => t === created.id);
+        const failed = report.failed.find(([t]) => t === created.id);
+        answer = { ...answer, ...(started ? { started: true, session: started[1], mode: started[2] } : {}), ...(queued ? { started: false, waits: queued[1] } : {}), ...(failed ? { started: false, failed: failed[1] } : {}) };
+      }
+      // the creator hears what happens from here on; a start answered above is not told twice
+      const address = args['no-notify'] ? null : args.notify ?? callerAddress();
+      if (address) withBoard((b) => engine.subscribe(b, created.id, address, 'creator'));
+      const status = withBoard((b) => tx(b, (db) => engine.getTask(db, created.id)));
+      answer = { ...answer, status: status.status, notify: address ?? null };
+      const line = answer.started ? `started ${created.id}: session ${answer.session} (${answer.mode})`
+        : answer.failed ? `${created.id} did not start: ${answer.failed}`
+          : answer.waits ? `${created.id} waits: ${answer.waits}`
+            : `${created.existing ? 'existing' : 'created'} ${created.id} (${status.status})`;
+      say(args, `${line}${address ? `; notices go to ${address}` : ''}`, answer);
+      return answer.failed ? 1 : 0;
+    }
+    case 'list': {
+      const cards = withBoard((b) => engine.listCards(b.db, { status: args.status, assignee: args.assignee, machine: args.machine, includeArchived: args.all }));
+      if (args.json) say(args, '', cards); else process.stdout.write(`${cards.map(row).join('\n')}${cards.length ? '\n' : ''}`);
+      return 0;
+    }
+    case 'show': {
+      need(1, 'a card id');
+      const card = withBoard((b) => engine.showCard(b.db, id));
+      if (args.json) { say(args, '', card); return 0; }
+      const t = card.task;
+      const lines = [row(t), t.body ? `\n${t.body}\n` : ''];
+      if (card.parents.length) lines.push(`parents: ${card.parents.map((p) => `${p.id} (${p.status})`).join(', ')}`);
+      if (card.children.length) lines.push(`children: ${card.children.join(', ')}`);
+      if (t.subtask_of) lines.push(`subtask of ${t.subtask_of}`);
+      for (const st of card.subtasks) lines.push(`subtask ${st.id} [${st.status}] ${st.title}`);
+      for (const r of card.runs) {
+        const s = r.metadata?.supercode;
+        const who = s ? (s.session_id ? `session ${s.session_id}${s.pane ? ` in pane ${s.pane}` : ''}` : `worker pid ${s.pid}`) : '';
+        lines.push(`run ${r.id}: ${r.status}${r.outcome ? ` / ${r.outcome}` : ''}${s ? ` — ${who} on ${s.machine} (${s.mode})` : ''}${r.summary ? ` — ${r.summary.split('\n')[0]}` : ''}`);
+      }
+      for (const c of card.comments) lines.push(`${c.author}: ${c.body}`);
+      for (const s of card.subscriptions) lines.push(`notices → ${s.chat_id} (${s.delivery_metadata?.role ?? s.platform})`);
+      process.stdout.write(`${lines.filter(Boolean).join('\n')}\n`);
+      return 0;
+    }
+    case 'context': need(1, 'a card id'); process.stdout.write(`${withBoard((b) => tx(b, (db) => engine.cardContext(db, id)))}\n`); return 0;
+    case 'comment': {
+      need(2, 'a card id and the text');
+      const n = withBoard((b) => engine.comment(b, id, args.author ?? callerAddress() ?? callerName(), rest.slice(1).join(' ')));
+      say(args, `commented on ${id}`, { ok: true, comment: n }); return 0;
+    }
+    case 'complete': need(1, 'a card id'); withBoard((b) => engine.complete(b, id, { summary: args.summary ?? null, result: args.result ?? null })); say(args, `${id} done`, { ok: true }); return 0;
+    case 'block': { need(1, 'a card id'); const s = withBoard((b) => engine.block(b, id, { reason: rest.slice(1).join(' ') || null, kind: args.kind ?? null })); say(args, `${id} ${s}`, { ok: true, status: s }); return 0; }
+    case 'unblock': { need(1, 'a card id'); const s = withBoard((b) => engine.unblock(b, id)); say(args, `${id} ${s}`, { ok: true, status: s }); return 0; }
+    case 'review': need(1, 'a card id'); withBoard((b) => engine.requestReview(b, id, { summary: args.summary ?? null, reviewer: args.reviewer ?? null })); say(args, `${id} in review`, { ok: true }); return 0;
+    case 'changes': need(1, 'a card id'); withBoard((b) => engine.requestChanges(b, id, { reason: args.reason ?? null, reviewer: args.reviewer ?? null })); say(args, `${id} sent back`, { ok: true }); return 0;
+    case 'schedule': need(1, 'a card id'); withBoard((b) => engine.schedule(b, id, rest.slice(1).join(' ') || null)); say(args, `${id} scheduled`, { ok: true }); return 0;
+    case 'promote': need(1, 'a card id'); withBoard((b) => engine.promote(b, id, { actor: callerName(), force: args.force })); say(args, `${id} ready`, { ok: true }); return 0;
+    case 'reclaim': need(1, 'a card id'); withBoard((b) => engine.reclaim(b, id, rest.slice(1).join(' ') || null)); say(args, `${id} reclaimed`, { ok: true }); return 0;
+    case 'archive': need(1, 'a card id'); withBoard((b) => engine.archive(b, id)); say(args, `${id} archived`, { ok: true }); return 0;
+    case 'assign': need(2, 'a card id and a profile (or none)'); withBoard((b) => engine.assign(b, id, rest[1] === 'none' ? null : rest[1])); say(args, `${id} → ${rest[1]}`, { ok: true }); return 0;
+    case 'move': need(2, 'a card id and a machine (or none)'); withBoard((b) => engine.setMachine(b, id, rest[1] === 'none' ? null : rest[1])); say(args, `${id} runs on ${rest[1]}`, { ok: true }); return 0;
+    case 'link': need(2, 'a parent and a child'); withBoard((b) => engine.link(b, rest[0], rest[1])); say(args, `${rest[1]} waits on ${rest[0]}`, { ok: true }); return 0;
+    case 'unlink': need(2, 'a parent and a child'); withBoard((b) => engine.unlink(b, rest[0], rest[1])); say(args, `${rest[1]} no longer waits on ${rest[0]}`, { ok: true }); return 0;
+    case 'subscribe': {
+      need(1, 'a card id');
+      const address = args.address ?? callerAddress();
+      if (!address) throw new Error('whose notices? --address sc:<machine>:<harness>:<id>');
+      withBoard((b) => engine.subscribe(b, id, address, args.role ?? 'creator'));
+      say(args, `${address} hears ${id}`, { ok: true, address }); return 0;
+    }
+    case 'unsubscribe': {
+      need(1, 'a card id');
+      const address = args.address ?? callerAddress();
+      const gone = withBoard((b) => engine.unsubscribe(b, id, address));
+      say(args, gone ? `${address} no longer hears ${id}` : `${address} did not hear ${id}`, { ok: gone }); return 0;
+    }
+    case 'dispatch': {
+      const { lanes, settings } = await laneState(root);
+      const reports = tick({ root, lanes, settings });
+      if (args.json) say(args, '', reports);
+      else for (const r of reports) process.stdout.write(`${summary(r)}\n`);
+      return reports.some((r) => r.error) ? 1 : 0;
+    }
+    case 'serve': return serve(root);
+    default: throw new Error(`no workflow verb ${verb}; \`supercode workflow help\` lists them`);
+  }
+}
+
+/** The card whose latest session is `sessionId` (the caller works it), or null. */
+function ownCard(db, sessionId) {
+  const hit = db.prepare("SELECT task_id FROM task_runs WHERE metadata LIKE ? ORDER BY id DESC LIMIT 1").get(`%"session_id":"${sessionId}"%`);
+  if (!hit) return null;
+  return engine.lastSession(db, hit.task_id)?.session_id === sessionId ? engine.getTask(db, hit.task_id) : null;
+}
+
+const READS = new Set(['list', 'show', 'context', 'help', 'init', 'dispatch']);
+
+/**
+ * What a card's own session may write (the owner's rule): on its card, comment, block with a typed reason, and send
+ * it to review; on its subtasks, create, complete, block, unblock and comment. Never its arc's completion, and never
+ * another arc's card: anything across arcs goes through the fleet's manager.
+ */
+function authorize(db, verb, rest, args, own) {
+  if (READS.has(verb)) return;
+  const refuse = (why) => { throw new Error(`the session working ${own.id} ${why}`); };
+  if (verb === 'create') {
+    if (args['subtask-of'] !== own.id) refuse(`files subtasks of its own card only (--subtask-of ${own.id})`);
+    return;
+  }
+  const card = engine.getTask(db, rest[0]);
+  if (!card) return; // the verb itself answers "no card"
+  const mine = card.id === own.id;
+  const sub = card.subtask_of === own.id;
+  const allowed = {
+    comment: mine || sub, block: mine || sub, review: mine || sub, complete: sub, unblock: sub,
+    subscribe: mine || sub, unsubscribe: mine || sub,
+  }[verb];
+  if (!allowed) refuse(mine ? `cannot ${verb} its own card; its reviewers and the fleet's manager do` : `writes only its own card and its subtasks, not ${card.id}`);
+  if (verb === 'block' && mine && !args.kind) refuse('blocks its card with a typed reason (--kind needs_input|capability|transient|dependency)');
+}
+
+/** Close the live session of a card that is not running, freeing its machine's place. */
+function closeSession(board, id) {
+  const { task, session } = tx(board, (db) => ({ task: engine.getTask(db, id), session: engine.lastSession(db, id) }));
+  if (!task) throw new Error(`no card ${id}`);
+  if (task.status === 'running') throw new Error(`${id} is running; block, complete or reclaim it before closing its session`);
+  if (!session?.pane) return null;
+  const r = spawnSync(process.env.SUPERCODE_BIN || 'supercode', ['teams', 'panes', 'close', session.pane, '--machine', session.machine], { cwd: tmpdir(), encoding: 'utf8', timeout: 60_000 });
+  if (r.status !== 0) throw new Error(`closing pane ${session.pane} on ${session.machine}: ${(r.stderr || r.stdout).trim().slice(-300)}`);
+  tx(board, (db) => event(db, id, 'session_closed', { session_id: session.session_id, machine: session.machine, pane: session.pane }));
+  return session;
+}
+
+function callerName() {
+  return process.env.HERMES_PROFILE || process.env.USER || 'user';
+}
+
+export function summary(r) {
+  const parts = [`board ${r.board}:`];
+  if (r.error) parts.push(`error ${r.error}`);
+  for (const [k, label] of [['started', 'started'], ['queued', 'waiting'], ['failed', 'failed'], ['lost', 'lost'], ['crashed', 'crashed'], ['timed_out', 'timed out'], ['reclaimed', 'reclaimed'], ['auto_blocked', 'gave up'], ['notified', 'notices']]) {
+    if (r[k]?.length) parts.push(`${label} ${r[k].length}`);
+  }
+  if (r.promoted) parts.push(`promoted ${r.promoted}`);
+  if (parts.length === 1) parts.push('nothing to do');
+  return parts.join(' ');
+}
+
+/**
+ * The dispatcher alone, for a home whose board is dispatched without the rest of the orchestrator (the lanes are
+ * re-read every tick, so a profile's change takes effect without a restart). It holds the board's one-dispatcher
+ * lock, as the daemon and Hermes's gateways do, so one dispatcher serves a board.
+ */
+async function serve(root) {
+  const lock = await holdDispatcherLock(root);
+  let stopped = false;
+  const stop = () => { stopped = true; };
+  process.on('SIGTERM', stop);
+  process.on('SIGINT', stop);
+  const log = (line) => process.stdout.write(`${new Date().toISOString()} ${line}\n`);
+  log(`dispatching the boards of ${root}`);
+  try {
+    while (!stopped) {
+      let interval = 60;
+      try {
+        const { lanes, settings } = await laneState(root);
+        interval = settings.interval;
+        for (const r of tick({ root, lanes, settings })) {
+          const said = summary(r);
+          if (!said.endsWith('nothing to do')) log(said);
+          for (const [t, why] of r.failed) log(`  ${t} did not start: ${why}`);
+          for (const [t, s, m] of r.started) log(`  ${t} started ${s} (${m})`);
+          for (const [t, to, why] of r.undelivered) log(`  notice for ${t} to ${to} not delivered: ${why}`);
+        }
+      } catch (error) {
+        log(`tick failed: ${error.message}`);
+      }
+      for (let waited = 0; waited < interval && !stopped; waited += 1) await new Promise((done) => setTimeout(done, 1000));
+    }
+  } finally {
+    lock.release();
+  }
+  log('stopped');
+  return 0;
+}
+
+export { listBoards };