@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
@@ -1,8 +1,10 @@
1
1
  import { type AgentTool, type ExecutionEnv } from "../../internal/harness.js";
2
2
  import { type TaskRegistry } from "../../core/task-registry.js";
3
+ import { type ImageDownsampler } from "../../core/image-downsample.js";
3
4
  import { type CwdRef } from "./fs-shared.js";
4
5
  import type { ReversibilityVerdict } from "../../core/types.js";
5
6
  import type { ShellReadAdmission } from "./shell-read-check.js";
7
+ import type { ReadFloorSeat } from "./read-floor.js";
6
8
  /**
7
9
  * The full shell face's SHAPE classifier for the `bash` tool, exposed as a `ToolSpec.reversibilityProbe`
8
10
  * (the "maybe" tier's probe, installed on every full shell). A command is reversible ONLY if every connected
@@ -121,10 +123,9 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
121
123
  /**
122
124
  * Mirrors {@link import("../../core/types.js").TaskSpec.oneShot}: this run has no later
123
125
  * turn for an async background notification to land in (a headless `-p` process exits once the
124
- * turn ends). Branches the background-launch receipt's guidance toward an active block-wait
125
- * instruction instead of "you will be notified — do not poll", the same failure form
126
- * `run_workflow`'s launch note was fixed for (a model that follows "end your turn" advice in a
127
- * one-shot process loses the result — the process exits with nothing left alive to receive it).
126
+ * turn ends), and its ending waits for loop-type background tasks only — never for a command's
127
+ * process. Branches the background-launch receipt to {@link ONE_SHOT_BACKGROUND_COMMAND_NOTE}
128
+ * instead of "you will be notified — do not poll".
128
129
  */
129
130
  oneShot?: boolean;
130
131
  /**
@@ -144,6 +145,11 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
144
145
  * nothing is re-established, and the full shell runs unconfined as it always did.
145
146
  */
146
147
  shellReadAdmission?: ShellReadAdmission;
148
+ /** The byte floor's seat (read-floor.ts): every command this leg starts, foreground or background, carries the
149
+ * read-deny table its call judges with to the environment. Absent ⇒ no table, the starts carry nothing. */
150
+ readFloor?: ReadFloorSeat;
151
+ /** The run's image processor seat (`RunnerDeps.imageProcessor`), for an image-data-URI stdout. */
152
+ imageProcessor?: ImageDownsampler | false;
147
153
  /** Override of the `timeout` parameter's DEFAULT budget, in ms — see
148
154
  * {@link import("./index.js").HandsToolkitOptions.bashDefaultTimeoutMs} for the resolution
149
155
  * contract (options over env over constant; invalid values discarded). */
@@ -201,6 +207,10 @@ export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical:
201
207
  * containment IS the station, and a consumer mounting it without one must run `runToolGate` with the
202
208
  * station's `shellReadCheck` (the Runner does). */
203
209
  shellReadAdmission?: ShellReadAdmission;
210
+ /** The byte floor's seat — the SAME one the full shell leg takes (read-floor.ts). */
211
+ readFloor?: ReadFloorSeat;
212
+ /** The image processor seat — the SAME one the full shell leg takes. */
213
+ imageProcessor?: ImageDownsampler | false;
204
214
  /** The run's tool-progress sink — the SAME seat the full shell leg takes, for the same reason its
205
215
  * two neighbours above are shared: both foreground legs run through `runShell`, so a long command
206
216
  * must breathe on both or a person watching one of them is told nothing. This face has no detach
@@ -6,15 +6,16 @@ import { defaultTaskRegistry } from "../../core/task-registry.js";
6
6
  import { accountDroppedBytes, spoolDropNote } from "../../core/task-registry-shared.js";
7
7
  import { RollingTailBuffer } from "../../core/exec-output-tail.js";
8
8
  import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, ENV_DIRECT_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "../../core/task-tool-shape.js";
9
- import { envDeclaresRetain, hasBackgroundShell, retainsBackgroundProcesses } from "../../core/background-shell.js";
9
+ import { createBackgroundOutputFile, envDeclaresRetain, hasBackgroundShell, retainsBackgroundProcesses } from "../../core/background-shell.js";
10
10
  import { delimitUntrusted } from "../../core/untrusted-text.js";
11
- import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
11
+ import { resolveImageProcessor } from "../../core/image-downsample.js";
12
12
  import { withinAnyRoot } from "./safety.js";
13
- import { imageMagicMatches } from "../../core/image-admission.js";
13
+ import { admitImageBytes, sniffImageMime } from "../../core/image-admission.js";
14
14
  import { isDeadCwd, diagnoseDeadCwd } from "./dead-cwd.js";
15
15
  import { boundaryIsTheSandbox, hasDestroy, isIsolated } from "../../core/remote-env.js";
16
16
  import { ghRateLimitHint } from "./gh-rate-limit.js";
17
- import { backgroundLifetimeNote } from "./fs-bash-background-text.js";
17
+ import { backgroundLifetimeNote, ONE_SHOT_BACKGROUND_COMMAND_NOTE } from "./fs-bash-background-text.js";
18
+ import { resolveCompletionSink } from "../../core/task-notification.js";
18
19
  import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, CWD_SENTINEL, stripCwdSentinel, } from "./fs-shared.js";
19
20
  import { bashClassifyDefaultAllow, BASH_READONLY_DEFAULT_ALLOW, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed, parseLeadingCommandName } from "./bash-readonly-classifier.js";
20
21
  import { readOnlyShellVerdict } from "../../core/read-only-shell.js";
@@ -92,20 +93,17 @@ export function bashExitOneInterpretation(command) {
92
93
  }
93
94
  return EXIT1_INTERPRETATION[name];
94
95
  }
95
- function dataUriImageFromStdout(stdout) {
96
+ async function dataUriImageFromStdout(stdout, imageProcessor) {
96
97
  const t = stdout.trim();
97
98
  const m = /^data:image\/[a-z0-9.+_-]+;base64,([A-Za-z0-9+/=\s]+)$/i.exec(t);
98
99
  if (!m)
99
100
  return undefined;
100
- const data = m[1].replace(/\s/g, "");
101
- if (data.length === 0 || data.length > MCP_IMAGE_MAX_BASE64)
101
+ const bytes = Buffer.from(m[1].replace(/\s/g, ""), "base64");
102
+ const mime = sniffImageMime(bytes);
103
+ if (mime === undefined)
102
104
  return undefined;
103
- const bytes = Buffer.from(data, "base64");
104
- for (const mime of ["image/png", "image/jpeg", "image/gif", "image/webp"]) {
105
- if (imageMagicMatches(bytes, mime))
106
- return { data, mime };
107
- }
108
- return undefined;
105
+ const admitted = await admitImageBytes(bytes, mime, await resolveImageProcessor(imageProcessor));
106
+ return admitted.ok ? admitted.block : undefined;
109
107
  }
110
108
  const AUTO_BACKGROUND_BLOCKED_FIRST_WORDS = new Set(["sleep"]);
111
109
  function pastAutoBackgroundWrapperPrefixes(words) {
@@ -292,7 +290,7 @@ function startLivenessTicks(onTick, filterStderr) {
292
290
  stop: () => clearInterval(timer),
293
291
  };
294
292
  }
295
- async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, cwdRef, detach, readOnly, containmentRoots, onTick) {
293
+ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, cwdRef, detach, readOnly, containmentRoots, onTick, readFloor, imageProcessor) {
296
294
  const requestedSec = Math.max(1, Math.floor(timeoutSec ?? caps.defaultSec));
297
295
  let timeout = Math.min(caps.maxSec, requestedSec);
298
296
  const cappedByMaxTimeout = requestedSec > caps.maxSec;
@@ -311,6 +309,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
311
309
  abortSignal: signal,
312
310
  ...execEnv,
313
311
  ...(live !== undefined ? { onStdout: live.onStdout, onStderr: live.onStderr } : {}),
312
+ ...(readFloor !== undefined ? { readFloor } : {}),
314
313
  ...(detach
315
314
  ? {
316
315
  detachSignal: detach.signal,
@@ -448,13 +447,13 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
448
447
  : "";
449
448
  const clippedStdout = clipShellOutput(stdout);
450
449
  const clippedStderr = clipShellOutput(stderr);
451
- const stdoutImage = dataUriImageFromStdout(stdout);
450
+ const stdoutImage = await dataUriImageFromStdout(stdout, imageProcessor);
452
451
  if (stdoutImage) {
453
452
  const imgOverflowFile = stderr.length > bashMaxOutputChars() ? await writeShellOverflowFile(env, "", stderr) : undefined;
454
453
  const imgOverflowNote = imgOverflowFile !== undefined ? shellRecoveryHint(imgOverflowFile, readOnly) : "";
455
454
  return {
456
455
  content: [
457
- { type: "image", data: stdoutImage.data, mimeType: stdoutImage.mime },
456
+ stdoutImage,
458
457
  { type: "text", text: `exit code: ${exitCode}\n[Image data detected in stdout and shown above]${stderr.trim() !== "" ? `\n--- stderr ---\n${clippedStderr}` : ""}${imgOverflowNote}${cwdOutsideNote ? `\n${cwdOutsideNote}` : ""}${survivedCapNote ? `\n${survivedCapNote}` : ""}` },
459
458
  ],
460
459
  details: { type: "bash", stdout: "[image data]", stderr: clippedStderr, exitCode, isImage: true, ...(imgOverflowFile !== undefined ? { output_file: imgOverflowFile } : {}), ...(cappedByMaxTimeout ? { requestedTimeoutSec: requestedSec, cappedToMaxTimeoutSec: caps.maxSec } : {}) },
@@ -491,7 +490,7 @@ function bashDescription(coAuthor, caps, bgNotifies = false, bgRetained = false,
491
490
  : `- End git commit messages with:\nCo-Authored-By: ${coAuthor}`;
492
491
  return `Executes a bash command and returns its output.
493
492
 
494
- - Working directory persists between calls, but prefer absolute paths — a \`cd\` carries over and moves the base for every later command. Shell state (env vars, functions) does not persist; the shell is re-initialized each call, starting at the configured root.
493
+ - Working directory persists between calls, but prefer absolute paths — each call starts in the directory the previous call ended in, so a \`cd\` carries over and moves the base for every later command. Shell state (env vars, functions) does not persist; the shell is re-initialized each call.
495
494
  - IMPORTANT: Avoid using this tool to run \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user.
496
495
  - File search by name: use the Glob tool (NOT \`find\` or \`ls\`); content search: use the Grep tool (NOT \`grep\`/\`rg\` in the shell).
497
496
  - \`timeout\` is in milliseconds: default ${caps.defaultMs}, max ${caps.maxMs}.
@@ -508,19 +507,12 @@ ${coAuthorLines}
508
507
  - Treat evidence of a deployment restriction — "Operation not permitted", "Read-only file system", a denied path, or a network failure — as a boundary, not a bug: adjust within the allowed scope or report the limit; don't reach for a destructive or privilege-escalating workaround.`;
509
508
  }
510
509
  async function adoptBackgroundShell(req) {
511
- const { env, shellId, registry, description, toolUseId, ctxTaskId, ctxPrincipal, wiring } = req;
510
+ const { env, shellId, registry, description, toolUseId, ctxTaskId, ctxPrincipal, ctxTaskArtifacts, wiring } = req;
512
511
  const sessionScoped = wiring.sessionId !== undefined;
513
512
  const owner = sessionScoped ? wiring.sessionId : (ctxTaskId ?? wiring.taskOwner);
514
513
  const scope = ctxPrincipal ?? wiring.taskScope;
515
514
  const onNotify = wiring.onNotify;
516
- let outputFile;
517
- if (onNotify !== undefined) {
518
- const tf = await env.createTempFile({ prefix: "bash-task-", suffix: ".output" });
519
- if (tf.ok) {
520
- const tfCanon = await env.canonicalPath(tf.value);
521
- outputFile = tfCanon.ok ? tfCanon.value : tf.value;
522
- }
523
- }
515
+ const outputFile = onNotify !== undefined ? await createBackgroundOutputFile(env, "bash-task-") : undefined;
524
516
  try {
525
517
  const taskId = registry.registerBackgroundBash({
526
518
  env,
@@ -531,6 +523,7 @@ async function adoptBackgroundShell(req) {
531
523
  ...(scope !== undefined ? { scope } : {}),
532
524
  ...(sessionScoped ? { sessionScoped: true } : {}),
533
525
  ...(outputFile !== undefined ? { outputFile } : {}),
526
+ ...(ctxTaskArtifacts !== undefined ? { taskArtifacts: ctxTaskArtifacts } : {}),
534
527
  ...(onNotify !== undefined ? { onTerminal: (n) => onNotify(n, { priority: "next" }) } : {}),
535
528
  ...(wiring.retainBackgroundProcesses !== undefined ? { retainBackgroundProcesses: wiring.retainBackgroundProcesses } : {}),
536
529
  });
@@ -607,9 +600,11 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
607
600
  if (ctx.signal?.aborted === true)
608
601
  return errorResult("Error (Bash): the call was cancelled before the background command started.");
609
602
  const requestedTimeoutSec = timeout !== undefined ? Math.max(1, Math.round(timeout / 1000)) : undefined;
603
+ const readFloor = taskOpts.readFloor?.(ctx.toolCallId);
610
604
  const r = await env.spawnBackground(command, {
611
605
  cwd: cwdRef.current,
612
606
  ...(requestedTimeoutSec !== undefined ? { timeout: requestedTimeoutSec } : {}),
607
+ ...(readFloor !== undefined ? { readFloor } : {}),
613
608
  });
614
609
  if (!r.ok)
615
610
  return errorResult(`Error (Bash): the background process could not be started (${r.error.code}): ${envErrorDetail(r.error.message)}`);
@@ -626,7 +621,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
626
621
  const lifetimeNote = backgroundLifetimeNote(bgRetained, bgSessionScoped, bgEnvIsolatedOwned);
627
622
  const registry = taskOpts.taskRegistry;
628
623
  if (registry !== undefined) {
629
- const onNotify = taskOpts.onTaskNotification;
624
+ const onNotify = resolveCompletionSink(ctx.onTaskNotification, taskOpts.onTaskNotification);
630
625
  const adopted = await adoptBackgroundShell({
631
626
  env,
632
627
  shellId: r.value.shellId,
@@ -635,6 +630,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
635
630
  toolUseId: ctx.toolCallId,
636
631
  ctxTaskId: ctx.taskId,
637
632
  ctxPrincipal: ctx.principal,
633
+ ctxTaskArtifacts: ctx.taskArtifacts,
638
634
  wiring: { sessionId: taskOpts.sessionId, taskOwner: taskOpts.taskOwner, taskScope: taskOpts.taskScope, onNotify, retainBackgroundProcesses: taskOpts.retainBackgroundProcesses },
639
635
  });
640
636
  if (!adopted.ok) {
@@ -654,9 +650,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
654
650
  ? ` Output file: ${outputFile} (full output is appended there — Read it any time).`
655
651
  : ` Use TaskOutput("${taskId}") to check interim output.`;
656
652
  if (taskOpts.oneShot === true && onNotify !== undefined) {
657
- return (`Command running in background; task_id=${taskId}.${interimNote} This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput({ task_id: "${taskId}", block: true }). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget. TaskStop("${taskId}") to stop.` +
658
- budgetNote +
659
- lifetimeNote);
653
+ return `Command running in background; task_id=${taskId}.${interimNote} ${ONE_SHOT_BACKGROUND_COMMAND_NOTE} TaskStop("${taskId}") to stop.` + budgetNote + lifetimeNote;
660
654
  }
661
655
  return onNotify !== undefined
662
656
  ? `Command running in background; task_id=${taskId}.${interimNote} You will be notified when it completes — do not poll; ` +
@@ -698,7 +692,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
698
692
  ? {
699
693
  signal: detachHub.signalFor(ctx.toolCallId),
700
694
  onDetached: async (shellId, stdoutSoFar, stderrSoFar, cause) => {
701
- const onNotify = taskOpts.onTaskNotification;
695
+ const onNotify = resolveCompletionSink(ctx.onTaskNotification, taskOpts.onTaskNotification);
702
696
  const adopted = await adoptBackgroundShell({
703
697
  env: detachEnv,
704
698
  shellId: shellId,
@@ -707,6 +701,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
707
701
  toolUseId: ctx.toolCallId,
708
702
  ctxTaskId: ctx.taskId,
709
703
  ctxPrincipal: ctx.principal,
704
+ ctxTaskArtifacts: ctx.taskArtifacts,
710
705
  wiring: { sessionId: taskOpts.sessionId, taskOwner: taskOpts.taskOwner, taskScope: taskOpts.taskScope, onNotify, retainBackgroundProcesses: taskOpts.retainBackgroundProcesses },
711
706
  });
712
707
  if (!adopted.ok) {
@@ -749,8 +744,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
749
744
  : `Use TaskOutput("${taskId}") to read its output. `) +
750
745
  `TaskStop("${taskId}") to stop it. ` +
751
746
  (taskOpts.oneShot === true && onNotify !== undefined
752
- ?
753
- `This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput({ task_id: "${taskId}", block: true }).`
747
+ ? ONE_SHOT_BACKGROUND_COMMAND_NOTE
754
748
  : onNotify !== undefined
755
749
  ? `You will be notified when it completes — do not poll.`
756
750
  : `Poll TaskOutput until its status is no longer "running".`) +
@@ -765,7 +759,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
765
759
  : undefined;
766
760
  let res;
767
761
  try {
768
- res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, cwdRef, detachChain, false, [rootCanonical, ...(taskOpts.additionalRoots ?? [])], onTick);
762
+ res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, cwdRef, detachChain, false, [rootCanonical, ...(taskOpts.additionalRoots ?? [])], onTick, taskOpts.readFloor?.(ctx.toolCallId), taskOpts.imageProcessor);
769
763
  }
770
764
  finally {
771
765
  taskOpts.detachHub?.gc(ctx.toolCallId);
@@ -811,7 +805,7 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
811
805
  if (refused !== undefined)
812
806
  return refused;
813
807
  const readOnlyTick = opts?.onToolProgress === undefined ? undefined : (t) => describeSafely(opts.onToolProgress, { toolCallId: ctx.toolCallId, toolName: "Bash", ...t });
814
- return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, true, undefined, readOnlyTick);
808
+ return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, true, undefined, readOnlyTick, opts?.readFloor?.(ctx.toolCallId), opts?.imageProcessor);
815
809
  },
816
810
  });
817
811
  }
@@ -1,7 +1,7 @@
1
1
  import type { DocumentContent, ImageContent, TextContent } from "../../internal/llm.js";
2
2
  import type { ExecutionEnv } from "../../internal/harness-types.js";
3
+ import { type ImageDownsampler } from "../../core/image-downsample.js";
3
4
  import { type PdfModelCapabilities } from "./pdf.js";
4
- import { type ReadImageDownsamplerOption } from "./fs-shared.js";
5
5
  import { type ReminderDisclosureEffects } from "../../core/reminder-disclosure.js";
6
6
  /** The reader's disclosure state, threaded into the PDF TEXT legs (the two `pdftotext` extraction arms —
7
7
  * the only PDF returns with a model-facing text projection of the document; the native document block and
@@ -44,4 +44,4 @@ type ReadPdfReturn = string | {
44
44
  * Every degraded return carries `details.fallback = { level, reason }` (telemetry on the structured frame).
45
45
  * `caps` absent ⇒ fully capable (native document block; the brain placeholder still guards).
46
46
  */
47
- export declare function readPdfFile(env: ExecutionEnv, path: string, key: string, pages: string | undefined, signal: AbortSignal | undefined, downsamplerOpt: ReadImageDownsamplerOption, cwd: string, preRead?: Uint8Array, caps?: PdfModelCapabilities, readDeny?: import("./read-deny.js").ReadDenyMatcher, disclosure?: PdfReminderDisclosure): Promise<ReadPdfReturn>;
47
+ export declare function readPdfFile(env: ExecutionEnv, path: string, key: string, pages: string | undefined, signal: AbortSignal | undefined, imageProcessor: ImageDownsampler | false | undefined, cwd: string, preRead?: Uint8Array, caps?: PdfModelCapabilities, readDeny?: import("./read-deny.js").ReadDenyMatcher, disclosure?: PdfReminderDisclosure): Promise<ReadPdfReturn>;
@@ -1,8 +1,8 @@
1
1
  import { delimitUntrusted } from "../../core/untrusted-text.js";
2
- import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
2
+ import { resolveImageProcessor } from "../../core/image-downsample.js";
3
3
  import { PDF_FALLBACK_RENDER_PAGES, PDF_INLINE_PAGE_THRESHOLD, PDF_MAX_EXTRACT_SIZE, PDF_MAX_PAGES_PER_READ, extractPdfPagesAsImages, extractPdfTextLayer, getPdfPageCount, parsePdfPageRange, pdfCutWords, } from "./pdf.js";
4
- import { PDF_TARGET_RAW_SIZE, pdfMagicMatches } from "../../core/image-admission.js";
5
- import { resolveAutoDownsampler, enoentMessage, MAX_READ_BYTES } from "./fs-shared.js";
4
+ import { admitImageBytes, IMAGE_ADMISSION, PDF_TARGET_RAW_SIZE, pdfMagicMatches, unprocessedSizeClause } from "../../core/image-admission.js";
5
+ import { enoentMessage, MAX_READ_BYTES } from "./fs-shared.js";
6
6
  import { planReminderDisclosure, renderReminderDisclosureTrailer } from "../../core/reminder-disclosure.js";
7
7
  import { MARKED_BLOCK_AFTER_DATA } from "../../core/reminder-mint.js";
8
8
  function pdfDisclosureTrailer(body, d) {
@@ -14,33 +14,38 @@ function pdfDisclosureTrailer(body, d) {
14
14
  return trailer !== undefined ? `${MARKED_BLOCK_AFTER_DATA}${trailer}` : "";
15
15
  }
16
16
  export { pdfModelCapabilitiesOf } from "./pdf.js";
17
- async function pdfPagesToImageBlocks(pages, path, downsamplerOpt) {
18
- const downsampler = downsamplerOpt === false ? undefined : (downsamplerOpt ?? (await resolveAutoDownsampler()));
17
+ async function pdfPagesToImageBlocks(pages, path, imageProcessor) {
18
+ const processor = await resolveImageProcessor(imageProcessor);
19
19
  const blocks = [];
20
20
  for (const p of pages) {
21
- let b64;
22
- let mime = "image/jpeg";
23
- if (downsampler) {
24
- const out = await downsampler(Buffer.from(p.jpeg), "image/jpeg").catch(() => undefined);
25
- if (out) {
26
- b64 = out.base64;
27
- mime = out.mimeType;
28
- }
29
- }
30
- b64 ??= Buffer.from(p.jpeg).toString("base64");
31
- if (b64.length > MCP_IMAGE_MAX_BASE64) {
32
- return `Error (Read): rendered page ${p.pageNumber} of "${path}" is too large to send (base64 ${b64.length} chars exceeds the ${MCP_IMAGE_MAX_BASE64}-char / 5MB API image limit); narrow the range or extract text via Bash (e.g. \`pdftotext\`).`;
21
+ const admitted = await admitImageBytes(p.jpeg, "image/jpeg", processor);
22
+ if (!admitted.ok) {
23
+ return `Error (Read): rendered page ${p.pageNumber} of "${path}" cannot be sent (${pageRefusal(admitted)}); narrow the range or extract text via Bash (e.g. \`pdftotext\`).`;
33
24
  }
34
- blocks.push({ type: "image", data: b64, mimeType: mime });
25
+ blocks.push(admitted.block);
35
26
  }
36
27
  return blocks;
37
28
  }
29
+ function pageRefusal(a) {
30
+ switch (a.reason) {
31
+ case "mime_unsupported":
32
+ case "magic_mismatch":
33
+ return "the renderer's output is not a valid JPEG";
34
+ case "raw_too_large":
35
+ return `${a.rawBytes} bytes, over the ${a.cap}-byte read cap`;
36
+ case "dimensions_unreadable":
37
+ case "dimensions_too_large":
38
+ return unprocessedSizeClause(a);
39
+ case "base64_too_large":
40
+ return `base64 ${a.base64.length} chars exceeds the ${IMAGE_ADMISSION.hard.imageBase64Chars}-char / 5MB API image limit`;
41
+ }
42
+ }
38
43
  function boundPdfExtractedText(text) {
39
44
  if (Buffer.byteLength(text, "utf8") <= MAX_READ_BYTES)
40
45
  return { body: text, truncated: false };
41
46
  return { body: text.slice(0, MAX_READ_BYTES), truncated: true };
42
47
  }
43
- export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt, cwd, preRead, caps, readDeny, disclosure) {
48
+ export async function readPdfFile(env, path, key, pages, signal, imageProcessor, cwd, preRead, caps, readDeny, disclosure) {
44
49
  const cap = caps ?? { document: true, vision: true };
45
50
  const meta = await env.fileInfo(key, signal);
46
51
  if (!meta.ok) {
@@ -125,7 +130,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
125
130
  }
126
131
  return `Error (Read): PDF page extraction failed for "${path}": ${extract.error}`;
127
132
  }
128
- const blocks = await pdfPagesToImageBlocks(extract.pages, path, downsamplerOpt);
133
+ const blocks = await pdfPagesToImageBlocks(extract.pages, path, imageProcessor);
129
134
  if (typeof blocks === "string")
130
135
  return blocks;
131
136
  const requestedPages = last - range.first + 1;
@@ -192,7 +197,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
192
197
  const n = Math.min(PDF_FALLBACK_RENDER_PAGES, pageCount ?? PDF_FALLBACK_RENDER_PAGES);
193
198
  const extract = await extractPdfPagesAsImages(env, key, 1, n, signal);
194
199
  if (extract.ok) {
195
- const blocks = await pdfPagesToImageBlocks(extract.pages, path, downsamplerOpt);
200
+ const blocks = await pdfPagesToImageBlocks(extract.pages, path, imageProcessor);
196
201
  if (typeof blocks !== "string") {
197
202
  const renderTimeoutNote = extract.cut !== undefined ? ` pdftoppm ${pdfCutWords(extract.cut).clause} — only the pages that finished rendering are included.` : "";
198
203
  return {
@@ -3,9 +3,9 @@ import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
3
3
  import { errorResult } from "../../core/tools.js";
4
4
  import type { ToolReturn } from "../../core/tool-spec.js";
5
5
  import { type ReadEntry, type ReadFileState, type RootsSeat } from "./safety.js";
6
- import { type ImageDimensions } from "../../core/mcp.js";
6
+ import { type ImageDimensions, type ImageDownsampler } from "../../core/image-downsample.js";
7
7
  import { type PdfModelCapabilities } from "./pdf.js";
8
- import { type ReadImageDownsamplerOption, type CwdRef } from "./fs-shared.js";
8
+ import { type CwdRef } from "./fs-shared.js";
9
9
  import { type ReminderDisclosureCounts, type ReminderDisclosureEffects, type ReminderDisclosureVerdict } from "../../core/reminder-disclosure.js";
10
10
  import { type DirectoryListing } from "./dir-entries.js";
11
11
  import { FileError, type BoundFileObject, type Result } from "../../internal/harness.js";
@@ -174,7 +174,8 @@ export interface ModelFileReaderOptions {
174
174
  rootCanonical: string;
175
175
  cwdRef?: CwdRef;
176
176
  additionalRoots?: RootsSeat;
177
- imageDownsampler?: ReadImageDownsamplerOption;
177
+ /** The run's image processor seat (`RunnerDeps.imageProcessor`): a processor, `false` (none), absent = auto-detect. */
178
+ imageProcessor?: ImageDownsampler | false;
178
179
  pdfCapabilities?: PdfModelCapabilities;
179
180
  /** See createReadFileTool's seat of the same name. */
180
181
  bgOutputReadExemption?: (canonicalKey: string, ctx: {
@@ -229,7 +230,7 @@ export declare function createModelFileReader(opts: ModelFileReaderOptions): Mod
229
230
  export declare function renderReadNoteForTool(note: ReadNote, mark: string | undefined): string;
230
231
  /** The Read tool's result for one read — the composition each lane has always returned. */
231
232
  export declare function renderReadToolResult(r: ReadForModelResult, mark: string | undefined): ToolReturn;
232
- export declare function createReadFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: RootsSeat, imageDownsampler?: ReadImageDownsamplerOption, pdfCapabilities?: PdfModelCapabilities, bgOutputReadExemption?: (canonicalKey: string, ctx: {
233
+ export declare function createReadFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: RootsSeat, imageProcessor?: ImageDownsampler | false, pdfCapabilities?: PdfModelCapabilities, bgOutputReadExemption?: (canonicalKey: string, ctx: {
233
234
  taskId?: string;
234
235
  principal?: string;
235
236
  toolCallId?: string;
@@ -3,9 +3,9 @@ import { defineTool, errorResult } from "../../core/tools.js";
3
3
  import { sha256, resolveKey, violationText, violationDetails, binaryMagicFormat, hasBinaryExtension, isBinaryContent, imageMimeForRead, } from "./safety.js";
4
4
  import { decodeTextBytes } from "./encoding.js";
5
5
  import { isNotebookPath, parseNotebookCells, renderNotebookCells, stripNotebookImageData, NOTEBOOK_IMAGE_BASE64_BUDGET } from "./notebook.js";
6
- import { MCP_IMAGE_MAX_BASE64, IMAGE_TARGET_RAW_SIZE } from "../../core/mcp.js";
6
+ import { resolveImageProcessor } from "../../core/image-downsample.js";
7
7
  import { countPdfPagesFromBytes, PDF_MAX_PAGES_PER_READ } from "./pdf.js";
8
- import { MAX_READ_BYTES, SLICED_READ_MAX_BYTES, NO_DOWNSAMPLER_IMAGE_CAP_HINT, resolveAutoDownsampler, MAX_READ_OUTPUT_CHARS, FILE_PATH_PARAMS, countLines, seededFileUnchangedReminder, enoentMessage, } from "./fs-shared.js";
8
+ import { MAX_READ_BYTES, SLICED_READ_MAX_BYTES, NO_DOWNSAMPLER_IMAGE_CAP_HINT, MAX_READ_OUTPUT_CHARS, FILE_PATH_PARAMS, countLines, seededFileUnchangedReminder, enoentMessage, } from "./fs-shared.js";
9
9
  import { readPdfFile } from "./fs-pdf.js";
10
10
  import { seatForCall, seatReady } from "./read-deny.js";
11
11
  import { thrownText } from "../../core/thrown-value.js";
@@ -13,14 +13,28 @@ import { MARKED_BLOCK_AFTER_DATA, openSystemReminder } from "../../core/reminder
13
13
  import { planReminderDisclosure, commitReminderDisclosureEffects, renderReminderDisclosureTrailer, } from "../../core/reminder-disclosure.js";
14
14
  import { toolFace } from "../../core/tool-catalog-entries.js";
15
15
  import { fileArgPath } from "../../core/tool-registry.js";
16
- import { admitImageBytes, imageReadCap, PDF_TARGET_RAW_SIZE, pdfMagicMatches } from "../../core/image-admission.js";
16
+ import { admitImageBytes, IMAGE_ADMISSION, imageReadCap, PDF_TARGET_RAW_SIZE, pdfMagicMatches, unprocessedSizeClause } from "../../core/image-admission.js";
17
17
  import { createEntryDenyJudge, enumerateDirectory } from "./dir-entries.js";
18
18
  import { FileError } from "../../internal/harness.js";
19
19
  export const READ_OUTCOMES = Object.freeze(["attached", "partial", "unchanged", "not_attached"]);
20
20
  const UNBINDABLE = "this environment cannot bind a read to the file that was checked, so it was not read";
21
21
  const NO_EFFECTS = () => ({ disclosure: [] });
22
+ async function admitNotebookImages(blocks, imageProcessor) {
23
+ if (!blocks.some((b) => b.type === "image"))
24
+ return blocks;
25
+ const processor = await resolveImageProcessor(imageProcessor);
26
+ return Promise.all(blocks.map(async (b) => {
27
+ if (b.type !== "image")
28
+ return b;
29
+ const a = await admitImageBytes(Buffer.from(b.data, "base64"), b.mimeType, processor);
30
+ if (a.ok)
31
+ return a.block;
32
+ const why = a.reason === "dimensions_unreadable" || a.reason === "dimensions_too_large" ? `: ${unprocessedSizeClause(a)}` : "";
33
+ return { type: "text", text: `[image output not shown (media admission: ${a.reason})${why}]` };
34
+ }));
35
+ }
22
36
  export function createModelFileReader(opts) {
23
- const { env, state, rootCanonical, cwdRef, imageDownsampler, pdfCapabilities, bgOutputReadExemption, readFace, reminderMark, readDeny: readDenySeat, additionalRoots: rootsSeat } = opts;
37
+ const { env, state, rootCanonical, cwdRef, imageProcessor, pdfCapabilities, bgOutputReadExemption, readFace, reminderMark, readDeny: readDenySeat, additionalRoots: rootsSeat } = opts;
24
38
  const windows = opts.disclosureWindows ?? new Map();
25
39
  const refuse = (envelope, kind) => ({
26
40
  outcome: "not_attached",
@@ -77,16 +91,16 @@ export function createModelFileReader(opts) {
77
91
  return refuse(errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal, readDeny)}`), "image");
78
92
  return refuse(errorResult(`Error (Read): cannot stat image "${path}" to verify its size before reading: ${meta.error.message}`), "image");
79
93
  }
80
- const downsampler = imageDownsampler === false ? undefined : (imageDownsampler ?? (await resolveAutoDownsampler()));
81
- const readCap = imageReadCap(downsampler);
82
- const tooLargeToRead = (bytes) => `Error (Read): image "${path}" is too large to read (${bytes} bytes > ${readCap}-byte cap).` +
83
- (downsampler ? "" : ` ${NO_DOWNSAMPLER_IMAGE_CAP_HINT}`);
94
+ const processor = await resolveImageProcessor(imageProcessor);
95
+ const readCap = imageReadCap(processor);
96
+ const noProcessorHint = processor === "none" ? ` ${NO_DOWNSAMPLER_IMAGE_CAP_HINT}` : "";
97
+ const tooLargeToRead = (bytes) => `Error (Read): image "${path}" is too large to read (${bytes} bytes > ${readCap}-byte cap).${noProcessorHint}`;
84
98
  if (meta.value.size > readCap)
85
99
  return refuse(errorResult(tooLargeToRead(meta.value.size)), "image");
86
100
  const bin = await readBytes(r.key, readCap);
87
101
  if (!bin.ok)
88
102
  return refuse(errorResult(`Error (Read): cannot read image "${path}": ${bin.error.message}`), "image");
89
- const admitted = await admitImageBytes(bin.value, imageMime, downsampler);
103
+ const admitted = await admitImageBytes(bin.value, imageMime, processor);
90
104
  if (!admitted.ok) {
91
105
  switch (admitted.reason) {
92
106
  case "raw_too_large":
@@ -94,11 +108,14 @@ export function createModelFileReader(opts) {
94
108
  case "magic_mismatch":
95
109
  case "mime_unsupported":
96
110
  return refuse(errorResult(`Error (Read): "${path}" has an image extension but its content is not a valid ${imageMime} (empty, truncated, or mis-named).`), "image");
111
+ case "dimensions_unreadable":
112
+ case "dimensions_too_large":
113
+ return refuse(errorResult(`Error (Read): image "${path}" cannot be sent: ${unprocessedSizeClause(admitted)}.${noProcessorHint}`), "image");
97
114
  case "base64_too_large":
98
- return refuse(errorResult(`Error (Read): image "${path}" is too large to send (${bin.value.byteLength} bytes; base64 ${admitted.base64.length} chars exceeds the ${MCP_IMAGE_MAX_BASE64}-char / 5MB API image limit` +
99
- (downsampler
100
- ? "; downsampling could not bring it under the limit)."
101
- : `; raw images over ${IMAGE_TARGET_RAW_SIZE} bytes always exceed it — shrink it first, e.g. with an image tool via bash).`)), "image");
115
+ return refuse(errorResult(`Error (Read): image "${path}" is too large to send (${bin.value.byteLength} bytes; base64 ${admitted.base64.length} chars exceeds the ${IMAGE_ADMISSION.hard.imageBase64Chars}-char / 5MB API image limit` +
116
+ (processor !== "none"
117
+ ? "; processing could not bring it under the limit)."
118
+ : `; raw images over ${IMAGE_ADMISSION.soft.rawBytes} bytes always exceed it — shrink it first, e.g. with an image tool via bash).`)), "image");
102
119
  }
103
120
  }
104
121
  const { block, dimensions, originalSize, resized } = admitted;
@@ -135,7 +152,7 @@ export function createModelFileReader(opts) {
135
152
  };
136
153
  }
137
154
  const effects = [];
138
- const out = await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, preRead, pdfCapabilities, readDeny, {
155
+ const out = await readPdfFile(env, path, r.key, pages, ctx.signal, imageProcessor, cwdRef?.current ?? rootCanonical, preRead, pdfCapabilities, readDeny, {
139
156
  mark: reminderMark,
140
157
  windows,
141
158
  key: r.key,
@@ -195,7 +212,7 @@ export function createModelFileReader(opts) {
195
212
  `this tool reads UTF-8 and BOM-marked UTF-16LE text only. Inspect or convert it with bash instead.`), "text");
196
213
  }
197
214
  const decoded = decodeTextBytes(readBin.value);
198
- if (decoded.malformed) {
215
+ if (decoded.malformed === "truncated_utf16") {
199
216
  return refuse(errorResult(`Error (Read): "${path}" has a UTF-16 BOM but a truncated (odd-length) body — the file is corrupt or mis-labelled; repair/convert it with bash (e.g. \`iconv\`) first.`), "text");
200
217
  }
201
218
  const content = decoded.text;
@@ -249,7 +266,7 @@ export function createModelFileReader(opts) {
249
266
  return {
250
267
  outcome: "attached",
251
268
  kind: "notebook",
252
- data: rendered.blocks,
269
+ data: await admitNotebookImages(rendered.blocks, imageProcessor),
253
270
  notes,
254
271
  details: { type: "notebook", file: { filePath: path, cells: parsed.cells.map(stripNotebookImageData) } },
255
272
  observation,
@@ -435,14 +452,14 @@ export function renderReadToolResult(r, mark) {
435
452
  }
436
453
  }
437
454
  }
438
- export function createReadFileTool(env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities, bgOutputReadExemption, readDeny, readFace, reminderMark, reminderDisclosureCounts, sharedReader) {
455
+ export function createReadFileTool(env, state, rootCanonical, cwdRef, additionalRoots, imageProcessor, pdfCapabilities, bgOutputReadExemption, readDeny, readFace, reminderMark, reminderDisclosureCounts, sharedReader) {
439
456
  const reader = sharedReader ?? createModelFileReader({
440
457
  env,
441
458
  state,
442
459
  rootCanonical,
443
460
  ...(cwdRef !== undefined ? { cwdRef } : {}),
444
461
  ...(additionalRoots !== undefined ? { additionalRoots } : {}),
445
- imageDownsampler,
462
+ imageProcessor,
446
463
  ...(pdfCapabilities !== undefined ? { pdfCapabilities } : {}),
447
464
  ...(bgOutputReadExemption !== undefined ? { bgOutputReadExemption } : {}),
448
465
  ...(readDeny !== undefined ? { readDeny } : {}),
@@ -3,6 +3,7 @@ import { defineTool, errorResult } from "../../core/tools.js";
3
3
  import { clipSpelling, pathFamilyOf, resolveKey, violationText, violationDetails, WIN32_NAMESPACE_REFUSAL_TEXT } from "./safety.js";
4
4
  import { runGrepDetailed, runGlobDetailed, invalidGlobTokens } from "./search.js";
5
5
  import { seatForCall } from "./read-deny.js";
6
+ import { readFloorSeat } from "./read-floor.js";
6
7
  import { toolFace } from "../../core/tool-catalog-entries.js";
7
8
  import { pathTargetBaseOf, splitAbsoluteGlobPattern } from "../../core/effective-path-target.js";
8
9
  import { pathTargetValue } from "../../core/tool-registry.js";
@@ -77,6 +78,7 @@ export function grepDetailFields(text, mode, offset, structuredRows) {
77
78
  }
78
79
  export function createGrepTool(env, rootCanonical, rootsSeat, denySeat, readFace, cwdRef, readAdmission) {
79
80
  const declaredTarget = toolFace("grep").pathTarget;
81
+ const grepReadFloor = readFloorSeat(denySeat);
80
82
  return defineTool({
81
83
  name: "Grep",
82
84
  ...toolFace("grep"),
@@ -115,6 +117,7 @@ export function createGrepTool(env, rootCanonical, rootsSeat, denySeat, readFace
115
117
  execute: async (args, ctx) => {
116
118
  const readDeny = seatForCall(denySeat, ctx.toolCallId);
117
119
  const additionalRoots = seatForCall(rootsSeat, ctx.toolCallId);
120
+ const readFloor = grepReadFloor?.(ctx.toolCallId);
118
121
  const retired = args;
119
122
  for (const [name, repair] of [
120
123
  ["regex", "the `pattern` is ALWAYS evaluated as a regular expression (ripgrep semantics) — drop the key; to match text literally, escape the regex metacharacters in `pattern`"],
@@ -167,7 +170,7 @@ export function createGrepTool(env, rootCanonical, rootsSeat, denySeat, readFace
167
170
  context_before: a.context_before ?? a["-B"],
168
171
  ignore_case: a.ignore_case ?? a["-i"],
169
172
  only_matching: a.only_matching ?? a["-o"],
170
- }, ctx.signal, readDeny);
173
+ }, ctx.signal, readDeny, readFloor);
171
174
  const text = grepRun.text;
172
175
  if (text.startsWith("Error (grep)") || text.startsWith("Error (Grep)"))
173
176
  return errorResult(text);
@@ -1,9 +1,8 @@
1
1
  import { Type } from "typebox";
2
2
  import type { ExecutionEnv } from "../../internal/harness-types.js";
3
3
  import { type FsViolation, type ReadEntry, type ReadFileState } from "./safety.js";
4
- import { type DecodedTextFile } from "./encoding.js";
4
+ import { type DecodedTextFile, type MalformedBody } from "./encoding.js";
5
5
  import { type HomeViewsCarrier } from "./read-deny-home.js";
6
- import { type ImageDownsampler } from "../../core/mcp.js";
7
6
  import { type EngineNotice } from "../../core/types.js";
8
7
  /**
9
8
  * The "hand" tool band — built per task over an injected {@link ExecutionEnv} and a per-task
@@ -60,6 +59,11 @@ export declare function tooLargeToEditMessage(path: string, bytes: number): stri
60
59
  /** The truncated-UTF-16 repair instruction, parameterized by the tool that refused. The condition is one
61
60
  * condition — an odd-length UTF-16 body cannot be decoded — reached from Edit, Write and NotebookEdit. */
62
61
  export declare function truncatedUtf16BodyMessage(tool: string, path: string): string;
62
+ /** The refusal of a body that is not valid UTF-8 (`not_utf8`), parameterized by the tool that refused: nothing was written,
63
+ * and the ways to make the change without converting the file. */
64
+ export declare function notUtf8BodyMessage(tool: string, path: string): string;
65
+ /** The write lanes' one refusal of a body they cannot write back byte for byte, by why ({@link MalformedBody}). */
66
+ export declare function malformedBodyMessage(tool: string, path: string, why: MalformedBody): string;
63
67
  /** Why a bash_readonly refusal is terminal rather than escalated. Appended by every arm of that refusal
64
68
  * family; the arms differ in what they found, never in what the model can do about it. */
65
69
  export declare 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.";
@@ -111,18 +115,12 @@ export declare function applyRecordedEdit(text: string, edit: RecordedEdit): str
111
115
  * both sharper shapes describe files Read handled successfully, so the encoding-deadlock sentence
112
116
  * would be false there — and stacking two escape routes on one refusal buries the one that applies. */
113
117
  export declare function notReadRefusalText(env: ExecutionEnv, toolName: string, key: string, v: Pick<FsViolation, "code" | "message" | "partialView">, signal?: AbortSignal, fallbackHint?: string): Promise<string>;
114
- /** The no-downsampler cap (`MAX_IMAGE_READ_BYTES`, core/image-admission.ts) is a DELIBERATE bound and does not move — but its refusal must not
115
- * read like a hard ceiling. Whether the higher cap is reachable depends on an OPTIONAL dependency the
118
+ /** The no-processor read cap (`IMAGE_ADMISSION.hard.readBytes.withoutProcessor`) is a DELIBERATE bound and does not move — but its
119
+ * refusal must not read like a hard ceiling. Whether the higher cap is reachable depends on an OPTIONAL dependency the
116
120
  * caller can install, and only this package knows that, so the refusal names the move instead of
117
- * leaving the caller to guess that the limit is negotiable. Appended ONLY on the no-downsampler
118
- * branch: with sharp already resolved the hint would be false advice. */
119
- export declare const NO_DOWNSAMPLER_IMAGE_CAP_HINT = "Install the optional \"sharp\" dependency (declared in this package's optionalDependencies) to read images up to 67108864 bytes \u2014 it downsamples them to fit the API image limit.";
120
- /** Read-image downsampler seam: `undefined` → auto-detect sharp; `false` → force-disabled (deterministic
121
- * no-sharp path, used by tests + envs that must not touch native deps); a function → injected. */
122
- export type ReadImageDownsamplerOption = ImageDownsampler | false | undefined;
123
- /** Resolve (and memoize) the auto-detected sharp downsampler, process-wide. Shared accessor for the two
124
- * consumers of the module-private {@link autoDownsampler} cache. */
125
- export declare function resolveAutoDownsampler(): Promise<ImageDownsampler | undefined>;
121
+ * leaving the caller to guess that the limit is negotiable. Appended ONLY on the no-processor
122
+ * branch: with a processor already resolved the hint would be false advice. */
123
+ export declare const NO_DOWNSAMPLER_IMAGE_CAP_HINT: string;
126
124
  /** Output-token cap as a char proxy (CC's 25000, at ~4 chars/token). Caps the shown body so 2000 very
127
125
  * long lines cannot blow the context budget.
128
126
  *