cdp-toolkit 1.1.0 → 1.4.0

package/src/shared-tools.ts

@@ -33,11 +33,13 @@
  * behavior outranks the abstraction, these 7 stay two implementations; see the migration report.
  */
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type {
-  BrowserDriver, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
+  BrowserCookie, BrowserDriver, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
 } from "./driver.ts";
 import type { TargetSelector } from "./types.ts";
+import { assertLeaseOk, claimLease, defaultLabel, leaseTtlMs, releaseLeaseFor, type LeaseBackend, type LeaseToken } from "./leases.ts";
+import { newTrackedPage, originIndex, type PageOrigin } from "./origins.ts";
 
 const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 const STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
@@ -49,6 +51,12 @@ function target3(p: PageInfo): { id: string; url: string; title: string } {
   return { id: p.id, url: p.url, title: p.title };
 }
 
+/** Same discriminator leases-tools.ts uses: the driver's own uid scheme tag
+ *  ("cdp" for Chrome, "bidi" for Firefox). */
+function backendOf(driver: BrowserDriver): LeaseBackend {
+  return driver.scheme === "bidi" ? "firefox" : "chrome";
+}
+
 /* -------------------------------- page acquisition -------------------------------- */
 
 /** Acquire, run, always release: the Driver counterpart of client.ts's withPage. */
@@ -61,14 +69,31 @@ async function withPage<T>(driver: BrowserDriver, target: TargetSelector | undef
   }
 }
 
+async function resolvePage(driver: BrowserDriver, selector?: TargetSelector): Promise<PageInfo> {
+  const pages = await driver.listPages();
+  const hit = await pickPage(driver, pages, selector);
+  // THE third choke point. close_page and select_page resolve here and nowhere
+  // else, so the lease check has to be here too, not only in resolveTarget /
+  // resolveContext. Closing someone else's leased tab is the worst version of
+  // the collision this feature exists to stop.
+  //
+  // Deliberately NOT passing liveIds, matching resolveTarget and resolveContext.
+  // For every branch but one it would be inert (hit is an element of `pages`),
+  // and for the bare-id branch it would be actively wrong: that branch can
+  // return a non-page target off the `all:true` listing, whose id is absent
+  // from `pages`, so passing pages' ids would report a perfectly healthy lease
+  // as target-gone and wave the caller straight through it.
+  await assertLeaseOk(backendOf(driver), hit.id, { url: hit.url, title: hit.title });
+  return hit;
+}
+
 /**
  * Same TargetSelector grammar as client.ts's resolveTarget. Matches its one asymmetry exactly:
  * every branch resolves against page-type targets only EXCEPT a bare-id lookup, which (like
  * legacy resolveTarget's `targets.find`) searches the FULL unfiltered listing, so passing an
  * exact non-page targetId (a worker, an iframe) still resolves.
  */
-async function resolvePage(driver: BrowserDriver, selector?: TargetSelector): Promise<PageInfo> {
-  const pages = await driver.listPages();
+async function pickPage(driver: BrowserDriver, pages: PageInfo[], selector?: TargetSelector): Promise<PageInfo> {
   if (selector === undefined || selector === "active") {
     if (!pages.length) throw new SharedToolError("no page targets open");
     return pages[0]!;
@@ -109,21 +134,97 @@ function locatorOf(args: { uid?: DriverUid; selector?: string }): ElementLocator
 
 /* -------------------------------- pages (4) -------------------------------- */
 
-export async function listPages(driver: BrowserDriver, args: { all?: boolean } = {}): Promise<{ pages: PageInfo[]; count: number }> {
+/**
+ * A page listing entry, PageInfo plus provenance. STRICTLY ADDITIVE: {id, url,
+ * title, type} are unchanged in name, type and value, because consumers read
+ * them today.
+ */
+export interface ListedPage extends PageInfo {
+  /** "agent" when the creation ledger has a record for this target. Otherwise
+   *  "unknown", NEVER "human": the absence of a record is not proof that a
+   *  person opened the tab. See src/origins.ts. */
+  origin: PageOrigin;
+  /** The creating agent's label. Present only when origin is "agent". */
+  label?: string;
+  /** When this toolkit created the tab (epoch ms). Only when origin is "agent". */
+  createdAt?: number;
+  /** Present only when this target HAS a ledger record that could not be read:
+   *  the errno, or "unparseable". origin stays "unknown" because provenance is
+   *  genuinely unknown, but this field is what keeps an unreadable record from
+   *  being reported as a clean "nothing was ever recorded". */
+  originUnreadable?: string;
+}
+
+/**
+ * The reap set for the origin ledger: every target the browser currently has,
+ * INCLUDING non-page targets, regardless of what this call is listing.
+ *
+ * Using the filtered page list would be a bug with a plausible disguise: a
+ * default list_pages call drops workers and iframes, so reaping against it
+ * would delete the ledger record of any target that is alive but filtered out.
+ * Returning undefined (which listOrigins reads as "reap nothing") when the
+ * unfiltered listing fails is the same principle one step further: a failed
+ * enumeration must never be able to empty the ledger.
+ */
+async function reapSet(driver: BrowserDriver, pages: PageInfo[], all?: boolean): Promise<readonly string[] | undefined> {
+  if (all === true) return pages.map((p) => p.id);
+  try {
+    return (await driver.listPages({ all: true })).map((p) => p.id);
+  } catch {
+    return undefined;
+  }
+}
+
+export async function listPages(driver: BrowserDriver, args: { all?: boolean } = {}): Promise<{ pages: ListedPage[]; count: number }> {
   const pages = await driver.listPages({ all: args.all });
-  return { pages, count: pages.length };
+  // Never let provenance break the listing: originIndex does not throw, and a
+  // missing or unreadable ledger yields an empty map, so every page falls back
+  // to origin "unknown" exactly as a pre-ledger consumer always saw.
+  const ledger = await originIndex(backendOf(driver), await reapSet(driver, pages, args.all));
+  const annotated: ListedPage[] = 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 };
 }
 
-export async function newPage(driver: BrowserDriver, args: { url?: string } = {}): Promise<{ targetId: string; url: string }> {
-  const p = await driver.newPage(args.url);
-  return { targetId: p.id, url: p.url };
+export async function newPage(
+  driver: BrowserDriver,
+  args: { url?: string; claim?: boolean; label?: string; ttlMs?: number } = {},
+): Promise<{ targetId: string; url: string; lease?: LeaseToken; label?: string; expiresAt?: number }> {
+  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
+  // Creates the tab AND writes its creation record. The record outlives any
+  // lease taken below, which is the point: a released tab is still an agent's.
+  const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label });
+  if (args.claim !== true) return { targetId: p.id, url: p.url };
+  // Atomic in the sense that matters: the tab is claimed before this call
+  // returns, so no other agent can see it unclaimed and take it first.
+  const { record, token } = await claimLease(backendOf(driver), p.id, {
+    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 };
 }
 
-export async function closePage(driver: BrowserDriver, args: { target?: TargetSelector }): Promise<{ closed: string; success: boolean }> {
+export async function closePage(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector },
+): Promise<{ closed: string; success: boolean; leaseReleased?: boolean }> {
   if (args.target === undefined || args.target === "") throw new SharedToolError("close_page requires an explicit target; refusing to guess which page to close");
   const p = await resolvePage(driver, args.target);
   const res = await driver.closePage(p.id);
-  return { closed: p.id, success: res.success };
+  // A failed close (target refused to close, or was already gone) must leave
+  // the lease intact: the caller still owns a tab that never actually closed,
+  // and releasing it here would let another agent claim a tab this one still
+  // thinks it holds.
+  if (!res.success) return { closed: p.id, success: false, leaseReleased: false };
+  // Closing a leased tab must not leave its lease file behind waiting on the
+  // TTL. resolvePage above already refused this call unless the caller holds
+  // the lease, so no token is needed here.
+  const released = await releaseLeaseFor(backendOf(driver), p.id);
+  return { closed: p.id, success: true, ...(released.released ? { leaseReleased: true } : {}) };
 }
 
 async function writeSelectedFile(id: string): Promise<void> {
@@ -186,14 +287,261 @@ export const waitFor = waitForText;
 
 /* ------------------------------- evaluate (1) ------------------------------- */
 
+/**
+ * The `savePath` result shape. Deliberately carries NO form of the evaluated
+ * value: not the value, not a preview, not a truncation, not a byte prefix.
+ * The whole reason `savePath` exists is that the value may be a credential
+ * (a JWT or session token read out of localStorage), and anything this object
+ * carried would land in the caller's transcript, which is the exact leak the
+ * file sink is here to prevent. `type` is the JS typeof of the value ("null"
+ * for null), which describes the value without disclosing any of it.
+ */
+export interface EvaluateScriptSaveResult {
+  path: string;
+  bytes: number;
+  type: string;
+  target: { id: string; url: string; title: string };
+}
+
+/**
+ * Serialize an evaluated value for the file sink. `undefined` (an expression
+ * with no result) is written as JSON null rather than left unwritten, so the
+ * file always exists and always parses.
+ */
+function serializeForSink(value: unknown): string {
+  const json = JSON.stringify(value === undefined ? null : value, null, 2);
+  return json ?? "null";
+}
+
+/**
+ * THE file sink, shared by every tool that takes a `savePath`: serialize the
+ * value as JSON, write it, and report only where it went and how big it was.
+ * It returns no form of the value on purpose, so a caller of this helper
+ * cannot accidentally leak one back into a response.
+ *
+ * Path resolution matches take_heapsnapshot: an absolute path is used as-is, a
+ * relative one resolves under the artifact dir, and missing parent directories
+ * are created.
+ */
+async function writeJsonSink(savePath: string, value: unknown): Promise<{ path: string; bytes: number }> {
+  const path = savePath.startsWith("/") ? savePath : join(ARTIFACT_DIR, savePath);
+  await mkdir(dirname(path), { recursive: true });
+  const json = serializeForSink(value);
+  await writeFile(path, json, "utf8");
+  return { path, bytes: Buffer.byteLength(json, "utf8") };
+}
+
+/** True when a savePath argument actually asks for the sink. An empty string is
+ *  treated as absent, so the caller gets the value inline. */
+function sinkRequested(savePath?: string): savePath is string {
+  return savePath !== undefined && savePath !== "";
+}
+
 export async function evaluateScript(
   driver: BrowserDriver,
-  args: { target?: TargetSelector; expression: string; awaitPromise?: boolean; args?: unknown[] },
+  args: { target?: TargetSelector; expression: string; awaitPromise?: boolean; args?: unknown[]; savePath?: string },
 ): Promise<unknown> {
   if (typeof args.expression !== "string" || args.expression.length === 0) {
     throw new SharedToolError("evaluateScript: 'expression' must be a non-empty string");
   }
-  return withPage(driver, args.target, (page) => page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true }));
+  return withPage(driver, args.target, async (page) => {
+    const value = await page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true });
+    // No savePath: byte-identical to the pre-sink behavior, the value itself.
+    // A thrown page-side exception never reaches here, so it still surfaces as
+    // an error rather than being written into the file.
+    if (!sinkRequested(args.savePath)) return value;
+
+    const { path, bytes } = await writeJsonSink(args.savePath, value);
+    const result: EvaluateScriptSaveResult = {
+      path,
+      bytes,
+      type: value === null ? "null" : typeof value,
+      target: target3(page.info),
+    };
+    return result;
+  });
+}
+
+/* -------------------------------- cookies (1) -------------------------------- */
+
+/**
+ * The `savePath` result shape for list_cookies. Same rule as
+ * EvaluateScriptSaveResult: NO cookie value in any form, not even a prefix. A
+ * session cookie IS the credential, so a preview of one is a leaked one.
+ * `count` is how many cookies were written, which tells a caller the read
+ * worked without disclosing anything about what it read.
+ */
+export interface ListCookiesSaveResult {
+  path: string;
+  bytes: number;
+  count: number;
+  target: { id: string; url: string; title: string };
+}
+
+export interface ListCookiesResult {
+  cookies: BrowserCookie[];
+  count: number;
+  target: { id: string; url: string; title: string };
+}
+
+/**
+ * Cookie domain matching for the `domain` filter, deliberately small.
+ *
+ * A cookie's own domain carries a leading dot when it was set for subdomains
+ * (".example.test") and none when it was host-only ("example.test"), and a
+ * caller who types "example.test" means both. So the comparison strips a
+ * leading dot from each side and then accepts an exact match or a subdomain of
+ * the filter ("app.example.test" matches "example.test"). That is the whole
+ * rule: no wildcards, no patterns, no query language.
+ */
+function cookieDomainMatches(cookieDomain: string, filter: string): boolean {
+  const bare = (d: string) => (d.startsWith(".") ? d.slice(1) : d).toLowerCase();
+  const c = bare(cookieDomain);
+  const f = bare(filter);
+  return c === f || c.endsWith(`.${f}`);
+}
+
+/** Apply the optional name/domain filters. Exported for the unit tests, which
+ *  can then check the matching rule without standing up a browser. */
+export function filterCookies(cookies: readonly BrowserCookie[], filter: { domain?: string; name?: string }): BrowserCookie[] {
+  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;
+  });
+}
+
+/**
+ * Read the cookies of the target page, httpOnly ones included.
+ *
+ * This is the one read that a page script cannot do: document.cookie omits
+ * every httpOnly cookie by design, which is precisely the set a session
+ * credential lives in. Both drivers answer over the protocol's own cookie
+ * store, so the flags come from the browser rather than being inferred.
+ *
+ * With `savePath` set the cookie array is written to that file as JSON and the
+ * response carries only {path, bytes, count, target}: no value, no preview, no
+ * truncation. Without it, the cookies are returned inline.
+ */
+export async function listCookies(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; domain?: string; name?: string; savePath?: string } = {},
+): Promise<ListCookiesResult | ListCookiesSaveResult> {
+  return withPage(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) };
+  });
+}
+
+export interface SetCookieResult {
+  set: true;
+  target: { id: string; url: string; title: string };
+}
+
+export interface DeleteCookiesResult {
+  deleted: true;
+  target: { id: string; url: string; title: string };
+}
+
+/**
+ * THE site constraint both write tools share: a cookie has to be attributed to
+ * a site, and `url` or `domain` is how a caller says which.
+ *
+ * Checked here, above the drivers, so the refusal is ONE message on both
+ * backends rather than a CDP protocol error on one and a Firefox no-op on the
+ * other. It throws rather than defaulting to the current page's origin: a
+ * guessed domain writes a real cookie somewhere the caller did not name, and a
+ * cookie written to the wrong site is worse than a call that failed loudly.
+ *
+ * Exported for the unit tests, which pin the message without a browser.
+ */
+export function assertCookieSite(
+  args: { url?: string; domain?: string },
+  toolName: string,
+): void {
+  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.`);
+  }
+}
+
+/** The shared 'name' check. A write tool with no name has nothing to write and
+ *  a delete tool with no name would match every cookie, so an empty one is
+ *  refused rather than treated as absent. */
+function assertCookieName(name: string | undefined, toolName: string): asserts name is string {
+  if (name === undefined || name === "") {
+    throw new Error(`${toolName} requires a non-empty 'name'.`);
+  }
+}
+
+/**
+ * Write one cookie into the target page's cookie store.
+ *
+ * The response is deliberately tiny: `{set: true, target}`. It does NOT echo
+ * the value back, because the value is frequently the credential and a caller
+ * who just supplied it does not need it repeated into their transcript. The
+ * `set: true` is earned rather than assumed: the CDP driver throws on Chrome's
+ * `{success:false}` refusal and the BiDi driver throws when it cannot derive
+ * the domain BiDi requires, so reaching this line means a backend confirmed
+ * the write.
+ */
+export async function setCookie(
+  driver: BrowserDriver,
+  args: {
+    target?: TargetSelector; name: string; value: string; url?: string; domain?: string;
+    path?: string; expires?: number; httpOnly?: boolean; secure?: boolean;
+    sameSite?: "strict" | "lax" | "none" | "default";
+  },
+): Promise<SetCookieResult> {
+  assertCookieName(args.name, "set_cookie");
+  if (typeof args.value !== "string") throw new Error("set_cookie requires a string 'value'.");
+  assertCookieSite(args, "set_cookie");
+  return withPage(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 as const, target: target3(page.info) };
+  });
+}
+
+/**
+ * Remove the named cookie from the target page's cookie store.
+ *
+ * `{deleted: true, target}` and NO count, on purpose. Neither protocol reports
+ * how many cookies it removed, so any number here would be invented; a caller
+ * who needs one reads list_cookies before and after. `deleted: true` means the
+ * backend accepted and performed the deletion, not that a matching cookie
+ * existed: deleting an absent cookie is a success on both backends.
+ */
+export async function deleteCookies(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; name: string; url?: string; domain?: string; path?: string },
+): Promise<DeleteCookiesResult> {
+  assertCookieName(args.name, "delete_cookies");
+  assertCookieSite(args, "delete_cookies");
+  return withPage(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 as const, target: target3(page.info) };
+  });
 }
 
 /* -------------------------------- snapshot (1) -------------------------------- */
@@ -394,7 +742,7 @@ export async function handleDialog(
 
 /* ------------------------------------- registry ------------------------------------- */
 
-/** The 20 tools this file unifies, importable by both src/index.ts (Chrome) and
+/** The 23 tools this file unifies, importable by both src/index.ts (Chrome) and
  *  src/firefox-tools.ts (Firefox). Each function is (driver, args) => Promise<result>. */
 export const SHARED_TOOLS = {
   list_pages: listPages,
@@ -404,6 +752,9 @@ export const 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,

package/src/tools/console.ts

@@ -1,5 +1,5 @@
 /**
- * console.ts — read console output captured by the recorder.
+ * console.ts: read console output captured by the recorder.
  *
  *   list_console_messages -> listConsoleMessages
  *   get_console_message   -> getConsoleMessage
@@ -135,7 +135,7 @@ async function readConsoleEntries(file: string): Promise<ConsoleEntry[]> {
 }
 
 /**
- * list_console_messages — return console output for the target. With
+ * list_console_messages: return console output for the target. With
  * `reload:true`, records a fresh capture window by reloading the page.
  */
 export async function listConsoleMessages(args: ListConsoleMessagesArgs = {}): Promise<{
@@ -166,7 +166,7 @@ export async function listConsoleMessages(args: ListConsoleMessagesArgs = {}): P
 }
 
 /**
- * get_console_message — return a single console entry by index from the
+ * get_console_message: return a single console entry by index from the
  * existing buffer for the target. Throws if the index is out of range.
  */
 export async function getConsoleMessage(args: GetConsoleMessageArgs = {}): Promise<ConsoleEntry> {

package/src/tools/evaluate.ts

@@ -1,5 +1,5 @@
 /**
- * evaluate_script — run arbitrary JavaScript in a page's main context over raw
+ * evaluate_script: run arbitrary JavaScript in a page's main context over raw
  * CDP and return the evaluated value.
  *
  * Two modes, selected by whether `args` is supplied:
@@ -148,7 +148,7 @@ export async function evaluateScript(args: EvaluateScriptArgs): Promise<unknown>
  *
  * Parity gaps vs chrome-devtools-mcp evaluate_script:
  *   - MCP injects a typed `page`/element handle into the evaluated function; here `args` are plain
- *     JSON-serializable values passed positionally — no live element/page handle is bound.
+ *     JSON-serializable values passed positionally; no live element/page handle is bound.
  *   - Non-serializable return values (DOM nodes, functions, circular objects) come back as their CDP
  *     `description` string rather than a structured handle, since returnByValue is used.
  *   - No isolated-world/contextId selection: evaluation runs in the page's default main-world context.

package/src/tools/heap.ts

@@ -1,5 +1,5 @@
 /**
- * heap.ts — `take_heapsnapshot` over raw CDP.
+ * heap.ts: `take_heapsnapshot` over raw CDP.
  *
  * Captures a V8 heap snapshot of a page target and writes it as a
  * `.heapsnapshot` file (the JSON format DevTools' Memory panel loads).
@@ -7,7 +7,7 @@
  * CDP semantics this module relies on:
  *   - `HeapProfiler.takeHeapSnapshot` streams the snapshot back as a sequence
  *     of `HeapProfiler.addHeapSnapshotChunk` events. The command's own result
- *     does NOT carry the data — it resolves only after the final chunk has been
+ *     does NOT carry the data; it resolves only after the final chunk has been
  *     emitted. So we subscribe to the chunk event first, accumulate every
  *     chunk's string, then `await` the command; once it resolves we have the
  *     complete snapshot and join the chunks into one JSON document.
@@ -103,7 +103,7 @@ export async function takeHeapsnapshot(
  *
  * Parity gaps vs chrome-devtools-mcp `take_heapsnapshot`:
  *   - reportProgress is forced false; no incremental progress callbacks surfaced.
- *   - Returns {path,bytes,chunks,target} only — does not parse/summarize the
+ *   - Returns {path,bytes,chunks,target} only; does not parse/summarize the
  *     snapshot (node counts, retained sizes); the .heapsnapshot file is for the
  *     DevTools Memory panel to load, matching the MCP tool's artifact behavior.
  * --------------------------------------------------------------------------*/

package/src/tools/lighthouse.ts

@@ -1,5 +1,5 @@
 /**
- * lighthouse_audit — THE ONLY non-CDP tool in this toolkit.
+ * lighthouse_audit: THE ONLY non-CDP tool in this toolkit.
  *
  * Unlike every other module, this one does NOT speak the Chrome DevTools
  * Protocol over a WebSocket. Instead it shells out to the external Lighthouse
@@ -105,7 +105,7 @@ interface LighthouseReport {
 }
 
 export interface LighthouseAuditArgs {
-  /** The URL to audit. Required — never points at a user tab implicitly. */
+  /** The URL to audit. Required, and never points at a user tab implicitly. */
   url: string;
   /**
    * Lighthouse categories to run. Defaults to the full set.
@@ -206,7 +206,7 @@ export async function lighthouseAudit(
     const hint = /not found|could not determine executable|npm ERR|E404|ERR_MODULE/i.test(
       res.stderr,
     )
-      ? " The Lighthouse CLI could not be fetched/installed via npx — ensure network access and that 'lighthouse' is installable."
+      ? " The Lighthouse CLI could not be fetched/installed via npx; ensure network access and that 'lighthouse' is installable."
       : "";
     throw new CdpError(
       `lighthouse_audit produced no report (exit code ${res.code}).${hint} stderr: ${truncate(res.stderr)}`,
@@ -264,7 +264,7 @@ function truncate(s: string, max = 600): string {
  * ---------------------------------------------------------------------------
  * NON-CDP MODULE. This is the toolkit's sole tool that does not speak raw CDP.
  *
- * External dependency (subprocess, fetched on demand by npx — not an npm dep):
+ * External dependency (subprocess, fetched on demand by npx, not an npm dep):
  *   - `npx --yes lighthouse <url> --port=<cdpPort> --output=json
  *      --output-path=<artifact> --quiet --preset=desktop
  *      [--only-categories=...] --chrome-flags=--headless=new`

package/src/tools/navigation.ts

@@ -48,7 +48,7 @@ export interface NavigatePageResult {
  * finish loading.
  *
  * `Page.navigate`/`Page.reload` resolve once the action is *committed*. We
- * separately race the load milestone event — subscribed BEFORE issuing the
+ * separately race the load milestone event, subscribed BEFORE issuing the
  * command so a fast load can't fire before we're listening. Pass
  * `reload:true, ignoreCache:true` for a hard reload that refetches every
  * subresource (the only way to pick up a freshly-deployed bundle the HTTP

package/src/tools/network.ts

@@ -1,5 +1,5 @@
 /**
- * network.ts — read network activity captured by the recorder.
+ * network.ts: read network activity captured by the recorder.
  *
  *   list_network_requests -> listNetworkRequests
  *   get_network_request   -> getNetworkRequest
@@ -8,14 +8,14 @@
  *   - default ({ reload: false }): read the target's shared "latest" buffer
  *     (rec-<targetId>.jsonl), correlate the four Network.* events by requestId,
  *     and return one row per request.
- *   - { reload: true }: run a captureWindow (both domains) — Page.reload, capture
+ *   - { reload: true }: run a captureWindow (both domains): Page.reload, capture
  *     for `durationMs` (default 2500ms), stop, then read+return the requests.
  *
  * Response bodies: CDP only serves a body from the LIVE renderer session, so
  * get_network_request with { includeBody: true } drives a fresh reload capture
  * and calls Network.getResponseBody before closing. Because a reload re-mints
  * requestIds, body fetch is matched by `url` (stable), not by a carried-over
- * requestId — see getNetworkRequest for the exact contract.
+ * requestId; see getNetworkRequest for the exact contract.
  */
 import { readFile } from "node:fs/promises";
 import { CdpError, resolveTarget } from "../client.ts";
@@ -59,7 +59,7 @@ export interface ListNetworkRequestsArgs {
 
 export interface GetNetworkRequestArgs {
   target?: TargetSelector;
-  /** Match by exact requestId (metadata only — see includeBody). */
+  /** Match by exact requestId (metadata only, see includeBody). */
   requestId?: string;
   /** Match by URL substring (first match). Required for body fetch (includeBody). */
   url?: string;
@@ -153,7 +153,7 @@ async function readNetworkRequests(file: string): Promise<NetworkRequest[]> {
 }
 
 /**
- * list_network_requests — correlated request rows for the target. With
+ * list_network_requests: correlated request rows for the target. With
  * `reload:true`, records a fresh capture window (both domains) by reloading.
  */
 export async function listNetworkRequests(args: ListNetworkRequestsArgs = {}): Promise<{
@@ -187,13 +187,13 @@ export async function listNetworkRequests(args: ListNetworkRequestsArgs = {}): P
 }
 
 /**
- * get_network_request — return one request (matched by requestId, else by URL
+ * get_network_request: return one request (matched by requestId, else by URL
  * substring) including response status/headers.
  *
  * Body retrieval: CDP only serves a response body from the LIVE renderer
  * session, so `includeBody:true` must drive a fresh reload capture and fetch the
  * body before the connection closes. A reload re-mints requestIds, so a body
- * fetch can only be matched by `url` (stable across reload) — NOT by a
+ * fetch can only be matched by `url` (stable across reload), NOT by a
  * `requestId` carried over from a prior `list_network_requests`. When a
  * requestId is supplied with includeBody we therefore return metadata from the
  * existing buffer and explain why the body is unavailable, rather than reloading