@lleverage-ai/agent-sdk 0.0.1

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 (327) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +2321 -0
  3. package/dist/agent.d.ts +52 -0
  4. package/dist/agent.d.ts.map +1 -0
  5. package/dist/agent.js +2122 -0
  6. package/dist/agent.js.map +1 -0
  7. package/dist/backend.d.ts +378 -0
  8. package/dist/backend.d.ts.map +1 -0
  9. package/dist/backend.js +71 -0
  10. package/dist/backend.js.map +1 -0
  11. package/dist/backends/composite.d.ts +258 -0
  12. package/dist/backends/composite.d.ts.map +1 -0
  13. package/dist/backends/composite.js +437 -0
  14. package/dist/backends/composite.js.map +1 -0
  15. package/dist/backends/filesystem.d.ts +268 -0
  16. package/dist/backends/filesystem.d.ts.map +1 -0
  17. package/dist/backends/filesystem.js +623 -0
  18. package/dist/backends/filesystem.js.map +1 -0
  19. package/dist/backends/index.d.ts +14 -0
  20. package/dist/backends/index.d.ts.map +1 -0
  21. package/dist/backends/index.js +14 -0
  22. package/dist/backends/index.js.map +1 -0
  23. package/dist/backends/persistent.d.ts +312 -0
  24. package/dist/backends/persistent.d.ts.map +1 -0
  25. package/dist/backends/persistent.js +519 -0
  26. package/dist/backends/persistent.js.map +1 -0
  27. package/dist/backends/sandbox.d.ts +315 -0
  28. package/dist/backends/sandbox.d.ts.map +1 -0
  29. package/dist/backends/sandbox.js +490 -0
  30. package/dist/backends/sandbox.js.map +1 -0
  31. package/dist/backends/state.d.ts +225 -0
  32. package/dist/backends/state.d.ts.map +1 -0
  33. package/dist/backends/state.js +396 -0
  34. package/dist/backends/state.js.map +1 -0
  35. package/dist/checkpointer/file-saver.d.ts +182 -0
  36. package/dist/checkpointer/file-saver.d.ts.map +1 -0
  37. package/dist/checkpointer/file-saver.js +298 -0
  38. package/dist/checkpointer/file-saver.js.map +1 -0
  39. package/dist/checkpointer/index.d.ts +40 -0
  40. package/dist/checkpointer/index.d.ts.map +1 -0
  41. package/dist/checkpointer/index.js +40 -0
  42. package/dist/checkpointer/index.js.map +1 -0
  43. package/dist/checkpointer/kv-saver.d.ts +142 -0
  44. package/dist/checkpointer/kv-saver.d.ts.map +1 -0
  45. package/dist/checkpointer/kv-saver.js +176 -0
  46. package/dist/checkpointer/kv-saver.js.map +1 -0
  47. package/dist/checkpointer/memory-saver.d.ts +158 -0
  48. package/dist/checkpointer/memory-saver.d.ts.map +1 -0
  49. package/dist/checkpointer/memory-saver.js +222 -0
  50. package/dist/checkpointer/memory-saver.js.map +1 -0
  51. package/dist/checkpointer/types.d.ts +353 -0
  52. package/dist/checkpointer/types.d.ts.map +1 -0
  53. package/dist/checkpointer/types.js +159 -0
  54. package/dist/checkpointer/types.js.map +1 -0
  55. package/dist/context-manager.d.ts +627 -0
  56. package/dist/context-manager.d.ts.map +1 -0
  57. package/dist/context-manager.js +1039 -0
  58. package/dist/context-manager.js.map +1 -0
  59. package/dist/context.d.ts +57 -0
  60. package/dist/context.d.ts.map +1 -0
  61. package/dist/context.js +76 -0
  62. package/dist/context.js.map +1 -0
  63. package/dist/errors/index.d.ts +611 -0
  64. package/dist/errors/index.d.ts.map +1 -0
  65. package/dist/errors/index.js +1023 -0
  66. package/dist/errors/index.js.map +1 -0
  67. package/dist/generation-helpers.d.ts +126 -0
  68. package/dist/generation-helpers.d.ts.map +1 -0
  69. package/dist/generation-helpers.js +181 -0
  70. package/dist/generation-helpers.js.map +1 -0
  71. package/dist/hooks/audit.d.ts +210 -0
  72. package/dist/hooks/audit.d.ts.map +1 -0
  73. package/dist/hooks/audit.js +305 -0
  74. package/dist/hooks/audit.js.map +1 -0
  75. package/dist/hooks/cache.d.ts +180 -0
  76. package/dist/hooks/cache.d.ts.map +1 -0
  77. package/dist/hooks/cache.js +273 -0
  78. package/dist/hooks/cache.js.map +1 -0
  79. package/dist/hooks/guardrails.d.ts +145 -0
  80. package/dist/hooks/guardrails.d.ts.map +1 -0
  81. package/dist/hooks/guardrails.js +326 -0
  82. package/dist/hooks/guardrails.js.map +1 -0
  83. package/dist/hooks/index.d.ts +18 -0
  84. package/dist/hooks/index.d.ts.map +1 -0
  85. package/dist/hooks/index.js +32 -0
  86. package/dist/hooks/index.js.map +1 -0
  87. package/dist/hooks/logging.d.ts +193 -0
  88. package/dist/hooks/logging.d.ts.map +1 -0
  89. package/dist/hooks/logging.js +345 -0
  90. package/dist/hooks/logging.js.map +1 -0
  91. package/dist/hooks/parallel-guardrails.d.ts +268 -0
  92. package/dist/hooks/parallel-guardrails.d.ts.map +1 -0
  93. package/dist/hooks/parallel-guardrails.js +416 -0
  94. package/dist/hooks/parallel-guardrails.js.map +1 -0
  95. package/dist/hooks/rate-limit.d.ts +305 -0
  96. package/dist/hooks/rate-limit.d.ts.map +1 -0
  97. package/dist/hooks/rate-limit.js +372 -0
  98. package/dist/hooks/rate-limit.js.map +1 -0
  99. package/dist/hooks/retry.d.ts +144 -0
  100. package/dist/hooks/retry.d.ts.map +1 -0
  101. package/dist/hooks/retry.js +210 -0
  102. package/dist/hooks/retry.js.map +1 -0
  103. package/dist/hooks/secrets.d.ts +174 -0
  104. package/dist/hooks/secrets.d.ts.map +1 -0
  105. package/dist/hooks/secrets.js +306 -0
  106. package/dist/hooks/secrets.js.map +1 -0
  107. package/dist/hooks.d.ts +229 -0
  108. package/dist/hooks.d.ts.map +1 -0
  109. package/dist/hooks.js +352 -0
  110. package/dist/hooks.js.map +1 -0
  111. package/dist/index.d.ts +97 -0
  112. package/dist/index.d.ts.map +1 -0
  113. package/dist/index.js +182 -0
  114. package/dist/index.js.map +1 -0
  115. package/dist/mcp/env.d.ts +25 -0
  116. package/dist/mcp/env.d.ts.map +1 -0
  117. package/dist/mcp/env.js +18 -0
  118. package/dist/mcp/env.js.map +1 -0
  119. package/dist/mcp/index.d.ts +16 -0
  120. package/dist/mcp/index.d.ts.map +1 -0
  121. package/dist/mcp/index.js +17 -0
  122. package/dist/mcp/index.js.map +1 -0
  123. package/dist/mcp/manager.d.ts +184 -0
  124. package/dist/mcp/manager.d.ts.map +1 -0
  125. package/dist/mcp/manager.js +446 -0
  126. package/dist/mcp/manager.js.map +1 -0
  127. package/dist/mcp/types.d.ts +58 -0
  128. package/dist/mcp/types.d.ts.map +1 -0
  129. package/dist/mcp/types.js +7 -0
  130. package/dist/mcp/types.js.map +1 -0
  131. package/dist/mcp/validation.d.ts +119 -0
  132. package/dist/mcp/validation.d.ts.map +1 -0
  133. package/dist/mcp/validation.js +407 -0
  134. package/dist/mcp/validation.js.map +1 -0
  135. package/dist/mcp/virtual-server.d.ts +78 -0
  136. package/dist/mcp/virtual-server.d.ts.map +1 -0
  137. package/dist/mcp/virtual-server.js +137 -0
  138. package/dist/mcp/virtual-server.js.map +1 -0
  139. package/dist/memory/filesystem-store.d.ts +217 -0
  140. package/dist/memory/filesystem-store.d.ts.map +1 -0
  141. package/dist/memory/filesystem-store.js +343 -0
  142. package/dist/memory/filesystem-store.js.map +1 -0
  143. package/dist/memory/index.d.ts +46 -0
  144. package/dist/memory/index.d.ts.map +1 -0
  145. package/dist/memory/index.js +46 -0
  146. package/dist/memory/index.js.map +1 -0
  147. package/dist/memory/loader.d.ts +396 -0
  148. package/dist/memory/loader.d.ts.map +1 -0
  149. package/dist/memory/loader.js +419 -0
  150. package/dist/memory/loader.js.map +1 -0
  151. package/dist/memory/permissions.d.ts +282 -0
  152. package/dist/memory/permissions.d.ts.map +1 -0
  153. package/dist/memory/permissions.js +297 -0
  154. package/dist/memory/permissions.js.map +1 -0
  155. package/dist/memory/rules.d.ts +249 -0
  156. package/dist/memory/rules.d.ts.map +1 -0
  157. package/dist/memory/rules.js +362 -0
  158. package/dist/memory/rules.js.map +1 -0
  159. package/dist/memory/store.d.ts +286 -0
  160. package/dist/memory/store.d.ts.map +1 -0
  161. package/dist/memory/store.js +263 -0
  162. package/dist/memory/store.js.map +1 -0
  163. package/dist/middleware/apply.d.ts +73 -0
  164. package/dist/middleware/apply.d.ts.map +1 -0
  165. package/dist/middleware/apply.js +219 -0
  166. package/dist/middleware/apply.js.map +1 -0
  167. package/dist/middleware/context.d.ts +33 -0
  168. package/dist/middleware/context.d.ts.map +1 -0
  169. package/dist/middleware/context.js +176 -0
  170. package/dist/middleware/context.js.map +1 -0
  171. package/dist/middleware/index.d.ts +31 -0
  172. package/dist/middleware/index.d.ts.map +1 -0
  173. package/dist/middleware/index.js +32 -0
  174. package/dist/middleware/index.js.map +1 -0
  175. package/dist/middleware/logging.d.ts +137 -0
  176. package/dist/middleware/logging.d.ts.map +1 -0
  177. package/dist/middleware/logging.js +374 -0
  178. package/dist/middleware/logging.js.map +1 -0
  179. package/dist/middleware/types.d.ts +183 -0
  180. package/dist/middleware/types.d.ts.map +1 -0
  181. package/dist/middleware/types.js +11 -0
  182. package/dist/middleware/types.js.map +1 -0
  183. package/dist/observability/events.d.ts +183 -0
  184. package/dist/observability/events.d.ts.map +1 -0
  185. package/dist/observability/events.js +305 -0
  186. package/dist/observability/events.js.map +1 -0
  187. package/dist/observability/index.d.ts +55 -0
  188. package/dist/observability/index.d.ts.map +1 -0
  189. package/dist/observability/index.js +87 -0
  190. package/dist/observability/index.js.map +1 -0
  191. package/dist/observability/logger.d.ts +318 -0
  192. package/dist/observability/logger.d.ts.map +1 -0
  193. package/dist/observability/logger.js +436 -0
  194. package/dist/observability/logger.js.map +1 -0
  195. package/dist/observability/metrics.d.ts +341 -0
  196. package/dist/observability/metrics.d.ts.map +1 -0
  197. package/dist/observability/metrics.js +490 -0
  198. package/dist/observability/metrics.js.map +1 -0
  199. package/dist/observability/preset.d.ts +161 -0
  200. package/dist/observability/preset.d.ts.map +1 -0
  201. package/dist/observability/preset.js +133 -0
  202. package/dist/observability/preset.js.map +1 -0
  203. package/dist/observability/streaming.d.ts +113 -0
  204. package/dist/observability/streaming.d.ts.map +1 -0
  205. package/dist/observability/streaming.js +114 -0
  206. package/dist/observability/streaming.js.map +1 -0
  207. package/dist/observability/tracing.d.ts +378 -0
  208. package/dist/observability/tracing.d.ts.map +1 -0
  209. package/dist/observability/tracing.js +539 -0
  210. package/dist/observability/tracing.js.map +1 -0
  211. package/dist/plugins.d.ts +55 -0
  212. package/dist/plugins.d.ts.map +1 -0
  213. package/dist/plugins.js +63 -0
  214. package/dist/plugins.js.map +1 -0
  215. package/dist/presets/index.d.ts +7 -0
  216. package/dist/presets/index.d.ts.map +1 -0
  217. package/dist/presets/index.js +7 -0
  218. package/dist/presets/index.js.map +1 -0
  219. package/dist/presets/production.d.ts +262 -0
  220. package/dist/presets/production.d.ts.map +1 -0
  221. package/dist/presets/production.js +295 -0
  222. package/dist/presets/production.js.map +1 -0
  223. package/dist/security/index.d.ts +179 -0
  224. package/dist/security/index.d.ts.map +1 -0
  225. package/dist/security/index.js +323 -0
  226. package/dist/security/index.js.map +1 -0
  227. package/dist/subagents/advanced.d.ts +413 -0
  228. package/dist/subagents/advanced.d.ts.map +1 -0
  229. package/dist/subagents/advanced.js +396 -0
  230. package/dist/subagents/advanced.js.map +1 -0
  231. package/dist/subagents/index.d.ts +14 -0
  232. package/dist/subagents/index.d.ts.map +1 -0
  233. package/dist/subagents/index.js +15 -0
  234. package/dist/subagents/index.js.map +1 -0
  235. package/dist/subagents.d.ts +73 -0
  236. package/dist/subagents.d.ts.map +1 -0
  237. package/dist/subagents.js +213 -0
  238. package/dist/subagents.js.map +1 -0
  239. package/dist/task-store/file-store.d.ts +76 -0
  240. package/dist/task-store/file-store.d.ts.map +1 -0
  241. package/dist/task-store/file-store.js +190 -0
  242. package/dist/task-store/file-store.js.map +1 -0
  243. package/dist/task-store/index.d.ts +11 -0
  244. package/dist/task-store/index.d.ts.map +1 -0
  245. package/dist/task-store/index.js +10 -0
  246. package/dist/task-store/index.js.map +1 -0
  247. package/dist/task-store/kv-store.d.ts +140 -0
  248. package/dist/task-store/kv-store.d.ts.map +1 -0
  249. package/dist/task-store/kv-store.js +169 -0
  250. package/dist/task-store/kv-store.js.map +1 -0
  251. package/dist/task-store/memory-store.d.ts +66 -0
  252. package/dist/task-store/memory-store.d.ts.map +1 -0
  253. package/dist/task-store/memory-store.js +125 -0
  254. package/dist/task-store/memory-store.js.map +1 -0
  255. package/dist/task-store/types.d.ts +235 -0
  256. package/dist/task-store/types.d.ts.map +1 -0
  257. package/dist/task-store/types.js +110 -0
  258. package/dist/task-store/types.js.map +1 -0
  259. package/dist/testing/assertions.d.ts +401 -0
  260. package/dist/testing/assertions.d.ts.map +1 -0
  261. package/dist/testing/assertions.js +630 -0
  262. package/dist/testing/assertions.js.map +1 -0
  263. package/dist/testing/index.d.ts +343 -0
  264. package/dist/testing/index.d.ts.map +1 -0
  265. package/dist/testing/index.js +360 -0
  266. package/dist/testing/index.js.map +1 -0
  267. package/dist/testing/mock-agent.d.ts +214 -0
  268. package/dist/testing/mock-agent.d.ts.map +1 -0
  269. package/dist/testing/mock-agent.js +448 -0
  270. package/dist/testing/mock-agent.js.map +1 -0
  271. package/dist/testing/recorder.d.ts +288 -0
  272. package/dist/testing/recorder.d.ts.map +1 -0
  273. package/dist/testing/recorder.js +499 -0
  274. package/dist/testing/recorder.js.map +1 -0
  275. package/dist/tools/execute.d.ts +104 -0
  276. package/dist/tools/execute.d.ts.map +1 -0
  277. package/dist/tools/execute.js +191 -0
  278. package/dist/tools/execute.js.map +1 -0
  279. package/dist/tools/factory.d.ts +260 -0
  280. package/dist/tools/factory.d.ts.map +1 -0
  281. package/dist/tools/factory.js +241 -0
  282. package/dist/tools/factory.js.map +1 -0
  283. package/dist/tools/filesystem.d.ts +215 -0
  284. package/dist/tools/filesystem.d.ts.map +1 -0
  285. package/dist/tools/filesystem.js +311 -0
  286. package/dist/tools/filesystem.js.map +1 -0
  287. package/dist/tools/index.d.ts +33 -0
  288. package/dist/tools/index.d.ts.map +1 -0
  289. package/dist/tools/index.js +33 -0
  290. package/dist/tools/index.js.map +1 -0
  291. package/dist/tools/search.d.ts +59 -0
  292. package/dist/tools/search.d.ts.map +1 -0
  293. package/dist/tools/search.js +94 -0
  294. package/dist/tools/search.js.map +1 -0
  295. package/dist/tools/skills.d.ts +354 -0
  296. package/dist/tools/skills.d.ts.map +1 -0
  297. package/dist/tools/skills.js +413 -0
  298. package/dist/tools/skills.js.map +1 -0
  299. package/dist/tools/task.d.ts +272 -0
  300. package/dist/tools/task.d.ts.map +1 -0
  301. package/dist/tools/task.js +521 -0
  302. package/dist/tools/task.js.map +1 -0
  303. package/dist/tools/todos.d.ts +131 -0
  304. package/dist/tools/todos.d.ts.map +1 -0
  305. package/dist/tools/todos.js +120 -0
  306. package/dist/tools/todos.js.map +1 -0
  307. package/dist/tools/tool-registry.d.ts +424 -0
  308. package/dist/tools/tool-registry.d.ts.map +1 -0
  309. package/dist/tools/tool-registry.js +607 -0
  310. package/dist/tools/tool-registry.js.map +1 -0
  311. package/dist/tools/user-interaction.d.ts +116 -0
  312. package/dist/tools/user-interaction.d.ts.map +1 -0
  313. package/dist/tools/user-interaction.js +147 -0
  314. package/dist/tools/user-interaction.js.map +1 -0
  315. package/dist/tools/utils.d.ts +124 -0
  316. package/dist/tools/utils.d.ts.map +1 -0
  317. package/dist/tools/utils.js +189 -0
  318. package/dist/tools/utils.js.map +1 -0
  319. package/dist/tools.d.ts +74 -0
  320. package/dist/tools.d.ts.map +1 -0
  321. package/dist/tools.js +73 -0
  322. package/dist/tools.js.map +1 -0
  323. package/dist/types.d.ts +2421 -0
  324. package/dist/types.d.ts.map +1 -0
  325. package/dist/types.js +55 -0
  326. package/dist/types.js.map +1 -0
  327. package/package.json +81 -0
@@ -0,0 +1,490 @@
1
+ /**
2
+ * Metrics Collection System.
3
+ *
4
+ * Provides a flexible metrics system for tracking:
5
+ * - Token usage (input/output tokens)
6
+ * - Latency (request duration)
7
+ * - Error rates
8
+ * - Custom counters, gauges, and histograms
9
+ *
10
+ * @packageDocumentation
11
+ */
12
+ // =============================================================================
13
+ // Utilities
14
+ // =============================================================================
15
+ /**
16
+ * Serialize labels to a string key.
17
+ * @internal
18
+ */
19
+ function labelsToKey(labels) {
20
+ const entries = Object.entries(labels).sort(([a], [b]) => a.localeCompare(b));
21
+ return entries.map(([k, v]) => `${k}=${v}`).join(",");
22
+ }
23
+ /**
24
+ * Default histogram buckets (latency in ms).
25
+ */
26
+ export const DEFAULT_LATENCY_BUCKETS = [
27
+ 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 10000,
28
+ ];
29
+ /**
30
+ * Default histogram buckets for token counts.
31
+ */
32
+ export const DEFAULT_TOKEN_BUCKETS = [
33
+ 10, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 25000, 50000, 100000,
34
+ ];
35
+ // =============================================================================
36
+ // Implementation
37
+ // =============================================================================
38
+ /**
39
+ * Creates a counter metric.
40
+ *
41
+ * @internal
42
+ */
43
+ function createCounter(name, defaultLabels) {
44
+ const values = new Map();
45
+ return {
46
+ inc(value = 1, labels = {}) {
47
+ const key = labelsToKey({ ...defaultLabels, ...labels });
48
+ values.set(key, (values.get(key) ?? 0) + value);
49
+ },
50
+ get(labels = {}) {
51
+ const key = labelsToKey({ ...defaultLabels, ...labels });
52
+ return values.get(key) ?? 0;
53
+ },
54
+ reset(labels = {}) {
55
+ const key = labelsToKey({ ...defaultLabels, ...labels });
56
+ values.delete(key);
57
+ },
58
+ };
59
+ }
60
+ /**
61
+ * Creates a gauge metric.
62
+ *
63
+ * @internal
64
+ */
65
+ function createGauge(name, defaultLabels) {
66
+ const values = new Map();
67
+ return {
68
+ set(value, labels = {}) {
69
+ const key = labelsToKey({ ...defaultLabels, ...labels });
70
+ values.set(key, value);
71
+ },
72
+ inc(value = 1, labels = {}) {
73
+ const key = labelsToKey({ ...defaultLabels, ...labels });
74
+ values.set(key, (values.get(key) ?? 0) + value);
75
+ },
76
+ dec(value = 1, labels = {}) {
77
+ const key = labelsToKey({ ...defaultLabels, ...labels });
78
+ values.set(key, (values.get(key) ?? 0) - value);
79
+ },
80
+ get(labels = {}) {
81
+ const key = labelsToKey({ ...defaultLabels, ...labels });
82
+ return values.get(key) ?? 0;
83
+ },
84
+ };
85
+ }
86
+ /**
87
+ * Creates a histogram metric.
88
+ *
89
+ * @internal
90
+ */
91
+ function createHistogram(name, buckets, defaultLabels) {
92
+ const sortedBuckets = [...buckets].sort((a, b) => a - b);
93
+ const data = new Map();
94
+ function getData(labels) {
95
+ const key = labelsToKey({ ...defaultLabels, ...labels });
96
+ let entry = data.get(key);
97
+ if (!entry) {
98
+ entry = {
99
+ bucketCounts: new Array(sortedBuckets.length).fill(0),
100
+ sum: 0,
101
+ count: 0,
102
+ };
103
+ data.set(key, entry);
104
+ }
105
+ return entry;
106
+ }
107
+ return {
108
+ observe(value, labels = {}) {
109
+ const d = getData(labels);
110
+ d.sum += value;
111
+ d.count += 1;
112
+ for (let i = 0; i < sortedBuckets.length; i++) {
113
+ if (value <= sortedBuckets[i]) {
114
+ d.bucketCounts[i] = (d.bucketCounts[i] ?? 0) + 1;
115
+ }
116
+ }
117
+ },
118
+ get(labels = {}) {
119
+ const d = getData(labels);
120
+ return {
121
+ buckets: sortedBuckets.map((le, i) => ({
122
+ le,
123
+ count: d.bucketCounts[i] ?? 0,
124
+ })),
125
+ sum: d.sum,
126
+ count: d.count,
127
+ };
128
+ },
129
+ startTimer(labels = {}) {
130
+ const start = Date.now();
131
+ return () => {
132
+ const duration = Date.now() - start;
133
+ this.observe(duration, labels);
134
+ return duration;
135
+ };
136
+ },
137
+ reset(labels = {}) {
138
+ const key = labelsToKey({ ...defaultLabels, ...labels });
139
+ data.delete(key);
140
+ },
141
+ };
142
+ }
143
+ /**
144
+ * Creates a metrics registry.
145
+ *
146
+ * @param options - Registry options
147
+ * @returns A metrics registry
148
+ *
149
+ * @example
150
+ * ```typescript
151
+ * const registry = createMetricsRegistry({
152
+ * defaultLabels: { service: "my-agent" },
153
+ * });
154
+ *
155
+ * const requestCounter = registry.counter("requests_total");
156
+ * const latencyHistogram = registry.histogram("request_duration_ms");
157
+ *
158
+ * requestCounter.inc();
159
+ * latencyHistogram.observe(150);
160
+ * ```
161
+ *
162
+ * @category Observability
163
+ */
164
+ export function createMetricsRegistry(options = {}) {
165
+ const { defaultLabels = {}, exporters = [], exportInterval = 0, prefix = "" } = options;
166
+ const counters = new Map();
167
+ const gauges = new Map();
168
+ const histograms = new Map();
169
+ let intervalHandle = null;
170
+ // Start export interval if configured
171
+ if (exportInterval > 0 && exporters.length > 0) {
172
+ intervalHandle = setInterval(async () => {
173
+ await registry.export();
174
+ }, exportInterval);
175
+ }
176
+ function prefixName(name) {
177
+ return prefix ? `${prefix}_${name}` : name;
178
+ }
179
+ const registry = {
180
+ counter(name, description) {
181
+ const prefixedName = prefixName(name);
182
+ let entry = counters.get(prefixedName);
183
+ if (!entry) {
184
+ entry = {
185
+ counter: createCounter(prefixedName, defaultLabels),
186
+ description,
187
+ };
188
+ counters.set(prefixedName, entry);
189
+ }
190
+ return entry.counter;
191
+ },
192
+ gauge(name, description) {
193
+ const prefixedName = prefixName(name);
194
+ let entry = gauges.get(prefixedName);
195
+ if (!entry) {
196
+ entry = {
197
+ gauge: createGauge(prefixedName, defaultLabels),
198
+ description,
199
+ };
200
+ gauges.set(prefixedName, entry);
201
+ }
202
+ return entry.gauge;
203
+ },
204
+ histogram(name, buckets = DEFAULT_LATENCY_BUCKETS, description) {
205
+ const prefixedName = prefixName(name);
206
+ let entry = histograms.get(prefixedName);
207
+ if (!entry) {
208
+ entry = {
209
+ histogram: createHistogram(prefixedName, buckets, defaultLabels),
210
+ buckets,
211
+ description,
212
+ };
213
+ histograms.set(prefixedName, entry);
214
+ }
215
+ return entry.histogram;
216
+ },
217
+ getMetrics() {
218
+ const points = [];
219
+ const timestamp = new Date().toISOString();
220
+ // Collect counter values
221
+ for (const [name, { counter }] of counters) {
222
+ const value = counter.get();
223
+ points.push({
224
+ name,
225
+ type: "counter",
226
+ value,
227
+ labels: { ...defaultLabels },
228
+ timestamp,
229
+ });
230
+ }
231
+ // Collect gauge values
232
+ for (const [name, { gauge }] of gauges) {
233
+ const value = gauge.get();
234
+ points.push({
235
+ name,
236
+ type: "gauge",
237
+ value,
238
+ labels: { ...defaultLabels },
239
+ timestamp,
240
+ });
241
+ }
242
+ // Collect histogram values
243
+ for (const [name, { histogram }] of histograms) {
244
+ const data = histogram.get();
245
+ // Export sum and count
246
+ points.push({
247
+ name: `${name}_sum`,
248
+ type: "histogram",
249
+ value: data.sum,
250
+ labels: { ...defaultLabels },
251
+ timestamp,
252
+ });
253
+ points.push({
254
+ name: `${name}_count`,
255
+ type: "histogram",
256
+ value: data.count,
257
+ labels: { ...defaultLabels },
258
+ timestamp,
259
+ });
260
+ // Export buckets
261
+ for (const bucket of data.buckets) {
262
+ points.push({
263
+ name: `${name}_bucket`,
264
+ type: "histogram",
265
+ value: bucket.count,
266
+ labels: { ...defaultLabels, le: String(bucket.le) },
267
+ timestamp,
268
+ });
269
+ }
270
+ }
271
+ return points;
272
+ },
273
+ async export() {
274
+ const metrics = this.getMetrics();
275
+ await Promise.all(exporters.map((e) => Promise.resolve(e.export(metrics)).catch(() => {
276
+ // Silently ignore export errors
277
+ })));
278
+ },
279
+ async close() {
280
+ if (intervalHandle) {
281
+ clearInterval(intervalHandle);
282
+ intervalHandle = null;
283
+ }
284
+ await Promise.all(exporters.map((e) => e.close ? Promise.resolve(e.close()).catch(() => { }) : Promise.resolve()));
285
+ },
286
+ };
287
+ return registry;
288
+ }
289
+ // =============================================================================
290
+ // Exporters
291
+ // =============================================================================
292
+ /**
293
+ * Creates a console exporter for debugging.
294
+ *
295
+ * @returns A console exporter
296
+ *
297
+ * @example
298
+ * ```typescript
299
+ * const registry = createMetricsRegistry({
300
+ * exporters: [createConsoleMetricsExporter()],
301
+ * });
302
+ * ```
303
+ *
304
+ * @category Observability
305
+ */
306
+ export function createConsoleMetricsExporter() {
307
+ return {
308
+ name: "console",
309
+ export(metrics) {
310
+ console.log("[Metrics]", JSON.stringify(metrics, null, 2));
311
+ },
312
+ };
313
+ }
314
+ /**
315
+ * Creates a memory exporter that stores metrics.
316
+ *
317
+ * @returns A memory exporter with access to stored metrics
318
+ *
319
+ * @example
320
+ * ```typescript
321
+ * const exporter = createMemoryMetricsExporter();
322
+ * const registry = createMetricsRegistry({ exporters: [exporter] });
323
+ *
324
+ * registry.counter("test").inc();
325
+ * await registry.export();
326
+ *
327
+ * console.log(exporter.metrics);
328
+ * ```
329
+ *
330
+ * @category Observability
331
+ */
332
+ export function createMemoryMetricsExporter() {
333
+ const metrics = [];
334
+ return {
335
+ name: "memory",
336
+ metrics,
337
+ export(points) {
338
+ metrics.push(...points);
339
+ },
340
+ clear() {
341
+ metrics.length = 0;
342
+ },
343
+ };
344
+ }
345
+ /**
346
+ * Creates a callback exporter that invokes a function for each export.
347
+ *
348
+ * @param callback - Function to call with metrics
349
+ * @returns A callback exporter
350
+ *
351
+ * @example
352
+ * ```typescript
353
+ * const exporter = createCallbackMetricsExporter((metrics) => {
354
+ * sendToPrometheus(metrics);
355
+ * });
356
+ * ```
357
+ *
358
+ * @category Observability
359
+ */
360
+ export function createCallbackMetricsExporter(callback) {
361
+ return {
362
+ name: "callback",
363
+ export: callback,
364
+ };
365
+ }
366
+ /**
367
+ * Creates pre-defined agent metrics.
368
+ *
369
+ * @param registry - The metrics registry to use
370
+ * @returns Agent metrics object
371
+ *
372
+ * @example
373
+ * ```typescript
374
+ * const registry = createMetricsRegistry();
375
+ * const metrics = createAgentMetrics(registry);
376
+ *
377
+ * // Use in agent hooks
378
+ * hooks.on("PostGenerate", (ctx) => {
379
+ * metrics.requestsTotal.inc({ model: "claude-3" });
380
+ * if (ctx.data.type === "PostGenerate" && ctx.data.result.usage) {
381
+ * metrics.inputTokensTotal.inc(ctx.data.result.usage.inputTokens);
382
+ * metrics.outputTokensTotal.inc(ctx.data.result.usage.outputTokens);
383
+ * }
384
+ * });
385
+ * ```
386
+ *
387
+ * @category Observability
388
+ */
389
+ export function createAgentMetrics(registry) {
390
+ return {
391
+ requestsTotal: registry.counter("agent_requests_total", "Total number of agent requests"),
392
+ requestsInProgress: registry.gauge("agent_requests_in_progress", "Number of requests currently in progress"),
393
+ requestDurationMs: registry.histogram("agent_request_duration_ms", DEFAULT_LATENCY_BUCKETS, "Request duration in milliseconds"),
394
+ inputTokensTotal: registry.counter("agent_input_tokens_total", "Total input tokens used"),
395
+ outputTokensTotal: registry.counter("agent_output_tokens_total", "Total output tokens used"),
396
+ tokensTotal: registry.counter("agent_tokens_total", "Total tokens used (input + output)"),
397
+ toolCallsTotal: registry.counter("agent_tool_calls_total", "Total tool calls made"),
398
+ toolErrorsTotal: registry.counter("agent_tool_errors_total", "Total tool call errors"),
399
+ subagentSpawnsTotal: registry.counter("agent_subagent_spawns_total", "Total subagent spawns"),
400
+ errorsTotal: registry.counter("agent_errors_total", "Total errors by type"),
401
+ compactionsTotal: registry.counter("agent_compactions_total", "Total context compactions"),
402
+ checkpointsTotal: registry.counter("agent_checkpoints_total", "Total checkpoint operations"),
403
+ };
404
+ }
405
+ /**
406
+ * Creates hooks that automatically update agent metrics.
407
+ *
408
+ * @param metrics - The agent metrics to update
409
+ * @returns Hook callbacks for metrics collection
410
+ *
411
+ * @example
412
+ * ```typescript
413
+ * const registry = createMetricsRegistry();
414
+ * const metrics = createAgentMetrics(registry);
415
+ * const metricsHooks = createMetricsHooks(metrics);
416
+ *
417
+ * const agent = createAgent({
418
+ * model,
419
+ * hooks: {
420
+ * PostGenerate: [metricsHooks.PostGenerate],
421
+ * PostToolUse: [metricsHooks.PostToolUse],
422
+ * PostToolUseFailure: [metricsHooks.PostToolUseFailure],
423
+ * PostCompact: [metricsHooks.PostCompact],
424
+ * },
425
+ * });
426
+ * ```
427
+ *
428
+ * @category Observability
429
+ */
430
+ export function createMetricsHooks(metrics) {
431
+ return {
432
+ PostGenerate: async (input) => {
433
+ if (input.hook_event_name !== "PostGenerate")
434
+ return {};
435
+ const postGenInput = input;
436
+ metrics.requestsTotal.inc();
437
+ if (postGenInput.result.usage) {
438
+ metrics.inputTokensTotal.inc(postGenInput.result.usage.inputTokens);
439
+ metrics.outputTokensTotal.inc(postGenInput.result.usage.outputTokens);
440
+ metrics.tokensTotal.inc(postGenInput.result.usage.totalTokens);
441
+ }
442
+ return {};
443
+ },
444
+ PostToolUse: async (input) => {
445
+ if (input.hook_event_name !== "PostToolUse")
446
+ return {};
447
+ const postToolInput = input;
448
+ metrics.toolCallsTotal.inc(1, { tool: postToolInput.tool_name });
449
+ return {};
450
+ },
451
+ PostToolUseFailure: async (input) => {
452
+ if (input.hook_event_name !== "PostToolUseFailure")
453
+ return {};
454
+ const failureInput = input;
455
+ metrics.toolErrorsTotal.inc(1, { tool: failureInput.tool_name });
456
+ metrics.errorsTotal.inc(1, { type: "tool_error" });
457
+ return {};
458
+ },
459
+ PostCompact: async (input) => {
460
+ if (input.hook_event_name !== "PostCompact")
461
+ return {};
462
+ const _postCompactInput = input;
463
+ metrics.compactionsTotal.inc();
464
+ // Note: Could add additional metrics here like tokens_saved gauge
465
+ // but keeping it simple for now - the hook input has all the data
466
+ // if users want to track more granular metrics
467
+ return {};
468
+ },
469
+ };
470
+ }
471
+ // =============================================================================
472
+ // Default Registry
473
+ // =============================================================================
474
+ /**
475
+ * The default global metrics registry.
476
+ *
477
+ * @category Observability
478
+ */
479
+ export let defaultMetricsRegistry = createMetricsRegistry();
480
+ /**
481
+ * Sets the default global metrics registry.
482
+ *
483
+ * @param registry - The registry to use as default
484
+ *
485
+ * @category Observability
486
+ */
487
+ export function setDefaultMetricsRegistry(registry) {
488
+ defaultMetricsRegistry = registry;
489
+ }
490
+ //# sourceMappingURL=metrics.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkKH,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF;;;GAGG;AACH,SAAS,WAAW,CAAC,MAAoB;IACvC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK;CAC/D,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM;CACrE,CAAC;AAEF,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;;;GAIG;AACH,SAAS,aAAa,CAAC,IAAY,EAAE,aAA2B;IAC9D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEzC,OAAO;QACL,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,MAAM,GAAG,EAAE;YACxB,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;YACzD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;QAClD,CAAC;QACD,GAAG,CAAC,MAAM,GAAG,EAAE;YACb,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;YACzD,OAAO,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;QACD,KAAK,CAAC,MAAM,GAAG,EAAE;YACf,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;YACzD,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,IAAY,EAAE,aAA2B;IAC5D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEzC,OAAO;QACL,GAAG,CAAC,KAAa,EAAE,MAAM,GAAG,EAAE;YAC5B,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;YACzD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACzB,CAAC;QACD,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,MAAM,GAAG,EAAE;YACxB,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;YACzD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;QAClD,CAAC;QACD,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,MAAM,GAAG,EAAE;YACxB,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;YACzD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;QAClD,CAAC;QACD,GAAG,CAAC,MAAM,GAAG,EAAE;YACb,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;YACzD,OAAO,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,IAAY,EAAE,OAAiB,EAAE,aAA2B;IACnF,MAAM,aAAa,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkE,CAAC;IAEvF,SAAS,OAAO,CAAC,MAAoB;QACnC,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;QACzD,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG;gBACN,YAAY,EAAE,IAAI,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;gBACrD,GAAG,EAAE,CAAC;gBACN,KAAK,EAAE,CAAC;aACT,CAAC;YACF,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO;QACL,OAAO,CAAC,KAAa,EAAE,MAAM,GAAG,EAAE;YAChC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YAC1B,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC;YACf,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;YACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC9C,IAAI,KAAK,IAAI,aAAa,CAAC,CAAC,CAAE,EAAE,CAAC;oBAC/B,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;gBACnD,CAAC;YACH,CAAC;QACH,CAAC;QACD,GAAG,CAAC,MAAM,GAAG,EAAE;YACb,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YAC1B,OAAO;gBACL,OAAO,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;oBACrC,EAAE;oBACF,KAAK,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC;iBAC9B,CAAC,CAAC;gBACH,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,KAAK,EAAE,CAAC,CAAC,KAAK;aACf,CAAC;QACJ,CAAC;QACD,UAAU,CAAC,MAAM,GAAG,EAAE;YACpB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACzB,OAAO,GAAG,EAAE;gBACV,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;gBACpC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;gBAC/B,OAAO,QAAQ,CAAC;YAClB,CAAC,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,MAAM,GAAG,EAAE;YACf,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;YACzD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAkC,EAAE;IACxE,MAAM,EAAE,aAAa,GAAG,EAAE,EAAE,SAAS,GAAG,EAAE,EAAE,cAAc,GAAG,CAAC,EAAE,MAAM,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAExF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAsD,CAAC;IAC/E,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkD,CAAC;IACzE,MAAM,UAAU,GAAG,IAAI,GAAG,EAGvB,CAAC;IAEJ,IAAI,cAAc,GAA0C,IAAI,CAAC;IAEjE,sCAAsC;IACtC,IAAI,cAAc,GAAG,CAAC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/C,cAAc,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;YACtC,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC1B,CAAC,EAAE,cAAc,CAAC,CAAC;IACrB,CAAC;IAED,SAAS,UAAU,CAAC,IAAY;QAC9B,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;IAED,MAAM,QAAQ,GAAoB;QAChC,OAAO,CAAC,IAAY,EAAE,WAAoB;YACxC,MAAM,YAAY,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YACvC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,KAAK,GAAG;oBACN,OAAO,EAAE,aAAa,CAAC,YAAY,EAAE,aAAa,CAAC;oBACnD,WAAW;iBACZ,CAAC;gBACF,QAAQ,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,KAAK,CAAC,OAAO,CAAC;QACvB,CAAC;QAED,KAAK,CAAC,IAAY,EAAE,WAAoB;YACtC,MAAM,YAAY,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YACrC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,KAAK,GAAG;oBACN,KAAK,EAAE,WAAW,CAAC,YAAY,EAAE,aAAa,CAAC;oBAC/C,WAAW;iBACZ,CAAC;gBACF,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;YAClC,CAAC;YACD,OAAO,KAAK,CAAC,KAAK,CAAC;QACrB,CAAC;QAED,SAAS,CACP,IAAY,EACZ,UAAoB,uBAAuB,EAC3C,WAAoB;YAEpB,MAAM,YAAY,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YACzC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,KAAK,GAAG;oBACN,SAAS,EAAE,eAAe,CAAC,YAAY,EAAE,OAAO,EAAE,aAAa,CAAC;oBAChE,OAAO;oBACP,WAAW;iBACZ,CAAC;gBACF,UAAU,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;YACtC,CAAC;YACD,OAAO,KAAK,CAAC,SAAS,CAAC;QACzB,CAAC;QAED,UAAU;YACR,MAAM,MAAM,GAAkB,EAAE,CAAC;YACjC,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAE3C,yBAAyB;YACzB,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC;gBAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;gBAC5B,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI;oBACJ,IAAI,EAAE,SAAS;oBACf,KAAK;oBACL,MAAM,EAAE,EAAE,GAAG,aAAa,EAAE;oBAC5B,SAAS;iBACV,CAAC,CAAC;YACL,CAAC;YAED,uBAAuB;YACvB,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC;gBACvC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;gBAC1B,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI;oBACJ,IAAI,EAAE,OAAO;oBACb,KAAK;oBACL,MAAM,EAAE,EAAE,GAAG,aAAa,EAAE;oBAC5B,SAAS;iBACV,CAAC,CAAC;YACL,CAAC;YAED,2BAA2B;YAC3B,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,IAAI,UAAU,EAAE,CAAC;gBAC/C,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC;gBAC7B,uBAAuB;gBACvB,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,GAAG,IAAI,MAAM;oBACnB,IAAI,EAAE,WAAW;oBACjB,KAAK,EAAE,IAAI,CAAC,GAAG;oBACf,MAAM,EAAE,EAAE,GAAG,aAAa,EAAE;oBAC5B,SAAS;iBACV,CAAC,CAAC;gBACH,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,GAAG,IAAI,QAAQ;oBACrB,IAAI,EAAE,WAAW;oBACjB,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,MAAM,EAAE,EAAE,GAAG,aAAa,EAAE;oBAC5B,SAAS;iBACV,CAAC,CAAC;gBACH,iBAAiB;gBACjB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;oBAClC,MAAM,CAAC,IAAI,CAAC;wBACV,IAAI,EAAE,GAAG,IAAI,SAAS;wBACtB,IAAI,EAAE,WAAW;wBACjB,KAAK,EAAE,MAAM,CAAC,KAAK;wBACnB,MAAM,EAAE,EAAE,GAAG,aAAa,EAAE,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE;wBACnD,SAAS;qBACV,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,KAAK,CAAC,MAAM;YACV,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAClC,MAAM,OAAO,CAAC,GAAG,CACf,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAClB,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;gBAC5C,gCAAgC;YAClC,CAAC,CAAC,CACH,CACF,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,KAAK;YACT,IAAI,cAAc,EAAE,CAAC;gBACnB,aAAa,CAAC,cAAc,CAAC,CAAC;gBAC9B,cAAc,GAAG,IAAI,CAAC;YACxB,CAAC;YACD,MAAM,OAAO,CAAC,GAAG,CACf,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAClB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CACzE,CACF,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,4BAA4B;IAC1C,OAAO;QACL,IAAI,EAAE,SAAS;QACf,MAAM,CAAC,OAAsB;YAC3B,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7D,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,2BAA2B;IAIzC,MAAM,OAAO,GAAkB,EAAE,CAAC;IAElC,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,OAAO;QACP,MAAM,CAAC,MAAqB;YAC1B,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;QAC1B,CAAC;QACD,KAAK;YACH,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,6BAA6B,CAC3C,QAA0D;IAE1D,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,QAAQ;KACjB,CAAC;AACJ,CAAC;AAsCD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAyB;IAC1D,OAAO;QACL,aAAa,EAAE,QAAQ,CAAC,OAAO,CAAC,sBAAsB,EAAE,gCAAgC,CAAC;QACzF,kBAAkB,EAAE,QAAQ,CAAC,KAAK,CAChC,4BAA4B,EAC5B,0CAA0C,CAC3C;QACD,iBAAiB,EAAE,QAAQ,CAAC,SAAS,CACnC,2BAA2B,EAC3B,uBAAuB,EACvB,kCAAkC,CACnC;QACD,gBAAgB,EAAE,QAAQ,CAAC,OAAO,CAAC,0BAA0B,EAAE,yBAAyB,CAAC;QACzF,iBAAiB,EAAE,QAAQ,CAAC,OAAO,CAAC,2BAA2B,EAAE,0BAA0B,CAAC;QAC5F,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,oBAAoB,EAAE,oCAAoC,CAAC;QACzF,cAAc,EAAE,QAAQ,CAAC,OAAO,CAAC,wBAAwB,EAAE,uBAAuB,CAAC;QACnF,eAAe,EAAE,QAAQ,CAAC,OAAO,CAAC,yBAAyB,EAAE,wBAAwB,CAAC;QACtF,mBAAmB,EAAE,QAAQ,CAAC,OAAO,CAAC,6BAA6B,EAAE,uBAAuB,CAAC;QAC7F,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,oBAAoB,EAAE,sBAAsB,CAAC;QAC3E,gBAAgB,EAAE,QAAQ,CAAC,OAAO,CAAC,yBAAyB,EAAE,2BAA2B,CAAC;QAC1F,gBAAgB,EAAE,QAAQ,CAAC,OAAO,CAAC,yBAAyB,EAAE,6BAA6B,CAAC;KAC7F,CAAC;AACJ,CAAC;AAcD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAqB;IAMtD,OAAO;QACL,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YAC5B,IAAI,KAAK,CAAC,eAAe,KAAK,cAAc;gBAAE,OAAO,EAAE,CAAC;YACxD,MAAM,YAAY,GAAG,KAA0B,CAAC;YAEhD,OAAO,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC;YAE5B,IAAI,YAAY,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBAC9B,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;gBACpE,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;gBACtE,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;YACjE,CAAC;YAED,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YAC3B,IAAI,KAAK,CAAC,eAAe,KAAK,aAAa;gBAAE,OAAO,EAAE,CAAC;YACvD,MAAM,aAAa,GAAG,KAAyB,CAAC;YAEhD,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,aAAa,CAAC,SAAS,EAAE,CAAC,CAAC;YAEjE,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,kBAAkB,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YAClC,IAAI,KAAK,CAAC,eAAe,KAAK,oBAAoB;gBAAE,OAAO,EAAE,CAAC;YAC9D,MAAM,YAAY,GAAG,KAAgC,CAAC;YAEtD,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,YAAY,CAAC,SAAS,EAAE,CAAC,CAAC;YACjE,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;YAEnD,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YAC3B,IAAI,KAAK,CAAC,eAAe,KAAK,aAAa;gBAAE,OAAO,EAAE,CAAC;YACvD,MAAM,iBAAiB,GAAG,KAAyB,CAAC;YAEpD,OAAO,CAAC,gBAAgB,CAAC,GAAG,EAAE,CAAC;YAE/B,kEAAkE;YAClE,kEAAkE;YAClE,+CAA+C;YAE/C,OAAO,EAAE,CAAC;QACZ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,CAAC,IAAI,sBAAsB,GAAoB,qBAAqB,EAAE,CAAC;AAE7E;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAyB;IACjE,sBAAsB,GAAG,QAAQ,CAAC;AACpC,CAAC"}
@@ -0,0 +1,161 @@
1
+ /**
2
+ * Observability Preset.
3
+ *
4
+ * Provides a convenience function for setting up complete observability
5
+ * in a single call, including logger, metrics, tracer, and hooks.
6
+ *
7
+ * @packageDocumentation
8
+ */
9
+ import { type LoggingHooksOptions } from "../hooks/logging.js";
10
+ import type { HookRegistration } from "../types.js";
11
+ import { type Logger, type LoggerOptions } from "./logger.js";
12
+ import { type AgentMetrics, type MetricsRegistry, type MetricsRegistryOptions } from "./metrics.js";
13
+ import { type SpanExporter, type Tracer, type TracerOptions } from "./tracing.js";
14
+ /**
15
+ * Options for creating an observability preset.
16
+ *
17
+ * @category Observability
18
+ */
19
+ export interface ObservabilityPresetOptions {
20
+ /**
21
+ * Name for the logger, tracer, and metrics (typically your agent name).
22
+ * @defaultValue "agent"
23
+ */
24
+ name?: string;
25
+ /**
26
+ * Whether to enable logging.
27
+ * @defaultValue true
28
+ */
29
+ enableLogging?: boolean;
30
+ /**
31
+ * Whether to enable metrics.
32
+ * @defaultValue true
33
+ */
34
+ enableMetrics?: boolean;
35
+ /**
36
+ * Whether to enable tracing.
37
+ * @defaultValue true
38
+ */
39
+ enableTracing?: boolean;
40
+ /**
41
+ * Whether to create hooks that wire the agent to the observability system.
42
+ * @defaultValue true
43
+ */
44
+ enableHooks?: boolean;
45
+ /**
46
+ * Logger options (overrides defaults).
47
+ */
48
+ loggerOptions?: Partial<LoggerOptions>;
49
+ /**
50
+ * Metrics registry options (overrides defaults).
51
+ */
52
+ metricsOptions?: Partial<MetricsRegistryOptions>;
53
+ /**
54
+ * Tracer options (overrides defaults).
55
+ */
56
+ tracerOptions?: Partial<TracerOptions>;
57
+ /**
58
+ * Logging hooks options (overrides defaults).
59
+ */
60
+ loggingHooksOptions?: Partial<LoggingHooksOptions>;
61
+ /**
62
+ * Custom span exporters for tracing.
63
+ * If not provided, defaults to console exporter.
64
+ */
65
+ spanExporters?: SpanExporter[];
66
+ }
67
+ /**
68
+ * Result of creating an observability preset.
69
+ *
70
+ * @category Observability
71
+ */
72
+ export interface ObservabilityPreset {
73
+ /**
74
+ * The logger instance (if enabled).
75
+ */
76
+ logger?: Logger;
77
+ /**
78
+ * The metrics registry (if enabled).
79
+ */
80
+ metricsRegistry?: MetricsRegistry;
81
+ /**
82
+ * Agent-specific metrics helpers (if metrics enabled).
83
+ */
84
+ metrics?: AgentMetrics;
85
+ /**
86
+ * The tracer instance (if enabled).
87
+ */
88
+ tracer?: Tracer;
89
+ /**
90
+ * Hook registration to pass to agent.hooks (if enabled).
91
+ */
92
+ hooks?: HookRegistration;
93
+ }
94
+ /**
95
+ * Creates a complete observability setup with logger, metrics, tracer, and hooks.
96
+ *
97
+ * This function provides a convenient way to set up comprehensive observability
98
+ * for your agent in a single call. It returns configured observability primitives
99
+ * and hooks that can be passed directly to `createAgent()`.
100
+ *
101
+ * @param options - Configuration options
102
+ * @returns Observability preset with logger, metrics, tracer, and hooks
103
+ *
104
+ * @example
105
+ * ```typescript
106
+ * import { createAgent, createObservabilityPreset } from "@lleverage-ai/agent-sdk";
107
+ * import { anthropic } from "@ai-sdk/anthropic";
108
+ *
109
+ * // One-line observability setup
110
+ * const observability = createObservabilityPreset({
111
+ * name: "my-agent",
112
+ * });
113
+ *
114
+ * // Create agent with full observability
115
+ * const agent = createAgent({
116
+ * model: anthropic("claude-sonnet-4-20250514"),
117
+ * hooks: observability.hooks,
118
+ * });
119
+ *
120
+ * // Access observability primitives
121
+ * observability.logger?.info("Agent started");
122
+ * observability.metrics?.requests.inc();
123
+ * const span = observability.tracer?.startSpan("custom-operation");
124
+ * ```
125
+ *
126
+ * @example
127
+
128
+ * ```typescript
129
+ * // Customize observability setup
130
+ * const observability = createObservabilityPreset({
131
+ * name: "my-agent",
132
+ * enableTracing: false, // Disable tracing
133
+ * loggerOptions: {
134
+ * level: "warn", // Only log warnings and errors
135
+ * },
136
+ * loggingHooksOptions: {
137
+ * logTiming: true,
138
+ * maxTextLength: 500,
139
+ * },
140
+ * });
141
+ * ```
142
+ *
143
+ * @example
144
+ * ```typescript
145
+ * // Export traces to OpenTelemetry collector
146
+ * import { createOTLPSpanExporter } from "@lleverage-ai/agent-sdk";
147
+ *
148
+ * const observability = createObservabilityPreset({
149
+ * name: "production-agent",
150
+ * spanExporters: [
151
+ * createOTLPSpanExporter({
152
+ * url: "http://localhost:4318/v1/traces",
153
+ * }),
154
+ * ],
155
+ * });
156
+ * ```
157
+ *
158
+ * @category Observability
159
+ */
160
+ export declare function createObservabilityPreset(options?: ObservabilityPresetOptions): ObservabilityPreset;
161
+ //# sourceMappingURL=preset.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"preset.d.ts","sourceRoot":"","sources":["../../src/observability/preset.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAmC,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAChG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAIL,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,YAAY,EAGjB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AAEtB;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAEvC;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAEjD;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAEvC;;OAEG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEnD;;;OAGG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;OAEG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,0BAA+B,GACvC,mBAAmB,CAyErB"}