@forwardimpact/libeval 0.1.44 → 0.1.46

package/src/discusser.js

@@ -27,14 +27,15 @@ import { OrchestrationLoop } from "./orchestration-loop.js";
 /** System prompt appended for the lead (Chair) runner in discuss mode. */
 export const DISCUSS_SYSTEM_PROMPT =
   "You lead an asynchronous discussion across multiple participants and a human channel. " +
-  "Ask delivers a question to one named participant — or broadcasts when no addressee is named — and blocks until that participant answers. " +
+  "Ask sends a question and returns immediately with {askIds:[N,…]}. The reply arrives on a later turn as `[answer#N] <participant>: <text>` in your inbox — between turns you can plan, reflect, or send more Asks while participants work in parallel. End your turn with text after you've asked everything you intend to; the orchestrator wakes you when the next message lands. " +
+  "Answer replies to an ask a participant addressed to you (you'll see it tagged `[ask#N] <participant>: …` in your inbox). Quote askId from the [ask#N] tag; omit it and the handler auto-picks the only pending ask or routes your message as an Announce. " +
   "Announce delivers a message with no reply obligation. " +
-  "Redirect interrupts an in-progress participant with replacement instructions. " +
   "RollCall returns the participant roster. " +
   "RequestForComment posts a message to the human thread via the bridge. Every reply you want the human to see MUST go through RequestForComment — the bridge delivers only queued replies, not your text output. " +
-  "Recess suspends the run with a resumption trigger (responses / elapsed / either). " +
+  "Recess suspends the run with a resumption trigger (responses / elapsed / either); any open Asks get a synthetic '[no answer: session concluded]' on the asker's queue so nothing dangles. " +
   "Adjourn ends the discussion with a verdict ('adjourned' / 'failed') and a summary. " +
-  "You MUST call RequestForComment with your response before calling Adjourn. You MUST end every run by calling Adjourn or Recess — never end a turn with only text.";
+  "Multiple Ask / Announce calls in one assistant turn dispatch in parallel — issue them as parallel tool_use blocks rather than sending the same question both broadcast and individually. " +
+  "You MUST call RequestForComment with your response before calling Adjourn. You MUST end every run by calling Adjourn or Recess — never end a turn with only text *after* every Ask round has resolved.";
 
 /**
  * Augment a base orchestration context with discuss-mode fields.
@@ -44,34 +45,13 @@ export const DISCUSS_SYSTEM_PROMPT =
  */
 export function augmentContextForDiscuss(ctx, discussionId) {
   ctx.discussionId = discussionId;
-  ctx.recessed = false;
   ctx.recessTrigger = null;
-  ctx.recessReason = null;
   ctx.replies = [];
   ctx.rfcCounter = 0;
   ctx.outcome = null;
   return ctx;
 }
 
-/**
- * Round-trip-safe representation of `ctx.pendingAsks` (a `Map`).
- * @param {Map<string, object>} map
- * @returns {object}
- */
-export function pendingAsksToPlain(map) {
-  return Object.fromEntries(map);
-}
-
-/**
- * Restore a plain object back into a `Map<string, …>`.
- * @param {object|null|undefined} plain
- * @returns {Map<string, object>}
- */
-export function pendingAsksFromPlain(plain) {
-  if (!plain) return new Map();
-  return new Map(Object.entries(plain));
-}
-
 const devNull = new Writable({
   write(_chunk, _enc, cb) {
     cb();
@@ -89,9 +69,9 @@ export class Discusser {
    * @param {OrchestrationLoop} deps.loop
    * @param {object} deps.ctx
    * @param {import("stream").Writable} deps.output
+   * @param {object} deps.redactor
    * @param {string|null} [deps.discussionId]
    * @param {SequenceCounter} [deps.counter]
-   * @param {object} [deps.redactor]
    */
   constructor({ loop, ctx, output, discussionId, counter, redactor }) {
     if (!loop) throw new Error("loop is required");
@@ -123,7 +103,7 @@ export class Discusser {
     await this.loop.run(task);
 
     const verdict = this.ctx.verdict ?? "failed";
-    const success = verdict === "adjourned" || verdict === "concluded";
+    const success = verdict === "adjourned";
     this.#emitDiscussSummary({
       success,
       verdict,
@@ -163,7 +143,6 @@ export class Discusser {
       replies: this.ctx.replies,
       ...(this.ctx.recessTrigger && { trigger: this.ctx.recessTrigger }),
       ...(this.discussionId && { discussion_id: this.discussionId }),
-      pending_asks: pendingAsksToPlain(this.ctx.pendingAsks),
     };
     this.output.write(
       JSON.stringify(
@@ -182,6 +161,12 @@ export class Discusser {
  * the `OrchestrationLoop` (with `leadName: "lead"` and discuss-mode
  * protocol tagging) and the wrapping `Discusser`.
  *
+ * Resume semantics: Recess ends the run, cancels any open Asks via
+ * `cancelPendingAsks`, and emits a synthetic null answer per cancelled
+ * ask so nothing dangles in the trace. The bridge later re-dispatches
+ * the workflow against a fresh context; the human reads the trail of
+ * events to decide what to re-ask.
+ *
  * @param {object} deps
  * @param {string} [deps.leadProfile]
  * @param {string} [deps.leadModel]
@@ -225,12 +210,11 @@ export function createDiscusser({
     discussionId ?? null,
   );
 
-  // Hydrate resume context — pendingAsks, participants, history, replies.
-  // resumeContext is the entire suspend/resume contract; every mutation a
-  // Recess needs to preserve must travel through it.
+  // Hydrate resume context — participants, replies, counters. `pendingAsks`
+  // is intentionally not restored: Recess cancelled every in-flight Ask
+  // with a synthetic null answer, so there's nothing meaningful to carry
+  // forward.
   if (resumeContext) {
-    if (resumeContext.pendingAsks)
-      ctx.pendingAsks = pendingAsksFromPlain(resumeContext.pendingAsks);
     if (Array.isArray(resumeContext.participants))
       ctx.participants = resumeContext.participants;
     if (Array.isArray(resumeContext.replies))
@@ -297,7 +281,7 @@ export function createDiscusser({
     query,
     output: devNull,
     model: leadModel ?? "claude-opus-4-7[1m]",
-    maxTurns: maxTurns ?? 40,
+    maxTurns: maxTurns ?? 80,
     allowedTools: ["Bash", "Read", "Glob", "Grep", "Write", "Edit"],
     disallowedTools: defaultDisallowed,
     onLine: (line) => discusser.loop.emitLine("lead", line),
@@ -314,7 +298,6 @@ export function createDiscusser({
     output,
     leadName: "lead",
     mode: "discussion",
-    maxTurns: maxTurns ?? 40,
     ctx,
     taskAmend,
     redactor,

package/src/facilitator.js

@@ -1,7 +1,7 @@
 /**
  * Facilitator — facilitate-mode wrapper around `OrchestrationLoop`. The
- * lead participant is named "facilitator" and uses the `Conclude` tool to
- * end the session. The within-run turn loop itself lives in
+ * lead participant is named "facilitator" and ends the session via the
+ * `Conclude` tool. The within-run turn loop lives in
  * `orchestration-loop.js`; this file owns only the facilitate-mode
  * specifics (lead role name, system prompts, tool wiring, factory).
  */
@@ -16,34 +16,33 @@ import {
   createFacilitatorToolServer,
   createFacilitatedAgentToolServer,
 } from "./orchestration-toolkit.js";
-import { createAsyncQueue } from "./orchestrator-helpers.js";
 import { OrchestrationLoop } from "./orchestration-loop.js";
 
 /** System prompt appended for the facilitator runner. */
 export const FACILITATOR_SYSTEM_PROMPT =
   "You coordinate multiple participants via these tools: " +
-  "Ask delivers a question to one named participant — or broadcasts when no addressee is named — and blocks until that participant answers. " +
+  "Ask sends a question and returns immediately with {askIds:[N,…]}. The reply arrives on a later turn as `[answer#N] <participant>: <text>` in your inbox — between turns you can plan, reflect, or send more Asks while participants work in parallel. End your turn with text after you've asked everything you intend to; the orchestrator wakes you again as soon as a reply (or any message) lands. " +
+  "Answer replies to an ask a participant addressed to you (you'll see it tagged `[ask#N] <participant>: …` in your inbox). Quote askId from the [ask#N] tag; omit it and the handler auto-picks the only pending ask or routes your message as an Announce. " +
   "Announce delivers a message with no reply obligation. " +
-  "Redirect interrupts an in-progress participant with replacement instructions. " +
   "RollCall returns the participant roster. " +
   "Conclude ends the session with a verdict ('success' or 'failure') and a summary. " +
-  "Ask and Announce calls issued in the same turn dispatch in parallel. " +
-  "You MUST call Conclude to end every session — never end a turn with only text. " +
+  "Multiple Ask / Announce calls in one assistant turn dispatch in parallel — issue them as parallel tool_use blocks rather than sending the same question both broadcast and individually. " +
+  "You MUST end every session with Conclude — never end a turn with only text *after* every Ask round has resolved. " +
   "If you can answer the task yourself, still call Conclude with verdict='success' and the answer as the summary.";
 
 /** System prompt appended for facilitated agent runners. */
 export const FACILITATED_AGENT_SYSTEM_PROMPT =
   "You participate in a coordinated session. " +
-  "Answer replies to an ask addressed to you. " +
-  "Ask sends a question to another participant. " +
-  "Announce broadcasts a message. " +
+  "Each question you receive carries an [ask#N] header — quote that N back as the askId field on Answer so the reply pairs with the right question. " +
+  "Answer replies to an ask addressed to you. askId is optional: omit it and the handler auto-picks if exactly one ask is owed to you, otherwise it routes your message as an Announce. " +
+  "Ask sends a question to another participant and returns immediately with {askIds:[N]}; the reply arrives on a later turn as `[answer#N] <participant>: <text>` in your inbox. " +
+  "Announce broadcasts a message to every other participant — use this for unsolicited remarks or to reply to an Announce. " +
   "RollCall lists participants.";
 
 /**
- * Facilitate-mode wrapper around `OrchestrationLoop`. The lead participant
- * is `"facilitator"` and the protocol mode is `"facilitated"`. Preserves
- * the public surface (`facilitatorRunner`, `facilitatorTurns`) that
- * existing callers rely on.
+ * Facilitate-mode wrapper around `OrchestrationLoop`. The lead is named
+ * `"facilitator"`. `facilitatorRunner` getter is a readability shim for
+ * tests that read the runner directly.
  */
 export class Facilitator extends OrchestrationLoop {
   /**
@@ -52,11 +51,9 @@ export class Facilitator extends OrchestrationLoop {
    * @param {Array<{name: string, role: string, runner: import("./agent-runner.js").AgentRunner}>} deps.agents
    * @param {import("./message-bus.js").MessageBus} deps.messageBus
    * @param {import("stream").Writable} deps.output
-   * @param {number} [deps.maxTurns]
-   * @param {object} [deps.ctx]
-   * @param {object} [deps.eventQueue]
-   * @param {string} [deps.taskAmend]
+   * @param {object} deps.ctx
    * @param {object} deps.redactor
+   * @param {string} [deps.taskAmend]
    */
   constructor(deps) {
     super({
@@ -67,20 +64,10 @@ export class Facilitator extends OrchestrationLoop {
     });
   }
 
-  /** @returns {import("./agent-runner.js").AgentRunner} */
+  /** Readability shim — exposes the lead runner under its mode-specific name. */
   get facilitatorRunner() {
     return this.leadRunner;
   }
-
-  /** @returns {number} */
-  get facilitatorTurns() {
-    return this.leadTurns;
-  }
-
-  /** @param {number} v */
-  set facilitatorTurns(v) {
-    this.leadTurns = v;
-  }
 }
 
 const devNull = new Writable({
@@ -96,15 +83,15 @@ const devNull = new Writable({
  * @param {Array<{name: string, role: string, cwd?: string, maxTurns?: number, allowedTools?: string[], agentProfile?: string, systemPromptAmend?: string}>} deps.agentConfigs
  * @param {function} deps.query
  * @param {import("stream").Writable} deps.output
- * @param {string} [deps.model] - Default model for all participants.
- * @param {string} [deps.agentModel] - Agent model override (falls back to `model`).
- * @param {string} [deps.facilitatorModel] - Facilitator model override (falls back to `model`).
- * @param {number} [deps.maxTurns] - Facilitator's own per-invocation turn budget (default 20). Each participating agent's budget is taken from `config.maxTurns` on its entry in `agentConfigs` (default 50 when unset). The CLI command (`commands/facilitate.js`) threads `--max-turns` into both this parameter and every agent config so a single CLI value bounds all participants uniformly.
- * @param {string[]} [deps.facilitatorAllowedTools] - Tools the facilitator may use; defaults to a read/write file-edit set.
- * @param {string[]} [deps.facilitatorDisallowedTools] - Additional tools to block on the facilitator; merged with the sub-agent spawn defaults (Agent/Task/TaskOutput/TaskStop).
- * @param {string} [deps.facilitatorProfile] - Facilitator profile name; resolved into the main-thread system prompt via `composeProfilePrompt`.
- * @param {string} [deps.profilesDir] - Directory containing `<name>.md` profile files. Defaults to `<facilitatorCwd>/.claude/agents`. Resolved once from the facilitator's cwd so profiles travel with the project, not with per-agent sandboxes.
- * @param {string} [deps.taskAmend] - Opaque addendum appended to the task before delivery.
+ * @param {string} [deps.model]
+ * @param {string} [deps.agentModel]
+ * @param {string} [deps.facilitatorModel]
+ * @param {number} [deps.maxTurns] - Per-SDK-call turn budget for the facilitator runner (default 80). Each agent's budget is taken from `config.maxTurns` (default 50). The lead is resumed once per inbox-drain round, so this caps the size of one such round, not the whole session — `OrchestrationLoop.maxLeadTurns` bounds session length.
+ * @param {string[]} [deps.facilitatorAllowedTools]
+ * @param {string[]} [deps.facilitatorDisallowedTools]
+ * @param {string} [deps.facilitatorProfile]
+ * @param {string} [deps.profilesDir]
+ * @param {string} [deps.taskAmend]
  * @returns {Facilitator}
  */
 export function createFacilitator({
@@ -147,8 +134,6 @@ export function createFacilitator({
 
   let facilitator;
 
-  const eventQueue = createAsyncQueue();
-
   const facilitatorServer = createFacilitatorToolServer(ctx);
 
   const agents = agentConfigs.map((config) => {
@@ -190,7 +175,7 @@ export function createFacilitator({
     query,
     output: devNull,
     model: facilitatorModel ?? model,
-    maxTurns: maxTurns ?? 20,
+    maxTurns: maxTurns ?? 80,
     allowedTools: facilitatorAllowedTools ?? [
       "Bash",
       "Read",
@@ -215,9 +200,7 @@ export function createFacilitator({
     agents,
     messageBus,
     output,
-    maxTurns,
     ctx,
-    eventQueue,
     taskAmend,
     redactor,
   });

package/src/index.js

@@ -38,8 +38,6 @@ export {
   createDiscusser,
   DISCUSS_SYSTEM_PROMPT,
   augmentContextForDiscuss,
-  pendingAsksToPlain,
-  pendingAsksFromPlain,
 } from "./discusser.js";
 export {
   createDiscussLeadToolServer,

package/src/judge.js

@@ -2,7 +2,7 @@
  * 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 relay loop. The judge reads the task, optionally
+ * 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.
  *

package/src/message-bus.js

@@ -1,22 +1,26 @@
 /**
- * MessageBus — in-memory per-participant message queues for facilitated and
- * supervised modes. The message vocabulary mirrors the orchestration toolkit:
+ * MessageBus — in-memory per-participant message queues.
  *
- * - ask(from, to, text, askId)       — direct question; registers nothing
- *   itself (the handler's caller owns pending-ask state). `to === "@broadcast"`
- *   sends an identical entry to every participant except the sender.
- * - answer(from, to, text, askId)    — direct reply to the asker.
- * - announce(from, text)             — broadcast, no reply expected.
- * - synthetic(to, text)              — orchestrator-only reminder injection.
+ * Four message kinds, each pushed 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.
+ * - `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.
  *
  * Follows OO+DI: constructor injection, factory function, tests bypass factory.
  */
 
-/** In-memory per-participant message queues for facilitated and supervised orchestration modes. */
+/** In-memory per-participant message queues. */
 export class MessageBus {
   /**
    * @param {object} deps
-   * @param {string[]} deps.participants - Participant names
+   * @param {string[]} deps.participants - Canonical participant names.
    */
   constructor({ participants }) {
     this.queues = new Map();
@@ -27,55 +31,30 @@ export class MessageBus {
     }
   }
 
-  /**
-   * Send a question to a participant (direct), or broadcast when
-   * `to === "@broadcast"`.
-   * @param {string} from
-   * @param {string} to - Recipient name or "@broadcast"
-   * @param {string} text
-   * @param {number} askId
-   */
+  /** Send a question to one participant. */
   ask(from, to, text, askId) {
     this.#assertParticipant(from);
-    if (to === "@broadcast") {
-      for (const [name, queue] of this.queues) {
-        if (name === from) continue;
-        queue.push({ from, text, kind: "ask", askId, direct: false });
-        this.#resolveWaiter(name);
-      }
-      return;
-    }
     this.#assertParticipant(to);
-    this.queues.get(to).push({ from, text, kind: "ask", askId, direct: true });
+    this.queues.get(to).push({ from, text, kind: "ask", askId });
     this.#resolveWaiter(to);
   }
 
   /**
-   * Reply to a pending ask.
-   * @param {string} from - Answerer (or "@orchestrator" for a synthetic answer)
-   * @param {string} to - Original asker
-   * @param {string} text
-   * @param {number} askId
+   * 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.
    */
   answer(from, to, text, askId) {
     this.#assertParticipant(to);
-    // Synthetic answers from the orchestrator bypass the participant check
-    // on `from` — the orchestrator is not a message-bus participant.
     if (from !== "@orchestrator") this.#assertParticipant(from);
-    this.queues
-      .get(to)
-      .push({ from, text, kind: "answer", askId, direct: true });
+    this.queues.get(to).push({ from, text, kind: "answer", askId });
     this.#resolveWaiter(to);
   }
 
-  /**
-   * Broadcast a message to every participant except the sender.
-   * @param {string} from
-   * @param {string} text
-   */
+  /** Broadcast a message to every participant except the sender. */
   announce(from, text) {
     this.#assertParticipant(from);
-    const msg = { from, text, kind: "announce", direct: false };
+    const msg = { from, text, kind: "announce" };
     for (const [name, queue] of this.queues) {
       if (name === from) continue;
       queue.push(msg);
@@ -83,53 +62,24 @@ export class MessageBus {
     }
   }
 
-  /**
-   * Send a direct message with no reply expected. Used by the Redirect
-   * runtime plumbing (facilitator / supervisor) to deliver replacement
-   * instructions to a single participant without engaging the ask/answer
-   * contract.
-   * @param {string} from
-   * @param {string} to
-   * @param {string} text
-   */
-  direct(from, to, text) {
-    this.#assertParticipant(from);
-    this.#assertParticipant(to);
-    this.queues.get(to).push({ from, text, kind: "direct", direct: true });
-    this.#resolveWaiter(to);
-  }
-
-  /**
-   * Inject an orchestrator-originated reminder onto a single participant's
-   * queue. Used by the turn-complete guard.
-   * @param {string} to
-   * @param {string} text
-   */
+  /** Inject an orchestrator-originated reminder onto one participant's queue. */
   synthetic(to, text) {
     this.#assertParticipant(to);
     this.queues
       .get(to)
-      .push({ from: "@orchestrator", text, kind: "synthetic", direct: true });
+      .push({ from: "@orchestrator", text, kind: "synthetic" });
     this.#resolveWaiter(to);
   }
 
-  /**
-   * Return and clear pending messages for a participant.
-   * @param {string} participant - Participant name
-   * @returns {{from: string, text: string, kind: string, direct: boolean, askId?: number}[]}
-   */
+  /** Return and clear pending messages for a participant. */
   drain(participant) {
     this.#assertParticipant(participant);
-    const queue = this.queues.get(participant);
-    const messages = queue.splice(0);
-    return messages;
+    return this.queues.get(participant).splice(0);
   }
 
   /**
    * Return a Promise that resolves when at least one message is pending.
    * Resolves immediately if messages are already queued.
-   * @param {string} participant - Participant name
-   * @returns {Promise<void>}
    */
   waitForMessages(participant) {
     this.#assertParticipant(participant);
@@ -156,11 +106,7 @@ export class MessageBus {
   }
 }
 
-/**
- * Factory function.
- * @param {object} deps - Same as MessageBus constructor
- * @returns {MessageBus}
- */
+/** Factory function. */
 export function createMessageBus(deps) {
   return new MessageBus(deps);
 }