@sema-agent/core 7.58.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 (284) hide show
  1. package/CHANGELOG.md +776 -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.js +33 -34
  10. package/dist/brain/anthropic.js +161 -45
  11. package/dist/brain/errors.d.ts +9 -3
  12. package/dist/brain/errors.js +7 -1
  13. package/dist/brain/failover.js +2 -1
  14. package/dist/brain/open-responses.js +3 -3
  15. package/dist/brain/openai.js +103 -53
  16. package/dist/brain/provider-dialect.d.ts +11 -0
  17. package/dist/brain/provider-dialect.js +5 -2
  18. package/dist/brain/reasoning-request.js +5 -4
  19. package/dist/brain/reasoning.d.ts +19 -0
  20. package/dist/brain/reasoning.js +17 -2
  21. package/dist/brain/request-route.d.ts +4 -1
  22. package/dist/brain/request-route.js +4 -1
  23. package/dist/brain/route-adjudicator.d.ts +84 -18
  24. package/dist/brain/route-adjudicator.js +87 -21
  25. package/dist/brain/route-conformance.js +1 -1
  26. package/dist/brain/stream-engine.js +84 -49
  27. package/dist/brain/stream-shared.d.ts +30 -0
  28. package/dist/brain/stream-shared.js +34 -1
  29. package/dist/brain/timeout.d.ts +62 -5
  30. package/dist/brain/timeout.js +93 -6
  31. package/dist/core/account-row.d.ts +61 -0
  32. package/dist/core/account-row.js +51 -0
  33. package/dist/core/advisor-verdict.d.ts +2 -1
  34. package/dist/core/advisor-verdict.js +1 -1
  35. package/dist/core/allow-entry.d.ts +18 -6
  36. package/dist/core/allow-entry.js +16 -8
  37. package/dist/core/approval-object.d.ts +29 -15
  38. package/dist/core/approval-object.js +47 -19
  39. package/dist/core/auto-compaction.js +1 -1
  40. package/dist/core/background-agent-store.d.ts +16 -3
  41. package/dist/core/checkpoint-requirements.d.ts +13 -1
  42. package/dist/core/checkpoint-requirements.js +3 -1
  43. package/dist/core/checkpoint-store.d.ts +58 -12
  44. package/dist/core/checkpoint-store.js +18 -6
  45. package/dist/core/child-clamp-seats.d.ts +29 -0
  46. package/dist/core/child-clamp-seats.js +56 -1
  47. package/dist/core/compliance.d.ts +2 -2
  48. package/dist/core/compliance.js +1 -1
  49. package/dist/core/effective-path-target.d.ts +8 -2
  50. package/dist/core/effective-path-target.js +8 -3
  51. package/dist/core/engine-notice.d.ts +98 -8
  52. package/dist/core/engine-notice.js +19 -5
  53. package/dist/core/gate-fold.js +1 -1
  54. package/dist/core/gate-lanes.js +8 -4
  55. package/dist/core/gate-outcome.d.ts +32 -3
  56. package/dist/core/gate-outcome.js +19 -1
  57. package/dist/core/governance-codes.d.ts +9 -1
  58. package/dist/core/governance-codes.js +13 -0
  59. package/dist/core/hooks.d.ts +31 -3
  60. package/dist/core/hooks.js +5 -6
  61. package/dist/core/image-admission.d.ts +6 -5
  62. package/dist/core/image-admission.js +18 -14
  63. package/dist/core/locked-config.d.ts +5 -2
  64. package/dist/core/locked-config.js +2 -1
  65. package/dist/core/mailbox-store.d.ts +45 -1
  66. package/dist/core/mailbox-store.js +53 -9
  67. package/dist/core/mcp-failure.d.ts +114 -18
  68. package/dist/core/mcp-failure.js +63 -5
  69. package/dist/core/mcp-server-link.d.ts +22 -1
  70. package/dist/core/mcp-server-link.js +25 -1
  71. package/dist/core/mcp.d.ts +12 -8
  72. package/dist/core/mcp.js +42 -25
  73. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  74. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  75. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  76. package/dist/core/memory-engine/consolidation.js +1 -0
  77. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  78. package/dist/core/memory-engine/distiller.js +2 -2
  79. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  80. package/dist/core/memory-engine/dual-root.js +44 -1
  81. package/dist/core/memory-engine/engine.d.ts +67 -14
  82. package/dist/core/memory-engine/engine.js +384 -212
  83. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  84. package/dist/core/memory-engine/export-bundle.js +23 -4
  85. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  86. package/dist/core/memory-engine/file-backend.js +290 -117
  87. package/dist/core/memory-engine/index.d.ts +1 -1
  88. package/dist/core/memory-engine/layout.d.ts +59 -11
  89. package/dist/core/memory-engine/layout.js +190 -40
  90. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  91. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  92. package/dist/core/memory-engine/sync-client.d.ts +9 -1
  93. package/dist/core/memory-engine/sync-client.js +31 -8
  94. package/dist/core/memory-engine/sync.d.ts +5 -0
  95. package/dist/core/memory-engine/types.d.ts +6 -0
  96. package/dist/core/mods/classic-events.d.ts +5 -1
  97. package/dist/core/mods/kernel/dispatch.js +2 -1
  98. package/dist/core/mods/kernel/events.d.ts +2 -1
  99. package/dist/core/mods/kernel/events.js +2 -2
  100. package/dist/core/mods/kernel/registration.d.ts +4 -0
  101. package/dist/core/mods/kernel/registration.js +3 -0
  102. package/dist/core/mods/stations.d.ts +31 -10
  103. package/dist/core/mods/stations.js +44 -10
  104. package/dist/core/mods/tool-call.js +1 -1
  105. package/dist/core/parent-spec-seat.d.ts +8 -3
  106. package/dist/core/parent-spec-seat.js +2 -0
  107. package/dist/core/park-selfcheck.js +6 -0
  108. package/dist/core/peer-seat.d.ts +70 -8
  109. package/dist/core/peer-seat.js +143 -11
  110. package/dist/core/permission-rule-consent.js +10 -4
  111. package/dist/core/permission-rule-model.d.ts +16 -0
  112. package/dist/core/permission-rule-model.js +1 -1
  113. package/dist/core/present-plan-tool.d.ts +11 -3
  114. package/dist/core/present-plan-tool.js +2 -2
  115. package/dist/core/resume-startup-cause.js +1 -0
  116. package/dist/core/rewrite-rejudge.d.ts +1 -0
  117. package/dist/core/rewrite-rejudge.js +2 -2
  118. package/dist/core/roles.d.ts +34 -2
  119. package/dist/core/roles.js +43 -4
  120. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  121. package/dist/core/runner/announce-once-ledger.js +4 -2
  122. package/dist/core/runner/call-hook-stations.js +2 -2
  123. package/dist/core/runner/contracts.d.ts +20 -16
  124. package/dist/core/runner/credential-origin-seat.js +4 -3
  125. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  126. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  127. package/dist/core/runner/decide-continuation.d.ts +2 -2
  128. package/dist/core/runner/gate-exit.d.ts +12 -4
  129. package/dist/core/runner/gate-exit.js +10 -7
  130. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  131. package/dist/core/runner/image-removed-seat.js +19 -0
  132. package/dist/core/runner/inline-image.js +1 -1
  133. package/dist/core/runner/memory-consolidation-driver.js +3 -3
  134. package/dist/core/runner/park-commit.d.ts +1 -1
  135. package/dist/core/runner/park-commit.js +3 -0
  136. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  137. package/dist/core/runner/prepare-ask-lane.js +2 -1
  138. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  139. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -5
  140. package/dist/core/runner/prepare-caps-and-workflow.js +2 -0
  141. package/dist/core/runner/prepare-config-doors.js +2 -0
  142. package/dist/core/runner/prepare-context-lane.js +2 -0
  143. package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
  144. package/dist/core/runner/prepare-delegation-surface.js +1 -0
  145. package/dist/core/runner/prepare-hands-readface.d.ts +4 -0
  146. package/dist/core/runner/prepare-hands-readface.js +5 -0
  147. package/dist/core/runner/prepare-inherited-gate.d.ts +1 -3
  148. package/dist/core/runner/prepare-inherited-gate.js +14 -27
  149. package/dist/core/runner/prepare-memory.js +10 -17
  150. package/dist/core/runner/prepare-park-ask.d.ts +1 -1
  151. package/dist/core/runner/prepare-park-ask.js +2 -1
  152. package/dist/core/runner/prepare-policy-chain.d.ts +3 -3
  153. package/dist/core/runner/prepare-policy-chain.js +16 -13
  154. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  155. package/dist/core/runner/prepare-project-context.js +2 -2
  156. package/dist/core/runner/prepare-prompt-inputs.d.ts +1 -1
  157. package/dist/core/runner/prepare-prompt-inputs.js +8 -19
  158. package/dist/core/runner/prepare-protocol-tools.js +9 -1
  159. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  160. package/dist/core/runner/prepare-run-refs.js +4 -1
  161. package/dist/core/runner/prepare-task.js +4 -2
  162. package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -1
  163. package/dist/core/runner/prepare-wiring-manifest.js +2 -1
  164. package/dist/core/runner/reply-pricing.d.ts +30 -0
  165. package/dist/core/runner/reply-pricing.js +19 -0
  166. package/dist/core/runner/resume-admission.js +4 -2
  167. package/dist/core/runner/resume-apply.js +6 -1
  168. package/dist/core/runner/resume-policy-outcome.js +5 -5
  169. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  170. package/dist/core/runner/role-seat-defaulted.js +40 -0
  171. package/dist/core/runner/run-brain-sinks.js +2 -0
  172. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  173. package/dist/core/runner/run-identity-wiring.js +5 -4
  174. package/dist/core/runner/run-leg.d.ts +2 -0
  175. package/dist/core/runner/run-leg.js +37 -28
  176. package/dist/core/runner/run-stop-and-final-verify.js +2 -2
  177. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  178. package/dist/core/runner/run-terminal-adoption.js +9 -3
  179. package/dist/core/runner/run-turn-boundary.js +77 -70
  180. package/dist/core/runner/runtask.d.ts +1 -1
  181. package/dist/core/runner/runtask.js +2 -2
  182. package/dist/core/runner/side-call-account.d.ts +1 -1
  183. package/dist/core/runner/side-call-account.js +3 -18
  184. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  185. package/dist/core/runner/sub-agent-deny-lists.js +10 -0
  186. package/dist/core/runner/tool-end-body.js +2 -2
  187. package/dist/core/runner/tool-occurrence.d.ts +1 -1
  188. package/dist/core/runner/tool-occurrence.js +2 -2
  189. package/dist/core/runner/turn-attachments.d.ts +26 -22
  190. package/dist/core/runner/turn-attachments.js +24 -26
  191. package/dist/core/runner-deps.d.ts +1 -1
  192. package/dist/core/secret-env.d.ts +32 -2
  193. package/dist/core/secret-env.js +65 -3
  194. package/dist/core/sensitive-path-policy.js +3 -3
  195. package/dist/core/session-policy-store.d.ts +3 -1
  196. package/dist/core/session-policy-store.js +13 -9
  197. package/dist/core/session-store.d.ts +2 -5
  198. package/dist/core/side-query.d.ts +11 -1
  199. package/dist/core/side-query.js +9 -0
  200. package/dist/core/skill-grant-binding.d.ts +31 -2
  201. package/dist/core/skill-grant-binding.js +31 -1
  202. package/dist/core/skill-grant.d.ts +8 -5
  203. package/dist/core/skill-grant.js +6 -6
  204. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  205. package/dist/core/store-contracts/checkpoint-store-contract.js +3 -2
  206. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  207. package/dist/core/synthetic-read-verdict.js +2 -1
  208. package/dist/core/task-event.d.ts +32 -8
  209. package/dist/core/task-notification.js +16 -10
  210. package/dist/core/task-registry-agent.js +1 -0
  211. package/dist/core/task-registry-shared.d.ts +5 -0
  212. package/dist/core/task-spec.d.ts +12 -1
  213. package/dist/core/terminal-cause.d.ts +10 -0
  214. package/dist/core/tool-check-reading.d.ts +1 -0
  215. package/dist/core/tool-check-reading.js +3 -3
  216. package/dist/core/tool-policy.d.ts +16 -0
  217. package/dist/core/tool-roster.d.ts +112 -5
  218. package/dist/core/tool-roster.js +42 -1
  219. package/dist/core/tool-spec.d.ts +3 -1
  220. package/dist/core/types.d.ts +2 -2
  221. package/dist/core/types.js +1 -1
  222. package/dist/core/user-attachment.js +1 -1
  223. package/dist/core/wiring-manifest.d.ts +6 -3
  224. package/dist/engine/compaction/compaction.js +29 -3
  225. package/dist/engine/execution-env/node-execution-env.d.ts +4 -3
  226. package/dist/engine/execution-env/node-execution-env.js +9 -12
  227. package/dist/engine/harness/agent-harness.d.ts +25 -2
  228. package/dist/engine/harness/agent-harness.js +41 -12
  229. package/dist/engine/harness/messages.d.ts +3 -1
  230. package/dist/engine/harness/messages.js +3 -2
  231. package/dist/engine/harness/types.d.ts +8 -0
  232. package/dist/engine/llm/rejected-images.d.ts +46 -0
  233. package/dist/engine/llm/rejected-images.js +54 -0
  234. package/dist/engine/llm/tool-turns.d.ts +2 -1
  235. package/dist/engine/llm/types.d.ts +18 -7
  236. package/dist/engine/loop/agent-loop.d.ts +8 -0
  237. package/dist/engine/loop/agent-loop.js +52 -15
  238. package/dist/engine/loop/types.d.ts +3 -1
  239. package/dist/engine/session/path-to-root.d.ts +38 -0
  240. package/dist/engine/session/path-to-root.js +39 -0
  241. package/dist/engine/session/storage-base.js +4 -21
  242. package/dist/index.d.ts +16 -10
  243. package/dist/index.js +11 -7
  244. package/dist/internal/harness-types.d.ts +1 -1
  245. package/dist/internal/harness.d.ts +1 -0
  246. package/dist/internal/llm.d.ts +1 -0
  247. package/dist/orchestration/workflow-observe.d.ts +17 -1
  248. package/dist/orchestration/workflow-observe.js +20 -0
  249. package/dist/orchestration/workflow-types.d.ts +32 -7
  250. package/dist/orchestration/workflow.js +739 -489
  251. package/dist/shell/counting-pass.d.ts +50 -0
  252. package/dist/shell/counting-pass.js +502 -0
  253. package/dist/shell/lex.d.ts +4 -2
  254. package/dist/shell/lex.js +93 -34
  255. package/dist/shell/shell-words.d.ts +1 -1
  256. package/dist/shell/shell-words.js +7 -6
  257. package/dist/stores/file/mailbox-store.js +6 -10
  258. package/dist/tools/fs/fs-bash.d.ts +6 -0
  259. package/dist/tools/fs/fs-bash.js +6 -3
  260. package/dist/tools/fs/index.js +6 -2
  261. package/dist/tools/fs/program-read-model.d.ts +13 -0
  262. package/dist/tools/fs/program-read-model.js +15 -0
  263. package/dist/tools/fs/program-read-model.rows.js +1 -1
  264. package/dist/tools/fs/read-deny.d.ts +13 -10
  265. package/dist/tools/fs/read-deny.js +25 -5
  266. package/dist/tools/fs/read-floor.d.ts +19 -0
  267. package/dist/tools/fs/read-floor.js +23 -0
  268. package/dist/tools/fs/shell-read-check.d.ts +1 -1
  269. package/dist/tools/fs/shell-read-check.js +2 -1
  270. package/dist/tools/fs/shell-read-judge.d.ts +16 -8
  271. package/dist/tools/fs/shell-read-judge.js +10 -6
  272. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  273. package/dist/tools/fs/shell-read-plan.js +22 -15
  274. package/dist/tools/fs/shell-read-start.js +1 -0
  275. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  276. package/dist/tools/fs/shell-reentry-text.js +25 -3
  277. package/dist/tools/monitor.d.ts +4 -0
  278. package/dist/tools/monitor.js +2 -0
  279. package/package.json +3 -2
  280. package/test/export-surface.snapshot.json +87 -1
  281. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  282. package/wire-changes/core@7.59.0.json +2459 -0
  283. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  284. package/wire-changes/primitives@7.59.0.json +29 -0
@@ -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
@@ -20,13 +27,40 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
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;
22
29
  * · `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;
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;
26
32
  * · `unknown` — the thrown value carried no structure this table reads.
27
33
  */
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"];
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"];
29
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
+ }
30
64
  /** The closed set of delivery verdicts ({@link McpFailure.delivered}). */
31
65
  export declare const MCP_DELIVERY_VERDICTS: readonly ["yes", "no", "unknown"];
32
66
  export type McpDelivered = (typeof MCP_DELIVERY_VERDICTS)[number];
@@ -41,6 +75,7 @@ export declare const DELIVERED_BY_KIND: {
41
75
  readonly connect_refused: "no";
42
76
  readonly connection_failed: "unknown";
43
77
  readonly connection_closed: "unknown";
78
+ readonly unauthorized: "unknown";
44
79
  readonly http_status: "unknown";
45
80
  readonly not_mcp_response: "unknown";
46
81
  readonly spawn_failed: "no";
@@ -103,6 +138,7 @@ export declare const LIVENESS_BY_FAILURE_KIND: {
103
138
  readonly connect_refused: "unreachable";
104
139
  readonly connection_failed: "unreachable";
105
140
  readonly connection_closed: "unreachable";
141
+ readonly unauthorized: "unknown";
106
142
  readonly http_status: "unknown";
107
143
  readonly not_mcp_response: "unknown";
108
144
  readonly spawn_failed: "unreachable";
@@ -115,16 +151,17 @@ export declare const LIVENESS_BY_FAILURE_KIND: {
115
151
  /** The fence over the liveness table: `never` while every kind has a verdict. */
116
152
  export type LivenessTableCoversEveryMcpFailureKind = AssertAllKeysHandled<Exclude<McpFailureKind, keyof typeof LIVENESS_BY_FAILURE_KIND>>;
117
153
  /**
118
- * What ONE exchange with a server tells the liveness record: the CLASS of the failure it ended in, or
119
- * `"completed"` when it finished. Every round trip the engine makes — a dial, a tool call, a resource
120
- * read, a listing, a refresh — reports exactly this, so the engine needs no second vocabulary and no
121
- * 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".
122
159
  */
123
- export type McpExchangeOutcome = McpFailureKind | "completed";
160
+ export type McpExchangeOutcome = McpFailureKind | "completed" | "unsent";
124
161
  /** The liveness observation an exchange supports, or `undefined` when the outcome is not an observation
125
- * at all (see {@link LIVENESS_BY_FAILURE_KIND}: a declaration that could never be dialed). THE single
126
- * mint of the record — no two sites can disagree about the word, about which words may carry
127
- * `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. */
128
165
  export declare function livenessOf(outcome: McpExchangeOutcome, observedAt: number): McpServerLiveness | undefined;
129
166
  /** A request over an established connection; `session` when the request carried the session id the server issued at the handshake. */
130
167
  export type McpRequestSite = {
@@ -139,7 +176,7 @@ export type McpFailureSite = {
139
176
  } | McpRequestSite;
140
177
  /**
141
178
  * The one MCP failure record. Both fields are always present; `httpStatus` rides only with
142
- * `kind === "http_status"`.
179
+ * `kind === "http_status"`, `authorization` only with `kind === "unauthorized"`.
143
180
  */
144
181
  export interface McpFailure {
145
182
  /**
@@ -171,7 +208,23 @@ export interface McpFailure {
171
208
  delivered: McpDelivered;
172
209
  /** The HTTP status the endpoint answered with; present iff `kind === "http_status"`. */
173
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;
174
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>;
175
228
  /**
176
229
  * The first errno-shaped / undici-shaped `code` on an error's cause chain (`E[A-Z_]+`, `UND_ERR_*`,
177
230
  * Node's `ERR_*`). `fetch` reports every network failure as a bare `TypeError: fetch failed` with the
@@ -180,12 +233,16 @@ export interface McpFailure {
180
233
  * DNS-temporary-failure errno is literally `EAI_AGAIN`.
181
234
  */
182
235
  export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;
183
- /** What a row reads OFF the thrown value: the failure's class, and the status the `http_status` class
184
- * carries. A row does NOT write the delivery verdict — that follows from the kind and the SITE, in
185
- * 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. */
186
241
  export type McpFailureClass = {
187
242
  kind: McpFailureKind;
188
243
  httpStatus?: number;
244
+ authorization?: McpAuthorization;
245
+ unsent?: true;
189
246
  };
190
247
  /** One row of the classifier: `when` reads structure only; `reads` names the class it saw. */
191
248
  export interface McpFailureRule {
@@ -209,6 +266,45 @@ export declare const FAILURE_CLASSIFIER: ReadonlyArray<McpFailureRule>;
209
266
  * Total: every input maps to a record.
210
267
  */
211
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;
212
308
  /**
213
309
  * What a transport-level HTTP failure can be said to be, in words for a model-facing line: the
214
310
  * condition to name, and the delivery verdict. `undefined` for every failure that is NOT of the HTTP
@@ -1,11 +1,12 @@
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
+ import { PeerAuthorizationRefused, PeerSeatFailure } from "./peer-seat.js";
5
5
  export const MCP_FAILURE_KINDS = Object.freeze([
6
6
  "connect_refused",
7
7
  "connection_failed",
8
8
  "connection_closed",
9
+ "unauthorized",
9
10
  "http_status",
10
11
  "not_mcp_response",
11
12
  "spawn_failed",
@@ -15,11 +16,13 @@ export const MCP_FAILURE_KINDS = Object.freeze([
15
16
  "credential_unavailable",
16
17
  "unknown",
17
18
  ]);
19
+ export const MCP_AUTHORIZATION_REASONS = Object.freeze(["rejected", "scope", "none"]);
18
20
  export const MCP_DELIVERY_VERDICTS = Object.freeze(["yes", "no", "unknown"]);
19
21
  export const DELIVERED_BY_KIND = {
20
22
  connect_refused: "no",
21
23
  connection_failed: "unknown",
22
24
  connection_closed: "unknown",
25
+ unauthorized: "unknown",
23
26
  http_status: "unknown",
24
27
  not_mcp_response: "unknown",
25
28
  spawn_failed: "no",
@@ -34,6 +37,7 @@ export const LIVENESS_BY_FAILURE_KIND = {
34
37
  connect_refused: "unreachable",
35
38
  connection_failed: "unreachable",
36
39
  connection_closed: "unreachable",
40
+ unauthorized: "unknown",
37
41
  http_status: "unknown",
38
42
  not_mcp_response: "unknown",
39
43
  spawn_failed: "unreachable",
@@ -46,12 +50,25 @@ export const LIVENESS_BY_FAILURE_KIND = {
46
50
  export function livenessOf(outcome, observedAt) {
47
51
  if (outcome === "completed")
48
52
  return { state: "reachable", observedAt };
53
+ if (outcome === "unsent")
54
+ return undefined;
49
55
  const state = LIVENESS_BY_FAILURE_KIND[outcome];
50
56
  if (state === undefined)
51
57
  return undefined;
52
58
  return state === "unreachable" ? { state, observedAt, errorCode: outcome } : { state, observedAt };
53
59
  }
54
- const CONNECT_KEEPS_THE_TABLE_VERDICT = new Set(["protocol", "http_status"]);
60
+ const CONNECT_KEEPS_THE_TABLE_VERDICT = new Set(["protocol", "http_status", "unauthorized"]);
61
+ export function failureFields(of) {
62
+ const kind = "kind" in of ? of.kind : of.errorCode;
63
+ if (kind === undefined)
64
+ return {};
65
+ return {
66
+ errorCode: kind,
67
+ ...(of.delivered !== undefined ? { delivered: of.delivered } : {}),
68
+ ...(of.httpStatus !== undefined ? { httpStatus: of.httpStatus } : {}),
69
+ ...(of.authorization !== undefined ? { authorization: { ...of.authorization } } : {}),
70
+ };
71
+ }
55
72
  const NETWORK_CODES_NEVER_DELIVERED = new Set([
56
73
  "ECONNREFUSED",
57
74
  "ENOTFOUND",
@@ -78,10 +95,15 @@ export function networkErrorCode(err, depth = 0) {
78
95
  const isNodeErrCode = (code) => code.startsWith("ERR_");
79
96
  const isDeclarationFault = (code) => code === "ERR_INVALID_URL" || (typeof code === "string" && code.startsWith("config."));
80
97
  export const FAILURE_CLASSIFIER = [
98
+ {
99
+ name: "peer seat answered the principal is not authorized",
100
+ when: (err) => err instanceof PeerSeatFailure && err.reason === "unauthorized",
101
+ reads: (err) => ({ kind: "unauthorized", authorization: authorizationOf("none", err.authorizeUrl, undefined), unsent: true }),
102
+ },
81
103
  {
82
104
  name: "peer seat did not furnish the request",
83
105
  when: (err) => err instanceof PeerSeatFailure,
84
- reads: () => ({ kind: "credential_unavailable" }),
106
+ reads: () => ({ kind: "credential_unavailable", unsent: true }),
85
107
  },
86
108
  {
87
109
  name: "sdk connection closed",
@@ -98,6 +120,13 @@ export const FAILURE_CLASSIFIER = [
98
120
  when: (err) => err instanceof McpError,
99
121
  reads: () => ({ kind: "protocol" }),
100
122
  },
123
+ {
124
+ name: "http endpoint refused the authorization",
125
+ when: (err) => err instanceof StreamableHTTPError && (err.code === 401 || err instanceof PeerAuthorizationRefused),
126
+ reads: (err) => err instanceof PeerAuthorizationRefused
127
+ ? { kind: "unauthorized", authorization: authorizationOf(err.reason, err.authorizeUrl, err.resourceMetadataUrl) }
128
+ : { kind: "unauthorized", authorization: { reason: "rejected" } },
129
+ },
101
130
  {
102
131
  name: "http endpoint answered a status",
103
132
  when: (err) => err instanceof StreamableHTTPError && typeof err.code === "number" && err.code > 0,
@@ -151,9 +180,37 @@ export const FAILURE_CLASSIFIER = [
151
180
  },
152
181
  ];
153
182
  export function classifyMcpFailure(err, at) {
154
- const read = classOf(err, at);
183
+ return readMcpFailure(err, at).failure;
184
+ }
185
+ export function readMcpFailure(err, at) {
186
+ const { unsent, ...read } = classOf(err, at);
155
187
  const dialled = at.phase === "connect" && !CONNECT_KEEPS_THE_TABLE_VERDICT.has(read.kind);
156
- return { ...read, delivered: dialled ? "no" : DELIVERED_BY_KIND[read.kind] };
188
+ return { failure: { ...read, delivered: unsent === true || dialled ? "no" : DELIVERED_BY_KIND[read.kind] }, exchange: unsent === true ? "unsent" : read.kind };
189
+ }
190
+ function authorizationOf(reason, authorizeUrl, resourceMetadataUrl) {
191
+ return { reason, ...(authorizeUrl !== undefined ? { authorizeUrl } : {}), ...(resourceMetadataUrl !== undefined ? { resourceMetadataUrl } : {}) };
192
+ }
193
+ export function whereToAuthorize(authorizeUrl) {
194
+ return authorizeUrl !== undefined ? `at ${authorizeUrl}` : "through the deployment's connector settings";
195
+ }
196
+ export function needsAuthorizationArm(entries, max) {
197
+ const named = entries.filter((f) => f.authorization !== undefined);
198
+ if (named.length === 0)
199
+ return undefined;
200
+ const withUrl = named.filter((f) => f.authorization?.authorizeUrl !== undefined).length;
201
+ const where = withUrl === named.length ? "at the address listed beside it" : withUrl === 0 ? whereToAuthorize(undefined) : `at the address listed beside it, or, for a server listed without one, ${whereToAuthorize(undefined)}`;
202
+ const lines = named.slice(0, max).map((f) => `${f.name}${f.authorization?.authorizeUrl !== undefined ? ` — authorize ${whereToAuthorize(f.authorization.authorizeUrl)}` : ""}`);
203
+ return (`The following MCP servers require authentication before their tools can be used:\n${lines.join("\n")}${named.length > max ? `\n…and ${named.length - max} more` : ""}\n\n` +
204
+ `You cannot start the authorization flow yourself. If the user's request depends on one of these servers (even if they didn't name it explicitly), ` +
205
+ `or they ask about it, tell them that it needs to be authorized — ${where} — and that the capability is unavailable until they do. ` +
206
+ `Otherwise carry on with the request and do not mention these servers. Do not ask the user for authorization codes, tokens, or callback URLs.`);
207
+ }
208
+ export function unauthorizedLine(what, serverLabel, a, renewed, writeTail) {
209
+ const owed = `The user needs to authorize this server${a.reason === "scope" ? " for the access this request needs" : ""} ${whereToAuthorize(a.authorizeUrl)}; its capability is unavailable until they do. Do not ask the user for authorization codes, tokens, or callback URLs.`;
210
+ if (a.reason === "none")
211
+ return `${what} was not sent to MCP server "${serverLabel}": the deployment holds no authorization of this user for it. ${owed} The request was not delivered, so the server did not execute it.`;
212
+ const refused = `${what} on MCP server "${serverLabel}" was refused ${a.reason === "scope" ? "for insufficient scope (HTTP 403)" : "as unauthorized (HTTP 401)"}`;
213
+ return renewed ? `${refused}; the deployment has since answered another credential, which a new call carries — this call was not sent again. If that call is refused too: ${owed}${writeTail}` : `${refused}. ${owed}${writeTail}`;
157
214
  }
158
215
  function classOf(err, at) {
159
216
  for (const rule of FAILURE_CLASSIFIER)
@@ -185,6 +242,7 @@ export function describeHttpTransportFailure(err, at = { phase: "request" }) {
185
242
  case "connection_failed":
186
243
  return { condition: `the connection to its HTTP endpoint failed (${networkErrorCode(err)})`, delivered: f.delivered };
187
244
  case "connection_closed":
245
+ case "unauthorized":
188
246
  case "spawn_failed":
189
247
  case "timeout":
190
248
  case "protocol":
@@ -13,7 +13,16 @@
13
13
  * replacement, so a late 404 never closes a connection other calls have moved to.
14
14
  */
15
15
  import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
16
- import type { McpExchangeOutcome } from "./mcp-failure.js";
16
+ import { type McpAuthorization, type McpExchangeOutcome, type McpFailure, type McpFailureSite } from "./mcp-failure.js";
17
+ /**
18
+ * One request failure, read once and told to the server's two writers: its reach ({@link ServerHealth.observe}) always, and — when
19
+ * `answer` (this failure is the request's answer: the lane sends nothing again) — the authorization the user owes
20
+ * ({@link ServerHealth.owed}). Returns the record.
21
+ */
22
+ export declare function observedFailure(err: unknown, site: McpFailureSite, health: ServerHealth | undefined, answer: boolean): McpFailure;
23
+ /** A tool call's FINAL failure (the translated error, whose `details` is the record the one reading stamped) tells the server's
24
+ * announcer what the user owes — the call lane's one announcement, made once its attempts are over. */
25
+ export declare function owedByAnswer(err: unknown, health: ServerHealth): void;
17
26
  /** Mutable per-server liveness flag, shared between a server's tool closures and its transport-close hook.
18
27
  * `pendingElicitations` (RB-199 FO-1 codex review): a live count of in-flight `onElicit` waits on THIS
19
28
  * server — the idle watchdog ({@link armMcpIdleWatchdog}) reads it before aborting a call (incremented when the wait starts,
@@ -37,6 +46,9 @@ export interface ServerHealth {
37
46
  * outage either, and the in-flight calls it fails belong to a connection we chose to replace.
38
47
  */
39
48
  observe?: (outcome: McpExchangeOutcome) => void;
49
+ /** The other thing a request can learn: its ANSWER was a refusal as `unauthorized`, so the user owes this authorization — the
50
+ * materialization's once-per-server announcer, filled by the merge stage beside `observe` (the same lifecycle silence applies). */
51
+ owed?: (authorization: McpAuthorization) => void;
40
52
  pendingElicitations: number;
41
53
  /** Stamped on EVERY
42
54
  * elicitation close (finally, unconditional — not just when the count returns to 0). Closes a race
@@ -156,6 +168,15 @@ export declare class Resendable {
156
168
  * {@link McpListingRefusal} answer only a call that was never sent.
157
169
  */
158
170
  export declare function callThroughLink<R extends object>(link: McpServerLink, name: string, gate: string, signal: AbortSignal | undefined, send: (on: McpLiveConnection, resent: boolean) => Promise<R | Resendable>, gone: () => never): Promise<R | McpListingRefusal>;
171
+ /** What judges a call a refusal turned away: the live connection's listing, the operator's revocation list, the declaration a tool was mounted with. */
172
+ export type RefusalJudge = "listing" | "revocation" | "declaration";
173
+ /**
174
+ * THE closing sentence of an MCP call refused before it was sent: what the refusal covers (this call) and what judges a later call,
175
+ * never how that call will come out — a host's re-dial, refresh or un-revoke lands between two calls, and the call after it is
176
+ * judged against what it took. The listing's refusal, a revoked server's four outlets and the task-required one end with it; no
177
+ * site words it again. (A server whose transport is gone has its own text, `throwDeadServer`.)
178
+ */
179
+ export declare function refusalScope(judge: RefusalJudge): string;
159
180
  /** The answer to a call {@link reach} refused before it was sent: the pre-send refusal record (`delivered: "no"`; `code` beside `error`, as the revocation refusal's). */
160
181
  export declare function listingRefusal(refusal: McpListingRefusal, remoteName: string, server: string): {
161
182
  content: Array<{
@@ -1,5 +1,20 @@
1
+ import { readMcpFailure } from "./mcp-failure.js";
1
2
  import { UNPROVEN_GATE } from "./mcp-listing-drift.js";
3
+ import { readMember } from "./thrown-value.js";
2
4
  import { inlineUntrusted } from "./untrusted-text.js";
5
+ export function observedFailure(err, site, health, answer) {
6
+ const { failure, exchange } = readMcpFailure(err, site);
7
+ health?.observe?.(exchange);
8
+ if (answer && failure.authorization !== undefined)
9
+ health?.owed?.(failure.authorization);
10
+ return failure;
11
+ }
12
+ export function owedByAnswer(err, health) {
13
+ const details = readMember(err, "details");
14
+ const a = readMember(details, "code") === "unauthorized" ? readMember(details, "authorization") : undefined;
15
+ if (typeof a === "object" && a !== null)
16
+ health.owed?.(a);
17
+ }
3
18
  export const IDLE_WATCHDOG_ABORT_REASON = Symbol("mcp-idle-watchdog-abort");
4
19
  export function armMcpIdleWatchdog(health, idleMs, outerSignal) {
5
20
  const idleController = new AbortController();
@@ -89,11 +104,20 @@ export async function callThroughLink(link, name, gate, signal, send, gone) {
89
104
  throw again.error;
90
105
  return again;
91
106
  }
107
+ const REFUSAL_JUDGES = {
108
+ listing: { rule: "each later call to this tool is checked again against the connection's latest listing", standing: "" },
109
+ revocation: { rule: "each later call to this server is checked again against the operator's current revocation list", standing: "This server stays on this run's tool roster. " },
110
+ declaration: { rule: "each later call to this tool is judged by the declaration of the listing it was mounted from, until a refresh or reconnect of the server mints the tool anew", standing: "" },
111
+ };
112
+ export function refusalScope(judge) {
113
+ const j = REFUSAL_JUDGES[judge];
114
+ return `${j.standing}This refusal is for this call only: ${j.rule}.`;
115
+ }
92
116
  export function listingRefusal(refusal, remoteName, server) {
93
117
  const changed = refusal === "changed";
94
118
  const code = changed ? "mcp.tool_declaration_changed" : "mcp.tool_listing_unreached";
95
119
  return {
96
- content: [{ type: "text", text: `The call to tool ${inlineUntrusted(remoteName)} was refused before it was sent: MCP server "${inlineUntrusted(server)}" ${changed ? "no longer declares this tool the way it was mounted (its safety declaration changed, or a complete listing no longer lists it)" : "has not listed this tool since it was reconnected (the re-listing stopped before it reached the tool), so whether the server still declares it the way it was mounted is unknown"}. The server did not execute it. Every call to this tool is refused the same way until a listing of the connection reaches the tool, so don't retry it.` }],
120
+ content: [{ type: "text", text: `The call to tool ${inlineUntrusted(remoteName)} was refused before it was sent: MCP server "${inlineUntrusted(server)}" ${changed ? "no longer declares this tool the way it was mounted (its safety declaration changed, or a complete listing no longer lists it)" : "has not listed this tool since it was reconnected (the re-listing stopped before it reached the tool), so whether the server still declares it the way it was mounted is unknown"}. The server did not execute it. ${refusalScope("listing")}` }],
97
121
  details: { error: code, code, delivered: "no", server },
98
122
  terminate: false,
99
123
  isError: true,
@@ -1,7 +1,7 @@
1
1
  import { type PeerSeat } from "./peer-seat.js";
2
2
  import { type McpInstructionsEntry, type PromptSectionDisposer } from "./prompt-section-seat.js";
3
3
  import { McpConnectionPool } from "./mcp-connection-pool.js";
4
- import { type McpDelivered, type McpFailureKind, type McpServerLiveness } from "./mcp-failure.js";
4
+ import { type McpAuthorization, type McpDelivered, type McpFailureKind, type McpServerLiveness } from "./mcp-failure.js";
5
5
  import type { AgentTool } from "../internal/harness-types.js";
6
6
  import type { ImageContent, TextContent } from "../internal/llm.js";
7
7
  import { type McpImageResizer } from "./image-downsample.js";
@@ -312,8 +312,8 @@ export interface McpReconnectResult {
312
312
  * what the run handle's verb forwards to `onError(phase:"mcp")`. One production, two drains. */
313
313
  warnings?: string[];
314
314
  /** The NEW connect-time status record (also swapped into {@link MaterializedMcp.statuses}), present
315
- * whenever the dial was attempted: a consumer keys its next action off `errorCode` / `httpStatus`
316
- * (a 401 is a re-authorization door, a `spawn_failed` a missing binary), not off {@link reason}. */
315
+ * whenever the dial was attempted: a consumer keys its next action off `errorCode` / `authorization`
316
+ * (an `unauthorized` is the user's authorization door, a `spawn_failed` a missing binary), not off {@link reason}. */
317
317
  status?: McpServerStatus;
318
318
  /** The re-dial's own `tools/list` walk did not finish — {@link McpRefreshResult.listingIncomplete}
319
319
  * minus the retention arm: a re-dial has no previous listing on this connection to retain from. */
@@ -334,13 +334,16 @@ export interface McpServerStatus {
334
334
  };
335
335
  toolNames?: string[];
336
336
  error?: string;
337
- /** Present iff `status === "failed"` — the connect-time failure record, spread flat: {@link McpFailure.kind}
338
- * as `errorCode`, {@link McpFailure.delivered} as `delivered`, and `httpStatus` when the kind is
339
- * `http_status`. A consumer keys an action off THESE (a `http_status` 401 is a re-authorization door,
337
+ /** Present iff `status === "failed"` — the connect-time failure record, spread flat ({@link import("./mcp-failure.js").failureFields}):
338
+ * {@link McpFailure.kind} as `errorCode`, {@link McpFailure.delivered} as `delivered`, `httpStatus` when the kind is `http_status`,
339
+ * `authorization` when it is `unauthorized`. A consumer keys an action off THESE (an `unauthorized` is the user's authorization door,
340
340
  * a `spawn_failed` is a missing binary) instead of parsing the neutralized `error` text. */
341
341
  errorCode?: McpFailureKind;
342
342
  delivered?: McpDelivered;
343
343
  httpStatus?: number;
344
+ /** {@link McpFailure.authorization}: why the principal must authorize this server and where — present iff `errorCode === "unauthorized"`.
345
+ * `authorizeUrl` is the deployment seat's (TRUSTED); `resourceMetadataUrl` is the endpoint's own claim (UNTRUSTED, like `error`). */
346
+ authorization?: McpAuthorization;
344
347
  /**
345
348
  * Set to `true` once core OBSERVES this server's transport close during the task; absent
346
349
  * otherwise (never `false`: absence means "no close was observed", which is not the same as "alive").
@@ -606,10 +609,11 @@ reminderDisclosure?: {
606
609
  }, poolOpts?: {
607
610
  pool: McpConnectionPool;
608
611
  ownsPool?: boolean;
609
- }, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean, signal?: AbortSignal, hostFloor?: HostFloor, peerSeat?: PeerSeat): Promise<MaterializedMcp>;
612
+ }, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean, signal?: AbortSignal, hostFloor?: HostFloor, peerSeat?: PeerSeat, // `RunnerDeps.peerSeat` (peer-seat.ts): what each request carries; absent ⇒ nothing, and a declared `credentials` refuses that dial
613
+ onAuthorizationRequired?: (server: string, authorization: McpAuthorization) => void): Promise<MaterializedMcp>;
610
614
  /** The runner's materialization of one leg (not index-exported): every minted tool's `tools/call` reads the leg's request-meta seat
611
615
  * (`mcp-call-meta.ts`) — the request meta's only source, written only by the `tool.call` station with what its judge passed. */
612
- export declare function materializeLegMcpTools(seat: McpLegMetaReader | undefined, ...[specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts, promptSections, dialable, signal, hostFloor, peerSeat]: Parameters<typeof materializeMcpTools>): Promise<MaterializedMcp>;
616
+ export declare function materializeLegMcpTools(seat: McpLegMetaReader | undefined, ...[specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts, promptSections, dialable, signal, hostFloor, peerSeat, onAuthorizationRequired]: Parameters<typeof materializeMcpTools>): Promise<MaterializedMcp>;
613
617
  /**
614
618
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.
615
619
  * Unlike server hints, the caller may RAISE or LOWER any axis: `effect` sets the repeat-safety class (lower to