@xzzpig/pi-subagents 0.20.0 → 0.21.0
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 +154 -0
- package/README.md +1 -1
- package/agents/oracle.md +8 -19
- package/agents/researcher.md +0 -3
- package/agents/reviewer.md +17 -61
- package/agents/scout.md +1 -4
- package/agents/worker.md +8 -25
- package/docs/agents.md +72 -7
- package/docs/configuration.md +58 -7
- package/docs/extension-api.md +36 -11
- package/docs/fork-extensions.md +1 -0
- package/docs/missions.md +34 -17
- package/docs/models.md +1 -1
- package/docs/observability.md +10 -5
- package/docs/tool-reference.md +117 -84
- package/docs/watchdog.md +8 -6
- package/docs/workflows.md +16 -7
- package/index.ts +5 -0
- package/package.json +5 -3
- package/prompts/council.md +1 -1
- package/skills/pi-subagents/SKILL.md +1 -1
- package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
- package/skills/pi-subagents/references/execution-controls.md +16 -16
- package/skills/pi-subagents/references/management-authoring-rpc.md +16 -12
- package/skills/pi-subagents/references/prompting-and-roles.md +3 -3
- package/src/agents/advertised-agent-prompt.ts +9 -1
- package/src/agents/agent-management.ts +4 -0
- package/src/agents/agent-memory.ts +3 -3
- package/src/agents/agent-scope.ts +4 -0
- package/src/agents/agent-serializer.ts +8 -1
- package/src/agents/agents.ts +191 -145
- package/src/api/preflight.ts +8 -4
- package/src/extension/config.ts +21 -2
- package/src/extension/context-injection.ts +6 -1
- package/src/extension/control-notices.ts +1 -9
- package/src/extension/declaration-pinning.ts +164 -0
- package/src/extension/doctor.ts +7 -10
- package/src/extension/fanout-child.ts +7 -8
- package/src/extension/index.ts +114 -132
- package/src/extension/reply-workflow-script.ts +20 -11
- package/src/extension/rpc.ts +11 -6
- package/src/extension/schemas.ts +34 -30
- package/src/extension/subagent-guide.ts +86 -6
- package/src/extension/subagent-options.ts +47 -0
- package/src/extension/tool-activation.ts +3 -2
- package/src/extension/tool-description.ts +51 -68
- package/src/inspectors/actions.ts +37 -11
- package/src/inspectors/plugins.ts +3 -2
- package/src/inspectors/tmux/actions.ts +204 -0
- package/src/inspectors/tmux/client.ts +85 -0
- package/src/inspectors/tmux/plugin.ts +21 -0
- package/src/integrations/herdr-status.ts +18 -49
- package/src/integrations/program-status.ts +215 -0
- package/src/intercom/native-supervisor-channel.ts +77 -4
- package/src/intercom/result-intercom.ts +3 -2
- package/src/intercom/supervisor-ui.ts +2 -174
- package/src/missions/store.ts +25 -5
- package/src/profiles/profiles.ts +24 -21
- package/src/runs/background/active-async-capacity.ts +58 -8
- package/src/runs/background/async-execution.ts +143 -38
- package/src/runs/background/async-job-tracker.ts +11 -4
- package/src/runs/background/async-resume.ts +5 -2
- package/src/runs/background/await-async-run.ts +14 -9
- package/src/runs/background/binary-bootstrap.ts +2 -1
- package/src/runs/background/calendar-schedule.ts +90 -0
- package/src/runs/background/chain-root-attachment.ts +9 -5
- package/src/runs/background/fleet-view.ts +5 -5
- package/src/runs/background/notify.ts +185 -12
- package/src/runs/background/result-files.ts +116 -5
- package/src/runs/background/result-watcher.ts +99 -66
- package/src/runs/background/resume-guidance.ts +2 -2
- package/src/runs/background/run-child-session.ts +16 -2
- package/src/runs/background/run-id-resolver.ts +8 -5
- package/src/runs/background/run-status.ts +21 -16
- package/src/runs/background/runner-child-launch.ts +1 -0
- package/src/runs/background/runner-http-dispatcher.ts +3 -0
- package/src/runs/background/scheduled-runs.ts +256 -61
- package/src/runs/background/subagent-runner-bootstrap.ts +4 -1
- package/src/runs/background/subagent-runner.ts +32 -12
- package/src/runs/background/subagent-wait.ts +38 -19
- package/src/runs/background/terminal-run-index.ts +46 -1
- package/src/runs/background/wait-completions.ts +1 -0
- package/src/runs/background/wait-tool.ts +33 -23
- package/src/runs/background/workflow-terminal-proof.ts +39 -22
- package/src/runs/foreground/async-stop-action.ts +48 -22
- package/src/runs/foreground/execution.ts +94 -52
- package/src/runs/foreground/foreground-history.ts +1 -0
- package/src/runs/foreground/subagent-executor.ts +207 -77
- package/src/runs/shared/child-commands.ts +2 -1
- package/src/runs/shared/child-hooks.ts +4 -3
- package/src/runs/shared/child-launch.ts +3 -0
- package/src/runs/shared/child-session.ts +41 -24
- package/src/runs/shared/child-tool-plan.ts +13 -26
- package/src/runs/shared/dynamic-fanout.ts +1 -1
- package/src/runs/shared/fork-command-result.ts +10 -0
- package/src/runs/shared/herdr-placed-run.ts +5 -4
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +5 -3
- package/src/runs/shared/model-resolution-diagnostic.ts +25 -0
- package/src/runs/shared/model-resolution.ts +30 -1
- package/src/runs/shared/nested-events.ts +5 -0
- package/src/runs/shared/parallel-handoff.ts +56 -8
- package/src/runs/shared/parallel-utils.ts +2 -0
- package/src/runs/shared/partial-output.ts +48 -0
- package/src/runs/shared/runner-launcher.ts +25 -0
- package/src/runs/shared/single-output.ts +53 -0
- package/src/runs/shared/structured-output.ts +14 -7
- package/src/runs/shared/subagent-control.ts +3 -3
- package/src/runs/shared/subagent-prompt-runtime.ts +47 -24
- package/src/runs/shared/workflow-async-child-guidance.ts +1 -1
- package/src/runs/shared/worktree-cleanup-apply.ts +160 -0
- package/src/runs/shared/worktree-cleanup-plan.ts +41 -19
- package/src/runs/shared/worktree-lock.ts +29 -0
- package/src/runs/shared/worktree.ts +12 -1
- package/src/shared/atomic-json.ts +4 -2
- package/src/shared/edit-distance.ts +33 -0
- package/src/shared/file-lease.ts +74 -0
- package/src/shared/formatters.ts +1 -5
- package/src/shared/model-info.ts +22 -0
- package/src/shared/package-version.ts +17 -0
- package/src/shared/parent-wake.ts +79 -0
- package/src/shared/pruned-fork.ts +7 -1
- package/src/shared/runtime-module-path.ts +19 -0
- package/src/shared/settings-file-lease.ts +36 -0
- package/src/shared/types.ts +36 -2
- package/src/shared/utils.ts +8 -6
- package/src/slash/slash-commands.ts +3 -3
- package/src/slash/subagents-admin.ts +2 -1
- package/src/tui/fleet-native-transcript.ts +2 -0
- package/src/tui/fleet-transcript.ts +12 -3
- package/src/tui/fleet.ts +11 -8
- package/src/tui/render.ts +27 -19
- package/src/tui/subagent-messages.ts +305 -0
- package/src/watchdog/diff-tool.ts +2 -2
- package/src/watchdog/register-main.ts +2 -22
- package/src/watchdog/render.ts +2 -24
- package/src/watchdog/runtime.ts +6 -4
- package/src/watchdog/settings.ts +18 -13
- package/src/watchdog/tool-actions.ts +2 -2
- package/src/workflows/scripted-workflow.ts +20 -6
- package/src/workflows/workflow-resources.ts +11 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xzzpig/pi-subagents",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.21.0",
|
|
4
4
|
"description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
|
|
5
5
|
"author": "Nico Bailon",
|
|
6
6
|
"license": "MIT",
|
|
@@ -36,6 +36,7 @@
|
|
|
36
36
|
"pi-package",
|
|
37
37
|
"pi",
|
|
38
38
|
"pi-coding-agent",
|
|
39
|
+
"extension",
|
|
39
40
|
"subagents",
|
|
40
41
|
"ai",
|
|
41
42
|
"agents",
|
|
@@ -92,6 +93,7 @@
|
|
|
92
93
|
},
|
|
93
94
|
"dependencies": {
|
|
94
95
|
"@xzzpig/pi-components": "0.4.0",
|
|
96
|
+
"@js-temporal/polyfill": "0.5.1",
|
|
95
97
|
"acorn": "8.18.0",
|
|
96
98
|
"jiti": "2.7.0",
|
|
97
99
|
"undici": "8.10.2",
|
|
@@ -119,8 +121,8 @@
|
|
|
119
121
|
"pack:pkg": "npm run build:pkg && npm pack ./dist-pkg",
|
|
120
122
|
"typecheck": "tsc --noEmit",
|
|
121
123
|
"test": "npm run test:unit",
|
|
122
|
-
"test:unit": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
|
|
123
|
-
"test:integration": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
|
|
124
|
+
"test:unit": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --import ./test/support/fork-test-environment.mjs --test test/unit/*.test.ts",
|
|
125
|
+
"test:integration": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/register-loader.mjs --import ./test/support/fork-test-environment.mjs --test test/integration/*.test.ts",
|
|
124
126
|
"test:smoke:tool-activation": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --test test/smoke/tool-activation.test.ts",
|
|
125
127
|
"test:all": "npm run test:unit && npm run test:integration"
|
|
126
128
|
}
|
package/prompts/council.md
CHANGED
|
@@ -9,7 +9,7 @@ decide which feedback is valid, and write the final memo. Advisors do not talk
|
|
|
9
9
|
directly or see peer transcripts by default. This is not free-form agent chat.
|
|
10
10
|
|
|
11
11
|
Before you orchestrate, load the council protocol with
|
|
12
|
-
`subagent({ action: "guide", topic: "council" })`. If only `subagents_enable`
|
|
12
|
+
`subagent({ action: "guide", options: { topic: "council" } })`. If only `subagents_enable`
|
|
13
13
|
is available, call it first; `subagent` is available on the next request. The
|
|
14
14
|
guide returns the packaged council-mode skill and the references it asks you to
|
|
15
15
|
read, so it also works when Pi runs with `--no-skills`.
|
|
@@ -87,7 +87,7 @@ that runner explicitly supports the option.
|
|
|
87
87
|
|
|
88
88
|
## Read the reference for the branch
|
|
89
89
|
|
|
90
|
-
For exact API fields and worked examples, call `subagent({action:"guide",topic:"tool-reference"})` or `topic:"workflows"`. The compact tool definition is not the recipe catalog; use `topic:"missions"` for mission updates and schedules.
|
|
90
|
+
For exact API fields and worked examples, call `subagent({action:"guide",options:{topic:"tool-reference"}})` or `topic:"workflows"`. The compact tool definition is not the recipe catalog; use `topic:"missions"` for mission updates and schedules.
|
|
91
91
|
|
|
92
92
|
| Branch | Read |
|
|
93
93
|
| --- | --- |
|
|
@@ -64,7 +64,7 @@ its overhead. Recipes select a shape; they do not authorize delegation:
|
|
|
64
64
|
|
|
65
65
|
## Error Handling
|
|
66
66
|
|
|
67
|
-
- **Unknown agent:**
|
|
67
|
+
- **Unknown agent:** the error lists the available agents and the directories searched; check scope/precedence and author new orchestration as a workflow script, not legacy chains.
|
|
68
68
|
- **Setup, discovery, or intercom confusion:** run `subagent({ action: "doctor" })`.
|
|
69
69
|
- **Max subagent depth exceeded:** flatten the workflow or raise `maxSubagentDepth` in config.
|
|
70
70
|
- **Missing session file for a fork:** persist the parent session before using `context: "fork"`.
|
|
@@ -211,19 +211,19 @@ return runs.run("correctness", { agent: "reviewer", task: "Review the current di
|
|
|
211
211
|
```
|
|
212
212
|
|
|
213
213
|
```typescript
|
|
214
|
-
const run = subagent({ workflow: true, async: true, context: "fresh" })
|
|
214
|
+
const run = subagent({ workflow: true, async: true, options: { context: "fresh" } })
|
|
215
215
|
// Continue local inspection, then later call status with the returned id.
|
|
216
216
|
```
|
|
217
217
|
|
|
218
218
|
While children run, the persistent FleetView and the collapsed foreground tool-result card show live per-child detail: resolved model and thinking level, `[fresh]`/`[fork]` context, tool/token/elapsed counters, and current activity. The collapsed running card also prints the configured expand-key hint ("Press … for live detail"); expanding it shows nested children, recent tools, and recent output. Model badges appear once the child's model resolves at first attempt start. `/subagents-fleet` opens the live fleet inspector, which also has per-child controls (`s` steer, `D` stop with confirmation). When optional Herdr 0.7.5+ is available, `H` opens a raw inspector dashboard for the selected active async child; this mirrors artifacts rather than attaching to the headless child. When optional Orca progress tabs are enabled, Pi creates one passive Orca observer tab for the top-level subagent call. Parallel and chain children share that tab and write child section headers into the mirrored log instead of opening one tab per child. Pi remains authoritative for lifecycle, status, control, artifacts, and results; the Orca tab is display-only. Pi also writes passive display metadata under `.pi/subagents/views/orca/` when possible, so other surfaces can discover the observer without treating it as an owned child run. Use visual panes for confusing or long-running active async work when the human wants a dedicated surface or FleetView is insufficient, not for routine headless runs.
|
|
219
219
|
|
|
220
|
-
Inspect async runs with `subagent({ action: "status", id: "..." })` or `subagent({ action: "status" })` for active runs. Use `subagent({ action: "status", view: "fleet" })` when supervising several active foreground/background runs and `subagent({ action: "status", id: "...", view: "transcript", index: 0 })` when you need the latest child output without digging through artifacts. If a delegated fanout child launches nested runs, the parent status view shows them as a tree and you can target a nested run directly with its nested id.
|
|
220
|
+
Inspect async runs with `subagent({ action: "status", id: "..." })` or `subagent({ action: "status" })` for active runs. Use `subagent({ action: "status", options: { view: "fleet" } })` when supervising several active foreground/background runs and `subagent({ action: "status", id: "...", options: { view: "transcript", index: 0 } })` when you need the latest child output without digging through artifacts. If a delegated fanout child launches nested runs, the parent status view shows them as a tree and you can target a nested run directly with its nested id.
|
|
221
221
|
|
|
222
222
|
Stop a current-session top-level async run with `stop` (or `/subagents-stop`). Stopped runs finish as `stopped`/cancelled and are not resumable. For an active foreground single-subagent run, `/subagents-detach [run-id]` leaves the child running without terminating it and returns the eventual result through status/wait.
|
|
223
223
|
|
|
224
224
|
```typescript
|
|
225
225
|
subagent({ action: "stop", id: "run-id" })
|
|
226
|
-
subagent({ action: "stop", id: "run-id", childId: "child-id" })
|
|
226
|
+
subagent({ action: "stop", id: "run-id", options: { childId: "child-id" } })
|
|
227
227
|
```
|
|
228
228
|
|
|
229
229
|
Use `childId` only for active async/workflow runs whose status snapshot shows a
|
|
@@ -237,7 +237,7 @@ Use `steer` for top-level live async guidance and `resume` after a delegated run
|
|
|
237
237
|
```typescript
|
|
238
238
|
subagent({ action: "steer", id: "run-id", message: "Focus on the failing test." })
|
|
239
239
|
subagent({ action: "resume", id: "run-id", message: "Follow up on this point." })
|
|
240
|
-
subagent({ action: "resume", id: "run-id",
|
|
240
|
+
subagent({ action: "resume", id: "run-id", message: "Continue reviewer 2.", options: { index: 1 } })
|
|
241
241
|
subagent({ action: "resume", id: "nested-run-id", message: "Continue this nested reviewer." })
|
|
242
242
|
```
|
|
243
243
|
|
|
@@ -275,10 +275,10 @@ Schedules are durable project records under `.pi/subagents/schedules/`. They are
|
|
|
275
275
|
|
|
276
276
|
```typescript
|
|
277
277
|
// One-shot reviewer, after a ```js workflow block with the script
|
|
278
|
-
subagent({ action: "schedule.create", id: "evening-review", name: "Evening review", at: "+30m"
|
|
278
|
+
subagent({ action: "schedule.create", id: "evening-review", workflow: true, options: { name: "Evening review", at: "+30m" } })
|
|
279
279
|
|
|
280
280
|
// Fixed recurring workflow from a script file
|
|
281
|
-
subagent({ action: "schedule.create", id: "backlog",
|
|
281
|
+
subagent({ action: "schedule.create", id: "backlog", workflow: "./.pi/workflows/backlog.js", options: { every: "6h", catchUp: "latest" } })
|
|
282
282
|
|
|
283
283
|
subagent({ action: "schedule.list" })
|
|
284
284
|
subagent({ action: "schedule.show", id: "backlog" })
|
|
@@ -345,8 +345,8 @@ Steering supports three delivery modes via the `mode` parameter (`steer` is the
|
|
|
345
345
|
- `mode: "auto"` — same next-safe-point delivery path as `steer`, but without the automatic pause-and-revive recovery after a missed acknowledgment.
|
|
346
346
|
|
|
347
347
|
```typescript
|
|
348
|
-
subagent({ action: "steer", id: "abc123",
|
|
349
|
-
subagent({ action: "steer", id: "abc123",
|
|
348
|
+
subagent({ action: "steer", id: "abc123", message: "After this step, also validate the config file.", options: { mode: "follow_up" } })
|
|
349
|
+
subagent({ action: "steer", id: "abc123", message: "Switch to the failing test now.", options: { mode: "auto" } })
|
|
350
350
|
```
|
|
351
351
|
|
|
352
352
|
For async runs, `delivered` records that the child consumed the correlated user input; foreground `delivered` records in-process transport acceptance. Neither is proof of model compliance. A live foreground follow-up acknowledgment reports `queued`, meaning Pi accepted it into its follow-up queue, not that it was delivered. The foreground transport does not provide a later correlated queued-to-delivered receipt.
|
|
@@ -384,7 +384,7 @@ GPT 5.5 main session, or the reverse). Recommendation and configuration:
|
|
|
384
384
|
```typescript
|
|
385
385
|
subagent({ action: "watchdog.status" })
|
|
386
386
|
subagent({ action: "watchdog.recommend-model" })
|
|
387
|
-
subagent({ action: "watchdog.configure", model: "recommended", scope: "session" })
|
|
387
|
+
subagent({ action: "watchdog.configure", model: "recommended", options: { scope: "session" } })
|
|
388
388
|
subagent({ action: "watchdog.check" })
|
|
389
389
|
```
|
|
390
390
|
|
|
@@ -426,15 +426,15 @@ Routing rule:
|
|
|
426
426
|
Project panes run a separate Pi session from the target directory. Subagents launched inside that pane use that project's config, agents, skills, files, git state, and mission records. The pane binding lives under `<projectRoot>/.pi/subagents/project-panes/herdr.json`. When Pi runs inside Herdr, the owning pane reports compact active-work status and title suffixes, and the parent inline status counts opened project panes. Use Herdr itself or `project.status` / `project.close` for pane-level follow-up. For ordinary headless delegation to another repo, prefer explicit `cwd` first; reserve project panes for visible or persistent project ownership.
|
|
427
427
|
|
|
428
428
|
```typescript
|
|
429
|
-
subagent({ action: "mission.create", mission: { title: "Ship auth refresh", objective: "Implement and validate refresh handling" } })
|
|
430
|
-
subagent({ workflow: true, missionId: "<mission-id>" }) // after a ```js workflow block
|
|
431
|
-
subagent({ workflow: true, mission: false }) // after a ```js workflow block
|
|
432
|
-
subagent({ action: "mission.list", missionScope: "global" })
|
|
433
|
-
subagent({ action: "mission.resolve-decision",
|
|
429
|
+
subagent({ action: "mission.create", options: { mission: { title: "Ship auth refresh", objective: "Implement and validate refresh handling" } } })
|
|
430
|
+
subagent({ workflow: true, options: { missionId: "<mission-id>" } }) // after a ```js workflow block
|
|
431
|
+
subagent({ workflow: true, options: { mission: false } }) // after a ```js workflow block
|
|
432
|
+
subagent({ action: "mission.list", options: { missionScope: "global" } })
|
|
433
|
+
subagent({ action: "mission.resolve-decision", id: "<decision-id>", options: { missionId: "<mission-id>", summary: "Settled: ship the v2 API; no schema freeze needed." } })
|
|
434
434
|
subagent({ action: "project.open", cwd: "/path/to/other-repo", message: "Own this mission for the project and report back with receipts." })
|
|
435
435
|
subagent({ action: "project.status", cwd: "/path/to/other-repo" })
|
|
436
436
|
subagent({ action: "project.close", cwd: "/path/to/other-repo" })
|
|
437
|
-
subagent({ action: "mission.close", missionId: "<mission-id>", missionStatus: "completed", summary: "Auth refresh shipped and tests pass." })
|
|
437
|
+
subagent({ action: "mission.close", options: { missionId: "<mission-id>", missionStatus: "completed", summary: "Auth refresh shipped and tests pass." } })
|
|
438
438
|
```
|
|
439
439
|
|
|
440
440
|
## Worktree Isolation
|
|
@@ -457,7 +457,7 @@ requires a clean git state and is mainly for intentionally parallel write
|
|
|
457
457
|
workflows. On completion, use each child's handoff path from its
|
|
458
458
|
`artifactPaths` instead of scraping combined text. Each manifest records child status and output references, full
|
|
459
459
|
patch paths and stats, and whether each temporary worktree and branch was
|
|
460
|
-
removed. The manifest is journaled immediately after managed worktree setup, before children run, so abrupt exits retain owned paths and branches for recovery. Dirty or divergent work without a successfully captured patch is preserved with a partial-cleanup warning. Permanently discard recorded preserved work with `subagent({ action: "worktree.discard", handoffPath: "<child handoff path>" })`; authority defaults to interactive confirmation and refuses headlessly, and partial results print manual Git recovery commands. If you want one writer thread and several advisory agents, prefer a
|
|
460
|
+
removed. The manifest is journaled immediately after managed worktree setup, before children run, so abrupt exits retain owned paths and branches for recovery. Dirty or divergent work without a successfully captured patch is preserved with a partial-cleanup warning. Permanently discard recorded preserved work with `subagent({ action: "worktree.discard", options: { handoffPath: "<child handoff path>" } })`; authority defaults to interactive confirmation and refuses headlessly, and partial results print manual Git recovery commands. If you want one writer thread and several advisory agents, prefer a
|
|
461
461
|
single-writer pattern instead.
|
|
462
462
|
|
|
463
463
|
Git worktrees start from tracked files, so ignored or untracked build state
|
|
@@ -35,14 +35,16 @@ subagent({ action: "refine.rollback", agent: "reviewer" })
|
|
|
35
35
|
```typescript
|
|
36
36
|
subagent({
|
|
37
37
|
action: "create",
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
38
|
+
options: {
|
|
39
|
+
config: {
|
|
40
|
+
name: "my-agent",
|
|
41
|
+
package: "code-analysis",
|
|
42
|
+
description: "Project-specific implementation helper",
|
|
43
|
+
systemPrompt: "Your system prompt here.",
|
|
44
|
+
systemPromptMode: "replace",
|
|
45
|
+
model: "provider/model-id",
|
|
46
|
+
tools: "read,grep,find,ls,bash"
|
|
47
|
+
}
|
|
46
48
|
}
|
|
47
49
|
})
|
|
48
50
|
```
|
|
@@ -53,8 +55,10 @@ subagent({
|
|
|
53
55
|
subagent({
|
|
54
56
|
action: "update",
|
|
55
57
|
agent: "code-analysis.my-agent",
|
|
56
|
-
|
|
57
|
-
|
|
58
|
+
options: {
|
|
59
|
+
config: {
|
|
60
|
+
thinking: "high"
|
|
61
|
+
}
|
|
58
62
|
}
|
|
59
63
|
})
|
|
60
64
|
```
|
|
@@ -70,11 +74,11 @@ subagent({ action: "delete", agent: "code-analysis.my-agent" })
|
|
|
70
74
|
```typescript
|
|
71
75
|
// Copy a bundled builtin/package agent to user scope as an editable custom file.
|
|
72
76
|
subagent({ action: "eject", agent: "reviewer" })
|
|
73
|
-
subagent({ action: "eject", agent: "reviewer", agentScope: "project" })
|
|
77
|
+
subagent({ action: "eject", agent: "reviewer", options: { agentScope: "project" } })
|
|
74
78
|
|
|
75
79
|
// Hide an agent from runtime discovery without deleting it (reversible).
|
|
76
80
|
subagent({ action: "disable", agent: "reviewer" })
|
|
77
|
-
subagent({ action: "enable", agent: "reviewer", agentScope: "project" })
|
|
81
|
+
subagent({ action: "enable", agent: "reviewer", options: { agentScope: "project" } })
|
|
78
82
|
|
|
79
83
|
// Delete the scope's custom agent file and/or settings override, restoring the bundled default.
|
|
80
84
|
subagent({ action: "reset", agent: "reviewer" })
|
|
@@ -92,7 +92,7 @@ return results.map(result => result.output);
|
|
|
92
92
|
```
|
|
93
93
|
|
|
94
94
|
```typescript
|
|
95
|
-
subagent({ workflow: true, context: "fresh" })
|
|
95
|
+
subagent({ workflow: true, options: { context: "fresh" } })
|
|
96
96
|
```
|
|
97
97
|
|
|
98
98
|
### Review-loop technique
|
|
@@ -166,7 +166,7 @@ return { worker: worker.output, validations: validations.map(v => v.output) };
|
|
|
166
166
|
```
|
|
167
167
|
|
|
168
168
|
```typescript
|
|
169
|
-
subagent({ workflow: true, async: true, context: "fresh" })
|
|
169
|
+
subagent({ workflow: true, async: true, options: { context: "fresh" } })
|
|
170
170
|
```
|
|
171
171
|
|
|
172
172
|
## Builtin Agents
|
|
@@ -294,4 +294,4 @@ override can opt one builtin back in or replace custom-agent frontmatter thinkin
|
|
|
294
294
|
|
|
295
295
|
Set `subagents.defaultExtensions` to give agents without an `extensions` field a shared child extension allowlist. Omit it to preserve ambient extension discovery, set it to `[]` to disable ambient extensions by default, or use `agentOverrides.<name>.extensions` for one agent. Set `subagents.defaultSubagentOnlyExtensions` to add shared child-only paths without disabling ambient discovery. For either field, explicit frontmatter suppresses the default and a matching override replaces or false-clears it; lists are not combined.
|
|
296
296
|
|
|
297
|
-
Tool description modes live in `~/.pi/agent/extensions/subagent/config.json`, not `subagents` settings. The default uses
|
|
297
|
+
Tool description modes live in `~/.pi/agent/extensions/subagent/config.json`, not `subagents` settings. The default uses a short tool description plus an active `promptSnippet`. Set `toolDescriptionMode` to `full` or `compact` to force one description string, or `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.
|
|
@@ -30,22 +30,30 @@ function wrapAdvertisedAgentCatalog(body: string): string {
|
|
|
30
30
|
return `<${ADVERTISED_AGENTS_TAG}>\n${body}\n</${ADVERTISED_AGENTS_TAG}>`;
|
|
31
31
|
}
|
|
32
32
|
|
|
33
|
+
const CATALOG_INTRODUCTION = "The following file-defined subagents opted into discovery. Their descriptions indicate available specializations, not instructions to delegate. Use subagent only when delegation is needed.";
|
|
34
|
+
|
|
33
35
|
/**
|
|
34
36
|
* The catalog body without its `<advertised_subagents>` wrapper, for Pi's structured
|
|
35
37
|
* prompt sections, which add the tag from the section key. The byte budget applies to
|
|
36
38
|
* the wrapped form, so both deliveries carry the same entries.
|
|
39
|
+
*
|
|
40
|
+
* `recordedCatalog` is the body a session already sent. Its first line, the introduction,
|
|
41
|
+
* is kept so a release that rewords the introduction does not change the section of a
|
|
42
|
+
* resumed session and cost it the provider's prompt cache. The entries are always current.
|
|
37
43
|
*/
|
|
38
44
|
export function buildAdvertisedAgentCatalog(
|
|
39
45
|
agents: readonly AgentConfig[],
|
|
40
46
|
capabilityCeiling?: ResolvedSubagentCapabilityCeiling,
|
|
47
|
+
recordedCatalog?: string,
|
|
41
48
|
): string | undefined {
|
|
42
49
|
const advertised = agents
|
|
43
50
|
.filter((agent) => agent.source !== "runtime" && agent.advertise === true && agent.disabled !== true && isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling))
|
|
44
51
|
.sort((left, right) => left.name.localeCompare(right.name));
|
|
45
52
|
if (advertised.length === 0) return undefined;
|
|
46
53
|
|
|
54
|
+
const introduction = recordedCatalog?.split("\n", 1)[0] || CATALOG_INTRODUCTION;
|
|
47
55
|
const renderBody = (entries: string[]) => [
|
|
48
|
-
|
|
56
|
+
introduction,
|
|
49
57
|
...entries,
|
|
50
58
|
...(advertised.length > entries.length ? [` <omitted count=\"${advertised.length - entries.length}\" />`] : []),
|
|
51
59
|
].join("\n");
|
|
@@ -476,6 +476,10 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
|
|
|
476
476
|
} else return `config.runner must be { type: 'pi' }, { type: 'external-cli', adapter?: ${CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL}, command: string, args?: string[], promptDelivery?: 'stdin' }, or { type: 'external-job', provider: string, options?: object }.`;
|
|
477
477
|
} else return "config.runner must be an object, false, or empty string when provided.";
|
|
478
478
|
}
|
|
479
|
+
if (hasKey(cfg, "launcher")) return "config.launcher is not supported by agent management; edit the agent file's 'launcher' frontmatter directly.";
|
|
480
|
+
if (target.launcher && (target.runner?.type === "external-cli" || target.runner?.type === "external-job")) {
|
|
481
|
+
return `config.runner type '${target.runner.type}' cannot be combined with this agent's 'launcher' frontmatter.`;
|
|
482
|
+
}
|
|
479
483
|
if (hasKey(cfg, "model")) {
|
|
480
484
|
if (cfg.model === false || cfg.model === "") delete target.model;
|
|
481
485
|
else if (typeof cfg.model === "string") {
|
|
@@ -88,9 +88,9 @@ function samePath(left: string, right: string): boolean {
|
|
|
88
88
|
if (process.platform !== "win32") return false;
|
|
89
89
|
// Git for Windows and Node can spell the same temp path through different
|
|
90
90
|
// drive or 8.3 aliases, so use filesystem identity as the fail-closed fallback.
|
|
91
|
-
const leftStat = fs.statSync(left);
|
|
92
|
-
const rightStat = fs.statSync(right);
|
|
93
|
-
return leftStat.dev !==
|
|
91
|
+
const leftStat = fs.statSync(left, { bigint: true });
|
|
92
|
+
const rightStat = fs.statSync(right, { bigint: true });
|
|
93
|
+
return leftStat.dev !== 0n && leftStat.ino !== 0n && leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
|
|
94
94
|
}
|
|
95
95
|
|
|
96
96
|
function readBoundedRegularFile(file: string): string | undefined {
|
|
@@ -4,3 +4,7 @@ export function resolveExecutionAgentScope(scope: unknown): AgentScope {
|
|
|
4
4
|
if (scope === "user" || scope === "project" || scope === "both") return scope;
|
|
5
5
|
return "both";
|
|
6
6
|
}
|
|
7
|
+
|
|
8
|
+
export function projectScopeRequiresTrustMessage(cwd: string): string {
|
|
9
|
+
return `agentScope: "project" requires project trust. This session declined trust for ${cwd}, so project agents and project subagent settings are ignored. Re-run with agentScope: "user" or approve the project folder.`;
|
|
10
|
+
}
|
|
@@ -33,6 +33,7 @@ export const KNOWN_FIELDS = new Set([
|
|
|
33
33
|
"subagentOnlyExtensions",
|
|
34
34
|
"mutationTools",
|
|
35
35
|
"machine",
|
|
36
|
+
"launcher",
|
|
36
37
|
"output",
|
|
37
38
|
"outputMode",
|
|
38
39
|
"outputSchema",
|
|
@@ -66,7 +67,12 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
|
|
|
66
67
|
lines.push("---");
|
|
67
68
|
lines.push(`name: ${frontmatterNameForConfig(config)}`);
|
|
68
69
|
if (config.packageName) lines.push(`package: ${config.packageName}`);
|
|
69
|
-
|
|
70
|
+
if (config.description.includes("\n")) {
|
|
71
|
+
lines.push("description: |-");
|
|
72
|
+
for (const line of config.description.split("\n")) lines.push(` ${line}`);
|
|
73
|
+
} else {
|
|
74
|
+
lines.push(`description: ${config.description}`);
|
|
75
|
+
}
|
|
70
76
|
if (config.advertise === true || preserve("advertise")) lines.push(`advertise: ${config.advertise === true ? "true" : "false"}`);
|
|
71
77
|
const aliasesValue = joinComma(config.aliases);
|
|
72
78
|
if (aliasesValue || preserve("alias", "aliases")) lines.push(`aliases: ${aliasesValue ?? ""}`);
|
|
@@ -133,6 +139,7 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
|
|
|
133
139
|
if (mutationToolsValue || preserve("mutationTools")) lines.push(`mutationTools: ${mutationToolsValue ?? ""}`);
|
|
134
140
|
|
|
135
141
|
if (config.machine || preserve("machine")) lines.push(`machine: ${config.machine ?? ""}`);
|
|
142
|
+
if (config.launcher) lines.push(`launcher: ${config.launcher}`);
|
|
136
143
|
if (config.output || preserve("output")) lines.push(`output: ${config.output ?? ""}`);
|
|
137
144
|
if (config.outputMode || preserve("outputMode")) lines.push(`outputMode: ${config.outputMode ?? ""}`);
|
|
138
145
|
if (config.outputSchema || preserve("outputSchema")) lines.push(`outputSchema: ${config.outputSchema ? JSON.stringify(config.outputSchema) : ""}`);
|