oc-metricboard 0.1.18 → 0.1.19

package/dist/collector.js

@@ -1,10 +1,10 @@
-import { getDisplayInputTokens, getDisplayOutputTokens, getTtft } from "./metrics";
+import { credibleTps, getDisplayInputTokens, getDisplayOutputTokens, getTtft, MAX_CREDIBLE_TPS } from "./metrics";
 import { registerEventHandlers } from "./event-handlers";
 import { hydrateSession, isHydrationApi, callWithFallback } from "./session-hydration";
 import { createSessionTree } from "./session-tree";
 import { getScopeElapsedMs, getSessionElapsedMs, startSessionTiming, stopSessionTiming } from "./session-timing";
 import { clearLiveSpeed, getLiveTps } from "./live-speed";
-import { getTurnTtft, liveRequestOutput, turnInputTokens } from "./turn-state";
+import { getTurnTtft, liveRequestOutput, toolOverlapMs, turnInputTokens } from "./turn-state";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -358,8 +358,21 @@ export function createCollector(api, config, log) {
                     : latest.isStreaming || latestLastActivity === null ? now : latestLastActivity;
                 const saneStart = genStart !== null && Number.isFinite(genStart) && genStart >= 0 && genStart <= now;
                 const saneEnd = genEnd !== null && Number.isFinite(genEnd) && genEnd >= 0 && genEnd <= now + 60_000;
+                let primary = null;
                 if (frTokens > 0 && saneStart && saneEnd && genEnd > genStart) {
-                    displayTps = Math.round((frTokens / ((genEnd - genStart) / 1000)) * 10) / 10;
+                    primary = Math.round((frTokens / ((genEnd - genStart) / 1000)) * 10) / 10;
+                }
+                // Same turn-anchored fallback as the main aggregate, using the latest
+                // request's own turn.
+                const latestTurn = state.turns.get(latest.sessionID);
+                if ((primary === null || primary > MAX_CREDIBLE_TPS) && latestTurn && frTokens > 0) {
+                    const turnEnd = completeTime ?? latestLastActivity ?? now;
+                    const turnWindow = turnEnd - latestTurn.turnStartTime
+                        - toolOverlapMs(latestTurn, latestTurn.turnStartTime, turnEnd);
+                    displayTps = credibleTps(frTokens, turnWindow) ?? primary;
+                }
+                else {
+                    displayTps = primary;
                 }
             }
             result.push({
@@ -506,8 +519,22 @@ export function createCollector(api, config, log) {
                     : foregroundActive || foregroundLastActivity === null ? now : foregroundLastActivity;
                 const saneStart = genStart !== null && Number.isFinite(genStart) && genStart >= 0 && genStart <= now;
                 const saneEnd = genEnd !== null && Number.isFinite(genEnd) && genEnd >= 0 && genEnd <= now + 60_000;
+                let primary = null;
                 if (frTokens > 0 && saneStart && saneEnd && genEnd > genStart) {
-                    displayTps = Math.round((frTokens / ((genEnd - genStart) / 1000)) * 10) / 10;
+                    primary = Math.round((frTokens / ((genEnd - genStart) / 1000)) * 10) / 10;
+                }
+                // Fall back to the turn-anchored window when the per-step window
+                // implies a physically incredible rate: per-delta times may be
+                // delivery-stamped (batched flushes), while turn admission, step
+                // boundaries, and tool spans use discrete truthful anchors.
+                if ((primary === null || primary > MAX_CREDIBLE_TPS) && foregroundTurn && frTokens > 0) {
+                    const turnEnd = completeTime ?? foregroundLastActivity ?? now;
+                    const turnWindow = turnEnd - foregroundTurn.turnStartTime
+                        - toolOverlapMs(foregroundTurn, foregroundTurn.turnStartTime, turnEnd);
+                    displayTps = credibleTps(frTokens, turnWindow) ?? primary;
+                }
+                else {
+                    displayTps = primary;
                 }
             }
             // NEW: Build per-model breakdown for tree scope

package/dist/event-handlers.js

@@ -5,7 +5,7 @@ import { applyAssistantTokens, applySessionModel, hasPositiveAssistantTokens, me
 import { completeRequest, currentRequest } from "./request-state";
 import { eventAggregateID, eventID, eventPerfTime, eventProperties, eventProperty, statusType, stringEventProperty } from "./event-bus";
 import { clearLiveSpeed, resetLiveSpeed } from "./live-speed";
-import { ensureTurn, retireRequestIntoTurn, startTurn } from "./turn-state";
+import { ensureTurn, recordToolCalled, recordToolSettled, retireRequestIntoTurn, startTurn } from "./turn-state";
 export function registerEventHandlers(ctx) {
     const { api, config, log, state, actions } = ctx;
     const disposers = [];
@@ -157,6 +157,33 @@ export function registerEventHandlers(ctx) {
     });
     on("session.next.text.delta", (event) => applyAssistantDelta(ctx, event));
     on("session.next.reasoning.delta", (event) => applyAssistantDelta(ctx, event));
+    // ── tool execution spans (V2 tool.* events; V1 has none) ──
+    // Feeds per-turn tool intervals so frozen TPS can subtract tool time from
+    // the turn-anchored window. Unknown shapes are ignored defensively.
+    on("session.tool.called", (event) => {
+        const sessionID = stringEventProperty(event, "sessionID");
+        if (sessionID.length === 0)
+            return;
+        recordEventAlias(event, sessionID);
+        recordToolCalled(state.turns, sessionID, stringEventProperty(event, "id"), eventPerfTime(event, performance.now()));
+        actions.notify();
+    });
+    on("session.tool.success", (event) => {
+        const sessionID = stringEventProperty(event, "sessionID");
+        if (sessionID.length === 0)
+            return;
+        recordEventAlias(event, sessionID);
+        recordToolSettled(state.turns, sessionID, stringEventProperty(event, "id"), eventPerfTime(event, performance.now()));
+        actions.notify();
+    });
+    on("session.tool.failed", (event) => {
+        const sessionID = stringEventProperty(event, "sessionID");
+        if (sessionID.length === 0)
+            return;
+        recordEventAlias(event, sessionID);
+        recordToolSettled(state.turns, sessionID, stringEventProperty(event, "id"), eventPerfTime(event, performance.now()));
+        actions.notify();
+    });
     on("session.next.step.ended", (event) => {
         const sessionID = stringEventProperty(event, "sessionID");
         const fallbackMessageID = sessionID ? state.assistantMessageIds.get(sessionID) ?? eventID(event) : eventID(event);

package/dist/metrics.js

@@ -113,6 +113,22 @@ export function getTtft(m) {
         return null;
     return gateTtft(m.firstTokenTime - m.requestStartTime);
 }
+/**
+ * Upper bound for a believable token rate. Mirrors the live-TPS sanity gate:
+ * per-delta times may be delivery-stamped (batched flushes), collapsing the
+ * generation window to milliseconds and inflating the quotient absurdly
+ * (e.g. 61 tokens / 42ms = 1450 t/s — physically impossible decoding).
+ * Windows implying a faster rate fall back to turn-anchored timing.
+ */
+export const MAX_CREDIBLE_TPS = 300;
+export function credibleTps(tokens, windowMs) {
+    if (!(tokens > 0) || !(windowMs > 0))
+        return null;
+    const tps = Math.round((tokens / (windowMs / 1000)) * 10) / 10;
+    if (!Number.isFinite(tps) || tps < 0 || tps > MAX_CREDIBLE_TPS)
+        return null;
+    return tps;
+}
 /**
  * Calculate average token speed (tokens/second).
  * Based on cumulative streaming time (now - firstTokenTime).

package/dist/tui-v2.js

@@ -64,6 +64,9 @@ const V2_EVENT_MAP = {
     "session.next.reasoning.delta": "session.reasoning.delta",
     "session.next.step.started": "session.step.started",
     "session.next.step.ended": "session.step.ended",
+    "session.tool.called": "session.tool.called",
+    "session.tool.success": "session.tool.success",
+    "session.tool.failed": "session.tool.failed",
 };
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/turn-state.js

@@ -12,6 +12,7 @@ export function createTurnMetrics(sessionID, now) {
         hasStickyContextTokens: false,
         stickyCacheReadTokens: 0,
         hasStickyCacheReadTokens: false,
+        toolIntervals: [],
         isComplete: false,
     };
 }
@@ -78,6 +79,68 @@ export function recordTurnFirstToken(turn, now) {
     if (turn.firstTokenTime === null)
         turn.firstTokenTime = now;
 }
+/**
+ * Record a tool execution span on the session's turn. Tools in one turn may
+ * overlap (parallel calls), so every span is kept and the union is computed
+ * at query time — a plain sum would double-count overlaps.
+ */
+export function recordToolCalled(turns, sessionID, toolID, now) {
+    const turn = ensureTurn(turns, sessionID, now);
+    turn.toolIntervals.push({ id: toolID, start: now, end: null });
+}
+export function recordToolSettled(turns, sessionID, toolID, now) {
+    const turn = turns.get(sessionID);
+    if (!turn)
+        return;
+    if (toolID) {
+        const open = turn.toolIntervals.find((interval) => interval.id === toolID && interval.end === null);
+        if (open) {
+            open.end = Math.max(now, open.start);
+            return;
+        }
+    }
+    // Unknown id (or unsettled shape): close the most recent open span so a
+    // lost settle event cannot leak an infinite interval.
+    for (let i = turn.toolIntervals.length - 1; i >= 0; i--) {
+        if (turn.toolIntervals[i].end === null) {
+            turn.toolIntervals[i].end = Math.max(now, turn.toolIntervals[i].start);
+            return;
+        }
+    }
+}
+/**
+ * Milliseconds of tool execution overlapping [from, to], unioned so parallel
+ * tool calls count once. Open spans are clamped at `to`.
+ */
+export function toolOverlapMs(turn, from, to) {
+    if (!turn || to <= from)
+        return 0;
+    const spans = [];
+    for (const interval of turn.toolIntervals) {
+        const start = Math.max(interval.start, from);
+        const end = Math.min(interval.end ?? to, to);
+        if (end > start)
+            spans.push({ start, end });
+    }
+    spans.sort((a, b) => a.start - b.start);
+    let total = 0;
+    let cursor = null;
+    let cursorEnd = 0;
+    for (const span of spans) {
+        if (cursor === null || span.start > cursorEnd) {
+            if (cursor !== null)
+                total += cursorEnd - cursor;
+            cursor = span.start;
+            cursorEnd = span.end;
+        }
+        else if (span.end > cursorEnd) {
+            cursorEnd = span.end;
+        }
+    }
+    if (cursor !== null)
+        total += cursorEnd - cursor;
+    return total;
+}
 /**
  * Turn-level TTFT (user message → first token), gated. Falls back to the
  * supplied per-request TTFT when the turn has no first-token timing. This is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oc-metricboard",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "OpenCode TUI sidebar plugin showing real-time LLM metrics (TPS, TTFT, tokens) with sub-agent × model breakdown",
   "keywords": [
     "opencode",

package/src/collector.ts

@@ -1,6 +1,6 @@
 import type { TuiPluginApi } from "@opencode-ai/plugin/tui"
 import type { BarConfig, CacheReadCompleteness, MetricsAggregate, MetricsScope, ModelMetrics, RequestMetrics } from "./types"
-import { getDisplayInputTokens, getDisplayOutputTokens, getTtft } from "./metrics"
+import { credibleTps, getDisplayInputTokens, getDisplayOutputTokens, getTtft, MAX_CREDIBLE_TPS } from "./metrics"
 import { registerEventHandlers } from "./event-handlers"
 import type { CollectorState } from "./collector-state"
 import type { MetricsEventApi } from "./event-bus"
@@ -8,7 +8,7 @@ import { hydrateSession, isHydrationApi, callWithFallback, type HydrationApi } f
 import { createSessionTree } from "./session-tree"
 import { getScopeElapsedMs, getSessionElapsedMs, startSessionTiming, stopSessionTiming } from "./session-timing"
 import { clearLiveSpeed, getLiveTps } from "./live-speed"
-import { getTurnTtft, liveRequestOutput, turnInputTokens } from "./turn-state"
+import { getTurnTtft, liveRequestOutput, toolOverlapMs, turnInputTokens } from "./turn-state"
 
 export type MetricsListener = () => void
 type MetricsHydrationApi = MetricsEventApi & HydrationApi
@@ -426,8 +426,20 @@ export function createCollector(
           : latest.isStreaming || latestLastActivity === null ? now : latestLastActivity
         const saneStart = genStart !== null && Number.isFinite(genStart) && genStart >= 0 && genStart <= now
         const saneEnd = genEnd !== null && Number.isFinite(genEnd) && genEnd >= 0 && genEnd <= now + 60_000
+        let primary: number | null = null
         if (frTokens > 0 && saneStart && saneEnd && genEnd > genStart) {
-          displayTps = Math.round((frTokens / ((genEnd - genStart) / 1000)) * 10) / 10
+          primary = Math.round((frTokens / ((genEnd - genStart) / 1000)) * 10) / 10
+        }
+        // Same turn-anchored fallback as the main aggregate, using the latest
+        // request's own turn.
+        const latestTurn = state.turns.get(latest.sessionID)
+        if ((primary === null || primary > MAX_CREDIBLE_TPS) && latestTurn && frTokens > 0) {
+          const turnEnd = completeTime ?? latestLastActivity ?? now
+          const turnWindow = turnEnd - latestTurn.turnStartTime
+            - toolOverlapMs(latestTurn, latestTurn.turnStartTime, turnEnd)
+          displayTps = credibleTps(frTokens, turnWindow) ?? primary
+        } else {
+          displayTps = primary
         }
       }
 
@@ -580,8 +592,21 @@ export function createCollector(
           : foregroundActive || foregroundLastActivity === null ? now : foregroundLastActivity
         const saneStart = genStart !== null && Number.isFinite(genStart) && genStart >= 0 && genStart <= now
         const saneEnd = genEnd !== null && Number.isFinite(genEnd) && genEnd >= 0 && genEnd <= now + 60_000
+        let primary: number | null = null
         if (frTokens > 0 && saneStart && saneEnd && genEnd > genStart) {
-          displayTps = Math.round((frTokens / ((genEnd - genStart) / 1000)) * 10) / 10
+          primary = Math.round((frTokens / ((genEnd - genStart) / 1000)) * 10) / 10
+        }
+        // Fall back to the turn-anchored window when the per-step window
+        // implies a physically incredible rate: per-delta times may be
+        // delivery-stamped (batched flushes), while turn admission, step
+        // boundaries, and tool spans use discrete truthful anchors.
+        if ((primary === null || primary > MAX_CREDIBLE_TPS) && foregroundTurn && frTokens > 0) {
+          const turnEnd = completeTime ?? foregroundLastActivity ?? now
+          const turnWindow = turnEnd - foregroundTurn.turnStartTime
+            - toolOverlapMs(foregroundTurn, foregroundTurn.turnStartTime, turnEnd)
+          displayTps = credibleTps(frTokens, turnWindow) ?? primary
+        } else {
+          displayTps = primary
         }
       }
 

package/src/event-handlers.ts

@@ -14,7 +14,7 @@ import { completeRequest, currentRequest } from "./request-state"
 import { eventAggregateID, eventID, eventPerfTime, eventProperties, eventProperty, statusType, stringEventProperty } from "./event-bus"
 import type { EventHandlerContext } from "./collector-state"
 import { clearLiveSpeed, resetLiveSpeed } from "./live-speed"
-import { ensureTurn, retireRequestIntoTurn, startTurn } from "./turn-state"
+import { ensureTurn, recordToolCalled, recordToolSettled, retireRequestIntoTurn, startTurn } from "./turn-state"
 
 export function registerEventHandlers(ctx: EventHandlerContext): Array<() => void> {
   const { api, config, log, state, actions } = ctx
@@ -169,6 +169,33 @@ export function registerEventHandlers(ctx: EventHandlerContext): Array<() => voi
 
   on("session.next.reasoning.delta", (event) => applyAssistantDelta(ctx, event))
 
+  // ── tool execution spans (V2 tool.* events; V1 has none) ──
+  // Feeds per-turn tool intervals so frozen TPS can subtract tool time from
+  // the turn-anchored window. Unknown shapes are ignored defensively.
+  on("session.tool.called", (event) => {
+    const sessionID = stringEventProperty(event, "sessionID")
+    if (sessionID.length === 0) return
+    recordEventAlias(event, sessionID)
+    recordToolCalled(state.turns, sessionID, stringEventProperty(event, "id"), eventPerfTime(event, performance.now()))
+    actions.notify()
+  })
+
+  on("session.tool.success", (event) => {
+    const sessionID = stringEventProperty(event, "sessionID")
+    if (sessionID.length === 0) return
+    recordEventAlias(event, sessionID)
+    recordToolSettled(state.turns, sessionID, stringEventProperty(event, "id"), eventPerfTime(event, performance.now()))
+    actions.notify()
+  })
+
+  on("session.tool.failed", (event) => {
+    const sessionID = stringEventProperty(event, "sessionID")
+    if (sessionID.length === 0) return
+    recordEventAlias(event, sessionID)
+    recordToolSettled(state.turns, sessionID, stringEventProperty(event, "id"), eventPerfTime(event, performance.now()))
+    actions.notify()
+  })
+
   on("session.next.step.ended", (event) => {
     const sessionID = stringEventProperty(event, "sessionID")
     const fallbackMessageID = sessionID ? state.assistantMessageIds.get(sessionID) ?? eventID(event) : eventID(event)

package/src/metrics.ts

@@ -127,6 +127,22 @@ export function getTtft(m: RequestMetrics): number | null {
   return gateTtft(m.firstTokenTime - m.requestStartTime)
 }
 
+/**
+ * Upper bound for a believable token rate. Mirrors the live-TPS sanity gate:
+ * per-delta times may be delivery-stamped (batched flushes), collapsing the
+ * generation window to milliseconds and inflating the quotient absurdly
+ * (e.g. 61 tokens / 42ms = 1450 t/s — physically impossible decoding).
+ * Windows implying a faster rate fall back to turn-anchored timing.
+ */
+export const MAX_CREDIBLE_TPS = 300
+
+export function credibleTps(tokens: number, windowMs: number): number | null {
+  if (!(tokens > 0) || !(windowMs > 0)) return null
+  const tps = Math.round((tokens / (windowMs / 1000)) * 10) / 10
+  if (!Number.isFinite(tps) || tps < 0 || tps > MAX_CREDIBLE_TPS) return null
+  return tps
+}
+
 /**
  * Calculate average token speed (tokens/second).
  * Based on cumulative streaming time (now - firstTokenTime).

package/src/tui-v2.tsx

@@ -114,6 +114,9 @@ const V2_EVENT_MAP: Readonly<Record<string, string | null>> = {
     "session.next.reasoning.delta": "session.reasoning.delta",
     "session.next.step.started": "session.step.started",
     "session.next.step.ended": "session.step.ended",
+    "session.tool.called": "session.tool.called",
+    "session.tool.success": "session.tool.success",
+    "session.tool.failed": "session.tool.failed",
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {

package/src/turn-state.ts

@@ -14,6 +14,7 @@ export function createTurnMetrics(sessionID: string, now: number): TurnMetrics {
     hasStickyContextTokens: false,
     stickyCacheReadTokens: 0,
     hasStickyCacheReadTokens: false,
+    toolIntervals: [],
     isComplete: false,
   }
 }
@@ -95,6 +96,75 @@ export function recordTurnFirstToken(turn: TurnMetrics, now: number): void {
   if (turn.firstTokenTime === null) turn.firstTokenTime = now
 }
 
+/**
+ * Record a tool execution span on the session's turn. Tools in one turn may
+ * overlap (parallel calls), so every span is kept and the union is computed
+ * at query time — a plain sum would double-count overlaps.
+ */
+export function recordToolCalled(
+  turns: Map<string, TurnMetrics>,
+  sessionID: string,
+  toolID: string,
+  now: number,
+): void {
+  const turn = ensureTurn(turns, sessionID, now)
+  turn.toolIntervals.push({ id: toolID, start: now, end: null })
+}
+
+export function recordToolSettled(
+  turns: Map<string, TurnMetrics>,
+  sessionID: string,
+  toolID: string,
+  now: number,
+): void {
+  const turn = turns.get(sessionID)
+  if (!turn) return
+  if (toolID) {
+    const open = turn.toolIntervals.find((interval) => interval.id === toolID && interval.end === null)
+    if (open) {
+      open.end = Math.max(now, open.start)
+      return
+    }
+  }
+  // Unknown id (or unsettled shape): close the most recent open span so a
+  // lost settle event cannot leak an infinite interval.
+  for (let i = turn.toolIntervals.length - 1; i >= 0; i--) {
+    if (turn.toolIntervals[i]!.end === null) {
+      turn.toolIntervals[i]!.end = Math.max(now, turn.toolIntervals[i]!.start)
+      return
+    }
+  }
+}
+
+/**
+ * Milliseconds of tool execution overlapping [from, to], unioned so parallel
+ * tool calls count once. Open spans are clamped at `to`.
+ */
+export function toolOverlapMs(turn: TurnMetrics | undefined, from: number, to: number): number {
+  if (!turn || to <= from) return 0
+  const spans: Array<{ start: number; end: number }> = []
+  for (const interval of turn.toolIntervals) {
+    const start = Math.max(interval.start, from)
+    const end = Math.min(interval.end ?? to, to)
+    if (end > start) spans.push({ start, end })
+  }
+  spans.sort((a, b) => a.start - b.start)
+  let total = 0
+  let cursor: number | null = null
+  let cursorEnd = 0
+  for (const span of spans) {
+    if (cursor === null || span.start > cursorEnd) {
+      if (cursor !== null) total += cursorEnd - cursor
+      cursor = span.start
+      cursorEnd = span.end
+    } else if (span.end > cursorEnd) {
+      cursorEnd = span.end
+    }
+  }
+  if (cursor !== null) total += cursorEnd - cursor
+  return total
+}
+
 /**
  * Turn-level TTFT (user message → first token), gated. Falls back to the
  * supplied per-request TTFT when the turn has no first-token timing. This is

package/src/types.ts

@@ -34,6 +34,12 @@ export interface FinalizedStepUsage {
   exact: boolean
 }
 
+export interface ToolInterval {
+  readonly id: string
+  readonly start: number
+  end: number | null                   // null = still running
+}
+
 export interface TurnMetrics {
   sessionID: string
   turnStartTime: number
@@ -46,6 +52,7 @@ export interface TurnMetrics {
   hasStickyContextTokens: boolean
   stickyCacheReadTokens: number
   hasStickyCacheReadTokens: boolean
+  toolIntervals: ToolInterval[]         // Tool execution spans (V2 tool.* events; empty on V1)
   isComplete: boolean
 }