@sema-agent/core 7.59.0 → 7.60.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 (360) hide show
  1. package/CHANGELOG.md +564 -0
  2. package/dist/agents/agent-definition.d.ts +7 -0
  3. package/dist/agents/agent-definition.js +12 -0
  4. package/dist/agents/agent-transcript-tool.d.ts +2 -1
  5. package/dist/agents/agent-transcript-tool.js +3 -1
  6. package/dist/agents/child-model-seat.js +6 -3
  7. package/dist/agents/cumulative-stats.js +0 -1
  8. package/dist/agents/inherited-tool-pool.d.ts +26 -1
  9. package/dist/agents/inherited-tool-pool.js +22 -0
  10. package/dist/agents/retain-ledger.d.ts +11 -1
  11. package/dist/agents/retain-ledger.js +13 -2
  12. package/dist/agents/roster-store.d.ts +1 -1
  13. package/dist/agents/roster-store.js +3 -1
  14. package/dist/agents/send-message-tool.d.ts +8 -19
  15. package/dist/agents/send-message-tool.js +11 -38
  16. package/dist/agents/subagent.d.ts +51 -17
  17. package/dist/agents/subagent.js +117 -78
  18. package/dist/agents/tool-filter.d.ts +1 -3
  19. package/dist/agents/tool-filter.js +4 -12
  20. package/dist/bench/metrics.d.ts +3 -5
  21. package/dist/bench/metrics.js +0 -1
  22. package/dist/brain/degrading.js +3 -1
  23. package/dist/brain/route-adjudicator.js +3 -1
  24. package/dist/brain/status-sink.d.ts +7 -1
  25. package/dist/brain/status-sink.js +6 -0
  26. package/dist/brain/timeout.d.ts +3 -1
  27. package/dist/brain/timeout.js +18 -5
  28. package/dist/core/a2a.d.ts +15 -5
  29. package/dist/core/a2a.js +34 -19
  30. package/dist/core/agent-definition.d.ts +20 -0
  31. package/dist/core/allow-entry.d.ts +2 -0
  32. package/dist/core/allow-entry.js +3 -1
  33. package/dist/core/artifact-host.d.ts +0 -2
  34. package/dist/core/artifact-host.js +0 -1
  35. package/dist/core/auto-mode-defaults.d.ts +8 -0
  36. package/dist/core/auto-mode-defaults.js +1 -0
  37. package/dist/core/auto-mode-rebuild.d.ts +2 -1
  38. package/dist/core/auto-mode.d.ts +39 -4
  39. package/dist/core/auto-mode.js +63 -12
  40. package/dist/core/background-agent-store.d.ts +10 -1
  41. package/dist/core/background-agent-store.js +3 -2
  42. package/dist/core/background-shell.d.ts +12 -1
  43. package/dist/core/background-shell.js +12 -0
  44. package/dist/core/checkpoint-store.d.ts +8 -13
  45. package/dist/core/checkpoint-store.js +4 -3
  46. package/dist/core/compliance.d.ts +1 -1
  47. package/dist/core/credential-echo.d.ts +52 -0
  48. package/dist/core/credential-echo.js +65 -0
  49. package/dist/core/credential-vocabulary.d.ts +13 -3
  50. package/dist/core/credential-vocabulary.js +12 -4
  51. package/dist/core/cross-boundary-taint.d.ts +4 -5
  52. package/dist/core/engine-notice.d.ts +58 -15
  53. package/dist/core/frame-settlement.d.ts +5 -0
  54. package/dist/core/frame-settlement.js +4 -0
  55. package/dist/core/gate-fold.js +7 -5
  56. package/dist/core/gate-lanes.js +39 -8
  57. package/dist/core/governance-codes.d.ts +9 -1
  58. package/dist/core/governance-codes.js +12 -0
  59. package/dist/core/hands-band-screen.js +0 -1
  60. package/dist/core/hands-band.d.ts +0 -3
  61. package/dist/core/hooks.d.ts +39 -56
  62. package/dist/core/hooks.js +123 -77
  63. package/dist/core/image-admission.d.ts +104 -51
  64. package/dist/core/image-admission.js +170 -46
  65. package/dist/core/image-downsample.d.ts +36 -69
  66. package/dist/core/image-downsample.js +111 -73
  67. package/dist/core/integer-option.d.ts +21 -0
  68. package/dist/core/integer-option.js +13 -0
  69. package/dist/core/locked-config.d.ts +54 -3
  70. package/dist/core/locked-config.js +81 -50
  71. package/dist/core/mcp-call-meta.d.ts +2 -2
  72. package/dist/core/mcp-call-meta.js +9 -10
  73. package/dist/core/mcp-failure.d.ts +9 -3
  74. package/dist/core/mcp-failure.js +10 -0
  75. package/dist/core/mcp-host-seat.d.ts +92 -0
  76. package/dist/core/mcp-host-seat.js +131 -0
  77. package/dist/core/mcp-probe.d.ts +7 -2
  78. package/dist/core/mcp-probe.js +7 -2
  79. package/dist/core/mcp-server-spec.d.ts +38 -9
  80. package/dist/core/mcp-server-spec.js +55 -21
  81. package/dist/core/mcp.d.ts +17 -6
  82. package/dist/core/mcp.js +67 -55
  83. package/dist/core/memory-admission.d.ts +23 -6
  84. package/dist/core/memory-admission.js +19 -9
  85. package/dist/core/memory-engine/content-origin.d.ts +13 -0
  86. package/dist/core/memory-engine/content-origin.js +21 -3
  87. package/dist/core/memory-engine/index.d.ts +2 -1
  88. package/dist/core/memory-engine/index.js +2 -1
  89. package/dist/core/memory-engine/scope-contract.d.ts +13 -3
  90. package/dist/core/memory-engine/scope-contract.js +2 -2
  91. package/dist/core/memory-engine/sync-client.d.ts +45 -11
  92. package/dist/core/memory-engine/sync-client.js +82 -11
  93. package/dist/core/memory-engine/sync-report.d.ts +103 -0
  94. package/dist/core/memory-engine/sync-report.js +119 -0
  95. package/dist/core/memory-engine/sync.d.ts +4 -2
  96. package/dist/core/mode-policy.d.ts +9 -1
  97. package/dist/core/mode-policy.js +11 -1
  98. package/dist/core/model-receipt.d.ts +39 -0
  99. package/dist/core/model-receipt.js +139 -0
  100. package/dist/core/mods/agent-stations.d.ts +65 -0
  101. package/dist/core/mods/agent-stations.js +105 -0
  102. package/dist/core/mods/kernel/dispatch.d.ts +5 -1
  103. package/dist/core/mods/kernel/dispatch.js +4 -4
  104. package/dist/core/mods/kernel/events.d.ts +10 -4
  105. package/dist/core/mods/kernel/events.js +10 -6
  106. package/dist/core/mods/kernel/receive.d.ts +5 -0
  107. package/dist/core/mods/kernel/receive.js +10 -0
  108. package/dist/core/mods/lifecycle-stations.d.ts +41 -0
  109. package/dist/core/mods/lifecycle-stations.js +35 -0
  110. package/dist/core/mods/stations.d.ts +51 -59
  111. package/dist/core/mods/stations.js +32 -42
  112. package/dist/core/mods/tool-call.d.ts +10 -4
  113. package/dist/core/mods/tool-call.js +28 -12
  114. package/dist/core/mounted-mcp.d.ts +5 -0
  115. package/dist/core/mounted-mcp.js +2 -2
  116. package/dist/core/namespaced-rule-name.d.ts +7 -1
  117. package/dist/core/namespaced-rule-name.js +13 -2
  118. package/dist/core/oracle-isolation.js +1 -1
  119. package/dist/core/own-property-receipt.d.ts +3 -0
  120. package/dist/core/own-property-receipt.js +3 -0
  121. package/dist/core/park-selfcheck.js +8 -8
  122. package/dist/core/peer-seat.d.ts +63 -8
  123. package/dist/core/peer-seat.js +179 -34
  124. package/dist/core/permission-rule-consent.d.ts +0 -21
  125. package/dist/core/permission-rule-consent.js +1 -2
  126. package/dist/core/permission-rule-model.d.ts +4 -2
  127. package/dist/core/permission-rule-model.js +7 -6
  128. package/dist/core/protocol-http-auth.d.ts +14 -2
  129. package/dist/core/protocol-http-auth.js +16 -7
  130. package/dist/core/read-face-seats.d.ts +7 -5
  131. package/dist/core/read-face-seats.js +4 -1
  132. package/dist/core/redaction-marks.d.ts +4 -3
  133. package/dist/core/redaction-marks.js +2 -2
  134. package/dist/core/remote-env.d.ts +146 -98
  135. package/dist/core/remote-env.js +113 -14
  136. package/dist/core/retention.js +37 -12
  137. package/dist/core/retired-keys.d.ts +6 -1
  138. package/dist/core/retired-keys.js +4 -1
  139. package/dist/core/rewrite-rejudge.d.ts +12 -5
  140. package/dist/core/rewrite-rejudge.js +9 -5
  141. package/dist/core/roles.d.ts +37 -3
  142. package/dist/core/roles.js +126 -78
  143. package/dist/core/rule-owner.d.ts +3 -0
  144. package/dist/core/runner/assemble-result.d.ts +0 -5
  145. package/dist/core/runner/assemble-result.js +0 -1
  146. package/dist/core/runner/call-hook-stations.d.ts +17 -10
  147. package/dist/core/runner/call-hook-stations.js +21 -10
  148. package/dist/core/runner/child-tree.d.ts +7 -8
  149. package/dist/core/runner/child-tree.js +6 -6
  150. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  151. package/dist/core/runner/classifier-ladder.js +39 -8
  152. package/dist/core/runner/construction-doors.js +5 -0
  153. package/dist/core/runner/contracts.d.ts +62 -41
  154. package/dist/core/runner/cross-boundary-lane.d.ts +3 -5
  155. package/dist/core/runner/cross-boundary-lane.js +11 -2
  156. package/dist/core/runner/env-capability-census.d.ts +15 -20
  157. package/dist/core/runner/env-capability-census.js +25 -34
  158. package/dist/core/runner/file-history-request.d.ts +2 -2
  159. package/dist/core/runner/file-history-request.js +0 -8
  160. package/dist/core/runner/gate-exit.d.ts +75 -7
  161. package/dist/core/runner/gate-exit.js +20 -1
  162. package/dist/core/runner/git-status-frame.d.ts +5 -2
  163. package/dist/core/runner/git-status-frame.js +3 -4
  164. package/dist/core/runner/image.d.ts +7 -2
  165. package/dist/core/runner/image.js +14 -8
  166. package/dist/core/runner/inline-image.d.ts +10 -8
  167. package/dist/core/runner/inline-image.js +11 -9
  168. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  169. package/dist/core/runner/permission-rule-lanes.js +1 -1
  170. package/dist/core/runner/prepare-boundary-parks.d.ts +2 -2
  171. package/dist/core/runner/prepare-boundary-parks.js +3 -3
  172. package/dist/core/runner/prepare-caps-and-workflow.d.ts +4 -0
  173. package/dist/core/runner/prepare-caps-and-workflow.js +4 -3
  174. package/dist/core/runner/prepare-config-doors.d.ts +6 -1
  175. package/dist/core/runner/prepare-config-doors.js +14 -9
  176. package/dist/core/runner/prepare-delegation-surface.d.ts +5 -3
  177. package/dist/core/runner/prepare-delegation-surface.js +4 -4
  178. package/dist/core/runner/prepare-file-history.d.ts +10 -12
  179. package/dist/core/runner/prepare-file-history.js +3 -12
  180. package/dist/core/runner/prepare-gate-stations.d.ts +4 -3
  181. package/dist/core/runner/prepare-gate-stations.js +4 -3
  182. package/dist/core/runner/prepare-hands-readface.d.ts +3 -1
  183. package/dist/core/runner/prepare-hands-readface.js +15 -7
  184. package/dist/core/runner/prepare-inherited-gate.d.ts +5 -4
  185. package/dist/core/runner/prepare-inherited-gate.js +9 -5
  186. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  187. package/dist/core/runner/prepare-memory.d.ts +2 -2
  188. package/dist/core/runner/prepare-memory.js +2 -2
  189. package/dist/core/runner/prepare-park-ask.d.ts +3 -5
  190. package/dist/core/runner/prepare-park-ask.js +3 -8
  191. package/dist/core/runner/prepare-policy-chain.d.ts +5 -4
  192. package/dist/core/runner/prepare-policy-chain.js +120 -108
  193. package/dist/core/runner/prepare-project-context.js +8 -5
  194. package/dist/core/runner/prepare-prompt-inputs.d.ts +4 -1
  195. package/dist/core/runner/prepare-prompt-inputs.js +3 -2
  196. package/dist/core/runner/prepare-protocol-tools.d.ts +5 -3
  197. package/dist/core/runner/prepare-protocol-tools.js +9 -2
  198. package/dist/core/runner/prepare-suspend-saga.d.ts +0 -2
  199. package/dist/core/runner/prepare-suspend-saga.js +5 -7
  200. package/dist/core/runner/prepare-task.js +41 -27
  201. package/dist/core/runner/prepare-turn-wiring.d.ts +2 -0
  202. package/dist/core/runner/prepare-turn-wiring.js +7 -2
  203. package/dist/core/runner/prepare-wiring-manifest.d.ts +4 -3
  204. package/dist/core/runner/prepare-wiring-manifest.js +32 -18
  205. package/dist/core/runner/prepare-workspace-restore.js +3 -3
  206. package/dist/core/runner/resume-checkpoint-screen.js +4 -4
  207. package/dist/core/runner/retired-runner-deps.js +4 -1
  208. package/dist/core/runner/run-attachment-seats.js +3 -3
  209. package/dist/core/runner/run-brain-sinks.js +1 -0
  210. package/dist/core/runner/run-git-lane.d.ts +3 -1
  211. package/dist/core/runner/run-git-lane.js +1 -1
  212. package/dist/core/runner/run-harness-handlers.d.ts +3 -1
  213. package/dist/core/runner/run-harness-handlers.js +3 -1
  214. package/dist/core/runner/run-identity-wiring.js +1 -1
  215. package/dist/core/runner/run-leg.js +26 -28
  216. package/dist/core/runner/run-notification-lane.d.ts +3 -1
  217. package/dist/core/runner/run-notification-lane.js +16 -10
  218. package/dist/core/runner/run-settle-and-teardown.js +5 -1
  219. package/dist/core/runner/run-stop-and-final-verify.d.ts +4 -0
  220. package/dist/core/runner/run-stop-and-final-verify.js +12 -4
  221. package/dist/core/runner/run-turn-boundary.js +12 -7
  222. package/dist/core/runner/runtask.d.ts +7 -4
  223. package/dist/core/runner/runtask.js +19 -11
  224. package/dist/core/runner/skills-seat.js +2 -2
  225. package/dist/core/runner/sub-agent-deny-lists.js +10 -7
  226. package/dist/core/runner/synthetic-tools.js +2 -2
  227. package/dist/core/runner/tool-disclosure.js +0 -2
  228. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  229. package/dist/core/runner/tool-face-overlay.js +26 -19
  230. package/dist/core/runner/tool-result-media-seat.d.ts +9 -1
  231. package/dist/core/runner/tool-result-media-seat.js +17 -1
  232. package/dist/core/runner/turn-attachments.d.ts +3 -5
  233. package/dist/core/runner/turn-attachments.js +3 -16
  234. package/dist/core/runner-deps.d.ts +31 -18
  235. package/dist/core/secret-env.d.ts +3 -2
  236. package/dist/core/session-policy-store.d.ts +9 -2
  237. package/dist/core/session-policy-store.js +16 -1
  238. package/dist/core/session-store.d.ts +3 -2
  239. package/dist/core/session-store.js +50 -11
  240. package/dist/core/skill-grant.d.ts +9 -0
  241. package/dist/core/skill-grant.js +18 -0
  242. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  243. package/dist/core/store-contracts/tool-result-store-contract.js +37 -0
  244. package/dist/core/stub-env.d.ts +5 -5
  245. package/dist/core/stub-env.js +11 -1
  246. package/dist/core/swappable-deps.d.ts +17 -43
  247. package/dist/core/swappable-deps.js +15 -5
  248. package/dist/core/synthetic-read-verdict.d.ts +1 -1
  249. package/dist/core/task-event.d.ts +18 -2
  250. package/dist/core/task-notification.d.ts +88 -5
  251. package/dist/core/task-notification.js +130 -7
  252. package/dist/core/task-registry-agent.d.ts +18 -12
  253. package/dist/core/task-registry-agent.js +18 -6
  254. package/dist/core/task-registry-monitor.d.ts +7 -0
  255. package/dist/core/task-registry-monitor.js +28 -1
  256. package/dist/core/task-registry-shared.d.ts +38 -3
  257. package/dist/core/task-registry-shared.js +21 -7
  258. package/dist/core/task-registry-workflow.js +1 -1
  259. package/dist/core/task-registry.d.ts +50 -35
  260. package/dist/core/task-registry.js +64 -23
  261. package/dist/core/task-result.d.ts +3 -12
  262. package/dist/core/task-spec.d.ts +3 -6
  263. package/dist/core/task-stream.d.ts +1 -1
  264. package/dist/core/tool-catalog-entries.js +1 -1
  265. package/dist/core/tool-face-reader.d.ts +7 -6
  266. package/dist/core/tool-face-reader.js +4 -3
  267. package/dist/core/tool-name-aliases.d.ts +19 -0
  268. package/dist/core/tool-name-aliases.js +54 -2
  269. package/dist/core/tool-policy.d.ts +5 -4
  270. package/dist/core/tool-policy.js +1 -1
  271. package/dist/core/tool-registry.d.ts +5 -5
  272. package/dist/core/tool-registry.js +2 -2
  273. package/dist/core/tool-result-store.d.ts +88 -5
  274. package/dist/core/tool-result-store.js +51 -12
  275. package/dist/core/tool-spec.d.ts +20 -4
  276. package/dist/core/trace.d.ts +0 -1
  277. package/dist/core/types.d.ts +3 -3
  278. package/dist/core/types.js +1 -1
  279. package/dist/core/untrusted-text.js +1 -1
  280. package/dist/core/user-attachment.d.ts +10 -5
  281. package/dist/core/user-attachment.js +14 -6
  282. package/dist/engine/execution-env/node-execution-env.d.ts +7 -2
  283. package/dist/engine/execution-env/node-execution-env.js +12 -1
  284. package/dist/engine/harness/agent-harness.d.ts +1 -1
  285. package/dist/engine/harness/agent-harness.js +8 -4
  286. package/dist/engine/harness/types.d.ts +112 -29
  287. package/dist/engine/loop/agent-loop.d.ts +12 -12
  288. package/dist/engine/loop/agent-loop.js +153 -21
  289. package/dist/engine/loop/types.d.ts +9 -2
  290. package/dist/engine/lsp/node-lsp-manager.d.ts +3 -3
  291. package/dist/engine/lsp/node-lsp-manager.js +32 -13
  292. package/dist/index.d.ts +22 -14
  293. package/dist/index.js +15 -10
  294. package/dist/internal/harness-types.d.ts +1 -1
  295. package/dist/orchestration/run-workflow-tool.d.ts +9 -3
  296. package/dist/orchestration/run-workflow-tool.js +59 -29
  297. package/dist/orchestration/workflow-governance.d.ts +1 -1
  298. package/dist/orchestration/workflow-governance.js +2 -1
  299. package/dist/orchestration/workflow.d.ts +4 -0
  300. package/dist/orchestration/workflow.js +25 -4
  301. package/dist/prompts/default.d.ts +1 -10
  302. package/dist/prompts/default.js +0 -2
  303. package/dist/stores/file/background-agent-store.d.ts +1 -1
  304. package/dist/stores/file/background-agent-store.js +3 -1
  305. package/dist/stores/file/checkpoint-store.d.ts +127 -2
  306. package/dist/stores/file/checkpoint-store.js +19 -14
  307. package/dist/stores/file/file-history-store.d.ts +1 -1
  308. package/dist/stores/file/file-history-store.js +3 -1
  309. package/dist/stores/file/index.d.ts +4 -3
  310. package/dist/stores/file/index.js +17 -8
  311. package/dist/stores/file/mailbox-store.d.ts +1 -1
  312. package/dist/stores/file/mailbox-store.js +3 -1
  313. package/dist/stores/file/memory-store.d.ts +1 -1
  314. package/dist/stores/file/memory-store.js +3 -1
  315. package/dist/stores/file/session-policy-store.d.ts +1 -1
  316. package/dist/stores/file/session-policy-store.js +3 -1
  317. package/dist/stores/file/session-store.d.ts +1 -1
  318. package/dist/stores/file/session-store.js +3 -1
  319. package/dist/stores/file/shared-ledger.d.ts +26 -0
  320. package/dist/stores/file/shared-ledger.js +38 -9
  321. package/dist/stores/file/tool-result-store.d.ts +20 -2
  322. package/dist/stores/file/tool-result-store.js +74 -6
  323. package/dist/stores/file/usage-window-store.d.ts +1 -1
  324. package/dist/stores/file/usage-window-store.js +3 -1
  325. package/dist/stores/file/workflow-journal-store.d.ts +1 -11
  326. package/dist/stores/file/workflow-journal-store.js +3 -2
  327. package/dist/tools/fs/containment-face.d.ts +5 -0
  328. package/dist/tools/fs/encoding.d.ts +13 -4
  329. package/dist/tools/fs/encoding.js +17 -2
  330. package/dist/tools/fs/fs-bash-background-text.d.ts +7 -0
  331. package/dist/tools/fs/fs-bash-background-text.js +1 -0
  332. package/dist/tools/fs/fs-bash.d.ts +8 -4
  333. package/dist/tools/fs/fs-bash.js +26 -35
  334. package/dist/tools/fs/fs-pdf.d.ts +2 -2
  335. package/dist/tools/fs/fs-pdf.js +26 -21
  336. package/dist/tools/fs/fs-read.d.ts +5 -4
  337. package/dist/tools/fs/fs-read.js +35 -18
  338. package/dist/tools/fs/fs-search-tools.js +4 -1
  339. package/dist/tools/fs/fs-shared.d.ts +11 -13
  340. package/dist/tools/fs/fs-shared.js +11 -7
  341. package/dist/tools/fs/fs-write.js +5 -5
  342. package/dist/tools/fs/index.d.ts +14 -8
  343. package/dist/tools/fs/index.js +8 -4
  344. package/dist/tools/fs/read-floor.d.ts +44 -1
  345. package/dist/tools/fs/read-floor.js +35 -0
  346. package/dist/tools/fs/removal-targets.d.ts +9 -4
  347. package/dist/tools/fs/removal-targets.js +17 -9
  348. package/dist/tools/fs/search.d.ts +3 -3
  349. package/dist/tools/fs/search.js +4 -4
  350. package/dist/tools/monitor.d.ts +5 -4
  351. package/dist/tools/monitor.js +15 -8
  352. package/dist/tools/scheduler-tools.js +42 -4
  353. package/dist/tools/web.d.ts +0 -10
  354. package/dist/tools/web.js +1 -4
  355. package/package.json +4 -2
  356. package/test/export-surface.snapshot.json +75 -21
  357. package/wire-changes/core-stores-sql@7.60.0.json +30 -0
  358. package/wire-changes/core@7.60.0.json +3274 -0
  359. package/wire-changes/mods-kernel@7.60.0.json +62 -0
  360. package/wire-changes/primitives@7.60.0.json +30 -0
@@ -178,13 +178,27 @@ export function terminalFrameFacets(facts) {
178
178
  };
179
179
  }
180
180
  const COMPLETION_REPORT_MAX = 2_000;
181
- export function notifyResultField(result) {
181
+ function cutReportReading(artifact) {
182
+ switch (artifact.kind) {
183
+ case "stored":
184
+ return `read the full text with ReadToolResult (ref "${artifact.ref}")`;
185
+ case "unconfirmed":
186
+ return "the full text could not be stored (the write failed or went unconfirmed), so no ref can read it back — ask the agent for it via SendMessage, or read it with TaskOutput where mounted";
187
+ case "no_store":
188
+ return "the full text is not stored behind a ref (no offload store) — ask the agent for it via SendMessage, or read it with TaskOutput where mounted";
189
+ }
190
+ }
191
+ export async function completionResultField(result, persist) {
182
192
  if (!result)
183
193
  return undefined;
184
194
  const report = egressText("same-principal", result);
185
- return report.length > COMPLETION_REPORT_MAX
186
- ? `${report.slice(0, COMPLETION_REPORT_MAX)}\n[result truncated: ${report.length} chars total — ask the agent for it via SendMessage, or read it with TaskOutput where mounted]`
187
- : report;
195
+ if (report.length <= COMPLETION_REPORT_MAX)
196
+ return { text: report };
197
+ const artifact = await persist(report);
198
+ return {
199
+ text: `${report.slice(0, COMPLETION_REPORT_MAX)}\n[result truncated: ${report.length} chars total — ${cutReportReading(artifact)}]`,
200
+ ...(artifact.kind === "stored" ? { ref: artifact.ref } : {}),
201
+ };
188
202
  }
189
203
  export const ENGINE_FRAME_CODEC_VERSION = 1;
190
204
  export const ENGINE_FRAME_TASK_TYPES = Object.freeze(["background_agent", "monitor", "workflow"]);
@@ -276,6 +290,89 @@ export function isDelegatedAgentTerminal(n) {
276
290
  export function isTerminalTaskNotification(n) {
277
291
  return TERMINAL_STATUSES.has(n.status);
278
292
  }
293
+ export function resolveCompletionSink(callSink, mountSink) {
294
+ return callSink ?? mountSink;
295
+ }
296
+ export class DeliveryObligations {
297
+ owed = new Map();
298
+ counted = new Set();
299
+ wakers = new Set();
300
+ waitDeadline;
301
+ owe(task) {
302
+ const lane = taskNotificationLaneKey(task);
303
+ this.owed.set(lane, (this.owed.get(lane) ?? 0) + 1);
304
+ }
305
+ discharge(frame) {
306
+ const lane = taskNotificationLaneKey(frame);
307
+ const key = taskNotificationDedupKey(frame);
308
+ if (!this.owed.has(lane) || this.counted.has(key))
309
+ return;
310
+ this.counted.add(key);
311
+ this.release(lane);
312
+ }
313
+ retire(task) {
314
+ this.release(taskNotificationLaneKey(task));
315
+ }
316
+ release(lane) {
317
+ const cycles = this.owed.get(lane);
318
+ if (cycles === undefined)
319
+ return;
320
+ if (cycles > 1)
321
+ this.owed.set(lane, cycles - 1);
322
+ else
323
+ this.owed.delete(lane);
324
+ this.wake();
325
+ }
326
+ wake() {
327
+ for (const wake of [...this.wakers])
328
+ wake();
329
+ }
330
+ get pending() {
331
+ return [...this.owed.keys()];
332
+ }
333
+ nextDischarge(signal, withinMs) {
334
+ if (this.owed.size === 0 || signal.aborted || withinMs <= 0)
335
+ return Promise.resolve();
336
+ return new Promise((resolve) => {
337
+ const timer = setTimeout(() => wake(), withinMs);
338
+ timer.unref?.();
339
+ const wake = () => {
340
+ clearTimeout(timer);
341
+ this.wakers.delete(wake);
342
+ signal.removeEventListener("abort", wake);
343
+ resolve();
344
+ };
345
+ this.wakers.add(wake);
346
+ signal.addEventListener("abort", wake, { once: true });
347
+ });
348
+ }
349
+ async waitOut(signal, keepWaiting, onInput) {
350
+ if (this.owed.size === 0)
351
+ return;
352
+ this.waitDeadline ??= performance.now() + ONE_SHOT_WAIT_CEILING_MS;
353
+ const unsubscribe = onInput(() => this.wake());
354
+ try {
355
+ while (this.owed.size > 0 && keepWaiting() && !signal.aborted && performance.now() < this.waitDeadline)
356
+ await this.nextDischarge(signal, this.waitDeadline - performance.now());
357
+ }
358
+ finally {
359
+ unsubscribe();
360
+ }
361
+ }
362
+ }
363
+ const ONE_SHOT_WAIT_CEILING_MS = 600_000;
364
+ const LANE_OBLIGATIONS = new WeakMap();
365
+ export function bindDeliveryObligations(sink, book) {
366
+ LANE_OBLIGATIONS.set(sink, book);
367
+ }
368
+ export function oweTerminalDelivery(sink, task) {
369
+ if (typeof sink === "function")
370
+ LANE_OBLIGATIONS.get(sink)?.owe(task);
371
+ }
372
+ export function retireTerminalDelivery(sink, task) {
373
+ if (typeof sink === "function")
374
+ LANE_OBLIGATIONS.get(sink)?.retire(task);
375
+ }
279
376
  export function createLiveNotificationLane(seat) {
280
377
  const handedOff = new Set();
281
378
  const enter = (admits) => (payload, priority, onDisposition) => {
@@ -575,7 +672,7 @@ function evictOldest(s, match) {
575
672
  const prior = s.dropped.get(laneKey);
576
673
  s.dropped.set(laneKey, { count: (prior?.count ?? 0) + 1, taskType: victim.task_type, taskId: victim.task_id });
577
674
  }
578
- export function discloseDroppedPending(drained) {
675
+ export function discloseDroppedPending(drained, readHandleOf, tasks) {
579
676
  const hasSessionLoss = drained.droppedWholeSession !== undefined && drained.droppedWholeSession > 0;
580
677
  if (!hasSessionLoss && drained.dropped.size === 0)
581
678
  return drained.items;
@@ -585,7 +682,7 @@ export function discloseDroppedPending(drained) {
585
682
  task_id: "session",
586
683
  task_type: "background_agent",
587
684
  status: "event",
588
- summary: `${drained.droppedWholeSession} pending notification(s) for this session were dropped before this turn (the pending store evicted the whole session under its session-count cap). Which tasks they came from is no longer known.`,
685
+ summary: `${drained.droppedWholeSession} pending notification(s) for this session were dropped before this turn (the pending store evicted the whole session under its session-count cap). Which tasks they came from is no longer known.${tasks === undefined ? "" : sessionLossTableClause(tasks())}`,
589
686
  },
590
687
  ]
591
688
  : [];
@@ -627,11 +724,37 @@ export function discloseDroppedPending(drained) {
627
724
  task_id: taskId,
628
725
  task_type: dropped.taskType,
629
726
  status: "event",
630
- summary: `[${taskId}] ${dropped.count} pending notification(s) from this task were dropped (pending-queue overflow) before this turn; nothing else from it survived. TaskOutput("${taskId}") may still serve its spool.`,
727
+ summary: `[${taskId}] ${dropped.count} pending notification(s) from this task were dropped (pending-queue overflow) before this turn; nothing else from it survived.${dropped.taskType === "external" || readHandleOf === undefined ? "" : droppedReadClause(readHandleOf(taskId))}`,
631
728
  });
632
729
  }
633
730
  return [...out, ...sessionLine];
634
731
  }
732
+ function droppedReadClause(read) {
733
+ return read !== undefined ? ` Its ${read}.` : " Its row is no longer readable from this run.";
734
+ }
735
+ const BACKGROUND_TASK_TABLE_ROWS_MAX = 50;
736
+ const BACKGROUND_TASK_TABLE_DESCRIPTION_MAX = 80;
737
+ export function renderBackgroundTaskTable(tasks) {
738
+ const unlisted = tasks.length - BACKGROUND_TASK_TABLE_ROWS_MAX;
739
+ const lines = tasks.slice(0, BACKGROUND_TASK_TABLE_ROWS_MAX).map((t) => {
740
+ const phrase = t.status === "completed"
741
+ ? "completed in background"
742
+ : t.status === "killed"
743
+ ? "stopped"
744
+ : t.status === "running"
745
+ ? "still running in background"
746
+ : t.status === "parked"
747
+ ? "parked awaiting an out-of-band approval — do NOT re-issue the gated call"
748
+ : t.status;
749
+ return `- [${t.id}] Task "${(t.description ?? "background task").slice(0, BACKGROUND_TASK_TABLE_DESCRIPTION_MAX)}" ${phrase}${t.read !== undefined ? ` — ${t.read}` : ""}`;
750
+ });
751
+ return lines.join("\n") + (unlisted > 0 ? `\n(+${unlisted} more background tasks, not listed here)` : "");
752
+ }
753
+ function sessionLossTableClause(rows) {
754
+ return rows.length === 0
755
+ ? " This run has no background task left to read."
756
+ : ` This run's background tasks (read output where its row says, terminate with TaskStop):\n${renderBackgroundTaskTable(rows)}`;
757
+ }
635
758
  export class SystemInjectionQueue {
636
759
  queues = {
637
760
  now: [],
@@ -1,5 +1,5 @@
1
1
  import { type BackgroundAgentRecord, type BackgroundAgentStore } from "./background-agent-store.js";
2
- import { type StopSource, type TaskAccess, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
2
+ import { type StopSource, type TaskAccess, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type RegisteredTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
3
3
  import { type ToolResultStore } from "./tool-result-store.js";
4
4
  import { type AgentState } from "./agent-state.js";
5
5
  import type { CheckpointSeat } from "./checkpoint-seat.js";
@@ -117,13 +117,24 @@ export declare function reapDurableAgentsLane(core: DurableAgentCore, scope: str
117
117
  skippedNoSessions: number;
118
118
  orphanPlacedReleased: number;
119
119
  }>;
120
- /** after a probe-false RELEASE the row must stop claiming a transcript:
121
- * the heartbeat's F-1 arm keeps re-driving a flush-failed lane, so a later successful flush
122
- * would otherwise persist a row whose sessionId points at the session the caller just released.
123
- * Clearing the anchor makes the eventual row honest: state/result survive, transcript does not. */
124
- export declare function releaseDurableTranscriptAnchorLane(core: DurableAgentCore, id: string): void;
120
+ /** The child session a background-agent row is anchored to right now — the session its child runs on
121
+ * or keeps (transcript / resume anchor) — or `undefined` before the bind, after the anchor's release,
122
+ * and on every other task type. The ONE reading of the anchor: the list row's `sessionId` and the
123
+ * release match below both read it here. */
124
+ export declare function childSessionAnchorOf(handle: RegisteredTaskHandle): string | undefined;
125
+ /** A successful release of the child session `sessionId` ends the row's claim on it: both copies of
126
+ * the anchor go — the handle's (the list row reads it) and the durable record's (the heartbeat's F-1
127
+ * arm keeps re-driving a flush-failed lane, so a later successful flush would otherwise persist a row
128
+ * pointing at the session the caller just released). The clear matches the PAIR (row, session): a late
129
+ * clear for a session the row no longer names leaves the current anchor alone. State/result survive,
130
+ * the transcript does not. */
131
+ export declare function releaseDurableTranscriptAnchorLane(core: DurableAgentCore, id: string, sessionId: string): void;
125
132
  /** design/151 S1a — bind the child's freshly-minted store session id onto the row (the transcript /
126
- * resume anchor; absent at register time because the child session is created after registration). */
133
+ * resume anchor; absent at register time because the child session is created after registration).
134
+ * A row already anchored to that session is left as it is (one fact, no second durable write). A row anchored to ANOTHER session
135
+ * is refused: an anchor changes only by its release ({@link releaseDurableTranscriptAnchorLane}) and a fresh bind, never by being
136
+ * written over, so the earlier session is never silently left unowned. An id that is no non-empty string is no anchor and is
137
+ * refused whatever the row holds. */
127
138
  export declare function bindBackgroundAgentSessionLane(core: DurableAgentCore, id: string, sessionId: string): void;
128
139
  /**
129
140
  * #22 — record the org-memory admission verdict THIS leg adjudicated onto the durable row, so the
@@ -556,11 +567,6 @@ agentState?: AgentState): UnifiedTaskResult;
556
567
  */
557
568
  export declare function spillClippedAgentResult(handle: BackgroundAgentTaskHandle, full: string, clipped: string, store: ToolResultStore | undefined, sessionId: string | undefined): Promise<string>;
558
569
  export declare function pollBackgroundAgentLane(handle: BackgroundAgentTaskHandle, deadline?: number, signal?: AbortSignal,
559
- /** Mirrors {@link import("./types.js").TaskSpec.oneShot} (see
560
- * {@link import("./task-registry.js").TaskToolOptions.oneShot} for the full contract): this run has
561
- * no later turn for an async background notification to land in, so the still-running body must
562
- * not teach "you will be notified when it completes". */
563
- oneShot?: boolean,
564
570
  /** design/158 S1 — the offload store a clipped result's full text spills to (see
565
571
  * {@link spillClippedAgentResult}). Absent ⇒ legal degrade, byte-identical to pre-S1 output. */
566
572
  store?: ToolResultStore,
@@ -296,6 +296,7 @@ export async function reapDurableAgentsLane(core, scope, deps, policy) {
296
296
  await deps.sessions.unpin?.(p.sessionId);
297
297
  await deps.sessions.release(p.sessionId);
298
298
  orphanPlacedReleased++;
299
+ releaseDurableTranscriptAnchorLane(core, p.handle, p.sessionId);
299
300
  }
300
301
  catch {
301
302
  }
@@ -310,16 +311,29 @@ export async function reapDurableAgentsLane(core, scope, deps, policy) {
310
311
  }
311
312
  return { rowsReaped, sessionsReleased, skippedNoSessions, orphanPlacedReleased };
312
313
  }
313
- export function releaseDurableTranscriptAnchorLane(core, id) {
314
+ export function childSessionAnchorOf(handle) {
315
+ return handle.type === "background_agent" ? handle.sessionId : undefined;
316
+ }
317
+ export function releaseDurableTranscriptAnchorLane(core, id, sessionId) {
314
318
  const handle = core.handles.get(id);
315
319
  if (!handle || handle.type !== "background_agent")
316
320
  return;
321
+ if (childSessionAnchorOf(handle) !== sessionId)
322
+ return;
323
+ delete handle.sessionId;
317
324
  durableAgentWriteLane(handle, {}, ["sessionId"]);
318
325
  }
319
326
  export function bindBackgroundAgentSessionLane(core, id, sessionId) {
327
+ if (typeof sessionId !== "string" || sessionId === "")
328
+ throw new Error(`TaskRegistry: a background-agent session anchor must be a non-empty session id (got ${typeof sessionId === "string" ? "an empty string" : `a ${sessionId === null ? "null" : typeof sessionId}`})`);
320
329
  const handle = core.handles.get(id);
321
330
  if (!handle || handle.type !== "background_agent")
322
331
  return;
332
+ const anchored = childSessionAnchorOf(handle);
333
+ if (anchored === sessionId)
334
+ return;
335
+ if (anchored !== undefined)
336
+ throw new Error(`TaskRegistry: background-agent row ${id} is anchored to a session already — release that anchor before binding another (the row keeps its anchor)`);
323
337
  handle.sessionId = sessionId;
324
338
  durableAgentWriteLane(handle, { sessionId });
325
339
  }
@@ -1095,6 +1109,7 @@ export async function reviveBackgroundAgentLane(core, id, access, abort) {
1095
1109
  handle.resultFull = undefined;
1096
1110
  handle.spillRef = undefined;
1097
1111
  handle.spillFailed = undefined;
1112
+ handle.artifactRef = undefined;
1098
1113
  handle.error = undefined;
1099
1114
  handle.errorCode = undefined;
1100
1115
  handle.errorRetryable = undefined;
@@ -1373,7 +1388,7 @@ export async function spillClippedAgentResult(handle, full, clipped, store, sess
1373
1388
  handle.spillRef = ref;
1374
1389
  return disclose(ref);
1375
1390
  }
1376
- export async function pollBackgroundAgentLane(handle, deadline, signal, oneShot, store, sessionId, checkpointSeat) {
1391
+ export async function pollBackgroundAgentLane(handle, deadline, signal, store, sessionId, checkpointSeat) {
1377
1392
  while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
1378
1393
  await sleepPollStep(deadline, signal);
1379
1394
  }
@@ -1419,10 +1434,7 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
1419
1434
  : "";
1420
1435
  const stateLine = `state: ${agentStateSummary(agentState)}\n`;
1421
1436
  const body = running
1422
- ? oneShot === true
1423
- ? `status: running
1424
- ${stateLine}This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput({ task_id: "${handle.id}", block: true }). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget.`
1425
- : `status: running
1437
+ ? `status: running
1426
1438
  ${stateLine}The agent is still working — you will be notified when it completes.`
1427
1439
  : `status: ${snap.status}
1428
1440
  ${stateLine}${snap.error ? `error: ${snap.error}${kindClause}
@@ -12,6 +12,13 @@ export declare function absorbMonitorPollLane(handle: MonitorTaskHandle, v: {
12
12
  truncated?: boolean;
13
13
  bytesDroppedBeforeCursor?: number;
14
14
  }): string[];
15
+ /** Append one poll's increment (stdout AND stderr) to the watch's output file — the bash watcher's mirror, for the
16
+ * same absorption's two consumers (the watcher tick and the stop-time drain). Never throws; a failed append is
17
+ * accounted on `spool.mirrorFailed` so the terminal frame says the file is incomplete instead of passing it off as whole. */
18
+ export declare function mirrorMonitorPollLane(handle: MonitorTaskHandle, v: {
19
+ stdout: string;
20
+ stderr: string;
21
+ }): Promise<void>;
15
22
  /** The swallow-guarded event sink, shared by the watcher's emits and the stop-time drain. */
16
23
  export declare function emitMonitorEventLane(handle: MonitorTaskHandle, n: TaskNotificationPayload): void;
17
24
  /** The monitor watcher tick loop. Same zombie-proofing discipline as {@link startBashWatcher}
@@ -29,6 +29,8 @@ export function registerMonitorLane(core, input) {
29
29
  env: input.env,
30
30
  shellId: input.shellId,
31
31
  spool: { stdout: "", stderr: "", rolledChars: 0 },
32
+ ...(input.outputFile !== undefined ? { outputFile: input.outputFile } : {}),
33
+ ...(input.taskArtifacts !== undefined ? { taskArtifacts: input.taskArtifacts } : {}),
32
34
  lineBuf: "",
33
35
  seq: 0,
34
36
  stormTokens: stormBurst,
@@ -116,6 +118,18 @@ export function absorbMonitorPollLane(handle, v) {
116
118
  handle.lineBuf = parts.pop() ?? "";
117
119
  return parts.filter((l) => l !== "");
118
120
  }
121
+ export async function mirrorMonitorPollLane(handle, v) {
122
+ if (handle.outputFile === undefined || (v.stdout.length === 0 && v.stderr.length === 0))
123
+ return;
124
+ try {
125
+ const ap = await handle.env.appendFile(handle.outputFile, v.stdout + v.stderr);
126
+ if (!ap.ok)
127
+ handle.spool.mirrorFailed = true;
128
+ }
129
+ catch {
130
+ handle.spool.mirrorFailed = true;
131
+ }
132
+ }
119
133
  function consumeStormToken(handle, now) {
120
134
  const gained = Math.floor((now - handle.stormRefilledAt) / handle.stormRefillIntervalMs);
121
135
  if (gained > 0) {
@@ -165,6 +179,7 @@ export function startMonitorWatcherLane(core, id) {
165
179
  ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
166
180
  status,
167
181
  ...(status === "killed" && handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
182
+ ...(handle.outputFile !== undefined ? { output_file: handle.outputFile } : {}),
168
183
  summary: `${terminalTaskSummary("monitor", (handle.description ?? "monitor").slice(0, 200), status, exitCode)} — ${detail}${droppedGapNote(handle.spool)}`,
169
184
  ...(finalLines.length > 0 ? { lines: finalLines.map(clipMonitorLine), result: clipMonitorEvent(finalLines.map(clipMonitorLine).join("\n")), ...(status === "killed" ? { partial: true } : {}) } : {}),
170
185
  ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
@@ -190,6 +205,12 @@ export function startMonitorWatcherLane(core, id) {
190
205
  return terminal("failed", `monitor lost its process (${r.error.message}); watch ended.${pendingSuppressionNote()}`, pendingFinalLines([]));
191
206
  }
192
207
  pollFailures = 0;
208
+ const mirrored = mirrorMonitorPollLane(handle, r.value);
209
+ handle.mirrorInFlight = mirrored;
210
+ await mirrored;
211
+ handle.mirrorInFlight = undefined;
212
+ if (core.handles.get(id) !== handle || handle.status !== "running")
213
+ return stop();
193
214
  const spool = handle.spool;
194
215
  const lines = absorbMonitorPollLane(handle, r.value);
195
216
  handle.status = statusFromBackground(r.value.status, r.value.exitCode);
@@ -367,6 +388,7 @@ function explicitStopTerminalNote(handle, alreadyGone) {
367
388
  ...(handle.toolUseId !== undefined ? { toolUseId: handle.toolUseId } : {}),
368
389
  status: "killed",
369
390
  ...(handle.stoppedBy !== undefined ? { stoppedBy: handle.stoppedBy } : {}),
391
+ ...(handle.outputFile !== undefined ? { output_file: handle.outputFile } : {}),
370
392
  summary: `${terminalTaskSummary("monitor", label, "killed")} — ${detail}${droppedGapNote(handle.spool)}`,
371
393
  ...(handle.completionId !== undefined ? { completionId: handle.completionId } : {}),
372
394
  });
@@ -377,11 +399,13 @@ export async function stopMonitorLane(core, handle) {
377
399
  handle.timers.clearInterval(handle.watcher);
378
400
  handle.watcher = undefined;
379
401
  }
402
+ let finalIncrement;
380
403
  if (wasRunning && handle.tickInFlight !== true) {
381
404
  try {
382
405
  const drained = await handle.env.pollBackground(handle.shellId);
383
406
  if (drained.ok) {
384
407
  const lines = absorbMonitorPollLane(handle, drained.value);
408
+ finalIncrement = drained.value;
385
409
  const finalLines = handle.lineBuf !== "" ? [...lines, handle.lineBuf] : lines;
386
410
  handle.lineBuf = "";
387
411
  if (finalLines.length > 0 && handle.status === "running") {
@@ -407,9 +431,12 @@ export async function stopMonitorLane(core, handle) {
407
431
  handle.spool.drainFailed = true;
408
432
  }
409
433
  }
410
- const drainNote = handle.spool.drainFailed === true ? " (the final output drain failed — TaskOutput may be missing the last window)" : "";
434
+ const drainNote = handle.spool.drainFailed === true ? " (the final output drain failed — the output file may be missing the last window)" : "";
411
435
  core.markStopSource(handle.id, "parent");
412
436
  const r = await handle.env.killBackground(handle.shellId);
437
+ await handle.mirrorInFlight;
438
+ if (finalIncrement !== undefined)
439
+ await mirrorMonitorPollLane(handle, finalIncrement);
413
440
  if (handle.status !== "running") {
414
441
  return {
415
442
  content: wasRunning ? `Terminated ${handle.id}.${drainNote}${consumePendingSuppressionNote(handle)}` : alreadyTerminalStopNote(handle.id, handle.status),
@@ -4,7 +4,7 @@ import { type WorkflowRunStore } from "./workflow-run-store.js";
4
4
  import type { BackgroundAgentRecord, BackgroundAgentStore } from "./background-agent-store.js";
5
5
  import type { WorkflowHandle, WorkflowRun } from "../orchestration/workflow.js";
6
6
  import type { TaskNotificationPayload } from "./task-notification.js";
7
- import type { ToolResultStore } from "./tool-result-store.js";
7
+ import type { TaskArtifactSeat, ToolResultStore } from "./tool-result-store.js";
8
8
  import type { AssertAllKeysHandled } from "./ask-origin.js";
9
9
  export type SemaTaskType = "background_bash" | "workflow" | "background_agent" | "monitor";
10
10
  /** design/134 §3.3 (R3): WHO initiated a kill — recorded at the initiation site (first-marker-wins),
@@ -107,10 +107,18 @@ export interface SemaTaskHandle {
107
107
  createdAt: number;
108
108
  updatedAt: number;
109
109
  outputFile?: string;
110
+ /** The ref a background agent's or workflow's full result was stored under when its completion frame cut it
111
+ * (`persistTaskArtifact`, recorded by {@link import("./task-registry.js").TaskRegistry.recordArtifactRef}). */
112
+ artifactRef?: string;
110
113
  /** P1-3 — see {@link UnifiedTaskOutput.completionId}. Minted fill-once at this task's own settle
111
114
  * point ({@link mintCompletionId}); absent until the task reaches a terminal status. */
112
115
  completionId?: string;
113
116
  }
117
+ /** THE read handle of one background task, as every model-facing list of tasks names it: a command's output file
118
+ * (Read it), or the ref a cut result is stored under (ReadToolResult). `undefined` = nothing to read beyond what its
119
+ * notification carried. One reading — the post-compaction table and a dropped-notification line both call it. A
120
+ * blank path or ref (empty or all whitespace) names nothing, so it reads as no handle. */
121
+ export declare function taskReadHandleText(h: Pick<SemaTaskHandle, "outputFile" | "artifactRef">): string | undefined;
114
122
  /** Mint a cross-channel completion correlation id ONCE per
115
123
  * handle/record, fill-once (first writer wins): every settle/direct-terminal-flip site calls this
116
124
  * instead of writing `completionId` directly, so no matter how many terminal-transition sites a lane
@@ -178,6 +186,9 @@ export interface BackgroundBashTaskHandle extends SemaTaskHandle {
178
186
  droppedBytes?: number;
179
187
  dropUnknown?: true;
180
188
  };
189
+ /** Where the command's retained output is stored when its output file is missing or incomplete — the result-artifact
190
+ * seat the launching call carried (`ToolExecuteContext.taskArtifacts`); absent ⇒ nothing is stored. */
191
+ taskArtifacts?: TaskArtifactSeat;
181
192
  watcher?: ReturnType<typeof setInterval>;
182
193
  /** design/134 §3.3 (R3 MED, 修类不修点): same attribution pair as the agent handle — see there. */
183
194
  stopSource?: StopSource;
@@ -260,7 +271,9 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
260
271
  parentSessionId?: string;
261
272
  rootSessionId?: string;
262
273
  /** design/151 S1a — the child's store session id (transcript/resume anchor), bound once the child
263
- * session is minted ({@link TaskRegistry.bindBackgroundAgentSession}). */
274
+ * session is minted ({@link TaskRegistry.bindBackgroundAgentSession}) and removed — together with the
275
+ * durable record's copy — by the successful release of that session
276
+ * ({@link TaskRegistry.releaseDurableTranscriptAnchor}). Read through `childSessionAnchorOf` only. */
264
277
  sessionId?: string;
265
278
  /** design/151 S1a — the durable write lane (present iff the registration wired a store). */
266
279
  durable?: DurableAgentLane;
@@ -437,7 +450,17 @@ export interface MonitorTaskHandle extends SemaTaskHandle {
437
450
  drainFailed?: true;
438
451
  timedOut?: boolean;
439
452
  timeoutSec?: number;
453
+ mirrorFailed?: true;
440
454
  };
455
+ /** See {@link BackgroundBashTaskHandle.taskArtifacts} — the same seat, for the watch's retained output. */
456
+ taskArtifacts?: TaskArtifactSeat;
457
+ /** The watch's output file (`createBackgroundOutputFile`, the bash lane's mint): every polled increment, stdout AND
458
+ * stderr, is appended to it — the full record the launch receipt and the terminal frame name, and the one place stderr
459
+ * is read from. Absent = the file could not be created. A failed append is accounted on `spool.mirrorFailed`. */
460
+ outputFile?: string;
461
+ /** The watcher tick's append to {@link outputFile} while it is in flight — a TaskStop that skips its own drain (the tick
462
+ * holds the env cursor) awaits it after the kill, so the terminal frame names a file that holds the tick's bytes. */
463
+ mirrorInFlight?: Promise<void>;
441
464
  /** Partial (newline-less) stdout tail awaiting completion — a line becomes an event only once terminated. */
442
465
  lineBuf: string;
443
466
  /** Per-batch monotonic counter → unique notification dedup keys (see task-notification.ts). */
@@ -554,6 +577,10 @@ export interface RegisterMonitorInput extends TaskAccess {
554
577
  /** design/158 S2 (RB-364 半) — the offload store a rolled-off spool middle spills to (see
555
578
  * {@link MonitorTaskHandle.toolResultStore}). Absent ⇒ legal degrade, byte-identical rolling. */
556
579
  toolResultStore?: ToolResultStore;
580
+ /** The watch's output file (see {@link MonitorTaskHandle.outputFile}); absent when it could not be created. */
581
+ outputFile?: string;
582
+ /** See {@link MonitorTaskHandle.taskArtifacts}. */
583
+ taskArtifacts?: TaskArtifactSeat;
557
584
  }
558
585
  export interface RegisterWorkflowInput extends TaskAccess {
559
586
  runId: string;
@@ -810,7 +837,15 @@ export declare function assertOwnership(input: TaskAccess, site: string): void;
810
837
  * (design/136 §2.3 S-1 定谳 posture, now positive-match on every arm). Exported: the run-workflow
811
838
  * tool's resume-ownership recheck and a deployment's serving layer apply the SAME predicate. */
812
839
  export declare function canAccessWorkflowRun(run: Pick<WorkflowRun, "scope" | "sourceTaskId" | "originatingSessionId">, access: TaskAccess): boolean;
813
- export declare function formatWorkflowRun(run: WorkflowRun): UnifiedTaskResult;
840
+ /** How much of a run {@link formatWorkflowRun} keeps: the poll reply is display-bounded; the stored record (read back by
841
+ * `ReadToolResult`, which pages) keeps every agent row and every finished agent's output. One projection, two bounds. */
842
+ export interface WorkflowRecordBounds {
843
+ readonly rows: number;
844
+ readonly partialResults: number;
845
+ }
846
+ /** The stored record's bounds: none. */
847
+ export declare const WORKFLOW_RECORD_WHOLE: WorkflowRecordBounds;
848
+ export declare function formatWorkflowRun(run: WorkflowRun, bounds?: WorkflowRecordBounds): UnifiedTaskResult;
814
849
  /** design/157 B13 一期定稿(二期细察补充 §「私有成员解法」)——the kernel-面 seam the MON/WF lane free
815
850
  * functions call through instead of `this`: exactly the 5 members `startMonitorWatcher`/`stopMonitor`/
816
851
  * `registerMonitor`/`registerWorkflow` actually reach into (`this.*` 耦合 grep 逐方法统计,见 B13 档).
@@ -4,6 +4,18 @@ import { delimitUntrusted } from "./untrusted-text.js";
4
4
  import { boundedRedactedSummary } from "./untrusted-egress.js";
5
5
  import { clipWithFilePointer, OUTPUT_BUDGET_MIN_CHARS } from "./tool-errors.js";
6
6
  import { resolveEnvBudget } from "./env-budget.js";
7
+ export function taskReadHandleText(h) {
8
+ const file = namedHandle(h.outputFile);
9
+ if (file !== undefined)
10
+ return `output: Read ${file}`;
11
+ const ref = namedHandle(h.artifactRef);
12
+ if (ref !== undefined)
13
+ return `result: ReadToolResult (ref "${ref}")`;
14
+ return undefined;
15
+ }
16
+ function namedHandle(value) {
17
+ return value !== undefined && value.trim() !== "" ? value : undefined;
18
+ }
7
19
  export function mintCompletionId(target) {
8
20
  if (target.completionId === undefined)
9
21
  target.completionId = uuidv7();
@@ -137,7 +149,7 @@ export function firstDropNote(spool) {
137
149
  return note;
138
150
  }
139
151
  export function alreadyTerminalStopNote(id, status) {
140
- return `${id} already ${status} — nothing to stop; poll TaskOutput for its final state.`;
152
+ return `${id} already ${status} — nothing to stop; its completion notification carries its final state.`;
141
153
  }
142
154
  export function assertOwnership(input, site) {
143
155
  if (input.owner === undefined || input.scope === undefined) {
@@ -155,6 +167,8 @@ export function canAccessWorkflowRun(run, access) {
155
167
  }
156
168
  const WORKFLOW_PARTIAL_RESULTS_MAX = 5;
157
169
  const WORKFLOW_AGENT_ROWS_MAX = 60;
170
+ const WORKFLOW_POLL_BOUNDS = Object.freeze({ rows: WORKFLOW_AGENT_ROWS_MAX, partialResults: WORKFLOW_PARTIAL_RESULTS_MAX });
171
+ export const WORKFLOW_RECORD_WHOLE = Object.freeze({ rows: Number.POSITIVE_INFINITY, partialResults: Number.POSITIVE_INFINITY });
158
172
  function workflowAgentRow(a, ordinal) {
159
173
  return {
160
174
  ordinal,
@@ -195,16 +209,16 @@ function timeoutInterruptionNote(interruption) {
195
209
  ` Raising the timeout only helps if that approval gets answered.`
196
210
  : ""));
197
211
  }
198
- export function formatWorkflowRun(run) {
212
+ export function formatWorkflowRun(run, bounds = WORKFLOW_POLL_BOUNDS) {
199
213
  const summary = summarizeWorkflowRun(run);
200
214
  const done = run.agents.filter((a) => a.status === "completed" || a.status === "failed").length;
201
215
  const failed = run.agents.filter((a) => a.status === "failed").length;
202
216
  const allRows = run.agents.map((a, i) => ({ a, i }));
203
- const overCap = allRows.length > WORKFLOW_AGENT_ROWS_MAX;
217
+ const overCap = allRows.length > bounds.rows;
204
218
  const keptRows = overCap
205
219
  ? (() => {
206
220
  const urgent = allRows.filter((r) => r.a.status !== "completed");
207
- const budget = Math.max(0, WORKFLOW_AGENT_ROWS_MAX - urgent.length);
221
+ const budget = Math.max(0, bounds.rows - urgent.length);
208
222
  const fill = allRows.filter((r) => r.a.status === "completed").slice(0, budget);
209
223
  return [...urgent, ...fill].sort((x, y) => x.i - y.i);
210
224
  })()
@@ -245,12 +259,12 @@ export function formatWorkflowRun(run) {
245
259
  : {}),
246
260
  ...(finishedAgents.length > 0
247
261
  ? {
248
- partial_results: finishedAgents.slice(0, WORKFLOW_PARTIAL_RESULTS_MAX).map((a) => ({
262
+ partial_results: finishedAgents.slice(0, bounds.partialResults).map((a) => ({
249
263
  agent: a.label,
250
264
  output: delimitUntrusted(`workflow agent ${a.label} output`, a.output),
251
265
  })),
252
- ...(finishedAgents.length > WORKFLOW_PARTIAL_RESULTS_MAX
253
- ? { partial_results_note: `showing ${WORKFLOW_PARTIAL_RESULTS_MAX} of ${finishedAgents.length} completed agent outputs; the full set remains retrievable from the workflow run record (getWorkflowRun / the workflow journal).` }
266
+ ...(finishedAgents.length > bounds.partialResults
267
+ ? { partial_results_note: `showing ${bounds.partialResults} of ${finishedAgents.length} completed agent outputs; the full set remains retrievable from the workflow run record (getWorkflowRun / the workflow journal).` }
254
268
  : {}),
255
269
  }
256
270
  : {}),
@@ -122,7 +122,7 @@ export async function stopWorkflowLane(handle) {
122
122
  type: "workflow",
123
123
  status: handle.status,
124
124
  stopped: false,
125
- note: `workflow already ${handle.status} — nothing to stop; poll TaskOutput for its final state.`,
125
+ note: `workflow already ${handle.status} — nothing to stop; its completion notification carries its final state.`,
126
126
  }),
127
127
  details: { task_id: handle.id, type: "workflow", status: handle.status, retrieval_status: "success" },
128
128
  };