@gotcos/glasses-server 6.50.4 → 6.52.0

package/server/routes/health.ts

@@ -49,7 +49,8 @@ import { G2_LENS_VARIANT_CAPABILITY } from '../lib/media-store.js'
 // The flag lives beside the endpoints it describes, so it cannot drift from
 // whether they are actually registered.
 import { MEDIA_CHUNKED_UPLOAD_ENABLED } from './media.js'
-import { durableQueryJobsCapability } from '../lib/query-job-feature.js'
+import { durableQueryJobsCapability, messagesTrailEnabled } from '../lib/query-job-feature.js'
+import { jobTrailStats } from '../lib/job-trail.js'
 import { getQueryJobRuntimeHealth } from '../lib/query-job-runtime.js'
 import { getMorningBriefScheduler } from '../lib/morning-brief-runtime.js'
 import { getTranscriptionPolicySnapshot } from '../lib/transcription-policy.js'
@@ -80,7 +81,10 @@ import {
   threadAttachHealthFields,
 } from '../lib/thread-attach-capability.js'
 import { sessionHooksHealthFields } from '../lib/session-hooks-runtime.js'
+import { permissionBrokerHealthFields, sessionQuestionsCapability } from '../lib/permission-broker.js'
 import { continueLiveEnabled, liveDeliveryStats } from '../lib/session-peer-inbox-deps.js'
+import { codexLiveStats } from '../lib/codex-live-queue-deps.js'
+import { codexLiveQueueEnabled } from '../lib/codex-live-queue.js'
 
 /**
  * 6.49.0: which last hop a Continue takes, and how often each fell back.
@@ -101,6 +105,18 @@ export function continueLiveHealthFields(): Record<string, unknown> {
       lastReason: stats.lastReason,
       lastAt: stats.lastAt,
     },
+    // 6.51.0: Codex's last hop, counted apart so the Claude row above keeps its meaning.
+    codexLiveQueue: (() => {
+      const codex = codexLiveStats()
+      return {
+        enabled: codexLiveQueueEnabled(),
+        attempts: codex.attempts,
+        delivered: codex.delivered,
+        fallbacks: codex.fallbacks,
+        lastReason: codex.lastReason,
+        lastAt: codex.lastAt,
+      }
+    })(),
   }
 }
 
@@ -374,6 +390,9 @@ healthRouter.get('/health', async (_req, res) => {
     server_version: managedServerVersion(),
     ...threadAttachHealthFields(threadAttach),
     ...sessionHooksHealthFields(),
+    // 6.52.0: counts, the mode and two timestamps; never an id, a question, a command, or
+    // how many are held (that is on the authenticated questions route).
+    ...permissionBrokerHealthFields(),
     ...continueLiveHealthFields(),
     server_instance_id: getServerInstanceId(),
     boot_id: serverMetrics.bootId,
@@ -465,6 +484,12 @@ healthRouter.get('/health', async (_req, res) => {
       protocolVersion: durableJobs.protocolVersion,
       state: durableJobs.store.state,
     },
+    // 6.52.0: the Messages trail's readers, process-wide since boot. Counts and a
+    // timestamp only: stdout lines read, entries emitted, failures swallowed.
+    messages_trail: {
+      enabled: durableJobs.enabled && messagesTrailEnabled(),
+      ...jobTrailStats(),
+    },
   })
 })
 
@@ -554,7 +579,15 @@ healthRouter.get('/models', async (req, res) => {
       durableQueryJobs: {
         enabled: durableJobs.enabled,
         protocolVersion: durableJobs.protocolVersion,
+        // 6.52.0: jobs journal `trail` events and carry `snapshot.trail`. The app reads
+        // THIS surface (not /api/health) and falls back to the activity log without it.
+        // False whenever jobs themselves are off or COS_MESSAGES_TRAIL=0.
+        trail: durableJobs.enabled && messagesTrailEnabled(),
       },
+      // 6.52.0: the session questions API and its client contract. A client polls
+      // `GET /api/session-questions?client=glasses|phone` every `pollIntervalMs`; one
+      // quiet for `liveWindowMs` hands every held request back to the Mac.
+      sessionQuestions: sessionQuestionsCapability(),
       transcription: {
         ...transcription,
         live: transcriptionLive,

package/server/routes/permission-broker.ts

@@ -0,0 +1,176 @@
+// The permission broker's two doors (6.52.0). See `lib/permission-broker.ts` for the why.
+//
+// POST /api/permission-requests/ask -- the COS session hook, on a PermissionRequest at a
+// desk idle for 90 s. THIS IS THE URL THE 6.51.0 SCRIPT ALREADY CALLS, so no Mac needs
+// `--hooks install` again (QA round 1: a new URL meant a new script, and every Mac that did
+// not reinstall would have shown Control's "hooks outdated" banner and kept the old door).
+// The hook holds the per-install HOOK token (`~/.cos-glasses/hook-token`, 0600), never the
+// pairing token the /api gate checks, so this one route is registered BEFORE that gate and
+// before the global body parser, as a deliberate exemption for exactly this method and
+// path: it checks the hook token itself, in constant time, BEFORE it reads a byte of the
+// body, and only then parses up to 2 MB. Any other method on the path falls through to the
+// /api gate like every other /api route. It answers only `{}` or a
+// `{"hookSpecificOutput": ...}` the hook prints verbatim, and is mounted unconditionally
+// (not behind COS_THREAD_ATTACH_ENABLED): the switch is `COS_PERMISSION_BROKER`, read per
+// request. It holds no maintenance lease; the broker refuses to park during a drain itself.
+//
+// Mixed versions fail safe. Against a 6.51 server the same script gets 401 from the /api
+// gate, prints nothing, and the native dialog shows, as it always did there.
+//
+// GET /api/session-questions and POST /api/session-questions/:id/answer -- the lens and the
+// phone, behind the API token like every other /api route. Question and command text only
+// ever travels here, never on the display bus. The GET is ALSO the broker's liveness
+// signal (lib/client-liveness.ts), and only when it names the client: `?client=glasses` or
+// `?client=phone`. Anything else (missing, `control`, a typo) is answered but never counts,
+// so a surface that only shows a count can poll without making the Mac hold questions it
+// cannot answer. It checks X-Cos-Token itself as well, in constant time, and a request
+// without it is refused and never counted, whatever sits in front of this router.
+
+import express, { Router, type NextFunction, type Request, type Response } from 'express'
+import { timingSafeTokenEqual } from '../lib/token-auth.js'
+import {
+  ANSWERING_CLIENTS,
+  CLIENT_LIVE_WINDOW_MS,
+  QUESTIONS_POLL_INTERVAL_MS,
+  SESSION_QUESTIONS_PROTOCOL_VERSION,
+  type BrokerAdmission,
+  type HookReplyChannel,
+  type PermissionBroker,
+} from '../lib/permission-broker.js'
+import { noteQuestionsPoll } from '../lib/client-liveness.js'
+
+export const PERMISSION_BROKER_HOOK_PATH = '/api/permission-requests/ask'
+/** The hook posts its spool envelope, capped at 1 MiB by the script itself. */
+export const PERMISSION_BROKER_BODY_LIMIT = '2mb'
+
+export interface PermissionBrokerHookRouterDeps {
+  /** The per-install hook token, or null when none has been minted (then nothing is answered). */
+  hookToken: () => string | null
+  broker: PermissionBroker
+}
+
+/**
+ * The hook-token check, as middleware that runs BEFORE any body parser: a request without
+ * the token is answered 401 without a byte of its body being read or parsed.
+ */
+export function requireHookToken(hookToken: () => string | null) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    res.set('Cache-Control', 'private, no-store')
+    let expected: string | null = null
+    try { expected = hookToken() } catch { expected = null }
+    if (!expected || !timingSafeTokenEqual(req.headers['x-cos-hook-token'], expected)) {
+      res.status(401).json({})
+      return
+    }
+    next()
+  }
+}
+
+/** The held response, as the broker sees it. */
+export function replyChannelFor(res: Response): HookReplyChannel {
+  const writable = (): boolean => {
+    if (res.headersSent || res.writableEnded || res.destroyed) return false
+    const socket = res.socket
+    return !!socket && !socket.destroyed && socket.writable !== false
+  }
+  return {
+    writable,
+    reply(body) {
+      if (!writable()) return false
+      try {
+        res.status(200).json(body)
+        return true
+      } catch {
+        return false
+      }
+    },
+  }
+}
+
+export function createPermissionBrokerHookRouter(deps: PermissionBrokerHookRouterDeps): Router {
+  const router = Router()
+  router.post(
+    PERMISSION_BROKER_HOOK_PATH,
+    requireHookToken(deps.hookToken),
+    express.json({ limit: PERMISSION_BROKER_BODY_LIMIT }),
+    async (req: Request, res: Response) => {
+      let admission: BrokerAdmission
+      try {
+        admission = await deps.broker.admit(req.body)
+      } catch (error) {
+        console.error(`[permission-broker] admit failed: ${error instanceof Error ? error.message : error}`)
+        res.json({})
+        return
+      }
+      if (!admission.ok) {
+        res.json({})
+        return
+      }
+      const channel = replyChannelFor(res)
+      // The hook gave up during the desk read: nothing to hold.
+      if (!channel.writable()) {
+        deps.broker.noteFastPath('hook_gone_early')
+        return
+      }
+      const id = deps.broker.park(admission.request, channel)
+      // `res` close, not `req` close: since Node 16 the request emits `close` once its body
+      // is read, which is not the hook leaving. A close after the reply is a no-op.
+      res.on('close', () => { deps.broker.hookClosed(id) })
+    },
+  )
+  // A body the parser refused (too large, not JSON): `{}` and nothing else, never a stack.
+  router.use(PERMISSION_BROKER_HOOK_PATH, (error: unknown, _req: Request, res: Response, next: NextFunction) => {
+    if (res.headersSent) { next(error); return }
+    deps.broker.noteFastPath('malformed')
+    const status = Number((error as { status?: unknown })?.status)
+    res.status(Number.isInteger(status) && status >= 400 && status < 500 ? status : 400).json({})
+  })
+  return router
+}
+
+export interface SessionQuestionsRouterDeps {
+  broker: PermissionBroker
+  /** The pairing token (X-Cos-Token). A poll counts as a live client only with it. */
+  apiToken: () => string
+  /** Where a counted poll is recorded; `noteQuestionsPoll` in production. */
+  notePoll?: (at: number) => void
+  now?: () => number
+}
+
+export function createSessionQuestionsRouter(deps: SessionQuestionsRouterDeps): Router {
+  const router = Router()
+  const notePoll = deps.notePoll ?? noteQuestionsPoll
+  const now = deps.now ?? Date.now
+  router.get('/session-questions', (req: Request, res: Response) => {
+    res.set('Cache-Control', 'private, no-store')
+    let expected = ''
+    try { expected = deps.apiToken() } catch { expected = '' }
+    // A hook token, or nothing: refused, and never a live client.
+    if (!timingSafeTokenEqual(req.headers['x-cos-token'], expected)) {
+      res.status(401).json({ error: 'unauthorized' })
+      return
+    }
+    // Only a client that says it can answer (and shows the cards) counts as live.
+    const client = typeof req.query.client === 'string' ? req.query.client : ''
+    if (ANSWERING_CLIENTS.has(client)) notePoll(now())
+    const health = deps.broker.health()
+    // Listed first: a deadline the timer has not caught yet is settled by the listing.
+    const items = deps.broker.list()
+    res.json({
+      enabled: health.enabled,
+      mode: health.mode,
+      protocolVersion: SESSION_QUESTIONS_PROTOCOL_VERSION,
+      pollIntervalMs: QUESTIONS_POLL_INTERVAL_MS,
+      liveWindowMs: CLIENT_LIVE_WINDOW_MS,
+      pending: deps.broker.pendingCount(),
+      stats: deps.broker.stats(),
+      items,
+    })
+  })
+  router.post('/session-questions/:id/answer', (req: Request, res: Response) => {
+    res.set('Cache-Control', 'private, no-store')
+    const result = deps.broker.answer(String(req.params.id ?? ''), req.body)
+    res.status(result.status).json(result.body)
+  })
+  return router
+}

package/server/routes/query-jobs.ts

@@ -1,4 +1,4 @@
-import { Router, type Response } from 'express'
+import { Router, type Request, type Response } from 'express'
 import { durableQueryJobsEnabled } from '../lib/query-job-feature.js'
 import {
   QueryJobCoordinator,
@@ -16,6 +16,7 @@ import {
   QueryJobPersistenceError,
   QueryJobProviderOrphanFenceError,
   QueryJobStoreError,
+  type QueryJobTrailFrame,
 } from '../lib/query-job-store.js'
 import {
   isTerminalQueryJobStatus,
@@ -89,7 +90,25 @@ function writeSse(res: Response, type: string, event: Record<string, unknown>):
   res.write(`event: ${type}\ndata: ${JSON.stringify(event)}\n\n`)
 }
 
-function snapshotEvent(job: QueryJobSnapshot, reason: string): Record<string, unknown> {
+/**
+ * THE TRAIL IS OPT-IN (6.52.0 QA round 1). A client that does not send `?trail=1` gets
+ * exactly the 6.51.0 bytes: no `trail` frames on the stream, and no `trail` field on any
+ * snapshot, in any response. A client that does gets `trail` frames (their own dense
+ * `trailSeq`, no `id:` line, so Last-Event-ID stays the job eventSeq) and, on subscribe or
+ * reconnect, every entry after its `trailAfter` from `snapshot.trail`, or one
+ * `trail_snapshot` frame to rebuild from when entries it missed are no longer held.
+ */
+function wantsTrail(req: Request): boolean {
+  return req.query.trail === '1'
+}
+
+function forClient(job: QueryJobSnapshot, trail: boolean): QueryJobSnapshot {
+  if (trail || !('trail' in job)) return job
+  const { trail: _trail, ...rest } = job
+  return rest as QueryJobSnapshot
+}
+
+function snapshotEvent(job: QueryJobSnapshot, reason: string, trail: boolean): Record<string, unknown> {
   return {
     type: 'snapshot',
     eventSeq: job.eventSeq,
@@ -98,7 +117,7 @@ function snapshotEvent(job: QueryJobSnapshot, reason: string): Record<string, un
     generation: job.generation,
     status: job.status,
     at: job.updatedAt,
-    data: { reason, job },
+    data: { reason, job: forClient(job, trail) },
   }
 }
 
@@ -122,7 +141,7 @@ export function createQueryJobsRouter(
     try {
       const prepared = options.prepareAdmission ? await options.prepareAdmission(req.body) : req.body
       const admission = await coordinator.submit(prepared)
-      return res.status(202).json({ job: admission.job })
+      return res.status(202).json({ job: forClient(admission.job, wantsTrail(req)) })
     } catch (error) {
       const wire = wireError(error)
       return res.status(wire.status).json(wire.body)
@@ -138,7 +157,7 @@ export function createQueryJobsRouter(
       const generation = requiredGeneration(req.query.generation)
       const job = await coordinator.getByClientGeneration(clientJobId, generation)
       if (!job) throw new QueryJobNotFoundError(`${clientJobId}:${generation}`)
-      return res.json({ job })
+      return res.json({ job: forClient(job, wantsTrail(req)) })
     } catch (error) {
       const wire = wireError(error)
       return res.status(wire.status).json(wire.body)
@@ -150,7 +169,7 @@ export function createQueryJobsRouter(
       const jobId = validJobId(req.params.jobId)
       const generation = requiredGeneration(req.query.generation)
       const job = await coordinator.getSnapshot(jobId, generation)
-      return res.json({ job })
+      return res.json({ job: forClient(job, wantsTrail(req)) })
     } catch (error) {
       const wire = wireError(error)
       return res.status(wire.status).json(wire.body)
@@ -163,7 +182,15 @@ export function createQueryJobsRouter(
     let closed = false
     let streamReady = false
     let sentSeq = -1
+    let sentTrailSeq = 0
     const pendingLive: QueryJobEvent[] = []
+    const pendingTrail: QueryJobTrailFrame[] = []
+    const trail = wantsTrail(req)
+    const writeTrail = (frame: QueryJobTrailFrame) => {
+      if (closed || frame.trailSeq <= sentTrailSeq) return
+      sentTrailSeq = frame.trailSeq
+      writeSse(res, 'trail', frame as unknown as Record<string, unknown>)
+    }
     const cleanup = () => {
       if (closed) return
       closed = true
@@ -184,8 +211,22 @@ export function createQueryJobsRouter(
       const generation = requiredGeneration(req.query.generation)
       const after = cursor(req.query.after)
       sentSeq = after
+      const trailAfter = trail ? cursor(req.query.trailAfter) : 0
+      sentTrailSeq = trailAfter
+      const trailSubscription = trail
+        ? {
+          after: trailAfter,
+          listener: (frame: QueryJobTrailFrame) => {
+            if (!streamReady) {
+              pendingTrail.push(frame)
+              return
+            }
+            writeTrail(frame)
+          },
+        }
+        : undefined
 
-      const subscription = await coordinator.subscribe(jobId, generation, after, (event: QueryJobEvent) => {
+      const onEvent = (event: QueryJobEvent) => {
         // subscribe() registers its live listener before returning the replay
         // snapshot so no append can fall into a gap. A very fast provider may
         // therefore publish while this route is still installing SSE headers.
@@ -199,7 +240,11 @@ export function createQueryJobsRouter(
         sentSeq = event.eventSeq
         writeSse(res, event.type, event as unknown as Record<string, unknown>)
         if (isTerminalQueryJobStatus(event.status)) finish()
-      })
+      }
+      // Without `?trail=1` the call is exactly the 6.51.0 one.
+      const subscription = trailSubscription
+        ? await coordinator.subscribe(jobId, generation, after, onEvent, trailSubscription)
+        : await coordinator.subscribe(jobId, generation, after, onEvent)
       unsubscribe = subscription.unsubscribe
       if (closed) {
         unsubscribe()
@@ -216,9 +261,33 @@ export function createQueryJobsRouter(
       res.flushHeaders()
       res.write(': keepalive\n\n')
 
-      const { replay } = subscription
+      const { replay, trailReplay } = subscription
+      // The trail first: every entry precedes the terminal event that may end this stream.
+      if (trail && trailReplay) {
+        if (trailReplay.gap) {
+          writeSse(res, 'trail_snapshot', {
+            type: 'trail_snapshot',
+            reason: trailReplay.reason ?? 'trail_gap',
+            jobId: replay.snapshot.jobId,
+            clientJobId: replay.snapshot.clientJobId,
+            generation: replay.snapshot.generation,
+            oldestTrailSeq: trailReplay.oldestTrailSeq,
+            latestTrailSeq: trailReplay.latestTrailSeq,
+            trail: trailReplay.entries,
+          })
+          sentTrailSeq = trailReplay.latestTrailSeq
+        } else {
+          for (const entry of trailReplay.entries) {
+            const { trailSeq, at, ...data } = entry
+            writeTrail({
+              type: 'trail', trailSeq, at, data,
+              jobId: replay.snapshot.jobId, clientJobId: replay.snapshot.clientJobId, generation: replay.snapshot.generation,
+            } as QueryJobTrailFrame)
+          }
+        }
+      }
       if (replay.gap) {
-        writeSse(res, 'snapshot', snapshotEvent(replay.snapshot, replay.reason ?? 'replay_gap'))
+        writeSse(res, 'snapshot', snapshotEvent(replay.snapshot, replay.reason ?? 'replay_gap', trail))
         sentSeq = replay.snapshot.eventSeq
       } else {
         for (const event of replay.events) {
@@ -230,7 +299,7 @@ export function createQueryJobsRouter(
 
       const replayTerminal = replay.events.some(event => isTerminalQueryJobStatus(event.status))
       if (isTerminalQueryJobStatus(replay.snapshot.status) && !replayTerminal && !replay.gap) {
-        writeSse(res, 'snapshot', snapshotEvent(replay.snapshot, 'terminal_snapshot'))
+        writeSse(res, 'snapshot', snapshotEvent(replay.snapshot, 'terminal_snapshot', trail))
         sentSeq = replay.snapshot.eventSeq
       }
       if (isTerminalQueryJobStatus(replay.snapshot.status)) {
@@ -239,6 +308,8 @@ export function createQueryJobsRouter(
       }
 
       streamReady = true
+      for (const frame of pendingTrail) writeTrail(frame)
+      pendingTrail.length = 0
       for (const event of pendingLive) {
         if (closed || event.eventSeq <= sentSeq) continue
         sentSeq = event.eventSeq
@@ -271,7 +342,7 @@ export function createQueryJobsRouter(
       const jobId = validJobId(req.params.jobId)
       const generation = requiredGeneration(req.body?.generation)
       const { job } = await coordinator.cancel(jobId, generation)
-      return res.json({ job })
+      return res.json({ job: forClient(job, wantsTrail(req)) })
     } catch (error) {
       const wire = wireError(error)
       return res.status(wire.status).json(wire.body)
@@ -283,7 +354,7 @@ export function createQueryJobsRouter(
       const jobId = validJobId(req.params.jobId)
       const generation = requiredGeneration(req.body?.generation)
       const job = await coordinator.acknowledge(jobId, generation)
-      return res.json({ job })
+      return res.json({ job: forClient(job, wantsTrail(req)) })
     } catch (error) {
       const wire = wireError(error)
       return res.status(wire.status).json(wire.body)

package/server/routes/thread-turn-queue.ts

@@ -119,7 +119,14 @@ export async function drainThread(
     // for every queued row repeats a whole-process descriptor scan. A refusal
     // can delay delivery until the next sweep, but can never authorize a write.
     // Positive verdicts and all checks after a delivery remain fresh.
-    const gate: ReturnType<ThreadTurnQueueDeps['occupancy']> = refusedGate ?? deps.occupancy(provider, threadId)
+    //
+    // 6.51.0: a Cursor turn is NEVER delivered from here. It leaves through the
+    // composer's own Stop hook (`routes/cursor-stop-followup.ts`), which claims it the
+    // moment the turn ends; a second deliverer could hand the same sentence over twice.
+    // The pass still runs for it so the TTL retires an unclaimed turn honestly.
+    const gate: ReturnType<ThreadTurnQueueDeps['occupancy']> = provider === 'cursor'
+      ? { attachable: false, reason: 'cursor_stop_hook_delivery' }
+      : refusedGate ?? deps.occupancy(provider, threadId)
     if (!gate.attachable) refusedGate = gate
     const seen: DrainObservation = {
       attachable: gate.attachable,
@@ -228,15 +235,18 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
       return res.status(400).json({ error: 'invalid_request', reason: 'invalid_cos_session_id' })
     }
 
-    if (provider === 'cursor') {
-      return res.status(423).json({ error: 'unsupported_provider', queueable: false })
-    }
-
     // THE GATE DECIDES WHETHER PARKING IS EVEN HONEST. A structural refusal can never
     // clear, and telling someone their turn is queued when it can never run is worse
     // than refusing it. An attachable thread is not queued either -- it is sent now,
     // through the ordinary route, which the client does on this 409.
     const gate = deps.occupancy(provider, threadId)
+
+    // 6.51.0: Cursor queues ONLY a composer its hooks show mid-turn, because the only way
+    // in is that turn's Stop hook. An idle composer fires no Stop, so a turn parked there
+    // could never run; that stays the 423 it always was, as does every Agent CLI chat.
+    if (provider === 'cursor' && gate.reason !== 'native_thread_working') {
+      return res.status(423).json({ error: 'unsupported_provider', queueable: false })
+    }
     if (gate.attachable) return res.status(409).json({ error: 'thread_free', hint: 'send_now' })
     if (!queueableRefusal(gate.reason)) {
       return res.status(423).json({ error: gate.reason ?? 'probe_failed', queueable: false })