@chrok/pi-braid 0.3.6 → 0.4.0

package/README.md

@@ -5,29 +5,34 @@
 This optional Pi extension runs Braid agent graphs as background jobs by default, with
 bounded loops, live updates, pause/resume, and a live flow panel.
 
-**0.3 API:** The npm badge shows the published version; see
+**0.4 API:** The npm badge shows the published version; see
 [GitHub releases](https://github.com/Epsirom/braid/releases) for release notes.
-Review the [0.2 → 0.3 migration guide](https://github.com/Epsirom/braid/blob/v0.3.0/docs/compatibility.md#migrating-from-02-to-03)
-before upgrading: writable nodes now have shell tools, checkpoints exclude
-untracked ignored outputs, and reminders can interrupt work between model steps.
-Users coming from 0.1 also need the
-[0.1 → 0.2 guide](https://github.com/Epsirom/braid/blob/v0.3.0/docs/compatibility.md#migrating-from-01-to-02).
+Review the [0.3 → 0.4 migration guide](https://github.com/Epsirom/braid/blob/v0.4.0/docs/compatibility.md#migrating-from-03-to-04)
+before upgrading: print and JSON runs wait for background jobs, Pi SDK sessions
+in the default print mode drain jobs before `session.prompt()` returns, and
+blocking mode is deprecated. Users coming from 0.2 also need the
+[0.2 → 0.3 guide](https://github.com/Epsirom/braid/blob/v0.4.0/docs/compatibility.md#migrating-from-02-to-03),
+and users coming from 0.1 the
+[0.1 → 0.2 guide](https://github.com/Epsirom/braid/blob/v0.4.0/docs/compatibility.md#migrating-from-01-to-02).
 For the previous release, use the
-[0.2.1 guide](https://github.com/Epsirom/braid/blob/v0.2.1/integrations/pi/README.md).
+[0.3.6 guide](https://github.com/Epsirom/braid/blob/v0.3.6/integrations/pi/README.md).
 
 It registers:
 
 - `braid` — submit a graph with optional bounded loops; receive a `jobId`
-  immediately in background mode, or final results in experimental blocking mode.
+  immediately in background mode (print/JSON runs wait for it before exiting), or
+  final results in deprecated blocking mode.
 - `braid_status` — retrieve progress and results with `{ "jobId": "..." }`, or
   add `"executionId": "..."` for an exact invocation's full output/error.
   `"nodeId": "..."` selects that definition's latest invocation. Omit all IDs
   to list jobs in the current session.
 - `braid_update` / `braid_resume` — edit live definitions or release paused executions.
 - `braid_cancel` — cancel a job with `{ "jobId": "..." }`.
+- `braid_finish` — print/JSON runs only: record the run outcome with
+  `{ "status": "success" | "failure", "summary": "..." }`.
 - `/braid [jobId]` — open a live flow panel in interactive Pi.
-- `/braid:blocking [on|off]` — experimental: enable or disable blocking for new `braid` tool calls;
-  omit the argument to show the current mode.
+- `/braid:blocking [on|off]` — deprecated, removed in 0.5.0: enable or disable
+  blocking for new `braid` tool calls; omit the argument to show the current mode.
 - `/braid:review [target or focus]` — run a bounded parallel review/fix loop.
 - `/braid:clear` — clear the progress widget above the editor; run it again while
   the widget is empty to restore what was cleared.
@@ -53,12 +58,65 @@ work, or end its turn if it needs the result, and not to sleep, use a timer, or
 poll in a loop to wait for the job.
 Stopping the foreground response does not stop background jobs.
 
-> **Experimental:** blocking mode is a stopgap for single-shot runs. Its flag,
-> command, and behavior may change or be replaced by an async-preserving CI mode
-> that keeps reminders, `pauseAfter`, and live updates
-> ([#80](https://github.com/Epsirom/braid/issues/80)).
+### Single-shot and CI runs
 
-For CI or other single-shot runs, enable blocking manually when starting Pi:
+In print mode (`pi -p`) and `--mode json`, background execution works unchanged:
+the run stays open until every Braid job reaches a terminal status and its
+reminder has been delivered, then exits after the parent's final response.
+
+```sh
+pi -p "Use Braid to review the changes and summarize the results."
+```
+
+The parent submits, ends its turn, and is resumed by the reminder as in
+interactive Pi, so `pauseAfter`, `notifyOnCompletion`, `braid_update`, and
+`braid_resume` keep working. Paused executions are never resumed automatically.
+If the parent ends its turn while only paused executions remain, it receives one
+warning naming them; ending the next turn without resuming them cancels their
+jobs, gives the parent a final turn on the cancellation reminder, and exits 1.
+
+`--braid-ci-timeout <duration>` bounds the whole run, starting at its first
+prompt. It accepts milliseconds or an `s`, `m`, or `h` suffix (for example
+`--braid-ci-timeout 30m`). On expiry, outstanding jobs are cancelled, the parent
+gets a final turn on the cancellation reminders, and the run exits 1. Either
+forced cancellation prints a `Braid:` line on stderr.
+
+A failed graph does not by itself fail the run. Instead, the parent is told to
+call `braid_finish` with `status` `success` or `failure` and a short `summary`
+once the task is done. The tool only records the outcome; the run still ends
+when the parent ends its turn with no Braid job outstanding, and a later call
+replaces the earlier outcome. A final `failure` exits 1 and prints
+`Braid: run reported failure: <summary>` on stderr. `success` never overrides a
+non-zero exit from a forced cancellation or from Pi itself. If the parent never
+calls it, the exit status is Pi's own apart from forced cancellations.
+
+In `--mode json`, the final outcome is also written as a session entry, after the
+`tool_execution_end` event of the call itself:
+
+```json
+{"type":"entry_appended","entry":{"type":"custom","customType":"braid-finish","data":{"status":"failure","summary":"Review found 2 blocking issues.","forcedFailures":[]},...}}
+```
+
+`forcedFailures` lists any forced cancellations, which fail the run whatever the
+reported status. The entry is not part of model context, and text mode still
+prints only the parent's final response. `braid_finish` is not offered in
+interactive or RPC sessions.
+
+Pi SDK sessions default to print mode too, so `session.prompt()` returns only
+after outstanding Braid jobs drain. Hosts that stay running and want reminders
+to start new runs after settling should bind with another mode, for example
+`session.bindExtensions({ mode: "rpc" })`.
+
+### Blocking mode (deprecated)
+
+> **Deprecated:** `--braid-blocking` and `/braid:blocking` will be removed in
+> 0.5.0. Print and JSON runs now wait for background jobs (see above), which keeps
+> `pauseAfter`, reminders, and live updates, and `braid_finish` sets the exit
+> status. To migrate, drop `--braid-blocking` (or `/braid:blocking on`) from the
+> command line ([#80](https://github.com/Epsirom/braid/issues/80)). Using either
+> prints a one-time warning: on stderr in print/JSON mode, or as a UI notice.
+
+Until then, to make each `braid` call wait in the foreground, enable blocking when starting Pi:
 
 ```sh
 pi --braid-blocking -p "Use Braid to review the changes and summarize the results."

package/dist/drain.js

@@ -0,0 +1,165 @@
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { defineTool, } from "@earendil-works/pi-coding-agent";
+/** Pi exits once print and JSON runs settle, so Braid drains jobs before that. */
+export const isSingleShot = (ctx) => ctx.mode === "print" || ctx.mode === "json";
+export const BRAID_DRAIN_GUIDANCE = "This is a single-shot run. It stays open until every Braid job finishes and its reminder is delivered, so submit, end your turn, and continue from the reminder as usual. " +
+    "Paused executions are not resumed automatically: resume or cancel them before ending your turn. If only paused executions remain when you end a turn, you get one warning; ending the next turn without resuming them cancels their jobs and the run exits with a failure status.";
+export const BRAID_FINISH_GUIDANCE = "When the task is done and no Braid job is outstanding, call braid_finish once with status success or failure and a short summary of the outcome, then end your turn with your final response. " +
+    "A failure status makes the run exit 1. braid_finish only records the outcome: the run still ends when your turn ends and every Braid job has finished. Call it again to replace the outcome if more work follows.";
+/** The run's wall-clock budget is checked by a timer, so the drain also wakes periodically. */
+const RECHECK_MS = 1_000;
+export function parseDuration(value) {
+    const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h)?\s*$/.exec(value);
+    const scale = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000 };
+    const ms = match ? Number(match[1]) * scale[(match[2] ?? "ms")] : NaN;
+    if (!(ms > 0) || ms > 2_147_483_647)
+        throw new Error(`Invalid --braid-ci-timeout ${JSON.stringify(value)}: use a positive duration such as 90000, 90s, 30m, or 2h`);
+    return ms;
+}
+const stalledReminder = (jobs) => `[system-reminder] This single-shot run cannot end while Braid jobs are outstanding, and nothing can progress: ` +
+    jobs.map(job => `${job.handle} is waiting on paused executions ${JSON.stringify(job.pausedExecutionIds)} at revision ${job.revision}`).join("; ") +
+    `. Resume them with braid_resume or braid_update with resume, or cancel the job with braid_cancel, then continue the original task. ` +
+    `If you end your turn again without doing so, Braid cancels these jobs and the run exits with a failure status. [/system-reminder]`;
+/**
+ * Keeps print and JSON runs alive until every Braid job reaches a terminal
+ * status. Reminders are steered into the run as in interactive mode, so the
+ * parent keeps the async model: it ends its turn and the reminder resumes it.
+ */
+export function registerDrain(pi, jobs, hasPendingReminders) {
+    pi.registerFlag("braid-ci-timeout", {
+        description: "Wall-clock budget for Braid jobs in print/JSON mode (e.g. 90000, 90s, 30m, 2h); on expiry, outstanding jobs are cancelled and the run exits 1",
+        type: "string",
+    });
+    let closed = false;
+    let timer;
+    let timedOut = false;
+    let warnedStall;
+    const failures = new Set();
+    let outcome;
+    let reported;
+    const fail = (reason) => {
+        if (failures.has(reason))
+            return;
+        failures.add(reason);
+        process.exitCode = 1;
+        console.error(`Braid: ${reason}`);
+    };
+    const cancelOutstanding = (reason) => {
+        const outstanding = jobs.outstanding();
+        if (!outstanding.length)
+            return;
+        fail(reason);
+        for (const job of outstanding)
+            jobs.cancel(job.jobId);
+    };
+    const expire = () => {
+        timedOut = true;
+        cancelOutstanding("--braid-ci-timeout expired; cancelled outstanding Braid jobs");
+    };
+    const nextChange = () => new Promise(resolve => {
+        const done = () => {
+            clearTimeout(tick);
+            unsubscribe();
+            resolve();
+        };
+        const tick = setTimeout(done, RECHECK_MS);
+        const unsubscribe = jobs.subscribe(done);
+    });
+    const finishParameters = Type.Object({
+        status: StringEnum(["success", "failure"], { description: "Whether the run achieved its task. failure makes the process exit 1." }),
+        summary: Type.String({ minLength: 1, description: "Short summary of the outcome for CI logs and JSON output." }),
+    }, { additionalProperties: false });
+    pi.registerTool(defineTool({
+        name: "braid_finish",
+        label: "Finish Braid run",
+        description: "Single-shot (print/JSON) runs only: record the run outcome for CI. status failure makes the process exit 1. " +
+            "It does not end the run; call it once the task is done and no Braid job is outstanding, then end your turn. A later call replaces the outcome.",
+        parameters: finishParameters,
+        // Activated in single-shot sessions only, so interactive runs never see it.
+        defaultActive: false,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            if (!isSingleShot(ctx))
+                throw new Error("braid_finish is only available in print and JSON runs");
+            outcome = { status: params.status, summary: params.summary };
+            const outstanding = jobs.outstanding().length;
+            return {
+                content: [{
+                        type: "text",
+                        text: `Recorded ${params.status}.` + (outstanding
+                            ? ` ${outstanding} Braid job(s) are still outstanding; the run stays open until they finish, so continue from their reminders and call braid_finish again if the outcome changes.`
+                            : " End your turn with your final response."),
+                    }],
+                details: outcome,
+            };
+        },
+    }));
+    /** Applies the reported outcome once the run is about to settle with nothing outstanding. */
+    const settle = (event) => {
+        if (!outcome || outcome === reported)
+            return;
+        reported = outcome;
+        // Never reset the exit code: success must not mask a forced cancellation or a Pi error.
+        if (outcome.status === "failure") {
+            process.exitCode = 1;
+            console.error(`Braid: run reported failure: ${outcome.summary}`);
+        }
+        // A custom entry is not model context and leaves the final assistant message last,
+        // so text output is unchanged; JSON mode streams it as an entry_appended event.
+        return {
+            entries: [...event.entries, {
+                    type: "custom",
+                    customType: "braid-finish",
+                    data: { ...outcome, forcedFailures: [...failures] },
+                }],
+        };
+    };
+    pi.on("session_start", (_event, ctx) => {
+        if (isSingleShot(ctx) && !pi.getActiveTools().includes("braid_finish"))
+            pi.setActiveTools([...pi.getActiveTools(), "braid_finish"]);
+    });
+    pi.on("before_agent_start", (_event, ctx) => {
+        const budget = pi.getFlag("braid-ci-timeout");
+        if (timer || timedOut || !isSingleShot(ctx) || typeof budget !== "string")
+            return;
+        // The budget covers the whole run, starting at its first prompt.
+        timer = setTimeout(expire, parseDuration(budget));
+        timer.unref();
+    });
+    pi.on("agent_before_settle", async (event, ctx) => {
+        if (!isSingleShot(ctx))
+            return;
+        while (!closed) {
+            // A queued reminder continues this run; Pi settles only when its queues are empty.
+            if (hasPendingReminders())
+                return;
+            if (timedOut)
+                cancelOutstanding("--braid-ci-timeout expired; cancelled outstanding Braid jobs");
+            const outstanding = jobs.outstanding();
+            if (!outstanding.length)
+                return settle(event);
+            if (outstanding.every(job => job.stalled)) {
+                const key = JSON.stringify(outstanding.map(job => [job.jobId, job.revision, job.pausedExecutionIds]));
+                if (key !== warnedStall) {
+                    warnedStall = key;
+                    return {
+                        entries: [...event.entries, {
+                                type: "custom_message",
+                                customType: "braid-drain-stalled",
+                                display: true,
+                                content: stalledReminder(outstanding),
+                                details: { jobs: outstanding },
+                            }],
+                        continue: true,
+                    };
+                }
+                // Cancellation reminders give the parent a final turn to report the outcome.
+                cancelOutstanding(`paused executions were never resumed; cancelled ${outstanding.map(job => job.handle).join(", ")}`);
+            }
+            await nextChange();
+        }
+    });
+    pi.on("session_shutdown", () => {
+        closed = true;
+        clearTimeout(timer);
+    });
+}

package/dist/index.js

@@ -7,6 +7,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { BraidJobs } from "./jobs.js";
 import { registerBraidCommand, registerBraidWidget } from "./command.js";
 import { registerReviewCommand } from "./review.js";
+import { BRAID_DRAIN_GUIDANCE, BRAID_FINISH_GUIDANCE, isSingleShot, registerDrain } from "./drain.js";
 import { renderGraphCall, renderGraphResult, renderNodeResult } from "./display.js";
 import { formatJobList, formatJobStatus, formatNodeStatus, formatReceipt, formatResume, formatUpdate } from "./status-text.js";
 const text = (description) => Type.String({ minLength: 1, pattern: "\\S", ...(description ? { description } : {}) });
@@ -97,6 +98,8 @@ export const BRAID_ASYNC_GUIDANCE = "By default, Braid is asynchronous: braid re
     "Do not call sleep, run a shell sleep, use a timer, or enter a sleep/poll loop solely to wait for a Braid job; delays required by the user's actual task remain allowed. " +
     "On the reminder, retrieve terminal outputs with braid_status before relying on them and continue the original task. Between reminders, use braid_status only for deliberate progress checks or diagnosis. " +
     "Set notifyOnCompletion=true on selected nodes to receive intermediate success/failure reminders. Use braid_status({jobId, executionId}) to retrieve the exact execution; nodeId selects the latest instance. Use pauseAfter=true to hold outgoing scheduling. Definitions can always be changed with braid_update using expectedRevision; existing executions retain their captured inputs. Use resume in the same update to apply changes and release held executions atomically, or braid_resume for no graph changes.";
+export const BRAID_BLOCKING_DEPRECATION = "Blocking mode (--braid-blocking, /braid:blocking) is deprecated and will be removed in 0.5.0. " +
+    "Print and JSON runs (pi -p) now wait for background Braid jobs; call braid_finish to report the outcome.";
 /** Short reminder repeated in every submission receipt. */
 export const BRAID_WAIT_REMINDER = "Braid runs asynchronously and notifies you when the job finishes. Continue independent work, or end your turn if you need the result before proceeding; the completion reminder will resume you. " +
     "Do not sleep or poll in a loop to wait for this job. Retrieve its results with braid_status after the reminder.";
@@ -371,20 +374,33 @@ export function createBraidTools(jobs, blocking = () => false) {
 }
 export default function braidExtension(pi) {
     pi.registerFlag("braid-blocking", {
-        description: "Experimental: wait for braid tool calls to finish in the foreground (for CI/print mode)",
+        description: "Deprecated, removed in 0.5.0: wait for braid tool calls to finish in the foreground. pi -p now waits for background jobs",
         type: "boolean",
         default: false,
     });
     let sessionBlocking;
     const blocking = () => sessionBlocking ?? (pi.getFlag("braid-blocking") === true);
+    let warnedBlocking = false;
+    const warnBlocking = (ctx) => {
+        if (warnedBlocking)
+            return;
+        warnedBlocking = true;
+        // Print and JSON runs have no UI; stderr keeps JSON stdout parseable.
+        if (ctx.hasUI)
+            ctx.ui.notify(BRAID_BLOCKING_DEPRECATION, "warning");
+        else
+            console.error(`Braid: ${BRAID_BLOCKING_DEPRECATION}`);
+    };
     pi.registerCommand("braid:blocking", {
-        description: "Experimental: set blocking mode for new braid tool calls: /braid:blocking [on|off]; omit to show the current mode",
+        description: "Deprecated, removed in 0.5.0: set blocking mode for new braid tool calls: /braid:blocking [on|off]; omit to show the current mode",
         handler: async (args, ctx) => {
             const setting = args.trim().toLowerCase();
             if (setting === "on" || setting === "off")
                 sessionBlocking = setting === "on";
             else if (setting)
                 throw new Error("Usage: /braid:blocking [on|off]");
+            if (setting === "on")
+                warnBlocking(ctx);
             ctx.ui.notify(`Braid blocking mode: ${blocking() ? "on" : "off"}. Applies to new braid tool calls.`, "info");
         },
     });
@@ -441,6 +457,7 @@ export default function braidExtension(pi) {
         }
     });
     const { braidTool, statusTool, cancelTool, updateTool, resumeTool } = createBraidTools(jobs, blocking);
+    registerDrain(pi, jobs, () => pending.size > 0);
     registerBraidCommand(pi, jobs);
     registerReviewCommand(pi, jobs);
     const disposeWidget = registerBraidWidget(pi, jobs);
@@ -454,7 +471,11 @@ export default function braidExtension(pi) {
         jobs.dispose();
         disposeWidget();
     });
-    pi.on("before_agent_start", (event) => ({
-        systemPrompt: `${event.systemPrompt}\n\n## Braid execution policy\n${BRAID_USAGE_GUIDANCE}\n${blocking() ? "Blocking mode is enabled for this session. " + BRAID_BLOCKING_GUIDANCE : BRAID_ASYNC_GUIDANCE}\n\nFor the current user request, make this delegation choice before using read, grep, find, edit, write, or bash. Completion reminders refer to existing jobs: retrieve their results instead of submitting the same graph again.`,
-    }));
+    pi.on("before_agent_start", (event, ctx) => {
+        if (pi.getFlag("braid-blocking") === true)
+            warnBlocking(ctx);
+        return {
+            systemPrompt: `${event.systemPrompt}\n\n## Braid execution policy\n${BRAID_USAGE_GUIDANCE}\n${blocking() ? "Blocking mode is enabled for this session. " + BRAID_BLOCKING_GUIDANCE : BRAID_ASYNC_GUIDANCE}${isSingleShot(ctx) ? `\n${BRAID_DRAIN_GUIDANCE}\n${BRAID_FINISH_GUIDANCE}` : ""}\n\nFor the current user request, make this delegation choice before using read, grep, find, edit, write, or bash. Completion reminders refer to existing jobs: retrieve their results instead of submitting the same graph again.`,
+        };
+    });
 }

package/dist/jobs.js

@@ -313,6 +313,23 @@ export class BraidJobs {
         }))
             .reverse();
     }
+    /**
+     * Jobs that have not reached a terminal status. A job is stalled when only
+     * paused executions remain, so it cannot progress without resume or cancel.
+     */
+    outstanding() {
+        return [...this.jobs.values()].filter(job => job.status === "running").map(job => {
+            // Skip the snapshot copy while executions are visibly running.
+            const state = job.runningExecutions.size ? undefined : job.run?.snapshot();
+            return {
+                jobId: job.jobId,
+                handle: job.handle,
+                stalled: state?.status === "waiting",
+                ...(state ? { revision: state.revision } : {}),
+                pausedExecutionIds: state?.pausedExecutionIds ?? [],
+            };
+        });
+    }
     /** Editor progress without copying outputs, transcripts, or execution snapshots. */
     progress(jobId) {
         const job = this.lookup(jobId);

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "license": "MIT",
   "description": "Pi extension for Braid: background agent graphs, bounded loops, live updates, and a flow panel",
   "type": "module",
   "dependencies": {
     "grok-mermaid": "^0.2.2",
-    "@chrok/braid": "0.3.6"
+    "@chrok/braid": "0.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",