cdp-toolkit 3.4.0 → 3.6.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.
package/dist/index.js CHANGED
@@ -322,6 +322,9 @@ function leaseTtlMs() {
322
322
  function markLongLivedProcess(value = true) {
323
323
  longLived = value;
324
324
  }
325
+ function isLongLivedProcess() {
326
+ return longLived;
327
+ }
325
328
  function requireLease() {
326
329
  if (!longLived)
327
330
  return false;
@@ -587,6 +590,15 @@ var init_leases = __esm(() => {
587
590
  LEASE_FILE_RE = new RegExp(`^lease-(${BACKEND_KEY_SOURCE})-(.+)\\.json$`);
588
591
  });
589
592
 
593
+ // src/focusPolicy.ts
594
+ function focusDenied() {
595
+ return TRUTHY.has((process.env.CDP_DENY_FOCUS ?? "").trim().toLowerCase());
596
+ }
597
+ var TRUTHY;
598
+ var init_focusPolicy = __esm(() => {
599
+ TRUTHY = new Set(["1", "true", "yes", "on"]);
600
+ });
601
+
590
602
  // src/origins.ts
591
603
  import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
592
604
  import { join as join2 } from "node:path";
@@ -686,7 +698,7 @@ async function originIndex(backend, liveIds) {
686
698
  return index;
687
699
  }
688
700
  async function newTrackedPage(driver, backend, opts = {}) {
689
- const page = await driver.newPage(opts.url, { focus: opts.focus === true });
701
+ const page = await driver.newPage(opts.url, { focus: opts.focus === true && !focusDenied() });
690
702
  await recordOrigin(backend, page.id, { label: opts.label });
691
703
  return page;
692
704
  }
@@ -713,6 +725,7 @@ async function resolveLiveLabel(backend, label, liveIds) {
713
725
  }
714
726
  var ORIGIN_FILE_RE;
715
727
  var init_origins = __esm(() => {
728
+ init_focusPolicy();
716
729
  init_leases();
717
730
  ORIGIN_FILE_RE = new RegExp(`^origin-(${BACKEND_KEY_SOURCE})-(.+)\\.json$`);
718
731
  });
@@ -1000,6 +1013,165 @@ var init_session = __esm(() => {
1000
1013
  init_endpoint();
1001
1014
  });
1002
1015
 
1016
+ // src/cdp/hiddenTabs.ts
1017
+ function hiddenTabsRequested() {
1018
+ return TRUTHY2.has((process.env.CDP_HIDDEN_TABS ?? "").trim().toLowerCase());
1019
+ }
1020
+ function hiddenTabsMax() {
1021
+ const raw = Number(process.env.CDP_HIDDEN_TABS_MAX);
1022
+ return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : DEFAULT_HIDDEN_TABS_MAX;
1023
+ }
1024
+
1025
+ class HiddenTabOwner {
1026
+ deps;
1027
+ conn;
1028
+ connecting;
1029
+ tabs = new Map;
1030
+ reserved = 0;
1031
+ constructor(deps) {
1032
+ this.deps = deps;
1033
+ }
1034
+ sweep() {
1035
+ if (this.conn && !this.conn.isOpen) {
1036
+ this.conn = undefined;
1037
+ this.tabs.clear();
1038
+ }
1039
+ }
1040
+ has(id) {
1041
+ this.sweep();
1042
+ return this.tabs.has(id);
1043
+ }
1044
+ ids() {
1045
+ this.sweep();
1046
+ return [...this.tabs.keys()];
1047
+ }
1048
+ async owner() {
1049
+ this.sweep();
1050
+ if (this.conn)
1051
+ return this.conn;
1052
+ if (!this.connecting) {
1053
+ this.connecting = (async () => {
1054
+ const conn = await this.deps.connect();
1055
+ conn.on("Target.targetDestroyed", (params) => {
1056
+ const id = params.targetId;
1057
+ if (typeof id === "string")
1058
+ this.tabs.delete(id);
1059
+ });
1060
+ this.conn = conn;
1061
+ return conn;
1062
+ })().finally(() => {
1063
+ this.connecting = undefined;
1064
+ });
1065
+ }
1066
+ return this.connecting;
1067
+ }
1068
+ async create(url) {
1069
+ this.sweep();
1070
+ const max = (this.deps.max ?? hiddenTabsMax)();
1071
+ if (this.tabs.size + this.reserved >= max)
1072
+ throw new HiddenTabCapError(max, [...this.tabs.keys()]);
1073
+ this.reserved++;
1074
+ try {
1075
+ const conn = await this.owner();
1076
+ const id = await this.deps.createSettled(conn, url, { hidden: true });
1077
+ try {
1078
+ const { sessionId } = await conn.send("Target.attachToTarget", { targetId: id, flatten: true }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
1079
+ const dpr = await conn.send("Runtime.evaluate", { expression: "devicePixelRatio", returnByValue: true }, { sessionId, timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).then((r) => r.result?.value).catch(() => {
1080
+ return;
1081
+ });
1082
+ await conn.send("Emulation.setDeviceMetricsOverride", {
1083
+ width: HIDDEN_TAB_VIEWPORT.width,
1084
+ height: HIDDEN_TAB_VIEWPORT.height,
1085
+ deviceScaleFactor: typeof dpr === "number" && Number.isFinite(dpr) && dpr > 0 ? dpr : FALLBACK_DEVICE_SCALE_FACTOR,
1086
+ mobile: false
1087
+ }, { sessionId, timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
1088
+ this.tabs.set(id, sessionId);
1089
+ return id;
1090
+ } catch (e) {
1091
+ await conn.send("Target.closeTarget", { targetId: id }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).catch(() => {
1092
+ return;
1093
+ });
1094
+ throw e;
1095
+ }
1096
+ } finally {
1097
+ this.reserved--;
1098
+ }
1099
+ }
1100
+ async close(id) {
1101
+ this.sweep();
1102
+ const conn = this.conn;
1103
+ const held = this.tabs.delete(id);
1104
+ if (!conn || !held)
1105
+ return { success: false };
1106
+ const res = await conn.send("Target.closeTarget", { targetId: id }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
1107
+ return { success: res.success ?? true };
1108
+ }
1109
+ async dispose() {
1110
+ const conn = this.conn;
1111
+ const ids = [...this.tabs.keys()];
1112
+ this.tabs.clear();
1113
+ this.conn = undefined;
1114
+ if (!conn)
1115
+ return;
1116
+ if (conn.isOpen) {
1117
+ await Promise.all(ids.map((targetId) => conn.send("Target.closeTarget", { targetId }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).catch(() => {
1118
+ return;
1119
+ })));
1120
+ }
1121
+ conn.close();
1122
+ }
1123
+ }
1124
+ function hiddenTabOwner(base, deps) {
1125
+ let owner = owners.get(base);
1126
+ if (!owner) {
1127
+ owner = new HiddenTabOwner(deps());
1128
+ owners.set(base, owner);
1129
+ }
1130
+ return owner;
1131
+ }
1132
+ function existingHiddenTabOwner(base) {
1133
+ return owners.get(base);
1134
+ }
1135
+ function markHiddenTargets(base, targets) {
1136
+ const owner = owners.get(base);
1137
+ if (!owner)
1138
+ return targets;
1139
+ const hidden = new Set(owner.ids());
1140
+ if (hidden.size === 0)
1141
+ return targets;
1142
+ const visible = [];
1143
+ const marked = [];
1144
+ for (const t of targets) {
1145
+ if (hidden.has(t.id))
1146
+ marked.push({ ...t, type: "page", hidden: true });
1147
+ else
1148
+ visible.push(t);
1149
+ }
1150
+ return marked.length ? [...visible, ...marked] : targets;
1151
+ }
1152
+ async function disposeHiddenTabs() {
1153
+ const all = [...owners.values()];
1154
+ owners.clear();
1155
+ await Promise.all(all.map((o) => o.dispose()));
1156
+ }
1157
+ var DEFAULT_HIDDEN_TABS_MAX = 20, HIDDEN_TAB_VIEWPORT, FALLBACK_DEVICE_SCALE_FACTOR = 2, OWNER_COMMAND_TIMEOUT_MS = 5000, TRUTHY2, HiddenTabCapError, owners;
1158
+ var init_hiddenTabs = __esm(() => {
1159
+ HIDDEN_TAB_VIEWPORT = { width: 1280, height: 800 };
1160
+ TRUTHY2 = new Set(["1", "true", "yes", "on"]);
1161
+ HiddenTabCapError = class HiddenTabCapError extends Error {
1162
+ max;
1163
+ openIds;
1164
+ code = "page-error";
1165
+ constructor(max, openIds) {
1166
+ super(`hidden-tab cap reached: ${openIds.length} hidden tabs are open (CDP_HIDDEN_TABS_MAX=${max}). ` + `Close one with close_page (open hidden tabs, oldest first: ${openIds.join(", ")}), ` + `or pass focus:true to open a visible tab instead.`);
1167
+ this.max = max;
1168
+ this.openIds = openIds;
1169
+ this.name = "HiddenTabCapError";
1170
+ }
1171
+ };
1172
+ owners = new Map;
1173
+ });
1174
+
1003
1175
  // src/client.ts
1004
1176
  class CdpConnection {
1005
1177
  wsUrl;
@@ -1118,6 +1290,9 @@ class CdpConnection {
1118
1290
  });
1119
1291
  });
1120
1292
  }
1293
+ get isOpen() {
1294
+ return !this.closed && this.ws !== undefined;
1295
+ }
1121
1296
  close() {
1122
1297
  this.closed = true;
1123
1298
  this.rejectAll(new CdpError("closed by caller"));
@@ -1146,11 +1321,11 @@ async function getTargetsOverBrowserWs() {
1146
1321
  async function listTargets() {
1147
1322
  const base = currentEndpoint().base;
1148
1323
  if (knownTransports.get(base) === "browser-ws")
1149
- return getTargetsOverBrowserWs();
1324
+ return markHiddenTargets(base, await getTargetsOverBrowserWs());
1150
1325
  try {
1151
1326
  const listing = await httpJson("/json/list");
1152
1327
  knownTransports.set(base, "http");
1153
- return listing;
1328
+ return markHiddenTargets(base, listing);
1154
1329
  } catch (httpError) {
1155
1330
  const detected = await detectEndpoint().catch(() => {
1156
1331
  return;
@@ -1161,7 +1336,7 @@ async function listTargets() {
1161
1336
  throw httpError;
1162
1337
  });
1163
1338
  knownTransports.set(base, "browser-ws");
1164
- return targets;
1339
+ return markHiddenTargets(base, targets);
1165
1340
  }
1166
1341
  }
1167
1342
  async function browserWsUrl() {
@@ -1274,6 +1449,7 @@ var init_client = __esm(() => {
1274
1449
  init_frames();
1275
1450
  init_endpoint();
1276
1451
  init_session();
1452
+ init_hiddenTabs();
1277
1453
  init_session();
1278
1454
  BASE = (() => {
1279
1455
  try {
@@ -1725,7 +1901,10 @@ var init_driver = __esm(() => {
1725
1901
  focus_emulation: ["emulate.focus"],
1726
1902
  click_focus_gated: ["emulate.focus"],
1727
1903
  wait_for_download: ["browser.downloads"],
1728
- grant_permissions: ["browser.permissions"]
1904
+ grant_permissions: ["browser.permissions"],
1905
+ list_tab_groups: ["browser.tabGroups"],
1906
+ group_tabs: ["browser.tabGroups"],
1907
+ ungroup_tabs: ["browser.tabGroups"]
1729
1908
  };
1730
1909
  });
1731
1910
 
@@ -2049,6 +2228,7 @@ init_client();
2049
2228
  init_session();
2050
2229
  init_frontApp();
2051
2230
  init_leases();
2231
+ init_hiddenTabs();
2052
2232
  init_endpoints();
2053
2233
  init_activity();
2054
2234
 
@@ -2559,6 +2739,7 @@ var CDP_CAPABILITIES = new Set([
2559
2739
  "emulate.focus",
2560
2740
  "browser.downloads",
2561
2741
  "browser.permissions",
2742
+ "browser.tabGroups",
2562
2743
  "worker.targets",
2563
2744
  "frame.targets"
2564
2745
  ]);
@@ -3249,8 +3430,10 @@ async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS, o
3249
3430
  await conn.send("Target.setDiscoverTargets", { discover: true }).catch(() => {
3250
3431
  return;
3251
3432
  });
3252
- const create = () => conn.send("Target.createTarget", { url, background: opts.focus !== true });
3253
- const { targetId } = opts.focus === true ? await create() : await keepFrontApp(create);
3433
+ const hidden = opts.hidden === true;
3434
+ const params = hidden ? { url, background: true, hidden: true } : { url, background: opts.focus !== true };
3435
+ const create = () => conn.send("Target.createTarget", params);
3436
+ const { targetId } = opts.focus === true || hidden ? await create() : await keepFrontApp(create);
3254
3437
  if (!targetId)
3255
3438
  throw driverError("page-error", "Target.createTarget returned no targetId");
3256
3439
  id = targetId;
@@ -3268,6 +3451,19 @@ async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS, o
3268
3451
  off();
3269
3452
  }
3270
3453
  }
3454
+ function hiddenTabsEnabled() {
3455
+ return hiddenTabsRequested() && isLongLivedProcess();
3456
+ }
3457
+ function currentHiddenOwner() {
3458
+ return hiddenTabOwner(currentEndpoint().base, () => ({
3459
+ connect: () => openBrowser(),
3460
+ createSettled: (conn, url, opts) => createSettledTarget(conn, url, NEW_TARGET_SETTLE_MS, opts)
3461
+ }));
3462
+ }
3463
+ function hiddenOwnerOf(id) {
3464
+ const owner = existingHiddenTabOwner(currentEndpoint().base);
3465
+ return owner?.has(id) ? owner : undefined;
3466
+ }
3271
3467
 
3272
3468
  class CdpBrowserDriver {
3273
3469
  scheme = "cdp";
@@ -3278,15 +3474,26 @@ class CdpBrowserDriver {
3278
3474
  async listPages(opts) {
3279
3475
  const targets = await listTargets();
3280
3476
  const filtered = opts?.all ? targets : targets.filter((t) => t.type === "page");
3281
- return filtered.map((t) => ({ id: t.id, url: t.url, title: t.title, type: t.type }));
3477
+ return filtered.map((t) => ({ id: t.id, url: t.url, title: t.title, type: t.type, ...t.hidden ? { hidden: true } : {} }));
3282
3478
  }
3283
3479
  async newPage(url, opts) {
3480
+ if (opts?.focus !== true && hiddenTabsEnabled()) {
3481
+ const id = await currentHiddenOwner().create(url ?? "about:blank");
3482
+ return { id, url: url ?? "about:blank", title: "", hidden: true };
3483
+ }
3284
3484
  return withBrowserConn(async (conn) => {
3285
3485
  const targetId = await createSettledTarget(conn, url ?? "about:blank", NEW_TARGET_SETTLE_MS, { focus: opts?.focus === true });
3286
3486
  return { id: targetId, url: url ?? "about:blank", title: "" };
3287
3487
  });
3288
3488
  }
3289
3489
  async closePage(id) {
3490
+ const owner = hiddenOwnerOf(id);
3491
+ if (owner) {
3492
+ const res = await owner.close(id);
3493
+ if (res.success)
3494
+ beaconSessions.drop(beaconKey(id));
3495
+ return res;
3496
+ }
3290
3497
  return withBrowserConn(async (conn) => {
3291
3498
  const res = await keepFrontApp(() => conn.send("Target.closeTarget", { targetId: id }));
3292
3499
  if (res.success !== false)
@@ -3296,6 +3503,16 @@ class CdpBrowserDriver {
3296
3503
  }
3297
3504
  async activatePage(id) {
3298
3505
  const target = await resolveTarget(id).catch(noSuchTarget);
3506
+ const owner = hiddenOwnerOf(target.id);
3507
+ if (owner) {
3508
+ const url = target.url || "about:blank";
3509
+ const newId = await withBrowserConn((conn) => createSettledTarget(conn, url, NEW_TARGET_SETTLE_MS, { focus: true }));
3510
+ await owner.close(target.id).catch(() => {
3511
+ return;
3512
+ });
3513
+ beaconSessions.drop(beaconKey(target.id));
3514
+ return { id: newId, url, title: target.title, revealedFrom: target.id };
3515
+ }
3299
3516
  await withBrowserConn((conn) => conn.send("Target.activateTarget", { targetId: target.id }));
3300
3517
  return { id: target.id, url: target.url, title: target.title };
3301
3518
  }
@@ -3369,6 +3586,7 @@ class CdpBrowserDriver {
3369
3586
  }
3370
3587
  async dispose() {
3371
3588
  beaconSessions.clear();
3589
+ await disposeHiddenTabs();
3372
3590
  }
3373
3591
  }
3374
3592
  function createCdpDriver() {
@@ -3434,6 +3652,7 @@ async function reapStaleAgentTabs(driver, backend) {
3434
3652
  }
3435
3653
 
3436
3654
  // src/shared-tools.ts
3655
+ init_focusPolicy();
3437
3656
  init_driver();
3438
3657
  import { mkdir as mkdir5, writeFile as writeFile4 } from "node:fs/promises";
3439
3658
  import { dirname as dirname2, join as join5 } from "node:path";
@@ -4117,16 +4336,20 @@ async function listPagesOne(driver, args = {}) {
4117
4336
  async function newPage(driver, args = {}) {
4118
4337
  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
4119
4338
  const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label, focus: args.focus === true });
4339
+ const hidden = {
4340
+ ...p.hidden === true ? { hidden: true } : {},
4341
+ ...args.focus === true && focusDenied() ? { focusDenied: true } : {}
4342
+ };
4120
4343
  const explicit = args.claim === true;
4121
4344
  if (!explicit && !requireLease())
4122
- return { targetId: p.id, url: p.url };
4345
+ return { targetId: p.id, url: p.url, ...hidden };
4123
4346
  const { record, token } = await claimLease(backendOf(driver), p.id, {
4124
4347
  label,
4125
4348
  ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
4126
4349
  auto: !explicit
4127
4350
  });
4128
4351
  await installBeacon(driver, p.id);
4129
- return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
4352
+ return { targetId: p.id, url: p.url, ...hidden, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
4130
4353
  }
4131
4354
  async function closePage(driver, args) {
4132
4355
  if (args.target === undefined || args.target === "")
@@ -4147,9 +4370,33 @@ async function selectPage(driver, args) {
4147
4370
  if (args.target === undefined || args.target === "")
4148
4371
  throw new SharedToolError("select_page requires an explicit target");
4149
4372
  const p = await resolvePage(driver, args.target);
4150
- const id = args.focus === true ? (await driver.activatePage(p.id)).id : p.id;
4151
- await writeSelectedFile(id);
4152
- return { selected: id, focused: args.focus === true };
4373
+ if (args.focus !== true || focusDenied()) {
4374
+ await writeSelectedFile(p.id);
4375
+ return { selected: p.id, focused: false, ...args.focus === true ? { focusDenied: true } : {} };
4376
+ }
4377
+ const shown = await driver.activatePage(p.id);
4378
+ if (shown.revealedFrom === undefined || shown.id === p.id) {
4379
+ await writeSelectedFile(shown.id);
4380
+ return { selected: shown.id, focused: true };
4381
+ }
4382
+ const moved = await moveRevealedTab(backendOf(driver), shown.revealedFrom, shown.id);
4383
+ await writeSelectedFile(shown.id);
4384
+ return { selected: shown.id, focused: true, revealedFrom: shown.revealedFrom, ...moved.lease ? { lease: moved.lease } : {} };
4385
+ }
4386
+ async function moveRevealedTab(backend, fromId, toId) {
4387
+ const origin = await readOrigin(backend, fromId).catch(() => {
4388
+ return;
4389
+ });
4390
+ if (origin)
4391
+ await recordOrigin(backend, toId, { label: origin.label, now: origin.createdAt });
4392
+ const lease = await readLease(backend, fromId).catch(() => {
4393
+ return;
4394
+ });
4395
+ if (!lease)
4396
+ return {};
4397
+ await releaseLeaseFor(backend, fromId);
4398
+ const { token } = await claimLease(backend, toId, { label: lease.label, ttlMs: lease.ttlMs, auto: lease.auto === true });
4399
+ return { lease: token };
4153
4400
  }
4154
4401
  function toLegacyWaitedFor(w) {
4155
4402
  if (w === "committed")
@@ -4560,7 +4807,7 @@ async function pressKey(driver, args) {
4560
4807
  pressed: args.key,
4561
4808
  modifiers,
4562
4809
  delivered: false,
4563
- note: "the page saw no keydown: a background tab gets no trusted keyboard input. A click on the tab's page (click tool) usually gives it focus so keys land; or open the tab with new_page focus:true. A key handled inside a cross-origin iframe also reads as not delivered."
4810
+ note: "the page saw no keydown: a background tab gets no trusted keyboard input. A click on the tab's page (click tool) usually gives it focus so keys land; or open the tab with new_page focus:true (which raises the browser over the user's work; refused under CDP_DENY_FOCUS). A key handled inside a cross-origin iframe also reads as not delivered."
4564
4811
  };
4565
4812
  }
4566
4813
  return { pressed: args.key, modifiers };
@@ -4815,6 +5062,7 @@ async function claimPage(driver, args = {}) {
4815
5062
  let targetId;
4816
5063
  let url;
4817
5064
  let opened;
5065
+ let hidden = false;
4818
5066
  if (hasTarget) {
4819
5067
  const hit = await pickPage(driver, pages, args.target).catch((err) => {
4820
5068
  throw new LeaseToolError(`claim_page: no open tab matches target '${args.target}' (${err.message}). No tab was opened: claim_page never creates one when 'target' is given.`);
@@ -4834,6 +5082,7 @@ async function claimPage(driver, args = {}) {
4834
5082
  targetId = page.id;
4835
5083
  url = page.url;
4836
5084
  opened = true;
5085
+ hidden = page.hidden === true;
4837
5086
  }
4838
5087
  const humanMs = opened ? null : await readHumanActiveMs(driver, backend, targetId);
4839
5088
  const liveIds = [...pages.map((p) => p.id), targetId];
@@ -4852,6 +5101,7 @@ async function claimPage(driver, args = {}) {
4852
5101
  ttlMs: record.ttlMs,
4853
5102
  expiresAt: record.lastUsedAt + record.ttlMs,
4854
5103
  opened,
5104
+ ...hidden ? { hidden: true } : {},
4855
5105
  ...beaconSupported(driver) ? { humanActiveMs: humanMs } : {},
4856
5106
  ...contention !== undefined ? { contention } : {}
4857
5107
  };
@@ -5559,6 +5809,7 @@ async function performanceAnalyzeInsight(args = {}) {
5559
5809
  }
5560
5810
 
5561
5811
  // src/tools/screencast.ts
5812
+ init_focusPolicy();
5562
5813
  init_client();
5563
5814
  import { spawn } from "node:child_process";
5564
5815
  import { mkdir as mkdir8, rm as rm2, stat as stat2, writeFile as writeFile7 } from "node:fs/promises";
@@ -5859,7 +6110,7 @@ async function startScreenRecording(args = {}) {
5859
6110
  });
5860
6111
  try {
5861
6112
  await conn.send("Page.enable");
5862
- if (args.bringToFront)
6113
+ if (args.bringToFront && !focusDenied())
5863
6114
  await conn.send("Page.bringToFront").catch(() => {});
5864
6115
  const params = { format };
5865
6116
  if (format === "jpeg" && args.quality !== undefined)
@@ -6505,11 +6756,302 @@ async function grantPermissions(args = {}) {
6505
6756
  return { granted: [...permissions], origin, ...reset ? { reset: true } : {}, target };
6506
6757
  }
6507
6758
 
6508
- // src/tools/extract.ts
6759
+ // src/tools/tab-groups.ts
6509
6760
  init_client();
6510
- import { mkdir as mkdir12, writeFile as writeFile9 } from "node:fs/promises";
6511
- import { dirname as dirname3, join as join11 } from "node:path";
6761
+ import { createHash } from "node:crypto";
6762
+ import { mkdir as mkdir12, readFile as readFile9, writeFile as writeFile9 } from "node:fs/promises";
6763
+ import { join as join11 } from "node:path";
6512
6764
  var ARTIFACT_DIR7 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
6765
+ var HELPER_DIR = join11(ARTIFACT_DIR7, "tab-groups-helper");
6766
+ var TAB_GROUP_COLORS = ["grey", "blue", "red", "yellow", "green", "pink", "purple", "cyan", "orange"];
6767
+ var HELPER_KEY = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqesYyi7LmBxzWP7VFJGlH2khinCz0uU2z3KNDvZ3Kb8gTLPpthgRWp27pu5/Wk2nvQJdcrunf6u5vqomH2xhvXIqjgXtth2o1GrE6oJMWRUqEoC7I4YUXdSieRpxAxtG37KiSFOyFOU59Som3gGOM2j1qlQIsID0QwRCeRs095SLoTtkA6YwZxtOETgvZAhbbpkmYwkXjTzgY85sS1JfMYj67cmfyz/Nt6yfORSJYEmWAfGCjQnvtOn9TjCazZvmoASUhsKZNZVWckAg+Md+ZKBPbl14/UUwLmWHQ7SDcJozHZtFeLFXySwvmBm3NhP1rK5vd/v+modsQY3M3DbqLQIDAQAB";
6768
+ var HELPER_MANIFEST = {
6769
+ manifest_version: 3,
6770
+ name: "cdp-toolkit tab groups",
6771
+ description: "Helper installed by cdp-toolkit's tab-group tools (list_tab_groups, group_tabs, ungroup_tabs). No UI, no state.",
6772
+ version: "1.0.0",
6773
+ key: HELPER_KEY,
6774
+ permissions: ["tabs", "tabGroups", "debugger"],
6775
+ background: { service_worker: "sw.js" }
6776
+ };
6777
+ function extensionIdFromKey(keyBase64) {
6778
+ const hex = createHash("sha256").update(Buffer.from(keyBase64, "base64")).digest("hex").slice(0, 32);
6779
+ return [...hex].map((c) => String.fromCharCode(97 + parseInt(c, 16))).join("");
6780
+ }
6781
+ var HELPER_EXTENSION_ID = extensionIdFromKey(HELPER_KEY);
6782
+ var HELPER_SW_BODY = String.raw`
6783
+ const NONE = -1;
6784
+
6785
+ async function targetIdsByTab() {
6786
+ const m = new Map();
6787
+ try {
6788
+ for (const t of await chrome.debugger.getTargets()) {
6789
+ if (t.type === "page" && typeof t.tabId === "number") m.set(t.tabId, t.id);
6790
+ }
6791
+ } catch (e) {
6792
+ // No mapping is a degraded answer (rows lack targetId), not a failure of the listing.
6793
+ }
6794
+ return m;
6795
+ }
6796
+
6797
+ function row(t, m) {
6798
+ return { tabId: t.id, targetId: m.get(t.id), index: t.index, url: t.url || t.pendingUrl || "", title: t.title || "" };
6799
+ }
6800
+
6801
+ const byPlace = (a, b) => a.windowId - b.windowId || a.index - b.index;
6802
+
6803
+ async function list(args) {
6804
+ const q = args && args.windowId !== undefined ? { windowId: args.windowId } : {};
6805
+ const [tabs, groups, m] = await Promise.all([chrome.tabs.query(q), chrome.tabGroups.query(q), targetIdsByTab()]);
6806
+ const wins = new Map();
6807
+ for (const t of tabs.slice().sort(byPlace)) {
6808
+ let w = wins.get(t.windowId);
6809
+ if (!w) wins.set(t.windowId, (w = { windowId: t.windowId, tabCount: 0, ungrouped: 0, groups: [] }));
6810
+ w.tabCount++;
6811
+ if (t.groupId === NONE || t.groupId === undefined) {
6812
+ w.ungrouped++;
6813
+ if (args && args.includeUngrouped) (w.ungroupedTabs || (w.ungroupedTabs = [])).push(row(t, m));
6814
+ continue;
6815
+ }
6816
+ let g = w.groups.find((x) => x.groupId === t.groupId);
6817
+ if (!g) {
6818
+ const info = groups.find((x) => x.id === t.groupId) || {};
6819
+ g = { groupId: t.groupId, title: info.title || "", color: info.color, collapsed: !!info.collapsed, tabs: [] };
6820
+ w.groups.push(g);
6821
+ }
6822
+ g.tabs.push(row(t, m));
6823
+ }
6824
+ const windows = [...wins.values()];
6825
+ return {
6826
+ windows,
6827
+ groupCount: windows.reduce((n, w) => n + w.groups.length, 0),
6828
+ tabCount: tabs.length,
6829
+ };
6830
+ }
6831
+
6832
+ async function selectTabs(args, m) {
6833
+ if (Array.isArray(args.tabIds)) {
6834
+ const out = [];
6835
+ for (const id of args.tabIds) {
6836
+ try { out.push(await chrome.tabs.get(id)); }
6837
+ catch (e) { throw new Error("no tab with tabId " + id + " (tab ids come from list_tab_groups)"); }
6838
+ }
6839
+ return out;
6840
+ }
6841
+ if (Array.isArray(args.targetIds)) {
6842
+ const byTarget = new Map([...m].map(([tabId, targetId]) => [targetId, tabId]));
6843
+ const out = [];
6844
+ for (const tid of args.targetIds) {
6845
+ const id = byTarget.get(tid);
6846
+ if (id === undefined) throw new Error("no tab with targetId " + tid + " (a page's CDP target id, as list_pages shows it)");
6847
+ out.push(await chrome.tabs.get(id));
6848
+ }
6849
+ return out;
6850
+ }
6851
+ const all = (await chrome.tabs.query({})).sort(byPlace);
6852
+ if (typeof args.urlMatch === "string") {
6853
+ const hit = all.filter((t) => (t.url || "").includes(args.urlMatch) || (t.pendingUrl || "").includes(args.urlMatch));
6854
+ if (!hit.length) throw new Error("urlMatch " + JSON.stringify(args.urlMatch) + " matched no tab");
6855
+ return hit;
6856
+ }
6857
+ if (typeof args.groupId === "number") {
6858
+ await chrome.tabGroups.get(args.groupId).catch(() => { throw new Error("no tab group with groupId " + args.groupId); });
6859
+ return all.filter((t) => t.groupId === args.groupId);
6860
+ }
6861
+ throw new Error("no tab selector given");
6862
+ }
6863
+
6864
+ async function group(args) {
6865
+ const m = await targetIdsByTab();
6866
+ const tabs = await selectTabs(args, m);
6867
+ let win;
6868
+ if (args.groupId !== undefined) {
6869
+ win = (await chrome.tabGroups.get(args.groupId).catch(() => { throw new Error("no tab group with groupId " + args.groupId); })).windowId;
6870
+ } else if (args.windowId !== undefined) {
6871
+ win = args.windowId;
6872
+ } else {
6873
+ const ws = [...new Set(tabs.map((t) => t.windowId))];
6874
+ if (ws.length > 1) {
6875
+ throw new Error(
6876
+ "the selected tabs are in " + ws.length + " windows (" + ws.join(", ") + "); pass windowId to name the window the group goes in " +
6877
+ "(tabs from other windows are moved there). Without it Chrome would move them all into the last-focused window.",
6878
+ );
6879
+ }
6880
+ win = ws[0];
6881
+ }
6882
+ const moved = tabs.filter((t) => t.windowId !== win).map((t) => ({ tabId: t.id, fromWindowId: t.windowId }));
6883
+ const opts = { tabIds: tabs.map((t) => t.id) };
6884
+ if (args.groupId !== undefined) opts.groupId = args.groupId;
6885
+ else opts.createProperties = { windowId: win };
6886
+ const gid = await chrome.tabs.group(opts);
6887
+ const upd = {};
6888
+ if (args.title !== undefined) upd.title = args.title;
6889
+ if (args.color !== undefined) upd.color = args.color;
6890
+ if (args.collapsed !== undefined) upd.collapsed = args.collapsed;
6891
+ const g = Object.keys(upd).length ? await chrome.tabGroups.update(gid, upd) : await chrome.tabGroups.get(gid);
6892
+ const members = g.windowId > 0 ? (await chrome.tabs.query({ windowId: g.windowId })).filter((t) => t.groupId === gid).sort(byPlace) : [];
6893
+ if (members.length === 0) {
6894
+ // Vivaldi answers chrome.tabs.group with an id but keeps its own tab stacks: the "group" has
6895
+ // windowId -1 and no tabs. Fail loudly rather than report a group that does not exist.
6896
+ throw new Error("the browser accepted chrome.tabs.group but created no visible group (windowId " + g.windowId + ", 0 tabs); this browser does not support Chrome tab groups (Vivaldi uses its own tab stacks)");
6897
+ }
6898
+ return { groupId: gid, windowId: g.windowId, title: g.title || "", color: g.color, collapsed: !!g.collapsed, tabs: members.map((t) => row(t, m)), moved };
6899
+ }
6900
+
6901
+ async function ungroup(args) {
6902
+ const m = await targetIdsByTab();
6903
+ const tabs = await selectTabs(args, m);
6904
+ const grouped = tabs.filter((t) => t.groupId !== NONE && t.groupId !== undefined);
6905
+ if (grouped.length) await chrome.tabs.ungroup(grouped.map((t) => t.id));
6906
+ return {
6907
+ ungrouped: grouped.map((t) => Object.assign(row(t, m), { fromGroupId: t.groupId })),
6908
+ alreadyUngrouped: tabs.filter((t) => !grouped.includes(t)).map((t) => t.id),
6909
+ };
6910
+ }
6911
+
6912
+ self.cdpToolkitTabGroups = { version: VERSION, list, group, ungroup };
6913
+ `;
6914
+ var HELPER_VERSION = createHash("sha256").update(HELPER_SW_BODY).digest("hex").slice(0, 12);
6915
+ var HELPER_SW_SOURCE = `"use strict";
6916
+ const VERSION = ${JSON.stringify(HELPER_VERSION)};
6917
+ ${HELPER_SW_BODY}`;
6918
+ var isInt = (v) => typeof v === "number" && Number.isInteger(v);
6919
+ function checkInt(tool, name, v) {
6920
+ if (v !== undefined && !isInt(v))
6921
+ throw new Error(`${tool}: '${name}' must be an integer (got ${JSON.stringify(v)})`);
6922
+ }
6923
+ function checkSelector(tool, a, withGroupId) {
6924
+ const given = [
6925
+ a.tabIds !== undefined && "tabIds",
6926
+ a.targetIds !== undefined && "targetIds",
6927
+ typeof a.urlMatch === "string" && a.urlMatch !== "" && "urlMatch",
6928
+ withGroupId && a.groupId !== undefined && "groupId"
6929
+ ].filter(Boolean);
6930
+ const names = withGroupId ? "tabIds, targetIds, urlMatch or groupId" : "tabIds, targetIds or urlMatch";
6931
+ if (given.length !== 1)
6932
+ throw new Error(`${tool}: give exactly one of ${names} (got ${given.length ? given.join(" + ") : "none"})`);
6933
+ if (a.tabIds !== undefined) {
6934
+ if (!Array.isArray(a.tabIds) || a.tabIds.length === 0 || !a.tabIds.every(isInt)) {
6935
+ throw new Error(`${tool}: 'tabIds' must be a non-empty array of integer chrome tab ids (got ${JSON.stringify(a.tabIds)})`);
6936
+ }
6937
+ }
6938
+ if (a.targetIds !== undefined) {
6939
+ if (!Array.isArray(a.targetIds) || a.targetIds.length === 0 || !a.targetIds.every((t) => typeof t === "string" && t !== "")) {
6940
+ throw new Error(`${tool}: 'targetIds' must be a non-empty array of CDP target id strings (got ${JSON.stringify(a.targetIds)})`);
6941
+ }
6942
+ }
6943
+ }
6944
+ function validateListTabGroupsArgs(a) {
6945
+ checkInt("list_tab_groups", "windowId", a.windowId);
6946
+ if (a.includeUngrouped !== undefined && typeof a.includeUngrouped !== "boolean") {
6947
+ throw new Error("list_tab_groups: 'includeUngrouped' must be a boolean");
6948
+ }
6949
+ }
6950
+ function validateGroupTabsArgs(a) {
6951
+ const tool = "group_tabs";
6952
+ checkSelector(tool, a, false);
6953
+ checkInt(tool, "groupId", a.groupId);
6954
+ checkInt(tool, "windowId", a.windowId);
6955
+ if (a.groupId !== undefined && a.windowId !== undefined) {
6956
+ throw new Error(`${tool}: give groupId (add to that group, in its window) or windowId (new group in that window), not both`);
6957
+ }
6958
+ if (a.title !== undefined && typeof a.title !== "string")
6959
+ throw new Error(`${tool}: 'title' must be a string`);
6960
+ if (a.collapsed !== undefined && typeof a.collapsed !== "boolean")
6961
+ throw new Error(`${tool}: 'collapsed' must be a boolean`);
6962
+ if (a.color !== undefined && !TAB_GROUP_COLORS.includes(a.color)) {
6963
+ throw new Error(`${tool}: 'color' must be one of ${TAB_GROUP_COLORS.join(", ")} (got ${JSON.stringify(a.color)})`);
6964
+ }
6965
+ }
6966
+ function validateUngroupTabsArgs(a) {
6967
+ checkSelector("ungroup_tabs", a, true);
6968
+ checkInt("ungroup_tabs", "groupId", a.groupId);
6969
+ }
6970
+ var SW_URL_PREFIX = `chrome-extension://${HELPER_EXTENSION_ID}/`;
6971
+ var WORKER_WAIT_MS = 5000;
6972
+ async function helperWorker() {
6973
+ return (await listTargets()).find((t) => t.type === "service_worker" && t.url.startsWith(SW_URL_PREFIX));
6974
+ }
6975
+ async function writeHelper() {
6976
+ await mkdir12(HELPER_DIR, { recursive: true });
6977
+ const files = {
6978
+ "manifest.json": JSON.stringify(HELPER_MANIFEST, null, 2),
6979
+ "sw.js": HELPER_SW_SOURCE
6980
+ };
6981
+ for (const [name, body] of Object.entries(files)) {
6982
+ const path = join11(HELPER_DIR, name);
6983
+ const current = await readFile9(path, "utf8").catch(() => {
6984
+ return;
6985
+ });
6986
+ if (current !== body)
6987
+ await writeFile9(path, body);
6988
+ }
6989
+ }
6990
+ async function evalIn(workerId, expression) {
6991
+ return withPage(workerId, async (conn) => {
6992
+ const r = await conn.send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true });
6993
+ if (r.exceptionDetails) {
6994
+ const d = r.exceptionDetails.exception?.description ?? r.exceptionDetails.text ?? "error";
6995
+ throw new Error(d.split(`
6996
+ `)[0].replace(/^Error: /, ""));
6997
+ }
6998
+ return r.result?.value;
6999
+ });
7000
+ }
7001
+ async function currentHelperWorker() {
7002
+ const w = await helperWorker();
7003
+ if (!w)
7004
+ return;
7005
+ const v = await evalIn(w.id, "self.cdpToolkitTabGroups && self.cdpToolkitTabGroups.version").catch(() => {
7006
+ return;
7007
+ });
7008
+ return v === HELPER_VERSION ? w.id : undefined;
7009
+ }
7010
+ async function ensureHelper() {
7011
+ const existing = await currentHelperWorker();
7012
+ if (existing)
7013
+ return existing;
7014
+ await writeHelper();
7015
+ const conn = await openBrowser();
7016
+ try {
7017
+ await conn.send("Extensions.loadUnpacked", { path: HELPER_DIR });
7018
+ } catch (e) {
7019
+ const msg = e instanceof Error ? e.message : String(e);
7020
+ throw new CdpError(`tab-group tools could not install their helper extension (Extensions.loadUnpacked: ${msg}). ` + `They need a Chromium that allows loadUnpacked over CDP, with ${HELPER_DIR} on the browser's own machine.`);
7021
+ } finally {
7022
+ conn.close();
7023
+ }
7024
+ const deadline = Date.now() + WORKER_WAIT_MS;
7025
+ while (Date.now() < deadline) {
7026
+ const id = await currentHelperWorker();
7027
+ if (id)
7028
+ return id;
7029
+ await new Promise((r) => setTimeout(r, 100));
7030
+ }
7031
+ throw new CdpError(`the tab-groups helper extension installed but its service worker did not start within ${WORKER_WAIT_MS} ms`);
7032
+ }
7033
+ async function callHelper(op, args) {
7034
+ const id = await ensureHelper();
7035
+ return await evalIn(id, `self.cdpToolkitTabGroups.${op}(${JSON.stringify(args)})`);
7036
+ }
7037
+ async function listTabGroups(args = {}) {
7038
+ validateListTabGroupsArgs(args);
7039
+ return callHelper("list", { windowId: args.windowId, includeUngrouped: args.includeUngrouped });
7040
+ }
7041
+ async function groupTabs(args = {}) {
7042
+ validateGroupTabsArgs(args);
7043
+ return callHelper("group", args);
7044
+ }
7045
+ async function ungroupTabs(args = {}) {
7046
+ validateUngroupTabsArgs(args);
7047
+ return callHelper("ungroup", args);
7048
+ }
7049
+
7050
+ // src/tools/extract.ts
7051
+ init_client();
7052
+ import { mkdir as mkdir13, writeFile as writeFile10 } from "node:fs/promises";
7053
+ import { dirname as dirname3, join as join12 } from "node:path";
7054
+ var ARTIFACT_DIR8 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
6513
7055
  var DEFAULT_BASE_URL = "http://127.0.0.1:8090/v1";
6514
7056
  var DEFAULT_MODEL = "schematron";
6515
7057
  var DEFAULT_TIMEOUT_MS2 = 90000;
@@ -6909,10 +7451,10 @@ async function extractPage(driver, args) {
6909
7451
  };
6910
7452
  if (args.savePath === undefined || args.savePath === "")
6911
7453
  return result;
6912
- const path = args.savePath.startsWith("/") ? args.savePath : join11(ARTIFACT_DIR7, args.savePath);
6913
- await mkdir12(dirname3(path), { recursive: true });
7454
+ const path = args.savePath.startsWith("/") ? args.savePath : join12(ARTIFACT_DIR8, args.savePath);
7455
+ await mkdir13(dirname3(path), { recursive: true });
6914
7456
  const json = JSON.stringify(result, null, 2);
6915
- await writeFile9(path, json, "utf8");
7457
+ await writeFile10(path, json, "utf8");
6916
7458
  const saved = {
6917
7459
  path,
6918
7460
  bytes: Buffer.byteLength(json, "utf8"),
@@ -6975,6 +7517,9 @@ var TOOLS = {
6975
7517
  click_focus_gated: clickFocusGated,
6976
7518
  wait_for_download: waitForDownload,
6977
7519
  grant_permissions: grantPermissions,
7520
+ list_tab_groups: listTabGroups,
7521
+ group_tabs: groupTabs,
7522
+ ungroup_tabs: ungroupTabs,
6978
7523
  extract_page: onCdp(extractPage),
6979
7524
  claim_page: onCdp(LEASE_TOOLS.claim_page),
6980
7525
  release_page: onCdp(LEASE_TOOLS.release_page),