@omnicross/contracts 0.1.0

package/dist/thinking-config.d.cts

@@ -0,0 +1,71 @@
+import { T as ThinkLevel } from './thinking-CBWSLel8.cjs';
+import { M as ModelConfig } from './llm-config-CQjOimv2.cjs';
+
+/**
+ * thinking-config — dependency-light thinking-budget / reasoning-effort helpers.
+ *
+ * The PURE budget/effort functions the `@omnicross/*` packages consume
+ * (`getOpenAIReasoningEffort`, `buildAnthropicThinking`, `calculateThinkingBudget`,
+ * `getClaudeMaxTokens`, `isReasoningModel`, `DEFAULT_MAX_TOKENS`) plus the in-file
+ * regex/numeric data they rely on.
+ *
+ * This module is intentionally import-closed (0 runtime deps): it OMITS any
+ * global model-thinking-level cache + its initializing side-effect (which would
+ * pull the full canonical-models / provider-presets closure into the import
+ * graph) and the cache-fed lookups (`getAvailableThinkLevels` / `validateThinkLevel`),
+ * none of which the `@omnicross/*` packages call.
+ */
+
+/**
+ * Thinking effort → budget ratio (budget = (max - min) * ratio + min). Used only
+ * by token-budget APIs (Claude budget_tokens, Gemini thinking_budget). OpenAI /
+ * DeepSeek discrete reasoning_effort providers pass the level through directly.
+ */
+declare const EFFORT_RATIO: Record<ThinkLevel, number>;
+/** Global default max_tokens — used only when an API requires max_tokens set. */
+declare const DEFAULT_MAX_TOKENS = 4096;
+declare const THINKING_TOKEN_MAP: Record<string, {
+    min: number;
+    max: number;
+}>;
+/** Reasoning-model recognition patterns. */
+declare const REASONING_MODEL_PATTERNS: RegExp[];
+/** Patterns for models that cannot fully disable thinking. */
+declare const CANNOT_DISABLE_THINKING_PATTERNS: RegExp[];
+/** Whether the model supports thinking/reasoning. */
+declare function isReasoningModel(modelId: string): boolean;
+/** Whether the model can disable thinking. */
+declare function canDisableThinking(modelId: string): boolean;
+/**
+ * Resolve the model's thinking-token limit. Prefers a declared
+ * `ModelConfig.thinkingTokenLimit`, else falls back to a regex match.
+ */
+declare function findTokenLimit(modelOrId: string | ModelConfig): {
+    min: number;
+    max: number;
+} | null;
+/**
+ * Calculate the thinking budget for a model + effort level.
+ * Returns undefined when no budget can be computed.
+ */
+declare function calculateThinkingBudget(modelId: string, level: ThinkLevel, userMaxTokens?: number): number | undefined;
+/** Claude max_tokens after subtracting the thinking budget. */
+declare function getClaudeMaxTokens(userMaxTokens: number | undefined, thinkingBudget: number | undefined): number | undefined;
+/** OpenAI reasoning_effort mapping (pass-through; `max` maps to `high`). */
+declare function getOpenAIReasoningEffort(level: ThinkLevel): string | undefined;
+/** Gemini thinkingConfig builder. */
+declare function buildGeminiThinkingConfig(modelId: string, level: ThinkLevel, userMaxTokens?: number): {
+    thinking_budget: number;
+} | undefined;
+/** Anthropic thinking config builder. */
+declare function buildAnthropicThinking(modelId: string, level: ThinkLevel, userMaxTokens?: number): {
+    type: 'enabled';
+    budget_tokens: number;
+} | undefined;
+/** Qwen/DeepSeek enable_thinking config builder. */
+declare function buildQwenThinkingConfig(level: ThinkLevel, userMaxTokens?: number): {
+    enable_thinking: boolean;
+    thinking_budget?: number;
+};
+
+export { CANNOT_DISABLE_THINKING_PATTERNS, DEFAULT_MAX_TOKENS, EFFORT_RATIO, REASONING_MODEL_PATTERNS, THINKING_TOKEN_MAP, buildAnthropicThinking, buildGeminiThinkingConfig, buildQwenThinkingConfig, calculateThinkingBudget, canDisableThinking, findTokenLimit, getClaudeMaxTokens, getOpenAIReasoningEffort, isReasoningModel };

package/dist/thinking-config.d.ts

@@ -0,0 +1,71 @@
+import { T as ThinkLevel } from './thinking-CBWSLel8.js';
+import { M as ModelConfig } from './llm-config-D1jKQLVp.js';
+
+/**
+ * thinking-config — dependency-light thinking-budget / reasoning-effort helpers.
+ *
+ * The PURE budget/effort functions the `@omnicross/*` packages consume
+ * (`getOpenAIReasoningEffort`, `buildAnthropicThinking`, `calculateThinkingBudget`,
+ * `getClaudeMaxTokens`, `isReasoningModel`, `DEFAULT_MAX_TOKENS`) plus the in-file
+ * regex/numeric data they rely on.
+ *
+ * This module is intentionally import-closed (0 runtime deps): it OMITS any
+ * global model-thinking-level cache + its initializing side-effect (which would
+ * pull the full canonical-models / provider-presets closure into the import
+ * graph) and the cache-fed lookups (`getAvailableThinkLevels` / `validateThinkLevel`),
+ * none of which the `@omnicross/*` packages call.
+ */
+
+/**
+ * Thinking effort → budget ratio (budget = (max - min) * ratio + min). Used only
+ * by token-budget APIs (Claude budget_tokens, Gemini thinking_budget). OpenAI /
+ * DeepSeek discrete reasoning_effort providers pass the level through directly.
+ */
+declare const EFFORT_RATIO: Record<ThinkLevel, number>;
+/** Global default max_tokens — used only when an API requires max_tokens set. */
+declare const DEFAULT_MAX_TOKENS = 4096;
+declare const THINKING_TOKEN_MAP: Record<string, {
+    min: number;
+    max: number;
+}>;
+/** Reasoning-model recognition patterns. */
+declare const REASONING_MODEL_PATTERNS: RegExp[];
+/** Patterns for models that cannot fully disable thinking. */
+declare const CANNOT_DISABLE_THINKING_PATTERNS: RegExp[];
+/** Whether the model supports thinking/reasoning. */
+declare function isReasoningModel(modelId: string): boolean;
+/** Whether the model can disable thinking. */
+declare function canDisableThinking(modelId: string): boolean;
+/**
+ * Resolve the model's thinking-token limit. Prefers a declared
+ * `ModelConfig.thinkingTokenLimit`, else falls back to a regex match.
+ */
+declare function findTokenLimit(modelOrId: string | ModelConfig): {
+    min: number;
+    max: number;
+} | null;
+/**
+ * Calculate the thinking budget for a model + effort level.
+ * Returns undefined when no budget can be computed.
+ */
+declare function calculateThinkingBudget(modelId: string, level: ThinkLevel, userMaxTokens?: number): number | undefined;
+/** Claude max_tokens after subtracting the thinking budget. */
+declare function getClaudeMaxTokens(userMaxTokens: number | undefined, thinkingBudget: number | undefined): number | undefined;
+/** OpenAI reasoning_effort mapping (pass-through; `max` maps to `high`). */
+declare function getOpenAIReasoningEffort(level: ThinkLevel): string | undefined;
+/** Gemini thinkingConfig builder. */
+declare function buildGeminiThinkingConfig(modelId: string, level: ThinkLevel, userMaxTokens?: number): {
+    thinking_budget: number;
+} | undefined;
+/** Anthropic thinking config builder. */
+declare function buildAnthropicThinking(modelId: string, level: ThinkLevel, userMaxTokens?: number): {
+    type: 'enabled';
+    budget_tokens: number;
+} | undefined;
+/** Qwen/DeepSeek enable_thinking config builder. */
+declare function buildQwenThinkingConfig(level: ThinkLevel, userMaxTokens?: number): {
+    enable_thinking: boolean;
+    thinking_budget?: number;
+};
+
+export { CANNOT_DISABLE_THINKING_PATTERNS, DEFAULT_MAX_TOKENS, EFFORT_RATIO, REASONING_MODEL_PATTERNS, THINKING_TOKEN_MAP, buildAnthropicThinking, buildGeminiThinkingConfig, buildQwenThinkingConfig, calculateThinkingBudget, canDisableThinking, findTokenLimit, getClaudeMaxTokens, getOpenAIReasoningEffort, isReasoningModel };

package/dist/thinking-config.js

@@ -0,0 +1,205 @@
+// src/thinking-config.ts
+var EFFORT_RATIO = {
+  none: 0.01,
+  minimal: 0.02,
+  low: 0.05,
+  medium: 0.5,
+  high: 0.8,
+  xhigh: 0.92,
+  max: 0.95
+};
+var DEFAULT_MAX_TOKENS = 4096;
+var THINKING_TOKEN_MAP = {
+  // Gemini
+  "gemini-2\\.5-flash-lite": { min: 512, max: 24576 },
+  "gemini-.*-flash": { min: 0, max: 24576 },
+  "gemini-.*-pro": { min: 128, max: 32768 },
+  // Qwen
+  "qwen3-235b-a22b-thinking": { min: 0, max: 81920 },
+  "qwen3-30b-a3b-thinking": { min: 0, max: 81920 },
+  "qwen3-vl-235b-a22b-thinking": { min: 0, max: 81920 },
+  "qwen3-vl-30b-a3b-thinking": { min: 0, max: 81920 },
+  "qwen-plus-2025": { min: 0, max: 38912 },
+  "qwen-plus": { min: 0, max: 81920 },
+  "qwen-turbo": { min: 0, max: 38912 },
+  "qwen-flash": { min: 0, max: 81920 },
+  "qwen3-": { min: 1024, max: 38912 },
+  qwq: { min: 1024, max: 38912 },
+  // Claude (incl. AWS Bedrock, GCP Vertex AI)
+  "claude-opus-4[.-]7": { min: 1024, max: 128e3 },
+  "claude-(sonnet|opus)-4[.-]6": { min: 1024, max: 128e3 },
+  "claude-3[.-]7.*sonnet": { min: 1024, max: 64e3 },
+  "claude-(haiku|sonnet|opus)-4[.-]5": { min: 1024, max: 64e3 },
+  "claude-opus-4[.-]1": { min: 1024, max: 32e3 },
+  "claude-sonnet-4": { min: 1024, max: 64e3 },
+  "claude-opus-4": { min: 1024, max: 32e3 },
+  "claude-3[.-]5-sonnet": { min: 1024, max: 64e3 },
+  // OpenAI o-series
+  "o1-preview": { min: 0, max: 32768 },
+  "o1-mini": { min: 0, max: 32768 },
+  "o1-pro": { min: 0, max: 32768 },
+  "o3-mini": { min: 0, max: 32768 },
+  o3: { min: 0, max: 65536 },
+  "o4-mini": { min: 0, max: 32768 },
+  // GPT-5 series (Response API reasoning models)
+  "gpt-5\\.5": { min: 0, max: 128e3 },
+  "gpt-5\\.4": { min: 0, max: 128e3 },
+  "gpt-5\\.3": { min: 0, max: 128e3 },
+  "gpt-5\\.2": { min: 0, max: 65536 },
+  "gpt-5\\.1": { min: 0, max: 65536 },
+  "gpt-5": { min: 0, max: 65536 },
+  // DeepSeek
+  "deepseek-v4-pro": { min: 0, max: 32768 },
+  "deepseek-v4-flash": { min: 0, max: 32768 },
+  "deepseek-r1": { min: 0, max: 32768 },
+  "deepseek-reasoner": { min: 0, max: 32768 },
+  // Baichuan
+  "baichuan-m2": { min: 0, max: 3e4 },
+  "baichuan-m3": { min: 0, max: 3e4 },
+  // Grok
+  "grok-3": { min: 0, max: 32768 },
+  // Zhipu GLM
+  "glm.*zero": { min: 0, max: 16384 },
+  // Hunyuan
+  "hunyuan.*t1": { min: 0, max: 16384 },
+  // Doubao
+  "doubao.*think": { min: 0, max: 16384 }
+};
+var REASONING_MODEL_PATTERNS = [
+  /^o[134](-mini|-preview|-pro)?$/i,
+  /^gpt-5(\.\d)?(-pro|-codex|-codex-max)?/i,
+  /claude.*3[.-]?5.*sonnet|claude.*sonnet.*3[.-]?5|claude-sonnet-4|claude-opus-4|claude-(haiku|sonnet|opus)-4[.-]?5/i,
+  /gemini.*(2\.0|2-|2\.5|3).*flash|gemini.*(2\.5|3).*pro|gemini.*think/i,
+  /grok-3/i,
+  /qwq|qwen.*qwq|qwen.*thinking/i,
+  /deepseek-v4|deepseek.*r1|r1.*deepseek|deepseek-reasoner/i,
+  /glm.*zero/i,
+  /hunyuan.*t1/i,
+  /doubao.*think/i,
+  /baichuan-m[23]/i
+];
+var CANNOT_DISABLE_THINKING_PATTERNS = [
+  /gemini.*3.*pro/i,
+  /gemini.*2\.5.*pro/i,
+  /^o1-pro$/i
+];
+function isReasoningModel(modelId) {
+  if (!modelId) return false;
+  return REASONING_MODEL_PATTERNS.some((pattern) => pattern.test(modelId));
+}
+function canDisableThinking(modelId) {
+  if (!modelId) return true;
+  return !CANNOT_DISABLE_THINKING_PATTERNS.some((pattern) => pattern.test(modelId));
+}
+function findTokenLimit(modelOrId) {
+  if (!modelOrId) return null;
+  if (typeof modelOrId === "object") {
+    if (modelOrId.thinkingTokenLimit) return modelOrId.thinkingTokenLimit;
+    return findTokenLimit(modelOrId.id);
+  }
+  const lowerModelId = modelOrId.toLowerCase();
+  for (const [pattern, limit] of Object.entries(THINKING_TOKEN_MAP)) {
+    const regex = new RegExp(pattern, "i");
+    if (regex.test(lowerModelId)) {
+      return limit;
+    }
+  }
+  return null;
+}
+function calculateThinkingBudget(modelId, level, userMaxTokens) {
+  if (level === "none") {
+    const tokenLimit2 = findTokenLimit(modelId);
+    if (tokenLimit2 && tokenLimit2.min > 0) {
+      return tokenLimit2.min;
+    }
+    return void 0;
+  }
+  const tokenLimit = findTokenLimit(modelId);
+  const ratio = EFFORT_RATIO[level];
+  if (!tokenLimit) {
+    if (userMaxTokens) {
+      const maxBudget = Math.floor(userMaxTokens * 0.75);
+      return Math.floor(Math.min(userMaxTokens * ratio, maxBudget));
+    }
+    return void 0;
+  }
+  const formulaResult = Math.floor((tokenLimit.max - tokenLimit.min) * ratio + tokenLimit.min);
+  if (userMaxTokens !== void 0) {
+    const maxBudgetFromUserTokens = Math.floor(userMaxTokens * Math.min(ratio, 0.75));
+    return Math.max(tokenLimit.min, Math.min(formulaResult, maxBudgetFromUserTokens));
+  }
+  return formulaResult;
+}
+function getClaudeMaxTokens(userMaxTokens, thinkingBudget) {
+  if (!userMaxTokens) return void 0;
+  if (!thinkingBudget) return userMaxTokens;
+  const outputTokens = userMaxTokens - thinkingBudget;
+  return outputTokens > 0 ? outputTokens : void 0;
+}
+function getOpenAIReasoningEffort(level) {
+  switch (level) {
+    case "none":
+      return "none";
+    case "minimal":
+      return "minimal";
+    case "low":
+      return "low";
+    case "medium":
+      return "medium";
+    case "high":
+      return "high";
+    case "xhigh":
+      return "xhigh";
+    case "max":
+      return "high";
+    default:
+      return void 0;
+  }
+}
+function buildGeminiThinkingConfig(modelId, level, userMaxTokens) {
+  if (!isReasoningModel(modelId)) {
+    return void 0;
+  }
+  const budget = calculateThinkingBudget(modelId, level, userMaxTokens);
+  if (budget === void 0) {
+    return void 0;
+  }
+  return { thinking_budget: budget };
+}
+function buildAnthropicThinking(modelId, level, userMaxTokens) {
+  if (level === "none") {
+    return void 0;
+  }
+  const budget = calculateThinkingBudget(modelId, level, userMaxTokens);
+  if (!budget || budget < 1024) {
+    return { type: "enabled", budget_tokens: 1024 };
+  }
+  return { type: "enabled", budget_tokens: budget };
+}
+function buildQwenThinkingConfig(level, userMaxTokens) {
+  if (level === "none") {
+    return { enable_thinking: false };
+  }
+  const ratio = EFFORT_RATIO[level];
+  const budget = userMaxTokens ? Math.floor(userMaxTokens * ratio) : void 0;
+  return {
+    enable_thinking: true,
+    thinking_budget: budget
+  };
+}
+export {
+  CANNOT_DISABLE_THINKING_PATTERNS,
+  DEFAULT_MAX_TOKENS,
+  EFFORT_RATIO,
+  REASONING_MODEL_PATTERNS,
+  THINKING_TOKEN_MAP,
+  buildAnthropicThinking,
+  buildGeminiThinkingConfig,
+  buildQwenThinkingConfig,
+  calculateThinkingBudget,
+  canDisableThinking,
+  findTokenLimit,
+  getClaudeMaxTokens,
+  getOpenAIReasoningEffort,
+  isReasoningModel
+};

package/dist/usage-types.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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/usage-types.ts
+var usage_types_exports = {};
+module.exports = __toCommonJS(usage_types_exports);

package/dist/usage-types.d.cts

@@ -0,0 +1,41 @@
+/**
+ * Usage statistics types — LLM request token/cost accounting contracts.
+ *
+ * Provider-neutral; no host/storage coupling. The serving core attributes each
+ * captured request with an engine origin + token counts; hosts own their own
+ * persistence rows and aggregation views on top of these shapes.
+ *
+ * @module usage-types
+ */
+/**
+ * Which engine path produced the request. Used for filtering and to
+ * disambiguate duplicate captures from cooperating layers.
+ */
+type UsageEngineOrigin = 
+/** CompletionService transformer / direct API path. */
+'completion'
+/** Claude Agent SDK engine when the host's agent proxy ran the request through the transformer chain. */
+ | 'claude-sdk'
+/** Claude Agent SDK engine + official Anthropic provider — proxy bypassed the transformer chain. */
+ | 'claude-sdk-direct'
+/** Codex CLI run as a model client through the Responses-API ingress. */
+ | 'codex-ingress'
+/** Additional engine origins defined by the embedding host's own engines. */
+ | (string & {});
+/**
+ * Token counts captured from a single LLM response. Names match the union of
+ * Anthropic and OpenAI/Gemini terminology — fields default to 0 when the
+ * provider does not report them.
+ */
+interface UsageTokens {
+    inputTokens: number;
+    outputTokens: number;
+    /** Anthropic prompt-cache hit (charged at the cache_read rate). */
+    cacheReadTokens: number;
+    /** Anthropic prompt-cache write (charged at the cache_write rate). */
+    cacheCreationTokens: number;
+    /** OpenAI o1 / Anthropic extended-thinking — already counted into outputTokens by some providers. */
+    reasoningTokens: number;
+}
+
+export type { UsageEngineOrigin, UsageTokens };

package/dist/usage-types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Usage statistics types — LLM request token/cost accounting contracts.
+ *
+ * Provider-neutral; no host/storage coupling. The serving core attributes each
+ * captured request with an engine origin + token counts; hosts own their own
+ * persistence rows and aggregation views on top of these shapes.
+ *
+ * @module usage-types
+ */
+/**
+ * Which engine path produced the request. Used for filtering and to
+ * disambiguate duplicate captures from cooperating layers.
+ */
+type UsageEngineOrigin = 
+/** CompletionService transformer / direct API path. */
+'completion'
+/** Claude Agent SDK engine when the host's agent proxy ran the request through the transformer chain. */
+ | 'claude-sdk'
+/** Claude Agent SDK engine + official Anthropic provider — proxy bypassed the transformer chain. */
+ | 'claude-sdk-direct'
+/** Codex CLI run as a model client through the Responses-API ingress. */
+ | 'codex-ingress'
+/** Additional engine origins defined by the embedding host's own engines. */
+ | (string & {});
+/**
+ * Token counts captured from a single LLM response. Names match the union of
+ * Anthropic and OpenAI/Gemini terminology — fields default to 0 when the
+ * provider does not report them.
+ */
+interface UsageTokens {
+    inputTokens: number;
+    outputTokens: number;
+    /** Anthropic prompt-cache hit (charged at the cache_read rate). */
+    cacheReadTokens: number;
+    /** Anthropic prompt-cache write (charged at the cache_write rate). */
+    cacheCreationTokens: number;
+    /** OpenAI o1 / Anthropic extended-thinking — already counted into outputTokens by some providers. */
+    reasoningTokens: number;
+}
+
+export type { UsageEngineOrigin, UsageTokens };

package/dist/websearch-types.cjs

@@ -0,0 +1,37 @@
+"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/websearch-types.ts
+var websearch_types_exports = {};
+__export(websearch_types_exports, {
+  isApiProvider: () => isApiProvider,
+  isLocalProvider: () => isLocalProvider
+});
+module.exports = __toCommonJS(websearch_types_exports);
+function isApiProvider(id) {
+  return !id.startsWith("local-");
+}
+function isLocalProvider(id) {
+  return id.startsWith("local-");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isApiProvider,
+  isLocalProvider
+});

package/dist/websearch-types.d.cts

@@ -0,0 +1,76 @@
+/**
+ * Web Search Types
+ *
+ * Provider-neutral web-search contract type definitions.
+ */
+/** Supported search provider IDs */
+type WebSearchProviderId = 'jina' | 'zhipu' | 'z.ai' | 'tavily' | 'exa' | 'searxng' | 'bocha' | 'claude' | 'grok' | 'local-google' | 'local-bing' | 'local-baidu' | 'local-duckduckgo';
+/** Provider type classification */
+type WebSearchProviderType = 'api' | 'local';
+/** Search provider configuration */
+interface WebSearchProviderConfig {
+    /** Unique provider identifier */
+    id: WebSearchProviderId;
+    /** Whether the provider is enabled */
+    enabled: boolean;
+    /** API key(s), comma-separated for rotation */
+    apiKey?: string;
+    /** Custom API host URL */
+    apiHost?: string;
+    /** HTTP basic auth username (for Searxng) */
+    basicAuthUsername?: string;
+    /** HTTP basic auth password (for Searxng) */
+    basicAuthPassword?: string;
+}
+/** Individual search result item */
+interface WebSearchResult {
+    /** Result title */
+    title: string;
+    /** Result content/snippet */
+    content: string;
+    /** Source URL */
+    url: string;
+}
+/** Search response from a provider */
+interface WebSearchResponse {
+    /** Whether the search was successful */
+    success: boolean;
+    /** The search query used */
+    query: string;
+    /** Array of search results */
+    results: WebSearchResult[];
+    /** Provider that performed the search */
+    provider?: WebSearchProviderId;
+    /** Error message if failed */
+    error?: string;
+}
+/** Search options for a single search request */
+interface WebSearchOptions {
+    /** Maximum number of results */
+    maxResults?: number;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Fetch full page content (Jina: uses X-Engine: direct) */
+    fetchPageContent?: boolean;
+}
+/** Jina Reader response for fetching URL content */
+interface JinaReaderResponse {
+    /** Whether the request was successful */
+    success: boolean;
+    /** The URL that was read */
+    url: string;
+    /** Page title */
+    title?: string;
+    /** Page content in markdown format */
+    content?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/** Check if provider is API type */
+declare function isApiProvider(id: WebSearchProviderId): boolean;
+/** Check if provider is local type */
+declare function isLocalProvider(id: WebSearchProviderId): boolean;
+
+export { type JinaReaderResponse, type WebSearchOptions, type WebSearchProviderConfig, type WebSearchProviderId, type WebSearchProviderType, type WebSearchResponse, type WebSearchResult, isApiProvider, isLocalProvider };

package/dist/websearch-types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Web Search Types
+ *
+ * Provider-neutral web-search contract type definitions.
+ */
+/** Supported search provider IDs */
+type WebSearchProviderId = 'jina' | 'zhipu' | 'z.ai' | 'tavily' | 'exa' | 'searxng' | 'bocha' | 'claude' | 'grok' | 'local-google' | 'local-bing' | 'local-baidu' | 'local-duckduckgo';
+/** Provider type classification */
+type WebSearchProviderType = 'api' | 'local';
+/** Search provider configuration */
+interface WebSearchProviderConfig {
+    /** Unique provider identifier */
+    id: WebSearchProviderId;
+    /** Whether the provider is enabled */
+    enabled: boolean;
+    /** API key(s), comma-separated for rotation */
+    apiKey?: string;
+    /** Custom API host URL */
+    apiHost?: string;
+    /** HTTP basic auth username (for Searxng) */
+    basicAuthUsername?: string;
+    /** HTTP basic auth password (for Searxng) */
+    basicAuthPassword?: string;
+}
+/** Individual search result item */
+interface WebSearchResult {
+    /** Result title */
+    title: string;
+    /** Result content/snippet */
+    content: string;
+    /** Source URL */
+    url: string;
+}
+/** Search response from a provider */
+interface WebSearchResponse {
+    /** Whether the search was successful */
+    success: boolean;
+    /** The search query used */
+    query: string;
+    /** Array of search results */
+    results: WebSearchResult[];
+    /** Provider that performed the search */
+    provider?: WebSearchProviderId;
+    /** Error message if failed */
+    error?: string;
+}
+/** Search options for a single search request */
+interface WebSearchOptions {
+    /** Maximum number of results */
+    maxResults?: number;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Fetch full page content (Jina: uses X-Engine: direct) */
+    fetchPageContent?: boolean;
+}
+/** Jina Reader response for fetching URL content */
+interface JinaReaderResponse {
+    /** Whether the request was successful */
+    success: boolean;
+    /** The URL that was read */
+    url: string;
+    /** Page title */
+    title?: string;
+    /** Page content in markdown format */
+    content?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/** Check if provider is API type */
+declare function isApiProvider(id: WebSearchProviderId): boolean;
+/** Check if provider is local type */
+declare function isLocalProvider(id: WebSearchProviderId): boolean;
+
+export { type JinaReaderResponse, type WebSearchOptions, type WebSearchProviderConfig, type WebSearchProviderId, type WebSearchProviderType, type WebSearchResponse, type WebSearchResult, isApiProvider, isLocalProvider };

package/dist/websearch-types.js

@@ -0,0 +1,11 @@
+// src/websearch-types.ts
+function isApiProvider(id) {
+  return !id.startsWith("local-");
+}
+function isLocalProvider(id) {
+  return id.startsWith("local-");
+}
+export {
+  isApiProvider,
+  isLocalProvider
+};