@dbx-tools/appkit-web-search 0.6.222 → 0.6.224

package/src/plugin.ts

@@ -1,16 +1,16 @@
 /**
  * AppKit plugin (registered name: `web-search`) that owns the resolved
  * web-search runtime - the URL policy, result / length caps, timeout, and
- * default approval gate the {@link webSearchTool} / {@link webFetchTool}
- * read. Registering it resolves and logs the effective config (which URL
- * policy is in force, the caps) so a misconfiguration is visible in the boot
- * logs rather than on the first search, and installs the plugin's
- * `execute()` as the runtime's executor so every outbound call picks up
- * AppKit's cache / retry / timeout / telemetry chain.
+ * default approval gate its tools read. Registering it resolves and logs the
+ * effective config (which URL policy is in force, the caps) so a
+ * misconfiguration is visible in the boot logs rather than on the first
+ * search. The plugin's `execute()` is captured by its own runtime so every
+ * outbound call picks up AppKit's cache / retry / timeout / telemetry chain.
  *
  * The plugin also implements AppKit's `ToolProvider`, so an AppKit agent gets
- * `web_search` / `web_fetch` without going through Mastra; the Mastra tools in
- * `tool.ts` are the other half and share the same runtime.
+ * `web_search` / `web_fetch` without going through Mastra. App-integrated
+ * Mastra agents consume this provider through `plugins["web-search"].toolkit()`;
+ * standalone factories in `tool.ts` use their own explicit runtime or config.
  *
  * @module
  */
@@ -38,7 +38,7 @@ import {
   type WebSearchPluginConfig,
 } from "./config.ts";
 import { runWebFetch } from "./fetch.ts";
-import { getWebSearchRuntime, resetWebSearchRuntime, setWebSearchExecutor } from "./runtime.ts";
+import { createWebSearchRuntime, type WebSearchRuntime } from "./runtime.ts";
 import {
   webFetchRequestSchema,
   webSearchRequestSchema,
@@ -120,6 +120,11 @@ export class WebSearchPlugin extends Plugin<WebSearchPluginConfig> implements To
     config: { schema: WEB_SEARCH_CONFIG_SCHEMA },
   } satisfies PluginManifest<"web-search">;
 
+  /** Runtime owned exclusively by this plugin instance. */
+  private readonly runtime: WebSearchRuntime = createWebSearchRuntime(this.config, (fn, settings) =>
+    this.execute(fn, settings),
+  );
+
   /**
    * Promote the serving endpoint to a required resource once a deployment
    * pins one, through plugin config or either environment name. Left optional
@@ -166,13 +171,12 @@ export class WebSearchPlugin extends Plugin<WebSearchPluginConfig> implements To
   };
 
   /**
-   * Prime the shared runtime from this plugin's config (over env), route the
-   * tools' outbound calls through this plugin's interceptor chain, and log the
-   * effective policy so an active allow-list / caps are obvious at boot.
+   * Log the effective policy so an active allow-list and caps are obvious at
+   * boot. Runtime construction already resolved config and captured this
+   * plugin's interceptor chain.
    */
   override async setup(): Promise<void> {
-    const { config } = getWebSearchRuntime(this.config);
-    setWebSearchExecutor((fn, settings) => this.execute(fn, settings));
+    const { config } = this.runtime;
     logger.info("ready", {
       model: config.model ?? `fallbacks:[${config.modelFallbacks.join(", ")}]`,
       modelSource: config.modelSource,
@@ -186,24 +190,16 @@ export class WebSearchPlugin extends Plugin<WebSearchPluginConfig> implements To
   }
 
   /**
-   * Drop the shared runtime so a restarted app re-resolves config and does not
-   * keep calling through a torn-down plugin's `execute()`. Bounded and
-   * idempotent: there is no connection to drain, only the memo to clear.
+   * No runtime resources require draining. The instance-owned config and
+   * executor become unreachable with this plugin.
    */
-  async shutdown(): Promise<void> {
-    resetWebSearchRuntime();
+  shutdown(): void {
+    return;
   }
 
-  /**
-   * Abort in-flight work. AppKit's graceful shutdown only invokes this hook -
-   * it never calls {@link shutdown} - so the runtime memo is dropped from here
-   * to keep a restarted app from calling through a torn-down `execute()`. The
-   * teardown is synchronous and idempotent, so the un-awaited call costs
-   * nothing.
-   */
+  /** Abort in-flight work owned by this plugin instance. */
   override abortActiveOperations(): void {
     super.abortActiveOperations();
-    void this.shutdown();
   }
 
   /** AppKit `ToolProvider`: the tool definitions offered to an agent. */
@@ -224,14 +220,14 @@ export class WebSearchPlugin extends Plugin<WebSearchPluginConfig> implements To
     return {
       /**
        * Run a web search directly (bypassing the agent tool). Resolves the
-       * OBO client from the active execution context and reads the shared
-       * runtime config primed at setup.
+       * OBO client from the active execution context and reads this plugin's
+       * runtime config.
        */
       search: (request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult> =>
         this.search(request, signal),
       /**
        * Fetch one URL directly (bypassing the agent tool). Enforces the
-       * configured URL policy. Reads the shared runtime config.
+       * configured URL policy.
        */
       fetch: (request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult> =>
         this.fetch(request, signal),
@@ -239,16 +235,11 @@ export class WebSearchPlugin extends Plugin<WebSearchPluginConfig> implements To
   }
 
   private async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult> {
-    return runWebSearch(
-      request,
-      getWebSearchRuntime().config,
-      await resolveWebSearchContext(),
-      signal,
-    );
+    return runWebSearch(request, this.runtime, await resolveWebSearchContext(), signal);
   }
 
   private async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult> {
-    return runWebFetch(request, getWebSearchRuntime().config, signal);
+    return runWebFetch(request, this.runtime, signal);
   }
 }
 
@@ -258,12 +249,14 @@ export class WebSearchPlugin extends Plugin<WebSearchPluginConfig> implements To
  * @example
  * ```ts
  * import { createApp, server } from "@databricks/appkit";
- * import { plugin as webSearchPlugin, tool as webTool } from "@dbx-tools/appkit-web-search";
+ * import { plugin as webSearchPlugin } from "@dbx-tools/appkit-web-search";
  * import { agents, plugin as mastraPlugin } from "@dbx-tools/appkit-mastra";
  *
  * const researcher = agents.createAgent({
  *   instructions: "Research questions with web_search, then read sources with web_fetch.",
- *   tools: () => ({ web_search: webTool.webSearchTool(), web_fetch: webTool.webFetchTool() }),
+ *   async tools(plugins) {
+ *     return { ...(await plugins["web-search"].toolkit()) };
+ *   },
  * });
  *
  * await createApp({

package/src/runtime.ts

@@ -1,20 +1,9 @@
 /**
- * The web-search runtime: a lazily-resolved, process-wide config shared by
- * the plugin and the `web_search` / `web_fetch` tools, so both read one
- * resolved allow-list / cap / timeout set. The first caller (normally the
- * plugin at setup) primes it from the plugin's config; later callers (the
- * tools' `execute`) reuse it.
+ * Web-search runtime construction and execution helpers.
  *
- * The runtime also carries the {@link WebSearchExecutor} every outbound call
- * runs through. The plugin installs its own `execute()` there at setup, which
- * is how the tools - plain functions with no plugin instance in scope - still
- * get AppKit's cache / retry / timeout / telemetry chain. Without a
- * registered plugin (a direct call from a script or a test) the calls still
- * run, just without interceptors.
- *
- * Unlike the email runtime there is no connection to pool - the backend is
- * stateless HTTP per call - so the runtime holds only the resolved config and
- * that executor.
+ * Each plugin instance owns one runtime. Standalone tool factories create their
+ * own runtime, so separate apps and direct consumers cannot overwrite each
+ * other's policy or executor.
  *
  * @module
  */
@@ -40,51 +29,84 @@ export type WebSearchExecutor = <T>(
   settings: WebSearchExecutionSettings,
 ) => Promise<ExecutionResult<T>>;
 
-/** The shared resolved config plus the executor outbound calls run through. */
+/** The resolved config plus the executor outbound calls run through. */
 export interface WebSearchRuntime {
   config: ResolvedWebSearchConfig;
   execute: WebSearchExecutor;
 }
 
+/** Runtime-aware operation input, retaining resolved-config compatibility. */
+export type WebSearchRuntimeInput = WebSearchRuntime | ResolvedWebSearchConfig;
+
 /**
- * Executor used until (or unless) the plugin installs its own: run the call
- * directly, mapping a throw onto the same {@link ExecutionResult} shape so
- * call sites branch on `ok` either way.
+ * Executor used by standalone runtimes: run the call directly, mapping a throw
+ * onto the same {@link ExecutionResult} shape so call sites branch on `ok`
+ * either way.
  */
 const directExecute = execution.directExecutor<WebSearchExecutionSettings>();
 
-let runtime: WebSearchRuntime | undefined;
+/** Build an isolated runtime for one plugin instance or standalone tool set. */
+export function createWebSearchRuntime(
+  overrides?: WebSearchPluginConfig,
+  execute: WebSearchExecutor = directExecute,
+): WebSearchRuntime {
+  return { config: resolveWebSearchConfig(overrides), execute };
+}
+
+/** Build an isolated runtime from config that has already been resolved. */
+export function createResolvedWebSearchRuntime(
+  config: ResolvedWebSearchConfig,
+  execute: WebSearchExecutor = directExecute,
+): WebSearchRuntime {
+  return { config, execute };
+}
+
+/** Normalize an explicit runtime or legacy resolved config for one operation. */
+export function toWebSearchRuntime(input: WebSearchRuntimeInput): WebSearchRuntime {
+  return "execute" in input ? input : createResolvedWebSearchRuntime(input);
+}
 
 /**
- * Return the shared runtime, building it on first use from the supplied
- * config layered over environment defaults. Overrides are only read when the
- * runtime is first created, so prime it from the plugin's config at setup;
- * subsequent calls (the tools' `execute`) pass nothing and get the same
- * instance.
+ * Build an isolated standalone runtime.
+ *
+ * @deprecated Use {@link createWebSearchRuntime}. This compatibility helper
+ * returns a new runtime on every call and never reads or updates plugin state.
  */
 export function getWebSearchRuntime(overrides?: WebSearchPluginConfig): WebSearchRuntime {
-  if (!runtime) {
-    runtime = { config: resolveWebSearchConfig(overrides), execute: directExecute };
-  }
-  return runtime;
+  return createWebSearchRuntime(overrides);
 }
 
+/** Install an executor on an explicit runtime. */
+export function setWebSearchExecutor(runtime: WebSearchRuntime, execute: WebSearchExecutor): void;
 /**
- * Install the executor outbound calls run through. The plugin calls this at
- * setup with its own `execute()`; a second call replaces the previous one, so
- * a re-registered plugin does not leave the tools bound to a dead instance.
+ * @deprecated Process-global executor registration is no longer supported.
+ * Pass a runtime as the first argument or provide the executor to
+ * {@link createWebSearchRuntime}.
  */
-export function setWebSearchExecutor(execute: WebSearchExecutor): void {
-  getWebSearchRuntime().execute = execute;
+export function setWebSearchExecutor(execute: WebSearchExecutor): never;
+export function setWebSearchExecutor(
+  runtimeOrExecute: WebSearchRuntime | WebSearchExecutor,
+  execute?: WebSearchExecutor,
+): void {
+  if (typeof runtimeOrExecute === "function") {
+    throw new TypeError(
+      "setWebSearchExecutor requires an explicit runtime; use createWebSearchRuntime(config, executor)",
+    );
+  }
+  if (!execute) throw new TypeError("setWebSearchExecutor requires an executor");
+  runtimeOrExecute.execute = execute;
 }
 
-/** Drop the memoized runtime so the next {@link getWebSearchRuntime} rebuilds it. */
+/**
+ * @deprecated Plugin runtimes are instance-owned and need no global reset.
+ * This compatibility helper is intentionally a no-op.
+ */
 export function resetWebSearchRuntime(): void {
-  runtime = undefined;
+  return;
 }
 
 /**
- * Run one idempotent read through the shared executor and unwrap it.
+ * Run one idempotent read through the runtime executor and unwrap it.
  *
  * `execute()` never throws, so a failed call arrives as `{ ok: false }` with
  * a status the interceptors already sanitized; it is logged here and re-raised
@@ -94,16 +116,16 @@ export function resetWebSearchRuntime(): void {
  * interceptor supplies so either one unwinds the I/O.
  */
 export async function executeRead<T>(
+  runtime: WebSearchRuntime,
   operation: string,
   settings: WebSearchExecutionSettings,
   fn: (signal?: AbortSignal) => Promise<T>,
   signal?: AbortSignal,
 ): Promise<T> {
-  const { execute } = getWebSearchRuntime();
   return execution.run({
     operation,
     settings,
-    execute,
+    execute: runtime.execute,
     fn,
     signal,
     canceled: ExecutionError.canceled,

package/src/scrape.ts

@@ -19,11 +19,11 @@
  */
 
 import { log } from "@dbx-tools/shared-core";
+import { load } from "cheerio";
 import { gotScraping } from "got-scraping";
-import type { ResolvedWebSearchConfig } from "./config.ts";
 import { scrapeSearchExecuteDefaults, toCallSettings } from "./defaults.ts";
 import { htmlFragmentToText } from "./html-text.ts";
-import { executeRead } from "./runtime.ts";
+import { executeRead, toWebSearchRuntime, type WebSearchRuntimeInput } from "./runtime.ts";
 import type { WebSearchCitation, WebSearchRequest, WebSearchResult } from "./schema.ts";
 
 const logger = log.logger("web-search/scrape");
@@ -47,25 +47,18 @@ function unwrapDdgUrl(href: string): string {
 }
 
 /** Parse DDG HTML result blocks into citations (title, url, snippet). */
-function parseDdgHtml(html: string): WebSearchCitation[] {
+export function parseDdgHtml(html: string): WebSearchCitation[] {
+  const $ = load(html);
   const citations: WebSearchCitation[] = [];
-  // Each result: an anchor with class result__a (title + href) and a snippet
-  // with class result__snippet. Match anchors, then the following snippet.
-  const anchorRe = /<a[^>]*class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
-  const snippetRe = /<a[^>]*class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/g;
-  const snippets: string[] = [];
-  let sm: RegExpExecArray | null;
-  while ((sm = snippetRe.exec(html)) !== null) snippets.push(htmlFragmentToText(sm[1] ?? ""));
-  let am: RegExpExecArray | null;
-  let i = 0;
-  while ((am = anchorRe.exec(html)) !== null) {
-    const url = unwrapDdgUrl(am[1] ?? "");
-    const title = htmlFragmentToText(am[2] ?? "");
-    if (!url || !title) continue;
-    const snippet = snippets[i] ?? "";
+  $("a.result__a").each((_index, element) => {
+    const anchor = $(element);
+    const url = unwrapDdgUrl(anchor.attr("href") ?? "");
+    const title = htmlFragmentToText(anchor.html() ?? "");
+    if (!url || !title) return;
+    const snippetElement = anchor.closest(".result").find(".result__snippet").first();
+    const snippet = htmlFragmentToText(snippetElement.html() ?? "");
     citations.push({ url, title, ...(snippet ? { snippet } : {}) });
-    i += 1;
-  }
+  });
   return citations;
 }
 
@@ -78,10 +71,13 @@ function parseDdgHtml(html: string): WebSearchCitation[] {
  */
 export async function runScrapeSearch(
   request: WebSearchRequest,
-  config: ResolvedWebSearchConfig,
+  runtimeOrConfig: WebSearchRuntimeInput,
   signal?: AbortSignal,
 ): Promise<WebSearchResult> {
+  const runtime = toWebSearchRuntime(runtimeOrConfig);
+  const { config } = runtime;
   const page = await executeRead(
+    runtime,
     "scrape-search",
     toCallSettings(scrapeSearchExecuteDefaults, config.timeoutMs, [
       "web-search",

package/src/search.ts

@@ -34,7 +34,12 @@ import { openaiChat, openaiResponses } from "@dbx-tools/shared-model";
 import { MODEL_ENV, SERVING_ENDPOINT_ENV, type ResolvedWebSearchConfig } from "./config.ts";
 import { toCallSettings, webSearchExecuteDefaults } from "./defaults.ts";
 import { detectWebSearchProvider, supportsWebSearch, webSearchToolSpec } from "./provider.ts";
-import { executeRead } from "./runtime.ts";
+import {
+  executeRead,
+  toWebSearchRuntime,
+  type WebSearchRuntime,
+  type WebSearchRuntimeInput,
+} from "./runtime.ts";
 import type { WebSearchCitation, WebSearchRequest, WebSearchResult } from "./schema.ts";
 import { runScrapeSearch } from "./scrape.ts";
 
@@ -168,11 +173,13 @@ async function postServing(
   ctx: WebSearchContext,
   url: string,
   body: unknown,
-  config: ResolvedWebSearchConfig,
+  runtime: WebSearchRuntime,
   cacheKey: readonly (string | number)[],
   signal?: AbortSignal,
 ): Promise<Record<string, unknown>> {
+  const { config } = runtime;
   const payload = await executeRead(
+    runtime,
     "serving-request",
     toCallSettings(webSearchExecuteDefaults, config.timeoutMs, cacheKey),
     async (executeSignal): Promise<unknown> => {
@@ -262,17 +269,19 @@ function fromChatPayload(payload: Record<string, unknown>): {
  */
 export async function runWebSearch(
   request: WebSearchRequest,
-  config: ResolvedWebSearchConfig,
+  runtimeOrConfig: WebSearchRuntimeInput,
   ctx: WebSearchContext,
   signal?: AbortSignal,
 ): Promise<WebSearchResult> {
+  const runtime = toWebSearchRuntime(runtimeOrConfig);
+  const { config } = runtime;
   const modelId = await resolveWebSearchModel(ctx, config, request.model);
 
   if (modelId === null) {
     // No native web-search model deployed in this workspace.
     if (config.scrapeFallback) {
       logger.info("no-native-model:scrape-fallback", { query: request.query });
-      return runScrapeSearch(request, config, signal);
+      return runScrapeSearch(request, runtime, signal);
     }
     throw ConfigurationError.resourceNotFound(
       "Web-search-capable serving endpoint",
@@ -304,7 +313,7 @@ export async function runWebSearch(
     ctx,
     url,
     body,
-    config,
+    runtime,
     ["web-search", "serving", spec.api, modelId, request.query],
     signal,
   );

package/src/tool.ts

@@ -13,10 +13,11 @@
  * list) gates only calls whose URL matches - for `web_fetch` that is evaluated
  * against the target URL, while `web_search` (whose result URLs aren't known
  * before the call) treats a pattern gate as "always gate". `approval` falls
- * back to the plugin's `approval` config when a tool omits its own.
+ * back to the standalone runtime's `approval` config when a tool omits its own.
  *
- * The same two tools are exposed to AppKit's own agents through the plugin's
- * `ToolProvider` (see `plugin.ts`); this module is the Mastra half.
+ * App-integrated agents should consume the plugin's native toolkit so calls
+ * retain that plugin's policy and executor. These factories are the standalone
+ * Mastra surface and capture an explicit runtime or isolated config.
  *
  * @module
  */
@@ -29,9 +30,10 @@ import {
   toApprovalPolicy,
   type ApprovalGate,
   type ApprovalPolicy,
+  type WebSearchPluginConfig,
 } from "./config.ts";
 import { runWebFetch } from "./fetch.ts";
-import { getWebSearchRuntime } from "./runtime.ts";
+import { createWebSearchRuntime, type WebSearchRuntime } from "./runtime.ts";
 import {
   webFetchRequestSchema,
   webFetchResultSchema,
@@ -60,19 +62,29 @@ function parseToolInput<S extends z.ZodType>(schema: S, input: unknown): z.infer
 export interface WebSearchToolOptions {
   /** Override the tool id. */
   id?: string;
+  /** Isolated runtime used by this standalone tool. Mutually exclusive with `config`. */
+  runtime?: WebSearchRuntime;
+  /** Config used to create an isolated direct-execution runtime. */
+  config?: WebSearchPluginConfig;
   /**
-   * Approval gate for this tool, overriding the plugin's `approval`. `true`
+   * Approval gate for this tool, overriding the runtime's `approval`. `true`
    * gates every call; a URL-pattern (or list) gates only matching calls;
    * omit / `false` for no approval. See {@link ApprovalGate}.
    */
   approval?: ApprovalGate | ApprovalPolicy;
 }
 
-/** Resolve the effective gate: explicit tool option, else the plugin default. */
-function effectiveGate(opts: WebSearchToolOptions): ApprovalPolicy {
-  return opts.approval === undefined
-    ? getWebSearchRuntime().config.approval
-    : toApprovalPolicy(opts.approval);
+/** Resolve the isolated runtime captured by one standalone tool factory. */
+function toolRuntime(opts: WebSearchToolOptions): WebSearchRuntime {
+  if (opts.runtime && opts.config) {
+    throw new TypeError("web-search tool options accept either runtime or config, not both");
+  }
+  return opts.runtime ?? createWebSearchRuntime(opts.config);
+}
+
+/** Resolve the effective gate: explicit tool option, else the runtime default. */
+function effectiveGate(opts: WebSearchToolOptions, runtime: WebSearchRuntime): ApprovalPolicy {
+  return opts.approval === undefined ? runtime.config.approval : toApprovalPolicy(opts.approval);
 }
 
 /**
@@ -91,7 +103,8 @@ function effectiveGate(opts: WebSearchToolOptions): ApprovalPolicy {
  * ```
  */
 export function webSearchTool(opts: WebSearchToolOptions = {}) {
-  const gate = effectiveGate(opts);
+  const runtime = toolRuntime(opts);
+  const gate = effectiveGate(opts, runtime);
   return createTool({
     id: opts.id ?? "web_search",
     description: WEB_SEARCH_TOOL_DESCRIPTION,
@@ -101,9 +114,8 @@ export function webSearchTool(opts: WebSearchToolOptions = {}) {
     // is treated as "always gate".
     ...(gate.mode === "none" ? {} : { requireApproval: () => true }),
     execute: async (input) => {
-      const { config } = getWebSearchRuntime();
       const request = parseToolInput(webSearchRequestSchema, input);
-      return runWebSearch(request, config, await resolveWebSearchContext());
+      return runWebSearch(request, runtime, await resolveWebSearchContext());
     },
   });
 }
@@ -120,7 +132,8 @@ export function webSearchTool(opts: WebSearchToolOptions = {}) {
  * ```
  */
 export function webFetchTool(opts: WebSearchToolOptions = {}) {
-  const gate = effectiveGate(opts);
+  const runtime = toolRuntime(opts);
+  const gate = effectiveGate(opts, runtime);
   return createTool({
     id: opts.id ?? "web_fetch",
     description: WEB_FETCH_TOOL_DESCRIPTION,
@@ -136,8 +149,7 @@ export function webFetchTool(opts: WebSearchToolOptions = {}) {
             approvalMatches(gate, [parseToolInput(webFetchRequestSchema, input).url]),
         }),
     execute: async (input) => {
-      const { config } = getWebSearchRuntime();
-      return runWebFetch(parseToolInput(webFetchRequestSchema, input), config);
+      return runWebFetch(parseToolInput(webFetchRequestSchema, input), runtime);
     },
   });
 }