@xzzpig/pi-subagents 0.22.0 → 0.24.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +355 -0
- package/README.md +2 -2
- package/agents/evidence-auditor.md +1 -0
- package/agents/oracle.md +1 -0
- package/agents/reviewer.md +1 -0
- package/bundle/agent-management.js +16 -0
- package/bundle/agents.js +41 -0
- package/bundle/background-work.js +16 -0
- package/bundle/capability-ceiling.js +22 -0
- package/bundle/child-tool-plan.js +11 -0
- package/bundle/chunk-355ECEP2.js +1321 -0
- package/bundle/chunk-35GII5EF.js +637 -0
- package/bundle/chunk-3U633XDZ.js +749 -0
- package/bundle/chunk-4QFZZV3O.js +57 -0
- package/bundle/chunk-62OCY2S4.js +14 -0
- package/bundle/chunk-6BJUEES3.js +276 -0
- package/bundle/chunk-7J4ZXMY7.js +18 -0
- package/bundle/chunk-BGIYHF2W.js +138 -0
- package/bundle/chunk-CTPAE36Y.js +94 -0
- package/bundle/chunk-D4EHT5SJ.js +14 -0
- package/bundle/chunk-ED55MIC2.js +1681 -0
- package/bundle/chunk-EUPJB4S7.js +5503 -0
- package/bundle/chunk-FG6SQJAR.js +940 -0
- package/bundle/chunk-FJWI64H7.js +490 -0
- package/bundle/chunk-H36HBZB2.js +753 -0
- package/bundle/chunk-ICNYIALB.js +7347 -0
- package/bundle/chunk-JEA2ZKUA.js +1372 -0
- package/bundle/chunk-LCDJWBVM.js +57 -0
- package/bundle/chunk-LMGQAJ3O.js +9872 -0
- package/bundle/chunk-LVWU2HOO.js +1234 -0
- package/bundle/chunk-NIXWDZZV.js +9 -0
- package/bundle/chunk-QXASAHIA.js +173 -0
- package/bundle/chunk-RB4GELQA.js +458 -0
- package/bundle/chunk-RU522D5W.js +1768 -0
- package/bundle/chunk-SLNMBXLL.js +7336 -0
- package/bundle/chunk-SW2VMNIU.js +526 -0
- package/bundle/chunk-TGLFTQWJ.js +143 -0
- package/bundle/chunk-TMHVDPYW.js +4132 -0
- package/bundle/chunk-U4ODUYAG.js +235 -0
- package/bundle/chunk-UKG4V45O.js +228 -0
- package/bundle/chunk-UQDHXMUG.js +264 -0
- package/bundle/chunk-V2KFIGFH.js +8774 -0
- package/bundle/chunk-VO3G7HI3.js +85 -0
- package/bundle/chunk-WPW4V6HM.js +227 -0
- package/bundle/chunk-WW76JRIX.js +175 -0
- package/bundle/chunk-X6LOM3Z4.js +4175 -0
- package/bundle/chunk-XA3DY6UG.js +161 -0
- package/bundle/chunk-Y6H2G6KX.js +1310 -0
- package/bundle/chunk-YFCK7H2S.js +129 -0
- package/bundle/chunk-YYREO77V.js +137 -0
- package/bundle/chunk-Z6TFJ6BR.js +400 -0
- package/bundle/chunk-ZWXU5SPQ.js +16932 -0
- package/bundle/control-channel.js +11 -0
- package/bundle/delegation.js +14 -0
- package/bundle/external-job-provider.js +20 -0
- package/bundle/external-runs.js +21 -0
- package/bundle/index.js +30 -0
- package/bundle/inspectors.js +8 -0
- package/bundle/intercom-bridge.js +11 -0
- package/bundle/preflight.js +468 -0
- package/bundle/project-panes.js +28 -0
- package/bundle/required-child-extensions.js +6 -0
- package/bundle/shared-types.js +8 -0
- package/bundle/supervisor-routing.js +12 -0
- package/bundle/workflow-resources.js +7 -0
- package/docs/agents.md +42 -10
- package/docs/configuration.md +59 -14
- package/docs/extension-api.md +61 -9
- package/docs/goal-auto-continuation-gate.md +26 -0
- package/docs/missions.md +2 -0
- package/docs/observability.md +20 -5
- package/docs/standalone-background.md +8 -6
- package/docs/tool-reference.md +18 -5
- package/docs/workflows.md +25 -7
- package/index.d.ts +3 -0
- package/index.js +14 -0
- package/node_modules/@xzzpig/pi-components/package.json +1 -2
- package/package.json +107 -87
- package/skills/council-mode/SKILL.md +1 -4
- package/skills/pi-subagents/SKILL.md +130 -106
- package/skills/pi-subagents/references/orchestration.md +124 -0
- package/skills/pi-subagents/references/prompting-and-roles.md +96 -291
- package/src/agents/advertised-agent-prompt.d.ts +13 -0
- package/src/agents/advertised-agent-prompt.js +68 -0
- package/src/agents/agent-eject.d.ts +39 -0
- package/src/agents/agent-eject.js +263 -0
- package/src/agents/agent-management.d.ts +33 -0
- package/src/agents/agent-management.js +1541 -0
- package/src/agents/agent-memory.d.ts +48 -0
- package/src/agents/agent-memory.js +350 -0
- package/src/agents/agent-refinements.d.ts +99 -0
- package/src/agents/agent-refinements.js +568 -0
- package/src/agents/agent-scope.d.ts +3 -0
- package/src/agents/agent-scope.js +8 -0
- package/src/agents/agent-selection.d.ts +2 -0
- package/src/agents/agent-selection.js +22 -0
- package/src/agents/agent-serializer.d.ts +7 -0
- package/src/agents/agent-serializer.js +213 -0
- package/src/agents/agents.d.ts +352 -0
- package/src/agents/agents.js +2817 -0
- package/src/agents/builtin-names.d.ts +1 -0
- package/src/agents/builtin-names.js +16 -0
- package/src/agents/chain-serializer.d.ts +6 -0
- package/src/agents/chain-serializer.js +318 -0
- package/src/agents/frontmatter.d.ts +19 -0
- package/src/agents/frontmatter.js +166 -0
- package/src/agents/global-npm-root.d.ts +6 -0
- package/src/agents/global-npm-root.js +57 -0
- package/src/agents/identity.d.ts +7 -0
- package/src/agents/identity.js +29 -0
- package/src/agents/proactive-skills.d.ts +35 -0
- package/src/agents/proactive-skills.js +155 -0
- package/src/agents/runtime-agent-events.d.ts +26 -0
- package/src/agents/runtime-agent-events.js +52 -0
- package/src/agents/runtime-agent-registry.d.ts +66 -0
- package/src/agents/runtime-agent-registry.js +415 -0
- package/src/agents/runtime-discovery.d.ts +13 -0
- package/src/agents/runtime-discovery.js +27 -0
- package/src/agents/skills.d.ts +34 -0
- package/src/agents/skills.js +718 -0
- package/src/api/agent-management.d.ts +2 -0
- package/src/api/agent-management.js +2 -0
- package/src/api/agents.d.ts +6 -0
- package/src/api/agents.js +3 -0
- package/src/api/background-work.d.ts +41 -0
- package/src/api/background-work.js +171 -0
- package/src/api/capability-ceiling.d.ts +1 -0
- package/src/api/capability-ceiling.js +1 -0
- package/src/api/child-tool-plan.d.ts +1 -0
- package/src/api/child-tool-plan.js +1 -0
- package/src/api/control-channel.d.ts +1 -0
- package/src/api/control-channel.js +1 -0
- package/src/api/delegation.d.ts +132 -0
- package/src/api/delegation.js +8 -0
- package/src/api/external-job-provider.d.ts +57 -0
- package/src/api/external-job-provider.js +139 -0
- package/src/api/external-runs.d.ts +47 -0
- package/src/api/external-runs.js +245 -0
- package/src/api/inspectors.d.ts +20 -0
- package/src/api/inspectors.js +11 -0
- package/src/api/intercom-bridge.d.ts +1 -0
- package/src/api/intercom-bridge.js +1 -0
- package/src/api/preflight.d.ts +183 -0
- package/src/api/preflight.js +455 -0
- package/src/api/project-panes.d.ts +7 -0
- package/src/api/project-panes.js +7 -0
- package/src/api/required-child-extensions.d.ts +1 -0
- package/src/api/required-child-extensions.js +1 -0
- package/src/api/shared-types.d.ts +1 -0
- package/src/api/shared-types.js +1 -0
- package/src/api/supervisor-routing.d.ts +110 -0
- package/src/api/supervisor-routing.js +95 -0
- package/src/api/workflow-resources.d.ts +2 -0
- package/src/api/workflow-resources.js +1 -0
- package/src/extension/active-runs-prompt.d.ts +7 -0
- package/src/extension/active-runs-prompt.js +29 -0
- package/src/extension/config.d.ts +7 -0
- package/src/extension/config.js +290 -0
- package/src/extension/context-injection.d.ts +52 -0
- package/src/extension/context-injection.js +102 -0
- package/src/extension/control-notices.d.ts +18 -0
- package/src/extension/control-notices.js +29 -0
- package/src/extension/declaration-pinning.d.ts +18 -0
- package/src/extension/declaration-pinning.js +167 -0
- package/src/extension/doctor.d.ts +34 -0
- package/src/extension/doctor.js +236 -0
- package/src/extension/fanout-child.d.ts +6 -0
- package/src/extension/fanout-child.js +278 -0
- package/src/extension/herdr-pi-bridge.d.ts +16 -0
- package/src/extension/herdr-pi-bridge.js +261 -0
- package/src/extension/index.d.ts +18 -0
- package/src/extension/index.js +1300 -0
- package/src/extension/public-execution.d.ts +71 -0
- package/src/extension/public-execution.js +214 -0
- package/src/extension/reply-workflow-script.d.ts +11 -0
- package/src/extension/reply-workflow-script.js +71 -0
- package/src/extension/rpc.d.ts +84 -0
- package/src/extension/rpc.js +729 -0
- package/src/extension/schemas.d.ts +276 -0
- package/src/extension/schemas.js +311 -0
- package/src/extension/steering-notices.d.ts +14 -0
- package/src/extension/steering-notices.js +22 -0
- package/src/extension/subagent-guide.d.ts +4 -0
- package/src/extension/subagent-guide.js +114 -0
- package/src/extension/subagent-options.d.ts +7 -0
- package/src/extension/subagent-options.js +64 -0
- package/src/extension/tool-activation.d.ts +7 -0
- package/src/extension/tool-activation.js +185 -0
- package/src/extension/tool-description.d.ts +19 -0
- package/src/extension/tool-description.js +169 -0
- package/src/extension/tool-result.d.ts +9 -0
- package/src/extension/tool-result.js +16 -0
- package/src/extension/upgrade-notice.d.ts +6 -0
- package/src/extension/upgrade-notice.js +42 -0
- package/src/goal-auto-continue-gate.d.ts +17 -0
- package/src/goal-auto-continue-gate.js +61 -0
- package/src/goal-auto-continue-state.d.ts +22 -0
- package/src/goal-auto-continue-state.js +20 -0
- package/src/inspectors/actions.d.ts +24 -0
- package/src/inspectors/actions.js +182 -0
- package/src/inspectors/ghostty/actions.d.ts +11 -0
- package/src/inspectors/ghostty/actions.js +62 -0
- package/src/inspectors/ghostty/plugin.d.ts +7 -0
- package/src/inspectors/ghostty/plugin.js +23 -0
- package/src/inspectors/herdr/actions.d.ts +25 -0
- package/src/inspectors/herdr/actions.js +133 -0
- package/src/inspectors/herdr/client.d.ts +41 -0
- package/src/inspectors/herdr/client.js +129 -0
- package/src/inspectors/herdr/focus.d.ts +24 -0
- package/src/inspectors/herdr/focus.js +49 -0
- package/src/inspectors/herdr/plugin.d.ts +6 -0
- package/src/inspectors/herdr/plugin.js +14 -0
- package/src/inspectors/herdr/project-panes.d.ts +136 -0
- package/src/inspectors/herdr/project-panes.js +610 -0
- package/src/inspectors/inspector-runner.d.ts +23 -0
- package/src/inspectors/inspector-runner.js +161 -0
- package/src/inspectors/plugins.d.ts +8 -0
- package/src/inspectors/plugins.js +82 -0
- package/src/inspectors/session-roots-codec.d.ts +15 -0
- package/src/inspectors/session-roots-codec.js +32 -0
- package/src/inspectors/shell-command.d.ts +1 -0
- package/src/inspectors/shell-command.js +16 -0
- package/src/inspectors/tmux/actions.d.ts +25 -0
- package/src/inspectors/tmux/actions.js +181 -0
- package/src/inspectors/tmux/client.d.ts +27 -0
- package/src/inspectors/tmux/client.js +64 -0
- package/src/inspectors/tmux/plugin.d.ts +7 -0
- package/src/inspectors/tmux/plugin.js +14 -0
- package/src/inspectors/types.d.ts +48 -0
- package/src/inspectors/types.js +1 -0
- package/src/integrations/herdr-status.d.ts +47 -0
- package/src/integrations/herdr-status.js +350 -0
- package/src/integrations/pi-web-session-liveness.d.ts +19 -0
- package/src/integrations/pi-web-session-liveness.js +53 -0
- package/src/integrations/program-status.d.ts +30 -0
- package/src/integrations/program-status.js +188 -0
- package/src/intercom/fork-supervisor-routing.d.ts +90 -0
- package/src/intercom/fork-supervisor-routing.js +392 -0
- package/src/intercom/intercom-bridge.d.ts +58 -0
- package/src/intercom/intercom-bridge.js +193 -0
- package/src/intercom/native-supervisor-channel.d.ts +97 -0
- package/src/intercom/native-supervisor-channel.js +1184 -0
- package/src/intercom/result-intercom.d.ts +35 -0
- package/src/intercom/result-intercom.js +376 -0
- package/src/intercom/supervisor-ui.d.ts +29 -0
- package/src/intercom/supervisor-ui.js +49 -0
- package/src/missions/actions.d.ts +54 -0
- package/src/missions/actions.js +400 -0
- package/src/missions/goal-driver.d.ts +16 -0
- package/src/missions/goal-driver.js +171 -0
- package/src/missions/lifecycle.d.ts +50 -0
- package/src/missions/lifecycle.js +388 -0
- package/src/missions/store.d.ts +21 -0
- package/src/missions/store.js +605 -0
- package/src/missions/types.d.ts +169 -0
- package/src/missions/types.js +9 -0
- package/src/missions/workflow-state.d.ts +14 -0
- package/src/missions/workflow-state.js +273 -0
- package/src/policy/authority.d.ts +9 -0
- package/src/policy/authority.js +41 -0
- package/src/profiles/profiles.d.ts +134 -0
- package/src/profiles/profiles.js +526 -0
- package/src/runs/background/active-async-capacity.d.ts +115 -0
- package/src/runs/background/active-async-capacity.js +517 -0
- package/src/runs/background/active-run-index.d.ts +12 -0
- package/src/runs/background/active-run-index.js +157 -0
- package/src/runs/background/async-execution.d.ts +306 -0
- package/src/runs/background/async-execution.js +2210 -0
- package/src/runs/background/async-job-tracker.d.ts +37 -0
- package/src/runs/background/async-job-tracker.js +926 -0
- package/src/runs/background/async-resume.d.ts +60 -0
- package/src/runs/background/async-resume.js +707 -0
- package/src/runs/background/async-retention.d.ts +45 -0
- package/src/runs/background/async-retention.js +932 -0
- package/src/runs/background/async-status-snapshot.d.ts +9 -0
- package/src/runs/background/async-status-snapshot.js +26 -0
- package/src/runs/background/async-status.d.ts +179 -0
- package/src/runs/background/async-status.js +712 -0
- package/src/runs/background/auto-drain.d.ts +16 -0
- package/src/runs/background/auto-drain.js +71 -0
- package/src/runs/background/await-async-run.d.ts +26 -0
- package/src/runs/background/await-async-run.js +83 -0
- package/src/runs/background/binary-bootstrap.d.ts +8 -0
- package/src/runs/background/binary-bootstrap.js +69 -0
- package/src/runs/background/boot-id.d.ts +12 -0
- package/src/runs/background/boot-id.js +47 -0
- package/src/runs/background/calendar-schedule.d.ts +26 -0
- package/src/runs/background/calendar-schedule.js +93 -0
- package/src/runs/background/chain-append.d.ts +34 -0
- package/src/runs/background/chain-append.js +299 -0
- package/src/runs/background/chain-root-attachment.d.ts +51 -0
- package/src/runs/background/chain-root-attachment.js +186 -0
- package/src/runs/background/completion-batcher.d.ts +51 -0
- package/src/runs/background/completion-batcher.js +119 -0
- package/src/runs/background/completion-dedupe.d.ts +13 -0
- package/src/runs/background/completion-dedupe.js +48 -0
- package/src/runs/background/completion-replay.d.ts +47 -0
- package/src/runs/background/completion-replay.js +266 -0
- package/src/runs/background/control-channel.d.ts +170 -0
- package/src/runs/background/control-channel.js +610 -0
- package/src/runs/background/fleet-view.d.ts +63 -0
- package/src/runs/background/fleet-view.js +666 -0
- package/src/runs/background/index-segment.d.ts +16 -0
- package/src/runs/background/index-segment.js +58 -0
- package/src/runs/background/inspect-rpc.d.ts +64 -0
- package/src/runs/background/inspect-rpc.js +422 -0
- package/src/runs/background/interrupted-elsewhere.d.ts +22 -0
- package/src/runs/background/interrupted-elsewhere.js +68 -0
- package/src/runs/background/notify.d.ts +216 -0
- package/src/runs/background/notify.js +1006 -0
- package/src/runs/background/owned-process-tree.d.ts +10 -0
- package/src/runs/background/owned-process-tree.js +116 -0
- package/src/runs/background/parallel-groups.d.ts +3 -0
- package/src/runs/background/parallel-groups.js +46 -0
- package/src/runs/background/pid-namespace.d.ts +2 -0
- package/src/runs/background/pid-namespace.js +19 -0
- package/src/runs/background/process-terminal-candidate.d.ts +17 -0
- package/src/runs/background/process-terminal-candidate.js +96 -0
- package/src/runs/background/process-terminal.d.ts +21 -0
- package/src/runs/background/process-terminal.js +227 -0
- package/src/runs/background/result-delivery-ownership.d.ts +14 -0
- package/src/runs/background/result-delivery-ownership.js +38 -0
- package/src/runs/background/result-files.d.ts +63 -0
- package/src/runs/background/result-files.js +629 -0
- package/src/runs/background/result-watcher.d.ts +92 -0
- package/src/runs/background/result-watcher.js +819 -0
- package/src/runs/background/resume-guidance.d.ts +4 -0
- package/src/runs/background/resume-guidance.js +57 -0
- package/src/runs/background/retained-children.d.ts +24 -0
- package/src/runs/background/retained-children.js +128 -0
- package/src/runs/background/retained-nested-route-tracker.d.ts +12 -0
- package/src/runs/background/retained-nested-route-tracker.js +90 -0
- package/src/runs/background/run-child-session.d.ts +123 -0
- package/src/runs/background/run-child-session.js +670 -0
- package/src/runs/background/run-id-query.d.ts +3 -0
- package/src/runs/background/run-id-query.js +6 -0
- package/src/runs/background/run-id-resolver.d.ts +22 -0
- package/src/runs/background/run-id-resolver.js +172 -0
- package/src/runs/background/run-status.d.ts +25 -0
- package/src/runs/background/run-status.js +850 -0
- package/src/runs/background/runner-aliases.d.ts +17 -0
- package/src/runs/background/runner-aliases.js +191 -0
- package/src/runs/background/runner-child-launch.d.ts +24 -0
- package/src/runs/background/runner-child-launch.js +72 -0
- package/src/runs/background/runner-child-sessions.d.ts +6 -0
- package/src/runs/background/runner-child-sessions.js +34 -0
- package/src/runs/background/runner-http-dispatcher.d.ts +45 -0
- package/src/runs/background/runner-http-dispatcher.js +115 -0
- package/src/runs/background/runner-startup-failure.d.ts +13 -0
- package/src/runs/background/runner-startup-failure.js +46 -0
- package/src/runs/background/scheduled-runs.d.ts +127 -0
- package/src/runs/background/scheduled-runs.js +1265 -0
- package/src/runs/background/stale-run-reconciler.d.ts +62 -0
- package/src/runs/background/stale-run-reconciler.js +509 -0
- package/src/runs/background/steering.d.ts +51 -0
- package/src/runs/background/steering.js +246 -0
- package/src/runs/background/subagent-runner-bootstrap.d.ts +13 -0
- package/src/runs/background/subagent-runner-bootstrap.js +283 -0
- package/src/runs/background/subagent-runner.d.ts +210 -0
- package/src/runs/background/subagent-runner.js +4963 -0
- package/src/runs/background/subagent-wait.d.ts +124 -0
- package/src/runs/background/subagent-wait.js +756 -0
- package/src/runs/background/terminal-run-index.d.ts +10 -0
- package/src/runs/background/terminal-run-index.js +209 -0
- package/src/runs/background/top-level-async.d.ts +7 -0
- package/src/runs/background/top-level-async.js +5 -0
- package/src/runs/background/wait-completions.d.ts +28 -0
- package/src/runs/background/wait-completions.js +264 -0
- package/src/runs/background/wait-config.d.ts +8 -0
- package/src/runs/background/wait-config.js +46 -0
- package/src/runs/background/wait-subscriptions.d.ts +26 -0
- package/src/runs/background/wait-subscriptions.js +339 -0
- package/src/runs/background/wait-tool.d.ts +6 -0
- package/src/runs/background/wait-tool.js +48 -0
- package/src/runs/background/workflow-terminal-proof.d.ts +47 -0
- package/src/runs/background/workflow-terminal-proof.js +116 -0
- package/src/runs/foreground/async-dismiss-action.d.ts +6 -0
- package/src/runs/foreground/async-dismiss-action.js +82 -0
- package/src/runs/foreground/async-steering-action.d.ts +31 -0
- package/src/runs/foreground/async-steering-action.js +294 -0
- package/src/runs/foreground/async-stop-action.d.ts +13 -0
- package/src/runs/foreground/async-stop-action.js +213 -0
- package/src/runs/foreground/command-action.d.ts +12 -0
- package/src/runs/foreground/command-action.js +38 -0
- package/src/runs/foreground/execution.d.ts +10 -0
- package/src/runs/foreground/execution.js +2322 -0
- package/src/runs/foreground/foreground-control.d.ts +24 -0
- package/src/runs/foreground/foreground-control.js +138 -0
- package/src/runs/foreground/foreground-history.d.ts +25 -0
- package/src/runs/foreground/foreground-history.js +267 -0
- package/src/runs/foreground/prompt-audit.d.ts +32 -0
- package/src/runs/foreground/prompt-audit.js +138 -0
- package/src/runs/foreground/subagent-executor.d.ts +316 -0
- package/src/runs/foreground/subagent-executor.js +7990 -0
- package/src/runs/foreground/workflow-detach-reconcile.d.ts +15 -0
- package/src/runs/foreground/workflow-detach-reconcile.js +283 -0
- package/src/runs/foreground/workflow-foreground-steering.d.ts +43 -0
- package/src/runs/foreground/workflow-foreground-steering.js +148 -0
- package/src/runs/shared/abort-recovery.d.ts +26 -0
- package/src/runs/shared/abort-recovery.js +108 -0
- package/src/runs/shared/acceptance.d.ts +144 -0
- package/src/runs/shared/acceptance.js +1616 -0
- package/src/runs/shared/agent-contract.d.ts +5 -0
- package/src/runs/shared/agent-contract.js +35 -0
- package/src/runs/shared/async-status-projection.d.ts +100 -0
- package/src/runs/shared/async-status-projection.js +566 -0
- package/src/runs/shared/background-process-options.d.ts +4 -0
- package/src/runs/shared/background-process-options.js +6 -0
- package/src/runs/shared/capability-ceiling.d.ts +58 -0
- package/src/runs/shared/capability-ceiling.js +179 -0
- package/src/runs/shared/chain-outputs.d.ts +18 -0
- package/src/runs/shared/chain-outputs.js +104 -0
- package/src/runs/shared/child-commands.d.ts +29 -0
- package/src/runs/shared/child-commands.js +254 -0
- package/src/runs/shared/child-hooks.d.ts +31 -0
- package/src/runs/shared/child-hooks.js +173 -0
- package/src/runs/shared/child-identity.d.ts +23 -0
- package/src/runs/shared/child-identity.js +40 -0
- package/src/runs/shared/child-launch-plan.d.ts +70 -0
- package/src/runs/shared/child-launch-plan.js +88 -0
- package/src/runs/shared/child-launch.d.ts +128 -0
- package/src/runs/shared/child-launch.js +262 -0
- package/src/runs/shared/child-lifecycle.d.ts +13 -0
- package/src/runs/shared/child-lifecycle.js +22 -0
- package/src/runs/shared/child-runtime-config.d.ts +111 -0
- package/src/runs/shared/child-runtime-config.js +44 -0
- package/src/runs/shared/child-session.d.ts +178 -0
- package/src/runs/shared/child-session.js +726 -0
- package/src/runs/shared/child-tool-plan.d.ts +101 -0
- package/src/runs/shared/child-tool-plan.js +430 -0
- package/src/runs/shared/claude-code-adapter.d.ts +80 -0
- package/src/runs/shared/claude-code-adapter.js +255 -0
- package/src/runs/shared/codex-exec-adapter.d.ts +25 -0
- package/src/runs/shared/codex-exec-adapter.js +127 -0
- package/src/runs/shared/context-mode.d.ts +12 -0
- package/src/runs/shared/context-mode.js +38 -0
- package/src/runs/shared/cursor-agent-adapter.d.ts +26 -0
- package/src/runs/shared/cursor-agent-adapter.js +99 -0
- package/src/runs/shared/dynamic-fanout.d.ts +49 -0
- package/src/runs/shared/dynamic-fanout.js +273 -0
- package/src/runs/shared/effective-system-prompt.d.ts +17 -0
- package/src/runs/shared/effective-system-prompt.js +23 -0
- package/src/runs/shared/extension-bindings.d.ts +25 -0
- package/src/runs/shared/extension-bindings.js +96 -0
- package/src/runs/shared/external-cli-contract.d.ts +29 -0
- package/src/runs/shared/external-cli-contract.js +145 -0
- package/src/runs/shared/external-cli-preflight.d.ts +41 -0
- package/src/runs/shared/external-cli-preflight.js +159 -0
- package/src/runs/shared/external-cli-runner.d.ts +65 -0
- package/src/runs/shared/external-cli-runner.js +425 -0
- package/src/runs/shared/external-job-bridge.d.ts +24 -0
- package/src/runs/shared/external-job-bridge.js +486 -0
- package/src/runs/shared/external-job-runner.d.ts +44 -0
- package/src/runs/shared/external-job-runner.js +352 -0
- package/src/runs/shared/fast-mode-extension.d.ts +3 -0
- package/src/runs/shared/fast-mode-extension.js +8 -0
- package/src/runs/shared/fork-placed-env.d.ts +4 -0
- package/src/runs/shared/fork-placed-env.js +13 -0
- package/src/runs/shared/git-environment.d.ts +2 -0
- package/src/runs/shared/git-environment.js +27 -0
- package/src/runs/shared/herdr-connection.d.ts +79 -0
- package/src/runs/shared/herdr-connection.js +269 -0
- package/src/runs/shared/herdr-external-adapters.d.ts +148 -0
- package/src/runs/shared/herdr-external-adapters.js +404 -0
- package/src/runs/shared/herdr-machine.d.ts +59 -0
- package/src/runs/shared/herdr-machine.js +294 -0
- package/src/runs/shared/herdr-pane-host.d.ts +88 -0
- package/src/runs/shared/herdr-pane-host.js +155 -0
- package/src/runs/shared/herdr-pi-protocol.d.ts +21 -0
- package/src/runs/shared/herdr-pi-protocol.js +57 -0
- package/src/runs/shared/herdr-placed-run.d.ts +144 -0
- package/src/runs/shared/herdr-placed-run.js +380 -0
- package/src/runs/shared/host-step-status.d.ts +33 -0
- package/src/runs/shared/host-step-status.js +244 -0
- package/src/runs/shared/lane-metadata.d.ts +23 -0
- package/src/runs/shared/lane-metadata.js +126 -0
- package/src/runs/shared/launch-cwd.d.ts +1 -0
- package/src/runs/shared/launch-cwd.js +16 -0
- package/src/runs/shared/local-machine-access.d.ts +5 -0
- package/src/runs/shared/local-machine-access.js +28 -0
- package/src/runs/shared/long-running-guard.d.ts +34 -0
- package/src/runs/shared/long-running-guard.js +256 -0
- package/src/runs/shared/mcp-config-sources.d.ts +33 -0
- package/src/runs/shared/mcp-config-sources.js +418 -0
- package/src/runs/shared/mcp-direct-tool-allowlist.d.ts +86 -0
- package/src/runs/shared/mcp-direct-tool-allowlist.js +477 -0
- package/src/runs/shared/mcp-direct-tool-grant.d.ts +42 -0
- package/src/runs/shared/mcp-direct-tool-grant.js +159 -0
- package/src/runs/shared/model-resolution-diagnostic.d.ts +44 -0
- package/src/runs/shared/model-resolution-diagnostic.js +116 -0
- package/src/runs/shared/model-resolution.d.ts +109 -0
- package/src/runs/shared/model-resolution.js +411 -0
- package/src/runs/shared/model-scope.d.ts +68 -0
- package/src/runs/shared/model-scope.js +171 -0
- package/src/runs/shared/mutation-evidence.d.ts +18 -0
- package/src/runs/shared/mutation-evidence.js +198 -0
- package/src/runs/shared/nested-events.d.ts +135 -0
- package/src/runs/shared/nested-events.js +1090 -0
- package/src/runs/shared/nested-path.d.ts +8 -0
- package/src/runs/shared/nested-path.js +34 -0
- package/src/runs/shared/nested-render.d.ts +20 -0
- package/src/runs/shared/nested-render.js +115 -0
- package/src/runs/shared/orca-progress-tabs.d.ts +31 -0
- package/src/runs/shared/orca-progress-tabs.js +503 -0
- package/src/runs/shared/parallel-handoff.d.ts +78 -0
- package/src/runs/shared/parallel-handoff.js +783 -0
- package/src/runs/shared/parallel-utils.d.ts +177 -0
- package/src/runs/shared/parallel-utils.js +125 -0
- package/src/runs/shared/partial-output.d.ts +24 -0
- package/src/runs/shared/partial-output.js +35 -0
- package/src/runs/shared/permissions.d.ts +12 -0
- package/src/runs/shared/permissions.js +92 -0
- package/src/runs/shared/pi-spawn.d.ts +31 -0
- package/src/runs/shared/pi-spawn.js +211 -0
- package/src/runs/shared/placed-run-owner.d.ts +49 -0
- package/src/runs/shared/placed-run-owner.js +93 -0
- package/src/runs/shared/placement-host.d.ts +99 -0
- package/src/runs/shared/placement-host.js +157 -0
- package/src/runs/shared/process-signal.d.ts +15 -0
- package/src/runs/shared/process-signal.js +21 -0
- package/src/runs/shared/profile-extensions.d.ts +21 -0
- package/src/runs/shared/profile-extensions.js +122 -0
- package/src/runs/shared/profile-launch-env.d.ts +26 -0
- package/src/runs/shared/profile-launch-env.js +90 -0
- package/src/runs/shared/readonly-drain-observation.d.ts +25 -0
- package/src/runs/shared/readonly-drain-observation.js +50 -0
- package/src/runs/shared/rex-machine.d.ts +25 -0
- package/src/runs/shared/rex-machine.js +83 -0
- package/src/runs/shared/rex-pane-host.d.ts +62 -0
- package/src/runs/shared/rex-pane-host.js +327 -0
- package/src/runs/shared/run-fanout-budget.d.ts +14 -0
- package/src/runs/shared/run-fanout-budget.js +258 -0
- package/src/runs/shared/run-ownership.d.ts +3 -0
- package/src/runs/shared/run-ownership.js +8 -0
- package/src/runs/shared/runner-launcher.d.ts +11 -0
- package/src/runs/shared/runner-launcher.js +24 -0
- package/src/runs/shared/runtime-acknowledged-extensions.d.ts +7 -0
- package/src/runs/shared/runtime-acknowledged-extensions.js +44 -0
- package/src/runs/shared/sandbox-profile-guard.d.ts +23 -0
- package/src/runs/shared/sandbox-profile-guard.js +106 -0
- package/src/runs/shared/sandbox-startup-diagnostics.d.ts +21 -0
- package/src/runs/shared/sandbox-startup-diagnostics.js +51 -0
- package/src/runs/shared/session-lease.d.ts +69 -0
- package/src/runs/shared/session-lease.js +250 -0
- package/src/runs/shared/single-output.d.ts +90 -0
- package/src/runs/shared/single-output.js +349 -0
- package/src/runs/shared/spawn-budget.d.ts +20 -0
- package/src/runs/shared/spawn-budget.js +93 -0
- package/src/runs/shared/structured-output.d.ts +66 -0
- package/src/runs/shared/structured-output.js +483 -0
- package/src/runs/shared/subagent-control.d.ts +50 -0
- package/src/runs/shared/subagent-control.js +247 -0
- package/src/runs/shared/subagent-prompt-runtime.d.ts +90 -0
- package/src/runs/shared/subagent-prompt-runtime.js +776 -0
- package/src/runs/shared/tool-availability.d.ts +16 -0
- package/src/runs/shared/tool-availability.js +29 -0
- package/src/runs/shared/tool-budget.d.ts +21 -0
- package/src/runs/shared/tool-budget.js +78 -0
- package/src/runs/shared/tool-timeout.d.ts +31 -0
- package/src/runs/shared/tool-timeout.js +73 -0
- package/src/runs/shared/usage-budget.d.ts +7 -0
- package/src/runs/shared/usage-budget.js +74 -0
- package/src/runs/shared/usage-reconciliation.d.ts +8 -0
- package/src/runs/shared/usage-reconciliation.js +71 -0
- package/src/runs/shared/workflow-async-child-guidance.d.ts +3 -0
- package/src/runs/shared/workflow-async-child-guidance.js +17 -0
- package/src/runs/shared/workflow-graph.d.ts +31 -0
- package/src/runs/shared/workflow-graph.js +221 -0
- package/src/runs/shared/worktree-cleanup-apply.d.ts +36 -0
- package/src/runs/shared/worktree-cleanup-apply.js +178 -0
- package/src/runs/shared/worktree-cleanup-plan.d.ts +84 -0
- package/src/runs/shared/worktree-cleanup-plan.js +803 -0
- package/src/runs/shared/worktree-lock.d.ts +5 -0
- package/src/runs/shared/worktree-lock.js +40 -0
- package/src/runs/shared/worktree-setup-command.d.ts +38 -0
- package/src/runs/shared/worktree-setup-command.js +200 -0
- package/src/runs/shared/worktree.d.ts +181 -0
- package/src/runs/shared/worktree.js +1346 -0
- package/src/shared/accessible-dir.d.ts +11 -0
- package/src/shared/accessible-dir.js +39 -0
- package/src/shared/agent-stream-options.d.ts +5 -0
- package/src/shared/agent-stream-options.js +3 -0
- package/src/shared/artifacts.d.ts +22 -0
- package/src/shared/artifacts.js +272 -0
- package/src/shared/atomic-json.d.ts +19 -0
- package/src/shared/atomic-json.js +61 -0
- package/src/shared/capacity-resilient-json.d.ts +26 -0
- package/src/shared/capacity-resilient-json.js +86 -0
- package/src/shared/child-cache-retention.d.ts +29 -0
- package/src/shared/child-cache-retention.js +40 -0
- package/src/shared/child-session-name.d.ts +8 -0
- package/src/shared/child-session-name.js +40 -0
- package/src/shared/child-transcript.d.ts +37 -0
- package/src/shared/child-transcript.js +225 -0
- package/src/shared/completion-owner.d.ts +7 -0
- package/src/shared/completion-owner.js +13 -0
- package/src/shared/disabled-features.d.ts +93 -0
- package/src/shared/disabled-features.js +120 -0
- package/src/shared/display-text.d.ts +5 -0
- package/src/shared/display-text.js +154 -0
- package/src/shared/edit-distance.d.ts +4 -0
- package/src/shared/edit-distance.js +32 -0
- package/src/shared/extension-context.d.ts +21 -0
- package/src/shared/extension-context.js +39 -0
- package/src/shared/file-coalescer.d.ts +11 -0
- package/src/shared/file-coalescer.js +34 -0
- package/src/shared/file-lease.d.ts +10 -0
- package/src/shared/file-lease.js +106 -0
- package/src/shared/file-system-retry.d.ts +31 -0
- package/src/shared/file-system-retry.js +84 -0
- package/src/shared/fork-context.d.ts +64 -0
- package/src/shared/fork-context.js +185 -0
- package/src/shared/fork-session-cwd.d.ts +2 -0
- package/src/shared/fork-session-cwd.js +23 -0
- package/src/shared/formatters.d.ts +35 -0
- package/src/shared/formatters.js +137 -0
- package/src/shared/jsonl-writer.d.ts +20 -0
- package/src/shared/jsonl-writer.js +67 -0
- package/src/shared/launch-contract.d.ts +65 -0
- package/src/shared/launch-contract.js +145 -0
- package/src/shared/model-info.d.ts +55 -0
- package/src/shared/model-info.js +103 -0
- package/src/shared/model-response-aliases.d.ts +1 -0
- package/src/shared/model-response-aliases.js +15 -0
- package/src/shared/node-executable.d.ts +1 -0
- package/src/shared/node-executable.js +20 -0
- package/src/shared/opencode-session-headers.d.ts +12 -0
- package/src/shared/opencode-session-headers.js +26 -0
- package/src/shared/package-version.d.ts +2 -0
- package/src/shared/package-version.js +14 -0
- package/src/shared/parent-wake.d.ts +26 -0
- package/src/shared/parent-wake.js +68 -0
- package/src/shared/permission-profile.d.ts +26 -0
- package/src/shared/permission-profile.js +49 -0
- package/src/shared/prompt-resources.d.ts +5 -0
- package/src/shared/prompt-resources.js +10 -0
- package/src/shared/provider-diagnostics.d.ts +9 -0
- package/src/shared/provider-diagnostics.js +75 -0
- package/src/shared/pruned-fork.d.ts +34 -0
- package/src/shared/pruned-fork.js +434 -0
- package/src/shared/required-child-extensions.d.ts +34 -0
- package/src/shared/required-child-extensions.js +105 -0
- package/src/shared/runtime-module-path.d.ts +10 -0
- package/src/shared/runtime-module-path.js +16 -0
- package/src/shared/sandbox-profile.d.ts +12 -0
- package/src/shared/sandbox-profile.js +35 -0
- package/src/shared/session-file-trust.d.ts +1 -0
- package/src/shared/session-file-trust.js +20 -0
- package/src/shared/session-identity.d.ts +8 -0
- package/src/shared/session-identity.js +32 -0
- package/src/shared/session-succession.d.ts +4 -0
- package/src/shared/session-succession.js +24 -0
- package/src/shared/session-tokens.d.ts +2 -0
- package/src/shared/session-tokens.js +58 -0
- package/src/shared/settings-file-lease.d.ts +4 -0
- package/src/shared/settings-file-lease.js +38 -0
- package/src/shared/settings.d.ts +146 -0
- package/src/shared/settings.js +247 -0
- package/src/shared/shortcuts.d.ts +1 -0
- package/src/shared/shortcuts.js +17 -0
- package/src/shared/status-format.d.ts +9 -0
- package/src/shared/status-format.js +60 -0
- package/src/shared/thinking-ceiling.d.ts +13 -0
- package/src/shared/thinking-ceiling.js +37 -0
- package/src/shared/types.d.ts +2842 -0
- package/src/shared/types.js +276 -0
- package/src/shared/utf8.d.ts +5 -0
- package/src/shared/utf8.js +12 -0
- package/src/shared/utils.d.ts +83 -0
- package/src/shared/utils.js +612 -0
- package/src/shared/watch-strategy.d.ts +2 -0
- package/src/shared/watch-strategy.js +5 -0
- package/src/shared/workflow-child-permit.d.ts +58 -0
- package/src/shared/workflow-child-permit.js +159 -0
- package/src/slash/delegation-adapters.d.ts +154 -0
- package/src/slash/delegation-adapters.js +316 -0
- package/src/slash/delegation-json.d.ts +10 -0
- package/src/slash/delegation-json.js +117 -0
- package/src/slash/delegation-request.d.ts +12 -0
- package/src/slash/delegation-request.js +174 -0
- package/src/slash/prompt-template-bridge.d.ts +29 -0
- package/src/slash/prompt-template-bridge.js +399 -0
- package/src/slash/prompt-workflows.d.ts +21 -0
- package/src/slash/prompt-workflows.js +274 -0
- package/src/slash/selector.d.ts +47 -0
- package/src/slash/selector.js +117 -0
- package/src/slash/slash-bridge.d.ts +30 -0
- package/src/slash/slash-bridge.js +132 -0
- package/src/slash/slash-commands.d.ts +10 -0
- package/src/slash/slash-commands.js +1059 -0
- package/src/slash/slash-live-state.d.ts +21 -0
- package/src/slash/slash-live-state.js +263 -0
- package/src/slash/subagent-cost.d.ts +29 -0
- package/src/slash/subagent-cost.js +310 -0
- package/src/slash/subagents-admin.d.ts +3 -0
- package/src/slash/subagents-admin.js +481 -0
- package/src/tui/fleet-layout.d.ts +20 -0
- package/src/tui/fleet-layout.js +17 -0
- package/src/tui/fleet-native-transcript.d.ts +53 -0
- package/src/tui/fleet-native-transcript.js +339 -0
- package/src/tui/fleet-status.d.ts +92 -0
- package/src/tui/fleet-status.js +1132 -0
- package/src/tui/fleet-transcript.d.ts +64 -0
- package/src/tui/fleet-transcript.js +544 -0
- package/src/tui/fleet-viewport.d.ts +12 -0
- package/src/tui/fleet-viewport.js +35 -0
- package/src/tui/fleet.d.ts +196 -0
- package/src/tui/fleet.js +1588 -0
- package/src/tui/mouse-events.d.ts +21 -0
- package/src/tui/mouse-events.js +26 -0
- package/src/tui/render-helpers.d.ts +23 -0
- package/src/tui/render-helpers.js +100 -0
- package/src/tui/render.d.ts +66 -0
- package/src/tui/render.js +3707 -0
- package/src/tui/running-tone.d.ts +10 -0
- package/src/tui/running-tone.js +22 -0
- package/src/tui/subagent-messages.d.ts +22 -0
- package/src/tui/subagent-messages.js +270 -0
- package/src/ui-silent-marker.d.ts +20 -0
- package/src/ui-silent-marker.js +25 -0
- package/src/watchdog/change-signature.d.ts +7 -0
- package/src/watchdog/change-signature.js +243 -0
- package/src/watchdog/child-status.d.ts +53 -0
- package/src/watchdog/child-status.js +187 -0
- package/src/watchdog/diff-tool.d.ts +25 -0
- package/src/watchdog/diff-tool.js +104 -0
- package/src/watchdog/emission-guard.d.ts +36 -0
- package/src/watchdog/emission-guard.js +97 -0
- package/src/watchdog/guidance.d.ts +3 -0
- package/src/watchdog/guidance.js +19 -0
- package/src/watchdog/lsp-diagnostics.d.ts +17 -0
- package/src/watchdog/lsp-diagnostics.js +489 -0
- package/src/watchdog/model-selection.d.ts +24 -0
- package/src/watchdog/model-selection.js +167 -0
- package/src/watchdog/permission-arbiter.d.ts +20 -0
- package/src/watchdog/permission-arbiter.js +135 -0
- package/src/watchdog/register-child.d.ts +13 -0
- package/src/watchdog/register-child.js +128 -0
- package/src/watchdog/register-main.d.ts +11 -0
- package/src/watchdog/register-main.js +400 -0
- package/src/watchdog/render.d.ts +3 -0
- package/src/watchdog/render.js +33 -0
- package/src/watchdog/review.d.ts +36 -0
- package/src/watchdog/review.js +319 -0
- package/src/watchdog/rules.d.ts +21 -0
- package/src/watchdog/rules.js +58 -0
- package/src/watchdog/runtime.d.ts +195 -0
- package/src/watchdog/runtime.js +864 -0
- package/src/watchdog/scope.d.ts +14 -0
- package/src/watchdog/scope.js +44 -0
- package/src/watchdog/settings.d.ts +29 -0
- package/src/watchdog/settings.js +480 -0
- package/src/watchdog/tool-actions.d.ts +17 -0
- package/src/watchdog/tool-actions.js +150 -0
- package/src/watchdog/turn-delta.d.ts +15 -0
- package/src/watchdog/turn-delta.js +188 -0
- package/src/watchdog/types.d.ts +141 -0
- package/src/watchdog/types.js +27 -0
- package/src/watchdog/warning-format.d.ts +7 -0
- package/src/watchdog/warning-format.js +59 -0
- package/src/workflows/chat-progress.d.ts +37 -0
- package/src/workflows/chat-progress.js +129 -0
- package/src/workflows/host-command.d.ts +30 -0
- package/src/workflows/host-command.js +227 -0
- package/src/workflows/scripted-workflow.d.ts +204 -0
- package/src/workflows/scripted-workflow.js +1673 -0
- package/src/workflows/structured-workflow-scripts.d.ts +10 -0
- package/src/workflows/structured-workflow-scripts.js +179 -0
- package/src/workflows/workflow-auto-resume.d.ts +32 -0
- package/src/workflows/workflow-auto-resume.js +102 -0
- package/src/workflows/workflow-checklist.d.ts +127 -0
- package/src/workflows/workflow-checklist.js +314 -0
- package/src/workflows/workflow-child-summary.d.ts +24 -0
- package/src/workflows/workflow-child-summary.js +195 -0
- package/src/workflows/workflow-launch-record.d.ts +27 -0
- package/src/workflows/workflow-launch-record.js +48 -0
- package/src/workflows/workflow-preflight.d.ts +58 -0
- package/src/workflows/workflow-preflight.js +288 -0
- package/src/workflows/workflow-receipt.d.ts +34 -0
- package/src/workflows/workflow-receipt.js +454 -0
- package/src/workflows/workflow-resources.d.ts +55 -0
- package/src/workflows/workflow-resources.js +271 -0
- package/src/workflows/workflow-resume-claim.d.ts +82 -0
- package/src/workflows/workflow-resume-claim.js +210 -0
- package/src/workflows/workflow-resume.d.ts +56 -0
- package/src/workflows/workflow-resume.js +106 -0
- package/src/workflows/workflow-reuse.d.ts +61 -0
- package/src/workflows/workflow-reuse.js +186 -0
- package/src/workflows/workflow-revival.d.ts +33 -0
- package/src/workflows/workflow-revival.js +111 -0
- package/src/workflows/workflow-settlement.d.ts +84 -0
- package/src/workflows/workflow-settlement.js +203 -0
- package/src/workflows/workflow-stop-cause.d.ts +6 -0
- package/src/workflows/workflow-stop-cause.js +8 -0
- package/workflow-script-worker.cjs +1342 -0
- package/index.ts +0 -18
- package/node_modules/@xzzpig/pi-components/src/transcript.ts +0 -1878
- package/skills/pi-subagents/references/constraints-and-recipes.md +0 -74
- package/skills/pi-subagents/references/execution-controls.md +0 -561
- package/skills/pi-subagents/references/management-authoring-rpc.md +0 -165
- package/skills/pi-subagents/references/multi-lane-orchestration.md +0 -61
- package/skills/pi-subagents/references/review-and-validation.md +0 -73
- package/src/agents/advertised-agent-prompt.ts +0 -82
- package/src/agents/agent-eject.ts +0 -339
- package/src/agents/agent-management.ts +0 -1442
- package/src/agents/agent-memory.ts +0 -341
- package/src/agents/agent-refinements.ts +0 -624
- package/src/agents/agent-scope.ts +0 -10
- package/src/agents/agent-selection.ts +0 -25
- package/src/agents/agent-serializer.ts +0 -195
- package/src/agents/agents.ts +0 -3169
- package/src/agents/builtin-names.ts +0 -16
- package/src/agents/chain-serializer.ts +0 -285
- package/src/agents/frontmatter.ts +0 -153
- package/src/agents/global-npm-root.ts +0 -58
- package/src/agents/identity.ts +0 -30
- package/src/agents/proactive-skills.ts +0 -197
- package/src/agents/runtime-agent-events.ts +0 -70
- package/src/agents/runtime-agent-registry.ts +0 -457
- package/src/agents/runtime-discovery.ts +0 -39
- package/src/agents/skills.ts +0 -787
- package/src/api/agent-management.ts +0 -9
- package/src/api/agents.ts +0 -19
- package/src/api/background-work.ts +0 -206
- package/src/api/capability-ceiling.ts +0 -16
- package/src/api/child-tool-plan.ts +0 -5
- package/src/api/control-channel.ts +0 -4
- package/src/api/delegation.ts +0 -131
- package/src/api/external-job-provider.ts +0 -195
- package/src/api/external-runs.ts +0 -282
- package/src/api/inspectors.ts +0 -27
- package/src/api/intercom-bridge.ts +0 -3
- package/src/api/preflight.ts +0 -641
- package/src/api/project-panes.ts +0 -32
- package/src/api/required-child-extensions.ts +0 -6
- package/src/api/shared-types.ts +0 -29
- package/src/api/supervisor-routing.ts +0 -196
- package/src/api/workflow-resources.ts +0 -6
- package/src/extension/config.ts +0 -262
- package/src/extension/context-injection.ts +0 -123
- package/src/extension/control-notices.ts +0 -53
- package/src/extension/declaration-pinning.ts +0 -164
- package/src/extension/doctor.ts +0 -284
- package/src/extension/fanout-child.ts +0 -282
- package/src/extension/herdr-pi-bridge.ts +0 -166
- package/src/extension/index.ts +0 -1212
- package/src/extension/public-execution.ts +0 -262
- package/src/extension/reply-workflow-script.ts +0 -67
- package/src/extension/rpc.ts +0 -881
- package/src/extension/schemas.ts +0 -337
- package/src/extension/steering-notices.ts +0 -35
- package/src/extension/subagent-guide.ts +0 -127
- package/src/extension/subagent-options.ts +0 -47
- package/src/extension/tool-activation.ts +0 -147
- package/src/extension/tool-description.ts +0 -193
- package/src/extension/tool-result.ts +0 -19
- package/src/extension/upgrade-notice.ts +0 -40
- package/src/inspectors/actions.ts +0 -174
- package/src/inspectors/ghostty/actions.ts +0 -74
- package/src/inspectors/ghostty/plugin.ts +0 -29
- package/src/inspectors/herdr/actions.ts +0 -155
- package/src/inspectors/herdr/client.ts +0 -130
- package/src/inspectors/herdr/focus.ts +0 -55
- package/src/inspectors/herdr/plugin.ts +0 -20
- package/src/inspectors/herdr/project-panes.ts +0 -733
- package/src/inspectors/inspector-runner.ts +0 -153
- package/src/inspectors/plugins.ts +0 -76
- package/src/inspectors/session-roots-codec.ts +0 -31
- package/src/inspectors/shell-command.ts +0 -16
- package/src/inspectors/tmux/actions.ts +0 -204
- package/src/inspectors/tmux/client.ts +0 -85
- package/src/inspectors/tmux/plugin.ts +0 -21
- package/src/inspectors/types.ts +0 -51
- package/src/integrations/herdr-status.ts +0 -385
- package/src/integrations/pi-web-session-liveness.ts +0 -73
- package/src/integrations/program-status.ts +0 -215
- package/src/intercom/fork-supervisor-routing.ts +0 -533
- package/src/intercom/intercom-bridge.ts +0 -235
- package/src/intercom/native-supervisor-channel.ts +0 -1066
- package/src/intercom/result-intercom.ts +0 -433
- package/src/intercom/supervisor-ui.ts +0 -72
- package/src/missions/actions.ts +0 -433
- package/src/missions/goal-driver.ts +0 -177
- package/src/missions/lifecycle.ts +0 -367
- package/src/missions/store.ts +0 -613
- package/src/missions/types.ts +0 -190
- package/src/missions/workflow-state.ts +0 -281
- package/src/policy/authority.ts +0 -50
- package/src/profiles/profiles.ts +0 -674
- package/src/runs/background/active-async-capacity.ts +0 -548
- package/src/runs/background/active-run-index.ts +0 -155
- package/src/runs/background/async-execution.ts +0 -2479
- package/src/runs/background/async-job-tracker.ts +0 -869
- package/src/runs/background/async-resume.ts +0 -686
- package/src/runs/background/async-retention.ts +0 -953
- package/src/runs/background/async-status-snapshot.ts +0 -46
- package/src/runs/background/async-status.ts +0 -787
- package/src/runs/background/auto-drain.ts +0 -92
- package/src/runs/background/await-async-run.ts +0 -83
- package/src/runs/background/binary-bootstrap.ts +0 -67
- package/src/runs/background/calendar-schedule.ts +0 -90
- package/src/runs/background/chain-append.ts +0 -321
- package/src/runs/background/chain-root-attachment.ts +0 -263
- package/src/runs/background/completion-batcher.ts +0 -168
- package/src/runs/background/completion-dedupe.ts +0 -58
- package/src/runs/background/completion-replay.ts +0 -287
- package/src/runs/background/control-channel.ts +0 -659
- package/src/runs/background/fleet-view.ts +0 -692
- package/src/runs/background/index-segment.ts +0 -59
- package/src/runs/background/inspect-rpc.ts +0 -443
- package/src/runs/background/notify.ts +0 -1083
- package/src/runs/background/owned-process-tree.ts +0 -131
- package/src/runs/background/parallel-groups.ts +0 -45
- package/src/runs/background/pid-namespace.ts +0 -18
- package/src/runs/background/process-terminal-candidate.ts +0 -98
- package/src/runs/background/process-terminal.ts +0 -231
- package/src/runs/background/result-delivery-ownership.ts +0 -45
- package/src/runs/background/result-files.ts +0 -634
- package/src/runs/background/result-watcher.ts +0 -842
- package/src/runs/background/resume-guidance.ts +0 -56
- package/src/runs/background/retained-children.ts +0 -136
- package/src/runs/background/retained-nested-route-tracker.ts +0 -96
- package/src/runs/background/run-child-session.ts +0 -725
- package/src/runs/background/run-id-query.ts +0 -7
- package/src/runs/background/run-id-resolver.ts +0 -183
- package/src/runs/background/run-status.ts +0 -803
- package/src/runs/background/runner-aliases.ts +0 -183
- package/src/runs/background/runner-child-launch.ts +0 -96
- package/src/runs/background/runner-child-sessions.ts +0 -32
- package/src/runs/background/runner-http-dispatcher.ts +0 -122
- package/src/runs/background/runner-startup-failure.ts +0 -56
- package/src/runs/background/scheduled-runs.ts +0 -1222
- package/src/runs/background/stale-run-reconciler.ts +0 -463
- package/src/runs/background/steering.ts +0 -260
- package/src/runs/background/subagent-runner-bootstrap.ts +0 -279
- package/src/runs/background/subagent-runner.ts +0 -5251
- package/src/runs/background/subagent-wait.ts +0 -895
- package/src/runs/background/terminal-run-index.ts +0 -183
- package/src/runs/background/top-level-async.ts +0 -14
- package/src/runs/background/wait-completions.ts +0 -262
- package/src/runs/background/wait-config.ts +0 -50
- package/src/runs/background/wait-subscriptions.ts +0 -354
- package/src/runs/background/wait-tool.ts +0 -57
- package/src/runs/background/workflow-terminal-proof.ts +0 -85
- package/src/runs/foreground/async-dismiss-action.ts +0 -86
- package/src/runs/foreground/async-steering-action.ts +0 -276
- package/src/runs/foreground/async-stop-action.ts +0 -216
- package/src/runs/foreground/command-action.ts +0 -41
- package/src/runs/foreground/execution.ts +0 -2315
- package/src/runs/foreground/foreground-control.ts +0 -157
- package/src/runs/foreground/foreground-history.ts +0 -164
- package/src/runs/foreground/prompt-audit.ts +0 -172
- package/src/runs/foreground/subagent-executor.ts +0 -8252
- package/src/runs/foreground/workflow-detach-reconcile.ts +0 -304
- package/src/runs/foreground/workflow-foreground-steering.ts +0 -169
- package/src/runs/shared/abort-recovery.ts +0 -119
- package/src/runs/shared/acceptance.ts +0 -1664
- package/src/runs/shared/agent-contract.ts +0 -38
- package/src/runs/shared/async-status-projection.ts +0 -664
- package/src/runs/shared/background-process-options.ts +0 -9
- package/src/runs/shared/capability-ceiling.ts +0 -214
- package/src/runs/shared/chain-outputs.ts +0 -116
- package/src/runs/shared/child-commands.ts +0 -229
- package/src/runs/shared/child-hooks.ts +0 -175
- package/src/runs/shared/child-identity.ts +0 -62
- package/src/runs/shared/child-launch-plan.ts +0 -163
- package/src/runs/shared/child-launch.ts +0 -389
- package/src/runs/shared/child-lifecycle.ts +0 -28
- package/src/runs/shared/child-runtime-config.ts +0 -136
- package/src/runs/shared/child-session.ts +0 -699
- package/src/runs/shared/child-tool-plan.ts +0 -599
- package/src/runs/shared/claude-code-adapter.ts +0 -288
- package/src/runs/shared/codex-exec-adapter.ts +0 -129
- package/src/runs/shared/context-mode.ts +0 -44
- package/src/runs/shared/cursor-agent-adapter.ts +0 -114
- package/src/runs/shared/dynamic-fanout.ts +0 -297
- package/src/runs/shared/effective-system-prompt.ts +0 -33
- package/src/runs/shared/extension-bindings.ts +0 -103
- package/src/runs/shared/external-cli-contract.ts +0 -177
- package/src/runs/shared/external-cli-preflight.ts +0 -190
- package/src/runs/shared/external-cli-runner.ts +0 -437
- package/src/runs/shared/external-job-bridge.ts +0 -514
- package/src/runs/shared/external-job-runner.ts +0 -389
- package/src/runs/shared/fast-mode-extension.ts +0 -10
- package/src/runs/shared/fork-command-result.ts +0 -10
- package/src/runs/shared/git-environment.ts +0 -29
- package/src/runs/shared/herdr-connection.ts +0 -134
- package/src/runs/shared/herdr-external-adapters.ts +0 -169
- package/src/runs/shared/herdr-machine.ts +0 -279
- package/src/runs/shared/herdr-pi-protocol.ts +0 -59
- package/src/runs/shared/herdr-placed-run.ts +0 -264
- package/src/runs/shared/host-step-status.ts +0 -231
- package/src/runs/shared/lane-metadata.ts +0 -126
- package/src/runs/shared/launch-cwd.ts +0 -16
- package/src/runs/shared/long-running-guard.ts +0 -221
- package/src/runs/shared/mcp-config-sources.ts +0 -426
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +0 -579
- package/src/runs/shared/mcp-direct-tool-grant.ts +0 -210
- package/src/runs/shared/model-resolution-diagnostic.ts +0 -101
- package/src/runs/shared/model-resolution.ts +0 -503
- package/src/runs/shared/model-scope.ts +0 -224
- package/src/runs/shared/mutation-evidence.ts +0 -199
- package/src/runs/shared/nested-events.ts +0 -1125
- package/src/runs/shared/nested-path.ts +0 -38
- package/src/runs/shared/nested-render.ts +0 -127
- package/src/runs/shared/orca-progress-tabs.ts +0 -511
- package/src/runs/shared/parallel-handoff.ts +0 -789
- package/src/runs/shared/parallel-utils.ts +0 -292
- package/src/runs/shared/partial-output.ts +0 -48
- package/src/runs/shared/permissions.ts +0 -86
- package/src/runs/shared/pi-spawn.ts +0 -205
- package/src/runs/shared/process-signal.ts +0 -35
- package/src/runs/shared/profile-extensions.ts +0 -134
- package/src/runs/shared/profile-launch-env.ts +0 -121
- package/src/runs/shared/readonly-drain-observation.ts +0 -42
- package/src/runs/shared/run-fanout-budget.ts +0 -267
- package/src/runs/shared/run-history.ts +0 -288
- package/src/runs/shared/runner-launcher.ts +0 -25
- package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -44
- package/src/runs/shared/sandbox-profile-guard.ts +0 -119
- package/src/runs/shared/sandbox-startup-diagnostics.ts +0 -54
- package/src/runs/shared/session-lease.ts +0 -293
- package/src/runs/shared/single-output.ts +0 -366
- package/src/runs/shared/spawn-budget.ts +0 -128
- package/src/runs/shared/structured-output.ts +0 -463
- package/src/runs/shared/subagent-control.ts +0 -295
- package/src/runs/shared/subagent-prompt-runtime.ts +0 -598
- package/src/runs/shared/tool-availability.ts +0 -37
- package/src/runs/shared/tool-budget.ts +0 -87
- package/src/runs/shared/tool-timeout.ts +0 -93
- package/src/runs/shared/usage-budget.ts +0 -65
- package/src/runs/shared/usage-reconciliation.ts +0 -73
- package/src/runs/shared/workflow-async-child-guidance.ts +0 -18
- package/src/runs/shared/workflow-graph.ts +0 -225
- package/src/runs/shared/worktree-cleanup-apply.ts +0 -160
- package/src/runs/shared/worktree-cleanup-plan.ts +0 -891
- package/src/runs/shared/worktree-lock.ts +0 -29
- package/src/runs/shared/worktree-setup-command.ts +0 -213
- package/src/runs/shared/worktree.ts +0 -1554
- package/src/shared/accessible-dir.ts +0 -47
- package/src/shared/agent-stream-options.ts +0 -5
- package/src/shared/artifacts.ts +0 -281
- package/src/shared/atomic-json.ts +0 -85
- package/src/shared/capacity-resilient-json.ts +0 -102
- package/src/shared/child-cache-retention.ts +0 -43
- package/src/shared/child-session-name.ts +0 -48
- package/src/shared/child-transcript.ts +0 -264
- package/src/shared/completion-owner.ts +0 -14
- package/src/shared/disabled-features.ts +0 -123
- package/src/shared/display-text.ts +0 -150
- package/src/shared/edit-distance.ts +0 -33
- package/src/shared/extension-context.ts +0 -37
- package/src/shared/file-coalescer.ts +0 -49
- package/src/shared/file-lease.ts +0 -74
- package/src/shared/file-system-retry.ts +0 -95
- package/src/shared/fork-context.ts +0 -243
- package/src/shared/fork-session-cwd.ts +0 -27
- package/src/shared/formatters.ts +0 -142
- package/src/shared/jsonl-writer.ts +0 -92
- package/src/shared/launch-contract.ts +0 -206
- package/src/shared/model-info.ts +0 -132
- package/src/shared/model-response-aliases.ts +0 -13
- package/src/shared/node-executable.ts +0 -21
- package/src/shared/opencode-session-headers.ts +0 -30
- package/src/shared/package-version.ts +0 -17
- package/src/shared/parent-wake.ts +0 -79
- package/src/shared/permission-profile.ts +0 -56
- package/src/shared/prompt-resources.ts +0 -11
- package/src/shared/pruned-fork.ts +0 -469
- package/src/shared/required-child-extensions.ts +0 -115
- package/src/shared/runtime-module-path.ts +0 -19
- package/src/shared/sandbox-profile.ts +0 -37
- package/src/shared/session-file-trust.ts +0 -19
- package/src/shared/session-identity.ts +0 -10
- package/src/shared/session-tokens.ts +0 -55
- package/src/shared/settings-file-lease.ts +0 -36
- package/src/shared/settings.ts +0 -412
- package/src/shared/shortcuts.ts +0 -13
- package/src/shared/status-format.ts +0 -55
- package/src/shared/thinking-ceiling.ts +0 -46
- package/src/shared/types.ts +0 -3105
- package/src/shared/utf8.ts +0 -11
- package/src/shared/utils.ts +0 -610
- package/src/shared/watch-strategy.ts +0 -12
- package/src/shared/workflow-child-permit.ts +0 -212
- package/src/slash/delegation-adapters.ts +0 -452
- package/src/slash/delegation-json.ts +0 -108
- package/src/slash/delegation-request.ts +0 -176
- package/src/slash/prompt-template-bridge.ts +0 -435
- package/src/slash/prompt-workflows.ts +0 -298
- package/src/slash/selector.ts +0 -147
- package/src/slash/slash-bridge.ts +0 -192
- package/src/slash/slash-commands.ts +0 -1096
- package/src/slash/slash-live-state.ts +0 -310
- package/src/slash/subagent-cost.ts +0 -317
- package/src/slash/subagents-admin.ts +0 -489
- package/src/tui/fleet-native-transcript.ts +0 -424
- package/src/tui/fleet-status.ts +0 -1139
- package/src/tui/fleet-transcript.ts +0 -591
- package/src/tui/fleet.ts +0 -1618
- package/src/tui/mouse-events.ts +0 -42
- package/src/tui/render-helpers.ts +0 -111
- package/src/tui/render.ts +0 -3824
- package/src/tui/running-tone.ts +0 -28
- package/src/tui/subagent-messages.ts +0 -305
- package/src/ui-silent-marker.ts +0 -32
- package/src/watchdog/change-signature.ts +0 -260
- package/src/watchdog/child-status.ts +0 -225
- package/src/watchdog/diff-tool.ts +0 -112
- package/src/watchdog/emission-guard.ts +0 -125
- package/src/watchdog/guidance.ts +0 -20
- package/src/watchdog/lsp-diagnostics.ts +0 -538
- package/src/watchdog/model-selection.ts +0 -187
- package/src/watchdog/permission-arbiter.ts +0 -154
- package/src/watchdog/register-child.ts +0 -136
- package/src/watchdog/register-main.ts +0 -425
- package/src/watchdog/render.ts +0 -31
- package/src/watchdog/review.ts +0 -362
- package/src/watchdog/rules.ts +0 -70
- package/src/watchdog/runtime.ts +0 -927
- package/src/watchdog/scope.ts +0 -51
- package/src/watchdog/settings.ts +0 -520
- package/src/watchdog/tool-actions.ts +0 -156
- package/src/watchdog/turn-delta.ts +0 -190
- package/src/watchdog/types.ts +0 -186
- package/src/watchdog/warning-format.ts +0 -72
- package/src/workflows/chat-progress.ts +0 -152
- package/src/workflows/host-command.ts +0 -235
- package/src/workflows/scripted-workflow.ts +0 -2733
- package/src/workflows/structured-workflow-scripts.ts +0 -177
- package/src/workflows/workflow-checklist.ts +0 -442
- package/src/workflows/workflow-child-summary.ts +0 -172
- package/src/workflows/workflow-preflight.ts +0 -297
- package/src/workflows/workflow-receipt.ts +0 -390
- package/src/workflows/workflow-resources.ts +0 -275
- package/src/workflows/workflow-reuse.ts +0 -120
- package/src/workflows/workflow-revival.ts +0 -123
- package/src/workflows/workflow-settlement.ts +0 -252
package/docs/agents.md
CHANGED
|
@@ -43,7 +43,7 @@ Builtins load at the lowest priority, so a user or project agent with the same n
|
|
|
43
43
|
| `researcher` | Web/docs research with sources: official docs, specs, benchmarks, recent changes, and a concise research brief. |
|
|
44
44
|
| `evidence-auditor` | Independent evidence review of important claims in an existing research brief. |
|
|
45
45
|
| `worker` | Implementation work, including approved oracle handoffs. It edits files, validates, and escalates unapproved decisions instead of guessing. |
|
|
46
|
-
| `reviewer` |
|
|
46
|
+
| `reviewer` | Read-only code review. It checks the implementation against the task/plan, tests, edge cases, and simplicity. |
|
|
47
47
|
| `oracle` | A second opinion before acting. It challenges assumptions, catches drift, and recommends the safest next move without editing. |
|
|
48
48
|
| `delegate` | A lightweight general delegate when you want a child agent that behaves close to the parent session. |
|
|
49
49
|
|
|
@@ -282,6 +282,36 @@ Placed external profiles are one-shot and stop-only: they cannot steer, resume,
|
|
|
282
282
|
|
|
283
283
|
pi-subagents never clones, pulls, or checks out on the machine. Generic `external-cli` commands and managed worktrees are rejected before launch; saved-machine placement accepts native Pi and only the six code-owned external profiles.
|
|
284
284
|
|
|
285
|
+
## Running a Pi child in a Rex pane on this machine
|
|
286
|
+
|
|
287
|
+
`machine: "local"` runs a native Pi child as a visible Pi in a new background tab of your own Rex session, labeled `subagent-<run id tail>`. It works wherever `machine` works: frontmatter, settings overrides, the `subagent` tool, workflow `runs.run`, chain, parallel, and dynamic-fanout steps. `local` is reserved and never looks in the Herdr catalog. The parent Pi must run inside Rex: with no `REX_SESSION`, or a session the Rex server does not confirm, the launch fails before anything starts.
|
|
288
|
+
|
|
289
|
+
The parent drives the child through the same bridge as a Herdr-placed Pi: prompt, steer, follow-up, abort, `contact_supervisor`, and results. The child Pi loads pi-subagents from its own extensions, so it must be installed at the same version. `cwd` is a directory on this machine; a relative path joins the launch directory. pi-subagents finds `rex` in `$REX_BIN_DIR`, then on `PATH`, then in the Rex server app.
|
|
290
|
+
|
|
291
|
+
A finished child keeps its tab open, with the idle Pi, until you close it; an aborted or stopped child's tab is closed. Limits: native Pi only (Claude Code, Codex, Cursor, and generic `external-cli` agents are rejected), fresh context only, and the same restrictions as a Herdr-placed Pi (no local extension paths, process environment, nested delegation, permission rules, or tool budgets).
|
|
292
|
+
|
|
293
|
+
## Running a Pi child in a Rex pane on another Mac
|
|
294
|
+
|
|
295
|
+
Name a Mac you reach over SSH in your user settings (`~/.pi/agent/settings.json`), with its repo root:
|
|
296
|
+
|
|
297
|
+
```json
|
|
298
|
+
{
|
|
299
|
+
"subagents": {
|
|
300
|
+
"machines": {
|
|
301
|
+
"workmac": { "rex": { "ssh": "100.82.67.118" }, "cwd": "~/dev/app" }
|
|
302
|
+
}
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
`machine: "workmac"` then runs a native Pi child as a visible Pi in a new background tab of the Rex session labeled `subagents` on that Mac. pi-subagents creates the session the first time and reuses it after that; if two sessions there have that label, the launch fails until you close or rename one. Every `rex` command runs on that Mac over SSH, and the bridge socket comes back through an SSH forward, so SSH must work without a prompt (`ssh <target>` once to accept the host key). A name with a `rex` entry never looks in the Herdr catalog, so Herdr does not need to be installed.
|
|
308
|
+
|
|
309
|
+
Only user settings may name a Rex host: a `rex` entry in a project's `.pi/settings.json` fails the launch, so a cloned repo cannot choose where a task runs. `cwd` can come from project or user settings, as for Herdr machines: a relative step `cwd` joins it, and an absolute or `~` path is used as given. The other Mac needs Rex, Pi on its login shell's `PATH`, and pi-subagents installed at the same version. The child edits that Mac's disk, so its changed files come from that Mac's Git state, as for a Herdr-placed child.
|
|
310
|
+
|
|
311
|
+
Programs in a Rex tab run under the Rex app's macOS privacy permissions. If Pi on that Mac reads files in Desktop, Documents, or Downloads (for example a package path in its settings), allow Rex there first: open a Rex tab on that Mac, run `ls ~/Documents`, and accept the prompt. Until then Pi waits on the prompt and the launch times out.
|
|
312
|
+
|
|
313
|
+
To watch the tab, open the `subagents` session in Rex on that Mac. To watch it from this Mac, add that Mac's Rex server to your hosts here once (`rex hosts add workmac <endpoint>`; after `rex server tailscale on` there, `rex whoami` on that Mac shows its Tailscale address). Tab lifecycle and limits are the same as for `machine: "local"`.
|
|
314
|
+
|
|
285
315
|
## Sandboxing background children with a launcher
|
|
286
316
|
|
|
287
317
|
A launcher wraps an agent's background runner in a command you choose, so that agent can run in a different sandbox from the parent session. Define the command in the user config key [`runnerLaunchers`](configuration.md#runnerlaunchers), then name it in the agent file:
|
|
@@ -359,6 +389,8 @@ Use these fields when an agent should see more:
|
|
|
359
389
|
|
|
360
390
|
Builtin agents opt into repository instruction inheritance by default so they follow repo-specific rules out of the box, but global context remains excluded unless `inheritGlobalContext: true` is set. This changes the behavior of existing agents that previously received global context as part of `inheritProjectContext: true`. `delegate` also uses append mode because its job is orchestration inside the parent workflow.
|
|
361
391
|
|
|
392
|
+
These fields and `systemPromptMode` shape a fresh child's system prompt. A forked child (`context: "fork"`) sends its parent's whole system prompt instead, project context, global context, and skills included, and gets its agent prompt in its task message (see [fork context details](tool-reference.md#fork-context-details)).
|
|
393
|
+
|
|
362
394
|
## Frontmatter reference
|
|
363
395
|
|
|
364
396
|
A full example:
|
|
@@ -411,7 +443,7 @@ tools:
|
|
|
411
443
|
- mcp:github/search_repositories
|
|
412
444
|
```
|
|
413
445
|
|
|
414
|
-
Field notes
|
|
446
|
+
### Field notes
|
|
415
447
|
|
|
416
448
|
| Field | Notes |
|
|
417
449
|
|-------|-------|
|
|
@@ -514,6 +546,7 @@ How `tools` behaves:
|
|
|
514
546
|
- `tools` omitted: the child session gets Pi's normal builtin tools.
|
|
515
547
|
- `tools` present: regular tool names become an explicit allowlist.
|
|
516
548
|
- `tools:` empty: the child session gets no tools.
|
|
549
|
+
- `tools: +codemode` or `tools: -write`: rejected. Pi's `--tools` and `defaultTools` accept `+name`/`-name` entries that edit the default tool set, but a child's `tools` list replaces that set, so name every tool the child needs, or omit `tools` and use `excludeTools` to drop one. A local agent with such an entry fails before launch. A Herdr- or Rex-placed child resolves its agent on that machine, so an entry only there fails when the pane bridge is configured, before the first prompt.
|
|
517
550
|
- `allowNestedSubagents: true`: explicitly enables child-safe nested fanout without turning omitted `tools` into an allowlist. Depth and inherited capability ceilings still apply.
|
|
518
551
|
- `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.
|
|
519
552
|
|
|
@@ -541,7 +574,7 @@ Examples:
|
|
|
541
574
|
|
|
542
575
|
### MCP tools
|
|
543
576
|
|
|
544
|
-
When [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) is not installed
|
|
577
|
+
When [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) is not installed, `mcp:server` and `mcp:server/tool` entries resolve against Pi's built-in MCP. Name the server and tool as the server reports them: `mcp:my-docs/get-item` selects the tool Pi registers as `mcp__my_docs__get_item`. The server part may also use the `-`→`_` form of its name that Pi's MCP namespace uses, such as `mcp:my_docs`. 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 child waits for the selected servers' current MCP connection attempts before its first prompt, then rejects the launch if any selected tool is missing or not available as a direct tool. Pi's MCP request timeout still bounds each connection; stopping, interrupting, timing out, or shutting down the child cancels the startup wait. An unrelated server does not delay this check.
|
|
545
578
|
|
|
546
579
|
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.
|
|
547
580
|
|
|
@@ -617,15 +650,14 @@ Agent-local `skillPath` candidates never enter Pi's parent/global skills catalog
|
|
|
617
650
|
|
|
618
651
|
## The bundled pi-subagents skill
|
|
619
652
|
|
|
620
|
-
The package bundles a `pi-subagents` skill that is automatically available to the parent agent when the extension is installed. Availability is not automatic routing or permission to delegate: the parent works directly unless the operator requests delegation in the current request or through applicable user/project instructions. Once authorized, use the smallest bounded child or workflow whose evidence, independent review, specialization, parallelism, or isolation benefit earns its overhead. It is for the orchestrating parent only: child subagents never receive it, and
|
|
653
|
+
The package bundles a `pi-subagents` skill that is automatically available to the parent agent when the extension is installed. Availability is not automatic routing or permission to delegate: the parent works directly unless the operator requests delegation in the current request or through applicable user/project instructions. Once authorized, use the smallest bounded child or workflow whose evidence, independent review, specialization, parallelism, or isolation benefit earns its overhead. It is for the orchestrating parent only: fresh child subagents never receive it, and a child's own context is filtered to strip parent-only orchestration instructions. A forked child is the exception: it keeps the history, system prompt, and tool declarations it inherited as the parent sent them, so it sees this skill in the parent's skills list and the parent's subagent catalog. It receives its own instructions, including its subagent boundary, in its task message, and its first request reuses the parent's prompt cache (see [fork context details](tool-reference.md#fork-context-details)).
|
|
621
654
|
|
|
622
655
|
What it covers:
|
|
623
656
|
|
|
624
|
-
- **
|
|
625
|
-
- **
|
|
626
|
-
- **
|
|
627
|
-
- **
|
|
628
|
-
- **
|
|
629
|
-
- **Control and diagnostics**: attention signals, soft interrupts, status, and the `doctor` action.
|
|
657
|
+
- **Calls**: the common `subagent` calls, workflow script and resume shapes, and async waiting rules.
|
|
658
|
+
- **Delegation rules**: when to delegate at all, what every child brief contains, one writer per worktree, fresh or forked context, and what to do when a lane fails.
|
|
659
|
+
- **Prompt workflow recipes**: how to apply the packaged techniques directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command: parallel review, review loop, parallel research, gather-context-and-clarify, parallel cleanup, and oracle consultation.
|
|
660
|
+
- **Orchestration**: splitting work into lanes, review loops, finding disposition, and gate-failure triage.
|
|
661
|
+
- **Lookups**: which `guide` section answers each rarer question, so the skill does not copy this reference.
|
|
630
662
|
|
|
631
663
|
If you are writing an agent that has been asked to orchestrate subagents, the bundled skill helps it behave correctly without guessing the patterns. If you are a human user, you do not need to read it; the README and prompt shortcuts encode the same workflows in user-facing form.
|
package/docs/configuration.md
CHANGED
|
@@ -80,9 +80,9 @@ A local Pi child whose selected model is a virtual model (`pi.registerVirtualMod
|
|
|
80
80
|
|
|
81
81
|
## Tool activation lifecycle
|
|
82
82
|
|
|
83
|
-
|
|
83
|
+
When the model can take a new tool mid-conversation (see [`toolActivation`](#toolactivation)), a fresh unrestricted parent starts with only `subagents_enable` active while `subagent`, `bg_wait`, and `subagent_supervisor` stay registered but inactive. Calling `subagents_enable({})` preserves unrelated active tools and exposes all three on the next model request. It does not launch a child or infer authority from prompt keywords. `bg_wait` is also declared without `subagent` once another extension registers a [background-work provider](extension-api.md#background-work-provider-api), because only `bg_wait` waits for that work. `subagent_supervisor`, which answers this session's children, is also declared when a child request reaches a session that does not have it, such as one from a scheduled run. With other models, a fresh parent starts with `subagent`, `bg_wait`, and `subagent_supervisor` active and no `subagents_enable`. `contact_supervisor` is active whenever `subagent` is, with the definition children use, so a forked child declares the same tools as its parent and can reuse its prompt cache; called in a session that is not a subagent, it returns an error.
|
|
84
84
|
|
|
85
|
-
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.
|
|
85
|
+
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. The recorded `bg_wait` and `subagent_supervisor` selections are restored the same way, so a session that declared them, for example on an earlier version, keeps them. 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`, `bg_wait`, and `subagent_supervisor` availability. If Pi's allowlist or exclusions remove the loader, the extension does not hide `subagent` or `bg_wait`; if they remove `subagent`, the loader reports it unavailable. The host version is not read from disk, so in-process hosts such as pi-web activate the same way as the Pi CLI.
|
|
86
86
|
|
|
87
87
|
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.
|
|
88
88
|
|
|
@@ -98,7 +98,7 @@ Controls how a new parent session offers the `subagent` tool. The default is `"a
|
|
|
98
98
|
- `"dynamic"`: every new session starts with the loader, whatever the model. This was the behavior before `toolActivation` existed.
|
|
99
99
|
- `"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.
|
|
100
100
|
|
|
101
|
-
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.
|
|
101
|
+
The choice is made at session start or tree navigation, and only for a session with no messages. If a compaction that kept no tool checkpoint dropped the record of this choice, the session is decided again as a new session would be; tool selections recorded after that compaction (for `bg_wait` or another extension's tools) are not evidence that the choice survived. 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.
|
|
102
102
|
|
|
103
103
|
## `toolDescriptionMode`
|
|
104
104
|
|
|
@@ -108,7 +108,15 @@ The choice is made at session start or tree navigation, and only for a session w
|
|
|
108
108
|
|
|
109
109
|
Controls the parent-facing `subagent` tool description registered at startup. The default registers the short execution/safety description, which states the delegation authorization rule, plus a one-line `promptSnippet`. Explicit `"compact"` uses the same description without the snippet; `"full"` adds workflow and management detail, also without the snippet. All modes retain the same flat parameter schema. Extended examples and recipes are available on demand through `action:"guide"` and the bundled pi-subagents skill; full mode is not an exhaustive manual. Count the default snippet as well as the tool definition when comparing prompt footprints.
|
|
110
110
|
|
|
111
|
-
`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. The change applies to new sessions; a resumed session keeps the tool definition and prompt text it already declared, so its prompt cache stays valid.
|
|
111
|
+
`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. The change applies to new sessions; a resumed session keeps the tool definition and prompt text it already declared, so its prompt cache stays valid. To apply it to resumed sessions too, set [`pinToolDeclarations`](#pintooldeclarations) to `false`.
|
|
112
|
+
|
|
113
|
+
## `pinToolDeclarations`
|
|
114
|
+
|
|
115
|
+
```json
|
|
116
|
+
{ "pinToolDeclarations": false }
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Pi records each tool definition and prompt section a session declares, and declares any difference again before the next request; a changed definition makes the provider read the whole conversation again without its prompt cache. So by default (`true`) a resumed or reloaded session keeps the `subagent`, `bg_wait`, and `subagents_enable` definitions and the pi-subagents prompt text it already declared, and only a session that never declared a tool gets its current definition. With `false`, every parent session gets the current definitions (subagent children stay pinned): a long-lived session picks up an upgrade, a changed `toolDescriptionMode`, `disabledFeatures`, or an edited custom description on the next restart, and pays one cache miss on its next request. Restart Pi after changing it.
|
|
112
120
|
|
|
113
121
|
## `disabledFeatures`
|
|
114
122
|
|
|
@@ -116,7 +124,7 @@ Controls the parent-facing `subagent` tool description registered at startup. Th
|
|
|
116
124
|
{ "disabledFeatures": ["watchdog", "panes", "preflight", "lane-metadata", "gates"] }
|
|
117
125
|
```
|
|
118
126
|
|
|
119
|
-
Removes feature groups you do not use from the `subagent` tool. Each listed feature loses its top-level parameters from the model-facing schema and its `options` keys are rejected, 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
|
|
127
|
+
Removes feature groups you do not use from the `subagent` tool. Each listed feature loses its top-level parameters from the model-facing schema and its `options` keys are rejected, 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. Every `{ action: "guide" }` response starts with a notice: a topic lists what is disabled, and a section points to the `tool-reference` topic for that list. With `workflow-scripts` disabled, the notice also says to use the top-level `tasks` or `chain` fields instead. 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.
|
|
120
128
|
|
|
121
129
|
| Feature | Parameters removed | Actions rejected |
|
|
122
130
|
|---|---|---|
|
|
@@ -142,8 +150,8 @@ Disabling a per-call option removes only the per-call override. Configured defau
|
|
|
142
150
|
|
|
143
151
|
`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:
|
|
144
152
|
|
|
145
|
-
- `tasks: [{ agent, task }, ...]` runs the children in parallel and returns their results in order.
|
|
146
|
-
- `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.
|
|
153
|
+
- `tasks: [{ agent, task, cwd?, model? }, ...]` runs the children in parallel and returns their results in order.
|
|
154
|
+
- `chain: [step, ...]` runs steps in order. A step is `{ agent, task?, as?, cwd?, model? }` or a parallel group `{ parallel: [{ agent, task, cwd?, model? }, ...] }`. A group waits for all of its children. `cwd` and `model` are optional and apply to that one child.
|
|
147
155
|
|
|
148
156
|
A top-level `task` is the original request. Tasks can use three placeholders:
|
|
149
157
|
|
|
@@ -186,6 +194,27 @@ With `"summary"`, a tool result looks like this:
|
|
|
186
194
|
✓ reviewer · completed
|
|
187
195
|
```
|
|
188
196
|
|
|
197
|
+
## `enableSlashCommands`
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
{ "enableSlashCommands": false }
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Set to `false` to register none of the pi-subagents slash commands (`/run`, `/subagents`, `/subagents-fleet`, `/subagents-watchdog`, `/prompt-workflow`, and the rest) and no [`foregroundDetachShortcut`](#foregrounddetachshortcut). The `subagent` tool, RPC, the async widget, and the extension's other features are unchanged. Prompt templates whose frontmatter has `chain:` launch through `/prompt-workflow`, so they stop working too. Defaults to `true`. Restart Pi or run `/reload` after changing it.
|
|
204
|
+
|
|
205
|
+
The package's prompt shortcuts, such as `/parallel-review` and `/review-loop`, are Pi prompt templates, not commands, so this setting leaves them alone. The same goes for its skills (`pi-subagents` and `council-mode`) and built-in agents. To turn them off, use Pi's package filter for prompts and skills and `disableBuiltins` for the agents, in Pi's `settings.json`. This turns off every prompt, the `council-mode` skill and every built-in agent:
|
|
206
|
+
|
|
207
|
+
```json
|
|
208
|
+
{
|
|
209
|
+
"packages": [
|
|
210
|
+
{ "source": "npm:pi-subagents", "prompts": [], "skills": ["!council-mode"] }
|
|
211
|
+
],
|
|
212
|
+
"subagents": { "disableBuiltins": true }
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
A `!` entry such as `"!review-loop.md"` drops one file, and `[]` drops all of that type. `subagents.agentOverrides.<name>.disabled: true` turns off one built-in agent instead of all of them ([agents.md](agents.md)). `pi config` toggles the package's prompts and skills interactively.
|
|
217
|
+
|
|
189
218
|
## `foregroundDetachShortcut`
|
|
190
219
|
|
|
191
220
|
```json
|
|
@@ -226,6 +255,14 @@ Set `enabled` to `false` (or remove the block) as a kill switch. In that state,
|
|
|
226
255
|
|
|
227
256
|
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.
|
|
228
257
|
|
|
258
|
+
## `autoResume`
|
|
259
|
+
|
|
260
|
+
```json
|
|
261
|
+
{ "autoResume": false }
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Default `true`. When a session is reopened (`pi -c`, `pi --session`, `/resume`) or reloaded (`/reload`), its own async workflows that a Pi exit or a reload interrupted in the last 24 hours are resumed once, without delaying session start; set `autoResume` to `false` to resume them only by hand. A one-shot `pi -p` run does not auto-resume, so it does not wait on the workflow. See [Workflows](workflows.md).
|
|
265
|
+
|
|
229
266
|
## `runnerLaunchers`
|
|
230
267
|
|
|
231
268
|
```json
|
|
@@ -270,7 +307,7 @@ Controls how resolved fork launches prepare the inherited session. The default `
|
|
|
270
307
|
|
|
271
308
|
Child-visible spilled items contain only the model summary and a stable `{ batchId, itemId }` recovery ref. Raw bodies and their digests, source entry ids, labels, sizes, and tool metadata go to a private `0600` sidecar next to the child session. This release does not add a recovery command or expose that payload to the child model.
|
|
272
309
|
|
|
273
|
-
Pruned forks keep the normal `parentSession` link, child cwd alignment, and fork thinking-block sanitization (signed Anthropic thinking blocks are stripped; the child keeps its requested thinking level). Missing model or auth, invalid or incomplete summary JSON, budget overflow, recovery validation failure, and raw overflow leakage all stop the launch before child spawn. The extension never falls back to a full fork or refs-only context after a prune failure.
|
|
310
|
+
Pruned forks keep the normal `parentSession` link, child cwd alignment, and fork thinking-block sanitization (a pruned fork rewrites inherited content, so its signed and redacted Anthropic thinking blocks are stripped; the child keeps its requested thinking level). Missing model or auth, invalid or incomplete summary JSON, budget overflow, recovery validation failure, and raw overflow leakage all stop the launch before child spawn. The extension never falls back to a full fork or refs-only context after a prune failure.
|
|
274
311
|
|
|
275
312
|
## `fleetView`
|
|
276
313
|
|
|
@@ -351,7 +388,15 @@ Reports are sent only from an interactive TUI session whose standard output is a
|
|
|
351
388
|
| failed, partial, or rejected | `error` |
|
|
352
389
|
| stopped or paused | `idle` |
|
|
353
390
|
|
|
354
|
-
Each record's `title` is the agent names or workflow key, and its `msg` is the current tool while working, or the outcome. Neither includes the task text. Finished runs keep their `done`, `error`, or `idle` record after they leave the async widget, for as long as they are in Fleet's recent history (the last 20 finished runs). Records of runs this session no longer tracks, for example after switching sessions, are cleared. At most 64 records are shown: running and waiting runs first, then finished ones, most recently updated first; older finished records are cleared to make room. When the extension is reloaded or the session is replaced, it clears every record it sent and the new session reports the runs it still tracks. Pi
|
|
391
|
+
Each record's `title` is the agent names or workflow key, and its `msg` is the current tool while working, or the outcome. Neither includes the task text. Finished runs keep their `done`, `error`, or `idle` record after they leave the async widget, for as long as they are in Fleet's recent history (the last 20 finished runs). Records of runs this session no longer tracks, for example after switching sessions, are cleared. At most 64 records are shown: running and waiting runs first, then finished ones, most recently updated first; older finished records are cleared to make room. When the extension is reloaded or the session is replaced, it clears every record it sent and the new session reports the runs it still tracks. Pi reports its own state on the root record and clears every record, these included, when it quits, suspends with Ctrl+Z, or opens an external editor. After a suspend, this extension sends its records again; after an external editor, each record comes back the next time it changes. Foreground runs are not reported, and tmux drops these sequences unless you configure passthrough.
|
|
392
|
+
|
|
393
|
+
## `activeRunsPrompt`
|
|
394
|
+
|
|
395
|
+
```json
|
|
396
|
+
{ "activeRunsPrompt": true }
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
Adds a short `active_subagents` section to the parent's system prompt while this session has queued or running background runs, so the model remembers work it launched earlier instead of starting it again. Off by default. Each run gets one line, for example `- <run id> researcher (chain, step 2/3)`, built from in-memory run state with no file reads; at most 10 runs are listed, then a `+N more` line. The line holds only the run id, agents, mode, and chain step (task text is redacted at launch), so the section changes only when a run starts, finishes, or moves to another chain step. Pi sends such a change as a mid-conversation system update where the provider supports it; on other providers it rebuilds the system prompt, so the prompt cache starts over on those turns. Nothing is added when no run is active.
|
|
355
400
|
|
|
356
401
|
## `waitTool`
|
|
357
402
|
|
|
@@ -361,8 +406,8 @@ Each record's `title` is the agent names or workflow key, and its `msg` is the c
|
|
|
361
406
|
|
|
362
407
|
`defaultTimeoutMs` sets the blocking window used when a `bg_wait` call omits `timeoutMs`; explicit call values win, followed by this setting, then the 30-minute fallback. `bg_wait` is the only registered wait tool. When the window elapses, the tool returns a non-error `window_elapsed` result with the still-active work identities, and that work keeps running. Set `enabled` to `false` to make direct calls return immediately instead of blocking. The default is enabled. You can also set `"waitTool": false`; set `PI_SUBAGENT_WAIT_TOOL_ENABLED=false` (or `0`, `off`, `disabled`) to override config for one process. The effective enabled and default-timeout values are passed explicitly to child runtimes. Headless `agent_end` auto-drain retains its own strict deadline and fails if required work remains unresolved. Invalid config or environment values fail instead of being coerced.
|
|
363
408
|
|
|
364
|
-
Blocking `bg_wait({ id: "..." })` keeps the current tool call open until that run changes. By default it returns when a run needs attention. Use `bg_wait({ stopOnAttention: false })` only for run-to-completion flows that should wait through idle or long-thinking attention; supervisor/contact requests still stop the wait. A steer or follow-up the operator sends while a blocking wait is open also ends it, with a non-error `user_input` result listing the still-active work, so the message reaches the model without waiting out the window. In a long-lived interactive parent session, `bg_wait({ id: "...", nonBlocking: true })` instead resolves the prefix once, persists the exact run identity, returns a subscription token immediately, and wakes that session on completion, failure, attention, reconciliation failure, or timeout. Use it for provider, detached, or other background work without a native completion notification; ordinary async subagent runs notify the parent natively and do not need a wait subscription. Armed subscriptions appear in ordinary `subagent({ action: "status" })` output and are not counted as active child work. Native completion notifications wake the session through the Pi process that launched the run, while that process is still running; a session reopened in a new process does not get that wake and should read the result with `subagent({ action: "status" })`. `nonBlocking` subscriptions need a host with a UI context, such as interactive or RPC mode; plain SDK embedding without a UI context rejects them.
|
|
365
409
|
|
|
410
|
+
Blocking `bg_wait({ id: "..." })` keeps the current tool call open until that run changes. By default it returns when a run needs attention, even when the run is still working normally, for example a `bash` command open longer than `activeNoticeAfterMs`; the result then says the run is still running. Use `bg_wait({ stopOnAttention: false })` for run-to-completion flows: it waits through idle time, a tool held open, or repeated tool failures, and still ends for a supervisor/contact request, a finished run, the timeout, user input, or abort. A steer or follow-up the operator sends while a blocking wait is open also ends it, with a non-error `user_input` result listing the still-active work, so the message reaches the model without waiting out the window. In a long-lived interactive parent session, `bg_wait({ id: "...", nonBlocking: true })` instead resolves the prefix once, persists the exact run identity, returns a subscription token immediately, and wakes that session on completion, failure, attention, reconciliation failure, or timeout. Use it for provider, detached, or other background work without a native completion notification; ordinary async subagent runs notify the parent natively and do not need a wait subscription. Armed subscriptions appear in ordinary `subagent({ action: "status" })` output and are not counted as active child work. A native completion notification goes to the Pi process that launched the run while that process is running; once it has exited, the session gets the result the next time it is open in any Pi. `nonBlocking` subscriptions need a host with a UI context, such as interactive or RPC mode; plain SDK embedding without a UI context rejects them.
|
|
366
411
|
This is different from `waitTool.enabled=false`, which returns immediately without registering any future wake. Provider items remain available only to blocking fleet-wide waits; non-blocking subscriptions require one async or remembered detached foreground run id.
|
|
367
412
|
|
|
368
413
|
## `resultScanLogging`
|
|
@@ -459,7 +504,7 @@ The budget counts single launches, expanded `tasks`/`count`, static chain steps
|
|
|
459
504
|
|
|
460
505
|
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.
|
|
461
506
|
|
|
462
|
-
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.
|
|
507
|
+
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. Three cases release without that proof: a run whose runner failed before child startup, recorded as `not-started` with an error; an async workflow child whose launch failed before any runner existed, recorded as a failed roster step with an error and no status or runner files in its run directory; and the abandoned-slot policy below. Resume transfers the source slot without a second charge. Dismissal and history cleanup do not release capacity.
|
|
463
508
|
|
|
464
509
|
When the runner is gone but process cleanup proof remains unknown, configure a bounded policy reclaim under `capacity.abandonedSlotReleaseAfterMs`:
|
|
465
510
|
|
|
@@ -467,9 +512,9 @@ When the runner is gone but process cleanup proof remains unknown, configure a b
|
|
|
467
512
|
{ "maxActiveAsyncRunsPerSession": 4, "capacity": { "abandonedSlotReleaseAfterMs": 1200000 } }
|
|
468
513
|
```
|
|
469
514
|
|
|
470
|
-
The default is `1200000` milliseconds (20 minutes).
|
|
515
|
+
The default is `1200000` milliseconds (20 minutes). For a top-level run, the policy releases only a failed terminal run whose runner PID is dead and whose last activity is older than the threshold (workflow children follow the rule below). A live or unknown PID, a top-level run in a non-failed terminal state, a recent run, or missing activity timestamp retains the slot. Set the value to `false` to keep strict retention. Valid configured durations range from 5 minutes through 24 hours. Policy release is reported as `abandoned-timeout` with `processProof: unknown`; it is not observed process-terminal proof and may reclaim capacity while an orphan child still exists.
|
|
471
516
|
|
|
472
|
-
A terminal workflow whose controller is gone uses the same policy when async children lack proof: the workflow must have ended longer ago than the threshold, and every async child without proof must
|
|
517
|
+
A terminal workflow whose controller is gone uses the same policy when async children lack proof: the workflow must have ended longer ago than the threshold, and every async child without proof must be a terminal run (failed, stopped, complete, partial or rejected, but not paused) with a dead runner PID in this PID namespace and old activity. A stopped or completed child counts too, because a child whose launching Pi process is gone never gets observed proof however it ended. Any other child without proof keeps the slot. The release event lists those children and their states under `abandonedChildren`.
|
|
473
518
|
|
|
474
519
|
This limit bounds current top-level async load. It is separate from cumulative `maxSubagentSpawnsPerSession`, `maxSubagentSpawnsPerRun`, and `globalConcurrencyLimit`.
|
|
475
520
|
|
|
@@ -554,7 +599,7 @@ export PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT=/path/to/pi-coding-agent-packag
|
|
|
554
599
|
|
|
555
600
|
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.
|
|
556
601
|
|
|
557
|
-
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 (
|
|
602
|
+
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 (a verified Pi-owned JavaScript entry, then this override, then any other Pi-owned entry such as an extensionless `.bin/pi` symlink, then the embedding host's dependency, 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. For an embedding host, discovery walks ancestor `node_modules` directories from the host entry's canonical location to find its Pi dependency before using the extension's install tree. 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, and foreground CLI resolution fails instead of falling back to another install or `pi` on `PATH`.
|
|
558
603
|
|
|
559
604
|
## `intercomBridge`
|
|
560
605
|
|
package/docs/extension-api.md
CHANGED
|
@@ -129,6 +129,7 @@ Method notes:
|
|
|
129
129
|
Capability advertisements on `ping`:
|
|
130
130
|
|
|
131
131
|
- `events.asyncComplete` — exact process-local completion correlation after RPC `spawn`.
|
|
132
|
+
- `events.jobsChanged`, `events.asyncStarted`, `events.childStatus`, `events.processTerminal` — the event names a host can listen to instead of polling `status` (see [Refresh a host view without polling](#refresh-a-host-view-without-polling)).
|
|
132
133
|
- `managementActions` — exact schedule management actions accepted by RPC `manage`.
|
|
133
134
|
- `launchResolvedExtensions` — the optional launch-resolved extension projection in status details.
|
|
134
135
|
- `runtimeAcknowledgedExtensions` — the optional child-runtime acknowledgement projection and event name.
|
|
@@ -141,6 +142,20 @@ Capability advertisements on `ping`:
|
|
|
141
142
|
|
|
142
143
|
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.
|
|
143
144
|
|
|
145
|
+
### Refresh a host view without polling
|
|
146
|
+
|
|
147
|
+
A host that shows background subagent activity (an editor panel, a footer, a status bar) can read `status` when something changed instead of on a timer:
|
|
148
|
+
|
|
149
|
+
1. Subscribe to the names under `ping.events`: `jobsChanged`, `asyncStarted`, `childStatus`, `asyncComplete`, and `processTerminal`.
|
|
150
|
+
2. Read `status` once, when the host starts or reconnects. Events are not replayed after a host restart, and subscribing first means a change during that read still triggers another one.
|
|
151
|
+
3. When any of the events fires, read `status` again. Events can arrive in bursts and can repeat, so coalesce them in the host, for example one `status` read per 250 ms, and keep a refresh that arrives while a read is in flight for after it ends.
|
|
152
|
+
|
|
153
|
+
`subagent:jobs-changed` carries only `{ version: 1 }`. It fires whenever the parent's background job view changes: a run starts, moves to another step (no other event reports a chain or parallel run's step changes), reports new activity (a tool, a turn, tokens, or output), finishes, or is cleared from the widget. While a child streams output this can be about once per second per run. Starts and finishes fire right away; step and activity changes fire when the parent next reads the run's status file, which on macOS is a check every 5 seconds. It fires only in sessions with a UI, which covers interactive and RPC mode; print mode (`pi -p`) and SDK embeddings without a UI do not get it. It fires even when the async widget is turned off.
|
|
154
|
+
|
|
155
|
+
Foreground children are not background jobs. Their progress arrives as updates to the parent's `subagent` tool call (Pi's `tool_execution_update` events), with the `details.results[]` rows described above.
|
|
156
|
+
|
|
157
|
+
To rebuild what ran in a session after a reload, read the records the session file already holds: the `subagent` tool result's `details.results[]` for foreground runs and the `subagent-notify` message's `details.runs[]` for background runs (see [Host session lifetime and completion wakes](#host-session-lifetime-and-completion-wakes)). The `cost` method returns per-child rows built from the same records.
|
|
158
|
+
|
|
144
159
|
### Direct async launch correlation
|
|
145
160
|
|
|
146
161
|
Direct async runs retain their originating `toolCallId` in status and result
|
|
@@ -212,14 +227,14 @@ This contract is process-local. It does not register agents in child sessions or
|
|
|
212
227
|
|
|
213
228
|
## External jobs in FleetView
|
|
214
229
|
|
|
215
|
-
Use
|
|
230
|
+
Use `@xzzpig/pi-subagents/external-runs` to publish display-only current-session jobs owned by another extension:
|
|
216
231
|
|
|
217
232
|
```ts
|
|
218
233
|
import {
|
|
219
234
|
registerExternalRun,
|
|
220
235
|
updateExternalRun,
|
|
221
236
|
unregisterExternalRun,
|
|
222
|
-
} from "pi-subagents/external-runs";
|
|
237
|
+
} from "@xzzpig/pi-subagents/external-runs";
|
|
223
238
|
|
|
224
239
|
registerExternalRun({
|
|
225
240
|
id: "dependency-review",
|
|
@@ -353,6 +368,33 @@ Results:
|
|
|
353
368
|
|
|
354
369
|
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.
|
|
355
370
|
|
|
371
|
+
Both `:update` and terminal `:response` optionally include one bounded `providerDiagnostics` snapshot:
|
|
372
|
+
|
|
373
|
+
```ts
|
|
374
|
+
{
|
|
375
|
+
errorCount: number,
|
|
376
|
+
lastError?: {
|
|
377
|
+
kind: "rate_limited" | "transient_other" | "unknown",
|
|
378
|
+
message: string,
|
|
379
|
+
at: number,
|
|
380
|
+
},
|
|
381
|
+
retry?: {
|
|
382
|
+
phase: "backoff" | "in_flight",
|
|
383
|
+
attempt: number,
|
|
384
|
+
maxAttempts: number,
|
|
385
|
+
delayMs: number,
|
|
386
|
+
scheduledAt: number,
|
|
387
|
+
},
|
|
388
|
+
}
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
- Coverage is **observed assistant-request errors and Pi retries**, not every provider-internal HTTP attempt. Healthy long reasoning does not invent diagnostics; absence means no observation, not proof that no internal retry happened.
|
|
392
|
+
- `errorCount` increments once per failed assistant `message_end` (`stopReason: "error"`), including repeated identical errors and errors without an `errorMessage`. It does not count retry scheduling, tool failures, aborts, or compaction. The first error is reported immediately, even with no output or tokens and before Pi schedules any retry.
|
|
393
|
+
- Only the failed message's `errorMessage` is classified, never assistant content or tool text. `rate_limited` requires explicit throttling evidence. Text that mentions quota or billing, or says credits, balance, or an account or usage limit is exhausted, is reported as `unknown`, even when it also carries throttling or transient wording, so account exhaustion never looks like transient throttling. Other Pi-recognized transient errors use `transient_other`; anything else uses `unknown`. This classification is observational and does not change Pi's retry policy or the delegation's status/error behavior.
|
|
394
|
+
- `lastError.message` is a short fixed safe description, **not** the raw provider error/body. Raw diagnostics remain in existing child artifacts. No HTTP status or provider code is inferred or exposed here. `at` and `scheduledAt` are observation-time Unix timestamps in milliseconds.
|
|
395
|
+
- `auto_retry_start` schedules `backoff`; `attempt` is the 1-based retry attempt, `maxAttempts` is Pi's retry budget, and `delayMs` is Pi's planned delay, **not** a claimed server `Retry-After`. The next `agent_start`/`turn_start` changes the phase to `in_flight`. `auto_retry_end` ends the sequence after success, exhaustion, or cancellation; it is not a backoff-finished event.
|
|
396
|
+
- Cumulative error history survives recovery and unrelated replacement updates. `retry` is active-only and is absent from every terminal response, including cancellation and timeout. Historical errors alone do not turn a recovered completed result into a failure.
|
|
397
|
+
|
|
356
398
|
Bounds:
|
|
357
399
|
|
|
358
400
|
- Schemas are capped at 64 KiB; tasks and returned text/structured values are capped at 1 MiB, with smaller bounds on identity/configuration strings and a maximum `timeoutMs` of 2,147,483,647.
|
|
@@ -388,6 +430,8 @@ const restriction = registerSubagentCapabilityCeiling({
|
|
|
388
430
|
// restriction.dispose() removes only this provider's registration.
|
|
389
431
|
```
|
|
390
432
|
|
|
433
|
+
Register with **`ctx.sessionManager.getSessionId()`**; a ceiling registered by session file path does not apply.
|
|
434
|
+
|
|
391
435
|
Semantics:
|
|
392
436
|
|
|
393
437
|
- Active registrations intersect their `allowedTools` and `allowedAgents` sets and OR `denyExtensions`.
|
|
@@ -413,16 +457,16 @@ const dispose = registerBackgroundWorkProvider({
|
|
|
413
457
|
name: "my-background-extension",
|
|
414
458
|
wakeChannels: ["my-extension:job-finished"],
|
|
415
459
|
listActiveWork: (context) => jobs
|
|
416
|
-
.filter((job) => job.status === "running" && (!context || job.ownerSessionId
|
|
460
|
+
.filter((job) => job.status === "running" && (!context || context.sessionIds.includes(job.ownerSessionId)))
|
|
417
461
|
.map((job) => ({ id: job.id, sessionId: job.ownerSessionId })),
|
|
418
|
-
reconcile: ({
|
|
462
|
+
reconcile: ({ sessionIds, nowMs }) => reconcileJobs(sessionIds, nowMs),
|
|
419
463
|
});
|
|
420
464
|
```
|
|
421
465
|
|
|
422
466
|
Semantics:
|
|
423
467
|
|
|
424
|
-
- Each item needs a stable provider-local ID and the
|
|
425
|
-
- `listActiveWork` receives an optional `{ sessionId, nowMs }` context during snapshots.
|
|
468
|
+
- Each item needs a stable provider-local ID and the session that owns it, as either `ctx.sessionManager.getSessionId()` or the session file path (`ctx.sessionManager.getSessionFile()`); both are accepted. `bg_wait` captures those identities rather than a count, so one job finishing while another starts still satisfies first-completion waits without losing the replacement.
|
|
469
|
+
- `listActiveWork` receives an optional `{ sessionId, sessionIds, nowMs }` context during snapshots, and `reconcile` receives the same fields. `sessionIds` holds every form of the current session (its file path when it has one, and its session id); `sessionId` is the first of them. Providers can use them to avoid scanning unrelated work; existing zero-argument `() => items` providers continue to work, and returned items are still validated and filtered to the current session. Each provider is called once per snapshot.
|
|
426
470
|
- It filters snapshots to the active session, fails closed if a provider disappears while its work is tracked, and surfaces malformed snapshots or provider errors with provider context.
|
|
427
471
|
- Wake channels only shorten polling; validated snapshots remain authoritative.
|
|
428
472
|
- Providers share a registry through `Symbol.for("pi-subagents.background-work.v1")`, allowing independently loaded extension modules to meet in one Pi process.
|
|
@@ -432,6 +476,10 @@ Children do not gain provider tools or extensions automatically. Add `bg_wait` t
|
|
|
432
476
|
|
|
433
477
|
Local foreground children never load the parent's ambient extensions: they share the parent's process, and loading them would start a second copy of every ambient extension, including this one, inside it. They do inherit the providers the parent's extensions registered, so a provider extension's models resolve in a local foreground child. Pane-native remote foreground children instead use the remote machine's provider discovery and configuration. Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) must run as background children (`async: true`), which load the ambient extensions inside the detached runner process unless the agent sets `extensions` or the capability ceiling denies extensions.
|
|
434
478
|
|
|
479
|
+
The runner hosts many child sessions in one process and keeps working after each one ends: a background child's extensions see `session_shutdown` with reason `"quit"` in print mode, but the process does not exit with it. An extension that acts on process exit at that point (for example by force-exiting a headless run) should first check `process.env.PI_SUBAGENT_RUNNER_PID === String(process.pid)`, which is true only inside the runner. `PI_SUBAGENT_CHILD=1` cannot make that distinction: processes spawned from a child, such as a headless `pi` started by its bash tool, inherit both variables but have their own pid.
|
|
480
|
+
|
|
481
|
+
A local foreground child ends the same way, but it runs inside the parent Pi process, which is not a runner and sets no marker. An extension configured into a foreground child (through the agent's `extensions` or `subagentOnlyExtensions`) must not act on process exit at `session_shutdown`.
|
|
482
|
+
|
|
435
483
|
## External job provider bridge
|
|
436
484
|
|
|
437
485
|
Extensions that own long-running advisor jobs can register a process-local provider for `runner.type: external-job` agents:
|
|
@@ -596,7 +644,7 @@ The API returns discriminated structured results with canonical project root, bi
|
|
|
596
644
|
|
|
597
645
|
A host that embeds this extension owns whether completion wakes can be delivered at all.
|
|
598
646
|
|
|
599
|
-
Ordinary async and foreground completion wakes use `registerSubagentNotify` and `sendCompletion`. They listen for completion events and deliver through `pi.sendMessage(..., { triggerTurn })`. When the parent is idle, every pi-subagents notice that should start a turn (completions, supervisor asks, control and steering notices, wait subscriptions)
|
|
647
|
+
Ordinary async and foreground completion wakes use `registerSubagentNotify` and `sendCompletion`. They listen for completion events and deliver through `pi.sendMessage(..., { triggerTurn })`. When the parent is idle, every pi-subagents notice that should start a turn (completions, supervisor asks, control and steering notices, wait subscriptions) starts the run itself with `triggerTurn: true`; Pi runs `before_agent_start` for that run, so extension-set system prompt sections stay in it. Each such notice ends with what the parent should do (for completions, `Parent action: ...`), and no separate user message is sent. If another extension's wake (pi-intercom's, through the shared `Symbol.for("pi.idle-wake.v1")` reservation) is already starting the run, the notice is appended without a turn and that run picks it up. A busy parent still gets the notice as a steering message. After the user aborts a parent run in a host with a UI, these notices are only appended, with no turn, until the next parent run starts. Session shutdown stops the result watcher and disposes this completion notifier. `createWaitSubscriptionManager` is separate: it is the explicit non-blocking `bg_wait` subscription path for work without native notification, not the ordinary completion wake path.
|
|
600
648
|
|
|
601
649
|
Each completion notice is a custom message with `customType: "subagent-notify"`. Its `content` is the text the model reads. Pi does not send `details` to the model, so hosts can use it to match a notice to its runs by id without parsing the text. `details.runs` has one entry per finished run, in the order of the notice. A grouped notice has several entries. Each entry has `agent` and `status` (`completed`, `failed`, `paused` or `stopped`). When known, an entry also has these fields:
|
|
602
650
|
|
|
@@ -612,7 +660,7 @@ Detached children do not stop when the session does. They are the host process's
|
|
|
612
660
|
|
|
613
661
|
This matters because "is the parent busy?" is the wrong idle signal. A parent that launches a detached run and hands control back — which is what the async launch output tells it to do — is not prompting, streaming, compacting, or running a shell command. A host that reaps sessions on those signals alone will dispose exactly the session that was waiting to be woken.
|
|
614
662
|
|
|
615
|
-
When pi-subagents runs inside a compatible pi-web host, it discovers the versioned `Symbol.for("@agegr/pi-web/session-liveness/v1")` registry and registers one provider for the current session. The provider reports live `queued`/`running` async jobs, active nested descendants (including foreground routes retained after their direct parent settles), foreground controls that still have a scheduling owner or active child, async runs that ended but whose result has not reached the parent (including a rejected send waiting for retry), completion notifications until Pi starts the wake message (`message_start`), even when Pi queued it behind the current turn or past `agent_settled`, and a
|
|
663
|
+
When pi-subagents runs inside a compatible pi-web host, it discovers the versioned `Symbol.for("@agegr/pi-web/session-liveness/v1")` registry and registers one provider for the current session. The provider reports live `queued`/`running` async jobs, active nested descendants (including foreground routes retained after their direct parent settles), foreground controls that still have a scheduling owner or active child, async runs that ended but whose result has not reached the parent (including a rejected send waiting for retry), completion notifications until Pi starts the wake message (`message_start`), even when Pi queued it behind the current turn or past `agent_settled`, and a turn-triggering notice sent to an idle parent until its run starts (`agent_start`). Accepted wakes remain owned by the same Pi session manager and session UUID across extension reloads, until they start. Independent session managers never share this ownership, and changing the UUID on an existing manager discards the old session's wakes. A wake message Pi discards without starting keeps the session live until the session shuts down for a reason other than reload. An idle wake whose run has not started 10 seconds later, while the parent is idle, stops holding the session live on its own; a completion notice whose run never started is still held by the undelivered-notice tracking above until the session shuts down, which records it for replay at the next start. Retained terminal history, future schedules, and wait subscriptions do not make a session live by themselves. The registration is replaced on session changes and released during runtime shutdown or reload; other hosts remain unaffected.
|
|
616
664
|
|
|
617
665
|
If your host reclaims idle sessions, keep a session alive while it still has live detached work:
|
|
618
666
|
|
|
@@ -624,6 +672,10 @@ If your host reclaims idle sessions, keep a session alive while it still has liv
|
|
|
624
672
|
|
|
625
673
|
The symptom when this is missed is quiet and easy to misattribute: subagents appear never to report back, which looks like a fault in this extension rather than in the host that disposed the listener.
|
|
626
674
|
|
|
675
|
+
## Component screens over RPC
|
|
676
|
+
|
|
677
|
+
`/subagents-fleet`, `/subagents-stop` and the `/subagents` model and thinking pickers draw a `ctx.ui.custom()` component in the TUI. In every other mode they fall back to text or `ctx.ui.select`, because stock Pi RPC defines `custom()` as a no-op. A host that runs Pi in RPC mode and renders `custom()` components itself, such as pi-web, can set `PI_SUBAGENTS_COMPONENT_UI=1` in Pi's environment to get the component screens.
|
|
678
|
+
|
|
627
679
|
## Runtime files
|
|
628
680
|
|
|
629
681
|
The main runtime files in this repository:
|
|
@@ -654,4 +706,4 @@ The main runtime files in this repository:
|
|
|
654
706
|
|
|
655
707
|
### Published package vs source checkout
|
|
656
708
|
|
|
657
|
-
The npm tarball ships
|
|
709
|
+
The npm tarball ships compiled JavaScript and declarations alongside an esbuild-bundled module graph. Pi loads `bundle/index.js`, and public subpaths resolve to bundled entrypoints with their corresponding declarations. The compiled file layout remains available for child processes and asset paths. A Git checkout continues to run `index.ts` directly, so local extension development does not require a build step. Install the repository's frozen pnpm workspace first, then run `pnpm run pack:pkg` to build and pack the same `dist-pkg` artifact published to npm.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Goal 自动续跑门禁接入
|
|
2
|
+
|
|
3
|
+
本说明记录 pi-subagents 如何响应 goal-x 的 `pi-goal:before-auto-continue:v1` 同步门禁。该监听器只延迟 goal-x 自己的 fallback checkpoint;不拦截子代理结果、监督请求、用户输入或其他原生唤醒。
|
|
4
|
+
|
|
5
|
+
## 状态来源与判据
|
|
6
|
+
|
|
7
|
+
| 工作阶段 | 读取的既有权威状态 | 门禁判据 |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| Async / workflow root 仍在排队或运行 | `SubagentState.asyncJobs`,由 `SUBAGENT_ASYNC_STARTED_EVENT` 建立、session 恢复时由 `listAsyncRuns` 的状态投影恢复 | 只对 `queued` / `running` 且通过 `ResultDeliveryOwnership.owns(sessionId, completionOwnerId)` 的运行阻止。workflow root 是一个普通的活动 async job;嵌套/并行子任务不另建阻止计数。恢复与 live status refresh 均保留 `AsyncStatus.completionOwnerId`,新建 single/chain context 显式使用父扩展的 owner,确保此判据不会因状态投影丢失归属。 |
|
|
10
|
+
| 显式静默的定时运行 | 已投影的 `AsyncJobState.scheduleOrigin`(源自当前启动事件或 `AsyncStatus.scheduleOrigin`) | `scheduleOrigin.quiet === true` 不单独阻止续跑;其成功完成本来就不会触发父会话续跑。失败等可操作结果仍沿用原通知策略。 |
|
|
11
|
+
| Detached foreground 仍运行 | `SubagentState.foregroundControls`(当前扩展 session 的内存控制器) | 用现有 `ownsRun(state.currentSessionId, control.sessionId)` 复用 session succession 归属;不扫描会话文件或 transcript。 |
|
|
12
|
+
| Async 已终态、结果还未交给 notifier | 既有 `owedResultRunIds`,由当前拥有者的 `holdOwedResult` 在 job terminal 路径维护 | 只要仍欠一个拥有者结果交接,就阻止 checkpoint,覆盖 runner terminal 与 result watcher/notifier 之间的窗口。该 Set 原已用于 session liveness,不为门禁新增计数器。 |
|
|
13
|
+
| 通知正在发送或 Pi 已接受 wake、父回合尚未开始 | `CompletionNotifier.hasPendingWake()`:仅观察原 notifier 的 pending trigger-turn deliveries 和 `unstartedWakes`;`messageStarted` 按现有语义释放已启动 wake | 只有当前通知确实承诺 native turn wake 时阻止。显式 `triggerTurn:false`、quiet 成功结果、或当前 held 状态下没有已承诺的 wake 不阻止。 |
|
|
14
|
+
|
|
15
|
+
门禁请求用当前 SDK `session_start` 的 `sessionManager.getSessionId()` UUID 与 `state.supervisorOwnerSessionId` 精确匹配。Async / foreground 运行归属仍由现有 ownership helper 按它们自己的 session 标识处理;绝不把 session UUID 和 session-file path 当作可直接比较的同类字符串。
|
|
16
|
+
|
|
17
|
+
## 同步监听及生命周期
|
|
18
|
+
|
|
19
|
+
监听器在 `session_start` 恢复当前运行状态后安装;会话替换时先 dispose 旧 listener 再安装新 listener,`session_shutdown` / 扩展 reload 由 runtime cleanup 移除。listener 在首个 `await` 前完成所有判断,只通过请求的单向 `defer` 回调投票;本地权威状态读取异常时 catch 并用固定短原因 fail closed,不调用模型、不读磁盘,也不改变 notifier、子代理状态或 goal 生命周期。
|
|
20
|
+
|
|
21
|
+
## 明确不做
|
|
22
|
+
|
|
23
|
+
- 不解析任意 tool result、tool-call args/status/id 或任务文本来猜测后台工作。
|
|
24
|
+
- 不在门禁热路径扫描状态目录、result 文件、session transcript 或事件日志。
|
|
25
|
+
- 不新增 started/completed 计数器、等待/重试机制、用户设置、命令或持久化 schema。
|
|
26
|
+
- 不改变 `sendMessage`、结果去重/所有权、监督请求或 `message_start` 的交付顺序。
|
package/docs/missions.md
CHANGED
|
@@ -13,6 +13,8 @@ Missions are durable wrappers around runs. The noun map:
|
|
|
13
13
|
|
|
14
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
15
|
|
|
16
|
+
A finished run completes a mission you asked for with `mission` or `missionId` only when its result was accepted. If the run, or any workflow child in the mission, ends with acceptance `review-required`, `rejected`, `claimed`, or `pending`, the mission stays `waiting` and `mission.show` lists each child's acceptance status. Check the result and close the mission with `mission.close`. A `gate` or `acceptance.verify` command lets the runtime accept the result, except for writer runs: they require a review by default and stay `review-required` without one. When the command is enough proof, use `acceptance: { level: "verified", verify: [{ id: "check", command: "..." }], review: { required: false } }` instead of `gate`. Missions made by default for ordinary launches still complete when their run finishes.
|
|
17
|
+
|
|
16
18
|
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.
|
|
17
19
|
|
|
18
20
|
Behavior:
|