@minded-ai/mindedjs 1.0.0-ec2-beta-1

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 (454) hide show
  1. package/README.md +6 -0
  2. package/dist/agent.d.ts +256 -0
  3. package/dist/agent.d.ts.map +1 -0
  4. package/dist/agent.js +896 -0
  5. package/dist/agent.js.map +1 -0
  6. package/dist/browserTask/README.md +419 -0
  7. package/dist/browserTask/browserAgent.py +632 -0
  8. package/dist/browserTask/captcha_isolated.png +0 -0
  9. package/dist/browserTask/executeBrowserTask.d.ts +14 -0
  10. package/dist/browserTask/executeBrowserTask.d.ts.map +1 -0
  11. package/dist/browserTask/executeBrowserTask.js +195 -0
  12. package/dist/browserTask/executeBrowserTask.js.map +1 -0
  13. package/dist/browserTask/executeBrowserTask.py +153 -0
  14. package/dist/browserTask/executeBrowserTask.ts +79 -0
  15. package/dist/browserTask/localBrowserTask.d.ts +49 -0
  16. package/dist/browserTask/localBrowserTask.d.ts.map +1 -0
  17. package/dist/browserTask/localBrowserTask.js +284 -0
  18. package/dist/browserTask/localBrowserTask.js.map +1 -0
  19. package/dist/browserTask/requirements.txt +8 -0
  20. package/dist/browserTask/setup.sh +144 -0
  21. package/dist/browserTask/types.d.ts +35 -0
  22. package/dist/browserTask/types.d.ts.map +1 -0
  23. package/dist/browserTask/types.js +10 -0
  24. package/dist/browserTask/types.js.map +1 -0
  25. package/dist/checkpointer/checkpointSaverFactory.d.ts +7 -0
  26. package/dist/checkpointer/checkpointSaverFactory.d.ts.map +1 -0
  27. package/dist/checkpointer/checkpointSaverFactory.js +53 -0
  28. package/dist/checkpointer/checkpointSaverFactory.js.map +1 -0
  29. package/dist/cli/index.d.ts +3 -0
  30. package/dist/cli/index.d.ts.map +1 -0
  31. package/dist/cli/index.js +209 -0
  32. package/dist/cli/index.js.map +1 -0
  33. package/dist/cli/lambdaHandlerTemplate.d.ts +10 -0
  34. package/dist/cli/lambdaHandlerTemplate.d.ts.map +1 -0
  35. package/dist/cli/lambdaHandlerTemplate.js +76 -0
  36. package/dist/cli/lambdaHandlerTemplate.js.map +1 -0
  37. package/dist/cli/lambdaHandlerTemplate.ts +78 -0
  38. package/dist/cli/localOperatorSetup.d.ts +6 -0
  39. package/dist/cli/localOperatorSetup.d.ts.map +1 -0
  40. package/dist/cli/localOperatorSetup.js +310 -0
  41. package/dist/cli/localOperatorSetup.js.map +1 -0
  42. package/dist/debugging/index.d.ts +2 -0
  43. package/dist/debugging/index.d.ts.map +1 -0
  44. package/dist/debugging/index.js +6 -0
  45. package/dist/debugging/index.js.map +1 -0
  46. package/dist/debugging/llmCallbackHandler.d.ts +36 -0
  47. package/dist/debugging/llmCallbackHandler.d.ts.map +1 -0
  48. package/dist/debugging/llmCallbackHandler.js +101 -0
  49. package/dist/debugging/llmCallbackHandler.js.map +1 -0
  50. package/dist/edges/createDirectEdge.d.ts +4 -0
  51. package/dist/edges/createDirectEdge.d.ts.map +1 -0
  52. package/dist/edges/createDirectEdge.js +24 -0
  53. package/dist/edges/createDirectEdge.js.map +1 -0
  54. package/dist/edges/createLogicalRouter.d.ts +8 -0
  55. package/dist/edges/createLogicalRouter.d.ts.map +1 -0
  56. package/dist/edges/createLogicalRouter.js +194 -0
  57. package/dist/edges/createLogicalRouter.js.map +1 -0
  58. package/dist/edges/createPromptRouter.d.ts +12 -0
  59. package/dist/edges/createPromptRouter.d.ts.map +1 -0
  60. package/dist/edges/createPromptRouter.js +176 -0
  61. package/dist/edges/createPromptRouter.js.map +1 -0
  62. package/dist/edges/edgeFactory.d.ts +14 -0
  63. package/dist/edges/edgeFactory.d.ts.map +1 -0
  64. package/dist/edges/edgeFactory.js +125 -0
  65. package/dist/edges/edgeFactory.js.map +1 -0
  66. package/dist/events/AgentEvents.d.ts +56 -0
  67. package/dist/events/AgentEvents.d.ts.map +1 -0
  68. package/dist/events/AgentEvents.js +13 -0
  69. package/dist/events/AgentEvents.js.map +1 -0
  70. package/dist/events/index.d.ts +3 -0
  71. package/dist/events/index.d.ts.map +1 -0
  72. package/dist/events/index.js +5 -0
  73. package/dist/events/index.js.map +1 -0
  74. package/dist/index.d.ts +35 -0
  75. package/dist/index.d.ts.map +1 -0
  76. package/dist/index.js +98 -0
  77. package/dist/index.js.map +1 -0
  78. package/dist/interfaces/zendesk.d.ts +35 -0
  79. package/dist/interfaces/zendesk.d.ts.map +1 -0
  80. package/dist/interfaces/zendesk.js +219 -0
  81. package/dist/interfaces/zendesk.js.map +1 -0
  82. package/dist/internalTools/appActionRunnerTool.d.ts +5 -0
  83. package/dist/internalTools/appActionRunnerTool.d.ts.map +1 -0
  84. package/dist/internalTools/appActionRunnerTool.js +88 -0
  85. package/dist/internalTools/appActionRunnerTool.js.map +1 -0
  86. package/dist/internalTools/documentExtraction/documentExtraction.d.ts +129 -0
  87. package/dist/internalTools/documentExtraction/documentExtraction.d.ts.map +1 -0
  88. package/dist/internalTools/documentExtraction/documentExtraction.js +736 -0
  89. package/dist/internalTools/documentExtraction/documentExtraction.js.map +1 -0
  90. package/dist/internalTools/documentExtraction/types.d.ts +29 -0
  91. package/dist/internalTools/documentExtraction/types.d.ts.map +1 -0
  92. package/dist/internalTools/documentExtraction/types.js +35 -0
  93. package/dist/internalTools/documentExtraction/types.js.map +1 -0
  94. package/dist/internalTools/libraryActionRunnerTool.d.ts +4 -0
  95. package/dist/internalTools/libraryActionRunnerTool.d.ts.map +1 -0
  96. package/dist/internalTools/libraryActionRunnerTool.js +53 -0
  97. package/dist/internalTools/libraryActionRunnerTool.js.map +1 -0
  98. package/dist/internalTools/retell.d.ts +12 -0
  99. package/dist/internalTools/retell.d.ts.map +1 -0
  100. package/dist/internalTools/retell.js +54 -0
  101. package/dist/internalTools/retell.js.map +1 -0
  102. package/dist/internalTools/sendPlaceholderMessage.d.ts +14 -0
  103. package/dist/internalTools/sendPlaceholderMessage.d.ts.map +1 -0
  104. package/dist/internalTools/sendPlaceholderMessage.js +61 -0
  105. package/dist/internalTools/sendPlaceholderMessage.js.map +1 -0
  106. package/dist/internalTools/timer.d.ts +99 -0
  107. package/dist/internalTools/timer.d.ts.map +1 -0
  108. package/dist/internalTools/timer.js +139 -0
  109. package/dist/internalTools/timer.js.map +1 -0
  110. package/dist/internalTools/voice/escalateVoiceCall.d.ts +2 -0
  111. package/dist/internalTools/voice/escalateVoiceCall.d.ts.map +1 -0
  112. package/dist/internalTools/voice/escalateVoiceCall.js +52 -0
  113. package/dist/internalTools/voice/escalateVoiceCall.js.map +1 -0
  114. package/dist/internalTools/voice/retell.d.ts +12 -0
  115. package/dist/internalTools/voice/retell.d.ts.map +1 -0
  116. package/dist/internalTools/voice/retell.js +54 -0
  117. package/dist/internalTools/voice/retell.js.map +1 -0
  118. package/dist/internalTools/voice/sendPlaceholderMessage.d.ts +14 -0
  119. package/dist/internalTools/voice/sendPlaceholderMessage.d.ts.map +1 -0
  120. package/dist/internalTools/voice/sendPlaceholderMessage.js +61 -0
  121. package/dist/internalTools/voice/sendPlaceholderMessage.js.map +1 -0
  122. package/dist/interrupts/BaseInterruptSessionManager.d.ts +49 -0
  123. package/dist/interrupts/BaseInterruptSessionManager.d.ts.map +1 -0
  124. package/dist/interrupts/BaseInterruptSessionManager.js +34 -0
  125. package/dist/interrupts/BaseInterruptSessionManager.js.map +1 -0
  126. package/dist/interrupts/MemoryInterruptSessionManager.d.ts +14 -0
  127. package/dist/interrupts/MemoryInterruptSessionManager.d.ts.map +1 -0
  128. package/dist/interrupts/MemoryInterruptSessionManager.js +60 -0
  129. package/dist/interrupts/MemoryInterruptSessionManager.js.map +1 -0
  130. package/dist/interrupts/MindedInterruptSessionManager.d.ts +13 -0
  131. package/dist/interrupts/MindedInterruptSessionManager.d.ts.map +1 -0
  132. package/dist/interrupts/MindedInterruptSessionManager.js +162 -0
  133. package/dist/interrupts/MindedInterruptSessionManager.js.map +1 -0
  134. package/dist/interrupts/interruptSessionManagerFactory.d.ts +3 -0
  135. package/dist/interrupts/interruptSessionManagerFactory.d.ts.map +1 -0
  136. package/dist/interrupts/interruptSessionManagerFactory.js +56 -0
  137. package/dist/interrupts/interruptSessionManagerFactory.js.map +1 -0
  138. package/dist/llm/createLlmInstance.d.ts +3 -0
  139. package/dist/llm/createLlmInstance.d.ts.map +1 -0
  140. package/dist/llm/createLlmInstance.js +31 -0
  141. package/dist/llm/createLlmInstance.js.map +1 -0
  142. package/dist/nodes/addAppToolNode.d.ts +13 -0
  143. package/dist/nodes/addAppToolNode.d.ts.map +1 -0
  144. package/dist/nodes/addAppToolNode.js +87 -0
  145. package/dist/nodes/addAppToolNode.js.map +1 -0
  146. package/dist/nodes/addBrowserTaskNode.d.ts +13 -0
  147. package/dist/nodes/addBrowserTaskNode.d.ts.map +1 -0
  148. package/dist/nodes/addBrowserTaskNode.js +167 -0
  149. package/dist/nodes/addBrowserTaskNode.js.map +1 -0
  150. package/dist/nodes/addBrowserTaskRunNode.d.ts +13 -0
  151. package/dist/nodes/addBrowserTaskRunNode.d.ts.map +1 -0
  152. package/dist/nodes/addBrowserTaskRunNode.js +167 -0
  153. package/dist/nodes/addBrowserTaskRunNode.js.map +1 -0
  154. package/dist/nodes/addHumanInTheLoopNode.d.ts +9 -0
  155. package/dist/nodes/addHumanInTheLoopNode.d.ts.map +1 -0
  156. package/dist/nodes/addHumanInTheLoopNode.js +22 -0
  157. package/dist/nodes/addHumanInTheLoopNode.js.map +1 -0
  158. package/dist/nodes/addJumpToNode.d.ts +7 -0
  159. package/dist/nodes/addJumpToNode.d.ts.map +1 -0
  160. package/dist/nodes/addJumpToNode.js +24 -0
  161. package/dist/nodes/addJumpToNode.js.map +1 -0
  162. package/dist/nodes/addJunctionNode.d.ts +7 -0
  163. package/dist/nodes/addJunctionNode.d.ts.map +1 -0
  164. package/dist/nodes/addJunctionNode.js +20 -0
  165. package/dist/nodes/addJunctionNode.js.map +1 -0
  166. package/dist/nodes/addPromptNode.d.ts +18 -0
  167. package/dist/nodes/addPromptNode.d.ts.map +1 -0
  168. package/dist/nodes/addPromptNode.js +253 -0
  169. package/dist/nodes/addPromptNode.js.map +1 -0
  170. package/dist/nodes/addRpaNode.d.ts +18 -0
  171. package/dist/nodes/addRpaNode.d.ts.map +1 -0
  172. package/dist/nodes/addRpaNode.js +180 -0
  173. package/dist/nodes/addRpaNode.js.map +1 -0
  174. package/dist/nodes/addToolNode.d.ts +13 -0
  175. package/dist/nodes/addToolNode.d.ts.map +1 -0
  176. package/dist/nodes/addToolNode.js +67 -0
  177. package/dist/nodes/addToolNode.js.map +1 -0
  178. package/dist/nodes/addToolRunNode.d.ts +17 -0
  179. package/dist/nodes/addToolRunNode.d.ts.map +1 -0
  180. package/dist/nodes/addToolRunNode.js +59 -0
  181. package/dist/nodes/addToolRunNode.js.map +1 -0
  182. package/dist/nodes/addTriggerNode.d.ts +7 -0
  183. package/dist/nodes/addTriggerNode.d.ts.map +1 -0
  184. package/dist/nodes/addTriggerNode.js +25 -0
  185. package/dist/nodes/addTriggerNode.js.map +1 -0
  186. package/dist/nodes/compilePrompt.d.ts +5 -0
  187. package/dist/nodes/compilePrompt.d.ts.map +1 -0
  188. package/dist/nodes/compilePrompt.js +76 -0
  189. package/dist/nodes/compilePrompt.js.map +1 -0
  190. package/dist/nodes/nodeFactory.d.ts +16 -0
  191. package/dist/nodes/nodeFactory.d.ts.map +1 -0
  192. package/dist/nodes/nodeFactory.js +45 -0
  193. package/dist/nodes/nodeFactory.js.map +1 -0
  194. package/dist/nodes/rpaStepsExecutor.d.ts +5 -0
  195. package/dist/nodes/rpaStepsExecutor.d.ts.map +1 -0
  196. package/dist/nodes/rpaStepsExecutor.js +156 -0
  197. package/dist/nodes/rpaStepsExecutor.js.map +1 -0
  198. package/dist/platform/config.d.ts +16 -0
  199. package/dist/platform/config.d.ts.map +1 -0
  200. package/dist/platform/config.js +80 -0
  201. package/dist/platform/config.js.map +1 -0
  202. package/dist/platform/mindedCheckpointSaver.d.ts +10 -0
  203. package/dist/platform/mindedCheckpointSaver.d.ts.map +1 -0
  204. package/dist/platform/mindedCheckpointSaver.js +137 -0
  205. package/dist/platform/mindedCheckpointSaver.js.map +1 -0
  206. package/dist/platform/mindedConnection.d.ts +15 -0
  207. package/dist/platform/mindedConnection.d.ts.map +1 -0
  208. package/dist/platform/mindedConnection.js +254 -0
  209. package/dist/platform/mindedConnection.js.map +1 -0
  210. package/dist/platform/mindedConnectionTypes.d.ts +404 -0
  211. package/dist/platform/mindedConnectionTypes.d.ts.map +1 -0
  212. package/dist/platform/mindedConnectionTypes.js +51 -0
  213. package/dist/platform/mindedConnectionTypes.js.map +1 -0
  214. package/dist/platform/models/mindedChatOpenAI.d.ts +20 -0
  215. package/dist/platform/models/mindedChatOpenAI.d.ts.map +1 -0
  216. package/dist/platform/models/mindedChatOpenAI.js +32 -0
  217. package/dist/platform/models/mindedChatOpenAI.js.map +1 -0
  218. package/dist/platform/models/parallelWrapper.d.ts +17 -0
  219. package/dist/platform/models/parallelWrapper.d.ts.map +1 -0
  220. package/dist/platform/models/parallelWrapper.js +105 -0
  221. package/dist/platform/models/parallelWrapper.js.map +1 -0
  222. package/dist/platform/piiGateway/gateway.d.ts +14 -0
  223. package/dist/platform/piiGateway/gateway.d.ts.map +1 -0
  224. package/dist/platform/piiGateway/gateway.js +117 -0
  225. package/dist/platform/piiGateway/gateway.js.map +1 -0
  226. package/dist/platform/piiGateway/index.d.ts +3 -0
  227. package/dist/platform/piiGateway/index.d.ts.map +1 -0
  228. package/dist/platform/piiGateway/index.js +7 -0
  229. package/dist/platform/piiGateway/index.js.map +1 -0
  230. package/dist/platform/piiGateway/types.d.ts +27 -0
  231. package/dist/platform/piiGateway/types.d.ts.map +1 -0
  232. package/dist/platform/piiGateway/types.js +3 -0
  233. package/dist/platform/piiGateway/types.js.map +1 -0
  234. package/dist/platform/toolExecutor.d.ts +29 -0
  235. package/dist/platform/toolExecutor.d.ts.map +1 -0
  236. package/dist/platform/toolExecutor.js +84 -0
  237. package/dist/platform/toolExecutor.js.map +1 -0
  238. package/dist/platform/utils/parseAttachments.d.ts +14 -0
  239. package/dist/platform/utils/parseAttachments.d.ts.map +1 -0
  240. package/dist/platform/utils/parseAttachments.js +53 -0
  241. package/dist/platform/utils/parseAttachments.js.map +1 -0
  242. package/dist/platform/utils/tools.d.ts +6 -0
  243. package/dist/platform/utils/tools.d.ts.map +1 -0
  244. package/dist/platform/utils/tools.js +57 -0
  245. package/dist/platform/utils/tools.js.map +1 -0
  246. package/dist/playbooks/playbooks.d.ts +15 -0
  247. package/dist/playbooks/playbooks.d.ts.map +1 -0
  248. package/dist/playbooks/playbooks.js +208 -0
  249. package/dist/playbooks/playbooks.js.map +1 -0
  250. package/dist/toolsLibrary/classifier.d.ts +74 -0
  251. package/dist/toolsLibrary/classifier.d.ts.map +1 -0
  252. package/dist/toolsLibrary/classifier.js +256 -0
  253. package/dist/toolsLibrary/classifier.js.map +1 -0
  254. package/dist/toolsLibrary/extraction.d.ts +83 -0
  255. package/dist/toolsLibrary/extraction.d.ts.map +1 -0
  256. package/dist/toolsLibrary/extraction.js +328 -0
  257. package/dist/toolsLibrary/extraction.js.map +1 -0
  258. package/dist/toolsLibrary/index.d.ts +9 -0
  259. package/dist/toolsLibrary/index.d.ts.map +1 -0
  260. package/dist/toolsLibrary/index.js +46 -0
  261. package/dist/toolsLibrary/index.js.map +1 -0
  262. package/dist/toolsLibrary/parseDocument.d.ts +30 -0
  263. package/dist/toolsLibrary/parseDocument.d.ts.map +1 -0
  264. package/dist/toolsLibrary/parseDocument.js +119 -0
  265. package/dist/toolsLibrary/parseDocument.js.map +1 -0
  266. package/dist/triggers/triggerTypeToDefaultMessage.d.ts +4 -0
  267. package/dist/triggers/triggerTypeToDefaultMessage.d.ts.map +1 -0
  268. package/dist/triggers/triggerTypeToDefaultMessage.js +10 -0
  269. package/dist/triggers/triggerTypeToDefaultMessage.js.map +1 -0
  270. package/dist/types/Agent.types.d.ts +60 -0
  271. package/dist/types/Agent.types.d.ts.map +1 -0
  272. package/dist/types/Agent.types.js +9 -0
  273. package/dist/types/Agent.types.js.map +1 -0
  274. package/dist/types/Flows.types.d.ts +232 -0
  275. package/dist/types/Flows.types.d.ts.map +1 -0
  276. package/dist/types/Flows.types.js +65 -0
  277. package/dist/types/Flows.types.js.map +1 -0
  278. package/dist/types/LLM.types.d.ts +7 -0
  279. package/dist/types/LLM.types.d.ts.map +1 -0
  280. package/dist/types/LLM.types.js +11 -0
  281. package/dist/types/LLM.types.js.map +1 -0
  282. package/dist/types/LangGraph.types.d.ts +45 -0
  283. package/dist/types/LangGraph.types.d.ts.map +1 -0
  284. package/dist/types/LangGraph.types.js +77 -0
  285. package/dist/types/LangGraph.types.js.map +1 -0
  286. package/dist/types/Platform.types.d.ts +7 -0
  287. package/dist/types/Platform.types.d.ts.map +1 -0
  288. package/dist/types/Platform.types.js +11 -0
  289. package/dist/types/Platform.types.js.map +1 -0
  290. package/dist/types/Tools.types.d.ts +26 -0
  291. package/dist/types/Tools.types.d.ts.map +1 -0
  292. package/dist/types/Tools.types.js +3 -0
  293. package/dist/types/Tools.types.js.map +1 -0
  294. package/dist/types/Voice.types.d.ts +5 -0
  295. package/dist/types/Voice.types.d.ts.map +1 -0
  296. package/dist/types/Voice.types.js +3 -0
  297. package/dist/types/Voice.types.js.map +1 -0
  298. package/dist/utils/agentUtils.d.ts +5 -0
  299. package/dist/utils/agentUtils.d.ts.map +1 -0
  300. package/dist/utils/agentUtils.js +97 -0
  301. package/dist/utils/agentUtils.js.map +1 -0
  302. package/dist/utils/extractStateMemoryResponse.d.ts +5 -0
  303. package/dist/utils/extractStateMemoryResponse.d.ts.map +1 -0
  304. package/dist/utils/extractStateMemoryResponse.js +91 -0
  305. package/dist/utils/extractStateMemoryResponse.js.map +1 -0
  306. package/dist/utils/history.d.ts +4 -0
  307. package/dist/utils/history.d.ts.map +1 -0
  308. package/dist/utils/history.js +33 -0
  309. package/dist/utils/history.js.map +1 -0
  310. package/dist/utils/logger.d.ts +3 -0
  311. package/dist/utils/logger.d.ts.map +1 -0
  312. package/dist/utils/logger.js +39 -0
  313. package/dist/utils/logger.js.map +1 -0
  314. package/dist/utils/schemaUtils.d.ts +15 -0
  315. package/dist/utils/schemaUtils.d.ts.map +1 -0
  316. package/dist/utils/schemaUtils.js +56 -0
  317. package/dist/utils/schemaUtils.js.map +1 -0
  318. package/dist/utils/wait.d.ts +2 -0
  319. package/dist/utils/wait.d.ts.map +1 -0
  320. package/dist/utils/wait.js +6 -0
  321. package/dist/utils/wait.js.map +1 -0
  322. package/dist/voice/elevenLabsUtils.d.ts +65 -0
  323. package/dist/voice/elevenLabsUtils.d.ts.map +1 -0
  324. package/dist/voice/elevenLabsUtils.js +4 -0
  325. package/dist/voice/elevenLabsUtils.js.map +1 -0
  326. package/dist/voice/voiceSession.d.ts +37 -0
  327. package/dist/voice/voiceSession.d.ts.map +1 -0
  328. package/dist/voice/voiceSession.js +306 -0
  329. package/dist/voice/voiceSession.js.map +1 -0
  330. package/docs/.gitbook/assets/ADLC.png +0 -0
  331. package/docs/.gitbook/assets/PII-masking.png +0 -0
  332. package/docs/.gitbook/assets/image.png +0 -0
  333. package/docs/.gitbook/assets/on-prem.svg +4 -0
  334. package/docs/README.md +54 -0
  335. package/docs/SUMMARY.md +56 -0
  336. package/docs/examples/order-refund-flow.md +566 -0
  337. package/docs/getting-started/environment-configuration.md +158 -0
  338. package/docs/getting-started/installation.md +44 -0
  339. package/docs/getting-started/project-configuration.md +206 -0
  340. package/docs/getting-started/quick-start.md +262 -0
  341. package/docs/integrations/zendesk.md +554 -0
  342. package/docs/low-code-editor/edges.md +396 -0
  343. package/docs/low-code-editor/flows.md +74 -0
  344. package/docs/low-code-editor/nodes.md +367 -0
  345. package/docs/low-code-editor/playbooks.md +280 -0
  346. package/docs/low-code-editor/tools.md +358 -0
  347. package/docs/low-code-editor/triggers.md +182 -0
  348. package/docs/platform/on-prem.md +182 -0
  349. package/docs/platform/operator.md +89 -0
  350. package/docs/platform/pii-masking.md +221 -0
  351. package/docs/platform/scenarios.md +43 -0
  352. package/docs/platform/secrets.md +99 -0
  353. package/docs/platform/sso.md +27 -0
  354. package/docs/resources/your-first-eval.md +108 -0
  355. package/docs/sdk/agent-api.md +540 -0
  356. package/docs/sdk/debugging.md +80 -0
  357. package/docs/sdk/events.md +595 -0
  358. package/docs/sdk/logging.md +72 -0
  359. package/docs/sdk/memory.md +271 -0
  360. package/docs/sdk/parallel-llm.md +242 -0
  361. package/docs/sdk/vectorstore-query.md +60 -0
  362. package/docs/tooling/classifier.md +217 -0
  363. package/docs/tooling/document-processing.md +389 -0
  364. package/docs/tooling/extraction.md +78 -0
  365. package/docs/tooling/timers.md +61 -0
  366. package/package.json +73 -0
  367. package/src/agent.ts +1019 -0
  368. package/src/browserTask/executeBrowserTask.py +153 -0
  369. package/src/browserTask/executeBrowserTask.ts +253 -0
  370. package/src/browserTask/localBrowserTask.ts +300 -0
  371. package/src/browserTask/profile/Default/Extension Rules/000003.log +0 -0
  372. package/src/browserTask/profile/Default/Extension Scripts/000003.log +0 -0
  373. package/src/browserTask/profile/Default/Extension State/000003.log +0 -0
  374. package/src/browserTask/profile/Default/GCM Store/000003.log +0 -0
  375. package/src/browserTask/profile/Default/Local Storage/leveldb/000004.log +0 -0
  376. package/src/browserTask/profile/Default/Session Storage/000003.log +0 -0
  377. package/src/browserTask/profile/Default/Site Characteristics Database/000003.log +0 -0
  378. package/src/browserTask/profile/Default/Sync Data/LevelDB/000003.log +0 -0
  379. package/src/browserTask/profile/Default/shared_proto_db/000003.log +0 -0
  380. package/src/browserTask/profile/Default/shared_proto_db/metadata/000003.log +0 -0
  381. package/src/browserTask/types.ts +37 -0
  382. package/src/checkpointer/checkpointSaverFactory.ts +18 -0
  383. package/src/cli/index.ts +188 -0
  384. package/src/cli/lambdaHandlerTemplate.ts +78 -0
  385. package/src/cli/localOperatorSetup.ts +308 -0
  386. package/src/debugging/index.ts +1 -0
  387. package/src/debugging/llmCallbackHandler.ts +125 -0
  388. package/src/edges/createDirectEdge.ts +22 -0
  389. package/src/edges/createLogicalRouter.ts +182 -0
  390. package/src/edges/createPromptRouter.ts +213 -0
  391. package/src/edges/edgeFactory.ts +167 -0
  392. package/src/events/AgentEvents.ts +58 -0
  393. package/src/events/index.ts +3 -0
  394. package/src/index.ts +105 -0
  395. package/src/interfaces/zendesk.ts +212 -0
  396. package/src/internalTools/appActionRunnerTool.ts +68 -0
  397. package/src/internalTools/documentExtraction/documentExtraction.ts +804 -0
  398. package/src/internalTools/documentExtraction/types.ts +59 -0
  399. package/src/internalTools/libraryActionRunnerTool.ts +62 -0
  400. package/src/internalTools/timer.ts +125 -0
  401. package/src/internalTools/voice/escalateVoiceCall.ts +15 -0
  402. package/src/internalTools/voice/retell.ts +28 -0
  403. package/src/internalTools/voice/sendPlaceholderMessage.ts +27 -0
  404. package/src/interrupts/BaseInterruptSessionManager.ts +80 -0
  405. package/src/interrupts/MemoryInterruptSessionManager.ts +63 -0
  406. package/src/interrupts/MindedInterruptSessionManager.ts +163 -0
  407. package/src/interrupts/interruptSessionManagerFactory.ts +20 -0
  408. package/src/llm/createLlmInstance.ts +33 -0
  409. package/src/nodes/addAppToolNode.ts +111 -0
  410. package/src/nodes/addBrowserTaskNode.ts +191 -0
  411. package/src/nodes/addBrowserTaskRunNode.ts +190 -0
  412. package/src/nodes/addHumanInTheLoopNode.ts +26 -0
  413. package/src/nodes/addJumpToNode.ts +26 -0
  414. package/src/nodes/addJunctionNode.ts +21 -0
  415. package/src/nodes/addPromptNode.ts +305 -0
  416. package/src/nodes/addRpaNode.ts +217 -0
  417. package/src/nodes/addToolNode.ts +84 -0
  418. package/src/nodes/addToolRunNode.ts +80 -0
  419. package/src/nodes/addTriggerNode.ts +27 -0
  420. package/src/nodes/compilePrompt.ts +44 -0
  421. package/src/nodes/nodeFactory.ts +61 -0
  422. package/src/nodes/rpaStepsExecutor.ts +175 -0
  423. package/src/platform/config.ts +89 -0
  424. package/src/platform/mindedCheckpointSaver.ts +146 -0
  425. package/src/platform/mindedConnection.ts +250 -0
  426. package/src/platform/mindedConnectionTypes.ts +495 -0
  427. package/src/platform/models/mindedChatOpenAI.ts +49 -0
  428. package/src/platform/models/parallelWrapper.ts +141 -0
  429. package/src/platform/piiGateway/gateway.ts +103 -0
  430. package/src/platform/piiGateway/index.ts +5 -0
  431. package/src/platform/piiGateway/types.ts +29 -0
  432. package/src/platform/toolExecutor.ts +106 -0
  433. package/src/platform/utils/parseAttachments.ts +56 -0
  434. package/src/platform/utils/tools.ts +55 -0
  435. package/src/playbooks/playbooks.ts +200 -0
  436. package/src/toolsLibrary/classifier.ts +326 -0
  437. package/src/toolsLibrary/extraction.ts +393 -0
  438. package/src/toolsLibrary/index.ts +10 -0
  439. package/src/toolsLibrary/parseDocument.ts +129 -0
  440. package/src/triggers/triggerTypeToDefaultMessage.ts +9 -0
  441. package/src/types/Agent.types.ts +73 -0
  442. package/src/types/Flows.types.ts +262 -0
  443. package/src/types/LLM.types.ts +15 -0
  444. package/src/types/LangGraph.types.ts +86 -0
  445. package/src/types/Platform.types.ts +6 -0
  446. package/src/types/Tools.types.ts +28 -0
  447. package/src/types/Voice.types.ts +4 -0
  448. package/src/utils/agentUtils.ts +69 -0
  449. package/src/utils/history.ts +38 -0
  450. package/src/utils/logger.ts +38 -0
  451. package/src/utils/schemaUtils.ts +68 -0
  452. package/src/utils/wait.ts +1 -0
  453. package/src/voice/elevenLabsUtils.ts +81 -0
  454. package/src/voice/voiceSession.ts +309 -0
@@ -0,0 +1,153 @@
1
+ import asyncio
2
+ import json
3
+ from typing import List, Optional, Dict, Any, TypedDict
4
+ from pydantic import BaseModel, create_model, Field
5
+ from browser_use import Agent, Controller, ActionResult
6
+ from browser_use.browser import BrowserProfile, BrowserSession
7
+ from browser_use.llm import ChatOpenAI
8
+ import os
9
+ import sys
10
+ from dotenv import load_dotenv
11
+
12
+ load_dotenv()
13
+
14
+ class OutputSchemaItemRequired(TypedDict):
15
+ name: str
16
+ type: str # 'string' | 'number'
17
+
18
+ class OutputSchemaItem(OutputSchemaItemRequired, total=False):
19
+ description: str
20
+ required: bool
21
+
22
+
23
+ def create_pydantic_model_from_schema(output_schema: Optional[List[Dict[str, Any]]]) -> Optional[type[BaseModel]]:
24
+ if not output_schema:
25
+ return None
26
+
27
+ field_definitions: Dict[str, Any] = {}
28
+ for item in output_schema:
29
+ type_mapping = {
30
+ 'string': str,
31
+ 'number': float,
32
+ }
33
+ field_type = type_mapping.get(item.get('type'), str)
34
+ description = item.get('description', '')
35
+ is_required = item.get('required', True)
36
+ if is_required:
37
+ field_definitions[item['name']] = (field_type, Field(description=description))
38
+ else:
39
+ field_definitions[item['name']] = (Optional[field_type], Field(default=None, description=description))
40
+
41
+ if field_definitions:
42
+ return create_model('DynamicOutputModel', **field_definitions)
43
+ return None
44
+
45
+
46
+ async def main(session_id: str, cdp_url: str, task: str, output_schema_json: Optional[str] = None, otp_secret: Optional[str] = None):
47
+ llm = ChatOpenAI(
48
+ model="gpt-4.1",
49
+ api_key=os.getenv("OPENAI_API_KEY"),
50
+ )
51
+ folder_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), f'downloads_{session_id}')
52
+
53
+ # Create folder if it doesn't exist
54
+ os.makedirs(folder_path, exist_ok=True)
55
+
56
+ available_files = [os.path.join(folder_path, file) for file in os.listdir(folder_path)]
57
+
58
+ # Set downloads_path to the local tools/files directory
59
+ browser_session = BrowserSession(
60
+ browser_profile=BrowserProfile(downloads_path=folder_path),
61
+ cdp_url=cdp_url
62
+ )
63
+
64
+ output_schema = None
65
+ if output_schema_json:
66
+ try:
67
+ output_schema = json.loads(output_schema_json)
68
+ except Exception:
69
+ output_schema = None
70
+
71
+ output_model = create_pydantic_model_from_schema(output_schema)
72
+
73
+ # Build controller and register dynamic tools
74
+ controller = Controller(output_model=output_model) if output_model is not None else Controller()
75
+
76
+ # Dynamically add generate_otp action when OTP secret is provided
77
+
78
+ if otp_secret:
79
+ # Ensure pyotp is available when OTP is requested
80
+ try:
81
+ import pyotp # type: ignore
82
+ except Exception as e:
83
+ raise RuntimeError("pyotp is required when otpSecret is provided. Install it with 'uv add pyotp'.") from e
84
+
85
+ @controller.registry.action("Generate a 6-digit TOTP code. Do not call any other tool at the same time.")
86
+ async def generate_otp() -> ActionResult:
87
+ try:
88
+ code = pyotp.TOTP(otp_secret).now()
89
+ print(f"Generated OTP: {code}")
90
+ return ActionResult(extracted_content=code)
91
+ except Exception as e:
92
+ print(f"Failed to generate OTP: {e}")
93
+ return ActionResult(extracted_content=f"Failed to generate OTP: {e}")
94
+
95
+ agent = Agent(
96
+ task=task,
97
+ llm=llm,
98
+ controller=controller,
99
+ available_file_paths=available_files,
100
+ browser_session=browser_session,
101
+ )
102
+ history = await agent.run()
103
+ final_result = history.final_result()
104
+
105
+ # Parse result with output model if provided
106
+ parsed_result = None
107
+ if output_model and final_result:
108
+ try:
109
+ # Validate and parse the result using the Pydantic model
110
+ parsed_result = output_model.model_validate_json(final_result)
111
+ # Convert to dict for JSON serialization
112
+ parsed_result = parsed_result.model_dump()
113
+ except Exception as e:
114
+ print(f"Failed to parse result with output model: {e}")
115
+ # Fall back to raw result
116
+ parsed_result = final_result
117
+ else:
118
+ parsed_result = final_result
119
+
120
+ print("___RESULT___")
121
+ if parsed_result:
122
+ print(json.dumps(parsed_result, indent=2))
123
+ else:
124
+ print(final_result)
125
+
126
+ if __name__ == '__main__':
127
+ # Prefer JSON payload via stdin; fallback to argv for backwards compatibility
128
+ payload_str = ''
129
+ try:
130
+ if not sys.stdin.isatty():
131
+ payload_str = sys.stdin.read().strip()
132
+ except Exception:
133
+ payload_str = ''
134
+
135
+ if payload_str:
136
+ try:
137
+ payload = json.loads(payload_str)
138
+ except Exception as e:
139
+ raise SystemExit(f"Failed to parse JSON payload from stdin: {e}")
140
+
141
+ session_id = payload.get('sessionId')
142
+ cdp_url = payload.get('cdpUrl')
143
+ task = payload.get('task')
144
+ output_schema = payload.get('outputSchema')
145
+ otp_secret = payload.get('otpSecret')
146
+
147
+ if not session_id or not cdp_url or not task:
148
+ raise SystemExit("Missing required fields in JSON payload: sessionId, cdpUrl, task")
149
+
150
+ output_schema_json = json.dumps(output_schema) if output_schema is not None else None
151
+ asyncio.run(main(session_id, cdp_url, task, output_schema_json, otp_secret))
152
+ else:
153
+ raise SystemExit("Usage: uv run executeBrowserTask.py; send a JSON payload via stdin")
@@ -0,0 +1,253 @@
1
+ import { spawn } from 'node:child_process';
2
+ import { logger } from '../utils/logger';
3
+ import { mindedConnection } from '../platform/mindedConnection';
4
+ import path from 'path';
5
+ import {
6
+ mindedConnectionSocketMessageType,
7
+ CreateBrowserSessionResponse,
8
+ InvokeBrowserTaskResponse,
9
+ CreateBrowserSessionRequest,
10
+ InvokeBrowserTaskRequest,
11
+ DestroyBrowserSessionRequest,
12
+ DestroyBrowserSessionResponse,
13
+ } from '../platform/mindedConnectionTypes';
14
+ import { kill, getOrStartLocalCDP, isLocalBrowserRunning } from './localBrowserTask';
15
+ import { BrowserTaskMode, InvokeBrowserTaskOptions } from './types';
16
+ import { isLocalOperatorSetup, validateLocalOperatorSetup } from '../cli/localOperatorSetup';
17
+
18
+ // Map to track sessionId to instanceId for local browser sessions
19
+ const localSessionInstances = new Map<string, string>();
20
+
21
+ // Socket-based browser task functions
22
+ export const createBrowserSession = async ({
23
+ sessionId,
24
+ proxy,
25
+ browserTaskMode,
26
+ }: {
27
+ sessionId: string;
28
+ proxy?: string;
29
+ browserTaskMode: BrowserTaskMode;
30
+ }): Promise<CreateBrowserSessionResponse> => {
31
+ logger.debug({ msg: 'Creating browser session via socket', proxy });
32
+
33
+ if (browserTaskMode === BrowserTaskMode.LOCAL) {
34
+ const { cdpUrl, instanceId } = await getOrStartLocalCDP({ headless: false });
35
+
36
+ // Store the mapping for cleanup later
37
+ localSessionInstances.set(sessionId, instanceId);
38
+
39
+ return {
40
+ sessionId,
41
+ cdpUrl,
42
+ };
43
+ }
44
+
45
+ const response = await mindedConnection.awaitEmit<CreateBrowserSessionRequest, CreateBrowserSessionResponse>(
46
+ mindedConnectionSocketMessageType.CREATE_BROWSER_SESSION,
47
+ {
48
+ type: mindedConnectionSocketMessageType.CREATE_BROWSER_SESSION,
49
+ proxy,
50
+ onPrem: browserTaskMode === BrowserTaskMode.ON_PREM,
51
+ },
52
+ 60000, // 60 seconds timeout
53
+ );
54
+
55
+ if (response.error) {
56
+ logger.error({ msg: 'Failed to create browser session', error: response.error });
57
+ throw new Error(response.error);
58
+ }
59
+
60
+ logger.debug({
61
+ msg: 'Browser session created successfully',
62
+ sessionId: response.sessionId,
63
+ hasLiveUrl: !!response.liveViewUrl,
64
+ });
65
+
66
+ return response;
67
+ };
68
+
69
+ export const destroyBrowserSession = async ({
70
+ sessionId,
71
+ onPrem,
72
+ localRun,
73
+ }: {
74
+ sessionId: string;
75
+ onPrem?: boolean;
76
+ localRun?: boolean;
77
+ }): Promise<DestroyBrowserSessionResponse> => {
78
+ logger.debug({ msg: 'Destroying browser session via socket', sessionId, onPrem });
79
+
80
+ if (localRun || process.env.BROWSER_TASK_MODE === BrowserTaskMode.LOCAL) {
81
+ // Kill specific instance if we have the mapping
82
+ const instanceId = localSessionInstances.get(sessionId);
83
+ if (instanceId) {
84
+ await kill(instanceId);
85
+ localSessionInstances.delete(sessionId);
86
+ } else {
87
+ // Fallback to killing all if no specific instance found
88
+ logger.warn({ msg: 'No instance ID found for session, killing all instances', sessionId });
89
+ await kill();
90
+ }
91
+ return {
92
+ success: true,
93
+ };
94
+ }
95
+
96
+ const response = await mindedConnection.awaitEmit<DestroyBrowserSessionRequest, DestroyBrowserSessionResponse>(
97
+ mindedConnectionSocketMessageType.DESTROY_BROWSER_SESSION,
98
+ {
99
+ type: mindedConnectionSocketMessageType.DESTROY_BROWSER_SESSION,
100
+ sessionId,
101
+ onPrem,
102
+ },
103
+ 30000,
104
+ );
105
+
106
+ if (response.error) {
107
+ logger.error({ msg: 'Failed to destroy browser session', error: response.error, sessionId });
108
+ throw new Error(response.error);
109
+ }
110
+
111
+ logger.debug({ msg: 'Browser session destroyed successfully', sessionId });
112
+ return response;
113
+ };
114
+
115
+ export const invokeBrowserTask = async (options: InvokeBrowserTaskOptions): Promise<InvokeBrowserTaskResponse> => {
116
+ try {
117
+ const { sessionId, cdpUrl, task, keepAlive, hooks, browserTaskMode, toolSchemas, outputSchema } = options;
118
+
119
+ if (browserTaskMode === BrowserTaskMode.LOCAL) {
120
+ validateLocalOperatorSetup();
121
+ const pythonScriptPath = path.resolve(__dirname, 'executeBrowserTask.py');
122
+
123
+ const args = ['run', pythonScriptPath];
124
+ logger.info({ message: 'Spawning Python process', args });
125
+
126
+ const child = spawn('uv', args, {
127
+ stdio: ['pipe', 'pipe', 'pipe'],
128
+ env: isLocalOperatorSetup()
129
+ ? {
130
+ ...process.env,
131
+ VIRTUAL_ENV: path.join(process.cwd(), '.venv'),
132
+ PATH: `${path.join(process.cwd(), '.venv', 'bin')}:${process.env.PATH}`,
133
+ }
134
+ : process.env,
135
+ });
136
+
137
+ // Build payload to send over stdin
138
+ const payload = {
139
+ sessionId,
140
+ cdpUrl,
141
+ task,
142
+ outputSchema,
143
+ otpSecret: process.env.OTP_SECRET,
144
+ };
145
+
146
+ // Write JSON payload to stdin
147
+ child.stdin.write(JSON.stringify(payload));
148
+ child.stdin.end();
149
+
150
+ let stdoutBuffer = '';
151
+ let stderrBuffer = '';
152
+
153
+ child.stdout.on('data', (data) => {
154
+ const text = data.toString();
155
+ stdoutBuffer += text;
156
+ process.stdout.write(text);
157
+ });
158
+
159
+ child.stderr.on('data', (data) => {
160
+ const text = data.toString();
161
+ stderrBuffer += text;
162
+ process.stderr.write(text);
163
+ });
164
+
165
+ const interval = setInterval(() => {
166
+ // Check if chromium process stopped running
167
+ if (!isLocalBrowserRunning()) {
168
+ logger.error({ message: 'Local browser process stopped running, killing browser task' });
169
+ child.kill();
170
+ clearInterval(interval);
171
+ }
172
+ }, 1000);
173
+
174
+ // Automatically clear interval after 20 minutes to avoid memory leaks
175
+ setTimeout(() => {
176
+ clearInterval(interval);
177
+ }, 1200000); // 20 minutes
178
+
179
+ const exitCode: number = await new Promise((resolve, reject) => {
180
+ child.on('error', (err) => reject(err));
181
+ child.on('close', (code) => resolve(code ?? 1));
182
+ });
183
+
184
+ clearInterval(interval);
185
+
186
+ if (exitCode !== 0) {
187
+ logger.error({ message: 'Operator failed', exitCode, stderr: stderrBuffer });
188
+ throw new Error(`Local browser task failed with exit code ${exitCode}`);
189
+ }
190
+
191
+ logger.info({ message: 'Operator finished' });
192
+
193
+ let result = stdoutBuffer.split('___RESULT___')[1]?.trim() || stdoutBuffer;
194
+ if (outputSchema?.length) {
195
+ try {
196
+ result = JSON.parse(result);
197
+ } catch (error) {
198
+ logger.debug({ message: 'Failed to parse result', error });
199
+ }
200
+ }
201
+
202
+ return {
203
+ result,
204
+ steps: [],
205
+ recordings: [],
206
+ };
207
+ }
208
+
209
+ logger.debug({
210
+ msg: 'Invoking browser task via socket',
211
+ sessionId,
212
+ taskLength: task.length,
213
+ keepAlive,
214
+ hooksCount: hooks?.length || 0,
215
+ onPrem: browserTaskMode === BrowserTaskMode.ON_PREM,
216
+ outputSchemaFields: outputSchema?.length || 0,
217
+ });
218
+
219
+ const response = await mindedConnection.awaitEmit<InvokeBrowserTaskRequest, InvokeBrowserTaskResponse>(
220
+ mindedConnectionSocketMessageType.INVOKE_BROWSER_TASK,
221
+ {
222
+ type: mindedConnectionSocketMessageType.INVOKE_BROWSER_TASK,
223
+ cdpUrl,
224
+ task,
225
+ sessionId,
226
+ keepAlive,
227
+ hooks,
228
+ onPrem: browserTaskMode === BrowserTaskMode.ON_PREM,
229
+ toolSchemas,
230
+ outputSchema,
231
+ },
232
+ 900000, // 15 minutes timeout
233
+ );
234
+
235
+ if (response.error) {
236
+ logger.error({ msg: 'Failed to invoke browser task', error: response.error });
237
+ throw new Error(response.error);
238
+ }
239
+
240
+ logger.debug({
241
+ msg: 'Browser task completed successfully',
242
+ sessionId,
243
+ hasResult: !!response.result,
244
+ stepCount: response.steps?.length || 0,
245
+ recordingCount: response.recordings?.length || 0,
246
+ });
247
+
248
+ return response;
249
+ } catch (err) {
250
+ logger.error({ message: 'Error invoking browser task', err });
251
+ throw err;
252
+ }
253
+ };
@@ -0,0 +1,300 @@
1
+ // getOrStartLocalCDP.ts
2
+ import { spawn, ChildProcess } from 'child_process';
3
+ import * as fs from 'fs/promises';
4
+ import * as path from 'path';
5
+ import { chromium } from 'playwright';
6
+ import { logger } from '../utils/logger';
7
+ import { wait } from '../utils/wait';
8
+ import * as net from 'net';
9
+
10
+ interface BrowserInstance {
11
+ id: string;
12
+ cdpUrl: string;
13
+ proc: ChildProcess;
14
+ port: number;
15
+ profileDir?: string;
16
+ }
17
+
18
+ // Map to track multiple browser instances
19
+ const browserInstances = new Map<string, BrowserInstance>();
20
+
21
+ // Port range for Chrome instances
22
+ const MIN_PORT = 9222;
23
+ const MAX_PORT = 9322; // Allow up to 100 concurrent instances
24
+
25
+ /**
26
+ * Find an available port in the specified range
27
+ */
28
+ async function findAvailablePort(startPort: number = MIN_PORT, endPort: number = MAX_PORT): Promise<number> {
29
+ // First check if any ports are already in use by our instances
30
+ const usedPorts = new Set(Array.from(browserInstances.values()).map((instance) => instance.port));
31
+
32
+ for (let port = startPort; port <= endPort; port++) {
33
+ if (usedPorts.has(port)) {
34
+ continue;
35
+ }
36
+
37
+ const isAvailable = await checkPortAvailable(port);
38
+ if (isAvailable) {
39
+ return port;
40
+ }
41
+ }
42
+
43
+ throw new Error(`No available ports found in range ${startPort}-${endPort}`);
44
+ }
45
+
46
+ /**
47
+ * Check if a port is available
48
+ */
49
+ function checkPortAvailable(port: number): Promise<boolean> {
50
+ return new Promise((resolve) => {
51
+ const server = net.createServer();
52
+
53
+ server.once('error', () => {
54
+ resolve(false);
55
+ });
56
+
57
+ server.once('listening', () => {
58
+ server.close();
59
+ resolve(true);
60
+ });
61
+
62
+ server.listen(port);
63
+ });
64
+ }
65
+
66
+ export type StartChromiumOptions = {
67
+ /** Headless by default. Set to false to see a window. */
68
+ headless?: boolean;
69
+ /** Extra CLI flags to pass to Chromium. */
70
+ extraArgs?: string[];
71
+ /** Provide your own user-data-dir. If omitted, a temp dir is created and later removable via `kill()`. */
72
+ userDataDir?: string;
73
+ /** Extra env vars. */
74
+ env?: NodeJS.ProcessEnv;
75
+ /** How long to wait for the DevTools port to come up (ms). Default: 10000 */
76
+ timeoutMs?: number;
77
+ /** Instance ID to reuse an existing browser instance. If not provided, a new instance will be created. */
78
+ instanceId?: string;
79
+ /** Preferred port to use. If not available, will find another available port. */
80
+ preferredPort?: number;
81
+ };
82
+
83
+ /**
84
+ * Launch Chromium with dynamic port allocation and return the CDP ws URL.
85
+ * Supports multiple concurrent instances.
86
+ * Works with Chrome/Chromium/Chrome for Testing.
87
+ */
88
+ export async function getOrStartLocalCDP(opts: StartChromiumOptions): Promise<{ cdpUrl: string; instanceId: string }> {
89
+ // If instanceId is provided, try to reuse existing instance
90
+ if (opts.instanceId && browserInstances.has(opts.instanceId)) {
91
+ const instance = browserInstances.get(opts.instanceId)!;
92
+ return {
93
+ cdpUrl: instance.cdpUrl,
94
+ instanceId: instance.id,
95
+ };
96
+ }
97
+
98
+ // Generate a new instance ID if not provided
99
+ const instanceId = opts.instanceId || `browser-${Date.now()}-${Math.random().toString(36).substring(7)}`;
100
+
101
+ const { env } = opts;
102
+
103
+ const executablePath = chromium.executablePath();
104
+
105
+ // Find an available port
106
+ const port = opts.preferredPort
107
+ ? (await checkPortAvailable(opts.preferredPort))
108
+ ? opts.preferredPort
109
+ : await findAvailablePort()
110
+ : await findAvailablePort();
111
+
112
+ logger.info({ message: `Starting Chrome instance on port ${port}`, instanceId });
113
+
114
+ const profileDir = path.join(__dirname, `profile-${instanceId}`);
115
+ await fs.mkdir(profileDir, { recursive: true });
116
+
117
+ const userDataDir = opts.userDataDir ?? profileDir;
118
+
119
+ const args = [
120
+ '--new-window',
121
+ `--user-data-dir=${userDataDir}`,
122
+ ...(process.env.HEADLESS === 'true' ? ['--headless'] : []),
123
+ '--disable-component-extensions-with-background-pages',
124
+ '--disable-background-networking',
125
+ '--disable-back-forward-cache',
126
+ '--disable-popup-blocking',
127
+ '--simulate-outdated-no-au="Tue, 31 Dec 2099 23:59:59 GMT"',
128
+ '--disable-renderer-backgrounding',
129
+ '--no-sandbox',
130
+ '--no-service-autorun',
131
+ '--disable-background-timer-throttling',
132
+ '--allow-legacy-extension-manifests',
133
+ '--allow-pre-commit-input',
134
+ '--log-level=2',
135
+ '--unsafely-disable-devtools-self-xss-warnings',
136
+ '--metrics-recording-only',
137
+ '--disable-window-activation',
138
+ '--disable-dev-shm-usage',
139
+ '--disable-backgrounding-occluded-windows',
140
+ '--disable-search-engine-choice-screen',
141
+ '--disable-print-preview',
142
+ '--disable-external-intent-requests',
143
+ '--disable-desktop-notifications',
144
+ '--disable-component-update',
145
+ '--generate-pdf-document-outline',
146
+ '--disable-focus-on-load',
147
+ '--disable-speech-api',
148
+ '--silent-debugger-extension-api',
149
+ '--suppress-message-center-popups',
150
+ '--disable-default-apps',
151
+ '--enable-network-information-downlink-max',
152
+ '--use-mock-keychain',
153
+ '--disable-ipc-flooding-protection',
154
+ '--safebrowsing-disable-auto-update',
155
+ '--install-autogenerated-theme=0,0,0',
156
+ '--disable-blink-features=AutomationControlled',
157
+ '--no-first-run',
158
+ '--extensions-on-chrome-urls',
159
+ '--ash-no-nudges',
160
+ '--no-pings',
161
+ '--test-type=gpu',
162
+ '--disable-client-side-phishing-detection',
163
+ '--password-store=basic',
164
+ '--enable-features=NetworkService,NetworkServiceInProcess',
165
+ '--disable-extensions-http-throttling',
166
+ '--disable-speech-synthesis-api',
167
+ '--no-default-browser-check',
168
+ '--disable-hang-monitor',
169
+ '--hide-crash-restore-bubble',
170
+ '--disable-domain-reliability',
171
+ '--export-tagged-pdf',
172
+ '--disable-sync',
173
+ '--disable-features=AcceptCHFrame,AutoExpandDetailsElement,AvoidUnnecessaryBeforeUnloadCheckSync,CertificateTransparencyComponentUpdater,DestroyProfileOnBrowserClose,DialMediaRouteProvider,ExtensionManifestV2Disabled,GlobalMediaControls,HttpsUpgrades,ImprovedCookieControls,LazyFrameLoading,LensOverlay,MediaRouter,PaintHolding,ThirdPartyStoragePartitioning,Translate,AutomationControlled,BackForwardCache,OptimizationHints,ProcessPerSiteUpToMainFrameThreshold,InterestFeedContentSuggestions,CalculateNativeWinOcclusion,HeavyAdPrivacyMitigations,PrivacySandboxSettings4,AutofillServerCommunication,CrashReporting,OverscrollHistoryNavigation,InfiniteSessionRestore,ExtensionDisableUnsupportedDeveloper',
174
+ '--disable-prompt-on-repost',
175
+ '--disable-infobars',
176
+ '--disable-datasaver-prompt',
177
+ '--noerrdialogs',
178
+ '--disable-breakpad',
179
+ '--disable-field-trial-config',
180
+ '--window-size=1920,1080',
181
+ '--window-position=0,0',
182
+ '--enable-extensions',
183
+ '--disable-extensions-file-access-check',
184
+ '--enable-extension-activity-logging',
185
+ `--remote-debugging-port=${port}`,
186
+ '--remote-debugging-address=0.0.0.0',
187
+ 'about:blank',
188
+ ];
189
+
190
+ const proc = spawn(executablePath, args, {
191
+ stdio: ['ignore', 'ignore', 'pipe'], // stderr is useful for debugging
192
+ env: { ...process.env, ...env },
193
+ });
194
+
195
+ proc.on('error', (error) => {
196
+ logger.error({ message: 'Chromium error', error });
197
+ });
198
+
199
+ proc.on('exit', (code, signal) => {
200
+ logger.error({ message: 'Chromium exited', code, signal, instanceId, port });
201
+ // Clean up the instance from our map
202
+ browserInstances.delete(instanceId);
203
+ });
204
+
205
+ await waitForCdpEndpoint(port, 30);
206
+
207
+ const cdpUrl = `http://127.0.0.1:${port}`;
208
+
209
+ const instance: BrowserInstance = {
210
+ id: instanceId,
211
+ cdpUrl,
212
+ proc,
213
+ port,
214
+ profileDir: userDataDir === profileDir ? profileDir : undefined,
215
+ };
216
+
217
+ browserInstances.set(instanceId, instance);
218
+
219
+ logger.info({ message: 'Local browser task started', cdpUrl, instanceId, port, totalInstances: browserInstances.size });
220
+
221
+ return { cdpUrl, instanceId };
222
+ }
223
+
224
+ // Legacy HTTP polling helpers removed in favor of waitForCdpEndpoint
225
+
226
+ async function waitForCdpEndpoint(port: number, maxAttempts: number): Promise<void> {
227
+ logger.info({ message: `Waiting for CDP endpoint on port ${port}...` });
228
+ for (let attemptIndex = 0; attemptIndex < maxAttempts; attemptIndex++) {
229
+ try {
230
+ const response = await fetch(`http://127.0.0.1:${port}/json/version`);
231
+ if (response.ok) {
232
+ const version = await response.json();
233
+ logger.info({ message: `CDP endpoint ready on port ${port}`, version: version['Browser'] });
234
+ return;
235
+ }
236
+ } catch (error) {
237
+ if (attemptIndex % 5 === 0) {
238
+ logger.debug({ message: `CDP endpoint not ready yet, attempt ${attemptIndex + 1}/${maxAttempts}`, error });
239
+ }
240
+ }
241
+ await wait(1000);
242
+ }
243
+ throw new Error(`CDP endpoint not available on port ${port} after ${maxAttempts} attempts`);
244
+ }
245
+
246
+ export function isLocalBrowserRunning(instanceId?: string): boolean {
247
+ if (instanceId) {
248
+ return browserInstances.has(instanceId);
249
+ }
250
+ return browserInstances.size > 0;
251
+ }
252
+
253
+ /**
254
+ * Get all running browser instances
255
+ */
256
+ export function getAllBrowserInstances(): Map<string, BrowserInstance> {
257
+ return new Map(browserInstances);
258
+ }
259
+
260
+ /**
261
+ * Get a specific browser instance
262
+ */
263
+ export function getBrowserInstance(instanceId: string): BrowserInstance | undefined {
264
+ return browserInstances.get(instanceId);
265
+ }
266
+
267
+ /**
268
+ * Kill a specific browser instance or all instances
269
+ * @param instanceId - Optional instance ID to kill. If not provided, kills all instances.
270
+ */
271
+ export async function kill(instanceId?: string) {
272
+ if (instanceId) {
273
+ // Kill specific instance
274
+ const instance = browserInstances.get(instanceId);
275
+ if (instance) {
276
+ logger.info({ message: 'Killing browser instance', instanceId, port: instance.port });
277
+ instance.proc.kill('SIGTERM');
278
+ await wait(300);
279
+ if (!instance.proc.killed) {
280
+ instance.proc.kill('SIGKILL');
281
+ }
282
+
283
+ // Clean up profile directory if it was auto-generated
284
+ if (instance.profileDir) {
285
+ try {
286
+ await fs.rm(instance.profileDir, { recursive: true, force: true });
287
+ } catch (error) {
288
+ logger.warn({ message: 'Failed to clean up profile directory', instanceId, error });
289
+ }
290
+ }
291
+
292
+ browserInstances.delete(instanceId);
293
+ }
294
+ } else {
295
+ // Kill all instances
296
+ logger.info({ message: 'Killing all browser instances', count: browserInstances.size });
297
+ const killPromises = Array.from(browserInstances.keys()).map((id) => kill(id));
298
+ await Promise.all(killPromises);
299
+ }
300
+ }