opencode2-tps 0.3.0 → 0.4.0-rc.1

package/README.md

@@ -12,7 +12,7 @@ When OpenCode reports terminal usage, the token count becomes exact while TPS re
 
 ## 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-19381`. The TUI plugin API is still moving, so a much newer or older build may drop the indicator without an error. If the figure never appears, check your version first.
+Built against the OpenCode 2 preview. The earliest known compatible 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. If the figure never appears, check your version first, then [open an issue](https://github.com/P-Theo/opencode2-tps/issues).
 
 Install it with the CLI's plugin command, which adds the entry to `~/.config/opencode/cli.json` for you:
 
@@ -43,15 +43,15 @@ To set options, use the object form:
 
 A running TUI picks up `cli.json` changes immediately. On first use it installs the package into its own cache under `~/.cache/opencode/npm/` on Linux — one millisecond-timestamped generation per spec, for example `opencode2-tps@latest/<generation>/`, with the newest generation winning.
 
-The host reuses the newest installed generation without contacting the registry, so a restart alone may not pick up a new release. To upgrade, delete the spec's cache directory and restart:
+The host reuses the newest installed generation without contacting the registry, so a restart alone may not pick up a new release. Delete the spec's cache directory and restart to upgrade:
 
 ```sh
 rm -rf ~/.cache/opencode/npm/opencode2-tps@latest
 ```
 
-To pin a version instead, put the range in the entry — `"opencode2-tps@0.1.0"`. Every distinct entry gets its own cache directory.
+Put the range in the entry to pin a version instead — `"opencode2-tps@0.1.0"`. Every distinct entry gets its own cache directory.
 
-The plugin ID is `opencode2.tps`. To switch it off without losing the entry and its options, add `"-opencode2.tps"` after it:
+The plugin ID is `opencode2.tps`. Add `"-opencode2.tps"` after it to switch it off without losing the entry and its options:
 
 ```json
 {
@@ -71,9 +71,9 @@ The defaults are usable as they are. For the full option list, the ranges and mo
 
 ## How it works
 
-While output streams, the plugin estimates tokens from observable UTF-8 bytes at a default of 4.75 bytes per token and calculates a bounded rolling delivery rate. Complete text, reasoning, and tool-input events reconcile buffered or missed deltas without creating artificial live-rate spikes.
+The plugin estimates tokens from observable UTF-8 bytes at a default of 4.75 bytes per token and calculates a bounded rolling delivery rate while output streams. Complete text, reasoning, and tool-input events reconcile buffered or missed deltas without creating artificial live-rate spikes.
 
-At the end of each model step, OpenCode's reported output and reasoning usage replaces the byte estimate. Settled TPS divides those exact tokens by observed step spans ending at `session.step.streamed`, the host's authoritative end of the model stream, published before local tools join. Hosts that do not publish the event fall back to the final model-content boundary. Either way, local tool execution and time between model calls are excluded.
+OpenCode's reported output and reasoning usage replaces the byte estimate at the end of each model step. Settled TPS divides those exact tokens by observed step spans ending at `session.step.streamed`, the host's authoritative end of the model stream, published before local tools join. Hosts that do not publish the event fall back to the final model-content boundary. Either way, local tool execution and time between model calls are excluded.
 
 OpenCode's built-in assistant-footer t/s divides visible output tokens by the same step spans, leaving hidden reasoning out of its numerator. This plugin counts output plus reasoning, so on reasoning models its settled figure reads higher than the built-in one — those tokens were generated too.
 
@@ -85,7 +85,7 @@ For more detail, see [Architecture](docs/development.md#architecture).
 
 Every output event carries the ID of the session that produced it, so each session is measured on its own.
 
-A sub-agent streams under its own child session ID. While it works, the orchestrator's number stops moving and holds the average of the output the orchestrator produced before delegating. Open the sub-agent's session to watch its live throughput.
+A sub-agent streams under its own child session ID. The orchestrator's number stops moving while it works and holds the average of the output the orchestrator produced before delegating. Open the sub-agent's session to watch its live throughput.
 
 <p align="center">
   <img src="docs/screenshots/subagent_tps.png" width="750" alt="Sub-agent session showing its own live throughput indicator" />

package/dist/debug.js

@@ -0,0 +1,79 @@
+import { appendFileSync, lstatSync, mkdirSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// debug
+//
+// Off unless asked for: an unconfigured install must never touch disk.
+//
+// The log goes inside an owner-only directory instead of straight into the
+// shared temp directory. A guessable path there (the PID is a small, enumerable
+// number) can be pre-created by another local user as a symlink, which
+// appendFileSync would happily follow into a file of their choosing; a
+// world-readable log would also hand them the session IDs it records.
+
+export const DEBUG_DIR_PREFIX = "tps-debug-";
+const debugState = {
+  enabled: false,
+  file: ""
+};
+
+/** True only for a real directory that belongs to us and to no one else. */
+function isOwnPrivateDir(path) {
+  try {
+    const stats = lstatSync(path); // lstat, not stat: a planted symlink must not pass
+
+    if (!stats.isDirectory()) return false;
+    const uid = process.getuid?.();
+
+    // Windows has no uid and a per-user temp directory, so there is nothing to check.
+    if (uid === undefined) return true;
+    return stats.uid === uid && (stats.mode & 0o777) === 0o700;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The 0700 directory to log into. Named after the PID so the process's own hot
+ * reloads keep appending to one file, and only reused when it really is ours —
+ * anything else squatting on the name gets sidestepped via mkdtemp.
+ */
+function debugDir() {
+  const preferred = join(tmpdir(), `${DEBUG_DIR_PREFIX}${process.pid}`);
+  try {
+    mkdirSync(preferred, {
+      mode: 0o700
+    });
+    return preferred;
+  } catch {
+    if (isOwnPrivateDir(preferred)) return preferred;
+    return mkdtempSync(`${preferred}-`);
+  }
+}
+export function configureDebug(enabled) {
+  debugState.enabled = enabled;
+  if (!enabled || debugState.file) return;
+  try {
+    debugState.file = join(debugDir(), "tps.log");
+  } catch {
+    debugState.enabled = false; // no usable temp directory: stay silent
+  }
+}
+
+/** Truthy spellings only: `TPS_DEBUG=0` must not start writing to disk. */
+export function isEnvEnabled(value) {
+  if (value === undefined) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true";
+}
+export function mark(line) {
+  if (!debugState.enabled) return;
+  try {
+    const safeLine = line.replace(/\p{Cc}/gu, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+    appendFileSync(debugState.file, `${new Date().toISOString()} ${safeLine}\n`);
+  } catch {
+    // debug only; never break the host
+  }
+}

package/dist/options.js

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// options
+//
+// `ctx.options` is host-supplied JSON (Record<string, any>), so this is a real
+// parsing boundary: every value is validated and clamped, and anything invalid
+// falls back to the default rather than propagating NaN into the arithmetic.
+// `options.schema.json` documents the same enumerations, defaults, and bounds
+// for editors and agents; `tests/options-schema.test.ts` keeps the two in
+// agreement.
+
+import { BYTES_PER_TOKEN_MAX, BYTES_PER_TOKEN_MIN, DEFAULT_CONFIG, formatTps } from "./tracker.js";
+export const DISPLAY_MODES = ["both", "tokens", "tps"];
+export const REFRESH_HZ_MIN = 1;
+export const REFRESH_HZ_MAX = 60;
+
+/**
+ * A value as it can arrive from `cli.json`: arbitrary JSON, nothing more.
+ * Named so the option boundary has a real input contract to validate against.
+ */
+
+/** The option surface, exactly as documented in the README, before validation. */
+
+export const DEFAULT_OPTIONS = {
+  ...DEFAULT_CONFIG,
+  display: "both",
+  refreshHz: 8,
+  debug: false
+};
+function isFiniteNumber(value) {
+  return Number.isFinite(value);
+}
+function isDisplayMode(value) {
+  return DISPLAY_MODES.some(mode => mode === value);
+}
+function clampNumber(value, fallback, min, max) {
+  if (!isFiniteNumber(value)) return fallback;
+  return Math.min(Math.max(value, min), max);
+}
+export function resolveOptions(raw) {
+  return {
+    display: isDisplayMode(raw.display) ? raw.display : DEFAULT_OPTIONS.display,
+    refreshHz: clampNumber(raw.refreshHz, DEFAULT_OPTIONS.refreshHz, REFRESH_HZ_MIN, REFRESH_HZ_MAX),
+    bytesPerToken: clampNumber(raw.bytesPerToken, DEFAULT_OPTIONS.bytesPerToken, BYTES_PER_TOKEN_MIN, BYTES_PER_TOKEN_MAX),
+    debug: raw.debug === true
+  };
+}
+export function formatLabel(value, display) {
+  const tokens = `${value.tokensEstimated ? "~" : ""}${value.tokens} tok`;
+  const tps = value.tps === null ? null : `~${formatTps(value.tps)} t/s`;
+  if (display === "tokens") return tokens;
+  if (display === "tps") return tps ?? "— t/s";
+  return tps === null ? tokens : `${tokens} · ${tps}`;
+}

package/dist/tracker.js

@@ -0,0 +1,263 @@
+// ---------------------------------------------------------------------------
+// tracker (UI-free)
+//
+// Measures the rate of the observable model stream: bytes to a rolling
+// estimate while output arrives, exact step usage once the host reports it,
+// and a frozen average after the run ends.
+
+import { mark } from "./debug.js";
+export const DEFAULT_CONFIG = {
+  bytesPerToken: 4.75
+};
+// The frozen final average stays visible until the next prompt starts a new run.
+
+export const BYTES_PER_TOKEN_MIN = 1;
+export const BYTES_PER_TOKEN_MAX = 16;
+const LIVE_WINDOW_MS = 5_000;
+const LIVE_STALE_MS = 1_500;
+const LIVE_MIN_DURATION_MS = 250;
+function estimateTokens(bytes, bytesPerToken) {
+  return Math.ceil(bytes / bytesPerToken);
+}
+export function formatTps(value) {
+  if (value < 10) return value.toFixed(2);
+  if (value < 100) return value.toFixed(1);
+  return Math.round(value).toString();
+}
+// A finished run keeps its frozen average indefinitely (it is what the composer
+// still shows), so the map is bounded instead: past this many tracked sessions,
+// the least recently started *finished* runs are dropped. Running ones are never
+// touched. Entries are tiny, so this is hygiene for a long-lived TUI, not a
+// memory fix.
+const MAX_TRACKED_RUNS = 64;
+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();
+  constructor(config = DEFAULT_CONFIG) {
+    this.config = config;
+  }
+  state(sessionID) {
+    let st = this.runs.get(sessionID);
+    if (!st) {
+      st = {
+        phase: "ended",
+        settledTokens: 0,
+        settledDurationMs: 0,
+        tokensEstimated: false,
+        partial: false,
+        activeStep: null,
+        settledSteps: new Set(),
+        frozen: null
+      };
+      this.runs.set(sessionID, st);
+    }
+    return st;
+  }
+  beginRun(sessionID) {
+    const st = this.state(sessionID);
+    st.phase = "running";
+    st.settledTokens = 0;
+    st.settledDurationMs = 0;
+    st.tokensEstimated = false;
+    st.partial = false;
+    st.activeStep = null;
+    st.settledSteps.clear();
+    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
+    // can grow the map.
+    this.runs.delete(sessionID);
+    this.runs.set(sessionID, st);
+    this.evictStale();
+  }
+  evictStale() {
+    if (this.runs.size <= MAX_TRACKED_RUNS) return;
+    for (const [sessionID, st] of this.runs) {
+      if (this.runs.size <= MAX_TRACKED_RUNS) return;
+      if (st.phase === "running") continue;
+      this.dropSession(sessionID);
+    }
+  }
+  ensureStep(sessionID, assistantMessageID, now, replace = false) {
+    const st = this.state(sessionID);
+    if (st.settledSteps.has(assistantMessageID) || st.phase === "ended" && st.frozen !== null) return null;
+    if (st.phase !== "running") this.beginRun(sessionID);
+    const running = this.state(sessionID);
+    if (running.activeStep?.assistantMessageID === assistantMessageID) return running.activeStep;
+    if (running.activeStep && !replace) return null;
+    if (running.activeStep) this.settleActiveStep(running, undefined);
+    const step = {
+      assistantMessageID,
+      startedAt: now,
+      streamedAt: null,
+      lastBoundaryAt: null,
+      observableBytes: 0,
+      blocks: new Map(),
+      samples: []
+    };
+    running.activeStep = step;
+    running.frozen = null;
+    return step;
+  }
+  beginStep(sessionID, assistantMessageID, now = Date.now()) {
+    const st = this.state(sessionID);
+    if (st.phase !== "running") {
+      if (st.settledSteps.has(assistantMessageID)) return;
+      this.beginRun(sessionID);
+    }
+    if (st.activeStep?.assistantMessageID === assistantMessageID) return;
+    this.ensureStep(sessionID, assistantMessageID, now, true);
+  }
+  beginBlock(sessionID, assistantMessageID, blockID, now) {
+    const step = this.ensureStep(sessionID, assistantMessageID, now);
+    if (!step) return;
+    if (!step.blocks.has(blockID)) step.blocks.set(blockID, {
+      streamedBytes: 0,
+      finalBytes: null
+    });
+  }
+  push(sessionID, delta, now, assistantMessageID = "implicit", blockID = "implicit") {
+    if (!delta) return;
+    const step = this.ensureStep(sessionID, assistantMessageID, now);
+    if (!step) return;
+    let block = step.blocks.get(blockID);
+    if (!block) {
+      block = {
+        streamedBytes: 0,
+        finalBytes: null
+      };
+      step.blocks.set(blockID, block);
+    }
+    if (block.finalBytes !== null) return;
+    const bytes = Buffer.byteLength(delta, "utf8");
+    block.streamedBytes += bytes;
+    step.observableBytes += bytes;
+    step.samples.push({
+      bytes,
+      timestamp: now
+    });
+    const oldest = now - LIVE_WINDOW_MS;
+    while (step.samples[0] && step.samples[0].timestamp < oldest) step.samples.shift();
+  }
+  finishBlock(sessionID, assistantMessageID, blockID, text, now) {
+    const st = this.runs.get(sessionID);
+    const step = st?.activeStep;
+    if (!step || step.assistantMessageID !== assistantMessageID) return;
+    let block = step.blocks.get(blockID);
+    if (!block) {
+      block = {
+        streamedBytes: 0,
+        finalBytes: null
+      };
+      step.blocks.set(blockID, block);
+    }
+    if (block.finalBytes !== null) return;
+    block.finalBytes = Buffer.byteLength(text, "utf8");
+    step.observableBytes += block.finalBytes - block.streamedBytes;
+    step.lastBoundaryAt = Math.max(step.lastBoundaryAt ?? now, now);
+  }
+
+  /**
+   * The host's authoritative end of the model stream, published after the
+   * provider stream exits and before local tools join. Assigned rather than
+   * maxed so a retried attempt reusing the message ID moves the boundary to its
+   * own completion.
+   */
+  markStreamed(sessionID, assistantMessageID, now) {
+    const st = this.runs.get(sessionID);
+    const step = st?.activeStep;
+    if (!step || step.assistantMessageID !== assistantMessageID) return;
+    step.streamedAt = now;
+  }
+  settleActiveStep(st, generatedTokens) {
+    const step = st.activeStep;
+    if (!step) return;
+    const exact = generatedTokens !== undefined && Number.isFinite(generatedTokens) && generatedTokens >= 0;
+    st.settledTokens += exact ? generatedTokens : estimateTokens(step.observableBytes, this.config.bytesPerToken);
+    if (!exact) {
+      st.tokensEstimated = true;
+      st.partial = true;
+    }
+
+    // `session.step.streamed` is the exact stream end; the last content boundary
+    // remains the fallback for hosts that do not publish it.
+    const end = step.streamedAt ?? step.lastBoundaryAt;
+    if (end !== null) st.settledDurationMs += Math.max(0, end - step.startedAt);
+    st.settledSteps.add(step.assistantMessageID);
+    st.activeStep = null;
+  }
+  finishStep(sessionID, assistantMessageID, generatedTokens, _now) {
+    const st = this.runs.get(sessionID);
+    if (st?.activeStep?.assistantMessageID !== assistantMessageID) return;
+    this.settleActiveStep(st, generatedTokens);
+  }
+  finish(sessionID, _now) {
+    const st = this.runs.get(sessionID);
+    if (!st || st.phase === "ended") return;
+    if (st.activeStep) this.settleActiveStep(st, undefined);
+    st.phase = "ended";
+    const tokens = st.settledTokens;
+    if (tokens <= 0) {
+      this.evictStale();
+      return;
+    }
+    const tps = st.settledDurationMs > 0 ? tokens / (st.settledDurationMs / 1000) : null;
+    st.frozen = {
+      tps,
+      tokens,
+      tokensEstimated: st.tokensEstimated,
+      partial: st.partial
+    };
+    mark(`finish sid=${sessionID} tokens=${tokens} observedMs=${st.settledDurationMs} tps=${tps?.toFixed(1) ?? "n/a"}`);
+    this.evictStale();
+  }
+  dropSession(sessionID) {
+    this.runs.delete(sessionID);
+  }
+  evict(sessionID) {
+    this.dropSession(sessionID);
+  }
+  hasRunning(now = Date.now()) {
+    for (const st of this.runs.values()) {
+      const last = st.activeStep?.samples.at(-1);
+      if (st.phase === "running" && last && now < last.timestamp + LIVE_STALE_MS) return true;
+    }
+    return false;
+  }
+  liveTps(step, now) {
+    const last = step.samples.at(-1);
+    if (!last) return null;
+    const effectiveNow = Math.min(now, last.timestamp + LIVE_STALE_MS);
+    const oldest = effectiveNow - LIVE_WINDOW_MS;
+    const samples = step.samples.filter(sample => sample.timestamp >= oldest);
+    const first = samples[0];
+    if (!first) return null;
+    const bytes = samples.reduce((total, sample) => total + sample.bytes, 0);
+    const durationMs = Math.max(effectiveNow - first.timestamp, LIVE_MIN_DURATION_MS);
+    return estimateTokens(bytes, this.config.bytesPerToken) / (durationMs / 1000);
+  }
+  value(sessionID, now) {
+    const st = this.runs.get(sessionID);
+    if (!st) return null;
+    if (st.frozen) return {
+      ...st.frozen,
+      frozen: true,
+      tpsEstimated: true
+    };
+    if (st.phase !== "running") return null;
+    const active = st.activeStep;
+    const activeTokens = active ? estimateTokens(active.observableBytes, this.config.bytesPerToken) : 0;
+    const tokens = st.settledTokens + activeTokens;
+    if (tokens <= 0) return null;
+    const settledTps = st.settledDurationMs > 0 ? st.settledTokens / (st.settledDurationMs / 1000) : null;
+    return {
+      tps: active ? this.liveTps(active, now) ?? settledTps : settledTps,
+      tokens,
+      frozen: false,
+      tokensEstimated: st.tokensEstimated || active !== null,
+      tpsEstimated: true,
+      partial: st.partial
+    };
+  }
+}

package/dist/tui.js

@@ -7,393 +7,9 @@ import { createComponent as _$createComponent } from "@opentui/solid";
 /** @jsxImportSource @opentui/solid */
 
 import { createMemo, createSignal, Show } from "solid-js";
-import { appendFileSync, lstatSync, mkdirSync, mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-// ---------------------------------------------------------------------------
-// debug
-//
-// Off unless asked for: an unconfigured install must never touch disk.
-//
-// The log goes inside an owner-only directory instead of straight into the
-// shared temp directory. A guessable path there (the PID is a small, enumerable
-// number) can be pre-created by another local user as a symlink, which
-// appendFileSync would happily follow into a file of their choosing; a
-// world-readable log would also hand them the session IDs it records.
-
-export const DEBUG_DIR_PREFIX = "tps-debug-";
-const debugState = {
-  enabled: false,
-  file: ""
-};
-
-/** True only for a real directory that belongs to us and to no one else. */
-function isOwnPrivateDir(path) {
-  try {
-    const stats = lstatSync(path); // lstat, not stat: a planted symlink must not pass
-    if (!stats.isDirectory()) return false;
-    const uid = process.getuid?.();
-    // Windows has no uid and a per-user temp directory, so there is nothing to check.
-    if (uid === undefined) return true;
-    return stats.uid === uid && (stats.mode & 0o777) === 0o700;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * The 0700 directory to log into. Named after the PID so the process's own hot
- * reloads keep appending to one file, and only reused when it really is ours —
- * anything else squatting on the name gets sidestepped via mkdtemp.
- */
-function debugDir() {
-  const preferred = join(tmpdir(), `${DEBUG_DIR_PREFIX}${process.pid}`);
-  try {
-    mkdirSync(preferred, {
-      mode: 0o700
-    });
-    return preferred;
-  } catch {
-    if (isOwnPrivateDir(preferred)) return preferred;
-    return mkdtempSync(`${preferred}-`);
-  }
-}
-function configureDebug(enabled) {
-  debugState.enabled = enabled;
-  if (!enabled || debugState.file) return;
-  try {
-    debugState.file = join(debugDir(), "tps.log");
-  } catch {
-    debugState.enabled = false; // no usable temp directory: stay silent
-  }
-}
-
-/** Truthy spellings only: `TPS_DEBUG=0` must not start writing to disk. */
-export function isEnvEnabled(value) {
-  if (value === undefined) return false;
-  const normalized = value.trim().toLowerCase();
-  return normalized === "1" || normalized === "true";
-}
-function mark(line) {
-  if (!debugState.enabled) return;
-  try {
-    const safeLine = line.replace(/\p{Cc}/gu, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
-    appendFileSync(debugState.file, `${new Date().toISOString()} ${safeLine}\n`);
-  } catch {
-    // debug only; never break the host
-  }
-}
-
-// ---------------------------------------------------------------------------
-// tuning
-
-export const DEFAULT_CONFIG = {
-  bytesPerToken: 4.75
-};
-// The frozen final average stays visible until the next prompt starts a new run.
-
-const BYTES_PER_TOKEN_MIN = 1;
-const BYTES_PER_TOKEN_MAX = 16;
-const LIVE_WINDOW_MS = 5_000;
-const LIVE_STALE_MS = 1_500;
-const LIVE_MIN_DURATION_MS = 250;
-function estimateTokens(bytes, bytesPerToken) {
-  return Math.ceil(bytes / bytesPerToken);
-}
-function formatTps(value) {
-  if (value < 10) return value.toFixed(2);
-  if (value < 100) return value.toFixed(1);
-  return Math.round(value).toString();
-}
-
-// ---------------------------------------------------------------------------
-// tracker (UI-free)
-
-// A finished run keeps its frozen average indefinitely (it is what the composer
-// still shows), so the map is bounded instead: past this many tracked sessions,
-// the least recently started *finished* runs are dropped. Running ones are never
-// touched. Entries are tiny, so this is hygiene for a long-lived TUI, not a
-// memory fix.
-const MAX_TRACKED_RUNS = 64;
-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();
-  constructor(config = DEFAULT_CONFIG) {
-    this.config = config;
-  }
-  state(sessionID) {
-    let st = this.runs.get(sessionID);
-    if (!st) {
-      st = {
-        phase: "ended",
-        settledTokens: 0,
-        settledDurationMs: 0,
-        tokensEstimated: false,
-        partial: false,
-        activeStep: null,
-        settledSteps: new Set(),
-        frozen: null
-      };
-      this.runs.set(sessionID, st);
-    }
-    return st;
-  }
-  beginRun(sessionID) {
-    const st = this.state(sessionID);
-    st.phase = "running";
-    st.settledTokens = 0;
-    st.settledDurationMs = 0;
-    st.tokensEstimated = false;
-    st.partial = false;
-    st.activeStep = null;
-    st.settledSteps.clear();
-    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
-    // can grow the map.
-    this.runs.delete(sessionID);
-    this.runs.set(sessionID, st);
-    this.evictStale();
-  }
-  evictStale() {
-    if (this.runs.size <= MAX_TRACKED_RUNS) return;
-    for (const [sessionID, st] of this.runs) {
-      if (this.runs.size <= MAX_TRACKED_RUNS) return;
-      if (st.phase === "running") continue;
-      this.dropSession(sessionID);
-    }
-  }
-  ensureStep(sessionID, assistantMessageID, now, replace = false) {
-    const st = this.state(sessionID);
-    if (st.settledSteps.has(assistantMessageID) || st.phase === "ended" && st.frozen !== null) return null;
-    if (st.phase !== "running") this.beginRun(sessionID);
-    const running = this.state(sessionID);
-    if (running.activeStep?.assistantMessageID === assistantMessageID) return running.activeStep;
-    if (running.activeStep && !replace) return null;
-    if (running.activeStep) this.settleActiveStep(running, undefined);
-    const step = {
-      assistantMessageID,
-      startedAt: now,
-      streamedAt: null,
-      lastBoundaryAt: null,
-      observableBytes: 0,
-      blocks: new Map(),
-      samples: []
-    };
-    running.activeStep = step;
-    running.frozen = null;
-    return step;
-  }
-  beginStep(sessionID, assistantMessageID, now = Date.now()) {
-    const st = this.state(sessionID);
-    if (st.phase !== "running") {
-      if (st.settledSteps.has(assistantMessageID)) return;
-      this.beginRun(sessionID);
-    }
-    if (st.activeStep?.assistantMessageID === assistantMessageID) return;
-    this.ensureStep(sessionID, assistantMessageID, now, true);
-  }
-  beginBlock(sessionID, assistantMessageID, blockID, now) {
-    const step = this.ensureStep(sessionID, assistantMessageID, now);
-    if (!step) return;
-    if (!step.blocks.has(blockID)) step.blocks.set(blockID, {
-      streamedBytes: 0,
-      finalBytes: null
-    });
-  }
-  push(sessionID, delta, now, assistantMessageID = "implicit", blockID = "implicit") {
-    if (!delta) return;
-    const step = this.ensureStep(sessionID, assistantMessageID, now);
-    if (!step) return;
-    let block = step.blocks.get(blockID);
-    if (!block) {
-      block = {
-        streamedBytes: 0,
-        finalBytes: null
-      };
-      step.blocks.set(blockID, block);
-    }
-    if (block.finalBytes !== null) return;
-    const bytes = Buffer.byteLength(delta, "utf8");
-    block.streamedBytes += bytes;
-    step.observableBytes += bytes;
-    step.samples.push({
-      bytes,
-      timestamp: now
-    });
-    const oldest = now - LIVE_WINDOW_MS;
-    while (step.samples[0] && step.samples[0].timestamp < oldest) step.samples.shift();
-  }
-  finishBlock(sessionID, assistantMessageID, blockID, text, now) {
-    const st = this.runs.get(sessionID);
-    const step = st?.activeStep;
-    if (!step || step.assistantMessageID !== assistantMessageID) return;
-    let block = step.blocks.get(blockID);
-    if (!block) {
-      block = {
-        streamedBytes: 0,
-        finalBytes: null
-      };
-      step.blocks.set(blockID, block);
-    }
-    if (block.finalBytes !== null) return;
-    block.finalBytes = Buffer.byteLength(text, "utf8");
-    step.observableBytes += block.finalBytes - block.streamedBytes;
-    step.lastBoundaryAt = Math.max(step.lastBoundaryAt ?? now, now);
-  }
-
-  /**
-   * The host's authoritative end of the model stream, published after the
-   * provider stream exits and before local tools join. Assigned rather than
-   * maxed so a retried attempt reusing the message ID moves the boundary to its
-   * own completion.
-   */
-  markStreamed(sessionID, assistantMessageID, now) {
-    const st = this.runs.get(sessionID);
-    const step = st?.activeStep;
-    if (!step || step.assistantMessageID !== assistantMessageID) return;
-    step.streamedAt = now;
-  }
-  settleActiveStep(st, generatedTokens) {
-    const step = st.activeStep;
-    if (!step) return;
-    const exact = generatedTokens !== undefined && Number.isFinite(generatedTokens) && generatedTokens >= 0;
-    st.settledTokens += exact ? generatedTokens : estimateTokens(step.observableBytes, this.config.bytesPerToken);
-    if (!exact) {
-      st.tokensEstimated = true;
-      st.partial = true;
-    }
-    // `session.step.streamed` is the exact stream end; the last content boundary
-    // remains the fallback for hosts that do not publish it.
-    const end = step.streamedAt ?? step.lastBoundaryAt;
-    if (end !== null) st.settledDurationMs += Math.max(0, end - step.startedAt);
-    st.settledSteps.add(step.assistantMessageID);
-    st.activeStep = null;
-  }
-  finishStep(sessionID, assistantMessageID, generatedTokens, _now) {
-    const st = this.runs.get(sessionID);
-    if (st?.activeStep?.assistantMessageID !== assistantMessageID) return;
-    this.settleActiveStep(st, generatedTokens);
-  }
-  finish(sessionID, _now) {
-    const st = this.runs.get(sessionID);
-    if (!st || st.phase === "ended") return;
-    if (st.activeStep) this.settleActiveStep(st, undefined);
-    st.phase = "ended";
-    const tokens = st.settledTokens;
-    if (tokens <= 0) {
-      this.evictStale();
-      return;
-    }
-    const tps = st.settledDurationMs > 0 ? tokens / (st.settledDurationMs / 1000) : null;
-    st.frozen = {
-      tps,
-      tokens,
-      tokensEstimated: st.tokensEstimated,
-      partial: st.partial
-    };
-    mark(`finish sid=${sessionID} tokens=${tokens} observedMs=${st.settledDurationMs} tps=${tps?.toFixed(1) ?? "n/a"}`);
-    this.evictStale();
-  }
-  dropSession(sessionID) {
-    this.runs.delete(sessionID);
-  }
-  evict(sessionID) {
-    this.dropSession(sessionID);
-  }
-  hasRunning(now = Date.now()) {
-    for (const st of this.runs.values()) {
-      const last = st.activeStep?.samples.at(-1);
-      if (st.phase === "running" && last && now < last.timestamp + LIVE_STALE_MS) return true;
-    }
-    return false;
-  }
-  liveTps(step, now) {
-    const last = step.samples.at(-1);
-    if (!last) return null;
-    const effectiveNow = Math.min(now, last.timestamp + LIVE_STALE_MS);
-    const oldest = effectiveNow - LIVE_WINDOW_MS;
-    const samples = step.samples.filter(sample => sample.timestamp >= oldest);
-    const first = samples[0];
-    if (!first) return null;
-    const bytes = samples.reduce((total, sample) => total + sample.bytes, 0);
-    const durationMs = Math.max(effectiveNow - first.timestamp, LIVE_MIN_DURATION_MS);
-    return estimateTokens(bytes, this.config.bytesPerToken) / (durationMs / 1000);
-  }
-  value(sessionID, now) {
-    const st = this.runs.get(sessionID);
-    if (!st) return null;
-    if (st.frozen) return {
-      ...st.frozen,
-      frozen: true,
-      tpsEstimated: true
-    };
-    if (st.phase !== "running") return null;
-    const active = st.activeStep;
-    const activeTokens = active ? estimateTokens(active.observableBytes, this.config.bytesPerToken) : 0;
-    const tokens = st.settledTokens + activeTokens;
-    if (tokens <= 0) return null;
-    const settledTps = st.settledDurationMs > 0 ? st.settledTokens / (st.settledDurationMs / 1000) : null;
-    return {
-      tps: active ? this.liveTps(active, now) ?? settledTps : settledTps,
-      tokens,
-      frozen: false,
-      tokensEstimated: st.tokensEstimated || active !== null,
-      tpsEstimated: true,
-      partial: st.partial
-    };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// options
-//
-// `ctx.options` is host-supplied JSON (Record<string, any>), so this is a real
-// parsing boundary: every value is validated and clamped, and anything invalid
-// falls back to the default rather than propagating NaN into the arithmetic.
-
-const DISPLAY_MODES = ["both", "tokens", "tps"];
-
-/**
- * A value as it can arrive from `cli.json`: arbitrary JSON, nothing more.
- * Named so the option boundary has a real input contract to validate against.
- */
-
-/** The option surface, exactly as documented in the README, before validation. */
-
-export const DEFAULT_OPTIONS = {
-  ...DEFAULT_CONFIG,
-  display: "both",
-  refreshHz: 8,
-  debug: false
-};
-function isFiniteNumber(value) {
-  return Number.isFinite(value);
-}
-function isDisplayMode(value) {
-  return DISPLAY_MODES.some(mode => mode === value);
-}
-function clampNumber(value, fallback, min, max) {
-  if (!isFiniteNumber(value)) return fallback;
-  return Math.min(Math.max(value, min), max);
-}
-export function resolveOptions(raw) {
-  return {
-    display: isDisplayMode(raw.display) ? raw.display : DEFAULT_OPTIONS.display,
-    refreshHz: clampNumber(raw.refreshHz, DEFAULT_OPTIONS.refreshHz, 1, 60),
-    bytesPerToken: clampNumber(raw.bytesPerToken, DEFAULT_OPTIONS.bytesPerToken, BYTES_PER_TOKEN_MIN, BYTES_PER_TOKEN_MAX),
-    debug: raw.debug === true
-  };
-}
-export function formatLabel(value, display) {
-  const tokens = `${value.tokensEstimated ? "~" : ""}${value.tokens} tok`;
-  const tps = value.tps === null ? null : `~${formatTps(value.tps)} t/s`;
-  if (display === "tokens") return tokens;
-  if (display === "tps") return tps ?? "— t/s";
-  return tps === null ? tokens : `${tokens} · ${tps}`;
-}
+import { configureDebug, isEnvEnabled, mark } from "./debug.js";
+import { TpsTracker } from "./tracker.js";
+import { formatLabel, resolveOptions } from "./options.js";
 
 // ---------------------------------------------------------------------------
 // plugin
@@ -452,6 +68,7 @@ const definition = {
         return;
       }
       const running = tracker.hasRunning(Date.now());
+
       // The observable live rate decays only through a short stale tail. Opaque
       // provider work after that is not charged to a numerator we cannot see.
       if (dirty || running) {

package/options.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/P-Theo/opencode2-tps/main/options.schema.json",
+  "title": "opencode2-tps plugin options",
+  "description": "Options for the opencode2-tps OpenCode 2 TUI plugin, as they appear in the plugin entry's `options` object in `~/.config/opencode/cli.json` (or `$XDG_CONFIG_HOME/opencode/cli.json`). The runtime parser is tolerant — an unusable value falls back to the documented default and an out-of-range number is clamped — but agents should write canonical values and validate against this schema. Unknown keys are rejected here on purpose: the runtime ignores them silently, so a typo in an option is otherwise invisible.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "display": {
+      "enum": ["both", "tokens", "tps"],
+      "default": "both",
+      "description": "Which parts of the label to show."
+    },
+    "refreshHz": {
+      "type": "number",
+      "minimum": 1,
+      "maximum": 60,
+      "default": 8,
+      "description": "How often the label updates while a session streams, clamped to 1-60."
+    },
+    "bytesPerToken": {
+      "type": "number",
+      "minimum": 1,
+      "maximum": 16,
+      "default": 4.75,
+      "description": "Bytes per token used for live and partial-output estimates, clamped to 1-16. Completed steps use OpenCode's reported token usage instead."
+    },
+    "debug": {
+      "type": "boolean",
+      "default": false,
+      "description": "Writes a debug log. Only `true` enables it."
+    }
+  },
+  "examples": [
+    {
+      "display": "tps",
+      "refreshHz": 12
+    },
+    {
+      "display": "both",
+      "refreshHz": 8,
+      "bytesPerToken": 4.75,
+      "debug": false
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode2-tps",
-  "version": "0.3.0",
+  "version": "0.4.0-rc.1",
   "description": "Live token-throughput indicator for the OpenCode 2 TUI prompt composer",
   "license": "MIT",
   "author": "P-Theo",
@@ -21,10 +21,12 @@
     "throughput"
   ],
   "exports": {
-    "./tui": "./dist/tui.js"
+    "./tui": "./dist/tui.js",
+    "./options.schema.json": "./options.schema.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "options.schema.json"
   ],
   "peerDependencies": {
     "@opentui/solid": ">=0.5.4",
@@ -53,16 +55,16 @@
     "@opentui/solid": "^0.5.10",
     "@oxlint/plugins": "^1.78.0",
     "@types/bun": "^1.3.14",
-    "@types/node": "^24.0.0",
+    "@types/node": "^26.0.0",
     "babel-preset-solid": "^1.9.12",
     "oxlint": "^1.78.0",
     "solid-js": "^1.9.0",
     "typescript": "^5.9.0"
   },
   "scripts": {
-    "build": "node build.mjs",
+    "build": "node scripts/build.mjs",
     "check": "tsc --noEmit",
-    "check:compatibility": "node check-compatibility.mjs",
+    "check:compatibility": "node scripts/check-compatibility.mjs",
     "lint": "oxlint",
     "test": "bun test",
     "prepack": "npm run lint && npm run check && npm test && npm run build"