@chrok/pi-braid 0.3.2 → 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.
@@ -225,11 +230,81 @@ Use Left/Right to select jobs, Up/Down or Page Up/Page Down to scroll, `c` to
 cancel the selected job, and Escape or `q` to close the panel. Closing the panel
 leaves jobs running. In RPC or noninteractive modes, use `braid_status`.
 
-Run `/braid <jobId> <nodeId>` to open the panel on one node's latest invocation,
-or `/braid <jobId> <executionId>` for an exact invocation such as an earlier loop
-iteration. The node view refreshes live with its status, model, elapsed time,
-token usage, context size, tool-call count, workspace, and full output or error.
-Press Backspace to return to the whole graph; switching jobs also returns to it.
+A flowchart wider than the terminal is cropped to the terminal width around the
+first running node, or from its left edge; a `[chart 1–76 of 245 cols]` line
+shows the visible columns.
+
+Press `v` to select a node: the arrow keys move a `◆` marker through the
+flowchart (starting at a running node), and the view pans horizontally and
+scrolls vertically to keep the selected node in sight. If the flowchart cannot be
+drawn, a node list replaces it while selecting. Enter opens that node's latest
+invocation as a live session. The session is drawn with Pi's own chat
+components, as in the main conversation: the worker's prompt, streamed
+assistant text and thinking, and tool cards whose arguments and output update
+while they run. The node summary—status, elapsed time, usage, context, and live
+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. 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
+as an earlier loop iteration. The header shows live activity for that exact invocation: the current phase
+(workspace preparation, worker, model request, tool, or checkpoint/cleanup) and
+how long it has been in it, time since the last observed signal, total time, the
+in-flight model request (sent, awaiting the first stream event, or streaming
+text/reasoning/tool-call arguments with a character count and latest tail), and
+running tools with their arguments, elapsed time, and latest output. Focused
+`braid_status` reads, and invocations whose session is no longer retained, add a
+chronological history of model requests and responses, assistant text, tool calls
+and results, workspace changes, and completion, with bounded detail previews.
+A quiet period is shown as elapsed time, not declared a stall. If the host cannot
+report a signal—for example a model registry without streaming—the view says so.
 Tab completes job handles and then that job's node IDs.
 IDs with leading/trailing whitespace, terminal controls, or a leading double
 quote use JSON string syntax, such as `/braid job-1 " review "` or
@@ -241,7 +316,10 @@ estimates or provider-reported usage, context-window sizes, filesystem tool-call
 counts, and the execution log. Active nodes are marked `▶ ACTIVE`. The status
 tool also renders a flowchart; expand its result to see more log events.
 When selecting `nodeId` or `executionId`, it instead shows that invocation's
-output/error, with the full text available on expansion.
+output/error and activity, with the full text and history available on expansion.
+The JSON includes `activity` with the latest 40 history entries; pass
+`activityBefore` with an entry sequence to page earlier ones. While the invocation
+runs, `activity` comes before `node` so it survives preview truncation.
 
 `/braid` now opens this panel; it no longer arms the next prompt. To request
 Braid explicitly, ask the agent to analyze the task using Braid.

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. */ }
+    }
+}