@dbx-tools/appkit-web-search 0.9.132 → 0.9.138

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. */