@mehmoodqureshi/chrome-mcp 0.6.6 → 0.7.0

package/dist/src/mcp/batch.js

@@ -23,6 +23,17 @@ const validators_1 = require("./validators");
 const MAX_OPS = 50;
 const DEFAULT_CONCURRENCY = 6;
 const MAX_CONCURRENCY = 16;
+/**
+ * Default ceiling on the TOTAL payload a batch returns.
+ *
+ * Each op is individually bounded, but a batch multiplies: 50 screenshots or 50
+ * `get_html` reads compose into one unbounded result — which is exactly the case
+ * `batch` is most useful for. Past the budget, an op's blocks are replaced by a
+ * one-line summary so the caller still learns it ran and what it produced.
+ */
+const DEFAULT_MAX_RESULT_BYTES = 1024 * 1024;
+const MIN_RESULT_BYTES = 4 * 1024;
+const MAX_RESULT_BYTES = 32 * 1024 * 1024;
 /** Validate the `ops` envelope. Structural problems throw (the whole batch is
  *  malformed); per-op semantic problems are handled later as per-op errors. */
 function parseOps(raw) {
@@ -70,6 +81,7 @@ async function runBatch(rawArgs, deps) {
     }
     const stopOnError = (0, validators_1.optionalBoolean)(a, 'stopOnError') ?? false;
     const concurrency = (0, validators_1.optionalNumber)(a, 'maxConcurrency', { min: 1, max: MAX_CONCURRENCY }) ?? DEFAULT_CONCURRENCY;
+    const maxResultBytes = (0, validators_1.optionalNumber)(a, 'maxResultBytes', { min: MIN_RESULT_BYTES, max: MAX_RESULT_BYTES }) ?? DEFAULT_MAX_RESULT_BYTES;
     /** Run one op through the firewall, after the per-op guards. Never throws. */
     const runOne = async (op) => {
         if (op.tool === 'batch')
@@ -99,11 +111,26 @@ async function runBatch(rawArgs, deps) {
         const results = await mapLimit(ops, concurrency, (op) => runOne(op));
         outcomes = results.map((result) => ({ status: result.isError ? 'error' : 'ok', result }));
     }
-    return renderBatch(ops, outcomes, mode);
+    return renderBatch(ops, outcomes, mode, maxResultBytes);
+}
+/** Approximate wire size of one content block (base64 image data dominates when present). */
+function blockBytes(block) {
+    const b = block;
+    if (typeof b.text === 'string')
+        return Buffer.byteLength(b.text, 'utf8');
+    if (typeof b.data === 'string')
+        return b.data.length;
+    return 0;
+}
+/** A one-line stand-in for an op whose blocks were dropped to stay inside the budget. */
+function elidedSummary(index, tool, blocks, bytes) {
+    const kinds = [...new Set(blocks.map((b) => b.type))].join('+') || 'none';
+    return `--- op ${index} (${tool}) omitted: ${blocks.length} ${kinds} block(s), ~${bytes} bytes — batch result budget reached; re-run this op on its own to see it ---`;
 }
 /** Compose the per-op outcomes into one MCP result: a JSON summary block first,
- *  then each executed op's own content blocks (text/images flow through intact). */
-function renderBatch(ops, outcomes, mode) {
+ *  then each executed op's own content blocks (text/images flow through intact),
+ *  stopping at `budget` bytes so one batch cannot flood the caller's context. */
+function renderBatch(ops, outcomes, mode, budget) {
     const summary = outcomes.map((o, i) => ({ index: i, tool: ops[i].tool, status: o.status }));
     const counts = {
         total: ops.length,
@@ -111,17 +138,42 @@ function renderBatch(ops, outcomes, mode) {
         error: summary.filter((s) => s.status === 'error').length,
         skipped: summary.filter((s) => s.status === 'skipped').length,
     };
-    const content = [
-        { type: 'text', text: JSON.stringify({ batch: { mode, ...counts }, results: summary }, null, 2) },
-    ];
+    // Render the payload first so the header can report how much was elided — the
+    // caller needs that number to decide whether to re-run anything.
+    const body = [];
+    let spent = 0;
+    let omittedOps = 0;
+    let omittedBytes = 0;
     for (let i = 0; i < outcomes.length; i++) {
         const o = outcomes[i];
         if (!o.result)
             continue; // skipped ops carry no payload
-        content.push({ type: 'text', text: `--- op ${i} (${ops[i].tool}) ${o.status} ---` });
-        for (const block of o.result.content)
-            content.push(block);
+        const blocks = o.result.content;
+        const size = blocks.reduce((n, b) => n + blockBytes(b), 0);
+        if (spent + size > budget && spent > 0) {
+            // `spent > 0` guarantees the first op always gets through: a single op
+            // larger than the whole budget is still more useful than an empty batch.
+            body.push({ type: 'text', text: elidedSummary(i, ops[i].tool, blocks, size) });
+            omittedOps++;
+            omittedBytes += size;
+            continue;
+        }
+        body.push({ type: 'text', text: `--- op ${i} (${ops[i].tool}) ${o.status} ---` });
+        for (const block of blocks)
+            body.push(block);
+        spent += size;
     }
+    const header = {
+        batch: {
+            mode,
+            ...counts,
+            ...(omittedOps > 0
+                ? { omittedOps, omittedBytes, resultBudgetBytes: budget, note: 'some op payloads were omitted to stay within the batch result budget; raise maxResultBytes or re-run those ops individually' }
+                : {}),
+        },
+        results: summary,
+    };
+    const content = [{ type: 'text', text: JSON.stringify(header, null, 2) }, ...body];
     // The batch ran successfully even if some ops failed; only flag isError when
     // nothing succeeded, so a host sees partial success as success.
     const isError = ops.length > 0 && counts.ok === 0;

package/dist/src/mcp/helpers.d.ts

@@ -4,7 +4,7 @@
  * `read_as_markdown` read via primitives; `fill_form` sequences fill+click.
  * (Only `download_file` is privileged and lives on the executor.)
  */
-import type { Executor } from '../executor/types';
+import type { Executor, FrameOpts } from '../executor/types';
 export interface LinkOut {
     href: string;
     text: string;
@@ -24,20 +24,20 @@ export declare function extractLinks(ex: Executor, args: {
     dedupe?: boolean;
     limit?: number;
     tabId?: string;
-}): Promise<{
+} & FrameOpts): Promise<{
     links: LinkOut[];
 }>;
 /** Read a page (or subtree) as readable markdown. */
 export declare function readAsMarkdown(ex: Executor, args: {
     selector?: string;
     tabId?: string;
-}): Promise<string>;
+} & FrameOpts): Promise<string>;
 /** Fill a set of fields (keyed by selector) and optionally submit. */
 export declare function fillForm(ex: Executor, args: {
     fields: Record<string, string | boolean>;
     submitSelector?: string;
     tabId?: string;
-}): Promise<{
+} & FrameOpts): Promise<{
     filled: number;
     submitted: boolean;
 }>;

package/dist/src/mcp/helpers.js

@@ -28,8 +28,9 @@ async function extractLinks(ex, args) {
       href: a.href, text: (a.textContent || '').trim().slice(0, 200),
     })).filter(l => l.href && (${args.sameOriginOnly ? 'l.href.startsWith(here)' : 'true'}));
   })()`;
+    const frames = { frameId: args.frameId, allFrames: args.allFrames };
     let links;
-    const res = await ex.eval(expr, { tabId: args.tabId });
+    const res = await ex.eval(expr, { tabId: args.tabId, ...frames });
     if (res.ok && Array.isArray(res.value)) {
         links = res.value;
     }
@@ -37,6 +38,7 @@ async function extractLinks(ex, args) {
         // Fallback: parse hrefs out of the HTML (e.g. when eval is policy-denied).
         const { html } = await ex.getHtml(args.selector ? { selector: args.selector } : undefined, {
             tabId: args.tabId,
+            ...frames,
         });
         links = [];
         const re = /<a[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi;
@@ -73,26 +75,29 @@ function refineLinks(links, opts) {
 async function readAsMarkdown(ex, args) {
     const { html } = await ex.getHtml(args.selector ? { selector: args.selector } : undefined, {
         tabId: args.tabId,
+        frameId: args.frameId,
+        allFrames: args.allFrames,
     });
     return (0, markdown_extract_1.htmlToMarkdown)(html);
 }
 /** Fill a set of fields (keyed by selector) and optionally submit. */
 async function fillForm(ex, args) {
+    const opts = { tabId: args.tabId, frameId: args.frameId, allFrames: args.allFrames };
     let filled = 0;
     for (const [selector, value] of Object.entries(args.fields)) {
         const target = { selector };
         if (typeof value === 'boolean') {
             // Checkbox/radio: a click toggles it.
-            await ex.click(target, { tabId: args.tabId });
+            await ex.click(target, opts);
         }
         else {
-            await ex.fill(target, value, { tabId: args.tabId });
+            await ex.fill(target, value, opts);
         }
         filled++;
     }
     let submitted = false;
     if (args.submitSelector) {
-        await ex.click({ selector: args.submitSelector }, { tabId: args.tabId });
+        await ex.click({ selector: args.submitSelector }, opts);
         submitted = true;
     }
     return { filled, submitted };

package/dist/src/mcp/limits.d.ts

@@ -0,0 +1,43 @@
+/**
+ * src/mcp/limits.ts — output size caps for the page-read tools.
+ *
+ * `eval` has been capped at 256 KB since 0.1 (MAX_EVAL_BYTES) and `screenshot`
+ * reports `truncated` with the real height, but the three tools that read page
+ * CONTENT — get_html, get_text, read_as_markdown — were unbounded. A single
+ * `get_html` on an ordinary content-heavy page can be several megabytes, which is
+ * enough to consume an agent's entire context window in one call, and the caller
+ * has no way to ask for less.
+ *
+ * The cap is applied server-side, after the read: the full payload is still
+ * written to the task's `results/` directory by the handlers that save artifacts,
+ * so nothing is lost on disk — only what crosses into the model's context is
+ * bounded.
+ */
+/** Default cap on a single content read, matching the long-standing eval cap. */
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+/** Floor/ceiling for a caller-supplied `maxBytes`. */
+export declare const MIN_OUTPUT_BYTES = 1024;
+export declare const MAX_OUTPUT_BYTES: number;
+export interface Truncation {
+    /** The (possibly shortened) text. */
+    text: string;
+    /** True when `text` is shorter than the input. */
+    truncated: boolean;
+    /** UTF-8 byte length of the ORIGINAL text. */
+    totalBytes: number;
+    /** UTF-8 byte length of `text`. */
+    returnedBytes: number;
+}
+/** Truncate plain text (or markdown) to a byte budget. */
+export declare function capText(text: string, maxBytes?: number): Truncation;
+/**
+ * Truncate HTML to a byte budget, backing up to the last tag boundary.
+ *
+ * Cutting mid-tag (`<div class="fo`) hands the caller markup that no parser will
+ * accept and that an LLM will happily hallucinate the rest of. Ending on a `>`
+ * keeps every returned tag complete — the document is still truncated, but every
+ * element in it is well-formed up to the cut.
+ */
+export declare function capHtml(html: string, maxBytes?: number): Truncation;
+/** The metadata fields appended to a truncated read's envelope. */
+export declare function truncationMeta(t: Truncation): Record<string, unknown>;

package/dist/src/mcp/limits.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * src/mcp/limits.ts — output size caps for the page-read tools.
+ *
+ * `eval` has been capped at 256 KB since 0.1 (MAX_EVAL_BYTES) and `screenshot`
+ * reports `truncated` with the real height, but the three tools that read page
+ * CONTENT — get_html, get_text, read_as_markdown — were unbounded. A single
+ * `get_html` on an ordinary content-heavy page can be several megabytes, which is
+ * enough to consume an agent's entire context window in one call, and the caller
+ * has no way to ask for less.
+ *
+ * The cap is applied server-side, after the read: the full payload is still
+ * written to the task's `results/` directory by the handlers that save artifacts,
+ * so nothing is lost on disk — only what crosses into the model's context is
+ * bounded.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_OUTPUT_BYTES = exports.MIN_OUTPUT_BYTES = exports.DEFAULT_MAX_OUTPUT_BYTES = void 0;
+exports.capText = capText;
+exports.capHtml = capHtml;
+exports.truncationMeta = truncationMeta;
+/** Default cap on a single content read, matching the long-standing eval cap. */
+exports.DEFAULT_MAX_OUTPUT_BYTES = 256 * 1024;
+/** Floor/ceiling for a caller-supplied `maxBytes`. */
+exports.MIN_OUTPUT_BYTES = 1024;
+exports.MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+/**
+ * Cut `text` to at most `maxBytes` UTF-8 bytes.
+ *
+ * `Buffer.subarray` slices bytes, which can land mid-codepoint; decoding back to
+ * a string would leave a replacement character at the seam. So the slice is taken
+ * and then trimmed back to the last complete character.
+ */
+function sliceUtf8(text, maxBytes) {
+    const buf = Buffer.from(text, 'utf8');
+    if (buf.byteLength <= maxBytes)
+        return text;
+    let end = maxBytes;
+    // A UTF-8 continuation byte is 10xxxxxx; walk back off the middle of a
+    // multi-byte sequence so the decode is clean.
+    while (end > 0 && (buf[end] & 0b1100_0000) === 0b1000_0000)
+        end--;
+    return buf.subarray(0, end).toString('utf8');
+}
+/** Truncate plain text (or markdown) to a byte budget. */
+function capText(text, maxBytes = exports.DEFAULT_MAX_OUTPUT_BYTES) {
+    const totalBytes = Buffer.byteLength(text, 'utf8');
+    if (totalBytes <= maxBytes) {
+        return { text, truncated: false, totalBytes, returnedBytes: totalBytes };
+    }
+    const cut = sliceUtf8(text, maxBytes);
+    return { text: cut, truncated: true, totalBytes, returnedBytes: Buffer.byteLength(cut, 'utf8') };
+}
+/**
+ * Truncate HTML to a byte budget, backing up to the last tag boundary.
+ *
+ * Cutting mid-tag (`<div class="fo`) hands the caller markup that no parser will
+ * accept and that an LLM will happily hallucinate the rest of. Ending on a `>`
+ * keeps every returned tag complete — the document is still truncated, but every
+ * element in it is well-formed up to the cut.
+ */
+function capHtml(html, maxBytes = exports.DEFAULT_MAX_OUTPUT_BYTES) {
+    const capped = capText(html, maxBytes);
+    if (!capped.truncated)
+        return capped;
+    const lastClose = capped.text.lastIndexOf('>');
+    // Only back up when a boundary exists reasonably near the cut; a single
+    // enormous text node has no tag to align to and is better returned as-is.
+    if (lastClose > 0) {
+        const aligned = capped.text.slice(0, lastClose + 1);
+        return { ...capped, text: aligned, returnedBytes: Buffer.byteLength(aligned, 'utf8') };
+    }
+    return capped;
+}
+/** The metadata fields appended to a truncated read's envelope. */
+function truncationMeta(t) {
+    if (!t.truncated)
+        return {};
+    return {
+        truncated: true,
+        totalBytes: t.totalBytes,
+        returnedBytes: t.returnedBytes,
+        truncationNote: `output capped at ${t.returnedBytes} of ${t.totalBytes} bytes; ` +
+            'raise `maxBytes` for more, or narrow the read with `selector`',
+    };
+}
+//# sourceMappingURL=limits.js.map

package/dist/src/mcp/locate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * src/mcp/locate.ts — target an element by what it IS rather than by where it
+ * sits in the DOM.
+ *
+ * Today every action needs a CSS selector or a `ref` from a snapshot, so the
+ * cheapest way to click "Sign in" is to pull the whole accessibility tree first
+ * and read a ref out of it. That is a large read to perform one small action,
+ * and a hand-written selector is the alternative that breaks on the next
+ * redeploy.
+ *
+ * A locator closes that: `{ role: 'button', name: 'Sign in' }` resolves through
+ * one snapshot, server-side, and the caller never sees the tree. Matching runs
+ * strongest-first (exact, then case-insensitive, then contains) so an
+ * unambiguous name wins outright, and an ambiguous one fails loudly with the
+ * candidates rather than silently clicking the first row.
+ */
+import type { Executor, SnapshotNode, Target } from '../executor/types';
+export interface Locator {
+    role?: string;
+    name?: string;
+    /** Alias for `name`, for callers that think in visible text. */
+    text?: string;
+    /** Pick the nth match (0-based) when a locator is legitimately ambiguous. */
+    nth?: number;
+}
+/** Was a locator supplied at all? */
+export declare function hasLocator(l: Locator | undefined): boolean;
+export interface Resolution {
+    target: Target;
+    node: SnapshotNode;
+    /** How many nodes matched at the same (winning) strength. */
+    matches: number;
+}
+/**
+ * Resolve a locator to a `ref` by taking one snapshot of the target tab.
+ *
+ * Throws `McpToolError` when nothing matches or when the best tier is ambiguous
+ * — an ambiguous click is a wrong click, and the message lists what it found so
+ * the caller can narrow it (or pass `nth`).
+ */
+export declare function resolveLocator(ex: Executor, loc: Locator, opts?: {
+    tabId?: string;
+    frameId?: number;
+    allFrames?: boolean;
+}): Promise<Resolution>;

package/dist/src/mcp/locate.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * src/mcp/locate.ts — target an element by what it IS rather than by where it
+ * sits in the DOM.
+ *
+ * Today every action needs a CSS selector or a `ref` from a snapshot, so the
+ * cheapest way to click "Sign in" is to pull the whole accessibility tree first
+ * and read a ref out of it. That is a large read to perform one small action,
+ * and a hand-written selector is the alternative that breaks on the next
+ * redeploy.
+ *
+ * A locator closes that: `{ role: 'button', name: 'Sign in' }` resolves through
+ * one snapshot, server-side, and the caller never sees the tree. Matching runs
+ * strongest-first (exact, then case-insensitive, then contains) so an
+ * unambiguous name wins outright, and an ambiguous one fails loudly with the
+ * candidates rather than silently clicking the first row.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasLocator = hasLocator;
+exports.resolveLocator = resolveLocator;
+const validators_1 = require("./validators");
+/** Was a locator supplied at all? */
+function hasLocator(l) {
+    return !!l && (l.role !== undefined || l.name !== undefined || l.text !== undefined);
+}
+const norm = (s) => s.replace(/\s+/g, ' ').trim().toLowerCase();
+/**
+ * Rank a node against the locator. Higher is better; 0 means no match.
+ * The tiers are what make an exact name beat a substring of a longer label.
+ */
+function score(node, want) {
+    if (want.role && norm(node.role) !== norm(want.role))
+        return 0;
+    if (!want.name)
+        return 1; // role-only locator: any node of that role
+    const have = norm(node.name);
+    const need = norm(want.name);
+    if (!have)
+        return 0;
+    if (node.name.trim() === want.name.trim())
+        return 4; // exact, case-sensitive
+    if (have === need)
+        return 3; // exact, case-insensitive
+    if (have.startsWith(need))
+        return 2;
+    if (have.includes(need))
+        return 1;
+    return 0;
+}
+/**
+ * Resolve a locator to a `ref` by taking one snapshot of the target tab.
+ *
+ * Throws `McpToolError` when nothing matches or when the best tier is ambiguous
+ * — an ambiguous click is a wrong click, and the message lists what it found so
+ * the caller can narrow it (or pass `nth`).
+ */
+async function resolveLocator(ex, loc, opts = {}) {
+    const want = { role: loc.role, name: loc.name ?? loc.text };
+    const snap = await ex.snapshot({
+        tabId: opts.tabId,
+        interactiveOnly: false,
+        max: 400,
+        frameId: opts.frameId,
+        allFrames: opts.allFrames,
+    });
+    let best = 0;
+    let winners = [];
+    for (const node of snap.nodes) {
+        const s = score(node, want);
+        if (s === 0)
+            continue;
+        if (s > best) {
+            best = s;
+            winners = [node];
+        }
+        else if (s === best) {
+            winners.push(node);
+        }
+    }
+    const describe = (n) => `${n.role} "${n.name}"`;
+    if (winners.length === 0) {
+        const sample = snap.nodes
+            .filter((n) => !want.role || norm(n.role) === norm(want.role))
+            .slice(0, 8)
+            .map(describe);
+        throw new validators_1.McpToolError(`no element matches ${JSON.stringify(want)}. ` +
+            (sample.length
+                ? `Closest by role: ${sample.join(', ')}. `
+                : 'Nothing on the page has that role. ') +
+            'Take a `snapshot` to see what is there, or target by `selector` instead.');
+    }
+    if (loc.nth !== undefined) {
+        const picked = winners[loc.nth];
+        if (!picked) {
+            throw new validators_1.McpToolError(`nth=${loc.nth} is out of range: ${winners.length} element(s) match ${JSON.stringify(want)}`);
+        }
+        return { target: { ref: picked.ref }, node: picked, matches: winners.length };
+    }
+    if (winners.length > 1) {
+        throw new validators_1.McpToolError(`${winners.length} elements match ${JSON.stringify(want)}: ${winners.slice(0, 6).map(describe).join(', ')}. ` +
+            'Narrow the name, add a role, or pass `nth` to choose one.');
+    }
+    return { target: { ref: winners[0].ref }, node: winners[0], matches: 1 };
+}
+//# sourceMappingURL=locate.js.map

package/dist/src/mcp/log.d.ts

@@ -0,0 +1,17 @@
+/**
+ * src/mcp/log.ts — stderr diagnostics, gated by `--log-level`.
+ *
+ * Lives apart from `server.ts` so the tool layer can log without importing the
+ * server module that imports it back. CRITICAL: in stdio mode NOTHING may be
+ * written to stdout except the JSON-RPC stream, so every diagnostic here goes to
+ * stderr.
+ */
+import type { LogLevel } from '../config';
+/** Apply the CLI's `--log-level`. Call before anything else logs. */
+export declare function setLogLevel(level: LogLevel): void;
+/** The level currently in force (for tests, and for callers gating expensive tracing). */
+export declare function getLogLevel(): LogLevel;
+/** stderr only — never stdout in stdio mode. Suppressed at `--log-level silent`. */
+export declare function logErr(message: string): void;
+/** Verbose tracing: emitted only at `--log-level debug`. */
+export declare function logDebug(message: string): void;

package/dist/src/mcp/log.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * src/mcp/log.ts — stderr diagnostics, gated by `--log-level`.
+ *
+ * Lives apart from `server.ts` so the tool layer can log without importing the
+ * server module that imports it back. CRITICAL: in stdio mode NOTHING may be
+ * written to stdout except the JSON-RPC stream, so every diagnostic here goes to
+ * stderr.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setLogLevel = setLogLevel;
+exports.getLogLevel = getLogLevel;
+exports.logErr = logErr;
+exports.logDebug = logDebug;
+/**
+ * Active verbosity, set once from `--log-level` at startup.
+ *
+ * `silent` suppresses stderr entirely — an editor MCP config that asked for it
+ * was getting the noise anyway, because the parsed flag was never consumed.
+ * `debug` turns on the wire tracing that `logDebug` guards.
+ */
+let logLevel = 'info';
+/** Apply the CLI's `--log-level`. Call before anything else logs. */
+function setLogLevel(level) {
+    logLevel = level;
+}
+/** The level currently in force (for tests, and for callers gating expensive tracing). */
+function getLogLevel() {
+    return logLevel;
+}
+/** stderr only — never stdout in stdio mode. Suppressed at `--log-level silent`. */
+function logErr(message) {
+    if (logLevel === 'silent')
+        return;
+    process.stderr.write(`[chrome-mcp] ${message}\n`);
+}
+/** Verbose tracing: emitted only at `--log-level debug`. */
+function logDebug(message) {
+    if (logLevel !== 'debug')
+        return;
+    process.stderr.write(`[chrome-mcp] [debug] ${message}\n`);
+}
+//# sourceMappingURL=log.js.map

package/dist/src/mcp/redact.d.ts

@@ -0,0 +1,48 @@
+/**
+ * src/mcp/redact.ts — keep secrets that happen to be on the page out of the
+ * model's context.
+ *
+ * The premise of this tool is that it drives a browser you are already logged
+ * into. That is also the problem: `get_text` / `get_html` / `read_as_markdown` /
+ * `eval` return whatever is on the page, and on a logged-in page that routinely
+ * includes a session token rendered into a script tag, an API key on a settings
+ * screen, or the value sitting in a password field. The domain allowlist decides
+ * WHICH pages may be read; it has nothing to say about what comes back from one
+ * that is allowed.
+ *
+ * Two layers, deliberately different in strength:
+ *   - password-field values are ALWAYS suppressed. That one is unambiguous — no
+ *     caller ever wants the characters in a `<input type=password>` — so it
+ *     needs no flag and has no false positives.
+ *   - pattern redaction (JWTs, cloud keys, bearer tokens, private key blocks) is
+ *     opt-in via `--redact`, because a pattern can and will fire on something a
+ *     user legitimately asked to read.
+ */
+export interface RedactionConfig {
+    /** Pattern-based redaction (the opt-in layer). Password fields are handled regardless. */
+    enabled: boolean;
+    /** Extra caller-supplied patterns, already compiled. */
+    extra: RegExp[];
+}
+export declare const NO_REDACTION: RedactionConfig;
+/**
+ * Compile a user-supplied pattern. Invalid regexes are a configuration error
+ * worth failing loudly on — silently ignoring one would leave the user believing
+ * a secret is being scrubbed when it is not.
+ */
+export declare function compileRedactionPattern(source: string): RegExp;
+export interface Redacted<T> {
+    value: T;
+    /** How many substitutions were made, so a caller can see redaction happened. */
+    redactions: number;
+}
+/** Replace every match of the configured patterns with a labelled marker. */
+export declare function redactText(text: string, cfg: RedactionConfig): Redacted<string>;
+/**
+ * Strip the `value` of every password input, then apply pattern redaction.
+ *
+ * The value attribute is emptied rather than removed so the markup keeps its
+ * shape — a caller reasoning about the form still sees the field, just not
+ * what is in it.
+ */
+export declare function redactHtml(html: string, cfg: RedactionConfig): Redacted<string>;