pi-async-bash 0.1.0

package/src/tools/bash-bg.ts

@@ -0,0 +1,116 @@
+// src/tools/bash-bg.ts
+//
+// `bash_async` starts a Bash command asynchronously and returns its job ID.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import { appendFileSync } from "node:fs";
+import type { BackgroundRegistry } from "../state.ts";
+import { isTerminalStatus, type UiContext } from "../types.ts";
+import { killProcessTree, spawnWithFileOutput } from "../spawn.ts";
+import { add, createRunningJob, newJobId, logPathFor } from "../registry.ts";
+import {
+    assertJobSlot,
+    detectBlockedSleep,
+    isAutoBackgroundAllowed,
+    isBlankCommand,
+    requireExistingCwd,
+    SLEEP_WAIT_GUIDANCE,
+    startBackgroundJob,
+} from "../lifecycle.ts";
+import { textBlock } from "../format.ts";
+import { renderBashAsyncCall } from "../render.ts";
+
+type BashAsyncContext = UiContext & { cwd: string };
+
+/** Register immediate asynchronous Bash execution. */
+export function registerBashBgTool(pi: ExtensionAPI, reg: BackgroundRegistry): void {
+    pi.registerTool({
+        name: "bash_async",
+        label: "Async Bash",
+        description: "Start a Bash command asynchronously. Output is saved to /tmp/pi-bg/<jobId>.log.",
+        promptSnippet: "Start long-running Bash commands asynchronously",
+        promptGuidelines: [
+            "Use bash_async when a command should start asynchronously immediately.",
+            "Use bash_async_watch for per-event streams; bash_async reports one terminal outcome.",
+            "Do not start a fixed sleep asynchronously. Use bash_async_list action='attach', bash_async_watch, or an until loop that exits when ready.",
+            "Give the job a name when it will be easier to track with bash_async_list.",
+        ],
+        parameters: Type.Object({
+            command: Type.String({ description: "Bash command to run" }),
+            name: Type.Optional(Type.String({ description: "Label shown by bash_async_list" })),
+            timeout: Type.Optional(Type.Number({ description: "Decision timeout in seconds" })),
+            notify: Type.Optional(Type.Boolean({ description: "Send terminal notification (default: true)" })),
+        }),
+        renderCall: renderBashAsyncCall,
+        async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+            const input = params as { command: string; name?: string; timeout?: number; notify?: boolean };
+            const asyncContext = ctx as BashAsyncContext;
+            if (isBlankCommand(input.command)) throw new Error("Command is empty.");
+            const sleepMatch = detectBlockedSleep(input.command);
+            if (sleepMatch) throw new Error(`Blocked: ${sleepMatch}. ${SLEEP_WAIT_GUIDANCE}`);
+            requireExistingCwd(asyncContext.cwd);
+            assertJobSlot(reg);
+
+            const id = newJobId("shell", reg);
+            const logPath = logPathFor(id);
+            const spawned = spawnWithFileOutput({ command: input.command, cwd: asyncContext.cwd, logPath });
+            const job = createRunningJob({
+                id,
+                name: input.name,
+                command: input.command,
+                pid: spawned.pid,
+                logPath,
+                toolCallId,
+            });
+            add(reg, job);
+            const jobAbort = startBackgroundJob({
+                reg,
+                pi,
+                ctx: asyncContext,
+                job,
+                exit: spawned.exit,
+                shouldNotify: input.notify !== false,
+            });
+            scheduleDecisionTimeout(reg, asyncContext, job, input.timeout, jobAbort, logPath);
+
+            return {
+                content: [textBlock(
+                    `Command running asynchronously with ID: ${id}.` +
+                    `${input.name ? ` Name: ${input.name}.` : ""} Output is being written to: ${logPath}`,
+                )],
+                details: undefined,
+            };
+        },
+    });
+}
+
+function scheduleDecisionTimeout(
+    reg: BackgroundRegistry,
+    ctx: BashAsyncContext,
+    job: ReturnType<typeof createRunningJob>,
+    timeout: number | undefined,
+    jobAbort: AbortController,
+    logPath: string,
+): void {
+    if (!timeout) return;
+    const timer = setTimeout(() => {
+        if (isTerminalStatus(job.status) || reg.nonInteractive) return;
+        if (!isAutoBackgroundAllowed(job.command)) {
+            try {
+                appendFileSync(logPath, `Command timed out after ${timeout}s\n`);
+            } catch {
+                // Process termination remains correct if diagnostics cannot be written.
+            }
+            killProcessTree(job.pid, "SIGTERM");
+            return;
+        }
+        reg.pendingDecisionJobId = job.id;
+        ctx.ui.notify(
+            `Async Bash job ${job.id} exceeded ${timeout}s. Use bash_async_decide to keep, stop, or inspect it.`,
+            "warning",
+        );
+    }, timeout * 1000);
+    timer.unref();
+    jobAbort.signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+}

package/src/tools/bash-params.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared bash parameter schema (TypeBox) used by the overridden `bash` tool.
+ */
+
+import { Type } from "@earendil-works/pi-ai";
+
+export const bashParamSchema = Type.Object({
+    command: Type.String({ description: "Shell command to run" }),
+    timeout: Type.Optional(
+        Type.Number({ description: "Timeout in seconds (default: 120)" })
+    ),
+    run_async: Type.Optional(
+        Type.Boolean({
+            description:
+                "Set to true to run this command in the background immediately. " +
+                "Output is saved to /tmp/pi-bg/<jobId>.log.",
+        })
+    ),
+    description: Type.Optional(
+        Type.String({ description: "Short description of what this command does" })
+    ),
+});

package/src/tools/bash.ts

@@ -0,0 +1,347 @@
+/**
+ * `bash` tool override.
+ *
+ * Single file-descriptor backend (no tmux):
+ *   - run_async=true starts asynchronous execution and returns a job handle
+ *   - foreground commands race completion against asynchronous handoff
+ *   - a 2s quick-completion window skips handoff machinery
+ *   - `/bash-async`, cooperative input, or the timeout timer move a command to async execution
+ */
+
+import type {
+    AgentToolResult,
+    AgentToolUpdateCallback,
+} from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+    createBashToolDefinition,
+    type BashToolDetails,
+} from "@earendil-works/pi-coding-agent";
+import { appendFileSync, unlinkSync } from "node:fs";
+import type { BackgroundRegistry } from "../state.ts";
+import {
+    DEFAULT_TIMEOUT_MS,
+    OUTPUT_PREVIEW_CHARS,
+    QUICK_COMPLETION_MS,
+    type ForegroundSlot,
+    type UiContext,
+} from "../types.ts";
+import { spawnWithFileOutput, killProcessTree, type SpawnExit } from "../spawn.ts";
+import { streamLog } from "../output.ts";
+import { showBackgroundHint, clearBackgroundHint } from "../hint.ts";
+import {
+    add,
+    createRunningJob,
+    markStarted,
+    newJobId,
+    logPathFor,
+    readLogTail,
+} from "../registry.ts";
+import {
+    assertJobSlot,
+    detectBlockedSleep,
+    SLEEP_WAIT_GUIDANCE,
+    isAutoBackgroundAllowed,
+    isBlankCommand,
+    requireExistingCwd,
+    startBackgroundJob,
+} from "../lifecycle.ts";
+import { textBlock } from "../format.ts";
+import { bashParamSchema } from "./bash-params.ts";
+
+/** UI context + cwd is all this tool needs from the host context. */
+type BashCtx = UiContext & { cwd: string };
+
+/** Register the overridden `bash` tool. */
+export function registerBashTool(
+    pi: ExtensionAPI,
+    reg: BackgroundRegistry,
+    originalBash: ReturnType<typeof createBashToolDefinition>
+): void {
+    pi.registerTool({
+        ...originalBash,
+        name: "bash",
+        description:
+            "Run a Bash command. Long-running commands continue asynchronously after timeout. " +
+            "Set run_async=true to start asynchronously immediately. " +
+            "Use /bash-async to hand off a running command.",
+        promptSnippet:
+            "Run shell commands; long-running commands continue asynchronously or use run_async=true",
+        promptGuidelines: [
+            "Use bash with run_async=true when a command is expected to run for a long time.",
+            "run_async is for ONE notification (the command exits when done). For per-event streaming (watching logs, polling an API, file changes), use the bash_async_watch tool instead.",
+            "Never `sleep N` to wait for something — the job lingers for the full sleep. Wait on a background job with bash_async_list action='attach', watch with the bash_async_watch tool, or poll with an `until` loop that exits when ready.",
+            "Check background job status with bash_async_list action='list'.",
+            "Read background output with bash_async_list action='output'.",
+        ],
+        parameters: bashParamSchema,
+
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            const p = params as {
+                command: string;
+                timeout?: number;
+                run_async?: boolean;
+                description?: string;
+            };
+            const bashCtx = ctx as BashCtx;
+
+            if (isBlankCommand(p.command)) throw new Error("Command is empty.");
+            requireExistingCwd(bashCtx.cwd);
+
+            const sleepMatch = detectBlockedSleep(p.command);
+            if (sleepMatch) {
+                throw new Error(`Blocked: ${sleepMatch}. ${SLEEP_WAIT_GUIDANCE}`);
+            }
+
+            assertJobSlot(reg);
+
+            // Explicit background mode — spawn and return immediately.
+            if (p.run_async) {
+                return spawnBackground({
+                    toolCallId,
+                    command: p.command,
+                    name: p.description,
+                    cwd: bashCtx.cwd,
+                    reg,
+                    pi,
+                    ctx: bashCtx,
+                });
+            }
+
+            // Foreground mode — race completion against backgrounding.
+            return runForeground({
+                toolCallId,
+                command: p.command,
+                timeoutMs: p.timeout ? p.timeout * 1000 : DEFAULT_TIMEOUT_MS,
+                signal,
+                onUpdate,
+                ctx: bashCtx,
+                reg,
+                pi,
+            });
+        },
+    });
+}
+
+// --- Foreground backend --------------------------------------------------
+
+async function runForeground(args: {
+    toolCallId: string;
+    command: string;
+    timeoutMs: number;
+    signal: AbortSignal | undefined;
+    onUpdate: AgentToolUpdateCallback<BashToolDetails | undefined> | undefined;
+    ctx: BashCtx;
+    reg: BackgroundRegistry;
+    pi: ExtensionAPI;
+}): Promise<AgentToolResult<BashToolDetails | undefined>> {
+    const { toolCallId, command, timeoutMs, signal, onUpdate, ctx, reg, pi } =
+        args;
+    const id = newJobId("shell", reg);
+    const logPath = logPathFor(id);
+
+    // Spawn WITHOUT wiring the turn signal to a process kill. Cooperative
+    // steering aborts the turn (ctx.abort) to move this command to the
+    // background; if the turn signal killed the process group, that abort would
+    // kill the very command we just backgrounded. We manage the signal manually
+    // below and only kill on a genuine cancel (abort with no pause requested).
+    const spawned = spawnWithFileOutput({
+        command,
+        cwd: ctx.cwd,
+        logPath,
+    });
+
+    // Register the foreground slot so `/bash-async` can find this command.
+    let pauseRequested = false;
+    let handedToBackground = false;
+    let pauseResolve: ((reason: "manual" | "timeout") => void) | null = null;
+    const pausePromise = new Promise<"manual" | "timeout">((r) => {
+        pauseResolve = r;
+    });
+    const requestPause = (reason: "manual" | "timeout") => {
+        pauseRequested = true;
+        pauseResolve?.(reason);
+    };
+
+    // Claude Code parity for the turn's abort signal:
+    //   - No pause requested  → a genuine cancel (Esc / 'user-cancel'): kill the
+    //     process group, like CC's ShellCommand.#abortHandler.
+    //   - Pause already requested → cooperative input, `/bash-async`, or timeout
+    //     moving the command to async execution: leave it running.
+    // Long-running work is protected the CC way — by auto-backgrounding at the
+    // timeout — not by refusing to honor a deliberate cancel.
+    const onTurnAbort = () => {
+        if (!pauseRequested) killProcessTree(spawned.pid, "SIGTERM");
+    };
+    if (signal) {
+        if (signal.aborted) onTurnAbort();
+        else signal.addEventListener("abort", onTurnAbort);
+    }
+
+    const slot: ForegroundSlot = { requestPause };
+    reg.foreground.set(toolCallId, slot);
+
+    const job = createRunningJob({
+        id,
+        command,
+        pid: spawned.pid,
+        logPath,
+        toolCallId,
+        isBackgrounded: false,
+    });
+    // Foreground jobs are tracked for the sidebar and async handoff but are not
+    // counted as started until they become asynchronous.
+    reg.jobs.set(id, job);
+
+    // Promote the running command to an asynchronous job (cooperative input,
+    // `/bash-async`, or timeout). Idempotent.
+    const promoteToBackground = () => {
+        if (handedToBackground) return;
+        handedToBackground = true;
+        // Clear the foreground slot now (not only in `finally`) so a backgrounded
+        // command can't strand a stale slot when cooperative steering tears down
+        // the turn right after requesting the pause.
+        reg.foreground.delete(toolCallId);
+        job.isBackgrounded = true;
+        markStarted(reg);
+        startBackgroundJob({ reg, pi, ctx, job, exit: spawned.exit });
+    };
+
+    // Timeout timer.
+    const timeoutTimer = setTimeout(() => {
+        if (reg.nonInteractive) return;
+        if (!reg.foreground.has(toolCallId)) return;
+        if (!isAutoBackgroundAllowed(command)) {
+            // Not eligible for auto-background (e.g. `sleep`) — kill it, but
+            // leave a marker in the log first so the model can tell a timeout
+            // kill apart from a normal failure (Claude Code prepends
+            // "Command timed out after {duration}" to the output).
+            try {
+                appendFileSync(logPath, `Command timed out after ${Math.round(timeoutMs / 1000)}s\n`);
+            } catch { /* best-effort — the kill below still happens */ }
+            killProcessTree(spawned.pid, "SIGTERM");
+            return;
+        }
+        requestPause("timeout");
+    }, timeoutMs);
+    (timeoutTimer as NodeJS.Timeout).unref();
+
+    let progressPoller: { stop: () => void } | undefined;
+    let hintShown = false;
+
+    const cleanup = () => {
+        progressPoller?.stop();
+        clearTimeout(timeoutTimer);
+        if (signal) signal.removeEventListener("abort", onTurnAbort);
+    };
+
+    // Foreground completion (quick or normal): read output, surface errors.
+    // Registry teardown happens in `finally` so no exit path can strand the job.
+    const finishForeground = (
+        exit: SpawnExit
+    ): AgentToolResult<BashToolDetails | undefined> => {
+        const output = readLogTail(job, OUTPUT_PREVIEW_CHARS);
+        // A signal death (e.g. Esc-cancel killed the process group) is a
+        // deliberate cancel, not a command failure — never an error result.
+        if (exit.signal === null && exit.code !== 0) {
+            throw new Error(output || `Command exited with code ${exit.code ?? 1}`);
+        }
+        return { content: [textBlock(output || "(no output)")], details: undefined };
+    };
+
+    try {
+        // Quick completion window (2s). Keep the timer referenced while the
+        // detached child is the only active handle, then clear it on exit.
+        let quickTimer: NodeJS.Timeout | undefined;
+        const quickResult = await Promise.race<SpawnExit | null>([
+            spawned.exit,
+            new Promise<null>((resolve) => {
+                quickTimer = setTimeout(() => resolve(null), QUICK_COMPLETION_MS);
+            }),
+        ]);
+        if (quickTimer) clearTimeout(quickTimer);
+
+        if (quickResult !== null) {
+            return finishForeground(quickResult);
+        }
+
+        // Still running past the quick window — stream progress and show the
+        // `/bash-async` handoff hint.
+        progressPoller = streamLog(logPath, onUpdate);
+        showBackgroundHint(ctx);
+        hintShown = true;
+
+        // Race: completion vs backgrounding.
+        const race = await Promise.race<
+            | { kind: "completed"; exit: SpawnExit }
+            | { kind: "backgrounded"; reason: "manual" | "timeout" }
+        >([
+            spawned.exit.then((exit) => ({ kind: "completed" as const, exit })),
+            pausePromise.then((reason) => ({ kind: "backgrounded" as const, reason })),
+        ]);
+
+        if (race.kind === "backgrounded") {
+            promoteToBackground();
+            // Claude Code's exact tool-result strings: a distinct line for a
+            // manual background, one generic line for the timeout path.
+            const text =
+                race.reason === "manual"
+                    ? `Command was moved to async execution with ID: ${id}. Output is being written to: ${logPath}`
+                    : `Command running asynchronously with ID: ${id}. Output is being written to: ${logPath}`;
+            return { content: [textBlock(text)], details: undefined };
+        }
+
+        // Normal completion.
+        return finishForeground(race.exit);
+    } finally {
+        // Single teardown for every exit path (return, throw, background hand-off).
+        cleanup();
+        if (hintShown) clearBackgroundHint(ctx);
+        reg.foreground.delete(toolCallId);
+        if (!handedToBackground) {
+            reg.jobs.delete(id);
+            try { unlinkSync(logPath); } catch { /* best-effort */ }
+        }
+    }
+}
+
+// --- Background backend --------------------------------------------------
+
+function spawnBackground(args: {
+    toolCallId: string;
+    command: string;
+    name?: string;
+    cwd: string;
+    reg: BackgroundRegistry;
+    pi: ExtensionAPI;
+    ctx: UiContext;
+}): AgentToolResult<BashToolDetails | undefined> {
+    const id = newJobId("shell", args.reg);
+    const logPath = logPathFor(id);
+
+    const spawned = spawnWithFileOutput({
+        command: args.command,
+        cwd: args.cwd,
+        logPath,
+    });
+
+    const job = createRunningJob({
+        id,
+        name: args.name,
+        command: args.command,
+        pid: spawned.pid,
+        logPath,
+        toolCallId: args.toolCallId,
+    });
+    add(args.reg, job);
+    startBackgroundJob({ reg: args.reg, pi: args.pi, ctx: args.ctx, job, exit: spawned.exit });
+
+    return {
+        content: [
+            textBlock(
+                `Command running asynchronously with ID: ${id}. Output is being written to: ${logPath}`
+            ),
+        ],
+        details: undefined,
+    };
+}

package/src/tools/job-decide.ts

@@ -0,0 +1,60 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import type { BackgroundRegistry } from "../state.ts";
+import { OUTPUT_PREVIEW_CHARS, type UiContext } from "../types.ts";
+import { findJob, readLogTail, renderSidebar } from "../registry.ts";
+import { terminateJobSilently } from "../lifecycle.ts";
+import { jobLabel, textBlock } from "../format.ts";
+
+/** Register decisions for timed asynchronous Bash commands. */
+export function registerJobDecideTool(pi: ExtensionAPI, reg: BackgroundRegistry): void {
+    pi.registerTool({
+        name: "bash_async_decide",
+        label: "Async Bash Decision",
+        description: "Keep, stop, or inspect an asynchronous Bash command that exceeded its timeout.",
+        promptSnippet: "Resolve a timed asynchronous Bash command",
+        promptGuidelines: [
+            "Use bash_async_decide after a bash_async timeout notification.",
+            "keep leaves the command running, kill stops it, and check shows its current output.",
+        ],
+        parameters: Type.Object({
+            jobId: Type.String({ description: "Timed asynchronous Bash job ID" }),
+            decision: StringEnum(["keep", "kill", "check"] as const, {
+                description: "Action to take for the timed job",
+            }),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            const { jobId, decision } = params as {
+                jobId: string;
+                decision: "keep" | "kill" | "check";
+            };
+            const job = findJob(reg, jobId);
+            if (!job) {
+                if (reg.pendingDecisionJobId === jobId) {
+                    reg.pendingDecisionJobId = undefined;
+                }
+                return { content: [textBlock(`No async Bash job found with ID: ${jobId}.`)], details: undefined };
+            }
+
+            if (decision === "check") {
+                const output = readLogTail(job, OUTPUT_PREVIEW_CHARS);
+                return {
+                    content: [textBlock(`Output for ${jobLabel(job)}:\n${output || "(no output yet)"}`)],
+                    details: undefined,
+                };
+            }
+
+            reg.pendingDecisionJobId = undefined;
+            if (decision === "kill") {
+                terminateJobSilently(reg, job);
+                renderSidebar(reg, ctx as UiContext);
+                return { content: [textBlock(`Stopped ${jobLabel(job)}.`)], details: undefined };
+            }
+
+            return {
+                content: [textBlock(`Keeping ${jobLabel(job)} running. Use bash_async_list to inspect it later.`)],
+                details: undefined,
+            };
+        },
+    });
+}