@lobu/runtime-device 24.1.1 → 24.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (194) hide show
  1. package/dist/component.json +1 -1
  2. package/dist/dependencies.bun.lock +46 -134
  3. package/npm-shrinkwrap.json +229 -730
  4. package/package.json +1 -1
  5. package/vendor/cli/dist/bundled-skills/lobu/SKILL.md +20 -5
  6. package/vendor/cli/dist/chrome-extension/accessibility-tree.js +834 -0
  7. package/vendor/cli/dist/chrome-extension/ambient-context.js +53 -0
  8. package/vendor/cli/dist/chrome-extension/auth-refresh.js +167 -0
  9. package/vendor/cli/dist/chrome-extension/automation-run.js +13 -0
  10. package/vendor/cli/dist/chrome-extension/background.js +1155 -0
  11. package/vendor/cli/dist/chrome-extension/bridge.js +140 -0
  12. package/vendor/cli/dist/chrome-extension/browser-origin-policy.js +62 -0
  13. package/vendor/cli/dist/chrome-extension/browser-recovery.js +260 -0
  14. package/vendor/cli/dist/chrome-extension/browser-url-sanitizer.js +284 -0
  15. package/vendor/cli/dist/chrome-extension/completion-response.js +12 -0
  16. package/vendor/cli/dist/chrome-extension/config.js +144 -0
  17. package/vendor/cli/dist/chrome-extension/connector-manifests/chrome.json +1516 -0
  18. package/vendor/cli/dist/chrome-extension/connector-manifests/chrome_bookmarks.json +84 -0
  19. package/vendor/cli/dist/chrome-extension/connector-manifests/chrome_downloads.json +86 -0
  20. package/vendor/cli/dist/chrome-extension/connector-manifests/chrome_history.json +78 -0
  21. package/vendor/cli/dist/chrome-extension/connector-manifests.js +1767 -0
  22. package/vendor/cli/dist/chrome-extension/console-capture.js +627 -0
  23. package/vendor/cli/dist/chrome-extension/control-activity.js +70 -0
  24. package/vendor/cli/dist/chrome-extension/debugger-lease.js +439 -0
  25. package/vendor/cli/dist/chrome-extension/feed-listener.js +488 -0
  26. package/vendor/cli/dist/chrome-extension/feed-transaction.js +48 -0
  27. package/vendor/cli/dist/chrome-extension/feeds.js +632 -0
  28. package/vendor/cli/dist/chrome-extension/focus-tab.js +25 -0
  29. package/vendor/cli/dist/chrome-extension/fonts/dm-mono-latin-500-normal.woff2 +0 -0
  30. package/vendor/cli/dist/chrome-extension/fonts/dm-sans-latin-400-normal.woff2 +0 -0
  31. package/vendor/cli/dist/chrome-extension/fonts/dm-sans-latin-600-normal.woff2 +0 -0
  32. package/vendor/cli/dist/chrome-extension/heartbeat.js +140 -0
  33. package/vendor/cli/dist/chrome-extension/icons/icon-128-rec.png +0 -0
  34. package/vendor/cli/dist/chrome-extension/icons/icon-128.png +0 -0
  35. package/vendor/cli/dist/chrome-extension/icons/icon-16-rec.png +0 -0
  36. package/vendor/cli/dist/chrome-extension/icons/icon-16.png +0 -0
  37. package/vendor/cli/dist/chrome-extension/icons/icon-32-rec.png +0 -0
  38. package/vendor/cli/dist/chrome-extension/icons/icon-32.png +0 -0
  39. package/vendor/cli/dist/chrome-extension/icons/icon-48-rec.png +0 -0
  40. package/vendor/cli/dist/chrome-extension/icons/icon-48.png +0 -0
  41. package/vendor/cli/dist/chrome-extension/lens-page.js +135 -0
  42. package/vendor/cli/dist/chrome-extension/lens-target.js +20 -0
  43. package/vendor/cli/dist/chrome-extension/manifest.json +76 -0
  44. package/vendor/cli/dist/chrome-extension/network-intercept.js +657 -0
  45. package/vendor/cli/dist/chrome-extension/page-activation.js +120 -0
  46. package/vendor/cli/dist/chrome-extension/page-dialogs.js +125 -0
  47. package/vendor/cli/dist/chrome-extension/page-url.js +11 -0
  48. package/vendor/cli/dist/chrome-extension/panel-session.js +184 -0
  49. package/vendor/cli/dist/chrome-extension/poll-auth.js +85 -0
  50. package/vendor/cli/dist/chrome-extension/poll-backoff.js +22 -0
  51. package/vendor/cli/dist/chrome-extension/run-fence.js +117 -0
  52. package/vendor/cli/dist/chrome-extension/setup-status.js +71 -0
  53. package/vendor/cli/dist/chrome-extension/side-panel-action-click.js +65 -0
  54. package/vendor/cli/dist/chrome-extension/sidepanel-context.js +50 -0
  55. package/vendor/cli/dist/chrome-extension/sidepanel.html +680 -0
  56. package/vendor/cli/dist/chrome-extension/sidepanel.js +1643 -0
  57. package/vendor/cli/dist/chrome-extension/tab-labels.js +233 -0
  58. package/vendor/cli/dist/chrome-extension/tools.js +3354 -0
  59. package/vendor/cli/dist/chrome-extension/watch-observer.js +354 -0
  60. package/vendor/cli/dist/chrome-extension/watch-redact.js +96 -0
  61. package/vendor/cli/dist/chrome-extension/watch.js +348 -0
  62. package/vendor/cli/dist/commands/_lib/apply/desired-state.d.ts +6 -4
  63. package/vendor/cli/dist/commands/_lib/apply/desired-state.js +5 -3
  64. package/vendor/cli/dist/commands/_lib/apply/diff.js +4 -3
  65. package/vendor/cli/dist/commands/_lib/chrome-for-testing.d.ts +13 -0
  66. package/vendor/cli/dist/commands/_lib/chrome-for-testing.js +226 -0
  67. package/vendor/cli/dist/commands/_lib/device-credential.d.ts +34 -0
  68. package/vendor/cli/dist/commands/_lib/device-credential.js +157 -0
  69. package/vendor/cli/dist/commands/_lib/device-wizard.d.ts +17 -0
  70. package/vendor/cli/dist/commands/_lib/device-wizard.js +11 -2
  71. package/vendor/cli/dist/commands/_lib/native-messaging.d.ts +7 -0
  72. package/vendor/cli/dist/commands/_lib/native-messaging.js +40 -0
  73. package/vendor/cli/dist/commands/browser.d.ts +23 -0
  74. package/vendor/cli/dist/commands/browser.js +492 -0
  75. package/vendor/cli/dist/commands/call.d.ts +12 -0
  76. package/vendor/cli/dist/commands/call.js +48 -26
  77. package/vendor/cli/dist/commands/chat.d.ts +0 -12
  78. package/vendor/cli/dist/commands/chat.js +1 -1
  79. package/vendor/cli/dist/commands/context.d.ts +3 -1
  80. package/vendor/cli/dist/commands/context.js +13 -2
  81. package/vendor/cli/dist/commands/daemon.js +38 -171
  82. package/vendor/cli/dist/commands/doctor.d.ts +0 -6
  83. package/vendor/cli/dist/commands/doctor.js +1 -1
  84. package/vendor/cli/dist/commands/memory/_lib/errors.d.ts +4 -1
  85. package/vendor/cli/dist/commands/memory/_lib/errors.js +9 -1
  86. package/vendor/cli/dist/commands/memory/_lib/mcp.d.ts +0 -9
  87. package/vendor/cli/dist/commands/memory/_lib/mcp.js +1 -23
  88. package/vendor/cli/dist/commands/memory/_lib/memory-auth.d.ts +20 -4
  89. package/vendor/cli/dist/commands/memory/_lib/memory-auth.js +21 -17
  90. package/vendor/cli/dist/commands/memory/_lib/seed-cmd.d.ts +0 -8
  91. package/vendor/cli/dist/commands/memory/_lib/seed-cmd.js +7 -18
  92. package/vendor/cli/dist/commands/memory/run.js +4 -25
  93. package/vendor/cli/dist/config/define.d.ts +1 -1
  94. package/vendor/cli/dist/connectors/gchat.ts +31 -1
  95. package/vendor/cli/dist/connectors/google_gmail.ts +70 -41
  96. package/vendor/cli/dist/connectors/google_gmail_references.ts +406 -0
  97. package/vendor/cli/dist/connectors/linkedin-inbox-adapter.js +107 -36
  98. package/vendor/cli/dist/connectors/linkedin-inbox.ts +13 -0
  99. package/vendor/cli/dist/connectors/linkedin.ts +1 -1
  100. package/vendor/cli/dist/connectors/postgres.ts +14 -8
  101. package/vendor/cli/dist/connectors/reddit.ts +171 -5
  102. package/vendor/cli/dist/connectors/whatsapp-web-adapter.js +147 -61
  103. package/vendor/cli/dist/connectors/whatsapp-web-helpers.ts +6 -2
  104. package/vendor/cli/dist/connectors/whatsapp_web.ts +48 -17
  105. package/vendor/cli/dist/connectors/x-dm-adapter.js +252 -35
  106. package/vendor/cli/dist/connectors/x.ts +189 -13
  107. package/vendor/cli/dist/index.js +46 -6
  108. package/vendor/cli/dist/internal/cli-update-check.d.ts +33 -0
  109. package/vendor/cli/dist/internal/cli-update-check.js +98 -0
  110. package/vendor/cli/dist/internal/credentials.js +10 -36
  111. package/vendor/cli/dist/internal/device-state.d.ts +2 -0
  112. package/vendor/cli/dist/internal/device-state.js +4 -0
  113. package/vendor/cli/dist/internal/gateway-url.d.ts +0 -8
  114. package/vendor/cli/dist/internal/gateway-url.js +1 -1
  115. package/vendor/cli/dist/runtime-components.json +4 -4
  116. package/vendor/cli/dist/templates/AGENTS.md.tmpl +3 -1
  117. package/vendor/cli/dist/templates/TESTING.md.tmpl +8 -8
  118. package/vendor/cli/package.json +1 -1
  119. package/vendor/connector-sdk/dist/browser-requirement.js +1 -1
  120. package/vendor/connector-sdk/dist/connector-types.d.ts +34 -1
  121. package/vendor/connector-sdk/dist/index.d.ts +3 -1
  122. package/vendor/connector-sdk/dist/index.js +4 -0
  123. package/vendor/connector-sdk/dist/redact.d.ts +10 -0
  124. package/vendor/{connector-worker/dist/executor → connector-sdk/dist}/redact.js +0 -49
  125. package/vendor/connector-sdk/dist/types.d.ts +2 -1
  126. package/vendor/connector-sdk/package.json +6 -1
  127. package/vendor/connector-worker/dist/agent-turn/gateway-tools.d.ts +9 -0
  128. package/vendor/connector-worker/dist/agent-turn/gateway-tools.js +23 -2
  129. package/vendor/connector-worker/dist/agent-turn/guest-entry.js +14 -6
  130. package/vendor/connector-worker/dist/agent-turn/guest.bundle.js +62 -25
  131. package/vendor/connector-worker/dist/agent-turn/media-tools.d.ts +1 -0
  132. package/vendor/connector-worker/dist/agent-turn/media-tools.js +5 -2
  133. package/vendor/connector-worker/dist/bin.js +2 -0
  134. package/vendor/connector-worker/dist/daemon/acp-adapters/THIRD_PARTY_LICENSES.txt +1 -1
  135. package/vendor/connector-worker/dist/daemon/acp-adapters/claude.js +7339 -2136
  136. package/vendor/connector-worker/dist/daemon/agent-turn.js +52 -17
  137. package/vendor/connector-worker/dist/daemon/automation.js +3 -13
  138. package/vendor/connector-worker/dist/daemon/client.d.ts +23 -3
  139. package/vendor/connector-worker/dist/daemon/client.js +59 -5
  140. package/vendor/connector-worker/dist/daemon/executor.d.ts +0 -28
  141. package/vendor/connector-worker/dist/daemon/executor.js +27 -12
  142. package/vendor/connector-worker/dist/daemon/index.d.ts +1 -1
  143. package/vendor/connector-worker/dist/daemon/index.js +1 -1
  144. package/vendor/connector-worker/dist/daemon/interactive-session.js +29 -6
  145. package/vendor/connector-worker/dist/daemon/poll-loop.js +29 -2
  146. package/vendor/connector-worker/dist/daemon/start.d.ts +0 -1
  147. package/vendor/connector-worker/dist/daemon/start.js +1 -1
  148. package/vendor/connector-worker/dist/daemon/terminal-delivery.d.ts +6 -10
  149. package/vendor/connector-worker/dist/daemon/terminal-delivery.js +59 -23
  150. package/vendor/connector-worker/dist/daemon/terminal-failure.js +2 -2
  151. package/vendor/connector-worker/dist/executor/isolate.js +4 -1
  152. package/vendor/connector-worker/dist/isolate/bridge.d.ts +6 -2
  153. package/vendor/connector-worker/dist/isolate/bridge.js +14 -8
  154. package/vendor/connector-worker/package.json +2 -2
  155. package/vendor/core/dist/agent-tooling.d.ts +8 -0
  156. package/vendor/core/dist/agent-tooling.js +9 -1
  157. package/vendor/core/dist/capabilities.d.ts +1 -1
  158. package/vendor/core/dist/capabilities.js +5 -0
  159. package/vendor/core/dist/connector-query-errors.d.ts +6 -0
  160. package/vendor/core/dist/connector-query-errors.js +4 -0
  161. package/vendor/core/dist/contracts/entity-reference.d.ts +3 -0
  162. package/vendor/core/dist/contracts/entity-reference.js +31 -0
  163. package/vendor/core/dist/contracts/tools/manage-automations.d.ts +3 -0
  164. package/vendor/core/dist/contracts/tools/manage-automations.js +4 -1
  165. package/vendor/core/dist/contracts/tools/manage-connections.js +1 -1
  166. package/vendor/core/dist/contracts/tools/manage-entity-schema.js +2 -2
  167. package/vendor/core/dist/contracts/tools/manage-entity.d.ts +117 -34
  168. package/vendor/core/dist/contracts/tools/manage-entity.js +47 -14
  169. package/vendor/core/dist/contracts/tools/manage-operations.d.ts +13 -4
  170. package/vendor/core/dist/contracts/tools/manage-operations.js +19 -7
  171. package/vendor/core/dist/contracts/tools/read-knowledge.d.ts +6 -1
  172. package/vendor/core/dist/contracts/tools/read-knowledge.js +20 -1
  173. package/vendor/core/dist/contracts/tools/view-attach.d.ts +1 -1
  174. package/vendor/core/dist/contracts/tools/view-runtime.d.ts +2 -0
  175. package/vendor/core/dist/contracts/tools/view-runtime.js +3 -1
  176. package/vendor/core/dist/contracts/worker/device-automation.d.ts +4 -9
  177. package/vendor/core/dist/contracts/worker/device-automation.js +10 -15
  178. package/vendor/core/dist/contracts/worker/protocol.d.ts +20 -0
  179. package/vendor/core/dist/contracts/worker/protocol.js +20 -0
  180. package/vendor/core/dist/errors.d.ts +0 -20
  181. package/vendor/core/dist/errors.js +1 -25
  182. package/vendor/core/dist/otel.js +38 -10
  183. package/vendor/core/dist/reserved.d.ts +6 -3
  184. package/vendor/core/dist/reserved.js +6 -3
  185. package/vendor/core/dist/utils/ajv.js +3 -1
  186. package/vendor/core/dist/worker/auth.d.ts +3 -2
  187. package/vendor/core/package.json +31 -5
  188. package/vendor/postgres/cf/src/query.js +3 -1
  189. package/vendor/postgres/cjs/src/query.js +3 -1
  190. package/vendor/postgres/src/query.js +3 -1
  191. package/vendor/connector-worker/dist/executor/http-status.d.ts +0 -16
  192. package/vendor/connector-worker/dist/executor/http-status.js +0 -21
  193. package/vendor/connector-worker/dist/executor/redact.d.ts +0 -29
  194. /package/vendor/postgres/{.bun-tag-2f292c6554a8475e → .bun-tag-22d644c2873790db} +0 -0
@@ -0,0 +1,3354 @@
1
+ // Per-tool implementations for the chrome connector's action surface.
2
+ // Each tool returns a uniform shape: { ok, observation, error?, … }.
3
+ // The dispatcher in background.js routes by action_key into one of these
4
+ // and posts the result back to the gateway.
5
+ //
6
+ // Lifecycle invariants:
7
+ // - chrome.debugger.attach is wrapped in attachTab() with a per-tab lock
8
+ // so two runs targeting the same tab can't race the debugger state.
9
+ // - Every tool that needs CDP MUST run under withDebugger() so detach
10
+ // is guaranteed even on throw.
11
+ // - Tabs the extension opens carry an agent label (tab-labels.js). Any agent
12
+ // may drive a labelled tab; an unlabelled tab is the user's, readable by
13
+ // everyone but mutable only with a grant (see enforceTabMutable).
14
+ // - Agents close their own tabs. The only timer close is an expired source
15
+ // recovery's own scrape-owned target (browser-recovery.js).
16
+
17
+ import { assertRecoveryTab, recoveryTabIds } from "./browser-recovery.js";
18
+
19
+ // Shared debugger lease — refcounted attach/detach so action tools (via
20
+ // withDebugger) and the long-lived network-intercept primitive can hold
21
+ // the same chrome.debugger session on a tab without racing. See
22
+ // debugger-lease.js for the lifecycle invariants.
23
+ import {
24
+ DEBUGGER_IDLE_DETACH_MS,
25
+ acquireDebuggerLease,
26
+ debuggerDetachGeneration,
27
+ debuggerDetachReason,
28
+ prepareDiscardedTab,
29
+ releaseDebuggerLease,
30
+ } from "./debugger-lease.js";
31
+ import {
32
+ dialogInterruption,
33
+ openDialog,
34
+ whenDialogCloses,
35
+ whenDialogOpens,
36
+ } from "./page-dialogs.js";
37
+ import { normalizePageUrl } from "./page-url.js";
38
+ import { browserUrlAllowed } from "./browser-origin-policy.js";
39
+ import { focusChromeTab } from "./focus-tab.js";
40
+ import { TABS_MANAGE_SCOPE, isActionGrantEnabled } from "./config.js";
41
+ import {
42
+ sanitizeBrowserRecord,
43
+ sanitizeBrowserText,
44
+ } from "./browser-url-sanitizer.js";
45
+ import { feedListenerTabIds, listenToFeed } from "./feed-listener.js";
46
+ import {
47
+ actorFromRunCtx,
48
+ agentLabelFor,
49
+ effectiveLabel,
50
+ forgetTabLabel,
51
+ joinGroup,
52
+ labelTab,
53
+ noteTaskSite,
54
+ readTabLabels,
55
+ siteKeyFor,
56
+ tabIsOnSite,
57
+ touchTabLabel,
58
+ withKeyLock,
59
+ } from "./tab-labels.js";
60
+ import { NETWORK_INTERCEPT_TOOLS } from "./network-intercept.js";
61
+ import { CONSOLE_CAPTURE_TOOLS } from "./console-capture.js";
62
+
63
+ const TAB_LOCKS = new Map(); // tabId → Promise chain
64
+ const NOTIFICATION_TARGETS_KEY = "owletto.notification_targets";
65
+
66
+ /**
67
+ * Identity of a *page* for reuse decisions: origin + pathname.
68
+ *
69
+ * Query strings and hashes are deliberately ignored so a differing `?to=` or
70
+ * `#section` does not force a needless reload. Returns "" for anything
71
+ * unparseable (about:blank, chrome-error://…), which never equals a real
72
+ * target and therefore always falls through to navigating.
73
+ */
74
+ function navigationPageKey(candidate) {
75
+ try {
76
+ const parsed = new URL(candidate);
77
+ return parsed.origin + parsed.pathname;
78
+ } catch {
79
+ return "";
80
+ }
81
+ }
82
+
83
+ /**
84
+ * The site's warm tab: one long-lived tab per site for connectors whose page
85
+ * state is expensive to rebuild (WhatsApp hydration, a logged-in bank session).
86
+ *
87
+ * Rediscover before creating, so a restart or an evicted label never yields a
88
+ * second copy: first a labelled warm tab still on the site, then any unlabelled
89
+ * tab already on the site (one Chrome restored after a restart), and only then
90
+ * a new tab. The tab the user is looking at is never adopted. Callers hold the
91
+ * site lock.
92
+ */
93
+ async function findOrCreateWarmTab(chromeApi, site, runCtx, focused) {
94
+ const labels = await readTabLabels();
95
+ for (const [id, label] of Object.entries(labels)) {
96
+ if (label?.kind !== "warm" || label.site !== site) continue;
97
+ const tab = await chromeApi.tabs.get(Number(id)).catch(() => null);
98
+ if (effectiveLabel(label, tab)) {
99
+ await touchTabLabel(tab.id, runCtx);
100
+ return await warmUp(chromeApi, tab, focused, true);
101
+ }
102
+ // Gone, or the user took it to another site: it is theirs now.
103
+ await forgetTabLabel(Number(id));
104
+ }
105
+ const [inUse] = await chromeApi.tabs.query({
106
+ active: true,
107
+ lastFocusedWindow: true,
108
+ });
109
+ const open = await chromeApi.tabs.query({});
110
+ const restored = open.find(
111
+ (tab) =>
112
+ tab.id !== inUse?.id &&
113
+ !labels[String(tab.id)] &&
114
+ tabIsOnSite(tab, site),
115
+ );
116
+ if (restored) {
117
+ await labelTab(restored.id, runCtx, { kind: "warm", site });
118
+ return await warmUp(chromeApi, restored, focused, true);
119
+ }
120
+ return await createWarmTab(chromeApi, site, runCtx, focused);
121
+ }
122
+
123
+ async function createWarmTab(chromeApi, site, runCtx, focused) {
124
+ const created = await chromeApi.tabs.create({
125
+ url: "about:blank",
126
+ active: focused === true,
127
+ });
128
+ if (created?.id == null)
129
+ throw new Error("navigate: failed to create the site's warm tab");
130
+ await labelTab(created.id, runCtx, { kind: "warm", site });
131
+ return await warmUp(chromeApi, created, false, false);
132
+ }
133
+
134
+ // Chrome's Memory Saver would otherwise discard a warm tab and throw away the
135
+ // very page state it exists to keep.
136
+ async function warmUp(chromeApi, tab, focused, reused) {
137
+ await chromeApi.tabs.update(tab.id, { autoDiscardable: false });
138
+ if (focused && tab.windowId != null) {
139
+ await chromeApi.windows
140
+ .update(tab.windowId, { focused: true, drawAttention: true })
141
+ .catch(() => {});
142
+ }
143
+ return { tabId: tab.id, reused };
144
+ }
145
+
146
+ /**
147
+ * A labelled task tab to reuse for `site`: this session's most recent one,
148
+ * else another session's (reported as busy_by so the caller knows it took a
149
+ * tab someone else was using). Warm tabs, tabs a feed listener is bound to and
150
+ * the tab the user is looking at are never reused generically. Callers hold
151
+ * the site lock.
152
+ */
153
+ async function selectTaskTab(chromeApi, site, runCtx) {
154
+ const session = actorFromRunCtx(runCtx).session;
155
+ const bound = await feedListenerTabIds();
156
+ const [inUse] = await chromeApi.tabs.query({
157
+ active: true,
158
+ lastFocusedWindow: true,
159
+ });
160
+ if (inUse?.id != null) bound.add(inUse.id);
161
+ // A source read's recovery tab is fenced to its own recovery.
162
+ for (const tabId of await recoveryTabIds(chromeApi)) bound.add(tabId);
163
+ const candidates = [];
164
+ for (const [id, label] of Object.entries(await readTabLabels())) {
165
+ const tabId = Number(id);
166
+ if (label?.kind !== "task" || label.site !== site || bound.has(tabId))
167
+ continue;
168
+ const tab = await chromeApi.tabs.get(tabId).catch(() => null);
169
+ // A just-created tab is still on about:blank until its navigate lands.
170
+ if (!tab || (!tabIsOnSite(tab, site) && (tab.pendingUrl || tab.url) !== "about:blank"))
171
+ continue;
172
+ candidates.push({ tabId, label });
173
+ }
174
+ candidates.sort(
175
+ (a, b) => (b.label.last_used_at ?? 0) - (a.label.last_used_at ?? 0),
176
+ );
177
+ const own =
178
+ session != null &&
179
+ candidates.find((c) => c.label.last_used_by?.session === session);
180
+ if (own) return { tabId: own.tabId, busyBy: null };
181
+ const other = candidates[0];
182
+ if (!other) return null;
183
+ const by = other.label.last_used_by ?? other.label.opened_by ?? {};
184
+ return {
185
+ tabId: other.tabId,
186
+ busyBy: {
187
+ agent: by.agent ?? null,
188
+ session: by.session ?? null,
189
+ last_used_at: other.label.last_used_at ?? null,
190
+ },
191
+ };
192
+ }
193
+
194
+ /**
195
+ * True when a chrome.debugger / tab failure means the TARGET TAB is stale or
196
+ * detached — the tab id is dead, the debugger was ripped away mid-command, or
197
+ * the target now belongs to a different extension context.
198
+ */
199
+ function isStaleDebuggerTargetError(error) {
200
+ const message = error instanceof Error ? error.message : String(error);
201
+ return /Cannot access a chrome-extension:\/\/ URL of different extension|Detached while handling command|No tab with (?:given )?id|Target page, context or browser has been closed/i.test(
202
+ message,
203
+ );
204
+ }
205
+
206
+ // chrome.debugger uses { tabId } as the target identifier throughout.
207
+ function dbgTarget(tabId) {
208
+ return { tabId };
209
+ }
210
+
211
+ // Queue per-tab ops so concurrent runs on the same tab serialize.
212
+ function withTabLock(tabId, fn) {
213
+ const prev = TAB_LOCKS.get(tabId) ?? Promise.resolve();
214
+ const next = prev.then(
215
+ () => fn(),
216
+ () => fn(),
217
+ );
218
+ // Make sure a thrown fn doesn't poison the queue forever.
219
+ const tail = next.catch(() => {});
220
+ TAB_LOCKS.set(tabId, tail);
221
+ return next;
222
+ }
223
+
224
+ // Attach (or reuse the tab's idle attachment), run, release. Other
225
+ // extensions / a user opening DevTools can still detach us mid-run; the
226
+ // failure then names that (explainDetach).
227
+ //
228
+ // While attached, a JS dialog (alert/confirm/prompt/beforeunload) blocks the
229
+ // page until the debugger answers it. Nothing answers on the agent's behalf:
230
+ // page-dialogs.js records it, the interrupted action reports it, and
231
+ // handle_dialog answers it.
232
+ // Cap the CDP setup commands. A tab that is still loading (a stalled reload)
233
+ // or otherwise unresponsive can leave Page.enable unanswered, and the tab lock
234
+ // would then never free.
235
+ const CDP_SETUP_TIMEOUT_MS = 15_000;
236
+ async function enableDomains(chromeApi, tabId) {
237
+ const setup = (async () => {
238
+ await chromeApi.debugger.sendCommand(dbgTarget(tabId), "Page.enable");
239
+ await chromeApi.debugger.sendCommand(dbgTarget(tabId), "Runtime.enable");
240
+ })();
241
+ setup.catch(() => {});
242
+ let timer;
243
+ try {
244
+ await Promise.race([
245
+ setup,
246
+ new Promise((_, reject) => {
247
+ timer = setTimeout(
248
+ () =>
249
+ reject(
250
+ new Error(
251
+ `tab ${tabId} did not answer the debugger within ${CDP_SETUP_TIMEOUT_MS}ms`,
252
+ ),
253
+ ),
254
+ CDP_SETUP_TIMEOUT_MS,
255
+ );
256
+ }),
257
+ ]);
258
+ } finally {
259
+ clearTimeout(timer);
260
+ }
261
+ }
262
+
263
+ // `authorize` holds the caller's checks on the tab (allowed origins, who may
264
+ // act on it). It runs inside the tab lock so the page it judges is the one the
265
+ // action sees: an earlier action queued on this tab may have navigated or
266
+ // reloaded it in the meantime.
267
+ export async function withDebugger(chromeApi, tabId, fn, authorize = null) {
268
+ // A dialog left open on this tab blocks the page: report it instead of
269
+ // queueing behind the action it interrupted.
270
+ // The caller's checks still apply: a dialog's text is the page's content.
271
+ const pending = openDialog(tabId);
272
+ if (pending) {
273
+ if (authorize) await authorize();
274
+ return dialogInterruption(tabId, pending);
275
+ }
276
+ let interrupted;
277
+ const onDialog = new Promise((resolve) => {
278
+ interrupted = resolve;
279
+ });
280
+ const locked = withTabLock(tabId, async () => {
281
+ if (authorize) await authorize();
282
+ // A dialog the action opens freezes the page, so whatever the action is
283
+ // waiting on in it never answers. The caller gets the dialog now; the
284
+ // action keeps the tab lock (and the attachment) until the dialog is
285
+ // answered or handed to the user, so nothing else runs against the
286
+ // frozen page.
287
+ const dialog = whenDialogOpens(tabId);
288
+ // One may have opened while this call waited for the lock (an earlier
289
+ // action's page opened it after that action returned).
290
+ const queuedBehind = openDialog(tabId);
291
+ if (queuedBehind) {
292
+ dialog.cancel();
293
+ return dialogInterruption(tabId, queuedBehind);
294
+ }
295
+ void dialog.promise.then((opened) => interrupted(dialogInterruption(tabId, opened)));
296
+ let lease;
297
+ try {
298
+ await prepareDiscardedTab(chromeApi, tabId, authorize);
299
+ lease = await acquireDebuggerLease(chromeApi, tabId);
300
+ } catch (error) {
301
+ dialog.cancel();
302
+ throw error;
303
+ }
304
+ try {
305
+ // Page + Runtime are needed by almost every tool; enable them once.
306
+ await enableDomains(chromeApi, tabId);
307
+ return await fn();
308
+ } catch (error) {
309
+ throw explainDetach(error, tabId, lease);
310
+ } finally {
311
+ dialog.cancel();
312
+ // Release with the lease TOKEN: if an external detach reset this tab's
313
+ // refcount mid-action, our token's generation is stale and release is a
314
+ // no-op, so we don't detach a lease a concurrent capture session may
315
+ // have freshly acquired. The attachment idles briefly for the agent's
316
+ // next call on this tab instead of detaching at once.
317
+ await releaseDebuggerLease(chromeApi, lease, {
318
+ idleDetachMs: DEBUGGER_IDLE_DETACH_MS,
319
+ });
320
+ }
321
+ });
322
+ return Promise.race([locked, onDialog]);
323
+ }
324
+
325
+ // A command failed because Chrome took the debugger away mid-action (the user
326
+ // dismissed the debugging bar, DevTools claimed the tab, the tab closed). The
327
+ // raw CDP error ("Detached while handling command") hides that, and hides that
328
+ // the action may already have taken effect. The original text stays in the
329
+ // message so callers that classify stale targets still recognise it.
330
+ function explainDetach(error, tabId, lease) {
331
+ if (lease.generation === debuggerDetachGeneration(tabId)) return error;
332
+ const reason = debuggerDetachReason(tabId);
333
+ const why =
334
+ reason === "canceled_by_user"
335
+ ? "the user dismissed Chrome's debugging bar"
336
+ : reason === "dialog_handed_to_user"
337
+ ? "a JS dialog went unanswered and was handed to the user"
338
+ : `Chrome detached the debugger (${reason ?? "unknown"})`;
339
+ const original = error instanceof Error ? error.message : String(error);
340
+ const explained = new Error(
341
+ `tab ${tabId}: ${why} during the action, so it may or may not have taken effect: ${original}`,
342
+ );
343
+ explained.cause = error;
344
+ return explained;
345
+ }
346
+
347
+ // Events can precede Page.navigate's reply. Anchor buffered commits to its
348
+ // returned loader, then follow main-frame commits through client-side redirects.
349
+ // Iframe loads and a previous document's buffered commit cannot complete it.
350
+ function navigationLoad(chromeApi, tabId) {
351
+ let frameId;
352
+ let expected;
353
+ let settle;
354
+ const seen = new Set();
355
+ const commits = [];
356
+ const promise = new Promise(resolve => { settle = resolve; });
357
+ const identity = event => JSON.stringify([event.frameId, event.loaderId]);
358
+ const listener = (source, method, event) => {
359
+ if (source.tabId !== tabId) return;
360
+ if (method === "Page.frameNavigated" && !event.frame.parentId) {
361
+ const commit = { frameId: event.frame.id, loaderId: event.frame.loaderId };
362
+ if (frameId === commit.frameId) {
363
+ expected = identity(commit);
364
+ if (seen.has(expected)) settle(true);
365
+ } else if (frameId === undefined && commits.length < 256) commits.push(commit);
366
+ return;
367
+ }
368
+ if (method !== "Page.lifecycleEvent" || event.name !== "load") return;
369
+ const key = identity(event);
370
+ if (key === expected) settle(true);
371
+ else if (seen.size < 256) seen.add(key);
372
+ };
373
+ const timer = setTimeout(() => settle(false), 15_000);
374
+ chromeApi.debugger.onEvent.addListener(listener);
375
+ return {
376
+ wait(navigation) {
377
+ // Same-document navigation does not create a loader or emit load.
378
+ if (!navigation.loaderId) return Promise.resolve(true);
379
+ frameId = navigation.frameId;
380
+ expected = identity(navigation);
381
+ const anchor = commits.findIndex(commit => identity(commit) === expected);
382
+ if (anchor >= 0) for (const commit of commits.slice(anchor)) {
383
+ if (commit.frameId === frameId) expected = identity(commit);
384
+ }
385
+ if (seen.has(expected)) settle(true);
386
+ return promise;
387
+ },
388
+ cancel() {
389
+ chromeApi.debugger.onEvent.removeListener(listener);
390
+ clearTimeout(timer);
391
+ settle(false);
392
+ },
393
+ };
394
+ }
395
+
396
+ // Cap a single in-page evaluation, well under the run fence.
397
+ //
398
+ // `awaitPromise` resolves only when the page's promise settles, and a page can
399
+ // block forever without throwing: WhatsApp Web's `require()` blocks while its
400
+ // module graph is still registering, so a readiness probe measured 95.2s in
401
+ // prod and the run fence killed it with `run timed out after 90000ms` -- a
402
+ // message the connector cannot classify, so a transient hydration stall was
403
+ // booked as a hard failure.
404
+ //
405
+ // This is CDP's own `Runtime.evaluate` timeout, so the evaluation is abandoned
406
+ // by the DevTools backend and returns an ordinary error here. That matters: the
407
+ // connector must never race a dispatch against a local timer, because an
408
+ // abandoned dispatch orphans its reply and once killed a worker pod (#3288).
409
+ // Bounding it at the CDP layer keeps exactly one reply per request.
410
+ const EVAL_TIMEOUT_MS = 30_000;
411
+
412
+ // CDP's `timeout` above bounds only synchronous execution, not the wait for an
413
+ // awaited promise: prod evaluates ran 34-90s with it set. On 2026-09-29 one
414
+ // promise never settled, its evaluate held withTabLock, and every later run on
415
+ // that tab queued behind it until the run fence, for three days. So a promise
416
+ // result is raced against a deadline inside the page itself: CDP still sends
417
+ // exactly one reply, and nothing is detached or abandoned. One budget covers
418
+ // both phases; it sits below the 90s run fence and above the WhatsApp
419
+ // connector's 60s collect budget. A page that replaces its own `setTimeout`
420
+ // or `Promise` can still defeat it, as it could defeat any in-page code.
421
+ const EVAL_AWAIT_TIMEOUT_MS = 80_000;
422
+
423
+ // Run an expression in the page's main world and return the JSON-serialised
424
+ // result. Throws on exception; caller catches to translate to a tool error.
425
+ async function evalInPage(chromeApi, tabId, expression, awaitPromise = true) {
426
+ const send = (method, params) =>
427
+ chromeApi.debugger.sendCommand(dbgTarget(tabId), method, params);
428
+ const startedAt = Date.now();
429
+ let result = await send("Runtime.evaluate", {
430
+ expression,
431
+ awaitPromise: false,
432
+ returnByValue: !awaitPromise,
433
+ userGesture: true,
434
+ timeout: EVAL_TIMEOUT_MS,
435
+ });
436
+ const handle = result?.result;
437
+ if (awaitPromise && !result?.exceptionDetails && handle?.objectId) {
438
+ const waitMs = Math.max(0, EVAL_AWAIT_TIMEOUT_MS - (Date.now() - startedAt));
439
+ // Only a promise needs the page's timer; anything else is read back as is.
440
+ const functionDeclaration =
441
+ handle.subtype === "promise"
442
+ ? `function () {
443
+ "use strict";
444
+ let timer;
445
+ const expired = new Promise((_, reject) => {
446
+ timer = setTimeout(() => reject(new Error("evaluate_timeout: page did not settle within ${waitMs}ms")), ${waitMs});
447
+ });
448
+ return Promise.race([this, expired]).finally(() => clearTimeout(timer));
449
+ }`
450
+ : 'function () { "use strict"; return this; }';
451
+ try {
452
+ result = await send("Runtime.callFunctionOn", {
453
+ objectId: handle.objectId,
454
+ functionDeclaration,
455
+ awaitPromise: true,
456
+ returnByValue: true,
457
+ });
458
+ } finally {
459
+ void send("Runtime.releaseObject", { objectId: handle.objectId }).catch(() => {});
460
+ }
461
+ }
462
+ if (result?.exceptionDetails) {
463
+ const e = result.exceptionDetails;
464
+ const msg = e?.exception?.description ?? e?.text ?? "evaluation failed";
465
+ const err = new Error(msg);
466
+ err.exceptionDetails = e;
467
+ throw err;
468
+ }
469
+ return result?.result?.value;
470
+ }
471
+
472
+ // Resolve once the tab finishes loading (chrome.tabs status === "complete").
473
+ // Used by the cs_scrape path, which loads pages without attaching the debugger.
474
+ function waitForTabComplete(chromeApi, tabId, timeoutMs = 20000) {
475
+ return new Promise((resolve) => {
476
+ let done = false;
477
+ const finish = (v) => {
478
+ if (done) return;
479
+ done = true;
480
+ try {
481
+ chromeApi.tabs.onUpdated.removeListener(listener);
482
+ } catch {}
483
+ resolve(v);
484
+ };
485
+ const listener = (id, info) => {
486
+ if (id === tabId && info.status === "complete") finish(true);
487
+ };
488
+ chromeApi.tabs.onUpdated.addListener(listener);
489
+ chromeApi.tabs
490
+ .get(tabId)
491
+ .then((t) => {
492
+ if (t?.status === "complete") finish(true);
493
+ })
494
+ .catch(() => {});
495
+ if (timeoutMs > 0) setTimeout(() => finish(false), timeoutMs);
496
+ else finish(true);
497
+ });
498
+ }
499
+
500
+ // Generic, config-driven in-page scraper. Injected via chrome.scripting
501
+ // (NO chrome.debugger) so visibility-gated feeds render like a real user tab.
502
+ // ALL site-specific knowledge — selectors, click targets, id derivation,
503
+ // scroll/auth-wall rules — comes from the connector via `cfg`. This function
504
+ // contains NO platform knowledge and names no site. MUST be fully
505
+ // self-contained (serialized + injected; no outer references).
506
+ //
507
+ // cfg shape:
508
+ // clickBefore?: { textEquals, waitForSelector?, maxWaitMs? } // e.g. a "See all" link
509
+ // expandRows?: { rowSelector, identity?, expected, items, open?, sort?, more?,
510
+ // maxPasses?, maxDurationMs?, stall?, waitMs?, outputField? }
511
+ // // expands repeated row-local content and records explicit
512
+ // // expected/collected completeness on each harvested row
513
+ // // identity: durable row-local provenance that must remain
514
+ // // stable on the exact DOM row; { selector?,
515
+ // // take?:"text"|"attr", attr?, regex?, regexFlags?, group? }.
516
+ // // Evidence is never merged into another DOM row snapshot.
517
+ // group?: { selector, rowSelector, labelFromFirstLine? } // day/section grouping
518
+ // rowSelector?: string // used when no group
519
+ // fields?: { [name]: { selector?, closestSelector?, take?:"text"|"attr"|"html"|"objectAll"|"clipboardAction", attr?, firstLine?, const?, parts? } }
520
+ // // objectAll: emit one object PER match, built from `parts`
521
+ // // parts: { [key]: { take:"attr"|"text"|"aria"|"alt", attr? } }
522
+ // // (aria = own/descendant aria-label; alt = descendant img[alt])
523
+ // // clipboardAction: retained as a compatibility token, but
524
+ // // deliberately returns "" without clicking. Page code can
525
+ // // retain native clipboard callables before injection, so a
526
+ // // late interceptor cannot prove non-mutation. Connectors must
527
+ // // extract a durable DOM identity or link instead.
528
+ // id?: { source:"attr"|"field", name?|name[]?, field?, regex?, group? }
529
+ // requireFields?: string[] // drop rows missing these
530
+ // // an empty array from an objectAll field counts as missing
531
+ // scroll?: { max?, stall?, waitMs?, deep? }
532
+ // loggedOutWhen?: { pathRegex?, hostRegex? }
533
+ // Exported for unit tests. This function is serialized into the page by
534
+ // chrome.scripting.executeScript (`func: genericScrape`), which stringifies the
535
+ // body — so it must stay self-contained and must not reference module scope.
536
+ export async function genericScrape(cfg) {
537
+ cfg = cfg || {};
538
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
539
+ const clean = (s) => (s || "").replace(/\s+/g, " ").trim();
540
+ const reTest = (pat, s, flags) => {
541
+ try {
542
+ return pat ? new RegExp(pat, flags).test(s) : false;
543
+ } catch {
544
+ return false;
545
+ }
546
+ };
547
+
548
+ const cb = cfg.clickBefore;
549
+ let clickedBefore = false;
550
+ if (cb && cb.textEquals) {
551
+ const want = String(cb.textEquals).toLowerCase();
552
+ const el = [
553
+ ...document.querySelectorAll('a, button, [role="button"], [role="link"]'),
554
+ ].find((e) => clean(e.innerText).toLowerCase() === want);
555
+ if (el) {
556
+ el.click();
557
+ clickedBefore = true;
558
+ const deadline = Date.now() + (cb.maxWaitMs || 6000);
559
+ while (Date.now() < deadline) {
560
+ await sleep(400);
561
+ if (cb.waitForSelector && document.querySelector(cb.waitForSelector))
562
+ break;
563
+ }
564
+ }
565
+ }
566
+
567
+ // Expand repeated content inside each currently-rendered row before it is
568
+ // harvested. Selectors and labels remain connector-owned; this engine only
569
+ // provides generic click-until-complete mechanics. Coverage is attached to
570
+ // the corresponding harvested row so callers never have to infer that a
571
+ // thread is complete merely because no more controls happened to be visible.
572
+ const expansionByRow = new WeakMap();
573
+ const expansionIdentityByRow = new WeakMap();
574
+ const expansionProofSignatureByCoverage = new WeakMap();
575
+ const expansionControlClicksByCoverage = new WeakMap();
576
+ const expansionHasUnresolvedControlsByCoverage = new WeakMap();
577
+ const unstableHarvestRows = new WeakSet();
578
+ const expandCfg = cfg.expandRows;
579
+ const expansionStartedAt = Date.now();
580
+ const expansionDurationMs = Math.max(
581
+ 1,
582
+ Number(expandCfg?.maxDurationMs ?? 60_000) || 60_000,
583
+ );
584
+ const expansionDeadline = expansionStartedAt + expansionDurationMs;
585
+ let expansionTimedOut = false;
586
+ const expansionDeadlineReached = () => {
587
+ if (!expandCfg || Date.now() < expansionDeadline) return false;
588
+ expansionTimedOut = true;
589
+ return true;
590
+ };
591
+ const elementTexts = (el) => {
592
+ const visible = clean(el?.innerText || el?.textContent);
593
+ const aria = clean(el?.getAttribute?.("aria-label"));
594
+ return aria && aria !== visible
595
+ ? [visible, aria].filter(Boolean)
596
+ : [visible || aria].filter(Boolean);
597
+ };
598
+ const matchingElements = (scope, selector, textRegex, textRegexFlags) => {
599
+ if (!scope || !selector) return [];
600
+ return [...scope.querySelectorAll(selector)].filter((el) =>
601
+ textRegex
602
+ ? elementTexts(el).some((value) =>
603
+ reTest(textRegex, value, textRegexFlags),
604
+ )
605
+ : true,
606
+ );
607
+ };
608
+ const belongsToExpansionRow = (el, rowEl) => {
609
+ if (!el || !rowEl || !expandCfg?.rowSelector) return true;
610
+ const owner = el.closest?.(expandCfg.rowSelector);
611
+ return owner === rowEl;
612
+ };
613
+ const belongsToConfiguredGroup = (el, rowEl) => {
614
+ const groupSelector = cfg.group?.selector;
615
+ if (!groupSelector) return true;
616
+ const rowGroup = rowEl?.closest?.(groupSelector);
617
+ return !!rowGroup && el?.closest?.(groupSelector) === rowGroup;
618
+ };
619
+ const belongsToHarvestRow = (el, rowEl) => {
620
+ if (!el || !rowEl) return true;
621
+ if (!belongsToConfiguredGroup(el, rowEl)) return false;
622
+ const rowSelector = cfg.group?.rowSelector || cfg.rowSelector;
623
+ if (!rowSelector) return true;
624
+ const owner = el.closest?.(rowSelector);
625
+ return owner === rowEl;
626
+ };
627
+ const collectedItemOwner = (el, selector) =>
628
+ el.matches?.(selector)
629
+ ? el.parentElement?.closest?.(selector)
630
+ : el.closest?.(selector);
631
+ const belongsToCollectedItems = (el, rowEl) => {
632
+ if (!el || !rowEl || !belongsToConfiguredGroup(el, rowEl)) return false;
633
+ // An item may itself be a harvested row (for example, a comment under a
634
+ // post). In that case its owner is the nearest harvested ancestor above it.
635
+ // Descendants of a nested harvested row belong to that nested row instead.
636
+ const selectors = [
637
+ expandCfg?.rowSelector,
638
+ cfg.group?.rowSelector || cfg.rowSelector,
639
+ ].filter(Boolean);
640
+ return selectors.every(
641
+ (selector) => collectedItemOwner(el, selector) === rowEl,
642
+ );
643
+ };
644
+ const ownedMatchingElements = (rowEl, selector, textRegex, textRegexFlags) =>
645
+ matchingElements(rowEl, selector, textRegex, textRegexFlags).filter(
646
+ (el) =>
647
+ belongsToExpansionRow(el, rowEl) && belongsToHarvestRow(el, rowEl),
648
+ );
649
+ const isRenderedThrough = (el, boundary) => {
650
+ if (!el?.isConnected || !boundary) return false;
651
+ for (let current = el; current; current = current.parentElement) {
652
+ if (current.hidden) return false;
653
+ const style = globalThis.getComputedStyle?.(current);
654
+ if (
655
+ style?.display === "none" ||
656
+ style?.visibility === "hidden" ||
657
+ style?.visibility === "collapse" ||
658
+ style?.contentVisibility === "hidden"
659
+ )
660
+ return false;
661
+ if (current === boundary) return true;
662
+ }
663
+ return false;
664
+ };
665
+ const isRenderedInDocument = (el) =>
666
+ isRenderedThrough(el, document.documentElement);
667
+ const isRenderedInRow = (el, rowEl) =>
668
+ isRenderedThrough(el, rowEl) && isRenderedInDocument(rowEl);
669
+ const visibleOwnedMatchingElements = (
670
+ rowEl,
671
+ selector,
672
+ textRegex,
673
+ textRegexFlags,
674
+ ) =>
675
+ ownedMatchingElements(rowEl, selector, textRegex, textRegexFlags).filter(
676
+ (el) => isRenderedInRow(el, rowEl),
677
+ );
678
+ const isVisibleOwnedMatchingElement = (
679
+ el,
680
+ rowEl,
681
+ selector,
682
+ textRegex,
683
+ textRegexFlags,
684
+ ) =>
685
+ !!el &&
686
+ !!rowEl &&
687
+ !!selector &&
688
+ !!el.matches?.(selector) &&
689
+ belongsToExpansionRow(el, rowEl) &&
690
+ belongsToHarvestRow(el, rowEl) &&
691
+ isRenderedInRow(el, rowEl) &&
692
+ (!textRegex ||
693
+ elementTexts(el).some((value) =>
694
+ reTest(textRegex, value, textRegexFlags),
695
+ ));
696
+ const expansionIdentity = (rowEl) => {
697
+ const spec = expandCfg?.identity;
698
+ if (!rowEl || !spec) return "";
699
+ const target = spec.selector
700
+ ? [...rowEl.querySelectorAll(spec.selector)].find(
701
+ (el) =>
702
+ belongsToExpansionRow(el, rowEl) && belongsToHarvestRow(el, rowEl),
703
+ )
704
+ : rowEl;
705
+ if (!target) return "";
706
+ let value =
707
+ spec.take === "attr"
708
+ ? target.getAttribute(spec.attr) || ""
709
+ : clean(target.innerText || target.textContent);
710
+ if (spec.regex && value) {
711
+ try {
712
+ const match = value.match(new RegExp(spec.regex, spec.regexFlags));
713
+ value = match ? (match[spec.group ?? 1] ?? match[0]) : "";
714
+ } catch {
715
+ return "";
716
+ }
717
+ }
718
+ return clean(value);
719
+ };
720
+ const hasUniqueExpansionIdentity = (rowEl, identity) => {
721
+ if (!expandCfg?.identity) return true;
722
+ if (!identity) return false;
723
+ const groupSelector = cfg.group?.selector;
724
+ const activeGroup = groupSelector ? rowEl.closest(groupSelector) : null;
725
+ const owners = [...document.querySelectorAll(expandCfg.rowSelector)].filter(
726
+ (candidate) =>
727
+ !unstableHarvestRows.has(candidate) &&
728
+ expansionIdentity(candidate) === identity &&
729
+ (!groupSelector || candidate.closest(groupSelector) === activeGroup),
730
+ );
731
+ return owners.length === 1 && owners[0] === rowEl;
732
+ };
733
+ const compactCount = (raw) => {
734
+ const match = clean(raw).match(/(\d[\d,.]*)(?:\s*([kmb]))?/i);
735
+ if (!match) return 0;
736
+ const base = Number(match[1].replace(/,/g, ""));
737
+ if (!Number.isFinite(base)) return 0;
738
+ const suffix = match[2]?.toLowerCase();
739
+ const multiplier =
740
+ suffix === "b"
741
+ ? 1_000_000_000
742
+ : suffix === "m"
743
+ ? 1_000_000
744
+ : suffix === "k"
745
+ ? 1_000
746
+ : 1;
747
+ return Math.round(base * multiplier);
748
+ };
749
+ const expectedRowItems = (rowEl, spec) => {
750
+ if (!spec?.selector) return 0;
751
+ const elements = visibleOwnedMatchingElements(
752
+ rowEl,
753
+ spec.selector,
754
+ spec.textRegex,
755
+ spec.textRegexFlags,
756
+ );
757
+ let maximum = 0;
758
+ for (const el of elements) {
759
+ const values =
760
+ spec.take === "attr"
761
+ ? [el.getAttribute(spec.attr) || ""]
762
+ : elementTexts(el).filter(
763
+ (value) =>
764
+ !spec.textRegex ||
765
+ reTest(spec.textRegex, value, spec.textRegexFlags),
766
+ );
767
+ for (const value of values) {
768
+ if (!spec.regex) {
769
+ maximum = Math.max(maximum, compactCount(value));
770
+ continue;
771
+ }
772
+ try {
773
+ const match = value.match(new RegExp(spec.regex, spec.regexFlags));
774
+ maximum = Math.max(
775
+ maximum,
776
+ compactCount(match?.[spec.group ?? 1] ?? match?.[0] ?? ""),
777
+ );
778
+ } catch {
779
+ return 0;
780
+ }
781
+ }
782
+ }
783
+ return maximum;
784
+ };
785
+ const collectedRowItemIds = (rowEl, spec) => {
786
+ const ids = new Set();
787
+ if (!spec?.selector) return ids;
788
+ for (const el of rowEl.querySelectorAll(spec.selector)) {
789
+ if (!belongsToCollectedItems(el, rowEl)) continue;
790
+ const id = spec.idAttr ? el.getAttribute(spec.idAttr) || "" : el.id || "";
791
+ if (id) ids.add(id);
792
+ }
793
+ return ids;
794
+ };
795
+ const collectedRowItemSignature = (rowEl) =>
796
+ JSON.stringify([...collectedRowItemIds(rowEl, expandCfg?.items)].sort());
797
+ const isConfiguredExpansionRow = (rowEl) =>
798
+ !!expandCfg?.rowSelector && !!rowEl?.matches?.(expandCfg.rowSelector);
799
+ const expansionProofSignature = (rowEl) => {
800
+ if (!isConfiguredExpansionRow(rowEl)) return "";
801
+ return JSON.stringify({
802
+ identity: expansionIdentity(rowEl),
803
+ expected: expectedRowItems(rowEl, expandCfg.expected),
804
+ items: collectedRowItemSignature(rowEl),
805
+ unresolvedControls: visibleOwnedMatchingElements(
806
+ rowEl,
807
+ expandCfg.more?.selector,
808
+ expandCfg.more?.textRegex,
809
+ expandCfg.more?.textRegexFlags,
810
+ ).length,
811
+ });
812
+ };
813
+ const clickElement = (el) => {
814
+ if (!el || el.disabled || el.getAttribute?.("aria-disabled") === "true")
815
+ return false;
816
+ try {
817
+ el.click();
818
+ return true;
819
+ } catch {
820
+ return false;
821
+ }
822
+ };
823
+ const waitForMatchingElement = async (scope, spec, accepts = () => true) => {
824
+ const deadline = Math.min(
825
+ Date.now() + (spec.maxWaitMs ?? 1500),
826
+ expansionDeadline,
827
+ );
828
+ while (Date.now() <= deadline) {
829
+ const match = matchingElements(
830
+ scope,
831
+ spec.selector,
832
+ spec.textRegex,
833
+ spec.textRegexFlags,
834
+ ).find(accepts);
835
+ if (match) return match;
836
+ await sleep(50);
837
+ }
838
+ return null;
839
+ };
840
+ const sortOptionOwnership = (option, trigger) => {
841
+ const controlledIds = [
842
+ trigger?.getAttribute?.("aria-controls"),
843
+ trigger?.getAttribute?.("aria-owns"),
844
+ ]
845
+ .filter(Boolean)
846
+ .flatMap((value) => value.trim().split(/\s+/).filter(Boolean));
847
+ if (controlledIds.length > 0) {
848
+ return controlledIds.some((id) => {
849
+ const container = document.getElementById(id);
850
+ return (
851
+ container && (container === option || container.contains(option))
852
+ );
853
+ });
854
+ }
855
+
856
+ const menu = option?.closest?.('[role="menu"], [role="listbox"]');
857
+ const labelledBy = menu
858
+ ?.getAttribute?.("aria-labelledby")
859
+ ?.trim()
860
+ .split(/\s+/)
861
+ .filter(Boolean);
862
+ if (labelledBy?.length)
863
+ return !!trigger?.id && labelledBy.includes(trigger.id);
864
+ return null;
865
+ };
866
+ const expandRow = async (rowEl) => {
867
+ if (!expandCfg) return;
868
+ let identity = expansionIdentity(rowEl);
869
+ if (!hasUniqueExpansionIdentity(rowEl, identity)) return;
870
+ const activeRow = rowEl;
871
+ let expected = expectedRowItems(activeRow, expandCfg.expected);
872
+ let collected = collectedRowItemIds(activeRow, expandCfg.items).size;
873
+ let clicks = 0;
874
+ let expansionControlClicks = 0;
875
+ let passes = 0;
876
+ let stable = 0;
877
+ let lostRow = false;
878
+ const maxPasses = expandCfg.maxPasses ?? 20;
879
+ const stallMax = expandCfg.stall ?? 2;
880
+ const waitMs = expandCfg.waitMs ?? 500;
881
+ const resolveLiveRow = () => {
882
+ if (!activeRow?.isConnected) return null;
883
+ const currentIdentity = expansionIdentity(activeRow);
884
+ if (!identity && currentIdentity) identity = currentIdentity;
885
+ if (currentIdentity !== identity) {
886
+ // A connected virtualized slot now represents another logical row.
887
+ // Quarantine the element instead of transferring partial proof.
888
+ unstableHarvestRows.add(activeRow);
889
+ return null;
890
+ }
891
+ if (!hasUniqueExpansionIdentity(activeRow, identity)) return null;
892
+ return activeRow;
893
+ };
894
+ const refreshRowState = () => {
895
+ const liveRow = resolveLiveRow();
896
+ if (!liveRow) {
897
+ lostRow = true;
898
+ return null;
899
+ }
900
+ expected = Math.max(
901
+ expected,
902
+ expectedRowItems(liveRow, expandCfg.expected),
903
+ );
904
+ collected = collectedRowItemIds(liveRow, expandCfg.items).size;
905
+ return liveRow;
906
+ };
907
+
908
+ if (
909
+ !expansionDeadlineReached() &&
910
+ expected > collected &&
911
+ collected === 0 &&
912
+ expandCfg.open
913
+ ) {
914
+ const liveRow = resolveLiveRow();
915
+ const trigger = visibleOwnedMatchingElements(
916
+ liveRow,
917
+ expandCfg.open.selector,
918
+ expandCfg.open.textRegex,
919
+ expandCfg.open.textRegexFlags,
920
+ )[0];
921
+ const currentRow = resolveLiveRow();
922
+ if (
923
+ isVisibleOwnedMatchingElement(
924
+ trigger,
925
+ currentRow,
926
+ expandCfg.open.selector,
927
+ expandCfg.open.textRegex,
928
+ expandCfg.open.textRegexFlags,
929
+ ) &&
930
+ clickElement(trigger)
931
+ ) {
932
+ clicks++;
933
+ expansionControlClicks++;
934
+ await sleep(waitMs);
935
+ refreshRowState();
936
+ }
937
+ }
938
+
939
+ if (!expansionDeadlineReached() && expected > 0 && expandCfg.sort) {
940
+ const sort = expandCfg.sort;
941
+ const liveRow = resolveLiveRow();
942
+ const trigger = visibleOwnedMatchingElements(
943
+ liveRow,
944
+ sort.triggerSelector,
945
+ sort.triggerTextRegex,
946
+ sort.triggerTextRegexFlags,
947
+ )[0];
948
+ const selected = elementTexts(trigger);
949
+ // Causality is about visibility, not whether an existing option happened to
950
+ // match the desired label before the click. A page can relabel an unrelated,
951
+ // already-visible element in response to the trigger; that does not make the
952
+ // element owned by this interaction.
953
+ const renderedOptionsBeforeTrigger = new Set(
954
+ [...document.querySelectorAll(sort.optionSelector)].filter(
955
+ isRenderedInDocument,
956
+ ),
957
+ );
958
+ const isActionableOption = (candidate) => {
959
+ if (!isRenderedInDocument(candidate)) return false;
960
+ const owned = sortOptionOwnership(candidate, trigger);
961
+ return (
962
+ owned === true ||
963
+ (owned == null && !renderedOptionsBeforeTrigger.has(candidate))
964
+ );
965
+ };
966
+ if (
967
+ trigger &&
968
+ !selected.some((value) =>
969
+ reTest(sort.selectedTextRegex, value, sort.selectedTextRegexFlags),
970
+ ) &&
971
+ clickElement(trigger)
972
+ ) {
973
+ clicks++;
974
+ const option = await waitForMatchingElement(
975
+ document,
976
+ {
977
+ selector: sort.optionSelector,
978
+ textRegex: sort.optionTextRegex,
979
+ textRegexFlags: sort.optionTextRegexFlags,
980
+ maxWaitMs: sort.maxWaitMs,
981
+ },
982
+ isActionableOption,
983
+ );
984
+ const currentRow = resolveLiveRow();
985
+ const triggerStillActionable = isVisibleOwnedMatchingElement(
986
+ trigger,
987
+ currentRow,
988
+ sort.triggerSelector,
989
+ sort.triggerTextRegex,
990
+ sort.triggerTextRegexFlags,
991
+ );
992
+ const optionStillMatches =
993
+ option?.matches?.(sort.optionSelector) &&
994
+ elementTexts(option).some((value) =>
995
+ reTest(sort.optionTextRegex, value, sort.optionTextRegexFlags),
996
+ );
997
+ if (
998
+ triggerStillActionable &&
999
+ optionStillMatches &&
1000
+ isActionableOption(option) &&
1001
+ clickElement(option)
1002
+ ) {
1003
+ clicks++;
1004
+ await sleep(waitMs);
1005
+ refreshRowState();
1006
+ }
1007
+ }
1008
+ }
1009
+
1010
+ while (
1011
+ (expected > 0 || collected > 0) &&
1012
+ passes < maxPasses &&
1013
+ stable < stallMax &&
1014
+ !expansionDeadlineReached()
1015
+ ) {
1016
+ const liveRow = resolveLiveRow();
1017
+ if (!liveRow) {
1018
+ lostRow = true;
1019
+ break;
1020
+ }
1021
+ const controls = visibleOwnedMatchingElements(
1022
+ liveRow,
1023
+ expandCfg.more?.selector,
1024
+ expandCfg.more?.textRegex,
1025
+ expandCfg.more?.textRegexFlags,
1026
+ );
1027
+ if (controls.length === 0) {
1028
+ if (collected >= expected) break;
1029
+ const before = collected;
1030
+ await sleep(waitMs);
1031
+ if (!refreshRowState()) break;
1032
+ stable = collected === before ? stable + 1 : 0;
1033
+ continue;
1034
+ }
1035
+ const before = collected;
1036
+ let clicked = false;
1037
+ for (const control of controls) {
1038
+ const currentRow = resolveLiveRow();
1039
+ if (!currentRow) {
1040
+ lostRow = true;
1041
+ break;
1042
+ }
1043
+ if (
1044
+ !isVisibleOwnedMatchingElement(
1045
+ control,
1046
+ currentRow,
1047
+ expandCfg.more?.selector,
1048
+ expandCfg.more?.textRegex,
1049
+ expandCfg.more?.textRegexFlags,
1050
+ )
1051
+ )
1052
+ continue;
1053
+ if (clickElement(control)) {
1054
+ clicks++;
1055
+ expansionControlClicks++;
1056
+ clicked = true;
1057
+ }
1058
+ }
1059
+ if (!clicked) break;
1060
+ passes++;
1061
+ await sleep(waitMs);
1062
+ refreshRowState();
1063
+ stable = collected === before ? stable + 1 : 0;
1064
+ }
1065
+ const timedOut = expansionDeadlineReached();
1066
+ const finalRow = resolveLiveRow();
1067
+ const remainingControls = visibleOwnedMatchingElements(
1068
+ finalRow,
1069
+ expandCfg.more?.selector,
1070
+ expandCfg.more?.textRegex,
1071
+ expandCfg.more?.textRegexFlags,
1072
+ );
1073
+ const exhausted = !!finalRow && remainingControls.length === 0;
1074
+
1075
+ const coverage = {
1076
+ expected,
1077
+ collected,
1078
+ complete: !timedOut && !lostRow && collected >= expected && exhausted,
1079
+ clicks,
1080
+ capped: !timedOut && !exhausted && passes >= maxPasses,
1081
+ };
1082
+ if (timedOut) coverage.timedOut = true;
1083
+ expansionControlClicksByCoverage.set(coverage, expansionControlClicks);
1084
+ expansionHasUnresolvedControlsByCoverage.set(
1085
+ coverage,
1086
+ remainingControls.length > 0,
1087
+ );
1088
+ // If a connected slot changed identity, resolveLiveRow deliberately returns
1089
+ // null. Do not bind the old item's partial proof to the replacement element.
1090
+ if (!finalRow) return;
1091
+ const evidenceRow = finalRow;
1092
+ const durableIdentity = expansionIdentity(evidenceRow) || identity;
1093
+ expansionProofSignatureByCoverage.set(
1094
+ coverage,
1095
+ expansionProofSignature(evidenceRow),
1096
+ );
1097
+ const previous =
1098
+ expansionByRow.has(evidenceRow) &&
1099
+ expansionIdentityByRow.get(evidenceRow) === durableIdentity
1100
+ ? expansionByRow.get(evidenceRow)
1101
+ : null;
1102
+ const merged = mergeExpansion(previous, coverage);
1103
+ expansionByRow.set(evidenceRow, merged);
1104
+ expansionIdentityByRow.set(evidenceRow, durableIdentity);
1105
+ };
1106
+ const expandVisibleRows = async () => {
1107
+ if (!expandCfg?.rowSelector) return;
1108
+ const groupSelector = cfg.group?.selector;
1109
+ for (const rowEl of document.querySelectorAll(expandCfg.rowSelector)) {
1110
+ if (unstableHarvestRows.has(rowEl)) continue;
1111
+ if (!belongsToHarvestRow(rowEl, rowEl)) continue;
1112
+ const identity = expansionIdentity(rowEl);
1113
+ const activeGroup = groupSelector ? rowEl.closest(groupSelector) : null;
1114
+ await expandRow(rowEl);
1115
+ if (rowEl.isConnected || !identity) continue;
1116
+
1117
+ // A sort action can replace the row that triggered it. Give one unique,
1118
+ // same-group replacement a fresh attempt, without carrying over clicks or
1119
+ // coverage from the detached DOM instance.
1120
+ const replacements = [
1121
+ ...document.querySelectorAll(expandCfg.rowSelector),
1122
+ ].filter(
1123
+ (candidate) =>
1124
+ !unstableHarvestRows.has(candidate) &&
1125
+ belongsToHarvestRow(candidate, candidate) &&
1126
+ expansionIdentity(candidate) === identity &&
1127
+ (!groupSelector || candidate.closest(groupSelector) === activeGroup),
1128
+ );
1129
+ if (
1130
+ replacements.length === 1 &&
1131
+ hasUniqueExpansionIdentity(replacements[0], identity)
1132
+ )
1133
+ await expandRow(replacements[0]);
1134
+ }
1135
+ };
1136
+
1137
+ // Read one primitive (attr / text / aria / alt) off an element. `aria` reads
1138
+ // the element's own aria-label or the first descendant's, and `alt` the first
1139
+ // descendant img[alt]. These labels can remain useful when class names are
1140
+ // obfuscated.
1141
+ const readPart = (el, part) => {
1142
+ if (!el || !part) return "";
1143
+ if (part.take === "attr") return el.getAttribute(part.attr) || "";
1144
+ if (part.take === "aria")
1145
+ return (
1146
+ el.getAttribute("aria-label") ||
1147
+ el.querySelector("[aria-label]")?.getAttribute("aria-label") ||
1148
+ ""
1149
+ );
1150
+ if (part.take === "alt")
1151
+ return el.querySelector("img[alt]")?.getAttribute("alt") || "";
1152
+ return clean(el.innerText || "");
1153
+ };
1154
+
1155
+ const extractField = async (rowEl, spec) => {
1156
+ if (!spec) return "";
1157
+ if (spec.take === "clipboardAction") return "";
1158
+ if (spec.const !== undefined) return spec.const;
1159
+ // objectAll reads EVERY matching element and emits one object per match,
1160
+ // built from a sub-spec of named parts. It lets a connector capture a row's
1161
+ // repeated structures (e.g. every profile link in a feed card as
1162
+ // {href, name}) without any site knowledge living in this engine. Returns an
1163
+ // array — always, so downstream shape checks stay uniform.
1164
+ if (spec.take === "objectAll") {
1165
+ const parts = spec.parts || {};
1166
+ return [...rowEl.querySelectorAll(spec.selector)].map((el) => {
1167
+ const obj = {};
1168
+ for (const name of Object.keys(parts))
1169
+ obj[name] = readPart(el, parts[name]);
1170
+ return obj;
1171
+ });
1172
+ }
1173
+ // closestSelector starts from the parent so a nested row can record its
1174
+ // enclosing row without selecting itself. This is useful for generic tree
1175
+ // relationships such as a reply nested under its parent comment.
1176
+ const target = spec.closestSelector
1177
+ ? rowEl.parentElement?.closest(spec.closestSelector)
1178
+ : spec.selector
1179
+ ? rowEl.querySelector(spec.selector)
1180
+ : rowEl;
1181
+ if (!target) return "";
1182
+ if (spec.take === "attr") return target.getAttribute(spec.attr) || "";
1183
+ if (spec.take === "html") return target.innerHTML || "";
1184
+ // Select firstLine from the RAW innerText before whitespace-normalizing —
1185
+ // clean() collapses newlines to spaces, so splitting after it loses lines.
1186
+ const raw = target.innerText || "";
1187
+ if (spec.firstLine)
1188
+ return clean(
1189
+ raw
1190
+ .split("\n")
1191
+ .map((s) => s.trim())
1192
+ .filter(Boolean)[0] || "",
1193
+ );
1194
+ return clean(raw);
1195
+ };
1196
+
1197
+ const configuredId = (rowEl, fields) => {
1198
+ const spec = cfg.id;
1199
+ if (!spec) return "";
1200
+ let raw = "";
1201
+ if (spec.source === "attr") {
1202
+ const names = Array.isArray(spec.name) ? spec.name : [spec.name];
1203
+ for (const n of names) {
1204
+ raw = rowEl.getAttribute(n) || "";
1205
+ if (raw) break;
1206
+ }
1207
+ } else if (spec.source === "field") {
1208
+ raw = String(fields[spec.field] ?? "");
1209
+ }
1210
+ if (spec.regex && raw) {
1211
+ const m = raw.match(new RegExp(spec.regex));
1212
+ raw = m ? (m[spec.group ?? 1] ?? m[0]) : "";
1213
+ }
1214
+ return raw;
1215
+ };
1216
+
1217
+ const deriveId = (rowEl, fields, groupLabel) => {
1218
+ const configured = configuredId(rowEl, fields);
1219
+ if (configured) return configured;
1220
+ const keys = Object.keys(fields);
1221
+ const first = keys.length ? String(fields[keys[0]]) : "";
1222
+ return (
1223
+ (groupLabel ? groupLabel + "|" : "") + (first || JSON.stringify(fields))
1224
+ );
1225
+ };
1226
+
1227
+ const fieldsCfg = cfg.fields || {};
1228
+ const requireFields = cfg.requireFields || [];
1229
+ const mergeExpansion = (current, candidate) => {
1230
+ if (!current) return candidate;
1231
+ if (!candidate) return current;
1232
+ const expected = Math.max(current.expected, candidate.expected);
1233
+ const collected = Math.max(current.collected, candidate.collected);
1234
+ const currentExpansionControlClicks =
1235
+ expansionControlClicksByCoverage.get(current) ?? 0;
1236
+ const candidateExpansionControlClicks =
1237
+ expansionControlClicksByCoverage.get(candidate) ?? 0;
1238
+ const currentHasUnresolvedControls =
1239
+ expansionHasUnresolvedControlsByCoverage.get(current) ?? false;
1240
+ const candidateHasUnresolvedControls =
1241
+ expansionHasUnresolvedControlsByCoverage.get(candidate) ?? false;
1242
+ const equalCounts =
1243
+ candidate.expected === current.expected &&
1244
+ candidate.collected === current.collected;
1245
+ const candidateIsStrictlyWeaker =
1246
+ candidate.expected <= current.expected &&
1247
+ candidate.collected <= current.collected &&
1248
+ !equalCounts;
1249
+
1250
+ let complete = false;
1251
+ if (collected >= expected) {
1252
+ if (current.complete && candidate.complete) {
1253
+ complete = true;
1254
+ } else if (!current.complete && candidate.complete) {
1255
+ // A later snapshot may resolve an earlier incomplete tie only when
1256
+ // this attempt causally exhausted a control, or when it actually
1257
+ // collected more durable items. A control that merely disappeared is
1258
+ // not proof that the thread finished loading.
1259
+ complete =
1260
+ candidate.collected > current.collected ||
1261
+ (equalCounts && candidateExpansionControlClicks > 0);
1262
+ } else if (current.complete && !candidate.complete) {
1263
+ // Preserve a proven stronger snapshot when virtualization later
1264
+ // exposes fewer items. An equal timeout-only retry also cannot erase
1265
+ // proof obtained before the global deadline. Equal non-timeout or
1266
+ // crossed later evidence remains conservatively incomplete.
1267
+ complete =
1268
+ !candidateHasUnresolvedControls &&
1269
+ (candidateIsStrictlyWeaker ||
1270
+ (equalCounts && candidate.timedOut === true));
1271
+ }
1272
+ }
1273
+ const timedOut =
1274
+ !complete && !!(current.timedOut || candidate.timedOut);
1275
+
1276
+ const merged = {
1277
+ expected,
1278
+ collected,
1279
+ complete,
1280
+ clicks: Math.max(current.clicks ?? 0, candidate.clicks ?? 0),
1281
+ capped: complete ? false : !!(current.capped || candidate.capped),
1282
+ };
1283
+ if (timedOut) merged.timedOut = true;
1284
+ expansionControlClicksByCoverage.set(
1285
+ merged,
1286
+ Math.max(
1287
+ currentExpansionControlClicks,
1288
+ candidateExpansionControlClicks,
1289
+ ),
1290
+ );
1291
+ expansionHasUnresolvedControlsByCoverage.set(
1292
+ merged,
1293
+ !complete &&
1294
+ (currentHasUnresolvedControls || candidateHasUnresolvedControls),
1295
+ );
1296
+ expansionProofSignatureByCoverage.set(
1297
+ merged,
1298
+ expansionProofSignatureByCoverage.get(candidate) ??
1299
+ expansionProofSignatureByCoverage.get(current) ??
1300
+ "",
1301
+ );
1302
+ return merged;
1303
+ };
1304
+ const expansionForRow = (rowEl, identity = expansionIdentity(rowEl)) => {
1305
+ const direct =
1306
+ expansionByRow.has(rowEl) &&
1307
+ expansionIdentityByRow.get(rowEl) === identity
1308
+ ? expansionByRow.get(rowEl)
1309
+ : null;
1310
+ const retained = direct;
1311
+ if (!retained) return null;
1312
+ const currentProofSignature = expansionProofSignature(rowEl);
1313
+ if (
1314
+ expansionProofSignatureByCoverage.get(retained) !== currentProofSignature
1315
+ ) {
1316
+ unstableHarvestRows.add(rowEl);
1317
+ return null;
1318
+ }
1319
+ const expected = Math.max(
1320
+ retained.expected,
1321
+ expectedRowItems(rowEl, expandCfg?.expected),
1322
+ );
1323
+ const collected = collectedRowItemIds(rowEl, expandCfg?.items).size;
1324
+ const hasUnresolvedControls = visibleOwnedMatchingElements(
1325
+ rowEl,
1326
+ expandCfg?.more?.selector,
1327
+ expandCfg?.more?.textRegex,
1328
+ expandCfg?.more?.textRegexFlags,
1329
+ ).length > 0;
1330
+ const complete =
1331
+ retained.complete && collected >= expected && !hasUnresolvedControls;
1332
+ const coverage = {
1333
+ ...retained,
1334
+ expected,
1335
+ collected,
1336
+ complete,
1337
+ capped: complete ? false : retained.capped,
1338
+ };
1339
+ if (complete) delete coverage.timedOut;
1340
+ expansionControlClicksByCoverage.set(
1341
+ coverage,
1342
+ expansionControlClicksByCoverage.get(retained) ?? 0,
1343
+ );
1344
+ expansionHasUnresolvedControlsByCoverage.set(
1345
+ coverage,
1346
+ hasUnresolvedControls,
1347
+ );
1348
+ expansionProofSignatureByCoverage.set(coverage, currentProofSignature);
1349
+ return coverage;
1350
+ };
1351
+ const buildRow = async (rowEl, groupLabel) => {
1352
+ if (unstableHarvestRows.has(rowEl)) return null;
1353
+ const expansionRow = isConfiguredExpansionRow(rowEl);
1354
+ if (
1355
+ expansionRow &&
1356
+ !hasUniqueExpansionIdentity(rowEl, expansionIdentity(rowEl))
1357
+ )
1358
+ return null;
1359
+ const identityBefore = expansionRow ? expansionIdentity(rowEl) : "";
1360
+ const proofSignatureBefore = expansionProofSignature(rowEl);
1361
+ const fields = {};
1362
+ // An empty array from a multi-match field means "nothing found" — but []
1363
+ // is truthy, so it needs an explicit length check to count as missing.
1364
+ const isMissing = (v) => (Array.isArray(v) ? v.length === 0 : !v);
1365
+ // Required cheap fields are checked first. This keeps an invalid/helper row
1366
+ // from opening an action menu merely to discover later that the row has no
1367
+ // body (or other required identity).
1368
+ for (const name of requireFields) {
1369
+ const spec = fieldsCfg[name];
1370
+ if (!spec) continue;
1371
+ fields[name] = await extractField(rowEl, spec);
1372
+ }
1373
+ if (requireFields.some((f) => isMissing(fields[f]))) return null;
1374
+ for (const name of Object.keys(fieldsCfg)) {
1375
+ if (name in fields) continue;
1376
+ fields[name] = await extractField(rowEl, fieldsCfg[name]);
1377
+ }
1378
+ const id = deriveId(rowEl, fields, groupLabel);
1379
+ const row = { id, ...fields };
1380
+ const identityAfterFields = expansionRow ? expansionIdentity(rowEl) : "";
1381
+ const proofSignatureAfterFields = expansionProofSignature(rowEl);
1382
+ if (
1383
+ identityBefore !== identityAfterFields ||
1384
+ proofSignatureBefore !== proofSignatureAfterFields
1385
+ ) {
1386
+ unstableHarvestRows.add(rowEl);
1387
+ return null;
1388
+ }
1389
+ const identity = identityAfterFields;
1390
+ const expansion = expansionRow ? expansionForRow(rowEl, identity) : null;
1391
+ if (unstableHarvestRows.has(rowEl)) return null;
1392
+ if (
1393
+ expansionRow &&
1394
+ (expansionIdentity(rowEl) !== identity ||
1395
+ expansionProofSignature(rowEl) !== proofSignatureAfterFields)
1396
+ ) {
1397
+ unstableHarvestRows.add(rowEl);
1398
+ return null;
1399
+ }
1400
+ if (expansion && expandCfg?.outputField)
1401
+ row[expandCfg.outputField] = expansion;
1402
+ if (groupLabel != null) row.group = groupLabel;
1403
+ return {
1404
+ row,
1405
+ identity,
1406
+ expansionRow,
1407
+ proofSignature: proofSignatureAfterFields,
1408
+ };
1409
+ };
1410
+ const seenIdentityById = new Map();
1411
+ const seenIdByIdentity = new Map();
1412
+ const strongestRowByIdentity = new Map();
1413
+ const seenExpansionSourceById = new Map();
1414
+ const rememberRow = (seen, rowEl, built) => {
1415
+ let candidate = built?.row;
1416
+ if (!candidate?.id) return;
1417
+ const identity = built.identity;
1418
+ if (built.expansionRow) {
1419
+ if (
1420
+ !isConfiguredExpansionRow(rowEl) ||
1421
+ !rowEl.isConnected ||
1422
+ unstableHarvestRows.has(rowEl) ||
1423
+ expansionIdentity(rowEl) !== identity ||
1424
+ !hasUniqueExpansionIdentity(rowEl, identity) ||
1425
+ expansionProofSignature(rowEl) !== built.proofSignature
1426
+ )
1427
+ return;
1428
+ }
1429
+ const outputField = expandCfg?.outputField;
1430
+ if (identity && outputField) {
1431
+ const previousSnapshot = strongestRowByIdentity.get(identity);
1432
+ const previous =
1433
+ previousSnapshot?.rowEl === rowEl ? previousSnapshot.row : null;
1434
+ const previousCoverage = previous?.[outputField];
1435
+ const candidateCoverage = candidate[outputField];
1436
+ const candidateExpected = candidateCoverage?.expected ?? -1;
1437
+ const previousExpected = previousCoverage?.expected ?? -1;
1438
+ const candidateCollected = candidateCoverage?.collected ?? -1;
1439
+ const previousCollected = previousCoverage?.collected ?? -1;
1440
+ const candidateIsStronger =
1441
+ !previous ||
1442
+ candidateExpected > previousExpected ||
1443
+ candidateCollected > previousCollected ||
1444
+ (candidateCollected === previousCollected &&
1445
+ (Boolean(candidateCoverage?.complete) ||
1446
+ !previousCoverage?.complete));
1447
+ if (candidateIsStronger)
1448
+ strongestRowByIdentity.set(identity, { row: candidate, rowEl });
1449
+ else candidate = previous;
1450
+ }
1451
+ const previousId = identity ? seenIdByIdentity.get(identity) : null;
1452
+ if (
1453
+ previousId &&
1454
+ previousId !== candidate.id &&
1455
+ seenIdentityById.get(previousId) === identity
1456
+ ) {
1457
+ seen.delete(previousId);
1458
+ seenIdentityById.delete(previousId);
1459
+ seenExpansionSourceById.delete(previousId);
1460
+ }
1461
+ const replacedIdentity = seenIdentityById.get(candidate.id);
1462
+ if (replacedIdentity && replacedIdentity !== identity) {
1463
+ const replacedSource = seenExpansionSourceById.get(candidate.id);
1464
+ if (seenIdByIdentity.get(replacedIdentity) === candidate.id)
1465
+ seenIdByIdentity.delete(replacedIdentity);
1466
+ if (
1467
+ replacedSource &&
1468
+ strongestRowByIdentity.get(replacedIdentity)?.rowEl ===
1469
+ replacedSource.rowEl
1470
+ )
1471
+ strongestRowByIdentity.delete(replacedIdentity);
1472
+ seenIdentityById.delete(candidate.id);
1473
+ seenExpansionSourceById.delete(candidate.id);
1474
+ }
1475
+ seen.set(candidate.id, candidate);
1476
+ if (identity) {
1477
+ seenIdentityById.set(candidate.id, identity);
1478
+ seenIdByIdentity.set(identity, candidate.id);
1479
+ seenExpansionSourceById.set(candidate.id, { rowEl, identity });
1480
+ } else {
1481
+ seenIdentityById.delete(candidate.id);
1482
+ seenExpansionSourceById.delete(candidate.id);
1483
+ }
1484
+ };
1485
+ const revokeInvalidExpansionRows = (seen) => {
1486
+ for (const [id, source] of seenExpansionSourceById) {
1487
+ const { rowEl, identity } = source;
1488
+ if (
1489
+ rowEl.isConnected &&
1490
+ !unstableHarvestRows.has(rowEl) &&
1491
+ expansionIdentity(rowEl) === identity &&
1492
+ hasUniqueExpansionIdentity(rowEl, identity)
1493
+ )
1494
+ continue;
1495
+ seen.delete(id);
1496
+ seenExpansionSourceById.delete(id);
1497
+ if (seenIdentityById.get(id) === identity) seenIdentityById.delete(id);
1498
+ if (seenIdByIdentity.get(identity) === id) seenIdByIdentity.delete(identity);
1499
+ if (strongestRowByIdentity.get(identity)?.rowEl === rowEl)
1500
+ strongestRowByIdentity.delete(identity);
1501
+ }
1502
+ };
1503
+
1504
+ const harvest = async (seen, expand = true) => {
1505
+ if (expand) await expandVisibleRows();
1506
+ const candidates = [];
1507
+ const captureRow = async (rowEl, groupLabel) => {
1508
+ candidates.push([rowEl, await buildRow(rowEl, groupLabel)]);
1509
+ };
1510
+ if (cfg.group && cfg.group.selector) {
1511
+ for (const g of document.querySelectorAll(cfg.group.selector)) {
1512
+ const label = cfg.group.labelFromFirstLine
1513
+ ? g.innerText
1514
+ .split("\n")
1515
+ .map((s) => s.trim())
1516
+ .filter(Boolean)[0] || ""
1517
+ : "";
1518
+ for (const rowEl of g.querySelectorAll(cfg.group.rowSelector)) {
1519
+ await captureRow(rowEl, label);
1520
+ }
1521
+ }
1522
+ } else if (cfg.rowSelector) {
1523
+ for (const rowEl of document.querySelectorAll(cfg.rowSelector)) {
1524
+ await captureRow(rowEl, null);
1525
+ }
1526
+ }
1527
+ // Expansion-field getters can schedule DOM work in microtasks. Let that
1528
+ // queue drain before the synchronous commit revalidation so proof cannot
1529
+ // change in the former buildRow -> rememberRow await gap. Ordinary harvest
1530
+ // rows retain their pre-existing snapshot semantics.
1531
+ if (candidates.some(([rowEl]) => isConfiguredExpansionRow(rowEl)))
1532
+ await sleep(0);
1533
+ for (const [rowEl, built] of candidates) rememberRow(seen, rowEl, built);
1534
+ revokeInvalidExpansionRows(seen);
1535
+ };
1536
+
1537
+ const sc = cfg.scroll || {};
1538
+ const maxScrolls = sc.max ?? 8;
1539
+ const stallMax = sc.stall ?? 3;
1540
+ const waitMs = sc.waitMs ?? 1500;
1541
+ const scrollStep = () => {
1542
+ const se = document.scrollingElement || document.documentElement;
1543
+ se.scrollTo(0, se.scrollHeight);
1544
+ window.scrollTo(0, document.body.scrollHeight);
1545
+ if (sc.deep) {
1546
+ let best = null;
1547
+ for (const el of document.querySelectorAll("*")) {
1548
+ const oy = getComputedStyle(el).overflowY;
1549
+ if (
1550
+ (oy === "auto" || oy === "scroll") &&
1551
+ el.scrollHeight > el.clientHeight + 200 &&
1552
+ (!best || el.scrollHeight > best.scrollHeight)
1553
+ )
1554
+ best = el;
1555
+ }
1556
+ if (best) best.scrollTo(0, best.scrollHeight);
1557
+ }
1558
+ };
1559
+
1560
+ // Always start from the TOP before harvesting. A persistent/reused tab may
1561
+ // still be scrolled deep into history from a prior run, and infinite lists
1562
+ // (e.g. Revolut transactions) virtualize off-screen rows — so without this a
1563
+ // scrolled-down tab harvests only OLD items and never sees the newest ones,
1564
+ // walking the sync backwards in time on every run.
1565
+ {
1566
+ const se = document.scrollingElement || document.documentElement;
1567
+ se.scrollTo(0, 0);
1568
+ window.scrollTo(0, 0);
1569
+ await sleep(waitMs);
1570
+ }
1571
+
1572
+ const seen = new Map();
1573
+ let stable = 0;
1574
+ for (let i = 0; i < maxScrolls && stable < stallMax; i++) {
1575
+ const before = seen.size;
1576
+ await harvest(seen);
1577
+ if (expansionTimedOut) break;
1578
+ scrollStep();
1579
+ await sleep(waitMs);
1580
+ stable = seen.size === before ? stable + 1 : 0;
1581
+ }
1582
+ await harvest(seen, !expansionTimedOut);
1583
+
1584
+ const low = cfg.loggedOutWhen || {};
1585
+ const loggedIn = !(
1586
+ reTest(low.pathRegex, location.pathname) ||
1587
+ reTest(low.hostRegex, location.hostname)
1588
+ );
1589
+ const rows = [...seen.values()];
1590
+ return {
1591
+ count: rows.length,
1592
+ host: location.hostname,
1593
+ landedUrl: location.href,
1594
+ loggedIn,
1595
+ clickedBefore,
1596
+ oldestGroup:
1597
+ rows.length && rows[rows.length - 1].group != null
1598
+ ? rows[rows.length - 1].group
1599
+ : "",
1600
+ rows,
1601
+ };
1602
+ }
1603
+
1604
+ // ── tools ──────────────────────────────────────────────────────────────
1605
+
1606
+ // navigate({ url, tab_id?, new_tab?, group?, wait_for_load?, cs_scrape?,
1607
+ // persistent?, focus? })
1608
+ async function tool_navigate(chromeApi, args, runCtx) {
1609
+ if (args?.require_page_activation === true) {
1610
+ throw new Error(
1611
+ "navigate: require_page_activation must be resolved by the gateway before extension dispatch",
1612
+ );
1613
+ }
1614
+ const url = args?.url;
1615
+ if (typeof url !== "string") throw new Error("navigate: 'url' is required");
1616
+ if (runCtx.activationTabId != null) {
1617
+ if (args.cs_scrape === true || args.extractor != null ||
1618
+ args.new_tab === true || args.persistent === true || args.group != null) {
1619
+ throw new Error("navigate: scrape and tab-selection options are not available on a page-activated run");
1620
+ }
1621
+ // A page-activated run may only "navigate" to the exact page the human
1622
+ // already has open: never a new tab, never a different URL.
1623
+ const tabId = runCtx.activationTabId;
1624
+ await enforceTabMutable(chromeApi, "navigate", tabId, runCtx);
1625
+ const tab = await chromeApi.tabs.get(tabId);
1626
+ if (tab.pendingUrl || normalizePageUrl(tab.url) !== normalizePageUrl(url)) {
1627
+ throw new Error("navigate: activated tab is not on the requested exact page");
1628
+ }
1629
+ return {
1630
+ ok: true,
1631
+ observation: { tab_id: tabId, current_url: tab.url, user_owned: true, outcome: "no_change" },
1632
+ };
1633
+ }
1634
+ enforceAllowedOrigin(url, runCtx);
1635
+ await assertHostPermission(chromeApi, url);
1636
+ const site = siteKeyFor(url, runCtx.allowedOrigins ?? []);
1637
+ const focused = args.window_focused === true || args.focus === true;
1638
+ if (args.persistent === true && site == null) {
1639
+ throw new Error("navigate: persistent needs an http(s) url");
1640
+ }
1641
+
1642
+ // cs_scrape: scroll + extract entirely via chrome.scripting (content script),
1643
+ // NEVER attaching chrome.debugger. Requires host_permissions for the site.
1644
+ //
1645
+ // Tab sources:
1646
+ // - persistent: the site's warm tab.
1647
+ // - tab_id: a specific tab.
1648
+ // - default: a one-shot window, closed when the scrape returns.
1649
+ // The connector supplies `scrape_config` (declarative selectors/rules); the
1650
+ // generic in-page engine runs it. No site knowledge lives here.
1651
+ if (args.cs_scrape === true) {
1652
+ const scrapeTab = async (tabId, persistentReused = null) => {
1653
+ await enforceAllowedOriginFromTab(chromeApi, tabId, runCtx);
1654
+ await enforceTabMutable(chromeApi, "navigate", tabId, runCtx);
1655
+ let result;
1656
+ try {
1657
+ const injected = await chromeApi.scripting.executeScript({
1658
+ target: { tabId },
1659
+ world: "MAIN",
1660
+ func: genericScrape,
1661
+ args: [args.scrape_config ?? {}],
1662
+ });
1663
+ result = injected?.[0]?.result ?? null;
1664
+ } catch (e) {
1665
+ result = { error: e instanceof Error ? e.message : String(e) };
1666
+ }
1667
+ return {
1668
+ ok: true,
1669
+ observation: {
1670
+ tab_id: tabId,
1671
+ cs_scrape: true,
1672
+ persistent_reused: persistentReused,
1673
+ result,
1674
+ },
1675
+ };
1676
+ };
1677
+
1678
+ const explicitTab = args.tab_id ?? runCtx.scratchTabId;
1679
+ if (explicitTab != null) return scrapeTab(explicitTab);
1680
+
1681
+ if (args.persistent === true) {
1682
+ return withKeyLock(`site:${site}`, async () => {
1683
+ const warm = await findOrCreateWarmTab(chromeApi, site, runCtx, focused);
1684
+ // Navigate unless the warm tab is ALREADY on the requested page
1685
+ // (same origin + path); a host-only match would leave it on a stale
1686
+ // route. Query strings/hashes are ignored so we don't needlessly reload.
1687
+ const tab = await chromeApi.tabs.get(warm.tabId);
1688
+ if (!warm.reused || navigationPageKey(tab.url || "") !== navigationPageKey(url)) {
1689
+ await chromeApi.tabs.update(warm.tabId, { url });
1690
+ await waitForTabComplete(chromeApi, warm.tabId, 20000);
1691
+ await sleep(warm.reused ? 2500 : 3000);
1692
+ }
1693
+ return scrapeTab(warm.tabId, warm.reused);
1694
+ });
1695
+ }
1696
+
1697
+ let tabId = null;
1698
+ let windowId = null;
1699
+ try {
1700
+ const win = await chromeApi.windows.create({
1701
+ url,
1702
+ focused: args.window_focused === true,
1703
+ type: "normal",
1704
+ width: args.window_width ?? 1100,
1705
+ height: args.window_height ?? 900,
1706
+ left: 40,
1707
+ top: 40,
1708
+ });
1709
+ const created = win?.tabs?.[0];
1710
+ if (!created?.id)
1711
+ throw new Error("navigate: failed to create cs_scrape window");
1712
+ tabId = created.id;
1713
+ windowId = win.id;
1714
+ // No site: a scrape window is never offered to another navigate.
1715
+ await labelTab(tabId, runCtx, { kind: "task" });
1716
+ await waitForTabComplete(chromeApi, tabId, 20000);
1717
+ await sleep(3000);
1718
+ return await scrapeTab(tabId);
1719
+ } finally {
1720
+ // The scrape created this window, so it disposes of it.
1721
+ if (windowId != null) {
1722
+ const removeTab = () => chromeApi.tabs.remove(tabId).catch(() => {});
1723
+ await chromeApi.windows.remove(windowId).catch(removeTab);
1724
+ }
1725
+ if (tabId != null) await forgetTabLabel(tabId);
1726
+ }
1727
+ }
1728
+
1729
+ const waitForLoad = args.wait_for_load !== false;
1730
+ /**
1731
+ * Navigate a tab, skipping the load when `allowReuse` and the tab is ALREADY
1732
+ * on the requested page.
1733
+ *
1734
+ * `Page.navigate` performs a full document load even when the URL is
1735
+ * identical, which destroys exactly the state a `persistent: true` caller
1736
+ * asked to keep. The WhatsApp connector pays ~25s of store hydration per
1737
+ * load, so reloading its own hot tab every run left the feed unable to
1738
+ * finish a single sync.
1739
+ *
1740
+ * Three deliberate details:
1741
+ * • The check runs INSIDE `withDebugger` and reads the live `location.href`
1742
+ * rather than `tab.url`. A tab parked on a network error page still
1743
+ * reports the intended URL in `tab.url` while `location` is
1744
+ * `chrome-error://chromewebdata/`, so a tab.url comparison would skip
1745
+ * forever and never recover.
1746
+ * • A tab that is still loading is not "already on the page" —
1747
+ * `wait_for_load` promises a loaded document, so it always navigates.
1748
+ * (withDebugger already reloaded a discarded tab, or refused it.)
1749
+ * • Only a REUSED warm tab may skip; a freshly created one is on about:blank.
1750
+ */
1751
+ const navigateTab = (targetTabId, { allowReuse = false } = {}) =>
1752
+ withDebugger(chromeApi, targetTabId, async () => {
1753
+ await assertRecoveryTab(chromeApi, targetTabId, runCtx);
1754
+ if (allowReuse) {
1755
+ let liveHref = null;
1756
+ try {
1757
+ const tab = await chromeApi.tabs.get(targetTabId);
1758
+ if (tab?.status === "complete") {
1759
+ liveHref = await evalInPage(chromeApi, targetTabId, "location.href");
1760
+ }
1761
+ } catch {
1762
+ liveHref = null;
1763
+ }
1764
+ if (
1765
+ liveHref &&
1766
+ navigationPageKey(liveHref) === navigationPageKey(url)
1767
+ ) {
1768
+ let title = "";
1769
+ try {
1770
+ title =
1771
+ (await evalInPage(chromeApi, targetTabId, "document.title")) ?? "";
1772
+ } catch {}
1773
+ return {
1774
+ ok: true,
1775
+ observation: { tab_id: targetTabId, current_url: liveHref, title, outcome: "no_change" },
1776
+ };
1777
+ }
1778
+ }
1779
+ const failed = message => ({ ok: false, error: message, observation: {
1780
+ tab_id: targetTabId, value: { __lobu_browser_interruption: { reason: "loading_failure", message } },
1781
+ } });
1782
+ if (waitForLoad) await chromeApi.debugger.sendCommand(dbgTarget(targetTabId), "Page.setLifecycleEventsEnabled", { enabled: true });
1783
+ const loaded = waitForLoad ? navigationLoad(chromeApi, targetTabId) : null;
1784
+ try {
1785
+ const navigation = await chromeApi.debugger.sendCommand(dbgTarget(targetTabId), "Page.navigate", { url });
1786
+ if (navigation.errorText) return failed(`navigate: navigation failed: ${navigation.errorText}`);
1787
+ if (navigation.isDownload) return failed("navigate: requested page became a download");
1788
+ if (loaded && !await loaded.wait(navigation)) return failed("navigate: timed out waiting for the navigated document to load");
1789
+ } finally { loaded?.cancel(); }
1790
+ // Nonblocking navigation acknowledges dispatch; its URL fallback is the requested destination.
1791
+ let current_url = waitForLoad ? undefined : url;
1792
+ let title = "";
1793
+ try {
1794
+ current_url = await evalInPage(chromeApi, targetTabId, "location.href");
1795
+ } catch {
1796
+ if (waitForLoad) return failed("navigate: loaded document could not be observed");
1797
+ }
1798
+ if (typeof current_url === "string" && current_url.startsWith("chrome-error:")) return failed("navigate: browser displayed a network error document");
1799
+ if (waitForLoad && !current_url) return failed("navigate: loaded document URL is unavailable");
1800
+ try { title = (await evalInPage(chromeApi, targetTabId, "document.title")) ?? ""; } catch {}
1801
+
1802
+ // A load we waited for is the navigation's read-back; a nonblocking
1803
+ // navigate only knows it was dispatched.
1804
+ return {
1805
+ ok: true,
1806
+ observation: {
1807
+ tab_id: targetTabId,
1808
+ current_url,
1809
+ title,
1810
+ outcome: waitForLoad ? "confirmed" : "unverifiable",
1811
+ },
1812
+ };
1813
+ });
1814
+
1815
+ let tabId = args.tab_id ?? runCtx.scratchTabId;
1816
+
1817
+ if (tabId == null && args.persistent === true) {
1818
+ return withKeyLock(`site:${site}`, async () => {
1819
+ const warm = await findOrCreateWarmTab(chromeApi, site, runCtx, focused);
1820
+ try {
1821
+ return await navigateTab(warm.tabId, { allowReuse: warm.reused });
1822
+ } catch (error) {
1823
+ if (!warm.reused || !isStaleDebuggerTargetError(error)) throw error;
1824
+ // A warm tab whose debugger target is poisoned cannot be recovered in
1825
+ // place. Close it first so the replacement never leaves a second copy
1826
+ // of the site open, then retry once on a fresh tab.
1827
+ await chromeApi.tabs.remove(warm.tabId).catch(() => {});
1828
+ await forgetTabLabel(warm.tabId);
1829
+ const fresh = await createWarmTab(chromeApi, site, runCtx, focused);
1830
+ return navigateTab(fresh.tabId);
1831
+ }
1832
+ });
1833
+ }
1834
+
1835
+ let busyBy = null;
1836
+ let reused = false;
1837
+ if (tabId == null) {
1838
+ // Reuse before create. Selection and creation share the site lock so two
1839
+ // concurrent navigates to one site end up in one tab, not two.
1840
+ const choose = async () => {
1841
+ const pick =
1842
+ args.new_tab === true || site == null
1843
+ ? null
1844
+ : await selectTaskTab(chromeApi, site, runCtx);
1845
+ if (pick) {
1846
+ await touchTabLabel(pick.tabId, runCtx);
1847
+ return { ...pick, reused: true };
1848
+ }
1849
+ const created = await chromeApi.tabs.create({
1850
+ url: "about:blank",
1851
+ active: false,
1852
+ });
1853
+ await labelTab(created.id, runCtx, { kind: "task", site });
1854
+ return { tabId: created.id, busyBy: null, reused: false };
1855
+ };
1856
+ const picked =
1857
+ site == null ? await choose() : await withKeyLock(`site:${site}`, choose);
1858
+ ({ tabId, busyBy, reused } = picked);
1859
+ } else {
1860
+ await enforceTabMutable(chromeApi, "navigate", tabId, runCtx);
1861
+ await noteTaskSite(tabId, site);
1862
+ }
1863
+ runCtx.scratchTabId = tabId;
1864
+ if (typeof args.group === "string" && args.group.trim()) {
1865
+ await joinGroup(chromeApi, tabId, args.group);
1866
+ }
1867
+ const result = await navigateTab(tabId);
1868
+ result.observation.reused = reused;
1869
+ if (busyBy) result.observation.busy_by = busyBy;
1870
+ return result;
1871
+ }
1872
+
1873
+ // get_accessibility_tree({ tab_id?, filter? })
1874
+ async function tool_get_accessibility_tree(chromeApi, args, runCtx) {
1875
+ const tabId = args?.tab_id ?? runCtx.scratchTabId;
1876
+ if (tabId == null) throw new Error("get_accessibility_tree: no tab");
1877
+ // The connector author's allowedOrigins gate applies to the current URL.
1878
+ const filter = args?.filter ?? "interactive";
1879
+ if (!["interactive", "visible", "all"].includes(filter)) {
1880
+ throw new Error(`get_accessibility_tree: bad filter '${filter}'`);
1881
+ }
1882
+
1883
+ // Inject the bundled walker into an isolated world, then call __lobuExtract.
1884
+ const authorize = async () => {
1885
+ await enforceAllowedOriginFromTab(chromeApi, tabId, runCtx);
1886
+ };
1887
+ return withDebugger(chromeApi, tabId, async () => {
1888
+ const ctxId = await injectAccessibilityScript(chromeApi, tabId);
1889
+ const extracted = await evalInContext(
1890
+ chromeApi,
1891
+ tabId,
1892
+ ctxId,
1893
+ `JSON.stringify(__lobuExtract({ filter: ${JSON.stringify(filter)} }))`,
1894
+ );
1895
+ const parsed =
1896
+ typeof extracted === "string" ? JSON.parse(extracted) : extracted;
1897
+ return {
1898
+ ok: true,
1899
+ observation: {
1900
+ tab_id: tabId,
1901
+ document_epoch: parsed.document_epoch,
1902
+ current_url: parsed.current_url,
1903
+ title: parsed.title,
1904
+ tree: parsed.tree,
1905
+ },
1906
+ };
1907
+ }, authorize);
1908
+ }
1909
+
1910
+ // click_ref({ ref, tab_id?, button?, click_count? })
1911
+ async function tool_click_ref(chromeApi, args, runCtx) {
1912
+ const ref = args?.ref;
1913
+ if (!ref || typeof ref !== "object")
1914
+ throw new Error("click_ref: 'ref' is required");
1915
+ const { ref_id, document_epoch } = ref;
1916
+ const tabId = args?.tab_id ?? runCtx.scratchTabId;
1917
+ if (tabId == null) throw new Error("click_ref: no tab");
1918
+ const button = args.button ?? "left";
1919
+ const clickCount = args.click_count ?? 1;
1920
+
1921
+ const authorize = async () => {
1922
+ await enforceAllowedOriginFromTab(chromeApi, tabId, runCtx);
1923
+ await enforceTabMutable(chromeApi, "click_ref", tabId, runCtx);
1924
+ };
1925
+ return withDebugger(chromeApi, tabId, async () => {
1926
+ const ctxId = await injectAccessibilityScript(chromeApi, tabId);
1927
+ const bboxJson = await evalInContext(
1928
+ chromeApi,
1929
+ tabId,
1930
+ ctxId,
1931
+ `JSON.stringify(__lobuFocusBbox(${JSON.stringify(ref_id)}, ${JSON.stringify(document_epoch)}))`,
1932
+ );
1933
+ const bbox = typeof bboxJson === "string" ? JSON.parse(bboxJson) : bboxJson;
1934
+ if (!bbox)
1935
+ throw new Error(`click_ref: stale ref (epoch ${document_epoch})`);
1936
+ // Headed Chrome drops synthesized input on a hidden page (a background
1937
+ // tab, where agent tabs live): the CDP call resolves, nothing happens.
1938
+ // Choose the route up front; replaying an unobserved click could
1939
+ // activate twice.
1940
+ const hidden =
1941
+ (await evalInContext(chromeApi, tabId, ctxId, "document.visibilityState")) ===
1942
+ "hidden";
1943
+ if (!hidden) {
1944
+ const startHref = await startWatch(chromeApi, tabId, ctxId);
1945
+ // One press/release per click with a rising clickCount, as a real
1946
+ // double click arrives: click detail 1, then 2, then dblclick.
1947
+ for (let count = 1; count <= clickCount; count++) {
1948
+ // Trusted input goes to whatever is on top at the point: an overlay
1949
+ // or cookie wall would take the click while this reported success.
1950
+ // Ask first, per click (the first may open a modal over the second).
1951
+ const blocked = await evalInContext(
1952
+ chromeApi,
1953
+ tabId,
1954
+ ctxId,
1955
+ `__lobuHitTest(${JSON.stringify(ref_id)}, ${JSON.stringify(document_epoch)})`,
1956
+ );
1957
+ if (blocked === "stale")
1958
+ throw new Error(`click_ref: stale ref (epoch ${document_epoch})`);
1959
+ if (blocked != null)
1960
+ throw new Error(`click_ref: the element is ${blocked}; a user could not click it either`);
1961
+ await dispatchMouse(chromeApi, tabId, "mousePressed", bbox.x, bbox.y, button, count);
1962
+ await dispatchMouse(chromeApi, tabId, "mouseReleased", bbox.x, bbox.y, button, count);
1963
+ }
1964
+ return {
1965
+ ok: true,
1966
+ observation: {
1967
+ tab_id: tabId,
1968
+ clicked: { x: bbox.x, y: bbox.y },
1969
+ dispatch: "input",
1970
+ outcome: await finishWatch(chromeApi, tabId, ctxId, startHref),
1971
+ },
1972
+ };
1973
+ }
1974
+ if (button !== "left") {
1975
+ // A page-dispatched contextmenu/auxclick runs page handlers but never
1976
+ // Chrome's own action (native menu, open in new tab).
1977
+ throw new Error(
1978
+ `click_ref: a ${button} click needs the tab in front (Chrome drops input to background tabs); call focus_tab first`,
1979
+ );
1980
+ }
1981
+ const startHref = await startWatch(chromeApi, tabId, ctxId);
1982
+ const clicked = await evalInContext(
1983
+ chromeApi,
1984
+ tabId,
1985
+ ctxId,
1986
+ `__lobuClickEl(${JSON.stringify(ref_id)}, ${JSON.stringify(document_epoch)}, ${JSON.stringify(clickCount)})`,
1987
+ );
1988
+ if (clicked === "stale")
1989
+ throw new Error(`click_ref: stale ref (epoch ${document_epoch})`);
1990
+ if (clicked !== "done")
1991
+ throw new Error(`click_ref: the element is ${clicked}; a user could not click it either`);
1992
+ return {
1993
+ ok: true,
1994
+ observation: {
1995
+ tab_id: tabId,
1996
+ clicked: { x: bbox.x, y: bbox.y },
1997
+ dispatch: "dom",
1998
+ outcome: await finishWatch(chromeApi, tabId, ctxId, startHref),
1999
+ },
2000
+ };
2001
+ }, authorize);
2002
+ }
2003
+
2004
+ // type_ref({ ref, text, tab_id?, clear_first? })
2005
+ async function tool_type_ref(chromeApi, args, runCtx) {
2006
+ const ref = args?.ref;
2007
+ const text = args?.text;
2008
+ if (!ref || typeof ref !== "object")
2009
+ throw new Error("type_ref: 'ref' is required");
2010
+ if (typeof text !== "string") throw new Error("type_ref: 'text' is required");
2011
+ const { ref_id, document_epoch } = ref;
2012
+ const tabId = args?.tab_id ?? runCtx.scratchTabId;
2013
+ if (tabId == null) throw new Error("type_ref: no tab");
2014
+ const clearFirst = args.clear_first !== false;
2015
+
2016
+ const authorize = async () => {
2017
+ await enforceAllowedOriginFromTab(chromeApi, tabId, runCtx);
2018
+ await enforceTabMutable(chromeApi, "type_ref", tabId, runCtx);
2019
+ };
2020
+ return withDebugger(chromeApi, tabId, async () => {
2021
+ const ctxId = await injectAccessibilityScript(chromeApi, tabId);
2022
+ const bboxJson = await evalInContext(
2023
+ chromeApi,
2024
+ tabId,
2025
+ ctxId,
2026
+ `JSON.stringify(__lobuFocusBbox(${JSON.stringify(ref_id)}, ${JSON.stringify(document_epoch)}))`,
2027
+ );
2028
+ const bbox = typeof bboxJson === "string" ? JSON.parse(bboxJson) : bboxJson;
2029
+ if (!bbox) throw new Error(`type_ref: stale ref (epoch ${document_epoch})`);
2030
+ await evalInContext(
2031
+ chromeApi,
2032
+ tabId,
2033
+ ctxId,
2034
+ `__lobuFieldBefore(${JSON.stringify(ref_id)}, ${JSON.stringify(document_epoch)})`,
2035
+ );
2036
+ // Selection plus Input.insertText replaces the content; key events would
2037
+ // be dropped on a background tab and append instead. Controls that take a
2038
+ // value rather than text (date, colour, range) and clearing to "" are set
2039
+ // in the page.
2040
+ const prepared = await evalInContext(
2041
+ chromeApi,
2042
+ tabId,
2043
+ ctxId,
2044
+ `__lobuPrepareText(${JSON.stringify(ref_id)}, ${JSON.stringify(document_epoch)}, ${JSON.stringify(text)}, ${JSON.stringify(clearFirst)})`,
2045
+ );
2046
+ if (prepared === "stale")
2047
+ throw new Error(`type_ref: stale ref (epoch ${document_epoch})`);
2048
+ if (prepared === "disabled" || prepared === "readonly")
2049
+ throw new Error(`type_ref: the field is ${prepared}`);
2050
+ if (prepared === "failed")
2051
+ throw new Error("type_ref: the field did not take the value");
2052
+ if (typeof prepared === "string" && prepared.startsWith("not-editable:"))
2053
+ throw new Error(
2054
+ `type_ref: the element is a <${prepared.slice("not-editable:".length)}> that does not take typed text (a select, checkbox or button); nothing was typed`,
2055
+ );
2056
+ if (prepared === "insert" && text !== "") {
2057
+ await chromeApi.debugger.sendCommand(dbgTarget(tabId), "Input.insertText", {
2058
+ text,
2059
+ });
2060
+ }
2061
+ // Read the field back: the value an input mask, a maxlength or a page
2062
+ // handler left is what the user would see. Only the comparison leaves
2063
+ // the page.
2064
+ const typed = await evalInContext(
2065
+ chromeApi,
2066
+ tabId,
2067
+ ctxId,
2068
+ `__lobuTypedOutcome(${JSON.stringify(ref_id)}, ${JSON.stringify(document_epoch)}, ${JSON.stringify(text)}, ${JSON.stringify(clearFirst || prepared === "done")})`,
2069
+ );
2070
+ const outcome = typed === "confirmed" || typed === "no_change" ? typed : "unverifiable";
2071
+ return { ok: true, observation: { tab_id: tabId, typed: text.length, outcome } };
2072
+ }, authorize);
2073
+ }
2074
+
2075
+ // upload_file({ ref, tab_id?, file_paths })
2076
+ // Set files on a file <input> resolved by a ref from a prior accessibility
2077
+ // snapshot, via CDP DOM.setFileInputFiles. The ref is resolved to a live DOM
2078
+ // node (returned by reference → objectId) so the command targets the exact
2079
+ // element, then the browser fires the input/change events a real picker would.
2080
+ async function tool_upload_file(chromeApi, args, runCtx) {
2081
+ const ref = args?.ref;
2082
+ if (!ref || typeof ref !== "object")
2083
+ throw new Error("upload_file: 'ref' is required");
2084
+ const filePaths = args?.file_paths;
2085
+ if (
2086
+ !Array.isArray(filePaths) ||
2087
+ filePaths.length === 0 ||
2088
+ !filePaths.every((p) => typeof p === "string" && p.length > 0)
2089
+ ) {
2090
+ throw new Error(
2091
+ "upload_file: 'file_paths' must be a non-empty array of strings",
2092
+ );
2093
+ }
2094
+ const { ref_id, document_epoch } = ref;
2095
+ const tabId = args?.tab_id ?? runCtx.scratchTabId;
2096
+ if (tabId == null) throw new Error("upload_file: no tab");
2097
+
2098
+ const authorize = async () => {
2099
+ await enforceAllowedOriginFromTab(chromeApi, tabId, runCtx);
2100
+ await enforceTabMutable(chromeApi, "upload_file", tabId, runCtx);
2101
+ };
2102
+ return withDebugger(chromeApi, tabId, async () => {
2103
+ const ctxId = await injectAccessibilityScript(chromeApi, tabId);
2104
+ // Resolve the ref → DOM node by reference so we get a CDP objectId.
2105
+ // __lobuResolveEl gates on the document epoch: a mismatch (or unknown
2106
+ // ref) yields null, so no objectId comes back — same stale-ref
2107
+ // semantics as click_ref / type_ref.
2108
+ const objectId = await evalInContextObjectId(
2109
+ chromeApi,
2110
+ tabId,
2111
+ ctxId,
2112
+ `__lobuResolveEl(${JSON.stringify(ref_id)}, ${JSON.stringify(document_epoch)})`,
2113
+ );
2114
+ if (!objectId)
2115
+ throw new Error(`upload_file: stale ref (epoch ${document_epoch})`);
2116
+ await chromeApi.debugger.sendCommand(
2117
+ dbgTarget(tabId),
2118
+ "DOM.setFileInputFiles",
2119
+ { files: filePaths, objectId },
2120
+ );
2121
+ const attached = await evalInContext(
2122
+ chromeApi,
2123
+ tabId,
2124
+ ctxId,
2125
+ `(__lobuResolveEl(${JSON.stringify(ref_id)}, ${JSON.stringify(document_epoch)})?.files?.length ?? null)`,
2126
+ ).catch(() => null);
2127
+ const outcome =
2128
+ attached === filePaths.length ? "confirmed" : attached === 0 ? "no_change" : "unverifiable";
2129
+ return {
2130
+ ok: true,
2131
+ observation: { tab_id: tabId, ref, file_count: filePaths.length, outcome },
2132
+ };
2133
+ }, authorize);
2134
+ }
2135
+
2136
+ // wait_for_selector({ selector, tab_id?, timeout_ms? })
2137
+ async function tool_wait_for_selector(chromeApi, args, runCtx) {
2138
+ const selector = args?.selector;
2139
+ if (typeof selector !== "string")
2140
+ throw new Error("wait_for_selector: 'selector' is required");
2141
+ const tabId = args?.tab_id ?? runCtx.scratchTabId;
2142
+ if (tabId == null) throw new Error("wait_for_selector: no tab");
2143
+ const timeoutMs = Math.min(60_000, Math.max(100, args.timeout_ms ?? 10_000));
2144
+
2145
+ const authorize = async () => {
2146
+ await enforceAllowedOriginFromTab(chromeApi, tabId, runCtx);
2147
+ };
2148
+ return withDebugger(chromeApi, tabId, async () => {
2149
+ const start = Date.now();
2150
+ while (Date.now() - start < timeoutMs) {
2151
+ const found = await evalInPage(
2152
+ chromeApi,
2153
+ tabId,
2154
+ `Boolean(document.querySelector(${JSON.stringify(selector)}))`,
2155
+ );
2156
+ if (found === true) {
2157
+ return {
2158
+ ok: true,
2159
+ observation: {
2160
+ tab_id: tabId,
2161
+ selector,
2162
+ elapsed_ms: Date.now() - start,
2163
+ },
2164
+ };
2165
+ }
2166
+ await sleep(200);
2167
+ }
2168
+ throw new Error(
2169
+ `wait_for_selector: '${selector}' not found within ${timeoutMs}ms`,
2170
+ );
2171
+ }, authorize);
2172
+ }
2173
+
2174
+ // Decoded byte length of a base64 string, without allocating the bytes.
2175
+ function base64ByteLength(b64) {
2176
+ if (typeof b64 !== "string" || b64.length === 0) return 0;
2177
+ let padding = 0;
2178
+ if (b64.endsWith("==")) padding = 2;
2179
+ else if (b64.endsWith("=")) padding = 1;
2180
+ return Math.floor((b64.length * 3) / 4) - padding;
2181
+ }
2182
+
2183
+ // screenshot({ tab_id? })
2184
+ async function tool_screenshot(chromeApi, args, runCtx) {
2185
+ const tabId = args?.tab_id ?? runCtx.scratchTabId;
2186
+ if (tabId == null) throw new Error("screenshot: no tab");
2187
+ const authorize = async () => {
2188
+ await enforceAllowedOriginFromTab(chromeApi, tabId, runCtx);
2189
+ };
2190
+ return withDebugger(chromeApi, tabId, async () => {
2191
+ const res = await chromeApi.debugger.sendCommand(
2192
+ dbgTarget(tabId),
2193
+ "Page.captureScreenshot",
2194
+ { format: "png" },
2195
+ );
2196
+ return {
2197
+ ok: true,
2198
+ observation: {
2199
+ tab_id: tabId,
2200
+ // Connector-standard inline attachment: the Lobu server strips
2201
+ // `data` into the ArtifactStore and leaves an artifact reference
2202
+ // behind. Returning a `data_url` instead kept the whole PNG in
2203
+ // `runs.action_output` forever.
2204
+ attachments: [
2205
+ {
2206
+ kind: "image",
2207
+ filename: "screenshot.png",
2208
+ mime_type: "image/png",
2209
+ size_bytes: base64ByteLength(res.data),
2210
+ data: res.data,
2211
+ },
2212
+ ],
2213
+ },
2214
+ };
2215
+ }, authorize);
2216
+ }
2217
+
2218
+ // focus_tab({ tab_id, draw_attention? })
2219
+ async function tool_focus_tab(chromeApi, args, runCtx) {
2220
+ const tabId = args?.tab_id;
2221
+ if (typeof tabId !== "number" || !Number.isFinite(tabId)) {
2222
+ throw new Error("focus_tab: 'tab_id' is required");
2223
+ }
2224
+ await enforceAllowedOriginFromTab(chromeApi, tabId, runCtx);
2225
+ await enforceTabMutable(chromeApi, "focus_tab", tabId, runCtx);
2226
+ const focused = await focusChromeTab(chromeApi, tabId, {
2227
+ drawAttention: args?.draw_attention !== false,
2228
+ });
2229
+ const tab = await chromeApi.tabs.get(tabId).catch(() => null);
2230
+ return {
2231
+ ok: true,
2232
+ observation: { ...focused, outcome: tab?.active ? "confirmed" : "unverifiable" },
2233
+ };
2234
+ }
2235
+
2236
+ // evaluate({ expression, tab_id?, await_promise? })
2237
+ async function tool_evaluate(chromeApi, args, runCtx) {
2238
+ const expression = args?.expression;
2239
+ if (typeof expression !== "string")
2240
+ throw new Error("evaluate: 'expression' is required");
2241
+ const tabId = args?.tab_id ?? runCtx.scratchTabId;
2242
+ if (tabId == null) throw new Error("evaluate: no tab");
2243
+ const awaitPromise = args.await_promise !== false;
2244
+ // A page-activated run re-checks the live URL inside the same script as the
2245
+ // expression, so no navigation can land between the check and the
2246
+ // evaluation. Plain statements, not a nested eval: page CSP may refuse
2247
+ // eval even when Runtime.evaluate itself is allowed.
2248
+ const guardedExpression =
2249
+ runCtx.activationTabId == null
2250
+ ? expression
2251
+ : `if (!${JSON.stringify(runCtx.activationTargetUrls)}.includes((${normalizePageUrl.toString()})(location.href))) throw new Error("Activated page changed before evaluation");\n${expression}`;
2252
+ const authorize = async () => {
2253
+ await enforceAllowedOriginFromTab(chromeApi, tabId, runCtx);
2254
+ await enforceTabMutable(chromeApi, "evaluate", tabId, runCtx);
2255
+ };
2256
+ return withDebugger(chromeApi, tabId, async () => {
2257
+ try {
2258
+ const value = await evalInPage(
2259
+ chromeApi,
2260
+ tabId,
2261
+ guardedExpression,
2262
+ awaitPromise,
2263
+ );
2264
+ // The expression's effect is the caller's to read back.
2265
+ return { ok: true, observation: { tab_id: tabId, value, outcome: "unverifiable" } };
2266
+ } catch (err) {
2267
+ return {
2268
+ ok: false,
2269
+ error: err instanceof Error ? err.message : String(err),
2270
+ };
2271
+ }
2272
+ }, authorize);
2273
+ }
2274
+
2275
+ // close_tab({ tab_id } | { group }) — explicit cleanup. Only an expired source
2276
+ // recovery's own target closes on a timer, so an agent closes the tabs it
2277
+ // opened when its task is done. A group
2278
+ // closes every tab in the groups with that exact title; user tabs in it are
2279
+ // left open (reported in `refused`) unless the user granted tab management.
2280
+ async function tool_close_tab(chromeApi, args, runCtx) {
2281
+ if (typeof args?.tab_id === "number") {
2282
+ const tabId = args.tab_id;
2283
+ if (!(await chromeApi.tabs.get(tabId).catch(() => null))) {
2284
+ await forgetTabLabel(tabId);
2285
+ return {
2286
+ ok: true,
2287
+ observation: { tab_id: tabId, closed: true, already_closed: true, outcome: "no_change" },
2288
+ };
2289
+ }
2290
+ await enforceAllowedOriginFromTab(chromeApi, tabId, runCtx);
2291
+ await enforceTabMutable(chromeApi, "close_tab", tabId, runCtx);
2292
+ await chromeApi.tabs.remove(tabId);
2293
+ await forgetTabLabel(tabId);
2294
+ // tabs.remove resolves once the tab is gone.
2295
+ return { ok: true, observation: { tab_id: tabId, closed: true, outcome: "confirmed" } };
2296
+ }
2297
+ const group = typeof args?.group === "string" ? args.group.trim() : "";
2298
+ if (!group) throw new Error("close_tab: 'tab_id' or 'group' is required");
2299
+ const closed = [];
2300
+ const refused = [];
2301
+ // tabGroups.query treats `title` as a pattern; compare exactly instead.
2302
+ const groups = (await chromeApi.tabGroups.query({})).filter(
2303
+ (candidate) => candidate.title === group,
2304
+ );
2305
+ for (const { id: groupId } of groups) {
2306
+ for (const tab of await chromeApi.tabs.query({ groupId })) {
2307
+ try {
2308
+ await enforceAllowedOriginFromTab(chromeApi, tab.id, runCtx);
2309
+ } catch {
2310
+ refused.push({ tab_id: tab.id, reason: "outside_allowed_origins" });
2311
+ continue;
2312
+ }
2313
+ try {
2314
+ await enforceTabMutable(chromeApi, "close_tab", tab.id, runCtx);
2315
+ } catch {
2316
+ refused.push({ tab_id: tab.id, reason: "user_tab" });
2317
+ continue;
2318
+ }
2319
+ await chromeApi.tabs.remove(tab.id);
2320
+ await forgetTabLabel(tab.id);
2321
+ closed.push(tab.id);
2322
+ }
2323
+ }
2324
+ return {
2325
+ ok: true,
2326
+ observation: { group, closed, refused, outcome: closed.length > 0 ? "confirmed" : "no_change" },
2327
+ };
2328
+ }
2329
+
2330
+ function normalizeCloseUserTabIds(args) {
2331
+ if (Array.isArray(args?.tab_ids)) {
2332
+ return args.tab_ids;
2333
+ }
2334
+ if (typeof args?.tab_id === "number") {
2335
+ return [args.tab_id];
2336
+ }
2337
+ return null;
2338
+ }
2339
+
2340
+ // close_user_tabs({ tab_ids | tab_id, allow_active? }) — close tabs the user
2341
+ // opened. Requires the opt-in tabs.manage action grant (extension storage,
2342
+ // not a platform capability / Chrome optional permission).
2343
+ async function tool_close_user_tabs(chromeApi, args) {
2344
+ const granted = await isActionGrantEnabled(chromeApi, TABS_MANAGE_SCOPE);
2345
+ if (!granted) {
2346
+ throw new Error(
2347
+ `close_user_tabs: requires the "${TABS_MANAGE_SCOPE}" action grant — enable "Manage open tabs" in Owletto Permissions.`,
2348
+ );
2349
+ }
2350
+ const rawIds = normalizeCloseUserTabIds(args);
2351
+ if (!rawIds || rawIds.length === 0) {
2352
+ throw new Error(
2353
+ "close_user_tabs: 'tab_ids' (array) or 'tab_id' (integer) is required",
2354
+ );
2355
+ }
2356
+ const allowActive = args?.allow_active === true;
2357
+ const closed = [];
2358
+ const refused = [];
2359
+ // Track remaining counts so batch closes in one window don't each think
2360
+ // they are the last tab until only one remains.
2361
+ const remainingByWindow = new Map();
2362
+
2363
+ for (const tabId of rawIds) {
2364
+ if (typeof tabId !== "number" || !Number.isInteger(tabId)) {
2365
+ refused.push({ tab_id: tabId, reason: "invalid_tab_id" });
2366
+ continue;
2367
+ }
2368
+ let tab;
2369
+ try {
2370
+ tab = await chromeApi.tabs.get(tabId);
2371
+ } catch {
2372
+ refused.push({ tab_id: tabId, reason: "not_found" });
2373
+ continue;
2374
+ }
2375
+ if (!tab || tab.id == null) {
2376
+ refused.push({ tab_id: tabId, reason: "not_found" });
2377
+ continue;
2378
+ }
2379
+ if (tab.active && !allowActive) {
2380
+ refused.push({ tab_id: tabId, reason: "active_blocked" });
2381
+ continue;
2382
+ }
2383
+ const windowId = tab.windowId;
2384
+ if (!remainingByWindow.has(windowId)) {
2385
+ const siblings = await chromeApi.tabs.query({ windowId });
2386
+ remainingByWindow.set(
2387
+ windowId,
2388
+ Array.isArray(siblings) ? siblings.length : 1,
2389
+ );
2390
+ }
2391
+ const remaining = remainingByWindow.get(windowId) ?? 1;
2392
+ if (remaining <= 1) {
2393
+ refused.push({ tab_id: tabId, reason: "last_tab_in_window" });
2394
+ continue;
2395
+ }
2396
+ try {
2397
+ await chromeApi.tabs.remove(tabId);
2398
+ await forgetTabLabel(tabId);
2399
+ remainingByWindow.set(windowId, remaining - 1);
2400
+ closed.push(tabId);
2401
+ } catch (err) {
2402
+ refused.push({
2403
+ tab_id: tabId,
2404
+ reason: "close_failed",
2405
+ error: err instanceof Error ? err.message : String(err),
2406
+ });
2407
+ }
2408
+ }
2409
+
2410
+ return {
2411
+ ok: true,
2412
+ observation: {
2413
+ closed,
2414
+ refused,
2415
+ closed_count: closed.length,
2416
+ refused_count: refused.length,
2417
+ outcome: closed.length > 0 ? "confirmed" : "no_change",
2418
+ },
2419
+ };
2420
+ }
2421
+
2422
+ // list_tabs() — every tab with Chrome's own fields (including whether it has a
2423
+ // live page) plus the agent label when there is one. No label means a user tab
2424
+ // (or one from before a restart).
2425
+ // URLs, titles and labels pass through the same redaction as tab snapshots.
2426
+ async function tool_list_tabs(chromeApi, _args, runCtx = {}) {
2427
+ const [tabs, windows, groups, labels] = await Promise.all([
2428
+ chromeApi.tabs.query({}),
2429
+ chromeApi.windows.getAll({}),
2430
+ liveGroupsById(chromeApi),
2431
+ readTabLabels(),
2432
+ ]);
2433
+ const focusedWindows = new Set(
2434
+ windows.filter((w) => w.focused).map((w) => w.id),
2435
+ );
2436
+ return {
2437
+ ok: true,
2438
+ observation: {
2439
+ tabs: tabs.filter((tab) => browserUrlAllowed(tab.url, runCtx.allowedOrigins)).map((tab) => {
2440
+ const groupId =
2441
+ typeof tab.groupId === "number" && tab.groupId >= 0
2442
+ ? tab.groupId
2443
+ : null;
2444
+ return sanitizeBrowserRecord({
2445
+ tab_id: tab.id,
2446
+ window_id: tab.windowId,
2447
+ url: tab.url ?? "",
2448
+ title: tab.title ?? "",
2449
+ active: tab.active === true,
2450
+ window_focused: focusedWindows.has(tab.windowId),
2451
+ last_accessed: tab.lastAccessed ?? null,
2452
+ opener_tab_id: tab.openerTabId ?? null,
2453
+ group_id: groupId,
2454
+ group_title:
2455
+ groupId == null ? null : (groups.get(groupId)?.title ?? null),
2456
+ label: effectiveLabel(labels[String(tab.id)], tab),
2457
+ // "unloaded" or discarded means no live page: the tab answers no
2458
+ // debugger command until it is reloaded.
2459
+ status: tab.status ?? null,
2460
+ discarded: tab.discarded === true,
2461
+ frozen: tab.frozen === true,
2462
+ });
2463
+ }),
2464
+ },
2465
+ };
2466
+ }
2467
+
2468
+ function shortText(value, fallback, maxLen) {
2469
+ const text = typeof value === "string" ? value.trim() : "";
2470
+ return (text || fallback).slice(0, maxLen);
2471
+ }
2472
+
2473
+ async function readNotificationTargets(chromeApi) {
2474
+ const stored = await chromeApi.storage.local.get(NOTIFICATION_TARGETS_KEY);
2475
+ const value = stored[NOTIFICATION_TARGETS_KEY];
2476
+ return value && typeof value === "object" ? value : {};
2477
+ }
2478
+
2479
+ async function writeNotificationTargets(chromeApi, targets) {
2480
+ await chromeApi.storage.local.set({ [NOTIFICATION_TARGETS_KEY]: targets });
2481
+ }
2482
+
2483
+ function normalizeClickUrl(value) {
2484
+ if (typeof value !== "string" || !value.trim()) return null;
2485
+ try {
2486
+ const url = new URL(value.trim());
2487
+ return url.protocol === "http:" || url.protocol === "https:"
2488
+ ? url.toString()
2489
+ : null;
2490
+ } catch {
2491
+ return null;
2492
+ }
2493
+ }
2494
+
2495
+ async function storeNotificationTarget(chromeApi, notificationId, args, runCtx) {
2496
+ const tabId = typeof args?.tab_id === "number" ? args.tab_id : null;
2497
+ const clickUrl = normalizeClickUrl(
2498
+ args?.click_url ?? args?.url ?? args?.landed_url,
2499
+ );
2500
+ if (tabId == null && !clickUrl) return;
2501
+ const targets = await readNotificationTargets(chromeApi);
2502
+ targets[notificationId] = {
2503
+ tab_id: tabId,
2504
+ click_url: clickUrl,
2505
+ allowed_origins: runCtx?.allowedOrigins ?? [],
2506
+ stored_at: Date.now(),
2507
+ };
2508
+ await writeNotificationTargets(chromeApi, targets);
2509
+ }
2510
+
2511
+ export async function handleNotificationClick(chromeApi, notificationId) {
2512
+ const targets = await readNotificationTargets(chromeApi);
2513
+ const target = targets[notificationId];
2514
+ delete targets[notificationId];
2515
+ await writeNotificationTargets(chromeApi, targets);
2516
+ await chromeApi.notifications?.clear?.(notificationId).catch(() => {});
2517
+ if (!target || typeof target !== "object") return;
2518
+ const runCtx = { allowedOrigins: target.allowed_origins ?? [] };
2519
+
2520
+ if (typeof target.tab_id === "number") {
2521
+ try {
2522
+ await enforceAllowedOriginFromTab(chromeApi, target.tab_id, runCtx);
2523
+ await focusChromeTab(chromeApi, target.tab_id);
2524
+ return;
2525
+ } catch {
2526
+ // Tab may have been closed. Fall back to click_url below when present.
2527
+ }
2528
+ }
2529
+
2530
+ if (target.click_url) {
2531
+ // Prefer focusing an existing tab on the same site (e.g. the Revolut tab
2532
+ // the user already has open) over spawning a fresh tab in whatever window
2533
+ // happens to be focused — which is often the side-panel window, not where
2534
+ // the user wants to land.
2535
+ try {
2536
+ const targetHost = new URL(target.click_url).hostname;
2537
+ const baseDomain = targetHost.split(".").slice(-2).join(".");
2538
+ const tabs = await chromeApi.tabs.query({});
2539
+ const match = tabs.find((t) => {
2540
+ if (!t.url || !browserUrlAllowed(t.url, runCtx.allowedOrigins)) return false;
2541
+ try {
2542
+ return new URL(t.url).hostname.endsWith(baseDomain);
2543
+ } catch {
2544
+ return false;
2545
+ }
2546
+ });
2547
+ if (match?.id != null) {
2548
+ await focusChromeTab(chromeApi, match.id);
2549
+ return;
2550
+ }
2551
+ } catch {
2552
+ // Fall through to opening a new tab.
2553
+ }
2554
+ await chromeApi.tabs.create({ url: target.click_url });
2555
+ }
2556
+ }
2557
+
2558
+ async function tool_show_notification(chromeApi, args, runCtx) {
2559
+ if (typeof args?.tab_id === "number") await enforceAllowedOriginFromTab(chromeApi, args.tab_id, runCtx);
2560
+ const clickUrl = normalizeClickUrl(args?.click_url ?? args?.url ?? args?.landed_url);
2561
+ if (clickUrl) enforceAllowedOrigin(clickUrl, runCtx);
2562
+ const title = shortText(args?.title, "Owletto needs attention", 80);
2563
+ const message = shortText(
2564
+ args?.message ?? args?.body,
2565
+ "Open Owletto for details.",
2566
+ 240,
2567
+ );
2568
+ const notificationId = shortText(
2569
+ args?.notification_id,
2570
+ `owletto-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
2571
+ 120,
2572
+ );
2573
+
2574
+ const granted = await chromeApi.permissions
2575
+ .contains({ permissions: ["notifications"] })
2576
+ .catch(() => false);
2577
+ if (!granted) {
2578
+ return {
2579
+ ok: true,
2580
+ observation: {
2581
+ shown: false,
2582
+ reason: "permission_not_granted",
2583
+ notification_id: notificationId,
2584
+ outcome: "no_change",
2585
+ },
2586
+ };
2587
+ }
2588
+ if (!chromeApi.notifications?.create) {
2589
+ return {
2590
+ ok: false,
2591
+ error: "show_notification: chrome.notifications API is unavailable",
2592
+ };
2593
+ }
2594
+
2595
+ await storeNotificationTarget(chromeApi, notificationId, args, runCtx);
2596
+ await chromeApi.notifications.create(notificationId, {
2597
+ type: "basic",
2598
+ iconUrl: chromeApi.runtime.getURL("icons/icon-128.png"),
2599
+ title,
2600
+ message,
2601
+ });
2602
+
2603
+ return {
2604
+ ok: true,
2605
+ observation: { shown: true, notification_id: notificationId, outcome: "confirmed" },
2606
+ };
2607
+ }
2608
+
2609
+ // open_tabs feed run — uses chrome.tabs.query, no debugger needed.
2610
+ // Returns the peek-then-commit transaction shape so the dispatcher's
2611
+ // feed path is uniform across all feeds. open_tabs has no buffer or
2612
+ // sentinel to commit, so commit is a no-op.
2613
+ /**
2614
+ * Live group metadata by group id, for the tab snapshot. Read from Chrome
2615
+ * rather than the extension's own store so USER-created groups are reported
2616
+ * too — the snapshot describes the browser as the human sees it, not just the
2617
+ * containers we own. A group that disappears mid-collection is simply absent,
2618
+ * and its tabs report null rather than a stale title invented from storage.
2619
+ */
2620
+ async function liveGroupsById(chromeApi) {
2621
+ const byId = new Map();
2622
+ if (!chromeApi?.tabGroups?.query) return byId;
2623
+ try {
2624
+ const groups = await chromeApi.tabGroups.query({});
2625
+ for (const g of Array.isArray(groups) ? groups : []) {
2626
+ if (typeof g?.id === "number") byId.set(g.id, g);
2627
+ }
2628
+ } catch {
2629
+ // tabGroups unavailable (permission or older Chrome) — omit the fields.
2630
+ }
2631
+ return byId;
2632
+ }
2633
+
2634
+ export async function feed_open_tabs(chromeApi) {
2635
+ const tabs = await chromeApi.tabs.query({});
2636
+ const groups = await liveGroupsById(chromeApi);
2637
+ const now = new Date().toISOString();
2638
+ const items = tabs
2639
+ .filter((t) => typeof t.url === "string" && t.url.length > 0)
2640
+ .map((raw) => {
2641
+ const t = sanitizeBrowserRecord(raw);
2642
+ // Chrome uses -1 (TAB_GROUP_ID_NONE) for an ungrouped tab; normalize
2643
+ // that sentinel to null so consumers never see a magic number.
2644
+ const groupId =
2645
+ typeof t.groupId === "number" && t.groupId >= 0 ? t.groupId : null;
2646
+ const group = groupId == null ? null : groups.get(groupId);
2647
+ return {
2648
+ id: `tab-${t.id}`,
2649
+ title: t.title ?? t.url,
2650
+ payload_type: "text",
2651
+ payload_text: t.title ? `${t.title}\n${t.url}` : t.url,
2652
+ occurred_at: now,
2653
+ source_url: t.url,
2654
+ origin_type: "tab_snapshot",
2655
+ semantic_type: "tab_snapshot",
2656
+ metadata: {
2657
+ source: "chrome_tabs",
2658
+ origin_id: `tab-${t.id}`,
2659
+ url: t.url,
2660
+ title: t.title,
2661
+ window_id: t.windowId,
2662
+ active: t.active,
2663
+ group_id: groupId,
2664
+ // The group record comes from a separate live-Chrome lookup, so
2665
+ // sanitizeBrowserRecord above never saw it. A user can rename a
2666
+ // group to anything — a pasted OAuth callback URL included — and
2667
+ // this field ships to the feed, so it obeys the same redaction
2668
+ // contract as url/title.
2669
+ group_title: group ? sanitizeBrowserText(group.title ?? "") : null,
2670
+ group_color: group ? (group.color ?? null) : null,
2671
+ },
2672
+ };
2673
+ });
2674
+ return { items, commit: async () => {} };
2675
+ }
2676
+
2677
+ // ── support ────────────────────────────────────────────────────────────
2678
+
2679
+ const ACCESSIBILITY_SCRIPT_URL_CACHE = { code: null };
2680
+
2681
+ // Inject the accessibility walker into a fresh CDP isolated world for the
2682
+ // tab's main frame and return its executionContextId. An isolated world is a
2683
+ // separate JS realm that shares the DOM, so the walker's globals (__lobuExtract
2684
+ // / __lobuFocusBbox) are invisible to page JS — page code can't observe or
2685
+ // forge them. The world is per-injection/ephemeral; cross-run state (the
2686
+ // ref→element mapping + epoch) rides DOM attributes (see accessibility-tree.js),
2687
+ // so a brand-new world on each call is fine. Re-running the script just
2688
+ // redefines the globals on that world's globalThis.
2689
+ async function injectAccessibilityScript(chromeApi, tabId) {
2690
+ if (!ACCESSIBILITY_SCRIPT_URL_CACHE.code) {
2691
+ const res = await fetch(chromeApi.runtime.getURL("accessibility-tree.js"));
2692
+ ACCESSIBILITY_SCRIPT_URL_CACHE.code = await res.text();
2693
+ }
2694
+ await chromeApi.debugger.sendCommand(dbgTarget(tabId), "Page.enable");
2695
+ const frameTree = await chromeApi.debugger.sendCommand(
2696
+ dbgTarget(tabId),
2697
+ "Page.getFrameTree",
2698
+ );
2699
+ const frameId = frameTree?.frameTree?.frame?.id;
2700
+ if (!frameId)
2701
+ throw new Error("get_accessibility_tree: could not resolve main frame");
2702
+ const world = await chromeApi.debugger.sendCommand(
2703
+ dbgTarget(tabId),
2704
+ "Page.createIsolatedWorld",
2705
+ {
2706
+ frameId,
2707
+ worldName: "lobu_ax",
2708
+ },
2709
+ );
2710
+ const contextId = world?.executionContextId;
2711
+ if (contextId == null)
2712
+ throw new Error("get_accessibility_tree: could not create isolated world");
2713
+ const result = await chromeApi.debugger.sendCommand(
2714
+ dbgTarget(tabId),
2715
+ "Runtime.evaluate",
2716
+ {
2717
+ expression: ACCESSIBILITY_SCRIPT_URL_CACHE.code,
2718
+ contextId,
2719
+ returnByValue: true,
2720
+ },
2721
+ );
2722
+ if (result?.exceptionDetails) {
2723
+ throw new Error("get_accessibility_tree: walker injection failed");
2724
+ }
2725
+ return contextId;
2726
+ }
2727
+
2728
+ // Like evalInPage but targets a specific (isolated-world) execution context.
2729
+ async function evalInContext(
2730
+ chromeApi,
2731
+ tabId,
2732
+ contextId,
2733
+ expression,
2734
+ awaitPromise = true,
2735
+ ) {
2736
+ const result = await chromeApi.debugger.sendCommand(
2737
+ dbgTarget(tabId),
2738
+ "Runtime.evaluate",
2739
+ {
2740
+ expression,
2741
+ contextId,
2742
+ awaitPromise,
2743
+ returnByValue: true,
2744
+ userGesture: true,
2745
+ },
2746
+ );
2747
+ if (result?.exceptionDetails) {
2748
+ const e = result.exceptionDetails;
2749
+ const msg = e?.exception?.description ?? e?.text ?? "evaluation failed";
2750
+ const err = new Error(msg);
2751
+ err.exceptionDetails = e;
2752
+ throw err;
2753
+ }
2754
+ return result?.result?.value;
2755
+ }
2756
+
2757
+ // Like evalInContext but returns the CDP objectId of the expression's result
2758
+ // (returnByValue:false) instead of its JSON value. Returns null when the
2759
+ // expression evaluated to null/undefined (no remote object handle). Used to
2760
+ // hand a resolved DOM node to node-target CDP commands like
2761
+ // DOM.setFileInputFiles. Throws on evaluation exception, mirroring evalInContext.
2762
+ async function evalInContextObjectId(chromeApi, tabId, contextId, expression) {
2763
+ const result = await chromeApi.debugger.sendCommand(
2764
+ dbgTarget(tabId),
2765
+ "Runtime.evaluate",
2766
+ {
2767
+ expression,
2768
+ contextId,
2769
+ returnByValue: false,
2770
+ userGesture: true,
2771
+ },
2772
+ );
2773
+ if (result?.exceptionDetails) {
2774
+ const e = result.exceptionDetails;
2775
+ const msg = e?.exception?.description ?? e?.text ?? "evaluation failed";
2776
+ const err = new Error(msg);
2777
+ err.exceptionDetails = e;
2778
+ throw err;
2779
+ }
2780
+ return result?.result?.objectId ?? null;
2781
+ }
2782
+
2783
+ async function dispatchMouse(chromeApi, tabId, type, x, y, button, clickCount) {
2784
+ await chromeApi.debugger.sendCommand(
2785
+ dbgTarget(tabId),
2786
+ "Input.dispatchMouseEvent",
2787
+ {
2788
+ type,
2789
+ x,
2790
+ y,
2791
+ button,
2792
+ clickCount,
2793
+ buttons: button === "left" ? 1 : button === "right" ? 2 : 4,
2794
+ },
2795
+ );
2796
+ }
2797
+
2798
+ function sleep(ms) {
2799
+ return new Promise((r) => setTimeout(r, ms));
2800
+ }
2801
+
2802
+ // A run needed a site this profile hasn't granted. Carries the origin so the
2803
+ // panel can offer the one-click grant; the message is what the agent relays.
2804
+ export class SiteAccessRequiredError extends Error {
2805
+ constructor(origin) {
2806
+ super(
2807
+ `Lobu for Chrome can't access ${origin} yet. Ask the user to click "Allow" in the Lobu side panel (or grant the site in its Settings), then retry.`,
2808
+ );
2809
+ this.name = "SiteAccessRequiredError";
2810
+ this.origin = origin;
2811
+ }
2812
+ }
2813
+
2814
+ // Headless runs can't prompt for a host permission — chrome.permissions.request
2815
+ // needs a user gesture and the poll loop has none. The extension ships no site
2816
+ // in host_permissions anymore; the user grants <all_urls> or per-site from the
2817
+ // panel. If the grant is missing, fail with a message that points there, rather
2818
+ // than the raw "Cannot access contents of url" that executeScript/debugger.attach
2819
+ // would throw deeper in.
2820
+ async function assertHostPermission(chromeApi, url) {
2821
+ if (url === "about:blank") return;
2822
+ let origin;
2823
+ try {
2824
+ origin = new URL(url).origin;
2825
+ } catch {
2826
+ return; // enforceAllowedOrigin already rejects malformed URLs
2827
+ }
2828
+ const granted = await chromeApi.permissions.contains({
2829
+ origins: [`${origin}/*`],
2830
+ });
2831
+ if (!granted) throw new SiteAccessRequiredError(origin);
2832
+ }
2833
+
2834
+ function enforceAllowedOrigin(url, runCtx) {
2835
+ if (!runCtx.allowedOrigins || runCtx.allowedOrigins.length === 0) return;
2836
+ // about:blank is the scratch-tab setup URL used by extensionNetworkSync
2837
+ // (open scratch tab → start network intercept → navigate to real URL).
2838
+ // It carries no origin, so the host allowlist doesn't meaningfully apply
2839
+ // — and rejecting it would block the only safe ordering for capturing
2840
+ // initial-render XHRs. Always allowed.
2841
+ if (url === "about:blank") return;
2842
+ let origin;
2843
+ try {
2844
+ origin = new URL(url).origin;
2845
+ } catch {
2846
+ throw new Error(`enforceAllowedOrigin: '${url}' is not a valid URL`);
2847
+ }
2848
+ if (browserUrlAllowed(url, runCtx.allowedOrigins)) return;
2849
+ throw new Error(
2850
+ `enforceAllowedOrigin: '${origin}' is not in allowedOrigins [${runCtx.allowedOrigins.join(", ")}]`,
2851
+ );
2852
+ }
2853
+
2854
+ /**
2855
+ * Gate a MUTATING action on the target tab.
2856
+ *
2857
+ * Reads stay open: every agent may list, screenshot and inspect any tab.
2858
+ * Labelled agent tabs are open to every agent too — agents see each other's
2859
+ * tabs and may take one over (navigate reports busy_by when it does). Only an
2860
+ * unlabelled tab, the user's own, needs authority: the gateway's page
2861
+ * activation for that exact tab, or the user's "Manage open tabs" grant.
2862
+ */
2863
+ async function enforceTabMutable(chromeApi, action, tabId, runCtx) {
2864
+ await assertRecoveryTab(chromeApi, tabId, runCtx);
2865
+ // A page-activated run acts on a tab the USER opened; the human's visit is
2866
+ // the whole authorization, and the gateway is the only party that knows
2867
+ // which tab that was. It resolved the id and target URLs from the parent run
2868
+ // and stamped them through trustedChromeActionInput, which strips any
2869
+ // caller-supplied copy first. Exact match only: the one tab the human
2870
+ // opened, still on one of the exact target pages, never an agent tab.
2871
+ if (runCtx?.activationTabId != null) {
2872
+ const tab = await chromeApi.tabs.get(tabId);
2873
+ if (
2874
+ tabId !== runCtx.activationTabId ||
2875
+ !tab?.url ||
2876
+ tab.pendingUrl ||
2877
+ !runCtx.activationTargetUrls?.includes(normalizePageUrl(tab.url)) ||
2878
+ (await agentLabelFor(chromeApi, tabId))
2879
+ ) {
2880
+ throw new Error(
2881
+ `${action}: activated tab is no longer on its exact user-owned target page`,
2882
+ );
2883
+ }
2884
+ return;
2885
+ }
2886
+ if (await agentLabelFor(chromeApi, tabId)) {
2887
+ await touchTabLabel(tabId, runCtx);
2888
+ return;
2889
+ }
2890
+ if (await isActionGrantEnabled(chromeApi, TABS_MANAGE_SCOPE)) return;
2891
+ throw new Error(
2892
+ `${action}: tab ${tabId} is the user's tab. Agents may read it (list_tabs, get_accessibility_tree, screenshot, wait_for_selector), but acting on it needs "Manage open tabs" in Owletto Permissions. Use navigate to open or reuse an agent tab instead.`,
2893
+ );
2894
+ }
2895
+
2896
+ async function enforceAllowedOriginFromTab(chromeApi, tabId, runCtx) {
2897
+ await assertRecoveryTab(chromeApi, tabId, runCtx);
2898
+ if (!runCtx.allowedOrigins || runCtx.allowedOrigins.length === 0) return;
2899
+ const tab = await chromeApi.tabs.get(tabId);
2900
+ // Fail closed: a missing URL means we can't verify the policy, so we
2901
+ // refuse the action rather than silently letting it through.
2902
+ if (!tab?.url) {
2903
+ throw new Error(
2904
+ `enforceAllowedOriginFromTab: tab ${tabId} has no URL to validate against allowedOrigins [${runCtx.allowedOrigins.join(", ")}]`,
2905
+ );
2906
+ }
2907
+ enforceAllowedOrigin(tab.url, runCtx);
2908
+ }
2909
+
2910
+ // ── outcome ────────────────────────────────────────────────────────────
2911
+ //
2912
+ // Every action reports `outcome`: "confirmed" when a read-back shows the
2913
+ // effect, "no_change" when the page is observably as it was, "unverifiable"
2914
+ // when nothing could be read back (the document went away mid-action, or the
2915
+ // action has no observable effect of its own).
2916
+
2917
+ // Long enough for a handler's synchronous re-render and a microtask-driven
2918
+ // framework update; a page that answers later reads as no_change, which tells
2919
+ // the agent to look again rather than claiming success.
2920
+ const OUTCOME_SETTLE_MS = 150;
2921
+
2922
+ async function startWatch(chromeApi, tabId, ctxId) {
2923
+ try {
2924
+ return await evalInContext(chromeApi, tabId, ctxId, "__lobuWatchStart()");
2925
+ } catch {
2926
+ return null;
2927
+ }
2928
+ }
2929
+
2930
+ async function finishWatch(chromeApi, tabId, ctxId, startHref) {
2931
+ await sleep(OUTCOME_SETTLE_MS);
2932
+ try {
2933
+ const watched = await evalInContext(chromeApi, tabId, ctxId, "__lobuWatchResult()");
2934
+ if (watched) return watched.changed ? "confirmed" : "no_change";
2935
+ } catch {
2936
+ // The world went with its document: the action navigated, or the page
2937
+ // replaced itself. The tab's URL still tells a navigation apart.
2938
+ }
2939
+ const tab = await chromeApi.tabs.get(tabId).catch(() => null);
2940
+ const href = tab?.pendingUrl || tab?.url;
2941
+ if (startHref && href && href !== startHref) return "confirmed";
2942
+ return "unverifiable";
2943
+ }
2944
+
2945
+ function refArg(action, args) {
2946
+ const ref = args?.ref;
2947
+ if (!ref || typeof ref !== "object") throw new Error(`${action}: 'ref' is required`);
2948
+ return ref;
2949
+ }
2950
+
2951
+ function actionTab(action, args, runCtx) {
2952
+ const tabId = args?.tab_id ?? runCtx.scratchTabId;
2953
+ if (tabId == null) throw new Error(`${action}: no tab`);
2954
+ return tabId;
2955
+ }
2956
+
2957
+ function mutatingAuthorize(chromeApi, action, tabId, runCtx) {
2958
+ return async () => {
2959
+ await enforceAllowedOriginFromTab(chromeApi, tabId, runCtx);
2960
+ await enforceTabMutable(chromeApi, action, tabId, runCtx);
2961
+ };
2962
+ }
2963
+
2964
+ // ── press_key ──────────────────────────────────────────────────────────
2965
+
2966
+ // Named keys: DOM `key` → [`code`, Windows virtual key code, text]. A key with
2967
+ // text (Enter, Space) is sent as keyDown so Chrome runs its default action
2968
+ // (implicit form submission, a button's activation); the rest as rawKeyDown.
2969
+ const NAMED_KEYS = new Map([
2970
+ ["Enter", ["Enter", 13, "\r"]],
2971
+ ["Tab", ["Tab", 9, ""]],
2972
+ ["Escape", ["Escape", 27, ""]],
2973
+ ["Backspace", ["Backspace", 8, ""]],
2974
+ ["Delete", ["Delete", 46, ""]],
2975
+ ["ArrowLeft", ["ArrowLeft", 37, ""]],
2976
+ ["ArrowUp", ["ArrowUp", 38, ""]],
2977
+ ["ArrowRight", ["ArrowRight", 39, ""]],
2978
+ ["ArrowDown", ["ArrowDown", 40, ""]],
2979
+ ["Home", ["Home", 36, ""]],
2980
+ ["End", ["End", 35, ""]],
2981
+ ["PageUp", ["PageUp", 33, ""]],
2982
+ ["PageDown", ["PageDown", 34, ""]],
2983
+ [" ", ["Space", 32, " "]],
2984
+ ]);
2985
+
2986
+ // CDP Input modifier bits.
2987
+ const MODIFIER_BITS = new Map([
2988
+ ["Alt", 1],
2989
+ ["Control", 2],
2990
+ ["Meta", 4],
2991
+ ["Shift", 8],
2992
+ ]);
2993
+
2994
+ const LOWER_A = "a".charCodeAt(0);
2995
+ const LOWER_Z = "z".charCodeAt(0);
2996
+ const DIGIT_0 = "0".charCodeAt(0);
2997
+ const DIGIT_9 = "9".charCodeAt(0);
2998
+
2999
+ // Resolve a DOM key name ("Enter", "a", "7", "/") to the CDP key event fields.
3000
+ // Returns null for a key outside the table and longer than one character.
3001
+ export function keyEventFields(key) {
3002
+ const named = NAMED_KEYS.get(key);
3003
+ if (named) {
3004
+ const [code, keyCode, text] = named;
3005
+ return { key, code, keyCode, text };
3006
+ }
3007
+ if (typeof key !== "string" || [...key].length !== 1) return null;
3008
+ const lower = key.toLowerCase().charCodeAt(0);
3009
+ if (key.length === 1 && lower >= LOWER_A && lower <= LOWER_Z) {
3010
+ const upper = key.toUpperCase();
3011
+ return { key, code: `Key${upper}`, keyCode: upper.charCodeAt(0), text: key };
3012
+ }
3013
+ const point = key.charCodeAt(0);
3014
+ if (key.length === 1 && point >= DIGIT_0 && point <= DIGIT_9) {
3015
+ return { key, code: `Digit${key}`, keyCode: point, text: key };
3016
+ }
3017
+ return { key, code: "", keyCode: 0, text: key };
3018
+ }
3019
+
3020
+ const FOCUS_WAIT_STEPS = 20;
3021
+ const FOCUS_WAIT_STEP_MS = 25;
3022
+ async function untilPageFocused(chromeApi, tabId, ctxId) {
3023
+ for (let step = 0; step < FOCUS_WAIT_STEPS; step++) {
3024
+ if (await evalInContext(chromeApi, tabId, ctxId, "document.hasFocus()")) return;
3025
+ await sleep(FOCUS_WAIT_STEP_MS);
3026
+ }
3027
+ }
3028
+
3029
+ async function keyDelivered(chromeApi, tabId, ctxId) {
3030
+ for (let step = 0; step < 4; step++) {
3031
+ if ((await evalInContext(chromeApi, tabId, ctxId, "__lobuKeysReceived()")) > 0) return true;
3032
+ await sleep(FOCUS_WAIT_STEP_MS);
3033
+ }
3034
+ return false;
3035
+ }
3036
+
3037
+ // press_key({ key, modifiers?, ref?, tab_id? })
3038
+ //
3039
+ // A trusted key press (Input.dispatchKeyEvent) to the focused element, or to
3040
+ // `ref` after focusing it. Chrome drops key input to a background tab, so the
3041
+ // press runs under focus emulation (Emulation.setFocusEmulationEnabled): the
3042
+ // page sees itself focused and visible for the press, and the tab is never
3043
+ // brought to the front. With a modifier held the key carries no text, so
3044
+ // Control+K reaches a page's shortcut handler without typing a "k".
3045
+ async function tool_press_key(chromeApi, args, runCtx) {
3046
+ const fields = keyEventFields(args?.key);
3047
+ if (!fields)
3048
+ throw new Error(
3049
+ `press_key: unknown key ${JSON.stringify(args?.key)}; use a single character or one of ${[...NAMED_KEYS.keys()].map((k) => JSON.stringify(k)).join(", ")}`,
3050
+ );
3051
+ const modifiers = args?.modifiers ?? [];
3052
+ if (!Array.isArray(modifiers) || !modifiers.every((m) => MODIFIER_BITS.has(m)))
3053
+ throw new Error(`press_key: 'modifiers' must be a list of ${[...MODIFIER_BITS.keys()].join(", ")}`);
3054
+ const bits = modifiers.reduce((sum, m) => sum | MODIFIER_BITS.get(m), 0);
3055
+ const shiftOnly = bits === 0 || bits === MODIFIER_BITS.get("Shift");
3056
+ const text = shiftOnly ? fields.text : "";
3057
+ const ref = args?.ref == null ? null : refArg("press_key", args);
3058
+ const tabId = actionTab("press_key", args, runCtx);
3059
+
3060
+ return withDebugger(chromeApi, tabId, async () => {
3061
+ const ctxId = await injectAccessibilityScript(chromeApi, tabId);
3062
+ if (ref) {
3063
+ const bbox = await evalInContext(
3064
+ chromeApi,
3065
+ tabId,
3066
+ ctxId,
3067
+ `JSON.stringify(__lobuFocusBbox(${JSON.stringify(ref.ref_id)}, ${JSON.stringify(ref.document_epoch)}))`,
3068
+ );
3069
+ if (!bbox || bbox === "null") throw new Error(`press_key: stale ref (epoch ${ref.document_epoch})`);
3070
+ }
3071
+ const startHref = await startWatch(chromeApi, tabId, ctxId);
3072
+ const send = (params) =>
3073
+ chromeApi.debugger.sendCommand(dbgTarget(tabId), "Input.dispatchKeyEvent", {
3074
+ key: fields.key,
3075
+ code: fields.code,
3076
+ windowsVirtualKeyCode: fields.keyCode,
3077
+ modifiers: bits,
3078
+ ...params,
3079
+ });
3080
+ await chromeApi.debugger.sendCommand(dbgTarget(tabId), "Emulation.setFocusEmulationEnabled", {
3081
+ enabled: true,
3082
+ });
3083
+ try {
3084
+ // The renderer applies emulated focus asynchronously; a key sent
3085
+ // before the page reports focus can be dropped (seen as a Tab that
3086
+ // moved nothing). Wait for it, briefly.
3087
+ await untilPageFocused(chromeApi, tabId, ctxId);
3088
+ await evalInContext(chromeApi, tabId, ctxId, "__lobuKeysStart()");
3089
+ const press = async () => {
3090
+ await send(text ? { type: "keyDown", text, unmodifiedText: text } : { type: "rawKeyDown" });
3091
+ await send({ type: "keyUp" });
3092
+ };
3093
+ await press();
3094
+ // Chrome can drop a press to a background page even under focus
3095
+ // emulation. A press the page never saw had no effect, so it is safe
3096
+ // to send once more; one it saw is never repeated.
3097
+ if (!(await keyDelivered(chromeApi, tabId, ctxId))) {
3098
+ await press();
3099
+ if (!(await keyDelivered(chromeApi, tabId, ctxId)))
3100
+ throw new Error(
3101
+ `press_key: Chrome did not deliver ${fields.key} to tab ${tabId}; nothing was pressed. Call focus_tab and retry`,
3102
+ );
3103
+ }
3104
+ } finally {
3105
+ // A page left emulating focus would stay "visible" behind the user's
3106
+ // tab. Best effort: the press may have navigated or detached.
3107
+ await chromeApi.debugger
3108
+ .sendCommand(dbgTarget(tabId), "Emulation.setFocusEmulationEnabled", { enabled: false })
3109
+ .catch(() => {});
3110
+ }
3111
+ return {
3112
+ ok: true,
3113
+ observation: {
3114
+ tab_id: tabId,
3115
+ key: fields.key,
3116
+ modifiers,
3117
+ outcome: await finishWatch(chromeApi, tabId, ctxId, startHref),
3118
+ },
3119
+ };
3120
+ }, mutatingAuthorize(chromeApi, "press_key", tabId, runCtx));
3121
+ }
3122
+
3123
+ // hover_ref({ ref, tab_id? })
3124
+ //
3125
+ // Moves the mouse onto the element's centre with a trusted mouseMoved, which
3126
+ // Chrome delivers to background tabs too: :hover styles apply and
3127
+ // mouseover/mouseenter fire, so hover menus and tooltips open. Refuses a
3128
+ // point something else covers, as a click would.
3129
+ async function tool_hover_ref(chromeApi, args, runCtx) {
3130
+ const ref = refArg("hover_ref", args);
3131
+ const tabId = actionTab("hover_ref", args, runCtx);
3132
+ const refExpr = `${JSON.stringify(ref.ref_id)}, ${JSON.stringify(ref.document_epoch)}`;
3133
+ return withDebugger(chromeApi, tabId, async () => {
3134
+ const ctxId = await injectAccessibilityScript(chromeApi, tabId);
3135
+ const bboxJson = await evalInContext(chromeApi, tabId, ctxId, `JSON.stringify(__lobuBbox(${refExpr}))`);
3136
+ const bbox = typeof bboxJson === "string" ? JSON.parse(bboxJson) : bboxJson;
3137
+ if (!bbox) throw new Error(`hover_ref: stale ref (epoch ${ref.document_epoch})`);
3138
+ const blocked = await evalInContext(chromeApi, tabId, ctxId, `__lobuHitTest(${refExpr})`);
3139
+ if (blocked === "stale") throw new Error(`hover_ref: stale ref (epoch ${ref.document_epoch})`);
3140
+ if (blocked != null)
3141
+ throw new Error(`hover_ref: the element is ${blocked}; a user could not hover it either`);
3142
+ await evalInContext(chromeApi, tabId, ctxId, `__lobuPointerStart(${refExpr})`);
3143
+ await chromeApi.debugger.sendCommand(dbgTarget(tabId), "Input.dispatchMouseEvent", {
3144
+ type: "mouseMoved",
3145
+ x: bbox.x,
3146
+ y: bbox.y,
3147
+ button: "none",
3148
+ buttons: 0,
3149
+ });
3150
+ const hovered = await evalInContext(chromeApi, tabId, ctxId, `__lobuHovered(${refExpr})`);
3151
+ if (hovered === "stale") throw new Error(`hover_ref: stale ref (epoch ${ref.document_epoch})`);
3152
+ return {
3153
+ ok: true,
3154
+ observation: { tab_id: tabId, hovered: { x: bbox.x, y: bbox.y }, outcome: hovered },
3155
+ };
3156
+ }, mutatingAuthorize(chromeApi, "hover_ref", tabId, runCtx));
3157
+ }
3158
+
3159
+ // scroll({ ref?, delta_x?, delta_y?, tab_id? })
3160
+ //
3161
+ // With a delta: scrolls the page, or with a ref the ref's own scroll
3162
+ // container (an inner feed pane), by that many CSS pixels. With only a ref:
3163
+ // brings it into view. Runs in the page, so a background tab scrolls too and
3164
+ // the page's scroll/lazy-load handlers fire. Reports whether anything moved
3165
+ // and whether the container is at its end, so a pager knows when to stop.
3166
+ async function tool_scroll(chromeApi, args, runCtx) {
3167
+ const ref = args?.ref == null ? null : refArg("scroll", args);
3168
+ const delta = (name) => {
3169
+ const value = args?.[name] ?? 0;
3170
+ if (typeof value !== "number" || !Number.isFinite(value))
3171
+ throw new Error(`scroll: '${name}' must be a number of pixels`);
3172
+ return value;
3173
+ };
3174
+ const dx = delta("delta_x");
3175
+ const dy = delta("delta_y");
3176
+ if (!ref && dx === 0 && dy === 0)
3177
+ throw new Error("scroll: give a 'ref' to bring into view, or a 'delta_x'/'delta_y'");
3178
+ const tabId = actionTab("scroll", args, runCtx);
3179
+ return withDebugger(chromeApi, tabId, async () => {
3180
+ const ctxId = await injectAccessibilityScript(chromeApi, tabId);
3181
+ const scrolled = await evalInContext(
3182
+ chromeApi,
3183
+ tabId,
3184
+ ctxId,
3185
+ `__lobuScrollBy(${JSON.stringify(ref?.ref_id ?? null)}, ${JSON.stringify(ref?.document_epoch ?? null)}, ${JSON.stringify(dx)}, ${JSON.stringify(dy)})`,
3186
+ );
3187
+ if (!scrolled || scrolled.stale)
3188
+ throw new Error(`scroll: stale ref (epoch ${ref?.document_epoch})`);
3189
+ return {
3190
+ ok: true,
3191
+ observation: {
3192
+ tab_id: tabId,
3193
+ moved: scrolled.moved,
3194
+ scroll_x: scrolled.x,
3195
+ scroll_y: scrolled.y,
3196
+ at_end: scrolled.at_end,
3197
+ outcome: scrolled.moved ? "confirmed" : "no_change",
3198
+ },
3199
+ };
3200
+ }, mutatingAuthorize(chromeApi, "scroll", tabId, runCtx));
3201
+ }
3202
+
3203
+ // select_option({ ref, value? | label?, tab_id? })
3204
+ //
3205
+ // Picks an option of a native <select> as the user's pick does (the
3206
+ // selectedIndex setter, then input and change) and reads the selection back.
3207
+ // Custom dropdowns are not selects: click them open and click the option.
3208
+ const SELECT_REFUSALS = new Map([
3209
+ ["not-select", "is not a native <select>; open a custom dropdown with click_ref and click its option"],
3210
+ ["multiple", "is a multi-select, which select_option does not drive"],
3211
+ ["disabled", "is disabled"],
3212
+ ["option-disabled", "has that option disabled"],
3213
+ ["failed", "did not keep the selection (a page handler reset it)"],
3214
+ ]);
3215
+
3216
+ async function tool_select_option(chromeApi, args, runCtx) {
3217
+ const ref = refArg("select_option", args);
3218
+ const value = typeof args?.value === "string" ? args.value : null;
3219
+ const label = typeof args?.label === "string" ? args.label : null;
3220
+ if ((value == null) === (label == null))
3221
+ throw new Error("select_option: give exactly one of 'value' or 'label'");
3222
+ const tabId = actionTab("select_option", args, runCtx);
3223
+ return withDebugger(chromeApi, tabId, async () => {
3224
+ const ctxId = await injectAccessibilityScript(chromeApi, tabId);
3225
+ const picked = await evalInContext(
3226
+ chromeApi,
3227
+ tabId,
3228
+ ctxId,
3229
+ `__lobuSelectOption(${JSON.stringify(ref.ref_id)}, ${JSON.stringify(ref.document_epoch)}, ${JSON.stringify(value)}, ${JSON.stringify(label)})`,
3230
+ );
3231
+ const status = picked?.status;
3232
+ if (status === "stale" || status == null)
3233
+ throw new Error(`select_option: stale ref (epoch ${ref.document_epoch})`);
3234
+ if (status === "no-option")
3235
+ throw new Error(
3236
+ `select_option: no option with ${value != null ? `value ${JSON.stringify(value)}` : `label ${JSON.stringify(label)}`}; options: ${(picked.available ?? []).map((o) => JSON.stringify(o)).join(", ")}`,
3237
+ );
3238
+ if (SELECT_REFUSALS.has(status))
3239
+ throw new Error(`select_option: the element ${SELECT_REFUSALS.get(status)}; nothing was selected`);
3240
+ return {
3241
+ ok: true,
3242
+ observation: {
3243
+ tab_id: tabId,
3244
+ selected: { value: picked.value, label: picked.label },
3245
+ outcome: status === "done" ? "confirmed" : "no_change",
3246
+ },
3247
+ };
3248
+ }, mutatingAuthorize(chromeApi, "select_option", tabId, runCtx));
3249
+ }
3250
+
3251
+ // handle_dialog({ dialog_id, accept, prompt_text?, tab_id? })
3252
+ //
3253
+ // Answers the JS dialog an earlier action reported. Outside the tab lock on
3254
+ // purpose: the interrupted action still holds it, frozen until this answer.
3255
+ const DIALOG_CLOSE_TIMEOUT_MS = 5_000;
3256
+
3257
+ async function tool_handle_dialog(chromeApi, args, runCtx) {
3258
+ const dialogId = args?.dialog_id;
3259
+ if (typeof dialogId !== "string" || !dialogId)
3260
+ throw new Error("handle_dialog: 'dialog_id' is required");
3261
+ if (typeof args?.accept !== "boolean") throw new Error("handle_dialog: 'accept' must be true or false");
3262
+ if (args.prompt_text != null && typeof args.prompt_text !== "string")
3263
+ throw new Error("handle_dialog: 'prompt_text' must be a string");
3264
+ const tabId = actionTab("handle_dialog", args, runCtx);
3265
+ await mutatingAuthorize(chromeApi, "handle_dialog", tabId, runCtx)();
3266
+ const dialog = openDialog(tabId);
3267
+ if (dialog?.dialog_id !== dialogId)
3268
+ throw new Error(
3269
+ dialog
3270
+ ? `handle_dialog: the open dialog on tab ${tabId} is ${dialog.dialog_id}, not ${dialogId}`
3271
+ : `handle_dialog: no dialog is open on tab ${tabId} (it was answered, or the debugger let go of the tab and Chrome is showing it to the user)`,
3272
+ );
3273
+ const lease = await acquireDebuggerLease(chromeApi, tabId);
3274
+ const closed = whenDialogCloses(tabId);
3275
+ let timer;
3276
+ try {
3277
+ await chromeApi.debugger.sendCommand(dbgTarget(tabId), "Page.handleJavaScriptDialog", {
3278
+ accept: args.accept,
3279
+ ...(args.prompt_text != null && args.accept ? { promptText: args.prompt_text } : {}),
3280
+ });
3281
+ const result = await Promise.race([
3282
+ closed.promise,
3283
+ new Promise((resolve) => {
3284
+ timer = setTimeout(() => resolve(undefined), DIALOG_CLOSE_TIMEOUT_MS);
3285
+ }),
3286
+ ]);
3287
+ return {
3288
+ ok: true,
3289
+ observation: {
3290
+ tab_id: tabId,
3291
+ dialog_id: dialogId,
3292
+ accepted: args.accept,
3293
+ // Chrome reports how the dialog closed; that is the read-back.
3294
+ outcome: result && result.accepted === args.accept ? "confirmed" : "unverifiable",
3295
+ },
3296
+ };
3297
+ } finally {
3298
+ clearTimeout(timer);
3299
+ closed.cancel();
3300
+ await releaseDebuggerLease(chromeApi, lease, { idleDetachMs: DEBUGGER_IDLE_DETACH_MS });
3301
+ }
3302
+ }
3303
+
3304
+ function gateCaptureStart(action, start) {
3305
+ return async (chromeApi, args, runCtx) => {
3306
+ const tabId = args?.tab_id ?? runCtx.scratchTabId;
3307
+ if (tabId != null) await enforceTabMutable(chromeApi, action, tabId, runCtx);
3308
+ return start(chromeApi, args, runCtx);
3309
+ };
3310
+ }
3311
+
3312
+ async function tool_feed_listen(chromeApi, args, runCtx) {
3313
+ await enforceAllowedOriginFromTab(chromeApi, args.tab_id, runCtx);
3314
+ await enforceTabMutable(chromeApi, "feed_listen", args.tab_id, runCtx);
3315
+ return listenToFeed(chromeApi, args, runCtx);
3316
+ }
3317
+
3318
+ export const TOOLS = {
3319
+ feed_listen: tool_feed_listen,
3320
+ navigate: tool_navigate,
3321
+ get_accessibility_tree: tool_get_accessibility_tree,
3322
+ click_ref: tool_click_ref,
3323
+ type_ref: tool_type_ref,
3324
+ upload_file: tool_upload_file,
3325
+ wait_for_selector: tool_wait_for_selector,
3326
+ scroll: tool_scroll,
3327
+ press_key: tool_press_key,
3328
+ hover_ref: tool_hover_ref,
3329
+ select_option: tool_select_option,
3330
+ handle_dialog: tool_handle_dialog,
3331
+ screenshot: tool_screenshot,
3332
+ focus_tab: tool_focus_tab,
3333
+ evaluate: tool_evaluate,
3334
+ close_tab: tool_close_tab,
3335
+ close_user_tabs: tool_close_user_tabs,
3336
+ list_tabs: tool_list_tabs,
3337
+ show_notification: tool_show_notification,
3338
+ // Network interception primitive — buffers CDP Network.responseReceived
3339
+ // bodies for connector code to drain. See network-intercept.js.
3340
+ ...NETWORK_INTERCEPT_TOOLS,
3341
+ // Console capture primitive — buffers CDP Runtime.consoleAPICalled /
3342
+ // exceptionThrown output for connector code to drain. See console-capture.js.
3343
+ ...CONSOLE_CAPTURE_TOOLS,
3344
+ // Starting a capture reads a page's traffic or console, so it follows the
3345
+ // mutating-tool rule; drain/stop act on a session that start authorized.
3346
+ network_intercept_start: gateCaptureStart(
3347
+ "network_intercept_start",
3348
+ NETWORK_INTERCEPT_TOOLS.network_intercept_start,
3349
+ ),
3350
+ console_capture_start: gateCaptureStart(
3351
+ "console_capture_start",
3352
+ CONSOLE_CAPTURE_TOOLS.console_capture_start,
3353
+ ),
3354
+ };