@sema-agent/core 7.60.0 → 7.61.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 (482) hide show
  1. package/CHANGELOG.md +605 -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 +61 -10
  6. package/dist/agents/cascade.js +60 -20
  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-notice-route.d.ts +1 -1
  17. package/dist/agents/peer-notice-route.js +4 -3
  18. package/dist/agents/peer-notices.d.ts +4 -4
  19. package/dist/agents/peer-notices.js +8 -4
  20. package/dist/agents/peer-session-drain.d.ts +8 -1
  21. package/dist/agents/peer-session-drain.js +36 -7
  22. package/dist/agents/repair-loop.js +16 -6
  23. package/dist/agents/retain-ledger.js +3 -1
  24. package/dist/agents/roster-store.d.ts +1 -1
  25. package/dist/agents/roster-store.js +7 -4
  26. package/dist/agents/send-message-tool.d.ts +8 -10
  27. package/dist/agents/send-message-tool.js +43 -23
  28. package/dist/agents/subagent-completion-gate.d.ts +35 -0
  29. package/dist/agents/subagent-completion-gate.js +62 -0
  30. package/dist/agents/subagent-steps.d.ts +7 -6
  31. package/dist/agents/subagent.d.ts +30 -40
  32. package/dist/agents/subagent.js +187 -196
  33. package/dist/agents/suspend-guard.d.ts +9 -0
  34. package/dist/agents/suspend-guard.js +4 -0
  35. package/dist/agents/verify.d.ts +41 -14
  36. package/dist/agents/verify.js +37 -27
  37. package/dist/brain/anthropic.js +1 -0
  38. package/dist/brain/errors.d.ts +7 -1
  39. package/dist/brain/errors.js +6 -0
  40. package/dist/brain/failover.js +2 -1
  41. package/dist/brain/open-responses.js +1 -0
  42. package/dist/brain/openai.js +1 -0
  43. package/dist/brain/provider-dialect.d.ts +10 -0
  44. package/dist/brain/provider-dialect.js +13 -2
  45. package/dist/brain/stream-engine.d.ts +3 -0
  46. package/dist/brain/stream-engine.js +4 -0
  47. package/dist/core/agent-state.d.ts +1 -1
  48. package/dist/core/allow-entry.d.ts +59 -23
  49. package/dist/core/allow-entry.js +131 -38
  50. package/dist/core/ask-origin.d.ts +79 -0
  51. package/dist/core/ask-origin.js +76 -0
  52. package/dist/core/ask-question.d.ts +19 -13
  53. package/dist/core/ask-question.js +8 -2
  54. package/dist/core/auto-compaction.d.ts +2 -0
  55. package/dist/core/auto-compaction.js +2 -1
  56. package/dist/core/auto-mode.js +3 -5
  57. package/dist/core/background-agent-store.d.ts +7 -5
  58. package/dist/core/background-agent-store.js +12 -11
  59. package/dist/core/checkpoint-requirements.d.ts +24 -3
  60. package/dist/core/checkpoint-requirements.js +9 -1
  61. package/dist/core/checkpoint-store.d.ts +78 -19
  62. package/dist/core/checkpoint-store.js +8 -4
  63. package/dist/core/child-clamp-seats.d.ts +3 -2
  64. package/dist/core/child-clamp-seats.js +4 -3
  65. package/dist/core/closest-name.d.ts +13 -0
  66. package/dist/core/closest-name.js +35 -0
  67. package/dist/core/context-settings.js +3 -5
  68. package/dist/core/cross-boundary-taint.d.ts +1 -1
  69. package/dist/core/decision-receipt.d.ts +14 -1
  70. package/dist/core/decision-receipt.js +6 -3
  71. package/dist/core/delegation-frames.d.ts +13 -9
  72. package/dist/core/effective-path-target.js +2 -3
  73. package/dist/core/engine-attestation.d.ts +11 -1
  74. package/dist/core/engine-attestation.js +2 -0
  75. package/dist/core/engine-notice.d.ts +49 -18
  76. package/dist/core/file-history-retention.d.ts +8 -0
  77. package/dist/core/file-history-retention.js +14 -11
  78. package/dist/core/file-history-store.d.ts +31 -1
  79. package/dist/core/file-history-store.js +31 -2
  80. package/dist/core/frame-settlement.d.ts +10 -0
  81. package/dist/core/frame-settlement.js +6 -1
  82. package/dist/core/fs-write-gate-policy.d.ts +3 -3
  83. package/dist/core/fs-write-gate-policy.js +8 -7
  84. package/dist/core/gate-fold.js +2 -1
  85. package/dist/core/gate-lanes.js +7 -4
  86. package/dist/core/gate-outcome.d.ts +40 -1
  87. package/dist/core/gate-outcome.js +10 -0
  88. package/dist/core/git-worktree-env.d.ts +7 -3
  89. package/dist/core/git-worktree-env.js +16 -13
  90. package/dist/core/governance-codes.d.ts +12 -4
  91. package/dist/core/governance-codes.js +16 -4
  92. package/dist/core/hooks.d.ts +12 -4
  93. package/dist/core/hooks.js +11 -4
  94. package/dist/core/host-floor.js +3 -5
  95. package/dist/core/image-admission.d.ts +48 -8
  96. package/dist/core/image-admission.js +35 -4
  97. package/dist/core/input-author.d.ts +36 -0
  98. package/dist/core/input-author.js +39 -0
  99. package/dist/core/leg-identity.d.ts +62 -0
  100. package/dist/core/leg-identity.js +18 -0
  101. package/dist/core/locked-config.d.ts +2 -1
  102. package/dist/core/locked-config.js +5 -3
  103. package/dist/core/lsp.d.ts +5 -3
  104. package/dist/core/lsp.js +3 -2
  105. package/dist/core/mailbox-store.d.ts +85 -10
  106. package/dist/core/mailbox-store.js +31 -10
  107. package/dist/core/mcp-connection-pool.d.ts +6 -20
  108. package/dist/core/mcp-connection-pool.js +10 -28
  109. package/dist/core/mcp-failure.d.ts +76 -15
  110. package/dist/core/mcp-failure.js +60 -33
  111. package/dist/core/mcp-host-seat.d.ts +92 -53
  112. package/dist/core/mcp-host-seat.js +220 -46
  113. package/dist/core/mcp-probe.js +2 -2
  114. package/dist/core/mcp-server-link.d.ts +18 -6
  115. package/dist/core/mcp-server-link.js +19 -4
  116. package/dist/core/mcp-server-spec.d.ts +2 -1
  117. package/dist/core/mcp-session-end.d.ts +1 -2
  118. package/dist/core/mcp-session-end.js +1 -1
  119. package/dist/core/mcp.d.ts +6 -49
  120. package/dist/core/mcp.js +115 -111
  121. package/dist/core/media-byte-cap.d.ts +21 -46
  122. package/dist/core/media-byte-cap.js +55 -55
  123. package/dist/core/member-group.d.ts +7 -0
  124. package/dist/core/member-group.js +35 -0
  125. package/dist/core/memory-engine/consolidation.d.ts +1 -1
  126. package/dist/core/memory-engine/consolidation.js +7 -1
  127. package/dist/core/memory-engine/dual-root.d.ts +31 -0
  128. package/dist/core/memory-engine/dual-root.js +59 -11
  129. package/dist/core/memory-engine/engine.js +27 -24
  130. package/dist/core/memory-engine/file-backend.d.ts +13 -0
  131. package/dist/core/memory-engine/file-backend.js +35 -15
  132. package/dist/core/memory-engine/layout.d.ts +3 -0
  133. package/dist/core/memory-engine/layout.js +13 -3
  134. package/dist/core/memory-engine/memory-deployment.d.ts +110 -0
  135. package/dist/core/memory-engine/memory-deployment.js +182 -0
  136. package/dist/core/memory-engine/sync-client.d.ts +39 -18
  137. package/dist/core/memory-engine/sync-client.js +72 -14
  138. package/dist/core/memory-engine/sync-report.d.ts +7 -4
  139. package/dist/core/memory-engine/sync.d.ts +9 -1
  140. package/dist/core/mode-policy.d.ts +8 -8
  141. package/dist/core/mode-policy.js +7 -5
  142. package/dist/core/mods/agent-stations.d.ts +39 -4
  143. package/dist/core/mods/agent-stations.js +59 -10
  144. package/dist/core/mods/dollar.d.ts +62 -0
  145. package/dist/core/mods/extension-call.d.ts +15 -1
  146. package/dist/core/mods/extension-call.js +7 -2
  147. package/dist/core/mods/kernel/dispatch.d.ts +4 -3
  148. package/dist/core/mods/kernel/dispatch.js +4 -4
  149. package/dist/core/mods/kernel/events.d.ts +4 -1
  150. package/dist/core/mods/kernel/events.js +6 -6
  151. package/dist/core/mods/kernel/registration.d.ts +3 -0
  152. package/dist/core/mods/kernel/registration.js +5 -0
  153. package/dist/core/mods/kernel/site-rules.d.ts +6 -3
  154. package/dist/core/mods/kernel/site-rules.js +10 -2
  155. package/dist/core/mods/session-append.d.ts +115 -0
  156. package/dist/core/mods/session-append.js +311 -0
  157. package/dist/core/mods/session-compact.d.ts +48 -0
  158. package/dist/core/mods/session-compact.js +194 -0
  159. package/dist/core/mods/session-receive.d.ts +93 -0
  160. package/dist/core/mods/session-receive.js +141 -0
  161. package/dist/core/mods/session-send.d.ts +72 -0
  162. package/dist/core/mods/session-send.js +88 -0
  163. package/dist/core/mods/stations.d.ts +38 -16
  164. package/dist/core/mods/stations.js +25 -11
  165. package/dist/core/mods/tool-call.d.ts +2 -0
  166. package/dist/core/mods/tool-call.js +4 -4
  167. package/dist/core/output-style.js +3 -4
  168. package/dist/core/own-property-receipt.d.ts +61 -2
  169. package/dist/core/own-property-receipt.js +42 -2
  170. package/dist/core/park-selfcheck.js +4 -2
  171. package/dist/core/path-identity.d.ts +11 -0
  172. package/dist/core/path-identity.js +4 -0
  173. package/dist/core/path-rule-binding.d.ts +3 -1
  174. package/dist/core/path-rule-binding.js +3 -1
  175. package/dist/core/peer-seat.d.ts +3 -3
  176. package/dist/core/peer-seat.js +20 -8
  177. package/dist/core/permission-rule-consent.d.ts +21 -5
  178. package/dist/core/permission-rule-consent.js +21 -1
  179. package/dist/core/permission-rule-model.d.ts +34 -11
  180. package/dist/core/permission-rule-model.js +47 -10
  181. package/dist/core/permission-rule-org.d.ts +1 -1
  182. package/dist/core/permission-rule-provider.js +4 -1
  183. package/dist/core/permission-rules.d.ts +4 -0
  184. package/dist/core/permission-rules.js +11 -16
  185. package/dist/core/remote-env.d.ts +74 -26
  186. package/dist/core/remote-env.js +20 -0
  187. package/dist/core/retention-policy.d.ts +24 -23
  188. package/dist/core/retention-policy.js +36 -2
  189. package/dist/core/retention.d.ts +4 -1
  190. package/dist/core/retired-keys.d.ts +4 -4
  191. package/dist/core/row-admission.d.ts +10 -0
  192. package/dist/core/row-admission.js +5 -0
  193. package/dist/core/runner/advisor-instructions.d.ts +2 -1
  194. package/dist/core/runner/advisor-instructions.js +2 -1
  195. package/dist/core/runner/announce-once-ledger.d.ts +4 -4
  196. package/dist/core/runner/assemble-result.d.ts +13 -3
  197. package/dist/core/runner/assemble-result.js +12 -7
  198. package/dist/core/runner/caller-roster.d.ts +12 -9
  199. package/dist/core/runner/caller-roster.js +5 -2
  200. package/dist/core/runner/checkpoint-scope.d.ts +16 -1
  201. package/dist/core/runner/checkpoint-scope.js +21 -0
  202. package/dist/core/runner/compact-session.js +14 -2
  203. package/dist/core/runner/compaction-call-options.d.ts +1 -1
  204. package/dist/core/runner/compaction-restate.d.ts +2 -2
  205. package/dist/core/runner/compaction-restate.js +4 -3
  206. package/dist/core/runner/construction-doors.d.ts +2 -2
  207. package/dist/core/runner/construction-doors.js +2 -2
  208. package/dist/core/runner/contracts.d.ts +98 -26
  209. package/dist/core/runner/cross-boundary-lane.d.ts +1 -1
  210. package/dist/core/runner/decide-continuation.d.ts +4 -2
  211. package/dist/core/runner/decide-continuation.js +7 -4
  212. package/dist/core/runner/denial-limit-arms.d.ts +15 -21
  213. package/dist/core/runner/denial-limit-arms.js +17 -10
  214. package/dist/core/runner/expire-settle.d.ts +44 -0
  215. package/dist/core/runner/expire-settle.js +55 -0
  216. package/dist/core/runner/git-status-frame.d.ts +3 -3
  217. package/dist/core/runner/git-status-frame.js +2 -1
  218. package/dist/core/runner/halt-attribution.d.ts +2 -1
  219. package/dist/core/runner/halt-attribution.js +2 -1
  220. package/dist/core/runner/local-claims.d.ts +17 -0
  221. package/dist/core/runner/local-claims.js +18 -0
  222. package/dist/core/runner/media-removed-seat.d.ts +46 -0
  223. package/dist/core/runner/media-removed-seat.js +88 -0
  224. package/dist/core/runner/park-commit.d.ts +2 -2
  225. package/dist/core/runner/permission-rule-lanes.d.ts +5 -1
  226. package/dist/core/runner/permission-rule-lanes.js +28 -9
  227. package/dist/core/runner/person-path-rows.js +1 -1
  228. package/dist/core/runner/placement-fence.d.ts +26 -0
  229. package/dist/core/runner/placement-fence.js +38 -0
  230. package/dist/core/runner/prepare-ask-lane.d.ts +6 -12
  231. package/dist/core/runner/prepare-ask-lane.js +4 -4
  232. package/dist/core/runner/prepare-boundary-parks.d.ts +4 -1
  233. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  234. package/dist/core/runner/prepare-caps-and-workflow.d.ts +2 -0
  235. package/dist/core/runner/prepare-caps-and-workflow.js +1 -0
  236. package/dist/core/runner/prepare-config-doors.js +16 -17
  237. package/dist/core/runner/prepare-context-lane.d.ts +6 -2
  238. package/dist/core/runner/prepare-context-lane.js +13 -13
  239. package/dist/core/runner/prepare-delegation-surface.d.ts +9 -9
  240. package/dist/core/runner/prepare-delegation-surface.js +4 -5
  241. package/dist/core/runner/prepare-execution-env.d.ts +5 -2
  242. package/dist/core/runner/prepare-execution-env.js +7 -4
  243. package/dist/core/runner/prepare-gate-stations.d.ts +19 -14
  244. package/dist/core/runner/prepare-gate-stations.js +6 -4
  245. package/dist/core/runner/prepare-hands-readface.d.ts +5 -5
  246. package/dist/core/runner/prepare-hands-readface.js +4 -4
  247. package/dist/core/runner/prepare-inherited-gate.d.ts +6 -0
  248. package/dist/core/runner/prepare-inherited-gate.js +3 -0
  249. package/dist/core/runner/prepare-lsp.d.ts +3 -0
  250. package/dist/core/runner/prepare-lsp.js +2 -2
  251. package/dist/core/runner/prepare-park-ask.d.ts +5 -2
  252. package/dist/core/runner/prepare-park-ask.js +4 -5
  253. package/dist/core/runner/prepare-policy-chain.d.ts +10 -21
  254. package/dist/core/runner/prepare-policy-chain.js +16 -25
  255. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  256. package/dist/core/runner/prepare-prompt-inputs.d.ts +5 -4
  257. package/dist/core/runner/prepare-prompt-inputs.js +3 -2
  258. package/dist/core/runner/prepare-question-face.d.ts +6 -4
  259. package/dist/core/runner/prepare-question-face.js +2 -2
  260. package/dist/core/runner/prepare-run-refs.d.ts +3 -0
  261. package/dist/core/runner/prepare-run-refs.js +2 -2
  262. package/dist/core/runner/prepare-suspend-saga.d.ts +11 -7
  263. package/dist/core/runner/prepare-suspend-saga.js +17 -7
  264. package/dist/core/runner/prepare-task.d.ts +1 -1
  265. package/dist/core/runner/prepare-task.js +56 -28
  266. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +6 -0
  267. package/dist/core/runner/prepare-tool-disclosure-mount.js +3 -1
  268. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -0
  269. package/dist/core/runner/prepare-wiring-manifest.js +2 -1
  270. package/dist/core/runner/prepare-workspace-restore.d.ts +5 -0
  271. package/dist/core/runner/prepare-workspace-restore.js +10 -6
  272. package/dist/core/runner/read-root-grant.d.ts +1 -1
  273. package/dist/core/runner/read-root-grant.js +2 -1
  274. package/dist/core/runner/resume-admission.d.ts +5 -3
  275. package/dist/core/runner/resume-admission.js +17 -3
  276. package/dist/core/runner/resume-apply.js +3 -1
  277. package/dist/core/runner/resume-claim.d.ts +8 -3
  278. package/dist/core/runner/resume-claim.js +28 -12
  279. package/dist/core/runner/resume-internals-and-config.d.ts +2 -2
  280. package/dist/core/runner/resume-internals-and-config.js +10 -1
  281. package/dist/core/runner/resume-preflight.d.ts +3 -2
  282. package/dist/core/runner/resume-preflight.js +13 -26
  283. package/dist/core/runner/retired-runner-deps.js +2 -0
  284. package/dist/core/runner/run-git-lane.js +2 -1
  285. package/dist/core/runner/run-harness-handlers.js +2 -2
  286. package/dist/core/runner/run-identity-wiring.d.ts +2 -2
  287. package/dist/core/runner/run-identity-wiring.js +14 -5
  288. package/dist/core/runner/run-leg.d.ts +3 -3
  289. package/dist/core/runner/run-leg.js +40 -29
  290. package/dist/core/runner/run-notification-lane.js +20 -2
  291. package/dist/core/runner/run-recovery-lanes.js +3 -2
  292. package/dist/core/runner/run-settle-and-teardown.js +9 -7
  293. package/dist/core/runner/run-telemetry-and-budget-seats.d.ts +1 -1
  294. package/dist/core/runner/run-terminal-adoption.d.ts +1 -1
  295. package/dist/core/runner/run-terminal-adoption.js +26 -17
  296. package/dist/core/runner/run-turn-boundary.js +27 -14
  297. package/dist/core/runner/runtask.d.ts +18 -3
  298. package/dist/core/runner/runtask.js +27 -11
  299. package/dist/core/runner/session-rule-policy.d.ts +1 -1
  300. package/dist/core/runner/session-rule-policy.js +6 -1
  301. package/dist/core/runner/shell-env-withheld.d.ts +1 -1
  302. package/dist/core/runner/stream-halt-verbs.d.ts +1 -14
  303. package/dist/core/runner/stream-halt-verbs.js +4 -3
  304. package/dist/core/runner/stream-reap.d.ts +7 -6
  305. package/dist/core/runner/stream-reap.js +13 -16
  306. package/dist/core/runner/stream-settle-backstop.d.ts +3 -2
  307. package/dist/core/runner/stream-settle-backstop.js +5 -3
  308. package/dist/core/runner/stream-steer-verb.d.ts +5 -2
  309. package/dist/core/runner/stream-steer-verb.js +8 -7
  310. package/dist/core/runner/terminal-account.d.ts +11 -1
  311. package/dist/core/runner/terminal-account.js +20 -0
  312. package/dist/core/runner/terminal-projection.d.ts +8 -2
  313. package/dist/core/runner/terminal-projection.js +2 -2
  314. package/dist/core/runner/tool-disclosure.d.ts +3 -0
  315. package/dist/core/runner/tool-disclosure.js +5 -2
  316. package/dist/core/runner/tool-end-body.d.ts +3 -3
  317. package/dist/core/runner/tool-end-body.js +1 -1
  318. package/dist/core/runner/tool-output-projection.d.ts +3 -3
  319. package/dist/core/runner/tool-output-projection.js +7 -6
  320. package/dist/core/runner/tool-table-view.d.ts +56 -0
  321. package/dist/core/runner/tool-table-view.js +51 -0
  322. package/dist/core/runner/turn-attachments.d.ts +3 -2
  323. package/dist/core/runner/turn-attachments.js +1 -1
  324. package/dist/core/runner/void-verifier-pause.d.ts +33 -0
  325. package/dist/core/runner/void-verifier-pause.js +41 -0
  326. package/dist/core/runner-deps.d.ts +24 -25
  327. package/dist/core/secret-env.d.ts +11 -11
  328. package/dist/core/secret-env.js +8 -9
  329. package/dist/core/session-log-transfer.js +9 -10
  330. package/dist/core/session-policy-store.d.ts +1 -1
  331. package/dist/core/session-policy-store.js +5 -2
  332. package/dist/core/session-reconcile.d.ts +3 -2
  333. package/dist/core/session-reconcile.js +7 -4
  334. package/dist/core/session-store.d.ts +2 -0
  335. package/dist/core/session-store.js +5 -7
  336. package/dist/core/session.d.ts +2 -1
  337. package/dist/core/shell-confinement.d.ts +37 -0
  338. package/dist/core/shell-confinement.js +56 -0
  339. package/dist/core/skill-grant.js +1 -1
  340. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +2 -2
  341. package/dist/core/store-contracts/checkpoint-store-contract.js +15 -2
  342. package/dist/core/store-contracts/file-history-store-contract.d.ts +5 -2
  343. package/dist/core/store-contracts/file-history-store-contract.js +25 -1
  344. package/dist/core/store-contracts/mailbox-store-contract.d.ts +12 -5
  345. package/dist/core/store-contracts/mailbox-store-contract.js +156 -9
  346. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  347. package/dist/core/store-contracts/tool-result-store-contract.js +30 -0
  348. package/dist/core/task-event.d.ts +17 -8
  349. package/dist/core/task-limits.d.ts +5 -0
  350. package/dist/core/task-notification.d.ts +89 -12
  351. package/dist/core/task-notification.js +87 -13
  352. package/dist/core/task-registry-agent.d.ts +5 -43
  353. package/dist/core/task-registry-agent.js +24 -51
  354. package/dist/core/task-registry-monitor.d.ts +1 -1
  355. package/dist/core/task-registry-monitor.js +15 -60
  356. package/dist/core/task-registry-shared.d.ts +15 -112
  357. package/dist/core/task-registry-shared.js +3 -41
  358. package/dist/core/task-registry-workflow.js +4 -21
  359. package/dist/core/task-registry.d.ts +19 -60
  360. package/dist/core/task-registry.js +19 -106
  361. package/dist/core/task-result.d.ts +24 -7
  362. package/dist/core/task-spec-members.d.ts +39 -0
  363. package/dist/core/task-spec-members.js +92 -0
  364. package/dist/core/task-spec.d.ts +10 -10
  365. package/dist/core/task-tool-shape.d.ts +7 -57
  366. package/dist/core/task-tool-shape.js +7 -66
  367. package/dist/core/terminal-cause.d.ts +30 -0
  368. package/dist/core/terminal-cause.js +1 -0
  369. package/dist/core/tool-catalog-entries.js +2 -5
  370. package/dist/core/tool-check-reading.js +16 -10
  371. package/dist/core/tool-conformance.js +1 -2
  372. package/dist/core/tool-errors.d.ts +6 -3
  373. package/dist/core/tool-errors.js +2 -0
  374. package/dist/core/tool-face-reader.js +3 -2
  375. package/dist/core/tool-face.d.ts +2 -3
  376. package/dist/core/tool-name-aliases.d.ts +5 -29
  377. package/dist/core/tool-name-aliases.js +9 -5
  378. package/dist/core/tool-name-readings.d.ts +14 -3
  379. package/dist/core/tool-name-readings.js +2 -0
  380. package/dist/core/tool-policy.d.ts +108 -18
  381. package/dist/core/tool-policy.js +84 -14
  382. package/dist/core/tool-result-store.d.ts +23 -0
  383. package/dist/core/tool-result-store.js +3 -2
  384. package/dist/core/tool-spec.d.ts +19 -6
  385. package/dist/core/trace.d.ts +18 -1
  386. package/dist/core/user-attachment.js +26 -21
  387. package/dist/core/workflow-journal-store.d.ts +1 -1
  388. package/dist/core/workflow-run-store.d.ts +2 -0
  389. package/dist/core/workflow-run-store.js +6 -5
  390. package/dist/core/workflow-settled-run.d.ts +5 -0
  391. package/dist/core/workflow-settled-run.js +7 -0
  392. package/dist/engine/execution-env/node-execution-env.d.ts +34 -9
  393. package/dist/engine/execution-env/node-execution-env.js +213 -21
  394. package/dist/engine/harness/agent-harness.d.ts +65 -18
  395. package/dist/engine/harness/agent-harness.js +90 -23
  396. package/dist/engine/harness/messages.d.ts +4 -3
  397. package/dist/engine/harness/messages.js +2 -2
  398. package/dist/engine/harness/types.d.ts +41 -7
  399. package/dist/engine/llm/media-removed.d.ts +14 -0
  400. package/dist/engine/llm/media-removed.js +9 -0
  401. package/dist/engine/llm/rejected-images.d.ts +35 -25
  402. package/dist/engine/llm/rejected-images.js +59 -10
  403. package/dist/engine/llm/types.d.ts +24 -3
  404. package/dist/engine/llm/types.js +7 -3
  405. package/dist/engine/loop/agent-loop.d.ts +6 -1
  406. package/dist/engine/loop/agent-loop.js +20 -11
  407. package/dist/engine/loop/types.d.ts +12 -3
  408. package/dist/engine/session/import-validate.js +7 -0
  409. package/dist/fixtures/index.d.ts +7 -5
  410. package/dist/fixtures/index.js +5 -3
  411. package/dist/index.d.ts +21 -11
  412. package/dist/index.js +15 -7
  413. package/dist/internal/harness-types.d.ts +2 -0
  414. package/dist/internal/llm.d.ts +2 -1
  415. package/dist/internal/llm.js +1 -0
  416. package/dist/orchestration/goal.d.ts +6 -2
  417. package/dist/orchestration/goal.js +6 -3
  418. package/dist/orchestration/run-workflow-tool.d.ts +11 -17
  419. package/dist/orchestration/run-workflow-tool.js +19 -42
  420. package/dist/orchestration/workflow-governance.d.ts +1 -1
  421. package/dist/orchestration/workflow-types.d.ts +2 -2
  422. package/dist/orchestration/workflow.d.ts +4 -0
  423. package/dist/orchestration/workflow.js +8 -5
  424. package/dist/stores/file/background-agent-store.js +18 -15
  425. package/dist/stores/file/checkpoint-store.js +7 -4
  426. package/dist/stores/file/file-history-store.js +3 -2
  427. package/dist/stores/file/index.d.ts +5 -3
  428. package/dist/stores/file/index.js +23 -8
  429. package/dist/stores/file/ledger-tuning.d.ts +23 -0
  430. package/dist/stores/file/ledger-tuning.js +21 -0
  431. package/dist/stores/file/mailbox-store.js +42 -22
  432. package/dist/stores/file/memory-store.js +3 -2
  433. package/dist/stores/file/permission-rule-adopt.js +24 -21
  434. package/dist/stores/file/permission-rule-store.js +6 -3
  435. package/dist/stores/file/session-policy-store.js +3 -2
  436. package/dist/stores/file/session-store.d.ts +16 -3
  437. package/dist/stores/file/session-store.js +21 -20
  438. package/dist/stores/file/tool-result-store.d.ts +11 -0
  439. package/dist/stores/file/tool-result-store.js +57 -3
  440. package/dist/stores/file/usage-window-store.js +3 -2
  441. package/dist/stores/file/workflow-journal-store.d.ts +0 -2
  442. package/dist/stores/file/workflow-journal-store.js +3 -18
  443. package/dist/stores/file/workflow-run-store.d.ts +1 -1
  444. package/dist/stores/file/workflow-run-store.js +15 -10
  445. package/dist/tools/fs/dead-cwd.d.ts +5 -5
  446. package/dist/tools/fs/dead-cwd.js +4 -11
  447. package/dist/tools/fs/fs-bash-background-text.d.ts +6 -0
  448. package/dist/tools/fs/fs-bash-background-text.js +6 -0
  449. package/dist/tools/fs/fs-bash.d.ts +3 -18
  450. package/dist/tools/fs/fs-bash.js +37 -124
  451. package/dist/tools/fs/fs-pdf.js +8 -6
  452. package/dist/tools/fs/fs-read.js +2 -2
  453. package/dist/tools/fs/fs-shared.d.ts +28 -3
  454. package/dist/tools/fs/fs-shared.js +15 -0
  455. package/dist/tools/fs/index.d.ts +1 -1
  456. package/dist/tools/fs/index.js +4 -14
  457. package/dist/tools/fs/pdf.d.ts +4 -4
  458. package/dist/tools/fs/pdf.js +6 -6
  459. package/dist/tools/fs/read-deny-home.js +8 -1
  460. package/dist/tools/fs/read-deny.d.ts +26 -2
  461. package/dist/tools/fs/read-deny.js +9 -2
  462. package/dist/tools/fs/read-floor.d.ts +13 -5
  463. package/dist/tools/fs/read-floor.js +206 -2
  464. package/dist/tools/fs/search.d.ts +3 -2
  465. package/dist/tools/fs/search.js +6 -6
  466. package/dist/tools/fs/shell-read-establish.js +3 -1
  467. package/dist/tools/fs/shell-read-identity.d.ts +3 -1
  468. package/dist/tools/fs/shell-read-identity.js +4 -2
  469. package/dist/tools/fs/shell-read-judge.d.ts +7 -1
  470. package/dist/tools/fs/shell-read-judge.js +1 -1
  471. package/dist/tools/monitor.d.ts +8 -7
  472. package/dist/tools/monitor.js +12 -10
  473. package/dist/tools/worktree.d.ts +5 -1
  474. package/dist/tools/worktree.js +20 -17
  475. package/package.json +6 -3
  476. package/test/export-surface.snapshot.json +92 -10
  477. package/wire-changes/core-stores-sql@7.61.0.json +480 -0
  478. package/wire-changes/core@7.61.0.json +4405 -0
  479. package/wire-changes/mods-kernel@7.61.0.json +65 -0
  480. package/wire-changes/primitives@7.61.0.json +30 -0
  481. package/dist/core/runner/image-removed-seat.d.ts +0 -12
  482. package/dist/core/runner/image-removed-seat.js +0 -19
@@ -199,8 +199,9 @@ export interface MailboxLease {
199
199
  export interface MailboxAppendMessage {
200
200
  /**
201
201
  * The record's identity, minted by its producer — a re-park of the same message carries the same
202
- * one. While the box HOLDS a record under this id, an append under it is that record: identical on
203
- * every {@link MAILBOX_REPLAY_FACETS} facet ⇒ the held `seq`, nothing written; any facet different ⇒
202
+ * one. While the box holds a record under this id, or has it in its received window
203
+ * ({@link MAILBOX_CONSUMED_ID_WINDOW}), an append under it is that record: identical on every
204
+ * {@link MAILBOX_REPLAY_FACETS} facet ⇒ that record's `seq`, nothing written; any facet different ⇒
204
205
  * refused with {@link MAILBOX_DUPLICATE_RECORD_ID_CODE}. Absent = the producer states no identity and
205
206
  * every append is a new record (its `seq` is all it is known by). Validated by {@link readMailboxRecordId}.
206
207
  */
@@ -215,7 +216,7 @@ export interface MailboxAppendMessage {
215
216
  }
216
217
  /** An `id` that is not a non-empty string of at most {@link MAILBOX_RECORD_ID_MAX_CHARS} characters. */
217
218
  export declare const MAILBOX_INVALID_RECORD_ID_CODE = "mailbox.invalid_record_id";
218
- /** An append under an `id` the box holds, whose record differs from the held one. */
219
+ /** An append under an `id` the box holds or has received, whose record differs from that one. */
219
220
  export declare const MAILBOX_DUPLICATE_RECORD_ID_CODE = "mailbox.duplicate_record_id";
220
221
  export declare const MAILBOX_RECORD_ID_MAX_CHARS = 1024;
221
222
  /**
@@ -224,6 +225,27 @@ export declare const MAILBOX_RECORD_ID_MAX_CHARS = 1024;
224
225
  */
225
226
  export declare const MAILBOX_REPLAY_FACETS: readonly ["from", "content", "hopChain", "peerMeta"];
226
227
  export type MailboxReplayFacet = (typeof MAILBOX_REPLAY_FACETS)[number];
228
+ /**
229
+ * How many id-bearing records a box remembers after consuming them — its RECEIVED WINDOW, kept at exactly this size by
230
+ * every backend (an out-of-repo backend imports the constant, never a copy of the number). An `ack` that deletes
231
+ * id-bearing records enters each one; the window keeps the newest by `seq`; a record with no id never takes a place.
232
+ * `drop` ends the window with the box's lifetime; `reap` keeps it, as it keeps the high-water mark (what it clears was
233
+ * never received).
234
+ */
235
+ export declare const MAILBOX_CONSUMED_ID_WINDOW = 256;
236
+ /** One record of a box's received window: the producer's id, the `seq` the record held, and its
237
+ * {@link mailboxReplayDigests} — what a later append under the id is judged against. */
238
+ export interface MailboxConsumedRecord {
239
+ readonly id: string;
240
+ readonly seq: number;
241
+ readonly digests: Readonly<Record<MailboxReplayFacet, string>>;
242
+ }
243
+ /** One digest per {@link MAILBOX_REPLAY_FACETS} facet (sha-256 of the facet's one spelling): the form a held record, a
244
+ * received one and an incoming append are compared in. */
245
+ export declare function mailboxReplayDigests(record: Partial<Pick<MailboxAppendMessage, MailboxReplayFacet>>): Record<MailboxReplayFacet, string>;
246
+ /** The received window once `removed` (the records an `ack` deleted) entered it — the one fold every bundled backend
247
+ * runs; the result holds the newest {@link MAILBOX_CONSUMED_ID_WINDOW} by `seq`. Module-level, not a root export. */
248
+ export declare function foldMailboxConsumed(window: readonly MailboxConsumedRecord[], removed: readonly MailboxMessage[]): MailboxConsumedRecord[];
227
249
  /** Validate a record id at `append`, before any side effect. `undefined` = no identity stated. */
228
250
  export declare function readMailboxRecordId(raw: unknown): string | undefined;
229
251
  /**
@@ -234,15 +256,20 @@ export declare function readMailboxRecordId(raw: unknown): string | undefined;
234
256
  export declare function readMailboxAppend(msg: MailboxAppendMessage): MailboxAppendMessage;
235
257
  /**
236
258
  * THE append-by-identity judgment, the one every backend runs inside its write critical section
237
- * (with `msg` already validated: `id` by {@link readMailboxRecordId}, `peerMeta` by {@link readMailboxPeerMeta}).
238
- * Returns the held record's `seq` when `msg` replays it (the caller writes nothing), `undefined` when the
239
- * box holds no record under `msg.id` (the caller appends), and throws {@link MAILBOX_DUPLICATE_RECORD_ID_CODE}
259
+ * (with `msg` already validated: `id` by {@link readMailboxRecordId}, `peerMeta` by {@link readMailboxPeerMeta}),
260
+ * over the box's two sets: the records it HOLDS and its received window ({@link MAILBOX_CONSUMED_ID_WINDOW}).
261
+ * Returns that record's `seq` when `msg` replays it (the caller writes nothing), `undefined` when neither set
262
+ * has a record under `msg.id` (the caller appends), and throws {@link MAILBOX_DUPLICATE_RECORD_ID_CODE}
240
263
  * naming the facets when a different record claims the id. A third-party backend calls this function too.
241
264
  */
242
- export declare function judgeMailboxAppendById(held: readonly MailboxMessage[], msg: MailboxAppendMessage): number | undefined;
265
+ export declare function judgeMailboxAppendById(box: {
266
+ readonly held: readonly MailboxMessage[];
267
+ readonly consumed: readonly MailboxConsumedRecord[];
268
+ }, msg: MailboxAppendMessage): number | undefined;
243
269
  /**
244
270
  * The pluggable mailbox seam (design/151 §7.1). Contract notes for implementations (file/pg):
245
- * - `append` is durable-first (a returned seq means the message survives a crash); seq is monotonic
271
+ * - `append` is durable-first (a returned seq means the box has taken the message: it survives a crash, still
272
+ * parked or — an id-bearing replay — already consumed inside the received window); seq is monotonic
246
273
  * per (scope, handle) and never reused WITHIN a box's lifetime (across lease/ack cycles the
247
274
  * high-water mark persists). `drop` ENDS the lifetime — a later rebuild restarts at 1 (server[1523]
248
275
  * 定谳: the row died with the box, dedup keys carry the handle, and a* handles are 64-bit-random).
@@ -281,7 +308,9 @@ export declare function judgeMailboxAppendById(held: readonly MailboxMessage[],
281
308
  * the box). A backend with NO view of that
282
309
  * lifecycle (the two bundled ones, the CC inbox adapter) has nothing to refuse and keeps accepting
283
310
  * — the clause fixes the SPELLING of the refusal, so a deployment reads one code instead of a
284
- * per-backend dialect. Acceptance kit: `mailboxTombstonedRecipientContract`.
311
+ * per-backend dialect. A backend that keeps the state writes it through its own
312
+ * `retireRecipient` and lists it through `listRetiredRecipients` (one optional pair); a backend
313
+ * without the pair has its box dropped instead. Acceptance kit: `mailboxTombstonedRecipientContract`.
285
314
  * - PEER METADATA (design/385, additive): `append` takes an optional typed `peerMeta`; a backend
286
315
  * persists it and hands it back on `claimLease` byte-for-byte (a detached copy), absent stays absent,
287
316
  * and a malformed value is REFUSED with `"mailbox.invalid_peer_meta"` before any side effect
@@ -293,7 +322,13 @@ export declare function judgeMailboxAppendById(held: readonly MailboxMessage[],
293
322
  * written), `"mailbox.duplicate_record_id"` for a different one — atomically with the seq allocation;
294
323
  * a malformed id is refused with `"mailbox.invalid_record_id"` before any side effect. This is what
295
324
  * makes re-asking a store whose reply was lost safe: a rejected append is not proof that nothing was
296
- * written. The box answers for what it HOLDS — once a record is acked its id is free again.
325
+ * written. The box answers for what it has RECEIVED, not only for what it holds: `ack` enters every
326
+ * id-bearing record it deletes into the box's received window — exactly the newest
327
+ * {@link MAILBOX_CONSUMED_ID_WINDOW} by seq, each kept as `{ id, seq, digests }`
328
+ * ({@link MailboxConsumedRecord}, {@link mailboxReplayDigests}) — persisted and shared like the
329
+ * high-water mark, and the same judgment answers from it: the consumed record's `seq` (nothing written),
330
+ * or the refusal. `drop` clears the window; `reap` keeps it. Acceptance: the window cases of
331
+ * `mailboxStoreContract` (T1) and `mailboxCrossProcessContract` (T2).
297
332
  * - CROSS-PROCESS SAFETY (design/385, optional capability declared on the store): the session-box
298
333
  * drain shares ONE box between several OS processes. A backend that is correct under that sharing —
299
334
  * seq minted once across processes, lease/ack never crossing, one process's housekeeping never
@@ -355,7 +390,45 @@ export interface MailboxStore {
355
390
  reap(scope: string, now: number, opts?: {
356
391
  maxAgeMs?: number;
357
392
  }): Promise<number>;
393
+ /**
394
+ * Put `(scope, handle)` into the PRE-DELETE state — the tombstone `append` refuses by
395
+ * (`"mailbox.recipient_tombstoned"`). Marks only: the messages already parked, their seqs and any live lease are
396
+ * untouched, so a deletion cascade retires the recipient first and drops the box after. Repeating it updates the
397
+ * tombstone's time and label. The tombstone lives as long as the box: `drop` removes both, so an id registered
398
+ * again later is a new recipient (there is no un-retire verb, and none is needed). `at` is the retirement time
399
+ * (epoch ms); `label` the recipient's name before it went, when it had one.
400
+ *
401
+ * `true` = a tombstone was written. `false` = none was, and the recipient is still refused: the store keeps no
402
+ * pre-delete state for this box and dropped it instead, or its key judge does not admit this handle (an `append`
403
+ * to it is refused by that judge's own sentence).
404
+ *
405
+ * Optional, and one capability with {@link listRetiredRecipients}: a store carries both or neither (read through
406
+ * {@link mailboxRecipientLifecycleOf}, which refuses half). Absent ⇒ the store has no view of its recipients'
407
+ * lifecycle; a deletion cascade drops the box. Acceptance kit: `mailboxTombstonedRecipientContract`.
408
+ */
409
+ retireRecipient?(scope: string, handle: string, at: number, label?: string): Promise<boolean>;
410
+ /** The tombstones under `scope` whose handle starts with `handlePrefix` — what a directory shows as a recipient
411
+ * being deleted. Optional, one capability with {@link retireRecipient}. */
412
+ listRetiredRecipients?(scope: string, handlePrefix: string): Promise<readonly MailboxRecipientTombstone[]>;
413
+ }
414
+ /** One retired recipient ({@link MailboxStore.listRetiredRecipients}). */
415
+ export interface MailboxRecipientTombstone {
416
+ /** The box handle (a session box is `session.<id>`). */
417
+ readonly handle: string;
418
+ /** When it was retired (epoch ms). */
419
+ readonly retiredAt: number;
420
+ /** Its name before it went; absent when it had none. */
421
+ readonly label?: string;
358
422
  }
423
+ /**
424
+ * The store's recipient-lifecycle pair, read as one capability: `undefined` when the store carries neither member;
425
+ * both, bound to the store, when it carries both; a refusal (`config.invalid_argument`) naming the missing one when
426
+ * it carries one — half the pair is not a smaller capability.
427
+ */
428
+ export declare function mailboxRecipientLifecycleOf(store: MailboxStore): Readonly<{
429
+ retireRecipient: NonNullable<MailboxStore["retireRecipient"]>;
430
+ listRetiredRecipients: NonNullable<MailboxStore["listRetiredRecipients"]>;
431
+ }> | undefined;
359
432
  /** The lane-mount verdict on a backend's cross-process declaration. */
360
433
  export type MailboxCrossProcessVerdict = {
361
434
  ok: true;
@@ -386,6 +459,8 @@ export declare function detachMailboxMessage(m: MailboxMessage): MailboxMessage;
386
459
  * {@link import("./background-agent-store.js").InMemoryBackgroundAgentStore}: not default-mounted,
387
460
  * detached copies at both boundaries, single-event-loop atomicity.
388
461
  */
462
+ /** The retention knobs a mailbox `reap` takes (an age sweep only: a box is cleared, never trimmed by count). */
463
+ export declare const MAILBOX_REAP_KNOBS: readonly ["maxAgeMs"];
389
464
  export declare class InMemoryMailboxStore implements MailboxStore {
390
465
  /** Process-local by construction (a Map): never a cross-process box, said so explicitly. */
391
466
  readonly crossProcessSafe = false;
@@ -1,4 +1,6 @@
1
- import { assertRetentionPolicy } from "./retention-policy.js";
1
+ import { createHash } from "node:crypto";
2
+ import { receiveRetentionPolicy } from "./retention-policy.js";
3
+ import { readMemberGroup } from "./member-group.js";
2
4
  export const MAILBOX_DECISIONS = Object.freeze(["held", "approved", "delivered", "denied", "expired", "refused", "dropped"]);
3
5
  export function readStoredMailboxDecision(raw) {
4
6
  if (raw === undefined)
@@ -154,6 +156,18 @@ export const MAILBOX_INVALID_RECORD_ID_CODE = "mailbox.invalid_record_id";
154
156
  export const MAILBOX_DUPLICATE_RECORD_ID_CODE = "mailbox.duplicate_record_id";
155
157
  export const MAILBOX_RECORD_ID_MAX_CHARS = 1024;
156
158
  export const MAILBOX_REPLAY_FACETS = Object.freeze(["from", "content", "hopChain", "peerMeta"]);
159
+ export const MAILBOX_CONSUMED_ID_WINDOW = 256;
160
+ export function mailboxReplayDigests(record) {
161
+ const out = {};
162
+ for (const f of MAILBOX_REPLAY_FACETS)
163
+ out[f] = createHash("sha256").update(facetSpelling(record[f])).digest("hex");
164
+ return out;
165
+ }
166
+ export function foldMailboxConsumed(window, removed) {
167
+ const entered = removed.flatMap((m) => (m.id !== undefined ? [{ id: m.id, seq: m.seq, digests: mailboxReplayDigests(m) }] : []));
168
+ const next = [...window, ...entered].sort((a, b) => a.seq - b.seq);
169
+ return next.length > MAILBOX_CONSUMED_ID_WINDOW ? next.slice(next.length - MAILBOX_CONSUMED_ID_WINDOW) : next;
170
+ }
157
171
  export function readMailboxRecordId(raw) {
158
172
  if (raw === undefined)
159
173
  return undefined;
@@ -187,16 +201,21 @@ function facetSpelling(v) {
187
201
  return `[${Array.from(v, facetSpelling).join(",")}]`;
188
202
  return `{${Object.keys(v).filter((k) => v[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${facetSpelling(v[k])}`).join(",")}}`;
189
203
  }
190
- export function judgeMailboxAppendById(held, msg) {
204
+ export function judgeMailboxAppendById(box, msg) {
191
205
  if (msg.id === undefined)
192
206
  return undefined;
193
- const prior = held.find((m) => m.id === msg.id);
207
+ const holding = box.held.find((m) => m.id === msg.id);
208
+ const prior = holding !== undefined ? { seq: holding.seq, digests: mailboxReplayDigests(holding) } : box.consumed.find((c) => c.id === msg.id);
194
209
  if (prior === undefined)
195
210
  return undefined;
196
- const differs = MAILBOX_REPLAY_FACETS.filter((f) => facetSpelling(prior[f]) !== facetSpelling(msg[f]));
211
+ const asked = mailboxReplayDigests(msg);
212
+ const differs = MAILBOX_REPLAY_FACETS.filter((f) => prior.digests[f] !== asked[f]);
197
213
  if (differs.length === 0)
198
214
  return prior.seq;
199
- throw new MailboxStoreError(MAILBOX_DUPLICATE_RECORD_ID_CODE, `MailboxStore.append: the box already holds a different record under this id (it differs in: ${differs.join(", ")}) — a new message takes a new id; an identical repeat would have been a replay`);
215
+ throw new MailboxStoreError(MAILBOX_DUPLICATE_RECORD_ID_CODE, `MailboxStore.append: the box already ${holding !== undefined ? "holds" : "received"} a different record under this id (it differs in: ${differs.join(", ")}) — a new message takes a new id; an identical repeat would have been a replay`);
216
+ }
217
+ export function mailboxRecipientLifecycleOf(store) {
218
+ return readMemberGroup("MailboxStore", store, ["retireRecipient", "listRetiredRecipients"]);
200
219
  }
201
220
  export function mailboxCrossProcessMountVerdict(store) {
202
221
  const declared = store.crossProcessSafe;
@@ -226,6 +245,7 @@ export function detachMailboxMessage(m) {
226
245
  ...(m.peerMeta !== undefined ? { peerMeta: cloneMailboxPeerMeta(m.peerMeta) } : {}),
227
246
  };
228
247
  }
248
+ export const MAILBOX_REAP_KNOBS = Object.freeze(["maxAgeMs"]);
229
249
  export class InMemoryMailboxStore {
230
250
  crossProcessSafe = false;
231
251
  boxes = new Map();
@@ -239,7 +259,7 @@ export class InMemoryMailboxStore {
239
259
  const k = this.key(scope, handle);
240
260
  let b = this.boxes.get(k);
241
261
  if (!b) {
242
- b = { scope, messages: [], nextSeq: 1 };
262
+ b = { scope, messages: [], nextSeq: 1, consumed: [] };
243
263
  this.boxes.set(k, b);
244
264
  }
245
265
  return b;
@@ -249,7 +269,7 @@ export class InMemoryMailboxStore {
249
269
  throw new Error("MailboxStore.append: refusing a message without a scope");
250
270
  const record = readMailboxAppend(msg);
251
271
  const b = this.box(scope, handle);
252
- const held = judgeMailboxAppendById(b.messages, record);
272
+ const held = judgeMailboxAppendById({ held: b.messages, consumed: b.consumed }, record);
253
273
  if (held !== undefined)
254
274
  return held;
255
275
  const seq = b.nextSeq++;
@@ -272,6 +292,7 @@ export class InMemoryMailboxStore {
272
292
  return { acked: false };
273
293
  if (b.lease === undefined || b.lease.owner !== owner)
274
294
  return { acked: false };
295
+ b.consumed = foldMailboxConsumed(b.consumed, b.messages.filter((m) => m.seq <= upToSeq));
275
296
  b.messages = b.messages.filter((m) => m.seq > upToSeq);
276
297
  if (b.lease.maxSeq <= upToSeq)
277
298
  b.lease = undefined;
@@ -299,15 +320,15 @@ export class InMemoryMailboxStore {
299
320
  this.boxes.delete(this.key(scope, handle));
300
321
  }
301
322
  async reap(scope, now, opts) {
302
- assertRetentionPolicy("MailboxStore.reap", opts);
303
- if (opts?.maxAgeMs === undefined)
323
+ const policy = receiveRetentionPolicy("MailboxStore.reap", opts, MAILBOX_REAP_KNOBS);
324
+ if (policy.maxAgeMs === undefined)
304
325
  return 0;
305
326
  let dropped = 0;
306
327
  for (const b of this.boxes.values()) {
307
328
  if (b.scope !== scope)
308
329
  continue;
309
330
  const newest = newestSentAt(b.messages);
310
- if (newest !== undefined && newest < now - opts.maxAgeMs) {
331
+ if (newest !== undefined && newest < now - policy.maxAgeMs) {
311
332
  b.messages = [];
312
333
  b.lease = undefined;
313
334
  dropped++;
@@ -19,32 +19,18 @@
19
19
  * peer seat's, asked under this same identity, so every holder of a connection sends what the one seat answers for it. A server that opted in to elicitation never enters the pool — the
20
20
  * answer to its questions belongs to the leg that is waiting on it.
21
21
  */
22
- import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
22
+ import type { Client } from "@modelcontextprotocol/client";
23
23
  import { ConnectionListing, type LenientListedTool } from "./mcp-server-link.js";
24
24
  import type { McpServerSpec } from "./mcp-server-spec.js";
25
- /** The slice of a listed tool the SDK client caches per connection (its output validator, its task-support flags). */
26
- export interface McpToolMeta {
27
- readonly name: string;
28
- readonly outputSchema?: unknown;
29
- readonly execution?: unknown;
30
- }
31
- /** Records one `tools/list` result on a pooled connection (see {@link McpLease.openListing}): the tools the leg mounted from it, of which
32
- * `retained` names the ones the listing did not return (an incomplete walk keeps them mounted) — those join the membership only. */
33
- export type McpListingWriter = (tools: ReadonlyArray<McpToolMeta>, apply: (all: McpToolMeta[]) => void, retained?: ReadonlySet<string>) => void;
25
+ /** The engine's own dial of `client` under `key` (the key {@link McpConnectionPool.keyOf} gives its declaration): the one connection a pool
26
+ * entry for that key may take. */
27
+ export declare function recordEngineDial(client: Client, key: string): void;
34
28
  /** One leg's hold on a pooled connection. */
35
29
  export interface McpLease {
36
30
  readonly client: Client;
37
- /** The connection's listing, one record shared by every holder (mcp-server-link.ts `ConnectionListing`). */
31
+ /** The connection's listing, one record shared by every holder (mcp-server-link.ts `ConnectionListing`): what every holder's tools are
32
+ * checked against and what their calls hand the SDK as the tool's definition, each through its own leg's intake. */
38
33
  readonly listing: ConnectionListing<LenientListedTool>;
39
- /**
40
- * Open a `tools/list` round trip on the connection — call it BEFORE the request. The returned writer records the result twice over:
41
- * as the connection's metadata for each listed tool, at this listing's version (its place in the order listings were opened on the
42
- * connection: a listing opened earlier never overwrites what a later one wrote, whichever answer arrives first; an entry the listing
43
- * did not return — `retained` — writes no record), and as THIS leg's membership (the names it mounted). It then rewrites the client's per-connection tool cache with the current metadata of every name
44
- * some holder mounted: the SDK clears and refills that cache on each write, so a leg that mounted a subset must not erase what its
45
- * siblings' tools need. A release changes the membership only and rewrites the cache from the same metadata.
46
- */
47
- openListing(): McpListingWriter;
48
34
  /** Run `fn` when the connection closes under the lease (the server died, the transport dropped). Never called for this lease's own release. */
49
35
  onClose(fn: () => void): void;
50
36
  /** Give the hold back; the last holder's release closes the connection. Idempotent. */
@@ -1,6 +1,10 @@
1
1
  import { canonicalize } from "./canonical-json.js";
2
2
  import { ConnectionListing } from "./mcp-server-link.js";
3
3
  import { carrierOf } from "./peer-seat.js";
4
+ const ENGINE_DIALS = new WeakMap();
5
+ export function recordEngineDial(client, key) {
6
+ ENGINE_DIALS.set(client, { key, entered: false });
7
+ }
4
8
  export class McpConnectionPool {
5
9
  entries = new Map();
6
10
  dialing = new Map();
@@ -105,7 +109,12 @@ export class McpConnectionPool {
105
109
  }
106
110
  async dialNew(key, generation, dial) {
107
111
  const client = await dial();
108
- const entry = { client, listing: new ConnectionListing(), refs: 0, listeners: new Set(), holders: new Map(), meta: new Map(), nextVersion: 0, current: true, closed: false };
112
+ const dialled = ENGINE_DIALS.get(client);
113
+ if (dialled === undefined || dialled.key !== key || dialled.entered) {
114
+ throw Object.assign(new Error("McpConnectionPool: the dial answered a connection the engine did not dial for this declaration (a client built elsewhere, dialled for another declaration or principal, or already held by a pool entry) — refused, the pool keeps nothing of it; the pool holds only connections the engine dials itself"), { code: "config.mcp_pool_foreign_connection" });
115
+ }
116
+ dialled.entered = true;
117
+ const entry = { client, listing: new ConnectionListing(), refs: 0, listeners: new Set(), current: true, closed: false };
109
118
  client.onclose = () => {
110
119
  entry.closed = true;
111
120
  if (this.entries.get(key) === entry)
@@ -128,10 +137,6 @@ export class McpConnectionPool {
128
137
  entry.refs++;
129
138
  const mine = new Set();
130
139
  let released = false;
131
- const cached = () => {
132
- const held = new Set([...entry.holders.values()].flat());
133
- return [...entry.meta].filter(([name]) => held.has(name)).map(([, r]) => r.tool);
134
- };
135
140
  const lease = {
136
141
  client: entry.client,
137
142
  listing: entry.listing,
@@ -139,27 +144,6 @@ export class McpConnectionPool {
139
144
  mine.add(fn);
140
145
  entry.listeners.add(fn);
141
146
  },
142
- openListing: () => {
143
- const version = entry.nextVersion++;
144
- return (tools, apply, retained) => {
145
- for (const tool of tools) {
146
- const prior = entry.meta.get(tool.name);
147
- if (retained?.has(tool.name) === true) {
148
- if (prior === undefined)
149
- entry.meta.set(tool.name, { tool, version: -1 });
150
- continue;
151
- }
152
- if (prior !== undefined && prior.version > version)
153
- continue;
154
- entry.meta.delete(tool.name);
155
- entry.meta.set(tool.name, { tool, version });
156
- }
157
- if (!released)
158
- entry.holders.set(lease, tools.map((t) => t.name));
159
- entry.apply = apply;
160
- apply(cached());
161
- };
162
- },
163
147
  release: async () => {
164
148
  if (released)
165
149
  return;
@@ -167,8 +151,6 @@ export class McpConnectionPool {
167
151
  for (const fn of mine)
168
152
  entry.listeners.delete(fn);
169
153
  entry.refs--;
170
- if (entry.holders.delete(lease) && entry.refs > 0)
171
- entry.apply?.(cached());
172
154
  if (entry.refs > 0)
173
155
  return;
174
156
  entry.current = false;
@@ -8,7 +8,7 @@ import type { McpTransportKind } from "./mcp-server-spec.js";
8
8
  * request: the request provably never left;
9
9
  * · `connection_failed` — any other errno / undici code on the cause chain (a reset or a timeout
10
10
  * mid-exchange): the request may have run;
11
- * · `connection_closed` — the SDK reported the transport closed (`McpError` `ConnectionClosed`): in
11
+ * · `connection_closed` — the SDK reported the transport closed (`SdkError` `ConnectionClosed`): in
12
12
  * flight the fate is unknowable, and for a server already known dead the
13
13
  * request was never attempted — the two are told apart by `delivered`;
14
14
  * · `unauthorized` — the principal must authorize this server before it serves them: the endpoint
@@ -31,9 +31,11 @@ import type { McpTransportKind } from "./mcp-server-spec.js";
31
31
  * answer in time, or answered something the engine cannot carry): that request
32
32
  * was not sent — a fault for the deployment to fix, not an outage of the server;
33
33
  * · `host_refused` — the host seat of a host-supplied transport (mcp-host-seat.ts) did not hand the request to the
34
- * remote: nothing ran, and nothing is said about whether the remote can be reached;
34
+ * remote, or handed its dial no pipe the engine could take (it said so, or what it handed is no
35
+ * transport or was already taken): nothing ran, and nothing is said about whether the remote can be
36
+ * reached;
35
37
  * · `unknown` — the thrown value carried no structure this table reads, or the host seat took the request
36
- * and cannot tell how it ended.
38
+ * and cannot tell how it ended (said at the dial, nothing of the caller's was sent either way).
37
39
  */
38
40
  export declare const MCP_FAILURE_KINDS: readonly ["connect_refused", "connection_failed", "connection_closed", "unauthorized", "http_status", "not_mcp_response", "spawn_failed", "timeout", "protocol", "invalid_config", "credential_unavailable", "host_refused", "unknown"];
39
41
  export type McpFailureKind = (typeof MCP_FAILURE_KINDS)[number];
@@ -240,16 +242,74 @@ export declare function failureFields(of: McpFailure | Partial<McpFailureFields>
240
242
  */
241
243
  export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;
242
244
  /** What a row reads OFF the thrown value: the failure's class, the status the `http_status` class carries, the authorization fact
243
- * the `unauthorized` class carries, and `unsent` — the thrown value is the engine's OWN refusal to send (the peer seat did not
244
- * furnish the request: {@link PeerSeatFailure}), a structural fact about our side of the exchange that makes the verdict `"no"`
245
- * whatever the class. A row does NOT write the delivery verdict — that follows from the kind, `unsent` and the SITE, in one place
246
- * ({@link DELIVERED_BY_KIND} + {@link classifyMcpFailure}), so a row cannot spell it wrong. */
245
+ * the `unauthorized` class carries, and `unsent` — the thrown value is a refusal on THIS side to send (the peer seat did not
246
+ * furnish the request: {@link PeerSeatFailure}; the SDK refused it before anything reached the transport: {@link SDK_ERROR_READINGS}),
247
+ * a structural fact about our side of the exchange that makes the verdict `"no"` whatever the class. A row does NOT write the delivery
248
+ * verdict — that follows from the kind, `unsent` and the SITE, in one place ({@link DELIVERED_BY_KIND} + {@link classifyMcpFailure}),
249
+ * so a row cannot spell it wrong. */
247
250
  export type McpFailureClass = {
248
251
  kind: McpFailureKind;
249
252
  httpStatus?: number;
250
253
  authorization?: McpAuthorization;
251
254
  unsent?: true;
252
255
  };
256
+ export declare const SDK_ERROR_READINGS: {
257
+ readonly NOT_CONNECTED: {
258
+ readonly kind: "connection_closed";
259
+ readonly unsent: true;
260
+ };
261
+ readonly ALREADY_CONNECTED: {
262
+ readonly kind: "unknown";
263
+ };
264
+ readonly NOT_INITIALIZED: {
265
+ readonly kind: "unknown";
266
+ };
267
+ readonly CAPABILITY_NOT_SUPPORTED: {
268
+ readonly kind: "unknown";
269
+ };
270
+ readonly REQUEST_TIMEOUT: {
271
+ readonly kind: "timeout";
272
+ };
273
+ readonly CONNECTION_CLOSED: {
274
+ readonly kind: "connection_closed";
275
+ };
276
+ readonly SEND_FAILED: {
277
+ readonly kind: "unknown";
278
+ };
279
+ readonly INVALID_RESULT: {
280
+ readonly kind: "protocol";
281
+ };
282
+ readonly UNSUPPORTED_RESULT_TYPE: {
283
+ readonly kind: "protocol";
284
+ };
285
+ readonly INPUT_REQUIRED_ROUNDS_EXCEEDED: {
286
+ readonly kind: "protocol";
287
+ };
288
+ readonly LIST_PAGINATION_EXCEEDED: {
289
+ readonly kind: "protocol";
290
+ };
291
+ readonly METHOD_NOT_SUPPORTED_BY_PROTOCOL_VERSION: {
292
+ readonly kind: "protocol";
293
+ readonly unsent: true;
294
+ };
295
+ readonly ERA_NEGOTIATION_FAILED: {
296
+ readonly kind: "unknown";
297
+ };
298
+ readonly CLIENT_HTTP_NOT_IMPLEMENTED: "status";
299
+ readonly CLIENT_HTTP_AUTHENTICATION: {
300
+ readonly kind: "unauthorized";
301
+ readonly reason: "rejected";
302
+ };
303
+ readonly CLIENT_HTTP_FORBIDDEN: {
304
+ readonly kind: "unauthorized";
305
+ readonly reason: "scope";
306
+ };
307
+ readonly CLIENT_HTTP_UNEXPECTED_CONTENT: {
308
+ readonly kind: "not_mcp_response";
309
+ };
310
+ readonly CLIENT_HTTP_FAILED_TO_OPEN_STREAM: "status";
311
+ readonly CLIENT_HTTP_FAILED_TO_TERMINATE_SESSION: "status";
312
+ };
253
313
  /** One row of the classifier: `when` reads structure only; `reads` names the class it saw. */
254
314
  export interface McpFailureRule {
255
315
  /** The row's name, for the discrimination pins (one pin per row) and for a reader of a verdict. */
@@ -259,10 +319,11 @@ export interface McpFailureRule {
259
319
  }
260
320
  /**
261
321
  * The ORDERED classifier. First match wins; the final row matches everything. The order is part of
262
- * the contract — the SDK's typed errors go first because they are an answer FROM the exchange (an
263
- * McpError is never a transport failure, whatever its text says), then the HTTP transport's typed
264
- * error, then the cause-chain codes from most specific (a configuration fault, a spawn) to least
265
- * (a connect-phase errno, any other network code).
322
+ * the contract — this side's own refusals first (the peer seat's; the request fetch's reading of a
323
+ * refused authorization), then the SDK's typed errors, because they say where the failure arose (a
324
+ * `ProtocolError` is never a transport failure, whatever its text says; an `SdkError` reads by its code),
325
+ * then the cause-chain codes from most specific (a configuration fault, a spawn) to least (a
326
+ * connect-phase errno, any other network code).
266
327
  */
267
328
  export declare const FAILURE_CLASSIFIER: ReadonlyArray<McpFailureRule>;
268
329
  /**
@@ -291,21 +352,21 @@ export declare function readMcpFailure(err: unknown, at: McpFailureSite): {
291
352
  export interface McpUnavailableEntry extends AnnouncedMcpFailure {
292
353
  authorization?: McpAuthorization;
293
354
  }
294
- /** Where the user authorizes, as every model-facing line names it: the seat's URL, or the deployment's connector settings. */
355
+ /** Where the user authorizes, as every model-facing line names it: the seat's URL when the seat gave one, else only that none was given. */
295
356
  export declare function whereToAuthorize(authorizeUrl: string | undefined): string;
296
357
  /**
297
358
  * The `mcp_unavailable` frame's needs-authorization arm — the servers among `entries` whose failure record carries `authorization`, or
298
359
  * `undefined` when there are none. CC 2.1.309's arm, minted as `needsAuthMcpServers` (cli309.js:265582), read back as `needsAuthMcpServers` (cli309.js:267398),
299
360
  * worded (cli309.js:267399) "The following MCP servers require authentication before their tools can be used" — ahead of the
300
361
  * failed-to-connect arm; this engine never runs an authorization flow itself, so it is always the reference's cannot-start-the-flow form.
301
- * `<where>` is the deployment seat's `authorizeUrl` when it gave one (listed beside the server), else the connector settings; no error
362
+ * `<where>` is the deployment seat's `authorizeUrl` when it gave one (listed beside the server), else only the fact that none was given; no error
302
363
  * text rides it (the fact is the record's). At most `max` servers are named, the rest counted.
303
364
  */
304
365
  export declare function needsAuthorizationArm(entries: readonly McpUnavailableEntry[], max: number): string | undefined;
305
366
  /**
306
367
  * The model's line for a request refused as `unauthorized` — the call-time twin of the needs-authorization arm the `mcp_unavailable`
307
368
  * frame carries for a server that could not mount (turn-attachments.ts): who must act (the user), where ({@link whereToAuthorize}: the
308
- * seat's URL only), what not to ask for, and the delivery tail (`writeTail`, the caller's write-class sentence) the verdict owes. A 401
369
+ * seat's URL, or that none was given), what not to ask for, and the delivery tail (`writeTail`, the caller's write-class sentence) the verdict owes. A 401
309
370
  * after which the deployment answered another credential that no request has carried yet (`renewed`: the first attempt, not sent again)
310
371
  * may pass on a new call: the line says so, and that only a refusal of that call too is the user's — a seat that answers a fresh
311
372
  * credential every time still reaches the user. A re-send refused again is the plain line.
@@ -314,7 +375,7 @@ export declare function unauthorizedLine(what: string, serverLabel: string, a: M
314
375
  /**
315
376
  * What a transport-level HTTP failure can be said to be, in words for a model-facing line: the
316
377
  * condition to name, and the delivery verdict. `undefined` for every failure that is NOT of the HTTP
317
- * transport family (an McpError is an answer FROM the server; a bare error with no structure is
378
+ * transport family (a ProtocolError is an answer FROM the server; a bare error with no structure is
318
379
  * `unknown` and gets no transport story). Shared with the A2A client leg, which faces the SAME `fetch`
319
380
  * layer and owes the same outcome contract — one classifier, so the two protocols cannot drift on what
320
381
  * "the request never reached them" means.