cdp-toolkit 1.2.0 → 1.4.0

package/dist/mcp.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),
@@ -2535,7 +2812,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 var MANIFEST = [
   {
     name: "list_pages",
-    description: "Enumerate browser page targets via the CDP browser endpoint (GET /json/list). By default returns only page-type tabs; set 'all' to also include workers and background pages. Each entry carries the targetId used as a target selector elsewhere.",
+    description: "Enumerate browser page targets via the CDP browser endpoint (GET /json/list). By default returns only page-type tabs; set 'all' to also include workers and background pages. Each entry carries the targetId used as a target selector elsewhere, plus an 'origin' field recording where the tab came from: 'agent' means this toolkit created it (the entry then also carries the creating 'label' and 'createdAt'), and this stays true after the creating agent releases its lease or dies, which is what makes a stray agent tab findable later. 'unknown' means there is no creation record. It never says 'human': the toolkit cannot prove a person opened a tab, so 'unknown' is the honest word for a tab it did not create, one opened before the toolkit ran, or one whose record could not be written. A tab whose record exists but could not be read reports origin 'unknown' plus 'originUnreadable', so a broken record is never mistaken for no record.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2702,7 +2979,7 @@ var MANIFEST = [
   },
   {
     name: "evaluate_script",
-    description: "Run arbitrary JavaScript in the target page's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args' the 'expression' is evaluated as a raw expression; when 'args' is provided 'expression' must be a function literal (arrow or classic) invoked on globalThis with the args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string.",
+    description: "Run arbitrary JavaScript in the target page's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args' the 'expression' is evaluated as a raw expression; when 'args' is provided 'expression' must be a function literal (arrow or classic) invoked on globalThis with the args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string. Pass 'savePath' to write the evaluated value to a JSON file instead: the response then carries only {path,bytes,type,target} and the value itself never appears in it, in any form. That is the way to read a credential (a JWT or session token out of localStorage, for example) without putting the secret into the caller's transcript.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2725,6 +3002,10 @@ var MANIFEST = [
         args: {
           type: "array",
           description: "Positional JSON-serializable arguments to pass to the expression, treating it as a function. No live element/page handle is bound."
+        },
+        savePath: {
+          type: "string",
+          description: "Write the evaluated value to this file as JSON and KEEP IT OUT OF THE RESPONSE: with savePath set the result is {path,bytes,type,target} only, with no copy, preview or truncation of the value. Use it to read credentials without putting them in a transcript. An absolute path (starting with /) is used as-is; a relative path is resolved under the artifact dir (/tmp/cdp-toolkit). Missing parent directories are created. Omit it to get the value back inline, exactly as before."
         }
       },
       required: [
@@ -2733,6 +3014,128 @@ var MANIFEST = [
       additionalProperties: false
     }
   },
+  {
+    name: "list_cookies",
+    description: "Read the cookie store for the target page, INCLUDING httpOnly cookies, which document.cookie cannot see and an evaluate_script call therefore cannot reach. Each cookie carries name, value, domain, path, expires (Unix seconds, -1 for a session cookie), size, httpOnly, secure, sameSite ('strict'|'lax'|'none'|'default') and session. The read is page-scoped, not browser-wide: it returns the cookies of the resolved tab (Chrome: Network.getCookies; Firefox: storage.getCookies partitioned by that browsing context), so point at a page on the site whose cookies you want. Filter with 'domain' and/or 'name'. Pass 'savePath' to write the cookie array to a JSON file instead: the response is then {path,bytes,count,target} only, with no cookie value in it in any form, which is how to capture a session cookie without putting the credential in the caller's transcript.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+        },
+        domain: {
+          type: "string",
+          description: "Keep only cookies for this domain. A leading dot is ignored on both sides and subdomains of the given domain match too, so 'example.test' matches '.example.test' and 'app.example.test'. No wildcards."
+        },
+        name: {
+          type: "string",
+          description: "Keep only the cookie with exactly this name. Exact match, not a substring."
+        },
+        savePath: {
+          type: "string",
+          description: "Write the cookie array to this file as JSON and KEEP THE VALUES OUT OF THE RESPONSE: with savePath set the result is {path,bytes,count,target} only, with no copy, preview or truncation of any cookie value. An absolute path (starting with /) is used as-is; a relative path is resolved under the artifact dir (/tmp/cdp-toolkit). Missing parent directories are created. Omit it to get the cookies back inline."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "set_cookie",
+    description: "Write one cookie into the target page's cookie store, INCLUDING an httpOnly or secure cookie, which document.cookie cannot create and an evaluate_script call therefore cannot either. Chrome uses Network.setCookie, Firefox uses storage.setCookie partitioned by the resolved browsing context. Either 'url' or 'domain' is REQUIRED: a cookie has to be attributed to a site and the call is refused with an error when neither is given, rather than guessing the current page's origin. The response is {set:true,target} and never echoes the value back, so a credential you just supplied does not land in the transcript twice. A 'set:true' is earned, not assumed: Chrome answers Network.setCookie with success:false when it declines a cookie (a domain the url does not belong to, a secure cookie on an insecure origin, an oversized value) and that refusal is raised as an error. On Firefox, 'domain' is derived from 'url' when only the url was given, because BiDi has no url parameter; a url with no host, such as about:blank or a data URL, is an error rather than a silent no-op. Read the result back with list_cookies when you need proof.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+        },
+        name: {
+          type: "string",
+          description: "Cookie name. Required and non-empty."
+        },
+        value: {
+          type: "string",
+          description: "Cookie value. Required. It is not echoed back in the response."
+        },
+        url: {
+          type: "string",
+          description: "The URL the cookie is set for, for example 'https://example.com/'. Chrome derives domain, path and secure from it. Firefox derives only the domain from its host. Give this or 'domain'."
+        },
+        domain: {
+          type: "string",
+          description: "Cookie domain, for example 'example.com' or '.example.com' for subdomains. Give this or 'url'. When both are given, this wins on Firefox and Chrome applies its own url plus domain consistency rule."
+        },
+        path: {
+          type: "string",
+          description: "Cookie path. Passed through exactly as given and NOT defaulted to '/': with a 'url' Chrome derives the path from it, so an invented default here would widen a cookie you meant to scope narrowly."
+        },
+        expires: {
+          type: "number",
+          description: "Expiry as Unix time in SECONDS, matching what list_cookies reports. Omit it for a session cookie, which is what both backends do when no expiry is supplied."
+        },
+        httpOnly: {
+          type: "boolean",
+          description: "Set the httpOnly flag, making the cookie invisible to document.cookie. Only a protocol write like this one can create such a cookie."
+        },
+        secure: {
+          type: "boolean",
+          description: "Set the secure flag. Chrome declines a secure cookie on an insecure origin, and that refusal surfaces as an error."
+        },
+        sameSite: {
+          type: "string",
+          enum: ["strict", "lax", "none", "default"],
+          description: "SameSite attribute, lowercase, matching what list_cookies reports. 'default' means the attribute is not set at all."
+        }
+      },
+      required: ["name", "value"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "delete_cookies",
+    description: "Delete the named cookie from the target page's cookie store, httpOnly cookies included. Chrome uses Network.deleteCookies, Firefox uses storage.deleteCookies with a filter, partitioned by the resolved browsing context. Both 'name' and one of 'url' or 'domain' are REQUIRED: without a site constraint the call would delete by name across the whole partition, so it is refused with an error instead. Narrow further with 'path'. The response is {deleted:true,target} and carries NO count, because neither protocol reports how many cookies it removed and a number here would be invented; call list_cookies before and after when you need a real count. 'deleted:true' means the backend accepted and performed the deletion, not that a matching cookie existed, since deleting an absent cookie is a success on both backends.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+        },
+        name: {
+          type: "string",
+          description: "Exact cookie name to delete. Required and non-empty. No wildcards: this removes a named cookie, not a swathe of them."
+        },
+        url: {
+          type: "string",
+          description: "Delete cookies matching this URL, for example 'https://example.com/'. Give this or 'domain'. On Firefox only the host is used, because BiDi's filter has no url field."
+        },
+        domain: {
+          type: "string",
+          description: "Delete cookies with this exact domain. Give this or 'url'."
+        },
+        path: {
+          type: "string",
+          description: "Narrow the deletion to cookies with this exact path. Omit to match any path allowed by the other constraints."
+        }
+      },
+      required: ["name"],
+      additionalProperties: false
+    }
+  },
   {
     name: "take_snapshot",
     description: "Capture the page's accessibility tree (Accessibility.getFullAXTree) as a compact indented text tree where each line is prefixed with [uid], the node's CDP backendDOMNodeId. These uids are the stateless element references that every interaction tool (click/hover/fill/etc.) feeds back to resolve a live DOM node (via DOM.resolveNode({ backendNodeId: uid })), so run this first to discover uids.",
@@ -4241,6 +4644,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 } : {} });
 }
@@ -4849,6 +5283,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 {
@@ -5023,7 +5500,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,
@@ -5097,7 +5574,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");
@@ -5367,7 +5844,7 @@ var FIREFOX_TOOLS = {
 };
 
 // src/mcp.ts
-var VERSION = "1.2.0";
+var VERSION = "1.4.0";
 var BROWSER = resolveBrowserKind(stripBrowserFlag(process.argv.slice(2)));
 var AVAILABILITY = toolAvailability(BROWSER);
 var AVAILABLE_NAMES = new Set(AVAILABILITY.available);