@sema-agent/core 7.57.0 → 7.59.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 (399) hide show
  1. package/CHANGELOG.md +1161 -0
  2. package/README.md +6 -4
  3. package/dist/agents/cc-peer-directory.js +8 -8
  4. package/dist/agents/child-model-seat.d.ts +4 -2
  5. package/dist/agents/child-model-seat.js +5 -3
  6. package/dist/agents/peer-directory.d.ts +9 -0
  7. package/dist/agents/peer-directory.js +6 -2
  8. package/dist/agents/send-message-tool.js +21 -12
  9. package/dist/agents/subagent-steps.js +2 -4
  10. package/dist/agents/subagent.js +33 -34
  11. package/dist/brain/anthropic.js +161 -45
  12. package/dist/brain/errors.d.ts +9 -3
  13. package/dist/brain/errors.js +7 -1
  14. package/dist/brain/failover.js +2 -1
  15. package/dist/brain/open-responses.js +3 -3
  16. package/dist/brain/openai.js +103 -53
  17. package/dist/brain/provider-dialect.d.ts +11 -0
  18. package/dist/brain/provider-dialect.js +5 -2
  19. package/dist/brain/reasoning-request.js +5 -4
  20. package/dist/brain/reasoning.d.ts +19 -0
  21. package/dist/brain/reasoning.js +17 -2
  22. package/dist/brain/request-route.d.ts +4 -1
  23. package/dist/brain/request-route.js +4 -1
  24. package/dist/brain/route-adjudicator.d.ts +84 -18
  25. package/dist/brain/route-adjudicator.js +89 -22
  26. package/dist/brain/route-conformance.js +1 -1
  27. package/dist/brain/stream-engine.js +84 -49
  28. package/dist/brain/stream-shared.d.ts +30 -0
  29. package/dist/brain/stream-shared.js +34 -1
  30. package/dist/brain/timeout.d.ts +62 -5
  31. package/dist/brain/timeout.js +93 -6
  32. package/dist/core/a2a.d.ts +2 -1
  33. package/dist/core/a2a.js +23 -10
  34. package/dist/core/account-row.d.ts +61 -0
  35. package/dist/core/account-row.js +51 -0
  36. package/dist/core/advisor-verdict.d.ts +2 -1
  37. package/dist/core/advisor-verdict.js +1 -1
  38. package/dist/core/allow-entry.d.ts +20 -7
  39. package/dist/core/allow-entry.js +18 -9
  40. package/dist/core/approval-object.d.ts +29 -15
  41. package/dist/core/approval-object.js +47 -19
  42. package/dist/core/ask-origin.d.ts +21 -2
  43. package/dist/core/ask-origin.js +5 -1
  44. package/dist/core/auto-compaction.d.ts +4 -0
  45. package/dist/core/auto-compaction.js +2 -2
  46. package/dist/core/auto-mode-directive.d.ts +29 -5
  47. package/dist/core/auto-mode-directive.js +38 -8
  48. package/dist/core/background-agent-store.d.ts +16 -3
  49. package/dist/core/checkpoint-requirements.d.ts +19 -1
  50. package/dist/core/checkpoint-requirements.js +5 -1
  51. package/dist/core/checkpoint-store.d.ts +85 -23
  52. package/dist/core/checkpoint-store.js +31 -9
  53. package/dist/core/child-clamp-seats.d.ts +29 -0
  54. package/dist/core/child-clamp-seats.js +56 -1
  55. package/dist/core/compliance.d.ts +2 -2
  56. package/dist/core/compliance.js +1 -1
  57. package/dist/core/effective-path-target.d.ts +8 -2
  58. package/dist/core/effective-path-target.js +8 -3
  59. package/dist/core/engine-notice.d.ts +99 -9
  60. package/dist/core/engine-notice.js +19 -5
  61. package/dist/core/fs-write-gate-policy.d.ts +4 -2
  62. package/dist/core/fs-write-gate-policy.js +7 -3
  63. package/dist/core/gate-fold.js +7 -4
  64. package/dist/core/gate-lanes.js +19 -6
  65. package/dist/core/gate-outcome.d.ts +32 -3
  66. package/dist/core/gate-outcome.js +19 -1
  67. package/dist/core/git-worktree-env.d.ts +53 -11
  68. package/dist/core/git-worktree-env.js +96 -12
  69. package/dist/core/governance-codes.d.ts +9 -1
  70. package/dist/core/governance-codes.js +13 -0
  71. package/dist/core/hooks.d.ts +35 -4
  72. package/dist/core/hooks.js +17 -11
  73. package/dist/core/human-input-projection.d.ts +1 -0
  74. package/dist/core/human-input-projection.js +3 -0
  75. package/dist/core/image-admission.d.ts +6 -5
  76. package/dist/core/image-admission.js +18 -14
  77. package/dist/core/locked-config.d.ts +20 -3
  78. package/dist/core/locked-config.js +40 -3
  79. package/dist/core/mailbox-store.d.ts +45 -1
  80. package/dist/core/mailbox-store.js +53 -9
  81. package/dist/core/mcp-call-meta.d.ts +66 -0
  82. package/dist/core/mcp-call-meta.js +103 -0
  83. package/dist/core/mcp-connection-pool.d.ts +3 -1
  84. package/dist/core/mcp-connection-pool.js +3 -1
  85. package/dist/core/mcp-failure.d.ts +117 -15
  86. package/dist/core/mcp-failure.js +71 -3
  87. package/dist/core/mcp-probe.d.ts +4 -0
  88. package/dist/core/mcp-probe.js +1 -1
  89. package/dist/core/mcp-server-link.d.ts +27 -3
  90. package/dist/core/mcp-server-link.js +25 -1
  91. package/dist/core/mcp-server-spec.d.ts +46 -18
  92. package/dist/core/mcp-server-spec.js +1 -18
  93. package/dist/core/mcp.d.ts +16 -20
  94. package/dist/core/mcp.js +112 -55
  95. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  96. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  97. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  98. package/dist/core/memory-engine/consolidation.js +1 -0
  99. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  100. package/dist/core/memory-engine/distiller.js +2 -2
  101. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  102. package/dist/core/memory-engine/dual-root.js +44 -1
  103. package/dist/core/memory-engine/engine.d.ts +67 -14
  104. package/dist/core/memory-engine/engine.js +384 -212
  105. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  106. package/dist/core/memory-engine/export-bundle.js +23 -4
  107. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  108. package/dist/core/memory-engine/file-backend.js +290 -117
  109. package/dist/core/memory-engine/index.d.ts +1 -1
  110. package/dist/core/memory-engine/layout.d.ts +59 -11
  111. package/dist/core/memory-engine/layout.js +190 -40
  112. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  113. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  114. package/dist/core/memory-engine/scope-contract.d.ts +45 -4
  115. package/dist/core/memory-engine/scope-contract.js +80 -11
  116. package/dist/core/memory-engine/sync-client.d.ts +9 -1
  117. package/dist/core/memory-engine/sync-client.js +31 -8
  118. package/dist/core/memory-engine/sync.d.ts +5 -0
  119. package/dist/core/memory-engine/types.d.ts +6 -0
  120. package/dist/core/mode-policy.d.ts +8 -5
  121. package/dist/core/mode-policy.js +5 -4
  122. package/dist/core/mods/classic-events.d.ts +5 -1
  123. package/dist/core/mods/host.js +1 -1
  124. package/dist/core/mods/kernel/dispatch.d.ts +3 -0
  125. package/dist/core/mods/kernel/dispatch.js +12 -9
  126. package/dist/core/mods/kernel/events.d.ts +6 -1
  127. package/dist/core/mods/kernel/events.js +2 -2
  128. package/dist/core/mods/kernel/registration.d.ts +9 -1
  129. package/dist/core/mods/kernel/registration.js +3 -0
  130. package/dist/core/mods/kernel/site-rules.d.ts +3 -0
  131. package/dist/core/mods/kernel/site-rules.js +10 -0
  132. package/dist/core/mods/package.d.ts +23 -0
  133. package/dist/core/mods/package.js +118 -0
  134. package/dist/core/mods/stations.d.ts +33 -12
  135. package/dist/core/mods/stations.js +45 -11
  136. package/dist/core/mods/tool-call.d.ts +5 -1
  137. package/dist/core/mods/tool-call.js +13 -4
  138. package/dist/core/parent-spec-seat.d.ts +8 -3
  139. package/dist/core/parent-spec-seat.js +2 -0
  140. package/dist/core/park-selfcheck.js +6 -0
  141. package/dist/core/path-guard-rows.d.ts +20 -0
  142. package/dist/core/path-guard-rows.js +11 -0
  143. package/dist/core/peer-seat.d.ts +248 -0
  144. package/dist/core/peer-seat.js +439 -0
  145. package/dist/core/permission-rule-consent.js +10 -4
  146. package/dist/core/permission-rule-model.d.ts +16 -0
  147. package/dist/core/permission-rule-model.js +1 -1
  148. package/dist/core/present-plan-tool.d.ts +20 -3
  149. package/dist/core/present-plan-tool.js +48 -4
  150. package/dist/core/protocol-http-auth.d.ts +40 -29
  151. package/dist/core/protocol-http-auth.js +30 -32
  152. package/dist/core/redaction-marks.d.ts +16 -0
  153. package/dist/core/redaction-marks.js +16 -0
  154. package/dist/core/redaction-passes.js +8 -9
  155. package/dist/core/resume-startup-cause.js +1 -0
  156. package/dist/core/retention.d.ts +41 -15
  157. package/dist/core/retention.js +59 -12
  158. package/dist/core/rewrite-rejudge.d.ts +38 -0
  159. package/dist/core/rewrite-rejudge.js +42 -2
  160. package/dist/core/roles.d.ts +34 -2
  161. package/dist/core/roles.js +43 -4
  162. package/dist/core/run-origin.d.ts +40 -0
  163. package/dist/core/run-origin.js +37 -0
  164. package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
  165. package/dist/core/runner/advertised-writable-dirs.js +126 -0
  166. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  167. package/dist/core/runner/announce-once-ledger.js +4 -2
  168. package/dist/core/runner/call-hook-stations.js +2 -2
  169. package/dist/core/runner/compaction-restate.d.ts +15 -6
  170. package/dist/core/runner/compaction-restate.js +28 -2
  171. package/dist/core/runner/contracts.d.ts +33 -21
  172. package/dist/core/runner/credential-origin-seat.js +4 -3
  173. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  174. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  175. package/dist/core/runner/decide-continuation.d.ts +2 -2
  176. package/dist/core/runner/gate-exit.d.ts +30 -8
  177. package/dist/core/runner/gate-exit.js +15 -8
  178. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  179. package/dist/core/runner/image-removed-seat.js +19 -0
  180. package/dist/core/runner/inline-image.js +1 -1
  181. package/dist/core/runner/memory-consolidation-driver.js +3 -3
  182. package/dist/core/runner/park-commit.d.ts +1 -1
  183. package/dist/core/runner/park-commit.js +3 -0
  184. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  185. package/dist/core/runner/prepare-ask-lane.js +2 -1
  186. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  187. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -5
  188. package/dist/core/runner/prepare-caps-and-workflow.js +3 -1
  189. package/dist/core/runner/prepare-config-doors.d.ts +8 -5
  190. package/dist/core/runner/prepare-config-doors.js +14 -10
  191. package/dist/core/runner/prepare-context-lane.js +2 -0
  192. package/dist/core/runner/prepare-delegation-surface.d.ts +8 -0
  193. package/dist/core/runner/prepare-delegation-surface.js +16 -18
  194. package/dist/core/runner/prepare-gate-stations.js +1 -1
  195. package/dist/core/runner/prepare-hands-readface.d.ts +11 -3
  196. package/dist/core/runner/prepare-hands-readface.js +9 -1
  197. package/dist/core/runner/prepare-inherited-gate.d.ts +1 -3
  198. package/dist/core/runner/prepare-inherited-gate.js +14 -27
  199. package/dist/core/runner/prepare-memory.d.ts +3 -0
  200. package/dist/core/runner/prepare-memory.js +26 -37
  201. package/dist/core/runner/prepare-park-ask.d.ts +1 -1
  202. package/dist/core/runner/prepare-park-ask.js +2 -1
  203. package/dist/core/runner/prepare-policy-chain.d.ts +7 -7
  204. package/dist/core/runner/prepare-policy-chain.js +18 -15
  205. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  206. package/dist/core/runner/prepare-project-context.js +2 -2
  207. package/dist/core/runner/prepare-prompt-inputs.d.ts +1 -1
  208. package/dist/core/runner/prepare-prompt-inputs.js +8 -19
  209. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
  210. package/dist/core/runner/prepare-protocol-tools.js +11 -3
  211. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  212. package/dist/core/runner/prepare-run-refs.js +4 -1
  213. package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
  214. package/dist/core/runner/prepare-suspend-saga.js +2 -1
  215. package/dist/core/runner/prepare-task.js +28 -13
  216. package/dist/core/runner/prepare-wiring-manifest.d.ts +2 -1
  217. package/dist/core/runner/prepare-wiring-manifest.js +4 -3
  218. package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
  219. package/dist/core/runner/prepare-workspace-restore.js +4 -4
  220. package/dist/core/runner/reply-pricing.d.ts +30 -0
  221. package/dist/core/runner/reply-pricing.js +19 -0
  222. package/dist/core/runner/resume-admission.js +5 -3
  223. package/dist/core/runner/resume-apply.js +6 -1
  224. package/dist/core/runner/resume-checkpoint-screen.js +2 -0
  225. package/dist/core/runner/resume-policy-outcome.js +5 -5
  226. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  227. package/dist/core/runner/role-seat-defaulted.js +40 -0
  228. package/dist/core/runner/run-brain-sinks.js +2 -0
  229. package/dist/core/runner/run-harness-handlers.d.ts +3 -4
  230. package/dist/core/runner/run-harness-handlers.js +1 -8
  231. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  232. package/dist/core/runner/run-identity-wiring.js +6 -4
  233. package/dist/core/runner/run-leg.d.ts +2 -0
  234. package/dist/core/runner/run-leg.js +42 -29
  235. package/dist/core/runner/run-notification-lane.js +3 -0
  236. package/dist/core/runner/run-stop-and-final-verify.js +2 -2
  237. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  238. package/dist/core/runner/run-terminal-adoption.js +9 -3
  239. package/dist/core/runner/run-turn-boundary.js +77 -70
  240. package/dist/core/runner/runtask.d.ts +1 -1
  241. package/dist/core/runner/runtask.js +2 -2
  242. package/dist/core/runner/side-call-account.d.ts +1 -1
  243. package/dist/core/runner/side-call-account.js +3 -18
  244. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  245. package/dist/core/runner/sub-agent-deny-lists.js +10 -0
  246. package/dist/core/runner/terminal-account.js +3 -3
  247. package/dist/core/runner/tool-end-body.js +2 -1
  248. package/dist/core/runner/tool-occurrence.d.ts +5 -2
  249. package/dist/core/runner/tool-occurrence.js +4 -3
  250. package/dist/core/runner/turn-attachments.d.ts +26 -22
  251. package/dist/core/runner/turn-attachments.js +24 -26
  252. package/dist/core/runner/write-protection-station.d.ts +8 -2
  253. package/dist/core/runner/write-protection-station.js +2 -0
  254. package/dist/core/runner-deps.d.ts +3 -3
  255. package/dist/core/secret-env.d.ts +32 -2
  256. package/dist/core/secret-env.js +65 -3
  257. package/dist/core/sensitive-path-policy.js +9 -10
  258. package/dist/core/session-log-transfer.d.ts +24 -0
  259. package/dist/core/session-log-transfer.js +166 -0
  260. package/dist/core/session-policy-store.d.ts +3 -1
  261. package/dist/core/session-policy-store.js +13 -9
  262. package/dist/core/session-store.d.ts +86 -24
  263. package/dist/core/session-store.js +162 -24
  264. package/dist/core/session.d.ts +92 -1
  265. package/dist/core/shell-read-silence.js +1 -0
  266. package/dist/core/side-query.d.ts +11 -1
  267. package/dist/core/side-query.js +9 -0
  268. package/dist/core/skill-grant-binding.d.ts +31 -2
  269. package/dist/core/skill-grant-binding.js +31 -1
  270. package/dist/core/skill-grant.d.ts +8 -5
  271. package/dist/core/skill-grant.js +6 -6
  272. package/dist/core/steer-replay.d.ts +4 -2
  273. package/dist/core/steer-replay.js +2 -1
  274. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  275. package/dist/core/store-contracts/checkpoint-store-contract.js +20 -2
  276. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  277. package/dist/core/store-contracts/session-repo-contract.js +112 -5
  278. package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
  279. package/dist/core/store-contracts/session-store-contract.js +236 -2
  280. package/dist/core/synthetic-read-verdict.js +2 -1
  281. package/dist/core/task-event.d.ts +92 -8
  282. package/dist/core/task-notification.js +16 -10
  283. package/dist/core/task-registry-agent.js +1 -0
  284. package/dist/core/task-registry-shared.d.ts +7 -1
  285. package/dist/core/task-spec.d.ts +49 -1
  286. package/dist/core/task-stream.d.ts +2 -1
  287. package/dist/core/terminal-cause.d.ts +11 -1
  288. package/dist/core/tool-catalog-entries.js +1 -0
  289. package/dist/core/tool-check-reading.d.ts +1 -0
  290. package/dist/core/tool-check-reading.js +3 -3
  291. package/dist/core/tool-policy.d.ts +16 -0
  292. package/dist/core/tool-result-store.d.ts +17 -10
  293. package/dist/core/tool-result-store.js +3 -1
  294. package/dist/core/tool-roster.d.ts +112 -5
  295. package/dist/core/tool-roster.js +42 -1
  296. package/dist/core/tool-spec.d.ts +3 -1
  297. package/dist/core/types.d.ts +3 -3
  298. package/dist/core/types.js +1 -1
  299. package/dist/core/untrusted-egress.d.ts +0 -2
  300. package/dist/core/untrusted-egress.js +10 -14
  301. package/dist/core/user-attachment.js +1 -1
  302. package/dist/core/wiring-manifest.d.ts +18 -6
  303. package/dist/core/wiring-manifest.js +4 -3
  304. package/dist/core/workspace-snapshot.d.ts +44 -0
  305. package/dist/core/workspace-snapshot.js +34 -0
  306. package/dist/core/write-protect.d.ts +43 -3
  307. package/dist/core/write-protect.js +43 -16
  308. package/dist/engine/compaction/compaction.js +29 -3
  309. package/dist/engine/execution-env/node-execution-env.d.ts +4 -3
  310. package/dist/engine/execution-env/node-execution-env.js +24 -23
  311. package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
  312. package/dist/engine/harness/agent-harness.d.ts +30 -2
  313. package/dist/engine/harness/agent-harness.js +43 -12
  314. package/dist/engine/harness/messages.d.ts +3 -1
  315. package/dist/engine/harness/messages.js +3 -2
  316. package/dist/engine/harness/types.d.ts +56 -7
  317. package/dist/engine/harness/types.js +5 -1
  318. package/dist/engine/llm/rejected-images.d.ts +46 -0
  319. package/dist/engine/llm/rejected-images.js +54 -0
  320. package/dist/engine/llm/tool-turns.d.ts +2 -1
  321. package/dist/engine/llm/types.d.ts +30 -10
  322. package/dist/engine/llm/types.js +1 -1
  323. package/dist/engine/loop/agent-loop.d.ts +8 -0
  324. package/dist/engine/loop/agent-loop.js +52 -15
  325. package/dist/engine/loop/types.d.ts +3 -1
  326. package/dist/engine/session/import-validate.js +3 -0
  327. package/dist/engine/session/memory-repo.d.ts +17 -9
  328. package/dist/engine/session/memory-repo.js +44 -34
  329. package/dist/engine/session/path-to-root.d.ts +38 -0
  330. package/dist/engine/session/path-to-root.js +39 -0
  331. package/dist/engine/session/repo-utils.d.ts +22 -4
  332. package/dist/engine/session/repo-utils.js +49 -1
  333. package/dist/engine/session/storage-base.d.ts +10 -1
  334. package/dist/engine/session/storage-base.js +11 -22
  335. package/dist/index.d.ts +29 -16
  336. package/dist/index.js +21 -11
  337. package/dist/internal/harness-types.d.ts +2 -2
  338. package/dist/internal/harness.d.ts +3 -2
  339. package/dist/internal/harness.js +2 -2
  340. package/dist/internal/llm.d.ts +1 -0
  341. package/dist/orchestration/workflow-observe.d.ts +17 -1
  342. package/dist/orchestration/workflow-observe.js +20 -0
  343. package/dist/orchestration/workflow-types.d.ts +32 -7
  344. package/dist/orchestration/workflow.js +739 -489
  345. package/dist/shell/counting-pass.d.ts +50 -0
  346. package/dist/shell/counting-pass.js +502 -0
  347. package/dist/shell/lex.d.ts +4 -2
  348. package/dist/shell/lex.js +93 -34
  349. package/dist/shell/shell-words.d.ts +1 -1
  350. package/dist/shell/shell-words.js +7 -6
  351. package/dist/stores/file/index.d.ts +4 -1
  352. package/dist/stores/file/index.js +4 -1
  353. package/dist/stores/file/mailbox-store.js +6 -10
  354. package/dist/stores/file/session-store.d.ts +15 -8
  355. package/dist/stores/file/session-store.js +28 -13
  356. package/dist/tools/fs/fs-bash.d.ts +6 -0
  357. package/dist/tools/fs/fs-bash.js +6 -3
  358. package/dist/tools/fs/fs-write.d.ts +6 -3
  359. package/dist/tools/fs/fs-write.js +8 -7
  360. package/dist/tools/fs/index.d.ts +3 -0
  361. package/dist/tools/fs/index.js +7 -3
  362. package/dist/tools/fs/program-read-model.d.ts +13 -0
  363. package/dist/tools/fs/program-read-model.js +15 -0
  364. package/dist/tools/fs/program-read-model.rows.js +1 -1
  365. package/dist/tools/fs/read-deny.d.ts +13 -10
  366. package/dist/tools/fs/read-deny.js +25 -5
  367. package/dist/tools/fs/read-floor.d.ts +19 -0
  368. package/dist/tools/fs/read-floor.js +23 -0
  369. package/dist/tools/fs/safety.js +40 -8
  370. package/dist/tools/fs/search.js +6 -24
  371. package/dist/tools/fs/shell-read-check.d.ts +9 -2
  372. package/dist/tools/fs/shell-read-check.js +61 -16
  373. package/dist/tools/fs/shell-read-establish.js +2 -1
  374. package/dist/tools/fs/shell-read-identity.js +1 -1
  375. package/dist/tools/fs/shell-read-judge.d.ts +26 -9
  376. package/dist/tools/fs/shell-read-judge.js +10 -6
  377. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  378. package/dist/tools/fs/shell-read-plan.js +22 -15
  379. package/dist/tools/fs/shell-read-start.js +1 -0
  380. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  381. package/dist/tools/fs/shell-reentry-text.js +25 -3
  382. package/dist/tools/monitor.d.ts +4 -0
  383. package/dist/tools/monitor.js +2 -0
  384. package/dist/tools/worktree.d.ts +42 -15
  385. package/dist/tools/worktree.js +60 -32
  386. package/package.json +5 -2
  387. package/test/export-surface.snapshot.json +149 -1
  388. package/wire-changes/core-stores-sql@7.58.0.json +29 -0
  389. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  390. package/wire-changes/core@7.58.0.json +2188 -0
  391. package/wire-changes/core@7.59.0.json +2459 -0
  392. package/wire-changes/mods-kernel@7.58.0.json +81 -0
  393. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  394. package/wire-changes/primitives@7.58.0.json +29 -0
  395. package/wire-changes/primitives@7.59.0.json +29 -0
  396. package/dist/primitives/credential-ref.d.ts +0 -89
  397. package/dist/primitives/credential-ref.js +0 -125
  398. package/dist/primitives/index.d.ts +0 -2
  399. package/dist/primitives/index.js +0 -1
@@ -1,29 +1,35 @@
1
1
  import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
2
2
  import { StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
3
3
  import { proxyTunnelRefusedSentence, readConnectFailure } from "../brain/errors.js";
4
+ import { PeerAuthorizationRefused, PeerSeatFailure } from "./peer-seat.js";
4
5
  export const MCP_FAILURE_KINDS = Object.freeze([
5
6
  "connect_refused",
6
7
  "connection_failed",
7
8
  "connection_closed",
9
+ "unauthorized",
8
10
  "http_status",
9
11
  "not_mcp_response",
10
12
  "spawn_failed",
11
13
  "timeout",
12
14
  "protocol",
13
15
  "invalid_config",
16
+ "credential_unavailable",
14
17
  "unknown",
15
18
  ]);
19
+ export const MCP_AUTHORIZATION_REASONS = Object.freeze(["rejected", "scope", "none"]);
16
20
  export const MCP_DELIVERY_VERDICTS = Object.freeze(["yes", "no", "unknown"]);
17
21
  export const DELIVERED_BY_KIND = {
18
22
  connect_refused: "no",
19
23
  connection_failed: "unknown",
20
24
  connection_closed: "unknown",
25
+ unauthorized: "unknown",
21
26
  http_status: "unknown",
22
27
  not_mcp_response: "unknown",
23
28
  spawn_failed: "no",
24
29
  timeout: "unknown",
25
30
  protocol: "yes",
26
31
  invalid_config: "no",
32
+ credential_unavailable: "no",
27
33
  unknown: "unknown",
28
34
  };
29
35
  export const MCP_LIVENESS_STATES = Object.freeze(["reachable", "unreachable", "unknown"]);
@@ -31,23 +37,38 @@ export const LIVENESS_BY_FAILURE_KIND = {
31
37
  connect_refused: "unreachable",
32
38
  connection_failed: "unreachable",
33
39
  connection_closed: "unreachable",
40
+ unauthorized: "unknown",
34
41
  http_status: "unknown",
35
42
  not_mcp_response: "unknown",
36
43
  spawn_failed: "unreachable",
37
44
  timeout: "unreachable",
38
45
  protocol: "reachable",
39
46
  invalid_config: undefined,
47
+ credential_unavailable: undefined,
40
48
  unknown: "unknown",
41
49
  };
42
50
  export function livenessOf(outcome, observedAt) {
43
51
  if (outcome === "completed")
44
52
  return { state: "reachable", observedAt };
53
+ if (outcome === "unsent")
54
+ return undefined;
45
55
  const state = LIVENESS_BY_FAILURE_KIND[outcome];
46
56
  if (state === undefined)
47
57
  return undefined;
48
58
  return state === "unreachable" ? { state, observedAt, errorCode: outcome } : { state, observedAt };
49
59
  }
50
- const CONNECT_KEEPS_THE_TABLE_VERDICT = new Set(["protocol", "http_status"]);
60
+ const CONNECT_KEEPS_THE_TABLE_VERDICT = new Set(["protocol", "http_status", "unauthorized"]);
61
+ export function failureFields(of) {
62
+ const kind = "kind" in of ? of.kind : of.errorCode;
63
+ if (kind === undefined)
64
+ return {};
65
+ return {
66
+ errorCode: kind,
67
+ ...(of.delivered !== undefined ? { delivered: of.delivered } : {}),
68
+ ...(of.httpStatus !== undefined ? { httpStatus: of.httpStatus } : {}),
69
+ ...(of.authorization !== undefined ? { authorization: { ...of.authorization } } : {}),
70
+ };
71
+ }
51
72
  const NETWORK_CODES_NEVER_DELIVERED = new Set([
52
73
  "ECONNREFUSED",
53
74
  "ENOTFOUND",
@@ -74,6 +95,16 @@ export function networkErrorCode(err, depth = 0) {
74
95
  const isNodeErrCode = (code) => code.startsWith("ERR_");
75
96
  const isDeclarationFault = (code) => code === "ERR_INVALID_URL" || (typeof code === "string" && code.startsWith("config."));
76
97
  export const FAILURE_CLASSIFIER = [
98
+ {
99
+ name: "peer seat answered the principal is not authorized",
100
+ when: (err) => err instanceof PeerSeatFailure && err.reason === "unauthorized",
101
+ reads: (err) => ({ kind: "unauthorized", authorization: authorizationOf("none", err.authorizeUrl, undefined), unsent: true }),
102
+ },
103
+ {
104
+ name: "peer seat did not furnish the request",
105
+ when: (err) => err instanceof PeerSeatFailure,
106
+ reads: () => ({ kind: "credential_unavailable", unsent: true }),
107
+ },
77
108
  {
78
109
  name: "sdk connection closed",
79
110
  when: (err) => err instanceof McpError && err.code === ErrorCode.ConnectionClosed,
@@ -89,6 +120,13 @@ export const FAILURE_CLASSIFIER = [
89
120
  when: (err) => err instanceof McpError,
90
121
  reads: () => ({ kind: "protocol" }),
91
122
  },
123
+ {
124
+ name: "http endpoint refused the authorization",
125
+ when: (err) => err instanceof StreamableHTTPError && (err.code === 401 || err instanceof PeerAuthorizationRefused),
126
+ reads: (err) => err instanceof PeerAuthorizationRefused
127
+ ? { kind: "unauthorized", authorization: authorizationOf(err.reason, err.authorizeUrl, err.resourceMetadataUrl) }
128
+ : { kind: "unauthorized", authorization: { reason: "rejected" } },
129
+ },
92
130
  {
93
131
  name: "http endpoint answered a status",
94
132
  when: (err) => err instanceof StreamableHTTPError && typeof err.code === "number" && err.code > 0,
@@ -142,9 +180,37 @@ export const FAILURE_CLASSIFIER = [
142
180
  },
143
181
  ];
144
182
  export function classifyMcpFailure(err, at) {
145
- const read = classOf(err, at);
183
+ return readMcpFailure(err, at).failure;
184
+ }
185
+ export function readMcpFailure(err, at) {
186
+ const { unsent, ...read } = classOf(err, at);
146
187
  const dialled = at.phase === "connect" && !CONNECT_KEEPS_THE_TABLE_VERDICT.has(read.kind);
147
- return { ...read, delivered: dialled ? "no" : DELIVERED_BY_KIND[read.kind] };
188
+ return { failure: { ...read, delivered: unsent === true || dialled ? "no" : DELIVERED_BY_KIND[read.kind] }, exchange: unsent === true ? "unsent" : read.kind };
189
+ }
190
+ function authorizationOf(reason, authorizeUrl, resourceMetadataUrl) {
191
+ return { reason, ...(authorizeUrl !== undefined ? { authorizeUrl } : {}), ...(resourceMetadataUrl !== undefined ? { resourceMetadataUrl } : {}) };
192
+ }
193
+ export function whereToAuthorize(authorizeUrl) {
194
+ return authorizeUrl !== undefined ? `at ${authorizeUrl}` : "through the deployment's connector settings";
195
+ }
196
+ export function needsAuthorizationArm(entries, max) {
197
+ const named = entries.filter((f) => f.authorization !== undefined);
198
+ if (named.length === 0)
199
+ return undefined;
200
+ const withUrl = named.filter((f) => f.authorization?.authorizeUrl !== undefined).length;
201
+ const where = withUrl === named.length ? "at the address listed beside it" : withUrl === 0 ? whereToAuthorize(undefined) : `at the address listed beside it, or, for a server listed without one, ${whereToAuthorize(undefined)}`;
202
+ const lines = named.slice(0, max).map((f) => `${f.name}${f.authorization?.authorizeUrl !== undefined ? ` — authorize ${whereToAuthorize(f.authorization.authorizeUrl)}` : ""}`);
203
+ return (`The following MCP servers require authentication before their tools can be used:\n${lines.join("\n")}${named.length > max ? `\n…and ${named.length - max} more` : ""}\n\n` +
204
+ `You cannot start the authorization flow yourself. If the user's request depends on one of these servers (even if they didn't name it explicitly), ` +
205
+ `or they ask about it, tell them that it needs to be authorized — ${where} — and that the capability is unavailable until they do. ` +
206
+ `Otherwise carry on with the request and do not mention these servers. Do not ask the user for authorization codes, tokens, or callback URLs.`);
207
+ }
208
+ export function unauthorizedLine(what, serverLabel, a, renewed, writeTail) {
209
+ const owed = `The user needs to authorize this server${a.reason === "scope" ? " for the access this request needs" : ""} ${whereToAuthorize(a.authorizeUrl)}; its capability is unavailable until they do. Do not ask the user for authorization codes, tokens, or callback URLs.`;
210
+ if (a.reason === "none")
211
+ return `${what} was not sent to MCP server "${serverLabel}": the deployment holds no authorization of this user for it. ${owed} The request was not delivered, so the server did not execute it.`;
212
+ const refused = `${what} on MCP server "${serverLabel}" was refused ${a.reason === "scope" ? "for insufficient scope (HTTP 403)" : "as unauthorized (HTTP 401)"}`;
213
+ return renewed ? `${refused}; the deployment has since answered another credential, which a new call carries — this call was not sent again. If that call is refused too: ${owed}${writeTail}` : `${refused}. ${owed}${writeTail}`;
148
214
  }
149
215
  function classOf(err, at) {
150
216
  for (const rule of FAILURE_CLASSIFIER)
@@ -176,10 +242,12 @@ export function describeHttpTransportFailure(err, at = { phase: "request" }) {
176
242
  case "connection_failed":
177
243
  return { condition: `the connection to its HTTP endpoint failed (${networkErrorCode(err)})`, delivered: f.delivered };
178
244
  case "connection_closed":
245
+ case "unauthorized":
179
246
  case "spawn_failed":
180
247
  case "timeout":
181
248
  case "protocol":
182
249
  case "invalid_config":
250
+ case "credential_unavailable":
183
251
  case "unknown":
184
252
  return undefined;
185
253
  }
@@ -1,5 +1,6 @@
1
1
  import { type McpFailureKind } from "./mcp-failure.js";
2
2
  import type { McpServerSpec, OnElicit } from "./mcp-server-spec.js";
3
+ import type { PeerSeat } from "./peer-seat.js";
3
4
  import type { WiringManifestMcpEntry } from "./wiring-manifest.js";
4
5
  /** One server's probe reading, beside its manifest row. `connectMs` is wall time this probe measured
5
6
  * for THIS server's dial — the spawn/handshake, the initial `tools/list` walk and the intake, ending
@@ -56,6 +57,9 @@ export interface McpProbeOptions {
56
57
  signal?: AbortSignal;
57
58
  /** The elicitation seat, for a caller that has a human behind it. Default: decline everything. */
58
59
  onElicit?: OnElicit;
60
+ /** The peer seat a prepared leg dials with (`RunnerDeps.peerSeat`): what each request carries. Absent ⇒ nothing is carried, and a
61
+ * server whose declaration names `credentials` reads `failed` (`invalid_config`, `config.peer_seat_missing`). */
62
+ peerSeat?: PeerSeat;
59
63
  /** Abort reading, stated once: the call rejects with the signal's own reason when that reason is an
60
64
  * Error (a bare `abort()` supplies a DOMException named `AbortError`) and with this module's own
61
65
  * `AbortError` otherwise — a face that throws a string is a face no `catch` can read. A condition
@@ -74,7 +74,7 @@ export async function probeMcpServers(specs, opts = {}) {
74
74
  const entry = declared[i];
75
75
  const started = performance.now();
76
76
  const elapsed = () => Math.round(performance.now() - started);
77
- const dial = materializeMcpTools([entry], opts.principal, onElicit);
77
+ const dial = materializeMcpTools([entry], opts.principal, onElicit, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, opts.peerSeat);
78
78
  const verdict = await raceDial(dial, timeoutMs, signal);
79
79
  if (verdict.kind === "settled") {
80
80
  const found = verdict.handle.statuses.find((s) => s.name === entry.name);
@@ -13,7 +13,16 @@
13
13
  * replacement, so a late 404 never closes a connection other calls have moved to.
14
14
  */
15
15
  import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
16
- import type { McpExchangeOutcome } from "./mcp-failure.js";
16
+ import { type McpAuthorization, type McpExchangeOutcome, type McpFailure, type McpFailureSite } from "./mcp-failure.js";
17
+ /**
18
+ * One request failure, read once and told to the server's two writers: its reach ({@link ServerHealth.observe}) always, and — when
19
+ * `answer` (this failure is the request's answer: the lane sends nothing again) — the authorization the user owes
20
+ * ({@link ServerHealth.owed}). Returns the record.
21
+ */
22
+ export declare function observedFailure(err: unknown, site: McpFailureSite, health: ServerHealth | undefined, answer: boolean): McpFailure;
23
+ /** A tool call's FINAL failure (the translated error, whose `details` is the record the one reading stamped) tells the server's
24
+ * announcer what the user owes — the call lane's one announcement, made once its attempts are over. */
25
+ export declare function owedByAnswer(err: unknown, health: ServerHealth): void;
17
26
  /** Mutable per-server liveness flag, shared between a server's tool closures and its transport-close hook.
18
27
  * `pendingElicitations` (RB-199 FO-1 codex review): a live count of in-flight `onElicit` waits on THIS
19
28
  * server — the idle watchdog ({@link armMcpIdleWatchdog}) reads it before aborting a call (incremented when the wait starts,
@@ -37,6 +46,9 @@ export interface ServerHealth {
37
46
  * outage either, and the in-flight calls it fails belong to a connection we chose to replace.
38
47
  */
39
48
  observe?: (outcome: McpExchangeOutcome) => void;
49
+ /** The other thing a request can learn: its ANSWER was a refusal as `unauthorized`, so the user owes this authorization — the
50
+ * materialization's once-per-server announcer, filled by the merge stage beside `observe` (the same lifecycle silence applies). */
51
+ owed?: (authorization: McpAuthorization) => void;
40
52
  pendingElicitations: number;
41
53
  /** Stamped on EVERY
42
54
  * elicitation close (finally, unconditional — not just when the count returns to 0). Closes a race
@@ -131,8 +143,11 @@ export interface McpLiveConnection {
131
143
  export interface McpServerLink {
132
144
  /** The connection the materialization holds for the server now; `undefined` while it holds none (a re-dial's old one is gone and the new one has not landed, or the last dial failed). */
133
145
  live(): McpLiveConnection | undefined;
134
- /** Recover the session `lost` lost: join the re-dial running for the server, or start one while `lost` is still the live connection. Settles when there is nothing left to wait for. */
135
- recover(lost: McpLiveConnection): Promise<unknown>;
146
+ /** Replace `lost`: join the re-dial running for the server, or start one while `lost` is still the live connection. Settles when there
147
+ * is nothing left to wait for. `cause`: the server dropped the session (`session`, the default), or the peer seat's pieces the
148
+ * connection was started with expired (`expired`: the calls in flight on it settle before it is closed, and the run tree's pooled
149
+ * connection is replaced once for all its holders). */
150
+ recover(lost: McpLiveConnection, cause?: "session" | "expired"): Promise<unknown>;
136
151
  }
137
152
  /** Why a tool may not be sent on a live connection: its listing mints the tool another gate or none (`changed`), or no listing of the connection has reached it (`unreached`). */
138
153
  export type McpListingRefusal = "changed" | "unreached";
@@ -153,6 +168,15 @@ export declare class Resendable {
153
168
  * {@link McpListingRefusal} answer only a call that was never sent.
154
169
  */
155
170
  export declare function callThroughLink<R extends object>(link: McpServerLink, name: string, gate: string, signal: AbortSignal | undefined, send: (on: McpLiveConnection, resent: boolean) => Promise<R | Resendable>, gone: () => never): Promise<R | McpListingRefusal>;
171
+ /** What judges a call a refusal turned away: the live connection's listing, the operator's revocation list, the declaration a tool was mounted with. */
172
+ export type RefusalJudge = "listing" | "revocation" | "declaration";
173
+ /**
174
+ * THE closing sentence of an MCP call refused before it was sent: what the refusal covers (this call) and what judges a later call,
175
+ * never how that call will come out — a host's re-dial, refresh or un-revoke lands between two calls, and the call after it is
176
+ * judged against what it took. The listing's refusal, a revoked server's four outlets and the task-required one end with it; no
177
+ * site words it again. (A server whose transport is gone has its own text, `throwDeadServer`.)
178
+ */
179
+ export declare function refusalScope(judge: RefusalJudge): string;
156
180
  /** The answer to a call {@link reach} refused before it was sent: the pre-send refusal record (`delivered: "no"`; `code` beside `error`, as the revocation refusal's). */
157
181
  export declare function listingRefusal(refusal: McpListingRefusal, remoteName: string, server: string): {
158
182
  content: Array<{
@@ -1,5 +1,20 @@
1
+ import { readMcpFailure } from "./mcp-failure.js";
1
2
  import { UNPROVEN_GATE } from "./mcp-listing-drift.js";
3
+ import { readMember } from "./thrown-value.js";
2
4
  import { inlineUntrusted } from "./untrusted-text.js";
5
+ export function observedFailure(err, site, health, answer) {
6
+ const { failure, exchange } = readMcpFailure(err, site);
7
+ health?.observe?.(exchange);
8
+ if (answer && failure.authorization !== undefined)
9
+ health?.owed?.(failure.authorization);
10
+ return failure;
11
+ }
12
+ export function owedByAnswer(err, health) {
13
+ const details = readMember(err, "details");
14
+ const a = readMember(details, "code") === "unauthorized" ? readMember(details, "authorization") : undefined;
15
+ if (typeof a === "object" && a !== null)
16
+ health.owed?.(a);
17
+ }
3
18
  export const IDLE_WATCHDOG_ABORT_REASON = Symbol("mcp-idle-watchdog-abort");
4
19
  export function armMcpIdleWatchdog(health, idleMs, outerSignal) {
5
20
  const idleController = new AbortController();
@@ -89,11 +104,20 @@ export async function callThroughLink(link, name, gate, signal, send, gone) {
89
104
  throw again.error;
90
105
  return again;
91
106
  }
107
+ const REFUSAL_JUDGES = {
108
+ listing: { rule: "each later call to this tool is checked again against the connection's latest listing", standing: "" },
109
+ revocation: { rule: "each later call to this server is checked again against the operator's current revocation list", standing: "This server stays on this run's tool roster. " },
110
+ declaration: { rule: "each later call to this tool is judged by the declaration of the listing it was mounted from, until a refresh or reconnect of the server mints the tool anew", standing: "" },
111
+ };
112
+ export function refusalScope(judge) {
113
+ const j = REFUSAL_JUDGES[judge];
114
+ return `${j.standing}This refusal is for this call only: ${j.rule}.`;
115
+ }
92
116
  export function listingRefusal(refusal, remoteName, server) {
93
117
  const changed = refusal === "changed";
94
118
  const code = changed ? "mcp.tool_declaration_changed" : "mcp.tool_listing_unreached";
95
119
  return {
96
- content: [{ type: "text", text: `The call to tool ${inlineUntrusted(remoteName)} was refused before it was sent: MCP server "${inlineUntrusted(server)}" ${changed ? "no longer declares this tool the way it was mounted (its safety declaration changed, or a complete listing no longer lists it)" : "has not listed this tool since it was reconnected (the re-listing stopped before it reached the tool), so whether the server still declares it the way it was mounted is unknown"}. The server did not execute it. Every call to this tool is refused the same way until a listing of the connection reaches the tool, so don't retry it.` }],
120
+ content: [{ type: "text", text: `The call to tool ${inlineUntrusted(remoteName)} was refused before it was sent: MCP server "${inlineUntrusted(server)}" ${changed ? "no longer declares this tool the way it was mounted (its safety declaration changed, or a complete listing no longer lists it)" : "has not listed this tool since it was reconnected (the re-listing stopped before it reached the tool), so whether the server still declares it the way it was mounted is unknown"}. The server did not execute it. ${refusalScope("listing")}` }],
97
121
  details: { error: code, code, delivered: "no", server },
98
122
  terminate: false,
99
123
  isError: true,
@@ -1,4 +1,5 @@
1
1
  import { type ReceiptFault } from "./mods/kernel/receive.js";
2
+ import type { CredentialRef } from "@sema-agent/primitives";
2
3
  import type { ToolContentOrigin, ToolEffect } from "./tool-spec.js";
3
4
  import type { ToolFamily, ToolHostTarget, ToolPathTarget, ToolRenderHints, ToolRuleFace } from "./tool-face.js";
4
5
  /** Definition of an MCP server to connect to for the duration of one task, then discard. */
@@ -13,24 +14,34 @@ export interface McpServerSpec {
13
14
  * declaring tier without keeping a side table keyed on names. Optional; absent stays absent.
14
15
  */
15
16
  source?: string;
17
+ /**
18
+ * Who the server is: the whole start command (stdio) or endpoint (http), and at most one opaque credential reference
19
+ * (`credentials`, read by the one reader `readCredentialRef` at every entrance — an unknown kind refuses the entry with
20
+ * `config.credential_ref_invalid`; the engine resolves nothing). A declaration carries no value: the pieces a request
21
+ * carries — an http request's credential headers, a stdio child's environment — are answered per send by the deployment's
22
+ * peer seat ({@link RunnerDeps.peerSeat}). A `credentials` reference with no seat wired refuses the entry
23
+ * (`config.peer_seat_missing`); a declaration carrying the retired value members `headers` / `env` is refused at every
24
+ * entrance (`config.credential_in_declaration`).
25
+ */
16
26
  transport: {
17
27
  kind: "stdio";
18
28
  command: string;
19
29
  args?: string[];
20
- env?: Record<string, string>;
30
+ credentials?: CredentialRef;
21
31
  } | {
22
32
  kind: "http";
23
33
  url: string;
24
- /** Static headers sent on every request (e.g. an auth bearer for the MCP server itself). */
25
- headers?: Record<string, string>;
34
+ credentials?: CredentialRef;
26
35
  /**
27
36
  * Per-task **end-user principal** header (design/62). When set, the Runner injects the running task's
28
37
  * authenticated {@link TaskSpec.principal} as this header (e.g. `"X-Agent-Principal"`) on every call to
29
38
  * this server's tools, so the MCP server can enforce per-user RBAC. Absent {@link TaskSpec.principal}
30
- * ⇒ the header is **not** sent (the MCP server must default to deny/public, never admin). A static `headers`
31
- * entry under the same name in any case refuses this server at its dial (`config.protocol_header_collision`,
32
- * header names being case-insensitive). The principal is Runner-held and the model/worker can neither read
33
- * nor set it (it is not a tool argument) — see {@link TaskSpec.principal}.
39
+ * ⇒ the header is **not** sent (the MCP server must default to deny/public, never admin). A header the
40
+ * peer seat answers under the same name in any case is the seat's fault, and that request is not sent
41
+ * (`config.protocol_header_collision`, header names being case-insensitive). The principal is Runner-held and the
42
+ * model/worker can neither read nor set it (it is not a tool argument) — see {@link TaskSpec.principal}. The name is
43
+ * neither the engine's own `MCP_ASSERTION_HEADER` nor a name the MCP transport writes itself (any case): naming one
44
+ * refuses this server at its dial.
34
45
  */
35
46
  principalHeader?: string;
36
47
  };
@@ -172,6 +183,21 @@ export interface McpServerSpec {
172
183
  * The no-run probe has no clock of its own: each startup phase carries this same bound (a caller's `timeoutMs` is an overall ceiling beside it).
173
184
  */
174
185
  startupTimeoutMs?: number;
186
+ /**
187
+ * Opt in to the sending leg's OWN session id on this server's requests: with a key declared, every `tools/call` and `resources/read` the
188
+ * engine sends this server carries `params._meta[key]` = that leg's `sessionId` (the id its events carry), over stdio and Streamable
189
+ * HTTP alike, so a connector can keep state per (principal, session). Absent ⇒ nothing is sent (a session id leaving the process is a
190
+ * correlation the deployment chooses). A delegated child is another session: its own calls carry its own id, and the engine does not
191
+ * guess a root — the principal ({@link TaskSpec.principal}) is shared by every session of one user, so it is not a tree key either.
192
+ *
193
+ * The key is judged once by {@link import("./mcp-call-meta.js").judgeSessionMetaKey} where the declaration is judged (the preparation door
194
+ * and `materializeMcpTools`): a non-string, an empty or over-long one, one outside the MCP `_meta` key-name format, one in a prefix MCP
195
+ * reserves (a prefix whose second label is `modelcontextprotocol` or `mcp`), `progressToken` (the SDK's own) or a key in the engine's
196
+ * `sema/` namespace refuses the entry with
197
+ * `config.invalid_argument` naming the key — never dropped, never defaulted. A dial with no leg (the library entrance, the no-run probe)
198
+ * has no session, so nothing rides.
199
+ */
200
+ sessionMetaKey?: string;
175
201
  }
176
202
  type ToolAxes = NonNullable<McpServerSpec["toolAxes"]>;
177
203
  /**
@@ -219,17 +245,17 @@ export type DeclarationRead = {
219
245
  * path does not say which kind of container each name came from, so a segment of digits alone is read as a list index.
220
246
  */
221
247
  export declare function declarationFaultOf(fault: ReceiptFault): DeclarationFault;
222
- /** What a declaration's own type fixes at one path, beyond being plain data: a string there, or a record of names to strings. */
248
+ /** What a declaration's own type fixes at one path, beyond being plain data: a string there. */
223
249
  export interface DeclarationPathRule {
224
250
  readonly path: readonly string[];
225
- readonly holds: "a string" | "names to strings";
251
+ readonly holds: "a string";
226
252
  /** The member must be there (a declaration with no value at the path is refused, as one with a value of another kind is). */
227
253
  readonly required?: true;
228
254
  }
229
255
  /**
230
- * Per surface, every path its declaration's type fixes beyond plain data — the declarer's `name` (a string, always there) and every record
231
- * the type writes as `Record<string, string>`: an MCP server's `transport.env` (a stdio server's environment) and `transport.headers` (an
232
- * HTTP server's headers); an A2A peer's `headers`. A path that is not its surface's (an A2A peer's `transport`) is not judged by another
256
+ * Per surface, every path its declaration's type fixes beyond plain data — the declarer's `name` (a string, always there). A declaration
257
+ * carries no record of values (its credential reference is judged by its own reader, the retired value members are refused by name —
258
+ * both after this receipt, src/core/peer-seat.ts). A path that is not its surface's (an A2A peer's `transport`) is not judged by another
233
259
  * surface's row: it is a member the surface does not read.
234
260
  */
235
261
  export declare const DECLARATION_PATH_RULES: Readonly<Record<ToolAxesSurface, readonly DeclarationPathRule[]>>;
@@ -349,16 +375,18 @@ export interface A2aServerSpec {
349
375
  /** Explicit agent-card location, when the peer does not publish at a well-known path. Set ⇒ it is used
350
376
  * ALONE (no well-known probing behind the operator's back). */
351
377
  cardUrl?: string;
352
- /** Static headers sent on every request to this peer (e.g. an auth bearer). They travel only to the
353
- * declared origins (`url`, `cardUrl`): a card naming an endpoint on another origin refuses the peer
354
- * (`config.protocol_endpoint_unbound`), and a redirect is not followed. */
355
- headers?: Record<string, string>;
378
+ /** At most one opaque credential reference, as on an MCP server's transport: the headers a send to this peer carries are
379
+ * answered per send by the deployment's peer seat ({@link RunnerDeps.peerSeat}), never declared (`headers` is retired and
380
+ * refused, `config.credential_in_declaration`). Pieces the seat answers travel only to the declared origins (`url`,
381
+ * `cardUrl`): a send carrying them to an endpoint on another origin is refused (`config.protocol_endpoint_unbound`), and it
382
+ * follows no redirect. */
383
+ credentials?: CredentialRef;
356
384
  /**
357
385
  * Per-task **end-user principal** header (design/62), same contract as the MCP side: when set, the
358
386
  * Runner injects the running task's authenticated {@link TaskSpec.principal} under this header name on
359
387
  * every call to this peer, so the peer can enforce per-user authorization. Absent principal ⇒ the
360
- * header is not sent (the peer must then default to deny/public, never admin). A static entry in
361
- * {@link headers} under the same name in any case refuses the peer (`config.protocol_header_collision`).
388
+ * header is not sent (the peer must then default to deny/public, never admin). A header the peer seat
389
+ * answers under the same name in any case is the seat's fault, and that send is not made (`config.protocol_header_collision`).
362
390
  * The principal is Runner-held: the model can neither read nor set it.
363
391
  */
364
392
  principalHeader?: string;
@@ -68,12 +68,9 @@ export function declarationFaultOf(fault) {
68
68
  export const DECLARATION_PATH_RULES = Object.freeze({
69
69
  mcp: Object.freeze([
70
70
  { path: ["name"], holds: "a string", required: true },
71
- { path: ["transport", "env"], holds: "names to strings" },
72
- { path: ["transport", "headers"], holds: "names to strings" },
73
71
  ].map((rule) => Object.freeze({ ...rule, path: Object.freeze([...rule.path]) }))),
74
72
  a2a: Object.freeze([
75
73
  { path: ["name"], holds: "a string", required: true },
76
- { path: ["headers"], holds: "names to strings" },
77
74
  ].map((rule) => Object.freeze({ ...rule, path: Object.freeze([...rule.path]) }))),
78
75
  });
79
76
  export const NO_DECLARATION_PATH_RULES = Object.freeze([]);
@@ -84,21 +81,7 @@ function declarationVocabularyFault(root, rules) {
84
81
  const stack = [];
85
82
  const ruleAt = () => rules.find((rule) => rule.path.length === path.length && rule.path.every((key, i) => key === path[i]));
86
83
  const onRuleRoute = () => rules.some((rule) => rule.path.length > path.length && path.every((key, i) => key === rule.path[i]));
87
- const ruleProblem = (rule, value) => {
88
- if (rule.holds === "a string")
89
- return typeof value === "string" ? undefined : `it is ${dataKind(value)}, not a string`;
90
- if (!isPlainRecord(value))
91
- return `it is ${dataKind(value)}, not a record of names to strings`;
92
- for (const [key, member] of Object.entries(value)) {
93
- path.push(key);
94
- if (key === "__proto__")
95
- return PROTO_MEMBER;
96
- if (member !== undefined && typeof member !== "string")
97
- return `it is ${dataKind(member)}, not a string: this record maps names to strings`;
98
- path.pop();
99
- }
100
- return undefined;
101
- };
84
+ const ruleProblem = (_rule, value) => (typeof value === "string" ? undefined : `it is ${dataKind(value)}, not a string`);
102
85
  const meet = (value) => {
103
86
  if (typeof value !== "object" || value === null || (asked.has(value) && !onRuleRoute()))
104
87
  return undefined;
@@ -1,6 +1,7 @@
1
+ import { type PeerSeat } from "./peer-seat.js";
1
2
  import { type McpInstructionsEntry, type PromptSectionDisposer } from "./prompt-section-seat.js";
2
3
  import { McpConnectionPool } from "./mcp-connection-pool.js";
3
- import { type McpDelivered, type McpFailureKind, type McpServerLiveness } from "./mcp-failure.js";
4
+ import { type McpAuthorization, type McpDelivered, type McpFailureKind, type McpServerLiveness } from "./mcp-failure.js";
4
5
  import type { AgentTool } from "../internal/harness-types.js";
5
6
  import type { ImageContent, TextContent } from "../internal/llm.js";
6
7
  import { type McpImageResizer } from "./image-downsample.js";
@@ -8,6 +9,7 @@ import type { McpServerSpec, OnElicit, ToolEffect } from "./types.js";
8
9
  import type { McpRevocationLedger } from "./mcp-server-spec.js";
9
10
  import { type HostFloor } from "./host-floor.js";
10
11
  import { type ReminderDisclosureCounts } from "./reminder-disclosure.js";
12
+ import { type McpLegMetaReader } from "./mcp-call-meta.js";
11
13
  export { resolveMcpDeclaredResultSize } from "./mcp-tool-meta.js";
12
14
  /**
13
15
  * The safety axes (design/77 §4 irreversibility, design/70 egress) derived from one materialized MCP
@@ -310,8 +312,8 @@ export interface McpReconnectResult {
310
312
  * what the run handle's verb forwards to `onError(phase:"mcp")`. One production, two drains. */
311
313
  warnings?: string[];
312
314
  /** The NEW connect-time status record (also swapped into {@link MaterializedMcp.statuses}), present
313
- * whenever the dial was attempted: a consumer keys its next action off `errorCode` / `httpStatus`
314
- * (a 401 is a re-authorization door, a `spawn_failed` a missing binary), not off {@link reason}. */
315
+ * whenever the dial was attempted: a consumer keys its next action off `errorCode` / `authorization`
316
+ * (an `unauthorized` is the user's authorization door, a `spawn_failed` a missing binary), not off {@link reason}. */
315
317
  status?: McpServerStatus;
316
318
  /** The re-dial's own `tools/list` walk did not finish — {@link McpRefreshResult.listingIncomplete}
317
319
  * minus the retention arm: a re-dial has no previous listing on this connection to retain from. */
@@ -332,13 +334,16 @@ export interface McpServerStatus {
332
334
  };
333
335
  toolNames?: string[];
334
336
  error?: string;
335
- /** Present iff `status === "failed"` — the connect-time failure record, spread flat: {@link McpFailure.kind}
336
- * as `errorCode`, {@link McpFailure.delivered} as `delivered`, and `httpStatus` when the kind is
337
- * `http_status`. A consumer keys an action off THESE (a `http_status` 401 is a re-authorization door,
337
+ /** Present iff `status === "failed"` — the connect-time failure record, spread flat ({@link import("./mcp-failure.js").failureFields}):
338
+ * {@link McpFailure.kind} as `errorCode`, {@link McpFailure.delivered} as `delivered`, `httpStatus` when the kind is `http_status`,
339
+ * `authorization` when it is `unauthorized`. A consumer keys an action off THESE (an `unauthorized` is the user's authorization door,
338
340
  * a `spawn_failed` is a missing binary) instead of parsing the neutralized `error` text. */
339
341
  errorCode?: McpFailureKind;
340
342
  delivered?: McpDelivered;
341
343
  httpStatus?: number;
344
+ /** {@link McpFailure.authorization}: why the principal must authorize this server and where — present iff `errorCode === "unauthorized"`.
345
+ * `authorizeUrl` is the deployment seat's (TRUSTED); `resourceMetadataUrl` is the endpoint's own claim (UNTRUSTED, like `error`). */
346
+ authorization?: McpAuthorization;
342
347
  /**
343
348
  * Set to `true` once core OBSERVES this server's transport close during the task; absent
344
349
  * otherwise (never `false`: absence means "no close was observed", which is not the same as "alive").
@@ -481,19 +486,6 @@ export * from "./image-downsample.js";
481
486
  * type, ≤10 object entries then `, ...`.
482
487
  */
483
488
  export declare function inferCompactSchema(value: unknown, depth?: number): string;
484
- /** `kind` is the dial's ONE read of `spec.transport.kind` (taken by the caller beside the dial and threaded
485
- * here, to the idle bucket and to the failure classifier alike): a nested `transport` object is the
486
- * caller's, and a getter that answered differently to two readers would otherwise connect over one
487
- * transport and be judged under another. An unknown kind takes the non-stdio branch, as it always did. */
488
- /**
489
- * The MCP HTTP transport's `fetch`: every request the transport makes — the POST, the SSE GET (initial and
490
- * resumed), the DELETE, the auth flows — goes to the endpoint the declaration NAMED and follows no redirect.
491
- * `fetch`'s default follows a 3xx silently and then reports only the last hop, which is the one shape under
492
- * which the delivery verdict would lie (a connect refusal on the redirect target reading "never sent" while
493
- * the declared endpoint had received the POST); a 3xx now surfaces as the SDK's HTTP-status error, and a
494
- * body or a credential never travels to a host the declaration did not name. Exported for its pin only.
495
- */
496
- export declare const declaredEndpointFetch: typeof fetch;
497
489
  interface McpContentItem {
498
490
  type: string;
499
491
  text?: string;
@@ -617,7 +609,11 @@ reminderDisclosure?: {
617
609
  }, poolOpts?: {
618
610
  pool: McpConnectionPool;
619
611
  ownsPool?: boolean;
620
- }, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean, signal?: AbortSignal, hostFloor?: HostFloor): Promise<MaterializedMcp>;
612
+ }, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean, signal?: AbortSignal, hostFloor?: HostFloor, peerSeat?: PeerSeat, // `RunnerDeps.peerSeat` (peer-seat.ts): what each request carries; absent ⇒ nothing, and a declared `credentials` refuses that dial
613
+ onAuthorizationRequired?: (server: string, authorization: McpAuthorization) => void): Promise<MaterializedMcp>;
614
+ /** The runner's materialization of one leg (not index-exported): every minted tool's `tools/call` reads the leg's request-meta seat
615
+ * (`mcp-call-meta.ts`) — the request meta's only source, written only by the `tool.call` station with what its judge passed. */
616
+ export declare function materializeLegMcpTools(seat: McpLegMetaReader | undefined, ...[specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts, promptSections, dialable, signal, hostFloor, peerSeat, onAuthorizationRequired]: Parameters<typeof materializeMcpTools>): Promise<MaterializedMcp>;
621
617
  /**
622
618
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.
623
619
  * Unlike server hints, the caller may RAISE or LOWER any axis: `effect` sets the repeat-safety class (lower to