@cyanheads/mcp-ts-core 0.13.7 → 0.13.9

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 (274) hide show
  1. package/AGENTS.md +19 -15
  2. package/CLAUDE.md +19 -15
  3. package/README.md +4 -2
  4. package/changelog/0.13.x/0.13.8.md +101 -0
  5. package/changelog/0.13.x/0.13.9.md +113 -0
  6. package/dist/config/index.d.ts +9 -0
  7. package/dist/config/index.d.ts.map +1 -1
  8. package/dist/config/index.js +39 -9
  9. package/dist/config/index.js.map +1 -1
  10. package/dist/core/app.d.ts +6 -3
  11. package/dist/core/app.d.ts.map +1 -1
  12. package/dist/core/app.js +20 -6
  13. package/dist/core/app.js.map +1 -1
  14. package/dist/core/context.d.ts +25 -1
  15. package/dist/core/context.d.ts.map +1 -1
  16. package/dist/core/context.js +13 -3
  17. package/dist/core/context.js.map +1 -1
  18. package/dist/core/serverManifest.d.ts +6 -0
  19. package/dist/core/serverManifest.d.ts.map +1 -1
  20. package/dist/core/serverManifest.js +6 -0
  21. package/dist/core/serverManifest.js.map +1 -1
  22. package/dist/core/worker.d.ts +2 -0
  23. package/dist/core/worker.d.ts.map +1 -1
  24. package/dist/core/worker.js +2 -0
  25. package/dist/core/worker.js.map +1 -1
  26. package/dist/linter/rules/enrichment-rules.d.ts +3 -2
  27. package/dist/linter/rules/enrichment-rules.d.ts.map +1 -1
  28. package/dist/linter/rules/enrichment-rules.js +9 -2
  29. package/dist/linter/rules/enrichment-rules.js.map +1 -1
  30. package/dist/linter/rules/handler-body-rules.d.ts.map +1 -1
  31. package/dist/linter/rules/handler-body-rules.js +10 -4
  32. package/dist/linter/rules/handler-body-rules.js.map +1 -1
  33. package/dist/linter/rules/schema-rules.d.ts +5 -0
  34. package/dist/linter/rules/schema-rules.d.ts.map +1 -1
  35. package/dist/linter/rules/schema-rules.js +44 -17
  36. package/dist/linter/rules/schema-rules.js.map +1 -1
  37. package/dist/linter/rules/tool-rules.d.ts +2 -1
  38. package/dist/linter/rules/tool-rules.d.ts.map +1 -1
  39. package/dist/linter/rules/tool-rules.js +36 -1
  40. package/dist/linter/rules/tool-rules.js.map +1 -1
  41. package/dist/mcp-server/inputRequired.d.ts +14 -5
  42. package/dist/mcp-server/inputRequired.d.ts.map +1 -1
  43. package/dist/mcp-server/inputRequired.js +15 -8
  44. package/dist/mcp-server/inputRequired.js.map +1 -1
  45. package/dist/mcp-server/outputContract.d.ts +33 -0
  46. package/dist/mcp-server/outputContract.d.ts.map +1 -0
  47. package/dist/mcp-server/outputContract.js +43 -0
  48. package/dist/mcp-server/outputContract.js.map +1 -0
  49. package/dist/mcp-server/resources/utils/resourceHandlerFactory.d.ts.map +1 -1
  50. package/dist/mcp-server/resources/utils/resourceHandlerFactory.js +10 -2
  51. package/dist/mcp-server/resources/utils/resourceHandlerFactory.js.map +1 -1
  52. package/dist/mcp-server/tools/utils/inputPrevalidation.d.ts +163 -40
  53. package/dist/mcp-server/tools/utils/inputPrevalidation.d.ts.map +1 -1
  54. package/dist/mcp-server/tools/utils/inputPrevalidation.js +330 -114
  55. package/dist/mcp-server/tools/utils/inputPrevalidation.js.map +1 -1
  56. package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts +39 -15
  57. package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts.map +1 -1
  58. package/dist/mcp-server/tools/utils/toolHandlerFactory.js +361 -93
  59. package/dist/mcp-server/tools/utils/toolHandlerFactory.js.map +1 -1
  60. package/dist/mcp-server/transports/auth/lib/authUtils.js +4 -1
  61. package/dist/mcp-server/transports/auth/lib/authUtils.js.map +1 -1
  62. package/dist/mcp-server/transports/auth/strategies/jwtStrategy.d.ts.map +1 -1
  63. package/dist/mcp-server/transports/auth/strategies/jwtStrategy.js +1 -1
  64. package/dist/mcp-server/transports/auth/strategies/jwtStrategy.js.map +1 -1
  65. package/dist/mcp-server/transports/auth/strategies/oauthStrategy.d.ts.map +1 -1
  66. package/dist/mcp-server/transports/auth/strategies/oauthStrategy.js +2 -5
  67. package/dist/mcp-server/transports/auth/strategies/oauthStrategy.js.map +1 -1
  68. package/dist/mcp-server/transports/http/httpTransport.d.ts.map +1 -1
  69. package/dist/mcp-server/transports/http/httpTransport.js +65 -9
  70. package/dist/mcp-server/transports/http/httpTransport.js.map +1 -1
  71. package/dist/mcp-server/transports/http/sessionStore.d.ts.map +1 -1
  72. package/dist/mcp-server/transports/http/sessionStore.js +2 -2
  73. package/dist/mcp-server/transports/http/sessionStore.js.map +1 -1
  74. package/dist/mcp-server/transports/stdio/stdioTransport.d.ts +9 -5
  75. package/dist/mcp-server/transports/stdio/stdioTransport.d.ts.map +1 -1
  76. package/dist/mcp-server/transports/stdio/stdioTransport.js +9 -5
  77. package/dist/mcp-server/transports/stdio/stdioTransport.js.map +1 -1
  78. package/dist/services/canvas/core/CanvasRegistry.d.ts +6 -2
  79. package/dist/services/canvas/core/CanvasRegistry.d.ts.map +1 -1
  80. package/dist/services/canvas/core/CanvasRegistry.js +8 -4
  81. package/dist/services/canvas/core/CanvasRegistry.js.map +1 -1
  82. package/dist/services/canvas/core/DataCanvas.d.ts.map +1 -1
  83. package/dist/services/canvas/core/DataCanvas.js +7 -5
  84. package/dist/services/canvas/core/DataCanvas.js.map +1 -1
  85. package/dist/services/canvas/core/canvasFactory.d.ts.map +1 -1
  86. package/dist/services/canvas/core/canvasFactory.js +2 -2
  87. package/dist/services/canvas/core/canvasFactory.js.map +1 -1
  88. package/dist/services/canvas/providers/duckdb/DuckdbProvider.d.ts +82 -18
  89. package/dist/services/canvas/providers/duckdb/DuckdbProvider.d.ts.map +1 -1
  90. package/dist/services/canvas/providers/duckdb/DuckdbProvider.js +645 -344
  91. package/dist/services/canvas/providers/duckdb/DuckdbProvider.js.map +1 -1
  92. package/dist/services/canvas/providers/duckdb/exportWriter.d.ts +11 -7
  93. package/dist/services/canvas/providers/duckdb/exportWriter.d.ts.map +1 -1
  94. package/dist/services/canvas/providers/duckdb/exportWriter.js +19 -16
  95. package/dist/services/canvas/providers/duckdb/exportWriter.js.map +1 -1
  96. package/dist/services/llm/providers/openrouter.provider.js +1 -1
  97. package/dist/services/llm/providers/openrouter.provider.js.map +1 -1
  98. package/dist/services/mirror/core/defineMirror.d.ts +1 -0
  99. package/dist/services/mirror/core/defineMirror.d.ts.map +1 -1
  100. package/dist/services/mirror/core/defineMirror.js +1 -0
  101. package/dist/services/mirror/core/defineMirror.js.map +1 -1
  102. package/dist/services/speech/providers/elevenlabs.provider.js +3 -3
  103. package/dist/services/speech/providers/elevenlabs.provider.js.map +1 -1
  104. package/dist/services/speech/providers/whisper.provider.d.ts.map +1 -1
  105. package/dist/services/speech/providers/whisper.provider.js +5 -5
  106. package/dist/services/speech/providers/whisper.provider.js.map +1 -1
  107. package/dist/storage/core/StorageService.d.ts.map +1 -1
  108. package/dist/storage/core/StorageService.js +3 -6
  109. package/dist/storage/core/StorageService.js.map +1 -1
  110. package/dist/storage/core/storageFactory.d.ts.map +1 -1
  111. package/dist/storage/core/storageFactory.js +12 -15
  112. package/dist/storage/core/storageFactory.js.map +1 -1
  113. package/dist/storage/core/storageValidation.d.ts +13 -13
  114. package/dist/storage/core/storageValidation.d.ts.map +1 -1
  115. package/dist/storage/core/storageValidation.js +49 -125
  116. package/dist/storage/core/storageValidation.js.map +1 -1
  117. package/dist/storage/providers/cloudflare/d1Provider.d.ts.map +1 -1
  118. package/dist/storage/providers/cloudflare/d1Provider.js +5 -3
  119. package/dist/storage/providers/cloudflare/d1Provider.js.map +1 -1
  120. package/dist/storage/providers/cloudflare/kvProvider.d.ts.map +1 -1
  121. package/dist/storage/providers/cloudflare/kvProvider.js +1 -1
  122. package/dist/storage/providers/cloudflare/kvProvider.js.map +1 -1
  123. package/dist/storage/providers/cloudflare/r2Provider.d.ts.map +1 -1
  124. package/dist/storage/providers/cloudflare/r2Provider.js +3 -3
  125. package/dist/storage/providers/cloudflare/r2Provider.js.map +1 -1
  126. package/dist/storage/providers/fileSystem/fileSystemProvider.js +4 -4
  127. package/dist/storage/providers/fileSystem/fileSystemProvider.js.map +1 -1
  128. package/dist/storage/providers/inMemory/inMemoryProvider.d.ts +1 -1
  129. package/dist/storage/providers/inMemory/inMemoryProvider.d.ts.map +1 -1
  130. package/dist/storage/providers/inMemory/inMemoryProvider.js +6 -5
  131. package/dist/storage/providers/inMemory/inMemoryProvider.js.map +1 -1
  132. package/dist/testing/fuzz.d.ts.map +1 -1
  133. package/dist/testing/fuzz.js +7 -1
  134. package/dist/testing/fuzz.js.map +1 -1
  135. package/dist/testing/index.d.ts +15 -2
  136. package/dist/testing/index.d.ts.map +1 -1
  137. package/dist/testing/index.js +51 -6
  138. package/dist/testing/index.js.map +1 -1
  139. package/dist/types-global/errors.d.ts +7 -4
  140. package/dist/types-global/errors.d.ts.map +1 -1
  141. package/dist/types-global/errors.js.map +1 -1
  142. package/dist/utils/formatting/codeSpan.d.ts +27 -0
  143. package/dist/utils/formatting/codeSpan.d.ts.map +1 -0
  144. package/dist/utils/formatting/codeSpan.js +42 -0
  145. package/dist/utils/formatting/codeSpan.js.map +1 -0
  146. package/dist/utils/formatting/diffFormatter.d.ts.map +1 -1
  147. package/dist/utils/formatting/diffFormatter.js +7 -15
  148. package/dist/utils/formatting/diffFormatter.js.map +1 -1
  149. package/dist/utils/formatting/markdownBuilder.d.ts +12 -5
  150. package/dist/utils/formatting/markdownBuilder.d.ts.map +1 -1
  151. package/dist/utils/formatting/markdownBuilder.js +14 -2
  152. package/dist/utils/formatting/markdownBuilder.js.map +1 -1
  153. package/dist/utils/formatting/tableFormatter.d.ts.map +1 -1
  154. package/dist/utils/formatting/tableFormatter.js +5 -9
  155. package/dist/utils/formatting/tableFormatter.js.map +1 -1
  156. package/dist/utils/formatting/treeFormatter.d.ts.map +1 -1
  157. package/dist/utils/formatting/treeFormatter.js +5 -9
  158. package/dist/utils/formatting/treeFormatter.js.map +1 -1
  159. package/dist/utils/index.d.ts +1 -1
  160. package/dist/utils/index.d.ts.map +1 -1
  161. package/dist/utils/index.js.map +1 -1
  162. package/dist/utils/internal/error-handler/errorHandler.d.ts +17 -10
  163. package/dist/utils/internal/error-handler/errorHandler.d.ts.map +1 -1
  164. package/dist/utils/internal/error-handler/errorHandler.js +47 -26
  165. package/dist/utils/internal/error-handler/errorHandler.js.map +1 -1
  166. package/dist/utils/internal/error-handler/mappings.d.ts +17 -1
  167. package/dist/utils/internal/error-handler/mappings.d.ts.map +1 -1
  168. package/dist/utils/internal/error-handler/mappings.js +22 -1
  169. package/dist/utils/internal/error-handler/mappings.js.map +1 -1
  170. package/dist/utils/internal/error-handler/types.d.ts +2 -0
  171. package/dist/utils/internal/error-handler/types.d.ts.map +1 -1
  172. package/dist/utils/internal/logger.d.ts +75 -3
  173. package/dist/utils/internal/logger.d.ts.map +1 -1
  174. package/dist/utils/internal/logger.js +181 -52
  175. package/dist/utils/internal/logger.js.map +1 -1
  176. package/dist/utils/internal/performance.d.ts +11 -0
  177. package/dist/utils/internal/performance.d.ts.map +1 -1
  178. package/dist/utils/internal/performance.js +46 -12
  179. package/dist/utils/internal/performance.js.map +1 -1
  180. package/dist/utils/network/fetchWithTimeout.d.ts +11 -5
  181. package/dist/utils/network/fetchWithTimeout.d.ts.map +1 -1
  182. package/dist/utils/network/fetchWithTimeout.js +50 -23
  183. package/dist/utils/network/fetchWithTimeout.js.map +1 -1
  184. package/dist/utils/network/pacer.d.ts +38 -5
  185. package/dist/utils/network/pacer.d.ts.map +1 -1
  186. package/dist/utils/network/pacer.js +87 -25
  187. package/dist/utils/network/pacer.js.map +1 -1
  188. package/dist/utils/network/retry.d.ts +16 -8
  189. package/dist/utils/network/retry.d.ts.map +1 -1
  190. package/dist/utils/network/retry.js +19 -8
  191. package/dist/utils/network/retry.js.map +1 -1
  192. package/dist/utils/overflow/outlineOnOverflow.d.ts +18 -2
  193. package/dist/utils/overflow/outlineOnOverflow.d.ts.map +1 -1
  194. package/dist/utils/overflow/outlineOnOverflow.js +28 -3
  195. package/dist/utils/overflow/outlineOnOverflow.js.map +1 -1
  196. package/dist/utils/pagination/pagination.d.ts +3 -1
  197. package/dist/utils/pagination/pagination.d.ts.map +1 -1
  198. package/dist/utils/pagination/pagination.js +10 -2
  199. package/dist/utils/pagination/pagination.js.map +1 -1
  200. package/dist/utils/parsing/csvParser.d.ts.map +1 -1
  201. package/dist/utils/parsing/csvParser.js +4 -2
  202. package/dist/utils/parsing/csvParser.js.map +1 -1
  203. package/dist/utils/parsing/htmlExtractor.js +1 -1
  204. package/dist/utils/parsing/htmlExtractor.js.map +1 -1
  205. package/dist/utils/parsing/jsonParser.d.ts.map +1 -1
  206. package/dist/utils/parsing/jsonParser.js +3 -1
  207. package/dist/utils/parsing/jsonParser.js.map +1 -1
  208. package/dist/utils/parsing/xmlParser.d.ts.map +1 -1
  209. package/dist/utils/parsing/xmlParser.js +3 -1
  210. package/dist/utils/parsing/xmlParser.js.map +1 -1
  211. package/dist/utils/parsing/yamlParser.d.ts.map +1 -1
  212. package/dist/utils/parsing/yamlParser.js +3 -1
  213. package/dist/utils/parsing/yamlParser.js.map +1 -1
  214. package/dist/utils/security/idGenerator.d.ts.map +1 -1
  215. package/dist/utils/security/idGenerator.js +20 -4
  216. package/dist/utils/security/idGenerator.js.map +1 -1
  217. package/dist/utils/security/sanitization.d.ts +31 -0
  218. package/dist/utils/security/sanitization.d.ts.map +1 -1
  219. package/dist/utils/security/sanitization.js +98 -11
  220. package/dist/utils/security/sanitization.js.map +1 -1
  221. package/dist/utils/telemetry/attributes.d.ts +21 -2
  222. package/dist/utils/telemetry/attributes.d.ts.map +1 -1
  223. package/dist/utils/telemetry/attributes.js +21 -2
  224. package/dist/utils/telemetry/attributes.js.map +1 -1
  225. package/dist/utils/telemetry/instrumentation.d.ts +9 -3
  226. package/dist/utils/telemetry/instrumentation.d.ts.map +1 -1
  227. package/dist/utils/telemetry/instrumentation.js +85 -13
  228. package/dist/utils/telemetry/instrumentation.js.map +1 -1
  229. package/framework-skills/add-app-tool/SKILL.md +3 -3
  230. package/framework-skills/add-export/SKILL.md +5 -16
  231. package/framework-skills/add-prompt/SKILL.md +7 -3
  232. package/framework-skills/add-resource/SKILL.md +7 -5
  233. package/framework-skills/add-tool/SKILL.md +12 -10
  234. package/framework-skills/api-auth/SKILL.md +4 -2
  235. package/framework-skills/api-canvas/SKILL.md +19 -10
  236. package/framework-skills/api-config/SKILL.md +9 -6
  237. package/framework-skills/api-context/SKILL.md +16 -5
  238. package/framework-skills/api-errors/SKILL.md +23 -17
  239. package/framework-skills/api-linter/SKILL.md +32 -9
  240. package/framework-skills/api-mirror/SKILL.md +2 -1
  241. package/framework-skills/api-telemetry/SKILL.md +34 -14
  242. package/framework-skills/api-testing/SKILL.md +5 -3
  243. package/framework-skills/api-utils/SKILL.md +10 -10
  244. package/framework-skills/api-utils/references/formatting.md +1 -1
  245. package/framework-skills/api-utils/references/parsing.md +2 -2
  246. package/framework-skills/api-utils/references/security.md +6 -4
  247. package/framework-skills/design-mcp-server/SKILL.md +2 -2
  248. package/framework-skills/field-test/SKILL.md +4 -4
  249. package/framework-skills/git-wrapup/SKILL.md +12 -7
  250. package/framework-skills/maintenance/SKILL.md +2 -2
  251. package/framework-skills/orchestrations/SKILL.md +7 -6
  252. package/framework-skills/orchestrations/workflows/field-test-fix.md +9 -19
  253. package/framework-skills/orchestrations/workflows/fix-wrapup-release.md +7 -7
  254. package/framework-skills/orchestrations/workflows/greenfield-build.md +8 -5
  255. package/framework-skills/orchestrations/workflows/maintenance-release.md +8 -8
  256. package/framework-skills/polish-docs-meta/SKILL.md +4 -4
  257. package/framework-skills/polish-docs-meta/references/readme.md +1 -0
  258. package/framework-skills/release-and-publish/SKILL.md +7 -5
  259. package/framework-skills/release-pr-review/SKILL.md +37 -23
  260. package/framework-skills/report-issue-framework/SKILL.md +7 -5
  261. package/framework-skills/report-issue-local/SKILL.md +8 -6
  262. package/framework-skills/security-pass/SKILL.md +8 -8
  263. package/framework-skills/techniques/SKILL.md +1 -1
  264. package/framework-skills/techniques/references/outline-on-overflow.md +12 -7
  265. package/package.json +20 -5
  266. package/scripts/check-skill-versions.ts +103 -22
  267. package/scripts/devcheck.ts +11 -9
  268. package/scripts/lint-mcp.ts +87 -27
  269. package/scripts/lint-packaging.ts +99 -1
  270. package/scripts/release-github.ts +117 -5
  271. package/templates/.env.example +4 -0
  272. package/templates/Dockerfile +26 -6
  273. package/templates/_.mcpbignore +2 -0
  274. package/templates/package.json +1 -0
@@ -1,8 +1,9 @@
1
1
  /**
2
2
  * @fileoverview Outbound request pacer — a FIFO queue in front of a rate-limited
3
3
  * upstream. Holds work back until every configured window, the minimum start gap,
4
- * and the concurrency cap allow it; sheds callers whose wait budget cannot be met;
5
- * and closes a shared cooldown gate when the upstream answers 429.
4
+ * and the concurrency cap allow it; sheds callers the queue cannot hold or whose
5
+ * wait budget cannot be met; and closes a shared cooldown gate when the upstream
6
+ * answers 429.
6
7
  *
7
8
  * The inbound `RateLimiter` (`utils/security`) is the mirror image: it is keyed
8
9
  * per caller and rejects synchronously, so it cannot queue work against an
@@ -13,6 +14,15 @@ import { JsonRpcErrorCode, McpError, rateLimited, requestCancelled, } from '../.
13
14
  import { parseRetryAfterMs } from './retry.js';
14
15
  import { ATTR_MCP_PACER_NAME } from '../telemetry/attributes.js';
15
16
  import { createCounter, createHistogram, createUpDownCounter } from '../telemetry/metrics.js';
17
+ /**
18
+ * The caller-facing message for each shed kind. A `queue_full` shed names the
19
+ * full queue, not a wait budget the caller may never have set.
20
+ */
21
+ const shedMessages = {
22
+ queue_full: (name) => `No ${name} request slot is open and the wait queue is full.`,
23
+ wait_elapsed: (name) => `The caller's wait budget ran out before a ${name} request slot opened.`,
24
+ wait_projected: (name) => `No ${name} request slot available within the caller's wait budget.`,
25
+ };
16
26
  let instruments;
17
27
  /**
18
28
  * The four pacer instruments, shared across every pacer in the process and told
@@ -22,7 +32,7 @@ function getPacerMetrics() {
22
32
  instruments ??= {
23
33
  cooldowns: createCounter('mcp.pacer.cooldowns', 'Cooldown gates closed by an upstream rate limit', '{cooldowns}'),
24
34
  queueDepth: createUpDownCounter('mcp.pacer.queue_depth', 'Requests waiting for a pacer slot', '{requests}'),
25
- sheds: createCounter('mcp.pacer.sheds', 'Requests shed before dispatch because no slot fit the wait budget', '{requests}'),
35
+ sheds: createCounter('mcp.pacer.sheds', 'Requests shed before dispatch: the wait queue was full, or no slot fit the wait budget', '{requests}'),
26
36
  wait: createHistogram('mcp.pacer.wait', 'Time a request spent waiting for a pacer slot', 'ms'),
27
37
  };
28
38
  return instruments;
@@ -122,21 +132,49 @@ export function createPacer(options) {
122
132
  }
123
133
  return at;
124
134
  }
125
- /** Seconds until a slot opens, for the shed error's `retryAfter`. */
126
- function secondsUntilSlot(now, ahead) {
127
- return Math.ceil(Math.max(0, projectedStart(now, ahead) - now) / 1000);
135
+ function atCapacity() {
136
+ return maxConcurrent !== undefined && active >= maxConcurrent;
137
+ }
138
+ /** Whether an arrival at `now` would start at once rather than wait. */
139
+ function canStartNow(now) {
140
+ return queue.length === 0 && !atCapacity() && earliestStart(starts, now) <= now;
141
+ }
142
+ /**
143
+ * Rate limits in the current streak, as the next one doubles from them. The
144
+ * streak lapses once the gate has stood open for `cooldown.maxMs` — one full
145
+ * capped cooldown with no rate limit — and is keyed to the gate rather than
146
+ * to the last rate limit, so continuous demand under a sustained limit, every
147
+ * attempt landing as the gate reopens, keeps its capped backoff.
148
+ */
149
+ function streak(now) {
150
+ return cooldown && now - gateOpensAt < cooldown.maxMs ? consecutiveRateLimits : 0;
128
151
  }
129
152
  /**
130
- * The shed error. `rateLimited` with no `retryable: false`: to the calling
131
- * agent this is an ordinary rate limit — wait `retryAfter`, call again — and
132
- * that flag would tell them the opposite. `withRetry`'s default predicate
133
- * reads `reason` instead, so an enclosing retry fails fast rather than
134
- * sleeping past the deadline the shed exists to enforce.
153
+ * The shed error, for a caller that enqueued at `enqueuedAt` — `now` when shed
154
+ * on arrival — and has already left the queue. `retryAfter` projects a caller
155
+ * joining behind every remaining waiter. That projection cannot see a
156
+ * concurrency slot freeing, so while `maxConcurrent` is saturated it is floored
157
+ * at the longest wait of any queued caller, the shed one included, and never
158
+ * below 1s: the slots have been held at least that long.
159
+ *
160
+ * `rateLimited` with no `retryable: false`: to the calling agent this is an
161
+ * ordinary rate limit — wait `retryAfter`, call again — and that flag would
162
+ * tell them the opposite. `withRetry`'s default predicate reads `reason`
163
+ * instead, so an enclosing retry fails fast rather than sleeping past the
164
+ * deadline the shed exists to enforce.
135
165
  */
136
- function shed(retryAfter, queueDepth) {
166
+ function shed(shedKind, enqueuedAt) {
137
167
  getPacerMetrics().sheds.add(1, attributes);
138
- return rateLimited(`No ${name} request slot available within the caller's wait budget.`, {
168
+ const now = Date.now();
169
+ const queueDepth = queue.length;
170
+ let retryAfter = Math.ceil(Math.max(0, projectedStart(now, queueDepth) - now) / 1000);
171
+ if (atCapacity()) {
172
+ const oldest = Math.min(enqueuedAt, queue[0]?.enqueuedAt ?? enqueuedAt);
173
+ retryAfter = Math.max(retryAfter, Math.ceil((now - oldest) / 1000), 1);
174
+ }
175
+ return rateLimited(shedMessages[shedKind](name), {
139
176
  reason: 'pacer_shed',
177
+ shedKind,
140
178
  retryAfter,
141
179
  queueDepth,
142
180
  });
@@ -181,7 +219,7 @@ export function createPacer(options) {
181
219
  function pump() {
182
220
  clearDispatchTimer();
183
221
  while (queue.length > 0) {
184
- if (maxConcurrent !== undefined && active >= maxConcurrent)
222
+ if (atCapacity())
185
223
  return;
186
224
  const now = Date.now();
187
225
  const earliest = earliestStart(starts, now);
@@ -206,19 +244,30 @@ export function createPacer(options) {
206
244
  /**
207
245
  * Closes the shared gate on an upstream rate limit:
208
246
  * `min(max(baseMs · 2^(consecutive−1), retryAfter), maxMs)`, as an absolute
209
- * instant. Any other error leaves it open; the first success resets the count.
247
+ * instant. Any other error leaves it open and the count untouched; the first
248
+ * success resets the count, and so does a gate left open for `maxMs`.
249
+ *
250
+ * A shed (`data.reason: 'pacer_shed'`) is excluded: raised by a pacer nested
251
+ * inside this task, it is local backpressure, and no upstream answered.
210
252
  */
211
253
  function noteRateLimit(error) {
212
254
  if (!cooldown)
213
255
  return;
214
256
  if (!(error instanceof McpError) || error.code !== JsonRpcErrorCode.RateLimited)
215
257
  return;
216
- consecutiveRateLimits++;
217
- const doubled = cooldown.baseMs * 2 ** (consecutiveRateLimits - 1);
258
+ if (error.data?.reason === 'pacer_shed')
259
+ return;
260
+ const now = Date.now();
261
+ consecutiveRateLimits = streak(now) + 1;
262
+ // The exponent is bounded so the product stays finite: past 2^1024 it is
263
+ // Infinity, and `baseMs: 0` would make it `0 · Infinity` — NaN, which sticks
264
+ // in `gateOpensAt` and stops every window and gap from binding. A positive
265
+ // `baseMs · 2^52` still exceeds any practical `maxMs`, so it clamps as before.
266
+ const doubled = cooldown.baseMs * 2 ** Math.min(consecutiveRateLimits - 1, 52);
218
267
  // An absent or unparseable hint contributes nothing, leaving the doubling.
219
268
  const honored = parseRetryAfterMs(error) ?? 0;
220
269
  const waitMs = Math.min(Math.max(doubled, honored), cooldown.maxMs);
221
- gateOpensAt = Math.max(gateOpensAt, Date.now() + waitMs);
270
+ gateOpensAt = Math.max(gateOpensAt, now + waitMs);
222
271
  getPacerMetrics().cooldowns.add(1, attributes);
223
272
  }
224
273
  function run(task, runOptions = {}) {
@@ -228,14 +277,19 @@ export function createPacer(options) {
228
277
  }
229
278
  if (signal?.aborted)
230
279
  return Promise.reject(signal.reason);
280
+ // Start whoever is already due before judging this arrival: a dispatch
281
+ // timer running late (event-loop lag) leaves a waiter whose slot is open
282
+ // counted against `maxQueueDepth`, and would shed this call with a
283
+ // `retryAfter` of 0.
284
+ pump();
231
285
  const now = Date.now();
232
- const ahead = queue.length;
233
- // Absolute backpressure first, so it rejects without arming a timer.
234
- if (maxQueueDepth !== undefined && ahead >= maxQueueDepth) {
235
- return Promise.reject(shed(secondsUntilSlot(now, ahead), ahead));
286
+ // Absolute backpressure first, so it rejects without arming a timer. It
287
+ // bounds waiters, so an arrival that can start this instant never counts.
288
+ if (maxQueueDepth !== undefined && queue.length >= maxQueueDepth && !canStartNow(now)) {
289
+ return Promise.reject(shed('queue_full', now));
236
290
  }
237
- if (maxWaitMs !== undefined && projectedStart(now, ahead) - now > maxWaitMs) {
238
- return Promise.reject(shed(secondsUntilSlot(now, ahead), ahead));
291
+ if (maxWaitMs !== undefined && projectedStart(now, queue.length) - now > maxWaitMs) {
292
+ return Promise.reject(shed('wait_projected', now));
239
293
  }
240
294
  return new Promise((resolve, reject) => {
241
295
  const entry = {
@@ -263,9 +317,13 @@ export function createPacer(options) {
263
317
  if (maxWaitMs !== undefined) {
264
318
  entry.shedTimer = setTimeout(() => {
265
319
  entry.shedTimer = undefined;
320
+ // This can fire ahead of a dispatch timer due the same instant, so
321
+ // drain what is due first: a slot opening as the budget ends
322
+ // dispatches the entry rather than shedding it.
323
+ pump();
266
324
  if (!remove(entry))
267
325
  return;
268
- reject(shed(secondsUntilSlot(Date.now(), 0), queue.length));
326
+ reject(shed('wait_elapsed', entry.enqueuedAt));
269
327
  // The shed entry is gone; whoever is behind it should not wait on it.
270
328
  pump();
271
329
  }, maxWaitMs);
@@ -296,6 +354,10 @@ export function createPacer(options) {
296
354
  }
297
355
  }
298
356
  return {
357
+ get cooldown() {
358
+ const now = Date.now();
359
+ return { remainingMs: Math.max(0, gateOpensAt - now), consecutive: streak(now) };
360
+ },
299
361
  dispose,
300
362
  run,
301
363
  [Symbol.dispose]: dispose,
@@ -1 +1 @@
1
- {"version":3,"file":"pacer.js","sourceRoot":"","sources":["../../../src/utils/network/pacer.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"pacer.js","sourceRoot":"","sources":["../../../src/utils/network/pacer.ts"],"names":[],"mappings":"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"}
@@ -95,10 +95,15 @@ export interface RetryOptions {
95
95
  operation?: string;
96
96
  /**
97
97
  * Optional AbortSignal. When aborted, the retry loop exits immediately
98
- * without further attempts, rethrowing unchanged — this is the caller-abort
99
- * passthrough and it outranks a {@link deadlineMs} expiry, so a cancelled
100
- * request is never relabelled as one that ran out of budget. Also composed
101
- * into {@link RetryAttempt.signal}.
98
+ * without further attempts. An abort that lands during an attempt rethrows
99
+ * that attempt's error unchanged; one that lands during a backoff wait
100
+ * rejects with `signal.reason` itself — the caller's string, `Error`, or the
101
+ * `AbortError` `DOMException` a reason-less `abort()` leaves — not an
102
+ * `McpError`. This caller-abort passthrough outranks a {@link deadlineMs}
103
+ * expiry, so a cancelled request is never relabelled as one that ran out of
104
+ * budget. Inside a tool or resource handler whose request signal is the one
105
+ * that fired, the handler factory reports either shape as `RequestCancelled`
106
+ * (-32011). Also composed into {@link RetryAttempt.signal}.
102
107
  */
103
108
  signal?: AbortSignal;
104
109
  }
@@ -135,6 +140,10 @@ export declare function parseRetryAfterMs(error: unknown): number | undefined;
135
140
  * classification applies. Non-`McpError` throws (raw network errors, unexpected
136
141
  * throws) are always assumed transient regardless of the flag.
137
142
  *
143
+ * Two framework shapes are also never retried: a pacer shed
144
+ * (`data.reason: 'pacer_shed'`) and a caller-side deadline from
145
+ * `fetchWithTimeout` (`data.errorSource: 'FetchSignalTimeout'`).
146
+ *
138
147
  * **Composing rather than replacing.** {@link RetryOptions.isTransient} replaces
139
148
  * this predicate outright, so a caller that wants "the framework default, except
140
149
  * this one error" composes off this export instead of mirroring the transient
@@ -181,10 +190,9 @@ export declare function defaultIsTransient(error: unknown): boolean;
181
190
  * by one in-flight request. A backoff that would consume the remaining budget
182
191
  * fails fast rather than sleeping into a certain timeout, and expiry rejects with
183
192
  * a single `Timeout` error carrying `data.reason: 'retry_deadline_exceeded'` —
184
- * the `RequestCancelled` that an external-signal abort produces inside
185
- * `fetchWithTimeout` normalizes to it. A caller abort on `options.signal` keeps
186
- * precedence and is never relabelled. Without `deadlineMs`, behavior is
187
- * unchanged.
193
+ * the per-attempt `Timeout` the clock's abort produces inside `fetchWithTimeout`
194
+ * normalizes to it. A caller abort on `options.signal` keeps precedence and is
195
+ * never relabelled. Without `deadlineMs`, behavior is unchanged.
188
196
  *
189
197
  * When retries exhaust, the final error is enriched with attempt count in both
190
198
  * the message and structured data, so callers know retries were already attempted.
@@ -1 +1 @@
1
- {"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAYzE;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAuBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAoBpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAgB1D;AA2FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,EACzC,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAuHZ"}
1
+ {"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAYzE;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAuBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAoBpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAuB1D;AA2FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,EACzC,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAuHZ"}
@@ -85,6 +85,10 @@ export function parseRetryAfterMs(error) {
85
85
  * classification applies. Non-`McpError` throws (raw network errors, unexpected
86
86
  * throws) are always assumed transient regardless of the flag.
87
87
  *
88
+ * Two framework shapes are also never retried: a pacer shed
89
+ * (`data.reason: 'pacer_shed'`) and a caller-side deadline from
90
+ * `fetchWithTimeout` (`data.errorSource: 'FetchSignalTimeout'`).
91
+ *
88
92
  * **Composing rather than replacing.** {@link RetryOptions.isTransient} replaces
89
93
  * this predicate outright, so a caller that wants "the framework default, except
90
94
  * this one error" composes off this export instead of mirroring the transient
@@ -115,6 +119,14 @@ export function defaultIsTransient(error) {
115
119
  */
116
120
  if (error.data?.reason === 'pacer_shed')
117
121
  return false;
122
+ /**
123
+ * A caller-side deadline — `fetchWithTimeout`'s external signal aborting
124
+ * with a `TimeoutError` — has already fired, and every retry would reuse
125
+ * that aborted signal: the loop could only sleep past the deadline the
126
+ * caller set. It stays `Timeout` on the wire, where a later call can succeed.
127
+ */
128
+ if (error.data?.errorSource === 'FetchSignalTimeout')
129
+ return false;
118
130
  return TRANSIENT_CODES.has(error.code);
119
131
  }
120
132
  // Non-McpError (raw network errors, unexpected throws) — assume transient
@@ -131,9 +143,9 @@ export function defaultIsTransient(error) {
131
143
  *
132
144
  * `withRetry` cannot tell the three clocks apart from a caught error alone — a
133
145
  * deadline abort reaching `fetchWithTimeout` on its external signal arrives as
134
- * `RequestCancelled`, and one landing mid-backoff arrives as the raw abort
135
- * reason — so both normalize through {@link DeadlineClock.exceeded} and the
136
- * caller matches one shape.
146
+ * a per-attempt `Timeout` (`errorSource: 'FetchSignalTimeout'`), and one
147
+ * landing mid-backoff arrives as the raw abort reason — so both normalize
148
+ * through {@link DeadlineClock.exceeded} and the caller matches one shape.
137
149
  *
138
150
  * The expiry carries no `retryable` flag: a narrower call can still succeed, and
139
151
  * that flag is {@link defaultIsTransient}'s in-band opt-out rather than a
@@ -211,10 +223,9 @@ function enrichExhaustedError(error, totalAttempts, operation) {
211
223
  * by one in-flight request. A backoff that would consume the remaining budget
212
224
  * fails fast rather than sleeping into a certain timeout, and expiry rejects with
213
225
  * a single `Timeout` error carrying `data.reason: 'retry_deadline_exceeded'` —
214
- * the `RequestCancelled` that an external-signal abort produces inside
215
- * `fetchWithTimeout` normalizes to it. A caller abort on `options.signal` keeps
216
- * precedence and is never relabelled. Without `deadlineMs`, behavior is
217
- * unchanged.
226
+ * the per-attempt `Timeout` the clock's abort produces inside `fetchWithTimeout`
227
+ * normalizes to it. A caller abort on `options.signal` keeps precedence and is
228
+ * never relabelled. Without `deadlineMs`, behavior is unchanged.
218
229
  *
219
230
  * When retries exhaust, the final error is enriched with attempt count in both
220
231
  * the message and structured data, so callers know retries were already attempted.
@@ -274,7 +285,7 @@ export async function withRetry(fn, options = {}) {
274
285
  throw error;
275
286
  }
276
287
  // The deadline fired inside the attempt. Whatever shape it took on the
277
- // way back (RequestCancelled from an external-signal abort, a raw abort
288
+ // way back (a per-attempt Timeout from `fetchWithTimeout`, a raw abort
278
289
  // reason), the caller sees one error.
279
290
  if (clock?.expired()) {
280
291
  throw clock.exceeded(error, attempt + 1);
@@ -1 +1 @@
1
- {"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGpD;;;GAGG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAmB;IAChD,gBAAgB,CAAC,kBAAkB;IACnC,gBAAgB,CAAC,OAAO;IACxB,gBAAgB,CAAC,WAAW;CAC7B,CAAC,CAAC;AAkHH;;;;;;;;GAQG;AACH,SAAS,YAAY,CACnB,OAAe,EACf,WAAmB,EACnB,UAAkB,EAClB,MAAc;IAEd,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,IAAI,OAAO,EAAE,UAAU,CAAC,CAAC;IACrE,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,WAAW,CAAC;IACpC,MAAM,WAAW,GAAG,WAAW,GAAG,MAAM,CAAC;IACzC,OAAO,WAAW,GAAG,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,GAAG,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAAE,OAAO;IACzC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC;IAEnC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO;IAEpC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO;IAE3B,6EAA6E;IAC7E,wDAAwD;IACxD,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAEzD,6DAA6D;IAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO;IACjC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,wDAAwD;QACxD,IAAI,KAAK,CAAC,IAAI,EAAE,SAAS,KAAK,KAAK;YAAE,OAAO,KAAK,CAAC;QAClD;;;;;;WAMG;QACH,IAAI,KAAK,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY;YAAE,OAAO,KAAK,CAAC;QACtD,OAAO,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IACD,0EAA0E;IAC1E,OAAO,IAAI,CAAC;AACd,CAAC;AAgBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,mBAAmB,CAAC,UAAkB,EAAE,SAAkB;IACjE,MAAM,KAAK,GAAG,SAAS,IAAI,WAAW,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,YAAY,CAC7B,GAAG,KAAK,iBAAiB,UAAU,oBAAoB,EACvD,cAAc,CACf,CAAC;IACF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC;IAErE,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,KAAK,MAAM;QAClD,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;QACrE,IAAI,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC;QAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,CACjC,OAAO,CACL,GAAG,KAAK,iBAAiB,UAAU,2BAA2B,aAAa,WAAW,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EACrH;YACE,MAAM,EAAE,yBAAyB;YACjC,UAAU;YACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YACjC,aAAa;SACd,EACD,EAAE,KAAK,EAAE,CACV;KACJ,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAAC,KAAc,EAAE,aAAqB,EAAE,SAAkB;IACrF,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,iBAAiB,aAAa,WAAW,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;QACxF,MAAM,eAAe,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;QAC9E,MAAM,YAAY,GAA4B;YAC5C,GAAG,KAAK,CAAC,IAAI;YACb,aAAa,EAAE,aAAa;YAC5B,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpC,CAAC;QACF,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,eAAe,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,iBAAiB,aAAa,WAAW,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;QACxF,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,GAAG,KAAK,CAAC,OAAO,IAAI,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1E,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QAC1B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAyC,EACzC,OAAO,GAAiB,EAAE;IAE1B,MAAM,EACJ,UAAU,GAAG,CAAC,EACd,WAAW,GAAG,IAAI,EAClB,UAAU,GAAG,MAAM,EACnB,MAAM,GAAG,IAAI,EACb,SAAS,EACT,OAAO,EACP,MAAM,EACN,UAAU,EACV,WAAW,GAAG,kBAAkB,GACjC,GAAG,OAAO,CAAC;IAEZ,MAAM,aAAa,GAAG,UAAU,GAAG,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAEhG,MAAM,aAAa,GACjB,KAAK,IAAI,MAAM;QACb,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,IAAI,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC,MAAM,CAAC,CAAC;IAEhE,IAAI,CAAC;QACH,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE,OAAO,EAAE,EAAE,CAAC;YACzD,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,CAAC;oBACd,MAAM,EAAE,aAAa;oBACrB,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,MAAM,CAAC,iBAAiB;iBAC9D,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAc,EAAE,CAAC;gBACxB,iEAAiE;gBACjE,oEAAoE;gBACpE,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;oBACpB,MAAM,KAAK,CAAC;gBACd,CAAC;gBAED,uEAAuE;gBACvE,wEAAwE;gBACxE,sCAAsC;gBACtC,IAAI,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC;oBACrB,MAAM,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;gBAC3C,CAAC;gBAED,MAAM,aAAa,GAAG,OAAO,IAAI,UAAU,CAAC;gBAE5C,wCAAwC;gBACxC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;oBACxB,MAAM,KAAK,CAAC;gBACd,CAAC;gBAED,qEAAqE;gBACrE,MAAM,YAAY,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;gBAE9C,6EAA6E;gBAC7E,0EAA0E;gBAC1E,2BAA2B;gBAC3B,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,GAAG,UAAU,EAAE,CAAC;oBAC5D,MAAM,CAAC,KAAK,CACV,eAAe,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,yBAAyB,UAAU,UAAU,SAAS,IAAI,WAAW,iBAAiB,EAC7H,OAAO,CACR,CAAC;oBACF,MAAM,KAAK,CAAC;gBACd,CAAC;gBAED,IAAI,aAAa,EAAE,CAAC;oBAClB,MAAM,oBAAoB,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;gBAC9D,CAAC;gBAED,6EAA6E;gBAC7E,MAAM,KAAK,GAAG,YAAY,IAAI,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;gBAErF;;;;;;;;;;;;mBAYG;gBACH,IAAI,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;oBACzC,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;wBAC/B,MAAM,CAAC,KAAK,CACV,eAAe,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,mBAAmB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,kBAAkB,UAAU,mBAAmB,SAAS,IAAI,WAAW,iBAAiB,EACjL,OAAO,CACR,CAAC;wBACF,MAAM,KAAK,CAAC;oBACd,CAAC;oBACD,MAAM,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;gBAC3C,CAAC;gBAED,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC5E,MAAM,WAAW,GAAG,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC;gBAEvE,MAAM,CAAC,KAAK,CACV,SAAS,OAAO,GAAG,CAAC,IAAI,UAAU,QAAQ,SAAS,IAAI,WAAW,KAAK,YAAY,cAAc,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,WAAW,EAAE,EACpI,OAAO,CACR,CAAC;gBAEF,IAAI,CAAC;oBACH,MAAM,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;gBACpC,CAAC;gBAAC,OAAO,UAAmB,EAAE,CAAC;oBAC7B,uEAAuE;oBACvE,oDAAoD;oBACpD,IAAI,MAAM,EAAE,OAAO;wBAAE,MAAM,UAAU,CAAC;oBACtC,IAAI,KAAK,EAAE,OAAO,EAAE;wBAAE,MAAM,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;oBAC/D,MAAM,UAAU,CAAC;gBACnB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,KAAK,EAAE,IAAI,EAAE,CAAC;IAChB,CAAC;IAED,kDAAkD;IAClD,MAAM,IAAI,QAAQ,CAAC,gBAAgB,CAAC,aAAa,EAAE,iCAAiC,CAAC,CAAC;AACxF,CAAC;AAED,yEAAyE;AACzE,SAAS,KAAK,CAAC,EAAU,EAAE,MAAoB;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,sFAAsF;QACtF,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;QAE3F,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,UAAU,CAAC,KAAK,EAAE,CAAC;YACnB,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QAEP,QAAQ,CAAC,gBAAgB,CACvB,OAAO,EACP,GAAG,EAAE;YACH,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,sEAAsE;YACtE,0EAA0E;YAC1E,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBACpB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACxB,CAAC;QACH,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}
1
+ {"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"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"}
@@ -32,12 +32,19 @@ export interface SectionMeta {
32
32
  *
33
33
  * ```ts
34
34
  * output: z.object({
35
- * kind: z.enum(['full', 'outline']),
35
+ * kind: z.enum(['full', 'outline']).describe('Whether the full record or a section outline was returned'),
36
36
  * // full-mode arms (present when kind === 'full') — each .optional()
37
- * sections: OUTLINE_VARIANT.shape.sections.optional(), // outline-mode arms
37
+ * sections: z // outline-mode arms
38
+ * .array(OUTLINE_VARIANT.shape.sections.element.describe('One section of the record'))
39
+ * .optional()
40
+ * .describe('Available sections, largest first'),
38
41
  * notice: OUTLINE_VARIANT.shape.notice.optional(),
39
42
  * }),
40
43
  * ```
44
+ *
45
+ * The section item is described in place because `describe-on-fields` asks every
46
+ * array-of-object element for a description and this schema's item carries none.
47
+ * `notice` beside a `sections` array is exempt from `enrichment-prefer-block`.
41
48
  */
42
49
  export declare const OUTLINE_VARIANT: z.ZodObject<{
43
50
  kind: z.ZodLiteral<"outline">;
@@ -107,9 +114,18 @@ export declare function outlineOnOverflow<T extends Record<string, unknown>>(doc
107
114
  * for. Pure top-level key projection; supply a custom selector when "section"
108
115
  * means something other than a top-level key.
109
116
  *
117
+ * A requested name that is not a key of `doc` is rejected rather than dropped:
118
+ * it is a stale or mistyped name, and a projection missing it would read as a
119
+ * successful narrow slice. The rejection travels through the tool's existing
120
+ * error path, so no output field has to be declared to carry it. `alwaysKeep`
121
+ * names are the author's, not the caller's, and an absent one is ignored.
122
+ *
110
123
  * @param doc - The full document.
111
124
  * @param want - Section identifiers the agent requested (from the outline).
112
125
  * @param options.alwaysKeep - Metadata keys to retain regardless (ids, timestamps).
126
+ * @throws {McpError} `InvalidParams` when any name in `want` is not a key of
127
+ * `doc`. The message names the unmatched and available keys; `data` carries
128
+ * both as `unmatched` and `available`.
113
129
  */
114
130
  export declare function selectSections<T extends Record<string, unknown>>(doc: T, want: string[], options?: {
115
131
  alwaysKeep?: string[];
@@ -1 +1 @@
1
- {"version":3,"file":"outlineOnOverflow.d.ts","sourceRoot":"","sources":["../../../src/utils/overflow/outlineOnOverflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qFAAqF;AACrF,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe;;;;;;;iBAW1B,CAAC;AAEH,wEAAwE;AACxE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE7D,mFAAmF;AACnF,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,cAAc,CAAC;AAEvE,6CAA6C;AAC7C,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,WAAW,EAAE,CAAC;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;CAC9D;AAsCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,GAAG,EAAE,CAAC,EACN,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,aAAa,CAAC,CAAC,CAAC,CAgBlB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAClC,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,EAAE,CASrE"}
1
+ {"version":3,"file":"outlineOnOverflow.d.ts","sourceRoot":"","sources":["../../../src/utils/overflow/outlineOnOverflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,qFAAqF;AACrF,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,eAAe;;;;;;;iBAW1B,CAAC;AAEH,wEAAwE;AACxE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE7D,mFAAmF;AACnF,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,cAAc,CAAC;AAEvE,6CAA6C;AAC7C,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,WAAW,EAAE,CAAC;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;CAC9D;AAsCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,GAAG,EAAE,CAAC,EACN,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,aAAa,CAAC,CAAC,CAAC,CAgBlB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAClC,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,EAAE,CASrE"}
@@ -1,4 +1,6 @@
1
1
  import { z } from 'zod';
2
+ import { invalidParams } from '../../types-global/errors.js';
3
+ import { codeSpan } from '../formatting/codeSpan.js';
2
4
  /** Default serialized-byte budget. Over this, a document overflows to an outline. */
3
5
  export const DEFAULT_OUTLINE_BUDGET_BYTES = 24_000;
4
6
  /**
@@ -10,12 +12,19 @@ export const DEFAULT_OUTLINE_BUDGET_BYTES = 24_000;
10
12
  *
11
13
  * ```ts
12
14
  * output: z.object({
13
- * kind: z.enum(['full', 'outline']),
15
+ * kind: z.enum(['full', 'outline']).describe('Whether the full record or a section outline was returned'),
14
16
  * // full-mode arms (present when kind === 'full') — each .optional()
15
- * sections: OUTLINE_VARIANT.shape.sections.optional(), // outline-mode arms
17
+ * sections: z // outline-mode arms
18
+ * .array(OUTLINE_VARIANT.shape.sections.element.describe('One section of the record'))
19
+ * .optional()
20
+ * .describe('Available sections, largest first'),
16
21
  * notice: OUTLINE_VARIANT.shape.notice.optional(),
17
22
  * }),
18
23
  * ```
24
+ *
25
+ * The section item is described in place because `describe-on-fields` asks every
26
+ * array-of-object element for a description and this schema's item carries none.
27
+ * `notice` beside a `sections` array is exempt from `enrichment-prefer-block`.
19
28
  */
20
29
  export const OUTLINE_VARIANT = z.object({
21
30
  kind: z.literal('outline'),
@@ -105,11 +114,27 @@ export function outlineOnOverflow(doc, options) {
105
114
  * for. Pure top-level key projection; supply a custom selector when "section"
106
115
  * means something other than a top-level key.
107
116
  *
117
+ * A requested name that is not a key of `doc` is rejected rather than dropped:
118
+ * it is a stale or mistyped name, and a projection missing it would read as a
119
+ * successful narrow slice. The rejection travels through the tool's existing
120
+ * error path, so no output field has to be declared to carry it. `alwaysKeep`
121
+ * names are the author's, not the caller's, and an absent one is ignored.
122
+ *
108
123
  * @param doc - The full document.
109
124
  * @param want - Section identifiers the agent requested (from the outline).
110
125
  * @param options.alwaysKeep - Metadata keys to retain regardless (ids, timestamps).
126
+ * @throws {McpError} `InvalidParams` when any name in `want` is not a key of
127
+ * `doc`. The message names the unmatched and available keys; `data` carries
128
+ * both as `unmatched` and `available`.
111
129
  */
112
130
  export function selectSections(doc, want, options) {
131
+ const available = Object.keys(doc);
132
+ const availableSet = new Set(available);
133
+ const unmatched = [...new Set(want.filter((name) => !availableSet.has(name)))];
134
+ if (unmatched.length > 0) {
135
+ throw invalidParams(`Unknown section${unmatched.length === 1 ? '' : 's'}: ${unmatched.join(', ')}. ` +
136
+ `Available sections: ${available.join(', ')}.`, { unmatched, available });
137
+ }
113
138
  const keep = new Set([...want, ...(options?.alwaysKeep ?? [])]);
114
139
  return Object.fromEntries(Object.entries(doc).filter(([key]) => keep.has(key)));
115
140
  }
@@ -132,7 +157,7 @@ export function formatOutline(outline) {
132
157
  const lines = [
133
158
  `**${outline.sections.length} sections available** (record too large to inline)`,
134
159
  '',
135
- ...outline.sections.map((s) => `- \`${s.name}\` — ${s.bytes} bytes`),
160
+ ...outline.sections.map((s) => `- ${codeSpan(s.name)} — ${s.bytes} bytes`),
136
161
  '',
137
162
  outline.notice,
138
163
  ];
@@ -1 +1 @@
1
- {"version":3,"file":"outlineOnOverflow.js","sourceRoot":"","sources":["../../../src/utils/overflow/outlineOnOverflow.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"outlineOnOverflow.js","sourceRoot":"","sources":["../../../src/utils/overflow/outlineOnOverflow.ts"],"names":[],"mappings":"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"}
@@ -67,7 +67,9 @@ export declare function encodeCursor(state: PaginationState): string;
67
67
  * @param context - Request context used to correlate warning log entries
68
68
  * @returns Validated `PaginationState` decoded from the cursor
69
69
  * @throws {McpError} With code `InvalidParams` (-32602) if the cursor is malformed,
70
- * base64-invalid, not valid JSON, or has an invalid `offset`/`limit` structure
70
+ * base64-invalid, not valid JSON, or has an invalid `offset`/`limit` structure.
71
+ * `data` carries the rejected `cursor`, `reason: 'invalid_cursor'`, and a
72
+ * `recovery.hint`, so a tool surfaces it like any other classified failure.
71
73
  * @example
72
74
  * const state = decodeCursor(req.params.cursor, ctx);
73
75
  * // state.offset and state.limit are safe to use directly
@@ -1 +1 @@
1
- {"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/utils/pagination/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,KAAK,cAAc,EAAa,MAAM,oCAAoC,CAAC;AAEpF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IAEjF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,iCAAiC;IACjC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAiB3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CA+BrF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7B,GAAG,MAAM,GAAG,SAAS,CAErB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,cAAc,GACtB,eAAe,CAAC,CAAC,CAAC,CAmCpB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB;IACpC,uCAAuC;aACvC,iBAAiB,EAAE,EAAE;IACrB,qCAAqC;aACrC,aAAa,EAAE,IAAI;IACnB,qCAAqC;aACrC,aAAa,EAAE,CAAC;CACR,CAAC"}
1
+ {"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/utils/pagination/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,KAAK,cAAc,EAAa,MAAM,oCAAoC,CAAC;AAEpF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IAEjF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,iCAAiC;IACjC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAiB3D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CAqCrF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7B,GAAG,MAAM,GAAG,SAAS,CAErB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,cAAc,GACtB,eAAe,CAAC,CAAC,CAAC,CAmCpB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB;IACpC,uCAAuC;aACvC,iBAAiB,EAAE,EAAE;IACrB,qCAAqC;aACrC,aAAa,EAAE,IAAI;IACnB,qCAAqC;aACrC,aAAa,EAAE,CAAC;CACR,CAAC"}
@@ -56,7 +56,9 @@ export function encodeCursor(state) {
56
56
  * @param context - Request context used to correlate warning log entries
57
57
  * @returns Validated `PaginationState` decoded from the cursor
58
58
  * @throws {McpError} With code `InvalidParams` (-32602) if the cursor is malformed,
59
- * base64-invalid, not valid JSON, or has an invalid `offset`/`limit` structure
59
+ * base64-invalid, not valid JSON, or has an invalid `offset`/`limit` structure.
60
+ * `data` carries the rejected `cursor`, `reason: 'invalid_cursor'`, and a
61
+ * `recovery.hint`, so a tool surfaces it like any other classified failure.
60
62
  * @example
61
63
  * const state = decodeCursor(req.params.cursor, ctx);
62
64
  * // state.offset and state.limit are safe to use directly
@@ -81,7 +83,13 @@ export function decodeCursor(cursor, context) {
81
83
  cursor,
82
84
  error: error instanceof Error ? error.message : String(error),
83
85
  }));
84
- throw invalidParams('Invalid pagination cursor. The cursor may be expired, corrupted, or from a different request.', { cursor });
86
+ throw invalidParams('Invalid pagination cursor. The cursor may be expired, corrupted, or from a different request.', {
87
+ cursor,
88
+ reason: 'invalid_cursor',
89
+ recovery: {
90
+ hint: 'Omit `cursor` to start from the first page, or pass the `nextCursor` from the previous response unchanged.',
91
+ },
92
+ });
85
93
  }
86
94
  }
87
95
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../src/utils/pagination/pagination.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../src/utils/pagination/pagination.ts"],"names":[],"mappings":"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"}
@@ -1 +1 @@
1
- {"version":3,"file":"csvParser.d.ts","sourceRoot":"","sources":["../../../src/utils/parsing/csvParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAKlC,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,oCAAoC,CAAC;AAkB5C;;;;;;;GAOG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,IAAI,CAAC,WAAW,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CA8D9B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,SAAS,WAAkB,CAAC"}
1
+ {"version":3,"file":"csvParser.d.ts","sourceRoot":"","sources":["../../../src/utils/parsing/csvParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAKlC,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,oCAAoC,CAAC;AAkB5C;;;;;;;GAOG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,IAAI,CAAC,WAAW,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CA6D9B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,SAAS,WAAkB,CAAC"}