@forwardimpact/libharness 3.0.0 → 3.0.2

package/src/judge.js

@@ -1,13 +1,13 @@
 /**
  * Judge — one agent session that inspects a completed agent's work and emits
- * a verdict via the orchestration `Conclude` tool. Parallel concept to
- * `Supervisor` and `Facilitator`, but post-hoc and solo: no peer agents,
- * no message bus, no orchestration loop. The judge reads the task, optionally
- * inspects the working directory and trace via read-only tools, and calls
- * Conclude exactly once.
+ * a verdict through the orchestration `Conclude` tool. It is a parallel
+ * concept to `Supervisor` and `Facilitator`. It runs post-hoc and solo: no
+ * peer agents, no message bus, no orchestration loop. The judge reads the
+ * task. It can inspect the working directory and the trace with read-only
+ * tools. It calls Conclude exactly once.
  *
- * Trace lines are tagged `source: "judge"` so consumers can distinguish
- * judge sessions from supervisor or facilitator sessions in a unified
+ * The judge tags trace lines with `source: "judge"`. Consumers can then tell
+ * judge sessions apart from supervisor or facilitator sessions in a unified
  * NDJSON envelope.
  *
  * Follows OO+DI: constructor injection, factory function, tests bypass factory.
@@ -25,17 +25,19 @@ import {
 } from "./orchestration-toolkit.js";
 
 /**
- * System-prompt trailer appended to the judge's main thread. Always applied,
- * even when a `judgeProfile` is supplied — the profile layers on top of the
- * trailer, the same way `SUPERVISOR_SYSTEM_PROMPT` and
- * `FACILITATOR_SYSTEM_PROMPT` work for their respective roles.
+ * System-prompt trailer for the judge's main thread. The factory always
+ * applies it, even when the caller supplies a `judgeProfile`. The profile
+ * layers on top of the trailer. `SUPERVISOR_SYSTEM_PROMPT` and
+ * `FACILITATOR_SYSTEM_PROMPT` work the same way for their roles.
  */
 export const JUDGE_SYSTEM_PROMPT =
   "You are a post-hoc judge for an agent task benchmark. " +
-  "The agent has already completed its work and an objective invariants step has already run; your role is to confirm or override the verdict by inspecting the agent's working directory and trace. " +
-  "You have read-only inspection tools — Read, Glob, Grep, Bash — to investigate; do not modify the working directory. " +
-  "Conclude ends the session with a verdict ('success' or 'failure') and a one-paragraph summary; verdict='success' iff the agent's work meets the criteria stated in the task. " +
-  "Call Conclude as your final action — do not deliberate across multiple turns.";
+  "The agent already completed its work. An objective invariants step already ran. " +
+  "Confirm or override the verdict. To do so, inspect the agent's working directory and trace. " +
+  "You have read-only inspection tools to investigate: Read, Glob, Grep, and Bash. Do not modify the working directory. " +
+  "Conclude ends the session with a verdict ('success' or 'failure') and a one-paragraph summary. " +
+  "Set verdict='success' exactly when the agent's work meets the criteria the task states. " +
+  "Call Conclude as your final action. Do not deliberate across multiple turns.";
 
 const DEFAULT_JUDGE_ALLOWED_TOOLS = ["Read", "Glob", "Grep", "Bash"];
 
@@ -45,7 +47,7 @@ const devNull = new Writable({
   },
 });
 
-/** Run a single post-hoc judge session and emit a verdict via Conclude. */
+/** Run a single post-hoc judge session and emit a verdict with Conclude. */
 export class Judge {
   /**
    * @param {object} deps
@@ -53,7 +55,7 @@ export class Judge {
    * @param {import("stream").Writable} deps.output - Stream to emit tagged NDJSON to.
    * @param {object} deps.ctx - Orchestration context (the Conclude handler writes to it).
    * @param {import("./redaction.js").Redactor} deps.redactor
-   * @param {string} [deps.taskAmend] - Opaque addendum appended to the task before delivery.
+   * @param {string} [deps.taskAmend] - Opaque addendum. The judge appends it to the task before delivery.
    */
   constructor({ runner, output, ctx, redactor, taskAmend }) {
     if (!runner) throw new Error("runner is required");
@@ -70,7 +72,7 @@ export class Judge {
 
   /**
    * Run the judge session.
-   * @param {string} task - The judge prompt (with placeholders already substituted).
+   * @param {string} task - The judge prompt (the caller already substituted the placeholders).
    * @returns {Promise<{success: boolean, verdict: string|null, summary: string|null, turns: number}>}
    */
   async run(task) {
@@ -89,7 +91,7 @@ export class Judge {
       return outcome;
     }
 
-    // The judge ended without calling Conclude. Surface that explicitly so
+    // The judge ended and never called Conclude. Surface that explicitly so
     // callers can distinguish "judge said fail" from "judge never voted."
     const outcome = {
       success: false,
@@ -103,9 +105,9 @@ export class Judge {
 
   /**
    * Tag a single NDJSON line with `source: "judge"` and emit it to the
-   * judge's output stream. Wired into the underlying AgentRunner via the
-   * `onLine` callback so the judge's stream is the single source of truth
-   * for the session's trace.
+   * judge's output stream. The factory wires this into the underlying
+   * AgentRunner through the `onLine` callback. The judge's stream is then the
+   * single source of truth for the session's trace.
    * @param {string} line
    */
   emitLine(line) {
@@ -115,7 +117,7 @@ export class Judge {
   }
 
   /**
-   * Emit a final orchestrator summary line, wrapped in the universal envelope.
+   * Emit a final orchestrator summary line in the universal envelope.
    * @param {{success: boolean, verdict?: string|null, summary?: string|null, turns: number}} result
    */
   emitSummary(result) {
@@ -138,20 +140,20 @@ export class Judge {
 }
 
 /**
- * Factory function — wires the AgentRunner with the judge orchestration server
+ * Factory function. Wires the AgentRunner with the judge orchestration server
  * and the JUDGE_SYSTEM_PROMPT trailer. A `judgeProfile` (when supplied) layers
- * on top of the trailer via `composeSystemPrompt`, matching the
- * supervisor/facilitator pattern.
+ * on top of the trailer through `composeSystemPrompt`. This matches the
+ * supervisor and facilitator pattern.
  *
  * @param {object} deps
  * @param {string} deps.cwd - Judge working directory. Defaults to the directory whose `.claude/agents` holds `judgeProfile`.
- * @param {function} deps.query - SDK query function (injected for testing).
+ * @param {function} deps.query - SDK query function (injected so tests can replace it).
  * @param {import("stream").Writable} deps.output - Trace output stream.
  * @param {import("./redaction.js").Redactor} deps.redactor
  * @param {string} [deps.model]
- * @param {number} [deps.maxTurns] - Default 5 (the judge is expected to act in turn 1; 5 leaves headroom for tool inspection).
- * @param {string[]} [deps.allowedTools] - Default `["Read","Glob","Grep","Bash"]` — read-only inspection.
- * @param {string} [deps.judgeProfile] - Profile name; resolved into the system prompt via `composeSystemPrompt`.
+ * @param {number} [deps.maxTurns] - Default 5. The judge should act in turn 1. The other turns leave headroom for tool inspection.
+ * @param {string[]} [deps.allowedTools] - Default `["Read","Glob","Grep","Bash"]` for read-only inspection.
+ * @param {string} [deps.judgeProfile] - Profile name. `composeSystemPrompt` resolves it into the system prompt.
  * @param {string} [deps.profilesDir] - Defaults to `<cwd>/.claude/agents`.
  * @param {string} [deps.taskAmend]
  * @returns {Judge}

package/src/message-bus.js

@@ -1,17 +1,18 @@
 /**
  * MessageBus — in-memory per-participant message queues.
  *
- * Four message kinds, each pushed onto the addressee's queue:
+ * Four message kinds exist. The bus pushes each one onto the addressee's
+ * queue:
  *
- * - `ask(from, to, text, askId)` — direct question; the toolkit owns the
- *   pending-ask state separately. Fan-out (broadcast Ask) happens at the
- *   handler level by calling `ask()` once per addressee.
+ * - `ask(from, to, text, askId)` — direct question. The toolkit owns the
+ *   pending-ask state separately. The handler level does the fan-out
+ *   (broadcast Ask). It calls `ask()` once per addressee.
  * - `answer(from, to, text, askId)` — direct reply to the original asker.
  *   The orchestrator may inject synthetic answers (`from === "@orchestrator"`)
  *   when an Ask times out.
- * - `announce(from, text)` — broadcast, no reply expected; lands on every
- *   participant's queue except the sender's.
- * - `synthetic(to, text)` — orchestrator-only reminder injection.
+ * - `announce(from, text)` — broadcast. It expects no reply. It lands on
+ *   every participant's queue except the sender's.
+ * - `synthetic(to, text)` — the orchestrator alone injects a reminder.
  *
  * Follows OO+DI: constructor injection, factory function, tests bypass factory.
  */
@@ -40,9 +41,9 @@ export class MessageBus {
   }
 
   /**
-   * Reply to a pending ask. `from === "@orchestrator"` is allowed for
-   * synthetic null answers — the orchestrator is not a real participant
-   * but it routes through the bus.
+   * Reply to a pending ask. The bus allows `from === "@orchestrator"` for
+   * synthetic null answers. The orchestrator is not a real participant. It
+   * still routes through the bus.
    */
   answer(from, to, text, askId) {
     this.#assertParticipant(to);
@@ -71,7 +72,7 @@ export class MessageBus {
     this.#resolveWaiter(to);
   }
 
-  /** Check whether a participant has pending messages without draining them. */
+  /** Check whether a participant has pending messages. It does not drain them. */
   hasPending(participant) {
     this.#assertParticipant(participant);
     return this.queues.get(participant).length > 0;

package/src/orchestration-loop.js

@@ -1,22 +1,22 @@
 /**
- * OrchestrationLoop — N agent sessions coordinated by one lead LLM session.
+ * OrchestrationLoop — one lead LLM session coordinates N agent sessions.
  *
- * Ask is **async**: the tool returns immediately, the actual reply arrives
+ * Ask is **async**. The tool returns immediately. The actual reply arrives
  * on a later turn as `[answer#N] participant: …` on the asker's bus queue.
- * Pending state keys by `askId` (visible in the `[ask#N]` tag), so duplicate
- * Asks to the same addressee coexist without overwriting each other, and
- * the asker can map each reply unambiguously back to its question.
+ * Pending state keys by `askId` (visible in the `[ask#N]` tag). Duplicate
+ * Asks to the same addressee then coexist and never overwrite each other.
+ * The asker can map each reply unambiguously back to its question.
  *
- * Both lead and participants follow the same outer pattern: drain the bus
- * queue, run / resume the LLM with the drained messages, then settle any
+ * Both lead and participants follow the same outer pattern. Drain the bus
+ * queue. Run or resume the LLM with the drained messages. Then settle any
  * unanswered Asks the participant owes. They differ only in how the first
- * turn starts (the lead receives the task; participants wait for traffic).
+ * turn starts. The lead receives the task. Participants wait for traffic.
  *
  * Termination signals:
  * - `ctx.concluded` — explicit Conclude / Adjourn / Recess.
- * - `stopped` — broader: also true on lead error, agent crash, or any
- *   other abort path. Loops watch `stopped`; `ctx.concluded` is only used
- *   for the summary's success/verdict.
+ * - `stopped` — broader. It is also true on lead error, agent crash, or any
+ *   other abort path. Loops watch `stopped`. The code uses `ctx.concluded`
+ *   only for the summary's success and verdict.
  */
 import { SequenceCounter } from "./sequence-counter.js";
 import {
@@ -26,10 +26,10 @@ import {
 } from "./orchestration-toolkit.js";
 import { formatMessages } from "./orchestrator-helpers.js";
 
-/** Default per-session lead-turn budget — accommodates multi-round injected conversations. */
+/** Default per-session lead-turn budget. It fits multi-round injected conversations. */
 const DEFAULT_MAX_LEAD_TURNS = 200;
 
-/** Orchestrate N agent sessions coordinated by a single lead LLM session. */
+/** Coordinate N agent sessions from a single lead LLM session. */
 export class OrchestrationLoop {
   /**
    * @param {object} deps
@@ -42,7 +42,7 @@ export class OrchestrationLoop {
    * @param {object} deps.ctx - Orchestration context (from `createOrchestrationContext()`).
    * @param {object} deps.redactor
    * @param {number} [deps.maxLeadTurns] - Cap on lead resumes per session (default 200).
-   * @param {string} [deps.taskAmend] - Appended to the task before delivery.
+   * @param {string} [deps.taskAmend] - The loop appends it to the task before delivery.
    * @param {import("./inbox-poller.js").InboxPoller} [deps.inboxPoller]
    * @param {AbortController} [deps.abortController]
    */
@@ -90,7 +90,7 @@ export class OrchestrationLoop {
     this.#signalDone = resolveDone;
   }
 
-  /** Internal — resolved when `stopped` flips true so waiters unblock. */
+  /** Internal. Resolves when `stopped` flips true so waiters unblock. */
   #signalDone;
 
   /**
@@ -112,9 +112,9 @@ export class OrchestrationLoop {
       this.#stop();
     };
 
-    // Start agent loops in parallel. Wrapped so a crash flips `stopped`
-    // but the wrapper itself resolves — Promise.allSettled below never
-    // sees an unhandled rejection.
+    // Start agent loops in parallel. The wrapper makes a crash flip `stopped`
+    // and still resolves itself. Promise.allSettled below then never sees an
+    // unhandled rejection.
     const agentPromises = this.agents.map((a) =>
       this.#runAgent(a).catch(abort),
     );
@@ -153,14 +153,14 @@ export class OrchestrationLoop {
   }
 
   /**
-   * Lead loop. The lead's first turn carries the task; every subsequent
-   * turn is a resume triggered by something landing on its inbox.
+   * Lead loop. The lead's first turn carries the task. Every later turn is
+   * a resume, and something that lands on its inbox triggers it.
    *
    * `messages.length === 0` from `#drainOrWait` means the session ended
-   * before any message arrived — that's the natural exit. If
-   * `drainOrWait` returned messages, deliver them even if the session
-   * concluded in the microtask window between wake-up and this check;
-   * the inbox already has them and they deserve to be seen.
+   * before any message arrived. That is the natural exit. If `drainOrWait`
+   * returned messages, deliver them even when the session concluded in the
+   * microtask window between wake-up and this check. The inbox already holds
+   * them, so the lead should see them.
    */
   async #runLead(initialTask) {
     this.leadTurns = 1;
@@ -190,8 +190,8 @@ export class OrchestrationLoop {
   }
 
   /**
-   * Agent loop. The first message off the inbox triggers `run()`; every
-   * subsequent batch triggers `resume()`. No turn budget — the agent
+   * Agent loop. The first message off the inbox triggers `run()`. Every
+   * later batch triggers `resume()`. The loop has no turn budget. The agent
    * runner's own `maxTurns` caps each SDK call.
    */
   async #runAgent({ name, runner }) {
@@ -235,10 +235,10 @@ export class OrchestrationLoop {
 
   /**
    * If `name` left a pending Ask unanswered, inject one synthetic reminder
-   * and resume once more. If still unanswered after the reminder, emit a
-   * `protocol_violation` event per outstanding ask and cancel them — the
-   * asker's queue gets a synthetic `[no answer: …]` so it doesn't deadlock
-   * on a participant that's silently ignoring its inbox.
+   * and resume once more. If it is still unanswered after the reminder, emit
+   * a `protocol_violation` event per outstanding ask and cancel them. The
+   * asker's queue then gets a synthetic `[no answer: …]`, so the asker does
+   * not deadlock on a participant that silently ignores its inbox.
    */
   async #settleOwedAsks(name, runner) {
     if (pendingAsksOwedBy(this.ctx, name).length === 0) return;
@@ -267,9 +267,9 @@ export class OrchestrationLoop {
   }
 
   /**
-   * Emit one NDJSON line tagged with its source (participant name) and a
-   * monotonic seq, wrapped in the universal `{source, seq, event}` envelope.
-   * Called from each runner's `onLine` callback.
+   * Emit one NDJSON line in the universal `{source, seq, event}` envelope.
+   * Tag it with its source (the participant name) and a monotonic seq.
+   * Each runner's `onLine` callback calls this.
    * @param {string} source
    * @param {string} line - Raw NDJSON line from the SDK iterator.
    */
@@ -288,8 +288,7 @@ export class OrchestrationLoop {
 
   /**
    * Emit one orchestrator-source event (`session_start`, `agent_start`,
-   * `protocol_violation`, `lead_turn_limit`) wrapped in the universal
-   * envelope.
+   * `protocol_violation`, `lead_turn_limit`) in the universal envelope.
    * @param {object} event
    */
   emitOrchestratorEvent(event) {
@@ -306,7 +305,7 @@ export class OrchestrationLoop {
 
   /**
    * Emit the terminal summary line. `Discusser` emits its own discuss-
-   * augmented summary after this one; trace consumers keep the last
+   * augmented summary after this one. Trace consumers keep the last
    * summary they see.
    * @param {{success: boolean, verdict?: string|null, turns: number, summary?: string|null}} result
    */

package/src/orchestration-toolkit.js

@@ -1,7 +1,7 @@
 /**
  * OrchestrationToolkit — tool schemas, per-role tool sets, and handler
  * factories for orchestration between leads (facilitator, supervisor,
- * discuss-lead) and their participating agents.
+ * discuss-lead) and the agents that take part.
  *
  * **Tool surface, by role:**
  *
@@ -15,16 +15,16 @@
  *   | Discuss agt |  ✓  |   ✓    |    ✓     |    ✓     |          | RFC                   |
  *   | Judge       |     |        |          |          |    ✓     |                       |
  *
- * **Ask is async.** Ask returns `{askIds:[…]}` immediately and posts the
+ * **Ask is async.** Ask returns `{askIds:[…]}` immediately. It posts the
  * question to the addressee's bus queue. The reply arrives on the asker's
- * next turn as `[answer#N] <participant>: <text>`. Pending state keys by
- * `askId` (visible in `[ask#N]` tags), so duplicate Asks to the same
- * addressee coexist without overwriting.
+ * next turn as `[answer#N] <participant>: <text>`. The toolkit keys pending
+ * state by `askId` (visible in `[ask#N]` tags). Duplicate Asks to the same
+ * addressee then coexist and never overwrite each other.
  *
  * **Answer's `askId` is optional.** With a matching askId, the reply
- * routes to that specific asker. Without, the handler auto-picks if
- * exactly one ask is owed to the caller, otherwise routes the message
- * as an Announce so it still reaches everyone.
+ * routes to that specific asker. Without one, the handler auto-picks when
+ * exactly one ask is owed to the caller. Otherwise the handler routes the
+ * message as an Announce so it still reaches everyone.
  */
 
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
@@ -48,9 +48,9 @@ export function createOrchestrationContext() {
 
 /**
  * Guard for terminal tools (`Conclude`, `Adjourn`, `Recess`). Returns an
- * error result when the caller still has Asks in flight, telling them to
- * end the turn and wait for the auto-resume. Returns `null` when no Asks
- * are pending and the terminal tool is free to run.
+ * error result when the caller still has Asks in flight. That result tells
+ * the caller to end the turn and wait for the auto-resume. Returns `null`
+ * when no Asks are pending and the terminal tool is free to run.
  */
 export function requireNoPendingAsks(ctx) {
   if (ctx.pendingAsks.size === 0) return null;
@@ -62,18 +62,18 @@ export function requireNoPendingAsks(ctx) {
 /**
  * Guard for terminal tools in discuss mode (`Adjourn`, `Recess`). Returns
  * an error result when the lead's inbox has unprocessed messages from the
- * human, telling them to end the turn and wait for the auto-resume.
- * Returns `null` when no inbox messages are pending and the terminal tool
- * is free to run.
+ * human. That result tells the lead to end the turn and wait for the
+ * auto-resume. Returns `null` when no inbox messages are pending and the
+ * terminal tool is free to run.
  */
 export function requireNoUnprocessedInbox(ctx) {
   if (!ctx.messageBus?.hasPending?.("lead")) return null;
   return errorResult(
-    "New messages from the human are waiting. End your turn. You will be resumed to process them.",
+    "New messages from the human are in your inbox. End your turn. You will be resumed to process them.",
   );
 }
 
-/** Mark the session as concluded; cancel any open Asks so askers see the synthetic null on their next turn. */
+/** Mark the session as concluded. Cancel any open Asks so askers see the synthetic null on their next turn. */
 export function createConcludeHandler(ctx) {
   return async ({ verdict, summary }) => {
     const guard = requireNoPendingAsks(ctx);
@@ -84,11 +84,11 @@ export function createConcludeHandler(ctx) {
 }
 
 /**
- * Shared terminal-tool helper. Conclude / Adjourn / Recess all set the
- * same three context fields (`concluded`, `verdict`, `summary`) and
- * cancel any in-flight Asks for the same reason: nobody will ever
- * answer them now. Mode-specific handlers (Adjourn, Recess) layer
- * extra state on top before calling this.
+ * Shared terminal-tool helper. Conclude, Adjourn, and Recess all set the
+ * same three context fields (`concluded`, `verdict`, `summary`). All three
+ * also cancel any in-flight Asks for the same reason. Nobody will ever
+ * answer them now. Mode-specific handlers (Adjourn, Recess) layer extra
+ * state on top before they call this.
  */
 export function concludeSession(ctx, { verdict, summary, reason }) {
   ctx.concluded = true;
@@ -124,21 +124,24 @@ function registerPendingAsk(ctx, { from, addressee, question }) {
 }
 
 /**
- * Create an Ask handler. Registers a pending entry per addressee, posts
- * the ask on the bus, returns `{askIds:[…]}` immediately. The LLM uses
- * those ids to match the `[answer#N]` it sees on a later turn.
+ * Create an Ask handler. The handler registers a pending entry for each
+ * addressee. It posts the ask on the bus. It returns `{askIds:[…]}`
+ * immediately. The LLM uses those ids to match the `[answer#N]` it sees on
+ * a later turn.
  *
  * @param {object} ctx
  * @param {object} opts
  * @param {string} opts.from
  * @param {string|undefined} opts.defaultTo - `undefined` means "broadcast
- *   to everyone else"; a participant name means "target that one when
+ *   to everyone else". A participant name means "target that one when
  *   `to` is omitted."
  */
 export function createAskHandler(ctx, { from, defaultTo }) {
   return async ({ question, to }) => {
     if (ctx.concluded) {
-      return errorResult("Session is concluded; Ask was not delivered.");
+      return errorResult(
+        "The session is concluded. The handler did not deliver your Ask.",
+      );
     }
     const addressees = resolveAddressees(ctx, { from, to, defaultTo });
     if (addressees.length === 0) {
@@ -157,7 +160,8 @@ export function createAskHandler(ctx, { from, defaultTo }) {
  * - askId provided + matches a pending entry whose addressee is the caller →
  *   route the reply to the asker's queue and clear the pending entry.
  * - askId provided but unknown or wrong addressee → `isError`. The caller
- *   tried to specify; we tell them why it didn't match.
+ *   tried to name an askId. The handler tells the caller why it did not
+ *   match.
  * - askId omitted + exactly one ask owed by the caller → auto-pick it.
  * - askId omitted + 0 or many pending → broadcast as Announce so the
  *   message still reaches every other participant.
@@ -180,9 +184,9 @@ export function createAnswerHandler(ctx, { from }) {
     ctx.messageBus.announce(from, message);
     const reason =
       owed.length === 0
-        ? "no pending ask for you"
-        : `${owed.length} pending asks (askId omitted is ambiguous)`;
-    return textResult(`Answer routed as Announce — ${reason}.`);
+        ? "You have no pending ask."
+        : `You have ${owed.length} pending asks. An omitted askId is ambiguous.`;
+    return textResult(`Answer routed as Announce. ${reason}`);
   };
 }
 
@@ -191,7 +195,7 @@ function routeAnswerByAskId(ctx, { from, askId, message }) {
   if (!entry) return errorResult(`No pending ask with askId=${askId}.`);
   if (entry.addresseeName !== from) {
     return errorResult(
-      `Ask #${askId} is addressed to ${entry.addresseeName}, not ${from}.`,
+      `Ask #${askId} is addressed to ${entry.addresseeName}. You are ${from}.`,
     );
   }
   ctx.pendingAsks.delete(askId);
@@ -208,9 +212,9 @@ export function createAnnounceHandler(ctx, { from }) {
 }
 
 /**
- * Cancel pending Asks and route a synthetic `[no answer: <reason>]` to
- * each asker's queue so callers never deadlock on a participant ignoring
- * its inbox.
+ * Cancel pending Asks. Route a synthetic `[no answer: <reason>]` to each
+ * asker's queue, so callers never deadlock when a participant ignores its
+ * inbox.
  *
  * @param {object} ctx
  * @param {string} reason - Surfaced inside `[no answer: <reason>]`.
@@ -234,8 +238,8 @@ export function pendingAsksOwedBy(ctx, addressee) {
 }
 
 /**
- * Inject a synthetic reminder onto the addressee's bus queue and mark
- * each owed ask as reminded. Returns true when a reminder fired.
+ * Inject a synthetic reminder onto the addressee's bus queue. Mark each
+ * owed ask as reminded. Returns true when a reminder fired.
  */
 export function remindOwedAsks(ctx, addressee) {
   const owed = pendingAsksOwedBy(ctx, addressee).filter((e) => !e.reminded);
@@ -252,13 +256,13 @@ export function remindOwedAsks(ctx, addressee) {
 // --- Tool descriptions (shared across roles) ---
 
 const ASK_DESC_BROADCAST =
-  "Send a question to one named participant, or omit 'to' to broadcast to every other participant. Returns {askIds:[…]} immediately; the reply arrives on a later turn as `[answer#N] <from>: <text>` in your inbox.";
+  "Send a question to one named participant. Omit 'to' to broadcast to every other participant. Returns {askIds:[…]} immediately. The reply arrives on a later turn as `[answer#N] <from>: <text>` in your inbox.";
 
 const ASK_DESC_TARGETED = (target) =>
-  `Send a question to ${target}. Returns {askIds:[N]} immediately; the reply arrives on a later turn as \`[answer#N] ${target}: <text>\` in your inbox.`;
+  `Send a question to ${target}. Returns {askIds:[N]} immediately. The reply arrives on a later turn as \`[answer#N] ${target}: <text>\` in your inbox.`;
 
 const ANSWER_DESC =
-  "Reply to an ask addressed to you. Quote askId from the [ask#N] tag on the question; omit it and the handler auto-picks the only pending ask, or routes your message as an Announce when 0 or many are pending.";
+  "Reply to an ask addressed to you. Quote askId from the [ask#N] tag on the question. Omit askId and the handler auto-picks the only pending ask. When 0 or many asks are pending, the handler routes your message as an Announce.";
 
 const ANNOUNCE_DESC = "Broadcast a message with no reply expected.";
 
@@ -275,7 +279,7 @@ const ADJOURN_DESC =
   "End the discussion. Provide a verdict ('adjourned' or 'failed') and a summary. Cancels any unanswered Asks.";
 
 const RECESS_DESC =
-  "End the run and schedule an out-of-session re-dispatch. Cancels any unanswered Asks. Use only when waiting on an external reply or duration. Do not use to wait on in-flight Asks.";
+  "End the run. Schedule an out-of-session re-dispatch. Cancels any unanswered Asks. Use only when you wait on an external reply or duration. Do not use to wait on in-flight Asks.";
 
 // --- Tool builders ---
 
@@ -283,7 +287,7 @@ const RECESS_DESC =
 function textResult(text) {
   return { content: [{ type: "text", text }] };
 }
-/** Build an MCP tool error result wrapping a single text message. */
+/** Build an MCP tool error result that wraps a single text message. */
 function errorResult(text) {
   return { content: [{ type: "text", text }], isError: true };
 }
@@ -298,10 +302,10 @@ function jsonResult(obj) {
  * @param {object} ctx
  * @param {object} opts
  * @param {string} opts.from - Caller's canonical name.
- * @param {string|undefined} opts.defaultTo - Default Ask target; `undefined`
+ * @param {string|undefined} opts.defaultTo - Default Ask target. `undefined`
  *   means "broadcast across everyone else when `to` is omitted."
  * @param {boolean} opts.broadcast - Whether Ask accepts a `to` field at all.
- *   Leads with multiple participants set this true; supervise's
+ *   Leads with multiple participants set this true. Supervise's
  *   single-participant roles set it false.
  */
 function baseTools(ctx, { from, defaultTo, broadcast }) {
@@ -338,19 +342,20 @@ function concludeTool(ctx) {
 }
 
 const ADVISOR_DESC =
-  "Consult a stronger model on one focused question. Your full session context (system prompt, prompts, transcript so far) is forwarded automatically — you cannot restrict it. The advice returns in the tool result. The consult budget is shared session-wide across all participants.";
+  "Consult a stronger model on one focused question. The tool forwards your full session context (system prompt, prompts, transcript so far) automatically. You cannot restrict it. The advice returns in the tool result. All participants share one session-wide consult budget.";
 
 /**
- * Build the `Advisor` consult tool for one caller. Mode-agnostic: loop
- * modes pass it into the agent tool-server factories via `extraTools`;
- * run mode gives it a dedicated server. No orchestration-context
- * dependency — the budget object and emit callback are injected.
+ * Build the `Advisor` consult tool for one caller. The tool is
+ * mode-agnostic. Loop modes pass it into the agent tool-server factories
+ * through `extraTools`. Run mode gives it a dedicated server. The tool has
+ * no orchestration-context dependency. The budget object and the emit
+ * callback arrive as injected dependencies.
  *
  * @param {object} deps
  * @param {string} deps.from - Caller's canonical name (event attribution).
  * @param {(question: string) => Promise<{advice?: string, unavailable?: boolean, reason?: string, durationMs: number}>} deps.consult
  * @param {(event: object) => void} deps.emit - Orchestrator-event emitter for the `advisor_consult` event.
- * @param {{maxUses: number, used: number}} deps.budget - Session-wide budget shared by every caller's handler.
+ * @param {{maxUses: number, used: number}} deps.budget - Session-wide budget that every caller's handler shares.
  * @param {string} deps.model - Advisor model id, carried on the consult event.
  */
 export function advisorTool({ from, consult, emit, budget, model }) {
@@ -378,7 +383,7 @@ export function advisorTool({ from, consult, emit, budget, model }) {
         remaining,
       });
       if (r.unavailable) {
-        // Not isError: fail-open, the caller continues normally.
+        // Not isError. This fails open, so the caller continues normally.
         return textResult(
           `The advisor is unavailable (${r.reason}) — proceed with your best judgment.`,
         );
@@ -477,7 +482,7 @@ export function createRequestForCommentHandler(ctx) {
 function requestForCommentTool(ctx) {
   return tool(
     "RequestForComment",
-    "Open a new Discussion thread for long-horizon coordination on an open question. The bridge creates the thread; replies arrive asynchronously on future runs.",
+    "Open a new Discussion thread for long-horizon coordination on an open question. The bridge creates the thread. Replies arrive asynchronously on future runs.",
     {
       channel: z.string(),
       body: z.string(),
@@ -487,8 +492,8 @@ function requestForCommentTool(ctx) {
   );
 }
 
-// Re-export the building blocks discuss-tools.js needs to assemble its
-// own lead tool surface (it has two extra terminal tools).
+// Re-export the parts discuss-tools.js needs to assemble its own lead tool
+// surface (it has two extra terminal tools).
 export {
   ADJOURN_DESC,
   baseTools,

package/src/orchestrator-helpers.js

@@ -1,8 +1,8 @@
 /**
  * Render a drained batch of bus messages as tagged text lines so the
  * LLM can read its inbox at a glance. Asks and answers include the
- * `askId` in the tag (`[ask#42] facilitator: …`, `[answer#42] agent: …`)
- * so the addressee can quote it back via Answer's `askId` field.
+ * `askId` in the tag (`[ask#42] facilitator: …`, `[answer#42] agent: …`).
+ * The addressee can then quote it back in Answer's `askId` field.
  *
  * @param {Array<{from: string, text: string, kind?: string, askId?: number}>} messages
  * @returns {string}