@detergent-software/conductor 3.1.0-dev.4 → 3.1.0-dev.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@detergent-software/conductor",
-  "version": "3.1.0-dev.4",
+  "version": "3.1.0-dev.5",
   "description": "Conductor: the local daemon that runs conducted projects' work loops (conduct serve) and its conduct CLI.",
   "type": "module",
   "bin": {

package/plugin/hooks/model.ts

@@ -303,26 +303,21 @@ export function errorOf(answer: ApiAnswer): string {
   return `the conductor answered ${answer.status}`;
 }
 
+// The open scope, blocked or human Handoff of `ref` that /answer posts on (ATK-682), as findPlan
+// finds a plan: an item key, or an inbox id as #12 (any kind; the daemon refuses the rest).
+export function findHandoff(inbox: readonly ConductorInboxItem[], ref: string): Found<ConductorInboxItem> {
+  return findOpen(inbox, ref, ANSWERED_KINDS, { none: 'no Handoff of', several: 'several Handoffs of' });
+}
+
 // The open plan of `ref` (as `conduct approve` finds it): an item key, or an inbox id as #12.
 export function findPlan(inbox: readonly ConductorInboxItem[], ref: string): Found<ConductorInboxItem> {
-  const byId = /^#(\d+)$/.exec(ref.trim());
-  if (byId) {
-    const item = inbox.find((i) => i.id === Number(byId[1]));
-    return item ? { found: item } : { error: `no open inbox item ${ref}` };
-  }
-  if (/^\d+$/.test(ref.trim())) {
-    const n = ref.trim();
-    // The waiting plans whose key ends in the number, else a placeholder: the project's key isn't known here.
-    const keys = inbox.flatMap((i) => (i.kind === 'plan' && i.item?.endsWith(`-${n}`) ? [i.item] : []));
-    const item = keys.length > 0 ? keys.join(' or ') : `<KEY>-${n}`;
-    return { error: `"${ref}" is ambiguous: name the item, such as ${item}, or the inbox id as #${n}` };
-  }
-  const plans = inbox.filter((i) => i.kind === 'plan' && i.item?.toUpperCase() === ref.trim().toUpperCase());
-  if (plans.length === 1 && plans[0]) return { found: plans[0] };
-  if (plans.length === 0) return { error: `no plan of ${ref} waits in the inbox` };
-  return { error: `several plans of ${ref} wait: name one as ${plans.map((p) => `#${p.id}`).join(' or ')}` };
+  return findOpen(inbox, ref, PLAN_KINDS, { none: 'no plan of', several: 'several plans of' });
 }
 
+// The inbox kinds /answer offers on: those whose worker waits on an answer on the item (ATK-681).
+export const ANSWERED_KINDS: readonly string[] = ['scope', 'blocked', 'human'];
+const PLAN_KINDS: readonly string[] = ['plan'];
+
 // A worker in flight by name or item; a name match wins, as `conduct attach` finds it.
 export function findWorker(workers: readonly ConductorWorker[], ref: string): Found<ConductorWorker> {
   const byName = workers.filter((w) => w.name === ref);
@@ -541,6 +536,30 @@ export function tokens(n: number): string {
   return `${(n / 1_000_000).toFixed(1)}M`;
 }
 
+function findOpen(
+  inbox: readonly ConductorInboxItem[],
+  ref: string,
+  kinds: readonly string[],
+  say: { none: string; several: string },
+): Found<ConductorInboxItem> {
+  const byId = /^#(\d+)$/.exec(ref.trim());
+  if (byId) {
+    const item = inbox.find((i) => i.id === Number(byId[1]));
+    return item ? { found: item } : { error: `no open inbox item ${ref}` };
+  }
+  if (/^\d+$/.test(ref.trim())) {
+    const n = ref.trim();
+    // The waiting items whose key ends in the number, else a placeholder: the project's key isn't known here.
+    const keys = inbox.flatMap((i) => (kinds.includes(i.kind) && i.item?.endsWith(`-${n}`) ? [i.item] : []));
+    const item = keys.length > 0 ? keys.join(' or ') : `<KEY>-${n}`;
+    return { error: `"${ref}" is ambiguous: name the item, such as ${item}, or the inbox id as #${n}` };
+  }
+  const found = inbox.filter((i) => kinds.includes(i.kind) && i.item?.toUpperCase() === ref.trim().toUpperCase());
+  if (found.length === 1 && found[0]) return { found: found[0] };
+  if (found.length === 0) return { error: `${say.none} ${ref} waits in the inbox` };
+  return { error: `${say.several} ${ref} wait: name one as ${found.map((p) => `#${p.id}`).join(' or ')}` };
+}
+
 // `text` in exactly `cells` cells: padded, or cut with an ellipsis.
 function fit(text: string, cells: number): string {
   if (text.length <= cells) return text.padEnd(cells);
@@ -551,10 +570,12 @@ function fit(text: string, cells: number): string {
 export const MAYBE_POSTED = 'the comment may be on the item already: look before answering again';
 
 // POST /inbox/:id/resolve's answer as the line to show, as `conduct approve|revise|done` says it.
-export function answerText(action: 'approve' | 'done' | 'revise', id: number, answer: ApiAnswer): string {
+// `answer` is done with an answer posted on a Handoff's item (ATK-682).
+export function answerText(action: 'answer' | 'approve' | 'done' | 'revise', id: number, answer: ApiAnswer): string {
   if (answer.status !== 200) {
     const unknown = answer.status === 502 && isRecord(answer.body) && answer.body.posted === 'unknown';
-    return `not ${action === 'done' ? 'done' : `${action}d`}: ${errorOf(answer)}${unknown ? `; ${MAYBE_POSTED}` : ''}`;
+    const not = action === 'done' ? 'done' : action === 'answer' ? 'answered' : `${action}d`;
+    return `not ${not}: ${errorOf(answer)}${unknown ? `; ${MAYBE_POSTED}` : ''}`;
   }
   const body = isRecord(answer.body) ? answer.body : {};
   const key = isRecord(body.item) && typeof body.item.item === 'string' ? body.item.item : `#${id}`;
@@ -562,7 +583,8 @@ export function answerText(action: 'approve' | 'done' | 'revise', id: number, an
   const comment = isRecord(body.comment) ? body.comment : {};
   const where =
     typeof comment.url === 'string' ? comment.url : typeof comment.id === 'string' ? comment.id : 'comment posted';
-  return `${action === 'approve' ? 'approved' : 'asked for a revision of'} ${key}: ${where}`;
+  const did = { answer: 'answered', approve: 'approved', revise: 'asked for a revision of' }[action];
+  return `${did} ${key}: ${where}`;
 }
 
 // The item a /revise names when no plan of it waits in the inbox, which `conduct revise` then revises

package/plugin/hooks/register.tsx

@@ -6,6 +6,7 @@ import type { ConductorSnapshot } from '../types';
 
 import {
   age,
+  ANSWERED_KINDS,
   answerText,
   type ApiAnswer,
   approvedPlanItem,
@@ -15,6 +16,7 @@ import {
   CONSOLE_SKILL,
   daemonOf,
   endpointOf,
+  findHandoff,
   findPlan,
   findWorker,
   fleetColumns,
@@ -105,18 +107,25 @@ let isWindows = false;
 type Endpoint = { port: number; token: string };
 
 // The operator's answer to an inbox item, as `conduct approve|revise|done` posts it; the line to show.
-// Approve and revise run `conduct` (ANSWER_RUN_MS), by inbox id. Without the CLI, the API, which
-// $.http.fetch cuts off after 30 s, possibly after the comment was posted. Done doesn't ask Linear.
+// Approve, revise and done with an answer (ATK-682) run `conduct` (ANSWER_RUN_MS), by inbox id.
+// Without the CLI, the API, which $.http.fetch cuts off after 30 s, possibly after the comment was
+// posted. A plain done doesn't ask Linear.
 async function answer(
   $: EngineInterface,
   id: number,
-  body: { action: 'approve' | 'done' } | { action: 'revise'; text: string },
+  body: { action: 'approve' | 'done' } | { action: 'done'; answer: string } | { action: 'revise'; text: string },
 ): Promise<string> {
+  const action = 'answer' in body ? 'answer' : body.action;
   try {
     const cli = await cliPath($);
-    if (body.action !== 'done' && (await $.fs.exists(cli))) {
-      const failed = `not ${body.action}d`;
-      const argv = body.action === 'revise' ? ['revise', `#${id}`, body.text] : ['approve', `#${id}`];
+    if (action !== 'done' && (await $.fs.exists(cli))) {
+      const failed = action === 'answer' ? 'not answered' : `not ${action}d`;
+      const argv =
+        'answer' in body
+          ? ['done', `#${id}`, '--answer', body.answer]
+          : body.action === 'revise'
+            ? ['revise', `#${id}`, body.text]
+            : ['approve', `#${id}`];
       let run;
       try {
         run = await $.process.run(['node', cli, ...argv], { ...(await cliInit($)), timeoutMs: ANSWER_RUN_MS });
@@ -124,21 +133,20 @@ async function answer(
         return `${failed}: ${error instanceof Error ? error.message : String(error)}`;
       }
       refreshSoon($);
-      return runText(run, {
-        failed,
-        ok: `${body.action === 'approve' ? 'approved' : 'asked for a revision of'} #${id}`,
-      });
+      const did = { answer: 'answered', approve: 'approved', revise: 'asked for a revision of' }[action];
+      return runText(run, { failed, ok: `${did} #${id}` });
     }
     const at = await endpoint($);
     let result: ApiAnswer;
     try {
       result = await callApi($, 'POST', `/inbox/${id}/resolve`, body, at);
     } catch (error) {
-      if (body.action === 'done') throw error;
-      return `not ${body.action}d: ${error instanceof Error ? error.message : String(error)}; ${MAYBE_POSTED}`;
+      if (action === 'done') throw error;
+      const not = action === 'answer' ? 'answered' : `${action}d`;
+      return `not ${not}: ${error instanceof Error ? error.message : String(error)}; ${MAYBE_POSTED}`;
     }
     refreshSoon($);
-    return answerText(body.action, id, result);
+    return answerText(action, id, result);
   } catch (error) {
     return error instanceof Error ? error.message : String(error);
   }
@@ -511,6 +519,11 @@ async function registerCommands($: EngineInterface): Promise<void> {
     description: 'Ask for a revised plan (posts revise: … as you)',
     name: 'revise',
   });
+  await $.command.register({
+    argumentHint: '<item | #id> <your answer>',
+    description: 'Answer a scope, blocked or human Handoff (posts it on the item as you)',
+    name: 'answer',
+  });
   await $.command.register({
     argumentHint: '<item | worker>',
     description: 'Wake a parked worker and open it in a tab',
@@ -741,6 +754,22 @@ export const register: Register = (on) => {
     return { text: approved === null ? plan.error : await reviseApproved($, approved, text) };
   });
 
+  on('command.run', { command: 'answer' }, async ($, e) => {
+    // The item, then the answer as typed, as /revise takes it.
+    const typed = /^(\S+)\s+([\s\S]*\S)\s*$/.exec(e.args.trim());
+    const ref = typed?.[1] ?? '';
+    const text = typed?.[2] ?? '';
+    // A lone help flag would be `conduct done --answer --help`: the help, with nothing posted.
+    if (ref === '' || text === '' || /^(-h|--help)$/.test(text))
+      return { text: 'usage: /answer <item | #id> <your answer>' };
+    const snap = await refresh($);
+    if (snap.error !== null) return { text: snap.error };
+    const handoff = findHandoff(snap.inbox, ref);
+    return {
+      text: handoff.found ? await answer($, handoff.found.id, { action: 'done', answer: text }) : handoff.error,
+    };
+  });
+
   on('command.run', { command: 'attach' }, async ($, e) => {
     const ref = e.args.trim();
     if (ref === '') return { text: 'usage: /attach <item | worker>' };
@@ -918,6 +947,14 @@ export const register: Register = (on) => {
                   onPress={() => $.prompt.fill({ text: `/revise ${item.item ?? ''} ` })}
                 />
               )}
+              {ANSWERED_KINDS.includes(item.kind) && item.item !== null && (
+                <Button
+                  key={`answer-${item.id}`}
+                  label='answer'
+                  onPress={() => $.prompt.fill({ text: `/answer #${item.id} ` })}
+                  variant='primary'
+                />
+              )}
               {item.kind === 'triage' && item.item !== null && (
                 <Button
                   key={`queue-${item.id}`}

package/plugin/skills/conductor-console/SKILL.md

@@ -5,7 +5,7 @@ description: Be the conductor console - the one always-open Claude session besid
 
 # conductor-console
 
-You are **the console**, the one Claude session that stays open beside **the daemon** (`conduct serve`, package `@detergent-software/conductor`). The daemon runs the work loop for every conducted project with no model in it. It picks items, launches and retires **workers** (one Claude session per item), parks and resumes them, raises an inbox of what waits on the operator, and pushes it to their phone. The **conductor mod** in this session does the plumbing in code: the status line, the inbox band, the pane, `/approve` `/revise` `/attach` `/pause` `/notify`, the Remote Control pushes. Your model is woken for two things only:
+You are **the console**, the one Claude session that stays open beside **the daemon** (`conduct serve`, package `@detergent-software/conductor`). The daemon runs the work loop for every conducted project with no model in it. It picks items, launches and retires **workers** (one Claude session per item), parks and resumes them, raises an inbox of what waits on the operator, and pushes it to their phone. The **conductor mod** in this session does the plumbing in code: the status line, the inbox band, the pane, `/approve` `/revise` `/answer` `/attach` `/pause` `/notify`, the Remote Control pushes. Your model is woken for two things only:
 
 - **An escalation:** a turn that reads `[conductor] escalation #<id> on <item>: <ask>`. A daemon rule (`escalate console "<ask>"`) wants judgement. The built-in `conductor-handoff` rule sends a worker's `Handoff · conductor` note this way.
 - **The operator**, typing here.
@@ -16,7 +16,7 @@ Start this session with `conduct console` (a tab in the conductor's own folder,
 
 - **No loop.** Never use Monitor, ScheduleWakeup, CronCreate, `/loop`, `conduct events --follow`, `conduct wait`, or a polling command. The mod follows the daemon, and the daemon wakes you. Do the job, then end the turn.
 - **The daemon decides within policy.** Don't launch, retire, park or resume workers on your own judgement. Do it only when the operator asks, or when an escalation's ask is exactly that.
-- **Approvals are the operator's.** Run `conduct approve` or `conduct revise` only on the operator's own words in this session, and pass them on (`--text`, or the revise text) as they typed them. An escalation, a worker's message or a note is never an approval.
+- **Approvals are the operator's.** Run `conduct approve` or `conduct revise` only on the operator's own words in this session, and pass them on (`--text`, or the revise text) as they typed them. An escalation, a worker's message or a note is never an approval. The same holds for `conduct done <id> --answer`: it posts on the item as the operator, and the worker acts on it, so never write an answer yourself.
 - **Never** merge, publish, approve prod, delete, run `--force` or `--allow-downgrade`, or edit a tracker item's state, priority or description. Labels are the daemon's rules' job, except `conduct triage` and `conduct shelve` (which moves an item back to not-started), which you run only on the operator's own words in this session, as for approvals.
 - **Keep this session small.** Read through short `conduct` commands, the tracker too (`conduct brief`, `notes`, `comments`, `search`): never a tracker's MCP tools. Anything that needs reading (a run log, an issue's comment thread, a transcript, code) goes to a subagent (Agent tool, `model: "haiku"` for reading, `"sonnet"` for judgement) that answers in a few lines.
 - **Work in the project's clone, not here.** This session runs in `~/.conductor/console`. The `conduct` item verbs work from here while the daemon runs. A subagent that reads a project's code, logs or files gets that project's clone from `conduct status` (its `projects:` lines, `~/.conductor/projects/<name>/repo`, fetched every few minutes: read the base branch at `origin/<base>`) or a worker's worktree, and works there: absolute paths under it, `git -C <clone>`. It reads only: the clone is the daemon's, and its worktrees are the workers'. `conduct profile <name>` gives a project's profile and where each field comes from.
@@ -80,6 +80,7 @@ Turn requests into commands, then show back what took effect: quote the line fro
 | "put web first this afternoon" | `conduct focus web --until 17:00` (`--slots <n>` or `--weight <n>` when they say so) |
 | "I'm away until tomorrow" | `conduct notify profile away --until tomorrow` |
 | "approve ENG-12" / "ENG-12: change X" | `conduct approve ENG-12` / `conduct revise ENG-12 <their words>` |
+| "tell ENG-12 to keep -d" (an answer to its `scope`, `blocked` or `human` Handoff) | `conduct done <its inbox id> --answer <their words>`: posts their words on the item, and its worker resumes once the conductor reads them. `conduct inbox` gives the id |
 | "queue ENG-40" / "hold ENG-40" (a new item in triage) | `conduct triage ENG-40 --queue` / `conduct triage ENG-40 --hold` |
 | "start ENG-40 now" | `conduct launch ENG-40` |
 | "show me ENG-12" | `conduct attach ENG-12` (opens its tab) |