{"_id":"@clanker-code/pi-monitor","_rev":"3-fea87c0e5420416b354f939362da8a13","name":"@clanker-code/pi-monitor","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@clanker-code/pi-monitor","version":"0.1.0","keywords":["pi-package","pi-extension","pi","background-jobs","monitoring","notifications"],"author":{"name":"XertroV"},"license":"Unlicense","_id":"@clanker-code/pi-monitor@0.1.0","maintainers":[{"name":"xertrov","email":"m@xk.io"}],"homepage":"https://github.com/clankercode/pi-monitor#readme","bugs":{"url":"https://github.com/clankercode/pi-monitor/issues"},"pi":{"extensions":["./extensions"]},"dist":{"shasum":"712df1c01c8223073aac0899147f56efb2a017fc","tarball":"https://registry.npmjs.org/@clanker-code/pi-monitor/-/pi-monitor-0.1.0.tgz","fileCount":15,"integrity":"sha512-rj2GO+0Glkj7ejcd8HulFHqxGk/64oP3qvMNMdIcVI1LVXEZt98TDk9A+4lqNId8Uxm2h6CQSvG8N5rQxE/WnA==","signatures":[{"sig":"MEUCIHTGx+EKqApAj7py911tWTmk+YwpqjB81pMUo05OzmNiAiEA5h1mgCc8Gbw5zE6cFCDJoaeaYV9s1bq4fDgl8dBlEhQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":105142},"type":"module","engines":{"node":">=22.19.0"},"gitHead":"eaca47fcd4338e6f35b003629b79d20bfcffc047","private":false,"scripts":{"test":"node --import tsx --test tests/*.test.ts tests/**/*.test.ts","check":"tsc --noEmit && node --import tsx --test tests/*.test.ts tests/**/*.test.ts","typecheck":"tsc --noEmit","prepublishOnly":"pnpm run check"},"_npmUser":{"name":"xertrov","email":"m@xk.io"},"repository":{"url":"git+https://github.com/clankercode/pi-monitor.git","type":"git"},"_npmVersion":"12.0.1","description":"Pi extension that watches background processes and delivers regex-matching stdout windows to the agent session.","directories":{},"_nodeVersion":"22.23.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.0","typescript":"^5.7.0","@types/node":"^22.0.0","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"0.79.4","@earendil-works/pi-coding-agent":"0.79.4"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-monitor_0.1.0_1785124483512_0.2039797217857071","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@clanker-code/pi-monitor","version":"0.1.1","keywords":["pi-package","pi-extension","pi","background-jobs","monitoring","notifications"],"author":{"name":"XertroV"},"license":"Unlicense","_id":"@clanker-code/pi-monitor@0.1.1","maintainers":[{"name":"xertrov","email":"m@xk.io"}],"homepage":"https://github.com/clankercode/pi-monitor#readme","bugs":{"url":"https://github.com/clankercode/pi-monitor/issues"},"pi":{"extensions":["./extensions"]},"dist":{"shasum":"280d938a51e6aab4a112007541dfbec3eac290ef","tarball":"https://registry.npmjs.org/@clanker-code/pi-monitor/-/pi-monitor-0.1.1.tgz","fileCount":15,"integrity":"sha512-dfLrKizisMQ2W5oCd/fUN3BFA1Q7EIfxO5+qSM8Fd7JnGuGxr0Veny1T7gYSCjH3ViwDgvDyDi7dOh9jdPn+1g==","signatures":[{"sig":"MEUCIQCerbiV25Lx/rdavZPmp9KVGPCfBhhXwohvrAT37btHRgIgT31zCSKmMPvN0sUGjld74NTOZ9p2iPs6myGyzvYoFwc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@clanker-code%2fpi-monitor@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":105142},"type":"module","engines":{"node":">=22.19.0"},"gitHead":"83ba8f3e60ad2d9184ab9c57d69ebf3cf0c32a33","private":false,"scripts":{"test":"node --import tsx --test tests/*.test.ts tests/**/*.test.ts","check":"tsc --noEmit && node --import tsx --test tests/*.test.ts tests/**/*.test.ts","typecheck":"tsc --noEmit","prepublishOnly":"pnpm run check"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cafd1799-75f6-4613-81e5-e7627323f663"}},"repository":{"url":"git+https://github.com/clankercode/pi-monitor.git","type":"git"},"_npmVersion":"12.0.1","description":"Pi extension that watches background processes and delivers regex-matching stdout windows to the agent session.","directories":{},"_nodeVersion":"22.23.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.0","typescript":"^5.7.0","@types/node":"^22.0.0","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"0.79.4","@earendil-works/pi-coding-agent":"0.79.4"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-monitor_0.1.1_1785124806695_0.07127123934532875","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@clanker-code/pi-monitor","version":"0.2.0","description":"Pi extension that watches background processes and delivers regex-matching stdout windows to the agent session.","type":"module","license":"Unlicense","author":{"name":"XertroV"},"private":false,"keywords":["pi-package","pi-extension","pi","background-jobs","monitoring","notifications"],"repository":{"type":"git","url":"git+https://github.com/clankercode/pi-monitor.git"},"homepage":"https://github.com/clankercode/pi-monitor#readme","bugs":{"url":"https://github.com/clankercode/pi-monitor/issues"},"pi":{"extensions":["./extensions"]},"scripts":{"typecheck":"tsc --noEmit","test":"node --import tsx --test tests/*.test.ts tests/**/*.test.ts","check":"tsc --noEmit && node --import tsx --test tests/*.test.ts tests/**/*.test.ts","prepublishOnly":"pnpm run check"},"engines":{"node":">=22.19.0"},"publishConfig":{"access":"public"},"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*","typebox":"*"},"devDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-coding-agent":"0.79.4","@earendil-works/pi-tui":"0.79.4","@types/node":"^22.0.0","tsx":"^4.22.0","typescript":"^5.7.0"},"gitHead":"e88b630bd92e755c7b1d7bd02ceb318a2a37a021","_id":"@clanker-code/pi-monitor@0.2.0","_nodeVersion":"22.23.1","_npmVersion":"12.0.2","dist":{"integrity":"sha512-aOlhTnMm9yr5mP29xsyVZzNgs1JdSyyaW8LBlAUCEgWHuMFpteVc+wYnfT87VH7t3P57vHS8CBbJHhLWuHVB/g==","shasum":"6a64005334259512a370097f42564c47d5179147","tarball":"https://registry.npmjs.org/@clanker-code/pi-monitor/-/pi-monitor-0.2.0.tgz","fileCount":16,"unpackedSize":133252,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@clanker-code%2fpi-monitor@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICwNfLGxh0LMuRpjf8rGgbIqk9A24jCpjtXh1ilOronPAiAQvT8k7Mew/6uCiahhRld5gydmjsrhQmGkYJPMDc0pNQ=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cafd1799-75f6-4613-81e5-e7627323f663"}},"directories":{},"maintainers":[{"name":"xertrov","email":"m@xk.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-monitor_0.2.0_1785654412570_0.01183298549149625"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-27T03:54:43.384Z","modified":"2026-08-02T07:06:53.058Z","0.1.0":"2026-07-27T03:54:43.644Z","0.1.1":"2026-07-27T04:00:06.818Z","0.2.0":"2026-08-02T07:06:52.719Z"},"bugs":{"url":"https://github.com/clankercode/pi-monitor/issues"},"author":{"name":"XertroV"},"license":"Unlicense","homepage":"https://github.com/clankercode/pi-monitor#readme","keywords":["pi-package","pi-extension","pi","background-jobs","monitoring","notifications"],"repository":{"type":"git","url":"git+https://github.com/clankercode/pi-monitor.git"},"description":"Pi extension that watches background processes and delivers regex-matching stdout windows to the agent session.","maintainers":[{"name":"xertrov","email":"m@xk.io"}],"readme":"# @clanker-code/pi-monitor\n\n| | |\n|---|---|\n| **npm** | [`@clanker-code/pi-monitor`](https://www.npmjs.com/package/@clanker-code/pi-monitor) — scope `@clanker-code` |\n| **GitHub** | [`clankercode/pi-monitor`](https://github.com/clankercode/pi-monitor) — org `clankercode` (no hyphen) |\n\nNaming is intentional and easy to mix up: **npm uses the hyphen** (`@clanker-code/…`); **this repo lives under GitHub `clankercode`** (no hyphen).\n\nA [pi](https://pi.dev) extension that watches background processes and delivers **regex-matching stdout windows** (with before/after context) into the agent session, plus **background shell jobs** that notify only on exit.\n\nThis is a **partial pseudo-fork** of [`pi-monitor-plugin`](https://github.com/Shodocan/pi-monitor-plugin) by [Walisson Casonatto (Shodocan)](https://github.com/Shodocan). Upstream planned a broader jobs surface (background / monitor / loop / schedule). We ported the **monitor** tool and its core infrastructure, then rebuilt delivery, TUI, and agent integration for our direction. Upstream changes are reviewed when useful; we do not merge blindly.\n\n> **Status:** Working monitor + background extension. Not a drop-in replacement for the full planned upstream jobs suite (loop/schedule omitted).\n\n**Do not poll.** Matching output and process exits are delivered automatically as steer messages. Exit notifications include exit code, last lines of output, and a path to the full process log.\n\n## Features\n\n- **Regex matching** — only forward lines that match a pattern (default: match everything)\n- **Before/after context** — deliver surrounding lines with each match\n- **Debouncing** — batch nearby matches into a single delivery\n- **Background jobs** — fire-and-forget shell commands (`bg_*`); no intermediate deliveries; notify on exit\n- **Exit notifications** — every job end steers the agent with exit code, last lines, and full log path\n- **Full output logs** — stdout/stderr tee'd to `{tmpdir}/pi-monitor/{pid}/{jobID}.log`\n- **No-poll contract** — tool descriptions and start/exit messages tell agents not to poll\n- **`triggerTurn` (default on)** — wake/steer the assistant when matching output arrives; set `false` for display-only logging (exits always wake)\n- **ReDoS protection** — vet regex patterns before execution\n- **Nonce-fencing** — untrusted output is fenced with cryptographic nonces\n- **XML envelope** — delivered windows wrapped for LLM context (`id` + `at`; exits add `event=\"exit\"`)\n- **Secret redaction** — best-effort scrubbing of tokens, keys, passwords\n- **ANSI stripping** — remove terminal escape sequences from output\n- **Idle/busy routing** — deliver immediately if idle; queue/invalidate safely across session lifecycle\n- **Same-turn batching** — group monitor deliveries that fire together\n- **Interactive `/monitor-list` TUI** — live tail, stop with confirm, keyboard nav\n- **AI-callable tools** — `Monitor`, `Background`, `MonitorStop`, `MonitorList`\n\n## Fork divergences\n\nThis package intentionally diverges from upstream. Keep this table honest on every release.\n\n| Feature | Status | Notes |\n|---------|--------|-------|\n| Package identity | ✅ shipped | **npm:** `@clanker-code/pi-monitor` (hyphenated scope). **GitHub:** `clankercode/pi-monitor` (no hyphen). |\n| Monitor + Background | ✅ shipped | Ported ProcessRunner, MonitorEngine, ReDoS, nonce-fencing, redaction, ANSI strip. **Dropped** loop/schedule. **Reintroduced** reduced Background tool (`bg_*`, exit-only). |\n| Working implementation | ✅ shipped | Upstream README describes a planning/scaffold jobs package; this repo is a usable extension. |\n| Exit notifications | ✅ shipped | Process exit always steers the agent with exit code, last ~8 lines, and full log path. Fixes silent disappear from list. |\n| Full output log path | ✅ shipped | Every job tees stream-tagged lines to a durable log file; path returned on start and exit. |\n| AI tools: stop + list | ✅ shipped | `MonitorStop` and `MonitorList` cover mon_* and bg_* (not only slash commands). |\n| `triggerTurn` + steer delivery | ✅ shipped | Default `true` for matches; exit always uses `deliverAs: \"steer\"` + `triggerTurn: true`. |\n| Same-turn delivery batching | ✅ shipped | Nearby/same-turn matches coalesce via `MonitorDeliveryBatcher`; invalidated on session shutdown. |\n| XML envelope for LLM context | ✅ shipped | Matches: `<pi-monitor id at>`; exits: `event=\"exit\"` + body with path/lastLines. TUI strips envelope. |\n| Compact custom tool renderers | ✅ shipped | Tools use custom TUI renderers (`renderShell: 'self'`); statusline `/m` shows active job count. |\n| Interactive `/monitor-list` menu | ✅ shipped | Vertical frame, live tail (last 10 lines), details mode, confirm-or-force stop, left/right nav. |\n| Sensible agent-oriented defaults | ✅ shipped | Default regex matches all lines; `before`/`after`/`debounceSeconds` default to `0`. |\n| Project/global settings | ✅ shipped | `confirmStop` in `.pi/pi-monitor.json` or `~/.pi/agent/pi-monitor.json` (project overrides global). |\n| License | ✅ shipped | Unlicense / public domain; not MIT like upstream’s published LICENSE. |\n| No GitHub PR-watch skill | intentionally omitted | Upstream plans a `gh`-based PR watcher skill; out of scope here. |\n| Fork maintenance docs | ✅ shipped | `AGENTS.md`, `CHANGELOG.md`, `RELEASE.md`, tag-driven CI publish. |\n\n## Install\n\n```bash\npi install npm:@clanker-code/pi-monitor\n```\n\nLocal development:\n\n```bash\npi install /path/to/pi-monitor\n# or ad-hoc for one run:\npi -e ./extensions/pi-monitor.ts\n```\n\nRequires Node ≥ 22.19 and a recent pi coding agent.\n\n## Tools\n\n### `Monitor`\n\nRun a shell command in the background and watch stdout for regex matches.\nMatching windows and process exit are delivered automatically — **do not poll**.\n\n```\nMonitor command=\"tail -f /var/log/app.log\" regex=\"error|warn\" before=5 after=3\n```\n\n| Parameter | Required | Default | Description |\n|-----------|----------|---------|-------------|\n| `command` | yes | — | Shell command to run |\n| `regex` | no | match all | Regex pattern against each stdout line |\n| `regexFlags` | no | `''` | RegExp flags |\n| `before` | no | `0` | Context lines before match (0–200) |\n| `after` | no | `0` | Context lines after match (0–200) |\n| `debounceSeconds` | no | `0` | Debounce window in seconds (0–60) |\n| `label` | no | — | Human-readable label |\n| `triggerTurn` | no | `true` | Wake/steer on match; `false` = display-only (exits always wake) |\n\n### `Background`\n\nRun a shell command in the background with **no intermediate deliveries** (exit-only).\nIds are `bg_N`. Full output is still written to a log file. **Do not poll.**\n\n```\nBackground command=\"pnpm build\" label=\"build\"\n```\n\n| Parameter | Required | Default | Description |\n|-----------|----------|---------|-------------|\n| `command` | yes | — | Shell command to run |\n| `label` | no | — | Human-readable label |\n\n### Exit notification\n\nWhen any job ends (natural exit, crash, or stop), the agent receives a steer message with:\n\n- exit code (and signal if the process was killed)\n- last ~8 lines of process output\n- path to the full output log (`{tmpdir}/pi-monitor/{pid}/{jobID}.log`)\n\n### `MonitorStop`\n\nStop a running job by id (`mon_1` or `bg_1`). You will still receive the exit notification when the process actually terminates.\n\n### `MonitorList`\n\nList all running monitors and background jobs (for inspection only — **do not poll** to wait for completion).\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/monitor-stop <jobID>` | Stop a running monitor or background job |\n| `/monitor-list` | Interactive menu: list jobs, view tail, stop |\n\nThere is **no** `/monitor` slash command — start jobs via the `Monitor` / `Background` tools.\n\n### `/monitor-list` menu\n\n- Lists active jobs, **newest first**\n- Detail pane shows the **last 10 stdout lines** (refreshes every 1s)\n- **Up/Down**: navigate · **Enter / s**: stop (confirm if `confirmStop`) · **x**: stop without confirm · **Left / Esc / q**: back/close · **Right**: Enter-equivalent on list\n\n### Settings\n\nRead from `<cwd>/.pi/pi-monitor.json` (project) or `~/.pi/agent/pi-monitor.json` (global); project overrides global.\n\n| Key | Type | Default | Description |\n|-----|------|---------|-------------|\n| `confirmStop` | boolean | `true` | Whether Enter/s asks for confirmation before stopping |\n\n```json\n{ \"confirmStop\": false }\n```\n\n## Security model\n\n- Pi packages run with full system access — review the source before installing.\n- Commands run in their own process group; stop is SIGTERM → grace → SIGKILL.\n- Delivered process output is nonce-fenced, ANSI/control-stripped, and best-effort secret-redacted.\n- Regex patterns are length-capped and ReDoS-vetted before a monitor starts.\n- Full process logs on disk may contain secrets; treat log paths as sensitive.\n\n## Development\n\n```bash\npnpm install\npnpm test\npnpm check\n```\n\nChangelog: [CHANGELOG.md](./CHANGELOG.md). Release process: [RELEASE.md](./RELEASE.md).\n\n## Upstream\n\n- Original design and research: [Shodocan/pi-monitor-plugin](https://github.com/Shodocan/pi-monitor-plugin) (successor ideas also relate to [opencode-monitor-plugin](https://github.com/Shodocan/opencode-monitor-plugin)).\n- We credit Walisson Casonatto for the monitor architecture (ProcessRunner, MonitorEngine, ReDoS worker, delivery hygiene). Divergences above are ours.\n\n## License\n\n[Unlicense](LICENSE) (public domain).\n","readmeFilename":"README.md"}