@forwardimpact/libeval 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Dick Olsson
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/bin/fit-eval.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import { runOutputCommand } from "../src/commands/output.js";
+import { runTeeCommand } from "../src/commands/tee.js";
+
+const COMMANDS = {
+  output: runOutputCommand,
+  tee: runTeeCommand,
+};
+
+const HELP_TEXT = `
+Eval CLI — Process Claude Code stream-json output
+
+Usage:
+  fit-eval <command> [options]
+
+Commands:
+  output [--format=json|text]    Process trace and output formatted result
+  tee [output.ndjson]            Stream text to stdout, optionally save raw NDJSON
+
+Options:
+  --help      Show this help message
+  --version   Show version number
+
+Examples:
+  fit-eval output --format=text < trace.ndjson
+  fit-eval output --format=json < trace.ndjson
+  fit-eval tee < trace.ndjson
+  fit-eval tee output.ndjson < trace.ndjson
+`.trim();
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+    console.log(HELP_TEXT);
+    return;
+  }
+
+  if (args.includes("--version")) {
+    const { readFileSync } = await import("fs");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, "..", "package.json"), "utf8"),
+    );
+    console.log(pkg.version);
+    return;
+  }
+
+  const commandName = args[0];
+  const handler = COMMANDS[commandName];
+
+  if (!handler) {
+    console.error(`Unknown command: ${commandName}\n`);
+    console.error(HELP_TEXT);
+    process.exit(1);
+  }
+
+  await handler(args.slice(1));
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/index.js

@@ -0,0 +1 @@
+export { TraceCollector, createTraceCollector } from "./src/trace-collector.js";

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@forwardimpact/libeval",
+  "version": "0.1.0",
+  "description": "Process Claude Code stream-json output into structured traces",
+  "license": "Apache-2.0",
+  "author": "D. Olsson <hi@senzilla.io>",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "fit-eval": "./bin/fit-eval.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands/output.js

@@ -0,0 +1,53 @@
+import { createTraceCollector } from "@forwardimpact/libeval";
+
+/**
+ * Output command — process a complete NDJSON trace from stdin and write
+ * formatted output to stdout.
+ *
+ * Usage: fit-eval output [--format=json|text] < trace.ndjson
+ *
+ * @param {string[]} args - Command arguments
+ */
+export async function runOutputCommand(args) {
+  const format = parseFormat(args);
+  const collector = createTraceCollector();
+
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const input = Buffer.concat(chunks).toString("utf8");
+
+  for (const line of input.split("\n")) {
+    collector.addLine(line);
+  }
+
+  if (format === "text") {
+    process.stdout.write(collector.toText() + "\n");
+  } else {
+    process.stdout.write(JSON.stringify(collector.toJSON()) + "\n");
+  }
+}
+
+/**
+ * Parse --format from args. Supports --format=value and --format value.
+ * @param {string[]} args
+ * @returns {"text"|"json"}
+ */
+function parseFormat(args) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("--format=")) {
+      const value = args[i].slice("--format=".length);
+      if (value === "text" || value === "json") return value;
+      console.error(`Unknown format: ${value}. Using "json".`);
+      return "json";
+    }
+    if (args[i] === "--format" && i + 1 < args.length) {
+      const value = args[i + 1];
+      if (value === "text" || value === "json") return value;
+      console.error(`Unknown format: ${value}. Using "json".`);
+      return "json";
+    }
+  }
+  return "json";
+}

package/src/commands/tee.js

@@ -0,0 +1,99 @@
+import { createWriteStream } from "fs";
+import { createTraceCollector } from "@forwardimpact/libeval";
+
+/**
+ * Tee command — stream text output to stdout while optionally saving the raw
+ * NDJSON to a file. Processes stdin line-by-line for streaming output.
+ *
+ * Usage: fit-eval tee [output.ndjson] < trace.ndjson
+ *
+ * @param {string[]} args - Command arguments (optional output file path)
+ */
+export async function runTeeCommand(args) {
+  const outputPath = args.find((a) => !a.startsWith("-")) ?? null;
+  const fileStream = outputPath ? createWriteStream(outputPath) : null;
+  const collector = createTraceCollector();
+  const turnsEmitted = { count: 0 };
+
+  try {
+    let buffer = "";
+
+    for await (const chunk of process.stdin) {
+      buffer += chunk.toString("utf8");
+
+      let newlineIdx;
+      while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, newlineIdx);
+        buffer = buffer.slice(newlineIdx + 1);
+
+        if (fileStream) {
+          fileStream.write(line + "\n");
+        }
+
+        collector.addLine(line);
+        flushNewTurns(collector, turnsEmitted);
+      }
+    }
+
+    // Process any remaining data without a trailing newline
+    if (buffer.trim()) {
+      if (fileStream) {
+        fileStream.write(buffer + "\n");
+      }
+      collector.addLine(buffer);
+      flushNewTurns(collector, turnsEmitted);
+    }
+
+    // Emit the result summary at the end
+    if (collector.result) {
+      const text = collector.toText();
+      const lastNewline = text.lastIndexOf("\n---");
+      if (lastNewline !== -1) {
+        process.stdout.write(text.slice(lastNewline) + "\n");
+      }
+    }
+  } finally {
+    if (fileStream) {
+      await new Promise((resolve, reject) => {
+        fileStream.end(() => resolve());
+        fileStream.on("error", reject);
+      });
+    }
+  }
+}
+
+/**
+ * Write text for any new turns that haven't been emitted yet.
+ * @param {import("@forwardimpact/libeval").TraceCollector} collector
+ * @param {{ count: number }} turnsEmitted
+ */
+function flushNewTurns(collector, turnsEmitted) {
+  const turns = collector.turns;
+  while (turnsEmitted.count < turns.length) {
+    const turn = turns[turnsEmitted.count];
+    turnsEmitted.count++;
+
+    if (turn.role === "assistant") {
+      for (const block of turn.content) {
+        if (block.type === "text") {
+          process.stdout.write(block.text + "\n");
+        } else if (block.type === "tool_use") {
+          const inputSummary = summarizeInput(block.input);
+          process.stdout.write(`> Tool: ${block.name} ${inputSummary}\n`);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Summarize tool input for text display, truncated to keep logs readable.
+ * @param {object} input - Tool input object
+ * @returns {string} Truncated summary
+ */
+function summarizeInput(input) {
+  if (!input || typeof input !== "object") return "";
+  const json = JSON.stringify(input);
+  if (json.length <= 200) return json;
+  return json.slice(0, 197) + "...";
+}

package/src/trace-collector.js

@@ -0,0 +1,259 @@
+/**
+ * Collects Claude Code stream-json NDJSON events into structured traces.
+ *
+ * Accepts one NDJSON line at a time via addLine(), then produces either a
+ * structured JSON trace (toJSON) or human-readable text (toText).
+ */
+export class TraceCollector {
+  /**
+   * @param {object} [deps]
+   * @param {function} [deps.now] - Returns ISO timestamp string. Defaults to () => new Date().toISOString()
+   */
+  constructor(deps = {}) {
+    /** @type {function} */
+    this.now = deps.now ?? (() => new Date().toISOString());
+    /** @type {object|null} */
+    this.metadata = null;
+    /** @type {Array<object>} */
+    this.turns = [];
+    /** @type {object|null} */
+    this.result = null;
+    /** @type {number} */
+    this.turnIndex = 0;
+  }
+
+  /**
+   * Parse one NDJSON line and accumulate state.
+   * Malformed lines are silently skipped.
+   * @param {string} line - A single JSON line from stream-json output
+   */
+  addLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let event;
+    try {
+      event = JSON.parse(trimmed);
+    } catch {
+      return;
+    }
+
+    switch (event.type) {
+      case "system":
+        this.handleSystem(event);
+        break;
+      case "assistant":
+        this.handleAssistant(event);
+        break;
+      case "user":
+        this.handleUser(event);
+        break;
+      case "result":
+        this.handleResult(event);
+        break;
+      default:
+        break;
+    }
+  }
+
+  /**
+   * @param {object} event
+   */
+  handleSystem(event) {
+    if (event.subtype === "init") {
+      this.metadata = {
+        timestamp: event.timestamp ?? this.now(),
+        sessionId: event.session_id ?? null,
+        model: event.model ?? null,
+        claudeCodeVersion: event.claude_code_version ?? null,
+        tools: event.tools ?? [],
+        permissionMode: event.permissionMode ?? null,
+      };
+    }
+  }
+
+  /**
+   * @param {object} event
+   */
+  handleAssistant(event) {
+    const message = event.message;
+    if (!message) return;
+
+    const content = (message.content ?? []).map((block) => {
+      if (block.type === "text") {
+        return { type: "text", text: block.text };
+      }
+      if (block.type === "tool_use") {
+        return {
+          type: "tool_use",
+          toolUseId: block.id ?? null,
+          name: block.name,
+          input: block.input,
+        };
+      }
+      return block;
+    });
+
+    const usage = message.usage
+      ? {
+          inputTokens: message.usage.input_tokens ?? 0,
+          outputTokens: message.usage.output_tokens ?? 0,
+          cacheReadInputTokens: message.usage.cache_read_input_tokens ?? 0,
+          cacheCreationInputTokens:
+            message.usage.cache_creation_input_tokens ?? 0,
+        }
+      : null;
+
+    this.turns.push({
+      index: this.turnIndex++,
+      role: "assistant",
+      content,
+      usage,
+    });
+  }
+
+  /**
+   * @param {object} event
+   */
+  handleUser(event) {
+    const message = event.message;
+    if (!message) return;
+
+    const contentItems = message.content;
+    if (!Array.isArray(contentItems)) return;
+
+    for (const item of contentItems) {
+      if (item.type === "tool_result") {
+        this.turns.push({
+          index: this.turnIndex++,
+          role: "tool_result",
+          toolUseId: item.tool_use_id ?? null,
+          content:
+            typeof item.content === "string"
+              ? item.content
+              : JSON.stringify(item.content),
+          isError: item.is_error ?? false,
+        });
+      }
+    }
+  }
+
+  /**
+   * @param {object} event
+   */
+  handleResult(event) {
+    this.result = {
+      result: event.subtype ?? "unknown",
+      isError: event.is_error ?? false,
+      totalCostUsd: event.total_cost_usd ?? 0,
+      durationMs: event.duration_ms ?? 0,
+      numTurns: event.num_turns ?? 0,
+      tokenUsage: event.usage
+        ? {
+            inputTokens: event.usage.input_tokens ?? 0,
+            outputTokens: event.usage.output_tokens ?? 0,
+            cacheReadInputTokens: event.usage.cache_read_input_tokens ?? 0,
+            cacheCreationInputTokens:
+              event.usage.cache_creation_input_tokens ?? 0,
+          }
+        : null,
+      modelUsage: event.modelUsage ?? null,
+    };
+  }
+
+  /**
+   * Return a structured trace object for offline analysis.
+   * @returns {object} Structured trace document
+   */
+  toJSON() {
+    return {
+      version: "1.0.0",
+      metadata: this.metadata ?? {
+        timestamp: this.now(),
+        sessionId: null,
+        model: null,
+        claudeCodeVersion: null,
+        tools: [],
+        permissionMode: null,
+      },
+      turns: this.turns,
+      summary: this.result ?? {
+        result: "unknown",
+        isError: false,
+        totalCostUsd: 0,
+        durationMs: 0,
+        numTurns: 0,
+        tokenUsage: null,
+        modelUsage: null,
+      },
+    };
+  }
+
+  /**
+   * Return human-readable text for workflow logs.
+   * @returns {string} Formatted text output
+   */
+  toText() {
+    const lines = [];
+
+    for (const turn of this.turns) {
+      if (turn.role === "assistant") {
+        for (const block of turn.content) {
+          if (block.type === "text") {
+            lines.push(block.text);
+          } else if (block.type === "tool_use") {
+            const inputSummary = summarizeInput(block.input);
+            lines.push(`> Tool: ${block.name} ${inputSummary}`);
+          }
+        }
+      }
+    }
+
+    if (this.result) {
+      const duration = formatDuration(this.result.durationMs);
+      const cost = Number(this.result.totalCostUsd).toFixed(4);
+      lines.push("");
+      lines.push(
+        `--- Result: ${this.result.result} | Turns: ${this.result.numTurns} | Cost: $${cost} | Duration: ${duration} ---`,
+      );
+    }
+
+    return lines.join("\n");
+  }
+}
+
+/**
+ * Summarize tool input for text display, truncated to keep logs readable.
+ * @param {object} input - Tool input object
+ * @returns {string} Truncated summary
+ */
+function summarizeInput(input) {
+  if (!input || typeof input !== "object") return "";
+  const json = JSON.stringify(input);
+  if (json.length <= 200) return json;
+  return json.slice(0, 197) + "...";
+}
+
+/**
+ * Format milliseconds into a human-readable duration.
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string} Formatted duration
+ */
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = Math.round(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  return `${minutes}m ${remainingSeconds}s`;
+}
+
+/**
+ * Factory function for TraceCollector.
+ * @param {object} [deps]
+ * @param {function} [deps.now] - Returns ISO timestamp string
+ * @returns {TraceCollector}
+ */
+export function createTraceCollector(deps) {
+  return new TraceCollector(deps);
+}

package/test/fixtures/stream.ndjson

@@ -0,0 +1,7 @@
+{"type":"system","subtype":"init","cwd":"/home/user/monorepo","session_id":"abc-123","tools":["Bash","Read","Glob","Grep","Write","Edit"],"mcp_servers":[],"model":"claude-opus-4-6","permissionMode":"default","claude_code_version":"2.1.87","uuid":"evt-1"}
+{"type":"assistant","message":{"model":"claude-opus-4-6","id":"msg_01","type":"message","role":"assistant","content":[{"type":"text","text":"I'll start by checking the repository structure."}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":100,"cache_creation_input_tokens":500,"cache_read_input_tokens":200,"output_tokens":15,"service_tier":"standard"}},"session_id":"abc-123","uuid":"evt-2"}
+{"type":"assistant","message":{"model":"claude-opus-4-6","id":"msg_01","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01","name":"Bash","input":{"command":"ls -la"}}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":100,"cache_creation_input_tokens":500,"cache_read_input_tokens":200,"output_tokens":15,"service_tier":"standard"}},"session_id":"abc-123","uuid":"evt-3"}
+{"type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01","type":"tool_result","content":"total 42\ndrwxr-xr-x  5 user user 4096 Mar 29 12:00 .\ndrwxr-xr-x  3 user user 4096 Mar 29 12:00 .."}]},"uuid":"evt-4","session_id":"abc-123"}
+{"type":"assistant","message":{"model":"claude-opus-4-6","id":"msg_02","type":"message","role":"assistant","content":[{"type":"text","text":"The repository looks good. No security issues found."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":150,"cache_creation_input_tokens":0,"cache_read_input_tokens":700,"output_tokens":12,"service_tier":"standard"}},"session_id":"abc-123","uuid":"evt-5"}
+{"type":"rate_limit_event","rate_limit_info":{"status":"allowed"},"uuid":"evt-6","session_id":"abc-123"}
+{"type":"result","subtype":"success","is_error":false,"duration_ms":5200,"duration_api_ms":4800,"num_turns":3,"result":"The repository looks good. No security issues found.","stop_reason":"end_turn","session_id":"abc-123","total_cost_usd":0.0523,"usage":{"input_tokens":350,"cache_creation_input_tokens":500,"cache_read_input_tokens":900,"output_tokens":42,"service_tier":"standard"},"modelUsage":{"claude-opus-4-6":{"inputTokens":350,"outputTokens":42,"cacheReadInputTokens":900,"cacheCreationInputTokens":500,"costUSD":0.0523}},"uuid":"evt-7"}

package/test/trace-collector.test.js

@@ -0,0 +1,328 @@
+import { describe, test } from "node:test";
+import assert from "node:assert";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { TraceCollector, createTraceCollector } from "@forwardimpact/libeval";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fixturePath = path.join(__dirname, "fixtures", "stream.ndjson");
+
+/**
+ * Load fixture lines from the NDJSON file.
+ * @returns {string[]}
+ */
+function loadFixture() {
+  return fs.readFileSync(fixturePath, "utf8").trim().split("\n");
+}
+
+/**
+ * Feed all fixture lines into a collector and return it.
+ * @returns {TraceCollector}
+ */
+function collectFixture() {
+  const collector = new TraceCollector();
+  for (const line of loadFixture()) {
+    collector.addLine(line);
+  }
+  return collector;
+}
+
+describe("TraceCollector", () => {
+  describe("addLine", () => {
+    test("extracts metadata from system init event", () => {
+      const collector = new TraceCollector();
+      collector.addLine(
+        JSON.stringify({
+          type: "system",
+          subtype: "init",
+          session_id: "sess-1",
+          model: "claude-opus-4-6",
+          claude_code_version: "2.1.87",
+          tools: ["Bash", "Read"],
+          permissionMode: "default",
+        }),
+      );
+
+      const trace = collector.toJSON();
+      assert.strictEqual(trace.metadata.sessionId, "sess-1");
+      assert.strictEqual(trace.metadata.model, "claude-opus-4-6");
+      assert.strictEqual(trace.metadata.claudeCodeVersion, "2.1.87");
+      assert.deepStrictEqual(trace.metadata.tools, ["Bash", "Read"]);
+    });
+
+    test("collects assistant text turns", () => {
+      const collector = new TraceCollector();
+      collector.addLine(
+        JSON.stringify({
+          type: "assistant",
+          message: {
+            content: [{ type: "text", text: "Hello world" }],
+            usage: { input_tokens: 10, output_tokens: 5 },
+          },
+        }),
+      );
+
+      const trace = collector.toJSON();
+      assert.strictEqual(trace.turns.length, 1);
+      assert.strictEqual(trace.turns[0].role, "assistant");
+      assert.strictEqual(trace.turns[0].content[0].text, "Hello world");
+      assert.strictEqual(trace.turns[0].usage.inputTokens, 10);
+    });
+
+    test("collects assistant tool_use turns", () => {
+      const collector = new TraceCollector();
+      collector.addLine(
+        JSON.stringify({
+          type: "assistant",
+          message: {
+            content: [
+              {
+                type: "tool_use",
+                id: "toolu_01",
+                name: "Bash",
+                input: { command: "ls" },
+              },
+            ],
+            usage: { input_tokens: 20, output_tokens: 10 },
+          },
+        }),
+      );
+
+      const trace = collector.toJSON();
+      assert.strictEqual(trace.turns[0].content[0].type, "tool_use");
+      assert.strictEqual(trace.turns[0].content[0].name, "Bash");
+      assert.strictEqual(trace.turns[0].content[0].toolUseId, "toolu_01");
+    });
+
+    test("collects tool_result from user events", () => {
+      const collector = new TraceCollector();
+      collector.addLine(
+        JSON.stringify({
+          type: "user",
+          message: {
+            role: "user",
+            content: [
+              {
+                type: "tool_result",
+                tool_use_id: "toolu_01",
+                content: "file listing output",
+              },
+            ],
+          },
+        }),
+      );
+
+      const trace = collector.toJSON();
+      assert.strictEqual(trace.turns.length, 1);
+      assert.strictEqual(trace.turns[0].role, "tool_result");
+      assert.strictEqual(trace.turns[0].toolUseId, "toolu_01");
+      assert.strictEqual(trace.turns[0].content, "file listing output");
+    });
+
+    test("extracts summary from result event", () => {
+      const collector = new TraceCollector();
+      collector.addLine(
+        JSON.stringify({
+          type: "result",
+          subtype: "success",
+          is_error: false,
+          total_cost_usd: 1.23,
+          duration_ms: 45000,
+          num_turns: 12,
+          usage: {
+            input_tokens: 5000,
+            output_tokens: 2000,
+            cache_read_input_tokens: 3000,
+            cache_creation_input_tokens: 1000,
+          },
+          modelUsage: { "claude-opus-4-6": { costUSD: 1.23 } },
+        }),
+      );
+
+      const trace = collector.toJSON();
+      assert.strictEqual(trace.summary.result, "success");
+      assert.strictEqual(trace.summary.totalCostUsd, 1.23);
+      assert.strictEqual(trace.summary.durationMs, 45000);
+      assert.strictEqual(trace.summary.numTurns, 12);
+      assert.strictEqual(trace.summary.tokenUsage.inputTokens, 5000);
+    });
+
+    test("skips rate_limit_event and unknown types", () => {
+      const collector = new TraceCollector();
+      collector.addLine(
+        JSON.stringify({ type: "rate_limit_event", rate_limit_info: {} }),
+      );
+      collector.addLine(JSON.stringify({ type: "unknown_event" }));
+
+      const trace = collector.toJSON();
+      assert.strictEqual(trace.turns.length, 0);
+    });
+
+    test("skips malformed JSON lines", () => {
+      const collector = new TraceCollector();
+      collector.addLine("not valid json {{{");
+      collector.addLine("");
+      collector.addLine("   ");
+
+      const trace = collector.toJSON();
+      assert.strictEqual(trace.turns.length, 0);
+    });
+
+    test("skips assistant event with missing message", () => {
+      const collector = new TraceCollector();
+      collector.addLine(JSON.stringify({ type: "assistant" }));
+      collector.addLine(JSON.stringify({ type: "assistant", message: null }));
+
+      assert.strictEqual(collector.toJSON().turns.length, 0);
+    });
+
+    test("skips user event with non-array content", () => {
+      const collector = new TraceCollector();
+      collector.addLine(
+        JSON.stringify({
+          type: "user",
+          message: { role: "user", content: "plain string" },
+        }),
+      );
+      collector.addLine(
+        JSON.stringify({ type: "user", message: { role: "user" } }),
+      );
+      collector.addLine(JSON.stringify({ type: "user" }));
+
+      assert.strictEqual(collector.toJSON().turns.length, 0);
+    });
+
+    test("uses event timestamp when present in system init", () => {
+      const collector = new TraceCollector();
+      collector.addLine(
+        JSON.stringify({
+          type: "system",
+          subtype: "init",
+          timestamp: "2026-01-15T10:00:00Z",
+          session_id: "sess-ts",
+        }),
+      );
+
+      assert.strictEqual(
+        collector.toJSON().metadata.timestamp,
+        "2026-01-15T10:00:00Z",
+      );
+    });
+  });
+
+  describe("toJSON", () => {
+    test("produces complete trace from fixture", () => {
+      const collector = collectFixture();
+      const trace = collector.toJSON();
+
+      assert.strictEqual(trace.version, "1.0.0");
+      assert.strictEqual(trace.metadata.sessionId, "abc-123");
+      assert.strictEqual(trace.metadata.model, "claude-opus-4-6");
+      assert.strictEqual(trace.metadata.claudeCodeVersion, "2.1.87");
+      assert.strictEqual(trace.metadata.tools.length, 6);
+      assert.ok(trace.turns.length > 0);
+      assert.strictEqual(trace.summary.result, "success");
+      assert.strictEqual(trace.summary.totalCostUsd, 0.0523);
+      assert.strictEqual(trace.summary.numTurns, 3);
+    });
+
+    test("assigns sequential turn indexes", () => {
+      const collector = collectFixture();
+      const trace = collector.toJSON();
+
+      trace.turns.forEach((turn, i) => {
+        assert.strictEqual(turn.index, i);
+      });
+    });
+
+    test("returns defaults for empty input", () => {
+      const collector = new TraceCollector();
+      const trace = collector.toJSON();
+
+      assert.strictEqual(trace.version, "1.0.0");
+      assert.strictEqual(trace.metadata.sessionId, null);
+      assert.strictEqual(trace.turns.length, 0);
+      assert.strictEqual(trace.summary.result, "unknown");
+    });
+  });
+
+  describe("toText", () => {
+    test("includes assistant text content", () => {
+      const collector = collectFixture();
+      const text = collector.toText();
+
+      assert.ok(
+        text.includes("I'll start by checking the repository structure"),
+      );
+      assert.ok(text.includes("No security issues found"));
+    });
+
+    test("includes tool call summaries", () => {
+      const collector = collectFixture();
+      const text = collector.toText();
+
+      assert.ok(text.includes("> Tool: Bash"));
+      assert.ok(text.includes("ls -la"));
+    });
+
+    test("includes result summary line", () => {
+      const collector = collectFixture();
+      const text = collector.toText();
+
+      assert.ok(text.includes("--- Result: success"));
+      assert.ok(text.includes("Turns: 3"));
+      assert.ok(text.includes("Cost: $0.0523"));
+      assert.ok(text.includes("Duration: 5s"));
+    });
+
+    test("truncates long tool input summaries", () => {
+      const collector = new TraceCollector();
+      const longCommand = "x".repeat(300);
+      collector.addLine(
+        JSON.stringify({
+          type: "assistant",
+          message: {
+            content: [
+              {
+                type: "tool_use",
+                name: "Bash",
+                input: { command: longCommand },
+              },
+            ],
+          },
+        }),
+      );
+
+      const text = collector.toText();
+      assert.ok(text.includes("> Tool: Bash"));
+      assert.ok(text.includes("..."));
+      // Total line should be truncated, not the full 300+ chars
+      const toolLine = text.split("\n").find((l) => l.startsWith("> Tool:"));
+      assert.ok(toolLine.length < 250);
+    });
+
+    test("returns empty string for empty input", () => {
+      const collector = new TraceCollector();
+      const text = collector.toText();
+
+      assert.strictEqual(text, "");
+    });
+  });
+
+  describe("createTraceCollector", () => {
+    test("returns a TraceCollector instance", () => {
+      const collector = createTraceCollector();
+      assert.ok(collector instanceof TraceCollector);
+    });
+
+    test("accepts injectable clock for deterministic timestamps", () => {
+      const fixedTime = "2026-01-01T00:00:00Z";
+      const collector = createTraceCollector({ now: () => fixedTime });
+      const trace = collector.toJSON();
+
+      assert.strictEqual(trace.metadata.timestamp, fixedTime);
+    });
+  });
+});