@forwardimpact/libeval 0.1.27 → 0.1.28

package/README.md

@@ -1,6 +1,11 @@
 # libeval
 
-Process Claude Code stream-json output into structured traces.
+<!-- BEGIN:description — Do not edit. Generated from package.json. -->
+
+Agent evaluation framework — prove whether agent changes improved outcomes with
+reproducible evidence.
+
+<!-- END:description -->
 
 ## Getting Started
 

package/bin/fit-eval.js

@@ -177,20 +177,20 @@ const definition = {
   ],
   documentation: [
     {
-      title: "Agent Evaluations",
-      url: "https://www.forwardimpact.team/docs/libraries/agent-evaluations/index.md",
+      title: "Run an Eval",
+      url: "https://www.forwardimpact.team/docs/libraries/prove-changes/run-eval/index.md",
       description:
         "Author a judge profile, run an eval locally, wire it into CI, and inspect the resulting trace.",
     },
     {
-      title: "Agent Collaboration",
-      url: "https://www.forwardimpact.team/docs/libraries/agent-collaboration/index.md",
+      title: "Prove Agent Changes",
+      url: "https://www.forwardimpact.team/docs/libraries/prove-changes/index.md",
       description:
-        "Author a facilitator and participant profiles, run a multi-agent session, and read the message flow.",
+        "End-to-end workflow from dataset generation through evaluation to trace analysis, including multi-agent collaboration sessions.",
     },
     {
-      title: "Trace Analysis",
-      url: "https://www.forwardimpact.team/docs/libraries/trace-analysis/index.md",
+      title: "Analyze Traces",
+      url: "https://www.forwardimpact.team/docs/libraries/prove-changes/trace-analysis/index.md",
       description:
         "Read the NDJSON traces produced by `fit-eval` with `fit-trace` — grounded-theory method and worked examples.",
     },

package/bin/fit-trace.js

@@ -214,22 +214,22 @@ const definition = {
   ],
   documentation: [
     {
-      title: "Trace Analysis",
-      url: "https://www.forwardimpact.team/docs/libraries/trace-analysis/index.md",
+      title: "Analyze Traces",
+      url: "https://www.forwardimpact.team/docs/libraries/prove-changes/trace-analysis/index.md",
       description:
         "The full method walkthrough with worked examples (an eval that failed, a multi-agent session that stalled).",
     },
     {
-      title: "Agent Evaluations",
-      url: "https://www.forwardimpact.team/docs/libraries/agent-evaluations/index.md",
+      title: "Run an Eval",
+      url: "https://www.forwardimpact.team/docs/libraries/prove-changes/run-eval/index.md",
       description:
         "How `fit-eval supervise` produces the traces this skill analyzes.",
     },
     {
-      title: "Agent Collaboration",
-      url: "https://www.forwardimpact.team/docs/libraries/agent-collaboration/index.md",
+      title: "Prove Agent Changes",
+      url: "https://www.forwardimpact.team/docs/libraries/prove-changes/index.md",
       description:
-        "How `fit-eval facilitate` produces multi-agent traces; `split` is the bridge into per-source files.",
+        "End-to-end workflow including multi-agent collaboration; `split` is the bridge into per-source trace files.",
     },
   ],
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forwardimpact/libeval",
-  "version": "0.1.27",
-  "description": "Agent evaluation: collect Claude Code traces, run agent loops, supervise multi-step workflows.",
+  "version": "0.1.28",
+  "description": "Agent evaluation framework — prove whether agent changes improved outcomes with reproducible evidence.",
   "keywords": [
     "eval",
     "agent",
@@ -17,14 +17,16 @@
   },
   "license": "Apache-2.0",
   "author": "D. Olsson <hi@senzilla.io>",
-  "forwardimpact": {
-    "capability": "agent-self-improvement",
-    "needs": [
-      "Parse and query Claude Code trace NDJSON files",
-      "Drive an LLM agent through a scripted run and capture its trace",
-      "Supervise a multi-step or multi-agent workflow"
-    ]
-  },
+  "jobs": [
+    {
+      "user": "Platform Builders",
+      "goal": "Prove Agent Changes",
+      "trigger": "An eval passes locally but fails in CI and the only output is 'assertion failed.'",
+      "bigHire": "prove whether agent changes improved outcomes with reproducible evidence.",
+      "littleHire": "run an eval and get a trace that shows exactly what the agent did.",
+      "competesWith": "manual before/after comparison; trusting gut feeling over evidence; skipping evaluation entirely"
+    }
+  ],
   "type": "module",
   "main": "./src/index.js",
   "exports": {

package/src/agent-runner.js

@@ -32,6 +32,7 @@ function applyDefaults(deps) {
   };
 }
 
+/** Run a single Claude Agent SDK session and emit raw NDJSON events to an output stream. */
 export class AgentRunner {
   /**
    * @param {object} deps

package/src/facilitator.js

@@ -36,6 +36,7 @@ export const FACILITATED_AGENT_SYSTEM_PROMPT =
   "Announce broadcasts a message. " +
   "RollCall lists participants.";
 
+/** Orchestrate N agent sessions coordinated by a single facilitator LLM session. */
 export class Facilitator {
   /**
    * @param {object} deps
@@ -296,6 +297,7 @@ export class Facilitator {
     }
   }
 
+  /** Return the last assistant text block from a runner's buffer, or the fallback if none exists. */
   extractLastText(runner, fallback) {
     const lines = runner.buffer;
     for (let i = lines.length - 1; i >= 0; i--) {

package/src/message-bus.js

@@ -12,6 +12,7 @@
  * Follows OO+DI: constructor injection, factory function, tests bypass factory.
  */
 
+/** In-memory per-participant message queues for facilitated and supervised orchestration modes. */
 export class MessageBus {
   /**
    * @param {object} deps

package/src/orchestration-toolkit.js

@@ -37,6 +37,7 @@ export function createOrchestrationContext() {
 
 // --- Handler factories ---
 
+/** Create a handler that marks the session as concluded and records the summary. */
 export function createConcludeHandler(ctx) {
   return async ({ summary }) => {
     ctx.concluded = true;
@@ -45,6 +46,7 @@ export function createConcludeHandler(ctx) {
   };
 }
 
+/** Create a handler that queues a redirect to interrupt a participant with replacement instructions. */
 export function createRedirectHandler(ctx) {
   return async ({ message, to }) => {
     ctx.redirect = { message, to: to ?? null };
@@ -52,6 +54,7 @@ export function createRedirectHandler(ctx) {
   };
 }
 
+/** Create a handler that returns the list of all session participants and their roles. */
 export function createRollCallHandler(ctx) {
   return async () => {
     return {

package/src/orchestrator-helpers.js

@@ -5,6 +5,7 @@
  * - `formatMessages`    — render a drained message batch as tagged lines.
  */
 
+/** Create a promise-based async queue for serializing event delivery to the facilitator loop. */
 export function createAsyncQueue() {
   const items = [];
   let waiter = null;

package/src/sequence-counter.js

@@ -2,16 +2,20 @@
  * 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/supervisor.js

@@ -4,8 +4,9 @@
  * introduces itself, and delegates work to the agent. The loop then alternates:
  * agent → supervisor → agent.
  *
- * Signaling uses orchestration tools (Ask / Answer / Announce / Redirect /
- * Conclude) via in-process MCP servers. The Ask/Answer contract is enforced
+ * Signaling uses orchestration tools (Ask / Announce / Redirect / Conclude)
+ * via in-process MCP servers; the supervisor has no Answer tool — agent replies
+ * are routed back through the relay loop. The Ask/Answer contract is enforced
  * at turn boundaries: an unanswered Ask triggers one synthetic reminder and
  * then a `protocol_violation` trace event plus a null-answer injection so the
  * session advances without silent deadlock.
@@ -52,6 +53,7 @@ export const AGENT_SYSTEM_PROMPT =
  */
 const MAX_INTERVENTIONS_PER_TURN = 5;
 
+/** Orchestrate a relay loop between a supervisor LLM and an agent LLM with mid-turn review. */
 export class Supervisor {
   /**
    * @param {object} deps

package/src/tee-writer.js

@@ -20,6 +20,7 @@ import { TraceCollector } from "./trace-collector.js";
 import { renderTurnLines } from "./render/turn-renderer.js";
 import { isSuppressedOrchestratorEvent } from "./render/orchestrator-filter.js";
 
+/** Writable stream that saves raw NDJSON to a file while streaming human-readable text to a display stream. */
 export class TeeWriter extends Writable {
   /**
    * @param {object} deps

package/src/trace-collector.js

@@ -12,6 +12,7 @@
 import { renderTurnLines } from "./render/turn-renderer.js";
 import { isSuppressedOrchestratorEvent } from "./render/orchestrator-filter.js";
 
+/** Accumulate Claude Code NDJSON stream events into structured traces for analysis or text replay. */
 export class TraceCollector {
   /**
    * @param {object} [deps]