@sema-agent/core 7.56.0 → 7.58.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 (319) hide show
  1. package/CHANGELOG.md +926 -0
  2. package/LICENSE +1 -1
  3. package/dist/agents/org-delivery-gate.js +3 -4
  4. package/dist/agents/peer-held-queue.d.ts +69 -49
  5. package/dist/agents/peer-held-queue.js +255 -106
  6. package/dist/agents/peer-session-drain.js +63 -43
  7. package/dist/agents/send-message-tool.js +3 -2
  8. package/dist/agents/subagent-steps.js +2 -4
  9. package/dist/agents/subagent.js +8 -8
  10. package/dist/brain/anthropic.js +16 -8
  11. package/dist/brain/open-responses.js +10 -8
  12. package/dist/brain/openai.js +11 -9
  13. package/dist/brain/provider-dialect.d.ts +3 -2
  14. package/dist/brain/provider-dialect.js +2 -2
  15. package/dist/brain/request-params.d.ts +6 -0
  16. package/dist/brain/request-params.js +14 -1
  17. package/dist/brain/route-adjudicator.js +2 -1
  18. package/dist/brain/stream-engine.d.ts +9 -0
  19. package/dist/brain/stream-engine.js +24 -10
  20. package/dist/brain/stream-shared.d.ts +5 -4
  21. package/dist/brain/stream-shared.js +4 -4
  22. package/dist/core/a2a.d.ts +2 -1
  23. package/dist/core/a2a.js +23 -10
  24. package/dist/core/allow-entry.d.ts +5 -11
  25. package/dist/core/allow-entry.js +19 -26
  26. package/dist/core/approval-object.d.ts +21 -5
  27. package/dist/core/approval-object.js +44 -17
  28. package/dist/core/ask-origin.d.ts +23 -4
  29. package/dist/core/ask-origin.js +5 -1
  30. package/dist/core/auto-compaction.d.ts +75 -6
  31. package/dist/core/auto-compaction.js +43 -27
  32. package/dist/core/auto-mode-directive.d.ts +29 -5
  33. package/dist/core/auto-mode-directive.js +38 -8
  34. package/dist/core/background-agent-store.d.ts +6 -2
  35. package/dist/core/background-agent-store.js +1 -1
  36. package/dist/core/checkpoint-requirements.d.ts +13 -1
  37. package/dist/core/checkpoint-requirements.js +4 -0
  38. package/dist/core/checkpoint-store.d.ts +44 -40
  39. package/dist/core/checkpoint-store.js +32 -14
  40. package/dist/core/cross-boundary-taint.js +4 -2
  41. package/dist/core/engine-notice.d.ts +4 -3
  42. package/dist/core/engine-notice.js +6 -0
  43. package/dist/core/file-history-store.d.ts +14 -8
  44. package/dist/core/file-history-store.js +14 -4
  45. package/dist/core/fs-write-gate-policy.d.ts +4 -2
  46. package/dist/core/fs-write-gate-policy.js +7 -3
  47. package/dist/core/gate-fold.js +6 -3
  48. package/dist/core/gate-lanes.js +13 -5
  49. package/dist/core/git-worktree-env.d.ts +53 -11
  50. package/dist/core/git-worktree-env.js +96 -12
  51. package/dist/core/hooks.d.ts +6 -3
  52. package/dist/core/hooks.js +12 -5
  53. package/dist/core/human-input-projection.d.ts +1 -0
  54. package/dist/core/human-input-projection.js +3 -0
  55. package/dist/core/locked-config.d.ts +15 -1
  56. package/dist/core/locked-config.js +38 -2
  57. package/dist/core/mailbox-store.d.ts +62 -1
  58. package/dist/core/mailbox-store.js +59 -0
  59. package/dist/core/mcp-call-meta.d.ts +66 -0
  60. package/dist/core/mcp-call-meta.js +103 -0
  61. package/dist/core/mcp-connection-pool.d.ts +3 -1
  62. package/dist/core/mcp-connection-pool.js +3 -1
  63. package/dist/core/mcp-failure.d.ts +7 -1
  64. package/dist/core/mcp-failure.js +10 -0
  65. package/dist/core/mcp-name-judge.d.ts +46 -0
  66. package/dist/core/mcp-name-judge.js +61 -0
  67. package/dist/core/mcp-probe.d.ts +5 -1
  68. package/dist/core/mcp-probe.js +3 -6
  69. package/dist/core/mcp-server-link.d.ts +5 -2
  70. package/dist/core/mcp-server-spec.d.ts +46 -18
  71. package/dist/core/mcp-server-spec.js +1 -18
  72. package/dist/core/mcp.d.ts +6 -14
  73. package/dist/core/mcp.js +85 -65
  74. package/dist/core/memory-engine/consolidation-driver.js +4 -3
  75. package/dist/core/memory-engine/distiller.js +26 -17
  76. package/dist/core/memory-engine/layout.js +5 -2
  77. package/dist/core/memory-engine/scope-contract.d.ts +45 -4
  78. package/dist/core/memory-engine/scope-contract.js +80 -11
  79. package/dist/core/mode-policy.d.ts +8 -5
  80. package/dist/core/mode-policy.js +5 -4
  81. package/dist/core/mods/host.js +1 -1
  82. package/dist/core/mods/kernel/dispatch.d.ts +3 -0
  83. package/dist/core/mods/kernel/dispatch.js +10 -8
  84. package/dist/core/mods/kernel/events.d.ts +5 -1
  85. package/dist/core/mods/kernel/events.js +1 -1
  86. package/dist/core/mods/kernel/registration.d.ts +5 -1
  87. package/dist/core/mods/kernel/site-rules.d.ts +3 -0
  88. package/dist/core/mods/kernel/site-rules.js +10 -0
  89. package/dist/core/mods/package.d.ts +23 -0
  90. package/dist/core/mods/package.js +118 -0
  91. package/dist/core/mods/stations.d.ts +2 -2
  92. package/dist/core/mods/stations.js +1 -1
  93. package/dist/core/mods/tool-call.d.ts +5 -1
  94. package/dist/core/mods/tool-call.js +12 -3
  95. package/dist/core/park-selfcheck.js +2 -0
  96. package/dist/core/path-guard-rows.d.ts +20 -0
  97. package/dist/core/path-guard-rows.js +11 -0
  98. package/dist/core/peer-seat.d.ts +186 -0
  99. package/dist/core/peer-seat.js +307 -0
  100. package/dist/core/permission-rule-consent.d.ts +5 -3
  101. package/dist/core/permission-rule-consent.js +20 -15
  102. package/dist/core/permission-rule-model.d.ts +43 -2
  103. package/dist/core/permission-rule-model.js +52 -8
  104. package/dist/core/permission-rule-org.js +1 -1
  105. package/dist/core/present-plan-tool.d.ts +10 -1
  106. package/dist/core/present-plan-tool.js +46 -2
  107. package/dist/core/protocol-http-auth.d.ts +56 -31
  108. package/dist/core/protocol-http-auth.js +71 -42
  109. package/dist/core/protocol-naming.d.ts +20 -0
  110. package/dist/core/protocol-naming.js +20 -3
  111. package/dist/core/read-only-shell.d.ts +20 -5
  112. package/dist/core/read-only-shell.js +29 -14
  113. package/dist/core/redaction-marks.d.ts +16 -0
  114. package/dist/core/redaction-marks.js +16 -0
  115. package/dist/core/redaction-passes.js +8 -9
  116. package/dist/core/remote-env.d.ts +37 -1
  117. package/dist/core/remote-env.js +11 -0
  118. package/dist/core/resume-startup-cause.d.ts +24 -2
  119. package/dist/core/resume-startup-cause.js +20 -1
  120. package/dist/core/retention.d.ts +41 -15
  121. package/dist/core/retention.js +59 -12
  122. package/dist/core/rewrite-rejudge.d.ts +37 -0
  123. package/dist/core/rewrite-rejudge.js +40 -0
  124. package/dist/core/roles.js +50 -7
  125. package/dist/core/run-origin.d.ts +40 -0
  126. package/dist/core/run-origin.js +37 -0
  127. package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
  128. package/dist/core/runner/advertised-writable-dirs.js +126 -0
  129. package/dist/core/runner/compact-session.d.ts +10 -0
  130. package/dist/core/runner/compact-session.js +202 -0
  131. package/dist/core/runner/compaction-call-options.d.ts +2 -2
  132. package/dist/core/runner/compaction-restate.d.ts +15 -6
  133. package/dist/core/runner/compaction-restate.js +28 -2
  134. package/dist/core/runner/compaction-seams.d.ts +21 -1
  135. package/dist/core/runner/compaction-seams.js +11 -8
  136. package/dist/core/runner/contracts.d.ts +36 -21
  137. package/dist/core/runner/derived-route-fallback.d.ts +13 -0
  138. package/dist/core/runner/derived-route-fallback.js +6 -0
  139. package/dist/core/runner/env-capability-census.d.ts +3 -2
  140. package/dist/core/runner/env-capability-census.js +9 -3
  141. package/dist/core/runner/gate-exit.d.ts +18 -4
  142. package/dist/core/runner/gate-exit.js +5 -1
  143. package/dist/core/runner/permission-rule-lanes.d.ts +7 -7
  144. package/dist/core/runner/permission-rule-lanes.js +17 -11
  145. package/dist/core/runner/prepare-acquire-reconcile.d.ts +3 -0
  146. package/dist/core/runner/prepare-acquire-reconcile.js +2 -1
  147. package/dist/core/runner/prepare-caps-and-workflow.d.ts +2 -0
  148. package/dist/core/runner/prepare-caps-and-workflow.js +1 -1
  149. package/dist/core/runner/prepare-config-doors.d.ts +14 -5
  150. package/dist/core/runner/prepare-config-doors.js +16 -13
  151. package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
  152. package/dist/core/runner/prepare-delegation-surface.js +15 -18
  153. package/dist/core/runner/prepare-gate-stations.js +1 -1
  154. package/dist/core/runner/prepare-hands-readface.d.ts +10 -4
  155. package/dist/core/runner/prepare-hands-readface.js +6 -1
  156. package/dist/core/runner/prepare-memory.d.ts +3 -0
  157. package/dist/core/runner/prepare-memory.js +19 -23
  158. package/dist/core/runner/prepare-park-ask.d.ts +2 -0
  159. package/dist/core/runner/prepare-park-ask.js +2 -2
  160. package/dist/core/runner/prepare-policy-chain.d.ts +4 -4
  161. package/dist/core/runner/prepare-policy-chain.js +4 -6
  162. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
  163. package/dist/core/runner/prepare-protocol-tools.js +3 -3
  164. package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
  165. package/dist/core/runner/prepare-suspend-saga.js +2 -1
  166. package/dist/core/runner/prepare-task.d.ts +4 -1
  167. package/dist/core/runner/prepare-task.js +46 -37
  168. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +13 -0
  169. package/dist/core/runner/prepare-tool-disclosure-mount.js +13 -7
  170. package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -0
  171. package/dist/core/runner/prepare-wiring-manifest.js +2 -2
  172. package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
  173. package/dist/core/runner/prepare-workspace-restore.js +4 -4
  174. package/dist/core/runner/resume-admission.js +1 -1
  175. package/dist/core/runner/resume-checkpoint-screen.js +2 -0
  176. package/dist/core/runner/rewind-files.d.ts +2 -5
  177. package/dist/core/runner/rewind-files.js +9 -51
  178. package/dist/core/runner/run-harness-handlers.d.ts +3 -4
  179. package/dist/core/runner/run-harness-handlers.js +1 -8
  180. package/dist/core/runner/run-identity-wiring.js +1 -0
  181. package/dist/core/runner/run-leg.js +15 -22
  182. package/dist/core/runner/run-notification-lane.d.ts +2 -0
  183. package/dist/core/runner/run-notification-lane.js +5 -2
  184. package/dist/core/runner/run-recovery-lanes.js +3 -4
  185. package/dist/core/runner/run-settle-and-teardown.js +5 -11
  186. package/dist/core/runner/run-terminal-adoption.js +3 -4
  187. package/dist/core/runner/run-turn-boundary.js +3 -5
  188. package/dist/core/runner/runtask.d.ts +8 -1
  189. package/dist/core/runner/runtask.js +28 -34
  190. package/dist/core/runner/send-message-continuation.js +1 -1
  191. package/dist/core/runner/session-verb-doors.d.ts +28 -0
  192. package/dist/core/runner/session-verb-doors.js +48 -0
  193. package/dist/core/runner/session-write-ledger.d.ts +30 -0
  194. package/dist/core/runner/session-write-ledger.js +101 -0
  195. package/dist/core/runner/stream-settle-backstop.js +11 -14
  196. package/dist/core/runner/sub-agent-deny-lists.d.ts +25 -3
  197. package/dist/core/runner/sub-agent-deny-lists.js +21 -10
  198. package/dist/core/runner/teardown-bounded.d.ts +1 -0
  199. package/dist/core/runner/teardown-bounded.js +1 -0
  200. package/dist/core/runner/terminal-account.js +3 -3
  201. package/dist/core/runner/tool-end-body.js +1 -0
  202. package/dist/core/runner/tool-occurrence.d.ts +4 -1
  203. package/dist/core/runner/tool-occurrence.js +2 -1
  204. package/dist/core/runner/write-protection-station.d.ts +8 -2
  205. package/dist/core/runner/write-protection-station.js +2 -0
  206. package/dist/core/runner-deps.d.ts +4 -4
  207. package/dist/core/secret-env.d.ts +4 -0
  208. package/dist/core/secret-env.js +3 -0
  209. package/dist/core/sensitive-path-policy.js +6 -7
  210. package/dist/core/session-log-transfer.d.ts +24 -0
  211. package/dist/core/session-log-transfer.js +166 -0
  212. package/dist/core/session-policy-store.d.ts +7 -2
  213. package/dist/core/session-policy-store.js +1 -1
  214. package/dist/core/session-store.d.ts +84 -19
  215. package/dist/core/session-store.js +162 -24
  216. package/dist/core/session.d.ts +92 -1
  217. package/dist/core/shell-read-silence.js +1 -0
  218. package/dist/core/shell-wrapper-projection.d.ts +1 -1
  219. package/dist/core/steer-replay.d.ts +4 -2
  220. package/dist/core/steer-replay.js +2 -1
  221. package/dist/core/store-contracts/background-agent-store-contract.js +1 -0
  222. package/dist/core/store-contracts/checkpoint-store-contract.js +19 -1
  223. package/dist/core/store-contracts/file-history-store-contract.js +9 -0
  224. package/dist/core/store-contracts/mailbox-store-contract.js +49 -1
  225. package/dist/core/store-contracts/session-repo-contract.js +112 -5
  226. package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
  227. package/dist/core/store-contracts/session-store-contract.js +236 -2
  228. package/dist/core/task-event.d.ts +68 -8
  229. package/dist/core/task-registry-agent.d.ts +8 -4
  230. package/dist/core/task-registry-agent.js +14 -8
  231. package/dist/core/task-registry-shared.d.ts +36 -6
  232. package/dist/core/task-registry-shared.js +11 -0
  233. package/dist/core/task-registry.d.ts +1 -1
  234. package/dist/core/task-registry.js +1 -1
  235. package/dist/core/task-spec.d.ts +37 -0
  236. package/dist/core/task-stream.d.ts +2 -1
  237. package/dist/core/terminal-cause.d.ts +1 -1
  238. package/dist/core/tool-catalog-entries.d.ts +6 -0
  239. package/dist/core/tool-catalog-entries.js +2 -0
  240. package/dist/core/tool-name-aliases.d.ts +32 -2
  241. package/dist/core/tool-name-aliases.js +23 -0
  242. package/dist/core/tool-name-readings.d.ts +4 -0
  243. package/dist/core/tool-name-readings.js +1 -0
  244. package/dist/core/tool-policy.d.ts +10 -6
  245. package/dist/core/tool-policy.js +4 -7
  246. package/dist/core/tool-result-store.d.ts +17 -10
  247. package/dist/core/tool-result-store.js +3 -1
  248. package/dist/core/trace.d.ts +4 -1
  249. package/dist/core/trace.js +2 -1
  250. package/dist/core/types.d.ts +1 -1
  251. package/dist/core/untrusted-egress.d.ts +18 -0
  252. package/dist/core/untrusted-egress.js +82 -12
  253. package/dist/core/wiring-manifest.d.ts +12 -3
  254. package/dist/core/wiring-manifest.js +4 -3
  255. package/dist/core/workspace-snapshot.d.ts +44 -0
  256. package/dist/core/workspace-snapshot.js +34 -0
  257. package/dist/core/write-protect.d.ts +43 -3
  258. package/dist/core/write-protect.js +43 -16
  259. package/dist/engine/execution-env/node-execution-env.js +15 -11
  260. package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
  261. package/dist/engine/harness/agent-harness.d.ts +12 -5
  262. package/dist/engine/harness/agent-harness.js +13 -2
  263. package/dist/engine/harness/types.d.ts +48 -7
  264. package/dist/engine/harness/types.js +5 -1
  265. package/dist/engine/llm/types.d.ts +12 -3
  266. package/dist/engine/llm/types.js +1 -1
  267. package/dist/engine/loop/agent-loop.d.ts +1 -4
  268. package/dist/engine/loop/agent-loop.js +26 -4
  269. package/dist/engine/session/import-validate.js +3 -0
  270. package/dist/engine/session/memory-repo.d.ts +17 -9
  271. package/dist/engine/session/memory-repo.js +44 -34
  272. package/dist/engine/session/repo-utils.d.ts +22 -4
  273. package/dist/engine/session/repo-utils.js +49 -1
  274. package/dist/engine/session/storage-base.d.ts +10 -1
  275. package/dist/engine/session/storage-base.js +7 -1
  276. package/dist/index.d.ts +23 -11
  277. package/dist/index.js +15 -6
  278. package/dist/internal/harness-types.d.ts +1 -1
  279. package/dist/internal/harness.d.ts +4 -3
  280. package/dist/internal/harness.js +3 -2
  281. package/dist/stores/file/checkpoint-store.d.ts +0 -4
  282. package/dist/stores/file/checkpoint-store.js +0 -1
  283. package/dist/stores/file/file-history-store.js +12 -4
  284. package/dist/stores/file/index.d.ts +4 -1
  285. package/dist/stores/file/index.js +4 -1
  286. package/dist/stores/file/mailbox-store.d.ts +2 -1
  287. package/dist/stores/file/mailbox-store.js +26 -1
  288. package/dist/stores/file/session-store.d.ts +15 -8
  289. package/dist/stores/file/session-store.js +28 -13
  290. package/dist/tools/fs/bash-readonly-classifier.d.ts +15 -19
  291. package/dist/tools/fs/bash-readonly-classifier.js +5 -10
  292. package/dist/tools/fs/fs-bash.js +10 -3
  293. package/dist/tools/fs/fs-write.d.ts +6 -3
  294. package/dist/tools/fs/fs-write.js +8 -7
  295. package/dist/tools/fs/index.d.ts +3 -0
  296. package/dist/tools/fs/index.js +1 -1
  297. package/dist/tools/fs/pattern-kill-guard.d.ts +3 -2
  298. package/dist/tools/fs/pattern-kill-guard.js +68 -36
  299. package/dist/tools/fs/safety.js +40 -8
  300. package/dist/tools/fs/search.js +6 -24
  301. package/dist/tools/fs/shell-read-check.d.ts +18 -1
  302. package/dist/tools/fs/shell-read-check.js +66 -16
  303. package/dist/tools/fs/shell-read-establish.js +2 -1
  304. package/dist/tools/fs/shell-read-identity.d.ts +12 -9
  305. package/dist/tools/fs/shell-read-identity.js +10 -5
  306. package/dist/tools/fs/shell-read-judge.d.ts +10 -1
  307. package/dist/tools/web.js +9 -7
  308. package/dist/tools/worktree.d.ts +42 -15
  309. package/dist/tools/worktree.js +60 -32
  310. package/package.json +4 -2
  311. package/test/export-surface.snapshot.json +141 -3
  312. package/wire-changes/core-stores-sql@7.57.0.json +29 -0
  313. package/wire-changes/core-stores-sql@7.58.0.json +29 -0
  314. package/wire-changes/core@7.57.0.json +1487 -0
  315. package/wire-changes/core@7.58.0.json +2188 -0
  316. package/wire-changes/mods-kernel@7.57.0.json +29 -0
  317. package/wire-changes/mods-kernel@7.58.0.json +81 -0
  318. package/wire-changes/primitives@7.57.0.json +245 -0
  319. package/wire-changes/primitives@7.58.0.json +29 -0
@@ -18,7 +18,56 @@ export interface MailboxMessage {
18
18
  * ABSENT = a pre-385 or foreign record (same semantics as an absent `hopChain`): the drain treats it
19
19
  * as foreign, never retro-admits it. Validated at `append` ({@link readMailboxPeerMeta}). */
20
20
  peerMeta?: MailboxPeerMeta;
21
+ /** The record's HOLD DECISION ({@link MailboxDecision}): absent = never held. Never appended — it
22
+ * starts absent and moves only through {@link MailboxStore.moveDecision}; every lease snapshot
23
+ * carries it, so every consumer of the box reads the same decision. */
24
+ decision?: MailboxDecision;
21
25
  }
26
+ /**
27
+ * A parked record's hold decision — the durable answer about a record a recipient's setting put on
28
+ * hold, kept ON the record so every consumer of the box (another terminal, another process, the session's
29
+ * next run) reads the same answer. `held` — waiting for a person; `approved` — a person approved it, not yet
30
+ * handed over; `delivered` — a consumer holding the lease took the move and handed it over (a later
31
+ * answer about it learns that instead of claiming a decision); `denied` / `expired` / `refused` /
32
+ * `dropped` — final: the record is never delivered and only waits for the ack that removes it.
33
+ */
34
+ export declare const MAILBOX_DECISIONS: readonly ["held", "approved", "delivered", "denied", "expired", "refused", "dropped"];
35
+ export type MailboxDecision = (typeof MAILBOX_DECISIONS)[number];
36
+ /** A stored decision word as a reader takes it: a word this engine does not know (a newer engine's) reads
37
+ * as `held` — never delivered on a guess, and left for a person (or that newer engine) to decide. */
38
+ export declare function readStoredMailboxDecision(raw: unknown): MailboxDecision | undefined;
39
+ /** The refusal code of a malformed {@link MailboxStore.moveDecision} call (a word outside the
40
+ * closed set, a non-positive seq, or an edge the decision law does not allow). */
41
+ export declare const MAILBOX_INVALID_DECISION_MOVE_CODE = "mailbox.invalid_decision_move";
42
+ export declare function isMailboxDecision(value: unknown): value is MailboxDecision;
43
+ /** Final states: the record is never delivered again, by any consumer. */
44
+ export declare function isMailboxDecisionFinal(state: MailboxDecision | undefined): boolean;
45
+ /** Deliverable states: a consumer holding the lease delivers the record (a setting that now refuses still wins). */
46
+ export declare function isMailboxDecisionDeliverable(state: MailboxDecision | undefined): boolean;
47
+ /**
48
+ * THE decision law — a decision only moves forward, and every hand-over of a held record is itself a move:
49
+ * absent → `held`; `held` → `approved` / `delivered` / `denied` / `expired` / `refused`; `approved` →
50
+ * `delivered` or a final state; `delivered` → `dropped` (the handed-over frame was refused by policy inside a lease-holding pass) only;
51
+ * a final state never moves.
52
+ */
53
+ export declare function mailboxDecisionEdgeAllowed(from: MailboxDecision | undefined, to: MailboxDecision): boolean;
54
+ /** What {@link MailboxStore.moveDecision} answers: the move happened, or the record's actual state
55
+ * (`unset` = never held, `gone` = no such record any more — acked, reaped or dropped). */
56
+ export type MailboxDecisionOutcome = {
57
+ readonly ok: true;
58
+ } | {
59
+ readonly ok: false;
60
+ readonly current: MailboxDecision | "unset" | "gone";
61
+ };
62
+ /**
63
+ * THE caller-side reading of {@link MailboxStore.moveDecision}: a fault can arrive AFTER the move
64
+ * committed (a lock release that failed, a reply lost on the wire), so a call that throws is asked once
65
+ * more, and a store that already holds `next` answers the first call's success. A second fault throws.
66
+ * Every engine-side decision move goes through this one function.
67
+ */
68
+ export declare function moveMailboxDecision(store: Pick<MailboxStore, "moveDecision">, scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
69
+ /** The one validator every backend runs BEFORE touching storage: a malformed call has zero side effects. */
70
+ export declare function assertMailboxDecisionMove(seq: unknown, expect: unknown, next: unknown): void;
22
71
  /** design/385 — the typed peer-metadata record on a parked message. ONE optional object, one-time
23
72
  * contract extension; every field optional. Bundled backends persist it verbatim and hand back a
24
73
  * detached copy. */
@@ -132,7 +181,7 @@ export declare const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tomb
132
181
  * A backend may raise the same code with a plain `Error` carrying `.code`; consumers branch on the
133
182
  * string, not on this class (a cross-process/out-of-repo store cannot hand back an instance).
134
183
  */
135
- export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE;
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;
136
185
  export declare class MailboxStoreError extends Error {
137
186
  readonly code: MailboxStoreErrorCode;
138
187
  constructor(code: MailboxStoreErrorCode, message: string);
@@ -241,6 +290,17 @@ export interface MailboxStore {
241
290
  * Implementations report `{acked:true}` only when they actually consumed the prefix.
242
291
  */
243
292
  ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
293
+ /**
294
+ * Move one record's hold decision from `expect` (absent = never held) to `next`, atomically
295
+ * against every other transition and against `ack` — the compare-and-set every decision about a held
296
+ * record goes through. NOT fenced by the lease: a person answers from whichever process shows the
297
+ * record, whether or not it holds the box. A state that is not `expect` answers `{ ok: false, current }`
298
+ * and changes nothing; a record no longer in the box answers `current: "gone"`. A malformed call (see
299
+ * {@link assertMailboxDecisionMove}) is refused with {@link MAILBOX_INVALID_DECISION_MOVE_CODE}
300
+ * before any side effect. The state is durable like the record, and `ack` / `reap` / `drop` remove it
301
+ * with the record.
302
+ */
303
+ moveDecision(scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
244
304
  releaseLease(scope: string, handle: string, owner: string): Promise<void>;
245
305
  /** Observation face (the "N pending" receipt figure) — count of currently-visible messages. */
246
306
  peekCount(scope: string, handle: string): Promise<number>;
@@ -291,6 +351,7 @@ export declare class InMemoryMailboxStore implements MailboxStore {
291
351
  append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
292
352
  claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
293
353
  ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
354
+ moveDecision(scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
294
355
  releaseLease(scope: string, handle: string, owner: string): Promise<void>;
295
356
  peekCount(scope: string, handle: string): Promise<number>;
296
357
  drop(scope: string, handle: string): Promise<void>;
@@ -1,4 +1,53 @@
1
1
  import { assertRetentionPolicy } from "./retention-policy.js";
2
+ export const MAILBOX_DECISIONS = Object.freeze(["held", "approved", "delivered", "denied", "expired", "refused", "dropped"]);
3
+ export function readStoredMailboxDecision(raw) {
4
+ if (raw === undefined)
5
+ return undefined;
6
+ return isMailboxDecision(raw) ? raw : "held";
7
+ }
8
+ export const MAILBOX_INVALID_DECISION_MOVE_CODE = "mailbox.invalid_decision_move";
9
+ export function isMailboxDecision(value) {
10
+ return typeof value === "string" && MAILBOX_DECISIONS.includes(value);
11
+ }
12
+ export function isMailboxDecisionFinal(state) {
13
+ return state === "denied" || state === "expired" || state === "refused" || state === "dropped";
14
+ }
15
+ export function isMailboxDecisionDeliverable(state) {
16
+ return state === "approved" || state === "delivered";
17
+ }
18
+ export function mailboxDecisionEdgeAllowed(from, to) {
19
+ if (from === undefined)
20
+ return to === "held";
21
+ if (from === "held")
22
+ return to === "approved" || to === "delivered" || to === "denied" || to === "expired" || to === "refused";
23
+ if (from === "approved")
24
+ return to === "delivered" || isMailboxDecisionFinal(to);
25
+ if (from === "delivered")
26
+ return to === "dropped";
27
+ return false;
28
+ }
29
+ export async function moveMailboxDecision(store, scope, handle, seq, expect, next) {
30
+ try {
31
+ return await store.moveDecision(scope, handle, seq, expect, next);
32
+ }
33
+ catch {
34
+ const again = await store.moveDecision(scope, handle, seq, expect, next);
35
+ return !again.ok && again.current === next ? { ok: true } : again;
36
+ }
37
+ }
38
+ export function assertMailboxDecisionMove(seq, expect, next) {
39
+ const refuse = (why) => {
40
+ throw new MailboxStoreError(MAILBOX_INVALID_DECISION_MOVE_CODE, `MailboxStore.moveDecision: ${why}`);
41
+ };
42
+ if (typeof seq !== "number" || !Number.isInteger(seq) || seq < 1)
43
+ refuse(`seq must be a positive integer (got ${String(seq)})`);
44
+ if (expect !== undefined && !isMailboxDecision(expect))
45
+ refuse(`expect must be absent or one of ${MAILBOX_DECISIONS.join("|")}`);
46
+ if (!isMailboxDecision(next))
47
+ refuse(`next must be one of ${MAILBOX_DECISIONS.join("|")}`);
48
+ if (!mailboxDecisionEdgeAllowed(expect, next))
49
+ refuse(`${String(expect ?? "unset")} → ${String(next)} is not a decision move (a decision only moves forward)`);
50
+ }
2
51
  export const MAILBOX_PEER_FROM_MODES = Object.freeze(["bypass", "prompting"]);
3
52
  export const MAILBOX_PEER_RECORD_KINDS = Object.freeze(["peer_message", "idle_notice", "delivery_notice", "idle_subscription", "engine_frame"]);
4
53
  export const MAILBOX_PEER_NOTICE_STATES = Object.freeze(["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable"]);
@@ -184,6 +233,16 @@ export class InMemoryMailboxStore {
184
233
  b.lease = undefined;
185
234
  return { acked: true };
186
235
  }
236
+ async moveDecision(scope, handle, seq, expect, next) {
237
+ assertMailboxDecisionMove(seq, expect, next);
238
+ const m = this.boxes.get(this.key(scope, handle))?.messages.find((x) => x.seq === seq);
239
+ if (m === undefined)
240
+ return { ok: false, current: "gone" };
241
+ if (m.decision !== expect)
242
+ return { ok: false, current: m.decision ?? "unset" };
243
+ m.decision = next;
244
+ return { ok: true };
245
+ }
187
246
  async releaseLease(scope, handle, owner) {
188
247
  const b = this.boxes.get(this.key(scope, handle));
189
248
  if (b?.lease?.owner === owner)
@@ -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) {
@@ -19,9 +19,13 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
19
19
  * capability, an ordinary `-32603`): the exchange happened;
20
20
  * · `invalid_config` — the declaration itself could not be dialed (a malformed `url`): a fault to
21
21
  * fix in the spec, never an outage to wait out;
22
+ * · `credential_unavailable` — the deployment's peer seat did not furnish the request (it threw, did not
23
+ * answer in time, answered something the engine cannot carry, or answered that
24
+ * the principal is not authorized): that request was not sent — a fault for the
25
+ * deployment to fix, not an outage of the server;
22
26
  * · `unknown` — the thrown value carried no structure this table reads.
23
27
  */
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"];
28
+ export declare const MCP_FAILURE_KINDS: readonly ["connect_refused", "connection_failed", "connection_closed", "http_status", "not_mcp_response", "spawn_failed", "timeout", "protocol", "invalid_config", "credential_unavailable", "unknown"];
25
29
  export type McpFailureKind = (typeof MCP_FAILURE_KINDS)[number];
26
30
  /** The closed set of delivery verdicts ({@link McpFailure.delivered}). */
27
31
  export declare const MCP_DELIVERY_VERDICTS: readonly ["yes", "no", "unknown"];
@@ -43,6 +47,7 @@ export declare const DELIVERED_BY_KIND: {
43
47
  readonly timeout: "unknown";
44
48
  readonly protocol: "yes";
45
49
  readonly invalid_config: "no";
50
+ readonly credential_unavailable: "no";
46
51
  readonly unknown: "unknown";
47
52
  };
48
53
  /** The fence over the delivery table: `never` while every kind has a verdict. */
@@ -104,6 +109,7 @@ export declare const LIVENESS_BY_FAILURE_KIND: {
104
109
  readonly timeout: "unreachable";
105
110
  readonly protocol: "reachable";
106
111
  readonly invalid_config: undefined;
112
+ readonly credential_unavailable: undefined;
107
113
  readonly unknown: "unknown";
108
114
  };
109
115
  /** The fence over the liveness table: `never` while every kind has a verdict. */
@@ -1,6 +1,7 @@
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 { PeerSeatFailure } from "./peer-seat.js";
4
5
  export const MCP_FAILURE_KINDS = Object.freeze([
5
6
  "connect_refused",
6
7
  "connection_failed",
@@ -11,6 +12,7 @@ export const MCP_FAILURE_KINDS = Object.freeze([
11
12
  "timeout",
12
13
  "protocol",
13
14
  "invalid_config",
15
+ "credential_unavailable",
14
16
  "unknown",
15
17
  ]);
16
18
  export const MCP_DELIVERY_VERDICTS = Object.freeze(["yes", "no", "unknown"]);
@@ -24,6 +26,7 @@ export const DELIVERED_BY_KIND = {
24
26
  timeout: "unknown",
25
27
  protocol: "yes",
26
28
  invalid_config: "no",
29
+ credential_unavailable: "no",
27
30
  unknown: "unknown",
28
31
  };
29
32
  export const MCP_LIVENESS_STATES = Object.freeze(["reachable", "unreachable", "unknown"]);
@@ -37,6 +40,7 @@ export const LIVENESS_BY_FAILURE_KIND = {
37
40
  timeout: "unreachable",
38
41
  protocol: "reachable",
39
42
  invalid_config: undefined,
43
+ credential_unavailable: undefined,
40
44
  unknown: "unknown",
41
45
  };
42
46
  export function livenessOf(outcome, observedAt) {
@@ -74,6 +78,11 @@ export function networkErrorCode(err, depth = 0) {
74
78
  const isNodeErrCode = (code) => code.startsWith("ERR_");
75
79
  const isDeclarationFault = (code) => code === "ERR_INVALID_URL" || (typeof code === "string" && code.startsWith("config."));
76
80
  export const FAILURE_CLASSIFIER = [
81
+ {
82
+ name: "peer seat did not furnish the request",
83
+ when: (err) => err instanceof PeerSeatFailure,
84
+ reads: () => ({ kind: "credential_unavailable" }),
85
+ },
77
86
  {
78
87
  name: "sdk connection closed",
79
88
  when: (err) => err instanceof McpError && err.code === ErrorCode.ConnectionClosed,
@@ -180,6 +189,7 @@ export function describeHttpTransportFailure(err, at = { phase: "request" }) {
180
189
  case "timeout":
181
190
  case "protocol":
182
191
  case "invalid_config":
192
+ case "credential_unavailable":
183
193
  case "unknown":
184
194
  return undefined;
185
195
  }
@@ -0,0 +1,46 @@
1
+ /**
2
+ * One declared server, as far as its names go: `McpServerSpec` fits as it is. `tools` are the server's REMOTE tool names the asker
3
+ * already knows (a listing, a host's reading of one — never the minted `mcp__…` names); absent means none are known.
4
+ */
5
+ export interface McpNameSetServer {
6
+ readonly name: string;
7
+ readonly tools?: readonly string[];
8
+ }
9
+ /**
10
+ * One contention: `names` are the two sources, the earlier one first (server names for `server_name`; the remote tool names for
11
+ * `tool_name`, where `server` says whose); `shared` is the name they mint — the prefix for `server_name`, the wire name for `tool_name`.
12
+ */
13
+ export type McpNameConflict = {
14
+ readonly kind: "server_name";
15
+ readonly names: readonly [string, string];
16
+ readonly shared: string;
17
+ } | {
18
+ readonly kind: "tool_name";
19
+ readonly server: string;
20
+ readonly names: readonly [string, string];
21
+ readonly shared: string;
22
+ };
23
+ /** The judge's answer: `ok`, or EVERY contention in the set — server rows first, then tool rows, each in declaration order; never empty. */
24
+ export type McpNameVerdict = {
25
+ readonly ok: true;
26
+ } | {
27
+ readonly ok: false;
28
+ readonly conflicts: readonly [McpNameConflict, ...McpNameConflict[]];
29
+ };
30
+ /** Judge a declared set. Pure: reads nothing but the names it is handed; a malformed set is refused (`config.invalid_argument`), never read as clean. */
31
+ export declare function judgeMcpNames(servers: readonly McpNameSetServer[]): McpNameVerdict;
32
+ /**
33
+ * The sentence that says why a tool of one server is not mounted under its own name: `heldBy` is the raw name that took the wire
34
+ * name `minted` first, `tool` the raw name that came after. TWO FACTS, TWO SENTENCES (a fixed label must not head more than one
35
+ * cause): the same raw name listed again, where namespacing folded nothing, and two different raw names that fold onto one name.
36
+ * It carries no raw name — the caller's own field says which tool.
37
+ */
38
+ export declare function mcpToolDropReason(minted: string, heldBy: string, tool: string): string;
39
+ /** One row as a sentence — the one the engine refuses a run with (`server_name`) or discloses a drop with (`tool_name`). Names are quoted single-line and bounded. */
40
+ export declare function describeMcpNameConflict(conflict: McpNameConflict): string;
41
+ /**
42
+ * The refusal of a declared set whose server names do not each own a namespace domain — thrown by the mount and by the no-run probe,
43
+ * so one set is refused with one code and one sentence wherever it is asked. It takes the NAMES only (a run's refusal reads no
44
+ * tool list); the FIRST `server_name` row speaks, naming both raw spellings.
45
+ */
46
+ export declare function refuseCollidingMcpServerNames(serverNames: readonly string[]): void;
@@ -0,0 +1,61 @@
1
+ import { MCP_NAMESPACE } from "./protocol-table.js";
2
+ import { createToolNameClaims, findNamespacePrefixCollisions } from "./protocol-naming.js";
3
+ import { inlineUntrusted } from "./untrusted-text.js";
4
+ function refuseArgument(problem) {
5
+ throw Object.assign(new Error(problem), { code: "config.invalid_argument" });
6
+ }
7
+ function readNameSet(servers) {
8
+ if (!Array.isArray(servers))
9
+ refuseArgument("judgeMcpNames takes a list of declared servers; what was passed is not a list.");
10
+ return Array.from(servers, (server, index) => {
11
+ if (typeof server !== "object" || server === null)
12
+ refuseArgument(`judgeMcpNames: entry ${index} is not a server declaration (an object with a "name").`);
13
+ const { name, tools } = server;
14
+ if (typeof name !== "string")
15
+ refuseArgument(`judgeMcpNames: entry ${index} has no string "name".`);
16
+ if (tools === undefined)
17
+ return { name };
18
+ const listed = Array.isArray(tools) ? Array.from(tools) : [undefined];
19
+ if (listed.some((tool) => typeof tool !== "string")) {
20
+ refuseArgument(`judgeMcpNames: entry ${index} ("${inlineUntrusted(name, 120)}") names its tools as something other than a list of strings.`);
21
+ }
22
+ return { name, tools: listed };
23
+ });
24
+ }
25
+ export function judgeMcpNames(servers) {
26
+ const set = readNameSet(servers);
27
+ const conflicts = findNamespacePrefixCollisions(MCP_NAMESPACE, set.map((s) => s.name)).map((c) => ({ kind: "server_name", names: c.peers, shared: c.prefix }));
28
+ for (const server of set) {
29
+ const claim = createToolNameClaims(MCP_NAMESPACE, server.name);
30
+ for (const tool of server.tools ?? []) {
31
+ const { minted, heldBy } = claim(tool);
32
+ if (heldBy !== undefined)
33
+ conflicts.push({ kind: "tool_name", server: server.name, names: [heldBy, tool], shared: minted });
34
+ }
35
+ }
36
+ const [first, ...rest] = conflicts;
37
+ return first === undefined ? { ok: true } : { ok: false, conflicts: [first, ...rest] };
38
+ }
39
+ export function mcpToolDropReason(minted, heldBy, tool) {
40
+ return heldBy === tool
41
+ ? `this server listed this tool name more than once in one listing; the first entry is mounted as "${minted}" and the repeat is dropped (one name cannot denote two tools)`
42
+ : `name collides with an earlier tool of this server: both mount as "${minted}" after namespacing (only [a-zA-Z0-9_-] survives), and one name cannot denote two tools`;
43
+ }
44
+ export function describeMcpNameConflict(conflict) {
45
+ const [a, b] = conflict.names;
46
+ if (conflict.kind === "tool_name") {
47
+ return `MCP server "${inlineUntrusted(conflict.server, 120)}", tool "${inlineUntrusted(b, 120)}": ${mcpToolDropReason(conflict.shared, a, b)}`;
48
+ }
49
+ return a === b
50
+ ? `MCP server "${inlineUntrusted(a, 120)}" is declared twice — each server needs its own name (both mount under "${conflict.shared}", so their tools would shadow each other and a refresh of one would unmount the other's).`
51
+ : `MCP server names "${inlineUntrusted(a, 120)}" and "${inlineUntrusted(b, 120)}" both mount under "${conflict.shared}" — the namespaced tool name keeps only [a-zA-Z0-9_-], so they are the same domain to this engine (their tools would shadow each other and a refresh of one would unmount the other's). Rename one.`;
52
+ }
53
+ export function refuseCollidingMcpServerNames(serverNames) {
54
+ const verdict = judgeMcpNames(serverNames.map((name) => ({ name })));
55
+ if (verdict.ok)
56
+ return;
57
+ const row = verdict.conflicts.find((c) => c.kind === "server_name");
58
+ if (row === undefined)
59
+ return;
60
+ throw Object.assign(new Error(describeMcpNameConflict(row)), { code: "config.mcp_server_name_collision" });
61
+ }
@@ -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
@@ -93,7 +97,7 @@ export interface McpProbeOptions {
93
97
  * FAILURE IS PER SERVER, REFUSAL IS NOT. A server that cannot be dialed, that answers a status, or that
94
98
  * outlives `timeoutMs` takes its verdict in its own row and the walk continues. What DOES reject is the
95
99
  * declaration set the materialization itself refuses — two names that mount under one namespace prefix
96
- * are refused before any transport is touched, by that same function, so the probe answers a colliding
100
+ * are refused before any transport is touched, by the judge the mount asks, so the probe answers a colliding
97
101
  * configuration exactly as a task would rather than showing two healthy-looking rows for a pair the
98
102
  * engine would never mount.
99
103
  *
@@ -2,8 +2,7 @@ import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
2
2
  import { snapshotMcpEntries } from "./locked-config.js";
3
3
  import { classifyMcpFailure, livenessOf } from "./mcp-failure.js";
4
4
  import { MCP_ENV_MS_MAX, materializeMcpTools } from "./mcp.js";
5
- import { findNamespacePrefixCollision } from "./protocol-naming.js";
6
- import { MCP_NAMESPACE } from "./protocol-table.js";
5
+ import { refuseCollidingMcpServerNames } from "./mcp-name-judge.js";
7
6
  import { mcpManifestEntries } from "./runner/prepare-wiring-manifest.js";
8
7
  const DECLINE_EVERY_ELICITATION = async () => ({ action: "decline" });
9
8
  function wholeInRange(name, value, min, max) {
@@ -66,9 +65,7 @@ export async function probeMcpServers(specs, opts = {}) {
66
65
  const concurrency = wholeInRange("concurrency", opts.concurrency, 1, Number.MAX_SAFE_INTEGER) ?? 1;
67
66
  const onElicit = opts.onElicit ?? DECLINE_EVERY_ELICITATION;
68
67
  const signal = opts.signal;
69
- if (findNamespacePrefixCollision(MCP_NAMESPACE, declared.map((e) => e.name)) !== undefined) {
70
- await materializeMcpTools(declared, opts.principal, onElicit);
71
- }
68
+ refuseCollidingMcpServerNames(declared.map((e) => e.name));
72
69
  const statuses = [];
73
70
  const servers = new Array(declared.length);
74
71
  const teardowns = [];
@@ -77,7 +74,7 @@ export async function probeMcpServers(specs, opts = {}) {
77
74
  const entry = declared[i];
78
75
  const started = performance.now();
79
76
  const elapsed = () => Math.round(performance.now() - started);
80
- 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);
81
78
  const verdict = await raceDial(dial, timeoutMs, signal);
82
79
  if (verdict.kind === "settled") {
83
80
  const found = verdict.handle.statuses.find((s) => s.name === entry.name);
@@ -131,8 +131,11 @@ export interface McpLiveConnection {
131
131
  export interface McpServerLink {
132
132
  /** 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
133
  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>;
134
+ /** Replace `lost`: join the re-dial running for the server, or start one while `lost` is still the live connection. Settles when there
135
+ * is nothing left to wait for. `cause`: the server dropped the session (`session`, the default), or the peer seat's pieces the
136
+ * connection was started with expired (`expired`: the calls in flight on it settle before it is closed, and the run tree's pooled
137
+ * connection is replaced once for all its holders). */
138
+ recover(lost: McpLiveConnection, cause?: "session" | "expired"): Promise<unknown>;
136
139
  }
137
140
  /** 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
141
  export type McpListingRefusal = "changed" | "unreached";