@united-workforce/cli 0.3.0 → 0.5.0

package/examples/debate.yaml

@@ -0,0 +1,169 @@
+version: 1
+name: debate
+description: "Multi-role structured debate with critical thinking framework and host summary."
+
+# Shared frontmatter schema for debater roles (YAML anchor)
+x-debater-frontmatter: &debater-frontmatter
+  type: object
+  oneOf:
+    - properties:
+        $status: { const: speak }
+        argument: { type: string }
+      required: [$status, argument]
+    - properties:
+        $status: { const: conceded }
+        reason: { type: string }
+      required: [$status, reason]
+    - properties:
+        $status: { const: final }
+        closing: { type: string }
+      required: [$status, closing]
+
+roles:
+  proponent:
+    description: "Argues FOR the proposition"
+    goal: "Build a compelling case for the proposition through logical reasoning and evidence"
+    capabilities: []
+    procedure: |
+      You are an experienced scholar arguing FOR the proposition.
+
+      ## Critical Thinking Framework (execute before every speech)
+
+      ### A. Pre-speech reflection (internal, do not output)
+      - Does every step in my argument chain hold? Any hidden assumptions or logical gaps?
+      - If I were my opponent, how would I attack this? Where am I weakest?
+      - Does my evidence actually support my claim, or could it backfire?
+      - Should I go on offense or defense this round?
+
+      ### B. Evidence discipline
+      - Verify key numbers — watch for order-of-magnitude errors
+      - Assess data freshness — fast-moving fields have short half-lives
+      - Distinguish primary data from secondary citations, expert opinion, and common assumptions
+
+      ### C. Anti-fragility
+      - Anticipate counterarguments; preemptively strengthen or strategically abandon weak points
+      - Catch logical gaps, data misuse, or outdated claims in your opponent's reasoning
+
+      ## Rules
+      1. Check Thread Progress to see how many times you have spoken.
+      2. On your 3rd speech, you MUST output $status: final (closing statement).
+      3. If genuinely convinced by the opponent, output $status: conceded.
+      4. Otherwise output $status: speak and counter the opponent's points.
+      5. Be rigorous, cite evidence, stay concise.
+    output: "Debate argument"
+    frontmatter: *debater-frontmatter
+
+  opponent:
+    description: "Argues AGAINST the proposition"
+    goal: "Build a compelling case against the proposition through logical reasoning and evidence"
+    capabilities: []
+    procedure: |
+      You are an experienced scholar arguing AGAINST the proposition.
+
+      ## Critical Thinking Framework (execute before every speech)
+
+      ### A. Pre-speech reflection (internal, do not output)
+      - Does every step in my argument chain hold? Any hidden assumptions or logical gaps?
+      - If I were my opponent, how would I attack this? Where am I weakest?
+      - Does my evidence actually support my claim, or could it backfire?
+      - Should I go on offense or defense this round?
+
+      ### B. Evidence discipline
+      - Verify key numbers — watch for order-of-magnitude errors
+      - Assess data freshness — fast-moving fields have short half-lives
+      - Distinguish primary data from secondary citations, expert opinion, and common assumptions
+
+      ### C. Anti-fragility
+      - Anticipate counterarguments; preemptively strengthen or strategically abandon weak points
+      - Catch logical gaps, data misuse, or outdated claims in your opponent's reasoning
+
+      ## Rules
+      1. Check Thread Progress to see how many times you have spoken.
+      2. On your 3rd speech, or when the proponent has issued a final statement, you MUST output $status: final.
+      3. If genuinely convinced by the proponent, output $status: conceded.
+      4. Otherwise output $status: speak and counter the proponent's points.
+      5. Be rigorous, cite evidence, stay concise.
+    output: "Debate argument"
+    frontmatter: *debater-frontmatter
+
+  host:
+    description: "Debate moderator — delivers impartial summary and verdict"
+    goal: "Objectively review the debate, analyze both sides, and deliver a verdict"
+    capabilities: []
+    procedure: |
+      You are an experienced academic debate moderator.
+
+      ## Task
+      1. Outline each side's core arguments
+      2. Evaluate reasoning quality and evidence use
+      3. Highlight the most impactful exchanges
+      4. Analyze the deeper significance of the topic
+      5. Deliver an overall verdict
+
+      ## Style
+      - Impartial but with independent judgment
+      - Substantive, not superficial
+    output: "Debate summary report"
+    frontmatter:
+      type: object
+      properties:
+        $status: { const: done }
+        summary: { type: string }
+        highlights: { type: string }
+        verdict: { type: string }
+      required: [$status, summary, highlights, verdict]
+
+  reporter:
+    description: "Generates an HTML report of the completed debate"
+    goal: "Produce a self-contained, visually polished HTML report that faithfully reproduces the entire debate with no paraphrasing."
+    capabilities: [run_command, write_file, read_file]
+    procedure: |
+      You are a report generator for a structured debate.
+
+      ## Steps
+      1. Read Thread Progress to get the thread ID.
+      2. Run: `uwf thread read <thread-id>` to get the full debate transcript.
+      3. Design and write a self-contained HTML file that presents the debate beautifully.
+      4. Save to `/tmp/debate-report-<thread-id>.html`.
+
+      ## HTML Report Requirements
+      - Title: the debate proposition
+      - Two-column layout comparing proponent vs opponent arguments round by round
+      - Key exchanges highlighted with visual callouts
+      - Host's verdict and summary in a prominent section
+      - If a side conceded, make it visually clear
+      - Clean typography, responsive layout, dark/light theme friendly
+      - All content verbatim from `uwf thread read` — do NOT paraphrase
+
+      ## Rules
+      1. You MUST use `uwf thread read` to get the data — do NOT rely on context.
+      2. Completely self-contained (inline styles, no CDN links).
+      3. Output the file path in your response body.
+    output: "Confirmation that the report was generated, with the file path."
+    frontmatter:
+      type: object
+      properties:
+        $status: { const: done }
+        reportPath: { type: string }
+      required: [$status, reportPath]
+
+graph:
+  $START:
+    new: { role: proponent, prompt: "The debate begins. You are arguing FOR the proposition. Present your opening argument." }
+    resume: { role: proponent, prompt: "The debate continues." }
+
+  proponent:
+    speak: { role: opponent, prompt: "Proponent argues:\n\n{{ argument }}\n\nYou are the opponent. Counter this argument." }
+    conceded: { role: host, prompt: "The proponent conceded: {{ reason }}\n\nPlease summarize the debate." }
+    final: { role: opponent, prompt: "Proponent's closing statement:\n\n{{ closing }}\n\nYou are the opponent. Deliver your final response." }
+
+  opponent:
+    speak: { role: proponent, prompt: "Opponent argues:\n\n{{ argument }}\n\nYou are the proponent. Counter this argument." }
+    conceded: { role: host, prompt: "The opponent conceded: {{ reason }}\n\nPlease summarize the debate." }
+    final: { role: host, prompt: "Opponent's closing statement:\n\n{{ closing }}\n\nThe debate is over. Please summarize." }
+
+  host:
+    done: { role: reporter, prompt: "Debate summary complete.\n\nSummary: {{ summary }}\nHighlights: {{ highlights }}\nVerdict: {{ verdict }}\n\nGenerate a polished HTML report of the entire debate." }
+
+  reporter:
+    done: { role: "$END", prompt: "Report generated." }

package/examples/socratic-questioning.yaml

@@ -0,0 +1,112 @@
+version: 1
+name: socratic-questioning
+description: "Socratic dialogue — a questioner helps the thinker examine their beliefs through probing questions."
+
+roles:
+  thinker:
+    description: "Holds and defends a position, refining it through dialogue"
+    goal: "Articulate and examine your position honestly. When a question exposes a weakness, acknowledge it and refine your view rather than deflecting."
+    capabilities: []
+    procedure: |
+      You are a thoughtful person exploring your own beliefs through dialogue.
+
+      ## Rules
+      1. Check Thread Progress to see how many times you have responded.
+      2. On your 3rd response, you MUST output $status: synthesis (your refined position).
+      3. Be honest — if a question reveals a gap, say so and adjust.
+      4. Build on previous exchanges, don't repeat yourself.
+      5. Keep responses focused (under 300 words).
+    output: "Your response to the question, or your final synthesis."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: respond }
+            insight: { type: string }
+          required: [$status, insight]
+        - properties:
+            $status: { const: synthesis }
+            revisedPosition: { type: string }
+            keyInsights: { type: string }
+          required: [$status, revisedPosition, keyInsights]
+
+  questioner:
+    description: "Asks probing questions to help the thinker examine assumptions"
+    goal: "Guide the thinker to deeper understanding through questions — never lecture, never argue, never assert your own position."
+    capabilities: []
+    procedure: |
+      You are a Socratic questioner. Your only tool is the question.
+
+      ## Questioning techniques
+      - **Clarification**: "What do you mean by...?" / "Can you give an example?"
+      - **Assumptions**: "What are you assuming here?" / "Why do you believe that's true?"
+      - **Evidence**: "What evidence supports this?" / "How would you respond to someone who says...?"
+      - **Implications**: "If that's true, what follows?" / "What would change if you're wrong?"
+      - **Perspective**: "How might someone in a different situation see this?"
+
+      ## Rules
+      1. Ask 1-2 questions per turn, not more.
+      2. NEVER state your own opinion or argue a position.
+      3. Build on the thinker's previous answer — don't jump to unrelated topics.
+      4. When the thinker reaches a synthesis, output $status: done.
+      5. Keep questions concise and sharp.
+    output: "Your probing question(s)."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: ask }
+            question: { type: string }
+          required: [$status, question]
+        - properties:
+            $status: { const: done }
+            summary: { type: string }
+          required: [$status, summary]
+
+  reporter:
+    description: "Generates an HTML report of the completed Socratic dialogue"
+    goal: "Produce a self-contained, visually polished HTML report that faithfully reproduces the entire dialogue with no paraphrasing."
+    capabilities: [run_command, write_file, read_file]
+    procedure: |
+      You are a report generator for a Socratic questioning session.
+
+      ## Steps
+      1. Read Thread Progress to get the thread ID.
+      2. Run: `uwf thread read <thread-id>` to get the full dialogue transcript.
+      3. Design and write a self-contained HTML file that presents the dialogue beautifully.
+      4. Save to `/tmp/socratic-report-<thread-id>.html`.
+
+      ## HTML Report Requirements
+      - Title: the original topic/position being examined
+      - Each exchange as a dialogue card (questioner question → thinker response)
+      - Visual distinction between questions and reflections
+      - The thinker's initial position and final synthesis prominently displayed
+      - A "journey" section showing how the position evolved
+      - Clean typography, responsive layout, dark/light theme friendly
+      - All content verbatim from `uwf thread read` — do NOT paraphrase
+
+      ## Rules
+      1. You MUST use `uwf thread read` to get the data — do NOT rely on context.
+      2. Completely self-contained (inline styles, no CDN links).
+      3. Output the file path in your response body.
+    output: "Confirmation that the report was generated, with the file path."
+    frontmatter:
+      type: object
+      properties:
+        $status: { const: done }
+        reportPath: { type: string }
+      required: [$status, reportPath]
+
+graph:
+  $START:
+    new: { role: thinker, prompt: "State your initial position on the topic. Be clear about what you believe and why." }
+    resume: { role: thinker, prompt: "Continue the dialogue from where you left off." }
+
+  thinker:
+    respond: { role: questioner, prompt: "The thinker says:\n\n{{ _body }}\n\nAsk a probing question to help them examine this further." }
+    synthesis: { role: questioner, prompt: "The thinker has reached a synthesis:\n\n{{ _body }}\n\nBriefly summarize the journey of this dialogue." }
+
+  questioner:
+    ask: { role: thinker, prompt: "The questioner asks:\n\n{{ _body }}\n\nReflect on this question and respond honestly." }
+    done: { role: reporter, prompt: "Dialogue complete.\n\nSummary: {{ summary }}\n\nGenerate a polished HTML report of the entire Socratic dialogue." }
+
+  reporter:
+    done: { role: "$END", prompt: "Report generated." }

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@united-workforce/cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "files": [
     "src",
     "dist",
+    "examples",
     "package.json"
   ],
   "type": "module",
@@ -11,22 +12,20 @@
     "uwf": "./dist/cli.js"
   },
   "dependencies": {
-    "@ocas/core": "^0.3.0",
-    "@ocas/fs": "^0.3.0",
+    "@ocas/core": "^0.5.0",
+    "@ocas/fs": "^0.4.1",
     "commander": "^14.0.3",
     "dotenv": "^16.6.1",
-    "mustache": "^4.2.0",
+    "liquidjs": "^10.27.0",
     "yaml": "^2.8.4",
-    "@united-workforce/protocol": "^0.1.0",
-    "@united-workforce/util": "^0.1.3",
-    "@united-workforce/util-agent": "^0.1.0"
+    "@united-workforce/util": "^0.2.0",
+    "@united-workforce/util-agent": "^0.2.1",
+    "@united-workforce/protocol": "^0.3.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {
-    "@types/mustache": "^4.2.6"
-  },
+  "devDependencies": {},
   "repository": {
     "type": "git",
     "url": "https://git.shazhou.work/shazhou/united-workforce.git",

package/src/__tests__/adapter-json-roundtrip.test.ts

@@ -25,12 +25,19 @@ const OUTPUT_SCHEMA = {
 // ── fixture ──────────────────────────────────────────────────────────────────
 
 let tmpDir: string;
+let savedOcasHome: string | undefined;
 
 beforeEach(async () => {
+  savedOcasHome = process.env.OCAS_HOME;
   tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-roundtrip-test-"));
 });
 
 afterEach(async () => {
+  if (savedOcasHome === undefined) {
+    delete process.env.OCAS_HOME;
+  } else {
+    process.env.OCAS_HOME = savedOcasHome;
+  }
   await rm(tmpDir, { recursive: true, force: true });
 });
 
@@ -119,7 +126,7 @@ describe("C1: adapter JSON round-trip integration", () => {
     const configPath = join(tmpDir, "config.yaml");
     await writeFile(
       configPath,
-      `defaultAgent: uwf-hermes\ndefaultModel: test-model\nagentOverrides: null\nagents: {}\nproviders: {}\nmodels: {}\n`,
+      `defaultAgent: uwf-hermes\nagentOverrides: null\nagents:\n  uwf-hermes:\n    command: uwf-hermes\n`,
     );
 
     // 5. Run CLI with agent override pointing to our mock
@@ -131,7 +138,7 @@ describe("C1: adapter JSON round-trip integration", () => {
     try {
       stdout = execFileSync(
         process.execPath,
-        [cliPath, "thread", "exec", threadId, "--agent", mockAgentPath],
+        [cliPath, "--format", "raw-json", "thread", "exec", threadId, "--agent", mockAgentPath],
         {
           encoding: "utf8",
           stdio: ["ignore", "pipe", "pipe"],
@@ -162,15 +169,17 @@ describe("C1: adapter JSON round-trip integration", () => {
       throw new Error(`CLI exited with code ${exitCode}\nstdout: ${stdout}\nstderr: ${stderr}`);
     }
 
-    // Parse CLI output
+    // Parse CLI output (raw-json envelope value: { threadId, workflowHash, steps: [...] })
     const cliOutput = JSON.parse(stdout.trim());
-    expect(cliOutput).toHaveProperty("thread", threadId);
-    expect(cliOutput).toHaveProperty("head", stepHash);
-    expect(cliOutput.head).toMatch(/^[0-9A-HJ-NP-TV-Z]{13}$/);
+    expect(cliOutput).toHaveProperty("threadId", threadId);
+    expect(cliOutput.steps).toHaveLength(1);
+    const firstStep = cliOutput.steps[0];
+    expect(firstStep).toHaveProperty("head", stepHash);
+    expect(firstStep.head).toMatch(/^[0-9A-HJ-NP-TV-Z]{13}$/);
 
     // Verify the CAS step node exists and has correct metadata
     const storeAfter = await openStore(casDir);
-    const stepNode = storeAfter.cas.get(cliOutput.head as CasRef);
+    const stepNode = storeAfter.cas.get(firstStep.head as CasRef);
     expect(stepNode).not.toBeNull();
 
     const payload = stepNode!.payload as StepNodePayload;

package/src/__tests__/agent-resolution-llm-free.test.ts

@@ -0,0 +1,39 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadWorkflowConfig } from "@united-workforce/util-agent";
+import { afterEach, describe, expect, test } from "vitest";
+
+describe("agent resolution works without LLM fields in config.yaml (issue #143)", () => {
+  let tempDir: string;
+  afterEach(() => {
+    if (tempDir) rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test("loadWorkflowConfig succeeds on a minimal engine-only config", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "uwf-engine-cfg-"));
+    writeFileSync(
+      join(tempDir, "config.yaml"),
+      "agents:\n  hermes: { command: uwf-hermes, args: [] }\ndefaultAgent: hermes\n",
+      "utf8",
+    );
+    const cfg = await loadWorkflowConfig(tempDir);
+    expect(cfg.defaultAgent).toBe("hermes");
+    expect(cfg.agents.hermes).toBeDefined();
+    expect(cfg.agentOverrides).toBeNull();
+  });
+
+  test("loadWorkflowConfig ignores legacy provider/model fields", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "uwf-engine-cfg-"));
+    writeFileSync(
+      join(tempDir, "config.yaml"),
+      "providers:\n  openai: { baseUrl: x, apiKey: y }\nmodels:\n  default: { provider: openai, name: gpt-4o }\ndefaultModel: default\nagents:\n  hermes: { command: uwf-hermes, args: [] }\ndefaultAgent: hermes\n",
+      "utf8",
+    );
+    const cfg = (await loadWorkflowConfig(tempDir)) as Record<string, unknown>;
+    expect(cfg.defaultAgent).toBe("hermes");
+    expect(cfg.providers).toBeUndefined();
+    expect(cfg.models).toBeUndefined();
+    expect(cfg.defaultModel).toBeUndefined();
+  });
+});

package/src/__tests__/build-step-entry.test.ts

@@ -0,0 +1,203 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CasRef, StepEntry, Usage } from "@united-workforce/protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { buildStepEntry, sumStepEntryUsage } from "../commands/step.js";
+import { createUwfStore, type UwfStore } from "../store.js";
+
+let tmpDir: string;
+let originalEnv: string | undefined;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "cli-build-step-entry-"));
+  originalEnv = process.env.OCAS_HOME;
+  process.env.OCAS_HOME = join(tmpDir, "cas");
+  await mkdir(process.env.OCAS_HOME, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+  if (originalEnv === undefined) {
+    delete process.env.OCAS_HOME;
+  } else {
+    process.env.OCAS_HOME = originalEnv;
+  }
+});
+
+type PutStepOptions = {
+  startedAtMs: number;
+  completedAtMs: number;
+  usage: Usage | null;
+  previousAttempts: CasRef[] | null;
+};
+
+async function setupStore(): Promise<{ uwf: UwfStore; startHash: CasRef }> {
+  const uwf = await createUwfStore(tmpDir);
+  const workflowHash = (await uwf.store.cas.put(uwf.schemas.workflow, {
+    name: "test-wf",
+    description: "desc",
+    roles: {},
+    graph: {},
+  })) as CasRef;
+  const startHash = (await uwf.store.cas.put(uwf.schemas.startNode, {
+    workflow: workflowHash,
+    prompt: "task",
+    cwd: "/tmp",
+  })) as CasRef;
+  return { uwf, startHash };
+}
+
+async function putStep(uwf: UwfStore, startHash: CasRef, options: PutStepOptions): Promise<CasRef> {
+  const outputHash = (await uwf.store.cas.put(uwf.schemas.text, "output text")) as CasRef;
+  const detailHash = (await uwf.store.cas.put(uwf.schemas.text, "detail text")) as CasRef;
+  return (await uwf.store.cas.put(uwf.schemas.stepNode, {
+    start: startHash,
+    prev: null,
+    role: "planner",
+    output: outputHash,
+    detail: detailHash,
+    agent: "uwf-mock",
+    edgePrompt: "",
+    startedAtMs: options.startedAtMs,
+    completedAtMs: options.completedAtMs,
+    cwd: "/tmp",
+    assembledPrompt: null,
+    usage: options.usage,
+    previousAttempts: options.previousAttempts,
+  })) as CasRef;
+}
+
+const usage = (
+  turns: number,
+  inputTokens: number,
+  outputTokens: number,
+  duration: number,
+): Usage => ({
+  turns,
+  inputTokens,
+  outputTokens,
+  duration,
+});
+
+describe("buildStepEntry", () => {
+  test("returns null for a non-StepNode hash", async () => {
+    const { uwf } = await setupStore();
+    const textHash = (await uwf.store.cas.put(uwf.schemas.text, "not a step")) as CasRef;
+    expect(buildStepEntry(uwf, textHash)).toBeNull();
+    expect(buildStepEntry(uwf, "MISSING000000" as CasRef)).toBeNull();
+  });
+
+  test("builds an entry with no previousAttempts and computes durationMs", async () => {
+    const { uwf, startHash } = await setupStore();
+    const stepHash = await putStep(uwf, startHash, {
+      startedAtMs: 1_000,
+      completedAtMs: 4_500,
+      usage: usage(2, 100, 50, 3.5),
+      previousAttempts: null,
+    });
+
+    const entry = buildStepEntry(uwf, stepHash);
+    expect(entry).not.toBeNull();
+    expect(entry?.hash).toBe(stepHash);
+    expect(entry?.role).toBe("planner");
+    expect(entry?.durationMs).toBe(3_500);
+    expect(entry?.usage).toEqual(usage(2, 100, 50, 3.5));
+    expect(entry?.previousAttempts).toBeNull();
+  });
+
+  test("recursively builds nested previousAttempts", async () => {
+    const { uwf, startHash } = await setupStore();
+    const first = await putStep(uwf, startHash, {
+      startedAtMs: 0,
+      completedAtMs: 100,
+      usage: usage(1, 10, 5, 0.1),
+      previousAttempts: null,
+    });
+    const second = await putStep(uwf, startHash, {
+      startedAtMs: 100,
+      completedAtMs: 300,
+      usage: usage(1, 20, 10, 0.2),
+      previousAttempts: [first],
+    });
+    const success = await putStep(uwf, startHash, {
+      startedAtMs: 300,
+      completedAtMs: 600,
+      usage: usage(3, 30, 15, 0.3),
+      previousAttempts: [second],
+    });
+
+    const entry = buildStepEntry(uwf, success);
+    expect(entry?.previousAttempts).toHaveLength(1);
+    const nested = entry?.previousAttempts?.[0];
+    expect(nested?.hash).toBe(second);
+    expect(nested?.previousAttempts).toHaveLength(1);
+    expect(nested?.previousAttempts?.[0]?.hash).toBe(first);
+    expect(nested?.previousAttempts?.[0]?.previousAttempts).toBeNull();
+  });
+
+  test("skips previousAttempts refs that do not resolve to a StepNode", async () => {
+    const { uwf, startHash } = await setupStore();
+    const success = await putStep(uwf, startHash, {
+      startedAtMs: 0,
+      completedAtMs: 100,
+      usage: null,
+      previousAttempts: ["DEADBEEF00000" as CasRef],
+    });
+
+    const entry = buildStepEntry(uwf, success);
+    expect(entry).not.toBeNull();
+    // The unresolvable ref is skipped, leaving no valid nested attempts.
+    expect(entry?.previousAttempts).toBeNull();
+  });
+});
+
+describe("sumStepEntryUsage", () => {
+  function entryWith(u: Usage | null, previousAttempts: StepEntry[] | null): StepEntry {
+    return {
+      hash: "STEP000000000" as CasRef,
+      role: "planner",
+      output: {},
+      detail: "DETAIL0000000" as CasRef,
+      agent: "uwf-mock",
+      timestamp: 0,
+      durationMs: 0,
+      usage: u,
+      previousAttempts,
+    };
+  }
+
+  test("returns zeros when usage is null and there are no attempts", () => {
+    expect(sumStepEntryUsage(entryWith(null, null))).toEqual({
+      turns: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      duration: 0,
+    });
+  });
+
+  test("aggregates usage across nested previousAttempts", () => {
+    const inner = entryWith(usage(1, 10, 5, 0.1), null);
+    const middle = entryWith(usage(2, 20, 10, 0.2), [inner]);
+    const root = entryWith(usage(3, 30, 15, 0.3), [middle]);
+
+    expect(sumStepEntryUsage(root)).toEqual({
+      turns: 6,
+      inputTokens: 60,
+      outputTokens: 30,
+      duration: expect.closeTo(0.6, 5),
+    });
+  });
+
+  test("treats null usage in nested attempts as zero", () => {
+    const inner = entryWith(null, null);
+    const root = entryWith(usage(2, 20, 10, 0.5), [inner]);
+
+    expect(sumStepEntryUsage(root)).toEqual({
+      turns: 2,
+      inputTokens: 20,
+      outputTokens: 10,
+      duration: 0.5,
+    });
+  });
+});