@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
@@ -2,6 +2,7 @@ import { randomBytes, randomUUID } from "node:crypto";
2
2
  import { uuidv7 } from "../internal/harness.js";
3
3
  import { PROBE_CAUSE_PATH_MAX, PROBE_REASON_MAX, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
4
4
  import { carriesBidiControls } from "./tool-policy.js";
5
+ import { agentIdOf, legTaskIdOf } from "./leg-identity.js";
5
6
  import { isAutoModeFallbackCause, readDenialLimitFallback } from "./auto-mode.js";
6
7
  import { isAskOrigin, isPermissionMode, isPersistedRuleMandate } from "./ask-origin.js";
7
8
  import { isRunOrigin, RUN_ORIGINS } from "./run-origin.js";
@@ -15,7 +16,7 @@ import { renderUntrustedCommandText, stripFormatCharacters } from "./permission-
15
16
  import { egressText } from "./untrusted-egress.js";
16
17
  import { steerReplayRefusal } from "./steer-replay.js";
17
18
  import { readRetentionDeclaration } from "./retention.js";
18
- import { receiveOptions } from "./own-property-receipt.js";
19
+ import { optionKeys, receiveOptions } from "./own-property-receipt.js";
19
20
  export function mintCheckpointToken() {
20
21
  return randomBytes(16).toString("hex");
21
22
  }
@@ -307,6 +308,7 @@ export function summarizeCheckpoint(cp, disclose) {
307
308
  const hasBidi = tool !== undefined &&
308
309
  (facts.hasBidiControls === true ||
309
310
  carriesBidiControls([toolInput, tool.preview], { maxNodes: BIDI_BACKFILL_MAX_NODES, maxChars: BIDI_BACKFILL_MAX_CHARS }));
311
+ const agentId = agentIdOf({ taskId: legTaskIdOf({}, cp.state, cp.sessionId), isDelegatedChild: cp.state.isDelegatedChild === true });
310
312
  return {
311
313
  token: facts.token,
312
314
  ...(cp.checkpointId !== undefined ? { checkpointId: cp.checkpointId } : {}),
@@ -317,7 +319,8 @@ export function summarizeCheckpoint(cp, disclose) {
317
319
  ...(cp.resourceLedger !== undefined ? { spentMicroUsd: cp.resourceLedger.spentMicroUsd } : {}),
318
320
  ...(facts.deadline !== null ? { deadline: facts.deadline } : {}),
319
321
  createdAt: facts.createdAt,
320
- ...(cp.sourceTaskId !== undefined ? { sourceTaskId: cp.sourceTaskId } : {}),
322
+ ...(cp.sourceSessionId !== undefined ? { sourceSessionId: cp.sourceSessionId } : {}),
323
+ ...(agentId !== undefined ? { agentId } : {}),
321
324
  ...(cp.principal !== undefined ? { principal: cp.principal } : {}),
322
325
  ...(facts.toolCallId !== null ? { toolCallId: facts.toolCallId } : {}),
323
326
  ...(requestedByCallId !== undefined ? { requestedByCallId } : {}),
@@ -347,7 +350,7 @@ export function summarizeCheckpoint(cp, disclose) {
347
350
  ...(hasBidi ? { hasBidiControls: true } : {}),
348
351
  };
349
352
  }
350
- export const CHECKPOINT_CONFIG_REFUSAL_CODES = Object.freeze(["config.spec_retired_key", "config.output_style_invalid", "config.permission_mode_invalid", "config.shell_gate_value_retired", "config.approval_reach_invalid", "config.run_origin_invalid", "config.user_invoked_skill_unknown", "config.skill_deny_unreadable", "config.user_attachment_invalid", "config.tool_face_control", "config.deps_retired_key", "config.peer_presence_invalid", "config.tool_model_gate_invalid", "config.microcompact_invalid", "config.prompt_selector_invalid", "resume_at.conflicts_resume", "resume_at.mode_without_target", "config.read_face_invalid", "config.write_face_invalid", "config.invalid_argument", "config.tool_face_invalid", "config.memory_delegation_evidence", "config.memory_provenance", "config.memory_capture_policy", "config.cross_boundary_posture", "config.advisor_tool_invalid", "config.advisor_model_invalid", "config.auto_consolidation", "config.unknown_role", "config.tool_materialize_invalid", "config.memory_persistence_invalid", "config.tool_materialize_unreachable", "config.locked_registry", "config.locked_key", "config.mcp_content_class", "config.skill_listing_budget_invalid", "config.limit_unknown_key", "config.limit_invalid", "config.attachment_invalid", "config.usage_window_invalid", "config.brain_call_guardrail_invalid", "config.retention_policy", "config.retention_capability", "config.invalid_checkpoint_store", "config.skill_base_dir_invalid", "config.host_floor_invalid", "config.credential_in_declaration", "config.credential_ref_invalid", "config.peer_seat_missing"]);
353
+ export const CHECKPOINT_CONFIG_REFUSAL_CODES = Object.freeze(["config.spec_retired_key", "config.output_style_invalid", "config.permission_mode_invalid", "config.shell_gate_value_retired", "config.approval_reach_invalid", "config.run_origin_invalid", "config.user_invoked_skill_unknown", "config.skill_deny_unreadable", "config.user_attachment_invalid", "config.tool_face_control", "config.deps_retired_key", "config.peer_presence_invalid", "config.tool_model_gate_invalid", "config.microcompact_invalid", "config.prompt_selector_invalid", "resume_at.conflicts_resume", "resume_at.mode_without_target", "config.read_face_invalid", "config.write_face_invalid", "config.invalid_argument", "config.tool_face_invalid", "config.memory_delegation_evidence", "config.memory_provenance", "config.memory_capture_policy", "config.cross_boundary_posture", "config.advisor_tool_invalid", "config.advisor_model_invalid", "config.auto_consolidation", "config.unknown_role", "config.tool_materialize_invalid", "config.memory_persistence_invalid", "config.tool_materialize_unreachable", "config.locked_registry", "config.locked_key", "config.mcp_content_class", "config.skill_listing_budget_invalid", "config.limit_unknown_key", "config.limit_invalid", "config.attachment_invalid", "config.usage_window_invalid", "config.brain_call_guardrail_invalid", "config.retention_policy", "config.retention_capability", "config.invalid_checkpoint_store", "config.skill_base_dir_invalid", "config.host_floor_invalid", "config.credential_in_declaration", "config.credential_ref_invalid", "config.peer_seat_missing", "config.spec_member_unreadable", "config.spec_unknown_key"]);
351
354
  export const isCheckpointConfigRefusalCode = (word) => CHECKPOINT_CONFIG_REFUSAL_CODES.some((w) => w === word);
352
355
  export class CheckpointError extends Error {
353
356
  code;
@@ -574,6 +577,7 @@ export function appendPendingSteer(state, entry) {
574
577
  export function checkpointRowMatches(cp, scope, status) {
575
578
  return cp !== undefined && cp.scope === scope && cp.status === status;
576
579
  }
580
+ const IN_MEMORY_CHECKPOINT_STORE_OPTION_KEYS = optionKeys()({ disclose: 0, sessionHeadOf: 0, holderIsCurrent: 0, retention: 0 });
577
581
  export class InMemoryCheckpointStore {
578
582
  retention;
579
583
  durability = "process-local";
@@ -584,7 +588,7 @@ export class InMemoryCheckpointStore {
584
588
  disclose;
585
589
  holderIsCurrent;
586
590
  constructor(options) {
587
- const opts = receiveOptions(options, "InMemoryCheckpointStore");
591
+ const opts = receiveOptions(options, "InMemoryCheckpointStore", IN_MEMORY_CHECKPOINT_STORE_OPTION_KEYS);
588
592
  this.retention = readRetentionDeclaration("InMemoryCheckpointStore.retention", opts.retention);
589
593
  this.disclose = opts.disclose;
590
594
  this.holderIsCurrent = opts.holderIsCurrent;
@@ -259,8 +259,9 @@ export declare function clampRecordError(message: string): Error & {
259
259
  /**
260
260
  * Refuse a caller-supplied clamp record that names a seat the table does not have (or, with `carrier`, a row another
261
261
  * carrier hands on): a name nobody reads would sit on the record as if wired — the silent drop the retired-key door
262
- * exists to prevent. `extra` names the record's own members that are not rows. Absent ⇒ nothing to judge; a member
263
- * whose value is `undefined` carries nothing and is read as absent (the retired-key door's presence rule).
262
+ * exists to prevent. `extra` names the record's own members that are not rows. Absent ⇒ nothing to judge. The record is
263
+ * judged by the engine's one name judgment (every own key a row's name, whatever its value: a stray key holding `undefined`
264
+ * is a stray key); no value is read here — the readers read the record itself.
264
265
  */
265
266
  export declare function assertClampRecord(record: unknown, owner: string, carrier?: ClampCarrier, extra?: readonly string[]): void;
266
267
  /**
@@ -1,5 +1,6 @@
1
1
  import { readDenyEntryProblem } from "../tools/fs/read-deny.js";
2
2
  import { COMPLIANCE_CAPABILITIES, complianceCapabilityProblem } from "./compliance.js";
3
+ import { strayMembersOf } from "./own-property-receipt.js";
3
4
  import { writeProtectedEntryIdentity, writeProtectedEntryProblem } from "./write-protect.js";
4
5
  function readDenyIdentity(entry) {
5
6
  return typeof entry === "string" ? `i:${entry}` : `${entry.caseSensitive === true ? "s" : "i"}:${entry.pattern}`;
@@ -235,9 +236,9 @@ export function assertClampRecord(record, owner, carrier, extra = []) {
235
236
  if (record === null || typeof record !== "object")
236
237
  throw clampRecordError(`${owner} must be a record of clamp seats, got ${record === null ? "null" : typeof record}`);
237
238
  const legal = [...ROWS.filter(([, row]) => carrier === undefined || row.carrier === carrier).map(([seat]) => seat), ...extra];
238
- const unknown = Object.keys(record).filter((k) => record[k] !== undefined && !legal.includes(k));
239
- if (unknown.length > 0) {
240
- throw clampRecordError(`${owner} names ${unknown.map((k) => JSON.stringify(k)).join(", ")}, which the clamp table does not carry there — the legal seats are ${legal.join(", ")}. Refused rather than ignored: a seat nobody reads would read to the caller as wired.`);
239
+ const unknown = strayMembersOf(record, { subject: owner, unit: "clamp seat", moment: "when the record is handed in" }, legal)?.names;
240
+ if (unknown !== undefined) {
241
+ throw clampRecordError(`${owner} names ${unknown.map((k) => JSON.stringify(String(k))).join(", ")}, which the clamp table does not carry there — the legal seats are ${legal.join(", ")}. Refused rather than ignored: a seat nobody reads would read to the caller as wired.`);
241
242
  }
242
243
  }
243
244
  export function readClampFloor(floor) {
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The engine's one "did you mean" reading: the nearest name to a misspelled one, within two edits. A leaf (it imports
3
+ * nothing), so a low-level door — the options receipt — can name the near miss without depending on the task registry
4
+ * that first needed it.
5
+ */
6
+ /** CC `gtr` (fable 复审 F1 — 亲核 @16169850: NOT plain Levenshtein but OSA / restricted
7
+ * Damerau-Levenshtein, WITH the adjacent-transposition term `o[i][s]=min(o[i][s], o[i-2][s-2]+1)`
8
+ * when `e[i-1]===t[s-2] && e[i-2]===t[s-1]`). The transposition matters: a typo like "tset"→"test"
9
+ * is distance 1 (CC has a Did-you-mean), plain Levenshtein would call it 2. */
10
+ export declare function editDistance(a: string, b: string): number;
11
+ /** CC `htr` shape (206:519814-519827): candidates within Levenshtein ≤2 (length-diff ≤2 pre-filter),
12
+ * best-first; the single best is the "Did you mean" suggestion (`htr(e, keys, 1)[0]`, 206:575196). */
13
+ export declare function closestName(query: string, candidates: Iterable<string>): string | undefined;
@@ -0,0 +1,35 @@
1
+ export function editDistance(a, b) {
2
+ if (a === b)
3
+ return 0;
4
+ const m = a.length;
5
+ const n = b.length;
6
+ const d = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
7
+ for (let i = 1; i <= m; i++) {
8
+ for (let j = 1; j <= n; j++) {
9
+ const cost = a[i - 1] === b[j - 1] ? 0 : 1;
10
+ d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
11
+ if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
12
+ d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
13
+ }
14
+ }
15
+ }
16
+ return d[m][n];
17
+ }
18
+ export function closestName(query, candidates) {
19
+ let best;
20
+ let bestDist = 3;
21
+ const seen = new Set();
22
+ for (const c of candidates) {
23
+ if (seen.has(c))
24
+ continue;
25
+ seen.add(c);
26
+ if (Math.abs(c.length - query.length) > 2)
27
+ continue;
28
+ const dist = editDistance(query, c);
29
+ if (dist <= 2 && dist < bestDist) {
30
+ bestDist = dist;
31
+ best = c;
32
+ }
33
+ }
34
+ return best;
35
+ }
@@ -1,4 +1,6 @@
1
1
  import { tierAliasVia } from "./roles.js";
2
+ import { optionKeys, receiveMembers } from "./own-property-receipt.js";
3
+ const OVERLAY_KEYS = optionKeys()({ contextTokens: 0, autoCompactTokens: 0, enabled: 0 });
2
4
  export function contextOverlayFor(settings, ref, catalog) {
3
5
  if (settings === undefined || typeof ref !== "string")
4
6
  return undefined;
@@ -26,11 +28,7 @@ export function assertContextSettingsValue(v, where) {
26
28
  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
27
29
  throw new Error(`${where}: contextSettings[${JSON.stringify(word)}] must be a plain object (got ${raw === null ? "null" : Array.isArray(raw) ? "array" : typeof raw})`);
28
30
  }
29
- const o = raw;
30
- const unknown = Object.keys(o).filter((k) => k !== "contextTokens" && k !== "autoCompactTokens" && k !== "enabled");
31
- if (unknown.length > 0) {
32
- throw new Error(`${where}: contextSettings[${JSON.stringify(word)}] carries ${unknown.map((k) => JSON.stringify(k)).join(", ")} — this seat declares window geometry only (contextTokens | autoCompactTokens | enabled); routing, pricing and fencing stay on the model card`);
33
- }
31
+ const o = receiveMembers(raw, { subject: `${where}: contextSettings[${JSON.stringify(word)}]`, unit: "member", moment: "when the overlay is read" }, OVERLAY_KEYS, (_, unknown) => new Error(`${where}: contextSettings[${JSON.stringify(word)}] carries ${unknown.map((k) => JSON.stringify(String(k))).join(", ")} — this seat declares window geometry only (contextTokens | autoCompactTokens | enabled); routing, pricing and fencing stay on the model card`));
34
32
  for (const k of ["contextTokens", "autoCompactTokens"]) {
35
33
  const n = o[k];
36
34
  if (n !== undefined && (typeof n !== "number" || !Number.isFinite(n) || n <= 0)) {
@@ -57,7 +57,7 @@ export interface BoundaryLegsGiven {
57
57
  readonly legs: readonly BoundaryLeg[];
58
58
  readonly env?: Pick<ExecutionEnv, "capabilities">;
59
59
  }
60
- /** What a leg's session is still owed when the leg ends: the legs each unfinished background task its access (the TaskOutput reach) delivers
60
+ /** What a leg's session is still owed when the leg ends: the legs each unfinished background task its access (the registry task access) delivers
61
61
  * along, read as the poll the session's next leg — another tree — would make of it (`TaskRegistry.owedDeliveries`). */
62
62
  export type OwedDeliveries = () => readonly BoundaryLegsGiven[];
63
63
  declare const CROSS_BOUNDARY_TREE_TOKEN: unique symbol;
@@ -1,4 +1,4 @@
1
- import type { AssertAllKeysHandled } from "./ask-origin.js";
1
+ import { type AssertAllKeysHandled } from "./ask-origin.js";
2
2
  import type { DecisionMember, PermissionResult } from "./tool-policy.js";
3
3
  export declare const refusedOutOfContract: (message: string) => PermissionResult;
4
4
  /** Is `d` a refusal the engine itself minted (by object identity — a look-alike `deny` a caller built is not one)? The receipt's
@@ -47,6 +47,7 @@ export declare const DECISION_MEMBER_ARMS: Readonly<{
47
47
  readonly origin: readonly ["ask"];
48
48
  readonly askClass: readonly ["ask"];
49
49
  readonly classes: readonly ["ask"];
50
+ readonly askReasons: readonly ["ask"];
50
51
  readonly ruleUnreadable: readonly ["ask"];
51
52
  readonly authoredBy: readonly ["ask"];
52
53
  readonly editRewritten: readonly ["ask"];
@@ -54,6 +55,17 @@ export declare const DECISION_MEMBER_ARMS: Readonly<{
54
55
  export type DecisionMemberArmsCoverTheUnion = AssertAllKeysHandled<{
55
56
  [M in DecisionMember]: Exclude<ArmOf<M>, (typeof DECISION_MEMBER_ARMS)[M][number]>;
56
57
  }[DecisionMember]>;
58
+ /**
59
+ * The members a PreToolUse hook's answer carries beyond the decision's, with their arms — the hook seat's half of the member ×
60
+ * arm table, read by the same screen: `additionalContext` (the text appended for the model, any arm) and `questionCause` (WHY
61
+ * the hook asked, {@link import("./ask-origin.js").HookQuestionCause} — the ask arm only). The hook seat's member list is the
62
+ * decision's plus these.
63
+ */
64
+ export declare const HOOK_SEAT_MEMBER_ARMS: Readonly<{
65
+ readonly additionalContext: readonly ["allow", "ask", "deny"];
66
+ readonly questionCause: readonly ["ask"];
67
+ }>;
68
+ export type HookSeatMember = keyof typeof HOOK_SEAT_MEMBER_ARMS;
57
69
  /**
58
70
  * WHO writes each member of the decision union — one writer per fact, one table (fenced to the union like
59
71
  * {@link DECISION_MEMBER_ARMS}: a member the union gains without a row is a type error):
@@ -85,6 +97,7 @@ export declare const DECISION_MEMBER_WRITERS: Readonly<{
85
97
  readonly origin: "stamp";
86
98
  readonly askClass: "stamp";
87
99
  readonly classes: "stamp";
100
+ readonly askReasons: "stamp";
88
101
  readonly ruleUnreadable: "composer";
89
102
  readonly authoredBy: "composer";
90
103
  readonly editRewritten: "composer";
@@ -1,4 +1,5 @@
1
1
  import { types } from "node:util";
2
+ import { HOOK_QUESTION_CAUSES, isHookQuestionCause } from "./ask-origin.js";
2
3
  import { AUTO_MODE_FALLBACK_CAUSES, isAutoModeFallbackCause, isDenialLimitBound } from "./auto-mode.js";
3
4
  import { thrownText } from "./thrown-value.js";
4
5
  const ENGINE_REFUSALS = new WeakSet();
@@ -26,6 +27,7 @@ const CLOSED_MEMBERS = [
26
27
  { member: "probeMandated", words: [true], has: (v) => v === true },
27
28
  { member: "crossBoundaryMandated", words: [true], has: (v) => v === true },
28
29
  { member: "mandated", words: [true], has: (v) => v === true },
30
+ { member: "questionCause", words: HOOK_QUESTION_CAUSES, has: isHookQuestionCause },
29
31
  ];
30
32
  const EVERY_ARM = ["allow", "ask", "deny"];
31
33
  const ASK = ["ask"];
@@ -33,15 +35,16 @@ export const DECISION_MEMBER_ARMS = Object.freeze({
33
35
  action: EVERY_ARM, updatedInput: EVERY_ARM, message: EVERY_ARM, decisionReason: EVERY_ARM, attestation: EVERY_ARM,
34
36
  requiresRealApproval: ASK, denialLimitFallback: ASK, classifierNoRuling: ASK, allowRuleShadowed: ASK, probeReason: ASK, probeCause: ASK,
35
37
  probeMandated: ASK, crossBoundaryMandated: ASK, mandated: ASK, mandate: ASK, probeReadRootCandidate: ASK, matchedAskRule: ASK, ruleEvidence: ASK,
36
- segmentCoverage: ASK, origin: ASK, askClass: ASK, classes: ASK, ruleUnreadable: ASK, authoredBy: ASK,
38
+ segmentCoverage: ASK, origin: ASK, askClass: ASK, classes: ASK, askReasons: ASK, ruleUnreadable: ASK, authoredBy: ASK,
37
39
  editRewritten: ASK,
38
40
  });
41
+ export const HOOK_SEAT_MEMBER_ARMS = Object.freeze({ additionalContext: EVERY_ARM, questionCause: ASK });
39
42
  export const DECISION_MEMBER_WRITERS = Object.freeze({
40
43
  action: "composer", updatedInput: "composer", message: "composer", decisionReason: "composer", attestation: "record",
41
44
  requiresRealApproval: "composer", denialLimitFallback: "composer", classifierNoRuling: "composer", allowRuleShadowed: "stamp", probeReason: "composer",
42
45
  probeCause: "composer", probeMandated: "composer", crossBoundaryMandated: "composer", mandated: "composer", mandate: "stamp",
43
46
  probeReadRootCandidate: "composer", matchedAskRule: "composer", ruleEvidence: "stamp", segmentCoverage: "stamp", origin: "stamp", askClass: "stamp",
44
- classes: "stamp", ruleUnreadable: "composer", authoredBy: "composer", editRewritten: "composer",
47
+ classes: "stamp", askReasons: "stamp", ruleUnreadable: "composer", authoredBy: "composer", editRewritten: "composer",
45
48
  });
46
49
  const STAMP_MEMBERS = Object.keys(DECISION_MEMBER_WRITERS).filter((m) => DECISION_MEMBER_WRITERS[m] === "stamp");
47
50
  const RETIRED_WINDOW_MEMBER = "autoDenyAfterMs";
@@ -101,7 +104,7 @@ export function screenContractValues(contract, opts) {
101
104
  return unrecognized(member, v, words);
102
105
  }
103
106
  const arm = contract.action;
104
- for (const [member, arms] of Object.entries(DECISION_MEMBER_ARMS)) {
107
+ for (const [member, arms] of Object.entries({ ...DECISION_MEMBER_ARMS, ...HOOK_SEAT_MEMBER_ARMS })) {
105
108
  if (contract[member] === undefined || (arm === undefined ? EVERY_ARM.every((a) => arms.includes(a)) : arms.includes(arm)))
106
109
  continue;
107
110
  return refusedOutOfContract(`a permission decision carries "${member}" on ${arm === undefined ? "a result with no action (no opinion)" : `its "${arm}" arm`} — the member belongs to ` +
@@ -11,8 +11,10 @@ import type { TaskEvent } from "./task-event.js";
11
11
  /**
12
12
  * design/129-B — one lifecycle event of a BACKGROUND delegation child, delivered to the
13
13
  * process-level {@link RunnerDeps.onBackgroundChildEvent} observer. Keys: `taskId` is the registry handle
14
- * (`a*` domain — the TaskOutput/TaskStop key); `progressTaskId`/`sessionId` are the child RUN's id (uuid
15
- * domain — the same key `task_progress` frames carry).
14
+ * (`a*` domain — the TaskStop / host-poll key), which is also the child run's own task id, so the child's
15
+ * own `task_progress` frames carry it; `sessionId` is the child run's session (uuid domain);
16
+ * `progressTaskId` is the task id of the leg whose frame a tick forwards (the child's own, or a nested
17
+ * descendant's).
16
18
  *
17
19
  * `kind: "spawn"` announces a fleet ROW's birth, which is a different fact from a child RUN's start
18
20
  * (`TaskEvent` `task_started`): an `a*` row is born when its lane registers it, before the child run
@@ -24,9 +26,9 @@ export interface BackgroundChildEvent {
24
26
  kind: "spawn" | "tick" | "terminal";
25
27
  /** Row key, stable across all three kinds. The prefix is the DOMAIN DISCRIMINATOR (load-bearing,
26
28
  * not opaque — design/149): `a*` = registry handle (background subagent —
27
- * TaskOutput/TaskStop addressable, fleet-footer display lane); `wa*` = synthetic workflow-agent
28
- * row (NOT a registry row — per-agent read face is the workflow's `TaskOutput(w*)` agent_runs
29
- * projection + journal API). Display contract (CC anchor): CC's footer renders ONLY the
29
+ * TaskStop addressable, fleet-footer display lane); `wa*` = synthetic workflow-agent
30
+ * row (NOT a registry row — per-agent read face is the workflow run's agent rows in its completion
31
+ * record + journal API). Display contract (CC anchor): CC's footer renders ONLY the
30
32
  * workflow AGGREGATE row — `wa*` rows are read-face/observability rows and SHOULD NOT be
31
33
  * rendered in the footer fleet tree; shells filter on the prefix. */
32
34
  taskId: string;
@@ -79,9 +81,10 @@ export interface BackgroundChildEvent {
79
81
  * authority; this field is the row-level convenience beside it.
80
82
  */
81
83
  model?: string;
82
- /** spawn: the HOST task's DECLARED task id (parent attribution). Omitted when the host
83
- * run declared no task id (the `spec.taskId ?? sessionId` fallback would launder a session id into
84
- * a task-id field — the orphan-pointer shape); {@link parentSessionId} is the always-on linkage. */
84
+ /** spawn: the HOST leg's task id (parent attribution) — a host declared id, or the parent row's id
85
+ * when the host is itself a background sub-agent. Omitted when the host's task id is just its
86
+ * session id (a host that declared none, or a foreground child): writing it would launder a session
87
+ * id into a task-id field — the orphan-pointer shape; {@link parentSessionId} is the always-on linkage. */
85
88
  parentTaskId?: string;
86
89
  /** spawn: the HOST run's session id (uuid domain) — the always-on parent
87
90
  * linkage, present whether or not a task id was declared. */
@@ -113,7 +116,8 @@ export interface BackgroundChildEvent {
113
116
  * field (their own `taskId` is the per-child key). ABSENT, never invented, on a workflow started with no
114
117
  * launching tool call. */
115
118
  parentToolCallId?: string;
116
- /** tick: the forwarded `task_progress` frame's own taskId (uuid domain; nested children carry theirs). */
119
+ /** tick: the forwarded `task_progress` frame's own taskId (the child's row id on its own ticks; a nested
120
+ * descendant's frame carries that descendant's task id). */
117
121
  progressTaskId?: string;
118
122
  /** tick: the forwarded frame's parentTaskId (nested attribution) · terminal: absent. */
119
123
  progressParentTaskId?: string;
@@ -1,6 +1,6 @@
1
1
  import { anchorSpelling, canonicalizeTarget, familyFor, hasWin32AliasedComponent, isAbsoluteForFamily, normalizeAbsPathLexically, pathFamilyOf, pathIdentityOf, spellingOfIdentity, win32NamespaceScreen } from "../tools/fs/safety.js";
2
2
  import { declaredPathTargetOf, pathTargetValue, protectivePathTargetOf } from "./tool-registry.js";
3
- import { symlinkChainHops } from "./path-identity.js";
3
+ import { leafChainMayHold, symlinkChainHops } from "./path-identity.js";
4
4
  import { DEFAULT_GATE_AWAIT_TIMEOUT_MS, withGateTimeout } from "./gate-bounded-await.js";
5
5
  import { thrownText } from "./thrown-value.js";
6
6
  import { canonicalize } from "./canonical-json.js";
@@ -106,8 +106,7 @@ export async function readPath(env, spelled, base, bases, contract, signal) {
106
106
  if (contract.views === "lexical" || env === undefined || family === undefined || lexical?.kind === "unreadable")
107
107
  return { lexical, hops: [] };
108
108
  const canonical = await canonicalizeTarget(env, spelled, signal, family, base);
109
- const climbs = (s) => s !== undefined && (family === "win" ? /(^|[\\/])\.\.([\\/]|$)/ : /(^|\/)\.\.(\/|$)/).test(s);
110
- const followsALink = canonical.ok && (climbs(spelled) || climbs(base) || lexical?.kind !== "path" || absoluteTargetIdentityOf(canonical.key, bases) !== lexical.identity);
109
+ const followsALink = canonical.ok && leafChainMayHold([spelled, base], lexical?.kind !== "path" || absoluteTargetIdentityOf(canonical.key, bases) !== lexical.identity, family);
111
110
  const chain = contract.views === "chain" && followsALink
112
111
  ? await withGateTimeout(symlinkChainHops(env, spelled, signal, family, base), DEFAULT_GATE_AWAIT_TIMEOUT_MS, signal, "canonicalChain").catch((err) => ({ ok: false, cause: thrownText(err), asked: true }))
113
112
  : { ok: true, hops: [] };
@@ -15,7 +15,7 @@
15
15
  * A leaf (type-only imports): the decision module that receives a record and the class derivation that reads one for its call
16
16
  * both depend on it, and neither depends on the other through it.
17
17
  */
18
- import type { AskClass, AskOrigin } from "./ask-origin.js";
18
+ import type { AskClass, AskOrigin, AskReason } from "./ask-origin.js";
19
19
  import type { ClassifierDenyCause, Settlement } from "./gate-outcome.js";
20
20
  import type { AutoModeClassifierRound } from "./auto-mode.js";
21
21
  import type { AskUnresolvableCause } from "./ask-unresolvable-notice.js";
@@ -56,6 +56,16 @@ export interface EngineAttestation {
56
56
  /** A seat refused the call's arguments because no approval can be bound to them: the refusal's sentence, carried by the
57
57
  * refusal itself — the gate's deny exit reads it (the remedy it gives) instead of judging again. */
58
58
  readonly bindingRefusal?: string;
59
+ /** The engine's own generic question the ask was composed with (the write gate's default "approve write to" sentence, the
60
+ * permission mode's own question) — not anyone's reason. The chain's entry mint ({@link
61
+ * import("./ask-origin.js").chainAskReasonsOf}) writes no entry while the ask's `message` IS this sentence; a later layer
62
+ * that spread the ask and put its own words in `message` keeps them. Written only by the station that composed that
63
+ * sentence, for that sentence; a composer cannot state it (an unbranded record is refused). */
64
+ readonly genericQuestion?: string;
65
+ /** The askers a station read off this ask where it first received it, before it narrated the sentence (an inherited station
66
+ * floating an ancestor's ask back into this leg's fold: its mark frames, its denial-limit fallback's sentence). The chain's
67
+ * entry mint takes these instead of the sentence; empty = the station read no asker. Written only by that float. */
68
+ readonly receivedAskReasons?: readonly AskReason[];
59
69
  }
60
70
  /** The members a station attests — everything but the call binding. */
61
71
  export type AttestationMembers = Omit<EngineAttestation, "toolCallId" | "toolName">;
@@ -10,6 +10,8 @@ const ATTESTATION_GROUP_OF = {
10
10
  guards: "guards",
11
11
  pathDenial: "pathDenial",
12
12
  bindingRefusal: "bindingRefusal",
13
+ genericQuestion: "genericQuestion",
14
+ receivedAskReasons: "receivedAskReasons",
13
15
  };
14
16
  const ATTESTATION_MEMBERS = Object.keys(ATTESTATION_GROUP_OF);
15
17
  const groupLead = (g) => ATTESTATION_MEMBERS.find((k) => ATTESTATION_GROUP_OF[k] === g);
@@ -107,6 +107,16 @@ export interface EngineNotice {
107
107
  * target (`IMAGE_ADMISSION.soft.targetBytes`), because the run has no image processor (`RunnerDeps.imageProcessor`
108
108
  * is `false`, or sharp did not resolve). ONCE PER RUN, at the first such image wherever it entered (a tool's result,
109
109
  * the task's images, an attachment). `detail: { bytes, targetBytes, sessionId, runId }`.
110
+ * - `"fs.staging_file_left"` — a whole-file replace (`NodeExecutionEnv.writeFile`) whose write itself SUCCEEDED could not
111
+ * remove the staged sibling it had written (the in-place rewrite after a refused rename, or after a refused staging open):
112
+ * the file is still on disk, up to the whole content. Audience `operator`. `detail: { path }`, the staged path. Seat-only:
113
+ * an environment with no `onNotice` seat says nothing (a failed write carries the same sentence in its error instead).
114
+ * ONCE PER LEFT FILE.
115
+ * - `"fs.staging_file_swept"` — a whole-file replace (`NodeExecutionEnv.writeFile`) removed the staged siblings of its target
116
+ * that a process which no longer runs had left behind (a process killed mid-write runs no cleanup): exactly the names the
117
+ * replace itself would mint for this target, under a pid that is gone, plain files with one name. A running writer's staged
118
+ * file is never touched. Audience `operator`. `detail: { count }` — how many, no names. Seat-only (an environment with no
119
+ * `onNotice` seat says nothing). ONCE PER WRITE THAT REMOVED ANY.
110
120
  * - `"workflow.governance_key_stripped"` (#235) — the fields of an LLM-authored workflow `agent(spec)`
111
121
  * that did NOT cross the governed default-deny whitelist: an unrecognized/control-plane field, or a
112
122
  * `readFace` value that is not the containment-tightening one. The spawn PROCEEDS on the deployment
@@ -288,7 +298,8 @@ export interface EngineNotice {
288
298
  * consecutive, sessionId?, runId? }` — `model` the retired rung's id, `to` the model the walk now starts at,
289
299
  * `rung` its ladder position, `consecutive` the count that tripped it (the configured bound). Once per retired
290
300
  * rung per run (the retirement is the dedup); only a rung with a rung behind it can retire, so a one-rung ladder
291
- * (`classifierFallback: "none"`) never mints it. Audience `operator`.
301
+ * (`classifierFallback: "none"`) never mints it. Audience `user`: the rest of the user's run is judged by another
302
+ * model, the same consequence `classifier.unavailable` tells the user.
292
303
  * - `"classifier.role_defaulted"` (`src/core/runner/classifier-ladder.ts`, the seat resolver) — no
293
304
  * `classifier` role names a model, so another model STANDS IN for the seat. `detail: { model, reason,
294
305
  * thinkingOffSpelled, sessionId?, runId? }` — `reason` ∈ `tier_below_main` (the nearest directly-bound
@@ -405,13 +416,26 @@ export interface EngineNotice {
405
416
  * the run proceeds on the repaired request. Audience `operator`; `detail: { repairs: [{ form, toolCallIds }],
406
417
  * sessionId, runId }`. ONCE PER RUN PER (form, calls) — the same broken turn is repaired on every request of
407
418
  * the run and announced on the first. Absent ⇒ every request of the run already had the structure.
408
- * - `"context.image_removed"` (#2874) — the provider refused a request because an image in it could not be processed
409
- * (the failed turn's `errorKind: "image_unprocessable"`), so the request view removed the images of the newest
410
- * message still carrying any, each replaced by `[image N removed: rejected by provider: image_unprocessable]`
411
- * (`engine/llm/rejected-images.ts`); the turn was re-sent without them and every later request of the session
412
- * reads the same removal. The transcript keeps the images. Audience `user`; `detail: { images, sessionId, runId }`
413
- * — `images` how many were removed from that message. ONCE PER RUN PER REFUSAL; a refusal recorded before the run
414
- * began is not announced again.
419
+ * - `"context.media_removed"` (#2874, #2988) — media left the model's view of a request while the transcript keeps it;
420
+ * each block's slot holds `[<image|document> N removed: <why>]` (`engine/llm/media-removed.ts`, N its ordinal among
421
+ * its message's blocks of that type). Audience `user`; `detail: { reason, images, documents, sessionId, runId }`,
422
+ * `reason` closed (`MEDIA_REMOVED_REASONS`):
423
+ * · `rejected_by_provider` — the provider refused a request because an image in it could not be processed (the
424
+ * failed turn's `errorKind: "image_unprocessable"`), so the request view removed the images of the newest message
425
+ * still carrying any (`engine/llm/rejected-images.ts`); the turn was re-sent without them and every later request
426
+ * of the session reads the same removal. `images` how many were removed from that message, `documents` 0. ONCE PER
427
+ * RUN PER REFUSAL; a refusal recorded before the run began is not announced again.
428
+ * · `media_budget` — the request's media no longer fit its limits (`IMAGE_ADMISSION.request`: the media-block count,
429
+ * the deployment's base64 budget `RunnerDeps.mediaBudgetBase64Chars`), so the oldest blocks were left out
430
+ * (`media-byte-cap.ts`). `images` / `documents` count the blocks this notice is the first to tell of: ONCE PER
431
+ * SESSION PER BLOCK, by the digest of its bytes (the session's announced record — bounded and best effort, so a
432
+ * block may be told again by a later run, never left untold); a request that was not sent tells of none.
433
+ * - `"context.tool_schema_removed"` (#2681) — the provider refused a request because of one tool's input schema and
434
+ * located the tool (the failed turn's `errorKind: "tool_schema_refused"`, `refusedTool`), so the turn was re-sent with
435
+ * that tool's parameters replaced by an empty object schema, and every later request built from a transcript the
436
+ * refusal's record stands in sends it so (`engine/llm/rejected-images.ts`; MCP and A2A tools only, at most 8 per such
437
+ * transcript; a compaction that summarizes the record away returns the schema until the provider refuses it again).
438
+ * The model can still call the tool. Audience `user`; `detail: { tool, sessionId, runId }`. ONCE PER REFUSAL.
415
439
  * - `"task.tool_turn_incomplete"` (#1230) — the person's line for a tool turn the model was handed incomplete, beside
416
440
  * the note the model itself reads. `detail.cause` (closed `TOOL_TURN_INCOMPLETE_CAUSES`): `truncated` — calls whose
417
441
  * arguments were cut before they parsed, dropped (they did not run); `unnamed` — calls that arrived with no tool
@@ -482,17 +506,21 @@ export interface EngineNotice {
482
506
  * empty table or an environment that keeps the floor (the Stub of a run without hands keeps it by refusing every
483
507
  * start). Once per run — each delegated child on its own environment — and once per construction of a library-direct
484
508
  * band that compiles its own table; `detail: { rowCount, sessionId?, runId? }` (the two ids on a run's notice).
509
+ * - `"config.read_floor_confinement_unavailable"` — a Node environment was asked to confine its starts to the floor
510
+ * (`readFloorConfinement: "os"`) and this host cannot (not macOS, or the seatbelt base does not apply here): the
511
+ * environment declares it does not keep the floor, and the run's own judgment (`config.read_deny_floor_unkept`)
512
+ * follows. Once per construction, at construction; `detail: { reason }`.
485
513
  * - `"config.secret_env_scrubbed"` (#1081) — the D1 fail-closed `scrub` policy, or the deployment's
486
514
  * own credentials (`declareWithheldEnv`: a declared name, or a value equal to a declared or engine-held
487
515
  * credential value), withheld one or more keys from a spawned child's environment (a tool's shell, an
488
516
  * oracle gate, or a language server).
489
517
  * Once per PROCESS, shared by every scrub site ({@link import("./secret-env.js").announceSecretEnvScrub});
490
518
  * `detail: { names, ownCredentials? }` — every withheld key's name, never a value; `ownCredentials`, present
491
- * only when one was withheld, the subset that is the deployment's own credential, by name or by value, whichever
519
+ * only when one was withheld, the subset that is the engine's own credentials, by name or by value, whichever
492
520
  * rule withheld it (withheld under any policy, `"all"` included).
493
521
  * - `"inherit_env.names_withheld"` (#1963) — the same fact for the person whose run drives a tool shell: the variables
494
522
  * of the engine's environment that shell does not receive (`ExecutionEnv.withheldEnv`), the scrub's half (the run's
495
- * `inheritEnv` hands them on) and the deployment's own credentials (no policy does). Audience `user`. Read as each
523
+ * `inheritEnv` hands them on) and the engine's own credentials (no policy does). Audience `user`. Read as each
496
524
  * call to the engine's own shell tool starts on a root leg (the answer can grow during a run: a credential the engine
497
525
  * takes in when it first routes a model is withheld from the next child); once per SESSION per name set (the
498
526
  * session's announced record). `detail: { state, names?, ownCredentials?, sessionId, runId? }` — `state` `"withheld"`
@@ -639,13 +667,13 @@ export interface EngineNotice {
639
667
  * them apart reads that key; one that only cares "a turn was cut" reads neither):
640
668
  * · the STEER-NOW lane (design/373) — a caller-provenance steer with `priority: "now"` cut
641
669
  * the turn and the run CONTINUES with the steer at the queue head.
642
- * `detail: { inputId, sessionId, runId, actorId?, taskId? }`, NO `cause` key — `inputId` is
670
+ * `detail: { inputId, sessionId, runId, actorId?, taskId }`, NO `cause` key — `inputId` is
643
671
  * the steer's own correlation key (the `human_input` frame's id) and `actorId` the caller's
644
672
  * asserted identity when one rode the steer.
645
673
  * · the BARE-HALT lane (#504, {@link TaskStream.halt}) — the person's Esc-form stop cut the
646
674
  * turn and the run does NOT continue: it collects to a clean, resumable
647
675
  * `status:"completed"` ending carrying {@link TaskResult.haltedByUser}.
648
- * `detail: { cause: "user_halt", sessionId, runId, taskId? }` — no `inputId` and no
676
+ * `detail: { cause: "user_halt", sessionId, runId, taskId }` — no `inputId` and no
649
677
  * `actorId`, because no text entered the model and the verb carries no caller identity. A
650
678
  * consumer keying `detail.inputId` off this row must treat it as ABSENT on this lane.
651
679
  * Fence tension: this notice asserts THE CUT only — when the cut
@@ -677,7 +705,7 @@ export interface EngineNotice {
677
705
  * for it (a brain minting its own `aborted` final beside a late halt, a natural completion the halt
678
706
  * arrived too late to prevent, an approval park whose commit won the race and whose abort owned the
679
707
  * ending); once per such run, at the result's settlement. Either way the notice is the halt's trace
680
- * beside the verb receipt. `detail: { sessionId, runId, taskId? }` — `runId` is the run whose ending
708
+ * beside the verb receipt. `detail: { sessionId, runId, taskId }` — `runId` is the run whose ending
681
709
  * the halt failed to claim. Audience `"user"`. A REFUSED halt (typed `steering.not_running` throw)
682
710
  * mints nothing: the refusal itself is the loud answer.
683
711
  *
@@ -691,7 +719,7 @@ export interface EngineNotice {
691
719
  * Minted only for a value that reads as an APPROVAL — an unconsumed
692
720
  * deny/refusal is an ordinary release and leaves no trace, and an unconsumed REJECTION goes to
693
721
  * `onError(phase:"hook")` instead (a failing callback, not an answer). One notice per
694
- * unconsumed approval; `detail: { toolName, toolCallId, sessionId, runId, taskId? }`. Audience `"user"`
722
+ * unconsumed approval; `detail: { toolName, toolCallId, sessionId, runId, taskId }`. Audience `"user"`
695
723
  * (whoever answered the card is the one entitled to hear the answer ran nothing); a host may
696
724
  * forward it on its own wire.
697
725
  *
@@ -706,7 +734,7 @@ export interface EngineNotice {
706
734
  * the stop's only trace. Minted once per such run, after the terminal arbitration (so it never
707
735
  * claims a completed ending the terminal did not give — a budget ceiling crossed by the last
708
736
  * turn's own spend still fails the run and mints nothing here); `detail: { sessionId, runId,
709
- * taskId?, origin }` with `origin` ∈ `"interrupt"` (the verb) | `"walltime"` | `"turns"` |
737
+ * taskId, origin }` with `origin` ∈ `"interrupt"` (the verb) | `"walltime"` | `"turns"` |
710
738
  * `"signal"` (every other run-level abort: the task's own `signal`, a parent's cancel, a
711
739
  * `destroy()`, a refused preempt — the leg names the three it can tell apart and files the rest
712
740
  * here). Audience `"user"`. A stop that arrives AFTER the loop's end but before `done` aborted no
@@ -718,7 +746,7 @@ export interface EngineNotice {
718
746
  * - `"approval.read_root_granted"` / `"approval.read_root_grant_rejected"` — an approver's `readRootGrant`
719
747
  * (`AskOutcome`). GRANTED: it equalled the card's `readRootCandidate.dir` beside `allow: true`; this run's READ
720
748
  * directories now include it (never the write roots; this run only); `detail: { dir, covers?, root, toolName,
721
- * toolCallId, sessionId, runId, taskId? }`, `root` = the canonical spelling held. REJECTED: nothing changed,
749
+ * toolCallId, sessionId, runId, taskId }`, `root` = the canonical spelling held. REJECTED: nothing changed,
722
750
  * the verdict stands; `detail: { reason, offered?, requested?, …same ids }`, `reason` ∈ `on_refusal` |
723
751
  * `not_a_string` | `no_candidate` | `mismatch` | `unresolvable` | `resolves_elsewhere` | `admits_artifact_store`
724
752
  * (the directory contains the wired local artifact store, lies inside it or is it) | `no_read_roots`. Once per
@@ -764,7 +792,7 @@ export interface EngineNotice {
764
792
  * same fact is the entry's own `human_input` account with `delivery: "blocked"` — the two share
765
793
  * the inputId, so "accepted at park, screened at redelivery" is auditable end to end. Audience
766
794
  * `"user"` (the person whose instruction was withheld is the one entitled to re-issue it);
767
- * `detail: { inputId?, sessionId, runId, taskId? }` — `inputId` is the parked entry's stored
795
+ * `detail: { inputId?, sessionId, runId, taskId }` — `inputId` is the parked entry's stored
768
796
  * correlation key (OPTIONAL: a row parked without one exists), and `runId` names the resume leg
769
797
  * that withheld it, so a session resumed twice does not report two withholdings as one.
770
798
  *
@@ -1076,7 +1104,10 @@ export interface EngineNotice {
1076
1104
  code: string;
1077
1105
  /** The exact human-readable line the unwired build prints via `console.warn` — same words, one text. */
1078
1106
  message: string;
1079
- /** Machine-readable facts of the notice (knob names, arriving values, values in force). */
1107
+ /** Machine-readable facts of the notice (knob names, arriving values, values in force). On a notice a leg raises about
1108
+ * itself, `detail.taskId` is that leg's own task id — the one value its prepare minted (`Prepared.taskId`: a background
1109
+ * sub-agent's registry task id, else the host's declared `TaskSpec.taskId`, else the leg's session id) — read the same way by
1110
+ * every such code; the per-code shapes below list it where a code carries it. */
1080
1111
  detail?: Record<string, unknown>;
1081
1112
  /** The owning session, when the notice HAS one — an ATTRIBUTION/correlation key, never a
1082
1113
  * projection permission: whether a notice may be surfaced onto that session's user-facing
@@ -51,6 +51,14 @@ export interface FileHistoryRetentionPolicy {
51
51
  */
52
52
  keep?: number | "unbounded";
53
53
  }
54
+ /**
55
+ * The retention door's reading of a policy: received by the receipt law with this door's one knob as the member it takes
56
+ * (a plain object read once off its own descriptors; a misspelled knob refused by name, `config.retention_policy_invalid`),
57
+ * its knob judged as {@link resolveFileHistoryRetention} judges it, and handed back as the frozen copy a store then
58
+ * holds — so a composition that receives the policy ahead of the store it configures hands that store the copy, and the
59
+ * caller's object is read once. Absent ⇒ `undefined` (the engine default applies).
60
+ */
61
+ export declare function receiveFileHistoryRetention(label: string, policy: FileHistoryRetentionPolicy | undefined): Readonly<FileHistoryRetentionPolicy> | undefined;
54
62
  /**
55
63
  * The retention door: resolve a deployment's policy to a boundary cap, or REFUSE loudly.
56
64
  *
@@ -1,18 +1,21 @@
1
- import { refuseRetentionPolicy } from "./retention-policy.js";
1
+ import { optionKeys, receiveMembers } from "./own-property-receipt.js";
2
+ import { refuseRetentionPolicy, retentionKnobRefusal } from "./retention-policy.js";
2
3
  export const DEFAULT_FILE_HISTORY_BOUNDARY_KEEP = 100;
3
- const KNOWN_KNOBS = new Set(["keep"]);
4
- export function resolveFileHistoryRetention(label, policy) {
4
+ const FILE_HISTORY_RETENTION_KNOBS = optionKeys()({ keep: 0 });
5
+ export function receiveFileHistoryRetention(label, policy) {
5
6
  if (policy === undefined)
6
- return DEFAULT_FILE_HISTORY_BOUNDARY_KEEP;
7
+ return undefined;
7
8
  if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
8
- refuseRetentionPolicy(label, "retention", policy, `an object of retention knobs (${[...KNOWN_KNOBS].join(", ")}) or omitted`);
9
- }
10
- const unknown = Object.keys(policy).filter((k) => !KNOWN_KNOBS.has(k));
11
- if (unknown.length > 0) {
12
- const first = unknown[0];
13
- refuseRetentionPolicy(label, `retention.${first}`, policy[first], `omitted — ${JSON.stringify(first)} is not a retention knob (the only knob is "keep"), and a misspelled one would leave the engine default in force while the operator believes their own number is`);
9
+ refuseRetentionPolicy(label, "retention", policy, `an object of retention knobs (${FILE_HISTORY_RETENTION_KNOBS.join(", ")}) or omitted`);
14
10
  }
15
- const keep = policy.keep;
11
+ const copy = receiveMembers(policy, { subject: `${label}.retention`, unit: "retention knob", moment: "at construction" }, FILE_HISTORY_RETENTION_KNOBS, retentionKnobRefusal);
12
+ boundaryKeepOf(label, copy.keep);
13
+ return copy;
14
+ }
15
+ export function resolveFileHistoryRetention(label, policy) {
16
+ return boundaryKeepOf(label, receiveFileHistoryRetention(label, policy)?.keep);
17
+ }
18
+ function boundaryKeepOf(label, keep) {
16
19
  if (keep === undefined)
17
20
  return DEFAULT_FILE_HISTORY_BOUNDARY_KEEP;
18
21
  if (keep === "unbounded")