@chrok/pi-braid 0.3.4 → 0.3.5

package/README.md

@@ -44,8 +44,10 @@ On completion, failure, or cancellation, the extension sends a custom
 Pi queues it as steering during streaming: it enters context after the current
 assistant response and its entire tool batch, before the next model step. It
 does not wait for the whole foreground task to finish or skip remaining tools.
-When idle, it starts a new agent turn automatically. The agent should wait for
-this reminder rather than poll.
+When idle, it starts a new agent turn automatically. Tool descriptions, the
+system prompt, and the submission receipt tell the agent to continue independent
+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.
 
 Jobs live in memory for the current Pi session. Quitting, reloading extensions,
@@ -107,9 +109,10 @@ All four types accept `model`, `notifyOnCompletion`, `pauseAfter`, and
 default to writable worktrees in Git; outside Git, all workers are read-only.
 The model-facing schema exposes these fields in one object with a `type` enum;
 core validation enforces the type-specific requirements before a submission or
-update takes effect. Submission/update replies echo the accepted node types,
-model overrides, policies, and edges without repeating prompts. If a definition
-problem repeats, inspect/report the mismatch instead of launching more probe jobs.
+update takes effect. The submission reply gives the job ID and how to wait for
+it; it does not repeat the graph the agent just sent. Update replies list the
+resulting graph without prompts. If a definition problem repeats,
+inspect/report the mismatch instead of launching more probe jobs.
 
 Edges use exact node IDs in `from` and `to`. `choice` is an exact label declared
 by the source decision; omitting it makes the edge unconditional. Pass `edges: []`
@@ -152,7 +155,7 @@ drops the queued message. Session shutdown suppresses delivery.
 
 Set `pauseAfter: true` to hold an execution's outgoing scheduling and receive a
 pause reminder. Independent branches continue. Fetch `braid_status` to obtain
-`execution.revision` and `execution.pausedExecutionIds`, then:
+the current graph revision and paused execution IDs, then:
 
 ```json
 {
@@ -178,9 +181,9 @@ Pause reminders describe the event when it occurred: check current status and
 paused IDs before attempting an update/resume, since the job can time out or be
 cancelled before the parent handles the reminder.
 
-Focused `braid_status` reads also include the current control fields; the
-returned `node.revision` is the revision captured when that invocation started.
-Use `execution.revision` for updates even when inspecting an older invocation.
+Focused `braid_status` reads also start with the current control fields: graph
+status, revision, and paused execution IDs. Use that current revision for
+updates even when inspecting an older invocation.
 After cancellation or finalization there are no resumable paused executions;
 the event log still records where pauses occurred.
 
@@ -317,9 +320,15 @@ counts, and the execution log. Active nodes are marked `▶ ACTIVE`. The status
 tool also renders a flowchart; expand its result to see more log events.
 When selecting `nodeId` or `executionId`, it instead shows that invocation's
 output/error and activity, with the full text and history available on expansion.
-The JSON includes `activity` with the latest 40 history entries; pass
+
+The Braid tools return plain-text documents to the model, not JSON. A
+whole-job read lists the control state, every execution, their outputs,
+workspaces, and the current graph without prompts. A focused read shows one
+execution's output and its activity with the latest 40 history entries; pass
 `activityBefore` with an entry sequence to page earlier ones. While the invocation
-runs, `activity` comes before `node` so it survives preview truncation.
+runs, the activity comes before the output so it survives preview truncation.
+Worker `git` results read like Pi's bash output, and `decide` returns
+`Recorded choice: <choice>`.
 
 `/braid` now opens this panel; it no longer arms the next prompt. To request
 Braid explicitly, ask the agent to analyze the task using Braid.
@@ -330,11 +339,9 @@ model lookup, credentials/OAuth, provider transport, filesystem tool execution,
 and token/cost accounting. The first
 whole-job `braid_status` retrieval of a finished job reports its accumulated Pi usage;
 subsequent retrievals do not count the same usage again.
-Use the status response's `usage` for Pi totals, including completed provider
-rounds from nodes that later fail or time out. Saved final result files expose
-the same accounting as `piUsage`; core `metadata.usage` only includes usage
-returned by runners. Large running status reads save a complete snapshot too,
-so truncation never requires waiting for job completion to inspect the graph.
+The whole-job status text reports Pi's totals as `Usage`, including completed
+provider rounds from nodes that later fail or time out; core `metadata.usage`
+only includes usage returned by runners.
 
 ## When Pi will use Braid
 
@@ -378,7 +385,7 @@ only the current source IDs and diagnoses missing, duplicate or unexpected IDs.
 
 ## Install from npm
 
-Requires Node.js 22.19+ and Pi 1.0.1 (the tested version):
+Requires Node.js 22.19+ and Pi 1.2.0 (the tested version):
 
 ```sh
 pi install npm:@chrok/pi-braid
@@ -389,7 +396,7 @@ The package depends on the exact matching `@chrok/braid` release; npm installs
 core automatically. It does not bundle core or depend on a source checkout.
 Pi supplies its core peer packages at runtime.
 Their wildcard ranges follow Pi's packaging convention, not universal version
-compatibility. Development and CI pin Pi 1.0.1.
+compatibility. Development and CI pin Pi 1.2.0.
 
 ## Install this local checkout in Pi
 
@@ -618,9 +625,9 @@ writes already made. Core waits for tracked writes, preserves checkpoints, and
 removes worker worktrees before completing cancellation.
 
 The tool output is capped at 50KB/2000 lines to protect Pi context. When exceeded,
-the adapter writes a full JSON result to a temporary file (mode 600 on POSIX;
-inherited ACLs on Windows) and includes
-its path in the tool output.
+the adapter writes the complete text to a temporary file (mode 600 on POSIX;
+inherited ACLs on Windows) and ends the preview with its path, for running jobs
+as well as finished ones.
 
 For a test of proactive selection, start a fresh Pi turn with a task such as:
 

package/dist/command.js

@@ -201,9 +201,6 @@ export class BraidPanel {
                         ...(current.result ?? current.live),
                         progress: current.live.progress,
                         ...(current.workspaces ? { workspaces: current.workspaces } : {}),
-                        ...(current.fullOutputPath
-                            ? { fullOutputPath: current.fullOutputPath }
-                            : {}),
                     }, true, false, this.theme, "", false, this.choosing).render(width),
                 ]
                 : ["No Braid jobs in this session."];

package/dist/display.js

@@ -551,7 +551,7 @@ export function renderNodeResult(node, expanded, theme, fullOutputPath, progress
         ...(activity && activity.executionId === node.executionId ? renderActivity(activity, expanded, theme, now) : []),
         ...(node.output ? [expanded ? clean(node.output) : compact(node.output, 400)] : []),
         ...(!expanded && node.output && (node.output.length > 400 || node.output.includes("\n")) ? [theme.fg("dim", "Expand for full node output")] : []),
-        ...(fullOutputPath ? [theme.fg("dim", `full node result: ${compact(fullOutputPath, 240)}`)] : []),
+        ...(fullOutputPath ? [theme.fg("dim", `full text: ${compact(fullOutputPath, 240)}`)] : []),
     ];
     return new Text(lines.join("\n"), 0, 0);
 }
@@ -655,7 +655,7 @@ export function renderGraphResult(result, expanded, isPartial, theme, fallback =
     if (expanded)
         lines.push(...renderEventLog(result.events ?? [], true, theme));
     if ("fullOutputPath" in result && result.fullOutputPath)
-        lines.push(theme.fg("dim", `full result/log: ${compact(result.fullOutputPath, 240)}`));
+        lines.push(theme.fg("dim", `full text: ${compact(result.fullOutputPath, 240)}`));
     return new FixedLines(lines, chartStart, chart.length, nodeList, [
         ...(selectedNodeId === undefined ? [] : [{ mark: SELECTED_NODE_MARK, label: "selected node" }]),
         { mark: "▶ ACTIVE", label: "running node" },

package/dist/index.js

@@ -8,6 +8,7 @@ import { BraidJobs } from "./jobs.js";
 import { registerBraidCommand, registerBraidWidget } from "./command.js";
 import { registerReviewCommand } from "./review.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 } : {}) });
 const prompt = () => Type.Union([
     text("Instructions for this node; it does not receive the parent conversation."),
@@ -89,14 +90,24 @@ const BRAID_FILESYSTEM_GUIDANCE = "Every execute/decision activation gets a fres
     "merge combines selected predecessor checkpoints into a new isolated worktree; integrate writes selected changes to the invoking checkout while preserving user edits. Workers apply changes with Git/file tools, then call finish_merge using executionId for each source; finish_merge only records dispositions and does not apply changes. There is no automatic final integration. " +
     "Do not set workspace on merge/integrate nodes. Checkpoints remain recoverable after cleanup. Optional failed predecessors pass errors and partial work along unconditional edges; requireSuccess=true makes failure abort the job. " +
     "Nodes have local read/ls and Git inspection; writable nodes have write/edit and Pi shell tools for dependencies, builds, and tests, while merge/integrate also have local Git integration tools. Search tools require local rg/fd. Outside Git all filesystem access is read-only; read-only nodes have no shell. Worktrees are not an OS sandbox: prompts constrain shell writes and shared resources. Checkpoints omit ignored new files. Parent extension/MCP tools and recursive Braid calls are not provided. Nodes should verify their changes; the parent reviews results and performs any remaining validation after integration.";
+/** Lifecycle guidance shared by the system prompt and tool descriptions. */
+export const BRAID_ASYNC_GUIDANCE = "Braid is asynchronous: braid returns a jobId immediately and the job keeps running independently of the foreground response; ending your turn does not cancel it. " +
+    "Completion, failure, or cancellation sends a reminder: an idle agent is resumed automatically, and a running agent receives it at the next model step. " +
+    "After submitting, continue useful independent work. If nothing else can proceed until the result arrives, end your turn and let the reminder resume the task. " +
+    "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 results with braid_status and continue the original task. Between reminders, use braid_status only for deliberate progress checks or diagnosis.";
+/** 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.";
 const BRAID_USAGE_GUIDANCE = [
     "Braid is a proactive execution primitive, not only a user-requested command.",
     "Selection rule: for a code review, bug investigation, design comparison, test-planning request, or change spanning multiple files, call braid FIRST when two or more concerns can be handled independently. Nodes can analyze the project and implement changes in isolated Git worktrees. Do this without waiting for the user to say Braid; do not read everything in the parent and then decide whether to delegate.",
     BRAID_FILESYSTEM_GUIDANCE,
     "For repeated instructions, define promptTemplates once and use prompt={template: name, variables: {name: value}} on nodes. Values are strings inserted literally into {{name}} placeholders; plain-string prompts remain supported.",
-    "When Braid fits, submit a graph: use parallel execute nodes for independent analysis or implementation, execute nodes to synthesize findings, merge nodes to combine code snapshots, and integrate nodes to apply changes to the working branch. The tool returns a jobId immediately. Continue independent work or finish your turn while it runs; do not poll repeatedly. A completion reminder will resume you. Use braid_status with the jobId to retrieve terminal outputs before relying on them.",
+    "When Braid fits, submit a graph: use parallel execute nodes for independent analysis or implementation, execute nodes to synthesize findings, merge nodes to combine code snapshots, and integrate nodes to apply changes to the working branch. Use braid_status with the jobId to retrieve terminal outputs before relying on them.",
+    BRAID_ASYNC_GUIDANCE,
     "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.",
-    "Make the delegation choice once per user request. Reminders and definition errors are not new tasks. Check the accepted node types and settings in the tool response. If the same definition problem recurs, stop resubmitting and report the concrete mismatch; do not launch repeated probe/replacement jobs. In braid_update, add new nodes together with their dependencies and loops: a node added without incoming edges can start immediately, even while another execution is paused.",
+    "Make the delegation choice once per user request. Reminders and definition errors are not new tasks. If the same definition problem recurs, stop resubmitting and report the concrete mismatch; do not launch repeated probe/replacement jobs. In braid_update, add new nodes together with their dependencies and loops: a node added without incoming edges can start immediately, even while another execution is paused.",
     "Do not use braid for a simple one-step answer, a trivial direct edit, a single shell command, or when decomposition adds no value. Writable nodes can implement and test their work. The parent reviews results and performs any remaining validation after Braid completes.",
 ].join("\n");
 function isJobSnapshot(value) {
@@ -110,21 +121,15 @@ function isJobSnapshot(value) {
 }
 /** Focused reads return the latest activity entries; activityBefore pages earlier ones. */
 export const STATUS_ACTIVITY_ENTRIES = 40;
-function executionControl(job) {
-    return job.execution && {
-        status: job.execution.status,
-        revision: job.execution.revision,
-        pausedExecutionIds: job.execution.pausedExecutionIds,
-    };
-}
-function graphReceipt(job) {
-    const graph = job.execution?.graph;
-    return graph && {
-        // Echo accepted types/policies without duplicating potentially large prompts.
-        nodes: graph.nodes.map(({ prompt: _prompt, ...node }) => node),
-        edges: graph.edges,
-        ...(graph.loops ? { loops: graph.loops } : {}),
-    };
+/** Bound a text result; the complete document stays readable in a private file. */
+async function boundedText(text, name) {
+    const preview = truncateHead(text);
+    if (!preview.truncated)
+        return { text };
+    const directory = await mkdtemp(join(tmpdir(), "braid-status-"));
+    const path = join(directory, name);
+    await writeFile(path, text, { mode: 0o600 });
+    return { text: `${preview.content}\n[Truncated. Full text: ${path}]`, path };
 }
 export function createBraidTools(jobs) {
     const braidTool = defineTool({
@@ -141,7 +146,8 @@ export function createBraidTools(jobs) {
             "no parent history, inherited extension/MCP tools, or recursive Braid tools. " +
             BRAID_FILESYSTEM_GUIDANCE + " " +
             "Do not use it for a simple one-step answer or trivial direct edit. " +
-            "Use braid_status(jobId) for progress and results, or braid_cancel(jobId) to stop it. A completion reminder resumes the agent if idle; do independent work or end your turn instead of polling. Humans can open /braid for the live flow panel. " +
+            "Use braid_cancel(jobId) to stop it. Humans can open /braid for the live flow panel. " +
+            BRAID_ASYNC_GUIDANCE + " " +
             "Set notifyOnCompletion=true on selected nodes for intermediate success/failure reminders; retrieve their output/error with braid_status({jobId, nodeId}). Notifications do not pause scheduling; use pauseAfter for a hold, and braid_update to edit definitions. " +
             "Read result.status: failed graphs can still return successful terminal outputs.",
         promptSnippet: "Use FIRST for nontrivial code review/debug/design/implementation work; set workspace=read-only for analysis/synthesis, use worktrees for edits, merge to combine snapshots, and integrate to apply changes",
@@ -183,13 +189,7 @@ export function createBraidTools(jobs) {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify({
-                                jobId: job.handle,
-                                canonicalJobId: job.jobId,
-                                status: job.status,
-                                graph: graphReceipt(job),
-                                message: "Running in background. Check the accepted graph above. Use braid_status to retrieve progress/results. Reminders arrive after the current step or resume you when idle; do not poll repeatedly.",
-                            }),
+                            text: formatReceipt(job, `${BRAID_WAIT_REMINDER} Humans can follow it live in /braid.`),
                         },
                     ],
                     details: job,
@@ -209,7 +209,7 @@ export function createBraidTools(jobs) {
     const statusTool = defineTool({
         name: "braid_status",
         label: "Braid status",
-        description: "Retrieve a background Braid job's status, node progress, and final results by exact session handle (e.g. job-1) or UUID in jobId. Add executionId for an exact execution, or nodeId for the latest instance, including intermediate results while the job runs. Focused reads include live activity: phase, time in phase and since the last observed signal, model request/stream state, running tools, and recent history. Lack of observed activity is a diagnostic signal, not proof of a stall. All job reads include current execution.revision and execution.pausedExecutionIds for live control; node.revision is the historical invocation revision. Large results include a path to the full JSON, including while running. For usage totals use usage (Pi provider accounting, including rounds from failed nodes), or piUsage in the saved final result. Prefer the short handle from submission/reminders. Omit all IDs to list jobs in this session. Completion reminders arrive automatically; avoid repeated polling.",
+        description: "Retrieve a background Braid job's status, node progress, and final results by exact session handle (e.g. job-1) or UUID in jobId. Add executionId for an exact execution, or nodeId for the latest instance, including intermediate results while the job runs. Focused reads include live activity: phase, time in phase and since the last observed signal, model request/stream state, running tools, and recent history. Lack of observed activity is a diagnostic signal, not proof of a stall. Every job read starts with the current graph revision and paused execution IDs for live control. Results are text; long ones are truncated and the full text is saved to a file whose path is shown. Usage is Pi's provider accounting, including rounds from failed nodes. Prefer the short handle from submission/reminders. Omit all IDs to list jobs in this session. Completion reminders arrive automatically: read results after the reminder, or deliberately for a progress check or diagnosis; do not sleep, use a timer, or poll in a loop to wait for a job.",
         parameters: statusParameters,
         renderResult(result, options, theme, ctx) {
             const job = result.details;
@@ -249,7 +249,7 @@ export function createBraidTools(jobs) {
                 throw new Error("activityBefore requires nodeId or executionId");
             if (!params.jobId)
                 return {
-                    content: [{ type: "text", text: JSON.stringify(jobs.list()) }],
+                    content: [{ type: "text", text: formatJobList(jobs.list()) }],
                     details: undefined,
                 };
             const job = jobs.get(params.jobId);
@@ -257,63 +257,22 @@ export function createBraidTools(jobs) {
                 throw jobs.unknownJob(params.jobId);
             if (params.nodeId !== undefined || params.executionId !== undefined) {
                 const node = jobs.getNode(params.jobId, params.nodeId, params.executionId);
-                const { id, executionId, status, error, output, ...nodeDetails } = node;
-                const activity = executionId ? jobs.getActivity(params.jobId, executionId, {
+                const activity = node.executionId ? jobs.getActivity(params.jobId, node.executionId, {
                     limit: STATUS_ACTIVITY_ENTRIES, ...(params.activityBefore === undefined ? {} : { before: params.activityBefore }),
                 }) : undefined;
-                // While running, activity is the useful part; afterwards the output is,
-                // so it comes first and history cannot push it out of the preview.
-                const running = activity && activity.finishedAt === undefined;
-                const live = activity ? { observedAt: job.live.observedAt, activity } : {};
-                const full = JSON.stringify({
-                    jobId: job.jobId, handle: job.handle, status: job.status, execution: executionControl(job),
-                    ...(running ? live : {}),
-                    node: { id, executionId, status, error, output, ...nodeDetails },
-                    ...(running ? {} : live),
-                }, null, 2);
-                const preview = truncateHead(full);
-                let suffix = "";
-                let nodeOutputPath;
-                if (preview.truncated) {
-                    const directory = await mkdtemp(join(tmpdir(), "braid-node-result-"));
-                    const path = join(directory, "result.json");
-                    await writeFile(path, full, { mode: 0o600 });
-                    nodeOutputPath = path;
-                    suffix = `\n[Preview truncated. Full node result: ${path}]`;
-                }
+                const result = await boundedText(formatNodeStatus({ job, node, ...(activity ? { activity } : {}), now: Date.now() }), "node.txt");
                 // Focused reads do not claim the whole job's usage; final job retrieval does.
-                return { content: [{ type: "text", text: preview.content + suffix }], details: {
-                        ...job, selectedNode: node, ...(activity ? { selectedActivity: activity } : {}), ...(nodeOutputPath ? { nodeOutputPath } : {}),
+                return { content: [{ type: "text", text: result.text }], details: {
+                        ...job, selectedNode: node, ...(activity ? { selectedActivity: activity } : {}), ...(result.path ? { nodeOutputPath: result.path } : {}),
                     } };
             }
-            const { jobId, handle, status, error, usage: providerUsage, fullOutputPath, execution, ...snapshot } = job;
-            // Put control/error/accounting fields before large prompts, outputs and logs.
-            const full = JSON.stringify({
-                jobId, handle, status,
-                error: error ?? job.result?.error ?? execution?.error,
-                usage: providerUsage, fullOutputPath,
-                execution: execution && { ...executionControl(job), ...execution },
-                ...snapshot,
-            }, null, 2);
-            const preview = truncateHead(full);
-            let suffix = "";
-            let details = job;
-            if (preview.truncated) {
-                if (job.fullOutputPath)
-                    suffix = `\n[Preview truncated. Full result/log: ${job.fullOutputPath}]`;
-                else {
-                    const directory = await mkdtemp(join(tmpdir(), "braid-status-"));
-                    const path = join(directory, "status.json");
-                    await writeFile(path, full, { mode: 0o600 });
-                    details = { ...job, fullOutputPath: path };
-                    suffix = `\n[Preview truncated. Full status snapshot: ${path}]`;
-                }
-            }
+            const result = await boundedText(formatJobStatus(job, Date.now()), "status.txt");
+            const details = result.path ? { ...job, fullOutputPath: result.path } : job;
             // Saving a running snapshot can race job completion; claim usage only
             // when this response actually contains a terminal snapshot.
             const usage = job.status === "running" ? undefined : jobs.claimUsage(job.jobId);
             return {
-                content: [{ type: "text", text: preview.content + suffix }],
+                content: [{ type: "text", text: result.text }],
                 details,
                 ...(usage ? { usage } : {}),
             };
@@ -342,14 +301,14 @@ export function createBraidTools(jobs) {
     });
     const updateParameters = Type.Object({
         jobId: text("Exact session handle (e.g. job-1) or UUID."),
-        expectedRevision: Type.Integer({ minimum: 0, description: "Current execution.revision from braid_status. A stale revision rejects the entire update." }),
+        expectedRevision: Type.Integer({ minimum: 0, description: "Current graph revision from braid_status. A stale revision rejects the entire update." }),
         upsertNodes: Type.Optional(Type.Array(nodeParameters, { description: "Complete node definitions to add or replace, not partial patches. Add dependencies and loops in this SAME update: new roots may start immediately even if another execution is paused. Already admitted executions keep their captured definitions." })),
         removeNodeIds: Type.Optional(Type.Array(text(), { description: "Node IDs to remove, together with all incident edges." })),
         addEdges: Type.Optional(Type.Array(updateEdgeParameters, { description: "Edges to add. Pin a historical source using executionId when needed." })),
-        removeEdges: Type.Optional(Type.Array(updateEdgeParameters, { description: "Exact edge identities to remove: copy from, to, and every present choice/feedback/executionId from execution.graph.edges. Omitted optional fields do not act as wildcards." })),
+        removeEdges: Type.Optional(Type.Array(updateEdgeParameters, { description: "Exact edge identities to remove: copy from, to, and every present choice/feedback/executionId from the current graph edges in braid_status. Omitted optional fields do not act as wildcards." })),
         promptTemplates: Type.Optional(Type.Record(Type.String(), text(), { description: `${templateDescription} Replaces the entire template map; omit to preserve it. Include every template still referenced by nodes.` })),
         loops: Type.Optional(Type.Array(loopParameters, { description: "Replaces all loop definitions; omit to preserve them, or use [] to remove all (also remove their feedback edges)." })),
-        resume: Type.Optional(Type.Array(text(), { uniqueItems: true, description: "Paused execution IDs from execution.pausedExecutionIds, not node IDs. Releases them atomically with the graph edit." })),
+        resume: Type.Optional(Type.Array(text(), { uniqueItems: true, description: "Paused execution IDs from braid_status, not node IDs. Releases them atomically with the graph edit." })),
     }, { additionalProperties: false });
     const updateTool = defineTool({
         name: "braid_update", label: "Update Braid",
@@ -364,13 +323,13 @@ export function createBraidTools(jobs) {
             catch (error) {
                 throw new Error(`Braid update rejected; no changes or resumes were applied. ${error instanceof Error ? error.message : String(error)}. Retry the complete corrected patch, including its edges/loops/resume; adding disconnected nodes separately can start them immediately.`);
             }
-            return { content: [{ type: "text", text: JSON.stringify({ jobId: job.handle, revision: job.execution.revision, pausedExecutionIds: job.execution.pausedExecutionIds, graph: graphReceipt(job) }) }], details: job };
+            return { content: [{ type: "text", text: formatUpdate(job) }], details: job };
         },
     });
     const resumeParameters = Type.Object({
         jobId: text("Exact session handle (e.g. job-1) or UUID."),
-        expectedRevision: Type.Integer({ minimum: 0, description: "Current execution.revision from braid_status." }),
-        executionIds: Type.Array(text(), { minItems: 1, uniqueItems: true, description: "IDs from execution.pausedExecutionIds, not node IDs. Only these completed, paused executions are released." }),
+        expectedRevision: Type.Integer({ minimum: 0, description: "Current graph revision from braid_status." }),
+        executionIds: Type.Array(text(), { minItems: 1, uniqueItems: true, description: "Paused execution IDs from braid_status, not node IDs. Only these completed, paused executions are released." }),
     }, { additionalProperties: false });
     const resumeTool = defineTool({
         name: "braid_resume", label: "Resume Braid",
@@ -378,7 +337,7 @@ export function createBraidTools(jobs) {
         parameters: resumeParameters,
         async execute(_id, params) {
             const job = jobs.resume(params.jobId, params.executionIds, params.expectedRevision);
-            return { content: [{ type: "text", text: JSON.stringify({ jobId: job.handle, revision: job.execution.revision, pausedExecutionIds: job.execution.pausedExecutionIds }) }], details: job };
+            return { content: [{ type: "text", text: formatResume(job) }], details: job };
         },
     });
     return { braidTool, statusTool, cancelTool, updateTool, resumeTool };

package/dist/jobs.js

@@ -1,8 +1,4 @@
-import { mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { setImmediate as nextTurn } from "node:timers/promises";
-import { truncateHead, } from "@earendil-works/pi-coding-agent";
 import { ExecutionActivityTracker, startBraid, validateGraph, } from "@chrok/braid";
 import { applyEvent, applyProgress, createLiveState, } from "./display.js";
 import { createPiRunner, sumPiUsage } from "./runner.js";
@@ -182,16 +178,6 @@ export class BraidJobs {
             const status = job.result.error?.code === "CANCELLED"
                 ? "cancelled"
                 : job.result.status;
-            // Core metadata counts usage returned by runners; Pi also records completed
-            // provider rounds from workers that later fail or time out.
-            const full = JSON.stringify({ ...job.result, workspaces: job.workspaces, piUsage: job.usage }, null, 2);
-            const preview = JSON.stringify({ ...this.get(job.jobId), status }, null, 2);
-            if (truncateHead(preview).truncated) {
-                const directory = await mkdtemp(join(tmpdir(), "braid-result-"));
-                const path = join(directory, "result.json");
-                await writeFile(path, full, { mode: 0o600 });
-                job.fullOutputPath = path;
-            }
             job.status = status;
         }
         catch (error) {

package/dist/runner.js

@@ -5,6 +5,18 @@ import { createWorktreeWriteTools } from "./write-tools.js";
 import { createAvailableReadTools } from "./read-tools.js";
 import { createWorkspaceShellTools } from "./shell-tools.js";
 import { formatHumanInput } from "./human-input.js";
+/**
+ * Present a Git result the way Pi's bash tool presents command output. Output
+ * stays byte-exact, so a diff can be passed back to git apply.
+ */
+export function formatGitResult(result) {
+    let output = result.stdout;
+    if (result.stderr)
+        output += (output && !output.endsWith("\n") ? "\n" : "") + result.stderr;
+    if (result.exitCode === 0)
+        return output || "(no output)";
+    return `${output ? `${output.replace(/\n$/, "")}\n\n` : ""}Command exited with code ${result.exitCode}`;
+}
 /** Keep Pi's provider/auth plumbing and filesystem capabilities out of Braid's core. */
 export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd()) {
     const options = typeof onUsageOrOptions === "function"
@@ -289,7 +301,7 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
                 if (call.name === "git" && request.git) {
                     const args = parseGitToolArguments(call.arguments, (request.node.type === "merge" || request.node.type === "integrate"));
                     const result = await request.git(args.args, args.input);
-                    return toolResult(call, JSON.stringify(result), result.exitCode !== 0);
+                    return toolResult(call, formatGitResult(result), result.exitCode !== 0);
                 }
                 if (call.name === "finish_merge" && request.merge) {
                     const dispositions = parseFinishMergeArguments(call.arguments, request.merge.sources.map(source => source.executionId));
@@ -339,7 +351,7 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
             // No coercion or prose parsing: the core enforces the enum and exactly one call.
             request.decide(args.choice);
             decided = true;
-            return toolResult(call, JSON.stringify({ choice: args.choice }), false);
+            return toolResult(call, `Recorded choice: ${args.choice}`, false);
         };
         while (true) {
             const response = await complete();

package/dist/status-text.js

@@ -0,0 +1,179 @@
+/** Model-facing text documents for the parent Braid tools. */
+const iso = (ms) => new Date(ms).toISOString();
+const duration = (ms) => ms < 1000 ? `${Math.max(0, Math.round(ms))}ms` : ms < 60_000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1000)}s`;
+const failure = (error) => `${error.code}: ${error.message}`;
+const ids = (values) => values?.length ? values.join(", ") : "none";
+const GOAL_CHARS = 2000;
+const clip = (text, limit) => text.length > limit ? `${text.slice(0, limit)}… [${text.length} chars]` : text;
+const indent = (text) => text.split("\n").map(line => line ? `  ${line}` : line).join("\n");
+export function formatUsage(usage) {
+    if (!usage)
+        return undefined;
+    const parts = [`input ${usage.input}`, `output ${usage.output}`];
+    if (usage.cacheRead)
+        parts.push(`cache read ${usage.cacheRead}`);
+    if (usage.cacheWrite)
+        parts.push(`cache write ${usage.cacheWrite}`);
+    const cost = usage.cost?.total ? `, $${usage.cost.total.toFixed(4)}` : "";
+    return `${parts.join(", ")} (${usage.totalTokens} tokens${cost})`;
+}
+function nodeLine(node) {
+    const settings = [node.type];
+    if ("workspace" in node && node.workspace)
+        settings.push(`workspace=${node.workspace}`);
+    if ("choices" in node)
+        settings.push(`choices=${node.choices.join("|")}`);
+    if (node.model)
+        settings.push(`model=${node.model}`);
+    if (typeof node.prompt === "object")
+        settings.push(`template=${node.prompt.template}`);
+    for (const flag of ["pauseAfter", "notifyOnCompletion", "requireSuccess"])
+        if (node[flag])
+            settings.push(flag);
+    return `- ${node.id}: ${settings.join(", ")}`;
+}
+/** Accepted definitions without prompts, which the caller already sent. */
+export function formatGraph(graph) {
+    const lines = ["Nodes:", ...graph.nodes.map(nodeLine), "Edges:"];
+    lines.push(...graph.edges.length ? graph.edges.map(edge => {
+        const labels = [edge.choice && `choice=${edge.choice}`, edge.feedback && `feedback=${edge.feedback}`, edge.executionId && `execution=${edge.executionId}`].filter(Boolean);
+        return `- ${edge.from} -> ${edge.to}${labels.length ? ` [${labels.join(", ")}]` : ""}`;
+    }) : ["- none"]);
+    if (graph.loops?.length)
+        lines.push("Loops:", ...graph.loops.map(loop => `- ${loop.id}: entry ${loop.entry}, at most ${loop.maxIterations} iterations`));
+    return lines.join("\n");
+}
+function workspaceLine(workspace) {
+    const parts = [`${workspace.mode} ${workspace.workingDirectory}`, workspace.state];
+    for (const root of [workspace.worktreeRoot, workspace.sourceRoot])
+        if (root && root !== workspace.workingDirectory)
+            parts.push(`root ${root}`);
+    if (workspace.checkpointRef)
+        parts.push(`checkpoint ${workspace.checkpointRef}`);
+    if (workspace.backupRef)
+        parts.push(`backup ${workspace.backupRef}`);
+    if (workspace.reason)
+        parts.push(workspace.reason);
+    for (const item of workspace.dispositions ?? [])
+        parts.push(`${item.executionId} ${item.disposition}: ${item.reason}`);
+    return parts.join(" · ");
+}
+function executionLine(execution) {
+    const parts = [execution.executionId ?? "(no execution)", `node ${execution.id}`];
+    if (execution.iteration)
+        parts.push(`iteration ${execution.iteration}`);
+    parts.push(execution.skipReason ? `${execution.status} (${execution.skipReason})` : execution.status);
+    if (execution.latencyMs !== undefined)
+        parts.push(duration(execution.latencyMs));
+    if (execution.decision)
+        parts.push(`decision ${execution.decision}`);
+    if (execution.error)
+        parts.push(failure(execution.error));
+    return `- ${parts.join(" · ")}`;
+}
+export function formatJobList(jobs) {
+    if (!jobs.length)
+        return "No Braid jobs in this session.";
+    return [`${jobs.length} Braid job${jobs.length === 1 ? "" : "s"} in this session, newest first:`,
+        ...jobs.map(job => `- ${job.handle} · ${job.status} · started ${iso(job.createdAt)} · id ${job.jobId}\n  Goal: ${job.goal}`)].join("\n");
+}
+function control(execution) {
+    return execution ? `Graph ${execution.status} · revision ${execution.revision} · paused executions: ${ids(execution.pausedExecutionIds)}` : "Graph not started";
+}
+/** The submission receipt. The caller already has the graph it submitted. */
+export function formatReceipt(job, message) {
+    return [`Braid job ${job.handle} started (${job.status}).`, `ID: ${job.jobId}`, message].join("\n");
+}
+export function formatUpdate(job) {
+    return [`Braid job ${job.handle} updated to revision ${job.execution.revision}.`,
+        `Paused executions: ${ids(job.execution.pausedExecutionIds)}`, "Current graph:", formatGraph(job.execution.graph)].join("\n");
+}
+export function formatResume(job) {
+    return `Braid job ${job.handle} resumed at revision ${job.execution.revision}. Still paused: ${ids(job.execution.pausedExecutionIds)}.`;
+}
+export function formatActivity(activity, now, jobId) {
+    const lines = [`Activity: ${activity.phase} for ${duration(now - activity.phaseStartedAt)}; last observed signal ${duration(now - activity.lastActivityAt)} ago (${activity.lastActivity}). Model requests ${activity.modelRequests}, tool calls ${activity.toolCalls}.`];
+    const model = activity.model;
+    if (model && model.completedAt === undefined) {
+        const stream = model.firstStreamAt === undefined ? "no stream received yet"
+            : `receiving ${model.receiving ?? "output"}${model.toolName ? ` for ${model.toolName}` : ""}, ${model.receivedChars} chars, last chunk ${duration(now - (model.lastStreamAt ?? model.firstStreamAt))} ago`;
+        lines.push(`Model request ${model.round}: started ${duration(now - model.startedAt)} ago; ${stream}.`);
+    }
+    for (const tool of activity.tools) {
+        lines.push(`Running tool ${tool.name} for ${duration(now - tool.startedAt)}: ${tool.arguments}`);
+        if (tool.outputTail)
+            lines.push(indent(`Output tail:\n${tool.outputTail}`));
+    }
+    for (const limitation of activity.limitations)
+        lines.push(`Not observable: ${limitation}`);
+    if (activity.entries.length) {
+        lines.push("History:");
+        for (const entry of activity.entries) {
+            lines.push(`- #${entry.sequence} ${iso(entry.timestamp)} ${entry.kind}${entry.toolName ? ` ${entry.toolName}` : ""}${entry.isError ? " (error)" : ""}${entry.durationMs !== undefined ? ` ${duration(entry.durationMs)}` : ""}: ${entry.summary}`);
+            if (entry.detail)
+                lines.push(indent(entry.detail + (entry.detailLength ? `\n[preview of ${entry.detailLength} chars]` : "")));
+        }
+        const first = activity.entries[0].sequence;
+        if (first > 1)
+            lines.push(first - 1 > activity.droppedEntries
+                ? `Earlier entries: braid_status({"jobId":"${jobId}","executionId":"${activity.executionId}","activityBefore":${first}})`
+                : `${activity.droppedEntries} earlier entries are no longer retained.`);
+    }
+    return lines.join("\n");
+}
+/** A focused read: the current control state, then one execution in full. */
+export function formatNodeStatus({ job, node, activity, now }) {
+    const lines = [`Braid job ${job.handle} · ${job.status} · ${control(job.execution)}`,
+        `Execution ${node.executionId ?? "(none yet)"} · node ${node.id}${node.node ? ` (${node.node.type})` : ""}${node.iteration ? ` · iteration ${node.iteration}` : ""} · ${node.skipReason ? `${node.status} (${node.skipReason})` : node.status}`];
+    const timing = [node.startedAt !== undefined && `started ${iso(node.startedAt)}`, node.latencyMs !== undefined && `took ${duration(node.latencyMs)}`,
+        node.model && `model ${node.model}`, node.usage && `usage input ${node.usage.inputTokens}, output ${node.usage.outputTokens}`].filter(Boolean);
+    if (timing.length)
+        lines.push(timing.join(" · "));
+    if (node.decision)
+        lines.push(`Decision: ${node.decision}`);
+    if (node.error)
+        lines.push(`Error: ${failure(node.error)}`);
+    if (node.workspace)
+        lines.push(`Workspace: ${workspaceLine(node.workspace)}`);
+    if (node.humanInputs?.length)
+        lines.push("Human input delivered during this execution:", ...node.humanInputs.map(input => `- ${iso(input.timestamp)}: ${input.text}`));
+    const output = `Output:\n${node.output ?? "(none)"}`;
+    // While running, activity is the useful part; afterwards the output is.
+    const running = activity && activity.finishedAt === undefined;
+    const sections = [lines.join("\n"), ...running ? [formatActivity(activity, now, job.handle), output] : [output, ...activity ? [formatActivity(activity, now, job.handle)] : []]];
+    return sections.join("\n\n");
+}
+/** The whole job: control state, every execution, then their outputs and the current definition. */
+export function formatJobStatus(job, now) {
+    const state = job.result ?? job.execution;
+    // Control fields lead: a long goal or output must not push them out of a truncated preview.
+    const header = [`Braid job ${job.handle} · ${job.status}`, `ID: ${job.jobId}`, control(job.execution)];
+    const error = job.error ?? (job.result?.error ? failure(job.result.error) : job.execution?.error ? failure(job.execution.error) : undefined);
+    if (error)
+        header.push(`Error: ${error}`);
+    const usage = formatUsage(job.usage);
+    if (usage)
+        header.push(`Usage: ${usage}`);
+    if (job.result)
+        header.push(`Finished ${iso(job.result.metadata.finishedAt)} after ${duration(job.result.metadata.latencyMs)}`);
+    else
+        header.push(`Started ${iso(job.createdAt)}, ${duration(now - job.createdAt)} ago`);
+    header.push(`Goal: ${clip(job.goal, GOAL_CHARS)}`);
+    const sections = [header.join("\n")];
+    const executions = Object.values(state?.executions ?? {});
+    if (executions.length)
+        sections.push([`Executions (${executions.length}):`, ...executions.map(executionLine)].join("\n"));
+    const pending = Object.values(state?.nodes ?? {}).filter(node => !node.executionId);
+    if (pending.length)
+        sections.push(["Nodes without executions:", ...pending.map(executionLine)].join("\n"));
+    const terminal = new Set(job.result?.terminalExecutionIds ?? []);
+    const outputs = executions.filter(execution => execution.output !== undefined);
+    if (outputs.length)
+        sections.push(["Outputs:", ...outputs.map(execution => `## ${execution.id} · ${execution.executionId}${terminal.has(execution.executionId) ? " · terminal" : ""}${execution.decision ? ` · decision ${execution.decision}` : ""}\n${execution.output}`)].join("\n\n"));
+    const workspaces = executions.filter(execution => execution.workspace);
+    if (workspaces.length)
+        sections.push(["Workspaces:", ...workspaces.map(execution => `- ${execution.executionId}: ${workspaceLine(execution.workspace)}`)].join("\n"));
+    if (job.execution)
+        sections.push(`Current graph (revision ${job.execution.revision}):\n${formatGraph(job.execution.graph)}`);
+    return sections.join("\n\n");
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "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.4"
+    "@chrok/braid": "0.3.5"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -14,9 +14,9 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "1.0.1",
-    "@earendil-works/pi-tui": "1.0.1",
-    "@earendil-works/pi-coding-agent": "1.0.1",
+    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
     "typescript": "^5.0.0",
     "tsx": "^4.0.0",
     "@types/node": "^22.0.0"