@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,142 @@
1
+ /**
2
+ * KeyValueStore adapter for checkpoint saving.
3
+ *
4
+ * KeyValueStoreSaver wraps any {@link KeyValueStore} implementation to provide
5
+ * checkpoint persistence. This allows reusing existing storage backends like
6
+ * Redis, SQLite, or cloud storage for checkpoints.
7
+ *
8
+ * @example
9
+ * ```typescript
10
+ * import { InMemoryStore } from "@lleverage-ai/agent-sdk";
11
+ *
12
+ * const store = new InMemoryStore();
13
+ * const saver = new KeyValueStoreSaver({ store });
14
+ *
15
+ * // Save a checkpoint
16
+ * await saver.save(checkpoint);
17
+ *
18
+ * // Load it back
19
+ * const loaded = await saver.load("session-123");
20
+ * ```
21
+ *
22
+ * @packageDocumentation
23
+ */
24
+ import type { KeyValueStore } from "../backends/persistent.js";
25
+ import type { BaseCheckpointSaver, Checkpoint, CheckpointSaverOptions } from "./types.js";
26
+ /**
27
+ * Options for creating a KeyValueStoreSaver.
28
+ *
29
+ * @category Checkpointer
30
+ */
31
+ export interface KeyValueStoreSaverOptions extends CheckpointSaverOptions {
32
+ /**
33
+ * The key-value store to use for persistence.
34
+ *
35
+ * Can be any implementation of {@link KeyValueStore}, such as
36
+ * {@link InMemoryStore} for testing, or custom implementations
37
+ * for Redis, SQLite, etc.
38
+ */
39
+ store: KeyValueStore;
40
+ }
41
+ /**
42
+ * Checkpoint saver that wraps a KeyValueStore.
43
+ *
44
+ * Stores checkpoints at: `[namespace?, "checkpoints", threadId]`
45
+ *
46
+ * This adapter allows using any KeyValueStore implementation for checkpoint
47
+ * persistence, making it easy to integrate with existing storage systems.
48
+ *
49
+ * @example
50
+ * ```typescript
51
+ * // Use with InMemoryStore for testing
52
+ * import { InMemoryStore, KeyValueStoreSaver } from "@lleverage-ai/agent-sdk";
53
+ *
54
+ * const store = new InMemoryStore();
55
+ * const saver = new KeyValueStoreSaver({ store });
56
+ *
57
+ * await saver.save(checkpoint);
58
+ * const loaded = await saver.load("session-123");
59
+ *
60
+ * // Use with namespace for multi-tenant isolation
61
+ * const userSaver = new KeyValueStoreSaver({
62
+ * store,
63
+ * namespace: "user-456",
64
+ * });
65
+ * ```
66
+ *
67
+ * @category Checkpointer
68
+ */
69
+ export declare class KeyValueStoreSaver implements BaseCheckpointSaver {
70
+ private readonly store;
71
+ private readonly namespace?;
72
+ /**
73
+ * Create a new KeyValueStoreSaver.
74
+ *
75
+ * @param options - Configuration including the key-value store
76
+ */
77
+ constructor(options: KeyValueStoreSaverOptions);
78
+ /**
79
+ * Save a checkpoint to the key-value store.
80
+ *
81
+ * @param checkpoint - The checkpoint to save
82
+ */
83
+ save(checkpoint: Checkpoint): Promise<void>;
84
+ /**
85
+ * Load a checkpoint from the key-value store.
86
+ *
87
+ * @param threadId - The thread ID to load
88
+ * @returns The checkpoint if found and valid, undefined otherwise
89
+ */
90
+ load(threadId: string): Promise<Checkpoint | undefined>;
91
+ /**
92
+ * List all thread IDs that have checkpoints.
93
+ *
94
+ * @returns Array of thread IDs
95
+ */
96
+ list(): Promise<string[]>;
97
+ /**
98
+ * Delete a checkpoint from the key-value store.
99
+ *
100
+ * @param threadId - The thread ID to delete
101
+ * @returns True if a checkpoint was deleted, false if not found
102
+ */
103
+ delete(threadId: string): Promise<boolean>;
104
+ /**
105
+ * Check if a checkpoint exists in the key-value store.
106
+ *
107
+ * @param threadId - The thread ID to check
108
+ * @returns True if the checkpoint exists
109
+ */
110
+ exists(threadId: string): Promise<boolean>;
111
+ /**
112
+ * Get the namespace array for the key-value store.
113
+ *
114
+ * @internal
115
+ */
116
+ private getNamespace;
117
+ }
118
+ /**
119
+ * Create a new KeyValueStoreSaver instance.
120
+ *
121
+ * @param options - Configuration including the key-value store
122
+ * @returns A new KeyValueStoreSaver instance
123
+ *
124
+ * @example
125
+ * ```typescript
126
+ * import { InMemoryStore, createKeyValueStoreSaver } from "@lleverage-ai/agent-sdk";
127
+ *
128
+ * // Basic usage with InMemoryStore
129
+ * const store = new InMemoryStore();
130
+ * const saver = createKeyValueStoreSaver({ store });
131
+ *
132
+ * // With namespace for isolation
133
+ * const userSaver = createKeyValueStoreSaver({
134
+ * store,
135
+ * namespace: "user-123",
136
+ * });
137
+ * ```
138
+ *
139
+ * @category Checkpointer
140
+ */
141
+ export declare function createKeyValueStoreSaver(options: KeyValueStoreSaverOptions): KeyValueStoreSaver;
142
+ //# sourceMappingURL=kv-saver.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"kv-saver.d.ts","sourceRoot":"","sources":["../../src/checkpointer/kv-saver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAO1F;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,sBAAsB;IACvE;;;;;;OAMG;IACH,KAAK,EAAE,aAAa,CAAC;CACtB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IAEpC;;;;OAIG;gBACS,OAAO,EAAE,yBAAyB;IAK9C;;;;OAIG;IACG,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAQjD;;;;;OAKG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAiB7D;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAO/B;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAahD;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUhD;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAGrB;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CAE/F"}
@@ -0,0 +1,176 @@
1
+ /**
2
+ * KeyValueStore adapter for checkpoint saving.
3
+ *
4
+ * KeyValueStoreSaver wraps any {@link KeyValueStore} implementation to provide
5
+ * checkpoint persistence. This allows reusing existing storage backends like
6
+ * Redis, SQLite, or cloud storage for checkpoints.
7
+ *
8
+ * @example
9
+ * ```typescript
10
+ * import { InMemoryStore } from "@lleverage-ai/agent-sdk";
11
+ *
12
+ * const store = new InMemoryStore();
13
+ * const saver = new KeyValueStoreSaver({ store });
14
+ *
15
+ * // Save a checkpoint
16
+ * await saver.save(checkpoint);
17
+ *
18
+ * // Load it back
19
+ * const loaded = await saver.load("session-123");
20
+ * ```
21
+ *
22
+ * @packageDocumentation
23
+ */
24
+ import { isCheckpoint } from "./types.js";
25
+ // =============================================================================
26
+ // KeyValueStoreSaver Implementation
27
+ // =============================================================================
28
+ /**
29
+ * Checkpoint saver that wraps a KeyValueStore.
30
+ *
31
+ * Stores checkpoints at: `[namespace?, "checkpoints", threadId]`
32
+ *
33
+ * This adapter allows using any KeyValueStore implementation for checkpoint
34
+ * persistence, making it easy to integrate with existing storage systems.
35
+ *
36
+ * @example
37
+ * ```typescript
38
+ * // Use with InMemoryStore for testing
39
+ * import { InMemoryStore, KeyValueStoreSaver } from "@lleverage-ai/agent-sdk";
40
+ *
41
+ * const store = new InMemoryStore();
42
+ * const saver = new KeyValueStoreSaver({ store });
43
+ *
44
+ * await saver.save(checkpoint);
45
+ * const loaded = await saver.load("session-123");
46
+ *
47
+ * // Use with namespace for multi-tenant isolation
48
+ * const userSaver = new KeyValueStoreSaver({
49
+ * store,
50
+ * namespace: "user-456",
51
+ * });
52
+ * ```
53
+ *
54
+ * @category Checkpointer
55
+ */
56
+ export class KeyValueStoreSaver {
57
+ store;
58
+ namespace;
59
+ /**
60
+ * Create a new KeyValueStoreSaver.
61
+ *
62
+ * @param options - Configuration including the key-value store
63
+ */
64
+ constructor(options) {
65
+ this.store = options.store;
66
+ this.namespace = options.namespace;
67
+ }
68
+ /**
69
+ * Save a checkpoint to the key-value store.
70
+ *
71
+ * @param checkpoint - The checkpoint to save
72
+ */
73
+ async save(checkpoint) {
74
+ const storeNamespace = this.getNamespace();
75
+ const key = checkpoint.threadId;
76
+ // Store checkpoint as a record (the KV store will handle serialization)
77
+ await this.store.put(storeNamespace, key, checkpoint);
78
+ }
79
+ /**
80
+ * Load a checkpoint from the key-value store.
81
+ *
82
+ * @param threadId - The thread ID to load
83
+ * @returns The checkpoint if found and valid, undefined otherwise
84
+ */
85
+ async load(threadId) {
86
+ const storeNamespace = this.getNamespace();
87
+ const data = await this.store.get(storeNamespace, threadId);
88
+ if (!data) {
89
+ return undefined;
90
+ }
91
+ // Validate the loaded data
92
+ if (!isCheckpoint(data)) {
93
+ console.warn(`Invalid checkpoint data for thread ${threadId}, expected Checkpoint object`);
94
+ return undefined;
95
+ }
96
+ return data;
97
+ }
98
+ /**
99
+ * List all thread IDs that have checkpoints.
100
+ *
101
+ * @returns Array of thread IDs
102
+ */
103
+ async list() {
104
+ const storeNamespace = this.getNamespace();
105
+ const entries = await this.store.list(storeNamespace);
106
+ return entries.map((entry) => entry.key);
107
+ }
108
+ /**
109
+ * Delete a checkpoint from the key-value store.
110
+ *
111
+ * @param threadId - The thread ID to delete
112
+ * @returns True if a checkpoint was deleted, false if not found
113
+ */
114
+ async delete(threadId) {
115
+ const storeNamespace = this.getNamespace();
116
+ // Check if it exists first
117
+ const exists = await this.exists(threadId);
118
+ if (!exists) {
119
+ return false;
120
+ }
121
+ await this.store.delete(storeNamespace, threadId);
122
+ return true;
123
+ }
124
+ /**
125
+ * Check if a checkpoint exists in the key-value store.
126
+ *
127
+ * @param threadId - The thread ID to check
128
+ * @returns True if the checkpoint exists
129
+ */
130
+ async exists(threadId) {
131
+ const storeNamespace = this.getNamespace();
132
+ const data = await this.store.get(storeNamespace, threadId);
133
+ return data !== undefined;
134
+ }
135
+ // ===========================================================================
136
+ // Private Helpers
137
+ // ===========================================================================
138
+ /**
139
+ * Get the namespace array for the key-value store.
140
+ *
141
+ * @internal
142
+ */
143
+ getNamespace() {
144
+ return this.namespace ? [this.namespace, "checkpoints"] : ["checkpoints"];
145
+ }
146
+ }
147
+ // =============================================================================
148
+ // Factory Function
149
+ // =============================================================================
150
+ /**
151
+ * Create a new KeyValueStoreSaver instance.
152
+ *
153
+ * @param options - Configuration including the key-value store
154
+ * @returns A new KeyValueStoreSaver instance
155
+ *
156
+ * @example
157
+ * ```typescript
158
+ * import { InMemoryStore, createKeyValueStoreSaver } from "@lleverage-ai/agent-sdk";
159
+ *
160
+ * // Basic usage with InMemoryStore
161
+ * const store = new InMemoryStore();
162
+ * const saver = createKeyValueStoreSaver({ store });
163
+ *
164
+ * // With namespace for isolation
165
+ * const userSaver = createKeyValueStoreSaver({
166
+ * store,
167
+ * namespace: "user-123",
168
+ * });
169
+ * ```
170
+ *
171
+ * @category Checkpointer
172
+ */
173
+ export function createKeyValueStoreSaver(options) {
174
+ return new KeyValueStoreSaver(options);
175
+ }
176
+ //# sourceMappingURL=kv-saver.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"kv-saver.js","sourceRoot":"","sources":["../../src/checkpointer/kv-saver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAsB1C,gFAAgF;AAChF,oCAAoC;AACpC,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,kBAAkB;IACZ,KAAK,CAAgB;IACrB,SAAS,CAAU;IAEpC;;;;OAIG;IACH,YAAY,OAAkC;QAC5C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,UAAsB;QAC/B,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC;QAEhC,wEAAwE;QACxE,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,EAAE,GAAG,EAAE,UAAgD,CAAC,CAAC;IAC9F,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,QAAgB;QACzB,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;QAE5D,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,2BAA2B;QAC3B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,sCAAsC,QAAQ,8BAA8B,CAAC,CAAC;YAC3F,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAEtD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,QAAgB;QAC3B,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAE3C,2BAA2B;QAC3B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,QAAgB;QAC3B,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;QAC5D,OAAO,IAAI,KAAK,SAAS,CAAC;IAC5B,CAAC;IAED,8EAA8E;IAC9E,kBAAkB;IAClB,8EAA8E;IAE9E;;;;OAIG;IACK,YAAY;QAClB,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAC5E,CAAC;CACF;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAkC;IACzE,OAAO,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;AACzC,CAAC"}
@@ -0,0 +1,158 @@
1
+ /**
2
+ * In-memory checkpoint saver for ephemeral storage.
3
+ *
4
+ * MemorySaver stores checkpoints in a Map, making it ideal for:
5
+ * - Development and testing
6
+ * - Single-session applications
7
+ * - Scenarios where persistence is not required
8
+ *
9
+ * Note: All data is lost when the process ends.
10
+ *
11
+ * @example
12
+ * ```typescript
13
+ * const saver = new MemorySaver();
14
+ *
15
+ * // Save a checkpoint
16
+ * await saver.save({
17
+ * threadId: "session-123",
18
+ * messages: [...],
19
+ * state: { todos: [], files: {} },
20
+ * step: 0,
21
+ * createdAt: new Date().toISOString(),
22
+ * updatedAt: new Date().toISOString(),
23
+ * });
24
+ *
25
+ * // Load it back
26
+ * const checkpoint = await saver.load("session-123");
27
+ * ```
28
+ *
29
+ * @packageDocumentation
30
+ */
31
+ import type { BaseCheckpointSaver, Checkpoint, CheckpointSaverOptions } from "./types.js";
32
+ /**
33
+ * Options for creating a MemorySaver.
34
+ *
35
+ * @category Checkpointer
36
+ */
37
+ export interface MemorySaverOptions extends CheckpointSaverOptions {
38
+ /**
39
+ * Initial checkpoints to populate the store with.
40
+ * Useful for testing or restoring from a backup.
41
+ */
42
+ initialCheckpoints?: Checkpoint[];
43
+ }
44
+ /**
45
+ * In-memory checkpoint saver.
46
+ *
47
+ * Stores checkpoints in a JavaScript Map for fast access.
48
+ * All data is ephemeral and lost when the process terminates.
49
+ *
50
+ * @example
51
+ * ```typescript
52
+ * const saver = new MemorySaver();
53
+ *
54
+ * // Save a checkpoint
55
+ * await saver.save(checkpoint);
56
+ *
57
+ * // List all threads
58
+ * const threads = await saver.list();
59
+ *
60
+ * // Load a specific thread
61
+ * const loaded = await saver.load(threads[0]);
62
+ *
63
+ * // Delete when done
64
+ * await saver.delete(threads[0]);
65
+ * ```
66
+ *
67
+ * @category Checkpointer
68
+ */
69
+ export declare class MemorySaver implements BaseCheckpointSaver {
70
+ private readonly checkpoints;
71
+ private readonly namespace?;
72
+ /**
73
+ * Create a new MemorySaver.
74
+ *
75
+ * @param options - Optional configuration
76
+ */
77
+ constructor(options?: MemorySaverOptions);
78
+ /**
79
+ * Save a checkpoint.
80
+ *
81
+ * If a checkpoint with the same threadId exists, it will be overwritten.
82
+ * The checkpoint is deep-copied to prevent external mutation.
83
+ *
84
+ * @param checkpoint - The checkpoint to save
85
+ */
86
+ save(checkpoint: Checkpoint): Promise<void>;
87
+ /**
88
+ * Load a checkpoint by thread ID.
89
+ *
90
+ * Returns a deep copy to prevent external mutation of stored data.
91
+ *
92
+ * @param threadId - The thread ID to load
93
+ * @returns The checkpoint if found, undefined otherwise
94
+ */
95
+ load(threadId: string): Promise<Checkpoint | undefined>;
96
+ /**
97
+ * List all thread IDs that have checkpoints.
98
+ *
99
+ * If a namespace is configured, only returns threads within that namespace.
100
+ *
101
+ * @returns Array of thread IDs
102
+ */
103
+ list(): Promise<string[]>;
104
+ /**
105
+ * Delete a checkpoint.
106
+ *
107
+ * @param threadId - The thread ID to delete
108
+ * @returns True if a checkpoint was deleted, false if not found
109
+ */
110
+ delete(threadId: string): Promise<boolean>;
111
+ /**
112
+ * Check if a checkpoint exists.
113
+ *
114
+ * @param threadId - The thread ID to check
115
+ * @returns True if the checkpoint exists
116
+ */
117
+ exists(threadId: string): Promise<boolean>;
118
+ /**
119
+ * Get the number of stored checkpoints.
120
+ *
121
+ * If a namespace is configured, returns count within that namespace only.
122
+ */
123
+ get size(): number;
124
+ /**
125
+ * Clear all stored checkpoints.
126
+ *
127
+ * If a namespace is configured, only clears checkpoints within that namespace.
128
+ */
129
+ clear(): void;
130
+ /**
131
+ * Get the storage key for a thread ID.
132
+ * @internal
133
+ */
134
+ private getKey;
135
+ /**
136
+ * Deep copy a checkpoint to prevent mutation.
137
+ * @internal
138
+ */
139
+ private deepCopy;
140
+ }
141
+ /**
142
+ * Create a new MemorySaver instance.
143
+ *
144
+ * @param options - Optional configuration
145
+ * @returns A new MemorySaver instance
146
+ *
147
+ * @example
148
+ * ```typescript
149
+ * const saver = createMemorySaver();
150
+ *
151
+ * // Or with namespace for multi-tenant isolation
152
+ * const userSaver = createMemorySaver({ namespace: "user-123" });
153
+ * ```
154
+ *
155
+ * @category Checkpointer
156
+ */
157
+ export declare function createMemorySaver(options?: MemorySaverOptions): MemorySaver;
158
+ //# sourceMappingURL=memory-saver.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"memory-saver.d.ts","sourceRoot":"","sources":["../../src/checkpointer/memory-saver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAE1F;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB;IAChE;;;OAGG;IACH,kBAAkB,CAAC,EAAE,UAAU,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,WAAY,YAAW,mBAAmB;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IAEpC;;;;OAIG;gBACS,OAAO,CAAC,EAAE,kBAAkB;IAaxC;;;;;;;OAOG;IACG,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjD;;;;;;;OAOG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAO7D;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAiB/B;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKhD;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAShD;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,CAajB;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAkBb;;;OAGG;IACH,OAAO,CAAC,MAAM;IAId;;;OAGG;IACH,OAAO,CAAC,QAAQ;CAGjB;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAE3E"}