@aria-cli/tools 1.0.0

package/src/executors/web.ts

@@ -0,0 +1,786 @@
+/**
+ * @aria/tools - Web tool executors
+ *
+ * Implementation of web operations for ARIA tool system.
+ */
+
+import { createHash } from "node:crypto";
+import { log } from "@aria/types";
+import { z } from "zod";
+import type { ToolContext, ToolResult } from "../types.js";
+import { success, fail, getErrorMessage } from "./utils.js";
+import { safeParseJson } from "../utils/safe-parse-json.js";
+import { validateUrlStructure, followRedirects, discardResponseBody } from "../security/ssrf.js";
+import { SearchProviderRouter } from "../providers/router.js";
+import {
+  TavilySearchProvider,
+  DuckDuckGoSearchProvider,
+  BraveSearchProvider,
+  JinaSearchProvider,
+  ExaSearchProvider,
+  FirecrawlSearchProvider,
+} from "../providers/index.js";
+import type { SearchProviderEnv, SearchOptions } from "../providers/search-provider.js";
+import { resolveSearchProviderEnv } from "../providers/search-provider.js";
+import {
+  searchCache,
+  fetchCache,
+  browseCache,
+  type CachedFetchOutput,
+  type CachedBrowseOutput,
+} from "../cache/web-cache.js";
+import { fetchWithSsrf } from "../utils/retry.js";
+import { wrapExternalContent } from "../security/external-content.js";
+import { extractFromResponse } from "../extraction/content-extraction.js";
+import { normalizeGitHubUrl, getUserAgent } from "../utils/url.js";
+
+function buildSearchEnv(ctx: ToolContext): SearchProviderEnv {
+  const env = ctx.env ?? {};
+  return {
+    ARIA_SEARCH_PROVIDER: env.ARIA_SEARCH_PROVIDER ?? process.env.ARIA_SEARCH_PROVIDER,
+    BRAVE_API_KEY: env.BRAVE_API_KEY ?? process.env.BRAVE_API_KEY,
+    FIRECRAWL_API_KEY: env.FIRECRAWL_API_KEY ?? process.env.FIRECRAWL_API_KEY,
+    EXA_API_KEY: env.EXA_API_KEY ?? process.env.EXA_API_KEY,
+    TAVILY_API_KEY: env.TAVILY_API_KEY ?? process.env.TAVILY_API_KEY,
+    JINA_API_KEY: env.JINA_API_KEY ?? process.env.JINA_API_KEY,
+  };
+}
+
+function createSearchRouter(env: SearchProviderEnv): SearchProviderRouter {
+  return new SearchProviderRouter(
+    [
+      new BraveSearchProvider(env),
+      new TavilySearchProvider(env),
+      new JinaSearchProvider(env),
+      new ExaSearchProvider(env),
+      new FirecrawlSearchProvider(env),
+      new DuckDuckGoSearchProvider(),
+    ],
+    env,
+  );
+}
+
+/** Default timeout for fetch requests in milliseconds */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** Default maximum response size in bytes for fetch (1MB) */
+const FETCH_MAX_SIZE_BYTES = 1 * 1024 * 1024;
+
+/** Default maximum response size in bytes for browse (2MB) */
+const BROWSE_MAX_SIZE_BYTES = 2 * 1024 * 1024;
+
+const JsonFetchContentSchema = z.union([
+  z.record(z.string(), z.unknown()),
+  z.array(z.unknown()),
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+]);
+
+/**
+ * Creates an AbortController with a timeout.
+ */
+function createTimeoutController(timeoutMs: number): {
+  controller: AbortController;
+  timeoutId: NodeJS.Timeout;
+} {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    if (!controller.signal.aborted) {
+      controller.abort();
+    }
+  }, timeoutMs);
+  return { controller, timeoutId };
+}
+
+/**
+ * Links a parent AbortSignal to a child AbortController, forwarding abort.
+ * Returns a cleanup function that MUST be called when the operation completes
+ * to prevent the listener from firing after the try/catch scope has exited.
+ */
+function linkAbortSignal(
+  parentSignal: AbortSignal | undefined,
+  childController: AbortController,
+): () => void {
+  if (!parentSignal) return () => {};
+
+  const onAbort = () => {
+    if (!childController.signal.aborted) {
+      childController.abort();
+    }
+  };
+
+  parentSignal.addEventListener("abort", onAbort, { once: true });
+  return () => {
+    parentSignal.removeEventListener("abort", onAbort);
+  };
+}
+
+interface ReadResponseResult {
+  text: string;
+  truncated: boolean;
+  contentBytes: number;
+}
+
+/**
+ * Reads a response body with a streaming byte limit.
+ * Unlike checking Content-Length alone, this protects against chunked/streaming
+ * responses that lack a Content-Length header.
+ *
+ * When `truncate` is false (default), throws if the limit is exceeded.
+ * When `truncate` is true, returns whatever was read up to the limit.
+ */
+async function readResponseWithLimit(
+  response: Response,
+  maxBytes: number,
+  options?: { truncate?: boolean },
+): Promise<ReadResponseResult> {
+  const body = response.body;
+  if (!body) {
+    return { text: "", truncated: false, contentBytes: 0 };
+  }
+
+  const truncateMode = options?.truncate ?? false;
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  const chunks: string[] = [];
+  let totalBytes = 0;
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      const chunkBytes = value.byteLength;
+      if (totalBytes + chunkBytes > maxBytes) {
+        if (truncateMode) {
+          // Keep what we have so far (exclude the chunk that exceeded the limit)
+          reader.cancel();
+          chunks.push(decoder.decode());
+          return {
+            text: chunks.join(""),
+            truncated: true,
+            contentBytes: totalBytes,
+          };
+        }
+        reader.cancel();
+        throw new Error(`Response body exceeds maximum size of ${maxBytes} bytes`);
+      }
+      totalBytes += chunkBytes;
+      chunks.push(decoder.decode(value, { stream: true }));
+    }
+    // Flush the decoder
+    chunks.push(decoder.decode());
+    return { text: chunks.join(""), truncated: false, contentBytes: totalBytes };
+  } catch (err) {
+    reader.cancel();
+    throw err;
+  }
+}
+
+// ============================================================================
+// Web Search
+// ============================================================================
+
+export interface WebSearchInput {
+  /** Search query */
+  query: string;
+  /** Maximum number of results */
+  limit?: number;
+  /** Search topic classification */
+  topic?: "general" | "news";
+  /** Restrict results to these domains */
+  domains?: string[];
+  /** Exclude results from these domains */
+  excludeDomains?: string[];
+  /** Restrict results by freshness window */
+  timeRange?: "day" | "week" | "month" | "year";
+}
+
+export interface WebSearchResult {
+  title: string;
+  url: string;
+  content: string;
+  score?: number;
+}
+
+export interface WebSearchOutput {
+  query: string;
+  results: WebSearchResult[];
+}
+
+function ensureWrappedExternalContent(
+  content: string,
+  source: Parameters<typeof wrapExternalContent>[1],
+): string {
+  return wrapExternalContent(content, source).content;
+}
+
+function wrapWebSearchOutput(output: WebSearchOutput): WebSearchOutput {
+  return {
+    query: output.query,
+    results: output.results.map((result) => ({
+      ...result,
+      content: ensureWrappedExternalContent(result.content, "web_search"),
+    })),
+  };
+}
+
+function hasAdvancedSearchOptions(input: WebSearchInput): boolean {
+  return (
+    input.limit !== undefined ||
+    input.topic !== undefined ||
+    (input.domains?.length ?? 0) > 0 ||
+    (input.excludeDomains?.length ?? 0) > 0 ||
+    input.timeRange !== undefined
+  );
+}
+
+function buildSearchCachePayload(query: string, options: SearchOptions): string {
+  return JSON.stringify({ query, ...options });
+}
+
+function buildRouterSearchCacheKey(
+  env: SearchProviderEnv,
+  query: string,
+  options: SearchOptions,
+): string {
+  const resolved = resolveSearchProviderEnv(env);
+  const providerOverride = resolved.ARIA_SEARCH_PROVIDER ?? "auto";
+  const providerAvailability = [
+    resolved.BRAVE_API_KEY ? "brave=1" : "brave=0",
+    resolved.TAVILY_API_KEY ? "tavily=1" : "tavily=0",
+    resolved.JINA_API_KEY ? "jina=1" : "jina=0",
+    resolved.EXA_API_KEY ? "exa=1" : "exa=0",
+    resolved.FIRECRAWL_API_KEY ? "firecrawl=1" : "firecrawl=0",
+  ].join(",");
+  return `search:router:${providerOverride}:${providerAvailability}:${buildSearchCachePayload(query, options)}`;
+}
+
+function buildNativeSearchCacheKey(
+  providerName: string,
+  query: string,
+  options: SearchOptions,
+): string {
+  return `search:native:${providerName}:${buildSearchCachePayload(query, options)}`;
+}
+
+/**
+ * Searches the web using the SearchProviderRouter with automatic fallback.
+ * Providers are selected based on available API keys (Brave, Tavily, Jina, Exa,
+ * Firecrawl, DuckDuckGo). DuckDuckGo is always available as a last resort.
+ *
+ * Results are cached via LRU+TTL cache for 15 minutes.
+ */
+export async function executeWebSearch(
+  input: WebSearchInput,
+  ctx: ToolContext,
+): Promise<ToolResult> {
+  const limit = input.limit ?? 10;
+  const searchOptions: SearchOptions = {
+    limit,
+    ...(input.topic ? { topic: input.topic } : {}),
+    ...(input.domains ? { domains: input.domains } : {}),
+    ...(input.excludeDomains ? { excludeDomains: input.excludeDomains } : {}),
+    ...(input.timeRange ? { timeRange: input.timeRange } : {}),
+  };
+  const searchEnv = buildSearchEnv(ctx);
+
+  const advancedOptionsProvided = hasAdvancedSearchOptions(input);
+  const nativeSearchAvailable = Boolean(
+    ctx.nativeSearchAdapter && ctx.providerContext?.capabilities?.nativeSearch,
+  );
+  const nativeProviderName = ctx.providerContext?.name ?? "unknown";
+
+  const routerCacheKey = buildRouterSearchCacheKey(searchEnv, input.query, searchOptions);
+  const nativeCacheKey =
+    nativeSearchAvailable && !advancedOptionsProvided
+      ? buildNativeSearchCacheKey(nativeProviderName, input.query, searchOptions)
+      : undefined;
+
+  if (nativeCacheKey) {
+    const cachedNative = searchCache.get(nativeCacheKey);
+    if (cachedNative) {
+      return success(
+        `Found ${cachedNative.results.length} cached results for "${input.query}"`,
+        wrapWebSearchOutput(cachedNative),
+      );
+    }
+  } else {
+    const cachedRouter = searchCache.get(routerCacheKey);
+    if (cachedRouter) {
+      return success(
+        `Found ${cachedRouter.results.length} cached results for "${input.query}"`,
+        wrapWebSearchOutput(cachedRouter),
+      );
+    }
+  }
+
+  if (advancedOptionsProvided && nativeSearchAvailable) {
+    log.debug("[web_search] advanced options provided; bypassing native adapter");
+  }
+
+  // Native search routing: If provider supports native search and adapter is wired, use it
+  // Phase 1: Gemini isolated adapter (router-based callback pattern)
+  if (nativeSearchAvailable && ctx.nativeSearchAdapter && !advancedOptionsProvided) {
+    try {
+      const rawResults = await ctx.nativeSearchAdapter(input.query);
+      if (rawResults.length === 0) {
+        throw new Error("Native search returned no results");
+      }
+      const results: WebSearchResult[] = rawResults.map((r) => ({
+        title: r.title,
+        url: r.url,
+        content: r.content,
+        score: r.score,
+      }));
+      const output: WebSearchOutput = { query: input.query, results };
+      searchCache.set(nativeCacheKey!, output);
+      return success(
+        `Found ${results.length} results for "${input.query}" (native search)`,
+        wrapWebSearchOutput(output),
+      );
+    } catch (err) {
+      // Fall through to SearchProviderRouter on native search failure
+      log.debug(`[web_search] native adapter failed, falling back: ${getErrorMessage(err)}`);
+      const cachedRouterFallback = searchCache.get(routerCacheKey);
+      if (cachedRouterFallback) {
+        return success(
+          `Found ${cachedRouterFallback.results.length} cached results for "${input.query}"`,
+          wrapWebSearchOutput(cachedRouterFallback),
+        );
+      }
+    }
+  }
+  const searchRouter = createSearchRouter(searchEnv);
+
+  try {
+    // Race search against context abort signal for cancellation support
+    let results: Awaited<ReturnType<typeof searchRouter.search>>;
+    if (ctx.abortSignal) {
+      const abortPromise = new Promise<never>((_resolve, reject) => {
+        if (ctx.abortSignal!.aborted) {
+          reject(new DOMException("The operation was aborted", "AbortError"));
+          return;
+        }
+        ctx.abortSignal!.addEventListener(
+          "abort",
+          () => reject(new DOMException("The operation was aborted", "AbortError")),
+          { once: true },
+        );
+      });
+      results = await Promise.race([searchRouter.search(input.query, searchOptions), abortPromise]);
+    } else {
+      results = await searchRouter.search(input.query, searchOptions);
+    }
+
+    // Normalize results to WebSearchResult shape (cache raw; wrap at return-time)
+    const webResults: WebSearchResult[] = results.map((r) => ({
+      title: r.title,
+      url: r.url,
+      content: r.content,
+      score: r.score,
+    }));
+
+    const output: WebSearchOutput = { query: input.query, results: webResults };
+    searchCache.set(routerCacheKey, output);
+
+    return success(
+      `Found ${webResults.length} results for "${input.query}"`,
+      wrapWebSearchOutput(output),
+    );
+  } catch (err) {
+    if (ctx.abortSignal?.aborted) {
+      return fail("Web search cancelled");
+    }
+    return fail(`Web search failed: ${getErrorMessage(err)}`);
+  }
+}
+
+// ============================================================================
+// Web Fetch
+// ============================================================================
+
+export interface WebFetchInput {
+  /** URL to fetch */
+  url: string;
+  /** Response format: 'text', 'html', or 'json' */
+  format?: "text" | "html" | "json";
+  /** Custom headers to include in the request */
+  headers?: Record<string, string>;
+  /** Request timeout in milliseconds (default: 30000) */
+  timeoutMs?: number;
+  /** Maximum response size in bytes (default: 1MB) */
+  maxSizeBytes?: number;
+}
+
+export interface WebFetchOutput {
+  content: unknown;
+  status: number;
+  contentType?: string;
+  fromCache: boolean;
+  fetchedAt: string;
+  finalUrl: string;
+  contentBytes: number;
+  truncated: boolean;
+}
+
+function wrapWebFetchOutput(output: WebFetchOutput): WebFetchOutput {
+  if (typeof output.content !== "string") {
+    return output;
+  }
+  return {
+    ...output,
+    content: ensureWrappedExternalContent(output.content, "web_fetch"),
+  };
+}
+
+function markFetchOutputFromCache(cached: CachedFetchOutput): WebFetchOutput {
+  return {
+    ...cached,
+    fromCache: true,
+  };
+}
+
+function normalizeRequestHeaders(
+  headers: Record<string, string> | undefined,
+): Array<[string, string]> {
+  if (!headers) {
+    return [];
+  }
+  return Object.entries(headers)
+    .map(([name, value]) => [name.trim().toLowerCase(), value.trim()] as [string, string])
+    .sort(([left], [right]) => left.localeCompare(right));
+}
+
+function hashRequestHeaders(headers: Record<string, string> | undefined): string {
+  const normalizedHeaders = normalizeRequestHeaders(headers);
+  if (normalizedHeaders.length === 0) {
+    return "none";
+  }
+  return createHash("sha256").update(JSON.stringify(normalizedHeaders)).digest("hex");
+}
+
+function createFetchCacheKey({
+  url,
+  format,
+  headers,
+  timeoutMs,
+  maxSizeBytes,
+}: {
+  url: string;
+  format: "text" | "html" | "json";
+  headers: Record<string, string> | undefined;
+  timeoutMs: number;
+  maxSizeBytes: number;
+}): string {
+  return `fetch:${url}:${format}:headers=${hashRequestHeaders(headers)}:maxSizeBytes=${maxSizeBytes}:timeoutMs=${timeoutMs}`;
+}
+
+/**
+ * Fetches content from a URL with retry resilience, caching, and security wrapping.
+ * Uses fetchWithRetry for automatic retry on transient failures (429, 5xx, ECONNRESET).
+ * Results are cached via LRU+TTL cache for 15 minutes.
+ */
+export async function executeWebFetch(input: WebFetchInput, ctx: ToolContext): Promise<ToolResult> {
+  // Normalize GitHub blob URLs to raw content URLs before fetching
+  const url = normalizeGitHubUrl(input.url);
+
+  // Validate URL structure. DNS/SSRF safety is enforced by fetchWithSsrf
+  // so validation and fetch share one trust boundary.
+  const urlError = validateUrlStructure(url);
+  if (urlError) {
+    return fail(urlError);
+  }
+
+  const format = input.format ?? "text";
+  const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxSizeBytes = input.maxSizeBytes ?? FETCH_MAX_SIZE_BYTES;
+
+  // Check cache first (use normalized URL + request variants to avoid collisions)
+  const cacheKey = createFetchCacheKey({
+    url,
+    format,
+    headers: input.headers,
+    timeoutMs,
+    maxSizeBytes,
+  });
+  const cached = fetchCache.get(cacheKey);
+  if (cached) {
+    return success(
+      `Fetched ${input.url} (cached)`,
+      wrapWebFetchOutput(markFetchOutputFromCache(cached)),
+    );
+  }
+
+  const { controller, timeoutId } = createTimeoutController(timeoutMs);
+
+  // Forward context abort signal to our controller
+  const unlinkAbort = linkAbortSignal(ctx.abortSignal, controller);
+
+  try {
+    const fetchOptions: RequestInit = {
+      headers: input.headers ?? {},
+      signal: controller.signal,
+      redirect: "manual",
+    };
+
+    // Use DNS-pinned SSRF fetch wrapper with transient retry support.
+    const initialResponse = await fetchWithSsrf(url, fetchOptions, {
+      maxAttempts: 2,
+    });
+
+    // Follow redirects manually and keep each hop on the same DNS-pinned path.
+    const response = await followRedirects(initialResponse, fetchOptions, {
+      baseUrl: url,
+      fetchFn: (redirectUrl, redirectInit) =>
+        fetchWithSsrf(redirectUrl, redirectInit, { maxAttempts: 2 }),
+      validateRedirectUrl: validateUrlStructure,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      await discardResponseBody(response);
+      unlinkAbort();
+      return fail(`HTTP error: ${response.status} ${response.statusText}`, {
+        status: response.status,
+        statusText: response.statusText,
+      });
+    }
+
+    // Check Content-Length header for size limit
+    const contentLength = response.headers.get("Content-Length");
+    if (contentLength) {
+      const size = parseInt(contentLength, 10);
+      if (!isNaN(size) && size > maxSizeBytes) {
+        await discardResponseBody(response);
+        unlinkAbort();
+        return fail(`Response too large: ${size} bytes exceeds maximum of ${maxSizeBytes} bytes`);
+      }
+    }
+
+    const contentType = response.headers.get("Content-Type") ?? undefined;
+    let content: unknown;
+
+    // Use streaming reader to enforce size limit even for chunked responses
+    let text: string;
+    let contentBytes = 0;
+    try {
+      const result = await readResponseWithLimit(response, maxSizeBytes);
+      text = result.text;
+      contentBytes = result.contentBytes;
+      if (result.truncated) {
+        unlinkAbort();
+        return fail(`Response body exceeds maximum size of ${maxSizeBytes} bytes`);
+      }
+    } catch (sizeErr) {
+      unlinkAbort();
+      return fail(getErrorMessage(sizeErr));
+    }
+
+    if (format === "json") {
+      const parsed = safeParseJson(text, JsonFetchContentSchema);
+      if (!parsed.ok) {
+        unlinkAbort();
+        return fail(`Failed to parse JSON response (${parsed.reason})`);
+      }
+      content = parsed.data;
+    } else {
+      content = text;
+    }
+
+    const output: WebFetchOutput = {
+      content,
+      status: response.status,
+      contentType,
+      fromCache: false,
+      fetchedAt: new Date().toISOString(),
+      finalUrl: response.url || url,
+      contentBytes,
+      truncated: false,
+    };
+    fetchCache.set(cacheKey, output);
+
+    unlinkAbort();
+    return success(`Fetched ${input.url} (${response.status})`, wrapWebFetchOutput(output));
+  } catch (err) {
+    clearTimeout(timeoutId);
+    unlinkAbort();
+    if (
+      err instanceof Error &&
+      (err.name === "AbortError" || (err instanceof DOMException && err.name === "AbortError"))
+    ) {
+      if (ctx.abortSignal?.aborted) {
+        return fail("Request cancelled");
+      }
+      return fail(`Request timed out after ${timeoutMs}ms`);
+    }
+    return fail(getErrorMessage(err));
+  }
+}
+
+// ============================================================================
+// Browse
+// ============================================================================
+
+/** Default timeout for browsing in milliseconds */
+const BROWSE_TIMEOUT_MS = 30_000;
+
+/** Maximum content length returned by browse (characters) — increased from 10K to 50K */
+const BROWSE_MAX_CONTENT_LENGTH = 50_000;
+
+export interface BrowseInput {
+  /** URL to browse */
+  url: string;
+  /** Timeout in milliseconds (default: 30000) */
+  timeoutMs?: number;
+}
+
+export interface BrowseOutput {
+  url: string;
+  title: string;
+  content: string;
+  fromCache: boolean;
+  fetchedAt: string;
+  finalUrl: string;
+  contentBytes: number;
+  truncated: boolean;
+}
+
+function wrapBrowseOutput(output: BrowseOutput): BrowseOutput {
+  return {
+    ...output,
+    content: ensureWrappedExternalContent(output.content, "browse"),
+  };
+}
+
+function markBrowseOutputFromCache(cached: CachedBrowseOutput): BrowseOutput {
+  return {
+    ...cached,
+    fromCache: true,
+  };
+}
+
+/**
+ * Browses a URL by fetching its HTML content and extracting Markdown.
+ * Uses Readability.js + Turndown for article extraction with three-tier fallback.
+ * Supports GitHub URL normalization, retry on transient failures, LRU+TTL caching,
+ * and nonce-based external content wrapping.
+ */
+export async function executeBrowse(input: BrowseInput, ctx: ToolContext): Promise<ToolResult> {
+  // Validate URL
+  if (!input.url) {
+    return fail("URL is required for browse");
+  }
+
+  // Normalize GitHub blob URLs to raw content URLs
+  const url = normalizeGitHubUrl(input.url);
+
+  // Check cache (using normalized URL as key)
+  const cached = browseCache.get(url);
+  if (cached) {
+    return success(
+      `Browsed ${input.url} (cached)`,
+      wrapBrowseOutput(markBrowseOutputFromCache(cached)),
+    );
+  }
+
+  const urlError = validateUrlStructure(url);
+  if (urlError) {
+    return fail(urlError);
+  }
+
+  const timeoutMs = input.timeoutMs ?? BROWSE_TIMEOUT_MS;
+  const { controller, timeoutId } = createTimeoutController(timeoutMs);
+
+  // Forward context abort signal to our controller
+  const unlinkAbort = linkAbortSignal(ctx.abortSignal, controller);
+
+  try {
+    const fetchOptions: RequestInit = {
+      headers: {
+        "User-Agent": getUserAgent(),
+        Accept: "text/html, application/xhtml+xml, */*",
+      },
+      signal: controller.signal,
+      redirect: "manual",
+    };
+
+    // Use DNS-pinned SSRF fetch wrapper with transient retry support.
+    const initialResponse = await fetchWithSsrf(url, fetchOptions, {
+      maxAttempts: 2,
+    });
+
+    // Follow redirects manually and keep each hop on the same DNS-pinned path.
+    const response = await followRedirects(initialResponse, fetchOptions, {
+      baseUrl: url,
+      fetchFn: (redirectUrl, redirectInit) =>
+        fetchWithSsrf(redirectUrl, redirectInit, { maxAttempts: 2 }),
+      validateRedirectUrl: validateUrlStructure,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      await discardResponseBody(response);
+      unlinkAbort();
+      return fail(`HTTP error fetching ${input.url}: ${response.status} ${response.statusText}`);
+    }
+
+    // Truncate large pages gracefully — content gets reduced to 50K chars by
+    // Readability+Turndown anyway, so the first 2MB of HTML is plenty.
+    const {
+      text: html,
+      truncated: responseTruncated,
+      contentBytes,
+    } = await readResponseWithLimit(response, BROWSE_MAX_SIZE_BYTES, {
+      truncate: true,
+    });
+
+    // Extract content using Content-Type-aware extraction pipeline.
+    const { title, content: extractedContent } = await extractFromResponse(
+      html,
+      url,
+      response.headers.get("Content-Type"),
+    );
+
+    // Truncate to 50K character limit
+    // extractContent() internally truncates to MAX_CONTENT_LENGTH (50K),
+    // so content that was originally longer arrives here at exactly 50K.
+    // Use >= to detect content that hit the internal limit.
+    const contentLimitReached = extractedContent.length >= BROWSE_MAX_CONTENT_LENGTH;
+    const truncated = contentLimitReached || responseTruncated;
+    const truncatedContent = contentLimitReached
+      ? extractedContent.slice(0, BROWSE_MAX_CONTENT_LENGTH) + "\n\n[Content truncated]"
+      : responseTruncated
+        ? extractedContent + "\n\n[Content truncated]"
+        : extractedContent;
+
+    const output: BrowseOutput = {
+      url: input.url,
+      title,
+      content: truncatedContent,
+      fromCache: false,
+      fetchedAt: new Date().toISOString(),
+      finalUrl: response.url || url,
+      contentBytes,
+      truncated,
+    };
+    browseCache.set(url, output);
+
+    unlinkAbort();
+    return success(`Browsed ${input.url}`, wrapBrowseOutput(output));
+  } catch (err) {
+    clearTimeout(timeoutId);
+    unlinkAbort();
+    if (err instanceof Error && err.name === "AbortError") {
+      if (ctx.abortSignal?.aborted) {
+        return fail("Browse cancelled");
+      }
+      return fail(`Browse timed out after ${timeoutMs}ms: ${input.url}`);
+    }
+    return fail(`Browse failed: ${getErrorMessage(err)}`);
+  }
+}