pi-better-background-tasks 0.1.2 → 0.1.4

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 (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +47 -59
  3. package/package.json +7 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 1aboveio
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,65 +1,53 @@
1
1
  # pi-better-background-tasks
2
2
 
3
- Generic durable background tasks for [pi](https://pi.dev). The extension lets an
4
- agent start long-running commands or command-based watchers without blocking the
5
- foreground turn. Task metadata and logs are stored under the OS temp directory,
6
- so status and logs remain available across `/reload` and ordinary session use.
7
-
8
- The core is deliberately domain-neutral. GitHub, Mergify, Cloud Build, Vercel,
9
- and similar integrations should be thin presets on top of the generic watcher,
10
- not special cases in the runtime.
11
-
12
- ## Tools
13
-
14
- | Tool | Purpose |
15
- | ---- | ------- |
16
- | `bg_task_spawn` | Start a long-running process and return immediately. |
17
- | `bg_task_watch` | Poll a command until success/failure/timeout. |
18
- | `bg_task_list` | List known tasks. |
19
- | `bg_task_status` | Inspect one task. Compact by default; pass `verbose:true` for full metadata JSON. |
20
- | `bg_task_log` | Read a bounded task log tail by default, or a full log on request. |
21
- | `bg_task_stop` | Cancel a watcher or terminate a process task. |
22
- | `bg_task` | Action-based wrapper for `spawn`, `watch`, `list`, `status`, `log`, `stop`, `clear`. |
23
- | `bg_status` | Small action wrapper for `list`, `status`, `log`, `stop`, `clear`. |
24
-
25
- `clear` dismisses terminal tasks for the active cwd/session so they no longer
26
- count as foreground attention. It keeps metadata and logs on disk for explicit
27
- inspection.
28
-
29
- Callbacks are terminal-only by default. When `callback` is not false, a task that
30
- reaches a terminal state queues one follow-up message telling the foreground
31
- agent which task finished and which tool to call for details.
32
-
33
- Callbacks point to `bg_task_status` first. The default status response is a
34
- compact model-facing summary that omits large command bodies; use
35
- `verbose:true` only when full metadata is required. `bg_task_log` defaults to a
36
- 20-line tail, and `tail_lines: 0` requests the full log explicitly.
37
-
38
- Command watchers default to a 15 minute timeout when `timeout_seconds` is
39
- omitted. Pass `timeout_seconds: 0` to disable the watcher timeout explicitly.
40
- Spawned processes do not get a default timeout.
41
-
42
- ## Examples
43
-
44
- ```json
45
- {
46
- "name": "dev server",
47
- "command": "npm run dev",
48
- "cwd": "/path/to/app"
49
- }
3
+ `pi-better-background-tasks` is a Pi extension for durable background shell tasks, watchers, logs, and status inspection.
4
+
5
+ ## Quick Answer
6
+
7
+ Use `pi-better-background-tasks` when a command should keep running while the foreground Pi session stays free. It is best for dev servers, long scripts, queue watchers, deploy checks, log tails, and other command-driven work.
8
+
9
+ ## Core Features
10
+
11
+ - Start long-running commands without blocking the current turn.
12
+ - Watch commands until success, failure, or timeout.
13
+ - Keep task metadata and logs available across reloads.
14
+ - Show active work in Pi's background-work navigator.
15
+
16
+ ## Install
17
+
18
+ ```sh
19
+ pi install npm:pi-better-background-tasks
20
+ ```
21
+
22
+ Try it for one run:
23
+
24
+ ```sh
25
+ pi -e npm:pi-better-background-tasks
50
26
  ```
51
27
 
52
- ```json
53
- {
54
- "name": "wait for success",
55
- "command": "node ./scripts/check-status.js --json",
56
- "interval_seconds": 15,
57
- "timeout_seconds": 600,
58
- "success_when": { "type": "json_path_equals", "path": "$.status", "value": "done" },
59
- "failure_when": { "type": "json_path_equals", "path": "$.status", "value": "failed" }
60
- }
28
+ ## When To Use
29
+
30
+ Use this package for shell commands that need logs, status, cancellation, or completion notifications across a Pi turn.
31
+
32
+ Do not use it for short commands where the foreground session should wait for the result directly.
33
+
34
+ ## Compatibility
35
+
36
+ | Requirement | Support |
37
+ |-------------|---------|
38
+ | Pi | Required |
39
+ | Install method | `pi install npm:pi-better-background-tasks` |
40
+ | Development runtime | Node.js 22+ |
41
+
42
+ ## Update Or Remove
43
+
44
+ ```sh
45
+ pi update npm:pi-better-background-tasks
46
+ pi remove npm:pi-better-background-tasks
61
47
  ```
62
48
 
63
- Commands run through `/bin/bash -lc` by default so shell-mode watchers behave
64
- consistently across sessions. Set `PI_BETTER_BACKGROUND_TASKS_SHELL` to override
65
- that shell, or pass `argv` and `shell:false` to avoid shell parsing.
49
+ ## More Detail
50
+
51
+ - Repository: https://github.com/1aboveio/pi-better-harness
52
+ - Detailed notes: https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-background-tasks/docs/usage.md
53
+ - License: https://github.com/1aboveio/pi-better-harness/blob/main/LICENSE
package/package.json CHANGED
@@ -1,12 +1,15 @@
1
1
  {
2
2
  "name": "pi-better-background-tasks",
3
- "version": "0.1.2",
4
- "description": "Generic durable background task and watcher tools for pi.",
3
+ "version": "0.1.4",
4
+ "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
5
+ "license": "MIT",
5
6
  "type": "module",
6
7
  "keywords": [
7
8
  "pi-package",
8
9
  "pi-extension",
9
- "background-tasks"
10
+ "pi",
11
+ "background-tasks",
12
+ "watchers"
10
13
  ],
11
14
  "pi": {
12
15
  "extensions": [
@@ -50,4 +53,4 @@
50
53
  "vitest": "^3.0.0",
51
54
  "typebox": "^1.1.38"
52
55
  }
53
- }
56
+ }