@agimon-ai/po-runner 0.0.0-alpha.0

package/package.json

@@ -0,0 +1,303 @@
+{
+  "name": "@agimon-ai/po-runner",
+  "version": "0.0.0-alpha.0",
+  "description": "Supervised shell execution, background process control, and run logs for Pi coding agents.",
+  "keywords": [
+    "ai",
+    "background-process",
+    "coding-agent",
+    "developer-tools",
+    "doom-runner",
+    "pi-coding-agent",
+    "pi-package",
+    "po",
+    "process-supervision",
+    "shell"
+  ],
+  "homepage": "https://agimon.ai",
+  "bugs": {
+    "url": "https://github.com/AgiFlow/po/issues"
+  },
+  "license": "MIT",
+  "author": "Vuong Ngo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgiFlow/po.git",
+    "directory": "packages/default/po-runner"
+  },
+  "bin": {
+    "po-runner": "./dist/bin/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "llms.txt",
+    "src/prompts",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "jsnext:main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./ansiScrub": {
+      "types": "./dist/ansiScrub.d.mts",
+      "import": "./dist/ansiScrub.mjs",
+      "require": "./dist/ansiScrub.cjs"
+    },
+    "./bashRunService": {
+      "types": "./dist/bashRunService.d.mts",
+      "import": "./dist/bashRunService.mjs",
+      "require": "./dist/bashRunService.cjs"
+    },
+    "./bashSchema": {
+      "types": "./dist/bashSchema.d.mts",
+      "import": "./dist/bashSchema.mjs",
+      "require": "./dist/bashSchema.cjs"
+    },
+    "./bashTool": {
+      "types": "./dist/bashTool.d.mts",
+      "import": "./dist/bashTool.mjs",
+      "require": "./dist/bashTool.cjs"
+    },
+    "./bin/cli": {
+      "types": "./dist/bin/cli.d.mts",
+      "import": "./dist/bin/cli.mjs",
+      "require": "./dist/bin/cli.cjs"
+    },
+    "./bin/logSink": {
+      "types": "./dist/bin/logSink.d.mts",
+      "import": "./dist/bin/logSink.mjs",
+      "require": "./dist/bin/logSink.cjs"
+    },
+    "./bin/runnerHost": {
+      "types": "./dist/bin/runnerHost.d.mts",
+      "import": "./dist/bin/runnerHost.mjs",
+      "require": "./dist/bin/runnerHost.cjs"
+    },
+    "./cliApp": {
+      "types": "./dist/cliApp.d.mts",
+      "import": "./dist/cliApp.mjs",
+      "require": "./dist/cliApp.cjs"
+    },
+    "./clock": {
+      "types": "./dist/clock.d.mts",
+      "import": "./dist/clock.mjs",
+      "require": "./dist/clock.cjs"
+    },
+    "./compaction": {
+      "types": "./dist/compaction.d.mts",
+      "import": "./dist/compaction.mjs",
+      "require": "./dist/compaction.cjs"
+    },
+    "./config": {
+      "types": "./dist/config.d.mts",
+      "import": "./dist/config.mjs",
+      "require": "./dist/config.cjs"
+    },
+    "./extensions/server": {
+      "types": "./dist/extensions/server.d.mts",
+      "import": "./dist/extensions/server.mjs",
+      "require": "./dist/extensions/server.cjs"
+    },
+    "./extensions/web": {
+      "import": "./dist/extensions/web.mjs"
+    },
+    "./launcher": {
+      "types": "./dist/launcher.d.mts",
+      "import": "./dist/launcher.mjs",
+      "require": "./dist/launcher.cjs"
+    },
+    "./lifeline": {
+      "types": "./dist/lifeline.d.mts",
+      "import": "./dist/lifeline.mjs",
+      "require": "./dist/lifeline.cjs"
+    },
+    "./logFile": {
+      "types": "./dist/logFile.d.mts",
+      "import": "./dist/logFile.mjs",
+      "require": "./dist/logFile.cjs"
+    },
+    "./logReader": {
+      "types": "./dist/logReader.d.mts",
+      "import": "./dist/logReader.mjs",
+      "require": "./dist/logReader.cjs"
+    },
+    "./processControl": {
+      "types": "./dist/processControl.d.mts",
+      "import": "./dist/processControl.mjs",
+      "require": "./dist/processControl.cjs"
+    },
+    "./ptyHost": {
+      "types": "./dist/ptyHost.d.mts",
+      "import": "./dist/ptyHost.mjs",
+      "require": "./dist/ptyHost.cjs"
+    },
+    "./ptySpawner": {
+      "types": "./dist/ptySpawner.d.mts",
+      "import": "./dist/ptySpawner.mjs",
+      "require": "./dist/ptySpawner.cjs"
+    },
+    "./reconcile": {
+      "types": "./dist/reconcile.d.mts",
+      "import": "./dist/reconcile.mjs",
+      "require": "./dist/reconcile.cjs"
+    },
+    "./responseEnvelope": {
+      "types": "./dist/responseEnvelope.d.mts",
+      "import": "./dist/responseEnvelope.mjs",
+      "require": "./dist/responseEnvelope.cjs"
+    },
+    "./rmuxBackend": {
+      "types": "./dist/rmuxBackend.d.mts",
+      "import": "./dist/rmuxBackend.mjs",
+      "require": "./dist/rmuxBackend.cjs"
+    },
+    "./rtkProcessor": {
+      "types": "./dist/rtkProcessor.d.mts",
+      "import": "./dist/rtkProcessor.mjs",
+      "require": "./dist/rtkProcessor.cjs"
+    },
+    "./runnerDependencies": {
+      "types": "./dist/runnerDependencies.d.mts",
+      "import": "./dist/runnerDependencies.mjs",
+      "require": "./dist/runnerDependencies.cjs"
+    },
+    "./runnerNamer": {
+      "types": "./dist/runnerNamer.d.mts",
+      "import": "./dist/runnerNamer.mjs",
+      "require": "./dist/runnerNamer.cjs"
+    },
+    "./runnerPaths": {
+      "types": "./dist/runnerPaths.d.mts",
+      "import": "./dist/runnerPaths.mjs",
+      "require": "./dist/runnerPaths.cjs"
+    },
+    "./runnerRegistry": {
+      "types": "./dist/runnerRegistry.d.mts",
+      "import": "./dist/runnerRegistry.mjs",
+      "require": "./dist/runnerRegistry.cjs"
+    },
+    "./session": {
+      "types": "./dist/session.d.mts",
+      "import": "./dist/session.mjs",
+      "require": "./dist/session.cjs"
+    },
+    "./spawner": {
+      "types": "./dist/spawner.d.mts",
+      "import": "./dist/spawner.mjs",
+      "require": "./dist/spawner.cjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/types.mjs",
+      "require": "./dist/types.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@agimon-ai/foundation-process-registry": "0.30.12",
+    "@agimon-ai/po-core": "0.0.0-alpha.0",
+    "@agimon-ai/po-telemetry": "0.0.0-alpha.0",
+    "@agimon-ai/po-ui": "0.0.0-alpha.0",
+    "@agimon-ai/po-web-components": "0.0.0-alpha.0",
+    "@agimon-ai/po-web-security": "0.0.0-alpha.0",
+    "@deepseek-ai/cordis": "4.0.4",
+    "@rmux/sdk": "0.6.5",
+    "@xterm/headless": "6.0.0",
+    "hono": "4.13.12",
+    "typebox": "1.3.34"
+  },
+  "devDependencies": {
+    "@agimon-ai/po-build": "0.0.0-alpha.0",
+    "@earendil-works/pi-coding-agent": "1.0.2",
+    "@tanstack/react-store": "0.11.2",
+    "@tanstack/store": "0.11.2",
+    "@types/node": "26.6.4",
+    "@types/react": "19.3.0",
+    "@vitest/coverage-v8": "5.0.3",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "1.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@agimon-ai/po-runner-rmux-darwin-arm64": "0.0.0-alpha.0",
+    "@agimon-ai/po-runner-rmux-darwin-x64": "0.0.0-alpha.0",
+    "@agimon-ai/po-runner-rmux-linux-arm64": "0.0.0-alpha.0",
+    "@agimon-ai/po-runner-rmux-linux-x64": "0.0.0-alpha.0",
+    "@agimon-ai/po-runner-rtk-darwin-arm64": "0.0.0-alpha.0",
+    "@agimon-ai/po-runner-rtk-darwin-x64": "0.0.0-alpha.0",
+    "@agimon-ai/po-runner-rtk-linux-arm64": "0.0.0-alpha.0",
+    "@agimon-ai/po-runner-rtk-linux-x64": "0.0.0-alpha.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "poMcp": {
+    "entry": "./generated/mcp.ts",
+    "dist": "./dist/extensions/mcp.mjs",
+    "scopes": [
+      "session"
+    ],
+    "ui": {
+      "entry": "./generated/mcp-ui.ts",
+      "dist": "./dist/extensions/mcp-ui.mjs",
+      "widgets": [
+        "@agimon-ai/po-runner/bash"
+      ]
+    }
+  },
+  "poServer": {
+    "entry": "./generated/server.ts",
+    "dist": "./dist/extensions/server.mjs",
+    "scopes": [
+      "global",
+      "workspace",
+      "session"
+    ],
+    "contracts": {
+      "entry": "./src/exports/apiContracts.ts",
+      "dist": "./dist/apiContracts.mjs"
+    }
+  },
+  "poWeb": {
+    "pluginId": "runner",
+    "channels": [
+      "runner_runs"
+    ],
+    "client": "./dist/extensions/web.mjs",
+    "scopes": [
+      "session"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown && tsdown --config tsdown.mcp.config.ts",
+    "build:mcp": "tsdown --config tsdown.mcp.config.ts",
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.web.json && tsc --noEmit -p tsconfig.mcp.json",
+    "lint": "oxlint . && oxfmt . --check",
+    "fixcode": "oxlint . --fix && oxfmt ."
+  }
+}

package/skills/doom-runner/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: doom-runner
+description: 'Manage long-running commands started by bash: dev servers, watchers, builds, tails, and anything that prompts for input. Trigger when a command needs to outlive the current turn, when bash output was truncated, or when a background process needs to be inspected, followed, given input, or stopped.'
+---
+
+# doom-runner
+
+`bash` supervises what it starts. A command that outlives the background
+threshold keeps running instead of blocking the turn. Use the `doom-runner`
+CLI to manage it without adding another model tool.
+
+## Backgrounding
+
+- A command still running after 60 seconds (`DOOM_RUNNER_BG_THRESHOLD_MS`) is
+  moved to the background automatically. You get its unique ID and streaming
+  log path.
+- Pass `background: true` for commands you already know will not finish: dev
+  servers, watchers, `tail -f`. Waiting out the threshold first wastes a turn.
+- Pass `interactive: true` when the command will prompt for confirmation or
+  input. It runs under a terminal and backgrounds immediately. Answer it with
+  `doom-runner input <id> --text <text> --enter`, or use Runner Space.
+- Pass `timeout` (seconds) when you want a command killed rather than
+  supervised. A timeout above the threshold has no effect: the command is
+  promoted first.
+- Pass `name` to choose the runner name. A name already in use gets a numbered
+  suffix.
+
+## CLI
+
+Invoke the CLI through the available Bash tool to inspect or control an existing
+runner. Do not relaunch its original command to recover output. The CLI inherits `PI_SESSION_ID` from the active Pi session and only accesses that
+session's runners. A manual shell without `PI_SESSION_ID` fails closed.
+
+Use the unique runner ID returned by `bash`:
+
+| Command                                            | Purpose                                        |
+| -------------------------------------------------- | ---------------------------------------------- |
+| `doom-runner list [--all]`                         | List active runners, or include completed ones |
+| `doom-runner status <id>`                          | Show command, state, backend, and log path     |
+| `doom-runner logs <id> [--lines N] [--follow]`     | Read or stream the saved log                   |
+| `doom-runner stop <id> [--reason <text>]`          | Stop one runner and keep its log               |
+| `doom-runner stop-all [--reason <text>]`           | Stop active runners owned by this Pi session   |
+| `doom-runner input <id> [--text <text>] [--enter]` | Send input to an interactive RMUX runner       |
+
+## Rules
+
+- **Read the log, do not re-run the command.** When output is truncated, the
+  full text is already on disk. Use `doom-runner logs <id>` or standard file
+  search tools against the reported path.
+- **Read the truncation notice before reading the file.** It states the real
+  file size and line count, so you do not read past the end.
+- **CLI access is session-scoped.** `list`, direct ID commands, and `stop-all`
+  only access runners owned by the inherited Pi session.
+- **`input` needs `interactive: true`.** A normal runner does not expose stdin.
+- **Stop what you no longer need.** Everything still running is stopped when
+  the session ends, but a forgotten dev server holds a port until then.
+- **Completion delivery depends on the client.** Local Po can notify its
+  agent, but remote MCP callers must not assume that this wakes their chat.
+  Use a bounded status or log read when needed. Do not sleep or poll in a loop,
+  promise automatic continuation, or report a running command as completed.
+- **Do not pipe to head or tail.** Results are already bounded and the full log
+  is on disk. A tail pipe also leaves the live log empty until the command
+  exits, which blanks the log pane in Runner Space.
+
+## Where things live
+
+Run metadata and logs sit under
+`$PI_CODING_AGENT_DIR/doom-runner/<session-id>/{runs,logs}`. Without an
+override, `$PI_CODING_AGENT_DIR` defaults to `~/.po/agent`. Completed metadata
+and complete raw logs remain readable for seven days.
+
+RMUX is bundled for supported macOS and Linux platforms. Non-interactive runs
+fall back to a supervised subprocess when RMUX is unavailable; interactive runs
+require RMUX. Eligible simple commands use a command-specific RTK stdin filter
+after completion. Compound shell commands and unsupported formats keep bounded
+raw output.
+
+`SPC r l` opens Runner Space. Escape returns from logs or an attached terminal.

package/src/prompts/po-use-runner/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: po-use-runner
+description: Use Doom Pi Runner to supervise shell commands, inspect durable logs, provide interactive input, and stop background runs.
+---
+
+# Use Doom Pi Runner
+
+Use Runner for shell work that may outlive one tool call, needs durable logs, or requires later inspection and control.
+
+## Launch work
+
+- Use the Runner-provided `bash` tool for shell commands.
+- Let short commands return inline.
+- Set `background: true` when the command should detach immediately.
+- Set `interactive: true` only when the process genuinely needs terminal input.
+- `timeout` only governs the foreground wait. A command promoted to the background can continue past it; do not treat it as a background deadline.
+
+## Inspect and control work
+
+For remote MCP, run the following commands through `bash`. They inherit the
+bound session; do not supply another session ID. `/runners` and `SPC r l` are
+local TUI interfaces, not shell commands or remote tools. For direct control, use:
+
+```bash
+doom-runner list
+doom-runner status <runner-id>
+doom-runner logs <runner-id> --lines 100
+doom-runner input <runner-id> --text "y" --enter
+doom-runner stop <runner-id>
+doom-runner stop-all
+```
+
+Input requires a running interactive process backed by RMUX. Preserve the returned runner identifier because it remains usable after transcript compaction.
+
+## Close the lifecycle
+
+Remote MCP never receives runner completion notices, and a runner you start
+does not resume your conversation when it ends. While a runner matters to your
+task, check `doom-runner status <id>` between steps of your own work and read
+`doom-runner logs <id> --lines 100`. Stop checking when State is completed, and
+report a runner that is still running with its identifier. Do not promise
+automatic follow-up or relaunch uncertain work.
+
+- Inspect logs instead of relaunching a command whose status is uncertain.
+- Stop watchers, servers, and failed interactive processes when they are no longer needed.
+- Treat commands as running with the Doom Pi process environment and the operating-system user's privileges.
+- Treat logs as sensitive because they may contain prompts, source, output, or credentials.