@sema-agent/core 7.60.0 → 7.62.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 (560) hide show
  1. package/CHANGELOG.md +917 -0
  2. package/README.md +2 -2
  3. package/dist/agents/agent-transcript-tool.d.ts +2 -2
  4. package/dist/agents/agent-transcript-tool.js +1 -1
  5. package/dist/agents/cascade.d.ts +71 -12
  6. package/dist/agents/cascade.js +61 -21
  7. package/dist/agents/composition-allowance.d.ts +53 -0
  8. package/dist/agents/composition-allowance.js +49 -0
  9. package/dist/agents/composition-placement.d.ts +29 -0
  10. package/dist/agents/composition-placement.js +24 -0
  11. package/dist/agents/cumulative-stats.d.ts +4 -0
  12. package/dist/agents/cumulative-stats.js +3 -0
  13. package/dist/agents/inherited-tool-pool.d.ts +5 -3
  14. package/dist/agents/inherited-tool-pool.js +2 -2
  15. package/dist/agents/list-agents-tool.d.ts +1 -1
  16. package/dist/agents/peer-held-queue.d.ts +27 -4
  17. package/dist/agents/peer-held-queue.js +81 -36
  18. package/dist/agents/peer-notice-route.d.ts +1 -1
  19. package/dist/agents/peer-notice-route.js +4 -3
  20. package/dist/agents/peer-notices.d.ts +4 -4
  21. package/dist/agents/peer-notices.js +8 -4
  22. package/dist/agents/peer-session-drain.d.ts +8 -1
  23. package/dist/agents/peer-session-drain.js +49 -10
  24. package/dist/agents/repair-loop.js +16 -6
  25. package/dist/agents/retain-ledger.js +3 -1
  26. package/dist/agents/roster-store.d.ts +1 -1
  27. package/dist/agents/roster-store.js +7 -4
  28. package/dist/agents/send-message-tool.d.ts +8 -10
  29. package/dist/agents/send-message-tool.js +43 -23
  30. package/dist/agents/subagent-completion-gate.d.ts +35 -0
  31. package/dist/agents/subagent-completion-gate.js +62 -0
  32. package/dist/agents/subagent-steps.d.ts +7 -6
  33. package/dist/agents/subagent.d.ts +36 -41
  34. package/dist/agents/subagent.js +245 -200
  35. package/dist/agents/suspend-guard.d.ts +47 -16
  36. package/dist/agents/suspend-guard.js +13 -4
  37. package/dist/agents/verify.d.ts +41 -14
  38. package/dist/agents/verify.js +41 -30
  39. package/dist/brain/anthropic.js +1 -0
  40. package/dist/brain/errors.d.ts +7 -1
  41. package/dist/brain/errors.js +6 -0
  42. package/dist/brain/failover.js +2 -1
  43. package/dist/brain/open-responses.js +1 -0
  44. package/dist/brain/openai.js +1 -0
  45. package/dist/brain/provider-dialect.d.ts +10 -0
  46. package/dist/brain/provider-dialect.js +13 -2
  47. package/dist/brain/stream-engine.d.ts +3 -0
  48. package/dist/brain/stream-engine.js +4 -0
  49. package/dist/core/agent-state.d.ts +1 -1
  50. package/dist/core/allow-entry.d.ts +59 -23
  51. package/dist/core/allow-entry.js +131 -38
  52. package/dist/core/ask-origin.d.ts +79 -0
  53. package/dist/core/ask-origin.js +76 -0
  54. package/dist/core/ask-question.d.ts +19 -13
  55. package/dist/core/ask-question.js +8 -2
  56. package/dist/core/auto-compaction.d.ts +2 -0
  57. package/dist/core/auto-compaction.js +2 -1
  58. package/dist/core/auto-mode.js +3 -5
  59. package/dist/core/background-agent-store.d.ts +7 -5
  60. package/dist/core/background-agent-store.js +12 -11
  61. package/dist/core/checkpoint-features.d.ts +722 -0
  62. package/dist/core/checkpoint-features.js +98 -0
  63. package/dist/core/checkpoint-requirements.d.ts +33 -5
  64. package/dist/core/checkpoint-requirements.js +18 -5
  65. package/dist/core/checkpoint-row-verdict.d.ts +99 -0
  66. package/dist/core/checkpoint-row-verdict.js +225 -0
  67. package/dist/core/checkpoint-store.d.ts +107 -738
  68. package/dist/core/checkpoint-store.js +45 -143
  69. package/dist/core/child-clamp-seats.d.ts +3 -2
  70. package/dist/core/child-clamp-seats.js +4 -3
  71. package/dist/core/closest-name.d.ts +13 -0
  72. package/dist/core/closest-name.js +35 -0
  73. package/dist/core/context-settings.js +3 -5
  74. package/dist/core/cross-boundary-taint.d.ts +1 -1
  75. package/dist/core/decision-receipt.d.ts +14 -1
  76. package/dist/core/decision-receipt.js +6 -3
  77. package/dist/core/delegation-frames.d.ts +13 -9
  78. package/dist/core/effective-path-target.js +2 -3
  79. package/dist/core/engine-attestation.d.ts +11 -1
  80. package/dist/core/engine-attestation.js +2 -0
  81. package/dist/core/engine-notice.d.ts +68 -21
  82. package/dist/core/engine-notice.js +9 -2
  83. package/dist/core/file-history-retention.d.ts +8 -0
  84. package/dist/core/file-history-retention.js +14 -11
  85. package/dist/core/file-history-store.d.ts +31 -1
  86. package/dist/core/file-history-store.js +31 -2
  87. package/dist/core/frame-settlement.d.ts +10 -0
  88. package/dist/core/frame-settlement.js +6 -1
  89. package/dist/core/fs-write-gate-policy.d.ts +3 -3
  90. package/dist/core/fs-write-gate-policy.js +8 -7
  91. package/dist/core/gate-fold.js +4 -3
  92. package/dist/core/gate-lanes.js +7 -4
  93. package/dist/core/gate-outcome.d.ts +40 -1
  94. package/dist/core/gate-outcome.js +10 -0
  95. package/dist/core/git-worktree-env.d.ts +7 -3
  96. package/dist/core/git-worktree-env.js +16 -13
  97. package/dist/core/governance-codes.d.ts +14 -4
  98. package/dist/core/governance-codes.js +19 -4
  99. package/dist/core/hooks.d.ts +25 -4
  100. package/dist/core/hooks.js +11 -4
  101. package/dist/core/host-floor.js +3 -5
  102. package/dist/core/human-input-projection.d.ts +1 -0
  103. package/dist/core/human-input-projection.js +3 -0
  104. package/dist/core/image-admission.d.ts +47 -7
  105. package/dist/core/image-admission.js +35 -4
  106. package/dist/core/input-author.d.ts +36 -0
  107. package/dist/core/input-author.js +39 -0
  108. package/dist/core/leg-identity.d.ts +62 -0
  109. package/dist/core/leg-identity.js +18 -0
  110. package/dist/core/locked-config.d.ts +4 -3
  111. package/dist/core/locked-config.js +5 -3
  112. package/dist/core/lsp.d.ts +5 -3
  113. package/dist/core/lsp.js +3 -2
  114. package/dist/core/mailbox-store.d.ts +85 -10
  115. package/dist/core/mailbox-store.js +31 -10
  116. package/dist/core/mcp-connection-pool.d.ts +6 -20
  117. package/dist/core/mcp-connection-pool.js +10 -28
  118. package/dist/core/mcp-failure.d.ts +76 -15
  119. package/dist/core/mcp-failure.js +60 -33
  120. package/dist/core/mcp-host-seat.d.ts +92 -53
  121. package/dist/core/mcp-host-seat.js +225 -46
  122. package/dist/core/mcp-probe.js +2 -2
  123. package/dist/core/mcp-server-link.d.ts +18 -6
  124. package/dist/core/mcp-server-link.js +19 -4
  125. package/dist/core/mcp-server-spec.d.ts +2 -1
  126. package/dist/core/mcp-session-end.d.ts +1 -2
  127. package/dist/core/mcp-session-end.js +1 -1
  128. package/dist/core/mcp.d.ts +6 -49
  129. package/dist/core/mcp.js +115 -111
  130. package/dist/core/media-byte-cap.d.ts +21 -46
  131. package/dist/core/media-byte-cap.js +55 -55
  132. package/dist/core/member-group.d.ts +7 -0
  133. package/dist/core/member-group.js +35 -0
  134. package/dist/core/memory-engine/consolidation-driver.d.ts +1 -1
  135. package/dist/core/memory-engine/consolidation.d.ts +1 -1
  136. package/dist/core/memory-engine/consolidation.js +7 -1
  137. package/dist/core/memory-engine/dual-root.d.ts +31 -0
  138. package/dist/core/memory-engine/dual-root.js +59 -11
  139. package/dist/core/memory-engine/engine.js +27 -24
  140. package/dist/core/memory-engine/file-backend.d.ts +13 -0
  141. package/dist/core/memory-engine/file-backend.js +35 -15
  142. package/dist/core/memory-engine/layout.d.ts +3 -0
  143. package/dist/core/memory-engine/layout.js +13 -3
  144. package/dist/core/memory-engine/memory-deployment.d.ts +110 -0
  145. package/dist/core/memory-engine/memory-deployment.js +182 -0
  146. package/dist/core/memory-engine/sync-client.d.ts +39 -18
  147. package/dist/core/memory-engine/sync-client.js +72 -14
  148. package/dist/core/memory-engine/sync-report.d.ts +7 -4
  149. package/dist/core/memory-engine/sync.d.ts +9 -1
  150. package/dist/core/memory-vector.d.ts +1 -1
  151. package/dist/core/memory.d.ts +10 -10
  152. package/dist/core/mode-policy.d.ts +8 -8
  153. package/dist/core/mode-policy.js +8 -6
  154. package/dist/core/mods/agent-stations.d.ts +39 -4
  155. package/dist/core/mods/agent-stations.js +59 -10
  156. package/dist/core/mods/classic-events.d.ts +9 -1
  157. package/dist/core/mods/dollar.d.ts +94 -1
  158. package/dist/core/mods/dollar.js +13 -1
  159. package/dist/core/mods/extension-call.d.ts +15 -1
  160. package/dist/core/mods/extension-call.js +7 -2
  161. package/dist/core/mods/kernel/dispatch.d.ts +4 -3
  162. package/dist/core/mods/kernel/dispatch.js +4 -4
  163. package/dist/core/mods/kernel/events.d.ts +14 -3
  164. package/dist/core/mods/kernel/events.js +18 -15
  165. package/dist/core/mods/kernel/registration.d.ts +3 -0
  166. package/dist/core/mods/kernel/registration.js +5 -0
  167. package/dist/core/mods/kernel/site-rules.d.ts +6 -3
  168. package/dist/core/mods/kernel/site-rules.js +10 -2
  169. package/dist/core/mods/lifecycle-stations.d.ts +36 -4
  170. package/dist/core/mods/lifecycle-stations.js +44 -9
  171. package/dist/core/mods/session-append.d.ts +118 -0
  172. package/dist/core/mods/session-append.js +318 -0
  173. package/dist/core/mods/session-compact.d.ts +48 -0
  174. package/dist/core/mods/session-compact.js +194 -0
  175. package/dist/core/mods/session-receive.d.ts +93 -0
  176. package/dist/core/mods/session-receive.js +138 -0
  177. package/dist/core/mods/session-send.d.ts +72 -0
  178. package/dist/core/mods/session-send.js +88 -0
  179. package/dist/core/mods/stations.d.ts +88 -21
  180. package/dist/core/mods/stations.js +149 -11
  181. package/dist/core/mods/tool-call.d.ts +2 -0
  182. package/dist/core/mods/tool-call.js +4 -4
  183. package/dist/core/output-style.js +3 -4
  184. package/dist/core/own-property-receipt.d.ts +68 -2
  185. package/dist/core/own-property-receipt.js +45 -2
  186. package/dist/core/park-selfcheck.js +4 -2
  187. package/dist/core/path-identity.d.ts +11 -0
  188. package/dist/core/path-identity.js +4 -0
  189. package/dist/core/path-rule-binding.d.ts +3 -1
  190. package/dist/core/path-rule-binding.js +3 -1
  191. package/dist/core/peer-seat.d.ts +3 -3
  192. package/dist/core/peer-seat.js +20 -8
  193. package/dist/core/permission-rule-consent.d.ts +21 -5
  194. package/dist/core/permission-rule-consent.js +21 -1
  195. package/dist/core/permission-rule-model.d.ts +34 -11
  196. package/dist/core/permission-rule-model.js +47 -10
  197. package/dist/core/permission-rule-org.d.ts +1 -1
  198. package/dist/core/permission-rule-provider.js +4 -1
  199. package/dist/core/permission-rules.d.ts +4 -0
  200. package/dist/core/permission-rules.js +11 -16
  201. package/dist/core/read-root-candidate.js +1 -1
  202. package/dist/core/remote-env.d.ts +74 -26
  203. package/dist/core/remote-env.js +20 -0
  204. package/dist/core/resume-startup-cause.d.ts +5 -4
  205. package/dist/core/retention-policy.d.ts +24 -23
  206. package/dist/core/retention-policy.js +36 -2
  207. package/dist/core/retention.d.ts +4 -1
  208. package/dist/core/retired-keys.d.ts +4 -4
  209. package/dist/core/row-admission.d.ts +10 -0
  210. package/dist/core/row-admission.js +5 -0
  211. package/dist/core/runner/advisor-instructions.d.ts +2 -1
  212. package/dist/core/runner/advisor-instructions.js +2 -1
  213. package/dist/core/runner/announce-once-ledger.d.ts +4 -4
  214. package/dist/core/runner/assemble-result.d.ts +13 -3
  215. package/dist/core/runner/assemble-result.js +12 -7
  216. package/dist/core/runner/caller-roster.d.ts +12 -9
  217. package/dist/core/runner/caller-roster.js +5 -2
  218. package/dist/core/runner/checkpoint-scope.d.ts +16 -1
  219. package/dist/core/runner/checkpoint-scope.js +21 -0
  220. package/dist/core/runner/compact-session.js +18 -3
  221. package/dist/core/runner/compaction-call-options.d.ts +1 -1
  222. package/dist/core/runner/compaction-restate.d.ts +2 -2
  223. package/dist/core/runner/compaction-restate.js +4 -3
  224. package/dist/core/runner/construction-doors.d.ts +2 -2
  225. package/dist/core/runner/construction-doors.js +2 -2
  226. package/dist/core/runner/contracts.d.ts +116 -34
  227. package/dist/core/runner/cross-boundary-lane.d.ts +1 -1
  228. package/dist/core/runner/decide-continuation.d.ts +4 -2
  229. package/dist/core/runner/decide-continuation.js +7 -4
  230. package/dist/core/runner/delegation-owner.d.ts +43 -0
  231. package/dist/core/runner/delegation-owner.js +59 -0
  232. package/dist/core/runner/denial-limit-arms.d.ts +15 -21
  233. package/dist/core/runner/denial-limit-arms.js +17 -10
  234. package/dist/core/runner/expire-settle.d.ts +44 -0
  235. package/dist/core/runner/expire-settle.js +55 -0
  236. package/dist/core/runner/git-status-frame.d.ts +3 -3
  237. package/dist/core/runner/git-status-frame.js +2 -1
  238. package/dist/core/runner/halt-attribution.d.ts +2 -1
  239. package/dist/core/runner/halt-attribution.js +2 -1
  240. package/dist/core/runner/lineage-reroot-view.d.ts +56 -0
  241. package/dist/core/runner/lineage-reroot-view.js +108 -0
  242. package/dist/core/runner/local-claims.d.ts +17 -0
  243. package/dist/core/runner/local-claims.js +18 -0
  244. package/dist/core/runner/media-removed-seat.d.ts +46 -0
  245. package/dist/core/runner/media-removed-seat.js +88 -0
  246. package/dist/core/runner/park-commit.d.ts +2 -2
  247. package/dist/core/runner/permission-rule-lanes.d.ts +7 -2
  248. package/dist/core/runner/permission-rule-lanes.js +28 -9
  249. package/dist/core/runner/person-path-rows.d.ts +15 -0
  250. package/dist/core/runner/person-path-rows.js +27 -4
  251. package/dist/core/runner/placement-fence.d.ts +26 -0
  252. package/dist/core/runner/placement-fence.js +38 -0
  253. package/dist/core/runner/prepare-acquire-reconcile.d.ts +4 -1
  254. package/dist/core/runner/prepare-acquire-reconcile.js +7 -2
  255. package/dist/core/runner/prepare-ask-lane.d.ts +6 -12
  256. package/dist/core/runner/prepare-ask-lane.js +4 -4
  257. package/dist/core/runner/prepare-boundary-parks.d.ts +4 -1
  258. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  259. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -0
  260. package/dist/core/runner/prepare-caps-and-workflow.js +2 -1
  261. package/dist/core/runner/prepare-config-doors.d.ts +6 -6
  262. package/dist/core/runner/prepare-config-doors.js +19 -21
  263. package/dist/core/runner/prepare-context-lane.d.ts +6 -2
  264. package/dist/core/runner/prepare-context-lane.js +13 -13
  265. package/dist/core/runner/prepare-delegation-surface.d.ts +9 -9
  266. package/dist/core/runner/prepare-delegation-surface.js +4 -5
  267. package/dist/core/runner/prepare-execution-env.d.ts +5 -2
  268. package/dist/core/runner/prepare-execution-env.js +7 -4
  269. package/dist/core/runner/prepare-gate-stations.d.ts +19 -14
  270. package/dist/core/runner/prepare-gate-stations.js +6 -4
  271. package/dist/core/runner/prepare-hands-readface.d.ts +6 -6
  272. package/dist/core/runner/prepare-hands-readface.js +32 -11
  273. package/dist/core/runner/prepare-inherited-gate.d.ts +8 -0
  274. package/dist/core/runner/prepare-inherited-gate.js +10 -3
  275. package/dist/core/runner/prepare-lsp.d.ts +3 -0
  276. package/dist/core/runner/prepare-lsp.js +2 -2
  277. package/dist/core/runner/prepare-park-ask.d.ts +5 -2
  278. package/dist/core/runner/prepare-park-ask.js +4 -5
  279. package/dist/core/runner/prepare-policy-chain.d.ts +10 -21
  280. package/dist/core/runner/prepare-policy-chain.js +16 -25
  281. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  282. package/dist/core/runner/prepare-prompt-inputs.d.ts +5 -4
  283. package/dist/core/runner/prepare-prompt-inputs.js +3 -2
  284. package/dist/core/runner/prepare-question-face.d.ts +6 -4
  285. package/dist/core/runner/prepare-question-face.js +2 -2
  286. package/dist/core/runner/prepare-run-refs.d.ts +3 -0
  287. package/dist/core/runner/prepare-run-refs.js +2 -2
  288. package/dist/core/runner/prepare-suspend-saga.d.ts +11 -7
  289. package/dist/core/runner/prepare-suspend-saga.js +17 -7
  290. package/dist/core/runner/prepare-task.d.ts +1 -1
  291. package/dist/core/runner/prepare-task.js +61 -30
  292. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +6 -0
  293. package/dist/core/runner/prepare-tool-disclosure-mount.js +3 -1
  294. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -0
  295. package/dist/core/runner/prepare-wiring-manifest.js +2 -1
  296. package/dist/core/runner/prepare-workspace-restore.d.ts +5 -0
  297. package/dist/core/runner/prepare-workspace-restore.js +10 -6
  298. package/dist/core/runner/read-root-grant.d.ts +1 -1
  299. package/dist/core/runner/read-root-grant.js +2 -1
  300. package/dist/core/runner/resume-admission.d.ts +8 -6
  301. package/dist/core/runner/resume-admission.js +23 -6
  302. package/dist/core/runner/resume-apply.d.ts +4 -0
  303. package/dist/core/runner/resume-apply.js +14 -5
  304. package/dist/core/runner/resume-checkpoint-screen.d.ts +9 -0
  305. package/dist/core/runner/resume-checkpoint-screen.js +4 -84
  306. package/dist/core/runner/resume-claim.d.ts +8 -3
  307. package/dist/core/runner/resume-claim.js +28 -12
  308. package/dist/core/runner/resume-internals-and-config.d.ts +2 -2
  309. package/dist/core/runner/resume-internals-and-config.js +10 -1
  310. package/dist/core/runner/resume-preflight.d.ts +3 -2
  311. package/dist/core/runner/resume-preflight.js +13 -26
  312. package/dist/core/runner/retired-runner-deps.js +2 -0
  313. package/dist/core/runner/run-git-lane.d.ts +2 -0
  314. package/dist/core/runner/run-git-lane.js +6 -2
  315. package/dist/core/runner/run-harness-handlers.d.ts +2 -0
  316. package/dist/core/runner/run-harness-handlers.js +5 -4
  317. package/dist/core/runner/run-identity-wiring.d.ts +2 -2
  318. package/dist/core/runner/run-identity-wiring.js +14 -5
  319. package/dist/core/runner/run-leg.d.ts +3 -3
  320. package/dist/core/runner/run-leg.js +64 -36
  321. package/dist/core/runner/run-notification-lane.js +20 -2
  322. package/dist/core/runner/run-recovery-lanes.js +3 -2
  323. package/dist/core/runner/run-settle-and-teardown.js +12 -9
  324. package/dist/core/runner/run-stop-and-final-verify.js +2 -1
  325. package/dist/core/runner/run-telemetry-and-budget-seats.d.ts +1 -1
  326. package/dist/core/runner/run-terminal-adoption.d.ts +1 -1
  327. package/dist/core/runner/run-terminal-adoption.js +26 -17
  328. package/dist/core/runner/run-turn-boundary.js +34 -18
  329. package/dist/core/runner/runtask.d.ts +18 -3
  330. package/dist/core/runner/runtask.js +33 -17
  331. package/dist/core/runner/session-rule-policy.d.ts +1 -1
  332. package/dist/core/runner/session-rule-policy.js +6 -1
  333. package/dist/core/runner/shell-env-withheld.d.ts +1 -1
  334. package/dist/core/runner/steering-preview.d.ts +9 -0
  335. package/dist/core/runner/steering-preview.js +5 -0
  336. package/dist/core/runner/stream-halt-verbs.d.ts +1 -14
  337. package/dist/core/runner/stream-halt-verbs.js +4 -3
  338. package/dist/core/runner/stream-reap.d.ts +7 -6
  339. package/dist/core/runner/stream-reap.js +13 -16
  340. package/dist/core/runner/stream-settle-backstop.d.ts +3 -2
  341. package/dist/core/runner/stream-settle-backstop.js +5 -3
  342. package/dist/core/runner/stream-steer-verb.d.ts +5 -2
  343. package/dist/core/runner/stream-steer-verb.js +16 -7
  344. package/dist/core/runner/terminal-account.d.ts +11 -1
  345. package/dist/core/runner/terminal-account.js +20 -0
  346. package/dist/core/runner/terminal-projection.d.ts +8 -2
  347. package/dist/core/runner/terminal-projection.js +2 -2
  348. package/dist/core/runner/tool-disclosure.d.ts +3 -0
  349. package/dist/core/runner/tool-disclosure.js +5 -2
  350. package/dist/core/runner/tool-end-body.d.ts +3 -3
  351. package/dist/core/runner/tool-end-body.js +1 -1
  352. package/dist/core/runner/tool-face-overlay.js +2 -0
  353. package/dist/core/runner/tool-output-projection.d.ts +3 -3
  354. package/dist/core/runner/tool-output-projection.js +7 -6
  355. package/dist/core/runner/tool-table-view.d.ts +56 -0
  356. package/dist/core/runner/tool-table-view.js +51 -0
  357. package/dist/core/runner/turn-attachments.d.ts +8 -2
  358. package/dist/core/runner/turn-attachments.js +2 -2
  359. package/dist/core/runner/void-verifier-pause.d.ts +33 -0
  360. package/dist/core/runner/void-verifier-pause.js +41 -0
  361. package/dist/core/runner-deps.d.ts +26 -27
  362. package/dist/core/secret-env.d.ts +19 -16
  363. package/dist/core/secret-env.js +45 -27
  364. package/dist/core/session-log-transfer.js +9 -10
  365. package/dist/core/session-policy-store.d.ts +1 -1
  366. package/dist/core/session-policy-store.js +5 -2
  367. package/dist/core/session-reconcile.d.ts +3 -2
  368. package/dist/core/session-reconcile.js +7 -4
  369. package/dist/core/session-store.d.ts +3 -1
  370. package/dist/core/session-store.js +10 -8
  371. package/dist/core/session.d.ts +16 -5
  372. package/dist/core/shell-confinement.d.ts +37 -0
  373. package/dist/core/shell-confinement.js +56 -0
  374. package/dist/core/skill-grant.js +1 -1
  375. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +8 -2
  376. package/dist/core/store-contracts/checkpoint-store-contract.js +83 -2
  377. package/dist/core/store-contracts/file-history-store-contract.d.ts +5 -2
  378. package/dist/core/store-contracts/file-history-store-contract.js +25 -1
  379. package/dist/core/store-contracts/mailbox-store-contract.d.ts +12 -5
  380. package/dist/core/store-contracts/mailbox-store-contract.js +156 -9
  381. package/dist/core/store-contracts/session-store-contract.js +22 -8
  382. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  383. package/dist/core/store-contracts/tool-result-store-contract.js +30 -0
  384. package/dist/core/task-event.d.ts +24 -9
  385. package/dist/core/task-limits.d.ts +5 -0
  386. package/dist/core/task-notification.d.ts +89 -12
  387. package/dist/core/task-notification.js +89 -14
  388. package/dist/core/task-registry-agent.d.ts +32 -50
  389. package/dist/core/task-registry-agent.js +36 -56
  390. package/dist/core/task-registry-monitor.d.ts +1 -1
  391. package/dist/core/task-registry-monitor.js +15 -60
  392. package/dist/core/task-registry-shared.d.ts +22 -112
  393. package/dist/core/task-registry-shared.js +3 -41
  394. package/dist/core/task-registry-workflow.js +5 -21
  395. package/dist/core/task-registry.d.ts +32 -62
  396. package/dist/core/task-registry.js +30 -110
  397. package/dist/core/task-result.d.ts +29 -12
  398. package/dist/core/task-spec-members.d.ts +39 -0
  399. package/dist/core/task-spec-members.js +92 -0
  400. package/dist/core/task-spec.d.ts +11 -11
  401. package/dist/core/task-tool-shape.d.ts +7 -57
  402. package/dist/core/task-tool-shape.js +7 -66
  403. package/dist/core/terminal-cause.d.ts +36 -6
  404. package/dist/core/terminal-cause.js +1 -0
  405. package/dist/core/tool-catalog-entries.js +2 -5
  406. package/dist/core/tool-check-reading.js +16 -10
  407. package/dist/core/tool-conformance.js +1 -2
  408. package/dist/core/tool-errors.d.ts +6 -3
  409. package/dist/core/tool-errors.js +2 -0
  410. package/dist/core/tool-face-reader.js +3 -2
  411. package/dist/core/tool-face.d.ts +8 -5
  412. package/dist/core/tool-face.js +1 -1
  413. package/dist/core/tool-name-aliases.d.ts +5 -29
  414. package/dist/core/tool-name-aliases.js +9 -5
  415. package/dist/core/tool-name-readings.d.ts +14 -3
  416. package/dist/core/tool-name-readings.js +2 -0
  417. package/dist/core/tool-policy.d.ts +109 -18
  418. package/dist/core/tool-policy.js +84 -14
  419. package/dist/core/tool-result-store.d.ts +23 -0
  420. package/dist/core/tool-result-store.js +3 -2
  421. package/dist/core/tool-roster.d.ts +4 -4
  422. package/dist/core/tool-spec.d.ts +23 -6
  423. package/dist/core/trace.d.ts +18 -1
  424. package/dist/core/types.d.ts +1 -1
  425. package/dist/core/types.js +1 -1
  426. package/dist/core/user-attachment.js +26 -21
  427. package/dist/core/workflow-journal-store.d.ts +1 -1
  428. package/dist/core/workflow-run-store.d.ts +2 -0
  429. package/dist/core/workflow-run-store.js +6 -5
  430. package/dist/core/workflow-settled-run.d.ts +5 -0
  431. package/dist/core/workflow-settled-run.js +7 -0
  432. package/dist/engine/execution-env/node-execution-env.d.ts +37 -9
  433. package/dist/engine/execution-env/node-execution-env.js +221 -22
  434. package/dist/engine/harness/agent-harness.d.ts +65 -18
  435. package/dist/engine/harness/agent-harness.js +90 -23
  436. package/dist/engine/harness/messages.d.ts +4 -3
  437. package/dist/engine/harness/messages.js +2 -2
  438. package/dist/engine/harness/types.d.ts +52 -7
  439. package/dist/engine/llm/media-removed.d.ts +14 -0
  440. package/dist/engine/llm/media-removed.js +9 -0
  441. package/dist/engine/llm/rejected-images.d.ts +35 -25
  442. package/dist/engine/llm/rejected-images.js +59 -10
  443. package/dist/engine/llm/types.d.ts +24 -3
  444. package/dist/engine/llm/types.js +7 -3
  445. package/dist/engine/loop/agent-loop.d.ts +6 -1
  446. package/dist/engine/loop/agent-loop.js +20 -11
  447. package/dist/engine/loop/types.d.ts +12 -3
  448. package/dist/engine/session/import-validate.js +7 -0
  449. package/dist/engine/session/parent-chain-guard.d.ts +3 -3
  450. package/dist/engine/session/parent-chain-guard.js +1 -1
  451. package/dist/engine/session/path-to-root.d.ts +18 -3
  452. package/dist/engine/session/path-to-root.js +15 -1
  453. package/dist/engine/session/repo-utils.d.ts +12 -1
  454. package/dist/engine/session/repo-utils.js +41 -0
  455. package/dist/engine/session/session.js +1 -1
  456. package/dist/engine/session/storage-base.d.ts +20 -0
  457. package/dist/engine/session/storage-base.js +28 -9
  458. package/dist/fixtures/index.d.ts +7 -5
  459. package/dist/fixtures/index.js +5 -3
  460. package/dist/index.d.ts +29 -18
  461. package/dist/index.js +19 -11
  462. package/dist/internal/harness-types.d.ts +2 -0
  463. package/dist/internal/harness.d.ts +4 -3
  464. package/dist/internal/harness.js +3 -2
  465. package/dist/internal/llm.d.ts +2 -1
  466. package/dist/internal/llm.js +1 -0
  467. package/dist/orchestration/goal.d.ts +6 -2
  468. package/dist/orchestration/goal.js +6 -3
  469. package/dist/orchestration/run-workflow-tool.d.ts +14 -17
  470. package/dist/orchestration/run-workflow-tool.js +43 -50
  471. package/dist/orchestration/workflow-types.d.ts +2 -2
  472. package/dist/orchestration/workflow.d.ts +7 -0
  473. package/dist/orchestration/workflow.js +10 -12
  474. package/dist/stores/file/background-agent-store.js +18 -15
  475. package/dist/stores/file/checkpoint-store.d.ts +2 -0
  476. package/dist/stores/file/checkpoint-store.js +13 -9
  477. package/dist/stores/file/file-history-store.js +3 -2
  478. package/dist/stores/file/fs-atomic.d.ts +0 -22
  479. package/dist/stores/file/fs-atomic.js +0 -17
  480. package/dist/stores/file/index.d.ts +7 -12
  481. package/dist/stores/file/index.js +25 -12
  482. package/dist/stores/file/ledger-tuning.d.ts +23 -0
  483. package/dist/stores/file/ledger-tuning.js +21 -0
  484. package/dist/stores/file/mailbox-store.js +42 -22
  485. package/dist/stores/file/memory-store.js +3 -2
  486. package/dist/stores/file/permission-rule-adopt.js +24 -21
  487. package/dist/stores/file/permission-rule-store.js +6 -3
  488. package/dist/stores/file/session-policy-store.js +3 -2
  489. package/dist/stores/file/session-store.d.ts +26 -7
  490. package/dist/stores/file/session-store.js +59 -35
  491. package/dist/stores/file/tool-result-store.d.ts +11 -0
  492. package/dist/stores/file/tool-result-store.js +57 -3
  493. package/dist/stores/file/usage-window-store.js +3 -2
  494. package/dist/stores/file/workflow-journal-store.d.ts +0 -2
  495. package/dist/stores/file/workflow-journal-store.js +3 -18
  496. package/dist/stores/file/workflow-run-store.d.ts +1 -1
  497. package/dist/stores/file/workflow-run-store.js +15 -10
  498. package/dist/tools/fs/bash-program-position.d.ts +3 -2
  499. package/dist/tools/fs/bash-program-position.js +7 -7
  500. package/dist/tools/fs/dead-cwd.d.ts +5 -5
  501. package/dist/tools/fs/dead-cwd.js +4 -11
  502. package/dist/tools/fs/fs-bash-background-text.d.ts +6 -0
  503. package/dist/tools/fs/fs-bash-background-text.js +6 -0
  504. package/dist/tools/fs/fs-bash.d.ts +3 -18
  505. package/dist/tools/fs/fs-bash.js +37 -124
  506. package/dist/tools/fs/fs-pdf.js +8 -6
  507. package/dist/tools/fs/fs-read.js +2 -2
  508. package/dist/tools/fs/fs-shared.d.ts +28 -3
  509. package/dist/tools/fs/fs-shared.js +15 -0
  510. package/dist/tools/fs/index.d.ts +1 -1
  511. package/dist/tools/fs/index.js +4 -14
  512. package/dist/tools/fs/pdf.d.ts +4 -4
  513. package/dist/tools/fs/pdf.js +6 -6
  514. package/dist/tools/fs/read-deny-home.js +8 -1
  515. package/dist/tools/fs/read-deny.d.ts +26 -2
  516. package/dist/tools/fs/read-deny.js +9 -2
  517. package/dist/tools/fs/read-floor.d.ts +13 -5
  518. package/dist/tools/fs/read-floor.js +206 -2
  519. package/dist/tools/fs/removal-targets.js +2 -2
  520. package/dist/tools/fs/search.d.ts +3 -2
  521. package/dist/tools/fs/search.js +6 -6
  522. package/dist/tools/fs/shell-read-argv.d.ts +4 -2
  523. package/dist/tools/fs/shell-read-argv.js +14 -3
  524. package/dist/tools/fs/shell-read-bindings.d.ts +18 -2
  525. package/dist/tools/fs/shell-read-bindings.js +148 -68
  526. package/dist/tools/fs/shell-read-check.js +20 -4
  527. package/dist/tools/fs/shell-read-establish.js +25 -9
  528. package/dist/tools/fs/shell-read-functions.js +2 -2
  529. package/dist/tools/fs/shell-read-identity.d.ts +3 -1
  530. package/dist/tools/fs/shell-read-identity.js +4 -2
  531. package/dist/tools/fs/shell-read-judge.d.ts +7 -1
  532. package/dist/tools/fs/shell-read-judge.js +1 -1
  533. package/dist/tools/fs/shell-read-object-path.d.ts +59 -0
  534. package/dist/tools/fs/shell-read-object-path.js +119 -0
  535. package/dist/tools/fs/shell-read-plan.d.ts +8 -0
  536. package/dist/tools/fs/shell-read-plan.js +47 -30
  537. package/dist/tools/fs/shell-read-start.d.ts +66 -13
  538. package/dist/tools/fs/shell-read-start.js +89 -17
  539. package/dist/tools/fs/shell-read-workdir.d.ts +29 -8
  540. package/dist/tools/fs/shell-read-workdir.js +31 -8
  541. package/dist/tools/monitor.d.ts +8 -7
  542. package/dist/tools/monitor.js +12 -10
  543. package/dist/tools/worktree.d.ts +5 -1
  544. package/dist/tools/worktree.js +20 -17
  545. package/package.json +6 -3
  546. package/test/export-surface.snapshot.json +112 -42
  547. package/wire-changes/core-stores-sql@7.61.0.json +480 -0
  548. package/wire-changes/core-stores-sql@7.62.0.json +30 -0
  549. package/wire-changes/core@7.61.0.json +4405 -0
  550. package/wire-changes/core@7.62.0.json +2181 -0
  551. package/wire-changes/mods-kernel@7.61.0.json +65 -0
  552. package/wire-changes/mods-kernel@7.62.0.json +42 -0
  553. package/wire-changes/primitives@7.61.0.json +30 -0
  554. package/wire-changes/primitives@7.62.0.json +30 -0
  555. package/dist/core/consolidate-scope.d.ts +0 -93
  556. package/dist/core/consolidate-scope.js +0 -98
  557. package/dist/core/runner/image-removed-seat.d.ts +0 -12
  558. package/dist/core/runner/image-removed-seat.js +0 -19
  559. package/dist/core/runner/memory-consolidation.d.ts +0 -109
  560. package/dist/core/runner/memory-consolidation.js +0 -251
package/README.md CHANGED
@@ -51,8 +51,8 @@ const res = await runner.runTask({ objective: "...", model: "main" });
51
51
  tool lifecycle, progress, diagnostics), ready to pipe into SSE via `createTaskServer`.
52
52
  - **Security model built in.** Tool policies with allow/ask/deny semantics, per-principal
53
53
  authorization, shell gating, and durable approval suspension — not bolted on.
54
- - **Small and honest.** Four runtime dependencies (`typebox`, `@modelcontextprotocol/sdk`, `undici`, and the sibling package
55
- `@sema-agent/primitives`, installed with it at the same version).
54
+ - **Small and honest.** Five runtime dependencies (`typebox`, `@modelcontextprotocol/client` with its `@modelcontextprotocol/core`,
55
+ `undici`, and the sibling package `@sema-agent/primitives`, installed with it at the same version).
56
56
  A deterministic vitest suite of 5,400+ tests runs fully offline (`npm test`), including a real
57
57
  stdio MCP server.
58
58
  - **Source-available.** BUSL-1.1: free for personal, educational, research, and non-commercial
@@ -15,7 +15,7 @@ export interface AgentTranscriptToolOptions {
15
15
  * lifecycle flip skipped its release). Reads go through `runner.sessions` — a split-store child
16
16
  * (caller-mounted Agent tool with its own runner) is honestly unreadable here after a restart. */
17
17
  agentStore?: import("../core/background-agent-store.js").BackgroundAgentStore;
18
- /** Access identity (mirrors SendMessage/TaskOutput — the mount fills these). */
18
+ /** Access identity (mirrors SendMessage/TaskStop — the mount fills these). */
19
19
  owner?: string;
20
20
  scope?: string;
21
21
  sessionId?: string;
@@ -50,7 +50,7 @@ export interface AgentTranscriptToolOptions {
50
50
  * into a child's tail when the residual isn't enough.
51
51
  *
52
52
  * Safety: reads are bounded to the parent's OWN lineage — the same non-leaking registry access scope as
53
- * SendMessage/TaskOutput (an unknown or out-of-scope id reads identically to "not found"). Two read
53
+ * SendMessage/TaskStop (an unknown or out-of-scope id reads identically to "not found"). Two read
54
54
  * paths keep a child's session reachable: the retain ledger (a RETAINED child), and the durable
55
55
  * agent-store fallback (`agentStore` wired + accessible row + preserved `sessionId` — readable even
56
56
  * with retain off/expired/evicted). Only when BOTH miss does the call return the honest
@@ -100,7 +100,7 @@ export function createAgentTranscriptTool(opts) {
100
100
  if (!row || row.type !== "background_agent") {
101
101
  if (/^w[0-9a-f]{16}$/.test(id) || (row !== undefined && row.type === "workflow")) {
102
102
  return {
103
- content: `No transcript: "${id}" is a WORKFLOW run id — AgentTranscript reads sub-agent transcripts only. For the run's per-agent rows (which agent failed, why, elapsed) call TaskOutput({ task_id: "${id}" }); to continue a fixed script, re-invoke the workflow with resumeFromRunId: "${id}".`,
103
+ content: `No transcript: "${id}" is a WORKFLOW run id — AgentTranscript reads sub-agent transcripts only. The run's per-agent rows (which agent failed, why, elapsed) are in its completion notification (the full record behind the ReadToolResult ref it names); to continue a fixed script, re-invoke the workflow with resumeFromRunId: "${id}".`,
104
104
  details: { error: "workflow_id", id },
105
105
  isError: true,
106
106
  };
@@ -1,10 +1,12 @@
1
- import type { RunInternals, RunnerSelfSeat } from "../core/runner/contracts.js";
1
+ import type { CompositionLeg, RunInternals, RunnerSelfSeat } from "../core/runner/contracts.js";
2
+ import type { CheckpointToken, ResumeOutcome } from "../core/checkpoint-store.js";
2
3
  import type { ModelRef, TaskResult, TaskSpec, TaskStatus } from "../core/types.js";
3
4
  /**
4
5
  * Quality-gate cascade (design/27). Run the SAME task across a ladder of models (cheapest → strongest);
5
6
  * after each rung a caller-supplied **decidable gate** judges "good enough" — pass = keep it, fail =
6
- * escalate to the next rung. Classic FrugalGPT cascade, as a thin function over `runner.runTask`
7
- * (no Runner-core changes).
7
+ * escalate to the next rung. Classic FrugalGPT cascade, as a thin function over `runner.runTask` — and over
8
+ * `runner.resume` for the one rung whose parked card {@link resumeCascade} continues. Both entries climb the ladder through
9
+ * ONE step loop (`climbLadder`); neither has a copy of it.
8
10
  *
9
11
  * APPLICABILITY: cascade only helps when the gate is **decidable** (a schema check, a verifier model, a
10
12
  * concrete assertion). Open-ended "completeness" tasks (find every bug, writing quality) have no oracle —
@@ -126,8 +128,11 @@ export interface CascadeAttempt {
126
128
  export interface CascadeRunResult extends TaskResult {
127
129
  /**
128
130
  * The cascade's conclusion, **distinct from the inherited `status`**: `"passed"` = some rung passed the
129
- * gate; `"exhausted"` = ladder/guards ran out with no rung passing (the last rung's result is returned,
130
- * and its `status` may still be "completed" — judge the cascade by `cascadeOutcome`, not `status`).
131
+ * gate; `"exhausted"` = the cascade ended with no rung passing (the last rung's result is returned, and its
132
+ * `status` may still be "completed" — judge the cascade by `cascadeOutcome`, not `status`). It ends that way
133
+ * when the ladder ran out, when a guard stopped it (escalation cap, cost ceiling, wall-clock budget, the
134
+ * caller's signal), when a rung durably parked (`failed.nestedPause` is on the terminal: {@link resumeCascade}
135
+ * continues it), or when a resumed rung's approved action never started (`failed.unstartedRow`).
131
136
  */
132
137
  cascadeOutcome: "passed" | "exhausted";
133
138
  /** F4: present when a finite `costCeilingMicroUsd` was configured but some rung's spend was unpriced —
@@ -153,8 +158,8 @@ export interface CascadeRunResult extends TaskResult {
153
158
  export declare function runCascade(runner: RunnerSelfSeat, spec: TaskSpec, config: CascadeConfig,
154
159
  /**
155
160
  * The TRUSTED, run-scoped internals channel — the same object `Runner.runTask` takes as its second
156
- * argument — forwarded to EVERY rung under the composition forward contract (identity, with the one
157
- * placement-axis exception stated where the shape is named in `src/index.ts`).
161
+ * argument — forwarded to EVERY rung under the composition forward contract (identity, with the
162
+ * placement exception stated where the shape is named in `src/index.ts`).
158
163
  *
159
164
  * WHY THE SEAT EXISTS: `runCascade` returns a `TaskResult` and DRAINS each rung's event stream
160
165
  * internally, so the host never holds a `TaskStream` for any rung. Without this parameter a
@@ -192,10 +197,64 @@ export declare function runCascade(runner: RunnerSelfSeat, spec: TaskSpec, confi
192
197
  * order. Whether it is still readable afterwards is the FACTORY's contract: each rung's
193
198
  * factory-minted env is torn down at the end of that rung's run.
194
199
  *
195
- * Absent ⇒ every rung is dispatched with `undefined`, with ONE design/380 O1② placement delta either
196
- * way: when neither `placementRoot` nor `rootSessionId` is present, rungs after the first get a
197
- * fresh shallow copy carrying `placementRoot` = the first rung's resolved sessionId (the ladder's
198
- * placement fixed point); every other field still rides by the same reference, and an internals
199
- * object that already carries a fixed point is forwarded verbatim.
200
+ * The design/380 O1② PLACEMENT delta, either way (present or absent): rung 0 is dispatched with a shallow
201
+ * copy whose `onWorkspaceResolved` first records the target rung 0's env reported, then calls the
202
+ * caller's own sink; rungs after the first land where the first rung landed — a fresh shallow copy
203
+ * carrying `placementRoot` = the fixed point that rung's result reports (`TaskResult.placementRoot`)
204
+ * unless the caller's object already resolves there (`placementRoot`, else `rootSessionId`: the
205
+ * ladder's fixed point), and `placementTarget` = that rung's target when it reported one (a later rung
206
+ * minted on another device is refused `config.placement_not_honored`).
207
+ *
208
+ * The COMPOSITION-LEG delta: when the caller's spec names its session (`spec.sessionId`, which no rung
209
+ * runs in — every rung is a cold re-run in its own), every rung is dispatched with a copy carrying
210
+ * `compositionLeg = { entry: "cascade", leg: <the rung's index>, hostSessionId: spec.sessionId }`, so a
211
+ * rung that durably parks files a card that says which rung it is and whose run it belongs to (the host
212
+ * links the card to its run by that session and hands it to {@link resumeCascade}). A spec that names
213
+ * no session mints none: such a rung's card cannot be linked to a composition.
214
+ *
215
+ * Every other field still rides by the same reference; a later rung with nothing to gain on any axis
216
+ * is dispatched with the caller's object itself (absent ⇒ `undefined`).
217
+ */
218
+ internals?: RunInternals): Promise<CascadeRunResult>;
219
+ /**
220
+ * Continue a cascade from a rung's parked card, then climb the rest of the ladder: the resume entry beside {@link runCascade},
221
+ * as {@link import("./verify.js").resumeWithVerification} is beside its fresh-run entry. A rung that durably parks ends the
222
+ * ladder (`cascadeOutcome`, `failed.nestedPause`) — the host holds the token, and the card's
223
+ * `CheckpointState.compositionLeg` says which rung parked and which host session it belongs to. Once the pause is decided,
224
+ * the host calls this with the token, the outcome, the ORIGINAL task spec, the ladder config and that `compositionLeg` as the
225
+ * card records it.
226
+ *
227
+ * A run whose task spec named no session (`spec.sessionId`) and whose caller handed it no leg through `internals` mints no
228
+ * composition leg, so its card records none: the host supplies `parkedLeg` itself — `{ entry: "cascade", leg: <the parked rung:
229
+ * the result's `finalRung`>, hostSessionId: <a session of its own> }` — and that value is the card's first record. The
230
+ * terminal's sentence says so.
231
+ *
232
+ * - **One door**: the parked rung is continued through `runner.resume(token, outcome, <rung config>, internals)` — the rung's
233
+ * config is the one {@link runCascade} derives for that rung (the task spec with the rung's model and overrides), minus the
234
+ * members a resume does not take (`objective`, `sessionId`, `userAttachments`, `runOrigin`); its internals carry
235
+ * `compositionLeg = parkedLeg`, so a card that records a different leg is refused before anything is consumed
236
+ * (`resume.composition_mismatch`, the card stays pending). The rung's placement fixed point and fence come back off the card
237
+ * inside the resumed rung's prepare; this entry neither reads nor re-supplies them. The rungs after it are placed at the fixed
238
+ * point the resumed rung reports.
239
+ * - **The resumed rung occupies its slot**: it continues the rung that parked, it is not a new escalation, so it is never
240
+ * refused by the escalation cap, the cost ceiling or the wall-clock budget, and the deadline does not cut it; it is run under
241
+ * the caller's `spec.signal` alone. Its result is gated exactly like a fresh rung: a pass ends the ladder `passed`, a fail
242
+ * escalates to the next rung, a re-park ends it again with that rung's own card. A resumed rung whose approved action never
243
+ * started (`resume.reopened_unstarted` / `resume.reopen_failed_unstarted`: the card is pending again, or its state unproven)
244
+ * is never escalated: the ladder ends there with its result as is, the session kept, and the same token resumes it again.
245
+ * - **Accounting covers this call**: `attempts` starts at the resumed rung (`index: parkedLeg.leg`), and the cumulative stats,
246
+ * the escalations counted against `maxEscalations`, the cost ceiling and `totalTimeoutMs` cover only the rungs this call
247
+ * dispatched. The resumed rung's stats are the engine's own report of that leg — never added to the stats of the call that
248
+ * parked it. A host that keeps one budget across a pause passes what is left of it.
249
+ *
250
+ * `parkedLeg` that is not a cascade leg of this ladder (another entry, a rung index outside the ladder, an empty host session)
251
+ * is refused before anything is dispatched (`config.cascade_invalid`); the checkpoint is untouched.
200
252
  */
253
+ export declare function resumeCascade(runner: RunnerSelfSeat, token: CheckpointToken, outcome: ResumeOutcome,
254
+ /** The ORIGINAL task spec the cascade ran (objective, attachments and run origin included): every rung after the resumed one
255
+ * is a cold re-run of it, and the resumed rung's config is derived from it. */
256
+ spec: TaskSpec, config: CascadeConfig,
257
+ /** The parked card's `CheckpointState.compositionLeg`, as the card records it. */
258
+ parkedLeg: CompositionLeg,
259
+ /** The trusted run-scoped internals channel, forwarded to every rung under the same contract as {@link runCascade}'s. */
201
260
  internals?: RunInternals): Promise<CascadeRunResult>;
@@ -1,8 +1,9 @@
1
1
  import { terminalProjection } from "../core/runner/terminal-projection.js";
2
2
  import { releaseSession } from "./session-util.js";
3
- import { mapNestedSuspend, isDurablePause } from "./suspend-guard.js";
3
+ import { mapNestedSuspend, isDurablePause, resumeNeverStarted } from "./suspend-guard.js";
4
4
  import { buildCumulativeStats } from "./cumulative-stats.js";
5
5
  import { createSafeNotifier } from "../core/safe-notify.js";
6
+ import { compositionPlacement } from "./composition-placement.js";
6
7
  import { thrownText } from "../core/thrown-value.js";
7
8
  const CASCADE_ON_RUNG_SITE = "cascade.onRung";
8
9
  const CASCADE_CONFIG_ERROR_CODE = "config.cascade_invalid";
@@ -21,15 +22,42 @@ function createDefaultGate(spec) {
21
22
  return (result) => result.terminal.kind === "completed" && (!requiresStructured || result.structuredOutput !== undefined);
22
23
  }
23
24
  export async function runCascade(runner, spec, config, internals) {
25
+ const hostSessionId = spec.sessionId || undefined;
26
+ return climbLadder("runCascade", runner, spec, config, internals, { kind: "fresh", hostSessionId });
27
+ }
28
+ export async function resumeCascade(runner, token, outcome, spec, config, parkedLeg, internals) {
29
+ const ladderLength = config.ladder?.length ?? 0;
30
+ const leg = parkedLeg;
31
+ const entry = typeof leg === "object" && leg !== null ? Reflect.get(leg, "entry") : undefined;
32
+ const index = typeof leg === "object" && leg !== null ? Reflect.get(leg, "leg") : undefined;
33
+ const host = typeof leg === "object" && leg !== null ? Reflect.get(leg, "hostSessionId") : undefined;
34
+ if (ladderLength > 0 && (entry !== "cascade" || typeof index !== "number" || !Number.isInteger(index) || index < 0 || index >= ladderLength || typeof host !== "string" || host === "")) {
35
+ throw cascadeConfigError(`resumeCascade: parkedLeg must be the card's cascade leg of this ladder — { entry: "cascade", leg: <a rung index below ${ladderLength}>, hostSessionId: <a session> } (got ${describeParkedLeg(leg)}); nothing was resumed and the checkpoint is untouched.`);
36
+ }
37
+ return climbLadder("resumeCascade", runner, spec, config, internals, { kind: "resume", token, outcome, parked: { entry: "cascade", leg: index, hostSessionId: host } });
38
+ }
39
+ function describeParkedLeg(leg) {
40
+ if (typeof leg !== "object" || leg === null)
41
+ return typeof leg;
42
+ try {
43
+ return JSON.stringify({ entry: Reflect.get(leg, "entry"), leg: Reflect.get(leg, "leg"), hostSessionId: Reflect.get(leg, "hostSessionId") }) ?? "an unreadable object";
44
+ }
45
+ catch {
46
+ return "an unreadable object";
47
+ }
48
+ }
49
+ async function climbLadder(entryName, runner, spec, config, internals, opening) {
24
50
  const ladder = config.ladder;
25
51
  if (!ladder || ladder.length === 0) {
26
- throw new Error("runCascade: config.ladder must have at least one rung");
52
+ throw new Error(`${entryName}: config.ladder must have at least one rung`);
27
53
  }
28
54
  const maxEscalations = config.maxEscalations ?? ladder.length - 1;
29
55
  if (typeof maxEscalations !== "number" || !Number.isFinite(maxEscalations)) {
30
- throw cascadeConfigError(`runCascade: config.maxEscalations must be a finite number (got ${String(config.maxEscalations)}) — an unevaluable escalation ceiling is not a ceiling, and folding it to a default would run the cascade under a bound nobody chose.`);
56
+ throw cascadeConfigError(`${entryName}: config.maxEscalations must be a finite number (got ${String(config.maxEscalations)}) — an unevaluable escalation ceiling is not a ceiling, and folding it to a default would run the cascade under a bound nobody chose.`);
31
57
  }
32
- const maxRungs = Math.min(ladder.length, Math.max(0, maxEscalations) + 1);
58
+ const start = opening.kind === "resume" ? opening.parked.leg : 0;
59
+ const maxRungs = Math.min(ladder.length, start + Math.max(0, maxEscalations) + 1);
60
+ const hostSessionId = opening.kind === "resume" ? opening.parked.hostSessionId : opening.hostSessionId;
33
61
  const gate = config.gate ?? createDefaultGate(spec);
34
62
  const startedAt = Date.now();
35
63
  const deadlineAt = config.totalTimeoutMs != null ? startedAt + config.totalTimeoutMs : undefined;
@@ -65,43 +93,56 @@ export async function runCascade(runner, spec, config, internals) {
65
93
  });
66
94
  let lastResult;
67
95
  let passedRung = -1;
68
- let ladderPlacementRoot;
96
+ let firstLegResult;
97
+ let finalRung = -1;
98
+ const placement = compositionPlacement(internals);
69
99
  const { sessionId: _drop, ...specBase } = spec;
70
- for (let i = 0; i < maxRungs; i++) {
71
- if (deadlineAt !== undefined && Date.now() >= deadlineAt)
72
- break;
73
- if (i > 0 && config.costCeilingMicroUsd != null && (totalCost >= config.costCeilingMicroUsd || !ceilingCostKnown)) {
74
- break;
100
+ const rungSpecOf = (rung, signal) => ({ ...specBase, model: rung.model, ...(rung.overrides ?? {}), ...(signal ? { signal } : {}) });
101
+ const resumeConfigOf = (task) => {
102
+ const { objective: _objective, userAttachments: _attachments, runOrigin: _origin, ...config } = task;
103
+ return config;
104
+ };
105
+ const legOf = (i) => (hostSessionId === undefined ? undefined : { entry: "cascade", leg: i, hostSessionId });
106
+ for (let i = start; i < maxRungs; i++) {
107
+ const resumed = opening.kind === "resume" && i === start ? opening : undefined;
108
+ if (resumed === undefined) {
109
+ if (deadlineAt !== undefined && Date.now() >= deadlineAt)
110
+ break;
111
+ if (i > start && config.costCeilingMicroUsd != null && (totalCost >= config.costCeilingMicroUsd || !ceilingCostKnown)) {
112
+ break;
113
+ }
75
114
  }
76
115
  const rung = ladder[i];
77
116
  let deadlineFired = false;
78
117
  const rungAbort = new AbortController();
79
118
  let deadlineTimer;
80
- if (deadlineAt !== undefined) {
119
+ if (deadlineAt !== undefined && resumed === undefined) {
81
120
  deadlineTimer = setTimeout(() => {
82
121
  deadlineFired = true;
83
- rungAbort.abort(new Error(`runCascade: totalTimeoutMs (${config.totalTimeoutMs}ms) reached`));
122
+ rungAbort.abort(new Error(`${entryName}: totalTimeoutMs (${config.totalTimeoutMs}ms) reached`));
84
123
  }, Math.max(0, deadlineAt - Date.now()));
85
124
  deadlineTimer.unref?.();
86
125
  }
87
- const rungSignal = deadlineAt === undefined
126
+ const rungSignal = deadlineTimer === undefined
88
127
  ? specBase.signal
89
128
  : specBase.signal
90
129
  ? AbortSignal.any([specBase.signal, rungAbort.signal])
91
130
  : rungAbort.signal;
92
131
  let result;
93
- const rungInternals = ladderPlacementRoot === undefined || internals?.placementRoot !== undefined || internals?.rootSessionId !== undefined
94
- ? internals
95
- : { ...internals, placementRoot: ladderPlacementRoot };
132
+ const placed = firstLegResult === undefined ? placement.firstLeg : placement.laterLeg(firstLegResult);
133
+ const compositionLeg = resumed !== undefined ? resumed.parked : legOf(i);
134
+ const rungInternals = compositionLeg === undefined ? placed : { ...placed, compositionLeg };
135
+ const rungTask = rungSpecOf(rung, rungSignal);
96
136
  try {
97
- result = await runner.runTask({ ...specBase, model: rung.model, ...(rung.overrides ?? {}), ...(rungSignal ? { signal: rungSignal } : {}) }, rungInternals);
137
+ result = resumed !== undefined ? await runner.resume(resumed.token, resumed.outcome, resumeConfigOf(rungTask), rungInternals) : await runner.runTask(rungTask, rungInternals);
98
138
  }
99
139
  finally {
100
140
  if (deadlineTimer !== undefined)
101
141
  clearTimeout(deadlineTimer);
102
142
  }
103
143
  lastResult = result;
104
- ladderPlacementRoot ??= internals?.placementRoot ?? internals?.rootSessionId ?? result.sessionId;
144
+ finalRung = i;
145
+ firstLegResult ??= result;
105
146
  const s = result.stats;
106
147
  const rungCostKnown = s.costMicroUsd !== undefined && (s.nested === undefined || s.nested.costMicroUsd !== undefined);
107
148
  const rungCost = rungCostKnown ? (s.costMicroUsd ?? 0) + (s.nested?.costMicroUsd ?? 0) : undefined;
@@ -136,8 +177,8 @@ export async function runCascade(runner, spec, config, internals) {
136
177
  nestedTasks += s.nested.tasks;
137
178
  nestedCostMicro += s.nested.costMicroUsd ?? 0;
138
179
  }
139
- if (isDurablePause(result.terminal)) {
140
- const mapped = mapNestedSuspend(result);
180
+ if (isDurablePause(result.terminal) || resumeNeverStarted(result)) {
181
+ const mapped = mapNestedSuspend(result, { door: "resumeCascade", legFrom: rungInternals?.compositionLeg === undefined ? "caller" : "card" });
141
182
  attempts.push({ index: i, model: rung.model, passed: false, costMicroUsd: rungCost, status: attemptTerminal(result).status, errorCode: attemptTerminal(mapped).errorCode });
142
183
  return {
143
184
  ...mapped,
@@ -216,7 +257,6 @@ export async function runCascade(runner, spec, config, internals) {
216
257
  };
217
258
  }
218
259
  const base = lastResult;
219
- const finalRung = attempts.length - 1;
220
260
  return {
221
261
  ...base,
222
262
  stats: cumulativeStats(base.stats),
@@ -0,0 +1,53 @@
1
+ import type { TaskSpec } from "../core/types.js";
2
+ /**
3
+ * The allowance a composition's later legs run on. A composition that dispatches several legs of ONE task — the
4
+ * verification gate's implementation and fix legs, the repair loop's attempts — spends from one account: every leg after
5
+ * the first is dispatched with what the task's WHOLE-TASK ceilings have left after the legs before it, so the caller's
6
+ * ceiling bounds the task, not each leg of it. One rule, read the same by every such composition:
7
+ * · the whole-task ceilings are `resourceSuspend.totalBudgetUsd` / `totalTokens` on a task that opted into resource
8
+ * suspension (its `limits` windows pace each slice, and each leg opens one exactly as a resume does), and
9
+ * `limits.maxCostUsd` / `maxTokens` / `maxTurns` otherwise (a task that cannot suspend runs one slice, so its window is
10
+ * the whole task's);
11
+ * · what the legs spent is their OWN reported spend — the figures the engine's limit gate reads on each leg (delegated
12
+ * children's spend stays on their own axis, as it does there);
13
+ * · an axis with nothing left dispatches no further leg: the composition stops where its own ceilings stop it, and says
14
+ * which axis (`AllowanceExhausted`) — it never mints a leg's terminal for a leg that did not run.
15
+ * The engine is not involved: the later leg's spec carries the figure, so the engine judges that leg exactly as it judges
16
+ * any run, and a leg that durably parks freezes the figure on its first slice's ledger. The account is the one call's: the
17
+ * ceilings are the ones this call was handed and the spend is what its legs reported, so across a durable pause it does
18
+ * not see the parking call's other legs or the totals frozen on the checkpoint (`docs/KNOWN-LIMITS.md` KL-3170-c, closed by #3176).
19
+ */
20
+ /** The whole-task axes a composition's legs share. */
21
+ export type AllowanceAxis = "cost" | "tokens" | "turns";
22
+ /** What a composition's legs spent so far, from their own reports. `costMicroUsd` is undefined once any leg was unpriced. */
23
+ export interface CompositionSpend {
24
+ readonly costMicroUsd: number | undefined;
25
+ readonly tokens: number;
26
+ readonly turns: number;
27
+ }
28
+ /**
29
+ * A whole-task axis with nothing left, so the composition dispatched no further leg. `remaining` is in the axis's own unit
30
+ * (micro-USD for `cost`, tokens, turns) and is `0` once the legs spent the ceiling; it is absent when the spend on the axis
31
+ * cannot be known (a leg ran unpriced under a cost ceiling; a reported figure that is NaN, infinite or negative, on any
32
+ * axis), which is never read as room to spend.
33
+ */
34
+ export interface AllowanceExhausted {
35
+ readonly axis: AllowanceAxis;
36
+ readonly remaining?: number;
37
+ }
38
+ /** A later leg's dispatch: the spec carrying what is left, or the axis with nothing left. */
39
+ export type LaterLegAllowance<S> = {
40
+ readonly spec: S;
41
+ readonly exhausted?: undefined;
42
+ } | {
43
+ readonly spec?: undefined;
44
+ readonly exhausted: AllowanceExhausted;
45
+ };
46
+ type AllowanceSpec = Pick<TaskSpec, "limits" | "resourceSuspend">;
47
+ /**
48
+ * The spec a composition's later leg is dispatched with, given the caller's spec and what the legs before it spent. Every
49
+ * armed whole-task ceiling is replaced by what is left of it; nothing armed ⇒ the caller's spec itself (the same object).
50
+ * The attribution order when several axes are spent is the engine's own: tokens, then cost, then turns.
51
+ */
52
+ export declare function laterLegAllowance<S extends AllowanceSpec>(spec: S, spent: CompositionSpend): LaterLegAllowance<S>;
53
+ export {};
@@ -0,0 +1,49 @@
1
+ export function laterLegAllowance(spec, spent) {
2
+ const suspendable = spec.resourceSuspend !== undefined;
3
+ const ceiling = (v) => (v !== undefined && Number.isFinite(v) ? v : undefined);
4
+ const costCeiling = ceiling(suspendable ? spec.resourceSuspend?.totalBudgetUsd : spec.limits?.maxCostUsd);
5
+ const tokenCeiling = ceiling(suspendable ? spec.resourceSuspend?.totalTokens : spec.limits?.maxTokens);
6
+ const turnCeiling = suspendable || spec.limits?.maxTurns === 0 ? undefined : ceiling(spec.limits?.maxTurns);
7
+ const known = (v) => v !== undefined && Number.isFinite(v) && v >= 0;
8
+ if (tokenCeiling !== undefined && !known(spent.tokens))
9
+ return { exhausted: { axis: "tokens" } };
10
+ const tokensLeft = tokenCeiling === undefined ? undefined : tokenCeiling - spent.tokens;
11
+ if (tokensLeft !== undefined && tokensLeft <= 0)
12
+ return { exhausted: { axis: "tokens", remaining: 0 } };
13
+ if (costCeiling !== undefined && !known(spent.costMicroUsd))
14
+ return { exhausted: { axis: "cost" } };
15
+ const costLeftMicroUsd = costCeiling === undefined ? undefined : Math.round(costCeiling * 1e6) - (spent.costMicroUsd ?? 0);
16
+ if (costLeftMicroUsd !== undefined && costLeftMicroUsd <= 0)
17
+ return { exhausted: { axis: "cost", remaining: 0 } };
18
+ if (turnCeiling !== undefined && !known(spent.turns))
19
+ return { exhausted: { axis: "turns" } };
20
+ const turnsLeft = turnCeiling === undefined ? undefined : turnCeiling - spent.turns;
21
+ if (turnsLeft !== undefined && turnsLeft <= 0)
22
+ return { exhausted: { axis: "turns", remaining: 0 } };
23
+ if (tokensLeft === undefined && costLeftMicroUsd === undefined && turnsLeft === undefined)
24
+ return { spec };
25
+ const totals = spec.resourceSuspend;
26
+ if (totals !== undefined) {
27
+ return {
28
+ spec: {
29
+ ...spec,
30
+ resourceSuspend: {
31
+ ...totals,
32
+ ...(costLeftMicroUsd !== undefined ? { totalBudgetUsd: costLeftMicroUsd / 1e6 } : {}),
33
+ ...(tokensLeft !== undefined ? { totalTokens: tokensLeft } : {}),
34
+ },
35
+ },
36
+ };
37
+ }
38
+ return {
39
+ spec: {
40
+ ...spec,
41
+ limits: {
42
+ ...spec.limits,
43
+ ...(costLeftMicroUsd !== undefined ? { maxCostUsd: costLeftMicroUsd / 1e6 } : {}),
44
+ ...(tokensLeft !== undefined ? { maxTokens: tokensLeft } : {}),
45
+ ...(turnsLeft !== undefined ? { maxTurns: turnsLeft } : {}),
46
+ },
47
+ },
48
+ };
49
+ }
@@ -0,0 +1,29 @@
1
+ import type { RunInternals } from "../core/runner/contracts.js";
2
+ import type { TaskResult } from "../core/types.js";
3
+ /**
4
+ * Where a composition entry places the legs it drives after the first — a cascade's rungs after the first it drives, a
5
+ * verification gate's verifier and fix legs. They are ONE piece of work, so each later leg is placed where the FIRST leg ran, on
6
+ * both axes a target-bound env factory reads:
7
+ * · the tree's fixed point (`RunInternals.placementRoot`): every later leg lands where the first leg landed — the first leg's
8
+ * own report of the fixed point its prepare resolved (`TaskResult.placementRoot`). It is minted into the copy unless the
9
+ * caller's object already resolves there by prepare's fold (`placementRoot`, else `rootSessionId`); on a fresh entry it
10
+ * always does whenever the caller carries a fixed point, so that caller's object rides unchanged. The first leg is the one
11
+ * the entry drove first: a resume entry's resumed leg reports the fixed point its parked row recorded, which outranks a
12
+ * supplied `rootSessionId` there, so a caller whose `rootSessionId` names another session still sees every leg after it land
13
+ * where the composition's work was placed, not at that session or the resumed leg's own. A first leg that reported none (a
14
+ * result no run assembled) mints none — the same law as the target below;
15
+ * · the target (`RunInternals.placementTarget`): what the first leg's environment reported as its workspace settled, learned
16
+ * through the trusted `onWorkspaceResolved` seat — the first leg is dispatched with a shallow copy whose sink records it
17
+ * before handing the payload to the caller's own sink, if any. A later leg whose env does not name the device the first leg's
18
+ * did is refused (`config.placement_not_honored`): a re-bind mid-composition moves no later leg onto another device. A first
19
+ * leg that reported no target leaves the caller's own `placementTarget` (if any) riding by reference.
20
+ * Every other field of the caller's object rides every leg by the caller's reference; the caller's object is never mutated, and
21
+ * a later leg with nothing to gain on either axis is dispatched with the caller's object itself.
22
+ */
23
+ export interface CompositionPlacement {
24
+ /** The internals the first leg is dispatched with: a copy whose `onWorkspaceResolved` records the leg's own target. */
25
+ readonly firstLeg: RunInternals;
26
+ /** The internals a later leg is dispatched with, given the first leg's result (its self-reported fixed point). */
27
+ laterLeg(firstLeg: Pick<TaskResult, "placementRoot">): RunInternals | undefined;
28
+ }
29
+ export declare function compositionPlacement(internals: RunInternals | undefined): CompositionPlacement;
@@ -0,0 +1,24 @@
1
+ export function compositionPlacement(internals) {
2
+ let observed = false;
3
+ let firstTarget;
4
+ const firstLeg = {
5
+ ...internals,
6
+ onWorkspaceResolved: (workspace) => {
7
+ if (!observed) {
8
+ observed = true;
9
+ firstTarget = workspace.target;
10
+ }
11
+ internals?.onWorkspaceResolved?.(workspace);
12
+ },
13
+ };
14
+ return {
15
+ firstLeg,
16
+ laterLeg(first) {
17
+ const landed = first.placementRoot;
18
+ const root = landed !== undefined && (internals?.placementRoot ?? internals?.rootSessionId) !== landed ? landed : undefined;
19
+ if (root === undefined && firstTarget === undefined)
20
+ return internals;
21
+ return { ...internals, ...(root !== undefined ? { placementRoot: root } : {}), ...(firstTarget !== undefined ? { placementTarget: firstTarget } : {}) };
22
+ },
23
+ };
24
+ }
@@ -1,4 +1,5 @@
1
1
  import type { TaskResult } from "../core/types.js";
2
+ import type { CompositionSpend } from "./composition-allowance.js";
2
3
  /**
3
4
  * Shared CUMULATIVE-STATS constructor for the multi-leg agent compositions (cascade rungs, repair-loop
4
5
  * attempts, verify legs). Each runs `runner.runTask` MORE THAN ONCE and must report the OPERATION's totals,
@@ -95,6 +96,9 @@ export interface CumulativeStatsTracker {
95
96
  * would rewrite a caller's object (0 → `undefined` normalization, a re-derived `cacheHitRate`) for no
96
97
  * gain. */
97
98
  readonly legs: number;
99
+ /** The legs' OWN spend so far, on the axes a later leg's allowance is cut from (`./composition-allowance.ts`); the cost is
100
+ * undefined once any leg was unpriced. */
101
+ spend(): CompositionSpend;
98
102
  }
99
103
  /**
100
104
  * Create a {@link CumulativeStatsTracker}.
@@ -83,5 +83,8 @@ export function createCumulativeStatsTracker() {
83
83
  build(base) {
84
84
  return buildCumulativeStats(base, acc);
85
85
  },
86
+ spend() {
87
+ return { costMicroUsd: acc.anyLegUnpriced ? undefined : acc.costMicroUsd, tokens: acc.tokens, turns: acc.turns };
88
+ },
86
89
  };
87
90
  }
@@ -36,9 +36,11 @@ export declare function inheritedMcpDeclarations(mounted: MountedMcp, selector:
36
36
  * host-transport servers among the child's declarations (`servers`), as the child's internals carry them — none ⇒ no member, so such a server
37
37
  * of the child fails its dial like any declaration without a seat. */
38
38
  export declare function inheritedHostSeats(held: ReadonlyMap<string, McpHostSeat> | undefined, servers: ReadonlyArray<McpServerSpec>): Pick<RunInternals, "mcpHostSeats">;
39
- /** A child's internals as a retained snapshot keeps them: without host seats — they are live objects of the run that held them, and each wake
40
- * hands the waker's own ({@link inheritedHostSeats} over the waker's mount). */
41
- export declare function withoutHostSeats(internals: RunInternals): RunInternals;
39
+ /** A child's internals as a retained snapshot keeps them: without the seats that belong to whoever wakes it — the host seats (live objects of
40
+ * the run that held them), the placement fence (the target of the leg that spawned it) and the objective's author (who wrote the spawn's
41
+ * prompt). Each wake hands the waker's own: its seats ({@link inheritedHostSeats} over the waker's mount), its target, so a woken agent is
42
+ * minted where its waker is — the same answer a tier-3 revival of that agent gets — and its author, since every resume states who wrote it. */
43
+ export declare function withoutWakerSeats(internals: RunInternals): RunInternals;
42
44
  /**
43
45
  * The MCP servers a leg spawned as an agent definition is declared ({@link AgentDefinition.mcp}): the servers its lane hands it (the
44
46
  * spawning run's it inherits, a workflow child's governed spec's) first, then each of the definition's own whose tool namespace none of
@@ -22,8 +22,8 @@ export function inheritedHostSeats(held, servers) {
22
22
  });
23
23
  return seats.length > 0 ? { mcpHostSeats: new Map(seats) } : {};
24
24
  }
25
- export function withoutHostSeats(internals) {
26
- const { mcpHostSeats: _live, ...kept } = internals;
25
+ export function withoutWakerSeats(internals) {
26
+ const { mcpHostSeats: _live, placementTarget: _spawnersTarget, objectiveAuthor: _spawnAuthor, ...kept } = internals;
27
27
  return kept;
28
28
  }
29
29
  export function withDefinitionServers(handed, own) {
@@ -101,7 +101,7 @@ export interface ListAgentsRow {
101
101
  * COMPLETED and nothing else: a model applies the continuable rule to that word. */
102
102
  state: "busy" | "idle" | "offline" | "running" | "parked" | "finished" | "failed" | "killed" | "cancelled" | "unknown";
103
103
  /** Agent lanes with a live registry row: the agent's current state
104
- * ({@link import("../core/agent-state.js").readAgentState}, the one reading AgentTranscript and TaskOutput
104
+ * ({@link import("../core/agent-state.js").readAgentState}, the one reading AgentTranscript and the host task poll
105
105
  * render too); {@link state} is this status word through the lane table. Absent on peer rows and on a
106
106
  * roster row with no live row. */
107
107
  agentState?: AgentState;
@@ -27,6 +27,10 @@ export interface PeerHeldEntry {
27
27
  * waiting for a lease-holding pass — a re-judgment that now refuses still wins); `delivered` (this
28
28
  * queue took the hand-over move and the injection is still owed; a policy that now refuses ends it as `dropped`). */
29
29
  decision: PeerCardDecision;
30
+ /** When this hold resolves to `expired` unless someone answers it first (ms epoch) — present exactly while
31
+ * its expiry timer is armed: a cause in `PEER_HELD_REVIEW_CAUSES`, a finite `dialogExpiry`, the card still
32
+ * `held`. A cause move re-arms or clears it; an approval, a hand-over, the deadline itself or the card leaving clears it. */
33
+ deadlineAt?: number;
30
34
  }
31
35
  /** How an entry left this queue. `retired` — the CARD left this process but no decision was taken: the
32
36
  * record stays held in its box for the next consumer (a queue-local event no receipt announced,
@@ -56,8 +60,10 @@ export interface PeerHeldQueueSink {
56
60
  * deliver never takes a move out of `delivered`. Absent ⇒
57
61
  * the presence of `inject` decides. */
58
62
  canInject?: (entry: PeerHeldEntry) => boolean;
59
- /** The receipt to the sender (the binding routes it into the sender's box). */
60
- receipt: (entry: PeerHeldEntry, state: PeerDeliveryReceiptState) => void;
63
+ /** The receipt to the sender (the binding routes it into the sender's box). Resolves once the receipt is in
64
+ * that box (or has no reader there); rejects when it could not be written. Only {@link PeerHeldQueue.shutdown}
65
+ * waits on it — every other path sends and goes on. */
66
+ receipt: (entry: PeerHeldEntry, state: PeerDeliveryReceiptState) => Promise<void>;
61
67
  /** Does a receipt about this entry reach a sender? A queue-local event (eviction, shutdown, a refused
62
68
  * release) is a decision about the record exactly when it does — the sender is told it is final. */
63
69
  tellsSender: (entry: PeerHeldEntry) => boolean;
@@ -101,7 +107,7 @@ export interface PeerHeldQueue {
101
107
  * At the cap, settles the oldest held card that tells its sender (it is then a decision); arms the
102
108
  * deadline for a hold cause a person could answer.
103
109
  */
104
- hold(entry: Omit<PeerHeldEntry, "heldAt" | "decision">, decision?: PeerCardDecision): Promise<PeerHoldOutcome>;
110
+ hold(entry: Omit<PeerHeldEntry, "heldAt" | "decision" | "deadlineAt">, decision?: PeerCardDecision): Promise<PeerHoldOutcome>;
105
111
  /** Re-judge every entry against current settings (CC `D`): deliverable ⇒ handed over (or kept with no
106
112
  * live run), refused ⇒ refused with a receipt, still held ⇒ re-announced only when the cause moved.
107
113
  * Every move goes through the decision seat. */
@@ -128,7 +134,8 @@ export interface PeerHeldQueue {
128
134
  list(): readonly PeerHeldEntry[];
129
135
  size(): number;
130
136
  /** CC `HBe` — a graceful shutdown settles everything still held as `expired` with receipts (where a
131
- * receipt reaches a sender; elsewhere the cards just leave this process). */
137
+ * receipt reaches a sender; elsewhere the cards just leave this process). Resolves once every receipt it
138
+ * sent has landed; rejects naming the seqs whose receipt did not (every card is settled either way). */
132
139
  shutdown(): Promise<void>;
133
140
  }
134
141
  export declare function createPeerHeldQueue(key: string, opts?: {
@@ -149,5 +156,21 @@ export declare function peerHeldQueueFor(scope: string, sessionId: string, opts?
149
156
  /** The held queue of a session if one exists in this process (a host review face reads through this
150
157
  * without creating state for sessions that never held anything); `box` as in {@link peerHeldQueueFor}. */
151
158
  export declare function peerHeldQueueIfAny(scope: string, sessionId: string, box?: string): PeerHeldQueue | undefined;
159
+ /** One held queue of this process as {@link listPeerHeldQueues} shows it. */
160
+ export interface PeerHeldQueueSnapshot {
161
+ readonly scope: string;
162
+ /** The session that opened the queue (the spelling it first used; the key folds case). */
163
+ readonly sessionId: string;
164
+ /** The box its cards come from: the session's own, or the principal inbox it also drains. */
165
+ readonly box: string;
166
+ readonly size: number;
167
+ /** The cards as {@link PeerHeldQueue.list} shows them, at the same moment as `size`. */
168
+ readonly entries: readonly PeerHeldEntry[];
169
+ }
170
+ /** Every held queue of this process's registry (opened through {@link peerHeldQueueFor}, as every drain opens its
171
+ * queues; a bare {@link createPeerHeldQueue} is not in it), as a read-only snapshot that opens none: a host approval face lists
172
+ * the held cards of all its sessions without keeping its own table of (session, box) coordinates. A row's
173
+ * (scope, sessionId, box) handed to {@link peerHeldQueueIfAny} reaches that queue for its settle face. */
174
+ export declare function listPeerHeldQueues(): readonly PeerHeldQueueSnapshot[];
152
175
  /** Test seam: drop every queue (timers cleared, NO receipts — the crash form). Never called by production code. */
153
176
  export declare function resetPeerHeldQueuesForTests(): void;