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,86 @@
1
+ # The turn wire
2
+
3
+ `httpRunner` speaks this contract. Any backend that answers it can drive an `AgentSession` — the session, the
4
+ tools, and the loop stay in the client; the server serves exactly one stateless model turn per request.
5
+
6
+ ## Request
7
+
8
+ `POST <url>` with `content-type: application/json`:
9
+
10
+ ```jsonc
11
+ {
12
+ "messages": [
13
+ { "role": "user", "text": "Trim the intro scene" },
14
+ { "role": "assistant", "text": "", "toolCalls": [{ "id": "c1", "name": "setSceneSeconds", "args": { "seconds": 4 } }] },
15
+ { "role": "tool", "toolResults": [{ "id": "c1", "name": "setSceneSeconds", "changes": [{ "name": "totalSeconds", "value": 39 }] }] }
16
+ ],
17
+ "tools": [
18
+ {
19
+ "name": "setSceneSeconds",
20
+ "description": "Change this scene's length in seconds",
21
+ "parameters": { "type": "object", "properties": { "seconds": { "type": "number" } }, "required": ["seconds"], "additionalProperties": false },
22
+ "needsConfirm": false
23
+ }
24
+ ],
25
+ "context": [{ "kind": "screen", "scopes": [{ "path": "scene-s1", "label": "Intro", "kind": "scene" }] }],
26
+ "instructions": "You are editing a video project." // optional
27
+ }
28
+ ```
29
+
30
+ - `messages` is the whole transcript in `ChatMessage` shape (`types.ts`). The server maps it to its provider's
31
+ format and maps the answer back; it never executes a tool — `tools` is a schema catalogue, not an offer.
32
+ - A message flagged `"summary": true` stands in for the earlier messages a client-side compaction replaced. It is
33
+ history, not something the user said, so a backend that can frame it as one — a system message — should.
34
+ - **Every `toolCalls` entry is answered by a `toolResults` entry of the same `id`, and every result answers a call
35
+ the request carries.** The client holds that invariant (`Transcript.sanitize`) because provider dialects refuse
36
+ a transcript that breaks it; a backend can map calls to results by id without checking for holes. A call the
37
+ client stopped before running arrives answered with an `error`, not missing.
38
+ - A message may carry `error` — a turn that failed, recorded where every other failure is recorded. No provider
39
+ format has a field for it, so **fold it into the text you send**: an assistant turn that reaches the model
40
+ saying nothing is one the model repeats.
41
+ - `context` blocks are host vocabulary. The server forwards them to the model as data, framed as data.
42
+ - Everything is JSON-serializable by contract; a tool whose `result` is not is the tool's bug.
43
+
44
+ ## Attachments
45
+
46
+ A message may carry files in `attachments` (`MessageAttachment`, `types.ts`) — one of `data` (base64 bytes), `url`,
47
+ or `text` (already-extracted content), plus `name` and `mimeType`:
48
+
49
+ ```jsonc
50
+ { "role": "user", "text": "What does this chart say?",
51
+ "attachments": [{ "name": "q3.png", "mimeType": "image/png", "data": "iVBORw0KG…" }] }
52
+ ```
53
+
54
+ They are content, not instructions, and the server frames them the way it frames `context`. **A backend must not
55
+ silently drop one its model cannot read** — a file the model never saw is a file it invents an answer about. Replace
56
+ it with a note in the message text saying which file was not read and why, so the model can say so and ask for
57
+ another form. `text` is readable by every provider by definition, which is what makes an extracted PDF work against
58
+ a text-only model.
59
+
60
+ Nothing here is stored: the wire carries the bytes for exactly one turn's request.
61
+
62
+ ## Response
63
+
64
+ `200` with a single JSON object:
65
+
66
+ ```jsonc
67
+ {
68
+ "text": "Trimmed. Anything else?", // optional
69
+ "toolCalls": [{ "id": "c2", "name": "renderProject", "args": {} }], // optional
70
+ "stop": "end" // "end" | "toolUse"; defaults from toolCalls
71
+ }
72
+ ```
73
+
74
+ Any non-2xx status is surfaced to the session as one error event and ends the turn; a string `message` or
75
+ `error` field in a JSON body becomes that event's message verbatim, and any other body is not interpreted. A
76
+ message that is a code rather than a sentence may be accompanied by a flat `data` object of strings and numbers —
77
+ the values whoever resolves the code interpolates into its text; a host that does not know the code shows the
78
+ message as it stands.
79
+
80
+ ## Streaming
81
+
82
+ The same endpoint may answer `text/event-stream` instead when the request's `accept` names it: one `RunnerEvent`
83
+ (`types.ts`) JSON object per SSE `data:` line, ending with the `done` event. A failure after the stream opened
84
+ travels as one `error` event — the status line is already gone by then. `httpRunner` sends
85
+ `accept: text/event-stream, application/json` and branches on the response's content type, so a server that never
86
+ streams keeps answering the single JSON object above unchanged.
@@ -0,0 +1,131 @@
1
+ import type { AgentRunner, RunnerEvent, ToolCallRequest } from "./types";
2
+
3
+ export interface HttpRunnerOptions {
4
+ url: string;
5
+ headers?: () => Record<string, string>;
6
+ /** Swap the transport — tests, a framework's own HTTP client, a custom fetch with credentials. */
7
+ fetcher?: typeof fetch;
8
+ }
9
+
10
+ interface TurnAnswer {
11
+ text?: string;
12
+ toolCalls?: ToolCallRequest[];
13
+ stop?: "end" | "toolUse";
14
+ }
15
+
16
+ const eventTypes = new Set(["text", "toolCall", "done", "error"]);
17
+
18
+ const parseFrame = (frame: string): RunnerEvent | null => {
19
+ const data = frame
20
+ .split("\n")
21
+ .filter((line) => line.startsWith("data:"))
22
+ .map((line) => line.slice(5).trim())
23
+ .join("\n");
24
+ if (!data) return null;
25
+ const event = JSON.parse(data) as RunnerEvent;
26
+ return eventTypes.has((event as { type?: string }).type ?? "") ? event : null;
27
+ };
28
+
29
+ /**
30
+ * A manual reader loop rather than for-await: ReadableStream async iteration is still missing from browsers the
31
+ * chat runs in. Breaking out early cancels the stream so the connection is released.
32
+ */
33
+ async function* streamedEvents(body: ReadableStream<Uint8Array>, signal: AbortSignal): AsyncGenerator<RunnerEvent> {
34
+ const reader = body.getReader();
35
+ const decoder = new TextDecoder();
36
+ let buffer = "";
37
+ let ended = false;
38
+ try {
39
+ while (true) {
40
+ const { done, value } = await reader.read();
41
+ if (done) break;
42
+ buffer += decoder.decode(value, { stream: true });
43
+ let cut = buffer.indexOf("\n\n");
44
+ while (cut !== -1) {
45
+ const frame = buffer.slice(0, cut);
46
+ buffer = buffer.slice(cut + 2);
47
+ cut = buffer.indexOf("\n\n");
48
+ const event = parseFrame(frame);
49
+ if (!event) continue;
50
+ yield event;
51
+ if (event.type === "done" || event.type === "error") {
52
+ ended = true;
53
+ return;
54
+ }
55
+ }
56
+ }
57
+ } catch (error) {
58
+ ended = true;
59
+ if (!signal.aborted) yield { type: "error", message: error instanceof Error ? error.message : String(error) };
60
+ return;
61
+ } finally {
62
+ void reader.cancel().catch(() => undefined);
63
+ }
64
+ if (!ended) yield { type: "error", message: "The turn stream ended without a done event." };
65
+ }
66
+
67
+ /** Only a flat record of scalars is forwarded: what a coded message interpolates, never a nested payload. */
68
+ const interpolations = (value: unknown): Record<string, string | number> | undefined => {
69
+ if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
70
+ const entries = Object.entries(value).filter(
71
+ (entry): entry is [string, string | number] => typeof entry[1] === "string" || typeof entry[1] === "number",
72
+ );
73
+ return entries.length ? Object.fromEntries(entries) : undefined;
74
+ };
75
+
76
+ /**
77
+ * The server's own message travels verbatim — it was written for whoever is reading the chat, and a prefix in
78
+ * front of it both reads as two sentences and hides a coded message from the host that would have resolved it.
79
+ * The status stands in only when the body says nothing.
80
+ */
81
+ const turnError = async (response: Response): Promise<RunnerEvent> => {
82
+ const fallback = { type: "error", message: `Agent turn failed: ${response.status}` } as const;
83
+ try {
84
+ const body = (await response.json()) as { message?: unknown; error?: unknown; data?: unknown };
85
+ const message = typeof body.message === "string" ? body.message : typeof body.error === "string" ? body.error : "";
86
+ if (!message) return fallback;
87
+ const data = interpolations(body.data);
88
+ return { type: "error", message, ...(data ? { data } : {}) };
89
+ } catch {
90
+ return fallback;
91
+ }
92
+ };
93
+
94
+ /**
95
+ * The default runner: one stateless POST per assistant turn, negotiated via `accept`. A server that streams
96
+ * answers `text/event-stream` — one `RunnerEvent` JSON per SSE `data:` line, ending with `done` — and one that
97
+ * does not answers the single JSON `TurnAnswer`; both ride the same endpoint and the same request JSON.
98
+ *
99
+ * The wire is documented in WIRE.md so any backend can serve it.
100
+ */
101
+ export const httpRunner = ({ url, headers, fetcher }: HttpRunnerOptions): AgentRunner => ({
102
+ async *run(request) {
103
+ const response = await (fetcher ?? fetch)(url, {
104
+ method: "POST",
105
+ headers: {
106
+ "content-type": "application/json",
107
+ accept: "text/event-stream, application/json",
108
+ ...(headers?.() ?? {}),
109
+ },
110
+ body: JSON.stringify({
111
+ messages: request.messages,
112
+ tools: request.tools,
113
+ context: request.context,
114
+ ...(request.instructions ? { instructions: request.instructions } : {}),
115
+ }),
116
+ signal: request.signal,
117
+ });
118
+ if (!response.ok) {
119
+ yield await turnError(response);
120
+ return;
121
+ }
122
+ if (response.headers.get("content-type")?.includes("text/event-stream") && response.body) {
123
+ yield* streamedEvents(response.body, request.signal);
124
+ return;
125
+ }
126
+ const turn = (await response.json()) as TurnAnswer;
127
+ if (turn.text) yield { type: "text", delta: turn.text };
128
+ for (const call of turn.toolCalls ?? []) yield { type: "toolCall", id: call.id, name: call.name, args: call.args };
129
+ yield { type: "done", stop: turn.stop ?? (turn.toolCalls?.length ? "toolUse" : "end") };
130
+ },
131
+ });
@@ -0,0 +1,20 @@
1
+ "use client";
2
+ export * from "./AgentAbort";
3
+ export * from "./Agentic";
4
+ export * from "./AgenticSurface";
5
+ export * from "./AgentProgress";
6
+ export * from "./AgentProvider";
7
+ export * from "./AgentScope";
8
+ export * from "./AgentSession";
9
+ export * from "./Compaction";
10
+ export * from "./httpRunner";
11
+ export * from "./sharedContext";
12
+ export * from "./surfaceContext";
13
+ export * from "./ToolOutput";
14
+ export * from "./Transcript";
15
+ export * from "./types";
16
+ export * from "./useAgent";
17
+ export * from "./useAgentGuide";
18
+ export * from "./useAgentResource";
19
+ export * from "./useAgentState";
20
+ export * from "./useAgentTool";
@@ -0,0 +1,25 @@
1
+ "use client";
2
+ import { type Context, createContext } from "react";
3
+
4
+ /**
5
+ * A React context interned on `globalThis`, for the reason `AgenticSurface.shared` is: an app does not get one
6
+ * copy of this package. An akan build inlines it into every client bundle that reaches it — four of them in this
7
+ * repo's own docs app — and a context is identified by object identity, so a `ScopeContext.Provider` rendered by
8
+ * `Agent.Zone` in one copy is invisible to the `st.tool` reading it from another.
9
+ *
10
+ * That failure is silent, which is what makes it worth a global: the read falls back to the context's default, so
11
+ * the tool registers at the root scope instead of the zone's, the zone session filters it out as belonging to a
12
+ * different view, and the model is handed the built-ins with nothing thrown and nothing logged.
13
+ *
14
+ * Every context this package owns goes through here. Adding one the plain way would work in the monorepo — one
15
+ * copy, one object — and fail only once bundled, which is exactly the bug this replaced.
16
+ */
17
+ export const sharedContext = <T>(name: string, initial: T): Context<T> => {
18
+ const key = Symbol.for(`useAgentic.context.${name}`);
19
+ const holder = globalThis as typeof globalThis & { [slot: symbol]: Context<T> | undefined };
20
+ const existing = holder[key];
21
+ if (existing) return existing;
22
+ const created = createContext(initial);
23
+ holder[key] = created;
24
+ return created;
25
+ };
@@ -0,0 +1,10 @@
1
+ "use client";
2
+ import { useContext } from "react";
3
+ import { AgenticSurface } from "./AgenticSurface";
4
+ import { sharedContext } from "./sharedContext";
5
+
6
+ export const SurfaceContext = sharedContext<AgenticSurface | null>("surface", null);
7
+ export const ScopeContext = sharedContext<string[]>("scope", []);
8
+
9
+ export const useSurface = () => useContext(SurfaceContext) ?? AgenticSurface.shared;
10
+ export const useScopePath = () => useContext(ScopeContext);
@@ -0,0 +1,192 @@
1
+ export type JsonSchema = Record<string, unknown>;
2
+
3
+ /** `true` asks with a default message, a string is the message, a function decides from the arguments. */
4
+ export type ToolConfirm = boolean | string | ((args: Record<string, unknown>) => string | boolean);
5
+
6
+ /** Re-checked at the moment of execution; a string is the refusal reason the agent reads. */
7
+ export type ToolGuard = (args: Record<string, unknown>) => true | string;
8
+
9
+ export interface ToolEntry {
10
+ name: string;
11
+ description?: string;
12
+ parameters?: JsonSchema;
13
+ /**
14
+ * Whether a call has to be waited out before its effect on the screen is reported. `false` is a read that
15
+ * returns what is already there; the default waits, because a write may still be landing when `run` resolves.
16
+ */
17
+ settle?: boolean;
18
+ confirm?: ToolConfirm;
19
+ guard?: ToolGuard;
20
+ run: (args: Record<string, unknown>) => unknown;
21
+ }
22
+
23
+ /** One call an agent made through the surface, in the order it made them. */
24
+ export interface AgentCall {
25
+ name: string;
26
+ args: Record<string, unknown>;
27
+ at: Date;
28
+ error?: string;
29
+ }
30
+
31
+ export interface ResourceEntry {
32
+ name: string;
33
+ description?: string;
34
+ /** `false` keeps it out of post-call diff reports — for values that change on their own every second. */
35
+ report?: boolean;
36
+ read: () => unknown;
37
+ }
38
+
39
+ export interface ScopeEntry {
40
+ id: string;
41
+ label?: string;
42
+ kind?: string;
43
+ }
44
+
45
+ /**
46
+ * A bulk contributor of entries whose names are already full — how a host store joins the surface. `view` is the
47
+ * scope path a zone session reads through; a source that ignores it contributes the same entries to every view.
48
+ */
49
+ export interface SurfaceSource {
50
+ tools?: (view?: string[]) => ToolEntry[];
51
+ resources?: (view?: string[]) => ResourceEntry[];
52
+ subscribe?: (listener: () => void) => () => void;
53
+ }
54
+
55
+ /**
56
+ * The reading half of a surface — what a session consumes. `AgenticSurface` is one; `surface.view(path)` answers a
57
+ * zone-scoped one over the same registry, so zones are views of the screen, never walls between its parts.
58
+ */
59
+ export interface SurfaceView {
60
+ snapshot(): SurfaceSnapshot;
61
+ tool(name: string): ToolEntry | null;
62
+ call(name: string, args?: Record<string, unknown>): Promise<unknown>;
63
+ read(name: string): unknown;
64
+ diffSince(before: SurfaceSnapshot): ResourceDiff[];
65
+ subscribe(listener: () => void): () => void;
66
+ }
67
+
68
+ export interface PublishedTool {
69
+ name: string;
70
+ description?: string;
71
+ parameters?: JsonSchema;
72
+ needsConfirm: boolean;
73
+ }
74
+
75
+ export interface PublishedResource {
76
+ name: string;
77
+ description?: string;
78
+ value?: unknown;
79
+ error?: string;
80
+ }
81
+
82
+ export interface PublishedScope {
83
+ path: string;
84
+ label?: string;
85
+ kind?: string;
86
+ }
87
+
88
+ export interface SurfaceSnapshot {
89
+ tools: PublishedTool[];
90
+ resources: PublishedResource[];
91
+ scopes: PublishedScope[];
92
+ /** Standing guidance texts, in registration order. Folded into the turn's instructions, not into context. */
93
+ guides: string[];
94
+ }
95
+
96
+ export interface ResourceDiff {
97
+ name: string;
98
+ value?: unknown;
99
+ error?: string;
100
+ removed?: boolean;
101
+ }
102
+
103
+ export type ChatRole = "user" | "assistant" | "tool";
104
+
105
+ export interface ToolCallRequest {
106
+ id: string;
107
+ name: string;
108
+ args: Record<string, unknown>;
109
+ }
110
+
111
+ export interface ToolCallResult {
112
+ id: string;
113
+ name: string;
114
+ /** What `run` returned. Must be JSON-serializable — it rides the wire back to the model. */
115
+ result?: unknown;
116
+ /** What the call changed on the surface — the whole report for a tool that returns nothing. */
117
+ changes?: ResourceDiff[];
118
+ error?: string;
119
+ }
120
+
121
+ /**
122
+ * A file the user handed the conversation rather than the screen — which is why it rides a message instead of a
123
+ * tool, the same reason `askUser` belongs to the session and not to the surface.
124
+ *
125
+ * Three carriers, one of which every attachment must have: `data` inlines the bytes, `url` points at something the
126
+ * provider can fetch, and `text` is content somebody already extracted — the only form a text-only model can read.
127
+ * They mirror what the server's own `Msg.image` / `Msg.link` / `Msg.resource` builders produce, so a prompt's
128
+ * attachment and a user's are the same thing on the wire.
129
+ *
130
+ * Whether a given carrier reaches the model is the provider's answer, not this type's: a backend drops what its
131
+ * model cannot read and says so in the transcript, because a silently dropped file is one the model then
132
+ * hallucinates about.
133
+ */
134
+ export interface MessageAttachment {
135
+ name: string;
136
+ mimeType: string;
137
+ /** Base64, with no `data:` prefix. */
138
+ data?: string;
139
+ url?: string;
140
+ text?: string;
141
+ }
142
+
143
+ export interface ChatMessage {
144
+ role: ChatRole;
145
+ text?: string;
146
+ /** Files the message carries. Content, not instructions — a backend frames them the way it frames context. */
147
+ attachments?: MessageAttachment[];
148
+ toolCalls?: ToolCallRequest[];
149
+ toolResults?: ToolCallResult[];
150
+ /** A failed or capped turn, recorded in the transcript rather than thrown past it. */
151
+ error?: string;
152
+ /**
153
+ * Host-rendered and never sent: a command's own output belongs in the transcript the user reads but not in the
154
+ * history the model reads, which would take it for something it had said itself.
155
+ */
156
+ local?: boolean;
157
+ /**
158
+ * Stands in for the messages compaction replaced. It rides the wire like any other message — it is what the
159
+ * model now remembers of them — but it is not something the user said, so a backend frames it as a summary and
160
+ * a host renders it as one.
161
+ */
162
+ summary?: boolean;
163
+ }
164
+
165
+ /** One block of screen context the host assembles per turn. `kind` is the host's vocabulary; the wire forwards it verbatim. */
166
+ export interface ContextBlock {
167
+ kind: string;
168
+ [key: string]: unknown;
169
+ }
170
+
171
+ export type RunnerEvent =
172
+ | { type: "text"; delta: string }
173
+ | { type: "toolCall"; id: string; name: string; args: Record<string, unknown> }
174
+ | { type: "done"; stop: "end" | "toolUse" }
175
+ /**
176
+ * `data` accompanies a message that is a code rather than a sentence — the values whoever resolves the code
177
+ * interpolates into its text. A host that does not know the code shows the message as it stands.
178
+ */
179
+ | { type: "error"; message: string; data?: Record<string, string | number> };
180
+
181
+ export interface RunnerRequest {
182
+ messages: ChatMessage[];
183
+ tools: PublishedTool[];
184
+ context: ContextBlock[];
185
+ instructions?: string;
186
+ signal: AbortSignal;
187
+ }
188
+
189
+ /** One model turn: request in, streamed events out. Where the loop runs is the implementation's business. */
190
+ export interface AgentRunner {
191
+ run: (request: RunnerRequest) => AsyncIterable<RunnerEvent>;
192
+ }
@@ -0,0 +1,18 @@
1
+ "use client";
2
+ import { useContext, useSyncExternalStore } from "react";
3
+ import type { AgentSession } from "./AgentSession";
4
+ import { sharedContext } from "./sharedContext";
5
+
6
+ export const SessionContext = sharedContext<AgentSession | null>("session", null);
7
+
8
+ /** The enclosing session, re-rendering on every session change. `send`/`abort` are safe to destructure. */
9
+ export const useAgent = (): AgentSession => {
10
+ const session = useContext(SessionContext);
11
+ if (!session) throw new Error("useAgent needs an AgentProvider with a session or a runner.");
12
+ useSyncExternalStore(
13
+ session.subscribe,
14
+ () => session.version,
15
+ () => session.version,
16
+ );
17
+ return session;
18
+ };
@@ -0,0 +1,16 @@
1
+ "use client";
2
+ import { useEffect, useRef } from "react";
3
+ import { useScopePath, useSurface } from "./surfaceContext";
4
+
5
+ /**
6
+ * Registers standing guidance for the agent while the component is mounted. Guidance is folded into the turn's
7
+ * instructions — it directs the model, unlike context, which is framed as data. The text is captured at mount
8
+ * like every declaration on the surface; remount to change it.
9
+ */
10
+ export const useAgentGuide = (text: string): void => {
11
+ const surface = useSurface();
12
+ const scope = useScopePath();
13
+ const captured = useRef(text);
14
+ const scopeKey = scope.join(".");
15
+ useEffect(() => surface.registerGuide(scope, captured.current), [surface, scopeKey]);
16
+ };
@@ -0,0 +1,36 @@
1
+ "use client";
2
+ import { useEffect, useRef } from "react";
3
+ import { useScopePath, useSurface } from "./surfaceContext";
4
+
5
+ export interface AgentResourceMeta {
6
+ description?: string;
7
+ serialize?: (value: unknown) => unknown;
8
+ report?: boolean;
9
+ }
10
+
11
+ /**
12
+ * Publishes a read-only view of any value the component already holds — derived totals, statuses, labels.
13
+ *
14
+ * A falsy name declares nothing: hooks run either way, so a component whose publication is conditional keeps a
15
+ * constant hook count instead of branching around the call.
16
+ */
17
+ export const useAgentResource = (name: string | null, value: unknown, meta: AgentResourceMeta = {}): void => {
18
+ const surface = useSurface();
19
+ const scope = useScopePath();
20
+ const live = useRef({ value, meta });
21
+ live.current = { value, meta };
22
+ const scopeKey = scope.join(".");
23
+ useEffect(() => {
24
+ if (!name) return;
25
+ const { meta: declared } = live.current;
26
+ return surface.registerResource(scope, {
27
+ name,
28
+ description: declared.description,
29
+ report: declared.report,
30
+ read: () => {
31
+ const { value: current, meta: currentMeta } = live.current;
32
+ return currentMeta.serialize ? currentMeta.serialize(current) : current;
33
+ },
34
+ });
35
+ }, [surface, scopeKey, name]);
36
+ };
@@ -0,0 +1,64 @@
1
+ "use client";
2
+ import { type Dispatch, type SetStateAction, useEffect, useRef, useState } from "react";
3
+ import { useScopePath, useSurface } from "./surfaceContext";
4
+ import type { JsonSchema } from "./types";
5
+
6
+ export interface AgentStateMeta<T> {
7
+ description?: string;
8
+ serialize?: (value: T) => unknown;
9
+ report?: boolean;
10
+ /** Schema of the setter's `value` argument. Without it the state is published read-only. */
11
+ set?: JsonSchema;
12
+ /** Validates or coerces the setter's incoming `value` — throw to refuse the write. Nothing else enforces `set`. */
13
+ parse?: (value: unknown) => T;
14
+ }
15
+
16
+ /**
17
+ * `useState` the agent can read — and write only through a named setter tool, and only when `set` declares one.
18
+ * A falsy name keeps the state and publishes nothing, so a conditional surface never changes the hook count.
19
+ */
20
+ export const useAgentState = <T>(
21
+ name: string | null,
22
+ initial: T | (() => T),
23
+ meta: AgentStateMeta<T> = {},
24
+ ): [T, Dispatch<SetStateAction<T>>] => {
25
+ const surface = useSurface();
26
+ const scope = useScopePath();
27
+ const [value, setValue] = useState(initial);
28
+ const live = useRef({ value, meta });
29
+ live.current = { value, meta };
30
+ const scopeKey = scope.join(".");
31
+ useEffect(() => {
32
+ if (!name) return;
33
+ const { meta: declared } = live.current;
34
+ return surface.registerResource(scope, {
35
+ name,
36
+ description: declared.description,
37
+ report: declared.report,
38
+ read: () => {
39
+ const { value: current, meta: currentMeta } = live.current;
40
+ return currentMeta.serialize ? currentMeta.serialize(current) : current;
41
+ },
42
+ });
43
+ }, [surface, scopeKey, name]);
44
+ const writable = !!meta.set;
45
+ useEffect(() => {
46
+ const { meta: declared } = live.current;
47
+ if (!name || !declared.set) return;
48
+ return surface.registerTool(scope, {
49
+ name: `set${name.charAt(0).toUpperCase()}${name.slice(1)}`,
50
+ description: `Set ${name}.${declared.description ? ` ${declared.description}` : ""}`,
51
+ parameters: {
52
+ type: "object",
53
+ properties: { value: declared.set },
54
+ required: ["value"],
55
+ additionalProperties: false,
56
+ },
57
+ run: (args) => {
58
+ const parse = live.current.meta.parse;
59
+ setValue(parse ? parse(args.value) : (args.value as T));
60
+ },
61
+ });
62
+ }, [surface, scopeKey, name, writable]);
63
+ return [value, setValue];
64
+ };
@@ -0,0 +1,55 @@
1
+ "use client";
2
+ import { useEffect, useRef } from "react";
3
+ import { useScopePath, useSurface } from "./surfaceContext";
4
+ import type { JsonSchema, ToolConfirm, ToolGuard } from "./types";
5
+
6
+ export interface AgentToolMeta {
7
+ description?: string;
8
+ parameters?: JsonSchema;
9
+ settle?: boolean;
10
+ confirm?: ToolConfirm;
11
+ guard?: ToolGuard;
12
+ }
13
+
14
+ /**
15
+ * Publishes one tool for as long as the component is mounted.
16
+ *
17
+ * Identity is the scoped name, not the callback — `run`, `guard`, and `confirm` read the latest render through a
18
+ * ref, so there is no dependency array and no stale closure for the agent to hit. `description` and `parameters`
19
+ * are declaration data, read once at mount.
20
+ */
21
+ export const useAgentTool = <Args extends Record<string, unknown> = Record<string, unknown>, Result = unknown>(
22
+ name: string,
23
+ meta: AgentToolMeta,
24
+ run: (args: Args) => Result | Promise<Result>,
25
+ ): ((args?: Args) => Promise<Result>) => {
26
+ const surface = useSurface();
27
+ const scope = useScopePath();
28
+ const live = useRef({ meta, run });
29
+ live.current = { meta, run };
30
+ const call = useRef<((args?: Args) => Promise<Result>) | null>(null);
31
+ if (!call.current) call.current = async (args = {} as Args) => await live.current.run(args);
32
+ const scopeKey = scope.join(".");
33
+ useEffect(() => {
34
+ const { meta: declared } = live.current;
35
+ return surface.registerTool(scope, {
36
+ name,
37
+ description: declared.description,
38
+ parameters: declared.parameters,
39
+ settle: declared.settle,
40
+ ...(declared.confirm === undefined
41
+ ? {}
42
+ : {
43
+ confirm: (args: Record<string, unknown>) => {
44
+ const confirm = live.current.meta.confirm;
45
+ return typeof confirm === "function" ? confirm(args) : (confirm ?? false);
46
+ },
47
+ }),
48
+ ...(declared.guard === undefined
49
+ ? {}
50
+ : { guard: (args: Record<string, unknown>) => live.current.meta.guard?.(args) ?? true }),
51
+ run: (args) => live.current.run(args as Args),
52
+ });
53
+ }, [surface, scopeKey, name]);
54
+ return call.current;
55
+ };