@vybestack/llxprt-code-core 0.11.0 → 0.12.0-nightly.260910.2aac6841e

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 (417) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.js +1 -1
  3. package/dist/index.js.map +1 -1
  4. package/dist/prompt-config/defaults/default-prompts.json +3 -3
  5. package/dist/src/config/agentClientLifecycle.d.ts +4 -3
  6. package/dist/src/config/agentClientLifecycle.js +27 -14
  7. package/dist/src/config/agentClientLifecycle.js.map +1 -1
  8. package/dist/src/config/config.d.ts +2 -5
  9. package/dist/src/config/config.js +10 -23
  10. package/dist/src/config/config.js.map +1 -1
  11. package/dist/src/config/configBase.d.ts +5 -1
  12. package/dist/src/config/configBase.js +27 -6
  13. package/dist/src/config/configBase.js.map +1 -1
  14. package/dist/src/config/configBaseCore.d.ts +26 -8
  15. package/dist/src/config/configBaseCore.js +30 -26
  16. package/dist/src/config/configBaseCore.js.map +1 -1
  17. package/dist/src/config/configMcpRuntime.d.ts +16 -0
  18. package/dist/src/config/configMcpRuntime.js +31 -0
  19. package/dist/src/config/configMcpRuntime.js.map +1 -0
  20. package/dist/src/config/configMediaDefaults.d.ts +10 -0
  21. package/dist/src/config/configMediaDefaults.js +17 -0
  22. package/dist/src/config/configMediaDefaults.js.map +1 -0
  23. package/dist/src/config/configTestHarness.d.ts +4 -0
  24. package/dist/src/config/configTypes.d.ts +4 -54
  25. package/dist/src/config/configTypes.js +6 -82
  26. package/dist/src/config/configTypes.js.map +1 -1
  27. package/dist/src/config/index.d.ts +1 -2
  28. package/dist/src/config/index.js +1 -2
  29. package/dist/src/config/index.js.map +1 -1
  30. package/dist/src/config/models.d.ts +0 -4
  31. package/dist/src/config/models.js +0 -4
  32. package/dist/src/config/models.js.map +1 -1
  33. package/dist/src/config/toolRegistryFactory.d.ts +2 -2
  34. package/dist/src/core/clientContract.d.ts +4 -6
  35. package/dist/src/core/compression/transcriptPathNotice.d.ts +22 -0
  36. package/dist/src/core/compression/transcriptPathNotice.js +29 -0
  37. package/dist/src/core/compression/transcriptPathNotice.js.map +1 -0
  38. package/dist/src/core/contentGenerator.d.ts +2 -5
  39. package/dist/src/core/contentGenerator.js +10 -24
  40. package/dist/src/core/contentGenerator.js.map +1 -1
  41. package/dist/src/core/logger.d.ts +66 -0
  42. package/dist/src/core/logger.js +345 -30
  43. package/dist/src/core/logger.js.map +1 -1
  44. package/dist/src/core/prompts.d.ts +0 -1
  45. package/dist/src/core/prompts.js +5 -79
  46. package/dist/src/core/prompts.js.map +1 -1
  47. package/dist/src/core/turn.d.ts +3 -3
  48. package/dist/src/hooks/hookTranslator.js +5 -4
  49. package/dist/src/hooks/hookTranslator.js.map +1 -1
  50. package/dist/src/index.d.ts +8 -6
  51. package/dist/src/index.js +8 -6
  52. package/dist/src/index.js.map +1 -1
  53. package/dist/src/llm-types/index.d.ts +1 -1
  54. package/dist/src/llm-types/modelEnvelope.d.ts +2 -1
  55. package/dist/src/llm-types/modelEnvelope.js +17 -1
  56. package/dist/src/llm-types/modelEnvelope.js.map +1 -1
  57. package/dist/src/models/schema.d.ts +40 -40
  58. package/dist/src/policy/policies/read-only.toml +0 -5
  59. package/dist/src/prompt-config/TemplateEngine.js +0 -3
  60. package/dist/src/prompt-config/TemplateEngine.js.map +1 -1
  61. package/dist/src/prompt-config/defaults/providers/gemini/core.md +0 -2
  62. package/dist/src/prompt-config/defaults/providers/gemini/models/gemini-2.5-flash/core.md +0 -2
  63. package/dist/src/prompt-config/defaults/providers/gemini/models/gemini-2.5-flash/gemini-2-5-flash/core.md +0 -2
  64. package/dist/src/prompt-config/prompt-loader.d.ts +1 -1
  65. package/dist/src/prompt-config/prompt-loader.js +4 -4
  66. package/dist/src/prompt-config/prompt-loader.js.map +1 -1
  67. package/dist/src/prompt-config/types.d.ts +0 -1
  68. package/dist/src/recording/CheckpointService.d.ts +4 -0
  69. package/dist/src/recording/CheckpointService.js +67 -46
  70. package/dist/src/recording/CheckpointService.js.map +1 -1
  71. package/dist/src/recording/HistoryMutationService.d.ts +1 -1
  72. package/dist/src/recording/HistoryMutationService.js +27 -4
  73. package/dist/src/recording/HistoryMutationService.js.map +1 -1
  74. package/dist/src/recording/RecordingIntegration.d.ts +36 -2
  75. package/dist/src/recording/RecordingIntegration.js +224 -7
  76. package/dist/src/recording/RecordingIntegration.js.map +1 -1
  77. package/dist/src/recording/ReplayEngine.d.ts +8 -10
  78. package/dist/src/recording/ReplayEngine.js +161 -95
  79. package/dist/src/recording/ReplayEngine.js.map +1 -1
  80. package/dist/src/recording/SessionDiscovery.d.ts +4 -2
  81. package/dist/src/recording/SessionDiscovery.js +13 -5
  82. package/dist/src/recording/SessionDiscovery.js.map +1 -1
  83. package/dist/src/recording/SessionRecordingService.d.ts +23 -3
  84. package/dist/src/recording/SessionRecordingService.js +209 -51
  85. package/dist/src/recording/SessionRecordingService.js.map +1 -1
  86. package/dist/src/recording/SessionTransitionService.d.ts +7 -0
  87. package/dist/src/recording/SessionTransitionService.js +66 -13
  88. package/dist/src/recording/SessionTransitionService.js.map +1 -1
  89. package/dist/src/recording/index.d.ts +1 -0
  90. package/dist/src/recording/index.js +1 -0
  91. package/dist/src/recording/index.js.map +1 -1
  92. package/dist/src/recording/janitor/cleanupTypes.d.ts +3 -0
  93. package/dist/src/recording/janitor/cleanupTypes.js.map +1 -1
  94. package/dist/src/recording/janitor/mediaReclamation.d.ts +23 -0
  95. package/dist/src/recording/janitor/mediaReclamation.js +195 -0
  96. package/dist/src/recording/janitor/mediaReclamation.js.map +1 -0
  97. package/dist/src/recording/janitor/sessionJanitor.js +47 -1
  98. package/dist/src/recording/janitor/sessionJanitor.js.map +1 -1
  99. package/dist/src/recording/janitor/sessionScanner.d.ts +12 -9
  100. package/dist/src/recording/janitor/sessionScanner.js +248 -193
  101. package/dist/src/recording/janitor/sessionScanner.js.map +1 -1
  102. package/dist/src/recording/replay-test-helpers.d.ts +10 -1
  103. package/dist/src/recording/replay-test-helpers.js +24 -2
  104. package/dist/src/recording/replay-test-helpers.js.map +1 -1
  105. package/dist/src/recording/replayCheckpointMetadata.d.ts +28 -0
  106. package/dist/src/recording/replayCheckpointMetadata.js +96 -0
  107. package/dist/src/recording/replayCheckpointMetadata.js.map +1 -0
  108. package/dist/src/recording/replayErrorFormatting.d.ts +6 -0
  109. package/dist/src/recording/replayErrorFormatting.js +38 -0
  110. package/dist/src/recording/replayErrorFormatting.js.map +1 -0
  111. package/dist/src/recording/resumeSession.d.ts +3 -0
  112. package/dist/src/recording/resumeSession.js +7 -1
  113. package/dist/src/recording/resumeSession.js.map +1 -1
  114. package/dist/src/recording/semanticMediaPurgeReplayValidation.d.ts +14 -0
  115. package/dist/src/recording/semanticMediaPurgeReplayValidation.js +24 -0
  116. package/dist/src/recording/semanticMediaPurgeReplayValidation.js.map +1 -0
  117. package/dist/src/recording/session-media-package-blobs.d.ts +8 -0
  118. package/dist/src/recording/session-media-package-blobs.js +72 -0
  119. package/dist/src/recording/session-media-package-blobs.js.map +1 -0
  120. package/dist/src/recording/session-media-package-import.d.ts +26 -0
  121. package/dist/src/recording/session-media-package-import.js +124 -0
  122. package/dist/src/recording/session-media-package-import.js.map +1 -0
  123. package/dist/src/recording/session-media-package-state.d.ts +19 -0
  124. package/dist/src/recording/session-media-package-state.js +56 -0
  125. package/dist/src/recording/session-media-package-state.js.map +1 -0
  126. package/dist/src/recording/session-media-package-validation.d.ts +59 -0
  127. package/dist/src/recording/session-media-package-validation.js +286 -0
  128. package/dist/src/recording/session-media-package-validation.js.map +1 -0
  129. package/dist/src/recording/session-media-package-writer.d.ts +18 -0
  130. package/dist/src/recording/session-media-package-writer.js +70 -0
  131. package/dist/src/recording/session-media-package-writer.js.map +1 -0
  132. package/dist/src/recording/session-media-package.d.ts +27 -0
  133. package/dist/src/recording/session-media-package.js +366 -0
  134. package/dist/src/recording/session-media-package.js.map +1 -0
  135. package/dist/src/recording/types.d.ts +34 -2
  136. package/dist/src/recording/types.js.map +1 -1
  137. package/dist/src/runtime/AgentRuntimeContext.d.ts +22 -5
  138. package/dist/src/runtime/AgentRuntimeLoader.d.ts +6 -0
  139. package/dist/src/runtime/AgentRuntimeLoader.js +25 -6
  140. package/dist/src/runtime/AgentRuntimeLoader.js.map +1 -1
  141. package/dist/src/runtime/contracts/PromptEstimation.d.ts +1 -0
  142. package/dist/src/runtime/contracts/PromptEstimation.js.map +1 -1
  143. package/dist/src/runtime/contracts/RuntimeProvider.d.ts +3 -2
  144. package/dist/src/runtime/contracts/RuntimeProviderManager.d.ts +0 -2
  145. package/dist/src/runtime/createAgentRuntimeContext.js +28 -1
  146. package/dist/src/runtime/createAgentRuntimeContext.js.map +1 -1
  147. package/dist/src/runtime/providerRuntimeContext.d.ts +12 -0
  148. package/dist/src/runtime/providerRuntimeContext.js +3 -0
  149. package/dist/src/runtime/providerRuntimeContext.js.map +1 -1
  150. package/dist/src/runtime/runtimeAdapters.js +2 -2
  151. package/dist/src/runtime/runtimeAdapters.js.map +1 -1
  152. package/dist/src/services/history/ContentConverters.d.ts +11 -7
  153. package/dist/src/services/history/ContentConverters.js +11 -7
  154. package/dist/src/services/history/ContentConverters.js.map +1 -1
  155. package/dist/src/services/history/HistoryService.d.ts +18 -180
  156. package/dist/src/services/history/HistoryService.js +53 -523
  157. package/dist/src/services/history/HistoryService.js.map +1 -1
  158. package/dist/src/services/history/HistoryServiceCore.d.ts +278 -0
  159. package/dist/src/services/history/HistoryServiceCore.js +727 -0
  160. package/dist/src/services/history/HistoryServiceCore.js.map +1 -0
  161. package/dist/src/services/history/IContent.d.ts +118 -16
  162. package/dist/src/services/history/IContent.js +284 -4
  163. package/dist/src/services/history/IContent.js.map +1 -1
  164. package/dist/src/services/history/contentSize.js +22 -2
  165. package/dist/src/services/history/contentSize.js.map +1 -1
  166. package/dist/src/services/history/historyChronology.d.ts +7 -0
  167. package/dist/src/services/history/historyChronology.js +35 -3
  168. package/dist/src/services/history/historyChronology.js.map +1 -1
  169. package/dist/src/services/history/historyCloneUtils.d.ts +5 -4
  170. package/dist/src/services/history/historyCloneUtils.js +23 -16
  171. package/dist/src/services/history/historyCloneUtils.js.map +1 -1
  172. package/dist/src/services/history/historyCompressionQueue.d.ts +33 -0
  173. package/dist/src/services/history/historyCompressionQueue.js +81 -0
  174. package/dist/src/services/history/historyCompressionQueue.js.map +1 -0
  175. package/dist/src/services/history/historyEventTypes.d.ts +3 -0
  176. package/dist/src/services/history/historyMutationFailure.d.ts +15 -0
  177. package/dist/src/services/history/historyMutationFailure.js +22 -0
  178. package/dist/src/services/history/historyMutationFailure.js.map +1 -1
  179. package/dist/src/services/history/historyProviderPipeline.d.ts +1 -1
  180. package/dist/src/services/history/historyProviderPipeline.js +15 -5
  181. package/dist/src/services/history/historyProviderPipeline.js.map +1 -1
  182. package/dist/src/services/history/historyTokenEstimation.js +10 -6
  183. package/dist/src/services/history/historyTokenEstimation.js.map +1 -1
  184. package/dist/src/services/history/historyToolNormalization.d.ts +2 -0
  185. package/dist/src/services/history/historyToolNormalization.js +26 -9
  186. package/dist/src/services/history/historyToolNormalization.js.map +1 -1
  187. package/dist/src/services/history/provider-file-binding.d.ts +11 -0
  188. package/dist/src/services/history/provider-file-binding.js +70 -0
  189. package/dist/src/services/history/provider-file-binding.js.map +1 -0
  190. package/dist/src/services/history/semantic-media-purge.d.ts +66 -0
  191. package/dist/src/services/history/semantic-media-purge.js +404 -0
  192. package/dist/src/services/history/semantic-media-purge.js.map +1 -0
  193. package/dist/src/storage/SessionPersistenceService.d.ts +53 -2
  194. package/dist/src/storage/SessionPersistenceService.js +435 -23
  195. package/dist/src/storage/SessionPersistenceService.js.map +1 -1
  196. package/dist/src/storage/history-media-ownership.d.ts +38 -0
  197. package/dist/src/storage/history-media-ownership.js +136 -0
  198. package/dist/src/storage/history-media-ownership.js.map +1 -0
  199. package/dist/src/storage/local-media-store-child.d.ts +6 -0
  200. package/dist/src/storage/local-media-store-child.js +140 -0
  201. package/dist/src/storage/local-media-store-child.js.map +1 -0
  202. package/dist/src/storage/local-media-store-files.d.ts +44 -0
  203. package/dist/src/storage/local-media-store-files.js +460 -0
  204. package/dist/src/storage/local-media-store-files.js.map +1 -0
  205. package/dist/src/storage/local-media-store-lock-recovery.d.ts +15 -0
  206. package/dist/src/storage/local-media-store-lock-recovery.js +112 -0
  207. package/dist/src/storage/local-media-store-lock-recovery.js.map +1 -0
  208. package/dist/src/storage/local-media-store-persistence.d.ts +48 -0
  209. package/dist/src/storage/local-media-store-persistence.js +443 -0
  210. package/dist/src/storage/local-media-store-persistence.js.map +1 -0
  211. package/dist/src/storage/local-media-store-quota.d.ts +6 -0
  212. package/dist/src/storage/local-media-store-quota.js +66 -0
  213. package/dist/src/storage/local-media-store-quota.js.map +1 -0
  214. package/dist/src/storage/local-media-store-reservations.d.ts +55 -0
  215. package/dist/src/storage/local-media-store-reservations.js +377 -0
  216. package/dist/src/storage/local-media-store-reservations.js.map +1 -0
  217. package/dist/src/storage/local-media-store-types.d.ts +110 -0
  218. package/dist/src/storage/local-media-store-types.js +35 -0
  219. package/dist/src/storage/local-media-store-types.js.map +1 -0
  220. package/dist/src/storage/local-media-store-validation.d.ts +34 -0
  221. package/dist/src/storage/local-media-store-validation.js +449 -0
  222. package/dist/src/storage/local-media-store-validation.js.map +1 -0
  223. package/dist/src/storage/local-media-store.d.ts +47 -0
  224. package/dist/src/storage/local-media-store.js +353 -0
  225. package/dist/src/storage/local-media-store.js.map +1 -0
  226. package/dist/src/storage/media-admission-service.d.ts +49 -0
  227. package/dist/src/storage/media-admission-service.js +333 -0
  228. package/dist/src/storage/media-admission-service.js.map +1 -0
  229. package/dist/src/storage/media-lifecycle-metrics.d.ts +75 -0
  230. package/dist/src/storage/media-lifecycle-metrics.js +105 -0
  231. package/dist/src/storage/media-lifecycle-metrics.js.map +1 -0
  232. package/dist/src/storage/media-reference-lifecycle.d.ts +16 -0
  233. package/dist/src/storage/media-reference-lifecycle.js +84 -0
  234. package/dist/src/storage/media-reference-lifecycle.js.map +1 -0
  235. package/dist/src/storage/request-media-resolver.d.ts +67 -0
  236. package/dist/src/storage/request-media-resolver.js +325 -0
  237. package/dist/src/storage/request-media-resolver.js.map +1 -0
  238. package/dist/src/storage/session-media-service-factories.d.ts +19 -0
  239. package/dist/src/storage/session-media-service-factories.js +34 -0
  240. package/dist/src/storage/session-media-service-factories.js.map +1 -0
  241. package/dist/src/storage/session-persistence-helpers.d.ts +10 -0
  242. package/dist/src/storage/session-persistence-helpers.js +46 -0
  243. package/dist/src/storage/session-persistence-helpers.js.map +1 -0
  244. package/dist/src/test-utils/config.d.ts +2 -0
  245. package/dist/src/test-utils/config.js +5 -5
  246. package/dist/src/test-utils/config.js.map +1 -1
  247. package/dist/src/test-utils/runtime.d.ts +2 -0
  248. package/dist/src/test-utils/runtime.js +1 -2
  249. package/dist/src/test-utils/runtime.js.map +1 -1
  250. package/dist/src/tools-adapters/CoreShellToolHostAdapter.js +1 -9
  251. package/dist/src/tools-adapters/CoreShellToolHostAdapter.js.map +1 -1
  252. package/dist/src/tools-adapters/CoreSkillServiceAdapter.d.ts +0 -2
  253. package/dist/src/tools-adapters/CoreSkillServiceAdapter.js +0 -17
  254. package/dist/src/tools-adapters/CoreSkillServiceAdapter.js.map +1 -1
  255. package/dist/src/tools-adapters/CoreToolHostAdapter.d.ts +0 -21
  256. package/dist/src/tools-adapters/CoreToolHostAdapter.js +0 -8
  257. package/dist/src/tools-adapters/CoreToolHostAdapter.js.map +1 -1
  258. package/dist/src/utils/environmentContext.d.ts +8 -9
  259. package/dist/src/utils/environmentContext.js +11 -22
  260. package/dist/src/utils/environmentContext.js.map +1 -1
  261. package/dist/src/utils/errorParsing.d.ts +1 -2
  262. package/dist/src/utils/errorParsing.js +22 -41
  263. package/dist/src/utils/errorParsing.js.map +1 -1
  264. package/dist/src/utils/generateContentResponseUtilities.js +12 -0
  265. package/dist/src/utils/generateContentResponseUtilities.js.map +1 -1
  266. package/dist/src/utils/summarizer.d.ts +1 -2
  267. package/dist/src/utils/summarizer.js +6 -5
  268. package/dist/src/utils/summarizer.js.map +1 -1
  269. package/dist/src/utils/tool-utils.js +7 -1
  270. package/dist/src/utils/tool-utils.js.map +1 -1
  271. package/index.ts +0 -4
  272. package/package.json +38 -30
  273. package/src/config/agentClientLifecycle.ts +53 -22
  274. package/src/config/config.ts +11 -26
  275. package/src/config/configBase.ts +46 -7
  276. package/src/config/configBaseCore.ts +38 -36
  277. package/src/config/configMcpRuntime.ts +46 -0
  278. package/src/config/configMediaDefaults.ts +19 -0
  279. package/src/config/configTypes.ts +13 -53
  280. package/src/config/index.ts +1 -4
  281. package/src/config/models.ts +0 -6
  282. package/src/config/toolRegistryFactory.ts +2 -2
  283. package/src/core/clientContract.ts +4 -6
  284. package/src/core/compression/transcriptPathNotice.ts +31 -0
  285. package/src/core/contentGenerator.ts +15 -39
  286. package/src/core/logger.ts +370 -39
  287. package/src/core/prompts.ts +4 -114
  288. package/src/core/turn.ts +3 -3
  289. package/src/hooks/hookTranslator.ts +6 -4
  290. package/src/index.ts +7 -7
  291. package/src/llm-types/index.ts +5 -0
  292. package/src/llm-types/modelEnvelope.ts +26 -2
  293. package/src/policy/policies/read-only.toml +0 -5
  294. package/src/prompt-config/TemplateEngine.ts +0 -3
  295. package/src/prompt-config/defaults/providers/gemini/core.md +0 -2
  296. package/src/prompt-config/defaults/providers/gemini/models/gemini-2.5-flash/core.md +0 -2
  297. package/src/prompt-config/defaults/providers/gemini/models/gemini-2.5-flash/gemini-2-5-flash/core.md +0 -2
  298. package/src/prompt-config/prompt-loader.ts +7 -8
  299. package/src/prompt-config/types.ts +0 -1
  300. package/src/recording/CheckpointService.ts +110 -45
  301. package/src/recording/HistoryMutationService.ts +28 -3
  302. package/src/recording/RecordingIntegration.ts +258 -11
  303. package/src/recording/ReplayEngine.ts +220 -110
  304. package/src/recording/SessionDiscovery.ts +30 -4
  305. package/src/recording/SessionRecordingService.ts +253 -55
  306. package/src/recording/SessionTransitionService.ts +75 -12
  307. package/src/recording/index.ts +7 -0
  308. package/src/recording/janitor/cleanupTypes.ts +4 -0
  309. package/src/recording/janitor/mediaReclamation.ts +295 -0
  310. package/src/recording/janitor/sessionJanitor.ts +54 -1
  311. package/src/recording/janitor/sessionScanner.ts +319 -227
  312. package/src/recording/replay-test-helpers.ts +33 -2
  313. package/src/recording/replayCheckpointMetadata.ts +115 -0
  314. package/src/recording/replayErrorFormatting.ts +43 -0
  315. package/src/recording/resumeSession.ts +10 -0
  316. package/src/recording/semanticMediaPurgeReplayValidation.ts +35 -0
  317. package/src/recording/session-media-package-blobs.ts +116 -0
  318. package/src/recording/session-media-package-import.ts +189 -0
  319. package/src/recording/session-media-package-state.ts +120 -0
  320. package/src/recording/session-media-package-validation.ts +400 -0
  321. package/src/recording/session-media-package-writer.ts +117 -0
  322. package/src/recording/session-media-package.ts +692 -0
  323. package/src/recording/types.ts +37 -2
  324. package/src/runtime/AgentRuntimeContext.ts +28 -5
  325. package/src/runtime/AgentRuntimeLoader.ts +32 -7
  326. package/src/runtime/contracts/PromptEstimation.ts +1 -0
  327. package/src/runtime/contracts/RuntimeProvider.ts +3 -8
  328. package/src/runtime/contracts/RuntimeProviderManager.ts +0 -2
  329. package/src/runtime/createAgentRuntimeContext.ts +43 -1
  330. package/src/runtime/providerRuntimeContext.ts +22 -0
  331. package/src/runtime/runtimeAdapters.ts +2 -2
  332. package/src/services/history/ContentConverters.ts +11 -7
  333. package/src/services/history/HistoryService.ts +71 -696
  334. package/src/services/history/HistoryServiceCore.ts +1055 -0
  335. package/src/services/history/IContent.ts +460 -20
  336. package/src/services/history/contentSize.ts +22 -2
  337. package/src/services/history/historyChronology.ts +53 -3
  338. package/src/services/history/historyCloneUtils.ts +26 -22
  339. package/src/services/history/historyCompressionQueue.ts +102 -0
  340. package/src/services/history/historyEventTypes.ts +9 -0
  341. package/src/services/history/historyMutationFailure.ts +33 -0
  342. package/src/services/history/historyProviderPipeline.ts +19 -5
  343. package/src/services/history/historyTokenEstimation.ts +9 -5
  344. package/src/services/history/historyToolNormalization.ts +43 -11
  345. package/src/services/history/provider-file-binding.ts +115 -0
  346. package/src/services/history/semantic-media-purge.ts +593 -0
  347. package/src/storage/SessionPersistenceService.ts +667 -30
  348. package/src/storage/history-media-ownership.ts +185 -0
  349. package/src/storage/local-media-store-child.ts +163 -0
  350. package/src/storage/local-media-store-files.ts +643 -0
  351. package/src/storage/local-media-store-lock-recovery.ts +159 -0
  352. package/src/storage/local-media-store-persistence.ts +737 -0
  353. package/src/storage/local-media-store-quota.ts +111 -0
  354. package/src/storage/local-media-store-reservations.ts +485 -0
  355. package/src/storage/local-media-store-types.ts +161 -0
  356. package/src/storage/local-media-store-validation.ts +643 -0
  357. package/src/storage/local-media-store.ts +696 -0
  358. package/src/storage/media-admission-service.ts +512 -0
  359. package/src/storage/media-lifecycle-metrics.ts +228 -0
  360. package/src/storage/media-reference-lifecycle.ts +164 -0
  361. package/src/storage/request-media-resolver.ts +491 -0
  362. package/src/storage/session-media-service-factories.ts +48 -0
  363. package/src/storage/session-persistence-helpers.ts +85 -0
  364. package/src/test-utils/config.ts +7 -5
  365. package/src/test-utils/runtime.ts +3 -2
  366. package/src/tools-adapters/CoreShellToolHostAdapter.ts +1 -11
  367. package/src/tools-adapters/CoreSkillServiceAdapter.ts +0 -23
  368. package/src/tools-adapters/CoreToolHostAdapter.ts +0 -36
  369. package/src/utils/environmentContext.ts +11 -30
  370. package/src/utils/errorParsing.ts +19 -69
  371. package/src/utils/generateContentResponseUtilities.ts +28 -1
  372. package/src/utils/summarizer.ts +8 -10
  373. package/src/utils/tool-utils.ts +7 -1
  374. package/dist/src/code_assist/codeAssist.d.ts +0 -19
  375. package/dist/src/code_assist/codeAssist.js +0 -41
  376. package/dist/src/code_assist/codeAssist.js.map +0 -1
  377. package/dist/src/code_assist/contentGeneratorAdapters.d.ts +0 -49
  378. package/dist/src/code_assist/contentGeneratorAdapters.js +0 -197
  379. package/dist/src/code_assist/contentGeneratorAdapters.js.map +0 -1
  380. package/dist/src/code_assist/converter.d.ts +0 -74
  381. package/dist/src/code_assist/converter.js +0 -158
  382. package/dist/src/code_assist/converter.js.map +0 -1
  383. package/dist/src/code_assist/googleGenAIWrapper.d.ts +0 -27
  384. package/dist/src/code_assist/googleGenAIWrapper.js +0 -46
  385. package/dist/src/code_assist/googleGenAIWrapper.js.map +0 -1
  386. package/dist/src/code_assist/oauth-credential-storage.d.ts +0 -30
  387. package/dist/src/code_assist/oauth-credential-storage.js +0 -135
  388. package/dist/src/code_assist/oauth-credential-storage.js.map +0 -1
  389. package/dist/src/code_assist/server.d.ts +0 -44
  390. package/dist/src/code_assist/server.js +0 -154
  391. package/dist/src/code_assist/server.js.map +0 -1
  392. package/dist/src/code_assist/setup.d.ts +0 -20
  393. package/dist/src/code_assist/setup.js +0 -126
  394. package/dist/src/code_assist/setup.js.map +0 -1
  395. package/dist/src/code_assist/types.d.ts +0 -161
  396. package/dist/src/code_assist/types.js +0 -46
  397. package/dist/src/code_assist/types.js.map +0 -1
  398. package/dist/src/utils/getFolderStructure.d.ts +0 -31
  399. package/dist/src/utils/getFolderStructure.js +0 -240
  400. package/dist/src/utils/getFolderStructure.js.map +0 -1
  401. package/dist/src/utils/installationManager.d.ts +0 -16
  402. package/dist/src/utils/installationManager.js +0 -51
  403. package/dist/src/utils/installationManager.js.map +0 -1
  404. package/dist/src/utils/llm-edit-fixer.d.ts +0 -25
  405. package/dist/src/utils/llm-edit-fixer.js +0 -120
  406. package/dist/src/utils/llm-edit-fixer.js.map +0 -1
  407. package/src/code_assist/codeAssist.ts +0 -59
  408. package/src/code_assist/contentGeneratorAdapters.ts +0 -275
  409. package/src/code_assist/converter.ts +0 -288
  410. package/src/code_assist/googleGenAIWrapper.ts +0 -90
  411. package/src/code_assist/oauth-credential-storage.ts +0 -171
  412. package/src/code_assist/server.ts +0 -263
  413. package/src/code_assist/setup.ts +0 -189
  414. package/src/code_assist/types.ts +0 -201
  415. package/src/utils/getFolderStructure.ts +0 -382
  416. package/src/utils/installationManager.ts +0 -59
  417. package/src/utils/llm-edit-fixer.ts +0 -157
@@ -0,0 +1,1055 @@
1
+ /**
2
+ * Copyright 2026 Vybestack LLC
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ */
16
+
17
+ import { finalizeMutationEffects } from './historyMutationFailure.js';
18
+ import { CompressionOperationQueue } from './historyCompressionQueue.js';
19
+ import {
20
+ type ChronologyMarker,
21
+ type IContent,
22
+ type MediaReferenceBlock,
23
+ } from './IContent.js';
24
+ import { EventEmitter } from 'events';
25
+ // @plan:PLAN-20260603-ISSUE1584.P05 RuntimeTokenizerFactory used for injection path
26
+ import type { RuntimeTokenizerFactory } from '../../runtime/contracts/RuntimeTokenizerFactory.js';
27
+ import type { RuntimeTokenizer as ITokenizer } from '../../runtime/contracts/RuntimeTokenizer.js';
28
+ import { DebugLogger } from '../../debug/index.js';
29
+ import { randomUUID } from 'crypto';
30
+ import { canonicalizeToolCallId } from './canonicalToolIds.js';
31
+ import type { DensityResult } from '../../core/compression/types.js';
32
+ import {
33
+ estimateContentTokens as estimateContentTokensImpl,
34
+ estimateTokensForContents as estimateTokensForContentsImpl,
35
+ simpleTokenEstimateForText,
36
+ type TokenizerProvider,
37
+ } from './historyTokenEstimation.js';
38
+ import {
39
+ validateDensityResult,
40
+ applyDensityMutations,
41
+ } from './densityValidation.js';
42
+ import {
43
+ logContentAdded,
44
+ logQueuedDuringCompression,
45
+ } from './curationDebugLogger.js';
46
+ import {
47
+ type HistoryServiceEventEmitter,
48
+ type CompressionConfig,
49
+ } from './historyEventTypes.js';
50
+ import { getTokenizerForModel } from './historyTokenizerAdapter.js';
51
+ import {
52
+ ChronologyStamper,
53
+ type ChronologyState,
54
+ } from './historyChronology.js';
55
+
56
+ // Preserve the CompressionConfig export from the same path for consumers.
57
+ export type { CompressionConfig };
58
+
59
+ import {
60
+ type MutationFailure,
61
+ combineMutationFailures,
62
+ } from './historyMutationFailure.js';
63
+
64
+ export interface PreparedHistoryBatchEffect {
65
+ publish(): void | Promise<void>;
66
+ rollback(): void | Promise<void>;
67
+ finalize?(): void | Promise<void>;
68
+ }
69
+
70
+ export type HistoryBatchParticipant = (
71
+ publication: HistoryBatchPublication,
72
+ ) => PreparedHistoryBatchEffect | Promise<PreparedHistoryBatchEffect>;
73
+
74
+ export interface HistoryOwnedMediaReservation {
75
+ readonly contentId: string;
76
+ readonly ownerId: string;
77
+ readonly reference?: MediaReferenceBlock;
78
+ }
79
+
80
+ /**
81
+ * Explicit owner participant that reconciles durable local-media ownership with live
82
+ * history on every mutation that adds, replaces, removes, or clears history.
83
+ * Registered via {@link HistoryService.registerMediaOwner}.
84
+ */
85
+ export interface HistoryMediaOwner {
86
+ /** Transactional ownership transition for a queued history mutation. */
87
+ prepareReplacement(input: {
88
+ readonly previous: readonly IContent[];
89
+ readonly next: readonly IContent[];
90
+ readonly adopted: readonly HistoryOwnedMediaReservation[];
91
+ }): PreparedHistoryBatchEffect | Promise<PreparedHistoryBatchEffect>;
92
+
93
+ /** Reconcile ownership from `previous` to current history for synchronous
94
+ * mutations that cannot await (clears, pops, settlement). */
95
+ reconcile(
96
+ previous: readonly IContent[],
97
+ getNext: () => readonly IContent[],
98
+ ): Promise<void>;
99
+
100
+ /** Release every reservation the history still owns (disposal). */
101
+ releaseAll(): Promise<void>;
102
+
103
+ /** Adopt reservations for content that becomes resident without a removal diff. */
104
+ adopt(contents: readonly IContent[]): void;
105
+ }
106
+
107
+ export interface HistoryBatchPublication {
108
+ readonly contents: readonly IContent[];
109
+ readonly nextHistory: readonly IContent[];
110
+ readonly addedTokens: number;
111
+ readonly totalTokens: number;
112
+ }
113
+
114
+ export interface HistoryBatchOptions {
115
+ readonly afterPublication?: () => void | Promise<void>;
116
+ readonly adoptedOwners?: readonly HistoryOwnedMediaReservation[];
117
+ }
118
+
119
+ type QueuedHistoryMutation =
120
+ | { kind: 'synchronous'; execute: () => void }
121
+ | {
122
+ kind: 'asynchronous';
123
+ execute: () => Promise<void>;
124
+ resolve: () => void;
125
+ reject: (error: unknown) => void;
126
+ };
127
+
128
+ interface ChronologyRollbackEntry {
129
+ readonly content: IContent;
130
+ readonly hadMetadata: boolean;
131
+ readonly chronology: ChronologyMarker | undefined;
132
+ }
133
+
134
+ /**
135
+ * Service for managing conversation history in a provider-agnostic way.
136
+ * All history is stored as IContent. Providers are responsible for converting
137
+ * to/from their own formats.
138
+ */
139
+ export abstract class HistoryServiceCore
140
+ extends EventEmitter
141
+ implements HistoryServiceEventEmitter
142
+ {
143
+ abstract recalculateTotalTokens(
144
+ modelName?: string,
145
+ activeProvider?: string,
146
+ ): Promise<void>;
147
+
148
+ protected history: IContent[] = [];
149
+ protected totalTokens: number = 0;
150
+ protected baseTokenOffset: number = 0;
151
+ protected tokenizerCache = new Map<string, ITokenizer>();
152
+ protected tokenizerLock: Promise<void> = Promise.resolve();
153
+ protected pendingTokenizerFailure: { error: unknown } | undefined;
154
+ private syncGeneration: number = 0;
155
+ private historyMutationInProgress = false;
156
+ private historyMutationQueue: QueuedHistoryMutation[] = [];
157
+ private batchParticipants = new Set<HistoryBatchParticipant>();
158
+ protected mediaOwner: HistoryMediaOwner | undefined;
159
+ private ownershipSettlement: Promise<void> = Promise.resolve();
160
+ private ownershipFailure: unknown;
161
+ protected logger = new DebugLogger('llxprt:history:service');
162
+
163
+ protected chronology = new ChronologyStamper();
164
+
165
+ /**
166
+ * Monotonic cache anchor: the highest chronology `seq` that must remain in
167
+ * the preserved head across every subsequent middle-out compression. Once a
168
+ * head entry is preserved by one compression, no later compression may drop
169
+ * it, which keeps the provider-visible prefix byte-identical (#3070).
170
+ *
171
+ * Survives atomic compression replacement; reset explicitly by session-reset
172
+ * and history-restore paths.
173
+ */
174
+ protected cacheAnchorSeq: number = 0;
175
+
176
+ /**
177
+ * @plan:PLAN-20260603-ISSUE1584.P05
178
+ * @requirement:REQ-DEP-001
179
+ * @pseudocode component-boundaries.md C-CB-01, lines 10-15
180
+ *
181
+ * Injected tokenizer factory. When provided, HistoryService uses the factory
182
+ * to obtain tokenizers instead of constructing provider tokenizers directly.
183
+ * This eliminates the core→providers import dependency on the injection path.
184
+ */
185
+ private tokenizerFactory?: RuntimeTokenizerFactory;
186
+ protected activeTokenizationModel = 'gpt-4.1';
187
+ protected activeTokenizationProvider?: string;
188
+
189
+ protected isCompressing: boolean = false;
190
+ /**
191
+ * True while a rebuild scope is running, so operations queued during the
192
+ * rebuild are tagged 'rebuild' and replayed before streaming work (#3338,
193
+ * #3264). Held here rather than in the subclass because this class owns the
194
+ * queue the tag is applied to.
195
+ */
196
+ protected inRebuildScope = false;
197
+ protected pendingOperations = new CompressionOperationQueue((pendingCount) =>
198
+ this.logger.error(
199
+ 'History compression queue exceeded its high-water mark; the compression lock is being held for an unexpectedly long time. No operations are dropped.',
200
+ { pendingCount },
201
+ ),
202
+ );
203
+
204
+ /**
205
+ * @plan:PLAN-20260603-ISSUE1584.P05
206
+ * @requirement:REQ-DEP-001
207
+ * @pseudocode component-boundaries.md C-CB-01, lines 10-15
208
+ *
209
+ * Set the tokenizer factory for injection-based tokenizer resolution.
210
+ * When set, getTokenizerForModel will prefer the factory over
211
+ * constructing provider tokenizers directly.
212
+ */
213
+ setTokenizerFactory(factory: RuntimeTokenizerFactory): void {
214
+ this.tokenizerFactory = factory;
215
+ this.tokenizerCache.clear();
216
+ }
217
+
218
+ setActiveTokenizationTarget(
219
+ modelName: string,
220
+ activeProvider?: string,
221
+ ): void {
222
+ this.activeTokenizationModel = modelName;
223
+ this.activeTokenizationProvider = activeProvider;
224
+ }
225
+
226
+ /**
227
+ * Get or create tokenizer for a specific model.
228
+ *
229
+ * @plan:PLAN-20260603-ISSUE1584.P05
230
+ * @requirement:REQ-DEP-001
231
+ * @pseudocode component-boundaries.md C-CB-01, lines 10-15
232
+ *
233
+ * When a RuntimeTokenizerFactory is injected, it is preferred over
234
+ * direct provider tokenizer construction. This removes the core→providers
235
+ * dependency when using the injection path.
236
+ */
237
+ private getTokenizerForModel(
238
+ modelName: string,
239
+ activeProvider?: string,
240
+ ): ITokenizer {
241
+ return getTokenizerForModel(activeProvider, modelName, {
242
+ tokenizerCache: this.tokenizerCache,
243
+ tokenizerFactory: this.tokenizerFactory,
244
+ });
245
+ }
246
+
247
+ /**
248
+ * Generate a new canonical history tool ID.
249
+ * Format: hist_tool_<hash>
250
+ */
251
+ generateHistoryId(
252
+ turnKey: string,
253
+ callIndex: number,
254
+ providerName?: string,
255
+ rawId?: string,
256
+ toolName?: string,
257
+ ): string {
258
+ return canonicalizeToolCallId({
259
+ providerName,
260
+ rawId,
261
+ toolName,
262
+ turnKey,
263
+ callIndex,
264
+ });
265
+ }
266
+
267
+ /**
268
+ * Get a callback suitable for passing into converters
269
+ * which will generate normalized history IDs on demand.
270
+ */
271
+ getIdGeneratorCallback(turnKey?: string): () => string {
272
+ let callIndex = 0;
273
+ const stableTurnKey = turnKey ?? this.generateTurnKey();
274
+ return () => this.generateHistoryId(stableTurnKey, callIndex++);
275
+ }
276
+
277
+ generateTurnKey(): string {
278
+ return `turn_${randomUUID()}`;
279
+ }
280
+
281
+ /**
282
+ * Get the current total token count including base offset (system prompt).
283
+ *
284
+ * This value is used for compression threshold calculations and should always
285
+ * reflect the total context size that will be sent to the API.
286
+ *
287
+ * @returns baseTokenOffset + totalTokens (history tokens)
288
+ */
289
+ getTotalTokens(): number {
290
+ return this.baseTokenOffset + this.totalTokens;
291
+ }
292
+
293
+ getBaseTokenOffset(): number {
294
+ return this.baseTokenOffset;
295
+ }
296
+
297
+ async estimateTokensForText(
298
+ text: string,
299
+ modelName = this.activeTokenizationModel,
300
+ ): Promise<number> {
301
+ if (!text) {
302
+ return 0;
303
+ }
304
+
305
+ const tokenizer = this.getTokenizerForModel(
306
+ modelName,
307
+ this.activeTokenizationProvider,
308
+ );
309
+ try {
310
+ return await tokenizer.countTokens(text);
311
+ } catch (error) {
312
+ if (tokenizer.fallbackPolicy === 'deny') {
313
+ throw error;
314
+ }
315
+ this.logger.debug(
316
+ 'Error counting tokens for raw text, using fallback:',
317
+ error,
318
+ );
319
+ return simpleTokenEstimateForText(text);
320
+ }
321
+ }
322
+
323
+ /**
324
+ * Set a base offset that is always included in the total token count.
325
+ * Useful for accounting for system prompts or other fixed overhead.
326
+ *
327
+ * The system prompt token count should be set once at chat start using this method.
328
+ * This offset is included in getTotalTokens() to ensure compression threshold
329
+ * calculations account for the full context size (system prompt + history).
330
+ *
331
+ * NOTE: The system prompt itself is NEVER compressed - only conversation history
332
+ * returned by getCurated() is subject to compression.
333
+ *
334
+ * @param offset - Number of tokens in the system prompt or fixed overhead
335
+ */
336
+ setBaseTokenOffset(offset: number): void {
337
+ const normalized = Math.max(0, Math.floor(offset));
338
+ const delta = normalized - this.baseTokenOffset;
339
+ this.baseTokenOffset = normalized;
340
+
341
+ if (delta !== 0) {
342
+ this.emit('tokensUpdated', {
343
+ totalTokens: this.getTotalTokens(),
344
+ addedTokens: delta,
345
+ contentId: null,
346
+ });
347
+ }
348
+ }
349
+
350
+ /**
351
+ * Sync the total token count to match actual prompt tokens from a provider.
352
+ * This adjusts the baseTokenOffset so estimates align with the real count.
353
+ */
354
+ syncTotalTokens(actualTotal: number): void {
355
+ if (!Number.isFinite(actualTotal)) {
356
+ this.logger.debug('Skipping syncTotalTokens for non-finite value', {
357
+ actualTotal,
358
+ });
359
+ return;
360
+ }
361
+
362
+ const normalized = Math.max(0, Math.floor(actualTotal));
363
+ const generation = this.syncGeneration;
364
+ this.observeTokenizerOperation(
365
+ this.runSerializedTokenOperation(() => {
366
+ if (generation !== this.syncGeneration) return;
367
+
368
+ const currentTotal = this.getTotalTokens();
369
+ const drift = normalized - currentTotal;
370
+
371
+ if (drift === 0) {
372
+ return;
373
+ }
374
+
375
+ this.baseTokenOffset += drift;
376
+
377
+ this.emit('tokensUpdated', {
378
+ totalTokens: this.getTotalTokens(),
379
+ addedTokens: drift,
380
+ contentId: null,
381
+ });
382
+ }),
383
+ );
384
+ }
385
+
386
+ protected runSerializedTokenOperation<T>(
387
+ operation: () => T | Promise<T>,
388
+ ): Promise<T> {
389
+ const result = this.tokenizerLock.then(operation);
390
+ this.tokenizerLock = result.then(
391
+ () => undefined,
392
+ () => undefined,
393
+ );
394
+ return result;
395
+ }
396
+
397
+ protected observeTokenizerOperation(operation: Promise<void>): void {
398
+ void operation.catch((error: unknown) => {
399
+ this.pendingTokenizerFailure ??= { error };
400
+ this.logger.error('Asynchronous token accounting failed', error);
401
+ });
402
+ }
403
+
404
+ protected invalidatePendingSyncs(): void {
405
+ this.syncGeneration++;
406
+ }
407
+
408
+ protected runSynchronousHistoryMutation(execute: () => void): void {
409
+ if (this.historyMutationInProgress) {
410
+ this.historyMutationQueue.push({ kind: 'synchronous', execute });
411
+ return;
412
+ }
413
+
414
+ this.historyMutationInProgress = true;
415
+ let failure: MutationFailure = { failed: false };
416
+ try {
417
+ execute();
418
+ } catch (error: unknown) {
419
+ failure = { failed: true, error };
420
+ }
421
+ const queuedFailure = this.drainSynchronousHistoryMutations();
422
+ this.historyMutationInProgress = false;
423
+ this.processHistoryMutationQueue();
424
+
425
+ const combinedFailure = combineMutationFailures(failure, queuedFailure);
426
+ if (combinedFailure.failed) throw combinedFailure.error;
427
+ }
428
+
429
+ private drainSynchronousHistoryMutations(): MutationFailure {
430
+ let failure: MutationFailure = { failed: false };
431
+ while (this.historyMutationQueue[0]?.kind === 'synchronous') {
432
+ const mutation = this.historyMutationQueue.shift();
433
+ if (mutation?.kind !== 'synchronous') break;
434
+ try {
435
+ mutation.execute();
436
+ } catch (error: unknown) {
437
+ failure = combineMutationFailures(failure, { failed: true, error });
438
+ }
439
+ }
440
+ return failure;
441
+ }
442
+
443
+ protected enqueueAsynchronousHistoryMutation(
444
+ execute: () => Promise<void>,
445
+ ): Promise<void> {
446
+ return new Promise((resolve, reject) => {
447
+ this.historyMutationQueue.push({
448
+ kind: 'asynchronous',
449
+ execute,
450
+ resolve,
451
+ reject,
452
+ });
453
+ this.processHistoryMutationQueue();
454
+ });
455
+ }
456
+
457
+ private processHistoryMutationQueue(): void {
458
+ if (this.historyMutationInProgress) return;
459
+ const mutation = this.historyMutationQueue.shift();
460
+ if (mutation === undefined) return;
461
+ if (mutation.kind === 'synchronous') {
462
+ this.runSynchronousHistoryMutation(mutation.execute);
463
+ return;
464
+ }
465
+
466
+ this.historyMutationInProgress = true;
467
+ void mutation.execute().then(
468
+ () =>
469
+ this.completeAsynchronousHistoryMutation(mutation, { failed: false }),
470
+ (error: unknown) =>
471
+ this.completeAsynchronousHistoryMutation(mutation, {
472
+ failed: true,
473
+ error,
474
+ }),
475
+ );
476
+ }
477
+
478
+ private completeAsynchronousHistoryMutation(
479
+ mutation: Extract<QueuedHistoryMutation, { kind: 'asynchronous' }>,
480
+ failure: MutationFailure,
481
+ ): void {
482
+ const queuedFailure = this.drainSynchronousHistoryMutations();
483
+ this.historyMutationInProgress = false;
484
+ const result = combineMutationFailures(failure, queuedFailure);
485
+ if (result.failed) mutation.reject(result.error);
486
+ else mutation.resolve();
487
+ this.processHistoryMutationQueue();
488
+ }
489
+
490
+ resetTokenAccounting(): void {
491
+ this.invalidatePendingSyncs();
492
+ this.baseTokenOffset = 0;
493
+ this.emit('tokensUpdated', {
494
+ totalTokens: this.getTotalTokens(),
495
+ addedTokens: 0,
496
+ contentId: null,
497
+ });
498
+ }
499
+
500
+ /**
501
+ * Add content to the history.
502
+ * Zero-block turns are rejected at insertion (issue #2410): they corrupt
503
+ * provider-facing history (z.ai rejects empty human turns with HTTP 400
504
+ * error 1213). All other content with a valid speaker is accepted.
505
+ */
506
+ add(content: IContent, modelName?: string): void {
507
+ if (this.isCompressing) {
508
+ logQueuedDuringCompression(this.logger, content);
509
+ this.queueCompressionOperation(() => {
510
+ this.runSynchronousHistoryMutation(() => {
511
+ this.addInternal(content, modelName);
512
+ });
513
+ });
514
+ return;
515
+ }
516
+
517
+ this.runSynchronousHistoryMutation(() => {
518
+ this.addInternal(content, modelName);
519
+ });
520
+ }
521
+
522
+ /**
523
+ * Queues an operation that arrived while compression held the history lock.
524
+ *
525
+ * Operations are never dropped and never rejected: `add()` is on the
526
+ * streaming path, so failing here would lose conversation content and could
527
+ * break a turn. `startCompression`/`endCompression` are balanced in a
528
+ * `finally` by the only caller (`CompressionHandler.performCompression`), so
529
+ * the lock is always released and the queue is bounded by how long a single
530
+ * compression takes. Crossing the high-water mark is reported once so an
531
+ * unbalanced lock would be diagnosable rather than silent (issue #2852).
532
+ */
533
+ protected queueCompressionOperation(operation: () => void): void {
534
+ this.pendingOperations.enqueue(
535
+ operation,
536
+ this.inRebuildScope ? 'rebuild' : 'streaming',
537
+ );
538
+ }
539
+
540
+ /**
541
+ * Runs a rebuild synchronously so operations queued inside it are replayed
542
+ * before streaming work.
543
+ *
544
+ * The callback returns `undefined` rather than `void` on purpose. An async
545
+ * function returns `Promise<void>`, which is not assignable to `undefined`,
546
+ * so the synchronous contract fails at compile time; an `await` inside the
547
+ * scope would exit it and mis-tag the remaining work as streaming (#3338).
548
+ */
549
+ rebuildWith(callback: () => undefined): void {
550
+ const previousScope = this.inRebuildScope;
551
+ this.inRebuildScope = true;
552
+ try {
553
+ callback();
554
+ } finally {
555
+ this.inRebuildScope = previousScope;
556
+ }
557
+ }
558
+
559
+ private addInternal(content: IContent, modelName?: string): void {
560
+ // Reject zero-block turns: a Content with no blocks corrupts provider-
561
+ // facing history (notably z.ai rejects empty human turns with HTTP 400
562
+ // error 1213, issue #2410). This is a systemic safety net — earlier
563
+ // layers should prevent these from reaching history, but we enforce the
564
+ // invariant here as the last line of defense.
565
+ const hasValidSpeaker = ['human', 'ai', 'tool'].includes(content.speaker);
566
+ const hasBlocks =
567
+ Array.isArray(content.blocks) && content.blocks.length > 0;
568
+ const accepted = hasValidSpeaker && hasBlocks;
569
+
570
+ if (accepted) {
571
+ // Stamp chronology only once the content is known to be accepted, so a
572
+ // rejected turn never consumes a sequence number (#1721).
573
+ this.chronology.stamp(content);
574
+ }
575
+
576
+ logContentAdded(this.logger, content, modelName);
577
+
578
+ if (!accepted) {
579
+ this.logger.debug(
580
+ hasValidSpeaker
581
+ ? 'Content rejected - zero blocks (issue #2410):'
582
+ : 'Content rejected - invalid speaker:',
583
+ content.speaker,
584
+ );
585
+ return;
586
+ }
587
+
588
+ const generation = this.syncGeneration;
589
+ this.history.push(content);
590
+
591
+ try {
592
+ this.emit('contentAdded', content);
593
+ this.mediaOwner?.adopt([content]);
594
+ } catch (error: unknown) {
595
+ // Roll back the insertion. The consumed chronology sequence number is
596
+ // intentionally NOT reclaimed: sequence numbers are never reused, and
597
+ // the resulting gap truthfully records that an item was removed.
598
+ this.history.pop();
599
+ throw error;
600
+ }
601
+
602
+ // Update token count asynchronously but atomically
603
+ this.observeTokenizerOperation(
604
+ this.updateTokenCount(content, modelName, generation),
605
+ );
606
+ }
607
+
608
+ /**
609
+ * Atomically update token count for new content
610
+ */
611
+ protected updateTokenCount(
612
+ content: IContent,
613
+ modelName?: string,
614
+ generation = this.syncGeneration,
615
+ ): Promise<void> {
616
+ return this.runSerializedTokenOperation(async () => {
617
+ // Always derive token counts from the stored content to avoid double counting
618
+ // when providers attach aggregate usage metadata (which already includes prompt tokens).
619
+ const defaultModel = modelName ?? this.activeTokenizationModel;
620
+ const contentTokens = await this.estimateContentTokens(
621
+ content,
622
+ defaultModel,
623
+ );
624
+ if (generation !== this.syncGeneration) return;
625
+
626
+ // Atomically update the total
627
+ this.totalTokens += contentTokens;
628
+
629
+ // Emit event with updated count
630
+ const eventData = {
631
+ totalTokens: this.getTotalTokens(),
632
+ addedTokens: contentTokens,
633
+ contentId: content.metadata?.id,
634
+ };
635
+
636
+ this.logger.debug('Emitting tokensUpdated:', eventData);
637
+
638
+ this.emit('tokensUpdated', eventData);
639
+ });
640
+ }
641
+
642
+ /**
643
+ * Estimate token count for content using tokenizer
644
+ */
645
+ protected async estimateContentTokens(
646
+ content: IContent,
647
+ modelName: string,
648
+ ): Promise<number> {
649
+ return estimateContentTokensImpl(
650
+ content,
651
+ modelName,
652
+ this.tokenizerProvider(),
653
+ this.logger,
654
+ );
655
+ }
656
+
657
+ /** Provide the TokenizerProvider interface for the token estimation helpers. */
658
+ protected tokenizerProvider(
659
+ activeProvider = this.activeTokenizationProvider,
660
+ ): TokenizerProvider {
661
+ return {
662
+ getTokenizerForModel: (modelName: string) =>
663
+ this.getTokenizerForModel(modelName, activeProvider),
664
+ activeProvider,
665
+ };
666
+ }
667
+
668
+ /**
669
+ * Add multiple contents to the history.
670
+ *
671
+ * Iterates a snapshot because `add` appends to `this.history`: if `contents`
672
+ * aliases the backing array (`getRawHistory()`), a live iterator would keep
673
+ * consuming its own appends and never terminate. `replaceAll` is already
674
+ * immune the same way — its `filter` produces a fresh array before use.
675
+ */
676
+ addAll(contents: readonly IContent[], modelName?: string): void {
677
+ for (const content of [...contents]) {
678
+ this.add(content, modelName);
679
+ }
680
+ }
681
+
682
+ addBatch(
683
+ contents: readonly IContent[],
684
+ modelName?: string,
685
+ options: HistoryBatchOptions = {},
686
+ ): Promise<void> {
687
+ const batch = [...contents];
688
+ return this.enqueueAsynchronousHistoryMutation(async () => {
689
+ this.validateBatch(batch);
690
+ if (batch.length === 0) return;
691
+ await this.waitForTokenUpdates();
692
+ const addedTokens = await this.estimateTokensForContents(
693
+ batch,
694
+ modelName,
695
+ );
696
+ await this.commitHistoryMutation({
697
+ nextHistory: [...this.history, ...batch],
698
+ nextHistoryTokens: this.totalTokens + addedTokens,
699
+ publishedContents: batch,
700
+ options,
701
+ });
702
+ });
703
+ }
704
+
705
+ replaceBatch(
706
+ contents: readonly IContent[],
707
+ modelName?: string,
708
+ options: HistoryBatchOptions = {},
709
+ ): Promise<void> {
710
+ const replacement = [...contents];
711
+ return this.enqueueAsynchronousHistoryMutation(async () => {
712
+ this.validateBatch(replacement);
713
+ await this.waitForTokenUpdates();
714
+ const replacementTokens = await this.estimateTokensForContents(
715
+ replacement,
716
+ modelName,
717
+ );
718
+ await this.commitHistoryMutation({
719
+ nextHistory: replacement,
720
+ nextHistoryTokens: replacementTokens,
721
+ publishedContents: replacement,
722
+ options,
723
+ });
724
+ });
725
+ }
726
+
727
+ transformAll(
728
+ transform: (
729
+ contents: readonly IContent[],
730
+ ) => readonly IContent[] | Promise<readonly IContent[]>,
731
+ modelName?: string,
732
+ options: HistoryBatchOptions = {},
733
+ ): Promise<void> {
734
+ return this.enqueueAsynchronousHistoryMutation(async () => {
735
+ const replacement = [...(await transform([...this.history]))];
736
+ this.validateBatch(replacement);
737
+ await this.waitForTokenUpdates();
738
+ const replacementTokens = await this.estimateTokensForContents(
739
+ replacement,
740
+ modelName,
741
+ );
742
+ await this.commitHistoryMutation({
743
+ nextHistory: replacement,
744
+ nextHistoryTokens: replacementTokens,
745
+ options,
746
+ });
747
+ });
748
+ }
749
+
750
+ registerBatchParticipant(participant: HistoryBatchParticipant): () => void {
751
+ this.batchParticipants.add(participant);
752
+ return () => {
753
+ this.batchParticipants.delete(participant);
754
+ };
755
+ }
756
+
757
+ registerMediaOwner(owner: HistoryMediaOwner): void {
758
+ this.mediaOwner = owner;
759
+ owner.adopt(this.history);
760
+ }
761
+
762
+ settleMediaOwnership(): Promise<void> {
763
+ return this.enqueueAsynchronousHistoryMutation(async () => {
764
+ await this.mediaOwner?.reconcile([...this.history], () => this.history);
765
+ });
766
+ }
767
+
768
+ async waitForOwnershipSettlement(): Promise<void> {
769
+ let settlement: Promise<void>;
770
+ do {
771
+ settlement = this.ownershipSettlement;
772
+ await settlement;
773
+ } while (settlement !== this.ownershipSettlement);
774
+ const failure = this.ownershipFailure;
775
+ this.ownershipFailure = undefined;
776
+ if (failure !== undefined) throw failure;
777
+ }
778
+
779
+ private observeOwnershipOperation(operation: Promise<void>): void {
780
+ const observed = operation.then(
781
+ () => undefined,
782
+ (error: unknown) => {
783
+ this.ownershipFailure =
784
+ this.ownershipFailure === undefined
785
+ ? error
786
+ : new AggregateError(
787
+ [this.ownershipFailure, error],
788
+ 'Multiple history media ownership operations failed',
789
+ );
790
+ },
791
+ );
792
+ this.ownershipSettlement = this.ownershipSettlement.then(() => observed);
793
+ }
794
+
795
+ protected enqueueSynchronousOwnershipReconcile(
796
+ previous: readonly IContent[],
797
+ getNext: () => readonly IContent[],
798
+ ): void {
799
+ const owner = this.mediaOwner;
800
+ if (owner === undefined) return;
801
+ this.observeOwnershipOperation(
802
+ this.enqueueAsynchronousHistoryMutation(() =>
803
+ owner.reconcile(previous, getNext),
804
+ ),
805
+ );
806
+ }
807
+
808
+ protected enqueueSynchronousOwnershipReleaseAll(): void {
809
+ const owner = this.mediaOwner;
810
+ if (owner === undefined) return;
811
+ this.observeOwnershipOperation(
812
+ this.enqueueAsynchronousHistoryMutation(() => owner.releaseAll()),
813
+ );
814
+ }
815
+
816
+ replaceAll(
817
+ contents: readonly IContent[],
818
+ modelName?: string,
819
+ options: HistoryBatchOptions = {},
820
+ ): Promise<void> {
821
+ const accepted = [...contents].filter(
822
+ (content) =>
823
+ ['human', 'ai', 'tool'].includes(content.speaker) &&
824
+ Array.isArray(content.blocks) &&
825
+ content.blocks.length > 0,
826
+ );
827
+ return this.enqueueAsynchronousHistoryMutation(async () => {
828
+ await this.waitForTokenUpdates();
829
+ const replacementTokens = await this.estimateTokensForContents(
830
+ accepted,
831
+ modelName,
832
+ );
833
+ await this.commitHistoryMutation({
834
+ nextHistory: accepted,
835
+ nextHistoryTokens: replacementTokens,
836
+ options,
837
+ });
838
+ });
839
+ }
840
+
841
+ private validateBatch(contents: readonly IContent[]): void {
842
+ for (const [index, content] of contents.entries()) {
843
+ const validSpeaker = ['human', 'ai', 'tool'].includes(content.speaker);
844
+ const validBlocks =
845
+ Array.isArray(content.blocks) && content.blocks.length > 0;
846
+ if (!validSpeaker || !validBlocks) {
847
+ throw new Error(
848
+ `History batch entry ${index} is invalid: ${validSpeaker ? 'content has no blocks' : 'speaker is invalid'}`,
849
+ );
850
+ }
851
+ }
852
+ }
853
+
854
+ private stampHistory(contents: readonly IContent[]): {
855
+ readonly state: ChronologyState;
856
+ readonly entries: readonly ChronologyRollbackEntry[];
857
+ } {
858
+ const state = this.chronology.snapshot();
859
+ const entries = contents.map((content) => ({
860
+ content,
861
+ hadMetadata: content.metadata !== undefined,
862
+ chronology: content.metadata?.chronology,
863
+ }));
864
+ for (const content of contents) {
865
+ this.chronology.stamp(content);
866
+ }
867
+ return { state, entries };
868
+ }
869
+
870
+ private restoreChronology(input: {
871
+ readonly state: ChronologyState;
872
+ readonly entries: readonly ChronologyRollbackEntry[];
873
+ }): void {
874
+ this.chronology.restore(input.state);
875
+ for (const entry of input.entries) {
876
+ if (!entry.hadMetadata) {
877
+ delete entry.content.metadata;
878
+ } else if (entry.chronology === undefined) {
879
+ if (entry.content.metadata?.chronology !== undefined) {
880
+ delete entry.content.metadata.chronology;
881
+ }
882
+ } else if (
883
+ entry.content.metadata !== undefined &&
884
+ entry.content.metadata.chronology !== entry.chronology
885
+ ) {
886
+ entry.content.metadata.chronology = entry.chronology;
887
+ }
888
+ }
889
+ }
890
+
891
+ private async prepareMutationEffects(
892
+ effects: PreparedHistoryBatchEffect[],
893
+ publication: HistoryBatchPublication | undefined,
894
+ previousHistory: readonly IContent[],
895
+ nextHistory: readonly IContent[],
896
+ adopted: readonly HistoryOwnedMediaReservation[],
897
+ ): Promise<void> {
898
+ if (this.mediaOwner !== undefined) {
899
+ effects.push(
900
+ await this.mediaOwner.prepareReplacement({
901
+ previous: previousHistory,
902
+ next: nextHistory,
903
+ adopted,
904
+ }),
905
+ );
906
+ }
907
+ if (publication !== undefined) {
908
+ for (const participant of this.batchParticipants) {
909
+ effects.push(await participant(publication));
910
+ }
911
+ }
912
+ }
913
+
914
+ private async rollbackMutationEffects(
915
+ effects: readonly PreparedHistoryBatchEffect[],
916
+ ): Promise<unknown[]> {
917
+ const failures: unknown[] = [];
918
+ for (const effect of [...effects].reverse()) {
919
+ try {
920
+ await effect.rollback();
921
+ } catch (error: unknown) {
922
+ failures.push(error);
923
+ }
924
+ }
925
+ return failures;
926
+ }
927
+
928
+ private async commitHistoryMutation(input: {
929
+ readonly nextHistory: readonly IContent[];
930
+ readonly nextHistoryTokens: number;
931
+ readonly publishedContents?: readonly IContent[];
932
+ readonly options: HistoryBatchOptions;
933
+ }): Promise<void> {
934
+ const previousHistory = this.history;
935
+ const previousTokens = this.totalTokens;
936
+ const chronology = this.stampHistory(input.nextHistory);
937
+ const nextHistory = [...input.nextHistory];
938
+ const addedTokens = input.nextHistoryTokens - previousTokens;
939
+ const publication: HistoryBatchPublication | undefined =
940
+ input.publishedContents === undefined
941
+ ? undefined
942
+ : {
943
+ contents: input.publishedContents,
944
+ nextHistory,
945
+ addedTokens,
946
+ totalTokens: this.baseTokenOffset + input.nextHistoryTokens,
947
+ };
948
+ const effects: PreparedHistoryBatchEffect[] = [];
949
+ let historyPublished = false;
950
+ try {
951
+ await this.prepareMutationEffects(
952
+ effects,
953
+ publication,
954
+ previousHistory,
955
+ nextHistory,
956
+ input.options.adoptedOwners ?? [],
957
+ );
958
+ for (const effect of effects) {
959
+ await effect.publish();
960
+ }
961
+
962
+ this.invalidatePendingSyncs();
963
+ this.history = nextHistory;
964
+ this.totalTokens = input.nextHistoryTokens;
965
+ historyPublished = true;
966
+ if (input.publishedContents !== undefined) {
967
+ this.emit('contentBatchAdded', input.publishedContents);
968
+ }
969
+ this.emit('tokensUpdated', {
970
+ totalTokens: this.getTotalTokens(),
971
+ addedTokens,
972
+ contentId: null,
973
+ });
974
+ await input.options.afterPublication?.();
975
+ await finalizeMutationEffects(effects);
976
+ } catch (error: unknown) {
977
+ if (historyPublished) {
978
+ this.invalidatePendingSyncs();
979
+ this.history = previousHistory;
980
+ this.totalTokens = previousTokens;
981
+ }
982
+ this.restoreChronology(chronology);
983
+ const rollbackFailures = await this.rollbackMutationEffects(effects);
984
+ if (rollbackFailures.length === 0) throw error;
985
+ throw new AggregateError(
986
+ [error, ...rollbackFailures],
987
+ 'History mutation and rollback failed',
988
+ );
989
+ }
990
+ }
991
+
992
+ /**
993
+ * Estimate total tokens for hypothetical contents without mutating history.
994
+ */
995
+ async estimateTokensForContents(
996
+ contents: readonly IContent[],
997
+ modelName?: string,
998
+ ): Promise<number> {
999
+ return estimateTokensForContentsImpl(
1000
+ [...contents],
1001
+ modelName,
1002
+ this.tokenizerProvider(),
1003
+ this.logger,
1004
+ );
1005
+ }
1006
+
1007
+ /**
1008
+ * Wait for any in-flight token updates to complete.
1009
+ */
1010
+ async waitForTokenUpdates(): Promise<void> {
1011
+ await this.tokenizerLock;
1012
+ const failure = this.pendingTokenizerFailure;
1013
+ this.pendingTokenizerFailure = undefined;
1014
+ if (failure !== undefined) throw failure.error;
1015
+ }
1016
+
1017
+ /**
1018
+ * Apply a density optimization result to the raw history.
1019
+ *
1020
+ * @plan PLAN-20260211-HIGHDENSITY.P08
1021
+ * @requirement REQ-HD-003.1, REQ-HD-003.2, REQ-HD-003.3, REQ-HD-001.6, REQ-HD-001.7
1022
+ * @pseudocode history-service.md lines 20-82
1023
+ */
1024
+ async applyDensityResult(result: DensityResult): Promise<void> {
1025
+ await this.enqueueAsynchronousHistoryMutation(async () => {
1026
+ validateDensityResult(result, this.history.length);
1027
+ const nextHistory = [...this.history];
1028
+ // Each density replacement takes over the chronology position of the item
1029
+ // it replaces, so the surviving history keeps an unbroken sequence.
1030
+ // densityValidation stays free of chronology knowledge.
1031
+ for (const [index, replacement] of result.replacements) {
1032
+ const replacedMarker = this.history[index].metadata?.chronology;
1033
+ if (replacedMarker !== undefined) {
1034
+ this.chronology.inherit(replacement, replacedMarker);
1035
+ }
1036
+ }
1037
+ applyDensityMutations(nextHistory, result);
1038
+ await this.waitForTokenUpdates();
1039
+ const replacementTokens =
1040
+ await this.estimateTokensForContents(nextHistory);
1041
+ await this.commitHistoryMutation({
1042
+ nextHistory,
1043
+ nextHistoryTokens: replacementTokens,
1044
+ options: {},
1045
+ });
1046
+
1047
+ this.logger.debug('Density: applied result', {
1048
+ replacements: result.replacements.size,
1049
+ removals: result.removals.length,
1050
+ newHistoryLength: this.history.length,
1051
+ metadata: result.metadata,
1052
+ });
1053
+ });
1054
+ }
1055
+ }