@gotcos/glasses-server 6.49.1 → 6.50.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 6.50.0
+
+Scroll back through a running session's conversation on the glasses.
+
+- **The recent conversation, served.** Miles, 2026-09-16: "if I come into a session that's been running, I can scroll up and see what was happening, what was the original prompt." COS Control already shows it (its helper parses the transcript on the Mac: last 120 turns, tools omitted); the lens cannot read the Mac's files and had only the live stream, which starts at the current turn. The detail route now answers `?turns=N` (1 to 40) with `recent_turns: [{ role, text, at? }]` and `recent_turns_more`, oldest first: who said what, tool calls, tool results, sub-agents and injected rows left out, a live Continue from the glasses shown as the user's own words, the text shaped exactly as `latest_reply` is. Without the parameter the payload is byte-for-byte what it was, so the detail poll and every older client are untouched; a failure reading the history costs the history, never the page.
+- **Read backward from the end, not from the digest's windows.** The digest reads an oversized transcript as a 256 KiB head plus a 768 KiB tail; on the 42 MB session this was built in, that tail held two prompts, because tool output dominates the bytes (twenty transcripts on this Mac are over 32 MB). The history reads 2, then 8, then at most 24 MiB from the end until it has the messages asked for. Measured on that session: 40 messages, nine prompts back, 8 MB read, 40 ms. A window is read from one byte before its start, so a record that begins exactly at the window's edge is kept (the first cut dropped it; its own test found that).
+- Tests: every row shape for Claude (text, tool call, tool result, sub-agent, thinking, slash-command body, compaction, peer Continue, wrappers, fences, the 4,000 cap), Codex (messages vs developer, calls and events) and Cursor (`<user_query>`); the growing windows, the ceiling, the torn first record, the boundary record; the route (absent unless asked, same fields when asked, oldest first, `more`, a malformed ask ignored). Mutation gate: six new cases.
+
 ## 6.49.1
 
 Where a turn's time goes, and the two things the /qa pass on 6.49.0 found that made a follow-up wait or repeat.

package/README.md

@@ -224,6 +224,11 @@ waiting out the lease; a binding with a turn in flight still refuses `native_tar
 The turn ledger is read across every binding of a thread, so a draft re-sent through a
 new binding (the phone attaches per send; a parked draft drains through the drainer's
 own) replays rather than repeats.
+`GET /api/agent-sessions/:provider/:id?turns=N` (6.50.0, N from 1 to 40) adds
+`recent_turns` (oldest first, `{ role: 'user' | 'assistant', text, at? }`, tools and
+sub-agents omitted) and `recent_turns_more` to the detail payload, read backward from
+the end of the transcript; without `turns` the payload is unchanged. The glasses use it
+to scroll back through a running session's conversation.
 
 ## Configuration
 

package/package.json

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

package/server/lib/agent-session-turns.ts

@@ -0,0 +1,178 @@
+// The recent conversation of a session, as the messages a person reads: who spoke and
+// what they said, tool calls and sub-agents left out (6.50.0).
+//
+// WHY THIS EXISTS. Miles, 2026-09-16, on the G2: "if I come into a session that's been
+// running, I can scroll up and see what was happening, what was the original prompt
+// that led off to all of this activity." COS Control already shows exactly that ("last
+// 120 of 338 turns · tools omitted"), but its helper reads the transcript file on the
+// Mac itself. The lens cannot read the Mac's files; it gets the live stream (the current
+// turn only) and the 2,000-character digest. This is the same history, served.
+//
+// WHY A READER OF ITS OWN, NOT THE DIGEST'S WINDOWS. `parseAgentSession` reads an
+// oversized transcript as a 256 KiB head plus a 768 KiB tail, which is right for a
+// digest and wrong for history: measured on the 42 MB session this was written in, the
+// 768 KiB tail held TWO prompts (3 user rows, 6 assistant text rows), because tool
+// results dominate the bytes. Twenty transcripts on this Mac are over 32 MB. So this
+// reads backward from the end in growing windows until it has the messages it was asked
+// for, or has covered the file, or reaches its cap.
+//
+// THE RULES MATCH THE DIGEST'S, from the same helpers: a sidechain (sub-agent) row is
+// not the conversation; a tool result is not a message; an injected row (`isMeta`, a
+// compaction summary) is not something anyone said, EXCEPT a peer-inbox row, which is a
+// live Continue the user dictated (6.49.1) and is unwrapped to their words; wrapper
+// prompts are dropped; the text is shaped by `latestAssistantReply`, the function the
+// lens already renders replies through (lines kept, fences and harness tags out, 4,000
+// characters with a visible ellipsis).
+
+import { open, stat } from 'node:fs/promises'
+import {
+  latestAssistantReply,
+  isWrapperPrompt,
+  parseJsonLine,
+  payloadText,
+  type AgentProvider,
+} from './agent-session-store.js'
+import { unwrapPeerMessage } from './session-stream-events.js'
+
+export interface SessionTurn {
+  role: 'user' | 'assistant'
+  text: string
+  /** The record's ISO timestamp, when the provider writes one (Cursor does not). */
+  at?: string
+}
+
+/** What a client may ask for in one read. Forty messages is ~10 lens pages of words. */
+export const SESSION_TURNS_MAX = 40
+
+/**
+ * The windows read backward from the end of the transcript, smallest first.
+ *
+ * MEASURED on the 42 MB session this was written in: 768 KiB held 2 prompts, 1.75 MiB
+ * held 11, 4 MiB held 17 (20 user rows, 56 assistant text rows). So 2 MiB covers an
+ * ordinary request for 20 messages in one read, and the larger windows exist for a
+ * turn whose tool output is unusually heavy. 24 MiB is the ceiling: past it the answer
+ * is what was found, marked as more-before, never a whole-file parse on a request path.
+ */
+export const SESSION_TURNS_WINDOWS: readonly number[] = [2 * 1024 * 1024, 8 * 1024 * 1024, 24 * 1024 * 1024]
+
+function iso(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 && !Number.isNaN(Date.parse(value)) ? value : undefined
+}
+
+/** A Cursor user row wraps the ask in `<user_query>`; the rest is scaffolding. */
+function cursorQuery(text: string): string {
+  const start = text.indexOf('<user_query>')
+  const end = text.indexOf('</user_query>')
+  return start >= 0 && end > start ? text.slice(start + '<user_query>'.length, end) : text
+}
+
+function shaped(role: SessionTurn['role'], raw: string, at: string | undefined): SessionTurn | null {
+  if (isWrapperPrompt(raw)) return null
+  const text = latestAssistantReply(raw)
+  if (!text) return null
+  return at ? { role, text, at } : { role, text }
+}
+
+/**
+ * One transcript record as a message a person reads, or null.
+ *
+ * Pure. The per-provider shapes are the ones `parseAgentSession` reads.
+ */
+export function sessionTurnFromRecord(provider: AgentProvider, obj: Record<string, unknown>): SessionTurn | null {
+  if (provider === 'claude') {
+    if (obj.isSidechain === true) return null
+    if (obj.type !== 'user' && obj.type !== 'assistant') return null
+    if (obj.type === 'user' && obj.toolUseResult) return null
+    const message = obj.message && typeof obj.message === 'object' ? obj.message as Record<string, unknown> : null
+    const text = message ? payloadText(message) : null
+    if (!text) return null
+    const at = iso(obj.timestamp)
+    if (obj.type === 'assistant') return shaped('assistant', text, at)
+    const peer = (obj.origin as { kind?: unknown } | undefined)?.kind === 'peer' ? unwrapPeerMessage(text) : null
+    if (peer !== null) return shaped('user', peer, at)
+    if (obj.isMeta === true || obj.isCompactSummary === true) return null
+    return shaped('user', text, at)
+  }
+  if (provider === 'codex') {
+    if (obj.type !== 'response_item' || !obj.payload || typeof obj.payload !== 'object') return null
+    const payload = obj.payload as Record<string, unknown>
+    if (String(payload.type ?? '') !== 'message') return null
+    if (payload.role !== 'user' && payload.role !== 'assistant') return null
+    const text = payloadText(payload)
+    if (!text) return null
+    return shaped(payload.role, text, iso(obj.timestamp))
+  }
+  if (obj.role !== 'user' && obj.role !== 'assistant') return null
+  const message = obj.message && typeof obj.message === 'object' ? obj.message as Record<string, unknown> : null
+  const text = message ? payloadText(message) : null
+  if (!text) return null
+  return shaped(obj.role, obj.role === 'user' ? cursorQuery(text) : text, iso(obj.timestamp))
+}
+
+/** The newest `limit` messages among these lines (file order in, file order out). */
+export function recentSessionTurns(provider: AgentProvider, lines: readonly string[], limit: number): SessionTurn[] {
+  const out: SessionTurn[] = []
+  for (const line of lines) {
+    const obj = parseJsonLine(line)
+    if (!obj) continue
+    const turn = sessionTurnFromRecord(provider, obj)
+    if (turn) out.push(turn)
+  }
+  return limit > 0 ? out.slice(-limit) : []
+}
+
+export interface RecentTurnsRead {
+  turns: SessionTurn[]
+  /** True when the transcript holds messages before the first one returned. */
+  more: boolean
+  /** Bytes of the transcript this read covered, for the log. */
+  bytesRead: number
+}
+
+/**
+ * The newest `limit` messages of a transcript, read backward in growing windows.
+ * Never parses more than the last window's bytes.
+ */
+export async function readRecentSessionTurns(
+  provider: AgentProvider,
+  path: string,
+  limit: number,
+  windows: readonly number[] = SESSION_TURNS_WINDOWS,
+): Promise<RecentTurnsRead> {
+  const want = Math.max(0, Math.min(SESSION_TURNS_MAX, Math.floor(limit)))
+  const { size } = await stat(path)
+  if (want === 0 || size === 0) return { turns: [], more: false, bytesRead: 0 }
+  const handle = await open(path, 'r')
+  try {
+    let found: SessionTurn[] = []
+    let start = size
+    for (const window of windows) {
+      start = Math.max(0, size - window)
+      // One byte BEFORE the window as well, so the first line is known to be whole or
+      // not: after a newline it splits off as '' and the record starting AT the window
+      // is kept; otherwise it is the tail of a record that began earlier and is
+      // dropped. Dropping the first line unconditionally lost a whole record whenever a
+      // window began exactly on a line start (found by its own test).
+      const from = start > 0 ? start - 1 : 0
+      const length = size - from
+      const buffer = Buffer.alloc(length)
+      await handle.read(buffer, 0, length, from)
+      const lines = buffer.toString('utf-8').split('\n')
+      if (start > 0) lines.shift()
+      // One more than wanted, so `more` can be answered from what was read.
+      found = recentSessionTurns(provider, lines, want + 1)
+      if (found.length > want || start === 0) break
+    }
+    const more = found.length > want || start > 0
+    return { turns: found.slice(-want), more, bytesRead: size - start }
+  } finally {
+    await handle.close()
+  }
+}
+
+/** `?turns=N`: an integer 1..SESSION_TURNS_MAX, or null (absent or malformed). */
+export function parseTurnsParam(value: unknown): number | null {
+  if (typeof value !== 'string' || !/^\d{1,3}$/.test(value)) return null
+  const n = Number(value)
+  return n >= 1 && n <= SESSION_TURNS_MAX ? n : null
+}

package/server/routes/agent-sessions.ts

@@ -61,6 +61,7 @@ import {
   type LockHolderSnapshot,
 } from '../lib/occupancy-probes.js'
 import type { OccupancyDirs } from '../lib/thread-occupancy.js'
+import { parseTurnsParam, readRecentSessionTurns } from '../lib/agent-session-turns.js'
 import { cosSpawnedPids } from '../lib/agent-session-ownership-store.js'
 
 export const agentSessionsRouter = Router()
@@ -474,6 +475,18 @@ agentSessionsRouter.get('/agent-sessions/:provider/:sessionId', async (req, res)
     // READ. Presenting a partial count as the session total would be the same
     // dishonesty as a silent cap, so the digest omits the number entirely instead.
     const parsed = await parseAgentSession(provider, found)
+    // 6.50.0 `?turns=N`: the recent conversation, for the lens's scroll-up history. Only
+    // when asked, so the detail poll and every older client get the same bytes as before.
+    // A failure here costs the history, never the detail page.
+    const turnsWanted = parseTurnsParam(req.query.turns)
+    let recentTurns: Awaited<ReturnType<typeof readRecentSessionTurns>> | null = null
+    if (turnsWanted !== null) {
+      try {
+        recentTurns = await readRecentSessionTurns(provider, found, turnsWanted)
+      } catch (error) {
+        console.warn(`[agent-sessions] recent turns failed provider=${provider}: ${error instanceof Error ? error.message : error}`)
+      }
+    }
     if (provider === 'cursor') {
       const names = await loadCursorComposerNames(agentSessionRoots().cursorComposerDb)
       const named = names.get(parsed.session_id) || names.get(sessionId)
@@ -545,6 +558,7 @@ agentSessionsRouter.get('/agent-sessions/:provider/:sessionId', async (req, res)
       omitted_tools: parsed.omitted_tools,
       ...(activity.lastActivityAt ? { last_activity_at: activity.lastActivityAt } : {}),
       ...(activity.lastTool ? { last_tool: activity.lastTool } : {}),
+      ...(recentTurns ? { recent_turns: recentTurns.turns, recent_turns_more: recentTurns.more } : {}),
     })
   } catch (error) {
     console.error(`[agent-sessions] detail failed: ${error instanceof Error ? error.message : error}`)