@forwardimpact/libharness 2.0.0 → 3.0.1

package/src/trace-query.js

@@ -9,11 +9,11 @@ import {
 } from "./trace-usage.js";
 
 /**
- * Query engine for structured trace documents produced by TraceCollector.
+ * Query engine for structured trace documents that TraceCollector produces.
  *
- * Loads a structured JSON trace into memory and provides methods for
- * paging, searching, filtering, and summarizing turns — the operations
- * agents need to analyze large traces efficiently.
+ * Loads a structured JSON trace into memory. Provides methods to page,
+ * search, filter, and summarize turns. Agents need these operations to
+ * analyze large traces efficiently.
  */
 export class TraceQuery {
   /**
@@ -54,7 +54,7 @@ export class TraceQuery {
   }
 
   /**
-   * Full system/init event — the single most diagnostic message for
+   * Full system/init event. It is the single most diagnostic message for
    * root-cause analysis. Returns null for traces collected before this
    * field existed.
    * @returns {object|null}
@@ -73,16 +73,16 @@ export class TraceQuery {
   }
 
   /**
-   * Filter turns by composable structural criteria. All criteria are
-   * combined as AND. `tool()` and `errors()` remain as convenience
-   * shortcuts for pre-existing workflows.
+   * Filter turns by composable structural criteria. The filter combines all
+   * criteria as AND. `tool()` and `errors()` remain as convenience
+   * shortcuts for workflows that already exist.
    *
-   * `toolName` matches assistant turns only. Applying `toolName` without
-   * `role: "assistant"` still drops every non-assistant turn, because
-   * resolving tool_use → tool_result pairs requires the `tool()` method.
-   * `isError` matches tool_result turns only. Combining `toolName` with
-   * `isError` therefore always returns `[]` (no turn is both assistant
-   * and tool_result) — use `tool(name)` for "errors from Bash"–shaped
+   * `toolName` matches assistant turns only. `toolName` without
+   * `role: "assistant"` still drops every non-assistant turn, because only
+   * the `tool()` method resolves tool_use → tool_result pairs.
+   * `isError` matches tool_result turns only. So `toolName` with
+   * `isError` always returns `[]`. No turn is both assistant and
+   * tool_result. Use `tool(name)` for "errors from Bash"–shaped
    * queries.
    *
    * @param {object} [opts]
@@ -138,15 +138,16 @@ export class TraceQuery {
   }
 
   /**
-   * Search all turn content for a regex pattern.  Returns matching turns
-   * with the matched text highlighted by context.
+   * Search all turn content for a regex pattern. Returns the turns that
+   * match and highlights the matched text with context.
    *
    * Searches: assistant text blocks, tool_use names and stringified input,
    * and tool_result content.
    *
    * @param {string} pattern - Regex pattern (case-insensitive)
    * @param {object} [opts]
-   * @param {number} [opts.context=0] - Number of surrounding turns to include
+   * @param {number} [opts.context=0] - Number of turns to include around the
+   *   match
    * @param {number} [opts.limit=50] - Max results
    * @param {boolean} [opts.full=false] - Emit full content block text in
    *   match descriptions instead of the default narrow excerpt window.
@@ -197,7 +198,8 @@ export class TraceQuery {
   }
 
   /**
-   * Filter turns involving a specific tool (both the tool_use and its result).
+   * Filter turns that involve a specific tool (both the tool_use and its
+   * result).
    * @param {string} name - Tool name
    * @returns {object[]}
    */
@@ -251,9 +253,9 @@ export class TraceQuery {
   }
 
   /**
-   * Compact one-line-per-assistant-turn timeline showing tool names,
-   * reasoning snippet, and token usage.  Thinking-only turns are marked
-   * as such and their content is omitted (it is model-internal).
+   * Compact one-line-per-assistant-turn timeline with tool names,
+   * reasoning snippet, and token usage. The timeline marks thinking-only
+   * turns as such. It omits their content (the content is model-internal).
    * @returns {string[]}
    */
   timeline() {
@@ -296,16 +298,18 @@ export class TraceQuery {
    * totals that name their population.
    *
    * A structured document collected before this change (version < 1.2.0)
-   * carries no message identity, so it reports its carried last-wins summary
-   * labeled as such — corrected figures come from re-running the NDJSON source.
+   * carries no message identity. It reports its carried last-wins summary
+   * and labels it as such. To get corrected figures, run the NDJSON source
+   * again.
    *
-   * Otherwise: when the trace carries result events, totals are the SDK's
-   * accumulated result-event sums (authoritative); the per-message sums are
-   * compared against them and any divergence on input/cacheRead/cacheCreation
-   * is surfaced, never silently absorbed. A trace with no result event
-   * (truncated or in-flight) falls back to the per-message sums, with output
-   * flagged as a streaming-snapshot lower bound and cost/duration/turns
-   * reported as unavailable rather than a silent 0.
+   * Otherwise, when the trace carries result events, the totals are the SDK's
+   * accumulated result-event sums (authoritative). The method compares the
+   * per-message sums against them. It surfaces any divergence on
+   * input/cacheRead/cacheCreation. It never absorbs that divergence
+   * silently. A trace with no result event (truncated or in-flight) falls
+   * back to the per-message sums. The method flags output as a
+   * streaming-snapshot lower bound. It reports cost/duration/turns as
+   * unavailable. It never reports a silent 0.
    * @returns {object}
    */
   stats() {
@@ -355,8 +359,8 @@ export class TraceQuery {
   }
 
   /**
-   * Stats for a pre-change structured document: report the carried last-wins
-   * summary and per-stream-event breakdown, each labeled, without claiming
+   * Stats for a pre-change structured document. Report the carried last-wins
+   * summary and the per-stream-event breakdown. Label each one. Do not claim
    * result-event parity (the document lacks the message identity it needs).
    * @returns {object}
    */
@@ -379,8 +383,8 @@ export class TraceQuery {
   }
 
   /**
-   * One record per `tool_use` block, each paired with its `tool_result`
-   * (joined by `toolUseId`) or `result: null` for orphaned calls.
+   * One record per `tool_use` block. Each record pairs with its `tool_result`
+   * (joined by `toolUseId`). An orphaned call gets `result: null`.
    * @returns {Array<{turnIndex: number, name: string, toolUseId: string, input: object, result: {content: *, isError: boolean}|null}>}
    */
   toolCalls() {
@@ -404,8 +408,10 @@ export class TraceQuery {
   }
 
   /**
-   * One record per `Bash` `tool_use` block, carrying its command text.
-   * @param {string} [re] - Optional regex source tested against `input.command`.
+   * One record per `Bash` `tool_use` block. Each record carries its command
+   * text.
+   * @param {string} [re] - Optional regex source to test against
+   *   `input.command`.
    * @returns {Array<{turnIndex: number, toolUseId: string, command: string}>}
    */
   commands(re) {
@@ -434,7 +440,7 @@ export class TraceQuery {
 
   /**
    * Side-by-side comparison of this trace against another peer `TraceQuery`.
-   * Identity (case name, participant) comes from the caller — the trace
+   * Identity (case name, participant) comes from the caller. The trace
    * carries no filename.
    * @param {TraceQuery} other
    * @param {{aIdentity: {caseName: string, participant: string|null}, bIdentity: {caseName: string, participant: string|null}}} identities
@@ -476,16 +482,17 @@ export class TraceQuery {
   }
 
   /**
-   * Per-tool token attribution: each `tool_use` block gets an equal share of
-   * its host turn's usage; assistant turns with no `tool_use` block contribute
-   * full usage to the `(no-tool)` bucket. Per-bucket sums are scaled onto
-   * `stats().totals` — the authoritative population (result-event sums when the
-   * trace carries them, the per-message fallback otherwise) — so the buckets
-   * answer "of the reported total, what share did each tool drive" rather than
-   * a separate per-turn re-count that drifts from the headline figure. The
-   * largest bucket absorbs the rounding residual on each axis, so the input,
-   * output, and `costShare` columns each sum to the corresponding `totals`
-   * value (and `1.0`) exactly (criterion-6 invariant).
+   * Per-tool token attribution. Each `tool_use` block gets an equal share of
+   * its host turn's usage. Assistant turns with no `tool_use` block
+   * contribute full usage to the `(no-tool)` bucket. The method scales the
+   * per-bucket sums onto `stats().totals`, the authoritative population
+   * (result-event sums when the trace carries them, the per-message fallback
+   * otherwise). So the buckets answer "of the reported total, what share did
+   * each tool drive". The method does not make a separate per-turn re-count.
+   * Such a re-count drifts from the headline figure. The largest bucket
+   * absorbs the rounding residual on each axis. So the input, output, and
+   * `costShare` columns each sum to the corresponding `totals` value (and
+   * `1.0`) exactly (criterion-6 invariant).
    * @returns {{perTool: Array<{tool: string, turns: number, inputTokens: number, outputTokens: number, costShare: number}>, totals: object}}
    */
   statsByTool() {
@@ -496,7 +503,7 @@ export class TraceQuery {
   }
 
   /**
-   * Totals-only view — `stats().totals` with no per-turn array.
+   * Totals-only view. Returns `stats().totals` with no per-turn array.
    * @returns {{totals: object}}
    */
   statsSummary() {
@@ -537,9 +544,10 @@ function matchesToolName(turn, toolName) {
 }
 
 /**
- * Collect every assistant `tool_use` block keyed by `toolUseId`, optionally
- * filtered by tool name. The shared join-key source feeding `toolCalls()`,
- * `commands()`, and `collectToolUseIds()`. Insertion order follows turn order.
+ * Collect every assistant `tool_use` block and key each one by `toolUseId`.
+ * Filter by tool name when the caller supplies a name. This is the shared
+ * join-key source for `toolCalls()`, `commands()`, and
+ * `collectToolUseIds()`. Insertion order follows turn order.
  * @param {object[]} turns
  * @param {string} [name] - Optional tool-name filter.
  * @returns {Map<string, {turnIndex: number, name: string, input: object}>}
@@ -633,7 +641,8 @@ function sideSummary(
 }
 
 /**
- * Search a single turn for regex matches. Returns array of match descriptions.
+ * Search a single turn for regex matches. Returns an array of match
+ * descriptions.
  * @param {object} turn
  * @param {RegExp} re
  * @param {boolean} [full=false] - Emit full block text instead of an excerpt.

package/src/trace-render.js

@@ -1,13 +1,13 @@
 /**
- * Text renderers for `fit-trace` query output.
+ * Text renderers for `gemba-trace` query output.
  *
  * One named export per renderable verb. Each renderer accepts the query result
- * plus `{multi, signatures}` and returns a string. `multi` controls
- * source-attribution prefixing (`grep -H` convention); record-per-line
- * renderers prepend `<basename>:`, block renderers emit `# <basename>` headers.
+ * plus `{multi, signatures}` and returns a string. `multi` controls the
+ * source-attribution prefix (`grep -H` convention). A record-per-line renderer
+ * prepends `<basename>:`. A block renderer emits `# <basename>` headers.
  *
- * Internal module — imported by `commands/trace.js` and tests by relative
- * path, never re-exported from `src/index.js`.
+ * This is an internal module. `commands/trace.js` and the tests import it by
+ * relative path. `src/index.js` never re-exports it.
  */
 
 /** Collapse newlines/tabs in a value to a single-line, grep-friendly string. */
@@ -16,7 +16,7 @@ function oneLine(value) {
   return str.replace(/[\r\n\t]+/g, " ").trim();
 }
 
-/** Group records by their `source` field (multi-file path), preserving order. */
+/** Group records by their `source` field (multi-file path). Keep the order. */
 function groupBySource(records) {
   const groups = new Map();
   for (const record of records) {
@@ -28,8 +28,8 @@ function groupBySource(records) {
 }
 
 /**
- * Render record-per-line output, prefixing each line with `<source>:` when
- * multi-file. `lineOf` maps one record to its text line.
+ * Render record-per-line output. Prefix each line with `<source>:` when
+ * `multi` is true. `lineOf` maps one record to its text line.
  * @param {object[]} records
  * @param {(record: object) => string} lineOf
  * @param {{multi: boolean}} opts
@@ -42,8 +42,8 @@ function renderLines(records, lineOf, { multi }) {
 }
 
 /**
- * Render a block per source. `blockOf` maps one record to a multi-line string;
- * multi-file output separates groups with `# <source>` headers.
+ * Render a block per source. `blockOf` maps one record to a multi-line
+ * string. Multi-file output separates groups with `# <source>` headers.
  * @param {object[]} records
  * @param {(record: object) => string} blockOf
  * @param {{multi: boolean}} opts
@@ -167,11 +167,11 @@ function multiPrefix(record, { multi }) {
 }
 
 /**
- * Default renderer for every other renderable verb: one record per block,
- * fields rendered as `key: value` lines (no JSON braces or quotes, so the
- * default output is grep/awk-friendly and does not parse as JSON). Nested
- * values are collapsed to a single grep-friendly line. Multi-file output
- * separates source groups with `# <source>` headers (`renderBlocks`
+ * Default renderer for every other renderable verb. It emits one record per
+ * block. It renders the fields as `key: value` lines. The output has no JSON
+ * braces or quotes, so it is grep/awk-friendly and does not parse as JSON.
+ * It collapses nested values to a single grep-friendly line. Multi-file
+ * output separates source groups with `# <source>` headers (`renderBlocks`
  * convention).
  * @param {object[]|object} result
  * @param {{multi: boolean}} opts
@@ -183,8 +183,8 @@ export function renderDefault(result, opts = {}) {
 }
 
 /**
- * Render one record as `key: value` lines. Scalars render verbatim; objects
- * and arrays collapse to a single line via `oneLine`. A non-object record
+ * Render one record as `key: value` lines. Scalars render verbatim. Objects
+ * and arrays collapse to a single line through `oneLine`. A non-object record
  * (string/number) renders as its own single line.
  * @param {*} record
  * @returns {string}
@@ -201,7 +201,7 @@ function recordBlock(record) {
     .join("\n");
 }
 
-/** Drop the orchestrator-injected `source` field before textifying. */
+/** Drop the orchestrator-injected `source` field before text output. */
 function stripSource(record) {
   if (record == null || typeof record !== "object" || Array.isArray(record)) {
     return record;

package/src/trace-usage.js

@@ -1,11 +1,12 @@
 /**
  * Token-usage accounting for structured trace documents.
  *
- * `stats()` reports totals that name their population: result-event sums when
- * the trace carries them (authoritative), the per-message fallback otherwise,
- * or the carried last-wins summary for a pre-change document. These helpers
- * compute the per-message accounting and surface any divergence against the
- * result-event sums so a mismatch is reported, never silently absorbed.
+ * `stats()` reports totals that name their population. It reports the
+ * result-event sums when the trace carries them (authoritative). It falls
+ * back to the per-message totals otherwise. For a pre-change document it
+ * reports the carried last-wins summary. These helpers compute the
+ * per-message accounting. They also report any divergence against the
+ * result-event sums. No mismatch disappears in silence.
  */
 
 /** Zero-valued token usage, used as the carried-document fallback. */
@@ -17,8 +18,8 @@ export const ZERO_USAGE = {
 };
 
 /**
- * Per-stream-event breakdown for a pre-change document, labeled as carried —
- * old documents lack message identity, so rows stay keyed by turn index.
+ * Per-stream-event breakdown for a pre-change document, labeled as carried.
+ * Old documents lack message identity, so rows stay keyed by turn index.
  * @param {object[]} turns
  * @returns {object[]}
  */
@@ -40,8 +41,9 @@ export function carriedPerTurn(turns) {
 
 /**
  * Whether a structured-document version predates per-message accounting
- * (1.2.0). A trace with no version (collected by this build from NDJSON) is
- * not pre-change. Compares numeric version parts so 1.10.0 reads as post-change.
+ * (1.2.0). A trace with no version is not pre-change. This build collects
+ * those traces from NDJSON. Compares numeric version parts so 1.10.0 reads
+ * as post-change.
  * @param {string|undefined|null} version
  * @returns {boolean}
  */
@@ -51,17 +53,17 @@ export function isPreChangeDoc(version) {
     .split(".")
     .map((part) => parseInt(part, 10) || 0);
   if (major !== 1) return major < 1;
-  // Per-message accounting arrived in 1.2.0; any 1.2.x is post-change.
+  // Per-message accounting arrived in 1.2.0. Any 1.2.x is post-change.
   return minor < 2;
 }
 
 /**
- * Account assistant usage once per API message. Turns are grouped by
- * `messageId` (a null id is its own singleton message); per message the
- * field-wise max across its snapshots is taken — order-insensitive, equal to
- * the single value when a message's duplicate snapshots are byte-identical
- * (zero residual against result-event sums), and a floor for output (the
- * largest streaming snapshot, never an overstatement).
+ * Account assistant usage once per API message. This function groups turns
+ * by `messageId`. A null id is its own singleton message. For each message
+ * it takes the field-wise max across the snapshots. The max ignores order.
+ * The max equals the single value when a message's duplicate snapshots are
+ * byte-identical (zero residual against result-event sums). For output the
+ * max is a floor. It is the largest streaming snapshot. It never overstates.
  * @param {object[]} turns
  * @returns {{perMessage: object[], totals: object}}
  */
@@ -128,10 +130,11 @@ function accumulateMessage(byMessage, key, turn) {
 }
 
 /**
- * Compare per-message sums against the result-event sums on the fields the
- * spec guarantees parity for (input, cacheRead, cacheCreation — never output,
- * which always diverges by mechanism 2). Returns the first divergent field as
- * `{field, perMessageSum, resultEventSum}`, or null when all agree.
+ * Compare per-message sums against the result-event sums. The spec
+ * guarantees parity for input, cacheRead, and cacheCreation only. Output
+ * always diverges by mechanism 2, so the comparison skips it. Returns the
+ * first divergent field as `{field, perMessageSum, resultEventSum}`, or
+ * null when all agree.
  * @param {object} perMessageTotals
  * @param {object} resultEventUsage
  * @returns {object|null}
@@ -155,9 +158,9 @@ export function computeDivergence(perMessageTotals, resultEventUsage) {
 const NO_TOOL = "(no-tool)";
 
 /**
- * Attribute per-turn usage to per-tool buckets: each `tool_use` block gets an
- * equal share of its host turn's usage; assistant turns with no `tool_use`
- * block contribute full usage to the `(no-tool)` bucket.
+ * Attribute per-turn usage to per-tool buckets. Each `tool_use` block gets
+ * an equal share of its host turn's usage. An assistant turn with no
+ * `tool_use` block contributes full usage to the `(no-tool)` bucket.
  * @param {object[]} turns
  * @returns {{buckets: Map<string, {inputTokens: number, outputTokens: number}>, bucketTurns: Map<string, Set<number>>}}
  */
@@ -192,11 +195,11 @@ export function bucketUsageByTool(turns) {
 }
 
 /**
- * Scale per-tool buckets onto the headline totals so the input, output, and
- * `costShare` columns each sum to the corresponding `totals` value (and 1.0)
- * exactly, regardless of population (result-event-sum, per-message-fallback, or
- * carried-document). The largest bucket absorbs the rounding residual on each
- * axis (criterion-6 invariant).
+ * Scale per-tool buckets onto the headline totals. The input, output, and
+ * `costShare` columns then each sum exactly to the corresponding `totals`
+ * value (and 1.0). This holds for every population (result-event-sum,
+ * per-message-fallback, or carried-document). The largest bucket absorbs
+ * the rounding residual on each axis (criterion-6 invariant).
  * @param {Map<string, {inputTokens: number, outputTokens: number}>} buckets
  * @param {Map<string, Set<number>>} bucketTurns
  * @param {object} totals

package/src/transcript-recorder.js

@@ -1,21 +1,23 @@
 /**
- * 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).
+ * TranscriptRecorder — a per-participant in-memory record of the composed
+ * system prompt, the delivered prompts, and the session messages. The
+ * recorder renders that record into the context text an advisor consult
+ * forwards. The harness constructs it only when a session runs with an
+ * advisor model. Otherwise the harness keeps no per-participant record.
+ * Session lines then 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
+ * The redaction path splits. The message tap arrives already redacted from
+ * `AgentRunner.#recordLine`. The seeded system prompt and the prompt tap
+ * are raw. The recorder redacts those two itself through 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.
+ * text. In practice it is always a
+ * `{type:"preset", preset:"claude_code", append}` object. Every recorded
+ * participant is an agent. The spec excludes leads. The function also
+ * accepts a plain string. It accepts `undefined` too.
  * @param {string|{type: string, preset?: string, append?: string}|undefined} systemPrompt
  * @returns {string|undefined}
  */
@@ -38,8 +40,8 @@ function wrapSection(tag, content) {
  *
  * @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.
+ *   composed for the participant, exactly as it goes to the runner. The
+ *   value arrives raw. The recorder redacts it at construction.
  * @param {import("./redaction.js").Redactor} deps.redactor
  * @returns {{recordPrompt: (text: string) => void, recordMessage: (line: string) => void, render: () => string}}
  */
@@ -56,25 +58,27 @@ export function createTranscriptRecorder({ systemPrompt, redactor }) {
 
   return {
     /**
-     * Record a delivered (amend-applied) prompt. Raw — redacted here.
+     * Record a delivered (amend-applied) prompt. The text arrives raw.
+     * This method redacts it.
      * @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).
+     * 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).
+     * Render the record as the advisor's context text. Blank lines join
+     * three tagged sections. Each section appears only when it is
+     * non-empty. The NDJSON lines stay verbatim. The forwarded context is
+     * uncurated by construction, because the spec excludes context-size
+     * curation.
      * @returns {string}
      */
     render() {

package/bin/fit-benchmark.js

@@ -1,44 +0,0 @@
-#!/usr/bin/env node
-
-import "@forwardimpact/libpreflight/node22";
-
-import { createCli } from "@forwardimpact/libcli";
-import { createDefaultRuntime } from "@forwardimpact/libutil/runtime";
-import { createLogger } from "@forwardimpact/libtelemetry";
-
-import { definition } from "../src/commands/benchmark-definition.js";
-
-const runtime = createDefaultRuntime();
-const logger = createLogger("benchmark", runtime);
-
-async function main() {
-  const cli = createCli(definition, {
-    runtime,
-    packageJsonUrl: new URL("../package.json", import.meta.url),
-  });
-  const parsed = cli.parse(runtime.proc.argv.slice(2));
-  if (!parsed) return runtime.proc.exit(0);
-
-  const { positionals } = parsed;
-  if (positionals.length === 0) {
-    cli.usageError("no command specified");
-    return runtime.proc.exit(2);
-  }
-
-  const command = positionals[0];
-  if (!definition.commands.some((c) => c.name === command)) {
-    cli.usageError(`unknown command "${command}"`);
-    return runtime.proc.exit(2);
-  }
-
-  const result = await cli.dispatch(parsed, { deps: { runtime } });
-  const envelope = result ?? { ok: true };
-  if (!envelope.ok && envelope.error) cli.error(envelope.error);
-  runtime.proc.exit(envelope.ok ? 0 : (envelope.code ?? 1));
-}
-
-main().catch((error) => {
-  logger.exception("main", error);
-  createCli(definition, { runtime }).error(error.message);
-  process.exit(1);
-});