@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/tools/serp-providers/index.js

@@ -6,9 +6,125 @@
  * Provides a common interface for search engine results page (SERP) providers
  * so that tool implementations can be provider-agnostic.
  */
-// ---------------------------------------------------------------------------
-// Re-exports
-// ---------------------------------------------------------------------------
+async function getSecret(key, resolver) {
+    return (resolver?.getSecret?.(key) ?? null) || process.env[key] || null;
+}
+/**
+ * The secrets each provider needs, for the "is this usable?" check and for the
+ * error message when it is not.
+ *
+ * Declared next to the factory that reads them so the two cannot drift: a
+ * provider added to the switch below without an entry here would be invisible
+ * to routing, which fails as a silently-skipped backend rather than an error.
+ */
+export const SERP_PROVIDER_SECRETS = {
+    serpapi: ["SERPAPI_API_KEY"],
+    dataforseo: ["DATA_FOR_SEO_LOGIN", "DATA_FOR_SEO_PASSWORD"],
+    brave: ["BRAVE_API_KEY"],
+    apify: ["APIFY_API_TOKEN", "APIFY_API_KEY"],
+    openai: ["OPENAI_API_KEY"],
+    gemini: ["GEMINI_API_KEY"]
+};
+/**
+ * The search types each provider's client can answer through
+ * `createSerpProvider`.
+ *
+ * Declared here rather than read off the instance because routing has to know
+ * before it builds a client (building one needs the key). A provider whose
+ * class implements `searchImages` must list `images` here and one that does
+ * not must not: `serp-providers-images.test.ts` instantiates every provider
+ * and checks the two against each other, so an image backend cannot be added
+ * and left invisible to routing.
+ */
+export const SERP_PROVIDER_SEARCH_TYPES = {
+    serpapi: ["web"],
+    dataforseo: ["web"],
+    brave: ["web", "images"],
+    apify: ["web"],
+    // OpenAI and Gemini answer in prose and cite the pages they read; the
+    // citations are the result list. Neither has an image or news endpoint, so
+    // routing skips them for those types instead of answering with pages.
+    openai: ["web"],
+    gemini: ["web"]
+};
+/**
+ * Whether every secret `type` needs is present.
+ *
+ * Apify is the one provider with two acceptable names: `APIFY_API_TOKEN` is
+ * what Apify's own docs call it and what the rest of NodeTool's Apify layer
+ * reads, while `APIFY_API_KEY` is what this install shipped first. Either
+ * satisfies it, so upgrading does not silently turn search off.
+ */
+export async function serpProviderConfigured(type, resolver) {
+    const names = SERP_PROVIDER_SECRETS[type];
+    if (type === "apify") {
+        for (const name of names) {
+            if (await getSecret(name, resolver))
+                return true;
+        }
+        return false;
+    }
+    for (const name of names) {
+        if (!(await getSecret(name, resolver)))
+            return false;
+    }
+    return true;
+}
+export async function createSerpProvider(providerType, resolver) {
+    const type = providerType.toLowerCase();
+    switch (type) {
+        case "serpapi": {
+            const key = await getSecret("SERPAPI_API_KEY", resolver);
+            if (!key) {
+                throw new Error("SERPAPI_API_KEY is required for SerpAPI provider. Set it as an environment variable or via settings.");
+            }
+            return new (await import("./serpapi-provider.js")).SerpApiProvider(key);
+        }
+        case "dataforseo": {
+            const login = await getSecret("DATA_FOR_SEO_LOGIN", resolver);
+            const password = await getSecret("DATA_FOR_SEO_PASSWORD", resolver);
+            if (!login || !password) {
+                throw new Error("DATA_FOR_SEO_LOGIN and DATA_FOR_SEO_PASSWORD are required for DataForSEO provider.");
+            }
+            return new (await import("./dataforseo-provider.js")).DataForSeoProvider(login, password);
+        }
+        case "brave": {
+            const key = await getSecret("BRAVE_API_KEY", resolver);
+            if (!key) {
+                throw new Error("BRAVE_API_KEY is required for Brave provider. Set it as an environment variable or via settings.");
+            }
+            return new (await import("./brave-provider.js")).BraveProvider(key);
+        }
+        case "apify": {
+            const key = (await getSecret("APIFY_API_TOKEN", resolver)) ??
+                (await getSecret("APIFY_API_KEY", resolver));
+            if (!key) {
+                throw new Error("APIFY_API_TOKEN is required for the Apify provider. Set it as an environment variable or via settings.");
+            }
+            return new (await import("./apify-provider.js")).ApifyProvider(key);
+        }
+        case "openai": {
+            const key = await getSecret("OPENAI_API_KEY", resolver);
+            if (!key) {
+                throw new Error("OPENAI_API_KEY is required for the OpenAI search provider. Set it as an environment variable or via settings.");
+            }
+            return new (await import("./openai-provider.js")).OpenAiSearchProvider(key);
+        }
+        case "gemini": {
+            const key = await getSecret("GEMINI_API_KEY", resolver);
+            if (!key) {
+                throw new Error("GEMINI_API_KEY is required for the Gemini search provider. Set it as an environment variable or via settings.");
+            }
+            return new (await import("./gemini-provider.js")).GeminiSearchProvider(key);
+        }
+        default:
+            throw new Error(`Unknown SERP provider: ${providerType}. Supported: ${Object.keys(SERP_PROVIDER_SECRETS).join(", ")}`);
+    }
+}
 export { SerpApiProvider } from "./serpapi-provider.js";
 export { DataForSeoProvider } from "./dataforseo-provider.js";
+export { BraveProvider } from "./brave-provider.js";
+export { ApifyProvider } from "./apify-provider.js";
+export { OpenAiSearchProvider, OPENAI_SEARCH_MODEL } from "./openai-provider.js";
+export { GeminiSearchProvider, GEMINI_SEARCH_MODEL } from "./gemini-provider.js";
 //# sourceMappingURL=index.js.map

package/dist/tools/serp-providers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/serp-providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAsCH,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/serp-providers/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/serp-providers/openai-provider.d.ts

@@ -0,0 +1,58 @@
+/**
+ * OpenAI web search as a SERP provider.
+ *
+ * OpenAI's search-enabled chat model answers in prose and attaches a
+ * `url_citation` annotation per page it read. The citations are the ranked
+ * result list — a title, a URL, and the span of the answer that page
+ * supported — so the same call serves both shapes: `search` returns the
+ * citations normalised to `SearchResult`, and `answer` returns the prose the
+ * routed `web_search` capability prints.
+ *
+ * This is the one implementation of the call. `tools/openai-tools.ts` resolves
+ * the key from a `ProcessingContext` and delegates here.
+ */
+import type { SerpProvider, SearchResult, SearchOptions } from "./index.js";
+/** The chat model that carries the web-search tool. */
+export declare const OPENAI_SEARCH_MODEL = "gpt-4o-search-preview";
+/** One OpenAI answer, with the pages it cited. */
+export interface OpenAiSearchAnswer {
+    /** The model's prose answer. */
+    text: string;
+    /** The cited pages, deduplicated by URL, in the order they appear. */
+    citations: SearchResult[];
+    /** The completion as OpenAI returned it. */
+    raw: unknown;
+}
+interface UrlCitation {
+    url?: unknown;
+    title?: unknown;
+    start_index?: unknown;
+    end_index?: unknown;
+}
+interface Annotation {
+    type?: unknown;
+    url_citation?: UrlCitation;
+}
+/**
+ * Read the `url_citation` annotations off an assistant message into ranked
+ * results. Duplicates are collapsed on URL — the model cites one page several
+ * times across an answer — keeping the first mention's snippet and position.
+ */
+export declare function citationsFromAnswer(text: string, annotations: readonly Annotation[]): SearchResult[];
+export declare class OpenAiSearchProvider implements SerpProvider {
+    private readonly apiKey;
+    private readonly model;
+    constructor(apiKey: string, model?: string);
+    /** Ask the search model, and read both the prose and the citations. */
+    answer(query: string): Promise<OpenAiSearchAnswer>;
+    /**
+     * The cited pages as a ranked result list.
+     *
+     * OpenAI's search tool takes no result count, so `numResults` truncates what
+     * came back rather than narrowing the request.
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    searchRaw(query: string): Promise<unknown>;
+}
+export {};
+//# sourceMappingURL=openai-provider.d.ts.map

package/dist/tools/serp-providers/openai-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-provider.d.ts","sourceRoot":"","sources":["../../../src/tools/serp-providers/openai-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAK3D,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,4CAA4C;IAC5C,GAAG,EAAE,OAAO,CAAC;CACd;AAED,UAAU,WAAW;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,UAAU;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,YAAY,CAAC,EAAE,WAAW,CAAC;CAC5B;AAqBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,SAAS,UAAU,EAAE,GACjC,YAAY,EAAE,CAgBhB;AAED,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,YAAY,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,MAA4B,EAG9D;IAED,uEAAuE;IACjE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA+BvD;IAED;;;;;OAKG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC,CAMzB;IAEK,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE/C;CACF"}

package/dist/tools/serp-providers/openai-provider.js

@@ -0,0 +1,113 @@
+/**
+ * OpenAI web search as a SERP provider.
+ *
+ * OpenAI's search-enabled chat model answers in prose and attaches a
+ * `url_citation` annotation per page it read. The citations are the ranked
+ * result list — a title, a URL, and the span of the answer that page
+ * supported — so the same call serves both shapes: `search` returns the
+ * citations normalised to `SearchResult`, and `answer` returns the prose the
+ * routed `web_search` capability prints.
+ *
+ * This is the one implementation of the call. `tools/openai-tools.ts` resolves
+ * the key from a `ProcessingContext` and delegates here.
+ */
+/** The chat model that carries the web-search tool. */
+export const OPENAI_SEARCH_MODEL = "gpt-4o-search-preview";
+/** How much of the cited span is kept as a snippet. */
+const MAX_SNIPPET_CHARS = 400;
+function readIndex(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0
+        ? value
+        : null;
+}
+/**
+ * The slice of the answer a citation covers, as the result's snippet.
+ *
+ * A citation with no usable span is not dropped: the page is still a result,
+ * it just has nothing to quote.
+ */
+function snippetFor(text, citation) {
+    const start = readIndex(citation.start_index);
+    const end = readIndex(citation.end_index);
+    if (start === null || end === null || end <= start)
+        return "";
+    return text.slice(start, end).trim().slice(0, MAX_SNIPPET_CHARS);
+}
+/**
+ * Read the `url_citation` annotations off an assistant message into ranked
+ * results. Duplicates are collapsed on URL — the model cites one page several
+ * times across an answer — keeping the first mention's snippet and position.
+ */
+export function citationsFromAnswer(text, annotations) {
+    const byUrl = new Map();
+    for (const annotation of annotations) {
+        if (annotation?.type !== "url_citation")
+            continue;
+        const citation = annotation.url_citation;
+        const url = citation?.url;
+        if (typeof url !== "string" || !url)
+            continue;
+        if (byUrl.has(url))
+            continue;
+        byUrl.set(url, {
+            title: typeof citation?.title === "string" ? citation.title : "",
+            url,
+            snippet: snippetFor(text, citation ?? {}),
+            position: byUrl.size + 1
+        });
+    }
+    return [...byUrl.values()];
+}
+export class OpenAiSearchProvider {
+    apiKey;
+    model;
+    constructor(apiKey, model = OPENAI_SEARCH_MODEL) {
+        this.apiKey = apiKey;
+        this.model = model;
+    }
+    /** Ask the search model, and read both the prose and the citations. */
+    async answer(query) {
+        // Dynamic import so `openai` stays an optional dependency of this path.
+        const { OpenAI } = await import("openai");
+        const client = new OpenAI({ apiKey: this.apiKey });
+        let completion;
+        try {
+            completion = await client.chat.completions.create({
+                model: this.model,
+                web_search_options: {},
+                messages: [{ role: "user", content: query }]
+            });
+        }
+        catch (e) {
+            // Name the call, so a transport or auth failure the SDK reports tersely
+            // still says which service it came from.
+            throw new Error(`OpenAI web search request failed: ${e.message}`);
+        }
+        const message = completion.choices[0]?.message;
+        const text = message?.content ?? "";
+        const annotations = message
+            ?.annotations;
+        return {
+            text,
+            citations: citationsFromAnswer(text, Array.isArray(annotations) ? annotations : []),
+            raw: completion
+        };
+    }
+    /**
+     * The cited pages as a ranked result list.
+     *
+     * OpenAI's search tool takes no result count, so `numResults` truncates what
+     * came back rather than narrowing the request.
+     */
+    async search(query, options) {
+        const { citations } = await this.answer(query);
+        const numResults = options?.numResults;
+        return numResults === undefined
+            ? citations
+            : citations.slice(0, numResults);
+    }
+    async searchRaw(query) {
+        return (await this.answer(query)).raw;
+    }
+}
+//# sourceMappingURL=openai-provider.js.map

package/dist/tools/serp-providers/openai-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-provider.js","sourceRoot":"","sources":["../../../src/tools/serp-providers/openai-provider.ts"],"names":[],"mappings":"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"}

package/dist/tools/serp-providers/serpapi-provider.d.ts

@@ -1,18 +1,22 @@
 /**
  * SerpAPI provider implementation.
  *
- * Port of src/nodetool/agents/serp_providers/serp_api_provider.py
+ * The narrow half of the SerpAPI surface: one query, one engine, normalised to
+ * the `SearchResult` shape every SERP provider answers with, so `web_search`
+ * does not care which backend this install configured.
  *
- * Wraps the SerpAPI HTTP API and normalises results into the common
- * SearchResult shape.
+ * The general half is the `serpapi` capability module — every engine, its
+ * parameters discovered from SerpAPI's own table. Both go through
+ * {@link SerpApiClient}, so there is one place that holds the key and one place
+ * that scrubs it out of an error.
  */
 import type { SerpProvider, SearchResult, SearchOptions } from "./index.js";
 export declare class SerpApiProvider implements SerpProvider {
-    private readonly apiKey;
+    private readonly client;
     private readonly gl;
     private readonly hl;
     constructor(apiKey: string, gl?: string, hl?: string);
     search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
-    searchRaw(query: string, options?: SearchOptions): Promise<unknown>;
+    searchRaw(query: string, options?: SearchOptions): Promise<Record<string, unknown>>;
 }
 //# sourceMappingURL=serpapi-provider.d.ts.map

package/dist/tools/serp-providers/serpapi-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serpapi-provider.d.ts","sourceRoot":"","sources":["../../../src/tools/serp-providers/serpapi-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAiC5E,qBAAa,eAAgB,YAAW,YAAY;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;gBAEhB,MAAM,EAAE,MAAM,EAAE,EAAE,SAAO,EAAE,EAAE,SAAO;IAM1C,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC;IAyBpB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;CAa1E"}
+{"version":3,"file":"serpapi-provider.d.ts","sourceRoot":"","sources":["../../../src/tools/serp-providers/serpapi-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI5E,qBAAa,eAAgB,YAAW,YAAY;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;IAE5B,YAAY,MAAM,EAAE,MAAM,EAAE,EAAE,SAAO,EAAE,EAAE,SAAO,EAI/C;IAEK,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC,CAYzB;IAEK,SAAS,CACb,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CASlC;CACF"}

package/dist/tools/serp-providers/serpapi-provider.js

@@ -1,66 +1,48 @@
 /**
  * SerpAPI provider implementation.
  *
- * Port of src/nodetool/agents/serp_providers/serp_api_provider.py
+ * The narrow half of the SerpAPI surface: one query, one engine, normalised to
+ * the `SearchResult` shape every SERP provider answers with, so `web_search`
+ * does not care which backend this install configured.
  *
- * Wraps the SerpAPI HTTP API and normalises results into the common
- * SearchResult shape.
+ * The general half is the `serpapi` capability module — every engine, its
+ * parameters discovered from SerpAPI's own table. Both go through
+ * {@link SerpApiClient}, so there is one place that holds the key and one place
+ * that scrubs it out of an error.
  */
-async function serpApiFetch(params) {
-    const url = new URL("https://serpapi.com/search");
-    for (const [k, v] of Object.entries(params)) {
-        if (v !== undefined)
-            url.searchParams.set(k, String(v));
-    }
-    const res = await fetch(url.toString());
-    if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`SerpAPI request failed (${res.status}): ${text}`);
-    }
-    return res.json();
-}
-// ---------------------------------------------------------------------------
-// Provider
-// ---------------------------------------------------------------------------
+import { SerpApiClient } from "../../serpapi/client.js";
+import { isRecord, isString } from "../../utils/type-guards.js";
 export class SerpApiProvider {
-    apiKey;
+    client;
     gl;
     hl;
     constructor(apiKey, gl = "us", hl = "en") {
-        this.apiKey = apiKey;
+        this.client = new SerpApiClient(apiKey);
         this.gl = gl;
         this.hl = hl;
     }
     async search(query, options) {
-        const numResults = options?.numResults ?? 10;
-        const engine = options?.engine ?? "google";
-        const data = (await serpApiFetch({
-            engine,
-            q: query,
-            api_key: this.apiKey,
-            num: numResults,
-            gl: this.gl,
-            hl: options?.language ?? this.hl
-        }));
-        const organicResults = (data.organic_results ?? []);
-        return organicResults.map((r, i) => ({
-            title: String(r.title ?? ""),
-            url: String(r.link ?? ""),
-            snippet: String(r.snippet ?? ""),
-            position: r.position ?? i + 1
+        const data = await this.searchRaw(query, options);
+        const organic = isRecord(data) ? data.organic_results : undefined;
+        if (!Array.isArray(organic))
+            return [];
+        return organic.filter(isRecord).map((result, index) => ({
+            title: isString(result.title) ? result.title : "",
+            url: isString(result.link) ? result.link : "",
+            snippet: isString(result.snippet) ? result.snippet : "",
+            position: typeof result.position === "number" ? result.position : index + 1
         }));
     }
     async searchRaw(query, options) {
-        const numResults = options?.numResults ?? 10;
-        const engine = options?.engine ?? "google";
-        return serpApiFetch({
-            engine,
+        const params = {
             q: query,
-            api_key: this.apiKey,
-            num: numResults,
+            num: options?.numResults ?? 10,
             gl: this.gl,
             hl: options?.language ?? this.hl
-        });
+        };
+        if (options?.location !== undefined)
+            params.location = options.location;
+        return this.client.search(options?.engine ?? "google", params);
     }
 }
 //# sourceMappingURL=serpapi-provider.js.map

package/dist/tools/serp-providers/serpapi-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"serpapi-provider.js","sourceRoot":"","sources":["../../../src/tools/serp-providers/serpapi-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH,KAAK,UAAU,YAAY,CAAC,MAAqB;IAC/C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,4BAA4B,CAAC,CAAC;IAClD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5C,IAAI,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,CAAC,MAAM,MAAM,IAAI,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC;AAED,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,MAAM,OAAO,eAAe;IACT,MAAM,CAAS;IACf,EAAE,CAAS;IACX,EAAE,CAAS;IAE5B,YAAY,MAAc,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,GAAG,IAAI;QAC9C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,KAAK,CAAC,MAAM,CACV,KAAa,EACb,OAAuB;QAEvB,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,QAAQ,CAAC;QAE3C,MAAM,IAAI,GAAG,CAAC,MAAM,YAAY,CAAC;YAC/B,MAAM;YACN,CAAC,EAAE,KAAK;YACR,OAAO,EAAE,IAAI,CAAC,MAAM;YACpB,GAAG,EAAE,UAAU;YACf,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,EAAE,EAAE,OAAO,EAAE,QAAQ,IAAI,IAAI,CAAC,EAAE;SACjC,CAAC,CAA4B,CAAC;QAE/B,MAAM,cAAc,GAAG,CAAC,IAAI,CAAC,eAAe,IAAI,EAAE,CAEjD,CAAC;QAEF,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YACnC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAC5B,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;YACzB,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC;YAChC,QAAQ,EAAG,CAAC,CAAC,QAAmB,IAAI,CAAC,GAAG,CAAC;SAC1C,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,KAAa,EAAE,OAAuB;QACpD,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,QAAQ,CAAC;QAE3C,OAAO,YAAY,CAAC;YAClB,MAAM;YACN,CAAC,EAAE,KAAK;YACR,OAAO,EAAE,IAAI,CAAC,MAAM;YACpB,GAAG,EAAE,UAAU;YACf,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,EAAE,EAAE,OAAO,EAAE,QAAQ,IAAI,IAAI,CAAC,EAAE;SACjC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"serpapi-provider.js","sourceRoot":"","sources":["../../../src/tools/serp-providers/serpapi-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAEhE,MAAM,OAAO,eAAe;IACT,MAAM,CAAgB;IACtB,EAAE,CAAS;IACX,EAAE,CAAS;IAE5B,YAAY,MAAc,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,GAAG,IAAI;QAC9C,IAAI,CAAC,MAAM,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,KAAK,CAAC,MAAM,CACV,KAAa,EACb,OAAuB;QAEvB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC;QAClE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,CAAC;QAEvC,OAAO,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YACtD,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;YACjD,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;YAC7C,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;YACvD,QAAQ,EACN,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;SACpE,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,SAAS,CACb,KAAa,EACb,OAAuB;QAEvB,MAAM,MAAM,GAAoC;YAC9C,CAAC,EAAE,KAAK;YACR,GAAG,EAAE,OAAO,EAAE,UAAU,IAAI,EAAE;YAC9B,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,EAAE,EAAE,OAAO,EAAE,QAAQ,IAAI,IAAI,CAAC,EAAE;SACjC,CAAC;QACF,IAAI,OAAO,EAAE,QAAQ,KAAK,SAAS;YAAE,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACxE,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,MAAM,CAAC,CAAC;IACjE,CAAC;CACF"}

package/dist/tools/serp-tool-factory.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SERP tool factory for creating search tools based on configured provider.
+ *
+ * Reads the SERP_PROVIDER setting and instantiates the appropriate tool
+ * with the resolved provider.
+ */
+import type { ProcessingContext } from "@nodetool-ai/runtime";
+import type { SerpProvider } from "./serp-providers/index.js";
+import type { Tool } from "./base-tool.js";
+/**
+ * Create a search tool based on the configured SERP_PROVIDER setting.
+ *
+ * This is the one `web_search` a belt cannot assemble from the registry: the
+ * resolved provider is bound into the implementation, not into the run, so the
+ * tool is built from the capability's spec over an implementation this factory
+ * closes over.
+ */
+export declare function createSearchTool(context: ProcessingContext): Promise<Tool>;
+/**
+ * Get the current configured SERP provider name.
+ */
+export declare function getConfiguredSerpProvider(context: ProcessingContext): Promise<string>;
+/**
+ * Resolve a provider instance based on the configured SERP_PROVIDER setting.
+ */
+export declare function resolveSerpProvider(context: ProcessingContext): Promise<SerpProvider>;
+//# sourceMappingURL=serp-tool-factory.d.ts.map

package/dist/tools/serp-tool-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serp-tool-factory.d.ts","sourceRoot":"","sources":["../../src/tools/serp-tool-factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AA4B3C;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,YAAY,CAAC,CAQvB"}

package/dist/tools/serp-tool-factory.js

@@ -0,0 +1,56 @@
+/**
+ * SERP tool factory for creating search tools based on configured provider.
+ *
+ * Reads the SERP_PROVIDER setting and instantiates the appropriate tool
+ * with the resolved provider.
+ */
+import { createSerpProvider } from "./serp-providers/index.js";
+import { toolFromCapability, ungatedCapabilityRun } from "../capabilities/index.js";
+import { webSearch, webSearchImpl } from "../capabilities/web.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function getSerpProviderSetting(context) {
+    // Try context first, then env var, then default to 'serpapi'
+    const fromCtx = await context.getSecret("SERP_PROVIDER");
+    if (fromCtx)
+        return fromCtx;
+    const fromEnv = process.env.SERP_PROVIDER;
+    if (fromEnv)
+        return fromEnv;
+    return "serpapi"; // Default to SerpAPI
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a search tool based on the configured SERP_PROVIDER setting.
+ *
+ * This is the one `web_search` a belt cannot assemble from the registry: the
+ * resolved provider is bound into the implementation, not into the run, so the
+ * tool is built from the capability's spec over an implementation this factory
+ * closes over.
+ */
+export async function createSearchTool(context) {
+    const provider = await resolveSerpProvider(context);
+    return toolFromCapability(webSearch.spec, webSearchImpl(provider), ungatedCapabilityRun);
+}
+/**
+ * Get the current configured SERP provider name.
+ */
+export async function getConfiguredSerpProvider(context) {
+    return getSerpProviderSetting(context);
+}
+/**
+ * Resolve a provider instance based on the configured SERP_PROVIDER setting.
+ */
+export async function resolveSerpProvider(context) {
+    const providerType = await getSerpProviderSetting(context);
+    // Bind getSecret to its ProcessingContext receiver. Passing the bare method
+    // reference detaches `this`, so context._secretResolver/userId are undefined
+    // and the secret store is never consulted — SERP keys stored there are lost.
+    return createSerpProvider(providerType, {
+        getSecret: (key) => context.getSecret(key)
+    });
+}
+//# sourceMappingURL=serp-tool-factory.js.map

package/dist/tools/serp-tool-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serp-tool-factory.js","sourceRoot":"","sources":["../../src/tools/serp-tool-factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAElE,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,KAAK,UAAU,sBAAsB,CACnC,OAA0B;IAE1B,6DAA6D;IAC7D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;IACzD,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAC1C,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5B,OAAO,SAAS,CAAC,CAAC,qBAAqB;AACzC,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAA0B;IAE1B,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACpD,OAAO,kBAAkB,CACvB,SAAS,CAAC,IAAI,EACd,aAAa,CAAC,QAAQ,CAAC,EACvB,oBAAoB,CACrB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAA0B;IAE1B,OAAO,sBAAsB,CAAC,OAAO,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAA0B;IAE1B,MAAM,YAAY,GAAG,MAAM,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAC3D,4EAA4E;IAC5E,6EAA6E;IAC7E,6EAA6E;IAC7E,OAAO,kBAAkB,CAAC,YAAY,EAAE;QACtC,SAAS,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC;KACnD,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/shared-tools.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Run-scoped memory tools — progressive-disclosure access to the shared agent
+ * memory a run carries at `context.memory`.
+ *
+ * Earlier versions auto-injected every memory entry into every step's user
+ * message. That worked but was wasteful: large upstream results bloated every
+ * downstream prompt even when the step only needed one specific entry.
+ *
+ * The 2026 pattern is **progressive disclosure**: the model receives a tiny
+ * "what's available" hint up front and pulls full values on demand:
+ *
+ *   1. `list_shared` — returns metadata for all entries (key, kind, title,
+ *      description, source, byte size). No values. Cheap to call.
+ *   2. `read_shared` — returns full values for a list of keys.
+ *   3. `share_result` — publishes a value to the `shared:` namespace so other
+ *      agents and steps can discover it via `list_shared`.
+ *
+ * The three live in the `shared` capability module
+ * (`../capabilities/shared.ts`); this file keeps only the belt they are mounted
+ * from, because mount policy stays with the executor. They are auto-attached to
+ * every {@link StepExecutor}; authors of custom executors call
+ * `getSharedTools()` and append the result to their tool array.
+ */
+import type { Tool } from "./base-tool.js";
+/** Names of the auto-attached memory tools. Useful for filtering / detection. */
+export declare const SHARED_TOOL_NAMES: readonly ["list_shared", "read_shared", "share_result"];
+/**
+ * Returns fresh instances of the three memory tools. Call this once per
+ * executor — every executor needs its own instances so they don't share
+ * mutable state (none currently exists, but this future-proofs).
+ */
+export declare function getSharedTools(): Tool[];
+//# sourceMappingURL=shared-tools.d.ts.map

package/dist/tools/shared-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-tools.d.ts","sourceRoot":"","sources":["../../src/tools/shared-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,YAC5B,aAAa,EACb,aAAa,EACb,cAAc,CACN,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,IAAI,EAAE,CAEvC"}

package/dist/tools/shared-tools.js

@@ -0,0 +1,39 @@
+/**
+ * Run-scoped memory tools — progressive-disclosure access to the shared agent
+ * memory a run carries at `context.memory`.
+ *
+ * Earlier versions auto-injected every memory entry into every step's user
+ * message. That worked but was wasteful: large upstream results bloated every
+ * downstream prompt even when the step only needed one specific entry.
+ *
+ * The 2026 pattern is **progressive disclosure**: the model receives a tiny
+ * "what's available" hint up front and pulls full values on demand:
+ *
+ *   1. `list_shared` — returns metadata for all entries (key, kind, title,
+ *      description, source, byte size). No values. Cheap to call.
+ *   2. `read_shared` — returns full values for a list of keys.
+ *   3. `share_result` — publishes a value to the `shared:` namespace so other
+ *      agents and steps can discover it via `list_shared`.
+ *
+ * The three live in the `shared` capability module
+ * (`../capabilities/shared.ts`); this file keeps only the belt they are mounted
+ * from, because mount policy stays with the executor. They are auto-attached to
+ * every {@link StepExecutor}; authors of custom executors call
+ * `getSharedTools()` and append the result to their tool array.
+ */
+import { toolForCapabilityName } from "../capabilities/lazy-tool.js";
+/** Names of the auto-attached memory tools. Useful for filtering / detection. */
+export const SHARED_TOOL_NAMES = [
+    "list_shared",
+    "read_shared",
+    "share_result"
+];
+/**
+ * Returns fresh instances of the three memory tools. Call this once per
+ * executor — every executor needs its own instances so they don't share
+ * mutable state (none currently exists, but this future-proofs).
+ */
+export function getSharedTools() {
+    return SHARED_TOOL_NAMES.map((name) => toolForCapabilityName(name));
+}
+//# sourceMappingURL=shared-tools.js.map