pi-async-bash 0.1.0

package/src/tools/jobs.ts

@@ -0,0 +1,365 @@
+/**
+ * `jobs` tool — manage background jobs.
+ *
+ * Actions:
+ *   - list: show all jobs (running + recently terminal)
+ *   - output: read a job's log tail (non-blocking peek)
+ *   - kill: terminate a job
+ *   - attach: follow a job's live output and wait for it to finish
+ *   - search: regex-search all job output
+ *   - cleanup: purge terminal jobs
+ *   - stats: aggregate metrics
+ */
+
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import type { BackgroundRegistry } from "../state.ts";
+import {
+    isTerminalStatus,
+    OUTPUT_PREVIEW_CHARS,
+    PREVIEW_CHARS,
+    type UiContext,
+} from "../types.ts";
+import { processExists } from "../spawn.ts";
+import {
+    cleanupTerminal,
+    findJob,
+    forget,
+    getStats,
+    readLogTail,
+    renderSidebar,
+} from "../registry.ts";
+import { formatDuration, formatJobLine, jobLabel, oneLine, textBlock } from "../format.ts";
+import { streamLog } from "../output.ts";
+import { searchLogs } from "../log-search.ts";
+import { markNotified } from "../notify.ts";
+import {
+    ensureCompletionPromise,
+    markTerminal,
+    terminateJobSilently,
+} from "../lifecycle.ts";
+
+/** Register the `jobs` tool. */
+export function registerJobsTool(
+    pi: ExtensionAPI,
+    reg: BackgroundRegistry
+): void {
+    pi.registerTool({
+        name: "bash_async_list",
+        label: "Background Jobs",
+        description:
+            "Manage background jobs: list, output, kill, attach, search, cleanup, and stats.",
+        promptSnippet: "Inspect and manage background jobs",
+        promptGuidelines: [
+            "list: show all jobs",
+            "output: show the log tail for one job",
+            "kill: terminate a job",
+            "attach: follow a job's live output and wait for it to finish (use output for a non-blocking peek)",
+            "search: regex-search all job output",
+            "cleanup: purge terminal jobs",
+            "stats: show aggregate metrics",
+            "Completion notices are informational — call 'output' on a FAILED job, or on any job whose output is the deliverable (e.g. a test/build you must report). Don't call it just to acknowledge a completed job.",
+        ],
+        parameters: Type.Object({
+            action: StringEnum(
+                [
+                    "list",
+                    "output",
+                    "kill",
+                    "attach",
+                    "search",
+                    "cleanup",
+                    "stats",
+                ] as const,
+                { description: "Action to perform" }
+            ),
+            jobId: Type.Optional(Type.String({ description: "Job ID" })),
+            pattern: Type.Optional(
+                Type.String({ description: "Regex pattern for search" })
+            ),
+            wait: Type.Optional(
+                Type.Boolean({
+                    description: "Whether attach should wait for completion (default: true)",
+                })
+            ),
+        }),
+
+        async execute(_toolCallId, params, signal, onUpdate, ctx): Promise<AgentToolResult<undefined>> {
+            const p = params as {
+                action: "list" | "output" | "kill" | "attach" | "search" | "cleanup" | "stats";
+                jobId?: string;
+                pattern?: string;
+                wait?: boolean;
+            };
+            switch (p.action) {
+                case "list":
+                    return listAction(reg);
+                case "output":
+                    return await outputAction(reg, p.jobId!);
+                case "kill":
+                    return await killAction(reg, p.jobId!, ctx);
+                case "attach":
+                    return await attachAction(reg, p.jobId!, p.wait ?? true, signal, onUpdate, ctx);
+                case "search":
+                    return await searchAction(reg, p.pattern ?? "");
+                case "cleanup":
+                    return cleanupAction(reg, ctx);
+                case "stats":
+                    return statsAction(reg);
+            }
+        },
+    });
+}
+
+// ─── list: show all jobs ─────────────────────────────────────────────────
+
+function listAction(reg: BackgroundRegistry): AgentToolResult<undefined> {
+    // Lazy eviction sweep: terminal jobs whose outcome was already surfaced
+    // (notified — via the <task-notification>, a kill, or a read) leave the
+    // live registry here. Their output logs stay on disk.
+    for (const job of Array.from(reg.jobs.values())) {
+        if (isTerminalStatus(job.status) && job.notified) forget(reg, job);
+    }
+    const running = Array.from(reg.jobs.values()).filter(
+        (j) => j.status === "running"
+    );
+    const recent = reg.recentTerminal.slice(-5).reverse();
+    const lines = [
+        ...running.map((j) => formatJobLine(j)),
+        ...recent.map((j) => formatJobLine(j)),
+    ];
+    return {
+        content: [
+            textBlock(
+                lines.length > 0
+                    ? `Background Jobs:\n${lines.join("\n")}`
+                    : "No background jobs"
+            ),
+        ],
+        details: undefined,
+    };
+}
+
+// ─── output: read a job's log tail ───────────────────────────────────────
+
+async function outputAction(
+    reg: BackgroundRegistry,
+    jobId: string
+): Promise<AgentToolResult<undefined>> {
+    const job = findJob(reg, jobId);
+    if (!job) throw new Error(`No task found with ID: ${jobId}`);
+    // CC's TaskOutputTool: a successful read of a TERMINAL job's output marks
+    // it notified, suppressing the separate <task-notification>. Peeking at a
+    // still-running job does NOT mark — its completion must still notify.
+    if (isTerminalStatus(job.status)) markNotified(job);
+    const out = readLogTail(job, OUTPUT_PREVIEW_CHARS).trimEnd();
+    const label = jobLabel(job);
+    return {
+        content: [
+            textBlock(
+                out
+                    ? `Output for ${label} (${job.status})\n${out}`
+                    : `No output yet for ${label} (${job.status}). Log: ${job.logPath}`
+            ),
+        ],
+        details: undefined,
+    };
+}
+
+// ─── kill: terminate a job ───────────────────────────────────────────────
+
+async function killAction(
+    reg: BackgroundRegistry,
+    jobId: string,
+    ctx: UiContext
+): Promise<AgentToolResult<undefined>> {
+    const job = findJob(reg, jobId);
+    if (!job) throw new Error(`No task found with ID: ${jobId}`);
+    if (isTerminalStatus(job.status)) {
+        throw new Error(`Job is not running: ${job.id}`);
+    }
+    // terminateJobSilently latches `notified` BEFORE the kill, so the exit
+    // handler skips the <task-notification> — this result IS the outcome.
+    terminateJobSilently(reg, job);
+    renderSidebar(reg, ctx);
+    // Claude Code's TaskStopTool result string (command collapsed to one line).
+    return {
+        content: [
+            textBlock(`Successfully stopped task: ${job.id} (${oneLine(job.command)})`),
+        ],
+        details: undefined,
+    };
+}
+
+// ─── attach: follow live output until completion ─────────────────────────
+
+async function attachAction(
+    reg: BackgroundRegistry,
+    jobId: string,
+    waitForCompletion: boolean,
+    signal: AbortSignal | undefined,
+    onUpdate: ((u: { content: Array<{ type: "text"; text: string }>; details: undefined }) => void) | undefined,
+    ctx: UiContext
+): Promise<AgentToolResult<undefined>> {
+    const job = findJob(reg, jobId);
+    if (!job) throw new Error(`No task found with ID: ${jobId}`);
+    const label = jobLabel(job);
+
+    if (job.status === "running" && waitForCompletion) {
+        ensureCompletionPromise(job);
+        // We're actively following this job — suppress its separate completion
+        // notification so the attach result is the single notification. Undone
+        // on the abort path below, so a job we detach from still reports when
+        // it ends.
+        job.notified = true;
+
+        // Bail early if the OS process already died.
+        if (job.pid > 0 && !processExists(job.pid)) {
+            markTerminal(job, "failed");
+        }
+
+        onUpdate?.({
+            content: [
+                textBlock(`Following ${label} live output — waiting for it to finish…`),
+            ],
+            details: undefined,
+        });
+
+        // Stream the live log tail while we wait, so "attach" shows progress
+        // instead of sitting silent.
+        const poller = streamLog(job.logPath, onUpdate);
+        let onAbort: (() => void) | undefined;
+        try {
+            if (signal && !signal.aborted) {
+                const abortPromise = new Promise<void>((resolve) => {
+                    onAbort = resolve;
+                    signal.addEventListener("abort", onAbort, { once: true });
+                });
+                await Promise.race([job.donePromise, abortPromise]);
+            } else {
+                await job.donePromise;
+            }
+        } finally {
+            poller.stop();
+            if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+        }
+
+        if (job.status === "running") {
+            // Aborted before completion — we never reported the finish, so let
+            // the job's own completion notification fire later.
+            job.notified = false;
+            return {
+                content: [
+                    textBlock(
+                        `Stopped following ${label} — it's still running in the background. Use bash_async_list output to check on it.`
+                    ),
+                ],
+                details: undefined,
+            };
+        }
+    }
+
+    const message = `${label} finished. Status: ${job.status}`;
+    ctx.ui.notify(message, job.status === "failed" ? "error" : "info");
+    // The attach result IS the outcome notification — mark it notified so the
+    // <task-notification> is suppressed (CC parity). Covers both the "attached
+    // to an already-terminal job" and "waited then finished" cases; idempotent
+    // with the running-branch set above.
+    markNotified(job);
+    return {
+        content: [textBlock(`${message}. Use bash_async_list output for the full log.`)],
+        details: undefined,
+    };
+}
+
+// ─── search ──────────────────────────────────────────────────────────────
+
+const SEARCH_DISPLAY_LIMIT_PER_JOB = 20;
+
+async function searchAction(
+    reg: BackgroundRegistry,
+    pattern: string
+): Promise<AgentToolResult<undefined>> {
+    if (!pattern) throw new Error("search action requires a pattern");
+
+    let re: RegExp;
+    try {
+        re = new RegExp(pattern);
+    } catch (err) {
+        throw new Error(`Invalid regex: ${(err as Error).message}`);
+    }
+
+    const result = await searchLogs({
+        jobs: [...Array.from(reg.jobs.values()), ...reg.recentTerminal],
+        pattern: re,
+        maxHitsPerJob: SEARCH_DISPLAY_LIMIT_PER_JOB,
+        maxLineChars: PREVIEW_CHARS.line,
+    });
+
+    if (result.totalHits === 0) {
+        return {
+            content: [textBlock(`No matches for /${pattern}/ in any job log.`)],
+            details: undefined,
+        };
+    }
+
+    const blocks = result.groups.map((group) => {
+        const headLabel = group.name ? `${group.name} (${group.jobId})` : group.jobId;
+        const body = group.hits
+            .map((h) => `  ${h.path}:${h.line}: ${h.text}`)
+            .join("\n");
+        const more = group.count > group.hits.length
+            ? `\n  ... and ${group.count - group.hits.length} more`
+            : "";
+        return `${headLabel} (${group.count} matches)\n${body}${more}`;
+    });
+
+    return {
+        content: [
+            textBlock(
+                `Found ${result.totalHits} matches for /${pattern}/ across ${result.groups.length} job(s):\n\n${blocks.join("\n\n")}`
+            ),
+        ],
+        details: undefined,
+    };
+}
+
+// ─── cleanup ─────────────────────────────────────────────────────────────
+
+function cleanupAction(
+    reg: BackgroundRegistry,
+    ctx: UiContext
+): AgentToolResult<undefined> {
+    const { purged, bytesReclaimed } = cleanupTerminal(reg);
+    renderSidebar(reg, ctx);
+    const kb = Math.round(bytesReclaimed / 1024);
+    return {
+        content: [
+            textBlock(
+                `Cleaned up ${purged} terminal job(s). Reclaimed ${kb} KiB of disk.`
+            ),
+        ],
+        details: undefined,
+    };
+}
+
+// ─── stats ───────────────────────────────────────────────────────────────
+
+function statsAction(reg: BackgroundRegistry): AgentToolResult<undefined> {
+    const s = getStats(reg);
+    const lines = [
+        `Total started:   ${s.totalStarted}`,
+        `Currently running: ${s.running}`,
+        `Completed:        ${s.completed}`,
+        `Failed:           ${s.failed}`,
+        `Killed:           ${s.killed}`,
+        `Recent terminal:  ${s.recentTerminal}`,
+        `Average duration: ${formatDuration(s.averageDurationMs)}`,
+        `Total CPU time:   ${formatDuration(s.totalDurationMs)}`,
+    ];
+    return {
+        content: [textBlock("Background Jobs Stats:\n" + lines.join("\n"))],
+        details: undefined,
+    };
+}

package/src/tools/monitor.ts

@@ -0,0 +1,165 @@
+// src/tools/monitor.ts
+//
+// `monitor` tool — a streaming-event background watch. Each stdout line (or
+// WebSocket text frame) becomes one notification delivered into the agent's
+// turn. This is distinct from bash_async/run_async (one notification on
+// completion): monitor is for per-event streams (tail -f | grep, poll loops,
+// file watches, ws feeds), not one-shot "wait until done".
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import type { BackgroundRegistry } from "../state.ts";
+import {
+    MONITOR_DEFAULT_TIMEOUT_MS,
+    MONITOR_MAX_TIMEOUT_MS,
+    type UiContext,
+} from "../types.ts";
+import { add, createRunningJob, errPathFor, newJobId, logPathFor } from "../registry.ts";
+import { assertJobSlot, isBlankCommand, requireExistingCwd } from "../lifecycle.ts";
+import { isWsSupported, type WsSpec } from "../monitor-ws.ts";
+import {
+    openWsMonitorSource,
+    spawnCommandSource,
+    type MonitorSource,
+} from "../monitor-source.ts";
+import { startMonitorSession } from "../monitor-session.ts";
+import { textBlock } from "../format.ts";
+
+type MonitorCtx = UiContext & { cwd: string };
+
+interface MonitorParams {
+    command?: string;
+    ws?: WsSpec;
+    description: string;
+    persistent?: boolean;
+    timeout_ms?: number;
+}
+
+export function registerMonitorTool(pi: ExtensionAPI, reg: BackgroundRegistry): void {
+    pi.registerTool({
+        name: "bash_async_watch",
+        label: "Monitor",
+        description:
+            "Stream events from a long-running process: each stdout line (or WebSocket " +
+            "text frame) becomes one notification, delivered while you keep working. " +
+            "Use this for per-event streams — NOT for one-shot 'wait until done' (use " +
+            "bash run_async for that). Exit ends the watch.",
+        promptSnippet:
+            "Stream per-event notifications from a process, log, poll loop, or WebSocket",
+        promptGuidelines: [
+            "Pick by notification count: ONE ('tell me when done') → bash run_async with an `until` loop that exits; ONE-PER-EVENT → bash_async_watch.",
+            "Don't use an unbounded command (tail -f, while true, inotifywait -m) for a single notification — it never exits and stays armed until timeout.",
+            "Every pipe stage must flush per line: grep needs --line-buffered, awk needs fflush(); never pipe to `head` (it buffers until N matches).",
+            "Silence is not success: your filter must match failure signatures too (e.g. grep -E --line-buffered 'done|Traceback|Error|FAILED|Killed|OOM'), or a crash looks identical to 'still running'.",
+            "Only stdout is the event stream; merge stderr with 2>&1 if its failures should notify. Poll remote APIs at 30s+, local checks at 0.5–1s, and guard transient failures with `|| true`.",
+            "Give a specific description — it is shown on every notification.",
+            "Use persistent:true for session-length watches (PR monitoring, log tails); stop it with the bash_async_list tool (action='kill').",
+            "Use the ws source for a WebSocket feed instead of `command: 'websocat …'` — each text frame becomes one event.",
+        ],
+        parameters: Type.Object({
+            command: Type.Optional(
+                Type.String({ description: "Shell script; each stdout line is an event. Mutually exclusive with ws." })
+            ),
+            ws: Type.Optional(
+                Type.Object(
+                    {
+                        url: Type.String({ description: "WebSocket URL (ws:// or wss://)" }),
+                        protocols: Type.Optional(Type.Array(Type.String())),
+                    },
+                    { description: "WebSocket source; each text frame is an event. Mutually exclusive with command." }
+                )
+            ),
+            description: Type.String({ description: "Specific description, shown on every notification." }),
+            persistent: Type.Optional(
+                Type.Boolean({ description: "Run for the whole session (no timeout). Stop via bash_async_list action='kill'. Default false." })
+            ),
+            timeout_ms: Type.Optional(
+                Type.Number({ description: "Kill after this deadline (default 300000, max 3600000). Ignored when persistent." })
+            ),
+        }),
+
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            const p = params as MonitorParams;
+            const mctx = ctx as MonitorCtx;
+
+            // --- Validation: command XOR ws -------------------------------
+            const hasCommand = typeof p.command === "string" && !isBlankCommand(p.command);
+            const hasWs = !!p.ws && typeof p.ws.url === "string" && p.ws.url.length > 0;
+            if (hasCommand && hasWs) {
+                throw new Error("Provide either `command` or `ws`, not both.");
+            }
+            if (!hasCommand && !hasWs) {
+                throw new Error("A monitor needs a `command` or a `ws` source.");
+            }
+            if (!p.description || p.description.trim().length === 0) {
+                throw new Error("`description` is required (shown on every notification).");
+            }
+            if (hasWs && !isWsSupported()) {
+                throw new Error(
+                    "WebSocket is not available in this runtime (needs Node 22+). " +
+                        `Use command: 'websocat ${p.ws!.url}' or 'wscat -c ${p.ws!.url}' instead.`
+                );
+            }
+            if (hasCommand) requireExistingCwd(mctx.cwd);
+            assertJobSlot(reg);
+
+            const description = p.description.trim();
+            const persistent = p.persistent === true;
+            const timeoutMs = Math.min(
+                p.timeout_ms && p.timeout_ms > 0 ? p.timeout_ms : MONITOR_DEFAULT_TIMEOUT_MS,
+                MONITOR_MAX_TIMEOUT_MS
+            );
+
+            const id = newJobId("monitor", reg);
+            const logPath = logPathFor(id);
+
+            // Build the event source (command or ws) behind one seam, then hand
+            // it to the session, which owns the streaming/terminal lifecycle.
+            const source: MonitorSource = hasWs
+                ? openWsMonitorSource(p.ws!, logPath)
+                : spawnCommandSource({
+                      command: p.command!,
+                      cwd: mctx.cwd,
+                      logPath,
+                      errPath: errPathFor(id),
+                  });
+
+            const job = createRunningJob({
+                id,
+                name: description,
+                command: source.label,
+                pid: source.pid,
+                logPath,
+                toolCallId: _toolCallId,
+                kind: "monitor",
+            });
+            add(reg, job);
+
+            startMonitorSession({
+                pi,
+                reg,
+                ctx: mctx,
+                job,
+                source,
+                description,
+                persistent,
+                timeoutMs,
+            });
+
+            const sourceDesc = hasWs ? `WebSocket ${p.ws!.url}` : "command";
+            const deadlineDesc = persistent
+                ? "persistent (stop via bash_async_list action='kill')"
+                : `timeout ${Math.round(timeoutMs / 1000)}s`;
+            return {
+                content: [
+                    textBlock(
+                        `Monitor ${id} started — ${sourceDesc}, ${deadlineDesc}. ` +
+                            `Events ("${description}") will arrive as notifications. ` +
+                            `Output: ${logPath}`
+                    ),
+                ],
+                details: undefined,
+            };
+        },
+    });
+}

package/src/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Type definitions and shared constants for the background-tasks extension.
+ */
+
+import type { TUI, Component, KeybindingsManager } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { ChildProcess } from "node:child_process";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+
+// --- Configuration constants ---
+export const DEFAULT_TIMEOUT_MS = 120_000;
+export const QUICK_COMPLETION_MS = 2_000;
+export const FOREGROUND_TAIL_BYTES = 4_096;
+export const STALL_CHECK_INTERVAL_MS = 5_000;
+export const STALL_THRESHOLD_MS = 45_000;
+export const STALL_TAIL_BYTES = 1024;
+export const MAX_LOG_BYTES = 100 * 1024 * 1024;
+export const OUTPUT_PREVIEW_CHARS = 12_000;
+export const RECENT_TERMINAL_KEEP = 20;
+export const MAX_CONCURRENT_JOBS = 16;
+
+// --- Monitor (streaming-event) constants ---
+/** Poll cadence for the line-accurate follower. Lines read within one tick are
+ *  batched into a single event — so this doubles as the ~200ms batch window. */
+export const MONITOR_POLL_MS = 200;
+/** Default streaming watch deadline (matches Claude Code's Monitor). */
+export const MONITOR_DEFAULT_TIMEOUT_MS = 300_000;
+/** Hard ceiling on a monitor's deadline. */
+export const MONITOR_MAX_TIMEOUT_MS = 3_600_000;
+/** Sliding window for firehose detection. */
+export const MONITOR_RATE_WINDOW_MS = 10_000;
+/** Max emitted lines per window before a monitor is auto-stopped. */
+export const MONITOR_MAX_LINES_PER_WINDOW = 500;
+
+export const PREVIEW_CHARS = {
+    sidebar: 25,
+    taskList: 40,
+    detail: 50,
+    line: 80,
+    /** Live progress line shown in the sidebar pill. */
+    progress: 60,
+} as const;
+
+// --- Domain types ---
+/** Claude Code's task-status enum. "pending" exists for parity (a task that is
+ *  registered but not yet started); every spawn path here starts "running". */
+export type JobStatus = "pending" | "running" | "completed" | "failed" | "killed";
+
+/** True once the job has reached a terminal state (completed | failed | killed). */
+export function isTerminalStatus(status: JobStatus): boolean {
+    return status === "completed" || status === "failed" || status === "killed";
+}
+
+/** What kind of asynchronous job this is. "shell" is the default; "monitor"
+ * is a streaming-event watch from the bash_async_watch tool. */
+export type JobKind = "shell" | "monitor";
+
+/** Typed job identifiers use a kind prefix, the spawning process identifier, and
+ * eight random base36 characters (for example, `b1234-7f3k9a2x`). */
+export const JOB_ID_PREFIX: Record<JobKind, string> = {
+    shell: "b",
+    monitor: "m",
+};
+
+export interface Job {
+    id: string;
+    name?: string;
+    command: string;
+    pid: number;
+    startTime: number;
+    status: JobStatus;
+    exitCode?: number;
+    logPath: string;
+    proc?: ChildProcess;
+    toolCallId: string;
+    donePromise?: Promise<void>;
+    resolveDone?: () => void;
+    /** Exactly-once latch for the terminal <task-notification> (Claude Code's
+     *  `notified` flag). Set BEFORE the notification send, before a deliberate
+     *  kill, and when the agent reads the outcome via bash_async_list output/attach — any
+     *  path that already surfaced the result suppresses the notification. */
+    notified?: boolean;
+    isBackgrounded: boolean;
+    /** Defaults to "shell" when absent. */
+    kind?: JobKind;
+    /** Transient teardown hook (follower + ws socket). */
+    stop?: () => void;
+}
+
+export type BackgroundReason = "manual" | "timeout";
+
+/** Transient handle for an in-flight foreground bash command, keyed by
+ * toolCallId in the registry. Async handoff and the timeout timer call
+ * requestPause to continue the command asynchronously. */
+export interface ForegroundSlot {
+    requestPause: (reason: BackgroundReason) => void;
+}
+
+// --- Event types ---
+export const EVENT = {
+    stall: "bg-stall",
+    taskNotification: "task-notification",
+    monitorEvent: "bg-monitor-event",
+} as const;
+
+export type EventName = (typeof EVENT)[keyof typeof EVENT];
+
+// --- Deliver options ---
+/** Steer the message into the current/next turn AND wake the agent.
+ *  pi queues it while the agent is streaming and delivers it at the next
+ *  tool-call boundary — Claude Code's 'next' priority. Use when the message
+ *  IS something the agent must react to now: a background job's terminal
+ *  <task-notification>, a stall warning, a deadline decision. */
+export const DELIVER_STEER = { deliverAs: "steer", triggerTurn: true } as const;
+/** Queue the message behind the current turn as a PASSIVE follow-up. The agent
+ *  picks it up on its next natural turn (when the user re-engages or the
+ *  current turn ends) but it does NOT spawn a new turn on its own. Monitor
+ *  stream events are informational and never force an unsolicited
+ *  acknowledgment or starve user input.
+ *  NOTE: sendMessage-only — `pi.sendUserMessage` rejects `triggerTurn` and
+ *  takes just `{ deliverAs: "followUp" }`. */
+export const DELIVER_FOLLOWUP = { deliverAs: "followUp", triggerTurn: false } as const;
+
+// --- UI context ---
+export interface UiContext {
+    ui: {
+        notify(message: string, level?: "info" | "warning" | "error"): void;
+        setWidget(
+            name: string,
+            content: string[] | undefined,
+            options?: { placement?: "aboveEditor" | "belowEditor" }
+        ): void;
+        setStatus(name: string, content: unknown): void;
+        theme: { fg(colour: string, text: string): string };
+        select(title: string, options: string[]): Promise<string | undefined>;
+        editor(title: string, content: string): Promise<string | undefined>;
+        custom?<T>(
+            factory: (
+                tui: TUI,
+                theme: Theme,
+                keybindings: KeybindingsManager,
+                done: (result: T) => void,
+            ) => Component,
+        ): Promise<T>;
+    };
+}
+
+export type ToolResult = AgentToolResult<unknown>;