akanjs 3.0.0-alpha.7 → 3.0.0-alpha.71

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 (719) hide show
  1. package/CHANGELOG.md +103 -0
  2. package/README.ko.md +1 -1
  3. package/README.md +1 -1
  4. package/base/baseEnv.ts +7 -4
  5. package/base/primitiveRegistry.ts +59 -12
  6. package/base/symbols.ts +4 -0
  7. package/client/capacitor.ts +34 -0
  8. package/client/clientRuntime.ts +5 -0
  9. package/client/csrTypes.ts +4 -3
  10. package/client/index.ts +1 -0
  11. package/client/locale.ts +2 -2
  12. package/client/router.ts +7 -7
  13. package/client/sharedContext.ts +31 -0
  14. package/client/translator.ts +2 -2
  15. package/client/types.ts +3 -3
  16. package/common/Logger.ts +280 -67
  17. package/common/clientAddress.ts +40 -0
  18. package/common/deepObjectify.ts +24 -9
  19. package/common/index.ts +42 -1
  20. package/common/logContext.ts +27 -0
  21. package/common/mcpExposure.ts +114 -0
  22. package/common/pathGetLoose.ts +31 -0
  23. package/common/pathSet.ts +17 -5
  24. package/common/plainFieldsOf.ts +13 -0
  25. package/common/routeConvention.ts +22 -12
  26. package/common/websocketBinaryFrame.ts +46 -0
  27. package/constant/crystalize.ts +94 -28
  28. package/constant/dateSlot.ts +62 -0
  29. package/constant/deserialize.ts +3 -2
  30. package/constant/fieldInfo.ts +43 -3
  31. package/constant/fieldQueryMeta.ts +35 -0
  32. package/constant/getDefault.ts +16 -11
  33. package/constant/hydrationPlan.ts +72 -0
  34. package/constant/immerify.ts +4 -6
  35. package/constant/index.ts +5 -0
  36. package/constant/labelOf.ts +26 -0
  37. package/constant/mask.ts +67 -0
  38. package/constant/purify.ts +17 -11
  39. package/constant/textFieldPaths.ts +13 -7
  40. package/constant/types.ts +19 -13
  41. package/constant/via.ts +24 -17
  42. package/dictionary/DictionaryLookup.ts +30 -0
  43. package/dictionary/agent.dictionary.ts +31 -0
  44. package/dictionary/agentTurn.dictionary.ts +29 -0
  45. package/dictionary/base.dictionary.ts +81 -0
  46. package/dictionary/dictInfo.ts +11 -2
  47. package/dictionary/dictionary.ts +9 -3
  48. package/dictionary/index.ts +1 -0
  49. package/dictionary/trans.ts +2 -2
  50. package/document/documentQuery.ts +1 -0
  51. package/document/filterMeta.ts +77 -12
  52. package/document/index.ts +1 -0
  53. package/document/noDocumentError.ts +12 -0
  54. package/document/types.ts +0 -1
  55. package/fetch/agentTurn.ts +19 -0
  56. package/fetch/client/fetchClient.ts +137 -37
  57. package/fetch/client/httpClient.ts +95 -20
  58. package/fetch/client/wsClient.ts +27 -12
  59. package/fetch/fetchType/appliedReturn.type.ts +65 -44
  60. package/fetch/fetchType/endpointFetch.type.ts +17 -8
  61. package/fetch/fetchType/sliceFetch.type.ts +27 -50
  62. package/fetch/index.ts +1 -0
  63. package/index.ts +80 -6
  64. package/local/apps/akan/akan-local.db +0 -0
  65. package/local/apps/akan/akan-local.db-shm +0 -0
  66. package/local/apps/akan/akan-local.db-wal +0 -0
  67. package/local/apps/akan/akan-local_solid.db +0 -0
  68. package/local/apps/akan/akan-local_solid.db-shm +0 -0
  69. package/local/apps/akan/akan-local_solid.db-wal +0 -0
  70. package/local/apps/serverLifecycle/serverLifecycle-local.db +0 -0
  71. package/local/apps/serverLifecycle/serverLifecycle-local.db-shm +0 -0
  72. package/local/apps/serverLifecycle/serverLifecycle-local.db-wal +0 -0
  73. package/local/apps/serverLifecycle/serverLifecycle-local_solid.db +0 -0
  74. package/local/apps/serverLifecycle/serverLifecycle-local_solid.db-shm +0 -0
  75. package/local/apps/serverLifecycle/serverLifecycle-local_solid.db-wal +0 -0
  76. package/package.json +27 -18
  77. package/server/akanApp.ts +278 -138
  78. package/server/akanAppHeaders.ts +16 -2
  79. package/server/akanOption.ts +63 -8
  80. package/server/akanServer.ts +387 -32
  81. package/server/animatedImage.ts +83 -0
  82. package/server/assetEncoding.ts +4 -24
  83. package/server/binaryPubsub.ts +55 -0
  84. package/server/console.ts +110 -101
  85. package/server/consoleEvaluator.ts +51 -0
  86. package/server/consolePasteFilter.ts +91 -0
  87. package/server/consoleSession.ts +242 -0
  88. package/server/contentEncoding.ts +83 -0
  89. package/server/devtools/signalSerializer.ts +2 -2
  90. package/server/devtools/types.ts +4 -4
  91. package/server/di/diLifecycle.ts +123 -13
  92. package/server/di/predefinedAdaptor.ts +6 -0
  93. package/server/di/utils.ts +40 -0
  94. package/server/imageOptimizer.ts +154 -57
  95. package/server/lifecycle/runtimeDir.ts +14 -0
  96. package/server/lifecycle/shutdownManager.ts +1 -1
  97. package/server/logging/childOutputReader.ts +137 -0
  98. package/server/logging/hubFileSink.ts +39 -0
  99. package/server/logging/logControlSocket.ts +173 -0
  100. package/server/logging/logForwarder.ts +131 -0
  101. package/server/logging/logHub.ts +0 -0
  102. package/server/logging/logQuery.ts +130 -0
  103. package/server/logging/logStdoutWriter.ts +39 -0
  104. package/server/logging/logStreamRoute.ts +87 -0
  105. package/server/logging/logTailClient.ts +161 -0
  106. package/server/mcp/McpAuth.ts +177 -0
  107. package/server/mcp/McpDispatcher.ts +289 -0
  108. package/server/mcp/McpEventStream.ts +24 -0
  109. package/server/mcp/McpExecutionContext.ts +105 -0
  110. package/server/mcp/McpRouter.ts +621 -0
  111. package/server/mcp/index.ts +5 -0
  112. package/server/processMetricsCollector.ts +1 -1
  113. package/server/resolver/database.resolver.ts +5 -4
  114. package/server/resolver/signal.resolver.ts +208 -86
  115. package/server/routeTreeBuilder.ts +10 -8
  116. package/server/routing/apiRouter.ts +44 -14
  117. package/server/routing/appWsData.ts +24 -2
  118. package/server/routing/eventStream.ts +93 -0
  119. package/server/routing/soloAppRoutes.ts +50 -0
  120. package/server/rscWorker.tsx +36 -22
  121. package/server/rscWorkerHost.ts +59 -8
  122. package/server/semaphore.ts +22 -0
  123. package/server/subRouteIndexDocument.tsx +61 -0
  124. package/server/systemPageDocument.tsx +3 -3
  125. package/server/systemPages.tsx +49 -16
  126. package/server/types.tsx +28 -0
  127. package/server/vendor/akanjs-fetch.ts +1 -0
  128. package/server/webRouter.ts +96 -39
  129. package/service/adapt.ts +4 -4
  130. package/service/agent.service.ts +81 -0
  131. package/service/base.service.ts +2 -1
  132. package/service/index.ts +1 -0
  133. package/service/injectInfo.ts +8 -3
  134. package/service/ipcTypes.ts +6 -0
  135. package/service/predefinedAdaptor/compress.adaptor.ts +5 -1
  136. package/service/predefinedAdaptor/database.adaptor.ts +68 -37
  137. package/service/predefinedAdaptor/deepseekLlm.ts +271 -0
  138. package/service/predefinedAdaptor/index.ts +3 -0
  139. package/service/predefinedAdaptor/insightQuery.ts +183 -0
  140. package/service/predefinedAdaptor/llm.adaptor.ts +115 -0
  141. package/service/predefinedAdaptor/logging.adaptor.ts +1 -1
  142. package/service/predefinedAdaptor/queue.adaptor.ts +5 -2
  143. package/service/predefinedAdaptor/role.adaptor.ts +2 -0
  144. package/service/predefinedAdaptor/schedule.adaptor.ts +12 -5
  145. package/service/predefinedAdaptor/solidPubsub.adaptor.ts +10 -6
  146. package/service/predefinedAdaptor/solidQueue.adaptor.ts +6 -2
  147. package/service/predefinedAdaptor/solidSqlite.ts +11 -9
  148. package/service/predefinedAdaptor/websocket.adaptor.ts +6 -1
  149. package/service/serve.ts +16 -9
  150. package/service/toolNames.ts +119 -0
  151. package/signal/agent/AgentCatalogue.ts +165 -0
  152. package/signal/agent/index.ts +1 -0
  153. package/signal/agent.signal.ts +38 -0
  154. package/signal/agentTurn.ts +8 -0
  155. package/signal/agentTurnStream.ts +60 -0
  156. package/signal/base.signal.ts +2 -1
  157. package/signal/endpointInfo.ts +38 -2
  158. package/signal/guard.ts +28 -1
  159. package/signal/guards.ts +49 -1
  160. package/signal/index.ts +6 -0
  161. package/signal/intercept.ts +4 -4
  162. package/signal/internalArg.ts +21 -4
  163. package/signal/mcp/McpDocument.ts +326 -0
  164. package/signal/mcp/McpProgress.ts +106 -0
  165. package/signal/mcp/McpUriTemplate.ts +80 -0
  166. package/signal/mcp/Msg.ts +368 -0
  167. package/signal/mcp/index.ts +5 -0
  168. package/signal/mcp/mcpProtocol.ts +120 -0
  169. package/signal/middleware.ts +3 -3
  170. package/signal/openapi/openapi.ts +36 -173
  171. package/signal/schema/JsonSchemaBuilder.ts +221 -0
  172. package/signal/schema/index.ts +1 -0
  173. package/signal/serializer/fetch.serializer.ts +51 -0
  174. package/signal/signalContext.ts +324 -76
  175. package/signal/slice.ts +62 -27
  176. package/signal/trace.ts +268 -9
  177. package/signal/types.ts +55 -4
  178. package/store/action.ts +34 -41
  179. package/store/actionTag.ts +33 -0
  180. package/store/agent/AgentBridge.ts +87 -0
  181. package/store/agent/AgentContext.ts +71 -0
  182. package/store/agent/AgentPrompts.ts +111 -0
  183. package/store/agent/ScreenReader.ts +349 -0
  184. package/store/agent/ScreenSettle.ts +45 -0
  185. package/store/agent/ScreenTarget.ts +135 -0
  186. package/store/agent/StoreCatalogue.ts +116 -0
  187. package/store/agent/StoreSurfaceSource.ts +225 -0
  188. package/store/agent/index.ts +13 -0
  189. package/store/agent/storeSurface.ts +28 -0
  190. package/store/agent/types.ts +16 -0
  191. package/store/agentic/AgentValue.ts +119 -0
  192. package/store/agentic/StExposeBuilder.ts +47 -0
  193. package/store/agentic/StExposeDraft.ts +24 -0
  194. package/store/agentic/StStateBuilder.ts +85 -0
  195. package/store/agentic/StStateDraft.ts +23 -0
  196. package/store/agentic/StToolBuilder.ts +279 -0
  197. package/store/agentic/StToolDraft.ts +22 -0
  198. package/store/agentic/attachAgentic.ts +33 -0
  199. package/store/agentic/formFields.ts +194 -0
  200. package/store/agentic/index.ts +12 -0
  201. package/store/agentic/useFieldTool.ts +183 -0
  202. package/store/agentic/useFormTools.ts +77 -0
  203. package/store/agentic/useRelationFieldTool.ts +113 -0
  204. package/store/baseSt.ts +1 -1
  205. package/store/databaseStateNames.ts +31 -0
  206. package/store/formSetterNames.ts +35 -0
  207. package/store/index.ts +8 -0
  208. package/store/rootStore.ts +3 -1
  209. package/store/sliceRole.ts +36 -0
  210. package/store/state.ts +2 -12
  211. package/store/store.ts +9 -0
  212. package/store/storeInstance.ts +185 -20
  213. package/store/storeRegistry.ts +39 -1
  214. package/store/types.ts +5 -0
  215. package/store/withSelector.ts +5 -4
  216. package/test/index.ts +1 -1
  217. package/test/registerDom.ts +4 -0
  218. package/test/sampleOf.ts +2 -0
  219. package/test/signalTestRuntime.ts +5 -5
  220. package/test/testServer.ts +14 -11
  221. package/types/base/baseEnv.d.ts +1 -1
  222. package/types/base/primitiveRegistry.d.ts +20 -8
  223. package/types/base/symbols.d.ts +4 -0
  224. package/types/client/capacitor.d.ts +39 -0
  225. package/types/client/clientRuntime.d.ts +7 -0
  226. package/types/client/index.d.ts +1 -0
  227. package/types/client/sharedContext.d.ts +21 -0
  228. package/types/client/types.d.ts +5 -3
  229. package/types/common/Logger.d.ts +88 -6
  230. package/types/common/clientAddress.d.ts +19 -0
  231. package/types/common/deepObjectify.d.ts +4 -2
  232. package/types/common/index.d.ts +8 -2
  233. package/types/common/logContext.d.ts +17 -0
  234. package/types/common/mcpExposure.d.ts +64 -0
  235. package/types/common/pathGetLoose.d.ts +8 -0
  236. package/types/common/plainFieldsOf.d.ts +6 -0
  237. package/types/common/routeConvention.d.ts +6 -0
  238. package/types/common/websocketBinaryFrame.d.ts +17 -0
  239. package/types/constant/constantRegistry.d.ts +2 -10
  240. package/types/constant/crystalize.d.ts +5 -0
  241. package/types/constant/dateSlot.d.ts +14 -0
  242. package/types/constant/fieldInfo.d.ts +20 -3
  243. package/types/constant/fieldQueryMeta.d.ts +17 -0
  244. package/types/constant/getDefault.d.ts +8 -0
  245. package/types/constant/hydrationPlan.d.ts +24 -0
  246. package/types/constant/index.d.ts +5 -0
  247. package/types/constant/labelOf.d.ts +7 -0
  248. package/types/constant/mask.d.ts +41 -0
  249. package/types/constant/purify.d.ts +2 -2
  250. package/types/constant/types.d.ts +5 -5
  251. package/types/dictionary/DictionaryLookup.d.ts +14 -0
  252. package/types/dictionary/agent.dictionary.d.ts +1 -0
  253. package/types/dictionary/agentTurn.dictionary.d.ts +1 -0
  254. package/types/dictionary/base.dictionary.d.ts +1 -1
  255. package/types/dictionary/dictInfo.d.ts +7 -1
  256. package/types/dictionary/dictionary.d.ts +11 -9
  257. package/types/dictionary/index.d.ts +1 -0
  258. package/types/document/filterMeta.d.ts +24 -4
  259. package/types/document/index.d.ts +1 -0
  260. package/types/document/noDocumentError.d.ts +12 -0
  261. package/types/document/types.d.ts +0 -1
  262. package/types/fetch/agentTurn.d.ts +475 -0
  263. package/types/fetch/client/fetchClient.d.ts +12 -0
  264. package/types/fetch/client/httpClient.d.ts +2 -1
  265. package/types/fetch/fetchType/appliedReturn.type.d.ts +37 -18
  266. package/types/fetch/fetchType/endpointFetch.type.d.ts +8 -5
  267. package/types/fetch/fetchType/sliceFetch.type.d.ts +11 -15
  268. package/types/fetch/index.d.ts +1 -0
  269. package/types/index.d.ts +74 -10
  270. package/types/server/akanApp.d.ts +12 -0
  271. package/types/server/akanAppHeaders.d.ts +7 -1
  272. package/types/server/akanOption.d.ts +36 -6
  273. package/types/server/akanServer.d.ts +67 -9
  274. package/types/server/animatedImage.d.ts +7 -0
  275. package/types/server/assetEncoding.d.ts +1 -1
  276. package/types/server/binaryPubsub.d.ts +18 -0
  277. package/types/server/console.d.ts +11 -1
  278. package/types/server/consoleEvaluator.d.ts +2 -0
  279. package/types/server/consolePasteFilter.d.ts +11 -0
  280. package/types/server/consoleSession.d.ts +22 -0
  281. package/types/server/contentEncoding.d.ts +28 -0
  282. package/types/server/devtools/types.d.ts +4 -4
  283. package/types/server/di/diLifecycle.d.ts +10 -2
  284. package/types/server/di/predefinedAdaptor.d.ts +4 -1
  285. package/types/server/di/utils.d.ts +16 -0
  286. package/types/server/lifecycle/runtimeDir.d.ts +5 -0
  287. package/types/server/logging/childOutputReader.d.ts +40 -0
  288. package/types/server/logging/hubFileSink.d.ts +18 -0
  289. package/types/server/logging/logControlSocket.d.ts +60 -0
  290. package/types/server/logging/logForwarder.d.ts +37 -0
  291. package/types/server/logging/logHub.d.ts +70 -0
  292. package/types/server/logging/logQuery.d.ts +31 -0
  293. package/types/server/logging/logStdoutWriter.d.ts +35 -0
  294. package/types/server/logging/logStreamRoute.d.ts +20 -0
  295. package/types/server/logging/logTailClient.d.ts +42 -0
  296. package/types/server/mcp/McpAuth.d.ts +62 -0
  297. package/types/server/mcp/McpDispatcher.d.ts +61 -0
  298. package/types/server/mcp/McpEventStream.d.ts +17 -0
  299. package/types/server/mcp/McpExecutionContext.d.ts +44 -0
  300. package/types/server/mcp/McpRouter.d.ts +65 -0
  301. package/types/server/mcp/index.d.ts +5 -0
  302. package/types/server/mcp.d.ts +1 -0
  303. package/types/server/resolver/signal.resolver.d.ts +7 -4
  304. package/types/server/routing/apiRouter.d.ts +2 -1
  305. package/types/server/routing/appWsData.d.ts +13 -1
  306. package/types/server/routing/eventStream.d.ts +23 -0
  307. package/types/server/routing/soloAppRoutes.d.ts +17 -0
  308. package/types/server/rscWorkerHost.d.ts +4 -1
  309. package/types/server/semaphore.d.ts +5 -0
  310. package/types/server/subRouteIndexDocument.d.ts +8 -0
  311. package/types/server/systemPageDocument.d.ts +1 -0
  312. package/types/server/systemPages.d.ts +5 -0
  313. package/types/server/types.d.ts +16 -0
  314. package/types/server/vendor/akanjs-fetch.d.ts +1 -0
  315. package/types/server/webRouter.d.ts +15 -4
  316. package/types/service/adapt.d.ts +2 -2
  317. package/types/service/agent.service.d.ts +32 -0
  318. package/types/service/base.service.d.ts +4 -0
  319. package/types/service/index.d.ts +1 -0
  320. package/types/service/injectInfo.d.ts +2 -2
  321. package/types/service/ipcTypes.d.ts +12 -0
  322. package/types/service/predefinedAdaptor/compress.adaptor.d.ts +1 -1
  323. package/types/service/predefinedAdaptor/database.adaptor.d.ts +9 -3
  324. package/types/service/predefinedAdaptor/deepseekLlm.d.ts +76 -0
  325. package/types/service/predefinedAdaptor/index.d.ts +3 -0
  326. package/types/service/predefinedAdaptor/insightQuery.d.ts +50 -0
  327. package/types/service/predefinedAdaptor/llm.adaptor.d.ts +105 -0
  328. package/types/service/predefinedAdaptor/queue.adaptor.d.ts +3 -2
  329. package/types/service/predefinedAdaptor/role.adaptor.d.ts +2 -0
  330. package/types/service/predefinedAdaptor/schedule.adaptor.d.ts +10 -6
  331. package/types/service/predefinedAdaptor/solidQueue.adaptor.d.ts +6 -2
  332. package/types/service/predefinedAdaptor/solidSqlite.d.ts +2 -2
  333. package/types/service/serve.d.ts +3 -3
  334. package/types/service/toolNames.d.ts +35 -0
  335. package/types/signal/agent/AgentCatalogue.d.ts +100 -0
  336. package/types/signal/agent/index.d.ts +1 -0
  337. package/types/signal/agent.d.ts +1 -0
  338. package/types/signal/agent.signal.d.ts +24 -0
  339. package/types/signal/agentTurn.d.ts +9 -0
  340. package/types/signal/agentTurnStream.d.ts +24 -0
  341. package/types/signal/base.signal.d.ts +1 -1
  342. package/types/signal/endpointInfo.d.ts +21 -3
  343. package/types/signal/guard.d.ts +12 -0
  344. package/types/signal/guards.d.ts +23 -1
  345. package/types/signal/index.d.ts +6 -0
  346. package/types/signal/intercept.d.ts +2 -2
  347. package/types/signal/internalArg.d.ts +22 -6
  348. package/types/signal/mcp/McpDocument.d.ts +84 -0
  349. package/types/signal/mcp/McpProgress.d.ts +40 -0
  350. package/types/signal/mcp/McpUriTemplate.d.ts +25 -0
  351. package/types/signal/mcp/Msg.d.ts +143 -0
  352. package/types/signal/mcp/index.d.ts +5 -0
  353. package/types/signal/mcp/mcpProtocol.d.ts +107 -0
  354. package/types/signal/mcp.d.ts +1 -0
  355. package/types/signal/middleware.d.ts +7 -7
  356. package/types/signal/openapi/openapi.d.ts +3 -3
  357. package/types/signal/schema/JsonSchemaBuilder.d.ts +51 -0
  358. package/types/signal/schema/index.d.ts +1 -0
  359. package/types/signal/schema.d.ts +1 -0
  360. package/types/signal/signalContext.d.ts +67 -8
  361. package/types/signal/slice.d.ts +42 -15
  362. package/types/signal/trace.d.ts +52 -2
  363. package/types/signal/types.d.ts +53 -4
  364. package/types/store/action.d.ts +7 -5
  365. package/types/store/actionTag.d.ts +21 -0
  366. package/types/store/agent/AgentBridge.d.ts +37 -0
  367. package/types/store/agent/AgentContext.d.ts +16 -0
  368. package/types/store/agent/AgentPrompts.d.ts +31 -0
  369. package/types/store/agent/ScreenReader.d.ts +29 -0
  370. package/types/store/agent/ScreenSettle.d.ts +22 -0
  371. package/types/store/agent/ScreenTarget.d.ts +34 -0
  372. package/types/store/agent/StoreCatalogue.d.ts +26 -0
  373. package/types/store/agent/StoreSurfaceSource.d.ts +30 -0
  374. package/types/store/agent/index.d.ts +11 -0
  375. package/types/store/agent/storeSurface.d.ts +14 -0
  376. package/types/store/agent/types.d.ts +15 -0
  377. package/types/store/agent.d.ts +1 -0
  378. package/types/store/agentic/AgentValue.d.ts +43 -0
  379. package/types/store/agentic/StExposeBuilder.d.ts +21 -0
  380. package/types/store/agentic/StExposeDraft.d.ts +13 -0
  381. package/types/store/agentic/StStateBuilder.d.ts +21 -0
  382. package/types/store/agentic/StStateDraft.d.ts +12 -0
  383. package/types/store/agentic/StToolBuilder.d.ts +56 -0
  384. package/types/store/agentic/StToolDraft.d.ts +13 -0
  385. package/types/store/agentic/attachAgentic.d.ts +25 -0
  386. package/types/store/agentic/formFields.d.ts +53 -0
  387. package/types/store/agentic/index.d.ts +12 -0
  388. package/types/store/agentic/useFieldTool.d.ts +22 -0
  389. package/types/store/agentic/useFormTools.d.ts +19 -0
  390. package/types/store/agentic/useRelationFieldTool.d.ts +27 -0
  391. package/types/store/agentic.d.ts +1 -0
  392. package/types/store/baseSt.d.ts +35 -39
  393. package/types/store/databaseStateNames.d.ts +25 -0
  394. package/types/store/formSetterNames.d.ts +30 -0
  395. package/types/store/index.d.ts +7 -0
  396. package/types/store/rootStore.d.ts +5 -1
  397. package/types/store/sliceRole.d.ts +25 -0
  398. package/types/store/store.d.ts +5 -1
  399. package/types/store/storeInstance.d.ts +33 -1
  400. package/types/store/storeRegistry.d.ts +5 -0
  401. package/types/store/types.d.ts +4 -0
  402. package/types/store/withSelector.d.ts +5 -4
  403. package/types/test/index.d.ts +1 -1
  404. package/types/test/registerDom.d.ts +1 -0
  405. package/types/test/signalTestRuntime.d.ts +2 -3
  406. package/types/test/testServer.d.ts +6 -4
  407. package/types/ui/Agent/Approval.d.ts +8 -0
  408. package/types/ui/Agent/Attach.d.ts +16 -0
  409. package/types/ui/Agent/Bubble.d.ts +26 -0
  410. package/types/ui/Agent/Chat.d.ts +91 -0
  411. package/types/ui/Agent/ChatCommands.d.ts +34 -0
  412. package/types/ui/Agent/Composer.d.ts +23 -0
  413. package/types/ui/Agent/Context.d.ts +13 -0
  414. package/types/ui/Agent/Dock.d.ts +17 -0
  415. package/types/ui/Agent/Guide.d.ts +9 -0
  416. package/types/ui/Agent/History.d.ts +26 -0
  417. package/types/ui/Agent/Launcher.d.ts +16 -0
  418. package/types/ui/Agent/Markdown.d.ts +19 -0
  419. package/types/ui/Agent/Menu.d.ts +18 -0
  420. package/types/ui/Agent/Mic.d.ts +8 -0
  421. package/types/ui/Agent/Question.d.ts +14 -0
  422. package/types/ui/Agent/Section.d.ts +10 -0
  423. package/types/ui/Agent/Skip.d.ts +22 -0
  424. package/types/ui/Agent/StateKey.d.ts +16 -0
  425. package/types/ui/Agent/Tool.d.ts +15 -0
  426. package/types/ui/Agent/Transcript.d.ts +13 -0
  427. package/types/ui/Agent/Zone.d.ts +48 -0
  428. package/types/ui/Agent/agentSessionOf.d.ts +27 -0
  429. package/types/ui/Agent/attachment.d.ts +34 -0
  430. package/types/ui/Agent/fetchRunner.d.ts +12 -0
  431. package/types/ui/Agent/index.d.ts +19 -0
  432. package/types/ui/Agent/index_.d.ts +1 -0
  433. package/types/ui/Agent/markdownBlocks.d.ts +35 -0
  434. package/types/ui/Agent/markdownSpans.d.ts +2 -0
  435. package/types/ui/Agent/markdownTable.d.ts +16 -0
  436. package/types/ui/Agent/sessionHistory.d.ts +14 -0
  437. package/types/ui/Agent/sessionView.d.ts +15 -0
  438. package/types/ui/Agent/tokenCount.d.ts +6 -0
  439. package/types/ui/Agent/useChatAttachments.d.ts +24 -0
  440. package/types/ui/Agent/useChatVoice.d.ts +30 -0
  441. package/types/ui/Agent/useDraftRecall.d.ts +14 -0
  442. package/types/ui/Agent/useKeyboardInset.d.ts +8 -0
  443. package/types/ui/Agent/useSlashMenu.d.ts +24 -0
  444. package/types/ui/Agent/voice.d.ts +71 -0
  445. package/types/ui/Agent.d.ts +1 -0
  446. package/types/ui/Badge.d.ts +1 -1
  447. package/types/ui/Button.d.ts +1 -1
  448. package/types/ui/Constant/Graph.d.ts +10 -0
  449. package/types/ui/Constant/index.d.ts +2 -1
  450. package/types/ui/Constant/schemaGraph.d.ts +39 -0
  451. package/types/ui/Data/Dashboard.d.ts +16 -3
  452. package/types/ui/Data/Insight.d.ts +1 -1
  453. package/types/ui/Data/ListContainer.d.ts +15 -7
  454. package/types/ui/Data/QueryMaker.d.ts +45 -3
  455. package/types/ui/Data/RefPicker.d.ts +16 -0
  456. package/types/ui/Data/dataExport.d.ts +5 -0
  457. package/types/ui/Data/dataText.d.ts +6 -0
  458. package/types/ui/Data/index.d.ts +2 -0
  459. package/types/ui/Data/index_.d.ts +1 -0
  460. package/types/ui/DatePicker.d.ts +15 -11
  461. package/types/ui/Dialog/LegacyModal.d.ts +13 -0
  462. package/types/ui/Dialog/Provider.d.ts +3 -1
  463. package/types/ui/Dialog/context.d.ts +9 -1
  464. package/types/ui/Dialog/index.d.ts +1 -0
  465. package/types/ui/DraggableList.d.ts +1 -1
  466. package/types/ui/Dropdown.d.ts +5 -1
  467. package/types/ui/Field.d.ts +13 -12
  468. package/types/ui/Layout/BottomTab.d.ts +3 -2
  469. package/types/ui/LegacyModal.d.ts +24 -0
  470. package/types/ui/Loading/ProgressBar.d.ts +4 -0
  471. package/types/ui/Loading/Spin.d.ts +2 -1
  472. package/types/ui/Model/AdminPanel.d.ts +15 -3
  473. package/types/ui/Model/EditModal.d.ts +1 -1
  474. package/types/ui/Model/New.d.ts +3 -1
  475. package/types/ui/Model/NewWrapper.d.ts +2 -0
  476. package/types/ui/Model/NewWrapper_Client.d.ts +2 -1
  477. package/types/ui/Pagination.d.ts +2 -2
  478. package/types/ui/Radio.d.ts +1 -1
  479. package/types/ui/RecentTime.d.ts +18 -1
  480. package/types/ui/Reference/Collapse.d.ts +11 -0
  481. package/types/ui/Reference/Panel.d.ts +29 -0
  482. package/types/ui/Reference/Segmented.d.ts +17 -0
  483. package/types/ui/Reference/Summary.d.ts +13 -0
  484. package/types/ui/Reference/Toolbar.d.ts +21 -0
  485. package/types/ui/Reference/dictText.d.ts +6 -0
  486. package/types/ui/Reference/index.d.ts +7 -0
  487. package/types/ui/Reference/style.d.ts +20 -0
  488. package/types/ui/Reference.d.ts +1 -0
  489. package/types/ui/ScreenNavigator.d.ts +3 -1
  490. package/types/ui/Signal/Arg.d.ts +7 -3
  491. package/types/ui/Signal/Doc.d.ts +4 -6
  492. package/types/ui/Signal/Object.d.ts +2 -1
  493. package/types/ui/Signal/RestApi.d.ts +2 -1
  494. package/types/ui/Signal/WebSocket.d.ts +2 -1
  495. package/types/ui/Signal/endpointEntries.d.ts +20 -0
  496. package/types/ui/Signal/style.d.ts +9 -8
  497. package/types/ui/System/Client.d.ts +1 -2
  498. package/types/ui/System/Common.d.ts +3 -4
  499. package/types/ui/System/Messages.d.ts +1 -1
  500. package/types/ui/Tab/Provider.d.ts +3 -1
  501. package/types/ui/Tab/context.d.ts +4 -2
  502. package/types/ui/ToggleSelect.d.ts +1 -0
  503. package/types/ui/UiOverride/context.d.ts +18 -1
  504. package/types/ui/agentAttrs.d.ts +14 -0
  505. package/types/ui/index.d.ts +22 -1
  506. package/types/ui/overlayLayer.d.ts +13 -0
  507. package/types/ui/overlayPosition.d.ts +28 -0
  508. package/types/ui/recipe/badgeRecipe.d.ts +2 -2
  509. package/types/ui/recipe/buttonRecipe.d.ts +2 -2
  510. package/types/vendor/use-agentic/AgentAbort.d.ts +17 -0
  511. package/types/vendor/use-agentic/AgentProgress.d.ts +27 -0
  512. package/types/vendor/use-agentic/AgentProvider.d.ts +17 -0
  513. package/types/vendor/use-agentic/AgentScope.d.ts +9 -0
  514. package/types/vendor/use-agentic/AgentSession.d.ts +163 -0
  515. package/types/vendor/use-agentic/Agentic.d.ts +21 -0
  516. package/types/vendor/use-agentic/AgenticSurface.d.ts +58 -0
  517. package/types/vendor/use-agentic/Compaction.d.ts +48 -0
  518. package/types/vendor/use-agentic/ToolOutput.d.ts +21 -0
  519. package/types/vendor/use-agentic/Transcript.d.ts +18 -0
  520. package/types/vendor/use-agentic/httpRunner.d.ts +15 -0
  521. package/types/vendor/use-agentic/index.d.ts +19 -0
  522. package/types/vendor/use-agentic/sharedContext.d.ts +15 -0
  523. package/types/vendor/use-agentic/surfaceContext.d.ts +5 -0
  524. package/types/vendor/use-agentic/types.d.ts +182 -0
  525. package/types/vendor/use-agentic/useAgent.d.ts +4 -0
  526. package/types/vendor/use-agentic/useAgentGuide.d.ts +6 -0
  527. package/types/vendor/use-agentic/useAgentResource.d.ts +12 -0
  528. package/types/vendor/use-agentic/useAgentState.d.ts +16 -0
  529. package/types/vendor/use-agentic/useAgentTool.d.ts +16 -0
  530. package/types/vendor/use-agentic.d.ts +1 -0
  531. package/types/webkit/index.d.ts +4 -0
  532. package/types/webkit/useBodyScrollLock.d.ts +2 -0
  533. package/types/webkit/usePageTool.d.ts +19 -0
  534. package/types/webkit/useScreenScope.d.ts +25 -0
  535. package/ui/Agent/Approval.tsx +32 -0
  536. package/ui/Agent/Attach.tsx +77 -0
  537. package/ui/Agent/Bubble.tsx +192 -0
  538. package/ui/Agent/Chat.tsx +525 -0
  539. package/ui/Agent/ChatCommands.ts +141 -0
  540. package/ui/Agent/Composer.tsx +94 -0
  541. package/ui/Agent/Context.tsx +49 -0
  542. package/ui/Agent/Dock.tsx +77 -0
  543. package/ui/Agent/Guide.tsx +16 -0
  544. package/ui/Agent/History.tsx +49 -0
  545. package/ui/Agent/Launcher.tsx +60 -0
  546. package/ui/Agent/Markdown.tsx +142 -0
  547. package/ui/Agent/Menu.tsx +55 -0
  548. package/ui/Agent/Mic.tsx +27 -0
  549. package/ui/Agent/Question.tsx +63 -0
  550. package/ui/Agent/Section.tsx +24 -0
  551. package/ui/Agent/Skip.tsx +30 -0
  552. package/ui/Agent/StateKey.tsx +46 -0
  553. package/ui/Agent/Tool.tsx +59 -0
  554. package/ui/Agent/Transcript.tsx +33 -0
  555. package/ui/Agent/Zone.tsx +116 -0
  556. package/ui/Agent/agentSessionOf.ts +60 -0
  557. package/ui/Agent/attachment.ts +73 -0
  558. package/ui/Agent/fetchRunner.ts +44 -0
  559. package/ui/Agent/index.ts +27 -0
  560. package/ui/Agent/index_.tsx +4 -0
  561. package/ui/Agent/markdownBlocks.ts +137 -0
  562. package/ui/Agent/markdownSpans.tsx +49 -0
  563. package/ui/Agent/markdownTable.ts +54 -0
  564. package/ui/Agent/sessionHistory.ts +62 -0
  565. package/ui/Agent/sessionView.ts +38 -0
  566. package/ui/Agent/tokenCount.ts +10 -0
  567. package/ui/Agent/useChatAttachments.ts +84 -0
  568. package/ui/Agent/useChatVoice.ts +129 -0
  569. package/ui/Agent/useDraftRecall.ts +42 -0
  570. package/ui/Agent/useKeyboardInset.ts +26 -0
  571. package/ui/Agent/useSlashMenu.ts +58 -0
  572. package/ui/Agent/voice.ts +177 -0
  573. package/ui/Badge.tsx +1 -1
  574. package/ui/BottomSheet.tsx +32 -36
  575. package/ui/Button.tsx +3 -1
  576. package/ui/Clipboard.tsx +3 -6
  577. package/ui/Constant/Doc.tsx +265 -254
  578. package/ui/Constant/Graph.tsx +151 -0
  579. package/ui/Constant/index.ts +3 -2
  580. package/ui/Constant/schemaGraph.ts +232 -0
  581. package/ui/Data/CardList.tsx +14 -3
  582. package/ui/Data/Dashboard.tsx +70 -52
  583. package/ui/Data/Insight.tsx +18 -12
  584. package/ui/Data/Item.tsx +42 -56
  585. package/ui/Data/ListContainer.tsx +246 -132
  586. package/ui/Data/Pagination.tsx +10 -3
  587. package/ui/Data/QueryMaker.tsx +160 -11
  588. package/ui/Data/RefPicker.tsx +202 -0
  589. package/ui/Data/TableList.tsx +22 -13
  590. package/ui/Data/dataExport.ts +54 -0
  591. package/ui/Data/dataText.ts +22 -0
  592. package/ui/Data/index.ts +13 -1
  593. package/ui/Data/index_.tsx +1 -0
  594. package/ui/DatePicker.tsx +110 -128
  595. package/ui/Dialog/Close.tsx +3 -7
  596. package/ui/Dialog/LegacyModal.tsx +241 -0
  597. package/ui/Dialog/Modal.tsx +62 -195
  598. package/ui/Dialog/Provider.tsx +47 -3
  599. package/ui/Dialog/Trigger.tsx +3 -7
  600. package/ui/Dialog/context.ts +14 -2
  601. package/ui/Dialog/index.tsx +2 -0
  602. package/ui/DragAction.tsx +3 -2
  603. package/ui/DraggableList.tsx +9 -4
  604. package/ui/Dropdown.tsx +89 -27
  605. package/ui/Empty.tsx +6 -4
  606. package/ui/Field.tsx +128 -58
  607. package/ui/Input.tsx +27 -5
  608. package/ui/KeyboardAvoiding.tsx +2 -2
  609. package/ui/Layout/BottomTab.tsx +32 -37
  610. package/ui/Layout/Sider.tsx +37 -14
  611. package/ui/LegacyModal.tsx +53 -0
  612. package/ui/Link/CsrLink.tsx +1 -1
  613. package/ui/Load/Pagination.tsx +15 -8
  614. package/ui/Load/Units.tsx +30 -7
  615. package/ui/Load/View.tsx +10 -3
  616. package/ui/Loading/Area.tsx +7 -6
  617. package/ui/Loading/Button.tsx +7 -9
  618. package/ui/Loading/Input.tsx +7 -9
  619. package/ui/Loading/ProgressBar.tsx +16 -7
  620. package/ui/Loading/Skeleton.tsx +8 -13
  621. package/ui/Loading/Spin.tsx +20 -14
  622. package/ui/Menu.tsx +1 -1
  623. package/ui/Model/AdminPanel.tsx +52 -12
  624. package/ui/Model/EditModal.tsx +28 -6
  625. package/ui/Model/EditWrapper.tsx +16 -4
  626. package/ui/Model/New.tsx +4 -0
  627. package/ui/Model/NewWrapper.tsx +2 -0
  628. package/ui/Model/NewWrapper_Client.tsx +20 -6
  629. package/ui/Model/Remove.tsx +18 -6
  630. package/ui/Model/RemoveWrapper.tsx +12 -2
  631. package/ui/Model/SureToRemove.tsx +18 -6
  632. package/ui/Model/ViewEditModal.tsx +64 -15
  633. package/ui/Model/ViewModal.tsx +25 -11
  634. package/ui/Model/ViewWrapper.tsx +15 -4
  635. package/ui/Model/index_.tsx +1 -1
  636. package/ui/Pagination.tsx +51 -66
  637. package/ui/Popconfirm.tsx +88 -78
  638. package/ui/Radio.tsx +53 -24
  639. package/ui/RecentTime.tsx +83 -35
  640. package/ui/Reference/Collapse.tsx +26 -0
  641. package/ui/Reference/Panel.tsx +79 -0
  642. package/ui/Reference/Segmented.tsx +41 -0
  643. package/ui/Reference/Summary.tsx +25 -0
  644. package/ui/Reference/Toolbar.tsx +44 -0
  645. package/ui/Reference/dictText.ts +9 -0
  646. package/ui/Reference/index.ts +7 -0
  647. package/ui/Reference/style.ts +45 -0
  648. package/ui/ScreenNavigator.tsx +17 -2
  649. package/ui/Select.tsx +96 -57
  650. package/ui/Signal/Arg.tsx +83 -68
  651. package/ui/Signal/Doc.tsx +163 -129
  652. package/ui/Signal/Listener.tsx +40 -29
  653. package/ui/Signal/Message.tsx +87 -135
  654. package/ui/Signal/Object.tsx +79 -57
  655. package/ui/Signal/PubSub.tsx +72 -113
  656. package/ui/Signal/Request.tsx +2 -22
  657. package/ui/Signal/Response.tsx +19 -45
  658. package/ui/Signal/RestApi.tsx +170 -200
  659. package/ui/Signal/WebSocket.tsx +29 -26
  660. package/ui/Signal/endpointEntries.ts +59 -0
  661. package/ui/Signal/makeExample.ts +10 -3
  662. package/ui/Signal/style.ts +34 -29
  663. package/ui/Switch.tsx +4 -0
  664. package/ui/System/CSR.tsx +1 -1
  665. package/ui/System/Client.tsx +31 -15
  666. package/ui/System/Common.tsx +3 -4
  667. package/ui/System/DevModeToggle.tsx +1 -1
  668. package/ui/System/Gtag.tsx +2 -2
  669. package/ui/System/Messages.tsx +52 -31
  670. package/ui/System/Reconnect.tsx +22 -56
  671. package/ui/System/SelectLanguage.tsx +24 -15
  672. package/ui/System/ThemeToggle.tsx +25 -13
  673. package/ui/Tab/Menu.tsx +24 -12
  674. package/ui/Tab/Menus.tsx +6 -3
  675. package/ui/Tab/Provider.tsx +30 -3
  676. package/ui/Tab/context.ts +8 -4
  677. package/ui/Table.tsx +66 -60
  678. package/ui/ToggleSelect.tsx +8 -7
  679. package/ui/Tooltip.tsx +15 -1
  680. package/ui/UiOverride/context.ts +21 -2
  681. package/ui/Unauthorized.tsx +6 -4
  682. package/ui/agentAttrs.ts +19 -0
  683. package/ui/index.ts +49 -1
  684. package/ui/overlayLayer.ts +12 -2
  685. package/ui/overlayPosition.ts +104 -0
  686. package/ui/recipe/buttonRecipe.ts +2 -2
  687. package/ui/styles.css +31 -0
  688. package/vendor/use-agentic/AgentAbort.ts +29 -0
  689. package/vendor/use-agentic/AgentProgress.ts +40 -0
  690. package/vendor/use-agentic/AgentProvider.tsx +39 -0
  691. package/vendor/use-agentic/AgentScope.tsx +20 -0
  692. package/vendor/use-agentic/AgentSession.ts +750 -0
  693. package/vendor/use-agentic/Agentic.tsx +44 -0
  694. package/vendor/use-agentic/AgenticSurface.ts +333 -0
  695. package/vendor/use-agentic/Compaction.ts +120 -0
  696. package/vendor/use-agentic/ToolOutput.ts +60 -0
  697. package/vendor/use-agentic/Transcript.ts +50 -0
  698. package/vendor/use-agentic/WIRE.md +86 -0
  699. package/vendor/use-agentic/httpRunner.ts +131 -0
  700. package/vendor/use-agentic/index.ts +20 -0
  701. package/vendor/use-agentic/sharedContext.ts +25 -0
  702. package/vendor/use-agentic/surfaceContext.ts +10 -0
  703. package/vendor/use-agentic/types.ts +192 -0
  704. package/vendor/use-agentic/useAgent.ts +18 -0
  705. package/vendor/use-agentic/useAgentGuide.ts +16 -0
  706. package/vendor/use-agentic/useAgentResource.ts +36 -0
  707. package/vendor/use-agentic/useAgentState.ts +64 -0
  708. package/vendor/use-agentic/useAgentTool.ts +55 -0
  709. package/webkit/bootCsr.tsx +10 -8
  710. package/webkit/index.ts +4 -0
  711. package/webkit/lazy.tsx +5 -1
  712. package/webkit/useBodyScrollLock.tsx +29 -0
  713. package/webkit/useFrameRuntime.ts +1 -1
  714. package/webkit/usePageTool.tsx +37 -0
  715. package/webkit/useScreenScope.tsx +60 -0
  716. package/types/ui/Constant/Mermaid.d.ts +0 -8
  717. package/types/ui/Signal/Collapse.d.ts +0 -12
  718. package/ui/Constant/Mermaid.tsx +0 -149
  719. package/ui/Signal/Collapse.tsx +0 -29
@@ -0,0 +1,750 @@
1
+ import { AgentAbort } from "./AgentAbort";
2
+ import { AgentProgress, type AgentProgressReport } from "./AgentProgress";
3
+ import { Compaction, type CompactOptions } from "./Compaction";
4
+ import { ToolOutput } from "./ToolOutput";
5
+ import { Transcript } from "./Transcript";
6
+ import type {
7
+ AgentRunner,
8
+ ChatMessage,
9
+ ContextBlock,
10
+ PublishedTool,
11
+ RunnerRequest,
12
+ SurfaceView,
13
+ ToolCallRequest,
14
+ ToolCallResult,
15
+ ToolEntry,
16
+ } from "./types";
17
+
18
+ export interface PendingApproval {
19
+ callId: string;
20
+ name: string;
21
+ args: Record<string, unknown>;
22
+ message: string;
23
+ approve: () => void;
24
+ reject: (reason?: string) => void;
25
+ }
26
+
27
+ /**
28
+ * A decision the agent handed back to the user mid-turn. The loop is parked on it until it settles, exactly as it
29
+ * parks on an approval. `choices` is empty for a free-text ask, and `multiple` never accompanies an empty one.
30
+ */
31
+ export interface PendingQuestion {
32
+ callId: string;
33
+ question: string;
34
+ choices: string[];
35
+ multiple: boolean;
36
+ answer: (value: string | string[]) => void;
37
+ dismiss: (reason?: string) => void;
38
+ }
39
+
40
+ /**
41
+ * Where a session keeps its transcript across page loads. Storage-neutral: the host decides what backs it, so a
42
+ * server-side transcript is as legal as web storage — which is why every method may answer asynchronously. A
43
+ * `load` still in flight when the user sends the first message is dropped rather than merged: the conversation
44
+ * on screen is the one they are having, and splicing a restored one under it would rewrite what they just said.
45
+ *
46
+ * Which makes **sending on mount a race the restore loses** — an opening prompt fired from an effect beats the
47
+ * fetch, and the user watches the conversation they came back to never arrive. Wait for `isRestoring` to clear,
48
+ * or write the prompt into the composer and leave the send to them.
49
+ */
50
+ export interface SessionHistory {
51
+ load(): ChatMessage[] | null | Promise<ChatMessage[] | null>;
52
+ save(messages: readonly ChatMessage[]): void | Promise<void>;
53
+ clear(): void | Promise<void>;
54
+ }
55
+
56
+ export interface AgentSessionOptions {
57
+ instructions?: string;
58
+ buildContext?: (surface: SurfaceView) => ContextBlock[];
59
+ /** Assistant turns per send before the session asks whether to keep going, or stops. */
60
+ maxTurns?: number;
61
+ /**
62
+ * Restores settled messages at construction and saves after every change, debounced. Failures are silent, and
63
+ * saves are chained rather than issued in parallel — an async host would otherwise land them out of order and
64
+ * persist an older transcript last.
65
+ */
66
+ history?: SessionHistory;
67
+ /**
68
+ * Awaited after a tool that changed something and before its change report is taken. A surface is read
69
+ * synchronously and a screen does not settle synchronously, so without this the report describes the moment
70
+ * before the change landed. `ScreenSettle.wait` is what an akan app passes.
71
+ */
72
+ settle?: () => Promise<void> | void;
73
+ /**
74
+ * Turns the turn cap into a question instead of a dead end. Omitted, the cap fails as before — a host that
75
+ * renders no `pendingQuestion` would otherwise wait forever for an answer nobody can give. Read per ask rather
76
+ * than at construction, so the text follows a language switched mid-conversation.
77
+ */
78
+ continueAsk?: () => { question: string; keep: string };
79
+ /**
80
+ * Keeps a long conversation inside the model's window: past `at` estimated tokens the history above the last
81
+ * few messages is replaced by one summary of itself, before the turn that would have overflowed is sent.
82
+ */
83
+ compact?: CompactOptions;
84
+ /**
85
+ * Fires after a compaction replaced `replaced` with `summary`. A host that keeps its own server-side summary
86
+ * uses it to move its watermark to the same cut, so the two do not summarize the same messages twice.
87
+ *
88
+ * It matters most to a host whose watermark is a *position*: compaction shrinks the transcript in place, so a
89
+ * "sync everything past index N" scheme silently stops syncing once N is past the shortened array — no
90
+ * duplicate, no error, just messages that never reach the server. Reset the mark here.
91
+ */
92
+ onCompact?: (replaced: readonly ChatMessage[], summary: ChatMessage) => void;
93
+ }
94
+
95
+ /**
96
+ * The client-side conversation loop: send → model turn → tool calls → approval gate → execute → report diffs → next
97
+ * turn. The loop lives here rather than on a server because the tools do — the runner is one stateless model turn,
98
+ * so any backend that answers it works and none has to hold a session.
99
+ *
100
+ * Failures land in the transcript instead of being thrown past it: a refused guard, a rejected approval, and an
101
+ * unknown tool are all things the agent did, and the model reads them as tool results the same way a person reads
102
+ * them in the chat.
103
+ */
104
+ export class AgentSession {
105
+ /**
106
+ * The one built-in the session owns instead of the surface: the answer comes from the conversation, not the
107
+ * screen, so every host that renders `pendingQuestion` gets it and a zone agent asks inside its own transcript.
108
+ * A surface tool of this name shadows it, like any other built-in.
109
+ */
110
+ static readonly askUserTool: PublishedTool = {
111
+ name: "askUser",
112
+ description:
113
+ "Ask the user to decide something that is theirs to decide — an ambiguous request, a missing value, a choice between paths. Use it instead of guessing. Pass `choices` to offer options, or omit them for a free-text answer; the user may answer off-list either way. Returns what they chose or wrote, and errors if they dismiss it.",
114
+ parameters: {
115
+ type: "object",
116
+ properties: {
117
+ question: { type: "string", description: "What to ask, in one sentence." },
118
+ choices: { type: "array", items: { type: "string" }, description: "The options to offer, as short labels." },
119
+ multiple: { type: "boolean", description: "Let the user pick several choices. Ignored without choices." },
120
+ },
121
+ required: ["question"],
122
+ additionalProperties: false,
123
+ },
124
+ needsConfirm: false,
125
+ };
126
+
127
+ readonly #surface: SurfaceView;
128
+ readonly #runner: AgentRunner;
129
+ readonly #options: AgentSessionOptions;
130
+ #messages: ChatMessage[] = [];
131
+ #running = false;
132
+ #pending: PendingApproval | null = null;
133
+ #question: PendingQuestion | null = null;
134
+ #progress: (AgentProgressReport & { callId: string }) | null = null;
135
+ #controller: AbortController | null = null;
136
+ #active: Promise<void> | null = null;
137
+ #version = 0;
138
+ #listeners = new Set<() => void>();
139
+ #saveTimer: ReturnType<typeof setTimeout> | null = null;
140
+ #saving: Promise<unknown> = Promise.resolve();
141
+ #restoring = false;
142
+
143
+ #history: SessionHistory | undefined;
144
+ #onCompact: AgentSessionOptions["onCompact"];
145
+ #compacting = false;
146
+ /** Size below which auto-compaction stays out of the way, raised when a summary failed to shrink anything. */
147
+ #compactFloor = 0;
148
+
149
+ constructor(surface: SurfaceView, runner: AgentRunner, options: AgentSessionOptions = {}) {
150
+ this.#surface = surface;
151
+ this.#runner = runner;
152
+ this.#options = options;
153
+ this.#history = options.history;
154
+ this.#onCompact = options.onCompact;
155
+ const restored = AgentSession.#restored(options.history);
156
+ if (Array.isArray(restored)) this.#messages = restored;
157
+ else {
158
+ this.#restoring = true;
159
+ void this.#hydrate(restored);
160
+ }
161
+ }
162
+
163
+ /**
164
+ * True while an async `history.load()` is still in flight — the transcript is empty but not yet known to be.
165
+ * A host that opens with a prompt of its own waits for this before sending, or the restore loses the race.
166
+ */
167
+ get isRestoring() {
168
+ return this.#restoring;
169
+ }
170
+
171
+ get surface(): SurfaceView {
172
+ return this.#surface;
173
+ }
174
+
175
+ get messages(): readonly ChatMessage[] {
176
+ return this.#messages;
177
+ }
178
+
179
+ get isRunning() {
180
+ return this.#running;
181
+ }
182
+
183
+ /**
184
+ * True while the conversation is summarizing itself. Distinct from `isRunning`, which an auto-compaction runs
185
+ * inside: the summarizing turn answers nothing the user asked for and takes as long as a model turn, so a chat
186
+ * that only says "running" reads as a question being ignored.
187
+ */
188
+ get isCompacting() {
189
+ return this.#compacting;
190
+ }
191
+
192
+ get pendingApproval(): PendingApproval | null {
193
+ return this.#pending;
194
+ }
195
+
196
+ get pendingQuestion(): PendingQuestion | null {
197
+ return this.#question;
198
+ }
199
+
200
+ /** What the tool running now last said about its own progress, for the row that is still spinning. */
201
+ get progress(): (AgentProgressReport & { callId: string }) | null {
202
+ return this.#progress;
203
+ }
204
+
205
+ /** Bumped on every change, so a store binding can use it as the snapshot. */
206
+ get version() {
207
+ return this.#version;
208
+ }
209
+
210
+ subscribe = (listener: () => void) => {
211
+ this.#listeners.add(listener);
212
+ return () => {
213
+ this.#listeners.delete(listener);
214
+ };
215
+ };
216
+
217
+ /** A user's text, or prewritten messages — how a host injects a prompt's result as the user's turn. */
218
+ send = async (input: string | ChatMessage[]) => {
219
+ if (this.#running) throw new Error("A turn is already running.");
220
+ this.#running = true;
221
+ const run = this.#turn(input);
222
+ this.#active = run;
223
+ await run;
224
+ };
225
+
226
+ async #turn(input: string | ChatMessage[]) {
227
+ const controller = new AbortController();
228
+ this.#controller = controller;
229
+ if (typeof input === "string") this.#append({ role: "user", text: input });
230
+ else for (const message of input) this.#append(message);
231
+ const maxTurns = this.#options.maxTurns ?? 8;
232
+ try {
233
+ let budget = maxTurns;
234
+ for (let turn = 0; ; turn += 1) {
235
+ if (controller.signal.aborted) return;
236
+ if (turn >= budget) {
237
+
238
+ const answer = await this.#askToContinue(turn, controller.signal);
239
+ if (answer === null) {
240
+ this.#fail(`Stopped after ${turn} assistant turns without a final answer.`);
241
+ return;
242
+ }
243
+ this.#append({ role: "user", text: answer });
244
+ budget = turn + maxTurns;
245
+ }
246
+ await this.#autoCompact(controller.signal);
247
+ const { toolCalls, stop } = await this.#assistantTurn(controller.signal);
248
+
249
+ if (controller.signal.aborted) {
250
+ this.#unanswered(toolCalls);
251
+ return;
252
+ }
253
+ if (stop !== "toolUse" || !toolCalls.length) return;
254
+ const toolResults: ToolCallResult[] = [];
255
+ for (const call of toolCalls)
256
+ toolResults.push(
257
+ controller.signal.aborted
258
+ ? { id: call.id, name: call.name, error: Transcript.unanswered }
259
+ :
260
+
261
+ ToolOutput.clipped(await this.#execute(call, controller.signal)),
262
+ );
263
+ this.#append({ role: "tool", toolResults });
264
+ }
265
+ } catch (error) {
266
+ if (!controller.signal.aborted) this.#fail(error instanceof Error ? error.message : String(error));
267
+ } finally {
268
+ this.#running = false;
269
+ this.#controller = null;
270
+ this.#active = null;
271
+ this.#pending = null;
272
+ this.#question = null;
273
+ this.#progress = null;
274
+ this.#notify();
275
+ }
276
+ }
277
+
278
+ abort = () => {
279
+ this.#controller?.abort();
280
+ };
281
+
282
+ /**
283
+ * Empties the transcript and the persisted history, ending a turn that is still running. Awaiting the abort
284
+ * matters: the loop settles in its own `finally`, a microtask later, and a transcript emptied before that lands
285
+ * is one the winding-down turn appends onto. The returned promise waits for the history to clear too.
286
+ */
287
+ reset = async () => {
288
+ if (this.#active) {
289
+ this.#controller?.abort();
290
+ await this.#active;
291
+ }
292
+ this.#messages = [];
293
+ this.#compactFloor = 0;
294
+
295
+ if (this.#saveTimer) {
296
+ clearTimeout(this.#saveTimer);
297
+ this.#saveTimer = null;
298
+ }
299
+ const history = this.#history;
300
+ if (history) {
301
+
302
+ this.#saving = this.#saving.then(() => history.clear()).catch(() => undefined);
303
+ await this.#saving;
304
+ }
305
+ this.#version += 1;
306
+ for (const listener of this.#listeners) listener();
307
+ };
308
+
309
+ /**
310
+ * Attaches a transcript store to a session built without one — what `Agent.History` mounts, so a zone can be
311
+ * assembled by a server component and still keep its transcript wherever the app keeps it. `null` detaches.
312
+ *
313
+ * Restoring follows the rule an async `load` already follows: it lands only while nothing has happened to this
314
+ * session yet. Attach before the first turn and it restores; attach after and it saves from there on, with the
315
+ * store never asked for a transcript that would be discarded. One rule rather than a mount-order surprise.
316
+ *
317
+ * Returns the detach, which clears the slot only while this call's store is still the one in it.
318
+ */
319
+ setHistory = (history: SessionHistory | null) => {
320
+ this.#history = history ?? undefined;
321
+ if (history && this.#version === 0) {
322
+ const restored = AgentSession.#restored(history);
323
+ if (restored instanceof Promise) {
324
+ this.#restoring = true;
325
+ void this.#hydrate(restored);
326
+ } else this.#restore(restored);
327
+ }
328
+
329
+ return () => {
330
+ if (history && this.#history === history) this.#history = undefined;
331
+ };
332
+ };
333
+
334
+ /** The compaction hook as a setter, for the same reason `setHistory` is one: a host attaches it after the fact. */
335
+ setOnCompact = (onCompact: AgentSessionOptions["onCompact"] | null) => {
336
+ this.#onCompact = onCompact ?? undefined;
337
+ return () => {
338
+ if (onCompact && this.#onCompact === onCompact) this.#onCompact = undefined;
339
+ };
340
+ };
341
+
342
+ /**
343
+ * Re-runs the last user message, dropping what the previous attempt produced. Turns fail for reasons that have
344
+ * nothing to do with what was asked — a refused relay, a model that is unavailable — and retyping is otherwise the
345
+ * only way back. Only the trailing message is replayed, so a prompt's own preamble stays where it is.
346
+ */
347
+ retry = async (): Promise<boolean> => {
348
+ if (this.#active) return false;
349
+ const at = this.#messages.findLastIndex(
350
+
351
+ (message) => message.role === "user" && !message.summary && (!!message.text || !!message.attachments?.length),
352
+ );
353
+ if (at < 0) return false;
354
+ const again = this.#messages[at];
355
+ this.#messages = this.#messages.slice(0, at);
356
+ await this.send([again]);
357
+ return true;
358
+ };
359
+
360
+ /**
361
+ * Replaces the history with one summary of itself and returns whether anything was replaced. `keep` leaves that
362
+ * many trailing messages verbatim; the command that a user types keeps none, because a summary of everything is
363
+ * what they asked for. A turn in flight refuses — the transcript it is appending to is not one to rewrite.
364
+ */
365
+ compact = async ({ keep = 0 }: { keep?: number } = {}): Promise<boolean> => {
366
+ if (this.#running) return false;
367
+ const controller = new AbortController();
368
+ this.#controller = controller;
369
+ this.#running = true;
370
+
371
+ this.#notify();
372
+ const run = this.#compact(keep, controller.signal);
373
+
374
+ this.#active = run.then(
375
+ () => undefined,
376
+ () => undefined,
377
+ );
378
+ try {
379
+ return await run;
380
+ } catch (error) {
381
+
382
+ if (controller.signal.aborted) return false;
383
+ throw error;
384
+ } finally {
385
+ this.#running = false;
386
+ this.#controller = null;
387
+ this.#active = null;
388
+ this.#notify();
389
+ }
390
+ };
391
+
392
+ /** What the transcript is estimated to cost the next turn, in tokens — the number auto-compaction watches. */
393
+ get tokens() {
394
+ return Compaction.tokensOf(this.#messages);
395
+ }
396
+
397
+ /** Records a host-side failure (a prompt fetch, an upload) in the transcript, where every other failure lands. */
398
+ report = (error: string) => {
399
+ this.#append({ role: "assistant", error });
400
+ };
401
+
402
+ /** A line the host wrote — a command's own output. Rendered in the transcript, withheld from the model. */
403
+ note = (text: string) => {
404
+ this.#append({ role: "assistant", text, local: true });
405
+ };
406
+
407
+ async #compact(keep: number, signal: AbortSignal): Promise<boolean> {
408
+ const at = Compaction.cutAt(this.#messages, keep);
409
+ if (at <= 0) return false;
410
+ this.#compacting = true;
411
+ this.#notify();
412
+ try {
413
+ const summary = (await this.#summarize(Compaction.digest(this.#messages.slice(0, at)), signal)).trim();
414
+ if (!summary || signal.aborted) return false;
415
+ const replaced = this.#messages.slice(0, at);
416
+ const message = Compaction.message(summary);
417
+ this.#messages = [message, ...this.#messages.slice(at)];
418
+ try {
419
+ this.#onCompact?.(replaced, message);
420
+ } catch {
421
+ }
422
+ return true;
423
+ } finally {
424
+ this.#compacting = false;
425
+ this.#notify();
426
+ }
427
+ }
428
+
429
+ /**
430
+ * Runs before the turn that would have overflowed rather than after it fails: the provider answers a request
431
+ * that is too long with a refusal, not with a shorter answer, so there is nothing to recover from afterwards.
432
+ * Best effort — a summary that cannot be produced leaves the transcript as it stands and the turn goes out as
433
+ * it would have, since it may well still fit.
434
+ */
435
+ async #autoCompact(signal: AbortSignal) {
436
+ const { at = Compaction.defaults.at, keep = Compaction.defaults.keep } = this.#options.compact ?? {};
437
+ if (!at || Compaction.tokensOf(this.#messages) < Math.max(at, this.#compactFloor)) return;
438
+ let compacted = false;
439
+ try {
440
+ compacted = await this.#compact(keep, signal);
441
+ } catch (error) {
442
+
443
+ console.warn(`[use-agentic] compaction failed: ${error instanceof Error ? error.message : String(error)}`);
444
+ return;
445
+ }
446
+ const after = Compaction.tokensOf(this.#messages);
447
+
448
+ this.#compactFloor = compacted && after >= at ? after + at : 0;
449
+ }
450
+
451
+ /** No tools and no screen context: this turn summarizes the conversation, and must not act on it. */
452
+ async #summarize(digest: string, signal: AbortSignal): Promise<string> {
453
+ const custom = this.#options.compact?.summarize;
454
+ if (custom) return await custom(digest, signal);
455
+ let text = "";
456
+ for await (const event of this.#runner.run({
457
+ messages: [{ role: "user", text: digest }],
458
+ tools: [],
459
+ context: [],
460
+ instructions: Compaction.instruction,
461
+ signal,
462
+ })) {
463
+ if (event.type === "text") text += event.delta;
464
+ else if (event.type === "error") throw new Error(event.message);
465
+ }
466
+ return text;
467
+ }
468
+
469
+ async #assistantTurn(signal: AbortSignal): Promise<{ toolCalls: ToolCallRequest[]; stop: "end" | "toolUse" }> {
470
+ const { tools, guides } = this.#surface.snapshot();
471
+ const instructions = [this.#options.instructions, ...guides].filter(Boolean).join("\n\n");
472
+ const request: RunnerRequest = {
473
+ messages: Transcript.wire(this.#messages),
474
+ tools: tools.some((tool) => tool.name === AgentSession.askUserTool.name)
475
+ ? tools
476
+ : [...tools, AgentSession.askUserTool],
477
+ context: this.#options.buildContext?.(this.#surface) ?? AgentSession.#defaultContext(this.#surface),
478
+ ...(instructions ? { instructions } : {}),
479
+ signal,
480
+ };
481
+ this.#append({ role: "assistant" });
482
+ let text = "";
483
+ const toolCalls: ToolCallRequest[] = [];
484
+ let stop: "end" | "toolUse" = "end";
485
+ for await (const event of this.#runner.run(request)) {
486
+ if (signal.aborted) break;
487
+ if (event.type === "text") {
488
+ text += event.delta;
489
+ this.#patchLast({ text });
490
+ } else if (event.type === "toolCall") toolCalls.push({ id: event.id, name: event.name, args: event.args });
491
+ else if (event.type === "done") stop = event.stop;
492
+ else throw new Error(event.message);
493
+ }
494
+ if (toolCalls.length) this.#patchLast({ toolCalls });
495
+ return { toolCalls, stop };
496
+ }
497
+
498
+ async #execute(call: ToolCallRequest, signal: AbortSignal): Promise<ToolCallResult> {
499
+ const base = { id: call.id, name: call.name };
500
+ const entry = this.#surface.tool(call.name);
501
+ if (!entry) {
502
+ if (call.name === AgentSession.askUserTool.name) return await this.#ask(call, signal);
503
+ return { ...base, error: `Unknown tool: ${call.name}` };
504
+ }
505
+ const message = AgentSession.#confirmMessage(call.name, entry, call.args);
506
+ if (message) {
507
+ const approved = await this.#awaitApproval(call, message, signal);
508
+ if (approved !== true) return { ...base, error: approved };
509
+ }
510
+ const before = this.#surface.snapshot();
511
+ try {
512
+ const result = await AgentAbort.run(signal, () =>
513
+ AgentProgress.run(
514
+ (report) => {
515
+ this.#progress = { ...report, callId: call.id };
516
+ this.#notify();
517
+ },
518
+ () => AgentSession.#raced(this.#surface.call(call.name, call.args), signal),
519
+ ),
520
+ );
521
+
522
+ if (entry.settle !== false) await this.#options.settle?.();
523
+ const changes = this.#surface.diffSince(before);
524
+ return {
525
+ ...base,
526
+ ...(result !== undefined ? { result } : {}),
527
+ ...(changes.length ? { changes } : {}),
528
+ };
529
+ } catch (error) {
530
+ return { ...base, error: error instanceof Error ? error.message : String(error) };
531
+ } finally {
532
+ if (this.#progress?.callId === call.id) {
533
+ this.#progress = null;
534
+ this.#notify();
535
+ }
536
+ }
537
+ }
538
+
539
+ /** `null` when the user declined or no ask is configured: both mean stop and record why. */
540
+ async #askToContinue(turns: number, signal: AbortSignal): Promise<string | null> {
541
+ const ask = this.#options.continueAsk?.();
542
+ if (!ask) return null;
543
+ const settled = await this.#awaitAnswer(`continue-${turns}`, ask.question, [ask.keep], false, signal);
544
+ if ("error" in settled) return null;
545
+ return Array.isArray(settled.result) ? settled.result.join(", ") : settled.result;
546
+ }
547
+
548
+ /** No surface call and so no diff to report: the only thing this changes is what the model knows. */
549
+ async #ask(call: ToolCallRequest, signal: AbortSignal): Promise<ToolCallResult> {
550
+ const base = { id: call.id, name: call.name };
551
+ const question = typeof call.args.question === "string" ? call.args.question.trim() : "";
552
+ if (!question) return { ...base, error: "askUser needs a question to ask." };
553
+
554
+ const choices = [
555
+ ...new Set(
556
+ (Array.isArray(call.args.choices) ? call.args.choices : [])
557
+ .filter((choice): choice is string => typeof choice === "string")
558
+ .map((choice) => choice.trim())
559
+ .filter(Boolean),
560
+ ),
561
+ ];
562
+ const multiple = call.args.multiple === true && choices.length > 1;
563
+ return { ...base, ...(await this.#awaitAnswer(call.id, question, choices, multiple, signal)) };
564
+ }
565
+
566
+ #awaitAnswer(
567
+ callId: string,
568
+ question: string,
569
+ choices: string[],
570
+ multiple: boolean,
571
+ signal: AbortSignal,
572
+ ): Promise<{ result: string | string[] } | { error: string }> {
573
+ return new Promise((resolve) => {
574
+ const settle = (value: { result: string | string[] } | { error: string }) => {
575
+ this.#question = null;
576
+ signal.removeEventListener("abort", onAbort);
577
+ this.#notify();
578
+ resolve(value);
579
+ };
580
+ const onAbort = () => settle({ error: "The user aborted the turn." });
581
+ signal.addEventListener("abort", onAbort);
582
+ this.#question = {
583
+ callId,
584
+ question,
585
+ choices,
586
+ multiple,
587
+ answer: (value) => settle({ result: value }),
588
+ dismiss: (reason) => settle({ error: reason ?? "The user dismissed the question without answering it." }),
589
+ };
590
+ this.#notify();
591
+ });
592
+ }
593
+
594
+ #awaitApproval(call: ToolCallRequest, message: string, signal: AbortSignal): Promise<true | string> {
595
+ return new Promise((resolve) => {
596
+ const settle = (value: true | string) => {
597
+ this.#pending = null;
598
+ signal.removeEventListener("abort", onAbort);
599
+ this.#notify();
600
+ resolve(value);
601
+ };
602
+ const onAbort = () => settle("The user aborted the turn.");
603
+ signal.addEventListener("abort", onAbort);
604
+ this.#pending = {
605
+ callId: call.id,
606
+ name: call.name,
607
+ args: call.args,
608
+ message,
609
+ approve: () => settle(true),
610
+ reject: (reason) => settle(reason ?? "The user declined."),
611
+ };
612
+ this.#notify();
613
+ });
614
+ }
615
+
616
+ /**
617
+ * The call, or the abort — whichever lands first.
618
+ *
619
+ * A tool is handed the signal through `AgentAbort` and may stop itself, but nothing obliges it to, and a tool
620
+ * that waits on a two-minute job is exactly the one a user reaches for Stop during. Without this race the loop
621
+ * stays parked inside the call for those two minutes with the chat still showing a turn in flight.
622
+ *
623
+ * The losing promise is left running rather than cancelled: the work is usually a job a server is already
624
+ * doing, and throwing away a result that is about to land helps nobody. Both of its outcomes are handled here,
625
+ * so a late failure settles nothing instead of surfacing as an unhandled rejection.
626
+ */
627
+ static #raced<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
628
+ return new Promise<T>((resolve, reject) => {
629
+ const onAbort = () => reject(new Error("The user aborted the turn."));
630
+ work.then(
631
+ (value) => {
632
+ signal.removeEventListener("abort", onAbort);
633
+ resolve(value);
634
+ },
635
+ (error: unknown) => {
636
+ signal.removeEventListener("abort", onAbort);
637
+ reject(error instanceof Error ? error : new Error(String(error)));
638
+ },
639
+ );
640
+ if (signal.aborted) onAbort();
641
+ else signal.addEventListener("abort", onAbort, { once: true });
642
+ });
643
+ }
644
+
645
+ static #confirmMessage(name: string, entry: ToolEntry, args: Record<string, unknown>): string | null {
646
+ const confirm = entry.confirm;
647
+ if (confirm === undefined || confirm === false) return null;
648
+ if (typeof confirm === "string") return confirm;
649
+ const verdict = confirm === true ? true : confirm(args);
650
+ if (verdict === false) return null;
651
+ return verdict === true ? `Run ${name}?` : verdict;
652
+ }
653
+
654
+ static #defaultContext(surface: SurfaceView): ContextBlock[] {
655
+ const { resources, scopes } = surface.snapshot();
656
+ return [
657
+ ...(scopes.length ? [{ kind: "screen", scopes }] : []),
658
+ ...(resources.length ? [{ kind: "resources", resources }] : []),
659
+ ];
660
+ }
661
+
662
+ /** Closes the calls a stopped turn never ran, so the pairing every provider dialect requires still holds. */
663
+ #unanswered(calls: ToolCallRequest[]) {
664
+ if (!calls.length) return;
665
+ this.#append({
666
+ role: "tool",
667
+ toolResults: calls.map((call) => ({ id: call.id, name: call.name, error: Transcript.unanswered })),
668
+ });
669
+ }
670
+
671
+ /** Recorded on the open assistant draft when there is one, so a failed turn reads as that turn failing. */
672
+ #fail(message: string) {
673
+ const last = this.#messages[this.#messages.length - 1];
674
+ if (last?.role === "assistant" && !last.error) this.#patchLast({ error: message });
675
+ else this.#append({ role: "assistant", error: message });
676
+ }
677
+
678
+ #append(message: ChatMessage) {
679
+ this.#messages = [...this.#messages, message];
680
+ this.#notify();
681
+ }
682
+
683
+ #patchLast(patch: Partial<ChatMessage>) {
684
+ const last = this.#messages[this.#messages.length - 1];
685
+ if (!last) return;
686
+ this.#messages = [...this.#messages.slice(0, -1), { ...last, ...patch }];
687
+ this.#notify();
688
+ }
689
+
690
+ #notify() {
691
+ this.#version += 1;
692
+ for (const listener of this.#listeners) listener();
693
+ this.#schedulePersist();
694
+ }
695
+
696
+ /** Debounced: streaming patches the last message on every delta, and a save per delta would thrash storage. */
697
+ #schedulePersist() {
698
+ const history = this.#history;
699
+ if (!history) return;
700
+ if (this.#saveTimer) clearTimeout(this.#saveTimer);
701
+ this.#saveTimer = setTimeout(() => {
702
+ this.#saveTimer = null;
703
+
704
+ this.#saving = this.#saving.then(() => history.save(this.#messages)).catch(() => undefined);
705
+ }, 300);
706
+ }
707
+
708
+ /** Sync for the storage case, a promise for a host that fetches — the constructor takes whichever it gets. */
709
+ static #restored(history: SessionHistory | undefined): ChatMessage[] | Promise<ChatMessage[]> {
710
+ if (!history) return [];
711
+ try {
712
+ const messages = history.load();
713
+ if (messages instanceof Promise) return messages.then(AgentSession.#settled, () => []);
714
+ return AgentSession.#settled(messages);
715
+ } catch {
716
+ return [];
717
+ }
718
+ }
719
+
720
+ static #settled(messages: ChatMessage[] | null): ChatMessage[] {
721
+
722
+ return Array.isArray(messages) ? Transcript.sanitize(messages) : [];
723
+ }
724
+
725
+ /**
726
+ * Lands an async restore, and only into a session nothing has happened to yet: `#version` is still 0 exactly
727
+ * while the transcript is untouched, so a user who sent a message — or cleared the chat — during the fetch keeps
728
+ * what they did. Notifies by hand rather than through `#notify`, which would save the transcript it just loaded.
729
+ */
730
+ async #hydrate(pending: Promise<ChatMessage[]>) {
731
+ let restored: ChatMessage[] = [];
732
+ try {
733
+ restored = await pending;
734
+ } catch {
735
+ }
736
+ this.#restoring = false;
737
+ this.#restore(restored);
738
+ }
739
+
740
+ /**
741
+ * Lands a restore under the one rule — only into a session nothing has happened to yet — and notifies either
742
+ * way, because `isRestoring` may have turned over with it. Notifies by hand rather than through `#notify`,
743
+ * which would save the transcript it has just loaded.
744
+ */
745
+ #restore(restored: ChatMessage[]) {
746
+ if (this.#version === 0 && restored.length) this.#messages = restored;
747
+ this.#version += 1;
748
+ for (const listener of this.#listeners) listener();
749
+ }
750
+ }