@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
@@ -1,20 +1,28 @@
1
1
  import type { DocumentContent, ImageContent } from "../internal/llm.js";
2
2
  import type { ImageDimensions, ImageDownsampler } from "./image-downsample.js";
3
- import { type MediaBlock } from "./media-byte-cap.js";
3
+ import type { MediaBlock } from "./media-byte-cap.js";
4
4
  /** Max raw size sent whole as a document block (CC `PDF_TARGET_RAW_SIZE`). */
5
5
  export declare const PDF_TARGET_RAW_SIZE: number;
6
6
  /**
7
7
  * Every number an image passes on its way to the model, in one table — the admission and its processor read it, and so
8
8
  * does every carrier that words a refusal; a downstream that bounds an image by the same limit reads the same field.
9
- * - `hard`: what refuses. `formats` (the header rows above), `readBytes` (the raw read cap — larger when a processor can
10
- * shrink what was read; the 64 MiB bound is an OOM sanity bound, CC reads the file whole), `urlBytes` (a fetched
11
- * image's body), `rejectEdge` (the longest edge the bytes that ship may state — `fI` (cli309.js:253044), the 2000 box,
12
- * its no-flag reject width), `imageBase64Chars` (the provider's single-image limit, on the base64 length — CC `fI`
13
- * `maxBase64Size`).
9
+ * - `hard`: what refuses. `formats` (the header rows above), `readBytes` (the raw read cap — without a processor the bytes
10
+ * ship as they are, so the cap is the raw size whose base64 fits `imageBase64Chars`, the one bound that binds there;
11
+ * with one it is larger, since the processor shrinks what was read, and the 64 MiB bound is an OOM sanity bound, CC
12
+ * reads the file whole), `urlBytes` (a fetched image's body), `rejectEdge` (the longest edge the bytes that ship may
13
+ * state — `fI` (cli309.js:253044), the 2000 box, its no-flag reject width), `imageBase64Chars` (the provider's
14
+ * single-image limit, on the base64 length — CC `fI` `maxBase64Size`).
14
15
  * - `soft`: what the processor aims at, best effort. `frameEdge` and `rawBytes` are the frame ladder's box and byte rung
15
16
  * (CC `fI` `maxWidth` / `targetRawSize`: 3.75 MB raw = 5 MiB base64); `targetBytes` is the byte-target step's goal
16
17
  * (`SZ` (cli309.js:253044), the bytes `N$o` compresses toward).
17
- * The request's media budget is not a row of this table yet.
18
+ * - `request`: what one provider request may carry of the media the conversation holds (CC `eSn` (cli309.js:265961) and
19
+ * its constants `Xai` / `Jai` (cli309.js:253044)), every size in base64 characters — the unit the provider counts. Over `maxItems`
20
+ * media blocks (images and documents together; `largeWindow.maxItems` for a model whose window is at least
21
+ * `largeWindow.fromContextWindow` tokens) the oldest go until `maxItems - margin` remain; over the budget the oldest go
22
+ * until `hysteresisBase64Chars` under it. `budgetBase64Chars` is the default budget a deployment may replace
23
+ * (`RunnerDeps.mediaBudgetBase64Chars`); it is not CC's first-party 24 MiB, because a sema deployment mostly serves
24
+ * endpoints CC treats as third-party, for which CC's own budget is 75 MiB. There is no document-only budget: CC holds
25
+ * one for its first-party endpoint alone.
18
26
  */
19
27
  export declare const IMAGE_ADMISSION: Readonly<{
20
28
  readonly hard: Readonly<{
@@ -32,7 +40,37 @@ export declare const IMAGE_ADMISSION: Readonly<{
32
40
  rawBytes: number;
33
41
  targetBytes: 512000;
34
42
  }>;
43
+ readonly request: Readonly<{
44
+ maxItems: 100;
45
+ largeWindow: Readonly<{
46
+ fromContextWindow: 1000000;
47
+ maxItems: 600;
48
+ }>;
49
+ margin: 20;
50
+ budgetBase64Chars: number;
51
+ hysteresisBase64Chars: number;
52
+ }>;
35
53
  }>;
54
+ /** What one request may carry, resolved for a model and a deployment's budget: the media-block count, the margin a count
55
+ * cut leaves under it, the base64 budget (`Infinity`: none) and the hysteresis a budget cut leaves under that. */
56
+ export interface RequestMediaLimits {
57
+ maxItems: number;
58
+ margin: number;
59
+ budgetBase64Chars: number;
60
+ hysteresisBase64Chars: number;
61
+ }
62
+ /** The one reading of a deployment's request media budget (`RunnerDeps.mediaBudgetBase64Chars`, screened by
63
+ * {@link checkedRequestMediaBudget} at `new Runner`), for both of its readers — the request trim and the `tool_end.output`
64
+ * projection: absent ⇒ `IMAGE_ADMISSION.request.budgetBase64Chars`; `0` or `Infinity` ⇒ no budget (`Infinity`). */
65
+ export declare function requestMediaBudget(knob: number | undefined): number;
66
+ /** The limits a request on `model` under the deployment's budget `knob` is trimmed to. */
67
+ export declare function requestMediaLimits(model: {
68
+ readonly contextWindow?: unknown;
69
+ }, knob: number | undefined): RequestMediaLimits;
70
+ /** The deployment's request media budget, screened once at `new Runner`: absent, `0` or `Infinity` (no budget), or a whole
71
+ * number of base64 characters no smaller than twice the hysteresis. Anything else — a non-number, `NaN`, a negative, a
72
+ * fraction, a budget a cut would empty — is refused (`config.invalid_argument`), never read as a default or as none. */
73
+ export declare function checkedRequestMediaBudget(value: unknown, seat: string): void;
36
74
  /** Verify the raw bytes actually ARE the image format the claimed type names (`IMAGE_ADMISSION.hard.formats`). Extension
37
75
  * alone is forgeable: a `.png` holding text / an empty file / a truncated blob / an Apple-optimized PNG would otherwise
38
76
  * become a malformed `ImageContent` that makes the NEXT provider request fail (400). Pure — no I/O. */
@@ -149,6 +187,8 @@ export interface ToolResultMediaAdmission {
149
187
  content: unknown[];
150
188
  refused: ToolResultMediaRefusal[];
151
189
  }
190
+ /** The media type a block claims — its `type`, read once, when that is a media type — or `undefined` for any other value. */
191
+ export declare function claimedMediaType(block: unknown): MediaBlock["type"] | undefined;
152
192
  /**
153
193
  * The decoded size of the first image block that goes to the model over `IMAGE_ADMISSION.soft.targetBytes` with no
154
194
  * processor to bring it down — the one fact the run's operator notice reads (`config.image_processor_unavailable`), at
@@ -1,6 +1,6 @@
1
1
  import { createHash } from "node:crypto";
2
- import { claimedMediaType } from "./media-byte-cap.js";
3
2
  import { readMember } from "./thrown-value.js";
3
+ import { describeRejectedValue } from "./tool-search-setting.js";
4
4
  export const PDF_TARGET_RAW_SIZE = 20 * 1024 * 1024;
5
5
  const spells = (b, at, text) => {
6
6
  if (b.length < at + text.length)
@@ -22,16 +22,42 @@ const IMAGE_HEADER_CHECKS = Object.freeze({
22
22
  "image/webp": (b) => b.length >= 16 && spells(b, 0, "RIFF") && spells(b, 8, "WEBP") && (spells(b, 12, "VP8 ") || spells(b, 12, "VP8L") || spells(b, 12, "VP8X")),
23
23
  });
24
24
  const MiB = 1024 * 1024;
25
+ const IMAGE_BASE64_CHARS = 5 * MiB;
26
+ const IMAGE_BASE64_RAW_BYTES = (IMAGE_BASE64_CHARS * 3) / 4;
25
27
  export const IMAGE_ADMISSION = Object.freeze({
26
28
  hard: Object.freeze({
27
29
  formats: IMAGE_HEADER_CHECKS,
28
- readBytes: Object.freeze({ withoutProcessor: 5 * MiB, withProcessor: 64 * MiB }),
30
+ readBytes: Object.freeze({ withoutProcessor: IMAGE_BASE64_RAW_BYTES, withProcessor: 64 * MiB }),
29
31
  urlBytes: 20 * MiB,
30
32
  rejectEdge: 2000,
31
- imageBase64Chars: 5 * MiB,
33
+ imageBase64Chars: IMAGE_BASE64_CHARS,
34
+ }),
35
+ soft: Object.freeze({ frameEdge: 2000, rawBytes: IMAGE_BASE64_RAW_BYTES, targetBytes: 512_000 }),
36
+ request: Object.freeze({
37
+ maxItems: 100,
38
+ largeWindow: Object.freeze({ fromContextWindow: 1_000_000, maxItems: 600 }),
39
+ margin: 20,
40
+ budgetBase64Chars: 40 * MiB,
41
+ hysteresisBase64Chars: 10 * MiB,
32
42
  }),
33
- soft: Object.freeze({ frameEdge: 2000, rawBytes: (5 * MiB * 3) / 4, targetBytes: 512_000 }),
34
43
  });
44
+ const smallestRequestMediaBudget = () => 2 * IMAGE_ADMISSION.request.hysteresisBase64Chars;
45
+ export function requestMediaBudget(knob) {
46
+ const budget = knob ?? IMAGE_ADMISSION.request.budgetBase64Chars;
47
+ return budget === 0 ? Infinity : budget;
48
+ }
49
+ export function requestMediaLimits(model, knob) {
50
+ const { maxItems, largeWindow, margin, hysteresisBase64Chars } = IMAGE_ADMISSION.request;
51
+ const window = model.contextWindow;
52
+ return { maxItems: typeof window === "number" && window >= largeWindow.fromContextWindow ? largeWindow.maxItems : maxItems, margin, budgetBase64Chars: requestMediaBudget(knob), hysteresisBase64Chars };
53
+ }
54
+ export function checkedRequestMediaBudget(value, seat) {
55
+ if (value === undefined || value === 0 || value === Infinity || (Number.isInteger(value) && value >= smallestRequestMediaBudget()))
56
+ return;
57
+ const e = new Error(`${seat} ${describeRejectedValue(value)} is not a request media budget — expected a whole number of base64 characters of at least ${smallestRequestMediaBudget()} (twice the ${IMAGE_ADMISSION.request.hysteresisBase64Chars}-character margin a cut leaves under the budget), 0 or Infinity for no budget, or omit it for the default ${IMAGE_ADMISSION.request.budgetBase64Chars}`);
58
+ e.code = "config.invalid_argument";
59
+ throw e;
60
+ }
35
61
  export function imageMagicMatches(bytes, mimeType) {
36
62
  const formats = IMAGE_ADMISSION.hard.formats;
37
63
  return Object.hasOwn(formats, mimeType) && formats[mimeType](bytes);
@@ -188,6 +214,11 @@ const placeholderOf = (toolName, r) => ({
188
214
  type: "text",
189
215
  text: `[${r.type} from the ${JSON.stringify(toolName)} tool not shown: ${REFUSAL_CLAUSE[r.reason](r)} (media admission: ${r.reason})]`,
190
216
  });
217
+ const MEDIA_BLOCK_TYPES = new Set(["image", "document"]);
218
+ export function claimedMediaType(block) {
219
+ const type = readMember(block, "type");
220
+ return MEDIA_BLOCK_TYPES.has(type) ? type : undefined;
221
+ }
191
222
  const claimsMedia = (block) => claimedMediaType(block) !== undefined;
192
223
  async function admitBlock(block, processor) {
193
224
  const type = claimedMediaType(block);
@@ -0,0 +1,36 @@
1
+ import type { RunInternals } from "./runner/contracts.js";
2
+ export declare const INPUT_AUTHORS: readonly ["operator", "parent_model", "workflow", "peer", "observer", "engine"];
3
+ export type InputAuthor = (typeof INPUT_AUTHORS)[number];
4
+ /** Membership test for {@link InputAuthor}. */
5
+ export declare function isInputAuthor(v: unknown): v is InputAuthor;
6
+ /** An author as read: a member of the set, or `unknown` for anything else. */
7
+ export type InputAuthorReading = InputAuthor | "unknown";
8
+ /** The one reader: a member reads as itself, anything else (`undefined` included) as `unknown`. */
9
+ export declare function readInputAuthor(raw: unknown): InputAuthorReading;
10
+ /** THE predicate: does this input count as the operator's — screened by `classic.UserPromptSubmit`, carried across a pause, on
11
+ * the person's undelivered-input account? An unreadable word does (a filter's safe side); the five other words do not. */
12
+ export declare function countsAsOperator(reading: InputAuthorReading): boolean;
13
+ /**
14
+ * The objective's author on a leg, from the trusted channel's word (`RunInternals.objectiveAuthor`): absent is the public
15
+ * entry's own mint, `operator` — the host that called `runTask` wrote the objective or relays the person who did; a member is
16
+ * itself; anything else is `unknown`, screened like the operator's, and its sentence is handed to `onUnreadable` (the caller
17
+ * reports it once).
18
+ */
19
+ export declare function objectiveAuthorOf(declared: unknown, onUnreadable: (error: Error) => void): InputAuthorReading;
20
+ /** The trusted channel of a recipe's continuation leg — the one mint of `engine`: a fresh shallow copy of the internals the leg rides
21
+ * otherwise, its objective the recipe's own words (the caller's request rode the recipe's first leg). A composition whose later legs
22
+ * re-run the caller's objective (a cascade's rungs) does not call it. */
23
+ export declare function recipeContinuationLeg(internals: RunInternals | undefined): RunInternals;
24
+ /**
25
+ * The engine's own relay into a running stream's steer lane, under the author it states. The public `TaskStream.steer` mints
26
+ * `operator` on every call; this seat is how the engine hands a stream an input someone else wrote (an observer's report). It
27
+ * lives on the stream object the Runner minted — registered here, never on the package face — so no caller can name an author.
28
+ */
29
+ export type AuthoredSteer = (author: InputAuthor, text: string) => Promise<void>;
30
+ /** Register the authored steer of a stream the Runner minted (the driver calls this once per stream). */
31
+ export declare function bindAuthoredSteer(stream: object, steer: AuthoredSteer): void;
32
+ /** The authored steer of a stream the Runner minted; `undefined` for any other object. */
33
+ export declare function authoredSteerOf(stream: object): AuthoredSteer | undefined;
34
+ /** The terminal account's sentence for inputs of other authors a run accepted and never delivered: they are dropped, never
35
+ * carried across a pause and never counted as the person's (the caller hands it to `onError` once, `phase: "degraded"`). */
36
+ export declare function droppedInputsDisclosure(authors: readonly InputAuthor[]): Error;
@@ -0,0 +1,39 @@
1
+ import { describeRejectedValue } from "./tool-search-setting.js";
2
+ export const INPUT_AUTHORS = Object.freeze(["operator", "parent_model", "workflow", "peer", "observer", "engine"]);
3
+ const INPUT_AUTHOR_SET = new Set(INPUT_AUTHORS);
4
+ export function isInputAuthor(v) {
5
+ return INPUT_AUTHOR_SET.has(v);
6
+ }
7
+ export function readInputAuthor(raw) {
8
+ return isInputAuthor(raw) ? raw : "unknown";
9
+ }
10
+ const COUNTS_AS_OPERATOR = Object.freeze({ operator: true, parent_model: false, workflow: false, peer: false, observer: false, engine: false });
11
+ export function countsAsOperator(reading) {
12
+ return reading === "unknown" || COUNTS_AS_OPERATOR[reading];
13
+ }
14
+ export function objectiveAuthorOf(declared, onUnreadable) {
15
+ if (declared === undefined)
16
+ return "operator";
17
+ const reading = readInputAuthor(declared);
18
+ if (reading === "unknown") {
19
+ onUnreadable(new Error(`RunInternals.objectiveAuthor ${describeRejectedValue(declared)} is not an input author (${INPUT_AUTHORS.join(" / ")}) — the objective is screened as the operator's`));
20
+ }
21
+ return reading;
22
+ }
23
+ export function recipeContinuationLeg(internals) {
24
+ return { ...internals, objectiveAuthor: "engine" };
25
+ }
26
+ const authoredSteers = new WeakMap();
27
+ export function bindAuthoredSteer(stream, steer) {
28
+ authoredSteers.set(stream, steer);
29
+ }
30
+ export function authoredSteerOf(stream) {
31
+ return authoredSteers.get(stream);
32
+ }
33
+ export function droppedInputsDisclosure(authors) {
34
+ const counts = new Map();
35
+ for (const a of authors)
36
+ counts.set(a, (counts.get(a) ?? 0) + 1);
37
+ const named = [...counts].map(([a, n]) => `${n} from ${a}`).join(", ");
38
+ return new Error(`the run ended with ${authors.length} accepted input(s) it never delivered that are not the operator's (${named}): they are dropped — only an operator's input is carried across a pause or counted as the person's undelivered input`);
39
+ }
@@ -0,0 +1,62 @@
1
+ /**
2
+ * A leg's two identity readings, as pure functions with no runtime imports — so a store's projection reads them exactly as
3
+ * the prepare mint and the stations do (one predicate each, never a second spelling at a reader that cannot reach the
4
+ * mods layer).
5
+ */
6
+ import type { HookInvocationIdentity } from "./hooks.js";
7
+ import type { AskSourceIdentity } from "./tool-policy.js";
8
+ /**
9
+ * The id a delegated leg's events carry as `agentId`: the leg's task id ({@link legTaskIdOf}) — for a background child, the
10
+ * registry task id its spawner registered it under (the string its row, launch card, notifications, `TaskStop` and
11
+ * `SendMessage` use); a foreground child has no row, so it is its session id. A top-level leg carries none. It reads two facts of
12
+ * the leg's identity, so a face minted before the leg's hook envelope (the ask source) asks it with the same two, and a parked
13
+ * row's summary asks it with the two the row records.
14
+ */
15
+ export declare function agentIdOf(identity: Pick<HookInvocationIdentity, "taskId" | "isDelegatedChild"> | undefined): string | undefined;
16
+ /** A leg's task id — the row a delegation lane runs it as (`internals.rowTaskId`), else its host's `spec.taskId`, else its
17
+ * session id. Minted once at prepare (`Prepared.taskId`); a reader before prepare asks this same function (the resume screen;
18
+ * the throw backstop, which has no session yet). The session id is the leg's transcript address. */
19
+ export declare function legTaskIdOf(spec: {
20
+ readonly taskId?: string | undefined;
21
+ }, internals: {
22
+ readonly rowTaskId?: string | undefined;
23
+ } | undefined, sessionId: string): string;
24
+ export declare function legTaskIdOf(spec: {
25
+ readonly taskId?: string | undefined;
26
+ }, internals: {
27
+ readonly rowTaskId?: string | undefined;
28
+ } | undefined, sessionId: string | undefined): string | undefined;
29
+ /** The facts a leg's ask source is minted from — all the leg's own, read once its session and task id are minted. */
30
+ export interface AskSourceFacts {
31
+ /** The leg's end-user principal (its spec's). */
32
+ readonly principal: string | undefined;
33
+ /** The leg's session id: the conversation every ask of the leg is raised in. */
34
+ readonly sessionId: string;
35
+ /** The leg's one task id ({@link legTaskIdOf}, as minted at prepare). */
36
+ readonly taskId: string;
37
+ /** The leg's effective delegation fact — forks included, the checkpoint's record on a deps-only resume. */
38
+ readonly isDelegatedChild: boolean;
39
+ /** The leg's trusted internals: the parent link and the display names. */
40
+ readonly internals: {
41
+ readonly parentTaskId?: string | undefined;
42
+ readonly explicitAgentName?: string | undefined;
43
+ readonly agentName?: string | undefined;
44
+ } | undefined;
45
+ }
46
+ /**
47
+ * The leg's ask source, minted ONCE per leg and read by every face that names the issuing leg: the four `resolveAsk`
48
+ * construction sites (the main gate, both inherited wrapper arms, the approved-edit re-ask) spread it, the question tool and
49
+ * the gate's question routing project it, and the approval and plan_review parks stamp its session onto the row — so the
50
+ * explicit "from a background agent" discriminator can never be dropped on one leg, and the same leg is never named two ways.
51
+ * Every member is a fact of THIS leg's own prepare (an inherited ask fires in the child's gate): `internals` never rides a
52
+ * TaskSpec, so a worker cannot self-declare or suppress them.
53
+ *
54
+ * - `sourceSessionId` — the leg's session: the conversation, never a task.
55
+ * - `agentId` — {@link agentIdOf} over the leg's task id and delegation fact: present exactly on a delegated child.
56
+ * - `fromSubagent` — the attribution discriminator: trusted `parentTaskId` presence (a directly-started workflow's agent has
57
+ * none, so it carries `agentId` without it).
58
+ * - `isDelegatedChild` — the refusal posture: the RAW delegation fact, forks included (a fork's interaction contract is
59
+ * one-shot — "no waiting for the user" — so a stop-and-wait refusal would ask it the impossible), so `resolveAsk`'s human
60
+ * refusal texts speak the right posture (parent thread: stop and wait for the user; delegated child: adapt or report).
61
+ */
62
+ export declare function mintAskSourceIdentity(leg: AskSourceFacts): AskSourceIdentity;
@@ -0,0 +1,18 @@
1
+ export function agentIdOf(identity) {
2
+ return identity?.isDelegatedChild === true ? identity.taskId : undefined;
3
+ }
4
+ export function legTaskIdOf(spec, internals, sessionId) {
5
+ return internals?.rowTaskId ?? spec.taskId ?? sessionId;
6
+ }
7
+ export function mintAskSourceIdentity(leg) {
8
+ const agentId = agentIdOf({ taskId: leg.taskId, isDelegatedChild: leg.isDelegatedChild });
9
+ const sourceAgentName = leg.internals?.explicitAgentName ?? leg.internals?.agentName;
10
+ return Object.freeze({
11
+ principal: leg.principal,
12
+ sourceSessionId: leg.sessionId,
13
+ ...(agentId !== undefined ? { agentId } : {}),
14
+ ...(leg.internals?.parentTaskId !== undefined ? { fromSubagent: true } : {}),
15
+ ...(sourceAgentName !== undefined ? { sourceAgentName } : {}),
16
+ ...(leg.isDelegatedChild ? { isDelegatedChild: true } : {}),
17
+ });
18
+ }
@@ -204,7 +204,8 @@ export declare function judgeEntrySessionMetaKey(copy: McpServerSpec): {
204
204
  /**
205
205
  * The host-transport question for ONE snapshot MCP entry: a `{ kind: "host" }` transport carries no member beyond its kind (its host seat
206
206
  * carries its own pieces — a reference, a principal header, a command or a url would be declared and never in force), and its server
207
- * cannot opt in to `elicitation` (the seat answers the engine's requests only: a server's request has no way back). Either refuses under
207
+ * cannot opt in to `elicitation` (the server behind a host's pipe is the host's own code: a question it has for the user goes through the
208
+ * host's own interface, and the engine advertises no elicitation for it). Either refuses under
208
209
  * `config.invalid_argument`, naming the server and the member. Any other entry is unchanged.
209
210
  */
210
211
  export declare function judgeEntryHostTransport(copy: McpServerSpec): {
@@ -267,8 +268,8 @@ export declare function snapshotAndValidateMcpEntries(declared: unknown, where?:
267
268
  * a locked slot (`config.locked_key`, two-state — the whole prepare is rejected, nothing is
268
269
  * silently dropped or merged), and produce the resolved snapshot downstream assembly consumes.
269
270
  * Runs BEFORE any side effect of task preparation — and, on a resume, before the claim: the resume's
270
- * screen calls this same function (`enter` naming each refusal's seat) and hands the leg the frozen
271
- * entries it judged, so the leg's prepare judges engine-owned plain data and dials what was judged.
271
+ * screen calls this same function (`enter` naming each refusal's seat) and hands the leg its judged copies
272
+ * of the lists THIS resume handed (the row records none), so the leg's prepare judges engine-owned plain data and dials what was judged.
272
273
  */
273
274
  export declare function preflightLockedConfig(spec: Pick<TaskSpec, "mcp" | "a2a" | "toolPolicy" | "basePolicyForResumeEdit">, deps: RunnerDeps, enter?: ConfigDoorEntry, receipt?: ReceivedPeerDeclarations): LockedPreflight;
274
275
  /**
@@ -3,7 +3,7 @@ import { DECLARATION_ENTRY_WORDS, DECLARATION_PATH_RULES, NO_DECLARATION_PATH_RU
3
3
  import { isPlainRecord, receive } from "./mods/kernel/receive.js";
4
4
  import { TOOL_FACE_WORDS, readToolFaces } from "./tool-face-reader.js";
5
5
  import { judgeSessionMetaKey } from "./mcp-call-meta.js";
6
- import { CONFIG_RECEIPT_MODE } from "./own-property-receipt.js";
6
+ import { CONFIG_RECEIPT_MODE, optionKeys, strayMembersOf } from "./own-property-receipt.js";
7
7
  import { isToolContentOrigin, TOOL_CONTENT_ORIGINS } from "./memory-engine/content-origin.js";
8
8
  import { inlineUntrusted } from "./untrusted-text.js";
9
9
  import { assertNoRetiredToolPolicyKeys } from "./retired-keys.js";
@@ -150,15 +150,17 @@ export function judgeEntrySessionMetaKey(copy) {
150
150
  return { ok: true, entry: copy };
151
151
  return { ok: false, error: codedError("config.invalid_argument", `${declarerWord("mcp")} ${declarerNameOf(copy.name)} declares ${inlineUntrusted(read.problem, 200)}. The key decides where the leg's session id rides on this server's requests, so it is refused rather than dropped or defaulted — a connector keyed on a session it never receives would share one state across every session.`) };
152
152
  }
153
+ const HOST_TRANSPORT_KEYS = optionKeys()({ kind: 0 });
153
154
  export function judgeEntryHostTransport(copy) {
154
155
  const transport = copy.transport;
155
156
  if (!isPlainRecord(transport) || transport["kind"] !== "host")
156
157
  return { ok: true, entry: copy };
157
- const extra = Object.keys(transport).find((member) => member !== "kind" && transport[member] !== undefined);
158
+ const stray = strayMembersOf(transport, { subject: "a host-supplied transport", unit: "member", moment: "when the entry is read" }, HOST_TRANSPORT_KEYS)?.names[0];
159
+ const extra = stray === undefined ? undefined : String(stray);
158
160
  const problem = extra !== undefined
159
161
  ? `a host-supplied transport with the member ${inlineUntrusted(JSON.stringify(extra), 80)}: a host transport carries its kind alone — the host seat carries what each request needs, so a member here would read as in force while nothing carries it`
160
162
  : copy.elicitation === true
161
- ? `elicitation on a host-supplied transport: the host seat answers the engine's requests only, so a server's question would have no way back`
163
+ ? `elicitation on a host-supplied transport: the server behind a host's pipe is the host's own code, so a question it has for the user goes through the host's own interface — the engine advertises no elicitation for it`
162
164
  : undefined;
163
165
  return problem === undefined ? { ok: true, entry: copy } : { ok: false, error: codedError("config.invalid_argument", `${declarerWord("mcp")} ${declarerNameOf(copy.name)} declares ${problem}.`) };
164
166
  }
@@ -2,7 +2,7 @@ import { type RootsSeat } from "../tools/fs/safety.js";
2
2
  import { type ReadDenyMatcher } from "../tools/fs/read-deny.js";
3
3
  import type { HomeViewsCarrier } from "../tools/fs/read-deny-home.js";
4
4
  import type { ContainmentFace } from "../tools/fs/containment-face.js";
5
- import type { AgentTool, BoundFileObject, ExecutionEnv } from "../internal/harness-types.js";
5
+ import type { AgentTool, BoundFileObject, ExecutionEnv, ReadFloor } from "../internal/harness-types.js";
6
6
  /**
7
7
  * LSP code-intelligence tool (design/64 §13.1) — the app-dev命门 (go-to-def / find-refs / hover across
8
8
  * Dart/Kotlin/TS). A single `lsp` tool with a 9-operation enum, built over a pluggable {@link LspServerManager}.
@@ -301,6 +301,8 @@ export interface LspToolOptions {
301
301
  export declare function createLspTool(manager: LspServerManager, opts?: LspToolOptions): AgentTool;
302
302
  /**
303
303
  * A git-check-ignore-based path filter for {@link LspToolOptions.isPathIgnored} (CC parity). Best-effort:
304
- * if git isn't available or the check fails, nothing is treated as ignored (keep all). Caches per path.
304
+ * if git isn't available or the check fails, nothing is treated as ignored (keep all). Caches per path. `readFloor` = the
305
+ * byte floor each check's start carries, read as it starts (a run's: the run's base table; absent ⇒ none — a caller with
306
+ * no run). A floor that cannot be read is a failed check.
305
307
  */
306
- export declare function gitCheckIgnoreFilter(env: ExecutionEnv, root: string): (uri: string) => Promise<boolean>;
308
+ export declare function gitCheckIgnoreFilter(env: ExecutionEnv, root: string, readFloor?: () => ReadFloor | undefined): (uri: string) => Promise<boolean>;
package/dist/core/lsp.js CHANGED
@@ -349,7 +349,7 @@ function toModelBase(result) {
349
349
  }
350
350
  return result;
351
351
  }
352
- export function gitCheckIgnoreFilter(env, root) {
352
+ export function gitCheckIgnoreFilter(env, root, readFloor) {
353
353
  const cache = new Map();
354
354
  return async (uri) => {
355
355
  const path = uriToPath(uri);
@@ -359,7 +359,8 @@ export function gitCheckIgnoreFilter(env, root) {
359
359
  let ignored = false;
360
360
  try {
361
361
  const q = `'${path.replace(/'/g, `'\\''`)}'`;
362
- const res = await env.exec(`git check-ignore ${q}`, { cwd: root, timeout: 10 });
362
+ const floor = readFloor?.();
363
+ const res = await env.exec(`git check-ignore ${q}`, { cwd: root, timeout: 10, ...(floor !== undefined ? { readFloor: floor } : {}) });
363
364
  ignored = res.ok && res.value.exitCode === 0;
364
365
  }
365
366
  catch {
@@ -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;