pi-background-tasks 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/PUBLISHING.md

@@ -0,0 +1,62 @@
+# Publishing pi-background-tasks
+
+This package is ready for both npm publishing and standalone git publishing.
+
+## Preconditions
+
+- npm account with publish rights for `pi-background-tasks`.
+- Standalone GitHub repository, expected: `github.com/ismailsaleekh/pi-background-tasks`.
+- Clean worktree.
+
+## Verify
+
+```bash
+cd packages/pi-background-tasks
+npm run smoke
+npm pack --dry-run
+npm view pi-background-tasks name version --json
+```
+
+At creation time, `npm view pi-background-tasks` returned 404, so the unscoped name appeared available.
+
+## Publish to npm
+
+```bash
+cd packages/pi-background-tasks
+npm login
+npm publish --access public
+```
+
+Pi install smoke after publish:
+
+```bash
+pi -e npm:pi-background-tasks@0.1.0 --offline --no-tools --no-session -p "/jobs"
+pi install npm:pi-background-tasks@0.1.0
+```
+
+## Publish to git
+
+Because Pi git package installs treat the repository root as the package root, do not point Pi at the `ai-pipeline` monorepo root for this package. Push the contents of `packages/pi-background-tasks/` to a standalone repository.
+
+```bash
+cd packages/pi-background-tasks
+git init
+git add .
+git commit -m "Initial pi-background-tasks package"
+git branch -M main
+git remote add origin git@github.com:ismailsaleekh/pi-background-tasks.git
+git push -u origin main
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Pi install smoke after git tag:
+
+```bash
+pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.1.0 --offline --no-tools --no-session -p "/jobs"
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.1.0
+```
+
+## pi.dev/packages
+
+The package includes the `pi-package` keyword and a `pi.extensions` manifest. After npm publish, it should be discoverable by pi.dev package indexing. If it does not appear automatically, submit/refresh the package according to the pi.dev package-gallery process.

package/README.md

@@ -0,0 +1,69 @@
+# pi-background-tasks
+
+Claude-Code-like explicit background shell task manager for [Pi](https://pi.dev/).
+
+This package adds tracked background shell jobs with durable output files, bounded log reads, kill/timeout safety, a `/tasks` manager UI, and completion notifications that can wake the agent when LLM-launched work finishes.
+
+## Install
+
+From npm after publish:
+
+```bash
+pi install npm:pi-background-tasks@0.1.0
+```
+
+From git after pushing this package to its standalone repository and tagging:
+
+```bash
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.1.0
+```
+
+For project-local install:
+
+```bash
+pi install -l npm:pi-background-tasks@0.1.0
+```
+
+## Commands
+
+- `/bg <command>` — start a tracked background shell command.
+- `/jobs` — list running and recent completed/failed/killed tasks.
+- `/logs <id> [maxBytes]` — show bounded tail output and full output path.
+- `/kill <id>` — stop a running task.
+- `/tasks` or `/bg-tasks` — open the interactive task manager UI.
+
+## LLM tools
+
+- `bg_run` — start long-running commands without blocking the conversation.
+- `bg_status` — inspect one task or all recent tasks.
+- `bg_logs` — read bounded task output.
+- `bg_kill` — stop a running task.
+
+`bg_run` defaults to `triggerOnCompletion: true`, so completion notifications trigger a follow-up agent turn. User-launched `/bg` jobs are display-only by default.
+
+## Runtime files
+
+Task output and metadata are written under the current project:
+
+```text
+.pi/tasks/<session-id>-<pid>/<task-id>.output
+.pi/tasks/<session-id>-<pid>/<task-id>.json
+```
+
+These are runtime artifacts and should remain gitignored.
+
+## Safety model
+
+- Commands are spawned and tracked with `child_process.spawn`; the package does not rely on shell `&`.
+- stdout/stderr are captured to task output files.
+- Model-visible logs are bounded and point to full output files.
+- POSIX process groups are used for process-tree kill where possible, with child-process fallback.
+- Running tasks are cleaned up on Pi session shutdown/reload.
+- Cross-Pi-restart process reattachment and Ctrl+B backgrounding of already-running foreground tools are intentionally out of scope.
+
+## Development smoke
+
+```bash
+npm run smoke
+npm run pack:dry-run
+```