@xzzpig/pi-subagents 0.16.0 → 0.19.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 +233 -1
- package/README.md +5 -3
- package/agents/claude-code-writer.md +1 -0
- package/agents/codex-exec-writer.md +1 -0
- package/agents/cursor-agent-writer.md +1 -0
- package/agents/reviewer.md +3 -2
- package/agents/worker.md +3 -2
- package/docs/agents.md +34 -21
- package/docs/configuration.md +82 -7
- package/docs/extension-api.md +75 -8
- package/docs/missions.md +13 -13
- package/docs/models.md +7 -5
- package/docs/observability.md +23 -13
- package/docs/standalone-background.md +5 -5
- package/docs/tool-reference.md +98 -100
- package/docs/watchdog.md +2 -0
- package/docs/workflows.md +214 -162
- package/inspector-runner.mjs +1 -1
- package/node_modules/@xzzpig/pi-components/package.json +4 -4
- package/package.json +15 -9
- package/prompts/council.md +6 -3
- package/prompts/review-loop.md +1 -1
- package/runner-peer-loader.mjs +4 -7
- package/runner-peer-preload.mjs +5 -7
- package/skills/council-mode/SKILL.md +1 -1
- package/skills/pi-subagents/SKILL.md +13 -5
- package/skills/pi-subagents/references/constraints-and-recipes.md +8 -5
- package/skills/pi-subagents/references/execution-controls.md +72 -69
- package/skills/pi-subagents/references/management-authoring-rpc.md +4 -4
- package/skills/pi-subagents/references/multi-lane-orchestration.md +9 -1
- package/skills/pi-subagents/references/prompting-and-roles.md +52 -54
- package/src/agents/advertised-agent-prompt.ts +21 -41
- package/src/agents/agent-eject.ts +3 -3
- package/src/agents/agent-management.ts +63 -54
- package/src/agents/agent-memory.ts +90 -3
- package/src/agents/agent-serializer.ts +4 -4
- package/src/agents/agents.ts +132 -51
- package/src/agents/global-npm-root.ts +58 -0
- package/src/agents/proactive-skills.ts +4 -1
- package/src/agents/runtime-agent-registry.ts +14 -11
- package/src/agents/skills.ts +42 -9
- package/src/api/delegation.ts +15 -0
- package/src/api/inspectors.ts +27 -0
- package/src/api/preflight.ts +7 -2
- package/src/extension/config.ts +12 -4
- package/src/extension/control-notices.ts +3 -0
- package/src/extension/doctor.ts +10 -4
- package/src/extension/fanout-child.ts +20 -3
- package/src/extension/herdr-pi-bridge.ts +2 -0
- package/src/extension/index.ts +168 -206
- package/src/extension/public-execution.ts +69 -35
- package/src/extension/reply-workflow-script.ts +58 -0
- package/src/extension/rpc.ts +39 -11
- package/src/extension/schemas.ts +47 -138
- package/src/extension/subagent-guide.ts +12 -4
- package/src/extension/tool-activation.ts +146 -0
- package/src/extension/tool-description.ts +62 -27
- package/src/extension/upgrade-notice.ts +40 -0
- package/src/inspectors/ghostty/plugin.ts +13 -1
- package/src/inspectors/plugins.ts +70 -3
- package/src/integrations/herdr-status.ts +19 -3
- package/src/intercom/intercom-bridge.ts +2 -0
- package/src/intercom/native-supervisor-channel.ts +26 -16
- package/src/intercom/result-intercom.ts +4 -0
- package/src/runs/background/active-async-capacity.ts +3 -25
- package/src/runs/background/async-execution.ts +60 -95
- package/src/runs/background/async-job-tracker.ts +91 -56
- package/src/runs/background/async-resume.ts +16 -8
- package/src/runs/background/async-retention.ts +46 -16
- package/src/runs/background/async-status.ts +2 -0
- package/src/runs/background/await-async-run.ts +76 -0
- package/src/runs/background/binary-bootstrap.ts +34 -6
- package/src/runs/background/chain-root-attachment.ts +4 -4
- package/src/runs/background/control-channel.ts +18 -2
- package/src/runs/background/fleet-view.ts +51 -7
- package/src/runs/background/notify.ts +98 -7
- package/src/runs/background/pid-namespace.ts +18 -0
- package/src/runs/background/process-terminal-candidate.ts +98 -0
- package/src/runs/background/process-terminal.ts +17 -96
- package/src/runs/background/result-watcher.ts +1 -1
- package/src/runs/background/retained-children.ts +3 -2
- package/src/runs/background/run-child-session.ts +20 -6
- package/src/runs/background/run-id-resolver.ts +10 -5
- package/src/runs/background/run-status.ts +16 -4
- package/src/runs/background/runner-aliases.ts +54 -16
- package/src/runs/background/runner-child-launch.ts +4 -2
- package/src/runs/background/runner-startup-failure.ts +56 -0
- package/src/runs/background/scheduled-runs.ts +5 -5
- package/src/runs/background/stale-run-reconciler.ts +19 -3
- package/src/runs/background/subagent-runner-bootstrap.ts +276 -0
- package/src/runs/background/subagent-runner.ts +111 -288
- package/src/runs/background/wait-tool.ts +2 -0
- package/src/runs/background/workflow-terminal-proof.ts +68 -0
- package/src/runs/foreground/async-stop-action.ts +17 -3
- package/src/runs/foreground/execution.ts +111 -139
- package/src/runs/foreground/prompt-audit.ts +3 -9
- package/src/runs/foreground/subagent-executor.ts +715 -258
- package/src/runs/shared/acceptance.ts +167 -68
- package/src/runs/shared/async-status-projection.ts +5 -0
- package/src/runs/shared/capability-ceiling.ts +4 -1
- package/src/runs/shared/child-hooks.ts +1 -16
- package/src/runs/shared/child-launch.ts +37 -16
- package/src/runs/shared/child-runtime-config.ts +3 -0
- package/src/runs/shared/child-session.ts +144 -8
- package/src/runs/shared/child-tool-plan.ts +38 -116
- package/src/runs/shared/dynamic-fanout.ts +1 -1
- package/src/runs/shared/external-cli-runner.ts +3 -1
- package/src/runs/shared/external-job-bridge.ts +54 -0
- package/src/runs/shared/git-environment.ts +29 -0
- package/src/runs/shared/mcp-config-sources.ts +5 -1
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +104 -12
- package/src/runs/shared/mcp-direct-tool-grant.ts +22 -6
- package/src/runs/shared/model-resolution.ts +35 -10
- package/src/runs/shared/model-scope.ts +28 -9
- package/src/runs/shared/nested-events.ts +12 -0
- package/src/runs/shared/orca-progress-tabs.ts +3 -2
- package/src/runs/shared/parallel-utils.ts +4 -1
- package/src/runs/shared/pi-spawn.ts +1 -3
- package/src/runs/shared/single-output.ts +11 -2
- package/src/runs/shared/structured-output.ts +227 -7
- package/src/runs/shared/subagent-control.ts +2 -16
- package/src/runs/shared/subagent-prompt-runtime.ts +29 -5
- package/src/runs/shared/tool-availability.ts +2 -2
- package/src/runs/shared/tool-budget.ts +21 -0
- package/src/runs/shared/usage-reconciliation.ts +73 -0
- package/src/runs/shared/worktree.ts +36 -9
- package/src/shared/child-session-name.ts +4 -2
- package/src/shared/disabled-features.ts +123 -0
- package/src/shared/extension-context.ts +13 -0
- package/src/shared/fork-context.ts +11 -4
- package/src/shared/launch-contract.ts +1 -1
- package/src/shared/model-info.ts +9 -0
- package/src/shared/pruned-fork.ts +69 -56
- package/src/shared/settings.ts +1 -1
- package/src/shared/types.ts +73 -16
- package/src/slash/delegation-adapters.ts +25 -1
- package/src/slash/prompt-template-bridge.ts +18 -3
- package/src/slash/prompt-workflows.ts +12 -1
- package/src/slash/slash-commands.ts +17 -246
- package/src/slash/subagent-cost.ts +313 -0
- package/src/slash/subagents-admin.ts +4 -5
- package/src/tui/fleet-status.ts +38 -8
- package/src/tui/fleet.ts +21 -6
- package/src/tui/render.ts +166 -71
- package/src/tui/running-tone.ts +28 -0
- package/src/watchdog/diff-tool.ts +47 -12
- package/src/watchdog/permission-arbiter.ts +13 -15
- package/src/watchdog/register-child.ts +13 -5
- package/src/watchdog/register-main.ts +3 -3
- package/src/watchdog/review.ts +16 -16
- package/src/watchdog/runtime.ts +2 -1
- package/src/watchdog/turn-delta.ts +12 -6
- package/src/workflows/chat-progress.ts +2 -2
- package/src/workflows/scripted-workflow.ts +225 -59
- package/src/workflows/structured-workflow-scripts.ts +177 -0
- package/src/workflows/workflow-checklist.ts +6 -0
- package/src/workflows/workflow-child-summary.ts +4 -2
- package/src/workflows/workflow-receipt.ts +8 -2
- package/src/workflows/workflow-resources.ts +37 -12
- package/src/workflows/workflow-reuse.ts +120 -0
- package/src/workflows/workflow-revival.ts +123 -0
- package/src/workflows/workflow-settlement.ts +4 -1
- package/src/runs/shared/completion-evidence.ts +0 -89
- package/src/runs/shared/completion-guard.ts +0 -255
- package/src/runs/shared/llm-intent-arbiter.ts +0 -321
- package/src/runs/shared/task-intent.ts +0 -244
package/docs/agents.md
CHANGED
|
@@ -58,6 +58,10 @@ If you disabled the old bundled `gpt-pro` workaround with `agentOverrides.gpt-pr
|
|
|
58
58
|
|
|
59
59
|
The Pi async run remains the source of truth for status, artifacts, wake/wait, mission attachment, retention, and diagnostics.
|
|
60
60
|
|
|
61
|
+
### Command-runner agents as typed steps
|
|
62
|
+
|
|
63
|
+
`runner.type: external-cli` with a plain `command` (no `adapter`) runs any local executable as a subagent: the assembled prompt is written to stdin, stdout becomes the child's output, and the run gets the usual run id, status, mission entry, and workflow key. This is how a classifier, a scoring script, or a small evaluation model becomes a `runs.run` step. Such agents are async-only (workflows launch children async by default; a direct `async: false` call is refused), receive no forked transcript, and cannot produce `structuredOutput` themselves; parse their `output` in the workflow, or pair them with a [typed gate](tool-reference.md#typed-gates). Generic commands are local-only; saved-machine placement accepts only the code-owned adapters below.
|
|
64
|
+
|
|
61
65
|
### Advisory runner data boundary
|
|
62
66
|
|
|
63
67
|
External CLI agents use their own runner contract. They are deliberate execution modes, not implicit recovery paths for a failed native `subagent` workflow. For backlog lanes and other subagent-governed workflows, switching to an external, foreground, or CLI runner requires explicit owner approval after the exact failure/run/worktree state is recorded and the worktree is verified clean or its partial diff is captured. Do not pass native Pi child options such as model override, structured output, acceptance/agent contract, tool budgets, fast mode, fork context, skills, or native Pi tools unless the adapter explicitly implements them.
|
|
@@ -216,7 +220,7 @@ You can override selected agent fields without copying the whole agent. Override
|
|
|
216
220
|
}
|
|
217
221
|
```
|
|
218
222
|
|
|
219
|
-
Supported override fields: `description`, `machine`, `output`, `outputMode`, `defaultReads`, `model`, `defaultProvider`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritGlobalContext`, `inheritSkills`, `defaultContext`, `acceptanceRole`, `disabled`, `skills`, `tools`, `sandbox`, and `systemPrompt`.
|
|
223
|
+
Supported override fields: `description`, `advertise`, `machine`, `output`, `outputMode`, `defaultReads`, `model`, `defaultProvider`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritGlobalContext`, `inheritSkills`, `defaultContext`, `acceptanceRole`, `disabled`, `skills`, `tools`, `sandbox`, and `systemPrompt`.
|
|
220
224
|
|
|
221
225
|
- `description` replaces the discovered description for builtin and custom agents, which lets list output show deployment-specific routing or model metadata.
|
|
222
226
|
- Use `output: false`, `defaultReads: false`, `defaultContext: false`, `acceptanceRole: false`, or `machine: false` to clear an inherited value.
|
|
@@ -232,6 +236,8 @@ Disable and restore:
|
|
|
232
236
|
- `subagent({ action: "eject", agent: "reviewer" })` copies a bundled builtin or package agent into the user or project agent dir (default `user`) as an editable custom file that shadows the original. Relative resource paths are normalized to stable paths; ejection validates copied skills and launch tool configuration, and removes only the new file when that validation fails.
|
|
233
237
|
- `subagent({ action: "reset", agent: "reviewer" })` deletes the scope's custom agent file and/or settings override entry, restoring the bundled default. It refuses if no bundled default exists (use `delete` for purely custom agents).
|
|
234
238
|
|
|
239
|
+
A custom agent file that shadows a bundled agent replaces the bundled definition wholesale; it does not inherit omitted frontmatter, including `acceptanceRole`. Custom implementation profiles must declare `acceptanceRole: writer` explicitly when writer acceptance inference is intended. Without it, automatic acceptance uses lightweight attestation as described in the [frontmatter reference](#frontmatter-reference).
|
|
240
|
+
|
|
235
241
|
`eject`, `disable`, `enable`, and `reset` accept `agentScope: "user" | "project"` and operate in one scope at a time. Project overrides still win over user ones, so a project-scope disable survives a user-scope `enable` until you target the project scope.
|
|
236
242
|
|
|
237
243
|
## Running external CLI agents on a Herdr saved machine
|
|
@@ -259,12 +265,14 @@ pi-subagents never clones, pulls, or checks out on the machine. Generic `externa
|
|
|
259
265
|
|
|
260
266
|
## Parent prompt discovery
|
|
261
267
|
|
|
262
|
-
Set `advertise: true` in a specialist's agent file frontmatter for parent-prompt discovery. When the `subagent` tool is active, pi-subagents adds an agent-owned catalog of names and descriptions to the parent system prompt. Disabled agents and agents excluded by the current capability ceiling are omitted. Advertisement is not supported through
|
|
268
|
+
Set `advertise: true` in a specialist's agent file frontmatter for parent-prompt discovery, or in `subagents.agentOverrides.<name>.advertise` when the definition must stay untouched. When the `subagent` tool is active, pi-subagents adds an agent-owned catalog of names and descriptions to the parent system prompt. Disabled agents and agents excluded by the current capability ceiling are omitted. Advertisement is not supported through runtime registration.
|
|
263
269
|
|
|
264
270
|
Advertisement is opt-in discovery, not automatic routing. The catalog is sorted by name and limited to 16 agents and 12,288 total rendered UTF-8 bytes, including XML escaping, instructions, and omission counts. Descriptions are capped at 512 UTF-8 bytes before escaping. Entries that cannot fit are omitted; canonical agent names are never truncated. The parent still calls `subagent({ action: "list", capabilities: true })` before execution to confirm that the selected agent is executable (including `runner.available === true` for external CLI agents).
|
|
265
271
|
|
|
266
272
|
The file catalog snapshot refreshes at session start/reload and after extension-owned agent-management mutations. External file or settings edits require `/reload`; ordinary turns do not poll the filesystem. Tool availability and capability-ceiling filtering are checked in memory on every prompt. A failed management-triggered refresh withdraws the catalog until a successful refresh, without changing the persisted mutation's result.
|
|
267
273
|
|
|
274
|
+
The catalog is sent as Pi's `advertised_subagents` prompt section. When it changes mid-session, Pi appends it as a small system message instead of changing the system prompt, so the provider prompt cache is kept. This only works if no other loaded extension returns a replacement `systemPrompt` from `before_agent_start`; in that case Pi folds section changes back into the system prompt and the cache is lost for that request.
|
|
275
|
+
|
|
268
276
|
## Prompt assembly
|
|
269
277
|
|
|
270
278
|
Subagents are narrow by default. Custom agents start with a clean system prompt and only the context you intentionally give them. They do not automatically inherit Pi's whole base prompt, project instruction files, or discovered skills catalog.
|
|
@@ -315,17 +323,17 @@ timeoutMs: 900000
|
|
|
315
323
|
toolTimeoutMs: 600000
|
|
316
324
|
acceptance: {"level":"none","reason":"lightweight lookup"}
|
|
317
325
|
acceptanceRole: read-only
|
|
318
|
-
completionGuard: false
|
|
319
326
|
interactive: true
|
|
320
327
|
maxSubagentDepth: 1
|
|
321
328
|
allowNestedSubagents: true
|
|
329
|
+
allowedAgents: scout, reviewer
|
|
322
330
|
injectToContext: true
|
|
323
331
|
---
|
|
324
332
|
|
|
325
333
|
Your system prompt goes here.
|
|
326
334
|
```
|
|
327
335
|
|
|
328
|
-
Simple-scalar list fields accept either a comma-separated form or a newline block list with one `- item` per line. This applies to `tools`, `excludeTools`, `defaultReads`, `skill`/`skills`, `skillPath`, `extensions`, and `subagentOnlyExtensions`:
|
|
336
|
+
Simple-scalar list fields accept either a comma-separated form or a newline block list with one `- item` per line. This applies to `tools`, `excludeTools`, `allowedAgents`, `defaultReads`, `skill`/`skills`, `skillPath`, `extensions`, and `subagentOnlyExtensions`:
|
|
329
337
|
|
|
330
338
|
```yaml
|
|
331
339
|
tools:
|
|
@@ -340,9 +348,10 @@ Field notes:
|
|
|
340
348
|
| `package` | Optional package identifier. A file with `name: scout` and `package: code-analysis` registers as `code-analysis.scout`; serialization keeps `name` and `package` separate. |
|
|
341
349
|
| `advertise` | Set `true` to include this agent's name and description in the parent system prompt when the `subagent` tool is active. Defaults to `false`. |
|
|
342
350
|
| `aliases` | Optional comma-separated or block-list names that resolve to this agent for selection and explicit `agent` and task inputs. Runtime status, persistence, and config still use the canonical `name`. Exact canonical names take precedence over aliases, and alias collisions between distinct canonical agents fail as ambiguous. |
|
|
343
|
-
| `tools` | Strict child tool allowlist. Named extension tools must also have their provider loaded. `mcp:` entries select direct MCP tools
|
|
351
|
+
| `tools` | Strict child tool allowlist. Named extension tools must also have their provider loaded. `mcp:` entries select direct MCP tools from `pi-mcp-adapter` when it is installed, and from Pi's built-in MCP otherwise. |
|
|
344
352
|
| `excludeTools` | Optional child tool deny-list applied after normal tool resolution. With an explicit `tools` allowlist, matching names are removed; when `tools` is omitted, the names are excluded from the child session's default tool set. Unknown names are ignored by Pi without making the agent definition invalid. |
|
|
345
353
|
| `allowNestedSubagents` | Set `true` to authorize the child-safe nested `subagent` runtime without making omitted `tools` an allowlist. Inherited depth and capability ceilings remain authoritative. |
|
|
354
|
+
| `allowedAgents` | Restricts which canonical, case-sensitive agent names this agent may launch. Omitted adds no restriction; an empty list denies every descendant launch. This only narrows an existing nesting grant: `tools: subagent` or `allowNestedSubagents: true` is still required. Inherited/runtime allowlists are intersected and cannot be widened. |
|
|
346
355
|
| `extensions` | Omitted means a background child loads the parent's ambient extensions; empty means no ambient extensions; list values load exactly those extensions. Foreground children never load ambient extensions, so for them only listed values apply. |
|
|
347
356
|
| `subagentOnlyExtensions` | Extension paths loaded only in this agent's child sessions. Tools registered there are unavailable to the main agent unless also installed through normal Pi extension configuration. |
|
|
348
357
|
| `sandbox` | Optional named `pi-sandbox` profile for a native Pi child. It must be a non-empty safe name defined in the global `<agentDir>/sandbox.json` or, when the project is trusted, in `<cwd>/.pi/sandbox.json`; it is a selector only, never an inline network or filesystem policy. |
|
|
@@ -352,7 +361,7 @@ Field notes:
|
|
|
352
361
|
| `systemPromptMode` | `replace` by default; `append` keeps Pi's base prompt. |
|
|
353
362
|
| `inheritProjectContext` | Keeps or strips inherited repository instruction blocks. |
|
|
354
363
|
| `inheritGlobalContext` | Keeps or strips the operator's global context file from the Pi config agent directory (e.g. `~/.pi/agent/AGENTS.md`). It has an effect only when `inheritProjectContext` is `true`; otherwise all context files are already disabled. Defaults to `false`. |
|
|
355
|
-
| `inheritSkills` | Keeps or strips Pi's discovered skills catalog. |
|
|
364
|
+
| `inheritSkills` | Keeps or strips Pi's discovered skills catalog. For in-process children this includes skills that loaded extensions add; herdr-placed children rely on Pi's `--no-skills`. |
|
|
356
365
|
| `defaultContext` | Optional `fresh` or `fork` launch-context preference. An implicit `fork` falls back to `fresh` when the parent has no persisted session file or current leaf; an explicit launch `context: "fork"` remains strict. |
|
|
357
366
|
| `skills` | Selects specific skills for the child, regardless of `inheritSkills`. |
|
|
358
367
|
| `skillPath` | Invocation-private skill files or discovery directories. Relative paths resolve from the agent definition file. Local matches take precedence, while unresolved or unreadable matches fall back to normal skill discovery. This field discovers candidates only; `skills` still selects what the child receives. |
|
|
@@ -363,9 +372,8 @@ Field notes:
|
|
|
363
372
|
| `timeoutMs` | Positive integer default runtime deadline in milliseconds for single-agent launches. Foreground launches use 30 minutes when neither the call nor agent provides a timeout; explicit `timeoutMs`/`maxRuntimeMs` and agent defaults win. |
|
|
364
373
|
| `toolTimeoutMs` | Optional positive integer hard per-tool-call deadline in milliseconds. An explicit call value wins, then this agent default, global `toolTimeoutMs`, and `PI_SUBAGENT_TOOL_TIMEOUT_MS`. When omitted, known-fast built-in tools get a five-minute default; long-running tools get attention notices but no hard default. It does not extend the run-level deadline; `contact_supervisor`, `intercom`, and `bg_wait` are exempt. |
|
|
365
374
|
| `acceptance` | Acceptance default for single-agent launches. Use a scalar level such as `checked` or an inline/block YAML map such as `{ level: "none", reason: "lightweight lookup" }`. Explicit call values win; chain and parallel acceptance remains task/step configuration. |
|
|
366
|
-
| `acceptanceRole` | Optional `read-only` or `writer` role for automatic acceptance inference.
|
|
367
|
-
| `mutationTools` | Comma-separated extension tool names
|
|
368
|
-
| `completionGuard` | Set `false` only for non-implementation agents that may mention implementation words while using mutation-capable tools such as `bash`. |
|
|
375
|
+
| `acceptanceRole` | Optional `read-only` or `writer` role for automatic acceptance inference. When omitted, automatic acceptance uses lightweight attestation; task wording and agent names do not escalate it. This does not grant or revoke tools. |
|
|
376
|
+
| `mutationTools` | Comma-separated extension tool names treated as mutating activity for runtime diagnostics, long-running-tool status, and timeout recovery. This is diagnostic only and never determines successful completion. List and load each tool through `tools` and its extension provider as usual. |
|
|
369
377
|
| `interactive` | Parsed for compatibility but not currently enforced. |
|
|
370
378
|
| `maxSubagentDepth` | Tightens nested delegation for this agent's children. |
|
|
371
379
|
| `injectToContext` | Advertise this agent in the parent system prompt at session start so the main agent can select it without calling `{ action: "list" }` first. See [Context injection](fork-extensions.md#context-injection). |
|
|
@@ -377,7 +385,7 @@ Hosts can import `registerRequiredChildExtensions` from `pi-subagents/required-c
|
|
|
377
385
|
|
|
378
386
|
Required paths follow ordinary extension resolution and survive agent defaults and `extensions: []` across native foreground, detached, nested, and recovery launches. A `capabilityCeiling.denyExtensions` conflict or required load/provider-registration failure rejects before model resolution. External runners are excluded, and status/watch paths do not query the registry.
|
|
379
387
|
|
|
380
|
-
|
|
388
|
+
Successful completion is determined by observable gates such as process outcome, required outputs, explicit acceptance, verification commands, independent review, and staged-index integrity. Best-effort mutation observations remain diagnostic: unchanged or unknown evidence does not fail a run, and observed changes do not prove correctness.
|
|
381
389
|
|
|
382
390
|
## Per-agent persistent memory
|
|
383
391
|
|
|
@@ -394,6 +402,7 @@ This is independent of Pi's own parent/session/project memory system and writes
|
|
|
394
402
|
How it works:
|
|
395
403
|
|
|
396
404
|
- On each run, the first 200 lines of `MEMORY.md` in the resolved memory directory are injected into the child system prompt, so the agent can recall accumulated role notes such as threat-model entries, release gotchas, or verified commands.
|
|
405
|
+
- Project memory resolves to the main checkout from standard linked Git worktrees whose metadata lives under `<main>/.git/worktrees/`, so isolated children share one durable role memory and worktree cleanup does not remove it. Custom `--separate-git-dir` layouts keep their current project-root behavior because Git does not retain a safely verifiable main-checkout path there.
|
|
397
406
|
- Agents with write tools (`edit`, `write`, or `bash`, or no `tools` allowlist at all) are told they may append concise dated entries to the file.
|
|
398
407
|
- Agents without write tools receive a read-only memory block and are not instructed to edit it. A read-only reviewer can recall prior notes without gaining write capability.
|
|
399
408
|
- The memory directory is never created eagerly. The agent's own `write` tool creates it (and `MEMORY.md`) on the first persist.
|
|
@@ -435,20 +444,20 @@ How `tools` behaves:
|
|
|
435
444
|
- `tools` present: regular tool names become an explicit allowlist.
|
|
436
445
|
- `tools:` empty: the child session gets no tools.
|
|
437
446
|
- `allowNestedSubagents: true`: explicitly enables child-safe nested fanout without turning omitted `tools` into an allowlist. Depth and inherited capability ceilings still apply.
|
|
447
|
+
- `allowedAgents: scout, reviewer`: if nesting is separately enabled, restricts this agent's descendant launches to those names. `allowedAgents:` denies all descendants and omission is unrestricted except for inherited/runtime policy.
|
|
438
448
|
|
|
439
449
|
`excludeTools` is applied after this resolution. It can narrow an explicit `tools` allowlist or, when `tools` is omitted, remove names from Pi's default builtin tool set. Runtime-injected tools are excluded only when their exact names are listed. An empty `excludeTools` list has no effect.
|
|
440
450
|
|
|
441
|
-
An allowlisted name does not load the extension that registers it. Load that provider through `extensions`, `subagentOnlyExtensions`, a path-like `tools` entry, or (background children only) normal Pi extension discovery.
|
|
451
|
+
An allowlisted name does not load the extension that registers it. Load that provider through `extensions`, `subagentOnlyExtensions`, a path-like `tools` entry, or (background children only) normal Pi extension discovery. Pi's built-in `codemode` is the exception: native children register the host SDK's official factory when codemode is permitted, without enabling it in the main session. On older Pi hosts without that factory, a child that requests codemode still reports it as unavailable; a capability ceiling that denies extensions prevents its registration.
|
|
442
452
|
|
|
443
|
-
Ambient extensions depend on where the child runs. Local foreground children are sessions inside the parent Pi process and never load the parent's ambient extensions; otherwise the parent would start a second copy of each ambient extension, including this one. Background children are sessions inside the detached runner process and load the ambient extensions unless the agent sets `extensions` or the capability ceiling denies extensions. Local foreground children do inherit the providers the parent's extensions registered (`pi.registerProvider`), so their models resolve without loading those extensions again. Pane-native remote foreground children instead use the remote machine's provider discovery and configuration. Agents that need MCP tools
|
|
453
|
+
Ambient extensions depend on where the child runs. Local foreground children are sessions inside the parent Pi process and never load the parent's ambient extensions; otherwise the parent would start a second copy of each ambient extension, including this one. Background children are sessions inside the detached runner process and load the ambient extensions unless the agent sets `extensions` or the capability ceiling denies extensions. Local foreground children do inherit the providers the parent's extensions registered (`pi.registerProvider`), so their models resolve without loading those extensions again. Pane-native remote foreground children instead use the remote machine's provider discovery and configuration. Agents that need MCP tools from an ambient adapter such as pi-mcp-adapter (including `mcp:` entries the adapter resolves) must therefore run as background children (`async: true`). A foreground launch of such an agent fails with a diagnostic that says exactly that.
|
|
444
454
|
|
|
445
455
|
More rules:
|
|
446
456
|
|
|
447
457
|
- `mcp:` entries are split out and forwarded as direct MCP selections without granting normal builtins unless those builtins are also listed.
|
|
448
458
|
- Path-like `tools` entries, such as extension paths or `.ts`/`.js` files, are treated as tool-extension paths rather than tool names.
|
|
449
459
|
- Internal runtime tools such as `structured_output` are added to an explicit allowlist only when their contract is active.
|
|
450
|
-
- Unknown extension tool calls
|
|
451
|
-
- Agents that declare only known read-only builtin tools skip the implementation completion guard. `bash`, unknown tools, and MCP tools stay mutation-capable. Use `completionGuard: false` for bash-enabled validators or advisors that should never be judged as implementation agents.
|
|
460
|
+
- Unknown extension tool calls are treated as mutating diagnostic activity only when their names are listed in `mutationTools`.
|
|
452
461
|
|
|
453
462
|
Examples:
|
|
454
463
|
|
|
@@ -459,7 +468,9 @@ Examples:
|
|
|
459
468
|
- `allowNestedSubagents: true` with `tools` omitted: normal builtin tools (and, for background children, ambient extensions) remain inherited, and the child-safe nested `subagent` runtime is added.
|
|
460
469
|
- `tools: read, fixture_search` plus `subagentOnlyExtensions: ./tools/fixture-search.ts`: the provider loads only in this agent's child sessions, and the registered `fixture_search` name survives the strict allowlist.
|
|
461
470
|
|
|
462
|
-
|
|
471
|
+
When [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) is not installed and Pi has built-in MCP (Pi 0.99 or later), `mcp:server` and `mcp:server/tool` entries resolve against Pi's built-in MCP. The child connects the servers in Pi's `mcp.json` (the project's `.pi/mcp.json` only when the parent trusts the project) and gets only the selected tools, as direct tools, whatever exposure the server is configured with; tools configured as `hidden` cannot be selected. Servers that an extension adds with `pi.registerMcpServer()` work in background children, because the registering extension loads there too. They do not work in foreground children, which load no ambient extensions, so a foreground launch that selects one fails and says to use `async: true`. The launch fails if a selected tool does not register in the child within 10 seconds.
|
|
472
|
+
|
|
473
|
+
When pi-mcp-adapter is installed, it keeps priority and provides the direct MCP tools. Subagents only receive direct MCP tools when `mcp:` entries are listed in their frontmatter; global `directTools: true` in the adapter's MCP config is not enough by itself. The generic `mcp` proxy tool can still be used for discovery when available. The adapter caches tool metadata at startup, so after connecting a new MCP server for the first time, restart Pi before relying on direct tools. Server `includeTools` and `excludeTools` policies are enforced while resolving cached metadata for children: both accept exact names and `*`/`?` glob patterns against raw, generated-resource, and server/short/mcp/none-prefixed names, with `excludeTools` taking precedence. `mcp:` entries must name servers from the adapter's configuration files. A server that exists only in the adapter's runtime snapshot (registered at runtime, not persisted) cannot be provided to a child: children are pi sessions inside the parent or the runner process, not `pi` processes that could receive an MCP config argument, so such a launch fails with an error saying that MCP tools must come from an ambient adapter extension in a background child. An `mcp:` entry named `subagent` does not authorize nested fanout; declare the builtin `subagent` tool or set `allowNestedSubagents: true`. If a resolved direct MCP name is missing from the child registry, pi-subagents keeps the launch failed under the strict allowlist and reports the registration mismatch; check the resolved names against what the host or pi-mcp-adapter actually registers before child startup.
|
|
463
474
|
|
|
464
475
|
`extensions` controls child extension loading:
|
|
465
476
|
|
|
@@ -477,7 +488,7 @@ When `extensions` is present, normal discovered extensions are disabled. The lis
|
|
|
477
488
|
|
|
478
489
|
Use `subagentOnlyExtensions` when a custom extension tool should exist only inside child sessions. It is scoped by agent config: every run of that agent receives those extension paths, while other agents do not unless they declare the same field. The current model does not have a separate named-subagent audience inside one agent definition.
|
|
479
490
|
|
|
480
|
-
To apply
|
|
491
|
+
To apply a shared extension policy to every agent that does not declare its own, set `subagents.defaultExtensions` for an ambient-disabling allowlist or `subagents.defaultSubagentOnlyExtensions` for child-only paths that preserve ambient discovery (see [configuration.md](configuration.md)).
|
|
481
492
|
|
|
482
493
|
Before the first model turn, the child runtime compares every explicit tool name with Pi's final filtered registry. A missing provider fails the run with the unavailable names and concrete `subagentOnlyExtensions`/`extensions` guidance, instead of letting a direct or chained child silently continue without its requested tools.
|
|
483
494
|
|
|
@@ -495,12 +506,14 @@ Discovery uses project-first precedence:
|
|
|
495
506
|
6. User packages and user settings packages via `package.json -> pi.skills`
|
|
496
507
|
7. `~/.pi/agent/settings.json -> skills`
|
|
497
508
|
|
|
498
|
-
Use agent defaults, override them at runtime, or disable them:
|
|
509
|
+
Use agent defaults, override them at runtime, or disable them inside the ```` ```js workflow ```` block:
|
|
499
510
|
|
|
500
|
-
```
|
|
501
|
-
|
|
502
|
-
{
|
|
503
|
-
{
|
|
511
|
+
```js
|
|
512
|
+
return runs.all([
|
|
513
|
+
{ key: "default", agent: "scout", task: "..." },
|
|
514
|
+
{ key: "override", agent: "scout", task: "...", skill: "tmux, safe-bash" },
|
|
515
|
+
{ key: "disabled", agent: "scout", task: "...", skill: false },
|
|
516
|
+
])
|
|
504
517
|
```
|
|
505
518
|
|
|
506
519
|
For chains, `skill` at the top level is additive. A step-level `skill` overrides that step; `false` disables skills for that step.
|
package/docs/configuration.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
`pi-subagents` reads optional JSON config from `~/.pi/agent/extensions/subagent/config.json`. This page lists every key, plus the environment variables and the settings-file keys that affect config resolution.
|
|
4
4
|
|
|
5
|
-
Settings-level keys (`subagents.defaultModel`, `defaultProvider`, `defaultThinking`, `defaultExtensions`, `agentOverrides`, `machines`, `agentScanDirs`, `agentExcludeDirs`, `modelScope`, `disableThinking`, `disableBuiltins`, `injectAgents`, watchdog settings) live in Pi settings files, not this config file. `modelScope.agents.<name>` adds per-agent restrictions,
|
|
5
|
+
Settings-level keys (`subagents.defaultModel`, `defaultProvider`, `defaultThinking`, `defaultExtensions`, `defaultSubagentOnlyExtensions`, `agentOverrides`, `machines`, `agentScanDirs`, `agentExcludeDirs`, `modelScope`, `disableThinking`, `disableBuiltins`, `injectAgents`, watchdog settings) live in Pi settings files, not this config file. `modelScope.agents.<name>` adds per-agent restrictions, `allow: ["inherit"]` permits the current parent model, and `allow: ["scoped"]` permits the parent session's scoped models (the parent model when the session is unscoped). See [models.md](models.md), [agents.md](agents.md), and [watchdog.md](watchdog.md).
|
|
6
6
|
|
|
7
7
|
## Project root resolution (settings)
|
|
8
8
|
|
|
@@ -76,6 +76,28 @@ For a native Pi `model_verification_failed` where your proxy accepts `claude-hai
|
|
|
76
76
|
|
|
77
77
|
Replace `YOUR_PROVIDER` with the resolved Pi provider ID. Keep the outgoing model alias unchanged. This native remedy already exists in v0.65.1; it does not infer equivalence from provider prefixes or dates. The built-in external `claude-code` adapter does not invoke this verifier or use this setting. If an external run shows this diagnostic, identify the installed version, resolved runner kind/adapter, and error location before applying a native remedy. Thanks to [sixtus](https://github.com/sixtus) for the concrete request-ID/response-ID example in [#1922](https://github.com/nicobailon/pi-subagents/issues/1922).
|
|
78
78
|
|
|
79
|
+
## Tool activation lifecycle
|
|
80
|
+
|
|
81
|
+
On Pi 0.86.1 or newer, when the model can take a new tool mid-conversation (see [`toolActivation`](#toolactivation)), a fresh unrestricted parent starts with `subagents_enable`, `bg_wait`, and `subagent_supervisor` active while `subagent` stays registered but inactive. Calling `subagents_enable({})` preserves unrelated active tools and exposes `subagent` on the next model request. It does not launch a child or infer authority from prompt keywords. With other models, a fresh parent starts with `subagent`, `bg_wait`, and `subagent_supervisor` active and no `subagents_enable`.
|
|
82
|
+
|
|
83
|
+
The recorded native `subagent` selection is restored on resume, reload, and tree navigation, so an activated session stays activated and a cold session stays cold. With the default `toolActivation`, the recorded `subagents_enable` selection is restored too, so a session that started without the loader never gets it later. Older history without tool-selection records keeps eager `subagent` availability. If Pi's allowlist or exclusions remove the loader, the extension does not hide `subagent`; if they remove `subagent`, the loader reports it unavailable. Hosts whose extension API lacks `getAllTools`, `getActiveTools`, or `setActiveTools` keep eager behavior and log one compatibility warning. The host version is not read from disk, so in-process hosts such as pi-web activate the same way as the Pi CLI.
|
|
84
|
+
|
|
85
|
+
Some providers fix the tool list for a whole prompt, for example bridges that hand Pi's tools to another agent SDK. There `subagent` appears only on the next user prompt, not the next model request. Start Pi with `--exclude-tools subagents_enable` to keep `subagent` active from the start.
|
|
86
|
+
|
|
87
|
+
## `toolActivation`
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
{ "toolActivation": "eager" }
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Controls how a new parent session offers the `subagent` tool. The default is `"auto"`.
|
|
94
|
+
|
|
95
|
+
- `"auto"`: a new session starts with the `subagents_enable` loader only when its model can take a new tool mid-conversation. Otherwise it starts with `subagent` active and no loader, because calling the loader on such a model makes Pi resend the conversation in a form the provider may not have cached. A model qualifies when its Pi `compat` settings set `supportsMidConvoSystemMessages: true` and, for its API, `supportsMidConvoToolChanges: true` (`anthropic-messages`), `supportsMidConvoToolAdditions: true` (`openai-completions`), or `supportsAdditionalTools: true` or `supportsToolSearch: true` (`openai-responses`, `openai-codex-responses`, `azure-openai-responses`). Other APIs, missing settings, and no model do not qualify.
|
|
96
|
+
- `"dynamic"`: every new session starts with the loader, whatever the model. This was the behavior before `toolActivation` existed.
|
|
97
|
+
- `"eager"`: the loader is not registered, so `subagent` is active from the first request, as with `--exclude-tools subagents_enable`. A resumed session that recorded the loader changes its tool list once on the next request.
|
|
98
|
+
|
|
99
|
+
The choice is made at session start or tree navigation, and only for a session with no messages. Resumed sessions keep the tools they recorded, and switching models mid-session does not change them. `"auto"` avoids only the loader's cache miss; other tool-list or provider changes can still miss the cache. An active `subagent` sends its full schema on every request. An invalid value is a config error, not a fallback to the default. Restart Pi after changing it.
|
|
100
|
+
|
|
79
101
|
## `toolDescriptionMode`
|
|
80
102
|
|
|
81
103
|
```json
|
|
@@ -86,6 +108,49 @@ Controls the parent-facing `subagent` tool description registered at startup. Th
|
|
|
86
108
|
|
|
87
109
|
`custom` reads `subagent-tool-description.md` from the project config directory, then from `~/.pi/agent/subagent-tool-description.md`. Missing, empty, unreadable, or oversized custom files fall back to the full description. Custom templates may use `{{fullDescription}}`, `{{compactDescription}}`, `{{safetyGuidance}}`, `{{agentDir}}`, and `{{projectConfigDir}}`; the safety guidance is always present so custom prose cannot remove the runtime guardrails. Restart Pi after changing the mode or custom file.
|
|
88
110
|
|
|
111
|
+
## `disabledFeatures`
|
|
112
|
+
|
|
113
|
+
```json
|
|
114
|
+
{ "disabledFeatures": ["watchdog", "panes", "preflight", "lane-metadata", "gates"] }
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Removes feature groups you do not use from the `subagent` tool. Each listed feature loses its parameters from the model-facing schema, and any request that still uses one of its parameters or actions fails with an error naming this setting. The check covers the parent tool, fanout-child tools, RPC, slash commands, prompt templates, scheduled launches, delegated launches, and workflow `runs.run`/`runs.all`/`runs.lanes` children, which are rejected before they launch. The built-in tool descriptions, the unknown-action list, the fanout-child tool description, and RPC `ping` no longer mention disabled features, and `{ action: "guide", topic: "tool-reference" }` starts with a notice listing what is disabled. Custom tool descriptions are not changed. Nothing is disabled by default, and the default schema and description are unchanged. An unknown or duplicate feature name fails config loading rather than silently re-enabling every feature.
|
|
118
|
+
|
|
119
|
+
| Feature | Parameters removed | Actions rejected |
|
|
120
|
+
|---|---|---|
|
|
121
|
+
| `agent-management` | `config` | `create`, `update`, `delete`, `eject`, `disable`, `enable`, `reset`, `refine`, `refine.show`, `refine.rollback` |
|
|
122
|
+
| `watchdog` | `scope`, `target`, `thinking` | `watchdog.status`, `watchdog.check`, `watchdog.configure`, `watchdog.recommend-model` |
|
|
123
|
+
| `panes` | `focus` | `inspector.*`, `project.*` |
|
|
124
|
+
| `missions` | `mission`, `missionUpdate`, `missionStatus`, `missionScope`, `missionId`, `runMode`, `runStatus`, `summary` | `mission.*` |
|
|
125
|
+
| `lane-management` | `handoffPath`, `laneId`, `merge`, `supersession`, `repo`, `planId` | `lane.status`, `lane.recordMerge`, `lane.recordSupersession`, `worktree.discard`, `worktree.cleanup` |
|
|
126
|
+
| `spawn-budget-grants` | `additional` | `grant-spawn-budget` |
|
|
127
|
+
| `preflight` | `preflight` | |
|
|
128
|
+
| `lane-metadata` | `lane` | |
|
|
129
|
+
| `gates` | `gate` | |
|
|
130
|
+
| `usage-budgets` | `usageBudget` | |
|
|
131
|
+
| `tool-budgets` | `toolBudget` | |
|
|
132
|
+
| `control-overrides` | `control` | |
|
|
133
|
+
| `extension-bindings` | `extensionBindings` | |
|
|
134
|
+
| `external-machines` | `machine` | |
|
|
135
|
+
| `workflow-scripts` | `workflow`, `args`, `preflight`, `globalConcurrencyLimit`, `maxSubagentSpawnsPerRun` | `validate` |
|
|
136
|
+
|
|
137
|
+
Disabling a per-call option removes only the per-call override. Configured defaults such as `toolBudget`, `usageBudget`, and `control` in this file still apply, the watchdog still follows its own settings, missions still attach automatically when [`missions`](#missions) enables them, and agents with a `machine` in their definition still run there. Operator screens that do not go through the `subagent` executor, such as `/subagents-admin`, are unchanged. With every feature and [`scheduledRuns.enabled`](#scheduledruns) disabled, the default `subagent` tool declaration (name, description, and parameter schema as JSON) shrinks from 18,239 to 10,263 characters (80 to 41 parameters). Restart Pi after changing this setting.
|
|
138
|
+
|
|
139
|
+
### Chain and tasks without workflow scripts
|
|
140
|
+
|
|
141
|
+
`workflow-scripts` removes workflow scripts and named workflow resources from every entry point. The model can no longer write a script, and a script that still arrives from RPC `spawn` (`script` or `workflow`), `/prompt-workflow`, a saved schedule, or a delegated launch fails with an error that names the setting. Schedule inspection, pause, and delete still work, but `schedule.create` cannot succeed because it needs a script. `/run` still works: it launches its one child directly. The built-in tool description and prompt snippet drop the script guidance and describe two small inputs instead:
|
|
142
|
+
|
|
143
|
+
- `tasks: [{ agent, task }, ...]` runs the children in parallel and returns their results in order.
|
|
144
|
+
- `chain: [step, ...]` runs steps in order. A step is `{ agent, task?, as? }` or a parallel group `{ parallel: [{ agent, task }, ...] }`. A group waits for all of its children.
|
|
145
|
+
|
|
146
|
+
A top-level `task` is the original request. Tasks can use three placeholders:
|
|
147
|
+
|
|
148
|
+
- `{task}` is the top-level `task`. Using it without a top-level `task` is an error.
|
|
149
|
+
- `{previous}` is the output of the previous chain step. For a parallel group, the outputs are joined in input order with a blank line between them. A chain step without `task` uses `{previous}`. The first step has no previous output, so it needs a `task` and cannot use `{previous}`.
|
|
150
|
+
- `{outputs.name}` is the output of an earlier sequential step that set `as: "name"`. Names are identifiers, and each name can be used once.
|
|
151
|
+
|
|
152
|
+
`tasks` items can only use `{task}`. Placeholders are replaced in one pass, so placeholder text inside an output is not replaced again. Other brace text stays as written. `chain` and `tasks` exclude each other, `agent`, and `action`. Steps accept only the fields above, and inputs are limited to 64 items and 16 KiB. Top-level child options such as `model`, `skill`, `output`, and `worktree` apply to every child. If a child fails, the run fails: a chain stops after the failed step or group, `tasks` fails once every child has settled, and the error names each failed child. The results of the children that already finished are still returned. Without this setting, `chain` and `tasks` are rejected as removed legacy inputs.
|
|
153
|
+
|
|
89
154
|
## `inlineToolDisplay`
|
|
90
155
|
|
|
91
156
|
```json
|
|
@@ -157,7 +222,7 @@ Set `enabled` to `false` (or remove the block) as a kill switch. In that state,
|
|
|
157
222
|
{ "asyncByDefault": false }
|
|
158
223
|
```
|
|
159
224
|
|
|
160
|
-
|
|
225
|
+
Workflow script calls use background execution when the request omits `async`. Set `asyncByDefault` to `false` to restore foreground-by-default behavior for tool launches that still use the internal single-run primitive. Callers can still force foreground with `async: false` unless `forceTopLevelAsync` is enabled.
|
|
161
226
|
|
|
162
227
|
## `defaultSubagentContext`
|
|
163
228
|
|
|
@@ -265,7 +330,7 @@ Forces depth-0 internal single, parallel, and chain runs into background mode an
|
|
|
265
330
|
{ "timeoutMs": 3600000 }
|
|
266
331
|
```
|
|
267
332
|
|
|
268
|
-
Global default runtime deadline, in milliseconds, for subagent runs. It replaces the built-in 30-minute backstop for foreground launches (single, parallel, chain, and
|
|
333
|
+
Global default runtime deadline, in milliseconds, for subagent runs. It replaces the built-in 30-minute backstop for foreground launches (single, parallel, chain, and workflow scripts) and plain single-agent async runs whenever no call-level `timeoutMs`/`maxRuntimeMs` applies. For single-agent launches, selected agent frontmatter `timeoutMs` still wins. This only moves the *default*. Expiring this run-level deadline is terminal.
|
|
269
334
|
|
|
270
335
|
This deadline bounds the whole run. The wait for a single model response is bounded separately by Pi's `httpIdleTimeoutMs` setting (default 300000; `0` disables it), which Pi applies both as the SDK request timeout and as the undici header/body idle timeout. Detached async runners read the same setting from `~/.pi/agent/settings.json` and the project `.pi/settings.json` for their own HTTP dispatcher, so a local model that queues or prefills for longer than five minutes needs `httpIdleTimeoutMs` raised or disabled in Pi settings, plus a `timeoutMs` long enough for the run.
|
|
271
336
|
|
|
@@ -301,7 +366,7 @@ An explicit `subagent` call value wins over this default. Choose a value at leas
|
|
|
301
366
|
{ "globalConcurrencyLimit": 20 }
|
|
302
367
|
```
|
|
303
368
|
|
|
304
|
-
Caps simultaneously running children inside one run, including durable legacy multi-child runs and
|
|
369
|
+
Caps simultaneously running children inside one run, including durable legacy multi-child runs and workflow script launches through `runs.run`/`runs.all`. Queued workflow children retain their stable keys and begin when a running sibling releases capacity. The default is `20`.
|
|
305
370
|
|
|
306
371
|
Inline or file-backed top-level workflow calls may set a positive safe-integer `globalConcurrencyLimit` to override this value for that workflow. The override is workflow-only and is not forwarded to child calls.
|
|
307
372
|
|
|
@@ -355,7 +420,7 @@ This limit bounds current top-level async load. It is separate from cumulative `
|
|
|
355
420
|
{ "scheduledRuns": { "enabled": false, "maxPending": 20 } }
|
|
356
421
|
```
|
|
357
422
|
|
|
358
|
-
Durable schedules are enabled by default and stored per project under `.pi/subagents/schedules/<id>/`. See [missions.md](missions.md#schedules) for usage.
|
|
423
|
+
Durable schedules are enabled by default and stored per project under `.pi/subagents/schedules/<id>/`. See [missions.md](missions.md#schedules) for usage. Setting `enabled` to `false` also removes the schedule parameters (`name`, `at`, `every`, `sessionOnly`, `quiet`, `on`, `timezone`, `overlap`, `catchUp`) from the `subagent` tool and rejects `schedule.*` actions from every entry point. Saved schedules are kept and become manageable again when you re-enable schedules.
|
|
359
424
|
|
|
360
425
|
Set `storeRoot` to keep durable schedules outside project repositories. It must be an absolute path or a `~/` path, which expands from the user home directory. Each project is stored under a hash of its resolved working directory, so projects do not share schedules.
|
|
361
426
|
|
|
@@ -400,7 +465,7 @@ Routes relative `output` paths for single-agent `/run` calls under this director
|
|
|
400
465
|
{ "maxSubagentDepth": 1 }
|
|
401
466
|
```
|
|
402
467
|
|
|
403
|
-
Controls nested delegation when no stricter limit is inherited from the launching child's runtime config. Per-agent `maxSubagentDepth` can tighten the limit for that agent's child runs, but cannot relax an inherited stricter limit. This applies even to children that explicitly declare `tools: subagent` or `allowNestedSubagents: true`; at the cap, execution fanout is blocked instead of silently hiding nested work.
|
|
468
|
+
Controls nested delegation when no stricter limit is inherited from the launching child's runtime config. The default is 2 when neither the runtime limit, `PI_SUBAGENT_MAX_DEPTH`, nor this setting supplies a limit. Per-agent `maxSubagentDepth` can tighten the limit for that agent's child runs, but cannot relax an inherited stricter limit. This applies even to children that explicitly declare `tools: subagent` or `allowNestedSubagents: true`; at the cap, execution fanout is blocked instead of silently hiding nested work.
|
|
404
469
|
|
|
405
470
|
## `PI_SUBAGENT_PI_BINARY`
|
|
406
471
|
|
|
@@ -412,13 +477,23 @@ Overrides the `pi` command pi-subagents spawns for project panes and the profile
|
|
|
412
477
|
|
|
413
478
|
Foreground children remain sessions inside the parent. Npm background children retain their Node runner and host-package peer aliases; this variable does not turn npm Pi into a binary-backed runner. See [Standalone background execution](standalone-background.md) for the official tested target.
|
|
414
479
|
|
|
480
|
+
## `PI_PACKAGE_DIR`
|
|
481
|
+
|
|
482
|
+
```bash
|
|
483
|
+
export PI_PACKAGE_DIR=/path/to/pi-coding-agent-package
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
Pi's own package/assets root. Npm background children receive the detected npm host root as `PI_PACKAGE_DIR`, which overrides an inherited bundled layout; Bun-compiled hosts pass the parent's value through so children keep their release assets.
|
|
487
|
+
|
|
415
488
|
## `PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT`
|
|
416
489
|
|
|
417
490
|
```bash
|
|
418
491
|
export PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT=/path/to/pi-coding-agent-package
|
|
419
492
|
```
|
|
420
493
|
|
|
421
|
-
Overrides host-package discovery for spawned children. Foreground CLI resolution uses this root to locate the `pi` CLI script, and the detached background runner uses it for jiti host resolution and peer-package aliases, so both child kinds agree on one host.
|
|
494
|
+
Overrides host-package discovery for spawned children. Foreground CLI resolution uses this root to locate the `pi` CLI script, and the detached background runner uses it for jiti host resolution and peer-package aliases, so both child kinds agree on one host. The value must be the root of a canonical `@earendil-works/pi-coding-agent` installation (the directory containing its `package.json`, with that package name); both child kinds still validate the package name and its peer packages from that install tree, so a package whose manifest carries a different name is rejected even with the override set. Empty or whitespace-only values are ignored.
|
|
495
|
+
|
|
496
|
+
The default in-process child session loader consults the same discovery. Before falling back to a bare `@earendil-works/pi-coding-agent` import, it resolves the host package root (the running pi process's location, then this override, then pi-subagents' own install tree as a last fallback) and imports the host's entry file directly, so children share the host's single SDK instance instead of a second copy. Roots whose `package.json` name is not `@earendil-works/pi-coding-agent` are rejected. When this override is selected, an unimportable root is reported instead of falling back to a bare import from a different tree.
|
|
422
497
|
|
|
423
498
|
## `intercomBridge`
|
|
424
499
|
|
package/docs/extension-api.md
CHANGED
|
@@ -19,7 +19,7 @@ registerWorkflowResource({
|
|
|
19
19
|
}): { dispose(): void }
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
Names are case-sensitive, at most 128 characters, and match `[A-Za-z0-9][A-Za-z0-9._-]*`; use an extension prefix. Versions are positive safe integers. Registration throws for invalid input, protected builtins (`review`, `run-ci`), or duplicate names within the same session. Different sessions may register the same name. Dispose before replacement; there is no silent overwrite.
|
|
22
|
+
Names are case-sensitive, at most 128 characters, and match `[A-Za-z0-9][A-Za-z0-9._-]*`; use an extension prefix. Versions are positive safe integers. Registration throws for invalid input, protected builtins (`review`, `run-ci`, and `chain` and `tasks`, which back the tool's structured inputs), or duplicate names within the same session. Different sessions may register the same name. Dispose before replacement; there is no silent overwrite.
|
|
23
23
|
|
|
24
24
|
Register in `session_start` using **`ctx.sessionManager.getSessionId()`**, not the session file path or a tool argument. Dispose in `session_shutdown`. New/resumed/forked sessions and reloads need registration from the replacement runtime's `session_start`; do not retain old `pi`/`ctx` references. The extension owns cleanup, not an automatic registration lifecycle manager. Disposal is idempotent and cannot remove a newer replacement. Missing cleanup can cause a duplicate-registration failure on reload.
|
|
25
25
|
|
|
@@ -108,20 +108,21 @@ pi.events.emit("subagents:rpc:v1:request", {
|
|
|
108
108
|
requestId,
|
|
109
109
|
method: "spawn",
|
|
110
110
|
params: {
|
|
111
|
-
|
|
111
|
+
script: `return runs.run("main", { agent: "reviewer", task: "Review the current diff" })`,
|
|
112
112
|
context: "fresh"
|
|
113
113
|
}
|
|
114
114
|
});
|
|
115
115
|
```
|
|
116
116
|
|
|
117
|
-
The RPC methods are `ping`, `status`, `manage`, `spawn`, `steer`, `interrupt`, `stop`, and `
|
|
117
|
+
The RPC methods are `ping`, `status`, `manage`, `spawn`, `steer`, `interrupt`, `stop`, `resume`, and `cost`. `status`, `manage`, `steer`, `interrupt`, and `resume` reuse normal package-owned actions.
|
|
118
118
|
|
|
119
119
|
Method notes:
|
|
120
120
|
|
|
121
121
|
- `manage` exposes a narrow schedule-only allowlist: `schedule.list`, `schedule.show`, `schedule.history`, `schedule.pause`, `schedule.resume`, `schedule.run`, and `schedule.delete`. All actions except `schedule.list` require `id`. Mission, agent, config, worktree, and arbitrary management actions are rejected before executor dispatch. `ping.capabilities.managementActions` advertises the exact allowlist.
|
|
122
|
-
- `spawn` accepts structured single-child execution (`agent`, `task?`), inline `
|
|
122
|
+
- `spawn` accepts structured single-child execution (`agent`, `task?`), inline script text as `script`, or `workflow` with a script path (containing `/`, such as `"./ci/sweep.js"`) or a named workflow resource. `workflow: true` is rejected because RPC requests have no assistant reply to read a block from; the removed `workflowScript` and `workflowScriptPath` fields are rejected with errors naming `script` and `workflow`. Spawn is async-only: omit `async` or set `async: true`, omit `clarify`, and do not pass management `action` values. Relative script paths resolve against the request `cwd`. It goes through the same executor as the `subagent` tool, so agent discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status all behave the same.
|
|
123
123
|
- `steer` requires an async run `id` (plus optional child `index`) and a non-empty `message`; its reply preserves the normal acknowledged-delivery result. Optional `mode` values are `steer` (default), `follow_up`, and `auto`, and receipts include `deliveryStatus: "delivered" | "queued"`. RPC steering disables the direct tool's pause-and-revive recovery in every mode so an extension keeps authority over the exact child it spawned; `ping.capabilities.nonRecoveringSteer` advertises this guarantee.
|
|
124
124
|
- `resume` requires a run target and non-empty `message`. It delegates to the existing revival path, which validates current-session ownership, persisted session/recovery metadata, stopped/live state, capability ceilings, and the exclusive session lease before returning the new async run details. Callers may request a `file-only` output path for the revived result without overriding its model, tools, or budgets. `ping.capabilities.resume` advertises this seam.
|
|
125
|
+
- `cost` returns the same parent-plus-child accounting `/subagent-cost` renders, as data: `{ version: 1, parent, children, childTotal, total, unresolvedAsyncChildren }`, where each usage is `{ input, output, cacheRead, cacheWrite, cost, turns }` and each child carries `label`, `agent`, `runId`, `usage`, and `sessionFile` when known. It is read-only and walks the current session branch plus existing run artifacts, so request it on your own turn boundaries (for example after `agent_settled` or an async completion wake), not on a timer. `unresolvedAsyncChildren` counts async children whose metadata could not be read; treat `childTotal` as a lower bound when it is non-zero, exactly as documented for `/subagent-cost` in [observability.md](observability.md). `ping.capabilities.cost` advertises `{ version: 1 }`.
|
|
125
126
|
- `stop` targets current-session top-level async runs through the stop control channel and records a `stopped` lifecycle instead of reporting a timeout.
|
|
126
127
|
- `status` keeps targeted and rich requests on the executor-backed path. A request with no `id`, `runId`, `dir`, `index`, `view`, or `lines` may use the restored in-memory projections and a short summary; when the live state is missing, stale, session-mismatched, or not restored, it falls back to normal executor status. Status `view`, `lines`, and `index` are forwarded for targeted transcript/fleet requests. Successful replies retain `text`, `details`, `fleet`, and `asyncSnapshot`; the short summary intentionally omits canonical filesystem details, wait subscriptions, and budget annotations.
|
|
127
128
|
|
|
@@ -136,6 +137,7 @@ Capability advertisements on `ping`:
|
|
|
136
137
|
- `resume` — the revival seam described above.
|
|
137
138
|
- `statusProjection: { version: 1, untargeted: "in-memory-when-ready", targeted: "executor" }` — untargeted status may use restored bounded projections; targeted or rich status remains executor-backed.
|
|
138
139
|
- `fleetStatus: { version: 1 }` — successful `status` replies additionally include `data.fleet`.
|
|
140
|
+
- `cost: { version: 1 }` — the `cost` method is available and returns the versioned report shape above.
|
|
139
141
|
|
|
140
142
|
Structured delegation progress updates carry `runId` as soon as foreground execution allocates it, so a caller can retain the package-owned revival target even if its own tool turn is interrupted before the terminal response. Foreground `details.results[]` rows also include a numeric `index` that is unique within the run and stable across partial progress snapshots and the final result; use `(runId, index)` instead of row position to correlate single, counted parallel, and chain children.
|
|
141
143
|
|
|
@@ -188,6 +190,8 @@ const registration = request.result.registration;
|
|
|
188
190
|
|
|
189
191
|
If `pi-subagents` is a resolvable dependency of the consumer package, `pi-subagents/agents` exports `RUNTIME_AGENT_REGISTER_EVENT`, the request/result types, and `registerAgentViaEvents()` for the same contract. A separately installed Pi package is not automatically a Node dependency of another package. In that case, use the event contract directly instead of a runtime import. A type-only development dependency is optional.
|
|
190
192
|
|
|
193
|
+
A registered agent follows the operator's subagent model settings like any other agent: `subagents.defaultModel`, `defaultProvider`, and `defaultThinking` fill a definition that omits `model` or `thinking`, and the `model`, `defaultProvider`, `fast`, and `thinking` fields of `agentOverrides.<name>` win over the definition. Every other definition field stays extension-owned, and other override fields are ignored for runtime agents. Set `model` in the definition only when the agent must not follow operator model settings; `model: "inherit"` selects the parent session model explicitly.
|
|
194
|
+
|
|
191
195
|
The installed owner applies the existing runtime-agent validation, collision checks, limits, runtime source metadata, and cleanup. If more than one owner listens, the first handler that writes `request.result` wins. Unsupported versions, malformed requests, and registration failures return `{ ok: false, error }`. No result means no compatible owner handled the event.
|
|
192
196
|
|
|
193
197
|
This contract is process-local. It does not register agents in child sessions or other Pi processes, and it does not change package discovery or package resolution.
|
|
@@ -258,7 +262,8 @@ Preflight covers ordinary single-agent launch resolution:
|
|
|
258
262
|
|
|
259
263
|
- Selected agent identity and shadowed candidates.
|
|
260
264
|
- A parsed-definition digest, including system prompt and launch-affecting model, tool, skill, extension, output, and memory fields. Runtime overlays such as the Intercom bridge never change it.
|
|
261
|
-
- Fresh/fork context, effective model and thinking, skill and tool resolution, direct MCP selections, runtime/configured extensions.
|
|
265
|
+
- Fresh/fork context, effective model and thinking, skill and tool resolution, direct MCP selections, runtime/configured extensions. Pass your extension's `pi` as `runtimeSnapshotHost` so `mcp:` selections resolve against Pi's built-in MCP the way a launch does. Without it, preflight cannot see built-in MCP and resolves `mcp:` selections through pi-mcp-adapter's configuration, as before.
|
|
266
|
+
- Model scope allow lists accept the reserved tokens `inherit` and `scoped`; `scoped` expands to the caller-supplied `scopedModelIds` snapshot, degrading to `inherit` when it is omitted. Callers whose `modelScope.allow` uses `scoped` must pass `scopedModelIds` (the session's `/scoped-models` snapshot) alongside `parentModel`, otherwise preflight resolves it as `inherit` and may reject models the actual launch allows.
|
|
262
267
|
- The resolved Intercom bridge state (`intercomBridge.mode` and `intercomBridge.active`). An active bridge appends the bridge instruction to the child prompt and adds `contact_supervisor` to a declared tool list, exactly as execution does.
|
|
263
268
|
- Artifact/session paths, async lifecycle/status/result/event/process-terminal paths, package/lifecycle versions, capability-ceiling audit data, and stable digests.
|
|
264
269
|
|
|
@@ -329,7 +334,7 @@ Identity:
|
|
|
329
334
|
Results:
|
|
330
335
|
|
|
331
336
|
- Result mode is explicit. Text remains literal even when it looks like JSON. Structured mode returns the separately captured, schema-validated JSON value.
|
|
332
|
-
- Terminal usage reports input, output, cache-read, cache-write, cost, turns, tool calls, and duration alongside the effective model and thinking level when known.
|
|
337
|
+
- Terminal usage reports input, output, cache-read, cache-write, cost, turns, tool calls, and duration alongside the effective model and thinking level when known. Native child totals are reconciled per attempt from post-prompt session messages: complete persisted fields replace live aggregates, while incomplete fields retain them.
|
|
333
338
|
|
|
334
339
|
Live update events are bounded progress snapshots, not patches, so consumers should replace the prior snapshot rather than merge it as a delta. Structured delegation coalesces heartbeats whose delegation-visible progress and recent output are unchanged; a duration-only heartbeat therefore does not produce another update. The terminal response remains authoritative for the complete result, error, and final usage details.
|
|
335
340
|
|
|
@@ -433,7 +438,7 @@ The provider returns handles with `providerJobId`, `state`, optional `handleUrl`
|
|
|
433
438
|
|
|
434
439
|
`followUp(input)` is optional. When it is present, a completed external-job run can be continued with `subagent({ action: "resume", id: "<run>", message: "..." })`. Pi sends the completed parent provider job id plus a stable `requestId` and `requestDigest`. The provider must continue that parent conversation or fail closed. It must not open a fresh thread when the parent conversation is missing.
|
|
435
440
|
|
|
436
|
-
The async runner process does not import provider internals. It writes operation requests into its async run directory. The
|
|
441
|
+
The async runner process does not import provider internals. It writes operation requests into its async run directory. The Pi process of the session that launched the run services those requests against the registered provider and writes operation responses. A child session services the external-job runs it launches. Register the provider in that child too, for example through the child agent's `extensions`. If the provider is not registered, the bridge fails closed with an actionable error. If a run is recovered after provider job metadata exists, the runner calls `reattach` and `result`; it does not call `start` or `follow-up` again.
|
|
437
442
|
|
|
438
443
|
## Inspect integration
|
|
439
444
|
|
|
@@ -446,7 +451,69 @@ subagent({ action: "inspector.status", id: "<run-id>", index: 0 })
|
|
|
446
451
|
subagent({ action: "inspector.close", id: "<run-id>", index: 0 })
|
|
447
452
|
```
|
|
448
453
|
|
|
449
|
-
`inspector.command` returns a standalone runner command without contacting a host or writing a binding. `inspector.open` selects an available
|
|
454
|
+
`inspector.command` returns a standalone runner command without contacting a host or writing a binding. `inspector.open` selects an available built-in or externally registered inspector plugin. `status` and `close` select the plugin that owns the run binding and report clearly when that plugin does not support the requested lifecycle action. Without an available plugin, `open` fails closed with an actionable message; ordinary launches remain headless. Closing an inspector never stops the run.
|
|
455
|
+
|
|
456
|
+
### Register an external inspector
|
|
457
|
+
|
|
458
|
+
A loaded Pi extension can add an inspector through the synchronous
|
|
459
|
+
`pi-subagents:inspector-register:v1` event. This lets terminal integrations use
|
|
460
|
+
Fleet's existing Enter/H actions without modifying pi-subagents. Registration
|
|
461
|
+
adds no runner, tool, or configuration option.
|
|
462
|
+
|
|
463
|
+
```ts
|
|
464
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
465
|
+
import type { InspectorRegistration, InspectorRegistrationRequest } from "pi-subagents/inspectors";
|
|
466
|
+
import { myInspector } from "./my-inspector.ts"; // Your InspectorPlugin implementation.
|
|
467
|
+
|
|
468
|
+
export default function (pi: ExtensionAPI) {
|
|
469
|
+
let registration: InspectorRegistration | undefined;
|
|
470
|
+
pi.on("session_start", () => {
|
|
471
|
+
registration?.dispose();
|
|
472
|
+
const request: InspectorRegistrationRequest = { version: 1, plugin: myInspector };
|
|
473
|
+
pi.events.emit("pi-subagents:inspector-register:v1", request);
|
|
474
|
+
if (!request.result) throw new Error("pi-subagents inspector registration is unavailable.");
|
|
475
|
+
if (!request.result.ok) throw request.result.error;
|
|
476
|
+
registration = request.result.registration;
|
|
477
|
+
});
|
|
478
|
+
pi.on("session_shutdown", () => registration?.dispose());
|
|
479
|
+
}
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
`pi-subagents/inspectors` exports the event name as `INSPECTOR_REGISTER_EVENT`,
|
|
483
|
+
the request and registration types, and the existing `InspectorPlugin`,
|
|
484
|
+
`InspectorContext`, `InspectorLaunch`, `InspectorParams`, and `InspectorTarget`
|
|
485
|
+
types. When pi-subagents is a resolvable dependency, `registerInspector(pi, plugin)`
|
|
486
|
+
emits the same request and returns the registration or throws. Independently
|
|
487
|
+
installed extensions can use the event directly; type-only imports need only a
|
|
488
|
+
development dependency and create no runtime module dependency.
|
|
489
|
+
|
|
490
|
+
An `InspectorPlugin` supplies:
|
|
491
|
+
|
|
492
|
+
- `name`: 1–128 letters, digits, dots, underscores, or hyphens, starting with a letter or digit.
|
|
493
|
+
- `available(context)`: whether this terminal host can open an inspector; may be async.
|
|
494
|
+
- `open(context, launch, params)`: open the supplied inspector command and return an `AgentToolResult<Details>`, like the built-in plugins. `launch.executable` and `launch.argv` carry the existing runner, target, trusted session roots, and steer/stop permission flags. Preserve these arguments and respect `params.focus`.
|
|
495
|
+
- `owns(context)`: synchronously check whether the provider owns an inspector binding for this target.
|
|
496
|
+
- Optional `status(context)` and `close(context)`: inspect or close that binding, returning the same result type. Closing an inspector must not stop the subagent.
|
|
497
|
+
|
|
498
|
+
The existing dispatcher tries Herdr, then Ghostty, then external providers in
|
|
499
|
+
registration order. Names are case-sensitive; duplicate names and the built-in
|
|
500
|
+
names `herdr` and `ghostty` are rejected. A selected provider's failure is not
|
|
501
|
+
retried through another provider. Status/close use the first provider whose
|
|
502
|
+
`owns` returns true; unavailable lifecycle methods remain explicit errors.
|
|
503
|
+
Providers own their pane bindings and must verify ownership before closing one.
|
|
504
|
+
|
|
505
|
+
Registrations belong to the pi-subagents runtimes listening on the Pi event bus,
|
|
506
|
+
not the consumer module; they survive runtime replacement, are isolated from
|
|
507
|
+
child runtimes and other Pi instances, and are cleared when the last owner shuts
|
|
508
|
+
down or reloads. Disposal is idempotent, removes callbacks without closing panes,
|
|
509
|
+
and takes effect even while Fleet is open because it resolves providers per
|
|
510
|
+
action. Providers receive the current action context, so do not capture a stale
|
|
511
|
+
session context; dispose before re-registering on session changes. Unsupported
|
|
512
|
+
versions and malformed plugins return `{ ok: false, error }`, and the first owner
|
|
513
|
+
to fill `result` handles the request.
|
|
514
|
+
|
|
515
|
+
This is a trusted-code integration, not a sandbox. Registration does not change
|
|
516
|
+
run resolution, child-safe restrictions, authority policy, or supervisor routing.
|
|
450
517
|
|
|
451
518
|
### Herdr inspector plugin
|
|
452
519
|
|
package/docs/missions.md
CHANGED
|
@@ -30,16 +30,11 @@ const created = subagent({
|
|
|
30
30
|
action: "mission.create",
|
|
31
31
|
mission: { title: "Ship auth refresh", objective: "Implement and validate token refresh" }
|
|
32
32
|
})
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
missionId: "<mission-id>"
|
|
36
|
-
})
|
|
33
|
+
// After a ```js workflow block that runs the approved auth refresh plan:
|
|
34
|
+
subagent({ workflow: true, missionId: "<mission-id>" })
|
|
37
35
|
|
|
38
36
|
// Or create and attach in one launch
|
|
39
|
-
subagent({
|
|
40
|
-
workflowScript: `return runs.run("main", { agent: "worker", task: "Implement the approved plan" })`,
|
|
41
|
-
mission: { title: "Ship auth refresh" }
|
|
42
|
-
})
|
|
37
|
+
subagent({ workflow: true, mission: { title: "Ship auth refresh" } })
|
|
43
38
|
```
|
|
44
39
|
|
|
45
40
|
### Goal missions
|
|
@@ -89,6 +84,10 @@ Durable schedules are enabled by default and stored per project under `.pi/subag
|
|
|
89
84
|
|
|
90
85
|
Create a one-shot schedule:
|
|
91
86
|
|
|
87
|
+
```js workflow
|
|
88
|
+
return runs.run("main", { agent: "reviewer", task: "Review the current diff." });
|
|
89
|
+
```
|
|
90
|
+
|
|
92
91
|
```ts
|
|
93
92
|
subagent({
|
|
94
93
|
action: "schedule.create",
|
|
@@ -96,22 +95,23 @@ subagent({
|
|
|
96
95
|
name: "Evening review",
|
|
97
96
|
at: "+30m",
|
|
98
97
|
baseRef: "refs/heads/release",
|
|
99
|
-
|
|
98
|
+
workflow: true
|
|
100
99
|
})
|
|
101
100
|
```
|
|
102
101
|
|
|
103
|
-
Create a fixed recurring workflow:
|
|
102
|
+
Create a fixed recurring workflow from a script file:
|
|
104
103
|
|
|
105
104
|
```ts
|
|
106
|
-
|
|
105
|
+
// .pi/workflows/backlog.js: return runs.run('main', { agent: 'worker', task: args.task })
|
|
106
|
+
subagent({ action: "schedule.create", id: "backlog", every: "6h", catchUp: "latest", workflow: "./.pi/workflows/backlog.js", args: { task: "Maintain core" } })
|
|
107
107
|
```
|
|
108
108
|
|
|
109
|
-
Fixed intervals support `m`, `h`, `d`, and `w` units and advance from the planned time without completion drift. Schedule arguments are normalized and persisted for exact replay after reload; do not put secrets in them.
|
|
109
|
+
Fixed intervals support `m`, `h`, `d`, and `w` units and advance from the planned time without completion drift. The schedule stores the script text read at creation, so later edits to the file do not change it. Schedule arguments are normalized and persisted for exact replay after reload; do not put secrets in them.
|
|
110
110
|
|
|
111
111
|
Create a quiet recurring workflow whose successful completions stay visible but do not wake the parent session:
|
|
112
112
|
|
|
113
113
|
```ts
|
|
114
|
-
subagent({ action: "schedule.create", id: "nightly-sweep", every: "24h", quiet: true,
|
|
114
|
+
subagent({ action: "schedule.create", id: "nightly-sweep", every: "24h", quiet: true, workflow: true })
|
|
115
115
|
```
|
|
116
116
|
|
|
117
117
|
Manage schedules with `schedule.list`, `schedule.show`, `schedule.history`, `schedule.pause`, `schedule.resume`, `schedule.run`, `schedule.run-due`, and `schedule.delete`.
|