pi-subagents 0.23.1 → 0.24.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/CHANGELOG.md +18 -0
- package/README.md +13 -76
- package/package.json +14 -13
- package/prompts/parallel-cleanup.md +11 -1
- package/prompts/parallel-review.md +11 -1
- package/skills/pi-subagents/SKILL.md +11 -12
- package/src/agents/agent-management.ts +2 -2
- package/src/agents/agent-serializer.ts +0 -42
- package/src/agents/agents.ts +1 -1
- package/src/extension/control-notices.ts +1 -1
- package/src/extension/index.ts +6 -6
- package/src/intercom/intercom-bridge.ts +1 -2
- package/src/runs/background/async-execution.ts +37 -11
- package/src/runs/background/async-job-tracker.ts +1 -1
- package/src/runs/background/async-status.ts +16 -50
- package/src/runs/background/notify.ts +1 -1
- package/src/runs/background/result-watcher.ts +1 -1
- package/src/runs/background/run-status.ts +9 -10
- package/src/runs/background/subagent-runner.ts +5 -19
- package/src/runs/foreground/chain-clarify.ts +186 -221
- package/src/runs/foreground/chain-execution.ts +2 -2
- package/src/runs/foreground/execution.ts +1 -1
- package/src/runs/foreground/subagent-executor.ts +6 -6
- package/src/runs/shared/completion-guard.ts +1 -1
- package/src/runs/shared/pi-spawn.ts +32 -15
- package/src/runs/shared/subagent-prompt-runtime.ts +1 -1
- package/src/shared/fork-context.ts +22 -7
- package/src/shared/status-format.ts +49 -0
- package/src/shared/types.ts +3 -8
- package/src/shared/utils.ts +1 -1
- package/src/slash/slash-bridge.ts +2 -2
- package/src/slash/slash-commands.ts +10 -77
- package/src/slash/slash-live-state.ts +2 -2
- package/src/tui/render-helpers.ts +2 -2
- package/src/tui/render.ts +35 -61
- package/src/agents/agent-templates.ts +0 -60
- package/src/manager-ui/agent-manager-chain-detail.ts +0 -164
- package/src/manager-ui/agent-manager-detail.ts +0 -235
- package/src/manager-ui/agent-manager-edit.ts +0 -456
- package/src/manager-ui/agent-manager-list.ts +0 -283
- package/src/manager-ui/agent-manager-parallel.ts +0 -302
- package/src/manager-ui/agent-manager.ts +0 -732
- package/src/tui/subagents-status.ts +0 -621
- package/src/tui/text-editor.ts +0 -286
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,24 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [0.24.1] - 2026-05-10
|
|
6
|
+
|
|
7
|
+
### Changed
|
|
8
|
+
- Migrated Pi package imports and package metadata to the `@earendil-works/*` scope, switched async TypeScript execution discovery to upstream `jiti`, and hardened forked-session creation to use the public `SessionManager.open()` path.
|
|
9
|
+
|
|
10
|
+
## [0.24.0] - 2026-05-03
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
- Consolidated async step activity and parallel-outcome formatting used by widgets and `subagent({ action: "status" })` output.
|
|
14
|
+
- Updated `/parallel-review` and `/parallel-cleanup` to end review synthesis with numbered follow-up choices, plus an `autofix` mode for automatically applying fixes worth doing now.
|
|
15
|
+
- Include async run output paths in `subagent({ action: "status" })` output so the remaining inspection path covers the logs previously surfaced by the removed overlay.
|
|
16
|
+
|
|
17
|
+
### Removed
|
|
18
|
+
- Removed the unnecessary `/agents` manager overlay, its `Ctrl+Shift+A` shortcut, and the `agentManager.newShortcut` setting to cut unnecessary UI surface area; agent and chain management remains available through tool actions, settings, and markdown files.
|
|
19
|
+
- Removed persistent save actions from the chain clarify UI: `S` no longer writes runtime overrides back to agent frontmatter, and `W` no longer saves `.chain.md` files. Clarify now only edits the imminent run.
|
|
20
|
+
- Removed the `/subagents-status` read-only overlay and its slash command; async runs remain inspectable through `subagent({ action: "status" })`, completion notifications, logs, and the async widget.
|
|
21
|
+
- Removed the standalone `src/tui/text-editor.ts`; chain clarify now keeps its small runtime editor logic local to the only remaining consumer.
|
|
22
|
+
|
|
5
23
|
## [0.23.1] - 2026-05-02
|
|
6
24
|
|
|
7
25
|
### Added
|
package/README.md
CHANGED
|
@@ -90,7 +90,7 @@ Those are ordinary Pi requests. Pi decides whether to call `subagent`, which age
|
|
|
90
90
|
| Run in the background | “Run this in the background.” |
|
|
91
91
|
| Browse agents | “Show me the available subagents.” |
|
|
92
92
|
| Use a saved workflow | “Run the review chain on this branch.” |
|
|
93
|
-
| See running work | “Show
|
|
93
|
+
| See running work | “Show active async runs.” |
|
|
94
94
|
| Check setup | “Check whether subagents are configured correctly.” |
|
|
95
95
|
|
|
96
96
|
The extension ships with builtin agents you can use immediately.
|
|
@@ -120,15 +120,7 @@ For one run, put the override in the command:
|
|
|
120
120
|
/run reviewer[model=anthropic/claude-sonnet-4:high] "Review this diff"
|
|
121
121
|
```
|
|
122
122
|
|
|
123
|
-
For a persistent override,
|
|
124
|
-
|
|
125
|
-
```text
|
|
126
|
-
/agents
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
Choose the builtin agent, press `e`, change the model or other fields, then save a user or project override. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides.
|
|
130
|
-
|
|
131
|
-
You can also edit settings directly. This example pins the reviewer everywhere, adds a backup model for provider failures, and keeps the other builtins on your normal default model:
|
|
123
|
+
For a persistent override, edit settings. This example pins the reviewer everywhere, adds a backup model for provider failures, and keeps the other builtins on your normal default model:
|
|
132
124
|
|
|
133
125
|
```json
|
|
134
126
|
{
|
|
@@ -150,18 +142,14 @@ Use `~/.pi/agent/settings.json` for a user override or `.pi/settings.json` for a
|
|
|
150
142
|
|
|
151
143
|
Foreground runs stream progress in the conversation while they run.
|
|
152
144
|
|
|
153
|
-
Background runs keep working after control returns to you.
|
|
145
|
+
Background runs keep working after control returns to you. Inspect active runs with `subagent({ action: "status" })`, or a specific run with `subagent({ action: "status", id: "..." })`.
|
|
154
146
|
|
|
155
|
-
|
|
156
|
-
/subagents-status
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
The status view shows active and recent runs for the current Pi session. Parallel background runs are shown as parallel work, with per-agent progress instead of fake chain steps. Chains with parallel groups keep their grouped shape in both progress and results views, so failed or paused agents stay visible next to completed ones.
|
|
147
|
+
They also show a compact async widget and send completion notifications. Parallel background runs show per-agent progress instead of fake chain steps. Chains with parallel groups keep their grouped shape in progress and results, so failed or paused agents stay visible next to completed ones.
|
|
160
148
|
|
|
161
149
|
You can also ask naturally:
|
|
162
150
|
|
|
163
151
|
```text
|
|
164
|
-
Show me the current
|
|
152
|
+
Show me the current async runs.
|
|
165
153
|
```
|
|
166
154
|
|
|
167
155
|
If something feels misconfigured, run:
|
|
@@ -203,6 +191,8 @@ The package includes reusable prompt templates for common workflows. You do not
|
|
|
203
191
|
| `/gather-context-and-clarify` | Scout/research first, then ask the user the clarification questions that matter. |
|
|
204
192
|
| `/parallel-cleanup` | Run review-only cleanup passes after implementation. |
|
|
205
193
|
|
|
194
|
+
Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the synthesized fixes worth doing now after reviewers return.
|
|
195
|
+
|
|
206
196
|
## Optional pi-intercom companion
|
|
207
197
|
|
|
208
198
|
`pi-subagents` works without `pi-intercom`. Install `pi-intercom` only if you want child agents to talk back to the parent Pi session while they are running.
|
|
@@ -229,7 +219,7 @@ The child can use one dedicated coordination tool:
|
|
|
229
219
|
|
|
230
220
|
Child-side routine completion handoffs are still not expected. With the intercom bridge active, parent-side `pi-subagents` sends grouped completion results through `pi-intercom`: one grouped message per foreground parent `subagent` run and one per completed async result file. Acknowledged foreground delivery returns a compact receipt with artifact/session paths; if unacknowledged, the normal full output is preserved. Grouped messages include child intercom targets and full child summaries.
|
|
231
221
|
|
|
232
|
-
If a child appears stalled, needs-attention notices can show up in the parent session with useful next actions, such as checking
|
|
222
|
+
If a child appears stalled, needs-attention notices can show up in the parent session with useful next actions, such as checking `subagent({ action: "status" })`, interrupting the run, or nudging the child.
|
|
233
223
|
|
|
234
224
|
If messages do not show up, run:
|
|
235
225
|
|
|
@@ -251,8 +241,6 @@ Skip this section until you want exact syntax.
|
|
|
251
241
|
| `/chain agent1 "task1" -> agent2 "task2"` | Run agents in sequence |
|
|
252
242
|
| `/parallel agent1 "task1" -> agent2 "task2"` | Run agents in parallel |
|
|
253
243
|
| `/run-chain <chainName> -- <task>` | Launch a saved `.chain.md` workflow |
|
|
254
|
-
| `/agents` | Open the Agents Manager overlay |
|
|
255
|
-
| `/subagents-status` | Open the active/recent run overlay |
|
|
256
244
|
| `/subagents-doctor` | Show read-only setup diagnostics |
|
|
257
245
|
|
|
258
246
|
Commands validate agent names locally, support tab completion, and send results back into the conversation.
|
|
@@ -338,7 +326,7 @@ The `oracle` and `worker` builtins are designed for an explicit decision loop. A
|
|
|
338
326
|
|
|
339
327
|
## Clarify and launch UI
|
|
340
328
|
|
|
341
|
-
Chains open a clarify UI by default so you can preview and edit the workflow before it runs. Single and parallel tool calls can opt into the same flow with `clarify: true`; slash commands
|
|
329
|
+
Chains open a clarify UI by default so you can preview and edit the workflow before it runs. Single and parallel tool calls can opt into the same flow with `clarify: true`; slash commands launch directly.
|
|
342
330
|
|
|
343
331
|
Common clarify keys:
|
|
344
332
|
|
|
@@ -353,44 +341,8 @@ Common clarify keys:
|
|
|
353
341
|
- `w` edits output/write behavior where supported
|
|
354
342
|
- `r` edits reads where supported
|
|
355
343
|
- `p` toggles progress tracking where supported
|
|
356
|
-
- `S` saves current overrides to the agent frontmatter
|
|
357
|
-
- `W` saves a chain configuration to `.chain.md`
|
|
358
|
-
|
|
359
344
|
Picker screens use `↑↓`, `Enter`, `Esc`, and type-to-filter. The full-screen editor supports word wrapping, paste, `Esc` to save, and `Ctrl+C` to discard.
|
|
360
345
|
|
|
361
|
-
## Agents Manager
|
|
362
|
-
|
|
363
|
-
Press `Ctrl+Shift+A` or type `/agents` to open the Agents Manager. It is the easiest way to browse, inspect, edit, create, and launch agents and chains.
|
|
364
|
-
|
|
365
|
-
Use it when you want to see what agents exist, adjust a builtin override, build a parallel run without writing slash syntax, or save a chain for later.
|
|
366
|
-
|
|
367
|
-
The main screens are:
|
|
368
|
-
|
|
369
|
-
| Screen | What it does |
|
|
370
|
-
|--------|--------------|
|
|
371
|
-
| List | Browse agents and chains with search, filters, scope badges, and selection. |
|
|
372
|
-
| Detail | View resolved prompt, frontmatter fields, run history, and builtin override path. |
|
|
373
|
-
| Edit | Edit models, thinking level, prompt mode, inheritance flags, skills, and prompt text. |
|
|
374
|
-
| Chain Detail | Inspect saved chain steps. |
|
|
375
|
-
| Parallel Builder | Build parallel slots, including repeated agents and per-slot task overrides. |
|
|
376
|
-
| Task Input | Enter the shared task and launch with fork/background/worktree toggles where supported. |
|
|
377
|
-
| New Agent | Create from templates such as Scout, Planner, Implementer, Code Reviewer, Blank Agent, or Blank Chain. |
|
|
378
|
-
|
|
379
|
-
Useful keys:
|
|
380
|
-
|
|
381
|
-
- type to search the list
|
|
382
|
-
- `Enter` opens detail screens
|
|
383
|
-
- `Shift+Ctrl+N` creates an agent or chain from a template
|
|
384
|
-
- `Ctrl+R` launches selected agents as a run or chain
|
|
385
|
-
- `Ctrl+P` opens the parallel builder
|
|
386
|
-
- `Tab` selects agents in the list or toggles skip-clarify in task input
|
|
387
|
-
- `Ctrl+A` adds a slot in the parallel builder
|
|
388
|
-
- `e` edits an agent or builtin override
|
|
389
|
-
- `Ctrl+S` saves an override; `r` resets the focused override field; `D` removes the override
|
|
390
|
-
- `Ctrl+K` clones the current item
|
|
391
|
-
- `Ctrl+D` or `Del` deletes the current item or removes a parallel slot
|
|
392
|
-
- `Esc` backs out of the current screen
|
|
393
|
-
|
|
394
346
|
## Agents and chains
|
|
395
347
|
|
|
396
348
|
Agents are markdown files with YAML frontmatter and a system prompt body. They define the specialist that will run in the child Pi process.
|
|
@@ -436,9 +388,7 @@ Example:
|
|
|
436
388
|
|
|
437
389
|
Supported override fields are `model`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `defaultContext`, `disabled`, `skills`, `tools`, and `systemPrompt`. Use `defaultContext: false` in builtin overrides to clear an inherited context default. Project overrides beat user overrides.
|
|
438
390
|
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
Set `disabled: true` to hide a builtin from runtime discovery and agent-facing `subagent({ action: "list" })` output while keeping it visible in `/agents`. For bulk control, set `subagents.disableBuiltins: true` in settings. Overridden builtins show badges like `[builtin+user]` or `[builtin+project]`; disabled builtins show `off` badges in the manager.
|
|
391
|
+
Set `disabled: true` to hide a builtin from runtime discovery and agent-facing `subagent({ action: "list" })` output. For bulk control, set `subagents.disableBuiltins: true` in settings.
|
|
442
392
|
|
|
443
393
|
### Prompt assembly
|
|
444
394
|
|
|
@@ -567,7 +517,7 @@ Each `## agent-name` section is a step. Config lines such as `output`, `outputMo
|
|
|
567
517
|
|
|
568
518
|
For `output`, `reads`, `skills`, and `progress`, chain behavior is three-state: omitted inherits from the agent, a value overrides, and `false` disables.
|
|
569
519
|
|
|
570
|
-
Create chains
|
|
520
|
+
Create chains by writing `.chain.md` files directly or with the `subagent({ action: "create", config: ... })` management action. Run them with natural language or:
|
|
571
521
|
|
|
572
522
|
```text
|
|
573
523
|
/run-chain scout-planner -- refactor authentication
|
|
@@ -866,18 +816,6 @@ Session directory precedence is: `params.sessionDir`, then `config.defaultSessio
|
|
|
866
816
|
|
|
867
817
|
Controls nested delegation when no inherited `PI_SUBAGENT_MAX_DEPTH` is already in effect. Per-agent `maxSubagentDepth` can tighten the limit for that agent’s child runs, but cannot relax an inherited stricter limit.
|
|
868
818
|
|
|
869
|
-
### `agentManager.newShortcut`
|
|
870
|
-
|
|
871
|
-
```json
|
|
872
|
-
{
|
|
873
|
-
"agentManager": {
|
|
874
|
-
"newShortcut": "shift+ctrl+n"
|
|
875
|
-
}
|
|
876
|
-
}
|
|
877
|
-
```
|
|
878
|
-
|
|
879
|
-
Sets the `/agents` list shortcut for opening the new agent/chain template picker. The default is `shift+ctrl+n`; use Pi key names such as `ctrl+n` if your terminal cannot distinguish Shift for control chords.
|
|
880
|
-
|
|
881
819
|
### `intercomBridge`
|
|
882
820
|
|
|
883
821
|
```json
|
|
@@ -952,7 +890,7 @@ Async runs write:
|
|
|
952
890
|
subagent-log-<id>.md
|
|
953
891
|
```
|
|
954
892
|
|
|
955
|
-
`status.json` powers the widget and
|
|
893
|
+
`status.json` powers the widget and `subagent({ action: "status" })` output. `events.jsonl` contains wrapper events plus child Pi JSON events annotated with run and step metadata. `output-<n>.log` is a live human-readable tail. Fallback information is persisted so background runs are debuggable after completion.
|
|
956
894
|
|
|
957
895
|
## Live progress
|
|
958
896
|
|
|
@@ -1038,9 +976,8 @@ The main runtime files are:
|
|
|
1038
976
|
| `src/runs/foreground/execution.ts` | Core foreground `runSync` handling. |
|
|
1039
977
|
| `src/runs/background/subagent-runner.ts` | Detached async runner. |
|
|
1040
978
|
| `src/runs/background/async-execution.ts` | Background launch support. |
|
|
1041
|
-
| `src/runs/background/async-status.ts`
|
|
979
|
+
| `src/runs/background/async-status.ts` | Status discovery and formatting for async runs. |
|
|
1042
980
|
| `src/runs/foreground/chain-execution.ts` / `src/agents/chain-serializer.ts` | Chain orchestration and `.chain.md` parsing. |
|
|
1043
|
-
| `src/manager-ui/agent-manager*.ts` | Agents Manager screens and editing flows. |
|
|
1044
981
|
| `src/shared/settings.ts` | Chain behavior, instructions, and config helpers. |
|
|
1045
982
|
| `src/runs/shared/worktree.ts` | Git worktree isolation. |
|
|
1046
983
|
| `src/intercom/intercom-bridge.ts` | Runtime intercom bridge instructions and diagnostics. |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-subagents",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.24.1",
|
|
4
4
|
"description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
|
|
5
5
|
"author": "Nico Bailon",
|
|
6
6
|
"license": "MIT",
|
|
@@ -52,32 +52,33 @@
|
|
|
52
52
|
]
|
|
53
53
|
},
|
|
54
54
|
"peerDependencies": {
|
|
55
|
-
"@
|
|
56
|
-
"@
|
|
57
|
-
"@
|
|
58
|
-
"@
|
|
55
|
+
"@earendil-works/pi-agent-core": "*",
|
|
56
|
+
"@earendil-works/pi-ai": "*",
|
|
57
|
+
"@earendil-works/pi-coding-agent": "*",
|
|
58
|
+
"@earendil-works/pi-tui": "*"
|
|
59
59
|
},
|
|
60
60
|
"peerDependenciesMeta": {
|
|
61
|
-
"@
|
|
61
|
+
"@earendil-works/pi-agent-core": {
|
|
62
62
|
"optional": true
|
|
63
63
|
},
|
|
64
|
-
"@
|
|
64
|
+
"@earendil-works/pi-ai": {
|
|
65
65
|
"optional": true
|
|
66
66
|
},
|
|
67
|
-
"@
|
|
67
|
+
"@earendil-works/pi-coding-agent": {
|
|
68
68
|
"optional": true
|
|
69
69
|
},
|
|
70
|
-
"@
|
|
70
|
+
"@earendil-works/pi-tui": {
|
|
71
71
|
"optional": true
|
|
72
72
|
}
|
|
73
73
|
},
|
|
74
74
|
"dependencies": {
|
|
75
|
+
"jiti": "^2.7.0",
|
|
75
76
|
"typebox": "^1.1.24"
|
|
76
77
|
},
|
|
77
78
|
"devDependencies": {
|
|
78
|
-
"@
|
|
79
|
-
"@
|
|
80
|
-
"@
|
|
81
|
-
"@
|
|
79
|
+
"@earendil-works/pi-agent-core": "^0.74.0",
|
|
80
|
+
"@earendil-works/pi-ai": "^0.74.0",
|
|
81
|
+
"@earendil-works/pi-coding-agent": "^0.74.0",
|
|
82
|
+
"@earendil-works/pi-tui": "^0.74.0"
|
|
82
83
|
}
|
|
83
84
|
}
|
|
@@ -42,7 +42,17 @@ While reviewers run, do your own narrow inspection if useful. After they return,
|
|
|
42
42
|
- optional improvements;
|
|
43
43
|
- feedback to ignore or defer, with a short reason.
|
|
44
44
|
|
|
45
|
-
Do not blindly apply every reviewer suggestion.
|
|
45
|
+
Do not blindly apply every reviewer suggestion.
|
|
46
|
+
|
|
47
|
+
Autofix mode: if the invocation contains the exact word `autofix`, treat it as workflow control, not cleanup scope. Remove it before deciding the cleanup target. After synthesis, apply only fixes worth doing now, validate, and summarize. Do not apply optional improvements unless explicitly requested. If there are no fixes worth doing now, do not edit.
|
|
48
|
+
|
|
49
|
+
Without autofix mode, ask before applying fixes unless I already told you to address review feedback. When you ask, end with a compact numbered menu so I can respond with a number. Use wording suited to the findings, but include these choices when applicable:
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
Reply with [1], [2], or further instructions:
|
|
53
|
+
[1] Apply only the fixes worth doing now.
|
|
54
|
+
[2] Apply the fixes worth doing now plus optional improvements.
|
|
55
|
+
```
|
|
46
56
|
|
|
47
57
|
Additional scope or focus from the slash command invocation:
|
|
48
58
|
|
|
@@ -35,7 +35,17 @@ While reviewers run, do your own narrow inspection if useful. After they return,
|
|
|
35
35
|
- optional improvements
|
|
36
36
|
- feedback to ignore or defer, with a short reason
|
|
37
37
|
|
|
38
|
-
Do not blindly apply every reviewer suggestion.
|
|
38
|
+
Do not blindly apply every reviewer suggestion.
|
|
39
|
+
|
|
40
|
+
Autofix mode: if the invocation contains the exact word `autofix`, treat it as workflow control, not review scope. Remove it before deciding the review target. After synthesis, apply only fixes worth doing now, validate, and summarize. Do not apply optional improvements unless explicitly requested. If there are no fixes worth doing now, do not edit.
|
|
41
|
+
|
|
42
|
+
Without autofix mode, ask before applying fixes unless I already told you to address review feedback. When you ask, end with a compact numbered menu so I can respond with a number. Use wording suited to the findings, but include these choices when applicable:
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
Reply with [1], [2], or further instructions:
|
|
46
|
+
[1] Apply only the fixes worth doing now.
|
|
47
|
+
[2] Apply the fixes worth doing now plus optional improvements.
|
|
48
|
+
```
|
|
39
49
|
|
|
40
50
|
Additional review target or focus from the slash command invocation:
|
|
41
51
|
|
|
@@ -32,9 +32,7 @@ Humans often use the slash-command layer instead:
|
|
|
32
32
|
- `/run` — launch a single agent
|
|
33
33
|
- `/chain` — launch a chain of steps
|
|
34
34
|
- `/parallel` — launch top-level parallel tasks
|
|
35
|
-
- `/agents` — open the agents manager TUI
|
|
36
35
|
- `/run-chain` — launch a saved `.chain.md` workflow
|
|
37
|
-
- `/subagents-status` — inspect active/recent async runs
|
|
38
36
|
- `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state
|
|
39
37
|
|
|
40
38
|
Prefer the tool when you are writing agent logic. Prefer the slash commands when
|
|
@@ -131,7 +129,7 @@ For one run, use inline config:
|
|
|
131
129
|
/run reviewer[model=anthropic/claude-sonnet-4] "Review this diff"
|
|
132
130
|
```
|
|
133
131
|
|
|
134
|
-
For persistent tweaks,
|
|
132
|
+
For persistent tweaks, edit `subagents.agentOverrides` in user or project settings. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides.
|
|
135
133
|
|
|
136
134
|
## Prompting role subagents
|
|
137
135
|
|
|
@@ -288,7 +286,7 @@ const run = subagent({
|
|
|
288
286
|
// Continue local inspection, then later call status with the returned id.
|
|
289
287
|
```
|
|
290
288
|
|
|
291
|
-
Inspect async runs with `subagent({ action: "status", id: "..." })
|
|
289
|
+
Inspect async runs with `subagent({ action: "status", id: "..." })` or `subagent({ action: "status" })` for active runs.
|
|
292
290
|
|
|
293
291
|
Use `resume` for follow-up work after a delegated run:
|
|
294
292
|
|
|
@@ -361,10 +359,9 @@ subagent({
|
|
|
361
359
|
})
|
|
362
360
|
```
|
|
363
361
|
|
|
364
|
-
Chains default to clarify mode
|
|
362
|
+
Chains default to clarify mode; set `clarify: false` to skip it. Clarify edits affect only the next run; use management actions, settings, or markdown files for persistent changes.
|
|
365
363
|
For programmatic background launches, use `clarify: false, async: true`.
|
|
366
364
|
|
|
367
|
-
The `/agents` manager also has launch toggles for forked context, background execution, and worktree-isolated parallel runs. Use it when guiding a human who wants to inspect or edit the launch before starting.
|
|
368
365
|
|
|
369
366
|
## Worktree Isolation
|
|
370
367
|
|
|
@@ -507,7 +504,7 @@ subagent({ action: "delete", agent: "code-analysis.my-agent" })
|
|
|
507
504
|
Use management actions when the system needs to create or edit subagents on
|
|
508
505
|
demand without dropping into raw file editing.
|
|
509
506
|
|
|
510
|
-
Management actions create or update user/project agent files. `config.name` is the local frontmatter name; optional `config.package` registers and looks up the runtime name as `{package}.{name}`. Use the dotted runtime name for `get`, `update`, `delete`, slash commands, and chain steps. For small builtin changes such as a model swap, prefer
|
|
507
|
+
Management actions create or update user/project agent files. `config.name` is the local frontmatter name; optional `config.package` registers and looks up the runtime name as `{package}.{name}`. Use the dotted runtime name for `get`, `update`, `delete`, slash commands, and chain steps. For small builtin changes such as a model swap, prefer `subagents.agentOverrides` in settings.
|
|
511
508
|
|
|
512
509
|
## Creating and Editing Agents by File
|
|
513
510
|
|
|
@@ -545,9 +542,11 @@ The package includes prompt shortcuts for common workflows: `/parallel-review`,
|
|
|
545
542
|
`/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan`,
|
|
546
543
|
`/gather-context-and-clarify`, and `/parallel-cleanup`. Use them when the user
|
|
547
544
|
wants repeatable review, research, context handoff, implementation handoff,
|
|
548
|
-
clarification, or cleanup-review patterns.
|
|
549
|
-
|
|
550
|
-
|
|
545
|
+
clarification, or cleanup-review patterns. `/parallel-review autofix` and
|
|
546
|
+
`/parallel-cleanup autofix` synthesize reviewer feedback and then apply only the
|
|
547
|
+
fixes worth doing now. Parent agents can also apply the same recipes directly
|
|
548
|
+
with `subagent(...)` when the user describes the workflow in natural language
|
|
549
|
+
instead of invoking a slash command.
|
|
551
550
|
|
|
552
551
|
If `pi-prompt-template-model` is installed, additional user prompt templates can delegate into
|
|
553
552
|
`pi-subagents`. This is useful when a slash command should always run through a
|
|
@@ -639,7 +638,7 @@ clarify → planner → worker → parallel fresh-context reviewers → worker
|
|
|
639
638
|
|
|
640
639
|
The first `worker` implements the approved plan. The parallel reviewers inspect the resulting diff from fresh context. The final `worker` applies synthesized review fixes in forked context. Do not stop after parallel review unless the user explicitly asked for review-only output or the review surfaced a decision that needs approval first.
|
|
641
640
|
|
|
642
|
-
Keep orchestration authority in the parent session. Child subagents should not launch more subagents, read this skill, or run their own orchestration loops. Spawned subagents do not receive the `pi-subagents` skill, parent-only
|
|
641
|
+
Keep orchestration authority in the parent session. Child subagents should not launch more subagents, read this skill, or run their own orchestration loops. Spawned subagents do not receive the `pi-subagents` skill, parent-only status/control/slash messages, prior parent `subagent` tool-call/tool-result artifacts, or the `subagent` extension tool. Child context filtering also strips old hidden orchestration-instruction messages when they appear in inherited history. Every child also receives a boundary instruction that says the parent owns orchestration, the child must not propose or run subagents, and implementation children must call real edit/write tools instead of printing pseudo tool calls. Pass children concrete role-specific work instead.
|
|
643
642
|
|
|
644
643
|
1. Clarify first. This is mandatory. Gather code context with `scout` or `context-builder`, add `researcher` only when external evidence matters, then ask the user clarifying questions with `interview` until scope, acceptance criteria, constraints, and non-goals are clear.
|
|
645
644
|
2. Plan when useful. For complex work, call `planner` or write a plan doc yourself and get approval before implementation. For simple work, confirm shared understanding and explicitly note why planning is skipped.
|
|
@@ -744,5 +743,5 @@ subagent({ action: "doctor" })
|
|
|
744
743
|
|
|
745
744
|
**Child fails before starting**
|
|
746
745
|
```typescript
|
|
747
|
-
// Inspect
|
|
746
|
+
// Inspect `subagent({ action: "status", id: "..." })`, artifact metadata/output logs, and run doctor. Extension loader errors usually appear in child output logs.
|
|
748
747
|
```
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import * as fs from "node:fs";
|
|
2
2
|
import * as path from "node:path";
|
|
3
|
-
import type { AgentToolResult } from "@
|
|
4
|
-
import type { ExtensionContext } from "@
|
|
3
|
+
import type { AgentToolResult } from "@earendil-works/pi-agent-core";
|
|
4
|
+
import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
5
5
|
import {
|
|
6
6
|
type AgentConfig,
|
|
7
7
|
type AgentScope,
|
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
import * as fs from "node:fs";
|
|
2
1
|
import type { AgentConfig } from "./agents.ts";
|
|
3
2
|
import { frontmatterNameForConfig } from "./identity.ts";
|
|
4
3
|
|
|
@@ -83,44 +82,3 @@ export function serializeAgent(config: AgentConfig): string {
|
|
|
83
82
|
const body = config.systemPrompt ?? "";
|
|
84
83
|
return `${lines.join("\n")}\n\n${body}\n`;
|
|
85
84
|
}
|
|
86
|
-
|
|
87
|
-
export function updateFrontmatterField(filePath: string, field: string, value: string | undefined): void {
|
|
88
|
-
const raw = fs.readFileSync(filePath, "utf-8");
|
|
89
|
-
const normalized = raw.replace(/\r\n/g, "\n");
|
|
90
|
-
if (!normalized.startsWith("---")) {
|
|
91
|
-
throw new Error("Frontmatter not found");
|
|
92
|
-
}
|
|
93
|
-
|
|
94
|
-
const endIndex = normalized.indexOf("\n---", 3);
|
|
95
|
-
if (endIndex === -1) {
|
|
96
|
-
throw new Error("Frontmatter not found");
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
const frontmatterBlock = normalized.slice(4, endIndex);
|
|
100
|
-
const rest = normalized.slice(endIndex + 4);
|
|
101
|
-
const lines = frontmatterBlock.split("\n");
|
|
102
|
-
|
|
103
|
-
const normalizedField = field === "skill" || field === "skills" ? "skills" : field;
|
|
104
|
-
const targetKeys = field === "skills" ? new Set(["skill", "skills"]) : new Set([field]);
|
|
105
|
-
let found = false;
|
|
106
|
-
const updated: string[] = [];
|
|
107
|
-
|
|
108
|
-
for (const line of lines) {
|
|
109
|
-
const match = line.match(/^([\w-]+):\s*(.*)$/);
|
|
110
|
-
if (match && targetKeys.has(match[1])) {
|
|
111
|
-
if (value !== undefined) {
|
|
112
|
-
if (!found) updated.push(`${normalizedField}: ${value}`);
|
|
113
|
-
found = true;
|
|
114
|
-
}
|
|
115
|
-
continue;
|
|
116
|
-
}
|
|
117
|
-
updated.push(line);
|
|
118
|
-
}
|
|
119
|
-
|
|
120
|
-
if (value !== undefined && !found) {
|
|
121
|
-
updated.push(`${normalizedField}: ${value}`);
|
|
122
|
-
}
|
|
123
|
-
|
|
124
|
-
const frontmatter = `---\n${updated.join("\n")}\n---`;
|
|
125
|
-
fs.writeFileSync(filePath, frontmatter + rest, "utf-8");
|
|
126
|
-
}
|
package/src/agents/agents.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { ExtensionAPI } from "@
|
|
1
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
2
2
|
import { controlNotificationKey, formatControlNoticeMessage } from "../runs/shared/subagent-control.ts";
|
|
3
3
|
import type { ControlEvent, SubagentState } from "../shared/types.ts";
|
|
4
4
|
|
package/src/extension/index.ts
CHANGED
|
@@ -9,15 +9,15 @@
|
|
|
9
9
|
* Toggle: async parameter (default: false, configurable via config.json)
|
|
10
10
|
*
|
|
11
11
|
* Config file: ~/.pi/agent/extensions/subagent/config.json
|
|
12
|
-
* { "asyncByDefault": true, "forceTopLevelAsync": true, "maxSubagentDepth": 1, "
|
|
12
|
+
* { "asyncByDefault": true, "forceTopLevelAsync": true, "maxSubagentDepth": 1, "intercomBridge": { "mode": "always", "instructionFile": "./intercom-bridge.md" }, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
|
|
13
13
|
*/
|
|
14
14
|
|
|
15
15
|
import * as fs from "node:fs";
|
|
16
16
|
import * as os from "node:os";
|
|
17
17
|
import * as path from "node:path";
|
|
18
|
-
import type { AgentToolResult } from "@
|
|
19
|
-
import { type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@
|
|
20
|
-
import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@
|
|
18
|
+
import type { AgentToolResult } from "@earendil-works/pi-agent-core";
|
|
19
|
+
import { type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
|
|
20
|
+
import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
|
|
21
21
|
import { discoverAgents } from "../agents/agents.ts";
|
|
22
22
|
import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
|
|
23
23
|
import { resolveCurrentSessionId } from "../shared/session-identity.ts";
|
|
@@ -242,7 +242,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
|
|
|
242
242
|
cleanupAllArtifactDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
|
|
243
243
|
|
|
244
244
|
const state: SubagentState = {
|
|
245
|
-
baseCwd:
|
|
245
|
+
baseCwd: "",
|
|
246
246
|
currentSessionId: null,
|
|
247
247
|
asyncJobs: new Map(),
|
|
248
248
|
foregroundRuns: new Map(),
|
|
@@ -473,7 +473,7 @@ DIAGNOSTICS:
|
|
|
473
473
|
};
|
|
474
474
|
|
|
475
475
|
pi.registerTool(tool);
|
|
476
|
-
registerSlashCommands(pi, state
|
|
476
|
+
registerSlashCommands(pi, state);
|
|
477
477
|
|
|
478
478
|
const eventUnsubscribeStoreKey = "__piSubagentEventUnsubscribes";
|
|
479
479
|
const controlNoticeSeenStoreKey = "__piSubagentVisibleControlNotices";
|
|
@@ -190,8 +190,7 @@ function getGlobalNpmRoot(): string | null {
|
|
|
190
190
|
}
|
|
191
191
|
|
|
192
192
|
function configuredPiIntercomPackageDir(input: ResolveIntercomBridgeInput, agentDir: string): string | undefined {
|
|
193
|
-
const
|
|
194
|
-
const projectConfigDir = findNearestProjectConfigDir(cwd);
|
|
193
|
+
const projectConfigDir = input.cwd ? findNearestProjectConfigDir(path.resolve(input.cwd)) : undefined;
|
|
195
194
|
const settingsFiles = [
|
|
196
195
|
...(projectConfigDir ? [{ file: path.join(projectConfigDir, "settings.json"), configDir: projectConfigDir, scope: "project" as const }] : []),
|
|
197
196
|
{ file: path.join(agentDir, "settings.json"), configDir: agentDir, scope: "user" as const },
|
|
@@ -8,7 +8,7 @@ import * as os from "node:os";
|
|
|
8
8
|
import * as path from "node:path";
|
|
9
9
|
import { fileURLToPath } from "node:url";
|
|
10
10
|
import { createRequire } from "node:module";
|
|
11
|
-
import type { ExtensionAPI } from "@
|
|
11
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
12
12
|
import type { AgentConfig } from "../../agents/agents.ts";
|
|
13
13
|
import { applyThinkingSuffix } from "../shared/pi-args.ts";
|
|
14
14
|
import { injectSingleOutputInstruction, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
|
|
@@ -35,26 +35,52 @@ import {
|
|
|
35
35
|
|
|
36
36
|
const require = createRequire(import.meta.url);
|
|
37
37
|
const piPackageRoot = resolvePiPackageRoot();
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
38
|
+
|
|
39
|
+
function resolveJitiCliFromPackageJson(packageJsonPath: string): string | undefined {
|
|
40
|
+
if (!fs.existsSync(packageJsonPath)) return undefined;
|
|
41
|
+
const packageRoot = path.dirname(packageJsonPath);
|
|
42
|
+
const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) as {
|
|
43
|
+
bin?: string | Record<string, string>;
|
|
44
|
+
};
|
|
45
|
+
const binField = pkg.bin;
|
|
46
|
+
const binPath = typeof binField === "string"
|
|
47
|
+
? binField
|
|
48
|
+
: binField?.jiti ?? Object.values(binField ?? {})[0];
|
|
49
|
+
const candidates = [binPath, "lib/jiti-cli.mjs"].filter((candidate): candidate is string => Boolean(candidate));
|
|
50
|
+
for (const candidate of candidates) {
|
|
51
|
+
const cliPath = path.resolve(packageRoot, candidate);
|
|
52
|
+
if (fs.existsSync(cliPath)) return cliPath;
|
|
53
|
+
}
|
|
54
|
+
return undefined;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function resolveJitiCliPath(): string | undefined {
|
|
58
|
+
const candidates: Array<() => string | undefined> = [
|
|
59
|
+
() => require.resolve("jiti/package.json"),
|
|
60
|
+
() => piPackageRoot
|
|
61
|
+
? createRequire(path.join(piPackageRoot, "package.json")).resolve("jiti/package.json")
|
|
62
|
+
: undefined,
|
|
42
63
|
() => {
|
|
64
|
+
if (!process.argv[1]) return undefined;
|
|
43
65
|
const piEntry = fs.realpathSync(process.argv[1]);
|
|
44
|
-
|
|
45
|
-
return path.join(path.dirname(piRequire.resolve("@mariozechner/jiti/package.json")), "lib/jiti-cli.mjs");
|
|
66
|
+
return createRequire(piEntry).resolve("jiti/package.json");
|
|
46
67
|
},
|
|
68
|
+
() => piPackageRoot ? path.join(piPackageRoot, "node_modules", "jiti", "package.json") : undefined,
|
|
47
69
|
];
|
|
48
70
|
for (const candidate of candidates) {
|
|
49
71
|
try {
|
|
50
|
-
const
|
|
51
|
-
if (
|
|
72
|
+
const packageJsonPath = candidate();
|
|
73
|
+
if (!packageJsonPath) continue;
|
|
74
|
+
const cliPath = resolveJitiCliFromPackageJson(packageJsonPath);
|
|
75
|
+
if (cliPath) return cliPath;
|
|
52
76
|
} catch {
|
|
53
77
|
// Candidate not available in this install, continue probing.
|
|
54
78
|
}
|
|
55
79
|
}
|
|
56
80
|
return undefined;
|
|
57
|
-
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
const jitiCliPath = resolveJitiCliPath();
|
|
58
84
|
|
|
59
85
|
interface AsyncExecutionContext {
|
|
60
86
|
pi: ExtensionAPI;
|
|
@@ -139,7 +165,7 @@ export function isAsyncAvailable(): boolean {
|
|
|
139
165
|
*/
|
|
140
166
|
function spawnRunner(cfg: object, suffix: string, cwd: string): { pid?: number; error?: string } {
|
|
141
167
|
if (!jitiCliPath) {
|
|
142
|
-
return { error: "jiti for TypeScript execution could not be found" };
|
|
168
|
+
return { error: "upstream jiti for TypeScript execution could not be found; ensure package dependencies are installed" };
|
|
143
169
|
}
|
|
144
170
|
|
|
145
171
|
try {
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { ExtensionAPI, ExtensionContext } from "@
|
|
1
|
+
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
2
|
import * as fs from "node:fs";
|
|
3
3
|
import * as path from "node:path";
|
|
4
4
|
import { renderWidget } from "../../tui/render.ts";
|