@haemmid/pi-processes 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning for public releases.
+
+## [0.9.0] - 2026-07-01
+
+Initial public release of `@haemmid/pi-processes`.
+
+### Added
+
+- Agent-facing `process` tool for Pi and pi-web automation workflows.
+- Managed process actions:
+  - `start`
+  - `restart`
+  - `list`
+  - `output`
+  - `logs`
+  - `kill`
+  - `clear`
+- File-backed stdout/stderr/combined logs.
+- Stable process names for dev-server workflows.
+- Duplicate running-name protection before spawning a process.
+- Dedicated safe `restart` action: await kill, then start.
+- `cwd` support for `start` and `restart`.
+- Background-command interception for fragile shell patterns:
+  - `&`
+  - `nohup`
+  - `disown`
+  - `setsid`
+  - `npm run dev`
+  - `pnpm dev`
+  - `yarn dev`
+  - `bun run dev`
+  - `npx vite`
+  - `npx astro dev`
+  - `docker compose up`
+  - `tail -f`
+  - `kubectl port-forward`
+- Session cleanup for managed processes.
+
+### Changed
+
+- Repositioned the package as a plain-text process manager for Pi/pi-web automation.
+- Simplified the original process-management workflow for agent use.
+- README now focuses on dev-server automation, especially Astro/Vite workflows.
+- Process name resolution now prioritizes live processes over old finished duplicates.
+
+### Removed
+
+- TUI widgets and overlays.
+- `/ps` overlay workflow.
+- Status widgets.
+- Rich TUI rendering in tool output.
+- Auto-notification claims after process exit.
+- Unneeded TUI dependencies.
+
+### Notes
+
+This package started as a fork of `mjakl/pi-processes`, which was based on `aliou/pi-processes`.
+
+This release focuses on a narrower use case: reliable, plain-text, agent-facing process management for automated Pi and pi-web coding workflows.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 haemmid
+
+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,233 @@
+# ⚙️ pi-processes
+
+> Agent-facing process manager for Pi and pi-web automation workflows.
+
+`pi-processes` lets the agent start, inspect, restart, and stop long-running commands through a managed `process` tool instead of fragile shell backgrounding.
+
+Designed for use with [jmfederico/pi-web](https://github.com/jmfederico/pi-web).
+
+[![npm](https://img.shields.io/npm/v/@haemmid/pi-processes)](https://www.npmjs.com/package/@haemmid/pi-processes)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/haemmid/pi-processes/v0.9.0/assets/hero.svg" alt="pi-processes managed process workflow" width="760">
+</p>
+
+## Why
+
+Agents often waste time or break sessions by running:
+
+- `npm run dev &`
+- `nohup pnpm dev ...`
+- `pkill -f vite`
+- repeated `timeout 10 npm run dev`
+
+This package gives the agent a stable process lifecycle instead:
+
+- `process start`
+- `process list`
+- `process output`
+- `process restart`
+- `process kill`
+
+## Table of Contents
+
+- [Features](#features)
+- [Install](#install)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Tool API](#tool-api)
+- [Killing processes](#killing-processes)
+- [Limitations](#limitations)
+- [Development](#development)
+- [Acknowledgements](#acknowledgements)
+- [Changelog](#changelog)
+- [License](#license)
+
+## Features
+
+- **Agent-facing `process` tool** — start, list, kill, get output, get log paths, and clear managed processes.
+- **File-backed logs** — process output is preserved in temp files outside the agent context window.
+- **Background-command interception** — optional guardrails steer the agent away from shell backgrounding, `nohup`, and obvious long-running foreground commands, and toward the `process` tool.
+- **Session cleanup** — managed processes are terminated when the session shuts down.
+- **Duplicate name protection** — refuses to spawn if a live process with the same name already exists.
+- **Dedicated `restart` action** — safely awaits kill before starting a new process.
+
+## Install
+
+Install from npm:
+
+```bash
+pi install npm:@haemmid/pi-processes
+```
+
+Install from git:
+
+```bash
+pi install git:github.com/haemmid/pi-processes
+```
+
+Or install from a local checkout:
+
+```bash
+pi install /path/to/pi-processes
+```
+
+## Usage
+
+The `process` tool is for the agent, not for direct user input. Ask the agent to start or inspect long-running work.
+
+Example user prompts:
+
+```text
+Start the dev server with pnpm dev and call it backend-dev.
+Show me the latest output from backend-dev.
+Stop the backend-dev process.
+```
+
+The agent should start managed processes through the `process` tool instead of running shell backgrounding such as `command &`, `nohup`, `disown`, or `setsid`.
+
+## Astro / Vite workflow
+
+For Astro/Vite dev servers, ask the agent:
+
+```text
+Use the process tool for the Astro dev server.
+Start `npm run dev -- --host 0.0.0.0` as `my-site:astro`.
+Use `process output` when you need logs.
+Do not restart after ordinary .astro, .ts, or .css edits.
+Restart only after package/config/env changes or if the server exits.
+```
+
+Typical tool flow:
+
+```text
+process list
+process start "npm run dev -- --host 0.0.0.0" name="my-site:astro"
+process output id="my-site:astro"
+process restart "npm run dev -- --host 0.0.0.0" name="my-site:astro"
+process kill id="my-site:astro"
+```
+
+## Demo
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/haemmid/pi-processes/v0.9.0/assets/demo-pi-web.gif" alt="pi-processes demo in pi-web" width="760">
+</p>
+
+## Configuration
+
+Global config lives in:
+
+```text
+~/.pi/agent/extensions/process.json
+```
+
+Example:
+
+```json
+{
+  "output": {
+    "defaultTailLines": 100,
+    "maxOutputLines": 200
+  },
+  "execution": {
+    "shellPath": "/absolute/path/to/bash"
+  },
+  "interception": {
+    "blockBackgroundCommands": true
+  }
+}
+```
+
+Options:
+
+- `output.defaultTailLines` — default number of lines returned by `process output`.
+- `output.maxOutputLines` — hard cap for `process output`.
+- `execution.shellPath` — absolute shell path override used for process startup.
+- `interception.blockBackgroundCommands` — block shell backgrounding and obvious long-running foreground commands such as `pnpm dev`, `docker compose up`, `tail -f`, or `kubectl port-forward`, and guide the agent to use the `process` tool instead.
+
+## Tool API
+
+The tool is named `process`.
+
+### Actions
+
+| Action | Description |
+|--------|-------------|
+| `start` | Start a managed process. |
+| `restart` | Kill existing process and start a new one (safe: await kill → start). |
+| `list` | List managed processes. |
+| `output` | Return a one-off tailed stdout/stderr snapshot. |
+| `logs` | Return file paths for stdout, stderr, and combined logs. |
+| `kill` | Terminate or force-kill a process. |
+| `clear` | Remove finished processes from the manager. |
+
+### Tool-call examples
+
+```text
+process start "pnpm dev" name="backend-dev"
+process start "pnpm test --watch" name="tests"
+process start "pnpm dev" name="backend-dev" cwd="/path/to/project"
+process restart "pnpm dev" name="backend-dev"
+process restart "pnpm dev" name="backend-dev" force=true
+process list
+process output id="backend-dev"
+process logs id="proc_1"
+process kill id="backend-dev"
+process kill id="proc_1" force=true
+process clear
+```
+
+### Field rules
+
+- `start`/`restart` require `command` and `name`.
+- `output`, `logs`, and `kill` require `id`.
+- `kill` accepts `force=true` to send `SIGKILL` instead of `SIGTERM`.
+- `start` refuses if a process with the same name is already running.
+- `restart` safely kills the existing process (awaited) before starting a new one.
+- `restart` accepts `force=true` to send `SIGKILL` instead of `SIGTERM`.
+- `start`/`restart` accept `cwd` to override the working directory (defaults to session cwd).
+
+## Killing processes
+
+- `process kill id="..."` sends `SIGTERM`.
+- `process kill id="..." force=true` sends `SIGKILL`.
+- Tool-triggered kills never notify the agent.
+
+## Limitations
+
+- **Linux/macOS only.** The extension disables itself on Windows.
+- **Session-scoped.** Processes are cleaned up on session shutdown.
+- **Not a system service manager.** Does not persist process registry across sessions.
+- **Manages only tool-started processes.** Does not track externally started processes.
+- **No TUI widgets.** Does not provide `/ps` overlays or status widgets.
+
+## Development
+
+There are no Git hooks installed by this repository. Before committing or opening a PR, consider running:
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm test
+```
+
+After dependency changes, also verify the lockfile with:
+
+```bash
+pnpm install --frozen-lockfile --ignore-scripts
+```
+
+## Acknowledgements
+
+This package started as a fork of [`mjakl/pi-processes`](https://github.com/mjakl/pi-processes), which was based on [`aliou/pi-processes`](https://github.com/aliou/pi-processes). This fork focuses specifically on plain-text, pi-web-friendly, agent-facing process management without TUI widgets or overlays.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT

package/assets/hero.svg

@@ -0,0 +1,141 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630" role="img" aria-labelledby="title desc">
+  <title id="title">@haemmid/pi-processes workflow</title>
+  <desc id="desc">Minimal technical diagram: Pi Agent starts a process tool, which manages an Astro or Vite dev server, captures logs and output, and speeds up pi-web automation.</desc>
+
+  <defs>
+    <style>
+      .bg { fill: #f5f5f2; }
+      .halo { fill: #f0f1ee; opacity: .58; }
+      .grid { fill: none; stroke: #c9ccc5; stroke-width: 1; opacity: .45; }
+      .shell, .card { fill: #ffffff; stroke: #c9ccc5; stroke-width: 1.2; }
+      .soft, .chip { fill: #f0f1ee; stroke: #c9ccc5; stroke-width: 1.1; }
+      .arrow { fill: none; stroke: #586f61; stroke-width: 2.8; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow); }
+      .arrow2 { fill: none; stroke: #8f9891; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; marker-end: url(#arrow2); }
+      .stroke { fill: none; stroke: #8f9891; stroke-width: 2.2; stroke-linecap: round; stroke-linejoin: round; }
+      .stroke-soft { fill: none; stroke: #c9ccc5; stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
+      .dot-muted { fill: #8f9891; }
+      .dot-ok { fill: #62806c; }
+      .bolt { fill: #918156; }
+      .title-text { font: 650 22px/1.1 ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; letter-spacing: -0.03em; fill: #202427; }
+      .label { font: 520 14px/1.2 ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #6f7772; }
+      .tiny { font: 650 11px/1 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; letter-spacing: .055em; fill: #6f7772; text-transform: uppercase; }
+      .mono { font: 520 14px/1.2 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; fill: #202427; }
+      .mono2 { font: 500 13px/1.2 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; fill: #6f7772; }
+      .arrow-head { fill: #586f61; }
+      .arrow-head2 { fill: #8f9891; }
+      .accent-stroke { stroke: #586f61; }
+      .accent-dot { fill: #586f61; }
+      .accent-dot2 { fill: #7f9488; }
+
+      @media (prefers-color-scheme: dark) {
+        .bg { fill: #121416; }
+        .halo { fill: #202529; opacity: .58; }
+        .grid { stroke: #353b3b; opacity: .55; }
+        .shell, .card { fill: #191d20; stroke: #353b3b; }
+        .soft, .chip { fill: #202529; stroke: #353b3b; }
+        .arrow { stroke: #a9c8b5; }
+        .arrow2, .stroke { stroke: #6e7872; }
+        .stroke-soft { stroke: #353b3b; }
+        .dot-muted { fill: #6e7872; }
+        .dot-ok { fill: #9bc5ad; }
+        .bolt { fill: #d2c088; }
+        .title-text, .mono { fill: #edf0ed; }
+        .label, .tiny, .mono2 { fill: #a5ada8; }
+        .arrow-head { fill: #a9c8b5; }
+        .arrow-head2 { fill: #6e7872; }
+        .accent-stroke { stroke: #a9c8b5; }
+        .accent-dot { fill: #a9c8b5; }
+        .accent-dot2 { fill: #86a090; }
+      }
+    </style>
+
+    <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+      <path d="M40 0H0V40" class="grid"/>
+    </pattern>
+
+    <marker id="arrow" viewBox="0 0 10 10" refX="8.8" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M0 0 10 5 0 10z" class="arrow-head"/>
+    </marker>
+    <marker id="arrow2" viewBox="0 0 10 10" refX="8.6" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 10 5 0 10z" class="arrow-head2"/>
+    </marker>
+  </defs>
+
+  <rect width="1200" height="630" class="bg"/>
+  <rect width="1200" height="630" fill="url(#grid)"/>
+  <circle cx="600" cy="315" r="260" class="halo"/>
+  <path d="M140 488C280 416 372 505 516 447C676 383 719 214 858 216C982 218 1038 325 1091 278" class="stroke-soft" opacity=".65"/>
+
+  <rect x="70" y="64" width="1060" height="502" rx="36" class="shell"/>
+  <rect x="96" y="92" width="1008" height="48" rx="18" class="soft"/>
+  <circle cx="124" cy="116" r="6" class="dot-muted" opacity=".6"/>
+  <circle cx="146" cy="116" r="6" class="dot-muted" opacity=".38"/>
+  <circle cx="168" cy="116" r="6" class="dot-muted" opacity=".25"/>
+  <text x="198" y="121" class="tiny">@haemmid/pi-processes</text>
+  <rect x="930" y="105" width="140" height="22" rx="11" class="chip"/>
+  <text x="953" y="120" class="tiny">managed runs</text>
+
+  <g transform="translate(96 176)">
+    <rect width="260" height="190" rx="24" class="card"/>
+    <rect x="22" y="22" width="216" height="48" rx="14" class="soft"/>
+    <path d="M45 47l13 12-13 12M72 69h43" class="stroke"/>
+    <text x="22" y="106" class="title-text">Pi Agent</text>
+    <text x="22" y="132" class="label">asks for a dev process</text>
+    <rect x="22" y="150" width="92" height="20" rx="10" class="chip"/>
+    <text x="39" y="164" class="tiny">start</text>
+    <rect x="124" y="150" width="92" height="20" rx="10" class="chip"/>
+    <text x="145" y="164" class="tiny">status</text>
+  </g>
+
+  <g transform="translate(468 166)">
+    <rect width="264" height="210" rx="28" class="card"/>
+    <circle cx="132" cy="73" r="40" class="soft"/>
+    <path d="M132 43v12M132 91v12M102 73h12M150 73h12M111 52l9 9M144 85l9 9M153 52l-9 9M120 85l-9 9" class="stroke"/>
+    <circle cx="132" cy="73" r="14" fill="none" class="accent-stroke" stroke-width="3"/>
+    <text x="36" y="136" class="title-text">process tool</text>
+    <text x="36" y="162" class="label">dedupe • resolve • stop</text>
+    <rect x="36" y="178" width="82" height="20" rx="10" class="chip"/>
+    <text x="55" y="192" class="tiny">pid</text>
+    <rect x="128" y="178" width="100" height="20" rx="10" class="chip"/>
+    <text x="148" y="192" class="tiny">logs</text>
+  </g>
+
+  <g transform="translate(844 176)">
+    <rect width="260" height="190" rx="24" class="card"/>
+    <text x="28" y="-14" class="title-text">managed dev server</text>
+    <rect x="28" y="28" width="204" height="36" rx="12" class="soft"/>
+    <rect x="28" y="76" width="204" height="36" rx="12" class="soft"/>
+    <rect x="28" y="124" width="204" height="36" rx="12" class="soft"/>
+    <circle cx="50" cy="46" r="5" class="dot-ok"/>
+    <circle cx="50" cy="94" r="5" class="dot-ok"/>
+    <circle cx="50" cy="142" r="5" class="dot-ok"/>
+    <path d="M72 46h104M72 94h126M72 142h78" class="stroke-soft"/>
+    <text x="28" y="186" class="label">Astro / Vite, kept under control</text>
+  </g>
+
+  <path d="M368 271C404 271 421 271 456 271" class="arrow"/>
+  <path d="M746 271C785 271 800 271 832 271" class="arrow"/>
+
+  <g transform="translate(390 420)">
+    <rect width="420" height="94" rx="22" class="card"/>
+    <text x="26" y="34" class="mono">stdout.log</text>
+    <text x="26" y="62" class="mono2">ready in 312ms • localhost:5173</text>
+    <text x="26" y="82" class="mono2">[managed] reused existing process</text>
+    <path d="M324 31h58M324 53h42M324 75h70" class="stroke-soft"/>
+  </g>
+  <path d="M600 388C600 404 600 410 600 418" class="arrow2"/>
+
+  <g transform="translate(842 423)">
+    <rect width="241" height="91" rx="22" class="card"/>
+    <circle cx="48" cy="46" r="25" class="soft"/>
+    <path d="M51 23 35 50h18l-5 20 22-33H52z" class="bolt"/>
+    <text x="88" y="40" class="title-text">faster pi-web</text>
+    <text x="88" y="66" class="label">automation loop</text>
+  </g>
+  <path d="M812 467C822 467 829 467 840 467" class="arrow2"/>
+
+  <circle cx="748" cy="232" r="5" class="accent-dot" opacity=".55"/>
+  <circle cx="457" cy="304" r="4" class="accent-dot2" opacity=".55"/>
+  <circle cx="600" cy="395" r="4" class="dot-muted" opacity=".45"/>
+
+</svg>

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@haemmid/pi-processes",
+  "version": "0.9.0",
+  "description": "Agent-facing background process manager for Pi and pi-web automation workflows.",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "homepage": "https://github.com/haemmid/pi-processes#readme",
+  "bugs": {
+    "url": "https://github.com/haemmid/pi-processes/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pi-web",
+    "processes",
+    "background-processes",
+    "dev-server",
+    "astro",
+    "vite"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haemmid/pi-processes.git"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "assets"
+  ],
+  "dependencies": {
+    "@aliou/sh": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@earendil-works/pi-coding-agent": "0.75.1",
+    "@types/node": "^25.0.10",
+    "typebox": "^1.1.24",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "format": "biome check --write",
+    "test": "vitest run"
+  },
+  "packageManager": "pnpm@10.26.1",
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,125 @@
+/**
+ * Runtime configuration for the processes extension.
+ *
+ * Global: ~/.pi/agent/extensions/process.json
+ */
+
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+interface ProcessesConfig {
+  output?: {
+    /** Default number of tail lines returned to the agent. */
+    defaultTailLines?: number;
+    /** Hard cap on output lines returned to the agent. */
+    maxOutputLines?: number;
+  };
+  execution?: {
+    /** Absolute shell path override. Leave unset to auto-resolve. */
+    shellPath?: string;
+  };
+  interception?: {
+    /** Block shell backgrounding and obvious long-running bash commands, and guide the model to use the process tool. */
+    blockBackgroundCommands?: boolean;
+  };
+}
+
+export interface ResolvedProcessesConfig {
+  output: {
+    defaultTailLines: number;
+    maxOutputLines: number;
+  };
+  execution: {
+    shellPath?: string;
+  };
+  interception: {
+    blockBackgroundCommands: boolean;
+  };
+}
+
+const DEFAULT_CONFIG: ResolvedProcessesConfig = {
+  output: {
+    defaultTailLines: 100,
+    maxOutputLines: 200,
+  },
+  execution: {},
+  interception: {
+    blockBackgroundCommands: true,
+  },
+};
+
+class ProcessesConfigLoader {
+  private resolved: ResolvedProcessesConfig | null = null;
+
+  async load(): Promise<void> {
+    const rawConfig = await readGlobalConfig();
+    this.resolved = resolveConfig(rawConfig);
+  }
+
+  getConfig(): ResolvedProcessesConfig {
+    if (!this.resolved) {
+      throw new Error("Config not loaded. Call load() first.");
+    }
+    return this.resolved;
+  }
+}
+
+async function readGlobalConfig(): Promise<ProcessesConfig | null> {
+  const path = resolve(getAgentDir(), "extensions/process.json");
+
+  try {
+    const content = await readFile(path, "utf-8");
+    const parsed: unknown = JSON.parse(content);
+    if (!isRecord(parsed)) return null;
+
+    const { $schema: _schema, ...config } = parsed;
+    return config as ProcessesConfig;
+  } catch {
+    return null;
+  }
+}
+
+function resolveConfig(
+  config: ProcessesConfig | null,
+): ResolvedProcessesConfig {
+  return {
+    output: {
+      defaultTailLines: numberOrDefault(
+        config?.output?.defaultTailLines,
+        DEFAULT_CONFIG.output.defaultTailLines,
+      ),
+      maxOutputLines: numberOrDefault(
+        config?.output?.maxOutputLines,
+        DEFAULT_CONFIG.output.maxOutputLines,
+      ),
+    },
+    execution: {
+      shellPath: stringOrUndefined(config?.execution?.shellPath),
+    },
+    interception: {
+      blockBackgroundCommands: booleanOrDefault(
+        config?.interception?.blockBackgroundCommands,
+        DEFAULT_CONFIG.interception.blockBackgroundCommands,
+      ),
+    },
+  };
+}
+
+function numberOrDefault(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function stringOrUndefined(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function booleanOrDefault(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export const configLoader = new ProcessesConfigLoader();

package/src/constants/index.ts

@@ -0,0 +1,11 @@
+export type {
+  ExecuteResult,
+  KillResult,
+  ManagerEvent,
+  ProcessesDetails,
+  ProcessInfo,
+  ProcessStatus,
+  ResolveProcessResult,
+} from "./types";
+
+export { LIVE_STATUSES } from "./types";