@dbx-tools/appkit-web-search 0.9.131 → 0.9.136

package/package.json

@@ -27,12 +27,12 @@
   },
   "dependencies": {
     "@databricks/appkit": "0.81.0",
-    "@dbx-tools/appkit": "^0.9.131",
-    "@dbx-tools/core": "^0.9.131",
-    "@dbx-tools/model": "^0.9.131",
-    "@dbx-tools/path": "^0.9.131",
-    "@dbx-tools/shared-core": "^0.9.131",
-    "@dbx-tools/shared-model": "^0.9.131",
+    "@dbx-tools/appkit": "^0.9.136",
+    "@dbx-tools/core": "^0.9.136",
+    "@dbx-tools/model": "^0.9.136",
+    "@dbx-tools/path": "^0.9.136",
+    "@dbx-tools/shared-core": "^0.9.136",
+    "@dbx-tools/shared-model": "^0.9.136",
     "@mastra/core": "1.71.0",
     "cheerio": "^1.2.0",
     "entities": "^4.5.0",
@@ -106,7 +106,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.131",
+  "version": "0.9.136",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [

package/src/fetch.ts

@@ -20,10 +20,43 @@ import { gotScraping } from "got-scraping";
 import { assertFetchUrlAllowed } from "./_fetch-url.ts";
 import { toCallSettings, webFetchExecuteDefaults } from "./defaults.ts";
 import { decodeHtmlEntities, htmlToText } from "./html-text.ts";
-import { executeRead, toWebSearchRuntime, type WebSearchRuntimeInput } from "./runtime.ts";
+import {
+  executeRead,
+  toWebSearchRuntime,
+  type WebSearchRuntime,
+  type WebSearchRuntimeInput,
+} from "./runtime.ts";
 import type { WebFetchRequest, WebFetchResult } from "./schema.ts";
 
 const logger = log.logger("web-search/fetch");
+const DEFAULT_IMAGE_MAX_BYTES = 5 * 1024 * 1024;
+const DEFAULT_ASSET_PAGE_MAX_LENGTH = 1_500_000;
+
+/** Input for a policy-checked HTML fetch used by in-process asset discovery. */
+export interface WebAssetPageFetchRequest {
+  /** Public HTTPS page URL. */
+  url: string;
+  /** Maximum returned markup length. Defaults to 1.5 million characters. */
+  maxLength?: number;
+}
+
+/** Input for a policy-checked binary image fetch. */
+export interface WebImageFetchRequest {
+  /** Public HTTPS image URL. */
+  url: string;
+  /** Maximum accepted response size. Defaults to 5 MiB. */
+  maxBytes?: number;
+}
+
+/** Binary image fetched through the web-search runtime's URL policy. */
+export interface WebImageFetchResult {
+  /** Final URL after redirects. */
+  url: string;
+  /** Image media type returned by the server. */
+  contentType: string;
+  /** Fetched image bytes. */
+  data: Uint8Array;
+}
 
 /** The slice of a got-scraping response this module reads. */
 interface FetchedPage {
@@ -46,38 +79,26 @@ function truncate(text: string, max: number): { content: string; truncated: bool
   return { content: text.slice(0, max), truncated: true };
 }
 
-/**
- * Fetch a single URL and return its content in the requested format.
- *
- * Throws when the URL is not permitted by the allow-list (the visible,
- * correctable failure the design calls for on the fetch path). The request's
- * `maxLength` narrows (never widens) the plugin's `fetchMaxLength` cap.
- * `signal` cancels the in-flight fetch.
- */
-export async function runWebFetch(
-  request: WebFetchRequest,
-  runtimeOrConfig: WebSearchRuntimeInput,
+/** Fetch and cache one raw page before caller-specific output reduction. */
+async function fetchPage(
+  requestUrl: string,
+  runtime: WebSearchRuntime,
   signal?: AbortSignal,
-): Promise<WebFetchResult> {
-  const runtime = toWebSearchRuntime(runtimeOrConfig);
+): Promise<FetchedPage> {
   const { config } = runtime;
-  await assertFetchUrlAllowed(request.url, config.allowList);
-  const cap = Math.min(request.maxLength ?? config.fetchMaxLength, config.fetchMaxLength);
-
-  // The response is cached before the format reduction, so the same page read
-  // as text and as html shares one network round trip.
+  await assertFetchUrlAllowed(requestUrl, config.allowList);
   const page = await executeRead(
     runtime,
     "page-fetch",
     toCallSettings(webFetchExecuteDefaults, config.timeoutMs, [
       "web-search",
       "fetch",
-      request.url,
+      requestUrl,
       ...config.allowList.patterns,
     ]),
     async (executeSignal): Promise<FetchedPage> => {
       const response = await gotScraping({
-        url: request.url,
+        url: requestUrl,
         // Bun's node:http2 reports default-port origins with :443 while
         // http2-wrapper compares them against URL-normalized origins.
         http2: false,
@@ -96,7 +117,7 @@ export async function runWebFetch(
         ...(executeSignal ? { signal: executeSignal } : {}),
       });
       return {
-        url: response.url ?? request.url,
+        url: response.url ?? requestUrl,
         statusCode: response.statusCode,
         contentType: response.headers["content-type"],
         body: typeof response.body === "string" ? response.body : String(response.body ?? ""),
@@ -105,6 +126,26 @@ export async function runWebFetch(
     signal,
   );
   await assertFetchUrlAllowed(page.url, config.allowList);
+  return page;
+}
+
+/**
+ * Fetch a single URL and return its content in the requested format.
+ *
+ * Throws when the URL is not permitted by the allow-list (the visible,
+ * correctable failure the design calls for on the fetch path). The request's
+ * `maxLength` narrows (never widens) the plugin's `fetchMaxLength` cap.
+ * `signal` cancels the in-flight fetch.
+ */
+export async function runWebFetch(
+  request: WebFetchRequest,
+  runtimeOrConfig: WebSearchRuntimeInput,
+  signal?: AbortSignal,
+): Promise<WebFetchResult> {
+  const runtime = toWebSearchRuntime(runtimeOrConfig);
+  const { config } = runtime;
+  const cap = Math.min(request.maxLength ?? config.fetchMaxLength, config.fetchMaxLength);
+  const page = await fetchPage(request.url, runtime, signal);
 
   const isHtml = !page.contentType || /html|xml/i.test(page.contentType);
   const rawContent = request.format === "html" || !isHtml ? page.body : htmlToText(page.body);
@@ -128,3 +169,91 @@ export async function runWebFetch(
     truncated,
   };
 }
+
+/**
+ * Fetch bounded raw markup for deterministic in-process asset discovery.
+ *
+ * This does not widen the model-facing `web_fetch` cap.
+ */
+export async function runWebAssetPageFetch(
+  request: WebAssetPageFetchRequest,
+  runtimeOrConfig: WebSearchRuntimeInput,
+  signal?: AbortSignal,
+): Promise<WebFetchResult> {
+  const runtime = toWebSearchRuntime(runtimeOrConfig);
+  const cap = Math.min(
+    Math.max(1, request.maxLength ?? DEFAULT_ASSET_PAGE_MAX_LENGTH),
+    DEFAULT_ASSET_PAGE_MAX_LENGTH,
+  );
+  const page = await fetchPage(request.url, runtime, signal);
+  const { content, truncated } = truncate(page.body, cap);
+  const title = extractTitle(page.body);
+  return {
+    url: page.url,
+    status: page.statusCode,
+    ...(page.contentType ? { contentType: page.contentType } : {}),
+    ...(title ? { title } : {}),
+    content,
+    truncated,
+  };
+}
+
+/** Fetch one public image while preserving URL policy, timeout, and redirect checks. */
+export async function runWebImageFetch(
+  request: WebImageFetchRequest,
+  runtimeOrConfig: WebSearchRuntimeInput,
+  signal?: AbortSignal,
+): Promise<WebImageFetchResult> {
+  const runtime = toWebSearchRuntime(runtimeOrConfig);
+  const { config } = runtime;
+  const maxBytes = Math.max(1, request.maxBytes ?? DEFAULT_IMAGE_MAX_BYTES);
+  await assertFetchUrlAllowed(request.url, config.allowList);
+  const page = await executeRead(
+    runtime,
+    "image-fetch",
+    {
+      default: {
+        cache: { enabled: false },
+        retry: { enabled: true, attempts: 2 },
+        timeout: config.timeoutMs,
+      },
+    },
+    async (executeSignal) => {
+      const response = await gotScraping({
+        url: request.url,
+        responseType: "buffer",
+        http2: false,
+        timeout: { request: config.timeoutMs },
+        throwHttpErrors: true,
+        followRedirect: true,
+        hooks: {
+          beforeRequest: [
+            async (options) => {
+              await assertFetchUrlAllowed(String(options.url), config.allowList);
+            },
+          ],
+        },
+        ...(executeSignal ? { signal: executeSignal } : {}),
+      });
+      const contentType = String(response.headers["content-type"] ?? "")
+        .split(";")[0]!
+        .trim()
+        .toLowerCase();
+      if (!contentType.startsWith("image/")) {
+        throw new TypeError(`Expected an image response, received ${contentType || "unknown"}`);
+      }
+      if (response.body.byteLength > maxBytes) {
+        throw new RangeError(`Image response exceeds ${maxBytes} bytes`);
+      }
+      return {
+        url: response.url ?? request.url,
+        contentType,
+        data: new Uint8Array(response.body),
+      };
+    },
+    signal,
+    false,
+  );
+  await assertFetchUrlAllowed(page.url, config.allowList);
+  return page;
+}

package/src/plugin.ts

@@ -31,7 +31,14 @@ import {
   WEB_SEARCH_CONFIG_SCHEMA,
   type WebSearchPluginConfig,
 } from "./config.ts";
-import { runWebFetch } from "./fetch.ts";
+import {
+  runWebAssetPageFetch,
+  runWebFetch,
+  runWebImageFetch,
+  type WebAssetPageFetchRequest,
+  type WebImageFetchRequest,
+  type WebImageFetchResult,
+} from "./fetch.ts";
 import { createWebSearchRuntime, type WebSearchRuntime } from "./runtime.ts";
 import {
   webFetchRequestSchema,
@@ -230,6 +237,16 @@ export class WebSearchPlugin extends ToolRegistryPlugin<WebSearchPluginConfig> {
        */
       fetch: (request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult> =>
         this.fetch(request, signal),
+      /** Fetch expanded HTML for in-process asset discovery. */
+      fetchAssetPage: (
+        request: WebAssetPageFetchRequest,
+        signal?: AbortSignal,
+      ): Promise<WebFetchResult> => runWebAssetPageFetch(request, this.runtime, signal),
+      /** Fetch one image for in-process visual research. */
+      fetchImage: (
+        request: WebImageFetchRequest,
+        signal?: AbortSignal,
+      ): Promise<WebImageFetchResult> => runWebImageFetch(request, this.runtime, signal),
     };
   }
 

package/src/runtime.ts

@@ -37,6 +37,10 @@ export interface WebSearchRuntime {
   execute: WebSearchExecutor;
   /** Provider-family cooldown deadlines learned from workspace failures. */
   familyCooldowns: Map<policy.ModelFamily, number>;
+  /** Provider families that completed a native search successfully. */
+  availableFamilies: Set<policy.ModelFamily>;
+  /** First native request currently establishing one family's availability. */
+  familyProbes: Map<policy.ModelFamily, Promise<void>>;
 }
 
 /** Runtime-aware operation input, retaining resolved-config compatibility. */
@@ -54,7 +58,13 @@ export function createWebSearchRuntime(
   overrides?: WebSearchPluginConfig,
   execute: WebSearchExecutor = directExecute,
 ): WebSearchRuntime {
-  return { config: resolveWebSearchConfig(overrides), execute, familyCooldowns: new Map() };
+  return {
+    config: resolveWebSearchConfig(overrides),
+    execute,
+    familyCooldowns: new Map(),
+    availableFamilies: new Set(),
+    familyProbes: new Map(),
+  };
 }
 
 /** Build an isolated runtime from config that has already been resolved. */
@@ -62,7 +72,13 @@ export function createResolvedWebSearchRuntime(
   config: ResolvedWebSearchConfig,
   execute: WebSearchExecutor = directExecute,
 ): WebSearchRuntime {
-  return { config, execute, familyCooldowns: new Map() };
+  return {
+    config,
+    execute,
+    familyCooldowns: new Map(),
+    availableFamilies: new Set(),
+    familyProbes: new Map(),
+  };
 }
 
 /** Normalize an explicit runtime or legacy resolved config for one operation. */
@@ -91,10 +107,11 @@ export async function executeRead<T>(
   settings: WebSearchExecutionSettings,
   fn: (signal?: AbortSignal) => Promise<T>,
   signal?: AbortSignal,
+  logFailure = true,
 ): Promise<T> {
   return pluginExecution.runPluginExecution({
     plugin: "web-search",
-    logger,
+    logger: logFailure ? logger : { warn() {} },
     operation,
     settings,
     execute: runtime.execute,

package/src/search.ts

@@ -231,25 +231,22 @@ async function postServing(
         const responseBody = await response.text();
         const model =
           object.isRecord(body) && typeof body.model === "string" ? body.model : undefined;
-        logger.error("serving-request-rejected", {
-          model,
-          api: url.endsWith("/responses") ? "responses" : "chat",
-          url,
-          status: response.status,
-          responseBody,
-        });
-        if (
+        const crossRegionDisabled =
           response.status === 400 &&
           model &&
           policy.modelFamily(model) === policy.ModelFamily.Gemini &&
-          GEMINI_CROSS_REGION_DISABLED.test(responseBody)
-        ) {
+          GEMINI_CROSS_REGION_DISABLED.test(responseBody);
+        if (crossRegionDisabled) {
           const expiresAt = Date.now() + GEMINI_CROSS_REGION_COOLDOWN_MS;
           runtime.familyCooldowns.set(policy.ModelFamily.Gemini, expiresAt);
-          logger.warn("provider-family-suppressed", {
-            family: policy.ModelFamily.Gemini,
-            reason: "cross-region-disabled",
-            expiresAt: new Date(expiresAt).toISOString(),
+          runtime.availableFamilies.delete(policy.ModelFamily.Gemini);
+        } else {
+          logger.error("serving-request-rejected", {
+            model,
+            api: url.endsWith("/responses") ? "responses" : "chat",
+            url,
+            status: response.status,
+            responseBody,
           });
         }
         // Load-shedding and server faults are worth another attempt; a 4xx is
@@ -268,6 +265,7 @@ async function postServing(
         : response.json();
     },
     signal,
+    false,
   );
   return object.isRecord(payload) ? payload : {};
 }
@@ -456,29 +454,95 @@ export async function runWebSearch(
     );
   }
 
+  return runSelectedWebSearch(request, runtime, ctx, endpoint, signal, writeProgress);
+}
+
+/** Run one selected family after its first request establishes availability. */
+async function runSelectedWebSearch(
+  request: WebSearchRequest,
+  runtime: WebSearchRuntime,
+  ctx: WebSearchContext,
+  endpoint: ServingEndpointSummary,
+  signal?: AbortSignal,
+  writeProgress?: ProgressWriter,
+): Promise<WebSearchResult> {
+  const family = endpointFamily(endpoint);
+  if (!family || runtime.availableFamilies.has(family)) {
+    try {
+      return await runNativeWebSearch(request, runtime, ctx, endpoint, signal, writeProgress);
+    } catch (error) {
+      return runSearchFallback(request, runtime, ctx, endpoint, error, signal, writeProgress);
+    }
+  }
+
+  const activeProbe = runtime.familyProbes.get(family);
+  if (activeProbe) {
+    signal?.throwIfAborted();
+    await activeProbe;
+    signal?.throwIfAborted();
+    return runWebSearch(request, runtime, ctx, signal, writeProgress);
+  }
+
+  let releaseProbe!: () => void;
+  const probe = new Promise<void>((resolve) => {
+    releaseProbe = resolve;
+  });
+  runtime.familyProbes.set(family, probe);
+
+  if (runtime.availableFamilies.has(family) || activeFamilyCooldowns(runtime).has(family)) {
+    runtime.familyProbes.delete(family);
+    releaseProbe();
+    return runWebSearch(request, runtime, ctx, signal, writeProgress);
+  }
+
+  let failure: unknown;
   try {
-    return await runNativeWebSearch(request, runtime, ctx, endpoint, signal, writeProgress);
+    const result = await runNativeWebSearch(request, runtime, ctx, endpoint, signal, writeProgress);
+    runtime.availableFamilies.add(family);
+    return result;
   } catch (error) {
-    if (
-      endpointFamily(endpoint) !== policy.ModelFamily.Gemini ||
-      !activeFamilyCooldowns(runtime).has(policy.ModelFamily.Gemini)
-    ) {
-      throw error;
-    }
-    const fallback = await resolveWebSearchModel(ctx, runtime, request.model);
-    if (!fallback) {
-      if (config.scrapeFallback) {
-        logger.info("gemini-unavailable:scrape-fallback", { query: request.query });
-        return runScrapeSearch(request, runtime, signal);
-      }
-      throw error;
+    failure = error;
+  } finally {
+    if (runtime.familyProbes.get(family) === probe) runtime.familyProbes.delete(family);
+    releaseProbe();
+  }
+  return runSearchFallback(request, runtime, ctx, endpoint, failure, signal, writeProgress);
+}
+
+/** Resolve a cached family failure to another model or the scrape fallback. */
+async function runSearchFallback(
+  request: WebSearchRequest,
+  runtime: WebSearchRuntime,
+  ctx: WebSearchContext,
+  endpoint: ServingEndpointSummary,
+  error: unknown,
+  signal?: AbortSignal,
+  writeProgress?: ProgressWriter,
+): Promise<WebSearchResult> {
+  if (
+    endpointFamily(endpoint) !== policy.ModelFamily.Gemini ||
+    !activeFamilyCooldowns(runtime).has(policy.ModelFamily.Gemini)
+  ) {
+    throw error;
+  }
+  const fallback = await resolveWebSearchModel(ctx, runtime, request.model);
+  if (!fallback) {
+    if (runtime.config.scrapeFallback) {
+      logger.warn("web-search-model-fallback", {
+        failedModel: endpoint.name,
+        fallback: "scrape",
+        reason: "cross-region-disabled",
+      });
+      return runScrapeSearch(request, runtime, signal);
     }
-    logger.info("gemini-unavailable:model-fallback", {
-      failedModel: endpoint.name,
-      fallbackModel: fallback.name,
-    });
-    return runNativeWebSearch(request, runtime, ctx, fallback, signal, writeProgress);
+    throw error;
   }
+  logger.warn("web-search-model-fallback", {
+    failedModel: endpoint.name,
+    fallbackModel: fallback.name,
+    reason: "cross-region-disabled",
+  });
+  return runSelectedWebSearch(request, runtime, ctx, fallback, signal, writeProgress);
 }
 
 /** Execute one native provider request against an already-selected endpoint. */