@forwardimpact/libharness 0.1.20 → 1.0.0

package/src/render/tool-hints.js

@@ -0,0 +1,154 @@
+/**
+ * Tool hints — pure one-line formatters for tool-call arguments and
+ * tool-result previews.
+ *
+ * `hintForCall(name, input)` renders the human-meaningful field for each
+ * tool (file path, command, pattern, …) sanitized to strip JSON punctuation
+ * (`{`, `}`, `"`) and collapsed to a single line ≤ 80 chars.
+ *
+ * MCP-prefixed tools (`mcp__*`) are an intentional carve-out: their hint is
+ * the full input rendered as compact single-line JSON, so `{` and `"` do
+ * appear on those lines. Readers of GitHub workflow logs need the full MCP
+ * payload to know what was actually sent across the protocol.
+ *
+ * `previewForResult(content, isError)` collapses a tool result to a single
+ * line ≤ 80 chars and flags errors so the renderer can apply the reserved
+ * error color and the `Error:` label.
+ */
+
+const MAX_HINT_CHARS = 80;
+
+/**
+ * Strip `{`, `}`, `"`, collapse whitespace, and truncate to MAX_HINT_CHARS.
+ * First line only — anything past a newline is dropped. Always returns a
+ * string, never null/undefined.
+ * @param {unknown} raw
+ * @returns {string}
+ */
+function sanitize(raw) {
+  if (raw === null || raw === undefined) return "";
+  const str = String(raw);
+  const firstLine = str.split(/\r?\n/)[0] ?? "";
+  const stripped = firstLine.replace(/[{}"]/g, "");
+  const collapsed = stripped.replace(/\s+/g, " ").trim();
+  if (collapsed.length <= MAX_HINT_CHARS) return collapsed;
+  return collapsed.slice(0, MAX_HINT_CHARS - 3) + "...";
+}
+
+/**
+ * Truncate an already-sanitized string to MAX_HINT_CHARS with a trailing
+ * ellipsis when it overflows. Shared by the few handlers that concatenate
+ * multiple sanitized pieces before deciding on truncation.
+ * @param {string} str
+ * @returns {string}
+ */
+function truncate(str) {
+  return str.length <= MAX_HINT_CHARS
+    ? str
+    : str.slice(0, MAX_HINT_CHARS - 3) + "...";
+}
+
+/**
+ * Per-tool hint handlers. Each entry takes the sanitized input object
+ * (never null) and returns the hint string. Kept as a flat table so adding
+ * a new tool is one entry, not a new branch in a growing switch.
+ */
+const HINT_HANDLERS = {
+  Bash: (i) => sanitize(i.command),
+  Read: (i) => sanitize(i.file_path),
+  Write: (i) => sanitize(i.file_path),
+  Edit: (i) => {
+    const base = sanitize(i.file_path);
+    return i.replace_all
+      ? (base + " (replace_all)").slice(0, MAX_HINT_CHARS)
+      : base;
+  },
+  Glob: (i) => sanitize(i.pattern),
+  Grep: (i) => {
+    const pattern = sanitize(i.pattern);
+    return i.path ? truncate(`${pattern} in ${sanitize(i.path)}`) : pattern;
+  },
+  WebFetch: (i) => sanitize(i.url),
+  WebSearch: (i) => sanitize(i.query),
+  ToolSearch: (i) => sanitize(i.query),
+  TodoWrite: (i) => {
+    const count = Array.isArray(i.todos) ? i.todos.length : 0;
+    return `${count} todos`;
+  },
+  NotebookEdit: (i) => sanitize(i.notebook_path),
+  Skill: (i) => sanitize(i.skill),
+  Agent: (i) => sanitize(i.prompt ?? i.description),
+  Task: (i) => sanitize(i.prompt ?? i.description),
+};
+
+/**
+ * Strip the `mcp__<server>__` prefix from MCP-namespaced tool names so logs
+ * show the bare method (e.g. `mcp__orchestration__Ask` → `Ask`). Non-MCP
+ * names and malformed inputs pass through unchanged.
+ * @param {string} name
+ * @returns {string}
+ */
+export function simplifyToolName(name) {
+  if (!name) return "";
+  if (!name.startsWith("mcp__")) return name;
+  const parts = name.split("__");
+  if (parts.length < 3) return name;
+  return parts.slice(2).join("__");
+}
+
+/**
+ * Map a tool name and input to a one-line human hint.
+ *
+ * Three branches, in priority order:
+ *  - A built-in tool with an entry in `HINT_HANDLERS` → sanitized hint, no
+ *    `{` / `"` from the input (built-in tool hints stay free of JSON
+ *    punctuation so readers see clean one-liners).
+ *  - An MCP-prefixed tool (`mcp__*`) → full input rendered as compact
+ *    single-line JSON; `{` and `"` intentionally appear so readers see
+ *    the actual MCP payload.
+ *  - Anything else → "" (the caller still shows the bare tool name).
+ *
+ * @param {string} name - Tool name (e.g. "Bash", "Read", "mcp__orchestration__Ask")
+ * @param {object|null|undefined} input - Raw tool input object from the trace
+ * @returns {string} One-line hint, or "" when no rule matches
+ */
+export function hintForCall(name, input) {
+  if (!name) return "";
+  const safeInput = input && typeof input === "object" ? input : {};
+
+  const handler = HINT_HANDLERS[name];
+  if (handler) return handler(safeInput);
+
+  if (name.startsWith("mcp__")) return JSON.stringify(safeInput);
+
+  return "";
+}
+
+/**
+ * Render a tool result as a single preview line plus an `isError` flag.
+ * The flag lets the line-renderer pick the reserved error color without
+ * re-inspecting the content.
+ *
+ * @param {string|object|null|undefined} content - Tool result content
+ * @param {boolean} isError - Whether the tool call failed
+ * @returns {{text: string, isError: boolean}}
+ */
+export function previewForResult(content, isError) {
+  const normalized =
+    content === null || content === undefined
+      ? ""
+      : typeof content === "string"
+        ? content
+        : JSON.stringify(content);
+  const firstNonBlank =
+    normalized
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .find((l) => l.length > 0) ?? "";
+
+  const fallback = isError ? "(no output)" : "(ok)";
+  return {
+    text: truncate(firstNonBlank || fallback),
+    isError,
+  };
+}

package/src/render/turn-renderer.js

@@ -0,0 +1,96 @@
+/**
+ * Turn renderer — maps a structured turn into formatted text lines.
+ *
+ * Shared by `TeeWriter.flushTurns()` (live stream) and
+ * `TraceCollector.toText()` (offline replay) so both emit identical output.
+ */
+
+import {
+  renderTextLine,
+  renderToolCallLine,
+  renderToolResultLine,
+} from "./line-renderer.js";
+import {
+  hintForCall,
+  previewForResult,
+  simplifyToolName,
+} from "./tool-hints.js";
+
+/**
+ * Render a single turn to formatted text lines.
+ *
+ * @param {object} turn - Structured turn object
+ * @param {boolean} withPrefix - Whether to include source labels
+ * @returns {string[]} Array of rendered line strings
+ */
+export function renderTurnLines(turn, withPrefix) {
+  return TURN_RENDERERS[turn.role]?.(turn, withPrefix) ?? [];
+}
+
+/** @param {object} turn @param {boolean} withPrefix @returns {string[]} */
+function renderAssistantTurn(turn, withPrefix) {
+  const lines = [];
+  for (const block of turn.content) {
+    if (block.type === "text") {
+      lines.push(
+        renderTextLine({ source: turn.source, text: block.text, withPrefix }),
+      );
+    } else if (block.type === "tool_use") {
+      lines.push(
+        renderToolCallLine({
+          source: turn.source,
+          toolName: simplifyToolName(block.name),
+          hint: hintForCall(block.name, block.input),
+          withPrefix,
+        }),
+      );
+    }
+  }
+  return lines;
+}
+
+/** @param {object} turn @param {boolean} withPrefix @returns {string[]} */
+function renderToolResultTurn(turn, withPrefix) {
+  // Successful tool results emit no preview line — the trace document keeps
+  // the structured turn, but readers of the streamed log only see errors.
+  if (!turn.isError) return [];
+  return [
+    renderToolResultLine({
+      source: turn.source,
+      preview: previewForResult(turn.content, true),
+      withPrefix,
+    }),
+  ];
+}
+
+/** @param {object} turn @param {boolean} withPrefix @returns {string[]} */
+function renderSystemTurn(turn, withPrefix) {
+  const label = turn.subtype ?? "system";
+  return [
+    renderTextLine({ source: turn.source, text: `[${label}]`, withPrefix }),
+  ];
+}
+
+/** @param {object} turn @param {boolean} withPrefix @returns {string[]} */
+function renderUserTurn(turn, withPrefix) {
+  const lines = [];
+  for (const block of turn.content) {
+    if (block.type === "text") {
+      lines.push(
+        renderTextLine({
+          source: turn.source,
+          text: `[user] ${block.text}`,
+          withPrefix,
+        }),
+      );
+    }
+  }
+  return lines;
+}
+
+const TURN_RENDERERS = {
+  assistant: renderAssistantTurn,
+  tool_result: renderToolResultTurn,
+  system: renderSystemTurn,
+  user: renderUserTurn,
+};

package/src/reply-emitter.js

@@ -0,0 +1,47 @@
+/**
+ * ReplyEmitter — POST reply/ack events to the callback URL as they
+ * happen. Each emission is fire-and-forget so the message bus is never
+ * blocked on network I/O.
+ */
+export class ReplyEmitter {
+  #callbackUrl;
+  #correlationId;
+  #counter;
+
+  /**
+   * @param {object} deps
+   * @param {string|null} deps.callbackUrl
+   * @param {string|null} deps.correlationId
+   * @param {import("./sequence-counter.js").SequenceCounter} deps.counter
+   */
+  constructor({ callbackUrl, correlationId, counter }) {
+    this.#callbackUrl = callbackUrl;
+    this.#correlationId = correlationId;
+    this.#counter = counter;
+  }
+
+  /**
+   * @param {object} event
+   * @param {"reply"|"ack"} event.kind
+   * @param {string} event.body
+   * @param {string} event.agent
+   * @returns {number} The assigned seq number
+   */
+  emit({ kind, body, agent }) {
+    const seq = this.#counter.next();
+    if (this.#callbackUrl) {
+      fetch(this.#callbackUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          correlation_id: this.#correlationId,
+          kind,
+          seq,
+          body,
+          agent,
+        }),
+      }).catch(() => {});
+    }
+    return seq;
+  }
+}

package/src/sequence-counter.js

@@ -0,0 +1,21 @@
+/**
+ * SequenceCounter — global monotonic counter shared across all participants
+ * in a session. Single-threaded JS means no synchronization needed.
+ */
+/** Monotonic counter that assigns globally ordered sequence numbers within a session. */
+export class SequenceCounter {
+  /** Initialize the counter at zero. */
+  constructor() {
+    this.value = 0;
+  }
+
+  /** Return the current value and advance the counter by one. */
+  next() {
+    return this.value++;
+  }
+}
+
+/** Create a new SequenceCounter starting at zero. */
+export function createSequenceCounter() {
+  return new SequenceCounter();
+}

package/src/signature-filter.js

@@ -0,0 +1,27 @@
+/**
+ * Strip `thinking.signature` base64 blobs from a JSON-serializable value.
+ *
+ * Applied at the CLI output boundary — the stored structured trace keeps
+ * signatures intact (lossless storage), and the display filter drops them
+ * by default because they dominate output without helping analysis.
+ *
+ * Recursively walks the input. For any object whose `type === "thinking"`,
+ * the `signature` field is removed after copying. Signatures on objects of
+ * any other type are preserved.
+ *
+ * @param {*} value - Any JSON-serializable value
+ * @returns {*} A deep-copy with thinking signatures removed
+ */
+export function stripSignatures(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(stripSignatures);
+
+  const result = {};
+  for (const [key, val] of Object.entries(value)) {
+    result[key] = stripSignatures(val);
+  }
+  if (result.type === "thinking") {
+    delete result.signature;
+  }
+  return result;
+}

package/src/supervisor.js

@@ -0,0 +1,236 @@
+/**
+ * Supervisor — supervise-mode wrapper around `OrchestrationLoop`. One
+ * named participant (`"agent"`) coordinated by a lead participant
+ * (`"supervisor"`). Structurally the same as `Facilitator` with a
+ * single agent; differs only in role names, prompts, and pass-through
+ * accessors.
+ *
+ * Ask is async (same contract as facilitate / discuss): returns
+ * `{askIds:[N]}` immediately; the agent's reply arrives on the
+ * supervisor's next turn as `[answer#N] agent: <text>`. The supervisor
+ * sees the agent at each Ask boundary, plans the next step, and
+ * eventually calls Conclude.
+ *
+ * For tighter feedback loops, size the agent's per-turn budget down
+ * (smaller `maxTurns` on the agent runner) so each Ask returns sooner.
+ */
+
+import { Writable } from "node:stream";
+import { resolve } from "node:path";
+import { createAgentRunner } from "./agent-runner.js";
+import { composeSystemPrompt } from "./profile-prompt.js";
+import { createMessageBus } from "./message-bus.js";
+import {
+  createOrchestrationContext,
+  createSupervisedAgentToolServer,
+  createSupervisorToolServer,
+} from "./orchestration-toolkit.js";
+import { OrchestrationLoop } from "./orchestration-loop.js";
+
+/** System prompt for the supervisor lead. L0 mechanics only per COALIGNED. */
+export const SUPERVISOR_SYSTEM_PROMPT =
+  "You supervise one agent.\n" +
+  "Use `Ask` to delegate the agent's task to the agent.\n" +
+  "`Ask` is async and returns {askIds:[N]} immediately.\n" +
+  "The reply arrives on your next turn as `[answer#N] agent: <text>` in your inbox.\n" +
+  "End your turn while Asks are pending. The system resumes you when an answer arrives.\n" +
+  "If the agent goes off-track, send a corrective `Ask`.\n" +
+  "End every session by calling `Conclude` with a verdict and summary.";
+
+/** System prompt for the supervised agent. L0 mechanics only per COALIGNED. */
+export const AGENT_SYSTEM_PROMPT =
+  "A supervisor directs your work.\n" +
+  "Each question arrives as `[ask#N] supervisor: <text>` in your inbox.\n" +
+  "Quote N as askId on your `Answer` to route the reply correctly.\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.";
+
+/**
+ * Supervise-mode wrapper around `OrchestrationLoop`. The lead is
+ * `"supervisor"`, one participant is `"agent"`, mode tag is `"supervised"`.
+ */
+export class Supervisor extends OrchestrationLoop {
+  /**
+   * @param {object} deps
+   * @param {import("./agent-runner.js").AgentRunner} deps.supervisorRunner
+   * @param {import("./agent-runner.js").AgentRunner} deps.agentRunner
+   * @param {import("./message-bus.js").MessageBus} deps.messageBus
+   * @param {import("stream").Writable} deps.output
+   * @param {object} deps.ctx
+   * @param {object} deps.redactor
+   * @param {string} [deps.taskAmend]
+   */
+  constructor({
+    supervisorRunner,
+    agentRunner,
+    messageBus,
+    output,
+    ctx,
+    taskAmend,
+    redactor,
+  }) {
+    if (!agentRunner) throw new Error("agentRunner is required");
+    if (!supervisorRunner) throw new Error("supervisorRunner is required");
+    if (!output) throw new Error("output is required");
+    super({
+      leadRunner: supervisorRunner,
+      agents: [{ name: "agent", role: "agent", runner: agentRunner }],
+      messageBus,
+      output,
+      leadName: "supervisor",
+      mode: "supervised",
+      ctx,
+      taskAmend,
+      redactor,
+    });
+  }
+
+  /** Readability shims for tests that read the runners by their domain names. */
+  /** Readability shim — exposes the lead runner under its mode-specific name. */
+  get supervisorRunner() {
+    return this.leadRunner;
+  }
+
+  /** Readability shim — exposes the single agent runner directly. */
+  get agentRunner() {
+    return this.agents[0].runner;
+  }
+}
+
+const devNull = new Writable({
+  write(_chunk, _enc, cb) {
+    cb();
+  },
+});
+
+/**
+ * Factory — wires the supervisor + agent runners and the orchestration
+ * context. Mirrors the facilitator factory in shape.
+ *
+ * @param {object} deps
+ * @param {string} deps.supervisorCwd
+ * @param {string} deps.agentCwd
+ * @param {function} deps.query
+ * @param {import("stream").Writable} deps.output
+ * @param {string} [deps.model]
+ * @param {string} [deps.agentModel]
+ * @param {string} [deps.supervisorModel]
+ * @param {number} [deps.maxTurns] - Per-runner SDK turn budget (default 200).
+ * @param {string[]} [deps.allowedTools]
+ * @param {string[]} [deps.supervisorAllowedTools]
+ * @param {string[]} [deps.supervisorDisallowedTools]
+ * @param {string} [deps.supervisorProfile]
+ * @param {string} [deps.agentProfile]
+ * @param {string} [deps.agentSystemPromptAmend] - Amendment folded into the agent's `<session_protocol>` section, after the protocol trailer.
+ * @param {string} [deps.profilesDir]
+ * @param {string} [deps.taskAmend]
+ * @param {Record<string, object>} [deps.agentMcpServers]
+ * @returns {Supervisor}
+ */
+export function createSupervisor({
+  supervisorCwd,
+  agentCwd,
+  query,
+  output,
+  model,
+  agentModel,
+  supervisorModel,
+  maxTurns,
+  allowedTools,
+  supervisorAllowedTools,
+  supervisorDisallowedTools,
+  supervisorProfile,
+  agentProfile,
+  agentSystemPromptAmend,
+  profilesDir,
+  taskAmend,
+  agentMcpServers,
+  redactor,
+  runtime,
+}) {
+  if (!redactor) throw new Error("redactor is required");
+  if (!runtime) throw new Error("runtime is required");
+  const resolvedProfilesDir =
+    profilesDir ?? resolve(supervisorCwd, ".claude/agents");
+
+  const ctx = createOrchestrationContext();
+  const messageBus = createMessageBus({
+    participants: ["supervisor", "agent"],
+  });
+  ctx.messageBus = messageBus;
+  ctx.participants = [
+    { name: "supervisor", role: "supervisor" },
+    { name: "agent", role: "agent" },
+  ];
+
+  let supervisor;
+  const perRunBudget = maxTurns ?? 200;
+
+  const agentServer = createSupervisedAgentToolServer(ctx);
+  const supervisorServer = createSupervisorToolServer(ctx);
+
+  const agentRunner = createAgentRunner({
+    cwd: agentCwd,
+    query,
+    output: devNull,
+    model: agentModel ?? model,
+    maxTurns: perRunBudget,
+    allowedTools,
+    onLine: (line) => supervisor.emitLine("agent", line),
+    settingSources: ["project"],
+    systemPrompt: composeSystemPrompt({
+      role: "agent",
+      profile: agentProfile,
+      profilesDir: resolvedProfilesDir,
+      trailer: AGENT_SYSTEM_PROMPT,
+      amend: agentSystemPromptAmend,
+      runtime,
+    }),
+    mcpServers: { orchestration: agentServer, ...agentMcpServers },
+    redactor,
+  });
+
+  const defaultDisallowed = [
+    "Agent",
+    "Task",
+    "TaskOutput",
+    "TaskStop",
+    "Write",
+    "Edit",
+  ];
+  const disallowedTools = supervisorDisallowedTools
+    ? [...new Set([...defaultDisallowed, ...supervisorDisallowedTools])]
+    : defaultDisallowed;
+
+  const supervisorRunner = createAgentRunner({
+    cwd: supervisorCwd,
+    query,
+    output: devNull,
+    model: supervisorModel ?? model,
+    maxTurns: perRunBudget,
+    allowedTools: supervisorAllowedTools ?? ["Read", "Glob", "Grep", "Bash"],
+    disallowedTools,
+    onLine: (line) => supervisor.emitLine("supervisor", line),
+    settingSources: ["project"],
+    systemPrompt: composeSystemPrompt({
+      role: "lead",
+      profile: supervisorProfile,
+      profilesDir: resolvedProfilesDir,
+      trailer: SUPERVISOR_SYSTEM_PROMPT,
+      runtime,
+    }),
+    mcpServers: { orchestration: supervisorServer },
+    redactor,
+  });
+
+  supervisor = new Supervisor({
+    supervisorRunner,
+    agentRunner,
+    messageBus,
+    output,
+    ctx,
+    taskAmend,
+    redactor,
+  });
+  return supervisor;
+}