cdp-toolkit 1.2.0 → 1.4.0

package/dist/cli.js

@@ -13,6 +13,9 @@ function leaseTtlMs() {
   const raw = Number(process.env.CDP_LEASE_TTL_MS);
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LEASE_TTL_MS;
 }
+function defaultLabel() {
+  return `pid-${process.pid}`;
+}
 function safeId(id) {
   return id.replace(/[^A-Za-z0-9._-]/g, "_");
 }
@@ -704,6 +707,31 @@ function decodeUid(uid) {
     throw driverError("foreign-uid", `malformed cdp uid payload: ${uid}`);
   return n;
 }
+function normalizeCdpCookie(c) {
+  const same = (c.sameSite ?? "").toLowerCase();
+  const sameSite = same === "strict" || same === "lax" || same === "none" ? same : "default";
+  return {
+    name: c.name,
+    value: c.value,
+    domain: c.domain,
+    path: c.path,
+    expires: typeof c.expires === "number" ? c.expires : -1,
+    size: typeof c.size === "number" ? c.size : Buffer.byteLength(`${c.name}${c.value}`, "utf8"),
+    httpOnly: c.httpOnly === true,
+    secure: c.secure === true,
+    sameSite,
+    session: c.session === true
+  };
+}
+function cdpSameSite(sameSite) {
+  if (sameSite === "strict")
+    return "Strict";
+  if (sameSite === "lax")
+    return "Lax";
+  if (sameSite === "none")
+    return "None";
+  return;
+}
 async function centerOf(conn, objectId) {
   const fn = "function(){this.scrollIntoView({block:'center',inline:'center'});const r=this.getBoundingClientRect();if(r.width===0&&r.height===0)return null;return {x:r.left+r.width/2,y:r.top+r.height/2};}";
   const { result, exceptionDetails } = await conn.send("Runtime.callFunctionOn", { objectId, functionDeclaration: fn, returnByValue: true });
@@ -1226,6 +1254,38 @@ class CdpPageDriver {
       });
     });
   }
+  async getCookies() {
+    await this.ensureDomain("Network");
+    const { cookies } = await this.conn.send("Network.getCookies");
+    return (cookies ?? []).map(normalizeCdpCookie);
+  }
+  async setCookie(params) {
+    await this.ensureDomain("Network");
+    const sameSite = cdpSameSite(params.sameSite);
+    const { success } = await this.conn.send("Network.setCookie", {
+      name: params.name,
+      value: params.value,
+      ...params.url !== undefined ? { url: params.url } : {},
+      ...params.domain !== undefined ? { domain: params.domain } : {},
+      ...params.path !== undefined ? { path: params.path } : {},
+      ...params.expires !== undefined ? { expires: params.expires } : {},
+      ...params.httpOnly !== undefined ? { httpOnly: params.httpOnly } : {},
+      ...params.secure !== undefined ? { secure: params.secure } : {},
+      ...sameSite !== undefined ? { sameSite } : {}
+    });
+    if (success !== true) {
+      throw driverError("page-error", `Network.setCookie declined the cookie '${params.name}'. Chrome rejects a cookie whose domain does not match the url, a secure cookie on an insecure origin, and an oversized name or value.`);
+    }
+  }
+  async deleteCookies(filter) {
+    await this.ensureDomain("Network");
+    await this.conn.send("Network.deleteCookies", {
+      name: filter.name,
+      ...filter.url !== undefined ? { url: filter.url } : {},
+      ...filter.domain !== undefined ? { domain: filter.domain } : {},
+      ...filter.path !== undefined ? { path: filter.path } : {}
+    });
+  }
   async startBodyCapture() {
     await this.ensureDomain("Network");
     return async () => {
@@ -1285,6 +1345,10 @@ async function withBrowserConn(fn) {
   }
 }
 function noSuchTarget(e) {
+  if (e instanceof LeaseConflictError)
+    throw e;
+  if (typeof e?.code === "string")
+    throw e;
   throw driverError("no-such-target", e instanceof CdpError ? e.message : String(e));
 }
 
@@ -1328,6 +1392,97 @@ function createCdpDriver() {
   return new CdpBrowserDriver;
 }
 
+// src/origins.ts
+import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+function safeId2(id) {
+  return id.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function originFile(backend, targetId) {
+  return join2(leaseDir(), `origin-${backend}-${safeId2(targetId)}.json`);
+}
+var ORIGIN_FILE_RE = /^origin-(chrome|firefox)-(.+)\.json$/;
+async function recordOrigin(backend, targetId, opts = {}) {
+  const record = {
+    backend,
+    targetId,
+    label: typeof opts.label === "string" && opts.label.length ? opts.label : defaultLabel(),
+    pid: process.pid,
+    createdAt: opts.now ?? Date.now()
+  };
+  const file = originFile(backend, targetId);
+  try {
+    await mkdir2(leaseDir(), { recursive: true });
+    try {
+      await writeFile2(file, JSON.stringify(record), { flag: "wx" });
+      return;
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+    }
+    await unlink2(file).catch(() => {
+      return;
+    });
+    await writeFile2(file, JSON.stringify(record), { flag: "wx" });
+  } catch {}
+}
+async function listOrigins(opts = {}) {
+  let names = [];
+  try {
+    names = await readdir2(leaseDir());
+  } catch {
+    return [];
+  }
+  const live = opts.liveIds === undefined ? undefined : new Set(opts.liveIds.map((id) => safeId2(id)));
+  const out = [];
+  for (const name of names) {
+    const parts = ORIGIN_FILE_RE.exec(name);
+    if (!parts)
+      continue;
+    const backend = parts[1];
+    const nameId = parts[2];
+    const scoped = live !== undefined && (opts.liveBackend === undefined || opts.liveBackend === backend);
+    if (scoped && !live.has(nameId)) {
+      await unlink2(join2(leaseDir(), name)).catch(() => {
+        return;
+      });
+      continue;
+    }
+    const fromName = { backend, targetId: nameId, label: "", pid: 0, createdAt: 0 };
+    let rec;
+    try {
+      rec = JSON.parse(await readFile2(join2(leaseDir(), name), "utf8"));
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT")
+        continue;
+      out.push({ ...fromName, unreadable: code ?? "unparseable" });
+      continue;
+    }
+    if (typeof rec?.targetId !== "string" || typeof rec?.label !== "string" || typeof rec?.createdAt !== "number") {
+      out.push({ ...fromName, unreadable: "unparseable" });
+      continue;
+    }
+    out.push({ backend: rec.backend, targetId: rec.targetId, label: rec.label, pid: rec.pid, createdAt: rec.createdAt });
+  }
+  return out;
+}
+async function originIndex(backend, liveIds) {
+  const rows = await listOrigins({ liveIds, liveBackend: backend }).catch(() => []);
+  const index = new Map;
+  for (const row of rows) {
+    if (row.backend !== backend)
+      continue;
+    index.set(row.targetId, row);
+  }
+  return index;
+}
+async function newTrackedPage(driver, backend, opts = {}) {
+  const page = await driver.newPage(opts.url);
+  await recordOrigin(backend, page.id, { label: opts.label });
+  return page;
+}
+
 // src/leases-tools.ts
 class LeaseToolError extends Error {
 }
@@ -1336,12 +1491,12 @@ function backendOf(driver) {
 }
 async function claimPage(driver, args = {}) {
   const backend = backendOf(driver);
-  const label = typeof args.label === "string" && args.label.length ? args.label : `pid-${process.pid}`;
+  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
   const pages = await driver.listPages();
   let targetId = args.targetId;
   let url = args.url ?? "about:blank";
   if (targetId === undefined || targetId === "") {
-    const page = await driver.newPage(args.url);
+    const page = await newTrackedPage(driver, backend, { url: args.url, label });
     targetId = page.id;
     url = page.url;
   } else {
@@ -1383,8 +1538,8 @@ var LEASE_TOOLS = {
 };
 
 // src/shared-tools.ts
-import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
-import { join as join2 } from "node:path";
+import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
+import { dirname, join as join3 } from "node:path";
 var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 
@@ -1452,16 +1607,35 @@ function locatorOf(args) {
     throw new SharedToolError("provide exactly one of { uid } or { selector }");
   return hasUid ? { uid: args.uid } : { css: args.selector };
 }
+async function reapSet(driver, pages, all) {
+  if (all === true)
+    return pages.map((p) => p.id);
+  try {
+    return (await driver.listPages({ all: true })).map((p) => p.id);
+  } catch {
+    return;
+  }
+}
 async function listPages(driver, args = {}) {
   const pages = await driver.listPages({ all: args.all });
-  return { pages, count: pages.length };
+  const ledger = await originIndex(backendOf2(driver), await reapSet(driver, pages, args.all));
+  const annotated = pages.map((p) => {
+    const rec = ledger.get(p.id);
+    if (!rec)
+      return { ...p, origin: "unknown" };
+    if (rec.unreadable !== undefined)
+      return { ...p, origin: "unknown", originUnreadable: rec.unreadable };
+    return { ...p, origin: "agent", label: rec.label, createdAt: rec.createdAt };
+  });
+  return { pages: annotated, count: annotated.length };
 }
 async function newPage(driver, args = {}) {
-  const p = await driver.newPage(args.url);
+  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
+  const p = await newTrackedPage(driver, backendOf2(driver), { url: args.url, label });
   if (args.claim !== true)
     return { targetId: p.id, url: p.url };
   const { record, token } = await claimLease(backendOf2(driver), p.id, {
-    label: typeof args.label === "string" && args.label.length ? args.label : `pid-${process.pid}`,
+    label,
     ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs()
   });
   return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
@@ -1477,8 +1651,8 @@ async function closePage(driver, args) {
   return { closed: p.id, success: true, ...released.released ? { leaseReleased: true } : {} };
 }
 async function writeSelectedFile(id) {
-  await mkdir2(STATE_DIR, { recursive: true });
-  await writeFile2(join2(STATE_DIR, "selected"), id, "utf8");
+  await mkdir3(STATE_DIR, { recursive: true });
+  await writeFile3(join3(STATE_DIR, "selected"), id, "utf8");
 }
 async function selectPage(driver, args) {
   if (args.target === undefined || args.target === "")
@@ -1518,11 +1692,108 @@ async function waitForText(driver, args) {
     return { found: true, waitedMs: r.elapsedMs };
   });
 }
+function serializeForSink(value) {
+  const json = JSON.stringify(value === undefined ? null : value, null, 2);
+  return json ?? "null";
+}
+async function writeJsonSink(savePath, value) {
+  const path = savePath.startsWith("/") ? savePath : join3(ARTIFACT_DIR, savePath);
+  await mkdir3(dirname(path), { recursive: true });
+  const json = serializeForSink(value);
+  await writeFile3(path, json, "utf8");
+  return { path, bytes: Buffer.byteLength(json, "utf8") };
+}
+function sinkRequested(savePath) {
+  return savePath !== undefined && savePath !== "";
+}
 async function evaluateScript(driver, args) {
   if (typeof args.expression !== "string" || args.expression.length === 0) {
     throw new SharedToolError("evaluateScript: 'expression' must be a non-empty string");
   }
-  return withPage2(driver, args.target, (page) => page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true }));
+  return withPage2(driver, args.target, async (page) => {
+    const value = await page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true });
+    if (!sinkRequested(args.savePath))
+      return value;
+    const { path, bytes } = await writeJsonSink(args.savePath, value);
+    const result = {
+      path,
+      bytes,
+      type: value === null ? "null" : typeof value,
+      target: target3(page.info)
+    };
+    return result;
+  });
+}
+function cookieDomainMatches(cookieDomain, filter) {
+  const bare = (d) => (d.startsWith(".") ? d.slice(1) : d).toLowerCase();
+  const c = bare(cookieDomain);
+  const f = bare(filter);
+  return c === f || c.endsWith(`.${f}`);
+}
+function filterCookies(cookies, filter) {
+  return cookies.filter((c) => {
+    if (filter.name !== undefined && filter.name !== "" && c.name !== filter.name)
+      return false;
+    if (filter.domain !== undefined && filter.domain !== "" && !cookieDomainMatches(c.domain, filter.domain))
+      return false;
+    return true;
+  });
+}
+async function listCookies(driver, args = {}) {
+  return withPage2(driver, args.target, async (page) => {
+    const all = await page.getCookies();
+    const cookies = filterCookies(all, { domain: args.domain, name: args.name });
+    if (!sinkRequested(args.savePath)) {
+      return { cookies, count: cookies.length, target: target3(page.info) };
+    }
+    const { path, bytes } = await writeJsonSink(args.savePath, cookies);
+    return { path, bytes, count: cookies.length, target: target3(page.info) };
+  });
+}
+function assertCookieSite(args, toolName) {
+  const hasUrl = args.url !== undefined && args.url !== "";
+  const hasDomain = args.domain !== undefined && args.domain !== "";
+  if (!hasUrl && !hasDomain) {
+    throw new Error(`${toolName} requires either 'url' or 'domain': a cookie has to be attributed to a site, and neither was given.`);
+  }
+}
+function assertCookieName(name, toolName) {
+  if (name === undefined || name === "") {
+    throw new Error(`${toolName} requires a non-empty 'name'.`);
+  }
+}
+async function setCookie(driver, args) {
+  assertCookieName(args.name, "set_cookie");
+  if (typeof args.value !== "string")
+    throw new Error("set_cookie requires a string 'value'.");
+  assertCookieSite(args, "set_cookie");
+  return withPage2(driver, args.target, async (page) => {
+    await page.setCookie({
+      name: args.name,
+      value: args.value,
+      ...args.url !== undefined ? { url: args.url } : {},
+      ...args.domain !== undefined ? { domain: args.domain } : {},
+      ...args.path !== undefined ? { path: args.path } : {},
+      ...args.expires !== undefined ? { expires: args.expires } : {},
+      ...args.httpOnly !== undefined ? { httpOnly: args.httpOnly } : {},
+      ...args.secure !== undefined ? { secure: args.secure } : {},
+      ...args.sameSite !== undefined ? { sameSite: args.sameSite } : {}
+    });
+    return { set: true, target: target3(page.info) };
+  });
+}
+async function deleteCookies(driver, args) {
+  assertCookieName(args.name, "delete_cookies");
+  assertCookieSite(args, "delete_cookies");
+  return withPage2(driver, args.target, async (page) => {
+    await page.deleteCookies({
+      name: args.name,
+      ...args.url !== undefined ? { url: args.url } : {},
+      ...args.domain !== undefined ? { domain: args.domain } : {},
+      ...args.path !== undefined ? { path: args.path } : {}
+    });
+    return { deleted: true, target: target3(page.info) };
+  });
 }
 var BARE_TOKEN_EXTRAS = new Set(["disabled", "focused"]);
 var UNQUOTED_EXTRAS = new Set(["checked", "expanded", "url"]);
@@ -1633,10 +1904,10 @@ async function takeScreenshot(driver, args = {}) {
     const { data, format: outFormat } = await page.screenshot({ format, quality: args.quality, fullPage: args.fullPage, ...clip ? { clip } : {} });
     if (data.byteLength === 0)
       throw new SharedToolError("captureScreenshot returned empty data");
-    await mkdir2(ARTIFACT_DIR, { recursive: true });
+    await mkdir3(ARTIFACT_DIR, { recursive: true });
     const ext = outFormat === "jpeg" ? "jpg" : "png";
-    const path = args.savePath ?? join2(ARTIFACT_DIR, `screenshot-${page.info.id.slice(0, 8)}-${stamp()}.${ext}`);
-    await writeFile2(path, Buffer.from(data));
+    const path = args.savePath ?? join3(ARTIFACT_DIR, `screenshot-${page.info.id.slice(0, 8)}-${stamp()}.${ext}`);
+    await writeFile3(path, Buffer.from(data));
     const result = {
       path,
       bytes: data.byteLength,
@@ -1683,6 +1954,9 @@ var SHARED_TOOLS = {
   navigate_page: navigatePage,
   wait_for: waitForText,
   evaluate_script: evaluateScript,
+  list_cookies: listCookies,
+  set_cookie: setCookie,
+  delete_cookies: deleteCookies,
   take_snapshot: takeSnapshot,
   click,
   hover,
@@ -1699,10 +1973,10 @@ var SHARED_TOOLS = {
 };
 
 // src/tools/console.ts
-import { readFile as readFile2 } from "node:fs/promises";
+import { readFile as readFile3 } from "node:fs/promises";
 
 // src/tools/recorder.ts
-import { mkdir as mkdir3, appendFile, writeFile as writeFile3, copyFile } from "node:fs/promises";
+import { mkdir as mkdir4, appendFile, writeFile as writeFile4, copyFile } from "node:fs/promises";
 var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function recFile(targetId) {
   return `${ARTIFACT_DIR2}/rec-${targetId}.jsonl`;
@@ -1723,11 +1997,11 @@ var CONSOLE_EVENTS = ["Runtime.consoleAPICalled", "Runtime.exceptionThrown", "Lo
 async function startRecorder(target, opts = {}) {
   const network = opts.network ?? true;
   const consoleCap = opts.console ?? true;
-  await mkdir3(ARTIFACT_DIR2, { recursive: true });
+  await mkdir4(ARTIFACT_DIR2, { recursive: true });
   const { conn, target: resolved } = await openPage(target, { timeoutMs: opts.timeoutMs });
   const file = opts.file ?? recFile(resolved.id);
   if (opts.truncate) {
-    await writeFile3(file, "");
+    await writeFile4(file, "");
   }
   let chain = Promise.resolve();
   let dropped = 0;
@@ -1869,7 +2143,7 @@ function lineToEntry(line, index) {
 async function readConsoleEntries(file) {
   let raw;
   try {
-    raw = await readFile2(file, "utf8");
+    raw = await readFile3(file, "utf8");
   } catch {
     return [];
   }
@@ -1925,7 +2199,7 @@ async function getConsoleMessage(args = {}) {
 }
 
 // src/tools/network.ts
-import { readFile as readFile3 } from "node:fs/promises";
+import { readFile as readFile4 } from "node:fs/promises";
 var DEFAULT_CAPTURE_MS2 = 2500;
 function asHeaders(v) {
   if (!v || typeof v !== "object")
@@ -1992,7 +2266,7 @@ function correlate(lines) {
 async function readNetworkRequests(file) {
   let raw;
   try {
-    raw = await readFile3(file, "utf8");
+    raw = await readFile4(file, "utf8");
   } catch {
     return [];
   }
@@ -2074,8 +2348,8 @@ async function getNetworkRequest(args = {}) {
 }
 
 // src/tools/performance.ts
-import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4, stat, unlink as unlink2 } from "node:fs/promises";
-import { join as join3 } from "node:path";
+import { mkdir as mkdir5, readFile as readFile5, writeFile as writeFile5, stat, unlink as unlink3 } from "node:fs/promises";
+import { join as join4 } from "node:path";
 var ARTIFACT_DIR3 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR2 = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 var DEFAULT_CATEGORIES = [
@@ -2093,7 +2367,7 @@ function shortId(id) {
   return id.slice(0, 8);
 }
 function stateFilePath() {
-  return join3(STATE_DIR2, "trace-state.json");
+  return join4(STATE_DIR2, "trace-state.json");
 }
 function bufferTraceData(conn, sink) {
   return conn.on("Tracing.dataCollected", (params) => {
@@ -2115,10 +2389,10 @@ async function endTrace(conn, sink, timeoutMs = 30000) {
   return sink;
 }
 async function writeTrace(events, targetId) {
-  await mkdir4(ARTIFACT_DIR3, { recursive: true });
-  const path = join3(ARTIFACT_DIR3, `trace-${shortId(targetId)}-${stamp2()}.json`);
+  await mkdir5(ARTIFACT_DIR3, { recursive: true });
+  const path = join4(ARTIFACT_DIR3, `trace-${shortId(targetId)}-${stamp2()}.json`);
   const body = JSON.stringify({ traceEvents: events, metadata: { source: "cdp-toolkit" } });
-  await writeFile4(path, body, "utf8");
+  await writeFile5(path, body, "utf8");
   const { size } = await stat(path);
   return { path, bytes: size };
 }
@@ -2138,7 +2412,7 @@ async function performanceStartTrace(args = {}) {
     throw err;
   }
   liveTraces.set(target.id, { conn, target, events, startedAt: Date.now() });
-  await mkdir4(STATE_DIR2, { recursive: true });
+  await mkdir5(STATE_DIR2, { recursive: true });
   const state = {
     targetId: target.id,
     url: target.url,
@@ -2146,7 +2420,7 @@ async function performanceStartTrace(args = {}) {
     pid: process.pid,
     categories
   };
-  await writeFile4(stateFilePath(), JSON.stringify(state), "utf8");
+  await writeFile5(stateFilePath(), JSON.stringify(state), "utf8");
   return {
     target: { id: target.id, url: target.url, title: target.title },
     categories,
@@ -2159,7 +2433,7 @@ async function performanceStopTrace(args = {}) {
   if (!entry) {
     let hint = "";
     try {
-      const raw = await readFile4(stateFilePath(), "utf8");
+      const raw = await readFile5(stateFilePath(), "utf8");
       const state = JSON.parse(raw);
       hint = state.pid === process.pid ? ` (state file lists target ${shortId(state.targetId)} but its live connection is gone)` : ` (trace was started by a DIFFERENT process pid=${state.pid}; live recordings cannot cross process boundaries)`;
     } catch {}
@@ -2171,7 +2445,7 @@ async function performanceStopTrace(args = {}) {
   } finally {
     conn.close();
     liveTraces.delete(target.id);
-    await unlink2(stateFilePath()).catch(() => {});
+    await unlink3(stateFilePath()).catch(() => {});
   }
   const written = await writeTrace(events, target.id);
   const metrics = analyzeEvents(events);
@@ -2289,7 +2563,7 @@ async function performanceAnalyzeInsight(args = {}) {
   }
   let raw;
   try {
-    raw = await readFile4(args.tracePath, "utf8");
+    raw = await readFile5(args.tracePath, "utf8");
   } catch (err) {
     throw new CdpError(`cannot read trace file '${args.tracePath}': ${err.message}`);
   }
@@ -2306,8 +2580,8 @@ async function performanceAnalyzeInsight(args = {}) {
 }
 
 // src/tools/heap.ts
-import { mkdir as mkdir5, writeFile as writeFile5 } from "node:fs/promises";
-import { join as join4 } from "node:path";
+import { mkdir as mkdir6, writeFile as writeFile6 } from "node:fs/promises";
+import { join as join5 } from "node:path";
 var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function stamp3(targetId) {
   const short = targetId.slice(0, 8);
@@ -2332,9 +2606,9 @@ async function takeHeapsnapshot(args = {}) {
     if (snapshot.length === 0) {
       throw new Error("HeapProfiler.takeHeapSnapshot produced no chunks");
     }
-    await mkdir5(ARTIFACT_DIR4, { recursive: true });
-    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join4(ARTIFACT_DIR4, args.savePath) : join4(ARTIFACT_DIR4, `take_heapsnapshot-${stamp3(target.id)}.heapsnapshot`);
-    await writeFile5(path, snapshot, "utf8");
+    await mkdir6(ARTIFACT_DIR4, { recursive: true });
+    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join5(ARTIFACT_DIR4, args.savePath) : join5(ARTIFACT_DIR4, `take_heapsnapshot-${stamp3(target.id)}.heapsnapshot`);
+    await writeFile6(path, snapshot, "utf8");
     const bytes = Buffer.byteLength(snapshot, "utf8");
     return {
       path,
@@ -2347,7 +2621,7 @@ async function takeHeapsnapshot(args = {}) {
 
 // src/tools/lighthouse.ts
 import { spawn } from "node:child_process";
-import { mkdir as mkdir6, readFile as readFile5, stat as stat2 } from "node:fs/promises";
+import { mkdir as mkdir7, readFile as readFile6, stat as stat2 } from "node:fs/promises";
 var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function cdpPort() {
   const base = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
@@ -2408,7 +2682,7 @@ async function lighthouseAudit(args) {
   const url = args.url.trim();
   const timeoutMs = args.timeoutMs ?? 120000;
   const port = cdpPort();
-  await mkdir6(ARTIFACT_DIR5, { recursive: true });
+  await mkdir7(ARTIFACT_DIR5, { recursive: true });
   const outPath = args.savePath ?? `${ARTIFACT_DIR5}/lighthouse-${shortHost(url)}-${stamp4()}.json`;
   const formFactor = args.formFactor ?? "desktop";
   const lhArgs = [
@@ -2437,7 +2711,7 @@ async function lighthouseAudit(args) {
   }
   let raw;
   try {
-    raw = await readFile5(outPath, "utf8");
+    raw = await readFile6(outPath, "utf8");
   } catch {
     raw = undefined;
   }
@@ -2494,6 +2768,9 @@ var TOOLS = {
   navigate_page: onCdp(SHARED_TOOLS.navigate_page),
   wait_for: onCdp(SHARED_TOOLS.wait_for),
   evaluate_script: onCdp(SHARED_TOOLS.evaluate_script),
+  list_cookies: onCdp(SHARED_TOOLS.list_cookies),
+  set_cookie: onCdp(SHARED_TOOLS.set_cookie),
+  delete_cookies: onCdp(SHARED_TOOLS.delete_cookies),
   take_snapshot: onCdp(SHARED_TOOLS.take_snapshot),
   click: onCdp(SHARED_TOOLS.click),
   hover: onCdp(SHARED_TOOLS.hover),
@@ -3030,6 +3307,37 @@ function buildSnapshotFunctionSource() {
 var MAX_NAME_LENGTH = 120;
 
 // src/bidi/driver.ts
+function normalizeBidiCookie(c) {
+  const value = c.value.type === "base64" ? Buffer.from(c.value.value, "base64").toString("utf8") : c.value.value;
+  const hasExpiry = typeof c.expiry === "number";
+  return {
+    name: c.name,
+    value,
+    domain: c.domain,
+    path: c.path,
+    expires: hasExpiry ? c.expiry : -1,
+    size: typeof c.size === "number" ? c.size : Buffer.byteLength(`${c.name}${value}`, "utf8"),
+    httpOnly: c.httpOnly === true,
+    secure: c.secure === true,
+    sameSite: c.sameSite ?? "default",
+    session: !hasExpiry
+  };
+}
+function hostFromUrl(url, toolName) {
+  if (url === undefined || url === "") {
+    throw driverError2("unsupported", `${toolName} on Firefox needs a 'domain': BiDi's storage cookie calls have no 'url' parameter, and no url was given to derive one from.`);
+  }
+  let host = "";
+  try {
+    host = new URL(url).hostname;
+  } catch {
+    throw driverError2("unsupported", `${toolName} could not parse the url '${url}' to derive the 'domain' BiDi requires. Pass 'domain' explicitly.`);
+  }
+  if (host === "") {
+    throw driverError2("unsupported", `${toolName} cannot derive a 'domain' from '${url}': that url has no host. Pass 'domain' explicitly.`);
+  }
+  return host;
+}
 function driverError2(code, message, data) {
   return Object.assign(new Error(message), { code, ...data !== undefined ? { data } : {} });
 }
@@ -3638,6 +3946,49 @@ class BidiPageDriver {
     }
     return this.handleOneDialog(accept, promptText, opts?.timeoutMs ?? 15000);
   }
+  async getCookies() {
+    try {
+      const { cookies } = await this.conn.send("storage.getCookies", { partition: { type: "context", context: this.contextId } });
+      return (cookies ?? []).map(normalizeBidiCookie);
+    } catch (e) {
+      throw mapBidiError(e);
+    }
+  }
+  async setCookie(params) {
+    const domain = params.domain ?? hostFromUrl(params.url, "set_cookie");
+    try {
+      await this.conn.send("storage.setCookie", {
+        cookie: {
+          name: params.name,
+          value: { type: "string", value: params.value },
+          domain,
+          ...params.path !== undefined ? { path: params.path } : {},
+          ...params.expires !== undefined ? { expiry: params.expires } : {},
+          ...params.httpOnly !== undefined ? { httpOnly: params.httpOnly } : {},
+          ...params.secure !== undefined ? { secure: params.secure } : {},
+          ...params.sameSite !== undefined ? { sameSite: params.sameSite } : {}
+        },
+        partition: { type: "context", context: this.contextId }
+      });
+    } catch (e) {
+      throw mapBidiError(e);
+    }
+  }
+  async deleteCookies(filter) {
+    const domain = filter.domain ?? hostFromUrl(filter.url, "delete_cookies");
+    try {
+      await this.conn.send("storage.deleteCookies", {
+        filter: {
+          name: filter.name,
+          domain,
+          ...filter.path !== undefined ? { path: filter.path } : {}
+        },
+        partition: { type: "context", context: this.contextId }
+      });
+    } catch (e) {
+      throw mapBidiError(e);
+    }
+  }
   async startBodyCapture() {
     let collector;
     try {
@@ -3812,7 +4163,7 @@ import { spawn as spawn2 } from "node:child_process";
 import { mkdtempSync, rmSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 function resolveBinary() {
   const candidates = [
     process.env.FIREFOX_BIN,
@@ -3886,7 +4237,7 @@ async function launchFirefox(opts = {}) {
   const binary = resolveBinary();
   const port = await pickPort(opts.port);
   const isThrowaway = opts.profilePath === undefined;
-  const profilePath = opts.profilePath ?? mkdtempSync(join5(tmpdir(), "cdp-toolkit-ff-profile-"));
+  const profilePath = opts.profilePath ?? mkdtempSync(join6(tmpdir(), "cdp-toolkit-ff-profile-"));
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
   if (opts.headless)
     args.push("--headless");