@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
@@ -4,7 +4,7 @@
4
4
  * A child the engine spawns may run what the MODEL chose (a tool shell, a gate over model-written code, a language
5
5
  * server). Under the `"scrub"` policy (the default) it inherits every variable but those the judgment below names —
6
6
  * deleted whole, never rewritten; `"all"` and a `string[]` allow list are the caller's explicit alternatives
7
- * ({@link inheritedHostEnv}). Whatever the policy, an entry that is this deployment's own credential is never inherited:
7
+ * ({@link inheritedHostEnv}). Whatever the policy, an entry that is one of the engine's own credentials is never inherited:
8
8
  * its name is one the deployment declared, or its value equals a credential value the deployment declared or the
9
9
  * engine holds ({@link declareWithheldEnv}, {@link holdOwnCredentialValues}). One judgment per variable ({@link classifySecretEnvEntry}), the first rule that answers:
10
10
  * 1. exempt — git's environment config and the proxy variables, handed on as written ({@link isExemptEnvName});
@@ -27,8 +27,8 @@ import { type EngineNotice } from "./engine-notice.js";
27
27
  * Reads the first {@link VALUE_SCAN_LIMIT} code units. The value half of the judgment, exported apart from the env
28
28
  * entry's exemptions ({@link isExemptEnvName}): a caller holding a value that is no environment variable asks this. */
29
29
  export declare function looksLikeCredentialValue(value: string): boolean;
30
- /** Which rule withheld an entry: one of the scrub's rules, or `own-credential` — the entry is this deployment's own
31
- * credential (its name is declared, or its value equals a declared or engine-held credential value:
30
+ /** Which rule withheld an entry: one of the scrub's rules, or `own-credential` — the entry is one of the engine's own
31
+ * credentials (its name is declared, or its value equals a declared or engine-held credential value:
32
32
  * {@link declareWithheldEnv}), which every policy withholds. */
33
33
  export type SecretEnvFindingKind = "exact-name" | "name-rule" | "namespace-rule" | "prefix-rule" | "value-rule" | "own-credential";
34
34
  /** One env entry withheld (deleted) from a child's environment: its name — never its value, so the record is
@@ -52,9 +52,9 @@ export declare function isSecretEnvKey(key: string, value?: string): boolean;
52
52
  export declare function scrubSecretEnv(env: NodeJS.ProcessEnv, findings?: SecretEnvFinding[]): NodeJS.ProcessEnv;
53
53
  /** How much of this process's environment a child spawned on this host inherits — the `inheritEnv` value. */
54
54
  export type InheritEnvPolicy = "all" | "scrub" | string[];
55
- /** What {@link declareWithheldEnv} takes: this deployment's own credentials in this process's environment. */
55
+ /** What {@link declareWithheldEnv} takes: the engine's own credentials in this process's environment. */
56
56
  export interface WithheldEnvDeclaration {
57
- /** Names of variables that are this deployment's own credentials: never inherited, and an allow list naming one is refused. */
57
+ /** Names of variables that are the engine's own credentials: never inherited, and an allow list naming one is refused. */
58
58
  readonly names: readonly string[];
59
59
  /** Credential values this deployment holds: an inherited entry whose value equals one — the same string, compared
60
60
  * whole, never as a part — is never inherited, whatever its name. A value must be a credential: not white space only,
@@ -76,10 +76,10 @@ export declare function isBlankCredential(value: string): boolean;
76
76
  * one-letter key) is left in the words, as it is left to every child. */
77
77
  export declare function namesASecret(value: string): boolean;
78
78
  /**
79
- * Declare this deployment's OWN credentials in this process's environment — the engine's or its host's: an approval
79
+ * Declare the engine's own credentials in this process's environment — the engine's or its host's: an approval
80
80
  * bearer, a service token — by name and by value. From then on no child spawned on this host inherits one, whatever the
81
81
  * policy: every spawn site reads its environment through {@link inheritedHostEnv}, which subtracts from `"all"`, from the
82
- * scrub's result and from an allow list's every entry that is this deployment's own credential (each one present is a
82
+ * scrub's result and from an allow list's every entry that is one of the engine's own credentials (each one present is a
83
83
  * finding of kind `own-credential`), and {@link inheritEnvPolicyProblem} refuses an allow list naming a declared name.
84
84
  * A NAME is compared as the platform compares variable names: exactly, but case-blind on Windows. A VALUE is compared
85
85
  * whole, as the same string: an entry holding it as a part (`Bearer <value>`, a URL, an encoding of it) is not its value.
@@ -160,7 +160,7 @@ export declare function credentialHeaderValues(headers: Readonly<Record<string,
160
160
  /** Test seam: never called by production code (a host re-declares `{ names: [], values: [] }`; what the engine took in stays). */
161
161
  export declare function __resetWithheldEnv(): void;
162
162
  /**
163
- * THE environment a child spawned ON THIS HOST inherits: the policy's arm, less this deployment's own credentials — a
163
+ * THE environment a child spawned ON THIS HOST inherits: the policy's arm, less the engine's own credentials — a
164
164
  * declared name, or a value equal to a declared or engine-held credential value ({@link declareWithheldEnv},
165
165
  * {@link holdOwnCredentialValues}). The arms: `"scrub"` (and absent) is this process's environment through
166
166
  * {@link scrubSecretEnv}; `"all"` is this process's environment as written; a `string[]` is exactly the named
@@ -198,8 +198,8 @@ export declare function hostChildEnv(policy: InheritEnvPolicy | undefined, ...gr
198
198
  export declare function inheritEnvPolicyProblem(value: unknown): string | undefined;
199
199
  /** Test seam: never called by production code. */
200
200
  export declare function __resetSecretEnvScrubNoticeAnnouncement(): void;
201
- /** What both disclosures say about one set of findings: every withheld name, and those that are this deployment's own
202
- * credential — withheld under every policy — whichever rule withheld them first ({@link ownCredentialJudge}, the
201
+ /** What both disclosures say about one set of findings: every withheld name, and those that are the engine's own
202
+ * credentials — withheld under every policy — whichever rule withheld them first ({@link ownCredentialJudge}, the
203
203
  * subtraction's own judgment, over the entry's value in this process's environment: every finding names an entry of
204
204
  * it). The rest the scrub withheld, and `"all"` or an allow list naming them hands them on. */
205
205
  export declare function withheldEnvNames(findings: readonly SecretEnvFinding[]): {
@@ -211,7 +211,7 @@ export declare function withheldEnvNames(findings: readonly SecretEnvFinding[]):
211
211
  * engine's one notice throat — so a wired `onNotice` seat REPLACES the console line exactly as every
212
212
  * other `EngineNotice` does, and an absent seat prints the same words `console.warn` always printed here.
213
213
  * `detail` is {@link withheldEnvNames}: `names` every withheld key, `ownCredentials` (present only when one was
214
- * withheld) the subset that is the deployment's own credential. Once per PROCESS, never per call or per site; an
214
+ * withheld) the subset that is the engine's own credentials. Once per PROCESS, never per call or per site; an
215
215
  * EMPTY findings array is a no-op.
216
216
  */
217
217
  export declare function announceSecretEnvScrub(onNotice: ((notice: EngineNotice) => void) | undefined, findings: readonly SecretEnvFinding[]): void;
@@ -1,9 +1,9 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { types } from "node:util";
3
3
  import { CREDENTIAL_MIN_CHARS, CREDENTIAL_VOCABULARY, envNameView, isSensitiveHeaderName, splitCamelCase } from "./credential-vocabulary.js";
4
- import { DEFAULT_INHERITED_ENV_VARS } from "@modelcontextprotocol/sdk/client/stdio.js";
4
+ import { DEFAULT_INHERITED_ENV_VARS } from "@modelcontextprotocol/client/stdio";
5
5
  import { deliverEngineNotice } from "./engine-notice.js";
6
- import { receiveOwnProperties } from "./own-property-receipt.js";
6
+ import { optionKeys, receiveMembers } from "./own-property-receipt.js";
7
7
  const GIT_CONFIG_ENV_RE = /^GIT_CONFIG_(?:COUNT|PARAMETERS|(?:KEY|VALUE)_[0-9]+)$/;
8
8
  const PROXY_ENV_RE = /^(?:(?:https?|ftp|all|no)_proxy|npm_config_(?:https?_)?proxy|npm_config_noproxy|yarn_proxy|(?:yarn|global_agent|docker|claude_code)_(?:https?|no)_proxy|cloudsdk_proxy_[a-z]+|electron_get_use_proxy)$/i;
9
9
  function isExemptEnvName(name) {
@@ -94,6 +94,7 @@ export function looksLikeCredentialValue(value) {
94
94
  TOKEN_WORD_RE.test(text) ||
95
95
  BEARER_BASIC_RE.test(text));
96
96
  }
97
+ const OWN_CREDENTIAL = "the engine's own service credential";
97
98
  const SECRET_ENV_KIND_CONFIDENCE = {
98
99
  "exact-name": "high",
99
100
  "prefix-rule": "high",
@@ -176,6 +177,7 @@ const withheldEnvOf = () => {
176
177
  Reflect.set(globalThis, WITHHELD_ENV, fresh);
177
178
  return fresh;
178
179
  };
180
+ const WITHHELD_ENV_TABLE_KEYS = optionKeys()({ names: 0, values: 0 });
179
181
  const kindOf = (v) => (v === null ? "null" : Array.isArray(v) ? "an array" : typeof v);
180
182
  function listCopy(label, list) {
181
183
  if (types.isProxy(list))
@@ -237,10 +239,7 @@ export function declareWithheldEnv(table) {
237
239
  if (given === null || typeof given !== "object" || Array.isArray(given)) {
238
240
  throw new Error(`declareWithheldEnv: the declaration must be a table { names, values } (got ${Array.isArray(given) ? "an array — a names-only list is no longer a declaration: pass { names, values }" : kindOf(given)})`);
239
241
  }
240
- const received = receiveOwnProperties(given, { subject: "declareWithheldEnv's table", unit: "member", moment: "at the declaration" });
241
- const stray = Object.keys(received).find((k) => k !== "names" && k !== "values");
242
- if (stray !== undefined)
243
- throw new Error(`declareWithheldEnv: the table has a member ${JSON.stringify(stray.slice(0, 64))} — it holds names and values only`);
242
+ const received = receiveMembers(given, { subject: "declareWithheldEnv's table", unit: "member", moment: "at the declaration" }, WITHHELD_ENV_TABLE_KEYS, (_, [stray]) => new Error(`declareWithheldEnv: the table has a member ${JSON.stringify(String(stray).slice(0, 64))} — it holds names and values only`));
244
243
  const givenNames = received.names;
245
244
  if (!Array.isArray(givenNames))
246
245
  throw new Error(`declareWithheldEnv: names must be an array of variable names (got ${kindOf(givenNames)})`);
@@ -444,7 +443,7 @@ export function inheritEnvPolicyProblem(value) {
444
443
  return shape;
445
444
  const own = new Set(names.map(envNameKey));
446
445
  const named = value.findIndex((k) => own.has(envNameKey(k)));
447
- return named === -1 ? undefined : `inheritEnv[${named}] names ${value[named]}, which is this deployment's own credential and cannot be inherited by a child (a configuration error: no retry succeeds until the policy or the declaration changes)`;
446
+ return named === -1 ? undefined : `inheritEnv[${named}] names ${value[named]}, which is ${OWN_CREDENTIAL} and cannot be inherited by a child (a configuration error: no retry succeeds until the policy or the declaration changes)`;
448
447
  }
449
448
  let secretEnvScrubNoticeAnnounced = false;
450
449
  export function __resetSecretEnvScrubNoticeAnnouncement() {
@@ -461,7 +460,7 @@ export function announceSecretEnvScrub(onNotice, findings) {
461
460
  return;
462
461
  secretEnvScrubNoticeAnnounced = true;
463
462
  const { names, ownCredentials } = withheldEnvNames(findings);
464
- const own = ownCredentials.length > 0 ? `; ${ownCredentials.length} of them this deployment's own credential(s) (${ownCredentials.join(", ")})` : "";
463
+ const own = ownCredentials.length > 0 ? `; ${ownCredentials.length} of them ${OWN_CREDENTIAL}(s) (${ownCredentials.join(", ")})` : "";
465
464
  deliverEngineNotice(onNotice, {
466
465
  code: "config.secret_env_scrubbed",
467
466
  message: `secret_env_scrubbed: ${names.length} env key(s) withheld from a spawned child's environment (${names.join(", ")})${own} — once per process; wire onNotice for the structured form`,
@@ -483,7 +482,7 @@ export function withheldEnvUserNotice(withheld, at) {
483
482
  const scrubbed = names.filter((k) => !ownCredentials.includes(k));
484
483
  const halves = [
485
484
  ...(scrubbed.length > 0 ? [`${scrubbed.join(", ")} — withheld by the credential scrub; the run's inheritEnv ("all", or a list naming them) hands them on`] : []),
486
- ...(ownCredentials.length > 0 ? [`${ownCredentials.join(", ")} — this deployment's own credential(s), withheld under every inheritEnv`] : []),
485
+ ...(ownCredentials.length > 0 ? [`${ownCredentials.join(", ")} — ${OWN_CREDENTIAL}(s), withheld under every inheritEnv`] : []),
487
486
  ];
488
487
  return {
489
488
  code: "inherit_env.names_withheld",
@@ -1,9 +1,12 @@
1
1
  import { SessionError, StreamingImportValidator, importRowCells, ownerCell, sessionLogMarkOf, uuidv7 } from "../internal/harness.js";
2
- import { receiptRefusal, receiveOwnProperties } from "./own-property-receipt.js";
2
+ import { optionKeys, receiptRefusal, receiveMembers } from "./own-property-receipt.js";
3
3
  import { thrownText } from "./thrown-value.js";
4
4
  const EXPORT_WORDS = { subject: "SessionLogExportOptions", unit: "member", moment: "at SessionLogTransfer.exportStream" };
5
5
  const BEGIN_WORDS = { subject: "SessionLogTransfer.beginReplace options", unit: "member", moment: "at SessionLogTransfer.beginReplace" };
6
6
  const COMMIT_WORDS = { subject: "SessionLogCommit", unit: "member", moment: "at SessionLogReplace.commit" };
7
+ const EXPORT_KEYS = optionKeys()({ afterSeq: 0, batchSize: 0 });
8
+ const BEGIN_KEYS = optionKeys()({ preserveActorAssertions: 0 });
9
+ const COMMIT_KEYS = optionKeys()({ owner: 0, decide: 0 });
7
10
  async function logOrNull(seat, sessionId) {
8
11
  return (await seat.readRow(sessionId))?.entries ?? null;
9
12
  }
@@ -15,14 +18,10 @@ function committedHead(sessionId, answer) {
15
18
  }
16
19
  throw new SessionError("storage", `the repo's importEntries wrote session ${sessionId}'s log but answered no head (got ${answer === null ? "null" : typeof answer}) — a repo behind SessionStore.logTransfer answers the head its write committed; read the row again`);
17
20
  }
18
- function readRecord(raw, words, names) {
21
+ function readRecord(raw, words, keys) {
19
22
  if (typeof raw !== "object" || raw === null)
20
23
  throw receiptRefusal(`${words.subject} must be an object, got ${raw === null ? "null" : typeof raw}`);
21
- const got = receiveOwnProperties(raw, words);
22
- for (const name of Object.keys(got))
23
- if (!names.includes(name))
24
- throw receiptRefusal(`${words.subject} carries "${name}" — not a member this face reads`);
25
- return got;
24
+ return receiveMembers(raw, words, keys, (_, [stray]) => receiptRefusal(`${words.subject} carries "${String(stray)}" — not a member this face reads`));
26
25
  }
27
26
  function isIntegerFrom(value, floor) {
28
27
  return typeof value === "number" && Number.isSafeInteger(value) && value >= floor;
@@ -30,7 +29,7 @@ function isIntegerFrom(value, floor) {
30
29
  function readExportOptions(raw) {
31
30
  if (raw === undefined)
32
31
  return { afterSeq: -1 };
33
- const got = readRecord(raw, EXPORT_WORDS, ["afterSeq", "batchSize"]);
32
+ const got = readRecord(raw, EXPORT_WORDS, EXPORT_KEYS);
34
33
  const afterSeq = got["afterSeq"];
35
34
  if (afterSeq !== undefined && !isIntegerFrom(afterSeq, -1))
36
35
  throw receiptRefusal("SessionLogExportOptions.afterSeq must be an integer ≥ -1 when present");
@@ -41,7 +40,7 @@ function readExportOptions(raw) {
41
40
  function readBeginOptions(raw) {
42
41
  if (raw === undefined)
43
42
  return {};
44
- const preserveActorAssertions = readRecord(raw, BEGIN_WORDS, ["preserveActorAssertions"])["preserveActorAssertions"];
43
+ const preserveActorAssertions = readRecord(raw, BEGIN_WORDS, BEGIN_KEYS)["preserveActorAssertions"];
45
44
  if (preserveActorAssertions === undefined)
46
45
  return {};
47
46
  if (typeof preserveActorAssertions !== "boolean")
@@ -49,7 +48,7 @@ function readBeginOptions(raw) {
49
48
  return { preserveActorAssertions };
50
49
  }
51
50
  function readCommit(raw) {
52
- const { owner, decide } = readRecord(raw, COMMIT_WORDS, ["owner", "decide"]);
51
+ const { owner, decide } = readRecord(raw, COMMIT_WORDS, COMMIT_KEYS);
53
52
  if (owner === undefined)
54
53
  throw receiptRefusal("SessionLogCommit.owner must be a principal name or null (anonymous), got undefined");
55
54
  try {
@@ -409,7 +409,7 @@ export declare class InMemorySessionPolicyStore implements SessionPolicyStore {
409
409
  private readonly map;
410
410
  /** {@link SessionPolicyStoreOptions.mountedToolNames}, read once at construction. */
411
411
  private readonly mountedToolNames;
412
- constructor(opts?: SessionPolicyStoreOptions);
412
+ constructor(options?: SessionPolicyStoreOptions);
413
413
  /**
414
414
  * The per-key mark {@link SessionPolicyStore.deleteBySession} may not erase: the largest `rev` this key has
415
415
  * ever been stamped with, kept outside the row so removing the row cannot roll the counter back. Written by
@@ -8,6 +8,7 @@ import { NAME_RULE_FACES, noticeRuleText } from "./permission-rule-model.js";
8
8
  import { parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
9
9
  import { splitNamespacedName } from "./tool-name-aliases.js";
10
10
  import { namesASetOfTools } from "./namespaced-rule-name.js";
11
+ import { optionKeys, receiveOptions } from "./own-property-receipt.js";
11
12
  const SESSION_RULE_BUCKETS = { toolAllow: "allow", toolDeny: "deny", allowDirs: "dirs" };
12
13
  const BUCKETS = Object.keys(SESSION_RULE_BUCKETS);
13
14
  const ENTRY_FIELDS = BUCKETS.filter((f) => SESSION_RULE_BUCKETS[f] !== "dirs");
@@ -25,6 +26,7 @@ export class SessionPolicyError extends Error {
25
26
  }
26
27
  }
27
28
  const NO_DECLARED_TOOLS = new Set();
29
+ const SESSION_POLICY_STORE_OPTION_KEYS = optionKeys()({ mountedToolNames: 0 });
28
30
  export function readMountedToolNames(value) {
29
31
  if (value === undefined)
30
32
  return NO_DECLARED_TOOLS;
@@ -525,8 +527,9 @@ export function continuesLineage(a, b) {
525
527
  export class InMemorySessionPolicyStore {
526
528
  map = new Map();
527
529
  mountedToolNames;
528
- constructor(opts) {
529
- this.mountedToolNames = readMountedToolNames(opts?.mountedToolNames);
530
+ constructor(options) {
531
+ const opts = receiveOptions(options, "InMemorySessionPolicyStore", SESSION_POLICY_STORE_OPTION_KEYS);
532
+ this.mountedToolNames = readMountedToolNames(opts.mountedToolNames);
530
533
  }
531
534
  highWater = new Map();
532
535
  key(sessionId, principal) {
@@ -1,4 +1,4 @@
1
- import type { AgentMessage } from "../internal/harness-types.js";
1
+ import type { AgentMessage, RowAdmission } from "../internal/harness-types.js";
2
2
  import type { ToolResultMessage } from "../internal/llm.js";
3
3
  import type { Session } from "./session.js";
4
4
  import type { ToolEffect } from "./types.js";
@@ -122,6 +122,7 @@ export declare const INTERRUPTED_BY_USER_FOR_TOOL_USE_MARKER = "[Request interru
122
122
  */
123
123
  export declare function appendInterruptionMarker(session: Session, opts: {
124
124
  toolUseInFlight: boolean;
125
+ admitRows?: RowAdmission;
125
126
  }): Promise<string>;
126
127
  /** One synthetic interrupted result: what a call with no recorded result is closed with. */
127
128
  export interface InterruptedResult {
@@ -172,4 +173,4 @@ export declare function interruptedResultMessage(result: InterruptedResult, time
172
173
  * never started: it is closed with a "never executed — safe to re-issue" result instead of the
173
174
  * conservative unknown-outcome wording. When omitted, every orphan keeps the conservative texts.
174
175
  */
175
- export declare function reconcileInterruptedSession(session: Session, toolEffects?: Map<string, ToolEffect>, suspendedBatch?: ReadonlySet<string>, startedToolCallIds?: ReadonlySet<string>): Promise<ReconcileReport>;
176
+ export declare function reconcileInterruptedSession(session: Session, toolEffects?: Map<string, ToolEffect>, suspendedBatch?: ReadonlySet<string>, startedToolCallIds?: ReadonlySet<string>, admitRows?: RowAdmission): Promise<ReconcileReport>;
@@ -1,3 +1,4 @@
1
+ import { appendAdmittedRow } from "./row-admission.js";
1
2
  import { readMember } from "./thrown-value.js";
2
3
  export const closeNeverExecuted = (errorKind) => errorKind === "interrupted_never_started";
3
4
  const INTERRUPTED_UNKNOWN = "[INTERRUPTED] The previous run ended before this tool call's result was recorded. Its outcome " +
@@ -86,7 +87,7 @@ export function findOrphanToolCalls(messages, suspendedBatch) {
86
87
  export const INTERRUPTED_BY_USER_MARKER = "[Request interrupted by user]";
87
88
  export const INTERRUPTED_BY_USER_FOR_TOOL_USE_MARKER = "[Request interrupted by user for tool use]";
88
89
  export async function appendInterruptionMarker(session, opts) {
89
- return await session.appendMessage({
90
+ return await appendAdmittedRow(opts.admitRows, session, {
90
91
  role: "user",
91
92
  content: [
92
93
  {
@@ -145,14 +146,16 @@ function closableByAppend(messages, suspendedBatch) {
145
146
  .sort((a, b) => a[1].order - b[1].order)
146
147
  .map(([toolCallId, site]) => ({ toolCallId, toolName: site.toolName, args: site.args }));
147
148
  }
148
- export async function reconcileInterruptedSession(session, toolEffects, suspendedBatch, startedToolCallIds) {
149
+ export async function reconcileInterruptedSession(session, toolEffects, suspendedBatch, startedToolCallIds, admitRows) {
149
150
  const { messages } = await session.buildContext();
150
151
  const orphans = closableByAppend(messages, suspendedBatch);
151
152
  const recovered = [];
152
153
  const results = interruptedResults(orphans, toolEffects, startedToolCallIds);
153
154
  for (const [i, result] of results.entries()) {
154
- const entryId = await session.appendMessage(interruptedResultMessage(result, Date.now()));
155
- recovered.push({ toolCallId: result.toolCallId, toolName: result.toolName, entryId, text: result.text, errorKind: result.errorKind, args: orphans[i].args });
155
+ const row = interruptedResultMessage(result, Date.now());
156
+ const entryId = await appendAdmittedRow(admitRows, session, row);
157
+ const text = row.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("\n");
158
+ recovered.push({ toolCallId: result.toolCallId, toolName: result.toolName, entryId, text, errorKind: result.errorKind, args: orphans[i].args });
156
159
  }
157
160
  return { recovered };
158
161
  }
@@ -96,6 +96,8 @@ export declare function admitSessionPlacement(sessionId: string, persisted: Sess
96
96
  }, capability: {
97
97
  subagentPlacement: boolean;
98
98
  }): void;
99
+ /** The hooks {@link TtlSessionStore} runs — a member of `hooks` outside it is refused by name. */
100
+ export declare const STORE_HOOK_KEYS: import("./own-property-receipt.js").OptionKeys<SessionStoreHooks>;
99
101
  /**
100
102
  * TTL-cached {@link SessionStore} over a pluggable {@link SessionRepo}.
101
103
  *
@@ -3,7 +3,7 @@ import { isSessionConflict, readSessionListQuery } from "./session.js";
3
3
  import { readRetentionDeclaration } from "./retention.js";
4
4
  import { readMember } from "./thrown-value.js";
5
5
  import { principalNameFault, principalNameOf } from "./principal-name.js";
6
- import { DECLARATION_RECEIPT_MODE, receiptRefusal, receiveOptions, receiveOwnProperties } from "./own-property-receipt.js";
6
+ import { DECLARATION_RECEIPT_MODE, optionKeys, receiptRefusal, receiveMembers, receiveOptions } from "./own-property-receipt.js";
7
7
  import { describeFault, receive } from "./mods/kernel/receive.js";
8
8
  import { describeRejectedValue } from "./tool-search-setting.js";
9
9
  import { readIntegerOption, TIMER_DELAY_MS } from "./integer-option.js";
@@ -25,6 +25,8 @@ export function admitSessionPlacement(sessionId, persisted, request, capability)
25
25
  }
26
26
  }
27
27
  }
28
+ const TTL_SESSION_STORE_OPTION_KEYS = optionKeys()({ defaultTtlDays: 0, sweepIntervalMs: 0, repo: 0, evict: 0, durability: 0, placements: 0, retention: 0, hooks: 0 });
29
+ export const STORE_HOOK_KEYS = optionKeys()({ beforeSessionDelete: 0 });
28
30
  export class TtlSessionStore {
29
31
  retention;
30
32
  durability;
@@ -47,7 +49,7 @@ export class TtlSessionStore {
47
49
  evictPolicy;
48
50
  sweepTimer;
49
51
  constructor(options) {
50
- const opts = receiveOptions(options, "TtlSessionStore");
52
+ const opts = receiveOptions(options, "TtlSessionStore", TTL_SESSION_STORE_OPTION_KEYS);
51
53
  this.retention = readRetentionDeclaration("TtlSessionStoreOptions.retention", opts.retention);
52
54
  const givenRepo = opts.repo;
53
55
  this.repo = givenRepo ?? new InMemorySessionRepo();
@@ -535,11 +537,7 @@ function readStoreHooks(hooks) {
535
537
  return undefined;
536
538
  if (typeof hooks !== "object" || hooks === null)
537
539
  throw receiptRefusal(`TtlSessionStoreOptions.hooks must be an object when given, got ${hooks === null ? "null" : typeof hooks}`);
538
- const got = receiveOwnProperties(hooks, { subject: "TtlSessionStoreOptions.hooks", unit: "hook", moment: "at construction" });
539
- for (const name of Object.keys(got)) {
540
- if (name !== "beforeSessionDelete")
541
- throw receiptRefusal(`TtlSessionStoreOptions.hooks.${name} is not a hook this store runs (it runs beforeSessionDelete)`);
542
- }
540
+ const got = receiveMembers(hooks, { subject: "TtlSessionStoreOptions.hooks", unit: "hook", moment: "at construction" }, STORE_HOOK_KEYS);
543
541
  const hook = got["beforeSessionDelete"];
544
542
  if (hook !== undefined && typeof hook !== "function")
545
543
  throw receiptRefusal(`TtlSessionStoreOptions.hooks.beforeSessionDelete must be a function when given, got ${hook === null ? "null" : typeof hook}`);
@@ -83,7 +83,8 @@ export interface SessionStoreSummary {
83
83
  /**
84
84
  * An ENGINE-minted run identity for this session ({@link import("./types.js").TaskResult.runId}),
85
85
  * recorded by the most recent {@link SessionStore.noteTaskRun} write to LAND.
86
- * {@link lastTaskId} above is `spec.taskId ?? sessionId`, so on the ordinary deployment that supplies no
86
+ * {@link lastTaskId} above is the leg's task id (a background row's id, else the declared one, else the
87
+ * session id), so on the ordinary deployment that supplies no
87
88
  * host task id it answers the SESSION's own id: a "last run" handle that names the session it hangs off
88
89
  * cannot say WHICH run it means. This one names a specific run — read the ORDERING clause below for
89
90
  * exactly how strong "most recent" is here, which is weaker than the sibling field's wording implies.
@@ -0,0 +1,37 @@
1
+ /**
2
+ * The seatbelt confinement a shell start runs under on the engine's macOS host: the launcher, the deny-default base every
3
+ * confined start runs under, the one assembly of a profile from the reads it refuses and the locations it holds in place,
4
+ * and the one wrapping of a start in its floor's profile. Below the engine and the tools both: an environment spawns
5
+ * through {@link confineShellStart} and probes with {@link SEATBELT_PROBE_PROFILE}; the floor's adapter translates its
6
+ * table into the expressions {@link seatbeltProfile} assembles (`ReadFloor.confinement`).
7
+ */
8
+ import type { ReadFloor } from "../internal/harness-types.js";
9
+ /** The seatbelt launcher, by its absolute path (a PATH lookup could run another program in its place). */
10
+ export declare const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
11
+ /** A profile: the base; reads open but for each of `reads` (an expression in the dialect's regex syntax), directory metadata
12
+ * still readable; writes open, and no unlink or create at any of `holds` (a rename cannot carry a refused file out from
13
+ * under its row). No expression on a side ⇒ no block for it. */
14
+ export declare function seatbeltProfile(reads: readonly string[], holds: readonly string[]): string;
15
+ /** The profile of no row: what an environment applies once to learn whether confinement works on this host at all. */
16
+ export declare const SEATBELT_PROBE_PROFILE: string;
17
+ /** A shell start as an environment spawns it: the shell and its arguments, the command last. */
18
+ export interface ShellStart {
19
+ readonly command: string;
20
+ readonly args: readonly string[];
21
+ }
22
+ /**
23
+ * The start confined to `floor` — the one wrapping every environment that spawns on the engine's host takes: no floor ⇒
24
+ * the start as it is (`profile` undefined); a floor ⇒ `sandbox-exec -p <the floor's seatbelt profile>` running the start,
25
+ * with that profile; a floor whose profile cannot be made ⇒ the row and why, and the start must not run. Pure: whether the
26
+ * host can apply a profile at all is the environment's probe, and an apply that fails at the start is the environment's to
27
+ * refuse.
28
+ */
29
+ export declare function confineShellStart(start: ShellStart, floor: ReadFloor | undefined): {
30
+ readonly ok: true;
31
+ readonly start: ShellStart;
32
+ readonly profile: string | undefined;
33
+ } | {
34
+ readonly ok: false;
35
+ readonly row: string;
36
+ readonly reason: string;
37
+ };
@@ -0,0 +1,56 @@
1
+ export const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
2
+ const SEATBELT_BASE = [
3
+ "(version 1)", "(deny default)", "(allow process-exec)", "(allow process-fork)", "(allow process-info* (target same-sandbox))",
4
+ "(allow signal (target same-sandbox))", "(allow mach-priv-task-port (target same-sandbox))", "(allow user-preference-read)", "(allow mach-lookup",
5
+ "(global-name \"com.apple.audio.systemsoundserver\")", "(global-name \"com.apple.distributed_notifications@Uv3\")",
6
+ "(global-name \"com.apple.FontObjectsServer\")", "(global-name \"com.apple.fonts\")", "(global-name \"com.apple.logd\")",
7
+ "(global-name \"com.apple.lsd.mapdb\")", "(global-name \"com.apple.PowerManagement.control\")", "(global-name \"com.apple.system.logger\")",
8
+ "(global-name \"com.apple.system.notification_center\")", "(global-name \"com.apple.system.opendirectoryd.libinfo\")",
9
+ "(global-name \"com.apple.system.opendirectoryd.membership\")", "(global-name \"com.apple.bsd.dirhelper\")",
10
+ "(global-name \"com.apple.securityd.xpc\")", "(global-name \"com.apple.coreservices.launchservicesd\")", ")", "(allow ipc-posix-shm)",
11
+ "(allow ipc-posix-sem)", "(allow iokit-open", "(iokit-registry-entry-class \"IOSurfaceRootUserClient\")",
12
+ "(iokit-registry-entry-class \"RootDomainUserClient\")", "(iokit-user-client-class \"IOSurfaceSendRight\")", ")", "(allow iokit-get-properties)",
13
+ "(allow system-socket (require-all (socket-domain AF_SYSTEM) (socket-protocol 2)))", "(allow sysctl-read", "(sysctl-name \"hw.activecpu\")",
14
+ "(sysctl-name \"hw.busfrequency_compat\")", "(sysctl-name \"hw.byteorder\")", "(sysctl-name \"hw.cacheconfig\")",
15
+ "(sysctl-name \"hw.cachelinesize_compat\")", "(sysctl-name \"hw.cpufamily\")", "(sysctl-name \"hw.cpufrequency\")",
16
+ "(sysctl-name \"hw.cpufrequency_compat\")", "(sysctl-name \"hw.cputype\")", "(sysctl-name \"hw.l1dcachesize_compat\")",
17
+ "(sysctl-name \"hw.l1icachesize_compat\")", "(sysctl-name \"hw.l2cachesize_compat\")", "(sysctl-name \"hw.l3cachesize_compat\")",
18
+ "(sysctl-name \"hw.logicalcpu\")", "(sysctl-name \"hw.logicalcpu_max\")", "(sysctl-name \"hw.machine\")", "(sysctl-name \"hw.memsize\")",
19
+ "(sysctl-name \"hw.ncpu\")", "(sysctl-name \"hw.nperflevels\")", "(sysctl-name \"hw.packages\")", "(sysctl-name \"hw.pagesize_compat\")",
20
+ "(sysctl-name \"hw.pagesize\")", "(sysctl-name \"hw.physicalcpu\")", "(sysctl-name \"hw.physicalcpu_max\")",
21
+ "(sysctl-name \"hw.tbfrequency_compat\")", "(sysctl-name \"hw.vectorunit\")", "(sysctl-name \"kern.argmax\")", "(sysctl-name \"kern.bootargs\")",
22
+ "(sysctl-name \"kern.hostname\")", "(sysctl-name \"kern.maxfiles\")", "(sysctl-name \"kern.maxfilesperproc\")", "(sysctl-name \"kern.maxproc\")",
23
+ "(sysctl-name \"kern.ngroups\")", "(sysctl-name \"kern.osproductversion\")", "(sysctl-name \"kern.osrelease\")", "(sysctl-name \"kern.ostype\")",
24
+ "(sysctl-name \"kern.osvariant_status\")", "(sysctl-name \"kern.osversion\")", "(sysctl-name \"kern.secure_kernel\")",
25
+ "(sysctl-name \"kern.tcsm_available\")", "(sysctl-name \"kern.tcsm_enable\")", "(sysctl-name \"kern.usrstack64\")", "(sysctl-name \"kern.version\")",
26
+ "(sysctl-name \"kern.willshutdown\")", "(sysctl-name \"machdep.cpu.brand_string\")", "(sysctl-name \"machdep.ptrauth_enabled\")",
27
+ "(sysctl-name \"security.mac.lockdown_mode_state\")", "(sysctl-name \"sysctl.proc_cputype\")", "(sysctl-name \"vm.loadavg\")",
28
+ "(sysctl-name-prefix \"hw.optional.arm\")", "(sysctl-name-prefix \"hw.optional.arm.\")", "(sysctl-name-prefix \"hw.optional.armv8_\")",
29
+ "(sysctl-name-prefix \"hw.perflevel\")", "(sysctl-name-prefix \"kern.proc.all\")", "(sysctl-name-prefix \"kern.proc.pgrp.\")",
30
+ "(sysctl-name-prefix \"kern.proc.pid.\")", "(sysctl-name-prefix \"machdep.cpu.\")", "(sysctl-name-prefix \"net.routetable.\")", ")",
31
+ "(allow sysctl-write", "(sysctl-name \"kern.tcsm_enable\")", ")", "(allow distributed-notification-post)",
32
+ "(allow mach-lookup (global-name \"com.apple.SecurityServer\"))", "(allow file-ioctl (literal \"/dev/null\"))",
33
+ "(allow file-ioctl (literal \"/dev/zero\"))", "(allow file-ioctl (literal \"/dev/random\"))", "(allow file-ioctl (literal \"/dev/urandom\"))",
34
+ "(allow file-ioctl (literal \"/dev/dtracehelper\"))", "(allow file-ioctl (literal \"/dev/tty\"))",
35
+ "(allow file-ioctl file-read-data file-write-data", "(require-all", "(literal \"/dev/null\")", "(vnode-type CHARACTER-DEVICE)", ")", ")",
36
+ "(allow network*)",
37
+ ];
38
+ export function seatbeltProfile(reads, holds) {
39
+ const filters = (xs) => xs.map((x) => `(regex ${JSON.stringify(x)})`);
40
+ const lines = [...SEATBELT_BASE, "(allow file-read*)"];
41
+ if (reads.length > 0)
42
+ lines.push("(deny file-read*", ...filters(reads), ")", "(allow file-read-metadata (vnode-type DIRECTORY))");
43
+ lines.push("(allow file-write*)");
44
+ if (holds.length > 0)
45
+ lines.push("(deny file-write-unlink file-write-create", ...filters(holds), ")");
46
+ return lines.join("\n");
47
+ }
48
+ export const SEATBELT_PROBE_PROFILE = seatbeltProfile([], []);
49
+ export function confineShellStart(start, floor) {
50
+ if (floor === undefined)
51
+ return { ok: true, start, profile: undefined };
52
+ const c = floor.confinement("seatbelt");
53
+ if (!c.ok)
54
+ return c;
55
+ return { ok: true, start: { command: SANDBOX_EXEC, args: ["-p", c.profile, start.command, ...start.args] }, profile: c.profile };
56
+ }
@@ -5,7 +5,7 @@ import { inlineUntrusted } from "./untrusted-text.js";
5
5
  import { boundInputHashOf } from "./canonical-json.js";
6
6
  import { NOT_BINDABLE } from "./skill-grant-binding.js";
7
7
  import { readToolNameList } from "./tool-name-list.js";
8
- import { closestName } from "./task-registry-shared.js";
8
+ import { closestName } from "./closest-name.js";
9
9
  import { allowingRows, strippedInAuto, compileAllowList, readRuleEntry, inertEntryPhrase, judgeAllowEntries, nonListValueLabel, renderListEntry, spelledListEntry } from "./allow-entry.js";
10
10
  export const SKILL_GRANT_ORIGINS = Object.freeze(["model", "user", "inherited"]);
11
11
  const FROZEN_SKILL_GRANT_ORIGINS = new Set(["model", "inherited"]);
@@ -63,7 +63,7 @@ export declare const EXPECTED_LISTBYSCOPE_SUMMARIES: ({
63
63
  severity: number;
64
64
  deadline: number;
65
65
  createdAt: number;
66
- sourceTaskId: string;
66
+ sourceSessionId: string;
67
67
  principal: string;
68
68
  toolCallId: string;
69
69
  toolName: string;
@@ -82,7 +82,7 @@ export declare const EXPECTED_LISTBYSCOPE_SUMMARIES: ({
82
82
  createdAt: number;
83
83
  severity?: undefined;
84
84
  deadline?: undefined;
85
- sourceTaskId?: undefined;
85
+ sourceSessionId?: undefined;
86
86
  principal?: undefined;
87
87
  toolCallId?: undefined;
88
88
  toolName?: undefined;
@@ -430,6 +430,19 @@ export async function checkpointStoreContract(make, runAssertion, options = {})
430
430
  const bareBack = (await store.get(bare.token));
431
431
  assert.equal("requires" in bareBack || "requirementsDigest" in bareBack, false, "a row without a list or digest must stay without (never [] / null / \"\")");
432
432
  });
433
+ run("held rows: a row's `heldRows` (the conversation rows owed after its leaf) survive the round-trip verbatim — every row, in its order, each member of each (text blocks, a string content, `provenance`, `rewrittenBy`); a row without them stays without", async () => {
434
+ const store = make();
435
+ const heldRows = [
436
+ { role: "user", content: "first note", timestamp: 1, provenance: "engine-note" },
437
+ { role: "user", content: [{ type: "text", text: "second note, rewritten" }], timestamp: 2, provenance: "engine-note", rewrittenBy: ["scrubber", "tagger"] },
438
+ ];
439
+ const held = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "held-rows", heldRows });
440
+ const bare = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "held-none" });
441
+ for (const cp of [held, bare])
442
+ await store.put(cp.token, cp);
443
+ assert.deepEqual((await store.get(held.token)).heldRows, heldRows, "the held rows must survive the round-trip as the same rows, in the same order, every member kept");
444
+ assert.equal("heldRows" in (await store.get(bare.token)), false, "a row without held rows must stay without (never [] / null)");
445
+ });
433
446
  run("run origin: a row's `state.runOrigin` survives the round-trip verbatim and rides the listing; absent stays absent; a word outside the set is kept on the row and reads as absent in the listing", async () => {
434
447
  const store = make();
435
448
  const member = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "ro-member" });
@@ -633,7 +646,7 @@ export async function checkpointListByScopeSummaries(store) {
633
646
  sessionId: "needs-approval",
634
647
  deadline: 1_999_999_999_999,
635
648
  createdAt: 1_700_000_000_000,
636
- sourceTaskId: "needs-approval",
649
+ sourceSessionId: "needs-approval",
637
650
  principal: "alice@corp",
638
651
  gate: {
639
652
  kind: "human",
@@ -681,7 +694,7 @@ export const EXPECTED_LISTBYSCOPE_SUMMARIES = [
681
694
  severity: 5,
682
695
  deadline: 1_999_999_999_999,
683
696
  createdAt: 1_700_000_000_000,
684
- sourceTaskId: "needs-approval",
697
+ sourceSessionId: "needs-approval",
685
698
  principal: "alice@corp",
686
699
  toolCallId: "call-pr",
687
700
  toolName: "open_pr",
@@ -1,3 +1,6 @@
1
- import type { FileHistoryStore } from "../file-history-store.js";
1
+ import { type FileHistoryStore } from "../file-history-store.js";
2
2
  import { type ContractAssertionRunner } from "./contract-harness.js";
3
- export declare function fileHistoryStoreContract(make: () => FileHistoryStore, runAssertion?: ContractAssertionRunner): Promise<void>;
3
+ export declare function fileHistoryStoreContract(make: () => FileHistoryStore, runAssertion?: ContractAssertionRunner, onOptionalMember?: (report: {
4
+ member: "blobExchange";
5
+ status: "verified" | "absent";
6
+ }) => void): Promise<void>;
@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
3
3
  import { chmod, mkdtemp, mkdir, rm, stat, symlink, writeFile, readFile } from "node:fs/promises";
4
4
  import { tmpdir } from "node:os";
5
5
  import { join } from "node:path";
6
+ import { fileHistoryBlobExchangeOf } from "../file-history-store.js";
6
7
  import { isGovernanceRetryClass } from "../governance-codes.js";
7
8
  import { NodeExecutionEnv } from "../../internal/harness.js";
8
9
  import { beginContract } from "./contract-harness.js";
@@ -51,8 +52,31 @@ async function withTree(fn) {
51
52
  await rm(dir, { recursive: true, force: true });
52
53
  }
53
54
  }
54
- export async function fileHistoryStoreContract(make, runAssertion) {
55
+ export async function fileHistoryStoreContract(make, runAssertion, onOptionalMember) {
55
56
  const { run, settle } = beginContract(runAssertion);
57
+ run("blobExchange (optional member group): read as one group; put checks the address and stores nothing it refuses; has answers from the index; get round-trips; absence is REPORTED", async () => {
58
+ const exchange = fileHistoryBlobExchangeOf(make());
59
+ if (exchange === undefined) {
60
+ onOptionalMember?.({ member: "blobExchange", status: "absent" });
61
+ return;
62
+ }
63
+ const bytes = new TextEncoder().encode("bytes another machine sent ahead of its import");
64
+ const other = new TextEncoder().encode("different bytes");
65
+ const hash = createHash("sha256").update(bytes).digest("hex");
66
+ const otherHash = createHash("sha256").update(other).digest("hex");
67
+ assert.deepEqual([...(await exchange.has([hash]))], [], "nothing is held before the put");
68
+ assert.equal(await exchange.get(hash), undefined, "get answers undefined for bytes the store does not hold");
69
+ const wrong = await exchange.put(otherHash, bytes);
70
+ assert.equal(wrong.ok, false, "bytes that do not hash to the address are refused");
71
+ assert.equal(!wrong.ok && wrong.error.code, "adopt_failed", "the refusal is the adoption family's word");
72
+ assert.equal(!wrong.ok && wrong.error.permanence, "terminal", "no retry makes the bytes hash differently");
73
+ assert.deepEqual([...(await exchange.has([otherHash, hash]))], [], "a refused put stores nothing under either address");
74
+ assert.deepEqual(await exchange.put(hash, bytes), { ok: true });
75
+ assert.deepEqual(await exchange.put(hash, bytes), { ok: true }, "a repeat put is idempotent");
76
+ assert.deepEqual([...(await exchange.has([hash, otherHash]))], [hash], "has names the held ones only");
77
+ assert.deepEqual([...((await exchange.get(hash)) ?? [])], [...bytes], "get round-trips the bytes");
78
+ onOptionalMember?.({ member: "blobExchange", status: "verified" });
79
+ });
56
80
  run("absent everything: canRestore=false, restore=failed/not_found with an empty ledger, reap=0 — and none of it throws", async () => {
57
81
  await withTree(async (dir, env) => {
58
82
  const store = make();
@@ -54,7 +54,7 @@ export interface MailboxCrossProcessContractHooks {
54
54
  /**
55
55
  * T2 可选能力层(cross-process 分册,design/385 §1.2⑥ / G11)—— 声明 `crossProcessSafe: true` 的后端必须
56
56
  * 过的全套判据。钉的是**整套**(跨进程 seq 单铸 + lease/ack 不交叉 + 一方的 housekeeping 不丢另一方的
57
- * 已落盘 append + reap/drop 的 seq 语义跨进程成立),不是「有锁」:一把锁配一份陈旧缓存照样在锁内铸
57
+ * 已落盘 append + reap/drop 的 seq 语义跨进程成立 + 已收窗跨进程共享),不是「有锁」:一把锁配一份陈旧缓存照样在锁内铸
58
58
  * 重号、照样把别人的消息压缩掉——所以每一条都从**对方进程的视角**回读。
59
59
  *
60
60
  * 受众:文件后端(本仓捆绑)、SQL 后端(事务天然过)。进程内 Map 的参照实现与 CC inbox 适配器不声明,
@@ -63,11 +63,18 @@ export interface MailboxCrossProcessContractHooks {
63
63
  */
64
64
  export declare function mailboxCrossProcessContract(hooks: MailboxCrossProcessContractHooks): Promise<void>;
65
65
  export interface MailboxTombstonedRecipientContractHooks {
66
- /** Put `(scope, handle)` into the deployment's PRE-DELETE state — whatever that is for this
67
- * backend (a cascade marking the session row, a `deleting` column, a tombstone table). Core does
68
- * not name the mechanism, only what `append` must then do. */
69
- tombstone: (store: MailboxStore, scope: string, handle: string) => Promise<void>;
66
+ /** Put `(scope, handle)` into the deployment's PRE-DELETE state, for a backend that keeps the state
67
+ * outside the store face (a cascade marking the session row, a `deleting` column). A store that
68
+ * carries the recipient-lifecycle pair (`retireRecipient` / `listRetiredRecipients`) is retired
69
+ * through its own `retireRecipient` instead, and then this hook is refused: two ways to write one
70
+ * state are two readings of it. */
71
+ tombstone?: (store: MailboxStore, scope: string, handle: string) => Promise<void>;
70
72
  runAssertion?: ContractAssertionRunner;
73
+ /** The observable channel for the optional pair: a case name cannot carry "verified" vs "absent". */
74
+ onOptionalMember?: (report: {
75
+ member: "recipientLifecycle";
76
+ status: "verified" | "absent";
77
+ }) => void;
71
78
  }
72
79
  /**
73
80
  * T2 可选能力层(pre-delete 分册)—— 只挂**看得见收件人生命周期**的后端:它的 mailbox 行与某个