@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
@@ -6,6 +6,7 @@ import { credentialHeaderValues, holdOwnCredentialValues, isBlankCredential, isC
6
6
  import { deliverEngineNotice } from "../core/engine-notice.js";
7
7
  import { uuidv7 } from "../engine/session/uuid.js";
8
8
  import { REDACTION_MARKS } from "../core/redaction-marks.js";
9
+ import { URI_SCHEME_SOURCE, URL_USERINFO_SOURCE } from "../core/credential-vocabulary.js";
9
10
  const REDACTED_VALUE = "«redacted»";
10
11
  const REDACTED_CREDENTIALS = REDACTION_MARKS.credentials;
11
12
  function servableParse(raw) {
@@ -180,8 +181,9 @@ export function joinRequestUrl(root, suffix) {
180
181
  }
181
182
  return composed;
182
183
  }
184
+ const AUTHORITY_USERINFO = new RegExp(String.raw `(${URI_SCHEME_SOURCE}:\/\/)${URL_USERINFO_SOURCE}`, "g");
183
185
  export function stripUrlCredentials(text) {
184
- return text.replace(/([A-Za-z][A-Za-z0-9+.\-]*:\/\/)[^/\s"'@]*@/g, `$1${REDACTED_CREDENTIALS}@`);
186
+ return text.replace(AUTHORITY_USERINFO, `$1${REDACTED_CREDENTIALS}@`);
185
187
  }
186
188
  export function resolveRequestRoot(modelBaseUrl, configBaseUrl, laneDefault = "") {
187
189
  return resolveRequestRootOf(modelBaseUrl, configBaseUrl, laneDefault).root;
@@ -1,10 +1,16 @@
1
- import type { BrainRetryErrClass, BrainStatus } from "../core/types.js";
1
+ import type { BrainRetryErrClass, BrainStatus, BrainStatusSeat } from "../core/types.js";
2
2
  import type { ReasoningWireFacts } from "./reasoning.js";
3
3
  import type { CapabilityDeclaration, ModelCapability } from "./model-capability.js";
4
4
  /** Run `fn` with a per-task brain-status sink in scope. ALS propagates it through the async brain calls
5
5
  * inside `fn` (the harness's prompt → brain.stream → connect/retry loop), so {@link emitBrainStatus}
6
6
  * reaches THIS task's sink and nothing else. */
7
7
  export declare function runWithStatusSink<T>(emit: (s: BrainStatus) => void, fn: () => Promise<T>): Promise<T>;
8
+ /**
9
+ * Run `fn` with every liveness frame its brain calls report stamped with `seat` ({@link BrainStatus.seat}): a nested scope over
10
+ * the ACTIVE sink (the frames still reach the task's stream, unlike a derived leg's no-op shield). A frame that names a seat keeps
11
+ * its own; the stamp is applied at emit time, so a timer-fired frame carries it; outside a sink the call runs unchanged.
12
+ */
13
+ export declare function withStatusSeat<T>(seat: BrainStatusSeat, fn: () => T): T;
8
14
  /**
9
15
  * Report a brain-layer liveness status to the active per-task sink, if any. A no-op outside a
10
16
  * {@link runWithStatusSink} scope (e.g. compaction's `complete`, or a brain used standalone).
@@ -3,6 +3,12 @@ const statusSinkStore = new AsyncLocalStorage();
3
3
  export function runWithStatusSink(emit, fn) {
4
4
  return statusSinkStore.run({ emit }, fn);
5
5
  }
6
+ export function withStatusSeat(seat, fn) {
7
+ const outer = statusSinkStore.getStore();
8
+ if (outer === undefined)
9
+ return fn();
10
+ return statusSinkStore.run({ emit: (s) => outer.emit(s.seat === undefined ? { ...s, seat } : s) }, fn);
11
+ }
6
12
  export function bindBrainStatusEmitter() {
7
13
  const sink = statusSinkStore.getStore();
8
14
  if (sink === undefined)
@@ -278,6 +278,8 @@ export interface BrainCallGuardrailRef {
278
278
  *
279
279
  * `return()` on the wrapped iterator forwards the inner cleanup WITHOUT awaiting it: the whole point
280
280
  * is that the engine stops waiting on a brain, so releasing the iterator must not re-introduce a wait
281
- * on the same hung code.
281
+ * on the same hung code. A `return()` before the brain's terminal event abandons the call: the signal the
282
+ * brain holds is aborted first, since a stream's own `return()` need not cancel its request and, once the
283
+ * gate is disarmed, no outer abort reaches the brain any more.
282
284
  */
283
285
  export declare function withBrainCallGuardrail(streamFn: StreamFn, limitMs: number, ref: BrainCallGuardrailRef): StreamFn;
@@ -224,6 +224,7 @@ function armCallGuardrail(limitMs, outerSignal, ref) {
224
224
  outerSignal.addEventListener("abort", forwardAbort, { once: true });
225
225
  }
226
226
  let expired;
227
+ let over = false;
227
228
  let rejectExpiry = () => undefined;
228
229
  const expiry = new Promise((_resolve, reject) => {
229
230
  rejectExpiry = reject;
@@ -246,12 +247,22 @@ function armCallGuardrail(limitMs, outerSignal, ref) {
246
247
  throw expired;
247
248
  return value;
248
249
  },
249
- disarm: () => {
250
- clearTimeout(timer);
251
- if (outerSignal !== undefined)
252
- outerSignal.removeEventListener("abort", forwardAbort);
250
+ disarm,
251
+ answered: () => {
252
+ over = true;
253
+ },
254
+ abandon: () => {
255
+ if (!over)
256
+ ac.abort();
257
+ disarm();
253
258
  },
254
259
  };
260
+ function disarm() {
261
+ over = true;
262
+ clearTimeout(timer);
263
+ if (outerSignal !== undefined)
264
+ outerSignal.removeEventListener("abort", forwardAbort);
265
+ }
255
266
  }
256
267
  export function withBrainCallGuardrail(streamFn, limitMs, ref) {
257
268
  return async (model, context, options) => {
@@ -279,10 +290,12 @@ export function withBrainCallGuardrail(streamFn, limitMs, ref) {
279
290
  }
280
291
  if (step.done === true)
281
292
  gate.disarm();
293
+ else if (step.value.type === "done" || step.value.type === "error")
294
+ gate.answered();
282
295
  return step;
283
296
  },
284
297
  return: async () => {
285
- gate.disarm();
298
+ gate.abandon();
286
299
  const release = it.return;
287
300
  if (release !== undefined) {
288
301
  Promise.resolve(release.call(it)).catch(() => undefined);
@@ -1,6 +1,8 @@
1
1
  import type { AgentTool } from "../internal/harness-types.js";
2
+ import { type CredentialEchoSite } from "./credential-echo.js";
2
3
  import { type PeerSeat } from "./peer-seat.js";
3
4
  import { type HostFloor } from "./host-floor.js";
5
+ import { type McpFailureFields } from "./mcp-failure.js";
4
6
  import type { A2aServerSpec, ToolEffect } from "./types.js";
5
7
  /** The hard per-skill description bound (ruled 2026-08-03: ~2KiB). */
6
8
  export declare const A2A_SKILL_DESCRIPTION_MAX_CHARS = 2048;
@@ -28,8 +30,15 @@ export interface A2aToolAxis {
28
30
  }
29
31
  /** design/99 §E9 equivalent for A2A — a per-peer projection of THIS materialization. A2A holds no
30
32
  * connection (every call is its own HTTPS request), so `ready` means "the card was fetched and its
31
- * skills were mounted at prepare time", never "the peer is alive right now". */
32
- export interface A2aPeerStatus {
33
+ * skills were mounted at prepare time", never "the peer is alive right now".
34
+ *
35
+ * A `failed` row carries the SAME failure record an MCP server's failed status carries ({@link McpFailureFields}: `errorCode`, one of
36
+ * `MCP_FAILURE_KINDS`; `delivered`; `authorization` for `unauthorized`), so a consumer keys on one vocabulary for both protocols. The
37
+ * members are present iff the row records a failure that was thrown. A peer seat that did not furnish a send reads
38
+ * `credential_unavailable` (`unauthorized` when it answered that the principal is not authorized); an error the A2A client itself raises
39
+ * for a non-2xx status or a JSON-RPC error carries no structure the classifier reads and reads `unknown` — `error` is the text to show,
40
+ * never the field to key on. */
41
+ export interface A2aPeerStatus extends Partial<McpFailureFields> {
33
42
  name: string;
34
43
  status: "ready" | "failed";
35
44
  /** The card's self-declared name, neutralized + bounded (it rides consumer-rendered lines). */
@@ -40,8 +49,9 @@ export interface A2aPeerStatus {
40
49
  toolNames?: string[];
41
50
  error?: string;
42
51
  }
43
- /** One per-peer entry of {@link MaterializedA2a.refresh}. */
44
- export interface A2aRefreshResult {
52
+ /** One per-peer entry of {@link MaterializedA2a.refresh}. A `failed` entry whose refresh threw carries the failure record
53
+ * ({@link A2aPeerStatus}); the entry for a name no peer is declared under (nothing was attempted) carries none. */
54
+ export interface A2aRefreshResult extends Partial<McpFailureFields> {
45
55
  peer: string;
46
56
  /** The peer's namespaced-name prefix — the consumer's SPLICE DOMAIN for a wholesale swap (the same
47
57
  * self-healing prefix domain the MCP refresh receipt hands out). Present on every entry. */
@@ -98,4 +108,4 @@ export declare class A2aRpcError extends Error {
98
108
  * `allSettled` keeps it fail-open: one unreachable peer is a skipped peer with a warning, never a task
99
109
  * that cannot start.
100
110
  */
101
- export declare function materializeA2aTools(specs: readonly A2aServerSpec[], principal?: string, signal?: AbortSignal, hostFloor?: HostFloor, peerSeat?: PeerSeat): Promise<MaterializedA2a>;
111
+ export declare function materializeA2aTools(specs: readonly A2aServerSpec[], principal?: string, signal?: AbortSignal, hostFloor?: HostFloor, given?: PeerSeat, onCredentialEchoed?: (peer: string, where: CredentialEchoSite) => void): Promise<MaterializedA2a>;
package/dist/core/a2a.js CHANGED
@@ -2,9 +2,10 @@ import { randomUUID } from "node:crypto";
2
2
  import { Type } from "typebox";
3
3
  import { A2A_TASK_STATES } from "./a2a-task-state.js";
4
4
  import { assertEndpointBound, carriesDeclaredHeaders, resolveProtocolHttpHeaders, underDeclaredHeaders } from "./protocol-http-auth.js";
5
- import { PeerCarrier, carriedHttpHeaders, peerSeatMissing } from "./peer-seat.js";
5
+ import { carrierEcho, echoAnnouncer, erasedEcho, nameEchoes } from "./credential-echo.js";
6
+ import { PeerCarrier, carriedHttpHeaders, peerSeatMissing, receivePeerSeat } from "./peer-seat.js";
6
7
  import { fetchFollowing, hopRefusal, HOST_FLOOR_REFUSED_CODE } from "./host-floor.js";
7
- import { describeHttpTransportFailure } from "./mcp-failure.js";
8
+ import { classifyMcpFailure, describeHttpTransportFailure, failureFields } from "./mcp-failure.js";
8
9
  import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName } from "./protocol-naming.js";
9
10
  import { A2A_NAMESPACE } from "./protocol-table.js";
10
11
  import { judgeEntryToolAxes, refusedDeclarer, snapshotDeclaredEntry } from "./locked-config.js";
@@ -49,6 +50,9 @@ const A2A_ERROR_CODE_NAMES = new Map([
49
50
  const A2A_TERMINAL_STATES = new Set(["completed", "canceled", "failed", "rejected"]);
50
51
  const A2A_CALLER_TURN_STATES = new Set(["input-required", "auth-required"]);
51
52
  const A2A_STATE_SET = new Set(A2A_TASK_STATES);
53
+ function peerFailureFields(err) {
54
+ return failureFields(classifyMcpFailure(err, { phase: "connect", transport: "http" }));
55
+ }
52
56
  export class A2aRpcError extends Error {
53
57
  code;
54
58
  constructor(peer, method, code, message) {
@@ -250,7 +254,7 @@ async function discoverCardBody(spec, t, signal) {
250
254
  }
251
255
  throw new Error(`a2a: peer "${peerLabel}" published no agent card — none of ${tried.join(", ")} answered`);
252
256
  }
253
- function negotiateEndpoint(peer, card, fallbackUrl) {
257
+ function negotiateEndpoint(peer, card, fallbackUrl, echo) {
254
258
  const offered = [];
255
259
  const primaryUrl = asString(card["url"]) ?? fallbackUrl;
256
260
  offered.push({ url: primaryUrl, transport: asString(card["preferredTransport"]) ?? A2A_JSONRPC_TRANSPORT });
@@ -266,6 +270,8 @@ function negotiateEndpoint(peer, card, fallbackUrl) {
266
270
  for (const candidate of offered) {
267
271
  if (candidate.transport.toUpperCase() !== A2A_JSONRPC_TRANSPORT)
268
272
  continue;
273
+ if (candidate.url !== fallbackUrl && nameEchoes(candidate.url, echo, "agent_card"))
274
+ continue;
269
275
  let absolute;
270
276
  try {
271
277
  absolute = new URL(candidate.url, fallbackUrl);
@@ -277,36 +283,42 @@ function negotiateEndpoint(peer, card, fallbackUrl) {
277
283
  continue;
278
284
  return absolute.toString();
279
285
  }
280
- const names = offered.map((o) => inlineUntrusted(o.transport, 40)).join(", ");
286
+ const names = offered.map((o) => inlineUntrusted(erasedEcho(o.transport, echo, "agent_card"), 40)).join(", ");
281
287
  throw new Error(`a2a: peer "${inlineUntrusted(peer, A2A_ID_MAX_CHARS)}" advertises no ${A2A_JSONRPC_TRANSPORT} interface (offered: ${names || "none"}) — this client speaks ${A2A_JSONRPC_TRANSPORT} only`);
282
288
  }
283
- function readCard(peer, body, fallbackUrl) {
289
+ function readCard(peer, body, fallbackUrl, echo) {
284
290
  const card = asRecord(body);
285
291
  if (card === undefined) {
286
292
  throw new Error(`a2a: peer "${inlineUntrusted(peer, A2A_ID_MAX_CHARS)}" served an agent card that is not a JSON object`);
287
293
  }
294
+ const text = (raw) => erasedEcho(raw, echo, "agent_card");
288
295
  const skills = [];
289
296
  for (const entry of asArray(card["skills"]) ?? []) {
290
297
  const rec = asRecord(entry);
291
298
  if (rec === undefined)
292
299
  continue;
293
300
  const id = asString(rec["id"]);
294
- if (id === undefined || id === "")
301
+ if (id === undefined || id === "" || nameEchoes(id, echo, "agent_card"))
295
302
  continue;
296
- const tags = (asArray(rec["tags"]) ?? []).filter((v) => typeof v === "string");
297
- const examples = (asArray(rec["examples"]) ?? []).filter((v) => typeof v === "string");
303
+ const tags = (asArray(rec["tags"]) ?? []).filter((v) => typeof v === "string").map((v) => text(v));
304
+ const examples = (asArray(rec["examples"]) ?? []).filter((v) => typeof v === "string").map((v) => text(v));
305
+ const name = text(asString(rec["name"]));
306
+ const description = text(asString(rec["description"]));
298
307
  skills.push({
299
308
  id,
300
- ...(asString(rec["name"]) !== undefined ? { name: asString(rec["name"]) } : {}),
301
- ...(asString(rec["description"]) !== undefined ? { description: asString(rec["description"]) } : {}),
309
+ ...(name !== undefined ? { name } : {}),
310
+ ...(description !== undefined ? { description } : {}),
302
311
  ...(tags.length > 0 ? { tags } : {}),
303
312
  ...(examples.length > 0 ? { examples } : {}),
304
313
  });
305
314
  }
315
+ const name = asString(card["name"]);
316
+ const nameHolds = name !== undefined && nameEchoes(name, echo, "agent_card");
317
+ const description = text(asString(card["description"]));
306
318
  return {
307
- ...(asString(card["name"]) !== undefined ? { name: inlineUntrusted(asString(card["name"]), A2A_CARD_NAME_MAX_CHARS) } : {}),
308
- ...(asString(card["description"]) !== undefined ? { description: inlineUntrusted(asString(card["description"]), A2A_CARD_DESCRIPTION_MAX_CHARS) } : {}),
309
- endpoint: negotiateEndpoint(peer, card, fallbackUrl),
319
+ ...(name !== undefined && !nameHolds ? { name: inlineUntrusted(name, A2A_CARD_NAME_MAX_CHARS) } : {}),
320
+ ...(description !== undefined ? { description: inlineUntrusted(description, A2A_CARD_DESCRIPTION_MAX_CHARS) } : {}),
321
+ endpoint: negotiateEndpoint(peer, card, fallbackUrl, echo),
310
322
  skills,
311
323
  };
312
324
  }
@@ -565,7 +577,7 @@ function declaredPeerOf(declared, index) {
565
577
  const judged = judgeEntryToolAxes(snapshot, "a2a");
566
578
  return judged.ok ? { spec: judged.entry } : { spec: snapshot, refusal: judged.error };
567
579
  }
568
- async function materializePeer(peer, principal, lifecycle, signal, floor, seat) {
580
+ async function materializePeer(peer, principal, lifecycle, signal, floor, seat, announceEcho) {
569
581
  if ("refusal" in peer)
570
582
  throw peer.refusal;
571
583
  const { spec } = peer;
@@ -579,7 +591,7 @@ async function materializePeer(peer, principal, lifecycle, signal, floor, seat)
579
591
  const carrier = new PeerCarrier(seat, identity, principal, "a2a", spec.principalHeader !== undefined);
580
592
  const asks = { carrier, principalHeader: spec.principalHeader, principal, declared, floor };
581
593
  const discovery = { peer: spec.name, endpoint: spec.url, ...asks };
582
- const card = readCard(spec.name, await discoverCardBody(spec, discovery, signal), spec.url);
594
+ const card = readCard(spec.name, await discoverCardBody(spec, discovery, signal), spec.url, carrierEcho(carrier, (where) => announceEcho(spec.name, where)));
583
595
  assertEndpointBound(A2A_NAMESPACE.id, spec.name, card.endpoint, declared, carrier.last?.headers === undefined ? undefined : { ...carrier.last.headers });
584
596
  const transport = { peer: spec.name, endpoint: card.endpoint, ...asks };
585
597
  const tools = [];
@@ -611,7 +623,8 @@ function asPeerWarning(spec, err) {
611
623
  warning.code = "a2a.peer_unavailable";
612
624
  return warning;
613
625
  }
614
- export async function materializeA2aTools(specs, principal, signal, hostFloor, peerSeat) {
626
+ export async function materializeA2aTools(specs, principal, signal, hostFloor, given, onCredentialEchoed) {
627
+ const peerSeat = receivePeerSeat(given, "materializeA2aTools peerSeat");
615
628
  const peers = specs.map((spec, index) => declaredPeerOf(spec, index));
616
629
  if (peers.length > 0) {
617
630
  const collision = findNamespacePrefixCollision(A2A_NAMESPACE, peers.map((p) => p.spec.name));
@@ -629,7 +642,8 @@ export async function materializeA2aTools(specs, principal, signal, hostFloor, p
629
642
  const toolAxes = [];
630
643
  const warnings = [];
631
644
  const statuses = [];
632
- const settled = await Promise.allSettled(peers.map((peer) => materializePeer(peer, principal, lifecycle, signal, hostFloor, peerSeat)));
645
+ const announceEcho = echoAnnouncer(onCredentialEchoed);
646
+ const settled = await Promise.allSettled(peers.map((peer) => materializePeer(peer, principal, lifecycle, signal, hostFloor, peerSeat, announceEcho)));
633
647
  for (let i = 0; i < peers.length; i++) {
634
648
  const spec = peers[i].spec;
635
649
  const outcome = settled[i];
@@ -640,7 +654,7 @@ export async function materializeA2aTools(specs, principal, signal, hostFloor, p
640
654
  }
641
655
  else {
642
656
  warnings.push(asPeerWarning(spec, outcome.reason));
643
- statuses.push({ name: spec.name, status: "failed", error: inlineUntrusted(thrownText(outcome.reason), A2A_ERROR_TEXT_MAX_CHARS) });
657
+ statuses.push({ name: spec.name, status: "failed", ...peerFailureFields(outcome.reason), error: inlineUntrusted(thrownText(outcome.reason), A2A_ERROR_TEXT_MAX_CHARS) });
644
658
  }
645
659
  }
646
660
  return {
@@ -664,7 +678,7 @@ export async function materializeA2aTools(specs, principal, signal, hostFloor, p
664
678
  }
665
679
  const previous = statuses.find((s) => s.name === spec.name)?.toolNames ?? [];
666
680
  try {
667
- const fresh = await materializePeer(target, principal, lifecycle, signal, hostFloor, peerSeat);
681
+ const fresh = await materializePeer(target, principal, lifecycle, signal, hostFloor, peerSeat, announceEcho);
668
682
  const names = fresh.tools.map((t) => t.name);
669
683
  results.push({
670
684
  peer: spec.name,
@@ -688,6 +702,7 @@ export async function materializeA2aTools(specs, principal, signal, hostFloor, p
688
702
  toolCount: previous.length,
689
703
  added: [],
690
704
  removed: [],
705
+ ...peerFailureFields(err),
691
706
  error: inlineUntrusted(thrownText(err), A2A_ERROR_TEXT_MAX_CHARS),
692
707
  });
693
708
  }
@@ -6,6 +6,7 @@
6
6
  import type { ThinkingLevel } from "../internal/harness.js";
7
7
  import type { ModelRef } from "./model-seat.js";
8
8
  import type { TaskSpec } from "./task-spec.js";
9
+ import type { McpServerSpec } from "./mcp-server-spec.js";
9
10
  /**
10
11
  * A declarative, reusable named sub-agent (design/38 1B). Hand a set to {@link createSubagentTool} and the
11
12
  * model picks one (by `whenToUse`) to delegate to; the chosen definition's config builds the child task.
@@ -42,6 +43,25 @@ export interface AgentDefinition {
42
43
  * invocable via the `skill` tool. Deployment-trusted, same trust tier as `systemPrompt`.
43
44
  */
44
45
  skills?: SkillSpec[];
46
+ /**
47
+ * The MCP servers this agent connects to when it runs — declarations in exactly the {@link TaskSpec.mcp} form, judged by the
48
+ * door that judges a task's own list (the same refusal, code and sentence) where the definition is received — the delegation
49
+ * tool's assembly, the {@link TaskSpec.agents} door, a workflow's `agentType` fold — and again at the leg's own prepare (an
50
+ * `mcp` configuration lock or a compliance deny of MCP servers refuses the leg there). They are declared on the leg spawned as
51
+ * this agent alone: its children inherit them as they inherit any server their spawner declares, and the spawning run never
52
+ * mounts them. Three rules decide what the leg holds:
53
+ * - the leg is declared the servers it inherits from the spawning run first (none when the delegation tool has a pool of its
54
+ * own), then each of these whose tool namespace (`mcp__<server>__`) none of those holds — a name the spawning run already
55
+ * declares for the leg names the spawning run's server; two of these under one namespace refuse the leg's mount, as a task's pair does;
56
+ * - this definition's own {@link allowTools}, when it has one, admits every tool of each server declared here (its own
57
+ * {@link denyTools} still wins), so an agent restricted to a few tools still holds the servers it brought;
58
+ * - every layer above the leg (the spawning run's tool lists and the ones it inherits) still decides, as for any tool of the
59
+ * leg: a server the leg's valve leaves nothing of — no tool of its namespace, no cross-server resource reader — is not dialled
60
+ * (the leg's wiring manifest reads it `skipped`).
61
+ * A server reference by name alone (another configuration's server) has no form here: a definition that should hold a server
62
+ * its spawning run declares names it in {@link allowTools} (`mcp__<server>`). Deployment-trusted, like {@link systemPrompt}.
63
+ */
64
+ mcp?: McpServerSpec[];
45
65
  /**
46
66
  * F7 (per-agent `background`, OR-ed into
47
67
  * the background predicate, GA/ungated): `true` = this agent ALWAYS launches on the background lane
@@ -22,6 +22,8 @@ export interface AllowEntryInertDetail {
22
22
  readonly verdict?: Exclude<RuleToolNameVerdict["kind"], "current">;
23
23
  readonly guidance?: string;
24
24
  readonly currentName?: string;
25
+ /** `tool_name` / `unmintable_segment` only: the refusal is the ALLOW-side ambiguity of an MCP name ({@link peerReadingsOf}), not a segment the mint never produces. */
26
+ readonly ambiguous?: true;
25
27
  readonly valueType?: string;
26
28
  /** Where the spelling of a `near_miss` comes from, when the station that read it reads more than the run's roster
27
29
  * ({@link NearMissCarrier}); absent ⇒ the roster the run mounts. A sentence only — never a field of a wire detail. */
@@ -132,12 +132,12 @@ export function autoStripped(compiled, call, allShell) {
132
132
  case "shell":
133
133
  return true;
134
134
  case "tool":
135
- case "covering":
136
135
  return call !== undefined && answersTo(call, isShellFaceToolName);
137
136
  case "command":
138
137
  if (allShell)
139
138
  return true;
140
139
  return compiled.rule.match === "pattern" ? commandPatternMayRun(compiled.rule.command, AUTO_STRIPPED_PROGRAMS) : shellContentStripped(shellRuleContent(compiled.rule));
140
+ case "covering":
141
141
  case "path":
142
142
  case "name":
143
143
  case "domain":
@@ -474,6 +474,8 @@ export function inertEntryPhrase(e) {
474
474
  case "unprefixed_namespace":
475
475
  return 'tool_name: a "__" name with no protocol prefix';
476
476
  case "unmintable_segment":
477
+ if (e.ambiguous === true && e.guidance !== undefined)
478
+ return `tool_name: ${e.guidance}${spelling !== undefined ? ` Write "${spelling}"` : ""}`;
477
479
  return `tool_name: a namespaced name with a segment the engine never mints${spelling !== undefined ? `, write "${spelling}"` : ""}`;
478
480
  default: {
479
481
  const exhaustive = e.verdict;
@@ -77,8 +77,6 @@ export type ResultCodeTableCoversEveryHostFailure = AssertAllKeysHandled<Exclude
77
77
  /** The one result code that is not a host word: the host threw, timed out, or answered outside its contract. */
78
78
  export declare const ARTIFACT_HOST_ERROR_CODE = "artifact.host_error";
79
79
  export type ArtifactResultCode = (typeof ARTIFACT_FAILURE_RESULT_CODE)[ArtifactHostFailureCode] | typeof ARTIFACT_HOST_ERROR_CODE;
80
- /** The `details.type` card the Artifact tool mints on every result. */
81
- export declare const ARTIFACT_CARD = "artifact";
82
80
  /**
83
81
  * What a host declares at mount time. Invariants (a violation refuses the mount and announces
84
82
  * `config.artifact_host_invalid`): `actions` non-empty, duplicate-free, within {@link ARTIFACT_ACTIONS},
@@ -38,7 +38,6 @@ export const ARTIFACT_FAILURE_RESULT_CODE = {
38
38
  refused: "artifact.refused",
39
39
  };
40
40
  export const ARTIFACT_HOST_ERROR_CODE = "artifact.host_error";
41
- export const ARTIFACT_CARD = "artifact";
42
41
  const isPositiveInt = (v) => typeof v === "number" && Number.isSafeInteger(v) && v > 0;
43
42
  const wordOf = (set, v) => typeof v === "string" && set.includes(v);
44
43
  export function readArtifactHostCapabilities(host) {
@@ -16,6 +16,14 @@ export declare const AUTO_MODE_DEFAULT_TIMEOUT_MS = 180000;
16
16
  * would only make the person wait out the rung's budget and hear "timed out" for a failure that was not one.
17
17
  */
18
18
  export declare const AUTO_MODE_CLASSIFIER_MAX_RETRIES = 4;
19
+ /**
20
+ * How many CONSECUTIVE classifications must end on a rung's rate limit (an HTTP 429 that outlived the brain's own
21
+ * {@link AUTO_MODE_CLASSIFIER_MAX_RETRIES} backoffs) before that rung is not asked again for the rest of the run, when
22
+ * `RunnerDeps.autoMode.rateLimitBreakAfter` is omitted. Each such classification has already slept the whole
23
+ * backoff ladder, so the number is the wall time a rate-limited seat may still cost before the walk starts behind it:
24
+ * three, the same count the denial limit hands a run to a person after.
25
+ */
26
+ export declare const AUTO_MODE_RATE_LIMIT_BREAK_AFTER_DEFAULT = 3;
19
27
  /**
20
28
  * What an arming RECORDING that carries no `timeoutMs` meant when it was written: the default of its day. Every
21
29
  * recipe minted since the deadline moved to 60 s MATERIALISES its bound, so an absent recorded knob dates the
@@ -1,5 +1,6 @@
1
1
  export const AUTO_MODE_DEFAULT_TIMEOUT_MS = 180_000;
2
2
  export const AUTO_MODE_CLASSIFIER_MAX_RETRIES = 4;
3
+ export const AUTO_MODE_RATE_LIMIT_BREAK_AFTER_DEFAULT = 3;
3
4
  export const AUTO_MODE_RECORDED_ABSENT_TIMEOUT_MS = 15_000;
4
5
  export const AUTO_MODE_DEFAULT_WINDOW_MAX_ENTRIES = 40;
5
6
  export const AUTO_MODE_DEFAULT_WINDOW_MAX_CHARS = 2_000;
@@ -67,7 +67,8 @@ export type AutoModeRebuildResult = {
67
67
  * overrides / settings-deny rules / session context, plus the engine's cross-session lane rule when
68
68
  * the recipe says the arming leg spliced it), the transcript-window bounds and the round-trip
69
69
  * timeout — i.e. every input the ancestor's own `createAutoModeDecider` call had except the model leg.
70
- * A decider carries no state between rounds, so there is no ancestor state to reproduce or to withhold.
70
+ * The rebuilt decider is one rung, which never retires (the rate-limit memory only a rung with another behind it keeps), so it
71
+ * carries no state between rounds and there is no ancestor state to reproduce or to withhold.
71
72
  *
72
73
  * NOT reproduced: this build's PROMPT ASSETS are its own. The recipe records the deployment's
73
74
  * overrides, so the assembled prompt is checked against the digest the arming recorded — a fleet running
@@ -59,6 +59,12 @@ export declare function isAutoModeTimeoutMs(v: unknown): v is number;
59
59
  * refusal carrying `config.auto_mode_timeout_invalid`. There is no OFF spelling: the budget bounds how long a
60
60
  * permission gate waits, and a gate with no bound is not a setting this knob offers. */
61
61
  export declare function autoModeTimeoutMsOf(v: unknown): number;
62
+ /** Read the retirement knob (`RunnerDeps.autoMode.rateLimitBreakAfter` / `AutoModeDeciderOptions.rateLimitBreakAfter`):
63
+ * absent ⇒ {@link AUTO_MODE_RATE_LIMIT_BREAK_AFTER_DEFAULT}; a safe integer of at least 1 ⇒ itself; ANYTHING ELSE
64
+ * (`0`, a negative, a fraction, NaN, ±Infinity, a string, an object) ⇒ a loud refusal carrying
65
+ * `config.auto_mode_rate_limit_break_invalid` — never clamped, never read as the default. There is no OFF
66
+ * spelling: a deployment that wants the seat asked for longer states a larger count. */
67
+ export declare function autoModeRateLimitBreakAfterOf(v: unknown): number;
62
68
  /** The classifier's verdict over one pending `ask`. Every arm may carry the classification's model
63
69
  * attribution ({@link AutoModeClassifierRound}), present iff the decider was wired with a candidate ladder. */
64
70
  export type AutoModeVerdict = ({
@@ -136,6 +142,15 @@ export declare const AUTO_MODE_ROUND_NOT_ASKED_CODE = "auto_mode.round_not_asked
136
142
  export declare function autoModeRoundNotAsked(reason: unknown): Error & {
137
143
  code: string;
138
144
  };
145
+ /**
146
+ * The word for "this rung's dispatch ended on the provider's RATE LIMIT" — an HTTP 429 that outlived the brain's own
147
+ * backoff ladder. A classify hook throws an error carrying this `code` (the same carrier as
148
+ * {@link AUTO_MODE_ROUND_NOT_ASKED_CODE}: a `code` on the thrown error, so any hook — including one this package never
149
+ * constructed — can raise it without importing a constructor). The decider reads it for one thing, the rung's
150
+ * RETIREMENT count (see the header's RATE-LIMIT RETIREMENT); the rung's verdict is the `unavailable` / `error` every
151
+ * leg failure already is.
152
+ */
153
+ export declare const AUTO_MODE_RUNG_RATE_LIMITED_CODE = "auto_mode.rung_rate_limited";
139
154
  /**
140
155
  * Why a rung did not settle the classification, or `undefined` when it SETTLED it and the ladder stops — the
141
156
  * ONE predicate behind the advance (there is no `if (fallback)` arm anywhere).
@@ -276,6 +291,13 @@ export interface AutoModeDeciderOptions<T = void> {
276
291
  * (`config.auto_mode_timeout_invalid`, {@link autoModeTimeoutMsOf}) — never clamped, never read as the
277
292
  * default, and there is no OFF: a permission gate always has a bound. */
278
293
  timeoutMs?: number;
294
+ /** How many CONSECUTIVE classifications must end on one rung's rate limit ({@link AUTO_MODE_RUNG_RATE_LIMITED_CODE})
295
+ * before that rung is not asked again for the rest of this decider's life — see the header's RATE-LIMIT
296
+ * RETIREMENT. Omitted ⇒ {@link AUTO_MODE_RATE_LIMIT_BREAK_AFTER_DEFAULT}. A present value that is not a whole number
297
+ * of at least 1 is REFUSED at construction (`config.auto_mode_rate_limit_break_invalid`,
298
+ * {@link autoModeRateLimitBreakAfterOf}) — never clamped, never read as the default. Inert on a one-rung ladder:
299
+ * only a rung with a rung behind it retires. */
300
+ rateLimitBreakAfter?: number;
279
301
  /**
280
302
  * Fired once per `decide` call with the verdict the gate is about to act on and the wall time it waited
281
303
  * (`ms`, integer ≥ 0; a timed-out classification reads the deadline, one that walked two rungs the whole
@@ -302,6 +324,17 @@ export interface AutoModeClassified {
302
324
  /** The classification's model attribution, present exactly when the decider was wired with a candidate ladder
303
325
  * ({@link AutoModeClassifierRound}) — the same object the verdict carries. */
304
326
  classifier?: AutoModeClassifierRound;
327
+ /** One entry per rung this classification RETIRED — the classification whose rate-limited dispatch was a rung's
328
+ * `rateLimitBreakAfter`-th in a row, so each retired rung is reported on exactly one classification: which rung stopped
329
+ * being asked (`rung`, its model `model`), the model the walk reaches after it (`to`) and the count that tripped it
330
+ * (`consecutive`; always the configured bound). ABSENT on every other classification, including those that walk
331
+ * behind an already-retired rung. */
332
+ rateLimitBreaks?: readonly {
333
+ readonly rung: number;
334
+ readonly model: string;
335
+ readonly to: string;
336
+ readonly consecutive: number;
337
+ }[];
305
338
  }
306
339
  export interface AutoModeDecider {
307
340
  /** Never rejects. Any internal failure surfaces as `unavailable`/`parse_error` (fail-closed). */
@@ -311,9 +344,10 @@ export interface AutoModeDecider {
311
344
  * host implements by hand. */
312
345
  readonly timeoutMs?: number;
313
346
  }
314
- /** The per-run decider: timeout + fail-closed error mapping, nothing carried between rounds. One instance per
315
- * run (it binds the run's model leg and assembled prompt); a round that failed says nothing about the next,
316
- * which asks the model again. */
347
+ /** The per-run decider: timeout + fail-closed error mapping, and nothing carried between rounds but the rate-limit
348
+ * retirement of a rung that has another behind it. One instance per run (it binds the run's model leg and assembled
349
+ * prompt); a round that failed says nothing about the next, which asks the model again — a rung that was
350
+ * rate-limited `rateLimitBreakAfter` times in a row is the one exception. */
317
351
  export declare function createAutoModeDecider<T = void>(opts: AutoModeDeciderOptions<T>): AutoModeDecider;
318
352
  /** The deployment's bounds for the denial limit (`RunnerDeps.autoMode.denialLimit`). Every member
319
353
  * optional; an omitted member takes its CC default. A present member with a bad value is REFUSED
@@ -445,13 +479,14 @@ export interface AutoModeDenialTracker {
445
479
  };
446
480
  }
447
481
  export declare function autoModeDenialLimitOf(v: unknown): Required<AutoModeDenialLimitOptions>;
448
- /** The deployment face's three value knobs, read by their one readers — every leg's prepare runs it while
482
+ /** The deployment face's four value knobs, read by their one readers — every leg's prepare runs it while
449
483
  * `RunnerDeps.autoMode` is present, whatever mode the leg starts in, so a bad knob refuses the run before a steer or a
450
484
  * parent's live ceiling can reach an arming that would have refused it. */
451
485
  export declare function screenAutoModeKnobs(face: {
452
486
  readonly timeoutMs?: unknown;
453
487
  readonly classifierFallback?: unknown;
454
488
  readonly denialLimit?: unknown;
489
+ readonly rateLimitBreakAfter?: unknown;
455
490
  }): void;
456
491
  /** Build the per-run tracker over {@link autoModeDenialLimitOf}'s bounds (a bad knob refuses there). */
457
492
  export declare function createAutoModeDenialTracker(opts?: AutoModeDenialLimitOptions): AutoModeDenialTracker;