@240xu/dsh-websearch 2.0.0

package/lib/index.js

@@ -0,0 +1,277 @@
+/**
+ * dsh-websearch: unified web search provider for the DSH web seam (ctx.web).
+ * Registers ONE provider under id "unified" that fans out to multiple backends
+ * concurrently and merges (URL-deduped) results. Keyless backends (Exa, Parallel,
+ * DuckDuckGo, SearXNG) give zero-config search; key-gated backends (DeepSeek/
+ * Anthropic/OpenAI/Brave/Tavily/Serper/Mojeek) activate when their API key is
+ * stored via the credentials service or the launching environment.
+ *
+ * @module dsh-websearch
+ */
+import z from "@deepseek-ai/schemastery";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import {
+  installSettingsSection,
+  settingsNamespace,
+} from "@deepseek-ai/dsh-settings";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+import { WebError } from "@deepseek-ai/dsh-web";
+
+// Import all backends
+import { exaBackend } from "./backends/exa.js";
+import { parallelBackend } from "./backends/parallel.js";
+import { ddgBackend } from "./backends/ddg.js";
+import {
+  deepseekBackend,
+  anthropicBackend,
+} from "./backends/anthropic-like.js";
+import { openaiBackend } from "./backends/openai.js";
+import { braveBackend } from "./backends/brave.js";
+import { tavilyBackend } from "./backends/tavily.js";
+import { serperBackend } from "./backends/serper.js";
+import { searxngBackend } from "./backends/searxng.js";
+import { mojeekBackend } from "./backends/mojeek.js";
+import { createUnifiedSearchProvider } from "./provider.js";
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = "unified-search";
+/** The web seam this provider registers into. */
+export const inject = ["web"];
+
+/** Settings namespace key. */
+const NAMESPACE = settingsNamespace("unified-search");
+
+/** Full backend registry. Order = default fan-out priority. */
+const BACKENDS = {
+  exa: exaBackend,
+  parallel: parallelBackend,
+  ddg: ddgBackend,
+  searxng: searxngBackend,
+  brave: braveBackend,
+  tavily: tavilyBackend,
+  serper: serperBackend,
+  mojeek: mojeekBackend,
+  deepseek: deepseekBackend,
+  anthropic: anthropicBackend,
+  openai: openaiBackend,
+};
+
+/** All backend ids in registry order. */
+const ALL_BACKENDS = Object.keys(BACKENDS);
+
+/** Backends enabled by default (keyless only). */
+const DEFAULT_ENABLED = ["exa", "parallel", "ddg", "searxng"];
+
+/** Environment-variable names each key-gated backend reads. */
+const DEFAULT_KEY_ENV = {
+  deepseek: "DEEPSEEK_API_KEY",
+  anthropic: "ANTHROPIC_API_KEY",
+  openai: "OPENAI_API_KEY",
+  brave: "BRAVE_API_KEY",
+  tavily: "TAVILY_API_KEY",
+  serper: "SERPER_API_KEY",
+  mojeek: "MOJEEK_API_KEY",
+};
+
+/** Default base URLs. */
+const DEFAULT_BASE_URLS = {
+  exa: "https://mcp.exa.ai/mcp",
+  parallel: "https://search.parallel.ai/mcp",
+  ddg: "https://html.duckduckgo.com/html/",
+  searxng: "https://searx.be",
+  brave: "https://api.search.brave.com/res/v1/web/search",
+  tavily: "https://api.tavily.com/search",
+  serper: "https://google.serper.dev/search",
+  mojeek: "https://api.mojeek.com/v1/search",
+  deepseek: "https://api.deepseek.com/anthropic/v1",
+  anthropic: "https://api.anthropic.com/v1",
+  openai: "https://api.openai.com/v1",
+};
+
+/** Env var that overrides the default backend sweep order / enabled set. */
+const ENABLED_ENV = "DSH_UNIFIED_SEARCH_BACKENDS";
+
+/** Default models for model-carrying backends. */
+const DEFAULT_MODELS = {
+  deepseek: "deepseek-v4-flash",
+  anthropic: "claude-sonnet-4-6",
+  openai: "gpt-4o",
+};
+
+/**
+ * GUI-friendly labels for each backend (shown in the Settings panel).
+ */
+const DEFAULT_LABELS = {
+  exa: "Exa (MCP, 免费无 Key)",
+  parallel: "Parallel (MCP, 免费无 Key)",
+  ddg: "DuckDuckGo (HTML 抓取, 兜底)",
+  searxng: "SearXNG (元搜索, 免费无 Key)",
+  brave: "Brave Search (独立索引, 2000/月免费)",
+  tavily: "Tavily (AI 专用, 含答案摘要)",
+  serper: "Serper.dev (Google 抓取, 2500/月免费)",
+  mojeek: "Mojeek (独立索引, 1000/天免费)",
+  deepseek: "DeepSeek (原生 web_search, 需 Key)",
+  anthropic: "Anthropic (Claude 原生 web_search, 需 Key)",
+  openai: "OpenAI (Responses API web_search, 需 Key)",
+};
+
+/**
+ * Settings schema — flat, GUI-friendly. Every object property is optional by
+ * default in schemastery; defaults are supplied via .default(). API keys are
+ * credential-refs (env-var names), which the Settings UI renders as a
+ * credential selector / secret field.
+ */
+export const Config = z.object({
+  // Global
+  numResults: z.number().step(1).min(1).max(50).default(8)
+    .description("每次搜索返回的最大结果数"),
+  concurrency: z.number().step(1).min(1).max(10).default(6)
+    .description("同时并发的后端数量"),
+  backendTimeoutMs: z.number().step(1000).min(1000).max(120000).default(30000)
+    .description("单后端最大等待时间（毫秒）"),
+
+  // Enable toggles (one per backend)
+  enableExa: z.boolean().default(true).description(DEFAULT_LABELS.exa),
+  enableParallel: z.boolean().default(true).description(DEFAULT_LABELS.parallel),
+  enableDdg: z.boolean().default(true).description(DEFAULT_LABELS.ddg),
+  enableSearxng: z.boolean().default(true).description(DEFAULT_LABELS.searxng),
+  enableBrave: z.boolean().default(false).description(DEFAULT_LABELS.brave),
+  enableTavily: z.boolean().default(false).description(DEFAULT_LABELS.tavily),
+  enableSerper: z.boolean().default(false).description(DEFAULT_LABELS.serper),
+  enableMojeek: z.boolean().default(false).description(DEFAULT_LABELS.mojeek),
+  enableDeepseek: z.boolean().default(false).description(DEFAULT_LABELS.deepseek),
+  enableAnthropic: z.boolean().default(false).description(DEFAULT_LABELS.anthropic),
+  enableOpenai: z.boolean().default(false).description(DEFAULT_LABELS.openai),
+
+  // Credential refs (env-var names; secrets live in the credentials service)
+  braveApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.brave),
+  tavilyApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.tavily),
+  serperApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.serper),
+  mojeekApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.mojeek),
+  deepseekApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.deepseek),
+  anthropicApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.anthropic),
+  openaiApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.openai),
+  searxngApiKeyEnv: z.string().role("credential-ref").default("SEARXNG_API_KEY")
+    .description("SearXNG 私有实例的 API Key（公共实例留空）"),
+
+  // Base URLs (defaults from built-in registry)
+  braveBaseURL: z.string().default(DEFAULT_BASE_URLS.brave),
+  tavilyBaseURL: z.string().default(DEFAULT_BASE_URLS.tavily),
+  serperBaseURL: z.string().default(DEFAULT_BASE_URLS.serper),
+  mojeekBaseURL: z.string().default(DEFAULT_BASE_URLS.mojeek),
+  searxngBaseURL: z.string().default(DEFAULT_BASE_URLS.searxng),
+  deepseekBaseURL: z.string().default(DEFAULT_BASE_URLS.deepseek),
+  anthropicBaseURL: z.string().default(DEFAULT_BASE_URLS.anthropic),
+  openaiBaseURL: z.string().default(DEFAULT_BASE_URLS.openai),
+
+  // Models
+  deepseekModel: z.string().default(DEFAULT_MODELS.deepseek),
+  anthropicModel: z.string().default(DEFAULT_MODELS.anthropic),
+  openaiModel: z.string().default(DEFAULT_MODELS.openai),
+  tavilySearchDepth: z.union(["basic", "advanced"]).default("basic")
+    .description("Tavily 搜索深度"),
+
+  // Legacy compatibility: explicit enabled-backend list overrides toggles
+  enabledBackends: z.array(z.string())
+    .description("显式启用后端列表（优先于上方开关；留空则用开关）"),
+});
+
+/**
+ * Project one resolved settings section into the options snapshot the provider
+ * serves its NEXT search with. Key resolution: credentialRef -> credentials
+ * service -> env.
+ */
+export function resolveOptions(ctx, config) {
+  // 1. Determine enabled backends: explicit list > toggles > env > defaults
+  let enabledBackends = [];
+
+  if (config?.enabledBackends && config.enabledBackends.length > 0) {
+    enabledBackends = config.enabledBackends.filter((id) => ALL_BACKENDS.includes(id));
+  }
+
+  if (enabledBackends.length === 0) {
+    const toggleMap = {
+      exa: config?.enableExa,
+      parallel: config?.enableParallel,
+      ddg: config?.enableDdg,
+      searxng: config?.enableSearxng,
+      brave: config?.enableBrave,
+      tavily: config?.enableTavily,
+      serper: config?.enableSerper,
+      mojeek: config?.enableMojeek,
+      deepseek: config?.enableDeepseek,
+      anthropic: config?.enableAnthropic,
+      openai: config?.enableOpenai,
+    };
+    enabledBackends = ALL_BACKENDS.filter((id) => toggleMap[id] === true);
+  }
+
+  if (enabledBackends.length === 0) {
+    const envList = launchEnvironmentOf(ctx).get(ENABLED_ENV)?.value;
+    if (envList && envList.length > 0) {
+      enabledBackends = envList
+        .split(/[,\s]+/)
+        .map((s) => s.trim())
+        .filter((s) => ALL_BACKENDS.includes(s));
+    }
+  }
+
+  if (enabledBackends.length === 0) {
+    enabledBackends = [...DEFAULT_ENABLED];
+  }
+
+  // 2. Resolve each backend option
+  const backends = {};
+  for (const id of ALL_BACKENDS) {
+    const keyEnvName = config?.[`${id}ApiKeyEnv`] ?? DEFAULT_KEY_ENV[id];
+    const ref = credentialRef(keyEnvName);
+
+    backends[id] = {
+      apiKeyEnv: keyEnvName,
+      baseURL: config?.[`${id}BaseURL`] ?? DEFAULT_BASE_URLS[id],
+      model: config?.[`${id}Model`] ?? DEFAULT_MODELS[id],
+      searchDepth: config?.tavilySearchDepth,
+      label: DEFAULT_LABELS[id] ?? id,
+      requiresKey: DEFAULT_KEY_ENV[id] !== undefined,
+      resolveApiKey: async () => {
+        const credentials = ctx.get("credentials");
+        if (credentials !== undefined) return (await credentials.resolve(ref))?.value;
+        const ambient = launchEnvironmentOf(ctx).get(ref);
+        return ambient !== undefined && ambient.value.length > 0 ? ambient.value : undefined;
+      },
+    };
+  }
+
+  return {
+    enabledBackends,
+    numResults: config?.numResults ?? 8,
+    concurrency: config?.concurrency ?? 6,
+    backendTimeoutMs: config?.backendTimeoutMs ?? 30000,
+    backends,
+    ctx,
+  };
+}
+
+/**
+ * Register the unified search provider with ctx.web. Installs a settings
+ * section so users can configure enabled backends / numResults / base URLs /
+ * model names / credential references in the DSH Settings panel.
+ */
+export function apply(ctx, config) {
+  let current = () => config;
+
+  installSettingsSection(ctx, NAMESPACE, Config, config, {
+    setSource: (source) => {
+      current = source;
+    },
+    onChange: () => {},
+  });
+
+  const provider = createUnifiedSearchProvider({
+    ctx,
+    resolveOptions: () => resolveOptions(ctx, current()),
+    backends: BACKENDS,
+  });
+
+  ctx.web.registerSearchProvider(provider);
+}

package/lib/provider.js

@@ -0,0 +1,225 @@
+// provider.js — UnifiedSearchProvider: one ctx.web search provider (id "unified")
+// that fans out to multiple backends concurrently and merges results. This
+// keeps the seam's selection rule happy (only one provider is registered, so
+// no WEB_PROVIDER_AMBIGUOUS error) while giving the user richer results than
+// any single backend alone.
+//
+// Per-backend abort demotion: a single backend throwing WEB_ABORTED becomes a
+// soft null (so other backends still contribute) — UNLESS the caller's own
+// AbortSignal fired (then we rethrow WEB_ABORTED up to the seam). Non-abort
+// failures are also soft: the provider stays usable as long as ≥1 backend
+// returns sources. Only when every enabled backend fails do we throw
+// WEB_PROVIDER_ERROR.
+//
+// Concurrency control: limits simultaneous backend calls to opts.concurrency (default 6).
+// Per-backend timeout: each backend call wrapped with opts.backendTimeoutMs (default 30s).
+
+import { WebError } from "@deepseek-ai/dsh-web";
+import { maybeAbortError, searchAborted, throwIfSearchAborted, isAbortedWebError } from "./util/abort.js";
+import {
+  recordBackendRequest,
+  recordBackendOutcome,
+} from "./util/log.js";
+
+const PROVIDER_ID = "unified";
+
+/**
+ * Simple concurrency limiter using a semaphore pattern.
+ * No external dependency needed.
+ */
+function createLimiter(concurrency) {
+  const queue = [];
+  let running = 0;
+  
+  return function limit(fn) {
+    return new Promise((resolve, reject) => {
+      queue.push({ fn, resolve, reject });
+      process();
+      
+      function process() {
+        while (running < concurrency && queue.length > 0) {
+          const { fn, resolve, reject } = queue.shift();
+          running++;
+          Promise.resolve(fn()).then(resolve).catch(reject).finally(() => {
+            running--;
+            process();
+          });
+        }
+      }
+    });
+  };
+}
+
+/**
+ * Build the UnifiedSearchProvider.
+ *
+ * @param {object} deps
+ * @param {object} deps.ctx          the Cordis plugin context
+ * @param {Function} deps.resolveOptions  () => resolved options snapshot
+ * @param {object} deps.backends     keyed backend registry
+ */
+export function createUnifiedSearchProvider({ ctx, resolveOptions, backends }) {
+  return {
+    id: PROVIDER_ID,
+
+    available() {
+      const opts = resolveOptions();
+      // Provider is usable iff at least one enabled backend is available.
+      for (const id of opts.enabledBackends) {
+        const be = backends[id];
+        if (!be) continue;
+        const beOpts = opts.backends?.[id] ?? {};
+        if (be.available(beOpts)) return true;
+      }
+      return false;
+    },
+
+    /**
+     * Fan out to all enabled & available backends concurrently, merge results
+     * (URL-dedup, keep first-seen snippet/title), enforce maxResults.
+     *
+     * @param {WebSearchRequest} request
+     * @param {AbortSignal} signal
+     * @returns {Promise<WebSearchResult>}
+     */
+    async search(request, signal) {
+      throwIfSearchAborted(signal);
+      const opts = resolveOptions();
+      const maxResults = request.maxResults ?? opts.numResults ?? 8;
+      const concurrency = opts.concurrency ?? 6;
+      const backendTimeoutMs = opts.backendTimeoutMs ?? 30000;
+
+      // Pick enabled & available backends.
+      const eligible = [];
+      for (const id of opts.enabledBackends) {
+        const be = backends[id];
+        if (!be) continue;
+        const beOpts = opts.backends?.[id] ?? {};
+        const avail = be.available(beOpts);
+        if (!avail) continue;
+        eligible.push({ id, backend: be, beOpts });
+      }
+
+      if (eligible.length === 0) {
+        throw new WebError(
+          "unified search: no enabled backend is available (configure a backend or set an API key)",
+          "WEB_PROVIDER_UNAVAILABLE",
+        );
+      }
+
+      // Concurrency limiter
+      const limit = createLimiter(opts.concurrency ?? 6);
+
+      // Wrap each backend call with timeout
+      const runWithTimeout = (backend, req, sig, beOpts, hooks) => {
+        const timeoutMs = backendTimeoutMs;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        
+        // Merge signals
+        const mergedSignal = sig 
+          ? AbortSignal.any([sig, controller.signal])
+          : controller.signal;
+
+        return Promise.race([
+          backend.search(req, mergedSignal, beOpts, hooks),
+          new Promise((_, reject) => {
+            controller.signal.addEventListener('abort', () => {
+              if (controller.signal.reason === 'timeout' || !sig?.aborted) {
+                reject(new WebError(`Backend timed out after ${timeoutMs}ms`, "WEB_PROVIDER_ERROR"));
+              }
+            });
+          })
+        ]).finally(() => clearTimeout(timeoutId));
+      };
+
+      const results = await Promise.allSettled(
+        eligible.map(({ id, backend, beOpts }) => {
+          const recordRequest = (req) => recordBackendRequest(ctx, id, req);
+          const recordOutcome = (out) => recordBackendOutcome(ctx, id, out);
+          const hooks = { recordRequest, recordOutcome };
+          
+          return limit(async () => {
+            return runWithTimeout(backend, request, signal, beOpts, hooks);
+          });
+        }),
+      );
+
+      throwIfSearchAborted(signal);
+
+      // Merge: dedup by url (case-insensitive normalized), keep first-seen
+      // non-empty title/snippet/publishedAt. Tolerate soft-null settled values.
+      const seen = new Set();
+      const merged = [];
+      let mergedContent;
+      let hardAborted = false;
+      let hardError = null;
+      const failures = [];
+
+      for (const settled of results) {
+        if (settled.status === "fulfilled") {
+          if (mergedContent === undefined && typeof settled.value?.content === "string" && settled.value.content.length > 0) {
+            mergedContent = settled.value.content;
+          }
+          const srcs = settled.value?.sources ?? [];
+          for (const s of srcs) {
+            if (!s || typeof s.url !== "string" || s.url.length === 0) continue;
+            const key = s.url.toLowerCase();
+            if (seen.has(key)) {
+              // Merge fields into the existing entry (fill-in missing ones).
+              const existing = merged.find((m) => m.url.toLowerCase() === key);
+              if (existing) {
+                if (!existing.title && s.title) existing.title = s.title;
+                if (!existing.snippet && s.snippet) existing.snippet = s.snippet;
+                if (!existing.publishedAt && s.publishedAt) existing.publishedAt = s.publishedAt;
+              }
+              continue;
+            }
+            seen.add(key);
+            merged.push({ ...s });
+            if (merged.length >= maxResults) break;
+          }
+          if (merged.length >= maxResults) break;
+        } else {
+          // settled.status === "rejected"
+          const err = settled.reason;
+          if (err instanceof WebError && err.code === "WEB_ABORTED") {
+            // Per-backend abort → soft unless caller signal fired.
+            if (signal?.aborted === true) hardAborted = true;
+            else failures.push({ id: "abort", err });
+          } else {
+            failures.push({ id: "error", err });
+            if (hardError === null) hardError = err;
+          }
+        }
+      }
+
+      // Caller-cancellation check (hard abort fires before we yield results).
+      if (signal?.aborted === true || hardAborted) {
+        throw searchAborted(signal);
+      }
+
+      // If we got ANY sources, return them even if some backends failed.
+      if (merged.length > 0) {
+        const sources = merged.slice(0, maxResults);
+        const wasCapped =
+          merged.length > maxResults ||
+          results.some((r) => r.status === "fulfilled" && (r.value?.sources?.length ?? 0) > maxResults);
+        return { sources, ...(mergedContent !== undefined ? { content: mergedContent } : {}), truncated: sources.length >= maxResults && wasCapped };
+      }
+
+      // All enabled backends failed — synthesize a meaningful WEB_PROVIDER_ERROR.
+      const firstDetail =
+        hardError instanceof Error
+          ? hardError.message
+          : String(hardError ?? "unknown");
+      throw new WebError(
+        `unified search: all enabled backends failed (${failures.length}). First: ${firstDetail}`,
+        "WEB_PROVIDER_ERROR",
+        { cause: hardError ?? undefined },
+      );
+    },
+  };
+}
+
+export default { createUnifiedSearchProvider, PROVIDER_ID };

package/lib/util/abort.js

@@ -0,0 +1,82 @@
+/**
+ * @module dsh-websearch/util/abort
+ *
+ * Abort/cancellation plumbing for the unified search provider. The provider
+ * fan-outs to multiple backends concurrently; every backend's fetch must
+ * observe the caller's signal so a cancelled search releases network quota.
+ *
+ * Two WebError codes the seam recognizes:
+ *   - "WEB_ABORTED": user/tool cancelled; no further retries attempted.
+ *   - "WEB_PROVIDER_ERROR": a backend failed (network/http/parse/key-missing).
+ *
+ * A single backend aborting is demoted to a soft null by the provider so other
+ * backends still contribute. Only when the caller-cancellable AbortSignal fires
+ * does the provider throw the hard WEB_ABORTED up to the seam.
+ */
+import { WebError } from "@deepseek-ai/dsh-web";
+
+/** DOMException#AbortError covers both signal.abort() and AbortSignal.timeout(ms). */
+export function isAbortError(error) {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+/** True for any WebError carrying the WEB_ABORTED code. */
+export function isAbortedWebError(error) {
+  return error instanceof WebError && error.code === "WEB_ABORTED";
+}
+
+/** Build the provider's stable cancellation error, retaining the caller's reason. */
+export function searchAborted(signal, fallback) {
+  return new WebError("unified search aborted", "WEB_ABORTED", {
+    cause: signal?.aborted === true ? signal.reason : fallback,
+  });
+}
+
+/** Convenience: throw WEB_ABORTED if the caller already cancelled. */
+export function throwIfSearchAborted(signal) {
+  if (signal?.aborted === true) throw searchAborted(signal);
+}
+
+/**
+ * Race an async operation against caller cancellation. The underlying operation
+ * keeps running after abort (we cannot cancel an in-flight credential resolve);
+ * we just reject the wrapper promise. Backend fetch paths forward signal directly.
+ */
+export function abortable(operation, signal) {
+  if (signal === undefined) return operation;
+  if (signal.aborted) return Promise.reject(searchAborted(signal));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(searchAborted(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error instanceof WebError ? error : new Error(String(error?.message ?? error), { cause: error }));
+      },
+    );
+  });
+}
+
+/**
+ * True when a thrown error reflects caller cancellation (not a backend failure).
+ * Used by backends to decide: demote-to-null vs rethrow. Checks signal.aborted,
+ * DOMException AbortError, and WebError WEB_ABORTED in that order.
+ */
+export function wasAborted(error, signal) {
+  return (
+    signal?.aborted === true ||
+    isAbortError(error) ||
+    isAbortedWebError(error)
+  );
+}
+
+/**
+ * Alias for wasAborted — the backend-facing helper used to decide whether a
+ * caught error should be converted to a soft null (caller cancelled) or
+ * rethrown as WEB_PROVIDER_ERROR (backend failed).
+ */
+export const maybeAbortError = wasAborted;

package/lib/util/log.js

@@ -0,0 +1,51 @@
+/**
+ * @module dsh-websearch/util/log
+ *
+ * Emit a structured "search/backend-request" event onto the current session,
+ * so debugging / token-cost attribution is possible from the dsh session log.
+ * Mirrors the official dsh-web-search-deepseek `recordRequest` pattern but
+ * is per-backend (each backend records its own endpoint + body so it is
+ * auditable which backend fired which request).
+ *
+ * Resilient to missing agents plane — if the session ledger is unavailable,
+ * the call silently no-ops (we MUST NOT break search just because we can't
+ * record an audit row).
+ */
+
+/**
+ * Record one backend request to the current session's event ledger.
+ *
+ * @param {object} ctx - the Cordis plugin context (`ctx.get("agents")`).
+ * @param {string} backendId - e.g. "exa" / "parallel" / "ddg" / "deepseek" / "anthropic" / "openai".
+ * @param {object} request - { endpoint, toolName, body, headers? } — headers are
+ *   filtered by the caller (do not pass Authorization/x-api-key here).
+ */
+export function recordBackendRequest(ctx, backendId, request) {
+  try {
+    const agents = ctx.get?.("agents");
+    const initiator = agents?.currentInitiator?.();
+    const session = initiator?.session;
+    if (session?.append) {
+      session.append("web/unified-search-backend-request", { backendId, ...request, ignorable: true });
+    }
+  } catch {
+    // audit logging is best-effort; never fatal
+  }
+}
+
+/**
+ * Record a backend's final outcome (number of sources returned / error message).
+ * Pairs with recordBackendRequest; useful for token-cost attribution.
+ */
+export function recordBackendOutcome(ctx, backendId, outcome) {
+  try {
+    const agents = ctx.get?.("agents");
+    const initiator = agents?.currentInitiator?.();
+    const session = initiator?.session;
+    if (session?.append) {
+      session.append("web/unified-search-backend-outcome", { backendId, ...outcome, ignorable: true });
+    }
+  } catch {
+    // best-effort
+  }
+}