@forwardimpact/libharness 1.2.1 → 1.4.0

package/src/commands/run.js

@@ -1,11 +1,23 @@
 import { Writable } from "node:stream";
 import { resolve } from "node:path";
 import { isoTimestamp } from "@forwardimpact/libutil";
+import { createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
 import { createAgentRunner } from "../agent-runner.js";
-import { composeProfilePrompt } from "../profile-prompt.js";
+import {
+  advisorGuidance,
+  createAdvisor,
+  createAdvisorBudget,
+} from "../advisor.js";
+import { advisorTool } from "../orchestration-toolkit.js";
+import {
+  composeProfilePrompt,
+  composeSystemPrompt,
+} from "../profile-prompt.js";
 import { createRedactor } from "../redaction.js";
 import { createTeeWriter } from "../tee-writer.js";
+import { createTranscriptRecorder } from "../transcript-recorder.js";
 import { SequenceCounter } from "../sequence-counter.js";
+import { parseAdvisorOptions } from "./advisor-flags.js";
 import { resolveWorkTracker } from "./work-tracker.js";
 import { resolveTaskContent } from "./task-input.js";
 import { createServiceConfig } from "@forwardimpact/libconfig";
@@ -15,7 +27,7 @@ import { AGENT_MODEL } from "@forwardimpact/libutil/models";
  * Parse and validate run command options from parsed values.
  * @param {object} values - Parsed option values from cli.parse()
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
- * @returns {{ taskContent: string, cwd: string, model: string, maxTurns: number, outputPath: string|undefined, agentProfile: string|undefined, workTracker: string, allowedTools: string[] }}
+ * @returns {{ taskContent: string, taskAmend: string|undefined, cwd: string, agentModel: string, maxTurns: number, outputPath: string|undefined, agentProfile: string|undefined, workTracker: string, allowedTools: string[], mcpServer: string|undefined, advisorModel: string|undefined, advisorMaxUses: number }}
  */
 export function parseRunOptions(values, runtime) {
   const { task: taskContent, amend: taskAmend } = resolveTaskContent(
@@ -40,9 +52,148 @@ export function parseRunOptions(values, runtime) {
       "Bash,Read,Glob,Grep,Write,Edit,Agent,TodoWrite"
     ).split(","),
     mcpServer: values["mcp-server"] || undefined,
+    ...parseAdvisorOptions(values),
   };
 }
 
+const devNull = new Writable({
+  write(_chunk, _enc, cb) {
+    cb();
+  },
+});
+
+/**
+ * Wire the run-mode agent session: external MCP entry, `LIBHARNESS_*` env
+ * writes, system-prompt composition, and — when an advisor model is set —
+ * the advisor wiring (budget, recorder, advisor session, dedicated MCP
+ * server holding only the `Advisor` tool). Extracted from `runRunCommand`
+ * so tests can inject a fake `query`.
+ *
+ * Run mode has no stop path (the command simply awaits the runner), so the
+ * consult timeout is deliberately the advisor's only guard.
+ *
+ * @param {object} deps
+ * @param {ReturnType<typeof parseRunOptions>} deps.opts
+ * @param {import("../redaction.js").Redactor} deps.redactor
+ * @param {import("stream").Writable} deps.output - Envelope NDJSON sink.
+ * @param {SequenceCounter} deps.counter
+ * @param {function} deps.query - SDK query function.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} deps.runtime
+ * @returns {Promise<{runner: import("../agent-runner.js").AgentRunner, advisor: object|null}>}
+ */
+export async function wireRunSession({
+  opts,
+  redactor,
+  output,
+  counter,
+  query,
+  runtime,
+}) {
+  const emitEnvelope = (source, event) => {
+    output.write(
+      JSON.stringify(
+        redactor.redactValue({ source, seq: counter.next(), event }),
+      ) + "\n",
+    );
+  };
+  const onLine = (line) => emitEnvelope("agent", JSON.parse(line));
+
+  let mcpServers = null;
+  const allowedTools = opts.allowedTools;
+  if (opts.mcpServer) {
+    const mcpConfig = await createServiceConfig("mcp");
+    mcpServers = {
+      [opts.mcpServer]: {
+        type: "http",
+        url: mcpConfig.url,
+        headers: { Authorization: `Bearer ${mcpConfig.mcpToken()}` },
+      },
+    };
+    allowedTools.push(`mcp__${opts.mcpServer}__*`);
+  }
+
+  if (opts.agentProfile) {
+    runtime.proc.env.LIBHARNESS_AGENT_PROFILE = opts.agentProfile;
+  }
+  // Unconditional so the default "github" is observable to the agent's
+  // active-tracker resolution, mirroring --agent-profile's env write above.
+  runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
+
+  // With a profile, the consult guidance rides the profile composer's
+  // amendment parameter; with no profile, a preset-append prompt carries
+  // the guidance as its only session-protocol fragment. Advisor off and no
+  // profile means no system prompt — today's behavior, unchanged.
+  let systemPrompt;
+  if (opts.agentProfile) {
+    systemPrompt = composeProfilePrompt(opts.agentProfile, {
+      profilesDir: resolve(opts.cwd, ".claude/agents"),
+      runtime,
+      ...(opts.advisorModel && {
+        amend: advisorGuidance(opts.advisorMaxUses),
+      }),
+    });
+  } else if (opts.advisorModel) {
+    systemPrompt = composeSystemPrompt({
+      role: "agent",
+      trailer: advisorGuidance(opts.advisorMaxUses),
+      runtime,
+    });
+  }
+
+  let advisor = null;
+  let recorder = null;
+  if (opts.advisorModel) {
+    const budget = createAdvisorBudget(opts.advisorMaxUses);
+    recorder = createTranscriptRecorder({ systemPrompt, redactor });
+    advisor = createAdvisor({
+      model: opts.advisorModel,
+      cwd: opts.cwd,
+      query,
+      recorder,
+      redactor,
+      runtime,
+      onLine: (line) => emitEnvelope("advisor", JSON.parse(line)),
+    });
+    const advTool = advisorTool({
+      from: "agent",
+      consult: (q) => advisor.consult(q),
+      emit: (event) => emitEnvelope("orchestrator", event),
+      budget,
+      model: opts.advisorModel,
+    });
+    // No allowlist push: in-process SDK MCP servers work under
+    // bypassPermissions without allowlist entries (loop-mode precedent).
+    mcpServers = {
+      ...mcpServers,
+      advisor: createSdkMcpServer({ name: "advisor", tools: [advTool] }),
+    };
+  }
+
+  const runner = createAgentRunner({
+    cwd: opts.cwd,
+    query,
+    output: devNull,
+    model: opts.agentModel,
+    maxTurns: opts.maxTurns,
+    allowedTools,
+    onLine: recorder
+      ? (line) => {
+          onLine(line);
+          recorder.recordMessage(line);
+        }
+      : onLine,
+    ...(recorder && { onPrompt: (text) => recorder.recordPrompt(text) }),
+    settingSources: ["project"],
+    systemPrompt,
+    taskAmend: opts.taskAmend,
+    mcpServers,
+    redactor,
+    runtime,
+  });
+
+  return { runner, advisor };
+}
+
 /**
  * Run command — execute a single agent via the Claude Agent SDK.
  *
@@ -53,18 +204,7 @@ export function parseRunOptions(values, runtime) {
  */
 export async function runRunCommand(ctx) {
   const runtime = ctx.deps.runtime;
-  const {
-    taskContent,
-    taskAmend,
-    cwd,
-    agentModel,
-    maxTurns,
-    outputPath,
-    agentProfile,
-    workTracker,
-    allowedTools,
-    mcpServer,
-  } = parseRunOptions(ctx.options, runtime);
+  const opts = parseRunOptions(ctx.options, runtime);
 
   // Build the redactor as the first observable side-effect after option
   // parsing — the env snapshot must freeze BEFORE any in-process
@@ -73,8 +213,8 @@ export async function runRunCommand(ctx) {
 
   // When --output is specified, stream text to stdout while writing NDJSON to file.
   // Otherwise, write NDJSON directly to stdout (backwards-compatible).
-  const fileStream = outputPath
-    ? runtime.fs.createWriteStream(outputPath)
+  const fileStream = opts.outputPath
+    ? runtime.fs.createWriteStream(opts.outputPath)
     : null;
   const output = fileStream
     ? createTeeWriter({
@@ -86,62 +226,17 @@ export async function runRunCommand(ctx) {
     : runtime.proc.stdout;
 
   const counter = new SequenceCounter();
-  const devNull = new Writable({
-    write(_chunk, _enc, cb) {
-      cb();
-    },
-  });
-  const onLine = (line) => {
-    const event = JSON.parse(line);
-    const tagged = { source: "agent", seq: counter.next(), event };
-    output.write(JSON.stringify(redactor.redactValue(tagged)) + "\n");
-  };
-
-  let mcpServers = null;
-  if (mcpServer) {
-    const mcpConfig = await createServiceConfig("mcp");
-    mcpServers = {
-      [mcpServer]: {
-        type: "http",
-        url: mcpConfig.url,
-        headers: { Authorization: `Bearer ${mcpConfig.mcpToken()}` },
-      },
-    };
-    allowedTools.push(`mcp__${mcpServer}__*`);
-  }
-
-  if (agentProfile) {
-    runtime.proc.env.LIBHARNESS_AGENT_PROFILE = agentProfile;
-  }
-  // Unconditional so the default "github" is observable to the agent's
-  // active-tracker resolution, mirroring --agent-profile's env write above.
-  runtime.proc.env.LIBHARNESS_WORK_TRACKER = workTracker;
-
-  const systemPrompt = agentProfile
-    ? composeProfilePrompt(agentProfile, {
-        profilesDir: resolve(cwd, ".claude/agents"),
-        runtime,
-      })
-    : undefined;
-
   const { query } = await import("@anthropic-ai/claude-agent-sdk");
-  const runner = createAgentRunner({
-    cwd,
-    query,
-    output: devNull,
-    model: agentModel,
-    maxTurns,
-    allowedTools,
-    onLine,
-    settingSources: ["project"],
-    systemPrompt,
-    taskAmend,
-    mcpServers,
+  const { runner } = await wireRunSession({
+    opts,
     redactor,
+    output,
+    counter,
+    query,
     runtime,
   });
 
-  const result = await runner.run(taskContent);
+  const result = await runner.run(opts.taskContent);
 
   if (fileStream) {
     await new Promise((r) => output.end(r));

package/src/commands/scan-logs.js

@@ -0,0 +1,155 @@
+/**
+ * `fit-harness scan-logs` — scan a run's log archive for secret literals and
+ * fail closed.
+ *
+ * A run-lifecycle concern (not an NDJSON trace, so it lives here rather than
+ * in `fit-trace`): after a CI run that handled secrets, download or accept the
+ * run's own log archive and assert none of a supplied set of literals leaked
+ * into it. Any hit exits non-zero; any download/extract failure also exits
+ * non-zero — the gate must never silently disarm.
+ *
+ * Log resolution:
+ *   - `--archive <zip>` — an already-resolved archive (extracted locally).
+ *   - `--run-id <id> --repo <owner/repo>` — download this run's archive via
+ *     `gh` first, then extract.
+ *
+ * Secrets are `--secret <label>=<literal>`, repeatable. The literal is
+ * everything after the FIRST `=` (JWTs and base64 keys contain `=`); the label
+ * is only cosmetic, named in the `FAIL:` line.
+ */
+
+import { join } from "node:path";
+
+/**
+ * Parse repeatable `--secret label=literal` flags. libcli's `multiple: true`
+ * yields an array from node's parseArgs in every case; tolerate a bare string
+ * or undefined defensively. Split on the FIRST `=` only.
+ *
+ * @param {string[]|string|undefined} secretOpt
+ * @returns {{label: string, literal: string}[]}
+ */
+export function parseSecrets(secretOpt) {
+  const arr = Array.isArray(secretOpt)
+    ? secretOpt
+    : secretOpt
+      ? [secretOpt]
+      : [];
+  return arr.map((s) => {
+    const idx = s.indexOf("=");
+    if (idx === -1) return { label: s, literal: "" };
+    return { label: s.slice(0, idx), literal: s.slice(idx + 1) };
+  });
+}
+
+/**
+ * Walk a directory tree and return every file path. Uses per-level readdir so
+ * it works against both node:fs and the libmock fs (no `recursive` reliance).
+ */
+async function collectFiles(dir, runtime) {
+  const out = [];
+  const entries = await runtime.fs.readdir(dir, { withFileTypes: true });
+  for (const ent of entries) {
+    const full = join(dir, ent.name);
+    if (ent.isDirectory()) {
+      out.push(...(await collectFiles(full, runtime)));
+    } else if (ent.isFile()) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Scan every file under `dir` for each secret literal. Returns the labels of
+ * secrets whose non-empty literal appears in any file (empty literals are
+ * skipped — a secret the run never set cannot leak).
+ *
+ * @param {object} params
+ * @param {string} params.dir
+ * @param {{label: string, literal: string}[]} params.secrets
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} params.runtime
+ * @returns {Promise<string[]>} labels that hit
+ */
+export async function scanDirectory({ dir, secrets, runtime }) {
+  const files = await collectFiles(dir, runtime);
+  const contents = await Promise.all(
+    files.map((f) => runtime.fs.readFile(f, "utf8").catch(() => "")),
+  );
+  const failures = [];
+  for (const { label, literal } of secrets) {
+    if (!literal) continue;
+    if (contents.some((c) => c.includes(literal))) failures.push(label);
+  }
+  return failures;
+}
+
+/**
+ * Resolve a directory of extracted log files, downloading the archive first
+ * when given a run id. Throws (→ fail closed) on any download or extract
+ * failure or on missing/invalid inputs.
+ */
+async function resolveLogsDir({ options, runtime }) {
+  const tmpRoot = runtime.proc.env.RUNNER_TEMP || "/tmp";
+  const dir = await runtime.fs.mkdtemp(join(tmpRoot, "scan-logs-"));
+  let zip = options.archive;
+
+  if (!zip) {
+    const runId = options["run-id"];
+    const repo = options.repo;
+    if (!runId || !repo) {
+      throw new Error("requires --archive, or --run-id and --repo");
+    }
+    if (!/^\d+$/.test(String(runId))) {
+      throw new Error("--run-id must be numeric");
+    }
+    if (!/^[\w.-]+\/[\w.-]+$/.test(repo)) {
+      throw new Error("--repo must be owner/name");
+    }
+    zip = join(dir, "run-logs.zip");
+    const dl = await runtime.subprocess.run("bash", [
+      "-c",
+      `gh api -H "Accept: application/vnd.github+json" ` +
+        `"/repos/${repo}/actions/runs/${runId}/logs" > "${zip}"`,
+    ]);
+    if (dl.exitCode !== 0) {
+      throw new Error(
+        `log archive download failed (gh exit ${dl.exitCode}): ${dl.stderr ?? ""}`,
+      );
+    }
+  }
+
+  const unz = await runtime.subprocess.run("unzip", ["-q", zip, "-d", dir]);
+  if (unz.exitCode !== 0) {
+    throw new Error(
+      `log archive empty/unreadable (unzip exit ${unz.exitCode})`,
+    );
+  }
+  return dir;
+}
+
+/**
+ * scan-logs command handler.
+ *
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: boolean, code: number, error?: string}>}
+ */
+export async function runScanLogsCommand(ctx) {
+  const runtime = ctx.deps.runtime;
+  const options = ctx.options;
+  const secrets = parseSecrets(options.secret);
+
+  let dir;
+  try {
+    dir = await resolveLogsDir({ options, runtime });
+  } catch (err) {
+    // Fail closed: an unresolvable archive must not pass as "no leak". The
+    // dispatcher prints the returned `error`, so don't also write it here.
+    return { ok: false, code: 1, error: `scan-logs: ${err.message}` };
+  }
+
+  const failures = await scanDirectory({ dir, secrets, runtime });
+  for (const label of failures) {
+    runtime.proc.stderr.write(`FAIL: ${label} literal in run logs\n`);
+  }
+  return { ok: failures.length === 0, code: failures.length ? 1 : 0 };
+}

package/src/commands/supervise.js

@@ -3,6 +3,7 @@ import { isoTimestamp } from "@forwardimpact/libutil";
 import { createSupervisor } from "../supervisor.js";
 import { createRedactor } from "../redaction.js";
 import { createTeeWriter } from "../tee-writer.js";
+import { parseAdvisorOptions } from "./advisor-flags.js";
 import { resolveTaskContent } from "./task-input.js";
 import { resolveWorkTracker } from "./work-tracker.js";
 import { createServiceConfig } from "@forwardimpact/libconfig";
@@ -52,6 +53,7 @@ export async function parseSuperviseOptions(values, runtime) {
       ? supervisorAllowedToolsRaw.split(",")
       : undefined,
     mcpServer: values["mcp-server"] || undefined,
+    ...parseAdvisorOptions(values),
   };
 }
 
@@ -125,6 +127,8 @@ export async function runSuperviseCommand(ctx) {
     agentMcpServers,
     redactor,
     runtime,
+    advisorModel: opts.advisorModel,
+    advisorMaxUses: opts.advisorMaxUses,
   });
 
   const result = await supervisor.run(opts.taskContent);

package/src/discuss-tools.js

@@ -107,7 +107,7 @@ 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 }) {
+export function createDiscussAgentToolServer(ctx, { from, extraTools = [] }) {
   return orchestrationServer([
     ...baseTools(ctx, { from, defaultTo: "lead", broadcast: true }),
     requestForCommentTool(ctx),
@@ -133,6 +133,7 @@ export function createDiscussAgentToolServer(ctx, { from }) {
         return { content: [{ type: "text", text: "Acknowledged." }] };
       },
     ),
+    ...extraTools,
   ]);
 }
 

package/src/discusser.js

@@ -22,7 +22,16 @@ 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 {
+  advisorTool,
+  createOrchestrationContext,
+} from "./orchestration-toolkit.js";
+import {
+  createAdvisor,
+  createAdvisorBudget,
+  withAdvisorGuidance,
+} from "./advisor.js";
+import { createTranscriptRecorder } from "./transcript-recorder.js";
 import {
   createDiscussLeadToolServer,
   createDiscussAgentToolServer,
@@ -206,6 +215,8 @@ export class Discusser {
  * @param {string|null} [deps.callbackUrl]
  * @param {string|null} [deps.inboxUrl]
  * @param {string|null} [deps.correlationId]
+ * @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 {Discusser}
  */
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: factory wires N runners + resume hydration paths
@@ -228,6 +239,8 @@ export function createDiscusser({
   inboxUrl,
   correlationId,
   runtime,
+  advisorModel,
+  advisorMaxUses,
 }) {
   if (!redactor) throw new Error("redactor is required");
   if (!runtime) throw new Error("runtime is required");
@@ -306,11 +319,54 @@ export function createDiscusser({
   let discusser;
   const leadServer = createDiscussLeadToolServer(ctx);
 
+  // One budget per session, shared by every agent's Advisor handler.
+  const budget = advisorModel ? createAdvisorBudget(advisorMaxUses ?? 3) : null;
+
   const agents = resolvedConfigs.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: DISCUSS_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 discusser` closure — the instance does
+      // not exist yet when the advisor and tool are built.
+      const advisor = createAdvisor({
+        model: advisorModel,
+        cwd: config.cwd ?? resolvedLeadCwd,
+        query,
+        recorder,
+        redactor,
+        runtime,
+        onLine: (line) => discusser.loop.emitLine("advisor", line),
+      });
+      abortController.signal.addEventListener("abort", () => advisor.abort());
+      extraTools = [
+        advisorTool({
+          from: config.name,
+          consult: (q) => advisor.consult(q),
+          emit: (e) => discusser.loop.emitOrchestratorEvent(e),
+          budget,
+          model: advisorModel,
+        }),
+      ];
+    }
+
     const agentServer = createDiscussAgentToolServer(ctx, {
       from: config.name,
+      ...(extraTools && { extraTools }),
     });
 
+    const emitAgentLine = (line) => discusser.loop.emitLine(config.name, line);
     const runner = createAgentRunner({
       cwd: config.cwd ?? resolvedLeadCwd,
       query,
@@ -318,17 +374,16 @@ export function createDiscusser({
       model: agentModel ?? AGENT_MODEL,
       maxTurns: config.maxTurns ?? 50,
       allowedTools: config.allowedTools,
-      onLine: (line) => discusser.loop.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: DISCUSS_AGENT_SYSTEM_PROMPT,
-        amend: config.systemPromptAmend,
-        runtime,
-      }),
+      systemPrompt,
       redactor,
     });