@volter/supercode-orchestrator 0.4.58 → 0.4.60

package/board/cli.mjs

@@ -29,7 +29,7 @@ Hermes Kanban's verbs, with their flags:
   claim <id> [--ttl]   reclaim <id> [--reason]   heartbeat <id> [--note] [--until <time|30m>]   link|unlink <parent> <child>
   comment <id> <text> [--author] [--max-len]   attach <id> <path> [--name] [--content-type]   attachments <id>   attach-rm <n>
   complete <id>... [--result] [--summary] [--metadata JSON]   edit <id> --result [--summary] [--metadata]
-  block <id> [reason] [--kind dependency|needs_input|capability|transient] [--ids ...]   schedule <id> [reason] [--ids ...]
+  block <id> [reason] (--on <card> | --waiting-on <message id>) [--ids ...]   schedule <id> [reason] [--ids ...]
   unblock <id>... [--reason]   request-review <id> [--summary] [--reviewer] [--force]   request-changes <id> <reason>   reopen-review <id>...   reopen <id>... [--reason]
   promote <id> [reason] [--ids ...] [--force] [--dry-run]   archive <id>... [--rm <id>...]
   specify <id> [--title --body] [--all]   decompose <id> [--child "<title>[@<profile>]"]... [--all]
@@ -500,7 +500,7 @@ export async function runWorkflow(argv) {
       need(1, 'a card id');
       const reason = rest.slice(1).join(' ') || null;
       const results = [];
-      for (const t of [id, ...(args.ids ?? [])]) results.push([t, (await withBoardAsync((b) => engine.block(b, t, { reason, kind: args.kind ?? null }))).to]);
+      for (const t of [id, ...(args.ids ?? [])]) results.push([t, (await withBoardAsync((b) => engine.block(b, t, { reason, on: args.on ?? null, waitingOn: args['waiting-on'] ?? null }))).to]);
       say(args, results.map(([t, s]) => `${s === 'todo' ? 'Waiting on dependencies' : s === 'triage' ? 'Routed to triage' : 'Blocked'} ${t}`).join('\n'), { ok: true, results }); return 0;
     }
     case 'schedule': {

package/board/dispatch.mjs

@@ -500,6 +500,10 @@ function observeIdle(board, fleet, settings, report, entry, effects) {
 
 /** A session effect a committed move asked for: a message to the card's current actor, or closing a slot's pane. */
 export async function sessionEffect(board, e) {
+  if (e.kind === 'tell') {
+    await send(boardAddress(board.label), board.label, e.to, e.text, `board-tell-${e.id}-${now()}`);
+    return;
+  }
   if (e.kind === 'send_to_actor') {
     const run = tx(board, (db) => currentRun(db, e.id));
     const session = run?.metadata?.supercode;

package/board/engine.mjs

@@ -15,7 +15,6 @@ import { claimer, event, json, newTaskId, now, tx } from './store.mjs';
 import { eventTo, fire, loadWorkflow, setStatus, settle, startNew, statusOf, workflowFor } from './workflow.mjs';
 
 export const STATUSES = ['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived'];
-export const BLOCK_KINDS = ['dependency', 'needs_input', 'capability', 'transient'];
 export const WORKSPACE_KINDS = ['scratch', 'dir', 'worktree'];
 /** A card blocked this many times in a row for the same kind goes to triage for a person (Hermes's limit). */
 export const BLOCK_RECURRENCE_LIMIT = 2;
@@ -408,10 +407,9 @@ function invalidateDescendants(db, board, id) {
 
 export const complete = (board, id, { result = null, summary = null, metadata = null, roles, runId = null } = {}) =>
   act(board, id, 'complete', { roles, payload: { result, summary, metadata, run_id: runId } });
-export const block = (board, id, { reason = null, kind = null, roles, runId = null } = {}) => {
-  if (kind && !BLOCK_KINDS.includes(kind)) throw new Error(`block kind is one of ${BLOCK_KINDS.join(', ')}`);
-  return act(board, id, 'block', { roles, payload: { reason, kind, run_id: runId } });
-};
+// a block names the one thing that ends it: a card it waits on (`on`), or the message whose answer it waits for (`waiting_on`)
+export const block = (board, id, { reason = null, on = null, waitingOn = null, roles, runId = null } = {}) =>
+  act(board, id, 'block', { roles, payload: { reason, on, waiting_on: waitingOn, run_id: runId } });
 export const unblock = (board, id, { reason = null, roles } = {}) => act(board, id, 'unblock', { roles, payload: { reason } });
 export const requestReview = (board, id, { summary = null, metadata = null, reviewer = null, force = false, expectedRunId = null, roles } = {}) =>
   act(board, id, 'request_review', { roles, payload: { summary, metadata, reviewer, force, run_id: expectedRunId } });

package/board/tools.mjs

@@ -101,7 +101,7 @@ export async function boardTool(root, name, args = {}, env = {}) {
       }
       case 'kanban_block': {
         const stale = ownRun(); if (stale) return error(stale);
-        const { to: status } = await engine.block(board, tid, { reason: args.reason ? redact(String(args.reason)) : null, kind: args.kind ?? null });
+        const { to: status } = await engine.block(board, tid, { reason: args.reason ? redact(String(args.reason)) : null, on: args.on ?? null, waitingOn: args.waiting_on ?? null });
         return ok({ task_id: tid, status });
       }
       case 'kanban_request_review': {

package/board/worker-prompt.mjs

@@ -14,8 +14,8 @@ export function taskProtocol(taskId) {
     '- `kanban_heartbeat` says you are still working on a long step; `kanban_comment` leaves a note on any task.',
     '- `kanban_create` files follow-up work (with `parents` to make it wait on another task); `kanban_link` adds a dependency.',
     '- When the work is done, `kanban_complete` with a `summary` a person can read (and `metadata`, `artifacts`, `created_cards` where they apply).',
-    '- If the work needs review, `kanban_request_review` instead. If you cannot go on, `kanban_block` with a `reason` and its `kind`',
-    '  (needs_input, capability, transient, or dependency when it waits on another task).',
+    '- If the work needs review, `kanban_request_review` instead. If you cannot go on, `kanban_block` with a `reason` and the one',
+    '  thing that ends the wait: `on` (the task it waits on) or `waiting_on` (the id of the message whose answer it waits for).',
     'End every run with exactly one of complete, request_review or block: a run that ends without one is counted as a failure.',
     'You may change only your own task\'s lifecycle; other tasks hear from you through comments.',
   ].join('\n');

package/board/workflow.mjs

@@ -79,6 +79,20 @@ function lastCommitAt(path, id) {
   return r.status === 0 && Number.isFinite(t) && t > 0 ? t : null;
 }
 
+/** The first answer to message `id` in its sender's mailbox (`supercode message show --replies`), as its id; or null. */
+function answerTo(id) {
+  if (!id) return null;
+  const r = spawnSync(process.env.SUPERCODE_BIN || 'supercode', ['message', 'show', '--replies', id, '--json'], { encoding: 'utf8', timeout: 20_000 });
+  try { return JSON.parse(r.stdout)?.[0]?.replies?.[0]?.id ?? null; } catch { return null; }
+}
+
+/** The session message `id` was filed for (`supercode message show`): who was asked; or null. */
+function askedOf(id) {
+  if (!id) return null;
+  const r = spawnSync(process.env.SUPERCODE_BIN || 'supercode', ['message', 'show', id, '--json'], { encoding: 'utf8', timeout: 20_000 });
+  try { return JSON.parse(r.stdout)?.[0]?.message?.session ?? null; } catch { return null; }
+}
+
 /** The scope an expression is evaluated in: the card (with its relations), the event, params, time, extras. */
 export function scopeOf(db, board, task, { params, event = {}, extra = {} } = {}) {
   const status = statusOf(db, task);
@@ -93,6 +107,8 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {} } = {}
   const interruption = json(one(db, `SELECT payload FROM task_events WHERE task_id = ? AND kind IN ('blocked', 'block_loop_detected', 'dependency_wait', 'gave_up',
     'unblocked', 'changes_requested', 'review_reopened', 'status', 'reclaimed', 'stale', 'timed_out', 'crashed', 'spawn_failed', 'rate_limited', 'session_lost')
     ORDER BY id DESC LIMIT 1`, task.id)?.payload, {}) ?? {};
+  const lastBlock = one(db, "SELECT kind, payload FROM task_events WHERE task_id = ? AND kind IN ('blocked', 'unblocked', 'dependency_wait') ORDER BY id DESC LIMIT 1", task.id);
+  const waitingOn = lastBlock?.kind === 'blocked' ? json(lastBlock.payload, {})?.waiting_on ?? null : null;
   const currentRun = task.current_run_id ? one(db, 'SELECT metadata FROM task_runs WHERE id = ?', task.current_run_id) : null;
   const session = json(currentRun?.metadata, {})?.supercode ?? {};
   const card = {
@@ -111,6 +127,10 @@ export function scopeOf(db, board, task, { params, event = {}, extra = {} } = {}
     subtasks: all(db, `SELECT t.id, ${related}, t.title, t.assignee FROM tasks t JOIN supercode_cards c ON c.task_id = t.id WHERE c.subtask_of = ? ORDER BY t.created_at`, task.id),
     queue_reason: json(one(db, "SELECT payload FROM task_events WHERE task_id = ? AND kind = 'respawn_guarded' AND created_at >= ? ORDER BY id DESC LIMIT 1",
       task.id, Number(one(db, 'SELECT since FROM supercode_cards WHERE task_id = ?', task.id)?.since ?? 0))?.payload, {})?.reason ?? null,
+    // the message whose answer the standing block waits for (`block --waiting-on`), and that answer's id once it has landed
+    waiting_on: waitingOn,
+    answer: () => answerTo(waitingOn),
+    asked_of: () => askedOf(waitingOn),
     last_block_event: one(db, "SELECT kind FROM task_events WHERE task_id = ? AND kind IN ('blocked', 'unblocked') ORDER BY id DESC LIMIT 1", task.id)?.kind ?? null,
     // where the latest interruption says the card resumes (any status the workflow declares); none recorded: null
     resume_status: interruption.resume_status ?? interruption.retry_status ?? interruption.source_status ?? null,
@@ -321,14 +341,15 @@ const FORMAT = {
     const artifacts = Array.isArray(e.metadata?.artifacts) ? e.metadata.artifacts.filter((a) => typeof a === 'string' && a.trim()) : [];
     return { result_len: e.result ? String(e.result).length : 0, summary: firstLine(e.summary ?? e.result), ...(artifacts.length ? { artifacts } : {}) };
   },
-  blocked: ({ e, after, source }) => ({ reason: e.reason ?? null, kind: e.kind ?? null, recurrences: Number(after.block_recurrences || 0), source_status: source }),
+  blocked: ({ e, after, source }) => ({ reason: e.reason ?? null, on: e.on ?? null, waiting_on: e.waiting_on ?? null, recurrences: Number(after.block_recurrences || 0), source_status: source }),
   block_loop_detected: ({ e, after, source, params }) => ({ reason: e.reason ?? null, kind: e.kind ?? null, recurrences: Number(after.block_recurrences || 0), limit: params.block_recurrence_limit, source_status: source }),
-  dependency_wait: ({ e, source }) => ({ reason: e.reason ?? null, kind: e.kind ?? null, source_status: source }),
+  dependency_wait: ({ e, source }) => ({ reason: e.reason ?? null, on: e.on ?? null, source_status: source }),
   review_requested: ({ e, before, after }) => ({ summary: firstLine(e.summary), implementer: before.assignee, reviewer: after.assignee !== before.assignee ? after.assignee : (e.reviewer ?? null) }),
   // the reviewer is the lane that reviewed (the card's assignee while in review), unless the verdict names one
   changes_requested: ({ e, before, after }) => ({ reason: e.reason ?? null, reviewer: e.reviewer ?? before.assignee ?? null, implementer: after.assignee }),
   review_reopened: ({ after, to }) => ({ status: to, implementer: after.assignee }),
-  unblocked: ({ to }) => (to !== 'ready' ? { status: to, resume_status: to } : null),
+  // what arrived (an unblock says it), and where the card resumes
+  unblocked: ({ e, to }) => ({ reason: e.reason ?? null, ...(to !== 'ready' ? { status: to, resume_status: to } : {}) }),
   gave_up: ({ e, after, params, outcome }) => ({ error: String(e.error ?? '').slice(0, 500) || null, failures: Number(after.consecutive_failures || 0), limit: after.max_retries ?? params.failure_limit, outcome }),
   promoted_manual: ({ e }) => ({ actor: e.actor ?? 'user', reason: e.reason ?? null, forced: Boolean(e.force) }),
   promoted: ({ to }) => (to !== 'ready' ? { status: to } : null),
@@ -361,7 +382,10 @@ const ACTIONS = {
       const { run_id: _r, force: _f, lock: _l, ...said } = e;
       payload = { ...said, ...(RETRY_KINDS.has(kind) ? { retry_status: ctx.to } : { source_status: source }) };
     }
-    record(ctx.db, ctx.id, kind, payload && Object.keys(payload).length ? payload : null, ctx.runId);
+    // `on`: the event is another card's (a dependency hears what waits on it), recorded there with no run
+    const on = typeof args === 'object' && args?.on ? String(args.on) : null;
+    if (on && !one(ctx.db, 'SELECT id FROM tasks WHERE id = ?', on)) return;
+    record(ctx.db, on ?? ctx.id, kind, payload && Object.keys(payload).length ? payload : null, on ? null : ctx.runId);
   },
   assign(ctx, { field, value }) {
     if (!ASSIGNABLE.has(field)) throw new Error(`the workflow assigns ${field}, which is not a card field it may set`);
@@ -432,9 +456,16 @@ const ACTIONS = {
     const e = said ?? {};
     const summary = e.summary ?? null;
     run(ctx.db, 'UPDATE tasks SET result = COALESCE(?, result), completed_at = COALESCE(completed_at, ?) WHERE id = ?', e.result ?? summary ?? null, now(), ctx.id);
-    if (ctx.runId) run(ctx.db, 'UPDATE task_runs SET summary = COALESCE(?, summary), metadata = COALESCE(?, metadata) WHERE id = ?', summary, e.metadata ? JSON.stringify(e.metadata) : null, ctx.runId);
+    if (!ctx.runId) return;
+    // the completion's metadata joins the run's; the board's record of the run's session (`supercode`) stays, so the
+    // session is still closed when the card is done
+    const was = json(one(ctx.db, 'SELECT metadata FROM task_runs WHERE id = ?', ctx.runId)?.metadata, {}) ?? {};
+    const given = e.metadata && typeof e.metadata === 'object' ? e.metadata : null;
+    run(ctx.db, 'UPDATE task_runs SET summary = COALESCE(?, summary), metadata = ? WHERE id = ?', summary,
+      given ? JSON.stringify({ ...was, ...given, ...(was.supercode ? { supercode: was.supercode } : {}) }) : (Object.keys(was).length ? JSON.stringify(was) : null), ctx.runId);
   },
   link(ctx, parent) {
+    if (!one(ctx.db, 'SELECT id FROM tasks WHERE id = ?', parent)) throw new Error(`${parent} is no card on this board`);
     run(ctx.db, 'INSERT OR IGNORE INTO task_links (parent_id, child_id) VALUES (?, ?)', parent, ctx.id);
   },
   unlink(ctx, parent) {
@@ -476,6 +507,8 @@ const ACTIONS = {
       return;
     }
   },
+  // a message from the board to a session (`to`: its address)
+  tell(ctx, { to, text }) { if (to) ctx.effects.push({ kind: 'tell', id: ctx.id, to: String(to), text: String(text ?? '') }); },
   send_to_actor(ctx, text) { ctx.effects.push({ kind: 'send_to_actor', id: ctx.id, text }); },
 };
 

package/mcp/hermes-kanban-tools.json

@@ -106,7 +106,7 @@
   },
   {
     "name": "kanban_block",
-    "description": "Stop work on this task and route it according to WHY you're stuck. Set ``kind`` to say which: 'dependency' (waiting on another task — goes to todo and auto-resumes when that task finishes, no human needed), 'needs_input' (you need a human decision/answer), 'capability' (a hard wall: no access, missing credentials, an action no agent can do), or 'transient' (a flaky failure that may clear). ``reason`` is shown to the human on the board. If a task keeps getting unblocked and re-blocked for the same reason, it is auto-escalated to triage. Use for genuine blockers only — don't block on things you can resolve yourself.",
+    "description": "Stop work on this task until one thing ends the wait, and name it: `on`, the task it waits on (it goes to todo and resumes when that task closes), or `waiting_on`, the id of the message you sent whose answer it waits for (it resumes when an answer to that message lands in your mailbox). An outside event is a task on the card of whoever makes it happen or watches for it. `reason` is shown on the board. The same block twice goes to triage.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -118,15 +118,13 @@
           "type": "string",
           "description": "What you need answered or what stopped you, in one or two sentences. Don't paste the whole conversation; the human has the board and can ask follow-ups via comments."
         },
-        "kind": {
+        "on": {
           "type": "string",
-          "enum": [
-            "dependency",
-            "needs_input",
-            "capability",
-            "transient"
-          ],
-          "description": "Why you're blocked. 'dependency' waits in todo and resumes automatically; the others surface to a human. Omit only if none apply."
+          "description": "The task id this waits on."
+        },
+        "waiting_on": {
+          "type": "string",
+          "description": "The id of the message (m-… or a-…) whose answer this waits for."
         },
         "board": {
           "type": "string",

package/package.json

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