@gotcos/glasses-server 6.12.7 → 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/health.ts

@@ -21,6 +21,9 @@ import { durableQueryJobsCapability } from '../lib/query-job-feature.js'
 import { getQueryJobRuntimeHealth } from '../lib/query-job-runtime.js'
 import { getTranscriptionPolicySnapshot } from '../lib/transcription-policy.js'
 import { CLI_DEBUG_CAPABILITY } from '../lib/cli-debug-view.js'
+import { managedRuntimeCapability, managedServerVersion } from '../lib/managed-runtime.js'
+import { getServerGenerationId } from '../lib/managed-runtime.js'
+import { maintenanceLifecycle } from '../lib/maintenance-lifecycle.js'
 
 export const healthRouter = Router()
 
@@ -145,12 +148,8 @@ healthRouter.get('/health', async (_req, res) => {
   const durableJobs = durableQueryJobStatus()
   const localFirstMeetings = localFirstMeetingsCapability(getServerInstanceId())
   const transcription = getTranscriptionPolicySnapshot()
-  const recovery = {
-    status: false,
-    restartWhisper: false,
-    restartServer: false,
-    managed: false,
-  }
+  const recovery = managedRuntimeCapability()
+  const maintenance = maintenanceLifecycle.snapshot()
   const features = {
     claude: claudeAvailable,
     codex: codexAvailable,
@@ -180,6 +179,10 @@ healthRouter.get('/health', async (_req, res) => {
   const codex_models = getCodexModelCatalogSnapshot()
   res.json({
     ...checks,
+    server_version: managedServerVersion(),
+    server_instance_id: getServerInstanceId(),
+    boot_id: serverMetrics.bootId,
+    generation_id: getServerGenerationId(),
     features,
     voice,
     whisper_health,
@@ -188,6 +191,11 @@ healthRouter.get('/health', async (_req, res) => {
     capabilities: {
       transcription,
       recovery,
+      maintenance: {
+        state: maintenance.state,
+        admissionsOpen: maintenance.admissionsOpen,
+        carriedAcrossBoot: maintenance.operation?.carriedAcrossBoot ?? false,
+      },
       cliDebug: CLI_DEBUG_CAPABILITY,
       ...(localFirstMeetings ? { localFirstMeetings } : {}),
     },
@@ -220,12 +228,7 @@ healthRouter.get('/models', async (req, res) => {
       },
       transcription,
       cliDebug: CLI_DEBUG_CAPABILITY,
-      recovery: {
-        status: false,
-        restartWhisper: false,
-        restartServer: false,
-        managed: false,
-      },
+      recovery: managedRuntimeCapability(),
       ...(localFirstMeetings ? { localFirstMeetings } : {}),
     },
   })

package/server/routes/maintenance.ts

@@ -0,0 +1,160 @@
+import { Router, type Request, type Response } from 'express'
+import {
+  MaintenanceLifecycleError,
+  maintenanceErrorPayload,
+  maintenanceLifecycle,
+  type MaintenanceDrainRequest,
+  type MaintenanceOperationCredentials,
+  type MaintenanceOperationIdentity,
+  type MaintenanceOperationKind,
+  type MaintenanceOperationScope,
+  type MaintenancePostcondition,
+} from '../lib/maintenance-lifecycle.js'
+import { managedRuntimeCapability, managedServerVersion, getServerGenerationId } from '../lib/managed-runtime.js'
+import { getQueryJobRuntimeHealth } from '../lib/query-job-runtime.js'
+import { serverMetrics } from '../lib/server-metrics.js'
+import { getServerInstanceId } from '../lib/server-instance-id.js'
+import { getWhisperHealth } from '../lib/whisper-local.js'
+import { getActiveTranscriptionSessionCount } from './transcribe-stream.js'
+
+export const maintenanceRouter = Router()
+
+function isLoopback(req: Request): boolean {
+  const address = req.socket.remoteAddress ?? ''
+  return address === '::1' || address === '127.0.0.1' || address.startsWith('127.')
+    || address.startsWith('::ffff:127.')
+}
+
+function bodyRecord(body: unknown): Record<string, unknown> {
+  return body && typeof body === 'object' ? body as Record<string, unknown> : {}
+}
+
+function operationIdentity(body: unknown): MaintenanceOperationIdentity {
+  const value = bodyRecord(body)
+  return {
+    serverInstanceId: typeof value.serverInstanceId === 'string' ? value.serverInstanceId : '',
+    bootId: typeof value.bootId === 'string' ? value.bootId : '',
+    generationId: typeof value.generationId === 'string' ? value.generationId : '',
+    operationId: typeof value.operationId === 'string' ? value.operationId : '',
+  }
+}
+
+function drainRequest(body: unknown): MaintenanceDrainRequest {
+  const value = bodyRecord(body)
+  return {
+    ...operationIdentity(value),
+    operationKind: value.operationKind as MaintenanceOperationKind,
+    scope: value.scope as MaintenanceOperationScope,
+    postcondition: value.postcondition as MaintenancePostcondition,
+    nonceSha256: typeof value.nonceSha256 === 'string' ? value.nonceSha256 : '',
+    authorizedSuccessorGenerations: Array.isArray(value.authorizedSuccessorGenerations)
+      ? value.authorizedSuccessorGenerations.filter((item): item is string => typeof item === 'string')
+      : [],
+    ...(typeof value.ttlMs === 'number' ? { ttlMs: value.ttlMs } : {}),
+  }
+}
+
+function operationCredentials(req: Request): MaintenanceOperationCredentials {
+  return {
+    leaseId: typeof req.headers['x-cos-maintenance-lease'] === 'string'
+      ? req.headers['x-cos-maintenance-lease']
+      : undefined,
+    operationId: typeof req.headers['x-cos-maintenance-operation'] === 'string'
+      ? req.headers['x-cos-maintenance-operation']
+      : undefined,
+    nonce: typeof req.headers['x-cos-maintenance-nonce'] === 'string'
+      ? req.headers['x-cos-maintenance-nonce']
+      : undefined,
+  }
+}
+
+function statusSnapshot(credentials: MaintenanceOperationCredentials = {}) {
+  const jobs = getQueryJobRuntimeHealth()
+  const activeTranscriptionSessions = getActiveTranscriptionSessionCount()
+  const managed = managedRuntimeCapability()
+  const tracked = maintenanceLifecycle.snapshot(credentials, {
+    recording_session: activeTranscriptionSessions,
+  })
+  const untrackedDurableRuns = Math.max(0, jobs.activeRuns - (tracked.activeByKind.durable_query ?? 0))
+  const lifecycle = untrackedDurableRuns > 0
+    ? maintenanceLifecycle.snapshot(credentials, {
+      durable_query_runtime: untrackedDurableRuns,
+      recording_session: activeTranscriptionSessions,
+    })
+    : tracked
+  return {
+    contractVersion: managed.contractVersion,
+    managed: managed.managed,
+    serverVersion: managedServerVersion(),
+    generationId: getServerGenerationId(),
+    serverInstanceId: getServerInstanceId(),
+    bootId: serverMetrics.bootId,
+    activeJobs: jobs.activeRuns,
+    activeTranscriptionSessions,
+    shuttingDown: jobs.shuttingDown,
+    durableStoreState: jobs.store.state,
+    lifecycle,
+    safeToRestart: lifecycle.safeToRestart && !jobs.shuttingDown,
+    whisper: getWhisperHealth(),
+  }
+}
+
+function sendLifecycleError(res: Response, error: unknown) {
+  if (error instanceof MaintenanceLifecycleError) {
+    if (error.retryAfterSeconds != null) res.setHeader('Retry-After', String(error.retryAfterSeconds))
+    res.status(error.status).json(maintenanceErrorPayload(error))
+    return
+  }
+  res.status(500).json({ error: 'maintenance_internal_error', retryable: false })
+}
+
+function requireLoopback(req: Request, res: Response): boolean {
+  if (isLoopback(req)) return true
+  res.status(403).json({ error: 'loopback_required', retryable: false })
+  return false
+}
+
+maintenanceRouter.get('/maintenance/status', (req, res) => {
+  res.json(statusSnapshot(operationCredentials(req)))
+})
+
+maintenanceRouter.post('/maintenance/drain', (req, res) => {
+  if (!requireLoopback(req, res)) return
+  try {
+    const leaseId = maintenanceLifecycle.beginDrain(drainRequest(req.body))
+    res.json({ leaseId, ...statusSnapshot() })
+  } catch (error) {
+    sendLifecycleError(res, error)
+  }
+})
+
+maintenanceRouter.post('/maintenance/drain/adopt', (req, res) => {
+  if (!requireLoopback(req, res)) return
+  const credentials = operationCredentials(req)
+  try {
+    maintenanceLifecycle.adoptDrain(operationIdentity(req.body), credentials)
+    res.json({ adopted: true, ...statusSnapshot(credentials) })
+  } catch (error) {
+    sendLifecycleError(res, error)
+  }
+})
+
+maintenanceRouter.post('/maintenance/drain/release', (req, res) => {
+  if (!requireLoopback(req, res)) return
+  try {
+    maintenanceLifecycle.releaseDrain(operationIdentity(req.body), operationCredentials(req))
+    res.json({ released: true, ...statusSnapshot() })
+  } catch (error) {
+    sendLifecycleError(res, error)
+  }
+})
+
+maintenanceRouter.post('/maintenance/drain/cancel', (req, res) => {
+  if (!requireLoopback(req, res)) return
+  try {
+    maintenanceLifecycle.cancelDrain(operationIdentity(req.body), operationCredentials(req))
+    res.json({ canceled: true, ...statusSnapshot() })
+  } catch (error) {
+    sendLifecycleError(res, error)
+  }
+})

package/server/routes/meeting.ts

@@ -40,6 +40,7 @@ import {
   type TranscriptGapReport,
 } from './transcribe-stream.js'
 import { getServerInstanceId } from '../lib/server-instance-id.js'
+import { acquireMaintenanceWork, type MaintenanceWorkLease } from '../lib/maintenance-lifecycle.js'
 
 interface MeetingSessionSource {
   getTranscript(sessionId: string): string | null
@@ -177,6 +178,7 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
 
   router.post('/meeting/save', async (req, res) => {
     let lockedSessionId: string | null = null
+    let maintenanceLease: MaintenanceWorkLease | undefined
     try {
       const body = req.body as Record<string, unknown> | undefined
       const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : ''
@@ -219,6 +221,10 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
         res.status(409).json({ error: 'Meeting save already in progress', reason: 'save_in_progress' })
         return
       }
+      // Saving/finalizing an already-recording session is a drain
+      // continuation. It must remain admitted so existing audio can reach a
+      // durable terminal while all genuinely new work is closed.
+      maintenanceLease = acquireMaintenanceWork('meeting_save', { allowDuringDrain: true })
       savingSessions.add(sessionId)
       lockedSessionId = sessionId
 
@@ -300,20 +306,30 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
       res.json(publicSaveResponse(saved))
 
       if (audioWritesReady && pendingAudioDir && chunkEntries.length > 0) {
-        const task = finalizeBatch({
-          audioDir: pendingAudioDir,
-          entries: chunkEntries.map(entry => ({ ...entry, chunk: { ...entry.chunk } })),
-          streamingWordCount: countWords(transcript),
-          meetingPath: saved.filepath,
-          sidecarPath: saved.sidecarPath,
-          runBatch,
+        // Acquire before the foreground save lease can leave scope: there is
+        // no zero-count proof gap between pending-audio handoff and the queued
+        // background finalizer.
+        const batchLease = acquireMaintenanceWork('meeting_batch_finalization', {
+          allowDuringDrain: true,
+          phase: 'queued',
+        })
+        const task = Promise.resolve().then(() => {
+          batchLease.setPhase('active')
+          return finalizeBatch({
+            audioDir: pendingAudioDir,
+            entries: chunkEntries.map(entry => ({ ...entry, chunk: { ...entry.chunk } })),
+            streamingWordCount: countWords(transcript),
+            meetingPath: saved.filepath,
+            sidecarPath: saved.sidecarPath,
+            runBatch,
+          })
         }).catch(error => {
           // Raw audio deliberately remains for the existing two-hour cleanup.
           console.error(
             `[meeting/save] Batch finalization failed for ${sessionId}: `
             + `${error instanceof Error ? error.message : String(error)}`,
           )
-        })
+        }).finally(() => batchLease.release())
         scheduleBackground(task)
       }
     } catch (error) {
@@ -324,6 +340,7 @@ export function createMeetingRouter(deps: MeetingRouteDependencies = {}): Router
       console.error('[meeting/save] Finalization failed:', error)
       res.status(500).json({ error: 'Meeting save failed', reason: 'meeting_save_error' })
     } finally {
+      maintenanceLease?.release()
       if (lockedSessionId) savingSessions.delete(lockedSessionId)
     }
   })