@gotcos/glasses-server 6.38.1 → 6.39.1

package/server/lib/even-hub-speaker-role.ts

@@ -0,0 +1,116 @@
+// Even Hub 0.0.14 wearer-vs-other histogram, carried on a meeting chunk.
+// Identity is a suggestion. This module parses and logs. It does not name
+// people and does not change identifyChunkSpeaker.
+
+export type EvenSpeakerRole = 'self' | 'other' | 'unknown'
+export type EvenSpeakerRoleMajority = EvenSpeakerRole | 'tie'
+
+export interface EvenSpeakerRoleHistogram {
+  schema: 1
+  frames: number
+  self: number
+  other: number
+  unknown: number
+  majority: EvenSpeakerRoleMajority
+  directionPresent: number
+  directionLast: number | null
+}
+
+export type EvenSpeakerRoleMode = 'off' | 'log' | 'apply'
+
+export function evenSpeakerRoleMode(): EvenSpeakerRoleMode {
+  const raw = (process.env.COS_EVEN_SPEAKER_ROLE ?? 'log').trim().toLowerCase()
+  if (raw === 'off' || raw === '0' || raw === 'false') return 'off'
+  if (raw === 'apply') return 'apply'
+  return 'log'
+}
+
+let applyNotImplementedWarned = false
+
+/** Gate A is not in this slice. apply must not silently change labels. */
+export function warnEvenSpeakerRoleApplyNotImplemented(): void {
+  if (evenSpeakerRoleMode() !== 'apply' || applyNotImplementedWarned) return
+  applyNotImplementedWarned = true
+  console.warn('[even-role] COS_EVEN_SPEAKER_ROLE=apply is not implemented; logging only')
+}
+
+function majorityOf(self: number, other: number, unknown: number, frames: number): EvenSpeakerRoleMajority {
+  if (frames <= 0) return 'unknown'
+  if (self > other && self > unknown) return 'self'
+  if (other > self && other > unknown) return 'other'
+  if (unknown > self && unknown > other) return 'unknown'
+  return 'tie'
+}
+
+function asNonNegInt(raw: unknown): number | null {
+  const n = typeof raw === 'number' ? raw : typeof raw === 'string' && raw !== '' ? Number(raw) : NaN
+  if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n)) return null
+  return n
+}
+
+/** Compact query `eh=self,other,unknown,frames,directionPresent,directionLast`. */
+export function parseEvenHubSpeakerRoleQuery(raw: unknown): EvenSpeakerRoleHistogram | undefined {
+  if (typeof raw !== 'string' || raw.length === 0) return undefined
+  const parts = raw.split(',')
+  if (parts.length < 4 || parts.length > 6) return undefined
+  const self = asNonNegInt(parts[0])
+  const other = asNonNegInt(parts[1])
+  const unknown = asNonNegInt(parts[2])
+  const frames = asNonNegInt(parts[3])
+  if (self == null || other == null || unknown == null || frames == null) return undefined
+  if (self + other + unknown !== frames) return undefined
+  const directionPresent = parts.length >= 5 ? asNonNegInt(parts[4]) : 0
+  if (directionPresent == null) return undefined
+  let directionLast: number | null = null
+  if (parts.length === 6 && parts[5] !== '') {
+    const last = Number(parts[5])
+    if (!Number.isFinite(last)) return undefined
+    directionLast = last
+  }
+  return {
+    schema: 1,
+    frames,
+    self,
+    other,
+    unknown,
+    majority: majorityOf(self, other, unknown, frames),
+    directionPresent,
+    directionLast,
+  }
+}
+
+export function parseEvenHubSpeakerRoleBody(raw: unknown): EvenSpeakerRoleHistogram | undefined {
+  if (!raw || typeof raw !== 'object') return undefined
+  const o = raw as Record<string, unknown>
+  const self = asNonNegInt(o.self)
+  const other = asNonNegInt(o.other)
+  const unknown = asNonNegInt(o.unknown)
+  const frames = asNonNegInt(o.frames)
+  if (self == null || other == null || unknown == null || frames == null) return undefined
+  if (self + other + unknown !== frames) return undefined
+  const directionPresent = o.directionPresent == null ? 0 : asNonNegInt(o.directionPresent)
+  if (directionPresent == null) return undefined
+  const directionLast = o.directionLast == null || o.directionLast === ''
+    ? null
+    : (typeof o.directionLast === 'number' && Number.isFinite(o.directionLast) ? o.directionLast : null)
+  return {
+    schema: 1,
+    frames,
+    self,
+    other,
+    unknown,
+    majority: majorityOf(self, other, unknown, frames),
+    directionPresent,
+    directionLast,
+  }
+}
+
+export function formatEvenRoleAgreement(opts: {
+  chunkIndex: number
+  even: EvenSpeakerRoleHistogram
+  amp: string
+  emb: string
+  similarity: number
+}): string {
+  return `[even-role] chunk=${opts.chunkIndex} even=${opts.even.majority} amp=${opts.amp} emb=${opts.emb} sim=${opts.similarity.toFixed(2)} frames=${opts.even.frames}`
+}

package/server/lib/fork-thread.ts

@@ -78,7 +78,6 @@ import {
   buildAttachedEnv,
   classifyStderr,
   extractNativeIdsFromLine,
-  findBannedPermissionArg,
   isAttachedPermissionPolicy,
   resolveProviderBinary,
   type AttachedChildProcess,
@@ -86,6 +85,7 @@ import {
   type AttachedStderrClass,
   type BinaryResolution,
 } from './attached-provider-adapter.js'
+import { findBannedPermissionArg } from './banned-permission-args.js'
 
 /**
  * Providers that can be forked. A strict subset of the attached set.
@@ -261,7 +261,7 @@ export function buildCodexForkArgs(nativeThreadId: string, cwd: string): string[
 /**
  * Build the argv, and REFUSE to hand back one carrying a banned permission flag.
  *
- * The predicate is IMPORTED from the adapter, not re-listed here. Two copies of a
+ * The predicate is IMPORTED from banned-permission-args, not re-listed here. Two copies of a
  * ban list in two modules is precisely the drift `native-thread-id.ts` was created
  * to end: the occupancy detector and the binding store each had their own idea of
  * what a thread id was, and a truncated id walked through the gap. A fork spawns a

package/server/lib/health-static-probes.ts

@@ -6,6 +6,11 @@ import {
   isCursorProviderReady,
   resolveAgentBinary,
 } from './cursor-model-catalog.js'
+import {
+  getOllamaCatalog,
+  getOllamaCatalogSnapshot,
+  isOllamaProviderReady,
+} from './ollama-catalog.js'
 
 const DEFAULT_CACHE_TTL_MS = 30_000
 const PROBE_TIMEOUT_MS = 5_000
@@ -15,9 +20,11 @@ export interface HealthStaticProbeSnapshot {
   claude: string
   codex: string
   cursor: string
+  ollama: string
   claudeAvailable: boolean
   codexAvailable: boolean
   cursorAvailable: boolean
+  ollamaAvailable: boolean
 }
 
 interface CachedProbe<T> {
@@ -153,21 +160,36 @@ async function probeCursor(): Promise<{ value: string; available: boolean }> {
   }
 }
 
+async function probeOllama(): Promise<{ value: string; available: boolean }> {
+  try {
+    const catalog = await getOllamaCatalog()
+    const available = isOllamaProviderReady()
+    if (available) return { value: catalog.model || 'available', available: true }
+    return { value: catalog.error || 'unavailable', available: false }
+  } catch {
+    const snapshot = getOllamaCatalogSnapshot()
+    return { value: snapshot.error || 'error', available: false }
+  }
+}
+
 async function loadStaticHealthProbes(): Promise<HealthStaticProbeSnapshot> {
-  const [python, claude, codex, cursor] = await Promise.all([
+  const [python, claude, codex, cursor, ollama] = await Promise.all([
     probePython(),
     probeClaude(),
     probeCodex(),
     probeCursor(),
+    probeOllama(),
   ])
   return {
     python,
     claude: claude.value,
     codex: codex.value,
     cursor: cursor.value,
+    ollama: ollama.value,
     claudeAvailable: claude.available,
     codexAvailable: codex.available,
     cursorAvailable: cursor.available,
+    ollamaAvailable: ollama.available,
   }
 }
 

package/server/lib/model-router.ts

@@ -1,6 +1,7 @@
 import { callClaudeStreaming, type CallOptions, type StreamCallbacks } from './claude-bridge.js'
 import { callCodexStreaming } from './codex-bridge.js'
 import { callCursorStreaming } from './cursor-bridge.js'
+import { callOllamaStreaming } from './ollama-bridge.js'
 import {
   getOrCreateSession,
   getSessionModel,
@@ -13,6 +14,7 @@ import {
   isCodexModel,
   isClaudeModel,
   isCursorModel,
+  isOllamaModel,
   normalizeModelPreference,
 } from '../../shared/model-preference.js'
 import {
@@ -20,6 +22,10 @@ import {
   isCursorProviderReady,
   resolveCursorModelOption,
 } from './cursor-model-catalog.js'
+import {
+  getOllamaCatalog,
+  isOllamaProviderReady,
+} from './ollama-catalog.js'
 import type { ModelImageInput } from './model-image-input.js'
 
 // Bridges return as soon as their subprocess is spawned, while completion is
@@ -112,6 +118,14 @@ export async function callModelStreaming(
       }
       return await callCursorStreaming(query, sid, lockedCallbacks, resolvedModel, images, reference, globalMsgNum, options)
     }
+    if (isOllamaModel(resolvedModel)) {
+      await getOllamaCatalog()
+      if (!isOllamaProviderReady()) {
+        await lockedCallbacks.onError('ollama-bridge: Ollama is not running. Start ollama serve on this Mac.')
+        return sid
+      }
+      return await callOllamaStreaming(query, sid, lockedCallbacks, images, reference, globalMsgNum, options)
+    }
     if (isCodexModel(resolvedModel)) {
       return await callCodexStreaming(query, sid, lockedCallbacks, resolvedModel, images, reference, globalMsgNum, options)
     }

package/server/lib/ollama-bridge.ts

@@ -0,0 +1,274 @@
+// Direct Ollama chat — POST /api/chat. No Codex --oss, no tools, text only.
+
+import type { CallOptions, StreamCallbacks } from './claude-bridge.js'
+import { buildLightweightSystemPrompt } from './context-builder.js'
+import {
+  addExchange,
+  formatHistoryForPrompt,
+  getHistory,
+  getOrCreateSession,
+  getSessionRaw,
+  isNewSession,
+  markSessionNotified,
+  reconcileExchangeByJobIdentity,
+  type Exchange,
+  type PromptReference,
+} from './conversation.js'
+import { cleanupModelImageInputs, type ModelImageInput } from './model-image-input.js'
+import {
+  getOllamaCatalog,
+  isOllamaProviderReady,
+  ollamaFetch,
+} from './ollama-catalog.js'
+import {
+  classifyOllamaError,
+  finishOllamaRun,
+  startOllamaRun,
+} from './ollama-run-ledger.js'
+import { notifyExchange, notifySessionStart } from './telegram-notify.js'
+import { OLLAMA_MODEL } from '../../shared/model-preference.js'
+
+const INACTIVITY_MS = 60_000
+const WALL_MAX_MS = 180_000
+const HISTORY_LIMIT = 20
+
+type OllamaChatMessage = { role: 'system' | 'user' | 'assistant'; content: string }
+
+export function parseOllamaChatDelta(line: string): { content: string; done: boolean; error?: string } {
+  const trimmed = line.trim()
+  if (!trimmed) return { content: '', done: false }
+  try {
+    const event = JSON.parse(trimmed) as {
+      error?: unknown
+      done?: unknown
+      message?: { content?: unknown }
+    }
+    if (typeof event.error === 'string' && event.error.trim()) {
+      return { content: '', done: true, error: event.error.trim() }
+    }
+    const content = typeof event.message?.content === 'string' ? event.message.content : ''
+    return { content, done: event.done === true }
+  } catch {
+    return { content: '', done: false }
+  }
+}
+
+export function historyToOllamaMessages(
+  exchanges: Exchange[],
+  contextBreaks: number[],
+  limit = HISTORY_LIMIT,
+): OllamaChatMessage[] {
+  const lastBreak = contextBreaks.length > 0 ? contextBreaks[contextBreaks.length - 1]! : 0
+  const recent = exchanges.filter(ex => ex.timestamp >= lastBreak).slice(-limit)
+  const messages: OllamaChatMessage[] = []
+  for (const ex of recent) {
+    const content = ex.content.trim()
+    if (!content) continue
+    if (ex.role === 'user') messages.push({ role: 'user', content })
+    else messages.push({ role: 'assistant', content })
+  }
+  return messages
+}
+
+function safeOllamaUserError(message: string): string {
+  const code = classifyOllamaError(message)
+  if (code === 'ollama.unavailable') return 'Ollama is not running. Start ollama serve on this Mac.'
+  if (code === 'ollama.no_model') return 'Ollama has no pulled models. Run ollama pull, then retry.'
+  if (code === 'ollama.text_only') return 'Ollama is text-only here. Remove the photo and retry.'
+  if (code === 'ollama.timeout') return 'Ollama timed out. Retry or pick another model.'
+  return `Ollama failed (${code}). Retry or check that ollama serve is running.`
+}
+
+export async function callOllamaStreaming(
+  query: string,
+  sessionId: string | undefined,
+  callbacks: StreamCallbacks,
+  images?: ModelImageInput[],
+  reference?: PromptReference,
+  globalMsgNum?: number,
+  options?: CallOptions,
+): Promise<string> {
+  const sid = getOrCreateSession(sessionId)
+  const imageInputs = images ?? []
+  const inboundAttachments = options?.requestAttachments ?? []
+
+  if (imageInputs.length > 0 || inboundAttachments.length > 0) {
+    cleanupModelImageInputs(imageInputs)
+    await callbacks.onError(safeOllamaUserError('ollama-bridge: Ollama is text-only in this version.'))
+    return sid
+  }
+
+  await getOllamaCatalog()
+  const catalog = await getOllamaCatalog()
+  if (!isOllamaProviderReady() || !catalog.model) {
+    await callbacks.onError(safeOllamaUserError(
+      catalog.error ? `ollama-bridge: ${catalog.error}` : 'ollama-bridge: Ollama is not ready.',
+    ))
+    return sid
+  }
+
+  const history = getHistory(sid)
+  const session = getSessionRaw(sid)
+  const contextBreaks = session?.contextBreaks ?? []
+  const historyPrompt = formatHistoryForPrompt(history, contextBreaks, reference)
+  const handoffPrompt = options?.handoffContext?.promptBlock ? `\n\n${options.handoffContext.promptBlock}` : ''
+  const systemPrompt = `${buildLightweightSystemPrompt(query, `${historyPrompt}${handoffPrompt}`)}\n\nYou have no tools. Answer from the prompt and conversation only. Plain text.`
+
+  const startTime = Date.now()
+  const run = startOllamaRun({
+    turnId: options?.turnId,
+    clientJobId: options?.clientJobId,
+    cosSessionId: sid,
+    ollamaModel: catalog.model,
+    origin: catalog.origin,
+    query,
+  })
+
+  callbacks.onStart?.(OLLAMA_MODEL, sid, undefined, { ollamaRunId: run.runId })
+  await callbacks.onProviderProcess?.({
+    provider: 'ollama',
+    runId: run.runId,
+    clientJobId: options?.clientJobId,
+    generation: options?.jobGeneration ?? options?.generation,
+  })
+
+  const jobGeneration = options?.jobGeneration ?? options?.generation
+  const durableIdentity = options?.clientJobId && Number.isSafeInteger(jobGeneration) && jobGeneration! > 0
+    ? { clientJobId: options.clientJobId, generation: jobGeneration! } : undefined
+  if (durableIdentity) {
+    reconcileExchangeByJobIdentity(sid, durableIdentity, 'user', query, globalMsgNum, undefined, undefined, OLLAMA_MODEL)
+  } else {
+    addExchange(sid, 'user', query, globalMsgNum, undefined, durableIdentity, OLLAMA_MODEL)
+  }
+
+  if (isNewSession(sid)) {
+    notifySessionStart(sid, query)
+    markSessionNotified(sid)
+  }
+
+  const messages: OllamaChatMessage[] = [
+    { role: 'system', content: systemPrompt },
+    ...historyToOllamaMessages(history, contextBreaks),
+    { role: 'user', content: query },
+  ]
+
+  const abort = new AbortController()
+  const onExternalAbort = () => abort.abort()
+  options?.abortSignal?.addEventListener('abort', onExternalAbort, { once: true })
+
+  let inactivityTimer: ReturnType<typeof setTimeout> | undefined
+  let wallTimer: ReturnType<typeof setTimeout> | undefined
+  const clearTimers = () => {
+    if (inactivityTimer) clearTimeout(inactivityTimer)
+    if (wallTimer) clearTimeout(wallTimer)
+  }
+  const bumpInactivity = () => {
+    if (inactivityTimer) clearTimeout(inactivityTimer)
+    inactivityTimer = setTimeout(() => abort.abort(), INACTIVITY_MS)
+  }
+
+  let fullText = ''
+  let finalized = false
+  const finalizeError = async (raw: string) => {
+    if (finalized) return
+    finalized = true
+    clearTimers()
+    finishOllamaRun(run.runId, { status: 'failed', startedAtMs: startTime, error: raw })
+    await callbacks.onError(safeOllamaUserError(raw))
+  }
+  const finalizeDone = async () => {
+    if (finalized) return
+    finalized = true
+    clearTimers()
+    const text = fullText.trim()
+    if (!text) {
+      finishOllamaRun(run.runId, { status: 'failed', startedAtMs: startTime, error: 'ollama-bridge: empty response' })
+      await callbacks.onError(safeOllamaUserError('ollama-bridge: Ollama completed without a response.'))
+      return
+    }
+    if (durableIdentity) {
+      reconcileExchangeByJobIdentity(sid, durableIdentity, 'assistant', text, globalMsgNum, undefined, undefined, OLLAMA_MODEL)
+    } else {
+      addExchange(sid, 'assistant', text, globalMsgNum, undefined, durableIdentity, OLLAMA_MODEL)
+    }
+    finishOllamaRun(run.runId, { status: 'completed', startedAtMs: startTime, output: text })
+    notifyExchange(sid, query, text)
+    await callbacks.onDone(text, OLLAMA_MODEL, undefined, { ollamaRunId: run.runId })
+  }
+
+  bumpInactivity()
+  wallTimer = setTimeout(() => abort.abort(), WALL_MAX_MS)
+
+  try {
+    const response = await ollamaFetch(`${catalog.origin}/api/chat`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: catalog.model,
+        messages,
+        stream: true,
+      }),
+      signal: abort.signal,
+    })
+    if (!response.ok) {
+      const detail = (await response.text().catch(() => '')).trim().slice(0, 240)
+      await finalizeError(`ollama-bridge: HTTP ${response.status}${detail ? ` — ${detail}` : ''}`)
+      return sid
+    }
+    if (!response.body) {
+      await finalizeError('ollama-bridge: empty stream')
+      return sid
+    }
+
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      bumpInactivity()
+      buffer += decoder.decode(value, { stream: true })
+      const lines = buffer.split('\n')
+      buffer = lines.pop() ?? ''
+      for (const line of lines) {
+        const delta = parseOllamaChatDelta(line)
+        if (delta.error) {
+          await finalizeError(`ollama-bridge: ${delta.error}`)
+          return sid
+        }
+        if (delta.content) {
+          fullText += delta.content
+          callbacks.onChunk(delta.content)
+        }
+        if (delta.done) {
+          await finalizeDone()
+          return sid
+        }
+      }
+    }
+    if (buffer.trim()) {
+      const delta = parseOllamaChatDelta(buffer)
+      if (delta.error) {
+        await finalizeError(`ollama-bridge: ${delta.error}`)
+        return sid
+      }
+      if (delta.content) {
+        fullText += delta.content
+        callbacks.onChunk(delta.content)
+      }
+    }
+    await finalizeDone()
+    return sid
+  } catch (error: any) {
+    const aborted = abort.signal.aborted || options?.abortSignal?.aborted
+    await finalizeError(
+      aborted
+        ? 'ollama-bridge: request aborted'
+        : `ollama-bridge: ${error?.message ?? 'fetch failed'}`,
+    )
+    return sid
+  } finally {
+    clearTimers()
+    options?.abortSignal?.removeEventListener('abort', onExternalAbort)
+  }
+}

package/server/lib/ollama-catalog.ts

@@ -0,0 +1,161 @@
+// Local Ollama discovery. Hidden picker until GET /api/tags succeeds with a model.
+// Host is loopback-only — COS_OLLAMA_HOST that is not 127.0.0.1 / localhost / ::1
+// is refused (SSRF).
+
+export const DEFAULT_OLLAMA_ORIGIN = 'http://127.0.0.1:11434'
+const PROBE_TIMEOUT_MS = 2_000
+const CACHE_TTL_MS = 30_000
+
+export interface OllamaCatalog {
+  ready: boolean
+  origin: string
+  model: string
+  models: string[]
+  refreshedAt: string
+  error?: string
+}
+
+type FetchLike = typeof fetch
+let catalogFetch: FetchLike = globalThis.fetch.bind(globalThis)
+
+export function ollamaFetch(...args: Parameters<FetchLike>): ReturnType<FetchLike> {
+  return catalogFetch(...args)
+}
+
+export function _setOllamaCatalogFetchForTests(fn: FetchLike | null): void {
+  catalogFetch = fn ?? globalThis.fetch.bind(globalThis)
+}
+
+function unavailableCatalog(origin: string, error: string): OllamaCatalog {
+  return {
+    ready: false,
+    origin,
+    model: '',
+    models: [],
+    refreshedAt: new Date().toISOString(),
+    error,
+  }
+}
+
+export function isLoopbackHostname(hostname: string): boolean {
+  const host = hostname.replace(/^\[|\]$/g, '').toLowerCase()
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1'
+}
+
+export function resolveOllamaOrigin(
+  raw: string | undefined = process.env.COS_OLLAMA_HOST,
+): { ok: true; origin: string } | { ok: false; error: string } {
+  const trimmed = (raw ?? '').trim()
+  if (!trimmed) return { ok: true, origin: DEFAULT_OLLAMA_ORIGIN }
+  try {
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `http://${trimmed}`
+    const url = new URL(withScheme)
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      return { ok: false, error: 'COS_OLLAMA_HOST must be http(s) on loopback' }
+    }
+    if (!isLoopbackHostname(url.hostname)) {
+      return { ok: false, error: 'COS_OLLAMA_HOST must be loopback (127.0.0.1, localhost, ::1)' }
+    }
+    if (url.username || url.password) {
+      return { ok: false, error: 'COS_OLLAMA_HOST must not include credentials' }
+    }
+    return { ok: true, origin: url.origin }
+  } catch {
+    return { ok: false, error: 'COS_OLLAMA_HOST is not a valid URL' }
+  }
+}
+
+export function selectOllamaModel(names: string[], preferred?: string): string {
+  const cleaned = names.map(name => name.trim()).filter(Boolean)
+  if (cleaned.length === 0) return ''
+  const pin = (preferred ?? process.env.COS_OLLAMA_MODEL ?? '').trim()
+  if (!pin) return cleaned[0] ?? ''
+  if (cleaned.includes(pin)) return pin
+  const tagged = cleaned.find(name => name.startsWith(`${pin}:`))
+  return tagged ?? ''
+}
+
+export function parseOllamaTagNames(body: unknown): string[] {
+  if (!body || typeof body !== 'object') return []
+  const models = (body as { models?: unknown }).models
+  if (!Array.isArray(models)) return []
+  const names: string[] = []
+  for (const row of models) {
+    if (!row || typeof row !== 'object') continue
+    const record = row as { name?: unknown; model?: unknown }
+    const name = typeof record.name === 'string' ? record.name
+      : typeof record.model === 'string' ? record.model
+        : ''
+    if (name.trim()) names.push(name.trim())
+  }
+  return names
+}
+
+let catalogSnapshot: OllamaCatalog = unavailableCatalog(DEFAULT_OLLAMA_ORIGIN, 'unprobed')
+let refreshPromise: Promise<OllamaCatalog> | null = null
+
+export function getOllamaCatalogSnapshot(): OllamaCatalog {
+  return catalogSnapshot
+}
+
+export function isOllamaProviderReady(): boolean {
+  return catalogSnapshot.ready && catalogSnapshot.model.length > 0
+}
+
+export function _resetOllamaCatalogCache(): void {
+  catalogSnapshot = unavailableCatalog(DEFAULT_OLLAMA_ORIGIN, 'unprobed')
+  refreshPromise = null
+}
+
+async function probeOllamaCatalog(): Promise<OllamaCatalog> {
+  const originResult = resolveOllamaOrigin()
+  if (!originResult.ok) return unavailableCatalog(DEFAULT_OLLAMA_ORIGIN, originResult.error)
+  const origin = originResult.origin
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS)
+  try {
+    const response = await catalogFetch(`${origin}/api/tags`, { signal: controller.signal })
+    if (!response.ok) {
+      return unavailableCatalog(origin, `ollama /api/tags HTTP ${response.status}`)
+    }
+    const body = await response.json() as unknown
+    const models = parseOllamaTagNames(body)
+    const model = selectOllamaModel(models)
+    if (!model) return unavailableCatalog(origin, 'no models pulled')
+    return {
+      ready: true,
+      origin,
+      model,
+      models,
+      refreshedAt: new Date().toISOString(),
+    }
+  } catch (error: any) {
+    const message = error?.name === 'AbortError'
+      ? 'ollama probe timed out'
+      : (error?.message ? String(error.message).slice(0, 160) : 'ollama unreachable')
+    return unavailableCatalog(origin, message)
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export async function getOllamaCatalog(forceRefresh = false): Promise<OllamaCatalog> {
+  const ageMs = Date.now() - Date.parse(catalogSnapshot.refreshedAt)
+  if (
+    !forceRefresh
+    && catalogSnapshot.ready
+    && Number.isFinite(ageMs)
+    && ageMs >= 0
+    && ageMs < CACHE_TTL_MS
+  ) {
+    return catalogSnapshot
+  }
+  if (refreshPromise) return refreshPromise
+  refreshPromise = probeOllamaCatalog().then(snapshot => {
+    catalogSnapshot = snapshot
+    return snapshot
+  }).finally(() => {
+    refreshPromise = null
+  })
+  return refreshPromise
+}