@volter/supercode-orchestrator 0.4.16 → 0.4.18

package/board/engine.mjs

@@ -105,7 +105,8 @@ function retryStatus(db, taskId) {
   const row = one(db, 'SELECT current_run_id FROM tasks WHERE id = ?', taskId);
   if (!row?.current_run_id) return 'ready';
   const claimed = one(db, "SELECT payload FROM task_events WHERE task_id = ? AND run_id = ? AND kind = 'claimed' ORDER BY id DESC LIMIT 1", taskId, row.current_run_id);
-  return json(claimed?.payload, {})?.source_status === 'review' ? 'review' : 'ready';
+  const source = json(claimed?.payload, {})?.source_status;
+  return source === 'review' || source === 'triage' ? source : 'ready';
 }
 
 /** The phase a card blocked out of comes back to (Hermes reads it off the latest interruption). */
@@ -151,12 +152,13 @@ export function createCard(board, spec) {
     while (one(db, 'SELECT 1 FROM tasks WHERE id = ?', id)) id = newTaskId();
     const t = now();
     run(db, `INSERT INTO tasks (id, title, body, assignee, status, priority, created_by, created_at, workspace_kind, workspace_path, branch_name,
-               tenant, idempotency_key, max_runtime_seconds, skills, max_retries, model_override, provider_override, reasoning_effort, session_id)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+               tenant, idempotency_key, max_runtime_seconds, skills, max_retries, model_override, provider_override, reasoning_effort, session_id,
+               project_id, goal_mode, goal_max_turns)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       id, title, spec.body ?? null, spec.assignee || null, status, Number(spec.priority) || 0, spec.createdBy ?? 'user', t, ws.kind, ws.path,
       spec.branch ?? null, spec.tenant ?? null, spec.idempotencyKey ?? null, spec.maxRuntime ?? null,
       spec.skills?.length ? JSON.stringify(spec.skills) : null, spec.maxRetries ?? null, spec.model ?? null, spec.provider ?? null,
-      spec.reasoning ?? null, spec.sessionId ?? null);
+      spec.reasoning ?? null, spec.sessionId ?? null, spec.project ?? null, spec.goal ? 1 : 0, spec.goal?.maxTurns ?? null);
     const machine = spec.machine ?? arc?.machine ?? null;
     if (machine || arc) run(db, 'INSERT OR REPLACE INTO supercode_cards (task_id, machine, subtask_of) VALUES (?, ?, ?)', id, machine, arc?.id ?? null);
     for (const p of parents) run(db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', p, id);
@@ -250,7 +252,8 @@ export function claim(board, id, { ttl, lock = claimer(), expectStatus = 'ready'
 
 /** `claim` inside the caller's own transaction (a dispatcher's guard and claim see one state). */
 export function claimIn(db, id, { ttl = claimTtl(), lock = claimer(), expectStatus = null } = {}) {
-  if (!parentsDone(db, id)) {
+  // a triage card is claimed to be specified, which does not wait on its parents
+  if (expectStatus !== 'triage' && !parentsDone(db, id)) {
     run(db, "UPDATE tasks SET status = 'todo' WHERE id = ? AND status = 'ready'", id);
     event(db, id, 'claim_rejected', { reason: 'parents_not_done' });
     return null;
@@ -268,7 +271,7 @@ export function claimIn(db, id, { ttl = claimTtl(), lock = claimer(), expectStat
     id, task.assignee, task.current_step_key, lock, expires, task.max_runtime_seconds, t);
   const runId = Number(r.lastInsertRowid);
   run(db, 'UPDATE tasks SET current_run_id = ? WHERE id = ?', runId, id);
-  event(db, id, 'claimed', { lock, expires, run_id: runId, source_status: task.status === 'review' ? 'review' : 'ready' }, runId);
+  event(db, id, 'claimed', { lock, expires, run_id: runId, source_status: ['review', 'triage'].includes(task.status) ? task.status : 'ready' }, runId);
   return runId;
 }
 
@@ -323,6 +326,10 @@ export function complete(board, id, { result = null, summary = null, metadata =
     if (runId === null && (said || metadata || task.status === 'review')) runId = synthesizeRun(db, id, { outcome: 'completed', summary: said ?? (task.status === 'review' ? 'Review approved without additional evidence.' : null), metadata });
     const first = String(said ?? '').trim().split('\n')[0].slice(0, 400);
     event(db, id, 'completed', { result_len: result ? result.length : 0, summary: first || null }, runId);
+    // card ids the handoff names that no card has (Hermes flags them the same way)
+    const named = [...new Set(`${summary ?? ''} ${result ?? ''}`.match(/\bt_[a-f0-9]{8,}\b/g) ?? [])];
+    const phantom = named.filter((t) => !one(db, 'SELECT 1 FROM tasks WHERE id = ?', t));
+    if (phantom.length) event(db, id, 'suspected_hallucinated_references', { phantom_refs: phantom, source: 'completion_summary' }, runId);
     recomputeIn(db);
   });
 }
@@ -380,7 +387,9 @@ export function requestChanges(board, id, { reason = null, reviewer = null, impl
   return tx(board, (db) => {
     const task = must(db, id);
     if (task.status !== 'review' && !(task.status === 'running' && retryStatus(db, id) === 'review')) throw new Error(`${id} is not in review`);
-    const back = implementer ?? task.assignee;
+    // back to the implementer the review request recorded, not to the reviewer now holding it
+    const asked = json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'review_requested' ORDER BY id DESC LIMIT 1", id)?.payload, {}) ?? {};
+    const back = implementer ?? asked.implementer ?? task.assignee;
     run(db, "UPDATE tasks SET status = ?, assignee = ?, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", parentsDone(db, id) ? 'ready' : 'todo', back, id);
     const runId = endRun(db, id, { outcome: 'changes_requested', summary: reason });
     event(db, id, 'changes_requested', { reason, reviewer, implementer: back }, runId);
@@ -545,3 +554,212 @@ export function cardContext(db, id) {
   }
   return out.join('\n');
 }
+
+// ------------------------------------------------------------------ the rest of Hermes's verbs
+
+/** A triage card gets its spec (a tightened title and a body) and waits in todo for its parents, as Hermes's specifier leaves it. */
+export function specify(board, id, { title = null, body = null, author = 'user' } = {}) {
+  return tx(board, (db) => {
+    const task = must(db, id);
+    if (task.status !== 'triage' && task.status !== 'running') throw new Error(`${id} is ${task.status}; only a triage card is specified`);
+    if (title && String(title).trim()) run(db, 'UPDATE tasks SET title = ? WHERE id = ?', String(title).trim(), id);
+    if (body !== null) run(db, 'UPDATE tasks SET body = ? WHERE id = ?', body, id);
+    run(db, "UPDATE tasks SET status = 'todo', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", id);
+    const runId = endRun(db, id, { outcome: 'specified', summary: 'specified' });
+    event(db, id, 'specified', { author, title_changed: Boolean(title), body_len: body ? body.length : 0 }, runId);
+    recomputeIn(db);
+  });
+}
+
+/**
+ * A triage card fans out into children it waits on (Hermes's decomposer: the root stays and is the child of every
+ * leaf, so it wakes when the graph is done). `children` are `{ title, body?, assignee? }`; answers their ids.
+ */
+export function decompose(board, id, children, { author = 'user' } = {}) {
+  if (!children.length) throw new Error('decompose names at least one child (--child "<title>[@<assignee>]")');
+  const task = tx(board, (db) => must(db, id));
+  if (task.status !== 'triage' && task.status !== 'running') throw new Error(`${id} is ${task.status}; only a triage card is decomposed`);
+  const ids = children.map((c) => createCard(board, {
+    title: c.title, body: c.body ?? null, assignee: c.assignee ?? task.assignee, machine: task.machine,
+    workspace: task.workspace_path ? `${task.workspace_kind}:${task.workspace_path}` : task.workspace_kind, tenant: task.tenant, createdBy: author,
+  }).id);
+  tx(board, (db) => {
+    for (const child of ids) run(db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', child, id);
+    run(db, "UPDATE tasks SET status = 'todo', claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?", id);
+    const runId = endRun(db, id, { outcome: 'decomposed', summary: `decomposed into ${ids.join(', ')}` });
+    event(db, id, 'decomposed', { children: ids, author }, runId);
+  });
+  return ids;
+}
+
+/** Hermes's swarm: a completed root as the shared blackboard, workers after it, a verifier after them all, a synthesizer last. */
+export function swarm(board, { goal, workers, verifier, synthesizer, tenant = null, createdBy = 'swarm-orchestrator', priority = 0, idempotencyKey = null }) {
+  if (!String(goal ?? '').trim()) throw new Error('a swarm has a goal');
+  if (!workers.length) throw new Error('a swarm has at least one --worker PROFILE:TITLE[:SKILL,SKILL]');
+  const protocol = (root) => `\n\n## Swarm protocol\n- Swarm root / shared blackboard: \`${root}\`.\n- Read sibling/parent handoffs from the board's context before working.\n`
+    + `- Put machine-readable facts in completion metadata.\n- Put cross-worker notes on the root card as comments.\n- Goal: ${goal.trim()}\n`;
+  const root = createCard(board, { title: `Swarm: ${goal.trim()}`.slice(0, 200), body: goal, tenant, createdBy, priority, idempotencyKey, initialStatus: 'blocked' });
+  if (root.existing) return { root_id: root.id, existing: true };
+  tx(board, (db) => {
+    run(db, "UPDATE tasks SET status = 'done', completed_at = ? WHERE id = ?", now(), root.id);
+    const runId = synthesizeRun(db, root.id, { outcome: 'completed', summary: 'swarm blackboard', metadata: { swarm: true } });
+    event(db, root.id, 'completed', { result_len: 0, summary: 'swarm blackboard' }, runId);
+  });
+  const workerIds = workers.map((w) => createCard(board, { title: w.title, body: `${w.title}${protocol(root.id)}`, assignee: w.profile, skills: w.skills, parents: [root.id], tenant, createdBy, priority }).id);
+  const verifierId = createCard(board, { title: 'Verify swarm outputs', body: `Verify the workers' outputs.${protocol(root.id)}`, assignee: verifier, parents: workerIds, tenant, createdBy, priority }).id;
+  const synthesizerId = createCard(board, { title: 'Synthesize swarm outputs', body: `Synthesize the verified outputs.${protocol(root.id)}`, assignee: synthesizer, parents: [verifierId], tenant, createdBy, priority }).id;
+  return { root_id: root.id, worker_ids: workerIds, verifier_id: verifierId, synthesizer_id: synthesizerId };
+}
+
+/** Hermes's `edit`: correct a done card's result (and its completed run's summary and metadata). */
+export function editResult(board, id, { result, summary = null, metadata = undefined }) {
+  return tx(board, (db) => {
+    const task = must(db, id);
+    if (task.status !== 'done') throw new Error(`${id} is ${task.status}; edit corrects a done card's result`);
+    run(db, 'UPDATE tasks SET result = ? WHERE id = ?', result, id);
+    const said = summary ?? result;
+    const last = one(db, "SELECT id FROM task_runs WHERE task_id = ? AND outcome = 'completed' ORDER BY COALESCE(ended_at, started_at, 0) DESC, id DESC LIMIT 1", id);
+    let runId = last ? Number(last.id) : null;
+    if (runId === null) runId = synthesizeRun(db, id, { outcome: 'completed', summary: said, metadata: metadata ?? null });
+    else {
+      run(db, 'UPDATE task_runs SET summary = ? WHERE id = ?', said, runId);
+      if (metadata !== undefined) run(db, 'UPDATE task_runs SET metadata = ? WHERE id = ?', JSON.stringify(metadata), runId);
+    }
+    event(db, id, 'edited', { fields: ['result', 'summary', ...(metadata !== undefined ? ['metadata'] : [])], result_len: result ? result.length : 0, summary: String(said ?? '').split('\n')[0].slice(0, 400) || null }, runId);
+  });
+}
+
+/** Send a card in review back to its implementer (ready, or todo while parents are open). */
+export function reopenReview(board, id) {
+  return tx(board, (db) => {
+    const task = must(db, id);
+    if (task.status !== 'review') throw new Error(`${id} is ${task.status}, not in review`);
+    const handoff = json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'review_requested' ORDER BY id DESC LIMIT 1", id)?.payload, {}) ?? {};
+    const status = parentsDone(db, id) ? 'ready' : 'todo';
+    const implementer = typeof handoff.implementer === 'string' && handoff.implementer.trim() ? handoff.implementer : null;
+    run(db, `UPDATE tasks SET status = ?, current_run_id = NULL, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL${implementer ? ', assignee = ?' : ''} WHERE id = ?`, ...(implementer ? [status, implementer, id] : [status, id]));
+    event(db, id, 'review_reopened', { status, ...(implementer ? { implementer } : {}) });
+    return status;
+  });
+}
+
+/** A running card's worker says it is alive (Hermes's `heartbeat`); the dispatcher does not rely on it. */
+export function heartbeat(board, id, note = null) {
+  return tx(board, (db) => {
+    const task = must(db, id);
+    if (task.status !== 'running') throw new Error(`${id} is ${task.status}, not running`);
+    const t = now();
+    run(db, 'UPDATE tasks SET last_heartbeat_at = ? WHERE id = ?', t, id);
+    if (task.current_run_id) run(db, 'UPDATE task_runs SET last_heartbeat_at = ? WHERE id = ?', t, task.current_run_id);
+    event(db, id, 'heartbeat', note ? { note } : null, task.current_run_id);
+  });
+}
+
+/** A card's model (and provider) for its next start, or cleared. */
+export function setModel(board, id, model = null, provider = null) {
+  if (provider && !model) throw new Error('a provider needs a model');
+  return tx(board, (db) => {
+    must(db, id);
+    run(db, 'UPDATE tasks SET model_override = ?, provider_override = ? WHERE id = ?', model || null, provider || null, id);
+    event(db, id, 'model_override_set', { model: model || null, provider: provider || null });
+  });
+}
+
+export function addAttachment(board, id, { file, name, contentType = null, author = 'user', dir }) {
+  return tx(board, (db) => {
+    must(db, id);
+    const r = run(db, 'INSERT INTO task_attachments (task_id, filename, stored_path, content_type, size, uploaded_by, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)',
+      id, name, file.path, contentType, file.size, author, now());
+    event(db, id, 'attachment_added', { id: Number(r.lastInsertRowid), filename: name, size: file.size });
+    return Number(r.lastInsertRowid);
+  });
+}
+
+export const attachments = (db, id) => all(db, 'SELECT * FROM task_attachments WHERE task_id = ? ORDER BY id', id);
+
+export function removeAttachment(board, attachmentId) {
+  return tx(board, (db) => {
+    const row = one(db, 'SELECT * FROM task_attachments WHERE id = ?', attachmentId);
+    if (!row) throw new Error(`no attachment ${attachmentId}`);
+    run(db, 'DELETE FROM task_attachments WHERE id = ?', attachmentId);
+    event(db, row.task_id, 'attachment_removed', { id: Number(attachmentId), filename: row.filename });
+    return row;
+  });
+}
+
+/** Per status, per assignee, and the oldest ready card's age (Hermes's `stats`). */
+export function stats(db) {
+  const byStatus = {};
+  for (const r of all(db, "SELECT status, COUNT(*) AS n FROM tasks WHERE status != 'archived' GROUP BY status")) byStatus[r.status] = Number(r.n);
+  const byAssignee = {};
+  for (const r of all(db, "SELECT assignee, status, COUNT(*) AS n FROM tasks WHERE status != 'archived' AND assignee IS NOT NULL GROUP BY assignee, status")) (byAssignee[r.assignee] ??= {})[r.status] = Number(r.n);
+  const byMachine = {};
+  for (const r of all(db, "SELECT c.machine, t.status, COUNT(*) AS n FROM tasks t JOIN supercode_cards c ON c.task_id = t.id WHERE t.status != 'archived' AND c.machine IS NOT NULL GROUP BY c.machine, t.status")) (byMachine[r.machine] ??= {})[r.status] = Number(r.n);
+  const oldest = one(db, "SELECT MIN(created_at) AS ts FROM tasks WHERE status = 'ready'")?.ts;
+  const t = now();
+  return { by_status: byStatus, by_assignee: byAssignee, by_machine: byMachine, oldest_ready_age_seconds: oldest ? t - Number(oldest) : null, now: t };
+}
+
+export function runs(db, id, { stateType = null, stateName = null } = {}) {
+  must(db, id);
+  const where = stateType === 'status' ? ' AND status = ?' : stateType === 'outcome' ? ' AND outcome = ?' : '';
+  return all(db, `SELECT * FROM task_runs WHERE task_id = ?${where} ORDER BY id`, ...(where ? [id, stateName] : [id])).map((r) => ({ ...r, metadata: json(r.metadata, null) }));
+}
+
+/** Delete the thread events of done and archived cards older than `seconds` (Hermes's `gc` of events). */
+export function gcEvents(board, seconds) {
+  return tx(board, (db) => Number(run(db, "DELETE FROM task_events WHERE created_at < ? AND task_id IN (SELECT id FROM tasks WHERE status IN ('done', 'archived'))", now() - seconds).changes));
+}
+
+// ------------------------------------------------------------------ diagnostics
+
+const hours = (s) => s / 3600;
+
+/**
+ * Distress signals on a card, computed on demand and never stored (Hermes's diagnostics, the same kinds where the
+ * same thing can go wrong, and supercode's own where only its sessions can): each `{ kind, severity, title, data,
+ * actions }`, worst first.
+ */
+export function diagnose(db, task, { failureLimit = DEFAULT_FAILURE_LIMIT, strandedSeconds = 30 * 60, blockedHours = 24, fleet = null } = {}) {
+  const out = [];
+  const t = now();
+  const events = all(db, 'SELECT kind, payload, created_at FROM task_events WHERE task_id = ? ORDER BY id', task.id);
+  const failures = Number(task.consecutive_failures || 0);
+  if (failures >= Math.max(1, (task.max_retries ?? failureLimit) - 1) && task.status !== 'done') {
+    out.push({ kind: 'repeated_failures', severity: task.status === 'blocked' ? 'error' : 'warning', title: `${failures} consecutive failures`,
+      data: { failures, last_error: task.last_failure_error }, actions: [`supercode workflow reclaim ${task.id}`, `supercode workflow reassign ${task.id} <profile>`] });
+  }
+  const phantom = [...events].reverse().find((e) => e.kind === 'suspected_hallucinated_references');
+  if (phantom && !events.some((e) => e.kind === 'edited' && e.created_at > phantom.created_at)) {
+    out.push({ kind: 'prose_phantom_refs', severity: 'warning', title: 'its completion summary names card ids no card has', data: json(phantom.payload, {}) ?? {}, actions: [`supercode workflow edit ${task.id} --result <corrected>`] });
+  }
+  const lost = events.filter((e) => e.kind === 'session_lost' && t - e.created_at < 24 * 3600).length;
+  if (lost >= 2) out.push({ kind: 'repeated_session_loss', severity: 'warning', title: `its session was lost ${lost}x in 24h`, data: { lost }, actions: [`supercode workflow move ${task.id} <machine>`] });
+  const crashes = events.filter((e) => e.kind === 'crashed' && t - e.created_at < 24 * 3600).length;
+  if (crashes >= 2) out.push({ kind: 'repeated_crashes', severity: 'error', title: `its worker crashed ${crashes}x in 24h`, data: { crashes }, actions: [`supercode workflow log ${task.id}`] });
+  if (task.status === 'blocked') {
+    const since = [...events].reverse().find((e) => e.kind === 'blocked' || e.kind === 'gave_up')?.created_at ?? task.created_at;
+    if (hours(t - since) >= blockedHours) out.push({ kind: 'stuck_in_blocked', severity: 'warning', title: `blocked for ${Math.floor(hours(t - since))}h`, data: { hours: Math.floor(hours(t - since)) }, actions: [`supercode workflow unblock ${task.id}`] });
+    const cycles = events.filter((e) => e.kind === 'unblocked' && t - e.created_at < 24 * 3600).length;
+    if (cycles >= 3) out.push({ kind: 'block_unblock_cycling', severity: 'warning', title: `block→unblock cycled ${cycles}x in 24h`, data: { cycles }, actions: [] });
+  }
+  if (task.status === 'ready' && task.assignee) {
+    const since = [...events].reverse().find((e) => ['created', 'promoted', 'unblocked', 'reclaimed', 'session_lost', 'promoted_manual'].includes(e.kind))?.created_at ?? task.created_at;
+    const age = t - since;
+    if (age >= strandedSeconds) {
+      const guard = json([...events].reverse().find((e) => e.kind === 'respawn_guarded')?.payload, {})?.reason;
+      out.push({ kind: 'stranded_in_ready', severity: age >= strandedSeconds * 6 ? 'critical' : age >= strandedSeconds * 2 ? 'error' : 'warning',
+        title: `ready for ${Math.floor(age / 60)}m with no session`, data: { age_seconds: age, ...(guard ? { waiting_because: guard } : {}) }, actions: [`supercode workflow reassign ${task.id} <profile>`] });
+    }
+  }
+  if (task.status === 'review') {
+    const children = all(db, 'SELECT child_id FROM task_links WHERE parent_id = ?', task.id).length;
+    if (children) out.push({ kind: 'review_dependency_deadlock', severity: 'warning', title: `review handoff holds ${children} dependent card(s)`, data: { children }, actions: [`supercode workflow complete ${task.id}`] });
+  }
+  if (task.status === 'running' && fleet?.ok) {
+    const session = lastSession(db, task.id);
+    if (session?.machine && !fleet.online.has(session.machine)) out.push({ kind: 'machine_offline', severity: 'warning', title: `its machine ${session.machine} is offline`, data: { machine: session.machine }, actions: [] });
+  }
+  const order = ['critical', 'error', 'warning'];
+  return out.sort((a, b) => order.indexOf(a.severity) - order.indexOf(b.severity));
+}

package/board.mjs

@@ -54,7 +54,6 @@ export async function startBoard({ root, config = {}, log = () => {} }) {
         for (const [task, why] of r.failed ?? []) log('warn', `board ${r.board}: ${task} did not start: ${why}`);
         for (const [task, to, why] of r.undelivered ?? []) log('warn', `board ${r.board}: a notice for ${task} to ${to} was not delivered: ${why}`);
         if (r.chat_subscriptions && !said.has(`subs:${r.board}`)) { said.add(`subs:${r.board}`); log('warn', `board ${r.board}: ${r.chat_subscriptions} subscription(s) name a chat platform, which Hermes's gateway notifier serves and this dispatcher does not (it tells supercode sessions)`); }
-        if (r.triage && !said.has(`triage:${r.board}`)) { said.add(`triage:${r.board}`); log('warn', `board ${r.board}: ${r.triage} triage card(s) wait for decomposition, which Hermes's gateway runs on its auxiliary model and this dispatcher does not`); }
         if (r.nonspawnable?.length && !said.has(`lane:${r.board}`)) { said.add(`lane:${r.board}`); log('warn', `board ${r.board}: ${r.nonspawnable.length} card(s) name an assignee that is no profile of this home, and wait`); }
       }
     } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.4.16",
+  "version": "0.4.18",
   "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": {