@gotcos/glasses-server 6.71.0 → 6.71.4

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

@@ -356,6 +356,42 @@ export const __progressiveHqTesting = {
   },
 }
 
+/** Read-only, default-off candidate for in-meeting Ask evidence. Does not
+ * rewrite canonical chunks, run a decoder, or include the open tail. A complete
+ * audio/config/context chain is required; any invalid checkpoint leaves the
+ * remaining live transcript untouched. */
+export function readProgressiveAskRefinements(
+  audioDir: string,
+  sessionId: string,
+  entries: IndexedTranscriptChunk[],
+  asrCompletedIndices: number[],
+): BatchResult[] {
+  if (process.env.COS_MEETING_ASK_HQ_EVIDENCE !== '1'
+    || process.env.COS_BATCH_HQ_TIMESTAMPS !== '1'
+    || !progressiveMeetingHqEnabled()) return []
+  const results: BatchResult[] = []
+  let previousText: string | undefined
+  for (const segment of segmentTranscriptChunks(entries, 30_000, false)) {
+    if (!segmentRangeIsComplete(segment, asrCompletedIndices)) break
+    const cached = readProgressiveCheckpoint(audioDir, segment, previousText, sessionId)
+    if (!cached) break
+    previousText = cached.text
+    const originals = entries.filter(e => e.chunkIndex >= segment.startChunkIdx && e.chunkIndex <= segment.endChunkIdx)
+    const baseline = originals.map(e => e.chunk.text).join(' ')
+    const count = baseline.trim().split(/\s+/).filter(Boolean).length
+    const quality = evaluateBatchQuality([cached], count)
+    // Runtime checks are conservative corruption guards, not proof of ASR
+    // accuracy. Human-corrected facts and latency remain qualification gates.
+    const numbers = baseline.match(/\b\d+(?:[.,]\d+)*\b/g) ?? []
+    const refinedNumbers = new Set(cached.text.match(/\b\d+(?:[.,]\d+)*\b/g) ?? [])
+    if (count >= 8 && quality.accepted && quality.coverageRatio >= 0.85
+      && quality.coverageRatio <= 1.75
+      && cached.words.filter(word => word.end > word.start).length >= quality.batchWordCount * 0.75
+      && numbers.every(number => refinedNumbers.has(number))) results.push(cached)
+  }
+  return results
+}
+
 export async function transcribeSegments(
   audioDir: string,
   segments: BatchSegment[],

package/server/lib/meeting-library-search.ts

@@ -577,12 +577,14 @@ export async function searchMeetingLibrary(options: {
   domain?: string
   limit?: number
   signal?: AbortSignal
+  /** false (6.71.1, Meeting Ask "keyword only") skips the embedding search. */
+  semantic?: boolean
 }, store: MeetingStore = getMeetingStore()): Promise<MeetingSearchResult> {
   const query = options.query.trim()
   const domain = options.domain || 'all'
   const limit = Math.max(1, Math.min(options.limit ?? 20, 50))
   const keywordHits = keywordSearchMeetings(query, domain, store)
-  const semantic = await semanticSearchMeetings(query, domain, limit, options.signal)
+  const semantic = options.semantic === false ? { hits: [], reason: 'keyword_only' } : await semanticSearchMeetings(query, domain, limit, options.signal)
   const hits = mergeMeetingSearchHits(keywordHits, semantic.hits, limit)
   return {
     hits,

package/server/lib/whisper-batch-timing.ts

@@ -0,0 +1,86 @@
+import type { WhisperWord } from './whisper-local.js'
+
+/** Canary-only until human-corrected meeting/fact and native contention gates pass.
+ * Live HTTP keeps compact JSON; interactive HQ and DTW are unchanged. */
+export function batchTimestampCanaryEnabled(): boolean {
+  return process.env.COS_BATCH_HQ_TIMESTAMPS === '1'
+}
+
+export interface VadTimeSegment {
+  originalStart: number
+  originalEnd: number
+  processedStart: number
+  processedEnd: number
+}
+
+/** Read the mapping emitted by the SAME native decode, rather than run a second
+ * VAD with potentially different weights, padding or thresholds. whisper.cpp
+ * 1.9.1/1.9.5 emit this centisecond table, even though CLI -ojf token offsets
+ * still use the compressed clock. Unknown/truncated diagnostics fail closed. */
+export function parseNativeVadTimeline(stderr: string): VadTimeSegment[] {
+  const count = [...stderr.matchAll(/^whisper_vad: detected (\d+) speech segments\s*$/gm)]
+  const reduced = [...stderr.matchAll(/^whisper_vad: Reduced audio from (\d+) to (\d+) samples .+$/gm)]
+  const rows = [...stderr.matchAll(/^whisper_vad: vad_segment_info: orig_start: ([\d.]+), orig_end: ([\d.]+), vad_start: ([\d.]+), vad_end: ([\d.]+)\s*$/gm)]
+  if (count.length !== 1 || reduced.length !== 1 || rows.length !== Number(count[0][1]) || !rows.length) {
+    throw new Error('HQ VAD timing evidence missing or incomplete')
+  }
+  const duration = Number(reduced[0][1]) / 16000
+  const processedDuration = Number(reduced[0][2]) / 16000
+  const table = rows.map(row => ({
+    originalStart: Number(row[1]), originalEnd: Number(row[2]),
+    processedStart: Number(row[3]), processedEnd: Number(row[4]),
+  }))
+  for (let i = 0; i < table.length; i++) {
+    const s = table[i], prior = table[i - 1]
+    if (!Object.values(s).every(Number.isFinite)
+      || s.originalStart < 0 || s.processedStart < 0
+      || s.originalEnd <= s.originalStart || s.processedEnd <= s.processedStart
+      // Silero's final speech padding can extend the reported original end
+      // beyond the last sample by up to 30 ms (+ centisecond rounding).
+      || s.originalEnd > duration + 0.041 || s.processedEnd > processedDuration + 0.011
+      || (i === 0 && s.processedStart !== 0)
+      || (prior && (s.originalStart < prior.originalEnd || s.processedStart <= prior.processedEnd))) {
+      throw new Error('HQ VAD timing evidence inconsistent')
+    }
+  }
+  if (Math.abs(table.at(-1)!.processedEnd - processedDuration) > 0.011) {
+    throw new Error('HQ VAD timing evidence does not cover the decoded audio')
+  }
+  table.at(-1)!.originalEnd = Math.min(table.at(-1)!.originalEnd, duration)
+  return table
+}
+
+/** Replica of whisper_map_token_time_segment_aware. A token in an inserted gap
+ * snaps to the nearest speech boundary; a linear map through the gap would put
+ * words into silence. The native table already includes overlap and padding. */
+export function mapVadTime(time: number, table: readonly VadTimeSegment[]): number {
+  if (!Number.isFinite(time) || time < 0 || !table.length) throw new Error('Invalid HQ word clock')
+  if (time <= table[0].processedStart) return table[0].originalStart
+  if (time >= table.at(-1)!.processedEnd) return table.at(-1)!.originalEnd
+  for (let i = 0; i < table.length; i++) {
+    const s = table[i], next = table[i + 1]
+    if (time >= s.processedStart && time <= s.processedEnd) {
+      return s.originalStart + (time - s.processedStart) *
+        (s.originalEnd - s.originalStart) / (s.processedEnd - s.processedStart)
+    }
+    if (next && time > s.processedEnd && time < next.processedStart) {
+      return time <= (s.processedEnd + next.processedStart) / 2 ? s.originalEnd : next.originalStart
+    }
+  }
+  throw new Error('Unmapped HQ word clock')
+}
+
+export function remapBatchWords(words: readonly WhisperWord[], stderr: string, useVad: boolean): WhisperWord[] {
+  // VAD-empty CLI output is a normal empty array, not a request for a new decode.
+  if (!words.length) return []
+  const table = useVad ? parseNativeVadTimeline(stderr) : []
+  return words.map(word => {
+    if (!Number.isFinite(word.start) || !Number.isFinite(word.end)
+      || word.start < 0 || word.end < 0) throw new Error('Invalid HQ word clock')
+    const start = useVad ? mapVadTime(word.start, table) : word.start
+    // Match whisper.cpp's mapped t1 getter: token heuristics can emit t1 < t0.
+    // A zero-duration token is not evidence of a precisely timed spoken word.
+    const end = Math.max(start, useVad ? mapVadTime(word.end, table) : word.end)
+    return { ...word, start, end }
+  })
+}

package/server/lib/whisper-local.ts

@@ -13,6 +13,7 @@ import { writeFileSync, unlinkSync, existsSync, readFileSync, statSync } from 'n
 import { basename, join } from 'node:path'
 import { homedir } from 'node:os'
 import crypto from 'node:crypto'
+import { batchTimestampCanaryEnabled, remapBatchWords } from './whisper-batch-timing.js'
 import { getVocabulary, getOwnerName, getWhisperCorrections } from './profile.js'
 import { stripBrandUrls } from './hallucination-filter.js'
 import {
@@ -38,7 +39,7 @@ import {
 const PROMPT_V2 = process.env.COS_PROMPT_V2 === '1'
 const STRIP_BRAND_URLS = process.env.COS_WHISPER_STRIP_BRAND_URLS !== '0'
 
-// Word-level timestamp types (from whisper.cpp DTW alignment)
+// Word/token timing from the batch CLI; live HTTP does not request word clocks.
 export interface WhisperWord {
   word: string
   start: number   // seconds
@@ -76,12 +77,14 @@ export interface HighQualityTranscriptionResult {
 }
 
 let highQualityCheckpointFingerprint: string | null = null
+let highQualityCheckpointTimingMode: boolean | null = null
 
 /** Stable, path-free cache identity for progressive meeting HQ checkpoints.
  * Model/configuration is immutable for the lifetime of one server process, so
  * cache this instead of stat'ing multi-GB model files on every health poll. */
 export function getHighQualityCheckpointFingerprint(): string {
-  if (highQualityCheckpointFingerprint) return highQualityCheckpointFingerprint
+  const timingMode = batchTimestampCanaryEnabled()
+  if (highQualityCheckpointFingerprint && highQualityCheckpointTimingMode === timingMode) return highQualityCheckpointFingerprint
   const identity = (path: string): Record<string, number | boolean> => {
     try {
       const stat = statSync(path)
@@ -92,6 +95,8 @@ export function getHighQualityCheckpointFingerprint(): string {
   }
   highQualityCheckpointFingerprint = crypto.createHash('sha256').update(JSON.stringify({
     schema: 2,
+    // Keep the existing legacy identity byte-for-byte when the canary is off.
+    ...(timingMode ? { batchTiming: 'native-vad-timestamps-v1' } : {}),
     serverVersion: process.env.COS_SERVER_VERSION?.trim() || 'development',
     whisperCli: identity(WHISPER_CLI),
     model: identity(resolveBatchModel()),
@@ -103,6 +108,7 @@ export function getHighQualityCheckpointFingerprint(): string {
     prompt: buildWhisperPrompt(),
     corrections: getWhisperCorrections(),
   })).digest('hex')
+  highQualityCheckpointTimingMode = timingMode
   return highQualityCheckpointFingerprint
 }
 
@@ -966,10 +972,27 @@ export async function transcribeHighQuality(
   // Word clocks on post-meeting CPU polish, and on any decode that asks for
   // them (the prompt tail guard). Other live decodes stay compact JSON.
   const captureWords = opts.priority === 'batch' || opts.words === true
+  const timestampCanary = opts.priority === 'batch' && batchTimestampCanaryEnabled()
+  let nativeDiagnostics = ''
 
   const modelPath = resolveBatchModel()
   const useLargeV3 = modelPath === BATCH_MODEL_LARGE_V3
 
+  // A valid empty PCM WAV has nothing to decode. Some native CLI versions exit
+  // zero without writing JSON for it; distinguish it from malformed audio.
+  if (timestampCanary && audioBuffer.length === 44
+    && audioBuffer.toString('ascii', 0, 4) === 'RIFF'
+    && audioBuffer.readUInt32LE(4) === 36
+    && audioBuffer.toString('ascii', 8, 12) === 'WAVE'
+    && audioBuffer.toString('ascii', 12, 16) === 'fmt '
+    && audioBuffer.readUInt32LE(16) === 16
+    && audioBuffer.readUInt16LE(20) === 1 && audioBuffer.readUInt16LE(22) === 1
+    && audioBuffer.readUInt32LE(24) === 16000 && audioBuffer.readUInt32LE(28) === 32000
+    && audioBuffer.readUInt16LE(32) === 2 && audioBuffer.readUInt16LE(34) === 16
+    && audioBuffer.toString('ascii', 36, 40) === 'data' && audioBuffer.readUInt32LE(40) === 0) {
+    return { text: '', words: [], model: useLargeV3 ? 'large-v3' : 'turbo', backend: 'whisper-cli', actualQuality: useLargeV3 ? 'hq' : 'fast' }
+  }
+
   try {
     writeFileSync(tmpWav, audioBuffer)
 
@@ -1008,8 +1031,9 @@ export async function transcribeHighQuality(
         ...(useMetal ? ['-fa'] : ['-ng']),
         '-bs', String(beam),
         '-bo', String(bestOf),
-        '--no-timestamps',
-        '-np',
+        // The candidate needs native VAD diagnostics for the exact mapping.
+        // Ordinary timestamp decoding never enables DTW or live verbose JSON.
+        ...(timestampCanary ? [] : ['--no-timestamps', '-np']),
         '--prompt', buildPrompt(context),
       ]
       if (captureWords) {
@@ -1103,6 +1127,7 @@ export async function transcribeHighQuality(
           reject(new Error(`whisper-cli HQ exit ${code}: ${stderr.trim().slice(0, 200)}`))
           return
         }
+        nativeDiagnostics = stderr
         resolve(stdout.trim())
       })
 
@@ -1122,13 +1147,23 @@ export async function transcribeHighQuality(
     if (captureWords) {
       try {
         if (existsSync(jsonPath)) {
-          const parsed = parseWhisperCliFullJson(readFileSync(jsonPath, 'utf8'))
-          if (parsed.text) finalText = parsed.text
-          words = parsed.words.length > 0
-            ? parsed.words.map(w => ({ ...w, word: applyCorrections(w.word) }))
+          const raw = readFileSync(jsonPath, 'utf8')
+          if (timestampCanary && !Array.isArray(JSON.parse(raw)?.transcription)) {
+            throw new Error('HQ timestamp candidate returned invalid CLI JSON')
+          }
+          const parsed = parseWhisperCliFullJson(raw)
+          if (timestampCanary || parsed.text) finalText = parsed.text
+          const timed = timestampCanary ? remapBatchWords(parsed.words, nativeDiagnostics, useVad) : parsed.words
+          words = timed.length > 0
+            ? timed.map(w => ({ ...w, word: applyCorrections(w.word) }))
             : []
+        } else if (timestampCanary) {
+          throw new Error('HQ timestamp candidate did not produce CLI JSON')
         }
       } catch (err) {
+        // Timestamp-mode stdout contains display clocks. Missing mapping/JSON
+        // must preserve the prior transcript, never persist that stdout as text.
+        if (timestampCanary) throw err
         console.warn(
           `[whisper-hq] Batch word JSON parse failed; keeping text-only polish: ` +
           `${err instanceof Error ? err.message : String(err)}`,

package/server/routes/health.ts

@@ -28,6 +28,7 @@ import {
 import { getOpenAIWhisperBudgetState } from '../lib/openai-whisper-budget.js'
 import { getMeetingSummaryBudgetState } from '../lib/meeting-summary-budget.js'
 import { meetingWebCapability } from '../lib/meeting-ask-web.js'
+import { MEETING_ASK_CAPABILITIES } from '../lib/meeting-ask-runtime.js'
 import { lensGistPublicHealth } from '../lib/lens-gist.js'
 import { meetingSummaryLLMEnabled } from '../lib/meeting-summary.js'
 import { getKeyStatus } from '../lib/openai-key.js'
@@ -466,7 +467,7 @@ healthRouter.get('/health', async (_req, res) => {
     review_audio: reviewAudio,
     ...(voiceProvenance ? { voice_provenance: voiceProvenance } : {}),
     capabilities: {
-      meetingAsk: { protocolVersion: 2, durableHistory: true, attachmentContext: true, webRetrieval: meetingWebCapability().available },
+      meetingAsk: { ...MEETING_ASK_CAPABILITIES, webRetrieval: meetingWebCapability().available },
       dictationCleanup: { models: DICTATION_CLEAN_MODELS },
       // 6.67.0: glasses pairing (docs/pairing-contract.md). Public on purpose: the phone
       // reads it before it holds a token, and an older server omits it, which is how
@@ -632,7 +633,7 @@ healthRouter.get('/models', async (req, res) => {
     // Changing that is a breaking change that needs a client version gate first.
     ...(apiToken ? { displayStreamTicket: mintDisplayTicket(apiToken) } : {}),
     capabilities: {
-      meetingAsk: { protocolVersion: 2, durableHistory: true, attachmentContext: true, webRetrieval: meetingWebCapability().available },
+      meetingAsk: { ...MEETING_ASK_CAPABILITIES, webRetrieval: meetingWebCapability().available },
       dictationCleanup: { models: DICTATION_CLEAN_MODELS },
       durableQueryJobs: {
         enabled: durableJobs.enabled,

package/server/routes/meeting-ask.ts

@@ -1,9 +1,10 @@
+import { transcriptSources } from '../lib/meeting-ask-transcript-sources.js';
 import { Router, type Response } from 'express';
 import { AskError } from '../lib/live-cos-ask.js';
 import { meetingAskRuntime, type MeetingAskRuntime } from '../lib/meeting-ask-runtime.js';
-import { getSessionChunkEntries, getSessionStartTime } from './transcribe-stream.js';
+import { refineActiveMeetingAsk } from '../lib/meeting-ask-refinement.js';
+import { resolveAskTranscript, type AskTranscriptSources } from '../lib/meeting-ask-transcript.js';
 import { ASK_SESSION } from '../lib/meeting-ask-store.js';
-import { redactSecrets } from '../lib/lens-gist-engines.js';
 import type { MeetingAskExchange, MeetingAskFile } from '../../shared/meeting-ask.js';
 function failure(res: Response, error: unknown) { res.status(error instanceof AskError ? error.status : 503).json({ error: error instanceof AskError ? error.reason : 'meeting_assistant_unavailable' }); }
 /** Safe Markdown export. Citations are namespaced to the request because T1 is answer-local. */
@@ -41,7 +42,7 @@ export function exportMeetingAsk(exchanges: MeetingAskExchange[], files: Meeting
         throw new AskError('export_too_large', 413);
     return text;
 }
-export function createMeetingAskRouter(runtime: MeetingAskRuntime = meetingAskRuntime) {
+export function createMeetingAskRouter(runtime: MeetingAskRuntime = meetingAskRuntime, transcripts: AskTranscriptSources = transcriptSources) {
     const router = Router();
     router.use((_q, res, next) => { res.set('Cache-Control', 'no-store'); next(); });
     router.get('/meeting-ask/config', async (_q, res) => { try {
@@ -56,6 +57,14 @@ export function createMeetingAskRouter(runtime: MeetingAskRuntime = meetingAskRu
     catch (e) {
         failure(res, e);
     } });
+    router.get('/meeting-ask/context', async (req, res) => { try {
+        const sessionId = String(req.query.sessionId ?? '');
+        res.json(await runtime.context(sessionId, req.query.serverInstanceId, transcripts.live(sessionId)?.startTime ?? null));
+    } catch (e) { failure(res, e); } });
+    router.put('/meeting-ask/context', async (req, res) => { try {
+        const sessionId = String(req.body?.sessionId ?? '');
+        res.json({ orientation: await runtime.setContext(sessionId, req.body?.serverInstanceId, transcripts.live(sessionId)?.startTime ?? null, req.body) });
+    } catch (e) { failure(res, e); } });
     router.post('/meeting-ask/requests', async (req, res) => { try {
         res.status(202).json({ exchange: await runtime.submit(req.body) });
     }
@@ -90,6 +99,12 @@ export function createMeetingAskRouter(runtime: MeetingAskRuntime = meetingAskRu
     catch (e) {
         failure(res, e);
     } });
+    router.post('/meeting-ask/files/media', (req, res) => { try {
+        res.json({ files: runtime.attachMedia(String(req.body?.sessionId ?? ''), req.body?.serverInstanceId, req.body?.media) });
+    }
+    catch (e) {
+        failure(res, e);
+    } });
     router.get('/meeting-ask/export', (req, res) => {
         try {
             const exchanges: MeetingAskExchange[] = [];
@@ -113,11 +128,14 @@ export function createMeetingAskRouter(runtime: MeetingAskRuntime = meetingAskRu
             const sessionId = String(req.query.sessionId ?? '');
             if (!ASK_SESSION.test(sessionId))
                 throw new AskError('invalid_session_id');
-            const chunks = getSessionChunkEntries(sessionId), start = getSessionStartTime(sessionId);
-            if (!chunks || start === null)
-                throw new AskError('session_not_available', 404);
-            const turns = chunks.filter(e => e.chunk.text.trim()).map(e => ({ id: e.chunkIndex, elapsedMs: Math.max(0, e.chunk.elapsed), speaker: e.chunk.speaker, text: redactSecrets(e.chunk.text) }));
-            res.json({ turns, elapsedMs: Math.max(Date.now() - start, ...turns.map(t => t.elapsedMs), 0), notices: [] });
+            const snapshot = resolveAskTranscript(sessionId, transcripts);
+            // Ended/saved transcripts keep the released resolver and source metadata.
+            // Only a live snapshot may use the default-off HQ cache overlay.
+            if (snapshot.source === 'live' && process.env.COS_MEETING_ASK_HQ_EVIDENCE === '1') {
+                const refined = refineActiveMeetingAsk({ sessionId, action: 'catch_up', question: '',
+                    elapsedMs: snapshot.elapsedMs, turns: snapshot.turns, history: [] });
+                res.json({ ...snapshot, turns: refined.input.turns, notices: [...snapshot.notices, ...refined.notices] });
+            } else res.json(snapshot);
         }
         catch (e) {
             failure(res, e);

package/shared/meeting-ask.ts

@@ -11,6 +11,20 @@ export interface MeetingAskTurn {
     speaker: string;
     text: string;
 }
+/**
+ * GET /api/meeting-ask/transcript. A live meeting answers from memory. A meeting that has ended (6.71.1)
+ * answers from its saved record with ended: true, so it stays askable. 404 meeting_transcript_unavailable
+ * only when no source holds its words.
+ */
+export interface MeetingAskTranscript {
+    turns: MeetingAskTurn[];
+    elapsedMs: number;
+    notices: string[];
+    ended?: true;
+    /** When the recording stopped, if known. */
+    endedAt?: string;
+    source?: 'live' | 'active_file' | 'saved';
+}
 export interface MeetingAskFile {
     id: string;
     revision: string;
@@ -18,8 +32,12 @@ export interface MeetingAskFile {
     status: 'ready' | 'pending' | 'unsupported' | 'failed' | 'removed' | 'secret-held';
     text: string;
     notice?: string;
+    /** "phone" for a file the phone attached through POST files/media (6.71.1). Control's rows omit it. */
+    origin?: 'phone';
 }
 export interface MeetingAskSource {
+  /** Server-owned accepted post-stop quotation; no live turn target or precise word clock. */
+  finalizedTranscript?: boolean
     id: string;
     kind: 'transcript' | 'memory' | 'meeting' | 'file' | 'web';
     title: string;
@@ -155,11 +173,24 @@ export interface MeetingAskCapabilities {
     durableHistory: true;
     attachmentContext: true;
     webRetrieval: boolean;
+    /** 6.71.1: POST /api/meeting-ask/files/media turns uploaded media into meeting files. */
+    phoneFiles?: true;
+    /** 6.71.1: config carries cosSearch and PUT config {cosSearch} changes it. */
+    cosSearchMode?: true;
+    meetingContext?: true;
 }
+/**
+ * How Meeting Ask searches COS memory and earlier meetings (6.71.1). 'meaning' (default) adds the embedding
+ * search, which sends the search phrase to the COS install's embedding provider; 'keyword' matches words
+ * locally only, with no embedding request and no tokens.
+ */
+export type MeetingAskCosSearch = 'meaning' | 'keyword';
 export interface MeetingAskConfig {
     protocolVersion: 2;
     serverInstanceId: string;
     selected: MeetingAskModel;
+    /** 6.71.1. Missing on older servers, which always used 'meaning'. */
+    cosSearch?: MeetingAskCosSearch;
     models: Array<MeetingAskModel & {
         available: boolean;
         reason?: string;
@@ -171,12 +202,26 @@ export interface MeetingAskConfig {
     };
     capabilities: MeetingAskCapabilities;
 }
-/** All paths under /api/meeting-ask. GET config; PUT config {engine,model}.
+/** All paths under /api/meeting-ask. GET config; PUT config {engine,model} and/or {cosSearch} (6.71.1); either part may come alone.
  * POST requests MeetingAskSubmit -> 202 {exchange}; GET requests/:requestId -> {exchange}.
  * POST requests/:requestId/cancel {serverInstanceId} -> {exchange}.
  * GET history?sessionId=...&serverInstanceId=...&offset=0&limit=50&order=asc|desc -> {exchanges,nextOffset,files}.
  * PUT files {sessionId,serverInstanceId,files:MeetingAskFile[]} -> {files}. Upsert only; removed is explicit.
+ * POST files/media {sessionId,serverInstanceId,media:[{id,name?}]} -> {files} (6.71.1, capabilities.phoneFiles):
+ * media already uploaded through /api/media joins the meeting's file list as id "phone_<mediaId>", origin "phone".
  * GET export?sessionId=...&serverInstanceId=... -> {text}; composes persisted Ask/file context,
  * client prepends its current canonical transcript. All operations use X-Cos-Token.
  * GET config is the capability probe (404 means old server); health.capabilities.meetingAsk mirrors capabilities.
  */
+
+/** User-confirmed navigation context for one meeting, never canonical transcript evidence. */
+export type MeetingAskDomain = string;
+export interface MeetingAskCalendarMatch {
+    id: string; title: string; start: string; end: string; suggestedDomain?: MeetingAskDomain;
+}
+export interface MeetingAskOrientation {
+    revision: number; domain: MeetingAskDomain | null; calendar: MeetingAskCalendarMatch | null;
+}
+export interface MeetingAskContext {
+    orientation: MeetingAskOrientation; domains: Array<{id: string; label: string}>; candidates: MeetingAskCalendarMatch[]; notices: string[];
+}