@gotcos/glasses-server 6.99.33 → 7.0.18

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

@@ -0,0 +1,321 @@
+/**
+ * "Recent activity first" for the Today summary (Miles, 2026-11-09): what was said INTO a session lately and where its
+ * latest reply left off, with when, so the summary describes what a session is doing now instead of its first prompt.
+ *
+ * Why: each session's list `line` (composeDiscussionSummary) is its FIRST prompt plus the latest reply, cut at 180
+ * characters. On 11/09 the Codex orchestrator's line led with an ask from 10/11, 29 days old, and the model wrote
+ * "following up a transcription bakeoff" about a session that had just confirmed a release was live.
+ *
+ * readRecentActivity(provider, file, now) answers the last few asks (each with when and how it arrived), the latest
+ * reply and when the session last moved. Read-only display evidence: never imported by an attach, queue or write gate.
+ *
+ * - Claude: the last 8 MB of the transcript, memoized on mtime and size like readClaudeSubagents. User turns follow
+ *   parseAgentSession's rules: sidechains, `isMeta` and `isCompactSummary` rows are not asks (a peer row is, unwrapped
+ *   by unwrapPeerMessage), the verify footer comes off (withoutTurnFooter), wrapper tags go (STRIPPABLE_TAG_RE) and a
+ *   pasted JSON block becomes "[pasted data]". A peer row, or a row that carried a COS verify footer, arrived from
+ *   another screen or session: `via: 'peer'`, never attributed to the person. A peer row that is agent-to-agent
+ *   protocol (a cross-session or agent-message envelope) is not an ask at all.
+ * - Codex: rollouts reach 32 GB with single lines of 44 MB (measured 11/09). An incremental forward scan keeps its byte
+ *   offset in memory; the first pass reads at most the last 256 MB; a line over 1 MB is skipped without being decoded
+ *   or parsed; reads are async, 4 MB at a time, and the scan yields between chunks. One scan per file at a time: a
+ *   second caller waits on the first, and a scan the Today route stopped waiting for still finishes and fills the memo.
+ *   Codex rows carry no sender marker, so only a COS verify footer marks one as sent in from another screen.
+ * - Cursor: the existing tail peek (the last user query and reply); its transcript has no timestamps, so every time is
+ *   the file's mtime.
+ *
+ * `startedAt` and `firstAsk` are set only for a session whose file was created within the last day, for the
+ * "started today as" note. Opens refuse symlinks and non-regular files. Never throws: null when unreadable.
+ */
+import { constants } from 'node:fs'
+import { open, stat } from 'node:fs/promises'
+import {
+  STRIPPABLE_TAG_RE, createdFromCodexFilename, firstClaudeUserTitle, firstCursorUserTitle, isWrapperPrompt, parseJsonLine,
+  payloadText, codexUserText, peekCodexMeta, peekCursorDiscussion, proseSnippet, type AgentProvider,
+} from './agent-session-store.js'
+import { unwrapPeerMessage } from './session-stream-events.js'
+import { stripG2TurnFooter } from './turn-footer.js'
+
+export type RecentVia = 'typed' | 'peer'
+export interface RecentAsk { at: number; text: string; via: RecentVia }
+export interface RecentReply { at: number; text: string }
+export interface RecentActivity {
+  /** The newest asks into the session, oldest first, at most RECENT_ASKS_KEPT. */
+  asks: RecentAsk[]
+  /** The newest assistant reply (Codex: its newest final answer, not commentary). */
+  reply: RecentReply | null
+  /** The newest record's time (ms), 0 when none was seen. */
+  movedAt: number
+  /** Only for a session created within the last day: when, and its first ask. */
+  startedAt?: number
+  firstAsk?: string
+}
+
+export const RECENT_ASKS_KEPT = 3
+export const CLAUDE_RECENT_TAIL_BYTES = 8 * 1024 * 1024
+export const CODEX_FIRST_PASS_BYTES = 256 * 1024 * 1024
+/** A line longer than this is skipped unparsed (a 44 MB Codex line holds tool output, never an ask). */
+export const RECENT_LINE_MAX_BYTES = 1024 * 1024
+export const RECENT_CHUNK_BYTES = 4 * 1024 * 1024
+const TEXT_KEEP = 1000
+const MEMO_MAX = 64
+const DAY_MS = 24 * 60 * 60 * 1000
+
+// ── text ───────────────────────────────────────────────────────────────────
+
+const PASTED = /<pasted_content\b[^>]*>([\s\S]*?)<\/pasted_content\b[^>]*>/gi
+const WRAPPER_BLOCKS = /<(task-notification|system-reminder|relevant-memories|cache-health|daily-bulletin|cos-alarms|device-handoff|now|memory-stored|local-command-stdout|local-command-stderr|command-name|command-message|command-args|user_query)\b[^>]*>[\s\S]*?<\/\1>/gi
+/** A peer row that is agent-to-agent protocol, not words for the session. */
+const AGENT_ENVELOPE = /^\s*(?:<(?:cross-session-message|agent-message)\b|Message Type:|Subagent hand-?back\b)/i
+/** A paragraph that is pasted data: it opens with { or [ and holds a "key": pair. */
+const JSON_PARAGRAPH = /^\s*[[{][\s\S]*"\s*:/
+
+/** One ask's words: pasted data replaced, wrapper blocks and tags out, one line, bounded. '' when nothing is left. */
+export function cleanAskText(raw: string): string {
+  // Whole wrapper blocks go first (a background task's notification, a reminder, a slash command's parts). What is left
+  // is then judged as parseAgentSession's collectTurn judges a turn: still a wrapper (it opens with a tag the block list
+  // does not know), it is not an ask, and no tag is taken off so that its insides could read as words.
+  let s = raw.replace(WRAPPER_BLOCKS, ' ').replace(PASTED, (_m, inner: string) => {
+    const t = String(inner).trim()
+    return t.startsWith('{') || t.startsWith('[') ? '\n\n[pasted data]\n\n' : ` ${t} `
+  })
+  if (!s.trim() || isWrapperPrompt(s)) return ''
+  s = s.split(/\n\s*\n/).map(p => (JSON_PARAGRAPH.test(p) ? '[pasted data]' : p)).join('\n\n')
+  s = s.replace(STRIPPABLE_TAG_RE, ' ').replace(/\s+/g, ' ').trim()
+  if (!s || isWrapperPrompt(s) || s.startsWith('[Request interrupted') || s.startsWith('[image: source')) return ''
+  return s.slice(0, TEXT_KEEP)
+}
+
+/** An ask's words and how it arrived: a footer means another screen (glasses, phone or web) sent it. */
+function footerVia(text: string, peer: boolean): { text: string; via: RecentVia } {
+  const f = stripG2TurnFooter(text)
+  return { text: f.text, via: peer || f.turnId ? 'peer' : 'typed' }
+}
+
+const tsOf = (v: unknown): number => (typeof v === 'string' ? Date.parse(v) || 0 : 0)
+
+interface Collector { asks: RecentAsk[]; reply: RecentReply | null; movedAt: number }
+const emptyCollector = (): Collector => ({ asks: [], reply: null, movedAt: 0 })
+function addAsk(c: Collector, ask: RecentAsk) {
+  c.asks.push(ask)
+  if (c.asks.length > RECENT_ASKS_KEPT) c.asks.shift()
+}
+const moved = (c: Collector, at: number) => { if (at > c.movedAt) c.movedAt = at }
+
+/** One Claude record into the collector (parseAgentSession's user-turn rules). */
+export function collectClaudeRecord(c: Collector, obj: Record<string, unknown>): void {
+  if (obj.isSidechain === true) return
+  const at = tsOf(obj.timestamp)
+  if (at && (obj.type === 'user' || obj.type === 'assistant' || obj.type === 'system')) moved(c, at)
+  if (obj.type !== 'user' && obj.type !== 'assistant') return
+  if (obj.type === 'user' && obj.toolUseResult) return
+  const message = obj.message && typeof obj.message === 'object' ? obj.message as Record<string, unknown> : null
+  const text = message ? payloadText(message) : null
+  if (!text) return
+  if (obj.type === 'assistant') {
+    const prose = proseSnippet(text, TEXT_KEEP)
+    if (prose) c.reply = { at, text: prose }
+    return
+  }
+  const isPeer = (obj.origin as { kind?: unknown } | undefined)?.kind === 'peer'
+  const peerWords = isPeer ? unwrapPeerMessage(text) : null
+  // Injected rows (a slash-command body, a compaction preamble) are not asks; a peer row is, once unwrapped.
+  if (peerWords === null && (obj.isMeta === true || obj.isCompactSummary === true)) return
+  if (peerWords !== null && AGENT_ENVELOPE.test(peerWords)) return
+  const { text: words, via } = footerVia(peerWords ?? text, peerWords !== null)
+  const clean = cleanAskText(words)
+  if (clean) addAsk(c, { at, text: clean, via })
+}
+
+/** One Codex rollout line into the collector. The caller has already checked its size. */
+export function collectCodexLine(c: Collector, line: Buffer): void {
+  const head = line.subarray(0, 512).toString('utf8')
+  const stamp = /"timestamp":"([^"]{10,40})"/.exec(head)
+  const at = stamp ? Date.parse(stamp[1]!) || 0 : 0
+  if (at) moved(c, at)
+  // Role and type sit before the content in a rollout line, so the head decides without decoding the rest.
+  if (!head.includes('"type":"message"') || !(head.includes('"role":"user"') || head.includes('"role":"assistant"'))) return
+  const obj = parseJsonLine(line.toString('utf8'))
+  if (!obj || obj.type !== 'response_item' || !obj.payload || typeof obj.payload !== 'object') return
+  const p = obj.payload as Record<string, unknown>
+  if (p.type !== 'message') return
+  if (p.role === 'assistant') {
+    if (p.phase === 'commentary') return
+    const text = payloadText(p)
+    const prose = text ? proseSnippet(text, TEXT_KEEP) : ''
+    if (prose) c.reply = { at, text: prose }
+    return
+  }
+  if (p.role !== 'user') return
+  const text = codexUserText(p)
+  if (!text || isWrapperPrompt(text)) return
+  const { text: words, via } = footerVia(text, false)
+  const clean = cleanAskText(words)
+  if (clean) addAsk(c, { at, text: clean, via })
+}
+
+// ── reads ──────────────────────────────────────────────────────────────────
+
+type Handle = Awaited<ReturnType<typeof open>>
+async function openRegular(file: string): Promise<{ handle: Handle; size: number; mtimeMs: number; birthtimeMs: number; ino: number } | null> {
+  let handle: Handle | null = null
+  try {
+    handle = await open(file, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0) | (constants.O_NOFOLLOW ?? 0))
+    const st = await handle.stat()
+    if (!st.isFile()) { await handle.close().catch(() => {}); return null }
+    return { handle, size: st.size, mtimeMs: st.mtimeMs, birthtimeMs: st.birthtimeMs, ino: st.ino }
+  } catch {
+    await handle?.close().catch(() => {})
+    return null
+  }
+}
+const yieldLoop = () => new Promise<void>(resolve => setImmediate(resolve))
+
+const claudeMemo = new Map<string, { mtimeMs: number; size: number; value: Collector }>()
+const remember = <V>(memo: Map<string, V>, key: string, value: V) => {
+  if (!memo.has(key) && memo.size >= MEMO_MAX) memo.delete(memo.keys().next().value!)
+  memo.set(key, value)
+}
+
+/** A Claude transcript's tail (8 MB), memoized on mtime and size. */
+async function readClaude(file: string, tailBytes = CLAUDE_RECENT_TAIL_BYTES): Promise<{ c: Collector; birthtimeMs: number } | null> {
+  const opened = await openRegular(file)
+  if (!opened) return null
+  const { handle, size, mtimeMs, birthtimeMs } = opened
+  try {
+    const hit = claudeMemo.get(file)
+    if (hit && hit.mtimeMs === mtimeMs && hit.size === size) return { c: hit.value, birthtimeMs }
+    const length = Math.min(size, tailBytes), start = size - length
+    const buffer = Buffer.alloc(length)
+    const read = await handle.read(buffer, 0, length, start)
+    const data = buffer.subarray(0, read.bytesRead)
+    const c = emptyCollector()
+    let pos = 0, n = 0
+    // A tail that starts mid-file has a cut first line: it fails to parse and is skipped like any bad line.
+    while (pos < data.length) {
+      let end = data.indexOf(0x0a, pos)
+      if (end < 0) end = data.length
+      if (end - pos > 0 && end - pos <= RECENT_LINE_MAX_BYTES) {
+        const obj = parseJsonLine(data.subarray(pos, end).toString('utf8'))
+        if (obj) collectClaudeRecord(c, obj)
+      }
+      pos = end + 1
+      if (++n % 2000 === 0) await yieldLoop()
+    }
+    remember(claudeMemo, file, { mtimeMs, size, value: c })
+    return { c, birthtimeMs }
+  } catch {
+    return null
+  } finally {
+    await handle.close().catch(() => {})
+  }
+}
+
+interface CodexScan { offset: number; size: number; partial: Buffer | null; skipping: boolean; c: Collector; running: Promise<void> | null; ino: number }
+const codexMemo = new Map<string, CodexScan>()
+
+/** Test seam: forget every memo (a new server process starts with none). */
+export function resetRecentActivityMemo(): void { claudeMemo.clear(); codexMemo.clear() }
+/** Test seam: the bytes of an unfinished line a Codex scan holds for its next read (never more than the line bound). */
+export function codexScanHeldBytes(file: string): number { return codexMemo.get(file)?.partial?.length ?? 0 }
+
+/**
+ * Scan a Codex rollout forward from where the last scan stopped. A first pass, or a gap past `firstPassBytes`, starts
+ * that far from the end and drops the line it lands inside.
+ */
+async function scanCodex(file: string, firstPassBytes: number, chunkBytes: number): Promise<CodexScan | null> {
+  const opened = await openRegular(file)
+  if (!opened) return null
+  const { handle, size, ino } = opened
+  try {
+    let scan = codexMemo.get(file)
+    if (scan && (scan.ino !== ino || size < scan.offset)) scan = undefined   // replaced or truncated: start over
+    if (!scan) {
+      scan = { offset: 0, size: 0, partial: null, skipping: false, c: emptyCollector(), running: null, ino }
+      remember(codexMemo, file, scan)
+    }
+    if (scan.running) { await scan.running; return scan }
+    const s = scan
+    const run = (async () => {
+      if (size - s.offset > firstPassBytes) {
+        s.offset = size - firstPassBytes
+        s.partial = null
+        s.skipping = s.offset > 0   // landed mid-line: that line is not whole
+      }
+      while (s.offset < size) {
+        const length = Math.min(chunkBytes, size - s.offset)
+        const chunk = Buffer.alloc(length)
+        const { bytesRead } = await handle.read(chunk, 0, length, s.offset)
+        if (bytesRead <= 0) break
+        s.offset += bytesRead
+        let buf = chunk.subarray(0, bytesRead)
+        if (s.partial) { buf = Buffer.concat([s.partial, buf]); s.partial = null }
+        let pos = 0
+        for (let nl = buf.indexOf(0x0a, pos); nl >= 0; nl = buf.indexOf(0x0a, pos)) {
+          if (s.skipping) s.skipping = false
+          else if (nl - pos > 0 && nl - pos <= RECENT_LINE_MAX_BYTES) collectCodexLine(s.c, buf.subarray(pos, nl))
+          pos = nl + 1
+        }
+        const rest = buf.subarray(pos)
+        // An unfinished line past the bound is never kept: the rest of it is skipped up to its newline. While skipping
+        // (no newline in this chunk at all), nothing is kept either.
+        if (!s.skipping) {
+          if (rest.length > RECENT_LINE_MAX_BYTES) s.skipping = true
+          else if (rest.length) s.partial = Buffer.from(rest)
+        }
+        await yieldLoop()
+      }
+      s.size = size
+    })()
+    s.running = run
+    try { await run } finally { s.running = null }
+    return s
+  } catch {
+    return null
+  } finally {
+    await handle.close().catch(() => {})
+  }
+}
+
+export interface RecentReadOptions { claudeTailBytes?: number; codexFirstPassBytes?: number; chunkBytes?: number }
+
+/** What was said into one session lately, its latest reply and when it last moved, or null when it cannot be read. */
+export async function readRecentActivity(provider: AgentProvider, file: string, now = Date.now(), opts: RecentReadOptions = {}): Promise<RecentActivity | null> {
+  try {
+    let c: Collector, createdAt = 0, firstAsk = ''
+    if (provider === 'claude') {
+      const r = await readClaude(file, opts.claudeTailBytes)
+      if (!r) return null
+      c = r.c
+      createdAt = r.birthtimeMs
+      if (createdAt && now - createdAt < DAY_MS) firstAsk = (await firstClaudeUserTitle(file)) ?? ''
+    } else if (provider === 'codex') {
+      const s = await scanCodex(file, opts.codexFirstPassBytes ?? CODEX_FIRST_PASS_BYTES, opts.chunkBytes ?? RECENT_CHUNK_BYTES)
+      if (!s) return null
+      c = s.c
+      createdAt = Date.parse(createdFromCodexFilename(file.split('/').pop() ?? '') ?? '') || 0
+      if (createdAt && now - createdAt < DAY_MS) firstAsk = (await peekCodexMeta(file))?.title ?? ''
+    } else {
+      const st = await stat(file).catch(() => null)
+      if (!st?.isFile()) return null
+      const peek = await peekCursorDiscussion(file)
+      const at = st.mtimeMs
+      c = { asks: [], reply: null, movedAt: at }
+      const ask = peek.lastUser ? cleanAskText(peek.lastUser) : ''
+      if (ask) c.asks.push({ at, text: ask, via: 'typed' })
+      const reply = peek.latestAssistant ? proseSnippet(peek.latestAssistant, TEXT_KEEP) : ''
+      if (reply) c.reply = { at, text: reply }
+      createdAt = st.birthtimeMs
+      if (createdAt && now - createdAt < DAY_MS) firstAsk = (await firstCursorUserTitle(file)) ?? ''
+    }
+    // Copies, so a caller can never edit the memo.
+    const out: RecentActivity = {
+      asks: c.asks.filter(a => a.at <= now).map(a => ({ ...a })),
+      reply: c.reply && c.reply.at <= now ? { ...c.reply } : null,
+      movedAt: c.movedAt,
+    }
+    if (firstAsk && createdAt) { out.startedAt = createdAt; out.firstAsk = firstAsk }
+    return out
+  } catch {
+    return null
+  }
+}

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

@@ -250,7 +250,7 @@ const STRIPPABLE_TAGS = [
   'local-command-stdout', 'local-command-stderr', 'thinking',
 ]
 
-const STRIPPABLE_TAG_RE = new RegExp(`</?(?:${STRIPPABLE_TAGS.join('|')})(?:\\s[^>]*)?/?>`, 'gi')
+export const STRIPPABLE_TAG_RE = new RegExp(`</?(?:${STRIPPABLE_TAGS.join('|')})(?:\\s[^>]*)?/?>`, 'gi')
 
 /**
  * Fenced code and known tags out. Shared so `proseSnippet` and `latestAssistantReply`
@@ -995,7 +995,7 @@ export async function peekCodexMeta(path: string): Promise<{ id: string; cwd: st
   return { id, cwd, title, subagent, created }
 }
 
-async function peekCursorDiscussion(path: string): Promise<{ lastUser: string | null; latestAssistant: string }> {
+export async function peekCursorDiscussion(path: string): Promise<{ lastUser: string | null; latestAssistant: string }> {
   const text = await readWindow(path, true)
   let lastUser: string | null = null
   for (const line of text.split('\n')) {
@@ -1010,7 +1010,7 @@ async function peekCursorDiscussion(path: string): Promise<{ lastUser: string |
   return { lastUser, latestAssistant: latestAssistantFromWindow(text) }
 }
 
-async function firstCursorUserTitle(path: string): Promise<string | null> {
+export async function firstCursorUserTitle(path: string): Promise<string | null> {
   const text = await readWindow(path, false)
   let fallback: string | null = null
   for (const line of text.split('\n')) {
@@ -1455,12 +1455,31 @@ export async function listAgentSessions(
   return rows.slice(0, limit)
 }
 
+/**
+ * Every Claude transcript by its lowercase id (names only, no stat). `shouldStop` lets a bounded caller end the walk
+ * between folders; a stopped walk answers what it has.
+ */
+export async function loadClaudeTranscriptIndex(roots: AgentSessionRoots, shouldStop: () => boolean = () => false): Promise<Map<string, string[]>> {
+  const files = new Map<string, string[]>()
+  for (const folder of await dirents(roots.claudeProjects)) {
+    if (shouldStop()) break
+    const dir = join(roots.claudeProjects, folder)
+    for (const name of await dirents(dir)) {
+      if (!CLAUDE_UUID_JSONL.test(name)) continue
+      const id = name.slice(0, -6).toLowerCase()
+      files.set(id, [...(files.get(id) || []), join(dir, name)])
+    }
+  }
+  return files
+}
+
 export async function findAgentSessionFile(
   provider: AgentProvider,
   sessionId: string,
   roots: AgentSessionRoots,
   now = new Date(),
   preloadedAliases?: ClaudeAliasMap,
+  preloaded?: { claudeFiles?: ReadonlyMap<string, string[]>; codexFiles?: readonly string[] },
 ): Promise<string | null> {
   if (!isSafeSessionId(sessionId)) return null
   const needle = sessionId.trim().toLowerCase()
@@ -1473,15 +1492,8 @@ export async function findAgentSessionFile(
     // Names only. This used to lstat every transcript on this Mac (1,697 of
     // them) to keep directories out of the candidate set, on every call. The
     // isFile check now runs on the one id that matched, below.
-    const files = new Map<string, string[]>()
-    for (const folder of await dirents(roots.claudeProjects)) {
-      const dir = join(roots.claudeProjects, folder)
-      for (const name of await dirents(dir)) {
-        if (!CLAUDE_UUID_JSONL.test(name)) continue
-        const id = name.slice(0, -6).toLowerCase()
-        files.set(id, [...(files.get(id) || []), join(dir, name)])
-      }
-    }
+    // 7.0.1: a caller resolving several ids at once (work-session-activity.ts) builds this index once and hands it in.
+    const files = preloaded?.claudeFiles ?? await loadClaudeTranscriptIndex(roots)
     const exact = aliases.has(needle) || files.has(needle)
     const ids = new Set<string>()
     for (const [id, head] of aliases) {
@@ -1498,8 +1510,9 @@ export async function findAgentSessionFile(
     return matches.length === 1 ? matches[0] : null
   }
   if (provider === 'codex') {
-    for (const root of codexSessionRootsOf(roots)) {
-      for (const file of await listCodexJsonlFiles(root)) {
+    const lists = preloaded?.codexFiles ? [preloaded.codexFiles] : await Promise.all(codexSessionRootsOf(roots).map(root => listCodexJsonlFiles(root)))
+    for (const list of lists) {
+      for (const file of list) {
         const name = file.split('/').pop()?.toLowerCase() ?? ''
         if (name.includes(needle)) return file
       }

package/server/lib/agent-session-tool-images.ts

@@ -0,0 +1,224 @@
+// Images a session LOOKED AT: the pictures that came back inside tool results (a Read of a PNG,
+// a browser or computer-use screenshot) and the pictures a person attached to a prompt.
+//
+// WHY. Miles, 11/08: the Claude app shows a thumbnail under a step like "Ran 2 commands, read 2
+// files", labelled "Read" and "1 of 2". Control Web showed only words for that turn. 6.99.28
+// covered images written into reply text and 6.99.35 covered SendUserFile; neither covered tool
+// results or prompt attachments.
+//
+// RECORD SHAPES (read from real transcripts on this Mac, 11/08, shapes only):
+// - Claude, a Read of an image: a `user` row with `toolUseResult: { type: 'image', file: { base64,
+//   type, originalSize, dimensions } }` and `message.content: [{ type: 'tool_result', tool_use_id,
+//   content: [{ type: 'image', source: { type: 'base64', media_type, data } }] }]`.
+// - Claude, a screenshot (Claude_Browser / claude-in-chrome / computer-use / Claude_Preview): the
+//   same tool_result block, its `content` a mix of text blocks and image blocks of base64 source.
+// - Claude, a prompt attachment: a plain `user` row (no toolUseResult) whose `message.content`
+//   holds `{ type: 'image', source: { type: 'base64', ... } }` beside the text block. A few rows
+//   (sent through the SDK) carry the image and no words at all.
+// - Codex: `response_item` rows. A tool output is `function_call_output` or
+//   `custom_tool_call_output` with `output: [{ type: 'input_text' }, { type: 'input_image',
+//   image_url: 'data:image/png;base64,...', detail }]`; a prompt attachment is a user `message`
+//   whose `content` holds `input_image` blocks. The calls were `exec`, `wait` and `js`.
+// - Every image seen was embedded base64 (png, jpeg, webp). None referenced a path only. The
+//   path-only Read is still handled, under the workspace rules output images use.
+//
+// This module is pure: it finds the images and names them. Ids, the workspace check and the
+// bytes live in agent-session-output-images.ts, beside the other previews.
+import type { AgentProvider } from './agent-session-store.js'
+
+export type ToolImageLabel = 'Read' | 'Screenshot' | 'Image' | 'Attached'
+export interface SessionToolImage {
+  /** Opaque, process-scoped: `ti_` and 64 hex characters. */
+  id: string
+  /** What the step was, as the Claude app labels it: "Read", "Screenshot", or "Attached" for a prompt image. */
+  tool: ToolImageLabel
+  /** Its place in the step, 1-based: "1 of 2". */
+  index: number
+  total: number
+  state: 'available' | 'unavailable'
+  /**
+   * `too_large`: the embedded image is over MAX_TOOL_IMAGE_BYTES. `outside_workspace` and
+   * `unavailable`: a path-only Read, under the output-image rules. `missing`: no bytes and no path.
+   * `secret_file` (7.0.4): a Read (path-only, or with its bytes embedded) of a file whose name says it may hold secrets
+   * (lib/secret-path-guard.ts). Embedded bytes with no path (a screenshot, a prompt attachment) have no name to judge.
+   */
+  reason?: 'outside_workspace' | 'unavailable' | 'too_large' | 'missing' | 'secret_file'
+  /** 7.0.4: the words the card shows instead, set only with `secret_file`. */
+  notice?: string
+  /** The step came before the turn's words (a reply that opened with tool calls). */
+  before?: true
+}
+
+export const SESSION_TOOL_IMAGE_ID = /^ti_[a-f0-9]{64}$/
+/** Thumbnails one turn may show. The rest are counted ("+N more") and never get an id. */
+export const TOOL_IMAGES_PER_TURN = 6
+/** The largest decoded image served. The biggest seen on this Mac was about 510 KB. */
+export const MAX_TOOL_IMAGE_BYTES = 8 * 1024 * 1024
+export const TOOL_IMAGE_TYPES: readonly string[] = ['image/png', 'image/jpeg', 'image/webp', 'image/gif']
+const IMAGE_PATH = /\.(png|jpe?g|webp|gif)$/i
+
+export type ToolImageRef =
+  /** `path`: the file a Read named, when its bytes are embedded (7.0.4 QA: the secret guard judges that name). */
+  | { kind: 'embedded'; mediaType: string; data: string; path?: string }
+  | { kind: 'path'; path: string }
+  | { kind: 'missing' }
+export interface ToolUseMeta { name: string; path?: string }
+export interface FoundToolImage { tool: ToolImageLabel; ref: ToolImageRef }
+
+/** The Claude app's label for a tool. Pure. */
+export function toolLabel(name: string | undefined): ToolImageLabel {
+  if (name === 'Read') return 'Read'
+  if (name && /screenshot|computer|zoom|browser_batch|app_batch|snapshot/i.test(name)) return 'Screenshot'
+  return 'Image'
+}
+
+/** Decoded size of a base64 string, without decoding it. */
+export function estimateBytes(b64: string): number {
+  let pad = 0
+  if (b64.endsWith('==')) pad = 2; else if (b64.endsWith('=')) pad = 1
+  return Math.max(0, Math.floor(b64.length * 3 / 4) - pad)
+}
+
+/** The image type the bytes ARE, from their magic numbers, or null. Never the declared type. */
+export function sniffImageType(bytes: Buffer): string | null {
+  if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'image/png'
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg'
+  if (bytes.length >= 6 && /^GIF8[79]a$/.test(bytes.subarray(0, 6).toString('latin1'))) return 'image/gif'
+  if (bytes.length >= 12 && bytes.subarray(0, 4).toString('latin1') === 'RIFF' && bytes.subarray(8, 12).toString('latin1') === 'WEBP') return 'image/webp'
+  return null
+}
+
+/** Decode an embedded image: refused over the cap (checked before decoding) or when the bytes are not a safe image type. */
+export function decodeToolImage(ref: { mediaType: string; data: string }): { status: 'ok'; bytes: Buffer; type: string } | { status: 'too_large' | 'unavailable' } {
+  if (estimateBytes(ref.data) > MAX_TOOL_IMAGE_BYTES) return { status: 'too_large' }
+  const bytes = Buffer.from(ref.data, 'base64')
+  if (!bytes.length || bytes.length > MAX_TOOL_IMAGE_BYTES) return { status: bytes.length ? 'too_large' : 'unavailable' }
+  const type = sniffImageType(bytes)
+  return type ? { status: 'ok', bytes, type } : { status: 'unavailable' }
+}
+
+function obj(v: unknown): Record<string, unknown> | null { return v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : null }
+
+/** An Anthropic image block of base64 source with a safe declared type, or null. */
+function base64Block(block: unknown): ToolImageRef | null {
+  const b = obj(block); if (!b || b.type !== 'image') return null
+  const s = obj(b.source)
+  if (!s || s.type !== 'base64' || typeof s.data !== 'string' || !s.data || typeof s.media_type !== 'string') return null
+  if (!TOOL_IMAGE_TYPES.includes(s.media_type)) return null
+  return { kind: 'embedded', mediaType: s.media_type, data: s.data }
+}
+/** A Codex/OpenAI `input_image` block carrying a data URL of a safe type, or null. Remote URLs stay inert. */
+function dataUrlBlock(block: unknown): ToolImageRef | null {
+  const b = obj(block); if (!b || b.type !== 'input_image' || typeof b.image_url !== 'string') return null
+  const m = /^data:(image\/(?:png|jpeg|webp|gif));base64,/.exec(b.image_url.slice(0, 64))
+  if (!m) return null
+  return { kind: 'embedded', mediaType: m[1], data: b.image_url.slice(m[0].length) }
+}
+
+/** Keep the source of a Codex view_image so embedded bytes pass the same filename guard as Read. */
+function codexImagePath(args: unknown): string | undefined {
+  if (typeof args === 'string') {
+    if (args.length > 16_384) return undefined
+    try { args = JSON.parse(args) } catch { return undefined }
+  }
+  const path = obj(args)?.path
+  return typeof path === 'string' && path.trim().length > 0 && path.length <= 4096 && !path.includes('\0') ? path : undefined
+}
+
+/** The tool calls a row makes, by call id: their names, and a Read's file path. Pure. */
+export function toolUsesOf(provider: AgentProvider, row: Record<string, unknown>): Array<[string, ToolUseMeta]> {
+  if (row.isSidechain === true) return []
+  if (provider === 'claude') {
+    if (row.type !== 'assistant') return []
+    const content = obj(row.message)?.content
+    if (!Array.isArray(content)) return []
+    const out: Array<[string, ToolUseMeta]> = []
+    for (const block of content) {
+      const b = obj(block)
+      if (!b || b.type !== 'tool_use' || typeof b.id !== 'string' || typeof b.name !== 'string') continue
+      const input = obj(b.input)
+      const path = typeof input?.file_path === 'string' ? input.file_path : undefined
+      out.push([b.id, path ? { name: b.name, path } : { name: b.name }])
+    }
+    return out
+  }
+  if (provider === 'codex') {
+    if (row.type !== 'response_item') return []
+    const p = obj(row.payload)
+    if (!p || (p.type !== 'function_call' && p.type !== 'custom_tool_call') || typeof p.call_id !== 'string' || typeof p.name !== 'string') return []
+    const path = p.name === 'view_image' ? codexImagePath(p.type === 'function_call' ? p.arguments : p.input) : undefined
+    return [[p.call_id, path ? { name: p.name, path } : { name: p.name }]]
+  }
+  return []
+}
+
+/**
+ * The images inside a row's tool results, in order, labelled by the tool that produced them.
+ * A sub-agent's results went to its parent, not to the person, and stay out. Pure.
+ */
+export function toolResultImages(provider: AgentProvider, row: Record<string, unknown>, uses: ReadonlyMap<string, ToolUseMeta>): FoundToolImage[] {
+  if (row.isSidechain === true) return []
+  const out: FoundToolImage[] = []
+  if (provider === 'claude') {
+    if (row.type !== 'user') return []
+    const content = obj(row.message)?.content
+    if (!Array.isArray(content)) return []
+    const results = content.filter(b => obj(b)?.type === 'tool_result')
+    for (const block of results) {
+      const b = obj(block)!
+      const meta = typeof b.tool_use_id === 'string' ? uses.get(b.tool_use_id) : undefined
+      const tool = toolLabel(meta?.name)
+      // 7.0.4 QA: a Read's embedded bytes keep the path it read, so `~/Desktop/credentials.png` is refused by name.
+      const readPath = meta?.name === 'Read' && meta.path ? meta.path : undefined
+      const found = Array.isArray(b.content) ? b.content.map(base64Block).filter((x): x is ToolImageRef => x !== null) : []
+      if (found.length) { for (const ref of found) out.push({ tool, ref: readPath && ref.kind === 'embedded' ? { ...ref, path: readPath } : ref }); continue }
+      // A Read of an image whose message block was not written: the row's own record of the
+      // result may still carry the bytes; else only the path the Read named; else nothing to show.
+      const result = obj(row.toolUseResult)
+      if (results.length !== 1 || b.is_error === true || result?.type !== 'image') continue
+      const file = obj(result.file)
+      if (file && typeof file.base64 === 'string' && file.base64 && typeof file.type === 'string' && TOOL_IMAGE_TYPES.includes(file.type)) {
+        out.push({ tool, ref: { kind: 'embedded', mediaType: file.type, data: file.base64, ...(readPath ? { path: readPath } : {}) } }); continue
+      }
+      if (meta?.name === 'Read' && meta.path && IMAGE_PATH.test(meta.path)) out.push({ tool, ref: { kind: 'path', path: meta.path } })
+      else out.push({ tool, ref: { kind: 'missing' } })
+    }
+    return out
+  }
+  if (provider === 'codex') {
+    if (row.type !== 'response_item') return []
+    const p = obj(row.payload)
+    if (!p || (p.type !== 'function_call_output' && p.type !== 'custom_tool_call_output') || !Array.isArray(p.output)) return []
+    const meta = typeof p.call_id === 'string' ? uses.get(p.call_id) : undefined
+    const tool = meta?.name === 'view_image' ? 'Read' : toolLabel(meta?.name)
+    for (const block of p.output) {
+      const ref = dataUrlBlock(block)
+      if (!ref || ref.kind !== 'embedded') continue
+      // A known file-read without a trustworthy source cannot bypass secret filename checks.
+      // Other image tools (for example exec screenshots) do not name a source file.
+      out.push({ tool, ref: meta?.name === 'view_image' ? meta.path ? { ...ref, path: meta.path } : { kind: 'missing' } : ref })
+    }
+  }
+  return out
+}
+
+/**
+ * The images a person attached to a prompt row, or [] (a tool result, a sub-agent, an injected
+ * row, an assistant row). Whether the row is a turn at all is the turn reader's call. Pure.
+ */
+export function promptImages(provider: AgentProvider, row: Record<string, unknown>): ToolImageRef[] {
+  if (row.isSidechain === true || row.isMeta === true || row.isCompactSummary === true) return []
+  if (provider === 'claude') {
+    if (row.type !== 'user' || row.toolUseResult) return []
+    const content = obj(row.message)?.content
+    if (!Array.isArray(content) || content.some(b => obj(b)?.type === 'tool_result')) return []
+    return content.map(base64Block).filter((x): x is ToolImageRef => x !== null)
+  }
+  if (provider === 'codex') {
+    if (row.type !== 'response_item') return []
+    const p = obj(row.payload)
+    if (!p || p.type !== 'message' || p.role !== 'user' || !Array.isArray(p.content)) return []
+    return p.content.map(dataUrlBlock).filter((x): x is ToolImageRef => x !== null)
+  }
+  return []
+}