@chrok/pi-braid 0.3.2 → 0.3.4

package/dist/runner.js

@@ -4,6 +4,7 @@ import { formatBudgetReminder, gitToolDefinition, finishMergeToolDefinition, mer
 import { createWorktreeWriteTools } from "./write-tools.js";
 import { createAvailableReadTools } from "./read-tools.js";
 import { createWorkspaceShellTools } from "./shell-tools.js";
+import { formatHumanInput } from "./human-input.js";
 /** Keep Pi's provider/auth plumbing and filesystem capabilities out of Braid's core. */
 export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd()) {
     const options = typeof onUsageOrOptions === "function"
@@ -41,6 +42,9 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
         const model = registry.find(name.slice(0, slash), name.slice(slash + 1));
         if (!model)
             throw new Error(`Pi model '${name}' is not registered; use an exact provider/modelId from /model`);
+        const activity = options.activity?.recorder(request);
+        if (!registry.stream)
+            activity?.limitation("This Pi model registry does not stream; model activity is observed only when a request starts and finishes.");
         const workspace = request.workspace ?? {
             nodeId: request.node.id, mode: "read-only", workingDirectory: sourceDirectory, state: "ready",
         };
@@ -139,6 +143,24 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
             tools: allToolDefinitions,
         };
         const toolByName = new Map(fileTools.map((tool) => [tool.name, tool]));
+        const executionId = request.execution.executionId;
+        const transcripts = executionId === undefined ? undefined : options.transcripts;
+        transcripts?.start(executionId, request.node.id, workingDirectory, {
+            prompt: request.node.prompt ?? `Default ${request.node.type} instructions`,
+            goal: request.goal,
+            predecessors: request.predecessors.length,
+            workspace: `${workspace.mode} · ${workingDirectory}`,
+        }, toolByName);
+        const humanInputs = executionId === undefined ? undefined : options.humanInputs;
+        // Between model requests only: a running tool batch is never interrupted.
+        const deliverHumanInputs = () => {
+            const inputs = humanInputs?.take(executionId) ?? [];
+            for (const input of inputs) {
+                request.recordHumanInput?.(input.text);
+                context.messages.push({ role: "user", content: formatHumanInput(input.text), timestamp: Date.now() });
+            }
+            transcripts?.human(executionId, inputs.map(input => input.text), true);
+        };
         const systemPrompt = context.systemPrompt;
         const sessionId = crypto.randomUUID();
         const usage = { inputTokens: 0, outputTokens: 0 };
@@ -150,6 +172,7 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
         let reportedContextTokens;
         const complete = async () => {
             request.signal.throwIfAborted();
+            deliverHumanInputs();
             const budgets = [];
             if (Number.isFinite(maxToolRounds)) {
                 budgets.push(`Tool round budget: ${toolRounds}/${maxToolRounds} used; ${maxToolRounds - toolRounds} remaining. A round is one assistant response containing tool calls.`);
@@ -171,14 +194,54 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
                 toolRounds,
                 phase: "model",
             });
-            // Registry.complete resolves stored API keys, OAuth, custom headers and endpoints.
-            const response = await registry.complete(model, context, {
+            // The registry resolves stored API keys, OAuth, custom headers and endpoints.
+            // complete() is stream().result(); streaming only adds observation.
+            const requestOptions = {
                 signal: request.signal,
                 sessionId,
                 cacheRetention: "none",
                 transport: "sse",
                 maxRetries: 0,
+            };
+            activity?.modelRequest();
+            let response;
+            try {
+                if (registry.stream) {
+                    const stream = registry.stream(model, context, requestOptions);
+                    for await (const event of stream) {
+                        if (event.type !== "done" && event.type !== "error")
+                            transcripts?.streaming(executionId, event.partial);
+                        if (event.type === "text_delta")
+                            activity?.modelStream("text", event.delta);
+                        else if (event.type === "thinking_delta")
+                            activity?.modelStream("reasoning", event.delta);
+                        else if (event.type === "toolcall_start" || event.type === "toolcall_delta") {
+                            const block = event.partial.content[event.contentIndex];
+                            activity?.modelStream("tool_call", event.type === "toolcall_delta" ? event.delta : "", block?.type === "toolCall" ? block.name : undefined);
+                        }
+                    }
+                    response = await stream.result();
+                }
+                else {
+                    response = await registry.complete(model, context, requestOptions);
+                }
+            }
+            catch (error) {
+                activity?.modelError(error instanceof Error ? error.message : String(error));
+                throw error;
+            }
+            transcripts?.assistant(executionId, response);
+            activity?.modelResponse({
+                text: response.content.flatMap(block => block.type === "text" ? [block.text] : []).join("\n\n"),
+                reasoning: response.content.flatMap(block => block.type === "thinking" ? [block.thinking] : []).join("\n\n"),
+                toolCalls: response.content.flatMap(block => block.type === "toolCall" ? [{ id: block.id, name: block.name }] : []),
+                stopReason: response.stopReason,
+                inputTokens: response.usage.input + response.usage.cacheRead + response.usage.cacheWrite,
+                outputTokens: response.usage.output,
             });
+            if (response.stopReason !== "stop" && response.stopReason !== "toolUse") {
+                activity?.modelError(response.errorMessage || `Pi model ended with '${response.stopReason}'`);
+            }
             actualModel = `${response.provider}/${response.responseModel ?? response.model}`;
             const providerContextTokens = response.usage.input +
                 response.usage.cacheRead +
@@ -234,7 +297,13 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
                     return toolResult(call, "Merge dispositions recorded. Return your final answer.", false);
                 }
                 const args = validateToolCall(allToolDefinitions, call);
-                const execute = () => tool.execute(call.id, args, request.signal, undefined);
+                const execute = () => tool.execute(call.id, args, request.signal, 
+                // Bash sends cumulative, throttled output snapshots.
+                (partial) => {
+                    activity?.toolOutput(call.id, partial.content
+                        .flatMap(block => block.type === "text" ? [block.text] : []).join(""), "replace");
+                    transcripts?.toolUpdate(executionId, call.id, { content: partial.content, details: partial.details });
+                });
                 const result = ["write", "edit", "bash", "powershell"].includes(call.name) && request.withWorkspaceWrite
                     ? await request.withWorkspaceWrite(execute)
                     : await execute();
@@ -254,6 +323,24 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
                 return toolResult(call, error instanceof Error ? error.message : String(error), true);
             }
         };
+        const executeCall = async (call) => {
+            if (call.name !== "decide")
+                return executeFileTool(call);
+            if (request.node.type !== "decision") {
+                return toolResult(call, "decide is available only on decision nodes", true);
+            }
+            const args = call.arguments;
+            if (!args ||
+                Array.isArray(args) ||
+                Object.keys(args).length !== 1 ||
+                typeof args.choice !== "string") {
+                throw new Error("decide requires exactly one string argument: choice");
+            }
+            // No coercion or prose parsing: the core enforces the enum and exactly one call.
+            request.decide(args.choice);
+            decided = true;
+            return toolResult(call, JSON.stringify({ choice: args.choice }), false);
+        };
         while (true) {
             const response = await complete();
             textParts.push(...response.content
@@ -261,8 +348,13 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
                 .map((block) => block.text));
             const calls = response.content.filter((block) => block.type === "toolCall");
             if (calls.length === 0) {
-                if (response.stopReason === "stop")
-                    break;
+                if (response.stopReason === "stop") {
+                    // A message that arrived during the final request gets one more round.
+                    if (!humanInputs?.pending(executionId).length)
+                        break;
+                    context.messages.push(response);
+                    continue;
+                }
                 throw new Error("Pi model requested tool use without a tool call");
             }
             if (response.stopReason !== "toolUse") {
@@ -287,26 +379,20 @@ export function createPiRunner(registry, onUsageOrOptions, cwd = process.cwd())
             const results = [];
             for (const call of calls) {
                 request.signal.throwIfAborted();
-                if (call.name === "decide") {
-                    if (request.node.type !== "decision") {
-                        results.push(toolResult(call, "decide is available only on decision nodes", true));
-                        continue;
-                    }
-                    const args = call.arguments;
-                    if (!args ||
-                        Array.isArray(args) ||
-                        Object.keys(args).length !== 1 ||
-                        typeof args.choice !== "string") {
-                        throw new Error("decide requires exactly one string argument: choice");
-                    }
-                    // No coercion or prose parsing: the core enforces the enum and exactly one call.
-                    request.decide(args.choice);
-                    decided = true;
-                    results.push(toolResult(call, JSON.stringify({ choice: args.choice }), false));
+                activity?.toolStart(call.id, call.name, call.arguments);
+                transcripts?.toolStart(executionId, call.id);
+                let result;
+                try {
+                    result = await executeCall(call);
                 }
-                else {
-                    results.push(await executeFileTool(call));
+                catch (error) {
+                    activity?.toolEnd(call.id, error instanceof Error ? error.message : String(error), true);
+                    throw error;
                 }
+                activity?.toolEnd(call.id, result.content
+                    .flatMap(block => block.type === "text" ? [block.text] : []).join("\n"), result.isError);
+                transcripts?.toolResult(executionId, result);
+                results.push(result);
             }
             context.messages.push(...results);
             if (decided) {

package/dist/session-view.js

@@ -0,0 +1,138 @@
+import { AssistantMessageComponent, getMarkdownTheme, ToolExecutionComponent, UserMessageComponent, } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, stripTerminalSequences, Text } from "@earendil-works/pi-tui";
+const plain = (value) => stripTerminalSequences(value).replace(/\p{Cc}/gu, " ");
+/**
+ * Renders a worker conversation with Pi's own chat components, applying only
+ * what changed since the last sync, the way Pi's interactive mode streams.
+ */
+export class NodeSessionView {
+    tui;
+    theme;
+    chat = new Container();
+    transcript;
+    version = -1;
+    rendered = 0;
+    streaming;
+    tools = new Map();
+    partials = new Map();
+    expanded = false;
+    constructor(tui, theme) {
+        this.tui = tui;
+        this.theme = theme;
+    }
+    /** Tool output expansion, like Pi's ctrl+o. */
+    toggleExpanded() {
+        this.expanded = !this.expanded;
+        for (const tool of this.tools.values())
+            tool.setExpanded(this.expanded);
+        this.version = -1;
+    }
+    render(transcript, width) {
+        this.sync(transcript);
+        // Pi marks its own prompts for terminal shell integration; these are not prompts.
+        return this.chat.render(width).map(line => line.replace(/\x1b\]133;[^\x07\x1b]*(?:\x07|\x1b\\)/g, ""));
+    }
+    sync(transcript) {
+        if (transcript !== this.transcript)
+            this.reset(transcript);
+        if (transcript.version === this.version)
+            return;
+        this.version = transcript.version;
+        for (; this.rendered < transcript.messages.length; this.rendered++) {
+            const message = transcript.messages[this.rendered];
+            if (message.role === "human") {
+                this.gap();
+                this.add(new Text(message.delivered
+                    ? this.theme.fg("warning", "✎ Human input · delivered before the next model request")
+                    : this.theme.fg("error", "✎ Human input · not delivered: the execution ended before its next model request"), 1, 0));
+                this.add(new UserMessageComponent(message.text, getMarkdownTheme()));
+                continue;
+            }
+            if (message.role === "user") {
+                const text = typeof message.content === "string" ? message.content
+                    : message.content.flatMap(block => block.type === "text" ? [block.text] : []).join("\n");
+                this.gap();
+                this.add(new UserMessageComponent(text, getMarkdownTheme()));
+                continue;
+            }
+            if (message.role === "toolResult") {
+                this.tools.get(message.toolCallId)?.updateResult(message);
+                this.partials.delete(message.toolCallId);
+                continue;
+            }
+            // The final message replaces the streamed partial in the same component.
+            const component = this.streaming ?? this.add(new AssistantMessageComponent(undefined, false, getMarkdownTheme()));
+            this.streaming = undefined;
+            component.updateContent(message, false);
+            this.toolCalls(message, transcript, true);
+            // A reply that requests no tools ends the turn; leave room below it right away.
+            if (message.stopReason !== "toolUse")
+                this.gap();
+        }
+        if (transcript.streaming) {
+            this.streaming ??= this.add(new AssistantMessageComponent(undefined, false, getMarkdownTheme()));
+            this.streaming.updateContent(transcript.streaming, true);
+            this.toolCalls(transcript.streaming, transcript, false);
+        }
+        for (const [callId, partial] of transcript.running) {
+            const tool = this.tools.get(callId);
+            if (!tool || this.partials.get(callId) === partial)
+                continue;
+            this.partials.set(callId, partial);
+            tool.markExecutionStarted();
+            if (partial)
+                tool.updateResult({ ...partial, isError: false }, true);
+        }
+    }
+    toolCalls(message, transcript, complete) {
+        for (const block of message.content) {
+            if (block.type !== "toolCall")
+                continue;
+            let tool = this.tools.get(block.id);
+            if (!tool) {
+                tool = new ToolExecutionComponent(block.name, block.id, block.arguments, undefined, transcript.renderers.get(block.name), this.tui, transcript.cwd);
+                tool.setExpanded(this.expanded);
+                this.tools.set(block.id, tool);
+                this.add(tool);
+            }
+            else if (!complete)
+                tool.updateArgs(block.arguments);
+            if (complete) {
+                if (message.stopReason === "aborted" || message.stopReason === "error") {
+                    tool.updateResult({ content: [{ type: "text", text: message.errorMessage || "Error" }], isError: true });
+                }
+                else {
+                    tool.updateArgs(block.arguments);
+                    tool.setArgsComplete();
+                }
+            }
+        }
+    }
+    reset(transcript) {
+        this.transcript = transcript;
+        this.chat.clear();
+        this.tools.clear();
+        this.partials.clear();
+        this.streaming = undefined;
+        this.rendered = 0;
+        this.version = -1;
+        const intro = transcript.intro;
+        if (!intro)
+            return;
+        this.add(new UserMessageComponent(intro.prompt, getMarkdownTheme()));
+        this.add(new Text(this.theme.fg("dim", [
+            `goal: ${plain(intro.goal)}`,
+            `context: ${intro.predecessors} predecessor output${intro.predecessors === 1 ? "" : "s"} · workspace ${plain(intro.workspace)}`,
+        ].join("\n")), 1, 0));
+    }
+    /** One blank line between turns: after a finished reply, or before a new message. */
+    gap() {
+        const last = this.chat.children.at(-1);
+        if (last && !(last instanceof Spacer))
+            this.add(new Spacer(1));
+    }
+    add(component) {
+        this.chat.addChild(component);
+        return component;
+    }
+}

package/dist/shell-tools.js

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

package/dist/transcript.js

@@ -0,0 +1,114 @@
+/**
+ * Live worker conversations keyed by execution ID. Running executions and the
+ * newest finished ones are retained; older transcripts are dropped to bound memory.
+ */
+export class PiTranscripts {
+    onChange;
+    maxFinished;
+    transcripts = new Map();
+    finishedIds = [];
+    pending;
+    constructor(onChange = () => { }, maxFinished = 20) {
+        this.onChange = onChange;
+        this.maxFinished = maxFinished;
+    }
+    get(executionId) {
+        return this.transcripts.get(executionId);
+    }
+    start(executionId, nodeId, cwd, intro, renderers) {
+        this.transcripts.set(executionId, {
+            executionId, nodeId, cwd, intro, messages: [], running: new Map(), renderers, version: 0, finished: false,
+        });
+        this.changed();
+    }
+    streaming(executionId, partial) {
+        this.update(executionId, transcript => { transcript.streaming = partial; }, true);
+    }
+    assistant(executionId, message) {
+        this.update(executionId, transcript => {
+            delete transcript.streaming;
+            transcript.messages.push(message);
+        });
+    }
+    toolStart(executionId, callId) {
+        this.update(executionId, transcript => { transcript.running.set(callId, undefined); });
+    }
+    toolUpdate(executionId, callId, partial) {
+        this.update(executionId, transcript => {
+            if (transcript.running.has(callId))
+                transcript.running.set(callId, partial);
+        }, true);
+    }
+    toolResult(executionId, result) {
+        this.update(executionId, transcript => {
+            transcript.running.delete(result.toolCallId);
+            transcript.messages.push(result);
+        });
+    }
+    /** Record human messages: delivered before a model request, or left over when the execution ended. */
+    human(executionId, texts, delivered) {
+        if (!texts.length)
+            return;
+        this.update(executionId, transcript => {
+            for (const text of texts)
+                transcript.messages.push({ role: "human", text, timestamp: Date.now(), delivered });
+        });
+    }
+    /** Accepting messages: the execution's session has started and has not finished. */
+    isLive(executionId) {
+        const transcript = this.transcripts.get(executionId);
+        return transcript !== undefined && !transcript.finished;
+    }
+    /** Close interrupted streams and tools so the view does not show them as still running. */
+    finish(executionId, reason = "Execution ended before this step finished") {
+        if (executionId === undefined)
+            return;
+        this.update(executionId, transcript => {
+            if (transcript.streaming) {
+                transcript.messages.push({ ...transcript.streaming, stopReason: "aborted", errorMessage: reason });
+                delete transcript.streaming;
+            }
+            for (const callId of transcript.running.keys()) {
+                const call = transcript.messages.flatMap(message => message.role === "assistant" ? message.content : [])
+                    .find(block => block.type === "toolCall" && block.id === callId);
+                transcript.messages.push({
+                    role: "toolResult", toolCallId: callId, toolName: call?.type === "toolCall" ? call.name : "tool",
+                    content: [{ type: "text", text: reason }], isError: true, timestamp: Date.now(),
+                });
+            }
+            transcript.running.clear();
+            transcript.finished = true;
+            if (!this.finishedIds.includes(executionId))
+                this.finishedIds.push(executionId);
+            while (this.finishedIds.length > this.maxFinished)
+                this.transcripts.delete(this.finishedIds.shift());
+        });
+    }
+    /** Token and output bursts coalesce into at most one notification per 100 ms. */
+    update(executionId, change, burst = false) {
+        const transcript = this.transcripts.get(executionId);
+        if (!transcript || transcript.finished)
+            return;
+        try {
+            change(transcript);
+            transcript.version++;
+        }
+        catch {
+            // Display state must never affect node execution.
+        }
+        if (!burst)
+            this.changed();
+        else if (!this.pending) {
+            this.pending = setTimeout(() => this.changed(), 100);
+            this.pending.unref?.();
+        }
+    }
+    changed() {
+        clearTimeout(this.pending);
+        this.pending = undefined;
+        try {
+            this.onChange();
+        }
+        catch { /* Observers cannot fail a worker. */ }
+    }
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "license": "MIT",
   "description": "Pi extension for Braid: background agent graphs, bounded loops, live updates, and a flow panel",
   "type": "module",
   "dependencies": {
     "grok-mermaid": "^0.2.2",
-    "@chrok/braid": "0.3.2"
+    "@chrok/braid": "0.3.4"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",