@xzzpig/pi-subagents 0.24.1 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (263) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/bundle/agent-management.js +4 -4
  3. package/bundle/agents.js +3 -3
  4. package/bundle/child-tool-plan.js +2 -2
  5. package/bundle/chunk-34TUUBRN.js +1107 -0
  6. package/bundle/{chunk-SW2VMNIU.js → chunk-5OD3OWTE.js} +2 -2
  7. package/bundle/{chunk-ZWXU5SPQ.js → chunk-5YEOWNSD.js} +371 -135
  8. package/bundle/{chunk-EUPJB4S7.js → chunk-5Z7JAORM.js} +196 -1219
  9. package/bundle/{chunk-LCDJWBVM.js → chunk-66JNFRFS.js} +1 -1
  10. package/bundle/{chunk-6BJUEES3.js → chunk-6MNRKUHY.js} +23 -12
  11. package/bundle/{chunk-ED55MIC2.js → chunk-CGFF4WA3.js} +42 -19
  12. package/bundle/{chunk-TMHVDPYW.js → chunk-DLVPMML3.js} +263 -154
  13. package/bundle/chunk-HXRB42AF.js +108 -0
  14. package/bundle/{chunk-355ECEP2.js → chunk-IH7LQVEE.js} +29 -14
  15. package/bundle/{chunk-SLNMBXLL.js → chunk-IJWITCC6.js} +411 -249
  16. package/bundle/{chunk-RU522D5W.js → chunk-IKFKH5EL.js} +369 -50
  17. package/bundle/{chunk-Z6TFJ6BR.js → chunk-INWSUNI6.js} +1 -1
  18. package/bundle/{chunk-JEA2ZKUA.js → chunk-IUDEI6FJ.js} +35 -200
  19. package/bundle/{chunk-WW76JRIX.js → chunk-JAXVBXGF.js} +1 -1
  20. package/bundle/{chunk-ICNYIALB.js → chunk-JH5H4CYJ.js} +784 -474
  21. package/bundle/{chunk-35GII5EF.js → chunk-JWFLPSTP.js} +41 -117
  22. package/bundle/{chunk-LMGQAJ3O.js → chunk-KCJFGKVK.js} +350 -123
  23. package/bundle/{chunk-RB4GELQA.js → chunk-LPJEKHOY.js} +1 -1
  24. package/bundle/chunk-LYKG4FKH.js +523 -0
  25. package/bundle/{chunk-X6LOM3Z4.js → chunk-LZ3HBDTR.js} +161 -78
  26. package/bundle/{chunk-FG6SQJAR.js → chunk-OGPOCGWX.js} +24 -6
  27. package/bundle/{chunk-Y6H2G6KX.js → chunk-OSVXFWPG.js} +67 -30
  28. package/bundle/{chunk-FJWI64H7.js → chunk-RMSABUN3.js} +27 -13
  29. package/bundle/{chunk-H36HBZB2.js → chunk-SJPABBZG.js} +2 -2
  30. package/bundle/{chunk-3U633XDZ.js → chunk-U3ZDUUTM.js} +11 -3
  31. package/bundle/{chunk-LVWU2HOO.js → chunk-ULGMXABL.js} +16 -7
  32. package/bundle/{chunk-WPW4V6HM.js → chunk-W7ZA6TYD.js} +2 -2
  33. package/bundle/{chunk-V2KFIGFH.js → chunk-XAC2XNAP.js} +503 -304
  34. package/bundle/{chunk-TGLFTQWJ.js → chunk-YWXILP5N.js} +5 -4
  35. package/bundle/control-channel.js +2 -2
  36. package/bundle/index.js +1 -1
  37. package/bundle/intercom-bridge.js +2 -2
  38. package/bundle/preflight.js +12 -10
  39. package/bundle/project-panes.js +3 -3
  40. package/bundle/workflow-resources.js +1 -1
  41. package/docs/agents.md +27 -6
  42. package/docs/configuration.md +20 -8
  43. package/docs/extension-api.md +18 -1
  44. package/docs/models.md +6 -2
  45. package/docs/observability.md +2 -0
  46. package/docs/tool-reference.md +7 -1
  47. package/docs/workflows.md +30 -2
  48. package/node_modules/@xzzpig/pi-components/CHANGELOG.md +12 -0
  49. package/node_modules/@xzzpig/pi-components/README.md +94 -0
  50. package/node_modules/@xzzpig/pi-components/dist/src/transcript-presenter.d.ts +186 -0
  51. package/node_modules/@xzzpig/pi-components/dist/src/transcript-presenter.js +693 -0
  52. package/node_modules/@xzzpig/pi-components/package.json +5 -1
  53. package/package.json +4 -4
  54. package/skills/pi-subagents/SKILL.md +15 -6
  55. package/skills/pi-subagents/references/prompting-and-roles.md +1 -0
  56. package/src/agents/agent-management.d.ts +1 -0
  57. package/src/agents/agent-management.js +46 -18
  58. package/src/agents/agent-memory.d.ts +1 -4
  59. package/src/agents/agent-memory.js +1 -4
  60. package/src/agents/agent-serializer.d.ts +2 -0
  61. package/src/agents/agent-serializer.js +1 -1
  62. package/src/agents/agents.d.ts +2 -3
  63. package/src/agents/agents.js +46 -20
  64. package/src/agents/frontmatter.js +1 -8
  65. package/src/agents/global-npm-root.d.ts +1 -0
  66. package/src/agents/global-npm-root.js +11 -3
  67. package/src/agents/skills.d.ts +0 -3
  68. package/src/agents/skills.js +0 -3
  69. package/src/api/preflight.d.ts +3 -1
  70. package/src/api/preflight.js +2 -0
  71. package/src/extension/config.d.ts +1 -0
  72. package/src/extension/config.js +13 -1
  73. package/src/extension/herdr-pi-bridge.js +10 -2
  74. package/src/extension/index.d.ts +0 -13
  75. package/src/extension/index.js +51 -37
  76. package/src/extension/public-execution.d.ts +1 -0
  77. package/src/extension/public-execution.js +4 -0
  78. package/src/extension/reply-workflow-script.js +24 -4
  79. package/src/extension/schemas.d.ts +12 -3
  80. package/src/extension/schemas.js +7 -3
  81. package/src/extension/session-switch.d.ts +25 -0
  82. package/src/extension/session-switch.js +138 -0
  83. package/src/extension/subagent-guide.d.ts +1 -1
  84. package/src/extension/subagent-guide.js +1 -1
  85. package/src/extension/subagent-launch-tool.d.ts +25 -0
  86. package/src/extension/subagent-launch-tool.js +48 -0
  87. package/src/extension/tool-activation.js +55 -15
  88. package/src/extension/tool-description.d.ts +1 -1
  89. package/src/extension/tool-description.js +14 -8
  90. package/src/inspectors/herdr/actions.d.ts +0 -1
  91. package/src/inspectors/herdr/actions.js +0 -1
  92. package/src/inspectors/session-roots-codec.d.ts +0 -1
  93. package/src/inspectors/session-roots-codec.js +0 -1
  94. package/src/inspectors/tmux/actions.d.ts +0 -1
  95. package/src/inspectors/tmux/actions.js +0 -1
  96. package/src/integrations/herdr-status.js +3 -8
  97. package/src/intercom/native-supervisor-channel.js +65 -9
  98. package/src/runs/background/async-execution.d.ts +7 -10
  99. package/src/runs/background/async-execution.js +66 -29
  100. package/src/runs/background/async-job-tracker.js +12 -0
  101. package/src/runs/background/async-resume.d.ts +2 -1
  102. package/src/runs/background/async-resume.js +114 -40
  103. package/src/runs/background/async-retention.d.ts +0 -2
  104. package/src/runs/background/async-retention.js +17 -6
  105. package/src/runs/background/async-status.d.ts +2 -0
  106. package/src/runs/background/async-status.js +4 -0
  107. package/src/runs/background/auto-drain.js +2 -1
  108. package/src/runs/background/boot-id.d.ts +1 -3
  109. package/src/runs/background/boot-id.js +1 -3
  110. package/src/runs/background/completion-batcher.d.ts +3 -4
  111. package/src/runs/background/completion-batcher.js +2 -3
  112. package/src/runs/background/control-channel.d.ts +0 -6
  113. package/src/runs/background/control-channel.js +0 -6
  114. package/src/runs/background/fleet-view.js +2 -3
  115. package/src/runs/background/notify.d.ts +0 -2
  116. package/src/runs/background/notify.js +0 -2
  117. package/src/runs/background/result-watcher.d.ts +1 -0
  118. package/src/runs/background/result-watcher.js +59 -29
  119. package/src/runs/background/resume-guidance.js +4 -2
  120. package/src/runs/background/retained-children.js +2 -1
  121. package/src/runs/background/run-child-session.d.ts +2 -3
  122. package/src/runs/background/run-child-session.js +5 -8
  123. package/src/runs/background/run-status.js +9 -7
  124. package/src/runs/background/runner-aliases.js +15 -0
  125. package/src/runs/background/scheduled-runs.d.ts +3 -1
  126. package/src/runs/background/scheduled-runs.js +13 -16
  127. package/src/runs/background/steering.d.ts +2 -11
  128. package/src/runs/background/steering.js +11 -6
  129. package/src/runs/background/subagent-runner.d.ts +2 -6
  130. package/src/runs/background/subagent-runner.js +88 -70
  131. package/src/runs/background/subagent-wait.js +12 -15
  132. package/src/runs/background/wait-config.d.ts +2 -0
  133. package/src/runs/background/wait-config.js +17 -3
  134. package/src/runs/background/wait-subscriptions.js +124 -12
  135. package/src/runs/background/wait-tool.js +4 -2
  136. package/src/runs/background/workflow-terminal-proof.d.ts +0 -1
  137. package/src/runs/background/workflow-terminal-proof.js +0 -1
  138. package/src/runs/foreground/async-steering-action.js +24 -9
  139. package/src/runs/foreground/async-stop-action.d.ts +1 -1
  140. package/src/runs/foreground/async-stop-action.js +9 -1
  141. package/src/runs/foreground/execution.d.ts +0 -3
  142. package/src/runs/foreground/execution.js +56 -24
  143. package/src/runs/foreground/prompt-audit.js +1 -0
  144. package/src/runs/foreground/subagent-executor.d.ts +5 -10
  145. package/src/runs/foreground/subagent-executor.js +164 -49
  146. package/src/runs/shared/acceptance.js +69 -26
  147. package/src/runs/shared/async-status-projection.d.ts +2 -0
  148. package/src/runs/shared/async-status-projection.js +10 -0
  149. package/src/runs/shared/child-commands.js +15 -2
  150. package/src/runs/shared/child-hooks.d.ts +1 -7
  151. package/src/runs/shared/child-hooks.js +13 -5
  152. package/src/runs/shared/child-launch.js +6 -2
  153. package/src/runs/shared/child-runtime-config.d.ts +0 -1
  154. package/src/runs/shared/child-session.d.ts +6 -5
  155. package/src/runs/shared/child-session.js +85 -38
  156. package/src/runs/shared/child-tool-plan.d.ts +0 -1
  157. package/src/runs/shared/child-tool-plan.js +0 -1
  158. package/src/runs/shared/claude-code-adapter.js +11 -0
  159. package/src/runs/shared/external-cli-contract.d.ts +49 -0
  160. package/src/runs/shared/external-cli-contract.js +18 -13
  161. package/src/runs/shared/external-cli-runner.js +26 -6
  162. package/src/runs/shared/herdr-connection.js +2 -1
  163. package/src/runs/shared/herdr-pane-host.d.ts +2 -2
  164. package/src/runs/shared/herdr-pane-host.js +17 -1
  165. package/src/runs/shared/herdr-placed-run.js +51 -24
  166. package/src/runs/shared/lane-metadata.d.ts +0 -1
  167. package/src/runs/shared/lane-metadata.js +0 -1
  168. package/src/runs/shared/mcp-config-sources.d.ts +4 -1
  169. package/src/runs/shared/mcp-config-sources.js +1 -1
  170. package/src/runs/shared/mcp-direct-tool-allowlist.d.ts +0 -3
  171. package/src/runs/shared/mcp-direct-tool-allowlist.js +26 -17
  172. package/src/runs/shared/mcp-direct-tool-grant.js +8 -1
  173. package/src/runs/shared/model-resolution-diagnostic.d.ts +0 -1
  174. package/src/runs/shared/model-resolution.d.ts +20 -5
  175. package/src/runs/shared/model-resolution.js +55 -50
  176. package/src/runs/shared/model-scope.d.ts +1 -5
  177. package/src/runs/shared/model-scope.js +1 -5
  178. package/src/runs/shared/mutation-evidence.d.ts +1 -1
  179. package/src/runs/shared/mutation-evidence.js +52 -7
  180. package/src/runs/shared/nested-events.d.ts +1 -0
  181. package/src/runs/shared/nested-events.js +1 -1
  182. package/src/runs/shared/parallel-utils.d.ts +0 -1
  183. package/src/runs/shared/permissions.js +5 -3
  184. package/src/runs/shared/placement-host.d.ts +5 -1
  185. package/src/runs/shared/rex-pane-host.d.ts +0 -1
  186. package/src/runs/shared/rex-pane-host.js +0 -2
  187. package/src/runs/shared/run-launch-folder.d.ts +12 -0
  188. package/src/runs/shared/run-launch-folder.js +21 -0
  189. package/src/runs/shared/runner-launcher.d.ts +12 -1
  190. package/src/runs/shared/runner-launcher.js +16 -0
  191. package/src/runs/shared/single-output.d.ts +3 -3
  192. package/src/runs/shared/single-output.js +5 -3
  193. package/src/runs/shared/structured-output.d.ts +8 -0
  194. package/src/runs/shared/structured-output.js +40 -5
  195. package/src/runs/shared/subagent-prompt-runtime.d.ts +0 -1
  196. package/src/runs/shared/subagent-prompt-runtime.js +18 -4
  197. package/src/runs/shared/supervisor-wait-timer.d.ts +16 -0
  198. package/src/runs/shared/supervisor-wait-timer.js +61 -0
  199. package/src/runs/shared/tool-timeout.js +2 -1
  200. package/src/runs/shared/worktree-cleanup-plan.d.ts +0 -1
  201. package/src/runs/shared/worktree-cleanup-plan.js +0 -1
  202. package/src/runs/shared/worktree.d.ts +3 -0
  203. package/src/runs/shared/worktree.js +20 -0
  204. package/src/shared/artifacts.d.ts +1 -0
  205. package/src/shared/artifacts.js +132 -22
  206. package/src/shared/capacity-resilient-json.d.ts +1 -1
  207. package/src/shared/child-cache-retention.d.ts +1 -2
  208. package/src/shared/child-cache-retention.js +1 -2
  209. package/src/shared/fleet-transcript-reader.d.ts +51 -0
  210. package/src/shared/fleet-transcript-reader.js +333 -0
  211. package/src/shared/formatters.d.ts +0 -18
  212. package/src/shared/formatters.js +0 -18
  213. package/src/shared/pruned-fork.js +2 -2
  214. package/src/shared/reported-progress.d.ts +1 -0
  215. package/src/shared/reported-progress.js +12 -0
  216. package/src/shared/session-succession.d.ts +16 -1
  217. package/src/shared/session-succession.js +41 -2
  218. package/src/shared/session-warnings.d.ts +7 -0
  219. package/src/shared/session-warnings.js +26 -0
  220. package/src/shared/settings.d.ts +0 -23
  221. package/src/shared/settings.js +3 -35
  222. package/src/shared/status-format.d.ts +1 -0
  223. package/src/shared/status-format.js +1 -1
  224. package/src/shared/types.d.ts +108 -59
  225. package/src/shared/types.js +0 -12
  226. package/src/shared/utils.d.ts +3 -15
  227. package/src/shared/utils.js +4 -22
  228. package/src/shared/wait-tool-name.d.ts +8 -0
  229. package/src/shared/wait-tool-name.js +13 -0
  230. package/src/slash/slash-commands.js +2 -1
  231. package/src/slash/subagent-cost.d.ts +3 -2
  232. package/src/slash/subagent-cost.js +22 -3
  233. package/src/slash/subagents-admin.js +0 -1
  234. package/src/tui/fleet-status.d.ts +0 -5
  235. package/src/tui/fleet-status.js +4 -24
  236. package/src/tui/fleet.js +6 -4
  237. package/src/tui/render.d.ts +0 -9
  238. package/src/tui/render.js +194 -68
  239. package/src/tui/subagent-messages.js +3 -2
  240. package/src/watchdog/model-selection.js +2 -2
  241. package/src/watchdog/permission-arbiter.js +1 -0
  242. package/src/watchdog/register-child.d.ts +2 -3
  243. package/src/watchdog/register-child.js +2 -3
  244. package/src/watchdog/review.d.ts +0 -5
  245. package/src/watchdog/review.js +4 -3
  246. package/src/watchdog/turn-delta.js +2 -1
  247. package/src/workflows/scripted-workflow.d.ts +2 -0
  248. package/src/workflows/scripted-workflow.js +344 -59
  249. package/src/workflows/structured-workflow-scripts.d.ts +4 -3
  250. package/src/workflows/structured-workflow-scripts.js +32 -11
  251. package/src/workflows/workflow-launch-record.d.ts +15 -6
  252. package/src/workflows/workflow-launch-record.js +30 -12
  253. package/src/workflows/workflow-receipt.js +36 -53
  254. package/src/workflows/workflow-resources.js +4 -4
  255. package/src/workflows/workflow-resume-claim.d.ts +2 -0
  256. package/src/workflows/workflow-resume-claim.js +3 -3
  257. package/src/workflows/workflow-resume.d.ts +1 -1
  258. package/src/workflows/workflow-resume.js +13 -8
  259. package/src/workflows/workflow-script-worker.d.ts +13 -0
  260. package/src/workflows/workflow-script-worker.js +81 -0
  261. package/workflow-script-process.cjs +36 -0
  262. package/workflow-script-worker.cjs +4 -1
  263. package/bundle/chunk-U4ODUYAG.js +0 -235
package/docs/workflows.md CHANGED
@@ -37,7 +37,7 @@ When the Pi process that ran an async workflow exits before the workflow finishe
37
37
 
38
38
  A stopped run is continued by one relaunch only. While that relaunch exists, another relaunch of the same stopped run, by the same script or by `options.reuseFrom`, is refused with `workflow run '<id>' was resumed as <new id>; wait on it or stop it.` If that relaunch stops the same way, relaunch it instead: it carries the children of every run before it. If the Pi process that started the relaunch exits before the relaunch begins, the stopped run can be relaunched again.
39
39
 
40
- To continue a stopped run without sending its script again, resume it by id from the session that owns it: `subagent({ action: "resume", id: "<stopped run id>" })` with no `message`. Every async top-level workflow saves its launch (the script or named resource, its `args` and options) when it starts, and the resume relaunches that launch with `options.reuseFrom` set to the stopped run, in the stopped run's cwd, with no more authority than it had. A named resource is resolved again and must still have the same script. The new run records `workflow.resumeOrigin: { sourceRunId, attempt }`, where `attempt` counts the resumes that followed a Pi exit. Another session cannot resume the run by id; reopen the session that started it, or relaunch the same script with `options.reuseFrom`. When the run cannot be resumed this way (it started before launches were saved, was launched from `tasks` or `chain`, or its resource changed), the refusal says so; relaunch the same script by hand with `options: { reuseFrom: "<stopped run id>" }`.
40
+ To continue a stopped run without sending its script again, resume it by id from the session that owns it: `subagent({ action: "resume", id: "<stopped run id>" })` with no `message`. Every async top-level workflow saves its launch (the script or named resource, its `args` and options) when it starts, outside its run directory, and the resume relaunches that launch with `options.reuseFrom` set to the stopped run, in the stopped run's cwd, with no more authority than it had. A named resource is resolved again and must still have the same script. The new run records `workflow.resumeOrigin: { sourceRunId, attempt }`, where `attempt` counts the resumes that followed a Pi exit. Another session cannot resume the run by id; reopen the session that started it, or relaunch the same script with `options.reuseFrom`. When the run cannot be resumed this way (it started before launches were saved outside run directories, was launched from `tasks` or `chain`, or its resource changed), the refusal says so; relaunch the same script by hand with `options: { reuseFrom: "<stopped run id>" }`.
41
41
 
42
42
  When the session that owns such a run is reopened or reloaded, the run is resumed this way automatically, once, if it was interrupted in the last 24 hours: for a Pi exit, measured from the last time the dead Pi process updated the run. Session start does not wait for the relaunch. A run that cannot be relaunched is named in its notice (`Not auto-resumed: …`, with how to continue by hand); a launch that fails after session start also posts one `Workflow <id> was not auto-resumed: <reason>.` message. Either way the run is not tried again. `/new` and forks do not resume the runs of the session they replaced. The `autoResume` setting turns this off; see [Configuration](configuration.md#autoresume).
43
43
 
@@ -45,12 +45,22 @@ Starting Pi in a folder where another session's subagent runs were cut off by it
45
45
 
46
46
  The completion notice of a workflow stopped by a Pi exit or a runtime replacement has one line right after `Workflow run: <id>` that says what happens next: `Auto-resumed as <new id>.`, `Resumed as <new id>.` (resumed by id), `Relaunched as <new id>.` (relaunched with the same script or `options.reuseFrom`), `Not auto-resumed: <reason>.` followed by the way to continue by hand, or, when nothing continues it, `Resume by hand: subagent({ action: "resume", id: "<id>" })` (or the `options.reuseFrom` form when its launch cannot be resumed by id).
47
47
 
48
- After `/new`, `/resume`, or a fork in the same Pi process, the new session owns the async runs of the session it replaced, and of the sessions that one replaced. It can list, `bg_wait` on, steer, stop, and resume them, receives their completion notices, and answers their children's pending supervisor requests. Over RPC, a host can steer, interrupt, stop, resume, and inspect them, and sees them in the fleet and `subagent-async` snapshots. Startup and other Pi processes inherit nothing; `/reload` adds nothing new but keeps what the session already inherited. To relaunch a stopped workflow instead of controlling its children one by one, use `options.reuseFrom`.
48
+ After `/new`, `/resume`, or a fork in the same Pi process, the new session owns the async runs of the session it replaced, and of the sessions that one replaced. It can list, `bg_wait` on, steer, stop, and resume them, receives their completion notices, and answers their children's pending supervisor requests. Over RPC, a host can steer, interrupt, stop, resume, and inspect them, and sees them in the fleet and `subagent-async` snapshots. Startup and other Pi processes inherit nothing; `/reload` adds nothing new but keeps what the session already inherited. A replaced session that starts again (pi-web reopening it) takes its runs back. To relaunch a stopped workflow instead of controlling its children one by one, use `options.reuseFrom`.
49
49
 
50
50
  Once the Pi process that started a background single, parallel, or chain run has exited, the run is reported once to a Pi window that has its session open, whether it finished while Pi was closed or finishes later. A workflow's children are reported through their workflow.
51
51
 
52
52
  Pi core may print a generic `pi -ne` extension-load hint; that out-of-repo hint is not protocol-approved fallback. A verified compaction abort may continue the retained child once on its already resolved model; it does not authorize an execution-mode or model switch.
53
53
 
54
+ ### Switching sessions with background work
55
+
56
+ When a session with a UI has queued or running async work, live nested children, undelivered results, or supervisor questions, `/new`, `/resume`, `/fork`, and `/clone` first ask **pi-subagents: switch sessions?**:
57
+
58
+ - **Stay here** (default, also Escape): cancel the switch. The work keeps running.
59
+ - **Switch and take the work**: the new session takes the work over, as after any switch without the prompt.
60
+ - **Switch and leave the work here**: the new session inherits nothing from this one. Async single, parallel, and chain runs keep running under this session; reopen it to get their results. Async workflows and detached foreground runs stop on any switch; a stopped workflow resumes automatically only if you reopen this session within 24 hours. A child's question can be answered only until it times out (10 minutes by default).
61
+
62
+ Without outstanding work, or without a UI (`pi -p`, SDK sessions), there is no prompt and the new session takes the work over. Over RPC the prompt is a select dialog that counts as **Stay here** if the host does not answer within one minute. The prompt never enters model history.
63
+
54
64
  ## Prompt shortcuts
55
65
 
56
66
  The package includes reusable prompt templates for common workflows. You do not need them, but they are handy when you want the same shape every time:
@@ -85,6 +95,10 @@ Workflow-level child controls default onto each `runs.run`/`runs.all` launch; ex
85
95
 
86
96
  Child results cross into the script as plain JSON data. Non-JSON host metadata is omitted, so use returned fields such as `runId`, `ok`, `output`, and `structuredOutput` for workflow control.
87
97
 
98
+ On Node, each script runs in a new permission-restricted process that can read only its supervisor, worker and Acorn parser; Node denies file writes, other reads, child processes and nested workers. The process inherits no host startup flags, preloads or environment variables (except `SystemRoot` on Windows) and starts in Acorn's directory, because Node lets worker threads read their working directory. A small supervisor keeps IPC responsive, so a busy script is still killed when the parent disconnects. The process ends when the workflow settles.
99
+
100
+ This is a permission layer around the VM, not an OS sandbox: network access stays open on Node 22 and 24, and child launches and `runs.host` commands still run in Pi under their own contracts. Bun has no permission model, so it keeps the in-process worker. If the Node process fails to start, the workflow fails; it never retries in an unrestricted worker.
101
+
88
102
  Omitting a child's `async` preserves awaited final-result semantics, even if the child runs in the background. Explicit child `async: true` intentionally returns after launch: its receipt has `state: "running"`, `ok: false`, an empty `output`, and no completion error or final `outputReference`. `ok` confirms successful child completion, not successful dispatch. It does not confirm that the task's intent was carried out: a child that declines or cannot do the work can still end normally. When later steps depend on the work having happened, give the child an `outputSchema` with an explicit status field (and check `structuredOutput` in the script) or a host-run `gate`, and treat only that verdict as success. Use `runId` and `asyncDir` to inspect the running child; `artifactPaths` may include runtime directories and is not a list of final reports. Reusing the same workflow key returns the same receipt, not a refreshed result.
89
103
 
90
104
  A workflow can finish dispatch while these children remain running. Its summary and child rows identify that distinction, and launch receipts do not generate child-completion notices. Consume the later child result before treating its work or report as complete.
@@ -133,6 +147,20 @@ The host resolves the name and validates bounded plain-JSON `args` before starti
133
147
 
134
148
  `parallel` runs independent children together without writing a script: `args.tasks` is a list of `{ agent, task, cwd?, model? }` items, the children run in one `runs.all` batch, and the result lists each child's output in order. `cwd` and `model` are optional per child and apply to that child only, as they do on a `runs.all` item, so one call can fan out across several repositories or mix models. A failed child fails the workflow. Use a workflow script when steps depend on each other.
135
149
 
150
+ ### Approving workflow children in permission extensions
151
+
152
+ Before a workflow starts a child, pi-subagents makes a nested `subagent_launch` tool call, so permission extensions see it in their `tool_call` handler like any other tool call. This covers reply-block, file and named workflows, and `chain` and `tasks`. The call's input is `{ workflowRunId, key, agent?, task?, cwd?, model?, async?, worktree?, resume?, commands?, output? }`. `cwd` is the absolute directory the child starts in. It is left out for a resumed child, which keeps its earlier directory, and for a child placed on another machine. `commands` lists, in run order, the shell commands the child's `gate`, `acceptance.verify` or agent `acceptance` will run on this machine after the child finishes, each `{ command, cwd?, env? }`. A command's `cwd` is absolute and is left out when the child's is; for a `worktree: true` child it names the source directory, because the worktree does not exist yet. `env` lists only the variables the command sets on top of the parent's environment. `output` is the absolute path of the file the child's `output` writes. The other optional fields appear when the child request sets them. A blocked or failed call stops that child, so its commands never run and its output file is never written; it fails with `Workflow child '<key>' was not started: …` and the block reason. Allowed calls do nothing else. The tool is not declared to the model.
153
+
154
+ Extensions that ask about tools they have no rule for ask once per workflow child until you allow `subagent_launch`. Ones that deny unknown tools without a UI, as in `pi -p`, refuse every workflow child until you allow it.
155
+
156
+ Limits:
157
+ - Children reused from an interrupted run's journal are not offered again; nothing new starts.
158
+ - Starts with no tool call behind them are not offered: schedule ticks, auto-resume on session reopen, `/prompt-workflow` and prompt-template delegation, and RPC or SDK launches. Block `schedule.create`, set `authorityPolicy.scheduleCreate` to `"forbid"`, or set [`autoResume`](configuration.md#autoresume) to `false` to control those.
159
+ - Workflows started inside child agents are not offered: children do not register `subagent_launch`. Neither are workflows in a session whose tool allowlist (`pi --tools …`) leaves it out.
160
+ - Commands are offered at launch, not when they run. An extension's `bash` rules don't apply to them on their own; it has to check `commands`.
161
+ - A resumed child's retained `acceptance.verify` commands are not listed again; only commands the resume request adds are.
162
+ - `runs.host` is only available to built-in workflows (`run-ci` runs only `npm test` or `npm run typecheck`) and is not offered.
163
+
136
164
  ### Opt-in bounded workflows
137
165
 
138
166
  Composite workflows have no default parent deadline. Add bounds only when the workflow contract calls for them:
@@ -3,6 +3,18 @@
3
3
  All notable changes to the internal `@xzzpig/pi-components` shared library are
4
4
  documented here.
5
5
 
6
+ ## 0.5.0
7
+
8
+ ### Added
9
+
10
+ - **可选启用的 `TranscriptPresenter`(`@xzzpig/pi-components/transcript-presenter`)。**
11
+ 在既有 `TranscriptEntry` 值之上的有状态展示层:按稳定消息段保留原生用户/助手
12
+ 组件,把真实流式状态传给 Pi 的 `AssistantMessageComponent`,在内容更新和缩放后
13
+ 保留原生思考块的点击状态,暴露组件行范围与规范化鼠标分发,支持本地统一思考切换
14
+ (包括通过 Pi 原生 `MouseRegion` 点击路径展开已完成的块),并提供显式的
15
+ `sync`/`render`/`invalidate`/`clear`/`dispose` 生命周期钩子。既有
16
+ `renderTranscriptLines` 与 `TranscriptViewport` 行为不变。
17
+
6
18
  ## 0.4.0
7
19
 
8
20
  ### Added
@@ -51,6 +51,100 @@ scrolling. Hosts keep ownership of terminal mouse-reporting setup, dialog
51
51
  chrome, focus behavior, input controls, session lifecycle, and cancellation
52
52
  policy. `Esc` handling is intentionally delegated to the host overlay.
53
53
 
54
+ ### 有状态展示器(可选启用)
55
+
56
+ `@xzzpig/pi-components/transcript-presenter` 新增 `TranscriptPresenter`,供需要
57
+ 真实流式状态、原生思考块点击和本地思考切换的宿主使用。上述无状态入口保持不变;
58
+ 宿主通过导入第二个子路径显式启用。
59
+
60
+ 展示器消费相同的 `TranscriptEntry` 值,并按用户条目保留一个原生
61
+ `UserMessageComponent`、按助手消息段保留一个原生 `AssistantMessageComponent`。
62
+ 助手组件先以空内容构造,再通过 `updateContent(message, streaming)` 接收内容,因此
63
+ Pi 的原生流式状态会到达宿主侧补丁(例如 `pi-thinking-collapse`),而不是先渲染
64
+ 一条已完成消息。只有段落文本或流式标志变化时才重新赋值内容;缩放和纯重绘保留组件
65
+ 及其逐块点击状态。
66
+
67
+ ```ts
68
+ import { SessionTranscript } from "@xzzpig/pi-components/transcript";
69
+ import { TranscriptPresenter } from "@xzzpig/pi-components/transcript-presenter";
70
+
71
+ const transcript = new SessionTranscript();
72
+ const presenter = new TranscriptPresenter({
73
+ theme,
74
+ // 复用 transcript 注册表,让工具 renderer 状态和展开点击跨帧保留。
75
+ // 仅在只读回放时省略;此时工具块回退为无状态的临时组件。
76
+ toolComponents: transcript.toolComponents,
77
+ assistantLabel: "Assistant",
78
+ // 省略 thinkingLabel 可保留 Pi 原生的 `Thinking...` 标签,折叠补丁会把
79
+ // 它替换成自己的 “click to expand” 提示。
80
+ });
81
+ presenter.attachTui(tui);
82
+ // 把 renderer 发起的工具重绘接到展示器修订号上。
83
+ transcript.toolComponents.attachTui({
84
+ requestRender: () => presenter.requestRender(),
85
+ });
86
+
87
+ // 宿主的 transcript 版本变化时(或简单宿主每帧一次),渲染前先 sync。
88
+ // 对未变化条目的重复 sync 只做内容比较,不会改动展示修订号。
89
+ presenter.sync(transcript.entries);
90
+ const frame = presenter.render(innerWidth);
91
+ const visibleLines = frame.lines.slice(scrollOffset, scrollOffset + height);
92
+
93
+ // 鼠标路由:把可见视口行加上 scroll offset 换算到完整 transcript 空间,
94
+ // 再交给展示器分发。
95
+ const handled = presenter.handleMouse({
96
+ ...mouseEvent,
97
+ y: mouseEvent.y - overlayChromeTop + scrollOffset,
98
+ });
99
+
100
+ // BTW 本地统一思考切换(在 overlay 绑定 Ctrl+T;不写 Pi 设置,也不碰主会话)。
101
+ const thinkingVisible = presenter.toggleThinkingVisibility();
102
+ ```
103
+
104
+ `sync(entries)` 只更新发生变化的段,并清理条目已消失的组件。`render(width)` 返回
105
+ 渲染行以及 `frame.rows`(组件行范围)、`frame.totalLines` 和 `frame.revision`;
106
+ 宿主缓存应比较 `frame.revision` 与宽度。展示器自身的缓存会在条目变化、宽度变化、
107
+ `invalidate()`(主题变化)、思考切换和 `requestRender()`(组件发起的重绘)时失效。
108
+
109
+ 鼠标处理使用 Pi 公开的 `Component.handleMouse` 路径:展示器把转录行映射到所属
110
+ 原生组件,减去该行的 `top`,再转发事件。这样无需读取组件私有字段,即可保留 Pi
111
+ 原生的逐块思考点击与工具展开。
112
+
113
+ 思考控制:
114
+
115
+ - `thinkingVisible` 反映展示器的本地偏好。展示器初始为 `auto`:没有宿主补丁时
116
+ Pi 原生默认展开;存在折叠补丁时,流式内容保持可见,完成的消息折叠。
117
+ - `setThinkingVisible(visible)` 把显式本地偏好应用到每个保留的助手组件。隐藏使用
118
+ Pi 公开的 `setHideThinkingBlock(true)`,因此会清除原生的逐块覆盖。显示时先通过
119
+ 同一个公开 setter 强制到已知的折叠状态,再通过原生思考 `MouseRegion`(经公开
120
+ 的 `Container.children` 取得)分发一次点击。这会设置与用户点击相同的逐块覆盖,
121
+ 因此即使宿主折叠补丁持续自动折叠,已完成消息也会展开。流式标志从不伪造,不读取
122
+ 组件私有字段,也不修改折叠补丁。
123
+ - 新段继承显式的可见偏好:首次内容更新后,展示器应用相同的原生点击路径。
124
+ - 之后对某个思考块的真实点击仍然只切换该块,且该覆盖在内容更新、主题失效和缩放后
125
+ 保持。
126
+ - `toggleThinkingVisibility()` 翻转偏好并返回新的可见性。从初始 `auto` 状态开始,
127
+ 第一次切换隐藏,下一次展开所有保留的块。
128
+ - 该偏好只属于本展示器。它绝不写入 Pi 设置,也不改变主会话的思考偏好。
129
+
130
+ 在 `AssistantMessageComponent` 没有思考 `MouseRegion` 的宿主(较旧的 Pi)上,
131
+ 显示会降级为公开的 `setHideThinkingBlock(false)` 调用;内容与键盘切换仍然可用,
132
+ 但宿主折叠补丁仍可再次折叠已完成消息。
133
+
134
+ 生命周期:
135
+
136
+ - `attachTui(tui)` / `detachTui()` 接通重绘转发。分离已关闭的 overlay 会保留线程
137
+ 状态,包括展开选择。
138
+ - `invalidate()` 为主题变化重新渲染原生组件,而不重新初始化宿主全局主题。
139
+ - `clear()` 在线程被清空时丢弃保留的消息组件与布局。
140
+ - `dispose()` 释放组件、分离 TUI,并让后续调用变为 no-op;在线程/会话本身销毁时
141
+ 使用。
142
+
143
+ 当宿主侧补丁自动折叠已完成的思考(例如 `pi-thinking-collapse`)时,展示器保留该
144
+ 补丁的流式与完成行为及其原生逐块点击覆盖。统一切换通过原生点击路径为保留块显式
145
+ 覆盖该自动折叠,新块继承该显式偏好。没有此类补丁时,已完成的思考遵循 Pi 原生
146
+ 默认值(展开),本地切换会展开/收起每个保留块。
147
+
54
148
  ### History replay
55
149
 
56
150
  Hosts that rebuild a transcript from persisted records write entries through
@@ -0,0 +1,186 @@
1
+ import { type TuiMouseEvent } from "@earendil-works/pi-tui";
2
+ import { type NativeToolRenderOptions, type ToolComponentLookup, type TranscriptEntry, type TranscriptTheme, type TranscriptTui } from "./transcript.js";
3
+ /**
4
+ * Options for the opt-in stateful presenter.
5
+ *
6
+ * The presenter owns user/assistant components; tool components stay owned by
7
+ * the caller's `TranscriptToolComponents` registry so live tool updates keep
8
+ * their existing renderer state. When no registry is supplied, tool calls are
9
+ * rendered through stateless ad-hoc components, exactly like
10
+ * `renderTranscriptLines`.
11
+ */
12
+ export interface TranscriptPresenterOptions extends NativeToolRenderOptions {
13
+ theme: TranscriptTheme;
14
+ emptyText?: string;
15
+ assistantLabel?: string;
16
+ /**
17
+ * Collapsed-label text used while thinking is hidden. Defaults to Pi's
18
+ * native `Thinking...` label so collapse patches can replace it with their
19
+ * own expand affordance instead of treating it as a custom label.
20
+ */
21
+ thinkingLabel?: string;
22
+ assistantBadgeBackground?: string;
23
+ assistantBadgeForeground?: string;
24
+ /**
25
+ * Start with the presenter's local thinking preference hidden. When omitted
26
+ * (or false) the presenter starts in `auto`: host patches such as
27
+ * `pi-thinking-collapse` keep deciding per-message visibility until the host
28
+ * calls `setThinkingVisible`/`toggleThinkingVisibility`.
29
+ */
30
+ hideThinkingBlock?: boolean;
31
+ /** Persistent native tool components keyed by tool call id. */
32
+ toolComponents?: ToolComponentLookup;
33
+ }
34
+ /**
35
+ * A rendered, mouse-addressable component range in the full transcript.
36
+ * `top` is the zero-based line offset including any scroll offset the host has
37
+ * not applied; callers translate visible viewport rows into this space.
38
+ */
39
+ export type TranscriptPresenterRow = {
40
+ kind: "user";
41
+ entryId: number;
42
+ top: number;
43
+ height: number;
44
+ } | {
45
+ kind: "assistant";
46
+ /** Stable id of the assistant message segment (its first entry id). */
47
+ segmentId: number;
48
+ entryIds: readonly number[];
49
+ top: number;
50
+ height: number;
51
+ } | {
52
+ kind: "tool";
53
+ entryId: number;
54
+ toolCallId: string;
55
+ top: number;
56
+ height: number;
57
+ };
58
+ /** One rendered frame plus the layout needed to route mouse events. */
59
+ export interface TranscriptPresenterFrame {
60
+ lines: string[];
61
+ rows: readonly TranscriptPresenterRow[];
62
+ totalLines: number;
63
+ width: number;
64
+ /**
65
+ * Display revision the lines were rendered at. A component that requests a
66
+ * repaint during rendering can raise the presenter's current revision above
67
+ * this value; callers then re-render instead of reusing the lines.
68
+ */
69
+ revision: number;
70
+ }
71
+ /**
72
+ * Opt-in stateful transcript presenter.
73
+ *
74
+ * It consumes the same `TranscriptEntry` values as `renderTranscriptLines`,
75
+ * but keeps one native `UserMessageComponent` per user entry and one native
76
+ * `AssistantMessageComponent` per assistant message segment. Assistant
77
+ * components are constructed empty and receive content through
78
+ * `updateContent(message, streaming)`, so a host-side thinking-collapse patch
79
+ * observes the real streaming state instead of an already-finished message.
80
+ *
81
+ * The presenter owns its display revision: entry changes, thinking toggles,
82
+ * theme invalidation, width changes, and component-initiated repaint requests
83
+ * all raise it. `render` reuses its line cache only while that revision and
84
+ * the width are unchanged; content is never re-assigned on a pure repaint or
85
+ * resize.
86
+ *
87
+ * Mouse handling is normalized: pass a `TuiMouseEvent` whose `y` is a row in
88
+ * the full transcript (visible row + scroll offset). The presenter maps it to
89
+ * the owning component and forwards it through the component's public
90
+ * `handleMouse`, so Pi's native thinking-block and tool-expansion click paths
91
+ * keep working without private fields.
92
+ */
93
+ export declare class TranscriptPresenter {
94
+ private readonly options;
95
+ private readonly assistantComponents;
96
+ private readonly assistantContent;
97
+ private readonly userComponents;
98
+ private readonly userText;
99
+ private readonly toolState;
100
+ private blocks;
101
+ private blockIdentities;
102
+ private rows;
103
+ private renderedToolComponents;
104
+ private cachedFrame;
105
+ private renderedWidth;
106
+ private renderedRevision;
107
+ private revisionValue;
108
+ private thinkingPreference;
109
+ private readonly expandedSegments;
110
+ private attachedTui;
111
+ private disposed;
112
+ constructor(options: TranscriptPresenterOptions);
113
+ /** Latest display revision. */
114
+ get revision(): number;
115
+ /** Retained presenter-owned message components (user + assistant). */
116
+ get componentCount(): number;
117
+ /**
118
+ * The presenter's local thinking preference. This is not the host patch's
119
+ * effective per-message state: in `auto` a collapse patch may still hide a
120
+ * completed message while the preference remains "visible".
121
+ */
122
+ get thinkingVisible(): boolean;
123
+ /** Wires the host TUI that receives repaint requests. */
124
+ attachTui(tui: TranscriptTui): void;
125
+ /** Stops forwarding repaint requests without discarding retained state. */
126
+ detachTui(): void;
127
+ /**
128
+ * Marks the display dirty and asks the attached TUI to repaint. Hosts wire
129
+ * tool components' repaint requests here so renderer-driven invalidations
130
+ * bypass the presenter's line cache.
131
+ */
132
+ requestRender(): void;
133
+ /**
134
+ * Synchronizes the presenter with the current entries. Components are
135
+ * created or updated only when their segment/content actually changed; a
136
+ * repeated sync of unchanged entries leaves the display revision alone.
137
+ */
138
+ sync(entries: readonly TranscriptEntry[]): number;
139
+ /**
140
+ * Renders the synced entries at `width`. When nothing changed since the last
141
+ * frame, the cached frame is returned unchanged.
142
+ */
143
+ render(width: number): TranscriptPresenterFrame;
144
+ /**
145
+ * Routes a normalized mouse event (transcript-space `y`) to the component
146
+ * whose row contains it. Returns whether the component handled the event.
147
+ */
148
+ handleMouse(event: TuiMouseEvent): boolean;
149
+ /**
150
+ * Applies the presenter's local thinking preference to every retained
151
+ * assistant component.
152
+ *
153
+ * Hiding uses the public `setHideThinkingBlock(true)`, which also clears
154
+ * native per-block overrides. Showing first forces the known collapsed state
155
+ * through the same public setter, then dispatches the native thinking-block
156
+ * click through `MouseRegion.handleMouse`. That sets the same per-block
157
+ * override a user click sets, so completed messages expand even while a
158
+ * host collapse patch keeps auto-collapsing them. No private component field
159
+ * is read and the streaming flag is never faked.
160
+ */
161
+ setThinkingVisible(visible: boolean): void;
162
+ /** Flips the local thinking preference and returns the new visibility. */
163
+ toggleThinkingVisibility(): boolean;
164
+ /**
165
+ * Invalidates native components for a theme change and raises the display
166
+ * revision. The host's global theme is never re-initialized here.
167
+ */
168
+ invalidate(): void;
169
+ /** Drops retained message components and rendered layout. */
170
+ clear(): void;
171
+ /**
172
+ * Releases every retained component and detaches the TUI. Idempotent; later
173
+ * calls to `sync`, `render`, and `handleMouse` degrade to no-ops.
174
+ */
175
+ dispose(): void;
176
+ private dropRetainedState;
177
+ private ensureAssistantComponent;
178
+ /**
179
+ * Expands every thinking block in `component` through the native public
180
+ * click path. When the host has no thinking `MouseRegion` (an older Pi), it
181
+ * degrades to the public visibility setter.
182
+ */
183
+ private expandThinking;
184
+ private componentForRow;
185
+ private renderBlocks;
186
+ }