@falai/agent 3.4.5 → 4.0.0-alpha.10

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 (865) hide show
  1. package/README.md +41 -34
  2. package/dist/cjs/core/Agent.d.ts +29 -378
  3. package/dist/cjs/core/Agent.d.ts.map +1 -1
  4. package/dist/cjs/core/Agent.js +113 -1178
  5. package/dist/cjs/core/Agent.js.map +1 -1
  6. package/dist/cjs/core/CompactionEngine.d.ts.map +1 -1
  7. package/dist/cjs/core/CompactionEngine.js +5 -3
  8. package/dist/cjs/core/CompactionEngine.js.map +1 -1
  9. package/dist/cjs/core/FlowSpec.d.ts +136 -0
  10. package/dist/cjs/core/FlowSpec.d.ts.map +1 -0
  11. package/dist/cjs/core/FlowSpec.js +573 -0
  12. package/dist/cjs/core/FlowSpec.js.map +1 -0
  13. package/dist/cjs/core/Migrate.d.ts +38 -0
  14. package/dist/cjs/core/Migrate.d.ts.map +1 -0
  15. package/dist/cjs/core/Migrate.js +270 -0
  16. package/dist/cjs/core/Migrate.js.map +1 -0
  17. package/dist/cjs/core/Prompt.d.ts +54 -0
  18. package/dist/cjs/core/Prompt.d.ts.map +1 -0
  19. package/dist/cjs/core/Prompt.js +149 -0
  20. package/dist/cjs/core/Prompt.js.map +1 -0
  21. package/dist/cjs/core/Runner.d.ts +171 -0
  22. package/dist/cjs/core/Runner.d.ts.map +1 -0
  23. package/dist/cjs/core/Runner.js +1158 -0
  24. package/dist/cjs/core/Runner.js.map +1 -0
  25. package/dist/cjs/core/Speak.d.ts +37 -0
  26. package/dist/cjs/core/Speak.d.ts.map +1 -0
  27. package/dist/cjs/core/Speak.js +373 -0
  28. package/dist/cjs/core/Speak.js.map +1 -0
  29. package/dist/cjs/core/Understand.d.ts +28 -0
  30. package/dist/cjs/core/Understand.d.ts.map +1 -0
  31. package/dist/cjs/core/Understand.js +357 -0
  32. package/dist/cjs/core/Understand.js.map +1 -0
  33. package/dist/cjs/core/contracts.d.ts +122 -0
  34. package/dist/cjs/core/contracts.d.ts.map +1 -0
  35. package/dist/cjs/core/contracts.js +11 -0
  36. package/dist/cjs/core/contracts.js.map +1 -0
  37. package/dist/cjs/core/falai.d.ts +57 -0
  38. package/dist/cjs/core/falai.d.ts.map +1 -0
  39. package/dist/cjs/core/falai.js +43 -0
  40. package/dist/cjs/core/falai.js.map +1 -0
  41. package/dist/cjs/core/predicate.d.ts +9 -0
  42. package/dist/cjs/core/predicate.d.ts.map +1 -0
  43. package/dist/cjs/core/predicate.js +58 -0
  44. package/dist/cjs/core/predicate.js.map +1 -0
  45. package/dist/cjs/index.d.ts +26 -31
  46. package/dist/cjs/index.d.ts.map +1 -1
  47. package/dist/cjs/index.js +46 -68
  48. package/dist/cjs/index.js.map +1 -1
  49. package/dist/cjs/persistence/MemoryStore.d.ts +15 -0
  50. package/dist/cjs/persistence/MemoryStore.d.ts.map +1 -0
  51. package/dist/cjs/persistence/MemoryStore.js +39 -0
  52. package/dist/cjs/persistence/MemoryStore.js.map +1 -0
  53. package/dist/cjs/persistence/MongoStore.d.ts +42 -0
  54. package/dist/cjs/persistence/MongoStore.d.ts.map +1 -0
  55. package/dist/cjs/persistence/MongoStore.js +60 -0
  56. package/dist/cjs/persistence/MongoStore.js.map +1 -0
  57. package/dist/cjs/persistence/OpenSearchStore.d.ts +86 -0
  58. package/dist/cjs/persistence/OpenSearchStore.d.ts.map +1 -0
  59. package/dist/cjs/persistence/OpenSearchStore.js +120 -0
  60. package/dist/cjs/persistence/OpenSearchStore.js.map +1 -0
  61. package/dist/cjs/persistence/PostgresStore.d.ts +41 -0
  62. package/dist/cjs/persistence/PostgresStore.d.ts.map +1 -0
  63. package/dist/cjs/persistence/PostgresStore.js +58 -0
  64. package/dist/cjs/persistence/PostgresStore.js.map +1 -0
  65. package/dist/cjs/persistence/PrismaStore.d.ts +65 -0
  66. package/dist/cjs/persistence/PrismaStore.d.ts.map +1 -0
  67. package/dist/cjs/persistence/PrismaStore.js +95 -0
  68. package/dist/cjs/persistence/PrismaStore.js.map +1 -0
  69. package/dist/cjs/persistence/RedisStore.d.ts +34 -0
  70. package/dist/cjs/persistence/RedisStore.d.ts.map +1 -0
  71. package/dist/cjs/persistence/RedisStore.js +61 -0
  72. package/dist/cjs/persistence/RedisStore.js.map +1 -0
  73. package/dist/cjs/persistence/SQLiteStore.d.ts +45 -0
  74. package/dist/cjs/persistence/SQLiteStore.d.ts.map +1 -0
  75. package/dist/cjs/persistence/SQLiteStore.js +74 -0
  76. package/dist/cjs/persistence/SQLiteStore.js.map +1 -0
  77. package/dist/cjs/persistence/sessionRow.d.ts +14 -0
  78. package/dist/cjs/persistence/sessionRow.d.ts.map +1 -0
  79. package/dist/cjs/persistence/sessionRow.js +50 -0
  80. package/dist/cjs/persistence/sessionRow.js.map +1 -0
  81. package/dist/cjs/providers/DeepSeekProvider.d.ts.map +1 -1
  82. package/dist/cjs/providers/DeepSeekProvider.js +8 -3
  83. package/dist/cjs/providers/DeepSeekProvider.js.map +1 -1
  84. package/dist/cjs/providers/GeminiProvider.d.ts +4 -3
  85. package/dist/cjs/providers/GeminiProvider.d.ts.map +1 -1
  86. package/dist/cjs/providers/GeminiProvider.js +4 -3
  87. package/dist/cjs/providers/GeminiProvider.js.map +1 -1
  88. package/dist/cjs/providers/OpenAICompatibleProvider.d.ts +4 -0
  89. package/dist/cjs/providers/OpenAICompatibleProvider.d.ts.map +1 -1
  90. package/dist/cjs/providers/OpenAICompatibleProvider.js +2 -0
  91. package/dist/cjs/providers/OpenAICompatibleProvider.js.map +1 -1
  92. package/dist/cjs/providers/OpenRouterProvider.d.ts.map +1 -1
  93. package/dist/cjs/providers/OpenRouterProvider.js +2 -4
  94. package/dist/cjs/providers/OpenRouterProvider.js.map +1 -1
  95. package/dist/cjs/providers/ProviderAdapter.d.ts +11 -6
  96. package/dist/cjs/providers/ProviderAdapter.d.ts.map +1 -1
  97. package/dist/cjs/providers/ProviderAdapter.js +33 -10
  98. package/dist/cjs/providers/ProviderAdapter.js.map +1 -1
  99. package/dist/cjs/providers/ZaiProvider.d.ts +6 -4
  100. package/dist/cjs/providers/ZaiProvider.d.ts.map +1 -1
  101. package/dist/cjs/providers/ZaiProvider.js +6 -4
  102. package/dist/cjs/providers/ZaiProvider.js.map +1 -1
  103. package/dist/cjs/types/agent.d.ts +163 -383
  104. package/dist/cjs/types/agent.d.ts.map +1 -1
  105. package/dist/cjs/types/agent.js +1 -1
  106. package/dist/cjs/types/ai.d.ts +32 -1
  107. package/dist/cjs/types/ai.d.ts.map +1 -1
  108. package/dist/cjs/types/compaction.d.ts +3 -1
  109. package/dist/cjs/types/compaction.d.ts.map +1 -1
  110. package/dist/cjs/types/errors.d.ts +9 -12
  111. package/dist/cjs/types/errors.d.ts.map +1 -1
  112. package/dist/cjs/types/errors.js +14 -17
  113. package/dist/cjs/types/errors.js.map +1 -1
  114. package/dist/cjs/types/flow.d.ts +265 -513
  115. package/dist/cjs/types/flow.d.ts.map +1 -1
  116. package/dist/cjs/types/flow.js +7 -1
  117. package/dist/cjs/types/flow.js.map +1 -1
  118. package/dist/cjs/types/history.d.ts +7 -18
  119. package/dist/cjs/types/history.d.ts.map +1 -1
  120. package/dist/cjs/types/history.js.map +1 -1
  121. package/dist/cjs/types/index.d.ts +9 -15
  122. package/dist/cjs/types/index.d.ts.map +1 -1
  123. package/dist/cjs/types/index.js +4 -14
  124. package/dist/cjs/types/index.js.map +1 -1
  125. package/dist/cjs/types/session.d.ts +94 -64
  126. package/dist/cjs/types/session.d.ts.map +1 -1
  127. package/dist/cjs/types/session.js +5 -1
  128. package/dist/cjs/types/session.js.map +1 -1
  129. package/dist/cjs/types/tool.d.ts +37 -207
  130. package/dist/cjs/types/tool.d.ts.map +1 -1
  131. package/dist/cjs/types/tool.js +5 -14
  132. package/dist/cjs/types/tool.js.map +1 -1
  133. package/dist/cjs/utils/clock.d.ts +28 -0
  134. package/dist/cjs/utils/clock.d.ts.map +1 -0
  135. package/dist/cjs/utils/clock.js +64 -0
  136. package/dist/cjs/utils/clock.js.map +1 -0
  137. package/dist/cjs/utils/duration.d.ts +11 -0
  138. package/dist/cjs/utils/duration.d.ts.map +1 -0
  139. package/dist/cjs/utils/duration.js +31 -0
  140. package/dist/cjs/utils/duration.js.map +1 -0
  141. package/dist/cjs/utils/history.d.ts +4 -1
  142. package/dist/cjs/utils/history.d.ts.map +1 -1
  143. package/dist/cjs/utils/history.js +2 -2
  144. package/dist/cjs/utils/history.js.map +1 -1
  145. package/dist/cjs/utils/index.d.ts +4 -10
  146. package/dist/cjs/utils/index.d.ts.map +1 -1
  147. package/dist/cjs/utils/index.js +14 -61
  148. package/dist/cjs/utils/index.js.map +1 -1
  149. package/dist/cjs/utils/json.d.ts +2 -0
  150. package/dist/cjs/utils/json.d.ts.map +1 -1
  151. package/dist/cjs/utils/json.js +5 -0
  152. package/dist/cjs/utils/json.js.map +1 -1
  153. package/dist/cjs/utils/outcomes.d.ts +48 -0
  154. package/dist/cjs/utils/outcomes.d.ts.map +1 -0
  155. package/dist/cjs/utils/outcomes.js +51 -0
  156. package/dist/cjs/utils/outcomes.js.map +1 -0
  157. package/dist/cjs/utils/phrases.d.ts +25 -0
  158. package/dist/cjs/utils/phrases.d.ts.map +1 -0
  159. package/dist/cjs/utils/phrases.js +38 -0
  160. package/dist/cjs/utils/phrases.js.map +1 -0
  161. package/dist/cjs/utils/schema.d.ts +50 -0
  162. package/dist/cjs/utils/schema.d.ts.map +1 -0
  163. package/dist/cjs/utils/schema.js +138 -0
  164. package/dist/cjs/utils/schema.js.map +1 -0
  165. package/dist/cjs/utils/streamingMessage.d.ts +3 -2
  166. package/dist/cjs/utils/streamingMessage.d.ts.map +1 -1
  167. package/dist/cjs/utils/streamingMessage.js +38 -4
  168. package/dist/cjs/utils/streamingMessage.js.map +1 -1
  169. package/dist/cjs/utils/template.d.ts +22 -150
  170. package/dist/cjs/utils/template.d.ts.map +1 -1
  171. package/dist/cjs/utils/template.js +64 -359
  172. package/dist/cjs/utils/template.js.map +1 -1
  173. package/dist/cjs/utils/usage.d.ts +19 -0
  174. package/dist/cjs/utils/usage.d.ts.map +1 -0
  175. package/dist/cjs/utils/usage.js +35 -0
  176. package/dist/cjs/utils/usage.js.map +1 -0
  177. package/dist/core/Agent.d.ts +29 -378
  178. package/dist/core/Agent.d.ts.map +1 -1
  179. package/dist/core/Agent.js +116 -1181
  180. package/dist/core/Agent.js.map +1 -1
  181. package/dist/core/CompactionEngine.d.ts.map +1 -1
  182. package/dist/core/CompactionEngine.js +5 -3
  183. package/dist/core/CompactionEngine.js.map +1 -1
  184. package/dist/core/FlowSpec.d.ts +136 -0
  185. package/dist/core/FlowSpec.d.ts.map +1 -0
  186. package/dist/core/FlowSpec.js +567 -0
  187. package/dist/core/FlowSpec.js.map +1 -0
  188. package/dist/core/Migrate.d.ts +38 -0
  189. package/dist/core/Migrate.d.ts.map +1 -0
  190. package/dist/core/Migrate.js +264 -0
  191. package/dist/core/Migrate.js.map +1 -0
  192. package/dist/core/Prompt.d.ts +54 -0
  193. package/dist/core/Prompt.d.ts.map +1 -0
  194. package/dist/core/Prompt.js +139 -0
  195. package/dist/core/Prompt.js.map +1 -0
  196. package/dist/core/Runner.d.ts +171 -0
  197. package/dist/core/Runner.d.ts.map +1 -0
  198. package/dist/core/Runner.js +1154 -0
  199. package/dist/core/Runner.js.map +1 -0
  200. package/dist/core/Speak.d.ts +37 -0
  201. package/dist/core/Speak.d.ts.map +1 -0
  202. package/dist/core/Speak.js +369 -0
  203. package/dist/core/Speak.js.map +1 -0
  204. package/dist/core/Understand.d.ts +28 -0
  205. package/dist/core/Understand.d.ts.map +1 -0
  206. package/dist/core/Understand.js +353 -0
  207. package/dist/core/Understand.js.map +1 -0
  208. package/dist/core/contracts.d.ts +122 -0
  209. package/dist/core/contracts.d.ts.map +1 -0
  210. package/dist/core/contracts.js +10 -0
  211. package/dist/core/contracts.js.map +1 -0
  212. package/dist/core/falai.d.ts +57 -0
  213. package/dist/core/falai.d.ts.map +1 -0
  214. package/dist/core/falai.js +40 -0
  215. package/dist/core/falai.js.map +1 -0
  216. package/dist/core/predicate.d.ts +9 -0
  217. package/dist/core/predicate.d.ts.map +1 -0
  218. package/dist/core/predicate.js +54 -0
  219. package/dist/core/predicate.js.map +1 -0
  220. package/dist/index.d.ts +26 -31
  221. package/dist/index.d.ts.map +1 -1
  222. package/dist/index.js +19 -24
  223. package/dist/index.js.map +1 -1
  224. package/dist/persistence/MemoryStore.d.ts +15 -0
  225. package/dist/persistence/MemoryStore.d.ts.map +1 -0
  226. package/dist/persistence/MemoryStore.js +35 -0
  227. package/dist/persistence/MemoryStore.js.map +1 -0
  228. package/dist/persistence/MongoStore.d.ts +42 -0
  229. package/dist/persistence/MongoStore.d.ts.map +1 -0
  230. package/dist/persistence/MongoStore.js +56 -0
  231. package/dist/persistence/MongoStore.js.map +1 -0
  232. package/dist/persistence/OpenSearchStore.d.ts +86 -0
  233. package/dist/persistence/OpenSearchStore.d.ts.map +1 -0
  234. package/dist/persistence/OpenSearchStore.js +116 -0
  235. package/dist/persistence/OpenSearchStore.js.map +1 -0
  236. package/dist/persistence/PostgresStore.d.ts +41 -0
  237. package/dist/persistence/PostgresStore.d.ts.map +1 -0
  238. package/dist/persistence/PostgresStore.js +54 -0
  239. package/dist/persistence/PostgresStore.js.map +1 -0
  240. package/dist/persistence/PrismaStore.d.ts +65 -0
  241. package/dist/persistence/PrismaStore.d.ts.map +1 -0
  242. package/dist/persistence/PrismaStore.js +91 -0
  243. package/dist/persistence/PrismaStore.js.map +1 -0
  244. package/dist/persistence/RedisStore.d.ts +34 -0
  245. package/dist/persistence/RedisStore.d.ts.map +1 -0
  246. package/dist/persistence/RedisStore.js +57 -0
  247. package/dist/persistence/RedisStore.js.map +1 -0
  248. package/dist/persistence/SQLiteStore.d.ts +45 -0
  249. package/dist/persistence/SQLiteStore.d.ts.map +1 -0
  250. package/dist/persistence/SQLiteStore.js +70 -0
  251. package/dist/persistence/SQLiteStore.js.map +1 -0
  252. package/dist/persistence/sessionRow.d.ts +14 -0
  253. package/dist/persistence/sessionRow.d.ts.map +1 -0
  254. package/dist/persistence/sessionRow.js +45 -0
  255. package/dist/persistence/sessionRow.js.map +1 -0
  256. package/dist/providers/DeepSeekProvider.d.ts.map +1 -1
  257. package/dist/providers/DeepSeekProvider.js +8 -3
  258. package/dist/providers/DeepSeekProvider.js.map +1 -1
  259. package/dist/providers/GeminiProvider.d.ts +4 -3
  260. package/dist/providers/GeminiProvider.d.ts.map +1 -1
  261. package/dist/providers/GeminiProvider.js +4 -3
  262. package/dist/providers/GeminiProvider.js.map +1 -1
  263. package/dist/providers/OpenAICompatibleProvider.d.ts +4 -0
  264. package/dist/providers/OpenAICompatibleProvider.d.ts.map +1 -1
  265. package/dist/providers/OpenAICompatibleProvider.js +2 -0
  266. package/dist/providers/OpenAICompatibleProvider.js.map +1 -1
  267. package/dist/providers/OpenRouterProvider.d.ts.map +1 -1
  268. package/dist/providers/OpenRouterProvider.js +2 -4
  269. package/dist/providers/OpenRouterProvider.js.map +1 -1
  270. package/dist/providers/ProviderAdapter.d.ts +11 -6
  271. package/dist/providers/ProviderAdapter.d.ts.map +1 -1
  272. package/dist/providers/ProviderAdapter.js +34 -11
  273. package/dist/providers/ProviderAdapter.js.map +1 -1
  274. package/dist/providers/ZaiProvider.d.ts +6 -4
  275. package/dist/providers/ZaiProvider.d.ts.map +1 -1
  276. package/dist/providers/ZaiProvider.js +6 -4
  277. package/dist/providers/ZaiProvider.js.map +1 -1
  278. package/dist/types/agent.d.ts +163 -383
  279. package/dist/types/agent.d.ts.map +1 -1
  280. package/dist/types/agent.js +1 -1
  281. package/dist/types/ai.d.ts +32 -1
  282. package/dist/types/ai.d.ts.map +1 -1
  283. package/dist/types/compaction.d.ts +3 -1
  284. package/dist/types/compaction.d.ts.map +1 -1
  285. package/dist/types/errors.d.ts +9 -12
  286. package/dist/types/errors.d.ts.map +1 -1
  287. package/dist/types/errors.js +12 -15
  288. package/dist/types/errors.js.map +1 -1
  289. package/dist/types/flow.d.ts +265 -513
  290. package/dist/types/flow.d.ts.map +1 -1
  291. package/dist/types/flow.js +7 -1
  292. package/dist/types/flow.js.map +1 -1
  293. package/dist/types/history.d.ts +7 -18
  294. package/dist/types/history.d.ts.map +1 -1
  295. package/dist/types/history.js.map +1 -1
  296. package/dist/types/index.d.ts +9 -15
  297. package/dist/types/index.d.ts.map +1 -1
  298. package/dist/types/index.js +2 -7
  299. package/dist/types/index.js.map +1 -1
  300. package/dist/types/session.d.ts +94 -64
  301. package/dist/types/session.d.ts.map +1 -1
  302. package/dist/types/session.js +5 -1
  303. package/dist/types/session.js.map +1 -1
  304. package/dist/types/tool.d.ts +37 -207
  305. package/dist/types/tool.d.ts.map +1 -1
  306. package/dist/types/tool.js +6 -13
  307. package/dist/types/tool.js.map +1 -1
  308. package/dist/utils/clock.d.ts +28 -0
  309. package/dist/utils/clock.d.ts.map +1 -0
  310. package/dist/utils/clock.js +59 -0
  311. package/dist/utils/clock.js.map +1 -0
  312. package/dist/utils/duration.d.ts +11 -0
  313. package/dist/utils/duration.d.ts.map +1 -0
  314. package/dist/utils/duration.js +26 -0
  315. package/dist/utils/duration.js.map +1 -0
  316. package/dist/utils/history.d.ts +4 -1
  317. package/dist/utils/history.d.ts.map +1 -1
  318. package/dist/utils/history.js +2 -2
  319. package/dist/utils/history.js.map +1 -1
  320. package/dist/utils/index.d.ts +4 -10
  321. package/dist/utils/index.d.ts.map +1 -1
  322. package/dist/utils/index.js +4 -21
  323. package/dist/utils/index.js.map +1 -1
  324. package/dist/utils/json.d.ts +2 -0
  325. package/dist/utils/json.d.ts.map +1 -1
  326. package/dist/utils/json.js +4 -0
  327. package/dist/utils/json.js.map +1 -1
  328. package/dist/utils/outcomes.d.ts +48 -0
  329. package/dist/utils/outcomes.d.ts.map +1 -0
  330. package/dist/utils/outcomes.js +48 -0
  331. package/dist/utils/outcomes.js.map +1 -0
  332. package/dist/utils/phrases.d.ts +25 -0
  333. package/dist/utils/phrases.d.ts.map +1 -0
  334. package/dist/utils/phrases.js +35 -0
  335. package/dist/utils/phrases.js.map +1 -0
  336. package/dist/utils/schema.d.ts +50 -0
  337. package/dist/utils/schema.d.ts.map +1 -0
  338. package/dist/utils/schema.js +129 -0
  339. package/dist/utils/schema.js.map +1 -0
  340. package/dist/utils/streamingMessage.d.ts +3 -2
  341. package/dist/utils/streamingMessage.d.ts.map +1 -1
  342. package/dist/utils/streamingMessage.js +38 -4
  343. package/dist/utils/streamingMessage.js.map +1 -1
  344. package/dist/utils/template.d.ts +22 -150
  345. package/dist/utils/template.d.ts.map +1 -1
  346. package/dist/utils/template.js +61 -351
  347. package/dist/utils/template.js.map +1 -1
  348. package/dist/utils/usage.d.ts +19 -0
  349. package/dist/utils/usage.d.ts.map +1 -0
  350. package/dist/utils/usage.js +31 -0
  351. package/dist/utils/usage.js.map +1 -0
  352. package/docs/README.md +37 -19
  353. package/docs/concepts/architecture.md +117 -239
  354. package/docs/concepts/collection.md +170 -0
  355. package/docs/concepts/pipeline.md +132 -378
  356. package/docs/concepts/runs-and-waits.md +192 -0
  357. package/docs/guides/actions-and-events.md +276 -0
  358. package/docs/guides/branching.md +119 -208
  359. package/docs/guides/compaction.md +63 -158
  360. package/docs/guides/conditions.md +164 -128
  361. package/docs/guides/error-handling.md +170 -164
  362. package/docs/guides/flow-control.md +210 -349
  363. package/docs/guides/flows-from-json.md +224 -0
  364. package/docs/guides/instructions.md +125 -161
  365. package/docs/guides/persistence.md +182 -206
  366. package/docs/guides/streaming.md +50 -114
  367. package/docs/guides/testing.md +284 -0
  368. package/docs/guides/triggers.md +401 -0
  369. package/docs/migration/README.md +8 -15
  370. package/docs/migration/v1-to-v2.md +1 -1
  371. package/docs/migration/v2-3-to-v2-4.md +2 -2
  372. package/docs/migration/v2-6-to-v2-7.md +4 -4
  373. package/docs/migration/v3-to-v4.md +457 -0
  374. package/docs/reference/actions-events-conditions.md +396 -0
  375. package/docs/reference/agent.md +248 -0
  376. package/docs/reference/branches.md +75 -203
  377. package/docs/reference/errors.md +188 -144
  378. package/docs/reference/fields.md +125 -0
  379. package/docs/reference/flow-spec.md +248 -0
  380. package/docs/reference/flow.md +104 -192
  381. package/docs/reference/instruction.md +83 -137
  382. package/docs/reference/outcomes.md +273 -0
  383. package/docs/reference/providers.md +525 -302
  384. package/docs/reference/session.md +210 -0
  385. package/docs/reference/step.md +194 -312
  386. package/docs/reference/stores.md +496 -0
  387. package/docs/reference/tool.md +162 -231
  388. package/docs/reference/trigger.md +200 -0
  389. package/docs/rfc/v4-one-flow.md +477 -0
  390. package/docs/start/01-install.md +59 -44
  391. package/docs/start/02-first-agent.md +97 -147
  392. package/docs/start/03-collect-data.md +78 -183
  393. package/docs/start/04-add-tools.md +159 -227
  394. package/docs/start/05-go-to-production.md +181 -163
  395. package/examples/01-quickstart.ts +26 -16
  396. package/examples/02-fields.ts +75 -0
  397. package/examples/03-tools.ts +79 -119
  398. package/examples/04-instructions.ts +60 -87
  399. package/examples/05-branches.ts +78 -0
  400. package/examples/06-triggers-and-waits.ts +149 -0
  401. package/examples/07-streaming.ts +34 -60
  402. package/examples/08-store-and-migration.ts +97 -0
  403. package/examples/09-flows-from-json.ts +107 -0
  404. package/package.json +11 -6
  405. package/src/core/Agent.ts +126 -1512
  406. package/src/core/CompactionEngine.ts +7 -4
  407. package/src/core/FlowSpec.ts +778 -0
  408. package/src/core/Migrate.ts +256 -0
  409. package/src/core/Prompt.ts +162 -0
  410. package/src/core/Runner.ts +1214 -0
  411. package/src/core/Speak.ts +460 -0
  412. package/src/core/Understand.ts +423 -0
  413. package/src/core/contracts.ts +111 -0
  414. package/src/core/falai.ts +86 -0
  415. package/src/core/predicate.ts +56 -0
  416. package/src/index.ts +120 -147
  417. package/src/persistence/MemoryStore.ts +37 -0
  418. package/src/persistence/MongoStore.ts +89 -0
  419. package/src/persistence/OpenSearchStore.ts +153 -0
  420. package/src/persistence/PostgresStore.ts +89 -0
  421. package/src/persistence/PrismaStore.ts +127 -0
  422. package/src/persistence/RedisStore.ts +90 -0
  423. package/src/persistence/SQLiteStore.ts +103 -0
  424. package/src/persistence/sessionRow.ts +45 -0
  425. package/src/providers/DeepSeekProvider.ts +8 -3
  426. package/src/providers/GeminiProvider.ts +4 -3
  427. package/src/providers/OpenAICompatibleProvider.ts +6 -0
  428. package/src/providers/OpenRouterProvider.ts +2 -4
  429. package/src/providers/ProviderAdapter.ts +46 -13
  430. package/src/providers/ZaiProvider.ts +6 -4
  431. package/src/types/agent.ts +135 -397
  432. package/src/types/ai.ts +33 -1
  433. package/src/types/compaction.ts +3 -1
  434. package/src/types/errors.ts +13 -16
  435. package/src/types/flow.ts +249 -550
  436. package/src/types/history.ts +7 -20
  437. package/src/types/index.ts +88 -139
  438. package/src/types/session.ts +135 -70
  439. package/src/types/tool.ts +42 -267
  440. package/src/utils/clock.ts +70 -0
  441. package/src/utils/duration.ts +33 -0
  442. package/src/utils/history.ts +3 -2
  443. package/src/utils/index.ts +8 -66
  444. package/src/utils/json.ts +5 -0
  445. package/src/utils/outcomes.ts +56 -0
  446. package/src/utils/phrases.ts +40 -0
  447. package/src/utils/schema.ts +145 -0
  448. package/src/utils/streamingMessage.ts +34 -4
  449. package/src/utils/template.ts +63 -418
  450. package/src/utils/usage.ts +37 -0
  451. package/dist/adapters/MemoryAdapter.d.ts +0 -47
  452. package/dist/adapters/MemoryAdapter.d.ts.map +0 -1
  453. package/dist/adapters/MemoryAdapter.js +0 -204
  454. package/dist/adapters/MemoryAdapter.js.map +0 -1
  455. package/dist/adapters/MongoAdapter.d.ts +0 -97
  456. package/dist/adapters/MongoAdapter.d.ts.map +0 -1
  457. package/dist/adapters/MongoAdapter.js +0 -196
  458. package/dist/adapters/MongoAdapter.js.map +0 -1
  459. package/dist/adapters/OpenSearchAdapter.d.ts +0 -169
  460. package/dist/adapters/OpenSearchAdapter.d.ts.map +0 -1
  461. package/dist/adapters/OpenSearchAdapter.js +0 -471
  462. package/dist/adapters/OpenSearchAdapter.js.map +0 -1
  463. package/dist/adapters/PostgreSQLAdapter.d.ts +0 -85
  464. package/dist/adapters/PostgreSQLAdapter.d.ts.map +0 -1
  465. package/dist/adapters/PostgreSQLAdapter.js +0 -308
  466. package/dist/adapters/PostgreSQLAdapter.js.map +0 -1
  467. package/dist/adapters/PrismaAdapter.d.ts +0 -115
  468. package/dist/adapters/PrismaAdapter.d.ts.map +0 -1
  469. package/dist/adapters/PrismaAdapter.js +0 -406
  470. package/dist/adapters/PrismaAdapter.js.map +0 -1
  471. package/dist/adapters/RedisAdapter.d.ts +0 -72
  472. package/dist/adapters/RedisAdapter.d.ts.map +0 -1
  473. package/dist/adapters/RedisAdapter.js +0 -286
  474. package/dist/adapters/RedisAdapter.js.map +0 -1
  475. package/dist/adapters/SQLiteAdapter.d.ts +0 -86
  476. package/dist/adapters/SQLiteAdapter.d.ts.map +0 -1
  477. package/dist/adapters/SQLiteAdapter.js +0 -337
  478. package/dist/adapters/SQLiteAdapter.js.map +0 -1
  479. package/dist/adapters/index.d.ts +0 -17
  480. package/dist/adapters/index.d.ts.map +0 -1
  481. package/dist/adapters/index.js +0 -11
  482. package/dist/adapters/index.js.map +0 -1
  483. package/dist/adapters/sessionRow.d.ts +0 -22
  484. package/dist/adapters/sessionRow.d.ts.map +0 -1
  485. package/dist/adapters/sessionRow.js +0 -48
  486. package/dist/adapters/sessionRow.js.map +0 -1
  487. package/dist/cjs/adapters/MemoryAdapter.d.ts +0 -47
  488. package/dist/cjs/adapters/MemoryAdapter.d.ts.map +0 -1
  489. package/dist/cjs/adapters/MemoryAdapter.js +0 -208
  490. package/dist/cjs/adapters/MemoryAdapter.js.map +0 -1
  491. package/dist/cjs/adapters/MongoAdapter.d.ts +0 -97
  492. package/dist/cjs/adapters/MongoAdapter.d.ts.map +0 -1
  493. package/dist/cjs/adapters/MongoAdapter.js +0 -200
  494. package/dist/cjs/adapters/MongoAdapter.js.map +0 -1
  495. package/dist/cjs/adapters/OpenSearchAdapter.d.ts +0 -169
  496. package/dist/cjs/adapters/OpenSearchAdapter.d.ts.map +0 -1
  497. package/dist/cjs/adapters/OpenSearchAdapter.js +0 -475
  498. package/dist/cjs/adapters/OpenSearchAdapter.js.map +0 -1
  499. package/dist/cjs/adapters/PostgreSQLAdapter.d.ts +0 -85
  500. package/dist/cjs/adapters/PostgreSQLAdapter.d.ts.map +0 -1
  501. package/dist/cjs/adapters/PostgreSQLAdapter.js +0 -312
  502. package/dist/cjs/adapters/PostgreSQLAdapter.js.map +0 -1
  503. package/dist/cjs/adapters/PrismaAdapter.d.ts +0 -115
  504. package/dist/cjs/adapters/PrismaAdapter.d.ts.map +0 -1
  505. package/dist/cjs/adapters/PrismaAdapter.js +0 -410
  506. package/dist/cjs/adapters/PrismaAdapter.js.map +0 -1
  507. package/dist/cjs/adapters/RedisAdapter.d.ts +0 -72
  508. package/dist/cjs/adapters/RedisAdapter.d.ts.map +0 -1
  509. package/dist/cjs/adapters/RedisAdapter.js +0 -290
  510. package/dist/cjs/adapters/RedisAdapter.js.map +0 -1
  511. package/dist/cjs/adapters/SQLiteAdapter.d.ts +0 -86
  512. package/dist/cjs/adapters/SQLiteAdapter.d.ts.map +0 -1
  513. package/dist/cjs/adapters/SQLiteAdapter.js +0 -341
  514. package/dist/cjs/adapters/SQLiteAdapter.js.map +0 -1
  515. package/dist/cjs/adapters/index.d.ts +0 -17
  516. package/dist/cjs/adapters/index.d.ts.map +0 -1
  517. package/dist/cjs/adapters/index.js +0 -21
  518. package/dist/cjs/adapters/index.js.map +0 -1
  519. package/dist/cjs/adapters/sessionRow.d.ts +0 -22
  520. package/dist/cjs/adapters/sessionRow.d.ts.map +0 -1
  521. package/dist/cjs/adapters/sessionRow.js +0 -52
  522. package/dist/cjs/adapters/sessionRow.js.map +0 -1
  523. package/dist/cjs/constants/index.d.ts +0 -1
  524. package/dist/cjs/constants/index.d.ts.map +0 -1
  525. package/dist/cjs/constants/index.js +0 -4
  526. package/dist/cjs/constants/index.js.map +0 -1
  527. package/dist/cjs/core/AutoChainExecutor.d.ts +0 -97
  528. package/dist/cjs/core/AutoChainExecutor.d.ts.map +0 -1
  529. package/dist/cjs/core/AutoChainExecutor.js +0 -288
  530. package/dist/cjs/core/AutoChainExecutor.js.map +0 -1
  531. package/dist/cjs/core/BranchEvaluator.d.ts +0 -55
  532. package/dist/cjs/core/BranchEvaluator.d.ts.map +0 -1
  533. package/dist/cjs/core/BranchEvaluator.js +0 -125
  534. package/dist/cjs/core/BranchEvaluator.js.map +0 -1
  535. package/dist/cjs/core/DirectiveChainTracker.d.ts +0 -49
  536. package/dist/cjs/core/DirectiveChainTracker.d.ts.map +0 -1
  537. package/dist/cjs/core/DirectiveChainTracker.js +0 -121
  538. package/dist/cjs/core/DirectiveChainTracker.js.map +0 -1
  539. package/dist/cjs/core/Events.d.ts +0 -26
  540. package/dist/cjs/core/Events.d.ts.map +0 -1
  541. package/dist/cjs/core/Events.js +0 -144
  542. package/dist/cjs/core/Events.js.map +0 -1
  543. package/dist/cjs/core/Flow.d.ts +0 -183
  544. package/dist/cjs/core/Flow.d.ts.map +0 -1
  545. package/dist/cjs/core/Flow.js +0 -551
  546. package/dist/cjs/core/Flow.js.map +0 -1
  547. package/dist/cjs/core/FlowRouter.d.ts +0 -183
  548. package/dist/cjs/core/FlowRouter.d.ts.map +0 -1
  549. package/dist/cjs/core/FlowRouter.js +0 -1047
  550. package/dist/cjs/core/FlowRouter.js.map +0 -1
  551. package/dist/cjs/core/PersistenceManager.d.ts +0 -114
  552. package/dist/cjs/core/PersistenceManager.d.ts.map +0 -1
  553. package/dist/cjs/core/PersistenceManager.js +0 -336
  554. package/dist/cjs/core/PersistenceManager.js.map +0 -1
  555. package/dist/cjs/core/PromptComposer.d.ts +0 -47
  556. package/dist/cjs/core/PromptComposer.d.ts.map +0 -1
  557. package/dist/cjs/core/PromptComposer.js +0 -397
  558. package/dist/cjs/core/PromptComposer.js.map +0 -1
  559. package/dist/cjs/core/PromptSectionCache.d.ts +0 -48
  560. package/dist/cjs/core/PromptSectionCache.d.ts.map +0 -1
  561. package/dist/cjs/core/PromptSectionCache.js +0 -108
  562. package/dist/cjs/core/PromptSectionCache.js.map +0 -1
  563. package/dist/cjs/core/ResponseEngine.d.ts +0 -43
  564. package/dist/cjs/core/ResponseEngine.d.ts.map +0 -1
  565. package/dist/cjs/core/ResponseEngine.js +0 -235
  566. package/dist/cjs/core/ResponseEngine.js.map +0 -1
  567. package/dist/cjs/core/ResponseGenerationError.d.ts +0 -30
  568. package/dist/cjs/core/ResponseGenerationError.d.ts.map +0 -1
  569. package/dist/cjs/core/ResponseGenerationError.js +0 -35
  570. package/dist/cjs/core/ResponseGenerationError.js.map +0 -1
  571. package/dist/cjs/core/ResponseModal.d.ts +0 -305
  572. package/dist/cjs/core/ResponseModal.d.ts.map +0 -1
  573. package/dist/cjs/core/ResponseModal.js +0 -1414
  574. package/dist/cjs/core/ResponseModal.js.map +0 -1
  575. package/dist/cjs/core/ResponsePipeline.d.ts +0 -220
  576. package/dist/cjs/core/ResponsePipeline.d.ts.map +0 -1
  577. package/dist/cjs/core/ResponsePipeline.js +0 -1040
  578. package/dist/cjs/core/ResponsePipeline.js.map +0 -1
  579. package/dist/cjs/core/SessionFinalizer.d.ts +0 -34
  580. package/dist/cjs/core/SessionFinalizer.d.ts.map +0 -1
  581. package/dist/cjs/core/SessionFinalizer.js +0 -88
  582. package/dist/cjs/core/SessionFinalizer.js.map +0 -1
  583. package/dist/cjs/core/SessionManager.d.ts +0 -112
  584. package/dist/cjs/core/SessionManager.d.ts.map +0 -1
  585. package/dist/cjs/core/SessionManager.js +0 -308
  586. package/dist/cjs/core/SessionManager.js.map +0 -1
  587. package/dist/cjs/core/SignalCoordinator.d.ts +0 -103
  588. package/dist/cjs/core/SignalCoordinator.d.ts.map +0 -1
  589. package/dist/cjs/core/SignalCoordinator.js +0 -207
  590. package/dist/cjs/core/SignalCoordinator.js.map +0 -1
  591. package/dist/cjs/core/SignalEvaluator.d.ts +0 -86
  592. package/dist/cjs/core/SignalEvaluator.d.ts.map +0 -1
  593. package/dist/cjs/core/SignalEvaluator.js +0 -319
  594. package/dist/cjs/core/SignalEvaluator.js.map +0 -1
  595. package/dist/cjs/core/SignalProcessor.d.ts +0 -152
  596. package/dist/cjs/core/SignalProcessor.d.ts.map +0 -1
  597. package/dist/cjs/core/SignalProcessor.js +0 -505
  598. package/dist/cjs/core/SignalProcessor.js.map +0 -1
  599. package/dist/cjs/core/Step.d.ts +0 -184
  600. package/dist/cjs/core/Step.d.ts.map +0 -1
  601. package/dist/cjs/core/Step.js +0 -599
  602. package/dist/cjs/core/Step.js.map +0 -1
  603. package/dist/cjs/core/StepLifecycle.d.ts +0 -43
  604. package/dist/cjs/core/StepLifecycle.d.ts.map +0 -1
  605. package/dist/cjs/core/StepLifecycle.js +0 -180
  606. package/dist/cjs/core/StepLifecycle.js.map +0 -1
  607. package/dist/cjs/core/StreamingToolExecutor.d.ts +0 -142
  608. package/dist/cjs/core/StreamingToolExecutor.d.ts.map +0 -1
  609. package/dist/cjs/core/StreamingToolExecutor.js +0 -490
  610. package/dist/cjs/core/StreamingToolExecutor.js.map +0 -1
  611. package/dist/cjs/core/ToolLoopExecutor.d.ts +0 -133
  612. package/dist/cjs/core/ToolLoopExecutor.d.ts.map +0 -1
  613. package/dist/cjs/core/ToolLoopExecutor.js +0 -568
  614. package/dist/cjs/core/ToolLoopExecutor.js.map +0 -1
  615. package/dist/cjs/core/ToolManager.d.ts +0 -250
  616. package/dist/cjs/core/ToolManager.d.ts.map +0 -1
  617. package/dist/cjs/core/ToolManager.js +0 -1104
  618. package/dist/cjs/core/ToolManager.js.map +0 -1
  619. package/dist/cjs/core/createAgent.d.ts +0 -35
  620. package/dist/cjs/core/createAgent.d.ts.map +0 -1
  621. package/dist/cjs/core/createAgent.js +0 -39
  622. package/dist/cjs/core/createAgent.js.map +0 -1
  623. package/dist/cjs/core/flow-namespace.d.ts +0 -64
  624. package/dist/cjs/core/flow-namespace.d.ts.map +0 -1
  625. package/dist/cjs/core/flow-namespace.js +0 -182
  626. package/dist/cjs/core/flow-namespace.js.map +0 -1
  627. package/dist/cjs/core/toolGates.d.ts +0 -24
  628. package/dist/cjs/core/toolGates.d.ts.map +0 -1
  629. package/dist/cjs/core/toolGates.js +0 -52
  630. package/dist/cjs/core/toolGates.js.map +0 -1
  631. package/dist/cjs/types/persistence.d.ts +0 -254
  632. package/dist/cjs/types/persistence.d.ts.map +0 -1
  633. package/dist/cjs/types/persistence.js +0 -7
  634. package/dist/cjs/types/persistence.js.map +0 -1
  635. package/dist/cjs/types/prompt-cache.d.ts +0 -15
  636. package/dist/cjs/types/prompt-cache.d.ts.map +0 -1
  637. package/dist/cjs/types/prompt-cache.js +0 -6
  638. package/dist/cjs/types/prompt-cache.js.map +0 -1
  639. package/dist/cjs/types/signals.d.ts +0 -263
  640. package/dist/cjs/types/signals.d.ts.map +0 -1
  641. package/dist/cjs/types/signals.js +0 -11
  642. package/dist/cjs/types/signals.js.map +0 -1
  643. package/dist/cjs/types/template.d.ts +0 -84
  644. package/dist/cjs/types/template.d.ts.map +0 -1
  645. package/dist/cjs/types/template.js +0 -3
  646. package/dist/cjs/types/template.js.map +0 -1
  647. package/dist/cjs/utils/condition.d.ts +0 -63
  648. package/dist/cjs/utils/condition.d.ts.map +0 -1
  649. package/dist/cjs/utils/condition.js +0 -239
  650. package/dist/cjs/utils/condition.js.map +0 -1
  651. package/dist/cjs/utils/event.d.ts +0 -6
  652. package/dist/cjs/utils/event.d.ts.map +0 -1
  653. package/dist/cjs/utils/event.js +0 -20
  654. package/dist/cjs/utils/event.js.map +0 -1
  655. package/dist/cjs/utils/id.d.ts +0 -33
  656. package/dist/cjs/utils/id.d.ts.map +0 -1
  657. package/dist/cjs/utils/id.js +0 -84
  658. package/dist/cjs/utils/id.js.map +0 -1
  659. package/dist/cjs/utils/serialize.d.ts +0 -36
  660. package/dist/cjs/utils/serialize.d.ts.map +0 -1
  661. package/dist/cjs/utils/serialize.js +0 -77
  662. package/dist/cjs/utils/serialize.js.map +0 -1
  663. package/dist/cjs/utils/session.d.ts +0 -124
  664. package/dist/cjs/utils/session.d.ts.map +0 -1
  665. package/dist/cjs/utils/session.js +0 -396
  666. package/dist/cjs/utils/session.js.map +0 -1
  667. package/dist/constants/index.d.ts +0 -2
  668. package/dist/constants/index.d.ts.map +0 -1
  669. package/dist/constants/index.js +0 -4
  670. package/dist/constants/index.js.map +0 -1
  671. package/dist/core/AutoChainExecutor.d.ts +0 -97
  672. package/dist/core/AutoChainExecutor.d.ts.map +0 -1
  673. package/dist/core/AutoChainExecutor.js +0 -284
  674. package/dist/core/AutoChainExecutor.js.map +0 -1
  675. package/dist/core/BranchEvaluator.d.ts +0 -55
  676. package/dist/core/BranchEvaluator.d.ts.map +0 -1
  677. package/dist/core/BranchEvaluator.js +0 -121
  678. package/dist/core/BranchEvaluator.js.map +0 -1
  679. package/dist/core/DirectiveChainTracker.d.ts +0 -49
  680. package/dist/core/DirectiveChainTracker.d.ts.map +0 -1
  681. package/dist/core/DirectiveChainTracker.js +0 -117
  682. package/dist/core/DirectiveChainTracker.js.map +0 -1
  683. package/dist/core/Events.d.ts +0 -26
  684. package/dist/core/Events.d.ts.map +0 -1
  685. package/dist/core/Events.js +0 -137
  686. package/dist/core/Events.js.map +0 -1
  687. package/dist/core/Flow.d.ts +0 -183
  688. package/dist/core/Flow.d.ts.map +0 -1
  689. package/dist/core/Flow.js +0 -547
  690. package/dist/core/Flow.js.map +0 -1
  691. package/dist/core/FlowRouter.d.ts +0 -183
  692. package/dist/core/FlowRouter.d.ts.map +0 -1
  693. package/dist/core/FlowRouter.js +0 -1043
  694. package/dist/core/FlowRouter.js.map +0 -1
  695. package/dist/core/PersistenceManager.d.ts +0 -114
  696. package/dist/core/PersistenceManager.d.ts.map +0 -1
  697. package/dist/core/PersistenceManager.js +0 -332
  698. package/dist/core/PersistenceManager.js.map +0 -1
  699. package/dist/core/PromptComposer.d.ts +0 -47
  700. package/dist/core/PromptComposer.d.ts.map +0 -1
  701. package/dist/core/PromptComposer.js +0 -393
  702. package/dist/core/PromptComposer.js.map +0 -1
  703. package/dist/core/PromptSectionCache.d.ts +0 -48
  704. package/dist/core/PromptSectionCache.d.ts.map +0 -1
  705. package/dist/core/PromptSectionCache.js +0 -104
  706. package/dist/core/PromptSectionCache.js.map +0 -1
  707. package/dist/core/ResponseEngine.d.ts +0 -43
  708. package/dist/core/ResponseEngine.d.ts.map +0 -1
  709. package/dist/core/ResponseEngine.js +0 -231
  710. package/dist/core/ResponseEngine.js.map +0 -1
  711. package/dist/core/ResponseGenerationError.d.ts +0 -30
  712. package/dist/core/ResponseGenerationError.d.ts.map +0 -1
  713. package/dist/core/ResponseGenerationError.js +0 -31
  714. package/dist/core/ResponseGenerationError.js.map +0 -1
  715. package/dist/core/ResponseModal.d.ts +0 -305
  716. package/dist/core/ResponseModal.d.ts.map +0 -1
  717. package/dist/core/ResponseModal.js +0 -1410
  718. package/dist/core/ResponseModal.js.map +0 -1
  719. package/dist/core/ResponsePipeline.d.ts +0 -220
  720. package/dist/core/ResponsePipeline.d.ts.map +0 -1
  721. package/dist/core/ResponsePipeline.js +0 -1035
  722. package/dist/core/ResponsePipeline.js.map +0 -1
  723. package/dist/core/SessionFinalizer.d.ts +0 -34
  724. package/dist/core/SessionFinalizer.d.ts.map +0 -1
  725. package/dist/core/SessionFinalizer.js +0 -84
  726. package/dist/core/SessionFinalizer.js.map +0 -1
  727. package/dist/core/SessionManager.d.ts +0 -112
  728. package/dist/core/SessionManager.d.ts.map +0 -1
  729. package/dist/core/SessionManager.js +0 -301
  730. package/dist/core/SessionManager.js.map +0 -1
  731. package/dist/core/SignalCoordinator.d.ts +0 -103
  732. package/dist/core/SignalCoordinator.d.ts.map +0 -1
  733. package/dist/core/SignalCoordinator.js +0 -203
  734. package/dist/core/SignalCoordinator.js.map +0 -1
  735. package/dist/core/SignalEvaluator.d.ts +0 -86
  736. package/dist/core/SignalEvaluator.d.ts.map +0 -1
  737. package/dist/core/SignalEvaluator.js +0 -312
  738. package/dist/core/SignalEvaluator.js.map +0 -1
  739. package/dist/core/SignalProcessor.d.ts +0 -152
  740. package/dist/core/SignalProcessor.d.ts.map +0 -1
  741. package/dist/core/SignalProcessor.js +0 -498
  742. package/dist/core/SignalProcessor.js.map +0 -1
  743. package/dist/core/Step.d.ts +0 -184
  744. package/dist/core/Step.d.ts.map +0 -1
  745. package/dist/core/Step.js +0 -594
  746. package/dist/core/Step.js.map +0 -1
  747. package/dist/core/StepLifecycle.d.ts +0 -43
  748. package/dist/core/StepLifecycle.d.ts.map +0 -1
  749. package/dist/core/StepLifecycle.js +0 -176
  750. package/dist/core/StepLifecycle.js.map +0 -1
  751. package/dist/core/StreamingToolExecutor.d.ts +0 -142
  752. package/dist/core/StreamingToolExecutor.d.ts.map +0 -1
  753. package/dist/core/StreamingToolExecutor.js +0 -483
  754. package/dist/core/StreamingToolExecutor.js.map +0 -1
  755. package/dist/core/ToolLoopExecutor.d.ts +0 -133
  756. package/dist/core/ToolLoopExecutor.d.ts.map +0 -1
  757. package/dist/core/ToolLoopExecutor.js +0 -564
  758. package/dist/core/ToolLoopExecutor.js.map +0 -1
  759. package/dist/core/ToolManager.d.ts +0 -250
  760. package/dist/core/ToolManager.d.ts.map +0 -1
  761. package/dist/core/ToolManager.js +0 -1098
  762. package/dist/core/ToolManager.js.map +0 -1
  763. package/dist/core/createAgent.d.ts +0 -35
  764. package/dist/core/createAgent.d.ts.map +0 -1
  765. package/dist/core/createAgent.js +0 -36
  766. package/dist/core/createAgent.js.map +0 -1
  767. package/dist/core/flow-namespace.d.ts +0 -64
  768. package/dist/core/flow-namespace.d.ts.map +0 -1
  769. package/dist/core/flow-namespace.js +0 -179
  770. package/dist/core/flow-namespace.js.map +0 -1
  771. package/dist/core/toolGates.d.ts +0 -24
  772. package/dist/core/toolGates.d.ts.map +0 -1
  773. package/dist/core/toolGates.js +0 -49
  774. package/dist/core/toolGates.js.map +0 -1
  775. package/dist/types/persistence.d.ts +0 -254
  776. package/dist/types/persistence.d.ts.map +0 -1
  777. package/dist/types/persistence.js +0 -6
  778. package/dist/types/persistence.js.map +0 -1
  779. package/dist/types/prompt-cache.d.ts +0 -15
  780. package/dist/types/prompt-cache.d.ts.map +0 -1
  781. package/dist/types/prompt-cache.js +0 -5
  782. package/dist/types/prompt-cache.js.map +0 -1
  783. package/dist/types/signals.d.ts +0 -263
  784. package/dist/types/signals.d.ts.map +0 -1
  785. package/dist/types/signals.js +0 -10
  786. package/dist/types/signals.js.map +0 -1
  787. package/dist/types/template.d.ts +0 -84
  788. package/dist/types/template.d.ts.map +0 -1
  789. package/dist/types/template.js +0 -2
  790. package/dist/types/template.js.map +0 -1
  791. package/dist/utils/condition.d.ts +0 -63
  792. package/dist/utils/condition.d.ts.map +0 -1
  793. package/dist/utils/condition.js +0 -230
  794. package/dist/utils/condition.js.map +0 -1
  795. package/dist/utils/event.d.ts +0 -6
  796. package/dist/utils/event.d.ts.map +0 -1
  797. package/dist/utils/event.js +0 -17
  798. package/dist/utils/event.js.map +0 -1
  799. package/dist/utils/id.d.ts +0 -33
  800. package/dist/utils/id.d.ts.map +0 -1
  801. package/dist/utils/id.js +0 -77
  802. package/dist/utils/id.js.map +0 -1
  803. package/dist/utils/serialize.d.ts +0 -36
  804. package/dist/utils/serialize.d.ts.map +0 -1
  805. package/dist/utils/serialize.js +0 -72
  806. package/dist/utils/serialize.js.map +0 -1
  807. package/dist/utils/session.d.ts +0 -124
  808. package/dist/utils/session.d.ts.map +0 -1
  809. package/dist/utils/session.js +0 -379
  810. package/dist/utils/session.js.map +0 -1
  811. package/docs/concepts/directives.md +0 -369
  812. package/docs/reference/adapters.md +0 -543
  813. package/docs/reference/create-agent.md +0 -216
  814. package/docs/reference/directive.md +0 -242
  815. package/docs/reference/signals.md +0 -368
  816. package/examples/02-data-extraction.ts +0 -90
  817. package/examples/05-branching.ts +0 -140
  818. package/examples/06-flow-control.ts +0 -103
  819. package/examples/08-persistence.ts +0 -98
  820. package/examples/09-signals.ts +0 -144
  821. package/src/adapters/MemoryAdapter.ts +0 -281
  822. package/src/adapters/MongoAdapter.ts +0 -341
  823. package/src/adapters/OpenSearchAdapter.ts +0 -693
  824. package/src/adapters/PostgreSQLAdapter.ts +0 -487
  825. package/src/adapters/PrismaAdapter.ts +0 -617
  826. package/src/adapters/RedisAdapter.ts +0 -439
  827. package/src/adapters/SQLiteAdapter.ts +0 -496
  828. package/src/adapters/index.ts +0 -43
  829. package/src/adapters/sessionRow.ts +0 -57
  830. package/src/constants/index.ts +0 -2
  831. package/src/core/AutoChainExecutor.ts +0 -397
  832. package/src/core/BranchEvaluator.ts +0 -161
  833. package/src/core/DirectiveChainTracker.ts +0 -144
  834. package/src/core/Events.ts +0 -164
  835. package/src/core/Flow.ts +0 -665
  836. package/src/core/FlowRouter.ts +0 -1540
  837. package/src/core/PersistenceManager.ts +0 -446
  838. package/src/core/PromptComposer.ts +0 -448
  839. package/src/core/PromptSectionCache.ts +0 -125
  840. package/src/core/ResponseEngine.ts +0 -338
  841. package/src/core/ResponseGenerationError.ts +0 -53
  842. package/src/core/ResponseModal.ts +0 -1902
  843. package/src/core/ResponsePipeline.ts +0 -1404
  844. package/src/core/SessionFinalizer.ts +0 -108
  845. package/src/core/SessionManager.ts +0 -372
  846. package/src/core/SignalCoordinator.ts +0 -263
  847. package/src/core/SignalEvaluator.ts +0 -404
  848. package/src/core/SignalProcessor.ts +0 -663
  849. package/src/core/Step.ts +0 -782
  850. package/src/core/StepLifecycle.ts +0 -242
  851. package/src/core/StreamingToolExecutor.ts +0 -609
  852. package/src/core/ToolLoopExecutor.ts +0 -749
  853. package/src/core/ToolManager.ts +0 -1379
  854. package/src/core/createAgent.ts +0 -40
  855. package/src/core/flow-namespace.ts +0 -227
  856. package/src/core/toolGates.ts +0 -72
  857. package/src/types/persistence.ts +0 -303
  858. package/src/types/prompt-cache.ts +0 -17
  859. package/src/types/signals.ts +0 -338
  860. package/src/types/template.ts +0 -98
  861. package/src/utils/condition.ts +0 -296
  862. package/src/utils/event.ts +0 -16
  863. package/src/utils/id.ts +0 -91
  864. package/src/utils/serialize.ts +0 -86
  865. package/src/utils/session.ts +0 -501
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  **Typed conversations where code stays in charge.**
6
6
 
7
- Define flows, steps, and tools in TypeScript; the framework calls the LLM only for the parts that need language — routing, extraction, and generation.
7
+ Define flows, steps and tools in TypeScript; the framework calls the AI only where language is needed: to understand what the customer wrote and to write the reply.
8
8
 
9
9
  [![npm](https://img.shields.io/npm/v/@falai/agent.svg)](https://www.npmjs.com/package/@falai/agent)
10
10
  [![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
@@ -12,51 +12,58 @@ Define flows, steps, and tools in TypeScript; the framework calls the LLM only f
12
12
 
13
13
  </div>
14
14
 
15
- > The AI understands. The code is in control.
16
-
17
- ```typescript
18
- import { createAgent, GeminiProvider } from "@falai/agent";
19
-
20
- const agent = createAgent({
21
- provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
22
- schema: { type: "object", properties: { name: { type: "string" } } },
23
- flows: [{
24
- title: "Greet",
25
- requiredFields: ["name"],
26
- steps: [{ id: "ask_name", prompt: "What's your name?", collect: ["name"] }],
27
- }],
28
- });
29
-
30
- const response = await agent.respond({ history: [{ role: "user", content: "Hi, I'm Alice" }] });
31
- console.log(response.message);
15
+ ```ts fragment
16
+ const r = await agent.turn({ sessionId: "demo", message: "oi" });
17
+ console.log(r.messages[0]?.text); // the AI asks for a name, something like "Oi! Como posso te chamar?"
32
18
  ```
33
19
 
34
- ## Primitives
35
-
36
- ### Agent
20
+ The `agent` behind that call, in full:
37
21
 
38
- **Bind schema to provider.**
22
+ ```ts
23
+ import { falai, GeminiProvider } from "@falai/agent";
39
24
 
40
- The top-level object. Owns the schema, the provider, the flows, the tools, and the session. One agent serves many conversations.
25
+ const apiKey = process.env.GEMINI_API_KEY;
26
+ if (!apiKey) throw new Error("Set GEMINI_API_KEY before running this example.");
41
27
 
42
- ### Flow
43
-
44
- **Collect until done.**
28
+ const f = falai().fields({
29
+ nome: { type: "string", ask: "Pergunte o nome da pessoa, sem tom de formulário." },
30
+ });
45
31
 
46
- A goal made of ordered steps. Declares which schema fields it needs; the engine completes the flow when every required field has been collected.
32
+ const agent = f.agent({
33
+ name: "Ana",
34
+ provider: new GeminiProvider({ apiKey, model: "gemini-2.5-flash" }),
35
+ flows: [
36
+ f.flow({
37
+ id: "boas-vindas",
38
+ name: "Boas-vindas",
39
+ on: [{ message: [] }],
40
+ steps: [
41
+ { id: "nome", collect: ["nome"] },
42
+ { id: "ajuda", prompt: "Agradeça pelo nome e pergunte como pode ajudar." },
43
+ ],
44
+ }),
45
+ ],
46
+ });
47
47
 
48
- ### Tool
48
+ const r = await agent.turn({ sessionId: "demo", message: "oi" });
49
+ console.log(r.messages[0]?.text);
50
+ ```
49
51
 
50
- **Run code, redirect flow.**
52
+ ## The model
51
53
 
52
- A typed function the AI can call. Receives a `ToolContext` with session data, can dispatch directives to redirect the conversation, and returns a typed result.
54
+ - A flow is a trigger plus an ordered list of steps; a flow that has started is a run.
55
+ - A step is one of five things: the AI talks (`prompt` / `collect`), a fixed text goes out (`say`), your code runs (`do`), the run waits (`wait`), or the code forks (`if`).
56
+ - Fields live on the agent, each with its own `ask`. The customer can give them in any order, and a step whose fields are already known is skipped.
57
+ - One `agent.turn()` takes every kind of input: a customer message, a timer, an event from your system, or a start you call by hand.
58
+ - It returns the messages to send, the timers to set and one outcome line per step. The framework never sends, never sleeps and never saves. You save the session, then send the messages and set the timers.
59
+ - A text turn costs at most two model calls (understand, then speak) plus one per tool round, and one more when `compaction` summarizes the history. `r.llmCalls` says how many it spent.
53
60
 
54
61
  ## Where to go next
55
62
 
56
63
  - **Build your first agent** → [docs/start/01-install.md](./docs/start/01-install.md)
57
- - **Explore the docs** → [docs/](./docs/README.md)
58
- - **Examples** → [examples/](./examples/)
59
- - **Upgrading** → [docs/migration/](./docs/migration/README.md) (v2.3 → v2.4, v1 → v2)
64
+ - **Read the docs** → [docs/](./docs/README.md)
65
+ - **Examples** → [examples/](./examples/), nine runnable files from a quickstart to flows stored as JSON
66
+ - **Upgrading** → [docs/migration/](./docs/migration/README.md); v4 is a clean break from 3.x
60
67
 
61
68
  ## Install
62
69
 
@@ -72,7 +79,7 @@ Requires Node 22.12+ or Bun 1.0+. Set a provider API key in your environment (fo
72
79
 
73
80
  ## License
74
81
 
75
- MIT © 2025
82
+ MIT © 2026
76
83
 
77
84
  <div align="center">
78
85
 
@@ -1,382 +1,33 @@
1
1
  /**
2
- * Core Agent implementation
2
+ * Agent: immutable configuration plus one entry point, `turn`.
3
+ *
4
+ * One instance serves every session; context and history arrive per turn.
5
+ * A turn is the eight phases of docs/rfc/v4-one-flow.md §4 in one line each:
6
+ * Runner moves the runs by code, Understand and Speak spend at most one
7
+ * provider call apiece, and Runner settles what they returned.
3
8
  */
4
- import type { AgentOptions, Term, Instruction, Tool, FlowOptions, SessionState, Template, AgentResponseStreamChunk, AgentResponse, StructuredSchema, ValidationResult, AiProvider, CompactionOptions, Directive } from "../types/index.js";
5
- import type { Signal } from "../types/signals.js";
6
- import { SignalProcessor } from "./SignalProcessor.js";
7
- import type { StreamOptions, GenerateOptions, RespondParams, ResponseModalDeps } from "./ResponseModal.js";
8
- import { Flow } from "./Flow.js";
9
- import { Step } from "./Step.js";
10
- import { PersistenceManager } from "./PersistenceManager.js";
11
- import { SessionManager } from "./SessionManager.js";
12
- import { FlowRouter } from "./FlowRouter.js";
13
- import { PromptSectionCache } from "./PromptSectionCache.js";
14
- import { ToolManager } from "./ToolManager.js";
15
- /**
16
- * Main Agent class with generic context and data support
17
- */
18
- export declare class Agent<TContext = unknown, TData = unknown> implements ResponseModalDeps<TContext, TData> {
19
- private options;
20
- private _terms;
21
- private _instructions;
22
- private _tools;
23
- private _flows;
24
- private _context;
25
- private _persistenceManager;
26
- private _routingEngine;
27
- private _responseModal;
28
- private _knowledgeBase;
29
- private _schema?;
30
- /**
31
- * Staging buffer for data set before any session exists (initialData and
32
- * pre-session updateCollectedData calls). Consumed when a session is
33
- * created; once a session exists, `session.data` is the single source of
34
- * truth and this buffer stays empty.
35
- */
36
- private _pendingData;
37
- private _compactionOptions?;
38
- private _promptSectionCache;
39
- /** Signals: typed event detectors that run around the LLM turn. */
40
- private _signals;
41
- /**
42
- * Signal processor instance. Undefined when no signals are configured.
43
- * Constructed only when `options.signals` is non-empty (Requirement 2.3).
44
- */
45
- signalProcessor: SignalProcessor<TContext, TData> | undefined;
46
- /** Maximum consecutive auto-steps allowed in a single turn before throwing. */
47
- readonly maxAutoStepsPerTurn: number;
48
- /** Maximum chained directives allowed in a single turn before throwing. */
49
- readonly maxDirectiveChain: number;
50
- /** Public session manager for easy session management */
51
- session: SessionManager<TData>;
52
- /** Public tool manager for simplified tool creation and management */
53
- tool: ToolManager<TContext, TData>;
54
- constructor(options: AgentOptions<TContext, TData>);
55
- /**
56
- * Drain the pre-session data staging buffer.
57
- * @internal Called by SessionManager when a session is created or loaded.
58
- */
59
- consumePendingData(): Partial<TData>;
60
- /**
61
- * Validate the agent-level schema structure
62
- * @private
63
- */
64
- private validateSchema;
65
- /**
66
- * Walk every flow's steps and resolve deferred string `then` values in branches
67
- * against the agent's flow registry. Strings that match neither a local step id
68
- * nor any flow id/title throw FlowConfigurationError.
69
- * @private
70
- */
71
- private validateBranchReferences;
72
- /**
73
- * Validate branch `then` string references for a single flow against the agent's
74
- * flow registry. Throws FlowConfigurationError for unresolved references.
75
- * @private
76
- */
77
- private validateFlowBranchReferences;
78
- /**
79
- * Validate that every step's `collect` fields in a flow reference valid keys
80
- * from the agent-level schema. Throws FlowConfigurationError at construction
81
- * time if any collect field is not a valid schema key.
82
- *
83
- * This enforces Requirement 14.5: generic inference is preserved AND every
84
- * `collect` field reference is a valid key of the inferred TData.
85
- * @private
86
- */
87
- private validateFlowCollectFields;
88
- /**
89
- * Validate data against the agent-level schema.
90
- *
91
- * A field the schema does not declare is a warning, not an error: a model
92
- * can extract a key nobody asked for, and `updateCollectedData` drops it
93
- * instead of failing the turn. `valid` is false only when `errors` is not empty.
94
- */
95
- validateData(data: Partial<TData>): ValidationResult;
96
- /**
97
- * Check if a field is valid according to the agent schema
98
- * @param field - The field key to validate
99
- * @returns true if field exists in schema or no schema is defined, false otherwise
100
- */
101
- isValidSchemaField(field: keyof TData): boolean;
102
- /**
103
- * Get the current collected data.
104
- * Reads from the live session when one exists; otherwise from the
105
- * pre-session staging buffer.
106
- */
107
- getCollectedData(): Partial<TData>;
108
- /**
109
- * Update collected data with validation.
110
- * Writes to the live session when one exists; otherwise stages the data
111
- * for the session that will be created. Fields the agent schema does not
112
- * declare are dropped with a warning, never stored.
113
- */
114
- updateCollectedData(updates: Partial<TData>): Promise<void>;
115
- /**
116
- * Get agent name
117
- */
118
- get name(): string;
119
- /**
120
- * Set agent name
121
- */
122
- set name(value: string);
123
- /**
124
- * Get agent persona
125
- */
126
- get persona(): Template<TContext> | undefined;
127
- /**
128
- * Set agent persona
129
- */
130
- set persona(value: Template<TContext> | undefined);
131
- /**
132
- * Get agent goal
133
- */
134
- get goal(): string | undefined;
135
- /**
136
- * Set agent goal
137
- */
138
- set goal(value: string | undefined);
139
- /**
140
- * Get whether debug mode is enabled
141
- */
142
- get debug(): boolean;
143
- /**
144
- * Set debug mode (also updates logger level)
145
- */
146
- set debug(value: boolean);
147
- /**
148
- * Get the AI provider
149
- */
150
- get provider(): AiProvider;
151
- /**
152
- * Set the AI provider
153
- */
154
- set provider(value: AiProvider);
155
- /**
156
- * Get the flow switch margin
157
- * @default 15
158
- */
159
- get flowSwitchMargin(): number;
160
- /**
161
- * Set the flow switch margin
162
- */
163
- set flowSwitchMargin(value: number);
164
- /**
165
- * Get the prompt section cache instance
166
- */
167
- get promptSectionCache(): PromptSectionCache;
168
- /**
169
- * Get all terms
170
- */
171
- get terms(): Term<TContext, TData>[];
172
- /**
173
- * Get all instructions
174
- */
175
- get instructions(): Instruction<TContext, TData>[];
176
- /**
177
- * Get all tools
178
- */
179
- get tools(): Tool<TContext, TData>[];
180
- /**
181
- * Get all flows
182
- */
183
- get flows(): Flow<TContext, TData>[];
184
- /**
185
- * Get current schema
186
- */
187
- get schema(): StructuredSchema | undefined;
188
- /**
189
- * Set schema (validates structure)
190
- */
191
- set schema(value: StructuredSchema | undefined);
192
- /**
193
- * Get the configured signals.
194
- */
195
- get signals(): Signal<TContext, TData, any>[];
196
- /**
197
- * Get the agent's knowledge base
198
- */
199
- get knowledgeBase(): Record<string, unknown>;
200
- /**
201
- * Set the agent's knowledge base
202
- */
203
- set knowledgeBase(value: Record<string, unknown>);
204
- /**
205
- * Get the current session (if set). Delegates to the SessionManager —
206
- * the single owner of the live session.
207
- */
208
- get currentSession(): SessionState<TData> | undefined;
209
- /**
210
- * Set the current session for convenience methods
211
- * Set to undefined to clear the current session
212
- */
213
- set currentSession(value: SessionState<TData> | undefined);
214
- /**
215
- * Get all flows
216
- */
217
- getFlows(): Flow<TContext, TData>[];
218
- /**
219
- * Get all terms
220
- */
221
- getTerms(): Term<TContext, TData>[];
222
- /**
223
- * Get all tools
224
- */
225
- getTools(): Tool<TContext, TData>[];
226
- /**
227
- * Get all instructions
228
- */
229
- getInstructions(): Instruction<TContext, TData>[];
230
- /**
231
- * Invalidate flow-dependent prompt cache sections.
232
- * Called automatically when the active flow changes.
233
- */
234
- invalidateFlowSections(): void;
235
- /**
236
- * Get the persistence manager (if configured)
237
- */
238
- getPersistenceManager(): PersistenceManager<TData> | undefined;
239
- /**
240
- * Check if persistence is enabled
241
- */
242
- hasPersistence(): boolean;
243
- /**
244
- * Get the resolved compaction options (if compaction is configured)
245
- */
246
- getCompactionOptions(): CompactionOptions | undefined;
247
- /**
248
- * Create a new flow (journey) using agent-level data type
249
- */
250
- createFlow(options: FlowOptions<TContext, TData>): Flow<TContext, TData>;
251
- /**
252
- * Create a domain term for the glossary
253
- */
254
- createTerm(term: Term<TContext, TData>): this;
255
- /**
256
- * Create an instruction (unified behavioral primitive).
257
- */
258
- createInstruction(instruction: Instruction<TContext, TData>): this;
259
- /**
260
- * Add a tool to the agent using the unified Tool interface
261
- * Creates and adds the tool to agent scope in one operation
262
- */
263
- addTool<TResult = unknown>(tool: Tool<TContext, TData, TResult>): this;
264
- /**
265
- * Register multiple tools at the agent level
266
- */
267
- registerTools<TResult = unknown>(tools: Tool<TContext, TData, TResult>[]): this;
268
- /**
269
- * Update the agent's context
270
- * Triggers both agent-level and flow-specific onContextUpdate lifecycle hooks if configured
271
- */
272
- updateContext(updates: Partial<TContext>): Promise<void>;
273
- /**
274
- * Update collected data in session with lifecycle hook support
275
- * Triggers both agent-level and flow-specific onDataUpdate lifecycle hooks if configured
276
- * @internal
277
- */
278
- private updateData;
279
- /**
280
- * Get current context (fetches from provider if configured)
281
- */
282
- getContext(): Promise<TContext | undefined>;
283
- /**
284
- * Generate a response based on history and context as a stream
285
- */
286
- respondStream(params: RespondParams<TContext, TData>): AsyncGenerator<AgentResponseStreamChunk<TData>>;
287
- /**
288
- * Generate a response based on history and context
289
- */
290
- respond(params: RespondParams<TContext, TData>): Promise<AgentResponse<TData>>;
291
- /**
292
- * Get agent options
293
- * @internal Used by ResponseModal
294
- */
295
- getAgentOptions(): AgentOptions<TContext, TData>;
296
- /**
297
- * Get flow router
298
- * @internal Used by ResponseModal
299
- */
300
- getFlowRouter(): FlowRouter<TContext, TData>;
301
- /**
302
- * Get the updateData method bound to this agent
303
- * @internal Used by ResponseModal
304
- */
305
- getUpdateDataMethod(): (session: SessionState<TData>, dataUpdate: Partial<TData>) => Promise<SessionState<TData>>;
306
- /**
307
- * Execute a prepare or finalize function/tool
308
- * @internal Used by ResponseModal
309
- */
310
- executePrepareFinalize(prepareOrFinalize: string | Tool<TContext, TData> | ((context: TContext, data?: Partial<TData>) => void | Promise<void>) | undefined, context: TContext, data?: Partial<TData>, flow?: Flow<TContext, TData>, step?: Step<TContext, TData>): Promise<void>;
311
- /**
312
- * Get collected data from the current session (or the pre-session staging
313
- * buffer when no session exists yet). Alias of getCollectedData().
314
- */
315
- getData(): Partial<TData>;
316
- /**
317
- * Dispatch a directive (or a flow shorthand) into a session.
318
- * Sets `pendingDirective` on the session without triggering a `respond()` call.
319
- * The directive will be applied at the start of the next turn.
320
- *
321
- * String form desugars to `{ goTo: target }`.
322
- *
323
- * Durability: with a persistence adapter and autoSave configured (the
324
- * defaults), the queued directive is persisted immediately — safe for
325
- * out-of-process callers like webhooks or cron. Without an adapter it is
326
- * memory-only, as is `persistence.autoSave: false` (then persisting before
327
- * the next turn is the caller's job).
328
- *
329
- * @param target - Flow ID/title string (desugars to `{ goTo: target }`) or a full Directive
330
- * @param session - Session to update (uses current session if not provided)
331
- * @returns Updated session with `pendingDirective` set
332
- *
333
- * @throws FlowConfigurationError if the string target doesn't match any flow
334
- * @throws FlowConfigurationError if the directive fails validation
335
- * @throws SessionConflictError when persistence is enabled and another writer
336
- * moved the stored session since this copy was loaded
337
- *
338
- * @example
339
- * // String shorthand — desugars to { goTo: 'Feedback' }
340
- * const updated = await agent.dispatch('Feedback', session);
341
- *
342
- * @example
343
- * // Full directive
344
- * const updated = await agent.dispatch({ goTo: 'Billing', reply: 'Transferring you now.' }, session);
345
- */
346
- dispatch(target: string | Directive<TContext, TData>, session?: SessionState<TData>): Promise<SessionState<TData>>;
347
- /**
348
- * Apply a directive synchronously to a session without invoking `respond()`.
349
- * Performs in-place application: updates flow/step position, merges state writes.
350
- *
351
- * This is the synchronous counterpart to `dispatch` — it applies immediately
352
- * rather than deferring to the next turn.
353
- *
354
- * @param directive - The directive to apply
355
- * @param session - The session to apply the directive to
356
- * @returns The updated session with the directive applied
357
- */
358
- applyDirective(directive: Directive<TContext, TData>, session: SessionState<TData>): SessionState<TData>;
359
- /**
360
- * Validate a directive for structural correctness.
361
- * Throws FlowConfigurationError for invalid combinations.
362
- * @private
363
- */
364
- private validateDirective;
365
- /**
366
- * Strip pre-LLM-only fields (appendPrompt, injectTools, halt) from a directive.
367
- * These fields are transient (one-turn lifetime) and must not be persisted.
368
- * @private
369
- */
370
- private stripPreDirectiveFields;
371
- /**
372
- * Simplified respond method using SessionManager
373
- * Automatically manages conversation history through the session
374
- */
375
- chat(message?: string, options?: GenerateOptions<TContext>): Promise<AgentResponse<TData>>;
376
- /**
377
- * Modern streaming API - simple interface like chat() but returns a stream
378
- * Automatically manages conversation history through the session
379
- */
380
- stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>;
9
+ import type { AgentOptions, PendingWakesInput, ScheduleEntry, TurnInput, TurnResult, TurnStreamChunk } from "../types/agent.js";
10
+ export declare class Agent<C = unknown, D = unknown> {
11
+ readonly options: AgentOptions<C, D>;
12
+ private readonly runner;
13
+ private readonly understand;
14
+ private readonly speak;
15
+ private readonly compaction?;
16
+ constructor(options: AgentOptions<C, D>);
17
+ /** Take whatever just happened and return the messages to send and the timers to set. */
18
+ turn(input: TurnInput<C, D>): Promise<TurnResult<D>>;
19
+ /** `turn`, streaming the spoken text as it is generated; the last chunk carries the result. */
20
+ turnStream(input: TurnInput<C, D>): AsyncIterable<TurnStreamChunk<D>>;
21
+ /**
22
+ * Every wake a saved session is waiting on, as its turns scheduled them: each parked run's,
23
+ * and each silence flow's since the assistant last spoke. For a queue that lost its jobs, and
24
+ * for sessions no turn has armed yet, such as blobs lifted by `migrateSession`. It changes
25
+ * nothing and spends no call: enqueue the entries as you would a turn's `schedule[]`.
26
+ */
27
+ pendingWakes(input: PendingWakesInput<C, D>): ScheduleEntry[];
28
+ /** Load, Ingest, Understand, Decide and Run: everything before the one speaker is known. */
29
+ private open;
30
+ /** With `compaction` set, the history both calls see is trimmed once per turn; a summarization is one model call. */
31
+ private compacted;
381
32
  }
382
33
  //# sourceMappingURL=Agent.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAahI,qBAAa,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IAM7B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;IALhD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAoB;gBAE3B,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;IAShD,yFAAyF;IACnF,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAM1D,+FAA+F;IACxF,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAa5E;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,aAAa,EAAE;IAI7D,4FAA4F;YAC9E,IAAI;IAWlB,qHAAqH;YACvG,SAAS;CAaxB"}