@gotcos/glasses-server 6.66.0 → 6.70.0

package/server/routes/health.ts

@@ -1,4 +1,5 @@
 import { DICTATION_CLEAN_MODELS } from '../lib/dictation-clean-models.js'
+import { PAIRING_PROTOCOL_VERSION } from '../lib/glasses-pairing.js'
 import { taskBridgeAvailable } from '../lib/task-bridge.js'
 import { Router } from 'express'
 import { isWorthRecovering } from '../lib/quarantine-auto-recover.js'
@@ -26,6 +27,7 @@ import {
 } from '../lib/whisper-local.js'
 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 { lensGistPublicHealth } from '../lib/lens-gist.js'
 import { meetingSummaryLLMEnabled } from '../lib/meeting-summary.js'
 import { getKeyStatus } from '../lib/openai-key.js'
@@ -464,7 +466,12 @@ healthRouter.get('/health', async (_req, res) => {
     review_audio: reviewAudio,
     ...(voiceProvenance ? { voice_provenance: voiceProvenance } : {}),
     capabilities: {
+      meetingAsk: { protocolVersion: 2, durableHistory: true, attachmentContext: true, 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
+      // the phone knows to say "Update COS on your Mac (server 6.67 or newer)".
+      pairing: { version: PAIRING_PROTOCOL_VERSION },
       // Advertised on the PUBLIC health route on purpose: a client deciding whether
       // to request a display ticket may not hold a usable token yet, and an old
       // server simply omits this key, which is how a new client detects it.
@@ -625,6 +632,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 },
       dictationCleanup: { models: DICTATION_CLEAN_MODELS },
       durableQueryJobs: {
         enabled: durableJobs.enabled,

package/server/routes/live-cos-ask.ts

@@ -0,0 +1,19 @@
+import { Router } from 'express'
+import { AskError, normalizeAsk } from '../lib/live-cos-ask.js'
+import { maintenanceAdmissionsOpen } from '../lib/maintenance-lifecycle.js'
+import { meetingAskRuntime } from '../lib/meeting-ask-runtime.js'
+export const liveCosAskRouter = Router()
+liveCosAskRouter.post('/meetings/live-ask', async (req, res) => {
+  res.set('Cache-Control', 'no-store')
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), 150_000)
+  res.once('close', () => { if (!res.writableEnded) controller.abort() })
+  try {
+    if (!maintenanceAdmissionsOpen()) throw new AskError('maintenance', 503)
+    // Authentication is provided by index.ts before all /api routes. No model-owned tools.
+    const input = normalizeAsk(req.body)
+    res.json(await meetingAskRuntime.legacy(input, controller.signal))
+  } catch (error) {
+    if (!res.destroyed) res.status(error instanceof AskError ? error.status : 503).json({ error: error instanceof AskError ? error.reason : 'haiku_unavailable' })
+  } finally { clearTimeout(timer) }
+})

package/server/routes/meeting-ask.ts

@@ -0,0 +1,128 @@
+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 { 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. */
+export function exportMeetingAsk(exchanges: MeetingAskExchange[], files: MeetingAskFile[]): string {
+    const parts = ['## Meeting assistant history'];
+    for (const e of exchanges) {
+        parts.push(`### ${e.createdAt} · ${e.action}\n\nQuestion: ${e.question || e.action}\n\nStatus: ${e.status}\nModel: ${e.model ?? `${e.selectedModel.engine}:${e.selectedModel.model}`}\nTranscript through: ${e.throughMs} ms`);
+        if (e.answer)
+            parts.push(e.answer.replace(/\[([THFW]\d+)\]/g, (_, id) => `[${e.requestId}:${id}]`));
+        for (const s of e.sources)
+            parts.push(`[${e.requestId}:${s.id}] ${s.title}${s.url ? ` — ${s.url}` : ''}\n${s.text}`);
+        if (e.notices.length)
+            parts.push('Coverage: ' + e.notices.join(' '));
+        if (e.error)
+            parts.push('Outcome: ' + e.error);
+    }
+    parts.push('## Meeting files');
+    const revisions = new Map<string, MeetingAskFile>();
+    for (const e of exchanges)
+        for (const f of e.files)
+            if (!revisions.has(`${f.id}@${f.revision}`) || f.status === 'ready')
+                revisions.set(`${f.id}@${f.revision}`, f);
+    // Current removal/failure is lifecycle metadata, never a replacement for admitted evidence.
+    for (const f of files) {
+        const key = `${f.id}@${f.revision}`, admitted = revisions.get(key);
+        if (!admitted)
+            revisions.set(key, f);
+        else if (admitted.status !== f.status)
+            parts.push(`Current file status: ${f.name} (${f.status}) · ${key}\nHistorical admitted context is retained below.`);
+    }
+    for (const f of revisions.values())
+        parts.push(`### ${f.name} (${f.status})\nReference: ${f.id}@${f.revision}\n${f.text || 'No extracted text available.'}`);
+    const text = parts.join('\n\n');
+    if (Buffer.byteLength(text, 'utf8') > 850000)
+        throw new AskError('export_too_large', 413);
+    return text;
+}
+export function createMeetingAskRouter(runtime: MeetingAskRuntime = meetingAskRuntime) {
+    const router = Router();
+    router.use((_q, res, next) => { res.set('Cache-Control', 'no-store'); next(); });
+    router.get('/meeting-ask/config', async (_q, res) => { try {
+        res.json(await runtime.config());
+    }
+    catch (e) {
+        failure(res, e);
+    } });
+    router.put('/meeting-ask/config', async (req, res) => { try {
+        res.json(await runtime.setConfig(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) });
+    }
+    catch (e) {
+        failure(res, e);
+    } });
+    router.get('/meeting-ask/requests/:id', (req, res) => { try {
+        res.json({ exchange: runtime.get(String(req.params.id)) });
+    }
+    catch (e) {
+        failure(res, e);
+    } });
+    router.post('/meeting-ask/requests/:id/cancel', (req, res) => { try {
+        res.json({ exchange: runtime.cancel(String(req.params.id), req.body?.serverInstanceId) });
+    }
+    catch (e) {
+        failure(res, e);
+    } });
+    router.get('/meeting-ask/history', (req, res) => { try {
+        const offset = Number(req.query.offset ?? 0), limit = Number(req.query.limit ?? 50);
+        const order = req.query.order ?? 'asc';
+        if (!Number.isFinite(offset) || !Number.isFinite(limit) || !['asc', 'desc'].includes(String(order)))
+            throw new AskError('invalid_page');
+        res.json(runtime.history(String(req.query.sessionId ?? ''), req.query.serverInstanceId, offset, limit, order as 'asc' | 'desc'));
+    }
+    catch (e) {
+        failure(res, e);
+    } });
+    router.put('/meeting-ask/files', (req, res) => { try {
+        res.json({ files: runtime.putFiles(req.body?.sessionId, req.body?.serverInstanceId, req.body?.files) });
+    }
+    catch (e) {
+        failure(res, e);
+    } });
+    router.get('/meeting-ask/export', (req, res) => {
+        try {
+            const exchanges: MeetingAskExchange[] = [];
+            let offset: number | null = 0;
+            let files: MeetingAskFile[] = [];
+            do {
+                const page = runtime.history(String(req.query.sessionId ?? ''), req.query.serverInstanceId, offset, 100);
+                exchanges.push(...page.exchanges);
+                files = page.files;
+                offset = page.nextOffset;
+            } while (offset !== null);
+            res.json({ text: exportMeetingAsk(exchanges, files) });
+        }
+        catch (e) {
+            failure(res, e);
+        }
+    });
+    router.get('/meeting-ask/transcript', (req, res) => {
+        try {
+            runtime.identity(req.query.serverInstanceId);
+            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: [] });
+        }
+        catch (e) {
+            failure(res, e);
+        }
+    });
+    return router;
+}
+export const meetingAskRouter = createMeetingAskRouter();

package/server/routes/pairing.ts

@@ -0,0 +1,121 @@
+// Glasses pairing routes (6.67.0). Contract: docs/pairing-contract.md.
+//
+// Mounted under /api AFTER requireApiToken and BEFORE the mutation-lease catch-all and
+// the global 10 MB JSON parser:
+// - POST /pairing/claim and GET /pairing/claim/:nonce are public (exact matches in
+//   isPublicApiRequest); everything else here needs the token AND a loopback socket.
+// - The routes write no files, so they never take the mutation lease. During a drain or
+//   shutdown, minting, claiming, status and decisions answer 503 `draining`. The poll is
+//   still served: it writes nothing, and a token the user already allowed must still
+//   reach the phone if the update gate closes between Allow and the next poll.
+// - Each route parses its own body with a 1 KB cap.
+//
+// Every address decision reads `req.socket.remoteAddress`, never `req.ip` or
+// X-Forwarded-For. Codes, nonces, tokens and QR text are never logged (lib/glasses-pairing.ts
+// logs the IP, the result and a 2-character hash of the code).
+
+import express, { Router, type ErrorRequestHandler, type Request, type RequestHandler, type Response } from 'express'
+import { isLoopbackSocket } from '../lib/network-policy.js'
+import {
+  PAIRING_NONCE_PATTERN,
+  PAIRING_REASON_MESSAGE,
+  PAIRING_REASON_STATUS,
+  PairingError,
+  type PairingReason,
+  type PairingState,
+} from '../lib/glasses-pairing.js'
+
+export interface PairingRouterOptions {
+  /** Read per request so a restart created after mount is honoured in tests. */
+  state: () => PairingState
+  /** True while the server is shutting down or the maintenance gate is closed. */
+  isDraining: () => boolean
+}
+
+function sendReason(res: Response, reason: PairingReason, retryAfterSeconds?: number, status?: number): void {
+  if (retryAfterSeconds != null) res.setHeader('Retry-After', String(retryAfterSeconds))
+  res.status(status ?? PAIRING_REASON_STATUS[reason]).json({ reason, message: PAIRING_REASON_MESSAGE[reason] })
+}
+
+function sendError(res: Response, error: unknown): void {
+  if (error instanceof PairingError) return sendReason(res, error.reason, error.retryAfterSeconds)
+  console.error('[pairing] internal error:', error instanceof Error ? error.message : 'unknown')
+  res.status(500).json({ reason: 'internal', message: 'Pairing failed on the Mac. Try again.' })
+}
+
+function socketIp(req: Request): string {
+  return req.socket?.remoteAddress ?? ''
+}
+
+export function createPairingRouter(options: PairingRouterOptions): Router {
+  const router = Router()
+  const smallJson = express.json({ limit: '1kb' })
+
+  const notDraining: RequestHandler = (_req, res, next) => {
+    if (options.isDraining()) return sendReason(res, 'draining', 30)
+    next()
+  }
+  const loopbackOnly: RequestHandler = (req, res, next) => {
+    if (!isLoopbackSocket(req)) return sendReason(res, 'not_loopback')
+    next()
+  }
+  const body = (req: Request): Record<string, unknown> =>
+    req.body && typeof req.body === 'object' && !Array.isArray(req.body) ? req.body as Record<string, unknown> : {}
+
+  router.post('/pairing/code', notDraining, loopbackOnly, smallJson, (req, res) => {
+    const input = body(req)
+    if (input.allowLan !== undefined && typeof input.allowLan !== 'boolean') return sendReason(res, 'bad_request')
+    try {
+      res.json(options.state().mint({ allowLan: input.allowLan === true }))
+    } catch (error) { sendError(res, error) }
+  })
+
+  router.post('/pairing/claim', notDraining, smallJson, (req, res) => {
+    const input = body(req)
+    try {
+      options.state().claim({ code: input.code, nonce: input.nonce }, socketIp(req))
+      res.status(202).json({ pending: true })
+    } catch (error) { sendError(res, error) }
+  })
+
+  router.get('/pairing/claim/:nonce', (req, res) => {
+    // Express routes HEAD to a GET handler. Only a real GET may read (and so spend) the
+    // token; api-auth.ts already keeps HEAD behind the token, this holds it here too.
+    if (req.method !== 'GET') {
+      res.setHeader('Allow', 'GET')
+      return sendReason(res, 'bad_request', undefined, 405)
+    }
+    const nonce = req.params.nonce
+    if (typeof nonce !== 'string' || !PAIRING_NONCE_PATTERN.test(nonce)) return sendReason(res, 'bad_request')
+    try {
+      res.setHeader('Cache-Control', 'no-store')
+      res.json(options.state().poll(nonce, socketIp(req)))
+    } catch (error) { sendError(res, error) }
+  })
+
+  router.get('/pairing/status', notDraining, loopbackOnly, (_req, res) => {
+    try {
+      res.setHeader('Cache-Control', 'no-store')
+      res.json(options.state().status())
+    } catch (error) { sendError(res, error) }
+  })
+
+  router.post('/pairing/decision', notDraining, loopbackOnly, smallJson, (req, res) => {
+    const input = body(req)
+    try {
+      options.state().decide(input.nonce, input.allow)
+      res.json({ ok: true })
+    } catch (error) { sendError(res, error) }
+  })
+
+  // A body over 1 KB or one that is not JSON answers in the contract's shape, not
+  // Express's HTML error page. Scoped to this router's own parsers.
+  const parseError: ErrorRequestHandler = (error, req, res, next) => {
+    if (!req.path.startsWith('/pairing/')) return next(error)
+    if (res.headersSent) return next(error)
+    sendReason(res, 'bad_request')
+  }
+  router.use(parseError)
+
+  return router
+}

package/shared/meeting-ask.ts

@@ -0,0 +1,106 @@
+/** Meeting assistance v2. Additive to the legacy /api/meetings/live-ask contract. */
+export type MeetingAskAction = 'catch_up' | 'summary' | 'questions' | 'actions' | 'ask';
+export type MeetingAskEngine = 'claude' | 'codex' | 'cursor' | 'ollama';
+export interface MeetingAskModel {
+    engine: MeetingAskEngine;
+    model: string;
+}
+export interface MeetingAskTurn {
+    id: number;
+    elapsedMs: number;
+    speaker: string;
+    text: string;
+}
+export interface MeetingAskFile {
+    id: string;
+    revision: string;
+    name: string;
+    status: 'ready' | 'pending' | 'unsupported' | 'failed' | 'removed' | 'secret-held';
+    text: string;
+    notice?: string;
+}
+export interface MeetingAskSource {
+    id: string;
+    kind: 'transcript' | 'memory' | 'meeting' | 'file' | 'web';
+    title: string;
+    text: string;
+    turnId?: number;
+    elapsedMs?: number;
+    sessionId?: string;
+    recordId?: string;
+    memoryId?: string;
+    domain?: string;
+    month?: string;
+    filename?: string;
+    fileId?: string;
+    revision?: string;
+    url?: string;
+    retrievedAt?: string;
+    retrievalId?: string;
+}
+export interface MeetingAskSubmit {
+    requestId: string;
+    sessionId: string;
+    serverInstanceId: string;
+    action: MeetingAskAction;
+    question: string;
+    elapsedMs: number;
+    turns: MeetingAskTurn[];
+    model?: MeetingAskModel;
+    files?: Array<{
+        id: string;
+        revision: string;
+    }>;
+    retryOf?: string;
+}
+export type MeetingAskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'interrupted';
+export interface MeetingAskExchange {
+    requestId: string;
+    sessionId: string;
+    serverInstanceId: string;
+    action: MeetingAskAction;
+    question: string;
+    status: MeetingAskStatus;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    selectedModel: MeetingAskModel;
+    model?: string;
+    answer?: string;
+    sources: MeetingAskSource[];
+    notices: string[];
+    throughMs: number;
+    files: MeetingAskFile[];
+    error?: string;
+    retryOf?: string;
+}
+export interface MeetingAskCapabilities {
+    protocolVersion: 2;
+    durableHistory: true;
+    attachmentContext: true;
+    webRetrieval: boolean;
+}
+export interface MeetingAskConfig {
+    protocolVersion: 2;
+    serverInstanceId: string;
+    selected: MeetingAskModel;
+    models: Array<MeetingAskModel & {
+        available: boolean;
+        reason?: string;
+    }>;
+    web: {
+        available: boolean;
+        reason?: string;
+        engine?: string;
+    };
+    capabilities: MeetingAskCapabilities;
+}
+/** All paths under /api/meeting-ask. GET config; PUT config {engine,model}.
+ * 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.
+ * 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.
+ */