@henryqw/pi-subagent 14.0.0 → 14.0.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.
- package/README.md +53 -38
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,13 +1,9 @@
|
|
|
1
1
|
# `@henryqw/pi-subagent`
|
|
2
2
|
|
|
3
|
-
Delegate bounded work from Main to isolated Pi Roles, or run independent implementation units through a fixed Git Flow.
|
|
3
|
+
Delegate bounded work from Main to isolated Pi Roles, or run independent implementation units through a fixed Git Flow. One Role system covers focused research, review, implementation, parallel work, and ordered chains without loading every detail into Main.
|
|
4
4
|
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
## Why
|
|
8
|
-
|
|
9
|
-
- **Created for**: Pi users who want focused child work without loading every detail into Main.
|
|
10
|
-
- **Advantage**: One Role system covers research, review, implementation, parallel work, and ordered chains.
|
|
6
|
+
|
|
11
7
|
|
|
12
8
|
## Install
|
|
13
9
|
|
|
@@ -18,13 +14,11 @@ pi install npm:@henryqw/pi-subagent
|
|
|
18
14
|
|
|
19
15
|
Run `/task-models` and configure the `fast` profile before delegating.
|
|
20
16
|
|
|
21
|
-
##
|
|
17
|
+
## Works with
|
|
22
18
|
|
|
23
|
-
|
|
24
|
-
| --- | --- |
|
|
25
|
-
| [`@henryqw/pi-task-models`](https://pi.henry.wang/extensions/pi-task-models) | Required. Supplies `fast`, `balanced`, `frontier`, and `fav` model routes. |
|
|
19
|
+
**Required.** [`@henryqw/pi-task-models`](https://pi.henry.wang/extensions/pi-task-models) supplies `fast`, `balanced`, `frontier`, and `fav` model routes.
|
|
26
20
|
|
|
27
|
-
Routes come from `~/.pi/agent/config/pi-task-models/config.json`. It stores explicit task overrides.
|
|
21
|
+
Routes come from `~/.pi/agent/config/pi-task-models/config.json`. It stores explicit task overrides. Missing shared model config warns once because delegation needs a route.
|
|
28
22
|
|
|
29
23
|
## Use
|
|
30
24
|
|
|
@@ -40,13 +34,16 @@ Start with one read-only delegation:
|
|
|
40
34
|
|
|
41
35
|
A separate child returns a bounded report to Main. It creates no saved Pi session and makes model requests through the selected route.
|
|
42
36
|
|
|
43
|
-
|
|
|
44
|
-
| --- | --- |
|
|
45
|
-
| `delegate_task` | Run one bounded task, independent tasks in parallel, or dependent tasks in a chain. |
|
|
46
|
-
| `delegate_flow` | Implement and integrate 1–8 independent Git units. |
|
|
47
|
-
| `delegate_flow_continue` | Repair the one blocked Flow unit once. |
|
|
37
|
+
| Surface | Type | Purpose |
|
|
38
|
+
| --- | --- | --- |
|
|
39
|
+
| `delegate_task` | tool | Run one bounded task, independent tasks in parallel, or dependent tasks in a chain. |
|
|
40
|
+
| `delegate_flow` | tool | Implement and integrate 1–8 independent Git units. |
|
|
41
|
+
| `delegate_flow_continue` | tool | Repair the one blocked Flow unit once. |
|
|
42
|
+
| `pi-subagent-delegated-development` | skill | Guide Main's planning and orchestration. |
|
|
43
|
+
|
|
44
|
+
Pi's built-in tool block shows each call and result.
|
|
48
45
|
|
|
49
|
-
|
|
46
|
+
Select exactly one `delegate_task` shape:
|
|
50
47
|
|
|
51
48
|
```text
|
|
52
49
|
// Single
|
|
@@ -59,21 +56,27 @@ Pi's built-in tool block shows each call and result. Select exactly one `delegat
|
|
|
59
56
|
{ chain: [{ role, name, task, model?, modelClass? }], background? }
|
|
60
57
|
```
|
|
61
58
|
|
|
62
|
-
Main supplies each `name`. It must be a short description, about five words and fewer than 30 characters
|
|
59
|
+
Main supplies each `name`. It must be a short description, about five words and fewer than 30 characters. Names cannot contain C0/C1 control characters such as newlines or terminal escapes. `role` and an explicit `model` also reject those controls.
|
|
63
60
|
|
|
64
|
-
`modelClass` selects `fast`, `balanced`, `frontier`, or `fav`. An explicit call class wins over a Role class
|
|
61
|
+
`modelClass` selects `fast`, `balanced`, `frontier`, or `fav`. An explicit call class wins over a Role class. Without either, the configured task assignment or declared default applies. The route sets the model and exact thinking level.
|
|
65
62
|
|
|
66
|
-
|
|
63
|
+
An explicit `model` (`provider/modelId`) replaces only the route model and must support that thinking level. `background` applies to the whole selected mode, never one entry.
|
|
67
64
|
|
|
68
|
-
|
|
65
|
+
Parallel tasks start together, settle together, and report in input order. Chains are sequential and fail at the first failure. `{previous}` passes only the immediately preceding successful assistant output.
|
|
66
|
+
|
|
67
|
+
Foreground failures throw after keeping bounded sibling and recovery evidence. One call has one aggregate 50 KiB cap for Main-visible text. Live updates show task names and statuses without opaque IDs. Final results show summaries first and full evidence below.
|
|
68
|
+
|
|
69
|
+
Background work belongs to its launching session. Shutdown or reload aborts it and may leave only recoverable-work evidence or no follow-up message.
|
|
69
70
|
|
|
70
71
|
Each entry resolves its own Role, resources, route, and optional isolation. A Role with `isolation: worktree` gets a separate deterministic worktree when available. Non-Git and unborn-`HEAD` contexts can use Main's directory. Other setup failures, including unsafe submodule layouts, reject instead of falling back. Siblings and chain steps never share a created worktree.
|
|
71
72
|
|
|
72
73
|
See the [orchestration guide](./docs/orchestration.md) for full delegation, transport, isolation, and UI behavior.
|
|
73
74
|
|
|
74
|
-
###
|
|
75
|
+
### Skills
|
|
75
76
|
|
|
76
|
-
|
|
77
|
+
The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill guides Main's planning and orchestration. It adds no runtime code, config, or Role installation. `delegate_flow` owns its Git mechanics and validation authority.
|
|
78
|
+
|
|
79
|
+
## Flow
|
|
77
80
|
|
|
78
81
|
Flow requires a clean Main worktree on an attached branch with a committed `HEAD`. Use it only for independent Git changes that can merge in any order. Do not split units that overlap files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.
|
|
79
82
|
|
|
@@ -82,16 +85,20 @@ delegate_flow({ units: [{ id, name, task, modelClass?, validation: [{ command, a
|
|
|
82
85
|
delegate_flow_continue({ guidance, modelClass? })
|
|
83
86
|
```
|
|
84
87
|
|
|
85
|
-
A Flow has 1–8 units with unique non-empty IDs
|
|
88
|
+
A Flow has 1–8 units with unique non-empty IDs and allows one active Flow. It freezes the effective Implementer at start. It freezes the Reviewer only when a unit requests `review`.
|
|
86
89
|
|
|
87
90
|
- Each unit gets one worktree. Implementers run in parallel. Flow handles units in declared order.
|
|
88
91
|
- Flow runs each declared command with its arguments. That validation is authoritative for objective checks.
|
|
89
92
|
- Without `review`, Flow fast-forwards the exact validated tip.
|
|
90
93
|
- With `review`, the Reviewer receives the exact `{base, tip, patchPath}` packet and must return exactly `PASS` before the same integration path. Use `review` only for stated judgment that validation cannot decide.
|
|
91
94
|
|
|
92
|
-
An explicit unit `modelClass` overrides both frozen Roles. Without one, each Role uses its own `modelClass
|
|
95
|
+
An explicit unit `modelClass` overrides both frozen Roles. Without one, each Role uses its own `modelClass`, configured `pi-subagent/delegateTask` assignment, or declared default.
|
|
96
|
+
|
|
97
|
+
One `delegate_flow_continue` can repair an Implementer, validation, or review block in the same worktree. Omitting its class keeps the unit's explicit class and frozen Role defaults. Supplying one replaces both Role defaults for that repair and its later Reviewer launch.
|
|
98
|
+
|
|
99
|
+
A second block is terminal. Rebase and infrastructure failures are terminal.
|
|
93
100
|
|
|
94
|
-
Flow
|
|
101
|
+
Flow has no dependency graph, saved recovery, automatic retry, aggregate review, or post-merge validation.
|
|
95
102
|
|
|
96
103
|
## Config
|
|
97
104
|
|
|
@@ -122,7 +129,7 @@ Malformed or unreadable JSON, a non-object root, unknown keys, and invalid value
|
|
|
122
129
|
|
|
123
130
|
`PI_SUBAGENT_MAX_SUBAGENTS` overrides `maxSubagents` for the session. It must be a positive integer. An invalid value prevents the extension from loading, so `delegate_task` is unavailable.
|
|
124
131
|
|
|
125
|
-
|
|
132
|
+
### Roles
|
|
126
133
|
|
|
127
134
|
Role Markdown files live beside the config file. They require frontmatter and a Markdown system prompt body.
|
|
128
135
|
|
|
@@ -151,24 +158,32 @@ The package always provides these built-in Roles. Their files leave `modelClass`
|
|
|
151
158
|
|
|
152
159
|
Flow uses the effective Implementer and, only when requested, Reviewer. The Scout is not part of Flow.
|
|
153
160
|
|
|
154
|
-
##
|
|
161
|
+
## API
|
|
155
162
|
|
|
156
|
-
|
|
163
|
+
The package root exports `loadRoles`, `resolveRoleSkills`, `resolveRoleLaunch`, `createRoleLaunch`, `createEphemeralSubagentExecutor`, and worktree helpers.
|
|
157
164
|
|
|
158
|
-
|
|
165
|
+
The executor works only inside the active Pi process. It does not discover or start a standalone Node.js Pi installation.
|
|
159
166
|
|
|
160
|
-
|
|
167
|
+
`finalizeChildWorktree` returns the breaking `WorktreePayload` lifecycle union. `pruned` proves zero commits, a clean tree, and removed worktree and branch. `retained` contains measured `commits` and `dirty` values. `recovery` has an actionable `note` and only completed measurements. An omitted recovery measurement is unknown.
|
|
161
168
|
|
|
162
|
-
|
|
169
|
+
See the [public Role and executor API](./docs/orchestration.md#public-role-and-executor-api) for contracts and a `prepare` example. Pass `modelClass` to `resolveRoleLaunch` to override a Role default.
|
|
163
170
|
|
|
164
|
-
##
|
|
171
|
+
## State and storage
|
|
165
172
|
|
|
166
|
-
|
|
173
|
+
Flow state is memory-only.
|
|
167
174
|
|
|
168
|
-
##
|
|
175
|
+
## Data, cost, and privacy
|
|
169
176
|
|
|
170
|
-
|
|
177
|
+
A Role selects base tools, extensions, named Skills, instructions, and optional worktree isolation. Named Skills resolve from Main's effective Pi registry. Unavailable names warn and skip.
|
|
171
178
|
|
|
172
|
-
|
|
179
|
+
Children disable ambient extension and Skill discovery. `tools: []` adds no base tools, but selected extension tools and caller tools still activate. `extensions: []` adds no Role extension bundle. `skills: []` adds no separately named Role Skills, but selected extension Skills still load.
|
|
173
180
|
|
|
174
|
-
|
|
181
|
+
An explicitly selected extension is trusted, not sandboxed. Its tools, Skills, and executable behavior load together. Select fewer trusted extensions to reduce scope. pi-subagent does not guess or remove undocumented dependencies.
|
|
182
|
+
|
|
183
|
+
Parent-only delegation tools and `ask_question` are always excluded. Requested Role or caller tool names are checked after provider loading. Unavailable tools fail before the first model turn.
|
|
184
|
+
|
|
185
|
+
## Limits and recovery
|
|
186
|
+
|
|
187
|
+
Flow never force-deletes recoverable work. Failed or uncertain units, and cleanup refusals after integration, retain their worktree path or branch for recovery.
|
|
188
|
+
|
|
189
|
+
See [Flow mechanics and recovery](./docs/orchestration.md#delegate_flow) for retained-work recovery.
|