@gotcos/glasses-server 6.21.1 → 6.21.2

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 6.21.2
+
+- Cache Python, Claude, Codex, and Cursor process probes for 30 seconds so the
+  public health endpoint remains cheap under frequent phone diagnostics. Stale
+  static versions are served while one background refresh runs; live recovery,
+  transcription, TTS, maintenance, and request fields remain fresh.
+- Parse Cursor's actual `CLI Version` line instead of reporting the About
+  heading. Authenticated model discovery continues to be the authoritative
+  Cursor readiness signal.
+
 ## 6.21.1
 
 - Make the transactional Claude readiness proof explicitly use Haiku instead

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.21.1",
+  "version": "6.21.2",
   "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {

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

@@ -0,0 +1,177 @@
+import { execFile } from 'node:child_process'
+import { PYTHON_BIN } from './python-bridge.js'
+import {
+  getCursorModelCatalog,
+  isCursorProviderReady,
+  resolveAgentBinary,
+} from './cursor-model-catalog.js'
+
+const DEFAULT_CACHE_TTL_MS = 30_000
+const PROBE_TIMEOUT_MS = 5_000
+
+export interface HealthStaticProbeSnapshot {
+  python: string
+  claude: string
+  codex: string
+  cursor: string
+  claudeAvailable: boolean
+  codexAvailable: boolean
+  cursorAvailable: boolean
+}
+
+interface CachedProbe<T> {
+  value: T
+  refreshedAt: number
+}
+
+/**
+ * Small stale-while-revalidate cache used for process-level health probes.
+ * Runtime fields (recordings, recovery leases, Whisper, TTS, request counts)
+ * remain fresh on every /api/health request.
+ */
+export function createStaticProbeCache<T>(
+  load: () => Promise<T>,
+  ttlMs: () => number,
+  now: () => number = Date.now,
+): { get: () => Promise<T>; reset: () => void } {
+  let cached: CachedProbe<T> | null = null
+  let inFlight: Promise<T> | null = null
+
+  const refresh = (): Promise<T> => {
+    if (inFlight) return inFlight
+    inFlight = load().then((value) => {
+      cached = { value, refreshedAt: now() }
+      return value
+    }).finally(() => {
+      inFlight = null
+    })
+    return inFlight
+  }
+
+  return {
+    get: async () => {
+      if (!cached) return refresh()
+      if (now() - cached.refreshedAt < ttlMs()) return cached.value
+      // A stale static version string is safer than making liveness wait for
+      // four child processes. Refresh it for the next request in background.
+      void refresh().catch(() => {})
+      return cached.value
+    },
+    reset: () => {
+      cached = null
+      inFlight = null
+    },
+  }
+}
+
+function cacheTtlMs(): number {
+  const raw = Number(process.env.COS_HEALTH_STATIC_PROBE_TTL_MS ?? DEFAULT_CACHE_TTL_MS)
+  return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : DEFAULT_CACHE_TTL_MS
+}
+
+function execute(file: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(file, args, {
+      encoding: 'utf8',
+      timeout: PROBE_TIMEOUT_MS,
+      maxBuffer: 256 * 1024,
+      killSignal: 'SIGKILL',
+    }, (error, stdout, stderr) => {
+      if (error) return reject(error)
+      resolve({ stdout: String(stdout), stderr: String(stderr) })
+    })
+  })
+}
+
+export function parseCursorAboutVersion(output: string): string | undefined {
+  for (const rawLine of output.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    const match = /^CLI Version\s*:?\s*(\d{4}(?:\.\d+){1,3}(?:[-+][a-z0-9.-]+)?)$/i.exec(line)
+    if (match) return match[1]
+  }
+  return undefined
+}
+
+function firstNonemptyLine(output: string): string | undefined {
+  return output.split(/\r?\n/).map(line => line.trim()).find(Boolean)
+}
+
+async function probePython(): Promise<string> {
+  if (!PYTHON_BIN) return 'standalone'
+  try {
+    return firstNonemptyLine((await execute(PYTHON_BIN, ['--version'])).stdout) ?? 'available'
+  } catch {
+    return 'error'
+  }
+}
+
+async function probeClaude(): Promise<{ value: string; available: boolean }> {
+  try {
+    const result = await execute('claude', ['--version'])
+    return { value: firstNonemptyLine(result.stdout) ?? 'available', available: true }
+  } catch {
+    return { value: 'error', available: false }
+  }
+}
+
+async function probeCodex(): Promise<{ value: string; available: boolean }> {
+  try {
+    const result = await execute('codex', ['--version'])
+    const combined = `${result.stdout}\n${result.stderr}`.trim()
+    const versionLine = combined.split(/\r?\n/).map(line => line.trim())
+      .find(line => /^codex(?:-cli)?\s+/i.test(line))
+    return { value: versionLine ?? firstNonemptyLine(combined) ?? 'available', available: true }
+  } catch {
+    return { value: 'error', available: false }
+  }
+}
+
+async function probeCursor(): Promise<{ value: string; available: boolean }> {
+  const agentBinary = resolveAgentBinary()
+  if (!agentBinary) return { value: 'error', available: false }
+  try {
+    const result = await execute(agentBinary, ['about'])
+    const combined = `${result.stdout}\n${result.stderr}`.trim()
+    const version = parseCursorAboutVersion(combined)
+    // Catalog discovery is authenticated downstream truth and can take up to
+    // seven seconds. Warm it without putting that latency on public health.
+    void getCursorModelCatalog().catch(() => {})
+    const available = isCursorProviderReady()
+    const value = version ?? 'available'
+    return {
+      value: available ? value : `${value} (models unresolved)`,
+      available,
+    }
+  } catch {
+    return { value: 'error', available: false }
+  }
+}
+
+async function loadStaticHealthProbes(): Promise<HealthStaticProbeSnapshot> {
+  const [python, claude, codex, cursor] = await Promise.all([
+    probePython(),
+    probeClaude(),
+    probeCodex(),
+    probeCursor(),
+  ])
+  return {
+    python,
+    claude: claude.value,
+    codex: codex.value,
+    cursor: cursor.value,
+    claudeAvailable: claude.available,
+    codexAvailable: codex.available,
+    cursorAvailable: cursor.available,
+  }
+}
+
+const staticProbeCache = createStaticProbeCache(loadStaticHealthProbes, cacheTtlMs)
+
+export function getHealthStaticProbes(): Promise<HealthStaticProbeSnapshot> {
+  return staticProbeCache.get()
+}
+
+/** Test hook. */
+export function _resetHealthStaticProbeCache(): void {
+  staticProbeCache.reset()
+}

package/server/routes/health.ts

@@ -1,8 +1,7 @@
 import { Router } from 'express'
-import { execFile } from 'node:child_process'
 import { statSync } from 'node:fs'
 import { resolve } from 'node:path'
-import { COS_SCRIPTS_DIR, COS_MODE, PYTHON_BIN } from '../lib/python-bridge.js'
+import { COS_SCRIPTS_DIR, COS_MODE } from '../lib/python-bridge.js'
 import { serverMetrics } from '../lib/server-metrics.js'
 import { getServerInstanceId } from '../lib/server-instance-id.js'
 import { localFirstMeetingsCapability } from '../lib/local-first-meetings-contract.js'
@@ -24,7 +23,6 @@ import {
   getCursorModelCatalog,
   getCursorModelCatalogSnapshot,
   isCursorProviderReady,
-  resolveAgentBinary,
 } from '../lib/cursor-model-catalog.js'
 import { isMediaProcessingReady } from '../lib/image-safety.js'
 import { G2_LENS_VARIANT_CAPABILITY } from '../lib/media-store.js'
@@ -41,6 +39,7 @@ import { getMeetingSyncSnapshot } from '../lib/meeting-batch-progress.js'
 import { listUnsavedCaptures } from '../lib/unsaved-audio-quarantine.js'
 import { getWhisperPreviewCapability } from '../lib/whisper-preview.js'
 import { getTranscriptionProfileStatus } from '../lib/profile.js'
+import { getHealthStaticProbes } from '../lib/health-static-probes.js'
 
 export const healthRouter = Router()
 
@@ -74,101 +73,26 @@ function durableQueryJobStatus() {
 }
 
 healthRouter.get('/health', async (_req, res) => {
-  await refreshLocalTtsHealth()
+  const [, staticProbes] = await Promise.all([
+    refreshLocalTtsHealth(),
+    getHealthStaticProbes(),
+  ])
   const checks: Record<string, string | number | boolean> = {
     status: 'ok',
     mode: COS_MODE ? 'cos' : 'standalone',
     server: 'ok',
-    python: 'unknown',
-    claude: 'unknown',
-    codex: 'unknown',
-    cursor: 'unknown',
+    python: staticProbes.python,
+    claude: staticProbes.claude,
+    codex: staticProbes.codex,
+    cursor: staticProbes.cursor,
     uptime_seconds: Math.floor((Date.now() - serverMetrics.startedAt) / 1000),
     request_count: serverMetrics.requestCount,
   }
 
   // Feature detection flags
-  let claudeAvailable = false
-  let codexAvailable = false
-  let cursorAvailable = false
-
-  // Check Python venv (COS mode only)
-  if (PYTHON_BIN) {
-    try {
-      await new Promise<void>((resolve, reject) => {
-        execFile(PYTHON_BIN!, ['--version'], { timeout: 5000 }, (err, stdout) => {
-          if (err) return reject(err)
-          checks.python = stdout.trim()
-          resolve()
-        })
-      })
-    } catch {
-      checks.python = 'error'
-    }
-  } else {
-    checks.python = 'standalone'
-  }
-
-  // Check claude CLI
-  try {
-    await new Promise<void>((resolve, reject) => {
-      execFile('claude', ['--version'], { timeout: 5000 }, (err, stdout) => {
-        if (err) return reject(err)
-        checks.claude = stdout.trim()
-        claudeAvailable = true
-        resolve()
-      })
-    })
-  } catch {
-    checks.claude = 'error'
-  }
-
-  // Check Codex CLI. The desktop CLI can print benign PATH warnings to stderr,
-  // so version extraction uses stdout + stderr and looks for the codex-cli line.
-  try {
-    await new Promise<void>((resolve, reject) => {
-      execFile('codex', ['--version'], { timeout: 5000 }, (err, stdout, stderr) => {
-        if (err) return reject(err)
-        const combined = `${stdout}\n${stderr}`.trim()
-        const versionLine = combined.split('\n').map(line => line.trim()).find(line => /^codex(?:-cli)?\s+/i.test(line))
-        checks.codex = versionLine ?? combined.split('\n')[0] ?? 'available'
-        codexAvailable = true
-        resolve()
-      })
-    })
-  } catch {
-    checks.codex = 'error'
-  }
-
-  // Cursor Agent CLI — probe via `agent about` only (≤5s). Never use
-  // `agent status` (can hang on login UX while logged out).
-  try {
-    const agentBinary = resolveAgentBinary()
-    if (!agentBinary) {
-      checks.cursor = 'error'
-    } else {
-      await new Promise<void>((resolveCheck, reject) => {
-        execFile(agentBinary, ['about'], { timeout: 5000 }, (err, stdout, stderr) => {
-          if (err) return reject(err)
-          const combined = `${stdout}\n${stderr}`.trim()
-          const versionLine = combined.split('\n').map(line => line.trim()).find(line =>
-            /CLI Version|cursor|agent/i.test(line),
-          )
-          checks.cursor = versionLine ?? combined.split('\n')[0] ?? 'available'
-          resolveCheck()
-        })
-      })
-      await getCursorModelCatalog()
-      cursorAvailable = isCursorProviderReady()
-      if (!cursorAvailable) {
-        checks.cursor = typeof checks.cursor === 'string' && checks.cursor !== 'error'
-          ? `${checks.cursor} (models unresolved)`
-          : 'error'
-      }
-    }
-  } catch {
-    checks.cursor = 'error'
-  }
+  const claudeAvailable = staticProbes.claudeAvailable
+  const codexAvailable = staticProbes.codexAvailable
+  const cursorAvailable = staticProbes.cursorAvailable
 
   // Check session cache freshness (COS mode only)
   if (COS_SCRIPTS_DIR) {