tracelattice 1.2.5

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 (294) hide show
  1. package/LICENSE +24 -0
  2. package/README.md +112 -0
  3. package/dist/ServerConfig.d.ts +229 -0
  4. package/dist/ServerConfig.d.ts.map +1 -0
  5. package/dist/ServerConfig.js +121 -0
  6. package/dist/ServerConfig.js.map +1 -0
  7. package/dist/__tests__/base-registry.test.d.ts +2 -0
  8. package/dist/__tests__/base-registry.test.d.ts.map +1 -0
  9. package/dist/__tests__/base-transport-cov.test.d.ts +2 -0
  10. package/dist/__tests__/base-transport-cov.test.d.ts.map +1 -0
  11. package/dist/__tests__/base-transport.test.d.ts +2 -0
  12. package/dist/__tests__/base-transport.test.d.ts.map +1 -0
  13. package/dist/__tests__/config-loader.test.d.ts +2 -0
  14. package/dist/__tests__/config-loader.test.d.ts.map +1 -0
  15. package/dist/__tests__/connection-pool-cov.test.d.ts +2 -0
  16. package/dist/__tests__/connection-pool-cov.test.d.ts.map +1 -0
  17. package/dist/__tests__/connection-pool.test.d.ts +2 -0
  18. package/dist/__tests__/connection-pool.test.d.ts.map +1 -0
  19. package/dist/__tests__/container.test.d.ts +2 -0
  20. package/dist/__tests__/container.test.d.ts.map +1 -0
  21. package/dist/__tests__/crud.test.d.ts +2 -0
  22. package/dist/__tests__/crud.test.d.ts.map +1 -0
  23. package/dist/__tests__/discovery-cache.test.d.ts +2 -0
  24. package/dist/__tests__/discovery-cache.test.d.ts.map +1 -0
  25. package/dist/__tests__/errors.test.d.ts +2 -0
  26. package/dist/__tests__/errors.test.d.ts.map +1 -0
  27. package/dist/__tests__/factories.test.d.ts +2 -0
  28. package/dist/__tests__/factories.test.d.ts.map +1 -0
  29. package/dist/__tests__/health-checker-cov.test.d.ts +2 -0
  30. package/dist/__tests__/health-checker-cov.test.d.ts.map +1 -0
  31. package/dist/__tests__/health-checker.test.d.ts +2 -0
  32. package/dist/__tests__/health-checker.test.d.ts.map +1 -0
  33. package/dist/__tests__/helpers/factories.d.ts +36 -0
  34. package/dist/__tests__/helpers/factories.d.ts.map +1 -0
  35. package/dist/__tests__/helpers/index.d.ts +3 -0
  36. package/dist/__tests__/helpers/index.d.ts.map +1 -0
  37. package/dist/__tests__/helpers/timers.d.ts +4 -0
  38. package/dist/__tests__/helpers/timers.d.ts.map +1 -0
  39. package/dist/__tests__/history-manager.test.d.ts +2 -0
  40. package/dist/__tests__/history-manager.test.d.ts.map +1 -0
  41. package/dist/__tests__/http-helpers-cov.test.d.ts +2 -0
  42. package/dist/__tests__/http-helpers-cov.test.d.ts.map +1 -0
  43. package/dist/__tests__/http-transport-cov.test.d.ts +2 -0
  44. package/dist/__tests__/http-transport-cov.test.d.ts.map +1 -0
  45. package/dist/__tests__/http-transport.test.d.ts +2 -0
  46. package/dist/__tests__/http-transport.test.d.ts.map +1 -0
  47. package/dist/__tests__/input-normalizer.test.d.ts +8 -0
  48. package/dist/__tests__/input-normalizer.test.d.ts.map +1 -0
  49. package/dist/__tests__/integration.test.d.ts +2 -0
  50. package/dist/__tests__/integration.test.d.ts.map +1 -0
  51. package/dist/__tests__/lib-server.test.d.ts +2 -0
  52. package/dist/__tests__/lib-server.test.d.ts.map +1 -0
  53. package/dist/__tests__/memory-persistence.test.d.ts +2 -0
  54. package/dist/__tests__/memory-persistence.test.d.ts.map +1 -0
  55. package/dist/__tests__/metrics-integration.test.d.ts +2 -0
  56. package/dist/__tests__/metrics-integration.test.d.ts.map +1 -0
  57. package/dist/__tests__/persistence.test.d.ts +2 -0
  58. package/dist/__tests__/persistence.test.d.ts.map +1 -0
  59. package/dist/__tests__/reasoning-integration.test.d.ts +11 -0
  60. package/dist/__tests__/reasoning-integration.test.d.ts.map +1 -0
  61. package/dist/__tests__/reasoning-types.test.d.ts +2 -0
  62. package/dist/__tests__/reasoning-types.test.d.ts.map +1 -0
  63. package/dist/__tests__/request-context.test.d.ts +2 -0
  64. package/dist/__tests__/request-context.test.d.ts.map +1 -0
  65. package/dist/__tests__/sanitize.test.d.ts +2 -0
  66. package/dist/__tests__/sanitize.test.d.ts.map +1 -0
  67. package/dist/__tests__/schema.test.d.ts +2 -0
  68. package/dist/__tests__/schema.test.d.ts.map +1 -0
  69. package/dist/__tests__/sequentialthinking-tools.test.d.ts +2 -0
  70. package/dist/__tests__/sequentialthinking-tools.test.d.ts.map +1 -0
  71. package/dist/__tests__/server-config.test.d.ts +2 -0
  72. package/dist/__tests__/server-config.test.d.ts.map +1 -0
  73. package/dist/__tests__/skill-discovery.test.d.ts +2 -0
  74. package/dist/__tests__/skill-discovery.test.d.ts.map +1 -0
  75. package/dist/__tests__/skill-registry.test.d.ts +2 -0
  76. package/dist/__tests__/skill-registry.test.d.ts.map +1 -0
  77. package/dist/__tests__/skill-watcher.test.d.ts +2 -0
  78. package/dist/__tests__/skill-watcher.test.d.ts.map +1 -0
  79. package/dist/__tests__/sqlite-persistence.test.d.ts +2 -0
  80. package/dist/__tests__/sqlite-persistence.test.d.ts.map +1 -0
  81. package/dist/__tests__/sse-transport-cov.test.d.ts +2 -0
  82. package/dist/__tests__/sse-transport-cov.test.d.ts.map +1 -0
  83. package/dist/__tests__/sse-transport.test.d.ts +2 -0
  84. package/dist/__tests__/sse-transport.test.d.ts.map +1 -0
  85. package/dist/__tests__/streamable-http-cov.test.d.ts +2 -0
  86. package/dist/__tests__/streamable-http-cov.test.d.ts.map +1 -0
  87. package/dist/__tests__/streamable-http-transport.test.d.ts +2 -0
  88. package/dist/__tests__/streamable-http-transport.test.d.ts.map +1 -0
  89. package/dist/__tests__/structured-logger.test.d.ts +2 -0
  90. package/dist/__tests__/structured-logger.test.d.ts.map +1 -0
  91. package/dist/__tests__/thought-evaluator.test.d.ts +2 -0
  92. package/dist/__tests__/thought-evaluator.test.d.ts.map +1 -0
  93. package/dist/__tests__/thought-formatter.test.d.ts +2 -0
  94. package/dist/__tests__/thought-formatter.test.d.ts.map +1 -0
  95. package/dist/__tests__/thought-processor.test.d.ts +8 -0
  96. package/dist/__tests__/thought-processor.test.d.ts.map +1 -0
  97. package/dist/__tests__/tool-registry-cov.test.d.ts +2 -0
  98. package/dist/__tests__/tool-registry-cov.test.d.ts.map +1 -0
  99. package/dist/__tests__/tool-registry.test.d.ts +2 -0
  100. package/dist/__tests__/tool-registry.test.d.ts.map +1 -0
  101. package/dist/__tests__/tool-watcher.test.d.ts +2 -0
  102. package/dist/__tests__/tool-watcher.test.d.ts.map +1 -0
  103. package/dist/__tests__/worker-manager-cov.test.d.ts +2 -0
  104. package/dist/__tests__/worker-manager-cov.test.d.ts.map +1 -0
  105. package/dist/__tests__/worker-manager.test.d.ts +2 -0
  106. package/dist/__tests__/worker-manager.test.d.ts.map +1 -0
  107. package/dist/cache/DiscoveryCache.d.ts +269 -0
  108. package/dist/cache/DiscoveryCache.d.ts.map +1 -0
  109. package/dist/cache/DiscoveryCache.js +100 -0
  110. package/dist/cache/DiscoveryCache.js.map +1 -0
  111. package/dist/cli.d.ts +3 -0
  112. package/dist/cli.d.ts.map +1 -0
  113. package/dist/cli.js +114 -0
  114. package/dist/cli.js.map +1 -0
  115. package/dist/cluster/WorkerManager.d.ts +166 -0
  116. package/dist/cluster/WorkerManager.d.ts.map +1 -0
  117. package/dist/cluster/WorkerManager.js +202 -0
  118. package/dist/cluster/WorkerManager.js.map +1 -0
  119. package/dist/cluster/worker.d.ts +11 -0
  120. package/dist/cluster/worker.d.ts.map +1 -0
  121. package/dist/cluster/worker.js +36 -0
  122. package/dist/cluster/worker.js.map +1 -0
  123. package/dist/config/ConfigLoader.d.ts +224 -0
  124. package/dist/config/ConfigLoader.d.ts.map +1 -0
  125. package/dist/config/ConfigLoader.js +85 -0
  126. package/dist/config/ConfigLoader.js.map +1 -0
  127. package/dist/context/RequestContext.d.ts +61 -0
  128. package/dist/context/RequestContext.d.ts.map +1 -0
  129. package/dist/context/RequestContext.js +17 -0
  130. package/dist/context/RequestContext.js.map +1 -0
  131. package/dist/contracts/index.d.ts +10 -0
  132. package/dist/contracts/index.d.ts.map +1 -0
  133. package/dist/contracts/index.js +1 -0
  134. package/dist/contracts/interfaces.d.ts +107 -0
  135. package/dist/contracts/interfaces.d.ts.map +1 -0
  136. package/dist/contracts/interfaces.js +1 -0
  137. package/dist/core/HistoryManager.d.ts +514 -0
  138. package/dist/core/HistoryManager.d.ts.map +1 -0
  139. package/dist/core/HistoryManager.js +331 -0
  140. package/dist/core/HistoryManager.js.map +1 -0
  141. package/dist/core/IHistoryManager.d.ts +100 -0
  142. package/dist/core/IHistoryManager.d.ts.map +1 -0
  143. package/dist/core/IHistoryManager.js +1 -0
  144. package/dist/core/InputNormalizer.d.ts +139 -0
  145. package/dist/core/InputNormalizer.d.ts.map +1 -0
  146. package/dist/core/InputNormalizer.js +101 -0
  147. package/dist/core/InputNormalizer.js.map +1 -0
  148. package/dist/core/ThoughtEvaluator.d.ts +127 -0
  149. package/dist/core/ThoughtEvaluator.d.ts.map +1 -0
  150. package/dist/core/ThoughtEvaluator.js +346 -0
  151. package/dist/core/ThoughtEvaluator.js.map +1 -0
  152. package/dist/core/ThoughtFormatter.d.ts +133 -0
  153. package/dist/core/ThoughtFormatter.d.ts.map +1 -0
  154. package/dist/core/ThoughtFormatter.js +70 -0
  155. package/dist/core/ThoughtFormatter.js.map +1 -0
  156. package/dist/core/ThoughtProcessor.d.ts +218 -0
  157. package/dist/core/ThoughtProcessor.d.ts.map +1 -0
  158. package/dist/core/ThoughtProcessor.js +205 -0
  159. package/dist/core/ThoughtProcessor.js.map +1 -0
  160. package/dist/core/reasoning.d.ts +169 -0
  161. package/dist/core/reasoning.d.ts.map +1 -0
  162. package/dist/core/reasoning.js +1 -0
  163. package/dist/core/step.d.ts +45 -0
  164. package/dist/core/step.d.ts.map +1 -0
  165. package/dist/core/step.js +1 -0
  166. package/dist/core/thought.d.ts +190 -0
  167. package/dist/core/thought.d.ts.map +1 -0
  168. package/dist/core/thought.js +1 -0
  169. package/dist/di/Container.d.ts +226 -0
  170. package/dist/di/Container.d.ts.map +1 -0
  171. package/dist/di/Container.js +96 -0
  172. package/dist/di/Container.js.map +1 -0
  173. package/dist/di/ServiceRegistry.d.ts +32 -0
  174. package/dist/di/ServiceRegistry.d.ts.map +1 -0
  175. package/dist/di/ServiceRegistry.js +1 -0
  176. package/dist/errors.d.ts +482 -0
  177. package/dist/errors.d.ts.map +1 -0
  178. package/dist/errors.js +108 -0
  179. package/dist/errors.js.map +1 -0
  180. package/dist/health/HealthChecker.d.ts +73 -0
  181. package/dist/health/HealthChecker.d.ts.map +1 -0
  182. package/dist/health/HealthChecker.js +69 -0
  183. package/dist/health/HealthChecker.js.map +1 -0
  184. package/dist/index.d.ts +2 -0
  185. package/dist/index.d.ts.map +1 -0
  186. package/dist/index.js +1 -0
  187. package/dist/lib.d.ts +205 -0
  188. package/dist/lib.d.ts.map +1 -0
  189. package/dist/lib.js +219 -0
  190. package/dist/lib.js.map +1 -0
  191. package/dist/logger/NullLogger.d.ts +154 -0
  192. package/dist/logger/NullLogger.d.ts.map +1 -0
  193. package/dist/logger/NullLogger.js +24 -0
  194. package/dist/logger/NullLogger.js.map +1 -0
  195. package/dist/logger/StructuredLogger.d.ts +327 -0
  196. package/dist/logger/StructuredLogger.d.ts.map +1 -0
  197. package/dist/logger/StructuredLogger.js +72 -0
  198. package/dist/logger/StructuredLogger.js.map +1 -0
  199. package/dist/metrics/__tests__/metrics.test.d.ts +2 -0
  200. package/dist/metrics/__tests__/metrics.test.d.ts.map +1 -0
  201. package/dist/metrics/metrics.impl.d.ts +252 -0
  202. package/dist/metrics/metrics.impl.d.ts.map +1 -0
  203. package/dist/metrics/metrics.impl.js +197 -0
  204. package/dist/metrics/metrics.impl.js.map +1 -0
  205. package/dist/persistence/FilePersistence.d.ts +66 -0
  206. package/dist/persistence/FilePersistence.d.ts.map +1 -0
  207. package/dist/persistence/FilePersistence.js +132 -0
  208. package/dist/persistence/FilePersistence.js.map +1 -0
  209. package/dist/persistence/MemoryPersistence.d.ts +68 -0
  210. package/dist/persistence/MemoryPersistence.d.ts.map +1 -0
  211. package/dist/persistence/MemoryPersistence.js +51 -0
  212. package/dist/persistence/MemoryPersistence.js.map +1 -0
  213. package/dist/persistence/PersistenceBackend.d.ts +69 -0
  214. package/dist/persistence/PersistenceBackend.d.ts.map +1 -0
  215. package/dist/persistence/PersistenceBackend.js +1 -0
  216. package/dist/persistence/PersistenceFactory.d.ts +21 -0
  217. package/dist/persistence/PersistenceFactory.d.ts.map +1 -0
  218. package/dist/persistence/PersistenceFactory.js +25 -0
  219. package/dist/persistence/PersistenceFactory.js.map +1 -0
  220. package/dist/persistence/SqlitePersistence.d.ts +60 -0
  221. package/dist/persistence/SqlitePersistence.d.ts.map +1 -0
  222. package/dist/persistence/SqlitePersistence.js +136 -0
  223. package/dist/persistence/SqlitePersistence.js.map +1 -0
  224. package/dist/pool/ConnectionPool.d.ts +215 -0
  225. package/dist/pool/ConnectionPool.d.ts.map +1 -0
  226. package/dist/pool/ConnectionPool.js +187 -0
  227. package/dist/pool/ConnectionPool.js.map +1 -0
  228. package/dist/registry/BaseRegistry.d.ts +203 -0
  229. package/dist/registry/BaseRegistry.d.ts.map +1 -0
  230. package/dist/registry/BaseRegistry.js +165 -0
  231. package/dist/registry/BaseRegistry.js.map +1 -0
  232. package/dist/registry/SkillRegistry.d.ts +69 -0
  233. package/dist/registry/SkillRegistry.d.ts.map +1 -0
  234. package/dist/registry/SkillRegistry.js +88 -0
  235. package/dist/registry/SkillRegistry.js.map +1 -0
  236. package/dist/registry/ToolRegistry.d.ts +69 -0
  237. package/dist/registry/ToolRegistry.d.ts.map +1 -0
  238. package/dist/registry/ToolRegistry.js +93 -0
  239. package/dist/registry/ToolRegistry.js.map +1 -0
  240. package/dist/sanitize.d.ts +63 -0
  241. package/dist/sanitize.d.ts.map +1 -0
  242. package/dist/sanitize.js +14 -0
  243. package/dist/sanitize.js.map +1 -0
  244. package/dist/schema.d.ts +531 -0
  245. package/dist/schema.d.ts.map +1 -0
  246. package/dist/schema.js +204 -0
  247. package/dist/schema.js.map +1 -0
  248. package/dist/telemetry/Telemetry.d.ts +36 -0
  249. package/dist/telemetry/Telemetry.d.ts.map +1 -0
  250. package/dist/telemetry/Telemetry.js +68 -0
  251. package/dist/telemetry/Telemetry.js.map +1 -0
  252. package/dist/telemetry/__tests__/Telemetry.test.d.ts +2 -0
  253. package/dist/telemetry/__tests__/Telemetry.test.d.ts.map +1 -0
  254. package/dist/transport/BaseTransport.d.ts +184 -0
  255. package/dist/transport/BaseTransport.d.ts.map +1 -0
  256. package/dist/transport/BaseTransport.js +200 -0
  257. package/dist/transport/BaseTransport.js.map +1 -0
  258. package/dist/transport/HttpHelpers.d.ts +60 -0
  259. package/dist/transport/HttpHelpers.d.ts.map +1 -0
  260. package/dist/transport/HttpHelpers.js +50 -0
  261. package/dist/transport/HttpHelpers.js.map +1 -0
  262. package/dist/transport/HttpTransport.d.ts +134 -0
  263. package/dist/transport/HttpTransport.d.ts.map +1 -0
  264. package/dist/transport/HttpTransport.js +175 -0
  265. package/dist/transport/HttpTransport.js.map +1 -0
  266. package/dist/transport/SseTransport.d.ts +133 -0
  267. package/dist/transport/SseTransport.d.ts.map +1 -0
  268. package/dist/transport/SseTransport.js +318 -0
  269. package/dist/transport/SseTransport.js.map +1 -0
  270. package/dist/transport/StreamableHttpTransport.d.ts +224 -0
  271. package/dist/transport/StreamableHttpTransport.d.ts.map +1 -0
  272. package/dist/transport/StreamableHttpTransport.js +407 -0
  273. package/dist/transport/StreamableHttpTransport.js.map +1 -0
  274. package/dist/types/disposable.d.ts +22 -0
  275. package/dist/types/disposable.d.ts.map +1 -0
  276. package/dist/types/disposable.js +1 -0
  277. package/dist/types/server-config.d.ts +32 -0
  278. package/dist/types/server-config.d.ts.map +1 -0
  279. package/dist/types/server-config.js +1 -0
  280. package/dist/types/skill.d.ts +69 -0
  281. package/dist/types/skill.d.ts.map +1 -0
  282. package/dist/types/skill.js +1 -0
  283. package/dist/types/tool.d.ts +68 -0
  284. package/dist/types/tool.d.ts.map +1 -0
  285. package/dist/types/tool.js +1 -0
  286. package/dist/watchers/SkillWatcher.d.ts +132 -0
  287. package/dist/watchers/SkillWatcher.d.ts.map +1 -0
  288. package/dist/watchers/SkillWatcher.js +73 -0
  289. package/dist/watchers/SkillWatcher.js.map +1 -0
  290. package/dist/watchers/ToolWatcher.d.ts +109 -0
  291. package/dist/watchers/ToolWatcher.d.ts.map +1 -0
  292. package/dist/watchers/ToolWatcher.js +71 -0
  293. package/dist/watchers/ToolWatcher.js.map +1 -0
  294. package/package.json +95 -0
@@ -0,0 +1,514 @@
1
+ /**
2
+ * History and branch management for sequential thinking.
3
+ *
4
+ * This module provides the `HistoryManager` class which manages thought history,
5
+ * branching, and optional persistence with per-session state isolation.
6
+ *
7
+ * @module HistoryManager
8
+ */
9
+ import type { IMetrics } from '../contracts/index.js';
10
+ import type { Logger } from '../logger/StructuredLogger.js';
11
+ import type { PersistenceBackend } from '../persistence/PersistenceBackend.js';
12
+ import type { IHistoryManager } from './IHistoryManager.js';
13
+ import type { ThoughtData } from './thought.js';
14
+ /**
15
+ * Absolute maximum history size. Cannot be overridden by configuration.
16
+ * Prevents unbounded memory growth from misconfiguration.
17
+ * At ~2KB per thought, 10K thoughts ≈ ~20MB — reasonable for server-side.
18
+ * @constant
19
+ */
20
+ export declare const ABSOLUTE_MAX_HISTORY_SIZE = 10000;
21
+ /**
22
+ * Interface for emitting persistence error events.
23
+ * Compatible with EventEmitter's emit method signature.
24
+ */
25
+ export interface PersistenceEventEmitter {
26
+ emit(event: 'persistenceError', payload: {
27
+ operation: string;
28
+ error: Error;
29
+ }): boolean;
30
+ }
31
+ /**
32
+ * Configuration options for creating a `HistoryManager` instance.
33
+ *
34
+ * @example
35
+ * ```typescript
36
+ * const config: HistoryManagerConfig = {
37
+ * maxHistorySize: 500,
38
+ * maxBranches: 25,
39
+ * maxBranchSize: 50,
40
+ * logger: new StructuredLogger(),
41
+ * persistence: filePersistence
42
+ * };
43
+ * ```
44
+ */
45
+ export interface HistoryManagerConfig {
46
+ /**
47
+ * Maximum number of thoughts to keep in main history.
48
+ * @default 1000
49
+ */
50
+ maxHistorySize?: number;
51
+ /**
52
+ * Maximum number of branches to maintain.
53
+ * @default 50
54
+ */
55
+ maxBranches?: number;
56
+ /**
57
+ * Maximum size of each branch.
58
+ * @default 100
59
+ */
60
+ maxBranchSize?: number;
61
+ /** Optional logger for diagnostics. */
62
+ logger?: Logger;
63
+ /** Optional persistence backend for saving/loading history. */
64
+ persistence?: PersistenceBackend | null;
65
+ metrics?: IMetrics;
66
+ /**
67
+ * Maximum number of thoughts to buffer before flushing to persistence.
68
+ * @default 100
69
+ */
70
+ persistenceBufferSize?: number;
71
+ /**
72
+ * Interval in milliseconds between periodic persistence flushes.
73
+ * @default 1000
74
+ */
75
+ persistenceFlushInterval?: number;
76
+ /**
77
+ * Maximum number of retries for failed persistence flushes.
78
+ * @default 3
79
+ */
80
+ persistenceMaxRetries?: number;
81
+ /**
82
+ * Event emitter for persistence error events.
83
+ * When provided, persistenceError events are emitted on persistent failures.
84
+ */
85
+ eventEmitter?: PersistenceEventEmitter;
86
+ }
87
+ /**
88
+ * Manages thought history and branching for sequential thinking.
89
+ *
90
+ * This class is the central component for managing the state of sequential thinking
91
+ * operations. It handles thought storage, branch management, and optional persistence
92
+ * for state recovery. State is isolated per session via a `Map<string, SessionState>`.
93
+ *
94
+ * @remarks
95
+ * **History Management:**
96
+ * - Thoughts are stored in a linear history array per session
97
+ * - Auto-trimming occurs when `maxHistorySize` is exceeded
98
+ * - Oldest thoughts are removed first (FIFO eviction)
99
+ *
100
+ * **Session Isolation:**
101
+ * - Each session maintains its own thought history, branches, and cached tools/skills
102
+ * - Sessions are identified by optional `session_id` on ThoughtData
103
+ * - Default (undefined) session_id maps to `__global__`
104
+ * - TTL-based cleanup prevents unbounded memory growth
105
+ * - LRU eviction when MAX_SESSIONS exceeded
106
+ *
107
+ * **Branch Management:**
108
+ * - Branches allow exploring alternative reasoning paths
109
+ * - Each branch has its own thought array within a session
110
+ * - Branches are created when `branch_from_thought` and `branch_id` are set
111
+ * - Branch count and size are limited by `maxBranches` and `maxBranchSize`
112
+ *
113
+ * **Persistence:**
114
+ * - Optional persistence backend for saving/loading state
115
+ * - Persists thoughts and branches asynchronously (fire-and-forget)
116
+ * - Does not block on persistence failures
117
+ *
118
+ * @example
119
+ * ```typescript
120
+ * const manager = new HistoryManager({
121
+ * maxHistorySize: 500,
122
+ * maxBranches: 25,
123
+ * logger: new StructuredLogger({ context: 'History' })
124
+ * });
125
+ *
126
+ * // Add a thought
127
+ * manager.addThought({
128
+ * thought: 'I need to analyze the problem',
129
+ * thought_number: 1,
130
+ * total_thoughts: 5,
131
+ * next_thought_needed: true
132
+ * });
133
+ *
134
+ * // Get history
135
+ * const history = manager.getHistory();
136
+ * console.log(`Thoughts: ${history.length}`);
137
+ *
138
+ * // Get branches
139
+ * const branches = manager.getBranches();
140
+ * console.log(`Branches: ${Object.keys(branches).length}`);
141
+ *
142
+ * // Clear all state
143
+ * manager.clear();
144
+ * ```
145
+ */
146
+ export declare class HistoryManager implements IHistoryManager {
147
+ /** Default session key for backward-compatible global state. */
148
+ private static readonly DEFAULT_SESSION;
149
+ /** TTL for inactive sessions in milliseconds (default: 30 minutes). */
150
+ private static readonly SESSION_TTL_MS;
151
+ /** Maximum number of concurrent sessions before eviction. */
152
+ private static readonly MAX_SESSIONS;
153
+ /** Session state storage. */
154
+ private _sessions;
155
+ /** Timer for periodic session cleanup. */
156
+ private _sessionCleanupTimer;
157
+ /** Maximum history size before auto-trimming. */
158
+ private _maxHistorySize;
159
+ /** Maximum number of branches before cleanup. */
160
+ private _maxBranches;
161
+ /** Maximum size of each branch. */
162
+ private _maxBranchSize;
163
+ /** Logger for diagnostics. */
164
+ private _logger;
165
+ /** Persistence backend for saving/loading state. */
166
+ private _persistence;
167
+ /** Whether persistence is enabled. */
168
+ private _persistenceEnabled;
169
+ private _metrics?;
170
+ /** Timer for periodic buffer flushes. */
171
+ private _flushTimer;
172
+ /** Guard to prevent concurrent flushes. */
173
+ private _isFlushing;
174
+ /** Tracks consecutive flush failures for backoff. */
175
+ private _flushRetryCount;
176
+ /** Maximum buffer size before triggering immediate flush. */
177
+ private _persistenceBufferSize;
178
+ /** Interval in milliseconds between periodic flushes. */
179
+ private _persistenceFlushInterval;
180
+ /** Maximum number of retries for failed flushes. */
181
+ private _persistenceMaxRetries;
182
+ /** Event emitter for persistence error events. */
183
+ private _eventEmitter;
184
+ /**
185
+ * Creates a new HistoryManager instance.
186
+ *
187
+ * @param config - Configuration options for the history manager
188
+ *
189
+ * @example
190
+ * ```typescript
191
+ * const manager = new HistoryManager({
192
+ * maxHistorySize: 500,
193
+ * maxBranches: 25,
194
+ * logger: new StructuredLogger(),
195
+ * persistence: filePersistence
196
+ * });
197
+ * ```
198
+ */
199
+ constructor(config?: HistoryManagerConfig);
200
+ /**
201
+ * Internal logging method.
202
+ * @param message - The message to log
203
+ * @param meta - Optional metadata
204
+ * @private
205
+ */
206
+ private log;
207
+ /**
208
+ * Gets or creates the session state for a given session ID.
209
+ * Creates a new SessionState if one doesn't exist.
210
+ * Updates lastAccessedAt on every access.
211
+ *
212
+ * @param sessionId - Optional session ID (defaults to `__global__`)
213
+ * @returns The session state
214
+ * @private
215
+ */
216
+ private _getSession;
217
+ /**
218
+ * Adds a thought to the history.
219
+ *
220
+ * The thought is appended to the session's history array. If history exceeds
221
+ * `maxHistorySize`, the oldest thoughts are removed. If the thought
222
+ * has `branch_from_thought` and `branch_id` set, it's also added to
223
+ * the appropriate branch. The thought is persisted asynchronously if
224
+ * persistence is enabled.
225
+ *
226
+ * @param thought - The thought data to add
227
+ *
228
+ * @example
229
+ * ```typescript
230
+ * manager.addThought({
231
+ * thought: 'I should read the README file',
232
+ * thought_number: 1,
233
+ * total_thoughts: 3,
234
+ * next_thought_needed: true
235
+ * });
236
+ * ```
237
+ */
238
+ addThought(thought: ThoughtData): void;
239
+ /**
240
+ * Buffers a thought for persistence if enabled.
241
+ * @param session - The session state to buffer into
242
+ * @param thought - The thought to buffer
243
+ * @private
244
+ */
245
+ private _bufferForPersistence;
246
+ /**
247
+ * Adds a thought to a branch within a specific session.
248
+ * @param session - The session state
249
+ * @param branchId - The branch identifier
250
+ * @param thought - The thought data to add
251
+ * @private
252
+ */
253
+ private _addToSessionBranch;
254
+ /**
255
+ * Removes old branches when count exceeds maxBranches within a session.
256
+ * @param session - The session state
257
+ * @private
258
+ */
259
+ private _cleanupSessionBranches;
260
+ /**
261
+ * Trims a branch to maxBranchSize within a session.
262
+ * @param session - The session state
263
+ * @param branchId - The branch identifier to trim
264
+ * @private
265
+ */
266
+ private _trimSessionBranchSize;
267
+ /**
268
+ * Gets the complete thought history.
269
+ *
270
+ * @param sessionId - Optional session ID for session-scoped results
271
+ * @returns An array of all thoughts in chronological order
272
+ *
273
+ * @example
274
+ * ```typescript
275
+ * const history = manager.getHistory();
276
+ * history.forEach(thought => {
277
+ * console.log(`${thought.thought_number}: ${thought.thought}`);
278
+ * });
279
+ * ```
280
+ */
281
+ getHistory(sessionId?: string): ThoughtData[];
282
+ /**
283
+ * Gets the current length of the thought history.
284
+ *
285
+ * @param sessionId - Optional session ID for session-scoped results
286
+ * @returns The number of thoughts in history
287
+ *
288
+ * @example
289
+ * ```typescript
290
+ * console.log(`Total thoughts: ${manager.getHistoryLength()}`);
291
+ * ```
292
+ */
293
+ getHistoryLength(sessionId?: string): number;
294
+ /**
295
+ * Gets all branches.
296
+ *
297
+ * @param sessionId - Optional session ID for session-scoped results
298
+ * @returns A record mapping branch IDs to their thought arrays
299
+ *
300
+ * @example
301
+ * ```typescript
302
+ * const branches = manager.getBranches();
303
+ * for (const [branchId, thoughts] of Object.entries(branches)) {
304
+ * console.log(`Branch ${branchId}: ${thoughts.length} thoughts`);
305
+ * }
306
+ * ```
307
+ */
308
+ getBranches(sessionId?: string): Record<string, ThoughtData[]>;
309
+ /**
310
+ * Gets all branch IDs.
311
+ *
312
+ * @param sessionId - Optional session ID for session-scoped results
313
+ * @returns An array of branch identifiers
314
+ *
315
+ * @example
316
+ * ```typescript
317
+ * const branchIds = manager.getBranchIds();
318
+ * console.log(`Active branches: ${branchIds.join(', ')}`);
319
+ * ```
320
+ */
321
+ getBranchIds(sessionId?: string): string[];
322
+ /**
323
+ * Gets the most recently available MCP tools from the session.
324
+ *
325
+ * @param sessionId - Optional session ID for session-scoped results
326
+ * @returns The last-seen array of MCP tool names, or undefined if never set
327
+ *
328
+ * @example
329
+ * ```typescript
330
+ * const tools = manager.getAvailableMcpTools();
331
+ * // ['Read', 'Grep', 'Glob'] or undefined
332
+ * ```
333
+ */
334
+ getAvailableMcpTools(sessionId?: string): string[] | undefined;
335
+ /**
336
+ * Gets the most recently available skills from the session.
337
+ *
338
+ * @param sessionId - Optional session ID for session-scoped results
339
+ * @returns The last-seen array of skill names, or undefined if never set
340
+ *
341
+ * @example
342
+ * ```typescript
343
+ * const skills = manager.getAvailableSkills();
344
+ * // ['commit', 'review-pr'] or undefined
345
+ * ```
346
+ */
347
+ getAvailableSkills(sessionId?: string): string[] | undefined;
348
+ /**
349
+ * Gets a specific branch by ID.
350
+ *
351
+ * @param branchId - The branch identifier
352
+ * @param sessionId - Optional session ID for session-scoped results
353
+ * @returns The branch's thought array, or undefined if not found
354
+ *
355
+ * @example
356
+ * ```typescript
357
+ * const branch = manager.getBranch('alternative-approach');
358
+ * if (branch) {
359
+ * console.log(`Branch has ${branch.length} thoughts`);
360
+ * } else {
361
+ * console.log('Branch not found');
362
+ * }
363
+ * ```
364
+ */
365
+ getBranch(branchId: string, sessionId?: string): ThoughtData[] | undefined;
366
+ /**
367
+ * Clears history and branches.
368
+ * If sessionId is provided, clears only that session.
369
+ * If omitted, clears all sessions.
370
+ *
371
+ * @param sessionId - Optional session ID to clear
372
+ *
373
+ * @example
374
+ * ```typescript
375
+ * manager.clear();
376
+ * console.log('All history and branches cleared');
377
+ * ```
378
+ */
379
+ clear(sessionId?: string): void;
380
+ /** Clears state for a specific session. Alias for clear(sessionId). */
381
+ clearSession(sessionId: string): void;
382
+ /** Gets all active session IDs. */
383
+ getSessionIds(): string[];
384
+ /** Gets the number of active sessions. */
385
+ getSessionCount(): number;
386
+ /**
387
+ * Loads history from the persistence backend.
388
+ *
389
+ * This should be called during initialization to restore previous state.
390
+ * Only loads if persistence is enabled and the backend is healthy.
391
+ * Loads into the global session.
392
+ *
393
+ * @returns Promise that resolves when loading is complete
394
+ *
395
+ * @example
396
+ * ```typescript
397
+ * await manager.loadFromPersistence();
398
+ * console.log(`Loaded ${manager.getHistoryLength()} thoughts`);
399
+ * ```
400
+ */
401
+ loadFromPersistence(): Promise<void>;
402
+ /**
403
+ * Checks if persistence is enabled.
404
+ *
405
+ * @returns true if persistence is enabled, false otherwise
406
+ *
407
+ * @example
408
+ * ```typescript
409
+ * if (manager.isPersistenceEnabled()) {
410
+ * console.log('Persistence is active');
411
+ * }
412
+ * ```
413
+ */
414
+ isPersistenceEnabled(): boolean;
415
+ /**
416
+ * Gets the persistence backend instance.
417
+ *
418
+ * @returns The persistence backend, or null if not configured
419
+ *
420
+ * @example
421
+ * ```typescript
422
+ * const backend = manager.getPersistenceBackend();
423
+ * if (backend) {
424
+ * await backend.healthy();
425
+ * }
426
+ * ```
427
+ */
428
+ getPersistenceBackend(): PersistenceBackend | null;
429
+ /**
430
+ * Sets the event emitter for persistence error events.
431
+ * This allows wiring up the event emitter after construction
432
+ * (e.g., when the server instance is the emitter).
433
+ *
434
+ * @param emitter - The event emitter to use for persistence error events
435
+ */
436
+ setEventEmitter(emitter: PersistenceEventEmitter): void;
437
+ /**
438
+ * Gracefully shuts down the write buffer and session cleanup.
439
+ * Stops the periodic flush timer and session cleanup timer,
440
+ * then flushes any remaining buffered writes.
441
+ * Should be called during server shutdown before closing the persistence backend.
442
+ */
443
+ shutdown(): Promise<void>;
444
+ /**
445
+ * Starts the periodic flush timer for the write buffer.
446
+ * @private
447
+ */
448
+ private _startFlushTimer;
449
+ /**
450
+ * Stops the periodic flush timer.
451
+ * @private
452
+ */
453
+ private _stopFlushTimer;
454
+ /**
455
+ * Starts the periodic session cleanup timer.
456
+ * Runs every 5 minutes to evict sessions that exceeded TTL.
457
+ * @private
458
+ */
459
+ private _startSessionCleanupTimer;
460
+ /**
461
+ * Stops the periodic session cleanup timer.
462
+ * @private
463
+ */
464
+ private _stopSessionCleanupTimer;
465
+ /**
466
+ * Evicts sessions that have been inactive longer than SESSION_TTL_MS.
467
+ * The global session is never evicted.
468
+ * @private
469
+ */
470
+ private _cleanupStaleSessions;
471
+ /**
472
+ * Evicts oldest sessions when MAX_SESSIONS is exceeded (LRU).
473
+ * The global session is never evicted.
474
+ * @private
475
+ */
476
+ private _evictExcessSessions;
477
+ /**
478
+ * Flushes the write buffer to the persistence backend.
479
+ *
480
+ * Collects all buffered thoughts across all sessions and saves them
481
+ * individually with retry logic. On persistent failure (all retries exhausted),
482
+ * emits a `persistenceError` event and re-queues failed items.
483
+ *
484
+ * This method is safe to call concurrently — duplicate calls are skipped.
485
+ * @internal
486
+ */
487
+ _flushBuffer(): Promise<void>;
488
+ /**
489
+ * Flushes a single thought to persistence with retry logic.
490
+ * @param thought - The thought to flush
491
+ * @returns true if saved successfully, false otherwise
492
+ * @private
493
+ */
494
+ private _flushSingleThought;
495
+ /**
496
+ * Handles the result of a flush operation, re-queuing failures.
497
+ * @param failedItems - Thoughts that failed to persist
498
+ * @param totalCount - Total number of thoughts attempted
499
+ * @private
500
+ */
501
+ private _handleFlushResult;
502
+ /**
503
+ * Returns a promise that resolves after the specified delay.
504
+ * @param ms - Delay in milliseconds
505
+ * @private
506
+ */
507
+ private _delay;
508
+ /**
509
+ * Gets the current write buffer length across all sessions.
510
+ * Useful for monitoring and testing.
511
+ */
512
+ getWriteBufferLength(): number;
513
+ }
514
+ //# sourceMappingURL=HistoryManager.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"HistoryManager.d.ts","sourceRoot":"","sources":["../../src/core/HistoryManager.ts"],"names":[],"mappings":"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"}