@sema-agent/core 7.59.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 (360) hide show
  1. package/CHANGELOG.md +564 -0
  2. package/dist/agents/agent-definition.d.ts +7 -0
  3. package/dist/agents/agent-definition.js +12 -0
  4. package/dist/agents/agent-transcript-tool.d.ts +2 -1
  5. package/dist/agents/agent-transcript-tool.js +3 -1
  6. package/dist/agents/child-model-seat.js +6 -3
  7. package/dist/agents/cumulative-stats.js +0 -1
  8. package/dist/agents/inherited-tool-pool.d.ts +26 -1
  9. package/dist/agents/inherited-tool-pool.js +22 -0
  10. package/dist/agents/retain-ledger.d.ts +11 -1
  11. package/dist/agents/retain-ledger.js +13 -2
  12. package/dist/agents/roster-store.d.ts +1 -1
  13. package/dist/agents/roster-store.js +3 -1
  14. package/dist/agents/send-message-tool.d.ts +8 -19
  15. package/dist/agents/send-message-tool.js +11 -38
  16. package/dist/agents/subagent.d.ts +51 -17
  17. package/dist/agents/subagent.js +117 -78
  18. package/dist/agents/tool-filter.d.ts +1 -3
  19. package/dist/agents/tool-filter.js +4 -12
  20. package/dist/bench/metrics.d.ts +3 -5
  21. package/dist/bench/metrics.js +0 -1
  22. package/dist/brain/degrading.js +3 -1
  23. package/dist/brain/route-adjudicator.js +3 -1
  24. package/dist/brain/status-sink.d.ts +7 -1
  25. package/dist/brain/status-sink.js +6 -0
  26. package/dist/brain/timeout.d.ts +3 -1
  27. package/dist/brain/timeout.js +18 -5
  28. package/dist/core/a2a.d.ts +15 -5
  29. package/dist/core/a2a.js +34 -19
  30. package/dist/core/agent-definition.d.ts +20 -0
  31. package/dist/core/allow-entry.d.ts +2 -0
  32. package/dist/core/allow-entry.js +3 -1
  33. package/dist/core/artifact-host.d.ts +0 -2
  34. package/dist/core/artifact-host.js +0 -1
  35. package/dist/core/auto-mode-defaults.d.ts +8 -0
  36. package/dist/core/auto-mode-defaults.js +1 -0
  37. package/dist/core/auto-mode-rebuild.d.ts +2 -1
  38. package/dist/core/auto-mode.d.ts +39 -4
  39. package/dist/core/auto-mode.js +63 -12
  40. package/dist/core/background-agent-store.d.ts +10 -1
  41. package/dist/core/background-agent-store.js +3 -2
  42. package/dist/core/background-shell.d.ts +12 -1
  43. package/dist/core/background-shell.js +12 -0
  44. package/dist/core/checkpoint-store.d.ts +8 -13
  45. package/dist/core/checkpoint-store.js +4 -3
  46. package/dist/core/compliance.d.ts +1 -1
  47. package/dist/core/credential-echo.d.ts +52 -0
  48. package/dist/core/credential-echo.js +65 -0
  49. package/dist/core/credential-vocabulary.d.ts +13 -3
  50. package/dist/core/credential-vocabulary.js +12 -4
  51. package/dist/core/cross-boundary-taint.d.ts +4 -5
  52. package/dist/core/engine-notice.d.ts +58 -15
  53. package/dist/core/frame-settlement.d.ts +5 -0
  54. package/dist/core/frame-settlement.js +4 -0
  55. package/dist/core/gate-fold.js +7 -5
  56. package/dist/core/gate-lanes.js +39 -8
  57. package/dist/core/governance-codes.d.ts +9 -1
  58. package/dist/core/governance-codes.js +12 -0
  59. package/dist/core/hands-band-screen.js +0 -1
  60. package/dist/core/hands-band.d.ts +0 -3
  61. package/dist/core/hooks.d.ts +39 -56
  62. package/dist/core/hooks.js +123 -77
  63. package/dist/core/image-admission.d.ts +104 -51
  64. package/dist/core/image-admission.js +170 -46
  65. package/dist/core/image-downsample.d.ts +36 -69
  66. package/dist/core/image-downsample.js +111 -73
  67. package/dist/core/integer-option.d.ts +21 -0
  68. package/dist/core/integer-option.js +13 -0
  69. package/dist/core/locked-config.d.ts +54 -3
  70. package/dist/core/locked-config.js +81 -50
  71. package/dist/core/mcp-call-meta.d.ts +2 -2
  72. package/dist/core/mcp-call-meta.js +9 -10
  73. package/dist/core/mcp-failure.d.ts +9 -3
  74. package/dist/core/mcp-failure.js +10 -0
  75. package/dist/core/mcp-host-seat.d.ts +92 -0
  76. package/dist/core/mcp-host-seat.js +131 -0
  77. package/dist/core/mcp-probe.d.ts +7 -2
  78. package/dist/core/mcp-probe.js +7 -2
  79. package/dist/core/mcp-server-spec.d.ts +38 -9
  80. package/dist/core/mcp-server-spec.js +55 -21
  81. package/dist/core/mcp.d.ts +17 -6
  82. package/dist/core/mcp.js +67 -55
  83. package/dist/core/memory-admission.d.ts +23 -6
  84. package/dist/core/memory-admission.js +19 -9
  85. package/dist/core/memory-engine/content-origin.d.ts +13 -0
  86. package/dist/core/memory-engine/content-origin.js +21 -3
  87. package/dist/core/memory-engine/index.d.ts +2 -1
  88. package/dist/core/memory-engine/index.js +2 -1
  89. package/dist/core/memory-engine/scope-contract.d.ts +13 -3
  90. package/dist/core/memory-engine/scope-contract.js +2 -2
  91. package/dist/core/memory-engine/sync-client.d.ts +45 -11
  92. package/dist/core/memory-engine/sync-client.js +82 -11
  93. package/dist/core/memory-engine/sync-report.d.ts +103 -0
  94. package/dist/core/memory-engine/sync-report.js +119 -0
  95. package/dist/core/memory-engine/sync.d.ts +4 -2
  96. package/dist/core/mode-policy.d.ts +9 -1
  97. package/dist/core/mode-policy.js +11 -1
  98. package/dist/core/model-receipt.d.ts +39 -0
  99. package/dist/core/model-receipt.js +139 -0
  100. package/dist/core/mods/agent-stations.d.ts +65 -0
  101. package/dist/core/mods/agent-stations.js +105 -0
  102. package/dist/core/mods/kernel/dispatch.d.ts +5 -1
  103. package/dist/core/mods/kernel/dispatch.js +4 -4
  104. package/dist/core/mods/kernel/events.d.ts +10 -4
  105. package/dist/core/mods/kernel/events.js +10 -6
  106. package/dist/core/mods/kernel/receive.d.ts +5 -0
  107. package/dist/core/mods/kernel/receive.js +10 -0
  108. package/dist/core/mods/lifecycle-stations.d.ts +41 -0
  109. package/dist/core/mods/lifecycle-stations.js +35 -0
  110. package/dist/core/mods/stations.d.ts +51 -59
  111. package/dist/core/mods/stations.js +32 -42
  112. package/dist/core/mods/tool-call.d.ts +10 -4
  113. package/dist/core/mods/tool-call.js +28 -12
  114. package/dist/core/mounted-mcp.d.ts +5 -0
  115. package/dist/core/mounted-mcp.js +2 -2
  116. package/dist/core/namespaced-rule-name.d.ts +7 -1
  117. package/dist/core/namespaced-rule-name.js +13 -2
  118. package/dist/core/oracle-isolation.js +1 -1
  119. package/dist/core/own-property-receipt.d.ts +3 -0
  120. package/dist/core/own-property-receipt.js +3 -0
  121. package/dist/core/park-selfcheck.js +8 -8
  122. package/dist/core/peer-seat.d.ts +63 -8
  123. package/dist/core/peer-seat.js +179 -34
  124. package/dist/core/permission-rule-consent.d.ts +0 -21
  125. package/dist/core/permission-rule-consent.js +1 -2
  126. package/dist/core/permission-rule-model.d.ts +4 -2
  127. package/dist/core/permission-rule-model.js +7 -6
  128. package/dist/core/protocol-http-auth.d.ts +14 -2
  129. package/dist/core/protocol-http-auth.js +16 -7
  130. package/dist/core/read-face-seats.d.ts +7 -5
  131. package/dist/core/read-face-seats.js +4 -1
  132. package/dist/core/redaction-marks.d.ts +4 -3
  133. package/dist/core/redaction-marks.js +2 -2
  134. package/dist/core/remote-env.d.ts +146 -98
  135. package/dist/core/remote-env.js +113 -14
  136. package/dist/core/retention.js +37 -12
  137. package/dist/core/retired-keys.d.ts +6 -1
  138. package/dist/core/retired-keys.js +4 -1
  139. package/dist/core/rewrite-rejudge.d.ts +12 -5
  140. package/dist/core/rewrite-rejudge.js +9 -5
  141. package/dist/core/roles.d.ts +37 -3
  142. package/dist/core/roles.js +126 -78
  143. package/dist/core/rule-owner.d.ts +3 -0
  144. package/dist/core/runner/assemble-result.d.ts +0 -5
  145. package/dist/core/runner/assemble-result.js +0 -1
  146. package/dist/core/runner/call-hook-stations.d.ts +17 -10
  147. package/dist/core/runner/call-hook-stations.js +21 -10
  148. package/dist/core/runner/child-tree.d.ts +7 -8
  149. package/dist/core/runner/child-tree.js +6 -6
  150. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  151. package/dist/core/runner/classifier-ladder.js +39 -8
  152. package/dist/core/runner/construction-doors.js +5 -0
  153. package/dist/core/runner/contracts.d.ts +62 -41
  154. package/dist/core/runner/cross-boundary-lane.d.ts +3 -5
  155. package/dist/core/runner/cross-boundary-lane.js +11 -2
  156. package/dist/core/runner/env-capability-census.d.ts +15 -20
  157. package/dist/core/runner/env-capability-census.js +25 -34
  158. package/dist/core/runner/file-history-request.d.ts +2 -2
  159. package/dist/core/runner/file-history-request.js +0 -8
  160. package/dist/core/runner/gate-exit.d.ts +75 -7
  161. package/dist/core/runner/gate-exit.js +20 -1
  162. package/dist/core/runner/git-status-frame.d.ts +5 -2
  163. package/dist/core/runner/git-status-frame.js +3 -4
  164. package/dist/core/runner/image.d.ts +7 -2
  165. package/dist/core/runner/image.js +14 -8
  166. package/dist/core/runner/inline-image.d.ts +10 -8
  167. package/dist/core/runner/inline-image.js +11 -9
  168. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  169. package/dist/core/runner/permission-rule-lanes.js +1 -1
  170. package/dist/core/runner/prepare-boundary-parks.d.ts +2 -2
  171. package/dist/core/runner/prepare-boundary-parks.js +3 -3
  172. package/dist/core/runner/prepare-caps-and-workflow.d.ts +4 -0
  173. package/dist/core/runner/prepare-caps-and-workflow.js +4 -3
  174. package/dist/core/runner/prepare-config-doors.d.ts +6 -1
  175. package/dist/core/runner/prepare-config-doors.js +14 -9
  176. package/dist/core/runner/prepare-delegation-surface.d.ts +5 -3
  177. package/dist/core/runner/prepare-delegation-surface.js +4 -4
  178. package/dist/core/runner/prepare-file-history.d.ts +10 -12
  179. package/dist/core/runner/prepare-file-history.js +3 -12
  180. package/dist/core/runner/prepare-gate-stations.d.ts +4 -3
  181. package/dist/core/runner/prepare-gate-stations.js +4 -3
  182. package/dist/core/runner/prepare-hands-readface.d.ts +3 -1
  183. package/dist/core/runner/prepare-hands-readface.js +15 -7
  184. package/dist/core/runner/prepare-inherited-gate.d.ts +5 -4
  185. package/dist/core/runner/prepare-inherited-gate.js +9 -5
  186. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  187. package/dist/core/runner/prepare-memory.d.ts +2 -2
  188. package/dist/core/runner/prepare-memory.js +2 -2
  189. package/dist/core/runner/prepare-park-ask.d.ts +3 -5
  190. package/dist/core/runner/prepare-park-ask.js +3 -8
  191. package/dist/core/runner/prepare-policy-chain.d.ts +5 -4
  192. package/dist/core/runner/prepare-policy-chain.js +120 -108
  193. package/dist/core/runner/prepare-project-context.js +8 -5
  194. package/dist/core/runner/prepare-prompt-inputs.d.ts +4 -1
  195. package/dist/core/runner/prepare-prompt-inputs.js +3 -2
  196. package/dist/core/runner/prepare-protocol-tools.d.ts +5 -3
  197. package/dist/core/runner/prepare-protocol-tools.js +9 -2
  198. package/dist/core/runner/prepare-suspend-saga.d.ts +0 -2
  199. package/dist/core/runner/prepare-suspend-saga.js +5 -7
  200. package/dist/core/runner/prepare-task.js +41 -27
  201. package/dist/core/runner/prepare-turn-wiring.d.ts +2 -0
  202. package/dist/core/runner/prepare-turn-wiring.js +7 -2
  203. package/dist/core/runner/prepare-wiring-manifest.d.ts +4 -3
  204. package/dist/core/runner/prepare-wiring-manifest.js +32 -18
  205. package/dist/core/runner/prepare-workspace-restore.js +3 -3
  206. package/dist/core/runner/resume-checkpoint-screen.js +4 -4
  207. package/dist/core/runner/retired-runner-deps.js +4 -1
  208. package/dist/core/runner/run-attachment-seats.js +3 -3
  209. package/dist/core/runner/run-brain-sinks.js +1 -0
  210. package/dist/core/runner/run-git-lane.d.ts +3 -1
  211. package/dist/core/runner/run-git-lane.js +1 -1
  212. package/dist/core/runner/run-harness-handlers.d.ts +3 -1
  213. package/dist/core/runner/run-harness-handlers.js +3 -1
  214. package/dist/core/runner/run-identity-wiring.js +1 -1
  215. package/dist/core/runner/run-leg.js +26 -28
  216. package/dist/core/runner/run-notification-lane.d.ts +3 -1
  217. package/dist/core/runner/run-notification-lane.js +16 -10
  218. package/dist/core/runner/run-settle-and-teardown.js +5 -1
  219. package/dist/core/runner/run-stop-and-final-verify.d.ts +4 -0
  220. package/dist/core/runner/run-stop-and-final-verify.js +12 -4
  221. package/dist/core/runner/run-turn-boundary.js +12 -7
  222. package/dist/core/runner/runtask.d.ts +7 -4
  223. package/dist/core/runner/runtask.js +19 -11
  224. package/dist/core/runner/skills-seat.js +2 -2
  225. package/dist/core/runner/sub-agent-deny-lists.js +10 -7
  226. package/dist/core/runner/synthetic-tools.js +2 -2
  227. package/dist/core/runner/tool-disclosure.js +0 -2
  228. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  229. package/dist/core/runner/tool-face-overlay.js +26 -19
  230. package/dist/core/runner/tool-result-media-seat.d.ts +9 -1
  231. package/dist/core/runner/tool-result-media-seat.js +17 -1
  232. package/dist/core/runner/turn-attachments.d.ts +3 -5
  233. package/dist/core/runner/turn-attachments.js +3 -16
  234. package/dist/core/runner-deps.d.ts +31 -18
  235. package/dist/core/secret-env.d.ts +3 -2
  236. package/dist/core/session-policy-store.d.ts +9 -2
  237. package/dist/core/session-policy-store.js +16 -1
  238. package/dist/core/session-store.d.ts +3 -2
  239. package/dist/core/session-store.js +50 -11
  240. package/dist/core/skill-grant.d.ts +9 -0
  241. package/dist/core/skill-grant.js +18 -0
  242. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  243. package/dist/core/store-contracts/tool-result-store-contract.js +37 -0
  244. package/dist/core/stub-env.d.ts +5 -5
  245. package/dist/core/stub-env.js +11 -1
  246. package/dist/core/swappable-deps.d.ts +17 -43
  247. package/dist/core/swappable-deps.js +15 -5
  248. package/dist/core/synthetic-read-verdict.d.ts +1 -1
  249. package/dist/core/task-event.d.ts +18 -2
  250. package/dist/core/task-notification.d.ts +88 -5
  251. package/dist/core/task-notification.js +130 -7
  252. package/dist/core/task-registry-agent.d.ts +18 -12
  253. package/dist/core/task-registry-agent.js +18 -6
  254. package/dist/core/task-registry-monitor.d.ts +7 -0
  255. package/dist/core/task-registry-monitor.js +28 -1
  256. package/dist/core/task-registry-shared.d.ts +38 -3
  257. package/dist/core/task-registry-shared.js +21 -7
  258. package/dist/core/task-registry-workflow.js +1 -1
  259. package/dist/core/task-registry.d.ts +50 -35
  260. package/dist/core/task-registry.js +64 -23
  261. package/dist/core/task-result.d.ts +3 -12
  262. package/dist/core/task-spec.d.ts +3 -6
  263. package/dist/core/task-stream.d.ts +1 -1
  264. package/dist/core/tool-catalog-entries.js +1 -1
  265. package/dist/core/tool-face-reader.d.ts +7 -6
  266. package/dist/core/tool-face-reader.js +4 -3
  267. package/dist/core/tool-name-aliases.d.ts +19 -0
  268. package/dist/core/tool-name-aliases.js +54 -2
  269. package/dist/core/tool-policy.d.ts +5 -4
  270. package/dist/core/tool-policy.js +1 -1
  271. package/dist/core/tool-registry.d.ts +5 -5
  272. package/dist/core/tool-registry.js +2 -2
  273. package/dist/core/tool-result-store.d.ts +88 -5
  274. package/dist/core/tool-result-store.js +51 -12
  275. package/dist/core/tool-spec.d.ts +20 -4
  276. package/dist/core/trace.d.ts +0 -1
  277. package/dist/core/types.d.ts +3 -3
  278. package/dist/core/types.js +1 -1
  279. package/dist/core/untrusted-text.js +1 -1
  280. package/dist/core/user-attachment.d.ts +10 -5
  281. package/dist/core/user-attachment.js +14 -6
  282. package/dist/engine/execution-env/node-execution-env.d.ts +7 -2
  283. package/dist/engine/execution-env/node-execution-env.js +12 -1
  284. package/dist/engine/harness/agent-harness.d.ts +1 -1
  285. package/dist/engine/harness/agent-harness.js +8 -4
  286. package/dist/engine/harness/types.d.ts +112 -29
  287. package/dist/engine/loop/agent-loop.d.ts +12 -12
  288. package/dist/engine/loop/agent-loop.js +153 -21
  289. package/dist/engine/loop/types.d.ts +9 -2
  290. package/dist/engine/lsp/node-lsp-manager.d.ts +3 -3
  291. package/dist/engine/lsp/node-lsp-manager.js +32 -13
  292. package/dist/index.d.ts +22 -14
  293. package/dist/index.js +15 -10
  294. package/dist/internal/harness-types.d.ts +1 -1
  295. package/dist/orchestration/run-workflow-tool.d.ts +9 -3
  296. package/dist/orchestration/run-workflow-tool.js +59 -29
  297. package/dist/orchestration/workflow-governance.d.ts +1 -1
  298. package/dist/orchestration/workflow-governance.js +2 -1
  299. package/dist/orchestration/workflow.d.ts +4 -0
  300. package/dist/orchestration/workflow.js +25 -4
  301. package/dist/prompts/default.d.ts +1 -10
  302. package/dist/prompts/default.js +0 -2
  303. package/dist/stores/file/background-agent-store.d.ts +1 -1
  304. package/dist/stores/file/background-agent-store.js +3 -1
  305. package/dist/stores/file/checkpoint-store.d.ts +127 -2
  306. package/dist/stores/file/checkpoint-store.js +19 -14
  307. package/dist/stores/file/file-history-store.d.ts +1 -1
  308. package/dist/stores/file/file-history-store.js +3 -1
  309. package/dist/stores/file/index.d.ts +4 -3
  310. package/dist/stores/file/index.js +17 -8
  311. package/dist/stores/file/mailbox-store.d.ts +1 -1
  312. package/dist/stores/file/mailbox-store.js +3 -1
  313. package/dist/stores/file/memory-store.d.ts +1 -1
  314. package/dist/stores/file/memory-store.js +3 -1
  315. package/dist/stores/file/session-policy-store.d.ts +1 -1
  316. package/dist/stores/file/session-policy-store.js +3 -1
  317. package/dist/stores/file/session-store.d.ts +1 -1
  318. package/dist/stores/file/session-store.js +3 -1
  319. package/dist/stores/file/shared-ledger.d.ts +26 -0
  320. package/dist/stores/file/shared-ledger.js +38 -9
  321. package/dist/stores/file/tool-result-store.d.ts +20 -2
  322. package/dist/stores/file/tool-result-store.js +74 -6
  323. package/dist/stores/file/usage-window-store.d.ts +1 -1
  324. package/dist/stores/file/usage-window-store.js +3 -1
  325. package/dist/stores/file/workflow-journal-store.d.ts +1 -11
  326. package/dist/stores/file/workflow-journal-store.js +3 -2
  327. package/dist/tools/fs/containment-face.d.ts +5 -0
  328. package/dist/tools/fs/encoding.d.ts +13 -4
  329. package/dist/tools/fs/encoding.js +17 -2
  330. package/dist/tools/fs/fs-bash-background-text.d.ts +7 -0
  331. package/dist/tools/fs/fs-bash-background-text.js +1 -0
  332. package/dist/tools/fs/fs-bash.d.ts +8 -4
  333. package/dist/tools/fs/fs-bash.js +26 -35
  334. package/dist/tools/fs/fs-pdf.d.ts +2 -2
  335. package/dist/tools/fs/fs-pdf.js +26 -21
  336. package/dist/tools/fs/fs-read.d.ts +5 -4
  337. package/dist/tools/fs/fs-read.js +35 -18
  338. package/dist/tools/fs/fs-search-tools.js +4 -1
  339. package/dist/tools/fs/fs-shared.d.ts +11 -13
  340. package/dist/tools/fs/fs-shared.js +11 -7
  341. package/dist/tools/fs/fs-write.js +5 -5
  342. package/dist/tools/fs/index.d.ts +14 -8
  343. package/dist/tools/fs/index.js +8 -4
  344. package/dist/tools/fs/read-floor.d.ts +44 -1
  345. package/dist/tools/fs/read-floor.js +35 -0
  346. package/dist/tools/fs/removal-targets.d.ts +9 -4
  347. package/dist/tools/fs/removal-targets.js +17 -9
  348. package/dist/tools/fs/search.d.ts +3 -3
  349. package/dist/tools/fs/search.js +4 -4
  350. package/dist/tools/monitor.d.ts +5 -4
  351. package/dist/tools/monitor.js +15 -8
  352. package/dist/tools/scheduler-tools.js +42 -4
  353. package/dist/tools/web.d.ts +0 -10
  354. package/dist/tools/web.js +1 -4
  355. package/package.json +4 -2
  356. package/test/export-surface.snapshot.json +75 -21
  357. package/wire-changes/core-stores-sql@7.60.0.json +30 -0
  358. package/wire-changes/core@7.60.0.json +3274 -0
  359. package/wire-changes/mods-kernel@7.60.0.json +62 -0
  360. package/wire-changes/primitives@7.60.0.json +30 -0
@@ -1,51 +1,3 @@
1
- /**
2
- * Generic image downsample/resize pipeline (design/157 S3 — split out of `core/mcp.ts`, which historically
3
- * carried this alongside MCP-protocol plumbing even though the pipeline itself has no MCP dependency).
4
- * Two consumers share this ONE pipeline + ONE size yardstick: the MCP inline-image bound (`core/mcp.ts`
5
- * `boundedImageBlock`) and the Read tool's image branch (`tools/fs/index.ts`). `core/mcp.ts` re-exports
6
- * everything below (`export * from "./image-downsample.js"`) so existing importers (`tools/fs/index.ts`,
7
- * `core/types.ts`) needed no changes on this car.
8
- */
9
- /**
10
- * design/116 W5-1 — the max base64 size of ONE inline image (5MB). Value =
11
- * `API_IMAGE_MAX_BASE64_SIZE` (constants/apiLimits.ts:22, "5 * 1024 * 1024 // 5 MB" — the hard Anthropic API
12
- * limit on a base64 image block; CC resizes/compresses down to fit UNDER it, imageResizer.ts). An MCP server
13
- * returning a bigger image previously passed straight through = a context/API bomb.
14
- */
15
- export declare const MCP_IMAGE_MAX_BASE64: number;
16
- /**
17
- * 批③ image-pipeline — CC 2.1.x `constants/apiLimits.ts` values, shared by the MCP inline-image bound
18
- * AND the Read tool's image branch (tools/fs — internal consistency: ONE yardstick per limit). That other
19
- * consumers are the file tools (`tools/fs/fs-read.ts`'s image branch, plus `fs-pdf`/`fs-bash`), which IMPORT
20
- * {@link MCP_IMAGE_MAX_BASE64} / {@link IMAGE_TARGET_RAW_SIZE} from here (through core/mcp.js's re-export)
21
- * rather than re-deriving them — one limit, every consumer reading it, no drift.
22
- * - `IMAGE_TARGET_RAW_SIZE` (apiLimits.ts:29): raw-byte target that guarantees the base64 encoding stays
23
- * under {@link MCP_IMAGE_MAX_BASE64} (raw × 4/3 = base64 → 3.75MB raw = 5MB base64).
24
- * - `IMAGE_MAX_WIDTH/HEIGHT` (apiLimits.ts:42-43): client-side resize box. The API internally resizes
25
- * above 1568px anyway; 2000px preserves a little extra quality while bounding token burn (~3x for a
26
- * full-resolution screenshot vs the box).
27
- */
28
- export declare const IMAGE_TARGET_RAW_SIZE: number;
29
- export declare const IMAGE_MAX_WIDTH = 2000;
30
- export declare const IMAGE_MAX_HEIGHT = 2000;
31
- /**
32
- * design/116 W5-1 — bound an inline MCP image. HONEST DELTA vs CC: CC really resizes/downsamples an
33
- * oversized image with sharp (utils/imageResizer.ts `maybeResizeAndDownsampleImageBuffer`: ≤2000x2000px,
34
- * ≤3.75MB raw = 5MB base64, progressive JPEG/PNG quality ladder). Core deliberately takes NO image-processing
35
- * dependency (arch decision — sharp is a native module we won't force on every consumer), so instead of
36
- * resizing we BOUND: an image whose base64 exceeds {@link MCP_IMAGE_MAX_BASE64} is spilled to disk and
37
- * replaced by an explanatory text block with the size + path; a within-limit image passes through unchanged.
38
- */
39
- /**
40
- * Optional image-resize seam (design/116 review CONFIRM-1, 裁定 2026-07-02 加 seam 保体验): given an
41
- * over-limit image, return a smaller re-encoded one — or undefined when it can't. CC resizes with sharp
42
- * (imageResizer.ts: fit within 2000x2000, JPEG quality ladder) so the model still SEES a degraded image;
43
- * core must not hard-depend on a native image library, so the capability is injected (or auto-detected).
44
- */
45
- export type McpImageResizer = (base64: string, mimeType: string) => Promise<{
46
- base64: string;
47
- mimeType: string;
48
- } | undefined>;
49
1
  /**
50
2
  * 批③ image-pipeline — original vs displayed size of a processed image (CC `imageResizer.ts`
51
3
  * `ImageDimensions`). `display*` = what the model actually sees; the Read tool renders the CC coordinate-
@@ -65,10 +17,9 @@ export interface DownsampledImage {
65
17
  dimensions?: ImageDimensions;
66
18
  }
67
19
  /**
68
- * 批③ — buffer-level image downsampler shared by the MCP inline-image bound AND the Read tool's image
69
- * branch. Returns undefined when the input can't be processed (corrupt/unsupported) — the caller keeps
70
- * its non-sharp path (spill for MCP, original-bytes for Read). A within-limits image passes through
71
- * UNCHANGED (with dimensions when known) — pass-through is not a failure.
20
+ * An image processor: the bytes the admission checked, in; the bytes the model gets, out — or undefined when the input
21
+ * can't be processed (corrupt/unsupported), and the admission then judges the original bytes as they are. A
22
+ * within-target image passes through UNCHANGED (with dimensions when known) — pass-through is not a failure.
72
23
  */
73
24
  export type ImageDownsampler = (input: Buffer, mimeType: string) => Promise<DownsampledImage | undefined>;
74
25
  /** Minimal structural slice of the sharp API the pipeline uses (fresh instance per operation — CC note:
@@ -79,7 +30,9 @@ interface SharpOps {
79
30
  width?: number;
80
31
  height?: number;
81
32
  format?: string;
33
+ orientation?: number;
82
34
  }>;
35
+ rotate: () => SharpOps;
83
36
  resize: (w: number, h: number, o: {
84
37
  fit: "inside";
85
38
  withoutEnlargement: boolean;
@@ -91,29 +44,43 @@ interface SharpOps {
91
44
  compressionLevel: number;
92
45
  palette: boolean;
93
46
  }) => SharpOps;
47
+ flatten: (o: {
48
+ background: string;
49
+ }) => SharpOps;
94
50
  toBuffer: () => Promise<Buffer>;
95
51
  }
96
52
  /**
97
- * The CC downsample pipeline (imageResizer.ts `maybeResizeAndDownsampleImageBuffer`, called by
98
- * FileReadTool.ts:1097 `readImageWithTokenBudget`), ported over an injected sharp factory so the ladder
99
- * is unit-testable without the native dependency:
100
- * 1. fits already (raw ≤ 3.75MB AND ≤ 2000×2000) → pass through, dimensions attached;
101
- * 2. dims fit but bytes over → full-resolution compression first (PNG lossless/palette for PNGs, then
102
- * JPEG quality ladder 80/60/40/20) — preserves resolution when possible;
103
- * 3. dims over → constrain to the 2000×2000 box (aspect kept), then the same ladder on the resized
104
- * image if still over; last rung = ≤1000px wide JPEG q20 (returned without a further size check —
105
- * the caller's base64 gate stays the final arbiter, CC-identical shape);
106
- * 4. metadata without dimensions → JPEG q80 when over target, else pass through (CC branch).
107
- * Exported for tests (fake sharp factory); production entry = {@link sharpImageDownsampler}.
53
+ * The processor over an injected sharp factory (so both stages are unit-testable without the native dependency). Two
54
+ * stages, in the order of `VS` (cli309.js:262027), after a frame that asks to be shown turned is turned upright:
55
+ * 1. the frame ladder (CC `IGe`, called by FileReadTool `readImageWithTokenBudget`), toward `soft.frameEdge` and
56
+ * `soft.rawBytes`:
57
+ * a. fits already (raw ≤ rawBytes AND inside the frame) → pass through, dimensions attached;
58
+ * b. dims fit but bytes over → full-resolution compression first (PNG lossless/palette for PNGs, then
59
+ * JPEG quality ladder 80/60/40/20) — preserves resolution when possible;
60
+ * c. dims over → constrain to the frame (aspect kept), then the same ladder on the resized image if still over; last
61
+ * rung = ≤1000px wide JPEG q20;
62
+ * d. metadata without dimensions → JPEG q80 when over rawBytes, else pass through (CC branch);
63
+ * 2. the byte-target step ({@link toByteTarget}) when the ladder's bytes are over `soft.targetBytes`. A failure of this
64
+ * step keeps the ladder's bytes (CC: "passing through unbudgeted").
65
+ * An image already inside the frame and at or under the target passes both stages byte-identical, so a second
66
+ * admission of what the first one sent changes nothing. The caller's base64 gate stays the final arbiter.
108
67
  */
109
68
  export declare function createImageDownsampler(sharp: SharpFactory): ImageDownsampler;
69
+ /**
70
+ * Production processor factory: dynamic `import("sharp")`. sharp is an OPTIONAL native dependency — declared under
71
+ * `optionalDependencies`, never `dependencies` (arch decision, design/116 W5-1: core won't force a native module on
72
+ * every consumer; RB-213 made the optional-ness VISIBLE to package managers without changing the decision —
73
+ * `optionalDependencies` still installs best-effort and never fails the parent install if the native build fails). A
74
+ * turnkey deployment that has it available gets the CC experience automatically; without it this resolves to undefined.
75
+ */
110
76
  export declare function sharpImageDownsampler(): Promise<ImageDownsampler | undefined>;
77
+ /** The seat's value door (at `new Runner`): a processor, `false`, or absent — anything else is refused by name rather than read
78
+ * as "detect" or "none" (`config.invalid_argument`). */
79
+ export declare function checkedImageProcessorSeat(value: unknown, seat: string): void;
111
80
  /**
112
- * Default resizer factory: dynamic `import("sharp")` — a turnkey deployment with sharp installed gets the
113
- * CC experience automatically; without it this resolves to undefined and the spill path applies. Since
114
- * 批③ this is a thin base64 adapter over {@link sharpImageDownsampler} (single pipeline, CC ladder);
115
- * the contract is unchanged: undefined when sharp is missing, the input is corrupt, or even the lowest
116
- * ladder rung stays over the API limit.
81
+ * The one reading of the image processor seat (`RunnerDeps.imageProcessor`): a function is the processor; `false` is
82
+ * `"none"` (nothing is detected); absent detects sharp once per process ({@link sharpImageDownsampler}) and answers
83
+ * `"none"` when it does not resolve. Every carrier that admits an image reads its processor here.
117
84
  */
118
- export declare function sharpImageResizer(): Promise<McpImageResizer | undefined>;
85
+ export declare function resolveImageProcessor(seat: ImageDownsampler | false | undefined): Promise<ImageDownsampler | "none">;
119
86
  export {};
@@ -1,76 +1,110 @@
1
- export const MCP_IMAGE_MAX_BASE64 = 5 * 1024 * 1024;
2
- export const IMAGE_TARGET_RAW_SIZE = (MCP_IMAGE_MAX_BASE64 * 3) / 4;
3
- export const IMAGE_MAX_WIDTH = 2000;
4
- export const IMAGE_MAX_HEIGHT = 2000;
1
+ import { IMAGE_ADMISSION } from "./image-admission.js";
2
+ import { describeRejectedValue } from "./tool-search-setting.js";
3
+ const toJpeg = (ops, quality) => ops.flatten({ background: "#ffffff" }).jpeg({ quality });
4
+ async function toByteTarget(sharp, input, target) {
5
+ const jpeg = (quality) => toJpeg(sharp(input.buf), quality).toBuffer();
6
+ const asJpeg = (buf) => ({ buf, mimeType: "image/jpeg", ...(input.dimensions !== undefined ? { dimensions: input.dimensions } : {}) });
7
+ let smallest = input;
8
+ let hi = 90;
9
+ if (input.mimeType !== "image/jpeg") {
10
+ const q90 = await jpeg(90);
11
+ if (q90.length < smallest.buf.length)
12
+ smallest = asJpeg(q90);
13
+ if (q90.length <= target)
14
+ return asJpeg(q90);
15
+ hi = 89;
16
+ }
17
+ let lo = 1;
18
+ let best;
19
+ for (let probe = 0; probe < 5; probe++) {
20
+ const quality = Math.floor((lo + hi) / 2);
21
+ const buf = await jpeg(quality);
22
+ if (buf.length < smallest.buf.length)
23
+ smallest = asJpeg(buf);
24
+ if (buf.length <= target) {
25
+ best = buf;
26
+ lo = quality + 1;
27
+ }
28
+ else
29
+ hi = quality - 1;
30
+ if (lo > hi)
31
+ break;
32
+ }
33
+ return best !== undefined ? asJpeg(best) : smallest;
34
+ }
5
35
  export function createImageDownsampler(sharp) {
6
36
  const BOX = { fit: "inside", withoutEnlargement: true };
7
- return async (input, mimeType) => {
8
- if (input.length === 0)
9
- return undefined;
10
- try {
11
- const meta = await sharp(input).metadata();
12
- const fmt = meta.format === "jpg" ? "jpeg" : meta.format;
13
- const passMime = fmt ? `image/${fmt}` : mimeType;
14
- const originalSize = input.length;
15
- if (!meta.width || !meta.height) {
16
- if (originalSize > IMAGE_TARGET_RAW_SIZE) {
17
- const buf = await sharp(input).jpeg({ quality: 80 }).toBuffer();
18
- return { base64: buf.toString("base64"), mimeType: "image/jpeg" };
19
- }
20
- return { base64: input.toString("base64"), mimeType: passMime };
21
- }
22
- const originalWidth = meta.width;
23
- const originalHeight = meta.height;
24
- let width = originalWidth;
25
- let height = originalHeight;
26
- const dims = (dw, dh) => ({ originalWidth, originalHeight, displayWidth: dw, displayHeight: dh });
27
- if (originalSize <= IMAGE_TARGET_RAW_SIZE && width <= IMAGE_MAX_WIDTH && height <= IMAGE_MAX_HEIGHT) {
28
- return { base64: input.toString("base64"), mimeType: passMime, dimensions: dims(width, height) };
29
- }
30
- const needsDimensionResize = width > IMAGE_MAX_WIDTH || height > IMAGE_MAX_HEIGHT;
31
- const isPng = fmt === "png";
32
- if (!needsDimensionResize) {
33
- if (isPng) {
34
- const png = await sharp(input).png({ compressionLevel: 9, palette: true }).toBuffer();
35
- if (png.length <= IMAGE_TARGET_RAW_SIZE)
36
- return { base64: png.toString("base64"), mimeType: "image/png", dimensions: dims(width, height) };
37
- }
38
- for (const quality of [80, 60, 40, 20]) {
39
- const buf = await sharp(input).jpeg({ quality }).toBuffer();
40
- if (buf.length <= IMAGE_TARGET_RAW_SIZE)
41
- return { base64: buf.toString("base64"), mimeType: "image/jpeg", dimensions: dims(width, height) };
42
- }
43
- }
44
- if (width > IMAGE_MAX_WIDTH) {
45
- height = Math.round((height * IMAGE_MAX_WIDTH) / width);
46
- width = IMAGE_MAX_WIDTH;
47
- }
48
- if (height > IMAGE_MAX_HEIGHT) {
49
- width = Math.round((width * IMAGE_MAX_HEIGHT) / height);
50
- height = IMAGE_MAX_HEIGHT;
51
- }
52
- const resized = await sharp(input).resize(width, height, BOX).toBuffer();
53
- if (resized.length <= IMAGE_TARGET_RAW_SIZE) {
54
- return { base64: resized.toString("base64"), mimeType: passMime, dimensions: dims(width, height) };
55
- }
37
+ const { frameEdge, rawBytes, targetBytes } = IMAGE_ADMISSION.soft;
38
+ const upright = async (input) => ((await sharp(input).metadata()).orientation ?? 1) >= 2 ? sharp(input).rotate().toBuffer() : input;
39
+ const ladder = async (input, mimeType) => {
40
+ const meta = await sharp(input).metadata();
41
+ const fmt = meta.format === "jpg" ? "jpeg" : meta.format;
42
+ const passMime = fmt ? `image/${fmt}` : mimeType;
43
+ const originalSize = input.length;
44
+ if (!meta.width || !meta.height) {
45
+ if (originalSize > rawBytes)
46
+ return { buf: await toJpeg(sharp(input), 80).toBuffer(), mimeType: "image/jpeg" };
47
+ return { buf: input, mimeType: passMime };
48
+ }
49
+ const originalWidth = meta.width;
50
+ const originalHeight = meta.height;
51
+ let width = originalWidth;
52
+ let height = originalHeight;
53
+ const dims = (dw, dh) => ({ originalWidth, originalHeight, displayWidth: dw, displayHeight: dh });
54
+ if (originalSize <= rawBytes && width <= frameEdge && height <= frameEdge)
55
+ return { buf: input, mimeType: passMime, dimensions: dims(width, height) };
56
+ const needsDimensionResize = width > frameEdge || height > frameEdge;
57
+ const isPng = fmt === "png";
58
+ if (!needsDimensionResize) {
56
59
  if (isPng) {
57
- const png = await sharp(input).resize(width, height, BOX).png({ compressionLevel: 9, palette: true }).toBuffer();
58
- if (png.length <= IMAGE_TARGET_RAW_SIZE)
59
- return { base64: png.toString("base64"), mimeType: "image/png", dimensions: dims(width, height) };
60
+ const png = await sharp(input).png({ compressionLevel: 9, palette: true }).toBuffer();
61
+ if (png.length <= rawBytes)
62
+ return { buf: png, mimeType: "image/png", dimensions: dims(width, height) };
60
63
  }
61
64
  for (const quality of [80, 60, 40, 20]) {
62
- const buf = await sharp(input).resize(width, height, BOX).jpeg({ quality }).toBuffer();
63
- if (buf.length <= IMAGE_TARGET_RAW_SIZE)
64
- return { base64: buf.toString("base64"), mimeType: "image/jpeg", dimensions: dims(width, height) };
65
+ const buf = await toJpeg(sharp(input), quality).toBuffer();
66
+ if (buf.length <= rawBytes)
67
+ return { buf, mimeType: "image/jpeg", dimensions: dims(width, height) };
65
68
  }
66
- const smallerWidth = Math.min(width, 1000);
67
- const smallerHeight = Math.round((height * smallerWidth) / Math.max(width, 1));
68
- const last = await sharp(input).resize(smallerWidth, smallerHeight, BOX).jpeg({ quality: 20 }).toBuffer();
69
- return { base64: last.toString("base64"), mimeType: "image/jpeg", dimensions: dims(smallerWidth, smallerHeight) };
69
+ }
70
+ if (width > frameEdge) {
71
+ height = Math.round((height * frameEdge) / width);
72
+ width = frameEdge;
73
+ }
74
+ if (height > frameEdge) {
75
+ width = Math.round((width * frameEdge) / height);
76
+ height = frameEdge;
77
+ }
78
+ const resized = await sharp(input).resize(width, height, BOX).toBuffer();
79
+ if (resized.length <= rawBytes)
80
+ return { buf: resized, mimeType: passMime, dimensions: dims(width, height) };
81
+ if (isPng) {
82
+ const png = await sharp(input).resize(width, height, BOX).png({ compressionLevel: 9, palette: true }).toBuffer();
83
+ if (png.length <= rawBytes)
84
+ return { buf: png, mimeType: "image/png", dimensions: dims(width, height) };
85
+ }
86
+ for (const quality of [80, 60, 40, 20]) {
87
+ const buf = await toJpeg(sharp(input).resize(width, height, BOX), quality).toBuffer();
88
+ if (buf.length <= rawBytes)
89
+ return { buf, mimeType: "image/jpeg", dimensions: dims(width, height) };
90
+ }
91
+ const smallerWidth = Math.min(width, 1000);
92
+ const smallerHeight = Math.round((height * smallerWidth) / Math.max(width, 1));
93
+ const last = await toJpeg(sharp(input).resize(smallerWidth, smallerHeight, BOX), 20).toBuffer();
94
+ return { buf: last, mimeType: "image/jpeg", dimensions: dims(smallerWidth, smallerHeight) };
95
+ };
96
+ return async (input, mimeType) => {
97
+ if (input.length === 0)
98
+ return undefined;
99
+ let framed;
100
+ try {
101
+ framed = await ladder(await upright(input), mimeType);
70
102
  }
71
103
  catch {
72
104
  return undefined;
73
105
  }
106
+ const out = framed.buf.length > targetBytes ? await toByteTarget(sharp, framed, targetBytes).catch(() => framed) : framed;
107
+ return { base64: out.buf.toString("base64"), mimeType: out.mimeType, ...(out.dimensions !== undefined ? { dimensions: out.dimensions } : {}) };
74
108
  };
75
109
  }
76
110
  const SHARP_LIMIT_INPUT_PIXELS = 100_000_000;
@@ -84,14 +118,18 @@ export async function sharpImageDownsampler() {
84
118
  return undefined;
85
119
  }
86
120
  }
87
- export async function sharpImageResizer() {
88
- const down = await sharpImageDownsampler();
89
- if (!down)
90
- return undefined;
91
- return async (base64, mimeType) => {
92
- const out = await down(Buffer.from(base64, "base64"), mimeType).catch(() => undefined);
93
- if (!out || out.base64.length > MCP_IMAGE_MAX_BASE64)
94
- return undefined;
95
- return { base64: out.base64, mimeType: out.mimeType };
96
- };
121
+ export function checkedImageProcessorSeat(value, seat) {
122
+ if (value === undefined || value === false || typeof value === "function")
123
+ return;
124
+ const e = new Error(`${seat} ${describeRejectedValue(value)} is not an image processor — expected an ImageDownsampler function, or false for none, or omit it to detect sharp`);
125
+ e.code = "config.invalid_argument";
126
+ throw e;
127
+ }
128
+ let detected;
129
+ export async function resolveImageProcessor(seat) {
130
+ if (typeof seat === "function")
131
+ return seat;
132
+ if (seat === false)
133
+ return "none";
134
+ return (await (detected ??= sharpImageDownsampler())) ?? "none";
97
135
  }
@@ -0,0 +1,21 @@
1
+ /** The integers an option takes, both ends included. */
2
+ export interface IntegerRange {
3
+ readonly min: number;
4
+ readonly max: number;
5
+ }
6
+ /** Every whole number a double holds exactly, from 0: the range of a count or a size. */
7
+ export declare const NON_NEGATIVE_SAFE_INTEGER: IntegerRange;
8
+ /** The milliseconds an interval timer takes: `1..{@link MAX_TIMER_DELAY_MS}`. Node reads a zero, a negative, a non-number or a longer
9
+ * delay as 1 ms and truncates a fractional one — an interval set to a 1 ms delay runs back to back — so an interval option refuses every value outside it. */
10
+ export declare const TIMER_DELAY_MS: IntegerRange;
11
+ /**
12
+ * The ONE reading of a whole-number option of a constructor: absent is the option's own default (`undefined`), a number that is an
13
+ * integer inside `range` is itself, and anything else — a fractional, an infinite, a NaN, an out-of-range number, a value that is no
14
+ * number — refuses (`config.invalid_argument`) rather than being read as "off" or as a neighbouring value. A number is spelled in the
15
+ * sentence; any other value is named by its type only, so a refusal never repeats text the caller handed over.
16
+ *
17
+ * @param name the option as the refusal names it (`Owner.option`)
18
+ * @param unit what the number counts (`milliseconds`, `characters`)
19
+ * @param absent what omitting the option means, as the sentence's way out
20
+ */
21
+ export declare function readIntegerOption(name: string, value: unknown, range: IntegerRange, unit: string, absent: string): number | undefined;
@@ -0,0 +1,13 @@
1
+ import { MAX_TIMER_DELAY_MS } from "../brain/timeout.js";
2
+ import { receiptRefusal } from "./own-property-receipt.js";
3
+ import { describeRejectedValue } from "./tool-search-setting.js";
4
+ export const NON_NEGATIVE_SAFE_INTEGER = Object.freeze({ min: 0, max: Number.MAX_SAFE_INTEGER });
5
+ export const TIMER_DELAY_MS = Object.freeze({ min: 1, max: MAX_TIMER_DELAY_MS });
6
+ export function readIntegerOption(name, value, range, unit, absent) {
7
+ if (value === undefined)
8
+ return undefined;
9
+ if (typeof value === "number" && Number.isInteger(value) && value >= range.min && value <= range.max)
10
+ return value;
11
+ const got = typeof value === "number" ? describeRejectedValue(value) : `a ${value === null ? "null" : typeof value}`;
12
+ throw receiptRefusal(`${name} must be a whole number of ${unit} from ${range.min} to ${range.max} (got ${got}) — omit it for ${absent}`);
13
+ }
@@ -43,7 +43,7 @@ export interface LockedPreflight {
43
43
  /** The validated lock set (empty when the deployment declares none). */
44
44
  lockedKeys: ReadonlySet<LockedKey>;
45
45
  /** Effective MCP server list for this task: a validated, frozen SNAPSHOT of `spec.mcp` when the
46
- * key is unlocked (see {@link snapshotAndValidateMcpEntries} — the content-class and `toolAxes` declarations
46
+ * key is unlocked (the receipt {@link receivePeerDeclarations}, judged by `validatedMcpEntries` — the content-class and `toolAxes` declarations
47
47
  * are read once and judged here, so no mint site downstream can be handed a different value than the door
48
48
  * approved); with `mcp` locked a spec-supplied value has already been refused, so this is always
49
49
  * `undefined` (core has no deployment-level MCP seat — a locked deployment mounts no
@@ -201,7 +201,22 @@ export declare function judgeEntrySessionMetaKey(copy: McpServerSpec): {
201
201
  code: string;
202
202
  };
203
203
  };
204
- /** Everything a snapshot MCP entry declares beyond its plain data, judged: its `toolAxes` ({@link judgeEntryToolAxes}), its `toolFaces` ({@link judgeEntryToolFaces}), its `sessionMetaKey` ({@link judgeEntrySessionMetaKey}). */
204
+ /**
205
+ * The host-transport question for ONE snapshot MCP entry: a `{ kind: "host" }` transport carries no member beyond its kind (its host seat
206
+ * carries its own pieces — a reference, a principal header, a command or a url would be declared and never in force), and its server
207
+ * cannot opt in to `elicitation` (the seat answers the engine's requests only: a server's request has no way back). Either refuses under
208
+ * `config.invalid_argument`, naming the server and the member. Any other entry is unchanged.
209
+ */
210
+ export declare function judgeEntryHostTransport(copy: McpServerSpec): {
211
+ ok: true;
212
+ entry: McpServerSpec;
213
+ } | {
214
+ ok: false;
215
+ error: Error & {
216
+ code: string;
217
+ };
218
+ };
219
+ /** Everything a snapshot MCP entry declares beyond its plain data, judged: its `toolAxes` ({@link judgeEntryToolAxes}), its `toolFaces` ({@link judgeEntryToolFaces}), its `sessionMetaKey` ({@link judgeEntrySessionMetaKey}), its host transport ({@link judgeEntryHostTransport}). */
205
220
  export declare function judgeMcpEntryDeclarations(copy: McpServerSpec): {
206
221
  ok: true;
207
222
  entry: McpServerSpec;
@@ -211,6 +226,42 @@ export declare function judgeMcpEntryDeclarations(copy: McpServerSpec): {
211
226
  code: string;
212
227
  };
213
228
  };
229
+ /** One received thing: what the receipt read, or the refusal it raised — kept, raised by the door where it would have been raised. */
230
+ export type Received<T> = {
231
+ readonly read: T;
232
+ } | {
233
+ readonly refused: unknown;
234
+ };
235
+ /**
236
+ * What the door receives of a task, read once: the deployment's lock set, then the declared MCP servers and A2A peers — each list read
237
+ * once, each entry copied (frozen plain data) or refused on its own (the door raises the refusals in the order it judges entries). A list
238
+ * is absent when the task declares none, when its key is locked (the door refuses a locked list without reading it), or when the lock
239
+ * declaration was refused (nothing past it is read). Taken where the engine takes the spec ({@link receivePeerDeclarations}).
240
+ */
241
+ export interface ReceivedPeerDeclarations {
242
+ readonly locks: Received<ReadonlySet<LockedKey>>;
243
+ readonly mcp?: Received<readonly Received<McpServerSpec>[]>;
244
+ readonly a2a?: Received<readonly Received<A2aServerSpec>[]>;
245
+ }
246
+ /**
247
+ * The door's receipt — the lock set, `spec.mcp`, `spec.a2a` — taken once at the moment the engine takes the spec
248
+ * (`Runner.runTaskStream`): the leg holds the references this copy names from then on (peer-seat.ts) and its door judges this same
249
+ * copy ({@link preflightLockedConfig}), so what a leg holds and what it dials are one read. Never throws.
250
+ */
251
+ export declare function receivePeerDeclarations(spec: Pick<TaskSpec, "mcp" | "a2a">, deps: Pick<RunnerDeps, "lockedConfig">): ReceivedPeerDeclarations;
252
+ /** The copies a receipt holds, as a keeper's declarations (a refused entry names nothing: the door refuses its leg before anything is dialled). */
253
+ export declare function receivedDeclarations(receipt: ReceivedPeerDeclarations): {
254
+ readonly mcp?: readonly McpServerSpec[];
255
+ readonly a2a?: readonly A2aServerSpec[];
256
+ };
257
+ /**
258
+ * The door's MCP half over one declared list, in one call: the list read once ({@link declaredEntriesOf}), each server snapshotted to frozen
259
+ * plain data ({@link snapshotMcpEntries}), its content class and its per-tool declarations judged ({@link validatedMcpEntries}) — a server
260
+ * whose declaration does not fit refuses the whole list. The same steps the task's own list takes (received when the engine takes the spec,
261
+ * {@link receivePeerDeclarations}, judged at its prepare), for a list received elsewhere: an agent definition's `AgentDefinition.mcp` where
262
+ * the definition is received (`where` names that field in the list-level sentence; every per-server sentence is the same).
263
+ */
264
+ export declare function snapshotAndValidateMcpEntries(declared: unknown, where?: string): McpServerSpec[];
214
265
  /**
215
266
  * The single preflight resolver: validate the lock declaration, refuse a spec that tries to occupy
216
267
  * a locked slot (`config.locked_key`, two-state — the whole prepare is rejected, nothing is
@@ -219,7 +270,7 @@ export declare function judgeMcpEntryDeclarations(copy: McpServerSpec): {
219
270
  * screen calls this same function (`enter` naming each refusal's seat) and hands the leg the frozen
220
271
  * entries it judged, so the leg's prepare judges engine-owned plain data and dials what was judged.
221
272
  */
222
- export declare function preflightLockedConfig(spec: Pick<TaskSpec, "mcp" | "a2a" | "toolPolicy" | "basePolicyForResumeEdit">, deps: RunnerDeps, enter?: ConfigDoorEntry): LockedPreflight;
273
+ export declare function preflightLockedConfig(spec: Pick<TaskSpec, "mcp" | "a2a" | "toolPolicy" | "basePolicyForResumeEdit">, deps: RunnerDeps, enter?: ConfigDoorEntry, receipt?: ReceivedPeerDeclarations): LockedPreflight;
223
274
  /**
224
275
  * The two caller policies a prepare resolves to: the task's own seat over the deployment's, or the deployment's alone
225
276
  * under a `toolPolicy` lock — one resolution, read by the preflight above (which a resume enters before its claim).