opencode2-tps 0.1.1 → 0.2.0-rc.1

package/README.md

@@ -16,7 +16,7 @@ When the run ends, the number freezes at the run average and stays there until t
 
 ## Install
 
-Built against the OpenCode 2 preview. The earliest known compatible beta is `0.0.0-beta-17595`; the latest tested beta is `0.0.0-beta-17595`. The TUI plugin API is still moving, so a much newer or older build may drop the indicator without an error: a renamed event stops arriving, and an unknown composer slot gets quietly rerouted. If the figure never appears, check your CLI version first.
+Built against the OpenCode 2 preview. The earliest known compatible beta is `0.0.0-beta-17595`; the latest tested beta is `0.0.0-beta-17639`. The TUI plugin API is still moving, so a much newer or older build may drop the indicator without an error: a renamed event stops arriving, and an unknown composer slot gets quietly rerouted. If the figure never appears, check your CLI version first.
 
 Add the package to `~/.config/opencode/cli.json`:
 
@@ -69,9 +69,9 @@ The defaults are usable as they are. For the full option list, the ranges and mo
 
 ## How it works
 
-The plugin counts the output bytes of a run and estimates tokens from the byte total. It also accumulates the run's active time, capping each gap between two outputs, so time spent in a tool call is not charged to the model's rate.
+The plugin counts the output bytes of a run and estimates tokens from the byte total. When the host reports the session's real token counts, the plugin measures its own bytes-per-token ratio for that session and switches to it — until then it assumes 4.75 bytes per token. TPS is the run's estimated tokens divided by active model-generation time: timing starts at each step's first output and continues without pause for provider stalls, while tool-execution intervals and time between model steps are excluded.
 
-The live figure comes from a rolling window over recent output. When that window holds nothing recent, the indicator falls back to the average of the run so far.
+The measured ratio depends on the model and is calibrated once per session. Changing models mid-session can therefore make the token and t/s estimates inaccurate; start a new session after switching models for a fresh calibration. This also avoids the prompt-cache disruption associated with changing models in existing sessions.
 
 For more detail, see [Architecture](docs/development.md#architecture).
 

package/dist/tui.js

@@ -87,19 +87,22 @@ function mark(line) {
 // ---------------------------------------------------------------------------
 // tuning
 
-const BYTES_PER_TOKEN = 5;
 export const DEFAULT_CONFIG = {
-  sampleWindowMs: 5_000,
-  liveStaleMs: 1_500,
-  singleSampleMinMs: 250,
-  singleSampleMaxMs: 1_000,
-  tailMaxMs: 1_000,
-  gapCapMs: 2_000
+  bytesPerToken: 4.75
 };
 // The frozen final average stays visible until the next prompt starts a new run.
 
-function estimateTokens(bytes) {
-  return Math.ceil(bytes / BYTES_PER_TOKEN);
+// Step completion events carry the generated-token count for that model call.
+// Pairing it with deltas from the same assistant message avoids contamination
+// from concurrent title generation and other session-level usage updates.
+export const CALIBRATION_MIN_BYTES = 2_048;
+export const CALIBRATION_MIN_TOKENS = 50;
+// Bounds shared by the option clamp and the calibration sanity check: a ratio
+// outside them means the report does not describe the bytes the plugin watched.
+const BYTES_PER_TOKEN_MIN = 1;
+const BYTES_PER_TOKEN_MAX = 16;
+function estimateTokens(bytes, bytesPerToken) {
+  return Math.ceil(bytes / bytesPerToken);
 }
 function formatTps(value) {
   if (value < 10) return value.toFixed(2);
@@ -120,6 +123,10 @@ export class TpsTracker {
   // Insertion order is kept equal to run-start recency (see beginRun), which is
   // what makes eviction from the front drop the stalest session.
   runs = new Map();
+  // Calibrated bytes/token and the currently observed model step. Both share
+  // the bounded lifecycle of `runs`.
+  ratios = new Map();
+  calibrationSteps = new Map();
   constructor(config = DEFAULT_CONFIG) {
     this.config = config;
   }
@@ -128,10 +135,13 @@ export class TpsTracker {
     if (!st) {
       st = {
         phase: "ended",
-        samples: [],
         bytes: 0,
         activeMs: 0,
+        activeAssistantMessageID: null,
         lastSampleAt: null,
+        activeTools: new Set(),
+        toolPauseStartedAt: null,
+        toolPausedMs: 0,
         frozen: null
       };
       this.runs.set(sessionID, st);
@@ -140,11 +150,15 @@ export class TpsTracker {
   }
   beginRun(sessionID) {
     const st = this.state(sessionID);
+    this.calibrationSteps.delete(sessionID);
     st.phase = "running";
-    st.samples = [];
     st.bytes = 0;
     st.activeMs = 0;
+    st.activeAssistantMessageID = null;
     st.lastSampleAt = null;
+    st.activeTools.clear();
+    st.toolPauseStartedAt = null;
+    st.toolPausedMs = 0;
     st.frozen = null;
     // Re-insert so this session becomes the newest in iteration order. Every
     // entry is created through here, so the cap is checked on the one path that
@@ -158,10 +172,18 @@ export class TpsTracker {
     for (const [sessionID, st] of this.runs) {
       if (this.runs.size <= MAX_TRACKED_RUNS) return;
       if (st.phase === "running") continue;
-      this.runs.delete(sessionID);
+      this.dropSession(sessionID);
     }
   }
-  push(sessionID, delta, now) {
+  advanceTiming(st, now) {
+    if (st.lastSampleAt === null) return;
+    const currentPause = st.toolPauseStartedAt === null ? 0 : Math.max(0, now - st.toolPauseStartedAt);
+    st.activeMs += Math.max(0, now - st.lastSampleAt - st.toolPausedMs - currentPause);
+    st.lastSampleAt = now;
+    st.toolPausedMs = 0;
+    if (st.toolPauseStartedAt !== null) st.toolPauseStartedAt = now;
+  }
+  push(sessionID, delta, now, assistantMessageID) {
     if (!delta) return;
     const st = this.state(sessionID);
     if (st.phase !== "running") this.beginRun(sessionID); // execution.started missed
@@ -169,72 +191,124 @@ export class TpsTracker {
     // Bytes accumulate; tokens are derived from the run total, so providers
     // that emit 1-3 byte deltas are not rounded up on every single one.
     const bytes = Buffer.byteLength(delta, "utf8");
-    st.samples.push({
-      bytes,
-      timestamp: now
-    });
     st.bytes += bytes;
-    // The first sample of a run contributes no elapsed time; the floor is
-    // applied once, where the average is computed.
-    if (st.lastSampleAt !== null) st.activeMs += Math.min(Math.max(0, now - st.lastSampleAt), this.config.gapCapMs);
-    st.lastSampleAt = now;
+    const calibration = this.calibrationSteps.get(sessionID);
+    if (calibration && calibration.assistantMessageID === assistantMessageID) calibration.bytes += bytes;
+    const stepID = assistantMessageID ?? "";
+    if (st.activeAssistantMessageID !== stepID) {
+      st.activeAssistantMessageID = stepID;
+      st.lastSampleAt = null;
+      st.activeTools.clear();
+      st.toolPauseStartedAt = null;
+      st.toolPausedMs = 0;
+    }
+    if (st.lastSampleAt === null) {
+      st.lastSampleAt = now;
+      if (st.activeTools.size > 0) st.toolPauseStartedAt = now;
+    } else {
+      this.advanceTiming(st, now);
+    }
+  }
+
+  /** Start observing one model step for a possible one-shot calibration. */
+  beginStep(sessionID, assistantMessageID) {
+    const st = this.runs.get(sessionID);
+    if (!st || st.phase !== "running") this.beginRun(sessionID);
+    const running = this.runs.get(sessionID);
+    if (running) {
+      running.activeAssistantMessageID = assistantMessageID;
+      running.lastSampleAt = null;
+      running.activeTools.clear();
+      running.toolPauseStartedAt = null;
+      running.toolPausedMs = 0;
+    }
+    if (this.ratios.has(sessionID)) return;
+    this.calibrationSteps.set(sessionID, {
+      assistantMessageID,
+      bytes: 0
+    });
+  }
+
+  /** Pair a completed step's usage with deltas from that assistant message. */
+  finishStep(sessionID, assistantMessageID, generatedTokens, now) {
+    const st = this.runs.get(sessionID);
+    if (st?.activeAssistantMessageID === assistantMessageID) {
+      this.advanceTiming(st, now);
+      st.activeAssistantMessageID = null;
+      st.lastSampleAt = null;
+      st.activeTools.clear();
+      st.toolPauseStartedAt = null;
+      st.toolPausedMs = 0;
+    }
+    const calibration = this.calibrationSteps.get(sessionID);
+    if (!calibration || calibration.assistantMessageID !== assistantMessageID) return;
+    this.calibrationSteps.delete(sessionID);
+    if (this.ratios.has(sessionID)) return;
+    if (generatedTokens === undefined || !Number.isFinite(generatedTokens) || generatedTokens < CALIBRATION_MIN_TOKENS) return;
+    const bytes = calibration.bytes;
+    if (bytes < CALIBRATION_MIN_BYTES) return;
+    const ratio = bytes / generatedTokens;
+    if (ratio < BYTES_PER_TOKEN_MIN || ratio > BYTES_PER_TOKEN_MAX) {
+      mark(`calibration rejected sid=${sessionID} bytes=${bytes} tokens=${generatedTokens} ratio=${ratio.toFixed(2)}`);
+      return;
+    }
+    this.ratios.set(sessionID, ratio);
+    mark(`calibrated sid=${sessionID} bytes=${bytes} tokens=${generatedTokens} ratio=${ratio.toFixed(2)}`);
+  }
+  beginTool(sessionID, assistantMessageID, toolID, now) {
+    const st = this.runs.get(sessionID);
+    if (!st || st.activeAssistantMessageID !== assistantMessageID || st.activeTools.has(toolID)) return;
+    if (st.activeTools.size === 0 && st.lastSampleAt !== null) st.toolPauseStartedAt = now;
+    st.activeTools.add(toolID);
+  }
+  finishTool(sessionID, assistantMessageID, toolID, now) {
+    const st = this.runs.get(sessionID);
+    if (st?.activeAssistantMessageID !== assistantMessageID || !st.activeTools.delete(toolID) || st.activeTools.size > 0) return;
+    if (st.toolPauseStartedAt !== null) st.toolPausedMs += Math.max(0, now - st.toolPauseStartedAt);
+    st.toolPauseStartedAt = null;
+  }
+
+  /** The session's calibrated ratio, or the configured fallback. */
+  ratioFor(sessionID) {
+    return this.ratios.get(sessionID) ?? this.config.bytesPerToken;
   }
   finish(sessionID, now) {
     const st = this.runs.get(sessionID);
     if (!st || st.phase === "ended") return;
+    this.calibrationSteps.delete(sessionID);
     st.phase = "ended";
-    if (st.lastSampleAt !== null) {
-      st.activeMs += Math.min(Math.max(0, now - st.lastSampleAt), this.config.tailMaxMs);
-      st.lastSampleAt = null;
-    }
-    const tokens = estimateTokens(st.bytes);
+    this.advanceTiming(st, now);
+    st.lastSampleAt = null;
+    st.activeAssistantMessageID = null;
+    st.activeTools.clear();
+    st.toolPauseStartedAt = null;
+    st.toolPausedMs = 0;
+    const tokens = estimateTokens(st.bytes, this.ratioFor(sessionID));
     if (tokens <= 0) {
-      this.runs.delete(sessionID);
+      this.evictStale();
       return;
     }
-    const seconds = Math.max(st.activeMs, this.config.singleSampleMinMs) / 1000;
+    const seconds = Math.max(st.activeMs, 1) / 1000;
     st.frozen = {
       tps: tokens / seconds,
       tokens
     };
-    st.samples = [];
     mark(`finish sid=${sessionID} tokens=${tokens} activeMs=${st.activeMs} tps=${st.frozen.tps.toFixed(1)}`);
+    this.evictStale();
   }
-  evict(sessionID) {
+  dropSession(sessionID) {
     this.runs.delete(sessionID);
+    this.ratios.delete(sessionID);
+    this.calibrationSteps.delete(sessionID);
   }
-  hasRunning() {
-    for (const st of this.runs.values()) if (st.phase === "running") return true;
-    return false;
+  evict(sessionID) {
+    this.dropSession(sessionID);
   }
-
-  // Throughput over the rolling window, or -1 when the window holds nothing
-  // recent enough to be called "live".
-  live(st, now) {
-    const cutoff = now - this.config.sampleWindowMs;
-    const active = st.samples.filter(s => s.timestamp >= cutoff);
-    const last = active.at(-1);
-    const first = active[0];
-    if (!last || !first || now - last.timestamp > this.config.liveStaleMs) return -1;
-    let bytes = 0;
-    for (const s of active) bytes += s.bytes;
-    const tokens = bytes / BYTES_PER_TOKEN;
-    let durationMs;
-    if (active.length < 2) {
-      durationMs = Math.max(this.config.singleSampleMinMs, Math.min(now - first.timestamp, this.config.singleSampleMaxMs));
-    } else {
-      // Gaps are capped exactly as in push(): a pause for tool execution must
-      // not be charged to the model's throughput.
-      let gaps = 0;
-      let prev = first.timestamp;
-      for (const s of active) {
-        gaps += Math.min(Math.max(0, s.timestamp - prev), this.config.gapCapMs);
-        prev = s.timestamp;
-      }
-      gaps += Math.min(now - last.timestamp, this.config.tailMaxMs);
-      durationMs = Math.max(gaps, this.config.singleSampleMinMs);
+  hasRunning() {
+    for (const st of this.runs.values()) {
+      if (st.phase === "running" && st.activeAssistantMessageID !== null && st.lastSampleAt !== null) return true;
     }
-    return tokens / durationMs * 1000;
+    return false;
   }
   value(sessionID, now) {
     const st = this.runs.get(sessionID);
@@ -245,34 +319,17 @@ export class TpsTracker {
       frozen: true
     };
     if (st.phase !== "running") return null;
-    const tokens = estimateTokens(st.bytes);
+    const tokens = estimateTokens(st.bytes, this.ratioFor(sessionID));
     if (tokens <= 0) return null;
-    const live = this.live(st, now);
-    if (live >= 0) return {
-      tps: live,
-      tokens,
-      frozen: false
-    };
-    // Live window empty (long tool call, sub-agent turn): keep showing the
-    // run-so-far average instead of blanking. It uses the same elapsed-time
-    // formula finish() will use, so freezing does not make the number jump.
-    const tail = st.lastSampleAt === null ? 0 : Math.min(Math.max(0, now - st.lastSampleAt), this.config.tailMaxMs);
-    const seconds = Math.max(st.activeMs + tail, this.config.singleSampleMinMs) / 1000;
+    const currentPause = st.toolPauseStartedAt === null ? 0 : Math.max(0, now - st.toolPauseStartedAt);
+    const activeTail = st.lastSampleAt === null ? 0 : Math.max(0, now - st.lastSampleAt - st.toolPausedMs - currentPause);
+    const seconds = Math.max(st.activeMs + activeTail, 1) / 1000;
     return {
       tps: tokens / seconds,
       tokens,
       frozen: false
     };
   }
-  prune(now) {
-    const cutoff = now - this.config.sampleWindowMs;
-    for (const st of this.runs.values()) {
-      // Finished runs keep their frozen average until the next run replaces
-      // them, so only the live sample window needs trimming.
-      const oldest = st.samples[0];
-      if (oldest && oldest.timestamp < cutoff) st.samples = st.samples.filter(s => s.timestamp >= cutoff);
-    }
-  }
 }
 
 // ---------------------------------------------------------------------------
@@ -308,17 +365,10 @@ function clampNumber(value, fallback, min, max) {
   return Math.min(Math.max(value, min), max);
 }
 export function resolveOptions(raw) {
-  const singleSampleMinMs = clampNumber(raw.singleSampleMinMs, DEFAULT_OPTIONS.singleSampleMinMs, 50, 5_000);
   return {
     display: isDisplayMode(raw.display) ? raw.display : DEFAULT_OPTIONS.display,
     refreshHz: clampNumber(raw.refreshHz, DEFAULT_OPTIONS.refreshHz, 1, 60),
-    sampleWindowMs: clampNumber(raw.sampleWindowMs, DEFAULT_OPTIONS.sampleWindowMs, 1_000, 60_000),
-    liveStaleMs: clampNumber(raw.liveStaleMs, DEFAULT_OPTIONS.liveStaleMs, 250, 30_000),
-    singleSampleMinMs,
-    // The ceiling can never sit below the floor, whatever the user wrote.
-    singleSampleMaxMs: Math.max(singleSampleMinMs, clampNumber(raw.singleSampleMaxMs, DEFAULT_OPTIONS.singleSampleMaxMs, 50, 10_000)),
-    tailMaxMs: clampNumber(raw.tailMaxMs, DEFAULT_OPTIONS.tailMaxMs, 0, 10_000),
-    gapCapMs: clampNumber(raw.gapCapMs, DEFAULT_OPTIONS.gapCapMs, 100, 30_000),
+    bytesPerToken: clampNumber(raw.bytesPerToken, DEFAULT_OPTIONS.bytesPerToken, BYTES_PER_TOKEN_MIN, BYTES_PER_TOKEN_MAX),
     debug: raw.debug === true
   };
 }
@@ -370,11 +420,9 @@ const definition = {
         stopTimer();
         return;
       }
-      const now = Date.now();
-      tracker.prune(now);
       const running = tracker.hasRunning();
-      // While running, the label is a function of `now` (window ageing, tail
-      // gap), so it is republished every tick regardless of new deltas.
+      // While a model step is running, elapsed generation time changes even
+      // without new deltas, so republish every tick to expose provider stalls.
       if (dirty || running) {
         dirty = false;
         setVersion(v => v + 1);
@@ -394,7 +442,7 @@ const definition = {
     };
     const onDelta = e => {
       if (!isActive()) return;
-      tracker.push(e.data.sessionID, e.data.delta, Date.now());
+      tracker.push(e.data.sessionID, e.data.delta, Date.now(), e.data.assistantMessageID);
       touch();
     };
     const onFinish = e => {
@@ -402,6 +450,24 @@ const definition = {
       tracker.finish(e.data.sessionID, Date.now());
       touch();
     };
+    const onStepStarted = e => {
+      if (!isActive()) return;
+      tracker.beginStep(e.data.sessionID, e.data.assistantMessageID);
+    };
+    const onStepFinished = e => {
+      if (!isActive()) return;
+      const tokens = e.data.tokens;
+      tracker.finishStep(e.data.sessionID, e.data.assistantMessageID, tokens === undefined ? undefined : tokens.output + tokens.reasoning, Date.now());
+      touch();
+    };
+    const onToolStarted = e => {
+      if (!isActive()) return;
+      tracker.beginTool(e.data.sessionID, e.data.assistantMessageID, e.data.id, Date.now());
+    };
+    const onToolFinished = e => {
+      if (!isActive()) return;
+      tracker.finishTool(e.data.sessionID, e.data.assistantMessageID, e.data.id, Date.now());
+    };
     const unsubs = [ctx.data.on("session.execution.started", e => {
       if (!isActive()) return;
       tracker.beginRun(e.data.sessionID);
@@ -409,7 +475,7 @@ const definition = {
     }), ctx.data.on("session.text.delta", onDelta), ctx.data.on("session.reasoning.delta", onDelta),
     // Tool arguments are model output too: without this the indicator blanks
     // partway through every large write/edit while generation is at full rate.
-    ctx.data.on("session.tool.input.delta", onDelta), ctx.data.on("session.execution.succeeded", onFinish), ctx.data.on("session.execution.failed", onFinish), ctx.data.on("session.execution.interrupted", onFinish), ctx.data.on("session.idle", onFinish), ctx.data.on("session.deleted", e => {
+    ctx.data.on("session.tool.input.delta", onDelta), ctx.data.on("session.step.started", onStepStarted), ctx.data.on("session.step.ended", onStepFinished), ctx.data.on("session.step.failed", onStepFinished), ctx.data.on("session.tool.called", onToolStarted), ctx.data.on("session.tool.success", onToolFinished), ctx.data.on("session.tool.failed", onToolFinished), ctx.data.on("session.execution.succeeded", onFinish), ctx.data.on("session.execution.failed", onFinish), ctx.data.on("session.execution.interrupted", onFinish), ctx.data.on("session.idle", onFinish), ctx.data.on("session.deleted", e => {
       if (!isActive()) return;
       tracker.evict(e.data.sessionID);
       touch();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode2-tps",
-  "version": "0.1.1",
+  "version": "0.2.0-rc.1",
   "description": "Live token-throughput indicator for the OpenCode 2 TUI prompt composer",
   "license": "MIT",
   "author": "P-Theo",
@@ -28,7 +28,7 @@
     "dist"
   ],
   "peerDependencies": {
-    "@opentui/solid": ">=0.5.3",
+    "@opentui/solid": ">=0.5.4",
     "solid-js": "^1.9.0"
   },
   "peerDependenciesMeta": {
@@ -47,11 +47,11 @@
   "devDependencies": {
     "@babel/core": "^7.29.7",
     "@babel/preset-typescript": "^7.29.7",
-    "@opencode-ai/cli": "0.0.0-beta-17595",
-    "@opencode-ai/plugin": "0.0.0-beta-17595",
-    "@opencode-ai/theme": "0.0.0-beta-17595",
-    "@opentui/core": "^0.5.3",
-    "@opentui/solid": "^0.5.3",
+    "@opencode-ai/cli": "0.0.0-beta-17639",
+    "@opencode-ai/plugin": "0.0.0-beta-17639",
+    "@opencode-ai/theme": "0.0.0-beta-17639",
+    "@opentui/core": "^0.5.4",
+    "@opentui/solid": "^0.5.4",
     "@oxlint/plugins": "^1.78.0",
     "@types/bun": "^1.3.14",
     "@types/node": "^24.0.0",