useful-pi-extensions 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "useful-pi-extensions",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "A small collection of pi extensions, installed with one command — a labelled status line with context pressure, cache, cost, effort, TTFT and tokens/sec.",
   "keywords": [
     "bun",

package/packages/statusline/extensions/statusline/index.ts

@@ -39,6 +39,8 @@ import {
   pair,
   row,
   shortenPath,
+  ttftDisplay,
+  ttftMs,
   USD,
   type Currency,
 } from './render.ts'
@@ -46,6 +48,8 @@ import {
 const LIVE_RENDER_MS = 200
 const WINDOW_MS = 2000
 const MIN_SAMPLE_MS = 200
+/** How often the waiting TTFT slot ticks while a request is in flight. */
+const TICK_MS = 250
 /** Pi's own estimateTokens() heuristic, used only until a real ratio is known. */
 const FALLBACK_TOKENS_PER_CHAR = 0.25
 
@@ -185,8 +189,9 @@ export default function (pi: ExtensionAPI) {
   let reading: { rate: number; exact: boolean; ttftMs: number | null } | null = null
 
   let chars = 0
-  let stepStartedAt = 0
+  let requestAt: number | null = null
   let firstTokenAt: number | null = null
+  let ticker: ReturnType<typeof setInterval> | null = null
   let windowAt = 0
   let windowTokens = 0
   let renderedAt = 0
@@ -199,11 +204,31 @@ export default function (pi: ExtensionAPI) {
     renderedAt = 0
   }
 
-  function publish(rate: number, exact: boolean, ttftMs: number | null): void {
-    reading = { rate, exact, ttftMs }
+  function publish(rate: number, exact: boolean, ttft: number | null): void {
+    reading = { rate, exact, ttftMs: ttft }
     requestRender?.()
   }
 
+  /** Stops the live count; a frozen TTFT needs no clock. */
+  function stopTicker(): void {
+    if (ticker !== null) {
+      clearInterval(ticker)
+      ticker = null
+    }
+  }
+
+  /** Ticks the footer while a request is in flight, until the first token lands or the turn ends. */
+  function startTicker(): void {
+    if (ticker !== null) return
+    ticker = setInterval(() => {
+      if (requestAt === null || firstTokenAt !== null) {
+        stopTicker()
+        return
+      }
+      requestRender?.()
+    }, TICK_MS)
+  }
+
   function installFooter(ctx: ExtensionContext): void {
     ctx.ui.setFooter((tui, theme, footerData: ReadonlyFooterDataProvider) => {
       requestRender = () => tui.requestRender()
@@ -235,7 +260,12 @@ export default function (pi: ExtensionAPI) {
           const model = ctx.model?.id ?? 'no model'
           const row2Parts = [theme.fg('accent', model)]
           if (ctx.thinkingLevel) row2Parts.push(pair(theme, 'Effort', ctx.thinkingLevel, 'muted'))
-          if (reading) {
+          const waiting = ttftDisplay(requestAt, firstTokenAt, Date.now())
+          if (waiting !== null) {
+            // The clock is running: this wait has no reading yet, so the previous turn's
+            // throughput would only be mistaken for the current one.
+            row2Parts.push(pair(theme, 'TTFT', waiting.text, 'muted'))
+          } else if (reading) {
             if (reading.ttftMs !== null)
               row2Parts.push(pair(theme, 'TTFT', formatLatency(reading.ttftMs), 'muted'))
             row2Parts.push(
@@ -283,9 +313,28 @@ export default function (pi: ExtensionAPI) {
     })
   }
 
+  // A run that ends without a first token (abort, provider error) must not leave a clock counting
+  // against a request that is no longer in flight.
+  pi.on('turn_end', async () => {
+    requestAt = null
+    stopTicker()
+  })
+
+  pi.on('agent_end', async () => {
+    requestAt = null
+    stopTicker()
+  })
+
+  pi.on('agent_settled', async () => {
+    requestAt = null
+    stopTicker()
+  })
+
   pi.on('session_start', async (_event, ctx) => {
     ratio = seedRatio(ctx)
     reading = null
+    requestAt = null
+    stopTicker()
     resetStream()
     currency = await loadCurrency((message) => ctx.ui.notify(message, 'warning'))
     installFooter(ctx)
@@ -294,7 +343,27 @@ export default function (pi: ExtensionAPI) {
   pi.on('message_start', async (event) => {
     if (event.message.role !== 'assistant') return
     resetStream()
-    stepStartedAt = Date.now()
+  })
+
+  // TTFT's request anchor, from the agent loop in pi's docs: turn_start opens the LLM call and
+  // before_provider_request is the last thing pi does before the wire. message_start is not that
+  // moment, and anchoring there made a first token that arrived early read as a clamped 0ms.
+  pi.on('turn_start', async () => {
+    requestAt = null
+  })
+
+  pi.on('before_provider_request', async () => {
+    requestAt = Date.now()
+  })
+
+  pi.on('turn_start', async () => {
+    requestAt = null
+    stopTicker()
+  })
+
+  pi.on('before_provider_request', async () => {
+    requestAt = Date.now()
+    startTicker()
   })
 
   pi.on('message_update', async (event) => {
@@ -310,7 +379,10 @@ export default function (pi: ExtensionAPI) {
     }
 
     const now = Date.now()
-    if (firstTokenAt === null) firstTokenAt = now
+    if (firstTokenAt === null) {
+      firstTokenAt = now
+      stopTicker()
+    }
     chars += delta.delta.length
 
     const tokens = chars * (ratio ?? FALLBACK_TOKENS_PER_CHAR)
@@ -326,7 +398,7 @@ export default function (pi: ExtensionAPI) {
     const rate =
       windowMs > 0 ? ((tokens - windowTokens) / windowMs) * 1000 : (tokens / decodeMs) * 1000
     renderedAt = now
-    publish(rate, false, firstTokenAt - stepStartedAt)
+    publish(rate, false, ttftMs(requestAt, firstTokenAt))
   })
 
   pi.on('message_end', async (event) => {
@@ -341,10 +413,13 @@ export default function (pi: ExtensionAPI) {
     }
 
     const decodeMs = firstTokenAt !== null ? Date.now() - firstTokenAt : 0
-    const ttftMs = firstTokenAt !== null ? firstTokenAt - stepStartedAt : null
+    const measured = ttftMs(requestAt, firstTokenAt)
     const tokens = output > 0 ? output : totalChars * (ratio ?? FALLBACK_TOKENS_PER_CHAR)
-    if (ttftMs !== null && decodeMs >= MIN_SAMPLE_MS)
-      publish((tokens / decodeMs) * 1000, output > 0, ttftMs)
+    if (measured !== null && decodeMs >= MIN_SAMPLE_MS)
+      publish((tokens / decodeMs) * 1000, output > 0, measured)
+    // Null it with the stream: a request that has produced its message is no longer in flight, and
+    // a stale anchor would let the live branch count against nothing until the next turn.
+    requestAt = null
     resetStream()
   })
 }

package/packages/statusline/extensions/statusline/render.ts

@@ -66,6 +66,51 @@ export function formatLatency(ms: number): string {
   return `${seconds < 10 ? Math.round(seconds * 10) / 10 : Math.round(seconds)}s`
 }
 
+/**
+ * TTFT from its two wall-clock anchors: the moment the request was dispatched, and the first
+ * streamed delta.
+ *
+ * The guard is the point. Both anchors come from extension events whose ordering around a stream is
+ * not guaranteed, and a first token that appears to precede its own request yields a negative that
+ * `formatLatency` would clamp to `0ms` — a confident fake where an honest absence belongs.
+ *
+ * @returns The milliseconds between the two, or null when they do not line up.
+ */
+export function ttftMs(requestAt: number | null, firstTokenAt: number | null): number | null {
+  if (requestAt === null || firstTokenAt === null) return null
+  return firstTokenAt > requestAt ? firstTokenAt - requestAt : null
+}
+
+/** What the TTFT slot renders, and whether the clock is still running. */
+export interface TtftDisplay {
+  text: string
+  live: boolean
+}
+
+/**
+ * The TTFT slot, for all three phases of a request.
+ *
+ * While the request is in flight the slot counts up (`~2s`, the `~` marking an unfinished wait, the
+ * same convention as the tok/s estimate) — a slow first byte is something you watch happen, not a
+ * number you are told about afterwards. The moment the first token lands the count freezes into the
+ * exact value. With no request in flight there is nothing to show.
+ *
+ * @param now - The clock, passed in so every branch stays a function of its arguments.
+ */
+export function ttftDisplay(
+  requestAt: number | null,
+  firstTokenAt: number | null,
+  now: number,
+): TtftDisplay | null {
+  if (requestAt === null) return null
+  if (firstTokenAt === null) {
+    if (now < requestAt) return null
+    return { text: `~${formatLatency(now - requestAt)}`, live: true }
+  }
+  const measured = ttftMs(requestAt, firstTokenAt)
+  return measured === null ? null : { text: formatLatency(measured), live: false }
+}
+
 /** Home-relative path, or the absolute path when it is outside the home directory. */
 export function formatCwd(cwd: string): string {
   const home = homedir()