@chrok/pi-braid 0.3.3 → 0.3.5

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,17 +1,17 @@
-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";
 import { PiTranscripts } from "./transcript.js";
+import { PiHumanInputs } from "./human-input.js";
+import { BraidAssistant } from "./assistant.js";
 /** Jobs belong to one extension/session lifetime, independently of foreground turns. */
 export class BraidJobs {
     onFinished;
     onNodeFinished;
     jobs = new Map();
+    assistants = new Map();
+    cwd = process.cwd();
     handles = new Map();
     nextHandle = 1;
     listeners = new Set();
@@ -47,6 +47,7 @@ export class BraidJobs {
             : undefined;
         const registry = ctx.modelRegistry;
         const cwd = ctx.cwd;
+        this.cwd = cwd;
         const job = {
             handle: `job-${this.nextHandle++}`,
             jobId: crypto.randomUUID(),
@@ -60,6 +61,7 @@ export class BraidJobs {
             runningExecutions: new Map(),
             activity: new ExecutionActivityTracker({ onChange: () => this.changed() }),
             transcripts: new PiTranscripts(() => this.changed()),
+            humanInputs: new PiHumanInputs(() => this.changed()),
             nodeResults: new Map(snapshot.nodes.map((node) => [node.id, { id: node.id, status: "pending" }])),
         };
         this.jobs.set(job.jobId, job);
@@ -84,6 +86,7 @@ export class BraidJobs {
                         cwd,
                         activity: job.activity,
                         transcripts: job.transcripts,
+                        humanInputs: job.humanInputs,
                         maxToolRounds: options.maxToolRounds ?? Infinity,
                         maxToolCalls: options.maxToolCalls ?? Infinity,
                         onUsage: (usage) => {
@@ -104,6 +107,10 @@ export class BraidJobs {
                         }
                         finally {
                             job.activity.workerFinished(request.execution.executionId);
+                            const executionId = request.execution.executionId;
+                            if (executionId !== undefined) {
+                                job.transcripts.human(executionId, job.humanInputs.close(executionId).map(input => input.text), false);
+                            }
                             job.transcripts.finish(request.execution.executionId, request.signal.aborted ? "Execution was stopped before this step finished" : undefined);
                         }
                     };
@@ -171,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) {
@@ -213,7 +210,7 @@ export class BraidJobs {
         const job = this.lookup(jobId);
         if (!job)
             return undefined;
-        const { run: _run, controller: _controller, done: _done, usageClaimed: _claimed, nodeResults: _nodeResults, runningExecutions: _runningExecutions, activity: _activity, transcripts: _transcripts, ...snapshot } = job;
+        const { run: _run, controller: _controller, done: _done, usageClaimed: _claimed, nodeResults: _nodeResults, runningExecutions: _runningExecutions, activity: _activity, transcripts: _transcripts, humanInputs: _humanInputs, ...snapshot } = job;
         const copy = structuredClone(snapshot);
         if (job.run)
             copy.execution = job.run.snapshot();
@@ -249,6 +246,39 @@ export class BraidJobs {
             throw this.unknownJob(jobId);
         return job.transcripts.get(executionId);
     }
+    /**
+     * Queue a human message for one running execution. The worker receives it
+     * before its next model request; running tools are not interrupted.
+     */
+    sendInput(jobId, executionId, text) {
+        const job = this.lookup(jobId);
+        if (!job)
+            throw this.unknownJob(jobId);
+        if (!job.transcripts.isLive(executionId)) {
+            throw new Error("Messages can be sent only to a running execution whose live session has started");
+        }
+        return job.humanInputs.send(executionId, text);
+    }
+    /** Messages waiting for the execution's next model request. */
+    pendingInputs(jobId, executionId) {
+        const job = this.lookup(jobId);
+        if (!job)
+            throw this.unknownJob(jobId);
+        return structuredClone(job.humanInputs.pending(executionId));
+    }
+    /** The panel's side conversation about a job or one of its nodes, kept for the session. */
+    assistant(jobId, nodeId) {
+        const job = this.lookup(jobId);
+        if (!job)
+            throw this.unknownJob(jobId);
+        const key = JSON.stringify([job.jobId, nodeId ?? null]);
+        let assistant = this.assistants.get(key);
+        if (!assistant) {
+            assistant = new BraidAssistant(this, job.jobId, this.cwd, () => this.changed(), nodeId);
+            this.assistants.set(key, assistant);
+        }
+        return assistant;
+    }
     update(jobId, patch) {
         const job = this.lookup(jobId);
         if (!job)
@@ -321,6 +351,8 @@ export class BraidJobs {
         this.disposed = true;
         for (const job of this.jobs.values())
             job.controller.abort();
+        for (const assistant of this.assistants.values())
+            assistant.dispose();
         this.listeners.clear();
     }
 }

package/dist/runner.js

@@ -4,6 +4,19 @@ import { formatBudgetReminder, gitToolDefinition, finishMergeToolDefinition, mer
 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"
@@ -150,6 +163,16 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
             predecessors: request.predecessors.length,
             workspace: `${workspace.mode} · ${workingDirectory}`,
         }, toolByName);
+        const humanInputs = executionId === undefined ? undefined : options.humanInputs;
+        // Between model requests only: a running tool batch is never interrupted.
+        const deliverHumanInputs = () => {
+            const inputs = humanInputs?.take(executionId) ?? [];
+            for (const input of inputs) {
+                request.recordHumanInput?.(input.text);
+                context.messages.push({ role: "user", content: formatHumanInput(input.text), timestamp: Date.now() });
+            }
+            transcripts?.human(executionId, inputs.map(input => input.text), true);
+        };
         const systemPrompt = context.systemPrompt;
         const sessionId = crypto.randomUUID();
         const usage = { inputTokens: 0, outputTokens: 0 };
@@ -161,6 +184,7 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
         let reportedContextTokens;
         const complete = async () => {
             request.signal.throwIfAborted();
+            deliverHumanInputs();
             const budgets = [];
             if (Number.isFinite(maxToolRounds)) {
                 budgets.push(`Tool round budget: ${toolRounds}/${maxToolRounds} used; ${maxToolRounds - toolRounds} remaining. A round is one assistant response containing tool calls.`);
@@ -277,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));
@@ -327,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();
@@ -336,8 +360,13 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
                 .map((block) => block.text));
             const calls = response.content.filter((block) => block.type === "toolCall");
             if (calls.length === 0) {
-                if (response.stopReason === "stop")
-                    break;
+                if (response.stopReason === "stop") {
+                    // A message that arrived during the final request gets one more round.
+                    if (!humanInputs?.pending(executionId).length)
+                        break;
+                    context.messages.push(response);
+                    continue;
+                }
                 throw new Error("Pi model requested tool use without a tool call");
             }
             if (response.stopReason !== "toolUse") {

package/dist/session-view.js

@@ -1,5 +1,5 @@
 import { AssistantMessageComponent, getMarkdownTheme, ToolExecutionComponent, UserMessageComponent, } from "@earendil-works/pi-coding-agent";
-import { Container, stripTerminalSequences, Text } from "@earendil-works/pi-tui";
+import { Container, Spacer, stripTerminalSequences, Text } from "@earendil-works/pi-tui";
 const plain = (value) => stripTerminalSequences(value).replace(/\p{Cc}/gu, " ");
 /**
  * Renders a worker conversation with Pi's own chat components, applying only
@@ -40,6 +40,21 @@ export class NodeSessionView {
         this.version = transcript.version;
         for (; this.rendered < transcript.messages.length; this.rendered++) {
             const message = transcript.messages[this.rendered];
+            if (message.role === "human") {
+                this.gap();
+                this.add(new Text(message.delivered
+                    ? this.theme.fg("warning", "✎ Human input · delivered before the next model request")
+                    : this.theme.fg("error", "✎ Human input · not delivered: the execution ended before its next model request"), 1, 0));
+                this.add(new UserMessageComponent(message.text, getMarkdownTheme()));
+                continue;
+            }
+            if (message.role === "user") {
+                const text = typeof message.content === "string" ? message.content
+                    : message.content.flatMap(block => block.type === "text" ? [block.text] : []).join("\n");
+                this.gap();
+                this.add(new UserMessageComponent(text, getMarkdownTheme()));
+                continue;
+            }
             if (message.role === "toolResult") {
                 this.tools.get(message.toolCallId)?.updateResult(message);
                 this.partials.delete(message.toolCallId);
@@ -50,6 +65,9 @@ export class NodeSessionView {
             this.streaming = undefined;
             component.updateContent(message, false);
             this.toolCalls(message, transcript, true);
+            // A reply that requests no tools ends the turn; leave room below it right away.
+            if (message.stopReason !== "toolUse")
+                this.gap();
         }
         if (transcript.streaming) {
             this.streaming ??= this.add(new AssistantMessageComponent(undefined, false, getMarkdownTheme()));
@@ -99,12 +117,20 @@ export class NodeSessionView {
         this.rendered = 0;
         this.version = -1;
         const intro = transcript.intro;
+        if (!intro)
+            return;
         this.add(new UserMessageComponent(intro.prompt, getMarkdownTheme()));
         this.add(new Text(this.theme.fg("dim", [
             `goal: ${plain(intro.goal)}`,
             `context: ${intro.predecessors} predecessor output${intro.predecessors === 1 ? "" : "s"} · workspace ${plain(intro.workspace)}`,
         ].join("\n")), 1, 0));
     }
+    /** One blank line between turns: after a finished reply, or before a new message. */
+    gap() {
+        const last = this.chat.children.at(-1);
+        if (last && !(last instanceof Spacer))
+            this.add(new Spacer(1));
+    }
     add(component) {
         this.chat.addChild(component);
         return component;

package/dist/shell-tools.js

@@ -32,15 +32,22 @@ function managedOperations(resolveShell, prefix = "") {
                 if (!child.pid)
                     return;
                 if (process.platform === "win32") {
-                    await new Promise((resolve, reject) => {
+                    const failure = await new Promise(resolve => {
                         execFile(join(process.env.SystemRoot ?? "C:\\Windows", "System32", "taskkill.exe"), ["/F", "/T", "/PID", String(child.pid)], { windowsHide: true }, error => {
                             // taskkill reports 128 when the process has already exited.
-                            if (error && error.code !== 128)
-                                reject(error);
-                            else
-                                resolve();
+                            resolve(error && error.code !== 128 ? error : undefined);
                         });
                     });
+                    if (failure) {
+                        // With /T, a descendant that exits during the tree walk makes taskkill
+                        // fail although the shell was killed. Fail only if the shell survives.
+                        const stopped = await Promise.race([
+                            exited.then(() => true, () => true),
+                            new Promise(resolve => setTimeout(() => resolve(false), 2000).unref()),
+                        ]);
+                        if (!stopped)
+                            throw failure;
+                    }
                 }
                 else {
                     try {