pi-background-run 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stablekernel
+
+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,81 @@
+# pi-background-run
+
+Run long shell commands (test suites, builds, linters) as detached background jobs
+so your pi agent session stays unblocked and its context stays clean. Output lands
+in a file under `~/.pi-bgrun/jobs/`; the command returns immediately. When the job
+finishes, pi-background-run **wakes the live agent session** so it proactively reads the
+results and continues — no polling, no human intervention.
+
+Built as a [pi](https://github.com/earendil-works/pi-coding-agent) extension. No
+shell runner, no poller, no sidecar files — the extension spawns the job in-process,
+detects completion via the child `exit` event, and calls `pi.sendUserMessage` to wake
+the agent. The log file is self-describing (full output + a trailing
+`__BGRUN_EXIT__=N` marker), so exit codes survive pi restarting.
+
+## Install
+
+```bash
+pi install npm:pi-background-run
+```
+
+> The npm package is `pi-background-run` — npm blocked the name `pi-bgrun`
+> (too similar to the existing `pi-bg-run`).
+
+Or the scoped alias (same code, permanent namespace claim):
+
+```bash
+pi install npm:@stablekernel/pi-background-run
+```
+
+Restart pi after install so the extension loads.
+
+## Tools registered
+
+| Tool | Purpose |
+| ------ | --------- |
+| `bgrun` | Launch a command detached in the background. Optional `name` gives the job a short human-readable label. Returns `started: <job-id>` immediately. Wakes the session automatically on completion. |
+| `bgstatus` | List jobs (running + done) with exit codes. Reads the in-memory table while pi is alive; scans the jobs dir after restart. |
+| `bgtail` | Print the last N lines of a job's log (default 40), stripping the exit marker. |
+| `bgclean` | Remove old job logs (default 7 days). Skips running jobs while pi is alive. |
+
+`bgwait` and `bgkill` are not provided — the pi port has no shell runner. Use
+`bash` with `kill` if you ever need to stop a running job.
+
+## How it works
+
+```
+agent calls bgrun(command: "make test-short", name: "unit-tests")
+  → extension resolves log path: ~/.pi-bgrun/jobs/<slug>-<ts>-<pid>.log
+  → spawn('sh', ['-c', '<cmd>; ec=$?; printf "\\n__BGRUN_EXIT__=%d\\n" "$ec"; exit $ec'],
+          { stdio: ['ignore', logFd, logFd], detached: true }).unref()
+  → records job in-memory + appends a bgrun-job entry to the session
+  → returns "started: <job-id>"
+
+child 'exit' event fires:
+  → extension records exit code, appends a done entry
+  → pi.sendUserMessage(wake) when idle (triggers a turn)
+     or pi.sendUserMessage(wake, { deliverAs: 'followUp' }) when busy
+  → ctx.ui.notify(...)  — toast for the human
+  → ctx.ui.setWidget("bgrun", ...)  — updates/clears the live status widget
+```
+
+The child writes the log directly via its own stdout fd (no pipe to pi), so the job
+survives pi crashing and the log completes on disk. The trailing
+`__BGRUN_EXIT__=N` marker makes the log self-describing — `bgstatus` recovers the
+exit code even after a restart.
+
+## Reading results without flooding context
+
+- **Quick peek:** `bgtail <id> 40` — last 40 lines, marker stripped.
+- **Whole-log analysis:** `ctx_execute_file` on `~/.pi-bgrun/jobs/<id>.log` to
+  extract only failure lines. Never `cat` or `Read` a full bgrun log.
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `PI_BGRUN_DIR` | `~/.pi-bgrun/jobs` | Override where job logs are stored. |
+
+## Status
+
+Early / pre-release. See `.pi/wip/pi-port-plan.md` in the source tree for the design.