@henryqw/pi-subagent 8.0.0 → 8.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 +136 -30
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# `@henryqw/pi-subagent`
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Main is the parent Pi session. It can delegate bounded single, parallel, and chained tasks, plus package-owned Git Flow work, to isolated Pi child roles.
|
|
4
4
|
|
|
5
5
|
## Why
|
|
6
6
|
|
|
7
|
-
- **Created for**:
|
|
8
|
-
- **Advantage**: Generic bounded delegation
|
|
7
|
+
- **Created for**: Delegate bounded work to isolated child Pi processes without losing Main's context.
|
|
8
|
+
- **Advantage**: Generic bounded delegation and a deterministic package-owned Git Flow use reusable Role launch policies for package authors.
|
|
9
9
|
|
|
10
10
|
## Install
|
|
11
11
|
|
|
@@ -19,8 +19,10 @@ pi install npm:@henryqw/pi-subagent
|
|
|
19
19
|
|
|
20
20
|
| Package | Why |
|
|
21
21
|
| --- | --- |
|
|
22
|
-
| `@henryqw/pi-
|
|
23
|
-
| `@henryqw/pi-
|
|
22
|
+
| `@henryqw/pi-multi-codex` | Required. Children can use Main's active Codex slot. |
|
|
23
|
+
| `@henryqw/pi-task-models` | Required. Shared `fast` / `balanced` / `frontier` / `fav` routes. |
|
|
24
|
+
|
|
25
|
+
Model routing is not configured here. Children resolve routes through shared `@henryqw/pi-task-models` config at `~/.pi/agent/config/pi-task-models.json`, which stores only explicit task overrides. The local `pi-subagent/delegateTask` declaration supplies the omitted-class default.
|
|
24
26
|
|
|
25
27
|
## Use
|
|
26
28
|
|
|
@@ -30,7 +32,7 @@ pi install npm:@henryqw/pi-subagent
|
|
|
30
32
|
| `delegate_flow` | tool | Package-owned parallel implementation and declared-order Git integration for 1–8 independent units. |
|
|
31
33
|
| `delegate_flow_continue` | tool | Repair the blocked Flow unit once in its existing worktree. |
|
|
32
34
|
|
|
33
|
-
All three delegation tool blocks use Pi's default boxed shell and background. Their compact custom content is an immutable call label, foreground aggregate partial-result status, and bounded final summaries
|
|
35
|
+
All three delegation tool blocks use Pi's default boxed shell and background. Their compact custom content is an immutable call label, foreground aggregate partial-result status, and bounded final summaries. There is no expanded view.
|
|
34
36
|
|
|
35
37
|
### `delegate_task`
|
|
36
38
|
|
|
@@ -47,37 +49,92 @@ Select exactly one shape:
|
|
|
47
49
|
{ chain: [{ role, task, model?, modelClass?, thinking? }], background? }
|
|
48
50
|
```
|
|
49
51
|
|
|
50
|
-
|
|
52
|
+
#### Model precedence
|
|
51
53
|
|
|
52
|
-
|
|
54
|
+
1. An explicit `model` is `provider/modelId` and overrides `modelClass`.
|
|
55
|
+
2. Main sets direct `model` and `thinking` only for an explicit user override.
|
|
56
|
+
3. Otherwise, Main selects `modelClass`: `fast` normally or `balanced` upfront for obviously complex work.
|
|
57
|
+
4. `modelClass` is `fast`, `balanced`, `frontier`, or `fav`.
|
|
58
|
+
When omitted, it uses pi-subagent's local `pi-subagent/delegateTask` Model Task declaration.
|
|
59
|
+
That declaration defaults to `fast` and shared config can explicitly override it.
|
|
53
60
|
|
|
54
|
-
|
|
61
|
+
This is Main policy only. The runtime records no provenance and does not enforce it. `background` applies to the whole selected mode and is never a per-delegation field.
|
|
55
62
|
|
|
56
|
-
|
|
63
|
+
#### Modes, limits, and isolation
|
|
57
64
|
|
|
58
|
-
|
|
65
|
+
- Parallel mode starts entries concurrently, waits for every entry, and reports them in input order.
|
|
66
|
+
- Chain mode is sequential and fail-fast. Each literal `{previous}` receives only the immediately preceding successful assistant output.
|
|
67
|
+
- Foreground failures throw after retaining bounded sibling and recovery evidence.
|
|
68
|
+
- One tool call has one aggregate 50 KiB Main-visible transport cap. It is not 50 KiB per child.
|
|
69
|
+
- Background workflows are session-scoped. Session shutdown or reload aborts them and may deliver only recoverable-work evidence or no follow-up message.
|
|
70
|
+
- Each delegation resolves its own Role, resources, route, and optional worktree request.
|
|
71
|
+
- When available, `isolation: worktree` gives each entry a deterministic separate worktree. Non-Git or unborn-`HEAD` contexts may use Main's cwd.
|
|
72
|
+
- Siblings and chain steps never implicitly share one created worktree.
|
|
59
73
|
|
|
60
74
|
See [Orchestration, isolation, and the public API](./docs/orchestration.md) for generic delegation, Flow behavior, and JavaScript composition examples.
|
|
61
75
|
|
|
62
76
|
### `delegate_flow`
|
|
63
77
|
|
|
64
|
-
Use Flow only for independent, commuting Git changes.
|
|
78
|
+
Use Flow only for independent, commuting Git changes. Commuting changes can integrate in any order.
|
|
79
|
+
|
|
80
|
+
Flow accepts 1–8 uniquely identified units. Each unit has a bounded task, optional `modelClass`, direct command/argument validation gate, and optional non-empty `review` judgment criterion:
|
|
65
81
|
|
|
66
82
|
```text
|
|
67
83
|
delegate_flow({ units: [{ id, task, modelClass?, validation: [{ command, args }], review? }] })
|
|
68
84
|
delegate_flow_continue({ guidance, modelClass? })
|
|
69
85
|
```
|
|
70
86
|
|
|
71
|
-
|
|
87
|
+
```mermaid
|
|
88
|
+
flowchart LR
|
|
89
|
+
setup["Setup: resolve roles and create Unit Worktrees"] --> implement["Implementers in parallel"]
|
|
90
|
+
implement -->|Implementer block| repair["One repair: delegate_flow_continue"]
|
|
91
|
+
implement --> rebase["Rebase, inspect committed state, and validate"]
|
|
92
|
+
rebase -->|Post-rebase no-op| cleanup["Cleanup"]
|
|
93
|
+
rebase --> review{"Review requested?"}
|
|
94
|
+
review -->|No| integrate["Integrate in declared order"]
|
|
95
|
+
review -->|Yes| packet["Exact {base, tip, patchPath}; require PASS"]
|
|
96
|
+
packet -->|PASS| integrate
|
|
97
|
+
rebase -->|Validation block| repair
|
|
98
|
+
packet -->|Review block| repair
|
|
99
|
+
repair --> revalidate["Revalidate repaired work"]
|
|
100
|
+
revalidate -->|No review requested| integrate
|
|
101
|
+
revalidate -->|Review required| rereview["Re-review exact {base, tip, patchPath}; require PASS"]
|
|
102
|
+
rereview -->|PASS| integrate
|
|
103
|
+
revalidate -->|Second block| terminal["Terminal failure: retain worktree"]
|
|
104
|
+
rereview -->|Second block| terminal
|
|
105
|
+
rebase -->|Rebase or infrastructure failure| terminal
|
|
106
|
+
repair -->|Infrastructure failure| terminal
|
|
107
|
+
integrate --> cleanup
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Objective verification is authoritative. Flow always inspects committed Git state and runs declared validation.
|
|
111
|
+
|
|
112
|
+
A unit without `review` skips review evidence and Reviewer launch. It fast-forwards its exact validated tip through the existing guarded `git merge --ff-only` path.
|
|
113
|
+
|
|
114
|
+
Add `review` only for judgment that automation cannot establish. That unit keeps the exact `{base, tip, patchPath}` protocol and requires exact `PASS` before the same integration path.
|
|
115
|
+
|
|
116
|
+
Only one memory-only Flow may be active. At start, it resolves and freezes the effective `implementer` Role, including a same-named user override. It resolves and freezes the effective `reviewer` only when at least one unit requests `review`.
|
|
117
|
+
|
|
118
|
+
An omitted `modelClass` uses the local `pi-subagent/delegateTask` declaration, which defaults to `fast`. A selected class resolves through its shared profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer.
|
|
72
119
|
|
|
73
|
-
|
|
120
|
+
Flow creates one Unit Worktree per unit before it launches Implementers. It runs Implementers in parallel, then processes settled results in declared order.
|
|
74
121
|
|
|
75
|
-
|
|
122
|
+
After integration, it removes the worktree and branch non-forcibly. A refusal is a completion warning with the retained worktree path and/or branch.
|
|
76
123
|
|
|
77
|
-
|
|
124
|
+
A rebase that drops all unit commits is a no-op. Flow validates it, skips Reviewer and merge, then cleans up ordinarily.
|
|
125
|
+
|
|
126
|
+
Implementer, validation, or review blocks can be repaired once through `delegate_flow_continue` in the same worktree. An omitted continuation `modelClass` retains the blocked unit's current class. A supplied class replaces it for that one repair.
|
|
127
|
+
|
|
128
|
+
Rebase and infrastructure failures are terminal. A reported fast-forward failure completes with its diagnostic as a warning only when Git left Main clean at the exact integrated tip.
|
|
129
|
+
|
|
130
|
+
Otherwise it is terminal and retains the affected worktree. Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge gate.
|
|
131
|
+
|
|
132
|
+
`delegate_task` keeps its generic isolation behavior. Flow uses the package-shipped Implementer by default and the package-shipped Reviewer only when a unit requests review. Same-named user Roles remain supported overrides.
|
|
78
133
|
|
|
79
134
|
### Delegate UI summary
|
|
80
135
|
|
|
136
|
+
The transient status widget shows status glyph, role, status label, task summary, activity, and metrics for each child. Activity is `thinking…` or the active tool with elapsed time and path basename. Metrics are completed turns, started tools, model, thinking level, tokens, and total duration.
|
|
137
|
+
|
|
81
138
|
| Aspect | Behavior |
|
|
82
139
|
| --- | --- |
|
|
83
140
|
| Call label | `delegate_task · single/parallel/chain · N task(s)`; `delegate_flow · parallel→serial · N unit(s)`; `delegate_flow_continue · repair continuation` |
|
|
@@ -88,11 +145,19 @@ A rebase that drops all unit commits is a no-op: Flow validates it, skips Review
|
|
|
88
145
|
| Terminal retention | Active rows persist; terminal rows clear on next user input |
|
|
89
146
|
| Final result | Bounded summaries with recovery paths; no expanded view |
|
|
90
147
|
|
|
148
|
+
- Rows are active-first: working items first, then stable insertion order.
|
|
149
|
+
- The hard six-physical-line maximum shows all child rows for six or fewer items.
|
|
150
|
+
- Above six, it shows five child rows and one status-aware overflow line: `… N more · X working · Y complete · Z failed · W stopped`.
|
|
151
|
+
- Terminal rows clear on the next real user input. Active rows persist until the child settles.
|
|
152
|
+
- The final `delegate_task` block is deliberately minimal. It has bounded final summaries and role attribution for parallel and chain work. It shows only retained-worktree recovery paths.
|
|
153
|
+
|
|
91
154
|
## Config
|
|
92
155
|
|
|
93
|
-
pi-subagent owns the extension-named config directory `~/.pi/agent/config/pi-subagent
|
|
156
|
+
pi-subagent owns the extension-named config directory `~/.pi/agent/config/pi-subagent/`. It holds two kinds of user-owned configuration.
|
|
157
|
+
|
|
158
|
+
One Markdown file belongs to each Role (see [Roles](#roles)). The other is its own optional JSON file below.
|
|
94
159
|
|
|
95
|
-
`~/.pi/agent/config/pi-subagent/pi-subagent.json` controls the
|
|
160
|
+
`~/.pi/agent/config/pi-subagent/pi-subagent.json` controls the child pool and execution limits. All fields are optional. A missing file uses defaults.
|
|
96
161
|
|
|
97
162
|
| Field | Required | Possible values | Default |
|
|
98
163
|
| --- | --- | --- | --- |
|
|
@@ -101,9 +166,17 @@ pi-subagent owns the extension-named config directory `~/.pi/agent/config/pi-sub
|
|
|
101
166
|
| `timeout.idleMinutes` | No | Positive number of minutes where minutes × 60 000 ms ≤ 2,147,483,647 | `10` |
|
|
102
167
|
| `timeout.maxMinutes` | No | Positive number within the same ms cap that must be greater than `timeout.idleMinutes`, otherwise the whole `timeout` object falls back to defaults | `30` |
|
|
103
168
|
|
|
104
|
-
Excess children wait FIFO without consuming child timeout.
|
|
169
|
+
- Excess children wait FIFO without consuming child timeout.
|
|
170
|
+
- A terminal response on turn 50 succeeds.
|
|
171
|
+
- An attempted continuation starts no model work and rejects with `turn_limit`.
|
|
172
|
+
- Before a continuing turn, the child gets one warning when completed turns reach 80%.
|
|
173
|
+
- It gets another warning when elapsed time reaches 80% of the maximum runtime.
|
|
174
|
+
- If both thresholds are first reached together, the child gets one combined warning.
|
|
175
|
+
- `PI_SUBAGENT_MAX_SUBAGENTS` overrides `maxSubagents` for the session. It must be a positive integer. An invalid value prevents the extension from loading and leaves `delegate_task` unavailable.
|
|
105
176
|
|
|
106
|
-
This JSON is read leniently
|
|
177
|
+
This JSON is read leniently. Malformed JSON, a non-object root, unknown keys, or invalid values are collected into one warning.
|
|
178
|
+
|
|
179
|
+
The affected settings fall back to defaults. The file is never rewritten.
|
|
107
180
|
|
|
108
181
|
### Role frontmatter
|
|
109
182
|
|
|
@@ -119,14 +192,14 @@ Each Role `.md` file in the same directory accepts these frontmatter fields:
|
|
|
119
192
|
| `skills` | Yes | YAML array of non-empty Skill names | `[]` selects no separately named Role Skills; trusted extension Skills still load |
|
|
120
193
|
| body | Yes | System-prompt Markdown after the frontmatter | — |
|
|
121
194
|
|
|
122
|
-
An unreadable or invalid Role file fails role loading fast
|
|
195
|
+
An unreadable or invalid Role file fails role loading fast. Duplicate role names are rejected.
|
|
123
196
|
|
|
124
197
|
## Roles
|
|
125
198
|
|
|
126
|
-
The package ships two working built-in Roles
|
|
199
|
+
The package ships two working built-in Roles. They are always available without configuration.
|
|
127
200
|
|
|
128
201
|
- `implementer`: focused edits requesting worktree isolation; commits completed scoped changes locally and never pushes or opens PRs without authorization
|
|
129
|
-
- `reviewer`: read-only correctness review of supplied plans
|
|
202
|
+
- `reviewer`: read-only correctness review of supplied plans or files, or—only when a Flow unit declares `review`—of Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits
|
|
130
203
|
|
|
131
204
|
A same-named Markdown file in `~/.pi/agent/config/pi-subagent/` explicitly overrides the built-in default.
|
|
132
205
|
|
|
@@ -135,25 +208,58 @@ The repository also includes optional inert samples:
|
|
|
135
208
|
- [`scout`](./examples/roles/scout.md): read-only discovery
|
|
136
209
|
- [`synthesizer`](./examples/roles/synthesizer.md): reconcile supplied reports
|
|
137
210
|
|
|
138
|
-
Copy them manually from your installed `@henryqw/pi-subagent` package
|
|
211
|
+
Copy them manually from your installed `@henryqw/pi-subagent` package if you want a starting point. npm installs ship the `examples/roles/` directory.
|
|
139
212
|
|
|
140
213
|
```bash
|
|
141
214
|
mkdir -p ~/.pi/agent/config/pi-subagent
|
|
142
215
|
cp <package-install-dir>/examples/roles/scout.md ~/.pi/agent/config/pi-subagent/
|
|
143
216
|
```
|
|
144
217
|
|
|
145
|
-
Locate the install directory with `npm root` inside your project, or
|
|
218
|
+
Locate the install directory with `npm root` inside your project, or through Pi's package installation path.
|
|
146
219
|
|
|
147
|
-
The package never installs or writes Role configuration. Sample names are not built-ins
|
|
220
|
+
The package never installs or writes Role configuration. Sample names are not built-ins. After copying, edit or replace them as your own Roles.
|
|
148
221
|
|
|
149
222
|
## Skill
|
|
150
223
|
|
|
151
|
-
The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill is Main-side planner
|
|
224
|
+
The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill is Main-side planner and orchestrator policy only. `delegate_flow` owns its fixed Git mechanics and validation authority.
|
|
225
|
+
|
|
226
|
+
The Skill adds no runtime code, configuration, or Role installation. Generic orchestration remains outside the executor under [ADR 001](./docs/adr/001-composable-ephemeral-execution.md).
|
|
227
|
+
|
|
228
|
+
## Role, Skill, and resource trust
|
|
229
|
+
|
|
230
|
+
### Role resources
|
|
231
|
+
|
|
232
|
+
A Role explicitly owns base tools, extensions, named Skills, instructions, and optional `isolation: worktree`. Every launch installs its Role tool policy.
|
|
233
|
+
|
|
234
|
+
Named Skills resolve through Main's effective Pi Skill registry. Ambient extension and Skill discovery is disabled in children.
|
|
235
|
+
|
|
236
|
+
### Trusted extensions are not sandboxing
|
|
237
|
+
|
|
238
|
+
Selecting an extension explicitly selects a trusted atomic capability bundle, not just a provider path. Every tool it registers and every Skill supplied through its Pi package metadata or dynamic `resources_discover` loads alongside separately named Role Skills.
|
|
152
239
|
|
|
153
|
-
|
|
240
|
+
This is intentional. An extension may depend on its tools, Skills, lifecycle, and prompt behavior. Loading it permits that executable behavior and is not sandboxing.
|
|
241
|
+
|
|
242
|
+
Scope a child by selecting fewer trusted extensions. Finer-grained selection requires separate extension entry points or configuration, or an upstream split. pi-subagent does not infer or externally narrow undocumented dependencies.
|
|
243
|
+
|
|
244
|
+
### Tool filtering
|
|
245
|
+
|
|
246
|
+
- `tools: []` activates no base built-ins. Trusted selected extension tools and explicit caller tool additions still activate.
|
|
247
|
+
- `skills: []` selects no separately named Role Skills. Trusted selected extension Skills still load.
|
|
248
|
+
- `extensions: []` selects no Role extension bundle.
|
|
249
|
+
- Parent-only recursive orchestration tools and interactive `ask_question` are excluded from children.
|
|
250
|
+
- Explicit Role or caller tool names are verified against the child’s final filtered active registry after provider extensions finish `session_start`.
|
|
251
|
+
- Unavailable tool names fail before the first model turn with provider-extension guidance. Unavailable named Skills warn and skip.
|
|
154
252
|
|
|
155
253
|
## Library API
|
|
156
254
|
|
|
157
|
-
The package root exports Role loading and launch resolution, `createEphemeralSubagentExecutor`, worktree helpers, and generic managed Herdr lifecycle helpers.
|
|
255
|
+
The package root exports Role loading and launch resolution, `createEphemeralSubagentExecutor`, worktree helpers, and generic managed Herdr lifecycle helpers.
|
|
256
|
+
|
|
257
|
+
The executor is for code already running inside active Pi. It does not provide standalone Node.js Pi discovery or launch support.
|
|
258
|
+
|
|
259
|
+
It defaults to a hard limit of 50 turns. An attempted continuation rejects with `turn_limit` while preserving accumulated usage and bounded output.
|
|
260
|
+
|
|
261
|
+
After Pi exits, the executor drains inherited stdout and stderr normally. It destroys streams held by escaped descendants after a short inactivity deadline or one-second hard deadline, so they cannot retain a pool permit.
|
|
262
|
+
|
|
263
|
+
Use [`docs/orchestration.md`](./docs/orchestration.md#public-role-and-executor-api) for exact API behavior.
|
|
158
264
|
|
|
159
|
-
|
|
265
|
+
It includes a post-permit `prepare` example. The example uses `resolveRoleLaunch` with a caller-owned Model Task declaration against the latest Pi context.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@henryqw/pi-subagent",
|
|
3
|
-
"version": "8.0.
|
|
3
|
+
"version": "8.0.1",
|
|
4
4
|
"description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi-package",
|
|
@@ -14,14 +14,14 @@
|
|
|
14
14
|
},
|
|
15
15
|
"license": "MIT",
|
|
16
16
|
"files": [
|
|
17
|
+
"LICENSE",
|
|
17
18
|
"dist",
|
|
18
19
|
"extensions",
|
|
19
20
|
"docs",
|
|
20
21
|
"examples",
|
|
21
22
|
"skills",
|
|
22
23
|
"README.md",
|
|
23
|
-
"CONTEXT.md"
|
|
24
|
-
"LICENSE"
|
|
24
|
+
"CONTEXT.md"
|
|
25
25
|
],
|
|
26
26
|
"types": "./dist/index.d.ts",
|
|
27
27
|
"exports": {
|