@gotcos/glasses-server 6.15.0 → 6.15.1

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 6.15.1
+
+- Fix prepared TTS playback for native audio clients by allowing only
+  `GET`/`HEAD /api/tts/play/<UUID>` through the global API-token boundary. The
+  authenticated prepare route mints a random, audio-scoped capability that
+  expires after 60 seconds; all other TTS routes remain token-protected.
+- Fix Kokoro first-run provisioning by selecting only Python 3.11 or 3.12,
+  the actual compatibility intersection of the pinned `numpy` and `misaki`
+  dependencies. Python 3.13 is no longer advertised or selected.
+- Reject an incompatible `COS_TTS_BOOTSTRAP_PYTHON` before installation and
+  automatically rebuild stale or partial TTS virtual environments instead of
+  repeatedly failing inside pip.
+
 ## 6.15.0
 
 - Add local-first spoken reply playback through a Mac-owned Kokoro sidecar on

package/README.md

@@ -45,8 +45,8 @@ without silently losing completed replies.
   _or_ **Codex CLI** (GPT Frontier/Balanced) — https://developers.openai.com/codex/, then `codex login`
 - **Even G2 glasses** + the **COS Glasses** app from the Even Hub
 - `brew install whisper-cpp` for free local voice (the launcher can download the model)
-- _Optional:_ `brew install python@3.13 ffmpeg espeak-ng` for local Kokoro
-  spoken replies on Apple silicon (Python 3.11-3.13 is supported). `ffmpeg`
+- _Optional:_ `brew install python@3.12 ffmpeg espeak-ng` for local Kokoro
+  spoken replies on Apple silicon (Python 3.11-3.12 is supported). `ffmpeg`
   also enables phone/output image attachments; text chat remains available
   without these optional dependencies.
 - _Optional:_ **Tailscale** so your phone reaches your Mac from anywhere
@@ -166,9 +166,11 @@ BIND_HOST=0.0.0.0 npm run start:server
   keeps compatible prompt/meeting audio available for retry instead of silently
   sending it to OpenAI.
 - *Local spoken replies unavailable?* — on Apple silicon, install
-  `python@3.13 ffmpeg espeak-ng`, restart the server, and wait for the
+  `python@3.12 ffmpeg espeak-ng`, restart the server, and wait for the
   first-run Kokoro model download. Confirm `/api/health` reports
   `tts_local.ready: true`.
+  If Python lives outside the normal Homebrew paths, set its absolute 3.11 or
+  3.12 path as `COS_TTS_BOOTSTRAP_PYTHON` in `~/.cos-glasses/.env`.
   Selecting Local never falls back to cloud; set `COS_TTS_ENGINE=openai_primary`
   only when OpenAI playback is intentionally configured.
 - *Photos unavailable?* — install `ffmpeg`, restart the server, and confirm `/api/health` reports `features.mediaProcessingReady: true`.

package/bin/cli.cjs

@@ -4,7 +4,7 @@
 // Runs the bundled server for Even G2 smart glasses. The server ships INSIDE this
 // package — there is no clone. Config persists at ~/.cos-glasses/.
 
-const { execSync, spawn } = require('child_process')
+const { execFileSync, execSync, spawn } = require('child_process')
 const {
   existsSync,
   mkdirSync,
@@ -47,7 +47,7 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log('    - Node.js 20.11+')
   console.log('    - Claude Code CLI (not Claude Desktop) or Codex CLI')
   console.log('    - Even G2 smart glasses + the COS Glasses app (Even Hub)')
-  console.log('    - Optional local Kokoro voice: Apple silicon + Python 3.11-3.13')
+  console.log('    - Optional local Kokoro voice: Apple silicon + Python 3.11 or 3.12')
   console.log('')
   console.log('  No API key is needed for chat — it runs through your installed CLI.')
   console.log('  Config persists at ~/.cos-glasses/.env')
@@ -79,6 +79,21 @@ function getCliVersion(command, versionArg = '--version') {
     return null
   }
 }
+function compatibleKokoroPython() {
+  const configured = process.env.COS_TTS_BOOTSTRAP_PYTHON?.trim()
+  const candidates = configured ? [configured] : ['python3.12', 'python3.11', 'python3']
+  for (const command of candidates) {
+    let version = null
+    try {
+      version = execFileSync(command, ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 }).trim()
+    } catch { /* try the next interpreter */ }
+    const match = version?.match(/^Python\s+(\d+)\.(\d+)/i)
+    if (match && Number(match[1]) === 3 && [11, 12].includes(Number(match[2]))) {
+      return { command, version }
+    }
+  }
+  return null
+}
 function normalizeCodexVersion(raw) {
   if (!raw) return 'available'
   const line = raw.split('\n').map((s) => s.trim()).find((s) => /^codex(?:-cli)?\s+/i.test(s)) || raw.split('\n')[0].trim()
@@ -182,14 +197,12 @@ try {
 // listener. An invoked agent CLI may still maintain its own user cache.
 if (process.argv.includes('--prepare-only')) {
   if (process.platform === 'darwin' && process.arch === 'arm64') {
-    const python = ['python3.13', 'python3.12', 'python3.11']
-      .map((command) => ({ command, version: getCliVersion(command, '--version') }))
-      .find((candidate) => candidate.version)
+    const python = compatibleKokoroPython()
     if (python) {
       console.log(green('  ✓') + ` Local voice Python ${python.version.replace(/^Python\s+/i, '')}`)
     } else {
-      console.log(yellow('  ⚠') + ' Local Kokoro voice needs Python 3.11-3.13')
-      console.log('    Install: ' + bold('brew install python@3.13 ffmpeg espeak-ng'))
+      console.log(yellow('  ⚠') + ' Local Kokoro voice needs Python 3.11 or 3.12')
+      console.log('    Install: ' + bold('brew install python@3.12 ffmpeg espeak-ng'))
     }
   }
   console.log('')

package/package.json

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

package/server/index.ts

@@ -66,7 +66,7 @@ import {
   isAllowedNetworkOrigin,
   isTailscaleIpv4,
 } from './lib/network-policy.js'
-import { timingSafeTokenEqual } from './lib/token-auth.js'
+import { requireApiToken } from './lib/api-auth.js'
 import { isManagedRuntime } from './lib/managed-runtime.js'
 import {
   acquireMaintenanceWork,
@@ -135,24 +135,12 @@ app.use(cors({
     cb(new Error('CORS blocked'))
   },
 }))
-// Auth middleware — always active (token is auto-generated if not set)
-app.use('/api', (req, res, next) => {
-  // Allow health checks, display stream, and client diagnostics without auth.
-  // Diagnostics are whitelisted because the client needs to report crashes
-  // that may happen before the wizard has supplied an API token, and
-  // enforcing auth on a debug telemetry endpoint adds risk during the exact
-  // boot window we're trying to observe.
-  if (
-    req.path === '/health' ||
-    req.path === '/display-stream' ||
-    req.path === '/diag/client' ||
-    req.path === '/diag/health'
-  ) return next()
-  if (!timingSafeTokenEqual(req.headers['x-cos-token'], API_TOKEN)) {
-    return res.status(401).json({ error: 'unauthorized' })
-  }
-  next()
-})
+// Auth middleware — always active (token is auto-generated if not set).
+// Mounted before body parsers so rejected uploads cannot consume parse memory.
+// The only capability-URL exception is a canonical /tts/play/<UUID> GET/HEAD;
+// authenticated /tts/prepare mints it for native audio players that cannot set
+// X-Cos-Token headers.
+app.use('/api', requireApiToken(API_TOKEN))
 
 // Fail-closed catch-all for mutation routes that do not own a more specific
 // lifecycle lease below. This closes the admission/drain race for secondary

package/server/lib/api-auth.ts

@@ -0,0 +1,34 @@
+import type { RequestHandler } from 'express'
+import { timingSafeTokenEqual } from './token-auth.js'
+
+// Recovery/setup clients need these availability surfaces before they have a
+// usable token. Keep private provider state and every mutation route out.
+const PUBLIC_API_PATHS = new Set([
+  '/health',
+  '/display-stream',
+  '/diag/client',
+  '/diag/health',
+])
+
+// Native HTML audio requests cannot attach X-Cos-Token. The UUID minted by
+// authenticated POST /tts/prepare is therefore a short-lived bearer
+// capability. Keep this exception exact: GET/HEAD only, one canonical v4 UUID
+// path segment, and no query-token fallback that could leak into URL logs.
+const TTS_PLAYBACK_CAPABILITY_PATH = /^\/tts\/play\/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+export function isPublicApiRequest(method: string, path: string): boolean {
+  if (PUBLIC_API_PATHS.has(path)) return true
+  return (method === 'GET' || method === 'HEAD')
+    && TTS_PLAYBACK_CAPABILITY_PATH.test(path)
+}
+
+/** Global /api authentication boundary. Mount before all body parsers. */
+export function requireApiToken(apiToken: string): RequestHandler {
+  return (req, res, next) => {
+    if (isPublicApiRequest(req.method, req.path)) return next()
+    if (!timingSafeTokenEqual(req.headers['x-cos-token'], apiToken)) {
+      return res.status(401).json({ error: 'unauthorized' })
+    }
+    next()
+  }
+}

package/server/lib/tts-cache.ts

@@ -495,9 +495,10 @@ function sweepStaleByAge(): void {
   }
 }
 
-/** Allocate a new session UUID pointing at a (hash, text, voice, format)
- *  bundle. The play route consumes the session; expired sessions are reaped
- *  by the periodic sweeper below. */
+/** Allocate a new random v4 session UUID pointing at one
+ *  (hash, text, voice, format) bundle. The play route may reread it for native
+ *  Range refills during the 60-second TTL; expired sessions are rejected and
+ *  reaped by the periodic sweeper below. */
 export function createSession(s: Omit<SessionEntry, 'expiresAt'>): string {
   const uuid = randomUUID()
   sessions.set(uuid, { ...s, expiresAt: Date.now() + SESSION_TTL_MS })

package/server/routes/tts.ts

@@ -810,12 +810,14 @@ ttsRouter.post('/tts/stream', async (req, res) => {
 //   1. Client POSTs {text, voice, format} here. We strip+trim+budget-check,
 //      hash the (text, voice, format) tuple, and return a session URL.
 //   2. Client sets audio.src = `${apiBase}${sessionUrl}` and calls .play().
-//   3. The browser GETs /api/tts/play/:session, which consumes the session
-//      and either serves cached bytes (instant) or kicks off OpenAI fresh.
+//   3. The browser GETs /api/tts/play/:session using the session as a bearer
+//      capability. Range refills may reuse it during its 60-second lifetime;
+//      the route serves cached bytes or starts live generation on a cold miss.
 //
 // The two-step pattern is required because authentication on the play route
 // would force XHR (no Range support, no progressive decoding). The session
-// UUID IS the auth — short-lived (60s) and one-shot.
+// UUID IS the auth — cryptographically random, short-lived (60s), and scoped
+// to one prepared audio item. It is re-readable only for native Range refills.
 ttsRouter.post('/tts/prepare', async (req, res) => {
   try {
     const { text, format, instructions, fast } = req.body ?? {}

package/server/tts-sidecar/bootstrap.sh

@@ -5,25 +5,49 @@ ROOT="$(cd "$(dirname "$0")" && pwd)"
 MODEL_DIR="${COS_TTS_MODEL_DIR:-$HOME/.local/share/cos-tts-models}"
 VENV="$MODEL_DIR/.venv"
 PY="${COS_TTS_BOOTSTRAP_PYTHON:-}"
-if [[ -z "$PY" ]]; then
-  if command -v python3.13 >/dev/null 2>&1; then PY="$(command -v python3.13)"
-  elif command -v python3.12 >/dev/null 2>&1; then PY="$(command -v python3.12)"
-  elif command -v python3.11 >/dev/null 2>&1; then PY="$(command -v python3.11)"
-  elif command -v python3 >/dev/null 2>&1; then PY="$(command -v python3)"
-  else
-    echo "[cos-tts] Python 3.11-3.13 is required for local Kokoro" >&2
+
+# The pinned stack has one strict intersection: numpy 2.4.6 requires 3.11+ and
+# misaki 0.9.4 requires <3.13. Select by the interpreter's real version instead
+# of trusting its filename so a newer `python3` alias cannot poison bootstrap.
+python_minor() {
+  "$1" -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")' 2>/dev/null
+}
+
+python_is_compatible() {
+  local minor
+  minor="$(python_minor "$1")" || return 1
+  [[ "$minor" == "3.11" || "$minor" == "3.12" ]]
+}
+
+if [[ -n "$PY" ]]; then
+  if [[ ! -x "$PY" ]] || ! python_is_compatible "$PY"; then
+    PY_MINOR="$(python_minor "$PY" 2>/dev/null || echo unknown)"
+    echo "[cos-tts] COS_TTS_BOOTSTRAP_PYTHON is Python $PY_MINOR; pinned Kokoro requires Python 3.11 or 3.12" >&2
     exit 2
   fi
-fi
-PY_MINOR="$($PY -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
-case "$PY_MINOR" in
-  3.11|3.12|3.13) ;;
-  *)
-    echo "[cos-tts] unsupported Python $PY_MINOR; install Python 3.11, 3.12, or 3.13" >&2
+else
+  for candidate in python3.12 python3.11 python3; do
+    candidate_path="$(command -v "$candidate" 2>/dev/null || true)"
+    if [[ -n "$candidate_path" ]] && python_is_compatible "$candidate_path"; then
+      PY="$candidate_path"
+      break
+    fi
+  done
+  if [[ -z "$PY" ]]; then
+    echo "[cos-tts] compatible Python not found; install Python 3.12 with: brew install python@3.12" >&2
     exit 2
-    ;;
-esac
+  fi
+fi
+
 mkdir -p "$MODEL_DIR"
+if [[ -x "$VENV/bin/python" ]] && ! python_is_compatible "$VENV/bin/python"; then
+  VENV_MINOR="$(python_minor "$VENV/bin/python" 2>/dev/null || echo unknown)"
+  echo "[cos-tts] rebuilding incompatible Python $VENV_MINOR venv"
+  rm -rf -- "$VENV"
+elif [[ -d "$VENV" && ! -x "$VENV/bin/python" ]]; then
+  echo "[cos-tts] rebuilding incomplete venv"
+  rm -rf -- "$VENV"
+fi
 if [[ ! -x "$VENV/bin/python" ]]; then
   echo "[cos-tts] creating venv at $VENV with $PY"
   "$PY" -m venv "$VENV"