@d3ara1n/pi-subagent 0.10.4 → 1.0.1

package/src/utils.test.ts

@@ -4,10 +4,12 @@
  * Zero-dependency: runs on node's built-in test runner.
  *   node --test packages/pi-subagent/src/utils.test.ts
  *
- * These guard the bug fixes introduced during the improvement rounds:
- * path-injection (sanitizeFilename), concurrency/abort/negative-active/unlimited
- * semantics (AsyncSemaphore), provider-error word list (isProviderError), unknown-tool
- * formatting (previewArgs), output truncation fallback (truncateOutput).
+ * Coverage highlights: path-injection safety (sanitizeFilename),
+ * concurrency/abort/unlimited semantics (AsyncSemaphore), provider-error
+ * heuristics (isProviderError), shared result-view composition
+ * (terminalResultLine), time/budget formatting (formatTimePart), budget-stop
+ * and fallback provenance notes, background-run helpers, and notification
+ * throttling (createThrottler).
  */
 
 import { test, describe } from "node:test";
@@ -19,47 +21,63 @@ import {
   previewArgs,
   truncateOutput,
   formatTokens,
+  formatUsageStats,
   effectiveTimeout,
   elapsedSeconds,
   hasFailedSubagentResult,
+  buildFallbackFrom,
+  formatFallback,
+  FALLBACK_STDERR_TAIL,
+  deriveRunState,
+  isWaitTimedOut,
+  describeCurrentActivity,
+  formatUsageFooter,
+  formatFallbackNote,
+  formatBudgetNote,
+  formatCheckText,
+  formatTimePart,
+  freezeFrame,
+  createThrottler,
+  terminalResultLine,
 } from "./utils.ts";
 import type { SubagentResult, SubagentRole } from "./types.ts";
 
+/** Shared SubagentResult fixture. */
+const baseResult = (overrides: Partial<SubagentResult> = {}): SubagentResult => ({
+  role: "worker",
+  task: "test task",
+  exitCode: 0,
+  output: "ok",
+  stderr: "",
+  usage: {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    contextTokens: 0,
+    turns: 0,
+  },
+  activityLog: [],
+  ...overrides,
+});
+
 describe("subagent failure details", () => {
-  const baseResult = (overrides: Partial<SubagentResult> = {}): SubagentResult => ({
-    role: "worker",
-    task: "test task",
-    exitCode: 0,
-    messages: [],
-    output: "ok",
-    stderr: "",
-    usage: {
-      input: 0,
-      output: 0,
-      cacheRead: 0,
-      cacheWrite: 0,
-      cost: 0,
-      contextTokens: 0,
-      turns: 0,
-    },
-    activityLog: [],
-    ...overrides,
-  });
 
   test("detects failed delegate results for tool_result error marking", () => {
     assert.equal(
-      hasFailedSubagentResult({ mode: "single", results: [baseResult({ exitCode: 1 })] }),
+      hasFailedSubagentResult({ results: [baseResult({ exitCode: 1 })] }),
       true,
     );
     assert.equal(
-      hasFailedSubagentResult({ mode: "single", results: [baseResult({ stopReason: "timeout" })] }),
+      hasFailedSubagentResult({ results: [baseResult({ stopReason: "timeout" })] }),
       true,
     );
   });
 
   test("does not mark successful or malformed details as failed", () => {
-    assert.equal(hasFailedSubagentResult({ mode: "single", results: [baseResult()] }), false);
-    assert.equal(hasFailedSubagentResult({ mode: "single", results: [] }), false);
+    assert.equal(hasFailedSubagentResult({ results: [baseResult()] }), false);
+    assert.equal(hasFailedSubagentResult({ results: [] }), false);
     assert.equal(hasFailedSubagentResult(undefined), false);
     assert.equal(hasFailedSubagentResult({}), false);
   });
@@ -97,26 +115,7 @@ describe("sanitizeFilename", () => {
 
 // ── isProviderError: guards the #9 expanded word list ──
 describe("isProviderError", () => {
-  const mk = (stderr: string, errorMessage = ""): SubagentResult =>
-    ({
-      stderr,
-      errorMessage,
-      role: "",
-      task: "",
-      exitCode: 0,
-      messages: [],
-      output: "",
-      usage: {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheWrite: 0,
-        cost: 0,
-        contextTokens: 0,
-        turns: 0,
-      },
-      activityLog: [],
-    }) as unknown as SubagentResult;
+  const mk = (stderr: string, errorMessage = ""): SubagentResult => baseResult({ stderr, errorMessage });
 
   test("matches provider error keywords", () => {
     const cases = [
@@ -293,10 +292,10 @@ describe("effectiveTimeout", () => {
     assert.equal(effectiveTimeout(role(["read", "grep"])), 0);
   });
   test("delegate-capable role without timeout is also unlimited", () => {
-    assert.equal(effectiveTimeout(role(["read", "delegate"])), 0);
+    assert.equal(effectiveTimeout(role(["read", "subagent_delegate"])), 0);
   });
   test("explicit role timeout is honored", () => {
-    assert.equal(effectiveTimeout(role(["read", "delegate"], 300)), 300);
+    assert.equal(effectiveTimeout(role(["read", "subagent_delegate"], 300)), 300);
   });
   test("negative and non-finite values normalize to unlimited", () => {
     assert.equal(effectiveTimeout(role(["read"], -1)), 0);
@@ -368,3 +367,276 @@ describe("elapsedSeconds", () => {
     assert.equal(elapsedSeconds({ exitCode: -1, startTime: start }), 0);
   });
 });
+
+// ── formatTimePart: shared elapsed/budget(+grace) text ──
+describe("formatTimePart", () => {
+  test("running frame with budget and grace", () => {
+    const r = { exitCode: -1, startTime: Date.now() - 42000, budgetMs: 900000, graceMs: 3000 };
+    assert.equal(formatTimePart(r), "42s/900s(+3s)");
+  });
+  test("running frame without budget", () => {
+    const r = { exitCode: -1, startTime: Date.now() - 3000 };
+    assert.equal(formatTimePart(r), "3s");
+  });
+  test("terminal frame uses the frozen elapsedMs", () => {
+    assert.equal(formatTimePart({ exitCode: 0, elapsedMs: 5000, budgetMs: 900000 }), "5s/900s");
+  });
+  test("queued frame has no time", () => {
+    assert.equal(formatTimePart({ exitCode: -1 }), null);
+  });
+});
+
+// ── terminalResultLine: one chain for every result view ──
+describe("terminalResultLine", () => {
+  const id = (_color: string, text: string) => text;
+
+  test("failure shows the error message in error styling", () => {
+    assert.equal(
+      terminalResultLine(baseResult({ exitCode: 1, errorMessage: "boom" }), id),
+      "\u2717 boom",
+    );
+  });
+  test("timeout/budget map to the warning styling", () => {
+    assert.equal(
+      terminalResultLine(baseResult({ stopReason: "timeout", exitCode: 124, errorMessage: "Timed out after 900s" }), id),
+      "\u23F1 Timed out after 900s",
+    );
+  });
+  test("budget-exceeded is a warning line even though the run state is finished", () => {
+    assert.equal(
+      terminalResultLine(
+        baseResult({ stopReason: "budget_exceeded", errorMessage: "Budget exceeded (50 turns; partial output returned)" }),
+        id,
+      ),
+      "\u23F2 Budget exceeded (50 turns; partial output returned)",
+    );
+  });
+  test("success chain: AI summary wins, then output first line, then placeholder", () => {
+    assert.equal(terminalResultLine(baseResult({ summary: "did the thing" }), id), "\u2713 did the thing");
+    assert.equal(terminalResultLine(baseResult(), id), "\u2713 ok");
+    assert.equal(terminalResultLine(baseResult({ output: "" }), id), "\u2713 (no output)");
+  });
+  test("finishedText replaces the success chain (wait's status-only line)", () => {
+    assert.equal(terminalResultLine(baseResult(), id, "finished"), "\u2713 finished");
+  });
+});
+
+// ── createThrottler: burst coalescing for onUpdate ──
+describe("createThrottler", () => {
+  test("coalesces a burst into one fire per window", async () => {
+    let fired = 0;
+    const t = createThrottler(() => fired++);
+    t.notify();
+    t.notify();
+    t.notify();
+    await new Promise((r) => setTimeout(r, 80));
+    assert.equal(fired, 1);
+  });
+  test("cancel drops the pending fire", async () => {
+    let fired = 0;
+    const t = createThrottler(() => fired++);
+    t.notify();
+    t.cancel();
+    await new Promise((r) => setTimeout(r, 80));
+    assert.equal(fired, 0);
+  });
+});
+
+describe("fallback observability", () => {
+  const failed = (overrides: Partial<SubagentResult> = {}): SubagentResult =>
+    baseResult({
+      role: "researcher",
+      exitCode: 1,
+      model: "opencode-go/deepseek-v4-flash",
+      stopReason: "timeout",
+      errorMessage: "Timed out after 900s",
+      ...overrides,
+    });
+
+  test("buildFallbackFrom snapshots the failed attempt", () => {
+    const f = buildFallbackFrom(failed());
+    assert.equal(f.model, "opencode-go/deepseek-v4-flash");
+    assert.equal(f.stopReason, "timeout");
+    assert.equal(f.errorMessage, "Timed out after 900s");
+    assert.equal(f.stderrTail, undefined);
+  });
+
+  test("buildFallbackFrom keeps a truncated stderr tail", () => {
+    const noise = "x".repeat(2000);
+    const f = buildFallbackFrom(failed({ stderr: `${noise}HTTP 429 at tail` }));
+    assert.ok(f.stderrTail!.endsWith("HTTP 429 at tail"));
+    assert.ok(f.stderrTail!.length <= FALLBACK_STDERR_TAIL);
+  });
+
+  test("buildFallbackFrom drops whitespace-only stderr", () => {
+    const f = buildFallbackFrom(failed({ stderr: "   \n\t " }));
+    assert.equal(f.stderrTail, undefined);
+  });
+
+  test("formatFallback prefers errorMessage", () => {
+    assert.equal(
+      formatFallback({ model: "ds", stopReason: "timeout", errorMessage: "boom" }),
+      "first attempt ds failed (boom)",
+    );
+  });
+
+  test("formatFallback falls back to stopReason then a generic label", () => {
+    assert.equal(formatFallback({ model: "ds", stopReason: "timeout" }), "first attempt ds failed (timeout)");
+    assert.equal(formatFallback({}), "first attempt unknown model failed (provider error)");
+  });
+
+  test("formatFallback keeps a single truncated line", () => {
+    assert.equal(formatFallback({ model: "ds", errorMessage: "line1\nline2" }), "first attempt ds failed (line1)");
+    const long = "y".repeat(150);
+    const out = formatFallback({ model: "ds", errorMessage: long });
+    assert.equal(out, `first attempt ds failed (${"y".repeat(100)}...)`);
+    assert.ok(out.endsWith("...)"));
+  });
+
+  test("buildFallbackFrom fills model from the requested model when the child died early", () => {
+    const f = buildFallbackFrom(failed({ model: undefined }), "opencode-go/deepseek-v4-flash");
+    assert.equal(f.model, "opencode-go/deepseek-v4-flash");
+  });
+
+  test("buildFallbackFrom derives a reason from stderr when errorMessage is unset", () => {
+    const f = buildFallbackFrom(
+      failed({ errorMessage: undefined, stderr: "\x1b[2Knoise\nError: 429 Too Many Requests\n\x1b[?25h" }),
+    );
+    assert.equal(f.errorMessage, "Error: 429 Too Many Requests");
+  });
+
+  test("an explicit errorMessage wins over stderr", () => {
+    const f = buildFallbackFrom(failed({ stderr: "connection reset by peer 429" }));
+    assert.equal(f.errorMessage, "Timed out after 900s");
+  });
+
+  test("formatFallback shows the error message, never raw stderr content", () => {
+    const f = buildFallbackFrom(failed({ stderr: "CONNECTIVITY monster line mentioning 429" }));
+    const out = formatFallback(f);
+    assert.ok(out.includes("Timed out after 900s"));
+    assert.ok(!out.includes("CONNECTIVITY"));
+  });
+});
+
+describe("background run helpers", () => {
+  const queuedFrame = () => baseResult({ exitCode: -1, queued: true });
+  const runningFrame = () => baseResult({ exitCode: -1 });
+
+  test("deriveRunState maps frames to lifecycle states", () => {
+    assert.equal(deriveRunState(queuedFrame()), "queued");
+    assert.equal(deriveRunState(runningFrame()), "running");
+    assert.equal(deriveRunState(baseResult()), "finished");
+    assert.equal(deriveRunState(baseResult({ exitCode: 1 })), "failed");
+    assert.equal(deriveRunState(baseResult({ stopReason: "timeout", exitCode: 124 })), "failed");
+    // budget stops are intentional finishes
+    assert.equal(deriveRunState(baseResult({ stopReason: "budget_exceeded" })), "finished");
+  });
+
+  test("isWaitTimedOut only matches the explicit timeout flag", () => {
+    assert.equal(isWaitTimedOut({ entries: [], timedOut: true }), true);
+    assert.equal(isWaitTimedOut({ entries: [] }), false);
+    assert.equal(isWaitTimedOut(undefined), false);
+  });
+
+  test("describeCurrentActivity reports the latest activity item", () => {
+    assert.equal(describeCurrentActivity(runningFrame()), "waiting for first event");
+    const thinking = runningFrame();
+    thinking.activityLog = [{ kind: "thinking", id: "thinking-0", status: "running" }];
+    assert.equal(describeCurrentActivity(thinking), "thinking");
+    const withTool = runningFrame();
+    withTool.activityLog = [
+      { kind: "thinking", id: "thinking-0", status: "done" },
+      { kind: "toolCall", id: "t1", status: "running", toolName: "bash", args: { command: "ls" } },
+    ];
+    assert.equal(describeCurrentActivity(withTool), "$ ls");
+  });
+
+  test("formatUsageFooter renders turns, tokens, cost, and model", () => {
+    assert.equal(formatUsageFooter(baseResult()), "");
+    const r = baseResult({
+      usage: { input: 1200, output: 300, cacheRead: 0, cacheWrite: 0, cost: 0.5, contextTokens: 0, turns: 2 },
+      model: "test/model-x",
+    });
+    assert.equal(formatUsageFooter(r), "\n\n--- 2 turns \u21911.2k \u2193300 $0.5000 test/model-x ---");
+  });
+
+  test("formatUsageStats adds cache and peak-context figures the footer omits", () => {
+    const usage = { input: 1200, output: 300, cacheRead: 900, cacheWrite: 100, cost: 0.5, contextTokens: 45000, turns: 2 };
+    assert.equal(
+      formatUsageStats(usage, "test/model-x"),
+      "2 turns \u21911.2k \u2193300 R900 W100 ctx45k $0.5000 test/model-x",
+    );
+    // Footer stays lean — no cache/context parts.
+    assert.equal(
+      formatUsageFooter({ usage, model: "test/model-x" }),
+      "\n\n--- 2 turns \u21911.2k \u2193300 $0.5000 test/model-x ---",
+    );
+  });
+
+  test("formatBudgetNote flags budget-stopped output as partial", () => {
+    assert.equal(formatBudgetNote(baseResult()), "");
+    assert.equal(
+      formatBudgetNote(baseResult({ stopReason: "budget_exceeded", errorMessage: "Budget exceeded (50 turns)" })),
+      "\n\n--- Budget exceeded (50 turns) ---",
+    );
+  });
+
+  test("formatFallbackNote is empty without a retry and descriptive with one", () => {
+    assert.equal(formatFallbackNote(baseResult()), "");
+    const r = baseResult({
+      fallbackFrom: { model: "primary/m1", errorMessage: "429 quota exceeded" },
+      model: "fallback/m2",
+    });
+    assert.equal(
+      formatFallbackNote(r),
+      "\n\n--- fallback: first attempt primary/m1 failed (429 quota exceeded); retried on fallback/m2 ---",
+    );
+  });
+
+  test("formatCheckText covers all four run states", () => {
+    assert.match(formatCheckText("sub-1", "explorer", queuedFrame()), /^sub-1 \(explorer\): queued —/);
+    assert.match(formatCheckText("sub-1", "explorer", runningFrame()), /^sub-1 \(explorer\): running — /);
+    assert.match(
+      formatCheckText("sub-1", "explorer", baseResult({ exitCode: 1, errorMessage: "boom" })),
+      /^sub-1 \(explorer\): failed — boom\n\nPartial output:\nok$/,
+    );
+    assert.match(formatCheckText("sub-1", "explorer", baseResult()), /^sub-1 \(explorer\): finished\n\nok$/);
+  });
+
+  test("formatCheckText flags budget-stopped runs as partial on the finished line", () => {
+    const r = baseResult({ stopReason: "budget_exceeded", errorMessage: "Budget exceeded (50 turns)" });
+    assert.match(
+      formatCheckText("sub-1", "explorer", r),
+      /^sub-1 \(explorer\): finished\n\nok\n\n--- Budget exceeded \(50 turns\) ---$/,
+    );
+  });
+
+  test("formatCheckText keeps the fallback note on failed runs too", () => {
+    const r = baseResult({
+      exitCode: 1,
+      errorMessage: "boom",
+      fallbackFrom: { model: "primary/m1", errorMessage: "429 quota exceeded" },
+      model: "fallback/m2",
+    });
+    assert.match(
+      formatCheckText("sub-1", "explorer", r),
+      /failed — boom\n\nPartial output:\nok\n\n--- fallback: first attempt primary\/m1 failed \(429 quota exceeded\); retried on fallback\/m2 ---$/,
+    );
+  });
+
+  test("freezeFrame stops the elapsed clock and folds the open pause into grace", () => {
+    const start = Date.now() - 5000;
+    const pausedAt = Date.now() - 2000;
+    const frozen = freezeFrame(baseResult({
+      exitCode: -1,
+      startTime: start,
+      budgetMs: 60000,
+      graceMs: 1000,
+      pauseStart: pausedAt,
+    }));
+    assert.equal(frozen.startTime, undefined);
+    assert.equal(frozen.pauseStart, undefined);
+    assert.ok(frozen.elapsedMs! >= 4990 && frozen.elapsedMs! <= 5010, `elapsedMs ~5000, got ${frozen.elapsedMs}`);
+    assert.ok(frozen.graceMs! >= 3000 && frozen.graceMs! <= 3010, `graceMs ~3000, got ${frozen.graceMs}`);
+  });
+});