@dbx-tools/appkit-web-search 0.9.154 → 0.9.158

package/src/config.ts

@@ -45,9 +45,9 @@
  */
 
 import { ConfigurationError, type BasePluginConfig } from "@databricks/appkit";
-import { configUtils } from "@dbx-tools/core";
-import { modelCatalog } from "@dbx-tools/model";
-import { json, object, type OneOrMany, stringUtils } from "@dbx-tools/shared-core";
+import { configUtils, text, ENV_ONLY, boolean, positiveNumber, positiveInt } from "@dbx-tools/core";
+import { DEFAULT_FUZZY_THRESHOLD } from "@dbx-tools/model";
+import { type OneOrMany, parseRecord, isRecord, trimToNull } from "@dbx-tools/shared-core";
 import type { JSONSchema7 } from "json-schema";
 import { parseAllowedUrls, toUrlAllowList, type UrlAllowList } from "./allowlist.ts";
 
@@ -297,9 +297,9 @@ export const WEB_SEARCH_CONFIG_SCHEMA: JSONSchema7 = {
  * silently leave the built-in tool specs in place, so it throws.
  */
 function parseToolsEnv(): Record<string, unknown> {
-  const raw = configUtils.text("WEB_SEARCH_TOOLS", configUtils.ENV_ONLY);
+  const raw = text("WEB_SEARCH_TOOLS", ENV_ONLY);
   if (raw === undefined) return {};
-  const parsed = json.parseRecord(raw);
+  const parsed = parseRecord(raw);
   if (!parsed) {
     throw new ConfigurationError(
       "WEB_SEARCH_TOOLS must be a JSON object mapping a provider family to its request fragment",
@@ -311,11 +311,11 @@ function parseToolsEnv(): Record<string, unknown> {
 
 /** Read the pinned endpoint id and record which source supplied it. */
 function resolveModelPin(config: WebSearchPluginConfig): { model?: string; source: ModelSource } {
-  const fromConfig = stringUtils.trimToNull(config.model);
+  const fromConfig = trimToNull(config.model);
   if (fromConfig !== null) return { model: fromConfig, source: "config" };
-  const fromModelEnv = configUtils.text(MODEL_ENV, configUtils.ENV_ONLY);
+  const fromModelEnv = text(MODEL_ENV, ENV_ONLY);
   if (fromModelEnv !== undefined) return { model: fromModelEnv, source: MODEL_ENV };
-  const fromResourceEnv = configUtils.text(SERVING_ENDPOINT_ENV, configUtils.ENV_ONLY);
+  const fromResourceEnv = text(SERVING_ENDPOINT_ENV, ENV_ONLY);
   if (fromResourceEnv !== undefined) {
     return { model: fromResourceEnv, source: SERVING_ENDPOINT_ENV };
   }
@@ -330,7 +330,7 @@ function resolveUrlPolicy(
   configured: UrlPolicyMode | undefined,
   patterns: readonly string[],
 ): UrlPolicyMode {
-  const raw = configured ?? configUtils.text("WEB_SEARCH_URL_POLICY", configUtils.ENV_ONLY);
+  const raw = configured ?? text("WEB_SEARCH_URL_POLICY", ENV_ONLY);
   if (raw === undefined) return patterns.length > 0 ? "allowlist" : "unrestricted";
   if (raw !== "allowlist" && raw !== "unrestricted") {
     throw new ConfigurationError(
@@ -362,7 +362,7 @@ function resolveUrlPolicy(
 export function toApprovalPolicy(gate: ApprovalGate | ApprovalPolicy | undefined): ApprovalPolicy {
   if (gate === undefined || gate === false) return { mode: "none" };
   if (gate === true) return { mode: "always" };
-  if (object.isRecord(gate) && "mode" in gate) {
+  if (isRecord(gate) && "mode" in gate) {
     if (gate.mode === "urls") {
       const patterns = parseAllowedUrls([...gate.patterns]);
       return patterns.length > 0 ? { mode: "urls", patterns } : { mode: "none" };
@@ -388,7 +388,7 @@ export function resolveWebSearchConfig(
   config: WebSearchPluginConfig = {},
 ): ResolvedWebSearchConfig {
   const patterns = parseAllowedUrls(
-    config.allowedUrls ?? configUtils.text("WEB_SEARCH_ALLOWED_URLS", configUtils.ENV_ONLY),
+    config.allowedUrls ?? text("WEB_SEARCH_ALLOWED_URLS", ENV_ONLY),
   );
   const urlPolicy = resolveUrlPolicy(config.urlPolicy, patterns);
   const { model, source } = resolveModelPin(config);
@@ -396,45 +396,34 @@ export function resolveWebSearchConfig(
     config.modelFallbacks,
     "WEB_SEARCH_MODEL_FALLBACKS",
     undefined,
-    configUtils.ENV_ONLY,
+    ENV_ONLY,
   );
   return {
     ...(model ? { model } : {}),
     modelSource: source,
     modelFallbacks: fallbacks.length > 0 ? fallbacks : DEFAULT_MODEL_FALLBACKS,
     webSearchTools: { ...parseToolsEnv(), ...(config.webSearchTools ?? {}) },
-    fuzzy:
-      configUtils.boolean(config.modelFuzzyMatch, "WEB_SEARCH_FUZZY", configUtils.ENV_ONLY) ?? true,
-    fuzzyThreshold: configUtils.positiveNumber(
+    fuzzy: boolean(config.modelFuzzyMatch, "WEB_SEARCH_FUZZY", ENV_ONLY) ?? true,
+    fuzzyThreshold: positiveNumber(
       config.modelFuzzyThreshold,
       "WEB_SEARCH_FUZZY_THRESHOLD",
-      modelCatalog.DEFAULT_FUZZY_THRESHOLD,
-      configUtils.ENV_ONLY,
+      DEFAULT_FUZZY_THRESHOLD,
+      ENV_ONLY,
     ),
-    maxCitations: configUtils.positiveInt(
+    maxCitations: positiveInt(
       config.maxCitations,
       "WEB_SEARCH_MAX_CITATIONS",
       DEFAULT_MAX_CITATIONS,
-      configUtils.ENV_ONLY,
+      ENV_ONLY,
     ),
-    fetchMaxLength: configUtils.positiveInt(
+    fetchMaxLength: positiveInt(
       config.fetchMaxLength,
       "WEB_SEARCH_FETCH_MAX_LENGTH",
       DEFAULT_FETCH_MAX_LENGTH,
-      configUtils.ENV_ONLY,
+      ENV_ONLY,
     ),
-    timeoutMs: configUtils.positiveInt(
-      config.timeoutMs,
-      "WEB_SEARCH_TIMEOUT_MS",
-      DEFAULT_TIMEOUT_MS,
-      configUtils.ENV_ONLY,
-    ),
-    scrapeFallback:
-      configUtils.boolean(
-        config.scrapeFallback,
-        "WEB_SEARCH_SCRAPE_FALLBACK",
-        configUtils.ENV_ONLY,
-      ) ?? true,
+    timeoutMs: positiveInt(config.timeoutMs, "WEB_SEARCH_TIMEOUT_MS", DEFAULT_TIMEOUT_MS, ENV_ONLY),
+    scrapeFallback: boolean(config.scrapeFallback, "WEB_SEARCH_SCRAPE_FALLBACK", ENV_ONLY) ?? true,
     urlPolicy,
     allowList: toUrlAllowList(urlPolicy === "allowlist" ? patterns : []),
     approval: toApprovalPolicy(config.approval),

package/src/plugin.ts

@@ -23,8 +23,8 @@ import {
 } from "@databricks/appkit";
 import { defineTool, type ToolRegistry } from "@databricks/appkit/beta";
 import { ToolRegistryPlugin } from "@dbx-tools/appkit";
-import type { AgentToolExecutionContext } from "@dbx-tools/appkit/tool-provider";
-import { log, stringUtils } from "@dbx-tools/shared-core";
+import type { AgentToolExecutionContext } from "@dbx-tools/appkit";
+import { log, trimToNull } from "@dbx-tools/shared-core";
 import {
   MODEL_ENV,
   SERVING_ENDPOINT_ENV,
@@ -134,9 +134,9 @@ export class WebSearchPlugin extends ToolRegistryPlugin<WebSearchPluginConfig> {
    */
   static getResourceRequirements(config: WebSearchPluginConfig): ResourceRequirement[] {
     const pinned =
-      stringUtils.trimToNull(config.model) ??
-      stringUtils.trimToNull(process.env[MODEL_ENV]) ??
-      stringUtils.trimToNull(process.env[SERVING_ENDPOINT_ENV]);
+      trimToNull(config.model) ??
+      trimToNull(process.env[MODEL_ENV]) ??
+      trimToNull(process.env[SERVING_ENDPOINT_ENV]);
     return pinned === null ? [] : [{ ...SERVING_ENDPOINT_RESOURCE, required: true }];
   }
 

package/src/runtime.ts

@@ -9,9 +9,9 @@
  */
 
 import type { ExecutionResult } from "@databricks/appkit";
-import { pluginExecution } from "@dbx-tools/appkit";
+import { runPluginExecution } from "@dbx-tools/appkit";
 import { policy } from "@dbx-tools/model";
-import { execution, log } from "@dbx-tools/shared-core";
+import { log, directExecutor } from "@dbx-tools/shared-core";
 import {
   resolveWebSearchConfig,
   type ResolvedWebSearchConfig,
@@ -51,7 +51,7 @@ export type WebSearchRuntimeInput = WebSearchRuntime | ResolvedWebSearchConfig;
  * onto the same {@link ExecutionResult} shape so call sites branch on `ok`
  * either way.
  */
-const directExecute = execution.directExecutor<WebSearchExecutionSettings>();
+const directExecute = directExecutor<WebSearchExecutionSettings>();
 
 /** Build an isolated runtime for one plugin instance or standalone tool set. */
 export function createWebSearchRuntime(
@@ -109,7 +109,7 @@ export async function executeRead<T>(
   signal?: AbortSignal,
   logFailure = true,
 ): Promise<T> {
-  return pluginExecution.runPluginExecution({
+  return runPluginExecution({
     plugin: "web-search",
     logger: logFailure ? logger : { warn() {} },
     operation,

package/src/schema.ts

@@ -17,14 +17,14 @@
  * @module
  */
 
-import { stringUtils } from "@dbx-tools/shared-core";
+import { toDescription } from "@dbx-tools/shared-core";
 import { z } from "zod";
 
 /**
  * Description the model reads for `web_search`. Shared by the Mastra tool and
  * the AppKit tool provider so both hosts describe the tool identically.
  */
-export const WEB_SEARCH_TOOL_DESCRIPTION = stringUtils.toDescription(`
+export const WEB_SEARCH_TOOL_DESCRIPTION = toDescription(`
   Search the web for current information and get an answer synthesized from
   live results, with the sources it used. Pass a natural-language query;
   the search runs inside a web-search-capable model (chosen independently
@@ -34,7 +34,7 @@ export const WEB_SEARCH_TOOL_DESCRIPTION = stringUtils.toDescription(`
 `);
 
 /** Description the model reads for `web_fetch`. Shared like {@link WEB_SEARCH_TOOL_DESCRIPTION}. */
-export const WEB_FETCH_TOOL_DESCRIPTION = stringUtils.toDescription(`
+export const WEB_FETCH_TOOL_DESCRIPTION = toDescription(`
   Fetch a single web page and return its readable contents. Pass an
   absolute URL (including https://); set format to "html" for raw markup
   instead of extracted text. Use it to read a page returned by web_search
@@ -53,7 +53,7 @@ export const webSearchRequestSchema = z.object({
     .string()
     .optional()
     .describe(
-      stringUtils.toDescription(`
+      toDescription(`
         Optional calling-model preference. The tool always tries the highest
         web-search-capable Gemini first. When Gemini is unavailable, a matching
         GPT endpoint wins before the highest-ranked GPT fallback.
@@ -108,7 +108,7 @@ export const webFetchRequestSchema = z.object({
     .enum(["text", "html"])
     .optional()
     .describe(
-      stringUtils.toDescription(`
+      toDescription(`
         Return format: "text" (default) strips the page to readable plain
         text; "html" returns the raw response body. Prefer "text" unless you
         need the markup.

package/src/search.ts

@@ -27,10 +27,14 @@ import {
   ExecutionError,
   getExecutionContext,
 } from "@databricks/appkit";
-import type { AgentToolExecutionContext } from "@dbx-tools/appkit/tool-provider";
-import { invoke, policy, resolve, modelCatalog } from "@dbx-tools/model";
-import { log, object, stringUtils } from "@dbx-tools/shared-core";
-import { openaiChat, type ServingEndpointSummary } from "@dbx-tools/shared-model";
+import type { AgentToolExecutionContext } from "@dbx-tools/appkit";
+import { invoke, policy, selection, modelCatalog } from "@dbx-tools/model";
+import { log, isRecord, trimToEmpty } from "@dbx-tools/shared-core";
+import {
+  type ServingEndpointSummary,
+  chatContentParts,
+  chatContentToText,
+} from "@dbx-tools/shared-model";
 import { MODEL_ENV, type ResolvedWebSearchConfig } from "./config.ts";
 import { toCallSettings, webSearchExecuteDefaults } from "./defaults.ts";
 import { supportsWebSearch, webSearchProviderForFamily, webSearchToolSpec } from "./provider.ts";
@@ -46,7 +50,7 @@ import { runScrapeSearch } from "./scrape.ts";
 type WorkspaceClientLike = modelCatalog.WorkspaceClientLike & invoke.AuthenticatingClientLike;
 type ProgressWriter = NonNullable<AgentToolExecutionContext["writeProgress"]>;
 const logger = log.logger("web-search/search");
-const { lookupModels } = resolve;
+const { lookupModels } = selection;
 const { listServingEndpoints } = modelCatalog;
 
 /**
@@ -229,8 +233,7 @@ async function postServing(
       });
       if (!response.ok) {
         const responseBody = await response.text();
-        const model =
-          object.isRecord(body) && typeof body.model === "string" ? body.model : undefined;
+        const model = isRecord(body) && typeof body.model === "string" ? body.model : undefined;
         const crossRegionDisabled =
           response.status === 400 &&
           model &&
@@ -267,7 +270,7 @@ async function postServing(
     signal,
     false,
   );
-  return object.isRecord(payload) ? payload : {};
+  return isRecord(payload) ? payload : {};
 }
 
 /** Consume an OpenAI Responses SSE stream and retain its completed response. */
@@ -287,9 +290,9 @@ async function readStreamingResponse(
       .join("\n");
     if (!data || data === "[DONE]") return;
     const event = JSON.parse(data) as unknown;
-    if (!object.isRecord(event) || typeof event.type !== "string") return;
+    if (!isRecord(event) || typeof event.type !== "string") return;
     await emitWebSearchProgress(event, writeProgress);
-    if (event.type === "response.completed" && object.isRecord(event.response)) {
+    if (event.type === "response.completed" && isRecord(event.response)) {
       completed = event.response;
     }
     if (event.type === "response.failed") {
@@ -321,8 +324,8 @@ async function emitWebSearchProgress(
   event: Record<string, unknown>,
   writeProgress: ProgressWriter,
 ): Promise<void> {
-  if (event.type !== "response.output_item.done" || !object.isRecord(event.item)) return;
-  const action = object.isRecord(event.item.action) ? event.item.action : undefined;
+  if (event.type !== "response.output_item.done" || !isRecord(event.item)) return;
+  const action = isRecord(event.item.action) ? event.item.action : undefined;
   if (!action || action.type !== "search") return;
   const query = typeof action.query === "string" ? action.query : undefined;
   const queries = Array.isArray(action.queries)
@@ -364,25 +367,25 @@ function fromResponsesPayload(payload: Record<string, unknown>): {
   const citations: WebSearchCitation[] = [];
   const seen = new Set<string>();
   for (const item of output) {
-    if (!object.isRecord(item)) continue;
-    const parts = openaiChat.chatContentParts(item.content);
+    if (!isRecord(item)) continue;
+    const parts = chatContentParts(item.content);
     if (!parts) continue;
     for (const part of parts) {
-      if (!object.isRecord(part)) continue;
-      const text = stringUtils.trimToEmpty(part.text);
+      if (!isRecord(part)) continue;
+      const text = trimToEmpty(part.text);
       if (text) texts.push(text);
       const annotations = Array.isArray(part.annotations) ? part.annotations : [];
       for (const annotation of annotations) {
-        if (!object.isRecord(annotation)) continue;
-        const url = stringUtils.trimToEmpty(annotation.url);
+        if (!isRecord(annotation)) continue;
+        const url = trimToEmpty(annotation.url);
         if (!url || seen.has(url)) continue;
         seen.add(url);
-        const title = stringUtils.trimToEmpty(annotation.title);
+        const title = trimToEmpty(annotation.title);
         citations.push({ url, ...(title ? { title } : {}) });
       }
     }
   }
-  const answer = stringUtils.trimToEmpty(payload.output_text) || texts.join("\n").trim();
+  const answer = trimToEmpty(payload.output_text) || texts.join("\n").trim();
   return { answer, citations };
 }
 
@@ -398,17 +401,17 @@ function fromChatPayload(payload: Record<string, unknown>): {
 } {
   const choices = Array.isArray(payload.choices) ? payload.choices : [];
   const first = choices[0];
-  const message = object.isRecord(first) && object.isRecord(first.message) ? first.message : {};
-  const answer = openaiChat.chatContentToText(message.content);
+  const message = isRecord(first) && isRecord(first.message) ? first.message : {};
+  const answer = chatContentToText(message.content);
   const citations: WebSearchCitation[] = [];
   // Best-effort grounding extraction: walk any nested object for {uri|url,title}.
   const seen = new Set<string>();
   const visit = (v: unknown, depth: number): void => {
-    if (depth > MAX_GROUNDING_WALK_DEPTH || !object.isRecord(v)) return;
-    const url = stringUtils.trimToEmpty(v.url) || stringUtils.trimToEmpty(v.uri);
+    if (depth > MAX_GROUNDING_WALK_DEPTH || !isRecord(v)) return;
+    const url = trimToEmpty(v.url) || trimToEmpty(v.uri);
     if (url && !seen.has(url)) {
       seen.add(url);
-      const title = stringUtils.trimToEmpty(v.title);
+      const title = trimToEmpty(v.title);
       citations.push({ url, ...(title ? { title } : {}) });
     }
     for (const val of Object.values(v)) {