@xzzpig/pi-subagents 0.14.0 → 0.15.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 +239 -0
- package/README.md +7 -6
- package/agents/evidence-auditor.md +34 -0
- package/agents/researcher.md +23 -13
- package/agents/reviewer.md +3 -2
- package/docs/agents.md +55 -136
- package/docs/configuration.md +92 -14
- package/docs/extension-api.md +132 -74
- package/docs/fork-extensions.md +184 -0
- package/docs/missions.md +10 -2
- package/docs/models.md +11 -22
- package/docs/observability.md +63 -11
- package/docs/standalone-background.md +59 -0
- package/docs/tool-reference.md +42 -23
- package/docs/watchdog.md +39 -10
- package/docs/workflows.md +58 -19
- package/index.ts +5 -2
- package/inspector-runner.mjs +2 -2
- package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +13 -3
- package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +18 -6
- package/node_modules/@xzzpig/pi-components/src/transcript.ts +26 -6
- package/package.json +9 -4
- package/prompts/parallel-review.md +1 -1
- package/runner-peer-loader.mjs +24 -0
- package/runner-peer-preload.mjs +36 -0
- package/skills/pi-subagents/SKILL.md +34 -22
- package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
- package/skills/pi-subagents/references/execution-controls.md +27 -8
- package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
- package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
- package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
- package/skills/pi-subagents/references/review-and-validation.md +3 -3
- package/src/agents/advertised-agent-prompt.ts +94 -0
- package/src/agents/agent-eject.ts +339 -0
- package/src/agents/agent-management.ts +79 -387
- package/src/agents/agent-serializer.ts +6 -3
- package/src/agents/agents.ts +198 -72
- package/src/agents/builtin-names.ts +1 -0
- package/src/agents/chain-serializer.ts +5 -0
- package/src/agents/runtime-agent-registry.ts +7 -6
- package/src/api/agent-management.ts +2 -2
- package/src/api/delegation.ts +4 -0
- package/src/api/preflight.ts +131 -86
- package/src/api/required-child-extensions.ts +6 -0
- package/src/api/shared-types.ts +3 -1
- package/src/api/workflow-resources.ts +6 -0
- package/src/extension/config.ts +14 -37
- package/src/extension/fanout-child.ts +68 -5
- package/src/extension/herdr-pi-bridge.ts +164 -0
- package/src/extension/index.ts +141 -51
- package/src/extension/public-execution.ts +7 -6
- package/src/extension/rpc.ts +8 -21
- package/src/extension/schemas.ts +86 -84
- package/src/extension/tool-description.ts +32 -79
- package/src/inspectors/actions.ts +148 -0
- package/src/inspectors/ghostty/actions.ts +74 -0
- package/src/inspectors/ghostty/plugin.ts +17 -0
- package/src/inspectors/herdr/actions.ts +99 -179
- package/src/inspectors/herdr/plugin.ts +20 -0
- package/src/inspectors/herdr/project-panes.ts +4 -1
- package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
- package/src/inspectors/plugins.ts +8 -0
- package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
- package/src/inspectors/types.ts +51 -0
- package/src/integrations/pi-web-session-liveness.ts +73 -0
- package/src/intercom/intercom-bridge.ts +50 -8
- package/src/intercom/native-supervisor-channel.ts +142 -115
- package/src/intercom/supervisor-ui.ts +3 -2
- package/src/missions/workflow-state.ts +37 -16
- package/src/policy/authority.ts +4 -0
- package/src/profiles/profiles.ts +12 -6
- package/src/runs/background/active-async-capacity.ts +22 -18
- package/src/runs/background/active-run-index.ts +17 -1
- package/src/runs/background/async-execution.ts +359 -176
- package/src/runs/background/async-job-tracker.ts +41 -7
- package/src/runs/background/async-resume.ts +19 -12
- package/src/runs/background/async-retention.ts +20 -0
- package/src/runs/background/async-status-snapshot.ts +10 -12
- package/src/runs/background/async-status.ts +38 -35
- package/src/runs/background/auto-drain.ts +59 -35
- package/src/runs/background/binary-bootstrap.ts +38 -0
- package/src/runs/background/chain-append.ts +1 -1
- package/src/runs/background/chain-root-attachment.ts +22 -33
- package/src/runs/background/control-channel.ts +78 -44
- package/src/runs/background/fleet-view.ts +30 -2
- package/src/runs/background/notify.ts +193 -19
- package/src/runs/background/owned-process-tree.ts +35 -8
- package/src/runs/background/process-terminal.ts +23 -23
- package/src/runs/background/result-files.ts +8 -4
- package/src/runs/background/result-watcher.ts +19 -2
- package/src/runs/background/retained-nested-route-tracker.ts +96 -0
- package/src/runs/background/run-child-session.ts +118 -41
- package/src/runs/background/run-status.ts +78 -5
- package/src/runs/background/runner-aliases.ts +22 -5
- package/src/runs/background/runner-child-launch.ts +93 -0
- package/src/runs/background/runner-child-sessions.ts +5 -4
- package/src/runs/background/runner-http-dispatcher.ts +119 -0
- package/src/runs/background/scheduled-runs.ts +51 -18
- package/src/runs/background/stale-run-reconciler.ts +38 -12
- package/src/runs/background/steering.ts +20 -2
- package/src/runs/background/subagent-runner.ts +770 -444
- package/src/runs/background/subagent-wait.ts +179 -28
- package/src/runs/background/wait-completions.ts +79 -27
- package/src/runs/background/wait-subscriptions.ts +9 -3
- package/src/runs/background/wait-tool.ts +5 -3
- package/src/runs/foreground/async-steering-action.ts +37 -7
- package/src/runs/foreground/async-stop-action.ts +93 -3
- package/src/runs/foreground/execution.ts +174 -194
- package/src/runs/foreground/foreground-history.ts +5 -2
- package/src/runs/foreground/prompt-audit.ts +12 -6
- package/src/runs/foreground/subagent-executor.ts +915 -411
- package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
- package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
- package/src/runs/shared/acceptance.ts +54 -14
- package/src/runs/shared/agent-contract.ts +1 -1
- package/src/runs/shared/async-status-projection.ts +172 -78
- package/src/runs/shared/capability-ceiling.ts +2 -0
- package/src/runs/shared/child-hooks.ts +167 -3
- package/src/runs/shared/child-launch-plan.ts +15 -3
- package/src/runs/shared/child-launch.ts +49 -85
- package/src/runs/shared/child-lifecycle.ts +6 -3
- package/src/runs/shared/child-runtime-config.ts +8 -1
- package/src/runs/shared/child-session.ts +130 -24
- package/src/runs/shared/child-tool-plan.ts +149 -112
- package/src/runs/shared/completion-evidence.ts +2 -2
- package/src/runs/shared/completion-guard.ts +6 -3
- package/src/runs/shared/dynamic-fanout.ts +2 -2
- package/src/runs/shared/effective-system-prompt.ts +33 -0
- package/src/runs/shared/external-cli-contract.ts +11 -1
- package/src/runs/shared/external-cli-preflight.ts +6 -2
- package/src/runs/shared/external-cli-runner.ts +9 -7
- package/src/runs/shared/herdr-connection.ts +134 -0
- package/src/runs/shared/herdr-external-adapters.ts +169 -0
- package/src/runs/shared/herdr-machine.ts +279 -0
- package/src/runs/shared/herdr-pi-protocol.ts +59 -0
- package/src/runs/shared/herdr-placed-run.ts +263 -0
- package/src/runs/shared/host-step-status.ts +11 -11
- package/src/runs/shared/llm-intent-arbiter.ts +40 -21
- package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
- package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
- package/src/runs/shared/model-scope.ts +1 -1
- package/src/runs/shared/nested-events.ts +27 -34
- package/src/runs/shared/orca-progress-tabs.ts +7 -1
- package/src/runs/shared/parallel-handoff.ts +57 -12
- package/src/runs/shared/parallel-utils.ts +10 -4
- package/src/runs/shared/pi-spawn.ts +10 -0
- package/src/runs/shared/profile-extensions.ts +134 -0
- package/src/runs/shared/profile-launch-env.ts +113 -0
- package/src/runs/shared/readonly-drain-observation.ts +42 -0
- package/src/runs/shared/run-fanout-budget.ts +8 -8
- package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
- package/src/runs/shared/sandbox-profile-guard.ts +34 -0
- package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
- package/src/runs/shared/task-intent.ts +46 -13
- package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
- package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
- package/src/runs/shared/worktree-setup-command.ts +213 -0
- package/src/runs/shared/worktree.ts +437 -214
- package/src/shared/child-cache-retention.ts +43 -0
- package/src/shared/fork-context.ts +15 -72
- package/src/shared/launch-contract.ts +70 -8
- package/src/shared/model-response-aliases.ts +13 -0
- package/src/shared/opencode-session-headers.ts +30 -0
- package/src/shared/permission-profile.ts +14 -0
- package/src/shared/pruned-fork.ts +1 -1
- package/src/shared/required-child-extensions.ts +81 -0
- package/src/shared/sandbox-profile.ts +14 -0
- package/src/shared/settings.ts +5 -2
- package/src/shared/shortcuts.ts +0 -4
- package/src/shared/types.ts +163 -90
- package/src/shared/utils.ts +10 -2
- package/src/shared/watch-strategy.ts +2 -0
- package/src/shared/workflow-child-permit.ts +18 -13
- package/src/slash/delegation-adapters.ts +3 -1
- package/src/slash/delegation-request.ts +14 -0
- package/src/slash/slash-commands.ts +2 -7
- package/src/slash/subagents-admin.ts +31 -14
- package/src/tui/fleet-status.ts +165 -20
- package/src/tui/fleet.ts +30 -19
- package/src/tui/render.ts +210 -50
- package/src/watchdog/child-status.ts +28 -28
- package/src/watchdog/lsp-diagnostics.ts +1 -1
- package/src/watchdog/model-selection.ts +21 -1
- package/src/watchdog/permission-arbiter.ts +5 -2
- package/src/watchdog/register-child.ts +10 -2
- package/src/watchdog/register-main.ts +39 -35
- package/src/watchdog/render.ts +1 -1
- package/src/watchdog/review.ts +122 -74
- package/src/watchdog/rules.ts +1 -1
- package/src/watchdog/runtime.ts +100 -27
- package/src/watchdog/scope.ts +1 -1
- package/src/watchdog/settings.ts +3 -0
- package/src/watchdog/tool-actions.ts +13 -12
- package/src/watchdog/turn-delta.ts +23 -0
- package/src/watchdog/types.ts +5 -3
- package/src/watchdog/warning-format.ts +1 -1
- package/src/workflows/chat-progress.ts +3 -3
- package/src/workflows/scripted-workflow.ts +349 -26
- package/src/workflows/workflow-checklist.ts +17 -20
- package/src/workflows/workflow-child-summary.ts +57 -8
- package/src/workflows/workflow-preflight.ts +19 -19
- package/src/workflows/workflow-receipt.ts +24 -6
- package/src/workflows/workflow-resources.ts +108 -22
- package/src/workflows/workflow-settlement.ts +3 -0
- package/src/runs/shared/model-exclusions.ts +0 -373
- /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
package/docs/workflows.md
CHANGED
|
@@ -19,6 +19,14 @@ Child-safety boundaries are enforced at runtime:
|
|
|
19
19
|
- By default, children do not register the `subagent` tool and receive boundary instructions that they are not the parent orchestrator and must not propose or run subagents.
|
|
20
20
|
- The explicit exception is an agent whose resolved builtin `tools` includes `subagent`; that child gets a child-safe `subagent` tool for the fanout work the parent assigned, still bounded by `maxSubagentDepth`.
|
|
21
21
|
|
|
22
|
+
### Failed lane recovery and execution-mode boundaries
|
|
23
|
+
|
|
24
|
+
A failure in the subagent workflow, child launch, prompt runtime, extension loading, or child tooling setup is a lane infrastructure blocker. It is not permission to silently retry through `interactive_shell`, `pi -ne`, Codex/Claude/Cursor CLI, a foreground agent, or another external execution mode.
|
|
25
|
+
|
|
26
|
+
Stop and report the exact failure, run/status, and repository/cwd/worktree/branch/ref state. Before a same-protocol retry or asking the owner, verify the worktree is clean or capture the partial diff. Retry or fix the `subagent` path only through a clear same-protocol action. For backlog lanes and other subagent-governed workflows, external/foreground/CLI fallback requires explicit owner approval. `interactive_shell` remains valid when the user explicitly requests visible foreground/CLI work or the task is outside the governed subagent protocol.
|
|
27
|
+
|
|
28
|
+
Pi core may print a generic `pi -ne` extension-load hint; that out-of-repo hint is not protocol-approved fallback. A verified compaction abort may continue the retained child once on its already resolved model; it does not authorize an execution-mode or model switch.
|
|
29
|
+
|
|
22
30
|
## Prompt shortcuts
|
|
23
31
|
|
|
24
32
|
The package includes reusable prompt templates for common workflows. You do not need them, but they are handy when you want the same shape every time:
|
|
@@ -37,6 +45,10 @@ Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the syn
|
|
|
37
45
|
|
|
38
46
|
Use direct `{ agent, task }` for one bounded child. Use `workflowScript` when the parent needs a stable keyed child, sequence, fanout, steering, retry, or aggregation. For ordinary parallel fanout, use `await runs.all([{ key, agent, task }, ...])`. It resolves to an ordered array, not a key map, so use indexes, destructuring, or `.map(...)`, not `results.<key>`. Do not read `.output` from unawaited `runs.run` launches. Store a `runs.run` promise only when the script later observes it with `await`, `Promise.race`, or `Promise.all`, such as steering a live child before awaiting its result. Scripts are ordinary JavaScript statement bodies. Use an explicit `return` for a useful result:
|
|
39
47
|
|
|
48
|
+
For multi-step or parallel work, make exactly one top-level `subagent` workflow call with `async:true` and launch children only inside it. Read this guide for recipes rather than constructing a second top-level orchestration. Available sandbox helpers include `runs.run`, `runs.all`, `runs.lanes`, `runs.steer`, `runs.status`, `runs.ref`/`runs.refs`, `emit`, `console`, standard JavaScript, and mission `state` when enabled. No filesystem, shell, arbitrary Pi tools, or host globals are available; named resources alone may grant `runs.host` authority.
|
|
49
|
+
|
|
50
|
+
Workflow-level child controls default onto each `runs.run`/`runs.all` launch; explicit child fields override them. See [retained children](tool-reference.md#retained-children) for follow-up challenges, [output binding](tool-reference.md#output-mode-details) for durable artifacts, and [schedules](missions.md#schedules) for delayed/recurring scripts.
|
|
51
|
+
|
|
40
52
|
Child results cross into the script as plain JSON data. Non-JSON host metadata is omitted, so use returned fields such as `runId`, `ok`, `output`, and `structuredOutput` for workflow control.
|
|
41
53
|
|
|
42
54
|
Validate a script without launching children:
|
|
@@ -57,6 +69,16 @@ subagent({ action: "validate", workflowScriptPath: "workflows/review.js" });
|
|
|
57
69
|
|
|
58
70
|
The fields are mutually exclusive. Relative paths resolve against the request `cwd`; absolute paths pass through. The host reads the file before validation, schedule creation, or workflow sandbox execution. The sandbox still has no filesystem access. Missing, unreadable, and empty files return file input errors instead of script syntax errors.
|
|
59
71
|
|
|
72
|
+
Inline and file-backed scripts accept bounded plain-JSON `args`:
|
|
73
|
+
|
|
74
|
+
```js
|
|
75
|
+
subagent({ workflowScriptPath: "workflows/review.js", args: { target: "src/workflows" } });
|
|
76
|
+
// workflows/review.js
|
|
77
|
+
return runs.run("review", { agent: "reviewer", task: `Review ${args.target}` });
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Omitted arguments are an empty object. The `args` object, its nested objects, and its arrays are frozen in the sandbox. Arguments are data only: they do not grant `runs.host` or other authority. Normalized arguments are persisted with workflow and schedule evidence for replay and diagnosis, so do not put secrets in them. Routine status text does not render argument values.
|
|
81
|
+
|
|
60
82
|
### Named workflow resources for permission extensions
|
|
61
83
|
|
|
62
84
|
Use a named workflow resource when a permission or policy extension needs to distinguish extension-resolved workflow content from raw model-authored scripts:
|
|
@@ -88,17 +110,18 @@ subagent({
|
|
|
88
110
|
- `toolBudget` becomes the default for each child unless that child supplies a narrower value.
|
|
89
111
|
- `usageBudget` accounts for reported usage across completed workflow children. Once exhausted, it rejects later child launches but does not stop children that are already running.
|
|
90
112
|
- Budget and timeout stops return a structured `terminalOutcome` with `state: "partial"` and reason `budget_exhausted` or `timeout`. Workflow receipts keep settled child evidence for recovery.
|
|
113
|
+
- After an async workflow receipt is successfully published, `workflowReceiptPath` exposes its exact path in wait completion details, completion notifications, and exact status/debug details. Text responses also identify the receipt. Pending runs and failed receipt publications omit the reference; older status records are not backfilled. The reference records publication, not a guarantee against later retention cleanup. Raw result files retain `workflowReceipt: { path, receipt }`.
|
|
91
114
|
|
|
92
115
|
These controls are opt-in. Avoid tight hard budgets for mutation-capable workers unless the workflow has an explicit checkpoint and handoff path.
|
|
93
116
|
|
|
94
|
-
The result is `{ ok, errors }`. Invalid scripts return a tool error and include line and column data when available. Validation checks syntax, portable nested-async rules, literal `runs.run` and `runs.all` keys, duplicate literal keys in one `runs.all` group, direct keyed access to a known `runs.all` result, and statically clear non-JSON boundary values. Dynamic keys and other runtime-only values are accepted without a warning. Validation does not discover agents, launch children, or create run artifacts.
|
|
117
|
+
The result is `{ ok, errors }`. Invalid scripts return a tool error and include line and column data when available. Validation checks syntax, portable nested-async rules, literal `runs.run` and `runs.all` keys and child `baseRef` values, duplicate literal keys in one `runs.all` group, direct keyed access to a known `runs.all` result, and statically clear non-JSON boundary values. Dynamic keys and other runtime-only values are accepted without a warning. Validation does not discover agents, launch children, or create run artifacts.
|
|
95
118
|
|
|
96
119
|
```js
|
|
97
120
|
subagent({ workflowScript: `
|
|
98
|
-
const scan = await runs.run("scan", { agent: "scout", task: "Scan the codebase" });
|
|
121
|
+
const scan = await runs.run("scan", { label: "Map codebase behavior", agent: "scout", task: "Scan the codebase" });
|
|
99
122
|
const reviews = await runs.all([
|
|
100
|
-
{ key: "correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
|
|
101
|
-
{ key: "tests", agent: "reviewer", task: "Review tests: " + scan.output }
|
|
123
|
+
{ key: "correctness", label: "Review codebase correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
|
|
124
|
+
{ key: "tests", label: "Review test coverage", agent: "reviewer", task: "Review tests: " + scan.output }
|
|
102
125
|
]);
|
|
103
126
|
return reviews.map(result => result.output);
|
|
104
127
|
` });
|
|
@@ -109,7 +132,7 @@ Keep helper functions portable across Node and Bun. Use top-level `await`, plain
|
|
|
109
132
|
```js
|
|
110
133
|
subagent({ workflowScript: `
|
|
111
134
|
function scan() {
|
|
112
|
-
return runs.run("scan", { agent: "scout", task: "Scan the codebase" });
|
|
135
|
+
return runs.run("scan", { label: "Map codebase behavior", agent: "scout", task: "Scan the codebase" });
|
|
113
136
|
}
|
|
114
137
|
const result = await scan();
|
|
115
138
|
return result.output;
|
|
@@ -120,8 +143,8 @@ Chaining is still supported. The supported form is scripted chaining: await one
|
|
|
120
143
|
|
|
121
144
|
```js
|
|
122
145
|
subagent({ workflowScript: `
|
|
123
|
-
const plan = await runs.run("plan", { agent: "scout", task: "Plan the migration" });
|
|
124
|
-
const patch = await runs.run("patch", { agent: "worker", task: "Implement this plan:\n" + plan.output });
|
|
146
|
+
const plan = await runs.run("plan", { label: "Plan migration behavior", agent: "scout", task: "Plan the migration" });
|
|
147
|
+
const patch = await runs.run("patch", { label: "Implement migration behavior", agent: "worker", task: "Implement this plan:\n" + plan.output });
|
|
125
148
|
return patch.output;
|
|
126
149
|
` });
|
|
127
150
|
```
|
|
@@ -136,16 +159,16 @@ subagent({ workflowScript: `
|
|
|
136
159
|
{
|
|
137
160
|
key: "api",
|
|
138
161
|
stages: [
|
|
139
|
-
{ key: "writer", agent: "worker", task: "Implement the API change" },
|
|
140
|
-
{ key: "challenge", resume: "previous", task: "Challenge the API implementation" },
|
|
141
|
-
{ key: "review", agent: "reviewer", task: "Review the API lane" }
|
|
162
|
+
{ key: "writer", label: "Implement API behavior", agent: "worker", task: "Implement the API change" },
|
|
163
|
+
{ key: "challenge", label: "Challenge API behavior", resume: "previous", task: "Challenge the API implementation" },
|
|
164
|
+
{ key: "review", label: "Review API behavior", agent: "reviewer", task: "Review the API lane" }
|
|
142
165
|
]
|
|
143
166
|
},
|
|
144
167
|
{
|
|
145
168
|
key: "ui",
|
|
146
169
|
stages: [
|
|
147
|
-
{ key: "writer", agent: "worker", task: "Implement the UI change" },
|
|
148
|
-
{ key: "review", agent: "reviewer", task: "Review the UI lane" }
|
|
170
|
+
{ key: "writer", label: "Implement UI behavior", agent: "worker", task: "Implement the UI change" },
|
|
171
|
+
{ key: "review", label: "Review UI behavior", agent: "reviewer", task: "Review the UI lane" }
|
|
149
172
|
]
|
|
150
173
|
}
|
|
151
174
|
]);
|
|
@@ -194,7 +217,7 @@ subagent({ workflowScript: `
|
|
|
194
217
|
` });
|
|
195
218
|
```
|
|
196
219
|
|
|
197
|
-
The receipt state is `queued`, `delivered`, `missed`, or `failed`. `delivered` means the child Pi
|
|
220
|
+
The receipt state is `queued`, `delivered`, `missed`, or `failed`. For an async child, `delivered` means it consumed the correlated user input; for a foreground child, it means the in-process Pi transport accepted the input. It does not mean the model followed it. `missed` means the keyed child became terminal or had no live route before delivery. This first slice uses the existing foreground and async steering transports but does not start steering recovery. Workflow traces include one steering attempt entry and one receipt entry.
|
|
198
221
|
|
|
199
222
|
Always await or return a `runs.steer` promise. The workflow waits for an observed steering side effect to settle before it exits and rejects fire-and-forget calls. Use ordinary `Promise.race` when the first child or steering receipt should advance the script. There is no callback API or child inbox access.
|
|
200
223
|
|
|
@@ -347,6 +370,8 @@ known, or for explicit emergency hotfix lanes.
|
|
|
347
370
|
|
|
348
371
|
For watched same-repo workflows, pass `async:false` only when the parent must block until completion. That blocking mode also shows the live in-chat workflow card. `chatProgress` can force `off` or `live-card` when the automatic policy is not what you want. Blocking workflows default to a 30-minute timeout; async workflows have no default timeout. See the [tool reference](tool-reference.md) for the full parameter list.
|
|
349
372
|
|
|
373
|
+
Synchronous workflows publish trace and `emit(...)` updates through the tool update callback regardless of `chatProgress`, including RPC/headless and cross-repository runs. These updates include `details.workflow` and `details.workflowChildren`; `chatProgress: "off"` disables the live card, not transport progress. Running foreground child rows additionally expose bounded `activity` (current tool, timing, and counters), plus resolved model/thinking when available, keyed by `childId`. Activity-only updates coalesce over 100 ms; lifecycle updates remain immediate. Activity clears when children settle, and is not persisted for async workflows. Tool names are limited to 256 UTF-8 bytes and each activity object is below 2 KiB (including JSON escaping); arguments and transcripts are not forwarded.
|
|
374
|
+
|
|
350
375
|
The legacy `/chain`, `/parallel`, and `/run-chain` commands are not registered.
|
|
351
376
|
|
|
352
377
|
## Direct commands
|
|
@@ -369,10 +394,14 @@ Each child uses the existing worktree lifecycle: it branches from clean HEAD, jo
|
|
|
369
394
|
|
|
370
395
|
A top-level `{ workflowScript, worktree: true }` makes isolation the default for every workflow child. An individual child can override that default with `worktree: false`. Keep one writer when parallel writes are not intentionally isolated.
|
|
371
396
|
|
|
372
|
-
|
|
397
|
+
Before a materialized `runs.run` or `runs.all` group dispatches fresh children, isolated sources must be Git repositories with clean working trees (excluding `.pi/subagents/` runtime state). A rejected group dispatches no children and spends no fan-out slots or child output claims; key-level failure traces can remain. Checks are shared only within that group, are cancellable, and run again at allocation because sources can change. Retained resumes keep their stored contracts. Select the correct cwd or arrange an operator-approved commit/stash; isolation is never dropped automatically.
|
|
398
|
+
|
|
399
|
+
Use `baseRef` to branch managed worktrees from `HEAD` or a supported named ref such as `refs/heads/release`, `refs/tags/v1`, or `origin/main`. Full 40/64-character commit IDs and revision expressions such as `HEAD~1` are unsupported. For example, `{ workflowScript, worktree: true, baseRef: "refs/heads/release" }` applies the release ref to children unless a child supplies its own `baseRef`. If omitted, the default `HEAD` is resolved at worktree allocation, not when the script is validated or a schedule is created. The source checkout must still be clean, and the ref must resolve to a commit before any worktree is allocated.
|
|
373
400
|
|
|
374
401
|
Configure the worktree provider, native path layout, base directory, and setup hook in [configuration.md](configuration.md).
|
|
375
402
|
|
|
403
|
+
Setup waits remain nonblocking and cancellable. Normal cleanup, including detached foreground finalization, waits for the same in-process setup turn rather than retaining worktrees merely because another setup is active. This is not a cross-process lock. Hooks must follow the [finite setup contract](configuration.md#worktreesetuphook).
|
|
404
|
+
|
|
376
405
|
### Lane metadata lifecycle
|
|
377
406
|
|
|
378
407
|
Workflow children may declare a bounded `lane` object (`version`, `key`, optional
|
|
@@ -394,11 +423,13 @@ Older runs without lane metadata remain readable and retain their existing
|
|
|
394
423
|
handoff/cleanup behavior. Missing lane, receipt, or handoff metadata is
|
|
395
424
|
unknown—not eligible for destructive cleanup.
|
|
396
425
|
|
|
397
|
-
|
|
398
|
-
display-only status
|
|
399
|
-
|
|
400
|
-
ownership
|
|
401
|
-
|
|
426
|
+
Managed setup records actual allocation attempts in the handoff; only validated
|
|
427
|
+
allocations become cleanup tasks and display-only status paths/branches. On
|
|
428
|
+
cancellation or failure with unknown settlement, it retains actual/attempted
|
|
429
|
+
ownership evidence and artifacts for manual reconciliation, blocking further
|
|
430
|
+
unsafe setup and cleanup in that process. An allocator interrupted before
|
|
431
|
+
reporting its path may leave branch-only diagnostics, never an invented path.
|
|
432
|
+
Inspect the handoff before reconciliation; cleanup still requires fresh checks.
|
|
402
433
|
|
|
403
434
|
## Supervisor coordination (child asks parent)
|
|
404
435
|
|
|
@@ -424,6 +455,14 @@ Children should not ask for clarification when the only conflict is review-only/
|
|
|
424
455
|
|
|
425
456
|
The parent replies with `subagent_supervisor({ action: "reply", replyTo, message })` or checks pending requests with `subagent_supervisor({ action: "pending" })`. Supervisor messages are scoped to the exact Pi session id that spawned the child. A second Pi session in the same repository does not receive those requests.
|
|
426
457
|
|
|
458
|
+
A nested coordinator needs both directions of coordination. If its agent declares an explicit `tools` allowlist, include `subagent_supervisor` to answer its own children, alongside `subagent` for delegation and `contact_supervisor` for asking its parent:
|
|
459
|
+
|
|
460
|
+
```yaml
|
|
461
|
+
tools: read, subagent, contact_supervisor, subagent_supervisor
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
For A → B → C, C's request belongs to B, not A. B can escalate a separate question to A with `contact_supervisor`, then answer C using C's original `replyTo` request id. A's reply to B does not resolve C's request, and steering is not a substitute for replying. Only fanout-authorized children get the downward supervisor provider; explicit tool exclusions and capability ceilings still apply, and ordinary leaves do not gain delegation or reply tools. Requesting `subagent_supervisor` without fanout authorization fails at launch with an actionable error. A coordinator that excludes the reply tool does not start downward supervision or receive prompts to use it. Explicitly selected native coordination tools survive host-builtin filtering because their providers are child runtime hooks, not host builtins.
|
|
465
|
+
|
|
427
466
|
Child-side routine completion handoffs are not expected. If a child appears stalled, needs-attention notices show up in the parent session with useful next actions, such as checking `subagent({ action: "status" })`, interrupting the run, or nudging the child.
|
|
428
467
|
|
|
429
468
|
If a `workflowScript` child detaches through `contact_supervisor`, the enclosing async workflow stays `paused` until that child exits. Then the extension reconciles it to `complete` or `failed`. Wait on the child until that happens.
|
package/index.ts
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
2
2
|
import type {} from "./src/types/pi-runtime-compat.d.ts";
|
|
3
|
+
import { HERDR_PI_MODE_ENV } from "./src/runs/shared/herdr-pi-protocol.ts";
|
|
3
4
|
|
|
4
|
-
const
|
|
5
|
+
const registerExtension = process.env[HERDR_PI_MODE_ENV] === "1"
|
|
6
|
+
? (await import("./src/extension/herdr-pi-bridge.ts")).default
|
|
7
|
+
: process.env.PI_SUBAGENT_CHILD === "1"
|
|
5
8
|
? undefined
|
|
6
9
|
: (await import("./src/extension/index.ts")).default;
|
|
7
10
|
|
|
8
11
|
export default function registerSubagentExtension(pi: ExtensionAPI): void {
|
|
9
|
-
|
|
12
|
+
registerExtension?.(pi);
|
|
10
13
|
}
|
package/inspector-runner.mjs
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import { createJiti } from "jiti";
|
|
2
2
|
|
|
3
3
|
const jiti = createJiti(import.meta.url);
|
|
4
|
-
const { runInspector } = await jiti.import("./src/inspectors/
|
|
4
|
+
const { runInspector } = await jiti.import("./src/inspectors/inspector-runner.ts");
|
|
5
5
|
|
|
6
6
|
try {
|
|
7
7
|
runInspector();
|
|
8
8
|
} catch (cause) {
|
|
9
|
-
process.stderr.write(`
|
|
9
|
+
process.stderr.write(`Inspector failed: ${cause instanceof Error ? cause.message : String(cause)}\n`);
|
|
10
10
|
process.exitCode = 1;
|
|
11
11
|
}
|
|
@@ -54,11 +54,19 @@ type Theme = TranscriptTheme;
|
|
|
54
54
|
type ThemeColor = string;
|
|
55
55
|
type ThemeBackground = string;
|
|
56
56
|
export type TranscriptNoticeTone = "info" | "warning" | "error";
|
|
57
|
+
/**
|
|
58
|
+
* How a turn ended. A host that distinguishes a completed exchange from one the
|
|
59
|
+
* user aborted or that failed records it on the turn's end boundary; rendering
|
|
60
|
+
* treats every finished turn the same, so this stays metadata for hosts/tests.
|
|
61
|
+
*/
|
|
62
|
+
export type TranscriptTurnOutcome = "completed" | "aborted" | "failed";
|
|
57
63
|
export type TranscriptEntry = {
|
|
58
64
|
id: number;
|
|
59
65
|
turnId: number;
|
|
60
66
|
type: "turn-boundary";
|
|
61
67
|
phase: "start" | "end";
|
|
68
|
+
/** Present on `end` boundaries when the host reported how the turn ended. */
|
|
69
|
+
outcome?: TranscriptTurnOutcome;
|
|
62
70
|
} | {
|
|
63
71
|
id: number;
|
|
64
72
|
turnId: number;
|
|
@@ -206,10 +214,12 @@ export declare function findLatestEntry<TType extends TranscriptEntry["type"]>(s
|
|
|
206
214
|
* Closes `turnId` (defaulting to the current turn): appends the end boundary
|
|
207
215
|
* unless one already exists, clears streaming flags on the turn's entries,
|
|
208
216
|
* and updates bookkeeping. Idempotent — finishing an already-finished turn is
|
|
209
|
-
* a no-op for boundary creation.
|
|
210
|
-
*
|
|
217
|
+
* a no-op for boundary creation. An optional `outcome` is recorded on the end
|
|
218
|
+
* boundary, letting hosts distinguish completed, aborted, and failed turns.
|
|
219
|
+
* Public building block for hosts that know when a replayed exchange is
|
|
220
|
+
* complete.
|
|
211
221
|
*/
|
|
212
|
-
export declare function finishTurn(state: TranscriptState, turnId?: number | null): void;
|
|
222
|
+
export declare function finishTurn(state: TranscriptState, turnId?: number | null, outcome?: TranscriptTurnOutcome): void;
|
|
213
223
|
export declare function removeTranscriptTurn(state: TranscriptState, turnId: number | null): void;
|
|
214
224
|
/**
|
|
215
225
|
* Degraded stand-in stored on a tool-call entry when the original arguments
|
|
@@ -314,17 +314,29 @@ export function findLatestEntry(state, turnId, type) {
|
|
|
314
314
|
* Closes `turnId` (defaulting to the current turn): appends the end boundary
|
|
315
315
|
* unless one already exists, clears streaming flags on the turn's entries,
|
|
316
316
|
* and updates bookkeeping. Idempotent — finishing an already-finished turn is
|
|
317
|
-
* a no-op for boundary creation.
|
|
318
|
-
*
|
|
317
|
+
* a no-op for boundary creation. An optional `outcome` is recorded on the end
|
|
318
|
+
* boundary, letting hosts distinguish completed, aborted, and failed turns.
|
|
319
|
+
* Public building block for hosts that know when a replayed exchange is
|
|
320
|
+
* complete.
|
|
319
321
|
*/
|
|
320
|
-
export function finishTurn(state, turnId = state.currentTurnId) {
|
|
322
|
+
export function finishTurn(state, turnId = state.currentTurnId, outcome) {
|
|
321
323
|
if (turnId === null)
|
|
322
324
|
return;
|
|
323
|
-
const
|
|
325
|
+
const endBoundary = state.entries.find((entry) => entry.turnId === turnId &&
|
|
324
326
|
entry.type === "turn-boundary" &&
|
|
325
327
|
entry.phase === "end");
|
|
326
|
-
if (
|
|
327
|
-
|
|
328
|
+
if (endBoundary) {
|
|
329
|
+
if (outcome !== undefined)
|
|
330
|
+
endBoundary.outcome = outcome;
|
|
331
|
+
}
|
|
332
|
+
else {
|
|
333
|
+
appendEntry(state, {
|
|
334
|
+
type: "turn-boundary",
|
|
335
|
+
turnId,
|
|
336
|
+
phase: "end",
|
|
337
|
+
...(outcome === undefined ? {} : { outcome }),
|
|
338
|
+
});
|
|
339
|
+
}
|
|
328
340
|
for (const entry of state.entries) {
|
|
329
341
|
if (entry.turnId !== turnId)
|
|
330
342
|
continue;
|
|
@@ -79,12 +79,21 @@ type ThemeBackground = string;
|
|
|
79
79
|
|
|
80
80
|
export type TranscriptNoticeTone = "info" | "warning" | "error";
|
|
81
81
|
|
|
82
|
+
/**
|
|
83
|
+
* How a turn ended. A host that distinguishes a completed exchange from one the
|
|
84
|
+
* user aborted or that failed records it on the turn's end boundary; rendering
|
|
85
|
+
* treats every finished turn the same, so this stays metadata for hosts/tests.
|
|
86
|
+
*/
|
|
87
|
+
export type TranscriptTurnOutcome = "completed" | "aborted" | "failed";
|
|
88
|
+
|
|
82
89
|
export type TranscriptEntry =
|
|
83
90
|
| {
|
|
84
91
|
id: number;
|
|
85
92
|
turnId: number;
|
|
86
93
|
type: "turn-boundary";
|
|
87
94
|
phase: "start" | "end";
|
|
95
|
+
/** Present on `end` boundaries when the host reported how the turn ended. */
|
|
96
|
+
outcome?: TranscriptTurnOutcome;
|
|
88
97
|
}
|
|
89
98
|
| { id: number; turnId: number; type: "user-message"; text: string }
|
|
90
99
|
| {
|
|
@@ -555,22 +564,33 @@ export function findLatestEntry<TType extends TranscriptEntry["type"]>(
|
|
|
555
564
|
* Closes `turnId` (defaulting to the current turn): appends the end boundary
|
|
556
565
|
* unless one already exists, clears streaming flags on the turn's entries,
|
|
557
566
|
* and updates bookkeeping. Idempotent — finishing an already-finished turn is
|
|
558
|
-
* a no-op for boundary creation.
|
|
559
|
-
*
|
|
567
|
+
* a no-op for boundary creation. An optional `outcome` is recorded on the end
|
|
568
|
+
* boundary, letting hosts distinguish completed, aborted, and failed turns.
|
|
569
|
+
* Public building block for hosts that know when a replayed exchange is
|
|
570
|
+
* complete.
|
|
560
571
|
*/
|
|
561
572
|
export function finishTurn(
|
|
562
573
|
state: TranscriptState,
|
|
563
574
|
turnId: number | null = state.currentTurnId,
|
|
575
|
+
outcome?: TranscriptTurnOutcome,
|
|
564
576
|
): void {
|
|
565
577
|
if (turnId === null) return;
|
|
566
|
-
const
|
|
567
|
-
(entry) =>
|
|
578
|
+
const endBoundary = state.entries.find(
|
|
579
|
+
(entry): entry is Extract<TranscriptEntry, { type: "turn-boundary" }> =>
|
|
568
580
|
entry.turnId === turnId &&
|
|
569
581
|
entry.type === "turn-boundary" &&
|
|
570
582
|
entry.phase === "end",
|
|
571
583
|
);
|
|
572
|
-
if (
|
|
573
|
-
|
|
584
|
+
if (endBoundary) {
|
|
585
|
+
if (outcome !== undefined) endBoundary.outcome = outcome;
|
|
586
|
+
} else {
|
|
587
|
+
appendEntry(state, {
|
|
588
|
+
type: "turn-boundary",
|
|
589
|
+
turnId,
|
|
590
|
+
phase: "end",
|
|
591
|
+
...(outcome === undefined ? {} : { outcome }),
|
|
592
|
+
});
|
|
593
|
+
}
|
|
574
594
|
for (const entry of state.entries) {
|
|
575
595
|
if (entry.turnId !== turnId) continue;
|
|
576
596
|
if (
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xzzpig/pi-subagents",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.15.1",
|
|
4
4
|
"description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
|
|
5
5
|
"author": "Nico Bailon",
|
|
6
6
|
"license": "MIT",
|
|
@@ -13,6 +13,8 @@
|
|
|
13
13
|
"./agents": "./src/api/agents.ts",
|
|
14
14
|
"./delegation": "./src/api/delegation.ts",
|
|
15
15
|
"./capability-ceiling": "./src/api/capability-ceiling.ts",
|
|
16
|
+
"./workflow-resources": "./src/api/workflow-resources.ts",
|
|
17
|
+
"./required-child-extensions": "./src/api/required-child-extensions.ts",
|
|
16
18
|
"./preflight": "./src/api/preflight.ts",
|
|
17
19
|
"./agent-management": "./src/api/agent-management.ts",
|
|
18
20
|
"./control-channel": "./src/api/control-channel.ts",
|
|
@@ -88,12 +90,13 @@
|
|
|
88
90
|
"acorn": "8.18.0",
|
|
89
91
|
"jiti": "2.7.0",
|
|
90
92
|
"typebox": "1.1.38",
|
|
93
|
+
"undici": "8.10.0",
|
|
91
94
|
"yaml": "2.8.3"
|
|
92
95
|
},
|
|
93
96
|
"devDependencies": {
|
|
94
|
-
"@earendil-works/pi-agent-core": "
|
|
95
|
-
"@earendil-works/pi-ai": "
|
|
96
|
-
"@earendil-works/pi-tui": "
|
|
97
|
+
"@earendil-works/pi-agent-core": "0.85.1",
|
|
98
|
+
"@earendil-works/pi-ai": "0.85.1",
|
|
99
|
+
"@earendil-works/pi-tui": "0.85.1",
|
|
97
100
|
"@oxlint/plugins": "1.80.0",
|
|
98
101
|
"@types/node": "24.13.3",
|
|
99
102
|
"oxlint": "1.80.0",
|
|
@@ -107,6 +110,8 @@
|
|
|
107
110
|
"@xzzpig/pi-components"
|
|
108
111
|
],
|
|
109
112
|
"scripts": {
|
|
113
|
+
"build:pkg": "node scripts/build-package.mjs",
|
|
114
|
+
"pack:pkg": "npm run build:pkg && npm pack ./dist-pkg",
|
|
110
115
|
"typecheck": "tsc --noEmit",
|
|
111
116
|
"test": "npm run test:unit",
|
|
112
117
|
"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",
|
|
@@ -28,7 +28,7 @@ Choose or adapt angles when the work calls for it:
|
|
|
28
28
|
|
|
29
29
|
Prefer three strong reviewers over many vague reviewers.
|
|
30
30
|
|
|
31
|
-
Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete
|
|
31
|
+
Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete and current within the named review target, and supported by source proof, a test or repro, or a contract contradiction. For a diff review, require that the issue is caused or made reachable by that diff. Label findings P0/P1/P2. P0 blocks merge. P1 should be fixed before release. P2 is report-only. End each review with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. If nothing qualifies, ask the reviewer to say exactly `No issues found.` The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
|
|
32
32
|
|
|
33
33
|
Do not default first-pass reviews to `blockers only`. That phrase is valid only for final pre-merge re-checks after P1/P2 findings are already inventoried, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred.
|
|
34
34
|
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { pathToFileURL } from "node:url";
|
|
2
|
+
|
|
3
|
+
let aliases = {};
|
|
4
|
+
let nativeRunner = false;
|
|
5
|
+
let compiledRunner = false;
|
|
6
|
+
let packageRootUrl;
|
|
7
|
+
const redirected = new Set([
|
|
8
|
+
"@earendil-works/pi-tui",
|
|
9
|
+
]);
|
|
10
|
+
|
|
11
|
+
export function initialize(data) {
|
|
12
|
+
aliases = data?.aliases ?? {};
|
|
13
|
+
nativeRunner = data?.nativeRunner === true;
|
|
14
|
+
compiledRunner = data?.compiledRunner === true;
|
|
15
|
+
packageRootUrl = data?.packageRootUrl;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export function resolve(specifier, context, nextResolve) {
|
|
19
|
+
const packageImport = typeof packageRootUrl === "string" && context.parentURL?.startsWith(packageRootUrl) === true;
|
|
20
|
+
if (nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier]) {
|
|
21
|
+
return nextResolve(pathToFileURL(aliases[specifier]).href, context);
|
|
22
|
+
}
|
|
23
|
+
return nextResolve(specifier, context);
|
|
24
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import * as nodeModule from "node:module";
|
|
2
|
+
import { pathToFileURL } from "node:url";
|
|
3
|
+
|
|
4
|
+
// Upstream-original preload: JITI_ALIAS is written by the runner launcher, so a malformed value must fail loudly.
|
|
5
|
+
// pi-lens-ignore: unchecked-throwing-call-js
|
|
6
|
+
const aliases = JSON.parse(process.env.JITI_ALIAS ?? "{}");
|
|
7
|
+
const nativeRunner = process.env.PI_ASYNC_NATIVE_RUNNER === "1";
|
|
8
|
+
const compiledRunner = process.env.PI_ASYNC_COMPILED_RUNNER === "1";
|
|
9
|
+
// Pi's jiti loader owns aliases for external extensions; these hooks only supply peers to our compiled package.
|
|
10
|
+
const packageRootUrl = new URL("./", import.meta.url).href;
|
|
11
|
+
const redirected = new Set([
|
|
12
|
+
"@earendil-works/pi-tui",
|
|
13
|
+
]);
|
|
14
|
+
|
|
15
|
+
// Upstream-original: Node version feature detection for registerHooks (Node 22.12+ vs register()).
|
|
16
|
+
// pi-lens-ignore: no-runtime-typeof
|
|
17
|
+
if (typeof nodeModule.registerHooks === "function") {
|
|
18
|
+
nodeModule.registerHooks({
|
|
19
|
+
resolve(specifier, context, nextResolve) {
|
|
20
|
+
const packageImport = context.parentURL?.startsWith(packageRootUrl) === true;
|
|
21
|
+
if ((nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier])) {
|
|
22
|
+
return nextResolve(pathToFileURL(aliases[specifier]).href, context);
|
|
23
|
+
}
|
|
24
|
+
try {
|
|
25
|
+
return nextResolve(specifier, context);
|
|
26
|
+
} catch (error) {
|
|
27
|
+
if (nativeRunner && specifier.endsWith(".js")) return nextResolve(`${specifier.slice(0, -3)}.ts`, context);
|
|
28
|
+
throw error;
|
|
29
|
+
}
|
|
30
|
+
},
|
|
31
|
+
});
|
|
32
|
+
} else {
|
|
33
|
+
nodeModule.register(new URL("./runner-peer-loader.mjs", import.meta.url), {
|
|
34
|
+
data: { aliases, nativeRunner, compiledRunner, packageRootUrl },
|
|
35
|
+
});
|
|
36
|
+
}
|
|
@@ -1,28 +1,25 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: pi-subagents
|
|
3
3
|
description: |
|
|
4
|
-
|
|
5
|
-
review, scripted
|
|
6
|
-
|
|
7
|
-
supply focused context, planning, review, or execution.
|
|
4
|
+
Technical guidance for operator-requested delegation to builtin or custom
|
|
5
|
+
subagents: bounded handoffs, parallel review, scripted workflows, async work,
|
|
6
|
+
forked context, isolation, and coordinated execution.
|
|
8
7
|
---
|
|
9
8
|
|
|
10
9
|
# Pi Subagents
|
|
11
10
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
- Direct parent edits during orchestrator mode should be intentional, small
|
|
25
|
-
interventions with a brief reason.
|
|
11
|
+
The parent works directly by default. Invoke subagents only when the operator
|
|
12
|
+
requested delegation in the current request or through applicable user/project
|
|
13
|
+
instructions. Task size, complexity, risk, tool-call count, recipe fit, or an
|
|
14
|
+
available specialist does not independently authorize delegation.
|
|
15
|
+
|
|
16
|
+
Once authorized, choose the smallest bounded shape that earns its token and
|
|
17
|
+
elapsed-time overhead through concrete evidence, independent review,
|
|
18
|
+
specialization, useful parallelism, or needed isolation. A single child is
|
|
19
|
+
valid; writer, challenge, and review stages must each earn their overhead rather
|
|
20
|
+
than becoming default ceremony. The parent keeps user intent, constraints,
|
|
21
|
+
routing, arbitration, decisions, final acceptance, and publication authority,
|
|
22
|
+
and may perform the work directly where it is the most efficient owner.
|
|
26
23
|
|
|
27
24
|
Children do not spawn subagents unless the parent explicitly delegated fanout
|
|
28
25
|
and their resolved `tools` allow `subagent`.
|
|
@@ -50,6 +47,18 @@ use ordinary `runs.run(...)` / `runs.all(...)`. See the [canonical staged-lane
|
|
|
50
47
|
example](../../docs/workflows.md#parallel-sequential-lanes). Keep assignments
|
|
51
48
|
bounded, but do not add stages or ceremony just to satisfy this skill.
|
|
52
49
|
|
|
50
|
+
When composing `runs.run(...)`, `runs.all(...)`, or `runs.lanes(...)`, always
|
|
51
|
+
supply a short verb + behavior display `label` derived from the task, unless
|
|
52
|
+
the user supplied an explicit label; preserve that label. Keep the stable
|
|
53
|
+
machine `key` independent (for example, `issue2011-writer` with
|
|
54
|
+
`label: "Fix workflow steering"`). For `runs.lanes`, put labels on stage
|
|
55
|
+
items, not lane objects. Use stage-appropriate labels for reviews and retained-child
|
|
56
|
+
follow-ups too (for example, `Review workflow steering`). Generate labels in
|
|
57
|
+
the orchestrator while composing the launch—no extra model call, runtime
|
|
58
|
+
generator, or schema change. Native direct `{ agent, task }` calls have no
|
|
59
|
+
top-level `label` parameter; do not invent one or wrap a tiny single task in
|
|
60
|
+
a workflow just to label it.
|
|
61
|
+
|
|
53
62
|
Use async/background by default. Set `async:false` only when the parent must
|
|
54
63
|
block. Final reviews, validation gates, oracle checks, and publication checks
|
|
55
64
|
stay async.
|
|
@@ -71,6 +80,8 @@ that runner explicitly supports the option.
|
|
|
71
80
|
|
|
72
81
|
## Read the reference for the branch
|
|
73
82
|
|
|
83
|
+
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.
|
|
84
|
+
|
|
74
85
|
| Branch | Read |
|
|
75
86
|
| --- | --- |
|
|
76
87
|
| Delegate or choose roles, prompts, models, or slash commands | `references/prompting-and-roles.md` |
|
|
@@ -80,9 +91,9 @@ that runner explicitly supports the option.
|
|
|
80
91
|
| List, create, edit, disable, eject, or expose agents/RPC | `references/management-authoring-rpc.md` |
|
|
81
92
|
| Check safety constraints, recipes, or error handling | `references/constraints-and-recipes.md` |
|
|
82
93
|
|
|
83
|
-
For complex
|
|
84
|
-
|
|
85
|
-
review.
|
|
94
|
+
For an authorized complex delegated workflow, read `prompting-and-roles.md` and
|
|
95
|
+
`execution-controls.md`, then load `review-and-validation.md` and
|
|
96
|
+
`constraints-and-recipes.md` before launch or review.
|
|
86
97
|
|
|
87
98
|
## Operating rules
|
|
88
99
|
|
|
@@ -91,7 +102,8 @@ review.
|
|
|
91
102
|
- Exact model names are deployment policy. Put them in user/project settings or profiles, not package guidance.
|
|
92
103
|
- Give every child a compact meta-prompt checklist: objective; repo/cwd/ref; authority/edit boundary; relevant files/contracts and constraints; success/acceptance criteria; validation; expected output/report; and stop/ask conditions. See `references/prompting-and-roles.md`.
|
|
93
104
|
- For mutation work, use an isolated lane/worktree when isolation, overlap, or concurrent juggling matters; keep one writer per cwd/worktree. See `references/multi-lane-orchestration.md` for lane mechanics.
|
|
94
|
-
- Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required.
|
|
105
|
+
- Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. Do not use `interactive_shell` as an implicit fallback for a failed `subagent` lane; see `references/execution-controls.md`.
|
|
106
|
+
- Treat subagent workflow, child launch, prompt runtime, extension load, and child tooling setup failures as lane infrastructure blockers. Stop, report the exact failure and run/worktree state, verify a clean worktree or capture a partial diff, and use only a clear same-protocol retry or an owner-approved execution-mode fallback.
|
|
95
107
|
- For cross-codebase work, record the repo, explicit `cwd`, authority boundary, and expected output before launch.
|
|
96
108
|
- Make parallel prompts distinct by source seam, evidence, and decision. Do not clone prompts with only item numbers swapped.
|
|
97
109
|
- Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
|
|
@@ -52,10 +52,11 @@ This reference keeps cross-cutting policy and failure handling. Load the matchin
|
|
|
52
52
|
| Independent lanes, repositories, worktrees, and handoffs | [`references/multi-lane-orchestration.md`](multi-lane-orchestration.md) |
|
|
53
53
|
| Agent management, file authoring, prompt integration, or RPC | [`references/management-authoring-rpc.md`](management-authoring-rpc.md) |
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
After delegation is operator-authorized, choose the smallest recipe that earns
|
|
56
|
+
its overhead. Recipes select a shape; they do not authorize delegation:
|
|
56
57
|
|
|
57
58
|
- **Recon → plan → implement:** run one focused `scout`, then one `worker` that consumes its findings.
|
|
58
|
-
- **
|
|
59
|
+
- **Implementation:** clarify scope and acceptance, record user-owned decisions and seam/validation contracts, and use a bounded scout, writer, or fresh reviewer only where the requested delegation benefits from that stage. Keep one writer, inspect direct evidence, and require every added stage to earn its overhead. Split large work into serial milestones instead of a writer swarm; do not stop at review without disposition.
|
|
59
60
|
- **Parallel analysis:** fan out only independent read/review/validation work, or isolate each writer in its own worktree. Never run concurrent writers in one checkout.
|
|
60
61
|
|
|
61
62
|
## Error Handling
|