@strands-agents/sdk 0.5.0 → 0.7.0

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 (486) hide show
  1. package/README.md +64 -0
  2. package/dist/src/__fixtures__/agent-helpers.d.ts +37 -4
  3. package/dist/src/__fixtures__/agent-helpers.d.ts.map +1 -1
  4. package/dist/src/__fixtures__/agent-helpers.js +31 -4
  5. package/dist/src/__fixtures__/agent-helpers.js.map +1 -1
  6. package/dist/src/__fixtures__/metrics-helpers.d.ts +55 -0
  7. package/dist/src/__fixtures__/metrics-helpers.d.ts.map +1 -0
  8. package/dist/src/__fixtures__/metrics-helpers.js +57 -0
  9. package/dist/src/__fixtures__/metrics-helpers.js.map +1 -0
  10. package/dist/src/__fixtures__/mock-message-model.d.ts +8 -4
  11. package/dist/src/__fixtures__/mock-message-model.d.ts.map +1 -1
  12. package/dist/src/__fixtures__/mock-message-model.js +25 -7
  13. package/dist/src/__fixtures__/mock-message-model.js.map +1 -1
  14. package/dist/src/__fixtures__/mock-meter.d.ts +32 -0
  15. package/dist/src/__fixtures__/mock-meter.d.ts.map +1 -0
  16. package/dist/src/__fixtures__/mock-meter.js +47 -0
  17. package/dist/src/__fixtures__/mock-meter.js.map +1 -0
  18. package/dist/src/__fixtures__/mock-plugin.d.ts +13 -0
  19. package/dist/src/__fixtures__/mock-plugin.d.ts.map +1 -0
  20. package/dist/src/__fixtures__/{mock-hook-provider.js → mock-plugin.js} +8 -5
  21. package/dist/src/__fixtures__/mock-plugin.js.map +1 -0
  22. package/dist/src/__fixtures__/mock-storage-provider.d.ts +5 -0
  23. package/dist/src/__fixtures__/mock-storage-provider.d.ts.map +1 -1
  24. package/dist/src/__fixtures__/mock-storage-provider.js +23 -6
  25. package/dist/src/__fixtures__/mock-storage-provider.js.map +1 -1
  26. package/dist/src/__fixtures__/slim-types.d.ts +2 -1
  27. package/dist/src/__fixtures__/slim-types.d.ts.map +1 -1
  28. package/dist/src/__fixtures__/tool-helpers.d.ts.map +1 -1
  29. package/dist/src/__fixtures__/tool-helpers.js +5 -2
  30. package/dist/src/__fixtures__/tool-helpers.js.map +1 -1
  31. package/dist/src/__tests__/index.test.js +21 -0
  32. package/dist/src/__tests__/index.test.js.map +1 -1
  33. package/dist/src/__tests__/mcp.test.js +45 -15
  34. package/dist/src/__tests__/mcp.test.js.map +1 -1
  35. package/dist/src/__tests__/mime.test.d.ts +2 -0
  36. package/dist/src/__tests__/mime.test.d.ts.map +1 -0
  37. package/dist/src/__tests__/mime.test.js +83 -0
  38. package/dist/src/__tests__/mime.test.js.map +1 -0
  39. package/dist/src/__tests__/state-store.test.d.ts +2 -0
  40. package/dist/src/__tests__/state-store.test.d.ts.map +1 -0
  41. package/dist/src/__tests__/{app-state.test.js → state-store.test.js} +86 -51
  42. package/dist/src/__tests__/state-store.test.js.map +1 -0
  43. package/dist/src/a2a/__tests__/a2a-agent.test.d.ts +2 -0
  44. package/dist/src/a2a/__tests__/a2a-agent.test.d.ts.map +1 -0
  45. package/dist/src/a2a/__tests__/a2a-agent.test.js +364 -0
  46. package/dist/src/a2a/__tests__/a2a-agent.test.js.map +1 -0
  47. package/dist/src/a2a/__tests__/adapters.test.d.ts +2 -0
  48. package/dist/src/a2a/__tests__/adapters.test.d.ts.map +1 -0
  49. package/dist/src/a2a/__tests__/adapters.test.js +151 -0
  50. package/dist/src/a2a/__tests__/adapters.test.js.map +1 -0
  51. package/dist/src/a2a/__tests__/executor.test.d.ts +2 -0
  52. package/dist/src/a2a/__tests__/executor.test.d.ts.map +1 -0
  53. package/dist/src/a2a/__tests__/executor.test.js +196 -0
  54. package/dist/src/a2a/__tests__/executor.test.js.map +1 -0
  55. package/dist/src/a2a/__tests__/server.test.d.ts +2 -0
  56. package/dist/src/a2a/__tests__/server.test.d.ts.map +1 -0
  57. package/dist/src/a2a/__tests__/server.test.js +51 -0
  58. package/dist/src/a2a/__tests__/server.test.js.map +1 -0
  59. package/dist/src/a2a/__tests__/server.test.node.d.ts +2 -0
  60. package/dist/src/a2a/__tests__/server.test.node.d.ts.map +1 -0
  61. package/dist/src/a2a/__tests__/server.test.node.js +110 -0
  62. package/dist/src/a2a/__tests__/server.test.node.js.map +1 -0
  63. package/dist/src/a2a/a2a-agent.d.ts +132 -0
  64. package/dist/src/a2a/a2a-agent.d.ts.map +1 -0
  65. package/dist/src/a2a/a2a-agent.js +255 -0
  66. package/dist/src/a2a/a2a-agent.js.map +1 -0
  67. package/dist/src/a2a/adapters.d.ts +27 -0
  68. package/dist/src/a2a/adapters.d.ts.map +1 -0
  69. package/dist/src/a2a/adapters.js +175 -0
  70. package/dist/src/a2a/adapters.js.map +1 -0
  71. package/dist/src/a2a/events.d.ts +42 -0
  72. package/dist/src/a2a/events.d.ts.map +1 -0
  73. package/dist/src/a2a/events.js +35 -0
  74. package/dist/src/a2a/events.js.map +1 -0
  75. package/dist/src/a2a/executor.d.ts +57 -0
  76. package/dist/src/a2a/executor.d.ts.map +1 -0
  77. package/dist/src/a2a/executor.js +130 -0
  78. package/dist/src/a2a/executor.js.map +1 -0
  79. package/dist/src/a2a/express-server.d.ts +67 -0
  80. package/dist/src/a2a/express-server.d.ts.map +1 -0
  81. package/dist/src/a2a/express-server.js +95 -0
  82. package/dist/src/a2a/express-server.js.map +1 -0
  83. package/dist/src/a2a/index.d.ts +16 -0
  84. package/dist/src/a2a/index.d.ts.map +1 -0
  85. package/dist/src/a2a/index.js +16 -0
  86. package/dist/src/a2a/index.js.map +1 -0
  87. package/dist/src/a2a/logging.d.ts +8 -0
  88. package/dist/src/a2a/logging.d.ts.map +1 -0
  89. package/dist/src/a2a/logging.js +15 -0
  90. package/dist/src/a2a/logging.js.map +1 -0
  91. package/dist/src/a2a/server.d.ts +67 -0
  92. package/dist/src/a2a/server.d.ts.map +1 -0
  93. package/dist/src/a2a/server.js +67 -0
  94. package/dist/src/a2a/server.js.map +1 -0
  95. package/dist/src/agent/__tests__/agent.hook.test.js +87 -51
  96. package/dist/src/agent/__tests__/agent.hook.test.js.map +1 -1
  97. package/dist/src/agent/__tests__/agent.test.js +176 -101
  98. package/dist/src/agent/__tests__/agent.test.js.map +1 -1
  99. package/dist/src/agent/__tests__/agent.tracer.test.js +10 -10
  100. package/dist/src/agent/__tests__/agent.tracer.test.js.map +1 -1
  101. package/dist/src/agent/__tests__/snapshot.test.js +11 -11
  102. package/dist/src/agent/__tests__/snapshot.test.js.map +1 -1
  103. package/dist/src/agent/agent.d.ts +71 -58
  104. package/dist/src/agent/agent.d.ts.map +1 -1
  105. package/dist/src/agent/agent.js +177 -93
  106. package/dist/src/agent/agent.js.map +1 -1
  107. package/dist/src/agent/snapshot.d.ts.map +1 -1
  108. package/dist/src/agent/snapshot.js +3 -2
  109. package/dist/src/agent/snapshot.js.map +1 -1
  110. package/dist/src/conversation-manager/__tests__/conversation-manager.test.d.ts +2 -0
  111. package/dist/src/conversation-manager/__tests__/conversation-manager.test.d.ts.map +1 -0
  112. package/dist/src/conversation-manager/__tests__/conversation-manager.test.js +100 -0
  113. package/dist/src/conversation-manager/__tests__/conversation-manager.test.js.map +1 -0
  114. package/dist/src/conversation-manager/__tests__/null-conversation-manager.test.js +26 -10
  115. package/dist/src/conversation-manager/__tests__/null-conversation-manager.test.js.map +1 -1
  116. package/dist/src/conversation-manager/__tests__/sliding-window-conversation-manager.test.js +84 -21
  117. package/dist/src/conversation-manager/__tests__/sliding-window-conversation-manager.test.js.map +1 -1
  118. package/dist/src/conversation-manager/conversation-manager.d.ts +87 -0
  119. package/dist/src/conversation-manager/conversation-manager.d.ts.map +1 -0
  120. package/dist/src/conversation-manager/conversation-manager.js +59 -0
  121. package/dist/src/conversation-manager/conversation-manager.js.map +1 -0
  122. package/dist/src/conversation-manager/index.d.ts +1 -0
  123. package/dist/src/conversation-manager/index.d.ts.map +1 -1
  124. package/dist/src/conversation-manager/index.js +1 -0
  125. package/dist/src/conversation-manager/index.js.map +1 -1
  126. package/dist/src/conversation-manager/null-conversation-manager.d.ts +12 -8
  127. package/dist/src/conversation-manager/null-conversation-manager.d.ts.map +1 -1
  128. package/dist/src/conversation-manager/null-conversation-manager.js +13 -7
  129. package/dist/src/conversation-manager/null-conversation-manager.js.map +1 -1
  130. package/dist/src/conversation-manager/sliding-window-conversation-manager.d.ts +28 -19
  131. package/dist/src/conversation-manager/sliding-window-conversation-manager.d.ts.map +1 -1
  132. package/dist/src/conversation-manager/sliding-window-conversation-manager.js +44 -36
  133. package/dist/src/conversation-manager/sliding-window-conversation-manager.js.map +1 -1
  134. package/dist/src/errors.d.ts +6 -0
  135. package/dist/src/errors.d.ts.map +1 -1
  136. package/dist/src/errors.js +9 -0
  137. package/dist/src/errors.js.map +1 -1
  138. package/dist/src/hooks/__tests__/events.test.js +2 -0
  139. package/dist/src/hooks/__tests__/events.test.js.map +1 -1
  140. package/dist/src/hooks/__tests__/registry.test.js +10 -154
  141. package/dist/src/hooks/__tests__/registry.test.js.map +1 -1
  142. package/dist/src/hooks/events.d.ts +60 -44
  143. package/dist/src/hooks/events.d.ts.map +1 -1
  144. package/dist/src/hooks/events.js +11 -11
  145. package/dist/src/hooks/events.js.map +1 -1
  146. package/dist/src/hooks/index.d.ts +4 -4
  147. package/dist/src/hooks/index.d.ts.map +1 -1
  148. package/dist/src/hooks/index.js +2 -2
  149. package/dist/src/hooks/registry.d.ts +1 -32
  150. package/dist/src/hooks/registry.d.ts.map +1 -1
  151. package/dist/src/hooks/registry.js +1 -47
  152. package/dist/src/hooks/registry.js.map +1 -1
  153. package/dist/src/hooks/types.d.ts +0 -31
  154. package/dist/src/hooks/types.d.ts.map +1 -1
  155. package/dist/src/index.d.ts +30 -15
  156. package/dist/src/index.d.ts.map +1 -1
  157. package/dist/src/index.js +21 -8
  158. package/dist/src/index.js.map +1 -1
  159. package/dist/src/mcp.d.ts +38 -0
  160. package/dist/src/mcp.d.ts.map +1 -1
  161. package/dist/src/mcp.js +23 -6
  162. package/dist/src/mcp.js.map +1 -1
  163. package/dist/src/mime.d.ts +24 -0
  164. package/dist/src/mime.d.ts.map +1 -0
  165. package/dist/src/mime.js +82 -0
  166. package/dist/src/mime.js.map +1 -0
  167. package/dist/src/models/__tests__/anthropic.test.js +78 -1
  168. package/dist/src/models/__tests__/anthropic.test.js.map +1 -1
  169. package/dist/src/models/__tests__/bedrock.test.js +2050 -131
  170. package/dist/src/models/__tests__/bedrock.test.js.map +1 -1
  171. package/dist/src/models/__tests__/gemini.test.js +100 -1
  172. package/dist/src/models/__tests__/gemini.test.js.map +1 -1
  173. package/dist/src/models/__tests__/model.test.js +131 -0
  174. package/dist/src/models/__tests__/model.test.js.map +1 -1
  175. package/dist/src/models/__tests__/openai.test.js +184 -32
  176. package/dist/src/models/__tests__/openai.test.js.map +1 -1
  177. package/dist/src/models/__tests__/streaming.test.d.ts +2 -0
  178. package/dist/src/models/__tests__/streaming.test.d.ts.map +1 -0
  179. package/dist/src/models/__tests__/streaming.test.js +50 -0
  180. package/dist/src/models/__tests__/streaming.test.js.map +1 -0
  181. package/dist/src/models/anthropic.d.ts.map +1 -1
  182. package/dist/src/models/anthropic.js +6 -7
  183. package/dist/src/models/anthropic.js.map +1 -1
  184. package/dist/src/models/bedrock.d.ts +144 -11
  185. package/dist/src/models/bedrock.d.ts.map +1 -1
  186. package/dist/src/models/bedrock.js +416 -28
  187. package/dist/src/models/bedrock.js.map +1 -1
  188. package/dist/src/models/gemini/adapters.d.ts.map +1 -1
  189. package/dist/src/models/gemini/adapters.js +65 -14
  190. package/dist/src/models/gemini/adapters.js.map +1 -1
  191. package/dist/src/models/model.d.ts +18 -0
  192. package/dist/src/models/model.d.ts.map +1 -1
  193. package/dist/src/models/model.js +57 -11
  194. package/dist/src/models/model.js.map +1 -1
  195. package/dist/src/models/openai.d.ts +15 -0
  196. package/dist/src/models/openai.d.ts.map +1 -1
  197. package/dist/src/models/openai.js +108 -64
  198. package/dist/src/models/openai.js.map +1 -1
  199. package/dist/src/models/streaming.d.ts +88 -2
  200. package/dist/src/models/streaming.d.ts.map +1 -1
  201. package/dist/src/models/streaming.js +26 -0
  202. package/dist/src/models/streaming.js.map +1 -1
  203. package/dist/src/multiagent/__tests__/events.test.js +41 -8
  204. package/dist/src/multiagent/__tests__/events.test.js.map +1 -1
  205. package/dist/src/multiagent/__tests__/graph.test.d.ts +2 -0
  206. package/dist/src/multiagent/__tests__/graph.test.d.ts.map +1 -0
  207. package/dist/src/multiagent/__tests__/graph.test.js +453 -0
  208. package/dist/src/multiagent/__tests__/graph.test.js.map +1 -0
  209. package/dist/src/multiagent/__tests__/nodes.test.js +34 -16
  210. package/dist/src/multiagent/__tests__/nodes.test.js.map +1 -1
  211. package/dist/src/multiagent/__tests__/queue.test.js +22 -0
  212. package/dist/src/multiagent/__tests__/queue.test.js.map +1 -1
  213. package/dist/src/multiagent/__tests__/swarm.test.d.ts +2 -0
  214. package/dist/src/multiagent/__tests__/swarm.test.d.ts.map +1 -0
  215. package/dist/src/multiagent/__tests__/swarm.test.js +264 -0
  216. package/dist/src/multiagent/__tests__/swarm.test.js.map +1 -0
  217. package/dist/src/multiagent/edge.d.ts +9 -2
  218. package/dist/src/multiagent/edge.d.ts.map +1 -1
  219. package/dist/src/multiagent/events.d.ts +63 -15
  220. package/dist/src/multiagent/events.d.ts.map +1 -1
  221. package/dist/src/multiagent/events.js +28 -3
  222. package/dist/src/multiagent/events.js.map +1 -1
  223. package/dist/src/multiagent/graph.d.ts +135 -0
  224. package/dist/src/multiagent/graph.d.ts.map +1 -0
  225. package/dist/src/multiagent/graph.js +400 -0
  226. package/dist/src/multiagent/graph.js.map +1 -0
  227. package/dist/src/multiagent/index.d.ts +8 -3
  228. package/dist/src/multiagent/index.d.ts.map +1 -1
  229. package/dist/src/multiagent/index.js +3 -1
  230. package/dist/src/multiagent/index.js.map +1 -1
  231. package/dist/src/multiagent/multiagent.d.ts +41 -0
  232. package/dist/src/multiagent/multiagent.d.ts.map +1 -0
  233. package/dist/src/multiagent/multiagent.js +2 -0
  234. package/dist/src/multiagent/multiagent.js.map +1 -0
  235. package/dist/src/multiagent/nodes.d.ts +24 -25
  236. package/dist/src/multiagent/nodes.d.ts.map +1 -1
  237. package/dist/src/multiagent/nodes.js +42 -15
  238. package/dist/src/multiagent/nodes.js.map +1 -1
  239. package/dist/src/multiagent/plugins.d.ts +70 -0
  240. package/dist/src/multiagent/plugins.d.ts.map +1 -0
  241. package/dist/src/multiagent/plugins.js +70 -0
  242. package/dist/src/multiagent/plugins.js.map +1 -0
  243. package/dist/src/multiagent/queue.d.ts +6 -0
  244. package/dist/src/multiagent/queue.d.ts.map +1 -1
  245. package/dist/src/multiagent/queue.js +13 -0
  246. package/dist/src/multiagent/queue.js.map +1 -1
  247. package/dist/src/multiagent/state.d.ts +4 -2
  248. package/dist/src/multiagent/state.d.ts.map +1 -1
  249. package/dist/src/multiagent/state.js +5 -2
  250. package/dist/src/multiagent/state.js.map +1 -1
  251. package/dist/src/multiagent/swarm.d.ts +112 -0
  252. package/dist/src/multiagent/swarm.d.ts.map +1 -0
  253. package/dist/src/multiagent/swarm.js +256 -0
  254. package/dist/src/multiagent/swarm.js.map +1 -0
  255. package/dist/src/plugins/__tests__/plugin.test.d.ts +2 -0
  256. package/dist/src/plugins/__tests__/plugin.test.d.ts.map +1 -0
  257. package/dist/src/plugins/__tests__/plugin.test.js +114 -0
  258. package/dist/src/plugins/__tests__/plugin.test.js.map +1 -0
  259. package/dist/src/plugins/__tests__/registry.test.d.ts +2 -0
  260. package/dist/src/plugins/__tests__/registry.test.d.ts.map +1 -0
  261. package/dist/src/plugins/__tests__/registry.test.js +147 -0
  262. package/dist/src/plugins/__tests__/registry.test.js.map +1 -0
  263. package/dist/src/plugins/index.d.ts +30 -0
  264. package/dist/src/plugins/index.d.ts.map +1 -0
  265. package/dist/src/plugins/index.js +30 -0
  266. package/dist/src/plugins/index.js.map +1 -0
  267. package/dist/src/plugins/plugin.d.ts +74 -0
  268. package/dist/src/plugins/plugin.d.ts.map +1 -0
  269. package/dist/src/plugins/plugin.js +8 -0
  270. package/dist/src/plugins/plugin.js.map +1 -0
  271. package/dist/src/plugins/registry.d.ts +25 -0
  272. package/dist/src/plugins/registry.d.ts.map +1 -0
  273. package/dist/src/plugins/registry.js +41 -0
  274. package/dist/src/plugins/registry.js.map +1 -0
  275. package/dist/src/registry/__tests__/tool-registry.test.d.ts +2 -0
  276. package/dist/src/registry/__tests__/tool-registry.test.d.ts.map +1 -0
  277. package/dist/src/registry/__tests__/tool-registry.test.js +124 -0
  278. package/dist/src/registry/__tests__/tool-registry.test.js.map +1 -0
  279. package/dist/src/registry/tool-registry.d.ts +32 -20
  280. package/dist/src/registry/tool-registry.d.ts.map +1 -1
  281. package/dist/src/registry/tool-registry.js +60 -158
  282. package/dist/src/registry/tool-registry.js.map +1 -1
  283. package/dist/src/session/__tests__/file-storage.test.node.js +75 -15
  284. package/dist/src/session/__tests__/file-storage.test.node.js.map +1 -1
  285. package/dist/src/session/__tests__/s3-storage.test.d.ts +2 -0
  286. package/dist/src/session/__tests__/s3-storage.test.d.ts.map +1 -0
  287. package/dist/src/session/__tests__/{s3-storage.test.node.js → s3-storage.test.js} +161 -75
  288. package/dist/src/session/__tests__/s3-storage.test.js.map +1 -0
  289. package/dist/src/session/__tests__/session-manager.test.d.ts +2 -0
  290. package/dist/src/session/__tests__/session-manager.test.d.ts.map +1 -0
  291. package/dist/src/session/__tests__/session-manager.test.js +443 -0
  292. package/dist/src/session/__tests__/session-manager.test.js.map +1 -0
  293. package/dist/src/session/__tests__/validation.test.js +28 -1
  294. package/dist/src/session/__tests__/validation.test.js.map +1 -1
  295. package/dist/src/session/file-storage.d.ts +53 -27
  296. package/dist/src/session/file-storage.d.ts.map +1 -1
  297. package/dist/src/session/file-storage.js +103 -52
  298. package/dist/src/session/file-storage.js.map +1 -1
  299. package/dist/src/session/index.d.ts +6 -14
  300. package/dist/src/session/index.d.ts.map +1 -1
  301. package/dist/src/session/index.js +4 -13
  302. package/dist/src/session/index.js.map +1 -1
  303. package/dist/src/session/s3-storage.d.ts +49 -20
  304. package/dist/src/session/s3-storage.d.ts.map +1 -1
  305. package/dist/src/session/s3-storage.js +120 -35
  306. package/dist/src/session/s3-storage.js.map +1 -1
  307. package/dist/src/session/session-manager.d.ts +87 -0
  308. package/dist/src/session/session-manager.d.ts.map +1 -0
  309. package/dist/src/session/session-manager.js +128 -0
  310. package/dist/src/session/session-manager.js.map +1 -0
  311. package/dist/src/session/storage.d.ts +20 -12
  312. package/dist/src/session/storage.d.ts.map +1 -1
  313. package/dist/src/session/types.d.ts +8 -20
  314. package/dist/src/session/types.d.ts.map +1 -1
  315. package/dist/src/session/validation.d.ts +7 -0
  316. package/dist/src/session/validation.d.ts.map +1 -1
  317. package/dist/src/session/validation.js +12 -0
  318. package/dist/src/session/validation.js.map +1 -1
  319. package/dist/src/{app-state.d.ts → state-store.d.ts} +11 -11
  320. package/dist/src/state-store.d.ts.map +1 -0
  321. package/dist/src/{app-state.js → state-store.js} +8 -7
  322. package/dist/src/state-store.js.map +1 -0
  323. package/dist/src/structured-output/__tests__/context.test.js +13 -13
  324. package/dist/src/structured-output/__tests__/context.test.js.map +1 -1
  325. package/dist/src/structured-output/context.js +1 -1
  326. package/dist/src/structured-output/context.js.map +1 -1
  327. package/dist/src/telemetry/__tests__/config.test.d.ts +2 -0
  328. package/dist/src/telemetry/__tests__/config.test.d.ts.map +1 -0
  329. package/dist/src/telemetry/__tests__/config.test.js +64 -0
  330. package/dist/src/telemetry/__tests__/config.test.js.map +1 -0
  331. package/dist/src/telemetry/__tests__/config.test.node.js +66 -36
  332. package/dist/src/telemetry/__tests__/config.test.node.js.map +1 -1
  333. package/dist/src/telemetry/__tests__/meter.test.d.ts +2 -0
  334. package/dist/src/telemetry/__tests__/meter.test.d.ts.map +1 -0
  335. package/dist/src/telemetry/__tests__/meter.test.js +624 -0
  336. package/dist/src/telemetry/__tests__/meter.test.js.map +1 -0
  337. package/dist/src/telemetry/__tests__/tracer.test.node.js +123 -2
  338. package/dist/src/telemetry/__tests__/tracer.test.node.js.map +1 -1
  339. package/dist/src/telemetry/config.d.ts +104 -23
  340. package/dist/src/telemetry/config.d.ts.map +1 -1
  341. package/dist/src/telemetry/config.js +152 -43
  342. package/dist/src/telemetry/config.js.map +1 -1
  343. package/dist/src/telemetry/index.d.ts +10 -7
  344. package/dist/src/telemetry/index.d.ts.map +1 -1
  345. package/dist/src/telemetry/index.js +9 -6
  346. package/dist/src/telemetry/index.js.map +1 -1
  347. package/dist/src/telemetry/meter.d.ts +296 -0
  348. package/dist/src/telemetry/meter.d.ts.map +1 -0
  349. package/dist/src/telemetry/meter.js +365 -0
  350. package/dist/src/telemetry/meter.js.map +1 -0
  351. package/dist/src/telemetry/tracer.d.ts +27 -0
  352. package/dist/src/telemetry/tracer.d.ts.map +1 -1
  353. package/dist/src/telemetry/tracer.js +79 -4
  354. package/dist/src/telemetry/tracer.js.map +1 -1
  355. package/dist/src/telemetry/types.d.ts +2 -0
  356. package/dist/src/telemetry/types.d.ts.map +1 -1
  357. package/dist/src/telemetry/utils.d.ts +10 -0
  358. package/dist/src/telemetry/utils.d.ts.map +1 -0
  359. package/dist/src/telemetry/utils.js +13 -0
  360. package/dist/src/telemetry/utils.js.map +1 -0
  361. package/dist/src/tools/__tests__/tool-factory.test.d.ts +2 -0
  362. package/dist/src/tools/__tests__/tool-factory.test.d.ts.map +1 -0
  363. package/dist/src/tools/__tests__/tool-factory.test.js +98 -0
  364. package/dist/src/tools/__tests__/tool-factory.test.js.map +1 -0
  365. package/dist/src/tools/__tests__/tool.test.js +22 -1
  366. package/dist/src/tools/__tests__/tool.test.js.map +1 -1
  367. package/dist/src/tools/__tests__/zod-tool.test-d.js +1 -1
  368. package/dist/src/tools/__tests__/zod-tool.test-d.js.map +1 -1
  369. package/dist/src/tools/__tests__/zod-tool.test.js +3 -4
  370. package/dist/src/tools/__tests__/zod-tool.test.js.map +1 -1
  371. package/dist/src/tools/function-tool.d.ts +26 -3
  372. package/dist/src/tools/function-tool.d.ts.map +1 -1
  373. package/dist/src/tools/function-tool.js +88 -3
  374. package/dist/src/tools/function-tool.js.map +1 -1
  375. package/dist/src/tools/tool-factory.d.ts +22 -0
  376. package/dist/src/tools/tool-factory.d.ts.map +1 -0
  377. package/dist/src/tools/tool-factory.js +55 -0
  378. package/dist/src/tools/tool-factory.js.map +1 -0
  379. package/dist/src/tools/tool.d.ts +2 -2
  380. package/dist/src/tools/tool.d.ts.map +1 -1
  381. package/dist/src/tools/zod-tool.d.ts +55 -52
  382. package/dist/src/tools/zod-tool.d.ts.map +1 -1
  383. package/dist/src/tools/zod-tool.js +7 -61
  384. package/dist/src/tools/zod-tool.js.map +1 -1
  385. package/dist/src/tsconfig.tsbuildinfo +1 -1
  386. package/dist/src/types/__tests__/agent.test.js +11 -0
  387. package/dist/src/types/__tests__/agent.test.js.map +1 -1
  388. package/dist/src/types/__tests__/citations.test.d.ts +2 -0
  389. package/dist/src/types/__tests__/citations.test.d.ts.map +1 -0
  390. package/dist/src/types/__tests__/citations.test.js +104 -0
  391. package/dist/src/types/__tests__/citations.test.js.map +1 -0
  392. package/dist/src/types/__tests__/media.test.js +22 -16
  393. package/dist/src/types/__tests__/media.test.js.map +1 -1
  394. package/dist/src/types/__tests__/messages.test.js +26 -0
  395. package/dist/src/types/__tests__/messages.test.js.map +1 -1
  396. package/dist/src/types/agent.d.ts +82 -7
  397. package/dist/src/types/agent.d.ts.map +1 -1
  398. package/dist/src/types/agent.js +9 -0
  399. package/dist/src/types/agent.js.map +1 -1
  400. package/dist/src/types/citations.d.ts +180 -0
  401. package/dist/src/types/citations.d.ts.map +1 -0
  402. package/dist/src/types/citations.js +45 -0
  403. package/dist/src/types/citations.js.map +1 -0
  404. package/dist/src/types/media.d.ts +27 -30
  405. package/dist/src/types/media.d.ts.map +1 -1
  406. package/dist/src/types/media.js +15 -56
  407. package/dist/src/types/media.js.map +1 -1
  408. package/dist/src/types/messages.d.ts +23 -5
  409. package/dist/src/types/messages.d.ts.map +1 -1
  410. package/dist/src/types/messages.js +26 -26
  411. package/dist/src/types/messages.js.map +1 -1
  412. package/dist/src/types/serializable.d.ts +34 -4
  413. package/dist/src/types/serializable.d.ts.map +1 -1
  414. package/dist/src/types/serializable.js +31 -2
  415. package/dist/src/types/serializable.js.map +1 -1
  416. package/dist/src/vended-tools/bash/__tests__/bash.test.node.js +5 -4
  417. package/dist/src/vended-tools/bash/__tests__/bash.test.node.js.map +1 -1
  418. package/dist/src/vended-tools/bash/bash.d.ts.map +1 -1
  419. package/dist/src/vended-tools/bash/bash.js +1 -2
  420. package/dist/src/vended-tools/bash/bash.js.map +1 -1
  421. package/dist/src/vended-tools/file-editor/__tests__/file-editor.test.node.d.ts.map +1 -0
  422. package/dist/src/vended-tools/{file_editor → file-editor}/__tests__/file-editor.test.node.js +11 -4
  423. package/dist/src/vended-tools/file-editor/__tests__/file-editor.test.node.js.map +1 -0
  424. package/dist/src/vended-tools/{file_editor → file-editor}/file-editor.d.ts +1 -1
  425. package/dist/src/vended-tools/{file_editor → file-editor}/file-editor.d.ts.map +1 -1
  426. package/dist/src/vended-tools/{file_editor → file-editor}/file-editor.js +3 -3
  427. package/dist/src/vended-tools/{file_editor → file-editor}/file-editor.js.map +1 -1
  428. package/dist/src/vended-tools/{file_editor → file-editor}/index.d.ts.map +1 -1
  429. package/dist/src/vended-tools/file-editor/index.js.map +1 -0
  430. package/dist/src/vended-tools/{file_editor → file-editor}/types.d.ts.map +1 -1
  431. package/dist/src/vended-tools/file-editor/types.js.map +1 -0
  432. package/dist/src/vended-tools/http-request/__tests__/http-request.test.d.ts.map +1 -0
  433. package/dist/src/vended-tools/{http_request → http-request}/__tests__/http-request.test.js.map +1 -1
  434. package/dist/src/vended-tools/http-request/http-request.d.ts.map +1 -0
  435. package/dist/src/vended-tools/{http_request → http-request}/http-request.js +1 -2
  436. package/dist/src/vended-tools/http-request/http-request.js.map +1 -0
  437. package/dist/src/vended-tools/{http_request → http-request}/index.d.ts.map +1 -1
  438. package/dist/src/vended-tools/http-request/index.js.map +1 -0
  439. package/dist/src/vended-tools/{http_request → http-request}/types.d.ts.map +1 -1
  440. package/dist/src/vended-tools/http-request/types.js.map +1 -0
  441. package/dist/src/vended-tools/notebook/__tests__/notebook.test.js +5 -4
  442. package/dist/src/vended-tools/notebook/__tests__/notebook.test.js.map +1 -1
  443. package/dist/src/vended-tools/notebook/notebook.d.ts +1 -1
  444. package/dist/src/vended-tools/notebook/notebook.js +2 -2
  445. package/dist/src/vended-tools/notebook/notebook.js.map +1 -1
  446. package/package.json +66 -12
  447. package/dist/src/__fixtures__/mock-hook-provider.d.ts +0 -10
  448. package/dist/src/__fixtures__/mock-hook-provider.d.ts.map +0 -1
  449. package/dist/src/__fixtures__/mock-hook-provider.js.map +0 -1
  450. package/dist/src/__tests__/app-state.test.d.ts +0 -2
  451. package/dist/src/__tests__/app-state.test.d.ts.map +0 -1
  452. package/dist/src/__tests__/app-state.test.js.map +0 -1
  453. package/dist/src/app-state.d.ts.map +0 -1
  454. package/dist/src/app-state.js.map +0 -1
  455. package/dist/src/multiagent/base.d.ts +0 -25
  456. package/dist/src/multiagent/base.d.ts.map +0 -1
  457. package/dist/src/multiagent/base.js +0 -2
  458. package/dist/src/multiagent/base.js.map +0 -1
  459. package/dist/src/registry/registry.d.ts +0 -117
  460. package/dist/src/registry/registry.d.ts.map +0 -1
  461. package/dist/src/registry/registry.js +0 -298
  462. package/dist/src/registry/registry.js.map +0 -1
  463. package/dist/src/session/__tests__/s3-storage.test.node.d.ts +0 -2
  464. package/dist/src/session/__tests__/s3-storage.test.node.d.ts.map +0 -1
  465. package/dist/src/session/__tests__/s3-storage.test.node.js.map +0 -1
  466. package/dist/src/vended-tools/file_editor/__tests__/file-editor.test.node.d.ts.map +0 -1
  467. package/dist/src/vended-tools/file_editor/__tests__/file-editor.test.node.js.map +0 -1
  468. package/dist/src/vended-tools/file_editor/index.js.map +0 -1
  469. package/dist/src/vended-tools/file_editor/types.js.map +0 -1
  470. package/dist/src/vended-tools/http_request/__tests__/http-request.test.d.ts.map +0 -1
  471. package/dist/src/vended-tools/http_request/http-request.d.ts.map +0 -1
  472. package/dist/src/vended-tools/http_request/http-request.js.map +0 -1
  473. package/dist/src/vended-tools/http_request/index.js.map +0 -1
  474. package/dist/src/vended-tools/http_request/types.js.map +0 -1
  475. /package/dist/src/vended-tools/{file_editor → file-editor}/__tests__/file-editor.test.node.d.ts +0 -0
  476. /package/dist/src/vended-tools/{file_editor → file-editor}/index.d.ts +0 -0
  477. /package/dist/src/vended-tools/{file_editor → file-editor}/index.js +0 -0
  478. /package/dist/src/vended-tools/{file_editor → file-editor}/types.d.ts +0 -0
  479. /package/dist/src/vended-tools/{file_editor → file-editor}/types.js +0 -0
  480. /package/dist/src/vended-tools/{http_request → http-request}/__tests__/http-request.test.d.ts +0 -0
  481. /package/dist/src/vended-tools/{http_request → http-request}/__tests__/http-request.test.js +0 -0
  482. /package/dist/src/vended-tools/{http_request → http-request}/http-request.d.ts +0 -0
  483. /package/dist/src/vended-tools/{http_request → http-request}/index.d.ts +0 -0
  484. /package/dist/src/vended-tools/{http_request → http-request}/index.js +0 -0
  485. /package/dist/src/vended-tools/{http_request → http-request}/types.d.ts +0 -0
  486. /package/dist/src/vended-tools/{http_request → http-request}/types.js +0 -0
@@ -1 +1 @@
1
- {"version":3,"file":"file-storage.d.ts","sourceRoot":"","sources":["../../../src/session/file-storage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAY5D;;GAEG;AACH,qBAAa,WAAY,YAAW,eAAe;IACjD,0BAA0B;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IAEjC;;;OAGG;gBACS,OAAO,EAAE,MAAM;IAI3B;;OAEG;IACH,OAAO,CAAC,QAAQ;IAMhB;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QACzB,QAAQ,EAAE,gBAAgB,CAAA;QAC1B,UAAU,EAAE,MAAM,CAAA;QAClB,QAAQ,EAAE,OAAO,CAAA;QACjB,QAAQ,EAAE,QAAQ,CAAA;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjB;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAQzG;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgBhF;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAarF;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrG;;OAEG;YACW,UAAU;IAWxB;;OAEG;YACW,SAAS;IAevB,OAAO,CAAC,sBAAsB;IAI9B,OAAO,CAAC,uBAAuB;CAGhC"}
1
+ {"version":3,"file":"file-storage.d.ts","sourceRoot":"","sources":["../../../src/session/file-storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAW5D;;;;;;;;;;;GAWG;AACH,qBAAa,WAAY,YAAW,eAAe;IACjD,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IAEjC;;OAEG;gBACS,OAAO,EAAE,MAAM;IAI3B;;;OAGG;YACW,QAAQ;IAOtB;;;OAGG;YACW,cAAc;IAM5B;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE;QACzB,QAAQ,EAAE,gBAAgB,CAAA;QAC1B,UAAU,EAAE,MAAM,CAAA;QAClB,QAAQ,EAAE,OAAO,CAAA;QACjB,QAAQ,EAAE,QAAQ,CAAA;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjB;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAQzG;;;;;;OAMG;IACG,eAAe,CAAC,MAAM,EAAE;QAC5B,QAAQ,EAAE,gBAAgB,CAAA;QAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAwBrB;;;OAGG;IACG,aAAa,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjE;;;OAGG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAYrF;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrG;;;OAGG;YACW,UAAU;IAaxB;;;OAGG;YACW,SAAS;IAgBvB,iFAAiF;IACjF,OAAO,CAAC,oBAAoB;IAI5B,+EAA+E;YACjE,sBAAsB;IAIpC;;;OAGG;YACW,uBAAuB;CAQtC"}
@@ -1,112 +1,147 @@
1
- import { promises as fs } from 'fs';
2
- import { join, dirname } from 'path';
3
1
  import { SessionError } from '../errors.js';
4
- import { validateIdentifier } from './validation.js';
2
+ import { validateIdentifier, validateUuidV7 } from './validation.js';
5
3
  const MANIFEST = 'manifest.json';
6
4
  const SNAPSHOT_LATEST = 'snapshot_latest.json';
7
5
  const IMMUTABLE_HISTORY = 'immutable_history';
8
- const SNAPSHOT_REGEX = /snapshot_(\d+)\.json$/;
6
+ const SNAPSHOT_REGEX = /snapshot_([\w-]+)\.json$/;
9
7
  const SCHEMA_VERSION = '1.0';
10
- const DEFAULT_SNAPSHOT_ID = '1';
11
8
  /**
12
- * File-based implementation of SnapshotStorage for persisting session snapshots
9
+ * File-based implementation of SnapshotStorage.
10
+ * Persists session snapshots to the local filesystem under a configurable base directory.
11
+ *
12
+ * Directory layout:
13
+ * ```
14
+ * <baseDir>/<sessionId>/scopes/<scope>/<scopeId>/snapshots/
15
+ * snapshot_latest.json
16
+ * immutable_history/
17
+ * snapshot_<uuid7>.json
18
+ * ```
13
19
  */
14
20
  export class FileStorage {
15
- /** Base directory path */
21
+ /** Absolute path to the root directory where all session data is stored. */
16
22
  _baseDir;
17
23
  /**
18
- * Creates new FileStorage instance
19
- * @param baseDir - Base directory path for storing snapshots
24
+ * @param baseDir - Absolute path to the root directory for storing session snapshots.
20
25
  */
21
26
  constructor(baseDir) {
22
27
  this._baseDir = baseDir;
23
28
  }
24
29
  /**
25
- * Generates file path for session scope snapshots
30
+ * Resolves the absolute file path for a given scope location and filename.
31
+ * Validates sessionId and scopeId before constructing the path.
26
32
  */
27
- _getPath(location, filename) {
33
+ async _getPath(location, filename) {
34
+ const { join } = await import('path');
28
35
  validateIdentifier(location.sessionId);
29
36
  validateIdentifier(location.scopeId);
30
37
  return join(this._baseDir, location.sessionId, 'scopes', location.scope, location.scopeId, 'snapshots', filename);
31
38
  }
32
39
  /**
33
- * Saves snapshot to file, optionally marking as latest
40
+ * Resolves the absolute path to the root directory for a session.
41
+ * Used by deleteSession to remove all data under `<baseDir>/<sessionId>/`.
42
+ */
43
+ async _getSessionDir(sessionId) {
44
+ const { join } = await import('path');
45
+ validateIdentifier(sessionId);
46
+ return join(this._baseDir, sessionId);
47
+ }
48
+ /**
49
+ * Persists a snapshot to disk.
50
+ * If `isLatest` is true, writes to `snapshot_latest.json` (overwriting any previous).
51
+ * Otherwise, writes to `immutable_history/snapshot_<snapshotId>.json`.
34
52
  */
35
53
  async saveSnapshot(params) {
36
- await this._writeJSON(this._getHistorySnapshotPath(params.location, params.snapshotId), params.snapshot);
37
- if (params.isLatest) {
38
- await this._writeJSON(this._getLatestSnapshotPath(params.location), params.snapshot);
39
- }
54
+ const path = params.isLatest
55
+ ? await this._getLatestSnapshotPath(params.location)
56
+ : await this._getHistorySnapshotPath(params.location, params.snapshotId);
57
+ await this._writeJSON(path, params.snapshot);
40
58
  }
41
59
  /**
42
- * Loads snapshot by ID or latest if null
60
+ * Loads a snapshot from disk.
61
+ * If `snapshotId` is omitted, loads `snapshot_latest.json`.
62
+ * Returns null if the file does not exist.
43
63
  */
44
64
  async loadSnapshot(params) {
45
65
  const path = params.snapshotId === undefined
46
- ? this._getLatestSnapshotPath(params.location)
47
- : this._getHistorySnapshotPath(params.location, params.snapshotId);
66
+ ? await this._getLatestSnapshotPath(params.location)
67
+ : await this._getHistorySnapshotPath(params.location, params.snapshotId);
48
68
  return this._readJSON(path);
49
69
  }
50
70
  /**
51
- * Checks if an error is a file not found error (ENOENT)
52
- */
53
- _isFileNotFoundError(error) {
54
- return error !== null && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
55
- }
56
- /**
57
- * Lists all snapshot IDs for a session scope.
58
- *
59
- * TODO: Add pagination support for long-running agents with many snapshots.
60
- * Future signature could be:
61
- * ```typescript
62
- * listSnapshots(params: {
63
- * sessionId: string
64
- * scope: Scope
65
- * limit?: number // Max results to return (e.g., 100)
66
- * startAfter?: string // Snapshot ID to start after (for cursor-based pagination)
67
- * }): Promise<{ snapshotIds: string[]; nextToken?: string }>
68
- * ```
71
+ * Lists immutable snapshot IDs for a scope, sorted chronologically.
72
+ * Since IDs are UUID v7, lexicographic sort equals chronological order.
73
+ * `startAfter` filters to IDs after the given UUID v7 (exclusive cursor).
74
+ * `limit` caps the number of returned IDs.
75
+ * Returns an empty array if no snapshots exist yet.
69
76
  */
70
77
  async listSnapshotIds(params) {
71
- const dirPath = this._getPath(params.location, IMMUTABLE_HISTORY);
78
+ if (params.limit !== undefined && params.limit <= 0)
79
+ return [];
80
+ if (params.startAfter)
81
+ validateUuidV7(params.startAfter);
82
+ const dirPath = await this._getPath(params.location, IMMUTABLE_HISTORY);
72
83
  try {
84
+ const { promises: fs } = await import('fs');
73
85
  const files = await fs.readdir(dirPath);
74
- return files
86
+ let ids = files
75
87
  .map((file) => file.match(SNAPSHOT_REGEX)?.[1])
76
88
  .filter((id) => id !== undefined)
77
- .sort((a, b) => parseInt(a) - parseInt(b));
89
+ .sort();
90
+ if (params.startAfter) {
91
+ ids = ids.filter((id) => id > params.startAfter);
92
+ }
93
+ if (params.limit !== undefined) {
94
+ ids = ids.slice(0, params.limit);
95
+ }
96
+ return ids;
78
97
  }
79
98
  catch (error) {
80
- if (this._isFileNotFoundError(error)) {
99
+ if (this._isFileNotFoundError(error))
81
100
  return [];
82
- }
83
101
  throw new SessionError(`Failed to list snapshots for session ${params.location.sessionId}`, { cause: error });
84
102
  }
85
103
  }
86
104
  /**
87
- * Loads manifest or returns default if not found
105
+ * Deletes all data for a session by removing its root directory (`<baseDir>/<sessionId>/`) recursively.
106
+ * No-ops if the session directory does not exist.
107
+ */
108
+ async deleteSession(params) {
109
+ const sessionDir = await this._getSessionDir(params.sessionId);
110
+ try {
111
+ const { promises: fs } = await import('fs');
112
+ await fs.rm(sessionDir, { recursive: true, force: true });
113
+ }
114
+ catch (error) {
115
+ throw new SessionError(`Failed to delete session ${params.sessionId}`, { cause: error });
116
+ }
117
+ }
118
+ /**
119
+ * Loads the snapshot manifest for a scope.
120
+ * Returns a default manifest with the current timestamp if none exists yet.
88
121
  */
89
122
  async loadManifest(params) {
90
- const path = this._getPath(params.location, MANIFEST);
123
+ const path = await this._getPath(params.location, MANIFEST);
91
124
  const manifest = await this._readJSON(path);
92
125
  return (manifest ?? {
93
126
  schemaVersion: SCHEMA_VERSION,
94
- nextSnapshotId: DEFAULT_SNAPSHOT_ID,
95
127
  updatedAt: new Date().toISOString(),
96
128
  });
97
129
  }
98
130
  /**
99
- * Saves manifest to file
131
+ * Persists the snapshot manifest for a scope to disk.
100
132
  */
101
133
  async saveManifest(params) {
102
- const path = this._getPath(params.location, MANIFEST);
134
+ const path = await this._getPath(params.location, MANIFEST);
103
135
  await this._writeJSON(path, params.manifest);
104
136
  }
105
137
  /**
106
- * Writes JSON data to file atomically
138
+ * Atomically writes JSON to a file using a `.tmp` intermediary to prevent partial writes.
139
+ * Creates parent directories if they do not exist.
107
140
  */
108
141
  async _writeJSON(path, data) {
109
142
  try {
143
+ const { promises: fs } = await import('fs');
144
+ const { dirname } = await import('path');
110
145
  await fs.mkdir(dirname(path), { recursive: true });
111
146
  const tmpPath = `${path}.tmp`;
112
147
  await fs.writeFile(tmpPath, JSON.stringify(data, null, 2), 'utf8');
@@ -117,10 +152,12 @@ export class FileStorage {
117
152
  }
118
153
  }
119
154
  /**
120
- * Reads and parses JSON from file
155
+ * Reads and parses a JSON file. Returns null if the file does not exist.
156
+ * Throws SessionError on parse failure or unexpected filesystem errors.
121
157
  */
122
158
  async _readJSON(path) {
123
159
  try {
160
+ const { promises: fs } = await import('fs');
124
161
  const content = await fs.readFile(path, 'utf8');
125
162
  return JSON.parse(content);
126
163
  }
@@ -134,11 +171,25 @@ export class FileStorage {
134
171
  throw new SessionError(`File system error reading ${path}`, { cause: error });
135
172
  }
136
173
  }
137
- _getLatestSnapshotPath(location) {
174
+ /** Returns true if the error represents a missing file or directory (ENOENT). */
175
+ _isFileNotFoundError(error) {
176
+ return error !== null && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
177
+ }
178
+ /** Returns the file path for `snapshot_latest.json` within the given scope. */
179
+ async _getLatestSnapshotPath(location) {
138
180
  return this._getPath(location, SNAPSHOT_LATEST);
139
181
  }
140
- _getHistorySnapshotPath(location, snapshotId) {
141
- return this._getPath(location, `${IMMUTABLE_HISTORY}/snapshot_${String(snapshotId).padStart(5, '0')}.json`);
182
+ /**
183
+ * Returns the file path for an immutable snapshot in `immutable_history/`.
184
+ * Validates the snapshotId and guards against path traversal outside `_baseDir`.
185
+ */
186
+ async _getHistorySnapshotPath(location, snapshotId) {
187
+ validateIdentifier(snapshotId);
188
+ const resolved = await this._getPath(location, `${IMMUTABLE_HISTORY}/snapshot_${snapshotId}.json`);
189
+ if (!resolved.startsWith(this._baseDir)) {
190
+ throw new SessionError(`Invalid snapshotId '${snapshotId}': resolves outside storage directory`);
191
+ }
192
+ return resolved;
142
193
  }
143
194
  }
144
195
  //# sourceMappingURL=file-storage.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"file-storage.js","sourceRoot":"","sources":["../../../src/session/file-storage.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"file-storage.js","sourceRoot":"","sources":["../../../src/session/file-storage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEpE,MAAM,QAAQ,GAAG,eAAe,CAAA;AAChC,MAAM,eAAe,GAAG,sBAAsB,CAAA;AAC9C,MAAM,iBAAiB,GAAG,mBAAmB,CAAA;AAC7C,MAAM,cAAc,GAAG,0BAA0B,CAAA;AACjD,MAAM,cAAc,GAAG,KAAK,CAAA;AAE5B;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,WAAW;IACtB,4EAA4E;IAC3D,QAAQ,CAAQ;IAEjC;;OAEG;IACH,YAAY,OAAe;QACzB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;IACzB,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,QAAQ,CAAC,QAA0B,EAAE,QAAgB;QACjE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAA;QACrC,kBAAkB,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;QACtC,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;QACpC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAA;IACnH,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,cAAc,CAAC,SAAiB;QAC5C,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAA;QACrC,kBAAkB,CAAC,SAAS,CAAC,CAAA;QAC7B,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAA;IACvC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,MAKlB;QACC,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ;YAC1B,CAAC,CAAC,MAAM,IAAI,CAAC,sBAAsB,CAAC,MAAM,CAAC,QAAQ,CAAC;YACpD,CAAC,CAAC,MAAM,IAAI,CAAC,uBAAuB,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAA;QAC1E,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC9C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,MAA2D;QAC5E,MAAM,IAAI,GACR,MAAM,CAAC,UAAU,KAAK,SAAS;YAC7B,CAAC,CAAC,MAAM,IAAI,CAAC,sBAAsB,CAAC,MAAM,CAAC,QAAQ,CAAC;YACpD,CAAC,CAAC,MAAM,IAAI,CAAC,uBAAuB,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAA;QAC5E,OAAO,IAAI,CAAC,SAAS,CAAW,IAAI,CAAC,CAAA;IACvC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,eAAe,CAAC,MAIrB;QACC,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,IAAI,CAAC;YAAE,OAAO,EAAE,CAAA;QAC9D,IAAI,MAAM,CAAC,UAAU;YAAE,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;QACxD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAA;QACvE,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAA;YAC3C,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;YACvC,IAAI,GAAG,GAAG,KAAK;iBACZ,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;iBAC9C,MAAM,CAAC,CAAC,EAAE,EAAgB,EAAE,CAAC,EAAE,KAAK,SAAS,CAAC;iBAC9C,IAAI,EAAE,CAAA;YACT,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBACtB,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,MAAM,CAAC,UAAW,CAAC,CAAA;YACnD,CAAC;YACD,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC/B,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;YAClC,CAAC;YACD,OAAO,GAAG,CAAA;QACZ,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAA;YAC/C,MAAM,IAAI,YAAY,CAAC,wCAAwC,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;QAC/G,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,aAAa,CAAC,MAA6B;QAC/C,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;QAC9D,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAA;YAC3C,MAAM,EAAE,CAAC,EAAE,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QAC3D,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,IAAI,YAAY,CAAC,4BAA4B,MAAM,CAAC,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;QAC1F,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,YAAY,CAAC,MAAsC;QACvD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;QAC3D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAmB,IAAI,CAAC,CAAA;QAE7D,OAAO,CACL,QAAQ,IAAI;YACV,aAAa,EAAE,cAAc;YAC7B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CACF,CAAA;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,YAAY,CAAC,MAAkE;QACnF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;QAC3D,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC9C,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,UAAU,CAAC,IAAY,EAAE,IAAa;QAClD,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAA;YAC3C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAA;YACxC,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YAClD,MAAM,OAAO,GAAG,GAAG,IAAI,MAAM,CAAA;YAC7B,MAAM,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;YAClE,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;QAChC,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,IAAI,YAAY,CAAC,wBAAwB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;QAC1E,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,SAAS,CAAI,IAAY;QACrC,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAA;YAC3C,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;YAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAC5B,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrC,OAAO,IAAI,CAAA;YACb,CAAC;YACD,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;gBACjC,MAAM,IAAI,YAAY,CAAC,wBAAwB,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;YAC1E,CAAC;YACD,MAAM,IAAI,YAAY,CAAC,6BAA6B,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;QAC/E,CAAC;IACH,CAAC;IAED,iFAAiF;IACzE,oBAAoB,CAAC,KAAc;QACzC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAA;IAClG,CAAC;IAED,+EAA+E;IACvE,KAAK,CAAC,sBAAsB,CAAC,QAA0B;QAC7D,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAA;IACjD,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,uBAAuB,CAAC,QAA0B,EAAE,UAAkB;QAClF,kBAAkB,CAAC,UAAU,CAAC,CAAA;QAC9B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,iBAAiB,aAAa,UAAU,OAAO,CAAC,CAAA;QAClG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,YAAY,CAAC,uBAAuB,UAAU,uCAAuC,CAAC,CAAA;QAClG,CAAC;QACD,OAAO,QAAQ,CAAA;IACjB,CAAC;CACF"}
@@ -1,19 +1,11 @@
1
1
  /**
2
- * Session management module for conversation persistence and restoration.
3
- *
4
- * Provides snapshot-based session management with pluggable storage backends.
5
- * Supports conversation history, state persistence, and branching.
6
- *
7
- * @example
8
- * ```typescript
9
- * import { FileStorage, SnapshotStorage } from '@strands/agents/session'
10
- *
11
- * const storage = new FileStorage('./sessions')
12
- * await storage.saveSnapshot({ sessionId, scope, isLatest: true, snapshot })
13
- * ```
2
+ * Session management module re-exports.
3
+ * These are exported from the main `@strands-agents/sdk` entry point.
14
4
  */
15
- export type { Scope, Snapshot, SnapshotManifest, SnapshotTriggerCallback } from './types.js';
5
+ export { SessionManager } from './session-manager.js';
6
+ export type { SessionManagerConfig, SaveLatestStrategy } from './session-manager.js';
7
+ export type { SnapshotManifest, SnapshotTriggerCallback, SnapshotTriggerParams } from './types.js';
16
8
  export type { SessionStorage, SnapshotStorage, SnapshotLocation } from './storage.js';
17
9
  export { FileStorage } from './file-storage.js';
18
- export { S3Storage, type S3StorageConfig } from './s3-storage.js';
10
+ export type { Scope, Snapshot } from '../agent/snapshot.js';
19
11
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAG5F,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,YAAY,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AACpF,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAGlG,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA"}
@@ -1,18 +1,9 @@
1
1
  /**
2
- * Session management module for conversation persistence and restoration.
3
- *
4
- * Provides snapshot-based session management with pluggable storage backends.
5
- * Supports conversation history, state persistence, and branching.
6
- *
7
- * @example
8
- * ```typescript
9
- * import { FileStorage, SnapshotStorage } from '@strands/agents/session'
10
- *
11
- * const storage = new FileStorage('./sessions')
12
- * await storage.saveSnapshot({ sessionId, scope, isLatest: true, snapshot })
13
- * ```
2
+ * Session management module re-exports.
3
+ * These are exported from the main `@strands-agents/sdk` entry point.
14
4
  */
5
+ // Core types
6
+ export { SessionManager } from './session-manager.js';
15
7
  // Storage implementations
16
8
  export { FileStorage } from './file-storage.js';
17
- export { S3Storage } from './s3-storage.js';
18
9
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,0BAA0B;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAwB,MAAM,iBAAiB,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,aAAa;AACb,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAOrD,0BAA0B;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA"}
@@ -15,7 +15,16 @@ export type S3StorageConfig = {
15
15
  s3Client?: S3Client;
16
16
  };
17
17
  /**
18
- * S3-based implementation of SnapshotStorage for persisting session snapshots
18
+ * S3-based implementation of SnapshotStorage.
19
+ * Persists session snapshots as JSON objects in an S3 bucket.
20
+ *
21
+ * Object key layout:
22
+ * ```
23
+ * [<prefix>/]<sessionId>/scopes/<scope>/<scopeId>/snapshots/
24
+ * snapshot_latest.json
25
+ * immutable_history/
26
+ * snapshot_<uuid7>.json
27
+ * ```
19
28
  */
20
29
  export declare class S3Storage implements SnapshotStorage {
21
30
  /** S3 client instance */
@@ -30,11 +39,19 @@ export declare class S3Storage implements SnapshotStorage {
30
39
  */
31
40
  constructor(config: S3StorageConfig);
32
41
  /**
33
- * Generates S3 key path for session scope snapshots
42
+ * Resolves the full S3 object key for a given scope location and path.
43
+ * Validates sessionId and scopeId before constructing the key.
34
44
  */
35
45
  private _getKey;
36
46
  /**
37
- * Saves snapshot to S3, optionally marking as latest
47
+ * Resolves the S3 key prefix for an entire session (`[<prefix>/]<sessionId>/`).
48
+ * Used by deleteSession to list and remove all objects under the session.
49
+ */
50
+ private _getSessionPrefix;
51
+ /**
52
+ * Persists a snapshot to S3.
53
+ * If `isLatest` is true, writes to `snapshot_latest.json` (overwriting any previous).
54
+ * Otherwise, writes to `immutable_history/snapshot_<snapshotId>.json`.
38
55
  */
39
56
  saveSnapshot(params: {
40
57
  location: SnapshotLocation;
@@ -43,51 +60,63 @@ export declare class S3Storage implements SnapshotStorage {
43
60
  snapshot: Snapshot;
44
61
  }): Promise<void>;
45
62
  /**
46
- * Loads snapshot by ID or latest if undefined
63
+ * Loads a snapshot from S3.
64
+ * If `snapshotId` is omitted, loads `snapshot_latest.json`.
65
+ * Returns null if the object does not exist.
47
66
  */
48
67
  loadSnapshot(params: {
49
68
  location: SnapshotLocation;
50
69
  snapshotId?: string;
51
70
  }): Promise<Snapshot | null>;
52
71
  /**
53
- * Lists all snapshot IDs for a session scope.
54
- *
55
- * TODO: Add pagination support for long-running agents with many snapshots.
56
- * Future signature could be:
57
- * ```typescript
58
- * listSnapshots(params: {
59
- * sessionId: string
60
- * scope: Scope
61
- * limit?: number // Max results to return (e.g., 100)
62
- * startAfter?: string // Snapshot ID to start after (for cursor-based pagination)
63
- * }): Promise<{ snapshotIds: string[]; nextToken?: string }>
64
- * ```
72
+ * Lists immutable snapshot IDs for a scope, sorted chronologically.
73
+ * Since IDs are UUID v7, lexicographic sort equals chronological order.
74
+ * Pushes `startAfter` and `limit` down to S3 via `StartAfter` and `MaxKeys`
75
+ * to avoid fetching unnecessary objects.
76
+ * Returns an empty array if no snapshots exist yet.
65
77
  */
66
78
  listSnapshotIds(params: {
67
79
  location: SnapshotLocation;
80
+ limit?: number;
81
+ startAfter?: string;
68
82
  }): Promise<string[]>;
69
83
  /**
70
- * Loads manifest or returns default if not found
84
+ * Deletes all S3 objects belonging to a session by listing and batch-deleting
85
+ * everything under `[<prefix>/]<sessionId>/`.
86
+ * Handles buckets with more than 1000 objects via continuation token pagination.
87
+ * No-ops if the session has no objects.
88
+ */
89
+ deleteSession(params: {
90
+ sessionId: string;
91
+ }): Promise<void>;
92
+ /**
93
+ * Loads the snapshot manifest for a scope from S3.
94
+ * Returns a default manifest with the current timestamp if none exists yet.
71
95
  */
72
96
  loadManifest(params: {
73
97
  location: SnapshotLocation;
74
98
  }): Promise<SnapshotManifest>;
75
99
  /**
76
- * Saves manifest to S3
100
+ * Persists the snapshot manifest for a scope to S3.
77
101
  */
78
102
  saveManifest(params: {
79
103
  location: SnapshotLocation;
80
104
  manifest: SnapshotManifest;
81
105
  }): Promise<void>;
82
106
  /**
83
- * Writes JSON data to S3
107
+ * Serializes data as JSON and writes it to S3 with `application/json` content type.
84
108
  */
85
109
  private _writeJSON;
86
110
  /**
87
- * Reads and parses JSON from S3
111
+ * Reads and parses a JSON object from S3. Returns null if the object does not exist.
112
+ * Throws SessionError on parse failure or unexpected S3 errors.
88
113
  */
89
114
  private _readJSON;
115
+ /** Returns true if the error represents a missing S3 object (`NoSuchKey`) or bucket (`NoSuchBucket`). */
116
+ private _isNotFoundError;
117
+ /** Returns the S3 key for `snapshot_latest.json` within the given scope. */
90
118
  private _getLatestSnapshotKey;
119
+ /** Returns the S3 key for an immutable snapshot in `immutable_history/`. Validates the snapshotId before constructing the key. */
91
120
  private _getHistorySnapshotKey;
92
121
  }
93
122
  //# sourceMappingURL=s3-storage.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"s3-storage.d.ts","sourceRoot":"","sources":["../../../src/session/s3-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAA4D,MAAM,oBAAoB,CAAA;AAEvG,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAW5D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB,CAAA;AAED;;GAEG;AACH,qBAAa,SAAU,YAAW,eAAe;IAC/C,yBAAyB;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAU;IAC9B,qBAAqB;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,iCAAiC;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAEhC;;;OAGG;gBACS,MAAM,EAAE,eAAe;IAUnC;;OAEG;IACH,OAAO,CAAC,OAAO;IAOf;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QACzB,QAAQ,EAAE,gBAAgB,CAAA;QAC1B,UAAU,EAAE,MAAM,CAAA;QAClB,QAAQ,EAAE,OAAO,CAAA;QACjB,QAAQ,EAAE,QAAQ,CAAA;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjB;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAQzG;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgBhF;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAarF;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrG;;OAEG;YACW,UAAU;IAexB;;OAEG;YACW,SAAS;IAiBvB,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,sBAAsB;CAG/B"}
1
+ {"version":3,"file":"s3-storage.d.ts","sourceRoot":"","sources":["../../../src/session/s3-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EAKT,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAW5D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,SAAU,YAAW,eAAe;IAC/C,yBAAyB;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAU;IAC9B,qBAAqB;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,iCAAiC;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC;;;OAGG;gBACS,MAAM,EAAE,eAAe;IAUnC;;;OAGG;IACH,OAAO,CAAC,OAAO;IAOf;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE;QACzB,QAAQ,EAAE,gBAAgB,CAAA;QAC1B,UAAU,EAAE,MAAM,CAAA;QAClB,QAAQ,EAAE,OAAO,CAAA;QACjB,QAAQ,EAAE,QAAQ,CAAA;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQjB;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAQzG;;;;;;OAMG;IACG,eAAe,CAAC,MAAM,EAAE;QAC5B,QAAQ,EAAE,gBAAgB,CAAA;QAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA4CrB;;;;;OAKG;IACG,aAAa,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBjE;;;OAGG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAYrF;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,gBAAgB,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrG;;OAEG;YACW,UAAU;IAexB;;;OAGG;YACW,SAAS;IAiBvB,yGAAyG;IACzG,OAAO,CAAC,gBAAgB;IAUxB,4EAA4E;IAC5E,OAAO,CAAC,qBAAqB;IAI7B,kIAAkI;IAClI,OAAO,CAAC,sBAAsB;CAI/B"}