agent-recall-mcp 3.5.2 → 3.5.4

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 (219) hide show
  1. package/README.md +254 -143
  2. package/dist/build-server.d.ts +28 -0
  3. package/dist/build-server.d.ts.map +1 -0
  4. package/dist/build-server.js +55 -0
  5. package/dist/build-server.js.map +1 -0
  6. package/dist/http/activity.d.ts +60 -0
  7. package/dist/http/activity.d.ts.map +1 -0
  8. package/dist/http/activity.js +254 -0
  9. package/dist/http/activity.js.map +1 -0
  10. package/dist/http/alerts.d.ts +84 -0
  11. package/dist/http/alerts.d.ts.map +1 -0
  12. package/dist/http/alerts.js +213 -0
  13. package/dist/http/alerts.js.map +1 -0
  14. package/dist/http/cli.d.ts +3 -0
  15. package/dist/http/cli.d.ts.map +1 -0
  16. package/dist/http/cli.js +515 -0
  17. package/dist/http/cli.js.map +1 -0
  18. package/dist/http/export-tar.d.ts +23 -0
  19. package/dist/http/export-tar.d.ts.map +1 -0
  20. package/dist/http/export-tar.js +264 -0
  21. package/dist/http/export-tar.js.map +1 -0
  22. package/dist/http/federation.d.ts +45 -0
  23. package/dist/http/federation.d.ts.map +1 -0
  24. package/dist/http/federation.js +185 -0
  25. package/dist/http/federation.js.map +1 -0
  26. package/dist/http/film/film.css +80 -0
  27. package/dist/http/film/film.js +446 -0
  28. package/dist/http/film/human.jpg +0 -0
  29. package/dist/http/film/m0.jpg +0 -0
  30. package/dist/http/film/m2.jpg +0 -0
  31. package/dist/http/film/m3.jpg +0 -0
  32. package/dist/http/film/wrong.jpg +0 -0
  33. package/dist/http/film.d.ts +16 -0
  34. package/dist/http/film.d.ts.map +1 -0
  35. package/dist/http/film.js +119 -0
  36. package/dist/http/film.js.map +1 -0
  37. package/dist/http/home/cabinet.svg +1 -0
  38. package/dist/http/home/drawer-project.svg +1 -0
  39. package/dist/http/home/drawer-rules.svg +1 -0
  40. package/dist/http/home/drawer-you.svg +1 -0
  41. package/dist/http/home/fig1.svg +242 -0
  42. package/dist/http/home/fig2-1.svg +61 -0
  43. package/dist/http/home/fig2-2.svg +92 -0
  44. package/dist/http/home/fig3.svg +1 -0
  45. package/dist/http/home/home.css +509 -0
  46. package/dist/http/home/home.html +517 -0
  47. package/dist/http/home/icons.svg +15 -0
  48. package/dist/http/home.d.ts +23 -0
  49. package/dist/http/home.d.ts.map +1 -0
  50. package/dist/http/home.js +295 -0
  51. package/dist/http/home.js.map +1 -0
  52. package/dist/http/identities.d.ts +29 -0
  53. package/dist/http/identities.d.ts.map +1 -0
  54. package/dist/http/identities.js +91 -0
  55. package/dist/http/identities.js.map +1 -0
  56. package/dist/http/import-memory.d.ts +161 -0
  57. package/dist/http/import-memory.d.ts.map +1 -0
  58. package/dist/http/import-memory.js +718 -0
  59. package/dist/http/import-memory.js.map +1 -0
  60. package/dist/http/jsonfile.d.ts +6 -0
  61. package/dist/http/jsonfile.d.ts.map +1 -0
  62. package/dist/http/jsonfile.js +60 -0
  63. package/dist/http/jsonfile.js.map +1 -0
  64. package/dist/http/legal/PRIVACY.md +70 -0
  65. package/dist/http/legal.d.ts +10 -0
  66. package/dist/http/legal.d.ts.map +1 -0
  67. package/dist/http/legal.js +35 -0
  68. package/dist/http/legal.js.map +1 -0
  69. package/dist/http/limits.d.ts +59 -0
  70. package/dist/http/limits.d.ts.map +1 -0
  71. package/dist/http/limits.js +163 -0
  72. package/dist/http/limits.js.map +1 -0
  73. package/dist/http/markdown-lite.d.ts +2 -0
  74. package/dist/http/markdown-lite.d.ts.map +1 -0
  75. package/dist/http/markdown-lite.js +86 -0
  76. package/dist/http/markdown-lite.js.map +1 -0
  77. package/dist/http/multipart.d.ts +43 -0
  78. package/dist/http/multipart.d.ts.map +1 -0
  79. package/dist/http/multipart.js +152 -0
  80. package/dist/http/multipart.js.map +1 -0
  81. package/dist/http/oauth-app.d.ts +75 -0
  82. package/dist/http/oauth-app.d.ts.map +1 -0
  83. package/dist/http/oauth-app.js +259 -0
  84. package/dist/http/oauth-app.js.map +1 -0
  85. package/dist/http/oauth-config.d.ts +46 -0
  86. package/dist/http/oauth-config.d.ts.map +1 -0
  87. package/dist/http/oauth-config.js +122 -0
  88. package/dist/http/oauth-config.js.map +1 -0
  89. package/dist/http/oauth-pages.d.ts +40 -0
  90. package/dist/http/oauth-pages.d.ts.map +1 -0
  91. package/dist/http/oauth-pages.js +97 -0
  92. package/dist/http/oauth-pages.js.map +1 -0
  93. package/dist/http/oauth-provider.d.ts +124 -0
  94. package/dist/http/oauth-provider.d.ts.map +1 -0
  95. package/dist/http/oauth-provider.js +486 -0
  96. package/dist/http/oauth-provider.js.map +1 -0
  97. package/dist/http/oauth-store.d.ts +128 -0
  98. package/dist/http/oauth-store.d.ts.map +1 -0
  99. package/dist/http/oauth-store.js +317 -0
  100. package/dist/http/oauth-store.js.map +1 -0
  101. package/dist/http/redirect-policy.d.ts +16 -0
  102. package/dist/http/redirect-policy.d.ts.map +1 -0
  103. package/dist/http/redirect-policy.js +83 -0
  104. package/dist/http/redirect-policy.js.map +1 -0
  105. package/dist/http/review-pages.d.ts +39 -0
  106. package/dist/http/review-pages.d.ts.map +1 -0
  107. package/dist/http/review-pages.js +78 -0
  108. package/dist/http/review-pages.js.map +1 -0
  109. package/dist/http/review.d.ts +36 -0
  110. package/dist/http/review.d.ts.map +1 -0
  111. package/dist/http/review.js +220 -0
  112. package/dist/http/review.js.map +1 -0
  113. package/dist/http/serve.d.ts +58 -0
  114. package/dist/http/serve.d.ts.map +1 -0
  115. package/dist/http/serve.js +324 -0
  116. package/dist/http/serve.js.map +1 -0
  117. package/dist/http/site-pages.d.ts +110 -0
  118. package/dist/http/site-pages.d.ts.map +1 -0
  119. package/dist/http/site-pages.js +630 -0
  120. package/dist/http/site-pages.js.map +1 -0
  121. package/dist/http/site-theme.d.ts +13 -0
  122. package/dist/http/site-theme.d.ts.map +1 -0
  123. package/dist/http/site-theme.js +22 -0
  124. package/dist/http/site-theme.js.map +1 -0
  125. package/dist/http/site.d.ts +52 -0
  126. package/dist/http/site.d.ts.map +1 -0
  127. package/dist/http/site.js +353 -0
  128. package/dist/http/site.js.map +1 -0
  129. package/dist/http/stats.d.ts +139 -0
  130. package/dist/http/stats.d.ts.map +1 -0
  131. package/dist/http/stats.js +599 -0
  132. package/dist/http/stats.js.map +1 -0
  133. package/dist/http/tar-import.d.ts +69 -0
  134. package/dist/http/tar-import.d.ts.map +1 -0
  135. package/dist/http/tar-import.js +234 -0
  136. package/dist/http/tar-import.js.map +1 -0
  137. package/dist/http/tenant-paths.d.ts +14 -0
  138. package/dist/http/tenant-paths.d.ts.map +1 -0
  139. package/dist/http/tenant-paths.js +42 -0
  140. package/dist/http/tenant-paths.js.map +1 -0
  141. package/dist/http/tokens.d.ts +32 -0
  142. package/dist/http/tokens.d.ts.map +1 -0
  143. package/dist/http/tokens.js +137 -0
  144. package/dist/http/tokens.js.map +1 -0
  145. package/dist/http/trial.d.ts +55 -0
  146. package/dist/http/trial.d.ts.map +1 -0
  147. package/dist/http/trial.js +218 -0
  148. package/dist/http/trial.js.map +1 -0
  149. package/dist/http/web-session.d.ts +108 -0
  150. package/dist/http/web-session.d.ts.map +1 -0
  151. package/dist/http/web-session.js +267 -0
  152. package/dist/http/web-session.js.map +1 -0
  153. package/dist/index.js +12 -65
  154. package/dist/index.js.map +1 -1
  155. package/dist/lib/ambient-capture.d.ts.map +1 -1
  156. package/dist/lib/ambient-capture.js +4 -1
  157. package/dist/lib/ambient-capture.js.map +1 -1
  158. package/dist/lib/bookkeeping.d.ts +26 -0
  159. package/dist/lib/bookkeeping.d.ts.map +1 -0
  160. package/dist/lib/bookkeeping.js +31 -0
  161. package/dist/lib/bookkeeping.js.map +1 -0
  162. package/dist/lib/hosted-redact.d.ts +17 -0
  163. package/dist/lib/hosted-redact.d.ts.map +1 -0
  164. package/dist/lib/hosted-redact.js +57 -0
  165. package/dist/lib/hosted-redact.js.map +1 -0
  166. package/dist/lib/lifecycle-exit.d.ts +5 -13
  167. package/dist/lib/lifecycle-exit.d.ts.map +1 -1
  168. package/dist/lib/lifecycle-exit.js +38 -16
  169. package/dist/lib/lifecycle-exit.js.map +1 -1
  170. package/dist/server.d.ts +3 -2
  171. package/dist/server.d.ts.map +1 -1
  172. package/dist/server.js +6 -3
  173. package/dist/server.js.map +1 -1
  174. package/dist/tools/annotations.d.ts +65 -0
  175. package/dist/tools/annotations.d.ts.map +1 -0
  176. package/dist/tools/annotations.js +4 -0
  177. package/dist/tools/annotations.js.map +1 -0
  178. package/dist/tools/check-action.d.ts.map +1 -1
  179. package/dist/tools/check-action.js +2 -0
  180. package/dist/tools/check-action.js.map +1 -1
  181. package/dist/tools/check.d.ts.map +1 -1
  182. package/dist/tools/check.js +6 -2
  183. package/dist/tools/check.js.map +1 -1
  184. package/dist/tools/digest.d.ts.map +1 -1
  185. package/dist/tools/digest.js +2 -0
  186. package/dist/tools/digest.js.map +1 -1
  187. package/dist/tools/pipeline-close.d.ts.map +1 -1
  188. package/dist/tools/pipeline-close.js +2 -0
  189. package/dist/tools/pipeline-close.js.map +1 -1
  190. package/dist/tools/pipeline-current.d.ts.map +1 -1
  191. package/dist/tools/pipeline-current.js +2 -0
  192. package/dist/tools/pipeline-current.js.map +1 -1
  193. package/dist/tools/pipeline-list.d.ts.map +1 -1
  194. package/dist/tools/pipeline-list.js +2 -0
  195. package/dist/tools/pipeline-list.js.map +1 -1
  196. package/dist/tools/pipeline-open.d.ts.map +1 -1
  197. package/dist/tools/pipeline-open.js +2 -0
  198. package/dist/tools/pipeline-open.js.map +1 -1
  199. package/dist/tools/pipeline-show.d.ts.map +1 -1
  200. package/dist/tools/pipeline-show.js +2 -0
  201. package/dist/tools/pipeline-show.js.map +1 -1
  202. package/dist/tools/recall.d.ts.map +1 -1
  203. package/dist/tools/recall.js +4 -1
  204. package/dist/tools/recall.js.map +1 -1
  205. package/dist/tools/register-rule.d.ts.map +1 -1
  206. package/dist/tools/register-rule.js +2 -0
  207. package/dist/tools/register-rule.js.map +1 -1
  208. package/dist/tools/remember.d.ts.map +1 -1
  209. package/dist/tools/remember.js +10 -1
  210. package/dist/tools/remember.js.map +1 -1
  211. package/dist/tools/session-end.d.ts +15 -0
  212. package/dist/tools/session-end.d.ts.map +1 -1
  213. package/dist/tools/session-end.js +13 -1
  214. package/dist/tools/session-end.js.map +1 -1
  215. package/dist/tools/session-start.d.ts +6 -1
  216. package/dist/tools/session-start.d.ts.map +1 -1
  217. package/dist/tools/session-start.js +24 -212
  218. package/dist/tools/session-start.js.map +1 -1
  219. package/package.json +11 -8
@@ -0,0 +1,28 @@
1
+ /**
2
+ * build-server.ts — the ONE place that assembles an AgentRecall MCP server.
3
+ *
4
+ * Both entry points use it:
5
+ * - index.ts (stdio, one local user per process): tier from the host env,
6
+ * ambient capture on.
7
+ * - http/serve.ts (hosted, many tenants per process): a fresh server per
8
+ * request, always Tier B (a remote client has no AgentRecall hooks), ambient
9
+ * capture off.
10
+ * Registration order and the tool surface are identical, so the default
11
+ * surface, --full and AR_EXTRAS behave the same everywhere.
12
+ */
13
+ import type { HostTier } from "agent-recall-core";
14
+ import { type ServerType } from "./server.js";
15
+ export interface BuildServerOptions {
16
+ /** Lifecycle tier → MCP instructions text. Hosted is always "B". */
17
+ tier: HostTier;
18
+ /** --full: adds check_action. */
19
+ full: boolean;
20
+ /** AR_EXTRAS=1 with --full: quarantined extras. */
21
+ extras: boolean;
22
+ /** Passive per-call working-memory capture (C-1). Off for hosted. */
23
+ ambientCapture: boolean;
24
+ /** Hosted only: scrub the tenant root from every tool/resource/prompt result and error. */
25
+ redactPaths?: boolean;
26
+ }
27
+ export declare function buildServer(opts: BuildServerOptions): ServerType;
28
+ //# sourceMappingURL=build-server.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"build-server.d.ts","sourceRoot":"","sources":["../src/build-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAsB/D,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,IAAI,EAAE,QAAQ,CAAC;IACf,iCAAiC;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,mDAAmD;IACnD,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,cAAc,EAAE,OAAO,CAAC;IACxB,2FAA2F;IAC3F,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,UAAU,CAqChE"}
@@ -0,0 +1,55 @@
1
+ import { createMcpServer } from "./server.js";
2
+ import { installBookkeeping } from "./lib/bookkeeping.js";
3
+ import { installAmbientCapture } from "./lib/ambient-capture.js";
4
+ import { installHostedRedaction } from "./lib/hosted-redact.js";
5
+ import { register as registerSessionStart } from "./tools/session-start.js";
6
+ import { register as registerRemember } from "./tools/remember.js";
7
+ import { register as registerRecall } from "./tools/recall.js";
8
+ import { register as registerSessionEnd } from "./tools/session-end.js";
9
+ import { register as registerCheck } from "./tools/check.js";
10
+ import { register as registerCheckAction } from "./tools/check-action.js";
11
+ import { register as registerPipelineOpen } from "./tools/pipeline-open.js";
12
+ import { register as registerPipelineClose } from "./tools/pipeline-close.js";
13
+ import { register as registerPipelineList } from "./tools/pipeline-list.js";
14
+ import { register as registerPipelineCurrent } from "./tools/pipeline-current.js";
15
+ import { register as registerPipelineShow } from "./tools/pipeline-show.js";
16
+ import { register as registerRegisterRule } from "./tools/register-rule.js";
17
+ import { register as registerDigest } from "./tools/digest.js";
18
+ import { register as registerJournalResources } from "./resources/journal-resources.js";
19
+ import { register as registerAwarenessResource } from "./resources/awareness-resource.js";
20
+ import { register as registerSessionPrompts } from "./prompts/session-prompts.js";
21
+ export function buildServer(opts) {
22
+ const server = createMcpServer(opts.tier);
23
+ // Read-only tools queue their bookkeeping, write tools apply it. First, so it is the outermost wrapper.
24
+ installBookkeeping(server);
25
+ // C-1 — must wrap registerTool BEFORE any registration (see ambient-capture.ts).
26
+ if (opts.ambientCapture)
27
+ installAmbientCapture(server);
28
+ // Hosted backstop — also before any registration (see lib/hosted-redact.ts).
29
+ if (opts.redactPaths)
30
+ installHostedRedaction(server);
31
+ // Default surface: 5 tools (Automaticity Law — every extra tool costs tokens every session).
32
+ registerSessionStart(server);
33
+ registerSessionEnd(server);
34
+ registerRemember(server);
35
+ registerRecall(server);
36
+ registerCheck(server);
37
+ if (opts.full) {
38
+ registerCheckAction(server);
39
+ }
40
+ // AR_EXTRAS quarantine zone (purity-census-2026-07-05).
41
+ if (opts.full && opts.extras) {
42
+ registerPipelineOpen(server);
43
+ registerPipelineClose(server);
44
+ registerPipelineList(server);
45
+ registerPipelineCurrent(server);
46
+ registerPipelineShow(server);
47
+ registerRegisterRule(server);
48
+ registerDigest(server);
49
+ }
50
+ registerJournalResources(server);
51
+ registerAwarenessResource(server);
52
+ registerSessionPrompts(server);
53
+ return server;
54
+ }
55
+ //# sourceMappingURL=build-server.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"build-server.js","sourceRoot":"","sources":["../src/build-server.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,eAAe,EAAmB,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,QAAQ,IAAI,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,QAAQ,IAAI,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,QAAQ,IAAI,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,QAAQ,IAAI,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,QAAQ,IAAI,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,QAAQ,IAAI,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AACxF,OAAO,EAAE,QAAQ,IAAI,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC1F,OAAO,EAAE,QAAQ,IAAI,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAelF,MAAM,UAAU,WAAW,CAAC,IAAwB;IAClD,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE1C,wGAAwG;IACxG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,iFAAiF;IACjF,IAAI,IAAI,CAAC,cAAc;QAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACvD,6EAA6E;IAC7E,IAAI,IAAI,CAAC,WAAW;QAAE,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAErD,6FAA6F;IAC7F,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7B,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3B,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,cAAc,CAAC,MAAM,CAAC,CAAC;IACvB,aAAa,CAAC,MAAM,CAAC,CAAC;IAEtB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,wDAAwD;IACxD,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC7B,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC9B,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC7B,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAChC,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC7B,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC7B,cAAc,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC;IAED,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAClC,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAE/B,OAAO,MAAM,CAAC;AAChB,CAAC"}
@@ -0,0 +1,60 @@
1
+ export declare const CLIENT_NAME_MAX = 60;
2
+ /** The hosted tool names (tier B, with and without --full). Anything else is not recorded. */
3
+ export declare const TOOL_NAMES: ReadonlySet<string>;
4
+ export interface ActivityEntry {
5
+ client: string;
6
+ first_seen: string;
7
+ last_seen: string;
8
+ /** ISO time of the last tools/call; absent until one is made (and on entries saved before this field). */
9
+ last_call?: string;
10
+ last_tool?: string;
11
+ calls: number;
12
+ }
13
+ export interface ActivityObservation {
14
+ client?: string;
15
+ tool?: string;
16
+ toolCalls: number;
17
+ }
18
+ /** Control, bidi and zero-width characters out; whitespace collapsed; capped. */
19
+ export declare function sanitizeClientName(raw: unknown): string | null;
20
+ /** What one parsed JSON-RPC body tells us: the client's name (initialize) and tool calls. */
21
+ export declare function observe(body: unknown): ActivityObservation;
22
+ export interface ActivityOptions {
23
+ now?: () => number;
24
+ log?: (line: string) => void;
25
+ flushMs?: number;
26
+ /** Test seam: replaces the atomic file write. */
27
+ write?: (file: string, data: unknown) => void;
28
+ /** Called on every failed write (the server raises a rate-limited alert). Must not throw. */
29
+ onWriteError?: (err: unknown) => void;
30
+ }
31
+ export declare class ActivityStore {
32
+ private readonly dataDir;
33
+ private readonly slots;
34
+ private timer;
35
+ private warned;
36
+ private failures;
37
+ private readonly now;
38
+ private readonly log;
39
+ private readonly flushMs;
40
+ private readonly write;
41
+ private readonly onWriteError;
42
+ constructor(dataDir: string, opts?: ActivityOptions);
43
+ /** Where a user's activity lives. Outside the tenant directory on purpose. */
44
+ fileFor(uid: string): string;
45
+ /** The user's slot, loaded once (one small read, size-capped). null = the file could not be read for a reason other than "absent/corrupt": do not touch it this round. */
46
+ private slot;
47
+ private schedule;
48
+ /** Record one authenticated request. Memory only; never throws. True when this credential was never seen before (a newly connected agent). */
49
+ record(uid: string, key: string, obs: ActivityObservation): boolean;
50
+ /** A copy of this user's entries (callers sort and filter by live credential). Never throws. */
51
+ entriesOf(uid: string): Record<string, ActivityEntry>;
52
+ /**
53
+ * Write dirty users. The timer writes at most FLUSH_BATCH per tick (the rest follow on the next tick);
54
+ * `all` (shutdown) writes everyone. A slot whose file an operator deleted is dropped, not recreated.
55
+ * Never throws.
56
+ */
57
+ flush(all?: boolean): void;
58
+ private complain;
59
+ }
60
+ //# sourceMappingURL=activity.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../src/http/activity.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,eAAe,KAAK,CAAC;AAIlC,8FAA8F;AAC9F,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CAA4F,CAAC;AAExI,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,0GAA0G;IAC1G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAAG,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AAM1F,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAS9D;AAED,6FAA6F;AAC7F,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,CAgB1D;AAqBD,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9C,6FAA6F;IAC7F,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACvC;AASD,qBAAa,aAAa;IAWZ,OAAO,CAAC,QAAQ,CAAC,OAAO;IAVpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAyB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwC;IAC9D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;gBAEzB,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB;IAQxE,8EAA8E;IAC9E,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAK5B,0KAA0K;IAC1K,OAAO,CAAC,IAAI;IA4BZ,OAAO,CAAC,QAAQ;IAOhB,8IAA8I;IAC9I,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,GAAG,OAAO;IA6BnE,gGAAgG;IAChG,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAUrD;;;;OAIG;IACH,KAAK,CAAC,GAAG,UAAO,GAAG,IAAI;IAyBvB,OAAO,CAAC,QAAQ;CAKjB"}
@@ -0,0 +1,254 @@
1
+ /**
2
+ * activity.ts — which agents actually used a user's memory, and when.
3
+ *
4
+ * One small file per user: <dataDir>/_server/activity/<uid>.json. It lives
5
+ * outside tenants/<uid>/, so it does not count toward the storage quota and is
6
+ * not part of "Download my memory". Entries are keyed by credential
7
+ * ("grant:<id>" for OAuth, "token:<id>" for an operator token), not by
8
+ * anything the client says, so a client cannot forge or merge rows; the
9
+ * self-reported client name is display text only.
10
+ *
11
+ * Stored per agent: client name, first/last seen, when it last made a tool call
12
+ * (last_call: initialize and tools/list do not move it), last tool NAME, count of
13
+ * tool calls. Never request content, arguments, IPs or tokens.
14
+ *
15
+ * Writes are write-behind: recorded in memory, flushed at most once per
16
+ * flushMs (default 60 s) and on shutdown. A failed write never fails a request
17
+ * (logged once; the entries stay dirty and are retried).
18
+ */
19
+ import * as fs from "node:fs";
20
+ import * as path from "node:path";
21
+ import { CREDENTIAL_ID_RE } from "agent-recall-core";
22
+ import { UID_RE } from "./tokens.js";
23
+ import { writeJsonAtomic } from "./jsonfile.js";
24
+ export const CLIENT_NAME_MAX = 60;
25
+ const MAX_ENTRIES_PER_UID = 50;
26
+ const MAX_UIDS_IN_MEMORY = 10_000;
27
+ const DEFAULT_FLUSH_MS = 60_000;
28
+ /** The hosted tool names (tier B, with and without --full). Anything else is not recorded. */
29
+ export const TOOL_NAMES = new Set(["session_start", "session_end", "remember", "recall", "check", "check_action"]);
30
+ /** Zero-width, bidi, line/paragraph separator, BOM and ALM code points (built from numbers so no invisible characters live in this file). */
31
+ const INVISIBLE = new RegExp("[" + [[0x200b, 0x200f], [0x2028, 0x202e], [0x2060, 0x2069], [0xfeff, 0xfeff], [0x061c, 0x061c]]
32
+ .map(([a, b]) => String.fromCharCode(a) + "-" + String.fromCharCode(b)).join("") + "]", "g");
33
+ /** Control, bidi and zero-width characters out; whitespace collapsed; capped. */
34
+ export function sanitizeClientName(raw) {
35
+ if (typeof raw !== "string")
36
+ return null;
37
+ const s = raw
38
+ .replace(INVISIBLE, "")
39
+ .replace(/[\p{Cc}\p{Cf}]/gu, " ")
40
+ .replace(/\s+/g, " ")
41
+ .trim();
42
+ const capped = Array.from(s).slice(0, CLIENT_NAME_MAX).join("").trim();
43
+ return capped === "" ? null : capped;
44
+ }
45
+ /** What one parsed JSON-RPC body tells us: the client's name (initialize) and tool calls. */
46
+ export function observe(body) {
47
+ const out = { toolCalls: 0 };
48
+ for (const m of Array.isArray(body) ? body.slice(0, 100) : [body]) {
49
+ if (m === null || typeof m !== "object")
50
+ continue;
51
+ const { method, params } = m;
52
+ const p = (params !== null && typeof params === "object" ? params : {});
53
+ if (method === "initialize") {
54
+ const info = p.clientInfo;
55
+ const name = info !== null && typeof info === "object" ? sanitizeClientName(info.name) : null;
56
+ if (name !== null)
57
+ out.client = name;
58
+ }
59
+ else if (method === "tools/call") {
60
+ out.toolCalls++;
61
+ if (typeof p.name === "string" && TOOL_NAMES.has(p.name))
62
+ out.tool = p.name;
63
+ }
64
+ }
65
+ return out;
66
+ }
67
+ function parseEntries(raw) {
68
+ const out = {};
69
+ const src = raw?.entries;
70
+ if (src === null || typeof src !== "object")
71
+ return out;
72
+ for (const [k, v] of Object.entries(src)) {
73
+ const e = v;
74
+ if (!CREDENTIAL_ID_RE.test(k) || !e || typeof e.first_seen !== "string" || typeof e.last_seen !== "string")
75
+ continue;
76
+ out[k] = {
77
+ client: sanitizeClientName(e.client) ?? "Unknown client",
78
+ first_seen: e.first_seen,
79
+ last_seen: e.last_seen,
80
+ last_call: typeof e.last_call === "string" ? e.last_call : undefined,
81
+ last_tool: typeof e.last_tool === "string" && TOOL_NAMES.has(e.last_tool) ? e.last_tool : undefined,
82
+ calls: Number.isSafeInteger(e.calls) && e.calls >= 0 ? e.calls : 0,
83
+ };
84
+ }
85
+ return out;
86
+ }
87
+ const MAX_FILE_BYTES = 256 * 1024; // 50 entries are ~10 KB; anything bigger is not ours
88
+ const FLUSH_BATCH = 200; // uids written per timer tick
89
+ const MAX_BACKOFF_MS = 15 * 60_000;
90
+ export class ActivityStore {
91
+ dataDir;
92
+ slots = new Map();
93
+ timer = null;
94
+ warned = false;
95
+ failures = 0;
96
+ now;
97
+ log;
98
+ flushMs;
99
+ write;
100
+ onWriteError;
101
+ constructor(dataDir, opts = {}) {
102
+ this.dataDir = dataDir;
103
+ this.now = opts.now ?? Date.now;
104
+ this.log = opts.log ?? (() => { });
105
+ this.flushMs = opts.flushMs ?? DEFAULT_FLUSH_MS;
106
+ this.write = opts.write ?? writeJsonAtomic;
107
+ this.onWriteError = opts.onWriteError ?? (() => { });
108
+ }
109
+ /** Where a user's activity lives. Outside the tenant directory on purpose. */
110
+ fileFor(uid) {
111
+ if (!UID_RE.test(uid))
112
+ throw new Error("invalid uid");
113
+ return path.join(this.dataDir, "_server", "activity", `${uid}.json`);
114
+ }
115
+ /** The user's slot, loaded once (one small read, size-capped). null = the file could not be read for a reason other than "absent/corrupt": do not touch it this round. */
116
+ slot(uid) {
117
+ let s = this.slots.get(uid);
118
+ if (s)
119
+ return s;
120
+ if (this.slots.size >= MAX_UIDS_IN_MEMORY) {
121
+ this.flush(true);
122
+ for (const [k, v] of this.slots)
123
+ if (!v.dirty)
124
+ this.slots.delete(k);
125
+ if (this.slots.size >= MAX_UIDS_IN_MEMORY) {
126
+ const oldest = this.slots.keys().next().value; // Map keeps insertion order: the longest-resident slot
127
+ if (oldest !== undefined)
128
+ this.slots.delete(oldest);
129
+ }
130
+ }
131
+ let entries = {};
132
+ let onDisk = false;
133
+ const file = this.fileFor(uid);
134
+ try {
135
+ if (fs.statSync(file).size > MAX_FILE_BYTES)
136
+ throw new SyntaxError("activity file too large");
137
+ entries = parseEntries(JSON.parse(fs.readFileSync(file, "utf-8")));
138
+ onDisk = true;
139
+ }
140
+ catch (err) {
141
+ const code = err?.code;
142
+ if (code !== undefined && code !== "ENOENT") {
143
+ this.complain(err);
144
+ return null;
145
+ } // EACCES, EIO, ...: leave the file alone
146
+ // ENOENT: none yet. Parse failure (no code): corrupt, start over.
147
+ }
148
+ s = { entries, dirty: false, onDisk };
149
+ this.slots.set(uid, s);
150
+ return s;
151
+ }
152
+ schedule() {
153
+ if (this.timer !== null)
154
+ return;
155
+ const wait = Math.min(MAX_BACKOFF_MS, this.flushMs * 2 ** Math.min(this.failures, 10)); // back off while writes fail
156
+ this.timer = setTimeout(() => { this.timer = null; this.flush(false); }, wait);
157
+ this.timer.unref();
158
+ }
159
+ /** Record one authenticated request. Memory only; never throws. True when this credential was never seen before (a newly connected agent). */
160
+ record(uid, key, obs) {
161
+ try {
162
+ if (!UID_RE.test(uid) || !CREDENTIAL_ID_RE.test(key))
163
+ return false;
164
+ const s = this.slot(uid);
165
+ if (s === null)
166
+ return false;
167
+ const at = new Date(this.now()).toISOString();
168
+ const prev = s.entries[key];
169
+ s.entries[key] = {
170
+ client: obs.client ?? prev?.client ?? "Unknown client",
171
+ first_seen: prev?.first_seen ?? at,
172
+ last_seen: at,
173
+ last_call: obs.toolCalls > 0 ? at : prev?.last_call,
174
+ last_tool: obs.tool ?? prev?.last_tool,
175
+ calls: (prev?.calls ?? 0) + obs.toolCalls,
176
+ };
177
+ const keys = Object.keys(s.entries);
178
+ if (keys.length > MAX_ENTRIES_PER_UID) {
179
+ keys.sort((a, b) => s.entries[a].last_seen.localeCompare(s.entries[b].last_seen));
180
+ for (const k of keys.slice(0, keys.length - MAX_ENTRIES_PER_UID))
181
+ delete s.entries[k];
182
+ }
183
+ s.dirty = true;
184
+ this.schedule();
185
+ return prev === undefined;
186
+ }
187
+ catch (err) {
188
+ this.complain(err);
189
+ return false;
190
+ }
191
+ }
192
+ /** A copy of this user's entries (callers sort and filter by live credential). Never throws. */
193
+ entriesOf(uid) {
194
+ try {
195
+ const s = UID_RE.test(uid) ? this.slot(uid) : null;
196
+ return s ? structuredClone(s.entries) : {};
197
+ }
198
+ catch (err) {
199
+ this.complain(err);
200
+ return {};
201
+ }
202
+ }
203
+ /**
204
+ * Write dirty users. The timer writes at most FLUSH_BATCH per tick (the rest follow on the next tick);
205
+ * `all` (shutdown) writes everyone. A slot whose file an operator deleted is dropped, not recreated.
206
+ * Never throws.
207
+ */
208
+ flush(all = true) {
209
+ if (this.timer !== null) {
210
+ clearTimeout(this.timer);
211
+ this.timer = null;
212
+ }
213
+ let written = 0;
214
+ let more = false;
215
+ let failed = false;
216
+ for (const [uid, s] of this.slots) {
217
+ if (!s.dirty)
218
+ continue;
219
+ if (!all && written >= FLUSH_BATCH) {
220
+ more = true;
221
+ break;
222
+ }
223
+ written++;
224
+ try {
225
+ const file = this.fileFor(uid);
226
+ if (s.onDisk && !fs.existsSync(file)) {
227
+ this.slots.delete(uid);
228
+ continue;
229
+ } // deleted on purpose
230
+ this.write(file, { version: 1, entries: s.entries });
231
+ s.dirty = false;
232
+ s.onDisk = true;
233
+ }
234
+ catch (err) {
235
+ failed = true;
236
+ this.complain(err);
237
+ try {
238
+ this.onWriteError(err);
239
+ }
240
+ catch { /* reporting never breaks the flush */ }
241
+ }
242
+ }
243
+ this.failures = failed ? this.failures + 1 : 0;
244
+ if (failed || more)
245
+ this.schedule(); // keep the data, try again (backed off when failing)
246
+ }
247
+ complain(err) {
248
+ if (this.warned)
249
+ return;
250
+ this.warned = true;
251
+ this.log(`[agent-recall-server] agent activity not saved (retrying quietly): ${err?.message ?? String(err)}`);
252
+ }
253
+ }
254
+ //# sourceMappingURL=activity.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"activity.js","sourceRoot":"","sources":["../../src/http/activity.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,84 @@
1
+ /**
2
+ * alerts.ts — error alerts to the server owner through a Telegram bot.
3
+ *
4
+ * Off unless BOTH AR_ALERT_TELEGRAM_BOT_TOKEN and AR_ALERT_TELEGRAM_CHAT_ID are set
5
+ * (an empty value is unset) and well-formed. The only outbound host is
6
+ * api.telegram.org (the apiBase option exists for tests and is not reachable from
7
+ * the environment).
8
+ *
9
+ * At most one message per error kind per window (10 minutes), carrying the count
10
+ * since the last message; errors after a message are summed and sent when the
11
+ * window ends. A message holds the kind, the count, the route classes, the top
12
+ * stack frame inside our own code (package/file:line), the server version and
13
+ * the time. Never a uid, token, path parameter, body, memory content or the raw
14
+ * error message (it can contain user content).
15
+ *
16
+ * raise() is synchronous and never throws; the Telegram call runs in the
17
+ * background with a timeout, so a failing or slow Telegram never touches a
18
+ * request. A failed send keeps its count for the next window.
19
+ */
20
+ import { type InternalKind, type RouteClass } from "./stats.js";
21
+ export declare const ALERT_KINDS: readonly InternalKind[];
22
+ export declare const ALERT_WINDOW_MS: number;
23
+ export interface AlertConfig {
24
+ token: string;
25
+ chatId: string;
26
+ }
27
+ /** Read the two env vars. config null = alerts off; problem = why, when the operator set something wrong (never echoes a value). */
28
+ export declare function loadAlertConfig(env?: NodeJS.ProcessEnv): {
29
+ config: AlertConfig | null;
30
+ problem?: string;
31
+ };
32
+ /**
33
+ * The first stack frame inside our own packages, as `mcp-server/http/serve.js:212`.
34
+ * Only frame lines after the error's own message are read, so text inside the message
35
+ * (which can carry user content) can never be mistaken for a frame.
36
+ */
37
+ export declare function topFrame(err: unknown): string | undefined;
38
+ export interface AlerterOptions {
39
+ config: AlertConfig;
40
+ version?: string;
41
+ now?: () => number;
42
+ log?: (line: string) => void;
43
+ windowMs?: number;
44
+ timeoutMs?: number;
45
+ /** Test seam: Bot API origin (default https://api.telegram.org). Not settable from the environment. */
46
+ apiBase?: string;
47
+ /** Test seam. */
48
+ fetchImpl?: typeof fetch;
49
+ }
50
+ export interface SendResult {
51
+ ok: boolean;
52
+ reason?: string;
53
+ }
54
+ export declare class Alerter {
55
+ private readonly opts;
56
+ private readonly state;
57
+ private readonly pending;
58
+ private readonly kinds;
59
+ private readonly routeSet;
60
+ private readonly now;
61
+ private readonly log;
62
+ private readonly windowMs;
63
+ private readonly timeoutMs;
64
+ private readonly url;
65
+ private readonly fetchImpl;
66
+ private readonly version;
67
+ constructor(opts: AlerterOptions);
68
+ /** Count one error of `kind`; a message goes out now or when the kind's window ends. Synchronous, never throws. */
69
+ raise(kind: InternalKind, ctx?: {
70
+ route?: RouteClass;
71
+ err?: unknown;
72
+ }): void;
73
+ /** pump() from a timer or a settled send: an exception there must never become an uncaught one. */
74
+ private safePump;
75
+ private pump;
76
+ private text;
77
+ /** One message to the configured chat, plain text. Never throws; never logs the token or the URL. */
78
+ send(text: string): Promise<SendResult>;
79
+ /** Resolves when no send is in flight (tests, `alert test`). Timers waiting for a window are not awaited. */
80
+ idle(): Promise<void>;
81
+ }
82
+ /** The text `agent-recall-server alert test` sends. */
83
+ export declare function testAlertText(version: string, now: number): string;
84
+ //# sourceMappingURL=alerts.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"alerts.d.ts","sourceRoot":"","sources":["../../src/http/alerts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAiC,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/F,eAAO,MAAM,WAAW,EAAE,SAAS,YAAY,EAAmB,CAAC;AACnE,eAAO,MAAM,eAAe,QAAc,CAAC;AAmB3C,MAAM,WAAW,WAAW;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAE9D,oIAAoI;AACpI,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG;IAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAUtH;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAezD;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAWD,MAAM,WAAW,UAAU;IAAG,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE;AAE5D,qBAAa,OAAO;IAaN,OAAO,CAAC,QAAQ,CAAC,IAAI;IAZjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6C;IACnE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+C;IACxE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAyB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAEJ,IAAI,EAAE,cAAc;IAWjD,mHAAmH;IACnH,KAAK,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,GAAE;QAAE,KAAK,CAAC,EAAE,UAAU,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI;IAkBhF,mGAAmG;IACnG,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,IAAI;IAkCZ,OAAO,CAAC,IAAI;IAaZ,qGAAqG;IAC/F,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAkB7C,6GAA6G;IACvG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B;AAED,uDAAuD;AACvD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAElE"}