@xzzpig/pi-subagents 0.2.0 → 0.4.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 +96 -0
- package/README.md +2 -0
- package/agents/oracle.md +7 -5
- package/agents/researcher.md +1 -1
- package/agents/reviewer.md +2 -2
- package/agents/scout.md +1 -1
- package/agents/worker.md +1 -1
- package/docs/agents.md +3 -0
- package/docs/configuration.md +121 -10
- package/docs/extension-api.md +36 -0
- package/docs/missions.md +5 -3
- package/docs/observability.md +43 -3
- package/docs/tool-reference.md +20 -3
- package/docs/workflows.md +2 -2
- package/package.json +4 -4
- package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
- package/skills/pi-subagents/references/execution-controls.md +5 -4
- package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
- package/skills/pi-subagents/references/prompting-and-roles.md +31 -15
- package/src/agents/agent-serializer.ts +2 -0
- package/src/agents/agents.ts +46 -15
- package/src/api/external-runs.ts +174 -84
- package/src/api/preflight.ts +13 -7
- package/src/extension/config.ts +59 -0
- package/src/extension/doctor.ts +40 -0
- package/src/extension/index.ts +83 -9
- package/src/extension/public-execution.ts +37 -4
- package/src/extension/rpc.ts +8 -10
- package/src/extension/schemas.ts +12 -10
- package/src/extension/tool-description.ts +13 -9
- package/src/inspectors/herdr/actions.ts +13 -8
- package/src/inspectors/herdr/inspector-runner.ts +16 -3
- package/src/inspectors/herdr/project-panes.ts +2 -6
- package/src/inspectors/herdr/shell-command.ts +16 -0
- package/src/intercom/intercom-bridge.ts +9 -5
- package/src/intercom/native-supervisor-channel.ts +19 -42
- package/src/missions/goal-driver.ts +3 -1
- package/src/missions/lifecycle.ts +4 -7
- package/src/missions/store.ts +12 -7
- package/src/missions/workflow-state.ts +6 -2
- package/src/runs/background/active-async-capacity.ts +431 -0
- package/src/runs/background/active-run-index.ts +77 -3
- package/src/runs/background/async-execution.ts +190 -72
- package/src/runs/background/async-job-tracker.ts +5 -0
- package/src/runs/background/async-resume.ts +21 -7
- package/src/runs/background/async-status-snapshot.ts +277 -0
- package/src/runs/background/async-status.ts +17 -6
- package/src/runs/background/chain-append.ts +33 -15
- package/src/runs/background/chain-root-attachment.ts +2 -2
- package/src/runs/background/completion-replay.ts +11 -1
- package/src/runs/background/fleet-view.ts +21 -6
- package/src/runs/background/owned-process-tree.ts +104 -0
- package/src/runs/background/process-terminal.ts +17 -3
- package/src/runs/background/result-files.ts +437 -0
- package/src/runs/background/result-watcher.ts +188 -41
- package/src/runs/background/resume-guidance.ts +27 -7
- package/src/runs/background/retained-children.ts +75 -18
- package/src/runs/background/run-id-resolver.ts +30 -24
- package/src/runs/background/run-status.ts +106 -5
- package/src/runs/background/scheduled-runs.ts +54 -28
- package/src/runs/background/stale-run-reconciler.ts +30 -16
- package/src/runs/background/subagent-runner.ts +352 -62
- package/src/runs/background/subagent-wait.ts +2 -0
- package/src/runs/background/wait-completions.ts +5 -2
- package/src/runs/foreground/async-dismiss-action.ts +2 -1
- package/src/runs/foreground/chain-execution.ts +53 -2
- package/src/runs/foreground/execution.ts +309 -34
- package/src/runs/foreground/foreground-control.ts +12 -0
- package/src/runs/foreground/prompt-audit.ts +172 -0
- package/src/runs/foreground/subagent-executor.ts +936 -224
- package/src/runs/shared/acceptance.ts +13 -4
- package/src/runs/shared/completion-guard.ts +107 -1
- package/src/runs/shared/external-cli-runner.ts +4 -0
- package/src/runs/shared/llm-intent-arbiter.ts +302 -0
- package/src/runs/shared/model-fallback.ts +16 -2
- package/src/runs/shared/nested-events.ts +66 -62
- package/src/runs/shared/orca-progress-tabs.ts +375 -0
- package/src/runs/shared/parallel-utils.ts +4 -0
- package/src/runs/shared/pi-args.ts +44 -1
- package/src/runs/shared/run-fanout-budget.ts +280 -0
- package/src/runs/shared/single-output.ts +4 -2
- package/src/runs/shared/subagent-control.ts +15 -0
- package/src/runs/shared/subagent-prompt-runtime.ts +1 -9
- package/src/runs/shared/subagent-startup-retry.ts +12 -0
- package/src/runs/shared/task-intent.ts +19 -3
- package/src/runs/shared/tool-timeout.ts +93 -0
- package/src/runs/shared/worktree.ts +17 -5
- package/src/shared/agent-stream-options.ts +5 -0
- package/src/shared/artifacts.ts +2 -6
- package/src/shared/display-text.ts +50 -0
- package/src/shared/node-executable.ts +21 -0
- package/src/shared/types.ts +143 -5
- package/src/shared/utils.ts +3 -1
- package/src/slash/slash-commands.ts +34 -25
- package/src/slash/slash-live-state.ts +3 -0
- package/src/tui/fleet-status.ts +164 -47
- package/src/tui/fleet-transcript.ts +1 -48
- package/src/tui/fleet.ts +352 -27
- package/src/tui/render.ts +122 -44
- package/src/watchdog/permission-arbiter.ts +2 -1
- package/src/watchdog/review.ts +4 -3
- package/src/workflows/chat-progress.ts +10 -2
- package/src/workflows/scripted-workflow.ts +292 -79
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,102 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [0.4.0] - 2026-08-16
|
|
6
|
+
|
|
7
|
+
### Changed
|
|
8
|
+
- Synced the fork with upstream pi-subagents v0.50.0 while preserving local compatibility fixes (@xzzpig/pi-permission-system priority in resolvePermissionSystemExtension(), Pi SDK 0.83 streamFn option naming).
|
|
9
|
+
|
|
10
|
+
## [0.50.0] - 2026-08-15
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
- Add optional Orca progress tabs with bounded, sanitized mirrors for native Pi and external CLI children. Thanks to @hyein-cbio for #1080.
|
|
14
|
+
- Show caller-owned external jobs in FleetView through a bounded push/cache API, without polling or exposing managed controls. Thanks to @ssyram for #1083.
|
|
15
|
+
- Add a bounded current-status snapshot for async runs in RPC surfaces, without replaying terminal history. Thanks to @yanqianglu for #1078.
|
|
16
|
+
- Add an optional `foregroundDetachShortcut` binding and show it in the running single-subagent card, so foreground work can be moved to the background without editing package source. Thanks to @Lewis-E for #1097.
|
|
17
|
+
|
|
18
|
+
### Changed
|
|
19
|
+
- Clarify retained-child resumability and native supervisor coordination guidance. Thanks to @ELA718 for #1126.
|
|
20
|
+
- Clarify that completed retained writers should use `resume`, while `steer` with `mode: "follow_up"` only queues text for the next revival (#1104).
|
|
21
|
+
- Treat oracle/advisor consultation prompts as supervisor-backed dialogue when material unknowns remain (#1102).
|
|
22
|
+
- Show explicit resumable and not-resumable states, with fallback guidance, in retained child listings (#1101).
|
|
23
|
+
- Reduce reload work for large async histories by indexing the async result inbox by session, observer, and tool-call id instead of scanning every old result file. Stale terminal active markers now age out, and replay cleanup scans run less often.
|
|
24
|
+
|
|
25
|
+
### Fixed
|
|
26
|
+
- Keep Orca progress tabs from treating write-stream backpressure as mirror truncation.
|
|
27
|
+
- Stop advertising an `output-<index>.log` artifact in run transcripts when that file was never written, so workflow runs no longer point at a path that cannot exist. Thanks to @lbijeau for #1124.
|
|
28
|
+
- Keep FleetView working when a session file path is longer than a short identity, instead of failing external-job inspection on every poll. Thanks to @albertgwo for #1121 and @Don-Yin for #1122.
|
|
29
|
+
- Keep structured single-child runs from overriding output paths in the task, while preserving explicit and agent-configured outputs. Thanks to @pasemes for #1119.
|
|
30
|
+
- Keep no-edit confirmations guarded after later changes retract a prior implementation (#1115).
|
|
31
|
+
- Remove the native generic `intercom` compatibility fallback from supervisor coordination while preserving `contact_supervisor`, `subagent_supervisor`, and external `intercom` providers. Thanks to @jaudiger for #1107.
|
|
32
|
+
- Report an actionable project-settings override when duplicate ambient Pi extensions prevent a child from starting (#1114).
|
|
33
|
+
- Keep the FleetView overlay refreshed while open and count active leaf agents in the compact summary. Thanks to @Don-Yin for #1108.
|
|
34
|
+
- Keep user-requested foreground detaches from showing supervisor-response recovery guidance. Thanks to @Lewis-E for #1109.
|
|
35
|
+
- Reject configured subagent models that are not in the active host model registry before spawning a child, instead of forwarding an invalid `--model` argument to Pi. Thanks to @DresvyanskiyDenis for #1093.
|
|
36
|
+
- Start Herdr inspector and project pane commands with a shell-safe executable token, including paths that need quoting in Nushell. Thanks to @Rival for #1092.
|
|
37
|
+
- Stop `agentContract.version` from using an `enum` on an integer, which Gemini's function-calling schema subset rejects. Integer bounds express the same constraint and are valid everywhere. Thanks to @MarcusNeufeldt for #1095.
|
|
38
|
+
- Show supervisor-detached workflow children as paused and needing attention instead of failed while preserving recovery guidance (#1096).
|
|
39
|
+
- Show workflow-owned foreground children and recursive nested runs as a bounded tree in FleetView. Thanks to @expoli for #1086.
|
|
40
|
+
- Warn once, instead of on every heartbeat, when a long-running workflow child outlives its mission record. Thanks to @albertgwo for #1079.
|
|
41
|
+
- Keep deleted-schedule timers from exiting Pi and re-arm recurring schedules after unexpected timer fire failures. Thanks to @albertgwo for #1084.
|
|
42
|
+
- Count native `await` use of `runs.run`, `runs.all`, and launch-containing Promise combinators as consumed without allowing fire-and-forget launches. Thanks to @kebinzhi for #1082.
|
|
43
|
+
|
|
44
|
+
## [0.3.0] - 2026-08-14
|
|
45
|
+
|
|
46
|
+
### Changed
|
|
47
|
+
- Synced the fork with upstream pi-subagents v0.49.0 while preserving local compatibility fixes.
|
|
48
|
+
|
|
49
|
+
## [0.49.0] - 2026-08-13
|
|
50
|
+
|
|
51
|
+
### Added
|
|
52
|
+
- Run a single child with `{ agent, task? }` when a full workflow script is not needed (#1059).
|
|
53
|
+
- Adjust FleetView spacing and collapsed result height from the main window. Thanks to @pierre-mgmt for #1048.
|
|
54
|
+
- Inspect async run state with `debug.run`, without exposing prompts, secrets, or transcripts (#1037).
|
|
55
|
+
- Let builtin role overrides keep Pi's normal tools and extensions with `tools: "inherit"`. Thanks to @estanexanavsem for #1047 and @davidarny for #1049.
|
|
56
|
+
- Add simple terminal examples for FleetView, the async widget, and inline tool display. Thanks to @czottmann for #1050.
|
|
57
|
+
- Add per-tool-call wedge protection with `toolTimeoutMs` call → agent → config → environment precedence. Known-fast built-in tools get a five-minute default, long-running tools get attention notices without a hard default, matching `toolCallId` timers survive parallel tool completions, and supervisor waits (`contact_supervisor`, `intercom`, `subagent_wait`) remain exempt. Thanks to @forrestbthomas for #1077.
|
|
58
|
+
|
|
59
|
+
### Changed
|
|
60
|
+
- Clean up active-run limits and artifact packaging code without changing behavior.
|
|
61
|
+
|
|
62
|
+
### Fixed
|
|
63
|
+
- Trust live Herdr session roots only when the parent executor registered them for that async run.
|
|
64
|
+
- Let a workflow child disable the intercom bridge for one run with `intercomBridge: { mode: "off" }`, while normal async completion still works. Thanks to @jaudiger for #1072.
|
|
65
|
+
- Recover sibling children after a detached workflow fails (#1066).
|
|
66
|
+
- Show child session transcripts in standalone Herdr inspectors when the transcript is in a trusted session folder (#1069).
|
|
67
|
+
- Keep watchdog reviews, permission checks, Prompt Audit rewriting, and completion intent checks on the authenticated provider stream across the Pi 0.81 and 0.84 APIs. Thanks to @nuzayets for #1067.
|
|
68
|
+
- Mark children stopped by a parent workflow as stopped, not failed, and keep the stop reason (#1060).
|
|
69
|
+
- Keep subagent artifacts and automatic mission records out of project worktrees by default, so read-only workflows leave the tree clean (#1062).
|
|
70
|
+
- Make parents wait at dependency barriers after async launches, so child results are available before dependent work continues. Thanks to @exuanbo for #1045.
|
|
71
|
+
- Keep wait callers alive for intercom replies instead of reviving a detached wrapper. Thanks to @yayamaz for #1053.
|
|
72
|
+
- Keep workflow summary reports separate from child reports, and reject report path collisions before launch (#1038).
|
|
73
|
+
- Accept no-edit implementation challenge passes when the writer says the current solution is already best (#1054).
|
|
74
|
+
- Make the mutation guard safer for LLM intent checks, long tasks, and provider authentication. Thanks to @MarcusNeufeldt for #1044.
|
|
75
|
+
- Launch Herdr inspector panes with Node when Pi runs as a standalone executable. Thanks to @kevinpita for #1051.
|
|
76
|
+
- Sanitize async, nested, and result transcript output before showing it in terminal views. Thanks to @riesbri for #1046.
|
|
77
|
+
|
|
78
|
+
## [0.48.0] - 2026-08-13
|
|
79
|
+
|
|
80
|
+
### Added
|
|
81
|
+
- Limit each run to 64 child launches by default, so accidental fan-out loops stop before they create too many children. Thanks to @asjer for #1031.
|
|
82
|
+
- Add an optional limit for how many top-level async runs one session can have active at the same time. Fleet, status, RPC, and doctor now show the limit and current usage. Thanks to @asjer for #1029.
|
|
83
|
+
- Add a live Prompt Audit drawer to Fleet for foreground children owned by the current session. It shows the prompt on screen without saving it to status files, history, transcripts, metadata, results, progress, or run artifacts (#1021).
|
|
84
|
+
- Add a global `timeoutMs` setting for default run deadlines on foreground launches and plain single-agent async runs. It applies when a launch or agent does not set its own timeout, and it prevents long foreground fan-outs from falling back to the built-in 30-minute limit. Composite async runs stay unbounded at the top level. Thanks to @shaharmor for #1018.
|
|
85
|
+
- Add `PI_SUBAGENT_TASK_DELIVERY=auto|file` for hosts that block child processes when the task text appears in the command line. File mode writes the task to a temporary `task.md` and passes that path instead. Thanks to @yanqianglu for #1028.
|
|
86
|
+
- Retry with file-based task delivery after a child exits with no activity, which helps recover from endpoint protection tools that block long command lines. Thanks to @yanqianglu for #1028.
|
|
87
|
+
|
|
88
|
+
### Fixed
|
|
89
|
+
- Open Fleet Prompt Audit with the original task visible by default, and show a short task summary in the normal Fleet detail pane (#1021).
|
|
90
|
+
- Use the full task text when caching LLM intent decisions, so similar tasks with the same prefix cannot share the wrong answer.
|
|
91
|
+
- Stop async Pi writer processes as full process groups, and only mark process cleanup as proven after the process tree has actually exited. Thanks to @asjer for #1030.
|
|
92
|
+
- Explain when a mission belongs to another worktree, including both the current project root and the mission directory (#1024).
|
|
93
|
+
- Keep the configured output reference when explicit acceptance rejects a foreground child, so useful reports remain available (#1023).
|
|
94
|
+
- Reject worktree base directories inside the agent extensions directory, including symlinked paths (#1014).
|
|
95
|
+
- Make unnamed intercom fallback targets match pi-intercom's registered name length, so subagents without a custom session name can still reach their parent. Thanks to @mystery4f for #1017.
|
|
96
|
+
- Stop treating phrases like "must-fix items" or "should-fix tests" as instructions to edit files during read-only review tasks. Thanks to @MarcusNeufeldt for #1020.
|
|
97
|
+
- Add an optional LLM check before the mutation guard fails a foreground single, parallel, or chain child that made no edits. If the task was actually read-only, the run now completes instead of failing. Thanks to @MarcusNeufeldt for #1020.
|
|
98
|
+
- Accept empty strings inside acceptance-report string arrays instead of rejecting the full report. Thanks to @hjiang for #1015.
|
|
99
|
+
- Let single external-CLI workflow children start without inheriting a Pi model, so model-less external runners do not fail preflight. Thanks to @twosunnus for #1016.
|
|
100
|
+
|
|
5
101
|
## [0.47.1] - 2026-08-12
|
|
6
102
|
|
|
7
103
|
### Fixed
|
package/README.md
CHANGED
|
@@ -93,6 +93,8 @@ In the TUI, a persistent FleetView below the editor keeps active work visible. `
|
|
|
93
93
|
|
|
94
94
|
Details, keybindings, and the machine-readable run artifacts are in [Observability](https://github.com/nicobailon/pi-subagents/blob/main/docs/observability.md).
|
|
95
95
|
|
|
96
|
+
For bounded orchestration, `maxSubagentSpawnsPerRun` limits cumulative logical children in one run tree. It defaults to 64 and stays separate from active concurrency and the session-wide cumulative spawn budget. See [Configuration](https://github.com/nicobailon/pi-subagents/blob/main/docs/configuration.md#maxsubagentspawnsperrun).
|
|
97
|
+
|
|
96
98
|
## If something feels off
|
|
97
99
|
|
|
98
100
|
```text
|
package/agents/oracle.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
name: oracle
|
|
3
3
|
aliases: advisor
|
|
4
4
|
description: High-context decision-consistency oracle that protects inherited state and prevents drift
|
|
5
|
-
tools: read, grep, find, ls, bash
|
|
5
|
+
tools: read, grep, find, ls, bash
|
|
6
6
|
thinking: high
|
|
7
7
|
systemPromptMode: replace
|
|
8
8
|
inheritProjectContext: true
|
|
@@ -16,9 +16,11 @@ Your primary job is to prevent the main agent from making hidden, conflicting, o
|
|
|
16
16
|
|
|
17
17
|
Before you do anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. Those decisions form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
|
|
18
18
|
|
|
19
|
-
If
|
|
19
|
+
If the task is framed as asking or consulting the oracle, treat it as a live consultation unless the parent explicitly requests a one-shot report. When runtime bridge instructions provide `contact_supervisor`, ask one focused question or challenge if a material unknown, contradiction, or unapproved decision would make a final recommendation guessy. If no supervisor channel is available, return the best recommendation and name the decision that still needs the main agent.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
If you need clarification from the main agent and bridge instructions provide `contact_supervisor`, use it with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep coordination traffic tight and purposeful. Do not narrate your whole review through `contact_supervisor`.
|
|
22
|
+
|
|
23
|
+
Do not send routine completion handoffs. If no coordination is needed, or after needed coordination is answered, return the final oracle recommendation normally. If `contact_supervisor` is unavailable, return the best recommendation and name the decision that still needs the main agent. Use generic `intercom` only when an external intercom provider explicitly supplies that tool and the task identifies a safe target.
|
|
22
24
|
|
|
23
25
|
Core responsibilities:
|
|
24
26
|
- reconstruct inherited decisions, constraints, and open questions from the context
|
|
@@ -39,8 +41,8 @@ What you do not do by default:
|
|
|
39
41
|
|
|
40
42
|
Working rules:
|
|
41
43
|
- Use `bash` only for inspection, verification, or read-only analysis.
|
|
42
|
-
- If information is missing and it matters, ask the main agent with `contact_supervisor` and `reason: "need_decision"` instead of guessing.
|
|
43
|
-
- If the answer depends on a decision the main agent has not made yet, stop and ask with `contact_supervisor`
|
|
44
|
+
- If information is missing and it matters, ask the main agent with `contact_supervisor` and `reason: "need_decision"` when bridge instructions provide that tool. If no supervisor channel is available, return the best recommendation and name the unresolved decision instead of guessing.
|
|
45
|
+
- If the answer depends on a decision the main agent has not made yet, stop and ask with `contact_supervisor` when bridge instructions provide that tool. If no supervisor channel is available, mark the decision as still needed in the final recommendation.
|
|
44
46
|
- When bridge instructions are present, send concise coordination messages only when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
|
|
45
47
|
- Prefer narrow, specific corrections to the current path over rewriting the whole plan.
|
|
46
48
|
|
package/agents/researcher.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: researcher
|
|
3
3
|
description: Autonomous web researcher — searches, evaluates, and synthesizes a focused research brief
|
|
4
|
-
tools: read, write, web_search, fetch_content, get_search_content
|
|
4
|
+
tools: read, write, web_search, fetch_content, get_search_content
|
|
5
5
|
thinking: medium
|
|
6
6
|
systemPromptMode: replace
|
|
7
7
|
inheritProjectContext: true
|
package/agents/reviewer.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: reviewer
|
|
3
3
|
description: Versatile review specialist for code diffs, plans, proposed solutions, codebase health, and PR/issue validation
|
|
4
|
-
tools: read, grep, find, ls
|
|
4
|
+
tools: read, grep, find, ls
|
|
5
5
|
thinking: high
|
|
6
6
|
systemPromptMode: replace
|
|
7
7
|
inheritProjectContext: true
|
|
@@ -62,7 +62,7 @@ Review a PR or issue by understanding the context, then verifying:
|
|
|
62
62
|
## Supervisor coordination
|
|
63
63
|
If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing; no-edit wins. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally.
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
If `contact_supervisor` is unavailable, report the blocking decision in your final review. Use generic `intercom` only when an external intercom provider explicitly supplies that tool and the task identifies a safe target.
|
|
66
66
|
|
|
67
67
|
## Review output format
|
|
68
68
|
Structure your findings clearly:
|
package/agents/scout.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: scout
|
|
3
3
|
description: Fast codebase recon that returns compressed context for handoff
|
|
4
|
-
tools: read, grep, find, ls, bash, write
|
|
4
|
+
tools: read, grep, find, ls, bash, write
|
|
5
5
|
thinking: low
|
|
6
6
|
systemPromptMode: replace
|
|
7
7
|
inheritProjectContext: true
|
package/agents/worker.md
CHANGED
|
@@ -22,7 +22,7 @@ The builtin worker uses a strict tool allowlist. It does not inherit ambient ext
|
|
|
22
22
|
|
|
23
23
|
If the task is framed as an approved direction, oracle handoff, or execution plan, treat that direction as the contract. Validate it against the actual code, but do not silently make new product, architecture, or scope decisions.
|
|
24
24
|
|
|
25
|
-
If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which supervisor session to contact and how to coordinate. Use `contact_supervisor` with `reason: "need_decision"` when a new decision is needed, and stay alive to receive the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested.
|
|
25
|
+
If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which supervisor session to contact and how to coordinate. Use `contact_supervisor` with `reason: "need_decision"` when a new decision is needed, and stay alive to receive the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. If `contact_supervisor` is unavailable, stop and report the required decision in your final response. Do not finish your final response with a question that requires the supervisor to choose before you can continue.
|
|
26
26
|
|
|
27
27
|
Default responsibilities:
|
|
28
28
|
- validate the task or approved direction against the actual code
|
package/docs/agents.md
CHANGED
|
@@ -77,6 +77,7 @@ Supported override fields: `description`, `model`, `fallbackModels`, `thinking`,
|
|
|
77
77
|
|
|
78
78
|
- `description` replaces the discovered description for builtin and custom agents, which lets list output show deployment-specific routing or model metadata.
|
|
79
79
|
- Use `defaultContext: false` or `acceptanceRole: false` to clear an inherited override.
|
|
80
|
+
- Use `tools: "inherit"` on a builtin when that one role should omit its bundled tool allowlist and receive Pi's normal builtins and ambient extensions. This keeps strict tools as the default for other builtins.
|
|
80
81
|
- Project overrides beat user overrides.
|
|
81
82
|
- Matching user and project agents also receive override fields that their frontmatter leaves unset, so a shared project config agent can keep the persona while local settings choose the model.
|
|
82
83
|
|
|
@@ -132,6 +133,7 @@ defaultReads: context.md
|
|
|
132
133
|
defaultProgress: true
|
|
133
134
|
async: true
|
|
134
135
|
timeoutMs: 900000
|
|
136
|
+
toolTimeoutMs: 600000
|
|
135
137
|
turnBudget: {"maxTurns":20,"graceTurns":2}
|
|
136
138
|
acceptance: {"level":"none","reason":"lightweight lookup"}
|
|
137
139
|
acceptanceRole: read-only
|
|
@@ -177,6 +179,7 @@ Field notes:
|
|
|
177
179
|
| `defaultProgress` | Maintain `progress.md`. |
|
|
178
180
|
| `async` | Default a single-agent launch to background (`true`) or foreground (`false`) when the call omits `async`. Explicit call values and `forceTopLevelAsync` win. |
|
|
179
181
|
| `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. |
|
|
182
|
+
| `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 `subagent_wait` are exempt. |
|
|
180
183
|
| `turnBudget` | JSON object default such as `{"maxTurns":20,"graceTurns":2}` for single-agent launches. An explicit call value wins, followed by this agent default, then global `turnBudget` config. |
|
|
181
184
|
| `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. |
|
|
182
185
|
| `acceptanceRole` | Optional `read-only` or `writer` role for automatic acceptance inference. Explicit task mutation or no-edit intent wins; otherwise the declared role replaces agent-name guessing. This does not grant or revoke tools. |
|
package/docs/configuration.md
CHANGED
|
@@ -44,6 +44,61 @@ Defaults to `false`. The default registered model-facing tool schema and descrip
|
|
|
44
44
|
|
|
45
45
|
Controls the `subagent` tool result shown inline in chat. The default, `"rich"`, shows live child activity and expands to detailed output. `"summary"` keeps the inline result at one stable row for running, completed, failed, stopped, and paused runs; it does not animate, show elapsed time, preview child output, or change when Pi's expand key is pressed. FleetView remains available for live progress and detailed inspection.
|
|
46
46
|
|
|
47
|
+
## `mainWindowRenderer`
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"mainWindowRenderer": {
|
|
52
|
+
"horizontalSpacing": 0,
|
|
53
|
+
"compactResultMaxLines": 4
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Controls only the main chat `subagent` call/result renderer. It does not change child execution, orchestration, FleetView, artifacts, transcripts, or model-facing content.
|
|
59
|
+
|
|
60
|
+
`horizontalSpacing` is an integer from `0` to `4`. The default preserves current spacing. Set it to `0` to remove the extra spaces before compact result details and between parts of the call row.
|
|
61
|
+
|
|
62
|
+
`compactResultMaxLines` is a positive integer. It caps only collapsed rich-result rows and adds an expand hint when rows are hidden. Expanded output remains uncapped.
|
|
63
|
+
|
|
64
|
+
With `"summary"`, a tool result looks like this:
|
|
65
|
+
|
|
66
|
+
```text
|
|
67
|
+
✓ reviewer · completed
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## `foregroundDetachShortcut`
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{ "foregroundDetachShortcut": "ctrl+b" }
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Optionally binds a shortcut that detaches the active foreground single-subagent run without terminating it. The running foreground card shows the configured shortcut beside its live-detail hint. The default is unset, so pi-subagents does not reserve a global key.
|
|
77
|
+
|
|
78
|
+
Pi binds `Ctrl+B` to editor cursor-left by default. The extension shortcut takes precedence, but Pi reports the conflict at startup. To reserve the key without that warning, override the editor action in `~/.pi/agent/keybindings.json`:
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"tui.editor.cursorLeft": "left"
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## `orcaProgressTabs` (experimental)
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"orcaProgressTabs": {
|
|
91
|
+
"enabled": true
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Opt in to a best-effort Orca observer that creates one Orca terminal tab for each subagent child and mirrors its live tool, assistant, stdout, and stderr progress. Tab titles use a persistent worktree-local sequence (`subagent · <agent> · 1`, `... · 2`, and so on), so separate workflows and concurrent children do not reuse the same number. This does **not** replace Pi as the child runner: native Pi children keep the same process, lifecycle, status, control, artifact, and result paths. External CLI profiles also keep their existing runner and can mirror their stdout/stderr.
|
|
97
|
+
|
|
98
|
+
The integration is off by default and supports macOS and Linux. It is disabled on Windows. When enabled, `pi-subagents` looks for executable `orca` on `PATH`, or uses the executable path in `PI_SUBAGENT_ORCA_BINARY`. If no executable is available, Orca is not running, the cwd is not an Orca-managed worktree, or `terminal create` fails, the authoritative subagent still runs normally. Tab creation is deliberately best-effort and never changes the child result.
|
|
99
|
+
|
|
100
|
+
Set `enabled` to `false` (or remove the block) as a kill switch. In that state, `pi-subagents` does not invoke `orca` and creates no Orca tabs. The temporary mirror files contain child output, use private file modes where supported, and are removed shortly after the child finishes. Each mirror is capped at 1 MiB. The observer stops accepting progress when the cap or stream backpressure is reached and appends a truncation notice. The viewer removes terminal control sequences with parser state that persists across file reads. On completion, the viewer exits back to the Orca terminal's shell prompt; the tab and its terminal scrollback remain open until the user closes the tab. A successfully completed native Pi child with a recorded session ends with a safely quoted `rm -- <exact-session-path>` command; failed, stopped, timed-out, and sessionless children do not show the removal command.
|
|
101
|
+
|
|
47
102
|
## `asyncByDefault`
|
|
48
103
|
|
|
49
104
|
```json
|
|
@@ -115,6 +170,30 @@ This is different from `waitTool.enabled=false`, which returns immediately witho
|
|
|
115
170
|
|
|
116
171
|
Forces depth-0 internal single, parallel, and chain runs into background mode and bypasses launch UI by forcing `clarify: false`. Nested calls keep their own inherited settings.
|
|
117
172
|
|
|
173
|
+
## `timeoutMs`
|
|
174
|
+
|
|
175
|
+
```json
|
|
176
|
+
{ "timeoutMs": 3600000 }
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Global default runtime deadline, in milliseconds, for subagent runs. It replaces the built-in 30-minute backstop for foreground launches (single, parallel, chain, and workflowScript) 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*.
|
|
180
|
+
|
|
181
|
+
Use it when foreground orchestration or plain async single-agent runs need a longer default than 30 minutes. It does not set async composite top-level deadlines, and it does not replace async fan-out child deadlines.
|
|
182
|
+
|
|
183
|
+
Composite async runs (async chains, parallel tasks, and scripted workflows) stay unbounded at the top level by design. Their runner children are bounded individually by their own agent or runner defaults, so this value does not cap them. Must be a positive integer no greater than `2147483647` (the largest delay a Node.js timer can honor, roughly 24.8 days); invalid or out-of-range values are ignored and the built-in defaults apply.
|
|
184
|
+
|
|
185
|
+
## `toolTimeoutMs`
|
|
186
|
+
|
|
187
|
+
```json
|
|
188
|
+
{ "toolTimeoutMs": 600000 }
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
Optional hard per-tool-call deadline in milliseconds. When configured, a child that emits `tool_execution_start` but not `tool_execution_end` is terminated with `timedOut: true` and a tool-specific error. The effective value is resolved per child: explicit `subagent` call value, then agent frontmatter, then this config value, then `PI_SUBAGENT_TOOL_TIMEOUT_MS`.
|
|
192
|
+
|
|
193
|
+
Without a configured value, Pi still applies a five-minute hard timeout to known-fast built-in tools: `read`, `grep`, `find`, `ls`, `edit`, `write`, and `structured_output`. Long-running tools such as `bash`, custom tools, and MCP tools do not get a hard default. They get the normal open-tool attention notice after `activeNoticeAfterMs` and remain bounded by the run-level deadline.
|
|
194
|
+
|
|
195
|
+
The tool timer tracks each active `toolCallId` separately and never extends the run-level deadline: when the remaining run budget is shorter, the ordinary run-level timeout wins. `contact_supervisor`, `intercom`, and `subagent_wait` are exempt because their legitimate purpose can be to wait for a human, supervisor, or child run. Use hard tool timeouts only for wedge protection; an elapsed timeout is not a mutation-safe boundary. Configured values must be positive integers no greater than `2147483647`; invalid or out-of-range values are rejected with a visible error rather than silently ignored.
|
|
196
|
+
|
|
118
197
|
## `globalConcurrencyLimit`
|
|
119
198
|
|
|
120
199
|
```json
|
|
@@ -131,9 +210,31 @@ Caps simultaneously running children inside existing durable legacy multi-child
|
|
|
131
210
|
|
|
132
211
|
Optionally caps the total number of child subagent launches during one parent session, including completed and failed children, parallel task counts, static chain steps, and bounded dynamic fanout children. Sessions are unlimited by default. Set this value to `0` to disable a configured cap. `PI_SUBAGENT_MAX_SPAWNS_PER_SESSION` overrides the config for a process and follows the same positive-cap/zero-unlimited semantics.
|
|
133
212
|
|
|
134
|
-
`subagent({ action: "status" })`, fleet status, and `subagent({ action: "doctor" })` expose used, effective limit, remaining capacity, grants, and the remaining grant allowance.
|
|
213
|
+
`subagent({ action: "status" })`, fleet status, and `subagent({ action: "doctor" })` expose used, effective limit, remaining capacity, grants, and the remaining grant allowance for this budget. A user may explicitly call `subagent({ action: "grant-spawn-budget", additional: 10 })` from the root interactive parent after all children settle and confirm the native prompt. Grants are additive: they never erase cumulative usage, are rejected for unlimited sessions and child/headless callers, and total granted capacity cannot exceed the original configured cap. Compaction remains part of the same logical parent session and does not reset usage or grants; starting a new parent session does.
|
|
214
|
+
|
|
215
|
+
## `maxSubagentSpawnsPerRun`
|
|
135
216
|
|
|
136
|
-
|
|
217
|
+
```json
|
|
218
|
+
{ "maxSubagentSpawnsPerRun": 64 }
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Caps cumulative logical child admissions in one top-level run tree. The default is `64`. `PI_SUBAGENT_MAX_SPAWNS_PER_RUN` overrides the config when it is a positive integer. Invalid, zero, or missing values fall back to the configured positive value or `64`.
|
|
222
|
+
|
|
223
|
+
The budget counts single launches, expanded `tasks`/`count`, static chain steps and parallel groups, actual dynamic `expand` items, appended chain steps, workflow children, and nested child calls. Static and materialized dynamic groups are admitted atomically. Startup retries, model fallback, and retained-child resume reuse the original logical child claim. Claims are never released or refunded. This cap is independent from the session-wide cumulative spawn budget and `globalConcurrencyLimit`.
|
|
224
|
+
|
|
225
|
+
## `maxActiveAsyncRunsPerSession`
|
|
226
|
+
|
|
227
|
+
```json
|
|
228
|
+
{ "maxActiveAsyncRunsPerSession": 4 }
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
Optionally caps concurrently active top-level async runs owned by one parent session. Unset or `0` keeps the existing unlimited behavior. A positive integer reserves one slot before an async single, parallel, chain, or workflow creates run artifacts or starts children. Foreground runs and nested/workflow children do not reserve another slot.
|
|
232
|
+
|
|
233
|
+
Queued, running, paused, and needs-attention runs retain capacity. Runner-backed slots release only after terminal logical state and matching observed process-terminal proof from #1030. Missing, malformed, or unknown cleanup proof retains the slot. A terminal async workflow releases after its controller is gone and every launched child is accounted for: awaited foreground children are covered by workflow settlement, while actual background children still require observed process-terminal proof. Resume transfers the source slot without a second charge. Dismissal and history cleanup do not release capacity.
|
|
234
|
+
|
|
235
|
+
This limit bounds current top-level async load. It is separate from cumulative `maxSubagentSpawnsPerSession`, `maxSubagentSpawnsPerRun`, and `globalConcurrencyLimit`.
|
|
236
|
+
|
|
237
|
+
`subagent({ action: "status" })`, fleet status, and `subagent({ action: "doctor" })` expose used, effective limit, and remaining active capacity. Static chains and parallel calls fail before creating run artifacts or starting partial work when their declared capacity cannot fit. Later retries or unbounded dynamic work are not guaranteed by that preflight.
|
|
137
238
|
|
|
138
239
|
## `scheduledRuns`
|
|
139
240
|
|
|
@@ -196,6 +297,16 @@ export PI_SUBAGENT_PI_BINARY=/path/to/pi-or-wrapper
|
|
|
196
297
|
|
|
197
298
|
Overrides the command used to launch child Pi processes. Package wrappers can set this to their own `pi`/agent binary so subagents inherit wrapper flags, environment setup, and bundled resources without relying on `PATH` ordering. Empty or whitespace-only values are ignored.
|
|
198
299
|
|
|
300
|
+
## `PI_SUBAGENT_TASK_DELIVERY`
|
|
301
|
+
|
|
302
|
+
```bash
|
|
303
|
+
export PI_SUBAGENT_TASK_DELIVERY=file # auto | file (default: auto)
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
Controls how the task text reaches the child Pi process. `auto` (default) passes short tasks as an inline argv token and writes tasks longer than 8000 characters to a temp `task.md` referenced as `@<path>`. `file` always uses a temp file, keeping the task out of argv entirely.
|
|
307
|
+
|
|
308
|
+
Use `file` on hosts where endpoint protection (EDR) pre-execution scanning denies child processes whose command line embeds a long natural-language task — that denial surfaces as an immediate zero-activity `SIGKILL`. Independently of this setting, startup retries automatically escalate to file delivery after an unexplained zero-activity `SIGKILL`. Empty, whitespace-only, or unrecognized values fall back to `auto`.
|
|
309
|
+
|
|
199
310
|
## `intercomBridge`
|
|
200
311
|
|
|
201
312
|
```json
|
|
@@ -208,7 +319,7 @@ Overrides the command used to launch child Pi processes. Package wrappers can se
|
|
|
208
319
|
}
|
|
209
320
|
```
|
|
210
321
|
|
|
211
|
-
Controls whether subagents receive runtime
|
|
322
|
+
Controls whether subagents receive runtime coordination instructions and whether `contact_supervisor` is auto-added to their tool allowlist when needed.
|
|
212
323
|
|
|
213
324
|
Fields:
|
|
214
325
|
|
|
@@ -216,9 +327,9 @@ Fields:
|
|
|
216
327
|
- `instructionFile`: optional Markdown template replacing the default bridge instructions. `{orchestratorTarget}` is interpolated. Relative paths resolve from `~/.pi/agent/extensions/subagent/`.
|
|
217
328
|
- `resultDelivery`: default `false`; set `true` only when an external listener consumes `subagent:result-intercom` and acknowledges the grouped completion payload. This is optional external result delivery, not native supervisor messaging. Enabled delivery waits for acknowledgement and reports acknowledgement failures. It does not change supervisor asks or progress updates.
|
|
218
329
|
|
|
219
|
-
Bridge activation requires a targetable current parent session id, which `pi-subagents` passes to children automatically. Native supervisor messaging does not require an external `pi-intercom` installation or per-agent extension allowlists: children use `contact_supervisor`, and parents use `subagent_supervisor` to inspect or reply.
|
|
330
|
+
Bridge activation requires a targetable current parent session id, which `pi-subagents` passes to children automatically. Native supervisor messaging does not require an external `pi-intercom` installation or per-agent extension allowlists: children use `contact_supervisor`, and parents use `subagent_supervisor` to inspect or reply. Agents can still use an external `intercom` tool when they explicitly request a provider that supplies it.
|
|
220
331
|
|
|
221
|
-
The default injected guidance tells children to use `contact_supervisor` with `reason: "need_decision"` when blocked or needing a decision, `reason: "progress_update"` only for meaningful blocked/progress updates,
|
|
332
|
+
The default injected guidance tells children to use `contact_supervisor` with `reason: "need_decision"` when blocked or needing a decision, `reason: "progress_update"` only for meaningful blocked/progress updates, and avoid routine completion handoffs.
|
|
222
333
|
|
|
223
334
|
## `worktreeBaseDir`
|
|
224
335
|
|
|
@@ -253,7 +364,6 @@ stdin is a JSON object with `repoRoot`, `worktreePath`, `agentCwd`, `branch`, `i
|
|
|
253
364
|
{
|
|
254
365
|
"missions": {
|
|
255
366
|
"enabled": true,
|
|
256
|
-
"directory": ".pi/subagents/missions",
|
|
257
367
|
"globalIndex": true,
|
|
258
368
|
"retainTerminal": 200
|
|
259
369
|
}
|
|
@@ -262,7 +372,8 @@ stdin is a JSON object with `repoRoot`, `worktreePath`, `agentCwd`, `branch`, `i
|
|
|
262
372
|
|
|
263
373
|
Automatic missions are enabled by default for ordinary launches with a task. Use per-launch `mission: false` for intentionally ephemeral work, or set `enabled: false` to disable automatic creation globally; explicit mission actions and `missionId`/`mission` launch fields still work.
|
|
264
374
|
|
|
265
|
-
-
|
|
375
|
+
- Mission records default to a project-keyed directory under pi's agent directory (`~/.pi/agent/missions/projects/<project-hash>/`). This keeps the project worktree clean.
|
|
376
|
+
- `directory` may be absolute, `~/...`, or project-relative. Set it to `.pi/subagents/missions` to opt in to project-scoped records.
|
|
266
377
|
- `retainTerminal` is a positive count (default `200`); pruning removes only the oldest completed, failed, or cancelled records and their pointers, never planned, active, waiting, needs-decision, or corrupt records.
|
|
267
378
|
- The user-global index contains pointers only; missing-record pointers self-heal when globally listed. Set `globalIndex: false` to disable writes or `globalIndexDir` to redirect it.
|
|
268
379
|
|
|
@@ -291,11 +402,11 @@ Each fixed action resolves to `"auto"`, `"confirm"`, or `"forbid"`. This is inte
|
|
|
291
402
|
|
|
292
403
|
Controls where subagent artifact files (inputs, outputs, transcripts, metadata) are stored:
|
|
293
404
|
|
|
294
|
-
- `"project"
|
|
295
|
-
- `"session"
|
|
405
|
+
- `"project"`: writes to `<cwd>/.pi/subagents/artifacts/`.
|
|
406
|
+
- `"session"` (default): stores artifacts under pi's session directory (`~/.pi/agent/sessions/<session>/subagent-artifacts/`), keeping the working directory clean. It falls back to the OS temp directory when no session file exists.
|
|
296
407
|
- `"temp"`: uses the OS temp directory.
|
|
297
408
|
|
|
298
|
-
This preference also controls the default chain scratch directory. `"project"` uses `<cwd>/.pi/subagents/chain-runs/`, while `"session"` and `"temp"` use the user-scoped temp chain directory.
|
|
409
|
+
This preference also controls the default chain scratch directory. `"project"` uses `<cwd>/.pi/subagents/chain-runs/`, while the default `"session"` and `"temp"` use the user-scoped temp chain directory.
|
|
299
410
|
|
|
300
411
|
The `"session"` option uses the same directory that `cleanupAllArtifactDirs` already scans for age-based cleanup, so artifacts are still cleaned up automatically. Temporary chain directories are cleaned up separately after 24 hours.
|
|
301
412
|
|
package/docs/extension-api.md
CHANGED
|
@@ -56,6 +56,42 @@ The DTO intentionally never exposes run, async, or tool IDs. Clients must ignore
|
|
|
56
56
|
|
|
57
57
|
`pi.events` is in-process only. It does not reach separate Pi processes or child subagents; use the file lifecycle artifacts or `pi-intercom` for cross-process coordination.
|
|
58
58
|
|
|
59
|
+
## External jobs in FleetView
|
|
60
|
+
|
|
61
|
+
Use `pi-subagents/external-runs` to publish display-only current-session jobs owned by another extension:
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
import {
|
|
65
|
+
registerExternalRun,
|
|
66
|
+
updateExternalRun,
|
|
67
|
+
unregisterExternalRun,
|
|
68
|
+
} from "pi-subagents/external-runs";
|
|
69
|
+
|
|
70
|
+
registerExternalRun({
|
|
71
|
+
id: "dependency-review",
|
|
72
|
+
sessionId: ctx.sessionManager.getSessionId(),
|
|
73
|
+
source: "interactive-shell",
|
|
74
|
+
label: "Dependency review",
|
|
75
|
+
state: "running",
|
|
76
|
+
startedAt: Date.now(),
|
|
77
|
+
currentAction: "Inspecting package metadata",
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
updateExternalRun(ctx.sessionManager.getSessionId(), "dependency-review", {
|
|
81
|
+
state: "completed",
|
|
82
|
+
updatedAt: Date.now(),
|
|
83
|
+
endedAt: Date.now(),
|
|
84
|
+
preview: "No dependency blockers found.",
|
|
85
|
+
reportPath: "/tmp/dependency-review.md",
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
unregisterExternalRun(ctx.sessionManager.getSessionId(), "dependency-review");
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The API validates and caches bounded display fields when the caller registers or updates a job. FleetView reads that cache only. It does not poll caller code. `snapshotExternalRuns(sessionId)` and `listExternalRuns(sessionId)` return bounded current-session snapshots. By default, malformed cached records throw with the validation error. Display-only Fleet callers can pass `{ ignoreMalformed: true, onMalformedRecord }` to remove bad records and keep rendering with a programmatic diagnostic.
|
|
92
|
+
|
|
93
|
+
External jobs are observational. The caller owns execution, persistence, cancellation, and result delivery. FleetView does not expose stop, steer, resume, cancel, or Herdr controls for them. Supplied report and transcript paths are shown as bounded text only; FleetView does not read arbitrary external paths.
|
|
94
|
+
|
|
59
95
|
## Launch contract preflight
|
|
60
96
|
|
|
61
97
|
Use `@xzzpig/pi-subagents/preflight` when an extension needs to inspect the resolved child launch contract before deciding whether to run anything:
|
package/docs/missions.md
CHANGED
|
@@ -11,7 +11,9 @@ Missions are durable wrappers around runs. The noun map:
|
|
|
11
11
|
- **Run** — one actual subagent execution.
|
|
12
12
|
- **Receipt** — proof or a link for an external outcome, such as a PR, CI check, deployment, or release.
|
|
13
13
|
|
|
14
|
-
Ordinary workflow launches create one enclosing mission by default, with detailed JSON records under
|
|
14
|
+
Ordinary workflow launches create one enclosing mission by default, with detailed JSON records under `~/.pi/agent/missions/projects/<project-hash>/` linking objectives, run ids, lifecycle status, decisions, artifact paths, and delivery receipts. Workflow children do not create separate missions. Each workflow child attempt is stored in the enclosing mission with its stable workflow key, run id when known, agent, task metadata, timestamps, session and artifact paths, and latest status heartbeat.
|
|
15
|
+
|
|
16
|
+
Records created under the old default `<project>/.pi/subagents/missions` stay on disk. Continue them by setting `missions.directory` to that path for the project or by copying the record into the new agent-dir project store. There is no automatic migration.
|
|
15
17
|
|
|
16
18
|
Behavior:
|
|
17
19
|
|
|
@@ -19,7 +21,7 @@ Behavior:
|
|
|
19
21
|
- Human receipts end with `Mission: <id> (<status>)`, while JSON/structured output text stays unchanged and `details.missionId` is authoritative.
|
|
20
22
|
- Pass `mission: false` for an intentionally ephemeral workflow. It creates no mission for the workflow or its children and has no `state` global.
|
|
21
23
|
- Set `missions.enabled: false` to disable automatic mission creation; explicit mission fields and actions still work.
|
|
22
|
-
- A workflow with a mission can use `await state.get(key)` and `await state.set(key, value)` for durable JSON state. Missing keys return `undefined`. Keys use the same format as `runs.run` keys. Each set takes the state-file lock, reads the latest file, merges the key, and atomically writes `<
|
|
24
|
+
- A workflow with a mission can use `await state.get(key)` and `await state.set(key, value)` for durable JSON state. Missing keys return `undefined`. Keys use the same format as `runs.run` keys. Each set takes the state-file lock, reads the latest file, merges the key, and atomically writes `<mission-directory>/<mission-id>/state.json`. The complete file cannot exceed 256 KiB. Each workflow caches the file on its first `get`. A `mission:false` workflow has no `state` global.
|
|
23
25
|
|
|
24
26
|
An explicit `mission` object must have exactly one non-empty `title` or `summary`. `objective` and `labels` are optional. When supplied, `goal` must be `true` and requires `budget: { tokens: <positive integer> }`.
|
|
25
27
|
|
|
@@ -56,7 +58,7 @@ subagent({
|
|
|
56
58
|
})
|
|
57
59
|
```
|
|
58
60
|
|
|
59
|
-
After each parent turn, an idle goal mission sends one needs-attention notice with its title, remaining token budget, and next ready action. The action comes from `state.nextReadyAction`, `state.nextAction`, a state item with `status: "ready"`, an open decision, or linked-run state. A workflow can write `state.nextReadyAction` to tell the next notice exactly what work is ready. When the latest linked workflow has a
|
|
61
|
+
After each parent turn, an idle goal mission sends one needs-attention notice with its title, remaining token budget, and next ready action. The action comes from `state.nextReadyAction`, `state.nextAction`, a state item with `status: "ready"`, an open decision, or linked-run state. A workflow can write `state.nextReadyAction` to tell the next notice exactly what work is ready. When the latest linked workflow has a resumable retained child, the notice names that child as the `resume` target. Non-resumable retained children stay visible in `children.list` with their reason, but goal notices do not present them as resume targets. The extension never launches or replans goal work by itself.
|
|
60
62
|
|
|
61
63
|
Linked-run token totals are stored on each run and folded into mission `usage`. An active linked run suppresses notices. Reaching the token budget changes the goal status to `budget-exhausted` and stops notices without closing the mission or reporting success.
|
|
62
64
|
|
package/docs/observability.md
CHANGED
|
@@ -4,7 +4,7 @@ Where running subagents show up, how to inspect them, and the files and events t
|
|
|
4
4
|
|
|
5
5
|
## Foreground runs
|
|
6
6
|
|
|
7
|
-
Foreground runs stream progress in the conversation while they run. They default to a generous 30-minute wall-clock timeout when neither the call nor the selected agent provides a timeout; explicit `timeoutMs`/`maxRuntimeMs` and agent defaults win.
|
|
7
|
+
Foreground runs stream progress in the conversation while they run. They default to a generous 30-minute wall-clock timeout when neither the call nor the selected agent provides a timeout; a global [`timeoutMs`](configuration.md#timeoutms) config replaces that default, and explicit `timeoutMs`/`maxRuntimeMs` and agent defaults win.
|
|
8
8
|
|
|
9
9
|
Live progress shows compact detail for single, chain, and parallel modes: current tool, recent output, token counts, aggregate cost, duration, activity freshness, current-tool duration, and chain graph metadata when available.
|
|
10
10
|
|
|
@@ -23,13 +23,37 @@ subagent({ action: "status", id: "..." }) // one run
|
|
|
23
23
|
|
|
24
24
|
Or ask naturally: "Show me the current async runs."
|
|
25
25
|
|
|
26
|
+
The under-editor async widget gives a short view while work runs. Its expand key follows your Pi keybinding:
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
async subagent worker · background
|
|
30
|
+
● worker
|
|
31
|
+
● Step 1/1: worker · running
|
|
32
|
+
⎿ read: src/auth.ts | 2.0s
|
|
33
|
+
Press configured-expand-key for live detail
|
|
34
|
+
```
|
|
35
|
+
|
|
26
36
|
To inspect one background child in text, use `subagent({ action: "status", id: "...", view: "transcript" })`; add `index` for a specific child in a parallel or chain run.
|
|
27
37
|
|
|
28
38
|
## FleetView
|
|
29
39
|
|
|
30
40
|
In the TUI, a persistent FleetView below the editor keeps active work visible as a compact summary. Set `fleetViewPlacement` to `"aboveEditor"` to move it above the editor.
|
|
31
41
|
|
|
32
|
-
|
|
42
|
+
```text
|
|
43
|
+
2 active agents · ↓ 4.2k tokens · ↓/← to inspect
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
After you expand it:
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
↑↓/jk select · enter inspect · esc back
|
|
50
|
+
|
|
51
|
+
> main
|
|
52
|
+
scout · running 1m 12s · ↓ 2.8k tokens
|
|
53
|
+
reviewer · running 38s · ↓ 1.4k tokens
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
When the focused editor is empty, press `↓` or `←` to expand the summary into `main` plus active children with agent name, state, elapsed time, and token totals. Then use `↑`/`↓` or `j`/`k` to select a child and `Enter` to inspect it. Printable navigation keys are never intercepted before activation.
|
|
33
57
|
|
|
34
58
|
FleetView replaces the legacy above-editor async widget by default. Successful background completions stay quiet so inactive Pi tabs are not marked unread, while failed or paused completions still notify the originating session. Parallel runs show every active child independently. Chains with parallel groups keep their grouped shape in progress and results, so failed or paused agents stay visible next to completed ones. When a child is explicitly allowed to fan out with `tools: subagent`, its nested runs appear under that parent child in the main status tree instead of being hidden inside the child process.
|
|
35
59
|
|
|
@@ -57,6 +81,22 @@ Without a TUI, `/subagents-fleet` retains the textual `subagent({ action: "statu
|
|
|
57
81
|
|
|
58
82
|
Use `/subagents-detach [run-id]` only for an active foreground single-subagent run you want to leave running without terminating; the eventual result remains available through status/wait.
|
|
59
83
|
|
|
84
|
+
Set `foregroundDetachShortcut` in `~/.pi/agent/extensions/subagent/config.json` to bind the same action to a shortcut. The running foreground card shows the configured shortcut beside its live-detail hint:
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"foregroundDetachShortcut": "ctrl+b"
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Pi binds `Ctrl+B` to editor cursor-left by default. The extension shortcut takes precedence, but Pi reports the conflict at startup. To reserve the key without that warning, override the editor action in `~/.pi/agent/keybindings.json`:
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"tui.editor.cursorLeft": "left"
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
60
100
|
If something feels misconfigured, run `/subagents-doctor` or ask: "Check whether subagents and intercom are set up correctly."
|
|
61
101
|
|
|
62
102
|
## Async run artifacts
|
|
@@ -126,7 +166,7 @@ Foreground and async runners share bounded child-protocol handling:
|
|
|
126
166
|
|
|
127
167
|
## Chain and debug artifacts
|
|
128
168
|
|
|
129
|
-
Each chain run creates a scratch directory under its resolved chain root. With the default `artifactDir: "
|
|
169
|
+
Each chain run creates a scratch directory under its resolved chain root. With the default `artifactDir: "session"` or with `"temp"`, it is user-scoped temp storage. With `artifactDir: "project"`, the root is `<cwd>/.pi/subagents/chain-runs/`:
|
|
130
170
|
|
|
131
171
|
```text
|
|
132
172
|
<tmpdir>/pi-subagents-<scope>/chain-runs/{runId}/
|