@sema-agent/core 7.60.0 → 7.62.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (560) hide show
  1. package/CHANGELOG.md +917 -0
  2. package/README.md +2 -2
  3. package/dist/agents/agent-transcript-tool.d.ts +2 -2
  4. package/dist/agents/agent-transcript-tool.js +1 -1
  5. package/dist/agents/cascade.d.ts +71 -12
  6. package/dist/agents/cascade.js +61 -21
  7. package/dist/agents/composition-allowance.d.ts +53 -0
  8. package/dist/agents/composition-allowance.js +49 -0
  9. package/dist/agents/composition-placement.d.ts +29 -0
  10. package/dist/agents/composition-placement.js +24 -0
  11. package/dist/agents/cumulative-stats.d.ts +4 -0
  12. package/dist/agents/cumulative-stats.js +3 -0
  13. package/dist/agents/inherited-tool-pool.d.ts +5 -3
  14. package/dist/agents/inherited-tool-pool.js +2 -2
  15. package/dist/agents/list-agents-tool.d.ts +1 -1
  16. package/dist/agents/peer-held-queue.d.ts +27 -4
  17. package/dist/agents/peer-held-queue.js +81 -36
  18. package/dist/agents/peer-notice-route.d.ts +1 -1
  19. package/dist/agents/peer-notice-route.js +4 -3
  20. package/dist/agents/peer-notices.d.ts +4 -4
  21. package/dist/agents/peer-notices.js +8 -4
  22. package/dist/agents/peer-session-drain.d.ts +8 -1
  23. package/dist/agents/peer-session-drain.js +49 -10
  24. package/dist/agents/repair-loop.js +16 -6
  25. package/dist/agents/retain-ledger.js +3 -1
  26. package/dist/agents/roster-store.d.ts +1 -1
  27. package/dist/agents/roster-store.js +7 -4
  28. package/dist/agents/send-message-tool.d.ts +8 -10
  29. package/dist/agents/send-message-tool.js +43 -23
  30. package/dist/agents/subagent-completion-gate.d.ts +35 -0
  31. package/dist/agents/subagent-completion-gate.js +62 -0
  32. package/dist/agents/subagent-steps.d.ts +7 -6
  33. package/dist/agents/subagent.d.ts +36 -41
  34. package/dist/agents/subagent.js +245 -200
  35. package/dist/agents/suspend-guard.d.ts +47 -16
  36. package/dist/agents/suspend-guard.js +13 -4
  37. package/dist/agents/verify.d.ts +41 -14
  38. package/dist/agents/verify.js +41 -30
  39. package/dist/brain/anthropic.js +1 -0
  40. package/dist/brain/errors.d.ts +7 -1
  41. package/dist/brain/errors.js +6 -0
  42. package/dist/brain/failover.js +2 -1
  43. package/dist/brain/open-responses.js +1 -0
  44. package/dist/brain/openai.js +1 -0
  45. package/dist/brain/provider-dialect.d.ts +10 -0
  46. package/dist/brain/provider-dialect.js +13 -2
  47. package/dist/brain/stream-engine.d.ts +3 -0
  48. package/dist/brain/stream-engine.js +4 -0
  49. package/dist/core/agent-state.d.ts +1 -1
  50. package/dist/core/allow-entry.d.ts +59 -23
  51. package/dist/core/allow-entry.js +131 -38
  52. package/dist/core/ask-origin.d.ts +79 -0
  53. package/dist/core/ask-origin.js +76 -0
  54. package/dist/core/ask-question.d.ts +19 -13
  55. package/dist/core/ask-question.js +8 -2
  56. package/dist/core/auto-compaction.d.ts +2 -0
  57. package/dist/core/auto-compaction.js +2 -1
  58. package/dist/core/auto-mode.js +3 -5
  59. package/dist/core/background-agent-store.d.ts +7 -5
  60. package/dist/core/background-agent-store.js +12 -11
  61. package/dist/core/checkpoint-features.d.ts +722 -0
  62. package/dist/core/checkpoint-features.js +98 -0
  63. package/dist/core/checkpoint-requirements.d.ts +33 -5
  64. package/dist/core/checkpoint-requirements.js +18 -5
  65. package/dist/core/checkpoint-row-verdict.d.ts +99 -0
  66. package/dist/core/checkpoint-row-verdict.js +225 -0
  67. package/dist/core/checkpoint-store.d.ts +107 -738
  68. package/dist/core/checkpoint-store.js +45 -143
  69. package/dist/core/child-clamp-seats.d.ts +3 -2
  70. package/dist/core/child-clamp-seats.js +4 -3
  71. package/dist/core/closest-name.d.ts +13 -0
  72. package/dist/core/closest-name.js +35 -0
  73. package/dist/core/context-settings.js +3 -5
  74. package/dist/core/cross-boundary-taint.d.ts +1 -1
  75. package/dist/core/decision-receipt.d.ts +14 -1
  76. package/dist/core/decision-receipt.js +6 -3
  77. package/dist/core/delegation-frames.d.ts +13 -9
  78. package/dist/core/effective-path-target.js +2 -3
  79. package/dist/core/engine-attestation.d.ts +11 -1
  80. package/dist/core/engine-attestation.js +2 -0
  81. package/dist/core/engine-notice.d.ts +68 -21
  82. package/dist/core/engine-notice.js +9 -2
  83. package/dist/core/file-history-retention.d.ts +8 -0
  84. package/dist/core/file-history-retention.js +14 -11
  85. package/dist/core/file-history-store.d.ts +31 -1
  86. package/dist/core/file-history-store.js +31 -2
  87. package/dist/core/frame-settlement.d.ts +10 -0
  88. package/dist/core/frame-settlement.js +6 -1
  89. package/dist/core/fs-write-gate-policy.d.ts +3 -3
  90. package/dist/core/fs-write-gate-policy.js +8 -7
  91. package/dist/core/gate-fold.js +4 -3
  92. package/dist/core/gate-lanes.js +7 -4
  93. package/dist/core/gate-outcome.d.ts +40 -1
  94. package/dist/core/gate-outcome.js +10 -0
  95. package/dist/core/git-worktree-env.d.ts +7 -3
  96. package/dist/core/git-worktree-env.js +16 -13
  97. package/dist/core/governance-codes.d.ts +14 -4
  98. package/dist/core/governance-codes.js +19 -4
  99. package/dist/core/hooks.d.ts +25 -4
  100. package/dist/core/hooks.js +11 -4
  101. package/dist/core/host-floor.js +3 -5
  102. package/dist/core/human-input-projection.d.ts +1 -0
  103. package/dist/core/human-input-projection.js +3 -0
  104. package/dist/core/image-admission.d.ts +47 -7
  105. package/dist/core/image-admission.js +35 -4
  106. package/dist/core/input-author.d.ts +36 -0
  107. package/dist/core/input-author.js +39 -0
  108. package/dist/core/leg-identity.d.ts +62 -0
  109. package/dist/core/leg-identity.js +18 -0
  110. package/dist/core/locked-config.d.ts +4 -3
  111. package/dist/core/locked-config.js +5 -3
  112. package/dist/core/lsp.d.ts +5 -3
  113. package/dist/core/lsp.js +3 -2
  114. package/dist/core/mailbox-store.d.ts +85 -10
  115. package/dist/core/mailbox-store.js +31 -10
  116. package/dist/core/mcp-connection-pool.d.ts +6 -20
  117. package/dist/core/mcp-connection-pool.js +10 -28
  118. package/dist/core/mcp-failure.d.ts +76 -15
  119. package/dist/core/mcp-failure.js +60 -33
  120. package/dist/core/mcp-host-seat.d.ts +92 -53
  121. package/dist/core/mcp-host-seat.js +225 -46
  122. package/dist/core/mcp-probe.js +2 -2
  123. package/dist/core/mcp-server-link.d.ts +18 -6
  124. package/dist/core/mcp-server-link.js +19 -4
  125. package/dist/core/mcp-server-spec.d.ts +2 -1
  126. package/dist/core/mcp-session-end.d.ts +1 -2
  127. package/dist/core/mcp-session-end.js +1 -1
  128. package/dist/core/mcp.d.ts +6 -49
  129. package/dist/core/mcp.js +115 -111
  130. package/dist/core/media-byte-cap.d.ts +21 -46
  131. package/dist/core/media-byte-cap.js +55 -55
  132. package/dist/core/member-group.d.ts +7 -0
  133. package/dist/core/member-group.js +35 -0
  134. package/dist/core/memory-engine/consolidation-driver.d.ts +1 -1
  135. package/dist/core/memory-engine/consolidation.d.ts +1 -1
  136. package/dist/core/memory-engine/consolidation.js +7 -1
  137. package/dist/core/memory-engine/dual-root.d.ts +31 -0
  138. package/dist/core/memory-engine/dual-root.js +59 -11
  139. package/dist/core/memory-engine/engine.js +27 -24
  140. package/dist/core/memory-engine/file-backend.d.ts +13 -0
  141. package/dist/core/memory-engine/file-backend.js +35 -15
  142. package/dist/core/memory-engine/layout.d.ts +3 -0
  143. package/dist/core/memory-engine/layout.js +13 -3
  144. package/dist/core/memory-engine/memory-deployment.d.ts +110 -0
  145. package/dist/core/memory-engine/memory-deployment.js +182 -0
  146. package/dist/core/memory-engine/sync-client.d.ts +39 -18
  147. package/dist/core/memory-engine/sync-client.js +72 -14
  148. package/dist/core/memory-engine/sync-report.d.ts +7 -4
  149. package/dist/core/memory-engine/sync.d.ts +9 -1
  150. package/dist/core/memory-vector.d.ts +1 -1
  151. package/dist/core/memory.d.ts +10 -10
  152. package/dist/core/mode-policy.d.ts +8 -8
  153. package/dist/core/mode-policy.js +8 -6
  154. package/dist/core/mods/agent-stations.d.ts +39 -4
  155. package/dist/core/mods/agent-stations.js +59 -10
  156. package/dist/core/mods/classic-events.d.ts +9 -1
  157. package/dist/core/mods/dollar.d.ts +94 -1
  158. package/dist/core/mods/dollar.js +13 -1
  159. package/dist/core/mods/extension-call.d.ts +15 -1
  160. package/dist/core/mods/extension-call.js +7 -2
  161. package/dist/core/mods/kernel/dispatch.d.ts +4 -3
  162. package/dist/core/mods/kernel/dispatch.js +4 -4
  163. package/dist/core/mods/kernel/events.d.ts +14 -3
  164. package/dist/core/mods/kernel/events.js +18 -15
  165. package/dist/core/mods/kernel/registration.d.ts +3 -0
  166. package/dist/core/mods/kernel/registration.js +5 -0
  167. package/dist/core/mods/kernel/site-rules.d.ts +6 -3
  168. package/dist/core/mods/kernel/site-rules.js +10 -2
  169. package/dist/core/mods/lifecycle-stations.d.ts +36 -4
  170. package/dist/core/mods/lifecycle-stations.js +44 -9
  171. package/dist/core/mods/session-append.d.ts +118 -0
  172. package/dist/core/mods/session-append.js +318 -0
  173. package/dist/core/mods/session-compact.d.ts +48 -0
  174. package/dist/core/mods/session-compact.js +194 -0
  175. package/dist/core/mods/session-receive.d.ts +93 -0
  176. package/dist/core/mods/session-receive.js +138 -0
  177. package/dist/core/mods/session-send.d.ts +72 -0
  178. package/dist/core/mods/session-send.js +88 -0
  179. package/dist/core/mods/stations.d.ts +88 -21
  180. package/dist/core/mods/stations.js +149 -11
  181. package/dist/core/mods/tool-call.d.ts +2 -0
  182. package/dist/core/mods/tool-call.js +4 -4
  183. package/dist/core/output-style.js +3 -4
  184. package/dist/core/own-property-receipt.d.ts +68 -2
  185. package/dist/core/own-property-receipt.js +45 -2
  186. package/dist/core/park-selfcheck.js +4 -2
  187. package/dist/core/path-identity.d.ts +11 -0
  188. package/dist/core/path-identity.js +4 -0
  189. package/dist/core/path-rule-binding.d.ts +3 -1
  190. package/dist/core/path-rule-binding.js +3 -1
  191. package/dist/core/peer-seat.d.ts +3 -3
  192. package/dist/core/peer-seat.js +20 -8
  193. package/dist/core/permission-rule-consent.d.ts +21 -5
  194. package/dist/core/permission-rule-consent.js +21 -1
  195. package/dist/core/permission-rule-model.d.ts +34 -11
  196. package/dist/core/permission-rule-model.js +47 -10
  197. package/dist/core/permission-rule-org.d.ts +1 -1
  198. package/dist/core/permission-rule-provider.js +4 -1
  199. package/dist/core/permission-rules.d.ts +4 -0
  200. package/dist/core/permission-rules.js +11 -16
  201. package/dist/core/read-root-candidate.js +1 -1
  202. package/dist/core/remote-env.d.ts +74 -26
  203. package/dist/core/remote-env.js +20 -0
  204. package/dist/core/resume-startup-cause.d.ts +5 -4
  205. package/dist/core/retention-policy.d.ts +24 -23
  206. package/dist/core/retention-policy.js +36 -2
  207. package/dist/core/retention.d.ts +4 -1
  208. package/dist/core/retired-keys.d.ts +4 -4
  209. package/dist/core/row-admission.d.ts +10 -0
  210. package/dist/core/row-admission.js +5 -0
  211. package/dist/core/runner/advisor-instructions.d.ts +2 -1
  212. package/dist/core/runner/advisor-instructions.js +2 -1
  213. package/dist/core/runner/announce-once-ledger.d.ts +4 -4
  214. package/dist/core/runner/assemble-result.d.ts +13 -3
  215. package/dist/core/runner/assemble-result.js +12 -7
  216. package/dist/core/runner/caller-roster.d.ts +12 -9
  217. package/dist/core/runner/caller-roster.js +5 -2
  218. package/dist/core/runner/checkpoint-scope.d.ts +16 -1
  219. package/dist/core/runner/checkpoint-scope.js +21 -0
  220. package/dist/core/runner/compact-session.js +18 -3
  221. package/dist/core/runner/compaction-call-options.d.ts +1 -1
  222. package/dist/core/runner/compaction-restate.d.ts +2 -2
  223. package/dist/core/runner/compaction-restate.js +4 -3
  224. package/dist/core/runner/construction-doors.d.ts +2 -2
  225. package/dist/core/runner/construction-doors.js +2 -2
  226. package/dist/core/runner/contracts.d.ts +116 -34
  227. package/dist/core/runner/cross-boundary-lane.d.ts +1 -1
  228. package/dist/core/runner/decide-continuation.d.ts +4 -2
  229. package/dist/core/runner/decide-continuation.js +7 -4
  230. package/dist/core/runner/delegation-owner.d.ts +43 -0
  231. package/dist/core/runner/delegation-owner.js +59 -0
  232. package/dist/core/runner/denial-limit-arms.d.ts +15 -21
  233. package/dist/core/runner/denial-limit-arms.js +17 -10
  234. package/dist/core/runner/expire-settle.d.ts +44 -0
  235. package/dist/core/runner/expire-settle.js +55 -0
  236. package/dist/core/runner/git-status-frame.d.ts +3 -3
  237. package/dist/core/runner/git-status-frame.js +2 -1
  238. package/dist/core/runner/halt-attribution.d.ts +2 -1
  239. package/dist/core/runner/halt-attribution.js +2 -1
  240. package/dist/core/runner/lineage-reroot-view.d.ts +56 -0
  241. package/dist/core/runner/lineage-reroot-view.js +108 -0
  242. package/dist/core/runner/local-claims.d.ts +17 -0
  243. package/dist/core/runner/local-claims.js +18 -0
  244. package/dist/core/runner/media-removed-seat.d.ts +46 -0
  245. package/dist/core/runner/media-removed-seat.js +88 -0
  246. package/dist/core/runner/park-commit.d.ts +2 -2
  247. package/dist/core/runner/permission-rule-lanes.d.ts +7 -2
  248. package/dist/core/runner/permission-rule-lanes.js +28 -9
  249. package/dist/core/runner/person-path-rows.d.ts +15 -0
  250. package/dist/core/runner/person-path-rows.js +27 -4
  251. package/dist/core/runner/placement-fence.d.ts +26 -0
  252. package/dist/core/runner/placement-fence.js +38 -0
  253. package/dist/core/runner/prepare-acquire-reconcile.d.ts +4 -1
  254. package/dist/core/runner/prepare-acquire-reconcile.js +7 -2
  255. package/dist/core/runner/prepare-ask-lane.d.ts +6 -12
  256. package/dist/core/runner/prepare-ask-lane.js +4 -4
  257. package/dist/core/runner/prepare-boundary-parks.d.ts +4 -1
  258. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  259. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -0
  260. package/dist/core/runner/prepare-caps-and-workflow.js +2 -1
  261. package/dist/core/runner/prepare-config-doors.d.ts +6 -6
  262. package/dist/core/runner/prepare-config-doors.js +19 -21
  263. package/dist/core/runner/prepare-context-lane.d.ts +6 -2
  264. package/dist/core/runner/prepare-context-lane.js +13 -13
  265. package/dist/core/runner/prepare-delegation-surface.d.ts +9 -9
  266. package/dist/core/runner/prepare-delegation-surface.js +4 -5
  267. package/dist/core/runner/prepare-execution-env.d.ts +5 -2
  268. package/dist/core/runner/prepare-execution-env.js +7 -4
  269. package/dist/core/runner/prepare-gate-stations.d.ts +19 -14
  270. package/dist/core/runner/prepare-gate-stations.js +6 -4
  271. package/dist/core/runner/prepare-hands-readface.d.ts +6 -6
  272. package/dist/core/runner/prepare-hands-readface.js +32 -11
  273. package/dist/core/runner/prepare-inherited-gate.d.ts +8 -0
  274. package/dist/core/runner/prepare-inherited-gate.js +10 -3
  275. package/dist/core/runner/prepare-lsp.d.ts +3 -0
  276. package/dist/core/runner/prepare-lsp.js +2 -2
  277. package/dist/core/runner/prepare-park-ask.d.ts +5 -2
  278. package/dist/core/runner/prepare-park-ask.js +4 -5
  279. package/dist/core/runner/prepare-policy-chain.d.ts +10 -21
  280. package/dist/core/runner/prepare-policy-chain.js +16 -25
  281. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  282. package/dist/core/runner/prepare-prompt-inputs.d.ts +5 -4
  283. package/dist/core/runner/prepare-prompt-inputs.js +3 -2
  284. package/dist/core/runner/prepare-question-face.d.ts +6 -4
  285. package/dist/core/runner/prepare-question-face.js +2 -2
  286. package/dist/core/runner/prepare-run-refs.d.ts +3 -0
  287. package/dist/core/runner/prepare-run-refs.js +2 -2
  288. package/dist/core/runner/prepare-suspend-saga.d.ts +11 -7
  289. package/dist/core/runner/prepare-suspend-saga.js +17 -7
  290. package/dist/core/runner/prepare-task.d.ts +1 -1
  291. package/dist/core/runner/prepare-task.js +61 -30
  292. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +6 -0
  293. package/dist/core/runner/prepare-tool-disclosure-mount.js +3 -1
  294. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -0
  295. package/dist/core/runner/prepare-wiring-manifest.js +2 -1
  296. package/dist/core/runner/prepare-workspace-restore.d.ts +5 -0
  297. package/dist/core/runner/prepare-workspace-restore.js +10 -6
  298. package/dist/core/runner/read-root-grant.d.ts +1 -1
  299. package/dist/core/runner/read-root-grant.js +2 -1
  300. package/dist/core/runner/resume-admission.d.ts +8 -6
  301. package/dist/core/runner/resume-admission.js +23 -6
  302. package/dist/core/runner/resume-apply.d.ts +4 -0
  303. package/dist/core/runner/resume-apply.js +14 -5
  304. package/dist/core/runner/resume-checkpoint-screen.d.ts +9 -0
  305. package/dist/core/runner/resume-checkpoint-screen.js +4 -84
  306. package/dist/core/runner/resume-claim.d.ts +8 -3
  307. package/dist/core/runner/resume-claim.js +28 -12
  308. package/dist/core/runner/resume-internals-and-config.d.ts +2 -2
  309. package/dist/core/runner/resume-internals-and-config.js +10 -1
  310. package/dist/core/runner/resume-preflight.d.ts +3 -2
  311. package/dist/core/runner/resume-preflight.js +13 -26
  312. package/dist/core/runner/retired-runner-deps.js +2 -0
  313. package/dist/core/runner/run-git-lane.d.ts +2 -0
  314. package/dist/core/runner/run-git-lane.js +6 -2
  315. package/dist/core/runner/run-harness-handlers.d.ts +2 -0
  316. package/dist/core/runner/run-harness-handlers.js +5 -4
  317. package/dist/core/runner/run-identity-wiring.d.ts +2 -2
  318. package/dist/core/runner/run-identity-wiring.js +14 -5
  319. package/dist/core/runner/run-leg.d.ts +3 -3
  320. package/dist/core/runner/run-leg.js +64 -36
  321. package/dist/core/runner/run-notification-lane.js +20 -2
  322. package/dist/core/runner/run-recovery-lanes.js +3 -2
  323. package/dist/core/runner/run-settle-and-teardown.js +12 -9
  324. package/dist/core/runner/run-stop-and-final-verify.js +2 -1
  325. package/dist/core/runner/run-telemetry-and-budget-seats.d.ts +1 -1
  326. package/dist/core/runner/run-terminal-adoption.d.ts +1 -1
  327. package/dist/core/runner/run-terminal-adoption.js +26 -17
  328. package/dist/core/runner/run-turn-boundary.js +34 -18
  329. package/dist/core/runner/runtask.d.ts +18 -3
  330. package/dist/core/runner/runtask.js +33 -17
  331. package/dist/core/runner/session-rule-policy.d.ts +1 -1
  332. package/dist/core/runner/session-rule-policy.js +6 -1
  333. package/dist/core/runner/shell-env-withheld.d.ts +1 -1
  334. package/dist/core/runner/steering-preview.d.ts +9 -0
  335. package/dist/core/runner/steering-preview.js +5 -0
  336. package/dist/core/runner/stream-halt-verbs.d.ts +1 -14
  337. package/dist/core/runner/stream-halt-verbs.js +4 -3
  338. package/dist/core/runner/stream-reap.d.ts +7 -6
  339. package/dist/core/runner/stream-reap.js +13 -16
  340. package/dist/core/runner/stream-settle-backstop.d.ts +3 -2
  341. package/dist/core/runner/stream-settle-backstop.js +5 -3
  342. package/dist/core/runner/stream-steer-verb.d.ts +5 -2
  343. package/dist/core/runner/stream-steer-verb.js +16 -7
  344. package/dist/core/runner/terminal-account.d.ts +11 -1
  345. package/dist/core/runner/terminal-account.js +20 -0
  346. package/dist/core/runner/terminal-projection.d.ts +8 -2
  347. package/dist/core/runner/terminal-projection.js +2 -2
  348. package/dist/core/runner/tool-disclosure.d.ts +3 -0
  349. package/dist/core/runner/tool-disclosure.js +5 -2
  350. package/dist/core/runner/tool-end-body.d.ts +3 -3
  351. package/dist/core/runner/tool-end-body.js +1 -1
  352. package/dist/core/runner/tool-face-overlay.js +2 -0
  353. package/dist/core/runner/tool-output-projection.d.ts +3 -3
  354. package/dist/core/runner/tool-output-projection.js +7 -6
  355. package/dist/core/runner/tool-table-view.d.ts +56 -0
  356. package/dist/core/runner/tool-table-view.js +51 -0
  357. package/dist/core/runner/turn-attachments.d.ts +8 -2
  358. package/dist/core/runner/turn-attachments.js +2 -2
  359. package/dist/core/runner/void-verifier-pause.d.ts +33 -0
  360. package/dist/core/runner/void-verifier-pause.js +41 -0
  361. package/dist/core/runner-deps.d.ts +26 -27
  362. package/dist/core/secret-env.d.ts +19 -16
  363. package/dist/core/secret-env.js +45 -27
  364. package/dist/core/session-log-transfer.js +9 -10
  365. package/dist/core/session-policy-store.d.ts +1 -1
  366. package/dist/core/session-policy-store.js +5 -2
  367. package/dist/core/session-reconcile.d.ts +3 -2
  368. package/dist/core/session-reconcile.js +7 -4
  369. package/dist/core/session-store.d.ts +3 -1
  370. package/dist/core/session-store.js +10 -8
  371. package/dist/core/session.d.ts +16 -5
  372. package/dist/core/shell-confinement.d.ts +37 -0
  373. package/dist/core/shell-confinement.js +56 -0
  374. package/dist/core/skill-grant.js +1 -1
  375. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +8 -2
  376. package/dist/core/store-contracts/checkpoint-store-contract.js +83 -2
  377. package/dist/core/store-contracts/file-history-store-contract.d.ts +5 -2
  378. package/dist/core/store-contracts/file-history-store-contract.js +25 -1
  379. package/dist/core/store-contracts/mailbox-store-contract.d.ts +12 -5
  380. package/dist/core/store-contracts/mailbox-store-contract.js +156 -9
  381. package/dist/core/store-contracts/session-store-contract.js +22 -8
  382. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  383. package/dist/core/store-contracts/tool-result-store-contract.js +30 -0
  384. package/dist/core/task-event.d.ts +24 -9
  385. package/dist/core/task-limits.d.ts +5 -0
  386. package/dist/core/task-notification.d.ts +89 -12
  387. package/dist/core/task-notification.js +89 -14
  388. package/dist/core/task-registry-agent.d.ts +32 -50
  389. package/dist/core/task-registry-agent.js +36 -56
  390. package/dist/core/task-registry-monitor.d.ts +1 -1
  391. package/dist/core/task-registry-monitor.js +15 -60
  392. package/dist/core/task-registry-shared.d.ts +22 -112
  393. package/dist/core/task-registry-shared.js +3 -41
  394. package/dist/core/task-registry-workflow.js +5 -21
  395. package/dist/core/task-registry.d.ts +32 -62
  396. package/dist/core/task-registry.js +30 -110
  397. package/dist/core/task-result.d.ts +29 -12
  398. package/dist/core/task-spec-members.d.ts +39 -0
  399. package/dist/core/task-spec-members.js +92 -0
  400. package/dist/core/task-spec.d.ts +11 -11
  401. package/dist/core/task-tool-shape.d.ts +7 -57
  402. package/dist/core/task-tool-shape.js +7 -66
  403. package/dist/core/terminal-cause.d.ts +36 -6
  404. package/dist/core/terminal-cause.js +1 -0
  405. package/dist/core/tool-catalog-entries.js +2 -5
  406. package/dist/core/tool-check-reading.js +16 -10
  407. package/dist/core/tool-conformance.js +1 -2
  408. package/dist/core/tool-errors.d.ts +6 -3
  409. package/dist/core/tool-errors.js +2 -0
  410. package/dist/core/tool-face-reader.js +3 -2
  411. package/dist/core/tool-face.d.ts +8 -5
  412. package/dist/core/tool-face.js +1 -1
  413. package/dist/core/tool-name-aliases.d.ts +5 -29
  414. package/dist/core/tool-name-aliases.js +9 -5
  415. package/dist/core/tool-name-readings.d.ts +14 -3
  416. package/dist/core/tool-name-readings.js +2 -0
  417. package/dist/core/tool-policy.d.ts +109 -18
  418. package/dist/core/tool-policy.js +84 -14
  419. package/dist/core/tool-result-store.d.ts +23 -0
  420. package/dist/core/tool-result-store.js +3 -2
  421. package/dist/core/tool-roster.d.ts +4 -4
  422. package/dist/core/tool-spec.d.ts +23 -6
  423. package/dist/core/trace.d.ts +18 -1
  424. package/dist/core/types.d.ts +1 -1
  425. package/dist/core/types.js +1 -1
  426. package/dist/core/user-attachment.js +26 -21
  427. package/dist/core/workflow-journal-store.d.ts +1 -1
  428. package/dist/core/workflow-run-store.d.ts +2 -0
  429. package/dist/core/workflow-run-store.js +6 -5
  430. package/dist/core/workflow-settled-run.d.ts +5 -0
  431. package/dist/core/workflow-settled-run.js +7 -0
  432. package/dist/engine/execution-env/node-execution-env.d.ts +37 -9
  433. package/dist/engine/execution-env/node-execution-env.js +221 -22
  434. package/dist/engine/harness/agent-harness.d.ts +65 -18
  435. package/dist/engine/harness/agent-harness.js +90 -23
  436. package/dist/engine/harness/messages.d.ts +4 -3
  437. package/dist/engine/harness/messages.js +2 -2
  438. package/dist/engine/harness/types.d.ts +52 -7
  439. package/dist/engine/llm/media-removed.d.ts +14 -0
  440. package/dist/engine/llm/media-removed.js +9 -0
  441. package/dist/engine/llm/rejected-images.d.ts +35 -25
  442. package/dist/engine/llm/rejected-images.js +59 -10
  443. package/dist/engine/llm/types.d.ts +24 -3
  444. package/dist/engine/llm/types.js +7 -3
  445. package/dist/engine/loop/agent-loop.d.ts +6 -1
  446. package/dist/engine/loop/agent-loop.js +20 -11
  447. package/dist/engine/loop/types.d.ts +12 -3
  448. package/dist/engine/session/import-validate.js +7 -0
  449. package/dist/engine/session/parent-chain-guard.d.ts +3 -3
  450. package/dist/engine/session/parent-chain-guard.js +1 -1
  451. package/dist/engine/session/path-to-root.d.ts +18 -3
  452. package/dist/engine/session/path-to-root.js +15 -1
  453. package/dist/engine/session/repo-utils.d.ts +12 -1
  454. package/dist/engine/session/repo-utils.js +41 -0
  455. package/dist/engine/session/session.js +1 -1
  456. package/dist/engine/session/storage-base.d.ts +20 -0
  457. package/dist/engine/session/storage-base.js +28 -9
  458. package/dist/fixtures/index.d.ts +7 -5
  459. package/dist/fixtures/index.js +5 -3
  460. package/dist/index.d.ts +29 -18
  461. package/dist/index.js +19 -11
  462. package/dist/internal/harness-types.d.ts +2 -0
  463. package/dist/internal/harness.d.ts +4 -3
  464. package/dist/internal/harness.js +3 -2
  465. package/dist/internal/llm.d.ts +2 -1
  466. package/dist/internal/llm.js +1 -0
  467. package/dist/orchestration/goal.d.ts +6 -2
  468. package/dist/orchestration/goal.js +6 -3
  469. package/dist/orchestration/run-workflow-tool.d.ts +14 -17
  470. package/dist/orchestration/run-workflow-tool.js +43 -50
  471. package/dist/orchestration/workflow-types.d.ts +2 -2
  472. package/dist/orchestration/workflow.d.ts +7 -0
  473. package/dist/orchestration/workflow.js +10 -12
  474. package/dist/stores/file/background-agent-store.js +18 -15
  475. package/dist/stores/file/checkpoint-store.d.ts +2 -0
  476. package/dist/stores/file/checkpoint-store.js +13 -9
  477. package/dist/stores/file/file-history-store.js +3 -2
  478. package/dist/stores/file/fs-atomic.d.ts +0 -22
  479. package/dist/stores/file/fs-atomic.js +0 -17
  480. package/dist/stores/file/index.d.ts +7 -12
  481. package/dist/stores/file/index.js +25 -12
  482. package/dist/stores/file/ledger-tuning.d.ts +23 -0
  483. package/dist/stores/file/ledger-tuning.js +21 -0
  484. package/dist/stores/file/mailbox-store.js +42 -22
  485. package/dist/stores/file/memory-store.js +3 -2
  486. package/dist/stores/file/permission-rule-adopt.js +24 -21
  487. package/dist/stores/file/permission-rule-store.js +6 -3
  488. package/dist/stores/file/session-policy-store.js +3 -2
  489. package/dist/stores/file/session-store.d.ts +26 -7
  490. package/dist/stores/file/session-store.js +59 -35
  491. package/dist/stores/file/tool-result-store.d.ts +11 -0
  492. package/dist/stores/file/tool-result-store.js +57 -3
  493. package/dist/stores/file/usage-window-store.js +3 -2
  494. package/dist/stores/file/workflow-journal-store.d.ts +0 -2
  495. package/dist/stores/file/workflow-journal-store.js +3 -18
  496. package/dist/stores/file/workflow-run-store.d.ts +1 -1
  497. package/dist/stores/file/workflow-run-store.js +15 -10
  498. package/dist/tools/fs/bash-program-position.d.ts +3 -2
  499. package/dist/tools/fs/bash-program-position.js +7 -7
  500. package/dist/tools/fs/dead-cwd.d.ts +5 -5
  501. package/dist/tools/fs/dead-cwd.js +4 -11
  502. package/dist/tools/fs/fs-bash-background-text.d.ts +6 -0
  503. package/dist/tools/fs/fs-bash-background-text.js +6 -0
  504. package/dist/tools/fs/fs-bash.d.ts +3 -18
  505. package/dist/tools/fs/fs-bash.js +37 -124
  506. package/dist/tools/fs/fs-pdf.js +8 -6
  507. package/dist/tools/fs/fs-read.js +2 -2
  508. package/dist/tools/fs/fs-shared.d.ts +28 -3
  509. package/dist/tools/fs/fs-shared.js +15 -0
  510. package/dist/tools/fs/index.d.ts +1 -1
  511. package/dist/tools/fs/index.js +4 -14
  512. package/dist/tools/fs/pdf.d.ts +4 -4
  513. package/dist/tools/fs/pdf.js +6 -6
  514. package/dist/tools/fs/read-deny-home.js +8 -1
  515. package/dist/tools/fs/read-deny.d.ts +26 -2
  516. package/dist/tools/fs/read-deny.js +9 -2
  517. package/dist/tools/fs/read-floor.d.ts +13 -5
  518. package/dist/tools/fs/read-floor.js +206 -2
  519. package/dist/tools/fs/removal-targets.js +2 -2
  520. package/dist/tools/fs/search.d.ts +3 -2
  521. package/dist/tools/fs/search.js +6 -6
  522. package/dist/tools/fs/shell-read-argv.d.ts +4 -2
  523. package/dist/tools/fs/shell-read-argv.js +14 -3
  524. package/dist/tools/fs/shell-read-bindings.d.ts +18 -2
  525. package/dist/tools/fs/shell-read-bindings.js +148 -68
  526. package/dist/tools/fs/shell-read-check.js +20 -4
  527. package/dist/tools/fs/shell-read-establish.js +25 -9
  528. package/dist/tools/fs/shell-read-functions.js +2 -2
  529. package/dist/tools/fs/shell-read-identity.d.ts +3 -1
  530. package/dist/tools/fs/shell-read-identity.js +4 -2
  531. package/dist/tools/fs/shell-read-judge.d.ts +7 -1
  532. package/dist/tools/fs/shell-read-judge.js +1 -1
  533. package/dist/tools/fs/shell-read-object-path.d.ts +59 -0
  534. package/dist/tools/fs/shell-read-object-path.js +119 -0
  535. package/dist/tools/fs/shell-read-plan.d.ts +8 -0
  536. package/dist/tools/fs/shell-read-plan.js +47 -30
  537. package/dist/tools/fs/shell-read-start.d.ts +66 -13
  538. package/dist/tools/fs/shell-read-start.js +89 -17
  539. package/dist/tools/fs/shell-read-workdir.d.ts +29 -8
  540. package/dist/tools/fs/shell-read-workdir.js +31 -8
  541. package/dist/tools/monitor.d.ts +8 -7
  542. package/dist/tools/monitor.js +12 -10
  543. package/dist/tools/worktree.d.ts +5 -1
  544. package/dist/tools/worktree.js +20 -17
  545. package/package.json +6 -3
  546. package/test/export-surface.snapshot.json +112 -42
  547. package/wire-changes/core-stores-sql@7.61.0.json +480 -0
  548. package/wire-changes/core-stores-sql@7.62.0.json +30 -0
  549. package/wire-changes/core@7.61.0.json +4405 -0
  550. package/wire-changes/core@7.62.0.json +2181 -0
  551. package/wire-changes/mods-kernel@7.61.0.json +65 -0
  552. package/wire-changes/mods-kernel@7.62.0.json +42 -0
  553. package/wire-changes/primitives@7.61.0.json +30 -0
  554. package/wire-changes/primitives@7.62.0.json +30 -0
  555. package/dist/core/consolidate-scope.d.ts +0 -93
  556. package/dist/core/consolidate-scope.js +0 -98
  557. package/dist/core/runner/image-removed-seat.d.ts +0 -12
  558. package/dist/core/runner/image-removed-seat.js +0 -19
  559. package/dist/core/runner/memory-consolidation.d.ts +0 -109
  560. package/dist/core/runner/memory-consolidation.js +0 -251
@@ -0,0 +1,5 @@
1
+ import type { WorkflowRun } from "../orchestration/workflow-types.js";
2
+ /** Bind `run` to the `done` promise that settles for it — the run's starter, once, before the promise is handed out. */
3
+ export declare function bindSettledRun(done: Promise<unknown>, run: WorkflowRun): void;
4
+ /** The run `done` settles for; `undefined` for a promise no run was bound to (a handle its caller assembled itself). */
5
+ export declare function settledRunOf(done: Promise<unknown>): WorkflowRun | undefined;
@@ -0,0 +1,7 @@
1
+ const runOfDone = new WeakMap();
2
+ export function bindSettledRun(done, run) {
3
+ runOfDone.set(done, run);
4
+ }
5
+ export function settledRunOf(done) {
6
+ return runOfDone.get(done);
7
+ }
@@ -1,7 +1,7 @@
1
1
  import { type FileHandle } from "node:fs/promises";
2
2
  import { type BoundFileObject, type ExecResult, type ExecutionEnv, ExecutionError, type ExecutionEnvExecOptions, FileError, type FileInfo, type Result } from "../harness/types.js";
3
3
  import { type SecretEnvFinding } from "../../core/secret-env.js";
4
- import type { EngineNotice } from "../../core/engine-notice.js";
4
+ import { type EngineNotice } from "../../core/engine-notice.js";
5
5
  import type { ExecutionEnvCapabilities, SymlinkChain } from "../harness/types.js";
6
6
  import type { BackgroundHardKillOutcome, BackgroundShellCapability, BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions } from "../../core/background-shell.js";
7
7
  import { BackgroundShellError } from "../../core/background-shell.js";
@@ -83,14 +83,22 @@ export declare function openSpoolPair(base: string): {
83
83
  export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCapability, SchedulerCapability {
84
84
  cwd: string;
85
85
  /** `ExecutionEnv.capabilities`: the engine's own host — commands are this process's children on its own disk, not
86
- * contained, not snapshotable; its resolver always answers; it does not keep the byte floor (no process confinement). */
86
+ * contained, not snapshotable; its resolver always answers; it keeps the byte floor exactly when its starts are confined
87
+ * (`readFloorConfinement: "os"` on a host where the probe applied), and otherwise does not. */
87
88
  readonly capabilities: ExecutionEnvCapabilities;
89
+ /** Every start carrying a floor runs under that floor's seatbelt profile (the probe applied at construction). */
90
+ private readonly confined;
91
+ /** Each profile's apply, once per text: `undefined` applied, else the launcher's reason. */
92
+ private readonly profileApplies;
88
93
  /** `ExecutionEnv.homeDir` = the `HOME` the shell child receives (its `~`/`$HOME`/`${HOME}` all expand to it), read LIVE off the same `shellEnv`-over-`inheritEnv` merge each exec gets; ABSENT when the
89
94
  * child gets none (an allowlist that withholds it: `~` then falls back to passwd while `$HOME` is empty — two values, no single home, home-relative operands stay fail-closed). Residual: a per-exec `env.HOME` override. */
90
95
  get homeDir(): string | undefined;
91
96
  /** `ExecutionEnv.cdPath` = the `CDPATH` the shell child receives, read LIVE off the same merge each exec gets (never the
92
97
  * engine process's own environment): its entries, `[]` when the child gets none. Residual: a per-exec `env.CDPATH`. */
93
98
  get cdPath(): readonly string[];
99
+ /** `ExecutionEnv.receivedEnvNames` = the names of the same merge each exec gets, read LIVE; `[]` when no child would be spawned
100
+ * at all. Residual: a per-exec `env` adding one. */
101
+ get receivedEnvNames(): readonly string[];
94
102
  /** `ExecutionEnv.withheldEnv` = what the same merge withholds from the shell child (an entry `shellEnv` re-supplies is
95
103
  * no loss), read LIVE; `[]` when no child would be spawned at all. Residual: a per-exec `env` re-supplying one. */
96
104
  get withheldEnv(): readonly SecretEnvFinding[];
@@ -154,6 +162,13 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
154
162
  * `code: "config.secret_env_scrubbed"`, `detail.names`); independent of `onSecretEnvScrub` (a raw
155
163
  * findings collector) except: that seat wired alone stays console-silent, as before this existed. */
156
164
  onNotice?: (notice: EngineNotice) => void;
165
+ /** Confine every start that carries a byte floor (`ExecutionEnvExecOptions.readFloor`) at the OS: `"os"` = on macOS,
166
+ * when the seatbelt base applies here (probed once, now), each such start runs under `sandbox-exec -p <the floor's
167
+ * profile>` and the environment declares `keepsReadFloor: true`; a floor the profile cannot express, or a profile that
168
+ * does not apply, refuses that start (`spawn_error` / `spawn_failed`, naming why) — it never runs unconfined. On any
169
+ * other host, or when the probe does not apply, the environment declares `false` and says so once on `onNotice`
170
+ * (`config.read_floor_confinement_unavailable`). Absent = no confinement (`false`). Any other value throws. */
171
+ readFloorConfinement?: "os";
157
172
  });
158
173
  get schedulerCapabilities(): SchedulerCapability["schedulerCapabilities"];
159
174
  schedule(intent: ScheduledIntent, ctx: SchedulerContext): Promise<Result<{
@@ -163,6 +178,10 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
163
178
  list(ctx: SchedulerContext): Promise<Result<ScheduledTaskSummary[], SchedulerError>>;
164
179
  absolutePath(path: string): Promise<Result<string, FileError>>;
165
180
  joinPath(parts: string[]): Promise<Result<string, FileError>>;
181
+ /** The program and arguments ONE shell start spawns: the shell as it is, or — on a confined environment, for a start
182
+ * carrying a floor — the shell under that floor's seatbelt profile; a floor the profile cannot express, or a profile the
183
+ * host does not apply, is the reason the start is refused (the command never runs, confined or not). */
184
+ private startOf;
166
185
  exec(command: string, options?: ExecutionEnvExecOptions): Promise<Result<ExecResult, ExecutionError>>;
167
186
  readTextFile(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
168
187
  readTextLines(path: string, options?: {
@@ -174,20 +193,29 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
174
193
  * The former single-step `writeFile` was an in-place O_TRUNC: an abort mid-write
175
194
  * (Esc during a large Write — ctx.signal reaches here directly), ENOSPC, or a crash left the target as
176
195
  * a torn prefix of the NEW content with the original unrecoverable. Post-fix contract: the target is
177
- * either fully old or fully new; `aborted` means it was never touched. Known semantic change (same as
178
- * CC): rename breaks a hard link — the other link keeps the old content. The replacement is a new inode made
179
- * by the writing process: its owner is the writer and its group follows the new-file rule, so the target's
180
- * group bits can land on another group; no fchown (KL-3120-b). */
196
+ * either fully old or fully new; `aborted` means it was never touched — the in-place fallback legs
197
+ * judge the signal once, before their first byte, so they answer `aborted` (untouched), `ok` or their own
198
+ * error, never `aborted` after a truncation. Known semantic change (same as CC): rename breaks a hard link —
199
+ * the other link keeps the old content. The replacement is a new inode made by the writing process: its owner
200
+ * is the writer and its group follows the new-file rule, so the target's group bits can land on another group;
201
+ * no fchown (KL-3120-b). */
181
202
  writeFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
182
203
  /** RB-221: the historical single-step in-place overwrite — kept for targets where
183
204
  * staging+rename would change node identity (symlink chains, non-regular files) and as the
184
- * CC-parity fallback for filesystems where the rename cannot work. NOT atomic by design. */
205
+ * CC-parity fallback for filesystems where the rename cannot work. NOT atomic by design, and
206
+ * deliberately not cancellable: the signal is judged once, here, before the first byte, and not again —
207
+ * so `aborted` never describes a target this write has truncated. */
185
208
  private writeFileInPlace;
186
209
  /** Atomic exclusive create ({@link FileSystem.writeFileExclusive}): Node `wx` flag = one
187
210
  * `open(O_CREAT|O_EXCL)` syscall — an existing file returns FileError `"already_exists"` and is left
188
211
  * untouched. The EEXIST→already_exists mapping lives HERE, on the exclusive-open step only — a parent
189
212
  * `mkdir` can also throw EEXIST (parent path component is a regular file) and that is NOT "the target
190
- * already exists" (fable review). Parent directories are created like writeFile. */
213
+ * already exists" (fable review). Parent directories are created like writeFile.
214
+ *
215
+ * The signal is judged before the first byte — at entry and after the parent `mkdir` — and is not handed to the write: the
216
+ * exclusive open creates the target itself, so a write cancelled after it would leave a new file holding a prefix of the
217
+ * content under an `aborted` answer. `aborted` therefore means no file was created; a write whose open has begun runs to its
218
+ * end and answers `ok` or its own error (the same rule as the in-place legs of {@link NodeExecutionEnv.writeFile}). */
191
219
  writeFileExclusive(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
192
220
  appendFile(path: string, content: string | Uint8Array): Promise<Result<void, FileError>>;
193
221
  fileInfo(path: string): Promise<Result<FileInfo, FileError>>;
@@ -241,7 +269,7 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
241
269
  suffix?: string;
242
270
  }): Promise<Result<string, FileError>>;
243
271
  /** design/116 detach: adopt a RUNNING foreground child as a background shell. Pre-fills the bg tails with
244
- * the output captured so far (so TaskOutput's first read has the full history), attaches fresh data/close
272
+ * the output captured so far (so the first background read has the full history), attaches fresh data/close
245
273
  * handlers, and arms the default bg timeout. Returns undefined when the live-shell limit is hit (detach
246
274
  * refused; the exec keeps running in the foreground). */
247
275
  private adoptRunningChild;
@@ -1,13 +1,15 @@
1
- import { spawn } from "node:child_process";
2
- import { randomUUID } from "node:crypto";
1
+ import { spawn, spawnSync } from "node:child_process";
2
+ import { createHash, randomUUID } from "node:crypto";
3
3
  import { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, rmSync, statSync, truncateSync, unlinkSync } from "node:fs";
4
4
  import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, stat, unlink, writeFile, } from "node:fs/promises";
5
5
  import { tmpdir } from "node:os";
6
- import { dirname, isAbsolute, join, sep } from "node:path";
6
+ import { basename, dirname, isAbsolute, join, sep } from "node:path";
7
7
  import { createInterface } from "node:readline";
8
8
  import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
9
9
  import { killProcessTree, shutdownDebug } from "./kill-tree.js";
10
10
  import { __resetSecretEnvScrubNoticeAnnouncement, announceSecretEnvScrub, hostChildEnv, hostChildEnvProblem, inheritedHostEnv } from "../../core/secret-env.js";
11
+ import { deliverEngineNotice } from "../../core/engine-notice.js";
12
+ import { confineShellStart, SANDBOX_EXEC, SEATBELT_PROBE_PROFILE } from "../../core/shell-confinement.js";
11
13
  import { physicalPathOfAsync } from "../../core/physical-path.js";
12
14
  import { posixModeBitsMeaningful } from "../../core/posix-mode-face.js";
13
15
  import { anchorAtLinkDir, walkSymlinkChain } from "./symlink-chain.js";
@@ -25,6 +27,41 @@ const NODE_ENV_CAPABILITIES = Object.freeze({
25
27
  io: true,
26
28
  keepsReadFloor: false,
27
29
  });
30
+ const NODE_ENV_CONFINED_CAPABILITIES = Object.freeze({ ...NODE_ENV_CAPABILITIES, keepsReadFloor: true });
31
+ function probeReadFloorConfinement() {
32
+ if (process.platform !== "darwin")
33
+ return { ok: false, reason: `this platform (${process.platform}) has no process confinement the engine applies — macOS only` };
34
+ try {
35
+ const r = spawnSync(SANDBOX_EXEC, ["-p", SEATBELT_PROBE_PROFILE, "/usr/bin/true"], { env: {}, stdio: ["ignore", "ignore", "pipe"], timeout: 10_000, encoding: "utf8" });
36
+ if (r.status === 0)
37
+ return { ok: true };
38
+ const said = (r.error?.message ?? r.stderr ?? "").trim().slice(0, 300);
39
+ return { ok: false, reason: `${SANDBOX_EXEC} could not apply the confinement base here (${r.status === null ? `signal ${r.signal ?? "none"}` : `exit ${r.status}`}${said !== "" ? `: ${said}` : ""})` };
40
+ }
41
+ catch (e) {
42
+ return { ok: false, reason: `${SANDBOX_EXEC} could not be run (${toError(e).message.slice(0, 300)})` };
43
+ }
44
+ }
45
+ function profileApplyFailure(profile) {
46
+ return new Promise((resolve) => {
47
+ let said = "";
48
+ let child;
49
+ try {
50
+ child = spawn(SANDBOX_EXEC, ["-p", profile, "/usr/bin/true"], { env: {}, stdio: ["ignore", "ignore", "pipe"] });
51
+ }
52
+ catch (e) {
53
+ resolve(`${SANDBOX_EXEC} could not be run: ${toError(e).message.slice(0, 300)}`);
54
+ return;
55
+ }
56
+ child.stderr?.setEncoding("utf8");
57
+ child.stderr?.on("data", (chunk) => {
58
+ if (said.length < 300)
59
+ said += chunk;
60
+ });
61
+ child.on("error", (e) => resolve(`${SANDBOX_EXEC} could not be run: ${e.message.slice(0, 300)}`));
62
+ child.on("close", (code, signal) => resolve(code === 0 ? undefined : `${code === null ? `signal ${signal ?? "none"}` : `exit ${code}`}${said.trim() !== "" ? `: ${said.trim().slice(0, 300)}` : ""}`));
63
+ });
64
+ }
28
65
  function resolvePath(cwd, path) {
29
66
  if (isAbsolute(path))
30
67
  return path;
@@ -126,6 +163,8 @@ function toFileError(error, path) {
126
163
  return new FileError("permission_denied", message, path, cause);
127
164
  case "ENOTDIR":
128
165
  return new FileError("not_directory", message, path, cause);
166
+ case "ELOOP":
167
+ return new FileError("symlink_loop", message, path, cause);
129
168
  case "EISDIR":
130
169
  return new FileError("is_directory", message, path, cause);
131
170
  case "ENAMETOOLONG":
@@ -156,6 +195,110 @@ function isFsSupportError(error) {
156
195
  return code === "EINVAL" || code === "ENOTSUP" || code === "EPERM" || code === "ENOSYS";
157
196
  }
158
197
  const RENAME_FALLBACK_CODES = new Set(["EXDEV", "EPERM", "EEXIST", "EBUSY"]);
198
+ const NAME_MAX_BYTES = 255;
199
+ const STAGING_NAME_DIGEST_HEX = 12;
200
+ const STAGING_CUT_AT_BYTES = NAME_MAX_BYTES - 3;
201
+ const STAGING_SUFFIX = /\.tmp\.(\d+)\.[0-9a-f]{12}$/;
202
+ function stagingSuffix(pid) {
203
+ return `.tmp.${pid}.${randomUUID().replace(/-/g, "").slice(0, 12)}`;
204
+ }
205
+ function stagingNameOf(name, suffix) {
206
+ const nameBytes = Buffer.byteLength(name, "utf8");
207
+ const suffixBytes = Buffer.byteLength(suffix, "utf8");
208
+ if (nameBytes + suffixBytes < STAGING_CUT_AT_BYTES || nameBytes > NAME_MAX_BYTES)
209
+ return `${name}${suffix}`;
210
+ const mark = `~${createHash("sha256").update(name, "utf8").digest("hex").slice(0, STAGING_NAME_DIGEST_HEX)}`;
211
+ const keep = NAME_MAX_BYTES - suffixBytes - Buffer.byteLength(mark, "utf8");
212
+ let kept = "";
213
+ let used = 0;
214
+ for (const char of name) {
215
+ const bytes = Buffer.byteLength(char, "utf8");
216
+ if (used + bytes > keep)
217
+ break;
218
+ kept += char;
219
+ used += bytes;
220
+ }
221
+ return `${kept}${mark}${suffix}`;
222
+ }
223
+ function stagingSiblingOf(target) {
224
+ const suffix = stagingSuffix(process.pid);
225
+ const name = basename(target);
226
+ if (!target.endsWith(name))
227
+ return `${target}${suffix}`;
228
+ return `${target.slice(0, target.length - name.length)}${stagingNameOf(name, suffix)}`;
229
+ }
230
+ function processIsGone(pid) {
231
+ if (!Number.isSafeInteger(pid) || pid < 1)
232
+ return false;
233
+ try {
234
+ process.kill(pid, 0);
235
+ return false;
236
+ }
237
+ catch (error) {
238
+ return isNodeError(error) && error.code === "ESRCH";
239
+ }
240
+ }
241
+ async function sweepDeadStaging(target) {
242
+ const name = basename(target);
243
+ if (!target.endsWith(name))
244
+ return 0;
245
+ const prefix = target.slice(0, target.length - name.length);
246
+ let entries;
247
+ try {
248
+ entries = await readdir(dirname(target));
249
+ }
250
+ catch {
251
+ return 0;
252
+ }
253
+ let swept = 0;
254
+ for (const entry of entries) {
255
+ if (entry === name)
256
+ continue;
257
+ const tail = STAGING_SUFFIX.exec(entry);
258
+ if (tail === null || entry !== stagingNameOf(name, tail[0]) || !processIsGone(Number(tail[1])))
259
+ continue;
260
+ const at = `${prefix}${entry}`;
261
+ if (SWEEPING.has(at))
262
+ continue;
263
+ SWEEPING.add(at);
264
+ try {
265
+ const st = await lstat(at);
266
+ if (!st.isFile() || st.nlink !== 1)
267
+ continue;
268
+ await unlink(at);
269
+ swept += 1;
270
+ }
271
+ catch {
272
+ }
273
+ finally {
274
+ SWEEPING.delete(at);
275
+ }
276
+ }
277
+ return swept;
278
+ }
279
+ const SWEEPING = new Set();
280
+ async function discardStaging(tmp) {
281
+ try {
282
+ await unlink(tmp);
283
+ return undefined;
284
+ }
285
+ catch (error) {
286
+ const code = isNodeError(error) ? error.code : undefined;
287
+ return code === "ENOENT" ? undefined : { path: tmp, sentence: `staging file left at ${tmp} (${code ?? "unlink failed"})` };
288
+ }
289
+ }
290
+ function withStagingResidue(result, left, onNotice) {
291
+ if (left === undefined)
292
+ return result;
293
+ if (result.ok) {
294
+ if (typeof onNotice === "function") {
295
+ deliverEngineNotice(onNotice, { code: "fs.staging_file_left", message: `${left.sentence}; the write itself succeeded`, detail: { path: left.path } });
296
+ }
297
+ return result;
298
+ }
299
+ const { code, message, path, cause } = result.error;
300
+ return err(new FileError(code, `${message}; ${left.sentence}`, path, cause instanceof Error ? cause : undefined));
301
+ }
159
302
  async function pathExists(path) {
160
303
  try {
161
304
  await access(path, constants.F_OK);
@@ -324,7 +467,9 @@ export function openSpoolPair(base) {
324
467
  }
325
468
  export class NodeExecutionEnv {
326
469
  cwd;
327
- capabilities = NODE_ENV_CAPABILITIES;
470
+ capabilities;
471
+ confined;
472
+ profileApplies = new Map();
328
473
  get homeDir() {
329
474
  return this.childEnvForRead()?.HOME;
330
475
  }
@@ -332,6 +477,9 @@ export class NodeExecutionEnv {
332
477
  const value = this.childEnvForRead()?.CDPATH;
333
478
  return value === undefined || value === "" ? [] : value.split(":");
334
479
  }
480
+ get receivedEnvNames() {
481
+ return Object.entries(this.childEnvForRead() ?? {}).flatMap(([name, value]) => (value === undefined ? [] : [name]));
482
+ }
335
483
  get withheldEnv() {
336
484
  let withheld = [];
337
485
  this.childEnvForRead((f) => (withheld = f));
@@ -358,6 +506,9 @@ export class NodeExecutionEnv {
358
506
  spoolPairs = new Set();
359
507
  backgroundCapabilities;
360
508
  constructor(options) {
509
+ if (options.readFloorConfinement !== undefined && options.readFloorConfinement !== "os") {
510
+ throw new Error(`NodeExecutionEnv: readFloorConfinement must be "os" or absent (got ${JSON.stringify(options.readFloorConfinement) ?? typeof options.readFloorConfinement}) — a confinement request that cannot be read is no request, so it refuses instead of reading as one side.`);
511
+ }
361
512
  this.cwd = options.cwd;
362
513
  this.shellPath = options.shellPath;
363
514
  this.shellEnv = options.shellEnv;
@@ -369,6 +520,16 @@ export class NodeExecutionEnv {
369
520
  this.retainBackgroundProcesses = options.retainBackgroundProcesses ?? false;
370
521
  this.onSecretEnvScrub = options.onSecretEnvScrub;
371
522
  this.onNotice = options.onNotice;
523
+ const probe = options.readFloorConfinement === "os" ? probeReadFloorConfinement() : undefined;
524
+ this.confined = probe?.ok === true;
525
+ this.capabilities = this.confined ? NODE_ENV_CONFINED_CAPABILITIES : NODE_ENV_CAPABILITIES;
526
+ if (probe !== undefined && !probe.ok) {
527
+ deliverEngineNotice(this.onNotice, {
528
+ code: "config.read_floor_confinement_unavailable",
529
+ message: `Process confinement of the byte floor was requested (readFloorConfinement: "os") and is not available: ${probe.reason}. This environment declares that it does not keep the floor (capabilities.keepsReadFloor is false), so a run with read-deny rows is announced or, under readDenyFloorRequired, refused.`,
530
+ detail: { reason: probe.reason },
531
+ });
532
+ }
372
533
  this.backgroundCapabilities = {
373
534
  supported: true,
374
535
  maxConcurrent: 8,
@@ -410,6 +571,27 @@ export class NodeExecutionEnv {
410
571
  const named = parts.map((part, i) => (i === 0 ? part : part.replace(leading, ""))).filter((part) => part !== "");
411
572
  return ok(named.length === 0 ? "." : named.reduce((at, part) => anchorAtLinkDir(at, part, sep)));
412
573
  }
574
+ async startOf(shell, command, floor) {
575
+ const start = { command: shell.shell, args: [...shell.args, command] };
576
+ if (!this.confined)
577
+ return { ok: true, ...start };
578
+ const confined = confineShellStart(start, floor);
579
+ if (!confined.ok)
580
+ return { ok: false, reason: `the read-deny row ${JSON.stringify(confined.row)} cannot be kept by this environment's process confinement (${confined.reason}) — the command was not started` };
581
+ if (confined.profile === undefined)
582
+ return { ok: true, ...confined.start };
583
+ let applies = this.profileApplies.get(confined.profile);
584
+ if (applies === undefined) {
585
+ if (this.profileApplies.size >= 16)
586
+ this.profileApplies.clear();
587
+ applies = profileApplyFailure(confined.profile);
588
+ this.profileApplies.set(confined.profile, applies);
589
+ }
590
+ const failed = await applies;
591
+ if (failed !== undefined)
592
+ return { ok: false, reason: `the read-deny table's confinement profile does not apply on this host (${failed}) — the command was not started` };
593
+ return { ok: true, ...confined.start };
594
+ }
413
595
  async exec(command, options) {
414
596
  if (options?.abortSignal?.aborted) {
415
597
  return err(new ExecutionError("aborted", "aborted"));
@@ -419,6 +601,9 @@ export class NodeExecutionEnv {
419
601
  if (!shellConfig.ok) {
420
602
  return shellConfig;
421
603
  }
604
+ const start = await this.startOf(shellConfig.value, command, options?.readFloor);
605
+ if (!start.ok)
606
+ return err(new ExecutionError("spawn_error", start.reason));
422
607
  return await new Promise((resolvePromise) => {
423
608
  const stdoutTail = new RollingTailBuffer();
424
609
  const stderrTail = new RollingTailBuffer();
@@ -517,7 +702,7 @@ export class NodeExecutionEnv {
517
702
  execSpoolFds = undefined;
518
703
  };
519
704
  try {
520
- child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
705
+ child = spawn(start.command, [...start.args], {
521
706
  cwd,
522
707
  detached: process.platform !== "win32",
523
708
  env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env, this.onSecretEnvScrub, this.onNotice),
@@ -894,10 +1079,23 @@ export class NodeExecutionEnv {
894
1079
  existingMode = st.mode & 0o7777;
895
1080
  }
896
1081
  }
897
- const tmp = `${target}.tmp.${process.pid}.${randomUUID().replace(/-/g, "").slice(0, 12)}`;
1082
+ const swept = await sweepDeadStaging(target);
1083
+ if (swept > 0 && typeof this.onNotice === "function") {
1084
+ deliverEngineNotice(this.onNotice, {
1085
+ code: "fs.staging_file_swept",
1086
+ message: `removed ${swept} staging file${swept === 1 ? "" : "s"} that a process which no longer runs left beside a file this write replaces`,
1087
+ detail: { count: swept },
1088
+ });
1089
+ }
1090
+ const afterSweepAbort = abortResult(abortSignal, resolved);
1091
+ if (afterSweepAbort)
1092
+ return afterSweepAbort;
1093
+ const tmp = stagingSiblingOf(target);
898
1094
  let tmpDurable = false;
1095
+ let created = false;
899
1096
  try {
900
1097
  const handle = await open(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), existingMode === undefined ? 0o666 : 0o600);
1098
+ created = true;
901
1099
  try {
902
1100
  await handle.writeFile(content, { signal: abortSignal });
903
1101
  if (existingMode !== undefined) {
@@ -923,17 +1121,15 @@ export class NodeExecutionEnv {
923
1121
  }
924
1122
  }
925
1123
  catch (error) {
926
- await unlink(tmp).catch(() => { });
1124
+ const left = created ? await discardStaging(tmp) : undefined;
927
1125
  if (isNodeError(error) && error.code === "EACCES" && existingMode !== undefined) {
928
- return await this.writeFileInPlace(resolved, content, abortSignal);
1126
+ return withStagingResidue(await this.writeFileInPlace(resolved, content, abortSignal), left, this.onNotice);
929
1127
  }
930
- return err(toFileError(error, resolved));
1128
+ return withStagingResidue(err(toFileError(error, resolved)), left, this.onNotice);
931
1129
  }
932
1130
  const preRenameAbort = abortResult(abortSignal, resolved);
933
- if (preRenameAbort) {
934
- await unlink(tmp).catch(() => { });
935
- return preRenameAbort;
936
- }
1131
+ if (preRenameAbort)
1132
+ return withStagingResidue(preRenameAbort, await discardStaging(tmp), this.onNotice);
937
1133
  try {
938
1134
  await rename(tmp, target);
939
1135
  return ok(undefined);
@@ -942,19 +1138,19 @@ export class NodeExecutionEnv {
942
1138
  const code = isNodeError(error) ? error.code : undefined;
943
1139
  if (tmpDurable && code !== undefined && RENAME_FALLBACK_CODES.has(code)) {
944
1140
  const inPlace = await this.writeFileInPlace(resolved, content, abortSignal);
945
- if (inPlace.ok) {
946
- await unlink(tmp).catch(() => { });
947
- return inPlace;
948
- }
1141
+ if (inPlace.ok || inPlace.error.code === "aborted")
1142
+ return withStagingResidue(inPlace, await discardStaging(tmp), this.onNotice);
949
1143
  return err(new FileError("unknown", `write to ${resolved} failed after the atomic rename was refused (${code}): ${inPlace.error.message}. The new content was preserved at ${tmp}`, resolved, inPlace.error));
950
1144
  }
951
- await unlink(tmp).catch(() => { });
952
- return err(toFileError(error, resolved));
1145
+ return withStagingResidue(err(toFileError(error, resolved)), await discardStaging(tmp), this.onNotice);
953
1146
  }
954
1147
  }
955
1148
  async writeFileInPlace(resolved, content, abortSignal) {
1149
+ const aborted = abortResult(abortSignal, resolved);
1150
+ if (aborted)
1151
+ return aborted;
956
1152
  try {
957
- await writeFile(resolved, content, { signal: abortSignal });
1153
+ await writeFile(resolved, content);
958
1154
  return ok(undefined);
959
1155
  }
960
1156
  catch (error) {
@@ -978,7 +1174,7 @@ export class NodeExecutionEnv {
978
1174
  return afterMkdirAbort;
979
1175
  }
980
1176
  try {
981
- await writeFile(resolved, content, { signal: abortSignal, flag: "wx" });
1177
+ await writeFile(resolved, content, { flag: "wx" });
982
1178
  return ok(undefined);
983
1179
  }
984
1180
  catch (error) {
@@ -1319,6 +1515,9 @@ export class NodeExecutionEnv {
1319
1515
  if (!shellConfig.ok) {
1320
1516
  return err(new BackgroundShellError("spawn_failed", shellConfig.error.message, shellConfig.error));
1321
1517
  }
1518
+ const start = await this.startOf(shellConfig.value, command, options?.readFloor);
1519
+ if (!start.ok)
1520
+ return err(new BackgroundShellError("spawn_failed", start.reason));
1322
1521
  let spool;
1323
1522
  let spoolFds;
1324
1523
  if (this.retainBackgroundProcesses || process.platform !== "win32") {
@@ -1339,7 +1538,7 @@ export class NodeExecutionEnv {
1339
1538
  }
1340
1539
  let child;
1341
1540
  try {
1342
- child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
1541
+ child = spawn(start.command, [...start.args], {
1343
1542
  cwd: options?.cwd ? resolvePath(this.cwd, options.cwd) : this.cwd,
1344
1543
  detached: process.platform !== "win32",
1345
1544
  env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env, this.onSecretEnvScrub, this.onNotice),