@chrok/pi-braid 0.3.3 → 0.3.5

package/dist/status-text.js

@@ -0,0 +1,179 @@
+/** Model-facing text documents for the parent Braid tools. */
+const iso = (ms) => new Date(ms).toISOString();
+const duration = (ms) => ms < 1000 ? `${Math.max(0, Math.round(ms))}ms` : ms < 60_000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1000)}s`;
+const failure = (error) => `${error.code}: ${error.message}`;
+const ids = (values) => values?.length ? values.join(", ") : "none";
+const GOAL_CHARS = 2000;
+const clip = (text, limit) => text.length > limit ? `${text.slice(0, limit)}… [${text.length} chars]` : text;
+const indent = (text) => text.split("\n").map(line => line ? `  ${line}` : line).join("\n");
+export function formatUsage(usage) {
+    if (!usage)
+        return undefined;
+    const parts = [`input ${usage.input}`, `output ${usage.output}`];
+    if (usage.cacheRead)
+        parts.push(`cache read ${usage.cacheRead}`);
+    if (usage.cacheWrite)
+        parts.push(`cache write ${usage.cacheWrite}`);
+    const cost = usage.cost?.total ? `, $${usage.cost.total.toFixed(4)}` : "";
+    return `${parts.join(", ")} (${usage.totalTokens} tokens${cost})`;
+}
+function nodeLine(node) {
+    const settings = [node.type];
+    if ("workspace" in node && node.workspace)
+        settings.push(`workspace=${node.workspace}`);
+    if ("choices" in node)
+        settings.push(`choices=${node.choices.join("|")}`);
+    if (node.model)
+        settings.push(`model=${node.model}`);
+    if (typeof node.prompt === "object")
+        settings.push(`template=${node.prompt.template}`);
+    for (const flag of ["pauseAfter", "notifyOnCompletion", "requireSuccess"])
+        if (node[flag])
+            settings.push(flag);
+    return `- ${node.id}: ${settings.join(", ")}`;
+}
+/** Accepted definitions without prompts, which the caller already sent. */
+export function formatGraph(graph) {
+    const lines = ["Nodes:", ...graph.nodes.map(nodeLine), "Edges:"];
+    lines.push(...graph.edges.length ? graph.edges.map(edge => {
+        const labels = [edge.choice && `choice=${edge.choice}`, edge.feedback && `feedback=${edge.feedback}`, edge.executionId && `execution=${edge.executionId}`].filter(Boolean);
+        return `- ${edge.from} -> ${edge.to}${labels.length ? ` [${labels.join(", ")}]` : ""}`;
+    }) : ["- none"]);
+    if (graph.loops?.length)
+        lines.push("Loops:", ...graph.loops.map(loop => `- ${loop.id}: entry ${loop.entry}, at most ${loop.maxIterations} iterations`));
+    return lines.join("\n");
+}
+function workspaceLine(workspace) {
+    const parts = [`${workspace.mode} ${workspace.workingDirectory}`, workspace.state];
+    for (const root of [workspace.worktreeRoot, workspace.sourceRoot])
+        if (root && root !== workspace.workingDirectory)
+            parts.push(`root ${root}`);
+    if (workspace.checkpointRef)
+        parts.push(`checkpoint ${workspace.checkpointRef}`);
+    if (workspace.backupRef)
+        parts.push(`backup ${workspace.backupRef}`);
+    if (workspace.reason)
+        parts.push(workspace.reason);
+    for (const item of workspace.dispositions ?? [])
+        parts.push(`${item.executionId} ${item.disposition}: ${item.reason}`);
+    return parts.join(" · ");
+}
+function executionLine(execution) {
+    const parts = [execution.executionId ?? "(no execution)", `node ${execution.id}`];
+    if (execution.iteration)
+        parts.push(`iteration ${execution.iteration}`);
+    parts.push(execution.skipReason ? `${execution.status} (${execution.skipReason})` : execution.status);
+    if (execution.latencyMs !== undefined)
+        parts.push(duration(execution.latencyMs));
+    if (execution.decision)
+        parts.push(`decision ${execution.decision}`);
+    if (execution.error)
+        parts.push(failure(execution.error));
+    return `- ${parts.join(" · ")}`;
+}
+export function formatJobList(jobs) {
+    if (!jobs.length)
+        return "No Braid jobs in this session.";
+    return [`${jobs.length} Braid job${jobs.length === 1 ? "" : "s"} in this session, newest first:`,
+        ...jobs.map(job => `- ${job.handle} · ${job.status} · started ${iso(job.createdAt)} · id ${job.jobId}\n  Goal: ${job.goal}`)].join("\n");
+}
+function control(execution) {
+    return execution ? `Graph ${execution.status} · revision ${execution.revision} · paused executions: ${ids(execution.pausedExecutionIds)}` : "Graph not started";
+}
+/** The submission receipt. The caller already has the graph it submitted. */
+export function formatReceipt(job, message) {
+    return [`Braid job ${job.handle} started (${job.status}).`, `ID: ${job.jobId}`, message].join("\n");
+}
+export function formatUpdate(job) {
+    return [`Braid job ${job.handle} updated to revision ${job.execution.revision}.`,
+        `Paused executions: ${ids(job.execution.pausedExecutionIds)}`, "Current graph:", formatGraph(job.execution.graph)].join("\n");
+}
+export function formatResume(job) {
+    return `Braid job ${job.handle} resumed at revision ${job.execution.revision}. Still paused: ${ids(job.execution.pausedExecutionIds)}.`;
+}
+export function formatActivity(activity, now, jobId) {
+    const lines = [`Activity: ${activity.phase} for ${duration(now - activity.phaseStartedAt)}; last observed signal ${duration(now - activity.lastActivityAt)} ago (${activity.lastActivity}). Model requests ${activity.modelRequests}, tool calls ${activity.toolCalls}.`];
+    const model = activity.model;
+    if (model && model.completedAt === undefined) {
+        const stream = model.firstStreamAt === undefined ? "no stream received yet"
+            : `receiving ${model.receiving ?? "output"}${model.toolName ? ` for ${model.toolName}` : ""}, ${model.receivedChars} chars, last chunk ${duration(now - (model.lastStreamAt ?? model.firstStreamAt))} ago`;
+        lines.push(`Model request ${model.round}: started ${duration(now - model.startedAt)} ago; ${stream}.`);
+    }
+    for (const tool of activity.tools) {
+        lines.push(`Running tool ${tool.name} for ${duration(now - tool.startedAt)}: ${tool.arguments}`);
+        if (tool.outputTail)
+            lines.push(indent(`Output tail:\n${tool.outputTail}`));
+    }
+    for (const limitation of activity.limitations)
+        lines.push(`Not observable: ${limitation}`);
+    if (activity.entries.length) {
+        lines.push("History:");
+        for (const entry of activity.entries) {
+            lines.push(`- #${entry.sequence} ${iso(entry.timestamp)} ${entry.kind}${entry.toolName ? ` ${entry.toolName}` : ""}${entry.isError ? " (error)" : ""}${entry.durationMs !== undefined ? ` ${duration(entry.durationMs)}` : ""}: ${entry.summary}`);
+            if (entry.detail)
+                lines.push(indent(entry.detail + (entry.detailLength ? `\n[preview of ${entry.detailLength} chars]` : "")));
+        }
+        const first = activity.entries[0].sequence;
+        if (first > 1)
+            lines.push(first - 1 > activity.droppedEntries
+                ? `Earlier entries: braid_status({"jobId":"${jobId}","executionId":"${activity.executionId}","activityBefore":${first}})`
+                : `${activity.droppedEntries} earlier entries are no longer retained.`);
+    }
+    return lines.join("\n");
+}
+/** A focused read: the current control state, then one execution in full. */
+export function formatNodeStatus({ job, node, activity, now }) {
+    const lines = [`Braid job ${job.handle} · ${job.status} · ${control(job.execution)}`,
+        `Execution ${node.executionId ?? "(none yet)"} · node ${node.id}${node.node ? ` (${node.node.type})` : ""}${node.iteration ? ` · iteration ${node.iteration}` : ""} · ${node.skipReason ? `${node.status} (${node.skipReason})` : node.status}`];
+    const timing = [node.startedAt !== undefined && `started ${iso(node.startedAt)}`, node.latencyMs !== undefined && `took ${duration(node.latencyMs)}`,
+        node.model && `model ${node.model}`, node.usage && `usage input ${node.usage.inputTokens}, output ${node.usage.outputTokens}`].filter(Boolean);
+    if (timing.length)
+        lines.push(timing.join(" · "));
+    if (node.decision)
+        lines.push(`Decision: ${node.decision}`);
+    if (node.error)
+        lines.push(`Error: ${failure(node.error)}`);
+    if (node.workspace)
+        lines.push(`Workspace: ${workspaceLine(node.workspace)}`);
+    if (node.humanInputs?.length)
+        lines.push("Human input delivered during this execution:", ...node.humanInputs.map(input => `- ${iso(input.timestamp)}: ${input.text}`));
+    const output = `Output:\n${node.output ?? "(none)"}`;
+    // While running, activity is the useful part; afterwards the output is.
+    const running = activity && activity.finishedAt === undefined;
+    const sections = [lines.join("\n"), ...running ? [formatActivity(activity, now, job.handle), output] : [output, ...activity ? [formatActivity(activity, now, job.handle)] : []]];
+    return sections.join("\n\n");
+}
+/** The whole job: control state, every execution, then their outputs and the current definition. */
+export function formatJobStatus(job, now) {
+    const state = job.result ?? job.execution;
+    // Control fields lead: a long goal or output must not push them out of a truncated preview.
+    const header = [`Braid job ${job.handle} · ${job.status}`, `ID: ${job.jobId}`, control(job.execution)];
+    const error = job.error ?? (job.result?.error ? failure(job.result.error) : job.execution?.error ? failure(job.execution.error) : undefined);
+    if (error)
+        header.push(`Error: ${error}`);
+    const usage = formatUsage(job.usage);
+    if (usage)
+        header.push(`Usage: ${usage}`);
+    if (job.result)
+        header.push(`Finished ${iso(job.result.metadata.finishedAt)} after ${duration(job.result.metadata.latencyMs)}`);
+    else
+        header.push(`Started ${iso(job.createdAt)}, ${duration(now - job.createdAt)} ago`);
+    header.push(`Goal: ${clip(job.goal, GOAL_CHARS)}`);
+    const sections = [header.join("\n")];
+    const executions = Object.values(state?.executions ?? {});
+    if (executions.length)
+        sections.push([`Executions (${executions.length}):`, ...executions.map(executionLine)].join("\n"));
+    const pending = Object.values(state?.nodes ?? {}).filter(node => !node.executionId);
+    if (pending.length)
+        sections.push(["Nodes without executions:", ...pending.map(executionLine)].join("\n"));
+    const terminal = new Set(job.result?.terminalExecutionIds ?? []);
+    const outputs = executions.filter(execution => execution.output !== undefined);
+    if (outputs.length)
+        sections.push(["Outputs:", ...outputs.map(execution => `## ${execution.id} · ${execution.executionId}${terminal.has(execution.executionId) ? " · terminal" : ""}${execution.decision ? ` · decision ${execution.decision}` : ""}\n${execution.output}`)].join("\n\n"));
+    const workspaces = executions.filter(execution => execution.workspace);
+    if (workspaces.length)
+        sections.push(["Workspaces:", ...workspaces.map(execution => `- ${execution.executionId}: ${workspaceLine(execution.workspace)}`)].join("\n"));
+    if (job.execution)
+        sections.push(`Current graph (revision ${job.execution.revision}):\n${formatGraph(job.execution.graph)}`);
+    return sections.join("\n\n");
+}

package/dist/transcript.js

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

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "license": "MIT",
   "description": "Pi extension for Braid: background agent graphs, bounded loops, live updates, and a flow panel",
   "type": "module",
   "dependencies": {
     "grok-mermaid": "^0.2.2",
-    "@chrok/braid": "0.3.3"
+    "@chrok/braid": "0.3.5"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -14,9 +14,9 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "1.0.1",
-    "@earendil-works/pi-tui": "1.0.1",
-    "@earendil-works/pi-coding-agent": "1.0.1",
+    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
     "typescript": "^5.0.0",
     "tsx": "^4.0.0",
     "@types/node": "^22.0.0"