@aliou/pi-processes 0.9.5 → 0.10.0

package/CONTRIBUTING.md

@@ -8,6 +8,11 @@ Keep development details, testing notes, internal tool guidance, and docs build
 
 ## Development
 
+Requirements:
+
+- Node.js `22.19.0` or newer
+- pnpm `10.26.1`
+
 Install dependencies:
 
 ```bash
@@ -17,20 +22,34 @@ pnpm install
 Run checks:
 
 ```bash
-pnpm lint
 pnpm typecheck
+pnpm lint
+pnpm test
+pnpm test:e2e
 ```
 
 ## Repository layout
 
-- `src/` - extension source
-- `src/tools/` - `process` tool and actions
-- `src/commands/` - `/ps` commands and settings UI
-- `src/hooks/` - lifecycle hooks, blocker, message rendering, widgets
-- `src/components/` - TUI components
+- `src/` - Pi-agnostic process management, types, protocol, and utilities
+- `extensions/processes/` - core extension, process tool (start, list, output, update, write, stop, clear), settings, lifecycle hooks, notifications, protocol handlers, `/ps`, `/ps:kill`, `/ps:clear`, and `/ps:settings`
+- `extensions/processes-logs/` - `/ps:logs` command and log overlay
+- `extensions/processes-dock/` - `/ps:dock`, `/ps:pin`, the dock widget, and the status widget
+- `extensions/shared/` - shared UI helpers (`statusDot`, `processStatusTone`, `LineComponent`, etc.) used across all three extensions
 - `skills/` - shipped package skills
 - `.agents/skills/` - local repo-only skills for development workflows
-- `.github/docs-site/` - isolated docs page build
+
+## Package metadata
+
+The package targets Pi `0.80.3`.
+
+Pi bundles core packages for extensions. Keep direct imports of these packages in `peerDependencies` with `"*"` ranges and exact local versions in `devDependencies`:
+
+- `@earendil-works/pi-ai`
+- `@earendil-works/pi-coding-agent`
+- `@earendil-works/pi-tui`
+- `typebox`
+
+Keep normal third-party runtime dependencies in `dependencies`.
 
 ## Internal behavior
 
@@ -58,15 +77,17 @@ pnpm lint
 pnpm typecheck
 ```
 
-Useful manual process scripts:
+Useful manual process scripts live under `tests/e2e/scripts/`:
 
 ```bash
-./test/test-output.sh
-./test/test-exit-success.sh 5
-./test/test-exit-failure.sh 5
-./test/test-exit-crash.sh 5
+./tests/e2e/scripts/continuous-output.sh   # long-running stdout
+./tests/e2e/scripts/error-log.sh            # interleaved info/error on stdout+stderr
+./tests/e2e/scripts/exited-task.sh          # finite, exits 0
+./tests/e2e/scripts/crash-on-file.sh <name>  # waits for a marker file then crashes
 ```
 
+See `.agents/skills/pi-processes-testing/SKILL.md` for the full manual QA workflow and the complete fixture script reference.
+
 ## Docs conventions
 
 ### README
@@ -86,38 +107,15 @@ Avoid putting these in `README.md`:
 - detailed tool-call schemas
 - release workflow notes
 
-### Video placeholders
-
-Use HTML comments in `README.md`:
-
-```md
-<!-- VIDEO: {"id":"process-panel","title":"Browse and manage processes from the panel"} -->
-```
-
-GitHub ignores these comments. The docs page build turns them into video blocks.
-
-Add one placeholder for each feature section.
-
-## Docs page build
-
-The generated docs page lives under `.github/docs-site/` and is isolated from the extension source.
-
-It reads `README.md`, converts markdown into structured content, replaces video placeholders, highlights code with Shiki, and builds a static page with Vite and Tailwind.
-
-The GitHub Actions workflow for this lives in `.github/workflows/docs-page.yml`.
+### Docs page build
 
-## Demo pattern
+The docs page is generated from `README.md` by an external build, not in this repo. Keep `README.md` self-contained with only standard markdown.
 
-For demo recording, use a small self-contained project with a realistic workflow.
+## Future design notes
 
-The best pattern used for this extension was a fake Northwind API project where Pi:
+Unimplemented design notes live in `docs/`:
 
-1. starts a server in the background
-2. runs tests and sees failures
-3. runs migrations
-4. checks server logs
-5. updates seed data
-6. reruns tests
-7. cleans up the process
+- `docs/future-cleanup-hooks.md` - planned `cleanup` support for `process start` / `process stop`
+- `docs/future-persistent-manager.md` - planned cross-session process persistence
 
-That pattern shows why background processes matter in a normal task instead of showing features one by one.
+These describe intended future behavior, not current behavior. Active implementation work goes under `.agents/plans/`.

package/README.md

@@ -1,4 +1,4 @@
-![banner](https://assets.aliou.me/github/aliou/pi-processes/banner.png)
+![banner](https://assets.aliou.me/github/aliou/pi-processes/banner-v0.10.x.png)
 
 # pi-processes
 
@@ -10,6 +10,8 @@ This extension lets Pi keep long-running commands alive while the conversation c
 
 When a task needs a long-running command, Pi can start it in the background by itself and keep helping with the rest of the work.
 
+[![Pi starts a long-running process and keeps working](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/agent-starts-processes.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/agent-starts-processes.mp4)
+
 That means Pi can, for example:
 
 - start a dev server and keep coding
@@ -17,9 +19,7 @@ That means Pi can, for example:
 - run a local API while it inspects logs
 - watch build output without blocking the conversation
 
-You can then inspect, pin, or stop those processes from the UI.
-
-<!-- VIDEO: {"id":"agent-starts-processes","title":"Pi starts a long-running process and keeps working"} -->
+You can then inspect, pin, stop, or clear those processes from the UI.
 
 ## Installation
 
@@ -35,9 +35,19 @@ From git:
 pi install git:github.com/aliou/pi-processes
 ```
 
+## How Pi stays in the loop
+
+Pi does not wait around for a background process. After it starts one, it keeps helping with the rest of the work and gets brought back automatically when something happens:
+
+- a readiness marker appears in the logs (a server prints "ready")
+- an error appears in the logs (a build prints a type error)
+- the process exits, whether it succeeded, failed, or was killed
+
+That is how Pi can start a dev server and then keep coding, or run a test watcher and react when a test fails, without sleeping or polling. If a watch fires too often, Pi can quiet it without restarting the process.
+
 ## Open the process panel
 
-Use `/ps` to open the main process panel.
+Use `/ps` to open the main process panel. It shows running and finished processes, with the most recent output preview. The preview opens on the newest page so you can see live activity without scrolling.
 
 From there you can:
 
@@ -47,53 +57,45 @@ From there you can:
 - kill a running process
 - clear finished entries
 
-Keys:
-
-- `j/k` or arrow keys: move selection
-- `J/K`: scroll preview
-- `enter`: pin selected process to the dock
-- `x`: kill selected process
-- `c`: clear finished processes
-- `q` or `esc`: close
-
-<!-- VIDEO: {"id":"process-panel","title":"Browse and manage processes from the panel"} -->
-
 ## Inspect logs
 
-Use `/ps:logs [id|name]` to open the log overlay for one process.
+Use `/ps:logs [id]` to open the log overlay for one process. The viewer is cached per process, so switching tabs preserves scroll position and follow mode.
 
 This is useful when Pi started a server, watcher, or local API and you want to follow what it is doing in more detail.
 
-Keys:
+## Control the dock
 
-- `tab` / `shift+tab`: switch process tabs
-- `g/G`: jump to top or bottom
-- `j/k` or arrow keys: scroll
-- `s`: switch between combined, stdout, and stderr
-- `f`: toggle follow mode
-- `/`: search
-- `n/N`: move between search matches
-- `q` or `esc`: close
+Use `/ps:dock [expand|collapse|close]` to control dock visibility.
 
-<!-- VIDEO: {"id":"inspect-logs","title":"Open the log overlay and inspect output"} -->
+The dock gives you a compact live view without leaving the conversation.
 
 ## Pin one process
 
-Use `/ps:pin [id|name]` to keep the dock focused on one process.
+Use `/ps:pin [id]` to keep the dock focused on one process.
 
 This is useful when one process matters more than the others, such as a dev server or a test watcher.
 
 Without arguments, Pi shows a picker.
 
-<!-- VIDEO: {"id":"pin-process","title":"Pin the dock to one process"} -->
+## Stop and clear processes
 
-## Control the dock
+Use `/ps:kill [id]` to stop a running process, and `/ps:clear` to remove finished entries from the panel and free their log storage.
 
-Use `/ps:dock [show|hide|toggle]` to control dock visibility.
+`/ps:kill` waits for the process to actually exit (or time out), so the result it reports reflects what happened. Without arguments, Pi shows a picker.
 
-The dock gives you a compact live view without leaving the conversation.
+`/ps:clear` never touches live processes.
+
+## Keep a status line in view
+
+Enable the status widget in `/ps:settings` to show a compact line of running processes below the editor. Each process shows a status dot, its name, and its state, with `+N more` overflow when the line does not fit.
 
-<!-- VIDEO: {"id":"dock-control","title":"Show, hide, and use the dock"} -->
+It is disabled by default. The widget reflows on resize and clears itself when the process list is empty.
+
+## Send input to a process
+
+Use the `process` tool with `action: "write"` to send bytes to a running process's stdin. This is how you drive interactive servers, REPLs, and CLIs that expect input after they start.
+
+Pass `input` for the bytes to write, and set `end: true` to close stdin (for example to signal EOF to a waiting process).
 
 ## Adjust settings
 
@@ -106,78 +108,46 @@ Available settings include:
 - shell path override
 - dock defaults
 - follow mode behavior
+- status widget toggle
 - optional background command interception
 
-<!-- VIDEO: {"id":"settings","title":"Adjust process extension settings"} -->
-
 ## Platform support
 
 - macOS: supported
 - Linux: supported
 - Windows: not supported
 
-## Runtime log watch alerts
+## Troubleshooting
 
-Use `process` tool `start` with `logWatches` to trigger immediate alerts while the process is still running.
+### Pi started something and I want to see more output
 
-- default behavior: each watch fires once (`repeat: false`)
-- set `repeat: true` to trigger on every match
-- scope by stream (`stdout`, `stderr`, `both`) to reduce noise
+Open `/ps` for a quick overview, or use `/ps:logs` for full logs.
 
-Example: server ready marker (one-time default)
+### I want one process to stay visible
 
-```json
-{
-  "action": "start",
-  "name": "dev-server",
-  "command": "pnpm dev",
-  "logWatches": [
-    { "pattern": "ready on http://localhost:3000" }
-  ]
-}
-```
+Use `/ps:pin` to focus the dock on that process.
 
-Example: error marker from stderr
-
-```json
-{
-  "action": "start",
-  "name": "builder",
-  "command": "pnpm build --watch",
-  "logWatches": [
-    { "pattern": "TypeError|ReferenceError", "stream": "stderr" }
-  ]
-}
-```
+### I want Pi to avoid shell background tricks
 
-Example: repeatable watch on stdout only
-
-```json
-{
-  "action": "start",
-  "name": "worker",
-  "command": "pnpm worker",
-  "logWatches": [
-    { "pattern": "job completed", "stream": "stdout", "repeat": true }
-  ]
-}
-```
+Enable background command interception in `/ps:settings`. When enabled, Pi avoids normal shell background patterns and uses the process workflow instead.
 
-Invalid regex patterns fail fast at process start with a clear error.
+## Feature demos
 
-## Troubleshooting
+**Watch a file-backed log and recover from an error**
 
-### Pi started something and I want to see more output
+[![Watch a file-backed log and recover from an error](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/debug-from-log.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/debug-from-log.mp4)
 
-Open `/ps` for a quick overview, or use `/ps:logs` for full logs.
+**Open the log overlay and inspect output**
 
-### I want one process to stay visible
+[![Open the log overlay and inspect output](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/inspect-logs.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/inspect-logs.mp4)
 
-Use `/ps:pin` to focus the dock on that process.
+**Stop and clear processes**
 
-### I want Pi to avoid shell background tricks
+[![Stop and clear processes](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/stop-and-clear.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/stop-and-clear.mp4)
 
-Enable background command interception in `/ps:settings`. When enabled, Pi avoids normal shell background patterns and uses the process workflow instead.
+**Send input to a running process**
+
+[![Send input to a running process](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/send-input.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/send-input.mp4)
 
 ## Contributing
 
@@ -185,4 +155,4 @@ For development, testing, docs generation, and extension internals, see [CONTRIB
 
 ## License
 
-MIT
+MIT

package/extensions/process-tabs.ts

@@ -0,0 +1,26 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import type { ProcessInfo } from "../src/types";
+import { truncateCmd } from "../src/utils/format";
+import { MAX_TAB_NAME, statusDot } from "./shared/ui";
+
+export { MAX_TAB_NAME, statusDot as renderProcessTabDot };
+
+/**
+ * Render a process tab: ` dot label ` with active highlight.
+ *
+ * Truncates the name to `MAX_TAB_NAME` without padding, so tabs stay compact
+ * (`● api` not `● api         `). The active tab is rendered on a selected
+ * background; inactive tabs use a dim label.
+ */
+export function renderProcessTab(
+  process: ProcessInfo,
+  active: boolean,
+  theme: Theme,
+): string {
+  const dot = statusDot(process, active, theme);
+  const label = truncateCmd(process.name, MAX_TAB_NAME);
+  return active
+    ? theme.bg("selectedBg", ` ${dot} ${theme.fg("accent", label)} `)
+    : ` ${dot} ${theme.fg("dim", label)} `;
+}

package/extensions/processes/client.ts

@@ -0,0 +1,194 @@
+/**
+ * Core-extension request/command helpers for the `/ps` overview panel.
+ *
+ * The overview panel prefers the existing `pi.events` protocol channels over
+ * calling the manager directly so a future split-out of the panel stays cheap.
+ * These helpers are the core equivalent of `extensions/processes-logs/client.ts`
+ * and `extensions/processes-dock/client.ts`.
+ */
+
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+import {
+  CHANNELS,
+  type CommandClearPayload,
+  type CommandKillPayload,
+  type CommandPinPayload,
+  type CommandPinResult,
+  type ProcessProtocolConfig,
+  type RequestCombinedOutputPayload,
+  type RequestConfigPayload,
+  type RequestGetPayload,
+  type RequestListPayload,
+} from "../../src/protocol";
+import type { KillResult, ProcessInfo } from "../../src/types";
+
+export type ProcessLogLine = { type: "stdout" | "stderr"; text: string };
+
+export function requestProcessList(events: EventBus): ProcessInfo[] {
+  let processes: ProcessInfo[] = [];
+  const payload: RequestListPayload = {
+    reply: (result) => {
+      processes = result;
+    },
+  };
+  events.emit(CHANNELS.REQUEST_LIST, payload);
+  return processes;
+}
+
+export function requestProcess(
+  events: EventBus,
+  id: string,
+): ProcessInfo | null {
+  let process: ProcessInfo | null = null;
+  const payload: RequestGetPayload = {
+    id,
+    reply: (result) => {
+      process = result;
+    },
+  };
+  events.emit(CHANNELS.REQUEST_GET, payload);
+  return process;
+}
+
+export function requestConfig(events: EventBus): ProcessProtocolConfig {
+  let config: ProcessProtocolConfig | null = null;
+  const payload: RequestConfigPayload = {
+    reply: (result) => {
+      config = result;
+    },
+  };
+  events.emit(CHANNELS.REQUEST_CONFIG, payload);
+  if (!config) {
+    throw new Error("processes core extension did not reply to config request");
+  }
+  return config;
+}
+
+export function requestCombinedOutput(
+  events: EventBus,
+  id: string,
+  tailLines?: number,
+): ProcessLogLine[] {
+  let lines: ProcessLogLine[] | null = null;
+  const payload: RequestCombinedOutputPayload = {
+    id,
+    tailLines,
+    reply: (result) => {
+      lines = result;
+    },
+  };
+  events.emit(CHANNELS.REQUEST_COMBINED_OUTPUT, payload);
+  return lines ?? [];
+}
+
+/**
+ * Kill a managed process. Resolves when the kill handler replies, or with a
+ * timeout error result if no listener responds.
+ *
+ * The kill handler runs `killIntentionally` asynchronously, so its reply fires
+ * on a later microtask rather than during the emit. That is why this returns a
+ * Promise (unlike the synchronous `requestClear`/`requestProcessList`): a
+ * synchronous read of `result` would always miss the reply and report failure.
+ *
+ * The safety timeout defaults to the kill timeout plus headroom so a successful
+ * slow kill still resolves first. The timer is unref'd so it never keeps the
+ * event loop alive.
+ */
+export function requestKill(
+  events: EventBus,
+  id: string,
+  options?: { signal?: NodeJS.Signals; timeoutMs?: number },
+): Promise<KillResult> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const killTimeoutMs = options?.timeoutMs ?? 3000;
+    const payload: CommandKillPayload = {
+      id,
+      signal: options?.signal,
+      timeoutMs: killTimeoutMs,
+      reply: (result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(result);
+      },
+    };
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      resolve(killTimeoutResult(id));
+    }, killTimeoutMs + 2000);
+    // Unref so a parked timer never keeps the event loop alive.
+    timer.unref?.();
+    events.emit(CHANNELS.COMMAND_KILL, payload);
+  });
+}
+
+function killTimeoutResult(id: string): KillResult {
+  return {
+    ok: false,
+    reason: "error",
+    info: {
+      id,
+      name: "(unknown)",
+      pid: -1,
+      command: "",
+      cwd: "",
+      startTime: 0,
+      endTime: null,
+      status: "exited",
+      exitCode: null,
+      success: false,
+      stdoutFile: "",
+      stderrFile: "",
+      endReason: null,
+      signal: null,
+      errorMessage: "No kill handler replied",
+    },
+  };
+}
+
+export function requestClear(events: EventBus): number {
+  let cleared = 0;
+  const payload: CommandClearPayload = {
+    reply: (value) => {
+      cleared = value;
+    },
+  };
+  events.emit(CHANNELS.COMMAND_CLEAR, payload);
+  return cleared;
+}
+
+/**
+ * Pin a process to the dock. Resolves when the dock extension replies, or
+ * rejects if no dock handler responds within `timeoutMs`.
+ *
+ * The dock extension must be loaded for this to succeed. If it is not
+ * registered, no listener will reply and the promise rejects with a timeout.
+ */
+export function requestPin(
+  events: EventBus,
+  id: string | null,
+  timeoutMs = 200,
+): Promise<CommandPinResult> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const payload: CommandPinPayload = {
+      id,
+      reply: (result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(result);
+      },
+    };
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      resolve({ ok: false, error: "Dock extension is not available" });
+    }, timeoutMs);
+    // The timeout needs to be unref'd so it never keeps the event loop alive.
+    timer.unref?.();
+    events.emit(CHANNELS.COMMAND_PIN, payload);
+  });
+}

package/extensions/processes/commands/clear.ts

@@ -0,0 +1,29 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { requestClear } from "../client";
+
+/**
+ * Register `/ps:clear`.
+ *
+ * Removes finished processes from the list via the clear protocol channel,
+ * mirroring main's behavior. Returns the count of cleared processes.
+ */
+export function registerClearCommand(pi: ExtensionAPI): void {
+  const events = pi.events;
+  pi.registerCommand("ps:clear", {
+    description: "Remove finished processes from the list.",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      const cleared = requestClear(events);
+      if (cleared === 0) {
+        ctx.ui.notify("No finished processes to clear.", "info");
+        return;
+      }
+      ctx.ui.notify(
+        `Cleared ${cleared} finished process${cleared === 1 ? "" : "es"}.`,
+        "info",
+      );
+    },
+  });
+}