@gotcos/glasses-server 6.3.1 → 6.6.0

package/server/bin/cos-output-image-publisher.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+
+// Capability-scoped image publisher used by a single COS Glasses model run.
+// It copies one already-local supported image artifact into the run's private inbox and
+// appends only an opaque content id + generic provenance to the manifest.
+// Source paths, URLs, and bytes never enter the manifest or stdout.
+
+import { createHash, timingSafeEqual } from 'node:crypto'
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+  writeSync,
+} from 'node:fs'
+import { basename, isAbsolute, join, sep } from 'node:path'
+
+const RUN_DIR_PREFIX = 'cos-glasses-output-images-'
+const ABSOLUTE_MAX_IMAGES = 5
+const MAX_IMAGE_BYTES = 16 * 1024 * 1024
+const MANIFEST_MAX_BYTES = 64 * 1024
+const PROVENANCE = new Set(['generated', 'research', 'email'])
+const OUTPUT_ID_RE = /^o_[a-f0-9]{32}$/
+const WAIT_ARRAY = new Int32Array(new SharedArrayBuffer(4))
+
+function configuredMaxImages() {
+  const parsed = Number(process.env.COS_OUTPUT_IMAGE_MAX)
+  if (!Number.isInteger(parsed)) return ABSOLUTE_MAX_IMAGES
+  return Math.max(0, Math.min(ABSOLUTE_MAX_IMAGES, parsed))
+}
+
+function fail(message) {
+  throw new Error(message)
+}
+
+function sleep(ms) {
+  Atomics.wait(WAIT_ARRAY, 0, 0, ms)
+}
+
+function isSupportedMagic(bytes) {
+  const jpeg = bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff
+  const png = bytes.length >= 8 &&
+    bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47 &&
+    bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a
+  const webp = bytes.length >= 12 &&
+    bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP'
+  let isoImage = false
+  if (bytes.length >= 12 && bytes.toString('ascii', 4, 8) === 'ftyp') {
+    const declaredBoxSize = bytes.readUInt32BE(0)
+    const boxEnd = Math.min(bytes.length, declaredBoxSize >= 16 ? declaredBoxSize : 16, 256)
+    const brands = [bytes.toString('ascii', 8, 12)]
+    for (let offset = 16; offset + 4 <= boxEnd; offset += 4) brands.push(bytes.toString('ascii', offset, offset + 4))
+    isoImage = brands.some((brand) => [
+      'avif', 'avis',
+      'heic', 'heix', 'hevc', 'hevx', 'heim', 'heis',
+      'mif1', 'msf1',
+    ].includes(brand))
+  }
+  return jpeg || png || webp || isoImage
+}
+
+function outputId(bytes) {
+  // Provenance is presentation metadata, not identity. The first publication
+  // of identical bytes wins regardless of how that image was later reused.
+  const digest = createHash('sha256').update(bytes).digest('hex')
+  return `o_${digest.slice(0, 32)}`
+}
+
+function validateItemsDir(runDir, expected) {
+  const itemsDir = join(runDir, 'items')
+  let fd = -1
+  try {
+    const before = lstatSync(itemsDir)
+    if (!before.isDirectory() || before.isSymbolicLink() || (before.mode & 0o777) !== 0o700) {
+      fail('Publisher items directory is unavailable.')
+    }
+    if (typeof process.getuid === 'function' && before.uid !== process.getuid()) {
+      fail('Publisher items directory is unavailable.')
+    }
+    const real = realpathSync(itemsDir)
+    if (real !== itemsDir || !real.startsWith(`${runDir}${sep}`)) {
+      fail('Publisher items directory is unavailable.')
+    }
+    fd = openSync(itemsDir, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0))
+    const opened = fstatSync(fd)
+    const after = lstatSync(itemsDir)
+    if (!opened.isDirectory() || opened.dev !== before.dev || opened.ino !== before.ino ||
+        after.isSymbolicLink() || after.dev !== opened.dev || after.ino !== opened.ino ||
+        (opened.mode & 0o777) !== 0o700 ||
+        (typeof process.getuid === 'function' && opened.uid !== process.getuid())) {
+      fail('Publisher items directory is unavailable.')
+    }
+    if (expected && (opened.dev !== expected.dev || opened.ino !== expected.ino)) {
+      fail('Publisher items directory is unavailable.')
+    }
+    return { path: itemsDir, dev: opened.dev, ino: opened.ino }
+  } catch (err) {
+    if (err instanceof Error && err.message === 'Publisher items directory is unavailable.') throw err
+    fail('Publisher items directory is unavailable.')
+  } finally {
+    if (fd >= 0) {
+      try { closeSync(fd) } catch { /* best effort */ }
+    }
+  }
+}
+
+function readManifestIds(path) {
+  if (!existsSync(path)) return new Set()
+  let contents = ''
+  let fd = -1
+  try {
+    const stat = lstatSync(path)
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MANIFEST_MAX_BYTES) {
+      fail('Publisher manifest is unavailable.')
+    }
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+    contents = readFileSync(fd, 'utf8')
+  } catch {
+    fail('Publisher manifest is unavailable.')
+  } finally {
+    if (fd >= 0) {
+      try { closeSync(fd) } catch { /* best effort */ }
+    }
+  }
+  const ids = new Set()
+  for (const line of contents.split('\n')) {
+    if (!line || line.length > 512) continue
+    try {
+      const item = JSON.parse(line)
+      if (item?.v === 1 && item?.type === 'publish' && OUTPUT_ID_RE.test(item.id) && PROVENANCE.has(item.provenance)) {
+        ids.add(item.id)
+      }
+    } catch {
+      // A process can die between append bytes. A malformed tail never makes
+      // a valid earlier publication disappear.
+    }
+  }
+  return ids
+}
+
+function acquireLock(runDir) {
+  const lockDir = join(runDir, '.publish.lock')
+  const deadline = Date.now() + 5_000
+  while (Date.now() < deadline) {
+    try {
+      mkdirSync(lockDir, { mode: 0o700 })
+      return lockDir
+    } catch (err) {
+      if (err?.code !== 'EEXIST') fail('Publisher lock is unavailable.')
+      try {
+        if (Date.now() - statSync(lockDir).mtimeMs > 30_000) {
+          rmSync(lockDir, { recursive: true, force: true })
+          continue
+        }
+      } catch {
+        // The owner may have released it between the failed mkdir and stat.
+      }
+      sleep(25)
+    }
+  }
+  fail('Publisher is busy; try once more.')
+}
+
+function readCapability(runDir, supplied) {
+  if (!supplied || Buffer.byteLength(supplied) > 256) fail('Publisher capability is unavailable.')
+  let expected = ''
+  try {
+    expected = readFileSync(join(runDir, '.capability'), 'utf8').trim()
+  } catch {
+    fail('Publisher capability is unavailable.')
+  }
+  const a = Buffer.from(supplied)
+  const b = Buffer.from(expected)
+  if (a.length !== b.length || !timingSafeEqual(a, b)) fail('Publisher capability is unavailable.')
+}
+
+function validateRunDir(rawDir) {
+  if (!rawDir || !isAbsolute(rawDir)) fail('Publisher directory is unavailable.')
+  let runDir
+  let tmpRoot
+  try {
+    runDir = realpathSync(rawDir)
+    tmpRoot = realpathSync('/tmp')
+    const stat = lstatSync(runDir)
+    if (!stat.isDirectory() || stat.isSymbolicLink()) fail('Publisher directory is unavailable.')
+    if ((stat.mode & 0o777) !== 0o700) fail('Publisher directory is not private.')
+    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) fail('Publisher directory is unavailable.')
+  } catch {
+    fail('Publisher directory is unavailable.')
+  }
+  if (!runDir.startsWith(`${tmpRoot}${sep}`) || !basename(runDir).startsWith(RUN_DIR_PREFIX)) {
+    fail('Publisher directory is unavailable.')
+  }
+  return runDir
+}
+
+function readLocalImage(source) {
+  if (!source || !isAbsolute(source) || /^[a-z][a-z0-9+.-]*:/i.test(source) || source.startsWith('//')) {
+    fail('Publisher accepts an absolute local file, never a URL.')
+  }
+  let fd = -1
+  try {
+    const before = lstatSync(source)
+    if (!before.isFile() || before.isSymbolicLink() || before.size <= 0 || before.size > MAX_IMAGE_BYTES) {
+      fail('Source must be a supported local image no larger than 16 MiB.')
+    }
+    fd = openSync(source, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+    const opened = fstatSync(fd)
+    if (!opened.isFile() || opened.size !== before.size || opened.ino !== before.ino || opened.dev !== before.dev) {
+      fail('Source image changed while publishing.')
+    }
+    const bytes = readFileSync(fd)
+    const after = fstatSync(fd)
+    if (after.size !== opened.size || after.ino !== opened.ino || after.dev !== opened.dev) {
+      fail('Source image changed while publishing.')
+    }
+    if (!isSupportedMagic(bytes)) fail('Only JPEG, PNG, WebP, HEIC, HEIF, or AVIF images can be published.')
+    return bytes
+  } catch (err) {
+    if (typeof err?.message === 'string' && err.message.startsWith('Source ')) throw err
+    fail('Source image is unavailable.')
+  } finally {
+    if (fd >= 0) {
+      try { closeSync(fd) } catch { /* best effort */ }
+    }
+  }
+}
+
+function main() {
+  const [provenance, source, ...extra] = process.argv.slice(2)
+  if (!PROVENANCE.has(provenance) || !source || extra.length > 0) {
+    fail('Usage: publisher <generated|research|email> <absolute-local-image>')
+  }
+
+  const runDir = validateRunDir(process.env.COS_OUTPUT_IMAGE_DIR)
+  readCapability(runDir, process.env.COS_OUTPUT_IMAGE_TOKEN)
+  const bytes = readLocalImage(source)
+  const id = outputId(bytes)
+  const maxImages = configuredMaxImages()
+  const manifestPath = join(runDir, 'manifest.jsonl')
+  const items = validateItemsDir(runDir)
+  const itemsDir = items.path
+  const lockDir = acquireLock(runDir)
+
+  try {
+    const published = readManifestIds(manifestPath)
+    if (!published.has(id) && published.size >= maxImages) {
+      fail(maxImages === 0 ? 'This response cannot accept output images.' : `This response already has ${maxImages} published images.`)
+    }
+
+    const target = join(itemsDir, `${id}.img`)
+    if (!existsSync(target)) {
+      const tmp = join(itemsDir, `.${id}-${process.pid}.tmp`)
+      let fd = -1
+      try {
+        validateItemsDir(runDir, items)
+        fd = openSync(
+          tmp,
+          constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0),
+          0o600,
+        )
+        const opened = fstatSync(fd)
+        if (!opened.isFile() || opened.nlink !== 1 || (opened.mode & 0o777) !== 0o600) {
+          fail('Publisher items directory is unavailable.')
+        }
+        // If the path was swapped between validation and open, detect that
+        // before writing any source bytes to the selected directory.
+        validateItemsDir(runDir, items)
+        writeSync(fd, bytes)
+        fsyncSync(fd)
+        closeSync(fd)
+        fd = -1
+        validateItemsDir(runDir, items)
+        renameSync(tmp, target)
+        validateItemsDir(runDir, items)
+      } finally {
+        if (fd >= 0) {
+          try { closeSync(fd) } catch { /* best effort */ }
+        }
+        try { rmSync(tmp, { force: true }) } catch { /* best effort */ }
+      }
+    }
+
+    if (!published.has(id)) {
+      const line = `${JSON.stringify({ v: 1, type: 'publish', id, provenance })}\n`
+      const fd = openSync(
+        manifestPath,
+        constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0),
+        0o600,
+      )
+      try {
+        const stat = fstatSync(fd)
+        if (!stat.isFile()) fail('Publisher manifest is unavailable.')
+        writeSync(fd, line)
+        fsyncSync(fd)
+      } finally {
+        closeSync(fd)
+      }
+      chmodSync(manifestPath, 0o600)
+    }
+    process.stdout.write(`Published ${provenance} image.\n`)
+  } finally {
+    rmSync(lockDir, { recursive: true, force: true })
+  }
+}
+
+try {
+  main()
+} catch (err) {
+  const message = err instanceof Error ? err.message : 'Image publication failed.'
+  process.stderr.write(`${message}\n`)
+  process.exitCode = 1
+}

package/server/bootstrap.ts

@@ -0,0 +1,16 @@
+// Must remain the first import in server/index.ts. Claim the same machine-wide
+// slot used by the installed LaunchAgent before mutable routes or stores load.
+import './env.js'
+import { acquireServerInstanceLock, ServerInstanceActiveError } from './lib/server-instance-lock.js'
+
+try {
+  const instanceLock = acquireServerInstanceLock()
+  process.once('exit', instanceLock.release)
+} catch (error) {
+  if (error instanceof ServerInstanceActiveError) {
+    console.error(`[COS API] Startup refused: ${error.message}`)
+    process.exit(75)
+  }
+  console.error('[COS API] Startup refused: single-instance lock failed.', error)
+  process.exit(74)
+}

package/server/index.ts

@@ -1,12 +1,12 @@
-// Load .env FIRST — ESM evaluates this module before subsequent imports,
-// ensuring process.env is populated before python-bridge.ts reads COS_SCRIPTS_DIR.
-import './env.js'
+// Load env and claim the one server slot before any mutable module initializes.
+import './bootstrap.js'
 
 import express from 'express'
 import cors from 'cors'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { createServer as createHttpsServer } from 'node:https'
+import { createServer as createHttpServer } from 'node:http'
 import { readFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs'
 import { networkInterfaces, homedir } from 'node:os'
 import { join } from 'node:path'
@@ -23,13 +23,23 @@ import { openaiKeyRouter } from './routes/openai-key.js'
 import { messageRefRouter } from './routes/message-ref.js'
 import { archiveRouter } from './routes/archive.js'
 import { sessionsRouter } from './routes/sessions.js'
+import { mediaRouter, mediaBodyParser } from './routes/media.js'
 import { prewarmContext } from './lib/context-builder.js'
 import { preWarmCLI } from './lib/claude-bridge.js'
+import { getCodexRunConfig } from './lib/codex-run-ledger.js'
+import {
+  startCodexModelCatalogRefresh,
+  stopCodexModelCatalogRefresh,
+} from './lib/codex-model-catalog.js'
 import { startWhisperServer, stopWhisperServer } from './lib/whisper-local.js'
 import { initSileroVAD } from './lib/vad-silero.js'
 import { initSessionCache } from './lib/session-cache-writer.js'
 import { initSpeakerEmbeddings } from './lib/speaker-embeddings.js'
 import { logActiveSessionsOnShutdown, startAutoSnapshot } from './lib/conversation.js'
+import { getMediaStore } from './lib/media-store.js'
+import { listenRequiredServers, type RequiredListener } from './lib/listener-startup.js'
+import { serverMetrics } from './lib/server-metrics.js'
+import { initializeServerInstanceId } from './lib/server-instance-id.js'
 
 const app = express()
 const PORT = parseInt(process.env.PORT ?? '3141', 10)
@@ -61,12 +71,6 @@ if (API_TOKEN_AUTO) {
   } catch { /* read-only home — token stays per-session */ }
 }
 
-// Server metrics — shared with /api/health for monitoring
-export const serverMetrics = {
-  startedAt: Date.now(),
-  requestCount: 0,
-}
-
 // IP allowlist — only accept connections from localhost, meshnet, and private networks.
 // Blocks untrusted public access (coffee-shop WiFi, the open internet) while keeping all
 // local + meshnet (Tailscale/CGNAT) + LAN consumers working.
@@ -99,8 +103,6 @@ app.use(cors({
     cb(new Error('CORS blocked'))
   },
 }))
-app.use(express.json({ limit: '10mb' }))
-
 // 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.
@@ -120,6 +122,11 @@ app.use('/api', (req, res, next) => {
   next()
 })
 
+// Authenticate before parsing large upload bodies. The 16 MB allowance stays
+// scoped to /api/media; every other route retains the 10 MB ceiling.
+app.use('/api/media', mediaBodyParser)
+app.use(express.json({ limit: '10mb' }))
+
 // Request counter — must be before route registrations
 app.use((_req, _res, next) => {
   serverMetrics.requestCount++
@@ -139,6 +146,7 @@ app.use('/api', openaiKeyRouter)
 app.use('/api', messageRefRouter)
 app.use('/api', archiveRouter)
 app.use('/api', sessionsRouter)
+app.use('/api', mediaRouter)
 
 // OpenAI-compatible endpoint for the G2 Agent (ER "Add Agent")
 // Mounted at root — routes are /v1/chat/completions and /v1/models
@@ -164,12 +172,19 @@ process.on('SIGTERM', () => {
   // Production stops (kill, service managers) send SIGTERM — flush session logs
   // exactly like SIGINT so active conversations aren't lost on shutdown.
   try { logActiveSessionsOnShutdown() } catch { /* best-effort flush */ }
+  stopCodexModelCatalogRefresh()
+  stopWhisperServer()
+  process.exit(0)
+})
+process.on('SIGINT', () => {
+  logActiveSessionsOnShutdown()
+  stopCodexModelCatalogRefresh()
   stopWhisperServer()
   process.exit(0)
 })
-process.on('SIGINT', () => { logActiveSessionsOnShutdown(); stopWhisperServer(); process.exit(0) })
 
-// Crash protection — log and survive instead of dying mid-meeting
+// Crash protection for runtime work. Listener failures are handled separately
+// and exit immediately so a supervisor can restart a clean, unified process.
 process.on('uncaughtException', (err) => {
   console.error('[CRASH GUARD] Uncaught exception (server stays alive):', err.message)
   console.error(err.stack)
@@ -184,20 +199,27 @@ process.on('unhandledRejection', (reason: any) => {
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const HTTPS_PORT = parseInt(process.env.HTTPS_PORT ?? '3143', 10)
 const certDir = path.join(__dirname, 'certs')
+const listeners: RequiredListener[] = []
 if (existsSync(path.join(certDir, 'cert.pem'))) {
   const httpsServer = createHttpsServer({
     cert: readFileSync(path.join(certDir, 'cert.pem')),
     key: readFileSync(path.join(certDir, 'key.pem')),
   }, app)
-  httpsServer.listen(HTTPS_PORT, BIND_HOST, () => {
-    console.log(`[COS API] HTTPS server running on https://${BIND_HOST}:${HTTPS_PORT}`)
-  })
+  listeners.push({ server: httpsServer, port: HTTPS_PORT, host: BIND_HOST, label: 'HTTPS' })
 } else {
   console.log('[COS API] No certs found — HTTPS disabled (drop cert.pem/key.pem in server/certs to enable)')
 }
 
-app.listen(PORT, BIND_HOST, () => {
+const httpServer = createHttpServer(app)
+listeners.push({ server: httpServer, port: PORT, host: BIND_HOST, label: 'HTTP' })
+
+listenRequiredServers(listeners).then(() => {
+  const serverInstanceId = initializeServerInstanceId()
+  if (listeners.some(listener => listener.label === 'HTTPS')) {
+    console.log(`[COS API] HTTPS server running on https://${BIND_HOST}:${HTTPS_PORT}`)
+  }
   console.log(`[COS API] HTTP server running on http://${BIND_HOST}:${PORT}`)
+  console.log(`[COS API] Server instance: ${serverInstanceId}`)
   console.log(`[COS API] Mode: ${COS_MODE ? 'COS pipeline' : 'standalone'}`)
 
   // Print ADDRESSES THE PHONE CAN ACTUALLY REACH. The bind address (0.0.0.0) is
@@ -228,15 +250,25 @@ app.listen(PORT, BIND_HOST, () => {
     console.log('')
   }
 
-  // Check Claude CLI availability — the chat backend
+  // Check Claude CLI availability. Codex-only installs remain fully valid.
+  let claudeAvailable = false
   try {
     execSync('claude --version', { timeout: 5000, stdio: 'pipe' })
+    claudeAvailable = true
     console.log('[COS API] Claude Code CLI detected')
   } catch {
     console.warn('[COS API] Claude Code CLI not found — install from https://claude.ai/download')
-    console.warn('[COS API]   AI queries will not work without the Claude Code CLI')
+    console.warn('[COS API]   Claude models unavailable; Codex models still work when Codex CLI is installed')
   }
 
+  const codexConfig = getCodexRunConfig()
+  console.log(`[COS API] Codex mode: ${codexConfig.persistenceEnabled ? 'persistent' : 'ephemeral'} · ${codexConfig.reasoningEffort} · ${codexConfig.trustMode}`)
+  console.log(`[COS API] Codex models (${codexConfig.catalogSource}): ${codexConfig.availableModels.map(item => `${item.displayName}=${item.model}`).join(' · ')}`)
+  console.log(`[COS API] Codex workdir: ${codexConfig.cwd}`)
+  // Refresh immediately and then periodically. The catalog module retains the
+  // last-known-good snapshot if Codex is temporarily unavailable.
+  startCodexModelCatalogRefresh()
+
   if (COS_MODE) {
     initSessionCache()
     // Pre-warm context cache so first query doesn't wait for the pipeline
@@ -251,9 +283,17 @@ app.listen(PORT, BIND_HOST, () => {
   const vadOk = initSileroVAD()
   console.log(`[startup] Silero VAD: ${vadOk ? 'active' : 'disabled (model not found)'}`)
 
-  // Pre-warm the Claude CLI so the first query doesn't eat a 2-15s cold start
-  preWarmCLI().catch(err => console.error('[startup] CLI pre-warm error:', err))
+  // Pre-warm Claude only when installed so Codex-only startup stays quiet.
+  if (claudeAvailable) {
+    preWarmCLI().catch(err => console.error('[startup] CLI pre-warm error:', err))
+  }
 
   // Auto-snapshot active sessions every 5 min (survives restarts)
   startAutoSnapshot(5 * 60_000)
+
+  // Durable media GC (staged/reserved expiry + generated-image content TTL).
+  getMediaStore().startGC()
+}).catch((error: NodeJS.ErrnoException) => {
+  console.error(`[COS API] Fatal listener startup: ${error.message}`)
+  process.exit(error.code === 'EADDRINUSE' ? 75 : 74)
 })