@pify/shell-background 0.5.1 → 0.6.1

package/README.md

@@ -34,7 +34,7 @@ shell_kill { id: "bg-2" }                # stop it and its whole process tree
 
 ## Delivery, and the headless caveat
 
-When a backgrounded command finishes in an **interactive** session, its result is pushed into the conversation as the next turn — you do not have to poll. Under headless `pi -p` there is nothing to deliver into (the session tears down when the prompt resolves), so **auto-background is disabled there** and only explicit `background: true` applies; collect it within the same turn with `shell_status { id, wait: N }`, which blocks (up to `N` seconds, 0–300) until the command finishes rather than returning immediately. This is the same delivery rule the rest of the suite lives by. A finish that a `shell_status` wait returns is collected there and not delivered a second time, so the model never spends a turn acknowledging a result it has just reported.
+When a backgrounded command finishes in an **interactive** session, its result is pushed into the conversation as the next turn — you do not have to poll. Under headless `pi -p` there is nothing to deliver into (the session tears down when the prompt resolves), so **auto-background is disabled there** and only explicit `background: true` applies; collect it within the same turn with `shell_status { id, wait: N }`, which blocks (up to `N` seconds, 0–300) until the command finishes rather than returning immediately. This is the same delivery rule the rest of the suite lives by. A job's result is pushed only at the end of the current turn, not the instant the command exits, so a job you collect during the turn with `shell_status {id}` (with or without `wait`) is never also delivered as a follow-up — the model never spends a turn acknowledging a result it has just reported. A job nobody collects is delivered once when the turn ends, and a job that finishes while the agent is idle wakes it right away.
 
 ## How it works
 
@@ -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,
@@ -241,6 +242,47 @@ export default function shellBackground(pi: ExtensionAPI) {
   const waiters = new Map<string, number>();
   const awaited = (job: Job): boolean => (waiters.get(job.id) ?? 0) > 0;
 
+  // A finished job's result must reach the model exactly once, and NOT while
+  // the model may still collect it itself. The old code sent the follow-up the
+  // instant the process exited, so a `shell_status {id}` that collected the
+  // same job later in that turn got the result a second time (issue #2): the
+  // message was already queued when the job ended, and marking it collected
+  // afterwards was too late. So a finished job is held in `pending` and
+  // delivered only at a turn boundary (agent_settled) — or right away while
+  // idle, so a job finishing between turns still wakes the agent — and the
+  // drain skips any job a `shell_status` read marked `delivered` meanwhile.
+  // `waiters` still covers an ACTIVE wait, which returns and collects the
+  // result itself and so must never also be sent.
+  const pending = new Set<Job>();
+  let turnActive = false;
+
+  function enqueueDelivery(job: Job): void {
+    if (job.delivered) return;
+    pending.add(job);
+    maybeDrainDeliveries();
+  }
+
+  /** Drain now only while idle; during a turn the model may still collect a job, so wait for agent_settled. */
+  function maybeDrainDeliveries(): void {
+    if (!turnActive) drainDeliveries();
+  }
+
+  function drainDeliveries(): void {
+    for (const job of [...pending]) {
+      // Collected (by a shell_status read) since it was queued — never send it.
+      if (job.delivered) {
+        pending.delete(job);
+        continue;
+      }
+      // An active shell_status wait will return and collect this job itself.
+      if (awaited(job)) continue;
+      pending.delete(job);
+      job.delivered = true;
+      registry?.persist(job);
+      deliver(job);
+    }
+  }
+
   /** Deliver a finished background job into the conversation, once. */
   function scheduleDelivery(job: Job, exit: Promise<unknown>): void {
     exit
@@ -253,10 +295,7 @@ export default function shellBackground(pi: ExtensionAPI) {
           registry?.persist(job);
           return;
         }
-        if (job.delivered || awaited(job)) return;
-        job.delivered = true;
-        registry?.persist(job);
-        deliver(job);
+        enqueueDelivery(job);
       })
       .catch(() => {
         // A /reload can make captured handles throw; delivery is a convenience,
@@ -543,19 +582,17 @@ export default function shellBackground(pi: ExtensionAPI) {
       }
       if (sig?.aborted) {
         // The model never sees an aborted tool result. If the job finished
-        // while this wait held the delivery path back, deliver it now.
-        if (isFinished(job) && !job.delivered) {
-          job.delivered = true;
-          registry.persist(job);
-          deliver(job);
-        }
+        // while the wait held delivery back, hand it to the turn-boundary drain
+        // (it was not collected here) rather than dropping it.
+        if (isFinished(job) && !job.delivered) enqueueDelivery(job);
         return { content: [{ type: "text", text: `shell_status ${job.id}: wait aborted` }], details: { id: job.id }, isError: true };
       }
-      // Reading a finished job marks it collected so it will not also be
-      // delivered unasked. A still-running poll must never do this: setting
-      // delivered here would permanently cancel the promised auto-delivery.
+      // Reading a finished job marks it collected so the turn-boundary drain
+      // never also sends it (issue #2). A still-running poll must never do this:
+      // setting delivered here would permanently cancel the promised delivery.
       if (isFinished(job)) {
         job.delivered = true;
+        pending.delete(job);
         registry.persist(job);
       }
       return {
@@ -641,11 +678,7 @@ export default function shellBackground(pi: ExtensionAPI) {
           }
         }
         if (job.status === "running") anyRunning = true;
-        else if (!job.delivered && !awaited(job)) {
-          job.delivered = true;
-          registry.persist(job);
-          deliver(job);
-        }
+        else enqueueDelivery(job);
       }
       renderWidget(ctx);
       if (!anyRunning) clearInterval(timer);
@@ -653,6 +686,19 @@ export default function shellBackground(pi: ExtensionAPI) {
     timer.unref?.();
   }
 
+  // Turn boundaries drive delivery: a finished job is pushed only when the
+  // current turn ends, so a job the model collects during the turn is never
+  // also delivered as a follow-up (issue #2).
+  pi.on("agent_start", async (_event, ctx) => {
+    turnActive = true;
+    lastUiCtx = ctx;
+  });
+  pi.on("agent_settled", async (_event, ctx) => {
+    turnActive = false;
+    lastUiCtx = ctx;
+    drainDeliveries();
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     const warnings = loadSettings(ctx.cwd);
     const key = sessionKey(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/shell-background",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "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})`);