@forwardimpact/libharness 1.3.0 → 1.4.0

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");
+    },
+  };
+}