@forwardimpact/libharness 0.1.20 → 1.0.0

package/src/cost.js

@@ -0,0 +1,79 @@
+/**
+ * Cost aggregation over Claude Code NDJSON traces — the single source of
+ * truth for "how much did this run cost, across every participant?".
+ *
+ * The SDK reports the cumulative session cost on each `result` event as
+ * `total_cost_usd`. Supervised, facilitated, and discuss sessions interleave
+ * one runner's events with another's in a single combined trace, wrapping
+ * each in a `{source, seq, event}` envelope; a plain `run` trace carries bare
+ * events with no envelope. A judge runs as its own session in a separate
+ * trace. In every case the rule is the same: sum the `total_cost_usd` of each
+ * `result` event, and keep a per-source breakdown so callers can attribute
+ * spend to the agent, supervisor, judge, or any named participant.
+ *
+ * This mirrors `TraceCollector.handleResult`, which accumulates the same
+ * figure for its summary footer — kept as a standalone pure helper so the
+ * benchmark runner, the callback command, and `fit-trace cost` share one
+ * implementation rather than each re-deriving it (and drifting).
+ */
+
+/** Bucket key for bare (un-enveloped) `run`-mode events: a lone agent session. */
+export const UNSOURCED = "agent";
+
+/**
+ * Sum `total_cost_usd` across every `result` event in an NDJSON trace.
+ *
+ * @param {Iterable<string>} lines - NDJSON lines (e.g. `content.split("\n")`).
+ *   Blank and malformed lines are skipped.
+ * @returns {{totalCostUsd: number, bySource: Record<string, number>}}
+ *   `totalCostUsd` is the sum across all participants; `bySource` maps each
+ *   envelope `source` (or {@link UNSOURCED} for bare events) to its subtotal.
+ */
+export function sumTraceCost(lines) {
+  let totalCostUsd = 0;
+  /** @type {Record<string, number>} */
+  const bySource = {};
+
+  for (const line of lines) {
+    const parsed = parseCostLine(line);
+    if (!parsed) continue;
+    const { source, cost } = parsed;
+    totalCostUsd += cost;
+    bySource[source] = (bySource[source] ?? 0) + cost;
+  }
+
+  return { totalCostUsd, bySource };
+}
+
+/**
+ * Parse a single NDJSON line and return its `result`-event cost contribution,
+ * or null when the line is blank, malformed, not a result event, or carries
+ * no numeric `total_cost_usd`.
+ *
+ * @param {string} line
+ * @returns {{source: string, cost: number} | null}
+ */
+function parseCostLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+
+  let event;
+  try {
+    event = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+
+  // Unwrap the combined-trace envelope {source, seq, event}; bare events
+  // (plain `run` traces) have a `type` and no `source`.
+  let source = UNSOURCED;
+  if (event.event && !event.type && typeof event.source === "string") {
+    source = event.source;
+    event = event.event;
+  }
+
+  if (event.type !== "result") return null;
+  if (typeof event.total_cost_usd !== "number") return null;
+
+  return { source, cost: event.total_cost_usd };
+}

package/src/discuss-tools.js

@@ -0,0 +1,173 @@
+/**
+ * DiscussTools — discuss-mode tool servers. The lead's surface extends the
+ * base set with two discuss-only terminal tools:
+ *
+ * - `Recess` suspends the session with a resumption trigger.
+ * - `Adjourn` ends the discussion with a verdict.
+ *
+ * `Conclude` is absent — discuss mode ends via Adjourn or Recess.
+ *
+ * `RequestForComment` is an agent-level coordination tool — available on
+ * discuss agents and facilitated agents (not leads). It opens a new
+ * Discussion thread for long-horizon coordination on open questions.
+ *
+ * In discuss mode, each agent Answer routed to the lead is captured as a
+ * thread reply delivered via the bridge callback — no explicit reply tool
+ * is needed on the lead surface.
+ */
+
+import { tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+
+import {
+  ADJOURN_DESC,
+  baseTools,
+  concludeSession,
+  orchestrationServer,
+  RECESS_DESC,
+  requestForCommentTool,
+  requireNoPendingAsks,
+  requireNoUnprocessedInbox,
+} from "./orchestration-toolkit.js";
+
+/** System prompt for discuss-mode agent participants. L0 mechanics only per COALIGNED. */
+export const DISCUSS_AGENT_SYSTEM_PROMPT =
+  "You are a participant in a discussion.\n" +
+  "Each question arrives as `[ask#N] <name>: <text>` in your inbox.\n" +
+  "Quote N as askId on your `Answer` to route the reply correctly.\n" +
+  "Your `Answer` is posted to the discussion thread as a separate reply.\n" +
+  "If the task already contains a completed response with no new human input after it, `Answer` that no further action is needed.\n" +
+  "Do not redo completed work.";
+
+const RESUME_TRIGGER_SCHEMA = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("missing_input"),
+      replies: z.number().int().positive(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("escalation_needed"),
+      signal: z.string().min(1),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("elapsed"),
+      elapsed: z.string().min(1),
+    })
+    .strict(),
+]);
+
+/** Discuss-mode lead tool server. */
+export function createDiscussLeadToolServer(ctx) {
+  return orchestrationServer([
+    ...baseTools(ctx, { from: "lead", defaultTo: undefined, broadcast: true }),
+    tool(
+      "Acknowledge",
+      "Post a brief message directly to the discussion thread. Use when responding to a human follow-up or providing a status update while participants are working.",
+      {
+        message: z.string().describe("Message to post on the thread"),
+      },
+      async ({ message }) => {
+        const seq =
+          ctx.emitter?.emit({ kind: "ack", body: message, agent: "lead" }) ??
+          -1;
+        ctx.replies.push({
+          body: message,
+          agent: "lead",
+          kind: "ack",
+          seq,
+          ...(ctx.discussionId && { thread_id: ctx.discussionId }),
+        });
+        return { content: [{ type: "text", text: "Posted." }] };
+      },
+    ),
+    tool(
+      "Recess",
+      RECESS_DESC,
+      { reason: z.string(), trigger: RESUME_TRIGGER_SCHEMA },
+      createRecessHandler(ctx),
+    ),
+    tool(
+      "Adjourn",
+      ADJOURN_DESC,
+      {
+        verdict: z.enum(["adjourned", "failed"]),
+        summary: z.string(),
+        outcome: z.string().optional(),
+      },
+      createAdjournHandler(ctx),
+    ),
+  ]);
+}
+
+const ACKNOWLEDGE_DESC =
+  "Acknowledge an Ask before starting work. Posts a visible comment on the thread. Does not discharge the Ask — you still owe an Answer.";
+
+/** Discuss-mode agent tool server. */
+export function createDiscussAgentToolServer(ctx, { from }) {
+  return orchestrationServer([
+    ...baseTools(ctx, { from, defaultTo: "lead", broadcast: true }),
+    requestForCommentTool(ctx),
+    tool(
+      "Acknowledge",
+      ACKNOWLEDGE_DESC,
+      {
+        message: z
+          .string()
+          .describe("Brief acknowledgement to post on the thread"),
+        askId: z.number().optional().describe("The ask being acknowledged"),
+      },
+      async ({ message }) => {
+        const seq =
+          ctx.emitter?.emit({ kind: "ack", body: message, agent: from }) ?? -1;
+        ctx.replies.push({
+          body: message,
+          agent: from,
+          kind: "ack",
+          seq,
+          ...(ctx.discussionId && { thread_id: ctx.discussionId }),
+        });
+        return { content: [{ type: "text", text: "Acknowledged." }] };
+      },
+    ),
+  ]);
+}
+
+/**
+ * Recess handler — ends the run with a structured pause + resumption
+ * trigger; cancels any open Asks so askers see a synthetic null answer.
+ * `concluded` flips true (same as Adjourn); the `recessed` verdict
+ * distinguishes them, and `recessTrigger` carries the resume shape for
+ * the bridge.
+ */
+export function createRecessHandler(ctx) {
+  return async ({ reason, trigger }) => {
+    const guard = requireNoPendingAsks(ctx) ?? requireNoUnprocessedInbox(ctx);
+    if (guard) return guard;
+    ctx.recessTrigger = trigger;
+    concludeSession(ctx, {
+      verdict: "recessed",
+      summary: reason,
+      reason: "session recessed",
+    });
+    return { content: [{ type: "text", text: "Recess queued." }] };
+  };
+}
+
+/** Adjourn handler — ends the discussion with a verdict. */
+export function createAdjournHandler(ctx) {
+  return async ({ verdict, summary, outcome }) => {
+    const guard = requireNoPendingAsks(ctx) ?? requireNoUnprocessedInbox(ctx);
+    if (guard) return guard;
+    if (outcome !== undefined) ctx.outcome = outcome;
+    concludeSession(ctx, {
+      verdict,
+      summary,
+      reason: "session adjourned",
+    });
+    return { content: [{ type: "text", text: "Session adjourned." }] };
+  };
+}

package/src/discusser.js

@@ -0,0 +1,394 @@
+/**
+ * Discusser — async, suspendable orchestration on top of a within-run
+ * `OrchestrationLoop`. The lead role uses `DiscussTools` (Adjourn / Recess)
+ * instead of the facilitator's Conclude.
+ *
+ * Discuss mode is a sibling of facilitate mode, not a subset of it. The
+ * within-run turn loop is shared via `OrchestrationLoop`, but the lead
+ * role, tool set, system prompts, and participant naming all stay
+ * mode-local.
+ *
+ * Each agent Answer routed to the lead is captured as a thread reply
+ * delivered via the bridge callback — no explicit reply tool is needed
+ * on the lead surface.
+ */
+
+import { Writable } from "node:stream";
+import { resolve } from "node:path";
+
+import { createAgentRunner } from "./agent-runner.js";
+import { InboxPoller } from "./inbox-poller.js";
+import { ReplyEmitter } from "./reply-emitter.js";
+import { composeSystemPrompt } from "./profile-prompt.js";
+import { SequenceCounter } from "./sequence-counter.js";
+import { createMessageBus } from "./message-bus.js";
+import { createOrchestrationContext } from "./orchestration-toolkit.js";
+import {
+  createDiscussLeadToolServer,
+  createDiscussAgentToolServer,
+  DISCUSS_AGENT_SYSTEM_PROMPT,
+} from "./discuss-tools.js";
+import { OrchestrationLoop } from "./orchestration-loop.js";
+import { AGENT_MODEL, LEAD_MODEL } from "@forwardimpact/libutil/models";
+
+/** System prompt for the discuss-mode lead. L0 mechanics only per COALIGNED. */
+export const DISCUSS_SYSTEM_PROMPT =
+  "You lead a discussion.\n" +
+  "You have no tools to perform work yourself.\n" +
+  "Use `RollCall` to list participants.\n" +
+  "Use `Ask` to delegate work to the best-suited participant.\n" +
+  "Participants are domain experts; state the task, not how to do it.\n" +
+  "Each participant's `Answer` is posted to the discussion thread as a separate reply.\n" +
+  "`Ask` is async and returns {askIds:[N,…]} immediately.\n" +
+  "Answers arrive on your next turn as `[answer#N] <participant>: <text>` in your inbox.\n" +
+  "End your turn while Asks are pending. The system resumes you when answers arrive.\n" +
+  "Multiple `Ask` calls in one turn run participants in parallel.\n" +
+  "Use `Acknowledge` to post a brief message directly to the discussion thread — use it to respond to human follow-ups or give status updates while participants are working.\n" +
+  "End the discussion by calling `Adjourn` with a verdict and summary, or `Recess` only to wait on an external reply or duration.";
+
+/**
+ * Augment a base orchestration context with discuss-mode fields.
+ * @param {object} ctx
+ * @param {string|null} discussionId
+ * @returns {object}
+ */
+export function augmentContextForDiscuss(ctx, discussionId) {
+  ctx.discussionId = discussionId;
+  ctx.recessTrigger = null;
+  ctx.replies = [];
+  ctx.rfcs = [];
+  ctx.rfcCounter = 0;
+  ctx.outcome = null;
+  return ctx;
+}
+
+const devNull = new Writable({
+  write(_chunk, _enc, cb) {
+    cb();
+  },
+});
+
+/**
+ * Async orchestrator for the `discuss` mode. Composes an
+ * `OrchestrationLoop` for the within-run turns but owns the discussion id,
+ * the resumption trigger, and the discuss-augmented terminal summary.
+ */
+export class Discusser {
+  /**
+   * @param {object} deps
+   * @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]
+   */
+  constructor({
+    loop,
+    ctx,
+    output,
+    discussionId,
+    counter,
+    redactor,
+    inboxPoller,
+  }) {
+    if (!loop) throw new Error("loop is required");
+    if (!ctx) throw new Error("ctx is required");
+    if (!output) throw new Error("output is required");
+    if (!redactor) throw new Error("redactor is required");
+    this.loop = loop;
+    this.ctx = ctx;
+    this.output = output;
+    this.discussionId = discussionId ?? null;
+    this.counter = counter ?? new SequenceCounter();
+    this.redactor = redactor;
+    this.inboxPoller = inboxPoller ?? null;
+  }
+
+  /**
+   * Run the discussion. Emits the meta header first (when a discussion_id
+   * is set), delegates the within-run loop to `OrchestrationLoop`, then
+   * emits the discuss-augmented summary (overrides the loop's earlier
+   * summary; trace consumers keep the last summary they see).
+   *
+   * @param {string} task
+   * @returns {Promise<{success: boolean, verdict: string, turns: number, replies: object[], trigger: object|null}>}
+   */
+  async run(task) {
+    this.#emitMeta();
+
+    // The loop owns within-run turns. Its emitSummary fires once before
+    // run() returns; ours replaces it as the last summary line.
+    await this.loop.run(task);
+
+    const verdict = this.ctx.verdict ?? "failed";
+    const success = verdict === "adjourned";
+    this.#emitDiscussSummary({
+      success,
+      verdict,
+      turns: this.loop.leadTurns,
+    });
+
+    return {
+      success,
+      verdict,
+      turns: this.loop.leadTurns,
+      replies: this.ctx.replies.slice(),
+      trigger: this.ctx.recessTrigger ?? null,
+    };
+  }
+
+  #emitMeta() {
+    if (!this.discussionId) return;
+    this.output.write(
+      JSON.stringify(
+        this.redactor.redactValue({
+          source: "orchestrator",
+          seq: this.counter.next(),
+          event: { type: "meta", discussion_id: this.discussionId },
+        }),
+      ) + "\n",
+    );
+  }
+
+  #emitDiscussSummary({ success, verdict, turns }) {
+    const event = {
+      type: "summary",
+      success,
+      verdict,
+      turns,
+      ...(this.ctx.summary && { summary: this.ctx.summary }),
+      ...(this.ctx.outcome && { outcome: this.ctx.outcome }),
+      replies: this.ctx.replies,
+      ...(this.ctx.rfcs?.length && { rfcs: this.ctx.rfcs }),
+      ...(this.ctx.recessTrigger && { trigger: this.ctx.recessTrigger }),
+      ...(this.discussionId && { discussion_id: this.discussionId }),
+      lastActedSeq: this.inboxPoller?.lastActedSeq ?? -1,
+    };
+    this.output.write(
+      JSON.stringify(
+        this.redactor.redactValue({
+          source: "orchestrator",
+          seq: this.counter.next(),
+          event,
+        }),
+      ) + "\n",
+    );
+  }
+}
+
+/**
+ * Factory — wires the lead and agent runners with `DiscussTools`, builds
+ * 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]
+ * @param {string} [deps.agentModel]
+ * @param {Array<object>} [deps.agentConfigs]
+ * @param {string|null} [deps.discussionId]
+ * @param {object|null} [deps.resumeContext]
+ * @param {function} deps.query
+ * @param {import("stream").Writable} deps.output
+ * @param {number} [deps.maxTurns]
+ * @param {number} [deps.maxLeadTurns]
+ * @param {string} [deps.leadCwd]
+ * @param {string} [deps.profilesDir]
+ * @param {string} [deps.taskAmend]
+ * @param {object} deps.redactor
+ * @param {string|null} [deps.callbackUrl]
+ * @param {string|null} [deps.inboxUrl]
+ * @param {string|null} [deps.correlationId]
+ * @returns {Discusser}
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: factory wires N runners + resume hydration paths
+export function createDiscusser({
+  leadProfile,
+  leadModel,
+  agentModel,
+  agentConfigs,
+  discussionId,
+  resumeContext,
+  query,
+  output,
+  maxTurns,
+  maxLeadTurns,
+  leadCwd,
+  profilesDir,
+  taskAmend,
+  redactor,
+  callbackUrl,
+  inboxUrl,
+  correlationId,
+  runtime,
+}) {
+  if (!redactor) throw new Error("redactor is required");
+  if (!runtime) throw new Error("runtime is required");
+  const resolvedLeadCwd = resolve(leadCwd ?? ".");
+  const resolvedProfilesDir =
+    profilesDir ?? resolve(resolvedLeadCwd, ".claude/agents");
+  const resolvedConfigs = agentConfigs ?? [];
+
+  const ctx = augmentContextForDiscuss(
+    createOrchestrationContext(),
+    discussionId ?? null,
+  );
+
+  // 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 (Array.isArray(resumeContext.participants))
+      ctx.participants = resumeContext.participants;
+    if (Array.isArray(resumeContext.replies))
+      ctx.replies = resumeContext.replies;
+    if (typeof resumeContext.askIdCounter === "number")
+      ctx.askIdCounter = resumeContext.askIdCounter;
+    if (typeof resumeContext.rfcCounter === "number")
+      ctx.rfcCounter = resumeContext.rfcCounter;
+  }
+
+  const messageBus = createMessageBus({
+    participants: ["lead", ...resolvedConfigs.map((a) => a.name)],
+  });
+
+  const loopCounter = new SequenceCounter();
+  const emitter = new ReplyEmitter({
+    callbackUrl: callbackUrl ?? null,
+    correlationId: correlationId ?? null,
+    counter: loopCounter,
+  });
+  ctx.emitter = emitter;
+
+  const abortController = new AbortController();
+  const inboxPoller = inboxUrl
+    ? new InboxPoller({
+        inboxUrl,
+        messageBus,
+        leadName: "lead",
+        signal: abortController.signal,
+        runtime,
+      })
+    : null;
+
+  // Intercept answers routed to the lead — each becomes a discussion reply.
+  const originalAnswer = messageBus.answer.bind(messageBus);
+  messageBus.answer = (from, to, text, askId) => {
+    if (to === "lead" && from !== "@orchestrator") {
+      const seq = emitter.emit({ kind: "reply", body: text, agent: from });
+      ctx.replies.push({
+        body: text,
+        agent: from,
+        kind: "reply",
+        seq,
+        ...(ctx.discussionId && { thread_id: ctx.discussionId }),
+      });
+    }
+    originalAnswer(from, to, text, askId);
+  };
+
+  ctx.messageBus = messageBus;
+  if (ctx.participants.length === 0) {
+    ctx.participants = [
+      { name: "lead", role: "lead" },
+      ...resolvedConfigs.map((a) => ({ name: a.name, role: a.role })),
+    ];
+  }
+
+  let discusser;
+  const leadServer = createDiscussLeadToolServer(ctx);
+
+  const agents = resolvedConfigs.map((config) => {
+    const agentServer = createDiscussAgentToolServer(ctx, {
+      from: config.name,
+    });
+
+    const runner = createAgentRunner({
+      cwd: config.cwd ?? resolvedLeadCwd,
+      query,
+      output: devNull,
+      model: agentModel ?? AGENT_MODEL,
+      maxTurns: config.maxTurns ?? 50,
+      allowedTools: config.allowedTools,
+      onLine: (line) => discusser.loop.emitLine(config.name, line),
+      mcpServers: { orchestration: agentServer },
+      settingSources: ["project"],
+      systemPrompt: composeSystemPrompt({
+        role: "agent",
+        profile: config.agentProfile,
+        profilesDir: resolvedProfilesDir,
+        trailer: DISCUSS_AGENT_SYSTEM_PROMPT,
+        amend: config.systemPromptAmend,
+        runtime,
+      }),
+      redactor,
+    });
+
+    return { name: config.name, role: config.role, runner };
+  });
+
+  const defaultDisallowed = [
+    "Agent",
+    "Task",
+    "TaskOutput",
+    "TaskStop",
+    "Bash",
+    "Write",
+    "Edit",
+  ];
+  const leadRunner = createAgentRunner({
+    cwd: resolvedLeadCwd,
+    query,
+    output: devNull,
+    model: leadModel ?? LEAD_MODEL,
+    maxTurns: maxTurns ?? 80,
+    allowedTools: ["Read", "Glob", "Grep"],
+    disallowedTools: defaultDisallowed,
+    onLine: (line) => discusser.loop.emitLine("lead", line),
+    mcpServers: { orchestration: leadServer },
+    settingSources: ["project"],
+    systemPrompt: composeSystemPrompt({
+      role: "lead",
+      profile: leadProfile,
+      profilesDir: resolvedProfilesDir,
+      trailer: DISCUSS_SYSTEM_PROMPT,
+      runtime,
+    }),
+    redactor,
+  });
+
+  const loop = new OrchestrationLoop({
+    leadRunner,
+    agents,
+    messageBus,
+    output,
+    leadName: "lead",
+    mode: "discussion",
+    maxLeadTurns: maxLeadTurns ?? undefined,
+    ctx,
+    taskAmend,
+    redactor,
+    inboxPoller,
+    abortController,
+  });
+  loop.counter = loopCounter;
+
+  discusser = new Discusser({
+    loop,
+    ctx,
+    output,
+    discussionId: discussionId ?? null,
+    redactor,
+    counter: loopCounter,
+    inboxPoller,
+  });
+  return discusser;
+}