@gotcos/glasses-server 6.17.0 → 6.18.1

package/server/lib/live-cues-memory.ts

@@ -0,0 +1,202 @@
+// Live Cues memory hops.
+//
+// callPython() cannot be used here: it shells exactly one script,
+// cos_api_bridge.py, whose dispatch has no semantic_search or lightrag_search
+// verb — an unknown verb returns nothing useful, indistinguishable from an
+// empty result. Both hops spawn python directly against the exported
+// PYTHON_BIN / COS_SCRIPTS_DIR with their own preflight, timeout, and parse.
+
+import { execFile, spawn, type ChildProcess } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { COS_SCRIPTS_DIR, PYTHON_BIN } from './python-bridge.js'
+import { terminateProviderProcess } from './provider-process-lifecycle.js'
+import { logTokenAudit } from './token-audit.js'
+
+export interface SemanticHit {
+  title: string
+  date: string
+  domain: string
+  score: number
+  summary: string
+}
+
+export interface Hop1Result {
+  ok: boolean
+  snippets: string[]
+  reason?: string
+}
+
+export interface Hop2Result {
+  ok: boolean
+  text: string | null
+  reason?: string
+  /** False when the python tree (which may hold claude -p grandchildren)
+   *  could not be proven dead after a timeout kill. */
+  treeClosed: boolean
+}
+
+const HOP1_TIMEOUT_MS = 15_000
+const HOP2_TIMEOUT_MS = 40_000
+
+// The LightRAG query pool is 200/day SHARED with /why, --explore, and prep,
+// and it increments per LLM call (~2 per query), not per invocation. The
+// reserve leaves headroom for interactive queries; it does NOT give cues an
+// isolated pool (that would need a third pool in lightrag_adapter.py).
+const LIGHTRAG_DAILY_CAP = 200
+
+function lightragReserve(): number {
+  const raw = Number(process.env.COS_LIVE_CUES_LIGHTRAG_RESERVE ?? 120)
+  return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 120
+}
+
+export function lightragBudgetAllows(): boolean {
+  if (!COS_SCRIPTS_DIR) return false
+  try {
+    const counterPath = resolve(COS_SCRIPTS_DIR, '.lightrag_daily_calls.json')
+    if (!existsSync(counterPath)) return true
+    const parsed = JSON.parse(readFileSync(counterPath, 'utf-8')) as { date?: string; query?: number }
+    const today = new Date().toISOString().slice(0, 10)
+    if (parsed.date !== today) return true
+    const spent = Number.isFinite(parsed.query) ? Number(parsed.query) : 0
+    return (LIGHTRAG_DAILY_CAP - spent) > lightragReserve()
+  } catch {
+    // An unreadable counter fails toward NOT spending: the reserve exists to
+    // protect the interactive pool, and blind spending defeats it.
+    return false
+  }
+}
+
+/** hop1 — Qdrant semantic search. No LLM spend; plain execFile timeout is fine. */
+export function semanticSearchHop(query: string): Promise<Hop1Result> {
+  const pythonBin = PYTHON_BIN
+  const scriptsDir = COS_SCRIPTS_DIR
+  if (!pythonBin || !scriptsDir) {
+    return Promise.resolve({ ok: false, snippets: [], reason: 'no_cos_pipeline' })
+  }
+  const script = resolve(scriptsDir, 'semantic_search.py')
+  if (!existsSync(script)) {
+    return Promise.resolve({ ok: false, snippets: [], reason: 'no_memory_scripts' })
+  }
+  return new Promise(resolveHop => {
+    execFile(
+      pythonBin,
+      // --min-score pinned explicitly: the CLI default is 0.25 but the
+      // programmatic default is 0.35, and inheriting the wrong one silently
+      // cuts recall.
+      [script, query, '--json', '--limit', '5', '--min-score', '0.25'],
+      { cwd: scriptsDir, timeout: HOP1_TIMEOUT_MS, maxBuffer: 1024 * 1024 },
+      (error: Error | null, stdout: string | Buffer) => {
+        if (error) {
+          resolveHop({ ok: false, snippets: [], reason: 'qdrant_unreachable' })
+          return
+        }
+        try {
+          const hits = JSON.parse(String(stdout)) as SemanticHit[]
+          const snippets = (Array.isArray(hits) ? hits : [])
+            .slice(0, 5)
+            .map(hit => `${hit.date ?? '?'} ${hit.title ?? 'Untitled'}: ${String(hit.summary ?? '').slice(0, 220)}`)
+          resolveHop({ ok: true, snippets })
+        } catch {
+          resolveHop({ ok: false, snippets: [], reason: 'qdrant_parse_error' })
+        }
+      },
+    )
+  })
+}
+
+/** Strip the human chrome lightrag_search.py --explore prints around the
+ *  answer. --explore returns before the --json branch — it can NEVER emit
+ *  JSON, so this is a plain-text contract by construction. */
+export function parseExploreOutput(raw: string): string {
+  return raw
+    .split('\n')
+    .filter(line => {
+      const trimmed = line.trim()
+      if (/^Exploring entity:/i.test(trimmed)) return false
+      if (/^-{10,}$/.test(trimmed)) return false
+      if (/^\[\d+(?:\.\d+)?s \| mode: /.test(trimmed)) return false
+      if (/^(Query|Mode):/i.test(trimmed)) return false
+      return true
+    })
+    .join('\n')
+    .trim()
+}
+
+/** hop2 — LightRAG entity exploration. Spends claude -p from the shared query
+ *  pool; spawned detached because the python child holds claude grandchildren
+ *  a plain timeout kill would orphan. */
+export function lightragExploreHop(
+  entity: string,
+  onProcess?: (proc: ChildProcess) => void,
+): Promise<Hop2Result> {
+  const pythonBin = PYTHON_BIN
+  const scriptsDir = COS_SCRIPTS_DIR
+  if (!pythonBin || !scriptsDir) {
+    return Promise.resolve({ ok: false, text: null, reason: 'no_cos_pipeline', treeClosed: true })
+  }
+  const script = resolve(scriptsDir, 'lightrag_search.py')
+  if (!existsSync(script)) {
+    return Promise.resolve({ ok: false, text: null, reason: 'no_memory_scripts', treeClosed: true })
+  }
+  if (!lightragBudgetAllows()) {
+    return Promise.resolve({ ok: false, text: null, reason: 'daily_graph_cap', treeClosed: true })
+  }
+  const startedAt = Date.now()
+  return new Promise(resolveHop => {
+    let settled = false
+    let stdout = ''
+    let timedOut = false
+
+    const proc = spawn(pythonBin, [script, '--explore', entity], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: scriptsDir,
+      env: { ...process.env },
+      detached: true,
+    })
+    onProcess?.(proc)
+
+    const finish = (result: Hop2Result) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolveHop(result)
+    }
+
+    const timer = setTimeout(() => {
+      timedOut = true
+      void terminateProviderProcess(proc).then(termination => {
+        finish({ ok: false, text: null, reason: 'graph_timeout', treeClosed: termination.closed })
+      })
+    }, HOP2_TIMEOUT_MS)
+
+    proc.on('error', () => finish({ ok: false, text: null, reason: 'graph_spawn_failed', treeClosed: !proc.pid }))
+    proc.stdout?.on('data', chunk => {
+      stdout += String(chunk)
+      if (stdout.length > 1024 * 1024) stdout = stdout.slice(-1024 * 1024)
+    })
+
+    proc.on('close', code => {
+      if (timedOut) return
+      const durationMs = Date.now() - startedAt
+      if (code !== 0) {
+        finish({ ok: false, text: null, reason: 'graph_failed', treeClosed: true })
+        return
+      }
+      const text = parseExploreOutput(stdout)
+      if (!text || /^LightRAG query failed/im.test(stdout)) {
+        finish({ ok: false, text: null, reason: 'graph_empty', treeClosed: true })
+        return
+      }
+      logTokenAudit({
+        source: 'live-cues',
+        model: 'lightrag',
+        inputChars: entity.length,
+        outputChars: text.length,
+        durationMs,
+        caller: 'live-cues-lightrag',
+      })
+      finish({ ok: true, text: text.slice(0, 4_000), treeClosed: true })
+    })
+  })
+}

package/server/lib/live-cues-prompt.ts

@@ -0,0 +1,98 @@
+// Live Cues prompts — planner and insight, both Composer asks via the
+// dedicated spawn (live-cues-cursor.ts). The bridge's system prompt is gone,
+// so these prompts own EVERY constraint themselves, including the anti-markdown
+// rule (the old bridge prompt forbade structured output, which is why the
+// bridge cannot be used) and the attribution rule (with sparse voiceprints,
+// diarization collapses to owner/Ext and a model will invent named speakers).
+
+export interface PlannerResult {
+  query: string
+  entity: string | null
+}
+
+export interface InsightResult {
+  nudge: string
+  type: string
+  priority: number
+}
+
+const JSON_ONLY_RULES = [
+  'Output ONLY minified JSON on a single line. No markdown, no code fences, no prose before or after.',
+  'If you have nothing sharp to contribute, output the literal token null.',
+].join(' ')
+
+export function buildPlannerPrompt(transcriptWindow: string): string {
+  return [
+    'You plan memory lookups for a live-meeting coaching system.',
+    'Given the transcript window below, produce the single most valuable memory query.',
+    JSON_ONLY_RULES,
+    'Schema: {"query": string, "entity": string | null}',
+    '- "query": a semantic search phrase for past-meeting retrieval (topics, decisions, commitments). Under 12 words.',
+    '- "entity": ONE named person, company, or project from the transcript worth exploring in the knowledge graph, or null.',
+    'Output null when the window is small talk, logistics, or filler with no retrievable substance.',
+    '',
+    'TRANSCRIPT WINDOW:',
+    transcriptWindow,
+  ].join('\n')
+}
+
+export function buildInsightPrompt(input: {
+  transcriptWindow: string
+  memorySnippets: string[]
+  graphContext: string | null
+}): string {
+  const memory = input.memorySnippets.length
+    ? input.memorySnippets.map((snippet, index) => `${index + 1}. ${snippet}`).join('\n')
+    : '(no related past meetings found)'
+  return [
+    'You produce ONE live coaching cue for smart-glasses during a meeting.',
+    'The wearer sees at most 85 characters, so the cue must be a single sharp line.',
+    JSON_ONLY_RULES,
+    'Schema: {"nudge": string, "type": string, "priority": number}',
+    '- "nudge": max 85 characters, max 14 words. Plain text. No markdown, no asterisks, no em dashes.',
+    '- "type": a short snake_case category, e.g. commitment_check, past_context, open_question, risk_flag. NEVER the literal string coaching_nudge.',
+    '- "priority": 1 (glance-worthy) to 3 (say this now).',
+    'Rules:',
+    '- The cue must use the MEMORY or GRAPH context to surface an edge the room cannot see. Do not replay what was just said.',
+    '- Never attribute a statement to a named person unless the transcript line is labeled with that name. Prefer "someone raised X".',
+    '- A sharp question is a valid cue when context is thin.',
+    '- Output null unless the cue is genuinely worth interrupting a meeting for.',
+    '',
+    'TRANSCRIPT WINDOW:',
+    input.transcriptWindow,
+    '',
+    'MEMORY (related past meetings):',
+    memory,
+    '',
+    'GRAPH CONTEXT:',
+    input.graphContext ?? '(unavailable this cycle)',
+  ].join('\n')
+}
+
+/** Parse a Composer reply that was instructed to emit minified JSON or null.
+ *  Tolerates accidental code fences; anything else unparseable returns null. */
+export function parseJsonReply<T>(raw: string, validate: (value: unknown) => value is T): T | null {
+  const trimmed = raw.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '').trim()
+  if (!trimmed || trimmed === 'null') return null
+  try {
+    const parsed: unknown = JSON.parse(trimmed)
+    return validate(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+export function isPlannerResult(value: unknown): value is PlannerResult {
+  if (!value || typeof value !== 'object') return false
+  const record = value as Record<string, unknown>
+  return typeof record.query === 'string' && record.query.trim().length > 0
+    && (record.entity === null || typeof record.entity === 'string')
+}
+
+export function isInsightResult(value: unknown): value is InsightResult {
+  if (!value || typeof value !== 'object') return false
+  const record = value as Record<string, unknown>
+  return typeof record.nudge === 'string' && record.nudge.trim().length > 0
+    && typeof record.type === 'string' && record.type.trim().length > 0
+    && typeof record.priority === 'number' && Number.isFinite(record.priority)
+}

package/server/lib/maintenance-lifecycle.ts

@@ -47,6 +47,12 @@ export type MaintenanceWorkKind =
   | 'prompt_draft_write'
   | 'prompt_draft_warm'
   | 'prompt_draft_finalize'
+  // Live Cues pipeline (planner + memory hops + insight). Held for the
+  // pipeline's in-flight duration so an Update Server drain cannot unload the
+  // server while a Cursor CLI or python child is live. The pipeline wall
+  // budget must stay under COS Control's 90s drain timeout (main.swift:1853)
+  // or every drain that catches a cue in flight hard-fails to Repair.
+  | 'live_cue_pipeline'
 
 export type MaintenanceWorkPhase = 'queued' | 'active'
 export type MaintenanceOperationScope = 'same_boot' | 'cross_boot'

package/server/lib/meeting-batch-transcribe.ts

@@ -6,6 +6,7 @@ import { existsSync, readFileSync, readdirSync, utimesSync, writeFileSync } from
 import { join, resolve } from 'node:path'
 import { enhanceAudio } from './audio-enhance.js'
 import { transcribeHighQuality, type WhisperWord } from './whisper-local.js'
+import { isMetalBatchPreempted } from './whisper-metal-gate.js'
 import type { IndexedTranscriptChunk } from '../routes/transcribe-stream.js'
 import {
   evaluateBatchQuality,
@@ -172,7 +173,26 @@ async function transcribeSegments(
       const combined = concatenateWavChunks(audioDir, segment.startChunkIdx, segment.endChunkIdx)
       const enhanced = await enhanceAudio(combined)
       const previousText = results.at(-1)?.text
-      const result = await transcribeHighQuality(enhanced, previousText?.slice(-250), { priority: 'batch' })
+      let result
+      try {
+        result = await transcribeHighQuality(enhanced, previousText?.slice(-250), { priority: 'batch' })
+      } catch (error) {
+        // A live meeting took the GPU mid-segment. The truncated Metal output
+        // was already discarded upstream (BLOCKER contract) — it is never
+        // accepted. Retry this SAME segment once on CPU, which cannot itself be
+        // preempted, so a busy day degrades to slow rather than to a silently
+        // missing stretch of transcript.
+        if (!isMetalBatchPreempted(error)) throw error
+        console.log(
+          `[meeting-batch] Segment ${segment.startChunkIdx}-${segment.endChunkIdx} preempted off Metal; `
+          + 'retrying once on CPU',
+        )
+        refreshPendingLease(audioDir)
+        result = await transcribeHighQuality(enhanced, previousText?.slice(-250), {
+          priority: 'batch',
+          forceCpu: true,
+        })
+      }
       const text = previousText ? stripOverlap(result.text, previousText) : result.text
       const words = result.words ?? []
       results.push({

package/server/lib/meeting-store.ts

@@ -409,7 +409,16 @@ export class MeetingStore {
       '',
       '## Summary',
       '',
-      '*Standalone recording — canonical transcript shown in meeting detail.*',
+      // When COS ops is configured, use the private-app pipeline markers so
+      // sync_meetings.py --g2-file will enrich (and reclassify domain). Plain
+      // "Standalone recording" summaries are treated as already-final and skipped.
+      ...(process.env.COS_SCRIPTS_DIR || process.env.COS_OPERATIONS_DIR || process.env.COS_MEETINGS_ROOT
+        ? [
+            '<!-- g2-needs-domain-review -->',
+            '',
+            '*G2 recording — summary pending pipeline processing.*',
+          ]
+        : ['*Standalone recording — canonical transcript shown in meeting detail.*']),
       '',
       '## Transcript',
       '',

package/server/lib/whisper-local.ts

@@ -14,6 +14,13 @@ import { homedir } from 'node:os'
 import crypto from 'node:crypto'
 import { getVocabulary, getOwnerName } from './profile.js'
 import { stripBrandUrls } from './hallucination-filter.js'
+import {
+  batchHqMetalEnabled,
+  chooseBatchDevice,
+  MetalBatchPreemptedError,
+  registerMetalBatchChild,
+  unregisterMetalBatchChild,
+} from './whisper-metal-gate.js'
 
 // Prompt hardening flags (transcription quality, 2026-05-29):
 //   COS_PROMPT_V2 — drop the trailing '.' on the vocab prompt and join prompt+context
@@ -697,7 +704,10 @@ export function parseWhisperCliFullJson(raw: string): { text: string; words: Whi
 export async function transcribeHighQuality(
   audioBuffer: Buffer,
   context?: string,
-  opts: { priority?: 'interactive' | 'batch' } = {},
+  /** forceCpu: the batch pipeline's one CPU retry after a Metal preempt. It
+   *  bypasses the gate entirely so the retry cannot itself be preempted into
+   *  an infinite loop. */
+  opts: { priority?: 'interactive' | 'batch'; forceCpu?: boolean } = {},
 ): Promise<HighQualityTranscriptionResult> {
   if (!cliAvailable) {
     // Fall back to server (no beam search available via HTTP API)
@@ -727,22 +737,33 @@ export async function transcribeHighQuality(
   try {
     writeFileSync(tmpWav, audioBuffer)
 
+    // Interactive HQ keeps Metal unconditionally — a short, user-blocking decode
+    // that is explicitly OUT of batch device policy. Only the long post-meeting
+    // batch is admission-controlled against live ASR.
+    const isBatch = opts.priority === 'batch'
+    const decision: { device: 'metal' | 'cpu'; reason: string; metalEnabled: boolean } = isBatch
+      ? (opts.forceCpu
+          ? { device: 'cpu', reason: 'preempt_retry', metalEnabled: batchHqMetalEnabled() }
+          : chooseBatchDevice())
+      : { device: 'metal', reason: 'interactive', metalEnabled: batchHqMetalEnabled() }
+    const useMetal = decision.device === 'metal'
+
     const text = await new Promise<string>((resolve, reject) => {
-      const isolateBatchFromLiveMetal = opts.priority === 'batch'
       // Interactive HQ: narrower beam (default 2) for latency. Meeting batch keeps 5.
       // Override: COS_HQ_BEAM_INTERACTIVE=N
       const interactiveBeamRaw = Number.parseInt(process.env.COS_HQ_BEAM_INTERACTIVE || '2', 10)
       const interactiveBeam = Number.isFinite(interactiveBeamRaw) && interactiveBeamRaw >= 1
         ? Math.min(interactiveBeamRaw, 5)
         : 2
-      const beam = isolateBatchFromLiveMetal ? 5 : interactiveBeam
+      const beam = isBatch ? 5 : interactiveBeam
       const bestOf = beam
       const args = [
         '-m', modelPath,
         '-f', tmpWav,
-        '-t', isolateBatchFromLiveMetal ? '8' : '16',
+        // CPU batch stays at 8 threads so it cannot starve live work of cores.
+        '-t', (isBatch && !useMetal) ? '8' : '16',
         '-l', 'en',
-        ...(isolateBatchFromLiveMetal ? ['-ng'] : ['-fa']),
+        ...(useMetal ? ['-fa'] : ['-ng']),
         '-bs', String(beam),
         '-bo', String(bestOf),
         '--no-timestamps',
@@ -763,6 +784,16 @@ export async function transcribeHighQuality(
       })
       ownedHqChildren.add(proc)
 
+      // BLOCKER contract: a preempted Metal child is a HARD FAIL. Its stdout
+      // and its -ojf JSON are truncated mid-decode, and writing that into a
+      // saved meeting is silent transcript corruption — strictly worse than a
+      // slow or failed batch. We record the preempt BEFORE the signal lands so
+      // the close handler can never mistake a truncated run for a clean exit.
+      let preemptedReason: string | null = null
+      if (isBatch && useMetal) {
+        registerMetalBatchChild(proc, reason => { preemptedReason = reason })
+      }
+
       let stdout = ''
       let stderr = ''
       proc.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString() })
@@ -785,8 +816,16 @@ export async function transcribeHighQuality(
 
       proc.on('close', (code) => {
         ownedHqChildren.delete(proc)
+        unregisterMetalBatchChild(proc)
         clearTimeout(timeout)
         if (forceKill) clearTimeout(forceKill)
+        // Preempt is checked FIRST and ignores the exit code: SIGTERM often
+        // yields a non-zero code, but a race could also let the child exit 0
+        // with partial output. Either way the text is discarded.
+        if (preemptedReason) {
+          reject(new MetalBatchPreemptedError(preemptedReason))
+          return
+        }
         if (timedOut) {
           reject(new Error(`whisper-cli HQ timeout (${timeoutMs / 1000}s, model=${useLargeV3 ? 'large-v3' : 'turbo'})`))
           return
@@ -800,6 +839,7 @@ export async function transcribeHighQuality(
 
       proc.on('error', (err) => {
         ownedHqChildren.delete(proc)
+        unregisterMetalBatchChild(proc)
         clearTimeout(timeout)
         if (forceKill) clearTimeout(forceKill)
         reject(new Error(`whisper-cli HQ spawn error: ${err.message}`))
@@ -831,7 +871,10 @@ export async function transcribeHighQuality(
     console.log(
       `[whisper-hq] Batch transcribed in ${elapsed}ms ` +
       `(${modelTag}${useVad ? '+vad' : ''}${captureBatchWords ? '+words' : ''}` +
-      `${words ? `, ${words.length} words` : ''}): ` +
+      `${words ? `, ${words.length} words` : ''}` +
+      // Device forensics: without these, "why is polish slow today" is
+      // unanswerable after the fact.
+      `${isBatch ? `, device=${decision.device} reason=${decision.reason} metalEnabled=${decision.metalEnabled}` : ''}): ` +
       `"${corrected.slice(0, 80)}${corrected.length > 80 ? '...' : ''}"`,
     )
     const metadata = useLargeV3