@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
@@ -2,6 +2,8 @@
2
2
  * lease/expiry cycles (a re-leased message keeps its number — dedup/ordering key). */
3
3
  export interface MailboxMessage {
4
4
  seq: number;
5
+ /** The identity the PRODUCER gave this record ({@link MailboxAppendMessage.id}); absent = it stated none. */
6
+ id?: string;
5
7
  /** Sender display name, when the sender had one (SendMessage `senderName` — display only). */
6
8
  from?: string;
7
9
  content: string;
@@ -181,7 +183,7 @@ export declare const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tomb
181
183
  * A backend may raise the same code with a plain `Error` carrying `.code`; consumers branch on the
182
184
  * string, not on this class (a cross-process/out-of-repo store cannot hand back an instance).
183
185
  */
184
- export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE | typeof MAILBOX_INVALID_DECISION_MOVE_CODE;
186
+ export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE | typeof MAILBOX_INVALID_DECISION_MOVE_CODE | typeof MAILBOX_INVALID_RECORD_ID_CODE | typeof MAILBOX_DUPLICATE_RECORD_ID_CODE;
185
187
  export declare class MailboxStoreError extends Error {
186
188
  readonly code: MailboxStoreErrorCode;
187
189
  constructor(code: MailboxStoreErrorCode, message: string);
@@ -195,6 +197,14 @@ export interface MailboxLease {
195
197
  /** REF-D18: one appended mailbox message — the SINGLE shape the interface method and both the
196
198
  * In-Memory and File implementations reference. */
197
199
  export interface MailboxAppendMessage {
200
+ /**
201
+ * The record's identity, minted by its producer — a re-park of the same message carries the same
202
+ * one. While the box HOLDS a record under this id, an append under it is that record: identical on
203
+ * every {@link MAILBOX_REPLAY_FACETS} facet ⇒ the held `seq`, nothing written; any facet different ⇒
204
+ * refused with {@link MAILBOX_DUPLICATE_RECORD_ID_CODE}. Absent = the producer states no identity and
205
+ * every append is a new record (its `seq` is all it is known by). Validated by {@link readMailboxRecordId}.
206
+ */
207
+ id?: string;
198
208
  from?: string;
199
209
  content: string;
200
210
  sentAt: number;
@@ -203,6 +213,33 @@ export interface MailboxAppendMessage {
203
213
  /** design/385 — see {@link MailboxMessage.peerMeta}; validated by {@link readMailboxPeerMeta}. */
204
214
  peerMeta?: MailboxPeerMeta;
205
215
  }
216
+ /** An `id` that is not a non-empty string of at most {@link MAILBOX_RECORD_ID_MAX_CHARS} characters. */
217
+ export declare const MAILBOX_INVALID_RECORD_ID_CODE = "mailbox.invalid_record_id";
218
+ /** An append under an `id` the box holds, whose record differs from the held one. */
219
+ export declare const MAILBOX_DUPLICATE_RECORD_ID_CODE = "mailbox.duplicate_record_id";
220
+ export declare const MAILBOX_RECORD_ID_MAX_CHARS = 1024;
221
+ /**
222
+ * What a record SAYS — the facets a repeat under one id is compared on. `sentAt` is not one of them: it
223
+ * is when a write happened, and a re-park of the same message happens later. Closed, in refusal order.
224
+ */
225
+ export declare const MAILBOX_REPLAY_FACETS: readonly ["from", "content", "hopChain", "peerMeta"];
226
+ export type MailboxReplayFacet = (typeof MAILBOX_REPLAY_FACETS)[number];
227
+ /** Validate a record id at `append`, before any side effect. `undefined` = no identity stated. */
228
+ export declare function readMailboxRecordId(raw: unknown): string | undefined;
229
+ /**
230
+ * ONE read of a caller's append: every member read once, validated (`peerMeta`, then `id`) and detached.
231
+ * A backend judges and persists THIS snapshot — never the caller's object again — so an accessor, or a
232
+ * mutation while the append waits for its lock, cannot make the record judged differ from the record stored.
233
+ */
234
+ export declare function readMailboxAppend(msg: MailboxAppendMessage): MailboxAppendMessage;
235
+ /**
236
+ * THE append-by-identity judgment, the one every backend runs inside its write critical section
237
+ * (with `msg` already validated: `id` by {@link readMailboxRecordId}, `peerMeta` by {@link readMailboxPeerMeta}).
238
+ * Returns the held record's `seq` when `msg` replays it (the caller writes nothing), `undefined` when the
239
+ * box holds no record under `msg.id` (the caller appends), and throws {@link MAILBOX_DUPLICATE_RECORD_ID_CODE}
240
+ * naming the facets when a different record claims the id. A third-party backend calls this function too.
241
+ */
242
+ export declare function judgeMailboxAppendById(held: readonly MailboxMessage[], msg: MailboxAppendMessage): number | undefined;
206
243
  /**
207
244
  * The pluggable mailbox seam (design/151 §7.1). Contract notes for implementations (file/pg):
208
245
  * - `append` is durable-first (a returned seq means the message survives a crash); seq is monotonic
@@ -250,6 +287,13 @@ export interface MailboxAppendMessage {
250
287
  * and a malformed value is REFUSED with `"mailbox.invalid_peer_meta"` before any side effect
251
288
  * (`readMailboxPeerMeta` is the one validator; bundled backends call it first). T1 cases in
252
289
  * `mailboxStoreContract` cover the pass trip, the refusal and the aliasing.
290
+ * - RECORD IDENTITY (every backend): `append` takes an optional producer-minted `id`, persists
291
+ * it and hands it back on `claimLease`. While the box holds a record under that id, an append under
292
+ * it is answered by {@link judgeMailboxAppendById} — the held `seq` for an identical record (nothing
293
+ * written), `"mailbox.duplicate_record_id"` for a different one — atomically with the seq allocation;
294
+ * a malformed id is refused with `"mailbox.invalid_record_id"` before any side effect. This is what
295
+ * makes re-asking a store whose reply was lost safe: a rejected append is not proof that nothing was
296
+ * written. The box answers for what it HOLDS — once a record is acked its id is free again.
253
297
  * - CROSS-PROCESS SAFETY (design/385, optional capability declared on the store): the session-box
254
298
  * drain shares ONE box between several OS processes. A backend that is correct under that sharing —
255
299
  * seq minted once across processes, lease/ack never crossing, one process's housekeeping never
@@ -150,6 +150,54 @@ export class MailboxStoreError extends Error {
150
150
  this.name = "MailboxStoreError";
151
151
  }
152
152
  }
153
+ export const MAILBOX_INVALID_RECORD_ID_CODE = "mailbox.invalid_record_id";
154
+ export const MAILBOX_DUPLICATE_RECORD_ID_CODE = "mailbox.duplicate_record_id";
155
+ export const MAILBOX_RECORD_ID_MAX_CHARS = 1024;
156
+ export const MAILBOX_REPLAY_FACETS = Object.freeze(["from", "content", "hopChain", "peerMeta"]);
157
+ export function readMailboxRecordId(raw) {
158
+ if (raw === undefined)
159
+ return undefined;
160
+ if (typeof raw !== "string" || raw === "" || raw.length > MAILBOX_RECORD_ID_MAX_CHARS) {
161
+ throw new MailboxStoreError(MAILBOX_INVALID_RECORD_ID_CODE, `MailboxStore.append: id must be a non-empty string of at most ${MAILBOX_RECORD_ID_MAX_CHARS} characters`);
162
+ }
163
+ return raw;
164
+ }
165
+ export function readMailboxAppend(msg) {
166
+ const peerMeta = readMailboxPeerMeta(msg.peerMeta);
167
+ const id = readMailboxRecordId(msg.id);
168
+ const from = msg.from;
169
+ const content = msg.content;
170
+ const sentAt = msg.sentAt;
171
+ const hopChain = msg.hopChain;
172
+ return {
173
+ ...(id !== undefined ? { id } : {}),
174
+ ...(from !== undefined ? { from } : {}),
175
+ content,
176
+ sentAt,
177
+ ...(hopChain !== undefined ? { hopChain: [...hopChain] } : {}),
178
+ ...(peerMeta !== undefined ? { peerMeta } : {}),
179
+ };
180
+ }
181
+ function facetSpelling(v) {
182
+ if (v === undefined || v === null)
183
+ return "-";
184
+ if (typeof v !== "object")
185
+ return JSON.stringify(v);
186
+ if (Array.isArray(v))
187
+ return `[${Array.from(v, facetSpelling).join(",")}]`;
188
+ return `{${Object.keys(v).filter((k) => v[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${facetSpelling(v[k])}`).join(",")}}`;
189
+ }
190
+ export function judgeMailboxAppendById(held, msg) {
191
+ if (msg.id === undefined)
192
+ return undefined;
193
+ const prior = held.find((m) => m.id === msg.id);
194
+ if (prior === undefined)
195
+ return undefined;
196
+ const differs = MAILBOX_REPLAY_FACETS.filter((f) => facetSpelling(prior[f]) !== facetSpelling(msg[f]));
197
+ if (differs.length === 0)
198
+ return prior.seq;
199
+ throw new MailboxStoreError(MAILBOX_DUPLICATE_RECORD_ID_CODE, `MailboxStore.append: the box already holds a different record under this id (it differs in: ${differs.join(", ")}) — a new message takes a new id; an identical repeat would have been a replay`);
200
+ }
153
201
  export function mailboxCrossProcessMountVerdict(store) {
154
202
  const declared = store.crossProcessSafe;
155
203
  if (declared === true)
@@ -199,17 +247,13 @@ export class InMemoryMailboxStore {
199
247
  async append(scope, handle, msg) {
200
248
  if (scope === undefined || scope === "")
201
249
  throw new Error("MailboxStore.append: refusing a message without a scope");
202
- const peerMeta = readMailboxPeerMeta(msg.peerMeta);
250
+ const record = readMailboxAppend(msg);
203
251
  const b = this.box(scope, handle);
252
+ const held = judgeMailboxAppendById(b.messages, record);
253
+ if (held !== undefined)
254
+ return held;
204
255
  const seq = b.nextSeq++;
205
- b.messages.push({
206
- seq,
207
- ...(msg.from !== undefined ? { from: msg.from } : {}),
208
- content: msg.content,
209
- sentAt: msg.sentAt,
210
- ...(msg.hopChain !== undefined ? { hopChain: [...msg.hopChain] } : {}),
211
- ...(peerMeta !== undefined ? { peerMeta } : {}),
212
- });
256
+ b.messages.push({ seq, ...record });
213
257
  return seq;
214
258
  }
215
259
  async claimLease(scope, handle, owner, ttlMs, now = Date.now()) {
@@ -0,0 +1,66 @@
1
+ /** The `_meta` key carrying the executing call's id. */
2
+ export declare const MCP_TOOL_USE_ID_META_KEY = "sema/toolUseId";
3
+ /** The `_meta` key carrying the request meta the call's `tool.call` chain handed on. */
4
+ export declare const MCP_REQUEST_META_KEY = "sema/requestMeta";
5
+ /** The most UTF-8 bytes a request meta may hold, its keys and values together (the reference's bound on its values: 262144). */
6
+ export declare const MCP_REQUEST_META_MAX_BYTES = 262144;
7
+ /** A request meta as it rides: string members only. */
8
+ export type McpRequestMeta = Readonly<Record<string, string>>;
9
+ /** A judged request meta: the copy that rides (undefined when there is none, or it has no member), or why it cannot ride. */
10
+ export type RequestMetaReading = {
11
+ readonly meta: McpRequestMeta | undefined;
12
+ } | {
13
+ readonly problem: string;
14
+ };
15
+ /**
16
+ * The request meta `value` stands for. It can ride when it is a plain record (the ordinary prototype, or none) whose own members
17
+ * are all enumerable string-keyed data properties holding strings, at most {@link MCP_REQUEST_META_MAX_BYTES} UTF-8 bytes of keys
18
+ * and values together; what rides is a frozen copy of those members with no prototype (an own `__proto__` key stays a key).
19
+ */
20
+ export declare function judgeRequestMeta(value: unknown): RequestMetaReading;
21
+ /** The request meta a handler handed on in `payload`: its OWN `requestMeta` data member (one inherited from a prototype is not
22
+ * handed on, and an accessor is never run), judged by {@link judgeRequestMeta}. */
23
+ export declare function readHandedRequestMeta(payload: object): RequestMetaReading;
24
+ /** The most characters a declared session key may have. */
25
+ export declare const MCP_SESSION_META_KEY_MAX_CHARS = 128;
26
+ /** A judged session key: the key that rides (undefined when none is declared), or why it cannot. */
27
+ export type SessionMetaKeyReading = {
28
+ readonly key: string | undefined;
29
+ } | {
30
+ readonly problem: string;
31
+ };
32
+ /**
33
+ * The one judge of a declared `sessionMetaKey` ({@link import("./mcp-server-spec.js").McpServerSpec.sessionMetaKey}). It can ride when it is
34
+ * a non-empty string of at most {@link MCP_SESSION_META_KEY_MAX_CHARS} characters in the MCP `_meta` key-name format (an optional
35
+ * prefix of dot-separated labels and a slash, then a name — the format is what a conforming server accepts, and it keeps out names such
36
+ * as `__proto__` that the SDK's own request parse drops) that names no `_meta` member of anyone else's: not the SDK's `progressToken`,
37
+ * not a key under the engine's `sema/` namespace, not under a prefix MCP reserves (the prefix is the text before the first `/`; its
38
+ * labels are DNS labels, so the second one is compared with case folded). Every refusal names the key; the key is the declaration's own
39
+ * text, bounded in the sentence.
40
+ */
41
+ export declare function judgeSessionMetaKey(value: unknown): SessionMetaKeyReading;
42
+ /**
43
+ * The `_meta` of one request the engine sends a server — a `tools/call` (the executing call's id, when it has one, and the request meta,
44
+ * when there is one: the judge answers none for a record with no member, so whatever it hands here rides) or a `resources/read` (neither) —
45
+ * and, when the server declared a session key, the leg's own session id under it. THE one mint: the key was judged where the declaration
46
+ * was ({@link judgeSessionMetaKey}), so it never lands on another member; no session id (a dial with no leg) rides nothing.
47
+ */
48
+ export declare function mcpCallMeta(toolUseId: string | undefined, requestMeta: McpRequestMeta | undefined, sessionMetaKey?: string, sessionId?: string): Record<string, unknown> | undefined;
49
+ /**
50
+ * The carrier from a call's `tool.call` chain bottom to the MCP tool's `execute`, one per leg. A tool's `execute` takes the call id
51
+ * and no per-call context, so the request meta rides the body's own async chain: {@link McpRequestMetaSeat.of} answers it only to
52
+ * an `execute` that runs inside that body, for the same call id, on the same leg's seat, while the body has not settled. Two calls
53
+ * in flight (even under one id), a child leg's calls (its own seat), a direct `execute` outside any body and a timer the body left
54
+ * behind never read each other's.
55
+ */
56
+ export interface McpRequestMetaSeat {
57
+ /** Run `body` with `meta` standing for the call `toolCallId` names, on this body's async chain; it stops standing when it settles. */
58
+ hold<T>(toolCallId: string, meta: McpRequestMeta | undefined, body: () => Promise<T>): Promise<T>;
59
+ /** What stands for the call `toolCallId` names, read from inside its body. */
60
+ of(toolCallId: string): McpRequestMeta | undefined;
61
+ /** The leg's own session id: what a server that declared a session key is sent ({@link mcpCallMeta}). Absent for a seat made without one. */
62
+ readonly sessionId?: string;
63
+ }
64
+ /** What the MCP materialization reads of its leg's seat: the request meta standing for a call, and the leg's session id. */
65
+ export type McpLegMetaReader = Pick<McpRequestMetaSeat, "of" | "sessionId">;
66
+ export declare function createMcpRequestMetaSeat(sessionId?: string): McpRequestMetaSeat;
@@ -0,0 +1,103 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { types } from "node:util";
3
+ import { isPlainRecord } from "./mods/kernel/receive.js";
4
+ import { dataKind } from "./mcp-server-spec.js";
5
+ export const MCP_TOOL_USE_ID_META_KEY = "sema/toolUseId";
6
+ export const MCP_REQUEST_META_KEY = "sema/requestMeta";
7
+ export const MCP_REQUEST_META_MAX_BYTES = 262_144;
8
+ const kindOf = (v) => v === null ? "null" : Array.isArray(v) ? "a list" : typeof v === "object" ? (types.isProxy(v) ? "a Proxy" : "an object that is not a plain record") : `a ${typeof v}`;
9
+ const named = (key) => JSON.stringify(key.length > 60 ? `${key.slice(0, 60)}…` : key);
10
+ export function judgeRequestMeta(value) {
11
+ if (value === undefined)
12
+ return { meta: undefined };
13
+ if (typeof value === "object" && value !== null && types.isProxy(value))
14
+ return { problem: "requestMeta is a Proxy; it takes a plain record of strings" };
15
+ if (!isPlainRecord(value))
16
+ return { problem: `requestMeta is ${kindOf(value)}; it takes a plain record of strings` };
17
+ const descriptors = Object.getOwnPropertyDescriptors(value);
18
+ if (Object.getOwnPropertySymbols(descriptors).length > 0)
19
+ return { problem: "requestMeta has a symbol-keyed member; its members are string keys holding strings" };
20
+ const copy = Object.create(null);
21
+ let bytes = 0;
22
+ let members = 0;
23
+ for (const key of Object.getOwnPropertyNames(descriptors)) {
24
+ const d = descriptors[key];
25
+ if (!Object.hasOwn(d, "value") || d.enumerable !== true)
26
+ return { problem: `requestMeta's member ${named(key)} is not an enumerable data property (a getter is never run)` };
27
+ const v = d.value;
28
+ if (typeof v !== "string")
29
+ return { problem: `requestMeta's member ${named(key)} is ${kindOf(v)}, not a string` };
30
+ bytes += Buffer.byteLength(key, "utf8") + Buffer.byteLength(v, "utf8");
31
+ Object.defineProperty(copy, key, { value: v, enumerable: true, writable: false, configurable: false });
32
+ members += 1;
33
+ }
34
+ if (bytes > MCP_REQUEST_META_MAX_BYTES)
35
+ return { problem: `requestMeta is ${bytes} bytes of keys and values; the most is ${MCP_REQUEST_META_MAX_BYTES}` };
36
+ return { meta: members === 0 ? undefined : Object.freeze(copy) };
37
+ }
38
+ export function readHandedRequestMeta(payload) {
39
+ const d = Object.getOwnPropertyDescriptor(payload, "requestMeta");
40
+ if (d === undefined)
41
+ return { meta: undefined };
42
+ if (!Object.hasOwn(d, "value"))
43
+ return { problem: "requestMeta is an accessor (a getter is never run); it takes a plain record of strings" };
44
+ return judgeRequestMeta(d.value);
45
+ }
46
+ const SDK_PROGRESS_TOKEN_KEY = "progressToken";
47
+ const ENGINE_META_NAMESPACE = "sema/";
48
+ export const MCP_SESSION_META_KEY_MAX_CHARS = 128;
49
+ const MCP_RESERVED_LABELS = ["modelcontextprotocol", "mcp"];
50
+ const META_LABEL = /^[A-Za-z](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
51
+ const META_NAME = /^(?:[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?)?$/;
52
+ export function judgeSessionMetaKey(value) {
53
+ if (value === undefined)
54
+ return { key: undefined };
55
+ if (typeof value !== "string")
56
+ return { problem: `sessionMetaKey is ${dataKind(value)}; it takes a non-empty string` };
57
+ if (value === "")
58
+ return { problem: "sessionMetaKey is the empty string; it takes a non-empty string" };
59
+ if (value.length > MCP_SESSION_META_KEY_MAX_CHARS)
60
+ return { problem: `sessionMetaKey ${named(value)} is ${value.length} characters; the most is ${MCP_SESSION_META_KEY_MAX_CHARS}` };
61
+ const slash = value.indexOf("/");
62
+ const labels = slash === -1 ? [] : value.slice(0, slash).split(".");
63
+ if (!labels.every((label) => META_LABEL.test(label)))
64
+ return { problem: `sessionMetaKey ${named(value)} has a prefix that is not dot-separated labels (a label starts with a letter, ends with a letter or digit, and holds letters, digits and hyphens) followed by a slash` };
65
+ if (!META_NAME.test(value.slice(slash + 1)))
66
+ return { problem: `sessionMetaKey ${named(value)} has a name that does not begin and end with a letter or digit, or holds a character other than letters, digits, hyphen, underscore and dot` };
67
+ if (value === SDK_PROGRESS_TOKEN_KEY)
68
+ return { problem: `sessionMetaKey ${named(value)} is the key the MCP SDK writes for its own progress token` };
69
+ if (value.startsWith(ENGINE_META_NAMESPACE))
70
+ return { problem: `sessionMetaKey ${named(value)} is under the engine's own "${ENGINE_META_NAMESPACE}" namespace` };
71
+ const second = labels[1]?.toLowerCase();
72
+ if (second !== undefined && MCP_RESERVED_LABELS.includes(second))
73
+ return { problem: `sessionMetaKey ${named(value)} is under a prefix MCP reserves (second label "${second}")` };
74
+ return { key: value };
75
+ }
76
+ export function mcpCallMeta(toolUseId, requestMeta, sessionMetaKey, sessionId) {
77
+ const meta = {
78
+ ...(typeof toolUseId === "string" && toolUseId !== "" ? { [MCP_TOOL_USE_ID_META_KEY]: toolUseId } : {}),
79
+ ...(requestMeta !== undefined ? { [MCP_REQUEST_META_KEY]: requestMeta } : {}),
80
+ ...(sessionMetaKey !== undefined && typeof sessionId === "string" && sessionId !== "" ? { [sessionMetaKey]: sessionId } : {}),
81
+ };
82
+ return Object.keys(meta).length === 0 ? undefined : meta;
83
+ }
84
+ const store = new AsyncLocalStorage();
85
+ export function createMcpRequestMetaSeat(sessionId) {
86
+ const seat = {};
87
+ return {
88
+ sessionId,
89
+ async hold(toolCallId, meta, body) {
90
+ const held = { seat, toolCallId, meta, live: true };
91
+ try {
92
+ return await store.run(held, body);
93
+ }
94
+ finally {
95
+ held.live = false;
96
+ }
97
+ },
98
+ of(toolCallId) {
99
+ const held = store.getStore();
100
+ return held !== undefined && held.live && held.seat === seat && held.toolCallId === toolCallId ? held.meta : undefined;
101
+ },
102
+ };
103
+ }
@@ -14,7 +14,9 @@
14
14
  * a revived one), so the DECLARATION stays the one source of truth — no handle is ever recorded anywhere.
15
15
  *
16
16
  * THE KEY is the server's declaration as the dial reads it (name and transport) and the principal the task runs under: a
17
- * different principal is a different identity at the server. A server that opted in to elicitation never enters the pool — the
17
+ * different principal is a different identity at the server. The transport holds no value (a declaration carries at most an
18
+ * opaque credential reference, so two references that differ never share a connection); the pieces a request carries are the
19
+ * peer seat's, asked under this same identity, so every holder of a connection sends what the one seat answers for it. A server that opted in to elicitation never enters the pool — the
18
20
  * answer to its questions belongs to the leg that is waiting on it.
19
21
  */
20
22
  import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -1,5 +1,6 @@
1
1
  import { canonicalize } from "./canonical-json.js";
2
2
  import { ConnectionListing } from "./mcp-server-link.js";
3
+ import { carrierOf } from "./peer-seat.js";
3
4
  export class McpConnectionPool {
4
5
  entries = new Map();
5
6
  dialing = new Map();
@@ -19,7 +20,8 @@ export class McpConnectionPool {
19
20
  if (this.shut)
20
21
  return undefined;
21
22
  opts?.signal?.throwIfAborted();
22
- if (opts?.fresh === true)
23
+ const held = this.entries.get(key);
24
+ if (opts?.fresh === true || (held !== undefined && carrierOf(held.client)?.expired() === true))
23
25
  this.detach(key);
24
26
  let entry = this.entries.get(key);
25
27
  if (entry === undefined || entry.closed) {
@@ -1,4 +1,5 @@
1
1
  import type { AssertAllKeysHandled } from "./ask-origin.js";
2
+ import type { AnnouncedMcpFailure } from "../internal/harness.js";
2
3
  /**
3
4
  * The closed set of failure classes ({@link McpFailure.kind}):
4
5
  * · `connect_refused` — a connect-phase errno (ECONNREFUSED / ENOTFOUND / EAI_AGAIN / EHOSTUNREACH /
@@ -9,8 +10,14 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
9
10
  * · `connection_closed` — the SDK reported the transport closed (`McpError` `ConnectionClosed`): in
10
11
  * flight the fate is unknowable, and for a server already known dead the
11
12
  * request was never attempted — the two are told apart by `delivered`;
12
- * · `http_status` — the HTTP endpoint answered with a status instead of an MCP response
13
- * (`httpStatus` carries the number: 401/403 = re-authorize, 5xx = down);
13
+ * · `unauthorized` — the principal must authorize this server before it serves them: the endpoint
14
+ * answered 401 (after the peer seat was asked once more), or 403 whose
15
+ * challenge says `insufficient_scope`, or the deployment's peer seat answered
16
+ * that the principal is not authorized here. `authorization` carries which
17
+ * ({@link McpAuthorization}); the next step is the user's, not an outage's;
18
+ * · `http_status` — the HTTP endpoint answered with any other status instead of an MCP response
19
+ * (`httpStatus` carries the number: 5xx = down, a 403 without a scope
20
+ * challenge = refused by policy);
14
21
  * · `not_mcp_response` — the HTTP endpoint answered something that is not an MCP payload and no status;
15
22
  * · `spawn_failed` — a stdio server process could not be started (a missing/unexecutable command);
16
23
  * · `timeout` — the request timed out (the SDK's per-call timer, the total ceiling, or the
@@ -19,10 +26,41 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
19
26
  * capability, an ordinary `-32603`): the exchange happened;
20
27
  * · `invalid_config` — the declaration itself could not be dialed (a malformed `url`): a fault to
21
28
  * fix in the spec, never an outage to wait out;
29
+ * · `credential_unavailable` — the deployment's peer seat did not furnish the request (it threw, did not
30
+ * answer in time, or answered something the engine cannot carry): that request
31
+ * was not sent — a fault for the deployment to fix, not an outage of the server;
22
32
  * · `unknown` — the thrown value carried no structure this table reads.
23
33
  */
24
- export declare const MCP_FAILURE_KINDS: readonly ["connect_refused", "connection_failed", "connection_closed", "http_status", "not_mcp_response", "spawn_failed", "timeout", "protocol", "invalid_config", "unknown"];
34
+ export declare const MCP_FAILURE_KINDS: readonly ["connect_refused", "connection_failed", "connection_closed", "unauthorized", "http_status", "not_mcp_response", "spawn_failed", "timeout", "protocol", "invalid_config", "credential_unavailable", "unknown"];
25
35
  export type McpFailureKind = (typeof MCP_FAILURE_KINDS)[number];
36
+ /**
37
+ * Why a server is `unauthorized` ({@link McpAuthorization.reason}), closed:
38
+ * · `rejected` — the HTTP endpoint answered 401: the request's credential (or its absence) was refused, and asking the peer seat once
39
+ * more did not answer a credential that passed;
40
+ * · `scope` — the HTTP endpoint answered 403 with a Bearer challenge whose `error` is `insufficient_scope` (RFC 6750 §3.1): the
41
+ * credential is good and does not cover this request;
42
+ * · `none` — the deployment's peer seat answered `unauthorized`: it holds no credential for this principal and this server, so
43
+ * nothing was sent.
44
+ */
45
+ export declare const MCP_AUTHORIZATION_REASONS: readonly ["rejected", "scope", "none"];
46
+ export type McpAuthorizationReason = (typeof MCP_AUTHORIZATION_REASONS)[number];
47
+ /**
48
+ * The authorization fact an `unauthorized` failure carries — one record, read whole by every face (the status record, the wiring
49
+ * manifest row, the thrown request error's `details`, the `mcp.authorization_required` notice, the model's needs-authorization line).
50
+ * The two URLs are separate members because their trust differs:
51
+ * · `authorizeUrl` comes ONLY from the deployment's peer seat (its `unauthorized` answer, to the send or to the re-ask after a 401) —
52
+ * TRUSTED; the engine never makes one up;
53
+ * · `resourceMetadataUrl` comes ONLY from the endpoint's own `WWW-Authenticate` challenge (`resource_metadata`, RFC 9728) — the
54
+ * REMOTE's claim, UNTRUSTED, and never rendered to the model by the engine.
55
+ * Both are read by one URL law at the point they arrive (`authorizationUrlOf`, peer-seat.ts): an absolute http(s) URL within
56
+ * {@link import("./peer-seat.js").AUTHORIZATION_URL_MAX} code units, kept as the URL parser serializes it (percent-encoded: no
57
+ * whitespace, no markup); the seat's URL that breaks the law refuses its answer, the remote's is dropped.
58
+ */
59
+ export interface McpAuthorization {
60
+ reason: McpAuthorizationReason;
61
+ authorizeUrl?: string;
62
+ resourceMetadataUrl?: string;
63
+ }
26
64
  /** The closed set of delivery verdicts ({@link McpFailure.delivered}). */
27
65
  export declare const MCP_DELIVERY_VERDICTS: readonly ["yes", "no", "unknown"];
28
66
  export type McpDelivered = (typeof MCP_DELIVERY_VERDICTS)[number];
@@ -37,12 +75,14 @@ export declare const DELIVERED_BY_KIND: {
37
75
  readonly connect_refused: "no";
38
76
  readonly connection_failed: "unknown";
39
77
  readonly connection_closed: "unknown";
78
+ readonly unauthorized: "unknown";
40
79
  readonly http_status: "unknown";
41
80
  readonly not_mcp_response: "unknown";
42
81
  readonly spawn_failed: "no";
43
82
  readonly timeout: "unknown";
44
83
  readonly protocol: "yes";
45
84
  readonly invalid_config: "no";
85
+ readonly credential_unavailable: "no";
46
86
  readonly unknown: "unknown";
47
87
  };
48
88
  /** The fence over the delivery table: `never` while every kind has a verdict. */
@@ -98,27 +138,30 @@ export declare const LIVENESS_BY_FAILURE_KIND: {
98
138
  readonly connect_refused: "unreachable";
99
139
  readonly connection_failed: "unreachable";
100
140
  readonly connection_closed: "unreachable";
141
+ readonly unauthorized: "unknown";
101
142
  readonly http_status: "unknown";
102
143
  readonly not_mcp_response: "unknown";
103
144
  readonly spawn_failed: "unreachable";
104
145
  readonly timeout: "unreachable";
105
146
  readonly protocol: "reachable";
106
147
  readonly invalid_config: undefined;
148
+ readonly credential_unavailable: undefined;
107
149
  readonly unknown: "unknown";
108
150
  };
109
151
  /** The fence over the liveness table: `never` while every kind has a verdict. */
110
152
  export type LivenessTableCoversEveryMcpFailureKind = AssertAllKeysHandled<Exclude<McpFailureKind, keyof typeof LIVENESS_BY_FAILURE_KIND>>;
111
153
  /**
112
- * What ONE exchange with a server tells the liveness record: the CLASS of the failure it ended in, or
113
- * `"completed"` when it finished. Every round trip the engine makes — a dial, a tool call, a resource
114
- * read, a listing, a refresh — reports exactly this, so the engine needs no second vocabulary and no
115
- * per-site judgment about which failures "count".
154
+ * What ONE exchange with a server tells the liveness record: the CLASS of the failure it ended in,
155
+ * `"completed"` when it finished, or `"unsent"` when the engine's own seat refused to send it (nothing
156
+ * was attempted, whatever the class — see {@link readMcpFailure}). Every round trip the engine makes — a
157
+ * dial, a tool call, a resource read, a listing, a refresh — reports exactly this, so the engine needs no
158
+ * second vocabulary and no per-site judgment about which failures "count".
116
159
  */
117
- export type McpExchangeOutcome = McpFailureKind | "completed";
160
+ export type McpExchangeOutcome = McpFailureKind | "completed" | "unsent";
118
161
  /** The liveness observation an exchange supports, or `undefined` when the outcome is not an observation
119
- * at all (see {@link LIVENESS_BY_FAILURE_KIND}: a declaration that could never be dialed). THE single
120
- * mint of the record — no two sites can disagree about the word, about which words may carry
121
- * `errorCode`, or about what a completed exchange proves. */
162
+ * at all (see {@link LIVENESS_BY_FAILURE_KIND}: a declaration that could never be dialed; a request the
163
+ * engine never sent). THE single mint of the record — no two sites can disagree about the word, about
164
+ * which words may carry `errorCode`, or about what a completed exchange proves. */
122
165
  export declare function livenessOf(outcome: McpExchangeOutcome, observedAt: number): McpServerLiveness | undefined;
123
166
  /** A request over an established connection; `session` when the request carried the session id the server issued at the handshake. */
124
167
  export type McpRequestSite = {
@@ -133,7 +176,7 @@ export type McpFailureSite = {
133
176
  } | McpRequestSite;
134
177
  /**
135
178
  * The one MCP failure record. Both fields are always present; `httpStatus` rides only with
136
- * `kind === "http_status"`.
179
+ * `kind === "http_status"`, `authorization` only with `kind === "unauthorized"`.
137
180
  */
138
181
  export interface McpFailure {
139
182
  /**
@@ -165,7 +208,23 @@ export interface McpFailure {
165
208
  delivered: McpDelivered;
166
209
  /** The HTTP status the endpoint answered with; present iff `kind === "http_status"`. */
167
210
  httpStatus?: number;
211
+ /** @contract mcp.failure.authorization — why the principal must authorize, and where ({@link McpAuthorization}); present iff
212
+ * `kind === "unauthorized"`. */
213
+ authorization?: McpAuthorization;
214
+ }
215
+ /**
216
+ * The failure record as a row carries it, spread flat: {@link McpFailure.kind} as `errorCode` beside `delivered`, and the class's own
217
+ * members (`httpStatus`, `authorization`). Every row that carries the record — the per-server status, the wiring manifest's `mcp[]`
218
+ * row — is written by {@link failureFields}, so a member the record gains rides every row without a second spelling.
219
+ */
220
+ export interface McpFailureFields {
221
+ errorCode: McpFailureKind;
222
+ delivered: McpDelivered;
223
+ httpStatus?: number;
224
+ authorization?: McpAuthorization;
168
225
  }
226
+ /** {@link McpFailureFields} of a record, or of a row that already carries them (`errorCode` absent ⇒ none) — fresh objects, never aliased. */
227
+ export declare function failureFields(of: McpFailure | Partial<McpFailureFields>): Partial<McpFailureFields>;
169
228
  /**
170
229
  * The first errno-shaped / undici-shaped `code` on an error's cause chain (`E[A-Z_]+`, `UND_ERR_*`,
171
230
  * Node's `ERR_*`). `fetch` reports every network failure as a bare `TypeError: fetch failed` with the
@@ -174,12 +233,16 @@ export interface McpFailure {
174
233
  * DNS-temporary-failure errno is literally `EAI_AGAIN`.
175
234
  */
176
235
  export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;
177
- /** What a row reads OFF the thrown value: the failure's class, and the status the `http_status` class
178
- * carries. A row does NOT write the delivery verdict — that follows from the kind and the SITE, in
179
- * one place ({@link DELIVERED_BY_KIND} + {@link classifyMcpFailure}), so a row cannot spell it wrong. */
236
+ /** What a row reads OFF the thrown value: the failure's class, the status the `http_status` class carries, the authorization fact
237
+ * the `unauthorized` class carries, and `unsent` — the thrown value is the engine's OWN refusal to send (the peer seat did not
238
+ * furnish the request: {@link PeerSeatFailure}), a structural fact about our side of the exchange that makes the verdict `"no"`
239
+ * whatever the class. A row does NOT write the delivery verdict — that follows from the kind, `unsent` and the SITE, in one place
240
+ * ({@link DELIVERED_BY_KIND} + {@link classifyMcpFailure}), so a row cannot spell it wrong. */
180
241
  export type McpFailureClass = {
181
242
  kind: McpFailureKind;
182
243
  httpStatus?: number;
244
+ authorization?: McpAuthorization;
245
+ unsent?: true;
183
246
  };
184
247
  /** One row of the classifier: `when` reads structure only; `reads` names the class it saw. */
185
248
  export interface McpFailureRule {
@@ -203,6 +266,45 @@ export declare const FAILURE_CLASSIFIER: ReadonlyArray<McpFailureRule>;
203
266
  * Total: every input maps to a record.
204
267
  */
205
268
  export declare function classifyMcpFailure(err: unknown, at: McpFailureSite): McpFailure;
269
+ /**
270
+ * One failure, read once: the record ({@link classifyMcpFailure}) and what the exchange tells the liveness record
271
+ * ({@link McpExchangeOutcome} — `"unsent"` for the engine's own refusal to send, else the class). A refusal of our own is `"no"` at every
272
+ * site and is no observation about the server; at the dial every other class but those minted from an answer is `"no"`
273
+ * ({@link CONNECT_KEEPS_THE_TABLE_VERDICT}); elsewhere the table says.
274
+ */
275
+ export declare function readMcpFailure(err: unknown, at: McpFailureSite): {
276
+ failure: McpFailure;
277
+ exchange: McpExchangeOutcome;
278
+ };
279
+ /**
280
+ * A failed server as the `mcp_unavailable` frame tells it: the session's told-record identity pair (`name`, `error` — the ledger judges
281
+ * telling by the pair, announce-once-ledger.ts) and, for an `unauthorized` failure, the record's own `authorization` — what the frame's
282
+ * needs-authorization arm renders. The told record keeps the pair only (`settleMcpUnavailable`): the pair already differs when the
283
+ * failure does.
284
+ */
285
+ export interface McpUnavailableEntry extends AnnouncedMcpFailure {
286
+ authorization?: McpAuthorization;
287
+ }
288
+ /** Where the user authorizes, as every model-facing line names it: the seat's URL, or the deployment's connector settings. */
289
+ export declare function whereToAuthorize(authorizeUrl: string | undefined): string;
290
+ /**
291
+ * The `mcp_unavailable` frame's needs-authorization arm — the servers among `entries` whose failure record carries `authorization`, or
292
+ * `undefined` when there are none. CC 2.1.309's arm, minted as `needsAuthMcpServers` (cli309.js:265582), read back as `needsAuthMcpServers` (cli309.js:267398),
293
+ * worded (cli309.js:267399) "The following MCP servers require authentication before their tools can be used" — ahead of the
294
+ * failed-to-connect arm; this engine never runs an authorization flow itself, so it is always the reference's cannot-start-the-flow form.
295
+ * `<where>` is the deployment seat's `authorizeUrl` when it gave one (listed beside the server), else the connector settings; no error
296
+ * text rides it (the fact is the record's). At most `max` servers are named, the rest counted.
297
+ */
298
+ export declare function needsAuthorizationArm(entries: readonly McpUnavailableEntry[], max: number): string | undefined;
299
+ /**
300
+ * The model's line for a request refused as `unauthorized` — the call-time twin of the needs-authorization arm the `mcp_unavailable`
301
+ * frame carries for a server that could not mount (turn-attachments.ts): who must act (the user), where ({@link whereToAuthorize}: the
302
+ * seat's URL only), what not to ask for, and the delivery tail (`writeTail`, the caller's write-class sentence) the verdict owes. A 401
303
+ * after which the deployment answered another credential that no request has carried yet (`renewed`: the first attempt, not sent again)
304
+ * may pass on a new call: the line says so, and that only a refusal of that call too is the user's — a seat that answers a fresh
305
+ * credential every time still reaches the user. A re-send refused again is the plain line.
306
+ */
307
+ export declare function unauthorizedLine(what: string, serverLabel: string, a: McpAuthorization, renewed: boolean, writeTail: string): string;
206
308
  /**
207
309
  * What a transport-level HTTP failure can be said to be, in words for a model-facing line: the
208
310
  * condition to name, and the delivery verdict. `undefined` for every failure that is NOT of the HTTP