pi-async-bash 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 patty.io
+Copyright (c) 2026 Dustin Fox (fork modifications)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# pi-async-bash
+
+[![npm version](https://img.shields.io/npm/v/pi-async-bash)](https://www.npmjs.com/package/pi-async-bash)
+[![npm downloads](https://img.shields.io/npm/dm/pi-async-bash)](https://www.npmjs.com/package/pi-async-bash)
+[![CI](https://img.shields.io/github/actions/workflow/status/unrelentingfox/pi-async-bash/ci.yml?branch=main&label=CI)](https://github.com/unrelentingfox/pi-async-bash/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/node/v/pi-async-bash)](https://www.npmjs.com/package/pi-async-bash)
+[![License](https://img.shields.io/github/license/unrelentingfox/pi-async-bash)](https://github.com/unrelentingfox/pi-async-bash/blob/main/LICENSE)
+
+`pi-async-bash` adds asynchronous Bash execution, task management, and event
+watches to [Pi](https://github.com/badlogic/pi-mono).
+
+## Install
+
+Install from npm:
+
+```bash
+pi install npm:pi-async-bash
+```
+
+During development, add the local checkout to Pi settings:
+
+```json
+{
+  "packages": [
+    "/local/home/dustinfx/workplace/pi/pi-async-bash"
+  ]
+}
+```
+
+## Agent tools
+
+| Tool | Parameters | Behavior |
+| --- | --- | --- |
+| `bash` | `command`; optional `timeout`, `run_async`, `description` | Overrides Pi's Bash tool. Commands start in the foreground by default. `run_async: true` starts detached work immediately. A long foreground command continues asynchronously after `timeout`. |
+| `bash_async` | `command`; optional `name`, `timeout`, `notify` | Starts a command asynchronously, shows the command in the call row, and returns its job ID and `/tmp/pi-bg/<jobId>.log` path. It sends one terminal notification unless `notify: false`. |
+| `bash_async_list` | `action`: `list`, `output`, `kill`, `attach`, `search`, `cleanup`, or `stats`; action-specific `jobId`, `pattern`, `wait` | Lists, reads, follows, searches, stops, cleans up, and reports on async jobs and watches. |
+| `bash_async_watch` | exactly one of `command` or `ws`; `description`; optional `persistent`, `timeout_ms` | Returns immediately and delivers each stdout line or WebSocket text frame as an event. It stops on source exit, timeout, event-rate protection, or `bash_async_list` `kill`. |
+| `bash_async_decide` | `jobId`; `decision`: `keep`, `kill`, or `check` | Resolves a `bash_async` command that has exceeded its optional timeout. |
+
+`run_in_background` is not supported. Use `run_async` instead.
+
+## Slash commands
+
+| Command | Behavior |
+| --- | --- |
+| `/bash-async` | Send the currently running bash command to the background. Return control to the agent. |
+| `/bash-async-list` | Open the interactive task manager. `j`/`k` and arrow keys move the highlight, `Enter` opens the highlighted task's output, `Ctrl+x` starts kill confirmation, and `Escape` closes the root list, returns from output, or cancels confirmation. |
+
+There are no keyboard shortcuts. While a foreground command runs, the editor
+shows `/bash-async to run asynchronously`. Submitting a new user message also
+hands active foreground Bash work to async execution and queues the message as
+a follow-up.
+
+## Behavior and safety
+
+- Async commands use a detached process group and capture combined output in
+  `/tmp/pi-bg`.
+- `bash_async_list attach` streams output while it waits. Use `output` for a
+  bounded non-blocking read.
+- `bash_async_watch` is for many events. Use `bash` with `run_async: true` or
+  `bash_async` when only the terminal result matters.
+- The extension rejects naïve long `sleep` commands, warns about interactive
+  prompts, caps non-persistent log growth at 100 MiB, limits concurrent jobs,
+  and removes stale log files at startup.
+- Same-process `/reload` restores compatible running job records. A fresh Pi
+  process never adopts or signals an old process ID, preventing PID reuse bugs.
+
+## Migration from upstream
+
+| Upstream | pi-async-bash |
+| --- | --- |
+| `bash` with `run_in_background` | `bash` with `run_async` |
+| `bash_bg` | `bash_async` |
+| `jobs` | `bash_async_list` |
+| `monitor` | `bash_async_watch` |
+| `job_decide` | `bash_async_decide` |
+| `/bg` | `/bash-async` |
+| `/bg-list` | `/bash-async-list` |
+| `/bg-version` | removed |
+| `agent_bg` | removed; use Pi's own subagent tooling |
+| keyboard shortcuts | removed |
+
+## Development
+
+```bash
+pnpm install --frozen-lockfile
+pnpm run check
+```
+
+## License and attribution
+
+Copyright (c) 2026 patty.io
+Copyright (c) 2026 Dustin Fox (fork modifications)
+
+Licensed under the MIT License. See [LICENSE](LICENSE).
+
+## Fork and attribution
+
+`pi-async-bash` is based on Patrick Rho's
+[`patty-io/pi-patty-bg-tasks`](https://github.com/patty-io/pi-patty-bg-tasks).
+It retains the upstream Git history and MIT notice. This project removes
+background Pi agent spawning and global keyboard shortcuts, and renames the
+public interface to use `async` consistently. The unscoped name
+`pi-background-bash` was already published, so this project uses
+`pi-async-bash`.

package/RELEASING.md

@@ -0,0 +1,23 @@
+# Releasing
+
+## Automated releases
+
+Every push to `main` runs Release Please. It opens or updates a release pull
+request from [Conventional Commits](https://github.com/googleapis/release-please#how-should-i-write-my-commits).
+Use `feat` for a minor release, `fix` for a patch release, `deps` for a
+dependency release, and `!` in the pull request title for a major release.
+Merging the release pull request creates the matching GitHub release. The
+workflow publishes that version when it is missing from npm, so rerunning a
+failed publish is safe.
+
+Repository rules for `main` must require `Validate Conventional Commit title`.
+Enable this requirement after the title workflow first lands on `main`.
+
+The `npm` GitHub environment must exist, and npm trusted publishing must
+authorize:
+
+- Repository: `unrelentingfox/pi-async-bash`
+- Workflow: `release.yml`
+- Environment: `npm`
+
+Confirm each release in the GitHub Actions Release run and on npm.

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "pi-async-bash",
+  "version": "0.1.0",
+  "description": "Asynchronous Bash tools for Pi: foreground Bash handoff, async jobs, event watches, and task management.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "async",
+    "bash",
+    "background-jobs",
+    "monitoring"
+  ],
+  "author": "Dustin Fox",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unrelentingfox/pi-async-bash.git"
+  },
+  "files": [
+    "src/",
+    "!src/__tests__/**",
+    "index.ts",
+    "README.md",
+    "RELEASING.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test --test-force-exit 'src/__tests__/*.test.ts' 'src/__tests__/*.test.mjs'",
+    "typecheck": "tsc --noEmit",
+    "check:pack": "node scripts/check-pack.mjs",
+    "check": "pnpm test && pnpm run typecheck && pnpm run check:pack"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.79.0",
+    "@earendil-works/pi-ai": ">=0.79.0",
+    "@earendil-works/pi-coding-agent": ">=0.79.0",
+    "@earendil-works/pi-tui": ">=0.79.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.83.0",
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-tui": "^0.83.0",
+    "@types/node": "25.6.2",
+    "typebox": "^1.3.30",
+    "typescript": "6.0.3"
+  },
+  "packageManager": "pnpm@10.33.1",
+  "bugs": {
+    "url": "https://github.com/unrelentingfox/pi-async-bash/issues"
+  },
+  "homepage": "https://github.com/unrelentingfox/pi-async-bash#readme",
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/commands.ts

@@ -0,0 +1,23 @@
+/** Async Bash slash commands. */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { BackgroundRegistry } from "./state.ts";
+import { takeControl, type ControlContext } from "./lifecycle.ts";
+import { openBgListPanel } from "./ui.ts";
+
+/** Register async handoff and task-list commands. */
+export function registerCommands(pi: ExtensionAPI, reg: BackgroundRegistry): void {
+    pi.registerCommand("bash-async", {
+        description: "Run the active Bash command asynchronously and return control to the agent",
+        handler: async (_args, ctx) => {
+            takeControl(reg, ctx as unknown as ControlContext);
+        },
+    });
+
+    pi.registerCommand("bash-async-list", {
+        description: "Open the interactive asynchronous Bash task manager",
+        handler: async (_args, ctx: ExtensionCommandContext) => {
+            await openBgListPanel(reg, ctx);
+        },
+    });
+}

package/src/format.ts

@@ -0,0 +1,78 @@
+/**
+ * Formatting helpers — duration strings, status pills, output tails.
+ * The <task-notification> builder lives in src/notify.ts; this module is
+ * the primitives layer that the rest of the codebase shares.
+ */
+import type { Job } from "./types.ts";
+import { PREVIEW_CHARS } from "./types.ts";
+
+/** The standard short label for a job: its name, or its id when unnamed. */
+export function jobLabel(job: Job): string {
+    return job.name ?? job.id;
+}
+
+/** Collapse all whitespace runs to single spaces — one-line rendering. */
+export function oneLine(s: string): string {
+    return s.replace(/\s+/g, " ").trim();
+}
+
+/** Human/agent prose label: the name when set, else the command collapsed to
+ *  one line and truncated. (jobLabel = name ?? id for registry lookups;
+ *  describeJob = name ?? one-line command for prose.) */
+export function describeJob(name: string | undefined, command: string): string {
+    if (name) return name;
+    const line = oneLine(command);
+    return line.length > 80 ? `${line.slice(0, 80)}…` : line;
+}
+
+/** "1m23s" / "45s" / "0s" — short human-readable duration. */
+export function formatDuration(ms: number): string {
+    const totalSecs = Math.floor(ms / 1000);
+    const mins = Math.floor(totalSecs / 60);
+    const secs = totalSecs % 60;
+    return mins > 0 ? `${mins}m${secs}s` : `${secs}s`;
+}
+
+/** Human-readable status pill, including duration for running jobs. */
+export function statusLabel(job: Job, duration?: string): string {
+    const dur = duration ?? formatDuration(Date.now() - job.startTime);
+    switch (job.status) {
+        case "pending":
+            return "◌ pending";
+        case "running":
+            if (job.kind === "monitor") return `◉ monitor (${dur})`;
+            return job.isBackgrounded ? `▶ bg (${dur})` : `▶ fg (${dur})`;
+        case "completed":
+            return "✓ completed";
+        case "failed":
+            return "✗ failed";
+        case "killed":
+            return "✗ killed";
+    }
+}
+
+/** "b7f3k9a2x1 [shell]: ls -la (last 80 chars)" — single line for `bash_async_list list`.
+ *  Every line carries the kind tag (shell/agent/monitor) so the unified list
+ *  shows what each task is. */
+export function formatJobLine(job: Job): string {
+    const head = job.name ? `${job.name} (${job.id})` : job.id;
+    const kind = job.kind ?? "shell";
+    const duration =
+        job.status === "running"
+            ? ` (${formatDuration(Date.now() - job.startTime)})`
+            : "";
+    return `${head} [${kind}]: ${job.command.slice(0, PREVIEW_CHARS.line)} - ${statusLabel(job)}${duration}`;
+}
+
+/** Truncate a tail with a consistent "showing last N chars" marker. */
+export function truncateTail(content: string, maxChars: number): string {
+    if (content.length <= maxChars) return content;
+    return `...[truncated, showing last ${maxChars} chars]\n${content.slice(-maxChars)}`;
+}
+
+/** Text content block builder — shared across all tools. The explicit return
+ *  type documents the shared contract for the five tool call sites that
+ *  import this — they rely on the literal shape, not inference. */
+export function textBlock(s: string): { type: "text"; text: string } {
+    return { type: "text" as const, text: s };
+}

package/src/hint.ts

@@ -0,0 +1,37 @@
+/**
+ * Live "(/bash-async to run asynchronously)" hint shown below the editor while
+ * a foreground bash command is running — mirrors Claude Code's BackgroundHint,
+ * which appears once a command has run past the quick-completion window.
+ */
+
+import type { UiContext } from "./types.ts";
+
+const HINT_KEY = "bg-hint";
+
+/**
+ * Ref-count of foreground commands currently showing the hint. The widget is a
+ * single shared key, but bash commands run in parallel — so we only render it on
+ * the 0→1 transition and clear it on the last 1→0, keeping the hint up as long
+ * as any foreground command is still running. Each caller must pair exactly one
+ * showBackgroundHint() with one clearBackgroundHint().
+ */
+let activeHints = 0;
+
+/** Show the async handoff hint below the editor (idempotent across parallel commands). */
+export function showBackgroundHint(ctx: UiContext): void {
+    activeHints++;
+    if (activeHints === 1) {
+        ctx.ui.setWidget(HINT_KEY, ["(/bash-async to run asynchronously)"], {
+            placement: "belowEditor",
+        });
+    }
+}
+
+/** Release one hint; clears the widget only when the last command is done. */
+export function clearBackgroundHint(ctx: UiContext): void {
+    if (activeHints === 0) return;
+    activeHints--;
+    if (activeHints === 0) {
+        ctx.ui.setWidget(HINT_KEY, undefined);
+    }
+}

package/src/index.ts

@@ -0,0 +1,91 @@
+/**
+ * pi-async-bash — asynchronous Bash execution for the Pi agent.
+ *
+ * Registers `bash`, `bash_async`, `bash_async_list`, `bash_async_watch`, and
+ * `bash_async_decide`, plus `/bash-async` and `/bash-async-list`.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createBashToolDefinition } from "@earendil-works/pi-coding-agent";
+import { BackgroundRegistry } from "./state.ts";
+import { cleanupStaleRuntimeArtifacts, detectNonInteractive, reviveAndValidate, serializeJobs, terminateJobSilently } from "./lifecycle.ts";
+import { stopSidebarTicker } from "./registry.ts";
+import { EVENT } from "./types.ts";
+import { registerBashTool } from "./tools/bash.ts";
+import { registerBashBgTool } from "./tools/bash-bg.ts";
+import { registerJobsTool } from "./tools/jobs.ts";
+import { registerMonitorTool } from "./tools/monitor.ts";
+import { registerCommands } from "./commands.ts";
+import { registerJobDecideTool } from "./tools/job-decide.ts";
+import { registerInputHandlers } from "./input.ts";
+
+/** Extension entry point. */
+export default function (pi: ExtensionAPI): void {
+    const reg = new BackgroundRegistry();
+
+    // ── Tool registration ─────────────────────────────────────────
+    // Use the unwrapped tool *definition* so the override inherits Pi's native
+    // bash renderCall/renderResult (createBashTool returns a wrapped AgentTool
+    // that drops them).
+    const originalBash = createBashToolDefinition(process.cwd());
+    registerBashTool(pi, reg, originalBash);
+    registerBashBgTool(pi, reg);
+    registerJobsTool(pi, reg);
+    registerMonitorTool(pi, reg);
+    registerJobDecideTool(pi, reg);
+
+    // ── Commands and cooperative steering ─────────────────────────
+    registerCommands(pi, reg);
+    registerInputHandlers(pi, reg);
+
+    // ── Message rendering ─────────────────────────────────────────
+    // <task-notification> messages render as one colored line: green for
+    // completed, red for failed, yellow for killed and for the statusless
+    // stall warning (CC's unread/attention color).
+    const renderTaskNotification = (
+        message: { content: unknown; details?: unknown },
+        theme: { fg(colour: string, text: string): string }
+    ) => {
+        const details = message.details as
+            | { status?: string; summary?: string }
+            | undefined;
+        const colour =
+            details?.status === "completed"
+                ? "success"
+                : details?.status === "failed"
+                  ? "error"
+                  : "warning";
+        const line = theme.fg(colour, `● ${details?.summary ?? String(message.content)}`);
+        return { render: () => [line], invalidate: () => {} };
+    };
+    pi.registerMessageRenderer(EVENT.taskNotification, (message, _options, theme) =>
+        renderTaskNotification(message, theme)
+    );
+    pi.registerMessageRenderer(EVENT.stall, (message, _options, theme) =>
+        renderTaskNotification(message, theme)
+    );
+
+    // Restore only jobs that belong to this Pi process. This preserves async
+    // work through `/reload` but refuses to signal reused PIDs after restart.
+    pi.on("session_start", async (_event, ctx) => {
+        reg.nonInteractive = detectNonInteractive(process.argv, Boolean(process.stdin.isTTY));
+        const entries = ctx.sessionManager.getEntries();
+        const state = [...entries].reverse().find((entry) =>
+            entry.type === "custom" && entry.customType === "pi-async-bash-state"
+        ) as { type: "custom"; data?: { jobs?: Array<import("./types.ts").Job> } } | undefined;
+        for (const job of state?.data?.jobs ?? []) {
+            if (reviveAndValidate(job) === "alive") reg.jobs.set(job.id, job);
+        }
+        void cleanupStaleRuntimeArtifacts();
+    });
+
+    pi.on("session_shutdown", async (event, _ctx) => {
+        stopSidebarTicker(reg);
+        if (event.reason === "quit") {
+            for (const job of reg.jobs.values()) {
+                if (job.status === "running") terminateJobSilently(reg, job);
+            }
+        }
+        pi.appendEntry("pi-async-bash-state", { jobs: serializeJobs(reg.jobs.values()) });
+    });
+}

package/src/input.ts

@@ -0,0 +1,35 @@
+// src/input.ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { BackgroundRegistry } from "./state.ts";
+import type { UiContext } from "./types.ts";
+import { backgroundActiveForeground } from "./lifecycle.ts";
+
+export function registerInputHandlers(pi: ExtensionAPI, reg: BackgroundRegistry): void {
+    pi.on("input", async (event, ctx) => {
+        // Cooperative steering (Claude Code parity): ANY input typed while a
+        // foreground bash command is running backgrounds that command and
+        // re-delivers the input as the next turn — regardless of the message's
+        // steer/followUp streamingBehavior. We only intercept when a foreground
+        // slot is active; everything else falls through to Pi.
+        if (reg.foreground.size === 0) return { action: "continue" };
+        // Don't intercept extension-sourced messages.
+        if (event.source === "extension") return { action: "continue" };
+
+        const text = event.text;
+        const bg = backgroundActiveForeground(reg, ctx as UiContext);
+        if (!bg) return { action: "continue" };
+
+        // Abort the current turn so the bash tool returns the "backgrounded" result.
+        ctx.abort?.();
+
+        // Resubmit the user's message as a follow-up — Pi delivers it
+        // after the current turn settles. No polling needed.
+        try {
+            pi.sendUserMessage(text, { deliverAs: "followUp" });
+        } catch {
+            // Session ended between abort and resubmit — nothing to deliver to.
+        }
+
+        return { action: "handled" };
+    });
+}