@omnicross/contracts 0.1.10 → 0.2.1

package/dist/search-compat.cjs

@@ -0,0 +1,130 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/search-compat.ts
+var search_compat_exports = {};
+__export(search_compat_exports, {
+  LEGACY_UNKNOWN_PROVIDER_ID: () => LEGACY_UNKNOWN_PROVIDER_ID,
+  fromLegacyWebSearchResponse: () => fromLegacyWebSearchResponse,
+  legacyErrorStringToSearchErrorCode: () => legacyErrorStringToSearchErrorCode,
+  legacyProviderIdToSearchProviderId: () => legacyProviderIdToSearchProviderId,
+  searchErrorToLegacyWebSearchResponse: () => searchErrorToLegacyWebSearchResponse,
+  toLegacyWebSearchResponse: () => toLegacyWebSearchResponse
+});
+module.exports = __toCommonJS(search_compat_exports);
+var LEGACY_UNKNOWN_PROVIDER_ID = "legacy:unknown";
+var DEFAULT_LEGACY_ERROR_CODE = "upstream_unavailable";
+function legacyProviderIdToSearchProviderId(id) {
+  return id;
+}
+var LEGACY_ERROR_RULES = [
+  // Runtime facts first.
+  { pattern: /abort|cancell?ed|cancell?ing/i, code: "cancelled" },
+  { pattern: /timed ?out|timeout/i, code: "timeout" },
+  // WebSearchService.search()
+  { pattern: /not configured/i, code: "config_missing" },
+  { pattern: /is disabled/i, code: "policy_denied" },
+  { pattern: /not implemented/i, code: "upstream_unavailable" },
+  // HttpOnlyWebSearchService / WebSearchOrchestrator transport availability
+  { pattern: /unavailable in this host/i, code: "upstream_unavailable" },
+  { pattern: /HTTP search transport is unavailable/i, code: "upstream_unavailable" },
+  // Exhausted-candidate summaries (both fallback implementations)
+  { pattern: /No eligible web search provider returned usable results/i, code: "upstream_unavailable" },
+  { pattern: /No keyless HTTP search provider returned usable results/i, code: "upstream_unavailable" },
+  // Anti-bot / anti-decoy refusals — the page came back, it just cannot be trusted.
+  { pattern: /bot-challenge/i, code: "upstream_unavailable" },
+  {
+    pattern: /returned an untrusted search result page|refusing to return possible bot-decoy content/i,
+    code: "upstream_unavailable"
+  },
+  { pattern: /JavaScript-only search shell without result entries/i, code: "upstream_unavailable" },
+  // Response the provider did return, but which could not be turned into results.
+  { pattern: /response contained no result entries/i, code: "parse_failed" },
+  { pattern: /returned an invalid response/i, code: "parse_failed" },
+  { pattern: /returned an invalid result list/i, code: "parse_failed" },
+  { pattern: /returned only duplicate results/i, code: "parse_failed" },
+  { pattern: /returned no usable direct results/i, code: "parse_failed" },
+  { pattern: /returned no results/i, code: "parse_failed" }
+];
+function legacyErrorStringToSearchErrorCode(message) {
+  for (const rule of LEGACY_ERROR_RULES) {
+    if (rule.pattern.test(message)) return rule.code;
+  }
+  return DEFAULT_LEGACY_ERROR_CODE;
+}
+function providerIdFromLegacyErrorString(message) {
+  const match = /^Provider\s+(?!is\b|returned\b|request\b)(\S+)\s+(?:is|not)\b/i.exec(message);
+  return match?.[1];
+}
+function toSearchResult(result) {
+  return { title: result.title, url: result.url, content: result.content };
+}
+function fromLegacyWebSearchResponse(resp) {
+  if (resp.success) {
+    return {
+      ok: true,
+      response: {
+        query: resp.query,
+        providerId: resp.provider ?? LEGACY_UNKNOWN_PROVIDER_ID,
+        results: resp.results.map(toSearchResult)
+      }
+    };
+  }
+  const message = resp.error ?? "Unknown error";
+  const error = {
+    code: legacyErrorStringToSearchErrorCode(message),
+    message
+  };
+  const providerId = resp.provider ?? providerIdFromLegacyErrorString(message);
+  if (providerId !== void 0) error.providerId = providerId;
+  return { ok: false, error };
+}
+function toLegacyWebSearchResponse(response) {
+  return {
+    success: true,
+    query: response.query,
+    results: response.results.map((result) => ({
+      title: result.title,
+      content: result.content,
+      url: result.url
+    })),
+    provider: response.providerId
+  };
+}
+function searchErrorToLegacyWebSearchResponse(query, error) {
+  const response = {
+    success: false,
+    query,
+    results: [],
+    error: error.message.trim().length > 0 ? error.message : error.code
+  };
+  if (error.providerId !== void 0) {
+    response.provider = error.providerId;
+  }
+  return response;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LEGACY_UNKNOWN_PROVIDER_ID,
+  fromLegacyWebSearchResponse,
+  legacyErrorStringToSearchErrorCode,
+  legacyProviderIdToSearchProviderId,
+  searchErrorToLegacyWebSearchResponse,
+  toLegacyWebSearchResponse
+});

package/dist/search-compat.d.cts

@@ -0,0 +1,93 @@
+import { SearchProviderId, SearchResponse, SearchErrorShape, SearchErrorCode } from './search-types.cjs';
+import { WebSearchResponse, WebSearchProviderId } from './websearch-types.cjs';
+
+/**
+ * Legacy ↔ target search conversions — a Phase-1 compat layer.
+ *
+ * **This module is temporary.** It exists so consumers can migrate from the
+ * legacy `WebSearch*` vocabulary in `./websearch-types` to the target
+ * `Search*` vocabulary in `./search-types` one at a time, instead of in one
+ * flag day. It is scheduled for deletion in Phase 2 (阶段8), once no consumer
+ * speaks the legacy shapes; every import of it is migration debt and is meant
+ * to be grep-able as such.
+ *
+ * Nothing here classifies a provider from its id's spelling. The one place a
+ * string is interpreted is {@link legacyErrorStringToSearchErrorCode}, which
+ * translates the *frozen* legacy error literals (recorded in
+ * `docs/design/search-baseline/elftia-search-baseline.md` §6.2) into the stable
+ * taxonomy — a single, tested mapping so the five Phase-1 stages do not each
+ * re-derive one.
+ *
+ * Pure module: no Node, Electron, HTTP, or SDK imports.
+ */
+
+/**
+ * Provider id used when a legacy response carries results but no `provider`.
+ *
+ * Namespaced so it can never collide with a real provider id, and deliberately
+ * not a member of `KnownSearchProviderId` — it marks "the legacy payload did
+ * not say", not a provider.
+ */
+declare const LEGACY_UNKNOWN_PROVIDER_ID: SearchProviderId;
+/**
+ * Widen a legacy provider id into the open id space.
+ *
+ * Identity at runtime; the value is a re-typing, not a translation. Every
+ * member of the closed legacy union is a valid {@link SearchProviderId}.
+ */
+declare function legacyProviderIdToSearchProviderId(id: WebSearchProviderId): SearchProviderId;
+/**
+ * Translate a legacy error string into a stable {@link SearchErrorCode}.
+ *
+ * Total and deterministic: every input returns a code, and the same input
+ * always returns the same one. Unrecognized strings — including a provider's
+ * own transport error text — map to the documented default
+ * `upstream_unavailable`, which is the safe assumption for a fallback policy
+ * (retry a different provider) as opposed to `cancelled` or `policy_denied`,
+ * which stop the loop.
+ *
+ * The recognized strings are the frozen legacy literals from baseline §6.2;
+ * they are asserted verbatim in this module's tests, so a future baseline
+ * drift fails loudly instead of silently re-coding a failure.
+ */
+declare function legacyErrorStringToSearchErrorCode(message: string): SearchErrorCode;
+/**
+ * Convert a legacy provider response into the target vocabulary.
+ *
+ * A legacy `success: false` becomes a taxonomy-coded {@link SearchErrorShape}
+ * (the original string is preserved verbatim in `message`, so the baseline's
+ * comparison oracles still work); a `success: true` becomes a
+ * {@link SearchResponse}, falling back to {@link LEGACY_UNKNOWN_PROVIDER_ID}
+ * when the legacy payload named no provider.
+ */
+declare function fromLegacyWebSearchResponse(resp: WebSearchResponse): {
+    ok: true;
+    response: SearchResponse;
+} | {
+    ok: false;
+    error: SearchErrorShape;
+};
+/**
+ * Convert a target response back into the legacy shape for a consumer that
+ * still speaks it.
+ *
+ * The legacy `provider` field is typed as the closed `WebSearchProviderId`
+ * union, which cannot express the ids Omnicross ships for HTTP providers
+ * (`http-bing`, `http-duckduckgo` — Elftia widened its own copy to
+ * `WebSearchExecutionProviderId` for exactly this reason). The id is preserved
+ * verbatim through a cast rather than dropped: losing which provider produced
+ * a result set is worse than a union the legacy type cannot name, and this
+ * mismatch is one of the reasons the compat layer is temporary.
+ */
+declare function toLegacyWebSearchResponse(response: SearchResponse): WebSearchResponse;
+/**
+ * Render a target error as a legacy failure response.
+ *
+ * The message is passed through unchanged — no code prefix — because legacy
+ * consumers and the baseline oracles compare these strings literally. An empty
+ * message falls back to the taxonomy code so the legacy `error` field is never
+ * blank.
+ */
+declare function searchErrorToLegacyWebSearchResponse(query: string, error: SearchErrorShape): WebSearchResponse;
+
+export { LEGACY_UNKNOWN_PROVIDER_ID, fromLegacyWebSearchResponse, legacyErrorStringToSearchErrorCode, legacyProviderIdToSearchProviderId, searchErrorToLegacyWebSearchResponse, toLegacyWebSearchResponse };

package/dist/search-compat.d.ts

@@ -0,0 +1,93 @@
+import { SearchProviderId, SearchResponse, SearchErrorShape, SearchErrorCode } from './search-types.js';
+import { WebSearchResponse, WebSearchProviderId } from './websearch-types.js';
+
+/**
+ * Legacy ↔ target search conversions — a Phase-1 compat layer.
+ *
+ * **This module is temporary.** It exists so consumers can migrate from the
+ * legacy `WebSearch*` vocabulary in `./websearch-types` to the target
+ * `Search*` vocabulary in `./search-types` one at a time, instead of in one
+ * flag day. It is scheduled for deletion in Phase 2 (阶段8), once no consumer
+ * speaks the legacy shapes; every import of it is migration debt and is meant
+ * to be grep-able as such.
+ *
+ * Nothing here classifies a provider from its id's spelling. The one place a
+ * string is interpreted is {@link legacyErrorStringToSearchErrorCode}, which
+ * translates the *frozen* legacy error literals (recorded in
+ * `docs/design/search-baseline/elftia-search-baseline.md` §6.2) into the stable
+ * taxonomy — a single, tested mapping so the five Phase-1 stages do not each
+ * re-derive one.
+ *
+ * Pure module: no Node, Electron, HTTP, or SDK imports.
+ */
+
+/**
+ * Provider id used when a legacy response carries results but no `provider`.
+ *
+ * Namespaced so it can never collide with a real provider id, and deliberately
+ * not a member of `KnownSearchProviderId` — it marks "the legacy payload did
+ * not say", not a provider.
+ */
+declare const LEGACY_UNKNOWN_PROVIDER_ID: SearchProviderId;
+/**
+ * Widen a legacy provider id into the open id space.
+ *
+ * Identity at runtime; the value is a re-typing, not a translation. Every
+ * member of the closed legacy union is a valid {@link SearchProviderId}.
+ */
+declare function legacyProviderIdToSearchProviderId(id: WebSearchProviderId): SearchProviderId;
+/**
+ * Translate a legacy error string into a stable {@link SearchErrorCode}.
+ *
+ * Total and deterministic: every input returns a code, and the same input
+ * always returns the same one. Unrecognized strings — including a provider's
+ * own transport error text — map to the documented default
+ * `upstream_unavailable`, which is the safe assumption for a fallback policy
+ * (retry a different provider) as opposed to `cancelled` or `policy_denied`,
+ * which stop the loop.
+ *
+ * The recognized strings are the frozen legacy literals from baseline §6.2;
+ * they are asserted verbatim in this module's tests, so a future baseline
+ * drift fails loudly instead of silently re-coding a failure.
+ */
+declare function legacyErrorStringToSearchErrorCode(message: string): SearchErrorCode;
+/**
+ * Convert a legacy provider response into the target vocabulary.
+ *
+ * A legacy `success: false` becomes a taxonomy-coded {@link SearchErrorShape}
+ * (the original string is preserved verbatim in `message`, so the baseline's
+ * comparison oracles still work); a `success: true` becomes a
+ * {@link SearchResponse}, falling back to {@link LEGACY_UNKNOWN_PROVIDER_ID}
+ * when the legacy payload named no provider.
+ */
+declare function fromLegacyWebSearchResponse(resp: WebSearchResponse): {
+    ok: true;
+    response: SearchResponse;
+} | {
+    ok: false;
+    error: SearchErrorShape;
+};
+/**
+ * Convert a target response back into the legacy shape for a consumer that
+ * still speaks it.
+ *
+ * The legacy `provider` field is typed as the closed `WebSearchProviderId`
+ * union, which cannot express the ids Omnicross ships for HTTP providers
+ * (`http-bing`, `http-duckduckgo` — Elftia widened its own copy to
+ * `WebSearchExecutionProviderId` for exactly this reason). The id is preserved
+ * verbatim through a cast rather than dropped: losing which provider produced
+ * a result set is worse than a union the legacy type cannot name, and this
+ * mismatch is one of the reasons the compat layer is temporary.
+ */
+declare function toLegacyWebSearchResponse(response: SearchResponse): WebSearchResponse;
+/**
+ * Render a target error as a legacy failure response.
+ *
+ * The message is passed through unchanged — no code prefix — because legacy
+ * consumers and the baseline oracles compare these strings literally. An empty
+ * message falls back to the taxonomy code so the legacy `error` field is never
+ * blank.
+ */
+declare function searchErrorToLegacyWebSearchResponse(query: string, error: SearchErrorShape): WebSearchResponse;
+
+export { LEGACY_UNKNOWN_PROVIDER_ID, fromLegacyWebSearchResponse, legacyErrorStringToSearchErrorCode, legacyProviderIdToSearchProviderId, searchErrorToLegacyWebSearchResponse, toLegacyWebSearchResponse };

package/dist/search-compat.js

@@ -0,0 +1,100 @@
+// src/search-compat.ts
+var LEGACY_UNKNOWN_PROVIDER_ID = "legacy:unknown";
+var DEFAULT_LEGACY_ERROR_CODE = "upstream_unavailable";
+function legacyProviderIdToSearchProviderId(id) {
+  return id;
+}
+var LEGACY_ERROR_RULES = [
+  // Runtime facts first.
+  { pattern: /abort|cancell?ed|cancell?ing/i, code: "cancelled" },
+  { pattern: /timed ?out|timeout/i, code: "timeout" },
+  // WebSearchService.search()
+  { pattern: /not configured/i, code: "config_missing" },
+  { pattern: /is disabled/i, code: "policy_denied" },
+  { pattern: /not implemented/i, code: "upstream_unavailable" },
+  // HttpOnlyWebSearchService / WebSearchOrchestrator transport availability
+  { pattern: /unavailable in this host/i, code: "upstream_unavailable" },
+  { pattern: /HTTP search transport is unavailable/i, code: "upstream_unavailable" },
+  // Exhausted-candidate summaries (both fallback implementations)
+  { pattern: /No eligible web search provider returned usable results/i, code: "upstream_unavailable" },
+  { pattern: /No keyless HTTP search provider returned usable results/i, code: "upstream_unavailable" },
+  // Anti-bot / anti-decoy refusals — the page came back, it just cannot be trusted.
+  { pattern: /bot-challenge/i, code: "upstream_unavailable" },
+  {
+    pattern: /returned an untrusted search result page|refusing to return possible bot-decoy content/i,
+    code: "upstream_unavailable"
+  },
+  { pattern: /JavaScript-only search shell without result entries/i, code: "upstream_unavailable" },
+  // Response the provider did return, but which could not be turned into results.
+  { pattern: /response contained no result entries/i, code: "parse_failed" },
+  { pattern: /returned an invalid response/i, code: "parse_failed" },
+  { pattern: /returned an invalid result list/i, code: "parse_failed" },
+  { pattern: /returned only duplicate results/i, code: "parse_failed" },
+  { pattern: /returned no usable direct results/i, code: "parse_failed" },
+  { pattern: /returned no results/i, code: "parse_failed" }
+];
+function legacyErrorStringToSearchErrorCode(message) {
+  for (const rule of LEGACY_ERROR_RULES) {
+    if (rule.pattern.test(message)) return rule.code;
+  }
+  return DEFAULT_LEGACY_ERROR_CODE;
+}
+function providerIdFromLegacyErrorString(message) {
+  const match = /^Provider\s+(?!is\b|returned\b|request\b)(\S+)\s+(?:is|not)\b/i.exec(message);
+  return match?.[1];
+}
+function toSearchResult(result) {
+  return { title: result.title, url: result.url, content: result.content };
+}
+function fromLegacyWebSearchResponse(resp) {
+  if (resp.success) {
+    return {
+      ok: true,
+      response: {
+        query: resp.query,
+        providerId: resp.provider ?? LEGACY_UNKNOWN_PROVIDER_ID,
+        results: resp.results.map(toSearchResult)
+      }
+    };
+  }
+  const message = resp.error ?? "Unknown error";
+  const error = {
+    code: legacyErrorStringToSearchErrorCode(message),
+    message
+  };
+  const providerId = resp.provider ?? providerIdFromLegacyErrorString(message);
+  if (providerId !== void 0) error.providerId = providerId;
+  return { ok: false, error };
+}
+function toLegacyWebSearchResponse(response) {
+  return {
+    success: true,
+    query: response.query,
+    results: response.results.map((result) => ({
+      title: result.title,
+      content: result.content,
+      url: result.url
+    })),
+    provider: response.providerId
+  };
+}
+function searchErrorToLegacyWebSearchResponse(query, error) {
+  const response = {
+    success: false,
+    query,
+    results: [],
+    error: error.message.trim().length > 0 ? error.message : error.code
+  };
+  if (error.providerId !== void 0) {
+    response.provider = error.providerId;
+  }
+  return response;
+}
+export {
+  LEGACY_UNKNOWN_PROVIDER_ID,
+  fromLegacyWebSearchResponse,
+  legacyErrorStringToSearchErrorCode,
+  legacyProviderIdToSearchProviderId,
+  searchErrorToLegacyWebSearchResponse,
+  toLegacyWebSearchResponse
+};

package/dist/search-types.cjs

@@ -0,0 +1,102 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/search-types.ts
+var search_types_exports = {};
+__export(search_types_exports, {
+  SearchProviderError: () => SearchProviderError,
+  isKnownSearchProviderId: () => isKnownSearchProviderId,
+  isSearchProviderError: () => isSearchProviderError,
+  toSearchErrorShape: () => toSearchErrorShape
+});
+module.exports = __toCommonJS(search_types_exports);
+var KNOWN_SEARCH_PROVIDER_IDS = /* @__PURE__ */ new Set([
+  "http-bing",
+  "http-duckduckgo",
+  "tavily",
+  "jina",
+  "searxng",
+  "zhipu",
+  "z.ai"
+]);
+function isKnownSearchProviderId(id) {
+  return KNOWN_SEARCH_PROVIDER_IDS.has(id);
+}
+var SEARCH_ERROR_CODES = /* @__PURE__ */ new Set([
+  "config_missing",
+  "auth_failed",
+  "rate_limited",
+  "timeout",
+  "upstream_unavailable",
+  "parse_failed",
+  "cancelled",
+  "policy_denied"
+]);
+var DEFAULT_SEARCH_ERROR_CODE = "upstream_unavailable";
+var SearchProviderError = class _SearchProviderError extends Error {
+  /** Stable taxonomy code. */
+  code;
+  /** The provider that failed, when known. */
+  providerId;
+  /** Whether retrying the same provider could plausibly succeed. */
+  retryable;
+  /** Pre-sanitized string-valued context. */
+  details;
+  constructor(code, message, init = {}) {
+    super(message, init.cause === void 0 ? void 0 : { cause: init.cause });
+    this.name = "SearchProviderError";
+    this.code = code;
+    this.providerId = init.providerId;
+    this.retryable = init.retryable;
+    this.details = init.details;
+    Object.setPrototypeOf(this, _SearchProviderError.prototype);
+  }
+  /** This error as its serializable {@link SearchErrorShape}. */
+  toShape() {
+    return toSearchErrorShape(this);
+  }
+};
+function isSearchProviderError(value) {
+  if (value instanceof SearchProviderError) return true;
+  if (!(value instanceof Error)) return false;
+  const code = value.code;
+  return typeof code === "string" && SEARCH_ERROR_CODES.has(code);
+}
+function toSearchErrorShape(value) {
+  if (isSearchProviderError(value)) {
+    const shape = { code: value.code, message: value.message };
+    if (value.providerId !== void 0) shape.providerId = value.providerId;
+    if (value.retryable !== void 0) shape.retryable = value.retryable;
+    if (value.details !== void 0) shape.details = value.details;
+    return shape;
+  }
+  return { code: DEFAULT_SEARCH_ERROR_CODE, message: describeUnknownError(value) };
+}
+function describeUnknownError(value) {
+  if (typeof value === "string") return value;
+  if (value instanceof Error && value.message) return value.message;
+  return "Unknown error";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SearchProviderError,
+  isKnownSearchProviderId,
+  isSearchProviderError,
+  toSearchErrorShape
+});