@yolk-sdk/emulators 0.1.0-canary.100

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 (338) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +2165 -0
  3. package/dist/anthropic.d.mts +269 -0
  4. package/dist/anthropic.d.mts.map +1 -0
  5. package/dist/anthropic.mjs +177 -0
  6. package/dist/anthropic.mjs.map +1 -0
  7. package/dist/chat-completions.d.mts +288 -0
  8. package/dist/chat-completions.d.mts.map +1 -0
  9. package/dist/chat-completions.mjs +451 -0
  10. package/dist/chat-completions.mjs.map +1 -0
  11. package/dist/codex.d.mts +265 -0
  12. package/dist/codex.d.mts.map +1 -0
  13. package/dist/codex.mjs +199 -0
  14. package/dist/codex.mjs.map +1 -0
  15. package/dist/dropbox/api.d.mts +63 -0
  16. package/dist/dropbox/api.d.mts.map +1 -0
  17. package/dist/dropbox/api.mjs +565 -0
  18. package/dist/dropbox/api.mjs.map +1 -0
  19. package/dist/dropbox/state.d.mts +136 -0
  20. package/dist/dropbox/state.d.mts.map +1 -0
  21. package/dist/dropbox/state.mjs +209 -0
  22. package/dist/dropbox/state.mjs.map +1 -0
  23. package/dist/dropbox.d.mts +79 -0
  24. package/dist/dropbox.d.mts.map +1 -0
  25. package/dist/dropbox.mjs +124 -0
  26. package/dist/dropbox.mjs.map +1 -0
  27. package/dist/email-fixtures.d.mts +36 -0
  28. package/dist/email-fixtures.d.mts.map +1 -0
  29. package/dist/email-fixtures.mjs +1080 -0
  30. package/dist/email-fixtures.mjs.map +1 -0
  31. package/dist/email.d.mts +160 -0
  32. package/dist/email.d.mts.map +1 -0
  33. package/dist/email.mjs +608 -0
  34. package/dist/email.mjs.map +1 -0
  35. package/dist/emulator-compose.d.mts +40 -0
  36. package/dist/emulator-compose.d.mts.map +1 -0
  37. package/dist/emulator-compose.mjs +91 -0
  38. package/dist/emulator-compose.mjs.map +1 -0
  39. package/dist/emulator-http.d.mts +53 -0
  40. package/dist/emulator-http.d.mts.map +1 -0
  41. package/dist/emulator-http.mjs +117 -0
  42. package/dist/emulator-http.mjs.map +1 -0
  43. package/dist/emulator-kernel.d.mts +176 -0
  44. package/dist/emulator-kernel.d.mts.map +1 -0
  45. package/dist/emulator-kernel.mjs +413 -0
  46. package/dist/emulator-kernel.mjs.map +1 -0
  47. package/dist/fixture-route.d.mts +129 -0
  48. package/dist/fixture-route.d.mts.map +1 -0
  49. package/dist/fixture-route.mjs +257 -0
  50. package/dist/fixture-route.mjs.map +1 -0
  51. package/dist/fortnox/api.d.mts +92 -0
  52. package/dist/fortnox/api.d.mts.map +1 -0
  53. package/dist/fortnox/api.mjs +750 -0
  54. package/dist/fortnox/api.mjs.map +1 -0
  55. package/dist/fortnox/state.d.mts +533 -0
  56. package/dist/fortnox/state.d.mts.map +1 -0
  57. package/dist/fortnox/state.mjs +612 -0
  58. package/dist/fortnox/state.mjs.map +1 -0
  59. package/dist/fortnox.d.mts +128 -0
  60. package/dist/fortnox.d.mts.map +1 -0
  61. package/dist/fortnox.mjs +403 -0
  62. package/dist/fortnox.mjs.map +1 -0
  63. package/dist/gateway-evaluate-recordings.d.mts +12 -0
  64. package/dist/gateway-evaluate-recordings.d.mts.map +1 -0
  65. package/dist/gateway-evaluate-recordings.mjs +128 -0
  66. package/dist/gateway-evaluate-recordings.mjs.map +1 -0
  67. package/dist/gateway.d.mts +272 -0
  68. package/dist/gateway.d.mts.map +1 -0
  69. package/dist/gateway.mjs +400 -0
  70. package/dist/gateway.mjs.map +1 -0
  71. package/dist/github/api.d.mts +63 -0
  72. package/dist/github/api.d.mts.map +1 -0
  73. package/dist/github/api.mjs +527 -0
  74. package/dist/github/api.mjs.map +1 -0
  75. package/dist/github/state.d.mts +272 -0
  76. package/dist/github/state.d.mts.map +1 -0
  77. package/dist/github/state.mjs +303 -0
  78. package/dist/github/state.mjs.map +1 -0
  79. package/dist/github.d.mts +77 -0
  80. package/dist/github.d.mts.map +1 -0
  81. package/dist/github.mjs +180 -0
  82. package/dist/github.mjs.map +1 -0
  83. package/dist/google/calendar.d.mts +10 -0
  84. package/dist/google/calendar.d.mts.map +1 -0
  85. package/dist/google/calendar.mjs +252 -0
  86. package/dist/google/calendar.mjs.map +1 -0
  87. package/dist/google/drive.d.mts +8 -0
  88. package/dist/google/drive.d.mts.map +1 -0
  89. package/dist/google/drive.mjs +252 -0
  90. package/dist/google/drive.mjs.map +1 -0
  91. package/dist/google/gmail.d.mts +10 -0
  92. package/dist/google/gmail.d.mts.map +1 -0
  93. package/dist/google/gmail.mjs +591 -0
  94. package/dist/google/gmail.mjs.map +1 -0
  95. package/dist/google/shared.d.mts +107 -0
  96. package/dist/google/shared.d.mts.map +1 -0
  97. package/dist/google/shared.mjs +146 -0
  98. package/dist/google/shared.mjs.map +1 -0
  99. package/dist/google/state.d.mts +385 -0
  100. package/dist/google/state.d.mts.map +1 -0
  101. package/dist/google/state.mjs +496 -0
  102. package/dist/google/state.mjs.map +1 -0
  103. package/dist/google.d.mts +75 -0
  104. package/dist/google.d.mts.map +1 -0
  105. package/dist/google.mjs +210 -0
  106. package/dist/google.mjs.map +1 -0
  107. package/dist/linkedin-search/api.d.mts +45 -0
  108. package/dist/linkedin-search/api.d.mts.map +1 -0
  109. package/dist/linkedin-search/api.mjs +181 -0
  110. package/dist/linkedin-search/api.mjs.map +1 -0
  111. package/dist/linkedin-search/state.d.mts +123 -0
  112. package/dist/linkedin-search/state.d.mts.map +1 -0
  113. package/dist/linkedin-search/state.mjs +261 -0
  114. package/dist/linkedin-search/state.mjs.map +1 -0
  115. package/dist/linkedin-search.d.mts +69 -0
  116. package/dist/linkedin-search.d.mts.map +1 -0
  117. package/dist/linkedin-search.mjs +158 -0
  118. package/dist/linkedin-search.mjs.map +1 -0
  119. package/dist/mcp/afloat-recordings.d.mts +8 -0
  120. package/dist/mcp/afloat-recordings.d.mts.map +1 -0
  121. package/dist/mcp/afloat-recordings.mjs +918 -0
  122. package/dist/mcp/afloat-recordings.mjs.map +1 -0
  123. package/dist/mcp/api.d.mts +45 -0
  124. package/dist/mcp/api.d.mts.map +1 -0
  125. package/dist/mcp/api.mjs +609 -0
  126. package/dist/mcp/api.mjs.map +1 -0
  127. package/dist/mcp/recordings.d.mts +40 -0
  128. package/dist/mcp/recordings.d.mts.map +1 -0
  129. package/dist/mcp/recordings.mjs +2390 -0
  130. package/dist/mcp/recordings.mjs.map +1 -0
  131. package/dist/mcp/state.d.mts +86 -0
  132. package/dist/mcp/state.d.mts.map +1 -0
  133. package/dist/mcp/state.mjs +98 -0
  134. package/dist/mcp/state.mjs.map +1 -0
  135. package/dist/mcp.d.mts +85 -0
  136. package/dist/mcp.d.mts.map +1 -0
  137. package/dist/mcp.mjs +264 -0
  138. package/dist/mcp.mjs.map +1 -0
  139. package/dist/messages.d.mts +183 -0
  140. package/dist/messages.d.mts.map +1 -0
  141. package/dist/messages.mjs +532 -0
  142. package/dist/messages.mjs.map +1 -0
  143. package/dist/microsoft/api.d.mts +47 -0
  144. package/dist/microsoft/api.d.mts.map +1 -0
  145. package/dist/microsoft/api.mjs +178 -0
  146. package/dist/microsoft/api.mjs.map +1 -0
  147. package/dist/microsoft/calendar.d.mts +30 -0
  148. package/dist/microsoft/calendar.d.mts.map +1 -0
  149. package/dist/microsoft/calendar.mjs +271 -0
  150. package/dist/microsoft/calendar.mjs.map +1 -0
  151. package/dist/microsoft/drive.d.mts +36 -0
  152. package/dist/microsoft/drive.d.mts.map +1 -0
  153. package/dist/microsoft/drive.mjs +298 -0
  154. package/dist/microsoft/drive.mjs.map +1 -0
  155. package/dist/microsoft/graph.d.mts +198 -0
  156. package/dist/microsoft/graph.d.mts.map +1 -0
  157. package/dist/microsoft/graph.mjs +264 -0
  158. package/dist/microsoft/graph.mjs.map +1 -0
  159. package/dist/microsoft/mail.d.mts +48 -0
  160. package/dist/microsoft/mail.d.mts.map +1 -0
  161. package/dist/microsoft/mail.mjs +488 -0
  162. package/dist/microsoft/mail.mjs.map +1 -0
  163. package/dist/microsoft/state.d.mts +480 -0
  164. package/dist/microsoft/state.d.mts.map +1 -0
  165. package/dist/microsoft/state.mjs +625 -0
  166. package/dist/microsoft/state.mjs.map +1 -0
  167. package/dist/microsoft.d.mts +168 -0
  168. package/dist/microsoft.d.mts.map +1 -0
  169. package/dist/microsoft.mjs +483 -0
  170. package/dist/microsoft.mjs.map +1 -0
  171. package/dist/node.d.mts +47 -0
  172. package/dist/node.d.mts.map +1 -0
  173. package/dist/node.mjs +178 -0
  174. package/dist/node.mjs.map +1 -0
  175. package/dist/notion/api.d.mts +51 -0
  176. package/dist/notion/api.d.mts.map +1 -0
  177. package/dist/notion/api.mjs +507 -0
  178. package/dist/notion/api.mjs.map +1 -0
  179. package/dist/notion/state.d.mts +329 -0
  180. package/dist/notion/state.d.mts.map +1 -0
  181. package/dist/notion/state.mjs +432 -0
  182. package/dist/notion/state.mjs.map +1 -0
  183. package/dist/notion.d.mts +72 -0
  184. package/dist/notion.d.mts.map +1 -0
  185. package/dist/notion.mjs +127 -0
  186. package/dist/notion.mjs.map +1 -0
  187. package/dist/openai.d.mts +165 -0
  188. package/dist/openai.d.mts.map +1 -0
  189. package/dist/openai.mjs +141 -0
  190. package/dist/openai.mjs.map +1 -0
  191. package/dist/opencode-recordings.d.mts +7 -0
  192. package/dist/opencode-recordings.d.mts.map +1 -0
  193. package/dist/opencode-recordings.mjs +222 -0
  194. package/dist/opencode-recordings.mjs.map +1 -0
  195. package/dist/opencode.d.mts +70 -0
  196. package/dist/opencode.d.mts.map +1 -0
  197. package/dist/opencode.mjs +217 -0
  198. package/dist/opencode.mjs.map +1 -0
  199. package/dist/r2-fixtures.d.mts +36 -0
  200. package/dist/r2-fixtures.d.mts.map +1 -0
  201. package/dist/r2-fixtures.mjs +245 -0
  202. package/dist/r2-fixtures.mjs.map +1 -0
  203. package/dist/r2-guard.d.mts +43 -0
  204. package/dist/r2-guard.d.mts.map +1 -0
  205. package/dist/r2-guard.mjs +216 -0
  206. package/dist/r2-guard.mjs.map +1 -0
  207. package/dist/r2.d.mts +166 -0
  208. package/dist/r2.d.mts.map +1 -0
  209. package/dist/r2.mjs +517 -0
  210. package/dist/r2.mjs.map +1 -0
  211. package/dist/responses.d.mts +231 -0
  212. package/dist/responses.d.mts.map +1 -0
  213. package/dist/responses.mjs +556 -0
  214. package/dist/responses.mjs.map +1 -0
  215. package/dist/route-evidence.d.mts +45 -0
  216. package/dist/route-evidence.d.mts.map +1 -0
  217. package/dist/route-evidence.mjs +56 -0
  218. package/dist/route-evidence.mjs.map +1 -0
  219. package/dist/router.d.mts +93 -0
  220. package/dist/router.d.mts.map +1 -0
  221. package/dist/router.mjs +259 -0
  222. package/dist/router.mjs.map +1 -0
  223. package/dist/stateful-core.d.mts +17 -0
  224. package/dist/stateful-core.d.mts.map +1 -0
  225. package/dist/stateful-core.mjs +41 -0
  226. package/dist/stateful-core.mjs.map +1 -0
  227. package/dist/stateful-emulator.d.mts +578 -0
  228. package/dist/stateful-emulator.d.mts.map +1 -0
  229. package/dist/stateful-emulator.mjs +1248 -0
  230. package/dist/stateful-emulator.mjs.map +1 -0
  231. package/dist/stateful-secrets.d.mts +84 -0
  232. package/dist/stateful-secrets.d.mts.map +1 -0
  233. package/dist/stateful-secrets.mjs +216 -0
  234. package/dist/stateful-secrets.mjs.map +1 -0
  235. package/dist/subscription-usage-recordings.d.mts +9 -0
  236. package/dist/subscription-usage-recordings.d.mts.map +1 -0
  237. package/dist/subscription-usage-recordings.mjs +53 -0
  238. package/dist/subscription-usage-recordings.mjs.map +1 -0
  239. package/dist/subscription-usage.d.mts +53 -0
  240. package/dist/subscription-usage.d.mts.map +1 -0
  241. package/dist/subscription-usage.mjs +21 -0
  242. package/dist/subscription-usage.mjs.map +1 -0
  243. package/dist/telegram/api.d.mts +34 -0
  244. package/dist/telegram/api.d.mts.map +1 -0
  245. package/dist/telegram/api.mjs +257 -0
  246. package/dist/telegram/api.mjs.map +1 -0
  247. package/dist/telegram/state.d.mts +128 -0
  248. package/dist/telegram/state.d.mts.map +1 -0
  249. package/dist/telegram/state.mjs +154 -0
  250. package/dist/telegram/state.mjs.map +1 -0
  251. package/dist/telegram.d.mts +62 -0
  252. package/dist/telegram.d.mts.map +1 -0
  253. package/dist/telegram.mjs +127 -0
  254. package/dist/telegram.mjs.map +1 -0
  255. package/dist/todoist/api.d.mts +55 -0
  256. package/dist/todoist/api.d.mts.map +1 -0
  257. package/dist/todoist/api.mjs +415 -0
  258. package/dist/todoist/api.mjs.map +1 -0
  259. package/dist/todoist/state.d.mts +275 -0
  260. package/dist/todoist/state.d.mts.map +1 -0
  261. package/dist/todoist/state.mjs +345 -0
  262. package/dist/todoist/state.mjs.map +1 -0
  263. package/dist/todoist.d.mts +68 -0
  264. package/dist/todoist.d.mts.map +1 -0
  265. package/dist/todoist.mjs +181 -0
  266. package/dist/todoist.mjs.map +1 -0
  267. package/dist/xai.d.mts +267 -0
  268. package/dist/xai.d.mts.map +1 -0
  269. package/dist/xai.mjs +252 -0
  270. package/dist/xai.mjs.map +1 -0
  271. package/package.json +157 -0
  272. package/src/anthropic.ts +289 -0
  273. package/src/chat-completions.ts +924 -0
  274. package/src/codex.ts +296 -0
  275. package/src/dropbox/api.ts +1084 -0
  276. package/src/dropbox/state.ts +364 -0
  277. package/src/dropbox.ts +203 -0
  278. package/src/email-fixtures.ts +1297 -0
  279. package/src/email.ts +1108 -0
  280. package/src/emulator-compose.ts +147 -0
  281. package/src/emulator-http.ts +184 -0
  282. package/src/emulator-kernel.ts +844 -0
  283. package/src/fixture-route.ts +561 -0
  284. package/src/fortnox/api.ts +1352 -0
  285. package/src/fortnox/state.ts +798 -0
  286. package/src/fortnox.ts +801 -0
  287. package/src/gateway-evaluate-recordings.ts +153 -0
  288. package/src/gateway.ts +530 -0
  289. package/src/github/api.ts +986 -0
  290. package/src/github/state.ts +439 -0
  291. package/src/github.ts +271 -0
  292. package/src/google/calendar.ts +486 -0
  293. package/src/google/drive.ts +471 -0
  294. package/src/google/gmail.ts +1011 -0
  295. package/src/google/shared.ts +321 -0
  296. package/src/google/state.ts +686 -0
  297. package/src/google.ts +298 -0
  298. package/src/linkedin-search/api.ts +363 -0
  299. package/src/linkedin-search/state.ts +373 -0
  300. package/src/linkedin-search.ts +241 -0
  301. package/src/mcp/afloat-recordings.ts +1040 -0
  302. package/src/mcp/api.ts +1105 -0
  303. package/src/mcp/recordings.ts +2665 -0
  304. package/src/mcp/state.ts +144 -0
  305. package/src/mcp.ts +364 -0
  306. package/src/messages.ts +844 -0
  307. package/src/microsoft/api.ts +426 -0
  308. package/src/microsoft/calendar.ts +491 -0
  309. package/src/microsoft/drive.ts +541 -0
  310. package/src/microsoft/graph.ts +550 -0
  311. package/src/microsoft/mail.ts +833 -0
  312. package/src/microsoft/state.ts +822 -0
  313. package/src/microsoft.ts +982 -0
  314. package/src/node.ts +293 -0
  315. package/src/notion/api.ts +976 -0
  316. package/src/notion/state.ts +512 -0
  317. package/src/notion.ts +210 -0
  318. package/src/openai.ts +198 -0
  319. package/src/opencode-recordings.ts +257 -0
  320. package/src/opencode.ts +271 -0
  321. package/src/r2-fixtures.ts +295 -0
  322. package/src/r2-guard.ts +324 -0
  323. package/src/r2.ts +890 -0
  324. package/src/responses.ts +901 -0
  325. package/src/route-evidence.ts +90 -0
  326. package/src/router.ts +490 -0
  327. package/src/stateful-core.ts +70 -0
  328. package/src/stateful-emulator.ts +2620 -0
  329. package/src/stateful-secrets.ts +299 -0
  330. package/src/subscription-usage-recordings.ts +77 -0
  331. package/src/subscription-usage.ts +68 -0
  332. package/src/telegram/api.ts +437 -0
  333. package/src/telegram/state.ts +229 -0
  334. package/src/telegram.ts +227 -0
  335. package/src/todoist/api.ts +736 -0
  336. package/src/todoist/state.ts +456 -0
  337. package/src/todoist.ts +316 -0
  338. package/src/xai.ts +341 -0
@@ -0,0 +1,144 @@
1
+ /**
2
+ * MCP emulator state, seed, profiles, and minted value forms (internal).
3
+ *
4
+ * The state holds the modern listing the seed selects and the legacy sessions minted since the
5
+ * last reset or seed; a seed holds no session, so no seeded value can take the minted
6
+ * `yolk-emu-session-<n>` form. The session counter and the cursor generation are runtime data
7
+ * that never reset (`McpRuntime`).
8
+ *
9
+ * @experimental
10
+ */
11
+ import { createHash } from 'node:crypto'
12
+ import { Result } from 'effect'
13
+ import * as Schema from 'effect/Schema'
14
+
15
+ /** The reserved origin both synthetic profiles answer on. */
16
+ export const mcpEmulatorOrigin = 'https://mcp.example.test'
17
+
18
+ /** The synthetic modern server: stateless `2026-07-28`, JSON answers. */
19
+ export const mcpEmulatorModernPath = '/modern/mcp'
20
+
21
+ /** The synthetic legacy server: an `initialize` handshake, a session, and SSE answers. */
22
+ export const mcpEmulatorLegacyPath = '/legacy/mcp'
23
+
24
+ /**
25
+ * The public reserved invalid credential of the MCP auth case: the only credential value the
26
+ * emulator compares a bearer with (through its digest), answered the recorded 401.
27
+ */
28
+ export const mcpEmulatorReservedInvalidCredential = 'yolk-conformance-invalid-credential-0000'
29
+
30
+ /** The Afloat profile's origin (the provider endpoint `https://useafloat.com/mcp`). */
31
+ export const mcpEmulatorAfloatOrigin = 'https://useafloat.com'
32
+
33
+ /** The Afloat profile: stateless `2026-07-28`, JSON answers, no session. */
34
+ export const mcpEmulatorAfloatPath = '/mcp'
35
+
36
+ /**
37
+ * The fixed public prefix of an Afloat key. On the Afloat origin a bearer is recognised only as
38
+ * `afloat_<remainder>`, and the remainder is the guarded secret (`a` is a hex digit, so the whole
39
+ * key fails the shared first-character rule).
40
+ */
41
+ export const mcpEmulatorAfloatKeyPrefix = 'afloat_'
42
+
43
+ /**
44
+ * The public reserved invalid Afloat credential of the MCP auth case, answered the recorded 401 on
45
+ * the Afloat profile (compared only through the digest of its remainder).
46
+ */
47
+ export const mcpEmulatorAfloatReservedInvalidCredential = 'afloat_yolkconformanceinvalid0000'
48
+
49
+ /** The minted session id form (`yolk-emu-session-<n>`, `n` from a counter that never resets). */
50
+ export const mcpEmulatorSessionPrefix = 'yolk-emu-session-'
51
+
52
+ /** At most this many sessions are held; an `initialize` beyond it is refused before any fault. */
53
+ export const mcpEmulatorSessionCap = 256
54
+
55
+ /**
56
+ * Which recorded modern listing `tools/list` answers: `one-page` (the listing every calling
57
+ * fixture records; the default) or `two-pages` (the paged listing of `mcp.tools.list`, whose first
58
+ * page issues a cursor). Both come from fixtures; neither is synthesised.
59
+ */
60
+ export const McpEmulatorModernListing = Schema.Literals(['one-page', 'two-pages'])
61
+
62
+ export type McpEmulatorModernListing = typeof McpEmulatorModernListing.Type
63
+
64
+ /** A legacy session: minted by `initialize`, ready after `notifications/initialized`. */
65
+ export const McpEmulatorSession = Schema.Struct({
66
+ id: Schema.String,
67
+ phase: Schema.Literals(['initializing', 'ready'])
68
+ })
69
+
70
+ export type McpEmulatorSession = typeof McpEmulatorSession.Type
71
+
72
+ /** The emulator state (a JSON value the core snapshots and restores). */
73
+ export const McpEmulatorStateSchema = Schema.Struct({
74
+ modernListing: McpEmulatorModernListing,
75
+ sessions: Schema.Array(McpEmulatorSession)
76
+ })
77
+
78
+ export type McpEmulatorState = {
79
+ modernListing: McpEmulatorModernListing
80
+ sessions: ReadonlyArray<McpEmulatorSession>
81
+ }
82
+
83
+ /** The typed seed: only the modern listing; it holds no session. */
84
+ export const McpEmulatorSeed = Schema.Struct({
85
+ modernListing: Schema.optionalKey(McpEmulatorModernListing)
86
+ })
87
+
88
+ export type McpEmulatorSeed = typeof McpEmulatorSeed.Type
89
+
90
+ const strict = { onExcessProperty: 'error' } as const
91
+
92
+ const decodeSeed = Schema.decodeUnknownResult(McpEmulatorSeed, strict)
93
+
94
+ const decodeStateSchema = Schema.decodeUnknownResult(McpEmulatorStateSchema, strict)
95
+
96
+ const issueMessage = (issue: Schema.SchemaError['issue']): string =>
97
+ new Schema.SchemaError(issue).message
98
+
99
+ /** Build the state of a seed (no sessions), or why the seed is invalid. */
100
+ export const buildSeedState = (input: unknown): McpEmulatorState | string => {
101
+ const decoded = decodeSeed(input)
102
+
103
+ if (Result.isFailure(decoded)) return issueMessage(decoded.failure.issue)
104
+
105
+ return { modernListing: decoded.success.modernListing ?? 'one-page', sessions: [] }
106
+ }
107
+
108
+ /** Decode a whole state (the core's seed validation), or why it is invalid. */
109
+ export const decodeState = (input: unknown): McpEmulatorState | string => {
110
+ const decoded = decodeStateSchema(input)
111
+
112
+ return Result.isFailure(decoded)
113
+ ? issueMessage(decoded.failure.issue)
114
+ : { modernListing: decoded.success.modernListing, sessions: decoded.success.sessions }
115
+ }
116
+
117
+ /**
118
+ * The one-way digest routes see instead of the bearer: SHA-256 of the arrival origin, a space,
119
+ * and the bearer (the wrapper's opt-in `bearerDigest`).
120
+ */
121
+ export const mcpBearerDigest = (bearer: string, origin: string): string =>
122
+ createHash('sha256').update(`${origin} ${bearer}`, 'utf8').digest('hex')
123
+
124
+ /**
125
+ * Runtime data (never in the state): the session counter and the cursor generation never reset;
126
+ * the cursor issued in the current generation is cleared on every reset and seed.
127
+ */
128
+ export type McpRuntime = {
129
+ /** The number of the next minted session (never reset). */
130
+ nextSession: number
131
+ /** Starts at 1; every reset and seed starts the next generation (never reset). */
132
+ generation: number
133
+ /** The generation that first issued the recorded cursor (never reset). */
134
+ cursorFirstGeneration: number | undefined
135
+ /** The cursor issued in the current generation, if any. */
136
+ issuedCursor: string | undefined
137
+ }
138
+
139
+ export const makeMcpRuntime = (): McpRuntime => ({
140
+ nextSession: 1,
141
+ generation: 1,
142
+ cursorFirstGeneration: undefined,
143
+ issuedCursor: undefined
144
+ })
package/src/mcp.ts ADDED
@@ -0,0 +1,364 @@
1
+ /**
2
+ * Stateful MCP emulator (the two synthetic servers of the MCP conformance fixtures: profile
3
+ * `synthetic-modern` on `https://mcp.example.test/modern/mcp`, stateless `2026-07-28` with JSON
4
+ * answers, and profile `synthetic-legacy` on `https://mcp.example.test/legacy/mcp`, an
5
+ * `initialize` handshake with sessions and SSE answers; and profile `afloat` on the provider
6
+ * endpoint `https://useafloat.com/mcp`, stateless `2026-07-28` with JSON answers and no session),
7
+ * built on the upstream `@emulators/core` custom runtime, with a request ledger, status and
8
+ * truncation faults, and an `/_emulate/*` control plane.
9
+ *
10
+ * It never imports SDK code: its answers are the sixteen synthetic `@yolk-sdk/mcp/conformance`
11
+ * fixtures copied as data (`src/mcp/recordings.ts`) and the eight derived
12
+ * `@yolk-sdk/connectors/afloat/conformance` fixtures copied as data
13
+ * (`src/mcp/afloat-recordings.ts`; derived from the provider's source, not recorded live, all
14
+ * unverified; one listing page of the published tool subset, the read call of `list-invoices`, its
15
+ * tool error, the absent tool, and the 401; answering those two derived `tools/call` fixtures, not
16
+ * only recorded calls, is in scope by the owner's decision), and every manifest row names the
17
+ * conformance cases whose fixtures it answers (`mcpEmulatorRoutes`: one
18
+ * `RPC <origin><path>#<method>` row per recorded JSON-RPC method of each profile, plus the legacy
19
+ * `GET` row; no row writes anything in a real service). Response behaviour comes only from the
20
+ * fixtures, byte for byte: a JSON-RPC POST is answered only when it equals a recorded request
21
+ * within the latitude below, with the recorded answer, the request id substituted at exactly the
22
+ * recorded place (the top-level `id` of a JSON answer, or the `id` of the SSE response event's
23
+ * payload; notification events and SSE `id:` lines stay byte for byte; an answer that does not
24
+ * carry the recorded request id, such as the legacy era probe's `id: null` error, is unchanged).
25
+ * The legacy `initialize` mints a session `yolk-emu-session-<n>` (`n` from a counter that never
26
+ * resets, a form no seed holds), answered in the recorded `mcp-session-id` header;
27
+ * `notifications/initialized` on that session answers the recorded 202 and makes it ready; on a
28
+ * ready session `tools/list`, `tools/call`, and the standing `GET` (the recorded 405) answer the
29
+ * recordings with the session's id. At most 256 sessions are held: another `initialize` is refused
30
+ * before any fault. `reset` and `seed` clear the sessions. The seed only selects which recorded
31
+ * modern listing `tools/list` answers (`modernListing`: `one-page`, the default, or `two-pages`,
32
+ * whose first page issues the recorded cursor in the generation that first issues it, and
33
+ * `<cursor>.g<generation>` after a reset or seed; the second page answers only the cursor issued in
34
+ * the current generation). Every plan prepares its answer before anything is written; its commit
35
+ * (minting a session, readying one, issuing a cursor) runs only when no fault answers the request.
36
+ * Status faults (400-599) and `truncate-after-chunks` faults apply only after a request is admitted
37
+ * and planned, and a faulted request writes nothing: a truncation sends the prepared answer cut
38
+ * short and never runs the commit, so a truncated `initialize` holds no session and leaves the
39
+ * counter and the cap where they were, and a truncated first page issues no cursor. `match.route`
40
+ * selects one manifest row (a value naming no row is rejected when the fault is added);
41
+ * `match.method` is the HTTP method. Anything else answers one 400 not-emulated, ledgered with
42
+ * constant text only (`/<unrecognised>`, a standard method or `<other>`, an empty query, no headers
43
+ * or body, a constant reason, and the route template or row), that writes nothing and uses up no
44
+ * fault.
45
+ *
46
+ * Not emulated: `DELETE` (the client never sends it), `ping`, `resources/*`, `prompts/*`,
47
+ * `logging/*`, `completion/*`, `tasks/*`, JSON-RPC batches and client-sent responses, a JSON body
48
+ * repeating a key (the wrapper's opt-in `uniqueJsonKeys`), `mcp-*` headers no recording carries
49
+ * (such as `mcp-param-*`), cursors this emulator did not issue, any other tool or arguments, any
50
+ * other origin or path, and a missing `Authorization` (no fixture records the answer to one).
51
+ *
52
+ * Fail closed, on the shared wrapper's fail-closed mode as `/github`, `/google`, and
53
+ * `/linkedin-search` use it, with its opt-in `constantRefusals`, `guardAllHeaders`, and
54
+ * `guardOutput`: a request is recognised only on an emulated route shape, and any `Authorization`
55
+ * header is exactly `Bearer <token>` with a recognisable bearer (the RFC 6750 `b64token` syntax, at
56
+ * least 8 characters, a first character in `[G-Zg-z\-._~+/]` other than `n`, `r`, `t`, `u`, and a
57
+ * character outside `[0-9.eE+-]`). The Afloat rule (the wrapper's opt-in `bearerPrefixes`, the
58
+ * Telegram precedent): on `https://useafloat.com` a bearer is recognised only as
59
+ * `afloat_<remainder>`, and the remainder, not the key, must be recognisable (an Afloat key starts
60
+ * with the hex digit `a`, which fails the first-character rule); the remainder is the guarded
61
+ * secret below and what the digest takes, and a bearer without `afloat_` there, or with it on the
62
+ * synthetic origin, is unrecognisable. A recognised request that repeats the bearer anywhere (its
63
+ * raw path, the raw query or any query key or value, any request header name or value other than
64
+ * `Authorization`, or its body, through the wrapper's fixpoint closure of tolerant percent-decoding
65
+ * and JSON-unescaping, capped, where a cap refuses) is ledgered with constant text only. The
66
+ * prepared output is checked the same way before any fault is decided or anything is committed: an
67
+ * answer (every header and chunk) or a minted session id or cursor that would repeat the bearer is
68
+ * refused with the constant credential-repeat entry, no fault used and nothing written, so a bearer
69
+ * such as `yolk-emu-session-1`, or `synthetic-mcp` (inside the recorded `yolk-synthetic-mcp`),
70
+ * never reaches a response, the state, or `/_emulate/*`. The bearer is never stored, forwarded,
71
+ * ledgered, or echoed: routes see only its digest (the wrapper's opt-in `bearerDigest`; SHA-256 of
72
+ * the origin, a space, and the bearer), which they compare only with the digest of the public
73
+ * reserved invalid credential `yolk-conformance-invalid-credential-0000` (itself a recognisable
74
+ * bearer), or on the Afloat profile of the remainder of `afloat_yolkconformanceinvalid0000`, to
75
+ * answer its recorded 401 byte for byte. Scope: the bearer is never copied from the request into a
76
+ * response, the state, or `/_emulate/*`; the output guard also refuses a prepared fixture answer,
77
+ * minted session id, or cursor that happens to contain it, but the emulator's other constants
78
+ * (state values such as `initializing`, wrapper headers such as `x-emulator-evidence`) and
79
+ * host-configured control-plane data (a fault body) may coincidentally equal a bearer and are not
80
+ * checked. `makeMcpEmulator` also throws when a copied recording is not canonical JSON (every JSON
81
+ * body and SSE `data:` payload equal to `JSON.stringify(JSON.parse(text))`), which id substitution
82
+ * relies on.
83
+ *
84
+ * Request-shape latitude (`/mcp`, the only accepted deviations): any bearer value in the RFC 6750
85
+ * `b64token` syntax (`[A-Za-z0-9\-._~+/]+=*`) of at least 8 characters, starting with a character
86
+ * in `[G-Zg-z\-._~+/]` other than `n`, `r`, `t`, `u`, with at least one outside `[0-9.eE+-]` (on
87
+ * the Afloat profile, `afloat_` followed by such a value: an Afloat key starts with the hex digit
88
+ * `a`, so its remainder after `afloat_` is the value checked, guarded, and digested), that occurs
89
+ * nowhere else in the request (any header name or value included) and in no answer or value the
90
+ * request would store (never stored or ledgered; only its digest is compared, with the digest of
91
+ * the public reserved invalid credential `yolk-conformance-invalid-credential-0000`, or on the
92
+ * Afloat profile of the remainder of `afloat_yolkconformanceinvalid0000`, each answering the
93
+ * recorded 401 on its profile's era probe); extra request headers, except `mcp-*` headers other
94
+ * than `mcp-method`, `mcp-name`, `mcp-protocol-version`, and `mcp-session-id`; a recorded header
95
+ * value sent as several headers that the HTTP layer joins into the recorded value; JSON key order;
96
+ * any JSON-RPC request id that is an integer from 0 to 2^53 - 1 or 1 to 64 printable ASCII
97
+ * characters where the recording has an id; any non-empty `name` and `version` (and no other key)
98
+ * in the `_meta` client info (`io.modelcontextprotocol/clientInfo`) of a modern request; a session
99
+ * id this emulator minted since the last reset or seed where the recording sends `mcp-session-id`
100
+ * (initializing for `notifications/initialized`, ready otherwise); and, with the seed's `two-pages`
101
+ * listing, the cursor this emulator issued in the current generation on the second page.
102
+ * `Authorization` must be exactly `Bearer <token>` (that spelling, one space). Everything else
103
+ * (another origin or path, any query, other HTTP methods such as `DELETE` or a `GET` on the modern
104
+ * or Afloat profile, a bearer without `afloat_` on the Afloat profile or with it on the synthetic
105
+ * profiles, an Afloat key whose remainder fails the rule above (such as one starting with a hex
106
+ * digit), JSON-RPC methods no fixture of the profile records such as `ping`, `resources/*`, or
107
+ * `prompts/*`, batches and client-sent responses, other members, a JSON body repeating a key
108
+ * (compared after unescaping), a `null`, negative, or fractional id, other params (other tools,
109
+ * arguments, protocol versions, or capabilities, extra client-info keys, a cursor on the Afloat
110
+ * listing, and a legacy `initialize` client info other than the recorded one), the MCP headers
111
+ * `accept`, `content-type`, `mcp-method`, `mcp-protocol-version`, `mcp-name`, and `last-event-id`
112
+ * other than the recorded values or present where none is recorded, any other `mcp-*` header (such
113
+ * as `mcp-param-*`), `mcp-session-id` missing where recorded or present where not, an unknown
114
+ * session or one in the wrong phase, a cursor not issued in the current generation, a reserved
115
+ * invalid credential on anything but its profile's era probe, a bearer repeated anywhere in the
116
+ * request, and a bearer an answer or a minted session id or cursor would repeat) is not emulated.
117
+ *
118
+ * Node-only: `@emulators/core` imports Node builtins, so the core is loaded lazily by
119
+ * `makeMcpEmulator` (importing this module has no side effects).
120
+ *
121
+ * @experimental
122
+ */
123
+ import { Data, Predicate } from 'effect'
124
+ import {
125
+ mcpApiRoutes,
126
+ mcpEmulatorDrillKnobs,
127
+ mcpRecordingProblems,
128
+ type McpApiEnv,
129
+ type McpEmulatorDrills
130
+ } from './mcp/api.ts'
131
+ import { mcpEmulatorAfloatFixtures } from './mcp/afloat-recordings.ts'
132
+ import { mcpEmulatorFixtures } from './mcp/recordings.ts'
133
+ import {
134
+ buildSeedState,
135
+ decodeState,
136
+ makeMcpRuntime,
137
+ mcpBearerDigest,
138
+ mcpEmulatorAfloatKeyPrefix,
139
+ mcpEmulatorAfloatOrigin,
140
+ mcpEmulatorAfloatReservedInvalidCredential,
141
+ mcpEmulatorOrigin,
142
+ mcpEmulatorReservedInvalidCredential,
143
+ type McpEmulatorSeed,
144
+ type McpEmulatorState
145
+ } from './mcp/state.ts'
146
+ import type { EmulatorRouteEvidence } from './route-evidence.ts'
147
+ import {
148
+ StatefulFaultMatch,
149
+ StatefulStreamFault,
150
+ checkBooleanDrills,
151
+ makeChunkedStatefulEmulator,
152
+ routeManifest,
153
+ type StatefulCoverage,
154
+ type StatefulEmulatorApi,
155
+ type StatefulFaultState,
156
+ type StatefulInputKind,
157
+ type StatefulLedgerEntry
158
+ } from './stateful-emulator.ts'
159
+ import { statefulCoreRuntime } from './stateful-core.ts'
160
+ import { isRecognisableBearerValue } from './stateful-secrets.ts'
161
+
162
+ export type { EmulatorEvidence, EmulatorRouteEvidence } from './route-evidence.ts'
163
+
164
+ export { emulatorEvidenceHeader } from './route-evidence.ts'
165
+
166
+ export { isMcpEmulatedRequestId, mcpEmulatorDrillKnobs, type McpEmulatorDrills } from './mcp/api.ts'
167
+
168
+ export {
169
+ McpEmulatorModernListing,
170
+ McpEmulatorSeed,
171
+ McpEmulatorSession,
172
+ McpEmulatorStateSchema,
173
+ mcpEmulatorAfloatKeyPrefix,
174
+ mcpEmulatorAfloatOrigin,
175
+ mcpEmulatorAfloatPath,
176
+ mcpEmulatorAfloatReservedInvalidCredential,
177
+ mcpEmulatorLegacyPath,
178
+ mcpEmulatorModernPath,
179
+ mcpEmulatorOrigin,
180
+ mcpEmulatorReservedInvalidCredential,
181
+ mcpEmulatorSessionCap,
182
+ mcpEmulatorSessionPrefix,
183
+ type McpEmulatorState
184
+ } from './mcp/state.ts'
185
+
186
+ export { mcpEmulatorAfloatFixtures } from './mcp/afloat-recordings.ts'
187
+
188
+ export {
189
+ mcpEmulatorFixtures,
190
+ type McpRecordedExchange,
191
+ type McpRecordedFixture,
192
+ type McpRecordedRequest,
193
+ type McpRecordedResponse
194
+ } from './mcp/recordings.ts'
195
+
196
+ /**
197
+ * Route evidence manifest: one `RPC <origin><path>#<method>` row per recorded JSON-RPC method of
198
+ * each profile, plus the legacy `GET` row, with the conformance cases whose (synthetic,
199
+ * unverified) fixtures each answers. No row writes anything. Kept in sync with the handlers by
200
+ * construction (both come from one route table).
201
+ */
202
+ export const mcpEmulatorRoutes: ReadonlyArray<EmulatorRouteEvidence> =
203
+ mcpApiRoutes.flatMap(routeManifest)
204
+
205
+ /**
206
+ * Optional fault filter; an omitted field matches every request. `method` is the HTTP method
207
+ * (`POST` or `GET`, never a row's `RPC`); `path` is the raw request path (ending in `*`, a
208
+ * prefix); `route` is a manifest row path (for example
209
+ * `https://mcp.example.test/legacy/mcp#tools/list`), and a value naming no row is rejected when
210
+ * the fault is added.
211
+ */
212
+ export const McpFaultMatch = StatefulFaultMatch
213
+
214
+ export type McpFaultMatch = typeof StatefulFaultMatch.Type
215
+
216
+ /**
217
+ * A status fault (400-599), or a `truncate-after-chunks` fault that sends the first `chunks`
218
+ * chunks of the prepared answer and then ends it cleanly (an SSE answer has two chunks, a JSON
219
+ * answer one). Only a request the emulator would answer reaches a fault: a request that is not
220
+ * emulated, by its shape or by the state, never uses one up. A faulted request writes nothing (a
221
+ * truncated `initialize` mints no session; a truncated first page issues no cursor). A truncation
222
+ * that cannot apply answers 500 and is not used up.
223
+ */
224
+ export const McpFault = StatefulStreamFault
225
+
226
+ export type McpFault = StatefulStreamFault
227
+
228
+ export type McpFaultState = StatefulFaultState<McpFault>
229
+
230
+ export type McpLedgerEntry = StatefulLedgerEntry
231
+
232
+ export type McpCoverage = StatefulCoverage
233
+
234
+ /** Invalid emulator input from the JS API: a seed, a fault, or an option. A programmer error. */
235
+ export class McpEmulatorInputInvalid extends Data.TaggedError('McpEmulatorInputInvalid')<{
236
+ readonly input: StatefulInputKind
237
+ readonly reason: string
238
+ }> {
239
+ override get message(): string {
240
+ return `Invalid MCP emulator ${this.input}: ${this.reason}`
241
+ }
242
+ }
243
+
244
+ export type McpEmulatorOptions = {
245
+ /** Typed seed; defaults to the one-page modern listing (sessions are never seeded). */
246
+ readonly seed?: McpEmulatorSeed
247
+ /** Drill knobs (tests only): make the emulator disagree with one conformance claim. */
248
+ readonly drills?: McpEmulatorDrills
249
+ }
250
+
251
+ export type McpEmulator = StatefulEmulatorApi<McpEmulatorState, McpEmulatorSeed, McpFault>
252
+
253
+ const inputInvalid = (input: StatefulInputKind, reason: string) =>
254
+ new McpEmulatorInputInvalid({ input, reason })
255
+
256
+ /** The constant reason of a request on no emulated route shape. */
257
+ const unrecognisedReason = 'no emulated MCP route for this method and path'
258
+
259
+ /** The constant reason of a request whose `Authorization` header is not one recognisable bearer. */
260
+ const unrecognisedAuthorizationReason = 'an unrecognisable Authorization header is not emulated'
261
+
262
+ /**
263
+ * Create a stateful MCP emulator on the `@emulators/core` custom runtime. Each call has its own
264
+ * state, ledger, faults, and session counter. Rejects with `McpEmulatorInputInvalid` for an
265
+ * invalid seed or option. See `src/stateful-emulator.ts` for the request precedence.
266
+ */
267
+ export const makeMcpEmulator = async (options: McpEmulatorOptions = {}): Promise<McpEmulator> => {
268
+ const initial = buildSeedState(options.seed ?? {})
269
+
270
+ if (Predicate.isString(initial)) {
271
+ throw inputInvalid('seed', initial)
272
+ }
273
+
274
+ checkBooleanDrills(options.drills, mcpEmulatorDrillKnobs, inputInvalid)
275
+
276
+ // The reserved invalid credential must reach the routes as a recognisable bearer's digest; a
277
+ // value the bearer rule refused would never be answered its recorded 401.
278
+ if (!isRecognisableBearerValue(mcpEmulatorReservedInvalidCredential)) {
279
+ throw new Error('the reserved invalid MCP credential is not a recognisable bearer')
280
+ }
281
+
282
+ // The Afloat profile guards the remainder after `afloat_`: it must be recognisable instead.
283
+ const afloatReservedRemainder = mcpEmulatorAfloatReservedInvalidCredential.slice(
284
+ mcpEmulatorAfloatKeyPrefix.length
285
+ )
286
+
287
+ if (
288
+ !mcpEmulatorAfloatReservedInvalidCredential.startsWith(mcpEmulatorAfloatKeyPrefix) ||
289
+ !isRecognisableBearerValue(afloatReservedRemainder)
290
+ ) {
291
+ throw new Error('the reserved invalid Afloat credential has no recognisable remainder')
292
+ }
293
+
294
+ // Id substitution re-serialises the response message: a recording copied in a non-canonical
295
+ // JSON form would answer other bytes, so it fails here, loudly.
296
+ const recordingProblems = mcpRecordingProblems([
297
+ ...mcpEmulatorFixtures,
298
+ ...mcpEmulatorAfloatFixtures
299
+ ])
300
+
301
+ if (recordingProblems.length > 0) {
302
+ throw new Error(`non-canonical MCP recordings: ${recordingProblems.join('; ')}`)
303
+ }
304
+
305
+ const drills = options.drills ?? {}
306
+ const runtime = makeMcpRuntime()
307
+
308
+ const env: McpApiEnv = {
309
+ drills: {
310
+ discoverCarriesErrorResponse: drills.discoverCarriesErrorResponse === true,
311
+ discoverWithoutResultType: drills.discoverWithoutResultType === true,
312
+ sessionIdNotVisibleAscii: drills.sessionIdNotVisibleAscii === true,
313
+ discoverAnsweredTwice: drills.discoverAnsweredTwice === true,
314
+ writeToolMarkedReadOnly: drills.writeToolMarkedReadOnly === true,
315
+ readCallAnswersToolError: drills.readCallAnswersToolError === true,
316
+ invalidCallAnswersRpcError: drills.invalidCallAnswersRpcError === true,
317
+ absentCallAnswersResult: drills.absentCallAnswersResult === true,
318
+ unauthorizedWithoutChallenge: drills.unauthorizedWithoutChallenge === true
319
+ },
320
+ reservedDigest: mcpBearerDigest(mcpEmulatorReservedInvalidCredential, mcpEmulatorOrigin),
321
+ afloatReservedDigest: mcpBearerDigest(afloatReservedRemainder, mcpEmulatorAfloatOrigin),
322
+ runtime
323
+ }
324
+
325
+ return makeChunkedStatefulEmulator<McpEmulatorState, McpApiEnv, McpEmulatorSeed>(
326
+ {
327
+ routes: mcpApiRoutes,
328
+ env,
329
+ initial,
330
+ buildSeed: buildSeedState,
331
+ recordHeaders: [
332
+ { name: 'accept', json: false },
333
+ { name: 'content-type', json: false },
334
+ { name: 'mcp-method', json: false },
335
+ { name: 'mcp-name', json: false },
336
+ { name: 'mcp-protocol-version', json: false },
337
+ { name: 'mcp-session-id', json: false }
338
+ ],
339
+ failClosed: {
340
+ unrecognised: unrecognisedReason,
341
+ unrecognisedAuthorization: unrecognisedAuthorizationReason
342
+ },
343
+ bearerDigest: mcpBearerDigest,
344
+ bearerPrefixes: { [mcpEmulatorAfloatOrigin]: mcpEmulatorAfloatKeyPrefix },
345
+ constantRefusals: true,
346
+ guardAllHeaders: true,
347
+ guardOutput: true,
348
+ uniqueJsonKeys: true,
349
+ // Every reset and seed starts a cursor generation; the session counter never resets.
350
+ clearRuntime: () => {
351
+ runtime.generation += 1
352
+ runtime.issuedCursor = undefined
353
+ },
354
+ runtimeState: () => ({
355
+ nextSession: runtime.nextSession,
356
+ cursorGeneration: runtime.generation,
357
+ issuedCursor: runtime.issuedCursor ?? null
358
+ }),
359
+ seedSummary: state => ({ modernListing: state.modernListing }),
360
+ inputInvalid
361
+ },
362
+ statefulCoreRuntime({ name: 'mcp', initial, decodeState, inputInvalid })
363
+ )
364
+ }