@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
@@ -5,5 +5,6 @@
5
5
  * llm-core); the facade stays so consumers never notice which side a symbol lives on.
6
6
  */
7
7
  export { createAssistantMessageEventStream, DATA_LABEL_UNSAFE, ensureToolTurnInvariants, findToolByName, isTextBlock, MODEL_OUTPUT_INVALID_CAUSES, quoteDataLabel, renderContentBlock, renderUserAttachmentView, snapshotActorAssertion, stampStreamDrops, streamDropsOf, stripEngineMetadata, TOOL_TURN_INCOMPLETE_CAUSES, TOOL_TURN_REPAIR_DROPS, toolNameIndex, userAttachmentOf } from "../engine/llm/index.js";
8
- export type { ActorAssertion, UserAttachmentKind, UserAttachmentObservation, UserAttachmentOutcome, UserAttachmentSupply, UserMessageAttachment, AnthropicMessagesCompat, OpenAICompletionsCompat, OpenAIResponsesCompat, AssistantMessage, AssistantMessageDiagnostic, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, Model, ModelOutputInvalid, ModelOutputInvalidCause, OutputLimit, ResilienceOptions, RouteAdjudication, RouteCredential, RouteCredentialSource, RoutePairingConfig, RoutePairingPosture, RouteRefusalCode, RouteRefusalDetail, SimpleStreamOptions, StallTimeouts, StopReason, StreamFn, TextContent, ThinkingContent, Tool, ToolCall, ToolDescriptionVariant, ToolResultMessage, StreamDrop, StreamDropCause, ToolTurnIncompleteCause, ToolTurnRepair, Usage, UserMessage, } from "../engine/llm/index.js";
8
+ export type { ActorAssertion, UserAttachmentKind, UserAttachmentObservation, UserAttachmentOutcome, UserAttachmentSupply, UserMessageAttachment, AnthropicMessagesCompat, OpenAICompletionsCompat, OpenAIResponsesCompat, AssistantMessage, AssistantMessageDiagnostic, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, Model, ModelOutputInvalid, ModelOutputInvalidCause, OutputLimit, ResilienceOptions, RouteAdjudication, RouteCredential, RouteCredentialSource, RoutePairingConfig, RoutePairingPosture, RouteRefusalCode, RouteRefusalDetail, SimpleStreamOptions, StallTimeouts, StopReason, StreamFn, TextContent, ThinkingContent, Tool, ToolCall, ToolDescriptionVariant, ToolResultMessage, StreamDrop, StreamDropCause, ToolTurnIncompleteCause, ToolTurnRepair, Usage, UserMessage, RowRewrittenBy, } from "../engine/llm/index.js";
9
9
  export type { RejectedImageRemoval } from "../engine/llm/rejected-images.js";
10
+ export { MEDIA_REMOVED_REASONS, mediaRemovedPlaceholder, type MediaRemovedReason } from "../engine/llm/media-removed.js";
@@ -1 +1,2 @@
1
1
  export { createAssistantMessageEventStream, DATA_LABEL_UNSAFE, ensureToolTurnInvariants, findToolByName, isTextBlock, MODEL_OUTPUT_INVALID_CAUSES, quoteDataLabel, renderContentBlock, renderUserAttachmentView, snapshotActorAssertion, stampStreamDrops, streamDropsOf, stripEngineMetadata, TOOL_TURN_INCOMPLETE_CAUSES, TOOL_TURN_REPAIR_DROPS, toolNameIndex, userAttachmentOf } from "../engine/llm/index.js";
2
+ export { MEDIA_REMOVED_REASONS, mediaRemovedPlaceholder } from "../engine/llm/media-removed.js";
@@ -11,7 +11,7 @@
11
11
  * **无任何 commit/accept 副作用**(纯 loop,同 runRepairLoop SAFE-tier 永不 `fixed`)。要 accept,caller 自走
12
12
  * design/77 Gate-1 out-of-process oracle 隔离边界,不在 goal helper 开后门。
13
13
  */
14
- import type { RunnerSelfSeat } from "../core/runner/contracts.js";
14
+ import type { RunInternals, RunnerSelfSeat } from "../core/runner/contracts.js";
15
15
  import type { CheckpointToken } from "../core/checkpoint-store.js";
16
16
  import type { GateKind, PAUSE_REGISTRY } from "../core/pause-registry.js";
17
17
  import type { PausedCause, TaskResult, TaskSpec } from "../core/types.js";
@@ -124,6 +124,10 @@ export declare const DECLARE_DONE_TOOL_NAME = "DeclareDone";
124
124
  * Only `declare_done` AND `doneCheck.done` → `achieved` (surfaced, NEVER auto-accepted, G1). A rejected
125
125
  * doneCheck feeds its reason back (fenced) and continues. Bounded by maxIterations / budget / wall-clock /
126
126
  * cancel; a durable pause (suspended/needs_review) is a hard boundary that surfaces the checkpointToken.
127
+ *
128
+ * `internals` is the trusted run-scoped channel of the caller, forwarded to every iteration (the shape the verification gate
129
+ * takes): a goal run inside a delegated leg keeps the delegation fact and its caller's author. The first iteration hands over the
130
+ * caller's goal and carries the caller's author; every later one is this loop's own words (`engine`).
127
131
  */
128
- export declare function runGoal(runner: RunnerSelfSeat, spec: GoalSpec): Promise<GoalResult>;
132
+ export declare function runGoal(runner: RunnerSelfSeat, spec: GoalSpec, internals?: RunInternals): Promise<GoalResult>;
129
133
  export {};
@@ -1,6 +1,8 @@
1
1
  import { createHash, randomUUID } from "node:crypto";
2
2
  import { Type } from "typebox";
3
3
  import { delimitUntrusted } from "../core/untrusted-text.js";
4
+ import { recipeContinuationLeg } from "../core/input-author.js";
5
+ import { legTaskIdOf } from "../core/leg-identity.js";
4
6
  import { isDurablePause, pauseFamily } from "../agents/suspend-guard.js";
5
7
  import { OUTPUT_TOOL_NAME, mountRuleFace, toolFace } from "../core/tool-catalog-entries.js";
6
8
  export const DECLARE_DONE_TOOL_NAME = "DeclareDone";
@@ -57,7 +59,7 @@ function raceAbortReject(p, signal) {
57
59
  });
58
60
  });
59
61
  }
60
- export async function runGoal(runner, spec) {
62
+ export async function runGoal(runner, spec, internals) {
61
63
  if (!Number.isFinite(spec.maxIterations) || spec.maxIterations < 1) {
62
64
  throw new Error(`runGoal: maxIterations must be a finite number ≥ 1 (got ${spec.maxIterations})`);
63
65
  }
@@ -108,7 +110,7 @@ export async function runGoal(runner, spec) {
108
110
  if (verificationKind === "mechanical" && status !== "suspended" && status !== "needs_review") {
109
111
  runner.emitTaskOutcome?.({
110
112
  taskSignature: spec.taskSignature ?? `goal:${objectiveHash}`,
111
- runId: r.result?.taskId ?? sessionId,
113
+ runId: r.result?.taskId ?? legTaskIdOf(spec.taskSpec, internals, sessionId),
112
114
  model: r.result?.model,
113
115
  verificationKind: "mechanical",
114
116
  status,
@@ -140,7 +142,8 @@ export async function runGoal(runner, spec) {
140
142
  const tools = hasOutputSchema
141
143
  ? spec.taskSpec.tools
142
144
  : [...(spec.taskSpec.tools ?? []), createDeclareDoneTool(doneRef)];
143
- const result = await runner.runTask({ ...spec.taskSpec, sessionId, objective, tools, signal: goalSignal }, { goalMode: true });
145
+ const roundInternals = { ...internals, goalMode: true };
146
+ const result = await runner.runTask({ ...spec.taskSpec, sessionId, objective, tools, signal: goalSignal }, iteration === 1 ? roundInternals : recipeContinuationLeg(roundInternals));
144
147
  lastResult = result;
145
148
  cumulativeTokens += (result.stats.tokens ?? 0) + (result.stats.nested?.tokens ?? 0);
146
149
  spentCostMicroUsd += (result.stats.costMicroUsd ?? 0) + (result.stats.nested?.costMicroUsd ?? 0);
@@ -27,6 +27,9 @@ import { type WorkflowSizeGuideline } from "./workflow-size-guideline.js";
27
27
  * `run_workflow` are NOT callable — they live in RETIRED_TOOL_NAMES as validation data only (a call
28
28
  * under either gets a loud roster miss), so every model-visible mention must use THIS constant. */
29
29
  export declare const RUN_WORKFLOW_TOOL_NAME = "Workflow";
30
+ /** The refusal a workflow call gets where its completion would come back on no channel (no completion sink for the call,
31
+ * none on the mount, no deployment notifier): a workflow has no synchronous form, so nothing is started. */
32
+ export declare const WORKFLOW_NO_COMPLETION_CHANNEL = "a workflow run is not available here \u2014 no completion would come back from one on this mount (no notification channel and no deployment notifier is wired), and a workflow has no synchronous form. Do the work directly instead.";
30
33
  /**
31
34
  * design/98 §D.5 — the seam the deployment implements to RE-INVOKE the originating LLM when its workflow
32
35
  * finishes. Core calls `notify` once per run (at most once — `runId` dedup) with a REDACTED, BOUNDED summary;
@@ -58,21 +61,6 @@ export interface WorkflowCompletionNotifier {
58
61
  * repeat the diagnostics field's own drift history (the comment right above this one). */
59
62
  completionId?: string;
60
63
  }): Promise<void> | void;
61
- /**
62
- * Poll-then-also-notify dedup: the ORIGINATING session was served this run's TERMINAL
63
- * state IN-BAND (a `TaskOutput` poll through the task registry returned a non-running snapshot) —
64
- * the deployment should ack/drop any still-pending completion-inbox entry for (originatingSessionId,
65
- * runId), so a later stream-open doesn't re-deliver a `workflow_complete` the model already
66
- * consumed. Fired at most once per run, AFTER `notify` may already have enqueued (the whole point:
67
- * the poll usually wins the race in-turn). Optional; errors are swallowed. The shell-side same-process
68
- * seed dedup remains the belt — this is the durable/cross-restart half.
69
- */
70
- ackServed?(input: {
71
- runId: string;
72
- originatingSessionId?: string;
73
- sourceTaskId?: string;
74
- principal?: string;
75
- }): Promise<void> | void;
76
64
  }
77
65
  /** design/98 §D.6 — the deployment's hard CEILINGS for an LLM-authored workflow (the tool forces them; a
78
66
  * script may only tighten). All optional; sensible defaults bound a runaway script. */
@@ -176,7 +164,8 @@ export interface RunWorkflowToolDeps {
176
164
  onAgentSpawn?: (handle: WorkflowAgentHandle) => void;
177
165
  /** Tenant/grouping key for the run. */
178
166
  scope?: string;
179
- /** Completion re-invoke seam. */
167
+ /** Completion re-invoke seam — the deployment-channel term of the one background admission: with it, a call is
168
+ * admitted even when no completion sink resolves. */
180
169
  notifier?: WorkflowCompletionNotifier;
181
170
  /** The originating session id, threaded into every completion notify. */
182
171
  originatingSessionId?: string;
@@ -200,7 +189,8 @@ export interface RunWorkflowToolDeps {
200
189
  /** design/115 P2 core slice: run-local task-notification sink for SDK event + live model XML injection.
201
190
  * design/373 §3.7: the sink accepts the injection tier — workflow terminals declare `"next"`
202
191
  * explicitly (a completion must reach a busy model at the boundary; the parameterless funnel
203
- * default is the EXTERNAL lane's `"later"` and no internal lane may lean on it). */
192
+ * default is the EXTERNAL lane's `"later"` and no internal lane may lean on it). A call carrying its run's lane
193
+ * delivers there instead; with neither this nor a {@link notifier}, a call is refused before anything starts. */
204
194
  taskNotification?: (notification: TaskNotificationPayload, opts?: {
205
195
  priority?: "now" | "next" | "later";
206
196
  }) => void;
@@ -268,6 +258,10 @@ export interface RunWorkflowToolDeps {
268
258
  /** The HOST task's effective working root — threaded into every spawned agent's trusted internals so a
269
259
  * TOC env factory can root the child at the parent's cwd (CC parity, 2026-07-03). */
270
260
  parentCwd?: string;
261
+ /** The HOST task's own placement target (what its env reported as its workspace settled) — the fence every agent the
262
+ * workflow spawns is minted under (`RunInternals.placementTarget`). Rides deps for the auto-mounted form (whose
263
+ * execute ctx carries none); a rich ctx's own `placementTarget` wins. */
264
+ placementTarget?: import("../core/remote-env.js").PlacementTarget;
271
265
  /** Call-time getter for the level a spawned agent runs at when neither the script, the agentType
272
266
  * definition nor the governance baseline set `thinking` (the mount folds the deployment's STATED
273
267
  * `roles.subagent.thinking` over the HOST task's current level — the child thinking seat's lower rungs).
@@ -3,11 +3,12 @@ import { defineTool, errorResult } from "../core/tools.js";
3
3
  import { governanceBaselineError, governanceBaselineProblem } from "./governance-baseline-validity.js";
4
4
  import { formatWorkflowRun, WORKFLOW_RECORD_WHOLE } from "../core/task-registry-shared.js";
5
5
  import { persistTaskArtifact } from "../core/tool-result-store.js";
6
- import { oweTerminalDelivery, resolveCompletionSink } from "../core/task-notification.js";
6
+ import { admitsBackgroundLaunch, oweTerminalDelivery, resolveCompletionSink } from "../core/task-notification.js";
7
7
  import { egressText, egressThrownText, boundedRedactedSummary } from "../core/untrusted-egress.js";
8
8
  import { withDelegationProvenance } from "../core/tool-policy.js";
9
9
  import { LAUNCH_RECEIPT_OWN_WORDS_CLAUSE, launchReceiptNoQuoteClause } from "../agents/launch-receipt-contract.js";
10
10
  import { startWorkflow } from "./workflow.js";
11
+ import { settledRunOf } from "../core/workflow-settled-run.js";
11
12
  import { WORKFLOW_AGENT_PARKED_ERROR_CODE, parkedAgentsOf } from "./workflow-types.js";
12
13
  import { checkpointStoreOfSeat } from "../core/checkpoint-seat.js";
13
14
  import { buildWorkflowPrimitives } from "./workflow-primitives.js";
@@ -32,6 +33,7 @@ import { workflowSizeGuidelineSection } from "./workflow-size-guideline.js";
32
33
  import { mountRuleFace, toolFace } from "../core/tool-catalog-entries.js";
33
34
  import { thrownText } from "../core/thrown-value.js";
34
35
  export const RUN_WORKFLOW_TOOL_NAME = "Workflow";
36
+ export const WORKFLOW_NO_COMPLETION_CHANNEL = "a workflow run is not available here — no completion would come back from one on this mount (no notification channel and no deployment notifier is wired), and a workflow has no synchronous form. Do the work directly instead.";
35
37
  function stripCodeFences(s) {
36
38
  const t = s.trim();
37
39
  const m = /^```[A-Za-z]*\r?\n([\s\S]*?)\r?\n?```$/.exec(t);
@@ -70,18 +72,10 @@ function workflowRecordTeach(run, artifact) {
70
72
  const recordTeach = artifact.kind === "stored"
71
73
  ? `Full record (the result and every agent's row): read it with ReadToolResult (ref "${artifact.ref}") before assuming an empty or unexpected result.`
72
74
  : artifact.kind === "unconfirmed"
73
- ? "The full record (the result and every agent's row) could not be stored (the write failed or went unconfirmed), so no ref can read it back; TaskOutput reads it where mounted."
74
- : "The full record (the result and every agent's row) is not stored behind a ref (no offload store); TaskOutput reads it where mounted.";
75
+ ? "The full record (the result and every agent's row) could not be stored (the write failed or went unconfirmed), so no ref can read it back — it is not readable in this session."
76
+ : "The full record (the result and every agent's row) is not stored behind a ref (no offload store) — it is not readable in this session.";
75
77
  return `${rowsTeach}${recordTeach}`;
76
78
  }
77
- function completionIdFromRejection(err) {
78
- return workflowRunOfRejection(err)?.completionId;
79
- }
80
- function workflowRunOfRejection(err) {
81
- if (err === null || (typeof err !== "object" && typeof err !== "function"))
82
- return undefined;
83
- return err.workflowRun;
84
- }
85
79
  function workflowUsageBlock(run) {
86
80
  const agents = run.agents;
87
81
  const parked = parkedAgentsOf(agents);
@@ -360,10 +354,9 @@ async function mountRunWorkflowTool(d) {
360
354
  "role.\n" +
361
355
  "\n" +
362
356
  "Don't race. After launching, you know nothing about what the workflow found. Never fabricate or predict its " +
363
- "results in any format — not as prose, summary, or structured output. When a completion notifier is wired " +
364
- "(the launch note will say so) END YOUR TURN and wait — the notification carries the result; poll " +
365
- "TaskOutput(task_id) only when the user asks for progress. If the user asks a follow-up before it lands, " +
366
- "give status, not a guess." +
357
+ "results in any format — not as prose, summary, or structured output. END YOUR TURN and wait — the completion " +
358
+ "notification carries the result and each agent's outcome (the launch note says how it reaches you). If the " +
359
+ "user asks a follow-up before it lands, give status, not a guess." +
367
360
  (namedWorkflowSection !== undefined ? `\n\n${namedWorkflowSection}` : "") +
368
361
  sizeGuidelineSection,
369
362
  parameters: Type.Object({
@@ -398,6 +391,9 @@ async function mountRunWorkflowTool(d) {
398
391
  const rawResume = rawArgs.resumeFromRunId;
399
392
  const resumeFromRunId = typeof rawResume === "string" && rawResume.length > 0 ? rawResume : undefined;
400
393
  const sourceTaskId = ctx.taskId ?? d.sourceTaskId;
394
+ const completionSink = resolveCompletionSink(ctx.onTaskNotification, d.taskNotification);
395
+ if (!admitsBackgroundLaunch(completionSink, d.notifier !== undefined))
396
+ return structuredError(WORKFLOW_NO_COMPLETION_CHANNEL);
401
397
  const hostSeat = parentSpecSeatOfCtx(ctx) ?? d.parentSpecSeat;
402
398
  const detachedSeat = hostSeat !== undefined ? stripSpawnTurnQuestionFace(hostSeat) : undefined;
403
399
  const parentSpecSeat = detachedSeat?.spec;
@@ -519,6 +515,7 @@ async function mountRunWorkflowTool(d) {
519
515
  ...(d.originatingSessionId !== undefined ? { originatingSessionId: d.originatingSessionId } : {}),
520
516
  ...((ctx.rootSessionId ?? d.rootSessionId ?? d.originatingSessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? d.rootSessionId ?? d.originatingSessionId } : {}),
521
517
  ...((ctx.placementRoot ?? d.placementRoot) !== undefined ? { placementRoot: ctx.placementRoot ?? d.placementRoot } : {}),
518
+ ...((ctx.placementTarget ?? d.placementTarget) !== undefined ? { placementTarget: ctx.placementTarget ?? d.placementTarget } : {}),
522
519
  ...((ctx.crossBoundaryTreeForChildren ?? d.crossBoundaryTree) !== undefined ? { crossBoundaryTree: ctx.crossBoundaryTreeForChildren ?? d.crossBoundaryTree } : {}),
523
520
  ...(workflowTaskId !== undefined ? { runId: workflowTaskId } : {}),
524
521
  journalStore: d.journalStore,
@@ -593,19 +590,8 @@ async function mountRunWorkflowTool(d) {
593
590
  ...(taskOwner !== undefined ? { owner: taskOwner } : {}),
594
591
  ...(taskScope !== undefined ? { scope: taskScope } : {}),
595
592
  ...(d.originatingSessionId !== undefined ? { originatingSessionId: d.originatingSessionId } : {}),
596
- onServedTerminal: () => {
597
- void Promise.resolve()
598
- .then(() => d.notifier?.ackServed?.({
599
- runId,
600
- ...(d.originatingSessionId !== undefined ? { originatingSessionId: d.originatingSessionId } : {}),
601
- ...(sourceTaskId !== undefined ? { sourceTaskId } : {}),
602
- ...(principal !== undefined ? { principal } : {}),
603
- }))
604
- .catch(() => { });
605
- },
606
593
  });
607
594
  }
608
- const completionSink = resolveCompletionSink(ctx.onTaskNotification, d.taskNotification);
609
595
  oweTerminalDelivery(completionSink, { task_id: runId, task_type: "workflow" });
610
596
  {
611
597
  let notified = false;
@@ -641,7 +627,7 @@ async function mountRunWorkflowTool(d) {
641
627
  const recordOf = async (run) => {
642
628
  const artifact = await persistTaskArtifact(d.taskArtifacts, runId, formatWorkflowRun(run, WORKFLOW_RECORD_WHOLE).content);
643
629
  if (artifact.kind === "stored")
644
- d.taskRegistry?.recordArtifactRef(runId, artifact.ref, 0);
630
+ d.taskRegistry?.recordArtifactRef(runId, artifact.ref, run.completionId);
645
631
  return workflowRecordTeach(run, artifact);
646
632
  };
647
633
  handle.done
@@ -656,9 +642,8 @@ async function mountRunWorkflowTool(d) {
656
642
  diagnostics: workflowDiagnostics(runId, d.journalStore?.locator?.(runId, res.run.scope), res.run.resume?.journalEntries === 0, await recordOf(res.run).catch(() => "This run's record could not be read.")),
657
643
  completionId: res.run.completionId,
658
644
  }), async (err) => {
659
- const carried = workflowRunOfRejection(err);
660
- const failedRun = (carried?.id === runId && Array.isArray(carried.agents) ? carried : undefined) ?? (d.store !== undefined ? ((await d.store.get(runId).catch(() => null)) ?? undefined) : undefined);
661
- const record = failedRun !== undefined ? await recordOf(failedRun).catch(() => "This run's record could not be read.") : "This failure carries no record of the run's agents and no run store holds one.";
645
+ const failedRun = settledRunOf(handle.done);
646
+ const record = (failedRun !== undefined ? await recordOf(failedRun).catch(() => undefined) : undefined) ?? "This run's record could not be read.";
662
647
  fire({
663
648
  task_id: runId,
664
649
  task_type: "workflow",
@@ -666,7 +651,7 @@ async function mountRunWorkflowTool(d) {
666
651
  status: "failed",
667
652
  summary: failureSummary(err, runId),
668
653
  diagnostics: workflowDiagnostics(runId, undefined, undefined, record),
669
- ...(completionIdFromRejection(err) !== undefined ? { completionId: completionIdFromRejection(err) } : {}),
654
+ ...(failedRun?.completionId !== undefined ? { completionId: failedRun.completionId } : {}),
670
655
  });
671
656
  })
672
657
  .catch(() => { });
@@ -680,20 +665,12 @@ async function mountRunWorkflowTool(d) {
680
665
  ...(persistedScriptPath !== undefined ? { scriptPath: persistedScriptPath } : {}),
681
666
  handling: `${launchReceiptNoQuoteClause(" (the ids above, and scriptPath when present)")} ${LAUNCH_RECEIPT_OWN_WORDS_CLAUSE}`,
682
667
  note: (() => {
683
- const pollExpr = d.taskRegistry ? `TaskOutput({ task_id: "${runId}" })` : undefined;
684
668
  const journalRef = d.journalStore?.locator?.(runId, taskScope ?? d.scope ?? "");
685
- const carries = pollExpr
686
- ? ` A terminal ${pollExpr} reply carries its result AND per-agent rows — read them${journalRef !== undefined ? ` (full journal: ${journalRef})` : ""} before assuming an empty or unexpected result.`
687
- : "";
669
+ const carries = ` The completion notification carries its result AND per-agent rows — read them${journalRef !== undefined ? ` (full journal: ${journalRef})` : ""} before assuming an empty or unexpected result.`;
688
670
  if (d.notifier) {
689
- return `The workflow runs asynchronously. You will be NOTIFIED when it completes (the notification carries the result). End your turn and wait — do not poll unless the user asks for progress.${carries}`;
690
- }
691
- if (completionSink) {
692
- return `The workflow runs asynchronously. Its completion is injected into THIS session if it is still active; if you have ended your turn and hear nothing, ${pollExpr ? `poll ${pollExpr}` : "there is no poll path wired"}.${carries}`;
671
+ return `The workflow runs asynchronously. You will be NOTIFIED when it completes (the notification carries the result). End your turn and wait — do not poll.${carries}`;
693
672
  }
694
- return pollExpr
695
- ? `The workflow runs asynchronously and no completion notifier is wired. Poll ${pollExpr}.${carries}`
696
- : "The workflow runs asynchronously; no completion notifier is wired and no status/poll path is available.";
673
+ return `The workflow runs asynchronously. Its completion is delivered to this session (its next turn, if this one has ended) — end your turn and wait.${carries}`;
697
674
  })(),
698
675
  }),
699
676
  };
@@ -92,7 +92,7 @@ export interface WorkflowAgentSpec extends ScriptClampSeats {
92
92
  * restricting value, an add-only row through the row's script and entry laws. A row marked inherited-only (its
93
93
  * restricting value switches off an operator-side record) is outside this set and is stripped like any other key.
94
94
  */
95
- export declare const WHITELIST_KEYS: readonly ("thinking" | "systemPrompt" | "objective" | "images" | "limits" | ScriptSeat | "modelName")[];
95
+ export declare const WHITELIST_KEYS: readonly ("thinking" | "objective" | "images" | "systemPrompt" | "limits" | ScriptSeat | "modelName")[];
96
96
  /**
97
97
  * #505 ② — ACCEPTED ALIAS SPELLINGS on the spec: `alias → the {@link WHITELIST_KEYS} member it means`.
98
98
  *
@@ -365,8 +365,8 @@ export interface WorkflowRun {
365
365
  * Absent on `completed` runs (their per-agent failures ride `agentFailures` + each `WorkflowAgentRun.errorCode`). */
366
366
  errorCode?: string;
367
367
  /** The script's RETURN VALUE, bounded + redacted at completion time (same egress
368
- * discipline as the notifier `result`), so a terminal `TaskOutput` poll can hand the
369
- * model the result instead of sending it in poll circles. Absent on failed runs and runs recorded by
368
+ * discipline as the notifier `result`), so a terminal host poll and the completion record carry the
369
+ * result. Absent on failed runs and runs recorded by
370
370
  * older engine versions. */
371
371
  result?: string;
372
372
  /** NH-1: the FULL return value (redacted, capped at {@link WORKFLOW_RESULT_FULL_MAX}), set ONLY
@@ -348,6 +348,10 @@ export interface RunWorkflowOptions {
348
348
  * placed at the ladder/gate root. Absent ⇒ nothing extra travels (the rootSessionId chain is the
349
349
  * placement root through prepare's mint middle segment). */
350
350
  placementRoot?: string;
351
+ /** The host run's own placement target (threaded by the run-workflow tool: what the host leg's env reported as its
352
+ * workspace settled) — every workflow-spawned agent, on either spawn leg, is minted under it as its fence
353
+ * (`RunInternals.placementTarget`). Absent ⇒ the agents carry no fence. */
354
+ placementTarget?: import("../core/remote-env.js").PlacementTarget;
351
355
  /** The host run tree's cross-boundary token (`RunInternals.crossBoundaryTree`, threaded by the run-workflow tool): every
352
356
  * workflow-spawned agent joins the tree it names, so a bit a workflow agent sets is read by the host and its siblings. */
353
357
  crossBoundaryTree?: import("../core/cross-boundary-taint.js").CrossBoundaryTreeToken;
@@ -15,7 +15,7 @@ import { combinePolicies, createAllowDenyPolicy } from "../core/tool-policy.js";
15
15
  import { createSafeNotifier } from "../core/safe-notify.js";
16
16
  import { callKeyOrdinal, clampRunIdText, oversizeJournalResult, journalOversizeTombstone, readWorkflowJournalEntry, JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES, WorkflowJournalIncompatibleError, } from "../core/workflow-journal-store.js";
17
17
  import { isWorkflowRunActive, closeWorkflowChannel, markWorkflowActive, publishWorkflowEvent, registerWorkflowParkDelivery } from "./workflow-observe.js";
18
- import { isDurablePause } from "../agents/suspend-guard.js";
18
+ import { isDurablePause, resumeNeverStarted } from "../agents/suspend-guard.js";
19
19
  import { RUNNING_AGENT_OBSERVE_EVERY_BEATS } from "../config/defaults.js";
20
20
  import { boundInputHashOf } from "../core/canonical-json.js";
21
21
  import { boundedRedactedSummary, egressThrownText } from "../core/untrusted-egress.js";
@@ -30,6 +30,7 @@ import { WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentBlocked
30
30
  import { WorkflowScriptError } from "./workflow-meta.js";
31
31
  import { firstByteLaneKnobMs, STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS } from "../brain/timeout.js";
32
32
  import { asThrownError, isErrorLike, readMember, thrownIs, thrownName, thrownText } from "../core/thrown-value.js";
33
+ import { bindSettledRun } from "../core/workflow-settled-run.js";
33
34
  export * from "./workflow-types.js";
34
35
  const MAX_TRANSCRIPT_CHARS = 4000;
35
36
  const WORKFLOW_RESULT_MAX = 4000;
@@ -727,6 +728,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
727
728
  };
728
729
  const spawnAttribution = {
729
730
  isDelegatedChild: true,
731
+ objectiveAuthor: "workflow",
730
732
  ...(opts.questionFaceStripped === true ? { questionFaceStripped: true } : {}),
731
733
  ...(opts.interactionPosture !== undefined ? { parentInteractionPosture: opts.interactionPosture } : {}),
732
734
  ...(opts.parentToolCallId !== undefined ? { parentToolCallId: opts.parentToolCallId } : {}),
@@ -738,6 +740,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
738
740
  ...(agentCeiling !== undefined ? { toolCeiling: agentCeiling } : {}),
739
741
  ...((opts.rootSessionId ?? opts.originatingSessionId) !== undefined ? { rootSessionId: opts.rootSessionId ?? opts.originatingSessionId } : {}),
740
742
  ...(opts.placementRoot !== undefined ? { placementRoot: opts.placementRoot } : {}),
743
+ ...(opts.placementTarget !== undefined ? { placementTarget: opts.placementTarget } : {}),
741
744
  ...(opts.crossBoundaryTree !== undefined ? { crossBoundaryTree: opts.crossBoundaryTree } : {}),
742
745
  ...(opts.originatingSessionId !== undefined ? { parentSessionId: opts.originatingSessionId } : {}),
743
746
  };
@@ -1060,7 +1063,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
1060
1063
  return p;
1061
1064
  };
1062
1065
  const degradedParkMaterial = (cp) => ({
1063
- taskId: cp.sourceTaskId ?? "",
1066
+ taskId: cp.sourceSessionId ?? "",
1064
1067
  sessionId: cp.sessionId,
1065
1068
  result: "",
1066
1069
  stats: { turns: 0, tokens: 0, costMicroUsd: 0, usageMissing: true },
@@ -1164,7 +1167,6 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
1164
1167
  throw Object.assign(new Error("agent.checkpointStore is not the store this run's children park in (the workflow's resolved checkpoint seat, RunWorkflowOptions.checkpointStore) — wire the one store, or leave the field unset and let the seat ride."), { code: "config.invalid_checkpoint_store" });
1165
1168
  }
1166
1169
  };
1167
- const driveNeverStarted = (r) => r.terminal.kind === "failed" && (r.terminal.code === "resume.reopened_unstarted" || r.terminal.code === "resume.reopen_failed_unstarted");
1168
1170
  const isPausedResult = (r) => isDurablePause(r.terminal);
1169
1171
  let isolationAdvised = false;
1170
1172
  const adviseIsolationIfConcurrent = (opts) => {
@@ -2151,7 +2153,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
2151
2153
  }
2152
2154
  if (finalized)
2153
2155
  return result;
2154
- const unstartedDrive = drive !== undefined && driveNeverStarted(result) ? drive : undefined;
2156
+ const unstartedDrive = drive !== undefined && resumeNeverStarted(result) ? drive : undefined;
2155
2157
  if (unstartedDrive !== undefined)
2156
2158
  emitRunLog(`[park] the parked leg "${label}" was driven but the approved action never started (${result.terminal.kind === "failed" ? result.terminal.code : ""}); the park stands.`);
2157
2159
  const parkOn = isPausedResult(result) ? { paused: result, live: true } : unstartedDrive !== undefined ? { paused: unstartedDrive.paused, live: false } : undefined;
@@ -2399,7 +2401,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
2399
2401
  releaseLeg();
2400
2402
  if (finalized)
2401
2403
  return result;
2402
- const unstartedDrive = drive !== undefined && driveNeverStarted(result) ? drive : undefined;
2404
+ const unstartedDrive = drive !== undefined && resumeNeverStarted(result) ? drive : undefined;
2403
2405
  if (unstartedDrive !== undefined)
2404
2406
  emitRunLog(`[park] the parked leg "${label}" was driven but the approved action never started (${result.terminal.kind === "failed" ? result.terminal.code : ""}); the park stands.`);
2405
2407
  const parkOn = isPausedResult(result) ? { paused: result, live: true } : unstartedDrive !== undefined ? { paused: unstartedDrive.paused, live: false } : undefined;
@@ -2850,6 +2852,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
2850
2852
  closeWorkflowChannel(runId);
2851
2853
  }
2852
2854
  })();
2855
+ bindSettledRun(done, run);
2853
2856
  return {
2854
2857
  runId,
2855
2858
  done,
@@ -1,9 +1,11 @@
1
1
  import { join } from "node:path";
2
- import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, assertBackgroundAgentReapOptions, queryBackgroundAgents, } from "../../core/background-agent-store.js";
2
+ import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, receiveBackgroundAgentReapOptions, queryBackgroundAgents, } from "../../core/background-agent-store.js";
3
3
  import { SharedLedgerTable } from "./shared-ledger.js";
4
4
  import { guardCorruptSink } from "./corrupt-read-sink.js";
5
5
  import { assertAdoptionBootGate } from "./adoption/marker.js";
6
- import { receiveOptions } from "../../core/own-property-receipt.js";
6
+ import { optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
7
+ import { readLedgerTuning } from "./ledger-tuning.js";
8
+ const FILE_BACKGROUND_AGENT_STORE_OPTION_KEYS = optionKeys()({ onCorruptRead: 0, fsync: 0, compactEvery: 0 });
7
9
  const isAgentRow = (x) => x !== null && typeof x === "object" && typeof x.handle === "string" && typeof x.scope === "string";
8
10
  const agentLedgers = new SharedLedgerTable({
9
11
  label: "background-agent ledger",
@@ -32,10 +34,11 @@ export class FileBackgroundAgentStore {
32
34
  return this.ledger.rows;
33
35
  }
34
36
  constructor(root, options) {
35
- const opts = receiveOptions(options, "FileBackgroundAgentStore");
37
+ const opts = receiveOptions(options, "FileBackgroundAgentStore", FILE_BACKGROUND_AGENT_STORE_OPTION_KEYS);
36
38
  assertAdoptionBootGate(root, "FileBackgroundAgentStore");
37
- this.fsyncEnabled = opts.fsync !== false;
38
- this.compactEvery = opts.compactEvery ?? 1000;
39
+ const tuning = readLedgerTuning(opts, "FileBackgroundAgentStore", "FileBackgroundAgentStore options");
40
+ this.fsyncEnabled = tuning.fsync;
41
+ this.compactEvery = tuning.compactEvery;
39
42
  const dir = join(root, "background-agents");
40
43
  this.ledger = agentLedgers.acquire({
41
44
  dir,
@@ -128,18 +131,18 @@ export class FileBackgroundAgentStore {
128
131
  });
129
132
  }
130
133
  async reap(scope, now, opts) {
131
- assertBackgroundAgentReapOptions(opts);
132
- if (!opts || (opts.maxAgeMs === undefined && opts.keep === undefined && opts.staleRunningMaxAgeMs === undefined))
134
+ const policy = receiveBackgroundAgentReapOptions(opts);
135
+ if (policy.maxAgeMs === undefined && policy.keep === undefined && policy.staleRunningMaxAgeMs === undefined)
133
136
  return 0;
134
137
  const changed = new Set();
135
- if (opts.staleRunningMaxAgeMs !== undefined) {
138
+ if (policy.staleRunningMaxAgeMs !== undefined) {
136
139
  const staleCandidates = [...this.rows.entries()]
137
- .filter(([, r]) => r.scope === scope && r.status === "running" && now - r.updatedAt > opts.staleRunningMaxAgeMs)
140
+ .filter(([, r]) => r.scope === scope && r.status === "running" && now - r.updatedAt > policy.staleRunningMaxAgeMs)
138
141
  .map(([k]) => k);
139
142
  for (const k of staleCandidates) {
140
143
  const flipped = await this.withLock(k, () => {
141
144
  const live = this.rows.get(k);
142
- if (!live || live.status !== "running" || now - live.updatedAt <= opts.staleRunningMaxAgeMs)
145
+ if (!live || live.status !== "running" || now - live.updatedAt <= policy.staleRunningMaxAgeMs)
143
146
  return false;
144
147
  const next = structuredClone(live);
145
148
  next.status = "failed";
@@ -160,14 +163,14 @@ export class FileBackgroundAgentStore {
160
163
  .filter(([, r]) => r.scope === scope && r.status !== "running" && r.status !== "parked")
161
164
  .sort(([, a], [, b]) => b.spawnedAt - a.spawnedAt);
162
165
  const doomed = new Map();
163
- if (opts.maxAgeMs !== undefined) {
166
+ if (policy.maxAgeMs !== undefined) {
164
167
  for (const [k, r] of terminal) {
165
- if ((r.settledAt ?? r.spawnedAt) < now - opts.maxAgeMs)
168
+ if ((r.settledAt ?? r.spawnedAt) < now - policy.maxAgeMs)
166
169
  doomed.set(k, { byAge: true });
167
170
  }
168
171
  }
169
- if (opts.keep !== undefined) {
170
- for (const [k] of terminal.slice(Math.max(0, opts.keep))) {
172
+ if (policy.keep !== undefined) {
173
+ for (const [k] of terminal.slice(Math.max(0, policy.keep))) {
171
174
  if (!doomed.has(k))
172
175
  doomed.set(k, { byAge: false });
173
176
  }
@@ -177,7 +180,7 @@ export class FileBackgroundAgentStore {
177
180
  const live = this.rows.get(k);
178
181
  if (!live || live.scope !== scope || live.status === "running" || live.status === "parked")
179
182
  return false;
180
- if (why.byAge && opts.maxAgeMs !== undefined && (live.settledAt ?? live.spawnedAt) >= now - opts.maxAgeMs)
183
+ if (why.byAge && policy.maxAgeMs !== undefined && (live.settledAt ?? live.spawnedAt) >= now - policy.maxAgeMs)
181
184
  return false;
182
185
  this.commit({ t: "delete", k });
183
186
  return true;
@@ -1,12 +1,14 @@
1
1
  import { join } from "node:path";
2
2
  import { assertAdoptionBootGate } from "./adoption/marker.js";
3
- import { receiveOptions } from "../../core/own-property-receipt.js";
3
+ import { optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
4
+ import { readLedgerTuning } from "./ledger-tuning.js";
4
5
  import { checkpointExecutionRecorded, executionRecordDisposition, ExecutionOutcomeConflictError, } from "../../core/checkpoint-execution-record.js";
5
6
  import { checkpointHolderMatches, checkpointOccMatches, checkpointRevOf } from "../../core/checkpoint-generation.js";
6
7
  import { appendPendingSteer, CheckpointError, checkpointRowMatches, encodeAtFidelity, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
7
8
  import { checkpointDeadlinePassed, deleteSessionRowsAtStart, readCheckpointOverdueQuery, readCheckpointSessionQuery, selectOverduePage, selectSessionPage, } from "../../core/checkpoint-queries.js";
8
9
  import { readLedgerSettled, SharedLedgerTable } from "./shared-ledger.js";
9
10
  import { guardCorruptSink } from "./corrupt-read-sink.js";
11
+ const FILE_CHECKPOINT_STORE_OPTION_KEYS = optionKeys()({ onCorruptRead: 0, fsync: 0, compactEvery: 0, sessionHeadOf: 0, holderIsCurrent: 0 });
10
12
  export const CHECKPOINT_LEDGER_EVENT_KINDS = Object.freeze(["put", "resolve", "reopen", "execution", "expire", "delete", "steer_append"]);
11
13
  const KNOWN_CHECKPOINT_LEDGER_EVENTS = new Set(CHECKPOINT_LEDGER_EVENT_KINDS);
12
14
  function applyCheckpointEvent(cps, ev) {
@@ -105,13 +107,14 @@ export class FileCheckpointStore {
105
107
  discloseCorrupt;
106
108
  ledgerPath;
107
109
  constructor(root, options) {
108
- const opts = receiveOptions(options, "FileCheckpointStore");
110
+ const opts = receiveOptions(options, "FileCheckpointStore", FILE_CHECKPOINT_STORE_OPTION_KEYS);
109
111
  assertAdoptionBootGate(root, "FileCheckpointStore");
110
- this.fsyncEnabled = opts.fsync !== false;
112
+ const tuning = readLedgerTuning(opts, "FileCheckpointStore", "FileCheckpointStore options");
113
+ this.fsyncEnabled = tuning.fsync;
111
114
  this.holderIsCurrent = opts.holderIsCurrent;
112
115
  if (opts.holderIsCurrent !== undefined)
113
116
  this.fence = Object.freeze({ holder: true });
114
- this.compactEvery = opts.compactEvery ?? 1000;
117
+ this.compactEvery = tuning.compactEvery;
115
118
  this.discloseCorrupt = guardCorruptSink(opts.onCorruptRead);
116
119
  const dir = join(root, "checkpoints");
117
120
  this.ledgerPath = join(dir, "checkpoints.jsonl");
@@ -8,7 +8,8 @@ import { atomicWriteFile, ensureDir, sanitizePathComponent, sanitizeScope, write
8
8
  import { guardCorruptSink } from "./corrupt-read-sink.js";
9
9
  import { isAbsoluteForFamily } from "../../tools/fs/safety.js";
10
10
  import { assertAdoptionBootGate } from "./adoption/marker.js";
11
- import { receiveOptions } from "../../core/own-property-receipt.js";
11
+ import { optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
12
+ const FILE_FILE_HISTORY_STORE_OPTION_KEYS = optionKeys()({ onCorruptRead: 0, retention: 0 });
12
13
  function trackedDigest(rows) {
13
14
  const canonical = [...rows]
14
15
  .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
@@ -157,7 +158,7 @@ export class FileFileHistoryStore {
157
158
  return this.lastCommittedAt;
158
159
  }
159
160
  constructor(root, options) {
160
- const opts = receiveOptions(options, "FileFileHistoryStore");
161
+ const opts = receiveOptions(options, "FileFileHistoryStore", FILE_FILE_HISTORY_STORE_OPTION_KEYS);
161
162
  assertAdoptionBootGate(root, "FileFileHistoryStore");
162
163
  this.boundaryKeep = resolveFileHistoryRetention("FileFileHistoryStore", opts?.retention);
163
164
  this.base = join(root, "file-history");
@@ -11,7 +11,7 @@ import type { FileHistoryStore } from "../../core/file-history-store.js";
11
11
  import type { BackgroundAgentStore } from "../../core/background-agent-store.js";
12
12
  import type { MailboxStore } from "../../core/mailbox-store.js";
13
13
  import type { RosterStore } from "../../agents/roster-store.js";
14
- import type { SessionPolicyStore } from "../../core/session-policy-store.js";
14
+ import { type SessionPolicyStore } from "../../core/session-policy-store.js";
15
15
  import type { WorkflowJournalStore } from "../../core/workflow-journal-store.js";
16
16
  import type { UsageWindowStore } from "../../core/usage-window-store.js";
17
17
  import type { EngineStorageBackend } from "../../core/engine-storage-backend.js";
@@ -67,8 +67,10 @@ export interface FileStorageBackendOptions {
67
67
  /** `TtlSessionStore` idle-eviction policy. Default `"forget"` (§7 decision 5 — durable history is never
68
68
  * deleted by an idle timer). */
69
69
  evict?: EvictPolicy;
70
- /** Checkpoint store tuning (fsync cadence for `put`/`setPendingSteer`, ledger compaction threshold). */
71
- checkpoint?: FileCheckpointStoreOptions;
70
+ /** Checkpoint store tuning (fsync cadence for `put`/`setPendingSteer`, ledger compaction threshold, the holder judge). The
71
+ * corrupt-read sink and the session head read are the backend's own — the sink is {@link FileStorageBackendOptions.onCorruptRead}
72
+ * (one failure grammar, one sink) and the head read is its session store's — so neither is accepted here. */
73
+ checkpoint?: Omit<FileCheckpointStoreOptions, "onCorruptRead" | "sessionHeadOf">;
72
74
  /**
73
75
  * design/381 §片2 — file-history tuning, today just the boundary RETENTION bound (omitted ⇒ the
74
76
  * engine default; `{ retention: { keep: "unbounded" } }` hands the GC schedule to the deployment).