dsh-speedometer 0.0.0-stage → 0.1.0

package/lib/index.js

@@ -0,0 +1,1005 @@
+/**
+ * DSH Speedometer
+ *
+ * Measures generation speed at the `llm/stream` layer, so it is provider
+ * agnostic: DeepSeek official, any OpenAI-compatible endpoint and local
+ * models all pass through the same hook. Completed attempts are grouped by
+ * session and served to the in-page widget over SSE.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const ROUTE = '/dsh-speed'
+const WIDGET_ROUTE = `${ROUTE}/widget.js`
+const EVENTS_ROUTE = `${ROUTE}/events`
+const STATE_ROUTE = `${ROUTE}/state`
+const VERSION = '0.1.0'
+const MAX_SESSIONS = 40
+const MAX_ATTEMPTS = 1000
+const MAX_SAMPLES = 220
+const TICK_MS = 180
+const WINDOW_MS = 1600
+const DSH_HOME = process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
+const HISTORY_FILE = path.join(DSH_HOME, 'dsh-speedometer', 'history.json')
+
+const DESKTOP_WIDGET_ROW_TEXT =
+  '(function(){try{var d=document.body||document.head||document.documentElement;if(!d)return;' +
+  'if(document.getElementById("dsh-speedometer-script"))return;' +
+  'var s=document.createElement("script");s.id="dsh-speedometer-script";s.src="' + WIDGET_ROUTE + '";' +
+  's.onerror=function(){};d.appendChild(s)}catch(e){}})()'
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value))
+}
+
+function finite(value) {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+function count(value) {
+  return finite(value) && value >= 0 ? Math.floor(value) : undefined
+}
+
+function textOfContent(content) {
+  try {
+    if (typeof content === 'string') return content
+    if (!Array.isArray(content)) return ''
+    const parts = []
+    for (const block of content) {
+      if (!block || typeof block !== 'object') continue
+      if (block.type === 'text' && typeof block.text === 'string') parts.push(block.text)
+      else if (block.type === 'reasoning' && typeof block.text === 'string') parts.push(block.text)
+    }
+    return parts.join(' ').trim()
+  } catch {
+    return ''
+  }
+}
+
+function shortLabel(text, max = 34) {
+  const normalized = String(text || '').replace(/\s+/g, ' ').trim()
+  if (!normalized) return ''
+  return normalized.length > max ? `${normalized.slice(0, max - 1)}…` : normalized
+}
+
+function safeId(value) {
+  return typeof value === 'string' && value.length > 0 ? value : ''
+}
+
+function isTokenChunk(chunk) {
+  if (!chunk || typeof chunk !== 'object') return false
+  switch (chunk.type) {
+    case 'text-delta':
+    case 'reasoning-delta':
+      return typeof chunk.text === 'string' && chunk.text.length > 0
+    case 'tool-call-delta':
+      return (typeof chunk.argumentsDelta === 'string' && chunk.argumentsDelta.length > 0)
+        || typeof chunk.name === 'string'
+    default:
+      return false
+  }
+}
+
+/** Expand DSH's compact timed stream records without importing host internals. */
+function* expandedRecords(stream) {
+  if (!Array.isArray(stream)) return
+  for (const record of stream) {
+    if (!record || typeof record !== 'object') continue
+    if (record.type === 'chunk' && record.chunk && typeof record.chunk === 'object') {
+      yield { time: finite(record.time) ? record.time : 0, chunk: record.chunk }
+      continue
+    }
+    const members = record.type === 'tool-call-chunks'
+      ? record.args
+      : record.type === 'text-chunks' || record.type === 'reasoning-chunks'
+        ? record.texts
+        : undefined
+    if (!Array.isArray(members)) continue
+    let time = finite(record.time0) ? record.time0 : 0
+    const dt = Array.isArray(record.dt) ? record.dt : []
+    for (let index = 0; index < members.length; index += 1) {
+      if (index > 0 && finite(dt[index - 1])) time += dt[index - 1]
+      yield { time, chunk: null, member: members[index], recordType: record.type }
+    }
+  }
+}
+
+/**
+ * Derive one durable attempt from an assistant settlement's compact stream.
+ * Historical TTFT is intentionally null: the stream begins after the request
+ * is already in flight, so claiming a first-byte latency would be misleading.
+ */
+function deriveSamples(tokenTimes, startTime, lastTime, maxPoints = 48) {
+  if (!Array.isArray(tokenTimes) || tokenTimes.length === 0 || !startTime) return []
+  const endTime = Math.max(lastTime, startTime + 320)
+  const span = endTime - startTime
+  const step = Math.max(280, Math.ceil(span / maxPoints))
+  const points = []
+  let cursor = 0
+  let windowStart = 0
+  for (let t = startTime; t <= endTime + step; t += step) {
+    while (cursor < tokenTimes.length && tokenTimes[cursor] <= t) cursor += 1
+    while (windowStart < cursor && tokenTimes[windowStart] < t - 1200) windowStart += 1
+    const windowTokens = cursor - windowStart
+    const elapsed = Math.max(320, Math.min(1200, t - startTime))
+    points.push({
+      t: Math.max(0, t - startTime),
+      v: windowTokens > 0 ? windowTokens / (elapsed / 1000) : 0,
+    })
+  }
+  return points.length > 0 ? points : [{ t: 0, v: 0 }]
+}
+
+function deriveFromStream(stream, eventTime) {
+  let firstTime = 0
+  let lastTime = 0
+  let firstTokenTime = 0
+  let lastTokenTime = 0
+  let tokens = 0
+  let usage
+  let finishKind = ''
+  const tokenTimes = []
+  for (const entry of expandedRecords(stream)) {
+    if (!firstTime) firstTime = entry.time
+    lastTime = Math.max(lastTime, entry.time)
+    if (entry.chunk) {
+      if ((entry.chunk.type === 'text-delta' || entry.chunk.type === 'reasoning-delta')
+        && typeof entry.chunk.text === 'string' && entry.chunk.text.length > 0) {
+        tokens += 1
+        if (!firstTokenTime) firstTokenTime = entry.time
+        lastTokenTime = Math.max(lastTokenTime, entry.time)
+        tokenTimes.push(entry.time)
+      } else if (entry.chunk.type === 'tool-call-delta'
+        && ((typeof entry.chunk.argumentsDelta === 'string' && entry.chunk.argumentsDelta.length > 0)
+          || typeof entry.chunk.name === 'string')) {
+        tokens += 1
+        if (!firstTokenTime) firstTokenTime = entry.time
+        lastTokenTime = Math.max(lastTokenTime, entry.time)
+        tokenTimes.push(entry.time)
+      } else if (entry.chunk.type === 'usage') {
+        usage = entry.chunk.usage
+      } else if (entry.chunk.type === 'finish') {
+        finishKind = entry.chunk.reason && typeof entry.chunk.reason.kind === 'string'
+          ? entry.chunk.reason.kind
+          : ''
+      }
+    } else if (typeof entry.member === 'string' && entry.member.length > 0) {
+      tokens += 1
+      if (!firstTokenTime) firstTokenTime = entry.time
+      lastTokenTime = Math.max(lastTokenTime, entry.time)
+      tokenTimes.push(entry.time)
+    }
+  }
+  const outputTokens = usage && count(usage.outputTokens)
+  const exactTokens = outputTokens !== undefined && outputTokens > 0 ? outputTokens : tokens
+  const durationMs = firstTime && lastTime > firstTime ? lastTime - firstTime : 0
+  const pointTimes = [...new Set(tokenTimes)].sort((a, b) => a - b)
+  const lastToken = pointTimes.length > 0 ? pointTimes[pointTimes.length - 1] : lastTime
+  const spanMs = lastToken - firstTime
+  const tps = spanMs > 40 && exactTokens > 0 ? exactTokens / (spanMs / 1000) : null
+  return {
+    tokens: exactTokens,
+    inputTokens: usage && count(usage.inputTokens),
+    finishKind,
+    firstTime,
+    lastTime,
+    generationMs: spanMs || durationMs,
+    tps,
+    samples: deriveSamples(pointTimes, firstTime || eventTime, lastTime || eventTime),
+  }
+}
+
+function uniqueId(prefix) {
+  return `${prefix}${Date.now().toString(36)}${Math.random().toString(36).slice(2, 7)}`
+}
+
+export default {
+  name: 'dsh-speedometer',
+
+  apply(root) {
+    const rowDisposers = []
+    try {
+      rowDisposers.push(root.on('webserver/index-inject', (table) => {
+        try {
+          if (!Array.isArray(table)) return
+          for (const row of table) {
+            if (!row) continue
+            if (row.kind === 'script-src' && row.src === WIDGET_ROUTE) return
+            if (row.kind === 'script' && typeof row.text === 'string'
+              && row.text.indexOf(WIDGET_ROUTE) !== -1) return
+          }
+          table.push({ kind: 'script', placement: 'body', text: DESKTOP_WIDGET_ROW_TEXT })
+        } catch {}
+      }))
+    } catch {}
+
+    root.effect(() => () => {
+      for (const dispose of rowDisposers) {
+        try { dispose() } catch {}
+      }
+    })
+
+    root.inject(['webServer', 'sessions', 'llm', 'connection'], (ctx) => {
+      const disposers = []
+      const clients = new Set()
+      const sessions = new Map()
+      let activeSessionId = null
+      let saveTimer = null
+      let lastBroadcastError = 0
+
+      function ensureSession(sessionId, patch = {}) {
+        const id = safeId(sessionId) || 'unknown'
+        let session = sessions.get(id)
+        if (!session) {
+          session = {
+            id,
+            label: '',
+            model: '',
+            provider: '',
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+            attempts: [],
+            live: null,
+            currentTurn: 0,
+          }
+          sessions.set(id, session)
+        }
+        if (patch.label) session.label = patch.label
+        if (patch.model) session.model = patch.model
+        if (patch.provider) session.provider = patch.provider
+        session.updatedAt = Date.now()
+        return session
+      }
+
+      function trimSessions() {
+        if (sessions.size <= MAX_SESSIONS) return
+        const ordered = [...sessions.values()].sort((a, b) => a.updatedAt - b.updatedAt)
+        while (ordered.length > MAX_SESSIONS) {
+          const victim = ordered.shift()
+          if (!victim || victim.id === activeSessionId) continue
+          sessions.delete(victim.id)
+        }
+      }
+
+      function attemptSignature(attempt) {
+        return [
+          attempt.sessionId,
+          attempt.turn ?? '',
+          attempt.step ?? '',
+          attempt.tokens,
+          Math.round((attempt.endedAt || attempt.startedAt || 0) / 2000),
+        ].join('|')
+      }
+
+      function addAttempt(attempt, { broadcast = true } = {}) {
+        const session = ensureSession(attempt.sessionId, {
+          model: attempt.model,
+          provider: attempt.provider,
+        })
+        const signature = attemptSignature(attempt)
+        const existing = session.attempts.find((candidate) => attemptSignature(candidate) === signature)
+        if (existing) return existing
+        session.attempts.push(attempt)
+        if (session.attempts.length > MAX_ATTEMPTS) {
+          session.attempts.splice(0, session.attempts.length - MAX_ATTEMPTS)
+        }
+        session.updatedAt = Date.now()
+        if (broadcast) emit('attempt', { attempt: publicAttempt(attempt, true), session: publicSessionMeta(session) })
+        scheduleSave()
+        return attempt
+      }
+
+      function publicSample(sample) {
+        return { t: Math.round(sample.t), v: Math.round(sample.v * 10) / 10 }
+      }
+
+      function publicAttempt(attempt, includeSamples = false) {
+        if (!attempt) return null
+        const out = {
+          id: attempt.id,
+          provider: attempt.provider || '',
+          model: attempt.model || '',
+          startedAt: attempt.startedAt,
+          endedAt: attempt.endedAt,
+          ttftMs: finite(attempt.ttftMs) ? Math.round(attempt.ttftMs) : null,
+          durationMs: finite(attempt.durationMs) ? Math.round(attempt.durationMs) : null,
+          tokens: attempt.tokens || 0,
+          inputTokens: attempt.inputTokens,
+          tps: finite(attempt.tps) ? Math.round(attempt.tps * 10) / 10 : null,
+          peakTps: finite(attempt.peakTps) ? Math.round(attempt.peakTps * 10) / 10 : null,
+          status: attempt.status || 'done',
+          turn: attempt.turn,
+          step: attempt.step,
+          historical: attempt.historical === true,
+        }
+        if (includeSamples && Array.isArray(attempt.samples) && attempt.samples.length > 0) {
+          out.samples = attempt.samples.map(publicSample)
+        }
+        return out
+      }
+
+      function publicSessionMeta(session) {
+        return {
+          id: session.id,
+          label: session.label || '',
+          model: session.model || '',
+          provider: session.provider || '',
+          updatedAt: session.updatedAt,
+          count: session.attempts.length,
+        }
+      }
+
+      function publicLive(live) {
+        if (!live) return null
+        return {
+          id: live.id,
+          sessionId: live.sessionId,
+          provider: live.provider || '',
+          model: live.model || '',
+          startedAt: live.startedAt,
+          tokens: live.tokens || 0,
+          tps: finite(live.tps) ? Math.round(live.tps * 10) / 10 : 0,
+          avgTps: finite(live.avgTps) ? Math.round(live.avgTps * 10) / 10 : null,
+          peakTps: finite(live.peakTps) ? Math.round(live.peakTps * 10) / 10 : null,
+          ttftMs: finite(live.ttftMs) ? Math.round(live.ttftMs) : null,
+          elapsedMs: Math.max(0, Date.now() - live.startedAt),
+          turn: live.turn,
+          samples: Array.isArray(live.samples) ? live.samples.map(publicSample) : [],
+        }
+      }
+
+      function publicState() {
+        const list = [...sessions.values()]
+          .filter((session) => session.attempts.length > 0 || session.live)
+          .sort((a, b) => b.updatedAt - a.updatedAt)
+          .slice(0, 24)
+          .map((session) => {
+            const attempts = session.attempts.slice(-MAX_ATTEMPTS)
+            const sampleFrom = attempts.length - 120
+            const mapped = attempts.map((attempt, index) => publicAttempt(attempt, index >= sampleFrom))
+            return {
+              ...publicSessionMeta(session),
+              attempts: mapped,
+              live: publicLive(session.live),
+            }
+          })
+        return {
+          type: 'state',
+          version: VERSION,
+          activeSessionId,
+          sessions: list,
+          serverTime: Date.now(),
+        }
+      }
+
+      function writeSse(res, event, payload) {
+        try {
+          res.write(`event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`)
+        } catch (error) {
+          clients.delete(res)
+        }
+      }
+
+      function emit(event, payload) {
+        for (const res of [...clients]) {
+          try {
+            writeSse(res, event, payload)
+          } catch (error) {
+            clients.delete(res)
+          }
+        }
+        if (clients.size === 0) return
+        if (Date.now() - lastBroadcastError < 0) lastBroadcastError = 0
+      }
+
+      function scheduleSave() {
+        if (saveTimer) clearTimeout(saveTimer)
+        saveTimer = setTimeout(saveHistory, 900)
+        if (typeof saveTimer.unref === 'function') saveTimer.unref()
+      }
+
+      function serializableAttempt(attempt) {
+        const out = publicAttempt(attempt, true)
+        return out
+      }
+
+      function saveHistory() {
+        saveTimer = null
+        try {
+          const payload = {
+            version: 1,
+            savedAt: Date.now(),
+            activeSessionId,
+            sessions: [...sessions.values()]
+              .filter((session) => session.attempts.length > 0)
+              .sort((a, b) => a.updatedAt - b.updatedAt)
+              .slice(-MAX_SESSIONS)
+              .map((session) => ({
+                ...publicSessionMeta(session),
+                attempts: session.attempts.slice(-MAX_ATTEMPTS).map(serializableAttempt),
+              })),
+          }
+          fs.mkdirSync(path.dirname(HISTORY_FILE), { recursive: true })
+          const temporary = `${HISTORY_FILE}.tmp`
+          fs.writeFileSync(temporary, JSON.stringify(payload), 'utf8')
+          fs.renameSync(temporary, HISTORY_FILE)
+        } catch (error) {
+          try { ctx.logger?.warn?.(`[dsh-speedometer] history save failed: ${error.message}`) } catch {}
+        }
+      }
+
+      function loadHistory() {
+        try {
+          const raw = fs.readFileSync(HISTORY_FILE, 'utf8')
+          const payload = JSON.parse(raw)
+          if (!payload || !Array.isArray(payload.sessions)) return
+          for (const item of payload.sessions) {
+            if (!item || typeof item.id !== 'string' || !Array.isArray(item.attempts)) continue
+            const session = ensureSession(item.id, {
+              label: typeof item.label === 'string' ? item.label : '',
+              model: typeof item.model === 'string' ? item.model : '',
+              provider: typeof item.provider === 'string' ? item.provider : '',
+            })
+            session.createdAt = finite(item.createdAt) ? item.createdAt : session.createdAt
+            session.updatedAt = finite(item.updatedAt) ? item.updatedAt : session.updatedAt
+            for (const candidate of item.attempts.slice(-MAX_ATTEMPTS)) {
+              if (!candidate || !finite(candidate.startedAt)) continue
+              const attempt = {
+                id: typeof candidate.id === 'string' ? candidate.id : uniqueId('a'),
+                sessionId: item.id,
+                provider: typeof candidate.provider === 'string' ? candidate.provider : '',
+                model: typeof candidate.model === 'string' ? candidate.model : '',
+                startedAt: candidate.startedAt,
+                endedAt: finite(candidate.endedAt) ? candidate.endedAt : candidate.startedAt,
+                ttftMs: finite(candidate.ttftMs) ? candidate.ttftMs : null,
+                durationMs: finite(candidate.durationMs) ? candidate.durationMs : null,
+                tokens: count(candidate.tokens) || 0,
+                inputTokens: count(candidate.inputTokens),
+                tps: finite(candidate.tps) ? candidate.tps : null,
+                peakTps: finite(candidate.peakTps) ? candidate.peakTps : null,
+                status: typeof candidate.status === 'string' ? candidate.status : 'done',
+                turn: finite(candidate.turn) ? candidate.turn : undefined,
+                step: finite(candidate.step) ? candidate.step : undefined,
+                historical: candidate.historical === true,
+                samples: Array.isArray(candidate.samples)
+                  ? candidate.samples.filter((s) => finite(s?.t) && finite(s?.v)).slice(-MAX_SAMPLES)
+                  : [],
+              }
+              addAttempt(attempt, { broadcast: false })
+            }
+          }
+          activeSessionId = safeId(payload.activeSessionId) || activeSessionId
+        } catch (error) {
+          if (error && error.code !== 'ENOENT') {
+            try { ctx.logger?.warn?.(`[dsh-speedometer] history load failed: ${error.message}`) } catch {}
+          }
+        }
+      }
+
+      function pushSample(live, tps, now) {
+        const t = Math.max(0, now - live.startedAt)
+        const last = live.samples[live.samples.length - 1]
+        if (last && t - last.t < 220) {
+          last.v = Math.max(last.v, tps)
+          return
+        }
+        live.samples.push({ t, v: tps })
+        if (live.samples.length > MAX_SAMPLES) {
+          const compacted = []
+          for (let index = 0; index < live.samples.length; index += 2) {
+            const a = live.samples[index]
+            const b = live.samples[index + 1] || a
+            compacted.push({ t: b.t, v: Math.max(a.v, b.v) })
+          }
+          live.samples = compacted
+        }
+      }
+
+      function pruneMarks(live, now) {
+        const cutoff = now - WINDOW_MS
+        while (live.marks.length > 0 && live.marks[0].t < cutoff) live.marks.shift()
+      }
+
+      function computeWindowTps(live, now) {
+        pruneMarks(live, now)
+        if (!live.firstTokenAt) return 0
+        let tokens = 0
+        for (const mark of live.marks) tokens += mark.n
+        const windowStart = Math.max(live.firstTokenAt, now - WINDOW_MS)
+        const span = Math.max(320, now - windowStart)
+        return tokens > 0 ? tokens / (span / 1000) : 0
+      }
+
+      function tickLive(live) {
+        if (!live || live.finished) return
+        const now = Date.now()
+        live.tps = computeWindowTps(live, now)
+        if (finite(live.tps)) live.peakTps = Math.max(live.peakTps || 0, live.tps)
+        if (live.firstTokenAt && live.lastTokenAt > live.firstTokenAt && live.tokens > 0) {
+          const generation = (live.lastTokenAt - live.firstTokenAt) / 1000
+          live.avgTps = generation > 0.08 ? live.tokens / generation : null
+        }
+        live.ttftMs = live.firstTokenAt ? live.firstTokenAt - live.startedAt : null
+        pushSample(live, live.tps || 0, now)
+        emit('tick', {
+          type: 'tick',
+          id: live.id,
+          sessionId: live.sessionId,
+          tokens: live.tokens,
+          tps: Math.round((live.tps || 0) * 10) / 10,
+          avgTps: finite(live.avgTps) ? Math.round(live.avgTps * 10) / 10 : null,
+          peakTps: finite(live.peakTps) ? Math.round(live.peakTps * 10) / 10 : null,
+          ttftMs: finite(live.ttftMs) ? Math.round(live.ttftMs) : null,
+          elapsedMs: Math.max(0, now - live.startedAt),
+          sample: live.samples.length > 0 ? publicSample(live.samples[live.samples.length - 1]) : null,
+        })
+      }
+
+      function finishLive(live, status) {
+        if (!live || live.finished) return
+        live.finished = true
+        if (live.timer) {
+          clearInterval(live.timer)
+          live.timer = null
+        }
+        const endedAt = Date.now()
+        const outputTokens = count(live.usage?.outputTokens)
+        const tokens = outputTokens !== undefined && outputTokens > 0 ? outputTokens : live.tokens
+        const generationMs = live.firstTokenAt && live.lastTokenAt > live.firstTokenAt
+          ? live.lastTokenAt - live.firstTokenAt
+          : 0
+        const durationMs = Math.max(0, endedAt - live.startedAt)
+        const tps = generationMs > 40 && tokens > 0 ? tokens / (generationMs / 1000) : null
+        // Keep at least a small visible segment for very short generations.
+        const currentTps = live.tps || live.avgTps || tps || 0
+        const endT = Math.max(0, endedAt - live.startedAt)
+        if (live.samples.length === 0) {
+          live.samples.push({ t: 0, v: currentTps })
+          live.samples.push({ t: endT, v: currentTps })
+        } else {
+          const last = live.samples[live.samples.length - 1]
+          if (endT - last.t > 40) live.samples.push({ t: endT, v: currentTps })
+          else last.v = Math.max(last.v, currentTps)
+          if (live.samples.length === 1) live.samples.unshift({ t: 0, v: live.samples[0].v })
+        }
+        const attempt = {
+          id: live.id,
+          sessionId: live.sessionId,
+          provider: live.provider || '',
+          model: live.model || '',
+          startedAt: live.startedAt,
+          endedAt,
+          ttftMs: live.firstTokenAt ? live.firstTokenAt - live.startedAt : null,
+          durationMs,
+          generationMs: generationMs || durationMs,
+          tokens,
+          inputTokens: count(live.usage?.inputTokens),
+          tps,
+          avgTps: tps,
+          peakTps: live.peakTps || null,
+          status: status || 'done',
+          turn: live.turn,
+          step: live.step,
+          samples: live.samples.slice(-MAX_SAMPLES),
+        }
+        const session = ensureSession(live.sessionId)
+        if (session.live === live) session.live = null
+        addAttempt(attempt)
+        emit('end', {
+          type: 'end',
+          id: live.id,
+          sessionId: live.sessionId,
+          attempt: publicAttempt(attempt, true),
+          session: publicSessionMeta(session),
+        })
+        scheduleSave()
+      }
+
+      function wrapStream(options, next) {
+        let iterator
+        const sessionId = safeId(options?.sessionId)
+        if (!sessionId || options?.purpose) {
+          iterator = next()
+          return iterator
+        }
+        return (async function* wrapped() {
+          const live = {
+            id: uniqueId('s'),
+            sessionId,
+            provider: typeof options.provider === 'string' ? options.provider : '',
+            model: typeof options.model === 'string' ? options.model : '',
+            startedAt: Date.now(),
+            firstTokenAt: 0,
+            lastTokenAt: 0,
+            tokens: 0,
+            tps: 0,
+            avgTps: null,
+            peakTps: 0,
+            ttftMs: null,
+            marks: [],
+            samples: [],
+            usage: undefined,
+            finished: false,
+            timer: null,
+          }
+          const session = ensureSession(sessionId, {
+            model: live.model,
+            provider: live.provider,
+          })
+          live.turn = finite(session.currentTurn) ? session.currentTurn : undefined
+          if (session.live?.timer) finishLive(session.live, 'replaced')
+          session.live = live
+          activeSessionId = sessionId
+          emit('start', {
+            type: 'start',
+            sessionId,
+            session: publicSessionMeta(session),
+            live: publicLive(live),
+            activeSessionId,
+          })
+          live.timer = setInterval(() => tickLive(live), TICK_MS)
+          if (typeof live.timer.unref === 'function') live.timer.unref()
+          let status = 'done'
+          let completed = false
+          let source
+          try {
+            source = next()
+            for await (const chunk of source) {
+              const now = Date.now()
+              if (chunk && isTokenChunk(chunk)) {
+                live.tokens += 1
+                if (!live.firstTokenAt) live.firstTokenAt = now
+                live.lastTokenAt = now
+                live.marks.push({ t: now, n: 1 })
+                pruneMarks(live, now)
+                live.tps = computeWindowTps(live, now)
+                if (finite(live.tps)) live.peakTps = Math.max(live.peakTps, live.tps)
+                if (live.firstTokenAt && live.lastTokenAt > live.firstTokenAt) {
+                  const generation = (live.lastTokenAt - live.firstTokenAt) / 1000
+                  live.avgTps = generation > 0.08 ? live.tokens / generation : null
+                }
+              } else if (chunk && chunk.type === 'usage') {
+                live.usage = chunk.usage
+              } else if (chunk && chunk.type === 'finish') {
+                completed = true
+                status = chunk.reason && typeof chunk.reason.kind === 'string'
+                  ? chunk.reason.kind
+                  : 'done'
+              }
+              yield chunk
+            }
+          } catch (error) {
+            status = 'error'
+            throw error
+          } finally {
+            if (!completed && status === 'done') status = 'aborted'
+            finishLive(live, status)
+          }
+        })()
+      }
+
+      // ---- hydration & live session bookkeeping -----------------------------
+      function hydrateSession(session) {
+        const sessionId = safeId(session?.id)
+        if (!sessionId) return
+        let events
+        try {
+          events = typeof session.snapshotEvents === 'function'
+            ? session.snapshotEvents()
+            : typeof session.ownEvents === 'function'
+              ? session.ownEvents()
+              : []
+        } catch {
+          return
+        }
+        if (!Array.isArray(events) || events.length === 0) return
+        let header = null
+        for (const event of events) {
+          if (!event || typeof event !== 'object') continue
+          const type = event.type
+          if (type === 'turn/start') {
+            ensureSession(sessionId).currentTurn = finite(event.data?.turn) ? event.data.turn : 0
+            continue
+          }
+          if (type === 'turn/end') {
+            ensureSession(sessionId).currentTurn = 0
+            continue
+          }
+          if (type === 'request/header') {
+            const config = event.data?.header?.config
+            if (config) header = { provider: config.provider, model: config.model }
+            continue
+          }
+          if (type === 'session/title') {
+            const title = event.data?.title
+            if (typeof title === 'string' && title.trim()) {
+              const target = ensureSession(sessionId)
+              target.label = shortLabel(title, 42)
+            }
+            continue
+          }
+          if (type === 'user/message') {
+            const target = ensureSession(sessionId)
+            if (!target.label) {
+              const text = textOfContent(event.data?.message?.content ?? event.data?.content)
+              if (text) target.label = shortLabel(text)
+            }
+            continue
+          }
+          if (type !== 'assistant/message' && type !== 'assistant/attempt') continue
+          const stream = event.data?.stream
+          if (!Array.isArray(stream) || stream.length === 0) continue
+          const derived = deriveFromStream(stream, event.time)
+          if (!derived || derived.tokens <= 0) continue
+          const usage = event.data?.usage
+          const outputTokens = usage?.outputTokens
+          const tokens = count(outputTokens) > 0 ? outputTokens : derived.tokens
+          const exactGeneration = derived.generationMs || 1
+          const attempt = {
+            id: uniqueId('h'),
+            sessionId,
+            provider: header?.provider || '',
+            model: header?.model || '',
+            startedAt: derived.firstTime,
+            endedAt: derived.lastTime,
+            ttftMs: null,
+            durationMs: derived.durationMs,
+            generationMs: derived.generationMs,
+            tokens,
+            inputTokens: count(usage?.inputTokens) ?? derived.inputTokens,
+            tps: derived.tps,
+            peakTps: null,
+            status: type === 'assistant/attempt'
+              ? (derived.finishKind || 'failed')
+              : (derived.finishKind || 'done'),
+            turn: finite(event.data?.turn) ? event.data.turn : undefined,
+            step: finite(event.data?.step) ? event.data.step : undefined,
+            historical: true,
+            samples: derived.samples || [],
+          }
+          if (attempt.tps === null && tokens > 0 && exactGeneration > 40) {
+            attempt.tps = tokens / (exactGeneration / 1000)
+          }
+          addAttempt(attempt, { broadcast: false })
+        }
+        trimSessions()
+      }
+
+      function hydrateExistingSessions() {
+        try {
+          const list = ctx.sessions?.list?.()
+          if (!Array.isArray(list)) return
+          for (const session of list) {
+            try { hydrateSession(session) } catch {}
+          }
+          if (!activeSessionId) {
+            let newest = null
+            for (const session of sessions.values()) {
+              if (!newest || session.updatedAt > newest.updatedAt) newest = session
+            }
+            if (newest) activeSessionId = newest.id
+          }
+        } catch {}
+      }
+
+      // ---- web routes -------------------------------------------------------
+      function parseHost(req) {
+        const host = String(req.headers?.host || '').toLowerCase()
+        const hostname = host.startsWith('[')
+          ? host.slice(0, host.indexOf(']') + 1)
+          : host.split(':')[0]
+        return { host, hostname }
+      }
+
+      function deny(res, status = 403) {
+        try {
+          res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' })
+          res.end('forbidden')
+        } catch {}
+        return true
+      }
+
+      function rejected(req, res) {
+        try {
+          const { host, hostname } = parseHost(req)
+          if (!host) return deny(res)
+          if (!['127.0.0.1', 'localhost', '[::1]', '::1'].includes(hostname)) return deny(res)
+          const origin = req.headers?.origin
+          if (origin) {
+            const parsed = new URL(String(origin))
+            if (parsed.host.toLowerCase() !== host) return deny(res)
+          }
+          if (String(req.headers?.['sec-fetch-site'] || '') === 'cross-site') return deny(res)
+          const connection = ctx.get?.('connection')
+          if (connection && typeof connection.requestRejection === 'function') {
+            const code = connection.requestRejection(req)
+            if (code !== undefined && code !== null && code !== false) {
+              return deny(res, typeof code === 'number' ? code : 403)
+            }
+          }
+        } catch {
+          return deny(res)
+        }
+        return false
+      }
+
+      function register(route) {
+        const inner = route.handler
+        const wrapped = {
+          ...route,
+          handler: async (req, res) => {
+            if (rejected(req, res)) return
+            try {
+              return await inner(req, res)
+            } catch (error) {
+              try { ctx.logger?.warn?.(`[dsh-speedometer] route ${route.path} failed: ${error.message}`) } catch {}
+              if (!res.headersSent) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' })
+                res.end(JSON.stringify({ error: 'internal' }))
+              } else {
+                try { res.end() } catch {}
+              }
+            }
+          },
+        }
+        return ctx.webServer.register(wrapped)
+      }
+
+      function json(res, status, payload) {
+        const body = JSON.stringify(payload)
+        res.writeHead(status, {
+          'Content-Type': 'application/json; charset=utf-8',
+          'Cache-Control': 'no-store',
+          'Content-Length': Buffer.byteLength(body),
+        })
+        res.end(body)
+      }
+
+      function widgetJs() {
+        try {
+          return fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), 'widget.js'), 'utf8')
+        } catch {
+          return '/* dsh-speedometer widget.js not found */'
+        }
+      }
+
+      function serveWidget(req, res) {
+        const body = widgetJs()
+        res.writeHead(200, {
+          'Content-Type': 'application/javascript; charset=utf-8',
+          'Cache-Control': 'no-store',
+        })
+        res.end(body)
+      }
+
+      function serveState(req, res) {
+        if (req.method !== 'GET' && req.method !== 'HEAD') return json(res, 405, { error: 'method' })
+        json(res, 200, publicState())
+      }
+
+      function serveEvents(req, res) {
+        if (req.method !== 'GET') return json(res, 405, { error: 'method' })
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream; charset=utf-8',
+          'Cache-Control': 'no-cache, no-transform',
+          Connection: 'keep-alive',
+          'X-Accel-Buffering': 'no',
+        })
+        try { res.flushHeaders?.() } catch {}
+        res.write('retry: 1800\n\n')
+        clients.add(res)
+        writeSse(res, 'state', publicState())
+        const heartbeat = setInterval(() => {
+          try { res.write(': ping\n\n') } catch { clients.delete(res) }
+        }, 15000)
+        if (typeof heartbeat.unref === 'function') heartbeat.unref()
+        const cleanup = () => {
+          clearInterval(heartbeat)
+          clients.delete(res)
+        }
+        req.on?.('close', cleanup)
+        req.on?.('aborted', cleanup)
+        res.on?.('close', cleanup)
+      }
+
+      // ---- wire it up -------------------------------------------------------
+      loadHistory()
+      hydrateExistingSessions()
+
+      disposers.push(register({ kind: 'exact', path: WIDGET_ROUTE, handler: serveWidget }))
+      disposers.push(register({ kind: 'exact', path: STATE_ROUTE, handler: serveState }))
+      disposers.push(register({ kind: 'exact', path: EVENTS_ROUTE, handler: serveEvents }))
+      disposers.push(register({
+        kind: 'exact',
+        path: `${ROUTE}/health`,
+        handler: (req, res) => json(res, 200, { ok: true, version: VERSION }),
+      }))
+
+      // Browser form: the index HTML is rendered by the host, so append the
+      // script tag here. The desktop shell uses the index-inject row above.
+      disposers.push(ctx.webServer.tapIndex((html) => {
+        try {
+          if (typeof html !== 'string' || html.indexOf(WIDGET_ROUTE) !== -1) return html
+          const tag = `<script defer src="${WIDGET_ROUTE}"></script>`
+          return html.indexOf('</body>') !== -1
+            ? html.replace('</body>', `${tag}</body>`)
+            : html + tag
+        } catch {
+          return html
+        }
+      }))
+
+      disposers.push(ctx.on('llm/stream', (options, next) => wrapStream(options, next)))
+
+      disposers.push(ctx.on('session/event', (session, event) => {
+        try {
+          const sessionId = safeId(session?.id)
+          if (!sessionId) return
+          if (event?.type === 'session/title') {
+            const title = event.data?.title
+            if (typeof title === 'string' && title.trim()) {
+              const target = ensureSession(sessionId)
+              target.label = shortLabel(title, 42)
+              target.updatedAt = Date.now()
+              emit('session', { type: 'session', session: publicSessionMeta(target), activeSessionId })
+            }
+            return
+          }
+          if (event?.type === 'user/message') {
+            const target = ensureSession(sessionId)
+            if (!target.label) {
+              const text = textOfContent(event.data?.message?.content ?? event.data?.content)
+              if (text) target.label = shortLabel(text)
+            }
+            if (!target.attempts.length && !target.live && sessionId !== activeSessionId) {
+              activeSessionId = sessionId
+              emit('active', { type: 'active', activeSessionId })
+            }
+            return
+          }
+          if (event?.type === 'turn/start') {
+            const target = ensureSession(sessionId)
+            target.currentTurn = finite(event.data?.turn) ? event.data.turn : 0
+            return
+          }
+          if (event?.type === 'turn/end') {
+            const target = ensureSession(sessionId)
+            target.currentTurn = 0
+            return
+          }
+          if (event?.type === 'session/disposed') {
+            try { sessions.delete(sessionId) } catch {}
+          }
+        } catch {}
+      }))
+
+      // The profile can add sessions after this plugin starts; hydrate an empty
+      // session once so titles and transcript labels are available.
+      disposers.push(ctx.on('session/created', (session) => {
+        try { hydrateSession(session) } catch {}
+      }))
+
+      disposers.push(ctx.effect(() => () => {
+        for (const dispose of disposers) {
+          try { dispose() } catch {}
+        }
+        for (const session of sessions.values()) {
+          if (session.live?.timer) clearInterval(session.live.timer)
+        }
+        for (const res of clients) {
+          try { res.end() } catch {}
+        }
+        clients.clear()
+        if (saveTimer) clearTimeout(saveTimer)
+        saveHistory()
+      }))
+
+      // Expose a small diagnostic surface for the host log.
+      try {
+        ctx.logger?.info?.(`[dsh-speedometer] v${VERSION} ready (${sessions.size} session(s) hydrated)`)
+      } catch {}
+    })
+  },
+}