@gotcos/glasses-server 6.13.0 → 6.14.0

package/server/routes/glossary.ts

@@ -0,0 +1,153 @@
+// Transcription glossary — runtime-editable positive vocabulary, exact
+// corrections, and negative cleanup rules. Persists into .cos-profile.json and
+// busts the profile + decoder caches so edits take effect WITHOUT a server
+// restart. Auto token-protected by the /api middleware (server/index.ts:124).
+//
+//   GET /api/transcription-glossary → { vocabulary, corrections, negative_rules }
+//   PUT /api/transcription-glossary → same shape; PARTIAL (any omitted field is
+//     left unchanged). whisper_corrections is stored as a JSON STRING in the
+//     profile (legacy decoder contract), so the route encodes/decodes it here.
+
+import { Router } from 'express'
+import { errMsg } from '../lib/utils.js'
+import {
+  getVocabulary,
+  getNegativeRules,
+  loadProfileField,
+  updateProfileFields,
+} from '../lib/profile.js'
+import { resetDecoderCaches } from '../lib/whisper-local.js'
+import { resetVocabEchoCache } from '../lib/hallucination-filter.js'
+import { validateNegativeRule } from '../lib/hallucination-filter.js'
+
+export const glossaryRouter = Router()
+
+const MAX_TERMS = 500
+const MAX_TERM_LEN = 100
+const MAX_RULES = 500
+
+// Positive vocab is injected into the Whisper decoder prompt; URLs/emails/paths
+// there induce ".com"/handle hallucinations on quiet audio — reject them.
+function looksLikeUrlEmailPath(s: string): boolean {
+  return /(?:https?:\/\/|www\.)/i.test(s)
+    || /@[\w.-]+\.\w/.test(s)
+    || /\.(?:com|net|org|io|ai|co|gov|edu|app|dev)\b/i.test(s)
+    || /[/\\]/.test(s)
+}
+
+function readCorrections(): Record<string, string> {
+  try {
+    const raw = loadProfileField('whisper_corrections', '')
+    if (!raw) return {}
+    const parsed = JSON.parse(raw)
+    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+      ? parsed as Record<string, string>
+      : {}
+  } catch {
+    return {}
+  }
+}
+
+function currentGlossary() {
+  return {
+    vocabulary: getVocabulary(),
+    corrections: readCorrections(),
+    negative_rules: getNegativeRules(),
+  }
+}
+
+// Serialize PUTs so two writers can't clobber the read-modify-write. (The RMW in
+// updateProfileFields is synchronous today, but this guards against future async
+// drift and satisfies the write-lock contract.)
+let putChain: Promise<unknown> = Promise.resolve()
+
+glossaryRouter.get('/transcription-glossary', (_req, res) => {
+  try {
+    res.json(currentGlossary())
+  } catch (err) {
+    res.status(500).json({ error: errMsg(err) })
+  }
+})
+
+glossaryRouter.put('/transcription-glossary', async (req, res) => {
+  const body = req.body ?? {}
+  const patch: Record<string, unknown> = {}
+
+  // ── vocabulary (positive spellings → decoder prompt + fuzzy targets) ──
+  if (body.vocabulary !== undefined) {
+    if (!Array.isArray(body.vocabulary)) {
+      return res.status(400).json({ error: 'vocabulary must be an array of strings' })
+    }
+    if (body.vocabulary.length > MAX_TERMS) {
+      return res.status(400).json({ error: `too many vocabulary terms (max ${MAX_TERMS})` })
+    }
+    const vocab: string[] = []
+    for (const raw of body.vocabulary) {
+      if (typeof raw !== 'string') return res.status(400).json({ error: 'vocabulary entries must be strings' })
+      const term = raw.trim()
+      if (!term) continue
+      if (term.length > MAX_TERM_LEN) return res.status(400).json({ error: `vocabulary term too long: "${term.slice(0, 40)}…"` })
+      if (looksLikeUrlEmailPath(term)) {
+        return res.status(400).json({ error: `vocabulary cannot contain URLs/emails/paths: "${term}" — they induce hallucinations in the decoder prompt` })
+      }
+      vocab.push(term)
+    }
+    patch.vocabulary = vocab
+  }
+
+  // ── corrections (bad → good) — persisted as a JSON STRING ──
+  if (body.corrections !== undefined) {
+    if (typeof body.corrections !== 'object' || body.corrections === null || Array.isArray(body.corrections)) {
+      return res.status(400).json({ error: 'corrections must be an object { "bad": "good" }' })
+    }
+    const entries = Object.entries(body.corrections as Record<string, unknown>)
+    if (entries.length > MAX_TERMS) return res.status(400).json({ error: `too many corrections (max ${MAX_TERMS})` })
+    const map: Record<string, string> = {}
+    for (const [bad, good] of entries) {
+      const b = bad.trim()
+      if (!b) continue
+      if (typeof good !== 'string') return res.status(400).json({ error: `correction "${bad}" must map to a string` })
+      if (b.length > MAX_TERM_LEN || good.length > MAX_TERM_LEN) {
+        return res.status(400).json({ error: `correction too long near "${b.slice(0, 40)}"` })
+      }
+      map[b] = good.trim()
+    }
+    patch.whisper_corrections = JSON.stringify(map)
+  }
+
+  // ── negative rules (whole/strip/replace/flag) ──
+  if (body.negative_rules !== undefined) {
+    if (!Array.isArray(body.negative_rules)) {
+      return res.status(400).json({ error: 'negative_rules must be an array of strings' })
+    }
+    if (body.negative_rules.length > MAX_RULES) {
+      return res.status(400).json({ error: `too many negative rules (max ${MAX_RULES})` })
+    }
+    const rules: string[] = []
+    for (const raw of body.negative_rules) {
+      if (typeof raw !== 'string') return res.status(400).json({ error: 'negative_rules entries must be strings' })
+      const v = validateNegativeRule(raw)
+      if (!v.ok) return res.status(400).json({ error: `invalid rule "${raw.slice(0, 60)}": ${v.error}` })
+      rules.push(raw)
+    }
+    patch.negative_rules = rules
+  }
+
+  if (Object.keys(patch).length === 0) {
+    return res.status(400).json({ error: 'nothing to update (send vocabulary, corrections, and/or negative_rules)' })
+  }
+
+  try {
+    // Cache-bust chain: updateProfileFields() writes atomically + clears the ROOT
+    // profileCache; resetDecoderCaches() clears the two derived decoder snapshots.
+    // Both are required for an edit to reach the decoder without a restart.
+    await (putChain = putChain.catch(() => {}).then(() => {
+      updateProfileFields(patch)
+      resetDecoderCaches()
+      resetVocabEchoCache()  // vocab matcher in hallucination-filter is profile-derived too
+    }))
+    return res.json(currentGlossary())
+  } catch (err) {
+    return res.status(500).json({ error: errMsg(err) })
+  }
+})

package/server/routes/handoffs.ts

@@ -0,0 +1,101 @@
+import { Router } from 'express'
+import {
+  buildHandoffPromptContext,
+  claimHandoff,
+  createHandoff,
+  getHandoff,
+  getLatestHandoff,
+  type HandoffCreateInput,
+} from '../lib/handoff-store.js'
+import { getAvailableCliSessionId } from '../lib/claude-bridge.js'
+import { getCodexExecutionCwd, getCodexTrustMode } from '../lib/codex-run-ledger.js'
+import { normalizeHandoffCode } from '../../shared/handoff-intent.js'
+
+export const handoffsRouter = Router()
+
+function runtimeExpiresAt(): string {
+  return new Date(Date.now() + 2 * 60 * 60_000).toISOString()
+}
+
+function enrichRuntime(body: Record<string, any>): HandoffCreateInput {
+  const input: HandoffCreateInput = { ...body }
+  const runtime = body.runtime && typeof body.runtime === 'object' ? { ...body.runtime } : {}
+
+  if (runtime.codex?.codexThreadId) {
+    runtime.codex = {
+      ...runtime.codex,
+      cwd: runtime.codex.cwd ?? getCodexExecutionCwd(),
+      trustMode: runtime.codex.trustMode ?? getCodexTrustMode(),
+      expiresAt: runtime.codex.expiresAt ?? runtimeExpiresAt(),
+    }
+  }
+
+  if (runtime.claude?.cliSessionId) {
+    runtime.claude = {
+      ...runtime.claude,
+      expiresAt: runtime.claude.expiresAt ?? runtimeExpiresAt(),
+    }
+  } else if (typeof body.sessionId === 'string') {
+    const cliSessionId = getAvailableCliSessionId(body.sessionId)
+    if (cliSessionId) {
+      runtime.claude = {
+        cliSessionId,
+        model: typeof body.model === 'string' ? body.model : undefined,
+        expiresAt: runtimeExpiresAt(),
+      }
+    }
+  }
+
+  if (runtime.codex || runtime.claude) input.runtime = runtime
+  return input
+}
+
+handoffsRouter.post('/handoffs', async (req, res) => {
+  try {
+    const body = req.body && typeof req.body === 'object' ? req.body : {}
+    const handoff = await createHandoff(enrichRuntime(body))
+    res.status(201).json({ handoff, context: buildHandoffPromptContext(handoff) })
+  } catch (err: any) {
+    res.status(500).json({ error: err?.message ?? 'handoff create failed' })
+  }
+})
+
+handoffsRouter.get('/handoffs/latest', async (req, res) => {
+  try {
+    const handoff = await getLatestHandoff({
+      source: typeof req.query.source === 'string' ? req.query.source : undefined,
+      target: typeof req.query.target === 'string' ? req.query.target : undefined,
+      createdBy: typeof req.query.createdBy === 'string' ? req.query.createdBy : undefined,
+      deviceId: typeof req.query.deviceId === 'string' ? req.query.deviceId : undefined,
+    })
+    if (!handoff) return res.status(404).json({ error: 'handoff not found' })
+    res.json({ handoff, context: buildHandoffPromptContext(handoff) })
+  } catch (err: any) {
+    res.status(500).json({ error: err?.message ?? 'handoff lookup failed' })
+  }
+})
+
+handoffsRouter.get('/handoffs/:code', async (req, res) => {
+  const code = normalizeHandoffCode(req.params.code)
+  if (!code) return res.status(404).json({ error: 'handoff not found' })
+  try {
+    const handoff = await getHandoff(code)
+    if (!handoff) return res.status(404).json({ error: 'handoff not found' })
+    res.json({ handoff, context: buildHandoffPromptContext(handoff) })
+  } catch (err: any) {
+    res.status(500).json({ error: err?.message ?? 'handoff lookup failed' })
+  }
+})
+
+handoffsRouter.post('/handoffs/:code/claim', async (req, res) => {
+  const code = normalizeHandoffCode(req.params.code)
+  if (!code) return res.status(404).json({ error: 'handoff not found' })
+  try {
+    const claimedBy = typeof req.body?.claimedBy === 'string' ? req.body.claimedBy : 'unknown'
+    const handoff = await claimHandoff(code, claimedBy)
+    if (!handoff) return res.status(404).json({ error: 'handoff not found' })
+    res.json({ handoff, context: buildHandoffPromptContext(handoff) })
+  } catch (err: any) {
+    res.status(500).json({ error: err?.message ?? 'handoff claim failed' })
+  }
+})

package/server/routes/prompt-edit.ts

@@ -0,0 +1,33 @@
+import { Router } from 'express'
+import {
+  PromptEditValidationError,
+  applyPromptEdit,
+  normalizePromptEditInput,
+} from '../lib/prompt-edit.js'
+import { errMsg } from '../lib/utils.js'
+
+export const promptEditRouter = Router()
+
+promptEditRouter.post('/prompt-edit', async (req, res) => {
+  const abort = new AbortController()
+  // Abort the model spawn ONLY if the client disconnects before we respond.
+  // Must listen on `res`, not `req`: express.json() fully drains the request
+  // body stream before this handler runs, so `req` emits 'close' on the next
+  // tick and would abort EVERY edit mid-flight (instant 500 "Prompt edit
+  // aborted"). `res` 'close' + !writableEnded fires only on a genuine premature
+  // disconnect. (House pattern: see routes/query.ts.)
+  res.on('close', () => {
+    if (!res.writableEnded) abort.abort()
+  })
+  try {
+    const input = normalizePromptEditInput(req.body)
+    const revisedText = await applyPromptEdit(input, abort.signal)
+    res.json({ revisedText })
+  } catch (err) {
+    if (err instanceof PromptEditValidationError) {
+      res.status(err.status).json({ error: err.message })
+      return
+    }
+    res.status(500).json({ error: errMsg(err) })
+  }
+})

package/server/routes/recovery.ts

@@ -0,0 +1,76 @@
+import { Router } from 'express'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { atomicWriteFileSync } from '../lib/atomic-fs.js'
+import { acquireMaintenance, getRecoveryActivityStatus } from '../lib/recovery-activity.js'
+import { getWhisperHealth, restartWhisperServer } from '../lib/whisper-local.js'
+import { serverMetrics } from '../lib/server-metrics.js'
+
+export const recoveryRouter = Router()
+const COOLDOWN_MS = 60_000
+const cooldownPath = resolve(import.meta.dirname, '../data/.recovery_restart.json')
+
+function lastRestartAt(): number {
+  try { return Number(JSON.parse(readFileSync(cooldownPath, 'utf8'))?.at) || 0 } catch { return 0 }
+}
+
+recoveryRouter.get('/live', (_req, res) => {
+  res.setHeader('Cache-Control', 'no-store')
+  res.json({
+    status: 'ok', bootId: serverMetrics.bootId, pid: process.pid,
+    uptimeSeconds: Math.round((Date.now() - serverMetrics.startedAt) / 1000),
+    managed: process.env.COS_HARNESS === 'daemon',
+  })
+})
+
+recoveryRouter.get('/recovery/status', (_req, res) => {
+  res.json({
+    bootId: serverMetrics.bootId,
+    managed: process.env.COS_HARNESS === 'daemon',
+    whisper: getWhisperHealth(),
+    asr: { hqActive: false, hqQueued: 0, fastRestarting: false }, // public build: no HQ/fast ASR scheduler in this server
+    activity: getRecoveryActivityStatus(),
+  })
+})
+
+recoveryRouter.post('/recovery/whisper/restart', async (_req, res) => {
+  const gate = acquireMaintenance()
+  if (!gate.ok) {
+    gate.release()
+    return res.status(409).json({ error: 'Recovery blocked by active work', reason: 'recovery_busy', busy: gate.busy })
+  }
+  try {
+    const result = await restartWhisperServer()
+    res.status(result.status === 'failed' ? 503 : 200).json(result)
+  } finally { gate.release() }
+})
+
+recoveryRouter.post('/recovery/server/restart', (_req, res) => {
+  if (process.env.COS_HARNESS !== 'daemon') {
+    return res.status(409).json({ error: 'Server is not managed by the COS LaunchAgent', reason: 'restart_unmanaged' })
+  }
+  const elapsed = Date.now() - lastRestartAt()
+  if (elapsed < COOLDOWN_MS) {
+    return res.status(429).json({ error: 'Restart cooldown active', reason: 'restart_cooldown', retryAfterMs: COOLDOWN_MS - elapsed })
+  }
+  const gate = acquireMaintenance()
+  if (!gate.ok) {
+    gate.release()
+    return res.status(409).json({ error: 'Restart blocked by active work', reason: 'recovery_busy', busy: gate.busy })
+  }
+  atomicWriteFileSync(cooldownPath, JSON.stringify({ at: Date.now(), bootId: serverMetrics.bootId }))
+  res.status(202).json({ accepted: true, oldBootId: serverMetrics.bootId })
+  // Schedule independently of the response socket. The phone may change
+  // network/close the sheet immediately after receiving 202; that must not
+  // cancel an accepted restart or strand maintenance forever.
+  const timer = setTimeout(() => {
+    if (process.env.COS_DISABLE_SELF_RESTART === '1') { gate.release(); return }
+    try {
+      process.kill(process.pid, 'SIGTERM')
+    } catch (error) {
+      gate.release()
+      console.error('[recovery] Failed to signal managed server restart:', error)
+    }
+  }, 350)
+  timer.unref?.()
+})