@forwardimpact/libharness 1.2.1 → 1.4.0

package/src/facilitator.js

@@ -12,11 +12,18 @@ import { createAgentRunner } from "./agent-runner.js";
 import { composeSystemPrompt } from "./profile-prompt.js";
 import { createMessageBus } from "./message-bus.js";
 import {
+  advisorTool,
   createOrchestrationContext,
   createFacilitatorToolServer,
   createFacilitatedAgentToolServer,
 } from "./orchestration-toolkit.js";
 import { OrchestrationLoop } from "./orchestration-loop.js";
+import {
+  createAdvisor,
+  createAdvisorBudget,
+  withAdvisorGuidance,
+} from "./advisor.js";
+import { createTranscriptRecorder } from "./transcript-recorder.js";
 
 /** System prompt for the facilitator lead. L0 mechanics only per COALIGNED. */
 export const FACILITATOR_SYSTEM_PROMPT =
@@ -92,6 +99,8 @@ const devNull = new Writable({
  * @param {string} [deps.facilitatorProfile]
  * @param {string} [deps.profilesDir]
  * @param {string} [deps.taskAmend]
+ * @param {string} [deps.advisorModel] - Claude model for advisor consults; absent means no Advisor tool is offered.
+ * @param {number} [deps.advisorMaxUses] - Session-wide consult budget shared by all agent participants (default 3).
  * @returns {Facilitator}
  */
 export function createFacilitator({
@@ -110,6 +119,8 @@ export function createFacilitator({
   taskAmend,
   redactor,
   runtime,
+  advisorModel,
+  advisorMaxUses,
 }) {
   if (!redactor) throw new Error("redactor is required");
   if (!runtime) throw new Error("runtime is required");
@@ -129,11 +140,55 @@ export function createFacilitator({
 
   const facilitatorServer = createFacilitatorToolServer(ctx);
 
+  const abortController = new AbortController();
+  // One budget per session, shared by every agent's Advisor handler.
+  const budget = advisorModel ? createAdvisorBudget(advisorMaxUses ?? 3) : null;
+
   const agents = agentConfigs.map((config) => {
+    // Everything advisor-shaped is gated on advisorModel; with it unset the
+    // composed prompt and tool surface are byte-identical to today's.
+    const systemPrompt = composeSystemPrompt({
+      role: "agent",
+      profile: config.agentProfile,
+      profilesDir: resolvedProfilesDir,
+      trailer: FACILITATED_AGENT_SYSTEM_PROMPT,
+      amend: withAdvisorGuidance(config.systemPromptAmend, budget),
+      runtime,
+    });
+
+    let recorder = null;
+    let extraTools;
+    if (advisorModel) {
+      recorder = createTranscriptRecorder({ systemPrompt, redactor });
+      // Late-bound through the `let facilitator` closure — the instance
+      // does not exist yet when the advisor and tool are built.
+      const advisor = createAdvisor({
+        model: advisorModel,
+        cwd: config.cwd ?? facilitatorCwd,
+        query,
+        recorder,
+        redactor,
+        runtime,
+        onLine: (line) => facilitator.emitLine("advisor", line),
+      });
+      abortController.signal.addEventListener("abort", () => advisor.abort());
+      extraTools = [
+        advisorTool({
+          from: config.name,
+          consult: (q) => advisor.consult(q),
+          emit: (e) => facilitator.emitOrchestratorEvent(e),
+          budget,
+          model: advisorModel,
+        }),
+      ];
+    }
+
     const agentServer = createFacilitatedAgentToolServer(ctx, {
       from: config.name,
+      ...(extraTools && { extraTools }),
     });
 
+    const emitAgentLine = (line) => facilitator.emitLine(config.name, line);
     const runner = createAgentRunner({
       cwd: config.cwd ?? facilitatorCwd,
       query,
@@ -141,17 +196,16 @@ export function createFacilitator({
       model: agentModel ?? model,
       maxTurns: config.maxTurns ?? 50,
       allowedTools: config.allowedTools,
-      onLine: (line) => facilitator.emitLine(config.name, line),
+      onLine: recorder
+        ? (line) => {
+            emitAgentLine(line);
+            recorder.recordMessage(line);
+          }
+        : emitAgentLine,
+      ...(recorder && { onPrompt: (text) => recorder.recordPrompt(text) }),
       mcpServers: { orchestration: agentServer },
       settingSources: ["project"],
-      systemPrompt: composeSystemPrompt({
-        role: "agent",
-        profile: config.agentProfile,
-        profilesDir: resolvedProfilesDir,
-        trailer: FACILITATED_AGENT_SYSTEM_PROMPT,
-        amend: config.systemPromptAmend,
-        runtime,
-      }),
+      systemPrompt,
       redactor,
     });
 
@@ -200,6 +254,7 @@ export function createFacilitator({
     ctx,
     taskAmend,
     redactor,
+    abortController,
   });
   return facilitator;
 }

package/src/index.js

@@ -26,6 +26,7 @@ export {
 export { TeeWriter, createTeeWriter } from "./tee-writer.js";
 export { SequenceCounter, createSequenceCounter } from "./sequence-counter.js";
 export {
+  advisorTool,
   createOrchestrationContext,
   createRequestForCommentHandler,
   createSupervisorToolServer,
@@ -34,6 +35,14 @@ export {
   createFacilitatedAgentToolServer,
   createJudgeToolServer,
 } from "./orchestration-toolkit.js";
+export {
+  ADVISOR_SYSTEM_PROMPT,
+  advisorGuidance,
+  createAdvisor,
+  createAdvisorBudget,
+  DEFAULT_CONSULT_TIMEOUT_MS,
+} from "./advisor.js";
+export { createTranscriptRecorder } from "./transcript-recorder.js";
 export { MessageBus, createMessageBus } from "./message-bus.js";
 export { OrchestrationLoop } from "./orchestration-loop.js";
 export {

package/src/orchestration-toolkit.js

@@ -337,6 +337,59 @@ 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.";
+
+/**
+ * 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.
+ *
+ * @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 {string} deps.model - Advisor model id, carried on the consult event.
+ */
+export function advisorTool({ from, consult, emit, budget, model }) {
+  return tool(
+    "Advisor",
+    ADVISOR_DESC,
+    { question: z.string() },
+    async ({ question }) => {
+      if (budget.used >= budget.maxUses) {
+        return textResult(
+          `Consult limit reached (${budget.maxUses}/${budget.maxUses} used) — proceed with your best judgment.`,
+        );
+      }
+      // Increment before the first await so two concurrent callers cannot
+      // both pass a last-slot check.
+      budget.used++;
+      const r = await consult(question);
+      const remaining = budget.maxUses - budget.used;
+      emit({
+        type: "advisor_consult",
+        caller: from,
+        question,
+        model,
+        durationMs: r.durationMs,
+        remaining,
+      });
+      if (r.unavailable) {
+        // Not isError: fail-open, the caller continues normally.
+        return textResult(
+          `The advisor is unavailable (${r.reason}) — proceed with your best judgment.`,
+        );
+      }
+      return textResult(
+        `${r.advice}\n\n[advisor consults remaining: ${remaining}]`,
+      );
+    },
+  );
+}
+
 const orchestrationServer = (tools) =>
   createSdkMcpServer({ name: "orchestration", tools });
 
@@ -354,15 +407,16 @@ export function createSupervisorToolServer(ctx) {
   ]);
 }
 
-/** Supervised agent tools: Ask + Answer + Announce + RollCall. */
-export function createSupervisedAgentToolServer(ctx) {
-  return orchestrationServer(
-    baseTools(ctx, {
+/** Supervised agent tools: Ask + Answer + Announce + RollCall (+ extras). */
+export function createSupervisedAgentToolServer(ctx, { extraTools = [] } = {}) {
+  return orchestrationServer([
+    ...baseTools(ctx, {
       from: "agent",
       defaultTo: "supervisor",
       broadcast: false,
     }),
-  );
+    ...extraTools,
+  ]);
 }
 
 /** Facilitator tools: Ask + Answer + Announce + RollCall + Conclude. */
@@ -377,11 +431,15 @@ export function createFacilitatorToolServer(ctx) {
   ]);
 }
 
-/** Facilitated agent tools: Ask + Answer + Announce + RollCall + RequestForComment. */
-export function createFacilitatedAgentToolServer(ctx, { from }) {
+/** Facilitated agent tools: Ask + Answer + Announce + RollCall + RequestForComment (+ extras). */
+export function createFacilitatedAgentToolServer(
+  ctx,
+  { from, extraTools = [] },
+) {
   return orchestrationServer([
     ...baseTools(ctx, { from, defaultTo: "facilitator", broadcast: true }),
     requestForCommentTool(ctx),
+    ...extraTools,
   ]);
 }
 

package/src/supervisor.js

@@ -21,11 +21,18 @@ import { createAgentRunner } from "./agent-runner.js";
 import { composeSystemPrompt } from "./profile-prompt.js";
 import { createMessageBus } from "./message-bus.js";
 import {
+  advisorTool,
   createOrchestrationContext,
   createSupervisedAgentToolServer,
   createSupervisorToolServer,
 } from "./orchestration-toolkit.js";
 import { OrchestrationLoop } from "./orchestration-loop.js";
+import {
+  createAdvisor,
+  createAdvisorBudget,
+  withAdvisorGuidance,
+} from "./advisor.js";
+import { createTranscriptRecorder } from "./transcript-recorder.js";
 
 /** System prompt for the supervisor lead. L0 mechanics only per COALIGNED. */
 export const SUPERVISOR_SYSTEM_PROMPT =
@@ -59,6 +66,7 @@ export class Supervisor extends OrchestrationLoop {
    * @param {object} deps.ctx
    * @param {object} deps.redactor
    * @param {string} [deps.taskAmend]
+   * @param {AbortController} [deps.abortController]
    */
   constructor({
     supervisorRunner,
@@ -68,6 +76,7 @@ export class Supervisor extends OrchestrationLoop {
     ctx,
     taskAmend,
     redactor,
+    abortController,
   }) {
     if (!agentRunner) throw new Error("agentRunner is required");
     if (!supervisorRunner) throw new Error("supervisorRunner is required");
@@ -82,6 +91,7 @@ export class Supervisor extends OrchestrationLoop {
       ctx,
       taskAmend,
       redactor,
+      abortController,
     });
   }
 
@@ -125,6 +135,8 @@ const devNull = new Writable({
  * @param {string} [deps.profilesDir]
  * @param {string} [deps.taskAmend]
  * @param {Record<string, object>} [deps.agentMcpServers]
+ * @param {string} [deps.advisorModel] - Claude model for advisor consults; absent means no Advisor tool is offered.
+ * @param {number} [deps.advisorMaxUses] - Session-wide consult budget (default 3).
  * @returns {Supervisor}
  */
 export function createSupervisor({
@@ -147,6 +159,8 @@ export function createSupervisor({
   agentMcpServers,
   redactor,
   runtime,
+  advisorModel,
+  advisorMaxUses,
 }) {
   if (!redactor) throw new Error("redactor is required");
   if (!runtime) throw new Error("runtime is required");
@@ -165,10 +179,58 @@ export function createSupervisor({
 
   let supervisor;
   const perRunBudget = maxTurns ?? 200;
+  const abortController = new AbortController();
+
+  // Advisor wiring — everything below is gated on advisorModel being set;
+  // with it unset the composed prompt and tool surface are byte-identical
+  // to today's.
+  const budget = advisorModel ? createAdvisorBudget(advisorMaxUses ?? 3) : null;
+  const agentSystemPrompt = composeSystemPrompt({
+    role: "agent",
+    profile: agentProfile,
+    profilesDir: resolvedProfilesDir,
+    trailer: AGENT_SYSTEM_PROMPT,
+    amend: withAdvisorGuidance(agentSystemPromptAmend, budget),
+    runtime,
+  });
 
-  const agentServer = createSupervisedAgentToolServer(ctx);
+  let recorder = null;
+  let extraTools;
+  if (advisorModel) {
+    recorder = createTranscriptRecorder({
+      systemPrompt: agentSystemPrompt,
+      redactor,
+    });
+    // Late-bound through the `let supervisor` closure — the instance does
+    // not exist yet when the advisor and tool are built.
+    const advisor = createAdvisor({
+      model: advisorModel,
+      cwd: agentCwd,
+      query,
+      recorder,
+      redactor,
+      runtime,
+      onLine: (line) => supervisor.emitLine("advisor", line),
+    });
+    abortController.signal.addEventListener("abort", () => advisor.abort());
+    extraTools = [
+      advisorTool({
+        from: "agent",
+        consult: (q) => advisor.consult(q),
+        emit: (e) => supervisor.emitOrchestratorEvent(e),
+        budget,
+        model: advisorModel,
+      }),
+    ];
+  }
+
+  const agentServer = createSupervisedAgentToolServer(
+    ctx,
+    extraTools ? { extraTools } : {},
+  );
   const supervisorServer = createSupervisorToolServer(ctx);
 
+  const emitAgentLine = (line) => supervisor.emitLine("agent", line);
   const agentRunner = createAgentRunner({
     cwd: agentCwd,
     query,
@@ -176,16 +238,15 @@ export function createSupervisor({
     model: agentModel ?? model,
     maxTurns: perRunBudget,
     allowedTools,
-    onLine: (line) => supervisor.emitLine("agent", line),
+    onLine: recorder
+      ? (line) => {
+          emitAgentLine(line);
+          recorder.recordMessage(line);
+        }
+      : emitAgentLine,
+    ...(recorder && { onPrompt: (text) => recorder.recordPrompt(text) }),
     settingSources: ["project"],
-    systemPrompt: composeSystemPrompt({
-      role: "agent",
-      profile: agentProfile,
-      profilesDir: resolvedProfilesDir,
-      trailer: AGENT_SYSTEM_PROMPT,
-      amend: agentSystemPromptAmend,
-      runtime,
-    }),
+    systemPrompt: agentSystemPrompt,
     mcpServers: { orchestration: agentServer, ...agentMcpServers },
     redactor,
   });
@@ -231,6 +292,7 @@ export function createSupervisor({
     ctx,
     taskAmend,
     redactor,
+    abortController,
   });
   return supervisor;
 }

package/src/transcript-recorder.js

@@ -0,0 +1,94 @@
+/**
+ * TranscriptRecorder — per-participant in-memory record of the composed
+ * system prompt, delivered prompts, and session messages, rendered into the
+ * context text an advisor consult forwards. Constructed only when a session
+ * runs with an advisor model; the harness otherwise keeps no per-participant
+ * record (session lines go straight to the trace stream).
+ *
+ * Redaction split: the message tap arrives post-redaction (fed from
+ * `AgentRunner.#recordLine`), but the seeded system prompt and the prompt
+ * tap are raw, so the recorder redacts those itself via the injected
+ * redactor.
+ */
+
+/**
+ * Normalize whatever the harness composed as a system prompt into plain
+ * text. In practice always a `{type:"preset", preset:"claude_code", append}`
+ * object (every recorded participant is an agent; leads are spec-excluded);
+ * a plain string is tolerated and `undefined` accepted.
+ * @param {string|{type: string, preset?: string, append?: string}|undefined} systemPrompt
+ * @returns {string|undefined}
+ */
+function normalizeSystemPrompt(systemPrompt) {
+  if (!systemPrompt) return undefined;
+  if (typeof systemPrompt === "string") return systemPrompt;
+  if (systemPrompt.append) {
+    return `(claude_code preset)\n${systemPrompt.append}`;
+  }
+  return undefined;
+}
+
+/** Wrap content in a tagged section, each tag on its own line. */
+function wrapSection(tag, content) {
+  return `<${tag}>\n${content}\n</${tag}>`;
+}
+
+/**
+ * Create a per-participant transcript recorder.
+ *
+ * @param {object} deps
+ * @param {string|object} [deps.systemPrompt] - The system prompt the harness
+ *   composed for the participant, as passed to its runner. Raw — redacted at
+ *   construction.
+ * @param {import("./redaction.js").Redactor} deps.redactor
+ * @returns {{recordPrompt: (text: string) => void, recordMessage: (line: string) => void, render: () => string}}
+ */
+export function createTranscriptRecorder({ systemPrompt, redactor }) {
+  if (!redactor) throw new Error("redactor is required");
+  const normalized = normalizeSystemPrompt(systemPrompt);
+  const seededPrompt = normalized
+    ? redactor.redactValue(normalized)
+    : undefined;
+  /** @type {string[]} */
+  const prompts = [];
+  /** @type {string[]} */
+  const messages = [];
+
+  return {
+    /**
+     * Record a delivered (amend-applied) prompt. Raw — redacted here.
+     * @param {string} text
+     */
+    recordPrompt(text) {
+      prompts.push(redactor.redactValue(text));
+    },
+    /**
+     * Record one NDJSON session line as-is (it arrives already redacted
+     * from the runner's line path).
+     * @param {string} line
+     */
+    recordMessage(line) {
+      messages.push(line);
+    },
+    /**
+     * Render the record as the advisor's context text: three tagged
+     * sections joined by blank lines, each present only when non-empty.
+     * NDJSON lines are verbatim — the forwarded context is uncurated by
+     * construction (context-size curation is spec-excluded).
+     * @returns {string}
+     */
+    render() {
+      const sections = [];
+      if (seededPrompt) {
+        sections.push(wrapSection("caller_system_prompt", seededPrompt));
+      }
+      if (prompts.length > 0) {
+        sections.push(wrapSection("caller_prompts", prompts.join("\n\n")));
+      }
+      if (messages.length > 0) {
+        sections.push(wrapSection("caller_transcript", messages.join("\n")));
+      }
+      return sections.join("\n\n");
+    },
+  };
+}