@threadcrumbs/common 0.1.4 → 0.1.6

package/telemetry/README.md

@@ -98,8 +98,10 @@ adapter in `../harnesses/`, so a session has the same id in both apps. Add the h
 | `error` | `turn-failed` | The last turn ended in an error | All but Hermes |
 | `done` | `unread` | The harness records that you haven't read the reply | Claude Code (the app's record), Codex, Hermes, OpenCode 2.x |
 | | `recent` | No record of reading, and the turn ended in the last 30 minutes | All |
+| | `process-idle` | The live process says it's idle, with no record of reading, and the turn ended in the last 30 minutes | Claude Code |
 | `idle` | `read` | The harness records that you've read the reply | Claude Code (the app's record), Codex, Hermes, OpenCode 2.x |
 | | `quiet` | No record of reading, and nothing for 30 minutes | All |
+| | `process-idle` | The live process says it's idle, with no record of reading, and nothing for 30 minutes | Claude Code |
 
 ### What a thread needs
 
@@ -158,6 +160,15 @@ Again, a `null` field means the harness doesn't record it. The shared helpers fo
 (`startCall`, `endCall`, `toolTarget`, `keepNewest`, `fileList`, and the limits) are in
 `../lib/telemetry-fields.mjs`.
 
+`sessionDetail(id, { filesOnly: true })` returns only `{ id, sessionId, files }`, with each file
+as `{ path }`, from what the session scan already holds. It's for finding other threads that
+changed the same files, so it never opens the readers that serve an open thread.
+
+The readers that serve an open thread (thoughts and replies for Claude Code, Codex, Cursor, and
+Antigravity) are kept for the last three sessions opened. Claude Code's and Codex's read the
+transcript from its end first, in growing steps, until they have the newest 50 replies, and then
+follow it forwards.
+
 ### Context breakdown
 
 `contextBreakdown` splits the context into parts, so an app can show what fills it.
@@ -170,8 +181,8 @@ Again, a `null` field means the harness doesn't record it. The shared helpers fo
   them aren't read, so an app should call it the default. Free space is `limit - total -
   reserved`.
 - **`parts`** are `[{ id, tokens, items }]` in this order: `messages`, `system`,
-  `builtInTools`, `mcpTools`, `skills`, `memory`. A part a harness doesn't let us size is left
-  out, and its tokens stay in `system`.
+  `builtInTools`, `mcpTools`, `skills`, `memory`. A part the harness records is sent even at 0
+  tokens; one it doesn't record is left out, and its tokens stay in `system`.
   - `messages` items: `{ id: 'prompts' }`, `{ id: 'replies' }`, `{ id: 'summary' }` (from the
     last compaction), and `{ id: 'tool', name }` for each tool's calls and results.
   - `mcpTools` items: `{ name, tools }` per server, `tools` a count or `null`.
@@ -183,6 +194,11 @@ Again, a `null` field means the harness doesn't record it. The shared helpers fo
   - That gives a characters-per-token ratio for the text of each fixed part (system prompt,
     tool definitions, MCP servers, skills, memory files), so each part is its text length at
     that ratio. A part added later counts at the same ratio.
+  - The ratio is used only when the system prompt and tool definitions were recorded, as in
+    Claude Code's `api-request-shape`. Otherwise it would spread their unrecorded text over the
+    parts that were, so each recorded part is its text at 4 characters a token, and `system` is
+    the rest of the fixed count. That's always the case for Codex, whose built-in tool
+    definitions aren't written.
   - `messages` is the rest of the total. Each request's growth over the one before is split
     among the prompts, replies, and tool calls and results since then, by text length. After a
     compaction, the next request's growth over the fixed parts is the summary.
@@ -200,8 +216,8 @@ Again, a `null` field means the harness doesn't record it. The shared helpers fo
   - Codex: the rollout's base instructions and developer messages, its AGENTS.md messages, and
     its `additional_tools` items. Its built-in tool definitions aren't written, so they're in
     `system`.
-- **Read only for an open thread,** by the same second reader as thoughts and replies. It keeps
-  numbers and names, never the text.
+- **Its sizes are kept by the session scan,** which already reads every record, as numbers and
+  names only, never the text, so opening a thread doesn't read its transcript again.
 
 ### Tool kinds
 

package/telemetry/antigravity.mjs

@@ -252,9 +252,10 @@ export function antigravity({
     return sessions
   }
 
-  async function sessionDetail(key) {
+  async function sessionDetail(key, { filesOnly = false } = {}) {
     const id = String(key).replace(/^antigravity:/, '')
     if (!known.has(id)) return null
+    if (filesOnly) return { id: `antigravity:${id}`, sessionId: id, files: null }
     const sessionDir = path.join(brainDir, id)
     const found = await transcriptOf(sessionDir)
     const state = (found && (await transcripts.read(found.file, found.stat).catch(() => null))) || emptyTranscript()

package/telemetry/claude-code.mjs

@@ -6,7 +6,8 @@ import { awaitedPeers, readLiveSessions, transcriptDetail, transcriptReader, tur
 import { exists, listDirs, listFiles, num } from '../lib/fsutil.mjs'
 import { contextBreakdown } from '../lib/context-breakdown.mjs'
 import { recentReaders } from '../lib/jsonl-follower.mjs'
-import { DETAIL_LIMITS, RECENT_MS, askOf, number, planSummary, sampleList, text, titleFromPrompt, toolNow } from '../lib/telemetry-fields.mjs'
+import { nameKind } from '../lib/tool-kinds.mjs'
+import { DETAIL_LIMITS, RECENT_MS, askOf, filePaths, number, planSummary, sampleList, text, titleFromPrompt, toolNow } from '../lib/telemetry-fields.mjs'
 
 export { nextPlan } from '../lib/telemetry-fields.mjs'
 
@@ -27,10 +28,10 @@ export function claudeCode({
   const projectsDir = path.join(home, 'projects')
   const liveDir = path.join(home, 'sessions')
   const catalogDir = path.join(home, 'cache', 'model-catalog')
-  const transcripts = transcriptReader({ detail: true })
+  const transcripts = transcriptReader({ detail: true, sizes: true })
   const subagentFiles = transcriptReader()
   const subagentDetails = transcriptReader({ detail: true, words: true })
-  const openedFor = recentReaders(() => transcriptReader({ words: true, sizes: true }), OPENED_KEPT)
+  const openedFor = recentReaders(() => transcriptReader({ words: true, tail: true }), OPENED_KEPT)
   const desktopRecords = desktopRecordReader()
   const olderReaders = new Map()
   const metas = new Map()
@@ -219,11 +220,11 @@ export function claudeCode({
     const read = await openedFor(file).read(file, stat).catch(() => null)
     const limit = contextLimit(limits, state.model)
     const reserved = limit ? Math.min(RESERVED_TOKENS, limit) : RESERVED_TOKENS
-    return { words: read?.words ?? null, contextBreakdown: contextBreakdown(read?.sizes, { total: state.context, limit, reserved }) }
+    return { words: read?.words ?? null, contextBreakdown: contextBreakdown(state.sizes, { total: state.context, limit, reserved }) }
   }
 
   function olderReader(file) {
-    const reader = olderReaders.get(file) || transcriptReader({ detail: true })
+    const reader = olderReaders.get(file) || transcriptReader({ detail: true, sizes: true })
     olderReaders.delete(file)
     olderReaders.set(file, reader)
     while (olderReaders.size > OLDER_KEPT) olderReaders.delete(olderReaders.keys().next().value)
@@ -252,13 +253,14 @@ export function claudeCode({
     }
   }
 
-  async function sessionDetail(sessionKey, { subagent = null } = {}) {
+  async function sessionDetail(sessionKey, { subagent = null, filesOnly = false } = {}) {
     const id = String(sessionKey).replace(/^claude-code:/, '')
     const file = known.get(id)
     const stat = file ? await fsp.stat(file).catch(() => null) : null
     if (!stat) return null
     if (subagent != null) return subagentDetail(file, id, String(subagent))
     const state = await transcripts.read(file, stat)
+    if (filesOnly) return { id: `claude-code:${id}`, sessionId: id, files: filePaths(state.detail.files, state.cwd) }
     const said = await opened(file, stat, state, await contextLimits())
     return {
       id: `claude-code:${id}`,
@@ -332,15 +334,19 @@ function statusOf({ running, state, calls, subagents, awaiting, lastAt, mark, un
   const { failed, onAgents: onlyAgents } = turnEnding(state)
   const blocked = mark?.outcome === 'blocked'
   const failedTurn = failed || Boolean(mark?.failed)
-  const quiet = () => (unread ? ['done', 'unread'] : ['idle', mark ? 'read' : 'quiet'])
+  const settled = running?.status === 'idle'
+  const quiet = () => (unread ? ['done', 'unread'] : ['idle', mark ? 'read' : settled ? 'process-idle' : 'quiet'])
   if (running) {
-    if (running.status === 'waiting') return ['asking', calls.some((c) => c.questions) ? 'question' : calls.length ? 'approval' : 'waiting']
+    if (running.status === 'waiting') {
+      const asked = calls.filter((c) => (c.kind ?? nameKind(c.name)) !== 'agent')
+      return ['asking', asked.some((c) => c.questions) ? 'question' : asked.length ? 'approval' : 'waiting']
+    }
     const busy = running.status ? running.status === 'busy' : midTurn
     if (busy) return onlyAgents ? ['delegating', 'subagents'] : ['working', running.status ? 'process-busy' : 'turn-open']
     if (subagents || awaiting.length) return ['delegating', subagents ? 'subagents' : 'awaiting']
     if (blocked) return ['asking', 'marked-blocked']
     if (failedTurn) return ['error', 'turn-failed']
-    if (!unread && now - lastAt < ACTIVE_WINDOW_MS) return ['done', 'recent']
+    if (!unread && now - lastAt < ACTIVE_WINDOW_MS) return ['done', settled ? 'process-idle' : 'recent']
     return quiet()
   }
   if (midTurn && now - lastAt < STALE_TURN_MS) return onlyAgents ? ['delegating', 'subagents'] : ['working', 'turn-open']
@@ -364,7 +370,8 @@ function toSession({ id, state, stat, running, subagents, workingSubagents, awai
   const unread = Boolean(mark) && (state.handedBackAt || mark.activeAt) > mark.focusedAt
   const calls = [...state.open.values()].sort((a, b) => a.startedAt - b.startedAt)
   const [status, statusReason] = statusOf({ running, state, calls, subagents, awaiting, lastAt: lastActivityAt, mark, unread, now })
-  const errorText = state.detail?.errors.at(-1)?.message || mark?.errorText || ''
+  const markFailed = Boolean(mark?.failed) && !turnEnding(state).failed
+  const errorText = (markFailed && mark.errorText) || state.detail?.errors.at(-1)?.message || mark?.errorText || ''
   const midTurn = Boolean(state.ending && !state.ending.handedBack)
   const turnOpen = midTurn && (status === 'working' || status === 'delegating' || status === 'asking')
   const { projectPath, project, worktree } = projectOf(mark?.cwd || state.firstCwd || state.cwd, mark?.originCwd)

package/telemetry/codex.mjs

@@ -19,6 +19,7 @@ import {
   emptySample,
   endCall,
   fileList,
+  filePaths,
   inputKind,
   joinedText,
   keepNewest,
@@ -34,6 +35,7 @@ import {
   startCall,
   text,
   textList,
+  wordsFull,
   titleFromPrompt,
   toolInput,
   toolNow,
@@ -43,6 +45,7 @@ import {
 const ACTIVE_WINDOW_MS = 30 * 60 * 1000
 const SUBAGENT_WINDOW_MS = 10 * 60 * 1000
 const OPENED_KEPT = 3
+const TAIL_BYTES = 512 * 1024
 const COMPACT_SHARE = 0.9
 const REPORTED_SHARE = 0.95
 const ROLLOUT_FILE = /^rollout-.{19}-([0-9a-f-]{36})(?:_[0-9a-f-]{36})?\.jsonl$/i
@@ -143,6 +146,7 @@ function emptyRollout() {
     fallbackPrompts: 0,
     open: false,
     turnStartedAt: 0,
+    turnId: '',
     usageLimits: null,
     failed: false,
     calls: new Map(),
@@ -151,6 +155,8 @@ function emptyRollout() {
     tokens: null,
     context: null,
     contextSample: emptySample(),
+    sizes: emptySizes(),
+    sent: emptySent(),
     plan: null,
     history: [],
     contextParts: null,
@@ -166,13 +172,19 @@ function emptyRollout() {
 
 const AGENTS_FILE = /^# AGENTS\.md instructions for ([^\n]+)/
 
-const emptyOpened = () => ({
-  lastAt: 0,
-  thoughts: [],
-  replies: [],
-  sizes: emptySizes(),
-  sent: { base: 0, developer: [], other: 0, memory: new Map(), tools: new Map() },
-})
+const emptyWords = () => ({ lastAt: 0, thoughts: [], replies: [] })
+
+function applyWords(state, record) {
+  const at = Date.parse(record.timestamp) || state.lastAt
+  state.lastAt = at
+  const item = record.payload
+  if (record.type !== 'response_item' || !item || typeof item !== 'object') return
+  const id = text(item.id) || null
+  if (item.type === 'reasoning') keepText(state.thoughts, 'thoughts', { id, at, text: joinedText(item.summary, 'summary_text', 'text') })
+  else if (item.type === 'message' && item.role === 'assistant') keepText(state.replies, 'replies', { id, at, text: joinedText(item.content, 'output_text', 'text') })
+}
+
+const emptySent = () => ({ base: 0, developer: [], other: 0, memory: new Map(), tools: new Map() })
 
 function callName(item) {
   if (item.type === 'local_shell_call') return 'shell'
@@ -186,14 +198,11 @@ function codexFixed(sent) {
   fixed.system = developer + (sent.developer.includes(sent.base) ? 0 : sent.base) + sent.other
   fixed.mcp = new Map(sent.tools)
   fixed.memory = new Map(sent.memory)
+  fixed.recorded = new Set(['system', 'mcpTools', 'memory'])
   return fixed
 }
 
-function applyOpened(state, record) {
-  const at = Date.parse(record.timestamp) || state.lastAt
-  state.lastAt = at
-  const item = record.payload
-  if (!item || typeof item !== 'object') return
+function applySizes(state, record, item, at) {
   const { sizes, sent } = state
   const before = sizes.first == null
   if (record.type === 'session_meta') {
@@ -207,14 +216,10 @@ function applyOpened(state, record) {
   } else if (record.type !== 'response_item') {
     return
   } else if (item.type === 'reasoning') {
-    const said = joinedText(item.summary, 'summary_text', 'text')
-    keepText(state.thoughts, 'thoughts', { id: text(item.id) || null, at, text: said })
-    sizeReply(sizes, said.length)
+    sizeReply(sizes, joinedText(item.summary, 'summary_text', 'text').length)
     return
   } else if (item.type === 'message' && item.role === 'assistant') {
-    const said = joinedText(item.content, 'output_text', 'text')
-    keepText(state.replies, 'replies', { id: text(item.id) || null, at, text: said })
-    sizeReply(sizes, said.length)
+    sizeReply(sizes, joinedText(item.content, 'output_text', 'text').length)
     return
   } else if (CALLS.has(item.type)) {
     sizeCall(sizes, text(item.call_id), callName(item), (text(item.arguments) || text(item.input) || JSON.stringify(item.action ?? '')).length)
@@ -230,7 +235,7 @@ function applyOpened(state, record) {
   } else if (item.type === 'message') {
     const raw = contentText(item.content)
     const agents = item.role === 'user' ? AGENTS_FILE.exec(raw) : null
-    if (agents) sent.memory.set(`${agents[1].trim().replace(/[\/]+$/, '')}/AGENTS.md`, raw.length)
+    if (agents) sent.memory.set(`${agents[1].trim().replace(/[\\/]+$/, '')}/AGENTS.md`, raw.length)
     else if (item.role === 'user' && promptText(raw)) {
       sizePrompt(sizes, raw.length)
       return
@@ -253,6 +258,7 @@ function applyRecord(state, record) {
   }
   const payload = record.payload
   if (!payload || typeof payload !== 'object') return
+  applySizes(state, record, payload, at || state.lastAt)
   if (record.type === 'session_meta') applyMeta(state, payload)
   else if (record.type === 'turn_context') applySettings(state, payload.model, payload.effort, payload.cwd)
   else if (record.type === 'response_item') applyItem(state, payload, at || state.lastAt)
@@ -367,13 +373,16 @@ function addLines(state, patch) {
 function applyEvent(state, event, at) {
   switch (event.type) {
     case 'task_started':
-    case 'turn_started':
-      if (!state.open) state.turnStartedAt = at
+    case 'turn_started': {
+      const turn = text(event.turn_id)
+      if (!state.open || (turn && turn !== state.turnId)) state.turnStartedAt = at
+      if (turn) state.turnId = turn
       state.open = true
       state.failed = false
       state.calls.clear()
       settleCalls(state.activity)
       break
+    }
     case 'task_complete':
     case 'turn_complete':
       state.open = false
@@ -468,7 +477,7 @@ export function codex({
   const locksDir = path.join(home, 'thread-writer-locks')
   const indexFile = path.join(home, 'session_index.jsonl')
   const rollouts = jsonlFollower({ empty: emptyRollout, apply: applyRecord })
-  const openedFor = recentReaders(() => jsonlFollower({ empty: emptyOpened, apply: applyOpened }), OPENED_KEPT)
+  const openedFor = recentReaders(() => jsonlFollower({ empty: emptyWords, apply: applyWords, tail: { bytes: TAIL_BYTES, enough: wordsFull } }), OPENED_KEPT)
   let index = { mtime: -1, names: new Map() }
   let known = new Map()
   let childrenOf = new Map()
@@ -576,11 +585,12 @@ export function codex({
     return state ? { file, stat, state } : null
   }
 
-  async function sessionDetail(key) {
+  async function sessionDetail(key, { filesOnly = false } = {}) {
     const id = String(key).replace(/^codex:/, '').toLowerCase()
     const found = await readKnown(id)
     if (!found || found.state.subagent || found.state.internal) return null
     const { file, stat, state } = found
+    if (filesOnly) return { id: `codex:${id}`, sessionId: id, files: filePaths(state.files, state.cwd) }
     const said = await openedFor(file).read(file, stat).catch(() => null)
     const limit = state.context?.limit || null
     const subagents = []
@@ -617,7 +627,7 @@ export function codex({
       prompts: (state.typed ? state.promptList : state.fallbackPromptList).map((p) => ({ ...p })),
       thoughts: textList(said?.thoughts),
       replies: textList(said?.replies),
-      contextBreakdown: contextBreakdown(said?.sizes, {
+      contextBreakdown: contextBreakdown(state.sizes, {
         total: state.context?.used,
         limit,
         reserved: limit ? Math.round(limit * (1 - COMPACT_SHARE / REPORTED_SHARE)) : null,

package/telemetry/cursor.mjs

@@ -198,9 +198,10 @@ export function cursor({
     return list.sort((a, b) => a.startedAt - b.startedAt).slice(-DETAIL_LIMITS.subagents)
   }
 
-  async function sessionDetail(key) {
+  async function sessionDetail(key, { filesOnly = false } = {}) {
     const id = String(key).replace(/^cursor:/, '')
     const entry = known.get(id)
+    if (filesOnly) return entry ? { id: `cursor:${id}`, sessionId: id, files: null } : null
     const stat = entry ? await fsp.stat(entry.file).catch(() => null) : null
     if (!stat) return null
     const state = await follow(entry.file, stat)

package/telemetry/hermes.mjs

@@ -122,10 +122,11 @@ export function hermes({ home = resolveHermesHome(), now = Date.now } = {}) {
     return sessions
   }
 
-  async function sessionDetail(key) {
+  async function sessionDetail(key, { filesOnly = false } = {}) {
     const match = /^hermes:([^:]+):(.+)$/.exec(String(key))
     if (!match) return null
     const [, profile, rootId] = match
+    if (filesOnly) return { id: `hermes:${profile}:${rootId}`, sessionId: rootId, files: null }
     const store = (await storeFiles()).find((s) => s.profile === profile)
     if (!store) return null
     const detail = await withReadOnly(store.file, (db) => detailFrom(db, rootId, now()), null)

package/ui/fonts.css

@@ -0,0 +1,48 @@
+@font-face {
+  font-family: 'Inter Variable';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 100 900;
+  unicode-range: U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF;
+  src: url('./fonts/inter-latin-ext-wght-normal.woff2') format('woff2-variations');
+}
+@font-face {
+  font-family: 'Inter Variable';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 100 900;
+  unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
+  src: url('./fonts/inter-latin-wght-normal.woff2') format('woff2-variations');
+}
+@font-face {
+  font-family: 'Inter Tight Variable';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 100 900;
+  unicode-range: U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF;
+  src: url('./fonts/inter-tight-latin-ext-wght-normal.woff2') format('woff2-variations');
+}
+@font-face {
+  font-family: 'Inter Tight Variable';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 100 900;
+  unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
+  src: url('./fonts/inter-tight-latin-wght-normal.woff2') format('woff2-variations');
+}
+@font-face {
+  font-family: 'JetBrains Mono Variable';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 100 800;
+  unicode-range: U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF;
+  src: url('./fonts/jetbrains-mono-latin-ext-wght-normal.woff2') format('woff2-variations');
+}
+@font-face {
+  font-family: 'JetBrains Mono Variable';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 100 800;
+  unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
+  src: url('./fonts/jetbrains-mono-latin-wght-normal.woff2') format('woff2-variations');
+}

package/ui/format.mjs

@@ -0,0 +1,60 @@
+const UNITS = [
+  ['B', 1e9],
+  ['M', 1e6],
+  ['K', 1e3],
+]
+
+export function compactNumber(n) {
+  if (!Number.isFinite(n)) return '—'
+  const abs = Math.abs(n)
+  for (const [suffix, size] of UNITS) {
+    if (abs < size * 0.9995) continue
+    const value = n / size
+    const shown = Math.abs(value) >= 99.95 ? String(Math.round(value)) : value.toFixed(1).replace(/\.0$/, '')
+    return `${shown}${suffix}`
+  }
+  return String(Math.round(n))
+}
+
+export function duration(ms) {
+  const seconds = Math.max(0, Math.floor(ms / 1000))
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  if (minutes < 60) return `${minutes}m ${seconds % 60}s`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return `${hours}h ${minutes % 60}m`
+  return `${Math.floor(hours / 24)}d ${hours % 24}h`
+}
+
+export function callDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return '—'
+  const tenths = Math.round(ms / 100)
+  if (tenths < 10) return `${(tenths / 10).toFixed(1)}s`
+  return duration(Math.max(ms, 1000))
+}
+
+export function ago(ms) {
+  if (ms < 45 * 1000) return 'just now'
+  const minutes = Math.round(ms / 60000)
+  if (minutes < 60) return `${minutes}m ago`
+  const hours = Math.round(minutes / 60)
+  if (hours < 24) return `${hours}h ago`
+  return `${Math.round(hours / 24)}d ago`
+}
+
+export function percent(used, limit) {
+  if (!limit) return null
+  return Math.min(100, Math.max(0, (used / limit) * 100))
+}
+
+export function modelName(id) {
+  const match = /^(?:[\w.-]+\/)?claude-([a-z]+)-(\d+)(?:-(\d{1,2}))?(?:-\d{8})?(\[.*\])?$/.exec(id || '')
+  if (!match) return id || ''
+  const [, family, major, minor] = match
+  return `${family[0].toUpperCase()}${family.slice(1)} ${minor ? `${major}.${minor}` : major}`
+}
+
+export function toolLabel(name) {
+  const mcp = /^mcp__(.+?)__(.+)$/.exec(name || '')
+  return mcp ? `${mcp[2]} (${mcp[1]})` : name || ''
+}

package/ui/gauge.css

@@ -0,0 +1,75 @@
+.inst {
+  display: block;
+  flex: none;
+  overflow: visible;
+}
+.i-dial {
+  fill: var(--dial);
+  stroke: var(--line);
+  stroke-width: 1;
+}
+.i-mini .i-dial {
+  stroke-width: 2.4;
+}
+.i-hub {
+  fill: var(--hub);
+}
+.i-track,
+.i-fill,
+.i-red {
+  fill: none;
+  stroke-width: 6;
+  stroke-linecap: round;
+}
+.i-track {
+  stroke: var(--dial-track);
+}
+.i-fill {
+  stroke: var(--inst);
+}
+.i-red {
+  stroke: var(--err);
+  opacity: 0.8;
+}
+.i-mini .i-track,
+.i-mini .i-fill,
+.i-mini .i-red {
+  stroke-width: 10;
+}
+.inst[data-level='high'] .i-fill {
+  stroke: var(--warn);
+}
+.inst[data-level='full'] .i-fill {
+  stroke: var(--err);
+}
+.i-needle {
+  stroke: var(--needle);
+  stroke-width: 3.2;
+  stroke-linecap: round;
+  filter: drop-shadow(0 0 3px var(--needle-glow));
+}
+.i-mini .i-needle {
+  stroke-width: 6;
+  filter: none;
+}
+.i-label {
+  fill: var(--text);
+  font: 600 12px var(--cond);
+}
+.i-wrap {
+  position: relative;
+}
+.i-wrap::after {
+  content: '';
+  position: absolute;
+  top: calc(-1 * var(--hit-t, 4px));
+  right: calc(-1 * var(--hit-r, 4px));
+  bottom: calc(-1 * var(--hit-b, 4px));
+  left: calc(-1 * var(--hit-l, 4px));
+}
+.i-wrap:has(+ .i-wrap) {
+  --hit-r: 2px;
+}
+.i-wrap + .i-wrap {
+  --hit-l: 2px;
+}

package/ui/gauge.mjs

@@ -0,0 +1,14 @@
+const ARC = 'M-19.8,19.8 A28,28 0 1 1 19.8,19.8'
+const fx = (n) => n.toFixed(2)
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v))
+
+export const levelOf = (pct) => (pct == null ? 'unknown' : pct >= 90 ? 'full' : pct >= 70 ? 'high' : 'ok')
+export const levelClass = (spec) => (spec.level === 'full' ? 'x' : spec.level === 'high' ? 'h' : 'f')
+
+export function contextGauge(spec, size = 18) {
+  const mini = size <= 30
+  const p = clamp(spec.pct ?? 0, 0, 100)
+  const level = spec.level || levelOf(spec.pct ?? null)
+  const body = `<path d="${ARC}" class="i-track" pathLength="100"/><path d="${ARC}" class="i-red" pathLength="100" stroke-dasharray="10 100" stroke-dashoffset="-90"/><path d="${ARC}" class="i-fill" pathLength="100" stroke-dasharray="${fx(p)} 100"/><line x1="0" y1="0" x2="${mini ? 19 : 21}" y2="0" class="i-needle" transform="rotate(${fx(135 + (270 * p) / 100)})"/>${mini ? '' : `<text x="0" y="28" class="i-label" text-anchor="middle">${Math.round(p)}%</text>`}`
+  return `<svg class="inst${mini ? ' i-mini' : ''}" data-k="gauge" data-level="${level}" width="${size}" height="${size}" viewBox="-36 -36 72 72" aria-hidden="true"><circle r="35" class="i-dial"/>${body}<circle r="${mini ? 6 : 4.5}" class="i-hub"/></svg>`
+}

package/ui/html.mjs

@@ -0,0 +1,12 @@
+export const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c])
+
+export const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`
+
+export function joinNames(names) {
+  if (names.length <= 1) return names[0] || ''
+  return `${names.slice(0, -1).join(', ')} and ${names.at(-1)}`
+}
+
+export const termButton = (key, label, attrs = '') => `<button type="button" class="term" data-term="${esc(key)}" aria-expanded="false"${attrs ? ` ${attrs}` : ''}>${esc(label)}</button>`
+
+export const instAttrs = (spec, val = '', sub = '') => `data-inst="${esc(JSON.stringify(spec))}" data-val="${esc(val)}" data-sub="${esc(sub)}"`