crawlforge-mcp-server 5.9.0 → 6.0.0

package/src/server/transports/streamableHttp.js

@@ -1,42 +1,62 @@
 /**
- * Streamable HTTP transport (MCP spec 2025-06-18).
+ * Dual-era Streamable HTTP transport.
  *
- * Single endpoint at /mcp:
- *   - POST /mcp           — JSON-RPC request, response as JSON or SSE stream
- *   - GET  /mcp           — SSE stream for server → client notifications
- *   - DELETE /mcp         — terminate session
+ * One endpoint at /mcp serves both protocol eras, routed by the SDK's own
+ * classification (`isLegacyRequest`) so this module can never disagree with it:
  *
- * Session resumption:
- *   - Server generates a session id and returns it as `Mcp-Session-Id` on init
- *   - Clients re-send `Mcp-Session-Id` on subsequent requests to resume state
+ *   - 2026-07-28 ("modern"): stateless, one server instance per request, each
+ *     request carrying its own `_meta` envelope (protocol version, clientInfo,
+ *     clientCapabilities) plus the SEP-2243 `Mcp-Method` / `Mcp-Name` headers.
+ *     Served by `createMcpHandler(..., { legacy: 'reject' })`, which owns the
+ *     Content-Type gate (415), the header/body cross-checks (-32020) and
+ *     `server/discover`.
+ *   - 2025-era ("legacy"): the sessionful path below — POST /mcp initialize
+ *     issues an `Mcp-Session-Id`, GET /mcp opens the notification SSE stream,
+ *     DELETE /mcp terminates the session. One transport + cloned McpServer per
+ *     session, kept in the `sessions` Map.
  *
  * Auth:
- *   - Bearer / X-API-Key required per request (creator mode bypasses)
+ *   - Bearer / X-API-Key required per request on BOTH eras, before any era
+ *     routing happens (creator mode bypasses, loopback only)
  *   - When OAuth is enabled (CRAWLFORGE_OAUTH_ENABLED=true), OAuth bearer
  *     tokens are validated by the OAuth provider and mapped server-side to
  *     a CrawlForge API key. See src/server/auth/oauth.js.
  *
  * Observability:
  *   - GET /metrics returns Prometheus exposition (when observability enabled)
- *   - GET /health returns liveness probe
- *
- * Replaces the legacy stateless http.js. Old /mcp endpoint behavior is
- * preserved when CRAWLFORGE_LEGACY_HTTP=true (one-release deprecation window);
- * `http.js`'s connectHttp() forwards straight into this module's legacy mode.
+ *   - GET /health returns liveness probe + the protocol revisions served
  */
-
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, createMcpHandler, isLegacyRequest, SUPPORTED_PROTOCOL_VERSIONS } from "@modelcontextprotocol/server";
+import { NodeStreamableHTTPServerTransport, toNodeHandler, toWebRequest } from "@modelcontextprotocol/node";
 import { createServer } from 'node:http';
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { requestContext } from '../requestContext.js';
-import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { applySpecHygiene } from '../specHygiene.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
 const SERVER_VERSION = pkg.version;
 
+/**
+ * Protocol revisions this endpoint serves, newest first: the modern era's
+ * revisions followed by the 2025-era list the SDK negotiates via `initialize`.
+ *
+ * The modern list mirrors the SDK's internal SUPPORTED_MODERN_PROTOCOL_VERSIONS,
+ * which is deliberately not exported. streamableHttp.test.js pins it against a
+ * live `server/discover` result, so an SDK upgrade that adds a revision fails a
+ * test rather than drifting silently.
+ */
+const MODERN_PROTOCOL_VERSIONS = Object.freeze(['2026-07-28']);
+const PROTOCOL_VERSIONS = Object.freeze([...MODERN_PROTOCOL_VERSIONS, ...SUPPORTED_PROTOCOL_VERSIONS]);
+
+/**
+ * SEP-2549 cache hint for the `server/discover` result (2026-07-28 only). The
+ * advertisement is the same for every caller and only changes when the server
+ * is redeployed, so it is `public`; the 5-minute TTL matches the tools/call
+ * hints in specHygiene.js. Without a hint the SDK emits `0` / `'private'`.
+ */
+const DISCOVER_CACHE_HINT = Object.freeze({ ttlMs: 300000, cacheScope: 'public' });
+
 /**
  * Build the `tools` array for the Smithery static server card, straight from
  * the live tool registry.
@@ -59,10 +79,9 @@ function buildToolCards(server) {
     .map(([name, tool]) => {
       let inputSchema = { type: 'object', properties: {} };
       try {
-        const shape = tool?.inputSchema;
-        if (shape) {
-          const zodObject = typeof shape?.safeParse === 'function' ? shape : z.object(shape);
-          const converted = zodToJsonSchema(zodObject, { $refStrategy: 'none' });
+        if (tool?.inputSchema) {
+          // The SDK's own conversion, so the card mirrors what tools/list serves.
+          const converted = { ...server.toolInputSchemaJson(name) };
           delete converted.$schema;
           inputSchema = converted;
         }
@@ -89,23 +108,34 @@ function buildToolCards(server) {
  * prompt tables — plain config + handler-closure references, no per-connection
  * state — then re-runs the same internal handler-wiring methods McpServer
  * itself calls from registerTool/registerResource/registerPrompt. This
- * depends on @modelcontextprotocol/sdk 1.30.0's internal McpServer/Server
- * field names (`_registered*`, `set*RequestHandlers`, `_capabilities`,
- * `_taskStore`); re-check on SDK upgrades.
+ * depends on the SDK's internal McpServer/Server field names
+ * (`_registered*`, `set*RequestHandlers`, `_capabilities`); re-verified
+ * against @modelcontextprotocol/server 2.0.0, which still exposes all of
+ * them. `_taskStore` is gone — v2 removed experimental tasks (SEP-2663).
+ * Re-check on SDK upgrades.
+ *
+ * The same clone backs a 2025-era session and a single 2026-era request, so
+ * both eras serve exactly the same tools — the SDK's "one factory for both
+ * legs" rule.
+ *
+ * applySpecHygiene() runs on the clone because its wrappers live on the
+ * template's own Protocol instance, not in the `_registered*` tables the clone
+ * copies: without this call an HTTP client got unsorted, icon-less tools/list
+ * results and no SEP-2549 cache markers on tools/call, while a stdio client
+ * got all three.
  *
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} templateServer
+ * @param {import('@modelcontextprotocol/server').McpServer} templateServer
  */
 function cloneServerForSession(templateServer) {
   const low = templateServer.server;
-  // capabilities + taskStore must survive the clone: the SDK's Protocol
-  // constructor wires the tasks/* request handlers only when options.taskStore
-  // is present, and without it a tools/call on any task-capable tool
-  // (crawl_deep, batch_scrape, deep_research, agent) throws
-  // 'No task store provided for task-capable tool.'
+  // capabilities must survive the clone so the session server advertises the
+  // same surface as the template. cacheHints only reaches the 2026-era encode
+  // seam (it rides a symbol-keyed property that is never serialized), so a
+  // 2025-era response is byte-identical with or without it.
   const sessionServer = new McpServer(low._serverInfo, {
     instructions: low._instructions,
     capabilities: low._capabilities,
-    taskStore: low._taskStore
+    cacheHints: { 'server/discover': DISCOVER_CACHE_HINT }
   });
 
   sessionServer._registeredTools = templateServer._registeredTools;
@@ -118,9 +148,18 @@ function cloneServerForSession(templateServer) {
   if (templateServer._promptHandlersInitialized) sessionServer.setPromptRequestHandlers();
   if (templateServer._completionHandlerInitialized) sessionServer.setCompletionRequestHandler();
 
+  applySpecHygiene(sessionServer);
+
   return sessionServer;
 }
 
+/** Reads a request body to completion as UTF-8. */
+async function readRequestBody(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
 /** Best-effort close — swallows errors so cleanup never throws into a request handler. */
 function safeClose(closable) {
   if (closable && typeof closable.close === 'function') {
@@ -138,14 +177,14 @@ function sendRpcError(res, status, code, message) {
 }
 
 /**
- * Stateful, session-aware Streamable HTTP transport.
+ * Dual-era Streamable HTTP transport: stateless 2026-07-28 and sessionful
+ * 2025-era traffic on the same /mcp route.
  *
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/server').McpServer} server
  * @param {import('../../core/AuthManager.js').default} authManager
  * @param {import('../../utils/Logger.js').logger} logger
  * @param {object} [options]
  * @param {number} [options.port=3000]
- * @param {boolean} [options.legacy=false]  — if true, run in stateless mode (3.1 behavior)
  * @param {object} [options.oauth]          — OAuth provider (see src/server/auth/oauth.js)
  * @param {object} [options.metrics]        — Prometheus registry (see src/observability/metrics.js)
  */
@@ -159,22 +198,37 @@ export async function connectStreamableHttp(server, authManager, logger, options
   if (authManager.isCreatorMode() && !hostIsLoopback) {
     console.error(`WARNING: creator mode is enabled but the server is bound to ${host} (non-loopback) — per-request auth will NOT be bypassed. Bind to 127.0.0.1 to use creator mode.`);
   }
-  const legacy = options.legacy === true;
   const oauthProvider = options.oauth ?? null;
   const metrics = options.metrics ?? null;
 
-  const mode = legacy ? 'legacy-stateless' : 'streamable-stateful';
+  const mode = 'streamable-stateful';
   const toolCount = Object.keys(server._registeredTools ?? {}).length;
 
   // sessionId -> { transport, server }. One StreamableHTTPServerTransport (and
   // therefore one cloned McpServer — see cloneServerForSession) per session.
+  // 2025-era only: the modern era is stateless and holds nothing here.
   const sessions = new Map();
 
+  // 2026-07-28 leg. `legacy: 'reject'` keeps it strict — every 2025-era request
+  // is routed to the sessions Map above by isLegacyRequest before it can reach
+  // this handler, so the modern leg never has to serve one. The SDK owns the
+  // Content-Type gate (415), the Mcp-Method/Mcp-Name cross-checks (-32020 on
+  // 400) and `server/discover`; nothing here re-implements them.
+  const modernHandler = createMcpHandler(() => cloneServerForSession(server), {
+    legacy: 'reject',
+    onerror: (err) => logger.warn('2026-era MCP request rejected', { error: err?.message })
+  });
+  const serveModern = toNodeHandler(modernHandler, {
+    onerror: (err) => logger.error('2026-era MCP request failed', { error: err?.message })
+  });
+
   const httpServer = createServer(async (req, res) => {
     // CORS — Smithery + browser-based MCP clients
     res.setHeader('Access-Control-Allow-Origin', '*');
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id, mcp-session-id, Authorization, X-API-Key, X-Internal-Secret');
+    // MCP-Protocol-Version / Mcp-Method / Mcp-Name are the 2026-07-28 era's
+    // request headers; the session id headers are the 2025 era's.
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id, mcp-session-id, MCP-Protocol-Version, Mcp-Method, Mcp-Name, Authorization, X-API-Key, X-Internal-Secret');
     res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id, mcp-session-id');
 
     if (req.method === 'OPTIONS') {
@@ -186,7 +240,7 @@ export async function connectStreamableHttp(server, authManager, logger, options
     // Health probe
     if (req.url === '/health') {
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ status: 'ok', version: SERVER_VERSION, mode }));
+      res.end(JSON.stringify({ status: 'ok', version: SERVER_VERSION, mode, protocolVersions: PROTOCOL_VERSIONS }));
       return;
     }
 
@@ -273,38 +327,42 @@ export async function connectStreamableHttp(server, authManager, logger, options
         internal = authResult.internal === true;
       }
 
-      if (legacy) {
-        // Stateless mode: the SDK forbids reusing a transport (or its connected
-        // Server) across requests, so build a fresh pair per request and always
-        // end the response, even on failure.
-        let sessionServer;
-        let reqTransport;
+      // Era routing. Only a POST can carry the 2026-07-28 per-request envelope;
+      // body-less GET/DELETE are 2025 session operations by construction and
+      // isLegacyRequest classifies them as such, so they skip this entirely and
+      // keep their existing behaviour byte-for-byte.
+      //
+      // Reading the body here drains the Node stream, so the parsed value is
+      // handed to whichever leg serves the request. A body that is not valid
+      // JSON classifies legacy (the SDK's own rule), and the 2025 transport
+      // still writes its own parse error — hence the undefined pass-through
+      // rather than an answer invented here.
+      let parsedBody;
+      if (req.method === 'POST') {
         try {
-          sessionServer = cloneServerForSession(server);
-          reqTransport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-          await sessionServer.connect(reqTransport);
-          await requestContext.run({ internal }, () => reqTransport.handleRequest(req, res));
-        } catch (err) {
-          logger.error('Legacy Streamable HTTP request failed', { error: err?.message });
-          sendRpcError(res, 500, -32603, 'Internal server error');
-        } finally {
-          res.on('close', () => {
-            safeClose(reqTransport);
-            safeClose(sessionServer);
-          });
+          parsedBody = JSON.parse(await readRequestBody(req));
+        } catch {
+          parsedBody = undefined;
+        }
+
+        if (parsedBody !== undefined) {
+          const probe = await toWebRequest(req, parsedBody);
+          if (!(await isLegacyRequest(probe, parsedBody))) {
+            await requestContext.run({ internal }, () => serveModern(req, res, parsedBody));
+            return;
+          }
         }
-        return;
       }
 
-      // Stateful mode: route by Mcp-Session-Id. A request without the header
-      // must be a fresh initialize, which gets its own transport + server pair
+      // 2025 era: route by Mcp-Session-Id. A request without the header must be
+      // a fresh initialize, which gets its own transport + server pair
       // (independent of any prior session's lifecycle) so reconnects/re-inits
       // never hit a stuck 'already initialized' transport.
       const sessionIdHeader = req.headers['mcp-session-id'];
       const existing = sessionIdHeader ? sessions.get(String(sessionIdHeader)) : undefined;
 
       if (existing) {
-        await requestContext.run({ internal }, () => existing.transport.handleRequest(req, res));
+        await requestContext.run({ internal }, () => existing.transport.handleRequest(req, res, parsedBody));
         return;
       }
 
@@ -321,7 +379,7 @@ export async function connectStreamableHttp(server, authManager, logger, options
       }
 
       const sessionServer = cloneServerForSession(server);
-      const transport = new StreamableHTTPServerTransport({
+      const transport = new NodeStreamableHTTPServerTransport({
         sessionIdGenerator: () => randomUUID(),
         onsessioninitialized: (sid) => {
           sessions.set(sid, { transport, server: sessionServer });
@@ -337,7 +395,7 @@ export async function connectStreamableHttp(server, authManager, logger, options
 
       try {
         await sessionServer.connect(transport);
-        await requestContext.run({ internal }, () => transport.handleRequest(req, res));
+        await requestContext.run({ internal }, () => transport.handleRequest(req, res, parsedBody));
       } catch (err) {
         logger.error('Streamable HTTP session initialization failed', { error: err?.message });
         safeClose(transport);
@@ -355,7 +413,7 @@ export async function connectStreamableHttp(server, authManager, logger, options
     httpServer.listen(port, host, () => {
       const actual = httpServer.address()?.port ?? port;
       console.error(`CrawlForge MCP Server v${SERVER_VERSION} listening on ${host}:${actual} (Streamable HTTP, ${mode})`);
-      console.error(`MCP endpoint:   http://${host}:${actual}/mcp`);
+      console.error(`MCP endpoint:   http://${host}:${actual}/mcp (protocol ${PROTOCOL_VERSIONS.join(', ')})`);
       console.error(`Health check:   http://${host}:${actual}/health`);
       if (metrics) console.error(`Metrics:        http://${host}:${actual}/metrics`);
       if (oauthProvider) console.error(`OAuth discovery: http://${host}:${actual}/.well-known/oauth-authorization-server`);
@@ -366,13 +424,17 @@ export async function connectStreamableHttp(server, authManager, logger, options
   return {
     httpServer,
     sessions,
-    /** Closes every live session's transport + server, then the HTTP server. */
+    /**
+     * Closes every live 2025-era session's transport + server and the modern
+     * leg (aborting in-flight exchanges), then the HTTP server.
+     */
     async close() {
       for (const { transport, server: sessionServer } of sessions.values()) {
         safeClose(transport);
         safeClose(sessionServer);
       }
       sessions.clear();
+      await modernHandler.close().catch(() => {});
       await new Promise((resolve) => httpServer.close(() => resolve()));
     }
   };

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/crawl/crawlDeep.js

@@ -22,7 +22,7 @@ const CrawlDeepSchema = z.object({
     dampingFactor: z.number().min(0).max(1).optional().default(0.85),
     maxIterations: z.number().min(1).max(1000).optional().default(100),
     enableCaching: z.boolean().optional().default(true)
-  }).optional().default({}),
+  }).optional().prefault({}),
   // New domain filtering options
   domain_filter: z.object({
     whitelist: z.array(z.union([
@@ -59,7 +59,7 @@ const CrawlDeepSchema = z.object({
       timeout: z.number().optional(),
       maxPages: z.number().optional(),
       concurrency: z.number().optional()
-    })).optional().default({})
+    })).optional().prefault({})
   }).optional(),
   import_filter_config: z.string().optional(), // JSON string of exported config
   // Session reuse: when enabled, all page fetches share a cookie jar and
@@ -67,11 +67,11 @@ const CrawlDeepSchema = z.object({
   session: z.object({
     enabled: z.boolean(),
     persistCookies: z.boolean().optional().default(true),
-    headers: z.record(z.string()).optional().default({}),
+    headers: z.record(z.string()).optional().prefault({}),
     initialRequest: z.object({
       url: z.string().url(),
       method: z.string().optional().default('GET'),
-      headers: z.record(z.string()).optional().default({}),
+      headers: z.record(z.string()).optional().prefault({}),
       body: z.string().optional()
     }).optional()
   }).optional()

package/src/tools/extract/analyzeContent.js

@@ -26,7 +26,7 @@ const AnalyzeContentSchema = z.object({
     includeAdvancedMetrics: z.boolean().default(false),
     groupEntitiesByType: z.boolean().default(true),
     rankByRelevance: z.boolean().default(true)
-  }).optional().default({})
+  }).optional().prefault({})
 });
 
 const AnalyzeContentResult = z.object({

package/src/tools/extract/extractContent.js

@@ -45,7 +45,7 @@ const ExtractContentSchema = z.object({
     includeRawHTML: z.boolean().default(false),
     includeCleanedHTML: z.boolean().default(false),
     outputFormat: z.enum(['text', 'markdown', 'structured']).default('structured')
-  }).optional().default({})
+  }).optional().prefault({})
 });
 
 const ExtractContentResult = z.object({

package/src/tools/extract/processDocument.js

@@ -49,7 +49,7 @@ const ProcessDocumentSchema = z.object({
     // Content filtering
     minContentLength: z.number().min(0).default(50),
     removeBoilerplate: z.boolean().default(true)
-  }).optional().default({})
+  }).optional().prefault({})
 });
 
 const ProcessDocumentResult = z.object({

package/src/tools/extract/summarizeContent.js

@@ -28,7 +28,7 @@ const SummarizeContentSchema = z.object({
     maxKeywords: z.number().min(1).max(20).default(10),
     preserveStructure: z.boolean().default(false),
     language: z.string().optional()
-  }).optional().default({})
+  }).optional().prefault({})
 });
 
 const SummarizeContentResult = z.object({

package/src/tools/llmstxt/generateLLMsTxt.js

@@ -21,7 +21,7 @@ const GenerateLLMsTxtSchema = z.object({
     checkSecurity: z.boolean().optional().default(false).describe('Whether to probe security-sensitive paths (opt-in; sends requests to /admin, /login, etc.)'),
     probeRateLimit: z.boolean().optional().default(false).describe('Whether to send repeated probe requests to estimate rate limits (opt-in; fires ~5 requests)'),
     respectRobots: z.boolean().optional().default(true).describe('Whether to respect robots.txt')
-  }).optional().default({}),
+  }).optional().prefault({}),
 
   outputOptions: z.object({
     includeDetailed: z.boolean().optional().default(true).describe('Generate detailed LLMs-full.txt'),
@@ -31,7 +31,7 @@ const GenerateLLMsTxtSchema = z.object({
     customGuidelines: z.array(z.string()).optional().describe('Additional custom guidelines'),
     customRestrictions: z.array(z.string()).optional().describe('Additional restrictions'),
     robotsStyle: z.boolean().optional().default(false).describe('Emit legacy robots.txt-style directives instead of spec-compliant llmstxt.org markdown')
-  }).optional().default({}),
+  }).optional().prefault({}),
 
   complianceLevel: z.enum(['basic', 'standard', 'strict']).optional().default('standard').describe('Compliance level for generated guidelines'),
   

package/src/tools/research/deepResearch.js

@@ -238,7 +238,7 @@ export class DeepResearchTool {
         return {
           success: false,
           error: 'Invalid parameters',
-          details: validationError.errors.map(err => ({
+          details: validationError.issues.map(err => ({
             field: err.path.join('.'),
             message: err.message,
             received: err.received

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);