@omnicross/contracts 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   IMAGE_GENERATION_ERROR_CODES: () => IMAGE_GENERATION_ERROR_CODES,
   KNOWN_MODELS: () => KNOWN_MODELS,
   LEGACY_THINKING_TOKEN_LIMITS: () => LEGACY_THINKING_TOKEN_LIMITS,
+  LEGACY_UNKNOWN_PROVIDER_ID: () => LEGACY_UNKNOWN_PROVIDER_ID,
   LLM_PROVIDER_PRESETS: () => LLM_PROVIDER_PRESETS,
   MAX_CONCURRENCY_DEFAULTS: () => MAX_CONCURRENCY_DEFAULTS,
   MODEL_ALIASES: () => MODEL_ALIASES,
@@ -45,6 +46,7 @@ __export(index_exports, {
   PROVIDER_SEARCH_CONFIGS: () => PROVIDER_SEARCH_CONFIGS,
   REASONING_MODEL_PATTERNS: () => REASONING_MODEL_PATTERNS,
   SUBSCRIPTION_MODEL_CATALOG: () => SUBSCRIPTION_MODEL_CATALOG,
+  SearchProviderError: () => SearchProviderError,
   THINKING_TOKEN_MAP: () => THINKING_TOKEN_MAP,
   WEBHOOK_DESTINATION_TYPES: () => WEBHOOK_DESTINATION_TYPES,
   WEBHOOK_EVENT_KINDS: () => WEBHOOK_EVENT_KINDS,
@@ -56,6 +58,7 @@ __export(index_exports, {
   canDisableThinking: () => canDisableThinking,
   findLegacyTokenLimit: () => findLegacyTokenLimit,
   findTokenLimit: () => findTokenLimit,
+  fromLegacyWebSearchResponse: () => fromLegacyWebSearchResponse,
   getAllProviderPresets: () => getAllProviderPresets,
   getClaudeMaxTokens: () => getClaudeMaxTokens,
   getCodingPlanBaseUrl: () => getCodingPlanBaseUrl,
@@ -66,16 +69,23 @@ __export(index_exports, {
   healthHttpStatus: () => healthHttpStatus,
   isApiProvider: () => isApiProvider,
   isExtendedContextCapable: () => isExtendedContextCapable,
+  isKnownSearchProviderId: () => isKnownSearchProviderId,
   isLocalProvider: () => isLocalProvider,
   isReasoningModel: () => isReasoningModel,
+  isSearchProviderError: () => isSearchProviderError,
   legacyCliBackendToSubscriptionProvider: () => legacyCliBackendToSubscriptionProvider,
+  legacyErrorStringToSearchErrorCode: () => legacyErrorStringToSearchErrorCode,
+  legacyProviderIdToSearchProviderId: () => legacyProviderIdToSearchProviderId,
   lookupCanonicalCapabilities: () => lookupCanonicalCapabilities,
   normalizeModelId: () => normalizeModelId,
   resolveFollowProviderModel: () => resolveFollowProviderModel,
   resolveModelCapabilities: () => resolveModelCapabilities,
   resolveProviderEndpoint: () => resolveProviderEndpoint,
+  searchErrorToLegacyWebSearchResponse: () => searchErrorToLegacyWebSearchResponse,
   subscriptionProviderHasCatalog: () => subscriptionProviderHasCatalog,
-  subscriptionTargetForSession: () => subscriptionTargetForSession
+  subscriptionTargetForSession: () => subscriptionTargetForSession,
+  toLegacyWebSearchResponse: () => toLegacyWebSearchResponse,
+  toSearchErrorShape: () => toSearchErrorShape
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -2582,6 +2592,168 @@ function getProviderSearchConfig(presetId) {
   return PROVIDER_SEARCH_CONFIGS[presetId];
 }
 
+// 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;
+}
+
+// src/search-types.ts
+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";
+}
+
 // src/subscription-model-catalog.ts
 var SUBSCRIPTION_MODEL_CATALOG = {
   claude: ["claude-haiku-4-5", "claude-sonnet-5", "claude-opus-5", "claude-fable-5"],
@@ -2852,6 +3024,7 @@ function isLocalProvider(id) {
   IMAGE_GENERATION_ERROR_CODES,
   KNOWN_MODELS,
   LEGACY_THINKING_TOKEN_LIMITS,
+  LEGACY_UNKNOWN_PROVIDER_ID,
   LLM_PROVIDER_PRESETS,
   MAX_CONCURRENCY_DEFAULTS,
   MODEL_ALIASES,
@@ -2859,6 +3032,7 @@ function isLocalProvider(id) {
   PROVIDER_SEARCH_CONFIGS,
   REASONING_MODEL_PATTERNS,
   SUBSCRIPTION_MODEL_CATALOG,
+  SearchProviderError,
   THINKING_TOKEN_MAP,
   WEBHOOK_DESTINATION_TYPES,
   WEBHOOK_EVENT_KINDS,
@@ -2870,6 +3044,7 @@ function isLocalProvider(id) {
   canDisableThinking,
   findLegacyTokenLimit,
   findTokenLimit,
+  fromLegacyWebSearchResponse,
   getAllProviderPresets,
   getClaudeMaxTokens,
   getCodingPlanBaseUrl,
@@ -2880,14 +3055,21 @@ function isLocalProvider(id) {
   healthHttpStatus,
   isApiProvider,
   isExtendedContextCapable,
+  isKnownSearchProviderId,
   isLocalProvider,
   isReasoningModel,
+  isSearchProviderError,
   legacyCliBackendToSubscriptionProvider,
+  legacyErrorStringToSearchErrorCode,
+  legacyProviderIdToSearchProviderId,
   lookupCanonicalCapabilities,
   normalizeModelId,
   resolveFollowProviderModel,
   resolveModelCapabilities,
   resolveProviderEndpoint,
+  searchErrorToLegacyWebSearchResponse,
   subscriptionProviderHasCatalog,
-  subscriptionTargetForSession
+  subscriptionTargetForSession,
+  toLegacyWebSearchResponse,
+  toSearchErrorShape
 });

package/dist/index.d.cts

@@ -15,6 +15,8 @@ export { DEFAULT_MCP_SESSION_CONFIG, MCPCallToolResponse, MCPTool, MCPToolRespon
 export { MessageBlock, MessageBlockBase, MessageBlockType, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock } from './message-blocks.cjs';
 export { DEFAULT_LITELLM_PRICING_URL, DEFAULT_OPENROUTER_PRICING_URL, PricingConflict, PricingConflictDecision, PricingEntry, PricingEntryInput, PricingFetchResult, PricingResolution, PricingSource, PricingSourceRefreshResult } from './pricing-types.cjs';
 export { CATALOG_VERSION, CODING_PLAN_URL_PRESETS, DEFAULT_SEED_PRESET_IDS, LLM_PROVIDER_PRESETS, MAX_CONCURRENCY_DEFAULTS, PROVIDER_MODEL_MAPPINGS, PROVIDER_SEARCH_CONFIGS, getAllProviderPresets, getCodingPlanBaseUrl, getPresetById, getPresetRevision, getProviderSearchConfig, resolveFollowProviderModel } from './provider-presets/index.cjs';
+export { LEGACY_UNKNOWN_PROVIDER_ID, fromLegacyWebSearchResponse, legacyErrorStringToSearchErrorCode, legacyProviderIdToSearchProviderId, searchErrorToLegacyWebSearchResponse, toLegacyWebSearchResponse } from './search-compat.cjs';
+export { KnownSearchProviderId, OrchestratedSearchResponse, SearchAttempt, SearchAttemptEvent, SearchAttemptOutcome, SearchCompleteEvent, SearchContributionContext, SearchErrorCode, SearchErrorShape, SearchOptions, SearchPolicy, SearchProvider, SearchProviderCapabilities, SearchProviderContribution, SearchProviderDescriptor, SearchProviderDiagnostic, SearchProviderError, SearchProviderErrorInit, SearchProviderHealthStatus, SearchProviderId, SearchProviderSource, SearchRequest, SearchResponse, SearchResult, SearchRuntimeEvent, SearchRuntimeEventBase, SearchTimeRange, SearchTransportKind, SearchUrlReadResult, isKnownSearchProviderId, isSearchProviderError, toSearchErrorShape } from './search-types.cjs';
 export { SUBSCRIPTION_MODEL_CATALOG, subscriptionProviderHasCatalog } from './subscription-model-catalog.cjs';
 export { CANNOT_DISABLE_THINKING_PATTERNS, DEFAULT_MAX_TOKENS, EFFORT_RATIO, LEGACY_THINKING_TOKEN_LIMITS, REASONING_MODEL_PATTERNS, THINKING_TOKEN_MAP, buildAnthropicThinking, buildGeminiThinkingConfig, buildQwenThinkingConfig, calculateThinkingBudget, canDisableThinking, findLegacyTokenLimit, findTokenLimit, getClaudeMaxTokens, getOpenAIReasoningEffort, isReasoningModel } from './thinking-config.cjs';
 export { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageCacheKeySource, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals } from './usage-stats-types.cjs';

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export { DEFAULT_MCP_SESSION_CONFIG, MCPCallToolResponse, MCPTool, MCPToolRespon
 export { MessageBlock, MessageBlockBase, MessageBlockType, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock } from './message-blocks.js';
 export { DEFAULT_LITELLM_PRICING_URL, DEFAULT_OPENROUTER_PRICING_URL, PricingConflict, PricingConflictDecision, PricingEntry, PricingEntryInput, PricingFetchResult, PricingResolution, PricingSource, PricingSourceRefreshResult } from './pricing-types.js';
 export { CATALOG_VERSION, CODING_PLAN_URL_PRESETS, DEFAULT_SEED_PRESET_IDS, LLM_PROVIDER_PRESETS, MAX_CONCURRENCY_DEFAULTS, PROVIDER_MODEL_MAPPINGS, PROVIDER_SEARCH_CONFIGS, getAllProviderPresets, getCodingPlanBaseUrl, getPresetById, getPresetRevision, getProviderSearchConfig, resolveFollowProviderModel } from './provider-presets/index.js';
+export { LEGACY_UNKNOWN_PROVIDER_ID, fromLegacyWebSearchResponse, legacyErrorStringToSearchErrorCode, legacyProviderIdToSearchProviderId, searchErrorToLegacyWebSearchResponse, toLegacyWebSearchResponse } from './search-compat.js';
+export { KnownSearchProviderId, OrchestratedSearchResponse, SearchAttempt, SearchAttemptEvent, SearchAttemptOutcome, SearchCompleteEvent, SearchContributionContext, SearchErrorCode, SearchErrorShape, SearchOptions, SearchPolicy, SearchProvider, SearchProviderCapabilities, SearchProviderContribution, SearchProviderDescriptor, SearchProviderDiagnostic, SearchProviderError, SearchProviderErrorInit, SearchProviderHealthStatus, SearchProviderId, SearchProviderSource, SearchRequest, SearchResponse, SearchResult, SearchRuntimeEvent, SearchRuntimeEventBase, SearchTimeRange, SearchTransportKind, SearchUrlReadResult, isKnownSearchProviderId, isSearchProviderError, toSearchErrorShape } from './search-types.js';
 export { SUBSCRIPTION_MODEL_CATALOG, subscriptionProviderHasCatalog } from './subscription-model-catalog.js';
 export { CANNOT_DISABLE_THINKING_PATTERNS, DEFAULT_MAX_TOKENS, EFFORT_RATIO, LEGACY_THINKING_TOKEN_LIMITS, REASONING_MODEL_PATTERNS, THINKING_TOKEN_MAP, buildAnthropicThinking, buildGeminiThinkingConfig, buildQwenThinkingConfig, calculateThinkingBudget, canDisableThinking, findLegacyTokenLimit, findTokenLimit, getClaudeMaxTokens, getOpenAIReasoningEffort, isReasoningModel } from './thinking-config.js';
 export { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageCacheKeySource, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals } from './usage-stats-types.js';

package/dist/index.js

@@ -2501,6 +2501,168 @@ function getProviderSearchConfig(presetId) {
   return PROVIDER_SEARCH_CONFIGS[presetId];
 }
 
+// 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;
+}
+
+// src/search-types.ts
+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";
+}
+
 // src/subscription-model-catalog.ts
 var SUBSCRIPTION_MODEL_CATALOG = {
   claude: ["claude-haiku-4-5", "claude-sonnet-5", "claude-opus-5", "claude-fable-5"],
@@ -2770,6 +2932,7 @@ export {
   IMAGE_GENERATION_ERROR_CODES,
   KNOWN_MODELS,
   LEGACY_THINKING_TOKEN_LIMITS,
+  LEGACY_UNKNOWN_PROVIDER_ID,
   LLM_PROVIDER_PRESETS,
   MAX_CONCURRENCY_DEFAULTS,
   MODEL_ALIASES,
@@ -2777,6 +2940,7 @@ export {
   PROVIDER_SEARCH_CONFIGS,
   REASONING_MODEL_PATTERNS,
   SUBSCRIPTION_MODEL_CATALOG,
+  SearchProviderError,
   THINKING_TOKEN_MAP,
   WEBHOOK_DESTINATION_TYPES,
   WEBHOOK_EVENT_KINDS,
@@ -2788,6 +2952,7 @@ export {
   canDisableThinking,
   findLegacyTokenLimit,
   findTokenLimit,
+  fromLegacyWebSearchResponse,
   getAllProviderPresets,
   getClaudeMaxTokens,
   getCodingPlanBaseUrl,
@@ -2798,14 +2963,21 @@ export {
   healthHttpStatus,
   isApiProvider,
   isExtendedContextCapable,
+  isKnownSearchProviderId,
   isLocalProvider,
   isReasoningModel,
+  isSearchProviderError,
   legacyCliBackendToSubscriptionProvider,
+  legacyErrorStringToSearchErrorCode,
+  legacyProviderIdToSearchProviderId,
   lookupCanonicalCapabilities,
   normalizeModelId,
   resolveFollowProviderModel,
   resolveModelCapabilities,
   resolveProviderEndpoint,
+  searchErrorToLegacyWebSearchResponse,
   subscriptionProviderHasCatalog,
-  subscriptionTargetForSession
+  subscriptionTargetForSession,
+  toLegacyWebSearchResponse,
+  toSearchErrorShape
 };

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
+});