@pify/shell-background 0.2.0 → 0.3.0

package/README.md

@@ -53,11 +53,14 @@ Put these in `.pi/shell-background.json` (project) or `<agentDir>/shell-backgrou
 ```json
 {
   "autoBackgroundMs": 30000,
-  "tailBytes": 65536
+  "tailBytes": 65536,
+  "maxBackground": 8
 }
 ```
 
-`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 shows. 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 shows. `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.
+
+The tail a result carries is cleaned the way pi's own bash cleans what the model sees — ANSI escapes, control characters and carriage-return progress frames stripped — so a chatty build or dev server does not spend tokens on colour codes and thousands of overwritten progress lines. The log file on disk keeps every byte.
 
 ## Coexistence with @pify/pretty
 

package/extensions/shell-background.ts

@@ -47,6 +47,7 @@ import { buildEnv } from "../src/env.ts";
 import { DEFAULT_SETTINGS, resolveSettings, type ShellBgSettings } from "../src/config.ts";
 import { backgroundedResult, deliveryMessage, DELIVERY_TYPE } from "../src/pending.ts";
 import { formatResult, formatList, header } from "../src/format.ts";
+import { sanitizeOutput } from "../src/sanitize.ts";
 import { buildWidgetLines } from "../src/widget.ts";
 import { isFinished } from "../src/types.ts";
 import type { Job } from "../src/types.ts";
@@ -187,7 +188,7 @@ export default function shellBackground(pi: ExtensionAPI) {
   function snapshot(job: Job): ToolResult {
     const tail = readTail(job.logPath, settings.tailBytes);
     return {
-      content: [{ type: "text", text: `${header(job)}\n${tail.text.replace(/\n+$/, "") || "(no output yet)"}` }],
+      content: [{ type: "text", text: `${header(job)}\n${sanitizeOutput(tail.text).replace(/\n+$/, "") || "(no output yet)"}` }],
       details: { id: job.id, status: job.status },
     };
   }
@@ -248,6 +249,27 @@ export default function shellBackground(pi: ExtensionAPI) {
     const command = String(params.command ?? "").trim();
     if (!command) return { content: [{ type: "text", text: "Empty command." }], details: {}, isError: true };
 
+    // The cap bounds how many jobs may be alive, not whether a command runs:
+    // an explicit background request over it is refused (the model can still
+    // run the command in the foreground); an auto-background transition over
+    // it is skipped and the command simply stays in the foreground.
+    const liveOthers = (self?: string) => registry!.running().filter((j) => j.id !== self).length;
+    if (params.background && liveOthers() >= settings.maxBackground) {
+      const n = liveOthers();
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `${n} background command${n === 1 ? " is" : "s are"} already running (maxBackground = ${settings.maxBackground}). ` +
+              `shell_kill one you no longer need, wait for one with shell_status {id, wait}, or run this in the foreground without background:true.`,
+          },
+        ],
+        details: { running: n, limit: settings.maxBackground },
+        isError: true,
+      };
+    }
+
     const job = registry.create(command, ctx.cwd);
     const { shell, args } = shellArgv();
 
@@ -316,13 +338,31 @@ export default function shellBackground(pi: ExtensionAPI) {
 
     try {
       const race: Array<Promise<string>> = [settle.then(() => "exit")];
-      if (autoMs > 0) race.push(after(autoMs, "auto"));
       if (params.timeout && params.timeout > 0) race.push(after(params.timeout * 1000, "timeout"));
       if (signal) race.push(abort);
 
-      const outcome = await Promise.race(race);
+      let outcome = await Promise.race(autoMs > 0 ? [...race, after(autoMs, "auto")] : race);
+
+      // Over the cap, the threshold passes without moving the command: it is
+      // never refused, it just keeps its foreground slot until it ends.
+      let keptForeground = false;
+      if (outcome === "auto" && liveOthers(job.id) >= settings.maxBackground) {
+        keptForeground = true;
+        outcome = await Promise.race(race);
+      }
 
-      if (outcome === "exit") return finished(job);
+      if (outcome === "exit") {
+        const r = finished(job);
+        if (keptForeground) {
+          r.content = [
+            {
+              type: "text",
+              text: `${r.content[0]?.text ?? ""}\n\n[kept in the foreground: ${settings.maxBackground} background commands were already running]`,
+            },
+          ];
+        }
+        return r;
+      }
 
       if (outcome === "auto") {
         scheduleDelivery(job, settle);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/shell-background",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -63,9 +63,9 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
+    "@earendil-works/pi-ai": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "^0.87.0",
+    "@earendil-works/pi-tui": "^0.87.0",
     "@types/node": "^22.10.2",
     "typebox": "^1.1.38",
     "typescript": "^5.7.2"

package/src/config.ts

@@ -14,11 +14,21 @@ export interface ShellBgSettings {
   autoBackgroundMs: number;
   /** Bytes of the log tail shown in a status/collect result. */
   tailBytes: number;
+  /**
+   * How many jobs may be alive at once before a request to background one
+   * more is refused and an auto-background transition is skipped. Every live
+   * job is a whole process tree plus an open log; a session that keeps
+   * starting servers and watchers should hear about it rather than
+   * accumulate them without bound. Only the backgrounding decision is capped
+   * — a command itself is never refused.
+   */
+  maxBackground: number;
 }
 
 export const DEFAULT_SETTINGS: ShellBgSettings = {
   autoBackgroundMs: 30_000,
   tailBytes: 64 * 1024,
+  maxBackground: 8,
 };
 
 const LIMITS: Record<keyof ShellBgSettings, { min: number; max: number }> = {
@@ -26,6 +36,7 @@ const LIMITS: Record<keyof ShellBgSettings, { min: number; max: number }> = {
   // does not make every command look long-running.
   autoBackgroundMs: { min: 0, max: 3_600_000 },
   tailBytes: { min: 1024, max: 4 * 1024 * 1024 },
+  maxBackground: { min: 1, max: 64 },
 };
 
 export function resolveSettings(

package/src/format.ts

@@ -4,6 +4,7 @@
  */
 import type { Job } from "./types.ts";
 import { readTail, countLines } from "./tail.ts";
+import { sanitizeOutput } from "./sanitize.ts";
 
 function secs(ms: number): string {
   if (ms < 1000) return `${ms}ms`;
@@ -38,14 +39,17 @@ export function header(job: Job): string {
  */
 export function formatResult(job: Job, tailBytes: number): string {
   const tail = readTail(job.logPath, tailBytes);
+  // Cleaned the way pi's own bash cleans its output for the model; the log on
+  // disk (which the truncation note points at) keeps every byte.
+  const text = sanitizeOutput(tail.text);
   const lines = [header(job)];
-  if (tail.text.trim() === "") {
+  if (text.trim() === "") {
     lines.push(job.status === "running" ? "(no output yet)" : "(no output)");
   } else {
     if (tail.truncated) {
-      lines.push(`… showing the last ${countLines(tail.text)} lines — full log: ${job.logPath}`);
+      lines.push(`… showing the last ${countLines(text)} lines — full log: ${job.logPath}`);
     }
-    lines.push(tail.text.replace(/\n+$/, ""));
+    lines.push(text.replace(/\n+$/, ""));
   }
   return lines.join("\n");
 }

package/src/sanitize.ts

@@ -0,0 +1,50 @@
+/**
+ * The same cleaning pi's own bash tool applies to what the model sees
+ * (bash-executor.ts: `sanitizeBinaryOutput(stripAnsi(text)).replace(/\r/g, "")`).
+ *
+ * This package re-registers `bash`, and a job's log is captured raw on disk on
+ * purpose (the detached spawn writes straight to a file; no in-process pipes).
+ * Without this step the tail handed back for a chatty build or dev server is
+ * escape codes and carriage-return progress frames — tokens the native tool
+ * would never have spent. The on-disk log stays byte-for-byte; only the text
+ * that reaches the model is cleaned. Zero dependencies: pi does not export
+ * these helpers, so the regex (ansi-regex, MIT) and the code-point filter are
+ * vendored here verbatim.
+ */
+
+// Valid string terminator sequences are BEL, ESC\, and 0x9c
+const ST = "(?:\\u0007|\\u001B\\u005C|\\u009C)";
+// OSC sequences only: ESC ] ... ST (non-greedy until the first ST)
+const OSC = `(?:\\u001B\\][\\s\\S]*?${ST})`;
+// CSI and related: ESC/C1, optional intermediates, optional params (supports ; and :) then final byte
+const CSI = "[\\u001B\\u009B][[\\]()#;?]*(?:\\d{1,4}(?:[;:]\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]";
+const ANSI = new RegExp(`${OSC}|${CSI}`, "g");
+
+export function stripAnsi(text: string): string {
+  // Fast path: ANSI codes require ESC (7-bit) or CSI (8-bit) introducer.
+  if (!text.includes("\u001B") && !text.includes("\u009B")) return text;
+  return text.replace(ANSI, "");
+}
+
+/**
+ * Drop characters that crash string-width or corrupt a terminal: control
+ * characters (except tab/newline/CR), Unicode format characters, lone
+ * surrogates and undefined code points.
+ */
+export function sanitizeBinaryOutput(text: string): string {
+  return Array.from(text)
+    .filter((char) => {
+      const code = char.codePointAt(0);
+      if (code === undefined) return false;
+      if (code === 0x09 || code === 0x0a || code === 0x0d) return true;
+      if (code <= 0x1f) return false;
+      if (code >= 0xfff9 && code <= 0xfffb) return false;
+      return true;
+    })
+    .join("");
+}
+
+/** Exactly what pi's bash gives the model: no ANSI, no control noise, no `\r`. */
+export function sanitizeOutput(text: string): string {
+  return sanitizeBinaryOutput(stripAnsi(text)).replace(/\r/g, "");
+}