@pify/shell-background 0.5.0 → 0.6.0

package/README.md

@@ -55,17 +55,22 @@ Put these in `.pi/shell-background.json` (project) or `<agentDir>/shell-backgrou
   "autoBackgroundMs": 30000,
   "tailBytes": 65536,
   "tailLines": 200,
-  "maxBackground": 8
+  "maxBackground": 8,
+  "deliverResults": true
 }
 ```
 
-`autoBackgroundMs` is how long a foreground command may run before it auto-backgrounds; set it to `0` to disable auto-background (explicit `background: true` still works). `PIFY_SHELL_BG_MS` overrides it for one run or in CI. `tailBytes` bounds how much of a job's log a status result reads; `tailLines` bounds how many lines of it the model is shown (0 disables the line shrink). `maxBackground` bounds how many jobs may be alive at once: over it, a `background: true` request is refused with a message naming the limit (the command can still run in the foreground), and a command that crosses the auto-background threshold simply stays in the foreground instead of moving — a command is never refused, only the decision to background it. Bad values fall back to the defaults with a warning rather than taking the tool down.
+`autoBackgroundMs` is how long a foreground command may run before it auto-backgrounds; set it to `0` to disable auto-background (explicit `background: true` still works). `PIFY_SHELL_BG_MS` overrides it for one run or in CI. `tailBytes` bounds how much of a job's log a status result reads; `tailLines` bounds how many lines of it the model is shown (0 disables the line shrink). `maxBackground` bounds how many jobs may be alive at once: over it, a `background: true` request is refused with a message naming the limit (the command can still run in the foreground), and a command that crosses the auto-background threshold simply stays in the foreground instead of moving — a command is never refused, only the decision to background it. `deliverResults` (boolean, default `true`): when a background job finishes, its result is pushed into the conversation and wakes the agent for a new turn. Set it to `false` to turn that off — the widget still updates and `shell_status {id}` still collects the result, but nothing is injected and the agent is not woken. Bad values fall back to the defaults with a warning rather than taking the tool down.
 
 Since pi 0.99 the bash tool also returns a machine-readable result — `structuredContent` — which codemode scripts and tools calling `ctx.executeTool("bash", …)` receive instead of the text. This package keeps pi's shape so such a script reads either tool unchanged: `output` (the whole log, up to 1 MiB, head and tail around an omission marker), `truncated`, `full_output_path`, `exit_code`, `wall_time_seconds` — plus `status` and `job_id`, because a command here can still be running when the tool returns; then `exit_code` is absent and `shell_status {id}` collects it, with the same structured result.
 
 A backgrounded command runs with no one to answer it, so its environment says so: `GIT_TERMINAL_PROMPT=0` and `GIT_EDITOR`/`EDITOR`/`VISUAL=true` are forced (a `git commit` without `-m` fails with "empty message" instead of waiting on an editor that never comes, and an https `git fetch` fails instead of prompting for a password), and pagers default to `cat` unless you set them. `CI` and `TERM` are left alone on purpose — dev servers and watchers read them.
 
-The tail a result carries is cleaned the way pi's own bash cleans what the model sees — ANSI escapes and control characters stripped — with two improvements borrowed from caveman's log compressors. A carriage-return redraw is **resolved to its last frame** rather than having the `\r` deleted: pi's own cleaning keeps every frame's text, so a 2000-frame progress bar arrives as one line holding all 2000 frames; here it arrives as `1999/2000`. And a long result is **shrunk by lines, not bytes**: the first and last lines are kept, every line that names trouble (`error`, `FAILED`, `Traceback`, `at …`, `File "…"`, `path:12:5:`, `FooError`, `caused by`, `exit status 1`) is kept wherever it sits, and the rest collapses into markers that count what they replaced — `[… 412 lines omitted (INFO ×380, DEBUG ×29) …]` — computed from exactly those lines. A byte window kept the *end* of a build log, where the summary is; a line window with that regex keeps the failing step in the middle too. Runs under three lines are shown as they are (a marker in place of one line only reads as a hole), the markers are recognised on a later poll so a shrunk result re-serialises identically (the provider prefix cache depends on it), and one note names what was left out and where the whole log is. A log that cannot be read says `(log unavailable: …)` rather than `(no output)`, which would send the model polling for output that will never come. The log file on disk keeps every byte.
+The tail a result carries is cleaned the way pi's own bash cleans what the model sees — ANSI escapes and control characters stripped — with two improvements borrowed from caveman's log compressors. A carriage-return redraw is **resolved to its last frame** rather than having the `\r` deleted: pi's own cleaning keeps every frame's text, so a 2000-frame progress bar arrives as one line holding all 2000 frames; here it arrives as `1999/2000`. And a long result is **shrunk by lines, not bytes**: the first and last lines are kept, every line that names trouble (`error`, `FAILED`, `Traceback`, `at …`, `File "…"`, `path:12:5:`, `FooError`, `caused by`, `exit status 1`) is kept wherever it sits, and the rest collapses into markers that count what they replaced — `[… 412 lines omitted (INFO ×380, DEBUG ×29) …]` — computed from exactly those lines. A byte window kept the *end* of a build log, where the summary is; a line window with that regex keeps the failing step in the middle too. Runs under three lines are shown as they are (a marker in place of one line only reads as a hole), the markers are recognised on a later poll so a shrunk result re-serialises identically (the provider prefix cache depends on it), and one note names what was left out and where the whole log is. The line shrink is guarded against truncating a *distinct* document: before a run of lines is collapsed, one representative of every kind of line a surviving line does not already resemble is kept (caveman's redundancy guard, vocabulary-containment with digit masking so lines differing only in a timestamp count as one). So a 50k-line repetitive build log collapses hard, while a 50k-line document where every line is distinct is kept and the shrink reports no win — the honest outcome rather than a silent deletion.
+
+A whole JSON test report in the tail — `pytest --json-report`, `jest --json` — is rendered as counts plus every failure with its stack trimmed to the first three and last two frames (`TEST SUMMARY: 240 passed, 3 failed` then each `FAILED: …`), instead of the raw document. Detection is on the exact top-level keys, so ordinary JSON is untouched; a truncated report is not valid JSON and falls through to the line view; the full report stays on disk. (JUnit XML lands in a file rather than on stdout and is left alone.)
+
+A log that cannot be read says `(log unavailable: …)` rather than `(no output)`, which would send the model polling for output that will never come. The log file on disk keeps every byte.
 
 ## Coexistence with @pify/pretty
 

package/extensions/shell-background.ts

@@ -218,6 +218,7 @@ export default function shellBackground(pi: ExtensionAPI) {
   /** Push a finished job's result into the conversation through the live pi. */
   function deliver(job: Job): void {
     renderWidget();
+    if (!settings.deliverResults) return;
     pi.sendMessage(
       {
         customType: DELIVERY_TYPE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/shell-background",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Long-running bash goes async: background: true launches detached, and any command still running after 30s auto-backgrounds and delivers its result when it finishes",
   "keywords": [
     "pi-package",

package/src/config.ts

@@ -29,6 +29,13 @@ export interface ShellBgSettings {
    * — a command itself is never refused.
    */
   maxBackground: number;
+  /**
+   * Whether a finished background job pushes its result into the conversation
+   * (and triggers a new agent turn that explains it). false: the job still
+   * finishes, the widget updates, and shell_status collects the result, but
+   * nothing is injected and the agent is not woken.
+   */
+  deliverResults: boolean;
 }
 
 export const DEFAULT_SETTINGS: ShellBgSettings = {
@@ -36,9 +43,12 @@ export const DEFAULT_SETTINGS: ShellBgSettings = {
   tailBytes: 64 * 1024,
   tailLines: 200,
   maxBackground: 8,
+  deliverResults: true,
 };
 
-const LIMITS: Record<keyof ShellBgSettings, { min: number; max: number }> = {
+type NumericKey = Exclude<keyof ShellBgSettings, "deliverResults">;
+
+const LIMITS: Record<NumericKey, { min: number; max: number }> = {
   // 0 is allowed (disable); otherwise at least 1s so a typo of "30" (=30ms)
   // does not make every command look long-running.
   autoBackgroundMs: { min: 0, max: 3_600_000 },
@@ -63,7 +73,12 @@ export function resolveSettings(
           warnings.push(`unknown setting "${key}"`);
           continue;
         }
-        const name = key as keyof ShellBgSettings;
+        if (key === "deliverResults") {
+          if (typeof value === "boolean") settings.deliverResults = value;
+          else warnings.push(`"deliverResults" must be true or false — using ${DEFAULT_SETTINGS.deliverResults}`);
+          continue;
+        }
+        const name = key as NumericKey;
         if (typeof value !== "number" || !Number.isFinite(value)) {
           warnings.push(`"${key}" must be a number — using ${DEFAULT_SETTINGS[name]}`);
           continue;
@@ -83,7 +98,7 @@ export function resolveSettings(
   return { settings, warnings };
 }
 
-function clamp(name: keyof ShellBgSettings, value: number, warnings: string[]): number {
+function clamp(name: NumericKey, value: number, warnings: string[]): number {
   const { min, max } = LIMITS[name];
   const c = Math.round(Math.min(max, Math.max(min, value)));
   if (c !== value) warnings.push(`"${name}" clamped to ${c} (allowed ${min}–${max})`);

package/src/format.ts

@@ -6,6 +6,7 @@ import type { Job } from "./types.ts";
 import { readTail } from "./tail.ts";
 import { sanitizeOutput } from "./sanitize.ts";
 import { DEFAULT_SHRINK, shrinkLines } from "./shrink.ts";
+import { parseTestReport, renderTestReport } from "./testreport.ts";
 
 function kb(bytes: number): string {
   return bytes < 1024 * 1024 ? `${Math.max(1, Math.round(bytes / 1024))}KB` : `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
@@ -61,6 +62,17 @@ export function formatResult(job: Job, tailBytes: number, tailLines: number = DE
     lines.push(job.status === "running" ? "(no output yet)" : "(no output)");
     return lines.join("\n");
   }
+  // A whole JSON test report (pytest --json-report, jest --json) read from the
+  // tail becomes counts + every failure. Only when the tail holds the whole
+  // document — a truncated one is not valid JSON and falls through to the
+  // line view. The full report stays on disk.
+  if (!tail.truncated) {
+    const report = parseTestReport(text);
+    if (report) {
+      lines.push(renderTestReport(report));
+      return lines.join("\n");
+    }
+  }
   const shrunk = shrinkLines(text, { maxLines: tailLines, tail: Math.max(DEFAULT_SHRINK.tail, Math.floor(tailLines / 2)) });
   const notes: string[] = [];
   if (shrunk.omitted > 0) {

package/src/redundancy.ts

@@ -0,0 +1,127 @@
+/**
+ * The guard that separates *eliding repetition* from *truncating a document*.
+ * A faithful port of caveman's keepNonRedundant (JuliusBrussee/caveman,
+ * engine/compressors/redundancy.go).
+ *
+ * The line shrink (shrink.ts) keeps the head, the tail, and every line that
+ * names trouble, and collapses the rest. On a build log that is the right
+ * call: the dropped lines are repeated chunk/step noise, each represented by
+ * a surviving one. On a 50k-line document where every line is distinct — a
+ * bibliography, a generated source file — the same transform would silently
+ * delete most of the content. This gate runs before the collapse: a line
+ * about to be dropped is KEPT when no surviving line already resembles it, so
+ * a distinct document retains a representative of every kind of line and only
+ * true repetition is elided. Deterministic (prefix cache), bounded (the work
+ * is the same on a 200-line and a 20,000-line payload), pure.
+ */
+
+const CONTAINMENT = 0.9; // a dropped line's vocabulary a survivor must carry to represent it
+const MAX_CLASSES = 64; // kept lines sampled to seed the represented classes
+const MAX_PROMOTIONS = 128; // first-of-kind lines kept before the payload is declared a document
+const MAX_UNIT_TOKENS = 128; // vocabulary built per line, so one long line cannot make this quadratic
+const MIN_WORD_TOKENS = 1; // letter-bearing tokens a line needs before its digits are masked
+
+interface Profile {
+  vocab: Set<string>;
+  masked: boolean;
+}
+
+/**
+ * A line reduced to its word/number tokens, every run of digits optionally
+ * collapsed to `#`. Masking lets two log lines that differ only in a timestamp
+ * recognise each other; a line with no words keeps its digits, because there
+ * the numbers ARE the content (`['1973.', 251]` must not match `['1974.', 260]`).
+ */
+function tokenize(unit: string, maskDigits: boolean): { vocab: Set<string>; words: number } {
+  const vocab = new Set<string>();
+  let words = 0;
+  let token = "";
+  let hasLetter = false;
+  let inDigits = false;
+  const flush = () => {
+    if (token.length > 0 && !vocab.has(token)) {
+      vocab.add(token);
+      if (hasLetter) words++;
+    }
+    token = "";
+    hasLetter = false;
+    inDigits = false;
+  };
+  for (const ch of unit.toLowerCase()) {
+    if (ch >= "0" && ch <= "9") {
+      if (maskDigits) {
+        if (!inDigits) {
+          token += "#";
+          inDigits = true;
+        }
+      } else {
+        token += ch;
+        inDigits = false;
+      }
+    } else if (/[a-z_]/.test(ch) || (ch.toLowerCase() !== ch.toUpperCase())) {
+      token += ch;
+      hasLetter = true;
+      inDigits = false;
+    } else {
+      flush();
+    }
+    if (vocab.size >= MAX_UNIT_TOKENS) return { vocab, words };
+  }
+  flush();
+  return { vocab, words };
+}
+
+function unitVocabulary(unit: string): Profile {
+  const masked = tokenize(unit, true);
+  if (masked.words >= MIN_WORD_TOKENS) return { vocab: masked.vocab, masked: true };
+  return { vocab: tokenize(unit, false).vocab, masked: false };
+}
+
+function representedBy(dropped: Profile, classes: Profile[]): boolean {
+  if (dropped.vocab.size === 0) return true; // punctuation-only line carries nothing to lose
+  const need = Math.ceil(CONTAINMENT * dropped.vocab.size - 1e-9);
+  for (const cls of classes) {
+    if (cls.masked !== dropped.masked) continue;
+    let hit = 0;
+    for (const token of dropped.vocab) {
+      if (cls.vocab.has(token)) {
+        hit++;
+        if (hit >= need) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Promote back to kept any not-yet-kept line that no surviving line
+ * represents. Mutates `keep` in place, in document order.
+ */
+export function keepNonRedundant(units: readonly string[], keep: boolean[]): void {
+  if (units.length !== keep.length) return;
+  const kept: number[] = [];
+  for (let i = 0; i < keep.length; i++) if (keep[i]) kept.push(i);
+
+  const classes: Profile[] = [];
+  const step = kept.length > MAX_CLASSES ? Math.floor(kept.length / MAX_CLASSES) : 1;
+  for (let n = 0; n < kept.length && classes.length < MAX_CLASSES; n += step) {
+    classes.push(unitVocabulary(units[kept[n]!]!));
+  }
+
+  let promotions = 0;
+  for (let i = 0; i < units.length; i++) {
+    if (keep[i]) continue;
+    if (promotions >= MAX_PROMOTIONS) {
+      // More distinct kinds of line than any repetitive stream has: a document.
+      // Keep the rest; the caller's "did this actually shrink?" check then
+      // passes the original through. Prefer the honest zero.
+      keep[i] = true;
+      continue;
+    }
+    const vocab = unitVocabulary(units[i]!);
+    if (representedBy(vocab, classes)) continue;
+    keep[i] = true;
+    promotions++;
+    classes.push(vocab);
+  }
+}

package/src/shrink.ts

@@ -70,6 +70,8 @@ export interface Shrunk {
   total: number;
 }
 
+import { keepNonRedundant } from "./redundancy.ts";
+
 export const DEFAULT_SHRINK: Required<ShrinkOptions> = { head: 3, tail: 100, maxLines: 200 };
 
 function levelSummary(lines: string[]): string {
@@ -101,6 +103,10 @@ export function shrinkLines(text: string, opts: ShrinkOptions = {}): Shrunk {
   const total = lines.length;
   if (maxLines <= 0 || total <= maxLines) return { text, omitted: 0, total };
   const keep = lines.map((line, i) => i < head || i >= total - tail || isImportantLine(line));
+  // Before collapsing, keep one representative of every DISTINCT line a run is
+  // about to drop, so a document of unique lines is not truncated — only true
+  // repetition is elided (caveman's redundancy guard).
+  keepNonRedundant(lines, keep);
   const out: string[] = [];
   let omitted = 0;
   let i = 0;

package/src/testreport.ts

@@ -0,0 +1,158 @@
+/**
+ * A machine-readable test report, rendered as counts plus every failure.
+ * Ported from caveman's test-report compressor (JuliusBrussee/caveman,
+ * engine/compressors/testreport.go), narrowed to the two JSON shapes a bash
+ * command actually prints to stdout: pytest-json-report and Jest `--json`.
+ * (JUnit XML lands in a file, not on stdout, and parsing it well needs an XML
+ * dependency this package does not take.)
+ *
+ * No failure is ever dropped: the summary counts every outcome, and each
+ * failure keeps its name, message and a stack trimmed to its first three and
+ * last two frames. Detection gates on the exact top-level keys, so ordinary
+ * JSON that merely mentions them is left to the normal tail. Pure; the full
+ * log stays on disk for recovery.
+ */
+
+export interface TestReport {
+  passed: number;
+  failed: number;
+  skipped: number;
+  errors: number;
+  duration?: number;
+  other: Record<string, number>;
+  failures: Array<{ name: string; message: string; type: "failure" | "error"; stack: string[] }>;
+}
+
+/** Keep a stack's first 3 and last 2 real frames, only when that drops at least 3. */
+export function trimStack(frames: string[]): string[] {
+  const clean = frames
+    .map((f) => f.trim())
+    .filter((f) => f !== "" && (/^at /.test(f) || /\.(py|java|js|ts|rb|go):/.test(f)));
+  if (clean.length < 8) return clean;
+  return [...clean.slice(0, 3), `... (${clean.length - 5} frames omitted)`, ...clean.slice(-2)];
+}
+
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+
+function parsePytest(doc: Record<string, unknown>): TestReport | null {
+  if (!Array.isArray(doc.tests)) return null;
+  const r: TestReport = { passed: 0, failed: 0, skipped: 0, errors: 0, duration: num(doc.duration) || undefined, other: {}, failures: [] };
+  for (const t of doc.tests) {
+    if (!t || typeof t !== "object") continue;
+    const test = t as Record<string, unknown>;
+    const outcome = typeof test.outcome === "string" ? test.outcome : "";
+    const stageRepr = (name: string): string => {
+      const stage = test[name];
+      const lr = stage && typeof stage === "object" ? (stage as Record<string, unknown>).longrepr : undefined;
+      return typeof lr === "string" ? lr : "";
+    };
+    const longrepr = stageRepr("call") || stageRepr("setup") || stageRepr("teardown");
+    const nodeid = typeof test.nodeid === "string" ? test.nodeid : "(unknown)";
+    if (outcome === "passed") r.passed++;
+    else if (outcome === "skipped") r.skipped++;
+    else if (outcome === "failed" || outcome === "error") {
+      const isError = outcome === "error";
+      isError ? r.errors++ : r.failed++;
+      let message = "";
+      const stack: string[] = [];
+      for (const raw of longrepr.split("\n")) {
+        const line = raw.trim();
+        if (!line) continue;
+        if (!isError && line.startsWith("E ")) {
+          if (!message) message = line.slice(2).trim();
+        } else if (line.includes(".py:") || line.startsWith("at ")) stack.push(line);
+        else if (isError && !message && !line.includes(".py:")) message = line;
+      }
+      r.failures.push({ name: nodeid, message, type: isError ? "error" : "failure", stack: trimStack(stack) });
+    } else if (outcome) r.other[outcome] = (r.other[outcome] ?? 0) + 1;
+  }
+  return r;
+}
+
+function parseJest(doc: Record<string, unknown>): TestReport | null {
+  if (!Array.isArray(doc.testResults)) return null;
+  const r: TestReport = {
+    passed: num(doc.numPassedTests),
+    failed: num(doc.numFailedTests),
+    skipped: num(doc.numPendingTests),
+    errors: 0,
+    other: {},
+    failures: [],
+  };
+  for (const suite of doc.testResults) {
+    const results = suite && typeof suite === "object" ? (suite as Record<string, unknown>).assertionResults : undefined;
+    if (!Array.isArray(results)) continue;
+    for (const a of results) {
+      if (!a || typeof a !== "object") continue;
+      const test = a as Record<string, unknown>;
+      if (test.status !== "failed") continue;
+      const ancestors = Array.isArray(test.ancestorTitles) ? (test.ancestorTitles as unknown[]).map(String) : [];
+      const title = typeof test.title === "string" ? test.title : "";
+      const name = (typeof test.fullName === "string" && test.fullName) || [...ancestors, title].filter(Boolean).join(" › ") || "(unnamed)";
+      let message = "";
+      const stack: string[] = [];
+      const msgs = Array.isArray(test.failureMessages) ? test.failureMessages : [];
+      if (msgs.length > 0 && typeof msgs[0] === "string") {
+        for (const raw of (msgs[0] as string).split("\n")) {
+          const line = raw.trim();
+          if (!line) continue;
+          if (line.startsWith("at ") || line.includes(".test.") || line.includes(".spec.")) stack.push(line);
+          else if (!message) message = line;
+        }
+      }
+      r.failures.push({ name, message, type: "failure", stack: trimStack(stack) });
+    }
+  }
+  return r;
+}
+
+/** Parse a JSON test report, or null when the text is not one. Detection is on exact top-level keys. */
+export function parseTestReport(text: string): TestReport | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("{")) return null;
+  // Byte pre-check so ordinary JSON is not parsed twice.
+  if (!trimmed.includes('"exitcode"') && !trimmed.includes('"numFailedTests"')) return null;
+  let doc: unknown;
+  try {
+    doc = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
+  const top = doc as Record<string, unknown>;
+  const report = "exitcode" in top && Array.isArray(top.tests) ? parsePytest(top)
+    : "numFailedTests" in top && Array.isArray(top.testResults) ? parseJest(top)
+    : null;
+  if (!report) return null;
+  const total = report.passed + report.failed + report.skipped + report.errors + Object.values(report.other).reduce((a, b) => a + b, 0);
+  return total === 0 ? null : report;
+}
+
+export function renderTestReport(r: TestReport): string {
+  const parts: string[] = [];
+  if (r.passed > 0) parts.push(`${r.passed} passed`);
+  if (r.failed > 0) parts.push(`${r.failed} failed`);
+  if (r.errors > 0) parts.push(`${r.errors} errors`);
+  if (r.skipped > 0) parts.push(`${r.skipped} skipped`);
+  for (const name of Object.keys(r.other).sort()) parts.push(`${r.other[name]} ${name}`);
+  let out = `TEST SUMMARY: ${parts.join(", ")}`;
+  if (r.duration && r.duration > 0) out += ` (${r.duration.toFixed(1)}s)`;
+  for (const f of r.failures) {
+    out += `\n\n${f.type === "error" ? "ERROR" : "FAILED"}: ${f.name}`;
+    if (f.message) for (const line of f.message.trim().split("\n")) out += `\n  ${line}`;
+    for (const frame of f.stack) out += `\n  ${frame}`;
+  }
+  return out;
+}
+
+/** `N failed, M passed`-style summary, or null — for a one-line collapsed row. */
+export function testCountLine(r: TestReport): string {
+  const parts: string[] = [];
+  if (r.failed > 0) parts.push(`${r.failed} failed`);
+  if (r.errors > 0) parts.push(`${r.errors} errors`);
+  if (r.passed > 0) parts.push(`${r.passed} passed`);
+  if (r.skipped > 0) parts.push(`${r.skipped} skipped`);
+  return parts.join(", ");
+}