@agimon-ai/doompi-runner 0.0.1-alpha.21 → 0.0.1-alpha.22

package/README.md

@@ -1,26 +1,23 @@
 # @agimon-ai/doompi-runner
 
-**A shell command should not hold the session hostage.**
+Supervised shell execution, background process control, durable logs, and Runner Space for Pi.
 
-Doompi Runner replaces Pi's built-in bash tool with a supervised one. Short commands behave
-normally. Long commands move into the background, keep writing to a saved log, and remain
-controllable through the process tool and TUI instead of blocking the agent until a timeout.
+Runner replaces Pi's built-in `bash` tool only in sessions that load it. Short commands return inline; long commands can be promoted to a background runner instead of blocking the agent.
 
-Detached runs reconcile after compaction and other context rewrites. The transcript can
-change; the process does not lose its identity.
+> **Alpha:** tool and process contracts may change between releases.
 
-This is part of [Doompi](https://www.npmjs.com/package/@agimon-ai/doompi). Most users load
-it through a major-mode layer.
+## Requirements
 
-## Install
+- Node.js 22.19.0 or newer
+- Pi 0.84.2 and Pi TUI 0.84.2
+- `/bin/bash`
+- macOS or Linux on arm64 or x64 for bundled RMUX support
 
-```bash
-npm install @agimon-ai/doompi-runner
-```
+Linux native loading also depends on a compatible system loader/libc. Runner uses a `node-pty` fallback when RMUX is unavailable.
 
-## How it loads
+## Install
 
-Put the bare package name in a layer, then add that layer to a major mode:
+DoomPi users add Runner to a layer:
 
 ```yaml
 layers:
@@ -28,28 +25,92 @@ layers:
     packages: ['@agimon-ai/doompi-runner']
 
 majorMode:
-  dev:
-    description: Development mode with supervised long-running commands.
+  development:
+    description: Development with supervised commands.
     layers: [runner]
 ```
 
-The package's Pi manifest selects the Pi adapter. It replaces bash only in modes that name
-the layer.
+For direct Pi installation:
+
+```bash
+pi install npm:@agimon-ai/doompi-runner
+```
+
+## Use the `bash` tool
+
+```json
+{
+  "command": "pnpm test",
+  "timeout": 60
+}
+```
+
+Commands crossing the promotion threshold move to a supervised runner. The default threshold is 60 seconds. Set `background: true` to detach immediately, or `interactive: true` only when a command needs terminal input.
+
+Runner requires `PI_SESSION_ID` for session ownership. Processes, controls, and logs remain addressable after transcript compaction because their identity is outside model context.
+
+## Inspect and control runs
+
+Use `/runners` or `SPC r r` in the TUI. The `doom-runner` CLI supports:
+
+```bash
+doom-runner list
+doom-runner status <runner-id>
+doom-runner logs <runner-id>
+doom-runner input <runner-id> "y"
+doom-runner stop <runner-id>
+doom-runner stop-all
+```
+
+Stop runs that are no longer required.
+
+## Storage and limits
+
+Session-scoped logs and registry data live under:
+
+```text
+~/.pi/agent/doom-runner/<session>/
+```
+
+Logs rotate at 5 MiB by default and are eligible for cleanup after seven days. Limits and the promotion threshold can be configured through Runner's exported configuration helpers and environment-backed runtime settings.
 
-## Leader
+Commands inherit the DoomPi process environment and the operating-system user's privileges. Logs may contain prompts, source, command output, credentials, or other secrets; restrict access and retention accordingly.
 
-`SPC r r` opens Runner Space, where background processes can be inspected and controlled.
+## Native artifacts
 
-## Runtime
+Runner selects one optional dependency automatically:
 
-The package ships the `doom-runner` CLI and chooses a prebuilt `rmux` binary from its
-platform-specific optional dependencies. npm installs the matching binary package; users
-do not pick one by hand.
+| Host        | Package                           |
+| ----------- | --------------------------------- |
+| macOS arm64 | `doompi-runner-rmux-darwin-arm64` |
+| macOS x64   | `doompi-runner-rmux-darwin-x64`   |
+| Linux arm64 | `doompi-runner-rmux-linux-arm64`  |
+| Linux x64   | `doompi-runner-rmux-linux-x64`    |
+
+Do not install these metadata-only native packages directly.
 
 ## Public API
 
-The root export and declared subpaths expose the runner protocol, process supervision,
-state, tools, and TUI. Use supported exports rather than reaching into `dist/`.
+```ts
+import {
+  createRunnerContainer,
+  DEFAULT_BG_THRESHOLD_MS,
+  DEFAULT_LOG_MAX_BYTES,
+  DEFAULT_LOG_TTL_MS,
+  RmuxBackend,
+} from '@agimon-ai/doompi-runner';
+```
+
+Declared subpaths expose process supervision, configuration, tools, response envelopes, and TUI integration for host authors.
+
+## Development
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agimon-ai/doompi-runner",
-  "version": "0.0.1-alpha.21",
+  "version": "0.0.1-alpha.22",
   "description": "Pi bash tool replacement with background process supervision",
   "keywords": [
     "ai",
@@ -292,10 +292,10 @@
     "node-pty": "1.1.0",
     "reflect-metadata": "0.2.2",
     "typebox": "1.1.38",
-    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.21",
-    "@agimon-ai/doompi-ui": "0.0.1-alpha.21",
-    "@agimon-ai/doompi-telemetry": "0.0.1-alpha.21",
-    "@agimon-ai/foundation-process-registry": "0.29.11"
+    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.22",
+    "@agimon-ai/doompi-telemetry": "0.0.1-alpha.22",
+    "@agimon-ai/doompi-ui": "0.0.1-alpha.22",
+    "@agimon-ai/foundation-process-registry": "0.29.12"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",
@@ -319,10 +319,10 @@
     }
   },
   "optionalDependencies": {
-    "@agimon-ai/doompi-runner-rmux-darwin-x64": "0.0.1-alpha.21",
-    "@agimon-ai/doompi-runner-rmux-linux-arm64": "0.0.1-alpha.21",
-    "@agimon-ai/doompi-runner-rmux-darwin-arm64": "0.0.1-alpha.21",
-    "@agimon-ai/doompi-runner-rmux-linux-x64": "0.0.1-alpha.21"
+    "@agimon-ai/doompi-runner-rmux-darwin-x64": "0.0.1-alpha.22",
+    "@agimon-ai/doompi-runner-rmux-linux-x64": "0.0.1-alpha.22",
+    "@agimon-ai/doompi-runner-rmux-darwin-arm64": "0.0.1-alpha.22",
+    "@agimon-ai/doompi-runner-rmux-linux-arm64": "0.0.1-alpha.22"
   },
   "engines": {
     "node": ">=22.19.0"