pi-long-task 0.3.0 → 0.3.1

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 (2) hide show
  1. package/README.md +90 -22
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,29 +1,40 @@
1
1
  # Pi Long Task
2
2
 
3
- Pi Long Task is a Pi extension that turns a larger coding request into a clear TODO plan, works through the tasks one by one, and reports the result.
3
+ Pi Long Task is a Pi extension that breaks large coding requests into tracked TODOs, executes them in isolated worker sessions, shows progress in a sidebar, and optionally commits completed work.
4
4
 
5
- It is useful when you want Pi to handle a multi-step change without losing track of what has been done, what is still left, and whether changes should be committed.
5
+ Use it when a coding request is bigger than one focused interaction. Pi Long Task creates or cleans up the TODO plan, hands each TODO to a fresh worker session, tracks every attempt, and keeps the run artifacts so you can inspect what happened later.
6
6
 
7
- ## What you get
7
+ ## Why use it
8
8
 
9
- When you ask Pi to run a long task, it will:
9
+ - **Take on bigger tasks:** split broad product, refactor, testing, or cleanup requests into smaller TODOs that Pi can complete one at a time.
10
+ - **Track progress visibly:** see the active TODO, inferred `**Status:**` subtasks, completed/failed/blocked counts, and remaining work in Pi's long-task sidebar.
11
+ - **Recover with retries:** tasks that do not report completion can be retried with context from previous attempts instead of losing the thread.
12
+ - **Commit safely when asked:** enable commits for completed task work, while generated run files and pre-existing dirty files are kept out of those commits.
13
+ - **Keep task artifacts:** every run writes a generated `TODO.md`, generated `TASK_RESULT.md`, attempt summaries, and final status under `tmp/pi-long-task/<run-id>/`.
14
+ - **Watch cost visibility:** worker spend is captured and surfaced in progress and final summaries when usage cost data is available.
10
15
 
11
- 1. Recognize natural-language requests like "run a long task with commits" and route them to `pi_long_task`.
12
- 2. Create or clean up a TODO plan from your request.
13
- 3. Work through each unfinished TODO task in order.
14
- 4. Show the current task and inferred subtask progress while it runs.
15
- 5. Record progress and final results under `tmp/pi-long-task/<run-id>/`.
16
- 6. Return a summary with completed, failed, blocked, and remaining task counts.
17
- 7. Optionally commit completed work after each task.
16
+ ## What happens during a run
17
+
18
+ When you ask Pi to run a long task, Pi Long Task:
19
+
20
+ 1. Recognizes natural-language requests like "run a long task with commits" and routes them to `pi_long_task`.
21
+ 2. Creates or cleans up a TODO plan from your request.
22
+ 3. Works through each unfinished TODO task in order using isolated worker sessions.
23
+ 4. Shows the current task and inferred subtask progress in a sidebar while it runs.
24
+ 5. Retries unfinished tasks up to the configured attempt limit.
25
+ 6. Records progress, task artifacts, and final results under `tmp/pi-long-task/<run-id>/`.
26
+ 7. Returns a summary with completed, failed, blocked, and remaining task counts, plus worker spend when available.
27
+ 8. Optionally commits completed work after each task.
18
28
 
19
29
  A finished run gives you:
20
30
 
21
31
  - a concise status summary in Pi
22
32
  - a generated `TODO.md`
23
33
  - a generated `TASK_RESULT.md`
24
- - live progress for the active task and its `**Status:**` checkbox subtasks
34
+ - live sidebar progress for the active task and its `**Status:**` checkbox subtasks
35
+ - task attempt history and any remaining or blocked tasks clearly listed
36
+ - worker spend when cost data is available
25
37
  - commit hashes when commits were enabled and created
26
- - any remaining or blocked tasks clearly listed
27
38
 
28
39
  ## Install
29
40
 
@@ -59,18 +70,74 @@ Or update all installed Pi extension packages:
59
70
  pi update --extensions
60
71
  ```
61
72
 
62
- ## Usage
73
+ ## Quick start examples
74
+
75
+ Use natural language; you do not need to mention `pi_long_task` explicitly. Copy one of these prompts and replace the quoted work with your own task.
63
76
 
64
- Use natural language; you do not need to mention `pi_long_task` explicitly:
77
+ Run with commits enabled, so each completed TODO can be committed separately:
78
+
79
+ ```text
80
+ Run a long task with commits to implement the TODOs in @TODO.md.
81
+ ```
82
+
83
+ ```text
84
+ Run a long task with commits to refactor the checkout flow, update the tests, and commit each completed task.
85
+ ```
86
+
87
+ Run without commits when you want to review all changes yourself before committing:
65
88
 
66
89
  ```text
67
90
  Run a long task without commits to add tests for the parser and fix any failures.
68
91
  ```
69
92
 
70
93
  ```text
71
- Run a long task with commits to implement the TODOs in @TODO.md.
94
+ Run a long task without commits to audit the README examples and leave the final diff uncommitted.
72
95
  ```
73
96
 
97
+ ## What it looks like
98
+
99
+ Pi keeps the active worker transcript in the main content area and shows the run timeline in the sidebar:
100
+
101
+ ```text
102
+ ┌─ Main content: active worker activity ───────────────┬─ Pi Long Task sidebar ───────────────┐
103
+ │ Worker TODO 2 — Add parser tests │ Progress: 2/5 tasks complete (40%) │
104
+ │ │ Worker spend: $0.18 │
105
+ │ $ npm test -- parser │ │
106
+ │ ✓ parser handles nested arrays │ Timeline │
107
+ │ ✗ parser rejects invalid escapes │ ● TODO 1 Rewrite intro done │
108
+ │ │ ● TODO 2 Add parser tests active │
109
+ │ Editing src/parser.test.ts... │ ◌ add edge-case fixtures │
110
+ │ Re-running focused tests after fix... │ ◌ fix failing assertions │
111
+ │ │ ○ TODO 3 Update docs next │
112
+ │ │ ○ TODO 4 Validate install later │
113
+ │ │ │
114
+ │ The worker reports commands, file edits, and result │ Sidebar tracks task statuses, │
115
+ │ details here while the current TODO is running. │ subtask progress, timeline, spend. │
116
+ └──────────────────────────────────────────────────────┴──────────────────────────────────────┘
117
+ ```
118
+
119
+ ## How it works
120
+
121
+ Pi Long Task coordinates a long request from planning through task completion:
122
+
123
+ 1. **Plan the work:** it creates a TODO plan from your request, or normalizes pasted TODO markdown so each item can be tracked consistently.
124
+ 2. **Run isolated workers:** each TODO is assigned to its own fresh worker session with the relevant task text, global instructions, attempt history, and commit setting.
125
+ 3. **Stream progress back:** the active worker's activity streams into the main Pi thread, so you can follow commands, edits, verification, and the final `TASK_RESULT` as they happen.
126
+ 4. **Show every task in the sidebar:** the sidebar lists the full run timeline, including completed, active, upcoming, failed, or blocked tasks and inferred subtask progress from each task's `**Status:**` checklist.
127
+ 5. **Write run artifacts:** the coordinator writes the generated/normalized `TODO.md`, `TASK_RESULT.md`, attempt summaries, and final run details to `tmp/pi-long-task/<run-id>/`.
128
+ 6. **Commit only when enabled:** if `commit` is `true`, Pi Long Task may create a commit after each completed task using only eligible task changes. If commits are disabled, no commits are created; even when enabled, commits can be skipped when there are no eligible changes or the task outcome is not commit-worthy.
129
+
130
+ ## Feature reference
131
+
132
+ - **Sidebar task timeline:** every TODO appears in the sidebar with past, current, and future statuses so you can distinguish completed, active, upcoming, failed, blocked, and remaining work at a glance.
133
+ - **Main-thread worker activity:** the active worker streams commands, edits, verification, and its per-task `TASK_RESULT` back into the main Pi conversation.
134
+ - **Cost visibility:** worker spend is included in Pi Long Task progress and is added to the main Pi `$ spent` total when cost data is available.
135
+ - **Result and TODO artifacts:** each run keeps the generated or normalized `TODO.md`, aggregate `TASK_RESULT.md`, per-attempt summaries, and final run details under `tmp/pi-long-task/<run-id>/`.
136
+ - **Commit-safe behavior:** when commits are enabled, Pi Long Task commits only eligible completed-task changes and skips generated run files.
137
+ - **Dirty-worktree protection:** files that were dirty before a worker started are not included in Pi Long Task commits, keeping your existing local work separate.
138
+
139
+ ## Usage
140
+
74
141
  You can also call the tool explicitly.
75
142
 
76
143
  Run without commits:
@@ -79,7 +146,7 @@ Run without commits:
79
146
  Use pi_long_task with inputText "add tests for the parser and fix any failures" and commit false.
80
147
  ```
81
148
 
82
- Run and allow commits:
149
+ Run with commits:
83
150
 
84
151
  ```text
85
152
  Use pi_long_task with inputText "implement the TODOs in @TODO.md" and commit true.
@@ -137,9 +204,9 @@ This lets you keep existing local work separate from Pi Long Task changes.
137
204
 
138
205
  Commit messages are generated from the task title and adjusted to resemble recent commit-message style in the repository. Pi Long Task does not prefix commits with generated labels like `Complete TODO 1 — ...`.
139
206
 
140
- ## Validate the install
207
+ ## Development and validation
141
208
 
142
- Run the local checks:
209
+ Run the local development checks:
143
210
 
144
211
  ```bash
145
212
  cd /path/to/pi-long-task
@@ -160,10 +227,11 @@ npm run smoke:native
160
227
 
161
228
  That smoke test creates disposable git repos and verifies both `commit: false` and `commit: true` runs.
162
229
 
163
- ## Notes
230
+ ## Limitations and expectations
164
231
 
165
- - Tasks run one at a time.
166
- - Real runs require a working Pi model/login or API key.
232
+ - Tasks run sequentially, one TODO at a time; Pi Long Task prioritizes isolation, progress tracking, and safe handoff over parallel execution.
233
+ - Real runs require usable Pi model credentials, such as a working Pi login or API key for the selected model.
234
+ - Worker spend is added to the main Pi `$ spent` total as cost-only usage. Token counts are not merged into the main thread because worker sessions have separate context windows, and merging their token usage would corrupt the main conversation's context statistics.
167
235
  - Run artifacts are written under `tmp/pi-long-task/<run-id>/`.
168
236
 
169
237
  ## License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-long-task",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "type": "module",
5
5
  "description": "Pi extension for breaking down and running long coding tasks safely.",
6
6
  "keywords": [