@sema-agent/core 7.59.0 → 7.61.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (643) hide show
  1. package/CHANGELOG.md +1169 -0
  2. package/README.md +2 -2
  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 +4 -3
  6. package/dist/agents/agent-transcript-tool.js +4 -2
  7. package/dist/agents/cascade.d.ts +61 -10
  8. package/dist/agents/cascade.js +60 -20
  9. package/dist/agents/child-model-seat.js +6 -3
  10. package/dist/agents/composition-allowance.d.ts +53 -0
  11. package/dist/agents/composition-allowance.js +49 -0
  12. package/dist/agents/composition-placement.d.ts +29 -0
  13. package/dist/agents/composition-placement.js +24 -0
  14. package/dist/agents/cumulative-stats.d.ts +4 -0
  15. package/dist/agents/cumulative-stats.js +3 -1
  16. package/dist/agents/inherited-tool-pool.d.ts +28 -1
  17. package/dist/agents/inherited-tool-pool.js +22 -0
  18. package/dist/agents/list-agents-tool.d.ts +1 -1
  19. package/dist/agents/peer-notice-route.d.ts +1 -1
  20. package/dist/agents/peer-notice-route.js +4 -3
  21. package/dist/agents/peer-notices.d.ts +4 -4
  22. package/dist/agents/peer-notices.js +8 -4
  23. package/dist/agents/peer-session-drain.d.ts +8 -1
  24. package/dist/agents/peer-session-drain.js +36 -7
  25. package/dist/agents/repair-loop.js +16 -6
  26. package/dist/agents/retain-ledger.d.ts +11 -1
  27. package/dist/agents/retain-ledger.js +16 -3
  28. package/dist/agents/roster-store.d.ts +2 -2
  29. package/dist/agents/roster-store.js +8 -3
  30. package/dist/agents/send-message-tool.d.ts +14 -27
  31. package/dist/agents/send-message-tool.js +47 -54
  32. package/dist/agents/subagent-completion-gate.d.ts +35 -0
  33. package/dist/agents/subagent-completion-gate.js +62 -0
  34. package/dist/agents/subagent-steps.d.ts +7 -6
  35. package/dist/agents/subagent.d.ts +52 -28
  36. package/dist/agents/subagent.js +276 -246
  37. package/dist/agents/suspend-guard.d.ts +9 -0
  38. package/dist/agents/suspend-guard.js +4 -0
  39. package/dist/agents/tool-filter.d.ts +1 -3
  40. package/dist/agents/tool-filter.js +4 -12
  41. package/dist/agents/verify.d.ts +41 -14
  42. package/dist/agents/verify.js +37 -27
  43. package/dist/bench/metrics.d.ts +3 -5
  44. package/dist/bench/metrics.js +0 -1
  45. package/dist/brain/anthropic.js +1 -0
  46. package/dist/brain/degrading.js +3 -1
  47. package/dist/brain/errors.d.ts +7 -1
  48. package/dist/brain/errors.js +6 -0
  49. package/dist/brain/failover.js +2 -1
  50. package/dist/brain/open-responses.js +1 -0
  51. package/dist/brain/openai.js +1 -0
  52. package/dist/brain/provider-dialect.d.ts +10 -0
  53. package/dist/brain/provider-dialect.js +13 -2
  54. package/dist/brain/route-adjudicator.js +3 -1
  55. package/dist/brain/status-sink.d.ts +7 -1
  56. package/dist/brain/status-sink.js +6 -0
  57. package/dist/brain/stream-engine.d.ts +3 -0
  58. package/dist/brain/stream-engine.js +4 -0
  59. package/dist/brain/timeout.d.ts +3 -1
  60. package/dist/brain/timeout.js +18 -5
  61. package/dist/core/a2a.d.ts +15 -5
  62. package/dist/core/a2a.js +34 -19
  63. package/dist/core/agent-definition.d.ts +20 -0
  64. package/dist/core/agent-state.d.ts +1 -1
  65. package/dist/core/allow-entry.d.ts +61 -23
  66. package/dist/core/allow-entry.js +134 -39
  67. package/dist/core/artifact-host.d.ts +0 -2
  68. package/dist/core/artifact-host.js +0 -1
  69. package/dist/core/ask-origin.d.ts +79 -0
  70. package/dist/core/ask-origin.js +76 -0
  71. package/dist/core/ask-question.d.ts +19 -13
  72. package/dist/core/ask-question.js +8 -2
  73. package/dist/core/auto-compaction.d.ts +2 -0
  74. package/dist/core/auto-compaction.js +2 -1
  75. package/dist/core/auto-mode-defaults.d.ts +8 -0
  76. package/dist/core/auto-mode-defaults.js +1 -0
  77. package/dist/core/auto-mode-rebuild.d.ts +2 -1
  78. package/dist/core/auto-mode.d.ts +39 -4
  79. package/dist/core/auto-mode.js +66 -17
  80. package/dist/core/background-agent-store.d.ts +17 -6
  81. package/dist/core/background-agent-store.js +15 -13
  82. package/dist/core/background-shell.d.ts +12 -1
  83. package/dist/core/background-shell.js +12 -0
  84. package/dist/core/checkpoint-requirements.d.ts +24 -3
  85. package/dist/core/checkpoint-requirements.js +9 -1
  86. package/dist/core/checkpoint-store.d.ts +86 -32
  87. package/dist/core/checkpoint-store.js +10 -5
  88. package/dist/core/child-clamp-seats.d.ts +3 -2
  89. package/dist/core/child-clamp-seats.js +4 -3
  90. package/dist/core/closest-name.d.ts +13 -0
  91. package/dist/core/closest-name.js +35 -0
  92. package/dist/core/compliance.d.ts +1 -1
  93. package/dist/core/context-settings.js +3 -5
  94. package/dist/core/credential-echo.d.ts +52 -0
  95. package/dist/core/credential-echo.js +65 -0
  96. package/dist/core/credential-vocabulary.d.ts +13 -3
  97. package/dist/core/credential-vocabulary.js +12 -4
  98. package/dist/core/cross-boundary-taint.d.ts +5 -6
  99. package/dist/core/decision-receipt.d.ts +14 -1
  100. package/dist/core/decision-receipt.js +6 -3
  101. package/dist/core/delegation-frames.d.ts +13 -9
  102. package/dist/core/effective-path-target.js +2 -3
  103. package/dist/core/engine-attestation.d.ts +11 -1
  104. package/dist/core/engine-attestation.js +2 -0
  105. package/dist/core/engine-notice.d.ts +106 -32
  106. package/dist/core/file-history-retention.d.ts +8 -0
  107. package/dist/core/file-history-retention.js +14 -11
  108. package/dist/core/file-history-store.d.ts +31 -1
  109. package/dist/core/file-history-store.js +31 -2
  110. package/dist/core/frame-settlement.d.ts +15 -0
  111. package/dist/core/frame-settlement.js +10 -1
  112. package/dist/core/fs-write-gate-policy.d.ts +3 -3
  113. package/dist/core/fs-write-gate-policy.js +8 -7
  114. package/dist/core/gate-fold.js +9 -6
  115. package/dist/core/gate-lanes.js +46 -12
  116. package/dist/core/gate-outcome.d.ts +40 -1
  117. package/dist/core/gate-outcome.js +10 -0
  118. package/dist/core/git-worktree-env.d.ts +7 -3
  119. package/dist/core/git-worktree-env.js +16 -13
  120. package/dist/core/governance-codes.d.ts +19 -3
  121. package/dist/core/governance-codes.js +27 -3
  122. package/dist/core/hands-band-screen.js +0 -1
  123. package/dist/core/hands-band.d.ts +0 -3
  124. package/dist/core/hooks.d.ts +51 -60
  125. package/dist/core/hooks.js +131 -78
  126. package/dist/core/host-floor.js +3 -5
  127. package/dist/core/image-admission.d.ts +145 -52
  128. package/dist/core/image-admission.js +202 -47
  129. package/dist/core/image-downsample.d.ts +36 -69
  130. package/dist/core/image-downsample.js +111 -73
  131. package/dist/core/input-author.d.ts +36 -0
  132. package/dist/core/input-author.js +39 -0
  133. package/dist/core/integer-option.d.ts +21 -0
  134. package/dist/core/integer-option.js +13 -0
  135. package/dist/core/leg-identity.d.ts +62 -0
  136. package/dist/core/leg-identity.js +18 -0
  137. package/dist/core/locked-config.d.ts +55 -3
  138. package/dist/core/locked-config.js +84 -51
  139. package/dist/core/lsp.d.ts +5 -3
  140. package/dist/core/lsp.js +3 -2
  141. package/dist/core/mailbox-store.d.ts +85 -10
  142. package/dist/core/mailbox-store.js +31 -10
  143. package/dist/core/mcp-call-meta.d.ts +2 -2
  144. package/dist/core/mcp-call-meta.js +9 -10
  145. package/dist/core/mcp-connection-pool.d.ts +6 -20
  146. package/dist/core/mcp-connection-pool.js +10 -28
  147. package/dist/core/mcp-failure.d.ts +83 -16
  148. package/dist/core/mcp-failure.js +67 -30
  149. package/dist/core/mcp-host-seat.d.ts +131 -0
  150. package/dist/core/mcp-host-seat.js +305 -0
  151. package/dist/core/mcp-probe.d.ts +7 -2
  152. package/dist/core/mcp-probe.js +9 -4
  153. package/dist/core/mcp-server-link.d.ts +18 -6
  154. package/dist/core/mcp-server-link.js +19 -4
  155. package/dist/core/mcp-server-spec.d.ts +39 -9
  156. package/dist/core/mcp-server-spec.js +55 -21
  157. package/dist/core/mcp-session-end.d.ts +1 -2
  158. package/dist/core/mcp-session-end.js +1 -1
  159. package/dist/core/mcp.d.ts +23 -55
  160. package/dist/core/mcp.js +172 -156
  161. package/dist/core/media-byte-cap.d.ts +21 -46
  162. package/dist/core/media-byte-cap.js +55 -55
  163. package/dist/core/member-group.d.ts +7 -0
  164. package/dist/core/member-group.js +35 -0
  165. package/dist/core/memory-admission.d.ts +23 -6
  166. package/dist/core/memory-admission.js +19 -9
  167. package/dist/core/memory-engine/consolidation.d.ts +1 -1
  168. package/dist/core/memory-engine/consolidation.js +7 -1
  169. package/dist/core/memory-engine/content-origin.d.ts +13 -0
  170. package/dist/core/memory-engine/content-origin.js +21 -3
  171. package/dist/core/memory-engine/dual-root.d.ts +31 -0
  172. package/dist/core/memory-engine/dual-root.js +59 -11
  173. package/dist/core/memory-engine/engine.js +27 -24
  174. package/dist/core/memory-engine/file-backend.d.ts +13 -0
  175. package/dist/core/memory-engine/file-backend.js +35 -15
  176. package/dist/core/memory-engine/index.d.ts +2 -1
  177. package/dist/core/memory-engine/index.js +2 -1
  178. package/dist/core/memory-engine/layout.d.ts +3 -0
  179. package/dist/core/memory-engine/layout.js +13 -3
  180. package/dist/core/memory-engine/memory-deployment.d.ts +110 -0
  181. package/dist/core/memory-engine/memory-deployment.js +182 -0
  182. package/dist/core/memory-engine/scope-contract.d.ts +13 -3
  183. package/dist/core/memory-engine/scope-contract.js +2 -2
  184. package/dist/core/memory-engine/sync-client.d.ts +68 -13
  185. package/dist/core/memory-engine/sync-client.js +147 -18
  186. package/dist/core/memory-engine/sync-report.d.ts +106 -0
  187. package/dist/core/memory-engine/sync-report.js +119 -0
  188. package/dist/core/memory-engine/sync.d.ts +13 -3
  189. package/dist/core/mode-policy.d.ts +15 -7
  190. package/dist/core/mode-policy.js +18 -6
  191. package/dist/core/model-receipt.d.ts +39 -0
  192. package/dist/core/model-receipt.js +139 -0
  193. package/dist/core/mods/agent-stations.d.ts +100 -0
  194. package/dist/core/mods/agent-stations.js +154 -0
  195. package/dist/core/mods/dollar.d.ts +62 -0
  196. package/dist/core/mods/extension-call.d.ts +15 -1
  197. package/dist/core/mods/extension-call.js +7 -2
  198. package/dist/core/mods/kernel/dispatch.d.ts +9 -4
  199. package/dist/core/mods/kernel/dispatch.js +8 -8
  200. package/dist/core/mods/kernel/events.d.ts +13 -4
  201. package/dist/core/mods/kernel/events.js +14 -10
  202. package/dist/core/mods/kernel/receive.d.ts +5 -0
  203. package/dist/core/mods/kernel/receive.js +10 -0
  204. package/dist/core/mods/kernel/registration.d.ts +3 -0
  205. package/dist/core/mods/kernel/registration.js +5 -0
  206. package/dist/core/mods/kernel/site-rules.d.ts +6 -3
  207. package/dist/core/mods/kernel/site-rules.js +10 -2
  208. package/dist/core/mods/lifecycle-stations.d.ts +41 -0
  209. package/dist/core/mods/lifecycle-stations.js +35 -0
  210. package/dist/core/mods/session-append.d.ts +115 -0
  211. package/dist/core/mods/session-append.js +311 -0
  212. package/dist/core/mods/session-compact.d.ts +48 -0
  213. package/dist/core/mods/session-compact.js +194 -0
  214. package/dist/core/mods/session-receive.d.ts +93 -0
  215. package/dist/core/mods/session-receive.js +141 -0
  216. package/dist/core/mods/session-send.d.ts +72 -0
  217. package/dist/core/mods/session-send.js +88 -0
  218. package/dist/core/mods/stations.d.ts +89 -75
  219. package/dist/core/mods/stations.js +57 -53
  220. package/dist/core/mods/tool-call.d.ts +12 -4
  221. package/dist/core/mods/tool-call.js +32 -16
  222. package/dist/core/mounted-mcp.d.ts +5 -0
  223. package/dist/core/mounted-mcp.js +2 -2
  224. package/dist/core/namespaced-rule-name.d.ts +7 -1
  225. package/dist/core/namespaced-rule-name.js +13 -2
  226. package/dist/core/oracle-isolation.js +1 -1
  227. package/dist/core/output-style.js +3 -4
  228. package/dist/core/own-property-receipt.d.ts +62 -0
  229. package/dist/core/own-property-receipt.js +43 -0
  230. package/dist/core/park-selfcheck.js +12 -10
  231. package/dist/core/path-identity.d.ts +11 -0
  232. package/dist/core/path-identity.js +4 -0
  233. package/dist/core/path-rule-binding.d.ts +3 -1
  234. package/dist/core/path-rule-binding.js +3 -1
  235. package/dist/core/peer-seat.d.ts +66 -11
  236. package/dist/core/peer-seat.js +199 -42
  237. package/dist/core/permission-rule-consent.d.ts +21 -26
  238. package/dist/core/permission-rule-consent.js +22 -3
  239. package/dist/core/permission-rule-model.d.ts +38 -13
  240. package/dist/core/permission-rule-model.js +54 -16
  241. package/dist/core/permission-rule-org.d.ts +1 -1
  242. package/dist/core/permission-rule-provider.js +4 -1
  243. package/dist/core/permission-rules.d.ts +4 -0
  244. package/dist/core/permission-rules.js +11 -16
  245. package/dist/core/protocol-http-auth.d.ts +14 -2
  246. package/dist/core/protocol-http-auth.js +16 -7
  247. package/dist/core/read-face-seats.d.ts +7 -5
  248. package/dist/core/read-face-seats.js +4 -1
  249. package/dist/core/redaction-marks.d.ts +4 -3
  250. package/dist/core/redaction-marks.js +2 -2
  251. package/dist/core/remote-env.d.ts +218 -122
  252. package/dist/core/remote-env.js +133 -14
  253. package/dist/core/retention-policy.d.ts +24 -23
  254. package/dist/core/retention-policy.js +36 -2
  255. package/dist/core/retention.d.ts +4 -1
  256. package/dist/core/retention.js +37 -12
  257. package/dist/core/retired-keys.d.ts +8 -3
  258. package/dist/core/retired-keys.js +4 -1
  259. package/dist/core/rewrite-rejudge.d.ts +12 -5
  260. package/dist/core/rewrite-rejudge.js +9 -5
  261. package/dist/core/roles.d.ts +37 -3
  262. package/dist/core/roles.js +126 -78
  263. package/dist/core/row-admission.d.ts +10 -0
  264. package/dist/core/row-admission.js +5 -0
  265. package/dist/core/rule-owner.d.ts +3 -0
  266. package/dist/core/runner/advisor-instructions.d.ts +2 -1
  267. package/dist/core/runner/advisor-instructions.js +2 -1
  268. package/dist/core/runner/announce-once-ledger.d.ts +4 -4
  269. package/dist/core/runner/assemble-result.d.ts +13 -8
  270. package/dist/core/runner/assemble-result.js +12 -8
  271. package/dist/core/runner/call-hook-stations.d.ts +17 -10
  272. package/dist/core/runner/call-hook-stations.js +21 -10
  273. package/dist/core/runner/caller-roster.d.ts +12 -9
  274. package/dist/core/runner/caller-roster.js +5 -2
  275. package/dist/core/runner/checkpoint-scope.d.ts +16 -1
  276. package/dist/core/runner/checkpoint-scope.js +21 -0
  277. package/dist/core/runner/child-tree.d.ts +7 -8
  278. package/dist/core/runner/child-tree.js +6 -6
  279. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  280. package/dist/core/runner/classifier-ladder.js +39 -8
  281. package/dist/core/runner/compact-session.js +14 -2
  282. package/dist/core/runner/compaction-call-options.d.ts +1 -1
  283. package/dist/core/runner/compaction-restate.d.ts +2 -2
  284. package/dist/core/runner/compaction-restate.js +4 -3
  285. package/dist/core/runner/construction-doors.d.ts +2 -2
  286. package/dist/core/runner/construction-doors.js +7 -2
  287. package/dist/core/runner/contracts.d.ts +158 -65
  288. package/dist/core/runner/cross-boundary-lane.d.ts +4 -6
  289. package/dist/core/runner/cross-boundary-lane.js +11 -2
  290. package/dist/core/runner/decide-continuation.d.ts +4 -2
  291. package/dist/core/runner/decide-continuation.js +7 -4
  292. package/dist/core/runner/denial-limit-arms.d.ts +15 -21
  293. package/dist/core/runner/denial-limit-arms.js +17 -10
  294. package/dist/core/runner/env-capability-census.d.ts +15 -20
  295. package/dist/core/runner/env-capability-census.js +25 -34
  296. package/dist/core/runner/expire-settle.d.ts +44 -0
  297. package/dist/core/runner/expire-settle.js +55 -0
  298. package/dist/core/runner/file-history-request.d.ts +2 -2
  299. package/dist/core/runner/file-history-request.js +0 -8
  300. package/dist/core/runner/gate-exit.d.ts +75 -7
  301. package/dist/core/runner/gate-exit.js +20 -1
  302. package/dist/core/runner/git-status-frame.d.ts +5 -2
  303. package/dist/core/runner/git-status-frame.js +4 -4
  304. package/dist/core/runner/halt-attribution.d.ts +2 -1
  305. package/dist/core/runner/halt-attribution.js +2 -1
  306. package/dist/core/runner/image.d.ts +7 -2
  307. package/dist/core/runner/image.js +14 -8
  308. package/dist/core/runner/inline-image.d.ts +10 -8
  309. package/dist/core/runner/inline-image.js +11 -9
  310. package/dist/core/runner/local-claims.d.ts +17 -0
  311. package/dist/core/runner/local-claims.js +18 -0
  312. package/dist/core/runner/media-removed-seat.d.ts +46 -0
  313. package/dist/core/runner/media-removed-seat.js +88 -0
  314. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  315. package/dist/core/runner/park-commit.d.ts +2 -2
  316. package/dist/core/runner/permission-rule-lanes.d.ts +5 -1
  317. package/dist/core/runner/permission-rule-lanes.js +29 -10
  318. package/dist/core/runner/person-path-rows.js +1 -1
  319. package/dist/core/runner/placement-fence.d.ts +26 -0
  320. package/dist/core/runner/placement-fence.js +38 -0
  321. package/dist/core/runner/prepare-ask-lane.d.ts +6 -12
  322. package/dist/core/runner/prepare-ask-lane.js +4 -4
  323. package/dist/core/runner/prepare-boundary-parks.d.ts +6 -3
  324. package/dist/core/runner/prepare-boundary-parks.js +4 -4
  325. package/dist/core/runner/prepare-caps-and-workflow.d.ts +6 -0
  326. package/dist/core/runner/prepare-caps-and-workflow.js +5 -3
  327. package/dist/core/runner/prepare-config-doors.d.ts +6 -1
  328. package/dist/core/runner/prepare-config-doors.js +30 -26
  329. package/dist/core/runner/prepare-context-lane.d.ts +6 -2
  330. package/dist/core/runner/prepare-context-lane.js +13 -13
  331. package/dist/core/runner/prepare-delegation-surface.d.ts +13 -11
  332. package/dist/core/runner/prepare-delegation-surface.js +7 -8
  333. package/dist/core/runner/prepare-execution-env.d.ts +5 -2
  334. package/dist/core/runner/prepare-execution-env.js +7 -4
  335. package/dist/core/runner/prepare-file-history.d.ts +10 -12
  336. package/dist/core/runner/prepare-file-history.js +3 -12
  337. package/dist/core/runner/prepare-gate-stations.d.ts +23 -17
  338. package/dist/core/runner/prepare-gate-stations.js +10 -7
  339. package/dist/core/runner/prepare-hands-readface.d.ts +8 -6
  340. package/dist/core/runner/prepare-hands-readface.js +19 -11
  341. package/dist/core/runner/prepare-inherited-gate.d.ts +11 -4
  342. package/dist/core/runner/prepare-inherited-gate.js +12 -5
  343. package/dist/core/runner/prepare-lsp.d.ts +3 -0
  344. package/dist/core/runner/prepare-lsp.js +2 -2
  345. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  346. package/dist/core/runner/prepare-memory.d.ts +2 -2
  347. package/dist/core/runner/prepare-memory.js +2 -2
  348. package/dist/core/runner/prepare-park-ask.d.ts +8 -7
  349. package/dist/core/runner/prepare-park-ask.js +6 -12
  350. package/dist/core/runner/prepare-policy-chain.d.ts +15 -25
  351. package/dist/core/runner/prepare-policy-chain.js +131 -128
  352. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  353. package/dist/core/runner/prepare-project-context.js +8 -5
  354. package/dist/core/runner/prepare-prompt-inputs.d.ts +4 -0
  355. package/dist/core/runner/prepare-prompt-inputs.js +4 -2
  356. package/dist/core/runner/prepare-protocol-tools.d.ts +5 -3
  357. package/dist/core/runner/prepare-protocol-tools.js +9 -2
  358. package/dist/core/runner/prepare-question-face.d.ts +6 -4
  359. package/dist/core/runner/prepare-question-face.js +2 -2
  360. package/dist/core/runner/prepare-run-refs.d.ts +3 -0
  361. package/dist/core/runner/prepare-run-refs.js +2 -2
  362. package/dist/core/runner/prepare-suspend-saga.d.ts +11 -9
  363. package/dist/core/runner/prepare-suspend-saga.js +21 -13
  364. package/dist/core/runner/prepare-task.d.ts +1 -1
  365. package/dist/core/runner/prepare-task.js +84 -42
  366. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +6 -0
  367. package/dist/core/runner/prepare-tool-disclosure-mount.js +3 -1
  368. package/dist/core/runner/prepare-turn-wiring.d.ts +2 -0
  369. package/dist/core/runner/prepare-turn-wiring.js +7 -2
  370. package/dist/core/runner/prepare-wiring-manifest.d.ts +7 -3
  371. package/dist/core/runner/prepare-wiring-manifest.js +34 -19
  372. package/dist/core/runner/prepare-workspace-restore.d.ts +5 -0
  373. package/dist/core/runner/prepare-workspace-restore.js +12 -8
  374. package/dist/core/runner/read-root-grant.d.ts +1 -1
  375. package/dist/core/runner/read-root-grant.js +2 -1
  376. package/dist/core/runner/resume-admission.d.ts +5 -3
  377. package/dist/core/runner/resume-admission.js +17 -3
  378. package/dist/core/runner/resume-apply.js +3 -1
  379. package/dist/core/runner/resume-checkpoint-screen.js +4 -4
  380. package/dist/core/runner/resume-claim.d.ts +8 -3
  381. package/dist/core/runner/resume-claim.js +28 -12
  382. package/dist/core/runner/resume-internals-and-config.d.ts +2 -2
  383. package/dist/core/runner/resume-internals-and-config.js +10 -1
  384. package/dist/core/runner/resume-preflight.d.ts +3 -2
  385. package/dist/core/runner/resume-preflight.js +13 -26
  386. package/dist/core/runner/retired-runner-deps.js +6 -1
  387. package/dist/core/runner/run-attachment-seats.js +3 -3
  388. package/dist/core/runner/run-brain-sinks.js +1 -0
  389. package/dist/core/runner/run-git-lane.d.ts +3 -1
  390. package/dist/core/runner/run-git-lane.js +3 -2
  391. package/dist/core/runner/run-harness-handlers.d.ts +3 -1
  392. package/dist/core/runner/run-harness-handlers.js +5 -3
  393. package/dist/core/runner/run-identity-wiring.d.ts +2 -2
  394. package/dist/core/runner/run-identity-wiring.js +15 -6
  395. package/dist/core/runner/run-leg.d.ts +3 -3
  396. package/dist/core/runner/run-leg.js +65 -56
  397. package/dist/core/runner/run-notification-lane.d.ts +3 -1
  398. package/dist/core/runner/run-notification-lane.js +36 -12
  399. package/dist/core/runner/run-recovery-lanes.js +3 -2
  400. package/dist/core/runner/run-settle-and-teardown.js +14 -8
  401. package/dist/core/runner/run-stop-and-final-verify.d.ts +4 -0
  402. package/dist/core/runner/run-stop-and-final-verify.js +12 -4
  403. package/dist/core/runner/run-telemetry-and-budget-seats.d.ts +1 -1
  404. package/dist/core/runner/run-terminal-adoption.d.ts +1 -1
  405. package/dist/core/runner/run-terminal-adoption.js +26 -17
  406. package/dist/core/runner/run-turn-boundary.js +37 -19
  407. package/dist/core/runner/runtask.d.ts +25 -7
  408. package/dist/core/runner/runtask.js +46 -22
  409. package/dist/core/runner/session-rule-policy.d.ts +1 -1
  410. package/dist/core/runner/session-rule-policy.js +6 -1
  411. package/dist/core/runner/shell-env-withheld.d.ts +1 -1
  412. package/dist/core/runner/skills-seat.js +2 -2
  413. package/dist/core/runner/stream-halt-verbs.d.ts +1 -14
  414. package/dist/core/runner/stream-halt-verbs.js +4 -3
  415. package/dist/core/runner/stream-reap.d.ts +7 -6
  416. package/dist/core/runner/stream-reap.js +13 -16
  417. package/dist/core/runner/stream-settle-backstop.d.ts +3 -2
  418. package/dist/core/runner/stream-settle-backstop.js +5 -3
  419. package/dist/core/runner/stream-steer-verb.d.ts +5 -2
  420. package/dist/core/runner/stream-steer-verb.js +8 -7
  421. package/dist/core/runner/sub-agent-deny-lists.js +10 -7
  422. package/dist/core/runner/synthetic-tools.js +2 -2
  423. package/dist/core/runner/terminal-account.d.ts +11 -1
  424. package/dist/core/runner/terminal-account.js +20 -0
  425. package/dist/core/runner/terminal-projection.d.ts +8 -2
  426. package/dist/core/runner/terminal-projection.js +2 -2
  427. package/dist/core/runner/tool-disclosure.d.ts +3 -0
  428. package/dist/core/runner/tool-disclosure.js +5 -4
  429. package/dist/core/runner/tool-end-body.d.ts +3 -3
  430. package/dist/core/runner/tool-end-body.js +1 -1
  431. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  432. package/dist/core/runner/tool-face-overlay.js +26 -19
  433. package/dist/core/runner/tool-output-projection.d.ts +3 -3
  434. package/dist/core/runner/tool-output-projection.js +7 -6
  435. package/dist/core/runner/tool-result-media-seat.d.ts +9 -1
  436. package/dist/core/runner/tool-result-media-seat.js +17 -1
  437. package/dist/core/runner/tool-table-view.d.ts +56 -0
  438. package/dist/core/runner/tool-table-view.js +51 -0
  439. package/dist/core/runner/turn-attachments.d.ts +6 -7
  440. package/dist/core/runner/turn-attachments.js +4 -17
  441. package/dist/core/runner/void-verifier-pause.d.ts +33 -0
  442. package/dist/core/runner/void-verifier-pause.js +41 -0
  443. package/dist/core/runner-deps.d.ts +55 -43
  444. package/dist/core/secret-env.d.ts +14 -13
  445. package/dist/core/secret-env.js +8 -9
  446. package/dist/core/session-log-transfer.js +9 -10
  447. package/dist/core/session-policy-store.d.ts +10 -3
  448. package/dist/core/session-policy-store.js +21 -3
  449. package/dist/core/session-reconcile.d.ts +3 -2
  450. package/dist/core/session-reconcile.js +7 -4
  451. package/dist/core/session-store.d.ts +5 -2
  452. package/dist/core/session-store.js +53 -16
  453. package/dist/core/session.d.ts +2 -1
  454. package/dist/core/shell-confinement.d.ts +37 -0
  455. package/dist/core/shell-confinement.js +56 -0
  456. package/dist/core/skill-grant.d.ts +9 -0
  457. package/dist/core/skill-grant.js +18 -0
  458. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +2 -2
  459. package/dist/core/store-contracts/checkpoint-store-contract.js +15 -2
  460. package/dist/core/store-contracts/file-history-store-contract.d.ts +5 -2
  461. package/dist/core/store-contracts/file-history-store-contract.js +25 -1
  462. package/dist/core/store-contracts/mailbox-store-contract.d.ts +12 -5
  463. package/dist/core/store-contracts/mailbox-store-contract.js +156 -9
  464. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  465. package/dist/core/store-contracts/tool-result-store-contract.js +67 -0
  466. package/dist/core/stub-env.d.ts +5 -5
  467. package/dist/core/stub-env.js +11 -1
  468. package/dist/core/swappable-deps.d.ts +17 -43
  469. package/dist/core/swappable-deps.js +15 -5
  470. package/dist/core/synthetic-read-verdict.d.ts +1 -1
  471. package/dist/core/task-event.d.ts +35 -10
  472. package/dist/core/task-limits.d.ts +5 -0
  473. package/dist/core/task-notification.d.ts +172 -12
  474. package/dist/core/task-notification.js +209 -12
  475. package/dist/core/task-registry-agent.d.ts +23 -55
  476. package/dist/core/task-registry-agent.js +41 -56
  477. package/dist/core/task-registry-monitor.d.ts +8 -1
  478. package/dist/core/task-registry-monitor.js +43 -61
  479. package/dist/core/task-registry-shared.d.ts +52 -114
  480. package/dist/core/task-registry-shared.js +24 -48
  481. package/dist/core/task-registry-workflow.js +5 -22
  482. package/dist/core/task-registry.d.ts +64 -90
  483. package/dist/core/task-registry.js +73 -119
  484. package/dist/core/task-result.d.ts +27 -19
  485. package/dist/core/task-spec-members.d.ts +39 -0
  486. package/dist/core/task-spec-members.js +92 -0
  487. package/dist/core/task-spec.d.ts +13 -16
  488. package/dist/core/task-stream.d.ts +1 -1
  489. package/dist/core/task-tool-shape.d.ts +7 -57
  490. package/dist/core/task-tool-shape.js +7 -66
  491. package/dist/core/terminal-cause.d.ts +30 -0
  492. package/dist/core/terminal-cause.js +1 -0
  493. package/dist/core/tool-catalog-entries.js +3 -6
  494. package/dist/core/tool-check-reading.js +16 -10
  495. package/dist/core/tool-conformance.js +1 -2
  496. package/dist/core/tool-errors.d.ts +6 -3
  497. package/dist/core/tool-errors.js +2 -0
  498. package/dist/core/tool-face-reader.d.ts +7 -6
  499. package/dist/core/tool-face-reader.js +6 -4
  500. package/dist/core/tool-face.d.ts +2 -3
  501. package/dist/core/tool-name-aliases.d.ts +23 -28
  502. package/dist/core/tool-name-aliases.js +63 -7
  503. package/dist/core/tool-name-readings.d.ts +14 -3
  504. package/dist/core/tool-name-readings.js +2 -0
  505. package/dist/core/tool-policy.d.ts +113 -22
  506. package/dist/core/tool-policy.js +85 -15
  507. package/dist/core/tool-registry.d.ts +5 -5
  508. package/dist/core/tool-registry.js +2 -2
  509. package/dist/core/tool-result-store.d.ts +111 -5
  510. package/dist/core/tool-result-store.js +52 -12
  511. package/dist/core/tool-spec.d.ts +39 -10
  512. package/dist/core/trace.d.ts +18 -2
  513. package/dist/core/types.d.ts +3 -3
  514. package/dist/core/types.js +1 -1
  515. package/dist/core/untrusted-text.js +1 -1
  516. package/dist/core/user-attachment.d.ts +10 -5
  517. package/dist/core/user-attachment.js +40 -27
  518. package/dist/core/workflow-journal-store.d.ts +1 -1
  519. package/dist/core/workflow-run-store.d.ts +2 -0
  520. package/dist/core/workflow-run-store.js +6 -5
  521. package/dist/core/workflow-settled-run.d.ts +5 -0
  522. package/dist/core/workflow-settled-run.js +7 -0
  523. package/dist/engine/execution-env/node-execution-env.d.ts +37 -7
  524. package/dist/engine/execution-env/node-execution-env.js +224 -21
  525. package/dist/engine/harness/agent-harness.d.ts +66 -19
  526. package/dist/engine/harness/agent-harness.js +98 -27
  527. package/dist/engine/harness/messages.d.ts +4 -3
  528. package/dist/engine/harness/messages.js +2 -2
  529. package/dist/engine/harness/types.d.ts +151 -34
  530. package/dist/engine/llm/media-removed.d.ts +14 -0
  531. package/dist/engine/llm/media-removed.js +9 -0
  532. package/dist/engine/llm/rejected-images.d.ts +35 -25
  533. package/dist/engine/llm/rejected-images.js +59 -10
  534. package/dist/engine/llm/types.d.ts +24 -3
  535. package/dist/engine/llm/types.js +7 -3
  536. package/dist/engine/loop/agent-loop.d.ts +18 -13
  537. package/dist/engine/loop/agent-loop.js +173 -32
  538. package/dist/engine/loop/types.d.ts +21 -5
  539. package/dist/engine/lsp/node-lsp-manager.d.ts +3 -3
  540. package/dist/engine/lsp/node-lsp-manager.js +32 -13
  541. package/dist/engine/session/import-validate.js +7 -0
  542. package/dist/fixtures/index.d.ts +7 -5
  543. package/dist/fixtures/index.js +5 -3
  544. package/dist/index.d.ts +41 -23
  545. package/dist/index.js +29 -16
  546. package/dist/internal/harness-types.d.ts +3 -1
  547. package/dist/internal/llm.d.ts +2 -1
  548. package/dist/internal/llm.js +1 -0
  549. package/dist/orchestration/goal.d.ts +6 -2
  550. package/dist/orchestration/goal.js +6 -3
  551. package/dist/orchestration/run-workflow-tool.d.ts +20 -20
  552. package/dist/orchestration/run-workflow-tool.js +63 -56
  553. package/dist/orchestration/workflow-governance.d.ts +1 -1
  554. package/dist/orchestration/workflow-governance.js +2 -1
  555. package/dist/orchestration/workflow-types.d.ts +2 -2
  556. package/dist/orchestration/workflow.d.ts +8 -0
  557. package/dist/orchestration/workflow.js +33 -9
  558. package/dist/prompts/default.d.ts +1 -10
  559. package/dist/prompts/default.js +0 -2
  560. package/dist/stores/file/background-agent-store.d.ts +1 -1
  561. package/dist/stores/file/background-agent-store.js +19 -14
  562. package/dist/stores/file/checkpoint-store.d.ts +127 -2
  563. package/dist/stores/file/checkpoint-store.js +24 -16
  564. package/dist/stores/file/file-history-store.d.ts +1 -1
  565. package/dist/stores/file/file-history-store.js +4 -1
  566. package/dist/stores/file/index.d.ts +9 -6
  567. package/dist/stores/file/index.js +33 -9
  568. package/dist/stores/file/ledger-tuning.d.ts +23 -0
  569. package/dist/stores/file/ledger-tuning.js +21 -0
  570. package/dist/stores/file/mailbox-store.d.ts +1 -1
  571. package/dist/stores/file/mailbox-store.js +43 -21
  572. package/dist/stores/file/memory-store.d.ts +1 -1
  573. package/dist/stores/file/memory-store.js +4 -1
  574. package/dist/stores/file/permission-rule-adopt.js +24 -21
  575. package/dist/stores/file/permission-rule-store.js +6 -3
  576. package/dist/stores/file/session-policy-store.d.ts +1 -1
  577. package/dist/stores/file/session-policy-store.js +4 -1
  578. package/dist/stores/file/session-store.d.ts +17 -4
  579. package/dist/stores/file/session-store.js +22 -19
  580. package/dist/stores/file/shared-ledger.d.ts +26 -0
  581. package/dist/stores/file/shared-ledger.js +38 -9
  582. package/dist/stores/file/tool-result-store.d.ts +31 -2
  583. package/dist/stores/file/tool-result-store.js +129 -7
  584. package/dist/stores/file/usage-window-store.d.ts +1 -1
  585. package/dist/stores/file/usage-window-store.js +4 -1
  586. package/dist/stores/file/workflow-journal-store.d.ts +1 -13
  587. package/dist/stores/file/workflow-journal-store.js +4 -18
  588. package/dist/stores/file/workflow-run-store.d.ts +1 -1
  589. package/dist/stores/file/workflow-run-store.js +15 -10
  590. package/dist/tools/fs/containment-face.d.ts +5 -0
  591. package/dist/tools/fs/dead-cwd.d.ts +5 -5
  592. package/dist/tools/fs/dead-cwd.js +4 -11
  593. package/dist/tools/fs/encoding.d.ts +13 -4
  594. package/dist/tools/fs/encoding.js +17 -2
  595. package/dist/tools/fs/fs-bash-background-text.d.ts +13 -0
  596. package/dist/tools/fs/fs-bash-background-text.js +7 -0
  597. package/dist/tools/fs/fs-bash.d.ts +11 -22
  598. package/dist/tools/fs/fs-bash.js +58 -154
  599. package/dist/tools/fs/fs-pdf.d.ts +2 -2
  600. package/dist/tools/fs/fs-pdf.js +34 -27
  601. package/dist/tools/fs/fs-read.d.ts +5 -4
  602. package/dist/tools/fs/fs-read.js +35 -18
  603. package/dist/tools/fs/fs-search-tools.js +4 -1
  604. package/dist/tools/fs/fs-shared.d.ts +39 -16
  605. package/dist/tools/fs/fs-shared.js +25 -6
  606. package/dist/tools/fs/fs-write.js +5 -5
  607. package/dist/tools/fs/index.d.ts +15 -9
  608. package/dist/tools/fs/index.js +12 -18
  609. package/dist/tools/fs/pdf.d.ts +4 -4
  610. package/dist/tools/fs/pdf.js +6 -6
  611. package/dist/tools/fs/read-deny-home.js +8 -1
  612. package/dist/tools/fs/read-deny.d.ts +26 -2
  613. package/dist/tools/fs/read-deny.js +9 -2
  614. package/dist/tools/fs/read-floor.d.ts +57 -6
  615. package/dist/tools/fs/read-floor.js +241 -2
  616. package/dist/tools/fs/removal-targets.d.ts +9 -4
  617. package/dist/tools/fs/removal-targets.js +17 -9
  618. package/dist/tools/fs/search.d.ts +6 -5
  619. package/dist/tools/fs/search.js +10 -10
  620. package/dist/tools/fs/shell-read-establish.js +3 -1
  621. package/dist/tools/fs/shell-read-identity.d.ts +3 -1
  622. package/dist/tools/fs/shell-read-identity.js +4 -2
  623. package/dist/tools/fs/shell-read-judge.d.ts +7 -1
  624. package/dist/tools/fs/shell-read-judge.js +1 -1
  625. package/dist/tools/monitor.d.ts +12 -10
  626. package/dist/tools/monitor.js +22 -13
  627. package/dist/tools/scheduler-tools.js +42 -4
  628. package/dist/tools/web.d.ts +0 -10
  629. package/dist/tools/web.js +1 -4
  630. package/dist/tools/worktree.d.ts +5 -1
  631. package/dist/tools/worktree.js +20 -17
  632. package/package.json +8 -3
  633. package/test/export-surface.snapshot.json +166 -30
  634. package/wire-changes/core-stores-sql@7.60.0.json +30 -0
  635. package/wire-changes/core-stores-sql@7.61.0.json +480 -0
  636. package/wire-changes/core@7.60.0.json +3274 -0
  637. package/wire-changes/core@7.61.0.json +4405 -0
  638. package/wire-changes/mods-kernel@7.60.0.json +62 -0
  639. package/wire-changes/mods-kernel@7.61.0.json +65 -0
  640. package/wire-changes/primitives@7.60.0.json +30 -0
  641. package/wire-changes/primitives@7.61.0.json +30 -0
  642. package/dist/core/runner/image-removed-seat.d.ts +0 -12
  643. package/dist/core/runner/image-removed-seat.js +0 -19
@@ -2,23 +2,21 @@ import { randomBytes } from "node:crypto";
2
2
  import { Type } from "typebox";
3
3
  import { defineTool, errorResult } from "../../core/tools.js";
4
4
  import { isTimeCutCode } from "../../internal/harness.js";
5
- import { defaultTaskRegistry } from "../../core/task-registry.js";
6
- import { accountDroppedBytes, spoolDropNote } from "../../core/task-registry-shared.js";
7
5
  import { RollingTailBuffer } from "../../core/exec-output-tail.js";
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";
6
+ import { createBackgroundOutputFile, envDeclaresRetain, hasBackgroundShell, retainsBackgroundProcesses } from "../../core/background-shell.js";
10
7
  import { delimitUntrusted } from "../../core/untrusted-text.js";
11
- import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
8
+ import { resolveImageProcessor } from "../../core/image-downsample.js";
12
9
  import { withinAnyRoot } from "./safety.js";
13
- import { imageMagicMatches } from "../../core/image-admission.js";
10
+ import { admitImageBytes, sniffImageMime } from "../../core/image-admission.js";
14
11
  import { isDeadCwd, diagnoseDeadCwd } from "./dead-cwd.js";
15
12
  import { boundaryIsTheSandbox, hasDestroy, isIsolated } from "../../core/remote-env.js";
16
13
  import { ghRateLimitHint } from "./gh-rate-limit.js";
17
- import { backgroundLifetimeNote } from "./fs-bash-background-text.js";
18
- import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, CWD_SENTINEL, stripCwdSentinel, } from "./fs-shared.js";
14
+ import { backgroundLifetimeNote, backgroundOutputFileNote, BASH_BACKGROUND_UNAVAILABLE, ONE_SHOT_BACKGROUND_COMMAND_NOTE } from "./fs-bash-background-text.js";
15
+ import { admitsBackgroundLaunch, resolveCompletionSink } from "../../core/task-notification.js";
16
+ import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, zeroOutputSentence, CWD_SENTINEL, stripCwdSentinel, } from "./fs-shared.js";
19
17
  import { bashClassifyDefaultAllow, BASH_READONLY_DEFAULT_ALLOW, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed, parseLeadingCommandName } from "./bash-readonly-classifier.js";
20
18
  import { readOnlyShellVerdict } from "../../core/read-only-shell.js";
21
- import { mountRuleFace, toolFace } from "../../core/tool-catalog-entries.js";
19
+ import { toolFace } from "../../core/tool-catalog-entries.js";
22
20
  import { argvOf, compoundValueHidesRun, expansionHidesRun, expansionsInHeredocBody, lexShell } from "../../shell/lex.js";
23
21
  import { arithmeticAssignedNames } from "./shell-read-bindings.js";
24
22
  import { thrownText } from "../../core/thrown-value.js";
@@ -92,20 +90,17 @@ export function bashExitOneInterpretation(command) {
92
90
  }
93
91
  return EXIT1_INTERPRETATION[name];
94
92
  }
95
- function dataUriImageFromStdout(stdout) {
93
+ async function dataUriImageFromStdout(stdout, imageProcessor) {
96
94
  const t = stdout.trim();
97
95
  const m = /^data:image\/[a-z0-9.+_-]+;base64,([A-Za-z0-9+/=\s]+)$/i.exec(t);
98
96
  if (!m)
99
97
  return undefined;
100
- const data = m[1].replace(/\s/g, "");
101
- if (data.length === 0 || data.length > MCP_IMAGE_MAX_BASE64)
98
+ const bytes = Buffer.from(m[1].replace(/\s/g, ""), "base64");
99
+ const mime = sniffImageMime(bytes);
100
+ if (mime === undefined)
102
101
  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;
102
+ const admitted = await admitImageBytes(bytes, mime, await resolveImageProcessor(imageProcessor));
103
+ return admitted.ok ? admitted.block : undefined;
109
104
  }
110
105
  const AUTO_BACKGROUND_BLOCKED_FIRST_WORDS = new Set(["sleep"]);
111
106
  function pastAutoBackgroundWrapperPrefixes(words) {
@@ -292,7 +287,7 @@ function startLivenessTicks(onTick, filterStderr) {
292
287
  stop: () => clearInterval(timer),
293
288
  };
294
289
  }
295
- async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, cwdRef, detach, readOnly, containmentRoots, onTick, readFloor) {
290
+ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, cwdRef, detach, readOnly, containmentRoots, onTick, readFloor, imageProcessor) {
296
291
  const requestedSec = Math.max(1, Math.floor(timeoutSec ?? caps.defaultSec));
297
292
  let timeout = Math.min(caps.maxSec, requestedSec);
298
293
  const cappedByMaxTimeout = requestedSec > caps.maxSec;
@@ -379,14 +374,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
379
374
  const captured = (pStdout ? `--- partial stdout ---\n${pStdout}` : "") +
380
375
  (pStderr ? `${pStdout ? "\n" : ""}--- partial stderr ---\n${pStderr}` : "");
381
376
  const zeroOutput = captured.length === 0;
382
- const zeroOutputHint = res.error.code === "liveness_no_output"
383
- ? ` — the process wrote nothing to its stdio for ${noOutputSec !== undefined ? `the whole ${noOutputSec}s window` : "the whole window"}; it may have been stalled before producing output, or holding it in a block buffer`
384
- : res.error.code === "timeout" && timeout >= 60
385
- ? ` — the process ran the full ${timeout}s without writing to its stdio; it may have been stalled before producing output, or holding it in a block buffer`
386
- : "";
387
- const body = !zeroOutput
388
- ? `\n${delimitUntrusted("partial command output", captured)}`
389
- : `\n(no output was produced before the cutoff${zeroOutputHint})`;
377
+ const body = !zeroOutput ? `\n${delimitUntrusted("partial command output", captured)}` : `\n${zeroOutputSentence(res.error, timeout, noOutputSec)}`;
390
378
  const overflowNote = cutOverflowFile !== undefined ? shellRecoveryHint(cutOverflowFile, readOnly) : "";
391
379
  return {
392
380
  content: `Error (${toolName}): ${headline}${body}${overflowNote}`,
@@ -449,13 +437,13 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
449
437
  : "";
450
438
  const clippedStdout = clipShellOutput(stdout);
451
439
  const clippedStderr = clipShellOutput(stderr);
452
- const stdoutImage = dataUriImageFromStdout(stdout);
440
+ const stdoutImage = await dataUriImageFromStdout(stdout, imageProcessor);
453
441
  if (stdoutImage) {
454
442
  const imgOverflowFile = stderr.length > bashMaxOutputChars() ? await writeShellOverflowFile(env, "", stderr) : undefined;
455
443
  const imgOverflowNote = imgOverflowFile !== undefined ? shellRecoveryHint(imgOverflowFile, readOnly) : "";
456
444
  return {
457
445
  content: [
458
- { type: "image", data: stdoutImage.data, mimeType: stdoutImage.mime },
446
+ stdoutImage,
459
447
  { 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}` : ""}` },
460
448
  ],
461
449
  details: { type: "bash", stdout: "[image data]", stderr: clippedStderr, exitCode, isImage: true, ...(imgOverflowFile !== undefined ? { output_file: imgOverflowFile } : {}), ...(cappedByMaxTimeout ? { requestedTimeoutSec: requestedSec, cappedToMaxTimeoutSec: caps.maxSec } : {}) },
@@ -486,17 +474,16 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
486
474
  },
487
475
  };
488
476
  }
489
- function bashDescription(coAuthor, caps, bgNotifies = false, bgRetained = false, bgSessionScoped = false, bgEnvIsolatedOwned = false) {
477
+ function bashDescription(coAuthor, caps, bgOffered = false, bgRetained = false, bgSessionScoped = false, bgEnvIsolatedOwned = false) {
490
478
  const coAuthorLines = coAuthor === false
491
479
  ? "- Follow the deployment's commit-message conventions."
492
480
  : `- End git commit messages with:\nCo-Authored-By: ${coAuthor}`;
493
481
  return `Executes a bash command and returns its output.
494
482
 
495
- - 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.
483
+ - 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.
496
484
  - 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.
497
485
  - File search by name: use the Glob tool (NOT \`find\` or \`ls\`); content search: use the Grep tool (NOT \`grep\`/\`rg\` in the shell).
498
- - \`timeout\` is in milliseconds: default ${caps.defaultMs}, max ${caps.maxMs}.
499
- - \`run_in_background\` runs the command detached: it keeps running across turns and ${bgNotifies ? "re-invokes you when it exits" : "you read its output later with TaskOutput(task_id)"}. No \`&\` needed.${backgroundLifetimeNote(bgRetained, bgSessionScoped, bgEnvIsolatedOwned, "description")}
486
+ - \`timeout\` is in milliseconds: default ${caps.defaultMs}, max ${caps.maxMs}.${bgOffered ? `\n- \`run_in_background\` runs the command detached: it keeps running across turns and re-invokes you when it exits. No \`&\` needed.${backgroundLifetimeNote(bgRetained, bgSessionScoped, bgEnvIsolatedOwned, "description")}` : ""}
500
487
 
501
488
  # Git
502
489
  - Interactive flags (\`-i\`, e.g. \`git rebase -i\`, \`git add -i\`) are not supported in this environment.
@@ -509,19 +496,12 @@ ${coAuthorLines}
509
496
  - 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.`;
510
497
  }
511
498
  async function adoptBackgroundShell(req) {
512
- const { env, shellId, registry, description, toolUseId, ctxTaskId, ctxPrincipal, wiring } = req;
499
+ const { env, shellId, registry, description, toolUseId, ctxTaskId, ctxPrincipal, ctxTaskArtifacts, wiring } = req;
513
500
  const sessionScoped = wiring.sessionId !== undefined;
514
501
  const owner = sessionScoped ? wiring.sessionId : (ctxTaskId ?? wiring.taskOwner);
515
502
  const scope = ctxPrincipal ?? wiring.taskScope;
516
503
  const onNotify = wiring.onNotify;
517
- let outputFile;
518
- if (onNotify !== undefined) {
519
- const tf = await env.createTempFile({ prefix: "bash-task-", suffix: ".output" });
520
- if (tf.ok) {
521
- const tfCanon = await env.canonicalPath(tf.value);
522
- outputFile = tfCanon.ok ? tfCanon.value : tf.value;
523
- }
524
- }
504
+ const outputFile = await createBackgroundOutputFile(env, "bash-task-");
525
505
  try {
526
506
  const taskId = registry.registerBackgroundBash({
527
507
  env,
@@ -532,7 +512,8 @@ async function adoptBackgroundShell(req) {
532
512
  ...(scope !== undefined ? { scope } : {}),
533
513
  ...(sessionScoped ? { sessionScoped: true } : {}),
534
514
  ...(outputFile !== undefined ? { outputFile } : {}),
535
- ...(onNotify !== undefined ? { onTerminal: (n) => onNotify(n, { priority: "next" }) } : {}),
515
+ ...(ctxTaskArtifacts !== undefined ? { taskArtifacts: ctxTaskArtifacts } : {}),
516
+ onTerminal: (n) => onNotify(n, { priority: "next" }),
536
517
  ...(wiring.retainBackgroundProcesses !== undefined ? { retainBackgroundProcesses: wiring.retainBackgroundProcesses } : {}),
537
518
  });
538
519
  return { ok: true, taskId, outputFile };
@@ -554,14 +535,14 @@ async function adoptBackgroundShell(req) {
554
535
  export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = { current: rootCanonical }, taskOpts = {}) {
555
536
  const timeoutCaps = resolveBashTimeoutCaps(taskOpts);
556
537
  const timeoutCapsSecView = bashTimeoutCapsSec(timeoutCaps);
557
- const bgNotifies = taskOpts.taskRegistry !== undefined && taskOpts.onTaskNotification !== undefined;
538
+ const bgOffered = hasBackgroundShell(env) && taskOpts.taskRegistry !== undefined;
558
539
  const bgRetained = hasBackgroundShell(env) && retainsBackgroundProcesses({ env: envDeclaresRetain(env), task: taskOpts.retainBackgroundProcesses === true });
559
540
  const bgSessionScoped = taskOpts.sessionId !== undefined && taskOpts.taskRegistry !== undefined;
560
541
  const bgEnvIsolatedOwned = hasDestroy(env) && isIsolated(env);
561
542
  return defineTool({
562
543
  name: "Bash",
563
544
  ...toolFace("bash"),
564
- description: bashDescription(coAuthor, timeoutCaps, bgNotifies, bgRetained, bgSessionScoped, bgEnvIsolatedOwned),
545
+ description: bashDescription(coAuthor, timeoutCaps, bgOffered, bgRetained, bgSessionScoped, bgEnvIsolatedOwned),
565
546
  parameters: Type.Object({
566
547
  command: Type.String({ description: "The command to execute" }),
567
548
  timeout: Type.Optional(Type.Number({ description: bashTimeoutParamDescription(timeoutCaps, false) })),
@@ -578,9 +559,13 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
578
559
  '- git reset --hard origin/main → "Discard all local changes and match remote main"\n' +
579
560
  "- curl -s url | jq '.data[]' → \"Fetch JSON from URL and extract data array elements\"",
580
561
  })),
581
- run_in_background: Type.Optional(Type.Boolean({
582
- description: "Set to true to run this command in the background.",
583
- })),
562
+ ...(bgOffered
563
+ ? {
564
+ run_in_background: Type.Optional(Type.Boolean({
565
+ description: "Set to true to run this command in the background.",
566
+ })),
567
+ }
568
+ : {}),
584
569
  }),
585
570
  isConcurrencySafe: (args) => {
586
571
  const command = shellCommandOf(args);
@@ -597,9 +582,10 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
597
582
  if (refused !== undefined)
598
583
  return refused;
599
584
  if (run_in_background) {
600
- if (!hasBackgroundShell(env)) {
601
- return errorResult("Error (Bash): this environment does not support background processes (run_in_background).");
602
- }
585
+ const registry = taskOpts.taskRegistry;
586
+ const onNotify = resolveCompletionSink(ctx.onTaskNotification, taskOpts.onTaskNotification);
587
+ if (!hasBackgroundShell(env) || registry === undefined || !admitsBackgroundLaunch(onNotify))
588
+ return errorResult(BASH_BACKGROUND_UNAVAILABLE);
603
589
  if (cwdRef && (await isDeadCwd(env, cwdRef.current, ctx.signal))) {
604
590
  const diagnosis = await diagnoseDeadCwd(env, "Bash", cwdRef.current, rootCanonical, cwdRef, ctx.signal);
605
591
  if (diagnosis !== undefined)
@@ -627,9 +613,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
627
613
  : ` Time budget: the process may run up to ${appliedTimeoutSec}s (hard cap ${bgCaps.maxBgTimeoutSec}s).`
628
614
  : "";
629
615
  const lifetimeNote = backgroundLifetimeNote(bgRetained, bgSessionScoped, bgEnvIsolatedOwned);
630
- const registry = taskOpts.taskRegistry;
631
- if (registry !== undefined) {
632
- const onNotify = taskOpts.onTaskNotification;
616
+ {
633
617
  const adopted = await adoptBackgroundShell({
634
618
  env,
635
619
  shellId: r.value.shellId,
@@ -638,6 +622,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
638
622
  toolUseId: ctx.toolCallId,
639
623
  ctxTaskId: ctx.taskId,
640
624
  ctxPrincipal: ctx.principal,
625
+ ctxTaskArtifacts: ctx.taskArtifacts,
641
626
  wiring: { sessionId: taskOpts.sessionId, taskOwner: taskOpts.taskOwner, taskScope: taskOpts.taskScope, onNotify, retainBackgroundProcesses: taskOpts.retainBackgroundProcesses },
642
627
  });
643
628
  if (!adopted.ok) {
@@ -646,37 +631,22 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
646
631
  }
647
632
  return {
648
633
  content: `Error (Bash): background process was started but could not be registered (${adopted.reason}), and the cleanup kill failed (${adopted.killMsg}). ` +
649
- `The process could NOT be terminated — it may still be running, but it has no task_id, so TaskOutput/TaskStop cannot reach it. ` +
634
+ `The process could NOT be terminated — it may still be running, but it has no task_id, so TaskStop cannot reach it and no completion will arrive. ` +
650
635
  `If it must be stopped, kill it manually (e.g. \`pkill -f\` on its command line).`,
651
636
  details: { type: "bash", registerFailed: true, killFailed: true },
652
637
  isError: true,
653
638
  };
654
639
  }
655
640
  const { taskId, outputFile } = adopted;
656
- const interimNote = outputFile !== undefined
657
- ? ` Output file: ${outputFile} (full output is appended there — Read it any time).`
658
- : ` Use TaskOutput("${taskId}") to check interim output.`;
659
- if (taskOpts.oneShot === true && onNotify !== undefined) {
660
- 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.` +
661
- budgetNote +
662
- lifetimeNote);
641
+ const interimNote = backgroundOutputFileNote(outputFile);
642
+ if (taskOpts.oneShot === true) {
643
+ return `Command running in background; task_id=${taskId}.${interimNote} ${ONE_SHOT_BACKGROUND_COMMAND_NOTE} TaskStop("${taskId}") to stop.` + budgetNote + lifetimeNote;
663
644
  }
664
- return onNotify !== undefined
665
- ? `Command running in background; task_id=${taskId}.${interimNote} You will be notified when it completes — do not poll; ` +
666
- `end your turn if nothing else is pending. TaskStop("${taskId}") to stop.` +
667
- budgetNote +
668
- lifetimeNote
669
- : `Started in background; task_id=${taskId}. ` +
670
- `Use TaskOutput("${taskId}") to read output (poll until status is no longer "running"); ` +
671
- `TaskStop("${taskId}") to stop. No '&' needed.` +
672
- budgetNote +
673
- lifetimeNote;
645
+ return (`Command running in background; task_id=${taskId}.${interimNote} You will be notified when it completes — do not poll; ` +
646
+ `end your turn if nothing else is pending. TaskStop("${taskId}") to stop.` +
647
+ budgetNote +
648
+ lifetimeNote);
674
649
  }
675
- return (`Started in background; task_id=${r.value.shellId}. ` +
676
- `Use TaskOutput("${r.value.shellId}") to read output (poll until status is no longer "running"); ` +
677
- `TaskStop("${r.value.shellId}") to stop. No '&' needed.` +
678
- budgetNote +
679
- lifetimeNote);
680
650
  }
681
651
  const detachHub = taskOpts.detachHub;
682
652
  const detachRegistry = taskOpts.taskRegistry;
@@ -697,11 +667,12 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
697
667
  detachHub.request(ctx.toolCallId);
698
668
  };
699
669
  const detachEnv = hasBackgroundShell(env) ? env : undefined;
700
- const detachChain = detachHub !== undefined && detachRegistry !== undefined && detachEnv !== undefined && detachEnv.backgroundCapabilities.supportsDetach === true
670
+ const detachSink = resolveCompletionSink(ctx.onTaskNotification, taskOpts.onTaskNotification);
671
+ const detachChain = detachHub !== undefined && detachRegistry !== undefined && detachEnv !== undefined && admitsBackgroundLaunch(detachSink) && detachEnv.backgroundCapabilities.supportsDetach === true
701
672
  ? {
702
673
  signal: detachHub.signalFor(ctx.toolCallId),
703
674
  onDetached: async (shellId, stdoutSoFar, stderrSoFar, cause) => {
704
- const onNotify = taskOpts.onTaskNotification;
675
+ const onNotify = detachSink;
705
676
  const adopted = await adoptBackgroundShell({
706
677
  env: detachEnv,
707
678
  shellId: shellId,
@@ -710,6 +681,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
710
681
  toolUseId: ctx.toolCallId,
711
682
  ctxTaskId: ctx.taskId,
712
683
  ctxPrincipal: ctx.principal,
684
+ ctxTaskArtifacts: ctx.taskArtifacts,
713
685
  wiring: { sessionId: taskOpts.sessionId, taskOwner: taskOpts.taskOwner, taskScope: taskOpts.taskScope, onNotify, retainBackgroundProcesses: taskOpts.retainBackgroundProcesses },
714
686
  });
715
687
  if (!adopted.ok) {
@@ -728,7 +700,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
728
700
  }
729
701
  return {
730
702
  content: `Error (Bash): command was detached to the background but could not be registered (${adopted.reason}), and the cleanup kill failed (${adopted.killMsg}). ` +
731
- `The process could NOT be terminated — it may still be running, but it has no task_id, so TaskOutput/TaskStop cannot reach it. ` +
703
+ `The process could NOT be terminated — it may still be running, but it has no task_id, so TaskStop cannot reach it and no completion will arrive. ` +
732
704
  `If it must be stopped, kill it manually (e.g. \`pkill -f\` on its command line).` +
733
705
  tails,
734
706
  details: { type: "bash", detached: true, registerFailed: true, killFailed: true },
@@ -747,16 +719,11 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
747
719
  : backgroundedForQueuedMessage
748
720
  ? `Command is still running and was moved to the background so a queued message could be delivered without waiting for it (task_id=${taskId}). It was NOT stopped and nothing about it failed. `
749
721
  : `Command moved to background; task_id=${taskId}. `) +
750
- (outputFile !== undefined
751
- ? `Output file: ${outputFile} (full output is appended there — Read it any time). `
752
- : `Use TaskOutput("${taskId}") to read its output. `) +
722
+ `${backgroundOutputFileNote(outputFile).trimStart()} ` +
753
723
  `TaskStop("${taskId}") to stop it. ` +
754
- (taskOpts.oneShot === true && onNotify !== undefined
755
- ?
756
- `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 }).`
757
- : onNotify !== undefined
758
- ? `You will be notified when it completes — do not poll.`
759
- : `Poll TaskOutput until its status is no longer "running".`) +
724
+ (taskOpts.oneShot === true
725
+ ? ONE_SHOT_BACKGROUND_COMMAND_NOTE
726
+ : `You will be notified when it completes — do not poll.`) +
760
727
  adoptBudgetNote +
761
728
  backgroundLifetimeNote(bgRetained, bgSessionScoped, bgEnvIsolatedOwned) +
762
729
  (tail ? `\n--- output so far (tail) ---\n${tail}` : ""),
@@ -768,7 +735,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
768
735
  : undefined;
769
736
  let res;
770
737
  try {
771
- res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, cwdRef, detachChain, false, [rootCanonical, ...(taskOpts.additionalRoots ?? [])], onTick, taskOpts.readFloor?.(ctx.toolCallId));
738
+ 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);
772
739
  }
773
740
  finally {
774
741
  taskOpts.detachHub?.gc(ctx.toolCallId);
@@ -814,70 +781,7 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
814
781
  if (refused !== undefined)
815
782
  return refused;
816
783
  const readOnlyTick = opts?.onToolProgress === undefined ? undefined : (t) => describeSafely(opts.onToolProgress, { toolCallId: ctx.toolCallId, toolName: "Bash", ...t });
817
- return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, true, undefined, readOnlyTick, opts?.readFloor?.(ctx.toolCallId));
818
- },
819
- });
820
- }
821
- export function createEnvTaskOutputTool(env) {
822
- return defineTool({
823
- name: TASK_OUTPUT_TOOL_NAME,
824
- ...toolFace("task-output-hands"),
825
- ruleFace: mountRuleFace("task-output-hands"),
826
- description: composeTaskOutputDescription(ENV_DIRECT_TASK_TOOL_CAPS),
827
- parameters: composeTaskOutputParams(ENV_DIRECT_TASK_TOOL_CAPS),
828
- execute: async (args) => {
829
- const { task_id, filter } = args;
830
- const id = resolveTaskIdArg(task_id);
831
- if (!id)
832
- return errorResult(TASK_OUTPUT_MISSING_ID_MESSAGE);
833
- if (!hasBackgroundShell(env)) {
834
- return errorResult("Error (TaskOutput): this environment does not support background processes.");
835
- }
836
- let rx;
837
- if (filter !== undefined) {
838
- try {
839
- rx = new RegExp(filter);
840
- }
841
- catch {
842
- return errorResult(`Error (TaskOutput): invalid filter regex: ${filter}`);
843
- }
844
- }
845
- const r = await env.pollBackground(id);
846
- if (!r.ok)
847
- return errorResult(`Error (TaskOutput): could not read ${id} (${r.error.code}): ${envErrorDetail(r.error.message)}`);
848
- const shape = (text) => clipShellOutput(rx ? text.split(/\r?\n/).filter((l) => rx.test(l)).join("\n") : text);
849
- const status = r.value.status === "exited" ? `exited(code ${r.value.exitCode})` : r.value.status;
850
- const dropAcct = {};
851
- accountDroppedBytes(dropAcct, r.value);
852
- const droppedNote = spoolDropNote(dropAcct);
853
- const body = `status: ${status}\n${droppedNote}--- new stdout ---\n${shape(r.value.stdout) || "(none)"}\n` +
854
- `--- new stderr ---\n${shape(r.value.stderr) || "(none)"}`;
855
- return delimitUntrusted(`TaskOutput ${id}`, body);
856
- },
857
- });
858
- }
859
- export function createEnvTaskStopTool(env, registry = defaultTaskRegistry) {
860
- return defineTool({
861
- name: TASK_STOP_TOOL_NAME,
862
- ...toolFace("task-stop-hands"),
863
- ruleFace: mountRuleFace("task-stop-hands"),
864
- description: composeTaskStopDescription(ENV_DIRECT_TASK_TOOL_CAPS),
865
- parameters: TASK_STOP_PARAMS,
866
- execute: async (args) => {
867
- const { task_id, shell_id } = args;
868
- const id = resolveTaskIdArg(task_id, shell_id);
869
- if (!id)
870
- return errorResult(TASK_STOP_MISSING_ID_MESSAGE);
871
- if (!hasBackgroundShell(env)) {
872
- return errorResult("Error (TaskStop): this environment does not support background processes.");
873
- }
874
- registry.markStopSourceByShellId(id, "parent", env);
875
- const r = await env.killBackground(id);
876
- if (!r.ok) {
877
- registry.clearPendingStopSourceByShellId(id, "parent", env);
878
- return errorResult(`${id} is unknown or has already ended.`);
879
- }
880
- return `Terminated ${id}.`;
784
+ return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, true, undefined, readOnlyTick, opts?.readFloor?.(ctx.toolCallId), opts?.imageProcessor);
881
785
  },
882
786
  });
883
787
  }
@@ -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,9 @@
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
+ import { readFloorSeat } from "./read-floor.js";
6
7
  import { planReminderDisclosure, renderReminderDisclosureTrailer } from "../../core/reminder-disclosure.js";
7
8
  import { MARKED_BLOCK_AFTER_DATA } from "../../core/reminder-mint.js";
8
9
  function pdfDisclosureTrailer(body, d) {
@@ -14,34 +15,40 @@ function pdfDisclosureTrailer(body, d) {
14
15
  return trailer !== undefined ? `${MARKED_BLOCK_AFTER_DATA}${trailer}` : "";
15
16
  }
16
17
  export { pdfModelCapabilitiesOf } from "./pdf.js";
17
- async function pdfPagesToImageBlocks(pages, path, downsamplerOpt) {
18
- const downsampler = downsamplerOpt === false ? undefined : (downsamplerOpt ?? (await resolveAutoDownsampler()));
18
+ async function pdfPagesToImageBlocks(pages, path, imageProcessor) {
19
+ const processor = await resolveImageProcessor(imageProcessor);
19
20
  const blocks = [];
20
21
  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\`).`;
22
+ const admitted = await admitImageBytes(p.jpeg, "image/jpeg", processor);
23
+ if (!admitted.ok) {
24
+ 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
25
  }
34
- blocks.push({ type: "image", data: b64, mimeType: mime });
26
+ blocks.push(admitted.block);
35
27
  }
36
28
  return blocks;
37
29
  }
30
+ function pageRefusal(a) {
31
+ switch (a.reason) {
32
+ case "mime_unsupported":
33
+ case "magic_mismatch":
34
+ return "the renderer's output is not a valid JPEG";
35
+ case "raw_too_large":
36
+ return `${a.rawBytes} bytes, over the ${a.cap}-byte read cap`;
37
+ case "dimensions_unreadable":
38
+ case "dimensions_too_large":
39
+ return unprocessedSizeClause(a);
40
+ case "base64_too_large":
41
+ return `base64 ${a.base64.length} chars exceeds the ${IMAGE_ADMISSION.hard.imageBase64Chars}-char / 5MB API image limit`;
42
+ }
43
+ }
38
44
  function boundPdfExtractedText(text) {
39
45
  if (Buffer.byteLength(text, "utf8") <= MAX_READ_BYTES)
40
46
  return { body: text, truncated: false };
41
47
  return { body: text.slice(0, MAX_READ_BYTES), truncated: true };
42
48
  }
43
- export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt, cwd, preRead, caps, readDeny, disclosure) {
49
+ export async function readPdfFile(env, path, key, pages, signal, imageProcessor, cwd, preRead, caps, readDeny, disclosure) {
44
50
  const cap = caps ?? { document: true, vision: true };
51
+ const readFloor = readFloorSeat(readDeny)?.(undefined);
45
52
  const meta = await env.fileInfo(key, signal);
46
53
  if (!meta.ok) {
47
54
  const ex = await env.exists(key, signal);
@@ -71,7 +78,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
71
78
  if (range.last !== Infinity && range.last - range.first + 1 > PDF_MAX_PAGES_PER_READ) {
72
79
  return `Error (Read): Page range "${pages}" exceeds maximum of ${PDF_MAX_PAGES_PER_READ} pages per request. Please use a smaller range.`;
73
80
  }
74
- const pageCount = await getPdfPageCount(env, key, bytes, signal);
81
+ const pageCount = await getPdfPageCount(env, key, bytes, signal, readFloor);
75
82
  if (pageCount !== undefined && range.first > pageCount) {
76
83
  return `Error (Read): page range "${pages}" starts past the end of the PDF (${pageCount} page${pageCount === 1 ? "" : "s"}).`;
77
84
  }
@@ -79,7 +86,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
79
86
  if (pageCount !== undefined)
80
87
  last = Math.min(last, pageCount);
81
88
  if (!cap.document && !cap.vision) {
82
- const t = await extractPdfTextLayer(env, key, { first: range.first, last }, signal);
89
+ const t = await extractPdfTextLayer(env, key, { first: range.first, last }, signal, readFloor);
83
90
  if (t.ok) {
84
91
  const { body, truncated } = boundPdfExtractedText(t.text);
85
92
  const words = t.cut !== undefined ? pdfCutWords(t.cut) : undefined;
@@ -117,7 +124,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
117
124
  },
118
125
  };
119
126
  }
120
- const extract = await extractPdfPagesAsImages(env, key, range.first, last, signal);
127
+ const extract = await extractPdfPagesAsImages(env, key, range.first, last, signal, readFloor);
121
128
  if (!extract.ok) {
122
129
  if (extract.toolMissing) {
123
130
  return (`Error (Read): reading a PDF page range requires the poppler utility \`pdftoppm\`, which is not available in this environment. ` +
@@ -125,7 +132,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
125
132
  }
126
133
  return `Error (Read): PDF page extraction failed for "${path}": ${extract.error}`;
127
134
  }
128
- const blocks = await pdfPagesToImageBlocks(extract.pages, path, downsamplerOpt);
135
+ const blocks = await pdfPagesToImageBlocks(extract.pages, path, imageProcessor);
129
136
  if (typeof blocks === "string")
130
137
  return blocks;
131
138
  const requestedPages = last - range.first + 1;
@@ -155,7 +162,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
155
162
  },
156
163
  };
157
164
  }
158
- const pageCount = await getPdfPageCount(env, key, bytes, signal);
165
+ const pageCount = await getPdfPageCount(env, key, bytes, signal, readFloor);
159
166
  if (pageCount !== undefined && pageCount > PDF_INLINE_PAGE_THRESHOLD) {
160
167
  return `Error (Read): This PDF has ${pageCount} pages, which is too many to read at once. Use the pages parameter to read specific page ranges (e.g., pages: "1-5"). Maximum ${PDF_MAX_PAGES_PER_READ} pages per request.`;
161
168
  }
@@ -164,7 +171,7 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
164
171
  }
165
172
  if (!cap.document) {
166
173
  const fileCard = { type: "application/pdf", originalSize: size, ...(pageCount !== undefined ? { pageCount } : {}) };
167
- const t = await extractPdfTextLayer(env, key, undefined, signal);
174
+ const t = await extractPdfTextLayer(env, key, undefined, signal, readFloor);
168
175
  if (t.ok) {
169
176
  const { body, truncated } = boundPdfExtractedText(t.text);
170
177
  const words = t.cut !== undefined ? pdfCutWords(t.cut) : undefined;
@@ -190,9 +197,9 @@ export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt,
190
197
  let renderWhy;
191
198
  if (cap.vision) {
192
199
  const n = Math.min(PDF_FALLBACK_RENDER_PAGES, pageCount ?? PDF_FALLBACK_RENDER_PAGES);
193
- const extract = await extractPdfPagesAsImages(env, key, 1, n, signal);
200
+ const extract = await extractPdfPagesAsImages(env, key, 1, n, signal, readFloor);
194
201
  if (extract.ok) {
195
- const blocks = await pdfPagesToImageBlocks(extract.pages, path, downsamplerOpt);
202
+ const blocks = await pdfPagesToImageBlocks(extract.pages, path, imageProcessor);
196
203
  if (typeof blocks !== "string") {
197
204
  const renderTimeoutNote = extract.cut !== undefined ? ` pdftoppm ${pdfCutWords(extract.cut).clause} — only the pages that finished rendering are included.` : "";
198
205
  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;