pi-web-toolkit 0.3.1 → 0.3.3

package/extensions/firecrawl_scrape.ts

@@ -41,17 +41,17 @@ const firecrawlScrapeTool = defineTool({
   name: "firecrawl_scrape",
   label: "Firecrawl Scrape",
   description: [
-    "Fetch a single page as clean markdown via Firecrawl (keyless — no API key, no signup).",
-    "Use firecrawl_scrape when the local web_fetch fails on a hard target (anti-bot,",
-    "JavaScript-heavy pages, PDFs) or when you need Firecrawl's cloud rendering directly.",
+    "Fallback-only cloud fetch via Firecrawl (keyless — no API key, no signup).",
+    "Do not use firecrawl_scrape as the first attempt for ordinary URL reading; use web_fetch first.",
+    "Use firecrawl_scrape only when web_fetch already failed on a hard target (anti-bot,",
+    "JavaScript-heavy pages, PDFs), or when the user explicitly asks for Firecrawl/cloud rendering.",
     "Privacy: the URL and page content are sent to Firecrawl's cloud.",
     `Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; if truncated, full output is saved to a temp file.`,
   ].join(" "),
-  promptSnippet: "Fetch a single page via Firecrawl keyless (anti-bot / JS / PDF fallback)",
+  promptSnippet: "Fallback-only Firecrawl scrape",
   promptGuidelines: [
-    "Prefer web_fetch first; reach for firecrawl_scrape when web_fetch fails or you need cloud rendering.",
-    "firecrawl_scrape handles anti-bot protection, JS-heavy SPAs, and PDFs that scrapling may miss.",
-    "Always pass the full URL including https://.",
+    "Use firecrawl_scrape only after web_fetch fails or explicit cloud scraping/rendering.",
+    "Use firecrawl_scrape for anti-bot pages, heavy JS, and PDFs.",
   ],
   parameters: FirecrawlScrapeParamsSchema,
 
@@ -97,13 +97,6 @@ const firecrawlScrapeTool = defineTool({
 
   renderResult(result, { expanded, isPartial }, theme, context) {
     const isError = context?.isError ?? false;
-
-    if (isPartial) {
-      const domain = details?.url ? getDomain(details.url) : "";
-      const label = domain ? `Scraping ${domain} via Firecrawl...` : "Scraping via Firecrawl...";
-      return new Text(theme.fg("warning", label), 0, 0);
-    }
-
     const details = result.details as {
       url?: string;
       bytes?: number;
@@ -113,6 +106,12 @@ const firecrawlScrapeTool = defineTool({
       creditsUsed?: number;
     } | undefined;
 
+    if (isPartial) {
+      const domain = details?.url ? getDomain(details.url) : "";
+      const label = domain ? `Scraping ${domain} via Firecrawl...` : "Scraping via Firecrawl...";
+      return new Text(theme.fg("warning", label), 0, 0);
+    }
+
     if (isError) {
       const errText = getErrorText(result);
       let text = theme.fg("error", "✗ Firecrawl scrape failed");

package/extensions/firecrawl_search.ts

@@ -42,17 +42,17 @@ const firecrawlSearchTool = defineTool({
   name: "firecrawl_search",
   label: "Firecrawl Search",
   description: [
-    "Search the web via Firecrawl (keyless — no API key, no signup).",
+    "Fallback-only cloud search via Firecrawl (keyless — no API key, no signup).",
+    "Do not use firecrawl_search as the first attempt for ordinary web discovery; use web_search first.",
     "Supports sources (web/images/news) and categories (github/research/pdf) that",
-    "SearXNG does not. Use as an escape hatch or when web_search returns nothing.",
+    "SearXNG does not. Use only as an escape hatch when web_search fails/returns nothing, or when the user explicitly asks for Firecrawl/cloud search.",
     "Privacy: the query is sent to Firecrawl's cloud.",
     `Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; if truncated, full output is saved to a temp file.`,
   ].join(" "),
-  promptSnippet: "Search the web via Firecrawl keyless (categories, sources, domain filters)",
+  promptSnippet: "Fallback-only Firecrawl search",
   promptGuidelines: [
-    "Prefer web_search first; reach for firecrawl_search when web_search fails or returns nothing.",
-    "Use categories=[\"github\"], [\"research\"], or [\"pdf\"] for source-type-specific discovery.",
-    "Use includeDomains/excludeDomains to scope results to specific sites.",
+    "Use firecrawl_search only after web_search fails/returns nothing, for Firecrawl-only categories, or explicit cloud search.",
+    "Use categories=[\"github\"|\"research\"|\"pdf\"] and includeDomains/excludeDomains when needed.",
   ],
   parameters: FirecrawlSearchParamsSchema,
 

package/extensions/index.ts

@@ -17,6 +17,26 @@ import registerFirecrawlScrape from "./firecrawl_scrape";
 import registerFirecrawlSearch from "./firecrawl_search";
 import registerFirecrawlInteract from "./firecrawl_interact";
 
+const WEB_TOOL_ROUTING_POLICY = [
+  "Web tools are local-first: web_search=discover, web_fetch=one static URL, web_batch_fetch=2–5 static URLs, web_browse=interaction.",
+  "Use firecrawl_* only after the matching local tool failed in this conversation, or when the user explicitly asks for Firecrawl/cloud.",
+  "web_search/web_fetch/web_browse already auto-fallback to Firecrawl; pass full URLs with scheme and selectors when useful.",
+].join("\n");
+
+const WEB_TOOL_NAMES = new Set([
+  "web_search",
+  "web_fetch",
+  "web_browse",
+  "web_batch_fetch",
+  "firecrawl_search",
+  "firecrawl_scrape",
+  "firecrawl_interact",
+]);
+
+function shouldInjectWebToolRoutingPolicy(selectedTools: readonly string[] | undefined): boolean {
+  return selectedTools?.some((tool) => WEB_TOOL_NAMES.has(tool)) ?? false;
+}
+
 export default function (pi: ExtensionAPI) {
   registerWebSearch(pi);
   registerWebFetch(pi);
@@ -25,4 +45,9 @@ export default function (pi: ExtensionAPI) {
   registerFirecrawlScrape(pi);
   registerFirecrawlSearch(pi);
   registerFirecrawlInteract(pi);
+
+  pi.on("before_agent_start", (event) => {
+    if (!shouldInjectWebToolRoutingPolicy(event.systemPromptOptions.selectedTools)) return;
+    return { systemPrompt: `${event.systemPrompt}\n\n${WEB_TOOL_ROUTING_POLICY}` };
+  });
 }

package/extensions/utils/agent-browser.ts

@@ -6,6 +6,7 @@
  */
 
 import { runCLI } from "./cli-runner";
+import { getToolkitCommand } from "./config";
 
 export interface BrowseAction {
   type: "click" | "fill" | "type" | "press" | "wait" | "wait_selector" | "scroll";
@@ -180,7 +181,7 @@ export async function runAgentBrowserBatch(
 
   try {
     const result = await runCLI({
-      command: "agent-browser",
+      command: getToolkitCommand("agentBrowser"),
       args,
       stdin: JSON.stringify(commands),
       timeout: options.timeout,
@@ -199,7 +200,7 @@ export async function runAgentBrowserBatch(
       );
     }
   } catch (err: any) {
-    if (err.message === "agent-browser is not installed") {
+    if (typeof err.message === "string" && err.message.includes("is not installed")) {
       throw new Error(
         "agent-browser is not installed.\n\nInstall it with:\n  npm i -g agent-browser && agent-browser install\n\nThen run: agent-browser doctor"
       );
@@ -211,7 +212,7 @@ export async function runAgentBrowserBatch(
 export async function closeAgentBrowserSession(session: string, signal?: AbortSignal): Promise<void> {
   try {
     await runCLI({
-      command: "agent-browser",
+      command: getToolkitCommand("agentBrowser"),
       args: ["--session", session, "close"],
       signal,
     });

package/extensions/utils/config.ts

@@ -0,0 +1,170 @@
+/**
+ * pi-web-toolkit runtime configuration
+ *
+ * Reads user-level toolkit configuration without requiring users to modify
+ * shell profiles. Environment variables remain the highest-priority override.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export const DEFAULT_SEARXNG_URL = "http://localhost:8080";
+
+export interface ToolkitCommandsConfig {
+  scrapling?: string;
+  agentBrowser?: string;
+  firecrawl?: string;
+}
+
+export type FirecrawlRunner = "installed" | "npx" | "bunx";
+
+export interface ToolkitConfig {
+  searxngUrl?: string;
+  firecrawlFallback?: boolean;
+  firecrawlRunner?: FirecrawlRunner;
+  commands?: ToolkitCommandsConfig;
+}
+
+export type ToolkitCommandName = "scrapling" | "agentBrowser" | "firecrawl";
+
+const COMMAND_DEFAULTS: Record<ToolkitCommandName, string> = {
+  scrapling: "scrapling",
+  agentBrowser: "agent-browser",
+  firecrawl: "firecrawl",
+};
+
+const COMMAND_ENV_VARS: Record<ToolkitCommandName, string> = {
+  scrapling: "SCRAPLING_BIN",
+  agentBrowser: "AGENT_BROWSER_BIN",
+  firecrawl: "FIRECRAWL_BIN",
+};
+
+const FIRECRAWL_RUNNERS = ["installed", "npx", "bunx"] as const;
+
+function isFirecrawlRunner(value: string): value is FirecrawlRunner {
+  return (FIRECRAWL_RUNNERS as readonly string[]).includes(value);
+}
+
+export function getDefaultToolkitConfigPath(): string {
+  const configHome = process.env.XDG_CONFIG_HOME?.trim() || path.join(os.homedir(), ".config");
+  return path.join(configHome, "pi-web-toolkit", "config.json");
+}
+
+export function getToolkitConfigPath(): string {
+  const configured = process.env.PI_WEB_TOOLKIT_CONFIG?.trim();
+  return configured || getDefaultToolkitConfigPath();
+}
+
+function parseConfigFile(filePath: string, required: boolean): ToolkitConfig {
+  if (!existsSync(filePath)) {
+    if (required) {
+      throw new Error(`Toolkit config file not found: ${filePath}`);
+    }
+    return {};
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch (err: any) {
+    throw new Error(`Unable to read toolkit config at ${filePath}: ${err.message ?? String(err)}`);
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("expected a JSON object");
+    }
+    validateToolkitConfig(parsed as Record<string, unknown>);
+    return parsed as ToolkitConfig;
+  } catch (err: any) {
+    throw new Error(`Invalid toolkit config at ${filePath}: ${err.message ?? String(err)}`);
+  }
+}
+
+function validateOptionalString(value: unknown, key: string): void {
+  if (value !== undefined && typeof value !== "string") {
+    throw new Error(`${key} must be a string`);
+  }
+}
+
+function validateToolkitConfig(value: Record<string, unknown>): void {
+  validateOptionalString(value.searxngUrl, "searxngUrl");
+
+  if (value.firecrawlFallback !== undefined && typeof value.firecrawlFallback !== "boolean") {
+    throw new Error("firecrawlFallback must be a boolean");
+  }
+
+  if (value.firecrawlRunner !== undefined) {
+    if (typeof value.firecrawlRunner !== "string" || !isFirecrawlRunner(value.firecrawlRunner)) {
+      throw new Error("firecrawlRunner must be one of: installed, npx, bunx");
+    }
+  }
+
+  if (value.commands !== undefined) {
+    if (typeof value.commands !== "object" || value.commands === null || Array.isArray(value.commands)) {
+      throw new Error("commands must be an object");
+    }
+    const commands = value.commands as Record<string, unknown>;
+    validateOptionalString(commands.scrapling, "commands.scrapling");
+    validateOptionalString(commands.agentBrowser, "commands.agentBrowser");
+    validateOptionalString(commands.firecrawl, "commands.firecrawl");
+  }
+}
+
+export function readToolkitConfig(): ToolkitConfig {
+  const filePath = getToolkitConfigPath();
+  const required = Boolean(process.env.PI_WEB_TOOLKIT_CONFIG?.trim());
+  return parseConfigFile(filePath, required);
+}
+
+function normalizeUrl(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+export function getSearxngUrl(): string {
+  const envUrl = process.env.SEARXNG_URL?.trim();
+  if (envUrl) return normalizeUrl(envUrl);
+
+  const cfgUrl = readToolkitConfig().searxngUrl?.trim();
+  if (cfgUrl) return normalizeUrl(cfgUrl);
+
+  return DEFAULT_SEARXNG_URL;
+}
+
+export function getToolkitCommand(name: ToolkitCommandName): string {
+  const envVar = COMMAND_ENV_VARS[name];
+  const envCommand = process.env[envVar]?.trim();
+  if (envCommand) return envCommand;
+
+  const cfgCommand = readToolkitConfig().commands?.[name]?.trim();
+  if (cfgCommand) return cfgCommand;
+
+  return COMMAND_DEFAULTS[name];
+}
+
+export function isFirecrawlFallbackEnabled(): boolean {
+  const envValue = process.env.PI_WEB_FIRECRAWL_FALLBACK;
+  if (envValue !== undefined) {
+    const v = envValue.trim().toLowerCase();
+    return !(v === "0" || v === "false" || v === "no" || v === "off");
+  }
+
+  const cfgValue = readToolkitConfig().firecrawlFallback;
+  if (cfgValue !== undefined) return cfgValue;
+
+  return true;
+}
+
+export function getFirecrawlRunner(): FirecrawlRunner {
+  const envValue = process.env.PI_WEB_FIRECRAWL_RUNNER?.trim().toLowerCase();
+  if (envValue) {
+    if (!isFirecrawlRunner(envValue)) {
+      throw new Error("PI_WEB_FIRECRAWL_RUNNER must be one of: installed, npx, bunx");
+    }
+    return envValue;
+  }
+
+  return readToolkitConfig().firecrawlRunner ?? "installed";
+}

package/extensions/utils/firecrawl.ts

@@ -19,6 +19,7 @@ import { mkdtemp, rm } from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { runCLI } from "./cli-runner";
+import { getFirecrawlRunner, getToolkitCommand, isFirecrawlFallbackEnabled, type FirecrawlRunner } from "./config";
 
 // ---------------------------------------------------------------------------
 // Shared types
@@ -33,8 +34,7 @@ export type FirecrawlFailureKind = "graceful-skip" | "hard-error";
  * the single opt-out for a strict local-only / no-cloud-egress policy.
  */
 export function isFirecrawlEnabled(): boolean {
-  const v = (process.env.PI_WEB_FIRECRAWL_FALLBACK ?? "").trim().toLowerCase();
-  return !(v === "0" || v === "false" || v === "no" || v === "off");
+  return isFirecrawlFallbackEnabled();
 }
 
 export interface FirecrawlFailure {
@@ -159,6 +159,29 @@ export interface FirecrawlCliResult {
   exitCode: number;
 }
 
+export interface FirecrawlCliInvocation {
+  command: string;
+  args: string[];
+}
+
+/**
+ * Build the command used to invoke the official Firecrawl CLI. `npx` and
+ * `bunx` are opt-in runners because they may run or download packages at
+ * fallback time.
+ */
+export function buildFirecrawlCliInvocation(
+  args: string[],
+  runner: FirecrawlRunner = getFirecrawlRunner(),
+): FirecrawlCliInvocation {
+  if (runner === "npx") {
+    return { command: "npx", args: ["-y", "firecrawl-cli", ...args] };
+  }
+  if (runner === "bunx") {
+    return { command: "bunx", args: ["firecrawl-cli", ...args] };
+  }
+  return { command: getToolkitCommand("firecrawl"), args };
+}
+
 /**
  * Run the firecrawl CLI under an isolated temporary HOME with no key env, so
  * it can only ever operate in keyless mode (no stored credentials, no
@@ -178,7 +201,8 @@ export async function runFirecrawlCli(
     delete env.FIRECRAWL_OAUTH_TOKEN;
     env.HOME = home;
     env.XDG_CONFIG_HOME = path.join(home, ".config");
-    return await runCLI({ command: "firecrawl", args, env, signal, timeout });
+    const invocation = buildFirecrawlCliInvocation(args);
+    return await runCLI({ command: invocation.command, args: invocation.args, env, signal, timeout });
   } finally {
     await rm(home, { recursive: true, force: true }).catch(() => { /* best-effort */ });
   }

package/extensions/utils/scrapling.ts

@@ -1,4 +1,5 @@
 import { runCLI } from "./cli-runner";
+import { getToolkitCommand } from "./config";
 
 /**
  * Run a scrapling CLI command with optional abort signal.
@@ -7,7 +8,7 @@ export function runScrapling(
   args: string[],
   signal?: AbortSignal,
 ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
-  return runCLI({ command: "scrapling", args, signal });
+  return runCLI({ command: getToolkitCommand("scrapling"), args, signal });
 }
 
 /**

package/extensions/utils/web-search-core.ts

@@ -0,0 +1,146 @@
+/**
+ * web_search execution core
+ *
+ * Keeps SearXNG-first search behavior behind a testable boundary. Firecrawl
+ * remains fallback-only and missing fallback runners never replace the primary
+ * SearXNG failure/no-result UX.
+ */
+
+import type { FirecrawlSearchOutput } from "./firecrawl";
+import { shouldFallbackSearch } from "./firecrawl";
+
+export interface WebSearchCoreInput {
+  query: string;
+  language?: string;
+  results?: number;
+}
+
+export interface WebSearchResultItem {
+  title: string;
+  url: string;
+  content?: string;
+  engine?: string;
+  score?: number;
+}
+
+interface SearxResponse {
+  query: string;
+  results: WebSearchResultItem[];
+  suggestions?: string[];
+}
+
+export interface WebSearchCoreResult {
+  query: string;
+  totalResults: number;
+  results: WebSearchResultItem[];
+  suggestions?: string[];
+  viaFirecrawl: boolean;
+  creditsUsed?: number;
+}
+
+export interface WebSearchCoreDeps {
+  searxngUrl: string;
+  fetchImpl: typeof fetch;
+  firecrawlSearch: (query: string, options: { limit: number }, signal?: AbortSignal) => Promise<FirecrawlSearchOutput>;
+  signal?: AbortSignal;
+}
+
+function normalizeSearxngUrl(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+export async function runWebSearchCore(
+  input: WebSearchCoreInput,
+  deps: WebSearchCoreDeps,
+): Promise<WebSearchCoreResult> {
+  const searxngUrl = normalizeSearxngUrl(deps.searxngUrl);
+  const maxResults = Math.floor(Math.min(60, Math.max(1, input.results ?? 20)));
+  const language = input.language ?? "";
+
+  const allResults: WebSearchResultItem[] = [];
+  const seenUrls = new Set<string>();
+  let suggestions: string[] | undefined;
+  let finalQuery = input.query;
+  const MAX_PAGES = 3;
+
+  let localOk = true;
+  let localError: string | undefined;
+
+  try {
+    for (let page = 1; page <= MAX_PAGES; page++) {
+      const searchParams = new URLSearchParams({
+        q: input.query,
+        format: "json",
+        pageno: String(page),
+      });
+      if (language) searchParams.set("language", language);
+
+      const response = await deps.fetchImpl(`${searxngUrl}/search?${searchParams.toString()}`, {
+        method: "GET",
+        headers: { Accept: "application/json" },
+        signal: deps.signal,
+      });
+
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`SearXNG error: ${response.status} ${response.statusText}\n${body}`);
+      }
+
+      const data = (await response.json()) as SearxResponse;
+      finalQuery = data.query;
+
+      if (data.suggestions && data.suggestions.length > 0 && !suggestions) {
+        suggestions = data.suggestions;
+      }
+
+      if (!data.results || data.results.length === 0) {
+        break;
+      }
+
+      for (const r of data.results) {
+        if (!seenUrls.has(r.url)) {
+          seenUrls.add(r.url);
+          allResults.push(r);
+        }
+      }
+
+      if (allResults.length >= maxResults) {
+        break;
+      }
+    }
+  } catch (err: any) {
+    localOk = false;
+    localError = err.message ?? String(err);
+  }
+
+  if (shouldFallbackSearch(localOk, allResults.length)) {
+    const fb = await deps.firecrawlSearch(input.query, { limit: Math.min(maxResults, 10) }, deps.signal);
+    if (fb.ok && fb.results.length > 0) {
+      const fbResults: WebSearchResultItem[] = fb.results.slice(0, maxResults).map((r) => ({
+        title: r.title ?? "(untitled)",
+        url: r.url,
+        content: r.description,
+        engine: "firecrawl",
+      }));
+      return {
+        query: input.query,
+        totalResults: fbResults.length,
+        results: fbResults,
+        viaFirecrawl: true,
+        creditsUsed: fb.creditsUsed,
+      };
+    }
+  }
+
+  if (!localOk) {
+    throw new Error(`Failed to query SearXNG at ${searxngUrl}: ${localError}`);
+  }
+
+  return {
+    query: finalQuery,
+    totalResults: allResults.length,
+    results: allResults.slice(0, maxResults),
+    suggestions,
+    viaFirecrawl: false,
+  };
+}

package/extensions/web_batch_fetch.ts

@@ -113,14 +113,10 @@ const webBatchFetchTool = defineTool({
     "For a single page, use web_fetch instead.",
     `Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; if truncated, full output is saved to a temp file.`,
   ].join(" "),
-  promptSnippet: "Fetch multiple URLs in parallel for research",
+  promptSnippet: "Parallel fetch for 2–5 URLs",
   promptGuidelines: [
-    "Use web_batch_fetch when web_search returns multiple (2–5) relevant pages and the agent needs to read them all at once.",
-    "Prefer web_batch_fetch over repeated web_fetch calls when reading multiple pages for comparison or synthesis.",
-    "Use web_batch_fetch for cross-referencing sources, comparing implementations, or synthesizing research from multiple sites.",
-    "For a single URL, always use web_fetch — it supports per-URL selectors and stealthy mode.",
-    "If a page in the batch fails, the tool reports the error but continues with the others.",
-    "Keep batch sizes reasonable (≤8) to avoid overwhelming the browser and token budget.",
+    "Use web_batch_fetch for 2–5 pages to compare/cross-reference/synthesize; single URL → web_fetch.",
+    "Keep batches small (≤8; schema max 15); failed pages are reported without stopping the batch.",
   ],
   parameters: WebBatchFetchParamsSchema,
 

package/extensions/web_browse.ts

@@ -106,22 +106,18 @@ const webBrowseTool = defineTool({
   name: "web_browse",
   label: "Web Browse",
   description: [
-    "Interact with a web page through a browser: navigate, click, fill forms, scroll,",
+    "Primary local-first tool for interactive web pages: navigate, click, fill forms, scroll,",
     "wait for content, and then extract text.",
-    "Uses the agent-browser CLI with batched JSON commands.",
+    "Uses the agent-browser CLI with batched JSON commands, then automatically tries Firecrawl keyless only if local browser automation fails.",
     "Use web_browse when the target content requires interaction (clicking buttons,",
     "scrolling, filling search boxes, waiting for JS to load) before it becomes available.",
     "For pages that need no interaction, use web_fetch instead.",
     `Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; if truncated, full output is saved to a temp file.`,
   ].join(" "),
-  promptSnippet: "Interact with a web page (click, scroll, fill) and extract content",
+  promptSnippet: "Local browser interaction and extraction",
   promptGuidelines: [
-    "Use web_browse when a page requires clicking, scrolling, or form submission before showing target content.",
-    "Use web_browse for SPAs, pagination (click 'Load more'), search forms, tab switching, and modal dialogs.",
-    "For static articles, docs, or blogs that load everything on first request, prefer web_fetch.",
-    "After web_search returns results, prefer web_fetch for reading individual articles.",
-    "Use web_browse directly when interaction is required; otherwise try web_fetch first.",
-    "Always provide a selector to extract only the relevant content area — avoid dumping full page text.",
+    "Use web_browse only when clicks/forms/scroll/wait are needed; otherwise use web_fetch.",
+    "Provide a selector to narrow extracted content when possible.",
   ],
   parameters: WebBrowseParamsSchema,
 

package/extensions/web_fetch.ts

@@ -40,19 +40,15 @@ const webFetchTool = defineTool({
   name: "web_fetch",
   label: "Web Fetch",
   description: [
-    "Fetch and extract readable content from a web page URL.",
-    "Uses scrapling to download the page and convert it to clean markdown.",
-    "Use web_fetch to read the full content of a specific result or user-provided URL.",
+    "Primary local-first tool for reading a single web page URL.",
+    "Fetches and extracts readable content via scrapling, then automatically tries Firecrawl keyless only if the local fetcher fails.",
+    "Use web_fetch as the first attempt to read the full content of a specific result or user-provided URL.",
     "Callers remain responsible for robots.txt and site terms; Scrapling extract commands do not enforce them automatically.",
     `Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; if truncated, full output is saved to a temp file.`,
   ].join(" "),
-  promptSnippet: "Fetch full page content from a URL as markdown",
+  promptSnippet: "Local-first fetch of one URL as markdown",
   promptGuidelines: [
-    "Use web_fetch to read a single page (article, doc, or blog) that needs no interaction.",
-    "For a single URL, always use web_fetch instead of web_batch_fetch.",
-    "If the page is dynamic/JavaScript-heavy, the tool automatically uses browser automation.",
-    "When reading multiple (2–5) pages at once (e.g., after web_search), prefer web_batch_fetch over repeated web_fetch calls.",
-    "Always pass the full URL including https://.",
+    "Use web_fetch for one non-interactive URL; use web_batch_fetch for 2–5 URLs.",
   ],
   parameters: WebFetchParamsSchema,