@pify/shell-background 0.5.1 → 0.6.0

package/README.md

@@ -55,11 +55,12 @@ 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.
 

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.1",
+  "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})`);