@gotcos/glasses-server 6.35.0 → 6.36.0

package/CHANGELOG.md

@@ -2219,6 +2219,49 @@ unsaved capture, and makes batch status stop lying about finished work.
 
 # Changelog
 
+## [6.36.0] - 2026-08-17
+
+### Sessions push instead of being polled
+
+A new SSE route streams what an agent session is doing, so the glasses stop
+re-asking every five seconds. Two cases, and the difference between them is real
+rather than something the UI papers over.
+
+- **`GET /api/agent-sessions/:provider/:sessionId/stream`** — one event per step
+  (`tool` / `prose` / `status` / `heartbeat`), a monotonic `seq` so a client can
+  see loss, and a heartbeat at least every 20s so silence is evidence rather than
+  ambiguity. Authenticated like every other route; `COS_SESSION_STREAM_ENABLED=0`
+  turns it off.
+- **A turn COS started streams from the pipe.** The child already ran with
+  `--output-format stream-json --verbose`; its stdout was read only to confirm a
+  session id and then discarded. It is now teed to the bus as well, and the id
+  scan is untouched.
+- **A session in a desktop window gets row-level push.** COS never spawned that
+  process and has no pipe to it, so the transcript file is the only observable.
+  It is tailed forward from a byte offset, one `stat` per second per OPEN view,
+  and each new record is emitted through the same grammar and envelope. Claude
+  writes a complete record per message, so a long reply lands all at once when it
+  finishes. **That asymmetry cannot be engineered away from a file** and the
+  contract does not claim otherwise.
+- **`fs.watch` was rejected deliberately.** On macOS it coalesces bursts and, on
+  an atomic replace, keeps watching the old inode and simply stops firing — a
+  watcher that goes silent is indistinguishable from a session that went quiet,
+  which is the failure class this repo keeps paying for. A `stat` poll cannot
+  miss a write because it does not observe writes; it observes size, and size is
+  cumulative.
+- **A record too large to stream hands the session back to the poll.** One record
+  in a real transcript on this machine is 1,239,046 bytes. The tail reads up to 4
+  MiB per TICK, so any record up to that arrives intact; a bigger one ends the
+  response with a terminal `done` instead of stalling. Skipping it was tried
+  first and was wrong twice: it wedged (the good record behind the oversized one
+  was skipped too, on every tick, forever — zero events, not even a status) and,
+  even working, it would have silently dropped a reply the user was waiting for.
+- **One watcher per session, ref-counted.** Two glasses on one session is not two
+  pollers on an 81 MB file, and a double release does not tear down a tail
+  another subscriber still holds.
+
+Needs COS Glasses 6.8.372 to be visible. An older app never calls the route.
+
 ## [6.35.0] - 2026-08-16
 
 ### The newest assistant reply arrives whole instead of at 160 characters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.35.0",
+  "version": "6.36.0",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -19,6 +19,8 @@ import { providerProofRouter } from './routes/provider-proof.js'
 import { transcribeRouter } from './routes/transcribe.js'
 import { sessionIndexRouter } from './routes/session-index.js'
 import { agentSessionsRouter } from './routes/agent-sessions.js'
+import { agentSessionStreamRouter } from './routes/agent-session-stream.js'
+import { createAttachedTurnStream } from './lib/session-stream-producer.js'
 import { claudeSessionsRouter } from './routes/claude-sessions.js'
 import {
   createAgentSessionBindingsRouter,
@@ -384,23 +386,45 @@ const deliverAttachedTurnForRoute = async (request: {
     return { attachable: verdict.attachable, reason: verdict.reason }
   })
 
-  return deliverAttachedTurn({
+  // PHASE 1 OF SESSION STREAMING. The child already writes `--output-format
+  // stream-json`; this is the only place that stream reaches anything other than the
+  // adapter's id scanner. Opened before the spawn so a subscriber that connects mid
+  // turn sees `working` rather than silence, and closed in a `finally` because the
+  // duplicate-suppression gate it holds must be released on EVERY exit path -- a stuck
+  // gate would silence Phase 2 for that session permanently.
+  const live = createAttachedTurnStream({
     provider: request.provider,
-    nativeThreadId: request.nativeThreadId,
-    prompt: request.prompt,
-    cwd: workspace.path,
-    // The only policy this build accepts. The adapter refuses anything else and
-    // asserts no bypass/always-approve flag reaches the argv (plan 4.7).
-    policy: 'read_only',
-    deps: {
-      ...base,
-      // `startMs` is deliberately unused: the adapter already probed it as a GATE
-      // (a null there aborts before this is reached), and the route probes again
-      // as the recorder. One record, one authority.
-      recordSpawn: (pid: number, _startMs: number) =>
-        request.onSpawn(pid) ? 'recorded' : 'route_refused_ownership',
-    },
+    sessionId: request.nativeThreadId,
   })
+
+  try {
+    const result = await deliverAttachedTurn({
+      provider: request.provider,
+      nativeThreadId: request.nativeThreadId,
+      prompt: request.prompt,
+      cwd: workspace.path,
+      // The only policy this build accepts. The adapter refuses anything else and
+      // asserts no bypass/always-approve flag reaches the argv (plan 4.7).
+      policy: 'read_only',
+      deps: {
+        ...base,
+        // `startMs` is deliberately unused: the adapter already probed it as a GATE
+        // (a null there aborts before this is reached), and the route probes again
+        // as the recorder. One record, one authority.
+        recordSpawn: (pid: number, _startMs: number) =>
+          request.onSpawn(pid) ? 'recorded' : 'route_refused_ownership',
+        observeStdout: chunk => live.observeStdout(chunk),
+      },
+    })
+    // `done` only for a turn the adapter proved landed. Anything else is `idle`: the
+    // session stopped working, and claiming a completion we could not verify is the
+    // kind of invention the rest of this feature refuses to make.
+    live.finish(result && typeof result === 'object' && (result as { ok?: unknown }).ok === true ? 'done' : 'idle')
+    return result
+  } catch (error) {
+    live.finish('idle')
+    throw error
+  }
 }
 
 /**
@@ -454,6 +478,11 @@ app.use('/api', transcribeRouter)
 app.use('/api', sessionIndexRouter)
 // Claude + Codex + Cursor transcripts from this Mac. Same 7-day window as Control.
 app.use('/api', agentSessionsRouter)
+// The live view of one of those sessions. Four segments ending in a literal `stream`,
+// so it cannot shadow the three-segment transcript route above or the bindings
+// router's `/attachability` below. READ-ONLY, and deliberately NOT behind
+// COS_THREAD_ATTACH_ENABLED -- see the header of the route for why.
+app.use('/api', agentSessionStreamRouter)
 // Presence view of Claude Code sessions on this Mac. Dark unless
 // COS_CLAUDE_SESSIONS_ENABLED=1 — it projects another product's 0700 state dir.
 app.use('/api', claudeSessionsRouter)

package/server/lib/attached-provider-adapter.ts

@@ -462,6 +462,25 @@ export interface AttachedTurnDeps {
    * and prove the turn is refused with zero spawns. Production never sets it.
    */
   buildArgs?: (provider: AttachedProvider, nativeThreadId: string, cwd: string) => string[]
+  /**
+   * A PASSIVE reader of the child's stdout. Optional; omitted changes nothing.
+   *
+   * The turn already spawns with `--output-format stream-json --verbose`, and this
+   * module reads that stream for exactly one thing: proving the returned session id
+   * matches the target. Everything else is discarded. This hook is how the live view
+   * gets a copy without that scan being touched.
+   *
+   * IT IS AN OBSERVER AND IS TREATED AS ONE. Registered as a SECOND `data` listener,
+   * AFTER the scanner, so the scanner runs first on every chunk. It shares no state
+   * with the scanner, it cannot influence any outcome, and a throw from it is caught
+   * and dropped rather than reaching `emit()` where it would starve the listener that
+   * matters. When absent, no second listener is registered at all, which is byte for
+   * byte the behaviour every existing caller and test already has.
+   *
+   * DELIBERATELY NOT A TRANSFORM. It returns nothing, so there is no shape in which a
+   * future edit can let it modify what the scan sees.
+   */
+  observeStdout?: (chunk: string) => void
 }
 
 export interface AttachedTurnRequest {
@@ -1144,6 +1163,26 @@ function driveChild(input: DriveInput): Promise<AttachedTurnResult> {
       return settleFailure('adapter_internal_error', { detail: 'wire_failed' })
     }
 
+    // --- the passive tee, wired LAST and in its own try ------------------------
+    // Its own try/catch, outside the block above, is the point: a stdout that refuses
+    // a second listener must cost the OBSERVER, not the turn. Inside that block the
+    // same throw would hit `wire_failed` and refuse a delivery for the sake of a view.
+    try {
+      const observe = deps.observeStdout
+      if (typeof observe === 'function' && child.stdout) {
+        child.stdout.on('data', (chunk: any) => {
+          try {
+            observe(typeof chunk === 'string' ? chunk : String(chunk))
+          } catch {
+            // Never rethrown. A throw here propagates out of `emit()` and would stop
+            // every later listener on this stream.
+          }
+        })
+      }
+    } catch {
+      /* the turn proceeds unobserved, which is the correct direction */
+    }
+
     // --- bounded budget ------------------------------------------------------
     deadline = setTimeout(() => {
       timedOut = true

package/server/lib/session-stream-bus.ts

@@ -0,0 +1,150 @@
+// Per-session pub/sub for the live session stream.
+//
+// WHY THIS IS NOT `display-bus.ts`, given the instruction to reuse the SSE machinery.
+// The SSE machinery being reused is the TRANSPORT: `text/event-stream`, the header
+// block, `retry:`, the close-on-`req.close` teardown. That pattern is copied from
+// `routes/display.ts` verbatim and no second transport is introduced.
+//
+// The display BUS is a different object with two properties that are wrong here, and
+// both would be regressions rather than style disagreements:
+//
+//   1. It is a GLOBAL BROADCAST. Every `/display-stream` subscriber, which is to say
+//      every connected pair of glasses, receives every event published to it. Session
+//      events belong to one session detail view; broadcasting them would put another
+//      thread's tool trail on the lens, and the plan is explicit that the stream must
+//      never write the lens directly.
+//   2. It has a 200-EVENT SHARED REPLAY BUFFER. A tool-heavy turn emits hundreds of
+//      events in seconds. Pushing those through `emitDisplay` would evict the real
+//      display events a reconnecting client replays from, and that client would then
+//      be told `buffer_overflow` — a silent loss of query results caused entirely by
+//      a feature that only wanted to show a file being read.
+//
+// So: same transport, own keyspace. This module is deliberately small.
+//
+// NO REPLAY BUFFER HERE EITHER, and that is a decision rather than an omission. A
+// reconnecting client resumes LIVE and its 5s/15s/60s poll is what fills the gap it
+// missed; the contract gives it `seq` precisely so it can SEE the gap. Retaining a
+// per-session ring would add memory that grows with the number of sessions ever
+// opened, to duplicate a fallback that already exists and already works.
+
+import type { SessionStreamDraft } from './session-stream-events.js'
+
+/** A draft with the publish instant stamped. `seq` stays per connection. */
+export type PublishedSessionEvent = SessionStreamDraft & { at: number }
+
+export type SessionStreamListener = (event: PublishedSessionEvent) => void
+
+/**
+ * Concurrent subscribers to ONE session.
+ *
+ * Small on purpose. The realistic count is one pair of glasses plus, briefly, a
+ * reconnecting duplicate of it. A ceiling means a client stuck in a reconnect loop
+ * costs a bounded number of file watchers rather than an unbounded one.
+ */
+export const MAX_SUBSCRIBERS_PER_SESSION = 8
+
+/** Sessions streamed at once. Each carries at most one poller. */
+export const MAX_STREAMED_SESSIONS = 16
+
+const listeners = new Map<string, Set<SessionStreamListener>>()
+
+/**
+ * Sessions with a COS-spawned turn writing to them right now.
+ *
+ * A counter, not a boolean: it is set and cleared by the turn's own lifecycle and a
+ * counter cannot be left stuck true by an unbalanced pair the way a boolean can, since
+ * an extra clear floors at zero instead of silently disabling the gate.
+ */
+const attachedTurns = new Map<string, number>()
+
+export function sessionStreamKey(provider: string, sessionId: string): string {
+  return `${String(provider).trim().toLowerCase()}:${String(sessionId).trim().toLowerCase()}`
+}
+
+export function subscriberCount(key: string): number {
+  return listeners.get(key)?.size ?? 0
+}
+
+export function streamedSessionCount(): number {
+  return listeners.size
+}
+
+/** Null when a ceiling is reached; the caller answers 503 and the client polls. */
+export function subscribeSessionStream(key: string, listener: SessionStreamListener): (() => void) | null {
+  const existing = listeners.get(key)
+  if (existing && existing.size >= MAX_SUBSCRIBERS_PER_SESSION) return null
+  if (!existing && listeners.size >= MAX_STREAMED_SESSIONS) return null
+
+  const set = existing ?? new Set<SessionStreamListener>()
+  set.add(listener)
+  listeners.set(key, set)
+
+  let released = false
+  return () => {
+    // Idempotent. A double release from a close handler that fires twice must not
+    // delete a key another subscriber still holds.
+    if (released) return
+    released = true
+    const current = listeners.get(key)
+    if (!current) return
+    current.delete(listener)
+    if (current.size === 0) listeners.delete(key)
+  }
+}
+
+/**
+ * Fan out one draft.
+ *
+ * A throwing listener is isolated: one dead socket must not stop the others from being
+ * written, and must not propagate back into the provider stdout handler that called
+ * this. Iterating a COPY additionally means a listener that unsubscribes itself while
+ * being notified cannot corrupt the iteration.
+ */
+export function publishSessionStream(key: string, draft: SessionStreamDraft, at: number = Date.now()): number {
+  const set = listeners.get(key)
+  if (!set || set.size === 0) return 0
+  const event: PublishedSessionEvent = { ...draft, at }
+  let delivered = 0
+  for (const listener of [...set]) {
+    try {
+      listener(event)
+      delivered++
+    } catch {
+      /* a broken subscriber costs itself, never the publisher or its peers */
+    }
+  }
+  return delivered
+}
+
+/**
+ * Mark a COS-spawned turn as the live writer for this session.
+ *
+ * THE DUPLICATE-SUPPRESSION GATE. A Continue turn appears TWICE: once as the stdout
+ * this server tees in Phase 1, and again as the transcript records the provider writes
+ * to the very file Phase 2 is tailing. Without a gate the reader sees every tool call
+ * and every reply twice.
+ *
+ * stdout wins while it exists, because it is live rather than post-hoc. The watcher
+ * keeps advancing its offset through the suppressed region, so when the turn ends the
+ * cursor is already past those records and nothing is replayed.
+ */
+export function beginAttachedTurn(key: string): () => void {
+  attachedTurns.set(key, (attachedTurns.get(key) ?? 0) + 1)
+  let ended = false
+  return () => {
+    if (ended) return
+    ended = true
+    const next = (attachedTurns.get(key) ?? 0) - 1
+    if (next > 0) attachedTurns.set(key, next)
+    else attachedTurns.delete(key)
+  }
+}
+
+export function isAttachedTurnActive(key: string): boolean {
+  return (attachedTurns.get(key) ?? 0) > 0
+}
+
+export function __resetSessionStreamBusForTests(): void {
+  listeners.clear()
+  attachedTurns.clear()
+}