pi-background-tasks 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/PUBLISHING.md +10 -8
  2. package/README.md +64 -9
  3. package/TESTING.md +103 -0
  4. package/TEST_PLAN.md +91 -0
  5. package/extensions/background-tasks.ts +1 -1305
  6. package/package.json +25 -2
  7. package/src/core/common.ts +24 -0
  8. package/src/extension.ts +1244 -0
  9. package/src/testing/normalize.ts +3 -0
  10. package/src/ui/background-tasks-manager.ts +565 -0
package/PUBLISHING.md CHANGED
@@ -12,12 +12,14 @@ This package is ready for both npm publishing and standalone git publishing.
12
12
 
13
13
  ```bash
14
14
  cd packages/pi-background-tasks
15
+ npm run test
16
+ npm run test:full
15
17
  npm run smoke
16
18
  npm pack --dry-run
17
19
  npm view pi-background-tasks name version --json
18
20
  ```
19
21
 
20
- At creation time, `npm view pi-background-tasks` returned 404, so the unscoped name appeared available.
22
+ `pi-background-tasks` is already published; bump `package.json` before each npm publish.
21
23
 
22
24
  ## Publish to npm
23
25
 
@@ -30,8 +32,8 @@ npm publish --access public
30
32
  Pi install smoke after publish:
31
33
 
32
34
  ```bash
33
- pi -e npm:pi-background-tasks@0.1.0 --offline --no-tools --no-session -p "/jobs"
34
- pi install npm:pi-background-tasks@0.1.0
35
+ pi -e npm:pi-background-tasks@0.2.0 --offline --no-tools --no-session -p "/jobs"
36
+ pi install npm:pi-background-tasks@0.2.0
35
37
  ```
36
38
 
37
39
  ## Publish to git
@@ -42,19 +44,19 @@ Because Pi git package installs treat the repository root as the package root, d
42
44
  cd packages/pi-background-tasks
43
45
  git init
44
46
  git add .
45
- git commit -m "Initial pi-background-tasks package"
47
+ git commit -m "Release pi-background-tasks"
46
48
  git branch -M main
47
49
  git remote add origin git@github.com:ismailsaleekh/pi-background-tasks.git
48
50
  git push -u origin main
49
- git tag v0.1.0
50
- git push origin v0.1.0
51
+ git tag v0.2.0
52
+ git push origin v0.2.0
51
53
  ```
52
54
 
53
55
  Pi install smoke after git tag:
54
56
 
55
57
  ```bash
56
- pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.1.0 --offline --no-tools --no-session -p "/jobs"
57
- pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.1.0
58
+ pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.2.0 --offline --no-tools --no-session -p "/jobs"
59
+ pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.2.0
58
60
  ```
59
61
 
60
62
  ## pi.dev/packages
package/README.md CHANGED
@@ -2,44 +2,74 @@
2
2
 
3
3
  Claude-Code-like explicit background shell task manager for [Pi](https://pi.dev/).
4
4
 
5
- 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.
5
+ This package adds named, tracked background shell jobs with durable output files, bounded log reads, kill/timeout safety, task-owned context-window telemetry, a focused footer-dock task manager, `/tasks` fallback UI, and completion notifications that can wake the agent when LLM-launched work finishes.
6
6
 
7
7
  ## Install
8
8
 
9
9
  From npm after publish:
10
10
 
11
11
  ```bash
12
- pi install npm:pi-background-tasks@0.1.0
12
+ pi install npm:pi-background-tasks@0.2.0
13
13
  ```
14
14
 
15
15
  From git after pushing this package to its standalone repository and tagging:
16
16
 
17
17
  ```bash
18
- pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.1.0
18
+ pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.2.0
19
19
  ```
20
20
 
21
21
  For project-local install:
22
22
 
23
23
  ```bash
24
- pi install -l npm:pi-background-tasks@0.1.0
24
+ pi install -l npm:pi-background-tasks@0.2.0
25
25
  ```
26
26
 
27
27
  ## Commands
28
28
 
29
- - `/bg <command>` — start a tracked background shell command.
29
+ - `/bg [--name "Task name"] <command>` — start a named tracked background shell command.
30
30
  - `/jobs` — list running and recent completed/failed/killed tasks.
31
31
  - `/logs <id> [maxBytes]` — show bounded tail output and full output path.
32
32
  - `/kill <id>` — stop a running task.
33
- - `/tasks` or `/bg-tasks` — open the interactive task manager UI.
33
+ - `/tasks` or `/bg-tasks` — fallback command to open the task manager UI.
34
+
35
+ ## Footer dock UX
36
+
37
+ When tasks are active or unseen completions/failures exist, Pi shows a compact footer status:
38
+
39
+ ```text
40
+ bg 2 running · Shift↓
41
+ bg 1 running · 1 failed · Shift↓
42
+ bg 2 done · Shift↓
43
+ ```
44
+
45
+ Press `Shift+Down` to open the focused bottom dock. Arrow keys are captured only while the dock is focused. Each task row shows context-window usage reported by that specific background task, for example `ctx 21.0%/200k`; tasks that do not report their own context show `ctx —` rather than the parent Pi session's usage. Finished-task badges intentionally remain visible until acknowledged; press uppercase `C` (`Shift+C`) from the main UI to clear finished background-task notices without opening the dock.
46
+
47
+ Dock controls:
48
+
49
+ | Key | Action |
50
+ |---|---|
51
+ | `Shift+Down` | Open focused background-task dock |
52
+ | `C` / `Shift+C` | Clear finished-task footer notices from the main UI |
53
+ | `↑` / `↓` | Select task |
54
+ | `PageUp` / `PageDown` | Page task list |
55
+ | `Enter` / `→` | Inspect logs/details |
56
+ | `←` | Return from details to list |
57
+ | `h` | Toggle recent history |
58
+ | `k` | Stop selected running task |
59
+ | `a` / `K` | Stop all running tasks, with confirmation |
60
+ | `r` | Refresh detail tail |
61
+ | `R` | Rerun selected command |
62
+ | `c` | Show copyable output path |
63
+ | `x` / `Esc` / `q` | Close dock |
34
64
 
35
65
  ## LLM tools
36
66
 
37
- - `bg_run` — start long-running commands without blocking the conversation.
67
+ - `bg_run` — start named long-running commands without blocking the conversation.
38
68
  - `bg_status` — inspect one task or all recent tasks.
39
69
  - `bg_logs` — read bounded task output.
40
70
  - `bg_kill` — stop a running task.
41
71
 
42
- `bg_run` defaults to `triggerOnCompletion: true`, so completion notifications trigger a follow-up agent turn. User-launched `/bg` jobs are display-only by default.
72
+ `bg_run` requires a concise `name` for the footer dock, plus the shell `command`. It defaults to `triggerOnCompletion: true`, so completion notifications trigger a follow-up agent turn. User-launched `/bg` jobs and UI reruns are display-only by default.
43
73
 
44
74
  ## Runtime files
45
75
 
@@ -61,9 +91,34 @@ These are runtime artifacts and should remain gitignored.
61
91
  - Running tasks are cleaned up on Pi session shutdown/reload.
62
92
  - Cross-Pi-restart process reattachment and Ctrl+B backgrounding of already-running foreground tools are intentionally out of scope.
63
93
 
64
- ## Development smoke
94
+ ## Development and QA
95
+
96
+ Default QA gate:
97
+
98
+ ```bash
99
+ npm run test
100
+ ```
101
+
102
+ Smoke and release checks:
65
103
 
66
104
  ```bash
67
105
  npm run smoke
68
106
  npm run pack:dry-run
69
107
  ```
108
+
109
+ Full interactive QA gate:
110
+
111
+ ```bash
112
+ npm run test:full
113
+ ```
114
+
115
+ The suite includes typecheck, unit, SDK, RPC, component, package, and PTY/TUI coverage for the focused dock and `Shift+Down` shortcut.
116
+
117
+ Note: the repo QA standard now requires exhaustive coverage of every public behavior and plausible edge case. This package passes the current baseline gates, but `TEST_PLAN.md` tracks remaining exhaustive-coverage work for restart/rerun, all dock keys, command/tool edge cases, lifecycle safety paths, notification follow-up, footer badges, package distribution edge cases, and cross-platform mocks.
118
+
119
+ This package follows the repo-wide Pi extension QA standard documented in:
120
+
121
+ - [`../EXTENSION_QA_STANDARD.md`](../EXTENSION_QA_STANDARD.md)
122
+ - [`../EXTENSION_TESTING_PLAYBOOK.md`](../EXTENSION_TESTING_PLAYBOOK.md)
123
+ - [`TEST_PLAN.md`](TEST_PLAN.md)
124
+ - [`TESTING.md`](TESTING.md)
package/TESTING.md ADDED
@@ -0,0 +1,103 @@
1
+ # pi-background-tasks Testing
2
+
3
+ This package follows the repo-wide Pi extension QA standard:
4
+
5
+ - [`../EXTENSION_QA_STANDARD.md`](../EXTENSION_QA_STANDARD.md)
6
+ - [`../EXTENSION_TESTING_PLAYBOOK.md`](../EXTENSION_TESTING_PLAYBOOK.md)
7
+ - [`TEST_PLAN.md`](TEST_PLAN.md)
8
+
9
+ ## Current commands
10
+
11
+ Default gate:
12
+
13
+ ```bash
14
+ npm run test
15
+ ```
16
+
17
+ This runs:
18
+
19
+ ```bash
20
+ npm run typecheck
21
+ npm run test:unit
22
+ npm run test:sdk
23
+ npm run test:rpc
24
+ npm run test:component
25
+ npm run test:package
26
+ ```
27
+
28
+ Full interactive gate:
29
+
30
+ ```bash
31
+ npm run test:full
32
+ ```
33
+
34
+ This runs the default gate plus:
35
+
36
+ ```bash
37
+ npm run test:pty
38
+ ```
39
+
40
+ Smoke/release checks:
41
+
42
+ ```bash
43
+ npm run smoke
44
+ npm run pack:dry-run
45
+ ```
46
+
47
+ Current smoke:
48
+
49
+ ```bash
50
+ pi --no-extensions -e ./extensions/background-tasks.ts --offline --no-tools --no-session -p "/jobs"
51
+ ```
52
+
53
+ Smoke proves loadability only; completion requires `npm run test`, `npm run test:full`, and `npm run pack:dry-run`.
54
+
55
+ ## Required isolated environment
56
+
57
+ Automated tests run with isolated temp project/agent/session directories and should use:
58
+
59
+ ```bash
60
+ PI_OFFLINE=1
61
+ PI_SKIP_VERSION_CHECK=1
62
+ PI_TELEMETRY=0
63
+ CI=1
64
+ ```
65
+
66
+ Tests must not use the user's real `~/.pi/agent`.
67
+
68
+ ## Coverage summary
69
+
70
+ Implemented coverage includes:
71
+
72
+ - tools: `bg_run`, `bg_status`, `bg_logs`, `bg_kill`, including unknown/ambiguous IDs, completed-kill failure, legacy no-name preparation, head/tail truncation, and notification on/off behavior
73
+ - commands: `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks` discovery, happy paths, malformed `/bg`, unknown/ambiguous IDs, completed-task `/kill`, byte-limit normalization, and RPC no-hang fallback behavior
74
+ - shortcut/UI: component coverage for focused dock list/detail/key handling, empty/history/unread states, paging, close aliases, stop/stop-all/rerun/path actions, missing output files; SDK coverage for explicit `Shift+C` finished-notice clearing; and PTY coverage for `/tasks`, real `Shift+Down`, detail/back/history/stop/close
75
+ - runtime files: output and metadata files under `.pi/tasks/`, task-owned context-window telemetry snapshots, metadata after completion/failure, local tarball install contents
76
+ - safety: kill, already-finished kill failure, timeout failure, spawn failure, low output-cap failure, multi-task shutdown cleanup
77
+ - package: manifest, docs, `pi.extensions`, peer dependency/import parity, packed runtime files, tarball-install smoke, and artifact exclusion
78
+
79
+ ## PTY notes
80
+
81
+ `test:pty` uses `/usr/bin/expect` to drive a real pseudo-terminal. It verifies:
82
+
83
+ - `/tasks` opens the focused dock and closes with `x`.
84
+ - A named `/bg` task appears in the dock when opened with xterm `Shift+Down` (`ESC [ 1 ; 2 B`).
85
+
86
+ ## Artifact policy
87
+
88
+ Use package-local or repo-level artifacts if future snapshot/log persistence is needed:
89
+
90
+ ```text
91
+ artifacts/pi-extension-tests/pi-background-tasks/
92
+ ├── summary.json
93
+ ├── rpc-events.jsonl
94
+ ├── tui-ansi.log
95
+ ├── screen.normalized.txt
96
+ └── snapshots/
97
+ ```
98
+
99
+ Normalize volatile values before snapshotting: task IDs, session IDs, PIDs, timestamps, durations, temp paths, and `.pi/tasks/<session-pid>/...` run directories.
100
+
101
+ ## Remaining full exhaustive coverage work
102
+
103
+ The package now has expanded edge-case coverage across the default and full gates. Remaining hardening items tracked in [`TEST_PLAN.md`](TEST_PLAN.md) are narrower: deeper registry extraction/race unit tests, scripted-provider validation of actual follow-up agent turns, exhaustive real-PTY coverage for every secondary dock key (`a`/`K`, `R`, `c`, page keys), process-tree kill fallback mocking, pruning, and Windows-specific shell/path/kill mocks.
package/TEST_PLAN.md ADDED
@@ -0,0 +1,91 @@
1
+ # pi-background-tasks Test Plan
2
+
3
+ This package follows:
4
+
5
+ - [`../EXTENSION_PACKAGE_STANDARD.md`](../EXTENSION_PACKAGE_STANDARD.md)
6
+ - [`../EXTENSION_QA_STANDARD.md`](../EXTENSION_QA_STANDARD.md)
7
+ - [`../EXTENSION_TESTING_PLAYBOOK.md`](../EXTENSION_TESTING_PLAYBOOK.md)
8
+
9
+ ## Package
10
+
11
+ | Field | Value |
12
+ |---|---|
13
+ | Package | `pi-background-tasks` |
14
+ | Extension entrypoint | `extensions/background-tasks.ts` |
15
+ | Public commands | `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks` |
16
+ | Public tools | `bg_run`, `bg_status`, `bg_logs`, `bg_kill` |
17
+ | Shortcuts | `Shift+Down`, `Shift+C` |
18
+ | Custom UI | footer status + focused bottom dock overlay |
19
+ | Custom provider | no |
20
+ | Runtime files/state | `.pi/tasks/<session-id>-<pid>/<task-id>.output`, `.pi/tasks/<session-id>-<pid>/<task-id>.json` |
21
+
22
+ ## Required gates
23
+
24
+ | Gate | Command | Required in default `npm run test`? | Status |
25
+ |---|---|---:|---|
26
+ | Typecheck | `npm run typecheck` | yes | implemented |
27
+ | Unit | `npm run test:unit` | yes | implemented |
28
+ | SDK | `npm run test:sdk` | yes | implemented |
29
+ | RPC | `npm run test:rpc` | yes | implemented |
30
+ | Component | `npm run test:component` | yes | implemented |
31
+ | Package | `npm run test:package` | yes | implemented |
32
+ | PTY/TUI | `npm run test:pty` | full gate | implemented |
33
+ | Pack dry run | `npm run pack:dry-run` | release gate | implemented |
34
+ | Smoke | `npm run smoke` | no | implemented; load-only |
35
+
36
+ ## Feature coverage matrix
37
+
38
+ | Feature | Public surface | Unit | SDK | RPC | Component | PTY | Package | Scripted provider | Notes |
39
+ |---|---|---:|---:|---:|---:|---:|---:|---:|---|
40
+ | Start background command from UI command | `/bg` | yes | | yes | | yes | | | Unit covers `--name`; RPC/PTY start real processes. |
41
+ | List tasks | `/jobs` | | | yes | | | | | RPC asserts running and killed task rows. |
42
+ | Show bounded logs | `/logs <id> [maxBytes]` | yes | | yes | | | | | Unit covers bounded reads; RPC verifies output/path. |
43
+ | Kill running task | `/kill <id>` | | yes | yes | | | | | SDK tool and RPC slash command. |
44
+ | Open task manager fallback | `/tasks`, `/bg-tasks` | | | discovery | yes | yes | | | Component covers dock; PTY covers `/tasks`. |
45
+ | Start background command from LLM tool | `bg_run` | yes | yes | | | | | optional | SDK starts named commands. |
46
+ | Inspect task status | `bg_status` | | yes | | | | | | SDK polls exact IDs and validates shutdown state. |
47
+ | Read task logs | `bg_logs` | yes | yes | | | | | | SDK verifies content. |
48
+ | Stop task from LLM tool | `bg_kill` | | yes | | | | | | Covers running kill and already-finished loud failure. |
49
+ | Completion notification | custom message `background-task-notification` | | manual/runtime | | renderer via typecheck | | | optional | Live runtime smoke previously verified; scripted-provider follow-up remains optional hardening. |
50
+ | Footer status | `ctx.ui.setStatus` | | load path + clear shortcut | | render semantics | yes | | | SDK verifies `C clear` persistence/clear; PTY verifies Shift+Down dock path after footer-visible task. |
51
+ | Per-task context usage | task row/detail + metadata | | yes | | yes | | | | SDK verifies task-owned telemetry is captured and parent `ctx.getContextUsage()` is not used; component verifies list/detail rendering plus `ctx —` placeholder. |
52
+ | Focused dock list | overlay component | | | | yes | yes | | | Selection/actions/history tested. |
53
+ | Focused dock detail | overlay component | | | | yes | | | | Tail read, output box, return-to-list tested. |
54
+ | Dock stop selected | `k` | | | | yes | | | | Component. |
55
+ | Dock stop all | `a`/`K` | | | | yes | | | | Component confirmation. |
56
+ | Dock rerun | `R` | | | | yes | | | | Component. |
57
+ | Dock close | `x`/`Esc`/`q` | | | | yes | yes | | | Component + PTY. |
58
+ | Shortcut opens dock | `Shift+Down` | | registration | | | yes | | | PTY sends xterm `ESC [ 1 ; 2 B`. |
59
+ | Shortcut clears finished notices | `Shift+C` / `C` | | yes | | | | | | SDK invokes registered shortcut and asserts finished notices remain until explicit clear. |
60
+ | Runtime output files | `.pi/tasks/...output` | yes | yes | | | | | | SDK asserts existence. |
61
+ | Runtime metadata files | `.pi/tasks/...json` | | yes | | | | | | SDK asserts shape/status/name/context usage. |
62
+ | Timeout kills task | `timeoutSeconds` | | yes | | | | | | SDK. |
63
+ | Output cap kills task | `PI_BG_MAX_OUTPUT_BYTES` | | | yes | | | | | RPC runs with a low cap and asserts failed status/log notice. |
64
+ | Shutdown cleanup | `session_shutdown` | | yes | | | | | | SDK asserts multiple running tasks become killed. |
65
+ | Package manifest | `package.json` | | | | | | yes | | Keywords, `pi.extensions`, files. |
66
+ | Pack contents | `npm pack --dry-run` | | | | | | yes | | Runtime files included. |
67
+
68
+ ## Remaining hardening coverage
69
+
70
+ The expanded suite now covers the major public command/tool/UI/package edge cases. The rows below are the residual hardening items that still require deeper extraction, mocks, or scripted-provider infrastructure before the package can be called exhaustively complete under the strictest interpretation of the repo QA standard.
71
+
72
+ | Gap | Owner | Date | Reason | Planned fix |
73
+ |---|---|---|---|---|
74
+ | Process registry still mostly lives in `src/extension.ts` | package maintainer | 2026-05-27 | UI was extracted; deeper registry extraction remains | Move process lifecycle into `src/core/registry.ts` and unit-test state transitions/races directly. |
75
+ | Restart/rerun not exhaustively tested in live PTY | package maintainer | 2026-05-27 | Component covers `R` from list/detail; PTY currently covers detail/back/history/stop/close but not real rerun | Add PTY cases for `R` from completed/killed/failed tasks, inherited fields, new ID, and display-only notification defaults. |
76
+ | Dock key map not exhaustively covered in PTY | package maintainer | 2026-05-27 | Component covers full key map; PTY covers `/tasks`, `Shift+Down`, `Enter`, `←`, `h`, `k`, `r`, `x` | Add PTY cases for `↑/↓`, page keys, `a`/`K`, `R`, `c`, failed/unseen/done badges, ordering, and multiple running tasks. |
77
+ | Process lifecycle/safety edge cases incomplete | package maintainer | 2026-05-27 | Timeout/shutdown/kill/spawn-failure/output-cap covered; lower-level races need extraction/mocks | Add tests for process-tree fallback where mockable, duplicate finalization prevention, duplicate notification prevention under races, metadata-after-notification ordering under write failures, and pruning old tasks. |
78
+ | Completion follow-up turn not deterministic | package maintainer | 2026-05-27 | SDK now verifies custom message XML/details and `notifyOnCompletion:false`; live runtime smoke verified wakeups | Add scripted-provider tests for `/bg` display-only default, `bg_run` wakeup default, failed notification error fields, and actual follow-up trigger behavior. |
79
+ | Footer/status behavior could be deeper | package maintainer | 2026-05-27 | SDK covers explicit clear and running/done persistence; component covers seen-state behavior and PTY observes dock path; full status protocol assertions are still thin | Add RPC/SDK assertions for failed/stopped count combinations and focused label. |
80
+ | Cross-platform behavior not covered | package maintainer | 2026-05-27 | Current tests run on local POSIX/macOS | Add unit/mocked coverage for Windows shell invocation, path separator handling, and kill fallback semantics. |
81
+
82
+ ## Acceptance checklist
83
+
84
+ - [x] `npm run test` passes offline in isolated temp dirs.
85
+ - [x] `npm run test:full` validates baseline real TUI/PTY behavior.
86
+ - [x] `npm run pack:dry-run` passes.
87
+ - [ ] README claims and all plausible edge cases are exhaustively mapped in this test plan.
88
+ - [ ] Every listed edge case has automated coverage at the lowest reliable layer.
89
+ - [x] No real LLM/API/network dependency in default tests.
90
+ - [x] No dependency on user/global `~/.pi/agent` for SDK/RPC/PTY tests.
91
+ - [x] Volatile output is normalized in snapshot-style assertions where applicable.