@pify/shell-background 0.3.0 → 0.4.0

package/README.md

@@ -60,6 +60,10 @@ Put these in `.pi/shell-background.json` (project) or `<agentDir>/shell-backgrou
 
 `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.
 
+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, 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

@@ -48,13 +48,21 @@ import { DEFAULT_SETTINGS, resolveSettings, type ShellBgSettings } from "../src/
 import { backgroundedResult, deliveryMessage, DELIVERY_TYPE } from "../src/pending.ts";
 import { formatResult, formatList, header } from "../src/format.ts";
 import { sanitizeOutput } from "../src/sanitize.ts";
+import { readFull } from "../src/tail.ts";
+import { STRUCTURED_OUTPUT_MAX_BYTES, bashOutputSchema, buildStructured, type BashStructured } from "../src/structured.ts";
 import { buildWidgetLines } from "../src/widget.ts";
 import { isFinished } from "../src/types.ts";
 import type { Job } from "../src/types.ts";
 
 type UiContext = ExtensionContext;
 type AnyTool = { name: string; execute: (...a: never[]) => unknown; [k: string]: unknown };
-type ToolResult = { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown>; isError?: boolean };
+type ToolResult = {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  /** pi 0.99: what codemode scripts and ctx.executeTool() callers receive instead of the text. */
+  structuredContent?: BashStructured;
+  isError?: boolean;
+};
 
 const WIDGET = "shell-bg";
 
@@ -193,10 +201,16 @@ export default function shellBackground(pi: ExtensionAPI) {
     };
   }
 
+  /** The structured half of any result about a job: the whole log (bounded) plus status, for scripts. */
+  function structured(job: Job): BashStructured {
+    return buildStructured(job, readFull(job.logPath, STRUCTURED_OUTPUT_MAX_BYTES));
+  }
+
   function finished(job: Job): ToolResult {
     return {
       content: [{ type: "text", text: formatResult(job, settings.tailBytes) }],
       details: { id: job.id, status: job.status, exitCode: job.exitCode, signal: job.signal, background: false },
+      structuredContent: structured(job),
       isError: job.status === "failed",
     };
   }
@@ -314,7 +328,7 @@ export default function shellBackground(pi: ExtensionAPI) {
         interactive: ctx.hasUI,
         collectWith: "shell_status",
       });
-      return { content: [{ type: "text", text: r.text }], details: r.details };
+      return { content: [{ type: "text", text: r.text }], details: r.details, structuredContent: structured(job) };
     }
 
     // Foreground: race the process against the auto-background threshold, an
@@ -387,7 +401,7 @@ export default function shellBackground(pi: ExtensionAPI) {
           interactive: ctx.hasUI,
           collectWith: "shell_status",
         });
-        return { content: [{ type: "text", text: r.text }], details: r.details };
+        return { content: [{ type: "text", text: r.text }], details: r.details, structuredContent: structured(job) };
       }
 
       // timeout or abort: stop the tree, let the record settle, report partial.
@@ -411,6 +425,7 @@ export default function shellBackground(pi: ExtensionAPI) {
             },
           ],
           details: { id: job.id, status: job.status },
+          structuredContent: structured(job),
           isError: true,
         };
       }
@@ -421,6 +436,7 @@ export default function shellBackground(pi: ExtensionAPI) {
       return {
         content: [{ type: "text", text: formatResult(job, settings.tailBytes) + note }],
         details: { id: job.id, status: job.status },
+        structuredContent: structured(job),
         isError: true,
       };
     } finally {
@@ -466,6 +482,10 @@ export default function shellBackground(pi: ExtensionAPI) {
         ),
       }),
       promptGuidelines: guidelines,
+      // pi 0.99: scripts and ctx.executeTool() callers receive structuredContent
+      // instead of the text. Same fields as pi's bash, plus status/job_id;
+      // exit_code is absent while the command still runs in the background.
+      outputSchema: bashOutputSchema,
       // Let pi render the result with its default text renderer; keep the call
       // renderer (it only needs the command) if the original had one.
       renderResult: undefined,
@@ -514,6 +534,7 @@ export default function shellBackground(pi: ExtensionAPI) {
       return {
         content: [{ type: "text", text: formatResult(job, settings.tailBytes) }],
         details: { id: job.id, status: job.status, exitCode: job.exitCode },
+        structuredContent: structured(job),
       };
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/shell-background",
-  "version": "0.3.0",
+  "version": "0.4.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.87.0",
-    "@earendil-works/pi-coding-agent": "^0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
+    "@earendil-works/pi-ai": "^0.99.0",
+    "@earendil-works/pi-coding-agent": "^0.99.0",
+    "@earendil-works/pi-tui": "^0.99.0",
     "@types/node": "^22.10.2",
     "typebox": "^1.1.38",
     "typescript": "^5.7.2"

package/src/env.ts

@@ -17,6 +17,37 @@
  */
 import { delimiter } from "node:path";
 
+/**
+ * Defaults that keep an unattended child from waiting on a human. FORCED —
+ * they win over the inherited value — because a background job has no one
+ * to answer: `git commit` without -m must not open $EDITOR, `git fetch` over
+ * https must not prompt for a password. With stdin ignored such a prompt
+ * either hangs forever or sits until the tree is killed, and while it waits
+ * it holds one of the maxBackground slots. (Set from oh-my-pi's
+ * non-interactive-env; the editor becomes `true`, which exits 0 with the
+ * message untouched, so git aborts with "empty commit message" instead.)
+ */
+export const NON_INTERACTIVE_FORCED: Readonly<Record<string, string>> = {
+  GIT_TERMINAL_PROMPT: "0",
+  GIT_EDITOR: "true",
+  EDITOR: "true",
+  VISUAL: "true",
+};
+
+/**
+ * Formatting-only defaults, applied UNDER the inherited env so an explicit
+ * value still wins: a pager only ever changes how output is shown, and to a
+ * pipe it is dead weight. Deliberately NOT here: CI=true and TERM=dumb —
+ * this package also runs dev servers and watchers, and those flags make many
+ * of them drop watch mode, change ports or strip the output the user wants.
+ */
+export const NON_INTERACTIVE_DEFAULTS: Readonly<Record<string, string>> = {
+  PAGER: "cat",
+  GIT_PAGER: "cat",
+  GH_PAGER: "cat",
+  LESS: "FRX",
+};
+
 /** The slice of the pi ExtensionContext this needs, kept structural for tests. */
 export interface EnvCtx {
   sessionManager?: { getSessionId?(): string; getSessionFile?(): string | undefined };
@@ -25,16 +56,18 @@ export interface EnvCtx {
 }
 
 /**
- * Copy `base`, prepend `binDir` to PATH when absent, and set the PI_* session
- * variables from `ctx`. The ctx reads are wrapped so a stale ctx after a
- * `/reload` degrades to plain env rather than failing the spawn.
+ * Copy `base`, prepend `binDir` to PATH when absent, set the PI_* session
+ * variables from `ctx`, and layer the non-interactive defaults (formatting
+ * ones under the base, the anti-hang ones over it). The ctx reads are
+ * wrapped so a stale ctx after a `/reload` degrades to plain env rather than
+ * failing the spawn.
  */
 export function buildEnv(
   ctx: EnvCtx,
   binDir: string,
   base: NodeJS.ProcessEnv = process.env,
 ): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = { ...base };
+  const env: NodeJS.ProcessEnv = { ...NON_INTERACTIVE_DEFAULTS, ...base, ...NON_INTERACTIVE_FORCED };
 
   // PATH is case-insensitive on Windows; find the real key so we do not create a
   // second, ignored "PATH" alongside an inherited "Path". Only prepend when the

package/src/structured.ts

@@ -0,0 +1,52 @@
+/**
+ * The machine-readable half of a result.
+ *
+ * pi 0.99's bash declares an `outputSchema` and returns `structuredContent`:
+ * the model still sees the text, but programmatic callers — codemode scripts,
+ * tools calling `ctx.executeTool("bash", …)` — receive the structured value
+ * (up to 1 MiB of output, not the model-facing tail). This package replaces
+ * that tool, so it has to speak the same shape or every script that reads
+ * `result.exit_code` breaks the moment it is installed. The fields pi's bash
+ * has are kept with the same names and meanings; `status` and `job_id` are
+ * added because a command here can still be running when the tool returns —
+ * in which case `exit_code` is absent, which is how a script tells.
+ */
+import { Type, type Static } from "typebox";
+import type { Job } from "./types.ts";
+import type { FullOutput } from "./tail.ts";
+
+export const STRUCTURED_OUTPUT_MAX_BYTES = 1024 * 1024;
+
+export const bashOutputSchema = Type.Object({
+  output: Type.String({
+    description: "Combined stdout and stderr, up to 1 MiB. Longer output keeps its first and last 512 KiB around an omission marker.",
+  }),
+  truncated: Type.Boolean({ description: "Whether `output` omits part of the command output" }),
+  full_output_path: Type.Optional(Type.String({ description: "The log file with the complete output, when truncated" })),
+  exit_code: Type.Optional(Type.Number({ description: "Absent while the command is still running in the background" })),
+  wall_time_seconds: Type.Number(),
+  status: Type.Union([
+    Type.Literal("running"),
+    Type.Literal("done"),
+    Type.Literal("failed"),
+    Type.Literal("killed"),
+    Type.Literal("orphaned"),
+  ]),
+  job_id: Type.String({ description: "Pass to shell_status to collect or check a running command" }),
+});
+
+export type BashStructured = Static<typeof bashOutputSchema>;
+
+/** Build the structured value for a job from its full log; `now` only matters while it runs. */
+export function buildStructured(job: Job, full: FullOutput, now: number = Date.now()): BashStructured {
+  const end = job.endedAt ?? now;
+  return {
+    output: full.content,
+    truncated: full.truncated,
+    ...(full.truncated ? { full_output_path: job.logPath } : {}),
+    ...(job.status !== "running" && typeof job.exitCode === "number" ? { exit_code: job.exitCode } : {}),
+    wall_time_seconds: Math.round(Math.max(0, end - job.startedAt) / 100) / 10,
+    status: job.status,
+    job_id: job.id,
+  };
+}

package/src/tail.ts

@@ -58,6 +58,57 @@ export function readTail(path: string, maxBytes: number = DEFAULT_TAIL_BYTES): T
   }
 }
 
+export interface FullOutput {
+  content: string;
+  /** True when `content` omits the middle of the log. */
+  truncated: boolean;
+  bytes: number;
+}
+
+/**
+ * The whole log, for callers that can take more than the model-facing tail
+ * (pi 0.99 hands a tool's `structuredContent` to codemode scripts). A log
+ * over `maxBytes` keeps its first and last `maxBytes / 2` bytes around an
+ * omission marker, cut at character boundaries — the same shape pi's own
+ * bash gives scripts, so a script written for it reads ours unchanged.
+ */
+export function readFull(path: string, maxBytes: number): FullOutput {
+  let fd: number;
+  try {
+    fd = openSync(path, "r");
+  } catch {
+    return { content: "", truncated: false, bytes: 0 };
+  }
+  try {
+    const size = fstatSync(fd).size;
+    if (size === 0) return { content: "", truncated: false, bytes: 0 };
+    const readAt = (start: number, len: number): Buffer => {
+      const buf = Buffer.allocUnsafe(len);
+      let read = 0;
+      while (read < len) {
+        const n = readSync(fd, buf, read, len - read, start + read);
+        if (n <= 0) break;
+        read += n;
+      }
+      return buf.subarray(0, read);
+    };
+    if (size <= maxBytes) return { content: readAt(0, size).toString("utf8"), truncated: false, bytes: size };
+    const headBytes = Math.floor(maxBytes / 2);
+    const tailBytes = maxBytes - headBytes;
+    const head = new TextDecoder().decode(readAt(0, headBytes), { stream: true });
+    let tail = readAt(size - tailBytes, tailBytes);
+    let i = 0;
+    while (i < tail.length && (tail[i]! & 0xc0) === 0x80) i++;
+    tail = tail.subarray(i);
+    const omitted = size - headBytes - tailBytes;
+    return { content: `${head}\n\n[... ${omitted} bytes omitted ...]\n\n${tail.toString("utf8")}`, truncated: true, bytes: size };
+  } catch {
+    return { content: "", truncated: false, bytes: 0 };
+  } finally {
+    closeSync(fd);
+  }
+}
+
 /** Non-empty line count of a chunk of text. */
 export function countLines(text: string): number {
   if (!text) return 0;