pi-simple-background-tasks 0.0.0-stage → 0.1.0

package/FORK-CHANGES.md

@@ -0,0 +1,66 @@
+# Fork changes: pi-simple-background-tasks vs pi-background-tasks
+
+This package is a **KISS fork** of
+[pi-background-tasks](https://github.com/ismailsaleekh/pi-background-tasks).
+
+## Fork base and comparison versions
+
+- **Fork base**: upstream `v2.6.9`, commit `4aceb55`.
+  The first commit of this repo (`990d60a`, "Import pi-background-tasks 2.6.9 as the fork base") is byte-identical to that upstream commit.
+- **Upstream at last comparison** (2026-10-17): `v2.6.10`, commit `799182f`.
+- **Commits in upstream after the fork base**: 4 — see "Upstream since the fork base" below. None are adopted.
+
+## Divergence summary
+
+Relative to the 2.6.9 source, the fork changes **63 files (31,260 lines removed, 3,704 added)**, ending with **13 source files**:
+
+| Subsystem (as in 2.6.9) | Fork |
+| --- | --- |
+| Background-task core: `registry`, `common`, `extension-api`, `durable-fs`, `task-durable`, `shell-policy`, `windows-taskkill`, `reload-shell-owner`, `ui/background-tasks-manager` | **Kept, simplified** |
+| Fusion workflows (`src/core/fusion/*` + `fusion-extension.ts` + `fusion-child-extension.ts` + `ui/fusion-model-selector.ts`) | **Removed** (~15k lines) |
+| Delegate (`src/core/delegate/*` + `delegate-extension.ts` + `delegate-child-extension.ts`) | **Removed** (~5k lines) |
+| Claude/Anthropic impersonation (`anthropic-attribution*.ts`) | **Removed** (~3.7k lines) |
+| Attested Pi runs (`attested-pi-*.ts`) | **Removed** (~1k lines) |
+| Context projection & budgeting (`src/core/context/*`) | **Removed** (~1.6k lines) |
+| Pi-agent telemetry (`isAgent` end-to-end) | **Removed** |
+| Dead EventBus request layer | **Removed** |
+| Update check + footer update hint (`update-check.ts`) | **Removed** |
+| TUI footer + seen/unread task state | **Removed** |
+| `/bg-tasks` alias | **Removed** |
+| `pi-launch.ts`, `canonical-json.ts`, `BACKGROUND-TASKS-INSTRUCTIONS.md` | **Removed** |
+
+## What the fork adds / changes
+
+- **`/clean` command + `bg_clean` tool** — delete finished tasks (`session` / `all` / `<id>`). New file `src/core/task-cleanup.ts`; empty run directories are removed after cleanup (tasks live under `~/.pi/agent/tasks`).
+- **Task runtime moved to `~/.pi/agent/tasks`** with the PI extension-config pattern (`pi-background-tasks.json`, `tasksDir`).
+- **KISS packaging** — single entry point `src/extension.ts`, no `dist/`, no tests, no docs tree; fork identity in `package.json`.
+- **Task manager UI** — opens top-right as a fixed 96-column modal (96 % width left the box stuck left on wide terminals); `d` deletes the selected task; both shortcuts registered (Shift↓ / Ctrl+Alt+B); footer options contextual to the selected task; empty-state footer shows only sensible actions; task detail adapts to terminal height (modal title dropped).
+- **`--agent` flag** removed from `/bg` (stale).
+- **Lazy module loader simplified.**
+- **Dependencies** — pi `^1.3.0`, TypeScript `^7.0.2`, `@types/node ^26.6.5`, tsx `^4.23.15`, typebox `^1.4.1`; peer ranges broadened to `|| ^1.0.0` (installs on pi 1.x, still accepts 0.81.1–0.84.0).
+- **biome** lint/format + `tsconfig.json` for `tsc --noEmit`.
+
+## Upstream since the fork base (2.6.9 → 2.6.10)
+
+Checked 2026-10-17. All 4 commits are about one new subsystem, **host-api**: an optional EventBus API (request / response / changed channels, leases, cursors, `~1.8k` lines of code plus docs and tests) for **native front ends** (desktop or mobile job panels). Its own docs state it does **not** change the TUI, the registered tools/commands, the dock, notifications or wake-up behavior.
+
+**Not adopted** — it targets a surface this fork does not ship, and its size/complexity contradict the KISS design.
+
+| Commit | What it is | Adopted |
+| --- | --- | --- |
+| `7781fe3` | land host-api: `host-api.ts`, `host-protocol.ts`, `host-results.ts`, docs, tests | No |
+| `1857b3c` | test(host-api): freeze background UI contract and terminal guard | No |
+| `9923a95` | test(host-api): correct passing group count label | No |
+| `799182f` | chore(release): bump version to 2.6.10 | n/a (this fork uses 0.1.x versioning) |
+
+## Re-checking the divergence
+
+```bash
+# inside this repo — everything this fork changed since the import:
+git diff --stat 990d60a7f0db3b61af80daf9d35607ff90009d75..HEAD
+
+# from any clone of ismailsaleekh/pi-background-tasks — what upstream
+# has done since the fork base (4aceb55):
+git log --oneline 4aceb55..main
+git diff --stat 4aceb55 main
+```

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/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# pi-simple-background-tasks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Durable background shell tasks for Pi.**
+
+A KISS fork of [pi-background-tasks](https://github.com/ismailsaleekh/pi-background-tasks). It keeps the core — running long shell jobs in the background without blocking the session. See [FORK-CHANGES.md](FORK-CHANGES.md) for the full list of changes relative to upstream and how to re-check the divergence.
+
+## Features
+
+- **Run long jobs without blocking**: start a named shell command in the background, keep talking to Pi, and get a completion notification in chat when it finishes.
+- **Durable tasks**: task state is persisted under `~/.pi/agent/tasks`, so it survives session restarts.
+- **Task manager overlay**: a TUI panel lists running and recent tasks with status and bounded output (default **Shift↓**).
+- **Survive Pi reloads**: opt in to keeping a shell task alive across a same-process `/reload`.
+- **Cross-platform**: POSIX shell and Windows (process-group kill).
+
+## Install
+
+```bash
+# Global install from the git main branch
+pi install git:github.com/jlsalvador/pi-simple-background-tasks@main
+
+# Project-local install from git
+pi install git:github.com/jlsalvador/pi-simple-background-tasks@main -l
+```
+
+## Quick start
+
+1. Start a background command:
+
+   ```text
+   /bg --name "Typecheck watch" npm run typecheck -- --watch
+   ```
+
+   `/bg` starts a tracked shell task and returns the task id plus output path. User-launched `/bg` tasks notify in the UI but do not automatically wake a follow-up model turn. Add one leading `--survive-reload` only when the shell process must keep running across a same-process `/reload`.
+
+2. List tasks or open the task manager:
+
+   ```text
+   /jobs
+   ```
+
+3. Read bounded output only when you need it:
+
+   ```text
+   /logs b12ab34c 20000
+   ```
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `bg_run` | Start a background shell command and return a task id plus output path. |
+| `bg_status` | Inspect one task, or list running and recent tasks. |
+| `bg_logs` | Read bounded output from a task. |
+| `bg_kill` | Stop a running task. |
+| `bg_clean` | Delete finished tasks to free disk space. Only terminal tasks are removed; running tasks are reported and left alone. Scope: one task by ID, this session (default), or the whole folder. |
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/bg [--survive-reload] [--name "name"] <command>` | Start a tracked shell command. |
+| `/jobs` | List running and recent tasks. |
+| `/tasks [id]` | Open the task manager overlay. |
+| `/logs <id> [maxBytes]` | Show bounded output from a task. |
+| `/kill <id>` | Stop a running task. |
+| `/clean [session\|all\|<id>]` | Delete finished tasks: one, this session (default), or all. |
+
+**Shift↓** and **Ctrl+Alt+B** both open the task manager.
+
+## Configuration
+
+Configuration follows the PI extension-config pattern. Create `pi-background-tasks.json` in the global or project location; project keys override global keys, and absent keys keep their defaults.
+
+| Location | Path |
+| --- | --- |
+| Global | `~/.pi/agent/extensions/pi-background-tasks.json` |
+| Project | `.pi/pi-background-tasks.json` |
+
+| Key | Type | Default |
+| --- | --- | --- |
+| `tasksDir` | string path | `~/.pi/agent/tasks` |
+
+Example:
+
+```json
+{
+  "tasksDir": "~/my-tasks"
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run check   # tsc --noEmit && biome check .
+npm run fix     # biome check --write .
+```
+
+## License
+
+ISC — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "pi-simple-background-tasks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Durable background shell tasks for Pi. KISS fork of pi-background-tasks.",
+  "type": "module",
+  "license": "ISC",
+  "author": "José Luis Salvador Rufo <salvador.joseluis@gmail.com>",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "background-tasks",
+    "coding-agent",
+    "shell",
+    "tasks",
+    "task-manager",
+    "pi-dev"
+  ],
+  "homepage": "https://github.com/jlsalvador/pi-simple-background-tasks#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jlsalvador/pi-simple-background-tasks.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jlsalvador/pi-simple-background-tasks/issues"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "FORK-CHANGES.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit && biome check .",
+    "fix": "biome check --write ."
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "^0.81.1 || ^0.82.1 || ^0.83.0 || ^0.84.0 || ^1.0.0",
+    "@earendil-works/pi-tui": "^0.81.1 || ^0.82.1 || ^0.83.0 || ^0.84.0 || ^1.0.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@earendil-works/pi-ai": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
+    "@earendil-works/pi-tui": "^1.3.0",
+    "@types/node": "^26.6.5",
+    "tsx": "^4.23.15",
+    "typebox": "^1.4.1",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}