@chrok/pi-braid 0.3.3 → 0.3.5

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
@@ -127,10 +201,7 @@ export class BraidPanel {
                         ...(current.result ?? current.live),
                         progress: current.live.progress,
                         ...(current.workspaces ? { workspaces: current.workspaces } : {}),
-                        ...(current.fullOutputPath
-                            ? { fullOutputPath: current.fullOutputPath }
-                            : {}),
-                    }, true, false, this.theme, "", false, this.choosing).render(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 +220,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 +351,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 +375,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 +469,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 +541,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 +617,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 +640,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))) {
@@ -542,7 +551,7 @@ export function renderNodeResult(node, expanded, theme, fullOutputPath, progress
         ...(activity && activity.executionId === node.executionId ? renderActivity(activity, expanded, theme, now) : []),
         ...(node.output ? [expanded ? clean(node.output) : compact(node.output, 400)] : []),
         ...(!expanded && node.output && (node.output.length > 400 || node.output.includes("\n")) ? [theme.fg("dim", "Expand for full node output")] : []),
-        ...(fullOutputPath ? [theme.fg("dim", `full node result: ${compact(fullOutputPath, 240)}`)] : []),
+        ...(fullOutputPath ? [theme.fg("dim", `full text: ${compact(fullOutputPath, 240)}`)] : []),
     ];
     return new Text(lines.join("\n"), 0, 0);
 }
@@ -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")] : []),
     ];
@@ -640,7 +655,7 @@ export function renderGraphResult(result, expanded, isPartial, theme, fallback =
     if (expanded)
         lines.push(...renderEventLog(result.events ?? [], true, theme));
     if ("fullOutputPath" in result && result.fullOutputPath)
-        lines.push(theme.fg("dim", `full result/log: ${compact(result.fullOutputPath, 240)}`));
+        lines.push(theme.fg("dim", `full text: ${compact(result.fullOutputPath, 240)}`));
     return new FixedLines(lines, chartStart, chart.length, nodeList, [
         ...(selectedNodeId === undefined ? [] : [{ mark: SELECTED_NODE_MARK, label: "selected node" }]),
         { mark: "▶ ACTIVE", label: "running node" },

package/dist/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;
+}