agentfootprint 1.0.0

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 (960) hide show
  1. package/AGENTS.md +297 -0
  2. package/CLAUDE.md +297 -0
  3. package/LICENSE +21 -0
  4. package/README.md +339 -0
  5. package/ai-instructions/claude-code/SKILL.md +597 -0
  6. package/ai-instructions/clinerules +85 -0
  7. package/ai-instructions/copilot-instructions.md +109 -0
  8. package/ai-instructions/cursor/agentfootprint.md +101 -0
  9. package/ai-instructions/kiro/agentfootprint.md +101 -0
  10. package/ai-instructions/setup.sh +140 -0
  11. package/ai-instructions/windsurfrules +85 -0
  12. package/dist/adapters/a2a/a2aRunner.js +36 -0
  13. package/dist/adapters/a2a/a2aRunner.js.map +1 -0
  14. package/dist/adapters/anthropic/AnthropicAdapter.js +293 -0
  15. package/dist/adapters/anthropic/AnthropicAdapter.js.map +1 -0
  16. package/dist/adapters/bedrock/BedrockAdapter.js +313 -0
  17. package/dist/adapters/bedrock/BedrockAdapter.js.map +1 -0
  18. package/dist/adapters/browser/BrowserAnthropicAdapter.js +349 -0
  19. package/dist/adapters/browser/BrowserAnthropicAdapter.js.map +1 -0
  20. package/dist/adapters/browser/BrowserOpenAIAdapter.js +303 -0
  21. package/dist/adapters/browser/BrowserOpenAIAdapter.js.map +1 -0
  22. package/dist/adapters/browser/index.js +8 -0
  23. package/dist/adapters/browser/index.js.map +1 -0
  24. package/dist/adapters/createAdapterSubflow.js +46 -0
  25. package/dist/adapters/createAdapterSubflow.js.map +1 -0
  26. package/dist/adapters/createProvider.js +107 -0
  27. package/dist/adapters/createProvider.js.map +1 -0
  28. package/dist/adapters/fallbackProvider.js +94 -0
  29. package/dist/adapters/fallbackProvider.js.map +1 -0
  30. package/dist/adapters/index.js +47 -0
  31. package/dist/adapters/index.js.map +1 -0
  32. package/dist/adapters/mcp/mcpToolProvider.js +44 -0
  33. package/dist/adapters/mcp/mcpToolProvider.js.map +1 -0
  34. package/dist/adapters/memory/inMemory.js +38 -0
  35. package/dist/adapters/memory/inMemory.js.map +1 -0
  36. package/dist/adapters/memory/index.js +6 -0
  37. package/dist/adapters/memory/index.js.map +1 -0
  38. package/dist/adapters/memory/stores.js +137 -0
  39. package/dist/adapters/memory/stores.js.map +1 -0
  40. package/dist/adapters/memory/types.js +14 -0
  41. package/dist/adapters/memory/types.js.map +1 -0
  42. package/dist/adapters/mock/MockAdapter.js +66 -0
  43. package/dist/adapters/mock/MockAdapter.js.map +1 -0
  44. package/dist/adapters/mock/MockRetriever.js +61 -0
  45. package/dist/adapters/mock/MockRetriever.js.map +1 -0
  46. package/dist/adapters/openai/OpenAIAdapter.js +276 -0
  47. package/dist/adapters/openai/OpenAIAdapter.js.map +1 -0
  48. package/dist/adapters/resilientProvider.js +93 -0
  49. package/dist/adapters/resilientProvider.js.map +1 -0
  50. package/dist/compositions/index.js +17 -0
  51. package/dist/compositions/index.js.map +1 -0
  52. package/dist/compositions/withCircuitBreaker.js +84 -0
  53. package/dist/compositions/withCircuitBreaker.js.map +1 -0
  54. package/dist/compositions/withFallback.js +33 -0
  55. package/dist/compositions/withFallback.js.map +1 -0
  56. package/dist/compositions/withRetry.js +59 -0
  57. package/dist/compositions/withRetry.js.map +1 -0
  58. package/dist/concepts/FlowChart.js +205 -0
  59. package/dist/concepts/FlowChart.js.map +1 -0
  60. package/dist/concepts/LLMCall.js +160 -0
  61. package/dist/concepts/LLMCall.js.map +1 -0
  62. package/dist/concepts/Parallel.js +254 -0
  63. package/dist/concepts/Parallel.js.map +1 -0
  64. package/dist/concepts/RAG.js +198 -0
  65. package/dist/concepts/RAG.js.map +1 -0
  66. package/dist/concepts/Swarm.js +270 -0
  67. package/dist/concepts/Swarm.js.map +1 -0
  68. package/dist/concepts/index.js +23 -0
  69. package/dist/concepts/index.js.map +1 -0
  70. package/dist/concepts/specIcons.js +48 -0
  71. package/dist/concepts/specIcons.js.map +1 -0
  72. package/dist/core/config.js +7 -0
  73. package/dist/core/config.js.map +1 -0
  74. package/dist/core/index.js +14 -0
  75. package/dist/core/index.js.map +1 -0
  76. package/dist/core/providers.js +19 -0
  77. package/dist/core/providers.js.map +1 -0
  78. package/dist/core/recorders.js +7 -0
  79. package/dist/core/recorders.js.map +1 -0
  80. package/dist/esm/adapters/a2a/a2aRunner.js +32 -0
  81. package/dist/esm/adapters/a2a/a2aRunner.js.map +1 -0
  82. package/dist/esm/adapters/anthropic/AnthropicAdapter.js +289 -0
  83. package/dist/esm/adapters/anthropic/AnthropicAdapter.js.map +1 -0
  84. package/dist/esm/adapters/bedrock/BedrockAdapter.js +309 -0
  85. package/dist/esm/adapters/bedrock/BedrockAdapter.js.map +1 -0
  86. package/dist/esm/adapters/browser/BrowserAnthropicAdapter.js +345 -0
  87. package/dist/esm/adapters/browser/BrowserAnthropicAdapter.js.map +1 -0
  88. package/dist/esm/adapters/browser/BrowserOpenAIAdapter.js +299 -0
  89. package/dist/esm/adapters/browser/BrowserOpenAIAdapter.js.map +1 -0
  90. package/dist/esm/adapters/browser/index.js +3 -0
  91. package/dist/esm/adapters/browser/index.js.map +1 -0
  92. package/dist/esm/adapters/createAdapterSubflow.js +42 -0
  93. package/dist/esm/adapters/createAdapterSubflow.js.map +1 -0
  94. package/dist/esm/adapters/createProvider.js +101 -0
  95. package/dist/esm/adapters/createProvider.js.map +1 -0
  96. package/dist/esm/adapters/fallbackProvider.js +90 -0
  97. package/dist/esm/adapters/fallbackProvider.js.map +1 -0
  98. package/dist/esm/adapters/index.js +23 -0
  99. package/dist/esm/adapters/index.js.map +1 -0
  100. package/dist/esm/adapters/mcp/mcpToolProvider.js +40 -0
  101. package/dist/esm/adapters/mcp/mcpToolProvider.js.map +1 -0
  102. package/dist/esm/adapters/memory/inMemory.js +34 -0
  103. package/dist/esm/adapters/memory/inMemory.js.map +1 -0
  104. package/dist/esm/adapters/memory/index.js +2 -0
  105. package/dist/esm/adapters/memory/index.js.map +1 -0
  106. package/dist/esm/adapters/memory/stores.js +131 -0
  107. package/dist/esm/adapters/memory/stores.js.map +1 -0
  108. package/dist/esm/adapters/memory/types.js +13 -0
  109. package/dist/esm/adapters/memory/types.js.map +1 -0
  110. package/dist/esm/adapters/mock/MockAdapter.js +61 -0
  111. package/dist/esm/adapters/mock/MockAdapter.js.map +1 -0
  112. package/dist/esm/adapters/mock/MockRetriever.js +56 -0
  113. package/dist/esm/adapters/mock/MockRetriever.js.map +1 -0
  114. package/dist/esm/adapters/openai/OpenAIAdapter.js +272 -0
  115. package/dist/esm/adapters/openai/OpenAIAdapter.js.map +1 -0
  116. package/dist/esm/adapters/resilientProvider.js +89 -0
  117. package/dist/esm/adapters/resilientProvider.js.map +1 -0
  118. package/dist/esm/compositions/index.js +10 -0
  119. package/dist/esm/compositions/index.js.map +1 -0
  120. package/dist/esm/compositions/withCircuitBreaker.js +79 -0
  121. package/dist/esm/compositions/withCircuitBreaker.js.map +1 -0
  122. package/dist/esm/compositions/withFallback.js +29 -0
  123. package/dist/esm/compositions/withFallback.js.map +1 -0
  124. package/dist/esm/compositions/withRetry.js +55 -0
  125. package/dist/esm/compositions/withRetry.js.map +1 -0
  126. package/dist/esm/concepts/FlowChart.js +200 -0
  127. package/dist/esm/concepts/FlowChart.js.map +1 -0
  128. package/dist/esm/concepts/LLMCall.js +155 -0
  129. package/dist/esm/concepts/LLMCall.js.map +1 -0
  130. package/dist/esm/concepts/Parallel.js +249 -0
  131. package/dist/esm/concepts/Parallel.js.map +1 -0
  132. package/dist/esm/concepts/RAG.js +193 -0
  133. package/dist/esm/concepts/RAG.js.map +1 -0
  134. package/dist/esm/concepts/Swarm.js +265 -0
  135. package/dist/esm/concepts/Swarm.js.map +1 -0
  136. package/dist/esm/concepts/index.js +8 -0
  137. package/dist/esm/concepts/index.js.map +1 -0
  138. package/dist/esm/concepts/specIcons.js +44 -0
  139. package/dist/esm/concepts/specIcons.js.map +1 -0
  140. package/dist/esm/core/config.js +6 -0
  141. package/dist/esm/core/config.js.map +1 -0
  142. package/dist/esm/core/index.js +13 -0
  143. package/dist/esm/core/index.js.map +1 -0
  144. package/dist/esm/core/providers.js +18 -0
  145. package/dist/esm/core/providers.js.map +1 -0
  146. package/dist/esm/core/recorders.js +6 -0
  147. package/dist/esm/core/recorders.js.map +1 -0
  148. package/dist/esm/executor/agentLoop.js +150 -0
  149. package/dist/esm/executor/agentLoop.js.map +1 -0
  150. package/dist/esm/executor/index.js +5 -0
  151. package/dist/esm/executor/index.js.map +1 -0
  152. package/dist/esm/explain.barrel.js +19 -0
  153. package/dist/esm/explain.barrel.js.map +1 -0
  154. package/dist/esm/index.js +29 -0
  155. package/dist/esm/index.js.map +1 -0
  156. package/dist/esm/instructions.barrel.js +22 -0
  157. package/dist/esm/instructions.barrel.js.map +1 -0
  158. package/dist/esm/lib/call/callLLMStage.js +64 -0
  159. package/dist/esm/lib/call/callLLMStage.js.map +1 -0
  160. package/dist/esm/lib/call/handleResponseStage.js +49 -0
  161. package/dist/esm/lib/call/handleResponseStage.js.map +1 -0
  162. package/dist/esm/lib/call/helpers.js +164 -0
  163. package/dist/esm/lib/call/helpers.js.map +1 -0
  164. package/dist/esm/lib/call/index.js +7 -0
  165. package/dist/esm/lib/call/index.js.map +1 -0
  166. package/dist/esm/lib/call/parseResponseStage.js +48 -0
  167. package/dist/esm/lib/call/parseResponseStage.js.map +1 -0
  168. package/dist/esm/lib/call/streamingCallLLMStage.js +103 -0
  169. package/dist/esm/lib/call/streamingCallLLMStage.js.map +1 -0
  170. package/dist/esm/lib/call/toolExecutionSubflow.js +87 -0
  171. package/dist/esm/lib/call/toolExecutionSubflow.js.map +1 -0
  172. package/dist/esm/lib/call/types.js +10 -0
  173. package/dist/esm/lib/call/types.js.map +1 -0
  174. package/dist/esm/lib/concepts/Agent.js +7 -0
  175. package/dist/esm/lib/concepts/Agent.js.map +1 -0
  176. package/dist/esm/lib/concepts/AgentBuilder.js +224 -0
  177. package/dist/esm/lib/concepts/AgentBuilder.js.map +1 -0
  178. package/dist/esm/lib/concepts/AgentRunner.js +337 -0
  179. package/dist/esm/lib/concepts/AgentRunner.js.map +1 -0
  180. package/dist/esm/lib/concepts/index.js +2 -0
  181. package/dist/esm/lib/concepts/index.js.map +1 -0
  182. package/dist/esm/lib/instructions/InstructionRecorder.js +121 -0
  183. package/dist/esm/lib/instructions/InstructionRecorder.js.map +1 -0
  184. package/dist/esm/lib/instructions/agentInstruction.js +139 -0
  185. package/dist/esm/lib/instructions/agentInstruction.js.map +1 -0
  186. package/dist/esm/lib/instructions/buildInstructionsToLLMSubflow.js +83 -0
  187. package/dist/esm/lib/instructions/buildInstructionsToLLMSubflow.js.map +1 -0
  188. package/dist/esm/lib/instructions/evaluator.js +196 -0
  189. package/dist/esm/lib/instructions/evaluator.js.map +1 -0
  190. package/dist/esm/lib/instructions/index.js +10 -0
  191. package/dist/esm/lib/instructions/index.js.map +1 -0
  192. package/dist/esm/lib/instructions/inject.js +55 -0
  193. package/dist/esm/lib/instructions/inject.js.map +1 -0
  194. package/dist/esm/lib/instructions/preview.js +88 -0
  195. package/dist/esm/lib/instructions/preview.js.map +1 -0
  196. package/dist/esm/lib/instructions/strictFollowUp.js +125 -0
  197. package/dist/esm/lib/instructions/strictFollowUp.js.map +1 -0
  198. package/dist/esm/lib/instructions/template.js +82 -0
  199. package/dist/esm/lib/instructions/template.js.map +1 -0
  200. package/dist/esm/lib/instructions/types.js +83 -0
  201. package/dist/esm/lib/instructions/types.js.map +1 -0
  202. package/dist/esm/lib/loop/buildAgentLoop.js +401 -0
  203. package/dist/esm/lib/loop/buildAgentLoop.js.map +1 -0
  204. package/dist/esm/lib/loop/index.js +3 -0
  205. package/dist/esm/lib/loop/index.js.map +1 -0
  206. package/dist/esm/lib/loop/types.js +71 -0
  207. package/dist/esm/lib/loop/types.js.map +1 -0
  208. package/dist/esm/lib/narrative/agentRenderer.js +293 -0
  209. package/dist/esm/lib/narrative/agentRenderer.js.map +1 -0
  210. package/dist/esm/lib/narrative/groundingHelpers.js +136 -0
  211. package/dist/esm/lib/narrative/groundingHelpers.js.map +1 -0
  212. package/dist/esm/lib/narrative/index.js +3 -0
  213. package/dist/esm/lib/narrative/index.js.map +1 -0
  214. package/dist/esm/lib/slots/helpers.js +23 -0
  215. package/dist/esm/lib/slots/helpers.js.map +1 -0
  216. package/dist/esm/lib/slots/index.js +4 -0
  217. package/dist/esm/lib/slots/index.js.map +1 -0
  218. package/dist/esm/lib/slots/messages/buildMessagesSubflow.js +108 -0
  219. package/dist/esm/lib/slots/messages/buildMessagesSubflow.js.map +1 -0
  220. package/dist/esm/lib/slots/messages/index.js +2 -0
  221. package/dist/esm/lib/slots/messages/index.js.map +1 -0
  222. package/dist/esm/lib/slots/messages/types.js +10 -0
  223. package/dist/esm/lib/slots/messages/types.js.map +1 -0
  224. package/dist/esm/lib/slots/system-prompt/buildSystemPromptSubflow.js +64 -0
  225. package/dist/esm/lib/slots/system-prompt/buildSystemPromptSubflow.js.map +1 -0
  226. package/dist/esm/lib/slots/system-prompt/index.js +2 -0
  227. package/dist/esm/lib/slots/system-prompt/index.js.map +1 -0
  228. package/dist/esm/lib/slots/system-prompt/types.js +9 -0
  229. package/dist/esm/lib/slots/system-prompt/types.js.map +1 -0
  230. package/dist/esm/lib/slots/tools/buildToolsSubflow.js +67 -0
  231. package/dist/esm/lib/slots/tools/buildToolsSubflow.js.map +1 -0
  232. package/dist/esm/lib/slots/tools/index.js +2 -0
  233. package/dist/esm/lib/slots/tools/index.js.map +1 -0
  234. package/dist/esm/lib/slots/tools/types.js +11 -0
  235. package/dist/esm/lib/slots/tools/types.js.map +1 -0
  236. package/dist/esm/lib/swarm/buildSwarmRouting.js +207 -0
  237. package/dist/esm/lib/swarm/buildSwarmRouting.js.map +1 -0
  238. package/dist/esm/lib/swarm/index.js +2 -0
  239. package/dist/esm/lib/swarm/index.js.map +1 -0
  240. package/dist/esm/memory/conversationHelpers.js +56 -0
  241. package/dist/esm/memory/conversationHelpers.js.map +1 -0
  242. package/dist/esm/memory/index.js +2 -0
  243. package/dist/esm/memory/index.js.map +1 -0
  244. package/dist/esm/models/index.js +3 -0
  245. package/dist/esm/models/index.js.map +1 -0
  246. package/dist/esm/models/pricing.js +23 -0
  247. package/dist/esm/models/pricing.js.map +1 -0
  248. package/dist/esm/models/providers.js +42 -0
  249. package/dist/esm/models/providers.js.map +1 -0
  250. package/dist/esm/models/types.js +6 -0
  251. package/dist/esm/models/types.js.map +1 -0
  252. package/dist/esm/observe.barrel.js +18 -0
  253. package/dist/esm/observe.barrel.js.map +1 -0
  254. package/dist/esm/providers/index.js +12 -0
  255. package/dist/esm/providers/index.js.map +1 -0
  256. package/dist/esm/providers/messages/charBudget.js +39 -0
  257. package/dist/esm/providers/messages/charBudget.js.map +1 -0
  258. package/dist/esm/providers/messages/compositeMessages.js +33 -0
  259. package/dist/esm/providers/messages/compositeMessages.js.map +1 -0
  260. package/dist/esm/providers/messages/fullHistory.js +15 -0
  261. package/dist/esm/providers/messages/fullHistory.js.map +1 -0
  262. package/dist/esm/providers/messages/index.js +11 -0
  263. package/dist/esm/providers/messages/index.js.map +1 -0
  264. package/dist/esm/providers/messages/persistentHistory.js +40 -0
  265. package/dist/esm/providers/messages/persistentHistory.js.map +1 -0
  266. package/dist/esm/providers/messages/slidingWindow.js +24 -0
  267. package/dist/esm/providers/messages/slidingWindow.js.map +1 -0
  268. package/dist/esm/providers/messages/summaryStrategy.js +41 -0
  269. package/dist/esm/providers/messages/summaryStrategy.js.map +1 -0
  270. package/dist/esm/providers/messages/withToolPairSafety.js +76 -0
  271. package/dist/esm/providers/messages/withToolPairSafety.js.map +1 -0
  272. package/dist/esm/providers/prompt/compositePrompt.js +28 -0
  273. package/dist/esm/providers/prompt/compositePrompt.js.map +1 -0
  274. package/dist/esm/providers/prompt/index.js +8 -0
  275. package/dist/esm/providers/prompt/index.js.map +1 -0
  276. package/dist/esm/providers/prompt/skillBasedPrompt.js +37 -0
  277. package/dist/esm/providers/prompt/skillBasedPrompt.js.map +1 -0
  278. package/dist/esm/providers/prompt/static.js +9 -0
  279. package/dist/esm/providers/prompt/static.js.map +1 -0
  280. package/dist/esm/providers/prompt/template.js +20 -0
  281. package/dist/esm/providers/prompt/template.js.map +1 -0
  282. package/dist/esm/providers/tools/PermissionPolicy.js +100 -0
  283. package/dist/esm/providers/tools/PermissionPolicy.js.map +1 -0
  284. package/dist/esm/providers/tools/agentAsTool.js +47 -0
  285. package/dist/esm/providers/tools/agentAsTool.js.map +1 -0
  286. package/dist/esm/providers/tools/compositeTools.js +49 -0
  287. package/dist/esm/providers/tools/compositeTools.js.map +1 -0
  288. package/dist/esm/providers/tools/dynamicTools.js +41 -0
  289. package/dist/esm/providers/tools/dynamicTools.js.map +1 -0
  290. package/dist/esm/providers/tools/gatedTools.js +90 -0
  291. package/dist/esm/providers/tools/gatedTools.js.map +1 -0
  292. package/dist/esm/providers/tools/index.js +11 -0
  293. package/dist/esm/providers/tools/index.js.map +1 -0
  294. package/dist/esm/providers/tools/noTools.js +9 -0
  295. package/dist/esm/providers/tools/noTools.js.map +1 -0
  296. package/dist/esm/providers/tools/staticTools.js +25 -0
  297. package/dist/esm/providers/tools/staticTools.js.map +1 -0
  298. package/dist/esm/providers.barrel.js +32 -0
  299. package/dist/esm/providers.barrel.js.map +1 -0
  300. package/dist/esm/recorders/index.js +5 -0
  301. package/dist/esm/recorders/index.js.map +1 -0
  302. package/dist/esm/recorders/v2/CompositeRecorder.js +65 -0
  303. package/dist/esm/recorders/v2/CompositeRecorder.js.map +1 -0
  304. package/dist/esm/recorders/v2/CostRecorder.js +47 -0
  305. package/dist/esm/recorders/v2/CostRecorder.js.map +1 -0
  306. package/dist/esm/recorders/v2/ExplainRecorder.js +93 -0
  307. package/dist/esm/recorders/v2/ExplainRecorder.js.map +1 -0
  308. package/dist/esm/recorders/v2/GuardrailRecorder.js +58 -0
  309. package/dist/esm/recorders/v2/GuardrailRecorder.js.map +1 -0
  310. package/dist/esm/recorders/v2/OTelRecorder.js +79 -0
  311. package/dist/esm/recorders/v2/OTelRecorder.js.map +1 -0
  312. package/dist/esm/recorders/v2/PermissionRecorder.js +86 -0
  313. package/dist/esm/recorders/v2/PermissionRecorder.js.map +1 -0
  314. package/dist/esm/recorders/v2/QualityRecorder.js +48 -0
  315. package/dist/esm/recorders/v2/QualityRecorder.js.map +1 -0
  316. package/dist/esm/recorders/v2/RecorderBridge.js +85 -0
  317. package/dist/esm/recorders/v2/RecorderBridge.js.map +1 -0
  318. package/dist/esm/recorders/v2/TokenRecorder.js +72 -0
  319. package/dist/esm/recorders/v2/TokenRecorder.js.map +1 -0
  320. package/dist/esm/recorders/v2/ToolUsageRecorder.js +54 -0
  321. package/dist/esm/recorders/v2/ToolUsageRecorder.js.map +1 -0
  322. package/dist/esm/recorders/v2/TurnRecorder.js +83 -0
  323. package/dist/esm/recorders/v2/TurnRecorder.js.map +1 -0
  324. package/dist/esm/recorders/v2/agentObservability.js +62 -0
  325. package/dist/esm/recorders/v2/agentObservability.js.map +1 -0
  326. package/dist/esm/recorders/v2/index.js +13 -0
  327. package/dist/esm/recorders/v2/index.js.map +1 -0
  328. package/dist/esm/resilience.barrel.js +16 -0
  329. package/dist/esm/resilience.barrel.js.map +1 -0
  330. package/dist/esm/scope/AgentScope.js +153 -0
  331. package/dist/esm/scope/AgentScope.js.map +1 -0
  332. package/dist/esm/scope/index.js +2 -0
  333. package/dist/esm/scope/index.js.map +1 -0
  334. package/dist/esm/scope/types.js +37 -0
  335. package/dist/esm/scope/types.js.map +1 -0
  336. package/dist/esm/security.barrel.js +17 -0
  337. package/dist/esm/security.barrel.js.map +1 -0
  338. package/dist/esm/stages/augmentPrompt.js +28 -0
  339. package/dist/esm/stages/augmentPrompt.js.map +1 -0
  340. package/dist/esm/stages/callLLM.js +15 -0
  341. package/dist/esm/stages/callLLM.js.map +1 -0
  342. package/dist/esm/stages/commitMemory.js +94 -0
  343. package/dist/esm/stages/commitMemory.js.map +1 -0
  344. package/dist/esm/stages/finalize.js +12 -0
  345. package/dist/esm/stages/finalize.js.map +1 -0
  346. package/dist/esm/stages/helpers.js +58 -0
  347. package/dist/esm/stages/helpers.js.map +1 -0
  348. package/dist/esm/stages/index.js +9 -0
  349. package/dist/esm/stages/index.js.map +1 -0
  350. package/dist/esm/stages/parseResponse.js +25 -0
  351. package/dist/esm/stages/parseResponse.js.map +1 -0
  352. package/dist/esm/stages/retrieve.js +18 -0
  353. package/dist/esm/stages/retrieve.js.map +1 -0
  354. package/dist/esm/stages/runnerAsStage.js +66 -0
  355. package/dist/esm/stages/runnerAsStage.js.map +1 -0
  356. package/dist/esm/stream.barrel.js +18 -0
  357. package/dist/esm/stream.barrel.js.map +1 -0
  358. package/dist/esm/streaming/StreamEmitter.js +43 -0
  359. package/dist/esm/streaming/StreamEmitter.js.map +1 -0
  360. package/dist/esm/streaming/index.js +2 -0
  361. package/dist/esm/streaming/index.js.map +1 -0
  362. package/dist/esm/subflows/index.js +2 -0
  363. package/dist/esm/subflows/index.js.map +1 -0
  364. package/dist/esm/subflows/prepareMemory.js +83 -0
  365. package/dist/esm/subflows/prepareMemory.js.map +1 -0
  366. package/dist/esm/tools/ToolRegistry.js +84 -0
  367. package/dist/esm/tools/ToolRegistry.js.map +1 -0
  368. package/dist/esm/tools/askHuman.js +63 -0
  369. package/dist/esm/tools/askHuman.js.map +1 -0
  370. package/dist/esm/tools/index.js +3 -0
  371. package/dist/esm/tools/index.js.map +1 -0
  372. package/dist/esm/tools/validateInput.js +56 -0
  373. package/dist/esm/tools/validateInput.js.map +1 -0
  374. package/dist/esm/tools/zodToJsonSchema.js +65 -0
  375. package/dist/esm/tools/zodToJsonSchema.js.map +1 -0
  376. package/dist/esm/types/adapter.js +11 -0
  377. package/dist/esm/types/adapter.js.map +1 -0
  378. package/dist/esm/types/agent.js +5 -0
  379. package/dist/esm/types/agent.js.map +1 -0
  380. package/dist/esm/types/content.js +82 -0
  381. package/dist/esm/types/content.js.map +1 -0
  382. package/dist/esm/types/errors.js +74 -0
  383. package/dist/esm/types/errors.js.map +1 -0
  384. package/dist/esm/types/index.js +5 -0
  385. package/dist/esm/types/index.js.map +1 -0
  386. package/dist/esm/types/llm.js +6 -0
  387. package/dist/esm/types/llm.js.map +1 -0
  388. package/dist/esm/types/messages.js +24 -0
  389. package/dist/esm/types/messages.js.map +1 -0
  390. package/dist/esm/types/multiAgent.js +5 -0
  391. package/dist/esm/types/multiAgent.js.map +1 -0
  392. package/dist/esm/types/retriever.js +6 -0
  393. package/dist/esm/types/retriever.js.map +1 -0
  394. package/dist/esm/types/tools.js +5 -0
  395. package/dist/esm/types/tools.js.map +1 -0
  396. package/dist/executor/agentLoop.js +154 -0
  397. package/dist/executor/agentLoop.js.map +1 -0
  398. package/dist/executor/index.js +9 -0
  399. package/dist/executor/index.js.map +1 -0
  400. package/dist/explain.barrel.js +27 -0
  401. package/dist/explain.barrel.js.map +1 -0
  402. package/dist/index.js +74 -0
  403. package/dist/index.js.map +1 -0
  404. package/dist/instructions.barrel.js +30 -0
  405. package/dist/instructions.barrel.js.map +1 -0
  406. package/dist/lib/call/callLLMStage.js +68 -0
  407. package/dist/lib/call/callLLMStage.js.map +1 -0
  408. package/dist/lib/call/handleResponseStage.js +53 -0
  409. package/dist/lib/call/handleResponseStage.js.map +1 -0
  410. package/dist/lib/call/helpers.js +169 -0
  411. package/dist/lib/call/helpers.js.map +1 -0
  412. package/dist/lib/call/index.js +17 -0
  413. package/dist/lib/call/index.js.map +1 -0
  414. package/dist/lib/call/parseResponseStage.js +52 -0
  415. package/dist/lib/call/parseResponseStage.js.map +1 -0
  416. package/dist/lib/call/streamingCallLLMStage.js +107 -0
  417. package/dist/lib/call/streamingCallLLMStage.js.map +1 -0
  418. package/dist/lib/call/toolExecutionSubflow.js +91 -0
  419. package/dist/lib/call/toolExecutionSubflow.js.map +1 -0
  420. package/dist/lib/call/types.js +11 -0
  421. package/dist/lib/call/types.js.map +1 -0
  422. package/dist/lib/concepts/Agent.js +12 -0
  423. package/dist/lib/concepts/Agent.js.map +1 -0
  424. package/dist/lib/concepts/AgentBuilder.js +228 -0
  425. package/dist/lib/concepts/AgentBuilder.js.map +1 -0
  426. package/dist/lib/concepts/AgentRunner.js +341 -0
  427. package/dist/lib/concepts/AgentRunner.js.map +1 -0
  428. package/dist/lib/concepts/index.js +7 -0
  429. package/dist/lib/concepts/index.js.map +1 -0
  430. package/dist/lib/instructions/InstructionRecorder.js +125 -0
  431. package/dist/lib/instructions/InstructionRecorder.js.map +1 -0
  432. package/dist/lib/instructions/agentInstruction.js +144 -0
  433. package/dist/lib/instructions/agentInstruction.js.map +1 -0
  434. package/dist/lib/instructions/buildInstructionsToLLMSubflow.js +87 -0
  435. package/dist/lib/instructions/buildInstructionsToLLMSubflow.js.map +1 -0
  436. package/dist/lib/instructions/evaluator.js +202 -0
  437. package/dist/lib/instructions/evaluator.js.map +1 -0
  438. package/dist/lib/instructions/index.js +27 -0
  439. package/dist/lib/instructions/index.js.map +1 -0
  440. package/dist/lib/instructions/inject.js +59 -0
  441. package/dist/lib/instructions/inject.js.map +1 -0
  442. package/dist/lib/instructions/preview.js +92 -0
  443. package/dist/lib/instructions/preview.js.map +1 -0
  444. package/dist/lib/instructions/strictFollowUp.js +130 -0
  445. package/dist/lib/instructions/strictFollowUp.js.map +1 -0
  446. package/dist/lib/instructions/template.js +86 -0
  447. package/dist/lib/instructions/template.js.map +1 -0
  448. package/dist/lib/instructions/types.js +88 -0
  449. package/dist/lib/instructions/types.js.map +1 -0
  450. package/dist/lib/loop/buildAgentLoop.js +405 -0
  451. package/dist/lib/loop/buildAgentLoop.js.map +1 -0
  452. package/dist/lib/loop/index.js +9 -0
  453. package/dist/lib/loop/index.js.map +1 -0
  454. package/dist/lib/loop/types.js +74 -0
  455. package/dist/lib/loop/types.js.map +1 -0
  456. package/dist/lib/narrative/agentRenderer.js +297 -0
  457. package/dist/lib/narrative/agentRenderer.js.map +1 -0
  458. package/dist/lib/narrative/groundingHelpers.js +142 -0
  459. package/dist/lib/narrative/groundingHelpers.js.map +1 -0
  460. package/dist/lib/narrative/index.js +10 -0
  461. package/dist/lib/narrative/index.js.map +1 -0
  462. package/dist/lib/slots/helpers.js +28 -0
  463. package/dist/lib/slots/helpers.js.map +1 -0
  464. package/dist/lib/slots/index.js +10 -0
  465. package/dist/lib/slots/index.js.map +1 -0
  466. package/dist/lib/slots/messages/buildMessagesSubflow.js +112 -0
  467. package/dist/lib/slots/messages/buildMessagesSubflow.js.map +1 -0
  468. package/dist/lib/slots/messages/index.js +6 -0
  469. package/dist/lib/slots/messages/index.js.map +1 -0
  470. package/dist/lib/slots/messages/types.js +11 -0
  471. package/dist/lib/slots/messages/types.js.map +1 -0
  472. package/dist/lib/slots/system-prompt/buildSystemPromptSubflow.js +68 -0
  473. package/dist/lib/slots/system-prompt/buildSystemPromptSubflow.js.map +1 -0
  474. package/dist/lib/slots/system-prompt/index.js +6 -0
  475. package/dist/lib/slots/system-prompt/index.js.map +1 -0
  476. package/dist/lib/slots/system-prompt/types.js +10 -0
  477. package/dist/lib/slots/system-prompt/types.js.map +1 -0
  478. package/dist/lib/slots/tools/buildToolsSubflow.js +71 -0
  479. package/dist/lib/slots/tools/buildToolsSubflow.js.map +1 -0
  480. package/dist/lib/slots/tools/index.js +6 -0
  481. package/dist/lib/slots/tools/index.js.map +1 -0
  482. package/dist/lib/slots/tools/types.js +12 -0
  483. package/dist/lib/slots/tools/types.js.map +1 -0
  484. package/dist/lib/swarm/buildSwarmRouting.js +211 -0
  485. package/dist/lib/swarm/buildSwarmRouting.js.map +1 -0
  486. package/dist/lib/swarm/index.js +6 -0
  487. package/dist/lib/swarm/index.js.map +1 -0
  488. package/dist/memory/conversationHelpers.js +66 -0
  489. package/dist/memory/conversationHelpers.js.map +1 -0
  490. package/dist/memory/index.js +12 -0
  491. package/dist/memory/index.js.map +1 -0
  492. package/dist/models/index.js +12 -0
  493. package/dist/models/index.js.map +1 -0
  494. package/dist/models/pricing.js +27 -0
  495. package/dist/models/pricing.js.map +1 -0
  496. package/dist/models/providers.js +49 -0
  497. package/dist/models/providers.js.map +1 -0
  498. package/dist/models/types.js +7 -0
  499. package/dist/models/types.js.map +1 -0
  500. package/dist/observe.barrel.js +31 -0
  501. package/dist/observe.barrel.js.map +1 -0
  502. package/dist/providers/index.js +34 -0
  503. package/dist/providers/index.js.map +1 -0
  504. package/dist/providers/messages/charBudget.js +43 -0
  505. package/dist/providers/messages/charBudget.js.map +1 -0
  506. package/dist/providers/messages/compositeMessages.js +37 -0
  507. package/dist/providers/messages/compositeMessages.js.map +1 -0
  508. package/dist/providers/messages/fullHistory.js +19 -0
  509. package/dist/providers/messages/fullHistory.js.map +1 -0
  510. package/dist/providers/messages/index.js +22 -0
  511. package/dist/providers/messages/index.js.map +1 -0
  512. package/dist/providers/messages/persistentHistory.js +45 -0
  513. package/dist/providers/messages/persistentHistory.js.map +1 -0
  514. package/dist/providers/messages/slidingWindow.js +28 -0
  515. package/dist/providers/messages/slidingWindow.js.map +1 -0
  516. package/dist/providers/messages/summaryStrategy.js +45 -0
  517. package/dist/providers/messages/summaryStrategy.js.map +1 -0
  518. package/dist/providers/messages/withToolPairSafety.js +80 -0
  519. package/dist/providers/messages/withToolPairSafety.js.map +1 -0
  520. package/dist/providers/prompt/compositePrompt.js +32 -0
  521. package/dist/providers/prompt/compositePrompt.js.map +1 -0
  522. package/dist/providers/prompt/index.js +15 -0
  523. package/dist/providers/prompt/index.js.map +1 -0
  524. package/dist/providers/prompt/skillBasedPrompt.js +41 -0
  525. package/dist/providers/prompt/skillBasedPrompt.js.map +1 -0
  526. package/dist/providers/prompt/static.js +13 -0
  527. package/dist/providers/prompt/static.js.map +1 -0
  528. package/dist/providers/prompt/template.js +24 -0
  529. package/dist/providers/prompt/template.js.map +1 -0
  530. package/dist/providers/tools/PermissionPolicy.js +104 -0
  531. package/dist/providers/tools/PermissionPolicy.js.map +1 -0
  532. package/dist/providers/tools/agentAsTool.js +51 -0
  533. package/dist/providers/tools/agentAsTool.js.map +1 -0
  534. package/dist/providers/tools/compositeTools.js +53 -0
  535. package/dist/providers/tools/compositeTools.js.map +1 -0
  536. package/dist/providers/tools/dynamicTools.js +45 -0
  537. package/dist/providers/tools/dynamicTools.js.map +1 -0
  538. package/dist/providers/tools/gatedTools.js +94 -0
  539. package/dist/providers/tools/gatedTools.js.map +1 -0
  540. package/dist/providers/tools/index.js +21 -0
  541. package/dist/providers/tools/index.js.map +1 -0
  542. package/dist/providers/tools/noTools.js +13 -0
  543. package/dist/providers/tools/noTools.js.map +1 -0
  544. package/dist/providers/tools/staticTools.js +29 -0
  545. package/dist/providers/tools/staticTools.js.map +1 -0
  546. package/dist/providers.barrel.js +61 -0
  547. package/dist/providers.barrel.js.map +1 -0
  548. package/dist/recorders/index.js +17 -0
  549. package/dist/recorders/index.js.map +1 -0
  550. package/dist/recorders/v2/CompositeRecorder.js +69 -0
  551. package/dist/recorders/v2/CompositeRecorder.js.map +1 -0
  552. package/dist/recorders/v2/CostRecorder.js +51 -0
  553. package/dist/recorders/v2/CostRecorder.js.map +1 -0
  554. package/dist/recorders/v2/ExplainRecorder.js +97 -0
  555. package/dist/recorders/v2/ExplainRecorder.js.map +1 -0
  556. package/dist/recorders/v2/GuardrailRecorder.js +62 -0
  557. package/dist/recorders/v2/GuardrailRecorder.js.map +1 -0
  558. package/dist/recorders/v2/OTelRecorder.js +83 -0
  559. package/dist/recorders/v2/OTelRecorder.js.map +1 -0
  560. package/dist/recorders/v2/PermissionRecorder.js +90 -0
  561. package/dist/recorders/v2/PermissionRecorder.js.map +1 -0
  562. package/dist/recorders/v2/QualityRecorder.js +52 -0
  563. package/dist/recorders/v2/QualityRecorder.js.map +1 -0
  564. package/dist/recorders/v2/RecorderBridge.js +89 -0
  565. package/dist/recorders/v2/RecorderBridge.js.map +1 -0
  566. package/dist/recorders/v2/TokenRecorder.js +76 -0
  567. package/dist/recorders/v2/TokenRecorder.js.map +1 -0
  568. package/dist/recorders/v2/ToolUsageRecorder.js +58 -0
  569. package/dist/recorders/v2/ToolUsageRecorder.js.map +1 -0
  570. package/dist/recorders/v2/TurnRecorder.js +87 -0
  571. package/dist/recorders/v2/TurnRecorder.js.map +1 -0
  572. package/dist/recorders/v2/agentObservability.js +66 -0
  573. package/dist/recorders/v2/agentObservability.js.map +1 -0
  574. package/dist/recorders/v2/index.js +25 -0
  575. package/dist/recorders/v2/index.js.map +1 -0
  576. package/dist/resilience.barrel.js +25 -0
  577. package/dist/resilience.barrel.js.map +1 -0
  578. package/dist/scope/AgentScope.js +156 -0
  579. package/dist/scope/AgentScope.js.map +1 -0
  580. package/dist/scope/index.js +10 -0
  581. package/dist/scope/index.js.map +1 -0
  582. package/dist/scope/types.js +40 -0
  583. package/dist/scope/types.js.map +1 -0
  584. package/dist/security.barrel.js +22 -0
  585. package/dist/security.barrel.js.map +1 -0
  586. package/dist/stages/augmentPrompt.js +32 -0
  587. package/dist/stages/augmentPrompt.js.map +1 -0
  588. package/dist/stages/callLLM.js +19 -0
  589. package/dist/stages/callLLM.js.map +1 -0
  590. package/dist/stages/commitMemory.js +98 -0
  591. package/dist/stages/commitMemory.js.map +1 -0
  592. package/dist/stages/finalize.js +16 -0
  593. package/dist/stages/finalize.js.map +1 -0
  594. package/dist/stages/helpers.js +63 -0
  595. package/dist/stages/helpers.js.map +1 -0
  596. package/dist/stages/index.js +21 -0
  597. package/dist/stages/index.js.map +1 -0
  598. package/dist/stages/parseResponse.js +29 -0
  599. package/dist/stages/parseResponse.js.map +1 -0
  600. package/dist/stages/retrieve.js +22 -0
  601. package/dist/stages/retrieve.js.map +1 -0
  602. package/dist/stages/runnerAsStage.js +70 -0
  603. package/dist/stages/runnerAsStage.js.map +1 -0
  604. package/dist/stream.barrel.js +23 -0
  605. package/dist/stream.barrel.js.map +1 -0
  606. package/dist/streaming/StreamEmitter.js +48 -0
  607. package/dist/streaming/StreamEmitter.js.map +1 -0
  608. package/dist/streaming/index.js +7 -0
  609. package/dist/streaming/index.js.map +1 -0
  610. package/dist/subflows/index.js +6 -0
  611. package/dist/subflows/index.js.map +1 -0
  612. package/dist/subflows/prepareMemory.js +87 -0
  613. package/dist/subflows/prepareMemory.js.map +1 -0
  614. package/dist/tools/ToolRegistry.js +89 -0
  615. package/dist/tools/ToolRegistry.js.map +1 -0
  616. package/dist/tools/askHuman.js +68 -0
  617. package/dist/tools/askHuman.js.map +1 -0
  618. package/dist/tools/index.js +9 -0
  619. package/dist/tools/index.js.map +1 -0
  620. package/dist/tools/validateInput.js +61 -0
  621. package/dist/tools/validateInput.js.map +1 -0
  622. package/dist/tools/zodToJsonSchema.js +70 -0
  623. package/dist/tools/zodToJsonSchema.js.map +1 -0
  624. package/dist/types/adapter.js +14 -0
  625. package/dist/types/adapter.js.map +1 -0
  626. package/dist/types/adapters/a2a/a2aRunner.d.ts +40 -0
  627. package/dist/types/adapters/a2a/a2aRunner.d.ts.map +1 -0
  628. package/dist/types/adapters/anthropic/AnthropicAdapter.d.ts +37 -0
  629. package/dist/types/adapters/anthropic/AnthropicAdapter.d.ts.map +1 -0
  630. package/dist/types/adapters/bedrock/BedrockAdapter.d.ts +44 -0
  631. package/dist/types/adapters/bedrock/BedrockAdapter.d.ts.map +1 -0
  632. package/dist/types/adapters/browser/BrowserAnthropicAdapter.d.ts +40 -0
  633. package/dist/types/adapters/browser/BrowserAnthropicAdapter.d.ts.map +1 -0
  634. package/dist/types/adapters/browser/BrowserOpenAIAdapter.d.ts +46 -0
  635. package/dist/types/adapters/browser/BrowserOpenAIAdapter.d.ts.map +1 -0
  636. package/dist/types/adapters/browser/index.d.ts +5 -0
  637. package/dist/types/adapters/browser/index.d.ts.map +1 -0
  638. package/dist/types/adapters/createAdapterSubflow.d.ts +36 -0
  639. package/dist/types/adapters/createAdapterSubflow.d.ts.map +1 -0
  640. package/dist/types/adapters/createProvider.d.ts +47 -0
  641. package/dist/types/adapters/createProvider.d.ts.map +1 -0
  642. package/dist/types/adapters/fallbackProvider.d.ts +45 -0
  643. package/dist/types/adapters/fallbackProvider.d.ts.map +1 -0
  644. package/dist/types/adapters/index.d.ts +30 -0
  645. package/dist/types/adapters/index.d.ts.map +1 -0
  646. package/dist/types/adapters/mcp/mcpToolProvider.d.ts +41 -0
  647. package/dist/types/adapters/mcp/mcpToolProvider.d.ts.map +1 -0
  648. package/dist/types/adapters/memory/inMemory.d.ts +22 -0
  649. package/dist/types/adapters/memory/inMemory.d.ts.map +1 -0
  650. package/dist/types/adapters/memory/index.d.ts +3 -0
  651. package/dist/types/adapters/memory/index.d.ts.map +1 -0
  652. package/dist/types/adapters/memory/stores.d.ts +92 -0
  653. package/dist/types/adapters/memory/stores.d.ts.map +1 -0
  654. package/dist/types/adapters/memory/types.d.ts +74 -0
  655. package/dist/types/adapters/memory/types.d.ts.map +1 -0
  656. package/dist/types/adapters/mock/MockAdapter.d.ts +51 -0
  657. package/dist/types/adapters/mock/MockAdapter.d.ts.map +1 -0
  658. package/dist/types/adapters/mock/MockRetriever.d.ts +43 -0
  659. package/dist/types/adapters/mock/MockRetriever.d.ts.map +1 -0
  660. package/dist/types/adapters/openai/OpenAIAdapter.d.ts +47 -0
  661. package/dist/types/adapters/openai/OpenAIAdapter.d.ts.map +1 -0
  662. package/dist/types/adapters/resilientProvider.d.ts +33 -0
  663. package/dist/types/adapters/resilientProvider.d.ts.map +1 -0
  664. package/dist/types/agent.js +6 -0
  665. package/dist/types/agent.js.map +1 -0
  666. package/dist/types/compositions/index.d.ts +13 -0
  667. package/dist/types/compositions/index.d.ts.map +1 -0
  668. package/dist/types/compositions/withCircuitBreaker.d.ts +43 -0
  669. package/dist/types/compositions/withCircuitBreaker.d.ts.map +1 -0
  670. package/dist/types/compositions/withFallback.d.ts +17 -0
  671. package/dist/types/compositions/withFallback.d.ts.map +1 -0
  672. package/dist/types/compositions/withRetry.d.ts +27 -0
  673. package/dist/types/compositions/withRetry.d.ts.map +1 -0
  674. package/dist/types/concepts/FlowChart.d.ts +52 -0
  675. package/dist/types/concepts/FlowChart.d.ts.map +1 -0
  676. package/dist/types/concepts/LLMCall.d.ts +56 -0
  677. package/dist/types/concepts/LLMCall.d.ts.map +1 -0
  678. package/dist/types/concepts/Parallel.d.ts +110 -0
  679. package/dist/types/concepts/Parallel.d.ts.map +1 -0
  680. package/dist/types/concepts/RAG.d.ts +71 -0
  681. package/dist/types/concepts/RAG.d.ts.map +1 -0
  682. package/dist/types/concepts/Swarm.d.ts +98 -0
  683. package/dist/types/concepts/Swarm.d.ts.map +1 -0
  684. package/dist/types/concepts/index.d.ts +12 -0
  685. package/dist/types/concepts/index.d.ts.map +1 -0
  686. package/dist/types/concepts/specIcons.d.ts +14 -0
  687. package/dist/types/concepts/specIcons.d.ts.map +1 -0
  688. package/dist/types/content.js +97 -0
  689. package/dist/types/content.js.map +1 -0
  690. package/dist/types/core/config.d.ts +24 -0
  691. package/dist/types/core/config.d.ts.map +1 -0
  692. package/dist/types/core/index.d.ts +15 -0
  693. package/dist/types/core/index.d.ts.map +1 -0
  694. package/dist/types/core/providers.d.ts +160 -0
  695. package/dist/types/core/providers.d.ts.map +1 -0
  696. package/dist/types/core/recorders.d.ts +54 -0
  697. package/dist/types/core/recorders.d.ts.map +1 -0
  698. package/dist/types/errors.js +80 -0
  699. package/dist/types/errors.js.map +1 -0
  700. package/dist/types/executor/agentLoop.d.ts +37 -0
  701. package/dist/types/executor/agentLoop.d.ts.map +1 -0
  702. package/dist/types/executor/index.d.ts +6 -0
  703. package/dist/types/executor/index.d.ts.map +1 -0
  704. package/dist/types/explain.barrel.d.ts +20 -0
  705. package/dist/types/explain.barrel.d.ts.map +1 -0
  706. package/dist/types/index.d.ts +31 -0
  707. package/dist/types/index.d.ts.map +1 -0
  708. package/dist/types/index.js +29 -0
  709. package/dist/types/index.js.map +1 -0
  710. package/dist/types/instructions.barrel.d.ts +24 -0
  711. package/dist/types/instructions.barrel.d.ts.map +1 -0
  712. package/dist/types/lib/call/callLLMStage.d.ts +29 -0
  713. package/dist/types/lib/call/callLLMStage.d.ts.map +1 -0
  714. package/dist/types/lib/call/handleResponseStage.d.ts +35 -0
  715. package/dist/types/lib/call/handleResponseStage.d.ts.map +1 -0
  716. package/dist/types/lib/call/helpers.d.ts +64 -0
  717. package/dist/types/lib/call/helpers.d.ts.map +1 -0
  718. package/dist/types/lib/call/index.d.ts +10 -0
  719. package/dist/types/lib/call/index.d.ts.map +1 -0
  720. package/dist/types/lib/call/parseResponseStage.d.ts +21 -0
  721. package/dist/types/lib/call/parseResponseStage.d.ts.map +1 -0
  722. package/dist/types/lib/call/streamingCallLLMStage.d.ts +23 -0
  723. package/dist/types/lib/call/streamingCallLLMStage.d.ts.map +1 -0
  724. package/dist/types/lib/call/toolExecutionSubflow.d.ts +70 -0
  725. package/dist/types/lib/call/toolExecutionSubflow.d.ts.map +1 -0
  726. package/dist/types/lib/call/types.d.ts +17 -0
  727. package/dist/types/lib/call/types.d.ts.map +1 -0
  728. package/dist/types/lib/concepts/Agent.d.ts +9 -0
  729. package/dist/types/lib/concepts/Agent.d.ts.map +1 -0
  730. package/dist/types/lib/concepts/AgentBuilder.d.ts +152 -0
  731. package/dist/types/lib/concepts/AgentBuilder.d.ts.map +1 -0
  732. package/dist/types/lib/concepts/AgentRunner.d.ts +100 -0
  733. package/dist/types/lib/concepts/AgentRunner.d.ts.map +1 -0
  734. package/dist/types/lib/concepts/index.d.ts +3 -0
  735. package/dist/types/lib/concepts/index.d.ts.map +1 -0
  736. package/dist/types/lib/instructions/InstructionRecorder.d.ts +85 -0
  737. package/dist/types/lib/instructions/InstructionRecorder.d.ts.map +1 -0
  738. package/dist/types/lib/instructions/agentInstruction.d.ts +150 -0
  739. package/dist/types/lib/instructions/agentInstruction.d.ts.map +1 -0
  740. package/dist/types/lib/instructions/buildInstructionsToLLMSubflow.d.ts +56 -0
  741. package/dist/types/lib/instructions/buildInstructionsToLLMSubflow.d.ts.map +1 -0
  742. package/dist/types/lib/instructions/evaluator.d.ts +99 -0
  743. package/dist/types/lib/instructions/evaluator.d.ts.map +1 -0
  744. package/dist/types/lib/instructions/index.d.ts +18 -0
  745. package/dist/types/lib/instructions/index.d.ts.map +1 -0
  746. package/dist/types/lib/instructions/inject.d.ts +54 -0
  747. package/dist/types/lib/instructions/inject.d.ts.map +1 -0
  748. package/dist/types/lib/instructions/preview.d.ts +85 -0
  749. package/dist/types/lib/instructions/preview.d.ts.map +1 -0
  750. package/dist/types/lib/instructions/strictFollowUp.d.ts +88 -0
  751. package/dist/types/lib/instructions/strictFollowUp.d.ts.map +1 -0
  752. package/dist/types/lib/instructions/template.d.ts +52 -0
  753. package/dist/types/lib/instructions/template.d.ts.map +1 -0
  754. package/dist/types/lib/instructions/types.d.ts +394 -0
  755. package/dist/types/lib/instructions/types.d.ts.map +1 -0
  756. package/dist/types/lib/loop/buildAgentLoop.d.ts +67 -0
  757. package/dist/types/lib/loop/buildAgentLoop.d.ts.map +1 -0
  758. package/dist/types/lib/loop/index.d.ts +5 -0
  759. package/dist/types/lib/loop/index.d.ts.map +1 -0
  760. package/dist/types/lib/loop/types.d.ts +248 -0
  761. package/dist/types/lib/loop/types.d.ts.map +1 -0
  762. package/dist/types/lib/narrative/agentRenderer.d.ts +51 -0
  763. package/dist/types/lib/narrative/agentRenderer.d.ts.map +1 -0
  764. package/dist/types/lib/narrative/groundingHelpers.d.ts +94 -0
  765. package/dist/types/lib/narrative/groundingHelpers.d.ts.map +1 -0
  766. package/dist/types/lib/narrative/index.d.ts +5 -0
  767. package/dist/types/lib/narrative/index.d.ts.map +1 -0
  768. package/dist/types/lib/slots/helpers.d.ts +16 -0
  769. package/dist/types/lib/slots/helpers.d.ts.map +1 -0
  770. package/dist/types/lib/slots/index.d.ts +7 -0
  771. package/dist/types/lib/slots/index.d.ts.map +1 -0
  772. package/dist/types/lib/slots/messages/buildMessagesSubflow.d.ts +40 -0
  773. package/dist/types/lib/slots/messages/buildMessagesSubflow.d.ts.map +1 -0
  774. package/dist/types/lib/slots/messages/index.d.ts +3 -0
  775. package/dist/types/lib/slots/messages/index.d.ts.map +1 -0
  776. package/dist/types/lib/slots/messages/types.d.ts +26 -0
  777. package/dist/types/lib/slots/messages/types.d.ts.map +1 -0
  778. package/dist/types/lib/slots/system-prompt/buildSystemPromptSubflow.d.ts +27 -0
  779. package/dist/types/lib/slots/system-prompt/buildSystemPromptSubflow.d.ts.map +1 -0
  780. package/dist/types/lib/slots/system-prompt/index.d.ts +3 -0
  781. package/dist/types/lib/slots/system-prompt/index.d.ts.map +1 -0
  782. package/dist/types/lib/slots/system-prompt/types.d.ts +17 -0
  783. package/dist/types/lib/slots/system-prompt/types.d.ts.map +1 -0
  784. package/dist/types/lib/slots/tools/buildToolsSubflow.d.ts +23 -0
  785. package/dist/types/lib/slots/tools/buildToolsSubflow.d.ts.map +1 -0
  786. package/dist/types/lib/slots/tools/index.d.ts +3 -0
  787. package/dist/types/lib/slots/tools/index.d.ts.map +1 -0
  788. package/dist/types/lib/slots/tools/types.d.ts +18 -0
  789. package/dist/types/lib/slots/tools/types.d.ts.map +1 -0
  790. package/dist/types/lib/swarm/buildSwarmRouting.d.ts +36 -0
  791. package/dist/types/lib/swarm/buildSwarmRouting.d.ts.map +1 -0
  792. package/dist/types/lib/swarm/index.d.ts +3 -0
  793. package/dist/types/lib/swarm/index.d.ts.map +1 -0
  794. package/dist/types/llm.js +7 -0
  795. package/dist/types/llm.js.map +1 -0
  796. package/dist/types/memory/conversationHelpers.d.ts +23 -0
  797. package/dist/types/memory/conversationHelpers.d.ts.map +1 -0
  798. package/dist/types/memory/index.d.ts +2 -0
  799. package/dist/types/memory/index.d.ts.map +1 -0
  800. package/dist/types/messages.js +32 -0
  801. package/dist/types/messages.js.map +1 -0
  802. package/dist/types/models/index.d.ts +4 -0
  803. package/dist/types/models/index.d.ts.map +1 -0
  804. package/dist/types/models/pricing.d.ts +8 -0
  805. package/dist/types/models/pricing.d.ts.map +1 -0
  806. package/dist/types/models/providers.d.ts +23 -0
  807. package/dist/types/models/providers.d.ts.map +1 -0
  808. package/dist/types/models/types.d.ts +25 -0
  809. package/dist/types/models/types.d.ts.map +1 -0
  810. package/dist/types/multiAgent.js +6 -0
  811. package/dist/types/multiAgent.js.map +1 -0
  812. package/dist/types/observe.barrel.d.ts +21 -0
  813. package/dist/types/observe.barrel.d.ts.map +1 -0
  814. package/dist/types/providers/index.d.ts +15 -0
  815. package/dist/types/providers/index.d.ts.map +1 -0
  816. package/dist/types/providers/messages/charBudget.d.ts +19 -0
  817. package/dist/types/providers/messages/charBudget.d.ts.map +1 -0
  818. package/dist/types/providers/messages/compositeMessages.d.ts +16 -0
  819. package/dist/types/providers/messages/compositeMessages.d.ts.map +1 -0
  820. package/dist/types/providers/messages/fullHistory.d.ts +12 -0
  821. package/dist/types/providers/messages/fullHistory.d.ts.map +1 -0
  822. package/dist/types/providers/messages/index.d.ts +15 -0
  823. package/dist/types/providers/messages/index.d.ts.map +1 -0
  824. package/dist/types/providers/messages/persistentHistory.d.ts +32 -0
  825. package/dist/types/providers/messages/persistentHistory.d.ts.map +1 -0
  826. package/dist/types/providers/messages/slidingWindow.d.ts +16 -0
  827. package/dist/types/providers/messages/slidingWindow.d.ts.map +1 -0
  828. package/dist/types/providers/messages/summaryStrategy.d.ts +29 -0
  829. package/dist/types/providers/messages/summaryStrategy.d.ts.map +1 -0
  830. package/dist/types/providers/messages/withToolPairSafety.d.ts +19 -0
  831. package/dist/types/providers/messages/withToolPairSafety.d.ts.map +1 -0
  832. package/dist/types/providers/prompt/compositePrompt.d.ts +20 -0
  833. package/dist/types/providers/prompt/compositePrompt.d.ts.map +1 -0
  834. package/dist/types/providers/prompt/index.d.ts +10 -0
  835. package/dist/types/providers/prompt/index.d.ts.map +1 -0
  836. package/dist/types/providers/prompt/skillBasedPrompt.d.ts +33 -0
  837. package/dist/types/providers/prompt/skillBasedPrompt.d.ts.map +1 -0
  838. package/dist/types/providers/prompt/static.d.ts +6 -0
  839. package/dist/types/providers/prompt/static.d.ts.map +1 -0
  840. package/dist/types/providers/prompt/template.d.ts +6 -0
  841. package/dist/types/providers/prompt/template.d.ts.map +1 -0
  842. package/dist/types/providers/tools/PermissionPolicy.d.ts +76 -0
  843. package/dist/types/providers/tools/PermissionPolicy.d.ts.map +1 -0
  844. package/dist/types/providers/tools/agentAsTool.d.ts +40 -0
  845. package/dist/types/providers/tools/agentAsTool.d.ts.map +1 -0
  846. package/dist/types/providers/tools/compositeTools.d.ts +18 -0
  847. package/dist/types/providers/tools/compositeTools.d.ts.map +1 -0
  848. package/dist/types/providers/tools/dynamicTools.d.ts +27 -0
  849. package/dist/types/providers/tools/dynamicTools.d.ts.map +1 -0
  850. package/dist/types/providers/tools/gatedTools.d.ts +52 -0
  851. package/dist/types/providers/tools/gatedTools.d.ts.map +1 -0
  852. package/dist/types/providers/tools/index.d.ts +15 -0
  853. package/dist/types/providers/tools/index.d.ts.map +1 -0
  854. package/dist/types/providers/tools/noTools.d.ts +6 -0
  855. package/dist/types/providers/tools/noTools.d.ts.map +1 -0
  856. package/dist/types/providers/tools/staticTools.d.ts +7 -0
  857. package/dist/types/providers/tools/staticTools.d.ts.map +1 -0
  858. package/dist/types/providers.barrel.d.ts +34 -0
  859. package/dist/types/providers.barrel.d.ts.map +1 -0
  860. package/dist/types/recorders/index.d.ts +6 -0
  861. package/dist/types/recorders/index.d.ts.map +1 -0
  862. package/dist/types/recorders/v2/CompositeRecorder.d.ts +30 -0
  863. package/dist/types/recorders/v2/CompositeRecorder.d.ts.map +1 -0
  864. package/dist/types/recorders/v2/CostRecorder.d.ts +43 -0
  865. package/dist/types/recorders/v2/CostRecorder.d.ts.map +1 -0
  866. package/dist/types/recorders/v2/ExplainRecorder.d.ts +67 -0
  867. package/dist/types/recorders/v2/ExplainRecorder.d.ts.map +1 -0
  868. package/dist/types/recorders/v2/GuardrailRecorder.d.ts +45 -0
  869. package/dist/types/recorders/v2/GuardrailRecorder.d.ts.map +1 -0
  870. package/dist/types/recorders/v2/OTelRecorder.d.ts +50 -0
  871. package/dist/types/recorders/v2/OTelRecorder.d.ts.map +1 -0
  872. package/dist/types/recorders/v2/PermissionRecorder.d.ts +66 -0
  873. package/dist/types/recorders/v2/PermissionRecorder.d.ts.map +1 -0
  874. package/dist/types/recorders/v2/QualityRecorder.d.ts +37 -0
  875. package/dist/types/recorders/v2/QualityRecorder.d.ts.map +1 -0
  876. package/dist/types/recorders/v2/RecorderBridge.d.ts +38 -0
  877. package/dist/types/recorders/v2/RecorderBridge.d.ts.map +1 -0
  878. package/dist/types/recorders/v2/TokenRecorder.d.ts +54 -0
  879. package/dist/types/recorders/v2/TokenRecorder.d.ts.map +1 -0
  880. package/dist/types/recorders/v2/ToolUsageRecorder.d.ts +34 -0
  881. package/dist/types/recorders/v2/ToolUsageRecorder.d.ts.map +1 -0
  882. package/dist/types/recorders/v2/TurnRecorder.d.ts +36 -0
  883. package/dist/types/recorders/v2/TurnRecorder.d.ts.map +1 -0
  884. package/dist/types/recorders/v2/agentObservability.d.ts +68 -0
  885. package/dist/types/recorders/v2/agentObservability.d.ts.map +1 -0
  886. package/dist/types/recorders/v2/index.d.ts +21 -0
  887. package/dist/types/recorders/v2/index.d.ts.map +1 -0
  888. package/dist/types/resilience.barrel.d.ts +18 -0
  889. package/dist/types/resilience.barrel.d.ts.map +1 -0
  890. package/dist/types/retriever.js +7 -0
  891. package/dist/types/retriever.js.map +1 -0
  892. package/dist/types/scope/AgentScope.d.ts +87 -0
  893. package/dist/types/scope/AgentScope.d.ts.map +1 -0
  894. package/dist/types/scope/index.d.ts +3 -0
  895. package/dist/types/scope/index.d.ts.map +1 -0
  896. package/dist/types/scope/types.d.ts +151 -0
  897. package/dist/types/scope/types.d.ts.map +1 -0
  898. package/dist/types/security.barrel.d.ts +17 -0
  899. package/dist/types/security.barrel.d.ts.map +1 -0
  900. package/dist/types/stages/augmentPrompt.d.ts +7 -0
  901. package/dist/types/stages/augmentPrompt.d.ts.map +1 -0
  902. package/dist/types/stages/callLLM.d.ts +8 -0
  903. package/dist/types/stages/callLLM.d.ts.map +1 -0
  904. package/dist/types/stages/commitMemory.d.ts +51 -0
  905. package/dist/types/stages/commitMemory.d.ts.map +1 -0
  906. package/dist/types/stages/finalize.d.ts +7 -0
  907. package/dist/types/stages/finalize.d.ts.map +1 -0
  908. package/dist/types/stages/helpers.d.ts +17 -0
  909. package/dist/types/stages/helpers.d.ts.map +1 -0
  910. package/dist/types/stages/index.d.ts +10 -0
  911. package/dist/types/stages/index.d.ts.map +1 -0
  912. package/dist/types/stages/parseResponse.d.ts +8 -0
  913. package/dist/types/stages/parseResponse.d.ts.map +1 -0
  914. package/dist/types/stages/retrieve.d.ts +8 -0
  915. package/dist/types/stages/retrieve.d.ts.map +1 -0
  916. package/dist/types/stages/runnerAsStage.d.ts +18 -0
  917. package/dist/types/stages/runnerAsStage.d.ts.map +1 -0
  918. package/dist/types/stream.barrel.d.ts +19 -0
  919. package/dist/types/stream.barrel.d.ts.map +1 -0
  920. package/dist/types/streaming/StreamEmitter.d.ts +93 -0
  921. package/dist/types/streaming/StreamEmitter.d.ts.map +1 -0
  922. package/dist/types/streaming/index.d.ts +3 -0
  923. package/dist/types/streaming/index.d.ts.map +1 -0
  924. package/dist/types/subflows/index.d.ts +3 -0
  925. package/dist/types/subflows/index.d.ts.map +1 -0
  926. package/dist/types/subflows/prepareMemory.d.ts +60 -0
  927. package/dist/types/subflows/prepareMemory.d.ts.map +1 -0
  928. package/dist/types/tools/ToolRegistry.d.ts +47 -0
  929. package/dist/types/tools/ToolRegistry.d.ts.map +1 -0
  930. package/dist/types/tools/askHuman.d.ts +39 -0
  931. package/dist/types/tools/askHuman.d.ts.map +1 -0
  932. package/dist/types/tools/index.d.ts +3 -0
  933. package/dist/types/tools/index.d.ts.map +1 -0
  934. package/dist/types/tools/validateInput.d.ts +29 -0
  935. package/dist/types/tools/validateInput.d.ts.map +1 -0
  936. package/dist/types/tools/zodToJsonSchema.d.ts +9 -0
  937. package/dist/types/tools/zodToJsonSchema.d.ts.map +1 -0
  938. package/dist/types/tools.js +6 -0
  939. package/dist/types/tools.js.map +1 -0
  940. package/dist/types/types/adapter.d.ts +36 -0
  941. package/dist/types/types/adapter.d.ts.map +1 -0
  942. package/dist/types/types/agent.d.ts +37 -0
  943. package/dist/types/types/agent.d.ts.map +1 -0
  944. package/dist/types/types/content.d.ts +104 -0
  945. package/dist/types/types/content.d.ts.map +1 -0
  946. package/dist/types/types/errors.d.ts +27 -0
  947. package/dist/types/types/errors.d.ts.map +1 -0
  948. package/dist/types/types/index.d.ts +14 -0
  949. package/dist/types/types/index.d.ts.map +1 -0
  950. package/dist/types/types/llm.d.ts +78 -0
  951. package/dist/types/types/llm.d.ts.map +1 -0
  952. package/dist/types/types/messages.d.ts +40 -0
  953. package/dist/types/types/messages.d.ts.map +1 -0
  954. package/dist/types/types/multiAgent.d.ts +57 -0
  955. package/dist/types/types/multiAgent.d.ts.map +1 -0
  956. package/dist/types/types/retriever.d.ts +41 -0
  957. package/dist/types/types/retriever.d.ts.map +1 -0
  958. package/dist/types/types/tools.d.ts +19 -0
  959. package/dist/types/types/tools.d.ts.map +1 -0
  960. package/package.json +178 -0
package/AGENTS.md ADDED
@@ -0,0 +1,297 @@
1
+ # agentfootprint — Agent Coding Instructions
2
+
3
+ This is the agentfootprint library — the explainable agent framework. Build AI agents you can explain, audit, and trust. Built on footprintjs.
4
+
5
+ ## Core Principles
6
+
7
+ - **Adapter-swap testing.** Every concept uses `LLMProvider` — swap `mock([...])` for `createProvider(anthropic(...))` with zero code changes. $0 test runs, deterministic assertions.
8
+ - **Concept ladder.** Five concepts, each a flowchart: LLMCall < RAG < Agent < FlowChart < Swarm. Each adds exactly one capability.
9
+ - **Built-in recorders.** Observe tokens, cost, tool usage, quality, guardrails — all via `.recorder()` on the builder. Never shape behavior, only observe.
10
+ - **Collect during traversal.** Inherited from footprintjs — all data collection happens as side effects of the single DFS traversal pass. Never post-process.
11
+
12
+ ## Architecture — Library of Libraries
13
+
14
+ ```
15
+ src/
16
+ ├── core/ → AgentLoopConfig, AgentRecorder interface, PromptProvider/ToolProvider interfaces
17
+ ├── concepts/ → 5 builders + runners (LLMCall, Agent, RAG, FlowChart, Swarm)
18
+ ├── adapters/ → LLMProvider implementations (mock, anthropic, openai, bedrock, mcp, a2a)
19
+ ├── models/ → ModelConfig factories (anthropic(), openai(), ollama(), bedrock())
20
+ ├── providers/ → Strategy implementations (prompt/, messages/, tools/)
21
+ ├── recorders/ → Scope-level (LLMRecorder, RAGRecorder) + v2 AgentRecorder impls
22
+ ├── tools/ → ToolRegistry + defineTool
23
+ ├── stages/ → Reusable flowchart stages (seedScope, callLLM, parseResponse, etc.)
24
+ ├── scope/ → AgentScope paths + helpers
25
+ ├── memory/ → Message utilities (appendMessage, slidingWindow, truncateToCharBudget)
26
+ ├── executor/ → agentLoop (core ReAct loop)
27
+ ├── compositions/→ withRetry, withFallback, withCircuitBreaker
28
+ ├── streaming/ → StreamEmitter, SSEFormatter, AgentStreamEvent
29
+ ├── lib/ → Instructions (agentInstruction, InstructionsToLLM subflow), narrative (grounding helpers), loop (buildAgentLoop), slots, call stages
30
+ └── types/ → All type definitions (messages, llm, tools, content blocks)
31
+ ```
32
+
33
+ Single entry point: `import { ... } from 'agentfootprint'`
34
+
35
+ ## Five Concepts (Builder API)
36
+
37
+ ### LLMCall — Single LLM call, no tools, no loop
38
+
39
+ ```typescript
40
+ import { LLMCall, mock } from 'agentfootprint';
41
+
42
+ const caller = LLMCall.create({ provider: mock([{ content: 'Hello!' }]) })
43
+ .system('You are helpful.')
44
+ .recorder(tokens)
45
+ .build();
46
+
47
+ const result = await caller.run('Hi');
48
+ // result.content — string response
49
+ ```
50
+
51
+ ### Agent — Full ReAct agent with tools and loop
52
+
53
+ ```typescript
54
+ import { Agent, defineTool, mock } from 'agentfootprint';
55
+
56
+ const searchTool = defineTool({
57
+ id: 'search',
58
+ description: 'Search the web',
59
+ inputSchema: { type: 'object', properties: { query: { type: 'string' } } },
60
+ handler: async (input) => ({ content: `Results for: ${input.query}` }),
61
+ });
62
+
63
+ const agent = Agent.create({ provider: mock([...]), name: 'my-agent' })
64
+ .system('You are a research assistant.')
65
+ .tool(searchTool)
66
+ .maxIterations(5)
67
+ .recorder(tokens)
68
+ .build();
69
+
70
+ const result = await agent.run('Find info about AI');
71
+ // result.content, result.messages, result.toolCalls
72
+ ```
73
+
74
+ ### RAG — Retrieve-Augment-Generate
75
+
76
+ ```typescript
77
+ import { RAG, mock, mockRetriever } from 'agentfootprint';
78
+
79
+ const rag = RAG.create({
80
+ provider: mock([{ content: 'Answer based on context.' }]),
81
+ retriever: mockRetriever([{ chunks: [{ content: 'doc text', score: 0.9 }] }]),
82
+ })
83
+ .system('Answer using the provided context.')
84
+ .topK(5)
85
+ .minScore(0.7)
86
+ .recorder(tokens)
87
+ .build();
88
+
89
+ const result = await rag.run('What is X?');
90
+ // result.content, result.retrieval
91
+ ```
92
+
93
+ ### FlowChart — Sequential multi-agent composition
94
+
95
+ ```typescript
96
+ import { FlowChart } from 'agentfootprint';
97
+
98
+ const pipeline = FlowChart.create()
99
+ .agent('researcher', 'Research', researchRunner)
100
+ .agent('writer', 'Write', writerRunner)
101
+ .recorder(tokens)
102
+ .build();
103
+
104
+ const result = await pipeline.run('Write about AI');
105
+ // result.results — array of per-agent results
106
+ ```
107
+
108
+ ### Swarm — LLM-routed multi-agent handoff
109
+
110
+ ```typescript
111
+ import { Swarm, createProvider, anthropic } from 'agentfootprint';
112
+
113
+ const swarm = Swarm.create({ provider: createProvider(anthropic('claude-sonnet-4-20250514')) })
114
+ .system('You are a router. Delegate to specialists.')
115
+ .specialist('research', 'Research a topic.', researchRunner)
116
+ .specialist('write', 'Write content.', writerRunner)
117
+ .maxIterations(10)
118
+ .recorder(tokens)
119
+ .build();
120
+
121
+ const result = await swarm.run('Write about AI');
122
+ ```
123
+
124
+ ## Tools
125
+
126
+ ```typescript
127
+ import { defineTool } from 'agentfootprint';
128
+
129
+ const tool = defineTool({
130
+ id: 'calculator',
131
+ description: 'Perform arithmetic',
132
+ inputSchema: {
133
+ type: 'object',
134
+ properties: { expression: { type: 'string' } },
135
+ required: ['expression'],
136
+ },
137
+ handler: async (input) => ({ content: String(eval(input.expression)) }),
138
+ });
139
+ ```
140
+
141
+ ## Provider System
142
+
143
+ Three provider interfaces — active strategies that shape what the LLM sees:
144
+
145
+ - **PromptProvider** — resolves system prompt per turn: `staticPrompt()`, `templatePrompt()`, `skillBasedPrompt()`, `compositePrompt()`
146
+ - **MessageStrategy** — prepares message array: `fullHistory()`, `slidingWindow()`, `charBudget()`, `summaryStrategy()`, `persistentHistory()`
147
+ - **ToolProvider** — resolves available tools: `staticTools()`, `dynamicTools()`, `noTools()`, `agentAsTool()`, `compositeTools()`
148
+
149
+ ## Adapters (LLMProvider implementations)
150
+
151
+ ```typescript
152
+ import { mock, createProvider, anthropic, openai, ollama, bedrock } from 'agentfootprint';
153
+
154
+ // Testing (deterministic, $0):
155
+ const provider = mock([{ content: 'response 1' }, { content: 'response 2' }]);
156
+
157
+ // Production:
158
+ const provider = createProvider(anthropic('claude-sonnet-4-20250514'));
159
+ const provider = createProvider(openai('gpt-4o'));
160
+ const provider = createProvider(ollama('llama3'));
161
+ const provider = createProvider(bedrock('anthropic.claude-3-sonnet'));
162
+ ```
163
+
164
+ ## Recorder System
165
+
166
+ Attach via `.recorder(rec)` on any builder. All implement `AgentRecorder` interface.
167
+
168
+ ```typescript
169
+ import {
170
+ TokenRecorder,
171
+ CostRecorder,
172
+ TurnRecorder,
173
+ ToolUsageRecorder,
174
+ QualityRecorder,
175
+ GuardrailRecorder,
176
+ CompositeRecorder,
177
+ } from 'agentfootprint';
178
+
179
+ const tokens = new TokenRecorder();
180
+ const costs = new CostRecorder({ pricingTable: { 'claude-sonnet': { input: 3, output: 15 } } });
181
+ const turns = new TurnRecorder();
182
+ const toolUsage = new ToolUsageRecorder();
183
+
184
+ const agent = Agent.create({ provider })
185
+ .system('...')
186
+ .recorder(tokens)
187
+ .recorder(costs)
188
+ .build();
189
+
190
+ await agent.run('Hello');
191
+
192
+ tokens.getStats(); // { totalCalls, totalInputTokens, totalOutputTokens, ... }
193
+ costs.getTotalCost(); // number (USD)
194
+ costs.getEntries(); // CostEntry[]
195
+ turns.getEntries(); // TurnEntry[]
196
+ toolUsage.getStats(); // ToolUsageStats
197
+ ```
198
+
199
+ Use `CompositeRecorder` to bundle multiple recorders:
200
+
201
+ ```typescript
202
+ const composite = new CompositeRecorder([tokens, costs, turns]);
203
+ agent.recorder(composite);
204
+ ```
205
+
206
+ ## Compositions (Resilience Wrappers)
207
+
208
+ ```typescript
209
+ import { withRetry, withFallback, withCircuitBreaker } from 'agentfootprint';
210
+
211
+ const resilient = withRetry(provider, { maxRetries: 3 });
212
+ const fallback = withFallback([primaryProvider, backupProvider]);
213
+ const breaker = withCircuitBreaker(provider, { failureThreshold: 5 });
214
+ ```
215
+
216
+ ## Instructions — Conditional Context Injection
217
+
218
+ ```typescript
219
+ import { defineInstruction, Agent, AgentPattern } from 'agentfootprint';
220
+
221
+ const refund = defineInstruction<MyDecision>({
222
+ id: 'refund-handling',
223
+ activeWhen: (d) => d.orderStatus === 'denied',
224
+ prompt: 'Handle denied orders with empathy.',
225
+ tools: [processRefund],
226
+ onToolResult: [{ id: 'empathy', text: 'Do NOT promise reversal.' }],
227
+ });
228
+
229
+ const agent = Agent.create({ provider })
230
+ .tool(lookupOrder)
231
+ .instruction(refund)
232
+ .decision<MyDecision>({ orderStatus: null })
233
+ .pattern(AgentPattern.Dynamic)
234
+ .build();
235
+ ```
236
+
237
+ Builder methods: `.instruction(instr)`, `.instructions([...])`, `.decision<T>({...})`, `.verbose()`
238
+
239
+ Three naming conventions:
240
+ - `activeWhen(decision)` — agent-level, reads Decision Scope
241
+ - `when(ctx)` — tool-level, reads tool result context
242
+ - `decide(decision, ctx)` — bridges tool results to Decision Scope
243
+
244
+ ## Streaming — AgentStreamEvent
245
+
246
+ ```typescript
247
+ const result = await agent.run('hello', {
248
+ onEvent: (event) => {
249
+ switch (event.type) {
250
+ case 'token': process.stdout.write(event.content); break;
251
+ case 'tool_start': console.log(`Running ${event.toolName}...`); break;
252
+ case 'tool_end': console.log(`Done (${event.latencyMs}ms)`); break;
253
+ case 'llm_end': console.log(`[${event.model}, ${event.latencyMs}ms]`); break;
254
+ }
255
+ },
256
+ });
257
+ ```
258
+
259
+ 9 events: `turn_start`, `llm_start`, `thinking`, `token`, `llm_end`, `tool_start`, `tool_end`, `turn_end`, `error`.
260
+ Tool lifecycle fires without `.streaming(true)`. Only `token`/`thinking` require streaming.
261
+ `onToken` is deprecated — use `onEvent`.
262
+
263
+ ## Grounding Analysis
264
+
265
+ ```typescript
266
+ import { getGroundingSources, getLLMClaims, getFullLLMContext } from 'agentfootprint';
267
+
268
+ const entries = agent.getNarrativeEntries();
269
+ const sources = getGroundingSources(entries); // tool results (sources of truth)
270
+ const claims = getLLMClaims(entries); // LLM output (to verify)
271
+ const context = getFullLLMContext(entries); // { systemPrompt, toolDescriptions, sources, claims, decision }
272
+ ```
273
+
274
+ Uses `CombinedNarrativeEntry.key` + `AgentScopeKey` enum — renderer-independent.
275
+
276
+ ## Anti-Patterns
277
+
278
+ - Never use the old functional API (`LLMCall({...})`, `Agent({...})`) — always use `LLMCall.create({...})` builder pattern
279
+ - Never use `CostRecorderV2` — use `CostRecorder` (V2 is a deprecated alias)
280
+ - Never pass recorders via constructor options — use `.recorder()` builder method
281
+ - Don't use `name`/`parameters` on `defineTool` — use `id`/`inputSchema`
282
+ - Don't use `tokens.stats()` — use `tokens.getStats()`
283
+ - Don't use `costs.totalCost()` — use `costs.getTotalCost()`
284
+ - Don't post-process the execution tree — use recorders
285
+ - Don't put infrastructure concerns in input — use footprintjs `getEnv()` for signal/traceId
286
+ - Don't pass functions through scope — they get stripped. Use closure captures (InstructionConfig pattern)
287
+ - Don't use `onToken` — use `onEvent` (onToken is deprecated, ignored when onEvent is set)
288
+ - Don't match grounding helpers on `entry.text` — use `entry.key` with `AgentScopeKey` enum
289
+
290
+ ## Build & Test
291
+
292
+ ```bash
293
+ npm run build # tsc (CJS) + tsc -p tsconfig.esm.json (ESM)
294
+ npm test # vitest — 1295+ tests
295
+ ```
296
+
297
+ Dual output: CommonJS (`dist/`) + ESM (`dist/esm/`) + types (`dist/types/`)
package/CLAUDE.md ADDED
@@ -0,0 +1,297 @@
1
+ # agentfootprint — AI Coding Instructions
2
+
3
+ This is the agentfootprint library — the explainable agent framework. Build AI agents you can explain, audit, and trust. Built on footprintjs.
4
+
5
+ ## Core Principles
6
+
7
+ - **Adapter-swap testing.** Every concept uses `LLMProvider` — swap `mock([...])` for `createProvider(anthropic(...))` with zero code changes. $0 test runs, deterministic assertions.
8
+ - **Concept ladder.** Five concepts, each a flowchart: LLMCall < RAG < Agent < FlowChart < Swarm. Each adds exactly one capability.
9
+ - **Built-in recorders.** Observe tokens, cost, tool usage, quality, guardrails — all via `.recorder()` on the builder. Never shape behavior, only observe.
10
+ - **Collect during traversal.** Inherited from footprintjs — all data collection happens as side effects of the single DFS traversal pass. Never post-process.
11
+
12
+ ## Architecture — Library of Libraries
13
+
14
+ ```
15
+ src/
16
+ ├── core/ → AgentLoopConfig, AgentRecorder interface, PromptProvider/ToolProvider interfaces
17
+ ├── concepts/ → 5 builders + runners (LLMCall, Agent, RAG, FlowChart, Swarm)
18
+ ├── adapters/ → LLMProvider implementations (mock, anthropic, openai, bedrock, mcp, a2a)
19
+ ├── models/ → ModelConfig factories (anthropic(), openai(), ollama(), bedrock())
20
+ ├── providers/ → Strategy implementations (prompt/, messages/, tools/)
21
+ ├── recorders/ → Scope-level (LLMRecorder, RAGRecorder) + v2 AgentRecorder impls
22
+ ├── tools/ → ToolRegistry + defineTool
23
+ ├── stages/ → Reusable flowchart stages (seedScope, callLLM, parseResponse, etc.)
24
+ ├── scope/ → AgentScope paths + helpers
25
+ ├── memory/ → Message utilities (appendMessage, slidingWindow, truncateToCharBudget)
26
+ ├── executor/ → agentLoop (core ReAct loop)
27
+ ├── compositions/→ withRetry, withFallback, withCircuitBreaker
28
+ ├── streaming/ → StreamEmitter, SSEFormatter, AgentStreamEvent
29
+ ├── lib/ → Instructions (agentInstruction, InstructionsToLLM subflow), narrative (grounding helpers), loop (buildAgentLoop), slots, call stages
30
+ └── types/ → All type definitions (messages, llm, tools, content blocks)
31
+ ```
32
+
33
+ Single entry point: `import { ... } from 'agentfootprint'`
34
+
35
+ ## Five Concepts (Builder API)
36
+
37
+ ### LLMCall — Single LLM call, no tools, no loop
38
+
39
+ ```typescript
40
+ import { LLMCall, mock } from 'agentfootprint';
41
+
42
+ const caller = LLMCall.create({ provider: mock([{ content: 'Hello!' }]) })
43
+ .system('You are helpful.')
44
+ .recorder(tokens)
45
+ .build();
46
+
47
+ const result = await caller.run('Hi');
48
+ // result.content — string response
49
+ ```
50
+
51
+ ### Agent — Full ReAct agent with tools and loop
52
+
53
+ ```typescript
54
+ import { Agent, defineTool, mock } from 'agentfootprint';
55
+
56
+ const searchTool = defineTool({
57
+ id: 'search',
58
+ description: 'Search the web',
59
+ inputSchema: { type: 'object', properties: { query: { type: 'string' } } },
60
+ handler: async (input) => ({ content: `Results for: ${input.query}` }),
61
+ });
62
+
63
+ const agent = Agent.create({ provider: mock([...]), name: 'my-agent' })
64
+ .system('You are a research assistant.')
65
+ .tool(searchTool)
66
+ .maxIterations(5)
67
+ .recorder(tokens)
68
+ .build();
69
+
70
+ const result = await agent.run('Find info about AI');
71
+ // result.content, result.messages, result.toolCalls
72
+ ```
73
+
74
+ ### RAG — Retrieve-Augment-Generate
75
+
76
+ ```typescript
77
+ import { RAG, mock, mockRetriever } from 'agentfootprint';
78
+
79
+ const rag = RAG.create({
80
+ provider: mock([{ content: 'Answer based on context.' }]),
81
+ retriever: mockRetriever([{ chunks: [{ content: 'doc text', score: 0.9 }] }]),
82
+ })
83
+ .system('Answer using the provided context.')
84
+ .topK(5)
85
+ .minScore(0.7)
86
+ .recorder(tokens)
87
+ .build();
88
+
89
+ const result = await rag.run('What is X?');
90
+ // result.content, result.retrieval
91
+ ```
92
+
93
+ ### FlowChart — Sequential multi-agent composition
94
+
95
+ ```typescript
96
+ import { FlowChart } from 'agentfootprint';
97
+
98
+ const pipeline = FlowChart.create()
99
+ .agent('researcher', 'Research', researchRunner)
100
+ .agent('writer', 'Write', writerRunner)
101
+ .recorder(tokens)
102
+ .build();
103
+
104
+ const result = await pipeline.run('Write about AI');
105
+ // result.results — array of per-agent results
106
+ ```
107
+
108
+ ### Swarm — LLM-routed multi-agent handoff
109
+
110
+ ```typescript
111
+ import { Swarm, createProvider, anthropic } from 'agentfootprint';
112
+
113
+ const swarm = Swarm.create({ provider: createProvider(anthropic('claude-sonnet-4-20250514')) })
114
+ .system('You are a router. Delegate to specialists.')
115
+ .specialist('research', 'Research a topic.', researchRunner)
116
+ .specialist('write', 'Write content.', writerRunner)
117
+ .maxIterations(10)
118
+ .recorder(tokens)
119
+ .build();
120
+
121
+ const result = await swarm.run('Write about AI');
122
+ ```
123
+
124
+ ## Tools
125
+
126
+ ```typescript
127
+ import { defineTool } from 'agentfootprint';
128
+
129
+ const tool = defineTool({
130
+ id: 'calculator',
131
+ description: 'Perform arithmetic',
132
+ inputSchema: {
133
+ type: 'object',
134
+ properties: { expression: { type: 'string' } },
135
+ required: ['expression'],
136
+ },
137
+ handler: async (input) => ({ content: String(eval(input.expression)) }),
138
+ });
139
+ ```
140
+
141
+ ## Provider System
142
+
143
+ Three provider interfaces — active strategies that shape what the LLM sees:
144
+
145
+ - **PromptProvider** — resolves system prompt per turn: `staticPrompt()`, `templatePrompt()`, `skillBasedPrompt()`, `compositePrompt()`
146
+ - **MessageStrategy** — prepares message array: `fullHistory()`, `slidingWindow()`, `charBudget()`, `summaryStrategy()`, `persistentHistory()`
147
+ - **ToolProvider** — resolves available tools: `staticTools()`, `dynamicTools()`, `noTools()`, `agentAsTool()`, `compositeTools()`
148
+
149
+ ## Adapters (LLMProvider implementations)
150
+
151
+ ```typescript
152
+ import { mock, createProvider, anthropic, openai, ollama, bedrock } from 'agentfootprint';
153
+
154
+ // Testing (deterministic, $0):
155
+ const provider = mock([{ content: 'response 1' }, { content: 'response 2' }]);
156
+
157
+ // Production:
158
+ const provider = createProvider(anthropic('claude-sonnet-4-20250514'));
159
+ const provider = createProvider(openai('gpt-4o'));
160
+ const provider = createProvider(ollama('llama3'));
161
+ const provider = createProvider(bedrock('anthropic.claude-3-sonnet'));
162
+ ```
163
+
164
+ ## Recorder System
165
+
166
+ Attach via `.recorder(rec)` on any builder. All implement `AgentRecorder` interface.
167
+
168
+ ```typescript
169
+ import {
170
+ TokenRecorder,
171
+ CostRecorder,
172
+ TurnRecorder,
173
+ ToolUsageRecorder,
174
+ QualityRecorder,
175
+ GuardrailRecorder,
176
+ CompositeRecorder,
177
+ } from 'agentfootprint';
178
+
179
+ const tokens = new TokenRecorder();
180
+ const costs = new CostRecorder({ pricingTable: { 'claude-sonnet': { input: 3, output: 15 } } });
181
+ const turns = new TurnRecorder();
182
+ const toolUsage = new ToolUsageRecorder();
183
+
184
+ const agent = Agent.create({ provider })
185
+ .system('...')
186
+ .recorder(tokens)
187
+ .recorder(costs)
188
+ .build();
189
+
190
+ await agent.run('Hello');
191
+
192
+ tokens.getStats(); // { totalCalls, totalInputTokens, totalOutputTokens, ... }
193
+ costs.getTotalCost(); // number (USD)
194
+ costs.getEntries(); // CostEntry[]
195
+ turns.getEntries(); // TurnEntry[]
196
+ toolUsage.getStats(); // ToolUsageStats
197
+ ```
198
+
199
+ Use `CompositeRecorder` to bundle multiple recorders:
200
+
201
+ ```typescript
202
+ const composite = new CompositeRecorder([tokens, costs, turns]);
203
+ agent.recorder(composite);
204
+ ```
205
+
206
+ ## Compositions (Resilience Wrappers)
207
+
208
+ ```typescript
209
+ import { withRetry, withFallback, withCircuitBreaker } from 'agentfootprint';
210
+
211
+ const resilient = withRetry(provider, { maxRetries: 3 });
212
+ const fallback = withFallback([primaryProvider, backupProvider]);
213
+ const breaker = withCircuitBreaker(provider, { failureThreshold: 5 });
214
+ ```
215
+
216
+ ## Instructions — Conditional Context Injection
217
+
218
+ ```typescript
219
+ import { defineInstruction, Agent, AgentPattern } from 'agentfootprint';
220
+
221
+ const refund = defineInstruction<MyDecision>({
222
+ id: 'refund-handling',
223
+ activeWhen: (d) => d.orderStatus === 'denied',
224
+ prompt: 'Handle denied orders with empathy.',
225
+ tools: [processRefund],
226
+ onToolResult: [{ id: 'empathy', text: 'Do NOT promise reversal.' }],
227
+ });
228
+
229
+ const agent = Agent.create({ provider })
230
+ .tool(lookupOrder)
231
+ .instruction(refund)
232
+ .decision<MyDecision>({ orderStatus: null })
233
+ .pattern(AgentPattern.Dynamic)
234
+ .build();
235
+ ```
236
+
237
+ Builder methods: `.instruction(instr)`, `.instructions([...])`, `.decision<T>({...})`, `.verbose()`
238
+
239
+ Three naming conventions:
240
+ - `activeWhen(decision)` — agent-level, reads Decision Scope
241
+ - `when(ctx)` — tool-level, reads tool result context
242
+ - `decide(decision, ctx)` — bridges tool results to Decision Scope
243
+
244
+ ## Streaming — AgentStreamEvent
245
+
246
+ ```typescript
247
+ const result = await agent.run('hello', {
248
+ onEvent: (event) => {
249
+ switch (event.type) {
250
+ case 'token': process.stdout.write(event.content); break;
251
+ case 'tool_start': console.log(`Running ${event.toolName}...`); break;
252
+ case 'tool_end': console.log(`Done (${event.latencyMs}ms)`); break;
253
+ case 'llm_end': console.log(`[${event.model}, ${event.latencyMs}ms]`); break;
254
+ }
255
+ },
256
+ });
257
+ ```
258
+
259
+ 9 events: `turn_start`, `llm_start`, `thinking`, `token`, `llm_end`, `tool_start`, `tool_end`, `turn_end`, `error`.
260
+ Tool lifecycle fires without `.streaming(true)`. Only `token`/`thinking` require streaming.
261
+ `onToken` is deprecated — use `onEvent`.
262
+
263
+ ## Grounding Analysis
264
+
265
+ ```typescript
266
+ import { getGroundingSources, getLLMClaims, getFullLLMContext } from 'agentfootprint';
267
+
268
+ const entries = agent.getNarrativeEntries();
269
+ const sources = getGroundingSources(entries); // tool results (sources of truth)
270
+ const claims = getLLMClaims(entries); // LLM output (to verify)
271
+ const context = getFullLLMContext(entries); // { systemPrompt, toolDescriptions, sources, claims, decision }
272
+ ```
273
+
274
+ Uses `CombinedNarrativeEntry.key` + `AgentScopeKey` enum — renderer-independent.
275
+
276
+ ## Anti-Patterns
277
+
278
+ - Never use the old functional API (`LLMCall({...})`, `Agent({...})`) — always use `LLMCall.create({...})` builder pattern
279
+ - Never use `CostRecorderV2` — use `CostRecorder` (V2 is a deprecated alias)
280
+ - Never pass recorders via constructor options — use `.recorder()` builder method
281
+ - Don't use `name`/`parameters` on `defineTool` — use `id`/`inputSchema`
282
+ - Don't use `tokens.stats()` — use `tokens.getStats()`
283
+ - Don't use `costs.totalCost()` — use `costs.getTotalCost()`
284
+ - Don't post-process the execution tree — use recorders
285
+ - Don't put infrastructure concerns in input — use footprintjs `getEnv()` for signal/traceId
286
+ - Don't pass functions through scope — they get stripped. Use closure captures (InstructionConfig pattern)
287
+ - Don't use `onToken` — use `onEvent` (onToken is deprecated, ignored when onEvent is set)
288
+ - Don't match grounding helpers on `entry.text` — use `entry.key` with `AgentScopeKey` enum
289
+
290
+ ## Build & Test
291
+
292
+ ```bash
293
+ npm run build # tsc (CJS) + tsc -p tsconfig.esm.json (ESM)
294
+ npm test # vitest — 1295+ tests
295
+ ```
296
+
297
+ Dual output: CommonJS (`dist/`) + ESM (`dist/esm/`) + types (`dist/types/`)
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024-present Sanjay Krishna Anbalagan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.