@chrok/pi-braid 0.3.3 → 0.3.4

package/README.md

@@ -26,6 +26,8 @@ It registers:
 - `braid_cancel` — cancel a job with `{ "jobId": "..." }`.
 - `/braid [jobId]` — open a live flow panel in interactive Pi.
 - `/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.
 
 Submission and completion reminders use short session handles such as `job-1`.
 Status, cancellation and the panel accept either that exact handle or the original
@@ -212,7 +214,10 @@ Braid job-1 · running · 2/5 done · review
 The widget shows node progress, active node IDs, paused gates, and failures.
 It shows up to three active jobs, with an overflow count for the rest. When no
 jobs are active, the newest job's final completed/failed/cancelled status stays
-visible until another job is submitted or the session ends. Counts use the
+visible until another job is submitted or the session ends. Run `/braid:clear`
+to clear the widget: it clears every job submitted so far, including running
+ones, and jobs submitted afterwards still appear. Running it again while the widget
+is empty restores the most recently cleared jobs. Counts use the
 latest state of each current node definition; failed and skipped nodes count as
 done, and reruns or live edits can change progress and totals. RPC, JSON, and
 print modes do not create a terminal widget.
@@ -241,9 +246,51 @@ activity (see below)—stays pinned at the top while the session scrolls. The
 session follows the newest lines; scroll up to pause, and press End to follow again. Left/Right switch between
 invocations of the same node (for example loop iterations), and ctrl+o expands
 tool output. Escape steps back one level—session, then node selection, then the
-graph—and closes the panel from the graph; `q` closes it from anywhere. Sessions
-are read-only. Running invocations and the 20 most recently finished ones per
-job keep their session; older ones show the summary and activity history.
+graph—and closes the panel from the graph; `q` closes it from anywhere. Running
+invocations and the 20 most recently finished ones per job keep their session;
+older ones show the summary and activity history.
+
+### Assistant
+
+Press Tab to open an assistant and Tab again to hide it. While it is open,
+every key goes to it, including `q` and `c`; type a question and press Enter.
+Escape stops an answer in progress, or hides the assistant. PgUp/PgDn or the
+mouse wheel scroll the conversation. A panel at least 100 columns wide shows
+the assistant beside the graph or session; a narrower one shows it in their
+place.
+
+Conversations are scoped. On the graph, the assistant talks about the whole
+job. With a node selected (`v`) or its session open, it uses that node's own
+conversation, shared by all of the node's executions; each question says which
+execution is shown. Each scope keeps its history for the Pi session, including
+while the assistant or the panel is hidden.
+
+In fullscreen mode the mouse wheel also scrolls the left side: the graph, a
+node session, or a node's details and history. Scrolling a session up stops it
+following new output; scrolling back to the bottom resumes.
+
+The assistant uses the main session's current model. It does not see the main
+conversation; each question tells it what the panel shows (the graph, the
+selected node, or the open session), and it reads the job through its own
+tools: job status and graph, an execution's details and activity, and the
+latest messages of a worker's conversation. It cannot edit the graph, cancel,
+or resume; ask the main agent for that.
+
+To steer a running execution, tell the assistant what it should do. The
+assistant messages that execution for you, and only when you ask. The message
+waits, shown as pending in the execution's session, and is delivered before the
+worker's next model request. A tool batch that is running finishes first and is
+never interrupted. If it arrives while the worker is writing its final answer,
+the worker gets one more round to take it into account. The worker receives it
+labelled as a message from the supervising human, separate from the node prompt
+and predecessor outputs; it cannot lift tool, budget, workspace, or decision
+constraints (a decision node that has already called `decide` keeps its
+choice). Delivered messages appear in the session, in the activity history, in
+the event log, and in the execution's `humanInputs` in `braid_status` results,
+so it stays visible that the result did not come from the graph alone. Messages
+still pending when the execution ends are marked as not delivered and are not
+recorded as input. Finished executions, including those held by `pauseAfter`,
+cannot be messaged.
 
 Run `/braid <jobId> <nodeId>` to open that node's latest invocation directly in
 the session view, or `/braid <jobId> <executionId>` for an exact invocation such

package/dist/assistant.js

@@ -0,0 +1,345 @@
+import { Type, validateToolCall, } from "@earendil-works/pi-ai";
+import { truncateHead } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+/** Bounds a single answer, independently of how the model behaves. */
+const MAX_ROUNDS = 24;
+const ACTIVITY_ENTRIES = 40;
+const TRANSCRIPT_MESSAGES = 20;
+const MESSAGE_PREVIEW = 1500;
+const id = (description) => Type.String({ minLength: 1, description });
+const TOOLS = [
+    {
+        name: "job_status",
+        description: "Read this job's goal, status, revision, graph definition (node prompts and edges), the latest result per node, and every execution with its status.",
+        parameters: Type.Object({}, { additionalProperties: false }),
+    },
+    {
+        name: "execution_details",
+        description: "Read one execution: status, output or error, decision, workspace, usage, human inputs, and live activity (phase, model/tool waits, recent history). Pass executionId, or nodeId for the node's latest execution.",
+        parameters: Type.Object({
+            executionId: Type.Optional(id("Exact execution ID.")),
+            nodeId: Type.Optional(id("Node ID; reads its latest execution.")),
+            activityBefore: Type.Optional(Type.Integer({ minimum: 1, description: "Page activity entries before this sequence number." })),
+        }, { additionalProperties: false }),
+    },
+    {
+        name: "execution_transcript",
+        description: "Read the latest messages of one execution's worker conversation: assistant text, tool calls and results, and human messages. Available while it runs and for recently finished executions.",
+        parameters: Type.Object({
+            executionId: id("Exact execution ID."),
+            last: Type.Optional(Type.Integer({ minimum: 1, maximum: 100, description: `Number of latest messages; default ${TRANSCRIPT_MESSAGES}.` })),
+        }, { additionalProperties: false }),
+    },
+    {
+        name: "message_execution",
+        description: "Send a message to a running execution's worker on the user's behalf. It is delivered before the worker's next model request (a running tool batch finishes first) and is recorded as human input on the execution. Use only when the user asks to guide, correct, or inform a running execution. Write a self-contained instruction the worker can act on; it cannot see this conversation.",
+        parameters: Type.Object({
+            executionId: id("Exact ID of a running execution."),
+            message: id("The instruction for the worker."),
+        }, { additionalProperties: false }),
+    },
+];
+const short = (value) => typeof value === "string" ? (value.length > 13 ? `${value.slice(0, 8)}…` : value) : "?";
+const target = (args) => args.executionId !== undefined ? `execution ${short(args.executionId)}` : args.nodeId !== undefined ? `node ${JSON.stringify(args.nodeId)}` : "";
+/** Compact tool cards: what was read or sent, with full results on ctrl+o. */
+function renderer(call) {
+    return {
+        renderCall: (args, theme) => new Text(call(args ?? {}, theme), 0, 0),
+        renderResult: (result, options, theme) => {
+            const text = textOf(result.content);
+            const first = text.split("\n").find(line => line.trim()) ?? "";
+            return new Text(options.expanded ? text : theme.fg("dim", first.length > 160 ? `${first.slice(0, 159)}…` : first), 0, 0);
+        },
+    };
+}
+const RENDERERS = new Map([
+    ["job_status", renderer((_args, theme) => theme.fg("toolTitle", theme.bold("Read job status")))],
+    ["execution_details", renderer((args, theme) => theme.fg("toolTitle", theme.bold("Read details")) + " " + theme.fg("muted", target(args)))],
+    ["execution_transcript", renderer((args, theme) => theme.fg("toolTitle", theme.bold("Read conversation")) + " " + theme.fg("muted", `of ${target(args)}`))],
+    ["message_execution", renderer((args, theme) => theme.fg("warning", theme.bold("✎ Message")) + " " + theme.fg("muted", `to ${target(args)}`) +
+            (typeof args.message === "string" ? `\n${args.message}` : ""))],
+]);
+const clip = (text, max = MESSAGE_PREVIEW) => text.length <= max ? text : `${text.slice(0, max)}… [${text.length - max} more characters]`;
+const textOf = (content) => content.flatMap(block => block.type === "text" && block.text ? [block.text] : []).join("\n");
+function describeTranscript(transcript, last) {
+    const lines = [];
+    const messages = transcript.messages.slice(-last);
+    if (messages.length < transcript.messages.length)
+        lines.push(`[${transcript.messages.length - messages.length} earlier messages omitted]`);
+    else
+        lines.push(`[node prompt] ${clip(transcript.intro.prompt)}`);
+    for (const message of messages) {
+        if (message.role === "human")
+            lines.push(`[human input · ${message.delivered ? "delivered" : "not delivered"}] ${clip(message.text)}`);
+        else if (message.role === "toolResult")
+            lines.push(`[${message.toolName} ${message.isError ? "error" : "result"}] ${clip(textOf(message.content), 800)}`);
+        else if (message.role === "assistant") {
+            for (const block of message.content) {
+                if (block.type === "text" && block.text.trim())
+                    lines.push(`[assistant] ${clip(block.text)}`);
+                else if (block.type === "toolCall")
+                    lines.push(`[tool call ${block.name}] ${clip(JSON.stringify(block.arguments), 400)}`);
+            }
+            if (message.stopReason === "error" || message.stopReason === "aborted")
+                lines.push(`[${message.stopReason}] ${message.errorMessage ?? ""}`);
+        }
+    }
+    if (transcript.streaming)
+        lines.push(`[assistant, streaming] ${clip(textOf(transcript.streaming.content))}`);
+    for (const callId of transcript.running.keys())
+        lines.push(`[tool running] ${callId}`);
+    lines.push(transcript.finished ? "[execution finished]" : "[execution running]");
+    return lines.join("\n");
+}
+/**
+ * A side conversation about one Braid job, or about one node of it. Each
+ * scope keeps its own history. It inspects the job through
+ * read-only tools and can message running executions; graph changes,
+ * cancellation, and resumption stay with the main agent.
+ */
+export class BraidAssistant {
+    jobs;
+    jobId;
+    onChange;
+    nodeId;
+    conversation;
+    history = [];
+    queued = [];
+    controller;
+    pending;
+    disposed = false;
+    constructor(jobs, jobId, cwd, onChange, 
+    /** The node this conversation is about; absent for the whole job. */
+    nodeId) {
+        this.jobs = jobs;
+        this.jobId = jobId;
+        this.onChange = onChange;
+        this.nodeId = nodeId;
+        this.conversation = { cwd, messages: [], running: new Map(), renderers: RENDERERS, version: 0 };
+    }
+    get busy() {
+        return this.controller !== undefined;
+    }
+    /** Ask a question or request an intervention. `view` describes what the panel shows. */
+    send(text, view, model) {
+        if (this.disposed || !text.trim())
+            return;
+        this.conversation.messages.push({ role: "user", content: text, timestamp: Date.now() });
+        this.queued.push({ text, view });
+        this.changed();
+        if (!this.controller)
+            void this.run(model);
+    }
+    /** Stop the current answer; queued questions are dropped. */
+    abort() {
+        this.queued = [];
+        this.controller?.abort();
+    }
+    dispose() {
+        this.disposed = true;
+        this.abort();
+        clearTimeout(this.pending);
+    }
+    systemPrompt() {
+        const job = this.jobs.get(this.jobId);
+        return "You are the Braid assistant inside the /braid panel of Pi. You help the user understand and steer one background Braid job " +
+            `(${job?.handle ?? this.jobId}: ${JSON.stringify(job?.goal ?? "")}). ` +
+            "A Braid job is a graph of nodes; each run of a node is an execution with its own isolated worker conversation. " +
+            "Use your tools to inspect the job instead of guessing, and cite node and execution IDs. " +
+            "When the user asks to guide, correct, or inform a running execution, use message_execution with a clear, self-contained instruction. " +
+            "If it is unclear which execution they mean, or none is running, say so instead of guessing. Never message an execution on your own initiative. " +
+            "Messages reach the worker before its next model request; they cannot change finished executions, the graph, or a decision already made. " +
+            "You cannot edit the graph, cancel, or resume; tell the user to ask the main Pi agent for that. " +
+            "You do not see the main conversation. Answer concisely, in the user's language." +
+            (this.nodeId === undefined
+                ? " This conversation is about the whole job; separate conversations exist for individual nodes."
+                : ` This conversation is about node ${JSON.stringify(this.nodeId)} and all of its executions; when the user says "it" or "this node", they mean this node. ` +
+                    "Each question says which execution the panel shows. You may still read other nodes for context, but message only this node's executions unless the user names another.");
+    }
+    async run(model) {
+        const controller = new AbortController();
+        this.controller = controller;
+        try {
+            while (this.queued.length && !controller.signal.aborted) {
+                for (const { text, view } of this.queued.splice(0)) {
+                    this.history.push({ role: "user", content: `[Panel view: ${view}]\n\n${text}`, timestamp: Date.now() });
+                }
+                await this.answer(model, controller.signal);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.closeToolCalls();
+            this.fail(controller.signal.aborted ? "aborted" : "error", controller.signal.aborted ? "Stopped" : message);
+        }
+        finally {
+            this.controller = undefined;
+            this.conversation.running.clear();
+            this.changed();
+        }
+    }
+    async answer(source, signal) {
+        const model = source.model;
+        if (!model)
+            throw new Error("Choose a Pi model with /model to use the Braid assistant");
+        for (let round = 0; round < MAX_ROUNDS; round++) {
+            signal.throwIfAborted();
+            const context = { systemPrompt: this.systemPrompt(), messages: this.history, tools: TOOLS };
+            const options = { signal, maxRetries: 0 };
+            let response;
+            if (source.registry.stream) {
+                const stream = source.registry.stream(model, context, options);
+                for await (const event of stream) {
+                    if (event.type === "done" || event.type === "error")
+                        continue;
+                    this.conversation.streaming = event.partial;
+                    this.changed(true);
+                }
+                response = await stream.result();
+            }
+            else {
+                response = await source.registry.complete(model, context, options);
+            }
+            delete this.conversation.streaming;
+            this.conversation.messages.push(response);
+            this.changed();
+            if (response.stopReason === "aborted")
+                signal.throwIfAborted();
+            // Failed responses are shown, but never sent back to the provider.
+            if (response.stopReason === "error" || response.stopReason === "aborted")
+                return;
+            this.history.push(response);
+            const calls = response.content.filter((block) => block.type === "toolCall");
+            if (!calls.length)
+                return;
+            for (const call of calls) {
+                signal.throwIfAborted();
+                this.conversation.running.set(call.id, undefined);
+                this.changed();
+                const result = this.execute(call);
+                this.conversation.running.delete(call.id);
+                this.history.push(result);
+                this.conversation.messages.push(result);
+                this.changed();
+            }
+        }
+        this.fail("error", `Stopped after ${MAX_ROUNDS} tool rounds`);
+    }
+    execute(call) {
+        let text;
+        let isError = false;
+        try {
+            const args = validateToolCall(TOOLS, call);
+            text = this.tool(call.name, args);
+        }
+        catch (error) {
+            text = error instanceof Error ? error.message : String(error);
+            isError = true;
+        }
+        return { role: "toolResult", toolCallId: call.id, toolName: call.name, content: [{ type: "text", text }], isError, timestamp: Date.now() };
+    }
+    tool(name, args) {
+        const job = this.jobs.get(this.jobId);
+        if (!job)
+            throw this.jobs.unknownJob(this.jobId);
+        const preview = (value) => {
+            const full = JSON.stringify(value, null, 2);
+            const result = truncateHead(full);
+            return result.truncated ? `${result.content}\n[Truncated; ask about a specific node or execution.]` : full;
+        };
+        switch (name) {
+            case "job_status": {
+                const state = job.result ?? job.execution;
+                return preview({
+                    handle: job.handle, goal: job.goal, status: job.status, error: job.error ?? state?.error,
+                    revision: job.execution?.revision, pausedExecutionIds: job.execution?.pausedExecutionIds,
+                    graph: job.execution?.graph,
+                    nodes: state?.nodes,
+                    executions: Object.values(state?.executions ?? {}).map(execution => ({
+                        executionId: execution.executionId, nodeId: execution.id, status: execution.status,
+                        ...(execution.iteration ? { iteration: execution.iteration } : {}),
+                        ...(execution.humanInputs?.length ? { humanInputs: execution.humanInputs.length } : {}),
+                    })),
+                });
+            }
+            case "execution_details": {
+                if (args.executionId === undefined && args.nodeId === undefined)
+                    throw new Error("Pass executionId or nodeId");
+                const node = this.jobs.getNode(this.jobId, args.nodeId, args.executionId);
+                const activity = node.executionId ? this.jobs.getActivity(this.jobId, node.executionId, {
+                    limit: ACTIVITY_ENTRIES, ...(args.activityBefore === undefined ? {} : { before: args.activityBefore }),
+                }) : undefined;
+                return preview({ node, ...(activity ? { activity } : {}) });
+            }
+            case "execution_transcript": {
+                const transcript = this.jobs.getTranscript(this.jobId, args.executionId);
+                if (!transcript)
+                    throw new Error("No live conversation is retained for this execution; use execution_details for its output and activity history.");
+                return describeTranscript(transcript, args.last ?? TRANSCRIPT_MESSAGES);
+            }
+            case "message_execution": {
+                this.jobs.sendInput(this.jobId, args.executionId, args.message);
+                return "Queued. The worker receives it before its next model request, after any running tool batch.";
+            }
+            default:
+                throw new Error(`Unknown tool ${name}`);
+        }
+    }
+    /** Answer tool calls interrupted by an abort, so the next request is well formed. */
+    closeToolCalls() {
+        let index = this.history.length - 1;
+        while (index >= 0 && this.history[index].role !== "assistant")
+            index--;
+        const last = this.history[index];
+        if (last?.role !== "assistant")
+            return;
+        const answered = new Set(this.history.slice(index + 1).flatMap(message => message.role === "toolResult" ? [message.toolCallId] : []));
+        for (const block of last.content) {
+            if (block.type !== "toolCall" || answered.has(block.id))
+                continue;
+            const result = {
+                role: "toolResult", toolCallId: block.id, toolName: block.name,
+                content: [{ type: "text", text: "Stopped by the user before this tool ran" }], isError: true, timestamp: Date.now(),
+            };
+            this.history.push(result);
+            this.conversation.messages.push(result);
+        }
+    }
+    fail(stopReason, errorMessage) {
+        const partial = this.conversation.streaming;
+        delete this.conversation.streaming;
+        const message = {
+            role: "assistant", api: partial?.api ?? "braid", provider: partial?.provider ?? "braid", model: partial?.model ?? "assistant",
+            content: partial?.content ?? [], stopReason, errorMessage, timestamp: Date.now(),
+            usage: partial?.usage ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        };
+        // The model sees what was said, without a dangling unanswered tool call.
+        if (message.content.some(block => block.type === "toolCall"))
+            message.content = message.content.filter(block => block.type !== "toolCall");
+        this.conversation.messages.push(message);
+        if (message.content.length)
+            this.history.push({ ...message, stopReason: "stop" });
+        this.changed();
+    }
+    /** Token bursts coalesce into at most one notification per 100 ms. */
+    changed(burst = false) {
+        this.conversation.version++;
+        if (!burst) {
+            clearTimeout(this.pending);
+            this.pending = undefined;
+            this.emit();
+        }
+        else if (!this.pending) {
+            this.pending = setTimeout(() => { this.pending = undefined; this.emit(); }, 100);
+            this.pending.unref?.();
+        }
+    }
+    emit() {
+        if (this.disposed)
+            return;
+        try {
+            this.onChange();
+        }
+        catch { /* Observers cannot fail the assistant. */ }
+    }
+}

package/dist/command.js

@@ -1,18 +1,24 @@
-import { matchesKey, stripTerminalSequences, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+import { Input, matchesKey, stripTerminalSequences, truncateToWidth, visibleWidth, wrapTextWithAnsi, } from "@earendil-works/pi-tui";
 import { renderGraphResult, renderNodeDetails, renderSessionHeader, SELECTED_NODE_MARK } from "./display.js";
 import { NodeSessionView } from "./session-view.js";
 // Match the overlay height exactly so Pi never clips the footer or bottom border.
 const panelHeight = (rows) => Math.max(1, Math.floor(rows * 0.9));
 const plain = (value) => stripTerminalSequences(value).replace(/\p{Cc}/gu, " ");
+/** Below this content width the graph and the assistant share the body, switched with Tab. */
+const SPLIT_WIDTH = 100;
+/** Marks a separator row so it can span the whole panel or only the left column. */
+const SEPARATOR = "\u0000separator";
 /**
  * A live, scrollable panel. Esc steps back one level: session → node selection →
- * graph → close. Closing the panel leaves jobs running.
+ * graph → close. Closing the panel leaves jobs running. Tab toggles an assistant
+ * that answers questions about the job and can message running executions.
  */
 export class BraidPanel {
     jobs;
     tui;
     theme;
     done;
+    assistantModel;
     selected;
     focus;
     /** Node highlighted in selection mode (`v`); undefined in the plain graph view. */
@@ -24,18 +30,46 @@ export class BraidPanel {
     offset = 0;
     maxOffset = 0;
     disposed = false;
+    /** While open, the assistant receives keys; it shares a wide panel and fills a narrow one. */
+    assistantOpen = false;
+    /** Where the body sits in the last frame, for routing mouse wheel events. */
+    layout;
+    /** Assistant lines scrolled up from the newest. */
+    chatOffset = 0;
+    chatMaxOffset = 0;
+    chatScope;
+    input;
     session;
+    chat;
     unsubscribe;
     ticker;
-    constructor(jobs, tui, theme, done, jobId, focus) {
+    constructor(jobs, tui, theme, done, jobId, focus, assistantModel = () => ({ registry: { complete: () => Promise.reject(new Error("No Pi model registry")) } })) {
         this.jobs = jobs;
         this.tui = tui;
         this.theme = theme;
         this.done = done;
+        this.assistantModel = assistantModel;
         this.selected = jobId ? jobs.get(jobId)?.jobId ?? jobId : undefined;
         this.focus = focus;
         // Pi's tool components only request renders through the TUI.
         this.session = new NodeSessionView(tui, theme);
+        this.chat = new NodeSessionView(tui, theme);
+        this.input = new Input({
+            prompt: theme.fg("accent", "› "),
+            placeholder: "Ask, or say how to steer…",
+            placeholderStyle: text => theme.fg("dim", text),
+        });
+        this.input.onSubmit = value => {
+            if (!value.trim() || !this.selected)
+                return;
+            const job = this.jobs.get(this.selected);
+            if (!job)
+                return;
+            this.jobs.assistant(job.jobId, this.assistantNode(job)).send(value, this.describeView(job), this.assistantModel());
+            this.input.setValue("");
+            this.chatOffset = 0;
+            this.refresh();
+        };
         this.unsubscribe = jobs.subscribe(() => this.refresh());
         this.ticker = setInterval(() => this.refresh(), 1000);
         this.ticker.unref();
@@ -108,16 +142,56 @@ export class BraidPanel {
         if (current && this.choosing !== undefined && !this.nodeIds(current).includes(this.choosing)) {
             this.choosing = this.nodeIds(current)[0];
         }
+        if (!current)
+            this.assistantOpen = false;
+        const available = rows - header.length - 4;
+        const open = current !== undefined && this.assistantOpen;
+        const split = open && contentWidth >= SPLIT_WIDTH;
+        const leftWidth = split ? Math.floor((contentWidth - 3) * 0.6) : contentWidth;
+        const chatWidth = split ? contentWidth - leftWidth - 3 : contentWidth;
+        const graph = !open || split ? this.renderGraphPane(current, leftWidth, available) : undefined;
+        const chat = open ? this.renderAssistant(current, chatWidth, available) : [];
+        // Columns: border and gutter, then the left pane, " │ ", then the assistant.
+        this.layout = { top: header.length, height: available,
+            ...(open ? { chatLeft: split ? 2 + leftWidth + 3 : 2 } : {}) };
+        const body = split
+            ? graph.lines.map((line, at) => (line === SEPARATOR ? border("─".repeat(leftWidth)) : truncateToWidth(line, leftWidth, "…", true)) +
+                " " + border("│") + " " + (chat[at] ?? ""))
+            : graph?.lines ?? chat;
+        const tab = current ? "Tab assistant   " : "";
+        const [wide, medium, narrow] = open
+            ? ["Enter send   Esc stop or hide   Tab hide   PgUp/PgDn or wheel scroll   ctrl+c close",
+                "Enter send · Esc hide · Tab hide", "Enter send · Tab hide"]
+            : this.focus
+                ? [`${tab}Esc back   ←/→ executions   ↑/↓ scroll   End follow   ctrl+o tools   c cancel   q close`,
+                    "Esc back · ←/→ executions · ↑/↓ scroll · q close", "Esc back · q close"]
+                : this.choosing !== undefined
+                    ? [`${tab}↑/↓/←/→ choose node   Enter open session   Esc back   PgUp/PgDn page   q close`,
+                        "↑/↓ choose · Enter open · Esc back", "Enter open · Esc back"]
+                    : [`${tab}v select node   ←/→ jobs   ↑/↓ scroll   PgUp/PgDn page   c cancel   Esc close`,
+                        "v select node · ←/→ jobs · ↑/↓ scroll · Esc close", "v select · Esc close"];
+        const help = contentWidth >= 80 ? wide : contentWidth >= 42 ? medium : narrow;
+        const status = graph ? graph.range : "Assistant";
+        return [
+            ...header,
+            ...body.map(line => line === SEPARATOR ? rule("├", "┤") : row(line)),
+            rule("├", "┤"),
+            row(this.theme.fg("dim", `${status}${contentWidth >= 60 ? "  ·  Jobs keep running when this panel closes" : ""}`)),
+            row(this.theme.fg("muted", help)),
+            rule("╰", "╯"),
+        ];
+    }
+    /** The graph, node selection, or a node session: pinned summary, separator, scrolled body. */
+    renderGraphPane(current, width, available) {
         // The node summary (or the selected node) stays pinned while the body scrolls.
-        const focused = current && this.focus ? this.renderFocus(current, this.focus, contentWidth) : undefined;
+        const focused = current && this.focus ? this.renderFocus(current, this.focus, width) : undefined;
         let pinned = focused?.pinned ?? (current && this.choosing !== undefined ? [this.choosingLine(current)] : []);
-        const available = rows - header.length - 4;
         const maxPinned = Math.max(2, Math.floor(available / 2));
         if (pinned.length > maxPinned) {
             pinned = [...pinned.slice(0, maxPinned - 1), this.theme.fg("dim", `… ${pinned.length - maxPinned + 1} more summary lines`)];
         }
         const content = focused
-            ? focused.body
+            ? [...focused.body, ...(current && focused.executionId ? this.pendingLines(current, focused.executionId) : [])]
             : current
                 ? [
                     ...(current.error
@@ -130,7 +204,7 @@ export class BraidPanel {
                         ...(current.fullOutputPath
                             ? { fullOutputPath: current.fullOutputPath }
                             : {}),
-                    }, true, false, this.theme, "", false, this.choosing).render(contentWidth),
+                    }, true, false, this.theme, "", false, this.choosing).render(width),
                 ]
                 : ["No Braid jobs in this session."];
         const height = available - (pinned.length ? pinned.length + 1 : 0);
@@ -149,26 +223,96 @@ export class BraidPanel {
         const body = content.slice(this.offset, this.offset + height);
         while (body.length < height)
             body.push("");
-        const range = `Lines ${this.offset + 1}–${Math.min(content.length, this.offset + height)}/${content.length}`;
-        const [wide, medium, narrow] = this.focus
-            ? ["Esc back   ←/→ executions   ↑/↓ scroll   End follow   ctrl+o tools   c cancel   q close",
-                "Esc back · ←/→ executions · ↑/↓ scroll · q close", "Esc back · q close"]
-            : this.choosing !== undefined
-                ? ["↑/↓/←/→ choose node   Enter open session   Esc back   PgUp/PgDn page   q close",
-                    "↑/↓ choose · Enter open · Esc back", "Enter open · Esc back"]
-                : ["v select node   ←/→ jobs   ↑/↓ scroll   PgUp/PgDn page   c cancel   Esc close",
-                    "v select node · ←/→ jobs · ↑/↓ scroll · Esc close", "v select · Esc close"];
-        const help = contentWidth >= 80 ? wide : contentWidth >= 42 ? medium : narrow;
+        return {
+            lines: [...(pinned.length ? [...pinned, SEPARATOR] : []), ...body],
+            range: `Lines ${this.offset + 1}–${Math.min(content.length, this.offset + height)}/${content.length}`,
+        };
+    }
+    /** The job's assistant conversation, newest lines at the bottom, above its input line. */
+    renderAssistant(job, width, height) {
+        const nodeId = this.assistantNode(job);
+        const assistant = this.jobs.assistant(job.jobId, nodeId);
+        // Each scope has its own conversation; a new one starts at its newest lines.
+        const scope = JSON.stringify([job.jobId, nodeId ?? null]);
+        if (scope !== this.chatScope) {
+            this.chatScope = scope;
+            this.chatOffset = 0;
+        }
+        const title = this.theme.fg("accent", this.theme.bold(nodeId === undefined ? "Assistant · job" : `Assistant · node ${plain(nodeId)}`)) +
+            this.theme.fg("muted", assistant.busy ? " · working… Esc to stop" : " · Tab to hide");
+        let lines;
+        try {
+            lines = assistant.conversation.messages.length
+                ? this.chat.render(assistant.conversation, width)
+                : [
+                    // Wrapped, not truncated, and kept off the input line like a finished reply.
+                    ...[
+                        nodeId === undefined
+                            ? "Ask what a node is doing, why it failed, or what it produced."
+                            : `Ask what ${plain(nodeId)} is doing, why it failed, or what it produced.`,
+                        "To change a running execution's direction, say what it should do; the assistant messages that execution for you.",
+                    ].flatMap(hint => wrapTextWithAnsi(this.theme.fg("dim", hint), width)),
+                    "",
+                ];
+        }
+        catch (error) {
+            lines = [this.theme.fg("error", `Assistant view unavailable: ${plain(error instanceof Error ? error.message : String(error))}`)];
+        }
+        const visible = Math.max(1, height - 3);
+        this.chatMaxOffset = Math.max(0, lines.length - visible);
+        this.chatOffset = Math.min(this.chatOffset, this.chatMaxOffset);
+        const end = lines.length - this.chatOffset;
+        const body = lines.slice(Math.max(0, end - visible), end);
+        while (body.length < visible)
+            body.unshift("");
+        this.input.focused = true;
+        const input = this.input.render(width)[0] ?? "";
+        return [title, this.theme.fg("borderMuted", "─".repeat(width)), ...body, input].slice(0, height);
+    }
+    /** Messages the assistant sent that this execution has not received yet. */
+    pendingLines(job, executionId) {
+        let pending = [];
+        try {
+            pending = this.jobs.pendingInputs(job.jobId, executionId);
+        }
+        catch { /* The job was removed; show nothing. */ }
+        if (!pending.length)
+            return [];
         return [
-            ...header,
-            ...(pinned.length ? [...pinned.map(row), rule("├", "┤")] : []),
-            ...body.map(row),
-            rule("├", "┤"),
-            row(this.theme.fg("dim", `${range}${contentWidth >= 60 ? "  ·  Jobs keep running when this panel closes" : ""}`)),
-            row(this.theme.fg("muted", help)),
-            rule("╰", "╯"),
+            ...pending.map(input => this.theme.fg("warning", `⧗ pending human input · ${plain(input.text)}`)),
+            this.theme.fg("dim", "  Delivered before the worker's next model request; running tools are not interrupted."),
         ];
     }
+    /** The node whose conversation the assistant shows: the open session's, or the selected one. */
+    assistantNode(job) {
+        if (!this.focus)
+            return this.choosing;
+        if ("nodeId" in this.focus)
+            return this.focus.nodeId;
+        try {
+            return this.jobs.getNode(job.jobId, undefined, this.focus.executionId).id;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** What the user is looking at, so "this node" means something to the assistant. */
+    describeView(job) {
+        if (this.focus) {
+            try {
+                const node = "nodeId" in this.focus ? this.jobs.getNode(job.jobId, this.focus.nodeId) : this.jobs.getNode(job.jobId, undefined, this.focus.executionId);
+                return `session of node ${JSON.stringify(node.id)}${node.executionId ? `, execution ${node.executionId}` : ""} (${node.status})`;
+            }
+            catch {
+                return "a node that is no longer in the graph";
+            }
+        }
+        if (this.choosing !== undefined) {
+            const node = (job.result?.nodes ?? job.live.nodes)[this.choosing];
+            return `job graph with node ${JSON.stringify(this.choosing)} selected (${node?.status ?? "pending"})`;
+        }
+        return `job graph overview (${job.status})`;
+    }
     /** Graph definition order, which is also the flowchart's declaration order. */
     nodeIds(job) {
         return Object.keys(job.result?.nodes ?? job.live.nodes);
@@ -210,7 +354,7 @@ export class BraidPanel {
         let failure;
         if (transcript) {
             try {
-                return { pinned: header, body: this.session.render(transcript, width) };
+                return { pinned: header, body: this.session.render(transcript, width), executionId: node.executionId };
             }
             catch (error) {
                 // A rendering failure must not take down the overlay; fall back to the summary.
@@ -234,7 +378,21 @@ export class BraidPanel {
         this.offset = 0;
     }
     handleInput(data) {
-        if (data === "q" || matchesKey(data, "ctrl+c")) {
+        if (matchesKey(data, "ctrl+c")) {
+            this.close();
+            return;
+        }
+        if (matchesKey(data, "tab") && this.selected) {
+            this.assistantOpen = !this.assistantOpen;
+            this.refresh();
+            return;
+        }
+        if (this.assistantOpen) {
+            this.assistantInput(data);
+            this.refresh();
+            return;
+        }
+        if (data === "q") {
             this.close();
             return;
         }
@@ -314,6 +472,44 @@ export class BraidPanel {
         else
             this.scroll(data);
     }
+    /** The wheel scrolls whichever side it is over; other mouse events are left to Pi. */
+    handleMouse(event) {
+        const layout = this.layout;
+        if (event.type !== "wheel" || !event.wheelDelta || !layout)
+            return undefined;
+        if (event.y < layout.top || event.y >= layout.top + layout.height)
+            return undefined;
+        if (layout.chatLeft !== undefined && event.x >= layout.chatLeft - 1) {
+            this.chatOffset = Math.max(0, Math.min(this.chatMaxOffset, this.chatOffset - event.wheelDelta));
+        }
+        else {
+            const before = this.offset;
+            this.offset = Math.max(0, Math.min(this.maxOffset, this.offset + event.wheelDelta));
+            if (this.offset < before)
+                this.follow = false;
+            else if (this.offset >= this.maxOffset)
+                this.follow = true;
+        }
+        this.refresh();
+        return { handled: true };
+    }
+    /** Every key belongs to the question, including q and c. */
+    assistantInput(data) {
+        const job = this.selected ? this.jobs.get(this.selected) : undefined;
+        const assistant = job ? this.jobs.assistant(job.jobId, this.assistantNode(job)) : undefined;
+        if (matchesKey(data, "escape")) {
+            if (assistant?.busy)
+                assistant.abort();
+            else
+                this.assistantOpen = false;
+        }
+        else if (matchesKey(data, "pageUp"))
+            this.chatOffset = Math.min(this.chatMaxOffset, this.chatOffset + 10);
+        else if (matchesKey(data, "pageDown"))
+            this.chatOffset = Math.max(0, this.chatOffset - 10);
+        else
+            this.input.handleInput(data);
+    }
     scroll(data) {
         const before = this.offset;
         if (matchesKey(data, "up"))
@@ -348,23 +544,54 @@ export class BraidPanel {
     }
 }
 export function registerBraidWidget(pi, jobs) {
+    // Clearing hides the jobs present at that moment; jobs submitted later still show.
+    const cleared = new Set();
+    let lastCleared = [];
+    const shown = () => jobs.list().filter(job => !cleared.has(job.jobId));
+    let refresh = () => { };
     let dispose = () => { };
     const clear = () => {
         dispose();
         dispose = () => { };
+        refresh = () => { };
     };
+    pi.registerCommand("braid:clear", {
+        description: "Clear the Braid progress widget; run again while it is empty to restore it",
+        handler: async (_args, ctx) => {
+            if (ctx.mode !== "tui")
+                throw new Error("The Braid progress widget requires interactive Pi.");
+            const visible = shown();
+            if (visible.length) {
+                lastCleared = visible.map(job => job.jobId);
+                for (const jobId of lastCleared)
+                    cleared.add(jobId);
+                ctx.ui.notify("Cleared Braid progress. Run /braid:clear again to restore it.", "info");
+            }
+            else if (lastCleared.length) {
+                for (const jobId of lastCleared)
+                    cleared.delete(jobId);
+                lastCleared = [];
+                ctx.ui.notify("Restored Braid progress.", "info");
+            }
+            else {
+                ctx.ui.notify("No Braid progress to clear.", "info");
+                return;
+            }
+            refresh();
+        },
+    });
     pi.on("session_start", (_event, ctx) => {
         clear();
         if (ctx.mode !== "tui")
             return;
-        const refresh = () => {
-            if (!jobs.list().length) {
+        refresh = () => {
+            if (!shown().length) {
                 ctx.ui.setWidget("braid-status", undefined);
                 return;
             }
             ctx.ui.setWidget("braid-status", (_tui, theme) => ({
                 render(width) {
-                    const all = jobs.list();
+                    const all = shown();
                     const active = all.filter(job => job.status === "running");
                     const selected = active.length ? active.slice(0, 3) : all.slice(0, 1);
                     const lines = selected.map(job => {
@@ -393,7 +620,7 @@ export function registerBraidWidget(pi, jobs) {
                 invalidate() { },
             }), { placement: "aboveEditor" });
         };
-        const unsubscribe = jobs.subscribe(refresh);
+        const unsubscribe = jobs.subscribe(() => refresh());
         dispose = () => {
             unsubscribe();
             ctx.ui.setWidget("braid-status", undefined);
@@ -416,7 +643,8 @@ export function registerBraidCommand(pi, jobs) {
             let panel;
             try {
                 await ctx.ui.custom((tui, theme, _keys, done) => {
-                    panel = new BraidPanel(jobs, tui, theme, done, jobId, focus);
+                    // The assistant uses whichever model the main session has selected when asked.
+                    panel = new BraidPanel(jobs, tui, theme, done, jobId, focus, () => ({ registry: ctx.modelRegistry, ...(ctx.model ? { model: ctx.model } : {}) }));
                     return panel;
                 }, {
                     overlay: true,

package/dist/display.js

@@ -301,6 +301,8 @@ function eventText(event) {
             return `handoff · ${compact(event.from, 40)} → ${compact(event.to, 40)}: ${compact(event.output, 64)}`;
         case "node_started":
             return `started · ${compact(event.nodeId, 40)}${event.model ? ` · ${compact(event.model, 50)}` : ""}`;
+        case "human_input":
+            return `human input · ${compact(event.nodeId, 40)}: ${compact(event.text, 64)}`;
         case "node_completed":
             return `completed · ${compact(event.nodeId, 40)}${event.decision ? ` → ${compact(event.decision, 30)}` : ""}: ${compact(event.output, 64)}`;
         case "node_skipped":
@@ -329,7 +331,9 @@ function renderEventLog(events, expanded, theme) {
                 ? "success"
                 : event.type === "node_started"
                     ? "accent"
-                    : "dim";
+                    : event.type === "human_input"
+                        ? "warning"
+                        : "dim";
         lines.push(theme.fg(color, `  ${String(event.sequence).padStart(3, "0")} ${eventText(event)}`));
     }
     return lines;
@@ -351,6 +355,8 @@ export function applyEvent(state, event) {
     const preview = { ...event };
     if ("output" in preview && preview.output !== undefined)
         preview.output = compact(preview.output, 180);
+    if (preview.type === "human_input")
+        preview.text = compact(preview.text, 180);
     if ("error" in preview)
         preview.error = {
             ...preview.error,
@@ -463,6 +469,9 @@ export function applyEvent(state, event) {
             node.skipReason = event.reason;
             node.finishedAt = event.timestamp;
             break;
+        case "human_input":
+            node.humanInputs = [...(node.humanInputs ?? []), { text: compact(event.text, 180), timestamp: event.timestamp }];
+            break;
     }
 }
 export function applyProgress(state, progress) {
@@ -504,7 +513,7 @@ export function renderActivity(activity, expanded, theme, now, part = "all") {
     const hidden = activity.droppedEntries + activity.entries.length - visible.length;
     lines.push(theme.fg("dim", `history · ${activity.sequence} events${hidden ? ` · ${hidden} earlier ${expanded ? "trimmed" : "hidden (expand for more)"}` : ""}:`));
     for (const entry of visible) {
-        const color = entry.isError ? "error" : entry.kind === "tool_call" ? "accent" : entry.kind === "assistant" ? "text" : "muted";
+        const color = entry.isError ? "error" : entry.kind === "tool_call" ? "accent" : entry.kind === "assistant" ? "text" : entry.kind === "human_input" ? "warning" : "muted";
         lines.push(theme.fg(color, `  ${`+${elapsed(Math.max(0, entry.timestamp - activity.startedAt))}`.padStart(7)} ${compact(entry.summary, 200)}`));
         // Show a detail preview only when the summary line does not already contain it.
         if (expanded && entry.detail && entry.kind !== "workspace" && !compact(entry.summary, 400).includes(compact(entry.detail, 400))) {
@@ -561,10 +570,12 @@ export function renderSessionHeader(node, theme, now, progress, activity) {
         theme.fg(failed ? "error" : "accent", `${failed ? "✗" : node.status === "completed" ? "✓" : node.status === "running" ? "▶" : "○"} Braid node ${compact(node.id, 80)} · ${node.status}`),
         ...(facts.length ? [theme.fg("muted", facts.join(" · "))] : []),
         ...(live ? [theme.fg("muted", `context ${live.contextSource === "estimate" ? "~" : ""}${compactCount(live.contextTokens)}/${live.contextWindow === undefined ? "—" : compactCount(live.contextWindow)} · ${live.toolCalls} tool calls in ${live.toolRounds} rounds · ${live.phase} phase`)] : []),
+        ...(node.humanInputs?.length ? [theme.fg("warning", humanInputNotice(node.humanInputs.length))] : []),
         ...(activity && activity.executionId === node.executionId ? renderActivity(activity, false, theme, now, "summary") : []),
         ...(node.error ? [theme.fg("error", `${node.error.code}: ${compact(node.error.message, 300)}`)] : []),
     ];
 }
+const humanInputNotice = (count) => `✎ received ${count} human message${count === 1 ? "" : "s"} while running; its result is not from the graph alone`;
 /** What a node view shows below its pinned header when no live session is retained. */
 export function renderNodeDetails(node, theme, now, activity) {
     const clean = (value) => stripTerminalSequences(value).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, "");
@@ -575,6 +586,10 @@ export function renderNodeDetails(node, theme, now, activity) {
         ...(workspace ? [theme.fg("dim", `workspace: ${workspace.mode} · ${workspace.state}${workspaceRef ? ` · ${compact(workspaceRef, 160)}` : ""}`)] : []),
         ...(node.decision ? [theme.fg("accent", `decision: ${compact(node.decision, 80)}`)] : []),
         ...(node.skipReason ? [theme.fg("muted", `skipped: ${node.skipReason}`)] : []),
+        ...(node.humanInputs?.length ? [
+            theme.fg("warning", humanInputNotice(node.humanInputs.length)),
+            ...node.humanInputs.map(input => theme.fg("warning", `  ✎ ${compact(clean(input.text), 300)}`)),
+        ] : []),
         ...(activity && activity.executionId === node.executionId ? renderActivity(activity, true, theme, now, "history") : []),
         ...(node.output ? ["", ...clean(node.output).split("\n")] : []),
     ];

package/dist/human-input.js

@@ -0,0 +1,60 @@
+/**
+ * Messages a human sent to running executions, keyed by execution ID. The
+ * runner takes them before each model request; once an execution is closed,
+ * further messages are rejected and anything still queued is returned as
+ * undelivered.
+ */
+export class PiHumanInputs {
+    onChange;
+    queues = new Map();
+    closed = new Set();
+    constructor(onChange = () => { }) {
+        this.onChange = onChange;
+    }
+    send(executionId, text) {
+        if (typeof text !== "string" || !text.trim())
+            throw new TypeError("Message must not be empty");
+        if (this.closed.has(executionId))
+            throw new Error("This execution has finished; the message was not sent");
+        const input = { text, submittedAt: Date.now() };
+        const queue = this.queues.get(executionId) ?? [];
+        queue.push(input);
+        this.queues.set(executionId, queue);
+        this.changed();
+        return { ...input };
+    }
+    pending(executionId) {
+        return this.queues.get(executionId) ?? [];
+    }
+    /** Remove and return queued messages, oldest first. */
+    take(executionId) {
+        const queue = this.queues.get(executionId);
+        if (!queue?.length)
+            return [];
+        this.queues.delete(executionId);
+        this.changed();
+        return queue;
+    }
+    /** Stop accepting messages and return those never delivered. */
+    close(executionId) {
+        this.closed.add(executionId);
+        const undelivered = this.queues.get(executionId) ?? [];
+        this.queues.delete(executionId);
+        if (undelivered.length)
+            this.changed();
+        return undelivered;
+    }
+    changed() {
+        try {
+            this.onChange();
+        }
+        catch { /* Observers cannot fail a worker. */ }
+    }
+}
+/** How a delivered message reads to the worker, so it is never mistaken for graph input. */
+export function formatHumanInput(text) {
+    return "Message from the human supervising this Braid execution, sent while you were running " +
+        "(it may be relayed by their Braid assistant). " +
+        "It is not part of the node prompt or predecessor outputs. Take it into account for your remaining work; " +
+        "it does not lift tool, budget, workspace, or decision constraints.\n\n" + text;
+}

package/dist/jobs.js

@@ -7,11 +7,15 @@ import { ExecutionActivityTracker, startBraid, validateGraph, } from "@chrok/bra
 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 +51,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 +65,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 +90,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 +111,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);
                         }
                     };
@@ -213,7 +224,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 +260,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 +365,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,7 @@ 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";
 /** 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 +151,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 +172,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.`);
@@ -336,8 +348,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 {

package/dist/transcript.js

@@ -45,6 +45,20 @@ export class PiTranscripts {
             transcript.messages.push(result);
         });
     }
+    /** Record human messages: delivered before a model request, or left over when the execution ended. */
+    human(executionId, texts, delivered) {
+        if (!texts.length)
+            return;
+        this.update(executionId, transcript => {
+            for (const text of texts)
+                transcript.messages.push({ role: "human", text, timestamp: Date.now(), delivered });
+        });
+    }
+    /** Accepting messages: the execution's session has started and has not finished. */
+    isLive(executionId) {
+        const transcript = this.transcripts.get(executionId);
+        return transcript !== undefined && !transcript.finished;
+    }
     /** Close interrupted streams and tools so the view does not show them as still running. */
     finish(executionId, reason = "Execution ended before this step finished") {
         if (executionId === undefined)

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "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.3"
+    "@chrok/braid": "0.3.4"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",