@sema-agent/core 7.58.0 → 7.60.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 (519) hide show
  1. package/CHANGELOG.md +1340 -0
  2. package/README.md +6 -4
  3. package/dist/agents/agent-definition.d.ts +7 -0
  4. package/dist/agents/agent-definition.js +12 -0
  5. package/dist/agents/agent-transcript-tool.d.ts +2 -1
  6. package/dist/agents/agent-transcript-tool.js +3 -1
  7. package/dist/agents/cc-peer-directory.js +8 -8
  8. package/dist/agents/child-model-seat.d.ts +4 -2
  9. package/dist/agents/child-model-seat.js +9 -4
  10. package/dist/agents/cumulative-stats.js +0 -1
  11. package/dist/agents/inherited-tool-pool.d.ts +26 -1
  12. package/dist/agents/inherited-tool-pool.js +22 -0
  13. package/dist/agents/peer-directory.d.ts +9 -0
  14. package/dist/agents/peer-directory.js +6 -2
  15. package/dist/agents/retain-ledger.d.ts +11 -1
  16. package/dist/agents/retain-ledger.js +13 -2
  17. package/dist/agents/roster-store.d.ts +1 -1
  18. package/dist/agents/roster-store.js +3 -1
  19. package/dist/agents/send-message-tool.d.ts +8 -19
  20. package/dist/agents/send-message-tool.js +32 -50
  21. package/dist/agents/subagent.d.ts +51 -17
  22. package/dist/agents/subagent.js +150 -112
  23. package/dist/agents/tool-filter.d.ts +1 -3
  24. package/dist/agents/tool-filter.js +4 -12
  25. package/dist/bench/metrics.d.ts +3 -5
  26. package/dist/bench/metrics.js +0 -1
  27. package/dist/brain/anthropic.js +161 -45
  28. package/dist/brain/degrading.js +3 -1
  29. package/dist/brain/errors.d.ts +9 -3
  30. package/dist/brain/errors.js +7 -1
  31. package/dist/brain/failover.js +2 -1
  32. package/dist/brain/open-responses.js +3 -3
  33. package/dist/brain/openai.js +103 -53
  34. package/dist/brain/provider-dialect.d.ts +11 -0
  35. package/dist/brain/provider-dialect.js +5 -2
  36. package/dist/brain/reasoning-request.js +5 -4
  37. package/dist/brain/reasoning.d.ts +19 -0
  38. package/dist/brain/reasoning.js +17 -2
  39. package/dist/brain/request-route.d.ts +4 -1
  40. package/dist/brain/request-route.js +4 -1
  41. package/dist/brain/route-adjudicator.d.ts +84 -18
  42. package/dist/brain/route-adjudicator.js +90 -22
  43. package/dist/brain/route-conformance.js +1 -1
  44. package/dist/brain/status-sink.d.ts +7 -1
  45. package/dist/brain/status-sink.js +6 -0
  46. package/dist/brain/stream-engine.js +84 -49
  47. package/dist/brain/stream-shared.d.ts +30 -0
  48. package/dist/brain/stream-shared.js +34 -1
  49. package/dist/brain/timeout.d.ts +65 -6
  50. package/dist/brain/timeout.js +111 -11
  51. package/dist/core/a2a.d.ts +15 -5
  52. package/dist/core/a2a.js +34 -19
  53. package/dist/core/account-row.d.ts +61 -0
  54. package/dist/core/account-row.js +51 -0
  55. package/dist/core/advisor-verdict.d.ts +2 -1
  56. package/dist/core/advisor-verdict.js +1 -1
  57. package/dist/core/agent-definition.d.ts +20 -0
  58. package/dist/core/allow-entry.d.ts +20 -6
  59. package/dist/core/allow-entry.js +17 -7
  60. package/dist/core/approval-object.d.ts +29 -15
  61. package/dist/core/approval-object.js +47 -19
  62. package/dist/core/artifact-host.d.ts +0 -2
  63. package/dist/core/artifact-host.js +0 -1
  64. package/dist/core/auto-compaction.js +1 -1
  65. package/dist/core/auto-mode-defaults.d.ts +8 -0
  66. package/dist/core/auto-mode-defaults.js +1 -0
  67. package/dist/core/auto-mode-rebuild.d.ts +2 -1
  68. package/dist/core/auto-mode.d.ts +39 -4
  69. package/dist/core/auto-mode.js +63 -12
  70. package/dist/core/background-agent-store.d.ts +26 -4
  71. package/dist/core/background-agent-store.js +3 -2
  72. package/dist/core/background-shell.d.ts +12 -1
  73. package/dist/core/background-shell.js +12 -0
  74. package/dist/core/checkpoint-requirements.d.ts +13 -1
  75. package/dist/core/checkpoint-requirements.js +3 -1
  76. package/dist/core/checkpoint-store.d.ts +66 -25
  77. package/dist/core/checkpoint-store.js +22 -9
  78. package/dist/core/child-clamp-seats.d.ts +29 -0
  79. package/dist/core/child-clamp-seats.js +56 -1
  80. package/dist/core/compliance.d.ts +3 -3
  81. package/dist/core/compliance.js +1 -1
  82. package/dist/core/credential-echo.d.ts +52 -0
  83. package/dist/core/credential-echo.js +65 -0
  84. package/dist/core/credential-vocabulary.d.ts +13 -3
  85. package/dist/core/credential-vocabulary.js +12 -4
  86. package/dist/core/cross-boundary-taint.d.ts +4 -5
  87. package/dist/core/effective-path-target.d.ts +8 -2
  88. package/dist/core/effective-path-target.js +8 -3
  89. package/dist/core/engine-notice.d.ts +156 -23
  90. package/dist/core/engine-notice.js +19 -5
  91. package/dist/core/frame-settlement.d.ts +5 -0
  92. package/dist/core/frame-settlement.js +4 -0
  93. package/dist/core/gate-fold.js +8 -6
  94. package/dist/core/gate-lanes.js +47 -12
  95. package/dist/core/gate-outcome.d.ts +32 -3
  96. package/dist/core/gate-outcome.js +19 -1
  97. package/dist/core/governance-codes.d.ts +17 -1
  98. package/dist/core/governance-codes.js +25 -0
  99. package/dist/core/hands-band-screen.js +0 -1
  100. package/dist/core/hands-band.d.ts +0 -3
  101. package/dist/core/hooks.d.ts +70 -59
  102. package/dist/core/hooks.js +125 -80
  103. package/dist/core/image-admission.d.ts +106 -52
  104. package/dist/core/image-admission.js +184 -56
  105. package/dist/core/image-downsample.d.ts +36 -69
  106. package/dist/core/image-downsample.js +111 -73
  107. package/dist/core/integer-option.d.ts +21 -0
  108. package/dist/core/integer-option.js +13 -0
  109. package/dist/core/locked-config.d.ts +59 -5
  110. package/dist/core/locked-config.js +82 -50
  111. package/dist/core/mailbox-store.d.ts +45 -1
  112. package/dist/core/mailbox-store.js +53 -9
  113. package/dist/core/mcp-call-meta.d.ts +2 -2
  114. package/dist/core/mcp-call-meta.js +9 -10
  115. package/dist/core/mcp-failure.d.ts +122 -20
  116. package/dist/core/mcp-failure.js +73 -5
  117. package/dist/core/mcp-host-seat.d.ts +92 -0
  118. package/dist/core/mcp-host-seat.js +131 -0
  119. package/dist/core/mcp-probe.d.ts +7 -2
  120. package/dist/core/mcp-probe.js +7 -2
  121. package/dist/core/mcp-server-link.d.ts +22 -1
  122. package/dist/core/mcp-server-link.js +25 -1
  123. package/dist/core/mcp-server-spec.d.ts +38 -9
  124. package/dist/core/mcp-server-spec.js +55 -21
  125. package/dist/core/mcp.d.ts +27 -12
  126. package/dist/core/mcp.js +105 -76
  127. package/dist/core/memory-admission.d.ts +23 -6
  128. package/dist/core/memory-admission.js +19 -9
  129. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  130. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  131. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  132. package/dist/core/memory-engine/consolidation.js +1 -0
  133. package/dist/core/memory-engine/content-origin.d.ts +13 -0
  134. package/dist/core/memory-engine/content-origin.js +21 -3
  135. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  136. package/dist/core/memory-engine/distiller.js +2 -2
  137. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  138. package/dist/core/memory-engine/dual-root.js +44 -1
  139. package/dist/core/memory-engine/engine.d.ts +67 -14
  140. package/dist/core/memory-engine/engine.js +384 -212
  141. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  142. package/dist/core/memory-engine/export-bundle.js +23 -4
  143. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  144. package/dist/core/memory-engine/file-backend.js +290 -117
  145. package/dist/core/memory-engine/index.d.ts +3 -2
  146. package/dist/core/memory-engine/index.js +2 -1
  147. package/dist/core/memory-engine/layout.d.ts +59 -11
  148. package/dist/core/memory-engine/layout.js +190 -40
  149. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  150. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  151. package/dist/core/memory-engine/scope-contract.d.ts +13 -3
  152. package/dist/core/memory-engine/scope-contract.js +2 -2
  153. package/dist/core/memory-engine/sync-client.d.ts +51 -9
  154. package/dist/core/memory-engine/sync-client.js +107 -13
  155. package/dist/core/memory-engine/sync-report.d.ts +103 -0
  156. package/dist/core/memory-engine/sync-report.js +119 -0
  157. package/dist/core/memory-engine/sync.d.ts +8 -1
  158. package/dist/core/memory-engine/types.d.ts +6 -0
  159. package/dist/core/mode-policy.d.ts +9 -1
  160. package/dist/core/mode-policy.js +11 -1
  161. package/dist/core/model-receipt.d.ts +39 -0
  162. package/dist/core/model-receipt.js +139 -0
  163. package/dist/core/mods/agent-stations.d.ts +65 -0
  164. package/dist/core/mods/agent-stations.js +105 -0
  165. package/dist/core/mods/classic-events.d.ts +5 -1
  166. package/dist/core/mods/kernel/dispatch.d.ts +5 -1
  167. package/dist/core/mods/kernel/dispatch.js +6 -5
  168. package/dist/core/mods/kernel/events.d.ts +11 -4
  169. package/dist/core/mods/kernel/events.js +11 -7
  170. package/dist/core/mods/kernel/receive.d.ts +5 -0
  171. package/dist/core/mods/kernel/receive.js +10 -0
  172. package/dist/core/mods/kernel/registration.d.ts +4 -0
  173. package/dist/core/mods/kernel/registration.js +3 -0
  174. package/dist/core/mods/lifecycle-stations.d.ts +41 -0
  175. package/dist/core/mods/lifecycle-stations.js +35 -0
  176. package/dist/core/mods/stations.d.ts +73 -60
  177. package/dist/core/mods/stations.js +64 -40
  178. package/dist/core/mods/tool-call.d.ts +10 -4
  179. package/dist/core/mods/tool-call.js +28 -12
  180. package/dist/core/mounted-mcp.d.ts +5 -0
  181. package/dist/core/mounted-mcp.js +2 -2
  182. package/dist/core/namespaced-rule-name.d.ts +7 -1
  183. package/dist/core/namespaced-rule-name.js +13 -2
  184. package/dist/core/oracle-isolation.js +1 -1
  185. package/dist/core/own-property-receipt.d.ts +3 -0
  186. package/dist/core/own-property-receipt.js +3 -0
  187. package/dist/core/parent-spec-seat.d.ts +8 -3
  188. package/dist/core/parent-spec-seat.js +2 -0
  189. package/dist/core/park-selfcheck.js +14 -8
  190. package/dist/core/peer-seat.d.ts +133 -16
  191. package/dist/core/peer-seat.js +319 -42
  192. package/dist/core/permission-rule-consent.d.ts +0 -21
  193. package/dist/core/permission-rule-consent.js +11 -6
  194. package/dist/core/permission-rule-model.d.ts +20 -2
  195. package/dist/core/permission-rule-model.js +8 -7
  196. package/dist/core/present-plan-tool.d.ts +11 -3
  197. package/dist/core/present-plan-tool.js +2 -2
  198. package/dist/core/protocol-http-auth.d.ts +14 -2
  199. package/dist/core/protocol-http-auth.js +16 -7
  200. package/dist/core/read-face-seats.d.ts +7 -5
  201. package/dist/core/read-face-seats.js +4 -1
  202. package/dist/core/redaction-marks.d.ts +4 -3
  203. package/dist/core/redaction-marks.js +2 -2
  204. package/dist/core/remote-env.d.ts +146 -98
  205. package/dist/core/remote-env.js +113 -14
  206. package/dist/core/resume-startup-cause.js +1 -0
  207. package/dist/core/retention.js +37 -12
  208. package/dist/core/retired-keys.d.ts +6 -1
  209. package/dist/core/retired-keys.js +4 -1
  210. package/dist/core/rewrite-rejudge.d.ts +13 -5
  211. package/dist/core/rewrite-rejudge.js +9 -5
  212. package/dist/core/roles.d.ts +69 -3
  213. package/dist/core/roles.js +167 -80
  214. package/dist/core/rule-owner.d.ts +3 -0
  215. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  216. package/dist/core/runner/announce-once-ledger.js +4 -2
  217. package/dist/core/runner/assemble-result.d.ts +0 -5
  218. package/dist/core/runner/assemble-result.js +0 -1
  219. package/dist/core/runner/call-hook-stations.d.ts +17 -10
  220. package/dist/core/runner/call-hook-stations.js +23 -12
  221. package/dist/core/runner/child-tree.d.ts +7 -8
  222. package/dist/core/runner/child-tree.js +6 -6
  223. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  224. package/dist/core/runner/classifier-ladder.js +39 -8
  225. package/dist/core/runner/construction-doors.js +5 -0
  226. package/dist/core/runner/contracts.d.ts +82 -57
  227. package/dist/core/runner/credential-origin-seat.js +4 -3
  228. package/dist/core/runner/cross-boundary-lane.d.ts +3 -5
  229. package/dist/core/runner/cross-boundary-lane.js +11 -2
  230. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  231. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  232. package/dist/core/runner/decide-continuation.d.ts +2 -2
  233. package/dist/core/runner/env-capability-census.d.ts +15 -20
  234. package/dist/core/runner/env-capability-census.js +25 -34
  235. package/dist/core/runner/file-history-request.d.ts +2 -2
  236. package/dist/core/runner/file-history-request.js +0 -8
  237. package/dist/core/runner/gate-exit.d.ts +87 -11
  238. package/dist/core/runner/gate-exit.js +30 -8
  239. package/dist/core/runner/git-status-frame.d.ts +5 -2
  240. package/dist/core/runner/git-status-frame.js +3 -4
  241. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  242. package/dist/core/runner/image-removed-seat.js +19 -0
  243. package/dist/core/runner/image.d.ts +7 -2
  244. package/dist/core/runner/image.js +14 -8
  245. package/dist/core/runner/inline-image.d.ts +10 -8
  246. package/dist/core/runner/inline-image.js +11 -9
  247. package/dist/core/runner/memory-consolidation-driver.js +5 -5
  248. package/dist/core/runner/park-commit.d.ts +1 -1
  249. package/dist/core/runner/park-commit.js +3 -0
  250. package/dist/core/runner/permission-rule-lanes.js +1 -1
  251. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  252. package/dist/core/runner/prepare-ask-lane.js +2 -1
  253. package/dist/core/runner/prepare-boundary-parks.d.ts +2 -2
  254. package/dist/core/runner/prepare-boundary-parks.js +5 -5
  255. package/dist/core/runner/prepare-caps-and-workflow.d.ts +7 -5
  256. package/dist/core/runner/prepare-caps-and-workflow.js +6 -3
  257. package/dist/core/runner/prepare-config-doors.d.ts +6 -1
  258. package/dist/core/runner/prepare-config-doors.js +16 -9
  259. package/dist/core/runner/prepare-context-lane.js +2 -0
  260. package/dist/core/runner/prepare-delegation-surface.d.ts +9 -3
  261. package/dist/core/runner/prepare-delegation-surface.js +5 -4
  262. package/dist/core/runner/prepare-file-history.d.ts +10 -12
  263. package/dist/core/runner/prepare-file-history.js +3 -12
  264. package/dist/core/runner/prepare-gate-stations.d.ts +4 -3
  265. package/dist/core/runner/prepare-gate-stations.js +4 -3
  266. package/dist/core/runner/prepare-hands-readface.d.ts +7 -1
  267. package/dist/core/runner/prepare-hands-readface.js +19 -6
  268. package/dist/core/runner/prepare-inherited-gate.d.ts +6 -7
  269. package/dist/core/runner/prepare-inherited-gate.js +22 -31
  270. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  271. package/dist/core/runner/prepare-memory.d.ts +2 -2
  272. package/dist/core/runner/prepare-memory.js +12 -19
  273. package/dist/core/runner/prepare-park-ask.d.ts +4 -6
  274. package/dist/core/runner/prepare-park-ask.js +5 -9
  275. package/dist/core/runner/prepare-policy-chain.d.ts +8 -7
  276. package/dist/core/runner/prepare-policy-chain.js +136 -121
  277. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  278. package/dist/core/runner/prepare-project-context.js +10 -7
  279. package/dist/core/runner/prepare-prompt-inputs.d.ts +5 -2
  280. package/dist/core/runner/prepare-prompt-inputs.js +10 -20
  281. package/dist/core/runner/prepare-protocol-tools.d.ts +5 -3
  282. package/dist/core/runner/prepare-protocol-tools.js +17 -2
  283. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  284. package/dist/core/runner/prepare-run-refs.js +4 -1
  285. package/dist/core/runner/prepare-suspend-saga.d.ts +0 -2
  286. package/dist/core/runner/prepare-suspend-saga.js +5 -7
  287. package/dist/core/runner/prepare-task.js +44 -28
  288. package/dist/core/runner/prepare-turn-wiring.d.ts +2 -0
  289. package/dist/core/runner/prepare-turn-wiring.js +7 -2
  290. package/dist/core/runner/prepare-wiring-manifest.d.ts +5 -4
  291. package/dist/core/runner/prepare-wiring-manifest.js +34 -19
  292. package/dist/core/runner/prepare-workspace-restore.js +3 -3
  293. package/dist/core/runner/reply-pricing.d.ts +30 -0
  294. package/dist/core/runner/reply-pricing.js +19 -0
  295. package/dist/core/runner/resume-admission.js +4 -2
  296. package/dist/core/runner/resume-apply.js +6 -1
  297. package/dist/core/runner/resume-checkpoint-screen.js +4 -4
  298. package/dist/core/runner/resume-policy-outcome.js +5 -5
  299. package/dist/core/runner/retired-runner-deps.js +4 -1
  300. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  301. package/dist/core/runner/role-seat-defaulted.js +40 -0
  302. package/dist/core/runner/run-attachment-seats.js +3 -3
  303. package/dist/core/runner/run-brain-sinks.js +3 -0
  304. package/dist/core/runner/run-git-lane.d.ts +3 -1
  305. package/dist/core/runner/run-git-lane.js +1 -1
  306. package/dist/core/runner/run-harness-handlers.d.ts +3 -1
  307. package/dist/core/runner/run-harness-handlers.js +3 -1
  308. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  309. package/dist/core/runner/run-identity-wiring.js +6 -5
  310. package/dist/core/runner/run-leg.d.ts +2 -0
  311. package/dist/core/runner/run-leg.js +63 -56
  312. package/dist/core/runner/run-notification-lane.d.ts +3 -1
  313. package/dist/core/runner/run-notification-lane.js +16 -10
  314. package/dist/core/runner/run-settle-and-teardown.js +5 -1
  315. package/dist/core/runner/run-stop-and-final-verify.d.ts +4 -0
  316. package/dist/core/runner/run-stop-and-final-verify.js +14 -6
  317. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  318. package/dist/core/runner/run-terminal-adoption.js +9 -3
  319. package/dist/core/runner/run-turn-boundary.js +89 -77
  320. package/dist/core/runner/runtask.d.ts +8 -5
  321. package/dist/core/runner/runtask.js +21 -13
  322. package/dist/core/runner/side-call-account.d.ts +1 -1
  323. package/dist/core/runner/side-call-account.js +3 -18
  324. package/dist/core/runner/skills-seat.js +2 -2
  325. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  326. package/dist/core/runner/sub-agent-deny-lists.js +20 -7
  327. package/dist/core/runner/synthetic-tools.js +2 -2
  328. package/dist/core/runner/tool-disclosure.js +0 -2
  329. package/dist/core/runner/tool-end-body.js +2 -2
  330. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  331. package/dist/core/runner/tool-face-overlay.js +26 -19
  332. package/dist/core/runner/tool-occurrence.d.ts +1 -1
  333. package/dist/core/runner/tool-occurrence.js +2 -2
  334. package/dist/core/runner/tool-result-media-seat.d.ts +9 -1
  335. package/dist/core/runner/tool-result-media-seat.js +17 -1
  336. package/dist/core/runner/turn-attachments.d.ts +29 -27
  337. package/dist/core/runner/turn-attachments.js +27 -42
  338. package/dist/core/runner-deps.d.ts +32 -19
  339. package/dist/core/secret-env.d.ts +35 -4
  340. package/dist/core/secret-env.js +65 -3
  341. package/dist/core/sensitive-path-policy.js +3 -3
  342. package/dist/core/session-policy-store.d.ts +12 -3
  343. package/dist/core/session-policy-store.js +29 -10
  344. package/dist/core/session-store.d.ts +5 -7
  345. package/dist/core/session-store.js +50 -11
  346. package/dist/core/side-query.d.ts +11 -1
  347. package/dist/core/side-query.js +9 -0
  348. package/dist/core/skill-grant-binding.d.ts +31 -2
  349. package/dist/core/skill-grant-binding.js +31 -1
  350. package/dist/core/skill-grant.d.ts +17 -5
  351. package/dist/core/skill-grant.js +24 -6
  352. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  353. package/dist/core/store-contracts/checkpoint-store-contract.js +3 -2
  354. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  355. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  356. package/dist/core/store-contracts/tool-result-store-contract.js +37 -0
  357. package/dist/core/stub-env.d.ts +5 -5
  358. package/dist/core/stub-env.js +11 -1
  359. package/dist/core/swappable-deps.d.ts +17 -43
  360. package/dist/core/swappable-deps.js +15 -5
  361. package/dist/core/synthetic-read-verdict.d.ts +1 -1
  362. package/dist/core/synthetic-read-verdict.js +2 -1
  363. package/dist/core/task-event.d.ts +50 -10
  364. package/dist/core/task-notification.d.ts +88 -5
  365. package/dist/core/task-notification.js +146 -17
  366. package/dist/core/task-registry-agent.d.ts +18 -12
  367. package/dist/core/task-registry-agent.js +19 -6
  368. package/dist/core/task-registry-monitor.d.ts +7 -0
  369. package/dist/core/task-registry-monitor.js +28 -1
  370. package/dist/core/task-registry-shared.d.ts +43 -3
  371. package/dist/core/task-registry-shared.js +21 -7
  372. package/dist/core/task-registry-workflow.js +1 -1
  373. package/dist/core/task-registry.d.ts +50 -35
  374. package/dist/core/task-registry.js +64 -23
  375. package/dist/core/task-result.d.ts +3 -12
  376. package/dist/core/task-spec.d.ts +15 -7
  377. package/dist/core/task-stream.d.ts +1 -1
  378. package/dist/core/terminal-cause.d.ts +10 -0
  379. package/dist/core/tool-catalog-entries.js +1 -1
  380. package/dist/core/tool-check-reading.d.ts +1 -0
  381. package/dist/core/tool-check-reading.js +3 -3
  382. package/dist/core/tool-face-reader.d.ts +7 -6
  383. package/dist/core/tool-face-reader.js +4 -3
  384. package/dist/core/tool-name-aliases.d.ts +19 -0
  385. package/dist/core/tool-name-aliases.js +54 -2
  386. package/dist/core/tool-policy.d.ts +21 -4
  387. package/dist/core/tool-policy.js +1 -1
  388. package/dist/core/tool-registry.d.ts +5 -5
  389. package/dist/core/tool-registry.js +2 -2
  390. package/dist/core/tool-result-store.d.ts +88 -5
  391. package/dist/core/tool-result-store.js +51 -12
  392. package/dist/core/tool-roster.d.ts +112 -5
  393. package/dist/core/tool-roster.js +42 -1
  394. package/dist/core/tool-spec.d.ts +23 -5
  395. package/dist/core/trace.d.ts +0 -1
  396. package/dist/core/types.d.ts +5 -5
  397. package/dist/core/types.js +2 -2
  398. package/dist/core/untrusted-text.js +1 -1
  399. package/dist/core/user-attachment.d.ts +10 -5
  400. package/dist/core/user-attachment.js +15 -7
  401. package/dist/core/wiring-manifest.d.ts +6 -3
  402. package/dist/engine/compaction/compaction.js +29 -3
  403. package/dist/engine/execution-env/node-execution-env.d.ts +11 -5
  404. package/dist/engine/execution-env/node-execution-env.js +21 -13
  405. package/dist/engine/harness/agent-harness.d.ts +26 -3
  406. package/dist/engine/harness/agent-harness.js +49 -16
  407. package/dist/engine/harness/messages.d.ts +3 -1
  408. package/dist/engine/harness/messages.js +3 -2
  409. package/dist/engine/harness/types.d.ts +119 -28
  410. package/dist/engine/llm/rejected-images.d.ts +46 -0
  411. package/dist/engine/llm/rejected-images.js +54 -0
  412. package/dist/engine/llm/tool-turns.d.ts +2 -1
  413. package/dist/engine/llm/types.d.ts +18 -7
  414. package/dist/engine/loop/agent-loop.d.ts +20 -12
  415. package/dist/engine/loop/agent-loop.js +205 -36
  416. package/dist/engine/loop/types.d.ts +12 -3
  417. package/dist/engine/lsp/node-lsp-manager.d.ts +3 -3
  418. package/dist/engine/lsp/node-lsp-manager.js +32 -13
  419. package/dist/engine/session/path-to-root.d.ts +38 -0
  420. package/dist/engine/session/path-to-root.js +39 -0
  421. package/dist/engine/session/storage-base.js +4 -21
  422. package/dist/index.d.ts +35 -21
  423. package/dist/index.js +26 -17
  424. package/dist/internal/harness-types.d.ts +1 -1
  425. package/dist/internal/harness.d.ts +1 -0
  426. package/dist/internal/llm.d.ts +1 -0
  427. package/dist/orchestration/run-workflow-tool.d.ts +9 -3
  428. package/dist/orchestration/run-workflow-tool.js +59 -29
  429. package/dist/orchestration/workflow-governance.d.ts +1 -1
  430. package/dist/orchestration/workflow-governance.js +2 -1
  431. package/dist/orchestration/workflow-observe.d.ts +17 -1
  432. package/dist/orchestration/workflow-observe.js +20 -0
  433. package/dist/orchestration/workflow-types.d.ts +32 -7
  434. package/dist/orchestration/workflow.d.ts +4 -0
  435. package/dist/orchestration/workflow.js +762 -491
  436. package/dist/prompts/default.d.ts +1 -10
  437. package/dist/prompts/default.js +0 -2
  438. package/dist/shell/counting-pass.d.ts +50 -0
  439. package/dist/shell/counting-pass.js +502 -0
  440. package/dist/shell/lex.d.ts +4 -2
  441. package/dist/shell/lex.js +93 -34
  442. package/dist/shell/shell-words.d.ts +1 -1
  443. package/dist/shell/shell-words.js +7 -6
  444. package/dist/stores/file/background-agent-store.d.ts +1 -1
  445. package/dist/stores/file/background-agent-store.js +3 -1
  446. package/dist/stores/file/checkpoint-store.d.ts +127 -2
  447. package/dist/stores/file/checkpoint-store.js +19 -14
  448. package/dist/stores/file/file-history-store.d.ts +1 -1
  449. package/dist/stores/file/file-history-store.js +3 -1
  450. package/dist/stores/file/index.d.ts +4 -3
  451. package/dist/stores/file/index.js +17 -8
  452. package/dist/stores/file/mailbox-store.d.ts +1 -1
  453. package/dist/stores/file/mailbox-store.js +9 -11
  454. package/dist/stores/file/memory-store.d.ts +1 -1
  455. package/dist/stores/file/memory-store.js +3 -1
  456. package/dist/stores/file/session-policy-store.d.ts +1 -1
  457. package/dist/stores/file/session-policy-store.js +3 -1
  458. package/dist/stores/file/session-store.d.ts +1 -1
  459. package/dist/stores/file/session-store.js +3 -1
  460. package/dist/stores/file/shared-ledger.d.ts +26 -0
  461. package/dist/stores/file/shared-ledger.js +38 -9
  462. package/dist/stores/file/tool-result-store.d.ts +20 -2
  463. package/dist/stores/file/tool-result-store.js +74 -6
  464. package/dist/stores/file/usage-window-store.d.ts +1 -1
  465. package/dist/stores/file/usage-window-store.js +3 -1
  466. package/dist/stores/file/workflow-journal-store.d.ts +1 -11
  467. package/dist/stores/file/workflow-journal-store.js +3 -2
  468. package/dist/tools/fs/containment-face.d.ts +5 -0
  469. package/dist/tools/fs/encoding.d.ts +13 -4
  470. package/dist/tools/fs/encoding.js +17 -2
  471. package/dist/tools/fs/fs-bash-background-text.d.ts +7 -0
  472. package/dist/tools/fs/fs-bash-background-text.js +1 -0
  473. package/dist/tools/fs/fs-bash.d.ts +14 -4
  474. package/dist/tools/fs/fs-bash.js +29 -35
  475. package/dist/tools/fs/fs-pdf.d.ts +2 -2
  476. package/dist/tools/fs/fs-pdf.js +26 -21
  477. package/dist/tools/fs/fs-read.d.ts +5 -4
  478. package/dist/tools/fs/fs-read.js +35 -18
  479. package/dist/tools/fs/fs-search-tools.js +4 -1
  480. package/dist/tools/fs/fs-shared.d.ts +11 -13
  481. package/dist/tools/fs/fs-shared.js +11 -7
  482. package/dist/tools/fs/fs-write.js +5 -5
  483. package/dist/tools/fs/index.d.ts +14 -8
  484. package/dist/tools/fs/index.js +13 -5
  485. package/dist/tools/fs/program-read-model.d.ts +13 -0
  486. package/dist/tools/fs/program-read-model.js +15 -0
  487. package/dist/tools/fs/program-read-model.rows.js +1 -1
  488. package/dist/tools/fs/read-deny.d.ts +13 -10
  489. package/dist/tools/fs/read-deny.js +25 -5
  490. package/dist/tools/fs/read-floor.d.ts +62 -0
  491. package/dist/tools/fs/read-floor.js +58 -0
  492. package/dist/tools/fs/removal-targets.d.ts +9 -4
  493. package/dist/tools/fs/removal-targets.js +17 -9
  494. package/dist/tools/fs/search.d.ts +3 -3
  495. package/dist/tools/fs/search.js +4 -4
  496. package/dist/tools/fs/shell-read-check.d.ts +1 -1
  497. package/dist/tools/fs/shell-read-check.js +2 -1
  498. package/dist/tools/fs/shell-read-judge.d.ts +16 -8
  499. package/dist/tools/fs/shell-read-judge.js +10 -6
  500. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  501. package/dist/tools/fs/shell-read-plan.js +22 -15
  502. package/dist/tools/fs/shell-read-start.js +1 -0
  503. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  504. package/dist/tools/fs/shell-reentry-text.js +25 -3
  505. package/dist/tools/monitor.d.ts +9 -4
  506. package/dist/tools/monitor.js +17 -8
  507. package/dist/tools/scheduler-tools.js +42 -4
  508. package/dist/tools/web.d.ts +0 -10
  509. package/dist/tools/web.js +1 -4
  510. package/package.json +5 -2
  511. package/test/export-surface.snapshot.json +161 -21
  512. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  513. package/wire-changes/core-stores-sql@7.60.0.json +30 -0
  514. package/wire-changes/core@7.59.0.json +2459 -0
  515. package/wire-changes/core@7.60.0.json +3274 -0
  516. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  517. package/wire-changes/mods-kernel@7.60.0.json +62 -0
  518. package/wire-changes/primitives@7.59.0.json +29 -0
  519. package/wire-changes/primitives@7.60.0.json +30 -0
@@ -5,8 +5,7 @@ import { decodeTextBytes, normalizeFileText } from "./encoding.js";
5
5
  import { shellQuote } from "./search.js";
6
6
  import { isNotebookPath } from "./notebook.js";
7
7
  import { homeViewsOf } from "./read-deny-home.js";
8
- import { sharpImageDownsampler } from "../../core/mcp.js";
9
- import { MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES } from "../../core/image-admission.js";
8
+ import { IMAGE_ADMISSION } from "../../core/image-admission.js";
10
9
  import { deliverEngineNotice } from "../../core/types.js";
11
10
  import { resolveEnvBudget } from "../../core/env-budget.js";
12
11
  import { openSystemReminder } from "../../core/reminder-mint.js";
@@ -38,6 +37,15 @@ export function tooLargeToEditMessage(path, bytes) {
38
37
  export function truncatedUtf16BodyMessage(tool, path) {
39
38
  return `Error (${tool}): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`;
40
39
  }
40
+ export function notUtf8BodyMessage(tool, path) {
41
+ return (`Error (${tool}): "${path}" is not valid UTF-8: it uses an older encoding such as Windows-1252, Shift-JIS or GBK, or it is binary. ` +
42
+ `These tools write UTF-8 (or UTF-16LE behind its byte-order mark) and never convert a file's encoding on their own, so nothing was written. ` +
43
+ `If the file is text, make the change with a shell command that reads and writes it in its own encoding (iconv), or ask the user whether to convert it to UTF-8 first. ` +
44
+ `To replace the whole file with new UTF-8 text anyway, delete it first, then Write it.`);
45
+ }
46
+ export function malformedBodyMessage(tool, path, why) {
47
+ return why === "truncated_utf16" ? truncatedUtf16BodyMessage(tool, path) : notUtf8BodyMessage(tool, path);
48
+ }
41
49
  export const BASH_READONLY_CONFINEMENT_NOTE = "bash_readonly is confined to the workspace roots; it has no approval path, so the call is refused rather than escalated.";
42
50
  export function persistedTextOf(encoded) {
43
51
  return decodeTextBytes(typeof encoded === "string" ? Buffer.from(encoded, "utf8") : encoded).text;
@@ -56,11 +64,7 @@ export async function notReadRefusalText(env, toolName, key, v, signal, fallback
56
64
  return `${base} ${OVERSIZE_READ_ESCAPE_HINT}`;
57
65
  return fallbackHint === undefined ? base : `${base} ${fallbackHint}`;
58
66
  }
59
- export const NO_DOWNSAMPLER_IMAGE_CAP_HINT = `Install the optional "sharp" dependency (declared in this package's optionalDependencies) to read images up to ${MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES} bytes — it downsamples them to fit the API image limit.`;
60
- let autoDownsampler;
61
- export function resolveAutoDownsampler() {
62
- return (autoDownsampler ??= sharpImageDownsampler());
63
- }
67
+ export const NO_DOWNSAMPLER_IMAGE_CAP_HINT = `Install the optional "sharp" dependency (declared in this package's optionalDependencies) to read images up to ${IMAGE_ADMISSION.hard.readBytes.withProcessor} bytes — it downsamples them to fit the API image limit.`;
64
68
  export const MAX_READ_OUTPUT_CHARS = 100_000;
65
69
  export const BASH_DEFAULT_TIMEOUT_SEC = 120;
66
70
  export const BASH_MAX_TIMEOUT_SEC = 600;
@@ -4,7 +4,7 @@ import { defineTool, errorResult } from "../../core/tools.js";
4
4
  import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, READ_REFUSED_ESCAPE_HINT, } from "./safety.js";
5
5
  import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
6
6
  import { seatForCall } from "./read-deny.js";
7
- import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, truncatedUtf16BodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, coerceWriteArguments, ipynbRedirect, countLines, applyRecordedEdit, } from "./fs-shared.js";
7
+ import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, malformedBodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, coerceWriteArguments, ipynbRedirect, countLines, applyRecordedEdit, } from "./fs-shared.js";
8
8
  import { toolFace } from "../../core/tool-catalog-entries.js";
9
9
  import { fileArgPath } from "../../core/tool-registry.js";
10
10
  import { thrownText } from "../../core/thrown-value.js";
@@ -209,7 +209,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
209
209
  return errorResult(preDecResult.message);
210
210
  const preDec = preDecResult.value;
211
211
  if (preDec.malformed)
212
- return errorResult(truncatedUtf16BodyMessage("Edit", path));
212
+ return errorResult(malformedBodyMessage("Edit", path, preDec.malformed));
213
213
  if (preDec.text.trim() !== "")
214
214
  return errorResult(`Error (Edit): Cannot create new file - file already exists.`);
215
215
  const priorRead = state.get(r.key);
@@ -255,7 +255,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
255
255
  return errorResult(decodedResult.message);
256
256
  const decoded = decodedResult.value;
257
257
  if (decoded.malformed)
258
- return errorResult(truncatedUtf16BodyMessage("Edit", path));
258
+ return errorResult(malformedBodyMessage("Edit", path, decoded.malformed));
259
259
  const original = decoded.text;
260
260
  const entry = state.get(r.key);
261
261
  const readWasTruncated = entry?.truncated === true;
@@ -383,7 +383,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
383
383
  return errorResult(`Error (Write): cannot re-read "${path}" to verify it is unchanged: ${readBin.error.message}`);
384
384
  const decodedPrev = decodeTextBytes(readBin.value);
385
385
  if (decodedPrev.malformed)
386
- return errorResult(truncatedUtf16BodyMessage("Write", path));
386
+ return errorResult(malformedBodyMessage("Write", path, decodedPrev.malformed));
387
387
  const stale = checkStale(state.get(r.key), sha256(decodedPrev.text));
388
388
  if (stale)
389
389
  return errorResult(violationText("Write", stale));
@@ -494,7 +494,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
494
494
  return errorResult(`Error (NotebookEdit): cannot read "${notebook_path}": ${readBin.error.message}`);
495
495
  const decodedNb = decodeTextBytes(readBin.value);
496
496
  if (decodedNb.malformed)
497
- return errorResult(truncatedUtf16BodyMessage("NotebookEdit", notebook_path));
497
+ return errorResult(malformedBodyMessage("NotebookEdit", notebook_path, decodedNb.malformed));
498
498
  const nbText = decodedNb.text;
499
499
  const stale = checkStale(state.get(r.key), sha256(nbText));
500
500
  if (stale)
@@ -17,7 +17,7 @@ export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-read
17
17
  import { type ReadDenyEntry } from "./read-deny.js";
18
18
  import { type ContainmentFace } from "./containment-face.js";
19
19
  export * from "./containment-face.js";
20
- import { type CwdRef, type ReadImageDownsamplerOption } from "./fs-shared.js";
20
+ import { type CwdRef } from "./fs-shared.js";
21
21
  /** Options for {@link createHandsToolkit}. */
22
22
  export interface HandsToolkitOptions {
23
23
  /** CC --add-dir parity: extra allowed containment roots (canonical). Widens file-tool containment
@@ -113,10 +113,9 @@ export interface HandsToolkitOptions {
113
113
  * console line prints verbatim (last-resort loudness). Threaded per toolkit build — never a
114
114
  * global. */
115
115
  onNotice?: (n: import("../../core/types.js").EngineNotice) => void;
116
- /** See createBashTool's taskOpts.oneShot / createTaskOutputTool's TaskToolOptions.oneShot for the
117
- * full contract: this run has no later turn for an async background notification to land in.
118
- * Threaded to both the Bash background-launch receipt and (when this band mounts TaskOutput itself,
119
- * `mountBackgroundTaskTools: true`) the TaskOutput poll receipt. Absent ⇒ the unbranched wording. */
116
+ /** See createBashTool's taskOpts.oneShot for the full contract: this run has no later turn for an async background
117
+ * notification to land in, and its ending waits for loop-type tasks only — threaded to the Bash background-launch
118
+ * receipt. Absent ⇒ the unbranched wording. */
120
119
  oneShot?: boolean;
121
120
  /** CC `Zry`/`WZi.#m` parity: see createBashTool's taskOpts field of the same name for the full
122
121
  * contract. Threaded from {@link HandsBandOptions.autoBackgroundOnTimeout} (a deployment-level
@@ -132,9 +131,10 @@ export interface HandsToolkitOptions {
132
131
  * of the same name. Runner-wired (reads the harness's own accepted-but-unserved account); absent ⇒ the
133
132
  * shell never auto-backgrounds a running command, exactly as before. */
134
133
  queuedHumanInput?: () => boolean;
135
- /** Read-image downsampler seam ({@link ReadImageDownsamplerOption}). Default undefined = auto-detect
136
- * the optional sharp dependency once per process; `false` disables it (deterministic no-sharp behavior). */
137
- readImageDownsampler?: ReadImageDownsamplerOption;
134
+ /** The run's image processor seat (`RunnerDeps.imageProcessor`), for every image this band hands the model (Read, a
135
+ * rendered PDF page, a Bash data URI): a processor; `false` = none (deterministic no-sharp behavior); undefined =
136
+ * auto-detect the optional sharp dependency once per process. */
137
+ imageProcessor?: import("../../core/image-downsample.js").ImageDownsampler | false;
138
138
  /** PDF degradation chain: the SERVING model's PDF capability profile (prepare-task derives it via
139
139
  * {@link import("./fs-pdf.js").pdfModelCapabilitiesOf}). A model without native document input gets pdftotext text extraction →
140
140
  * rendered page images (vision) → an honest placeholder, instead of a brain-level placeholder. Default
@@ -180,6 +180,12 @@ export interface HandsToolkitOptions {
180
180
  * of an inactive tier is a satisfied intent (no-op); a name matching NO table row throws at wiring
181
181
  * time (never silently ignored). Deployment seat ONLY, same clamp argument as the tiers key. */
182
182
  readDenyBuiltinExclude?: readonly string[];
183
+ /** Mirror of `RunnerDeps.readDenyFloorRequired`, for a band that compiles its OWN table (no Runner face carried):
184
+ * `true` ⇒ building the band throws `config.read_deny_floor_unkept` when that table holds a row and `env` does not
185
+ * declare it keeps the byte floor; absent / `false` ⇒ the same fact is announced once per construction through
186
+ * {@link onNotice}. A non-boolean value throws (`config.read_face_seat`). A band handed the Runner's face judges
187
+ * nothing: the Runner judged that table when it compiled it. */
188
+ readDenyFloorRequired?: boolean;
183
189
  /** The spellings of the execution environment's home a home-anchored deny row (`~/…`) is placed under
184
190
  * ({@link import("./read-deny-home.js").readDenyHomesOf}: the declared home and the account home, each with its canonical
185
191
  * spelling). Absolute path strings only — any other shape throws at wiring time, naming the seat. The Runner passes the
@@ -17,6 +17,7 @@ export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-read
17
17
  import { checkedReadDenyHomes, compileReadDeny, compileWriteDeny, readDenyBuiltinConfigOf, readDenyRowAnchor } from "./read-deny.js";
18
18
  import { withGateTimeout } from "../../core/gate-bounded-await.js";
19
19
  import { carriedReadFaceOf, carryHomeViews, homeViewsAt, placeReadDenyAtHome, placementViewsOf, readDenyPlacedLater, sayPlacementLost } from "./read-deny-home.js";
20
+ import { judgeReadFloorKept, readFloorSeat, screenReadDenyFloorRequired } from "./read-floor.js";
20
21
  import { deploymentFaceClampNotice, resolveContainmentFace } from "./containment-face.js";
21
22
  export * from "./containment-face.js";
22
23
  import {} from "./fs-shared.js";
@@ -43,6 +44,10 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
43
44
  ? undefined
44
45
  : (canonicalKey, c) => readAdmission?.(c.toolCallId, canonicalKey) === true || (bgOutput?.(canonicalKey, c) ?? false);
45
46
  const { readDeny, writeDeny, afterPlacement } = carriedFace !== undefined ? { readDeny: carriedFace.readDeny, writeDeny: carriedFace.writeDeny, afterPlacement: (tool) => tool } : bandOwnTables(env, opts);
47
+ const readFloor = readFloorSeat(readDeny);
48
+ const floorRequired = screenReadDenyFloorRequired(opts.readDenyFloorRequired, "HandsToolkitOptions.readDenyFloorRequired") === true;
49
+ if (carriedFace === undefined)
50
+ judgeReadFloorKept({ env, table: readDeny, floor: readFloor?.(undefined), required: floorRequired, onNotice: opts.onNotice });
46
51
  const readFace = resolveContainmentFace({
47
52
  kind: "read",
48
53
  depsFace: opts.readFace,
@@ -67,7 +72,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
67
72
  rootCanonical,
68
73
  ...(readCwd !== undefined ? { cwdRef: readCwd } : {}),
69
74
  ...(readFaceRoots !== undefined ? { additionalRoots: readFaceRoots } : {}),
70
- imageDownsampler: opts.readImageDownsampler,
75
+ imageProcessor: opts.imageProcessor,
71
76
  ...(opts.pdfModelCapabilities !== undefined ? { pdfCapabilities: opts.pdfModelCapabilities } : {}),
72
77
  ...(bgOutputReadExemption !== undefined ? { bgOutputReadExemption } : {}),
73
78
  ...(readDeny !== undefined ? { readDeny } : {}),
@@ -78,19 +83,21 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
78
83
  if (opts.modelFileReaderSeat !== undefined)
79
84
  opts.modelFileReaderSeat.current = reader;
80
85
  const tools = [
81
- afterPlacement(createReadFileTool(env, readFileState, rootCanonical, readCwd, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts, reader)),
86
+ afterPlacement(createReadFileTool(env, readFileState, rootCanonical, readCwd, readFaceRoots, opts.imageProcessor, opts.pdfModelCapabilities, bgOutputReadExemption, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts, reader)),
82
87
  ];
83
88
  if (handsWriteHalfMounts({ readOnly })) {
84
89
  tools.push(createEditFileTool(env, readFileState, opts.writeRoot ?? rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFaceOf, writeDeny), createWriteFileTool(env, readFileState, opts.writeRoot ?? rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFaceOf, writeDeny), createNotebookEditTool(env, readFileState, opts.writeRoot ?? rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFaceOf, writeDeny));
85
90
  }
86
91
  tools.push(afterPlacement(createGrepTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef, readAdmission)), afterPlacement(createGlobTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef, readAdmission)), afterPlacement(createRepoMapTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef, readAdmission)));
87
92
  if (includeShell) {
88
- tools.push(readOnly
93
+ tools.push(afterPlacement(readOnly
89
94
  ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), {
90
95
  ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
91
96
  ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
92
97
  ...(opts.onNotice !== undefined ? { onNotice: opts.onNotice } : {}),
93
98
  ...(opts.shellReadAdmission !== undefined ? { shellReadAdmission: opts.shellReadAdmission } : {}),
99
+ ...(readFloor !== undefined ? { readFloor } : {}),
100
+ ...(opts.imageProcessor !== undefined ? { imageProcessor: opts.imageProcessor } : {}),
94
101
  ...(opts.onToolProgress !== undefined ? { onToolProgress: opts.onToolProgress } : {}),
95
102
  })
96
103
  : createBashTool(env, rootCanonical, commitCoAuthor, cwdRef, {
@@ -107,12 +114,14 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
107
114
  ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}),
108
115
  ...(additionalRoots !== undefined ? { additionalRoots } : {}),
109
116
  ...(opts.shellReadAdmission !== undefined ? { shellReadAdmission: opts.shellReadAdmission } : {}),
117
+ ...(readFloor !== undefined ? { readFloor } : {}),
118
+ ...(opts.imageProcessor !== undefined ? { imageProcessor: opts.imageProcessor } : {}),
110
119
  ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
111
120
  ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
112
121
  ...(opts.onNotice !== undefined ? { onNotice: opts.onNotice } : {}),
113
122
  ...(opts.monitorToolActive !== undefined ? { monitorToolActive: opts.monitorToolActive } : {}),
114
123
  ...(opts.reminderMark !== undefined ? { reminderMark: opts.reminderMark } : {}),
115
- }));
124
+ })));
116
125
  if (!readOnly && mountBackgroundTaskTools && hasBackgroundShell(env)) {
117
126
  const sessionAxis = opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {};
118
127
  tools.push(opts.taskRegistry
@@ -121,7 +130,6 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
121
130
  owner: opts.taskOwner,
122
131
  scope: opts.taskScope,
123
132
  ...sessionAxis,
124
- ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}),
125
133
  notificationWired: opts.taskNotification !== undefined,
126
134
  })
127
135
  : createEnvTaskOutputTool(env), opts.taskRegistry
@@ -422,6 +422,9 @@ export interface ProgramRow {
422
422
  readonly movesBase?: "stack";
423
423
  /** A shell block word at the program position: it names no command of its own. */
424
424
  readonly syntax?: "block";
425
+ /** What it writes to its standard output, read off its operands ({@link printedText}): `words` = its operands joined
426
+ * by a space (`echo`), `format` = its one operand as a format (`printf`). */
427
+ readonly prints?: "words" | "format";
425
428
  /** Git-style subcommands: the word after the program's own options names one, and the words after it are read by
426
429
  * ITS grammar, operands and traversal ({@link subcommandOf}). */
427
430
  readonly subcommands?: Readonly<Record<string, Subcommand>>;
@@ -875,6 +878,16 @@ export declare function readProgramTextLanguage(row: ProgramRow | undefined): st
875
878
  /** The program text of an invocation of a row whose first positional is program text, under EACH implementation's
876
879
  * grammar (no text says which one runs, so a reader combines the readings). */
877
880
  export declare function programTextReadings(row: ProgramRow, args: readonly string[]): ProgramTextReading[];
881
+ /**
882
+ * The text a printer row ({@link ProgramRow.prints}) writes to its standard output, read off its argv (the program word
883
+ * excluded; `undefined` = a word whose value the command does not spell). `undefined` wherever the words do not spell the
884
+ * text: such a word, an option the row does not explain, an escape the program may interpret (a backslash: `echo -e`, an
885
+ * `echo` that reads escapes by default, every `printf` format), a format with a directive (`%`), a format behind an
886
+ * option (`printf -v NAME` writes a variable, not the output), or a row that prints nothing it is handed. What the printer
887
+ * is where the command runs (a function or an alias of its name, a trap around it)
888
+ * is not read here: the one reader of this text uses it to refuse, never to clear (`ShellReadSegment.printed`).
889
+ */
890
+ export declare function printedText(row: ProgramRow | undefined, args: readonly (string | undefined)[]): string | undefined;
878
891
  /**
879
892
  * The subcommand an argv (the program word excluded) names, and the row it is read by: the first word past the
880
893
  * program's own options, which are read EXACTLY by the row's grammar — an option the row does not declare may take the
@@ -1331,6 +1331,21 @@ function programTextUnder(g, args) {
1331
1331
  const script = supplied ? scripts.join("\n") : firstOperand;
1332
1332
  return script === undefined ? "none" : { text: script };
1333
1333
  }
1334
+ export function printedText(row, args) {
1335
+ const words = args.filter((a) => a !== undefined);
1336
+ if (row?.prints === undefined || words.length !== args.length)
1337
+ return undefined;
1338
+ const events = readArgRoles(row, words);
1339
+ const from = events.find((e) => e.kind === "operand" || e.kind === "dash-word-operand")?.at ?? words.length;
1340
+ if (events.some((e) => e.at < from && e.kind === "option" && e.reading === "speculative"))
1341
+ return undefined;
1342
+ const printed = words.slice(from);
1343
+ if (printed.some((w) => w.includes("\\")))
1344
+ return undefined;
1345
+ if (row.prints === "words")
1346
+ return printed.join(" ");
1347
+ return from === 0 && printed.length === 1 && !printed[0].includes("%") ? printed[0] : undefined;
1348
+ }
1334
1349
  function exactSpec(g, tok) {
1335
1350
  if (tok.startsWith("--"))
1336
1351
  return tok.includes("=") ? undefined : g.long[tok.slice(2)];
@@ -585,7 +585,7 @@ const git = {
585
585
  const noPath = (key, rest, extra = {}) => ({ key, grammars: [], operands: { rest }, witness: BINARY, ...extra });
586
586
  const BUILTIN_ONLY = { declared: "a shell builtin with no binary of its own on every host: its words are read by the shell" };
587
587
  const noPathRows = [
588
- noPath("pwd", LABEL, { builtin: "inert" }), noPath("echo", LABEL, { builtin: "inert", grammars: [grammar(switches("neE"), {}, { afterFirstOperand: "operands" })] }), noPath("printf", LABEL, { grammars: [grammar({ v: val(BINDS_NAME) })] }), noPath("whoami", LABEL), noPath("uname", LABEL),
588
+ noPath("pwd", LABEL, { builtin: "inert" }), noPath("echo", LABEL, { builtin: "inert", grammars: [grammar(switches("neE"), {}, { afterFirstOperand: "operands" })], prints: "words" }), noPath("printf", LABEL, { grammars: [grammar({ v: val(BINDS_NAME) })], prints: "format" }), noPath("whoami", LABEL), noPath("uname", LABEL),
589
589
  noPath("which", LABEL), noPath("basename", LABEL), noPath("dirname", LABEL),
590
590
  { key: "tr", grammars: [], operands: { rest: LABEL, stdinBelow: "always" }, witness: BINARY },
591
591
  noPath("cal", COUNT), noPath("uptime", LABEL), noPath("id", LABEL), noPath("groups", LABEL), noPath("nproc", LABEL), noPath("locale", LABEL),
@@ -12,9 +12,10 @@ import { type PathGuardFold, type PathGuardRow, type PathRowsHit, type TargetVie
12
12
  * absolute path (a path that is not absolute is not placed, and the row does not judge it).
13
13
  * String shorthand ≡ `{ pattern }`. Matching is ASCII-case-insensitive by default (a case-insensitive
14
14
  * filesystem serves `.SSH` and `.ssh` as the same directory); `caseSensitive: true` opts a single
15
- * entry out. Unicode normalization (NFC/NFD) and volume-level case semantics are NOT modeled (v1
16
- * residual, shared with the write guard; the canonical view — realpath returns the on-disk spelling —
17
- * covers half of it).
15
+ * entry out. Names are compared in canonical composition (NFC) whatever the case setting — `ü` as one code point and `u` plus a
16
+ * combining diaeresis are one name, as on a filesystem that compares names by canonical equivalence; a compatibility form
17
+ * (a ligature) is another name. Volume-level case semantics are NOT modeled (v1 residual, shared with the write guard; the
18
+ * canonical view — realpath returns the on-disk spelling — covers half of it).
18
19
  */
19
20
  export type ReadDenyEntry = string | {
20
21
  pattern: string;
@@ -422,11 +423,13 @@ export declare const READ_FACE_DEFAULT_DENY_ENTRIES: readonly ReadDenyEntry[];
422
423
  * themselves, `ß` stays `ß`). Both sides of a comparison go through it.
423
424
  */
424
425
  export declare function ignoreCaseFold(s: string): string;
425
- /** How a compiled pattern compares: `none` byte for byte; `ascii` and `unicode` through the fold of that name, both sides —
426
- * the pattern's side at compile, the segments' side by whoever tests (once per path: {@link segmentReadingsOf}). */
426
+ /** How a compiled pattern compares, both sides composed ({@link composed}), then: `none` byte for byte; `ascii` and `unicode`
427
+ * through the case fold of that name — the pattern's side at compile, the segments' side by whoever tests (once per path:
428
+ * {@link segmentReadingsOf}). */
427
429
  export type SegmentFold = "none" | "ascii" | "unicode";
428
430
  /** The function that folds a string as each fold folds — the one place that says which function that is (the pattern at compile,
429
- * a path's segments in the readings, an anchor's segments all read it, at the time they fold). */
431
+ * a path's segments in the readings, an anchor's segments all read it, at the time they fold): composition first, in every
432
+ * fold, then the fold's own case mapping. */
430
433
  export declare const SEGMENT_FOLDS: Record<SegmentFold, (s: string) => string>;
431
434
  /** One compiled segment of a pattern: `*` stands for any run of characters but a separator, every other character for itself. */
432
435
  export interface SegmentMatcher {
@@ -454,11 +457,11 @@ export interface CompiledSegmentPattern {
454
457
  unplacedHome?: true;
455
458
  }
456
459
  /**
457
- * Compile one segment-glob pattern (shared engine). `fold`:
458
- * · "none" — byte-exact segments;
460
+ * Compile one segment-glob pattern (shared engine). `fold` (every fold first composes the name, {@link composed}):
461
+ * · "none" — exact segments, case included;
459
462
  * · "ascii" — ASCII-case-insensitive (deny-set contract);
460
- * · "unicode" — the fold a RegExp `i` flag applies, {@link ignoreCaseFold} (the write guard's historical host-keyed
461
- * behavior — kept for it answer for answer; NOT used by the deny set).
463
+ * · "unicode" — the fold a RegExp `i` flag applies, {@link ignoreCaseFold}, over the composed name (the write guard's
464
+ * historical host-keyed case behavior; NOT used by the deny set).
462
465
  * The pattern is folded here, once; the segments a row is tested on are folded by whoever tests, once per path
463
466
  * ({@link segmentReadingsOf}) — never once per row per test.
464
467
  * Returns null when the pattern reduces to zero segments — the CALLER owns its loud path (the two
@@ -337,16 +337,35 @@ export function ignoreCaseFold(s) {
337
337
  }
338
338
  return out;
339
339
  }
340
- export const SEGMENT_FOLDS = { none: (s) => s, ascii: asciiLower, unicode: ignoreCaseFold };
340
+ function composed(s) {
341
+ return /[^\x00-\x7f]/.test(s) ? s.normalize("NFC") : s;
342
+ }
343
+ export const SEGMENT_FOLDS = {
344
+ none: composed,
345
+ ascii: (s) => asciiLower(composed(s)),
346
+ unicode: (s) => ignoreCaseFold(composed(s)),
347
+ };
341
348
  function foldSegments(fold, segs) {
342
349
  return segs.map((s) => SEGMENT_FOLDS[fold](s));
343
350
  }
351
+ const SPELLED_FOLDS = { none: (s) => s, ascii: asciiLower, unicode: ignoreCaseFold };
352
+ function readingsOfViews(fold, views) {
353
+ const out = [];
354
+ for (const segs of views) {
355
+ const twin = foldSegments(fold, segs);
356
+ out.push(twin);
357
+ const spelled = segs.map((s) => SPELLED_FOLDS[fold](s));
358
+ if (spelled.some((s, i) => s !== twin[i]))
359
+ out.push(spelled);
360
+ }
361
+ return out;
362
+ }
344
363
  function foldedViewsOf(views) {
345
364
  const memo = new Map();
346
365
  return (fold) => {
347
366
  let folded = memo.get(fold);
348
367
  if (folded === undefined)
349
- memo.set(fold, (folded = fold === "none" ? views : views.map((segs) => foldSegments(fold, segs))));
368
+ memo.set(fold, (folded = readingsOfViews(fold, views)));
350
369
  return folded;
351
370
  };
352
371
  }
@@ -376,12 +395,13 @@ function segmentReadingsOf(path, aliasResolved) {
376
395
  const known = SEGMENT_READINGS.get(key);
377
396
  if (known !== undefined)
378
397
  return known;
379
- const views = segmentViewsOf(path, aliasResolved ? { aliasResolved } : undefined);
398
+ const spelledViews = segmentViewsOf(path, aliasResolved ? { aliasResolved } : undefined);
399
+ const views = readingsOfViews("none", spelledViews);
380
400
  let folded;
381
401
  const readings = {
382
402
  views,
383
- lowered: views.map((v) => foldSegments("ascii", v)),
384
- folded: () => (folded ??= views.map((v) => foldSegments("unicode", v))),
403
+ lowered: readingsOfViews("ascii", spelledViews),
404
+ folded: () => (folded ??= readingsOfViews("unicode", spelledViews)),
385
405
  rooted: isAbsoluteForFamily("own", path),
386
406
  };
387
407
  if (SEGMENT_READINGS.size >= 512)
@@ -0,0 +1,62 @@
1
+ /**
2
+ * The byte floor's one adapter: the read-deny table a call judges with, as the {@link ReadFloor} its command
3
+ * start carries to the environment the command runs in.
4
+ *
5
+ * One table, two readers. The shell read station judges what a command NAMES (its operands, its expansions, a
6
+ * recursive read's root — never the tree below a root, the zero-friction reading); the environment judges what a process
7
+ * OPENS. Both read the same rows through the same judgment: this module derives nothing — the rows are the ones the
8
+ * engine's refusals cite (`readDenySeat`) and the judgment is the table's own `matchPath`, read off the table the call
9
+ * is pinned to (`seatForCall`). A floor never loosens the station: what the station refuses never starts.
10
+ *
11
+ * Whether the environment KEEPS the floor is its declaration (`capabilities.keepsReadFloor`), judged once per table
12
+ * owner by {@link judgeReadFloorKept}: a non-empty table on an environment that does not keep it is announced, or
13
+ * refused when the deployment requires the floor.
14
+ */
15
+ import type { ExecutionEnv, ReadFloor } from "../../internal/harness-types.js";
16
+ import { type EngineNotice } from "../../core/engine-notice.js";
17
+ import { type ReadDenyMatcher } from "./read-deny.js";
18
+ /** The floor ONE call's command start carries, read off the table that call judges with — `undefined` when the table
19
+ * holds no row (an empty table keeps nothing, and the start then carries no floor: the options are the ones a start
20
+ * took before the floor existed). */
21
+ export type ReadFloorSeat = (toolCallId: string | undefined) => ReadFloor | undefined;
22
+ /** The seat over a face's deny table (the run's, or a library-direct band's own); `undefined` for no table. Built once per
23
+ * mount; each call reads its own pinned table through it. */
24
+ export declare function readFloorSeat(table: ReadDenyMatcher | undefined): ReadFloorSeat | undefined;
25
+ /** The value gate of the floor requirement (`RunnerDeps.readDenyFloorRequired`, mirrored on `HandsToolkitOptions`), the one
26
+ * gate of every door that admits it: a boolean, or absent (`undefined`, read as "not required"); anything else refuses
27
+ * (`config.read_face_seat`), because a requirement that cannot be read is no requirement and must not read as one side. */
28
+ export declare function screenReadDenyFloorRequired(value: unknown, seat: string): boolean | undefined;
29
+ /** The code a non-empty read-deny table on an environment that does not keep the byte floor carries: the operator's notice,
30
+ * and the prepare refusal when the deployment requires the floor — one fact, one word, two loudness dialects. */
31
+ export declare const READ_DENY_FLOOR_UNKEPT = "config.read_deny_floor_unkept";
32
+ /** What {@link judgeReadFloorKept} is handed: the table's owner states the environment, its table, the floor its own engine
33
+ * starts carry off that table (the base table's), and whether the deployment requires the floor. */
34
+ export interface ReadFloorJudgment {
35
+ readonly env: Pick<ExecutionEnv, "capabilities">;
36
+ readonly table: ReadDenyMatcher | undefined;
37
+ readonly floor: ReadFloor | undefined;
38
+ readonly required: boolean;
39
+ readonly onNotice: ((notice: EngineNotice) => void) | undefined;
40
+ /** The run the judgment is for, carried on the notice (a library-direct band has none). */
41
+ readonly attribution?: {
42
+ readonly sessionId?: string;
43
+ readonly runId?: string;
44
+ };
45
+ /** The owner's once-latch when it judges more than one table (a run: every table it compiles): the notice is said the
46
+ * first time and never again for that owner; a refusal is never latched. Absent ⇒ every judgment may say it. */
47
+ readonly said?: {
48
+ done: boolean;
49
+ };
50
+ }
51
+ /**
52
+ * The ONE judgment of whether a table owner's byte floor is kept, taken where the table is compiled: the Runner's prepare
53
+ * for a run (each delegated child on its own environment), a library-direct hand band for the table it compiles itself —
54
+ * never a band handed the Runner's face. Judged on the table's AUTHORITATIVE row count, the rows its refusals cite:
55
+ * · no row ⇒ nothing to keep, no judgment;
56
+ * · rows, and no floor for the owner's engine starts to carry ⇒ an engine defect, refused loudly (the starts would run with
57
+ * fewer rows than the table holds);
58
+ * · rows, on an environment that declares it keeps the floor ⇒ nothing to say;
59
+ * · rows, on one that does not: `required` ⇒ refused with {@link READ_DENY_FLOOR_UNKEPT}; otherwise that word once, to the
60
+ * operator — a recursive read under a root still reads the rows below it there, so the notice is no protection.
61
+ */
62
+ export declare function judgeReadFloorKept(j: ReadFloorJudgment): void;
@@ -0,0 +1,58 @@
1
+ import { deliverEngineNotice } from "../../core/engine-notice.js";
2
+ import { keepsReadFloor } from "../../core/remote-env.js";
3
+ import { readDenySeat, seatForCall } from "./read-deny.js";
4
+ import { isAbsoluteForFamily } from "./safety.js";
5
+ export function readFloorSeat(table) {
6
+ if (table === undefined)
7
+ return undefined;
8
+ return (toolCallId) => readFloorOf(seatForCall(table, toolCallId));
9
+ }
10
+ function readFloorOf(table) {
11
+ const rows = Object.freeze([...readDenySeat(table).denyEntries]);
12
+ if (rows.length === 0)
13
+ return undefined;
14
+ const denies = (absolutePath) => {
15
+ if (typeof absolutePath !== "string" || !isAbsoluteForFamily("own", absolutePath))
16
+ return rows[0];
17
+ try {
18
+ return table.matchPath(absolutePath)?.pattern ?? null;
19
+ }
20
+ catch {
21
+ return rows[0];
22
+ }
23
+ };
24
+ return Object.freeze({ rows, denies });
25
+ }
26
+ export function screenReadDenyFloorRequired(value, seat) {
27
+ if (value === undefined || typeof value === "boolean")
28
+ return value;
29
+ const e = new Error(`${seat} must be a boolean or absent (got ${value === null ? "null" : typeof value}) — a requirement that cannot be read is no requirement, so it refuses loudly instead of reading as one side.`);
30
+ e.code = "config.read_face_seat";
31
+ throw e;
32
+ }
33
+ export const READ_DENY_FLOOR_UNKEPT = "config.read_deny_floor_unkept";
34
+ export function judgeReadFloorKept(j) {
35
+ const rowCount = j.table === undefined ? 0 : readDenySeat(j.table).denyEntries.length;
36
+ if (rowCount === 0)
37
+ return;
38
+ if (j.floor === undefined || j.floor.rows.length !== rowCount) {
39
+ throw new Error(`the read-deny table holds ${rowCount} row(s) but the floor its engine starts would carry holds ${j.floor?.rows.length ?? 0} — refused rather than start commands with fewer rows than the table refuses (an engine defect).`);
40
+ }
41
+ if (keepsReadFloor(j.env))
42
+ return;
43
+ if (j.required) {
44
+ const e = new Error(`The run's read-deny table holds ${rowCount} row(s), and the execution environment does not declare that it keeps the byte floor (capabilities.keepsReadFloor is not true), while the deployment requires the floor (readDenyFloorRequired) — refused before any command starts. Run it on an environment that keeps the floor, or unset the requirement.`);
45
+ e.code = READ_DENY_FLOOR_UNKEPT;
46
+ throw e;
47
+ }
48
+ if (j.said !== undefined) {
49
+ if (j.said.done)
50
+ return;
51
+ j.said.done = true;
52
+ }
53
+ deliverEngineNotice(j.onNotice, {
54
+ code: READ_DENY_FLOOR_UNKEPT,
55
+ message: `The run's read-deny table holds ${rowCount} row(s), and the execution environment does not declare that it keeps the byte floor (capabilities.keepsReadFloor is not true): the engine refuses what a command names, but a recursive read under a root reads the files below it on this environment, deny rows included, and their bytes reach the conversation. To refuse such runs instead, set readDenyFloorRequired.`,
56
+ detail: { rowCount, ...(j.attribution?.sessionId !== undefined ? { sessionId: j.attribution.sessionId } : {}), ...(j.attribution?.runId !== undefined ? { runId: j.attribution.runId } : {}) },
57
+ });
58
+ }
@@ -7,7 +7,7 @@ import type { ToolCallRequest } from "../../core/tool-policy.js";
7
7
  export declare const SHELL_REMOVAL_COMMANDS: readonly ["rm", "rmdir"];
8
8
  export type ShellRemovalCommand = (typeof SHELL_REMOVAL_COMMANDS)[number];
9
9
  /** What makes a removal target dangerous, in the order a card names it. */
10
- export type DangerousRemovalKind = "filesystem_root" | "home" | "workspace" | "top_level";
10
+ export type DangerousRemovalKind = "filesystem_root" | "home" | "workspace" | "top_level" | "mounted_drive";
11
11
  /** The protected locations a removal is judged against. `homes`: the environment's declared home and every other spelling
12
12
  * of it (its canonical one); `workspace`: the task root, the working directory, the additional working directories. */
13
13
  export interface RemovalSeat {
@@ -26,9 +26,14 @@ export interface DangerousRemoval {
26
26
  * implementation's set — the filesystem root (a drive root, a UNC share root), a home directory
27
27
  * (every spelling the seat holds), a workspace directory or any of its ANCESTORS (the task root, the working directory, an
28
28
  * additional working directory — whether the home lies inside the task root or the task root inside the home), a top-level
29
- * directory (one segment below the root). `undefined` for a relative path or any other target.
29
+ * directory (one segment below the root) — and, for an `rm` that walks what it removes (`rm`: present; `recursive`: it
30
+ * selects a recursive option; or the path names every entry of a directory), a mounted drive ({@link MOUNTED_DRIVE_KEY}):
31
+ * the folder that holds drives, a drive, or an entry at a drive's top level. `undefined` for a relative path or any other
32
+ * target.
30
33
  */
31
- export declare function dangerousRemovalOf(path: string, seat: RemovalSeat): DangerousRemovalKind | undefined;
34
+ export declare function dangerousRemovalOf(path: string, seat: RemovalSeat, rm?: {
35
+ readonly recursive: boolean;
36
+ }): DangerousRemovalKind | undefined;
32
37
  /** What one removal finding asks: a protected location (`dangerous_delete`; `untrackedFrom` — the segment the working
33
38
  * directory stops being tracked at, where the target is relative and was judged where the text stood then); a recursive
34
39
  * forced removal whose target the
@@ -68,7 +73,7 @@ export declare const KNOWN_SAFE_ROOTS: readonly string[];
68
73
  * OPERANDS (every write target that is not one of its option words: a word some implementation's reading of the
69
74
  * program's row writes, {@link writeReadings}) as the plan established it on the WRITE face (the entry the program
70
75
  * unlinks, and the deny-floor shadow of a home word the plan did not place) is judged by {@link dangerousRemovalOf},
71
- * save one the program refuses by its own first step ({@link refusedByRemoval}: `.`, `..`). In a recursive forced removal ({@link recursiveForce}), an operand
76
+ * save one the program refuses by its own first step ({@link refusedByRemoval}: `.`, `..`). In a recursive forced removal ({@link selectsOptions}), an operand
72
77
  * the shell rewrites from a value the plan's table does not settle — a name with no value here or one set in a form the
73
78
  * table cannot read, a substitution, a parameter operator, a positional parameter — is an unverifiable target, save a
74
79
  * literal path below a known-safe root the shell still provides there ({@link belowKnownSafeRoot}); so are the operands
@@ -24,11 +24,14 @@ function removalKey(path) {
24
24
  function driveOf(path, key) {
25
25
  return isWinFormPath(path) && key.length >= 2 && key[1] === ":" ? key.slice(0, 2) : "";
26
26
  }
27
- export function dangerousRemovalOf(path, seat) {
27
+ const MOUNTED_DRIVE_KEY = /^\/(?:system\/)?volumes(?:\/[^/]+){0,2}$|^\/mnt\/(?:[^/]+|[a-z]\/[^/]+)$|^\/(?:run\/)?media(?:\/[^/]+){0,3}$/;
28
+ const NAMES_EVERY_ENTRY = /(?:[\\/]+\*+)+[\\/]*$/;
29
+ export function dangerousRemovalOf(path, seat, rm) {
28
30
  if (!isAbsoluteForFamily("own", path))
29
31
  return undefined;
30
32
  const k = removalKey(path);
31
- const rest = k.slice(driveOf(path, k).length);
33
+ const drive = driveOf(path, k);
34
+ const rest = k.slice(drive.length);
32
35
  if (rest === "/" || /^\/\/[^/]+\/[^/]+$/.test(k))
33
36
  return "filesystem_root";
34
37
  if (seat.homes.some((h) => isAbsoluteForFamily("own", h) && removalKey(h) === k))
@@ -38,6 +41,8 @@ export function dangerousRemovalOf(path, seat) {
38
41
  return "workspace";
39
42
  if (/^\/[^/]+$/.test(rest))
40
43
  return "top_level";
44
+ if (rm !== undefined && (rm.recursive || NAMES_EVERY_ENTRY.test(path)) && drive === "" && !k.startsWith("//") && MOUNTED_DRIVE_KEY.test(rest))
45
+ return "mounted_drive";
41
46
  return undefined;
42
47
  }
43
48
  function tildeNamesAHome(spelled) {
@@ -47,10 +52,10 @@ function tildeNamesAHome(spelled) {
47
52
  const key = removalKey(`/~home${m[2] ?? ""}`);
48
53
  return key === "/~home" || !key.startsWith("/~home/");
49
54
  }
50
- function removalKindOf(read, seat) {
55
+ function removalKindOf(read, seat, rm) {
51
56
  const floors = read.established === "unestablishable" && read.candidate.bases === "unmodelled" ? read.spellings : [];
52
57
  for (const view of [read.target, read.origin, ...floors]) {
53
- const kind = view === undefined ? undefined : dangerousRemovalOf(view, seat);
58
+ const kind = view === undefined ? undefined : dangerousRemovalOf(view, seat, rm);
54
59
  if (kind !== undefined)
55
60
  return kind;
56
61
  }
@@ -76,11 +81,12 @@ function optionsReceived(row, args) {
76
81
  const shellChooses = chosenAt >= 0 && writeReadings(row, present.slice(0, chosenAt + 1).map((w) => w.spelled)).some((r) => r.written.length === 0);
77
82
  return { refused: rowRefusesArgv(row, asWritten), shellChooses };
78
83
  }
79
- function recursiveForce(row, args, shellChooses) {
84
+ const TRAVERSAL = (o) => o.selects === "traversal";
85
+ const FORCED = (o) => o.mode === "forced";
86
+ function selectsOptions(row, args, shellChooses, ...wanted) {
80
87
  return implementationsOf(row).some((view) => {
81
88
  const selected = selectedOptions(view, args, "one-implementation");
82
- const selects = (has) => selected.some(has) || (shellChooses && declaresOption(view, has));
83
- return selects((o) => o.selects === "traversal") && selects((o) => o.mode === "forced");
89
+ return wanted.every((has) => selected.some(has) || (shellChooses && declaresOption(view, has)));
84
90
  });
85
91
  }
86
92
  export function removalFindingsOf(established, seat, safeRoots = KNOWN_SAFE_ROOTS, enclosingRelocated = false) {
@@ -98,7 +104,8 @@ export function removalFindingsOf(established, seat, safeRoots = KNOWN_SAFE_ROOT
98
104
  const { row, named } = removal;
99
105
  const removed = new Set(writeReadings(row, spelled).flatMap((r) => r.written.map((w) => w.at)));
100
106
  const options = new Set(args.filter((_, at) => !removed.has(at)).map((w) => w.raw));
101
- const forced = recursiveForce(row, spelled, received.shellChooses);
107
+ const forced = selectsOptions(row, spelled, received.shellChooses, TRAVERSAL, FORCED);
108
+ const rm = removal.program === "rm" || !named ? { recursive: selectsOptions(row, spelled, received.shellChooses, TRAVERSAL) } : undefined;
102
109
  if (forced && segment.reentry === "argv")
103
110
  out.push({ guard: "unverifiable_delete", program: removal.program, operand: segment.text.trim(), source: "stream" });
104
111
  const relocated = enclosingRelocated || readProgramPosition(segment.argv).launcherMovesBase;
@@ -107,7 +114,7 @@ export function removalFindingsOf(established, seat, safeRoots = KNOWN_SAFE_ROOT
107
114
  continue;
108
115
  if (refusedByRemoval(read))
109
116
  continue;
110
- const kind = removalKindOf(read, seat);
117
+ const kind = removalKindOf(read, seat, rm);
111
118
  if (kind !== undefined) {
112
119
  const untracked = read.candidate.bases === "unmodelled" ? established.plan.segments.find((s) => s.bases === "unmodelled")?.text.trim() : undefined;
113
120
  out.push({ guard: "dangerous_delete", kind, program: removal.program, operand: read.candidate.raw, target: read.target ?? read.candidate.floorSpelled ?? read.candidate.spelled, ...(untracked !== undefined ? { untrackedFrom: untracked } : {}) });
@@ -191,6 +198,7 @@ const DANGEROUS_REMOVAL_SENTENCE = {
191
198
  home: (p, t) => `\`${p}\` would remove a home directory (${t})`,
192
199
  workspace: (p, t) => `\`${p}\` would remove a workspace directory — the task root, the working directory or an additional working directory — or one of its ancestors (${t})`,
193
200
  top_level: (p, t) => `\`${p}\` would remove a top-level system directory (${t})`,
201
+ mounted_drive: (p, t) => `\`${p}\` would remove a mounted drive, the folder that holds mounted drives, or a file or folder at the top level of a drive (${t}) — if you meant something deeper inside, name it by its full path`,
194
202
  };
195
203
  const UNVERIFIABLE_REMOVAL_SENTENCE = {
196
204
  rewritten: (p, o) => `\`${p}\` recursive+force target ${o} is rewritten by the shell from a value this command does not settle (a name with no value here or one it sets in a form the guard cannot read, a substitution, a parameter operator) — the deleted path cannot be verified from this command`,