mixdog 0.7.1

package/src/search/lib/backends/anthropic-oauth.mjs

@@ -0,0 +1,98 @@
+/**
+ * Anthropic OAuth search backend.
+ *
+ * Reuses agent.providers.anthropic-oauth credentials (Claude Pro/Max bearer).
+ * Calls Messages API + web_search_20250305 server tool. Model is fixed to
+ * claude-haiku-4-5 — sonnet/opus over OAuth is rate-limited by Anthropic
+ * third-party policy (Jan 2026) and reserved for the agent itself.
+ */
+import { providerHttpError } from '../state.mjs'
+import { AnthropicOAuthProvider } from '../../../agent/orchestrator/providers/anthropic-oauth.mjs'
+
+const API_URL = 'https://api.anthropic.com/v1/messages'
+const ANTHROPIC_VERSION = '2023-06-01'
+const BETA_HEADERS = 'oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,extended-cache-ttl-2025-04-11'
+const MODEL = 'claude-haiku-4-5-20251001'
+const SYSTEM_PROMPT = 'You are an assistant for performing a web search tool use. Use web_search to find current information and reply concisely with the answer and citations.'
+
+// Reuse one provider instance across searches so its in-memory token cache
+// survives between calls — avoids re-loading credentials on every search.
+// ensureAuth() still re-validates via mtime + expiry per use.
+let _sharedProvider = null
+function getSharedProvider() {
+  if (!_sharedProvider) _sharedProvider = new AnthropicOAuthProvider({})
+  return _sharedProvider
+}
+
+export async function searchViaAnthropicOAuth({ query, site, maxResults = 5, locale, warnings = [], signal }) {
+  const t0 = Date.now()
+  const provider = getSharedProvider()
+  await provider.ensureAuth({ reason: 'search' })
+  const tok = provider.credentials?.access_token || provider.credentials?.accessToken
+  if (!tok) throw new Error('[search:anthropic-oauth] no access_token available')
+  const webSearchTool = { type: 'web_search_20250305', name: 'web_search', max_uses: 2 }
+  if (site) webSearchTool.allowed_domains = [site]
+  if (locale?.country || locale?.city || locale?.region || locale?.timezone) {
+    webSearchTool.user_location = {
+      type: 'approximate',
+      ...(locale.country ? { country: locale.country } : {}),
+      ...(locale.city ? { city: locale.city } : {}),
+      ...(locale.region ? { region: locale.region } : {}),
+      ...(locale.timezone ? { timezone: locale.timezone } : {}),
+    }
+  }
+
+  const body = {
+    model: MODEL,
+    max_tokens: 1024,
+    system: [{ type: 'text', text: SYSTEM_PROMPT }],
+    messages: [{
+      role: 'user',
+      content: `${String(query)}\n\nReturn a concise answer and cite at most ${maxResults} source URLs.`,
+    }],
+    tools: [webSearchTool],
+    tool_choice: { type: 'tool', name: 'web_search' },
+    stream: false,
+  }
+
+  const res = await fetch(API_URL, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${tok}`,
+      'anthropic-version': ANTHROPIC_VERSION,
+      'anthropic-beta': BETA_HEADERS,
+      'anthropic-dangerous-direct-browser-access': 'true',
+      'user-agent': 'claude-cli/2.1.77 (external, sdk-cli)',
+      'x-app': 'cli',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+    signal,
+  })
+
+  if (res.status !== 200) {
+    const text = await res.text()
+    throw providerHttpError('anthropic-oauth', res.status, text)
+  }
+  const json = await res.json()
+  const blocks = json?.content || []
+  const answer = blocks.filter(b => b.type === 'text').map(b => b.text).join('').trim()
+  const citations = []
+  for (const b of blocks) {
+    if (b.type === 'web_search_tool_result' && Array.isArray(b.content)) {
+      for (const c of b.content) {
+        if (c?.url) citations.push({ title: c.title || '', url: c.url, snippet: '', source: 'anthropic-oauth' })
+      }
+    }
+  }
+  return {
+    backend: 'anthropic-oauth',
+    model: MODEL,
+    query,
+    answer,
+    citations: citations.slice(0, maxResults),
+    durationMs: Date.now() - t0,
+    usage: json?.usage || null,
+    warnings,
+  }
+}

package/src/search/lib/backends/exa.mjs

@@ -0,0 +1,50 @@
+/**
+ * Exa semantic search backend.
+ *
+ * Uses search.credentials.exa.apiKey. POST /search with type:'auto' so Exa
+ * picks keyword vs neural mode. /contents endpoint integrates fetch-step.
+ */
+import { providerHttpError } from '../state.mjs'
+import { getSearchApiKey } from '../../../shared/config.mjs'
+
+const URL = 'https://api.exa.ai/search'
+
+export async function searchViaExa({ query, limit = 5, site, type = 'web', locale, signal }) {
+  const t0 = Date.now()
+  const key = getSearchApiKey('exa')
+  if (!key) throw new Error('[search:exa] no api key - register via mixdog-search setup -> search-keys')
+  const body = {
+    query: String(query),
+    numResults: limit,
+    type: 'auto',
+    ...(site ? { includeDomains: [site] } : {}),
+    ...(locale?.country ? { userLocation: locale.country } : {}),
+    ...(type === 'news' ? { category: 'news' } : {}),
+  }
+
+  const res = await fetch(URL, {
+    method: 'POST',
+    headers: { 'x-api-key': key, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal,
+  })
+  if (res.status !== 200) {
+    const text = await res.text()
+    throw providerHttpError('exa', res.status, text)
+  }
+  const j = await res.json()
+  const citations = (j?.results || []).slice(0, limit).map(h => ({
+    title: h.title || '',
+    url: h.url || '',
+    snippet: (h.text || h.snippet || '').slice(0, 240),
+    publishedDate: h.publishedDate || h.published_date || null,
+    source: 'exa',
+  }))
+  return {
+    backend: 'exa',
+    query,
+    answer: '',
+    citations,
+    durationMs: Date.now() - t0,
+  }
+}

package/src/search/lib/backends/firecrawl.mjs

@@ -0,0 +1,61 @@
+/**
+ * Firecrawl search backend.
+ *
+ * Uses search.credentials.firecrawl.apiKey (managed via the Setup UI's
+ * search-keys section). Calls /v2/search and returns the raw SERP as
+ * citations. No AI synthesis layer — answer is empty by design; the caller
+ * (or mixdog model) is expected to consume citations directly.
+ */
+import { providerHttpError } from '../state.mjs'
+import { getSearchApiKey } from '../../../shared/config.mjs'
+
+const SEARCH_URL = 'https://api.firecrawl.dev/v2/search'
+
+export async function searchViaFirecrawl({ query, limit = 5, site, type = 'web', locale, signal }) {
+  const t0 = Date.now()
+  const key = getSearchApiKey('firecrawl')
+  if (!key) throw new Error('[search:firecrawl] no api key — register via mixdog-search setup -> search-keys')
+  const source = type === 'images' ? 'images' : type === 'news' ? 'news' : 'web'
+  const body = {
+    query: String(query),
+    limit,
+    sources: [source],
+    ...(site ? { includeDomains: [site] } : {}),
+    ...(locale?.country ? { country: locale.country } : {}),
+  }
+
+  const res = await fetch(SEARCH_URL, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${key}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+    signal,
+  })
+
+  if (res.status !== 200) {
+    const text = await res.text()
+    throw providerHttpError('firecrawl', res.status, text)
+  }
+  const json = await res.json()
+  const data = Array.isArray(json?.data?.[source])
+    ? json.data[source]
+    : Array.isArray(json?.data)
+      ? json.data
+      : []
+  const citations = data.slice(0, limit).map(h => ({
+    title: h.title || '',
+    url: h.url || h.imageUrl || '',
+    snippet: (h.description || h.markdown || h.alt || '').slice(0, 240),
+    publishedDate: h.publishedDate || h.date || null,
+    source: 'firecrawl',
+  }))
+  return {
+    backend: 'firecrawl',
+    query,
+    answer: '',
+    citations,
+    durationMs: Date.now() - t0,
+  }
+}

package/src/search/lib/backends/gemini-api.mjs

@@ -0,0 +1,83 @@
+/**
+ * Gemini API key search backend.
+ *
+ * Reuses agent.providers.gemini.apiKey. Calls generateContent + google_search
+ * tool. Model is config-driven.
+ */
+import { providerHttpError } from '../state.mjs'
+import { getAgentApiKey } from '../../../shared/config.mjs'
+import { GeminiProvider, ensureLatestGeminiModel } from '../../../agent/orchestrator/providers/gemini.mjs'
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+let _geminiWarmProvider = null
+let _geminiWarmProviderKey = ''
+function getGeminiWarmProvider(apiKey) {
+  if (!_geminiWarmProvider || _geminiWarmProviderKey !== apiKey) {
+    _geminiWarmProvider = new GeminiProvider({ apiKey })
+    _geminiWarmProviderKey = apiKey
+  }
+  return _geminiWarmProvider
+}
+
+export async function searchViaGeminiApi({ query, model, maxResults = 5, warnings = [], signal }) {
+  const t0 = Date.now()
+  const key = getAgentApiKey('gemini')
+  if (!key) throw new Error('[search:gemini-api] no api key — set GEMINI_API_KEY or the Gemini provider key in setup')
+  const useModel = model || await ensureLatestGeminiModel(getGeminiWarmProvider(key))
+
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(useModel)}:generateContent?key=${encodeURIComponent(key)}`
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      contents: [{ parts: [{ text: String(query) }] }],
+      tools: [{ google_search: {} }],
+    }),
+    signal,
+  })
+  if (res.status !== 200) {
+    const text = await res.text()
+    throw providerHttpError('gemini-api', res.status, text)
+  }
+  const j = await res.json()
+  const malformed = () => { throw new Error('[search:gemini-api] malformed JSON response') }
+  if (!Array.isArray(j?.candidates)) malformed()
+  const cand = j.candidates[0]
+  if (!isRecord(cand) || !isRecord(cand.content)) malformed()
+  const parts = cand.content.parts
+  if (!Array.isArray(parts)) malformed()
+  const text = parts.map(p => (isRecord(p) && typeof p.text === 'string' ? p.text : undefined)).filter(Boolean).join('').trim()
+  if (!text) malformed()
+  const groundingMetadata = cand.groundingMetadata
+  const groundingChunks = groundingMetadata === undefined
+    ? []
+    : (isRecord(groundingMetadata) && Array.isArray(groundingMetadata.groundingChunks)
+      ? groundingMetadata.groundingChunks
+      : undefined)
+  if (!groundingChunks) malformed()
+  // Keep only well-formed web grounding chunks. Gemini may also emit non-web
+  // grounding sources (e.g. retrievedContext) and occasional empty entries;
+  // dropping those avoids blank citations without rejecting an otherwise valid
+  // grounded response.
+  const chunks = groundingChunks
+    .filter(c => isRecord(c) && isRecord(c.web) && typeof c.web.uri === 'string' && c.web.uri)
+    .map(c => ({
+      title: typeof c.web.title === 'string' ? c.web.title : '',
+      url: c.web.uri,
+      snippet: '',
+      source: 'gemini-api',
+    }))
+  return {
+    backend: 'gemini-api',
+    model: useModel,
+    query,
+    answer: text,
+    citations: chunks.slice(0, maxResults),
+    durationMs: Date.now() - t0,
+    usage: j?.usageMetadata || null,
+    warnings,
+  }
+}

package/src/search/lib/backends/grok-oauth.mjs

@@ -0,0 +1,86 @@
+/**
+ * Grok (xAI) OAuth search backend.
+ *
+ * Same Responses API + web_search (Agent Tools) call as xai-api.mjs, but the
+ * Bearer is a refreshable OAuth access token from the Grok OAuth provider
+ * ("Grok Build" consent / ~/.grok/auth.json) instead of a static API key.
+ * Verified: this OAuth token drives api.x.ai/v1 /responses with the web_search
+ * server tool and returns real citations. Auth + refresh are owned by
+ * GrokOAuthProvider.ensureAuth().
+ */
+import { providerHttpError } from '../state.mjs'
+import { GrokOAuthProvider, ensureLatestGrokModel, normalizeGrokModelId } from '../../../agent/orchestrator/providers/grok-oauth.mjs'
+
+const URL = 'https://api.x.ai/v1/responses'
+
+// Reuse one provider instance across searches so its in-memory token cache
+// (this.tokens) survives between calls — avoids re-reading grok-oauth.json on
+// every search. ensureAuth() still re-validates via mtime + expiry per use.
+let _sharedProvider = null
+function getSharedProvider() {
+  if (!_sharedProvider) _sharedProvider = new GrokOAuthProvider({})
+  return _sharedProvider
+}
+
+export async function searchViaGrokOAuth({ query, model, maxResults = 5, warnings = [], signal }) {
+  const t0 = Date.now()
+  const provider = getSharedProvider()
+  const useModel = normalizeGrokModelId(
+    model || await ensureLatestGrokModel(provider),
+  )
+  const tokens = await provider.ensureAuth()
+  if (!tokens?.access_token) throw new Error('[search:grok-oauth] no access_token available — run the Grok CLI login or the Setup login first')
+
+  const res = await fetch(URL, {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${tokens.access_token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      model: useModel,
+      input: String(query),
+      tools: [{ type: 'web_search' }],
+    }),
+    // Bearer-bearing request — refuse redirects so the OAuth token is never
+    // replayed to a redirect target.
+    redirect: 'error',
+    signal,
+  })
+  if (res.status !== 200) {
+    const text = await res.text()
+    throw providerHttpError('grok-oauth', res.status, text)
+  }
+  const j = await res.json()
+  const items = Array.isArray(j?.output) ? j.output : []
+  // xAI Responses emits output_text either as a direct output item or nested
+  // inside a message; a web_search turn typically pairs a web_search_call item
+  // with a direct output_text item. Collect both shapes (and a top-level
+  // output_text fallback) so a valid search answer is never dropped.
+  const textBlocks = []
+  for (const it of items) {
+    if (it?.type === 'output_text') textBlocks.push(it)
+    else if (it?.type === 'message') {
+      for (const c of (it.content || [])) if (c?.type === 'output_text') textBlocks.push(c)
+    }
+  }
+  let answer = textBlocks.map(b => b?.text || '').join('').trim()
+  if (!answer && typeof j?.output_text === 'string') answer = j.output_text.trim()
+  let citations = textBlocks
+    .flatMap(b => b?.annotations || [])
+    .filter(a => a?.url)
+    .map(a => ({ title: a.title || '', url: a.url || '', snippet: '', source: 'grok-oauth' }))
+  if (!citations.length && Array.isArray(j?.citations)) {
+    citations = j.citations
+      .map(c => (typeof c === 'string' ? { url: c } : c))
+      .filter(c => c?.url)
+      .map(c => ({ title: c.title || '', url: c.url, snippet: '', source: 'grok-oauth' }))
+  }
+  return {
+    backend: 'grok-oauth',
+    model: useModel,
+    query,
+    answer,
+    citations: citations.slice(0, maxResults),
+    durationMs: Date.now() - t0,
+    usage: j?.usage || null,
+    warnings,
+  }
+}

package/src/search/lib/backends/index.mjs

@@ -0,0 +1,150 @@
+/**
+ * Search backend dispatcher.
+ *
+ * `web_fetch` is provider-independent: it uses local readability+puppeteer
+ * extractors via src/search/lib/web-tools.mjs, not provider backends.
+ * 4xx HTTP from a search backend is surfaced as an error — no silent
+ * fallback.
+ */
+import { searchViaAnthropicOAuth } from './anthropic-oauth.mjs'
+import { searchViaFirecrawl } from './firecrawl.mjs'
+import { searchViaOpenAIOAuth } from './openai-oauth.mjs'
+import { searchViaOpenAIApi } from './openai-api.mjs'
+import { searchViaGeminiApi } from './gemini-api.mjs'
+import { searchViaXAIApi } from './xai-api.mjs'
+import { searchViaGrokOAuth } from './grok-oauth.mjs'
+import { searchViaTavily } from './tavily.mjs'
+import { searchViaExa } from './exa.mjs'
+import { normalizeSearchIntent } from '../search-intent.mjs'
+
+/**
+ * Capability matrix for every supported provider.
+ *
+ * `siteMode` controls whether a site restriction is sent as a structured API/tool
+ * parameter or appended to the query for providers that expose no structured
+ * domain filter. `localeMode:none` means an explicit locale is ignored with a
+ * warning rather than being rewritten into the query.
+ */
+export const PROVIDER_CAPS = Object.freeze({
+  'anthropic-oauth': { searchTypes: ['web'],                   siteMode: 'tool',  localeMode: 'tool' },
+  'openai-oauth':    { searchTypes: ['web', 'images'],         siteMode: 'tool',  localeMode: 'tool' },
+  'openai-api':      { searchTypes: ['web', 'images'],         siteMode: 'tool',  localeMode: 'tool' },
+  'gemini-api':      { searchTypes: ['web'],                   siteMode: 'query', localeMode: 'none' },
+  'xai-api':         { searchTypes: ['web'],                   siteMode: 'query', localeMode: 'none' },
+  'grok-oauth':      { searchTypes: ['web'],                   siteMode: 'query', localeMode: 'none' },
+  'tavily':          { searchTypes: ['web', 'news'],           siteMode: 'api',   localeMode: 'api' },
+  'firecrawl':       { searchTypes: ['web', 'news', 'images'], siteMode: 'api',   localeMode: 'api' },
+  'exa':             { searchTypes: ['web', 'news'],           siteMode: 'api',   localeMode: 'api' },
+})
+
+export const SUPPORTED_PROVIDERS = Object.freeze(Object.keys(PROVIDER_CAPS))
+
+function scopedQuery(intent, caps) {
+  return caps?.siteMode === 'api' || caps?.siteMode === 'tool'
+    ? intent.query
+    : intent.queryWithSite
+}
+
+function withSearchTimeout(signal, timeoutMs) {
+  const ms = Number(timeoutMs || 0)
+  if (!Number.isFinite(ms) || ms <= 0) return { signal, cleanup: () => {} }
+  const controller = new AbortController()
+  let timer = null
+  const abortFromParent = () => {
+    try { controller.abort(signal?.reason || new Error('search aborted')) } catch {}
+  }
+  if (signal?.aborted) {
+    abortFromParent()
+  } else if (signal) {
+    signal.addEventListener('abort', abortFromParent, { once: true })
+  }
+  timer = setTimeout(() => {
+    try { controller.abort(new Error(`search timeout after ${ms}ms`)) } catch {}
+  }, ms)
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      if (timer) clearTimeout(timer)
+      if (signal) signal.removeEventListener('abort', abortFromParent)
+    },
+  }
+}
+
+export async function dispatchSearchBackend({ provider, query, keywords, site, type, maxResults, contextSize, locale, signal, config }) {
+  const caps = PROVIDER_CAPS[provider]
+  if (!caps) {
+    throw new Error(`[search:dispatch] unknown provider "${provider}" — supported: ${SUPPORTED_PROVIDERS.join(', ')}`)
+  }
+  const models = config?.models || {}
+  const modelOptions = config?.modelOptions || {}
+  const openaiOpts = modelOptions.openai || {}
+  const intent = normalizeSearchIntent(
+    { query, keywords, site, type, maxResults, contextSize, locale, defaultContextSize: openaiOpts.searchContextSize || 'low' },
+    { caps, defaultMaxResults: config?.rawSearch?.maxResults || 5 },
+  )
+  const { signal: searchSignal, cleanup } = withSearchTimeout(signal, config?.requestTimeoutMs)
+  const common = {
+    query: scopedQuery(intent, caps),
+    rawQuery: intent.rawQuery,
+    site: intent.site,
+    type: intent.type,
+    requestedType: intent.requestedType,
+    maxResults: intent.maxResults,
+    limit: intent.maxResults,
+    locale: caps.localeMode === 'none' ? null : intent.locale,
+    contextSize: intent.contextSize,
+    signal: searchSignal,
+  }
+  try {
+    let result
+    switch (provider) {
+      case 'anthropic-oauth':
+        result = await searchViaAnthropicOAuth(common)
+        break
+      case 'firecrawl':
+        result = await searchViaFirecrawl(common)
+        break
+      case 'openai-oauth':
+        result = await searchViaOpenAIOAuth({ ...common, model: models.openai || undefined, effort: openaiOpts.effort, fast: openaiOpts.fast === true })
+        break
+      case 'openai-api':
+        result = await searchViaOpenAIApi({ ...common, model: models.openai || undefined, effort: openaiOpts.effort, fast: openaiOpts.fast === true })
+        break
+      case 'gemini-api':
+        result = await searchViaGeminiApi({ ...common, model: models.gemini || undefined })
+        break
+      case 'xai-api':
+        result = await searchViaXAIApi({ ...common, model: models.xai || undefined })
+        break
+      case 'grok-oauth':
+        // OAuth bearer (Grok CLI login) drives the same api.x.ai Responses +
+        // web_search call. Model is user-selectable from the live xAI catalog
+        // (shares the 'xai' model family → models.xai); when unset the backend
+        // resolves the newest chat model from the live catalog.
+        result = await searchViaGrokOAuth({ ...common, model: models.xai })
+        break
+      case 'tavily':
+        result = await searchViaTavily(common)
+        break
+      case 'exa':
+        result = await searchViaExa(common)
+        break
+      default:
+        throw new Error(`[search:dispatch] provider "${provider}" has no search case wired — PROVIDER_CAPS / switch are out of sync`)
+    }
+    return {
+      ...result,
+      query: result.query || intent.queryWithSite,
+      rawQuery: intent.rawQuery,
+      site: intent.site || undefined,
+      type: intent.type,
+      requestedType: intent.requestedType,
+      maxResults: intent.maxResults,
+      locale: caps.localeMode === 'none' ? null : intent.locale,
+      warnings: [...intent.warnings, ...(result.warnings || [])],
+    }
+  } finally {
+    cleanup()
+  }
+}
+

package/src/search/lib/backends/openai-api.mjs

@@ -0,0 +1,144 @@
+/**
+ * OpenAI API key search backend.
+ *
+ * Reuses agent.providers.openai.apiKey. Calls Responses API + web_search
+ * server tool. Model is config-driven.
+ */
+import { providerHttpError } from '../state.mjs'
+import { getAgentApiKey } from '../../../shared/config.mjs'
+import {
+  OPENAI_SEARCH_SYSTEM_INSTRUCTIONS,
+  buildOpenAISearchPrompt,
+  buildOpenAIWebSearchTool,
+  citationsFromText,
+} from './openai-web-search.mjs'
+
+const URL = 'https://api.openai.com/v1/responses'
+const MODELS_URL = 'https://api.openai.com/v1/models'
+
+function _codexFamily(id) {
+  const s = String(id || '').toLowerCase()
+  if (s.includes('nano')) return 'gpt-nano'
+  if (s.includes('mini')) return 'gpt-mini'
+  if (s.includes('codex')) return 'gpt-codex'
+  if (s.startsWith('gpt-5.5')) return 'gpt-5.5'
+  if (s.startsWith('gpt-5.4')) return 'gpt-5.4'
+  if (s.startsWith('gpt-5.2')) return 'gpt-5.2'
+  if (s.startsWith('gpt-5')) return 'gpt-5'
+  return 'gpt'
+}
+
+function _compareVersion(a, b) {
+  const na = (String(a).match(/gpt-(\d+)\.(\d+)/) || []).slice(1).map(Number)
+  const nb = (String(b).match(/gpt-(\d+)\.(\d+)/) || []).slice(1).map(Number)
+  for (let i = 0; i < Math.max(na.length, nb.length); i++) {
+    if ((na[i] || 0) !== (nb[i] || 0)) return (na[i] || 0) - (nb[i] || 0)
+  }
+  return String(a).localeCompare(String(b))
+}
+
+function _isMainCodexFamily(family) {
+  return typeof family === 'string' && family.startsWith('gpt-5')
+}
+
+function _pickLatestMainGpt5Model(ids) {
+  let best = null
+  for (const id of ids) {
+    if (!id || typeof id !== 'string') continue
+    const family = _codexFamily(id)
+    if (!_isMainCodexFamily(family)) continue
+    if (!best || _compareVersion(id, best) > 0) best = id
+  }
+  return best
+}
+
+async function ensureLatestOpenAIApiModel(apiKey, signal) {
+  const res = await fetch(MODELS_URL, {
+    method: 'GET',
+    headers: { Authorization: `Bearer ${apiKey}` },
+    redirect: 'error',
+    signal: signal ?? AbortSignal.timeout(10_000),
+  })
+  if (!res.ok) {
+    const text = await res.text().catch(() => '')
+    throw new Error(
+      `[search:openai-api] model catalog unavailable (${res.status}${text ? `: ${text.slice(0, 200)}` : ''}) — set search.models.openai to an explicit model id`,
+    )
+  }
+  const data = await res.json()
+  const ids = (Array.isArray(data?.data) ? data.data : [])
+    .map(m => m?.id)
+    .filter(Boolean)
+  const m = _pickLatestMainGpt5Model(ids)
+  if (m) return m
+  throw new Error(
+    '[search:openai-api] no default gpt-5 model in API catalog — set search.models.openai to an explicit model id',
+  )
+}
+
+export async function searchViaOpenAIApi({
+  query,
+  model,
+  effort,
+  fast = false,
+  site,
+  type = 'web',
+  maxResults = 5,
+  locale,
+  contextSize = 'low',
+  warnings = [],
+  signal,
+}) {
+  const t0 = Date.now()
+  const key = getAgentApiKey('openai')
+  if (!key) throw new Error('[search:openai-api] no api key — set OPENAI_API_KEY or the OpenAI provider key in setup')
+  const useModel = model || await ensureLatestOpenAIApiModel(key, signal)
+
+  const payload = {
+    model: useModel,
+    instructions: OPENAI_SEARCH_SYSTEM_INSTRUCTIONS,
+    input: buildOpenAISearchPrompt(query, maxResults),
+    tools: [buildOpenAIWebSearchTool({ site, type, locale, contextSize })],
+    prompt_cache_key: `mixdog-search-openai-api-${useModel}`,
+    text: { verbosity: 'low' },
+  }
+  if (effort || /^gpt-5/i.test(String(useModel))) payload.reasoning = { effort: effort || 'low' }
+  if (fast === true) payload.service_tier = 'priority'
+  const res = await fetch(URL, {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${key}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+    signal,
+  })
+  if (res.status !== 200) {
+    const text = await res.text()
+    throw providerHttpError('openai-api', res.status, text)
+  }
+  const j = await res.json()
+  const items = j?.output || []
+  // Collect every output_text part across all message items — the model can
+  // split its answer (and citations) across multiple content parts and/or
+  // multiple messages. Reading only the first part drops the rest.
+  const textParts = items
+    .filter(it => it.type === 'message')
+    .flatMap(it => Array.isArray(it.content) ? it.content : [])
+    .filter(c => c.type === 'output_text')
+  const answer = (textParts.map(c => c?.text || '').join('').trim() || j?.output_text || '').trim()
+  const annotations = textParts
+    .flatMap(c => Array.isArray(c?.annotations) ? c.annotations : [])
+    .filter(a => a?.url)
+    .map(a => ({ title: a.title || '', url: a.url || '', snippet: '', source: 'openai-api' }))
+  const citations = annotations.length
+    ? annotations.slice(0, maxResults)
+    : citationsFromText(answer, maxResults, 'openai-api')
+  return {
+    backend: 'openai-api',
+    model: useModel,
+    query,
+    answer,
+    citations,
+    durationMs: Date.now() - t0,
+    usage: j?.usage || null,
+    warnings,
+  }
+}