@bastani/atomic 0.8.21 → 0.8.22

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 (235) hide show
  1. package/CHANGELOG.md +66 -9
  2. package/dist/builtin/intercom/broker/broker.ts +3 -3
  3. package/dist/builtin/intercom/config.ts +3 -3
  4. package/dist/builtin/intercom/index.ts +1 -1
  5. package/dist/builtin/intercom/package.json +1 -1
  6. package/dist/builtin/intercom/ui/compose.ts +2 -2
  7. package/dist/builtin/mcp/host-html-template.ts +0 -3
  8. package/dist/builtin/mcp/package.json +1 -1
  9. package/dist/builtin/subagents/CHANGELOG.md +20 -4
  10. package/dist/builtin/subagents/agents/codebase-online-researcher.md +9 -9
  11. package/dist/builtin/subagents/agents/debugger.md +6 -6
  12. package/dist/builtin/subagents/package.json +1 -1
  13. package/dist/builtin/subagents/prompts/parallel-handoff-plan.md +1 -1
  14. package/dist/builtin/subagents/skills/browser-use/SKILL.md +234 -0
  15. package/dist/builtin/subagents/skills/browser-use/references/cdp-python.md +76 -0
  16. package/dist/builtin/subagents/skills/browser-use/references/multi-session.md +92 -0
  17. package/dist/builtin/subagents/skills/subagent/SKILL.md +4 -4
  18. package/dist/builtin/subagents/src/agents/skills.ts +19 -1
  19. package/dist/builtin/subagents/src/extension/index.ts +24 -22
  20. package/dist/builtin/subagents/src/intercom/intercom-bridge.ts +7 -1
  21. package/dist/builtin/subagents/src/runs/background/async-execution.ts +23 -7
  22. package/dist/builtin/subagents/src/runs/background/async-job-tracker.ts +98 -3
  23. package/dist/builtin/subagents/src/runs/background/async-status.ts +3 -1
  24. package/dist/builtin/subagents/src/runs/background/run-status.ts +1 -1
  25. package/dist/builtin/subagents/src/runs/background/stale-run-reconciler.ts +3 -0
  26. package/dist/builtin/subagents/src/runs/background/subagent-runner.ts +37 -12
  27. package/dist/builtin/subagents/src/runs/foreground/chain-clarify.ts +15 -15
  28. package/dist/builtin/subagents/src/runs/foreground/execution.ts +26 -2
  29. package/dist/builtin/subagents/src/runs/shared/nested-render.ts +1 -1
  30. package/dist/builtin/subagents/src/runs/shared/parallel-utils.ts +7 -0
  31. package/dist/builtin/subagents/src/runs/shared/pi-args.ts +28 -1
  32. package/dist/builtin/subagents/src/shared/fast-mode.ts +80 -0
  33. package/dist/builtin/subagents/src/shared/formatters.ts +4 -2
  34. package/dist/builtin/subagents/src/shared/types.ts +4 -2
  35. package/dist/builtin/subagents/src/shared/utils.ts +3 -61
  36. package/dist/builtin/subagents/src/tui/render.ts +303 -157
  37. package/dist/builtin/web-access/package.json +1 -1
  38. package/dist/builtin/workflows/CHANGELOG.md +113 -35
  39. package/dist/builtin/workflows/README.md +228 -41
  40. package/dist/builtin/workflows/builtin/deep-research-codebase.ts +535 -541
  41. package/dist/builtin/workflows/builtin/goal.ts +39 -25
  42. package/dist/builtin/workflows/builtin/open-claude-design.ts +66 -69
  43. package/dist/builtin/workflows/builtin/ralph.ts +21 -21
  44. package/dist/builtin/workflows/package.json +6 -5
  45. package/dist/builtin/workflows/skills/research-codebase/SKILL.md +1 -1
  46. package/dist/builtin/workflows/src/extension/background-ui-adapter.ts +2 -2
  47. package/dist/builtin/workflows/src/extension/discovery.ts +25 -146
  48. package/dist/builtin/workflows/src/extension/dispatcher.ts +72 -24
  49. package/dist/builtin/workflows/src/extension/hil-answer-notifications.ts +363 -0
  50. package/dist/builtin/workflows/src/extension/index.ts +690 -352
  51. package/dist/builtin/workflows/src/extension/lifecycle-notifications.ts +99 -62
  52. package/dist/builtin/workflows/src/extension/render-call.ts +2 -1
  53. package/dist/builtin/workflows/src/extension/render-result.ts +9 -3
  54. package/dist/builtin/workflows/src/extension/renderers.ts +5 -3
  55. package/dist/builtin/workflows/src/extension/runtime.ts +68 -33
  56. package/dist/builtin/workflows/src/extension/status-writer.ts +1 -1
  57. package/dist/builtin/workflows/src/extension/wiring.ts +34 -13
  58. package/dist/builtin/workflows/src/extension/workflow-module-loader.ts +142 -0
  59. package/dist/builtin/workflows/src/extension/workflow-schema.ts +4 -4
  60. package/dist/builtin/workflows/src/index.ts +2 -0
  61. package/dist/builtin/workflows/src/intercom/result-intercom.ts +1 -1
  62. package/dist/builtin/workflows/src/runs/background/runner.ts +6 -4
  63. package/dist/builtin/workflows/src/runs/background/status.ts +45 -21
  64. package/dist/builtin/workflows/src/runs/foreground/executor.ts +624 -52
  65. package/dist/builtin/workflows/src/runs/foreground/stage-control-registry.ts +1 -1
  66. package/dist/builtin/workflows/src/runs/foreground/stage-runner.ts +80 -24
  67. package/dist/builtin/workflows/src/runs/shared/validate-inputs.ts +61 -24
  68. package/dist/builtin/workflows/src/runs/shared/workflow-runner.ts +32 -10
  69. package/dist/builtin/workflows/src/sdk-surface.ts +6 -0
  70. package/dist/builtin/workflows/src/shared/expanded-workflow-graph.ts +178 -0
  71. package/dist/builtin/workflows/src/shared/persistence-restore.ts +92 -12
  72. package/dist/builtin/workflows/src/shared/persistence-session-entries.ts +21 -3
  73. package/dist/builtin/workflows/src/shared/render-inputs-schema.ts +1 -2
  74. package/dist/builtin/workflows/src/shared/run-visibility.ts +9 -0
  75. package/dist/builtin/workflows/src/shared/schema-introspection.ts +121 -0
  76. package/dist/builtin/workflows/src/shared/serializable.ts +132 -0
  77. package/dist/builtin/workflows/src/shared/stage-ui-broker.ts +91 -9
  78. package/dist/builtin/workflows/src/shared/store-types.ts +31 -3
  79. package/dist/builtin/workflows/src/shared/store.ts +58 -14
  80. package/dist/builtin/workflows/src/shared/types.ts +105 -40
  81. package/dist/builtin/workflows/src/tui/chat-surface-message.ts +129 -13
  82. package/dist/builtin/workflows/src/tui/chat-surface.ts +6 -1
  83. package/dist/builtin/workflows/src/tui/dispatch-confirm.ts +3 -2
  84. package/dist/builtin/workflows/src/tui/graph-canvas.ts +1 -1
  85. package/dist/builtin/workflows/src/tui/graph-view.ts +91 -65
  86. package/dist/builtin/workflows/src/tui/inline-form-card.ts +1 -1
  87. package/dist/builtin/workflows/src/tui/inline-form-overlay.ts +3 -2
  88. package/dist/builtin/workflows/src/tui/inputs-overlay.ts +3 -2
  89. package/dist/builtin/workflows/src/tui/inputs-picker.ts +8 -7
  90. package/dist/builtin/workflows/src/tui/keybindings-adapter.ts +2 -0
  91. package/dist/builtin/workflows/src/tui/node-card.ts +34 -8
  92. package/dist/builtin/workflows/src/tui/overlay-adapter.ts +4 -11
  93. package/dist/builtin/workflows/src/tui/prompt-card.ts +98 -50
  94. package/dist/builtin/workflows/src/tui/session-list.ts +7 -2
  95. package/dist/builtin/workflows/src/tui/session-picker.ts +2 -0
  96. package/dist/builtin/workflows/src/tui/stage-chat-view.ts +226 -55
  97. package/dist/builtin/workflows/src/tui/status-helpers.ts +2 -0
  98. package/dist/builtin/workflows/src/tui/store-widget-installer.ts +37 -158
  99. package/dist/builtin/workflows/src/tui/toast.ts +2 -2
  100. package/dist/builtin/workflows/src/tui/widget.ts +53 -12
  101. package/dist/builtin/workflows/src/tui/workflow-attach-pane.ts +270 -19
  102. package/dist/builtin/workflows/src/tui/workflow-notice-card.ts +184 -0
  103. package/dist/builtin/workflows/src/workflows/define-workflow.ts +138 -43
  104. package/dist/config.d.ts +9 -0
  105. package/dist/config.d.ts.map +1 -1
  106. package/dist/config.js +45 -0
  107. package/dist/config.js.map +1 -1
  108. package/dist/core/agent-session.d.ts +27 -9
  109. package/dist/core/agent-session.d.ts.map +1 -1
  110. package/dist/core/agent-session.js +196 -17
  111. package/dist/core/agent-session.js.map +1 -1
  112. package/dist/core/atomic-guide-command.d.ts.map +1 -1
  113. package/dist/core/atomic-guide-command.js +2 -2
  114. package/dist/core/atomic-guide-command.js.map +1 -1
  115. package/dist/core/codex-fast-mode.d.ts +36 -0
  116. package/dist/core/codex-fast-mode.d.ts.map +1 -0
  117. package/dist/core/codex-fast-mode.js +117 -0
  118. package/dist/core/codex-fast-mode.js.map +1 -0
  119. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  120. package/dist/core/compaction/branch-summarization.js +1 -1
  121. package/dist/core/compaction/branch-summarization.js.map +1 -1
  122. package/dist/core/compaction/compaction.d.ts.map +1 -1
  123. package/dist/core/compaction/compaction.js +1 -1
  124. package/dist/core/compaction/compaction.js.map +1 -1
  125. package/dist/core/extensions/index.d.ts +4 -1
  126. package/dist/core/extensions/index.d.ts.map +1 -1
  127. package/dist/core/extensions/index.js +1 -0
  128. package/dist/core/extensions/index.js.map +1 -1
  129. package/dist/core/extensions/loader.d.ts +7 -2
  130. package/dist/core/extensions/loader.d.ts.map +1 -1
  131. package/dist/core/extensions/loader.js +23 -8
  132. package/dist/core/extensions/loader.js.map +1 -1
  133. package/dist/core/extensions/reactive-widget.d.ts +58 -0
  134. package/dist/core/extensions/reactive-widget.d.ts.map +1 -0
  135. package/dist/core/extensions/reactive-widget.js +182 -0
  136. package/dist/core/extensions/reactive-widget.js.map +1 -0
  137. package/dist/core/extensions/runner.d.ts.map +1 -1
  138. package/dist/core/extensions/runner.js +1 -0
  139. package/dist/core/extensions/runner.js.map +1 -1
  140. package/dist/core/extensions/types.d.ts +26 -12
  141. package/dist/core/extensions/types.d.ts.map +1 -1
  142. package/dist/core/extensions/types.js.map +1 -1
  143. package/dist/core/messages.d.ts +1 -1
  144. package/dist/core/messages.d.ts.map +1 -1
  145. package/dist/core/messages.js +8 -2
  146. package/dist/core/messages.js.map +1 -1
  147. package/dist/core/model-registry.d.ts +4 -0
  148. package/dist/core/model-registry.d.ts.map +1 -1
  149. package/dist/core/model-registry.js +11 -0
  150. package/dist/core/model-registry.js.map +1 -1
  151. package/dist/core/resource-loader.d.ts +9 -1
  152. package/dist/core/resource-loader.d.ts.map +1 -1
  153. package/dist/core/resource-loader.js +49 -21
  154. package/dist/core/resource-loader.js.map +1 -1
  155. package/dist/core/sdk.d.ts.map +1 -1
  156. package/dist/core/sdk.js +22 -13
  157. package/dist/core/sdk.js.map +1 -1
  158. package/dist/core/session-manager.d.ts +7 -5
  159. package/dist/core/session-manager.d.ts.map +1 -1
  160. package/dist/core/session-manager.js +5 -3
  161. package/dist/core/session-manager.js.map +1 -1
  162. package/dist/core/settings-manager.d.ts +16 -0
  163. package/dist/core/settings-manager.d.ts.map +1 -1
  164. package/dist/core/settings-manager.js +64 -5
  165. package/dist/core/settings-manager.js.map +1 -1
  166. package/dist/core/slash-commands.d.ts.map +1 -1
  167. package/dist/core/slash-commands.js +1 -0
  168. package/dist/core/slash-commands.js.map +1 -1
  169. package/dist/core/system-prompt.d.ts.map +1 -1
  170. package/dist/core/system-prompt.js +7 -4
  171. package/dist/core/system-prompt.js.map +1 -1
  172. package/dist/core/tools/ask-user-question/ask-user-question.d.ts.map +1 -1
  173. package/dist/core/tools/ask-user-question/ask-user-question.js +2 -2
  174. package/dist/core/tools/ask-user-question/ask-user-question.js.map +1 -1
  175. package/dist/index.d.ts +4 -3
  176. package/dist/index.d.ts.map +1 -1
  177. package/dist/index.js +3 -2
  178. package/dist/index.js.map +1 -1
  179. package/dist/main.d.ts +3 -0
  180. package/dist/main.d.ts.map +1 -1
  181. package/dist/main.js +12 -0
  182. package/dist/main.js.map +1 -1
  183. package/dist/modes/interactive/chat-input-actions.d.ts.map +1 -1
  184. package/dist/modes/interactive/chat-input-actions.js.map +1 -1
  185. package/dist/modes/interactive/components/diff.d.ts.map +1 -1
  186. package/dist/modes/interactive/components/diff.js +0 -1
  187. package/dist/modes/interactive/components/diff.js.map +1 -1
  188. package/dist/modes/interactive/components/fast-mode-selector.d.ts +27 -0
  189. package/dist/modes/interactive/components/fast-mode-selector.d.ts.map +1 -0
  190. package/dist/modes/interactive/components/fast-mode-selector.js +105 -0
  191. package/dist/modes/interactive/components/fast-mode-selector.js.map +1 -0
  192. package/dist/modes/interactive/components/footer.d.ts.map +1 -1
  193. package/dist/modes/interactive/components/footer.js +7 -12
  194. package/dist/modes/interactive/components/footer.js.map +1 -1
  195. package/dist/modes/interactive/components/index.d.ts +1 -0
  196. package/dist/modes/interactive/components/index.d.ts.map +1 -1
  197. package/dist/modes/interactive/components/index.js +1 -0
  198. package/dist/modes/interactive/components/index.js.map +1 -1
  199. package/dist/modes/interactive/interactive-mode.d.ts +4 -0
  200. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  201. package/dist/modes/interactive/interactive-mode.js +132 -30
  202. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  203. package/dist/modes/print-mode.d.ts.map +1 -1
  204. package/dist/modes/print-mode.js +53 -6
  205. package/dist/modes/print-mode.js.map +1 -1
  206. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  207. package/dist/modes/rpc/rpc-mode.js +3 -0
  208. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  209. package/docs/compaction.md +1 -1
  210. package/docs/custom-provider.md +2 -2
  211. package/docs/development.md +2 -2
  212. package/docs/docs.json +2 -2
  213. package/docs/extensions.md +18 -13
  214. package/docs/providers.md +5 -1
  215. package/docs/quickstart.md +5 -3
  216. package/docs/rpc.md +5 -5
  217. package/docs/sdk.md +12 -12
  218. package/docs/settings.md +18 -0
  219. package/docs/themes.md +6 -6
  220. package/docs/tui.md +20 -18
  221. package/docs/usage.md +2 -0
  222. package/docs/workflows.md +403 -39
  223. package/examples/extensions/qna.ts +2 -2
  224. package/package.json +4 -4
  225. package/dist/builtin/subagents/skills/playwright-cli/SKILL.md +0 -392
  226. package/dist/builtin/subagents/skills/playwright-cli/references/element-attributes.md +0 -23
  227. package/dist/builtin/subagents/skills/playwright-cli/references/playwright-tests.md +0 -39
  228. package/dist/builtin/subagents/skills/playwright-cli/references/request-mocking.md +0 -87
  229. package/dist/builtin/subagents/skills/playwright-cli/references/running-code.md +0 -241
  230. package/dist/builtin/subagents/skills/playwright-cli/references/session-management.md +0 -225
  231. package/dist/builtin/subagents/skills/playwright-cli/references/spec-driven-testing.md +0 -305
  232. package/dist/builtin/subagents/skills/playwright-cli/references/storage-state.md +0 -275
  233. package/dist/builtin/subagents/skills/playwright-cli/references/test-generation.md +0 -134
  234. package/dist/builtin/subagents/skills/playwright-cli/references/tracing.md +0 -139
  235. package/dist/builtin/subagents/skills/playwright-cli/references/video-recording.md +0 -143
@@ -0,0 +1,234 @@
1
+ ---
2
+ name: browser-use
3
+ description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, or extract information from web pages.
4
+ allowed-tools: Bash(browser-use:*)
5
+ ---
6
+
7
+ # Browser Automation with browser-use CLI
8
+
9
+ The `browser-use` command provides fast, persistent browser automation. A background daemon keeps the browser open across commands, giving ~50ms latency per call.
10
+
11
+ ## Prerequisites
12
+
13
+ ```bash
14
+ browser-use doctor # Verify installation
15
+ ```
16
+
17
+ For setup details, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md
18
+
19
+ ## Core Workflow
20
+
21
+ 1. **Navigate**: `browser-use open <url>` — launches headless browser and opens page
22
+ 2. **Inspect**: `browser-use state` — returns clickable elements with indices
23
+ 3. **Interact**: use indices from state (`browser-use click 5`, `browser-use input 3 "text"`)
24
+ 4. **Verify**: `browser-use state` or `browser-use screenshot` to confirm
25
+ 5. **Repeat**: browser stays open between commands
26
+
27
+ If a command fails, run `browser-use close` first to clear any broken session, then retry.
28
+
29
+ To use the user's existing Chrome (preserves logins/cookies): run `browser-use connect` first.
30
+ To use a cloud browser instead: run `browser-use cloud connect` first.
31
+ After either, commands work the same way.
32
+
33
+ ### If `browser-use connect` fails
34
+
35
+ When `browser-use connect` cannot find a running Chrome with remote debugging, prompt the user with two options:
36
+
37
+ 1. **Use their real Chrome browser** — they need to enable remote debugging first:
38
+ - Open `chrome://inspect/#remote-debugging` in Chrome, or relaunch Chrome with `--remote-debugging-port=9222`
39
+ - Then retry `browser-use connect`
40
+ 2. **Use managed Chromium with their Chrome profile** — no Chrome setup needed:
41
+ - Run `browser-use profile list` to show available profiles
42
+ - Ask which profile they want, then use `browser-use --profile "ProfileName" open <url>`
43
+ - This launches a separate Chromium instance with their profile data (cookies, logins, extensions)
44
+
45
+ Let the user choose — don't assume one path over the other.
46
+
47
+ ## Browser Modes
48
+
49
+ ```bash
50
+ browser-use open <url> # Default: headless Chromium (no setup needed)
51
+ browser-use --headed open <url> # Visible window (for debugging)
52
+ browser-use connect # Connect to user's Chrome (preserves logins/cookies)
53
+ browser-use cloud connect # Cloud browser (zero-config, requires API key)
54
+ browser-use --profile "Default" open <url> # Real Chrome with specific profile
55
+ ```
56
+
57
+ After `connect` or `cloud connect`, all subsequent commands go to that browser — no extra flags needed.
58
+
59
+ ## Commands
60
+
61
+ ```bash
62
+ # Navigation
63
+ browser-use open <url> # Navigate to URL
64
+ browser-use back # Go back in history
65
+ browser-use scroll down # Scroll down (--amount N for pixels)
66
+ browser-use scroll up # Scroll up
67
+ browser-use tab list # List all tabs
68
+ browser-use tab new [url] # Open a new tab (blank or with URL)
69
+ browser-use tab switch <index> # Switch to tab by index
70
+ browser-use tab close <index> [index...] # Close one or more tabs
71
+
72
+ # Page State — always run state first to get element indices
73
+ browser-use state # URL, title, clickable elements with indices
74
+ browser-use screenshot [path.png] # Screenshot (base64 if no path, --full for full page)
75
+
76
+ # Interactions — use indices from state
77
+ browser-use click <index> # Click element by index
78
+ browser-use click <x> <y> # Click at pixel coordinates
79
+ browser-use type "text" # Type into focused element
80
+ browser-use input <index> "text" # Click element, clear existing text, then type
81
+ browser-use input <index> "" # Clear a field without typing new text
82
+ browser-use keys "Enter" # Send keyboard keys (also "Control+a", etc.)
83
+ browser-use select <index> "option" # Select dropdown option
84
+ browser-use upload <index> <path> # Upload file to file input
85
+ browser-use hover <index> # Hover over element
86
+ browser-use dblclick <index> # Double-click element
87
+ browser-use rightclick <index> # Right-click element
88
+
89
+ # Data Extraction
90
+ browser-use eval "js code" # Execute JavaScript, return result
91
+ browser-use get title # Page title
92
+ browser-use get html [--selector "h1"] # Page HTML (or scoped to selector)
93
+ browser-use get text <index> # Element text content
94
+ browser-use get value <index> # Input/textarea value
95
+ browser-use get attributes <index> # Element attributes
96
+ browser-use get bbox <index> # Bounding box (x, y, width, height)
97
+
98
+ # Wait
99
+ browser-use wait selector "css" # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
100
+ browser-use wait text "text" # Wait for text to appear
101
+
102
+ # Cookies
103
+ browser-use cookies get [--url <url>] # Get cookies (optionally filtered)
104
+ browser-use cookies set <name> <value> # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
105
+ browser-use cookies clear [--url <url>] # Clear cookies
106
+ browser-use cookies export <file> # Export to JSON
107
+ browser-use cookies import <file> # Import from JSON
108
+
109
+ # Session
110
+ browser-use close # Close browser and stop daemon
111
+ browser-use sessions # List active sessions
112
+ browser-use close --all # Close all sessions
113
+ ```
114
+
115
+ For advanced browser control (CDP, device emulation, tab activation), see `references/cdp-python.md`.
116
+
117
+ ## Cloud API
118
+
119
+ ```bash
120
+ browser-use cloud connect # Provision cloud browser and connect (zero-config)
121
+ browser-use cloud login <api-key> # Save API key (or set BROWSER_USE_API_KEY)
122
+ browser-use cloud logout # Remove API key
123
+ browser-use cloud v2 GET /browsers # REST passthrough (v2 or v3)
124
+ browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
125
+ browser-use cloud v2 poll <task-id> # Poll task until done
126
+ browser-use cloud v2 --help # Show API endpoints
127
+ ```
128
+
129
+ `cloud connect` provisions a cloud browser with a persistent profile (auto-created on first use), connects via CDP, and prints a live URL. `browser-use close` disconnects AND stops the cloud browser. For custom browser settings (proxy, timeout, specific profile), use `cloud v2 POST /browsers` directly with the desired parameters.
130
+
131
+ ### Agent Self-Registration
132
+
133
+ Only use this if you don't already have an API key (check `browser-use doctor` to see if api_key is set). If already logged in, skip this entirely.
134
+
135
+ 1. `browser-use cloud signup` — get a challenge
136
+ 2. Solve the challenge
137
+ 3. `browser-use cloud signup --verify <challenge-id> <answer>` — verify and save API key
138
+ 4. `browser-use cloud signup --claim` — generate URL for a human to claim the account
139
+
140
+ ## Tunnels
141
+
142
+ ```bash
143
+ browser-use tunnel <port> # Start Cloudflare tunnel (idempotent)
144
+ browser-use tunnel list # Show active tunnels
145
+ browser-use tunnel stop <port> # Stop tunnel
146
+ browser-use tunnel stop --all # Stop all tunnels
147
+ ```
148
+
149
+ ## Profile Management
150
+
151
+ ```bash
152
+ browser-use profile list # List detected browsers and profiles
153
+ browser-use profile sync --all # Sync profiles to cloud
154
+ browser-use profile update # Download/update profile-use binary
155
+ ```
156
+
157
+ ## Command Chaining
158
+
159
+ Commands can be chained with `&&`. The browser persists via the daemon, so chaining is safe and efficient.
160
+
161
+ ```bash
162
+ browser-use open https://example.com && browser-use state
163
+ browser-use input 5 "user@example.com" && browser-use input 6 "password" && browser-use click 7
164
+ ```
165
+
166
+ Chain when you don't need intermediate output. Run separately when you need to parse `state` to discover indices first.
167
+
168
+ ## Common Workflows
169
+
170
+ ### Authenticated Browsing
171
+
172
+ When a task requires an authenticated site (Gmail, GitHub, internal tools), use Chrome profiles:
173
+
174
+ ```bash
175
+ browser-use profile list # Check available profiles
176
+ # Ask the user which profile to use, then:
177
+ browser-use --profile "Default" open https://github.com # Already logged in
178
+ ```
179
+
180
+ ### Exposing Local Dev Servers
181
+
182
+ ```bash
183
+ browser-use tunnel 3000 # → https://abc.trycloudflare.com
184
+ browser-use open https://abc.trycloudflare.com # Browse the tunnel
185
+ ```
186
+
187
+ ## Multiple Browsers
188
+
189
+ For subagent workflows or running multiple browsers in parallel, use `--session NAME`. Each session gets its own browser. See `references/multi-session.md`.
190
+
191
+ ## Configuration
192
+
193
+ ```bash
194
+ browser-use config list # Show all config values
195
+ browser-use config set cloud_connect_proxy jp # Set a value
196
+ browser-use config get cloud_connect_proxy # Get a value
197
+ browser-use config unset cloud_connect_timeout # Remove a value
198
+ browser-use doctor # Shows config + diagnostics
199
+ browser-use setup # Interactive post-install setup
200
+ ```
201
+
202
+ Config stored in `~/.browser-use/config.json`.
203
+
204
+ ## Global Options
205
+
206
+ | Option | Description |
207
+ |--------|-------------|
208
+ | `--headed` | Show browser window |
209
+ | `--profile [NAME]` | Use real Chrome (bare `--profile` uses "Default") |
210
+ | `--cdp-url <url>` | Connect via CDP URL (`http://` or `ws://`) |
211
+ | `--session NAME` | Target a named session (default: "default") |
212
+ | `--json` | Output as JSON |
213
+ | `--mcp` | Run as MCP server via stdin/stdout |
214
+
215
+ ## Tips
216
+
217
+ 1. **Always run `state` first** to see available elements and their indices
218
+ 2. **Use `--headed` for debugging** to see what the browser is doing
219
+ 3. **Sessions persist** — browser stays open between commands
220
+ 4. **CLI aliases**: `bu`, `browser`, and `browseruse` all work
221
+ 5. **If commands fail**, run `browser-use close` first, then retry
222
+
223
+ ## Troubleshooting
224
+
225
+ - **Browser won't start?** `browser-use close` then `browser-use --headed open <url>`
226
+ - **Element not found?** `browser-use scroll down` then `browser-use state`
227
+ - **Run diagnostics:** `browser-use doctor`
228
+
229
+ ## Cleanup
230
+
231
+ ```bash
232
+ browser-use close # Close browser session
233
+ browser-use tunnel stop --all # Stop tunnels (if any)
234
+ ```
@@ -0,0 +1,76 @@
1
+ # Raw CDP & Python Session Reference
2
+
3
+ The CLI commands handle most browser interactions. Use `browser-use python` with raw CDP when you need browser-level control the CLI doesn't expose — activating a tab so the user sees it, intercepting network requests, emulating devices, or working with Chrome target IDs directly.
4
+
5
+ ## How the Python session works
6
+
7
+ `browser-use python "statement"` executes one Python statement per call. Variables persist across calls — set a value in one call, use it in the next.
8
+
9
+ A `browser` object is pre-injected with sync wrappers for common operations (`browser.goto()`, `browser.click()`, etc.). For anything beyond those, two internals give you full access:
10
+
11
+ - `browser._run(coroutine)` — run any async coroutine synchronously (60s timeout)
12
+ - `browser._session` — the raw `BrowserSession` with full CDP client access
13
+
14
+ ## Getting a CDP client
15
+
16
+ ```bash
17
+ browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
18
+ ```
19
+
20
+ After this, `cdp` persists across calls. Use `cdp.cdp_client.send.<Domain>.<method>()` for any CDP command and `cdp.session_id` for the session parameter.
21
+
22
+ ## Recipes
23
+
24
+ ### Activate a tab (make it visible to the user)
25
+
26
+ The CLI's `tab switch` only changes the agent's internal focus — Chrome's visible tab doesn't change. To actually show the user a specific tab:
27
+
28
+ ```bash
29
+ # Get all targets to find the target ID
30
+ browser-use python "targets = browser._session.session_manager.get_all_page_targets()"
31
+ browser-use python "print([(i, t.url) for i, t in enumerate(targets)])"
32
+
33
+ # Activate target at index 1 so the user sees it
34
+ browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session(target_id=None, focus=False))"
35
+ browser-use python "browser._run(cdp.cdp_client.send.Target.activateTarget(params={'targetId': targets[1].target_id}))"
36
+ ```
37
+
38
+ ### List all tabs with target IDs
39
+
40
+ ```bash
41
+ browser-use python "targets = browser._session.session_manager.get_all_page_targets()"
42
+ browser-use python "
43
+ for i, t in enumerate(targets):
44
+ print(f'{i}: {t.target_id[:12]}... {t.url}')
45
+ "
46
+ ```
47
+
48
+ ### Run JavaScript and get the result
49
+
50
+ ```bash
51
+ browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
52
+ browser-use python "result = browser._run(cdp.cdp_client.send.Runtime.evaluate(params={'expression': 'document.title', 'returnByValue': True}, session_id=cdp.session_id))"
53
+ browser-use python "print(result['result']['value'])"
54
+ ```
55
+
56
+ ### Emulate a mobile device
57
+
58
+ ```bash
59
+ browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
60
+ browser-use python "browser._run(cdp.cdp_client.send.Emulation.setDeviceMetricsOverride(params={'width': 375, 'height': 812, 'deviceScaleFactor': 3, 'mobile': True}, session_id=cdp.session_id))"
61
+ ```
62
+
63
+ ### Get cookies via CDP
64
+
65
+ ```bash
66
+ browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"
67
+ browser-use python "cookies = browser._run(cdp.cdp_client.send.Network.getCookies(params={}, session_id=cdp.session_id))"
68
+ browser-use python "print(cookies)"
69
+ ```
70
+
71
+ ## Tips
72
+
73
+ - Each `browser-use python` call is one statement. Multi-line strings work for `for` loops and `if` blocks, but you can't mix statements and expressions. Use multiple calls.
74
+ - Variables persist: set `cdp = ...` in one call, use `cdp` in the next.
75
+ - The `browser._run()` bridge has a 60-second timeout. For long operations, increase it or use the async internals directly.
76
+ - All CDP domains are available via `cdp.cdp_client.send.<Domain>.<method>()`. See the [Chrome DevTools Protocol docs](https://chromedevtools.github.io/devtools-protocol/) for the full API.
@@ -0,0 +1,92 @@
1
+ # Multiple Browser Sessions
2
+
3
+ ## Why use multiple sessions
4
+
5
+ When you need more than one browser at a time:
6
+ - Cloud browser for scraping + local Chrome for authenticated tasks
7
+ - Two different Chrome profiles simultaneously
8
+ - Isolated browser for testing that won't affect the user's browsing
9
+ - Running a headed browser for debugging while headless runs in background
10
+
11
+ ## How sessions are isolated
12
+
13
+ Each `--session NAME` gets:
14
+ - Its own daemon process
15
+ - Its own Unix socket (`~/.browser-use/{name}.sock`)
16
+ - Its own PID file and state file
17
+ - Its own browser instance (completely independent)
18
+ - Its own tab ownership state (multi-agent locks don't cross sessions)
19
+
20
+ ## The `--session` flag
21
+
22
+ Must be passed on every command targeting that session:
23
+
24
+ ```bash
25
+ browser-use --session work open <url> # goes to 'work' daemon
26
+ browser-use --session work state # reads from 'work' daemon
27
+ browser-use state # goes to 'default' daemon (different browser)
28
+ ```
29
+
30
+ If you forget `--session`, the command goes to the `default` session. This is the most common mistake — you'll interact with the wrong browser.
31
+
32
+ ## Combining sessions with browser modes
33
+
34
+ ```bash
35
+ # Session 1: cloud browser
36
+ browser-use --session cloud cloud connect
37
+
38
+ # Session 2: connect to user's Chrome
39
+ browser-use --session chrome connect
40
+
41
+ # Session 3: headed Chromium for debugging
42
+ browser-use --session debug --headed open <url>
43
+ ```
44
+
45
+ Each session is fully independent. The cloud session talks to a remote browser, the chrome session talks to the user's Chrome, and the debug session manages its own Chromium — all running simultaneously.
46
+
47
+ ## Listing and managing sessions
48
+
49
+ ```bash
50
+ browser-use sessions
51
+ ```
52
+
53
+ Output:
54
+ ```
55
+ SESSION PHASE PID CONFIG
56
+ cloud running 12345 cloud
57
+ chrome running 12346 cdp
58
+ debug ready 12347 headed
59
+ ```
60
+
61
+ PHASE shows the daemon lifecycle state: `initializing`, `ready`, `starting`, `running`, `shutting_down`, `stopped`, `failed`.
62
+
63
+ ```bash
64
+ browser-use --session cloud close # close one session
65
+ browser-use close --all # close every session
66
+ ```
67
+
68
+ ## Common patterns
69
+
70
+ **Cloud + local authenticated:**
71
+ ```bash
72
+ browser-use --session scraper cloud connect
73
+ browser-use --session scraper open https://example.com
74
+ # ... scrape data ...
75
+
76
+ browser-use --session auth --profile "Default" open https://github.com
77
+ browser-use --session auth state
78
+ # ... interact with authenticated site ...
79
+ ```
80
+
81
+ **Throwaway test browser:**
82
+ ```bash
83
+ browser-use --session test --headed open https://localhost:3000
84
+ # ... test, debug, inspect ...
85
+ browser-use --session test close # done, clean up
86
+ ```
87
+
88
+ **Environment variable:**
89
+ ```bash
90
+ export BROWSER_USE_SESSION=work
91
+ browser-use open <url> # uses 'work' session without --session flag
92
+ ```
@@ -20,7 +20,7 @@ Use this skill when the parent orchestrator needs to launch a specialized subage
20
20
  - **Parallel codebase discovery**: combine `codebase-locator`, `codebase-analyzer`, and `codebase-pattern-finder` to map where code lives, how it works, and what existing conventions look like — concurrently, with fresh context per child.
21
21
  - **Local research mining**: pair `codebase-research-locator` with `codebase-research-analyzer` to surface prior decisions in `research/` and `specs/` and extract what still applies.
22
22
  - **External research**: use `codebase-online-researcher` for authoritative web sources, with persisted findings in `research/web/`.
23
- - **Debug and fix**: use `debugger` to reproduce, diagnose, and patch failing behavior with `tdd` and `playwright-cli` support.
23
+ - **Debug and fix**: use `debugger` to reproduce, diagnose, and patch failing behavior with `tdd` and `browser-use` support.
24
24
  - **Refinement**: use `code-simplifier` to clean up recently changed code without altering behavior.
25
25
  - **Adversarial review**: compose read-only specialists (`codebase-analyzer`, `codebase-pattern-finder`, `debugger` in inspect-only mode, `codebase-online-researcher`) into a parallel review pass — there is no generic `reviewer` agent.
26
26
  - **Long-running work**: launch async/background runs and inspect them later.
@@ -125,9 +125,9 @@ Builtin agents load at the lowest priority. Project agents override user agents,
125
125
  | `codebase-pattern-finder` | Find similar implementations or conventions | `openai/gpt-5.4-mini` | low | read, grep, find, ls, bash | Read-only. Returns code snippets with `file:line` references. |
126
126
  | `codebase-research-locator` | Discover prior `research/` and `specs/` docs | `openai/gpt-5.4-mini` | low | read, grep, find, ls, bash | Read-only. Sorts by date, tiers by recency, flags supersession. |
127
127
  | `codebase-research-analyzer` | Extract decisions and constraints from prior docs | `openai/gpt-5.5` | low | read, grep, find, ls, bash | Read-only. Filters aggressively for what still applies today. |
128
- | `codebase-online-researcher` | Web research with authoritative sources | `openai/gpt-5.5` | low | read, grep, find, ls, bash, write, web_search, fetch_content, get_search_content | Has the `playwright-cli` skill. Persists keepers to `research/web/`. |
128
+ | `codebase-online-researcher` | Web research with authoritative sources | `openai/gpt-5.5` | low | read, grep, find, ls, bash, write, web_search, fetch_content, get_search_content | Has the `browser-use` skill. Persists keepers to `research/web/`. |
129
129
  | `code-simplifier` | Clean up recently changed code without changing behavior | `openai/gpt-5.5` | low | read, edit, write, grep, find, ls, bash | **Writer.** Scopes to recently modified code by default; preserves all observable behavior. |
130
- | `debugger` | Reproduce, diagnose, and fix failing behavior | `openai/gpt-5.5` | high | read, edit, write, grep, find, ls, bash, web_search, fetch_content, get_search_content | **Writer.** Has the `tdd` and `playwright-cli` skills. Inspect-only mode requires an explicit instruction. |
130
+ | `debugger` | Reproduce, diagnose, and fix failing behavior | `openai/gpt-5.5` | high | read, edit, write, grep, find, ls, bash, web_search, fetch_content, get_search_content | **Writer.** Has the `tdd` and `browser-use` skills. Inspect-only mode requires an explicit instruction. |
131
131
 
132
132
  Each builtin declares an explicit `model` and `fallbackModels` chain (typically `github-copilot/<same>`, then `anthropic/claude-opus-4-8`, then `github-copilot/claude-opus-4.7`). The current user-selected model is automatically appended as the last fallback and de-duplicated. Override per run with inline config:
133
133
 
@@ -153,7 +153,7 @@ A strong subagent prompt usually includes:
153
153
  - **Output**: the expected summary shape, artifact path, or finding format.
154
154
  - **Stop rules**: when to stop after enough evidence, and when not to keep searching.
155
155
 
156
- Avoid carrying over old prompt habits that over-specify every step. Use `must`, `always`, and `never` for real invariants; for judgment calls, give decision rules. For example, tell `codebase-analyzer` to trace the staged diff directly and report only evidence-backed findings, rather than prescribing every file or command. Tell `codebase-online-researcher` the retrieval budget: start with broad targeted searches, fetch the strongest sources via `fetch_content`, fall back to `playwright-cli` only when JS execution is required, and stop when the question is answered.
156
+ Avoid carrying over old prompt habits that over-specify every step. Use `must`, `always`, and `never` for real invariants; for judgment calls, give decision rules. For example, tell `codebase-analyzer` to trace the staged diff directly and report only evidence-backed findings, rather than prescribing every file or command. Tell `codebase-online-researcher` the retrieval budget: start with broad targeted searches, fetch the strongest sources via `fetch_content`, fall back to `browser-use` only when JS execution is required, and stop when the question is answered.
157
157
 
158
158
  For implementation handoffs to `debugger` or `code-simplifier`, name the approved scope and success criteria more clearly than the process. Good prompts say what to change, what not to change, where the evidence lives, how to validate, and when to escalate. They should not ask the child to create another subagent plan or continue the parent conversation.
159
159
 
@@ -119,11 +119,20 @@ function extractSkillPathsFromPackageRoot(packageRoot: string, source: SkillSour
119
119
  }
120
120
 
121
121
  let cachedGlobalNpmRoot: string | null = null;
122
+ let execSyncGlobalNpmRoot = execSync;
123
+ const GLOBAL_NPM_ROOT_TIMEOUT_MS = 2500;
122
124
 
123
125
  function getGlobalNpmRoot(): string | null {
124
126
  if (cachedGlobalNpmRoot !== null) return cachedGlobalNpmRoot;
125
127
  try {
126
- cachedGlobalNpmRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
128
+ // Keep global package probing bounded during startup while still allowing
129
+ // slower Windows/corporate npm wrappers enough time to launch.
130
+ cachedGlobalNpmRoot = execSyncGlobalNpmRoot("npm root -g", {
131
+ encoding: "utf-8",
132
+ stdio: ["ignore", "pipe", "ignore"],
133
+ timeout: GLOBAL_NPM_ROOT_TIMEOUT_MS,
134
+ windowsHide: true,
135
+ }).trim();
127
136
  return cachedGlobalNpmRoot;
128
137
  } catch {
129
138
  // Global npm root is optional in constrained environments.
@@ -639,4 +648,13 @@ export function discoverAvailableSkills(cwd: string): Array<{
639
648
  export function clearSkillCache(): void {
640
649
  skillCache.clear();
641
650
  loadSkillsCache = null;
651
+ cachedGlobalNpmRoot = null;
652
+ }
653
+
654
+ /**
655
+ * @internal Test seam for unit tests that need to mock `npm root -g`.
656
+ */
657
+ export function __setGlobalNpmRootExecSyncForTest(execSyncImpl?: typeof execSync): void {
658
+ execSyncGlobalNpmRoot = execSyncImpl ?? execSync;
659
+ cachedGlobalNpmRoot = null;
642
660
  }
@@ -23,7 +23,7 @@ import { discoverAgents } from "../agents/agents.ts";
23
23
  import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
24
24
  import { resolveCurrentSessionId } from "../shared/session-identity.ts";
25
25
  import { cleanupOldChainDirs } from "../shared/settings.ts";
26
- import { renderWidget, renderSubagentResult, stopResultAnimations, stopWidgetAnimation, syncResultAnimation } from "../tui/render.ts";
26
+ import { renderLiveSubagentResult, renderSubagentResult, stopResultAnimations, stopWidgetAnimation, type SubagentResultRenderState } from "../tui/render.ts";
27
27
  import { SubagentParams } from "./schemas.ts";
28
28
  import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
29
29
  import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
@@ -117,10 +117,12 @@ function isStaleExtensionContextError(error: unknown): boolean {
117
117
  return error instanceof Error && error.message.includes("Extension context no longer active");
118
118
  }
119
119
 
120
+ type SubagentToolRenderState = SubagentResultRenderState;
121
+
120
122
  function rebuildSlashResultContainer(
121
123
  container: Container,
122
124
  result: AgentToolResult<Details>,
123
- options: { expanded: boolean },
125
+ options: { expanded: boolean; now?: number },
124
126
  theme: ExtensionContext["ui"]["theme"],
125
127
  ): void {
126
128
  container.clear();
@@ -135,20 +137,17 @@ function createSlashResultComponent(
135
137
  details: SlashMessageDetails,
136
138
  options: { expanded: boolean },
137
139
  theme: ExtensionContext["ui"]["theme"],
138
- requestRender: () => void,
139
140
  ): Container {
140
141
  const container = new Container();
141
- const animationState: { subagentResultAnimationTimer?: ReturnType<typeof setInterval> } = {};
142
142
  let lastVersion = -1;
143
+ let lastSnapshotNow = 0;
143
144
  container.render = (width: number): string[] => {
144
145
  const snapshot = getSlashRenderableSnapshot(details);
145
- if (snapshot.version !== lastVersion || isSlashResultRunning(snapshot.result)) {
146
+ if (snapshot.version !== lastVersion) {
146
147
  lastVersion = snapshot.version;
147
- rebuildSlashResultContainer(container, snapshot.result, options, theme);
148
+ lastSnapshotNow = Date.now();
149
+ rebuildSlashResultContainer(container, snapshot.result, { ...options, now: lastSnapshotNow }, theme);
148
150
  }
149
- // Keep the live slash card's spinner animating by scheduling steady
150
- // re-renders while it runs (and tearing the timer down once it settles).
151
- syncResultAnimation(snapshot.result, { state: animationState, invalidate: requestRender });
152
151
  return Container.prototype.render.call(container, width);
153
152
  };
154
153
  return container;
@@ -281,7 +280,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
281
280
  };
282
281
  globalStore[runtimeCleanupStoreKey] = runtimeCleanup;
283
282
 
284
- const { ensurePoller, handleStarted, handleComplete, resetJobs } = createAsyncJobTracker(pi, state, ASYNC_DIR);
283
+ const { ensurePoller, handleStarted, handleComplete, resetJobs, hydrateActiveJobs } = createAsyncJobTracker(pi, state, ASYNC_DIR);
285
284
  const executor = createSubagentExecutor({
286
285
  pi,
287
286
  state,
@@ -296,7 +295,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
296
295
  pi.registerMessageRenderer<SlashMessageDetails>(SLASH_RESULT_TYPE, (message, options, theme) => {
297
296
  const details = resolveSlashMessageDetails(message.details);
298
297
  if (!details) return undefined;
299
- return createSlashResultComponent(details, options, theme, () => state.lastUiContext?.ui.requestRender?.());
298
+ return createSlashResultComponent(details, options, theme);
300
299
  });
301
300
 
302
301
  pi.registerMessageRenderer<SubagentNotifyDetails>("subagent-notify", (message, options, theme) => {
@@ -337,7 +336,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
337
336
  });
338
337
 
339
338
  const executeSubagentCollapsed = (id: string, params: SubagentParamsLike, signal: AbortSignal, onUpdate: ((result: AgentToolResult<Details>) => void) | undefined, ctx: ExtensionContext) => {
340
- if (ctx.hasUI) ctx.ui.setToolsExpanded(false);
339
+ if (ctx.hasUI) {
340
+ state.lastUiContext = ctx;
341
+ ctx.ui.setToolsExpanded(false);
342
+ }
341
343
  return executor.execute(id, params, signal, onUpdate, ctx);
342
344
  };
343
345
 
@@ -394,7 +396,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
394
396
  }, 0);
395
397
  }
396
398
 
397
- const tool: ToolDefinition<typeof SubagentParams, Details> = {
399
+ const tool: ToolDefinition<typeof SubagentParams, Details, SubagentToolRenderState> = {
398
400
  name: "subagent",
399
401
  label: "Subagent",
400
402
  description: `Delegate to subagents or manage agent definitions.
@@ -465,10 +467,12 @@ DIAGNOSTICS:
465
467
  },
466
468
 
467
469
  renderResult(result, options, theme, context) {
468
- // Animate the live subagent spinner by scheduling steady re-renders
469
- // while the result is running; the timer stops once it settles.
470
- syncResultAnimation(result, context);
471
- return renderSubagentResult(result, options, theme);
470
+ // Tool-result rows live in chat scrollback. The host keeps context.state
471
+ // on the ToolExecutionComponent for this row, so foreground updates/ticks
472
+ // capture an explicit frame timestamp and arbitrary host re-renders reuse
473
+ // it. Running foreground rows intentionally advance via their own timer;
474
+ // completed scrollback remains a stable point-in-time snapshot.
475
+ return renderLiveSubagentResult(result, options, theme, context);
472
476
  },
473
477
 
474
478
  };
@@ -513,11 +517,8 @@ DIAGNOSTICS:
513
517
  if (event.toolName !== "subagent") return;
514
518
  if (!ctx.hasUI) return;
515
519
  state.lastUiContext = ctx;
516
- if (state.asyncJobs.size > 0) {
517
- renderWidget(ctx, Array.from(state.asyncJobs.values()));
518
- ctx.ui.requestRender?.();
519
- ensurePoller();
520
- }
520
+ hydrateActiveJobs(ctx);
521
+ if (state.asyncJobs.size > 0) ensurePoller();
521
522
  });
522
523
 
523
524
  const cleanupSessionArtifacts = (ctx: ExtensionContext) => {
@@ -538,6 +539,7 @@ DIAGNOSTICS:
538
539
  cleanupSessionArtifacts(ctx);
539
540
  clearPendingForegroundControlNotices(state);
540
541
  resetJobs(ctx);
542
+ hydrateActiveJobs(ctx);
541
543
  restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
542
544
  primeExistingResults();
543
545
  };
@@ -197,7 +197,12 @@ function configuredPiIntercomPackageDir(input: ResolveIntercomBridgeInput, agent
197
197
  ...(projectConfigDir ? [{ file: path.join(projectConfigDir, "settings.json"), configDir: projectConfigDir, scope: "project" as const }] : []),
198
198
  { file: path.join(agentDir, "settings.json"), configDir: agentDir, scope: "user" as const },
199
199
  ];
200
- const globalNpmRoot = input.globalNpmRoot === undefined ? getGlobalNpmRoot() : input.globalNpmRoot;
200
+ let resolvedGlobalNpmRoot = input.globalNpmRoot;
201
+ const resolveGlobalNpmRoot = (): string | null => {
202
+ if (resolvedGlobalNpmRoot !== undefined) return resolvedGlobalNpmRoot;
203
+ resolvedGlobalNpmRoot = getGlobalNpmRoot();
204
+ return resolvedGlobalNpmRoot;
205
+ };
201
206
 
202
207
  for (const { file, configDir, scope } of settingsFiles) {
203
208
  const settings = readJsonBestEffort(file);
@@ -211,6 +216,7 @@ function configuredPiIntercomPackageDir(input: ResolveIntercomBridgeInput, agent
211
216
  if (!source?.startsWith("npm:")) continue;
212
217
  const packageName = parseNpmPackageName(source);
213
218
  if (packageName !== PI_INTERCOM_PACKAGE_NAME) continue;
219
+ const globalNpmRoot = scope === "user" ? resolveGlobalNpmRoot() : null;
214
220
  const candidates = scope === "project"
215
221
  ? [path.join(configDir, "npm", "node_modules", packageName)]
216
222
  : [