groundswell 0.0.1 → 0.0.3

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 (451) hide show
  1. package/CHANGELOG.md +188 -0
  2. package/README.md +99 -5
  3. package/dist/__tests__/adversarial/attachChild-performance.test.d.ts +16 -0
  4. package/dist/__tests__/adversarial/attachChild-performance.test.d.ts.map +1 -0
  5. package/dist/__tests__/adversarial/attachChild-performance.test.js +187 -0
  6. package/dist/__tests__/adversarial/attachChild-performance.test.js.map +1 -0
  7. package/dist/__tests__/adversarial/circular-reference.test.d.ts +13 -0
  8. package/dist/__tests__/adversarial/circular-reference.test.d.ts.map +1 -0
  9. package/dist/__tests__/adversarial/circular-reference.test.js +92 -0
  10. package/dist/__tests__/adversarial/circular-reference.test.js.map +1 -0
  11. package/dist/__tests__/adversarial/complex-circular-reference.test.d.ts +16 -0
  12. package/dist/__tests__/adversarial/complex-circular-reference.test.d.ts.map +1 -0
  13. package/dist/__tests__/adversarial/complex-circular-reference.test.js +127 -0
  14. package/dist/__tests__/adversarial/complex-circular-reference.test.js.map +1 -0
  15. package/dist/__tests__/adversarial/concurrent-task-failures.test.d.ts +21 -0
  16. package/dist/__tests__/adversarial/concurrent-task-failures.test.d.ts.map +1 -0
  17. package/dist/__tests__/adversarial/concurrent-task-failures.test.js +667 -0
  18. package/dist/__tests__/adversarial/concurrent-task-failures.test.js.map +1 -0
  19. package/dist/__tests__/adversarial/deep-analysis.test.d.ts +6 -0
  20. package/dist/__tests__/adversarial/deep-analysis.test.d.ts.map +1 -0
  21. package/dist/__tests__/adversarial/deep-analysis.test.js +877 -0
  22. package/dist/__tests__/adversarial/deep-analysis.test.js.map +1 -0
  23. package/dist/__tests__/adversarial/deep-hierarchy-stress.test.d.ts +13 -0
  24. package/dist/__tests__/adversarial/deep-hierarchy-stress.test.d.ts.map +1 -0
  25. package/dist/__tests__/adversarial/deep-hierarchy-stress.test.js +186 -0
  26. package/dist/__tests__/adversarial/deep-hierarchy-stress.test.js.map +1 -0
  27. package/dist/__tests__/adversarial/e2e-prd-validation.test.d.ts +6 -0
  28. package/dist/__tests__/adversarial/e2e-prd-validation.test.d.ts.map +1 -0
  29. package/dist/__tests__/adversarial/e2e-prd-validation.test.js +626 -0
  30. package/dist/__tests__/adversarial/e2e-prd-validation.test.js.map +1 -0
  31. package/dist/__tests__/adversarial/edge-case.test.d.ts +6 -0
  32. package/dist/__tests__/adversarial/edge-case.test.d.ts.map +1 -0
  33. package/dist/__tests__/adversarial/edge-case.test.js +857 -0
  34. package/dist/__tests__/adversarial/edge-case.test.js.map +1 -0
  35. package/dist/__tests__/adversarial/error-merge-strategy.test.d.ts +20 -0
  36. package/dist/__tests__/adversarial/error-merge-strategy.test.d.ts.map +1 -0
  37. package/dist/__tests__/adversarial/error-merge-strategy.test.js +907 -0
  38. package/dist/__tests__/adversarial/error-merge-strategy.test.js.map +1 -0
  39. package/dist/__tests__/adversarial/incremental-performance.test.d.ts +2 -0
  40. package/dist/__tests__/adversarial/incremental-performance.test.d.ts.map +1 -0
  41. package/dist/__tests__/adversarial/incremental-performance.test.js +113 -0
  42. package/dist/__tests__/adversarial/incremental-performance.test.js.map +1 -0
  43. package/dist/__tests__/adversarial/node-map-update-benchmarks.test.d.ts +22 -0
  44. package/dist/__tests__/adversarial/node-map-update-benchmarks.test.d.ts.map +1 -0
  45. package/dist/__tests__/adversarial/node-map-update-benchmarks.test.js +383 -0
  46. package/dist/__tests__/adversarial/node-map-update-benchmarks.test.js.map +1 -0
  47. package/dist/__tests__/adversarial/observer-propagation.test.d.ts +21 -0
  48. package/dist/__tests__/adversarial/observer-propagation.test.d.ts.map +1 -0
  49. package/dist/__tests__/adversarial/observer-propagation.test.js +404 -0
  50. package/dist/__tests__/adversarial/observer-propagation.test.js.map +1 -0
  51. package/dist/__tests__/adversarial/parent-validation.test.d.ts +13 -0
  52. package/dist/__tests__/adversarial/parent-validation.test.d.ts.map +1 -0
  53. package/dist/__tests__/adversarial/parent-validation.test.js +128 -0
  54. package/dist/__tests__/adversarial/parent-validation.test.js.map +1 -0
  55. package/dist/__tests__/adversarial/prd-12-2-compliance.test.d.ts +20 -0
  56. package/dist/__tests__/adversarial/prd-12-2-compliance.test.d.ts.map +1 -0
  57. package/dist/__tests__/adversarial/prd-12-2-compliance.test.js +482 -0
  58. package/dist/__tests__/adversarial/prd-12-2-compliance.test.js.map +1 -0
  59. package/dist/__tests__/adversarial/prd-compliance.test.d.ts +6 -0
  60. package/dist/__tests__/adversarial/prd-compliance.test.d.ts.map +1 -0
  61. package/dist/__tests__/adversarial/prd-compliance.test.js +886 -0
  62. package/dist/__tests__/adversarial/prd-compliance.test.js.map +1 -0
  63. package/dist/__tests__/compatibility/backward-compatibility.test.d.ts +22 -0
  64. package/dist/__tests__/compatibility/backward-compatibility.test.d.ts.map +1 -0
  65. package/dist/__tests__/compatibility/backward-compatibility.test.js +1843 -0
  66. package/dist/__tests__/compatibility/backward-compatibility.test.js.map +1 -0
  67. package/dist/__tests__/helpers/index.d.ts +10 -0
  68. package/dist/__tests__/helpers/index.d.ts.map +1 -0
  69. package/dist/__tests__/helpers/index.js +10 -0
  70. package/dist/__tests__/helpers/index.js.map +1 -0
  71. package/dist/__tests__/helpers/tree-verification.d.ts +90 -0
  72. package/dist/__tests__/helpers/tree-verification.d.ts.map +1 -0
  73. package/dist/__tests__/helpers/tree-verification.js +202 -0
  74. package/dist/__tests__/helpers/tree-verification.js.map +1 -0
  75. package/dist/__tests__/integration/agent-workflow.test.d.ts +2 -0
  76. package/dist/__tests__/integration/agent-workflow.test.d.ts.map +1 -0
  77. package/dist/__tests__/integration/agent-workflow.test.js +256 -0
  78. package/dist/__tests__/integration/agent-workflow.test.js.map +1 -0
  79. package/dist/__tests__/integration/bidirectional-consistency.test.d.ts +14 -0
  80. package/dist/__tests__/integration/bidirectional-consistency.test.d.ts.map +1 -0
  81. package/dist/__tests__/integration/bidirectional-consistency.test.js +668 -0
  82. package/dist/__tests__/integration/bidirectional-consistency.test.js.map +1 -0
  83. package/dist/__tests__/integration/observer-logging.test.d.ts +2 -0
  84. package/dist/__tests__/integration/observer-logging.test.d.ts.map +1 -0
  85. package/dist/__tests__/integration/observer-logging.test.js +517 -0
  86. package/dist/__tests__/integration/observer-logging.test.js.map +1 -0
  87. package/dist/__tests__/integration/tree-mirroring.test.d.ts +2 -0
  88. package/dist/__tests__/integration/tree-mirroring.test.d.ts.map +1 -0
  89. package/dist/__tests__/integration/tree-mirroring.test.js +117 -0
  90. package/dist/__tests__/integration/tree-mirroring.test.js.map +1 -0
  91. package/dist/__tests__/integration/workflow-reparenting.test.d.ts +12 -0
  92. package/dist/__tests__/integration/workflow-reparenting.test.d.ts.map +1 -0
  93. package/dist/__tests__/integration/workflow-reparenting.test.js +239 -0
  94. package/dist/__tests__/integration/workflow-reparenting.test.js.map +1 -0
  95. package/dist/__tests__/unit/agent.test.d.ts +2 -0
  96. package/dist/__tests__/unit/agent.test.d.ts.map +1 -0
  97. package/dist/__tests__/unit/agent.test.js +143 -0
  98. package/dist/__tests__/unit/agent.test.js.map +1 -0
  99. package/dist/__tests__/unit/cache-key.test.d.ts +5 -0
  100. package/dist/__tests__/unit/cache-key.test.d.ts.map +1 -0
  101. package/dist/__tests__/unit/cache-key.test.js +145 -0
  102. package/dist/__tests__/unit/cache-key.test.js.map +1 -0
  103. package/dist/__tests__/unit/cache.test.d.ts +5 -0
  104. package/dist/__tests__/unit/cache.test.d.ts.map +1 -0
  105. package/dist/__tests__/unit/cache.test.js +132 -0
  106. package/dist/__tests__/unit/cache.test.js.map +1 -0
  107. package/dist/__tests__/unit/context.test.d.ts +2 -0
  108. package/dist/__tests__/unit/context.test.d.ts.map +1 -0
  109. package/dist/__tests__/unit/context.test.js +220 -0
  110. package/dist/__tests__/unit/context.test.js.map +1 -0
  111. package/dist/__tests__/unit/decorators.test.d.ts +2 -0
  112. package/dist/__tests__/unit/decorators.test.d.ts.map +1 -0
  113. package/dist/__tests__/unit/decorators.test.js +162 -0
  114. package/dist/__tests__/unit/decorators.test.js.map +1 -0
  115. package/dist/__tests__/unit/introspection-tools.test.d.ts +5 -0
  116. package/dist/__tests__/unit/introspection-tools.test.d.ts.map +1 -0
  117. package/dist/__tests__/unit/introspection-tools.test.js +191 -0
  118. package/dist/__tests__/unit/introspection-tools.test.js.map +1 -0
  119. package/dist/__tests__/unit/logger.test.d.ts +2 -0
  120. package/dist/__tests__/unit/logger.test.d.ts.map +1 -0
  121. package/dist/__tests__/unit/logger.test.js +241 -0
  122. package/dist/__tests__/unit/logger.test.js.map +1 -0
  123. package/dist/__tests__/unit/observable.test.d.ts +2 -0
  124. package/dist/__tests__/unit/observable.test.d.ts.map +1 -0
  125. package/dist/__tests__/unit/observable.test.js +251 -0
  126. package/dist/__tests__/unit/observable.test.js.map +1 -0
  127. package/dist/__tests__/unit/prompt.test.d.ts +2 -0
  128. package/dist/__tests__/unit/prompt.test.d.ts.map +1 -0
  129. package/dist/__tests__/unit/prompt.test.js +113 -0
  130. package/dist/__tests__/unit/prompt.test.js.map +1 -0
  131. package/dist/__tests__/unit/reflection.test.d.ts +5 -0
  132. package/dist/__tests__/unit/reflection.test.d.ts.map +1 -0
  133. package/dist/__tests__/unit/reflection.test.js +160 -0
  134. package/dist/__tests__/unit/reflection.test.js.map +1 -0
  135. package/dist/__tests__/unit/tree-debugger-incremental.test.d.ts +2 -0
  136. package/dist/__tests__/unit/tree-debugger-incremental.test.d.ts.map +1 -0
  137. package/dist/__tests__/unit/tree-debugger-incremental.test.js +136 -0
  138. package/dist/__tests__/unit/tree-debugger-incremental.test.js.map +1 -0
  139. package/dist/__tests__/unit/tree-debugger.test.d.ts +2 -0
  140. package/dist/__tests__/unit/tree-debugger.test.d.ts.map +1 -0
  141. package/dist/__tests__/unit/tree-debugger.test.js +69 -0
  142. package/dist/__tests__/unit/tree-debugger.test.js.map +1 -0
  143. package/dist/__tests__/unit/utils/workflow-error-utils.test.d.ts +2 -0
  144. package/dist/__tests__/unit/utils/workflow-error-utils.test.d.ts.map +1 -0
  145. package/dist/__tests__/unit/utils/workflow-error-utils.test.js +154 -0
  146. package/dist/__tests__/unit/utils/workflow-error-utils.test.js.map +1 -0
  147. package/dist/__tests__/unit/workflow-detachChild.test.d.ts +2 -0
  148. package/dist/__tests__/unit/workflow-detachChild.test.d.ts.map +1 -0
  149. package/dist/__tests__/unit/workflow-detachChild.test.js +76 -0
  150. package/dist/__tests__/unit/workflow-detachChild.test.js.map +1 -0
  151. package/dist/__tests__/unit/workflow-emitEvent-childDetached.test.d.ts +2 -0
  152. package/dist/__tests__/unit/workflow-emitEvent-childDetached.test.d.ts.map +1 -0
  153. package/dist/__tests__/unit/workflow-emitEvent-childDetached.test.js +122 -0
  154. package/dist/__tests__/unit/workflow-emitEvent-childDetached.test.js.map +1 -0
  155. package/dist/__tests__/unit/workflow-isDescendantOf.test.d.ts +2 -0
  156. package/dist/__tests__/unit/workflow-isDescendantOf.test.d.ts.map +1 -0
  157. package/dist/__tests__/unit/workflow-isDescendantOf.test.js +140 -0
  158. package/dist/__tests__/unit/workflow-isDescendantOf.test.js.map +1 -0
  159. package/dist/__tests__/unit/workflow.test.d.ts +2 -0
  160. package/dist/__tests__/unit/workflow.test.d.ts.map +1 -0
  161. package/dist/__tests__/unit/workflow.test.js +330 -0
  162. package/dist/__tests__/unit/workflow.test.js.map +1 -0
  163. package/dist/cache/cache-key.d.ts +66 -0
  164. package/dist/cache/cache-key.d.ts.map +1 -0
  165. package/dist/cache/cache-key.js +195 -0
  166. package/dist/cache/cache-key.js.map +1 -0
  167. package/dist/cache/cache.d.ts +104 -0
  168. package/dist/cache/cache.d.ts.map +1 -0
  169. package/dist/cache/cache.js +179 -0
  170. package/dist/cache/cache.js.map +1 -0
  171. package/{src/cache/index.ts → dist/cache/index.d.ts} +1 -1
  172. package/dist/cache/index.d.ts.map +1 -0
  173. package/dist/cache/index.js +6 -0
  174. package/dist/cache/index.js.map +1 -0
  175. package/dist/core/agent.d.ts +112 -0
  176. package/dist/core/agent.d.ts.map +1 -0
  177. package/dist/core/agent.js +426 -0
  178. package/dist/core/agent.js.map +1 -0
  179. package/{src/core/context.ts → dist/core/context.d.ts} +16 -67
  180. package/dist/core/context.d.ts.map +1 -0
  181. package/dist/core/context.js +80 -0
  182. package/dist/core/context.js.map +1 -0
  183. package/dist/core/event-tree.d.ts +72 -0
  184. package/dist/core/event-tree.d.ts.map +1 -0
  185. package/dist/core/event-tree.js +211 -0
  186. package/dist/core/event-tree.js.map +1 -0
  187. package/{src/core/factory.ts → dist/core/factory.d.ts} +6 -27
  188. package/dist/core/factory.d.ts.map +1 -0
  189. package/dist/core/factory.js +110 -0
  190. package/dist/core/factory.js.map +1 -0
  191. package/{src/core/index.ts → dist/core/index.d.ts} +2 -10
  192. package/dist/core/index.d.ts.map +1 -0
  193. package/dist/core/index.js +9 -0
  194. package/dist/core/index.js.map +1 -0
  195. package/dist/core/logger.d.ts +50 -0
  196. package/dist/core/logger.d.ts.map +1 -0
  197. package/dist/core/logger.js +91 -0
  198. package/dist/core/logger.js.map +1 -0
  199. package/dist/core/mcp-handler.d.ts +69 -0
  200. package/dist/core/mcp-handler.d.ts.map +1 -0
  201. package/dist/core/mcp-handler.js +143 -0
  202. package/dist/core/mcp-handler.js.map +1 -0
  203. package/dist/core/prompt.d.ts +80 -0
  204. package/dist/core/prompt.d.ts.map +1 -0
  205. package/dist/core/prompt.js +120 -0
  206. package/dist/core/prompt.js.map +1 -0
  207. package/dist/core/workflow-context.d.ts +57 -0
  208. package/dist/core/workflow-context.d.ts.map +1 -0
  209. package/dist/core/workflow-context.js +263 -0
  210. package/dist/core/workflow-context.js.map +1 -0
  211. package/dist/core/workflow.d.ts +241 -0
  212. package/dist/core/workflow.d.ts.map +1 -0
  213. package/dist/core/workflow.js +464 -0
  214. package/dist/core/workflow.js.map +1 -0
  215. package/dist/debugger/index.d.ts +2 -0
  216. package/dist/debugger/index.d.ts.map +1 -0
  217. package/{src/debugger/index.ts → dist/debugger/index.js} +1 -0
  218. package/dist/debugger/index.js.map +1 -0
  219. package/dist/debugger/tree-debugger.d.ts +71 -0
  220. package/dist/debugger/tree-debugger.d.ts.map +1 -0
  221. package/dist/debugger/tree-debugger.js +198 -0
  222. package/dist/debugger/tree-debugger.js.map +1 -0
  223. package/dist/decorators/index.d.ts +4 -0
  224. package/dist/decorators/index.d.ts.map +1 -0
  225. package/{src/decorators/index.ts → dist/decorators/index.js} +1 -0
  226. package/dist/decorators/index.js.map +1 -0
  227. package/dist/decorators/observed-state.d.ts +32 -0
  228. package/dist/decorators/observed-state.d.ts.map +1 -0
  229. package/dist/decorators/observed-state.js +79 -0
  230. package/dist/decorators/observed-state.js.map +1 -0
  231. package/dist/decorators/step.d.ts +15 -0
  232. package/dist/decorators/step.d.ts.map +1 -0
  233. package/dist/decorators/step.js +110 -0
  234. package/dist/decorators/step.js.map +1 -0
  235. package/dist/decorators/task.d.ts +50 -0
  236. package/dist/decorators/task.d.ts.map +1 -0
  237. package/dist/decorators/task.js +118 -0
  238. package/dist/decorators/task.js.map +1 -0
  239. package/dist/examples/index.d.ts +3 -0
  240. package/dist/examples/index.d.ts.map +1 -0
  241. package/{src/examples/index.ts → dist/examples/index.js} +1 -0
  242. package/dist/examples/index.js.map +1 -0
  243. package/dist/examples/tdd-orchestrator.d.ts +15 -0
  244. package/dist/examples/tdd-orchestrator.d.ts.map +1 -0
  245. package/dist/examples/tdd-orchestrator.js +121 -0
  246. package/dist/examples/tdd-orchestrator.js.map +1 -0
  247. package/dist/examples/test-cycle-workflow.d.ts +14 -0
  248. package/dist/examples/test-cycle-workflow.d.ts.map +1 -0
  249. package/dist/examples/test-cycle-workflow.js +116 -0
  250. package/dist/examples/test-cycle-workflow.js.map +1 -0
  251. package/dist/index.d.ts +27 -0
  252. package/dist/index.d.ts.map +1 -0
  253. package/dist/index.js +40 -0
  254. package/dist/index.js.map +1 -0
  255. package/dist/reflection/index.d.ts +5 -0
  256. package/dist/reflection/index.d.ts.map +1 -0
  257. package/{src/reflection/index.ts → dist/reflection/index.js} +1 -1
  258. package/dist/reflection/index.js.map +1 -0
  259. package/dist/reflection/reflection.d.ts +84 -0
  260. package/dist/reflection/reflection.d.ts.map +1 -0
  261. package/dist/reflection/reflection.js +329 -0
  262. package/dist/reflection/reflection.js.map +1 -0
  263. package/dist/tools/index.d.ts +6 -0
  264. package/dist/tools/index.d.ts.map +1 -0
  265. package/dist/tools/index.js +11 -0
  266. package/dist/tools/index.js.map +1 -0
  267. package/dist/tools/introspection.d.ts +165 -0
  268. package/dist/tools/introspection.d.ts.map +1 -0
  269. package/dist/tools/introspection.js +324 -0
  270. package/dist/tools/introspection.js.map +1 -0
  271. package/dist/types/agent.d.ts +66 -0
  272. package/dist/types/agent.d.ts.map +1 -0
  273. package/dist/types/agent.js +6 -0
  274. package/dist/types/agent.js.map +1 -0
  275. package/dist/types/decorators.d.ts +31 -0
  276. package/dist/types/decorators.d.ts.map +1 -0
  277. package/dist/types/decorators.js +2 -0
  278. package/dist/types/decorators.js.map +1 -0
  279. package/dist/types/error-strategy.d.ts +13 -0
  280. package/dist/types/error-strategy.d.ts.map +1 -0
  281. package/dist/types/error-strategy.js +2 -0
  282. package/dist/types/error-strategy.js.map +1 -0
  283. package/dist/types/error.d.ts +20 -0
  284. package/dist/types/error.d.ts.map +1 -0
  285. package/dist/types/error.js +2 -0
  286. package/dist/types/error.js.map +1 -0
  287. package/dist/types/events.d.ts +87 -0
  288. package/dist/types/events.d.ts.map +1 -0
  289. package/dist/types/events.js +2 -0
  290. package/dist/types/events.js.map +1 -0
  291. package/dist/types/index.d.ts +15 -0
  292. package/dist/types/index.d.ts.map +1 -0
  293. package/dist/types/index.js +2 -0
  294. package/dist/types/index.js.map +1 -0
  295. package/dist/types/logging.d.ts +24 -0
  296. package/dist/types/logging.d.ts.map +1 -0
  297. package/dist/types/logging.js +2 -0
  298. package/dist/types/logging.js.map +1 -0
  299. package/dist/types/observer.d.ts +18 -0
  300. package/dist/types/observer.d.ts.map +1 -0
  301. package/dist/types/observer.js +2 -0
  302. package/dist/types/observer.js.map +1 -0
  303. package/dist/types/prompt.d.ts +31 -0
  304. package/dist/types/prompt.d.ts.map +1 -0
  305. package/dist/types/prompt.js +6 -0
  306. package/dist/types/prompt.js.map +1 -0
  307. package/dist/types/reflection.d.ts +96 -0
  308. package/dist/types/reflection.d.ts.map +1 -0
  309. package/dist/types/reflection.js +24 -0
  310. package/dist/types/reflection.js.map +1 -0
  311. package/dist/types/sdk-primitives.d.ts +118 -0
  312. package/dist/types/sdk-primitives.d.ts.map +1 -0
  313. package/dist/types/sdk-primitives.js +6 -0
  314. package/dist/types/sdk-primitives.js.map +1 -0
  315. package/{src/types/snapshot.ts → dist/types/snapshot.d.ts} +5 -5
  316. package/dist/types/snapshot.d.ts.map +1 -0
  317. package/dist/types/snapshot.js +2 -0
  318. package/dist/types/snapshot.js.map +1 -0
  319. package/dist/types/workflow-context.d.ts +139 -0
  320. package/dist/types/workflow-context.d.ts.map +1 -0
  321. package/dist/types/workflow-context.js +8 -0
  322. package/dist/types/workflow-context.js.map +1 -0
  323. package/dist/types/workflow.d.ts +30 -0
  324. package/dist/types/workflow.d.ts.map +1 -0
  325. package/dist/types/workflow.js +2 -0
  326. package/dist/types/workflow.js.map +1 -0
  327. package/dist/utils/id.d.ts +6 -0
  328. package/dist/utils/id.d.ts.map +1 -0
  329. package/dist/utils/id.js +12 -0
  330. package/dist/utils/id.js.map +1 -0
  331. package/{src/utils/index.ts → dist/utils/index.d.ts} +2 -0
  332. package/dist/utils/index.d.ts.map +1 -0
  333. package/dist/utils/index.js +4 -0
  334. package/dist/utils/index.js.map +1 -0
  335. package/dist/utils/observable.d.ts +54 -0
  336. package/dist/utils/observable.d.ts.map +1 -0
  337. package/dist/utils/observable.js +82 -0
  338. package/dist/utils/observable.js.map +1 -0
  339. package/dist/utils/workflow-error-utils.d.ts +22 -0
  340. package/dist/utils/workflow-error-utils.d.ts.map +1 -0
  341. package/dist/utils/workflow-error-utils.js +45 -0
  342. package/dist/utils/workflow-error-utils.js.map +1 -0
  343. package/package.json +7 -2
  344. package/.claude/settings.local.json +0 -9
  345. package/.claude/system_prompts/task-breakdown.md +0 -100
  346. package/PRPs/001-hierarchical-workflow-engine.md +0 -2438
  347. package/PRPs/PRDs/001-hierarchical-workflow-engine.md +0 -543
  348. package/PRPs/PRDs/002-agent-prompt.md +0 -390
  349. package/PRPs/PRDs/003-agent-prompt.md +0 -943
  350. package/PRPs/PRDs/004-agent-prompt.md +0 -1136
  351. package/PRPs/PRDs/tasks-001.json +0 -492
  352. package/PRPs/README.md +0 -83
  353. package/PRPs/templates/prp_base.md +0 -222
  354. package/docs/agent.md +0 -422
  355. package/docs/prompt.md +0 -419
  356. package/docs/workflow.md +0 -600
  357. package/examples/README.md +0 -244
  358. package/examples/examples/01-basic-workflow.ts +0 -100
  359. package/examples/examples/02-decorator-options.ts +0 -217
  360. package/examples/examples/03-parent-child.ts +0 -241
  361. package/examples/examples/04-observers-debugger.ts +0 -340
  362. package/examples/examples/05-error-handling.ts +0 -387
  363. package/examples/examples/06-concurrent-tasks.ts +0 -352
  364. package/examples/examples/07-agent-loops.ts +0 -432
  365. package/examples/examples/08-sdk-features.ts +0 -667
  366. package/examples/examples/09-reflection.ts +0 -573
  367. package/examples/examples/10-introspection.ts +0 -550
  368. package/examples/index.ts +0 -143
  369. package/examples/utils/helpers.ts +0 -57
  370. package/llms_full.txt +0 -5890
  371. package/plan/P1P2/PRP.md +0 -527
  372. package/plan/P1P2/research/LRU_CACHE_BEST_PRACTICES.md +0 -1929
  373. package/plan/P1P2/research/LRU_CACHE_CODE_PATTERNS.md +0 -857
  374. package/plan/P1P2/research/LRU_CACHE_INTEGRATION_GUIDE.md +0 -738
  375. package/plan/P1P2/research/LRU_CACHE_RESEARCH_INDEX.md +0 -424
  376. package/plan/P1P2/research/REFLECTION_INDEX.md +0 -291
  377. package/plan/P1P2/research/REFLECTION_RESEARCH_REPORT.md +0 -1342
  378. package/plan/P1P2/research/RESEARCH_SUMMARY.md +0 -342
  379. package/plan/P1P2/research/anthropic-sdk.md +0 -174
  380. package/plan/P1P2/research/async-local-storage.md +0 -200
  381. package/plan/P1P2/research/reflection-code-patterns.md +0 -1205
  382. package/plan/P1P2/research/reflection-decision-matrix.md +0 -421
  383. package/plan/P1P2/research/reflection-implementation-guide.md +0 -1341
  384. package/plan/P1P2/research/reflection-integration-guide.md +0 -834
  385. package/plan/P1P2/research/reflection-patterns.md +0 -1468
  386. package/plan/P1P2/research/reflection-quick-reference.md +0 -558
  387. package/plan/P1P2/research/zod-schema.md +0 -152
  388. package/plan/P3P4/PRP.md +0 -1388
  389. package/plan/P3P4/research/caching-lru.md +0 -116
  390. package/plan/P3P4/research/introspection-tools.md +0 -177
  391. package/plan/P3P4/research/reflection-patterns.md +0 -117
  392. package/plan/P4P5/PRP.md +0 -1136
  393. package/plan/P4P5/research/RESEARCH_SUMMARY.md +0 -151
  394. package/plan/architecture/external_deps.md +0 -358
  395. package/plan/architecture/system_context.md +0 -242
  396. package/plan/backlog.json +0 -867
  397. package/plan/research/INTROSPECTION_RESEARCH_SUMMARY.md +0 -378
  398. package/plan/research/README-INTROSPECTION.md +0 -352
  399. package/plan/research/agent-introspection-patterns.md +0 -1085
  400. package/plan/research/introspection-security-guide.md +0 -928
  401. package/plan/research/introspection-tool-examples.md +0 -875
  402. package/scripts/generate-llms-full.ts +0 -206
  403. package/src/__tests__/integration/agent-workflow.test.ts +0 -256
  404. package/src/__tests__/integration/tree-mirroring.test.ts +0 -114
  405. package/src/__tests__/unit/agent.test.ts +0 -169
  406. package/src/__tests__/unit/cache-key.test.ts +0 -182
  407. package/src/__tests__/unit/cache.test.ts +0 -172
  408. package/src/__tests__/unit/context.test.ts +0 -138
  409. package/src/__tests__/unit/decorators.test.ts +0 -100
  410. package/src/__tests__/unit/introspection-tools.test.ts +0 -277
  411. package/src/__tests__/unit/prompt.test.ts +0 -135
  412. package/src/__tests__/unit/reflection.test.ts +0 -210
  413. package/src/__tests__/unit/tree-debugger.test.ts +0 -85
  414. package/src/__tests__/unit/workflow.test.ts +0 -81
  415. package/src/cache/cache-key.ts +0 -244
  416. package/src/cache/cache.ts +0 -236
  417. package/src/core/agent.ts +0 -573
  418. package/src/core/event-tree.ts +0 -260
  419. package/src/core/logger.ts +0 -87
  420. package/src/core/mcp-handler.ts +0 -184
  421. package/src/core/prompt.ts +0 -150
  422. package/src/core/workflow-context.ts +0 -349
  423. package/src/core/workflow.ts +0 -302
  424. package/src/debugger/tree-debugger.ts +0 -210
  425. package/src/decorators/observed-state.ts +0 -95
  426. package/src/decorators/step.ts +0 -139
  427. package/src/decorators/task.ts +0 -96
  428. package/src/examples/tdd-orchestrator.ts +0 -65
  429. package/src/examples/test-cycle-workflow.ts +0 -64
  430. package/src/index.ts +0 -140
  431. package/src/reflection/reflection.ts +0 -407
  432. package/src/tools/index.ts +0 -36
  433. package/src/tools/introspection.ts +0 -464
  434. package/src/types/agent.ts +0 -90
  435. package/src/types/decorators.ts +0 -25
  436. package/src/types/error-strategy.ts +0 -13
  437. package/src/types/error.ts +0 -20
  438. package/src/types/events.ts +0 -74
  439. package/src/types/index.ts +0 -55
  440. package/src/types/logging.ts +0 -24
  441. package/src/types/observer.ts +0 -18
  442. package/src/types/prompt.ts +0 -40
  443. package/src/types/reflection.ts +0 -117
  444. package/src/types/sdk-primitives.ts +0 -128
  445. package/src/types/workflow-context.ts +0 -163
  446. package/src/types/workflow.ts +0 -37
  447. package/src/utils/id.ts +0 -11
  448. package/src/utils/observable.ts +0 -77
  449. package/tasks.json +0 -0
  450. package/tsconfig.json +0 -22
  451. package/vitest.config.ts +0 -16
@@ -0,0 +1,198 @@
1
+ import { Observable } from '../utils/observable.js';
2
+ /**
3
+ * Status symbols for tree visualization
4
+ */
5
+ const STATUS_SYMBOLS = {
6
+ idle: '○',
7
+ running: '◐',
8
+ completed: '✓',
9
+ failed: '✗',
10
+ cancelled: '⊘',
11
+ };
12
+ /**
13
+ * Tree debugger for real-time workflow visualization
14
+ * Implements WorkflowObserver to receive all events
15
+ */
16
+ export class WorkflowTreeDebugger {
17
+ /** Root node of the workflow tree */
18
+ root;
19
+ /** Observable stream of workflow events */
20
+ events;
21
+ /** Node lookup map for quick access */
22
+ nodeMap = new Map();
23
+ /**
24
+ * Create a tree debugger attached to a workflow
25
+ * @param workflow The root workflow to debug
26
+ */
27
+ constructor(workflow) {
28
+ this.root = workflow.getNode();
29
+ this.events = new Observable();
30
+ // Build initial node map
31
+ this.buildNodeMap(this.root);
32
+ // Register as observer on the workflow
33
+ workflow.addObserver(this);
34
+ }
35
+ /**
36
+ * Build node lookup map recursively
37
+ */
38
+ buildNodeMap(node) {
39
+ this.nodeMap.set(node.id, node);
40
+ for (const child of node.children) {
41
+ this.buildNodeMap(child);
42
+ }
43
+ }
44
+ /**
45
+ * Remove entire subtree from node map using BFS traversal
46
+ * O(k) complexity where k = number of nodes in subtree
47
+ * Uses iterative BFS to avoid stack overflow on deep trees
48
+ */
49
+ removeSubtreeNodes(nodeId) {
50
+ const node = this.nodeMap.get(nodeId);
51
+ if (!node)
52
+ return; // Already removed or never existed
53
+ // BFS traversal to collect all descendant IDs
54
+ const toRemove = [];
55
+ const queue = [node];
56
+ while (queue.length > 0) {
57
+ const current = queue.shift();
58
+ toRemove.push(current.id);
59
+ // Add children to queue for BFS traversal
60
+ queue.push(...current.children);
61
+ }
62
+ // Batch delete all collected keys (atomic update)
63
+ for (const id of toRemove) {
64
+ this.nodeMap.delete(id);
65
+ }
66
+ }
67
+ // WorkflowObserver implementation
68
+ onLog(_entry) {
69
+ // Events are forwarded through the event stream
70
+ }
71
+ onEvent(event) {
72
+ // Handle structural events with incremental updates
73
+ switch (event.type) {
74
+ case 'childAttached':
75
+ // Keep existing logic - already optimal O(k)
76
+ this.buildNodeMap(event.child);
77
+ break;
78
+ case 'childDetached':
79
+ // NEW: Incremental subtree removal
80
+ this.removeSubtreeNodes(event.childId);
81
+ break;
82
+ case 'treeUpdated':
83
+ // NEW: Update root reference only
84
+ this.root = event.root;
85
+ break;
86
+ default:
87
+ // Non-structural events - no map update needed
88
+ break;
89
+ }
90
+ // Always forward to event stream (existing behavior)
91
+ this.events.next(event);
92
+ }
93
+ onStateUpdated(_node) {
94
+ // State updates are available through the node
95
+ }
96
+ onTreeChanged(root) {
97
+ // All tree changes now handled incrementally in onEvent()
98
+ // Just update root reference if different
99
+ if (this.root !== root) {
100
+ this.root = root;
101
+ }
102
+ }
103
+ // Public API
104
+ /**
105
+ * Get the current tree root
106
+ */
107
+ getTree() {
108
+ return this.root;
109
+ }
110
+ /**
111
+ * Get a node by ID
112
+ */
113
+ getNode(id) {
114
+ return this.nodeMap.get(id);
115
+ }
116
+ /**
117
+ * Render tree as ASCII string
118
+ * @param node Starting node (defaults to root)
119
+ */
120
+ toTreeString(node) {
121
+ return this.renderTree(node ?? this.root, '', true, true);
122
+ }
123
+ /**
124
+ * Recursive tree rendering
125
+ */
126
+ renderTree(node, prefix, isLast, isRoot) {
127
+ let result = '';
128
+ // Status symbol and color indicator
129
+ const statusSymbol = STATUS_SYMBOLS[node.status] || '?';
130
+ const nodeInfo = `${statusSymbol} ${node.name} [${node.status}]`;
131
+ if (isRoot) {
132
+ result += nodeInfo + '\n';
133
+ }
134
+ else {
135
+ const connector = isLast ? '└── ' : '├── ';
136
+ result += prefix + connector + nodeInfo + '\n';
137
+ }
138
+ // Render children
139
+ const childCount = node.children.length;
140
+ node.children.forEach((child, index) => {
141
+ const isLastChild = index === childCount - 1;
142
+ const childPrefix = isRoot ? '' : prefix + (isLast ? ' ' : '│ ');
143
+ result += this.renderTree(child, childPrefix, isLastChild, false);
144
+ });
145
+ return result;
146
+ }
147
+ /**
148
+ * Render logs as formatted string
149
+ * @param node Starting node (defaults to root, includes descendants)
150
+ */
151
+ toLogString(node) {
152
+ const logs = this.collectLogs(node ?? this.root);
153
+ // Sort by timestamp
154
+ logs.sort((a, b) => a.timestamp - b.timestamp);
155
+ return logs
156
+ .map((log) => {
157
+ const time = new Date(log.timestamp).toISOString();
158
+ const level = log.level.toUpperCase().padEnd(5);
159
+ const nodeRef = this.nodeMap.get(log.workflowId);
160
+ const nodeName = nodeRef?.name ?? log.workflowId;
161
+ return `[${time}] ${level} [${nodeName}] ${log.message}`;
162
+ })
163
+ .join('\n');
164
+ }
165
+ /**
166
+ * Collect all logs from a node and its descendants
167
+ */
168
+ collectLogs(node) {
169
+ const logs = [...node.logs];
170
+ for (const child of node.children) {
171
+ logs.push(...this.collectLogs(child));
172
+ }
173
+ return logs;
174
+ }
175
+ /**
176
+ * Get summary statistics for the tree
177
+ */
178
+ getStats() {
179
+ const stats = {
180
+ totalNodes: 0,
181
+ byStatus: {},
182
+ totalLogs: 0,
183
+ totalEvents: 0,
184
+ };
185
+ this.collectStats(this.root, stats);
186
+ return stats;
187
+ }
188
+ collectStats(node, stats) {
189
+ stats.totalNodes++;
190
+ stats.byStatus[node.status] = (stats.byStatus[node.status] || 0) + 1;
191
+ stats.totalLogs += node.logs.length;
192
+ stats.totalEvents += node.events.length;
193
+ for (const child of node.children) {
194
+ this.collectStats(child, stats);
195
+ }
196
+ }
197
+ }
198
+ //# sourceMappingURL=tree-debugger.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tree-debugger.js","sourceRoot":"","sources":["../../src/debugger/tree-debugger.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,4 @@
1
+ export { ObservedState, getObservedState, isFieldObserved, getFieldMetadata } from './observed-state.js';
2
+ export { Step } from './step.js';
3
+ export { Task } from './task.js';
4
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACzG,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC"}
@@ -1,3 +1,4 @@
1
1
  export { ObservedState, getObservedState, isFieldObserved, getFieldMetadata } from './observed-state.js';
2
2
  export { Step } from './step.js';
3
3
  export { Task } from './task.js';
4
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACzG,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC"}
@@ -0,0 +1,32 @@
1
+ import type { StateFieldMetadata, SerializedWorkflowState } from '../types/index.js';
2
+ /**
3
+ * @ObservedState decorator
4
+ * Marks a class field for inclusion in state snapshots
5
+ *
6
+ * @example
7
+ * class MyWorkflow extends Workflow {
8
+ * @ObservedState()
9
+ * currentStep!: string;
10
+ *
11
+ * @ObservedState({ redact: true })
12
+ * sensitiveData!: string;
13
+ *
14
+ * @ObservedState({ hidden: true })
15
+ * internalState!: object;
16
+ * }
17
+ */
18
+ export declare function ObservedState(meta?: StateFieldMetadata): (_value: undefined, context: ClassFieldDecoratorContext) => void;
19
+ /**
20
+ * Get all observed state from an object instance
21
+ * Applies hidden and redact transformations
22
+ */
23
+ export declare function getObservedState(obj: object): SerializedWorkflowState;
24
+ /**
25
+ * Check if a field is observed on an object
26
+ */
27
+ export declare function isFieldObserved(obj: object, fieldName: string): boolean;
28
+ /**
29
+ * Get metadata for a specific field
30
+ */
31
+ export declare function getFieldMetadata(obj: object, fieldName: string): StateFieldMetadata | undefined;
32
+ //# sourceMappingURL=observed-state.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"observed-state.d.ts","sourceRoot":"","sources":["../../src/decorators/observed-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAQrF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,IAAI,GAAE,kBAAuB,IAEvD,QAAQ,SAAS,EACjB,SAAS,0BAA0B,KAClC,IAAI,CAeR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,uBAAuB,CA2BrE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAIvE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAI/F"}
@@ -0,0 +1,79 @@
1
+ /**
2
+ * WeakMap storing field metadata keyed by class prototype
3
+ * Structure: Map<propertyKey, StateFieldMetadata>
4
+ */
5
+ const OBSERVED_STATE_FIELDS = new WeakMap();
6
+ /**
7
+ * @ObservedState decorator
8
+ * Marks a class field for inclusion in state snapshots
9
+ *
10
+ * @example
11
+ * class MyWorkflow extends Workflow {
12
+ * @ObservedState()
13
+ * currentStep!: string;
14
+ *
15
+ * @ObservedState({ redact: true })
16
+ * sensitiveData!: string;
17
+ *
18
+ * @ObservedState({ hidden: true })
19
+ * internalState!: object;
20
+ * }
21
+ */
22
+ export function ObservedState(meta = {}) {
23
+ return function (_value, context) {
24
+ const propertyKey = String(context.name);
25
+ // Use addInitializer to register field when class is instantiated
26
+ context.addInitializer(function () {
27
+ const instance = this;
28
+ const proto = Object.getPrototypeOf(instance);
29
+ let map = OBSERVED_STATE_FIELDS.get(proto);
30
+ if (!map) {
31
+ map = new Map();
32
+ OBSERVED_STATE_FIELDS.set(proto, map);
33
+ }
34
+ map.set(propertyKey, meta);
35
+ });
36
+ };
37
+ }
38
+ /**
39
+ * Get all observed state from an object instance
40
+ * Applies hidden and redact transformations
41
+ */
42
+ export function getObservedState(obj) {
43
+ const proto = Object.getPrototypeOf(obj);
44
+ const map = OBSERVED_STATE_FIELDS.get(proto);
45
+ if (!map) {
46
+ return {};
47
+ }
48
+ const result = {};
49
+ for (const [key, meta] of map) {
50
+ // Skip hidden fields
51
+ if (meta.hidden) {
52
+ continue;
53
+ }
54
+ let value = obj[key];
55
+ // Redact sensitive fields
56
+ if (meta.redact) {
57
+ value = '***';
58
+ }
59
+ result[key] = value;
60
+ }
61
+ return result;
62
+ }
63
+ /**
64
+ * Check if a field is observed on an object
65
+ */
66
+ export function isFieldObserved(obj, fieldName) {
67
+ const proto = Object.getPrototypeOf(obj);
68
+ const map = OBSERVED_STATE_FIELDS.get(proto);
69
+ return map?.has(fieldName) ?? false;
70
+ }
71
+ /**
72
+ * Get metadata for a specific field
73
+ */
74
+ export function getFieldMetadata(obj, fieldName) {
75
+ const proto = Object.getPrototypeOf(obj);
76
+ const map = OBSERVED_STATE_FIELDS.get(proto);
77
+ return map?.get(fieldName);
78
+ }
79
+ //# sourceMappingURL=observed-state.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"observed-state.js","sourceRoot":"","sources":["../../src/decorators/observed-state.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,qBAAqB,GAAG,IAAI,OAAO,EAA2C,CAAC;AAErF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,OAA2B,EAAE;IACzD,OAAO,UACL,MAAiB,EACjB,OAAmC;QAEnC,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAEzC,kEAAkE;QAClE,OAAO,CAAC,cAAc,CAAC;YACrB,MAAM,QAAQ,GAAG,IAAc,CAAC;YAChC,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;YAC9C,IAAI,GAAG,GAAG,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC3C,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;gBAChB,qBAAqB,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACxC,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAE7C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAA4B,EAAE,CAAC;IAE3C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QAC9B,qBAAqB;QACrB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,SAAS;QACX,CAAC;QAED,IAAI,KAAK,GAAI,GAA+B,CAAC,GAAG,CAAC,CAAC;QAElD,0BAA0B;QAC1B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,KAAK,GAAG,KAAK,CAAC;QAChB,CAAC;QAED,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,SAAiB;IAC5D,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO,GAAG,EAAE,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,SAAiB;IAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO,GAAG,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;AAC7B,CAAC"}
@@ -0,0 +1,15 @@
1
+ import type { StepOptions } from '../types/index.js';
2
+ /**
3
+ * @Step decorator
4
+ * Wraps a method to emit step events, handle errors, and optionally snapshot state
5
+ *
6
+ * @example
7
+ * class MyWorkflow extends Workflow {
8
+ * @Step({ snapshotState: true, trackTiming: true })
9
+ * async processData() {
10
+ * // ... step logic
11
+ * }
12
+ * }
13
+ */
14
+ export declare function Step(opts?: StepOptions): <This, Args extends unknown[], Return>(originalMethod: (this: This, ...args: Args) => Promise<Return>, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Promise<Return>>) => (this: This, ...args: Args) => Promise<Return>;
15
+ //# sourceMappingURL=step.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/decorators/step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAwD,MAAM,mBAAmB,CAAC;AAgB3G;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,IAAI,GAAE,WAAgB,IACxB,IAAI,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACnD,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,EAC9D,SAAS,2BAA2B,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,YAKzD,IAAI,WAAW,IAAI,KAAG,OAAO,CAAC,MAAM,CAAC,CAsGzE"}
@@ -0,0 +1,110 @@
1
+ import { getObservedState } from './observed-state.js';
2
+ import { runInContext } from '../core/context.js';
3
+ import { generateId } from '../utils/id.js';
4
+ /**
5
+ * @Step decorator
6
+ * Wraps a method to emit step events, handle errors, and optionally snapshot state
7
+ *
8
+ * @example
9
+ * class MyWorkflow extends Workflow {
10
+ * @Step({ snapshotState: true, trackTiming: true })
11
+ * async processData() {
12
+ * // ... step logic
13
+ * }
14
+ * }
15
+ */
16
+ export function Step(opts = {}) {
17
+ return function (originalMethod, context) {
18
+ const methodName = String(context.name);
19
+ // CRITICAL: Use regular function, not arrow function, to preserve 'this'
20
+ async function stepWrapper(...args) {
21
+ // Cast to WorkflowLike for type safety when accessing workflow properties
22
+ const wf = this;
23
+ const stepName = opts.name ?? methodName;
24
+ const startTime = Date.now();
25
+ // Log start if requested
26
+ if (opts.logStart) {
27
+ wf.logger.info(`STEP START: ${stepName}`);
28
+ }
29
+ // Emit step start event
30
+ wf.emitEvent({
31
+ type: 'stepStart',
32
+ node: wf.node,
33
+ step: stepName,
34
+ });
35
+ // Create step node for hierarchy tracking
36
+ const stepNode = {
37
+ id: generateId(),
38
+ name: stepName,
39
+ parent: wf.node,
40
+ children: [],
41
+ status: 'running',
42
+ logs: [],
43
+ events: [],
44
+ stateSnapshot: null,
45
+ };
46
+ // Create execution context for agent/prompt operations within this step
47
+ const executionContext = {
48
+ workflowNode: stepNode,
49
+ emitEvent: (event) => {
50
+ stepNode.events.push(event);
51
+ wf.emitEvent(event);
52
+ },
53
+ workflowId: wf.id,
54
+ };
55
+ try {
56
+ // Execute the original method within the execution context
57
+ // This allows Agent.prompt() calls to automatically capture events
58
+ const result = await runInContext(executionContext, async () => {
59
+ return originalMethod.call(this, ...args);
60
+ });
61
+ // Update step node status
62
+ stepNode.status = 'completed';
63
+ // Snapshot state if requested
64
+ if (opts.snapshotState) {
65
+ wf.snapshotState();
66
+ }
67
+ // Calculate duration and emit end event
68
+ const duration = Date.now() - startTime;
69
+ if (opts.trackTiming !== false) {
70
+ wf.emitEvent({
71
+ type: 'stepEnd',
72
+ node: wf.node,
73
+ step: stepName,
74
+ duration,
75
+ });
76
+ }
77
+ // Log finish if requested
78
+ if (opts.logFinish) {
79
+ wf.logger.info(`STEP END: ${stepName} (${duration}ms)`);
80
+ }
81
+ return result;
82
+ }
83
+ catch (err) {
84
+ // Update step node status
85
+ stepNode.status = 'failed';
86
+ // Create rich error with context
87
+ const error = err;
88
+ const snap = getObservedState(this);
89
+ const workflowError = {
90
+ message: error?.message ?? 'Unknown error',
91
+ original: err,
92
+ workflowId: wf.id,
93
+ stack: error?.stack,
94
+ state: snap,
95
+ logs: [...wf.node.logs],
96
+ };
97
+ // Emit error event
98
+ wf.emitEvent({
99
+ type: 'error',
100
+ node: wf.node,
101
+ error: workflowError,
102
+ });
103
+ // Re-throw the enriched error
104
+ throw workflowError;
105
+ }
106
+ }
107
+ return stepWrapper;
108
+ };
109
+ }
110
+ //# sourceMappingURL=step.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"step.js","sourceRoot":"","sources":["../../src/decorators/step.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,50 @@
1
+ import type { TaskOptions } from '../types/index.js';
2
+ /**
3
+ * @Task decorator
4
+ * Wraps a method that returns child workflow(s), automatically attaching them
5
+ *
6
+ * @example
7
+ * class ParentWorkflow extends Workflow {
8
+ * @Task({ concurrent: true })
9
+ * async createChildren(): Promise<ChildWorkflow[]> {
10
+ * return [
11
+ * new ChildWorkflow('child1', this),
12
+ * new ChildWorkflow('child2', this),
13
+ * ];
14
+ * }
15
+ * }
16
+ *
17
+ * @example Non-workflow return (silently skipped)
18
+ * class MyWorkflow extends Workflow {
19
+ * @Task()
20
+ * async returnsString(): Promise<string> {
21
+ * return 'not a workflow'; // Returned as-is, not attached
22
+ * }
23
+ * }
24
+ *
25
+ * @example Mixed return (only workflows attached)
26
+ * class MyWorkflow extends Workflow {
27
+ * @Task()
28
+ * async mixedReturn(): Promise<(Workflow | string)[]> {
29
+ * return [
30
+ * new ChildWorkflow('child1', this), // Attached
31
+ * 'some string', // Skipped
32
+ * new ChildWorkflow('child2', this), // Attached
33
+ * ];
34
+ * }
35
+ * }
36
+ *
37
+ * Validation Behavior
38
+ *
39
+ * The decorator uses lenient validation for return values:
40
+ * - Workflow objects (with 'id' property) are automatically attached
41
+ * - Non-workflow objects are silently skipped (not attached)
42
+ * - The original return value is always preserved
43
+ *
44
+ * This lenient approach enables:
45
+ * - Duck-typing: Works with workflow-like objects, not just Workflow instances
46
+ * - Flexible signatures: Methods can return any type without breaking
47
+ * - Graceful handling: Edge cases (null, undefined, primitives) don't throw errors
48
+ */
49
+ export declare function Task(opts?: TaskOptions): <This, Args extends unknown[], Return>(originalMethod: (this: This, ...args: Args) => Promise<Return>, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Promise<Return>>) => (this: This, ...args: Args) => Promise<Return>;
50
+ //# sourceMappingURL=task.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/decorators/task.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAuE,MAAM,mBAAmB,CAAC;AAkB1H;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,IAAI,CAAC,IAAI,GAAE,WAAgB,IACxB,IAAI,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACnD,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,EAC9D,SAAS,2BAA2B,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,YAKzD,IAAI,WAAW,IAAI,KAAG,OAAO,CAAC,MAAM,CAAC,CAqFzE"}
@@ -0,0 +1,118 @@
1
+ import { mergeWorkflowErrors } from '../utils/workflow-error-utils.js';
2
+ /**
3
+ * @Task decorator
4
+ * Wraps a method that returns child workflow(s), automatically attaching them
5
+ *
6
+ * @example
7
+ * class ParentWorkflow extends Workflow {
8
+ * @Task({ concurrent: true })
9
+ * async createChildren(): Promise<ChildWorkflow[]> {
10
+ * return [
11
+ * new ChildWorkflow('child1', this),
12
+ * new ChildWorkflow('child2', this),
13
+ * ];
14
+ * }
15
+ * }
16
+ *
17
+ * @example Non-workflow return (silently skipped)
18
+ * class MyWorkflow extends Workflow {
19
+ * @Task()
20
+ * async returnsString(): Promise<string> {
21
+ * return 'not a workflow'; // Returned as-is, not attached
22
+ * }
23
+ * }
24
+ *
25
+ * @example Mixed return (only workflows attached)
26
+ * class MyWorkflow extends Workflow {
27
+ * @Task()
28
+ * async mixedReturn(): Promise<(Workflow | string)[]> {
29
+ * return [
30
+ * new ChildWorkflow('child1', this), // Attached
31
+ * 'some string', // Skipped
32
+ * new ChildWorkflow('child2', this), // Attached
33
+ * ];
34
+ * }
35
+ * }
36
+ *
37
+ * Validation Behavior
38
+ *
39
+ * The decorator uses lenient validation for return values:
40
+ * - Workflow objects (with 'id' property) are automatically attached
41
+ * - Non-workflow objects are silently skipped (not attached)
42
+ * - The original return value is always preserved
43
+ *
44
+ * This lenient approach enables:
45
+ * - Duck-typing: Works with workflow-like objects, not just Workflow instances
46
+ * - Flexible signatures: Methods can return any type without breaking
47
+ * - Graceful handling: Edge cases (null, undefined, primitives) don't throw errors
48
+ */
49
+ export function Task(opts = {}) {
50
+ return function (originalMethod, context) {
51
+ const methodName = String(context.name);
52
+ // CRITICAL: Use regular function, not arrow function
53
+ async function taskWrapper(...args) {
54
+ // Cast to WorkflowLike for type safety when accessing workflow properties
55
+ const wf = this;
56
+ const taskName = opts.name ?? methodName;
57
+ // Emit task start event
58
+ wf.emitEvent({
59
+ type: 'taskStart',
60
+ node: wf.node,
61
+ task: taskName,
62
+ });
63
+ // Execute the original method
64
+ const result = await originalMethod.call(this, ...args);
65
+ // Process returned workflows
66
+ const workflows = Array.isArray(result) ? result : [result];
67
+ for (const workflow of workflows) {
68
+ // Type guard to check if it's a workflow
69
+ if (workflow && typeof workflow === 'object' && 'id' in workflow) {
70
+ const childWf = workflow;
71
+ // Only attach if not already attached (parent not set by constructor)
72
+ if (!childWf.parent) {
73
+ childWf.parent = wf;
74
+ wf.attachChild(childWf);
75
+ }
76
+ }
77
+ }
78
+ // If concurrent option is set and we have multiple workflows, run them in parallel
79
+ if (opts.concurrent && Array.isArray(result)) {
80
+ const runnable = workflows.filter((w) => w && typeof w === 'object' && 'run' in w && typeof w.run === 'function');
81
+ if (runnable.length > 0) {
82
+ const results = await Promise.allSettled(runnable.map((w) => w.run()));
83
+ const rejected = results.filter((r) => r.status === 'rejected');
84
+ if (rejected.length > 0) {
85
+ // Check if error merge strategy is enabled
86
+ if (opts.errorMergeStrategy?.enabled) {
87
+ // Extract WorkflowError objects from rejected promises
88
+ const errors = rejected.map((r) => r.reason);
89
+ // Merge errors using custom combine() or default merger
90
+ const mergedError = opts.errorMergeStrategy?.combine
91
+ ? opts.errorMergeStrategy.combine(errors)
92
+ : mergeWorkflowErrors(errors, taskName, wf.id, runnable.length);
93
+ // Emit error event with merged error
94
+ wf.emitEvent({
95
+ type: 'error',
96
+ node: wf.node,
97
+ error: mergedError,
98
+ });
99
+ // Throw merged error
100
+ throw mergedError;
101
+ }
102
+ // Backward compatibility: throw first error
103
+ throw rejected[0].reason;
104
+ }
105
+ }
106
+ }
107
+ // Emit task end event
108
+ wf.emitEvent({
109
+ type: 'taskEnd',
110
+ node: wf.node,
111
+ task: taskName,
112
+ });
113
+ return result;
114
+ }
115
+ return taskWrapper;
116
+ };
117
+ }
118
+ //# sourceMappingURL=task.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/decorators/task.ts"],"names":[],"mappings":"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"}