@namzu/sdk 39.0.0 → 41.0.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 (289) hide show
  1. package/CHANGELOG.md +328 -0
  2. package/dist/bridge/a2a/mapper.d.ts.map +1 -1
  3. package/dist/bridge/a2a/mapper.js +8 -0
  4. package/dist/bridge/a2a/mapper.js.map +1 -1
  5. package/dist/bridge/sse/mapper.d.ts.map +1 -1
  6. package/dist/bridge/sse/mapper.js +11 -0
  7. package/dist/bridge/sse/mapper.js.map +1 -1
  8. package/dist/connector/index.d.ts +2 -2
  9. package/dist/connector/index.d.ts.map +1 -1
  10. package/dist/connector/index.js +1 -1
  11. package/dist/connector/index.js.map +1 -1
  12. package/dist/connector/mcp/adapter.d.ts.map +1 -1
  13. package/dist/connector/mcp/adapter.js +112 -10
  14. package/dist/connector/mcp/adapter.js.map +1 -1
  15. package/dist/connector/mcp/audio-admission.d.ts +17 -0
  16. package/dist/connector/mcp/audio-admission.d.ts.map +1 -0
  17. package/dist/connector/mcp/audio-admission.js +171 -0
  18. package/dist/connector/mcp/audio-admission.js.map +1 -0
  19. package/dist/connector/mcp/client.d.ts +252 -1
  20. package/dist/connector/mcp/client.d.ts.map +1 -1
  21. package/dist/connector/mcp/client.js +611 -39
  22. package/dist/connector/mcp/client.js.map +1 -1
  23. package/dist/connector/mcp/envelope.d.ts +91 -0
  24. package/dist/connector/mcp/envelope.d.ts.map +1 -0
  25. package/dist/connector/mcp/envelope.js +173 -0
  26. package/dist/connector/mcp/envelope.js.map +1 -0
  27. package/dist/connector/mcp/era.d.ts +130 -0
  28. package/dist/connector/mcp/era.d.ts.map +1 -0
  29. package/dist/connector/mcp/era.js +304 -0
  30. package/dist/connector/mcp/era.js.map +1 -0
  31. package/dist/connector/mcp/errors.d.ts +106 -0
  32. package/dist/connector/mcp/errors.d.ts.map +1 -0
  33. package/dist/connector/mcp/errors.js +154 -0
  34. package/dist/connector/mcp/errors.js.map +1 -0
  35. package/dist/connector/mcp/http-sse.d.ts +11 -0
  36. package/dist/connector/mcp/http-sse.d.ts.map +1 -1
  37. package/dist/connector/mcp/http-sse.js +21 -6
  38. package/dist/connector/mcp/http-sse.js.map +1 -1
  39. package/dist/connector/mcp/index.d.ts +7 -0
  40. package/dist/connector/mcp/index.d.ts.map +1 -1
  41. package/dist/connector/mcp/index.js +10 -0
  42. package/dist/connector/mcp/index.js.map +1 -1
  43. package/dist/connector/mcp/streamable-http.d.ts +83 -0
  44. package/dist/connector/mcp/streamable-http.d.ts.map +1 -1
  45. package/dist/connector/mcp/streamable-http.js +177 -11
  46. package/dist/connector/mcp/streamable-http.js.map +1 -1
  47. package/dist/connector/mcp/x-mcp-header.d.ts +56 -0
  48. package/dist/connector/mcp/x-mcp-header.d.ts.map +1 -0
  49. package/dist/connector/mcp/x-mcp-header.js +254 -0
  50. package/dist/connector/mcp/x-mcp-header.js.map +1 -0
  51. package/dist/constants/mcp/index.d.ts +123 -15
  52. package/dist/constants/mcp/index.d.ts.map +1 -1
  53. package/dist/constants/mcp/index.js +135 -16
  54. package/dist/constants/mcp/index.js.map +1 -1
  55. package/dist/manager/agent/lifecycle.d.ts.map +1 -1
  56. package/dist/manager/agent/lifecycle.js +23 -0
  57. package/dist/manager/agent/lifecycle.js.map +1 -1
  58. package/dist/manager/run/persistence.d.ts +8 -0
  59. package/dist/manager/run/persistence.d.ts.map +1 -1
  60. package/dist/manager/run/persistence.js +12 -0
  61. package/dist/manager/run/persistence.js.map +1 -1
  62. package/dist/prompt/coding-agent-doctrine.d.ts +20 -0
  63. package/dist/prompt/coding-agent-doctrine.d.ts.map +1 -1
  64. package/dist/prompt/coding-agent-doctrine.js +19 -3
  65. package/dist/prompt/coding-agent-doctrine.js.map +1 -1
  66. package/dist/prompt/index.d.ts +1 -1
  67. package/dist/prompt/index.d.ts.map +1 -1
  68. package/dist/prompt/index.js +1 -1
  69. package/dist/prompt/index.js.map +1 -1
  70. package/dist/public-runtime.d.ts +6 -4
  71. package/dist/public-runtime.d.ts.map +1 -1
  72. package/dist/public-runtime.js +8 -4
  73. package/dist/public-runtime.js.map +1 -1
  74. package/dist/public-tools.d.ts +11 -0
  75. package/dist/public-tools.d.ts.map +1 -1
  76. package/dist/public-tools.js +14 -0
  77. package/dist/public-tools.js.map +1 -1
  78. package/dist/registry/tool/execute.d.ts.map +1 -1
  79. package/dist/registry/tool/execute.js +2 -3
  80. package/dist/registry/tool/execute.js.map +1 -1
  81. package/dist/registry/tool/portable.d.ts +65 -0
  82. package/dist/registry/tool/portable.d.ts.map +1 -0
  83. package/dist/registry/tool/portable.js +244 -0
  84. package/dist/registry/tool/portable.js.map +1 -0
  85. package/dist/registry/tool/schema.d.ts +32 -5
  86. package/dist/registry/tool/schema.d.ts.map +1 -1
  87. package/dist/registry/tool/schema.js +35 -9
  88. package/dist/registry/tool/schema.js.map +1 -1
  89. package/dist/registry/toolset/catalog.js +8 -8
  90. package/dist/registry/toolset/catalog.js.map +1 -1
  91. package/dist/runtime/jobs/awaited-jobs.d.ts +215 -0
  92. package/dist/runtime/jobs/awaited-jobs.d.ts.map +1 -0
  93. package/dist/runtime/jobs/awaited-jobs.js +259 -0
  94. package/dist/runtime/jobs/awaited-jobs.js.map +1 -0
  95. package/dist/runtime/jobs/registry.d.ts +33 -2
  96. package/dist/runtime/jobs/registry.d.ts.map +1 -1
  97. package/dist/runtime/jobs/registry.js +37 -0
  98. package/dist/runtime/jobs/registry.js.map +1 -1
  99. package/dist/runtime/query/executor.d.ts +28 -0
  100. package/dist/runtime/query/executor.d.ts.map +1 -1
  101. package/dist/runtime/query/executor.js +39 -1
  102. package/dist/runtime/query/executor.js.map +1 -1
  103. package/dist/runtime/query/file-evidence-context.d.ts.map +1 -1
  104. package/dist/runtime/query/file-evidence-context.js +159 -43
  105. package/dist/runtime/query/file-evidence-context.js.map +1 -1
  106. package/dist/runtime/query/file-evidence-replay.d.ts +260 -0
  107. package/dist/runtime/query/file-evidence-replay.d.ts.map +1 -0
  108. package/dist/runtime/query/file-evidence-replay.js +647 -0
  109. package/dist/runtime/query/file-evidence-replay.js.map +1 -0
  110. package/dist/runtime/query/file-evidence-seed.d.ts +50 -0
  111. package/dist/runtime/query/file-evidence-seed.d.ts.map +1 -0
  112. package/dist/runtime/query/file-evidence-seed.js +100 -0
  113. package/dist/runtime/query/file-evidence-seed.js.map +1 -0
  114. package/dist/runtime/query/index.d.ts.map +1 -1
  115. package/dist/runtime/query/index.js +94 -2
  116. package/dist/runtime/query/index.js.map +1 -1
  117. package/dist/runtime/query/iteration/index.d.ts +87 -9
  118. package/dist/runtime/query/iteration/index.d.ts.map +1 -1
  119. package/dist/runtime/query/iteration/index.js +193 -28
  120. package/dist/runtime/query/iteration/index.js.map +1 -1
  121. package/dist/runtime/query/iteration/phases/context.d.ts +10 -0
  122. package/dist/runtime/query/iteration/phases/context.d.ts.map +1 -1
  123. package/dist/runtime/query/iteration/phases/context.js.map +1 -1
  124. package/dist/runtime/query/iteration/phases/tool-review.d.ts.map +1 -1
  125. package/dist/runtime/query/iteration/phases/tool-review.js +5 -1
  126. package/dist/runtime/query/iteration/phases/tool-review.js.map +1 -1
  127. package/dist/runtime/query/plugin-hooks.d.ts +14 -0
  128. package/dist/runtime/query/plugin-hooks.d.ts.map +1 -1
  129. package/dist/runtime/query/plugin-hooks.js +18 -0
  130. package/dist/runtime/query/plugin-hooks.js.map +1 -1
  131. package/dist/runtime/query/repeat-call.d.ts +17 -4
  132. package/dist/runtime/query/repeat-call.d.ts.map +1 -1
  133. package/dist/runtime/query/repeat-call.js +26 -19
  134. package/dist/runtime/query/repeat-call.js.map +1 -1
  135. package/dist/runtime/query/steering.d.ts +11 -1
  136. package/dist/runtime/query/steering.d.ts.map +1 -1
  137. package/dist/runtime/query/steering.js +12 -1
  138. package/dist/runtime/query/steering.js.map +1 -1
  139. package/dist/runtime/query/tooling.d.ts +2 -0
  140. package/dist/runtime/query/tooling.d.ts.map +1 -1
  141. package/dist/runtime/query/tooling.js +1 -0
  142. package/dist/runtime/query/tooling.js.map +1 -1
  143. package/dist/sandbox/provider/local.d.ts.map +1 -1
  144. package/dist/sandbox/provider/local.js +46 -3
  145. package/dist/sandbox/provider/local.js.map +1 -1
  146. package/dist/scheduler/completion-inbox.d.ts +48 -2
  147. package/dist/scheduler/completion-inbox.d.ts.map +1 -1
  148. package/dist/scheduler/completion-inbox.js +102 -10
  149. package/dist/scheduler/completion-inbox.js.map +1 -1
  150. package/dist/scheduler/local.d.ts.map +1 -1
  151. package/dist/scheduler/local.js +8 -0
  152. package/dist/scheduler/local.js.map +1 -1
  153. package/dist/store/run/disk.d.ts +35 -1
  154. package/dist/store/run/disk.d.ts.map +1 -1
  155. package/dist/store/run/disk.js +100 -0
  156. package/dist/store/run/disk.js.map +1 -1
  157. package/dist/tools/builtins/bash.d.ts.map +1 -1
  158. package/dist/tools/builtins/bash.js +4 -10
  159. package/dist/tools/builtins/bash.js.map +1 -1
  160. package/dist/tools/builtins/edit-apply.d.ts +126 -0
  161. package/dist/tools/builtins/edit-apply.d.ts.map +1 -0
  162. package/dist/tools/builtins/edit-apply.js +360 -0
  163. package/dist/tools/builtins/edit-apply.js.map +1 -0
  164. package/dist/tools/builtins/edit.d.ts +143 -1
  165. package/dist/tools/builtins/edit.d.ts.map +1 -1
  166. package/dist/tools/builtins/edit.js +37 -219
  167. package/dist/tools/builtins/edit.js.map +1 -1
  168. package/dist/tools/builtins/index.d.ts +1 -0
  169. package/dist/tools/builtins/index.d.ts.map +1 -1
  170. package/dist/tools/builtins/index.js +9 -3
  171. package/dist/tools/builtins/index.js.map +1 -1
  172. package/dist/tools/builtins/job.js +1 -1
  173. package/dist/tools/builtins/job.js.map +1 -1
  174. package/dist/tools/builtins/read-file.d.ts +2 -2
  175. package/dist/tools/builtins/read-file.d.ts.map +1 -1
  176. package/dist/tools/builtins/read-file.js +50 -65
  177. package/dist/tools/builtins/read-file.js.map +1 -1
  178. package/dist/tools/builtins/read-render.d.ts +56 -0
  179. package/dist/tools/builtins/read-render.d.ts.map +1 -0
  180. package/dist/tools/builtins/read-render.js +73 -0
  181. package/dist/tools/builtins/read-render.js.map +1 -0
  182. package/dist/tools/builtins/wait-for-job-bounds.d.ts +67 -0
  183. package/dist/tools/builtins/wait-for-job-bounds.d.ts.map +1 -0
  184. package/dist/tools/builtins/wait-for-job-bounds.js +108 -0
  185. package/dist/tools/builtins/wait-for-job-bounds.js.map +1 -0
  186. package/dist/tools/builtins/wait-for-job.d.ts +6 -0
  187. package/dist/tools/builtins/wait-for-job.d.ts.map +1 -0
  188. package/dist/tools/builtins/wait-for-job.js +162 -0
  189. package/dist/tools/builtins/wait-for-job.js.map +1 -0
  190. package/dist/tools/builtins/write-file.js +5 -0
  191. package/dist/tools/builtins/write-file.js.map +1 -1
  192. package/dist/tools/coordinator/index.d.ts.map +1 -1
  193. package/dist/tools/coordinator/index.js +1 -7
  194. package/dist/tools/coordinator/index.js.map +1 -1
  195. package/dist/tools/file-read-tracker.d.ts.map +1 -1
  196. package/dist/tools/file-read-tracker.js +88 -10
  197. package/dist/tools/file-read-tracker.js.map +1 -1
  198. package/dist/types/agent/scheduler.d.ts +20 -0
  199. package/dist/types/agent/scheduler.d.ts.map +1 -1
  200. package/dist/types/agent/task.d.ts +20 -0
  201. package/dist/types/agent/task.d.ts.map +1 -1
  202. package/dist/types/connector/mcp.d.ts +205 -0
  203. package/dist/types/connector/mcp.d.ts.map +1 -1
  204. package/dist/types/message/index.d.ts +1 -1
  205. package/dist/types/message/index.d.ts.map +1 -1
  206. package/dist/types/message/index.js +2 -0
  207. package/dist/types/message/index.js.map +1 -1
  208. package/dist/types/run/entity.d.ts +13 -0
  209. package/dist/types/run/entity.d.ts.map +1 -1
  210. package/dist/types/run/events.d.ts +56 -0
  211. package/dist/types/run/events.d.ts.map +1 -1
  212. package/dist/types/run/events.js.map +1 -1
  213. package/dist/types/run/store.d.ts +41 -0
  214. package/dist/types/run/store.d.ts.map +1 -1
  215. package/dist/types/sandbox/index.d.ts +83 -15
  216. package/dist/types/sandbox/index.d.ts.map +1 -1
  217. package/dist/types/sandbox/index.js.map +1 -1
  218. package/dist/types/tool/index.d.ts +109 -0
  219. package/dist/types/tool/index.d.ts.map +1 -1
  220. package/dist/types/tool/index.js.map +1 -1
  221. package/dist/utils/env.d.ts +19 -0
  222. package/dist/utils/env.d.ts.map +1 -0
  223. package/dist/utils/env.js +25 -0
  224. package/dist/utils/env.js.map +1 -0
  225. package/package.json +1 -1
  226. package/src/bridge/a2a/mapper.ts +8 -0
  227. package/src/bridge/sse/mapper.ts +11 -0
  228. package/src/connector/index.ts +27 -0
  229. package/src/connector/mcp/adapter.ts +123 -10
  230. package/src/connector/mcp/audio-admission.ts +173 -0
  231. package/src/connector/mcp/client.ts +694 -45
  232. package/src/connector/mcp/envelope.ts +235 -0
  233. package/src/connector/mcp/era.ts +400 -0
  234. package/src/connector/mcp/errors.ts +171 -0
  235. package/src/connector/mcp/http-sse.ts +23 -6
  236. package/src/connector/mcp/index.ts +37 -0
  237. package/src/connector/mcp/streamable-http.ts +199 -11
  238. package/src/connector/mcp/x-mcp-header.ts +322 -0
  239. package/src/constants/mcp/index.ts +145 -16
  240. package/src/manager/agent/lifecycle.ts +29 -0
  241. package/src/manager/run/persistence.ts +12 -0
  242. package/src/prompt/coding-agent-doctrine.ts +31 -4
  243. package/src/prompt/index.ts +1 -0
  244. package/src/public-runtime.ts +37 -1
  245. package/src/public-tools.ts +18 -0
  246. package/src/registry/tool/execute.ts +2 -4
  247. package/src/registry/tool/portable.ts +264 -0
  248. package/src/registry/tool/schema.ts +38 -8
  249. package/src/registry/toolset/catalog.ts +8 -9
  250. package/src/runtime/jobs/awaited-jobs.ts +271 -0
  251. package/src/runtime/jobs/registry.ts +50 -0
  252. package/src/runtime/query/executor.ts +49 -1
  253. package/src/runtime/query/file-evidence-context.ts +190 -46
  254. package/src/runtime/query/file-evidence-replay.ts +776 -0
  255. package/src/runtime/query/file-evidence-seed.ts +126 -0
  256. package/src/runtime/query/index.ts +104 -2
  257. package/src/runtime/query/iteration/index.ts +202 -28
  258. package/src/runtime/query/iteration/phases/context.ts +10 -0
  259. package/src/runtime/query/iteration/phases/tool-review.ts +4 -0
  260. package/src/runtime/query/plugin-hooks.ts +20 -0
  261. package/src/runtime/query/repeat-call.ts +28 -18
  262. package/src/runtime/query/steering.ts +11 -0
  263. package/src/runtime/query/tooling.ts +3 -0
  264. package/src/sandbox/provider/local.ts +45 -2
  265. package/src/scheduler/completion-inbox.ts +105 -9
  266. package/src/scheduler/local.ts +8 -0
  267. package/src/store/run/disk.ts +108 -0
  268. package/src/tools/builtins/bash.ts +4 -10
  269. package/src/tools/builtins/edit-apply.ts +456 -0
  270. package/src/tools/builtins/edit.ts +39 -270
  271. package/src/tools/builtins/index.ts +9 -3
  272. package/src/tools/builtins/job.ts +1 -1
  273. package/src/tools/builtins/read-file.ts +56 -77
  274. package/src/tools/builtins/read-render.ts +104 -0
  275. package/src/tools/builtins/wait-for-job-bounds.ts +179 -0
  276. package/src/tools/builtins/wait-for-job.ts +184 -0
  277. package/src/tools/builtins/write-file.ts +5 -0
  278. package/src/tools/coordinator/index.ts +1 -7
  279. package/src/tools/file-read-tracker.ts +85 -7
  280. package/src/types/agent/scheduler.ts +21 -0
  281. package/src/types/agent/task.ts +21 -0
  282. package/src/types/connector/mcp.ts +205 -1
  283. package/src/types/message/index.ts +2 -0
  284. package/src/types/run/entity.ts +14 -0
  285. package/src/types/run/events.ts +56 -0
  286. package/src/types/run/store.ts +42 -0
  287. package/src/types/sandbox/index.ts +84 -15
  288. package/src/types/tool/index.ts +104 -0
  289. package/src/utils/env.ts +23 -0
@@ -1,4 +1,4 @@
1
- import type { MCPClientConfig, MCPClientState, MCPContentBlock, MCPEventListener, MCPInitializeResult, MCPPromptDefinition, MCPPromptMessage, MCPRequestOptions, MCPResource, MCPResourceTemplate, MCPToolDefinition, MCPToolResult } from '../../types/connector/index.js';
1
+ import type { MCPClientConfig, MCPClientState, MCPContentBlock, MCPEventListener, MCPInitializeResult, MCPPromptDefinition, MCPPromptMessage, MCPRequestOptions, MCPResource, MCPResourceTemplate, MCPToolDefinition, MCPToolResult, McpEra } from '../../types/connector/index.js';
2
2
  import type { MCPClientId } from '../../types/ids/index.js';
3
3
  export declare class MCPClient {
4
4
  readonly id: MCPClientId;
@@ -6,6 +6,7 @@ export declare class MCPClient {
6
6
  private status;
7
7
  private serverInfo?;
8
8
  private serverCapabilities?;
9
+ private era?;
9
10
  private connectedAt?;
10
11
  private error?;
11
12
  private pendingRequests;
@@ -17,13 +18,192 @@ export declare class MCPClient {
17
18
  private log;
18
19
  private readonly config;
19
20
  private readonly requestTimeoutMs;
21
+ private readonly eraCache;
22
+ private readonly eraCacheKey;
23
+ private readonly eraProbeTimeoutMs;
24
+ /**
25
+ * What each listed tool asked to mirror into `Mcp-Param-*` headers,
26
+ * by tool name.
27
+ *
28
+ * Rebuilt by every `listTools()` and empty until the first one: a header
29
+ * is only ever written from a schema this client has seen the server
30
+ * publish, so a stale binding cannot outlive the listing that produced
31
+ * it.
32
+ */
33
+ private toolParamHeaders;
20
34
  constructor(config: MCPClientConfig);
21
35
  connect(): Promise<MCPInitializeResult>;
36
+ /**
37
+ * One `initialize` round trip, offering the newest legacy version this
38
+ * client speaks — never a per-version waterfall. The spec's own
39
+ * backward-compatibility algorithm offers one version and honors
40
+ * whatever the server answers with; a three-step retry loop would be
41
+ * three times the latency for a path no server expects.
42
+ * `protocol-negotiation.test.ts` counts `initialize` frames so this
43
+ * stays true.
44
+ *
45
+ * Shared by `connect()`'s first handshake and by
46
+ * {@link reinitializeLegacySession}'s recovery from a `404`d session —
47
+ * the second call is not a special case, it is this same function run
48
+ * again on a connection that already exists.
49
+ */
50
+ private performLegacyInitializeHandshake;
51
+ /**
52
+ * A request answered `404` on a session-bearing legacy connection: the
53
+ * legacy Streamable HTTP transports specify that a terminated session
54
+ * answers this way, and the client's remedy is to drop it and run the
55
+ * handshake again, exactly once, before giving up.
56
+ *
57
+ * Gated to legacy by construction, not by a flag: `hasSession()` is only
58
+ * ever true on a connection that completed the legacy `initialize`
59
+ * handshake in the first place — a modern connection never calls it (see
60
+ * `probeDiscover`), so `resetSession`/`hasSession` have nothing to report
61
+ * there.
62
+ */
63
+ private isLegacySessionLostError;
64
+ /** Drop the stale session and run the legacy handshake again, from scratch. */
65
+ private reinitializeLegacySession;
66
+ /**
67
+ * `request()`, with the legacy session recovery a live connection needs
68
+ * that the initial handshake does not: `connect()`'s own `initialize`
69
+ * call has no session yet to lose, so it goes through `request()`
70
+ * directly and never through here.
71
+ *
72
+ * At most one recovery attempt. A retry that fails the same way is not
73
+ * retried again — surfacing it is more honest than masking a second
74
+ * genuine failure as a transient one.
75
+ */
76
+ private requestWithSessionRecovery;
77
+ /**
78
+ * Which era this peer speaks, probed once and remembered per origin (or
79
+ * per stdio command).
80
+ *
81
+ * Modern first. The wasted round trip against a legacy server is real
82
+ * and is the reason the cache exists; the alternative is worse than
83
+ * wasted latency, because a legacy server handed an era-ambiguous method
84
+ * processes it under legacy semantics and fails confusingly, where a
85
+ * probe fails cleanly and recovers.
86
+ */
87
+ private resolveEra;
88
+ /**
89
+ * Ask the peer to describe itself, and report silence as an answer.
90
+ *
91
+ * Deliberately NOT `request()`. A probe differs from a request in the
92
+ * two ways that matter: a timeout is a legitimate outcome rather than a
93
+ * failure — the stdio spec says in so many words that a legacy server
94
+ * may not respond at all — and a probe that gives up must not send
95
+ * `notifications/cancelled`, because the peer it would be sent to is, by
96
+ * hypothesis, one that did not understand the request in the first
97
+ * place. Everything `request()` owns about cancellation ordering is left
98
+ * exactly as it is rather than taught a second mode.
99
+ */
100
+ private probeDiscover;
101
+ /**
102
+ * Finish a connection that resolved modern, with no handshake at all.
103
+ *
104
+ * The modern era has no `initialize` and no `notifications/initialized`,
105
+ * so there is nothing here to await: the probe already carried the only
106
+ * round trip a modern connection needs. `MCPInitializeResult` is
107
+ * synthesised from the `DiscoverResult` so a host sees the same return
108
+ * shape whichever era resolved — the era is this client's business, not
109
+ * something every caller has to branch on.
110
+ */
111
+ private completeModernConnection;
112
+ /**
113
+ * A `DiscoverResult` read as the `MCPInitializeResult` a host expects.
114
+ *
115
+ * `serverInfo` is a SHOULD on a discover result, not a MUST, and
116
+ * `MCPInitializeResult.serverInfo` is required — so a server that does
117
+ * not name itself is reported under the name the operator gave it.
118
+ * Inventing a placeholder like "unknown" would put a word in the
119
+ * server's mouth in the one field a person reads to identify it.
120
+ */
121
+ private modernInitializeResult;
22
122
  disconnect(): Promise<void>;
23
123
  isConnected(): boolean;
124
+ /**
125
+ * Which era and exact revision the last `connect()` negotiated.
126
+ *
127
+ * `undefined` before a connection has been negotiated. Which arm it
128
+ * lands on is the peer's answer, not a configuration: `connect()` probes
129
+ * for a modern server and falls back to the legacy handshake.
130
+ */
131
+ getEra(): McpEra | undefined;
24
132
  getState(): MCPClientState;
133
+ /**
134
+ * Every tool this server publishes that this client is willing to expose.
135
+ *
136
+ * The second clause is new and it is the first place namzu refuses
137
+ * something a server offered. A tool whose `inputSchema` carries an
138
+ * invalid `x-mcp-header` annotation is excluded from the result, with the
139
+ * tool name and the reason logged — the spec's requirement, and the
140
+ * reason it is a requirement is that the annotation names a header this
141
+ * client would otherwise write from a value it cannot vouch for.
142
+ *
143
+ * It lives HERE rather than in `MCPToolDiscovery` or the tool adapter
144
+ * because the shipping CLI calls `listTools()` directly and never
145
+ * touches discovery: validating one layer up would exempt the one caller
146
+ * that matters most.
147
+ */
25
148
  listTools(options?: MCPRequestOptions): Promise<MCPToolDefinition[]>;
149
+ /**
150
+ * Call one tool, and recover once from a server that says our mirrored
151
+ * headers disagree with its current schema.
152
+ *
153
+ * `-32020` (`HeaderMismatch`) means the `Mcp-Param-*` headers this client
154
+ * wrote are missing or wrong for the schema the server holds NOW — which
155
+ * a server can legitimately cause by changing a tool between the listing
156
+ * and the call. The spec's recovery is to re-read `tools/list` and retry
157
+ * the request once. Exactly once: the retry goes through `request()`
158
+ * rather than back through this method, so a second `-32020` surfaces to
159
+ * the caller instead of starting a third round trip.
160
+ */
26
161
  callTool(name: string, args?: Record<string, unknown>, options?: MCPRequestOptions): Promise<MCPToolResult>;
162
+ /**
163
+ * Does this connection mirror tool parameters into `Mcp-Param-*` headers?
164
+ *
165
+ * Conditioned on the TRANSPORT, not on the era, because that is how the
166
+ * spec conditions it: the feature belongs to Streamable HTTP, and a
167
+ * client on another transport may ignore `x-mcp-header` entirely. stdio
168
+ * has no headers to mirror into, and `http-sse` is the 2024-11-05
169
+ * transport, which predates the annotation by two years.
170
+ *
171
+ * The headers themselves are written only on a modern request — that is
172
+ * `buildEnvelope`'s doing, not this predicate's — but the VALIDATION runs
173
+ * in both eras on this transport, so a tool's admission does not silently
174
+ * change shape the day the server behind it stops answering `initialize`.
175
+ */
176
+ private mirrorsParamHeaders;
177
+ /**
178
+ * Drop the tools whose header annotations this client will not honour,
179
+ * and remember what the rest asked to mirror.
180
+ *
181
+ * One malformed definition must not deny the others, which is why this
182
+ * filters rather than throws: a server with fifty tools and one bad
183
+ * annotation stays a server with forty-nine usable tools.
184
+ */
185
+ private admitToolHeaderAnnotations;
186
+ /**
187
+ * `tools/call`, resolved past the MRTR `resultType` envelope.
188
+ *
189
+ * Absent or `"complete"` is the ordinary path — unchanged from before
190
+ * this existed. `"input_required"` with nothing but a `requestState` is
191
+ * retried exactly once, echoing that state byte-for-byte under a NEW
192
+ * JSON-RPC id (a fresh `request()` call, which allocates one): the
193
+ * spec's own words are that the client MAY retry immediately when there
194
+ * is nothing for it to gather. Any other shape — `inputRequests` this
195
+ * client cannot satisfy, or a second `input_required` after the one
196
+ * retry — throws `MCPInputRequiredError` rather than looping or
197
+ * returning something that looks like success; `mcpToolToToolDefinition`
198
+ * catches it and turns it into a named, catchable `ToolResult` instead
199
+ * of letting it reach a caller as an unexplained rejection.
200
+ *
201
+ * `requestState` travels back as a top-level `requestState` param,
202
+ * alongside `name`/`arguments`, the same way `listAllPages` threads a
203
+ * `cursor` — the one continuation-style field this codebase already has
204
+ * a convention for.
205
+ */
206
+ private callToolDecoded;
27
207
  listResources(options?: MCPRequestOptions): Promise<MCPResource[]>;
28
208
  readResource(uri: string, options?: MCPRequestOptions): Promise<MCPContentBlock[]>;
29
209
  /**
@@ -110,6 +290,77 @@ export declare class MCPClient {
110
290
  * crash, just a process that stopped.
111
291
  */
112
292
  private request;
293
+ /**
294
+ * `{ headers: {...} }` when the era produced any, `{}` otherwise —
295
+ * spread into a `send()` options object so a send with no era headers
296
+ * (a legacy era before 2025-06-18, and everything sent before an era is
297
+ * resolved) gets no `headers` key at all rather than one holding an
298
+ * empty object.
299
+ */
300
+ private eraHeaderOptions;
301
+ /**
302
+ * `{ paramHeaders }` for a `tools/call` whose tool asked for mirrored
303
+ * headers, `{}` for everything else — spread into the envelope input so
304
+ * every other request is built from exactly the object it was built from
305
+ * before this existed.
306
+ *
307
+ * Read from the last listing rather than passed down from `callTool`, so
308
+ * the bindings are the ones that came with the schema the caller was
309
+ * shown, whichever call site reached `request()`.
310
+ */
311
+ private paramHeaderBindings;
312
+ /**
313
+ * `request()`'s full per-send header authority: the era's own headers
314
+ * from `buildEnvelope`, this call's `MCPRequestOptions.headers` merged
315
+ * over them — a collision resolves to the caller's value, except on the
316
+ * headers the protocol itself owns — and this call's `bearerToken`, if
317
+ * given, applied last as `Authorization` so it overrides a same-named
318
+ * header from either of the other two sources.
319
+ *
320
+ * **The exception.** `MCP-Protocol-Version`, `Mcp-Method` and `Mcp-Name`
321
+ * are not decoration: each mirrors a value the same request carries in
322
+ * its body — the negotiated version in
323
+ * `_meta['io.modelcontextprotocol/protocolVersion']`, the method, the
324
+ * target's name — and a conforming modern server rejects a header that
325
+ * disagrees with what it mirrors (`-32020`, HeaderMismatch). Letting a
326
+ * caller's value win there would make the mismatched pair
327
+ * {@link buildEnvelope} exists to render unconstructible constructible
328
+ * again one layer up, and the failure would reach the host as an opaque
329
+ * 400 with nothing pointing at the header that caused it. So a caller
330
+ * header colliding with one of {@link CANONICAL_MCP_REQUEST_HEADERS} is
331
+ * refused and warn-logged, naming it — in EVERY era, including a legacy
332
+ * one old enough that {@link buildEnvelope} puts no headers of its own
333
+ * on this request. Matching ignores case, because HTTP field names are
334
+ * case-insensitive and `{ 'mcp-protocol-version': … }` alongside the
335
+ * era's `MCP-Protocol-Version` would otherwise reach the wire as one
336
+ * field holding both values, comma-joined.
337
+ *
338
+ * Every other header a caller sends is untouched, in both eras.
339
+ *
340
+ * `notify()` and `sendCancellation()` are internal, not caller-facing,
341
+ * so they carry era headers alone — only a public request the caller
342
+ * shaped can carry a per-call header or token.
343
+ *
344
+ * Returns `{}`, never `{ headers: undefined }`, when nothing applies, so
345
+ * the zero-option path stays the exact object shape `request()` sent
346
+ * before any of this existed.
347
+ */
348
+ private requestAuthorityHeaders;
349
+ /**
350
+ * Does a cancelled request on THIS connection owe the peer a
351
+ * `notifications/cancelled`?
352
+ *
353
+ * Everywhere except modern Streamable HTTP, yes. There, no: closing the
354
+ * SSE response stream IS the cancellation signal, so the notification is
355
+ * a second, redundant POST — and one the spec does not ask for. stdio
356
+ * has no stream to close, so it still sends it, in every era.
357
+ *
358
+ * This predicate is the ONLY thing the modern era changes about
359
+ * cancellation. The ordering guarantees in `request()` — who owns
360
+ * cleanup, which cause wins, when the transport is aborted — are
361
+ * untouched.
362
+ */
363
+ private sendsCancellationNotification;
113
364
  /** Ask the peer to stop without letting cleanup become another hanging request. */
114
365
  private sendCancellation;
115
366
  private abortCancellations;
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/connector/mcp/client.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/connector/mcp/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,eAAe,EACf,cAAc,EAEd,eAAe,EAGf,gBAAgB,EAChB,mBAAmB,EAGnB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EAEnB,iBAAiB,EACjB,aAAa,EAGb,MAAM,EAGN,MAAM,gCAAgC,CAAA;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AA0F3D,qBAAa,SAAS;IACrB,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAA;IACxB,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,MAAM,CAAsC;IACpD,OAAO,CAAC,UAAU,CAAC,CAAoC;IACvD,OAAO,CAAC,kBAAkB,CAAC,CAAuB;IAClD,OAAO,CAAC,GAAG,CAAC,CAAQ;IACpB,OAAO,CAAC,WAAW,CAAC,CAAQ;IAC5B,OAAO,CAAC,KAAK,CAAC,CAAQ;IACtB,OAAO,CAAC,eAAe,CAOpB;IACH,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,oBAAoB,CACzB;IACH,OAAO,CAAC,kBAAkB,CAAyB;IACnD,qFAAqF;IACrF,OAAO,CAAC,uBAAuB,CAA6B;IAC5D,OAAO,CAAC,GAAG,CAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAC1C;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB,CAA2D;gBAEvE,MAAM,EAAE,eAAe;IA6B7B,OAAO,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAsE7C;;;;;;;;;;;;;OAaG;YACW,gCAAgC;IAoD9C;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,wBAAwB;IAUhC,+EAA+E;YACjE,yBAAyB;IAOvC;;;;;;;;;OASG;YACW,0BAA0B;IAkBxC;;;;;;;;;OASG;YACW,UAAU;IAqBxB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IA6CrB;;;;;;;;;OASG;IACH,OAAO,CAAC,wBAAwB;IA2BhC;;;;;;;;OAQG;IACH,OAAO,CAAC,sBAAsB;IAWxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC,WAAW,IAAI,OAAO;IAItB;;;;;;OAMG;IACH,MAAM,IAAI,MAAM,GAAG,SAAS;IAI5B,QAAQ,IAAI,cAAc;IAY1B;;;;;;;;;;;;;;OAcG;IACG,SAAS,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAM1E;;;;;;;;;;;OAWG;IACG,QAAQ,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,aAAa,CAAC;IAezB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,mBAAmB;IAK3B;;;;;;;OAOG;IACH,OAAO,CAAC,0BAA0B;IAuBlC;;;;;;;;;;;;;;;;;;;OAmBG;YACW,eAAe;IAyCvB,aAAa,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAKlE,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAQxF;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAK9E;;;;;;;;OAQG;IACG,SAAS,CACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;KAAE,CAAC;IAgB5D,qBAAqB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAKxF;;;;;;;;;;;;;;;;OAgBG;YACW,YAAY;IA6B1B,cAAc,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,IAAI;IAIzF;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,IAAI;IAQnD;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,eAAe;IAcvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,OAAO;IAgIf;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;;;;;;;OASG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,OAAO,CAAC,uBAAuB;IA4B/B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,6BAA6B;IAKrC,mFAAmF;IACnF,OAAO,CAAC,gBAAgB;IA+CxB,OAAO,CAAC,kBAAkB;IAK1B;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;YAYV,MAAM;IAgBpB,OAAO,CAAC,aAAa;IAgDrB,OAAO,CAAC,gBAAgB;CAOxB"}