@omnicross/core 0.2.0 → 0.3.0

package/dist/chunk-E4QHVXV5.cjs

@@ -0,0 +1,118 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }// src/search/frontends.ts
+var SEARCH_FRONTEND_NAMES = Object.freeze([
+  "codex",
+  "responses",
+  "anthropic"
+]);
+var SEARCH_FRONTEND_MODES = Object.freeze([
+  "native",
+  "managed",
+  "off"
+]);
+var DEFAULT_SEARCH_FRONTEND_MODES = Object.freeze({
+  codex: "off",
+  responses: "native",
+  anthropic: "native"
+});
+var SEARCH_UNSUPPORTED_CAPABILITY_CODE = "unsupported_capability";
+function searchErrorHttpStatus(code) {
+  switch (code) {
+    case "rate_limited":
+      return 429;
+    case "timeout":
+      return 504;
+    case "cancelled":
+      return 499;
+    case "config_missing":
+      return 503;
+    case "auth_failed":
+    case "upstream_unavailable":
+    case "parse_failed":
+    case "policy_denied":
+      return 502;
+    default:
+      return 502;
+  }
+}
+function isSearchFrontendMode(value) {
+  return typeof value === "string" && SEARCH_FRONTEND_MODES.includes(value);
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function normalizeSearchFrontendModes(value) {
+  const raw = _nullishCoalesce(record(value), () => ( {}));
+  const modes = {
+    ...DEFAULT_SEARCH_FRONTEND_MODES
+  };
+  for (const name of SEARCH_FRONTEND_NAMES) {
+    const candidate = raw[name];
+    if (isSearchFrontendMode(candidate)) modes[name] = candidate;
+  }
+  return Object.freeze(modes);
+}
+function validateSearchFrontendModes(value, path = "$.search.modes") {
+  if (value === void 0) return [];
+  const raw = record(value);
+  if (!raw) return [`${path}: expected an object`];
+  const errors = [];
+  for (const [key, candidate] of Object.entries(raw)) {
+    if (!SEARCH_FRONTEND_NAMES.includes(key)) {
+      errors.push(`${path}.${key}: unknown frontend (expected ${SEARCH_FRONTEND_NAMES.join(", ")})`);
+      continue;
+    }
+    if (isSearchFrontendMode(candidate)) continue;
+    errors.push(
+      `${path}.${key}: not a mode (got ${typeof candidate}; expected ${SEARCH_FRONTEND_MODES.join(", ")})`
+    );
+  }
+  return errors;
+}
+
+// src/search/webSearchBackendCompat.ts
+
+
+
+var _searchcompat = require('@omnicross/contracts/search-compat');
+var _searchtypes = require('@omnicross/contracts/search-types');
+function searchRuntimeAsWebSearchBackend(runtime, options = {}) {
+  return {
+    async search(query, providerId, searchOptions) {
+      try {
+        const response = await runtime.search({
+          query,
+          provider: providerId,
+          // `WebSearchOptions` is a strict subset of `SearchOptions` with
+          // identical field names — asserted in the contracts tests.
+          ...searchOptions === void 0 ? {} : { options: searchOptions }
+        });
+        return _searchcompat.toLegacyWebSearchResponse.call(void 0, response);
+      } catch (error) {
+        return _searchcompat.searchErrorToLegacyWebSearchResponse.call(void 0, query, _searchtypes.toSearchErrorShape.call(void 0, error));
+      }
+    },
+    isProviderEnabled(id) {
+      return runtime.listProviders().some((descriptor) => descriptor.id === id);
+    },
+    async readUrl(url, readOptions) {
+      if (options.readUrl !== void 0) return options.readUrl(url, readOptions);
+      return {
+        success: false,
+        url,
+        error: "URL reading is not available through the search runtime adapter"
+      };
+    }
+  };
+}
+
+
+
+
+
+
+
+
+
+
+
+exports.SEARCH_FRONTEND_NAMES = SEARCH_FRONTEND_NAMES; exports.SEARCH_FRONTEND_MODES = SEARCH_FRONTEND_MODES; exports.DEFAULT_SEARCH_FRONTEND_MODES = DEFAULT_SEARCH_FRONTEND_MODES; exports.SEARCH_UNSUPPORTED_CAPABILITY_CODE = SEARCH_UNSUPPORTED_CAPABILITY_CODE; exports.searchErrorHttpStatus = searchErrorHttpStatus; exports.isSearchFrontendMode = isSearchFrontendMode; exports.normalizeSearchFrontendModes = normalizeSearchFrontendModes; exports.validateSearchFrontendModes = validateSearchFrontendModes; exports.searchRuntimeAsWebSearchBackend = searchRuntimeAsWebSearchBackend;

package/dist/chunk-L7O2YQ5O.js

@@ -0,0 +1,386 @@
+import {
+  builtinHttpSearchContributions
+} from "./chunk-DXWFBBSK.js";
+
+// src/search/orchestrator.ts
+import { SearchProviderError, toSearchErrorShape } from "@omnicross/contracts/search-types";
+import { createHash, randomUUID } from "crypto";
+
+// src/search/normalize.ts
+var DEFAULT_NORMALIZED_MAX_RESULTS = 5;
+var SERP_REDIRECT_RULES = [
+  { domain: "google.com", paths: ["/search", "/goto"] },
+  { domain: "bing.com", paths: ["/search"] },
+  { domain: "duckduckgo.com", paths: ["/html/", "/l/"] },
+  { domain: "baidu.com", paths: ["/s"] }
+];
+function isDirectResultUrl(rawUrl) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  const host = url.hostname.toLowerCase();
+  for (const rule of SERP_REDIRECT_RULES) {
+    if (host !== rule.domain && !host.endsWith(`.${rule.domain}`)) continue;
+    if (rule.paths.includes(url.pathname)) return false;
+  }
+  return true;
+}
+function normalizedResultLimit(maxResults) {
+  const requested = maxResults === void 0 || !Number.isFinite(maxResults) ? DEFAULT_NORMALIZED_MAX_RESULTS : Math.floor(maxResults);
+  return Math.max(1, requested);
+}
+function normalizeSearchResults(results, maxResults) {
+  const limit = normalizedResultLimit(maxResults);
+  const seenUrls = /* @__PURE__ */ new Set();
+  const normalized = [];
+  for (const result of results) {
+    if (result === null || typeof result !== "object") continue;
+    const title = typeof result.title === "string" ? result.title.trim() : "";
+    const url = typeof result.url === "string" ? result.url.trim() : "";
+    if (title.length === 0 || !isDirectResultUrl(url)) continue;
+    if (seenUrls.has(url)) continue;
+    seenUrls.add(url);
+    normalized.push({
+      title,
+      url,
+      content: typeof result.content === "string" ? result.content.trim() : ""
+    });
+    if (normalized.length >= limit) break;
+  }
+  return normalized;
+}
+
+// src/search/orchestrator.ts
+var QUERY_HASH_LENGTH = 12;
+function hashSearchQuery(query) {
+  return createHash("sha256").update(query).digest("hex").slice(0, QUERY_HASH_LENGTH);
+}
+var SearchOrchestrator = class {
+  registry;
+  defaultPolicy;
+  onEvent;
+  constructor(registry, options = {}) {
+    this.registry = registry;
+    this.defaultPolicy = options.policy ?? {};
+    this.onEvent = options.onEvent;
+  }
+  /**
+   * Run one search.
+   *
+   * @param request - the query, an optional pinned provider, and per-request
+   *   options. `options` is passed to the provider untouched: providers own
+   *   their own timeouts and the orchestrator adds no second timeout layer.
+   * @param policyOverride - per-request policy, merged field-by-field over the
+   *   orchestrator's default.
+   * @throws {SearchProviderError} when no provider produced a response.
+   */
+  async search(request, policyOverride) {
+    const policy = { ...this.defaultPolicy, ...policyOverride };
+    const requestId = randomUUID();
+    const queryHash = hashSearchQuery(request.query);
+    const startedAt = Date.now();
+    const attempts = [];
+    const emitComplete = (providerId, resultCount) => {
+      this.emit({
+        type: "search_complete",
+        requestId,
+        queryHash,
+        ...providerId === void 0 ? {} : { providerId },
+        resultCount,
+        fallbackCount: fallbackCountOf(attempts),
+        durationMs: Date.now() - startedAt
+      });
+    };
+    let plan;
+    try {
+      plan = this.planCandidates(request, policy);
+    } catch (error) {
+      emitComplete(void 0, 0);
+      throw error;
+    }
+    if (plan.skippedPreferred !== void 0) {
+      this.emit({
+        type: "search_attempt",
+        requestId,
+        queryHash,
+        providerId: plan.skippedPreferred.providerId,
+        outcome: "failed",
+        errorCode: plan.skippedPreferred.errorCode,
+        durationMs: 0
+      });
+    }
+    let lastError;
+    for (const candidate of plan.candidates) {
+      const attemptStartedAt = Date.now();
+      try {
+        const produced = await candidate.provider.search(request.query, request.options);
+        const durationMs = Date.now() - attemptStartedAt;
+        const results = normalizeSearchResults(produced, request.options?.maxResults);
+        attempts.push({
+          providerId: candidate.id,
+          outcome: "success",
+          resultCount: results.length,
+          durationMs
+        });
+        this.emit({
+          type: "search_attempt",
+          requestId,
+          queryHash,
+          providerId: candidate.id,
+          outcome: "success",
+          resultCount: results.length,
+          durationMs
+        });
+        emitComplete(candidate.id, results.length);
+        return {
+          query: request.query,
+          providerId: candidate.id,
+          results,
+          attempts,
+          fallbackCount: fallbackCountOf(attempts)
+        };
+      } catch (error) {
+        const durationMs = Date.now() - attemptStartedAt;
+        const shape = toSearchErrorShape(error);
+        const isCancelled = shape.code === "cancelled" || request.options?.signal?.aborted === true;
+        const errorCode = isCancelled ? "cancelled" : shape.code;
+        attempts.push({
+          providerId: candidate.id,
+          outcome: "failed",
+          errorCode,
+          durationMs
+        });
+        this.emit({
+          type: "search_attempt",
+          requestId,
+          queryHash,
+          providerId: candidate.id,
+          outcome: "failed",
+          errorCode,
+          durationMs
+        });
+        if (isCancelled) {
+          emitComplete(void 0, 0);
+          throw shape.code === "cancelled" ? error : new SearchProviderError("cancelled", "search was cancelled by the caller", {
+            providerId: candidate.id,
+            retryable: false,
+            cause: error
+          });
+        }
+        lastError = asSearchProviderError(error, shape.code, shape.message, candidate.id);
+      }
+    }
+    emitComplete(void 0, 0);
+    throw exhaustionError(attempts, lastError);
+  }
+  /** Resolve the candidate list for one request. */
+  planCandidates(request, policy) {
+    if (request.provider !== void 0) {
+      const pinned = this.registry.get(request.provider);
+      if (pinned === void 0) {
+        throw new SearchProviderError(
+          "upstream_unavailable",
+          `search provider '${request.provider}' is not registered in this runtime`,
+          { providerId: request.provider, retryable: false }
+        );
+      }
+      if (!isAllowed(pinned.id, policy)) {
+        throw new SearchProviderError(
+          "policy_denied",
+          `search provider '${request.provider}' is not allowed by the active search policy`,
+          { providerId: request.provider, retryable: false }
+        );
+      }
+      return { candidates: [pinned] };
+    }
+    const allowed = this.registry.list().filter((entry) => isAllowed(entry.id, policy));
+    let ordered = allowed;
+    let skippedPreferred;
+    if (policy.preferred !== void 0) {
+      const preferred = allowed.find((entry) => entry.id === policy.preferred);
+      if (preferred === void 0) {
+        skippedPreferred = {
+          providerId: policy.preferred,
+          errorCode: this.registry.has(policy.preferred) ? "policy_denied" : "upstream_unavailable"
+        };
+      } else {
+        ordered = [preferred, ...allowed.filter((entry) => entry.id !== preferred.id)];
+      }
+    }
+    if (policy.fallbackEnabled === false) ordered = ordered.slice(0, 1);
+    if (policy.maxAttempts !== void 0) {
+      ordered = ordered.slice(0, Math.max(0, Math.floor(policy.maxAttempts)));
+    }
+    return { candidates: ordered, ...skippedPreferred === void 0 ? {} : { skippedPreferred } };
+  }
+  /** Deliver one event. A listener that throws must never fail a search. */
+  emit(event) {
+    if (this.onEvent === void 0) return;
+    try {
+      this.onEvent(event);
+    } catch {
+    }
+  }
+};
+function fallbackCountOf(attempts) {
+  return Math.max(0, attempts.length - 1);
+}
+function isAllowed(id, policy) {
+  return policy.allowed === void 0 || policy.allowed.includes(id);
+}
+function asSearchProviderError(error, code, message, providerId) {
+  if (error instanceof SearchProviderError) return error;
+  return new SearchProviderError(code, message, { providerId, cause: error });
+}
+function exhaustionError(attempts, lastError) {
+  if (attempts.length === 1 && lastError !== void 0) return lastError;
+  if (attempts.length === 0) {
+    return new SearchProviderError(
+      "upstream_unavailable",
+      "no eligible search provider was available (0 attempts)",
+      { retryable: false }
+    );
+  }
+  const trail = attempts.map((attempt) => `${attempt.providerId}:${attempt.errorCode ?? "unknown"}`).join(",");
+  return new SearchProviderError(
+    lastError?.code ?? "upstream_unavailable",
+    `search failed after ${attempts.length} attempt(s)`,
+    { retryable: lastError?.retryable, details: { attempts: trail }, cause: lastError }
+  );
+}
+
+// src/search/registry.ts
+var SearchRegistryError = class _SearchRegistryError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SearchRegistryError";
+    Object.setPrototypeOf(this, _SearchRegistryError.prototype);
+  }
+};
+var SearchProviderRegistry = class {
+  entries = /* @__PURE__ */ new Map();
+  allowBuiltinOverride;
+  nextSequence = 0;
+  constructor(options = {}) {
+    this.allowBuiltinOverride = options.allowBuiltinOverride === true;
+  }
+  /**
+   * Register one provider.
+   *
+   * @param contribution - the provider with its origin, transport, and
+   *   capabilities declared.
+   * @param context - who is registering, for a Phase-2 host. Retained as-is;
+   *   no rule reads it today, and the parameter exists so adding one later is
+   *   not a signature change for every caller.
+   * @throws {SearchRegistryError} on a blank id, a duplicate id, or a host
+   *   contribution colliding with a builtin without `allowBuiltinOverride`.
+   */
+  register(contribution, context) {
+    const id = contribution.id;
+    if (typeof id !== "string" || id.trim().length === 0) {
+      throw new SearchRegistryError("a search provider contribution needs a non-blank id");
+    }
+    const existing = this.entries.get(id);
+    let sequence = this.nextSequence;
+    if (existing !== void 0) {
+      const isPermittedOverride = this.allowBuiltinOverride && contribution.source === "host" && existing.contribution.source === "builtin";
+      if (!isPermittedOverride) {
+        throw new SearchRegistryError(
+          existing.contribution.source === "builtin" && contribution.source === "host" ? `search provider '${id}' is a builtin; overriding it requires allowBuiltinOverride` : `search provider '${id}' is already registered`
+        );
+      }
+      sequence = existing.sequence;
+    } else {
+      this.nextSequence += 1;
+    }
+    this.entries.set(id, { contribution, context, sequence });
+  }
+  /** Whether an id is currently registered. */
+  has(id) {
+    return this.entries.has(id);
+  }
+  /** The contribution registered under `id`, if any. */
+  get(id) {
+    return this.entries.get(id)?.contribution;
+  }
+  /**
+   * Remove a provider.
+   *
+   * The Phase-2 host-disconnect hook: when a host goes away its contributions
+   * go with it, and the id becomes free to register again.
+   *
+   * @returns whether something was removed.
+   */
+  unregister(id) {
+    return this.entries.delete(id);
+  }
+  /**
+   * Every registered contribution, in candidate order.
+   *
+   * `priorityHint` ascending; contributions without a hint come AFTER every
+   * hinted one (an absent hint is "no opinion", not "highest priority"); ties
+   * keep registration order. The builtin HTTP contributions carry no hints, so
+   * today this is exactly registration order.
+   */
+  list() {
+    return [...this.entries.values()].sort((a, b) => {
+      const aHint = a.contribution.priorityHint;
+      const bHint = b.contribution.priorityHint;
+      if (aHint !== bHint) {
+        if (aHint === void 0) return 1;
+        if (bHint === void 0) return -1;
+        return aHint - bHint;
+      }
+      return a.sequence - b.sequence;
+    }).map((entry) => entry.contribution);
+  }
+};
+
+// src/search/runtime.ts
+function createSearchRuntime(options = {}) {
+  const registry = new SearchProviderRegistry({
+    allowBuiltinOverride: options.allowBuiltinOverride === true
+  });
+  for (const contribution of options.contributions ?? builtinHttpSearchContributions()) {
+    registry.register(contribution);
+  }
+  const orchestrator = new SearchOrchestrator(registry, {
+    ...options.policy === void 0 ? {} : { policy: options.policy },
+    ...options.onEvent === void 0 ? {} : { onEvent: options.onEvent }
+  });
+  return {
+    search(request) {
+      return orchestrator.search(request);
+    },
+    registerContribution(contribution, context) {
+      registry.register(contribution, context);
+    },
+    unregisterContribution(id) {
+      return registry.unregister(id);
+    },
+    listProviders() {
+      return registry.list().map((contribution) => ({
+        id: contribution.id,
+        source: contribution.source,
+        kind: contribution.kind,
+        capabilities: { ...contribution.capabilities }
+      }));
+    }
+  };
+}
+
+export {
+  DEFAULT_NORMALIZED_MAX_RESULTS,
+  isDirectResultUrl,
+  normalizedResultLimit,
+  normalizeSearchResults,
+  hashSearchQuery,
+  SearchOrchestrator,
+  SearchRegistryError,
+  SearchProviderRegistry,
+  createSearchRuntime
+};