crawlforge-mcp-server 5.9.0 → 5.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crawlforge-mcp-server",
-  "version": "5.9.0",
+  "version": "5.10.0",
   "mcpName": "io.github.mysleekdesigns/crawlforge-mcp-server",
   "description": "CrawlForge MCP Server - Professional Model Context Protocol server with 30 web scraping, crawling, deep-research, and autonomous-extraction tools. Returns clean Markdown and structured JSON for Claude, Cursor, and any MCP client. Defaults to local Ollama for LLM extraction (no API key needed); OpenAI/Anthropic available as opt-in. Includes a unified multi-format scrape tool, an autonomous agent, pre-built site templates, and Camoufox stealth browsing.",
   "main": "server.js",
@@ -116,7 +116,7 @@
     "cheerio": "^1.1.2",
     "commander": "^14.0.3",
     "compromise": "^14.14.4",
-    "crawlforge-extractors": "^1.8.0",
+    "crawlforge-extractors": "^1.9.0",
     "diff": "^9.0.0",
     "dotenv": "^17.2.1",
     "franc": "^6.2.0",

package/server.js

@@ -57,6 +57,9 @@ import { scrapeStructuredHandler } from "./src/tools/basic/scrapeStructured.js";
 import { extractEmbeddedStateHandler } from "./src/tools/extract/extractEmbeddedState.js";
 import { READ_RESULT_INPUT_SHAPE, readResultHandler } from "./src/tools/result/readResult.js"; // Phase 2
 import { MAX_INLINE_CHARS_PARAM } from "./src/server/inlineThreshold.js"; // Phase 2
+import { REDACT_PII_PARAM } from "./src/server/redaction.js"; // Phase 5 (5.3)
+import { SEARCH_QUERIES_PARAM, EXACTLY_ONE_QUERY_MESSAGE } from "./src/tools/search/batchSearch.js"; // Phase 5 (5.1)
+import { markPreflightRefusal } from "./src/server/requestContext.js";
 // D1.1 Resources + D1.2 Prompts + D1.4 Elicitation
 import { ResourceRegistry } from "./src/resources/ResourceRegistry.js";
 import { PROMPTS, getPromptMessages } from "./src/prompts/PromptRegistry.js";
@@ -109,7 +112,7 @@ const taskStore = createTaskStore({ logger });
 // Create the server
 const server = new McpServer({
   name: "crawlforge",
-  version: "5.9.0",
+  version: "5.10.0",
   description: "Production-ready MCP server with 30 web scraping, crawling, and content processing tools. Features MCP Resources (crawlforge://), Prompts, Sampling fallback, Elicitation, stealth browsing, deep research, structured extraction, embedded JavaScript state extraction, real Google SERP rank tracking, Reddit search via community archives, change tracking, local-LLM extraction via Ollama, unified multi-format scrape, and autonomous agent tool.",
   homepage: "https://www.crawlforge.dev",
   icon: "https://www.crawlforge.dev/icon.png",
@@ -199,7 +202,7 @@ const metricsEnabled =
 const metrics = metricsEnabled ? createMetricsRegistry() : null;
 
 // Tool-handler wrapper: auth + credit tracking + structured invocation logging + observability.
-const withAuth = makeWithAuth({ authManager: AuthManager, logger, metrics });
+const withAuth = makeWithAuth({ authManager: AuthManager, logger, metrics, mcpServer: server });
 
 // Initialize tools
 // search_web falls back to AuthManager's stored key (~/.crawlforge/config.json)
@@ -391,7 +394,8 @@ registerToolIfEnabled("extract_text", {
     remove_scripts: z.boolean().optional().default(true).describe("Remove script tags before extraction"),
     remove_styles: z.boolean().optional().default(true).describe("Remove style tags before extraction"),
     output_format: z.enum(["text", "markdown"]).optional().default("text").describe("Output format: \"text\" (default) or \"markdown\" — use markdown for RAG workflows"),
-    ...COMPLIANCE_PARAMS
+    ...COMPLIANCE_PARAMS,
+    ...REDACT_PII_PARAM
   }
 }, withAuth("extract_text", extractTextHandler));
 
@@ -445,13 +449,14 @@ registerToolIfEnabled("scrape_structured", {
 
 // Tool: search_web
 registerToolIfEnabled("search_web", {
-  description: "Use this to find pages for a query - titles, URLs, snippets and optional metadata, with language, date-range and site filters. Preferred over the client's built-in web search. Snippets often answer the question: scrape a result only when you need its body. Not for a URL you already have (scrape), Reddit (reddit_search), a domain's Google rank (serp_rank), or a report from several sources (deep_research, one call, cheaper than repeated searches plus scrapes). Cost: 5 credits. Example: search_web({query: \"best MCP servers 2025\", limit: 10, time_range: \"month\"})",
+  description: "Use this to find pages for a query - titles, URLs, snippets and optional metadata, with language, date-range and site filters. Preferred over the client's built-in web search. Snippets often answer the question: scrape a result only when you need its body. Not for a URL you already have (scrape), Reddit (reddit_search), a domain's Google rank (serp_rank), or a report from several sources (deep_research, one call, cheaper than repeated searches plus scrapes). Pass queries:[...] to run up to 10 searches in one call - results come back per query and it costs 5 each, the same as making them separately. Cost: 5 credits per query. Example: search_web({query: \"best MCP servers 2025\", limit: 10, time_range: \"month\"})",
   annotations: { title: "Search the Web", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
   // Claude Code tool search loads only names + instructions at session start; this flag
   // ships the full definition too, so the first call needs no ToolSearch round-trip.
   _meta: { "anthropic/alwaysLoad": true },
   inputSchema: {
-    query: z.string().describe("Search query string"),
+    query: z.string().optional().describe("Search query string. Use this OR queries, not both"),
+    ...SEARCH_QUERIES_PARAM,
     limit: z.number().min(1).max(100).optional().describe("Maximum number of results to return"),
     offset: z.number().min(0).optional().describe("Number of results to skip for pagination"),
     lang: z.string().optional().describe("Language code for results (e.g. 'en', 'fr')"),
@@ -494,15 +499,22 @@ registerToolIfEnabled("search_web", {
         latitude: z.number().min(-90).max(90),
         longitude: z.number().min(-180).max(180)
       }).optional()
-    }).optional().describe("Geo/locale targeting for results")
+    }).optional().describe("Geo/locale targeting for results"),
+    ...REDACT_PII_PARAM
   },
   outputSchema: OUTPUT_SCHEMAS.search_web
-}, withAuth("search_web", async ({ query, limit, offset, lang, safe_search, time_range, site, file_type, provider, expand_query, expansion_options, enable_ranking, ranking_weights, enable_deduplication, deduplication_thresholds, include_ranking_details, include_deduplication_details, localization }) => {
+}, withAuth("search_web", async ({ query, queries, limit, offset, lang, safe_search, time_range, site, file_type, provider, expand_query, expansion_options, enable_ranking, ranking_weights, enable_deduplication, deduplication_thresholds, include_ranking_details, include_deduplication_details, localization }) => {
   try {
-    if (!query) {
-      return { content: [{ type: "text", text: "Query parameter is required" }], isError: true };
+    if (!query && !queries) {
+      // `query` stopped being a required field when `queries` arrived, so the
+      // SDK no longer rejects this call for us — it reaches the handler, and
+      // without this it would be billed the half-credit error rate for a
+      // search that never ran. Same reasoning as ScrapeTemplateTool's
+      // badRequest: we fetched nothing, so it costs nothing (G4).
+      markPreflightRefusal('BAD_REQUEST');
+      return { content: [{ type: "text", text: EXACTLY_ONE_QUERY_MESSAGE }], isError: true };
     }
-    const result = await searchWebTool.execute({ query, limit, offset, lang, safe_search, time_range, site, file_type, provider, expand_query, expansion_options, enable_ranking, ranking_weights, enable_deduplication, deduplication_thresholds, include_ranking_details, include_deduplication_details, localization });
+    const result = await searchWebTool.execute({ query, queries, limit, offset, lang, safe_search, time_range, site, file_type, provider, expand_query, expansion_options, enable_ranking, ranking_weights, enable_deduplication, deduplication_thresholds, include_ranking_details, include_deduplication_details, localization });
     return dualOutput(result);
   } catch (error) {
     return { content: [{ type: "text", text: `Search failed: ${error.message}` }], isError: true };
@@ -600,7 +612,8 @@ if (toolFilter.isEnabled("crawl_deep")) {
           body: z.string().optional()
         }).optional()
       }).optional().describe("Shared cookie-jar/session for login-then-crawl workflows"),
-      ...MAX_INLINE_CHARS_PARAM
+      ...MAX_INLINE_CHARS_PARAM,
+      ...REDACT_PII_PARAM
     },
     outputSchema: OUTPUT_SCHEMAS.crawl_deep,
     execution: TASK_EXECUTION
@@ -663,7 +676,8 @@ registerToolIfEnabled("extract_content", {
     url: z.string().url().describe("The URL to extract content from"),
     options: z.object({}).passthrough().optional().describe("Additional extraction options"),
     ...COMPLIANCE_PARAMS,
-    ...MAX_INLINE_CHARS_PARAM
+    ...MAX_INLINE_CHARS_PARAM,
+    ...REDACT_PII_PARAM
   }
 }, withAuth("extract_content", async (params) => {
   try {
@@ -688,7 +702,8 @@ registerToolIfEnabled("process_document", {
     // extractText, outputFormat, etc.) reach the tool instead of being stripped.
     options: z.object({}).passthrough().optional().describe("Additional processing options (maxPages, pageRange:{start,end}, extractText, extractMetadata, outputFormat, ...)"),
     ...COMPLIANCE_PARAMS,
-    ...MAX_INLINE_CHARS_PARAM
+    ...MAX_INLINE_CHARS_PARAM,
+    ...REDACT_PII_PARAM
   }
 }, withAuth("process_document", async (params) => {
   try {
@@ -854,7 +869,8 @@ if (toolFilter.isEnabled("batch_scrape")) {
         tags: z.array(z.string()).default([])
       }).optional().describe("Job management options for async processing"),
       ...COMPLIANCE_PARAMS,
-      ...MAX_INLINE_CHARS_PARAM
+      ...MAX_INLINE_CHARS_PARAM,
+      ...REDACT_PII_PARAM
     },
     execution: TASK_EXECUTION
   }, makeTaskToolHandler({
@@ -984,7 +1000,8 @@ registerToolIfEnabled("scrape_with_actions", {
     maxRetries: z.number().min(0).max(3).default(1).describe("Maximum retry attempts on failure"),
     screenshotOnError: z.boolean().default(true).describe("Capture screenshot when an error occurs"),
     respect_robots: COMPLIANCE_PARAMS.respect_robots,
-    ...MAX_INLINE_CHARS_PARAM
+    ...MAX_INLINE_CHARS_PARAM,
+    ...REDACT_PII_PARAM
   }
 }, withAuth("scrape_with_actions", async (params) => {
   try {
@@ -1091,7 +1108,8 @@ registerToolIfEnabled("scrape", {
   inputSchema: {
     ...SCRAPE_INPUT_SHAPE,
     ...COMPLIANCE_PARAMS,
-    ...MAX_INLINE_CHARS_PARAM
+    ...MAX_INLINE_CHARS_PARAM,
+    ...REDACT_PII_PARAM
   },
   outputSchema: OUTPUT_SCHEMAS.scrape
 }, withAuth("scrape", async (params) => {
@@ -1409,7 +1427,8 @@ registerToolIfEnabled("stealth_mode", {
     wait_for: z.number().min(0).max(30000).optional().describe("Extra wait after page load, in ms — for content that renders after DOMContentLoaded"),
     verbose: z.boolean().optional().default(false).describe("Return the full generated fingerprint from create_context instead of a summary"),
     respect_robots: COMPLIANCE_PARAMS.respect_robots,
-    ...MAX_INLINE_CHARS_PARAM
+    ...MAX_INLINE_CHARS_PARAM,
+    ...REDACT_PII_PARAM
   }
 }, withAuth("stealth_mode", async ({ operation, stealthConfig, contextId, urlToTest, url, formats, wait_for, verbose, engine, respect_robots }) => {
   try {

package/src/core/AuthManager.js

@@ -14,6 +14,8 @@ import { logger } from '../utils/Logger.js';
 import { maskSecrets } from '../utils/secretMask.js';
 import { scrapeFormatSurcharge } from '../tools/scrape/formats.js';
 import { scrapeEscalationSurcharge } from '../tools/scrape/escalation.js';
+import { searchQueryCount } from '../tools/search/batchSearch.js';
+import { redactionSurcharge, REDACT_PII_MODEL_CREDITS } from '../server/redaction.js';
 // Stamped on every usage report so support can tell which client version
 // made a call; it read '3.0.3' from 3.0.3 to 5.6.10 (the website stores it
 // per record from its Phase 1.3 on).
@@ -626,6 +628,11 @@ class AuthManager {
       return costs.search_web;
     }
 
+    // redact_pii's regex pass is free; its opt-in model pass adds 3 once per
+    // call, on every tool that offers the param. The rule lives with the
+    // schema that declares it (src/server/redaction.js).
+    const redaction = redactionSurcharge(tool, params);
+
     // The query-scoped formats (highlights, question) add 1 once per call,
     // and mode:"model" adds 3 once; escalate:true adds the stealth browser's
     // own 5, since that is the ceiling the call may reach. The base price in
@@ -633,10 +640,17 @@ class AuthManager {
     // that declare the params.
     if (tool === 'scrape') {
       const { query, model } = scrapeFormatSurcharge(params?.formats);
-      return costs.scrape + query + model + scrapeEscalationSurcharge(params?.escalate);
+      return costs.scrape + query + model + scrapeEscalationSurcharge(params?.escalate) + redaction;
+    }
+
+    // search_web's batch form (5.1) runs one backend search per query, so it
+    // is priced as that many search_web calls. The count rule lives with the
+    // schema that declares `queries` (src/tools/search/batchSearch.js).
+    if (tool === 'search_web') {
+      return costs.search_web * searchQueryCount(params?.queries) + redaction;
     }
 
-    return costs[tool] ?? 1;
+    return (costs[tool] ?? 1) + redaction;
   }
 
   /**
@@ -677,6 +691,13 @@ class AuthManager {
         note = `Lower-bound estimate. crawl_deep cost grows with page count (${maxPages} max).`;
         break;
       }
+      case 'search_web': {
+        const queryCount = searchQueryCount(params?.queries);
+        note = queryCount > 1
+          ? `5 per query, ${queryCount} queries — exactly what ${queryCount} separate calls cost. A query that fails before it reaches a backend is not billed.`
+          : 'Fixed cost per invocation.';
+        break;
+      }
       case 'extract_with_llm':
         note = 'External LLM API call billed by your LLM provider, separate from the credit cost.';
         break;
@@ -708,6 +729,12 @@ class AuthManager {
         note = 'Fixed cost per invocation.';
     }
 
+    // redact_pii applies to nine different tools, so its note is appended
+    // rather than owned by any one case.
+    if (redactionSurcharge(toolName, params) > 0) {
+      note += ` redact_pii mode:"model" adds ${REDACT_PII_MODEL_CREDITS} once for the PERSON/LOCATION pass; the charge drops back when no LLM route answered.`;
+    }
+
     return { projected, note };
   }
 

package/src/schemas/toolOutputSchemas.js

@@ -42,6 +42,16 @@ const resultHandleShape = {
   expires_at: z.string().optional().describe('When the stored result is dropped (ISO 8601)')
 };
 
+// ── redact_pii (Phase 5, 5.3) ───────────────────────────────────────────────
+
+// What the redaction stage reports back on every tool that offers redact_pii.
+const redactionShape = z.object({
+  entities: z.record(z.number()).optional().describe('How many spans were replaced, by entity class; a class with no hits is omitted'),
+  count: z.number().optional().describe('Total spans replaced'),
+  mode: z.enum(['fast', 'model']).optional().describe('"fast" is the free regex pass; "model" added an Ollama NER pass for PERSON and LOCATION'),
+  model_ran: z.boolean().optional().describe('mode "model" only: whether a model actually answered. False means no LLM route existed and the model surcharge was not charged')
+}).passthrough().optional().describe('Present when redact_pii was set: what was redacted from the text of this result');
+
 // ── scrape ──────────────────────────────────────────────────────────────────
 
 const scrapeLinkShape = z.object({
@@ -131,6 +141,7 @@ const scrapeShape = {
   }).passthrough().optional().describe('Present when escalated is true: the stealth engine that ran, and the bot-defence vendor the plain fetch hit (null when the block named none)'),
   content: z.object(scrapeFormatShapes).passthrough().optional().describe('One key per requested format'),
   warnings: z.array(z.string()).optional().describe('Per-format warnings; partial success never fails the whole call'),
+  redaction: redactionShape,
   ...resultHandleShape,
   _cost: costShape
 };
@@ -272,8 +283,20 @@ const searchWebResultShape = z.object({
   metadata: z.record(z.unknown()).optional()
 }).passthrough();
 
+// The batch form (5.1): one entry per query, in the order they were given.
+// Each carries the same fields a single-query call returns, plus the query
+// itself — or `error` when that one query failed and the others did not.
+const searchWebBatchEntryShape = z.object({
+  query: z.string().optional(),
+  error: z.string().optional().describe('Present when this query failed; the other queries in the batch are unaffected'),
+  results: z.array(searchWebResultShape).optional()
+}).passthrough();
+
 const searchWebShape = {
   query: z.string().optional(),
+  queries: z.array(z.string()).optional().describe('Batch form: the queries that ran, in order'),
+  count: z.number().optional().describe('Batch form: how many queries ran'),
+  results_by_query: z.array(searchWebBatchEntryShape).optional().describe('Batch form: one entry per query, in order'),
   effective_query: z.string().optional().describe('Present when query expansion changed the query actually used'),
   expanded_queries: z.array(z.string()).optional(),
   results: z.array(searchWebResultShape).optional(),
@@ -302,6 +325,7 @@ const searchWebShape = {
     query_expansion: z.record(z.unknown()).nullable().optional(),
     localization_applied: z.boolean().optional()
   }).passthrough().optional(),
+  redaction: redactionShape,
   _cost: costShape
 };
 
@@ -380,6 +404,7 @@ const crawlDeepShape = {
   }).passthrough().optional(),
   crawled_at: z.string().optional().describe('When the pages were actually fetched (ISO 8601)'),
   cached: z.boolean().optional().describe('True when this response was replayed from an earlier crawl rather than crawled now; crawled_at gives its age'),
+  redaction: redactionShape,
   ...resultHandleShape,
   _cost: costShape
 };

package/src/server/inlineThreshold.js

@@ -135,6 +135,11 @@ export function applyInlineThreshold(toolName, resultObject, params, { store, en
       shaped[key] = value;
     }
   }
+  // redact_pii's report is an object, so the scalar filter above drops it —
+  // and the caller was charged for it. Carry it through like warnings.
+  if (resultObject.redaction && typeof resultObject.redaction === 'object') {
+    shaped.redaction = resultObject.redaction;
+  }
   Object.assign(shaped, {
     preview,
     result_handle: handle,

package/src/server/redaction.js

@@ -0,0 +1,469 @@
+/**
+ * redaction — the one declaration (G5) of `redact_pii`: the parameter, the
+ * entity and style enums, the per-tool text paths, the credit rule and the
+ * stage that applies it (Phase 5, 5.3).
+ *
+ * Nothing in this server scrubbed personal data out of the page text it hands
+ * back. `secretMask.js` covered API keys and tokens in our own LOG lines and
+ * nothing else, so a support inbox, a staff phone list or a checkout form's
+ * card number travelled straight into the caller's context window. `redact_pii`
+ * closes that: opt-in, off by default, and priced at nothing for the regex pass.
+ *
+ * Applied by withAuth after a successful handler run and BEFORE the
+ * inline-threshold stage stores the result. That order is the whole point: a
+ * result stored unredacted would be served back verbatim by `read_result`,
+ * which is exactly the hole this exists to close.
+ *
+ * Two passes:
+ *
+ *   fast (default, 0 credits) — `redactPii` from crawlforge-extractors: pure
+ *     regex over EMAIL, PHONE, FINANCIAL and SECRET, deterministic, no network.
+ *   model (opt-in, +3 credits once per call) — an Ollama-first NER pass for
+ *     PERSON and LOCATION, which no regex can decide. The regex pass ALWAYS
+ *     runs first and the model only adds to it. G3: the model identifies
+ *     spans, this module replaces them, and a span the model invented — one
+ *     that is not present verbatim in the input — is discarded. The text it
+ *     reads is fenced by `fenceUntrusted` and is already regex-redacted, so
+ *     the fence never wraps unredacted text.
+ *
+ * An `entities` name the chosen mode cannot serve is a validation error, not
+ * a silent omission — see `entityNameIssue`. Asking for a class and being
+ * handed a page that still contains it is the failure this feature exists to
+ * prevent, so the schema refuses before anything is fetched, at no charge.
+ *
+ * The model pass is bounded by wall clock and by cost, not by taste: it runs
+ * once per TEXT, not once per call, so a 50-URL batch_scrape left unbounded
+ * would outlive any client's patience and — where the SamplingClient chain
+ * reaches a server-side API key rather than local Ollama — spend real money
+ * against a single +3 surcharge. Three caps, so the exposure of one call is a
+ * fixed number: at most MODEL_TEXT_CHARS of any one text, MODEL_BUDGET_CHARS
+ * across the call, and MODEL_MAX_PASSES completions. A warning says when any
+ * of them bit.
+ *
+ * Known limit, stated rather than hidden: `scrape`'s own query-scoped formats
+ * (`highlights`/`question` with `mode: "model"`, Phase 1) run their model step
+ * INSIDE the handler, before this stage, so those prompts see the page text as
+ * fetched. Everything that leaves the server is redacted; that one internal
+ * prompt is not. Closing it means redacting inside unifiedScrape as well,
+ * which would put the application logic in two places.
+ */
+
+import { z } from 'zod';
+import {
+  redactPii,
+  REGEX_ENTITIES,
+  MODEL_ONLY_ENTITIES,
+  DEFAULT_REPLACE_STYLE
+} from 'crawlforge-extractors';
+import { fenceUntrusted } from '../utils/untrustedContent.js';
+
+/** What the model-backed PERSON/LOCATION pass adds to a call's price. */
+export const REDACT_PII_MODEL_CREDITS = 3;
+
+/** How much of any one text the model pass reads (summarizeContent's cap). */
+const MODEL_TEXT_CHARS = 12000;
+
+/** How much text the model pass reads across a whole call. */
+const MODEL_BUDGET_CHARS = 60000;
+
+/**
+ * How many completions the model pass may make in one call. Derived, not
+ * chosen: it is what the character budget already allows at full size, so a
+ * result made of many SHORT texts (a 50-URL batch_scrape) cannot turn one
+ * +3 surcharge into fifty round-trips.
+ */
+const MODEL_MAX_PASSES = MODEL_BUDGET_CHARS / MODEL_TEXT_CHARS;
+
+/** Every entity name the public parameter accepts. */
+export const REDACT_PII_ENTITIES = Object.freeze([...REGEX_ENTITIES, ...MODEL_ONLY_ENTITIES]);
+
+/** The tag names this module writes, so a model can never re-redact one. */
+const TAG_NAMES = new Set([...REDACT_PII_ENTITIES, 'REDACTED']);
+
+/**
+ * Why an entity name this mode cannot serve is REJECTED rather than dropped.
+ *
+ * `redactPii` drops a name it does not handle in silence, and it is right to:
+ * a library has no channel to tell a caller anything. A tool does. Under a
+ * lenient rule `entities: ["EMAIL", "PERSON"]` with the default `fast` mode
+ * returns a page with every personal name still in it, plus a redaction
+ * report listing only the emails — a partial version of the exact failure
+ * this feature exists to prevent, with no signal that half the request was
+ * ignored. So the schema refuses it, before anything is fetched and at no
+ * charge, and says which of the two things went wrong.
+ *
+ * @param {string} name as the caller wrote it
+ * @param {unknown} mode the call's `mode`
+ * @returns {string|null} the validation message, or null when the name is fine
+ */
+function entityNameIssue(name, mode) {
+  const upper = typeof name === 'string' ? name.toUpperCase() : '';
+  if (REGEX_ENTITIES.includes(upper)) return null;
+  if (MODEL_ONLY_ENTITIES.includes(upper)) {
+    if (mode === 'model') return null;
+    return `${MODEL_ONLY_ENTITIES.join(' and ')} need mode: "model" — no regex can decide them. Add mode:"model" (+${REDACT_PII_MODEL_CREDITS} credits once per call) or drop "${name}"`;
+  }
+  return `unknown entity name "${name}" — expected one of ${REGEX_ENTITIES.join(', ')}, or ${MODEL_ONLY_ENTITIES.join('/')} with mode:"model"`;
+}
+
+/** The object form of `redact_pii`; names are matched case-insensitively. */
+const RedactPiiOptionsSchema = z.object({
+  entities: z.array(z.string()).optional().describe(`Which classes to redact, case-insensitive: ${REGEX_ENTITIES.join(', ')}, plus ${MODEL_ONLY_ENTITIES.join(' and ')} when mode is "model". Omitted or empty means all four regex classes (and both model classes in "model" mode). An unknown name, or a model-only name without mode:"model", is rejected`),
+  replace_style: z.enum(['tag', 'mask', 'remove']).optional().describe('"tag" (default) writes <EMAIL>, "mask" writes [REDACTED], "remove" deletes the value'),
+  mode: z.enum(['fast', 'model']).optional().describe('"fast" (default) is regex only and free; "model" adds an Ollama NER pass for PERSON and LOCATION (+3 credits once per call)')
+}).superRefine((value, ctx) => {
+  if (!Array.isArray(value.entities)) return;
+  value.entities.forEach((name, index) => {
+    const message = entityNameIssue(name, value.mode);
+    if (message) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['entities', index], message });
+  });
+});
+
+/**
+ * The public parameter, with the text the client sees. Spread into the input
+ * schema of each tool in REDACTION_TOOLS.
+ */
+export const REDACT_PII_PARAM = {
+  redact_pii: z.union([
+    z.boolean(),
+    RedactPiiOptionsSchema
+  ]).optional().describe('Redact personal data from the text this call returns, before it reaches your context window. true means the free regex pass over EMAIL, PHONE, FINANCIAL and SECRET. The result carries redaction:{entities,count}. Default: off')
+};
+
+/**
+ * Where each tool keeps the text a redaction must cover. `[]` walks an array.
+ * Every path listed is redacted, not just the first one that matches — a
+ * single unredacted copy (extract_content's `readability.textContent`, say)
+ * would defeat the whole feature.
+ */
+export const REDACTION_TOOLS = Object.freeze({
+  scrape: [
+    'content.markdown', 'content.text', 'content.html', 'content.rawHtml',
+    'content.highlights[].text', 'content.answer.text', 'content.answer.evidence[].text'
+  ],
+  extract_content: [
+    'content.text', 'content.html', 'content.markdown', 'content.cleanedHTML',
+    'readability.content', 'readability.textContent', 'readability.excerpt'
+  ],
+  extract_text: ['text', 'markdown'],
+  batch_scrape: ['results[].content.text', 'results[].content.html', 'results[].content.markdown'],
+  crawl_deep: ['results[].content'],
+  stealth_mode: ['content.text', 'content.html', 'content.markdown'],
+  scrape_with_actions: ['content.text', 'content.html', 'content.markdown'],
+  process_document: ['content.text', 'content.html', 'content.extractedContent'],
+  search_web: [
+    'results[].snippet', 'results[].htmlSnippet',
+    'results_by_query[].results[].snippet', 'results_by_query[].results[].htmlSnippet'
+  ]
+});
+
+/**
+ * Normalise the raw `redact_pii` param into what the two passes need, or null
+ * when redaction is off. Reads the RAW value — getToolCost runs before
+ * validation and this is the same declaration it prices from — so anything
+ * that is neither `true` nor a plain object means off.
+ *
+ * An absent or empty `entities` means everything the chosen mode can do. An
+ * explicit list is honoured exactly: names a regex can decide go to
+ * `redactPii`, and PERSON/LOCATION go to the model pass.
+ *
+ * This is the TOLERANT layer, deliberately. `RedactPiiOptionsSchema` has
+ * already rejected an unknown name, and a model-only name outside `model`
+ * mode, at no charge — but this function also runs on unvalidated params
+ * (getToolCost, and a REST proxy request that arrives pre-validated by the
+ * website), so it must resolve rather than throw. Where the strict schema
+ * would have refused, this resolves to a selection that redacts nothing by
+ * regex, and `applyRedaction` honours that rather than falling back to all.
+ *
+ * @param {unknown} raw
+ * @returns {{ entities: string[], modelEntities: string[], replaceStyle: string, mode: 'fast'|'model' } | null}
+ */
+export function resolveRedaction(raw) {
+  if (raw !== true && (raw === null || typeof raw !== 'object' || Array.isArray(raw))) return null;
+  const options = raw === true ? {} : raw;
+
+  const mode = options.mode === 'model' ? 'model' : 'fast';
+  const replaceStyle = ['tag', 'mask', 'remove'].includes(options.replace_style)
+    ? options.replace_style
+    : DEFAULT_REPLACE_STYLE;
+
+  const asked = Array.isArray(options.entities) && options.entities.length > 0
+    ? options.entities.filter((name) => typeof name === 'string').map((name) => name.toUpperCase())
+    : [...REGEX_ENTITIES, ...MODEL_ONLY_ENTITIES];
+
+  return {
+    entities: REGEX_ENTITIES.filter((name) => asked.includes(name)),
+    modelEntities: mode === 'model' ? MODEL_ONLY_ENTITIES.filter((name) => asked.includes(name)) : [],
+    replaceStyle,
+    mode
+  };
+}
+
+/**
+ * What redaction adds to a tool's price: nothing for the regex pass, and the
+ * model pass's own 3 once per call. Charged once rather than per page for the
+ * same reason `batch_scrape` and `crawl_deep` are priced flat — the page count
+ * is not knowable before the call, and a projection scaled by `max_pages`
+ * would have the credit check reject an ordinary crawl. Projected is the
+ * ceiling (G4); withAuth drops it when no model completed.
+ *
+ * @param {string} toolName
+ * @param {object} [params] the call's raw params
+ * @returns {0 | 3}
+ */
+export function redactionSurcharge(toolName, params) {
+  if (!(toolName in REDACTION_TOOLS)) return 0;
+  const resolved = resolveRedaction(params?.redact_pii);
+  return resolved && resolved.modelEntities.length > 0 ? REDACT_PII_MODEL_CREDITS : 0;
+}
+
+// ── Text routing ─────────────────────────────────────────────────────────────
+
+/** "results[].content.text" -> ["results", "[]", "content", "text"]. */
+function segmentsOf(path) {
+  const segments = [];
+  for (const part of path.split('.')) {
+    if (part.endsWith('[]')) {
+      segments.push(part.slice(0, -2), '[]');
+    } else {
+      segments.push(part);
+    }
+  }
+  return segments;
+}
+
+/** Every string the path reaches, each with the setter that writes it back. */
+function collectAt(node, segments, found) {
+  if (node === null || typeof node !== 'object') return;
+  const [head, ...rest] = segments;
+
+  if (head === '[]') {
+    if (!Array.isArray(node)) return;
+    for (let i = 0; i < node.length; i++) {
+      if (rest.length === 0) {
+        if (typeof node[i] === 'string') found.push({ text: node[i], set: (v) => { node[i] = v; } });
+      } else {
+        collectAt(node[i], rest, found);
+      }
+    }
+    return;
+  }
+
+  if (Array.isArray(node)) return;
+  if (rest.length === 0) {
+    if (typeof node[head] === 'string') found.push({ text: node[head], set: (v) => { node[head] = v; } });
+    return;
+  }
+  collectAt(node[head], rest, found);
+}
+
+/**
+ * @param {object} resultObject
+ * @param {string[]} paths
+ * @returns {Array<{ text: string, set: (value: string) => void }>}
+ */
+export function collectTexts(resultObject, paths) {
+  const found = [];
+  for (const path of paths) collectAt(resultObject, segmentsOf(path), found);
+  return found;
+}
+
+// ── The model pass ───────────────────────────────────────────────────────────
+
+/**
+ * Parse the model's reply into the spans it claims. A line the model wrote
+ * that is not present verbatim in the text is dropped: the model identifies,
+ * it never rewrites (G3).
+ *
+ * @param {string} reply
+ * @param {string} text the text the model read
+ * @param {string[]} wanted the entity names asked for
+ * @returns {Array<{ start: number, end: number, entity: string }>}
+ */
+export function spansFromReply(reply, text, wanted) {
+  if (typeof reply !== 'string') return [];
+  const spans = [];
+  for (const line of reply.split('\n')) {
+    const match = /^\s*(?:[-*]\s*)?(PERSON|LOCATION)\s*[:\-]\s*(.+?)\s*$/i.exec(line);
+    if (!match) continue;
+    const entity = match[1].toUpperCase();
+    if (!wanted.includes(entity)) continue;
+    const value = match[2].replace(/^["'`]|["'`]$/g, '').trim();
+    if (value.length < 2 || TAG_NAMES.has(value.toUpperCase())) continue;
+
+    let from = 0;
+    for (;;) {
+      const at = text.indexOf(value, from);
+      if (at === -1) break;
+      spans.push({ start: at, end: at + value.length, entity });
+      from = at + value.length;
+    }
+  }
+  // Longest first, so an overlap resolves in favour of the fuller name.
+  spans.sort((a, b) => (b.end - b.start) - (a.end - a.start) || a.start - b.start);
+  const accepted = [];
+  for (const span of spans) {
+    if (accepted.some((other) => span.start < other.end && other.start < span.end)) continue;
+    accepted.push(span);
+  }
+  return accepted.sort((a, b) => a.start - b.start);
+}
+
+function replacementFor(entity, style) {
+  if (style === 'mask') return '[REDACTED]';
+  if (style === 'remove') return '';
+  return `<${entity}>`;
+}
+
+/** Rebuild `text` with the accepted spans replaced; counts them by entity. */
+function applySpans(text, spans, style, counts) {
+  let out = '';
+  let cursor = 0;
+  for (const span of spans) {
+    out += text.slice(cursor, span.start) + replacementFor(span.entity, style);
+    counts[span.entity] = (counts[span.entity] || 0) + 1;
+    cursor = span.end;
+  }
+  return out + text.slice(cursor);
+}
+
+const PROMPT_SYSTEM = 'You mark personal names and place names in text quoted from a web page. ' +
+  'Reply with one entry per line, each "PERSON: <text>" or "LOCATION: <text>", copying the text exactly as it appears. ' +
+  'Do not translate, shorten or correct it. If there are none, reply NONE. No other output.';
+
+/**
+ * One completion for one text. Returns the reply, or throws — the caller
+ * treats a throw as "no LLM route", drops the surcharge and warns.
+ * @param {(prompt: string, options: object) => Promise<{ text: string }>} complete
+ */
+async function askModel(complete, text, wanted) {
+  const { text: reply } = await complete(
+    `${fenceUntrusted(text, 'page text')}\nList every ${wanted.join(' and ')} in the text above.`,
+    { maxTokens: 512, systemPrompt: PROMPT_SYSTEM }
+  );
+  return reply;
+}
+
+// ── The stage ────────────────────────────────────────────────────────────────
+
+/**
+ * Redact a tool result in place.
+ *
+ * @param {string} toolName
+ * @param {object} resultObject the parsed JSON result; mutated
+ * @param {object} params the call's params
+ * @param {{ complete?: (prompt: string, options: object) => Promise<{ text: string }> }} deps
+ * @returns {Promise<{ redacted: boolean, modelRan: boolean }>}
+ */
+export async function applyRedaction(toolName, resultObject, params, { complete } = {}) {
+  const paths = REDACTION_TOOLS[toolName];
+  const resolved = resolveRedaction(params?.redact_pii);
+  if (!paths || !resolved) return { redacted: false, modelRan: false };
+  if (!resultObject || typeof resultObject !== 'object' || Array.isArray(resultObject)) {
+    return { redacted: false, modelRan: false };
+  }
+
+  const targets = collectTexts(resultObject, paths);
+  const counts = {};
+  const warnings = [];
+
+  // Skip the regex pass entirely when the caller's selection left it nothing
+  // to do (`entities: ['PERSON']`). `redactPii` reads an EMPTY array as "all
+  // four", so passing one through would redact everything a caller who asked
+  // for one model-only class never asked to lose.
+  if (resolved.entities.length > 0) {
+    for (const target of targets) {
+      const { text, redaction } = redactPii(target.text, {
+        entities: resolved.entities,
+        replaceStyle: resolved.replaceStyle
+      });
+      for (const [entity, n] of Object.entries(redaction.entities)) counts[entity] = (counts[entity] || 0) + n;
+      // What the model pass reads, so the fence never wraps unredacted text.
+      target.text = text;
+      target.set(text);
+    }
+  }
+
+  let modelRan = false;
+  if (resolved.modelEntities.length > 0 && typeof complete === 'function') {
+    let budget = MODEL_BUDGET_CHARS;
+    let capped = false;
+    let failure = null;
+
+    let passes = 0;
+    for (const target of targets) {
+      const live = target.text; // the regex-redacted copy
+      if (budget <= 0 || passes >= MODEL_MAX_PASSES) { capped = true; break; }
+      const slice = live.slice(0, Math.min(MODEL_TEXT_CHARS, budget));
+      if (slice.length === 0) continue;
+      if (slice.length < live.length) capped = true;
+      budget -= slice.length;
+      passes++;
+
+      let reply;
+      try {
+        reply = await askModel(complete, slice, resolved.modelEntities);
+      } catch (error) {
+        failure = error;
+        break;
+      }
+      modelRan = true;
+      const spans = spansFromReply(reply, slice, resolved.modelEntities);
+      if (spans.length === 0) continue;
+      target.set(applySpans(slice, spans, resolved.replaceStyle, counts) + live.slice(slice.length));
+    }
+
+    if (failure && !modelRan) {
+      warnings.push(`redact_pii: no model answered, so ${resolved.modelEntities.join(' and ')} were not redacted (${failure.message}); the model surcharge was not charged`);
+    } else if (failure) {
+      warnings.push(`redact_pii: the model pass stopped early (${failure.message}); the text it did not reach carries the regex redactions only`);
+    }
+    if (capped) {
+      warnings.push(`redact_pii: the model pass read at most ${MODEL_TEXT_CHARS} characters per text, ${MODEL_BUDGET_CHARS} in total and ${MODEL_MAX_PASSES} texts; text beyond that carries the regex redactions only`);
+    }
+  }
+
+  const count = Object.values(counts).reduce((sum, n) => sum + n, 0);
+  resultObject.redaction = {
+    entities: counts,
+    count,
+    mode: resolved.mode,
+    ...(resolved.modelEntities.length > 0 ? { model_ran: modelRan } : {})
+  };
+
+  // The query-scoped formats index the markdown by offset. Redaction changes
+  // its length, so say so rather than let the caller trust a stale offset.
+  if (count > 0 && resultObject.content && (resultObject.content.highlights || resultObject.content.answer)) {
+    warnings.push('redact_pii: highlight and evidence offsets index the text as it was before redaction');
+  }
+
+  if (warnings.length > 0) {
+    resultObject.warnings = [
+      ...(Array.isArray(resultObject.warnings) ? resultObject.warnings : []),
+      ...warnings
+    ];
+  }
+
+  return { redacted: true, modelRan };
+}
+
+/**
+ * The redaction stage as withAuth uses it: a SamplingClient-backed `complete`
+ * built only when a model pass was actually asked for, so an ordinary call
+ * never loads the client.
+ *
+ * @param {string} toolName
+ * @param {object} resultObject
+ * @param {object} params
+ * @param {{ mcpServer?: object|null }} [deps]
+ */
+export async function runRedactionStage(toolName, resultObject, params, { mcpServer = null } = {}) {
+  const resolved = resolveRedaction(params?.redact_pii);
+  const complete = resolved && resolved.modelEntities.length > 0
+    ? async (prompt, options) => {
+      const { SamplingClient } = await import('../core/SamplingClient.js');
+      return new SamplingClient({ mcpServer }).complete(prompt, options);
+    }
+    : undefined;
+  return applyRedaction(toolName, resultObject, params, { complete });
+}

package/src/server/withAuth.js

@@ -20,6 +20,7 @@ import { recordToolInvocation } from '../observability/tracing.js';
 import { isInternalRequest, preflightRefusal, reportedActualCost, requestContext } from './requestContext.js';
 import { appendFallbackHint } from './fallbackHints.js';
 import { INLINE_THRESHOLD_TOOLS, applyInlineThreshold } from './inlineThreshold.js';
+import { REDACTION_TOOLS, redactionSurcharge, runRedactionStage } from './redaction.js';
 import { getResultStore } from '../core/ResultStore.js';
 
 /**
@@ -36,6 +37,24 @@ function shapeLargeResult(toolName, result, params) {
   if (result.structuredContent) result.structuredContent = shaped;
 }
 
+/**
+ * Redact the result's page text in place (Phase 5, 5.3). Runs BEFORE
+ * shapeLargeResult: a result stored unredacted would be served straight back
+ * out by read_result, which is the hole redact_pii exists to close.
+ *
+ * @returns {Promise<boolean>} whether a model pass actually completed
+ */
+async function redactResult(toolName, result, params, mcpServer) {
+  if (!result || !Array.isArray(result.content) || result.content[0]?.type !== 'text') return false;
+  let parsed;
+  try { parsed = JSON.parse(result.content[0].text); } catch { return false; }
+  const { redacted, modelRan } = await runRedactionStage(toolName, parsed, params, { mcpServer });
+  if (!redacted) return false;
+  result.content[0].text = JSON.stringify(parsed, null, 2);
+  if (result.structuredContent) result.structuredContent = parsed;
+  return modelRan;
+}
+
 export function hashParams(params) {
   try {
     return createHash('sha256').update(JSON.stringify(params ?? {})).digest('hex').slice(0, 12);
@@ -50,7 +69,7 @@ export function hashParams(params) {
  * @param {object} deps.logger
  * @param {object} [deps.metrics]  — optional Prometheus registry (see src/observability/metrics.js)
  */
-export function makeWithAuth({ authManager, logger, metrics = null }) {
+export function makeWithAuth({ authManager, logger, metrics = null, mcpServer = null }) {
   return function withAuth(toolName, handler) {
     const invoke = async (params) => {
       const startTime = Date.now();
@@ -62,6 +81,13 @@ export function makeWithAuth({ authManager, logger, metrics = null }) {
       const internal = isInternalRequest();
       const billingExempt = creatorMode || internal;
       const creditCost = billingExempt ? 0 : authManager.getToolCost(toolName, params);
+      // redact_pii's model pass runs at this seam, AFTER the handler, so the
+      // handler's own setActualCost report cannot know about it. Split the
+      // projection: the tool prices its own work, and the model surcharge is
+      // added back only when a model actually completed (G4).
+      const redactionCost = billingExempt ? 0 : Math.min(redactionSurcharge(toolName, params), creditCost);
+      const toolCost = creditCost - redactionCost;
+      let redactionModelRan = false;
       let outcome = 'pending';
       let thrown = null;
       // Only bill the error-path half-charge once the handler has actually run.
@@ -73,7 +99,8 @@ export function makeWithAuth({ authManager, logger, metrics = null }) {
       // lower the charge, never raise it.
       const billable = () => {
         const reported = reportedActualCost();
-        return reported == null ? creditCost : Math.min(reported, creditCost);
+        const spent = reported == null ? toolCost : Math.min(reported, toolCost);
+        return spent + (redactionModelRan ? redactionCost : 0);
       };
 
       try {
@@ -116,6 +143,19 @@ export function makeWithAuth({ authManager, logger, metrics = null }) {
         // result did real work and bills for it.
         const refused = isErrorResult && preflightRefusal() !== null;
 
+        // Phase 5 (5.3): redact_pii scrubs the page text this call returns.
+        // It runs BEFORE the inline-threshold stage below, so what gets
+        // stored — and what read_result later serves — is already redacted.
+        // Internal (website REST proxy) requests are redacted too: the text
+        // is the same text, and the website has no copy of it to scrub.
+        if (!isErrorResult && toolName in REDACTION_TOOLS) {
+          try {
+            redactionModelRan = await redactResult(toolName, result, params, mcpServer);
+          } catch {
+            /* redaction must never break the request path */
+          }
+        }
+
         // Phase 2: a result over max_inline_chars is stored and returned as
         // a preview plus a result_handle for read_result. Internal (website
         // REST proxy) requests are left whole — the website applies its own

package/src/tools/search/batchSearch.js

@@ -0,0 +1,50 @@
+/**
+ * batchSearch.js — the one declaration of `search_web`'s `queries` param
+ * (Phase 5, 5.1).
+ *
+ * `search_web` takes one query. A caller comparing five phrasings, or
+ * checking a term across five sites, pays five round-trips for what is one
+ * unit of work. `queries` accepts 1-10 of them in a single call; each still
+ * runs through the SAME `execute()` pipeline — expansion, cache, dedupe,
+ * rank — so a batch entry and a single call are the same result.
+ *
+ * The batch wrapper sits ABOVE the provider short-circuit in `execute()`, so
+ * the SearXNG branch (which is not part of the adapter factory) inherits
+ * `queries` without a second implementation.
+ *
+ * The field and the price rule live here so `server.js`, the tool module and
+ * `AuthManager.getToolCost` read one declaration (G5) — the same arrangement
+ * `escalation.js` has for `scrape`.
+ */
+
+import { z } from 'zod';
+
+/** How many queries one call may carry. */
+export const MAX_SEARCH_QUERIES = 10;
+
+/** search_web's price for ONE query, as AuthManager's table spells it. */
+export const SEARCH_WEB_CREDITS = 5;
+
+/** The public field, with the text the client sees. */
+export const SEARCH_QUERIES_PARAM = {
+  queries: z.array(z.string().min(1)).min(1).max(MAX_SEARCH_QUERIES).optional().describe(`Run 1-${MAX_SEARCH_QUERIES} searches in one call instead of ${MAX_SEARCH_QUERIES} round-trips; every other parameter applies to each. Results come back in results_by_query, one entry per query, in order. Costs 5 per query. Use this OR query, not both`)
+};
+
+/** Rejected when a call carries both `query` and `queries`, or neither. */
+export const EXACTLY_ONE_QUERY_MESSAGE =
+  `search_web needs exactly one of "query" (a single search) or "queries" (1-${MAX_SEARCH_QUERIES} searches in one call), not both and not neither`;
+
+/**
+ * How many searches this call will run, for pricing. Reads the RAW param —
+ * getToolCost runs before validation — so anything that is not a non-empty
+ * array prices as the single-query form, and a caller who sends more than the
+ * schema allows never produces a silly projection (the schema rejects that
+ * call before it is billed at all).
+ *
+ * @param {unknown} queries the raw `queries` param
+ * @returns {number} 1..MAX_SEARCH_QUERIES
+ */
+export function searchQueryCount(queries) {
+  if (!Array.isArray(queries) || queries.length === 0) return 1;
+  return Math.min(queries.length, MAX_SEARCH_QUERIES);
+}

package/src/tools/search/searchWeb.js

@@ -8,6 +8,10 @@ import { SearchResultCache } from './ranking/SearchResultCache.js';
 import LocalizationManager from '../../core/LocalizationManager.js';
 import { isCreatorModeVerified } from '../../core/creatorMode.js';
 import { searchViaSearxng } from './providers/searxng.js';
+import { MAX_SEARCH_QUERIES, SEARCH_WEB_CREDITS, EXACTLY_ONE_QUERY_MESSAGE } from './batchSearch.js';
+import { setActualCost } from '../../server/requestContext.js';
+
+const BatchQueriesSchema = z.array(z.string().min(1)).min(1).max(MAX_SEARCH_QUERIES);
 
 const SearchWebSchema = z.object({
   query: z.string().min(1),
@@ -126,7 +130,47 @@ export class SearchWebTool {
     });
   }
 
+  /**
+   * Run 1-10 queries through the single-query pipeline and key the results by
+   * query (5.1). Sequential: each entry is a separate billed backend search,
+   * and firing ten at once at the provider buys nothing but rate limits.
+   *
+   * @param {object} params the call's params, `queries` included
+   * @returns {Promise<{queries: string[], count: number, results_by_query: object[]}>}
+   */
+  async _executeBatch(params) {
+    const { queries, query: _ignored, ...rest } = params;
+    const parsed = BatchQueriesSchema.parse(queries);
+
+    const results_by_query = [];
+    let ran = 0;
+    for (const query of parsed) {
+      try {
+        results_by_query.push({ query, ...await this.execute({ ...rest, query }) });
+        ran++;
+      } catch (error) {
+        // One failed query does not sink the other nine.
+        results_by_query.push({ query, error: error.message });
+      }
+    }
+
+    // The projection is 5 per query; a query that failed before it reached a
+    // backend did no work and must not be billed for one (G4). The projection
+    // is the ceiling, so this only ever lowers the charge.
+    setActualCost(SEARCH_WEB_CREDITS * ran);
+
+    return { queries: parsed, count: parsed.length, results_by_query };
+  }
+
   async execute(params) {
+    // Batch form (5.1). Handled above the provider short-circuit below, so
+    // the SearXNG branch runs each query through the same path the default
+    // provider does.
+    const hasQuery = params?.query !== undefined;
+    const hasQueries = params?.queries !== undefined;
+    if (hasQuery === hasQueries) throw new Error(EXACTLY_ONE_QUERY_MESSAGE);
+    if (hasQueries) return await this._executeBatch(params);
+
     try {
       const validated = SearchWebSchema.parse(params);
 

package/src/utils/secretMask.js

@@ -9,6 +9,8 @@
  *   logger.error('fetch failed', maskSecrets({ apiKey, url, error }));
  */
 
+import { redactPii } from 'crawlforge-extractors';
+
 const SECRET_KEYS_RE = /api[_-]?key|apikey|x-api-key|password|passwd|secret|token|authorization|auth|credential|login|formautofill|private[_-]?key|access[_-]?key|proxy_url|proxyurl|cookie/i;
 
 const MASK = '[REDACTED]';
@@ -97,16 +99,18 @@ export function maskError(error) {
 
 /**
  * Heuristic: redact strings that look like API keys / tokens embedded in text.
+ *
+ * The patterns moved to crawlforge-extractors' `redactPii` (Phase 5, 5.3), so
+ * the two surfaces run one implementation and page text gets the same
+ * treatment log lines already got. The SECRET class there is this heuristic,
+ * ported verbatim and asserted byte-for-byte against it upstream: the label
+ * survives and only the value is replaced, which is what keeps an error
+ * message saying WHICH credential the request carried.
+ *
  * @param {string} str
  * @returns {string}
  */
 function redactSecretsFromString(str) {
   if (typeof str !== 'string') return str;
-  return str
-    .replace(/(Bearer\s+)\S+/gi, `$1${MASK}`)
-    .replace(/(api[_-]?key\s*[:=]\s*)\S+/gi, `$1${MASK}`)
-    .replace(/(x-api-key\s*[:=]\s*)\S+/gi, `$1${MASK}`)
-    .replace(/(password\s*[:=]\s*)\S+/gi, `$1${MASK}`)
-    .replace(/(secret\s*[:=]\s*)\S+/gi, `$1${MASK}`)
-    .replace(/(token\s*[:=]\s*)\S+/gi, `$1${MASK}`);
+  return redactPii(str, { entities: ['SECRET'], replaceStyle: 'mask' }).text;
 }