@chrok/pi-braid 0.3.2 → 0.3.4

package/dist/display.js

@@ -1,26 +1,46 @@
 import { render as renderMermaid } from "grok-mermaid";
-import { Text, stripTerminalSequences, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+import { Text, sliceByColumn, stripTerminalSequences, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+import { formatActivityStatus, } from "@chrok/braid";
 export const MAX_VISIBLE_EVENTS = 80;
 export const MAX_VISIBLE_NODES = 80;
 class FixedLines {
     lines;
     chartStart;
     chartLength;
-    constructor(lines, chartStart = lines.length, chartLength = 0) {
+    fallback;
+    focusMarks;
+    /**
+     * A too-wide chart is cropped to the terminal width around the first
+     * `focusMarks` entry drawn in it (the selected node, then a running node),
+     * or from its left edge. `fallback` (a node list while selecting) appears when
+     * there is no chart, or when the selected node cannot be found in it.
+     */
+    constructor(lines, chartStart = lines.length, chartLength = 0, fallback = [], focusMarks = []) {
         this.lines = lines;
         this.chartStart = chartStart;
         this.chartLength = chartLength;
+        this.fallback = fallback;
+        this.focusMarks = focusMarks;
     }
     render(width) {
         const chart = this.lines.slice(this.chartStart, this.chartStart + this.chartLength);
-        if (chart.length === 0)
+        const fallback = this.fallback.map((line) => truncateToWidth(line, width, ""));
+        if (chart.length === 0 && fallback.length === 0)
             return this.lines.map((line) => truncateToWidth(line, width, ""));
-        const chartWidth = Math.max(...chart.map((line) => visibleWidth(line)));
-        const chartOutput = chartWidth <= width
-            ? chart
-            : [
-                truncateToWidth(`[Flowchart needs ${chartWidth} columns; terminal width is ${width}. Expand your terminal to see it.]`, width, ""),
+        const chartWidth = chart.length ? Math.max(...chart.map((line) => visibleWidth(line))) : 0;
+        let chartOutput = chart;
+        if (!chart.length)
+            chartOutput = fallback;
+        else if (chartWidth > width) {
+            const focus = this.focus(chart);
+            const start = focus === undefined ? 0 : Math.max(0, Math.min(chartWidth - width, focus.column - Math.floor(width / 2)));
+            chartOutput = [
+                truncateToWidth(`[chart ${start + 1}–${start + width} of ${chartWidth} cols${focus ? ` · ${focus.label}` : ""}]`, width, ""),
+                ...chart.map((line) => sliceByColumn(line, start, width, true)),
+                // The first mark is the selection; list nodes if it is not drawn.
+                ...(this.focusMarks.length && focus?.mark !== this.focusMarks[0].mark ? fallback : []),
             ];
+        }
         const output = [];
         let chartInserted = false;
         for (let index = 0; index < this.lines.length; index++) {
@@ -37,6 +57,22 @@ class FixedLines {
             output.push(...chartOutput);
         return output;
     }
+    /** The first focus mark drawn in the chart and its centre column. */
+    focus(chart) {
+        for (const { mark, label } of this.focusMarks) {
+            for (const line of chart) {
+                const plain = stripTerminalSequences(line);
+                const index = plain.indexOf(mark);
+                if (index < 0)
+                    continue;
+                // Centre on the label: from the mark to the node's right border, when drawn.
+                const border = plain.indexOf("│", index);
+                const end = border < 0 ? index : border;
+                return { mark, label, column: Math.floor((visibleWidth(plain.slice(0, index)) + visibleWidth(plain.slice(0, end))) / 2) };
+            }
+        }
+        return undefined;
+    }
     invalidate() { }
 }
 function record(value) {
@@ -121,7 +157,9 @@ function nodeElapsed(node, now) {
     }
     return "—";
 }
-function mermaidLabelLines(id, result) {
+/** Replaces the selected node's one-column status icon, so selection never moves the layout. */
+export const SELECTED_NODE_MARK = "◆";
+function mermaidLabelLines(id, result, selected = false) {
     const progress = "progress" in result ? result.progress?.[id] : undefined;
     const node = result.nodes[id];
     if (!node)
@@ -140,7 +178,7 @@ function mermaidLabelLines(id, result) {
     const now = "observedAt" in result ? result.observedAt : Date.now();
     const iteration = "executions" in result ? result.executions[node.executionId ?? ""]?.iteration : result.iterations?.[id];
     const lines = [
-        `${icon} ${compact(id, 24)}${iteration ? ` #${iteration}` : ""}`,
+        `${selected ? SELECTED_NODE_MARK + icon.slice(1) : icon} ${compact(id, 24)}${iteration ? ` #${iteration}` : ""}`,
         `${status}${decision} · ${nodeElapsed(node, now)}`,
     ];
     if (progress) {
@@ -152,7 +190,7 @@ function mermaidLabelLines(id, result) {
     }
     return lines;
 }
-function mermaidSource(result) {
+function mermaidSource(result, selected) {
     const parts = graphParts(result);
     const ids = Object.keys(parts.nodes);
     const names = new Map(ids.map((id, index) => [id, `n${index}`]));
@@ -173,15 +211,22 @@ function mermaidSource(result) {
     for (const id of ids) {
         const shape = parts.nodeTypes[id] === "decision" ? "{" : "[";
         const close = parts.nodeTypes[id] === "decision" ? "}" : "]";
-        lines.push(`  ${names.get(id)}${shape}"${mermaidLabelLines(id, result).map(escapeMermaidText).join("<br/>")}"${close}`);
+        lines.push(`  ${names.get(id)}${shape}"${mermaidLabelLines(id, result, id === selected).map(escapeMermaidText).join("<br/>")}"${close}`);
     }
     for (const edge of parts.edges) {
         lines.push(`  ${names.get(edge.from)} -->${edge.choice ? `|${escapeMermaidText(edge.choice)}|` : ""} ${names.get(edge.to)}`);
     }
     return lines.join("\n");
 }
-function mermaidLines(result, theme) {
-    const art = renderMermaid(mermaidSource(result));
+function mermaidLines(result, theme, selected) {
+    let art;
+    try {
+        art = renderMermaid(mermaidSource(result, selected));
+    }
+    catch {
+        // The chart is a view of state already listed elsewhere; never fail the panel for it.
+        return [];
+    }
     if (!art)
         return [];
     return art.styled.map((row) => row
@@ -190,6 +235,8 @@ function mermaidLines(result, theme) {
             case "border":
                 return theme.fg("borderMuted", span.text);
             case "text":
+                if (selected !== undefined && span.text.includes(SELECTED_NODE_MARK))
+                    return theme.bg("selectedBg", theme.bold(theme.fg("warning", span.text)));
                 return span.text.includes("▶ ACTIVE")
                     ? theme.bg("selectedBg", theme.bold(theme.fg("accent", span.text)))
                     : theme.fg("text", span.text);
@@ -254,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":
@@ -282,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;
@@ -304,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,
@@ -416,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) {
@@ -428,8 +484,46 @@ export function applyProgress(state, progress) {
         writable: true,
     });
 }
+export const COLLAPSED_ACTIVITY_ENTRIES = 6;
+/** Live phase, waits, and chronological history; absence of activity is shown, not judged. */
+export function renderActivity(activity, expanded, theme, now, part = "all") {
+    const ago = (at) => elapsed(Math.max(0, now - at));
+    if (part === "history")
+        return renderActivity(activity, expanded, theme, now).slice(renderActivity(activity, expanded, theme, now, "summary").length);
+    const lines = [theme.fg(activity.finishedAt === undefined ? "accent" : "muted", `activity: ${compact(formatActivityStatus(activity, now), 200)}`)];
+    const model = activity.model;
+    if (model && model.completedAt === undefined) {
+        lines.push(theme.fg("muted", model.firstStreamAt === undefined
+            ? `  model request #${model.round} sent ${ago(model.startedAt)} ago · no stream events received yet`
+            : `  model request #${model.round} sent ${ago(model.startedAt)} ago · ${model.streamEvents} stream events, ${compactCount(model.receivedChars)} chars · last ${ago(model.lastStreamAt)} ago`));
+        if (model.tail)
+            lines.push(theme.fg("dim", `  receiving ${model.receiving === "tool_call" ? `${compact(model.toolName ?? "tool call", 40)} arguments` : model.receiving ?? "output"}: …${compact(model.tail, 160)}`));
+    }
+    for (const tool of activity.tools) {
+        lines.push(theme.fg("warning", `  tool ${compact(tool.name, 40)} running ${ago(tool.startedAt)} · ${tool.lastOutputAt === undefined ? "no output yet" : `last output ${ago(tool.lastOutputAt)} ago`}`));
+        lines.push(theme.fg("dim", `    args: ${compact(tool.arguments, 200)}`));
+        if (tool.outputTail)
+            lines.push(theme.fg("dim", `    output: …${compact(tool.outputTail, 200)}`));
+    }
+    for (const limitation of activity.limitations)
+        lines.push(theme.fg("muted", `  unavailable: ${compact(limitation, 200)}`));
+    if (part === "summary")
+        return lines;
+    const visible = expanded ? activity.entries : activity.entries.slice(-COLLAPSED_ACTIVITY_ENTRIES);
+    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" : 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))) {
+            lines.push(theme.fg("dim", `          ${compact(entry.detail, 300)}${entry.detailLength ? ` (${compactCount(entry.detailLength)} chars)` : ""}`));
+        }
+    }
+    return lines;
+}
 /** Focused status reads must show the requested execution, including historical ones. */
-export function renderNodeResult(node, expanded, theme, fullOutputPath, progress, now = Date.now()) {
+export function renderNodeResult(node, expanded, theme, fullOutputPath, progress, now = Date.now(), activity) {
     const failed = node.status === "failed";
     const clean = (value) => stripTerminalSequences(value).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, "");
     const timing = [
@@ -453,13 +547,54 @@ export function renderNodeResult(node, expanded, theme, fullOutputPath, progress
         ...(node.decision ? [theme.fg("accent", `decision: ${compact(node.decision, 80)}`)] : []),
         ...(node.error ? [theme.fg("error", `${node.error.code}: ${clean(node.error.message)}`)] : []),
         ...(node.skipReason ? [theme.fg("muted", `skipped: ${node.skipReason}`)] : []),
+        // Activity describes one execution; never mix histories from repeated visits.
+        ...(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)}`)] : []),
     ];
     return new Text(lines.join("\n"), 0, 0);
 }
-export function renderGraphResult(result, expanded, isPartial, theme, fallback = "", isError = false) {
+/** Status, timing, and live waits above a node's session transcript. */
+export function renderSessionHeader(node, theme, now, progress, activity) {
+    const failed = node.status === "failed";
+    const live = progress && (!progress.executionId || progress.executionId === node.executionId) ? progress : undefined;
+    const facts = [
+        ...(node.executionId ? [compact(node.executionId, 80)] : []),
+        ...(node.iteration ? [`iteration #${node.iteration}`] : []),
+        ...(node.model ? [compact(node.model, 60)] : []),
+        ...(node.startedAt !== undefined || node.latencyMs !== undefined ? [`elapsed ${nodeElapsed(node, now)}`] : []),
+        ...(node.usage ? [`${compactCount(node.usage.inputTokens)} in / ${compactCount(node.usage.outputTokens)} out tokens`] : []),
+    ];
+    return [
+        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, "");
+    const workspace = node.workspace;
+    const workspaceActive = workspace && ["preparing", "ready", "failed"].includes(workspace.state);
+    const workspaceRef = workspaceActive ? workspace.worktreeRoot : workspace?.checkpointRef ?? workspace?.reason;
+    return [
+        ...(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")] : []),
+    ];
+}
+export function renderGraphResult(result, expanded, isPartial, theme, fallback = "", isError = false, selectedNodeId) {
     if (isError || !result?.nodes) {
         const message = fallback ||
             (isPartial ? "Braid is running…" : "Braid returned no execution details");
@@ -495,8 +630,17 @@ export function renderGraphResult(result, expanded, isPartial, theme, fallback =
     if ("executions" in result)
         lines.push(theme.fg("dim", `${Object.keys(result.executions).length} executions · revision ${result.revision}`));
     const chartStart = lines.length;
-    const chart = mermaidLines(result, theme);
+    const chart = mermaidLines(result, theme, selectedNodeId);
     lines.push(...chart);
+    // Selection must stay usable when the chart cannot be drawn or does not fit.
+    const nodeList = selectedNodeId === undefined ? [] : [
+        theme.fg("dim", chart.length ? "nodes (selected node not found in the flowchart):" : "nodes (flowchart unavailable):"),
+        ...Object.keys(graphParts(result).nodes).map(id => {
+            const node = result.nodes[id];
+            const text = `${id === selectedNodeId ? `${SELECTED_NODE_MARK} ` : "  "}${compact(id, 60)} · ${node?.status ?? "pending"}`;
+            return id === selectedNodeId ? theme.bg("selectedBg", theme.bold(theme.fg("warning", text))) : theme.fg("muted", text);
+        }),
+    ];
     const workspaces = Object.values(result.workspaces ?? {}).filter(workspace => workspace.worktreeRoot);
     if (workspaces.length) {
         const active = workspaces.filter(workspace => ["preparing", "ready", "failed"].includes(workspace.state)).length;
@@ -512,5 +656,8 @@ export function renderGraphResult(result, expanded, isPartial, theme, fallback =
         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)}`));
-    return new FixedLines(lines, chartStart, chart.length);
+    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;
+}

package/dist/index.js

@@ -108,6 +108,8 @@ function isJobSnapshot(value) {
         ["running", "completed", "failed", "cancelled"].includes(job.status ?? "") &&
         !!job.live && typeof job.live.nodes === "object" && job.live.nodes !== null;
 }
+/** Focused reads return the latest activity entries; activityBefore pages earlier ones. */
+export const STATUS_ACTIVITY_ENTRIES = 40;
 function executionControl(job) {
     return job.execution && {
         status: job.execution.status,
@@ -202,11 +204,12 @@ export function createBraidTools(jobs) {
         jobId: Type.Optional(text("Exact session handle (e.g. job-1) or UUID; omit all IDs to list jobs.")),
         executionId: Type.Optional(text("Exact execution ID from braid_status or a reminder; requires jobId. Takes precedence over nodeId; if both are provided they must match.")),
         nodeId: Type.Optional(text("Exact node ID; requires jobId. Retrieve this node's latest full output/error even while the job is running.")),
+        activityBefore: Type.Optional(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER, description: `Focused reads include activity: the current phase, model/tool waits, and the latest ${STATUS_ACTIVITY_ENTRIES} history entries. Pass an entry sequence to page earlier entries.` })),
     }, { additionalProperties: false });
     const statusTool = defineTool({
         name: "braid_status",
         label: "Braid status",
-        description: "Retrieve a background Braid job's status, node progress, and final results by exact session handle (e.g. job-1) or UUID in jobId. Add executionId for an exact execution, or nodeId for the latest instance, including intermediate results while the job runs. All job reads include current execution.revision and execution.pausedExecutionIds for live control; node.revision is the historical invocation revision. Large results include a path to the full JSON, including while running. For usage totals use usage (Pi provider accounting, including rounds from failed nodes), or piUsage in the saved final result. Prefer the short handle from submission/reminders. Omit all IDs to list jobs in this session. Completion reminders arrive automatically; avoid repeated polling.",
+        description: "Retrieve a background Braid job's status, node progress, and final results by exact session handle (e.g. job-1) or UUID in jobId. Add executionId for an exact execution, or nodeId for the latest instance, including intermediate results while the job runs. Focused reads include live activity: phase, time in phase and since the last observed signal, model request/stream state, running tools, and recent history. Lack of observed activity is a diagnostic signal, not proof of a stall. All job reads include current execution.revision and execution.pausedExecutionIds for live control; node.revision is the historical invocation revision. Large results include a path to the full JSON, including while running. For usage totals use usage (Pi provider accounting, including rounds from failed nodes), or piUsage in the saved final result. Prefer the short handle from submission/reminders. Omit all IDs to list jobs in this session. Completion reminders arrive automatically; avoid repeated polling.",
         parameters: statusParameters,
         renderResult(result, options, theme, ctx) {
             const job = result.details;
@@ -227,7 +230,7 @@ export function createBraidTools(jobs) {
                 : nodeId && state && Object.hasOwn(state.nodes, nodeId) ? state.nodes[nodeId] : undefined);
             // Render at the read's observation time so a saved result never keeps counting.
             if (selectedNode)
-                return renderNodeResult(selectedNode, options.expanded, theme, job.nodeOutputPath, job.live.progress?.[selectedNode.id], job.live.observedAt);
+                return renderNodeResult(selectedNode, options.expanded, theme, job.nodeOutputPath, job.live.progress?.[selectedNode.id], job.live.observedAt, job.selectedActivity);
             if (executionId || nodeId)
                 return new Text(fallback || "Braid returned no node details", 0, 0);
             if (job.error)
@@ -242,6 +245,8 @@ export function createBraidTools(jobs) {
         async execute(_id, params) {
             if ((params.nodeId !== undefined || params.executionId !== undefined) && !params.jobId)
                 throw new Error("nodeId/executionId requires jobId");
+            if (params.activityBefore !== undefined && params.nodeId === undefined && params.executionId === undefined)
+                throw new Error("activityBefore requires nodeId or executionId");
             if (!params.jobId)
                 return {
                     content: [{ type: "text", text: JSON.stringify(jobs.list()) }],
@@ -253,9 +258,18 @@ export function createBraidTools(jobs) {
             if (params.nodeId !== undefined || params.executionId !== undefined) {
                 const node = jobs.getNode(params.jobId, params.nodeId, params.executionId);
                 const { id, executionId, status, error, output, ...nodeDetails } = node;
+                const activity = executionId ? jobs.getActivity(params.jobId, executionId, {
+                    limit: STATUS_ACTIVITY_ENTRIES, ...(params.activityBefore === undefined ? {} : { before: params.activityBefore }),
+                }) : undefined;
+                // While running, activity is the useful part; afterwards the output is,
+                // so it comes first and history cannot push it out of the preview.
+                const running = activity && activity.finishedAt === undefined;
+                const live = activity ? { observedAt: job.live.observedAt, activity } : {};
                 const full = JSON.stringify({
                     jobId: job.jobId, handle: job.handle, status: job.status, execution: executionControl(job),
+                    ...(running ? live : {}),
                     node: { id, executionId, status, error, output, ...nodeDetails },
+                    ...(running ? {} : live),
                 }, null, 2);
                 const preview = truncateHead(full);
                 let suffix = "";
@@ -269,7 +283,7 @@ export function createBraidTools(jobs) {
                 }
                 // Focused reads do not claim the whole job's usage; final job retrieval does.
                 return { content: [{ type: "text", text: preview.content + suffix }], details: {
-                        ...job, selectedNode: node, ...(nodeOutputPath ? { nodeOutputPath } : {}),
+                        ...job, selectedNode: node, ...(activity ? { selectedActivity: activity } : {}), ...(nodeOutputPath ? { nodeOutputPath } : {}),
                     } };
             }
             const { jobId, handle, status, error, usage: providerUsage, fullOutputPath, execution, ...snapshot } = job;

package/dist/jobs.js

@@ -3,14 +3,19 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setImmediate as nextTurn } from "node:timers/promises";
 import { truncateHead, } from "@earendil-works/pi-coding-agent";
-import { startBraid, validateGraph, } from "@chrok/braid";
+import { ExecutionActivityTracker, startBraid, validateGraph, } from "@chrok/braid";
 import { applyEvent, applyProgress, createLiveState, } from "./display.js";
 import { createPiRunner, sumPiUsage } from "./runner.js";
+import { PiTranscripts } from "./transcript.js";
+import { PiHumanInputs } from "./human-input.js";
+import { BraidAssistant } from "./assistant.js";
 /** Jobs belong to one extension/session lifetime, independently of foreground turns. */
 export class BraidJobs {
     onFinished;
     onNodeFinished;
     jobs = new Map();
+    assistants = new Map();
+    cwd = process.cwd();
     handles = new Map();
     nextHandle = 1;
     listeners = new Set();
@@ -46,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(),
@@ -57,6 +63,9 @@ export class BraidJobs {
             done: Promise.resolve(),
             usageClaimed: false,
             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);
@@ -79,6 +88,9 @@ export class BraidJobs {
                 runner: (() => {
                     const invoke = createPiRunner(registry, {
                         cwd,
+                        activity: job.activity,
+                        transcripts: job.transcripts,
+                        humanInputs: job.humanInputs,
                         maxToolRounds: options.maxToolRounds ?? Infinity,
                         maxToolCalls: options.maxToolCalls ?? Infinity,
                         onUsage: (usage) => {
@@ -92,9 +104,23 @@ export class BraidJobs {
                             this.changed();
                         },
                     });
-                    return async (request) => { await nextTurn(); return invoke(request); };
+                    return async (request) => {
+                        try {
+                            await nextTurn();
+                            return await invoke(request);
+                        }
+                        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);
+                        }
+                    };
                 })(),
                 onEvent: (event) => {
+                    job.activity.observe(event);
                     if (event.type === "workspace_updated") {
                         job.workspaces ??= {};
                         Object.defineProperty(job.workspaces, event.workspace.executionId ?? event.workspace.nodeId, {
@@ -198,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, ...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();
@@ -220,6 +246,53 @@ export class BraidJobs {
             throw new Error(`Unknown Braid node or execution in ${job.handle}. Use braid_status with only jobId to list executions.`);
         return structuredClone(node);
     }
+    /** Live activity for one exact execution; undefined until it is first observed. */
+    getActivity(jobId, executionId, page) {
+        const job = this.lookup(jobId);
+        if (!job)
+            throw this.unknownJob(jobId);
+        return job.activity.get(executionId, page);
+    }
+    /** The live conversation for one execution; read-only, and absent once evicted. */
+    getTranscript(jobId, executionId) {
+        const job = this.lookup(jobId);
+        if (!job)
+            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)
@@ -292,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();
     }
 }