@chrok/pi-braid 0.1.0

package/dist/integrations/pi/display.js

@@ -0,0 +1,417 @@
+import { render as renderMermaid } from "grok-mermaid";
+import { Text, stripTerminalSequences, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+export const MAX_VISIBLE_EVENTS = 80;
+export const MAX_VISIBLE_NODES = 80;
+class FixedLines {
+    lines;
+    chartStart;
+    chartLength;
+    constructor(lines, chartStart = lines.length, chartLength = 0) {
+        this.lines = lines;
+        this.chartStart = chartStart;
+        this.chartLength = chartLength;
+    }
+    render(width) {
+        const chart = this.lines.slice(this.chartStart, this.chartStart + this.chartLength);
+        if (chart.length === 0)
+            return this.lines.map((line) => truncateToWidth(line, width, ""));
+        const chartWidth = Math.max(...chart.map((line) => visibleWidth(line)));
+        const chartOutput = chartWidth <= width
+            ? chart
+            : [
+                `[Flowchart needs ${chartWidth} columns; terminal width is ${width}. Expand your terminal to see it.]`,
+            ];
+        const output = [];
+        let chartInserted = false;
+        for (let index = 0; index < this.lines.length; index++) {
+            if (index === this.chartStart) {
+                output.push(...chartOutput);
+                chartInserted = true;
+            }
+            if (index < this.chartStart ||
+                index >= this.chartStart + this.chartLength) {
+                output.push(truncateToWidth(this.lines[index], width, ""));
+            }
+        }
+        if (!chartInserted)
+            output.push(...chartOutput);
+        return output;
+    }
+    invalidate() { }
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function compact(value, max = 90) {
+    if (typeof value !== "string")
+        return "…";
+    // Node IDs and model output are untrusted terminal content, not ANSI markup.
+    const line = stripTerminalSequences(value)
+        .replace(/\p{Cc}|\s+/gu, " ")
+        .trim();
+    return line.length <= max ? line : `${line.slice(0, max - 1)}…`;
+}
+function graphParts(result) {
+    if ("nodeTypes" in result)
+        return result;
+    const nodes = Object.assign(Object.create(null), result.nodes);
+    const nodeTypes = Object.create(null);
+    const edges = [];
+    for (const event of result.events) {
+        if (event.type === "node_created") {
+            nodes[event.nodeId] ??= { id: event.nodeId, status: "pending" };
+            if (event.model !== undefined &&
+                nodes[event.nodeId].model === undefined) {
+                nodes[event.nodeId].model = event.model;
+            }
+            Object.defineProperty(nodeTypes, event.nodeId, {
+                value: event.nodeType,
+                enumerable: true,
+                configurable: true,
+            });
+        }
+        else if (event.type === "edge_created") {
+            edges.push({
+                from: event.from,
+                to: event.to,
+                ...(event.choice ? { choice: event.choice } : {}),
+            });
+        }
+    }
+    const progress = "progress" in result &&
+        result.progress !== undefined &&
+        typeof result.progress === "object"
+        ? result.progress
+        : Object.create(null);
+    return { nodes, nodeTypes, edges, progress };
+}
+function compactCount(value) {
+    if (value >= 1_000_000)
+        return `${(value / 1_000_000).toFixed(value % 1_000_000 === 0 ? 0 : 1)}M`;
+    if (value >= 1_000)
+        return `${Math.round(value / 1_000)}K`;
+    return String(value);
+}
+function elapsed(ms) {
+    if (ms === undefined)
+        return "—";
+    if (ms < 1000)
+        return `${(ms / 1000).toFixed(2)}s`;
+    if (ms < 60_000)
+        return `${Math.floor(ms / 1000)}s`;
+    return `${Math.floor(ms / 60_000)}m${Math.floor((ms % 60_000) / 1000)}s`;
+}
+function nodeElapsed(node, now) {
+    if (node.latencyMs !== undefined)
+        return elapsed(node.latencyMs);
+    if (node.status === "running" && node.startedAt !== undefined) {
+        return elapsed(Math.max(0, now - node.startedAt));
+    }
+    return "—";
+}
+function mermaidLabelLines(id, result) {
+    const progress = "progress" in result ? result.progress?.[id] : undefined;
+    const node = result.nodes[id];
+    if (!node)
+        return [compact(id, 24), "pending"];
+    const icon = node.status === "running"
+        ? "▶ ACTIVE"
+        : {
+            completed: "✓",
+            failed: "✗",
+            skipped: "·",
+            runnable: "◇",
+            pending: "○",
+        }[node.status];
+    const status = node.status === "completed" ? "done" : node.status;
+    const decision = node.decision === undefined ? "" : ` → ${compact(node.decision, 16)}`;
+    const now = "observedAt" in result ? result.observedAt : Date.now();
+    const lines = [
+        `${icon} ${compact(id, 24)}`,
+        `${status}${decision} · ${nodeElapsed(node, now)}`,
+    ];
+    if (progress) {
+        const window = progress.contextWindow === undefined
+            ? "—"
+            : compactCount(progress.contextWindow);
+        const prefix = progress.contextSource === "estimate" ? "~" : "";
+        lines.push(`${prefix}${compactCount(progress.contextTokens)}/${window} · T${progress.toolCalls}`);
+    }
+    return lines;
+}
+function mermaidSource(result) {
+    const parts = graphParts(result);
+    const ids = Object.keys(parts.nodes);
+    const names = new Map(ids.map((id, index) => [id, `n${index}`]));
+    const escapeMermaidText = (value) => stripTerminalSequences(value)
+        .replace(/\p{Cc}/gu, "")
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/\|/g, "&#124;")
+        .replace(/[[\]{}<>]/g, (character) => ({
+        "[": "&#91;",
+        "]": "&#93;",
+        "{": "&#123;",
+        "}": "&#125;",
+        "<": "&lt;",
+        ">": "&gt;",
+    })[character] ?? character);
+    const lines = ["flowchart TD"];
+    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}`);
+    }
+    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));
+    if (!art)
+        return [];
+    return art.styled.map((row) => row
+        .map((span) => {
+        switch (span.cls) {
+            case "border":
+                return theme.fg("borderMuted", span.text);
+            case "text":
+                return span.text.includes("▶ ACTIVE")
+                    ? theme.bg("selectedBg", theme.bold(theme.fg("accent", span.text)))
+                    : theme.fg("text", span.text);
+            case "edge":
+                return theme.fg("accent", span.text);
+            case "edgeLabel":
+                return theme.fg("muted", span.text);
+            case "title":
+                return theme.fg("accent", theme.bold(span.text));
+            default:
+                return span.text;
+        }
+    })
+        .join(""));
+}
+export function renderGraphCall(args, theme) {
+    // Pi renders partially streamed tool arguments, including incomplete array items.
+    const partial = record(args) ? args : {};
+    const nodes = Array.isArray(partial.nodes)
+        ? partial.nodes.filter(record)
+        : [];
+    const edges = Array.isArray(partial.edges)
+        ? partial.edges.filter(record)
+        : [];
+    const options = record(partial.options) ? partial.options : {};
+    const decisions = nodes.filter((node) => node.type === "decision").length;
+    const route = edges
+        .slice(0, 5)
+        .map((edge) => `${compact(edge.from, 30)}${edge.choice ? ` -${compact(edge.choice, 20)}->` : " →"} ${compact(edge.to, 30)}`)
+        .join("  ");
+    const nodeLabels = nodes
+        .slice(0, 8)
+        .map((node) => `${node.type === "decision" ? "◇" : "○"} ${compact(node.id, 30)}`);
+    return new FixedLines([
+        theme.fg("toolTitle", "◆ Braid"),
+        theme.fg("muted", `${nodes.length} nodes (${decisions} decision) · ${edges.length} edges · max ${options.maxConcurrency ?? 4}`),
+        theme.fg("dim", `goal: ${compact(partial.goal)}`),
+        theme.fg("accent", `nodes: ${nodeLabels.join("  ")}${nodes.length > 8 ? `  +${nodes.length - 8} more` : ""}`),
+        theme.fg("dim", route
+            ? `graph: ${route}${edges.length > 5 ? `  +${edges.length - 5} more` : ""}`
+            : "graph: no edges yet"),
+    ]);
+}
+function eventText(event) {
+    switch (event.type) {
+        case "graph_created":
+            return `graph created · ${event.nodeCount} nodes · ${event.edgeCount} edges`;
+        case "node_created":
+            return `node created · ${compact(event.nodeId, 40)} (${event.nodeType})${event.model ? ` · ${compact(event.model, 50)}` : ""}`;
+        case "edge_created":
+            return `edge created · ${compact(event.from, 40)}${event.choice ? ` -${compact(event.choice, 30)}->` : " →"} ${compact(event.to, 40)}`;
+        case "workspace_updated":
+            return `workspace · ${compact(event.workspace.nodeId, 40)} · ${event.workspace.state}`;
+        case "node_runnable":
+            return `runnable · ${compact(event.nodeId, 40)}`;
+        case "handoff":
+            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 "node_completed":
+            return `completed · ${compact(event.nodeId, 40)}${event.decision ? ` → ${compact(event.decision, 30)}` : ""}: ${compact(event.output, 64)}`;
+        case "node_skipped":
+            return `skipped · ${compact(event.nodeId, 40)} (${event.reason})`;
+        case "node_failed":
+            return `failed · ${compact(event.nodeId, 40)} (${event.error.code}): ${compact(event.error.message, 64)}`;
+        case "graph_completed":
+            return `graph completed · terminals: ${compact(event.terminalNodeIds.join(", "), 80) || "none"}`;
+        case "graph_failed":
+            return `graph failed · ${event.error.code}: ${compact(event.error.message, 80)}`;
+    }
+}
+function renderEventLog(events, expanded, theme) {
+    if (!events.length)
+        return [];
+    const visible = events.slice(-(expanded ? MAX_VISIBLE_EVENTS : 8));
+    const total = events.at(-1).sequence;
+    const lines = [theme.fg("dim", `execution log · ${total} events:`)];
+    if (visible[0].sequence > 1) {
+        lines.push(theme.fg("dim", `  … ${visible[0].sequence - 1} earlier events${expanded ? " (see full result)" : " (expand for more)"}`));
+    }
+    for (const event of visible) {
+        const color = event.type.endsWith("failed")
+            ? "error"
+            : event.type.endsWith("completed")
+                ? "success"
+                : event.type === "node_started"
+                    ? "accent"
+                    : "dim";
+        lines.push(theme.fg(color, `  ${String(event.sequence).padStart(3, "0")} ${eventText(event)}`));
+    }
+    return lines;
+}
+export function createLiveState() {
+    return {
+        status: "running",
+        nodes: Object.create(null),
+        nodeTypes: Object.create(null),
+        edges: [],
+        progress: Object.create(null),
+        events: [],
+        latencyMs: 0,
+        observedAt: Date.now(),
+    };
+}
+export function applyEvent(state, event) {
+    // Keep per-update payloads bounded, without discarding any events from the core result.
+    const preview = { ...event };
+    if ("output" in preview && preview.output !== undefined)
+        preview.output = compact(preview.output, 180);
+    if ("error" in preview)
+        preview.error = {
+            ...preview.error,
+            message: compact(preview.error.message, 180),
+        };
+    state.events.push(preview);
+    if (event.type === "node_created")
+        Object.defineProperty(state.nodeTypes, event.nodeId, {
+            value: event.nodeType,
+            enumerable: true,
+            configurable: true,
+        });
+    if (event.type === "edge_created")
+        state.edges.push({
+            from: event.from,
+            to: event.to,
+            ...(event.choice ? { choice: event.choice } : {}),
+        });
+    if (state.events.length > MAX_VISIBLE_EVENTS)
+        state.events.shift();
+    if (event.type === "node_created") {
+        Object.defineProperty(state.nodes, event.nodeId, {
+            value: {
+                id: event.nodeId,
+                status: "pending",
+                ...(event.model ? { model: event.model } : {}),
+            },
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+        return;
+    }
+    const node = "nodeId" in event && Object.hasOwn(state.nodes, event.nodeId)
+        ? state.nodes[event.nodeId]
+        : undefined;
+    if (!node)
+        return;
+    switch (event.type) {
+        case "node_runnable":
+            node.status = "runnable";
+            break;
+        case "node_started":
+            node.status = "running";
+            node.startedAt = event.timestamp;
+            break;
+        case "node_completed":
+        case "node_failed":
+            node.status = event.type === "node_completed" ? "completed" : "failed";
+            node.finishedAt = event.timestamp;
+            node.latencyMs = event.latencyMs;
+            if (event.output !== undefined)
+                node.output = compact(event.output, 180);
+            if (event.decision !== undefined)
+                node.decision = event.decision;
+            if (event.model !== undefined)
+                node.model = event.model;
+            if (event.usage !== undefined)
+                node.usage = { ...event.usage };
+            if (event.type === "node_failed")
+                node.error = {
+                    ...event.error,
+                    message: compact(event.error.message, 180),
+                };
+            break;
+        case "node_skipped":
+            node.status = "skipped";
+            node.skipReason = event.reason;
+            node.finishedAt = event.timestamp;
+            break;
+    }
+}
+export function applyProgress(state, progress) {
+    Object.defineProperty(state.progress, progress.nodeId, {
+        value: progress,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+    });
+}
+export function renderGraphResult(result, expanded, isPartial, theme, fallback = "", isError = false) {
+    if (isError || !result?.nodes) {
+        const message = fallback ||
+            (isPartial ? "Braid is running…" : "Braid returned no execution details");
+        return new Text(theme.fg(isError ? "error" : "warning", compact(message, 500)), 0, 0);
+    }
+    const nodes = Object.values(result.nodes);
+    const completed = nodes.filter((node) => node.status === "completed").length;
+    const skipped = nodes.filter((node) => node.status === "skipped").length;
+    const failed = nodes.filter((node) => node.status === "failed").length;
+    const active = nodes.filter((node) => node.status === "running").length;
+    const pending = nodes.filter((node) => node.status === "pending" || node.status === "runnable").length;
+    const elapsedMs = "metadata" in result ? result.metadata.latencyMs : result.latencyMs;
+    const title = result.status === "running"
+        ? theme.fg("warning", "⟳ Braid executing")
+        : result.status === "completed"
+            ? theme.fg("success", "✓ Braid completed")
+            : theme.fg("error", "✗ Braid failed");
+    const lines = [
+        title,
+        theme.fg("muted", `${completed}/${nodes.length} completed · ${result.status === "running" ? `${active} active · ${pending} pending · ` : ""}${skipped} skipped · ${failed} failed · ${elapsed(elapsedMs)}`),
+    ];
+    if ("terminalOutputs" in result) {
+        const terminals = Object.keys(result.terminalOutputs);
+        if (terminals.length)
+            lines.push(theme.fg("accent", `terminals: ${compact(terminals.join(", "), 120)}`));
+        if (result.error)
+            lines.push(theme.fg("error", `${result.error.code}: ${compact(result.error.message, 120)}`));
+    }
+    const chartStart = lines.length;
+    const chart = mermaidLines(result, theme);
+    lines.push(...chart);
+    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;
+        lines.push(theme.fg("accent", `workspaces: ${active} active · ${workspaces.length - active} cleaned${expanded ? "" : " (expand for recovery refs)"}`));
+        if (expanded) {
+            for (const workspace of workspaces.slice(0, MAX_VISIBLE_NODES)) {
+                const active = ["preparing", "ready", "failed"].includes(workspace.state);
+                lines.push(theme.fg("dim", `  ${compact(workspace.nodeId, 40)} · ${workspace.state}: ${compact(active ? workspace.worktreeRoot : workspace.checkpointRef ?? workspace.reason, 240)}`));
+            }
+        }
+    }
+    if (expanded)
+        lines.push(...renderEventLog(result.events ?? [], true, theme));
+    if ("fullOutputPath" in result && result.fullOutputPath)
+        lines.push(theme.fg("dim", `full result/log: ${compact(result.fullOutputPath, 240)}`));
+    return new FixedLines(lines, chartStart, chart.length);
+}

package/dist/integrations/pi/index.js

@@ -0,0 +1,232 @@
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { defineTool, truncateHead, } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { BraidJobs } from "./jobs.js";
+import { registerBraidCommand } from "./command.js";
+import { renderGraphCall, renderGraphResult } from "./display.js";
+const text = () => Type.String({ minLength: 1 });
+const timeout = () => Type.Optional(Type.Number({
+    exclusiveMinimum: 0,
+    maximum: 2_147_483_647,
+    description: "Timeout in milliseconds; omit for no time limit",
+}));
+const toolBudget = (unit) => Type.Optional(Type.Integer({
+    minimum: 1,
+    maximum: Number.MAX_SAFE_INTEGER,
+    description: `Maximum tool ${unit} per node, including decide and rejected requests; omit for no limit`,
+}));
+const braidParameters = Type.Object({
+    goal: text(),
+    // A flat object avoids provider-specific discriminated-union schema problems.
+    nodes: Type.Array(Type.Object({
+        type: StringEnum(["execute", "decision", "merge"]),
+        id: text(),
+        prompt: Type.Optional(text()),
+        model: Type.Optional(Type.String({
+            description: "Exact provider/modelId; default is the current Pi model",
+        })),
+        choices: Type.Optional(Type.Array(text(), {
+            minItems: 1,
+            description: "Required on decision nodes; forbidden on execute nodes",
+        })),
+    }, { additionalProperties: false }), { minItems: 1 }),
+    edges: Type.Array(Type.Object({
+        from: text(),
+        to: text(),
+        choice: Type.Optional(text()),
+    }, { additionalProperties: false })),
+    options: Type.Optional(Type.Object({
+        maxConcurrency: Type.Optional(Type.Integer({ minimum: 1 })),
+        nodeTimeoutMs: timeout(),
+        graphTimeoutMs: timeout(),
+        maxToolRounds: toolBudget("rounds"),
+        maxToolCalls: toolBudget("calls"),
+    }, { additionalProperties: false })),
+}, { additionalProperties: false });
+const BRAID_FILESYSTEM_GUIDANCE = "In a Git repository, execute and decision nodes get individual writable worktrees with read, ls, write, edit, and Git inspection. Search tools grep/find are exposed only when their local rg/fd dependencies are available. " +
+    "Worktrees include tracked changes and non-ignored untracked files. Merge nodes operate in the source checkout and decide whether to merge, cherry-pick, apply, or discard predecessor changes; core never makes that choice. " +
+    "Merge agents must call finish_merge for every source; core checkpoints changes and removes processed worktrees. Core appends a final merge agent for remaining worktrees. Failed predecessors pass their errors and partial work along unconditional edges. " +
+    "Outside Git, nodes have read and ls, plus grep/find when their local dependencies are available. Shell commands and tests remain unavailable in all nodes. " +
+    "Inspect braid_status for integration outcomes and recovery checkpoint refs, then run tests in the parent. Avoid concurrent parent edits while a merge agent owns the source checkout.";
+const BRAID_USAGE_GUIDANCE = [
+    "Braid is a proactive execution primitive, not only a user-requested command.",
+    "Selection rule: for a code review, bug investigation, design comparison, test-planning request, or change spanning multiple files, call braid FIRST when two or more concerns can be analyzed independently. Do this without waiting for the user to say Braid; do not read everything in the parent and then decide whether to delegate.",
+    BRAID_FILESYSTEM_GUIDANCE,
+    "When Braid fits, construct and submit the complete DAG in one call: use parallel execute nodes for independent concerns and a final execute node to synthesize their outputs. The tool returns a jobId immediately. Continue independent work or finish your turn while it runs; do not poll repeatedly. A completion reminder will resume you. Use braid_status with the jobId to retrieve terminal outputs before relying on them.",
+    "Do not use braid for a simple one-step answer, a trivial direct edit, shell work, or when decomposition adds no value. The parent reviews results, runs tests, and executes shell commands after Braid completes.",
+].join("\n");
+export function createBraidTools(jobs) {
+    const braidTool = defineTool({
+        name: "braid",
+        label: "Braid",
+        description: "Use this tool FIRST for nontrivial engineering work: code reviews, bug investigations, design comparisons, test planning, and changes spanning multiple files. " +
+            "It starts a background job and immediately returns jobId for a complete DAG of isolated LLM invocations with parallel branches and joins; the user does not need to mention Braid. " +
+            "Use execute, decision, or merge nodes. Decision nodes must declare choices and call decide; matching choice edges activate together. Merge nodes accept multiple predecessors and an optional prompt. " +
+            "Unlabelled edges are unconditional. Joins wait for all possible predecessor paths to resolve. " +
+            "Nodes see only the goal, their prompt, labelled direct-predecessor outputs, and their filesystem capabilities: " +
+            "no parent history, shell, tests, or recursive Braid calls. " +
+            BRAID_FILESYSTEM_GUIDANCE + " " +
+            "Do not use it for a simple one-step answer or trivial direct edit. " +
+            "Use braid_status(jobId) for progress and results, or braid_cancel(jobId) to stop it. A completion reminder resumes the agent if idle; do independent work or end your turn instead of polling. Humans can open /braid for the live flow panel. " +
+            "Read result.status: failed graphs can still return successful terminal outputs.",
+        promptSnippet: "Use FIRST for nontrivial code review/debug/design work; parallelize independent analysis and synthesize",
+        promptGuidelines: [
+            "Call braid before direct repository inspection when a code task has two or more separable review, debugging, design, or test-planning concerns; the Braid nodes can inspect the project and edit isolated Git worktrees.",
+            "Use parallel execute nodes for independent concerns and a final synthesis node. The user does not need to mention Braid or design the graph.",
+            "Do not use braid for simple one-step answers or trivial direct edits. Keep shell commands and test execution in the parent; use merge nodes for integration.",
+            BRAID_FILESYSTEM_GUIDANCE,
+            "Decision nodes additionally receive decide. Nodes cannot call recursive Braid.",
+            "Tool and time budgets are unlimited by default. Set maxToolRounds, maxToolCalls, nodeTimeoutMs, or graphTimeoutMs in options to impose hard limits; nodes receive system reminders of their remaining budgets before each model call.",
+        ],
+        parameters: braidParameters,
+        renderCall(args, theme) {
+            return renderGraphCall(args, theme);
+        },
+        renderResult(result, _options, theme) {
+            const job = result.details;
+            return new Text(theme.fg(job ? "accent" : "error", job
+                ? `Braid background job ${job.jobId} · ${job.status} · /braid to view`
+                : result.content
+                    .filter((item) => item.type === "text")
+                    .map((item) => item.text)
+                    .join("\n")), 0, 0);
+        },
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            signal?.throwIfAborted();
+            try {
+                const job = jobs.start({
+                    goal: params.goal,
+                    nodes: params.nodes,
+                    edges: params.edges,
+                }, params.options ?? {}, ctx);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                jobId: job.handle,
+                                canonicalJobId: job.jobId,
+                                status: job.status,
+                                message: "Running in background. Use braid_status to retrieve progress/results. A completion reminder will resume you; do not poll repeatedly.",
+                            }),
+                        },
+                    ],
+                    details: job,
+                };
+            }
+            catch (error) {
+                throw new Error(`Braid submission failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    const statusParameters = Type.Object({ jobId: Type.Optional(text()) }, { 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. Prefer the short handle from submission/reminders. Omit jobId to list jobs in this session. Completion reminders arrive automatically; avoid repeated polling.",
+        parameters: statusParameters,
+        renderResult(result, options, theme) {
+            const job = result.details;
+            const fallback = result.content
+                .filter((item) => item.type === "text")
+                .map((item) => item.text)
+                .join("\n");
+            if (!job)
+                return new Text(fallback, 0, 0);
+            if (job.error)
+                return new Text(theme.fg("error", `Braid ${job.status}: ${job.error}`), 0, 0);
+            return renderGraphResult({
+                ...(job.result ?? job.live),
+                progress: job.live.progress,
+                ...(job.workspaces ? { workspaces: job.workspaces } : {}),
+                ...(job.fullOutputPath ? { fullOutputPath: job.fullOutputPath } : {}),
+            }, options.expanded, options.isPartial, theme, fallback);
+        },
+        async execute(_id, params) {
+            if (!params.jobId)
+                return {
+                    content: [{ type: "text", text: JSON.stringify(jobs.list()) }],
+                    details: undefined,
+                };
+            const job = jobs.get(params.jobId);
+            if (!job)
+                throw jobs.unknownJob(params.jobId);
+            const preview = truncateHead(JSON.stringify(job, null, 2));
+            const suffix = preview.truncated
+                ? `\n[Preview truncated. ${job.fullOutputPath ? `Full result/log: ${job.fullOutputPath}` : "Full results will be available when the job finishes."}]`
+                : "";
+            const usage = jobs.claimUsage(job.jobId);
+            return {
+                content: [{ type: "text", text: preview.content + suffix }],
+                details: job,
+                ...(usage ? { usage } : {}),
+            };
+        },
+    });
+    const cancelParameters = Type.Object({ jobId: text() }, { additionalProperties: false });
+    const cancelTool = defineTool({
+        name: "braid_cancel",
+        label: "Cancel Braid",
+        description: "Cancel a background Braid job by jobId. Stopping the foreground response does not cancel background jobs.",
+        parameters: cancelParameters,
+        async execute(_id, params) {
+            const cancelled = jobs.cancel(params.jobId);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: cancelled
+                            ? "Cancellation requested."
+                            : "Job has already finished.",
+                    },
+                ],
+                details: undefined,
+            };
+        },
+    });
+    return { braidTool, statusTool, cancelTool };
+}
+export default function braidExtension(pi) {
+    const pending = new Map();
+    const remind = (jobId, status) => {
+        const handle = jobs.get(jobId)?.handle ?? jobId;
+        pi.sendMessage({
+            customType: "braid-completed",
+            display: true,
+            content: `[system-reminder] Braid job ${handle} finished with status ${status}. Retrieve its results with braid_status({"jobId":"${handle}"}) and continue the original task. Failed or cancelled jobs may contain successful partial outputs. [/system-reminder]`,
+            details: { jobId, handle, status },
+        }, { triggerTurn: true, deliverAs: "followUp" });
+    };
+    const jobs = new BraidJobs((job) => {
+        pending.set(job.jobId, job.status);
+        remind(job.jobId, job.status);
+    });
+    // Foreground cancellation can discard queued follow-ups. Retry only reminders
+    // that never entered context, once Pi has settled and emptied its queues.
+    pi.on("message_start", (event) => {
+        const message = event.message;
+        if (message.role === "custom" && message.customType === "braid-completed") {
+            const details = message.details;
+            if (details?.jobId)
+                pending.delete(details.jobId);
+        }
+    });
+    pi.on("agent_settled", (_event, ctx) => {
+        if (ctx.isIdle() && !ctx.hasPendingMessages()) {
+            for (const [jobId, status] of pending)
+                remind(jobId, status);
+        }
+    });
+    const { braidTool, statusTool, cancelTool } = createBraidTools(jobs);
+    registerBraidCommand(pi, jobs);
+    pi.registerTool(braidTool);
+    pi.registerTool(statusTool);
+    pi.registerTool(cancelTool);
+    pi.on("session_shutdown", () => {
+        pending.clear();
+        jobs.dispose();
+    });
+    pi.on("before_agent_start", (event) => ({
+        systemPrompt: `${event.systemPrompt}\n\n## Braid execution policy\n${BRAID_USAGE_GUIDANCE}\n\nFor the current user request, make this delegation choice before using read, grep, find, edit, write, or bash. Completion reminders refer to existing jobs: retrieve their results instead of submitting the same graph again.`,
+    }));
+}