@pentoshi/clai 4.11.7 → 4.11.9

package/dist/tools/web/search-attempts.js

@@ -0,0 +1,303 @@
+import { searchProviders } from "./providers/provider.js";
+import { MAX_SNIPPET_LENGTH, MAX_TITLE_LENGTH } from "./types.js";
+const MAX_SEARCH_RETRIES = 6;
+const MAX_SEARCH_RETRY_WAIT_MS = 120_000;
+function searchKeyAttemptPlan(keyCount, activeIndex) {
+    if (keyCount <= 0)
+        return [];
+    const start = ((activeIndex % keyCount) + keyCount) % keyCount;
+    return Array.from({ length: keyCount }, (_, offset) => (start + offset) % keyCount);
+}
+function searchAttemptsPerKey(keyCount) {
+    return keyCount <= 1 ? MAX_SEARCH_RETRIES + 1 : 2;
+}
+function shouldStopSearchKeyCircle(outcome) {
+    const status = outcome.error?.status;
+    return status === 404 || status === 422;
+}
+function shouldSwitchSearchKeyImmediately(outcome) {
+    return outcome.error?.kind === "auth" || outcome.error?.status === 402;
+}
+function isRetriableSearchKeyFailure(outcome) {
+    return ["rate-limit", "network", "server"].includes(outcome.error?.kind ?? "");
+}
+function searchRetryWaitMs(outcome, attempt) {
+    return outcome.error?.kind === "rate-limit"
+        ? Math.pow(3, attempt) * 2_000
+        : Math.pow(2, attempt) * 1_000;
+}
+async function waitForSearchRetry(ms, signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new Error("Aborted");
+    await new Promise((resolve, reject) => {
+        const abort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            reject(signal?.reason ?? new Error("Aborted"));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+export async function attemptProviderWithKeyRotation(opts) {
+    const { provider, keys } = opts;
+    const keyCount = keys.keys.length;
+    const plan = provider.needsApiKey
+        ? searchKeyAttemptPlan(keyCount, keys.activeIndex)
+        : [0];
+    let lastOutcome;
+    for (const keyIndex of plan) {
+        const apiKey = provider.needsApiKey ? keys.keys[keyIndex]?.value : undefined;
+        const attempts = opts.retrySameKey && provider.needsApiKey ? searchAttemptsPerKey(keyCount) : 1;
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            const budgetMs = opts.remainingMs();
+            if (budgetMs <= 0 || opts.signal?.aborted) {
+                return buildTimeoutOutcome(provider.id, opts.timeoutMs);
+            }
+            const outcome = await attemptProvider(provider, apiKey, opts.query, opts.maxResults, budgetMs, opts.signal);
+            opts.onOutcome(outcome);
+            if (outcome.ok) {
+                if (provider.needsApiKey && keys.source !== "env" && keys.source !== "injected") {
+                    const { markSearchProviderKeySuccess } = await import("../../store/keys.js");
+                    void markSearchProviderKeySuccess(provider.id, keyIndex).catch(() => { });
+                }
+                return outcome;
+            }
+            lastOutcome = outcome;
+            if (outcome.error?.kind === "timeout" || shouldStopSearchKeyCircle(outcome)) {
+                return outcome;
+            }
+            if (shouldSwitchSearchKeyImmediately(outcome))
+                break;
+            if (!isRetriableSearchKeyFailure(outcome))
+                return outcome;
+            if (!opts.retrySameKey || attempt + 1 >= attempts)
+                break;
+            const wait = searchRetryWaitMs(outcome, attempt);
+            if (wait > MAX_SEARCH_RETRY_WAIT_MS || wait >= opts.remainingMs()) {
+                break;
+            }
+            try {
+                await waitForSearchRetry(wait, opts.signal);
+            }
+            catch {
+                return buildTimeoutOutcome(provider.id, opts.timeoutMs);
+            }
+        }
+    }
+    return lastOutcome ?? buildTimeoutOutcome(provider.id, opts.timeoutMs);
+}
+async function attemptProvider(provider, apiKey, query, maxResults, timeoutMs, callerSignal) {
+    const controller = new AbortController();
+    const onCallerAbort = () => controller.abort();
+    if (callerSignal) {
+        if (callerSignal.aborted)
+            controller.abort();
+        else
+            callerSignal.addEventListener("abort", onCallerAbort);
+    }
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    timer.unref?.();
+    let raw;
+    try {
+        raw = await provider.search(query, maxResults, { ...(apiKey !== undefined ? { apiKey } : {}) }, controller.signal);
+    }
+    catch (err) {
+        return controller.signal.aborted
+            ? buildTimeoutOutcome(provider.id, timeoutMs)
+            : buildNetworkOutcome(provider.id, err);
+    }
+    finally {
+        clearTimeout(timer);
+        if (callerSignal)
+            callerSignal.removeEventListener("abort", onCallerAbort);
+    }
+    const httpError = classifyHttpStatus(provider.id, raw);
+    if (httpError) {
+        return {
+            ok: false,
+            provider: provider.id,
+            results: [],
+            error: httpError,
+        };
+    }
+    if (raw.parseError) {
+        return {
+            ok: false,
+            provider: provider.id,
+            results: [],
+            error: {
+                kind: "parse",
+                provider: provider.id,
+                message: `${provider.displayName}: response parse error (${raw.parseError})`,
+            },
+        };
+    }
+    const filtered = [];
+    for (const hit of raw.hits) {
+        const normalised = normaliseHit(hit);
+        if (!normalised)
+            continue;
+        filtered.push(normalised);
+    }
+    filtered.sort((a, b) => trustHostScore(b.url) - trustHostScore(a.url));
+    const truncated = filtered.slice(0, maxResults);
+    return {
+        ok: true,
+        provider: provider.id,
+        results: truncated,
+    };
+}
+function trustHostScore(url) {
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        if (host.endsWith(".gov") ||
+            host.endsWith(".gov.uk") ||
+            host.endsWith(".gov.au") ||
+            host.endsWith(".europa.eu") ||
+            host === "wikipedia.org" ||
+            host.endsWith(".wikipedia.org")) {
+            return 3;
+        }
+        if (host === "bbc.co.uk" ||
+            host.endsWith(".bbc.co.uk") ||
+            host === "bbc.com" ||
+            host.endsWith(".bbc.com") ||
+            host === "reuters.com" ||
+            host.endsWith(".reuters.com") ||
+            host === "apnews.com" ||
+            host.endsWith(".apnews.com") ||
+            host === "theguardian.com" ||
+            host.endsWith(".theguardian.com") ||
+            host === "nytimes.com" ||
+            host.endsWith(".nytimes.com") ||
+            host.endsWith(".who.int") ||
+            host.endsWith(".un.org")) {
+            return 2;
+        }
+        if (host === "github.com" ||
+            host.endsWith(".github.io") ||
+            host.endsWith(".mozilla.org") ||
+            host.endsWith(".microsoft.com") ||
+            host.endsWith(".apple.com") ||
+            host.endsWith(".google.com") ||
+            host.endsWith(".cloudflare.com")) {
+            return 1;
+        }
+    }
+    catch {
+    }
+    return 0;
+}
+const URL_INVALID_CHARS_RE = /[\s\u0000-\u001f\u007f]/;
+function normaliseHit(hit) {
+    const url = typeof hit.url === "string" ? hit.url : "";
+    if (url.length === 0)
+        return undefined;
+    if (URL_INVALID_CHARS_RE.test(url))
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return undefined;
+    }
+    const title = typeof hit.title === "string" ? hit.title.trim() : "";
+    if (title.length === 0)
+        return undefined;
+    const clampedTitle = title.slice(0, MAX_TITLE_LENGTH);
+    const snippet = typeof hit.snippet === "string" ? hit.snippet : "";
+    const clampedSnippet = snippet.slice(0, MAX_SNIPPET_LENGTH);
+    return {
+        title: clampedTitle,
+        url,
+        snippet: clampedSnippet,
+    };
+}
+function classifyHttpStatus(id, raw) {
+    const provider = searchProviders[id];
+    const displayName = provider?.displayName ?? id;
+    const { status } = raw;
+    if (status === 200)
+        return undefined;
+    if (status > 200 && status < 300) {
+        return {
+            kind: "http",
+            provider: id,
+            status,
+            message: `${displayName}: received HTTP ${status} instead of a results page (typically an anti-bot challenge). Configure a keyed provider with \`clai search-provider brave\` (or \`tavily\`) and \`clai set <provider> <KEY>\`.`,
+        };
+    }
+    if (status === 401 || status === 403) {
+        return {
+            kind: "auth",
+            provider: id,
+            status,
+            message: `${displayName} authentication failed (HTTP ${status}). Run \`clai set ${id}\` to update the key.`,
+        };
+    }
+    if (status === 429) {
+        return {
+            kind: "rate-limit",
+            provider: id,
+            status,
+            message: `${displayName} rate-limited (HTTP 429). Retry later.`,
+        };
+    }
+    if (status >= 500 && status < 600) {
+        return {
+            kind: "server",
+            provider: id,
+            status,
+            message: `${displayName} server error (HTTP ${status}).`,
+        };
+    }
+    if (status === 0) {
+        return {
+            kind: "network",
+            provider: id,
+            message: `${displayName}: provider returned no response (status=0).`,
+        };
+    }
+    return {
+        kind: "http",
+        provider: id,
+        status,
+        message: `${displayName}: HTTP ${status}.`,
+    };
+}
+function buildTimeoutOutcome(id, timeoutMs) {
+    const display = searchProviders[id]?.displayName ?? id;
+    return {
+        ok: false,
+        provider: id,
+        results: [],
+        error: {
+            kind: "timeout",
+            provider: id,
+            message: `${display}: timeout after ${Math.round(timeoutMs / 1000)}s`,
+        },
+    };
+}
+function buildNetworkOutcome(id, err) {
+    const display = searchProviders[id]?.displayName ?? id;
+    const detail = err instanceof Error ? err.message : String(err);
+    return {
+        ok: false,
+        provider: id,
+        results: [],
+        error: {
+            kind: "network",
+            provider: id,
+            message: `${display}: network failure (${detail})`,
+        },
+    };
+}
+//# sourceMappingURL=search-attempts.js.map

package/dist/tools/web/search-attempts.js.map

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

package/dist/tools/web/search.d.ts

@@ -1,23 +1,3 @@
-/**
- * `web.search` registry handler: resolves the active
- * {@link SearchProviderId}, looks up its API key, dispatches a single
- * outbound request per provider (no retry of the *same* provider),
- * validates/truncates the hits to `maxResults`, and emits one audit-log
- * entry per attempt. Failures surface as `ok=false` with a categorical
- * `error.kind` naming the provider.
- *
- * DuckDuckGo fallback: DuckDuckGo is the keyless default and regularly
- * returns anti-bot challenges (HTTP 202) or upstream 502/5xx responses on
- * shared or rate-limited networks. When the active provider is DuckDuckGo
- * and it fails, the handler transparently falls back to a keyed provider
- * — Exa first, then Tavily, then Brave — whenever a key is configured for
- * it. Each
- * fallback is a single attempt against a *different* provider, so the
- * per-provider single-attempt contract (Requirement 6.7) is preserved.
- *
- * Provider modules self-register into {@link searchProviders} on import,
- * so they're eagerly imported here.
- */
 import type { ToolResult } from "../../types.js";
 import type { ToolRunOptions } from "../registry.js";
 import { type SearchProvider } from "./providers/provider.js";
@@ -26,24 +6,11 @@ import "./providers/brave.js";
 import "./providers/tavily.js";
 import "./providers/exa.js";
 import { type SearchProviderId, type WebSearchArgs, type WebSearchErrorKind, type WebSearchOutcome } from "./types.js";
-/**
- * Optional injection points for tests so the search dispatch can be
- * exercised without invoking the real provider modules. Production
- * callers never pass these.
- */
 export interface WebSearchOptions extends ToolRunOptions {
-    /** Override the active provider lookup. */
     provider?: SearchProviderId;
-    /** Override the registered {@link SearchProvider} for the active id. */
     providerOverride?: SearchProvider;
-    /** Override the API-key resolver. Returns the raw key (or undefined). */
     resolveKey?: (id: SearchProviderId) => Promise<string | undefined>;
-    /** Wall-clock timeout in milliseconds. Default: {@link SEARCH_TIMEOUT_MS}. */
     timeoutMs?: number;
 }
-/**
- * Run `web.search`. Always emits a single audit-log entry. Never
- * throws — every failure mode surfaces as `ok=false`.
- */
 export declare function webSearch(args: WebSearchArgs, options?: WebSearchOptions): Promise<ToolResult>;
 export type { WebSearchOutcome, WebSearchErrorKind };